diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f6c687d18..f4df415b9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -131,6 +131,19 @@ jobs:
         run: |
           npm run cli:build:prod -- --target=${{ matrix.target }}
 
+      - name: Prepare bundled Pi runtime
+        shell: bash
+        run: |
+          case "${{ matrix.target }}" in
+            aarch64-apple-darwin) platform=darwin; arch=arm64 ;;
+            x86_64-apple-darwin) platform=darwin; arch=x64 ;;
+            *-windows-msvc) platform=win32; arch=x64 ;;
+            *-linux-gnu) platform=linux; arch=x64 ;;
+            *) echo "Unsupported Pi release target: ${{ matrix.target }}" >&2; exit 1 ;;
+          esac
+          node scripts/prepare-pi-bundle.mjs --platform "$platform" --arch "$arch"
+          echo "FLOWIX_PI_TARGET_ARCH=$arch" >> "$GITHUB_ENV"
+
       - name: Import Windows signing certificate for Tauri
         if: matrix.target == 'x86_64-pc-windows-msvc'
         shell: pwsh
diff --git a/CLAUDE.md b/CLAUDE.md
index 8ccafabc6..c817d2458 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,7 +9,7 @@ Flowix 是一款桌面笔记应用（**Tauri 2 + Rust 后端，React 19 + TS + T
 
 ```bash
 export PATH="$HOME/.cargo/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
-npm run tauri:dev        # 推荐：独立 dev bundle ID (com.flowix.app.dev / "Flowix Dev")，可与生产 app 并存
+npm run tauri:dev        # 推荐：独立 dev bundle ID (com.flowix-dev.app / "Flowix Dev")，可与生产 app 并存
 npm run tauri:dev:win    # Windows 开发启动：使用 app/flowix-desktop/tauri.windows.dev.conf.json
 npm run tauri dev        # ⚠️ 走默认 tauri.conf.json，与生产同 bundle ID (com.flowix.app)，已被生产占住时会立刻 exit 0
 npm run dev              # 仅前端 (localhost:1420)
@@ -35,12 +35,12 @@ cargo test --workspace --lib                         # 跑全部
 
 通过差异化 Tauri 配置，让 dev 版与已安装的生产版同时运行：
 
-- **dev**：`npm run tauri:dev` → `app/flowix-desktop/tauri.conf.dev.json` → bundle ID `com.flowix.app.dev` / `Flowix Dev`
+- **dev**：`npm run tauri:dev` → `app/flowix-desktop/tauri.conf.dev.json` → bundle ID `com.flowix-dev.app` / `Flowix Dev`
 - **生产**：`npm run tauri:build:prod` → `tauri.conf.json` + 平台覆盖层 + 签名覆盖层 → 平台专用 `tauri.*.production.local.json` → bundle ID `com.flowix.app` / `Flowix`
 
 `tauri:dev` 通过 `--config` 指向独立配置，**不要**改 `tauri.conf.json` 的 `identifier` / `productName` / `mainBinaryName` / `bundle.macOS.bundleName` —— 这四个字段是生产身份的锚点。`tauri.conf.production.json` 作为覆盖层被 `tauri build --config` 深合并在 `tauri.conf.json` 之上，因此 dev 配置改动不会污染生产链路。
 
-dev 与生产现使用不同 bundle ID（`com.flowix.app.dev` vs `com.flowix.app`），可同时运行且互不冲突（Tauri `app_data_dir` / `tauri-plugin-single-instance` lock 都按 identifier 派生）。代价：dev 首次运行需要重新授予一次 user-selected folder 授权（TCC 按 identifier 记忆授权），prod 已授予的不会带过来。视觉上仍通过 bundle name / 窗口标题区分（`Flowix Dev` vs `Flowix`）。URL scheme `flowix://` 仍共用，让浏览器深链能落到任一已装实例。
+dev 与生产现使用不同 bundle ID（`com.flowix-dev.app` vs `com.flowix.app`），可同时运行且互不冲突（Tauri `app_data_dir` / `tauri-plugin-single-instance` lock 都按 identifier 派生）。代价：dev 首次运行需要重新授予一次 user-selected folder 授权（TCC 按 identifier 记忆授权），prod 已授予的不会带过来。视觉上仍通过 bundle name / 窗口标题区分（`Flowix Dev` vs `Flowix`）。Dev 使用独立 URL scheme `flowix-dev://`，以便浏览器回调明确交给 Dev 实例。
 
 ### macOS 本地生产包 ad-hoc 签名
 
diff --git a/README.md b/README.md
index 3b623c6c8..2e38d5dbe 100644
--- a/README.md
+++ b/README.md
@@ -124,11 +124,21 @@ git clone https://github.com/text2future/flowix.git
 cd flowix
 npm install
 
-npm run tauri dev
-npm run dev
-npm run tauri build
+npm run tauri:dev
+npm run tauri:build:prod
 ```
 
+Run `npm run dev` separately only when you want the Vite frontend without the Tauri desktop backend.
+
+The desktop dev build (`npm run tauri:dev`) connects to `https://cloud.flowix.cc` by default. In Preferences → Development → Environment configuration, choose Staging or Prod; Flowix restarts to apply the change. The saved preference is authoritative and takes precedence over the build default. `--cloud-env=staging|prod` sets that default and is used until a preference is saved. The environments keep separate sign-in credentials and sync databases.
+
+```bash
+npm run tauri:dev -- --cloud-env=staging
+npm run tauri:dev -- --cloud-env=prod
+```
+
+`npm run tauri:dev:pi` and `npm run tauri:dev:win` accept the same option. Production packages built with `npm run tauri:build:prod` always connect to `https://cloud.flowix.cc`, and do not show the environment selector. Running `npm run dev` alone starts only the Vite frontend; it does not start desktop Cloud sync.
+
 The development environment requires Node.js 20+, Rust 1.75+ and Tauri v2; the desktop app supports macOS 14+ and Windows 10+.
 
 ## License
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 9ab913255..b931c389c 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -121,11 +121,21 @@ git clone https://github.com/text2future/flowix.git
 cd flowix
 npm install
 
-npm run tauri dev
-npm run dev
-npm run tauri build
+npm run tauri:dev
+npm run tauri:build:prod
 ```
 
+单独运行 `npm run dev` 只启动 Vite 前端，不会启动 Tauri 桌面后端。
+
+桌面开发版 `npm run tauri:dev` 默认连接 `https://cloud.flowix.cc`。在「偏好设置 → 开发 → 环境配置」中选择 Staging 或 Prod，Flowix 会重启以应用切换。首次启动默认使用 Prod；已保存的界面选择优先于构建默认值；`--cloud-env=staging|prod` 设置默认值，仅在尚未保存界面选择时生效：
+
+```bash
+npm run tauri:dev -- --cloud-env=staging
+npm run tauri:dev -- --cloud-env=prod
+```
+
+`npm run tauri:dev:pi` 和 `npm run tauri:dev:win` 也接受该参数。正式包 `npm run tauri:build:prod` 始终连接 `https://cloud.flowix.cc`，不会显示环境下拉。单独运行 `npm run dev` 只启动 Vite 前端，不会启动桌面端 Cloud 同步。
+
 开发环境要求 Node.js 20+、Rust 1.75+ 与 Tauri v2；桌面应用支持 macOS 14+ 与 Windows 10+。
 
 ## 许可协议
diff --git a/app/Cargo.lock b/app/Cargo.lock
index 738c819b0..bbd1a4c27 100644
--- a/app/Cargo.lock
+++ b/app/Cargo.lock
@@ -1222,7 +1222,7 @@ dependencies = [
 
 [[package]]
 name = "flowix-cli"
-version = "1.5.6"
+version = "1.5.8"
 dependencies = [
  "chrono",
  "clap",
@@ -1242,7 +1242,7 @@ dependencies = [
 
 [[package]]
 name = "flowix-core"
-version = "1.5.6"
+version = "1.5.8"
 dependencies = [
  "chrono",
  "diffy",
@@ -1268,7 +1268,7 @@ dependencies = [
 
 [[package]]
 name = "flowix-desktop"
-version = "1.5.6"
+version = "1.5.8"
 dependencies = [
  "async-trait",
  "base64 0.22.1",
@@ -1287,7 +1287,6 @@ dependencies = [
  "image",
  "libc",
  "machine-uid",
- "mime_guess",
  "minisign-verify",
  "nanoid",
  "notify",
@@ -1330,7 +1329,7 @@ dependencies = [
 
 [[package]]
 name = "flowix-installer-helper"
-version = "1.5.6"
+version = "1.5.8"
 dependencies = [
  "dunce",
  "windows",
@@ -1338,7 +1337,7 @@ dependencies = [
 
 [[package]]
 name = "flowix-plugin-runtime"
-version = "1.5.6"
+version = "1.5.8"
 dependencies = [
  "chrono",
  "flowix-core",
@@ -1353,7 +1352,7 @@ dependencies = [
 
 [[package]]
 name = "flowix-sync"
-version = "1.5.6"
+version = "1.5.8"
 dependencies = [
  "chrono",
  "flowix-core",
@@ -2650,16 +2649,6 @@ version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
 
-[[package]]
-name = "mime_guess"
-version = "2.0.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
-dependencies = [
- "mime",
- "unicase",
-]
-
 [[package]]
 name = "minisign-verify"
 version = "0.2.5"
@@ -5447,12 +5436,6 @@ dependencies = [
  "unic-common",
 ]
 
-[[package]]
-name = "unicase"
-version = "2.10.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "357cc3acc6a036009fd6c973ed009037c732d60d0b4f6c673e9041497482a28f"
-
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
diff --git a/app/Cargo.toml b/app/Cargo.toml
index c2da9dd36..7260c50f6 100644
--- a/app/Cargo.toml
+++ b/app/Cargo.toml
@@ -11,7 +11,7 @@ members = [
 
 # 锁定共用依赖到同一版本 ── 避免 backend / cli 走不一致版本。
 [workspace.package]
-version = "1.5.6"
+version = "1.5.8"
 edition = "2021"
 
 # 锁定共用依赖到同一版本 ── 避免 backend / cli 走不一致版本。
@@ -25,7 +25,6 @@ serde_yaml = "0.9"
 toml = "0.8"
 tauri-plugin-process = "2"
 tauri-plugin-updater = "2"
-tauri-plugin-opener = "2"
 chrono = { version = "0.4", features = ["serde"] }
 dirs = "5.0"
 walkdir = "2.4"
diff --git a/app/flowix-cli/Cargo.toml b/app/flowix-cli/Cargo.toml
index 7b6d20a21..79ebd19c8 100644
--- a/app/flowix-cli/Cargo.toml
+++ b/app/flowix-cli/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "flowix-cli"
-version = "1.5.6"
+version = "1.5.8"
 description = "Flowix 命令行工具 ── 共享同一份 memo_file 存储, 跟桌面端 watcher 双向同步"
 authors = ["Flowix Contributors"]
 edition.workspace = true
diff --git a/app/flowix-cli/src/collection_store.rs b/app/flowix-cli/src/collection_store.rs
index 2b9b3e418..3423ed89a 100644
--- a/app/flowix-cli/src/collection_store.rs
+++ b/app/flowix-cli/src/collection_store.rs
@@ -1,7 +1,7 @@
 //! Read-only collection dataset access shared by the CLI and MCP operation layer.
 use crate::{errors::CliError, store};
 use flowix_core::{
-    collection::{valid_id, CollectionDocument, CollectionPlacement, CollectionType},
+    collection::{display_name_for_path, valid_id, CollectionDocument, CollectionPlacement, CollectionType},
     memo_file::FileManagementPolicy,
 };
 use rusqlite::Connection;
@@ -23,7 +23,7 @@ pub(crate) fn read(
     }
 
     let memo = store::open()?;
-    let notebook = flowix_core::MemoService::new(&memo).resolve_notebook(notebook_key)?;
+    let notebook = store::resolve_notebook_config(&memo, notebook_key)?;
     let root = fs::canonicalize(&notebook.path)?;
     let policy = FileManagementPolicy::from_notebook_root(&root);
     let (path, document) = if let Some(id) = collection_id {
@@ -50,7 +50,7 @@ pub(crate) fn read(
         "collection": {
             "id": document.collection.id,
             "type": document.collection.kind.as_str(),
-            "name": document.collection.name,
+            "name": display_name_for_path(&path, document.collection.placement),
             "revision": document.collection.revision,
             "createdAt": document.collection.created_at,
             "updatedAt": document.collection.updated_at,
diff --git a/app/flowix-cli/src/path_store.rs b/app/flowix-cli/src/path_store.rs
index 6b1616172..b2727455b 100644
--- a/app/flowix-cli/src/path_store.rs
+++ b/app/flowix-cli/src/path_store.rs
@@ -1,6 +1,6 @@
 //! Path-addressed note operations shared by the CLI, MCP and operation API.
 use crate::{errors::CliError, store};
-use flowix_core::{memo_file::NotebookConfig, MemoService, NoteService};
+use flowix_core::{memo_file::NotebookConfig, NoteService};
 use serde_json::{json, Value};
 use std::{io::Read, path::Path};
 
@@ -67,7 +67,7 @@ fn document_json(document: &flowix_core::service::NoteDocument) -> Value {
 
 pub(crate) fn list(notebook_key: &str) -> Result<Value, CliError> {
     let mf = store::open()?;
-    let notebook = MemoService::new(&mf).resolve_notebook(notebook_key)?;
+    let notebook = store::resolve_notebook_config(&mf, notebook_key)?;
     mf.reconcile_note_index_blocking(&notebook.id)?;
     let notes = NoteService::new(&mf).list(&notebook.id)?;
     Ok(json!({"notebookId": notebook.id, "notes": notes}))
@@ -84,7 +84,7 @@ pub(crate) fn create(notebook_key: &str, content: &str) -> Result<Value, CliErro
         return Err(CliError::Usage("create: content is empty".into()));
     }
     let mf = store::open()?;
-    let notebook = MemoService::new(&mf).resolve_notebook(notebook_key)?;
+    let notebook = store::resolve_notebook_config(&mf, notebook_key)?;
     let parent = flowix_core::memo_file::default_create_folder_for_notebook(Path::new(&notebook.path))
         .map_err(CliError::Other)?;
     let document = NoteService::new(&mf).create(
@@ -181,9 +181,9 @@ pub(crate) fn search(
         })
         .transpose()?;
     let mf = store::open()?;
-    let configs = MemoService::new(&mf).list_notebooks()?;
+    let configs = mf.read_notebook_configs()?;
     let selected = if let Some(key) = notebook_filter {
-        vec![MemoService::new(&mf).resolve_notebook(key)?]
+        vec![store::resolve_notebook_config(&mf, key)?]
     } else {
         configs
     };
diff --git a/app/flowix-cli/src/paths.rs b/app/flowix-cli/src/paths.rs
index 3b9fb1a1d..e2d0536f6 100644
--- a/app/flowix-cli/src/paths.rs
+++ b/app/flowix-cli/src/paths.rs
@@ -12,7 +12,7 @@ use std::path::{Path, PathBuf};
 
 use crate::errors::CliError;
 
-/// 用户配置目录名 (~/.<NAME>/ 下放 index.db / boot/preference.json /
+/// 用户配置目录名 (~/.<NAME>/ 下放 db/local.db / boot/preference.json /
 /// agent-config.toml / boot/system.json 等)。
 pub const USER_CONFIG_DIR_NAME: &str = ".flowix";
 
@@ -26,7 +26,7 @@ pub struct Resolved {
     /// 或 `$XDG_DATA_HOME/flowix` (Linux)
     #[allow(dead_code)]
     pub app_data: PathBuf,
-    /// `~/.flowix/`. 笔记本注册表就存在这里 (`<config_dir>/index.db`).
+    /// `~/.flowix/`. 笔记本注册表位于 `<config_dir>/db/local.db`.
     #[allow(dead_code)]
     pub config_dir: PathBuf,
 }
diff --git a/app/flowix-cli/src/store.rs b/app/flowix-cli/src/store.rs
index 4e8794d3b..3a1874802 100644
--- a/app/flowix-cli/src/store.rs
+++ b/app/flowix-cli/src/store.rs
@@ -1,6 +1,9 @@
 //! Notebook configuration shared by the path-addressed CLI and MCP commands.
 use crate::{errors::CliError, fmt, paths};
-use flowix_core::{memo_file::{MemoFile, NotebookConfig}, MemoService, NoteService};
+use flowix_core::{
+    memo_file::{MemoFile, NotebookConfig},
+    NoteService,
+};
 use std::collections::HashMap;
 
 pub fn open() -> Result<MemoFile, CliError> {
@@ -10,12 +13,24 @@ pub fn open() -> Result<MemoFile, CliError> {
 
 pub(crate) fn notebooks_list_data() -> Result<(Vec<NotebookConfig>, Option<String>), CliError> {
     let mf = open()?;
-    let notebooks = MemoService::new(&mf).list_notebooks()?;
+    let notebooks = mf.read_notebook_configs()?;
     let selected = mf.read_selected_notebook_id()?;
     Ok((notebooks, selected))
 }
 
-pub(crate) fn notebook_note_counts(configs: &[NotebookConfig]) -> Result<HashMap<String, usize>, CliError> {
+pub(crate) fn resolve_notebook_config(
+    mf: &MemoFile,
+    key: &str,
+) -> Result<NotebookConfig, CliError> {
+    let configs = mf.read_notebook_configs()?;
+    find_notebook(&configs, key)
+        .cloned()
+        .ok_or_else(|| CliError::NotFound(format!("notebook not found: {key}")))
+}
+
+pub(crate) fn notebook_note_counts(
+    configs: &[NotebookConfig],
+) -> Result<HashMap<String, usize>, CliError> {
     let mf = open()?;
     let mut counts = HashMap::new();
     for config in configs {
@@ -24,20 +39,35 @@ pub(crate) fn notebook_note_counts(configs: &[NotebookConfig]) -> Result<HashMap
         // counts. Stat-based reconcile hashes only changed files, so a fresh
         // index is cheap while the crash window is still covered.
         mf.reconcile_note_index_blocking(&config.id)?;
-        counts.insert(config.id.clone(), NoteService::new(&mf).list(&config.id)?.len());
+        counts.insert(
+            config.id.clone(),
+            NoteService::new(&mf).list(&config.id)?.len(),
+        );
     }
     Ok(counts)
 }
 
-pub(crate) fn notebook_tag_counts(configs: &[NotebookConfig]) -> Result<HashMap<String, usize>, CliError> {
+pub(crate) fn notebook_tag_counts(
+    configs: &[NotebookConfig],
+) -> Result<HashMap<String, usize>, CliError> {
     let mf = open()?;
-    Ok(configs.iter().map(|config| {
-        (config.id.clone(), mf.read_notebook_tag_paths(Some(&config.id)).unwrap_or_default().len())
-    }).collect())
+    Ok(configs
+        .iter()
+        .map(|config| {
+            (
+                config.id.clone(),
+                mf.read_notebook_tag_paths(Some(&config.id))
+                    .unwrap_or_default()
+                    .len(),
+            )
+        })
+        .collect())
 }
 
 pub fn find_notebook<'a>(configs: &'a [NotebookConfig], key: &str) -> Option<&'a NotebookConfig> {
-    configs.iter().find(|config| config.id == key)
+    configs
+        .iter()
+        .find(|config| config.id == key)
         .or_else(|| configs.iter().find(|config| config.name == key))
 }
 
@@ -46,9 +76,14 @@ pub(crate) fn resolve_notebook_key(notebook: Option<&str>) -> Result<String, Cli
         return Ok(value.to_owned());
     }
     let mf = open()?;
-    if let Some(selected) = mf.read_selected_notebook_id()? { return Ok(selected); }
+    if let Some(selected) = mf.read_selected_notebook_id()? {
+        return Ok(selected);
+    }
     let configs = mf.read_notebook_configs()?;
-    configs.iter().find(|config| config.is_default).or_else(|| configs.first())
+    configs
+        .iter()
+        .find(|config| config.is_default)
+        .or_else(|| configs.first())
         .map(|config| config.id.clone())
         .ok_or_else(|| CliError::NotFound("no notebook is configured".into()))
 }
@@ -56,32 +91,51 @@ pub(crate) fn resolve_notebook_key(notebook: Option<&str>) -> Result<String, Cli
 pub(crate) fn notebook_tags(notebook: Option<&str>) -> Result<serde_json::Value, CliError> {
     let key = resolve_notebook_key(notebook)?;
     let mf = open()?;
-    let config = MemoService::new(&mf).resolve_notebook(&key)?;
+    let config = resolve_notebook_config(&mf, &key)?;
     mf.reconcile_note_index_blocking(&config.id)?;
     let tags = mf.read_used_tag_ids_for_notebook_id(Some(&config.id))?;
-    Ok(serde_json::json!({"ok": true, "action": "tags", "notebook": config.name,
-        "notebookId": config.id, "total": tags.len(), "tags": tags}))
+    Ok(
+        serde_json::json!({"ok": true, "action": "tags", "notebook": config.name,
+        "notebookId": config.id, "total": tags.len(), "tags": tags}),
+    )
 }
 
 pub fn cmd_notebooks_json() -> Result<(), CliError> {
     let (configs, selected) = notebooks_list_data()?;
-    fmt::print_notebooks_json(&configs, &notebook_note_counts(&configs)?,
-        &notebook_tag_counts(&configs)?, selected.as_deref());
+    fmt::print_notebooks_json(
+        &configs,
+        &notebook_note_counts(&configs)?,
+        &notebook_tag_counts(&configs)?,
+        selected.as_deref(),
+    );
     Ok(())
 }
 
 pub fn cmd_notebooks() -> Result<(), CliError> {
     let (configs, selected) = notebooks_list_data()?;
-    fmt::print_notebooks(&configs, &notebook_note_counts(&configs)?,
-        &notebook_tag_counts(&configs)?, selected.as_deref());
+    fmt::print_notebooks(
+        &configs,
+        &notebook_note_counts(&configs)?,
+        &notebook_tag_counts(&configs)?,
+        selected.as_deref(),
+    );
     Ok(())
 }
 
 pub fn cmd_tags(notebook: Option<&str>, json: bool) -> Result<(), CliError> {
     let payload = notebook_tags(notebook)?;
-    if json { println!("{}", serde_json::to_string_pretty(&payload).map_err(|error| CliError::Other(error.to_string()))?); }
-    else if let Some(tags) = payload["tags"].as_array() {
-        for tag in tags { if let Some(name) = tag.as_str() { println!("{name}"); } }
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string_pretty(&payload)
+                .map_err(|error| CliError::Other(error.to_string()))?
+        );
+    } else if let Some(tags) = payload["tags"].as_array() {
+        for tag in tags {
+            if let Some(name) = tag.as_str() {
+                println!("{name}");
+            }
+        }
     }
     Ok(())
 }
@@ -90,9 +144,24 @@ pub fn cmd_completion(shell: &str) -> Result<(), CliError> {
     let mut command = crate::cli::cli_command();
     let mut output = std::io::stdout();
     match shell {
-        "bash" => clap_complete::generate(clap_complete::shells::Bash, &mut command, "flowix", &mut output),
-        "zsh" => clap_complete::generate(clap_complete::shells::Zsh, &mut command, "flowix", &mut output),
-        "fish" => clap_complete::generate(clap_complete::shells::Fish, &mut command, "flowix", &mut output),
+        "bash" => clap_complete::generate(
+            clap_complete::shells::Bash,
+            &mut command,
+            "flowix",
+            &mut output,
+        ),
+        "zsh" => clap_complete::generate(
+            clap_complete::shells::Zsh,
+            &mut command,
+            "flowix",
+            &mut output,
+        ),
+        "fish" => clap_complete::generate(
+            clap_complete::shells::Fish,
+            &mut command,
+            "flowix",
+            &mut output,
+        ),
         other => return Err(CliError::Usage(format!("unknown shell: {other}"))),
     }
     Ok(())
diff --git a/app/flowix-core/src/collection.rs b/app/flowix-core/src/collection.rs
index 1401693e1..57feec1e9 100644
--- a/app/flowix-core/src/collection.rs
+++ b/app/flowix-core/src/collection.rs
@@ -43,6 +43,8 @@ pub struct CollectionMetadata {
     pub kind: CollectionType,
     #[serde(default, skip_serializing_if = "is_standalone")]
     pub placement: CollectionPlacement,
+    /// Deprecated compatibility field. Names are derived from the collection path.
+    #[serde(default, skip_serializing)]
     pub name: String,
     pub revision: i64,
     pub created_at: String,
@@ -52,6 +54,24 @@ pub struct CollectionMetadata {
 fn is_standalone(value: &CollectionPlacement) -> bool {
     *value == CollectionPlacement::Standalone
 }
+
+pub fn display_name_for_path(path: &std::path::Path, placement: CollectionPlacement) -> String {
+    let display_path = if placement == CollectionPlacement::Folder {
+        path.parent().unwrap_or(path)
+    } else {
+        path
+    };
+    let filename = display_path.file_name().unwrap_or_default().to_string_lossy();
+    if placement == CollectionPlacement::Folder {
+        return filename.into_owned();
+    }
+    [".index.yaml", ".index.yml", ".table.yaml", ".table.yml", ".lib.yaml", ".lib.yml"]
+        .iter()
+        .find_map(|suffix| filename.get(..filename.len().checked_sub(suffix.len())?)
+            .filter(|_| filename.to_ascii_lowercase().ends_with(suffix)))
+        .unwrap_or(&filename)
+        .to_owned()
+}
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct CollectionDocument {
@@ -115,8 +135,6 @@ impl CollectionDocument {
         if self.format != "flowix.collection"
             || self.schema_version < 1
             || !valid_id(&metadata.id, "col_")
-            || metadata.name.trim().is_empty()
-            || metadata.name != metadata.name.trim()
             || !(0..=9_007_199_254_740_991).contains(&metadata.revision)
             || chrono::DateTime::parse_from_rfc3339(&metadata.created_at).is_err()
             || chrono::DateTime::parse_from_rfc3339(&metadata.updated_at).is_err()
@@ -244,6 +262,55 @@ impl CollectionDocument {
         Ok(())
     }
 
+    /// Set media resource references to the canonical notebook-and-path ID.
+    /// Collection row IDs remain collection-local record identities.
+    pub fn normalize_media_resource_ids(&mut self, notebook_id: &str) -> Result<bool, String> {
+        if self.collection.kind != CollectionType::MediaLibrary {
+            return Ok(false);
+        }
+        let Some(records) = self
+            .payload
+            .get_mut("dataset")
+            .and_then(|dataset| dataset.get_mut("records"))
+        else {
+            return Err("INVALID_MEDIA_LIBRARY_RECORDS".into());
+        };
+        let mut changed = false;
+        for key in ["include", "exclude"] {
+            let entries = records
+                .get_mut(key)
+                .and_then(Value::as_array_mut)
+                .ok_or("INVALID_MEDIA_LIBRARY_RECORDS")?;
+            for record in entries {
+                let path = record
+                    .get("relative_path")
+                    .and_then(Value::as_str)
+                    .ok_or("INVALID_MEDIA_LIBRARY_PATH")?;
+                let id = crate::memo_file::media_resource_id(notebook_id, path)
+                    .map_err(|error| error.to_string())?;
+                if record.get("resource_id").and_then(Value::as_str) != Some(id.as_str()) {
+                    record["resource_id"] = Value::String(id);
+                    changed = true;
+                }
+            }
+        }
+        Ok(changed)
+    }
+
+    /// Rebase file references and update media resource identities in one edit.
+    pub fn rebase_paths_for_notebook(
+        &mut self,
+        notebook_id: &str,
+        previous: &str,
+        next: &str,
+    ) -> Result<bool, String> {
+        let changed = self.rebase_paths(previous, next);
+        if changed {
+            self.normalize_media_resource_ids(notebook_id)?;
+        }
+        Ok(changed)
+    }
+
     /// Rebase notebook-relative references after a confirmed file or directory move.
     /// The caller owns revision updates and persistence.
     pub fn rebase_paths(&mut self, previous: &str, next: &str) -> bool {
@@ -304,7 +371,15 @@ impl CollectionDocument {
                 changed = true;
             }
         }
-        if let Some(filter) = dataset.get_mut("filter") { changed |= rules(filter, previous, next); }
+        if let Some(filter) = dataset.get_mut("filter") {
+            if let Some(path) = filter.get("path").and_then(Value::as_str) {
+                if let Some(path) = rebase(path, previous, next) {
+                    filter["path"] = Value::String(path);
+                    changed = true;
+                }
+            }
+            changed |= rules(filter, previous, next);
+        }
         if let Some(views) = self.payload.get_mut("views").and_then(|views| views.get_mut("items")).and_then(Value::as_array_mut) {
             for view in views {
                 if let Some(filter) = view.get_mut("filter") { changed |= rules(filter, previous, next); }
@@ -506,7 +581,7 @@ fn validate_collection_v2(document: &CollectionDocument) -> Result<(), String> {
     }
     if let Some(filter) = dataset.get("filter") {
         if !filter.is_null() {
-            validate_rule_filter(filter, document.collection.kind)?;
+            validate_dataset_filter(filter, document.collection.kind)?;
         }
     }
     let views = payload.get("views").ok_or("MISSING_COLLECTION_VIEWS")?;
@@ -582,7 +657,31 @@ fn validate_collection_v2(document: &CollectionDocument) -> Result<(), String> {
     Ok(())
 }
 fn validate_rule_filter(filter: &Value, collection_type: CollectionType) -> Result<(), String> {
-    validate_rule_filter_depth(filter, collection_type, 0)
+  validate_rule_filter_depth(filter, collection_type, 0)
+}
+fn validate_dataset_filter(filter: &Value, collection_type: CollectionType) -> Result<(), String> {
+    if filter.get("conditions").is_none() && filter.get("match").is_none() {
+        return validate_rule_filter(filter, collection_type);
+    }
+    only_keys(filter, &["path", "match", "conditions"])?;
+    match filter.get("path") {
+        Some(Value::Null) => {}
+        Some(Value::String(path)) if path.is_empty() => {}
+        Some(Value::String(path)) => validate_relative_resource_path(Some(path), "filter.path")?,
+        _ => return Err("INVALID_COLLECTION_FILTER_PATH".into()),
+    }
+    if !matches!(filter["match"].as_str(), Some("all" | "any")) {
+        return Err("INVALID_COLLECTION_FILTER_MATCH".into());
+    }
+    if collection_type == CollectionType::MediaLibrary && filter["match"] != "all" {
+        return Err("INVALID_COLLECTION_FILTER_MATCH".into());
+    }
+    for rule in array(filter, "conditions")? {
+        if rule.get("all").is_some() || rule.get("any").is_some() || rule["field"] == "path" {
+            return Err("INVALID_COLLECTION_FILTER_CONDITION".into());
+        }
+    }
+    validate_rule_filter(&serde_json::json!({"all":array(filter, "conditions")?,"any":[]}), collection_type)
 }
 fn validate_rule_filter_depth(filter: &Value, collection_type: CollectionType, depth: usize) -> Result<(), String> {
     only_keys(filter, &["all", "any"])?;
diff --git a/app/flowix-core/src/lib.rs b/app/flowix-core/src/lib.rs
index b8874d0a3..623b0cf37 100644
--- a/app/flowix-core/src/lib.rs
+++ b/app/flowix-core/src/lib.rs
@@ -17,6 +17,6 @@ pub mod secret;
 pub mod service;
 pub mod text_merge;
 
-pub use service::{FlowixError, MemoPage, MemoService, NotePage, NoteSaveOutcome, NoteService};
+pub use service::{FlowixError, NotePage, NoteSaveOutcome, NoteService};
 
 pub mod collection;
diff --git a/app/flowix-core/src/memo_file/content.rs b/app/flowix-core/src/memo_file/content.rs
index 4c5e2540f..2c4d5d9d7 100644
--- a/app/flowix-core/src/memo_file/content.rs
+++ b/app/flowix-core/src/memo_file/content.rs
@@ -1,8 +1,6 @@
 //! Markdown reads, memo list queries, and filters.
 //!
-//! Current-notebook methods support watcher and legacy reconciliation flows.
-//! Global memo-ID lookups remain for compatibility callers. Normal notebook
-//! lists and path-based document operations use the Note projection instead.
+//! Current-notebook methods support watcher and path-based document flows.
 
 use std::collections::HashSet;
 use std::fs;
@@ -17,17 +15,19 @@ impl MemoFile {
         Self::derive_tags_from_memos(self.read_all_memos())
     }
 
-    pub fn derived_tags_for_notebook_id(&self, notebook_id: Option<&str>) -> Vec<MemoTag> {
+    pub fn derived_tags_for_notebook_id(
+        &self,
+        notebook_id: Option<&str>,
+    ) -> std::io::Result<Vec<MemoTag>> {
         let now = chrono::Utc::now().timestamp_millis();
-        self.read_notebook_tag_paths(notebook_id)
-            .unwrap_or_default()
+        Ok(self.read_used_tag_ids_for_notebook_id(notebook_id)?
             .into_iter()
             .map(|name| MemoTag {
                 id: name.clone(),
                 name,
                 created_at: now,
             })
-            .collect()
+            .collect())
     }
 
     fn derive_tags_from_memos(memos: Vec<Memo>) -> Vec<MemoTag> {
@@ -56,13 +56,6 @@ impl MemoFile {
         let notebook_id = self.current_notebook_id_for_index();
         let policy = self.file_management_policy(&notebook_id);
         let root = self.get_memo_base();
-        if let Ok(Some(entries)) = self.list_note_entries_with_legacy_ids(&notebook_id) {
-            return Self::memos_from_index(super::types::MemoIndexFile {
-                version: 2,
-                last_updated: chrono::Utc::now().timestamp_millis(),
-                memos: entries,
-            }, &policy, &root);
-        }
         let list = match self.read_index() {
             Some(l) => l,
             None => return Vec::new(),
@@ -76,13 +69,6 @@ impl MemoFile {
         let root = self.get_notebook_config_by_id(&resolved_id)
             .map(|config| std::path::PathBuf::from(config.path))
             .unwrap_or_default();
-        if let Ok(Some(entries)) = self.list_note_entries_with_legacy_ids(&resolved_id) {
-            return Self::memos_from_index(super::types::MemoIndexFile {
-                version: 2,
-                last_updated: chrono::Utc::now().timestamp_millis(),
-                memos: entries,
-            }, &policy, &root);
-        }
         let list = match self.read_index_for_notebook_id(notebook_id) {
             Ok(Some(list)) => list,
             _ => return Vec::new(),
@@ -94,7 +80,7 @@ impl MemoFile {
         let mut memos: Vec<Memo> = list
             .memos
             .iter()
-            .filter(|entry| !entry.id.is_empty())
+            .filter(|entry| !entry.relative_path.is_empty())
             .filter(|entry| {
                 let relative_path = if entry.relative_path.is_empty() {
                     &entry.filename
@@ -195,7 +181,7 @@ impl MemoFile {
                         .to_lowercase()
                         .cmp(&b.filename.to_lowercase())
                         .then_with(|| a.filename.cmp(&b.filename))
-                        .then_with(|| a.id.cmp(&b.id));
+                        .then_with(|| a.relative_path.cmp(&b.relative_path));
                     b.favorited.cmp(&a.favorited).then_with(|| {
                         if descending {
                             filename_order.reverse()
@@ -216,7 +202,7 @@ impl MemoFile {
                         .then_with(|| b.updated_at.cmp(&a.updated_at))
                         // 同一毫秒创建/更新的 memo 也必须有确定顺序, 否则
                         // 分页时会出现重复或漏项。
-                        .then_with(|| b.id.cmp(&a.id))
+                        .then_with(|| b.relative_path.cmp(&a.relative_path))
                 });
                 sorted
             }
@@ -226,7 +212,7 @@ impl MemoFile {
                     b.favorited
                         .cmp(&a.favorited)
                         .then_with(|| b.created_at.cmp(&a.created_at))
-                        .then_with(|| b.id.cmp(&a.id))
+                        .then_with(|| b.relative_path.cmp(&a.relative_path))
                 });
                 sorted
             }
@@ -234,24 +220,16 @@ impl MemoFile {
     }
 
     /// Read one memo from the current notebook index. Body is not loaded.
-    pub fn read_current_memo(&self, id: &str) -> Option<Memo> {
+    pub fn read_current_memo(&self, relative_path: &str) -> Option<Memo> {
         let list = self.read_index()?;
         list.memos
             .iter()
-            .find(|e| e.id == id)
+            .find(|e| e.relative_path == relative_path)
             .map(MemoFile::index_entry_to_memo)
     }
 
-    pub fn read_memo(&self, id: &str) -> Option<Memo> {
-        self.read_current_memo(id)
-    }
-
-    /// Resolve one memo by globally unique id across all notebooks.
-    pub fn read_memo_global(&self, id: &str) -> Option<Memo> {
-        self.resolve_memo_location(id)
-            .ok()
-            .flatten()
-            .map(|location| MemoFile::index_entry_to_memo(&location.memo))
+    pub fn read_memo(&self, relative_path: &str) -> Option<Memo> {
+        self.read_current_memo(relative_path)
     }
 
     /// Read metadata and full markdown body for all memos in the current notebook.
@@ -276,7 +254,7 @@ impl MemoFile {
         let policy = super::FileManagementPolicy::from_notebook_root(&base);
         list.memos
             .into_iter()
-            .filter(|e| !e.id.is_empty())
+            .filter(|e| !e.relative_path.is_empty())
             .filter(|entry| !policy.is_index_ignored_at(&base, std::path::Path::new(&entry.relative_path)))
             .map(|entry| {
                 let path = super::notebook_path_from_relative(&base, &entry.relative_path)
@@ -288,9 +266,9 @@ impl MemoFile {
     }
 
     /// Read one memo and markdown body from the current notebook only.
-    pub fn read_current_memo_with_body(&self, id: &str) -> Option<(MemoIndexEntry, String)> {
+    pub fn read_current_memo_with_body(&self, relative_path: &str) -> Option<(MemoIndexEntry, String)> {
         let list = self.read_index()?;
-        let entry = list.memos.iter().find(|e| e.id == id)?.clone();
+        let entry = list.memos.iter().find(|e| e.relative_path == relative_path)?.clone();
         let base = self.get_memo_base();
         let path = super::notebook_path_from_relative(&base, &entry.relative_path)
             .unwrap_or_else(|_| base.join(&entry.filename));
@@ -298,18 +276,7 @@ impl MemoFile {
         Some((entry, body))
     }
 
-    pub fn read_memo_with_body(&self, id: &str) -> Option<(MemoIndexEntry, String)> {
-        self.read_current_memo_with_body(id)
-    }
-
-    /// Resolve one memo globally and read its markdown body from its owning notebook.
-    pub fn read_memo_with_body_global(&self, id: &str) -> Option<(MemoIndexEntry, String)> {
-        let location = self.resolve_memo_location(id).ok().flatten()?;
-        let entry = location.memo;
-        let base = std::path::PathBuf::from(location.notebook.path);
-        let path = super::notebook_path_from_relative(&base, &entry.relative_path)
-            .unwrap_or_else(|_| base.join(&entry.filename));
-        let body = fs::read_to_string(&path).ok()?;
-        Some((entry, body))
+    pub fn read_memo_with_body(&self, relative_path: &str) -> Option<(MemoIndexEntry, String)> {
+        self.read_current_memo_with_body(relative_path)
     }
 }
diff --git a/app/flowix-core/src/memo_file/database_layout.rs b/app/flowix-core/src/memo_file/database_layout.rs
new file mode 100644
index 000000000..d0c217787
--- /dev/null
+++ b/app/flowix-core/src/memo_file/database_layout.rs
@@ -0,0 +1,103 @@
+//! User-level SQLite database layout helpers.
+//!
+//! Databases used to live directly under `~/.flowix/`. They now live under
+//! `~/.flowix/db/`. Publish a complete SQLite snapshot under a layout lock;
+//! interruption leaves the original database and its WAL together for retry.
+
+use std::fs::{self, OpenOptions};
+use std::io;
+use std::path::{Path, PathBuf};
+
+use fs2::FileExt;
+
+pub const DATABASE_DIRECTORY_NAME: &str = "db";
+
+/// Create `db/` and snapshot existing named databases from the config root.
+/// The source is retained with its sidecars. An existing canonical database
+/// wins, leaving the complete legacy copy untouched.
+pub fn prepare_database_directory(
+    config_dir: &Path,
+    database_names: &[&str],
+) -> io::Result<PathBuf> {
+    super::ensure_storage_directory(config_dir)?;
+    let lock_path = config_dir.join(".database-layout.lock");
+    if fs::symlink_metadata(&lock_path).is_ok_and(|metadata| !metadata.file_type().is_file()) {
+        super::backup_storage_file(&lock_path)?;
+    }
+    let lock = OpenOptions::new()
+        .create(true)
+        .read(true)
+        .write(true)
+        .open(lock_path)?;
+    FileExt::lock_exclusive(&lock)?;
+
+    let result = (|| {
+        let database_dir = config_dir.join(DATABASE_DIRECTORY_NAME);
+        super::ensure_storage_directory(&database_dir)?;
+        for name in database_names {
+            validate_database_name(name)?;
+            move_database_with_sidecars(config_dir, &database_dir, name)?;
+        }
+        Ok(database_dir)
+    })();
+
+    let unlock_result = FileExt::unlock(&lock);
+    match (result, unlock_result) {
+        (Ok(path), Ok(())) => Ok(path),
+        (Err(error), _) => Err(error),
+        (Ok(_), Err(error)) => Err(error),
+    }
+}
+
+fn validate_database_name(name: &str) -> io::Result<()> {
+    let path = Path::new(name);
+    if name.is_empty()
+        || path.components().count() != 1
+        || !path.file_name().is_some_and(|n| n == name)
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("invalid database filename: {name}"),
+        ));
+    }
+    Ok(())
+}
+
+fn move_database_with_sidecars(root: &Path, database_dir: &Path, name: &str) -> io::Result<()> {
+    let source = root.join(name);
+    let destination = database_dir.join(name);
+
+    // The canonical database wins as a complete group. Never attach sidecars
+    // from an older copy, even when the two main files happen to be identical.
+    if fs::symlink_metadata(&destination).is_ok() {
+        return Ok(());
+    }
+    // Orphan WAL files cannot belong to a new main database.
+    super::backup_database(&destination)?;
+    if !source.is_file() {
+        return Ok(());
+    }
+    // VACUUM INTO includes committed WAL contents in a standalone database.
+    // Only publish after SQLite has closed the snapshot. Never split the
+    // source main file from its WAL, even if the process exits mid-migration.
+    let temporary = database_dir.join(format!(".{name}.{}.tmp", uuid::Uuid::new_v4()));
+    let snapshot = (|| -> io::Result<()> {
+        let conn = rusqlite::Connection::open_with_flags(
+            &source, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
+        ).map_err(io::Error::other)?;
+        conn.execute("VACUUM INTO ?1", [temporary.to_string_lossy().as_ref()])
+            .map_err(io::Error::other)?;
+        drop(conn);
+        fs::File::open(&temporary)?.sync_all()?;
+        fs::rename(&temporary, &destination)
+    })();
+    if let Err(error) = snapshot {
+        let _ = fs::remove_file(&temporary);
+        if super::is_rebuildable_storage_error(&error) {
+            super::backup_database(&source)?;
+            return Ok(()); // The normal initializer creates an empty canonical DB.
+        }
+        return Err(error);
+    }
+    Ok(())
+}
diff --git a/app/flowix-core/src/memo_file/derivation.rs b/app/flowix-core/src/memo_file/derivation.rs
index 4f7c1908f..19be9afd3 100644
--- a/app/flowix-core/src/memo_file/derivation.rs
+++ b/app/flowix-core/src/memo_file/derivation.rs
@@ -847,7 +847,7 @@ pub fn apply_derived_memo_fields(memo: &mut Memo, full_content: &str) {
                 Some(_) => None,
                 None => {
                     tracing::warn!(
-                        memo_id = %memo.id,
+                        note_path = %memo.relative_path,
                         tag = %raw,
                         "ignoring invalid legacy frontmatter tag path while deriving memo metadata"
                     );
diff --git a/app/flowix-core/src/memo_file/file_management.rs b/app/flowix-core/src/memo_file/file_management.rs
index ce6b26071..dc77028cb 100644
--- a/app/flowix-core/src/memo_file/file_management.rs
+++ b/app/flowix-core/src/memo_file/file_management.rs
@@ -17,35 +17,9 @@ pub struct FileManagementPolicy {
     /// the Markdown note index.
     #[serde(default)]
     pub excluded_index_paths: Vec<String>,
-    #[serde(default)]
-    pub legacy_skip_dirs: Vec<String>,
-    #[serde(default)]
-    pub legacy_skip_files: Vec<String>,
-    #[serde(default)]
-    pub legacy_watcher_migrated: bool,
-}
-
-fn wildcard_match(pattern: &str, name: &str) -> bool {
-    let (pattern, name) = (pattern.as_bytes(), name.as_bytes());
-    let (mut p, mut n, mut star, mut retry) = (0, 0, None, 0);
-    while n < name.len() {
-        if p < pattern.len() && pattern[p] == name[n] { p += 1; n += 1; }
-        else if p < pattern.len() && pattern[p] == b'*' { star = Some(p); p += 1; retry = n; }
-        else if let Some(position) = star { p = position + 1; retry += 1; n = retry; }
-        else { return false; }
-    }
-    while p < pattern.len() && pattern[p] == b'*' { p += 1; }
-    p == pattern.len()
 }
 
 impl FileManagementPolicy {
-    pub fn matches_legacy_entry(&self, absolute: &Path) -> bool {
-        let Some(name) = absolute.file_name().map(|name| name.to_string_lossy()) else { return false; };
-        self.legacy_skip_dirs.iter().any(|skip| skip == name.as_ref())
-            || std::fs::symlink_metadata(absolute).is_ok_and(|metadata| metadata.is_file())
-                && self.legacy_skip_files.iter().any(|pattern| wildcard_match(pattern, &name))
-    }
-
     pub fn is_locked_name(name: &str) -> bool {
         matches!(name, ".flowix" | ".plugin-output") || name.eq_ignore_ascii_case(".index.yaml")
     }
@@ -89,7 +63,6 @@ impl FileManagementPolicy {
             let ignored_name = notebook_agents_file
                 || name.starts_with('.')
                 || matches!(name.as_ref(), "attachments" | "attachments-cache" | "node_modules" | "bower_components" | "__pycache__")
-                || self.legacy_skip_dirs.iter().any(|skip| skip == name.as_ref())
                 || legacy_media_sidecar
                 || (is_last && (matches!(name.as_ref(), "Thumbs.db" | "ehthumbs.db" | "desktop.ini")
                     || name.ends_with(".tmp") || name.ends_with(".swp") || name.ends_with(".bak")
@@ -105,14 +78,6 @@ impl FileManagementPolicy {
     /// as names. The relative path is always scoped to `root`.
     pub fn is_ignored_at(&self, root: &Path, relative: &Path) -> bool {
         if self.is_ignored(relative) { return true; }
-        let key = relative.to_string_lossy().replace('\\', "/");
-        let file = root.join(relative);
-        if !self.included_paths.iter().any(|included| included == &key)
-            && std::fs::symlink_metadata(&file).is_ok_and(|metadata| metadata.is_file())
-        {
-            let name = relative.file_name().unwrap_or_default().to_string_lossy();
-            if self.legacy_skip_files.iter().any(|pattern| wildcard_match(pattern, &name)) { return true; }
-        }
         let mut current = root.to_path_buf();
         let mut key = String::new();
         for component in relative.components() {
@@ -144,8 +109,7 @@ impl FileManagementPolicy {
             && relative.file_name().is_some_and(|name| name.to_string_lossy() == "AGENTS.md");
         let default_policy = FileManagementPolicy::default();
         if !is_root_agents
-            && (default_policy.is_ignored_at(root, relative)
-                || self.matches_legacy_entry(&root.join(relative)))
+            && default_policy.is_ignored_at(root, relative)
         {
             return true;
         }
diff --git a/app/flowix-core/src/memo_file/frontmatter.rs b/app/flowix-core/src/memo_file/frontmatter.rs
index 08c602e83..0dba58569 100644
--- a/app/flowix-core/src/memo_file/frontmatter.rs
+++ b/app/flowix-core/src/memo_file/frontmatter.rs
@@ -1,14 +1,12 @@
 //! Markdown frontmatter 解析与编辑。
 //!
 //! Notes are addressed by notebook-relative path. Supplied Markdown is kept
-//! intact, including legacy `flowix_key`. Existing identity fields remain reserved, and the
-//! merge helper can read them for legacy frontmatter compatibility. File
-//! registration never derives a note identity from those fields.
+//! intact; frontmatter fields are not parsed as note identities.
 //!
 //! ## 工具
 //!
 //! - [`extract_body_content`] — 切掉 `---\n...\n---` 块, 返回 body 切片。
-//! - [`build_md_content`] — 新建时剔除模板遗留的身份字段。
+//! - [`extract_document_metadata`] — 解析 frontmatter 属性与标签。
 //! - [`merge_frontmatter`] — 就地编辑 frontmatter 块, 见下文。
 //!
 //! ## `merge_frontmatter` 行为
@@ -19,7 +17,6 @@
 //!      **就地替换** value;
 //!    - 其它行 (注释 / 空行 / 列表 / 多行值起点 / 其它 map) → **字节级保留**。
 //! 3. `overrides` 里有但 frontmatter 找不到对应行的新字段:
-//!    - 显式传入的旧 `flowix_key` 字段 → **头部**追加;
 //!    - 其它字段 → **末尾**追加。
 //! 4. 无 frontmatter 块 → 在文件头插入包含 `overrides` 的完整块。
 //! 5. 规范化文件边界的 UTF-8 BOM; 其它 body 内容保持原样。
@@ -79,15 +76,6 @@ pub fn normalize_markdown_encoding_boundaries(content: &str) -> Cow<'_, str> {
 /// 3. value (含引号, 替换时由 caller 决定是否重新加引号)
 static FM_LINE_RE: Lazy<Regex> =
     Lazy::new(|| Regex::new(r"^(\s*)([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*?)\s*$").unwrap());
-pub const CANONICAL_FRONTMATTER_KEY: &str = "flowix_key";
-pub const LEGACY_FRONTMATTER_KEY: &str = "key";
-/// Reserved legacy identity fields. They are not note identities in the path
-/// index and must not appear as user-defined properties.
-pub const SYSTEM_FRONTMATTER_KEYS: [&str; 2] = [CANONICAL_FRONTMATTER_KEY, LEGACY_FRONTMATTER_KEY];
-
-pub fn is_system_frontmatter_key(key: &str) -> bool {
-    SYSTEM_FRONTMATTER_KEYS.contains(&key)
-}
 static TAGS_LINE_RE: Lazy<Regex> =
     Lazy::new(|| Regex::new(r#"^(?:tags|'tags'|"tags")\s*:"#).unwrap());
 static LEGACY_TAG_LINE_RE: Lazy<Regex> =
@@ -115,9 +103,7 @@ pub enum FrontmatterMetadataError {
 
 /// 注入指令集: key → 新 value。**就地替换**语义。
 ///
-/// The merge helper accepts an old `key` override for compatibility and maps
-/// it to `flowix_key`. Current note creation and indexing do not supply an
-/// identity override. Other field names are merged as provided.
+/// Frontmatter overrides are merged by field name. No field carries note identity.
 pub type MergeOverrides = BTreeMap<String, String>;
 
 /// 切掉 YAML frontmatter 块, 返回剩余 body。
@@ -125,7 +111,7 @@ pub type MergeOverrides = BTreeMap<String, String>;
 /// 输入示例:
 /// ```text
 /// ---
-/// flowix_key: abc123
+/// status: draft
 /// ---
 /// # Hello
 /// body
@@ -139,66 +125,6 @@ pub fn extract_body_content(content: &str) -> &str {
     }
 }
 
-/// Read a legacy `flowix_key` value for frontmatter compatibility. File
-/// registration resolves existing notes by path and does not call this parser.
-///
-/// 行为:
-/// - 无 frontmatter 块 → None
-/// - 有 frontmatter 但没 `flowix_key:` 行 → None
-/// - `flowix_key:` value 不在 `[0-9a-z]{6|8}` 字符集 → None (防止用户手写垃圾值)
-pub fn extract_frontmatter_key(content: &str) -> Option<String> {
-    let caps = FRONTMATTER_RE.captures(content)?;
-    let inner = caps.get(1)?.as_str();
-    for line in inner.split('\n') {
-        if let Some(c) = FM_LINE_RE.captures(line) {
-            let name = c.get(2).map(|m| m.as_str())?;
-            if name == CANONICAL_FRONTMATTER_KEY {
-                let value = c
-                    .get(3)
-                    .map(|m| m.as_str())?
-                    .trim()
-                    .trim_matches(|ch| ch == '"' || ch == '\'');
-                if matches!(value.len(), 6 | super::MEMO_ID_LENGTH)
-                    && value.chars().all(|c| {
-                        c.is_ascii_alphanumeric() && (c.is_ascii_digit() || c.is_ascii_lowercase())
-                    })
-                {
-                    return Some(value.to_string());
-                }
-                return None;
-            }
-        }
-    }
-    None
-}
-
-fn extract_legacy_frontmatter_key(content: &str) -> Option<String> {
-    let caps = FRONTMATTER_RE.captures(content)?;
-    let inner = caps.get(1)?.as_str();
-    for line in inner.split('\n') {
-        if let Some(c) = FM_LINE_RE.captures(line) {
-            let name = c.get(2).map(|m| m.as_str())?;
-            if name != LEGACY_FRONTMATTER_KEY {
-                continue;
-            }
-            let value = c
-                .get(3)
-                .map(|m| m.as_str())?
-                .trim()
-                .trim_matches(|ch| ch == '"' || ch == '\'');
-            if matches!(value.len(), 6 | 8)
-                && value.chars().all(|c| {
-                    c.is_ascii_alphanumeric() && (c.is_ascii_digit() || c.is_ascii_lowercase())
-                })
-            {
-                return Some(value.to_string());
-            }
-            return None;
-        }
-    }
-    None
-}
-
 pub fn extract_frontmatter_properties(content: &str) -> Value {
     extract_document_metadata_tolerant(content)
         .map(|metadata| metadata.properties)
@@ -500,15 +426,7 @@ pub(crate) fn replace_frontmatter_tags_preserving_invalid_paths(
             .map_err(|error| FrontmatterMetadataError::InvalidYaml(error.to_string()))?;
         lines = yaml.trim_end().lines().map(str::to_string).collect();
     } else {
-        let insert_at = lines
-            .iter()
-            .position(|line| {
-                line.trim_start()
-                    .starts_with(&format!("{}:", CANONICAL_FRONTMATTER_KEY))
-            })
-            .map(|index| index + 1)
-            .unwrap_or(lines.len());
-        lines.splice(insert_at..insert_at, replacement);
+        lines.extend(replacement);
     }
 
     Ok(format!("---\n{}\n---\n{}", lines.join("\n"), body))
@@ -516,34 +434,7 @@ pub(crate) fn replace_frontmatter_tags_preserving_invalid_paths(
 
 /// 就地编辑 frontmatter 块, 见模块 doc 详述行为契约。
 pub fn merge_frontmatter(content: &str, overrides: &MergeOverrides) -> String {
-    let mut canonical_overrides = overrides.clone();
-    if let Some(legacy_value) = canonical_overrides.remove(LEGACY_FRONTMATTER_KEY) {
-        // A legacy override must not replace an existing canonical field.
-        // Explicit canonical overrides remain available to compatibility callers.
-        if extract_frontmatter_key(content).is_none() {
-            // Existing legacy-only notes migrate by copying their stored
-            // legacy value. The override is only a fallback when no legacy
-            // key line exists at all.
-            let legacy_value = extract_legacy_frontmatter_key(content).unwrap_or(legacy_value);
-            canonical_overrides
-                .entry(CANONICAL_FRONTMATTER_KEY.to_string())
-                .or_insert(legacy_value);
-        }
-    }
-    let overrides = &canonical_overrides;
-
     if overrides.is_empty() {
-        // Preserve an existing legacy field when collapsing an adjacent
-        // system-only frontmatter block into the user's block.
-        if let Some(canonical_key) = extract_frontmatter_key(content) {
-            let mut structural_overrides = MergeOverrides::new();
-            structural_overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), canonical_key);
-            if let Some(collapsed) =
-                collapse_adjacent_override_frontmatter(content, &structural_overrides)
-            {
-                return merge_frontmatter(&collapsed, &structural_overrides);
-            }
-        }
         return content.to_string();
     }
 
@@ -580,16 +471,10 @@ pub fn merge_frontmatter(content: &str, overrides: &MergeOverrides) -> String {
         }
         None => {
             // 无 frontmatter 块 → 从显式传入的 overrides 创建完整块。
-            let mut block_lines: Vec<String> = Vec::new();
-            let mut tail_lines: Vec<String> = Vec::new();
-            for (k, v) in overrides {
-                if k == CANONICAL_FRONTMATTER_KEY {
-                    block_lines.push(format!("{}: {}", k, v));
-                } else {
-                    tail_lines.push(format!("{}: {}", k, v));
-                }
-            }
-            block_lines.extend(tail_lines);
+            let block_lines: Vec<String> = overrides
+                .iter()
+                .map(|(key, value)| format!("{}: {}", key, value))
+                .collect();
             let block = block_lines.join("\n");
             // body 前补一个换行: 文件头插入 `---\n...\n---\n\n<body>`
             format!("---\n{}\n---\n\n{}", block, content)
@@ -648,7 +533,6 @@ fn frontmatter_contains_only_override_fields(inner: &str, overrides: &MergeOverr
 /// - 对 `key: value` 单行, 命中 overrides 内的 key 时**就地替换** value;
 ///   **不**命中时**保留原行** (含其原引号风格 / 缩进)。
 /// - overrides 内出现但 frontmatter 找不到对应行的字段:
-///   - 显式传入的 `flowix_key` → 准备头部追加;
 ///   - 其它字段 → 准备末尾追加。
 fn merge_inner(inner: &str, overrides: &MergeOverrides) -> String {
     // 1. 行级扫描, 拆出 (key 名, 替换后 value 或 None) 与保留行
@@ -677,22 +561,15 @@ fn merge_inner(inner: &str, overrides: &MergeOverrides) -> String {
         }
     }
 
-    // 2. 显式旧身份字段在头部追加，其它字段在末尾追加。
-    let mut head_lines: Vec<String> = Vec::new();
+    // 2. Append newly supplied fields in their original order.
     let mut tail_lines: Vec<String> = Vec::new();
     for (k, v) in &pending {
         // pending 里剩下的就是 overrides 中未在 frontmatter 找到对应行的 key
-        if k == CANONICAL_FRONTMATTER_KEY {
-            head_lines.push(format!("{}: {}", k, v));
-        } else {
-            tail_lines.push(format!("{}: {}", k, v));
-        }
+        tail_lines.push(format!("{}: {}", k, v));
     }
 
     // 3. 拼接
-    let mut final_lines: Vec<String> =
-        Vec::with_capacity(head_lines.len() + preserved_lines.len() + tail_lines.len());
-    final_lines.extend(head_lines);
+    let mut final_lines: Vec<String> = Vec::with_capacity(preserved_lines.len() + tail_lines.len());
     final_lines.extend(preserved_lines);
     final_lines.extend(tail_lines);
 
@@ -707,19 +584,22 @@ mod tests {
 
     #[test]
     fn extracts_body_after_frontmatter() {
-        let md = "---\nflowix_key: x\n---\n# Title\nbody\n";
+        let md = "---\nstatus: draft\n---\n# Title\nbody\n";
         assert_eq!(extract_body_content(md), "# Title\nbody\n");
     }
 
     #[test]
     fn extracts_frontmatter_after_leading_blank_lines() {
         let md = "\n  \n---\nflowix_key: abc12345\ntags: [inbox]\n---\n# Title\n";
-        assert_eq!(extract_frontmatter_key(md), Some("abc12345".to_string()));
         assert_eq!(extract_body_content(md), "# Title\n");
         assert_eq!(
             extract_document_metadata(md).unwrap().tags,
             vec!["inbox".to_string()]
         );
+        assert_eq!(
+            extract_document_metadata(md).unwrap().properties["flowix_key"],
+            "abc12345"
+        );
     }
 
     #[test]
@@ -735,57 +615,45 @@ mod tests {
     }
 
     #[test]
-    fn extracts_quoted_frontmatter_keys() {
-        assert_eq!(
-            extract_frontmatter_key("---\nflowix_key: \"abc12345\"\n---\nbody\n"),
-            Some("abc12345".to_string())
-        );
-        assert_eq!(
-            extract_frontmatter_key("---\nflowix_key: 'abc123'\n---\nbody\n"),
-            Some("abc123".to_string())
-        );
-    }
-
-    #[test]
-    fn ignores_legacy_key_as_memo_identity() {
-        assert_eq!(
-            extract_frontmatter_key("---\nkey: abc12345\n---\nbody\n"),
-            None
-        );
-    }
-
-    #[test]
-    fn rejects_invalid_canonical_key_even_when_legacy_key_is_valid() {
-        assert_eq!(
-            extract_frontmatter_key("---\nflowix_key: not-a-valid-id\nkey: abc12345\n---\nbody\n"),
-            None
-        );
+    fn historical_flowix_key_is_an_ordinary_yaml_property() {
+        let metadata = extract_document_metadata(
+            "---\nflowix_key: \"abc12345\"\nkey: legacy-value\n---\nbody\n",
+        )
+        .unwrap();
+        assert_eq!(metadata.properties["flowix_key"], "abc12345");
+        assert_eq!(metadata.properties["key"], "legacy-value");
     }
 
     #[test]
-    fn copies_legacy_key_into_canonical_field_without_removing_legacy_field() {
+    fn ordinary_properties_can_be_merged_independently() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "abc123".to_string());
         let out = merge_frontmatter("---\nkey: old999\n---\nbody\n", &overrides);
-        assert_eq!(out, "---\nflowix_key: old999\nkey: old999\n---\nbody\n");
+        assert_eq!(out, "---\nkey: abc123\n---\nbody\n");
     }
 
     #[test]
-    fn canonical_merge_override_wins_over_legacy_override() {
+    fn historical_identity_named_fields_use_generic_merge_behavior() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "legacy123".to_string());
-        overrides.insert("flowix_key".to_string(), "canonical1".to_string());
+        overrides.insert("flowix_key".to_string(), "ordinary1".to_string());
         let out = merge_frontmatter("body\n", &overrides);
-        assert_eq!(out, "---\nflowix_key: canonical1\n---\n\nbody\n");
+        assert_eq!(
+            out,
+            "---\nflowix_key: ordinary1\nkey: legacy123\n---\n\nbody\n"
+        );
     }
 
     #[test]
-    fn legacy_merge_override_does_not_replace_valid_canonical_key() {
+    fn merge_adds_an_ordinary_property_alongside_historical_identity_field() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "legacy-new-id".to_string());
         let input = "---\nflowix_key: abc12345\n---\nbody\n";
 
-        assert_eq!(merge_frontmatter(input, &overrides), input);
+        assert_eq!(
+            merge_frontmatter(input, &overrides),
+            "---\nflowix_key: abc12345\nkey: legacy-new-id\n---\nbody\n"
+        );
     }
 
     // ============== merge_frontmatter: no frontmatter ==============
@@ -795,7 +663,7 @@ mod tests {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "abc123".to_string());
         let out = merge_frontmatter("body\n", &overrides);
-        assert_eq!(out, "---\nflowix_key: abc123\n---\n\nbody\n");
+        assert_eq!(out, "---\nkey: abc123\n---\n\nbody\n");
     }
 
     #[test]
@@ -804,19 +672,19 @@ mod tests {
         overrides.insert("key".to_string(), "abc123".to_string());
         assert_eq!(
             merge_frontmatter("", &overrides),
-            "---\nflowix_key: abc123\n---\n\n"
+            "---\nkey: abc123\n---\n\n"
         );
     }
 
     // ============== merge_frontmatter: replace existing key ==============
 
     #[test]
-    fn explicit_canonical_override_replaces_existing_key_in_place() {
+    fn merge_replaces_historical_identity_named_property_in_place() {
         let mut overrides = MergeOverrides::new();
-        overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), "newid1".to_string());
+        overrides.insert("flowix_key".to_string(), "new-value".to_string());
         let input = "---\nflowix_key: oldid9\ntags: [a]\n---\nbody\n";
         let out = merge_frontmatter(input, &overrides);
-        assert_eq!(out, "---\nflowix_key: newid1\ntags: [a]\n---\nbody\n");
+        assert_eq!(out, "---\nflowix_key: new-value\ntags: [a]\n---\nbody\n");
     }
 
     #[test]
@@ -827,40 +695,40 @@ mod tests {
         let out = merge_frontmatter(input, &overrides);
         assert_eq!(
             out,
-            "---\nflowix_key: abc123\ntags: [a, b]\n# comment\ndescription: |\n  multi\n  line\n\nauthor: x\n---\nbody\n"
+            "---\ntags: [a, b]\n# comment\ndescription: |\n  multi\n  line\n\nauthor: x\nkey: abc123\n---\nbody\n"
         );
     }
 
-    // ============== merge_frontmatter: prepend key, append others ==============
+    // ============== merge_frontmatter: append fields ==============
 
     #[test]
-    fn merge_prepends_missing_key() {
+    fn merge_appends_missing_key_property() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "abc123".to_string());
         let input = "---\ntags: [a]\n---\nbody\n";
         let out = merge_frontmatter(input, &overrides);
-        assert_eq!(out, "---\nflowix_key: abc123\ntags: [a]\n---\nbody\n");
+        assert_eq!(out, "---\ntags: [a]\nkey: abc123\n---\nbody\n");
     }
 
     #[test]
-    fn merge_prepends_missing_key_in_crlf_frontmatter() {
+    fn merge_appends_missing_key_property_in_crlf_frontmatter() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "abc123".to_string());
         let input = "---\r\nname: imported\r\n---\r\nbody\r\n";
         let out = merge_frontmatter(input, &overrides);
         assert_eq!(
             out,
-            "---\nflowix_key: abc123\nname: imported\n---\nbody\r\n"
+            "---\nname: imported\nkey: abc123\n---\nbody\r\n"
         );
     }
 
     #[test]
-    fn merge_collapses_adjacent_key_block_into_user_frontmatter() {
+    fn merge_collapses_adjacent_frontmatter_for_an_ordinary_property() {
         let mut overrides = MergeOverrides::new();
-        overrides.insert("key".to_string(), "sg8qgwdq".to_string());
+        overrides.insert("name".to_string(), "new-name".to_string());
         let input = concat!(
             "---\n",
-            "flowix_key: sg8qgwdq\n",
+            "name: old-name\n",
             "---\n",
             "---\n",
             "name: guizang-ppt-skill\n",
@@ -873,8 +741,7 @@ mod tests {
             out,
             concat!(
                 "---\n",
-                "flowix_key: sg8qgwdq\n",
-                "name: guizang-ppt-skill\n",
+                "name: new-name\n",
                 "description: deck generator\n",
                 "---\n",
                 "body\n"
@@ -886,16 +753,16 @@ mod tests {
     fn merge_appends_missing_non_key_field() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("extra".to_string(), "x".to_string());
-        let input = "---\nflowix_key: abc123\ntags: [a]\n---\nbody\n";
+        let input = "---\nstatus: draft\ntags: [a]\n---\nbody\n";
         let out = merge_frontmatter(input, &overrides);
         assert_eq!(
             out,
-            "---\nflowix_key: abc123\ntags: [a]\nextra: x\n---\nbody\n"
+            "---\nstatus: draft\ntags: [a]\nextra: x\n---\nbody\n"
         );
     }
 
     #[test]
-    fn merge_prepends_key_and_appends_others_together() {
+    fn merge_appends_multiple_fields() {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "abc123".to_string());
         overrides.insert("extra".to_string(), "y".to_string());
@@ -903,7 +770,7 @@ mod tests {
         let out = merge_frontmatter(input, &overrides);
         assert_eq!(
             out,
-            "---\nflowix_key: abc123\ntags: [a]\nextra: y\n---\nbody\n"
+            "---\ntags: [a]\nextra: y\nkey: abc123\n---\nbody\n"
         );
     }
 
@@ -914,40 +781,40 @@ mod tests {
         // 同一字段名出现两次: 都替换 (YAML 语义上重复 key 是非法的,
         // 工具做防御性替换避免用户 frontmatter 包含重复行时丢改)。
         let mut overrides = MergeOverrides::new();
-        overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), "newid1".to_string());
-        let input = "---\nflowix_key: oldid9\nother: x\nflowix_key: anotherold\n---\nbody\n";
+        overrides.insert("status".to_string(), "new-value".to_string());
+        let input = "---\nstatus: old\nother: x\nstatus: another\n---\nbody\n";
         let out = merge_frontmatter(input, &overrides);
         assert_eq!(
             out,
-            "---\nflowix_key: newid1\nother: x\nflowix_key: newid1\n---\nbody\n"
+            "---\nstatus: new-value\nother: x\nstatus: new-value\n---\nbody\n"
         );
     }
 
     #[test]
     fn merge_empty_overrides_returns_content_unchanged() {
         let overrides: MergeOverrides = MergeOverrides::new();
-        let input = "---\nflowix_key: abc123\n---\nbody\n";
+        let input = "---\nstatus: draft\n---\nbody\n";
         assert_eq!(merge_frontmatter(input, &overrides), input);
     }
 
     #[test]
     fn merge_strips_leading_bom_before_inserting_frontmatter() {
         let mut overrides = MergeOverrides::new();
-        overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), "abc123".to_string());
+        overrides.insert("status".to_string(), "draft".to_string());
 
         let out = merge_frontmatter("\u{FEFF}# Imported\n", &overrides);
 
-        assert_eq!(out, "---\nflowix_key: abc123\n---\n\n# Imported\n");
+        assert_eq!(out, "---\nstatus: draft\n---\n\n# Imported\n");
     }
 
     #[test]
     fn encoding_boundary_normalization_is_idempotent_and_scoped() {
-        let legacy = "---\nflowix_key: abc123\n---\n\u{FEFF}body \u{FEFF} text\n";
+        let legacy = "---\nstatus: draft\n---\n\u{FEFF}body \u{FEFF} text\n";
         let normalized = normalize_markdown_encoding_boundaries(legacy);
 
         assert_eq!(
             normalized,
-            "---\nflowix_key: abc123\n---\nbody \u{FEFF} text\n"
+            "---\nstatus: draft\n---\nbody \u{FEFF} text\n"
         );
         assert!(matches!(
             normalize_markdown_encoding_boundaries(normalized.as_ref()),
@@ -958,24 +825,24 @@ mod tests {
     #[test]
     fn merge_strips_leading_bom_before_updating_frontmatter() {
         let mut overrides = MergeOverrides::new();
-        overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), "abc123".to_string());
+        overrides.insert("status".to_string(), "draft".to_string());
 
-        let out = merge_frontmatter("\u{FEFF}---\nflowix_key: old999\n---\nbody\n", &overrides);
+        let out = merge_frontmatter("\u{FEFF}---\nstatus: old\n---\nbody\n", &overrides);
 
-        assert_eq!(out, "---\nflowix_key: abc123\n---\nbody\n");
+        assert_eq!(out, "---\nstatus: draft\n---\nbody\n");
     }
 
     #[test]
     fn merge_strips_legacy_bom_at_frontmatter_body_boundary() {
         let mut overrides = MergeOverrides::new();
-        overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), "abc123".to_string());
+        overrides.insert("status".to_string(), "draft".to_string());
 
         let out = merge_frontmatter(
-            "---\nflowix_key: old999\n---\n\u{FEFF}<p>Imported</p>\n",
+            "---\nstatus: old\n---\n\u{FEFF}<p>Imported</p>\n",
             &overrides,
         );
 
-        assert_eq!(out, "---\nflowix_key: abc123\n---\n<p>Imported</p>\n");
+        assert_eq!(out, "---\nstatus: draft\n---\n<p>Imported</p>\n");
     }
 
     #[test]
@@ -985,17 +852,17 @@ mod tests {
 
         let out = merge_frontmatter("body \u{FEFF} text\n", &overrides);
 
-        assert_eq!(out, "---\nflowix_key: abc123\n---\n\nbody \u{FEFF} text\n");
+        assert_eq!(out, "---\nkey: abc123\n---\n\nbody \u{FEFF} text\n");
     }
 
     #[test]
     fn merge_preserves_value_with_quotes() {
         // 替换时按 YAML 标准不引号, 工具统一输出 `key: <value>` 无引号
         let mut overrides = MergeOverrides::new();
-        overrides.insert(CANONICAL_FRONTMATTER_KEY.to_string(), "abc123".to_string());
-        let input = "---\nflowix_key: \"old999\"\n---\nbody\n";
+        overrides.insert("status".to_string(), "draft".to_string());
+        let input = "---\nstatus: \"old\"\n---\nbody\n";
         let out = merge_frontmatter(input, &overrides);
-        assert_eq!(out, "---\nflowix_key: abc123\n---\nbody\n");
+        assert_eq!(out, "---\nstatus: draft\n---\nbody\n");
     }
 
     #[test]
@@ -1004,14 +871,14 @@ mod tests {
         let mut overrides = MergeOverrides::new();
         overrides.insert("key".to_string(), "z9y8x7".to_string());
         let out = merge_frontmatter("---\n---\nx", &overrides);
-        assert_eq!(out, "---\nflowix_key: z9y8x7\n---\nx");
+        assert_eq!(out, "---\nkey: z9y8x7\n---\nx");
     }
 
     #[test]
     fn document_metadata_uses_only_frontmatter_tags() {
         let content = concat!(
             "---\n",
-            "flowix_key: abc12345\n",
+            "status: draft\n",
             "tags: [product, product/design, product]\n",
             "status: draft\n",
             "---\n",
@@ -1037,7 +904,7 @@ mod tests {
 
     #[test]
     fn lenient_tag_replacement_preserves_unrelated_invalid_paths() {
-        let input = "---\nflowix_key: abc12345\ntags: [\"legacy tag\", remove]\n---\nbody\n";
+        let input = "---\nstatus: draft\ntags: [\"legacy tag\", remove]\n---\nbody\n";
         let metadata = extract_document_metadata_preserving_invalid_tag_paths(input).unwrap();
         assert_eq!(metadata.tags, vec!["legacy tag", "remove"]);
 
@@ -1051,13 +918,13 @@ mod tests {
     #[test]
     fn document_metadata_does_not_classify_body_tags() {
         let metadata =
-            extract_document_metadata("---\nflowix_key: abc12345\n---\n# body-only\n").unwrap();
+            extract_document_metadata("---\nstatus: draft\n---\n# body-only\n").unwrap();
         assert!(metadata.tags.is_empty());
     }
 
     #[test]
     fn legacy_singular_tag_is_read_and_rewritten_as_tags() {
-        let input = "---\nflowix_key: abc12345\ntag: [legacy]\n---\nbody\n";
+        let input = "---\nstatus: draft\ntag: [legacy]\n---\nbody\n";
         let metadata = extract_document_metadata(input).unwrap();
         assert_eq!(metadata.tags, vec!["legacy"]);
         assert!(metadata.properties.get("tag").is_none());
@@ -1101,7 +968,7 @@ mod tests {
     fn replace_tags_preserves_unrelated_yaml_and_body() {
         let input = concat!(
             "---\n",
-            "flowix_key: abc12345\n",
+            "status: draft\n",
             "# keep this comment\n",
             "tags:\n",
             "  - old/path\n",
@@ -1116,7 +983,7 @@ mod tests {
             output,
             concat!(
                 "---\n",
-                "flowix_key: abc12345\n",
+                "status: draft\n",
                 "# keep this comment\n",
                 "tags:\n",
                 "  - \"new/path\"\n",
@@ -1129,15 +996,15 @@ mod tests {
     }
 
     #[test]
-    fn replace_tags_inserts_after_key_and_keeps_body() {
+    fn replace_tags_appends_a_frontmatter_property_and_keeps_body() {
         let output = replace_frontmatter_tags(
-            "---\nflowix_key: abc12345\nstatus: draft\n---\nbody\n",
+            "---\nsource: archive\nstatus: draft\n---\nbody\n",
             &["product".to_string()],
         )
         .unwrap();
         assert_eq!(
             output,
-            "---\nflowix_key: abc12345\ntags:\n  - \"product\"\nstatus: draft\n---\nbody\n"
+            "---\nsource: archive\nstatus: draft\ntags:\n  - \"product\"\n---\nbody\n"
         );
     }
 }
diff --git a/app/flowix-core/src/memo_file/index_store.rs b/app/flowix-core/src/memo_file/index_store.rs
index b17c3957c..9b9ef6821 100644
--- a/app/flowix-core/src/memo_file/index_store.rs
+++ b/app/flowix-core/src/memo_file/index_store.rs
@@ -1,8 +1,7 @@
-//! Legacy memo-ID records and metadata stored in the notebook-local database.
+//! Notebook-relative-path projection stored in the notebook-local database.
 //!
-//! The Note projection is path-keyed in `note_index`; this module remains
-//! for callers and records that still require memo IDs. Older global rows are
-//! imported from the user-level registry database during notebook setup.
+//! The separate Note catalog in `note_index` tracks filesystem metadata. This
+//! module stores the content-derived listing fields used by memo surfaces.
 
 use std::fs;
 use std::path::PathBuf;
@@ -13,34 +12,12 @@ use super::derivation::{extract_agent_threads_from_body, extract_thumbnail};
 use super::frontmatter::extract_frontmatter_properties;
 use super::notebook::sqlite_to_io;
 use super::types::{
-    AgentThreadItem, Memo, MemoColor, MemoIndexEntry, MemoIndexFile, MemoLocation, MemoTodoEntry,
-    NotebookConfig, TodoItem,
+    AgentThreadItem, Memo, NoteColor, MemoIndexEntry, MemoIndexFile, MemoLocation, NotebookConfig,
 };
 use super::MemoFile;
 
-/// Durable identity of the latest committed bytes for one memo.
-///
-/// `revision` is a local, monotonically increasing counter. `change_id`
-/// identifies one concrete content transition and is stable when duplicate
-/// filesystem notifications observe the same bytes.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MemoContentRevision {
-    pub memo_id: String,
-    pub notebook_id: String,
-    pub content_hash: String,
-    pub revision: i64,
-    pub change_id: String,
-    pub updated_at: i64,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct MemoContentCommit {
-    pub state: MemoContentRevision,
-    pub changed: bool,
-}
-
-/// Path-keyed successor of [`MemoContentRevision`]. The revision stream is
-/// addressed by `(notebook_id, relative_path)` instead of a legacy memo ID,
+/// Path-keyed content revision for a note. The revision stream is
+/// addressed by `(notebook_id, relative_path)`,
 /// so renames must carry the row over (see rename/move flows).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct NoteContentRevision {
@@ -58,43 +35,31 @@ pub struct NoteContentCommit {
     pub changed: bool,
 }
 
-// Pending markers only bridge a live Desktop watcher and a concurrent CLI/MCP
-// process. Expiry prevents an offline create from being mistaken for a create
-// when that document is edited much later.
-const EXTERNAL_CREATE_MARKER_TTL_MS: i64 = 60_000;
-
-fn color_to_str(color: MemoColor) -> &'static str {
+fn color_to_str(color: NoteColor) -> &'static str {
     match color {
-        MemoColor::Red => "red",
-        MemoColor::Orange => "orange",
-        MemoColor::Yellow => "yellow",
-        MemoColor::Green => "green",
-        MemoColor::Cyan => "cyan",
-        MemoColor::Blue => "blue",
-        MemoColor::Gray => "gray",
+        NoteColor::Red => "red",
+        NoteColor::Orange => "orange",
+        NoteColor::Yellow => "yellow",
+        NoteColor::Green => "green",
+        NoteColor::Cyan => "cyan",
+        NoteColor::Blue => "blue",
+        NoteColor::Gray => "gray",
     }
 }
 
-fn color_from_str(value: &str) -> Option<MemoColor> {
+fn color_from_str(value: &str) -> Option<NoteColor> {
     match value {
-        "red" => Some(MemoColor::Red),
-        "orange" => Some(MemoColor::Orange),
-        "yellow" => Some(MemoColor::Yellow),
-        "green" => Some(MemoColor::Green),
-        "cyan" => Some(MemoColor::Cyan),
-        "blue" => Some(MemoColor::Blue),
-        "gray" => Some(MemoColor::Gray),
+        "red" => Some(NoteColor::Red),
+        "orange" => Some(NoteColor::Orange),
+        "yellow" => Some(NoteColor::Yellow),
+        "green" => Some(NoteColor::Green),
+        "cyan" => Some(NoteColor::Cyan),
+        "blue" => Some(NoteColor::Blue),
+        "gray" => Some(NoteColor::Gray),
         _ => None,
     }
 }
 
-fn tag_path_prefixes(path: &str) -> Vec<String> {
-    let segments: Vec<&str> = path.split('/').collect();
-    (1..=segments.len())
-        .map(|end| segments[..end].join("/"))
-        .collect()
-}
-
 mod persistence;
 mod repository;
 mod schema;
diff --git a/app/flowix-core/src/memo_file/index_store/persistence.rs b/app/flowix-core/src/memo_file/index_store/persistence.rs
index 8416c7ee5..ea14abd80 100644
--- a/app/flowix-core/src/memo_file/index_store/persistence.rs
+++ b/app/flowix-core/src/memo_file/index_store/persistence.rs
@@ -29,9 +29,9 @@ impl MemoFile {
         tx.execute(
             r#"
             INSERT INTO memos
-                (id, notebook_id, filename, relative_path, preview, thumbnail, thumbnail_checked, agents_checked, created_at, updated_at, favorited, icon, properties)
-            VALUES (?1, ?2, ?3, ?4, ?5, ?6, 1, 1, ?7, ?8, ?9, ?10, ?11)
-            ON CONFLICT(id) DO UPDATE SET
+                (notebook_id, filename, relative_path, preview, thumbnail, thumbnail_checked, agents_checked, created_at, updated_at, favorited, icon, properties)
+            VALUES (?1, ?2, ?3, ?4, ?5, 1, 1, ?6, ?7, ?8, ?9, ?10)
+            ON CONFLICT(relative_path) DO UPDATE SET
                 notebook_id = excluded.notebook_id,
                 filename = excluded.filename,
                 relative_path = excluded.relative_path,
@@ -46,7 +46,6 @@ impl MemoFile {
                 properties = excluded.properties
             "#,
             params![
-                entry.id,
                 notebook_id,
                 entry.filename,
                 entry.relative_path,
@@ -65,93 +64,24 @@ impl MemoFile {
 
     fn replace_entry_children_in_tx(
         tx: &rusqlite::Transaction<'_>,
-        notebook_id: &str,
+        _notebook_id: &str,
         entry: &MemoIndexEntry,
     ) -> std::io::Result<()> {
-        // Todo metadata is user-visible state kept in the local index. Read it
-        // before deleting the derived rows so a content refresh can preserve
-        // priority/owner/assignee and timestamps.
-        let existing_todos = Self::read_existing_todo_metadata_in_tx(tx, &entry.id)?;
-
-        tx.execute(
-            "DELETE FROM memo_tags WHERE memo_id = ?1",
-            params![entry.id],
-        )
-        .map_err(sqlite_to_io)?;
-        tx.execute(
-            "DELETE FROM memo_colors WHERE memo_id = ?1",
-            params![entry.id],
-        )
-        .map_err(sqlite_to_io)?;
         tx.execute(
-            "DELETE FROM memo_todos WHERE memo_id = ?1",
-            params![entry.id],
+            "DELETE FROM memo_colors WHERE relative_path = ?1",
+            params![entry.relative_path],
         )
         .map_err(sqlite_to_io)?;
         tx.execute(
-            "DELETE FROM memo_agents WHERE memo_id = ?1",
-            params![entry.id],
+            "DELETE FROM memo_agents WHERE relative_path = ?1",
+            params![entry.relative_path],
         )
         .map_err(sqlite_to_io)?;
 
-        for tag in &entry.tags {
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_tags (memo_id, tag) VALUES (?1, ?2)",
-                params![entry.id, tag],
-            )
-            .map_err(sqlite_to_io)?;
-            let now = chrono::Utc::now().timestamp_millis();
-            for prefix in tag_path_prefixes(tag) {
-                tx.execute(
-                    "INSERT OR IGNORE INTO notebook_tags
-                        (notebook_id, path, created_at, updated_at)
-                     VALUES (?1, ?2, ?3, ?3)",
-                    params![notebook_id, prefix, now],
-                )
-                .map_err(sqlite_to_io)?;
-            }
-        }
         for (position, color) in entry.colors.iter().enumerate() {
             tx.execute(
-                "INSERT OR REPLACE INTO memo_colors (memo_id, color, position) VALUES (?1, ?2, ?3)",
-                params![entry.id, color_to_str(*color), position as i64],
-            )
-            .map_err(sqlite_to_io)?;
-        }
-        let now = chrono::Utc::now().timestamp_millis();
-
-        for (position, todo) in entry.todos.iter().enumerate() {
-            let existing = existing_todos
-                .iter()
-                .find(|entry| entry.content == todo.content);
-            let created_at = existing
-                .map(|entry| entry.created_at)
-                .filter(|value| *value > 0)
-                .unwrap_or(entry.created_at);
-            let updated_at = existing
-                .filter(|entry| entry.status == todo.status)
-                .map(|entry| entry.updated_at)
-                .filter(|value| *value > 0)
-                .unwrap_or(now);
-            tx.execute(
-                r#"
-                INSERT OR REPLACE INTO memo_todos
-                    (memo_id, todo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at, position)
-                VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)
-                "#,
-                params![
-                    entry.id,
-                    if todo.id.is_empty() { format!("todo-{}", position) } else { todo.id.clone() },
-                    todo.content,
-                    todo.status,
-                    existing.map(|entry| entry.priority.as_str()).unwrap_or(""),
-                    existing.map(|entry| entry.time_range.as_str()).unwrap_or(""),
-                    existing.map(|entry| entry.owner.as_str()).unwrap_or(""),
-                    existing.map(|entry| entry.assignee.as_str()).unwrap_or(""),
-                    created_at,
-                    updated_at,
-                    position as i64,
-                ],
+                "INSERT OR REPLACE INTO memo_colors (relative_path, color, position) VALUES (?1, ?2, ?3)",
+                params![entry.relative_path, color_to_str(*color), position as i64],
             )
             .map_err(sqlite_to_io)?;
         }
@@ -159,11 +89,11 @@ impl MemoFile {
             tx.execute(
                 r#"
                 INSERT OR REPLACE INTO memo_agents
-                    (memo_id, thread_id, title, agent_type, position)
+                    (relative_path, thread_id, title, agent_type, position)
                 VALUES (?1, ?2, ?3, ?4, ?5)
                 "#,
                 params![
-                    entry.id,
+                    entry.relative_path,
                     agent.thread_id,
                     agent.title,
                     agent.agent_type,
@@ -175,38 +105,6 @@ impl MemoFile {
         Ok(())
     }
 
-    fn read_existing_todo_metadata_in_tx(
-        tx: &rusqlite::Transaction<'_>,
-        memo_id: &str,
-    ) -> std::io::Result<Vec<MemoTodoEntry>> {
-        let mut stmt = tx
-            .prepare(
-                r#"
-                SELECT todo_id, content, status, memo_id, priority, time_range, owner, assignee, created_at, updated_at
-                FROM memo_todos
-                WHERE memo_id = ?1
-                "#,
-            )
-            .map_err(sqlite_to_io)?;
-        let rows = stmt
-            .query_map(params![memo_id], |row| {
-                Ok(MemoTodoEntry {
-                    todo_id: row.get(0)?,
-                    content: row.get(1)?,
-                    status: row.get(2)?,
-                    memo_id: row.get(3)?,
-                    priority: row.get(4)?,
-                    time_range: row.get(5)?,
-                    owner: row.get(6)?,
-                    assignee: row.get(7)?,
-                    created_at: row.get(8)?,
-                    updated_at: row.get(9)?,
-                })
-            })
-            .map_err(sqlite_to_io)?;
-        rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)
-    }
-
     pub(super) fn read_index_from_db(
         &self,
         conn: &Connection,
@@ -227,7 +125,7 @@ impl MemoFile {
         let mut stmt = conn
             .prepare(
                 r#"
-                SELECT id, filename, relative_path, preview, thumbnail, created_at, updated_at, favorited, icon, properties
+                SELECT filename, relative_path, preview, thumbnail, created_at, updated_at, favorited, icon, properties
                 FROM memos
                 WHERE notebook_id = ?1
                 ORDER BY created_at ASC, rowid ASC
@@ -236,23 +134,21 @@ impl MemoFile {
             .map_err(sqlite_to_io)?;
         let rows = stmt
             .query_map(params![notebook_id], |row| {
-                let id: String = row.get(0)?;
                 Ok(MemoIndexEntry {
-                    id,
-                    filename: row.get(1)?,
-                    relative_path: row.get(2)?,
-                    preview: row.get(3)?,
-                    thumbnail: row.get(4)?,
+                    filename: row.get(0)?,
+                    relative_path: row.get(1)?,
+                    preview: row.get(2)?,
+                    thumbnail: row.get(3)?,
                     tags: Vec::new(),
                     todos: Vec::new(),
                     agents: Vec::new(),
-                    created_at: row.get(5)?,
-                    updated_at: row.get(6)?,
-                    favorited: row.get::<_, i64>(7)? != 0,
-                    icon: row.get(8)?,
+                    created_at: row.get(4)?,
+                    updated_at: row.get(5)?,
+                    favorited: row.get::<_, i64>(6)? != 0,
+                    icon: row.get(7)?,
                     colors: Vec::new(),
                     properties: serde_json::from_str::<serde_json::Value>(
-                        &row.get::<_, String>(9)?,
+                        &row.get::<_, String>(8)?,
                     )
                     .unwrap_or_else(|_| serde_json::json!({})),
                 })
@@ -261,10 +157,8 @@ impl MemoFile {
         let mut memos = rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?;
 
         for entry in &mut memos {
-            entry.tags = self.read_entry_tags(conn, &entry.id)?;
-            entry.colors = self.read_entry_colors(conn, &entry.id)?;
-            entry.todos = self.read_entry_todos(conn, &entry.id)?;
-            entry.agents = self.read_entry_agents(conn, &entry.id)?;
+            entry.colors = self.read_entry_colors(conn, &entry.relative_path)?;
+            entry.agents = self.read_entry_agents(conn, &entry.relative_path)?;
         }
         let memo_base = self.memo_base_for_notebook_id(notebook_id);
         self.backfill_missing_properties(conn, notebook_id, &memo_base, &mut memos)?;
@@ -334,11 +228,11 @@ impl MemoFile {
             }
 
             conn.execute(
-                "UPDATE memos SET properties = ?1 WHERE notebook_id = ?2 AND id = ?3",
+                "UPDATE memos SET properties = ?1 WHERE notebook_id = ?2 AND relative_path = ?3",
                 params![
                     serde_json::to_string(&properties).unwrap_or_else(|_| "{}".to_string()),
                     notebook_id,
-                    entry.id,
+                    entry.relative_path,
                 ],
             )
             .map_err(sqlite_to_io)?;
@@ -358,8 +252,8 @@ impl MemoFile {
             if entry.thumbnail.as_deref().unwrap_or("").trim().is_empty() {
                 let checked = conn
                     .query_row(
-                        "SELECT thumbnail_checked FROM memos WHERE notebook_id = ?1 AND id = ?2",
-                        params![notebook_id, entry.id],
+                        "SELECT thumbnail_checked FROM memos WHERE notebook_id = ?1 AND relative_path = ?2",
+                        params![notebook_id, entry.relative_path],
                         |row| row.get::<_, i64>(0),
                     )
                     .optional()
@@ -379,8 +273,8 @@ impl MemoFile {
                 .and_then(|content| extract_thumbnail(&content));
 
             conn.execute(
-                "UPDATE memos SET thumbnail = ?1, thumbnail_checked = 1 WHERE notebook_id = ?2 AND id = ?3",
-                params![thumbnail, notebook_id, entry.id],
+                "UPDATE memos SET thumbnail = ?1, thumbnail_checked = 1 WHERE notebook_id = ?2 AND relative_path = ?3",
+                params![thumbnail, notebook_id, entry.relative_path],
             )
             .map_err(sqlite_to_io)?;
             entry.thumbnail = thumbnail;
@@ -402,8 +296,8 @@ impl MemoFile {
 
             let checked = conn
                 .query_row(
-                    "SELECT agents_checked FROM memos WHERE notebook_id = ?1 AND id = ?2",
-                    params![notebook_id, entry.id],
+                    "SELECT agents_checked FROM memos WHERE notebook_id = ?1 AND relative_path = ?2",
+                    params![notebook_id, entry.relative_path],
                     |row| row.get::<_, i64>(0),
                 )
                 .optional()
@@ -422,19 +316,19 @@ impl MemoFile {
 
             let tx = conn.unchecked_transaction().map_err(sqlite_to_io)?;
             tx.execute(
-                "DELETE FROM memo_agents WHERE memo_id = ?1",
-                params![entry.id],
+                "DELETE FROM memo_agents WHERE relative_path = ?1",
+                params![entry.relative_path],
             )
             .map_err(sqlite_to_io)?;
             for (position, agent) in agents.iter().enumerate() {
                 tx.execute(
                     r#"
                     INSERT OR REPLACE INTO memo_agents
-                        (memo_id, thread_id, title, agent_type, position)
+                        (relative_path, thread_id, title, agent_type, position)
                     VALUES (?1, ?2, ?3, ?4, ?5)
                     "#,
                     params![
-                        entry.id,
+                        entry.relative_path,
                         agent.thread_id,
                         agent.title,
                         agent.agent_type,
@@ -444,8 +338,8 @@ impl MemoFile {
                 .map_err(sqlite_to_io)?;
             }
             tx.execute(
-                "UPDATE memos SET agents_checked = 1 WHERE notebook_id = ?1 AND id = ?2",
-                params![notebook_id, entry.id],
+                "UPDATE memos SET agents_checked = 1 WHERE notebook_id = ?1 AND relative_path = ?2",
+                params![notebook_id, entry.relative_path],
             )
             .map_err(sqlite_to_io)?;
             tx.commit().map_err(sqlite_to_io)?;
@@ -454,30 +348,16 @@ impl MemoFile {
         Ok(())
     }
 
-    pub(super) fn read_entry_tags(
-        &self,
-        conn: &Connection,
-        memo_id: &str,
-    ) -> std::io::Result<Vec<String>> {
-        let mut stmt = conn
-            .prepare("SELECT tag FROM memo_tags WHERE memo_id = ?1 ORDER BY rowid ASC")
-            .map_err(sqlite_to_io)?;
-        let rows = stmt
-            .query_map(params![memo_id], |row| row.get(0))
-            .map_err(sqlite_to_io)?;
-        rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)
-    }
-
     pub(super) fn read_entry_colors(
         &self,
         conn: &Connection,
-        memo_id: &str,
-    ) -> std::io::Result<Vec<MemoColor>> {
+        relative_path: &str,
+    ) -> std::io::Result<Vec<NoteColor>> {
         let mut stmt = conn
-            .prepare("SELECT color FROM memo_colors WHERE memo_id = ?1 ORDER BY position ASC")
+            .prepare("SELECT color FROM memo_colors WHERE relative_path = ?1 ORDER BY position ASC")
             .map_err(sqlite_to_io)?;
         let rows = stmt
-            .query_map(params![memo_id], |row| row.get::<_, String>(0))
+            .query_map(params![relative_path], |row| row.get::<_, String>(0))
             .map_err(sqlite_to_io)?;
         Ok(rows
             .collect::<Result<Vec<_>, _>>()
@@ -487,40 +367,18 @@ impl MemoFile {
             .collect())
     }
 
-    pub(super) fn read_entry_todos(
-        &self,
-        conn: &Connection,
-        memo_id: &str,
-    ) -> std::io::Result<Vec<TodoItem>> {
-        let mut stmt = conn
-            .prepare(
-                "SELECT todo_id, content, status FROM memo_todos WHERE memo_id = ?1 ORDER BY position ASC",
-            )
-            .map_err(sqlite_to_io)?;
-        let rows = stmt
-            .query_map(params![memo_id], |row| {
-                Ok(TodoItem {
-                    id: row.get(0)?,
-                    content: row.get(1)?,
-                    status: row.get(2)?,
-                })
-            })
-            .map_err(sqlite_to_io)?;
-        rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)
-    }
-
     pub(super) fn read_entry_agents(
         &self,
         conn: &Connection,
-        memo_id: &str,
+        relative_path: &str,
     ) -> std::io::Result<Vec<AgentThreadItem>> {
         let mut stmt = conn
             .prepare(
-                "SELECT thread_id, title, agent_type FROM memo_agents WHERE memo_id = ?1 ORDER BY position ASC",
+                "SELECT thread_id, title, agent_type FROM memo_agents WHERE relative_path = ?1 ORDER BY position ASC",
             )
             .map_err(sqlite_to_io)?;
         let rows = stmt
-            .query_map(params![memo_id], |row| {
+            .query_map(params![relative_path], |row| {
                 Ok(AgentThreadItem {
                     thread_id: row.get(0)?,
                     title: row.get(1)?,
diff --git a/app/flowix-core/src/memo_file/index_store/repository.rs b/app/flowix-core/src/memo_file/index_store/repository.rs
index 74ed1fe87..09a058191 100644
--- a/app/flowix-core/src/memo_file/index_store/repository.rs
+++ b/app/flowix-core/src/memo_file/index_store/repository.rs
@@ -1,5 +1,3 @@
-use std::collections::HashMap;
-
 use super::*;
 
 impl MemoFile {
@@ -8,43 +6,11 @@ impl MemoFile {
         notebook_id: &str,
         parent: Option<&str>,
     ) -> std::io::Result<Vec<String>> {
-        if self.note_index_is_ready(notebook_id)? {
-            return self.note_occupied_filenames(notebook_id, parent);
+        if !self.note_index_is_ready(notebook_id)? {
+            self.reconcile_note_index_blocking(notebook_id)?;
         }
-        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let mut stmt = conn
-            .prepare(
-                "SELECT filename FROM memos WHERE notebook_id = ?1 AND \
-             CASE WHEN relative_path = filename THEN '' \
-             ELSE substr(relative_path, 1, length(relative_path) - length(filename) - 1) END = ?2",
-            )
-            .map_err(sqlite_to_io)?;
-        let rows = stmt
-            .query_map(params![notebook_id, parent.unwrap_or("")], |row| row.get(0))
-            .map_err(sqlite_to_io)?;
-        rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)
+        self.note_occupied_filenames(notebook_id, parent)
     }
-    /// Read every notebook's memo count from its notebook-local index.
-    pub fn memo_counts_by_notebook(&self) -> std::io::Result<HashMap<String, usize>> {
-        let mut counts = HashMap::new();
-        for notebook in self.read_notebook_configs()? {
-            if self.note_index_is_ready(&notebook.id)? {
-                counts.insert(notebook.id.clone(), self.note_count(&notebook.id)?);
-                continue;
-            }
-            let conn = self.open_memo_index_db_for_notebook_id(&notebook.id)?;
-            let count: i64 = conn
-                .query_row(
-                    "SELECT COUNT(*) FROM memos WHERE notebook_id = ?1",
-                    params![notebook.id],
-                    |row| row.get(0),
-                )
-                .map_err(sqlite_to_io)?;
-            counts.insert(notebook.id, usize::try_from(count).unwrap_or(0));
-        }
-        Ok(counts)
-    }
-
     pub fn read_index(&self) -> Option<MemoIndexFile> {
         let notebook_id = self.current_notebook_id_for_index();
         if let Ok(Some(cached)) = self.current_cached_index(&notebook_id) {
@@ -82,14 +48,19 @@ impl MemoFile {
         self.read_index_from_db(&conn, &notebook_id)
     }
 
-    pub fn resolve_memo_location(&self, memo_id: &str) -> std::io::Result<Option<MemoLocation>> {
-        for notebook_config in self.read_notebook_configs()? {
-            let conn = self.open_memo_index_db_for_notebook_id(&notebook_config.id)?;
-            let row = conn
+    pub fn resolve_note_location_for_notebook_id(
+        &self,
+        notebook_id: &str,
+        relative_path: &str,
+    ) -> std::io::Result<Option<MemoLocation>> {
+        let notebook_config = self.get_notebook_config_by_id(notebook_id).ok_or_else(|| {
+            std::io::Error::new(std::io::ErrorKind::NotFound, format!("notebook not found: {notebook_id}"))
+        })?;
+        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
+        let row = conn
                 .query_row(
                     r#"
                 SELECT
-                    m.id,
                     m.filename,
                     m.relative_path,
                     m.preview,
@@ -108,42 +79,40 @@ impl MemoFile {
                     n.updated_at
                 FROM memos m
                 JOIN notebooks n ON n.id = m.notebook_id
-                WHERE m.id = ?1
+                WHERE m.notebook_id = ?1 AND m.relative_path = ?2
                 LIMIT 1
                 "#,
-                    params![memo_id],
+                    params![notebook_id, relative_path],
                     |row| {
-                        let memo_id: String = row.get(0)?;
-                        let is_default: i64 = row.get(14)?;
+                        let is_default: i64 = row.get(13)?;
                         Ok((
                             MemoIndexEntry {
-                                id: memo_id,
-                                filename: row.get(1)?,
-                                relative_path: row.get(2)?,
-                                preview: row.get(3)?,
-                                thumbnail: row.get(4)?,
+                                filename: row.get(0)?,
+                                relative_path: row.get(1)?,
+                                preview: row.get(2)?,
+                                thumbnail: row.get(3)?,
                                 tags: Vec::new(),
                                 todos: Vec::new(),
                                 agents: Vec::new(),
-                                created_at: row.get(5)?,
-                                updated_at: row.get(6)?,
-                                favorited: row.get::<_, i64>(7)? != 0,
-                                icon: row.get(8)?,
+                                created_at: row.get(4)?,
+                                updated_at: row.get(5)?,
+                                favorited: row.get::<_, i64>(6)? != 0,
+                                icon: row.get(7)?,
                                 colors: Vec::new(),
                                 properties: serde_json::from_str::<serde_json::Value>(
-                                    &row.get::<_, String>(9)?,
+                                    &row.get::<_, String>(8)?,
                                 )
                                 .unwrap_or_else(|_| serde_json::json!({})),
                             },
                             NotebookConfig {
-                                id: row.get(10)?,
-                                name: row.get(11)?,
-                                icon: row.get(12)?,
-                                path: row.get(13)?,
+                                id: notebook_config.id.clone(),
+                                name: notebook_config.name.clone(),
+                                icon: notebook_config.icon.clone(),
+                                path: notebook_config.path.clone(),
                                 is_default: is_default != 0,
-                                sort: 0,
-                                created_at: row.get(15)?,
-                                updated_at: row.get(16)?,
+                                sort: notebook_config.sort,
+                                created_at: notebook_config.created_at,
+                                updated_at: notebook_config.updated_at,
                             },
                         ))
                     },
@@ -151,13 +120,11 @@ impl MemoFile {
                 .optional()
                 .map_err(sqlite_to_io)?;
 
-            let Some((mut memo, notebook)) = row else {
-                continue;
-            };
-            memo.tags = self.read_entry_tags(&conn, &memo.id)?;
-            memo.colors = self.read_entry_colors(&conn, &memo.id)?;
-            memo.todos = self.read_entry_todos(&conn, &memo.id)?;
-            memo.agents = self.read_entry_agents(&conn, &memo.id)?;
+        let Some((mut memo, notebook)) = row else {
+            return Ok(None);
+        };
+            memo.colors = self.read_entry_colors(&conn, &memo.relative_path)?;
+            memo.agents = self.read_entry_agents(&conn, &memo.relative_path)?;
             self.backfill_missing_properties(
                 &conn,
                 &notebook.id,
@@ -177,10 +144,7 @@ impl MemoFile {
                 std::slice::from_mut(&mut memo),
             )?;
 
-            return Ok(Some(MemoLocation { memo, notebook }));
-        }
-
-        Ok(None)
+        Ok(Some(MemoLocation { memo, notebook }))
     }
 
     pub fn read_index_result(&self) -> std::io::Result<Option<MemoIndexFile>> {
@@ -216,7 +180,6 @@ impl MemoFile {
 
     pub fn memo_to_index_entry(memo: &Memo) -> MemoIndexEntry {
         MemoIndexEntry {
-            id: memo.id.clone(),
             filename: memo.filename.clone(),
             relative_path: memo.relative_path.clone(),
             preview: memo.preview.clone(),
@@ -235,7 +198,6 @@ impl MemoFile {
 
     pub fn index_entry_to_memo(entry: &MemoIndexEntry) -> Memo {
         Memo {
-            id: entry.id.clone(),
             filename: entry.filename.clone(),
             relative_path: entry.relative_path.clone(),
             preview: entry.preview.clone(),
@@ -267,28 +229,19 @@ impl MemoFile {
         notebook_id: &str,
         memo: &Memo,
     ) -> std::io::Result<()> {
-        self.sync_index_on_write_for_notebook_id_locked_inner(notebook_id, memo, true)
-    }
-
-    pub(crate) fn sync_index_on_write_for_notebook_id_locked_without_projection(
-        &self,
-        notebook_id: &str,
-        memo: &Memo,
-    ) -> std::io::Result<()> {
-        self.sync_index_on_write_for_notebook_id_locked_inner(notebook_id, memo, false)
+        self.sync_index_on_write_for_notebook_id_locked_inner(notebook_id, memo)
     }
 
     fn sync_index_on_write_for_notebook_id_locked_inner(
         &self,
         notebook_id: &str,
         memo: &Memo,
-        refresh_projection: bool,
     ) -> std::io::Result<()> {
         let mut conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
         let old_path: Option<String> = conn
             .query_row(
-                "SELECT relative_path FROM memos WHERE notebook_id = ?1 AND id = ?2",
-                params![notebook_id, memo.id],
+                "SELECT relative_path FROM memos WHERE notebook_id = ?1 AND relative_path = ?2",
+                params![notebook_id, memo.relative_path],
                 |row| row.get(0),
             )
             .optional()
@@ -305,17 +258,15 @@ impl MemoFile {
             updated_at,
         )?;
         tx.commit().map_err(sqlite_to_io)?;
-        if refresh_projection {
-            if let Some(path) = old_path.filter(|path| path != &memo.relative_path) {
-                self.refresh_note_path(notebook_id, &path)?;
-            }
-            self.refresh_note_path(notebook_id, &memo.relative_path)?;
+        if let Some(path) = old_path.filter(|path| path != &memo.relative_path) {
+            self.refresh_note_path(notebook_id, &path)?;
         }
+        self.refresh_note_path(notebook_id, &memo.relative_path)?;
         if self.current_notebook_id_for_index() == notebook_id {
             let mut cache = self.index_cache.write().expect("index_cache poisoned");
             if let Some(index) = cache.as_mut() {
                 let entry = Self::memo_to_index_entry(memo);
-                if let Some(existing) = index.memos.iter_mut().find(|item| item.id == memo.id) {
+                if let Some(existing) = index.memos.iter_mut().find(|item| item.relative_path == memo.relative_path) {
                     *existing = entry;
                 } else {
                     index.memos.push(entry);
@@ -334,26 +285,26 @@ impl MemoFile {
         self.sync_index_on_write(memo)
     }
 
-    pub fn sync_index_on_delete(&self, memo_id: &str) -> std::io::Result<()> {
+    pub fn sync_index_on_delete(&self, relative_path: &str) -> std::io::Result<()> {
         let _guard = self.current_index_io.lock().expect("index_io poisoned");
-        self.sync_index_on_delete_locked(memo_id)
+        self.sync_index_on_delete_locked(relative_path)
     }
 
-    pub fn sync_index_on_delete_locked(&self, memo_id: &str) -> std::io::Result<()> {
+    pub fn sync_index_on_delete_locked(&self, relative_path: &str) -> std::io::Result<()> {
         let notebook_id = self.current_notebook_id_for_index();
-        self.sync_index_on_delete_for_notebook_id_locked(&notebook_id, memo_id)
+        self.sync_index_on_delete_for_notebook_id_locked(&notebook_id, relative_path)
     }
 
     pub fn sync_index_on_delete_for_notebook_id_locked(
         &self,
         notebook_id: &str,
-        memo_id: &str,
+        relative_path: &str,
     ) -> std::io::Result<()> {
         let mut conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
         let old_path: Option<String> = conn
             .query_row(
-                "SELECT relative_path FROM memos WHERE notebook_id = ?1 AND id = ?2",
-                params![notebook_id, memo_id],
+                "SELECT relative_path FROM memos WHERE notebook_id = ?1 AND relative_path = ?2",
+                params![notebook_id, relative_path],
                 |row| row.get(0),
             )
             .optional()
@@ -362,8 +313,8 @@ impl MemoFile {
             .transaction_with_behavior(TransactionBehavior::Immediate)
             .map_err(sqlite_to_io)?;
         tx.execute(
-            "DELETE FROM memos WHERE notebook_id = ?1 AND id = ?2",
-            params![notebook_id, memo_id],
+            "DELETE FROM memos WHERE notebook_id = ?1 AND relative_path = ?2",
+            params![notebook_id, relative_path],
         )
         .map_err(sqlite_to_io)?;
         self.mark_index_state(
diff --git a/app/flowix-core/src/memo_file/index_store/schema.rs b/app/flowix-core/src/memo_file/index_store/schema.rs
index e33fc28ec..610fcf102 100644
--- a/app/flowix-core/src/memo_file/index_store/schema.rs
+++ b/app/flowix-core/src/memo_file/index_store/schema.rs
@@ -1,20 +1,4 @@
 use super::*;
-use std::sync::{LazyLock, Mutex};
-
-static MEMO_RELATIVE_PATH_MIGRATION_LOCK: LazyLock<Mutex<()>> = LazyLock::new(|| Mutex::new(()));
-
-/// Legacy global indexes predate several optional tables and columns.
-/// Importing from an absent source is a no-op, not an error; anything else
-/// still fails.
-fn tolerate_missing_legacy_table(error: std::io::Error) -> std::io::Result<usize> {
-    if error.to_string().contains("no such table")
-        || error.to_string().contains("no such column")
-    {
-        Ok(0)
-    } else {
-        Err(error)
-    }
-}
 
 impl MemoFile {
     pub fn storage_title_from_filename(filename: &str) -> String {
@@ -53,6 +37,51 @@ impl MemoFile {
     }
 
     fn ensure_memo_tables(&self, conn: &Connection) -> std::io::Result<()> {
+        // Remove retired ID-backed state even if an earlier upgrade already
+        // replaced `memos.id` but left these tables behind.
+        let (has_legacy_id, has_retired_id_tables): (bool, bool) = conn
+            .query_row(
+                "SELECT
+                    EXISTS(SELECT 1 FROM pragma_table_info('memos') WHERE name = 'id')
+                        OR EXISTS(SELECT 1 FROM pragma_table_info('memo_agents') WHERE name = 'memo_id')
+                        OR EXISTS(SELECT 1 FROM pragma_table_info('memo_colors') WHERE name = 'memo_id'),
+                    EXISTS(
+                        SELECT 1 FROM sqlite_master
+                        WHERE type = 'table'
+                          AND name IN (
+                              'memo_content_revisions',
+                              'pending_external_memo_creates',
+                              'memo_lifecycles',
+                              'schema_migrations'
+                          )
+                    )",
+                [],
+                |row| Ok((row.get(0)?, row.get(1)?)),
+            )
+            .map_err(sqlite_to_io)?;
+        if has_retired_id_tables {
+            conn.execute_batch(
+                "DROP TABLE IF EXISTS memo_content_revisions;
+                 DROP TABLE IF EXISTS pending_external_memo_creates;
+                 DROP TABLE IF EXISTS memo_lifecycles;
+                 DROP TABLE IF EXISTS schema_migrations;",
+            )
+            .map_err(sqlite_to_io)?;
+        }
+
+        // Rebuild the older cache if any of its tables still use memo IDs.
+        // Markdown remains the source of truth for every dropped projection.
+        if has_legacy_id {
+            conn.execute_batch(
+                "DROP TABLE IF EXISTS memo_todos;
+                 DROP TABLE IF EXISTS memo_tags;
+                 DROP TABLE IF EXISTS memo_agents;
+                 DROP TABLE IF EXISTS memo_colors;
+                 DROP TABLE IF EXISTS memos;
+                 DROP TABLE IF EXISTS memo_index_state;",
+            )
+            .map_err(sqlite_to_io)?;
+        }
         conn.execute_batch(
             r#"
             PRAGMA foreign_keys = ON;
@@ -79,12 +108,7 @@ impl MemoFile {
                 completed_at INTEGER NOT NULL,
                 PRIMARY KEY(notebook_id, migration_key)
             );
-            CREATE TABLE IF NOT EXISTS schema_migrations (
-                migration_key TEXT PRIMARY KEY,
-                completed_at INTEGER NOT NULL
-            );
             CREATE TABLE IF NOT EXISTS memos (
-                id TEXT PRIMARY KEY,
                 notebook_id TEXT NOT NULL,
                 filename TEXT NOT NULL,
                 relative_path TEXT NOT NULL,
@@ -97,47 +121,13 @@ impl MemoFile {
                 favorited INTEGER NOT NULL,
                 icon TEXT,
                 properties TEXT NOT NULL DEFAULT '{}',
-                FOREIGN KEY(notebook_id) REFERENCES notebooks(id) ON DELETE CASCADE,
-                UNIQUE(notebook_id, relative_path)
+                PRIMARY KEY(relative_path),
+                FOREIGN KEY(notebook_id) REFERENCES notebooks(id) ON DELETE CASCADE
             );
             CREATE INDEX IF NOT EXISTS idx_memos_notebook_created
                 ON memos(notebook_id, created_at DESC);
             CREATE INDEX IF NOT EXISTS idx_memos_notebook_updated
                 ON memos(notebook_id, updated_at DESC);
-            CREATE TABLE IF NOT EXISTS pending_external_memo_creates (
-                memo_id TEXT PRIMARY KEY,
-                notebook_id TEXT NOT NULL,
-                created_at INTEGER NOT NULL
-            );
-            CREATE TABLE IF NOT EXISTS memo_lifecycles (
-                memo_id TEXT PRIMARY KEY,
-                notebook_id TEXT NOT NULL,
-                relative_path TEXT NOT NULL DEFAULT '',
-                generation INTEGER NOT NULL DEFAULT 1,
-                is_deleted INTEGER NOT NULL DEFAULT 0 CHECK(is_deleted IN (0, 1)),
-                created_at INTEGER NOT NULL,
-                updated_at INTEGER NOT NULL,
-                deleted_at INTEGER
-            );
-            CREATE INDEX IF NOT EXISTS idx_memo_lifecycles_notebook
-                ON memo_lifecycles(notebook_id, is_deleted);
-            CREATE TABLE IF NOT EXISTS memo_content_revisions (
-                memo_id TEXT PRIMARY KEY,
-                notebook_id TEXT NOT NULL,
-                content_hash TEXT NOT NULL,
-                local_revision INTEGER NOT NULL,
-                change_id TEXT NOT NULL,
-                updated_at INTEGER NOT NULL,
-                FOREIGN KEY(memo_id) REFERENCES memo_lifecycles(memo_id) ON DELETE RESTRICT
-            );
-            CREATE INDEX IF NOT EXISTS idx_memo_content_revisions_notebook
-                ON memo_content_revisions(notebook_id);
-            CREATE TABLE IF NOT EXISTS memo_tags (
-                memo_id TEXT NOT NULL,
-                tag TEXT NOT NULL,
-                PRIMARY KEY(memo_id, tag),
-                FOREIGN KEY(memo_id) REFERENCES memos(id) ON DELETE CASCADE
-            );
             CREATE TABLE IF NOT EXISTS notebook_tags (
                 notebook_id TEXT NOT NULL,
                 path TEXT NOT NULL,
@@ -148,651 +138,36 @@ impl MemoFile {
             );
             CREATE INDEX IF NOT EXISTS idx_notebook_tags_notebook
                 ON notebook_tags(notebook_id);
-            CREATE TRIGGER IF NOT EXISTS trg_memo_tags_register_notebook_tag
-            AFTER INSERT ON memo_tags
-            BEGIN
-                INSERT OR IGNORE INTO notebook_tags
-                    (notebook_id, path, created_at, updated_at)
-                SELECT
-                    m.notebook_id,
-                    NEW.tag,
-                    CAST(strftime('%s', 'now') AS INTEGER) * 1000,
-                    CAST(strftime('%s', 'now') AS INTEGER) * 1000
-                FROM memos m
-                WHERE m.id = NEW.memo_id;
-            END;
             CREATE TABLE IF NOT EXISTS memo_colors (
-                memo_id TEXT NOT NULL,
+                relative_path TEXT NOT NULL,
                 color TEXT NOT NULL,
                 position INTEGER NOT NULL,
-                PRIMARY KEY(memo_id, color),
-                FOREIGN KEY(memo_id) REFERENCES memos(id) ON DELETE CASCADE
-            );
-            CREATE TABLE IF NOT EXISTS memo_todos (
-                memo_id TEXT NOT NULL,
-                todo_id TEXT NOT NULL DEFAULT '',
-                content TEXT NOT NULL,
-                status TEXT NOT NULL,
-                priority TEXT NOT NULL DEFAULT '',
-                time_range TEXT NOT NULL DEFAULT '',
-                owner TEXT NOT NULL DEFAULT '',
-                assignee TEXT NOT NULL DEFAULT '',
-                created_at INTEGER NOT NULL DEFAULT 0,
-                updated_at INTEGER NOT NULL DEFAULT 0,
-                position INTEGER NOT NULL,
-                PRIMARY KEY(memo_id, todo_id),
-                FOREIGN KEY(memo_id) REFERENCES memos(id) ON DELETE CASCADE
+                PRIMARY KEY(relative_path, color),
+                FOREIGN KEY(relative_path) REFERENCES memos(relative_path) ON DELETE CASCADE
             );
             CREATE TABLE IF NOT EXISTS memo_agents (
-                memo_id TEXT NOT NULL,
+                relative_path TEXT NOT NULL,
                 thread_id TEXT NOT NULL,
                 title TEXT NOT NULL DEFAULT '',
                 agent_type TEXT NOT NULL DEFAULT '',
                 position INTEGER NOT NULL,
-                PRIMARY KEY(memo_id, thread_id),
-                FOREIGN KEY(memo_id) REFERENCES memos(id) ON DELETE CASCADE
+                PRIMARY KEY(relative_path, thread_id),
+                FOREIGN KEY(relative_path) REFERENCES memos(relative_path) ON DELETE CASCADE
             );
-            CREATE INDEX IF NOT EXISTS idx_memo_agents_memo_id
-                ON memo_agents(memo_id);
+            CREATE INDEX IF NOT EXISTS idx_memo_agents_relative_path
+                ON memo_agents(relative_path);
             "#,
         )
         .map_err(sqlite_to_io)?;
-        self.migrate_memo_relative_paths(conn)?;
-        self.migrate_memo_todo_ids(conn)?;
-        self.migrate_memo_lifecycles(conn)?;
         conn.execute_batch(
-            r#"
-            INSERT OR IGNORE INTO notebook_tags
-                (notebook_id, path, created_at, updated_at)
-            SELECT DISTINCT
-                m.notebook_id,
-                mt.tag,
-                CAST(strftime('%s', 'now') AS INTEGER) * 1000,
-                CAST(strftime('%s', 'now') AS INTEGER) * 1000
-            FROM memo_tags mt
-            JOIN memos m ON m.id = mt.memo_id
-            WHERE NOT EXISTS (
-                SELECT 1
-                FROM schema_migrations
-                WHERE migration_key = 'notebook_tags_v1'
-            );
-
-            INSERT OR IGNORE INTO schema_migrations (migration_key, completed_at)
-            VALUES (
-                'notebook_tags_v1',
-                CAST(strftime('%s', 'now') AS INTEGER) * 1000
-            );
-            "#,
+            "DROP TRIGGER IF EXISTS trg_memo_tags_register_notebook_tag; \
+             DROP TABLE IF EXISTS memo_tags; \
+             DROP TABLE IF EXISTS memo_todos;",
         )
         .map_err(sqlite_to_io)?;
         Ok(())
     }
 
-    /// Upgrade the v3 index where filename was the notebook-relative
-    /// location. Keep filename as the basename and make relative_path the
-    /// durable location identity so same-named notes can coexist in folders.
-    fn migrate_memo_relative_paths(&self, conn: &Connection) -> std::io::Result<()> {
-        // Multiple MemoFile instances can open the same index during startup.
-        // The per-instance RMW mutex cannot protect schema setup, so combine a
-        // process-wide guard with SQLite's write transaction. The second
-        // connection re-checks the marker after it acquires the database lock.
-        let _migration_guard = MEMO_RELATIVE_PATH_MIGRATION_LOCK
-            .lock()
-            .expect("memo migration lock poisoned");
-
-        // Existing installations have the old UNIQUE(notebook_id, filename)
-        // constraint, which cannot be dropped in place. Rebuild the metadata
-        // table while preserving child tables and memo ids. SQLite DDL is
-        // transactional, so a crash must leave either the old or new schema.
-        conn.execute_batch("PRAGMA foreign_keys = OFF; BEGIN IMMEDIATE;")
-            .map_err(sqlite_to_io)?;
-        let result = (|| -> std::io::Result<()> {
-            let done: Option<String> = conn
-                .query_row(
-                    "SELECT migration_key FROM schema_migrations WHERE migration_key = 'memo_relative_paths_v1'",
-                    [],
-                    |row| row.get(0),
-                )
-                .optional()
-                .map_err(sqlite_to_io)?;
-            if done.is_some() {
-                return Ok(());
-            }
-
-            let has_relative_path = conn
-                .prepare("PRAGMA table_info(memos)")
-                .and_then(|mut statement| {
-                    let rows = statement.query_map([], |row| row.get::<_, String>(1))?;
-                    rows.collect::<Result<Vec<_>, _>>()
-                })
-                .map_err(sqlite_to_io)?
-                .into_iter()
-                .any(|name| name == "relative_path");
-
-            let recovery_table_exists: bool = conn
-                .query_row(
-                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memos_relative_paths_v1')",
-                    [],
-                    |row| row.get(0),
-                )
-                .map_err(sqlite_to_io)?;
-
-            // Recover databases left by the earlier non-transactional
-            // migration. It could copy every memo into the replacement table
-            // and leave the live table empty without writing the marker.
-            if has_relative_path {
-                if recovery_table_exists {
-                    let live_count: i64 = conn
-                        .query_row("SELECT COUNT(*) FROM memos", [], |row| row.get(0))
-                        .map_err(sqlite_to_io)?;
-                    let recovery_count: i64 = conn
-                        .query_row("SELECT COUNT(*) FROM memos_relative_paths_v1", [], |row| {
-                            row.get(0)
-                        })
-                        .map_err(sqlite_to_io)?;
-                    if live_count == 0 && recovery_count > 0 {
-                        conn.execute_batch(
-                            r#"
-                            DROP TRIGGER IF EXISTS trg_memo_tags_register_notebook_tag;
-                            DROP TABLE memos;
-                            ALTER TABLE memos_relative_paths_v1 RENAME TO memos;
-                            "#,
-                        )
-                        .map_err(sqlite_to_io)?;
-                    } else {
-                        conn.execute_batch("DROP TABLE memos_relative_paths_v1;")
-                            .map_err(sqlite_to_io)?;
-                    }
-                }
-                Self::finish_memo_relative_path_migration(conn)?;
-                return Ok(());
-            }
-
-            conn.execute_batch("DROP TABLE IF EXISTS memos_relative_paths_v1;")
-                .map_err(sqlite_to_io)?;
-            conn.execute("ALTER TABLE memos ADD COLUMN relative_path TEXT", [])
-                .map_err(sqlite_to_io)?;
-            conn.execute_batch(
-                r#"
-                CREATE TABLE memos_relative_paths_v1 (
-                    id TEXT PRIMARY KEY,
-                    notebook_id TEXT NOT NULL,
-                    filename TEXT NOT NULL,
-                    relative_path TEXT NOT NULL,
-                    preview TEXT NOT NULL,
-                    thumbnail TEXT,
-                    thumbnail_checked INTEGER NOT NULL DEFAULT 0,
-                    agents_checked INTEGER NOT NULL DEFAULT 0,
-                    created_at INTEGER NOT NULL,
-                    updated_at INTEGER NOT NULL,
-                    favorited INTEGER NOT NULL,
-                    icon TEXT,
-                    properties TEXT NOT NULL DEFAULT '{}',
-                    FOREIGN KEY(notebook_id) REFERENCES notebooks(id) ON DELETE CASCADE,
-                    UNIQUE(notebook_id, relative_path)
-                );
-                INSERT INTO memos_relative_paths_v1
-                    (id, notebook_id, filename, relative_path, preview, thumbnail,
-                     thumbnail_checked, agents_checked, created_at, updated_at,
-                     favorited, icon, properties)
-                SELECT id, notebook_id, filename,
-                    COALESCE(NULLIF(relative_path, ''), filename),
-                    preview, thumbnail, thumbnail_checked, agents_checked,
-                    created_at, updated_at, favorited, icon, properties
-                FROM memos;
-                DROP TRIGGER IF EXISTS trg_memo_tags_register_notebook_tag;
-                DROP TABLE memos;
-                ALTER TABLE memos_relative_paths_v1 RENAME TO memos;
-                "#,
-            )
-            .map_err(sqlite_to_io)?;
-            Self::finish_memo_relative_path_migration(conn)?;
-            Ok(())
-        })();
-        let transaction = match result {
-            Ok(()) => conn.execute_batch("COMMIT;").map_err(sqlite_to_io),
-            Err(error) => {
-                let _ = conn.execute_batch("ROLLBACK;");
-                Err(error)
-            }
-        };
-        let restore = conn
-            .execute_batch("PRAGMA foreign_keys = ON;")
-            .map_err(sqlite_to_io);
-        transaction.and(restore)
-    }
-
-    fn finish_memo_relative_path_migration(conn: &Connection) -> std::io::Result<()> {
-        conn.execute_batch(
-            r#"
-            CREATE INDEX IF NOT EXISTS idx_memos_notebook_created
-                ON memos(notebook_id, created_at DESC);
-            CREATE INDEX IF NOT EXISTS idx_memos_notebook_updated
-                ON memos(notebook_id, updated_at DESC);
-            CREATE TRIGGER IF NOT EXISTS trg_memo_tags_register_notebook_tag
-            AFTER INSERT ON memo_tags
-            BEGIN
-                INSERT OR IGNORE INTO notebook_tags
-                    (notebook_id, path, created_at, updated_at)
-                SELECT
-                    m.notebook_id,
-                    NEW.tag,
-                    CAST(strftime('%s', 'now') AS INTEGER) * 1000,
-                    CAST(strftime('%s', 'now') AS INTEGER) * 1000
-                FROM memos m
-                WHERE m.id = NEW.memo_id;
-            END;
-            INSERT OR IGNORE INTO schema_migrations (migration_key, completed_at)
-            VALUES ('memo_relative_paths_v1', CAST(strftime('%s', 'now') AS INTEGER) * 1000);
-            UPDATE memo_index_state
-            SET version = version + 1,
-                last_updated = MAX(
-                    last_updated + 1,
-                    CAST(strftime('%s', 'now') AS INTEGER) * 1000
-                );
-            "#,
-        )
-        .map_err(sqlite_to_io)
-    }
-
-    /// Upgrade the original `(memo_id, content)` todo key. Content is mutable
-    /// and is not unique (two checklist rows may intentionally have the same
-    /// text), so the durable child key must be `(memo_id, todo_id)`.
-    fn migrate_memo_todo_ids(&self, conn: &Connection) -> std::io::Result<()> {
-        let columns = conn
-            .prepare("PRAGMA table_info(memo_todos)")
-            .and_then(|mut statement| {
-                let rows = statement.query_map([], |row| {
-                    Ok((row.get::<_, String>(1)?, row.get::<_, i64>(5)?))
-                })?;
-                rows.collect::<Result<Vec<_>, _>>()
-            })
-            .map_err(sqlite_to_io)?;
-        if columns.is_empty() {
-            return Ok(());
-        }
-        let has_todo_id = columns.iter().any(|(name, _)| name == "todo_id");
-        if !has_todo_id {
-            conn.execute(
-                "ALTER TABLE memo_todos ADD COLUMN todo_id TEXT NOT NULL DEFAULT ''",
-                [],
-            )
-            .map_err(sqlite_to_io)?;
-        }
-        let todo_id_is_primary_key = columns
-            .iter()
-            .any(|(name, primary_key)| name == "todo_id" && *primary_key > 0);
-        if todo_id_is_primary_key {
-            return Ok(());
-        }
-
-        conn.execute_batch("PRAGMA foreign_keys = OFF; BEGIN IMMEDIATE;")
-            .map_err(sqlite_to_io)?;
-        let result = (|| -> std::io::Result<()> {
-            conn.execute_batch(
-                r#"
-                DROP TABLE IF EXISTS memo_todos_v2;
-                CREATE TABLE memo_todos_v2 (
-                    memo_id TEXT NOT NULL,
-                    todo_id TEXT NOT NULL,
-                    content TEXT NOT NULL,
-                    status TEXT NOT NULL,
-                    priority TEXT NOT NULL DEFAULT '',
-                    time_range TEXT NOT NULL DEFAULT '',
-                    owner TEXT NOT NULL DEFAULT '',
-                    assignee TEXT NOT NULL DEFAULT '',
-                    created_at INTEGER NOT NULL DEFAULT 0,
-                    updated_at INTEGER NOT NULL DEFAULT 0,
-                    position INTEGER NOT NULL,
-                    PRIMARY KEY(memo_id, todo_id),
-                    FOREIGN KEY(memo_id) REFERENCES memos(id) ON DELETE CASCADE
-                );
-                "#,
-            )
-            .map_err(sqlite_to_io)?;
-            let mut statement = conn
-                .prepare(
-                    "SELECT rowid, memo_id, todo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at, position FROM memo_todos ORDER BY memo_id, position, rowid",
-                )
-                .map_err(sqlite_to_io)?;
-            let rows = statement
-                .query_map([], |row| {
-                    Ok((
-                        row.get::<_, i64>(0)?,
-                        row.get::<_, String>(1)?,
-                        row.get::<_, String>(2)?,
-                        row.get::<_, String>(3)?,
-                        row.get::<_, String>(4)?,
-                        row.get::<_, String>(5)?,
-                        row.get::<_, String>(6)?,
-                        row.get::<_, String>(7)?,
-                        row.get::<_, String>(8)?,
-                        row.get::<_, i64>(9)?,
-                        row.get::<_, i64>(10)?,
-                        row.get::<_, i64>(11)?,
-                    ))
-                })
-                .map_err(sqlite_to_io)?;
-            let rows = rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?;
-            drop(statement);
-            for (
-                rowid,
-                memo_id,
-                _legacy_todo_id,
-                content,
-                status,
-                priority,
-                time_range,
-                owner,
-                assignee,
-                created_at,
-                updated_at,
-                position,
-            ) in rows
-            {
-                // rowid is only used for migrating legacy rows. New and
-                // imported rows receive their marker-derived id before they
-                // reach this table.
-                let todo_id = format!("todo-legacy-{rowid}");
-                conn.execute(
-                    r#"INSERT INTO memo_todos_v2
-                       (memo_id, todo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at, position)
-                       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)"#,
-                    params![memo_id, todo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at, position],
-                )
-                .map_err(sqlite_to_io)?;
-            }
-            conn.execute_batch(
-                "DROP TABLE memo_todos; ALTER TABLE memo_todos_v2 RENAME TO memo_todos; CREATE INDEX IF NOT EXISTS idx_memo_todos_memo_id ON memo_todos(memo_id);",
-            )
-            .map_err(sqlite_to_io)?;
-            Ok(())
-        })();
-        let transaction = match result {
-            Ok(()) => conn.execute_batch("COMMIT;").map_err(sqlite_to_io),
-            Err(error) => {
-                let _ = conn.execute_batch("ROLLBACK;");
-                Err(error)
-            }
-        };
-        let restore = conn
-            .execute_batch("PRAGMA foreign_keys = ON;")
-            .map_err(sqlite_to_io);
-        transaction.and(restore)
-    }
-
-    /// Keep revisions after a memo row is deleted, but make their owner an
-    /// explicit lifecycle record. This gives revision history a real foreign
-    /// key without cascading away the state needed to publish a tombstone.
-    fn migrate_memo_lifecycles(&self, conn: &Connection) -> std::io::Result<()> {
-        let has_fk = conn
-            .prepare("PRAGMA foreign_key_list(memo_content_revisions)")
-            .and_then(|mut statement| {
-                let rows = statement.query_map([], |row| row.get::<_, String>(2))?;
-                rows.collect::<Result<Vec<_>, _>>()
-            })
-            .map_err(sqlite_to_io)?
-            .into_iter()
-            .any(|table| table == "memo_lifecycles");
-
-        conn.execute_batch(
-            r#"
-            INSERT OR IGNORE INTO memo_lifecycles
-                (memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at)
-            SELECT id, notebook_id, relative_path, 1, 0, created_at, updated_at FROM memos;
-            INSERT OR IGNORE INTO memo_lifecycles
-                (memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at)
-            SELECT memo_id, notebook_id, '', 1, 1, updated_at, updated_at
-            FROM memo_content_revisions;
-            "#,
-        )
-        .map_err(sqlite_to_io)?;
-        if has_fk {
-            return Ok(());
-        }
-
-        conn.execute_batch("PRAGMA foreign_keys = OFF; BEGIN IMMEDIATE;")
-            .map_err(sqlite_to_io)?;
-        let result = (|| -> std::io::Result<()> {
-            conn.execute_batch(
-                r#"
-                CREATE TABLE memo_content_revisions_v2 (
-                    memo_id TEXT PRIMARY KEY,
-                    notebook_id TEXT NOT NULL,
-                    content_hash TEXT NOT NULL,
-                    local_revision INTEGER NOT NULL,
-                    change_id TEXT NOT NULL,
-                    updated_at INTEGER NOT NULL,
-                    FOREIGN KEY(memo_id) REFERENCES memo_lifecycles(memo_id) ON DELETE RESTRICT
-                );
-                INSERT INTO memo_content_revisions_v2
-                    (memo_id, notebook_id, content_hash, local_revision, change_id, updated_at)
-                SELECT memo_id, notebook_id, content_hash, local_revision, change_id, updated_at
-                FROM memo_content_revisions;
-                DROP TABLE memo_content_revisions;
-                ALTER TABLE memo_content_revisions_v2 RENAME TO memo_content_revisions;
-                CREATE INDEX IF NOT EXISTS idx_memo_content_revisions_notebook
-                    ON memo_content_revisions(notebook_id);
-                "#,
-            )
-            .map_err(sqlite_to_io)
-        })();
-        let transaction = match result {
-            Ok(()) => conn.execute_batch("COMMIT;").map_err(sqlite_to_io),
-            Err(error) => {
-                let _ = conn.execute_batch("ROLLBACK;");
-                Err(error)
-            }
-        };
-        let restore = conn
-            .execute_batch("PRAGMA foreign_keys = ON;")
-            .map_err(sqlite_to_io);
-        transaction.and(restore)
-    }
-
-    fn import_legacy_global_memo_index(
-        &self,
-        conn: &Connection,
-        notebook_id: &str,
-    ) -> std::io::Result<()> {
-        let already_imported: Option<String> = conn
-            .query_row(
-                "SELECT value FROM notebook_index_meta WHERE key = 'legacy_global_index_import_v1'",
-                [],
-                |row| row.get(0),
-            )
-            .optional()
-            .map_err(sqlite_to_io)?;
-        if already_imported.is_some() {
-            return Ok(());
-        }
-
-        let legacy_path = self.registry_db_path();
-        if !legacy_path.is_file() {
-            conn.execute(
-                "INSERT OR REPLACE INTO notebook_index_meta (key, value) VALUES ('legacy_global_index_import_v1', ?1)",
-                ["missing"],
-            )
-            .map_err(sqlite_to_io)?;
-            return Ok(());
-        }
-
-        let legacy = self.open_registry_db()?;
-        let has_memos: bool = legacy
-            .query_row(
-                "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memos')",
-                [],
-                |row| row.get(0),
-            )
-            .map_err(sqlite_to_io)?;
-        if !has_memos {
-            conn.execute(
-                "INSERT OR REPLACE INTO notebook_index_meta (key, value) VALUES ('legacy_global_index_import_v1', ?1)",
-                ["empty"],
-            )
-            .map_err(sqlite_to_io)?;
-            return Ok(());
-        }
-
-        let legacy_path_string = legacy_path.to_string_lossy().to_string();
-        conn.execute("ATTACH DATABASE ?1 AS legacy_index", [&legacy_path_string])
-            .map_err(sqlite_to_io)?;
-        // Pre-relative-path global indexes kept the notebook-relative location
-        // in `filename` and had no `relative_path` column; pre-todo-id todo
-        // tables had no stable `todo_id`. Detect both and adapt the import.
-        let legacy_has = |table: &str, column: &str| -> std::io::Result<bool> {
-            let count: i64 = conn.query_row(
-                "SELECT COUNT(*) FROM pragma_table_info(?1, 'legacy_index') WHERE name = ?2",
-                [table, column],
-                |row| row.get(0),
-            )
-            .map_err(sqlite_to_io)?;
-            Ok(count > 0)
-        };
-        let legacy_relative_path_expr = if legacy_has("memos", "relative_path")? {
-            "relative_path"
-        } else {
-            "filename"
-        };
-        let legacy_todo_id_expr = if legacy_has("memo_todos", "todo_id")? {
-            "mt.todo_id"
-        } else {
-            "'todo-legacy-' || mt.rowid"
-        };
-        let result = (|| -> std::io::Result<()> {
-            let tx = conn.unchecked_transaction().map_err(sqlite_to_io)?;
-
-            // Global indexes written before the lifecycle refactor predate the
-            // memo_lifecycles table. Skipping the import is safe: the primary
-            // copy stays valid and migrate_memo_lifecycles backfills lifecycle
-            // rows from the imported memos.
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_lifecycles
-                    (memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at, deleted_at)
-                 SELECT memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at, deleted_at
-                 FROM legacy_index.memo_lifecycles WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_lifecycles
-                    (memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at, deleted_at)
-                 SELECT memo_id, notebook_id, '', 1, 1, updated_at, updated_at, NULL
-                 FROM legacy_index.memo_content_revisions
-                 WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-                // Older global indexes did not have revisions yet. The
-                // primary copy remains valid when that optional table is absent.
-                .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                &format!(
-                    "INSERT OR IGNORE INTO memos
-                        (id, notebook_id, filename, relative_path, preview, thumbnail, thumbnail_checked, agents_checked, created_at, updated_at, favorited, icon, properties)
-                     SELECT id, notebook_id, filename, {legacy_relative_path_expr}, COALESCE(preview, ''), thumbnail, thumbnail_checked, agents_checked, created_at, updated_at, favorited, icon, COALESCE(properties, '{{}}')
-                     FROM legacy_index.memos WHERE notebook_id = ?1"
-                ),
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)?;
-            // The ensure_memo_tables lifecycle backfill ran before this import,
-            // so imported memos have no lifecycle rows yet. Backfill now: later
-            // revision imports reference these rows under FK RESTRICT.
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_lifecycles
-                    (memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at)
-                 SELECT id, notebook_id, relative_path, 1, 0, created_at, updated_at
-                 FROM memos WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_content_revisions
-                    (memo_id, notebook_id, content_hash, local_revision, change_id, updated_at)
-                 SELECT memo_id, notebook_id, content_hash, local_revision, change_id, updated_at
-                 FROM legacy_index.memo_content_revisions WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_tags (memo_id, tag)
-                 SELECT mt.memo_id, mt.tag FROM legacy_index.memo_tags mt
-                 JOIN legacy_index.memos m ON m.id = mt.memo_id
-                 WHERE m.notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_colors (memo_id, color, position)
-                 SELECT mc.memo_id, mc.color, mc.position FROM legacy_index.memo_colors mc
-                 JOIN legacy_index.memos m ON m.id = mc.memo_id
-                 WHERE m.notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                &format!(
-                    "INSERT OR IGNORE INTO memo_todos
-                        (memo_id, todo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at, position)
-                     SELECT mt.memo_id, {legacy_todo_id_expr}, mt.content, mt.status, mt.priority, mt.time_range, mt.owner, mt.assignee, mt.created_at, mt.updated_at, mt.position
-                     FROM legacy_index.memo_todos mt
-                     JOIN legacy_index.memos m ON m.id = mt.memo_id
-                     WHERE m.notebook_id = ?1"
-                ),
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_agents (memo_id, thread_id, title, agent_type, position)
-                 SELECT ma.memo_id, ma.thread_id, ma.title, ma.agent_type, ma.position
-                 FROM legacy_index.memo_agents ma
-                 JOIN legacy_index.memos m ON m.id = ma.memo_id
-                 WHERE m.notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO notebook_tags (notebook_id, path, created_at, updated_at)
-                 SELECT notebook_id, path, created_at, updated_at
-                 FROM legacy_index.notebook_tags WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO memo_index_state (notebook_id, version, last_updated, migrated_at)
-                 SELECT notebook_id, version, last_updated, migrated_at
-                 FROM legacy_index.memo_index_state WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR IGNORE INTO notebook_data_migrations (notebook_id, migration_key, version, completed_at)
-                 SELECT notebook_id, migration_key, version, completed_at
-                 FROM legacy_index.notebook_data_migrations WHERE notebook_id = ?1",
-                [notebook_id],
-            )
-            .map_err(sqlite_to_io)
-            .or_else(tolerate_missing_legacy_table)?;
-            tx.execute(
-                "INSERT OR REPLACE INTO notebook_index_meta (key, value) VALUES ('legacy_global_index_import_v1', ?1)",
-                ["complete"],
-            )
-            .map_err(sqlite_to_io)?;
-            tx.commit().map_err(sqlite_to_io)
-        })();
-        let detach = conn.execute_batch("DETACH DATABASE legacy_index;");
-        result.and(detach.map_err(sqlite_to_io))
-    }
-
     fn ensure_local_notebook_row(
         &self,
         conn: &Connection,
@@ -833,7 +208,6 @@ impl MemoFile {
         let conn = self.open_notebook_db(notebook_id)?;
         self.ensure_memo_tables(&conn)?;
         self.ensure_local_notebook_row(&conn, notebook_id)?;
-        self.import_legacy_global_memo_index(&conn, notebook_id)?;
         Ok(conn)
     }
 
@@ -842,327 +216,6 @@ impl MemoFile {
         self.open_memo_index_db_for_notebook_id(&notebook_id)
     }
 
-    /// Record an external-process create before its markdown file becomes visible.
-    /// The Desktop watcher consumes this marker when it observes the filesystem event.
-    pub fn mark_pending_external_memo_create(
-        &self,
-        memo_id: &str,
-        notebook_id: &str,
-    ) -> std::io::Result<()> {
-        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let now = chrono::Utc::now().timestamp_millis();
-        conn.execute(
-            "DELETE FROM pending_external_memo_creates WHERE created_at < ?1",
-            params![now - EXTERNAL_CREATE_MARKER_TTL_MS],
-        )
-        .map_err(sqlite_to_io)?;
-        conn.execute(
-            r#"
-            INSERT INTO pending_external_memo_creates (memo_id, notebook_id, created_at)
-            VALUES (?1, ?2, ?3)
-            ON CONFLICT(memo_id) DO UPDATE SET
-                notebook_id = excluded.notebook_id,
-                created_at = excluded.created_at
-            "#,
-            params![memo_id, notebook_id, now],
-        )
-        .map_err(sqlite_to_io)?;
-        Ok(())
-    }
-
-    /// Atomically claim an external create marker. A marker can produce at most one
-    /// `Created` event even when the platform reports several filesystem events.
-    pub fn consume_pending_external_memo_create(
-        &self,
-        memo_id: &str,
-        notebook_id: &str,
-    ) -> std::io::Result<bool> {
-        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let cutoff = chrono::Utc::now().timestamp_millis() - EXTERNAL_CREATE_MARKER_TTL_MS;
-        let changed = conn
-            .execute(
-                "DELETE FROM pending_external_memo_creates WHERE memo_id = ?1 AND notebook_id = ?2 AND created_at >= ?3",
-                params![memo_id, notebook_id, cutoff],
-            )
-            .map_err(sqlite_to_io)?;
-        Ok(changed > 0)
-    }
-
-    pub fn pending_external_memo_creates_for_notebook(
-        &self,
-        notebook_id: &str,
-    ) -> std::io::Result<std::collections::HashSet<String>> {
-        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let cutoff = chrono::Utc::now().timestamp_millis() - EXTERNAL_CREATE_MARKER_TTL_MS;
-        let mut statement = conn
-            .prepare(
-                "SELECT memo_id FROM pending_external_memo_creates WHERE notebook_id = ?1 AND created_at >= ?2",
-            )
-            .map_err(sqlite_to_io)?;
-        let rows = statement
-            .query_map(params![notebook_id, cutoff], |row| row.get::<_, String>(0))
-            .map_err(sqlite_to_io)?;
-        let mut memo_ids = std::collections::HashSet::new();
-        for row in rows {
-            memo_ids.insert(row.map_err(sqlite_to_io)?);
-        }
-        Ok(memo_ids)
-    }
-
-    pub fn has_pending_external_memo_create(
-        &self,
-        memo_id: &str,
-        notebook_id: &str,
-    ) -> std::io::Result<bool> {
-        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let cutoff = chrono::Utc::now().timestamp_millis() - EXTERNAL_CREATE_MARKER_TTL_MS;
-        conn.query_row(
-            "SELECT 1 FROM pending_external_memo_creates WHERE memo_id = ?1 AND notebook_id = ?2 AND created_at >= ?3",
-            params![memo_id, notebook_id, cutoff],
-            |_| Ok(()),
-        )
-        .optional()
-        .map(|row| row.is_some())
-        .map_err(sqlite_to_io)
-    }
-
-    pub fn clear_pending_external_memo_create(&self, memo_id: &str) -> std::io::Result<()> {
-        let conn = self.open_memo_index_db()?;
-        conn.execute(
-            "DELETE FROM pending_external_memo_creates WHERE memo_id = ?1",
-            params![memo_id],
-        )
-        .map_err(sqlite_to_io)?;
-        Ok(())
-    }
-
-    /// Atomically records a stable content revision for a memo.
-    ///
-    /// Re-observing identical bytes returns the existing revision/change id.
-    /// Returning to an older hash after another commit is a new transition and
-    /// therefore advances the counter as well.
-    pub fn commit_memo_content_revision(
-        &self,
-        memo_id: &str,
-        notebook_id: &str,
-        content_hash: &str,
-        next_change_id: &str,
-    ) -> std::io::Result<MemoContentCommit> {
-        self.commit_memo_content_revision_internal(
-            memo_id,
-            notebook_id,
-            content_hash,
-            next_change_id,
-            None,
-        )?
-        .ok_or_else(|| std::io::Error::other("unconditional revision commit was rejected"))
-    }
-
-    pub fn commit_memo_content_revision_if_current(
-        &self,
-        memo_id: &str,
-        notebook_id: &str,
-        content_hash: &str,
-        next_change_id: &str,
-        expected: Option<&MemoContentRevision>,
-    ) -> std::io::Result<Option<MemoContentCommit>> {
-        self.commit_memo_content_revision_internal(
-            memo_id,
-            notebook_id,
-            content_hash,
-            next_change_id,
-            Some(expected),
-        )
-    }
-
-    fn commit_memo_content_revision_internal(
-        &self,
-        memo_id: &str,
-        notebook_id: &str,
-        content_hash: &str,
-        next_change_id: &str,
-        expected: Option<Option<&MemoContentRevision>>,
-    ) -> std::io::Result<Option<MemoContentCommit>> {
-        let mut conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let tx = conn
-            .transaction_with_behavior(TransactionBehavior::Immediate)
-            .map_err(sqlite_to_io)?;
-        // Revision rows may be created before the corresponding Markdown file
-        // is indexed (for example while an external writer is committing a
-        // save). Keep the lifecycle anchor in the same local index so the FK
-        // remains valid without making the revision stream depend on a prior
-        // memo-list refresh.
-        tx.execute(
-            "INSERT OR IGNORE INTO memo_lifecycles
-                (memo_id, notebook_id, relative_path, generation, is_deleted, created_at, updated_at)
-             VALUES (?1, ?2, '', 1, 0, ?3, ?3)",
-            params![memo_id, notebook_id, chrono::Utc::now().timestamp_millis()],
-        )
-        .map_err(sqlite_to_io)?;
-        let current = tx
-            .query_row(
-                "SELECT content_hash, local_revision, change_id, updated_at
-                 FROM memo_content_revisions WHERE memo_id = ?1",
-                params![memo_id],
-                |row| {
-                    Ok((
-                        row.get::<_, String>(0)?,
-                        row.get::<_, i64>(1)?,
-                        row.get::<_, String>(2)?,
-                        row.get::<_, i64>(3)?,
-                    ))
-                },
-            )
-            .optional()
-            .map_err(sqlite_to_io)?;
-
-        if let Some(expected) = expected {
-            let matches = match (expected, current.as_ref()) {
-                (None, None) => true,
-                (Some(expected), Some((hash, revision, change_id, _))) => {
-                    expected.memo_id == memo_id
-                        && expected.content_hash == *hash
-                        && expected.revision == *revision
-                        && expected.change_id == *change_id
-                }
-                _ => false,
-            };
-            if !matches {
-                return Ok(None);
-            }
-        }
-
-        if let Some((existing_hash, revision, change_id, updated_at)) = current.as_ref() {
-            if existing_hash == content_hash {
-                tx.commit().map_err(sqlite_to_io)?;
-                return Ok(Some(MemoContentCommit {
-                    state: MemoContentRevision {
-                        memo_id: memo_id.to_string(),
-                        notebook_id: notebook_id.to_string(),
-                        content_hash: existing_hash.clone(),
-                        revision: *revision,
-                        change_id: change_id.clone(),
-                        updated_at: *updated_at,
-                    },
-                    changed: false,
-                }));
-            }
-        }
-
-        let revision = current
-            .as_ref()
-            .map(|(_, revision, _, _)| revision.saturating_add(1))
-            .unwrap_or(1);
-        let updated_at = chrono::Utc::now().timestamp_millis();
-        tx.execute(
-            r#"
-            INSERT INTO memo_content_revisions
-                (memo_id, notebook_id, content_hash, local_revision, change_id, updated_at)
-            VALUES (?1, ?2, ?3, ?4, ?5, ?6)
-            ON CONFLICT(memo_id) DO UPDATE SET
-                notebook_id = excluded.notebook_id,
-                content_hash = excluded.content_hash,
-                local_revision = excluded.local_revision,
-                change_id = excluded.change_id,
-                updated_at = excluded.updated_at
-            "#,
-            params![
-                memo_id,
-                notebook_id,
-                content_hash,
-                revision,
-                next_change_id,
-                updated_at,
-            ],
-        )
-        .map_err(sqlite_to_io)?;
-        tx.commit().map_err(sqlite_to_io)?;
-
-        Ok(Some(MemoContentCommit {
-            state: MemoContentRevision {
-                memo_id: memo_id.to_string(),
-                notebook_id: notebook_id.to_string(),
-                content_hash: content_hash.to_string(),
-                revision,
-                change_id: next_change_id.to_string(),
-                updated_at,
-            },
-            changed: true,
-        }))
-    }
-
-    pub fn read_memo_content_revision(
-        &self,
-        memo_id: &str,
-    ) -> std::io::Result<Option<MemoContentRevision>> {
-        for notebook in self.read_notebook_configs()? {
-            let revision = self.read_memo_content_revision_for_notebook(&notebook.id, memo_id)?;
-            if revision.is_some() {
-                return Ok(revision);
-            }
-        }
-        Ok(None)
-    }
-
-    /// Mutation callers already know the notebook. Avoid opening every local
-    /// database, especially for newly created notes with no revision yet.
-    pub fn read_memo_content_revision_for_notebook(
-        &self,
-        notebook_id: &str,
-        memo_id: &str,
-    ) -> std::io::Result<Option<MemoContentRevision>> {
-        let conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        conn.query_row(
-            "SELECT notebook_id, content_hash, local_revision, change_id, updated_at
-                     FROM memo_content_revisions WHERE memo_id = ?1 AND notebook_id = ?2",
-            params![memo_id, notebook_id],
-            |row| {
-                Ok(MemoContentRevision {
-                    memo_id: memo_id.to_string(),
-                    notebook_id: row.get(0)?,
-                    content_hash: row.get(1)?,
-                    revision: row.get(2)?,
-                    change_id: row.get(3)?,
-                    updated_at: row.get(4)?,
-                })
-            },
-        )
-        .optional()
-        .map_err(sqlite_to_io)
-    }
-
-    /// Backfill the path-keyed revision table from the legacy ID-keyed one.
-    /// Runs only when the legacy tables exist (they are never created here, so
-    /// path-only notebooks stay free of them). Idempotent: existing path-keyed
-    /// rows (which may already be newer after a rename cascade) always win.
-    fn backfill_note_content_revisions(conn: &Connection) -> std::io::Result<bool> {
-        let legacy_present: bool = conn
-            .query_row(
-                "SELECT COUNT(*) = 2 FROM sqlite_master
-                 WHERE type = 'table' AND name IN ('memo_content_revisions', 'memos')",
-                [],
-                |row| row.get(0),
-            )
-            .map_err(sqlite_to_io)?;
-        if !legacy_present {
-            return Ok(false);
-        }
-        let migrated = conn
-            .execute(
-                r#"
-            INSERT OR IGNORE INTO note_content_revisions
-                (notebook_id, relative_path, content_hash, local_revision, change_id, updated_at)
-            SELECT m.notebook_id, m.relative_path, r.content_hash, r.local_revision, r.change_id, r.updated_at
-            FROM memo_content_revisions r
-            JOIN memos m ON m.id = r.memo_id AND m.notebook_id = r.notebook_id
-            WHERE m.relative_path != ''
-            "#,
-                [],
-            )
-            .map_err(sqlite_to_io)?;
-        Ok(migrated > 0)
-    }
-
     /// Atomically records a stable content revision for one note, addressed by
     /// `(notebook_id, relative_path)`.
     ///
@@ -1212,7 +265,6 @@ impl MemoFile {
         expected: Option<Option<&NoteContentRevision>>,
     ) -> std::io::Result<Option<NoteContentCommit>> {
         let mut conn = self.open_note_index_connection(notebook_id)?;
-        Self::backfill_note_content_revisions(&conn)?;
         let tx = conn
             .transaction_with_behavior(TransactionBehavior::Immediate)
             .map_err(sqlite_to_io)?;
@@ -1315,7 +367,6 @@ impl MemoFile {
         relative_path: &str,
     ) -> std::io::Result<Option<NoteContentRevision>> {
         let conn = self.open_note_index_connection(notebook_id)?;
-        Self::backfill_note_content_revisions(&conn)?;
         conn.query_row(
             "SELECT content_hash, local_revision, change_id, updated_at
              FROM note_content_revisions WHERE notebook_id = ?1 AND relative_path = ?2",
@@ -1348,7 +399,6 @@ impl MemoFile {
             return Ok(());
         }
         let mut conn = self.open_note_index_connection(notebook_id)?;
-        Self::backfill_note_content_revisions(&conn)?;
         let tx = conn
             .transaction_with_behavior(TransactionBehavior::Immediate)
             .map_err(sqlite_to_io)?;
diff --git a/app/flowix-core/src/memo_file/index_store/tags.rs b/app/flowix-core/src/memo_file/index_store/tags.rs
index fe6e8740b..6a1d33888 100644
--- a/app/flowix-core/src/memo_file/index_store/tags.rs
+++ b/app/flowix-core/src/memo_file/index_store/tags.rs
@@ -19,65 +19,19 @@ impl MemoFile {
         notebook_id: Option<&str>,
     ) -> std::io::Result<Vec<String>> {
         let notebook_id = self.notebook_id_for_index(notebook_id);
-        let conn = self.open_memo_index_db_for_notebook_id(&notebook_id)?;
-        let mut stmt = conn
-            .prepare(
-                "SELECT path
-                 FROM notebook_tags
-                 WHERE notebook_id = ?1
-                 ORDER BY path COLLATE NOCASE ASC, path ASC",
-            )
-            .map_err(sqlite_to_io)?;
-        let rows = stmt
-            .query_map(params![notebook_id], |row| row.get::<_, String>(0))
-            .map_err(sqlite_to_io)?;
-        rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)
-    }
-
-    pub fn create_notebook_tag(&self, notebook_id: &str, path: &str) -> std::io::Result<String> {
-        let path = super::super::derivation::normalize_tag_path(path).ok_or_else(|| {
-            std::io::Error::new(
-                std::io::ErrorKind::InvalidInput,
-                format!("invalid tag path: {path}"),
-            )
-        })?;
-        if self.get_notebook_config_by_id(notebook_id).is_none() {
-            return Err(std::io::Error::new(
-                std::io::ErrorKind::NotFound,
-                format!("notebook not found: {notebook_id}"),
-            ));
-        }
-        let mut conn = self.open_memo_index_db_for_notebook_id(notebook_id)?;
-        let now = chrono::Utc::now().timestamp_millis();
-        let exists = conn
-            .query_row(
-                "SELECT 1 FROM notebook_tags
-                 WHERE notebook_id = ?1 AND path = ?2
-                 LIMIT 1",
-                params![notebook_id, path],
-                |_| Ok(true),
-            )
-            .optional()
-            .map_err(sqlite_to_io)?
-            .unwrap_or(false);
-        if exists {
-            return Err(std::io::Error::new(
-                std::io::ErrorKind::AlreadyExists,
-                format!("tag already exists in notebook: {path}"),
-            ));
-        }
-        let tx = conn.transaction().map_err(sqlite_to_io)?;
-        for prefix in tag_path_prefixes(&path) {
-            tx.execute(
-                "INSERT OR IGNORE INTO notebook_tags
-                    (notebook_id, path, created_at, updated_at)
-                 VALUES (?1, ?2, ?3, ?3)",
-                params![notebook_id, prefix, now],
-            )
-            .map_err(sqlite_to_io)?;
+        let used = self.read_used_tag_ids_for_notebook_id(Some(&notebook_id))?;
+        let mut paths = std::collections::BTreeSet::new();
+        for tag in used {
+            let mut prefix = String::new();
+            for segment in tag.split('/') {
+                if !prefix.is_empty() {
+                    prefix.push('/');
+                }
+                prefix.push_str(segment);
+                paths.insert(prefix.clone());
+            }
         }
-        tx.commit().map_err(sqlite_to_io)?;
-        Ok(path)
+        Ok(paths.into_iter().collect())
     }
 
     pub fn read_used_tag_ids_for_notebook_id(
@@ -98,27 +52,24 @@ impl MemoFile {
     ) -> std::io::Result<TagUsageSummary> {
         let notebook_id = self.notebook_id_for_index(notebook_id);
         if !self.note_index_is_ready(&notebook_id)? {
-            // Cold start: rebuild the rebuildable projection instead of
-            // reading the legacy ID-keyed cache. The summary is an active
-            // request, so wait for the maintenance lock rather than skipping.
-            let _ = self.reconcile_note_index_blocking(&notebook_id);
+            return Err(std::io::Error::new(std::io::ErrorKind::WouldBlock, "Note index is not ready"));
         }
         self.note_tag_usage_summary(&notebook_id)
     }
 
 
-    /// 路径式 tag 的 prefix → 去重 memo 数。每个真实 tag `T` 拆出
+    /// 路径式 tag 的 prefix → 去重笔记数。每个真实 tag `T` 拆出
     /// 所有前缀 (`T` 自身 + `T` 的每级祖先 fullPath), 然后每个 prefix
-    /// 收集所有"挂载了 T 的 memo id", 取 set 长度 (即有任意 tag
-    /// 落在 prefix 之下的 distinct memo 数)。
+    /// 收集所有"挂载了 T 的笔记路径", 取 set 长度 (即有任意 tag
+    /// 落在 prefix 之下的不同笔记数)。
     ///
-    /// **为什么需要**: 之前侧栏 tree 用 `tagCounts` 累加, 一个 memo
+    /// **为什么需要**: 之前侧栏 tree 用 `tagCounts` 累加, 一篇笔记
     /// 既有 `#中国/湖南` 又有 `#中国/广东` 会被 `中国` 节点算两次。
-    /// 现在用 distinct memo_id, 1 个 memo 即使挂了多个子 tag, 父节点
+    /// 现在按 distinct note path 去重；1 篇笔记即使挂了多个子 tag，父节点
     /// 也只算 1。
     ///
-    /// O(N×L) where N = (tag, memo) pairs, L = 平均路径深度。典型
-    /// 库 (10K memos × 3 tags × depth 2) ~ 60K HashMap insert, 远低于
+    /// O(N×L) where N = (tag, note) pairs, L = 平均路径深度。典型
+    /// 库 (10K notes × 3 tags × depth 2) ~ 60K HashMap insert, 远低于
     /// 1ms, 不需要 SQL 聚合优化。
     pub fn read_tag_prefix_counts_for_notebook_id(
         &self,
@@ -127,27 +78,10 @@ impl MemoFile {
         use std::collections::{HashMap, HashSet};
 
         let notebook_id = self.notebook_id_for_index(notebook_id);
-        let pairs: Vec<(String, String)> = if self.note_index_is_ready(&notebook_id)? {
-            self.note_tag_path_pairs(&notebook_id)?
-        } else {
-            let conn = self.open_memo_index_db_for_notebook_id(&notebook_id)?;
-            let mut stmt = conn
-                .prepare(
-                    "SELECT mt.tag, mt.memo_id
-                 FROM memo_tags mt
-                 JOIN memos m ON m.id = mt.memo_id
-                 WHERE m.notebook_id = ?1",
-                )
-                .map_err(sqlite_to_io)?;
-            let collected = stmt
-                .query_map(rusqlite::params![&notebook_id], |row| {
-                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
-                })
-                .map_err(sqlite_to_io)?
-                .collect::<Result<Vec<_>, _>>()
-                .map_err(sqlite_to_io)?;
-            collected
-        };
+        if !self.note_index_is_ready(&notebook_id)? {
+            return Err(std::io::Error::new(std::io::ErrorKind::WouldBlock, "Note index is not ready"));
+        }
+        let pairs = self.note_tag_path_pairs(&notebook_id)?;
 
         let mut prefix_to_memos: HashMap<String, HashSet<String>> = HashMap::new();
         for (tag, note_key) in &pairs {
diff --git a/app/flowix-core/src/memo_file/internal_migration.rs b/app/flowix-core/src/memo_file/internal_migration.rs
index 55b7afd9e..98576efb8 100644
--- a/app/flowix-core/src/memo_file/internal_migration.rs
+++ b/app/flowix-core/src/memo_file/internal_migration.rs
@@ -29,6 +29,29 @@ impl NotebookInternalMigrationReport {
 }
 
 impl MemoFile {
+    /// Whether a registered notebook still has the old plugin artifact paths.
+    /// New notebooks use `.flowix/plugin` from creation and do not need this
+    /// migration.
+    pub fn has_legacy_notebook_internal_data(&self, notebook_id: &str) -> io::Result<bool> {
+        let base = self
+            .get_notebook_config_by_id(notebook_id)
+            .map(|config| PathBuf::from(config.path))
+            .ok_or_else(|| {
+                io::Error::new(
+                    io::ErrorKind::NotFound,
+                    format!("notebook not found: {notebook_id}"),
+                )
+            })?;
+        if !base.is_dir() {
+            return Err(io::Error::new(
+                io::ErrorKind::NotFound,
+                format!("notebook directory missing: {}", base.display()),
+            ));
+        }
+        Ok(has_legacy_content(&base.join(".plugin-output"))?
+            || has_legacy_content(&base.join(".flowix/artifacts"))?)
+    }
+
     /// Move legacy notebook-local data to `.flowix/`.
     ///
     /// This method is safe to call on every notebook open/switch. The marker
@@ -108,6 +131,18 @@ impl MemoFile {
     }
 }
 
+fn has_legacy_content(path: &Path) -> io::Result<bool> {
+    let metadata = match fs::symlink_metadata(path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(false),
+        Err(error) => return Err(error),
+    };
+    if metadata.file_type().is_symlink() || !metadata.is_dir() {
+        return Ok(true);
+    }
+    Ok(fs::read_dir(path)?.next().is_some())
+}
+
 fn migrate_legacy_artifacts(
     source: &Path,
     plugin_root: &Path,
diff --git a/app/flowix-core/src/memo_file/local_migrations.rs b/app/flowix-core/src/memo_file/local_migrations.rs
new file mode 100644
index 000000000..993f6cd50
--- /dev/null
+++ b/app/flowix-core/src/memo_file/local_migrations.rs
@@ -0,0 +1,61 @@
+//! Shared device-local migration journal. Both historical journal layouts are accepted.
+use rusqlite::Connection;
+use std::io;
+
+pub fn initialize_local_migration_table(conn: &mut Connection) -> io::Result<()> {
+    let columns = {
+        let mut statement = conn
+            .prepare("PRAGMA table_info(local_migrations)")
+            .map_err(io::Error::other)?;
+        let rows = statement
+            .query_map([], |row| row.get::<_, String>(1))
+            .map_err(io::Error::other)?;
+        rows.collect::<Result<Vec<_>, _>>()
+            .map_err(io::Error::other)?
+    };
+    if columns.is_empty() {
+        conn.execute_batch("CREATE TABLE local_migrations (migration_key TEXT PRIMARY KEY, completed_at INTEGER NOT NULL DEFAULT 0);").map_err(io::Error::other)?;
+    } else if columns.iter().any(|name| name == "key")
+        && !columns.iter().any(|name| name == "migration_key")
+    {
+        let tx = conn.transaction().map_err(io::Error::other)?;
+        tx.execute_batch("ALTER TABLE local_migrations RENAME TO local_migrations_old;
+            CREATE TABLE local_migrations (migration_key TEXT PRIMARY KEY, completed_at INTEGER NOT NULL DEFAULT 0);
+            INSERT INTO local_migrations (migration_key, completed_at) SELECT key, 0 FROM local_migrations_old;
+            DROP TABLE local_migrations_old;").map_err(io::Error::other)?;
+        tx.commit().map_err(io::Error::other)?;
+    } else if !columns.iter().any(|name| name == "migration_key")
+        || !columns.iter().any(|name| name == "completed_at")
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "unsupported local_migrations schema",
+        ));
+    }
+    Ok(())
+}
+
+/// Notebook jobs shared by execution and startup pending detection.
+#[derive(Clone, Copy)]
+pub enum NotebookInitializationJob {
+    ResetLegacyStorage,
+    InitializeSchema,
+    MigrateMediaResourceIdentity,
+}
+
+impl NotebookInitializationJob {
+    pub const ALL: [Self; 3] = [
+        Self::ResetLegacyStorage,
+        Self::InitializeSchema,
+        Self::MigrateMediaResourceIdentity,
+    ];
+
+    pub fn key(self, notebook_id: &str) -> String {
+        let prefix = match self {
+            Self::ResetLegacyStorage => "storage_reset_v1",
+            Self::InitializeSchema => "storage_schema_v1",
+            Self::MigrateMediaResourceIdentity => "media_resource_identity_v1",
+        };
+        format!("{prefix}:notebook:{notebook_id}")
+    }
+}
diff --git a/app/flowix-core/src/memo_file/media_resource.rs b/app/flowix-core/src/memo_file/media_resource.rs
index ad3f95d6a..ac2d8b5c4 100644
--- a/app/flowix-core/src/memo_file/media_resource.rs
+++ b/app/flowix-core/src/memo_file/media_resource.rs
@@ -3,7 +3,7 @@
 //! Media files remain on disk, while their user properties and resource
 //! identity are stored in the notebook-local database at
 //! `<notebook>/.flowix/notebook.db`. It is deliberately separate from the
-//! global notebook registry database (`~/.flowix/index.db`).
+//! global notebook registry database (`~/.flowix/db/local.db`).
 
 use std::collections::{HashMap, HashSet};
 use std::fs;
@@ -64,6 +64,28 @@ struct MediaResourceRecord {
 
 const MEDIA_MISSING_RETENTION_MS: i64 = 30 * 24 * 60 * 60 * 1000;
 
+/// Normalize a notebook-relative media path and derive its stable resource ID.
+/// The path is deliberately part of identity: a rename produces a new ID.
+pub fn media_resource_id(notebook_id: &str, relative_path: &str) -> std::io::Result<String> {
+    let normalized = normalize_media_relative_path(relative_path)?;
+    if notebook_id.is_empty() || notebook_id.contains("::") || notebook_id.contains('\0') {
+        return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, "invalid notebook id"));
+    }
+    Ok(format!("{notebook_id}::{normalized}"))
+}
+
+fn normalize_media_relative_path(relative_path: &str) -> std::io::Result<String> {
+    let normalized = relative_path.replace('\\', "/");
+    if normalized.is_empty()
+        || normalized.starts_with('/')
+        || normalized.contains('\0')
+        || normalized.split('/').any(|part| part.is_empty() || part == "." || part == "..")
+    {
+        return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, "invalid media relative path"));
+    }
+    Ok(normalized)
+}
+
 fn now_ms() -> i64 {
     chrono::Utc::now().timestamp_millis()
 }
@@ -158,6 +180,35 @@ pub fn media_kind_for_path(path: &Path) -> Option<MediaResourceKind> {
 
 impl MemoFile {
     pub(crate) fn open_notebook_db(&self, notebook_id: &str) -> std::io::Result<Connection> {
+        self.open_notebook_db_inner(notebook_id, false)
+    }
+
+    /// Upgrade the notebook media catalog during version initialization.
+    pub fn initialize_media_resource_schema(&self, notebook_id: &str) -> std::io::Result<()> {
+        self.open_notebook_db_inner(notebook_id, true)?;
+        Ok(())
+    }
+
+    fn open_notebook_db_inner(
+        &self,
+        notebook_id: &str,
+        run_legacy_migrations: bool,
+    ) -> std::io::Result<Connection> {
+        let path = self.notebook_db_path(notebook_id)?;
+        if run_legacy_migrations {
+            super::with_database_rebuild(&path, || {
+                self.open_notebook_db_unchecked(notebook_id, true)
+            })
+        } else {
+            self.open_notebook_db_unchecked(notebook_id, false)
+        }
+    }
+
+    fn open_notebook_db_unchecked(
+        &self,
+        notebook_id: &str,
+        run_legacy_migrations: bool,
+    ) -> std::io::Result<Connection> {
         let path = self.notebook_db_path(notebook_id)?;
         let mut conn = Connection::open(path).map_err(sqlite_to_io)?;
         conn.busy_timeout(std::time::Duration::from_secs(10))
@@ -196,6 +247,9 @@ impl MemoFile {
             "#,
         )
         .map_err(sqlite_to_io)?;
+        if !run_legacy_migrations {
+            return Ok(conn);
+        }
         let tx = conn
             .transaction_with_behavior(TransactionBehavior::Immediate)
             .map_err(sqlite_to_io)?;
@@ -406,6 +460,8 @@ impl MemoFile {
         kind: MediaResourceKind,
         absolute_path: &Path,
     ) -> std::io::Result<MediaResource> {
+        let relative_path = normalize_media_relative_path(relative_path)?;
+        let id = media_resource_id(notebook_id, &relative_path)?;
         let metadata = fs::metadata(absolute_path)?;
         if !metadata.is_file() {
             return Err(std::io::Error::new(
@@ -427,10 +483,10 @@ impl MemoFile {
             .optional()
             .map_err(sqlite_to_io)?
             .is_none();
-        let mut existing = self.read_media_resource_record(notebook_id, relative_path)?;
+        let mut existing = self.read_media_resource_record(notebook_id, &relative_path)?;
 
-        // Preserve the resource id and its database properties when a file was
-        // renamed outside Flowix. Only associate an old row when its previous
+        // Preserve database properties when a file was renamed outside Flowix.
+        // Only associate an old row when its previous
         // media path is gone and the fingerprint is unique; identical copies
         // must not steal one another's metadata.
         if existing.is_none() {
@@ -456,20 +512,16 @@ impl MemoFile {
                     .map_err(std::io::Error::other)?;
                 if !old_absolute.is_file() {
                     conn.execute(
-                        "UPDATE media_resources SET relative_path = ?1, updated_at = ?2,
+                        "UPDATE media_resources SET id = ?1, relative_path = ?2, updated_at = ?3,
                              missing_since = NULL, deleted_at = NULL
-                         WHERE notebook_id = ?3 AND id = ?4",
-                        params![relative_path, now_ms(), notebook_id, candidate_id],
+                         WHERE notebook_id = ?4 AND id = ?5",
+                        params![id, relative_path, now_ms(), notebook_id, candidate_id],
                     )
                     .map_err(sqlite_to_io)?;
-                    existing = self.read_media_resource_record(notebook_id, relative_path)?;
+                    existing = self.read_media_resource_record(notebook_id, &relative_path)?;
                 }
             }
         }
-        let id = existing
-            .as_ref()
-            .map(|record| record.resource.id.clone())
-            .unwrap_or_else(|| format!("media_{}", uuid::Uuid::now_v7()));
         let created_at = existing
             .as_ref()
             .map(|record| record.resource.created_at)
@@ -502,6 +554,7 @@ impl MemoFile {
                  created_at, updated_at)
             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 0, NULL, NULL, ?9, ?10)
             ON CONFLICT(notebook_id, relative_path) DO UPDATE SET
+                id = excluded.id,
                 kind = excluded.kind,
                 size_bytes = excluded.size_bytes,
                 modified_ms = excluded.modified_ms,
@@ -527,7 +580,7 @@ impl MemoFile {
         Ok(MediaResource {
             id,
             notebook_id: notebook_id.to_string(),
-            relative_path: relative_path.to_string(),
+            relative_path: relative_path.clone(),
             kind,
             size_bytes,
             modified_ms: modified,
@@ -709,7 +762,8 @@ impl MemoFile {
         Ok(())
     }
 
-    /// Preserve identity for a confirmed same-notebook filesystem rename.
+    /// Move a catalog row after a confirmed same-notebook filesystem rename.
+    /// The resource ID changes with the path while user properties remain on the row.
     /// Returns false when the old path is unknown or the destination already
     /// has a catalog record; callers can then use ordinary path refresh.
     pub fn move_media_resource_path(
@@ -718,6 +772,8 @@ impl MemoFile {
         old_relative_path: &str,
         new_relative_path: &str,
     ) -> std::io::Result<bool> {
+        let old_relative_path = normalize_media_relative_path(old_relative_path)?;
+        let new_relative_path = normalize_media_relative_path(new_relative_path)?;
         if old_relative_path == new_relative_path {
             return Ok(false);
         }
@@ -725,12 +781,12 @@ impl MemoFile {
             .memo_base_for_notebook_id_result(notebook_id)
             .map_err(std::io::Error::other)?;
         let policy = self.file_management_policy(notebook_id);
-        if policy.is_ignored_at(&root, Path::new(old_relative_path))
-            || policy.is_ignored_at(&root, Path::new(new_relative_path))
+        if policy.is_ignored_at(&root, Path::new(&old_relative_path))
+            || policy.is_ignored_at(&root, Path::new(&new_relative_path))
         {
             return Ok(false);
         }
-        let new_absolute = super::notebook_path_from_relative(&root, new_relative_path)
+        let new_absolute = super::notebook_path_from_relative(&root, &new_relative_path)
             .map_err(std::io::Error::other)?;
         let metadata = fs::symlink_metadata(&new_absolute)?;
         if metadata.file_type().is_symlink() || !metadata.is_file()
@@ -747,6 +803,7 @@ impl MemoFile {
         let size = metadata.len();
         let modified = modified_ms(&new_absolute);
         let fingerprint = stable_fingerprint(&new_absolute, size);
+        let new_id = media_resource_id(notebook_id, &new_relative_path)?;
         let mut conn = self.open_notebook_db(notebook_id)?;
         let tx = conn
             .transaction_with_behavior(TransactionBehavior::Immediate)
@@ -765,11 +822,12 @@ impl MemoFile {
         }
         let changed = tx
             .execute(
-                "UPDATE media_resources SET relative_path=?1, kind=?2, size_bytes=?3,
-                    modified_ms=?4, fingerprint=?5, missing_since=NULL, deleted_at=NULL,
-                    updated_at=?6
-                 WHERE notebook_id=?7 AND relative_path=?8",
+                "UPDATE media_resources SET id=?1, relative_path=?2, kind=?3, size_bytes=?4,
+                    modified_ms=?5, fingerprint=?6, missing_since=NULL, deleted_at=NULL,
+                    updated_at=?7
+                 WHERE notebook_id=?8 AND relative_path=?9",
                 params![
+                    new_id,
                     new_relative_path,
                     kind.as_str(),
                     size as i64,
@@ -785,10 +843,108 @@ impl MemoFile {
         Ok(changed > 0)
     }
 
+    /// Replace historical generated media IDs and normalize media library
+    /// references. Database and document updates are idempotent so startup can
+    /// safely retry after an interrupted run.
+    pub fn migrate_media_resource_identities(&self, notebook_id: &str) -> std::io::Result<usize> {
+        let root = self
+            .memo_base_for_notebook_id_result(notebook_id)
+            .map_err(std::io::Error::other)?;
+        let mut conn = self.open_notebook_db(notebook_id)?;
+        let tx = conn.transaction_with_behavior(TransactionBehavior::Immediate).map_err(sqlite_to_io)?;
+        let rows = {
+            let mut statement = tx
+                .prepare("SELECT id, relative_path FROM media_resources WHERE notebook_id=?1 ORDER BY relative_path")
+                .map_err(sqlite_to_io)?;
+            let rows = statement
+                .query_map([notebook_id], |row| Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?)))
+                .map_err(sqlite_to_io)?;
+            rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?
+        };
+        let mut updates = Vec::new();
+        let mut targets = HashSet::new();
+        for (old_id, old_path) in rows {
+            let relative_path = normalize_media_relative_path(&old_path)?;
+            let id = media_resource_id(notebook_id, &relative_path)?;
+            if !targets.insert(id.clone()) {
+                return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "duplicate canonical media resource identity"));
+            }
+            if old_id != id || old_path != relative_path {
+                let temporary_id = format!("__flowix_media_migration__{}", uuid::Uuid::now_v7().simple());
+                updates.push((old_id, temporary_id, id, relative_path));
+            }
+        }
+        for (old_id, temporary_id, _, _) in &updates {
+            tx.execute(
+                "UPDATE media_resources SET id=?1 WHERE notebook_id=?2 AND id=?3",
+                params![temporary_id, notebook_id, old_id],
+            ).map_err(sqlite_to_io)?;
+        }
+        for (_, temporary_id, id, relative_path) in &updates {
+            tx.execute(
+                "UPDATE media_resources SET id=?1, relative_path=?2 WHERE notebook_id=?3 AND id=?4",
+                params![id, relative_path, notebook_id, temporary_id],
+            ).map_err(sqlite_to_io)?;
+        }
+        tx.commit().map_err(sqlite_to_io)?;
+        drop(conn);
+
+        let mut changed = updates.len();
+        let walker = walkdir::WalkDir::new(&root).follow_links(false).into_iter().filter_entry(|entry| {
+            if entry.depth() == 0 || !entry.file_type().is_dir() { return true; }
+            let name = entry.file_name().to_string_lossy();
+            if name == ".flowix" || name == ".plugin-output" { return false; }
+            let internal = entry.path().join(".flowix");
+            !(internal.join("notebook.json").is_file() || internal.join("notebook.db").is_file())
+        });
+        for entry in walker {
+            let entry = entry.map_err(std::io::Error::other)?;
+            if !entry.file_type().is_file() { continue; }
+            let name = entry.file_name().to_string_lossy().to_ascii_lowercase();
+            if !(name == ".index.yaml" || name.ends_with(".lib.yaml") || name.ends_with(".lib.yml")) { continue; }
+            let path = entry.path();
+            let source = fs::read_to_string(path)?;
+            let Ok(mut document) = crate::collection::CollectionDocument::parse(&source) else {
+                // Do not block startup on a damaged collection. The explicit
+                // collection recovery flow rewrites its media IDs when repaired.
+                tracing::warn!(path = %path.display(), "skip malformed collection during media identity migration");
+                continue;
+            };
+            if document.collection.kind != crate::collection::CollectionType::MediaLibrary { continue; }
+            document = match document.normalized_v2() {
+                Ok(document) => document,
+                Err(error) => {
+                    tracing::warn!(path = %path.display(), %error,
+                        "skip invalid collection during media identity migration");
+                    continue;
+                }
+            };
+            let changed_ids = document
+                .normalize_media_resource_ids(notebook_id)
+                .map_err(std::io::Error::other)?;
+            if !changed_ids { continue; }
+            document.revise().map_err(std::io::Error::other)?;
+            let next = document.serialize().map_err(std::io::Error::other)?;
+            match self.write_file_if_matches_for_notebook(notebook_id, path, &next, Some(&source))? {
+                super::FileWriteOutcome::Saved => changed += 1,
+                super::FileWriteOutcome::Conflict { .. } => {
+                    return Err(std::io::Error::new(std::io::ErrorKind::WouldBlock, format!("media library changed during identity migration: {}", path.display())));
+                }
+            }
+        }
+        Ok(changed)
+    }
+
     /// Rebuild the media catalog from notebook files. The media file remains
     /// on disk, while resource properties are restored from the notebook
     /// database and are not regenerated from sibling files.
     pub fn reconcile_media_resources(&self, notebook_id: &str) -> std::io::Result<usize> {
+        self.reconcile_media_resources_background(notebook_id, &|| true)
+    }
+
+    pub fn reconcile_media_resources_background(
+        &self, notebook_id: &str, keep_running: &dyn Fn() -> bool,
+    ) -> std::io::Result<usize> {
         let root = self
             .memo_base_for_notebook_id_result(notebook_id)
             .map_err(std::io::Error::other)?;
@@ -829,11 +985,12 @@ impl MemoFile {
                     .is_ok_and(|relative| relative.as_os_str().is_empty() || !policy.is_ignored_at(&root, relative))
             })
         {
+            if !keep_running() { return Err(std::io::Error::from(std::io::ErrorKind::Interrupted)); }
             let entry = match entry {
                 Ok(entry) => entry,
                 Err(error) => {
-                    tracing::debug!(notebook = %notebook_id, error = %error, "skip unreadable media index entry");
-                    continue;
+                    // An incomplete directory walk is not evidence of deletion.
+                    return Err(std::io::Error::other(error));
                 }
             };
             if !entry.file_type().is_file() {
@@ -888,17 +1045,32 @@ impl MemoFile {
         drop(statement);
         let now = now_ms();
         for (id, relative, missing_since, deleted_at) in stale {
+            if !keep_running() { return Err(std::io::Error::from(std::io::ErrorKind::Interrupted)); }
+            if !root.is_dir() { return Err(std::io::Error::new(std::io::ErrorKind::NotFound, "notebook unavailable")); }
             if !seen.contains(&relative) {
                 if policy.is_ignored_at(&root, Path::new(&relative)) {
                     continue;
                 }
+                // A file can reappear after its directory was enumerated. A
+                // stale scan must not retire its catalog entry or user properties.
+                let candidate = super::notebook_path_from_relative(&root, &relative)
+                    .map_err(std::io::Error::other)?;
+                match fs::symlink_metadata(&candidate) {
+                    Ok(_) => continue,
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                    Err(error) => return Err(error),
+                }
+                if !root.is_dir() {
+                    return Err(std::io::Error::new(std::io::ErrorKind::NotFound, "notebook unavailable"));
+                }
                 let first_missing_at = missing_since.unwrap_or(now);
                 conn.execute(
                     "UPDATE media_resources
                      SET missing_since = COALESCE(missing_since, ?1),
                          updated_at = CASE WHEN missing_since IS NULL THEN ?1 ELSE updated_at END
-                     WHERE notebook_id = ?2 AND id = ?3",
-                    params![first_missing_at, notebook_id, id],
+                     WHERE notebook_id = ?2 AND id = ?3 AND relative_path = ?4
+                       AND missing_since IS ?5 AND deleted_at IS ?6",
+                    params![first_missing_at, notebook_id, id, relative, missing_since, deleted_at],
                 )
                 .map_err(sqlite_to_io)?;
                 if first_missing_at < now - MEDIA_MISSING_RETENTION_MS
@@ -907,8 +1079,9 @@ impl MemoFile {
                 {
                     conn.execute(
                         "DELETE FROM media_resources
-                         WHERE notebook_id = ?1 AND id = ?2",
-                        params![notebook_id, id],
+                         WHERE notebook_id = ?1 AND id = ?2 AND relative_path = ?3
+                           AND missing_since = ?4 AND deleted_at IS ?5",
+                        params![notebook_id, id, relative, first_missing_at, deleted_at],
                     )
                     .map_err(sqlite_to_io)?;
                 }
@@ -930,7 +1103,85 @@ mod tests {
     use super::*;
 
     #[test]
-    fn directory_index_rebase_preserves_media_identity_and_note_projections_and_is_repeatable() {
+    fn background_note_preparation_preserves_shared_media_properties() {
+        let (memo, _temp, root) = fixture();
+        fs::write(root.join("kept.png"), b"image").unwrap();
+        fs::write(root.join("note.md"), "# Note").unwrap();
+        let media = memo.ensure_media_resource("nb_media_test", "kept.png", MediaResourceKind::Image, &root.join("kept.png")).unwrap();
+        memo.update_media_resource_properties("nb_media_test", &media.id, &serde_json::json!({"caption":"user data"})).unwrap();
+        memo.prepare_background_note_projection("nb_media_test").unwrap();
+        memo.reconcile_note_index_background("nb_media_test", &|| true).unwrap();
+        let after = memo.read_media_resource("nb_media_test", "kept.png").unwrap().unwrap();
+        assert_eq!(after.id, media.id);
+        assert_eq!(after.properties["caption"], "user data");
+    }
+
+    #[test]
+    fn media_reappearing_after_enumeration_keeps_its_catalog_entry() {
+        let (memo, _temp, root) = fixture();
+        let path = root.join("returned.png");
+        fs::write(&path, b"image").unwrap();
+        memo.reconcile_media_resources("nb_media_test").unwrap();
+        let before = memo.read_media_resource("nb_media_test", "returned.png").unwrap().unwrap();
+        fs::remove_file(&path).unwrap();
+        let checks = std::cell::Cell::new(0);
+        memo.reconcile_media_resources_background("nb_media_test", &|| {
+            checks.set(checks.get() + 1);
+            // The empty root is visited first, then the stale catalog row.
+            if checks.get() == 2 { fs::write(&path, b"image").unwrap(); }
+            true
+        }).unwrap();
+        assert!(path.is_file());
+        let conn = memo.open_notebook_db("nb_media_test").unwrap();
+        let missing: Option<i64> = conn.query_row("SELECT missing_since FROM media_resources WHERE id=?1", [&before.id], |row| row.get(0)).unwrap();
+        assert!(missing.is_none());
+    }
+
+    #[test]
+    fn stale_media_cleanup_cannot_delete_a_concurrently_restored_catalog_row() {
+        let (memo, _temp, root) = fixture();
+        let old_path = root.join("old.png");
+        fs::write(&old_path, b"image").unwrap();
+        memo.reconcile_media_resources("nb_media_test").unwrap();
+        let before = memo.read_media_resource("nb_media_test", "old.png").unwrap().unwrap();
+        let conn = memo.open_notebook_db("nb_media_test").unwrap();
+        conn.execute("UPDATE media_resources SET missing_since=1, deleted_at=1 WHERE id=?1", [&before.id]).unwrap();
+        fs::remove_file(&old_path).unwrap();
+        let checks = std::cell::Cell::new(0);
+        memo.reconcile_media_resources_background("nb_media_test", &|| {
+            checks.set(checks.get() + 1);
+            if checks.get() == 2 {
+                fs::write(root.join("new.png"), b"image").unwrap();
+                conn.execute(
+                    "UPDATE media_resources SET id=?1, relative_path='new.png', missing_since=NULL, deleted_at=NULL WHERE id=?2",
+                    params![media_resource_id("nb_media_test", "new.png").unwrap(), before.id],
+                ).unwrap();
+            }
+            true
+        }).unwrap();
+        let after = memo.read_media_resource("nb_media_test", "new.png").unwrap().unwrap();
+        assert_eq!(after.id, media_resource_id("nb_media_test", "new.png").unwrap());
+        assert_ne!(after.id, before.id);
+        let missing: Option<i64> = conn.query_row("SELECT missing_since FROM media_resources WHERE id=?1", [&after.id], |row| row.get(0)).unwrap();
+        assert!(missing.is_none());
+    }
+
+    #[test]
+    fn cancelled_media_scan_never_marks_unvisited_resources_missing() {
+        let (memo, _temp, root) = fixture();
+        fs::write(root.join("kept.png"), b"image").unwrap();
+        memo.reconcile_media_resources("nb_media_test").unwrap();
+        let before = memo.read_media_resource("nb_media_test", "kept.png").unwrap().unwrap();
+        assert_eq!(memo.reconcile_media_resources_background("nb_media_test", &|| false).unwrap_err().kind(), std::io::ErrorKind::Interrupted);
+        let after = memo.read_media_resource("nb_media_test", "kept.png").unwrap().unwrap();
+        assert_eq!(before.id, after.id);
+        let conn = memo.open_notebook_db("nb_media_test").unwrap();
+        let missing: Option<i64> = conn.query_row("SELECT missing_since FROM media_resources WHERE id=?1", [&before.id], |row| row.get(0)).unwrap();
+        assert!(missing.is_none());
+    }
+
+    #[test]
+    fn directory_index_rebase_updates_media_path_identity_and_preserves_projections() {
         let (memo, _temp, root) = fixture();
         fs::create_dir(root.join("Old")).unwrap();
         fs::create_dir(root.join("Oldish")).unwrap();
@@ -943,7 +1194,7 @@ mod tests {
         let before = memo.read_media_resource("nb_media_test", "Old/photo.png").unwrap().unwrap();
         memo.update_media_resource_properties("nb_media_test", &before.id, &serde_json::json!({"caption":"keep"})).unwrap();
         let conn = memo.open_note_index_connection("nb_media_test").unwrap();
-        conn.execute("INSERT INTO note_tags(relative_path,tag) VALUES('Old/note.md','keep')", []).unwrap();
+        conn.execute("UPDATE notes SET tags='[\"keep\"]' WHERE relative_path='Old/note.md'", []).unwrap();
         conn.execute("UPDATE notes SET created_at=42 WHERE relative_path='Old/note.md'", []).unwrap();
         drop(conn);
         fs::rename(root.join("Old"), root.join("New")).unwrap();
@@ -952,14 +1203,15 @@ mod tests {
                 memo.rebase_directory_indexes("nb_media_test", "Old", "New")).unwrap();
         }
         let after = memo.read_media_resource("nb_media_test", "New/photo.png").unwrap().unwrap();
-        assert_eq!(after.id, before.id);
+        assert_eq!(after.id, media_resource_id("nb_media_test", "New/photo.png").unwrap());
+        assert_ne!(after.id, before.id);
         assert_eq!(after.fingerprint, before.fingerprint);
         assert_eq!(after.properties["caption"], "keep");
         assert!(memo.read_media_resource("nb_media_test", "Old/photo.png").unwrap().is_none());
         assert!(memo.read_media_resource("nb_media_test", "Oldish/keep.png").unwrap().is_some());
         let conn = memo.open_note_index_connection("nb_media_test").unwrap();
         assert_eq!(conn.query_row("SELECT created_at FROM notes WHERE relative_path='New/note.md'", [], |row| row.get::<_, i64>(0)).unwrap(), 42);
-        assert_eq!(conn.query_row("SELECT tag FROM note_tags WHERE relative_path='New/note.md'", [], |row| row.get::<_, String>(0)).unwrap(), "keep");
+        assert_eq!(conn.query_row("SELECT tags FROM notes WHERE relative_path='New/note.md'", [], |row| row.get::<_, String>(0)).unwrap(), "[\"keep\"]");
         assert_eq!(conn.query_row("SELECT COUNT(*) FROM notes WHERE relative_path='Old/note.md'", [], |row| row.get::<_, i64>(0)).unwrap(), 0);
     }
 
@@ -982,7 +1234,8 @@ mod tests {
         memo_file.refresh_media_resource_path("nb_media_test", "old.png").unwrap();
         let renamed = memo_file.read_media_resource("nb_media_test", "new.png")
             .unwrap().unwrap();
-        assert_eq!(renamed.id, resource.id);
+        assert_eq!(renamed.id, media_resource_id("nb_media_test", "new.png").unwrap());
+        assert_ne!(renamed.id, resource.id);
         assert_eq!(renamed.properties, properties);
 
         fs::remove_file(&new).unwrap();
@@ -1011,6 +1264,112 @@ mod tests {
         (memo_file, temp, root)
     }
 
+    fn media_library_source(include_path: &str, exclude_path: &str) -> String {
+        serde_yaml::to_string(&serde_json::json!({
+            "format": "flowix.collection",
+            "schema_version": 2,
+            "collection": {
+                "id": format!("col_{}", "a".repeat(32)),
+                "type": "media_library",
+                "revision": 4,
+                "created_at": "2026-01-01T00:00:00Z",
+                "updated_at": "2026-01-01T00:00:00Z",
+                "properties": {}
+            },
+            "payload": {
+                "schema_version": 2,
+                "dataset": {
+                    "source": {"scope": "notebook", "depth": "descendants"},
+                    "schema": {"fields": []},
+                    "records": {
+                        "include": [{"resource_id": "media_old_photo", "relative_path": include_path}],
+                        "exclude": [{"resource_id": "media_old_excluded", "relative_path": exclude_path}]
+                    },
+                    "filter": null
+                },
+                "views": {
+                    "default_id": format!("view_{}", "b".repeat(32)),
+                    "items": [{
+                        "id": format!("view_{}", "b".repeat(32)),
+                        "name": "All media",
+                        "layout": "waterfall",
+                        "filter": {"all": [], "any": []},
+                        "sort": [{"field": "created_at", "direction": "desc"}],
+                        "config": {}
+                    }]
+                }
+            }
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn media_identity_migration_rewrites_database_and_collection_references_idempotently() {
+        let (memo, _temp, root) = fixture();
+        let photo = root.join("photo.png");
+        fs::write(&photo, b"image").unwrap();
+        let resource = memo.ensure_media_resource(
+            "nb_media_test", "photo.png", MediaResourceKind::Image, &photo,
+        ).unwrap();
+        memo.update_media_resource_properties(
+            "nb_media_test", &resource.id, &serde_json::json!({"caption": "keep me"}),
+        ).unwrap();
+        let conn = memo.open_notebook_db("nb_media_test").unwrap();
+        conn.execute(
+            "UPDATE media_resources SET id='media_old_photo' WHERE notebook_id='nb_media_test' AND relative_path='photo.png'",
+            [],
+        ).unwrap();
+        drop(conn);
+
+        let collection_path = root.join("Library.lib.yaml");
+        fs::write(&collection_path, media_library_source("photo.png", "removed.png")).unwrap();
+        assert_eq!(memo.migrate_media_resource_identities("nb_media_test").unwrap(), 2);
+
+        let canonical_photo_id = media_resource_id("nb_media_test", "photo.png").unwrap();
+        let migrated = memo.read_media_resource("nb_media_test", "photo.png").unwrap().unwrap();
+        assert_eq!(migrated.id, canonical_photo_id);
+        assert_eq!(migrated.properties["caption"], "keep me");
+
+        let source = fs::read_to_string(&collection_path).unwrap();
+        let document = crate::collection::CollectionDocument::parse(&source).unwrap();
+        assert_eq!(document.payload["dataset"]["records"]["include"][0]["resource_id"], canonical_photo_id);
+        assert_eq!(document.payload["dataset"]["records"]["exclude"][0]["resource_id"], media_resource_id("nb_media_test", "removed.png").unwrap());
+        assert_eq!(document.collection.revision, 5);
+        assert_eq!(memo.migrate_media_resource_identities("nb_media_test").unwrap(), 0);
+    }
+
+    #[test]
+    fn media_identity_migration_skips_semantically_invalid_collections_and_continues() {
+        let (memo, _temp, root) = fixture();
+        let photo = root.join("photo.png");
+        fs::write(&photo, b"image").unwrap();
+        memo.ensure_media_resource(
+            "nb_media_test", "photo.png", MediaResourceKind::Image, &photo,
+        ).unwrap();
+        let conn = memo.open_notebook_db("nb_media_test").unwrap();
+        conn.execute(
+            "UPDATE media_resources SET id='media_old_photo' WHERE notebook_id='nb_media_test' AND relative_path='photo.png'",
+            [],
+        ).unwrap();
+        let stored_id: String = conn.query_row(
+            "SELECT id FROM media_resources WHERE notebook_id='nb_media_test' AND relative_path='photo.png'",
+            [],
+            |row| row.get(0),
+        ).unwrap();
+        assert_eq!(stored_id, "media_old_photo");
+        drop(conn);
+
+        let invalid_path = root.join("Broken.lib.yaml");
+        let invalid_source = media_library_source("../photo.png", "removed.png");
+        fs::write(&invalid_path, &invalid_source).unwrap();
+        assert_eq!(memo.migrate_media_resource_identities("nb_media_test").unwrap(), 1);
+        assert_eq!(
+            memo.read_media_resource("nb_media_test", "photo.png").unwrap().unwrap().id,
+            media_resource_id("nb_media_test", "photo.png").unwrap(),
+        );
+        assert_eq!(fs::read_to_string(invalid_path).unwrap(), invalid_source);
+    }
+
     #[test]
     fn media_kind_classifies_supported_files_only() {
         assert_eq!(
@@ -1321,7 +1680,7 @@ mod tests {
     }
 
     #[test]
-    fn renamed_media_keeps_its_id_and_database_properties() {
+    fn renamed_media_changes_its_path_id_and_keeps_database_properties() {
         let (memo_file, _temp, root) = fixture();
         let old_media = root.join("old.png");
         let new_media = root.join("new.png");
@@ -1349,7 +1708,8 @@ mod tests {
             )
             .unwrap();
 
-        assert_eq!(new_resource.id, old_resource.id);
+        assert_eq!(new_resource.id, media_resource_id("nb_media_test", "new.png").unwrap());
+        assert_ne!(new_resource.id, old_resource.id);
         assert_eq!(new_resource.properties, properties);
         assert!(!MemoFile::legacy_media_properties_path(&new_media).exists());
         assert!(!MemoFile::legacy_media_properties_path(&old_media).exists());
diff --git a/app/flowix-core/src/memo_file/mod.rs b/app/flowix-core/src/memo_file/mod.rs
index a1a53c75d..3169f1c8f 100644
--- a/app/flowix-core/src/memo_file/mod.rs
+++ b/app/flowix-core/src/memo_file/mod.rs
@@ -1,16 +1,15 @@
 //! Notebook storage and Markdown file operations.
 //!
-//! Markdown files own note content. The rebuildable path projection in each
-//! notebook's `.flowix/notebook.db` addresses notes by relative path. Legacy
-//! memo-ID records and APIs remain for callers that have not migrated yet;
-//! new Note writes do not stamp those IDs into Markdown frontmatter or filenames.
+//! Markdown files own note content. Rebuildable projections address notes by
+//! notebook-relative path; note identity is never generated from or parsed
+//! out of Markdown frontmatter.
 //!
 //! - `frontmatter` parses and edits authored YAML metadata.
 //! - `note_index` maintains the path-keyed Note projection and path operations;
 //!   it discards the old rebuildable `v2_*` projection schema on first use.
-//! - `index_store` maintains legacy memo-ID records and related metadata.
-//! - `ops` contains legacy CRUD and reconciliation operations.
-//! - `versions` stores history currently keyed by internal memo ID.
+//! - `index_store` stores content-derived listing fields.
+//! - `ops` contains CRUD and reconciliation operations.
+//! - `versions` stores history keyed by notebook-relative path.
 //!
 //! `MemoIndexEntry::filename` contains the disk filename, including `.md`.
 //! Nested notes also carry a notebook-relative path; resolve that path against
@@ -19,23 +18,16 @@
 use std::path::PathBuf;
 use std::{fs::OpenOptions, io};
 
-/// memo id 随机段使用的字符集 — `[0-9a-z]` 36 个字符 (小写字母 + 数字)。
-///
-/// nanoid's default alphabet includes `_` and `-`; legacy memo IDs use only
-/// lowercase letters and digits. New IDs contain [`MEMO_ID_LENGTH`] characters.
-pub const MEMO_ID_ALPHABET: [char; 36] = [
-    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i',
-    'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z',
-];
-pub const MEMO_ID_LENGTH: usize = 8;
-
 mod content;
+mod database_layout;
+mod storage_repair;
 mod derivation;
 mod file_management;
 mod file_io;
 pub(crate) mod frontmatter;
 mod index_store;
 mod internal_migration;
+mod local_migrations;
 mod media_resource;
 mod migration;
 mod notebook;
@@ -50,8 +42,8 @@ mod note_index;
 mod versions;
 
 pub use note_index::{
-    NoteEntry, NoteIndexReconcileReport, NotePropertyMigrationReport, NoteSearchHit,
-    NoteTodoMigrationReport, NoteWriteOutcome,
+    NoteEntry, NoteIndexReconcileReport, NoteSearchHit,
+    NoteWriteOutcome,
 };
 pub use operation_locks::{FileLockIntent, FileWriteGuard, OperationLocks};
 
@@ -67,15 +59,17 @@ pub use file_io::{
 };
 pub use file_management::{default_create_folder_for_notebook, FileManagementPolicy};
 pub use frontmatter::{
-    extract_body_content, extract_document_metadata, extract_frontmatter_key,
-    extract_frontmatter_properties, is_system_frontmatter_key, merge_frontmatter,
+    extract_body_content, extract_document_metadata, extract_frontmatter_properties,
+    merge_frontmatter,
     normalize_document_tags, normalize_markdown_encoding_boundaries, replace_frontmatter_tags,
-    DocumentMetadata, FrontmatterMetadataError, MergeOverrides, CANONICAL_FRONTMATTER_KEY,
-    LEGACY_FRONTMATTER_KEY, SYSTEM_FRONTMATTER_KEYS,
+    DocumentMetadata, FrontmatterMetadataError, MergeOverrides,
 };
-pub use index_store::{MemoContentCommit, MemoContentRevision, NoteContentCommit, NoteContentRevision};
+pub use index_store::{NoteContentCommit, NoteContentRevision};
+pub use local_migrations::{initialize_local_migration_table, NotebookInitializationJob};
 pub use internal_migration::{NotebookInternalMigrationReport, NOTEBOOK_INTERNAL_MIGRATION_KEY};
-pub use media_resource::{media_kind_for_path, MediaResource, MediaResourceKind, MediaResourcePage};
+pub use storage_repair::{ensure_storage_directory, read_or_create_json, backup_database, backup_storage_file, is_rebuildable_storage_error, with_database_rebuild};
+pub use database_layout::{prepare_database_directory, DATABASE_DIRECTORY_NAME};
+pub use media_resource::{media_kind_for_path, media_resource_id, MediaResource, MediaResourceKind, MediaResourcePage};
 pub use migration::{DataMigrationReport, NotebookMigrationReport, LATEST_DATA_MIGRATION_VERSION};
 pub use ops::{
     base_filename, filename_from_notebook_relative_path, is_ignored_notebook_relative_path,
@@ -83,9 +77,11 @@ pub use ops::{
     resolve_relative_filename_conflict, sanitize_filename_component, IsMd,
 };
 pub use types::{
-    AgentThreadItem, DeleteTagReport, Memo, MemoColor, MemoIndexEntry, MemoIndexFile, MemoLocation,
-    MemoMetadataFile, MemoTag, MemoTodoEntry, MoveTagReport, NoteColor,
+    AgentThreadItem, DeleteTagReport, Memo, MemoIndexEntry, MemoIndexFile, MemoLocation,
+    MemoTag, MoveTagReport, NoteColor,
     Notebook, NotebookConfig, NotebookManifest, NotebookSetupJob, NotebookSetupJobStatus,
+    NotebookSetupSnapshot,
+    NotebookSetupStage,
     NotebookSetupReport,
     ReconcileReport, TodoItem,
 };
@@ -94,16 +90,16 @@ pub use versions::{
     MEMO_VERSION_LIMIT,
 };
 
-/// Compatibility storage façade over notebook registry, Note catalog, media,
-/// revisions and Memo-ID records. Domain implementations live in separate
-/// modules; `NotebookRegistry` owns the device-local registry path and cache.
+/// Storage façade over notebook registry, Note catalog, media and revisions.
+/// Domain implementations live in separate modules; `NotebookRegistry` owns
+/// the device-local registry path and cache.
 ///
 /// 字段:
 /// - `registry`: 用户配置目录 (`~/.flowix/`) 下的设备级笔记本注册表。
-/// - Note 投影、兼容 memo-ID 数据和媒体属性位于
+/// - Note 投影和媒体属性位于
 ///   `<notebook>/.flowix/notebook.db`。
 /// - `current_notebook_id`: 当前活跃 notebook id, `None` 表示走默认。
-/// - `index_cache`: 当前 notebook 兼容 memo-ID 列表的内存缓存。读路径先查询 SQLite
+/// - `index_cache`: 当前 notebook 相对路径索引的内存缓存。读路径先查询 SQLite
 ///   `memo_index_state.last_updated`，只有版本一致才复用，保证其他进程写入可见。
 ///   写路径 ([`MemoFile::write_index`] / `_locked` 系列) 在 DB 写入成功后回填。
 ///   切 notebook 时由 [`Self::set_current_notebook`] 失效。
@@ -340,3 +336,6 @@ impl MemoFile {
 
 #[cfg(test)]
 mod tests;
+
+mod workspace;
+pub use workspace::{NotebookAddDir, NotebookWorkspaceConfig, NotebookWorkspaceSnapshot};
diff --git a/app/flowix-core/src/memo_file/note_index.rs b/app/flowix-core/src/memo_file/note_index.rs
index c603fc66a..fb16287b2 100644
--- a/app/flowix-core/src/memo_file/note_index.rs
+++ b/app/flowix-core/src/memo_file/note_index.rs
@@ -3,7 +3,7 @@
 //! This index never supplies bytes for a note. Markdown remains the source of
 //! content and the projection can be discarded and rebuilt from the notebook.
 
-use std::collections::{BTreeMap, HashMap, HashSet};
+use std::collections::{HashMap, HashSet};
 use std::fs;
 use std::io;
 use std::path::Path;
@@ -17,13 +17,13 @@ use walkdir::WalkDir;
 
 use super::{
     notebook_path_from_relative, notebook_relative_path, AgentThreadItem, Memo, MemoFile,
-    MemoIndexEntry, NoteColor, TodoItem,
+    NoteColor, TodoItem,
 };
 
-const SCHEMA_VERSION: i64 = 3;
-// Version 9 tolerates legacy malformed tags while retaining ordinary properties.
-const PARSER_VERSION: i64 = 9;
-const NOTE_SEARCH_FTS_VERSION: i64 = 1;
+const SCHEMA_VERSION: i64 = 4;
+// Version 10 stores derived tags, todos, and agents on each notes row.
+const PARSER_VERSION: i64 = 10;
+const NOTE_SEARCH_FTS_VERSION: i64 = 2;
 const NOTE_INDEX_REFRESH_PENDING: &str = "note-index-refresh-pending";
 const NOTE_INDEX_REFRESH_PENDING_DIR: &str = "note-index-refresh-pending.d";
 static NOTE_INDEX_REFRESH_SEQUENCE: AtomicU64 = AtomicU64::new(0);
@@ -129,6 +129,13 @@ pub enum NoteWriteOutcome {
     Conflict { disk_content: String },
 }
 
+#[derive(Clone, Copy)]
+enum MaintenanceAdmission {
+    Wait,
+    SkipIfBusy,
+    FailIfBusy,
+}
+
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct NoteIndexReconcileReport {
     pub added: usize,
@@ -146,61 +153,6 @@ pub struct NoteSearchHit {
     pub matched_in: String,
 }
 
-#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
-pub struct NoteTodoMigrationReport {
-    pub notes_written: usize,
-    pub tasks_written: usize,
-}
-
-#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
-pub struct NotePropertyMigrationReport {
-    pub notes_written: usize,
-    pub properties_written: usize,
-}
-
-#[derive(Debug)]
-struct LegacyNoteProperties {
-    id: String,
-    relative_path: String,
-    created_at: i64,
-    favorited: bool,
-    icon: Option<String>,
-    properties_json: String,
-}
-
-#[derive(Debug)]
-struct LegacyTodoAttributes {
-    todo_id: String,
-    priority: String,
-    time_range: String,
-    owner: String,
-    assignee: String,
-    created_at: i64,
-    updated_at: i64,
-}
-
-impl LegacyTodoAttributes {
-    fn has_persistent_value(&self) -> bool {
-        !self.priority.is_empty()
-            || !self.time_range.is_empty()
-            || !self.owner.is_empty()
-            || !self.assignee.is_empty()
-            || self.created_at != 0
-            || self.updated_at != 0
-    }
-
-    fn json_value(&self) -> serde_json::Value {
-        serde_json::json!({
-            "priority": self.priority,
-            "timeRange": self.time_range,
-            "owner": self.owner,
-            "assignee": self.assignee,
-            "createdAt": self.created_at,
-            "updatedAt": self.updated_at,
-        })
-    }
-}
-
 impl MemoFile {
     pub(crate) fn mark_note_index_refresh_pending_for_notebook(&self, notebook_id: &str) -> io::Result<()> {
         let root = self.notebook_root_for_note(notebook_id)?;
@@ -667,7 +619,7 @@ impl MemoFile {
         let conn = self.open_note_index_connection(notebook_id)?;
         let exists: bool = conn
             .query_row(
-                "SELECT EXISTS(SELECT 1 FROM note_tags WHERE tag = ?1)",
+                "SELECT EXISTS(SELECT 1 FROM notes n, json_each(n.tags) t WHERE t.value = ?1)",
                 [tag],
                 |row| row.get(0),
             )
@@ -683,15 +635,14 @@ impl MemoFile {
         tag: &str,
     ) -> io::Result<Vec<String>> {
         let conn = self.open_note_index_connection(notebook_id)?;
-        let prefix = format!("{tag}/");
         let mut stmt = conn
             .prepare(
-                "SELECT DISTINCT relative_path FROM note_tags \
-                 WHERE tag = ?1 OR tag LIKE ?2 ESCAPE '\\' ORDER BY relative_path",
+                "SELECT DISTINCT n.relative_path FROM notes n, json_each(n.tags) t \
+                 WHERE t.value = ?1 OR substr(t.value, 1, length(?1)+1) = ?1 || '/' ORDER BY n.relative_path",
             )
             .map_err(io::Error::other)?;
         let rows = stmt
-            .query_map(params![tag, format!("{prefix}%")], |row| row.get(0))
+            .query_map(params![tag], |row| row.get(0))
             .map_err(io::Error::other)?;
         rows.collect::<Result<Vec<_>, _>>().map_err(io::Error::other)
     }
@@ -716,13 +667,14 @@ impl MemoFile {
         relative_path: &str,
     ) -> io::Result<Option<NoteEntry>> {
         let conn = self.open_note_index_connection(notebook_id)?;
-        let row: Option<(String, String, String, Option<String>, i64, i64, i64, Option<String>, String, String, u64)> = conn
+        let row: Option<(String, String, String, Option<String>, i64, i64, i64, Option<String>, String, String, u64, String, String, String)> = conn
             .query_row(
-                "SELECT relative_path, title, preview, thumbnail, created_at, updated_at, favorited, icon, colors_json, properties_json, size_bytes \
+                "SELECT relative_path, title, preview, thumbnail, created_at, updated_at, favorited, icon, colors_json, properties_json, size_bytes, tags, todos, agents \
                  FROM notes WHERE relative_path=?1",
                 params![relative_path],
                 |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?, row.get(4)?,
-                    row.get(5)?, row.get(6)?, row.get(7)?, row.get(8)?, row.get(9)?, row.get(10)?)),
+                    row.get(5)?, row.get(6)?, row.get(7)?, row.get(8)?, row.get(9)?, row.get(10)?,
+                    row.get(11)?, row.get(12)?, row.get(13)?)),
             )
             .optional()
             .map_err(io::Error::other)?;
@@ -738,19 +690,22 @@ impl MemoFile {
             colors,
             properties,
             size_bytes,
+            tags,
+            todos,
+            agents,
         )) = row
         else {
             return Ok(None);
         };
-        let mut entry = NoteEntry {
+        let entry = NoteEntry {
             size_bytes,
             relative_path,
             title,
             preview,
             thumbnail,
-            tags: Vec::new(),
-            todos: Vec::new(),
-            agents: Vec::new(),
+            tags: serde_json::from_str(&tags).map_err(io::Error::other)?,
+            todos: serde_json::from_str(&todos).map_err(io::Error::other)?,
+            agents: serde_json::from_str(&agents).map_err(io::Error::other)?,
             created_at,
             updated_at,
             favorited: favorited != 0,
@@ -758,42 +713,6 @@ impl MemoFile {
             colors: serde_json::from_str(&colors).map_err(io::Error::other)?,
             properties: serde_json::from_str(&properties).map_err(io::Error::other)?,
         };
-        let mut stmt = conn
-            .prepare("SELECT tag FROM note_tags WHERE relative_path=?1 ORDER BY tag")
-            .map_err(io::Error::other)?;
-        entry.tags = stmt
-            .query_map(params![&entry.relative_path], |row| row.get(0))
-            .map_err(io::Error::other)?
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(io::Error::other)?;
-        let mut stmt = conn.prepare(
-            "SELECT todo_id, content, status FROM note_todos WHERE relative_path=?1 ORDER BY position"
-        ).map_err(io::Error::other)?;
-        entry.todos = stmt
-            .query_map(params![&entry.relative_path], |row| {
-                Ok(TodoItem {
-                    id: row.get(0)?,
-                    content: row.get(1)?,
-                    status: row.get(2)?,
-                })
-            })
-            .map_err(io::Error::other)?
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(io::Error::other)?;
-        let mut stmt = conn.prepare(
-            "SELECT thread_id, title, agent_type FROM note_agents WHERE relative_path=?1 ORDER BY position"
-        ).map_err(io::Error::other)?;
-        entry.agents = stmt
-            .query_map(params![&entry.relative_path], |row| {
-                Ok(AgentThreadItem {
-                    thread_id: row.get(0)?,
-                    title: row.get(1)?,
-                    agent_type: row.get(2)?,
-                })
-            })
-            .map_err(io::Error::other)?
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(io::Error::other)?;
         Ok(Some(entry))
     }
 
@@ -823,7 +742,6 @@ impl MemoFile {
             .unwrap_or(updated_at);
         let content = fs::read_to_string(&path)?;
         let mut derived = Memo {
-            id: String::new(),
             filename: relative_path
                 .rsplit('/')
                 .next()
@@ -872,7 +790,7 @@ impl MemoFile {
         }
         let conn = self.open_note_index_connection(notebook_id)?;
         let mut stmt = conn.prepare(
-            "SELECT relative_path, title, preview, thumbnail, created_at, updated_at, favorited, icon, colors_json, properties_json, size_bytes \
+            "SELECT relative_path, title, preview, thumbnail, created_at, updated_at, favorited, icon, colors_json, properties_json, size_bytes, tags, todos, agents \
              FROM notes ORDER BY created_at ASC, relative_path ASC"
         ).map_err(io::Error::other)?;
         let rows = stmt
@@ -889,6 +807,9 @@ impl MemoFile {
                     row.get::<_, String>(8)?,
                     row.get::<_, String>(9)?,
                     row.get::<_, u64>(10)?,
+                    row.get::<_, String>(11)?,
+                    row.get::<_, String>(12)?,
+                    row.get::<_, String>(13)?,
                 ))
             })
             .map_err(io::Error::other)?;
@@ -906,6 +827,9 @@ impl MemoFile {
                 colors,
                 properties,
                 size_bytes,
+                tags,
+                todos,
+                agents,
             ) = row.map_err(io::Error::other)?;
             entries.push(NoteEntry {
                 size_bytes,
@@ -913,9 +837,9 @@ impl MemoFile {
                 title,
                 preview,
                 thumbnail,
-                tags: Vec::new(),
-                todos: Vec::new(),
-                agents: Vec::new(),
+                tags: serde_json::from_str(&tags).map_err(io::Error::other)?,
+                todos: serde_json::from_str(&todos).map_err(io::Error::other)?,
+                agents: serde_json::from_str(&agents).map_err(io::Error::other)?,
                 created_at,
                 updated_at,
                 favorited: favorited != 0,
@@ -924,68 +848,6 @@ impl MemoFile {
                 properties: serde_json::from_str(&properties).map_err(io::Error::other)?,
             });
         }
-        drop(stmt);
-        let positions: HashMap<_, _> = entries
-            .iter()
-            .enumerate()
-            .map(|(index, entry)| (entry.relative_path.clone(), index))
-            .collect();
-        let mut stmt = conn
-            .prepare("SELECT relative_path, tag FROM note_tags ORDER BY relative_path, tag")
-            .map_err(io::Error::other)?;
-        let rows = stmt
-            .query_map([], |row| {
-                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
-            })
-            .map_err(io::Error::other)?;
-        for row in rows {
-            let (path, tag) = row.map_err(io::Error::other)?;
-            if let Some(index) = positions.get(&path) {
-                entries[*index].tags.push(tag);
-            }
-        }
-        let mut stmt = conn.prepare(
-            "SELECT relative_path, todo_id, content, status FROM note_todos ORDER BY relative_path, position"
-        ).map_err(io::Error::other)?;
-        let rows = stmt
-            .query_map([], |row| {
-                Ok((
-                    row.get::<_, String>(0)?,
-                    TodoItem {
-                        id: row.get(1)?,
-                        content: row.get(2)?,
-                        status: row.get(3)?,
-                    },
-                ))
-            })
-            .map_err(io::Error::other)?;
-        for row in rows {
-            let (path, todo) = row.map_err(io::Error::other)?;
-            if let Some(index) = positions.get(&path) {
-                entries[*index].todos.push(todo);
-            }
-        }
-        let mut stmt = conn.prepare(
-            "SELECT relative_path, thread_id, title, agent_type FROM note_agents ORDER BY relative_path, position"
-        ).map_err(io::Error::other)?;
-        let rows = stmt
-            .query_map([], |row| {
-                Ok((
-                    row.get::<_, String>(0)?,
-                    AgentThreadItem {
-                        thread_id: row.get(1)?,
-                        title: row.get(2)?,
-                        agent_type: row.get(3)?,
-                    },
-                ))
-            })
-            .map_err(io::Error::other)?;
-        for row in rows {
-            let (path, agent) = row.map_err(io::Error::other)?;
-            if let Some(index) = positions.get(&path) {
-                entries[*index].agents.push(agent);
-            }
-        }
         Ok(entries)
     }
 
@@ -1035,9 +897,9 @@ impl MemoFile {
                     OR lower(body) LIKE ?1 ESCAPE '\\'
                     OR lower(tags) LIKE ?1 ESCAPE '\\')
                    AND (?4 IS NULL OR EXISTS (
-                       SELECT 1 FROM note_tags t
-                       WHERE t.relative_path=note_search_fts.relative_path
-                         AND (t.tag=?4 OR substr(t.tag, 1, length(?4)+1)=?4 || '/')
+                       SELECT 1 FROM notes n, json_each(n.tags) t
+                       WHERE n.relative_path=note_search_fts.relative_path
+                         AND (t.value=?4 OR substr(t.value, 1, length(?4)+1)=?4 || '/')
                    ))
                  ORDER BY updated_at DESC, relative_path ASC LIMIT ?3",
                 pattern,
@@ -1052,9 +914,9 @@ impl MemoFile {
                  FROM note_search_fts
                  WHERE note_search_fts MATCH ?1
                    AND (?4 IS NULL OR EXISTS (
-                       SELECT 1 FROM note_tags t
-                       WHERE t.relative_path=note_search_fts.relative_path
-                         AND (t.tag=?4 OR substr(t.tag, 1, length(?4)+1)=?4 || '/')
+                       SELECT 1 FROM notes n, json_each(n.tags) t
+                       WHERE n.relative_path=note_search_fts.relative_path
+                         AND (t.value=?4 OR substr(t.value, 1, length(?4)+1)=?4 || '/')
                    ))
                  ORDER BY updated_at DESC, relative_path ASC LIMIT ?3",
                 quoted,
@@ -1161,7 +1023,7 @@ impl MemoFile {
                 continue;
             }
             let tags: String = tx.query_row(
-                "SELECT COALESCE(group_concat(tag, ' '), '') FROM note_tags WHERE relative_path=?1",
+                "SELECT COALESCE(group_concat(value, ' '), '') FROM notes n, json_each(n.tags) WHERE n.relative_path=?1",
                 params![relative_path], |row| row.get(0),
             ).map_err(io::Error::other)?;
             tx.execute(
@@ -1221,21 +1083,17 @@ impl MemoFile {
         let mut sql = String::from("SELECT n.relative_path FROM notes n WHERE 1=1");
         let mut args: Vec<SqlValue> = Vec::new();
         match filter {
-            "todos" => sql.push_str(
-                " AND EXISTS (SELECT 1 FROM note_todos t WHERE t.relative_path=n.relative_path)",
-            ),
-            "agents" => sql.push_str(
-                " AND EXISTS (SELECT 1 FROM note_agents a WHERE a.relative_path=n.relative_path)",
-            ),
+            "todos" => sql.push_str(" AND json_array_length(n.todos)>0"),
+            "agents" => sql.push_str(" AND json_array_length(n.agents)>0"),
             "favorited" => sql.push_str(" AND n.favorited=1"),
             "tagged" => {
                 if let Some(tag) = tag_id {
-                    sql.push_str(" AND EXISTS (SELECT 1 FROM note_tags t WHERE t.relative_path=n.relative_path AND (t.tag=? OR substr(t.tag,1,length(?)+1)=?))");
+                    sql.push_str(" AND EXISTS (SELECT 1 FROM json_each(n.tags) t WHERE t.value=? OR substr(t.value,1,length(?)+1)=?)");
                     args.push(tag.to_owned().into());
                     args.push(tag.to_owned().into());
                     args.push(format!("{tag}/").into());
                 } else {
-                    sql.push_str(" AND EXISTS (SELECT 1 FROM note_tags t WHERE t.relative_path=n.relative_path)");
+                    sql.push_str(" AND json_array_length(n.tags)>0");
                 }
             }
             "thisWeek" | "thisMonth" => {
@@ -1319,69 +1177,6 @@ impl MemoFile {
             .collect()
     }
 
-    /// Adapt the path-keyed list to the current ID-bearing API while migration
-    /// of external callers is still in progress.
-    pub(crate) fn list_note_entries_with_legacy_ids(
-        &self,
-        notebook_id: &str,
-    ) -> io::Result<Option<Vec<MemoIndexEntry>>> {
-        if !self.note_index_is_ready(notebook_id)? {
-            return Ok(None);
-        }
-        let entries = self.read_note_entries(notebook_id)?;
-        let conn = self.open_note_index_connection(notebook_id)?;
-        let legacy_table: i64 = conn
-            .query_row(
-                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='memos'",
-                [],
-                |row| row.get(0),
-            )
-            .map_err(io::Error::other)?;
-        if legacy_table == 0 {
-            return Ok(None);
-        }
-        let mut stmt = conn
-            .prepare("SELECT relative_path, id FROM memos WHERE notebook_id=?1")
-            .map_err(io::Error::other)?;
-        let mappings = stmt
-            .query_map(params![notebook_id], |row| {
-                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
-            })
-            .map_err(io::Error::other)?
-            .collect::<Result<HashMap<_, _>, _>>()
-            .map_err(io::Error::other)?;
-        if entries.len() != mappings.len() {
-            return Ok(None);
-        }
-        let mut adapted = Vec::with_capacity(entries.len());
-        for entry in entries {
-            let Some(id) = mappings.get(&entry.relative_path) else {
-                return Ok(None);
-            };
-            adapted.push(MemoIndexEntry {
-                id: id.clone(),
-                filename: entry
-                    .relative_path
-                    .rsplit('/')
-                    .next()
-                    .unwrap_or(&entry.relative_path)
-                    .to_owned(),
-                relative_path: entry.relative_path,
-                preview: entry.preview,
-                thumbnail: entry.thumbnail.clone(),
-                tags: entry.tags,
-                todos: entry.todos,
-                agents: entry.agents,
-                created_at: entry.created_at,
-                updated_at: entry.updated_at,
-                favorited: entry.favorited,
-                icon: entry.icon,
-                colors: entry.colors,
-                properties: entry.properties,
-            });
-        }
-        Ok(Some(adapted))
-    }
     pub(crate) fn note_index_is_ready(&self, notebook_id: &str) -> io::Result<bool> {
         let conn = self.open_note_index_connection(notebook_id)?;
         let mut stmt = conn.prepare(
@@ -1402,6 +1197,32 @@ impl MemoFile {
                 .is_some_and(|value| value == &PARSER_VERSION.to_string()))
     }
 
+    /// Read a completed projection without creating directories, tables or scans.
+    /// Absence, an unfinished build, and an obsolete parser return unknown.
+    pub fn cached_note_count(&self, notebook_id: &str) -> io::Result<Option<usize>> {
+        let notebook = self.get_notebook_config_by_id(notebook_id)
+            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "notebook not found"))?;
+        let path = Path::new(&notebook.path).join(".flowix/notebook.db");
+        if !path.is_file() { return Ok(None); }
+        let conn = Connection::open_with_flags(path, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY)
+            .map_err(io::Error::other)?;
+        conn.busy_timeout(Duration::from_millis(50)).map_err(io::Error::other)?;
+        let has_projection: bool = conn.query_row(
+            "SELECT COUNT(*)=2 FROM sqlite_master WHERE type='table' AND name IN ('note_index_meta', 'notes')",
+            [], |row| row.get(0),
+        ).map_err(io::Error::other)?;
+        if !has_projection { return Ok(None); }
+        let ready: bool = conn.query_row(
+            "SELECT EXISTS(SELECT 1 FROM note_index_meta WHERE key='build_state' AND value='ready')
+             AND EXISTS(SELECT 1 FROM note_index_meta WHERE key='parser_version' AND value=?1)",
+            [PARSER_VERSION.to_string()], |row| row.get(0),
+        ).map_err(io::Error::other)?;
+        if !ready { return Ok(None); }
+        let count: i64 = conn.query_row("SELECT COUNT(*) FROM notes", [], |row| row.get(0))
+            .map_err(io::Error::other)?;
+        Ok(Some(usize::try_from(count).unwrap_or(0)))
+    }
+
     pub(crate) fn note_count(&self, notebook_id: &str) -> io::Result<usize> {
         let conn = self.open_note_index_connection(notebook_id)?;
         let count: i64 = conn
@@ -1451,11 +1272,11 @@ impl MemoFile {
             Ok(usize::try_from(value).unwrap_or(0))
         };
         let total = count("SELECT COUNT(*) FROM notes")?;
-        let agents = count("SELECT COUNT(DISTINCT relative_path) FROM note_agents")?;
-        let todos = count("SELECT COUNT(DISTINCT relative_path) FROM note_todos")?;
+        let agents = count("SELECT COUNT(*) FROM notes WHERE json_array_length(agents)>0")?;
+        let todos = count("SELECT COUNT(*) FROM notes WHERE json_array_length(todos)>0")?;
         let mut stmt = conn
             .prepare(
-                "SELECT tag, COUNT(*) FROM note_tags GROUP BY tag ORDER BY tag COLLATE NOCASE ASC",
+                "SELECT t.value, COUNT(DISTINCT n.relative_path) FROM notes n, json_each(n.tags) t GROUP BY t.value ORDER BY t.value COLLATE NOCASE ASC",
             )
             .map_err(io::Error::other)?;
         let tags = stmt
@@ -1478,7 +1299,7 @@ impl MemoFile {
     ) -> io::Result<Vec<(String, String)>> {
         let conn = self.open_note_index_connection(notebook_id)?;
         let mut stmt = conn
-            .prepare("SELECT tag, relative_path FROM note_tags")
+            .prepare("SELECT t.value, n.relative_path FROM notes n, json_each(n.tags) t")
             .map_err(io::Error::other)?;
         let pairs = stmt
             .query_map([], |row| {
@@ -1490,350 +1311,54 @@ impl MemoFile {
         pairs
     }
 
-    /// Move note properties that may exist only in the legacy index into the
-    /// Markdown frontmatter. Existing file properties always win.
-    pub fn migrate_note_properties_for_notebook(
-        &self,
-        notebook_id: &str,
-    ) -> io::Result<NotePropertyMigrationReport> {
-        let _write_guard = self.acquire_cross_process_write_lock()?;
-        let _index_guard = self.current_index_io.lock().expect("index_io poisoned");
-        let root = self
-            .get_notebook_config_by_id(notebook_id)
-            .map(|config| std::path::PathBuf::from(config.path))
-            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "notebook not found"))?;
+    /// Drop the obsolete Memo-ID projection after rebuilding the path index from Markdown.
+    /// Derived tags, todos, agents, colors, and properties come from the source files.
+    pub fn retire_legacy_memo_index(&self, notebook_id: &str) -> io::Result<()> {
+        self.initialize_note_index_schema(notebook_id)?;
         let conn = self.open_note_index_connection(notebook_id)?;
-        let complete: Option<String> = conn
+        let retired: Option<String> = conn
             .query_row(
-                "SELECT value FROM note_index_meta WHERE key='note_properties_migrated'",
+                "SELECT value FROM note_index_meta WHERE key='legacy_memo_index_retired'",
                 [],
                 |row| row.get(0),
             )
             .optional()
             .map_err(io::Error::other)?;
-        if complete.as_deref() == Some("1") {
-            return Ok(NotePropertyMigrationReport::default());
-        }
-        let has_legacy: i64 = conn
-            .query_row(
-                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='memos'",
-                [],
-                |row| row.get(0),
-            )
-            .map_err(io::Error::other)?;
-        if has_legacy == 0 {
-            conn.execute(
-                "INSERT INTO note_index_meta (key, value) VALUES ('note_properties_migrated','1') \
-                ON CONFLICT(key) DO UPDATE SET value='1'",
-                [],
-            )
-            .map_err(io::Error::other)?;
-            return Ok(NotePropertyMigrationReport::default());
-        }
-        let mut statement = conn
-            .prepare(
-                "SELECT id, relative_path, created_at, favorited, icon, properties \
-             FROM memos WHERE notebook_id=?1 ORDER BY relative_path",
-            )
-            .map_err(io::Error::other)?;
-        let notes = statement
-            .query_map(params![notebook_id], |row| {
-                Ok(LegacyNoteProperties {
-                    id: row.get(0)?,
-                    relative_path: row.get(1)?,
-                    created_at: row.get(2)?,
-                    favorited: row.get::<_, i64>(3)? != 0,
-                    icon: row.get(4)?,
-                    properties_json: row.get(5)?,
-                })
-            })
-            .map_err(io::Error::other)?
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(io::Error::other)?;
-        drop(statement);
-        let legacy_created_times: Vec<_> = notes
-            .iter()
-            .filter(|note| note.created_at > 0)
-            .map(|note| (note.relative_path.clone(), note.created_at))
-            .collect();
-        let mut report = NotePropertyMigrationReport::default();
-        for note in notes {
-            let stored_properties: serde_json::Value = serde_json::from_str(&note.properties_json)
-                .map_err(|error| {
-                    io::Error::new(
-                        io::ErrorKind::InvalidData,
-                        format!(
-                            "invalid legacy properties for {}: {error}",
-                            note.relative_path
-                        ),
-                    )
-                })?;
-            let stored_properties = stored_properties.as_object().ok_or_else(|| {
-                io::Error::new(
-                    io::ErrorKind::InvalidData,
-                    format!(
-                        "legacy properties are not an object for {}",
-                        note.relative_path
-                    ),
-                )
-            })?;
-            let path = notebook_path_from_relative(&root, &note.relative_path)
-                .map_err(io::Error::other)?;
-            let original = fs::read_to_string(&path)?;
-            let metadata = super::extract_document_metadata(&original)
-                .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error.to_string()))?;
-            let existing = metadata.properties.as_object().ok_or_else(|| {
-                io::Error::new(io::ErrorKind::InvalidData, "frontmatter is not a mapping")
-            })?;
-            let mut values = serde_json::Map::new();
-            if note.favorited && !existing.contains_key("flowix_favorited") {
-                values.insert("flowix_favorited".into(), serde_json::json!(true));
-            }
-            if let Some(icon) = note.icon.filter(|value| !value.is_empty()) {
-                if !existing.contains_key("flowix_icon") {
-                    values.insert("flowix_icon".into(), serde_json::json!(icon));
-                }
-            }
-            if !existing.contains_key("flowix_colors") {
-                let mut colors = conn
-                    .prepare("SELECT color FROM memo_colors WHERE memo_id=?1 ORDER BY position")
-                    .map_err(io::Error::other)?
-                    .query_map(params![note.id], |row| row.get::<_, String>(0))
-                    .map_err(io::Error::other)?
-                    .collect::<Result<Vec<_>, _>>()
-                    .map_err(io::Error::other)?;
-                if !colors.is_empty() {
-                    values.insert(
-                        "flowix_colors".into(),
-                        serde_json::json!(std::mem::take(&mut colors)),
-                    );
-                }
-            }
-            for (key, value) in stored_properties {
-                if key != "key"
-                    && key != "flowix_key"
-                    && key != "flowix_created_at"
-                    && !existing.contains_key(key)
-                    && !values.contains_key(key)
-                {
-                    values.insert(key.clone(), value.clone());
-                }
-            }
-            if values.is_empty() {
-                continue;
-            }
-            let mut overrides = super::MergeOverrides::new();
-            for (key, value) in &values {
-                if key.is_empty() || key.contains(['\n', '\r']) {
-                    return Err(io::Error::new(
-                        io::ErrorKind::InvalidData,
-                        format!("invalid legacy property name in {}", note.relative_path),
-                    ));
-                }
-                let yaml_key = if key
-                    .chars()
-                    .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-')
-                {
-                    key.clone()
-                } else {
-                    serde_json::to_string(key).map_err(io::Error::other)?
-                };
-                overrides.insert(yaml_key, value.to_string());
-            }
-            let updated = super::merge_frontmatter(&original, &overrides);
-            let readback = super::extract_document_metadata(&updated)
-                .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error.to_string()))?;
-            for (key, value) in &values {
-                if readback.properties.get(key) != Some(value) {
-                    return Err(io::Error::new(
-                        io::ErrorKind::InvalidData,
-                        format!("property {key} readback failed for {}", note.relative_path),
-                    ));
-                }
-            }
-            if fs::read_to_string(&path)? != original {
-                return Err(io::Error::new(
-                    io::ErrorKind::WouldBlock,
-                    format!(
-                        "note changed during property migration: {}",
-                        note.relative_path
-                    ),
-                ));
-            }
-            super::atomic_write_bytes(&path, updated.as_bytes())?;
-            report.notes_written += 1;
-            report.properties_written += values.len();
-        }
-        // Creation time remains index metadata. Seed it from the old index
-        // once, without changing the Markdown file for this field.
-        for (relative_path, created_at) in legacy_created_times {
-            self.refresh_note_path(notebook_id, &relative_path)?;
-            conn.execute(
-                "UPDATE notes SET created_at=?2 WHERE relative_path=?1",
-                params![relative_path, created_at],
-            )
-            .map_err(io::Error::other)?;
+        if retired.as_deref() == Some("1") {
+            return Ok(());
         }
-        conn.execute(
-            "INSERT INTO note_index_meta (key, value) VALUES ('note_properties_migrated','1') \
-            ON CONFLICT(key) DO UPDATE SET value='1'",
-            [],
+        conn.execute_batch(
+            "BEGIN IMMEDIATE;
+             DELETE FROM notes;
+             DELETE FROM note_index_meta WHERE key='parser_version';
+             COMMIT;",
         )
         .map_err(io::Error::other)?;
-        Ok(report)
-    }
-
-    /// Persist non-derivable legacy task attributes in their Markdown note.
-    /// The migration is idempotent. A mismatched task ID or conflicting
-    /// frontmatter value aborts before writing that note.
-    pub fn migrate_note_todo_metadata_for_notebook(
-        &self,
-        notebook_id: &str,
-    ) -> io::Result<NoteTodoMigrationReport> {
-        let _write_guard = self.acquire_cross_process_write_lock()?;
-        let _index_guard = self.current_index_io.lock().expect("index_io poisoned");
-        let root = self
-            .get_notebook_config_by_id(notebook_id)
-            .map(|config| std::path::PathBuf::from(config.path))
-            .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "notebook not found"))?;
+        drop(conn);
+        self.reconcile_note_index_blocking(notebook_id)?;
         let conn = self.open_note_index_connection(notebook_id)?;
-        let complete: Option<String> = conn
-            .query_row(
-                "SELECT value FROM note_index_meta WHERE key='todo_metadata_migrated'",
-                [],
-                |row| row.get(0),
-            )
-            .optional()
-            .map_err(io::Error::other)?;
-        if complete.as_deref() == Some("1") {
-            return Ok(NoteTodoMigrationReport::default());
-        }
-        let has_legacy: i64 = conn
-            .query_row(
-                "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='memo_todos'",
-                [],
-                |row| row.get(0),
-            )
-            .map_err(io::Error::other)?;
-        if has_legacy == 0 {
-            conn.execute(
-                "INSERT INTO note_index_meta (key, value) VALUES ('todo_metadata_migrated', '1') \
-                          ON CONFLICT(key) DO UPDATE SET value='1'",
-                [],
-            )
-            .map_err(io::Error::other)?;
-            return Ok(NoteTodoMigrationReport::default());
-        }
-        let mut stmt = conn
-            .prepare("SELECT m.relative_path, t.todo_id, t.priority, t.time_range, t.owner, t.assignee, \
-                      t.created_at, t.updated_at FROM memo_todos t \
-                      JOIN memos m ON m.id=t.memo_id WHERE m.notebook_id=?1 ORDER BY m.relative_path, t.position")
-            .map_err(io::Error::other)?;
-        let rows = stmt
-            .query_map(params![notebook_id], |row| {
-                Ok((
-                    row.get::<_, String>(0)?,
-                    LegacyTodoAttributes {
-                        todo_id: row.get(1)?,
-                        priority: row.get(2)?,
-                        time_range: row.get(3)?,
-                        owner: row.get(4)?,
-                        assignee: row.get(5)?,
-                        created_at: row.get(6)?,
-                        updated_at: row.get(7)?,
-                    },
-                ))
-            })
-            .map_err(io::Error::other)?;
-        let mut by_path: BTreeMap<String, Vec<LegacyTodoAttributes>> = BTreeMap::new();
-        for row in rows {
-            let (path, attributes) = row.map_err(io::Error::other)?;
-            if attributes.has_persistent_value() {
-                by_path.entry(path).or_default().push(attributes);
-            }
-        }
-        drop(stmt);
-        let mut report = NoteTodoMigrationReport::default();
-        for (relative_path, attributes) in by_path {
-            let path =
-                notebook_path_from_relative(&root, &relative_path).map_err(io::Error::other)?;
-            let original = fs::read_to_string(&path)?;
-            let with_ids = super::ensure_todo_ids_in_content(&original);
-            let todos = super::extract_todos_from_body(&with_ids);
-            let known_ids: HashSet<String> = todos.iter().map(|todo| todo.id.clone()).collect();
-            if known_ids.len() != todos.len() {
-                return Err(io::Error::new(
-                    io::ErrorKind::InvalidData,
-                    format!("duplicate task IDs in {relative_path}"),
-                ));
-            }
-            let mut metadata = super::extract_document_metadata(&with_ids)
-                .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error.to_string()))?
-                .properties
-                .get("flowix_todo_metadata")
-                .and_then(serde_json::Value::as_object)
-                .cloned()
-                .unwrap_or_default();
-            for attribute in &attributes {
-                if !known_ids.contains(&attribute.todo_id) {
-                    return Err(io::Error::new(
-                        io::ErrorKind::InvalidData,
-                        format!(
-                            "legacy task {} is missing from {}",
-                            attribute.todo_id, relative_path
-                        ),
-                    ));
-                }
-                let value = attribute.json_value();
-                if let Some(existing) = metadata.get(&attribute.todo_id) {
-                    if existing != &value {
-                        return Err(io::Error::new(
-                            io::ErrorKind::InvalidData,
-                            format!(
-                                "task metadata conflict for {} in {}",
-                                attribute.todo_id, relative_path
-                            ),
-                        ));
-                    }
-                } else {
-                    metadata.insert(attribute.todo_id.clone(), value);
-                }
-            }
-            let mut overrides = HashMap::new();
-            overrides.insert(
-                "flowix_todo_metadata".to_owned(),
-                serde_json::Value::Object(metadata.clone()).to_string(),
-            );
-            let updated = super::merge_frontmatter(&with_ids, &overrides.into_iter().collect());
-            let readback = super::extract_document_metadata(&updated)
-                .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error.to_string()))?;
-            if readback.properties.get("flowix_todo_metadata")
-                != Some(&serde_json::Value::Object(metadata))
-            {
-                return Err(io::Error::new(
-                    io::ErrorKind::InvalidData,
-                    format!("task metadata readback failed for {relative_path}"),
-                ));
-            }
-            if updated != original {
-                if fs::read_to_string(&path)? != original {
-                    return Err(io::Error::new(
-                        io::ErrorKind::WouldBlock,
-                        format!("note changed during task metadata migration: {relative_path}"),
-                    ));
-                }
-                super::atomic_write_bytes(&path, updated.as_bytes())?;
-                report.notes_written += 1;
-                report.tasks_written += attributes.len();
-            }
-        }
-        conn.execute(
-            "INSERT INTO note_index_meta (key, value) VALUES ('todo_metadata_migrated', '1') \
-                      ON CONFLICT(key) DO UPDATE SET value='1'",
-            [],
+        conn.execute_batch(
+            "BEGIN IMMEDIATE;
+             DROP TABLE IF EXISTS memo_content_revisions;
+             DROP TABLE IF EXISTS memo_agents;
+             DROP TABLE IF EXISTS memo_colors;
+             DROP TRIGGER IF EXISTS trg_memo_tags_register_notebook_tag;
+             DROP TABLE IF EXISTS memo_tags;
+             DROP TABLE IF EXISTS memo_todos;
+             DROP TABLE IF EXISTS pending_external_memo_creates;
+             DROP TABLE IF EXISTS notebook_tags;
+             DROP TABLE IF EXISTS memos;
+             DROP TABLE IF EXISTS memo_lifecycles;
+             DROP TABLE IF EXISTS memo_index_state;
+             DROP TABLE IF EXISTS notebook_data_migrations;
+             DROP TABLE IF EXISTS schema_migrations;
+             INSERT INTO note_index_meta (key, value)
+               VALUES ('legacy_memo_index_retired', '1')
+               ON CONFLICT(key) DO UPDATE SET value='1';
+             COMMIT;",
         )
         .map_err(io::Error::other)?;
-        Ok(report)
+        Ok(())
     }
 
     /// Reconcile one notebook's Note projection with files on disk. Existing
@@ -1844,7 +1369,7 @@ impl MemoFile {
     /// already reconciling the same notebook, so a background refresh never
     /// turns into a spurious 5s timeout error. The next read pass retries.
     pub fn reconcile_note_index(&self, notebook_id: &str) -> io::Result<NoteIndexReconcileReport> {
-        self.reconcile_note_index_inner(notebook_id, false, true)
+        self.reconcile_note_index_inner(notebook_id, false, MaintenanceAdmission::SkipIfBusy, &|| true)
     }
 
     /// Hash every file, including entries whose size and mtime are unchanged.
@@ -1854,7 +1379,7 @@ impl MemoFile {
     /// maintenance lock rather than skipping, so the caller can rely on a full
     /// pass having completed.
     pub fn verify_note_index(&self, notebook_id: &str) -> io::Result<NoteIndexReconcileReport> {
-        self.reconcile_note_index_inner(notebook_id, true, false)
+        self.reconcile_note_index_inner(notebook_id, true, MaintenanceAdmission::Wait, &|| true)
     }
 
     /// Blocking reconcile used by short-lived CLI/MCP processes that need an
@@ -1867,7 +1392,7 @@ impl MemoFile {
         &self,
         notebook_id: &str,
     ) -> io::Result<NoteIndexReconcileReport> {
-        self.reconcile_note_index_inner(notebook_id, false, false)
+        self.reconcile_note_index_inner(notebook_id, false, MaintenanceAdmission::Wait, &|| true)
     }
 
     /// Enumerate Markdown note paths directly from the notebook tree without
@@ -1937,13 +1462,32 @@ impl MemoFile {
         )
     }
 
+    /// Upgrade only the rebuildable projection in place. Never replace the
+    /// shared notebook database, which also owns media properties/revisions.
+    pub fn prepare_background_note_projection(&self, notebook_id: &str) -> io::Result<()> {
+        let Some(_guard) = self.operation_locks().try_notebook_maintenance(notebook_id, "prepare_note_projection")? else {
+            return Err(io::Error::new(io::ErrorKind::WouldBlock, "notebook maintenance is busy"));
+        };
+        self.open_note_index_connection_unchecked(notebook_id, true)?;
+        Ok(())
+    }
+
+    /// Cooperative desktop maintenance. Locks and transactions remain per file;
+    /// cancellation leaves an incomplete cold index explicitly unavailable.
+    pub fn reconcile_note_index_background(
+        &self, notebook_id: &str, keep_running: &dyn Fn() -> bool,
+    ) -> io::Result<NoteIndexReconcileReport> {
+        self.reconcile_note_index_inner(notebook_id, false, MaintenanceAdmission::FailIfBusy, keep_running)
+    }
+
     fn reconcile_note_index_inner(
         &self,
         notebook_id: &str,
         verify_hashes: bool,
-        skip_if_busy: bool,
+        admission: MaintenanceAdmission,
+        keep_running: &dyn Fn() -> bool,
     ) -> io::Result<NoteIndexReconcileReport> {
-        let _maintenance_guard = if skip_if_busy {
+        let _maintenance_guard = if !matches!(admission, MaintenanceAdmission::Wait) {
             let Some(guard) = self
                 .operation_locks()
                 .try_notebook_maintenance(notebook_id, "reconcile_note_index")?
@@ -1952,6 +1496,9 @@ impl MemoFile {
                     notebook_id,
                     "note index reconcile skipped: another maintenance pass is in progress"
                 );
+                if matches!(admission, MaintenanceAdmission::FailIfBusy) {
+                    return Err(io::Error::new(io::ErrorKind::WouldBlock, "notebook maintenance is busy"));
+                }
                 return Ok(NoteIndexReconcileReport::default());
             };
             guard
@@ -1981,12 +1528,13 @@ impl MemoFile {
             .map_err(io::Error::other)?
             .and_then(|value| value.parse().ok());
         let reparse_all = parser_version != Some(PARSER_VERSION);
-        conn.execute(
-            "INSERT INTO note_index_meta (key, value) VALUES ('build_state', 'building') \
-                      ON CONFLICT(key) DO UPDATE SET value='building'",
-            [],
-        )
-        .map_err(io::Error::other)?;
+        // A warm refresh must not make existing lists unavailable while scanning.
+        if reparse_all || !self.note_index_is_ready(notebook_id)? {
+            conn.execute(
+                "INSERT INTO note_index_meta (key, value) VALUES ('build_state', 'building') \
+                 ON CONFLICT(key) DO UPDATE SET value='building'", [],
+            ).map_err(io::Error::other)?;
+        }
         let mut seen = HashSet::new();
         let mut report = NoteIndexReconcileReport::default();
         let policy = self.file_management_policy(notebook_id);
@@ -2004,6 +1552,9 @@ impl MemoFile {
                         .unwrap_or(false)
             })
         {
+            if !keep_running() {
+                return Err(io::Error::new(io::ErrorKind::Interrupted, "index maintenance cancelled"));
+            }
             let entry = entry.map_err(io::Error::other)?;
             if !entry.file_type().is_file() || !is_markdown_note_path(entry.path()) {
                 continue;
@@ -2030,6 +1581,9 @@ impl MemoFile {
             .map_err(io::Error::other)?;
         drop(stmt);
         for relative in indexed {
+            if !keep_running() {
+                return Err(io::Error::new(io::ErrorKind::Interrupted, "index maintenance cancelled"));
+            }
             if !seen.contains(&relative) {
                 let candidate = notebook_path_from_relative(&root, &relative).map_err(io::Error::other)?;
                 // The scan only nominates stale rows. A file may have appeared
@@ -2121,6 +1675,9 @@ impl MemoFile {
             Err(error) => return Err(error),
         };
         if missing || policy.is_index_ignored_at(root, Path::new(&relative)) {
+            if !root.is_dir() {
+                return Err(io::Error::new(io::ErrorKind::NotFound, "notebook directory unavailable"));
+            }
             tx.execute(
                 "DELETE FROM note_search_fts WHERE relative_path = ?1",
                 params![relative],
@@ -2185,7 +1742,6 @@ impl MemoFile {
             .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
         let title = display_title_from_relative_path(&relative);
         let mut derived = Memo {
-            id: String::new(),
             filename: relative.rsplit('/').next().unwrap_or(&relative).to_owned(),
             relative_path: relative.clone(),
             preview: String::new(),
@@ -2202,13 +1758,14 @@ impl MemoFile {
         };
         super::apply_derived_memo_fields(&mut derived, &content);
         tx.execute(
-                "INSERT INTO notes (relative_path, size_bytes, modified_ns, content_hash, title, preview, thumbnail, properties_json, indexed_at, created_at, updated_at, favorited, icon, colors_json, filename, filename_lower) \
-                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16) \
+                "INSERT INTO notes (relative_path, size_bytes, modified_ns, content_hash, title, preview, thumbnail, properties_json, indexed_at, created_at, updated_at, favorited, icon, colors_json, filename, filename_lower, tags, todos, agents) \
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19) \
                  ON CONFLICT(relative_path) DO UPDATE SET size_bytes=excluded.size_bytes, modified_ns=excluded.modified_ns, \
                  content_hash=excluded.content_hash, title=excluded.title, preview=excluded.preview, thumbnail=excluded.thumbnail, \
                  properties_json=excluded.properties_json, indexed_at=excluded.indexed_at, \
                  created_at=excluded.created_at, updated_at=excluded.updated_at, favorited=excluded.favorited, \
-                 icon=excluded.icon, colors_json=excluded.colors_json, filename=excluded.filename, filename_lower=excluded.filename_lower",
+                 icon=excluded.icon, colors_json=excluded.colors_json, filename=excluded.filename, filename_lower=excluded.filename_lower, \
+                 tags=excluded.tags, todos=excluded.todos, agents=excluded.agents",
                 params![relative, size, modified_ns, hash, title, derived.preview, derived.thumbnail,
                     derived.properties.to_string(),
                     chrono::Utc::now().timestamp_millis(),
@@ -2217,20 +1774,11 @@ impl MemoFile {
                     modified_ns.unwrap_or(0) / 1_000_000,
                     i64::from(derived.favorited), derived.icon,
                      serde_json::to_string(&derived.colors).map_err(io::Error::other)?,
-                     derived.filename, derived.filename.to_lowercase()],
+                     derived.filename, derived.filename.to_lowercase(),
+                     serde_json::to_string(&derived.tags).map_err(io::Error::other)?,
+                     serde_json::to_string(&derived.todos).map_err(io::Error::other)?,
+                     serde_json::to_string(&derived.agents).map_err(io::Error::other)?],
             ).map_err(io::Error::other)?;
-        tx.execute(
-            "DELETE FROM note_tags WHERE relative_path = ?1",
-            params![relative],
-        )
-        .map_err(io::Error::other)?;
-        for tag in &derived.tags {
-            tx.execute(
-                "INSERT INTO note_tags (relative_path, tag) VALUES (?1, ?2)",
-                params![relative, tag],
-            )
-            .map_err(io::Error::other)?;
-        }
         tx.execute(
             "DELETE FROM note_search_fts WHERE relative_path = ?1",
             params![relative],
@@ -2248,45 +1796,6 @@ impl MemoFile {
             ],
         )
         .map_err(io::Error::other)?;
-        tx.execute(
-            "DELETE FROM note_todos WHERE relative_path = ?1",
-            params![relative],
-        )
-        .map_err(io::Error::other)?;
-        for (position, todo) in derived.todos.iter().enumerate() {
-            let attributes = derived
-                .properties
-                .get("flowix_todo_metadata")
-                .and_then(|value| value.get(&todo.id));
-            let string_field = |name| {
-                attributes
-                    .and_then(|value| value.get(name))
-                    .and_then(serde_json::Value::as_str)
-                    .unwrap_or("")
-            };
-            let number_field = |name| {
-                attributes
-                    .and_then(|value| value.get(name))
-                    .and_then(serde_json::Value::as_i64)
-                    .unwrap_or(0)
-            };
-            tx.execute("INSERT INTO note_todos \
-                    (relative_path, position, todo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at) \
-                    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
-                    params![relative, position as i64, todo.id, todo.content, todo.status,
-                        string_field("priority"), string_field("timeRange"), string_field("owner"),
-                        string_field("assignee"), number_field("createdAt"), number_field("updatedAt")])
-                    .map_err(io::Error::other)?;
-        }
-        tx.execute(
-            "DELETE FROM note_agents WHERE relative_path = ?1",
-            params![relative],
-        )
-        .map_err(io::Error::other)?;
-        for (position, agent) in derived.agents.iter().enumerate() {
-            tx.execute("INSERT INTO note_agents (relative_path, position, thread_id, title, agent_type) VALUES (?1, ?2, ?3, ?4, ?5)",
-                    params![relative, position as i64, agent.thread_id, agent.title, agent.agent_type]).map_err(io::Error::other)?;
-        }
         tx.commit().map_err(io::Error::other)?;
         if previous.is_some() {
             report.updated += 1;
@@ -2297,13 +1806,44 @@ impl MemoFile {
     }
 
     pub(crate) fn open_note_index_connection(&self, notebook_id: &str) -> io::Result<Connection> {
+        self.open_note_index_connection_inner(notebook_id, false)
+    }
+
+    /// Upgrade an existing note index only from the version-initialization worker.
+    pub fn initialize_note_index_schema(&self, notebook_id: &str) -> io::Result<()> {
+        self.open_note_index_connection_inner(notebook_id, true)?;
+        Ok(())
+    }
+
+    fn open_note_index_connection_inner(
+        &self,
+        notebook_id: &str,
+        run_legacy_migrations: bool,
+    ) -> io::Result<Connection> {
+        let path = self.notebook_db_path(notebook_id)?;
+        if run_legacy_migrations {
+            super::with_database_rebuild(&path, || {
+                self.open_note_index_connection_unchecked(notebook_id, true)
+            })
+        } else {
+            self.open_note_index_connection_unchecked(notebook_id, false)
+        }
+    }
+
+    fn open_note_index_connection_unchecked(
+        &self,
+        notebook_id: &str,
+        run_legacy_migrations: bool,
+    ) -> io::Result<Connection> {
         let path = self.notebook_db_path(notebook_id)?;
         let mut conn = Connection::open(path).map_err(io::Error::other)?;
         conn.busy_timeout(std::time::Duration::from_secs(10))
             .map_err(io::Error::other)?;
         conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;")
             .map_err(io::Error::other)?;
-        discard_legacy_v2_note_projection(&mut conn)?;
+        if run_legacy_migrations {
+            discard_legacy_v2_note_projection(&mut conn)?;
+        }
         conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; \
             CREATE TABLE IF NOT EXISTS note_index_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL); \
             CREATE TABLE IF NOT EXISTS notes (relative_path TEXT PRIMARY KEY, \
@@ -2311,20 +1851,8 @@ impl MemoFile {
               title TEXT NOT NULL, preview TEXT NOT NULL, thumbnail TEXT, properties_json TEXT NOT NULL, indexed_at INTEGER NOT NULL, \
               created_at INTEGER NOT NULL DEFAULT 0, updated_at INTEGER NOT NULL DEFAULT 0, \
               favorited INTEGER NOT NULL DEFAULT 0, icon TEXT, colors_json TEXT NOT NULL DEFAULT '[]', \
-              filename TEXT NOT NULL DEFAULT '', filename_lower TEXT NOT NULL DEFAULT ''); \
-            CREATE TABLE IF NOT EXISTS note_tags (relative_path TEXT NOT NULL REFERENCES notes(relative_path) ON DELETE CASCADE, \
-              tag TEXT NOT NULL, PRIMARY KEY(relative_path, tag)); \
-            CREATE INDEX IF NOT EXISTS idx_note_tags_tag ON note_tags(tag); \
-            CREATE INDEX IF NOT EXISTS idx_notes_created_page ON notes(favorited DESC, created_at DESC, relative_path DESC); \
-            CREATE INDEX IF NOT EXISTS idx_notes_updated_page ON notes(favorited DESC, updated_at DESC, relative_path DESC); \
-            CREATE TABLE IF NOT EXISTS note_todos (relative_path TEXT NOT NULL REFERENCES notes(relative_path) ON DELETE CASCADE, \
-              position INTEGER NOT NULL, todo_id TEXT NOT NULL, content TEXT NOT NULL, status TEXT NOT NULL, \
-              priority TEXT NOT NULL DEFAULT '', time_range TEXT NOT NULL DEFAULT '', owner TEXT NOT NULL DEFAULT '', \
-              assignee TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL DEFAULT 0, updated_at INTEGER NOT NULL DEFAULT 0, \
-              PRIMARY KEY(relative_path, position)); \
-            CREATE TABLE IF NOT EXISTS note_agents (relative_path TEXT NOT NULL REFERENCES notes(relative_path) ON DELETE CASCADE, \
-              position INTEGER NOT NULL, thread_id TEXT NOT NULL, title TEXT NOT NULL, agent_type TEXT NOT NULL, \
-              PRIMARY KEY(relative_path, position)); \
+              filename TEXT NOT NULL DEFAULT '', filename_lower TEXT NOT NULL DEFAULT '', \
+              tags TEXT NOT NULL DEFAULT '[]', todos TEXT NOT NULL DEFAULT '[]', agents TEXT NOT NULL DEFAULT '[]'); \
             CREATE TABLE IF NOT EXISTS note_content_revisions (notebook_id TEXT NOT NULL, \
               relative_path TEXT NOT NULL, content_hash TEXT NOT NULL, local_revision INTEGER NOT NULL, \
               change_id TEXT NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY(notebook_id, relative_path));")
@@ -2336,55 +1864,62 @@ impl MemoFile {
             );",
         )
         .map_err(io::Error::other)?;
-        for (column, definition) in [
-            ("priority", "TEXT NOT NULL DEFAULT ''"),
-            ("time_range", "TEXT NOT NULL DEFAULT ''"),
-            ("owner", "TEXT NOT NULL DEFAULT ''"),
-            ("assignee", "TEXT NOT NULL DEFAULT ''"),
-            ("created_at", "INTEGER NOT NULL DEFAULT 0"),
-            ("updated_at", "INTEGER NOT NULL DEFAULT 0"),
-        ] {
-            let mut statement = conn
-                .prepare("PRAGMA table_info(note_todos)")
-                .map_err(io::Error::other)?;
-            let names = statement
-                .query_map([], |row| row.get::<_, String>(1))
-                .map_err(io::Error::other)?
-                .collect::<Result<Vec<_>, _>>()
-                .map_err(io::Error::other)?;
-            if !names.iter().any(|name| name == column) {
-                conn.execute_batch(&format!(
-                    "ALTER TABLE note_todos ADD COLUMN {column} {definition}"
-                ))
-                .map_err(io::Error::other)?;
+        if run_legacy_migrations {
+            for (column, definition) in [
+                ("thumbnail", "TEXT"),
+                ("created_at", "INTEGER NOT NULL DEFAULT 0"),
+                ("updated_at", "INTEGER NOT NULL DEFAULT 0"),
+                ("favorited", "INTEGER NOT NULL DEFAULT 0"),
+                ("icon", "TEXT"),
+                ("colors_json", "TEXT NOT NULL DEFAULT '[]'"),
+                ("filename", "TEXT NOT NULL DEFAULT ''"),
+                ("filename_lower", "TEXT NOT NULL DEFAULT ''"),
+                ("tags", "TEXT NOT NULL DEFAULT '[]'"),
+                ("todos", "TEXT NOT NULL DEFAULT '[]'"),
+                ("agents", "TEXT NOT NULL DEFAULT '[]'"),
+            ] {
+                let mut statement = conn
+                    .prepare("PRAGMA table_info(notes)")
+                    .map_err(io::Error::other)?;
+                let names = statement
+                    .query_map([], |row| row.get::<_, String>(1))
+                    .map_err(io::Error::other)?
+                    .collect::<Result<Vec<_>, _>>()
+                    .map_err(io::Error::other)?;
+                if !names.iter().any(|name| name == column) {
+                    conn.execute_batch(&format!(
+                        "ALTER TABLE notes ADD COLUMN {column} {definition}"
+                    ))
+                    .map_err(io::Error::other)?;
+                }
             }
-        }
-        for (column, definition) in [
-            ("thumbnail", "TEXT"),
-            ("created_at", "INTEGER NOT NULL DEFAULT 0"),
-            ("updated_at", "INTEGER NOT NULL DEFAULT 0"),
-            ("favorited", "INTEGER NOT NULL DEFAULT 0"),
-            ("icon", "TEXT"),
-            ("colors_json", "TEXT NOT NULL DEFAULT '[]'"),
-            ("filename", "TEXT NOT NULL DEFAULT ''"),
-            ("filename_lower", "TEXT NOT NULL DEFAULT ''"),
-        ] {
-            let mut statement = conn
-                .prepare("PRAGMA table_info(notes)")
-                .map_err(io::Error::other)?;
-            let names = statement
-                .query_map([], |row| row.get::<_, String>(1))
-                .map_err(io::Error::other)?
-                .collect::<Result<Vec<_>, _>>()
-                .map_err(io::Error::other)?;
-            if !names.iter().any(|name| name == column) {
-                conn.execute_batch(&format!(
-                    "ALTER TABLE notes ADD COLUMN {column} {definition}"
-                ))
+            // Older path projections stored derived values in child tables.
+            // Markdown is authoritative, so do not copy these rows into the
+            // new projection. Force a full parser pass before any query can
+            // rely on the replacement columns, then discard the old tables.
+            let has_table = |name: &str| -> io::Result<bool> {
+                conn.query_row(
+                    "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
+                    [name],
+                    |row| row.get(0),
+                ).map_err(io::Error::other)
+            };
+            let has_legacy_derived_tables = ["note_tags", "note_todos", "note_agents"]
+                .into_iter()
+                .try_fold(false, |found, table| Ok::<_, io::Error>(found || has_table(table)?))?;
+            if has_legacy_derived_tables {
+                conn.execute(
+                    "DELETE FROM note_index_meta WHERE key='parser_version'",
+                    [],
+                )
                 .map_err(io::Error::other)?;
             }
+            conn.execute_batch("DROP TABLE IF EXISTS note_tags; DROP TABLE IF EXISTS note_todos; DROP TABLE IF EXISTS note_agents;")
+                .map_err(io::Error::other)?;
         }
-        conn.execute_batch("CREATE INDEX IF NOT EXISTS idx_notes_filename_page ON notes(favorited DESC, filename_lower ASC, filename ASC, relative_path ASC);")
+        conn.execute_batch("CREATE INDEX IF NOT EXISTS idx_notes_created_page ON notes(favorited DESC, created_at DESC, relative_path DESC); \
+            CREATE INDEX IF NOT EXISTS idx_notes_updated_page ON notes(favorited DESC, updated_at DESC, relative_path DESC); \
+            CREATE INDEX IF NOT EXISTS idx_notes_filename_page ON notes(favorited DESC, filename_lower ASC, filename ASC, relative_path ASC);")
             .map_err(io::Error::other)?;
         conn.execute(
             "INSERT INTO note_index_meta (key, value) VALUES ('schema_version', ?1) \
@@ -2400,10 +1935,18 @@ impl MemoFile {
             )
             .map_err(io::Error::other)?;
         if stored_version != SCHEMA_VERSION.to_string() {
-            return Err(io::Error::new(
-                io::ErrorKind::InvalidData,
-                format!("unsupported Note index schema version: {stored_version}"),
-            ));
+            let legacy_version = stored_version.parse::<i64>().unwrap_or(i64::MAX);
+            if !run_legacy_migrations || legacy_version > SCHEMA_VERSION {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidData,
+                    format!("unsupported Note index schema version: {stored_version}"),
+                ));
+            }
+            conn.execute(
+                "UPDATE note_index_meta SET value = ?1 WHERE key = 'schema_version'",
+                params![SCHEMA_VERSION.to_string()],
+            )
+            .map_err(io::Error::other)?;
         }
         let stored_notebook: Option<String> = conn
             .query_row(
@@ -2471,6 +2014,82 @@ mod tests {
     use super::*;
     use crate::memo_file::NotebookConfig;
 
+    fn background_fixture() -> (tempfile::TempDir, MemoFile, std::path::PathBuf) {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path().join("notebook"); fs::create_dir_all(&root).unwrap();
+        let memo = MemoFile::new(temp.path().join("config"));
+        memo.initialize_current_registry_storage().unwrap();
+        memo.write_notebook_configs(&[NotebookConfig {
+            id: "background".into(), name: "Background".into(), icon: None,
+            path: root.to_string_lossy().into_owned(), is_default: true,
+            sort: 0, created_at: 0, updated_at: 0,
+        }]).unwrap();
+        (temp, memo, root)
+    }
+
+    #[test]
+    fn cached_counts_do_not_create_or_scan_a_cold_notebook() {
+        let (_temp, memo, root) = background_fixture();
+        fs::write(root.join("a.md"), "untouched").unwrap();
+        assert_eq!(memo.cached_note_count("background").unwrap(), None);
+        assert!(!root.join(".flowix/notebook.db").exists());
+    }
+
+    #[test]
+    fn cached_counts_treat_an_old_database_without_projection_as_unknown() {
+        let (_temp, memo, _root) = background_fixture();
+        let path = memo.notebook_db_path("background").unwrap();
+        let conn = Connection::open(&path).unwrap();
+        conn.execute_batch("CREATE TABLE legacy_data (value TEXT); INSERT INTO legacy_data VALUES ('keep');").unwrap();
+        assert_eq!(memo.cached_note_count("background").unwrap(), None);
+        let value: String = conn.query_row("SELECT value FROM legacy_data", [], |row| row.get(0)).unwrap();
+        assert_eq!(value, "keep");
+        let tables: i64 = conn.query_row("SELECT COUNT(*) FROM sqlite_master WHERE name='notes'", [], |row| row.get(0)).unwrap();
+        assert_eq!(tables, 0);
+    }
+
+    #[test]
+    fn background_scan_reports_busy_instead_of_claiming_completion() {
+        let (_temp, memo, _root) = background_fixture();
+        let _guard = memo.operation_locks().notebook_maintenance("background", "test_busy").unwrap();
+        assert_eq!(memo.reconcile_note_index_background("background", &|| true).unwrap_err().kind(), io::ErrorKind::WouldBlock);
+        // Preserve the older passive API's documented skip behavior.
+        assert_eq!(memo.reconcile_note_index("background").unwrap(), NoteIndexReconcileReport::default());
+    }
+
+    #[test]
+    fn cold_tag_queries_request_preparation_without_scanning() {
+        let (_temp, memo, root) = background_fixture();
+        fs::write(root.join("a.md"), "#tag\nbody").unwrap();
+        assert_eq!(memo.read_tag_usage_summary_for_notebook_id(Some("background")).unwrap_err().kind(), io::ErrorKind::WouldBlock);
+        assert_eq!(memo.read_tag_prefix_counts_for_notebook_id(Some("background")).unwrap_err().kind(), io::ErrorKind::WouldBlock);
+        assert_eq!(memo.note_count("background").unwrap(), 0);
+        assert_eq!(memo.cached_note_count("background").unwrap(), None);
+    }
+
+    #[test]
+    fn cancelled_cold_index_can_resume_without_changing_source_files() {
+        let (_temp, memo, root) = background_fixture();
+        fs::write(root.join("a.md"), "# Keep\nbody").unwrap();
+        assert_eq!(memo.reconcile_note_index_background("background", &|| false).unwrap_err().kind(), io::ErrorKind::Interrupted);
+        assert_eq!(memo.cached_note_count("background").unwrap(), None);
+        memo.reconcile_note_index_background("background", &|| true).unwrap();
+        assert_eq!(memo.cached_note_count("background").unwrap(), Some(1));
+        assert_eq!(fs::read_to_string(root.join("a.md")).unwrap(), "# Keep\nbody");
+    }
+
+    #[test]
+    fn cancelled_warm_refresh_keeps_the_previous_projection_readable() {
+        let (_temp, memo, root) = background_fixture();
+        fs::write(root.join("a.md"), "a").unwrap();
+        memo.reconcile_note_index_background("background", &|| true).unwrap();
+        fs::write(root.join("b.md"), "b").unwrap();
+        assert!(memo.reconcile_note_index_background("background", &|| false).is_err());
+        assert_eq!(memo.read_note_entries("background").unwrap().len(), 1);
+        memo.reconcile_note_index_background("background", &|| true).unwrap();
+        assert_eq!(memo.read_note_entries("background").unwrap().len(), 2);
+    }
+
     #[test]
     fn parser_upgrade_repairs_null_tag_properties_without_changing_note() {
         let temp = tempfile::tempdir().unwrap();
@@ -2523,15 +2142,17 @@ mod tests {
             INSERT INTO v2_notes VALUES ('old.md');
             CREATE VIRTUAL TABLE v2_note_search USING fts5(body);
             INSERT INTO v2_note_search (body) VALUES ('old');
-            CREATE TABLE memos (id TEXT PRIMARY KEY);
-            INSERT INTO memos VALUES ('legacy-id');").unwrap();
+            CREATE TABLE memos (relative_path TEXT PRIMARY KEY);
+            INSERT INTO memos VALUES ('legacy-note.md');").unwrap();
         drop(conn);
 
         let conn = store.open_note_index_connection("nb_test").unwrap();
         let note: String = conn.query_row("SELECT relative_path FROM notes", [], |row| row.get(0)).unwrap();
         assert_eq!(note, "current.md");
-        let legacy: String = conn.query_row("SELECT id FROM memos", [], |row| row.get(0)).unwrap();
-        assert_eq!(legacy, "legacy-id");
+        let memo_path: String = conn
+            .query_row("SELECT relative_path FROM memos", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(memo_path, "legacy-note.md");
         let old_tables: i64 = conn.query_row("SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name LIKE 'v2_%'", [], |row| row.get(0)).unwrap();
         assert_eq!(old_tables, 0);
     }
@@ -2677,10 +2298,6 @@ mod tests {
             )
             .unwrap();
         assert_eq!(legacy_tables, 0);
-        assert!(store
-            .list_note_entries_with_legacy_ids("nb_test")
-            .unwrap()
-            .is_none());
         let path_entries = store.read_note_entries("nb_test").unwrap();
         assert_eq!(path_entries.len(), 1);
         assert_eq!(path_entries[0].relative_path, "sub/a.md");
@@ -2705,14 +2322,14 @@ mod tests {
         );
         let tags: i64 = conn
             .query_row(
-                "SELECT COUNT(*) FROM note_tags WHERE tag = 'work'",
+                "SELECT COUNT(*) FROM notes n, json_each(n.tags) t WHERE t.value = 'work'",
                 [],
                 |row| row.get(0),
             )
             .unwrap();
         assert_eq!(tags, 1);
         drop(conn);
-        assert_eq!(store.memo_counts_by_notebook().unwrap()["nb_test"], 1);
+        assert_eq!(store.cached_note_count("nb_test").unwrap(), Some(1));
         assert_eq!(
             store
                 .occupied_filenames_in_directory("nb_test", Some("sub"))
@@ -2775,52 +2392,6 @@ mod tests {
             .is_none());
     }
 
-    #[test]
-    fn legacy_revisions_backfill_into_the_path_keyed_table_once() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path().join("notebook");
-        fs::create_dir_all(&root).unwrap();
-        fs::write(root.join("Legacy.md"), "# Legacy\n").unwrap();
-        let mut store = MemoFile::new(temp.path().join("config"));
-        store
-            .write_notebook_configs(&[NotebookConfig {
-                id: "nb_test".into(),
-                name: "Test".into(),
-                icon: None,
-                path: root.to_string_lossy().into_owned(),
-                is_default: true,
-                sort: 0,
-                created_at: 0,
-                updated_at: 0,
-            }])
-            .unwrap();
-        store.set_current_notebook(Some("nb_test".into()));
-        // Register the file in the legacy id-keyed cache, then commit a
-        // revision through the legacy API.
-        let memo = store
-            .register_existing_file_for_notebook_id("nb_test", &root.join("Legacy.md"))
-            .map_err(|error| error.to_string())
-            .unwrap();
-        store
-            .commit_memo_content_revision(&memo.id, "nb_test", "hash-legacy", "change-legacy")
-            .unwrap();
-
-        // First path-keyed read migrates the legacy row.
-        let revision = store
-            .read_note_content_revision_for_notebook("nb_test", "Legacy.md")
-            .unwrap()
-            .expect("legacy revision must be visible through the path key");
-        assert_eq!(revision.revision, 1);
-        assert_eq!(revision.change_id, "change-legacy");
-
-        // A new path-keyed commit continues the same stream.
-        let commit = store
-            .commit_note_content_revision("nb_test", "Legacy.md", "hash-new", "change-new")
-            .unwrap();
-        assert!(commit.changed);
-        assert_eq!(commit.state.revision, 2);
-    }
-
     #[test]
     fn moves_note_by_path_without_a_legacy_memo_row() {
         let temp = tempfile::tempdir().unwrap();
@@ -2872,7 +2443,7 @@ mod tests {
     }
 
     #[test]
-    fn note_projection_coexists_with_legacy_rows_in_the_same_notebook_db() {
+    fn note_projection_coexists_with_path_keyed_memo_rows_in_the_same_notebook_db() {
         let temp = tempfile::tempdir().unwrap();
         let root = temp.path().join("notebook");
         fs::create_dir_all(&root).unwrap();
@@ -2903,10 +2474,10 @@ mod tests {
         // parser version and reparses that row once.
         assert_eq!(store.reconcile_note_index("nb_test").unwrap().updated, 1);
         let conn = store.open_note_index_connection("nb_test").unwrap();
-        let legacy_id: String = conn
-            .query_row("SELECT id FROM memos", [], |row| row.get(0))
+        let memo_path: String = conn
+            .query_row("SELECT relative_path FROM memos", [], |row| row.get(0))
             .unwrap();
-        assert_eq!(legacy_id, created.id);
+        assert_eq!(memo_path, created.relative_path);
         let note_path: String = conn
             .query_row("SELECT relative_path FROM notes", [], |row| row.get(0))
             .unwrap();
@@ -2914,23 +2485,16 @@ mod tests {
         drop(conn);
         let conn = store.open_memo_index_db_for_notebook_id("nb_test").unwrap();
         conn.execute(
-            "UPDATE memos SET preview='stale legacy preview' WHERE id=?1",
-            params![created.id],
+            "UPDATE memos SET preview='stale memo preview' WHERE relative_path=?1",
+            params![created.relative_path],
         )
         .unwrap();
         drop(conn);
-        let listed = store
-            .list_note_entries_with_legacy_ids("nb_test")
-            .unwrap()
-            .unwrap();
-        assert_eq!(listed.len(), 1);
-        assert_ne!(listed[0].preview, "stale legacy preview");
-        assert_eq!(listed[0].id, created.id);
         let mut service = crate::service::NoteService::new(&store);
         let service_list = service.list("nb_test").unwrap();
-        assert_ne!(service_list[0].preview, "stale legacy preview");
+        assert_ne!(service_list[0].preview, "stale memo preview");
         store
-            .write_memo(&created.id, "# Changed\nnew body\n")
+            .write_memo(&created.relative_path, "# Changed\nnew body\n")
             .unwrap();
         let conn = store.open_note_index_connection("nb_test").unwrap();
         let title: String = conn
@@ -2938,7 +2502,9 @@ mod tests {
             .unwrap();
         assert_eq!(title, "Legacy and Note");
         drop(conn);
-        store.delete_memo_result_global(&created.id).unwrap();
+        store
+            .delete_memo_result_global(&created.relative_path)
+            .unwrap();
         let conn = store.open_note_index_connection("nb_test").unwrap();
         let count: i64 = conn
             .query_row("SELECT COUNT(*) FROM notes", [], |row| row.get(0))
@@ -2946,179 +2512,5 @@ mod tests {
         assert_eq!(count, 0);
     }
 
-    #[test]
-    fn legacy_task_attributes_survive_rebuilding_the_note_projection() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path().join("notebook");
-        fs::create_dir_all(&root).unwrap();
-        let mut store = MemoFile::new(temp.path().join("config"));
-        store
-            .write_notebook_configs(&[NotebookConfig {
-                id: "nb_test".into(),
-                name: "Test".into(),
-                icon: None,
-                path: root.to_string_lossy().into_owned(),
-                is_default: true,
-                sort: 0,
-                created_at: 0,
-                updated_at: 0,
-            }])
-            .unwrap();
-        store.set_current_notebook(Some("nb_test".into()));
-        let created = store
-            .create_memo("Tasks", "- [ ] keep this task\n", None)
-            .unwrap();
-        let conn = store.open_memo_index_db_for_notebook_id("nb_test").unwrap();
-        conn.execute(
-            "UPDATE memo_todos SET priority='high', owner='me', created_at=11 WHERE memo_id=?1",
-            params![created.id],
-        )
-        .unwrap();
-        drop(conn);
 
-        let report = store
-            .migrate_note_todo_metadata_for_notebook("nb_test")
-            .unwrap();
-        assert_eq!(report.notes_written, 1);
-        assert_eq!(report.tasks_written, 1);
-        assert_eq!(
-            store
-                .migrate_note_todo_metadata_for_notebook("nb_test")
-                .unwrap()
-                .notes_written,
-            0
-        );
-        let content = fs::read_to_string(root.join(&created.relative_path)).unwrap();
-        assert!(content.contains("flowix_todo_metadata:"));
-        store.reconcile_note_index("nb_test").unwrap();
-        let conn = store.open_note_index_connection("nb_test").unwrap();
-        let (priority, owner, created_at): (String, String, i64) = conn
-            .query_row(
-                "SELECT priority, owner, created_at FROM note_todos",
-                [],
-                |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
-            )
-            .unwrap();
-        assert_eq!(
-            (priority.as_str(), owner.as_str(), created_at),
-            ("high", "me", 11)
-        );
-        conn.execute("DELETE FROM notes", []).unwrap();
-        drop(conn);
-        store.reconcile_note_index("nb_test").unwrap();
-        let conn = store.open_note_index_connection("nb_test").unwrap();
-        let priority: String = conn
-            .query_row("SELECT priority FROM note_todos", [], |row| row.get(0))
-            .unwrap();
-        assert_eq!(priority, "high");
-    }
-
-    #[test]
-    fn legacy_note_properties_survive_rebuilding_and_file_values_win() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path().join("notebook");
-        fs::create_dir_all(&root).unwrap();
-        let mut store = MemoFile::new(temp.path().join("config"));
-        store
-            .write_notebook_configs(&[NotebookConfig {
-                id: "nb_test".into(),
-                name: "Test".into(),
-                icon: None,
-                path: root.to_string_lossy().into_owned(),
-                is_default: true,
-                sort: 0,
-                created_at: 0,
-                updated_at: 0,
-            }])
-            .unwrap();
-        store.set_current_notebook(Some("nb_test".into()));
-        let created = store
-            .create_memo(
-                "Properties",
-                "---\nflowix_icon: file-icon\n---\n# Properties\n",
-                None,
-            )
-            .unwrap();
-        let conn = store.open_memo_index_db_for_notebook_id("nb_test").unwrap();
-        conn.execute(
-            "UPDATE memos SET created_at=123, favorited=1, icon='index-icon' WHERE id=?1",
-            params![created.id],
-        )
-        .unwrap();
-        conn.execute(
-            "INSERT INTO memo_colors (memo_id,color,position) VALUES (?1,'blue',0)",
-            params![created.id],
-        )
-        .unwrap();
-        drop(conn);
-        let report = store
-            .migrate_note_properties_for_notebook("nb_test")
-            .unwrap();
-        assert_eq!(report.notes_written, 1);
-        let content = fs::read_to_string(root.join(&created.relative_path)).unwrap();
-        let properties = super::super::extract_document_metadata(&content)
-            .unwrap()
-            .properties;
-        assert!(properties.get("flowix_created_at").is_none());
-        assert_eq!(properties["flowix_favorited"], true);
-        assert_eq!(properties["flowix_icon"], "file-icon");
-        assert_eq!(properties["flowix_colors"], serde_json::json!(["blue"]));
-        assert_eq!(
-            store
-                .migrate_note_properties_for_notebook("nb_test")
-                .unwrap()
-                .notes_written,
-            0
-        );
-        store.reconcile_note_index("nb_test").unwrap();
-        let conn = store.open_note_index_connection("nb_test").unwrap();
-        let (created_at, icon): (i64, String) = conn
-            .query_row("SELECT created_at, icon FROM notes", [], |row| {
-                Ok((row.get(0)?, row.get(1)?))
-            })
-            .unwrap();
-        assert_eq!((created_at, icon.as_str()), (123, "file-icon"));
-    }
-
-    #[test]
-    fn legacy_creation_time_stays_in_index_without_changing_markdown() {
-        let temp = tempfile::tempdir().unwrap();
-        let root = temp.path().join("notebook");
-        fs::create_dir_all(&root).unwrap();
-        let mut store = MemoFile::new(temp.path().join("config"));
-        store
-            .write_notebook_configs(&[NotebookConfig {
-                id: "nb_test".into(),
-                name: "Test".into(),
-                icon: None,
-                path: root.to_string_lossy().into_owned(),
-                is_default: true,
-                sort: 0,
-                created_at: 0,
-                updated_at: 0,
-            }])
-            .unwrap();
-        store.set_current_notebook(Some("nb_test".into()));
-        let created = store.create_memo("Plain", "# Plain\n", None).unwrap();
-        let path = root.join(&created.relative_path);
-        let original = fs::read(&path).unwrap();
-        let conn = store.open_memo_index_db_for_notebook_id("nb_test").unwrap();
-        conn.execute(
-            "UPDATE memos SET created_at=123 WHERE id=?1",
-            params![created.id],
-        )
-        .unwrap();
-        drop(conn);
-
-        let report = store
-            .migrate_note_properties_for_notebook("nb_test")
-            .unwrap();
-        assert_eq!(report.notes_written, 0);
-        assert_eq!(fs::read(&path).unwrap(), original);
-        let conn = store.open_note_index_connection("nb_test").unwrap();
-        let created_at: i64 = conn
-            .query_row("SELECT created_at FROM notes", [], |row| row.get(0))
-            .unwrap();
-        assert_eq!(created_at, 123);
-    }
 }
diff --git a/app/flowix-core/src/memo_file/notebook.rs b/app/flowix-core/src/memo_file/notebook.rs
index 1515a65d8..118a6dca2 100644
--- a/app/flowix-core/src/memo_file/notebook.rs
+++ b/app/flowix-core/src/memo_file/notebook.rs
@@ -1,19 +1,20 @@
 //! Notebook registry storage.
 //!
-//! The authoritative notebook registry lives in `index.db` under the user
-//! config directory (`~/.flowix/index.db` in production). Notebook-owned note
+//! The authoritative notebook registry lives in `db/local.db` under the user
+//! config directory (`~/.flowix/db/local.db` in production). Notebook-owned note
 //! and media data live separately in `<notebook>/.flowix/notebook.db`.
 
+use rusqlite::{params, Connection, OptionalExtension, Row};
 use std::collections::HashSet;
 use std::fs;
 use std::path::PathBuf;
-use rusqlite::{params, Connection, OptionalExtension, Row};
 
 use super::file_io::atomic_write_bytes;
+use super::types::NotebookSetupReport;
 use super::types::{
     NotebookConfig, NotebookManifest, NotebookSetupJob, NotebookSetupJobStatus,
+    NotebookSetupSnapshot, NotebookSetupStage,
 };
-use super::types::NotebookSetupReport;
 use super::MemoFile;
 
 pub(super) fn sqlite_to_io(error: rusqlite::Error) -> std::io::Error {
@@ -30,6 +31,25 @@ fn notebook_setup_status_as_str(status: NotebookSetupJobStatus) -> &'static str
     }
 }
 
+fn notebook_setup_stage_as_str(stage: NotebookSetupStage) -> &'static str {
+    match stage {
+        NotebookSetupStage::Preparing => "preparing",
+        NotebookSetupStage::Writing => "writing",
+        NotebookSetupStage::Indexing => "indexing",
+        NotebookSetupStage::Completed => "completed",
+    }
+}
+
+fn notebook_setup_stage_from_str(stage: &str) -> Option<NotebookSetupStage> {
+    match stage {
+        "preparing" | "queued" => Some(NotebookSetupStage::Preparing),
+        "writing" | "template" => Some(NotebookSetupStage::Writing),
+        "indexing" => Some(NotebookSetupStage::Indexing),
+        "completed" => Some(NotebookSetupStage::Completed),
+        _ => None,
+    }
+}
+
 fn map_notebook_setup_job(row: &Row<'_>) -> rusqlite::Result<NotebookSetupJob> {
     let status: String = row.get(2)?;
     let status = match status.as_str() {
@@ -40,23 +60,57 @@ fn map_notebook_setup_job(row: &Row<'_>) -> rusqlite::Result<NotebookSetupJob> {
         "failed" => NotebookSetupJobStatus::Failed,
         _ => return Err(rusqlite::Error::InvalidQuery),
     };
-    let completed_files: i64 = row.get(4)?;
-    let total_files: i64 = row.get(5)?;
-    let report_json: Option<String> = row.get(8)?;
+    let report_json: Option<String> = row.get(6)?;
+    let stage: String = row.get(3)?;
+    let stage = notebook_setup_stage_from_str(&stage).ok_or(rusqlite::Error::InvalidQuery)?;
     Ok(NotebookSetupJob {
         notebook_id: row.get(0)?,
         template_id: row.get(1)?,
         status,
-        stage: row.get(3)?,
-        completed_files: completed_files.max(0) as usize,
-        total_files: total_files.max(0) as usize,
-        message: row.get(6)?,
-        report: report_json.and_then(|json| serde_json::from_str::<NotebookSetupReport>(&json).ok()),
-        updated_at: row.get(7)?,
-        overwrite_existing: row.get::<_, i64>(9)? != 0,
+        stage,
+        message: row.get(4)?,
+        report: report_json
+            .and_then(|json| serde_json::from_str::<NotebookSetupReport>(&json).ok()),
+        updated_at: row.get(5)?,
+        overwrite_existing: row.get::<_, i64>(7)? != 0,
+        revision: row.get(8)?,
+        run_id: row.get(9)?,
+        job_id: row.get(10)?,
+        execution_requested: row.get::<_, i64>(11)? != 0,
     })
 }
 
+fn next_notebook_setup_revision(
+    tx: &rusqlite::Transaction<'_>,
+    updated_at: i64,
+) -> std::io::Result<i64> {
+    tx.execute(
+        "INSERT OR IGNORE INTO app_state (key, value, updated_at) VALUES ('notebook_setup_revision', '0', ?1)",
+        [updated_at],
+    )
+    .map_err(sqlite_to_io)?;
+    tx.execute(
+        "UPDATE app_state SET value = CAST(COALESCE(value, '0') AS INTEGER) + 1, updated_at = ?1 WHERE key = 'notebook_setup_revision'",
+        [updated_at],
+    )
+    .map_err(sqlite_to_io)?;
+    tx.query_row(
+        "SELECT CAST(COALESCE(value, '0') AS INTEGER) FROM app_state WHERE key = 'notebook_setup_revision'",
+        [],
+        |row| row.get(0),
+    )
+    .map_err(sqlite_to_io)
+}
+
+fn current_notebook_setup_revision(conn: &Connection) -> std::io::Result<i64> {
+    conn.query_row(
+        "SELECT CAST(COALESCE(value, '0') AS INTEGER) FROM app_state WHERE key = 'notebook_setup_revision'",
+        [],
+        |row| row.get(0),
+    )
+    .map_err(sqlite_to_io)
+}
+
 impl MemoFile {
     pub const NOTEBOOK_MANIFEST_VERSION: u32 = 1;
 
@@ -164,11 +218,7 @@ impl MemoFile {
         scene_id: &str,
     ) -> std::io::Result<()> {
         Self::ensure_notebook_manifest(config)?;
-        Self::set_notebook_scene_id(
-            std::path::Path::new(&config.path),
-            &config.id,
-            scene_id,
-        )?;
+        Self::set_notebook_scene_id(std::path::Path::new(&config.path), &config.id, scene_id)?;
         Ok(())
     }
 
@@ -189,8 +239,7 @@ impl MemoFile {
         Ok(flowix_dir.join("notebook.db"))
     }
 
-    /// Device-local notebook registry database. The on-disk name remains
-    /// `index.db` for compatibility; it stores registry state, not the active
+    /// Device-local notebook registry database. It stores registry state, not the active
     /// notebook's note catalog.
     pub fn registry_db_path(&self) -> PathBuf {
         self.registry.db_path()
@@ -218,6 +267,65 @@ impl MemoFile {
         Ok(())
     }
 
+    /// Prepare the current registry schema and migrate its database directory.
+    pub fn initialize_registry_storage(&self) -> std::io::Result<()> {
+        super::database_layout::prepare_database_directory(
+            &self.registry.config_dir,
+            &["local.db"],
+        )?;
+        self.initialize_current_registry_storage()
+    }
+
+    /// Prepare only the current store. A completed installation must not inspect
+    /// or copy legacy databases when a runtime dependency needs rebuilding.
+    pub fn initialize_current_registry_storage(&self) -> std::io::Result<()> {
+        super::with_database_rebuild(&self.registry_db_path(), || {
+            let connection = self.registry.open_for_initialization()?;
+            self.workspace_connection()?;
+            self.read_notebook_configs()?;
+            self.read_selected_notebook_id()?;
+            Ok(connection)
+        })?;
+        Ok(())
+    }
+
+    /// Read a completion marker from the device-local migration journal.
+    pub fn local_migration_completed(&self, key: &str) -> std::io::Result<bool> {
+        let connection = self.registry.open()?;
+        connection
+            .query_row(
+                "SELECT EXISTS(SELECT 1 FROM local_migrations WHERE migration_key = ?1)",
+                [key],
+                |row| row.get(0),
+            )
+            .map_err(sqlite_to_io)
+    }
+
+    /// Record a completed device-local migration step.
+    pub fn mark_local_migration_completed(&self, key: &str) -> std::io::Result<()> {
+        let connection = self.registry.open()?;
+        connection
+            .execute(
+                "INSERT OR IGNORE INTO local_migrations (migration_key, completed_at) VALUES (?1, CAST(strftime('%s','now') AS INTEGER) * 1000)",
+                [key],
+            )
+            .map_err(sqlite_to_io)?;
+        Ok(())
+    }
+
+    /// Whether a registered notebook still needs its legacy storage decision.
+    /// Offline notebooks remain pending until their paths can be inspected.
+    pub fn has_pending_notebook_storage_initialization(&self) -> std::io::Result<bool> {
+        for notebook in self.read_notebook_configs()? {
+            for job in super::NotebookInitializationJob::ALL {
+                if !self.local_migration_completed(&job.key(&notebook.id))? {
+                    return Ok(true);
+                }
+            }
+        }
+        Ok(false)
+    }
+
     pub(super) fn open_registry_db(&self) -> std::io::Result<Connection> {
         self.registry.open()
     }
@@ -304,7 +412,7 @@ impl MemoFile {
                 FROM notebooks
                 -- 用户拖拽顺序优先, 然后用 created_at + name 兜底 (旧库未
                 -- normalize 时 sort 全部一致, 仍能保持稳定顺序)。
-                ORDER BY sort ASC, created_at ASC, name COLLATE NOCASE ASC
+                ORDER BY pinned DESC, sort ASC, created_at ASC, name COLLATE NOCASE ASC
                 "#,
             )
             .map_err(sqlite_to_io)?;
@@ -336,6 +444,40 @@ impl MemoFile {
         Ok(configs)
     }
 
+    /// Read device-local pin state for the global notebook selector.
+    pub fn read_notebook_pin_states(&self) -> std::io::Result<HashSet<String>> {
+        let conn = self.open_registry_db()?;
+        let mut stmt = conn
+            .prepare("SELECT id FROM notebooks WHERE pinned = 1")
+            .map_err(sqlite_to_io)?;
+        let pinned_ids = stmt
+            .query_map([], |row| row.get::<_, String>(0))
+            .map_err(sqlite_to_io)?
+            .collect::<Result<HashSet<_>, _>>()
+            .map_err(sqlite_to_io)?;
+        Ok(pinned_ids)
+    }
+
+    /// Update a notebook's device-local pin state without changing its drag order.
+    pub fn set_notebook_pinned(&self, notebook_id: &str, pinned: bool) -> std::io::Result<bool> {
+        let conn = self.open_registry_db()?;
+        let changed = conn
+            .execute(
+                "UPDATE notebooks SET pinned = ?1 WHERE id = ?2",
+                params![if pinned { 1 } else { 0 }, notebook_id],
+            )
+            .map_err(sqlite_to_io)?
+            > 0;
+        if changed {
+            *self
+                .registry
+                .configs_cache
+                .write()
+                .expect("notebook_configs_cache poisoned") = None;
+        }
+        Ok(changed)
+    }
+
     /// Registered notebook directories.
     pub fn registered_notebook_paths(&self) -> Vec<PathBuf> {
         self.read_notebook_configs()
@@ -345,13 +487,89 @@ impl MemoFile {
             .collect()
     }
 
-    /// Synchronize notebook rows in `index.db` without deleting unchanged
+    /// Synchronize notebook rows in `local.db` without deleting unchanged
     /// notebook ids. Deleting and reinserting every row would trigger
     /// `ON DELETE CASCADE` on memo rows for notebooks that still exist.
     pub fn write_notebook_configs(&self, notebooks: &[NotebookConfig]) -> std::io::Result<()> {
         self.write_notebook_configs_with_setup_job(notebooks, None)
     }
 
+    /// Drop legacy notebook display, setup, and external-directory settings
+    /// while keeping the registry identities and their filesystem paths.
+    /// The folder name becomes the display name, icons are cleared, and order
+    /// is rebuilt from the stable path order.
+    pub fn reset_legacy_notebook_settings_for_initialization(&self) -> std::io::Result<()> {
+        let mut conn = self.open_registry_db()?;
+        let tx = conn
+            .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)
+            .map_err(sqlite_to_io)?;
+        tx.execute_batch(
+            "DROP TABLE IF EXISTS notebook_add_dirs;
+             DROP TABLE IF EXISTS notebook_workspace_state;
+             CREATE TABLE notebook_workspace_state (
+                 notebook_id TEXT PRIMARY KEY REFERENCES notebooks(id) ON DELETE CASCADE,
+                 revision INTEGER NOT NULL DEFAULT 0
+             );
+             CREATE TABLE notebook_add_dirs (
+                 id TEXT NOT NULL,
+                 notebook_id TEXT NOT NULL REFERENCES notebooks(id) ON DELETE CASCADE,
+                 path TEXT NOT NULL,
+                 path_key TEXT NOT NULL,
+                 label TEXT NOT NULL,
+                 enabled INTEGER NOT NULL,
+                 sort INTEGER NOT NULL,
+                 created_at INTEGER NOT NULL,
+                 updated_at INTEGER NOT NULL,
+                 PRIMARY KEY(notebook_id,id),
+                 UNIQUE(notebook_id,path_key)
+             );",
+        )
+        .map_err(sqlite_to_io)?;
+        let mut notebooks = {
+            let mut statement = tx
+                .prepare("SELECT id, path FROM notebooks")
+                .map_err(sqlite_to_io)?;
+            let rows = statement
+                .query_map([], |row| {
+                    Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
+                })
+                .map_err(sqlite_to_io)?;
+            rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?
+        };
+        notebooks.sort_by_key(|(_, path)| path.to_lowercase());
+        for (index, (id, path)) in notebooks.iter().enumerate() {
+            let display_name = std::path::Path::new(path)
+                .file_name()
+                .and_then(|name| name.to_str())
+                .filter(|name| !name.is_empty())
+                .unwrap_or("笔记本");
+            tx.execute(
+                "UPDATE notebooks SET name=?1, icon=NULL, sort=?2 WHERE id=?3",
+                rusqlite::params![display_name, (index as i64 + 1) * 10, id],
+            )
+            .map_err(sqlite_to_io)?;
+        }
+
+        tx.execute("DELETE FROM notebook_setup_jobs", [])
+            .map_err(sqlite_to_io)?;
+        tx.execute(
+            "INSERT INTO notebook_workspace_state (notebook_id, revision)
+             SELECT id, 1 FROM notebooks",
+            [],
+        )
+        .map_err(sqlite_to_io)?;
+        tx.execute("DROP TABLE IF EXISTS data_migration_state", [])
+            .map_err(sqlite_to_io)?;
+        tx.commit().map_err(sqlite_to_io)?;
+
+        *self
+            .registry
+            .configs_cache
+            .write()
+            .unwrap_or_else(|poisoned| poisoned.into_inner()) = None;
+        Ok(())
+    }
+
     /// Atomically persist notebook registration and its optional first-open
     /// setup job. This closes the crash window between creating a notebook and
     /// remembering which template it should receive.
@@ -376,7 +594,9 @@ impl MemoFile {
             }
         }
         let mut conn = self.open_registry_db()?;
-        let tx = conn.transaction().map_err(sqlite_to_io)?;
+        let tx = conn
+            .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)
+            .map_err(sqlite_to_io)?;
         {
             let mut stmt = tx
                 .prepare(
@@ -421,14 +641,41 @@ impl MemoFile {
             .map_err(sqlite_to_io)?;
         drop(stmt);
 
+        let mut removed_notebook = false;
         for id in existing_ids {
             if !keep_ids.contains(id.as_str()) {
                 tx.execute("DELETE FROM notebooks WHERE id = ?1", params![id])
                     .map_err(sqlite_to_io)?;
+                removed_notebook = true;
             }
         }
 
+        if removed_notebook {
+            next_notebook_setup_revision(&tx, chrono::Utc::now().timestamp_millis())?;
+        }
+
         if let Some(job) = setup_job {
+            if job.job_id.trim().is_empty() {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::InvalidInput,
+                    "notebook setup job identity is missing",
+                ));
+            }
+            let existing_status: Option<String> = tx
+                .query_row(
+                    "SELECT status FROM notebook_setup_jobs WHERE notebook_id = ?1",
+                    [&job.notebook_id],
+                    |row| row.get(0),
+                )
+                .optional()
+                .map_err(sqlite_to_io)?;
+            if existing_status.as_deref() == Some("running") {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::Interrupted,
+                    "NOTEBOOK_TEMPLATE_SETUP_IN_PROGRESS",
+                ));
+            }
+            let revision = next_notebook_setup_revision(&tx, job.updated_at)?;
             let status = notebook_setup_status_as_str(job.status);
             let report_json = job
                 .report
@@ -439,30 +686,34 @@ impl MemoFile {
             tx.execute(
                 r#"
                 INSERT INTO notebook_setup_jobs
-                    (notebook_id, template_id, status, stage, completed_files, total_files, message, report_json, updated_at, overwrite_existing)
-                VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
+                    (notebook_id, template_id, status, stage, message, report_json, updated_at, overwrite_existing, revision, run_id, job_id, execution_requested)
+                VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
                 ON CONFLICT(notebook_id) DO UPDATE SET
                     template_id = excluded.template_id,
                     status = excluded.status,
                     stage = excluded.stage,
-                    completed_files = excluded.completed_files,
-                    total_files = excluded.total_files,
                     message = excluded.message,
                     report_json = excluded.report_json,
                     updated_at = excluded.updated_at,
-                    overwrite_existing = excluded.overwrite_existing
+                    overwrite_existing = excluded.overwrite_existing,
+                    revision = excluded.revision,
+                    run_id = excluded.run_id,
+                    job_id = excluded.job_id,
+                    execution_requested = excluded.execution_requested
                 "#,
                 params![
                     job.notebook_id,
                     job.template_id,
                     status,
-                    job.stage,
-                    job.completed_files as i64,
-                    job.total_files as i64,
+                    notebook_setup_stage_as_str(job.stage),
                     job.message,
                     report_json,
                     job.updated_at,
                     if job.overwrite_existing { 1 } else { 0 },
+                    revision,
+                    job.run_id,
+                    job.job_id,
+                    if job.execution_requested { 1 } else { 0 },
                 ],
             )
             .map_err(sqlite_to_io)?;
@@ -478,11 +729,14 @@ impl MemoFile {
         Ok(())
     }
 
-    pub fn get_notebook_setup_job(&self, notebook_id: &str) -> std::io::Result<Option<NotebookSetupJob>> {
+    pub fn get_notebook_setup_job(
+        &self,
+        notebook_id: &str,
+    ) -> std::io::Result<Option<NotebookSetupJob>> {
         let conn = self.open_registry_db()?;
         conn.query_row(
-            r#"SELECT notebook_id, template_id, status, stage, completed_files,
-                      total_files, message, updated_at, report_json, overwrite_existing
+            r#"SELECT notebook_id, template_id, status, stage, message, updated_at,
+                      report_json, overwrite_existing, revision, run_id, job_id, execution_requested
                FROM notebook_setup_jobs WHERE notebook_id = ?1"#,
             [notebook_id],
             map_notebook_setup_job,
@@ -495,8 +749,8 @@ impl MemoFile {
         let conn = self.open_registry_db()?;
         let mut statement = conn
             .prepare(
-                r#"SELECT notebook_id, template_id, status, stage, completed_files,
-                          total_files, message, updated_at, report_json, overwrite_existing
+                r#"SELECT notebook_id, template_id, status, stage, message, updated_at,
+                          report_json, overwrite_existing, revision, run_id, job_id, execution_requested
                    FROM notebook_setup_jobs"#,
             )
             .map_err(sqlite_to_io)?;
@@ -506,45 +760,138 @@ impl MemoFile {
         rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)
     }
 
-    pub fn write_notebook_setup_job(&self, job: &NotebookSetupJob) -> std::io::Result<()> {
-        let conn = self.open_registry_db()?;
+    pub fn get_notebook_setup_snapshot(&self) -> std::io::Result<NotebookSetupSnapshot> {
+        let mut conn = self.open_registry_db()?;
+        let tx = conn
+            .transaction_with_behavior(rusqlite::TransactionBehavior::Deferred)
+            .map_err(sqlite_to_io)?;
+        let revision = current_notebook_setup_revision(&tx)?;
+        let jobs = {
+            let mut statement = tx
+                .prepare(
+                    r#"SELECT notebook_id, template_id, status, stage, message, updated_at,
+                              report_json, overwrite_existing, revision, run_id, job_id, execution_requested
+                       FROM notebook_setup_jobs"#,
+                )
+                .map_err(sqlite_to_io)?;
+            let rows = statement
+                .query_map([], map_notebook_setup_job)
+                .map_err(sqlite_to_io)?;
+            rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?
+        };
+        tx.commit().map_err(sqlite_to_io)?;
+        Ok(NotebookSetupSnapshot { revision, jobs })
+    }
+
+    pub fn write_notebook_setup_job(
+        &self,
+        job: &NotebookSetupJob,
+    ) -> std::io::Result<NotebookSetupJob> {
+        self.write_notebook_setup_job_with_run_transition(job, None)
+    }
+
+    pub fn start_notebook_setup_job(
+        &self,
+        job: &NotebookSetupJob,
+        expected_run_id: &str,
+    ) -> std::io::Result<NotebookSetupJob> {
+        self.write_notebook_setup_job_with_run_transition(job, Some(expected_run_id))
+    }
+
+    fn write_notebook_setup_job_with_run_transition(
+        &self,
+        job: &NotebookSetupJob,
+        expected_run_id: Option<&str>,
+    ) -> std::io::Result<NotebookSetupJob> {
+        let mut conn = self.open_registry_db()?;
+        let tx = conn
+            .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)
+            .map_err(sqlite_to_io)?;
+        if job.job_id.trim().is_empty() {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "notebook setup job identity is missing",
+            ));
+        }
+        let current: Option<(String, String, String)> = tx
+            .query_row(
+                "SELECT job_id, run_id, status FROM notebook_setup_jobs WHERE notebook_id = ?1",
+                [&job.notebook_id],
+                |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
+            )
+            .optional()
+            .map_err(sqlite_to_io)?;
+        if let Some((current_job_id, current_run_id, current_status)) = current {
+            if current_job_id != job.job_id {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::Interrupted,
+                    "NOTEBOOK_SETUP_JOB_SUPERSEDED",
+                ));
+            }
+            if current_run_id != job.run_id
+                && !(job.status == NotebookSetupJobStatus::Running
+                    && expected_run_id == Some(current_run_id.as_str())
+                    && matches!(
+                        current_status.as_str(),
+                        "pending" | "running" | "partial" | "failed"
+                    ))
+            {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::Interrupted,
+                    "NOTEBOOK_SETUP_RUN_SUPERSEDED",
+                ));
+            }
+        } else if job.status != NotebookSetupJobStatus::Pending {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::Interrupted,
+                "NOTEBOOK_SETUP_JOB_MISSING",
+            ));
+        }
+        let revision = next_notebook_setup_revision(&tx, job.updated_at)?;
         let report_json = job
             .report
             .as_ref()
             .map(serde_json::to_string)
             .transpose()
             .map_err(std::io::Error::other)?;
-        conn.execute(
+        tx.execute(
             r#"
             INSERT INTO notebook_setup_jobs
-                (notebook_id, template_id, status, stage, completed_files, total_files, message, report_json, updated_at, overwrite_existing)
-            VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
+                (notebook_id, template_id, status, stage, message, report_json, updated_at, overwrite_existing, revision, run_id, job_id, execution_requested)
+            VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
             ON CONFLICT(notebook_id) DO UPDATE SET
                 template_id = excluded.template_id,
                 status = excluded.status,
                 stage = excluded.stage,
-                completed_files = excluded.completed_files,
-                total_files = excluded.total_files,
                 message = excluded.message,
                 report_json = excluded.report_json,
                 updated_at = excluded.updated_at,
-                overwrite_existing = excluded.overwrite_existing
+                overwrite_existing = excluded.overwrite_existing,
+                revision = excluded.revision,
+                run_id = excluded.run_id,
+                job_id = excluded.job_id,
+                execution_requested = excluded.execution_requested
             "#,
             params![
                 job.notebook_id,
                 job.template_id,
                 notebook_setup_status_as_str(job.status),
-                job.stage,
-                job.completed_files as i64,
-                job.total_files as i64,
+                notebook_setup_stage_as_str(job.stage),
                 job.message,
                 report_json,
                 job.updated_at,
                 if job.overwrite_existing { 1 } else { 0 },
+                revision,
+                job.run_id,
+                job.job_id,
+                if job.execution_requested { 1 } else { 0 },
             ],
         )
         .map_err(sqlite_to_io)?;
-        Ok(())
+        tx.commit().map_err(sqlite_to_io)?;
+        let mut persisted = job.clone();
+        persisted.revision = revision;
+        Ok(persisted)
     }
 
     /// 分配一个新 notebook 的 sort: 已存在的最大 sort + 10, 步长 10 方便后续
diff --git a/app/flowix-core/src/memo_file/notebook_registry.rs b/app/flowix-core/src/memo_file/notebook_registry.rs
index 82de89310..d433dda0e 100644
--- a/app/flowix-core/src/memo_file/notebook_registry.rs
+++ b/app/flowix-core/src/memo_file/notebook_registry.rs
@@ -4,7 +4,7 @@ use std::fs;
 use std::path::PathBuf;
 use std::time::Duration;
 
-use rusqlite::{params, Connection};
+use rusqlite::{params, Connection, OptionalExtension};
 
 use super::notebook::sqlite_to_io;
 use super::types::NotebookConfig;
@@ -23,16 +23,34 @@ impl NotebookRegistry {
     }
 
     pub(super) fn db_path(&self) -> PathBuf {
-        self.config_dir.join("index.db")
+        self.config_dir.join("db").join("local.db")
     }
 
     pub(super) fn open(&self) -> std::io::Result<Connection> {
+        self.open_with_legacy_migrations(false)
+    }
+
+    pub(super) fn open_for_initialization(&self) -> std::io::Result<Connection> {
+        self.open_with_legacy_migrations(true)
+    }
+
+    fn open_with_legacy_migrations(
+        &self,
+        run_legacy_migrations: bool,
+    ) -> std::io::Result<Connection> {
         if let Some(parent) = self.db_path().parent() {
             fs::create_dir_all(parent)?;
         }
         let mut conn = Connection::open(self.db_path()).map_err(sqlite_to_io)?;
         conn.busy_timeout(Duration::from_secs(10))
             .map_err(sqlite_to_io)?;
+        let notebooks_table_exists: bool = conn
+            .query_row(
+                "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name='notebooks')",
+                [],
+                |row| row.get(0),
+            )
+            .map_err(sqlite_to_io)?;
         let has_sort_column = conn
             .prepare("PRAGMA table_info(notebooks)")
             .map_err(sqlite_to_io)?
@@ -40,7 +58,20 @@ impl NotebookRegistry {
             .map_err(sqlite_to_io)?
             .filter_map(Result::ok)
             .any(|name| name == "sort");
-        if !has_sort_column {
+        let has_pinned_column = conn
+            .prepare("PRAGMA table_info(notebooks)")
+            .map_err(sqlite_to_io)?
+            .query_map([], |row| row.get::<_, String>(1))
+            .map_err(sqlite_to_io)?
+            .filter_map(Result::ok)
+            .any(|name| name == "pinned");
+        if notebooks_table_exists && !has_sort_column && !run_legacy_migrations {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidData,
+                "notebook registry requires version initialization",
+            ));
+        }
+        if notebooks_table_exists && !has_sort_column {
             conn.execute_batch(
                 r#"
                 CREATE TABLE IF NOT EXISTS notebooks (
@@ -56,6 +87,16 @@ impl NotebookRegistry {
             )
             .map_err(sqlite_to_io)?;
             conn.execute_batch("ALTER TABLE notebooks ADD COLUMN sort INTEGER NOT NULL DEFAULT 0;")
+            .map_err(sqlite_to_io)?;
+        }
+        if notebooks_table_exists && !has_pinned_column {
+            if !run_legacy_migrations {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::InvalidData,
+                    "notebook registry requires pinned-column migration",
+                ));
+            }
+            conn.execute_batch("ALTER TABLE notebooks ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0 CHECK(pinned IN (0,1));")
                 .map_err(sqlite_to_io)?;
         }
         conn.execute_batch(
@@ -70,6 +111,7 @@ impl NotebookRegistry {
                 path TEXT NOT NULL UNIQUE,
                 is_default INTEGER NOT NULL,
                 sort INTEGER NOT NULL DEFAULT 0,
+                pinned INTEGER NOT NULL DEFAULT 0 CHECK(pinned IN (0,1)),
                 created_at INTEGER NOT NULL,
                 updated_at INTEGER NOT NULL
             );
@@ -77,6 +119,8 @@ impl NotebookRegistry {
                 ON notebooks(is_default);
             CREATE INDEX IF NOT EXISTS idx_notebooks_sort
                 ON notebooks(sort);
+            CREATE INDEX IF NOT EXISTS idx_notebooks_pinned_sort
+                ON notebooks(pinned DESC, sort ASC);
             CREATE TABLE IF NOT EXISTS app_state (
                 key TEXT PRIMARY KEY,
                 value TEXT,
@@ -87,12 +131,18 @@ impl NotebookRegistry {
                 template_id TEXT,
                 status TEXT NOT NULL,
                 stage TEXT NOT NULL,
-                completed_files INTEGER NOT NULL DEFAULT 0,
-                total_files INTEGER NOT NULL DEFAULT 0,
                 message TEXT,
                 report_json TEXT,
                 overwrite_existing INTEGER NOT NULL DEFAULT 0,
-                updated_at INTEGER NOT NULL
+                updated_at INTEGER NOT NULL,
+                revision INTEGER NOT NULL DEFAULT 0,
+                run_id TEXT NOT NULL DEFAULT '',
+                job_id TEXT NOT NULL DEFAULT '',
+                execution_requested INTEGER NOT NULL DEFAULT 0
+            );
+            CREATE TABLE IF NOT EXISTS local_migrations (
+                migration_key TEXT PRIMARY KEY,
+                completed_at INTEGER NOT NULL DEFAULT 0
             );
             "#,
         )
@@ -104,6 +154,12 @@ impl NotebookRegistry {
             .map_err(sqlite_to_io)?
             .filter_map(Result::ok)
             .any(|name| name == "report_json");
+        if !has_setup_report && !run_legacy_migrations {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidData,
+                "notebook setup registry requires version initialization",
+            ));
+        }
         if !has_setup_report {
             conn.execute_batch("ALTER TABLE notebook_setup_jobs ADD COLUMN report_json TEXT;")
                 .map_err(sqlite_to_io)?;
@@ -115,13 +171,81 @@ impl NotebookRegistry {
             .map_err(sqlite_to_io)?
             .filter_map(Result::ok)
             .any(|name| name == "overwrite_existing");
+        if !has_setup_overwrite && !run_legacy_migrations {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidData,
+                "notebook setup registry requires version initialization",
+            ));
+        }
         if !has_setup_overwrite {
             conn.execute_batch(
                 "ALTER TABLE notebook_setup_jobs ADD COLUMN overwrite_existing INTEGER NOT NULL DEFAULT 0;",
             )
             .map_err(sqlite_to_io)?;
         }
-        if !has_sort_column {
+        for (column, declaration) in [
+            ("revision", "INTEGER NOT NULL DEFAULT 0"),
+            ("run_id", "TEXT NOT NULL DEFAULT ''"),
+            ("job_id", "TEXT NOT NULL DEFAULT ''"),
+            ("execution_requested", "INTEGER NOT NULL DEFAULT 0"),
+        ] {
+            let has_column = conn
+                .prepare("PRAGMA table_info(notebook_setup_jobs)")
+                .map_err(sqlite_to_io)?
+                .query_map([], |row| row.get::<_, String>(1))
+                .map_err(sqlite_to_io)?
+                .filter_map(Result::ok)
+                .any(|name| name == column);
+            if !has_column && !run_legacy_migrations {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::InvalidData,
+                    format!("notebook setup registry requires version initialization ({column})"),
+                ));
+            }
+            if !has_column {
+                conn.execute_batch(&format!(
+                    "ALTER TABLE notebook_setup_jobs ADD COLUMN {column} {declaration};"
+                ))
+                .map_err(sqlite_to_io)?;
+            }
+        }
+        conn.execute(
+            "UPDATE notebook_setup_jobs SET job_id = lower(hex(randomblob(16))) WHERE job_id = ''",
+            [],
+        )
+        .map_err(sqlite_to_io)?;
+        let migration_tx = conn
+            .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)
+            .map_err(sqlite_to_io)?;
+        let execution_request_migration: Option<String> = migration_tx
+            .query_row(
+                "SELECT value FROM app_state WHERE key = 'notebook_setup_execution_request_migrated'",
+                [],
+                |row| row.get(0),
+            )
+            .optional()
+            .map_err(sqlite_to_io)?;
+        if execution_request_migration.is_none() {
+            migration_tx
+                .execute(
+                    "UPDATE notebook_setup_jobs SET execution_requested = 1 WHERE status IN ('pending', 'running')",
+                    [],
+                )
+                .map_err(sqlite_to_io)?;
+            migration_tx
+                .execute(
+                    "INSERT INTO app_state (key, value, updated_at) VALUES ('notebook_setup_execution_request_migrated', '1', 0)",
+                    [],
+                )
+                .map_err(sqlite_to_io)?;
+        }
+        migration_tx.commit().map_err(sqlite_to_io)?;
+        conn.execute(
+            "INSERT OR IGNORE INTO app_state (key, value, updated_at) SELECT 'notebook_setup_revision', CAST(COALESCE(MAX(revision), 0) AS TEXT), 0 FROM notebook_setup_jobs",
+            [],
+        )
+        .map_err(sqlite_to_io)?;
+        if notebooks_table_exists && !has_sort_column {
             let tx = conn.transaction().map_err(sqlite_to_io)?;
             let mut stmt = tx
                 .prepare(
diff --git a/app/flowix-core/src/memo_file/onboarding.rs b/app/flowix-core/src/memo_file/onboarding.rs
index 0de099fa6..e02a80bf0 100644
--- a/app/flowix-core/src/memo_file/onboarding.rs
+++ b/app/flowix-core/src/memo_file/onboarding.rs
@@ -39,8 +39,12 @@ impl MemoFile {
     /// Safety guard: if the target folder already contains memos (for example,
     /// the user registered a folder full of notes), this is a no-op.
     pub fn seed_onboarding_docs(&self) -> std::io::Result<bool> {
-        let index = self.read_index_result()?.unwrap_or_default();
-        seed_onboarding_docs_if_empty(self, self.get_memo_base(), index.memos.is_empty(), None)
+        let notebook_id = self.current_notebook_id_for_index();
+        if !self.note_index_is_ready(&notebook_id)? {
+            self.reconcile_note_index_blocking(&notebook_id)?;
+        }
+        let empty = self.note_count(&notebook_id)? == 0;
+        seed_onboarding_docs_if_empty(self, self.get_memo_base(), empty, None)
     }
 
     /// Seed onboarding documents into a notebook without changing the
@@ -48,13 +52,14 @@ impl MemoFile {
     /// imports: importing a newly registered notebook must not change the
     /// user's active notebook while they are browsing another one.
     pub fn seed_onboarding_docs_for_notebook_id(&self, notebook_id: &str) -> std::io::Result<bool> {
-        let index = self
-            .read_index_for_notebook_id(Some(notebook_id))?
-            .unwrap_or_default();
+        if !self.note_index_is_ready(notebook_id)? {
+            self.reconcile_note_index_blocking(notebook_id)?;
+        }
+        let empty = self.note_count(notebook_id)? == 0;
         let base = self
             .memo_base_for_notebook_id_result(notebook_id)
             .map_err(std::io::Error::other)?;
-        seed_onboarding_docs_if_empty(self, base, index.memos.is_empty(), Some(notebook_id))
+        seed_onboarding_docs_if_empty(self, base, empty, Some(notebook_id))
     }
 }
 
@@ -233,7 +238,7 @@ mod tests {
             content.contains(original),
             "original Markdown body must survive"
         );
-        assert_eq!(crate::memo_file::extract_frontmatter_key(&content), None);
+        assert!(!content.contains("flowix_key:"));
     }
 
     #[test]
diff --git a/app/flowix-core/src/memo_file/ops.rs b/app/flowix-core/src/memo_file/ops.rs
index 678f28980..d631543b8 100644
--- a/app/flowix-core/src/memo_file/ops.rs
+++ b/app/flowix-core/src/memo_file/ops.rs
@@ -1,30 +1,22 @@
-//! Legacy memo-ID CRUD and reconciliation operations.
-//!
-//! Markdown remains the content source. This module maintains an ID-bearing
-//! cache for older callers; path-based operations and the rebuildable Note
-//! index also live in `note_index`. New internal IDs contain eight `[0-9a-z]`
-//! characters; older six-character IDs remain readable. New writes do not
-//! append an ID to filenames or frontmatter.
+//! Markdown CRUD and reconciliation operations keyed by notebook-relative path.
 //!
 //! `Memo` / `MemoIndexEntry::filename` stores the disk filename including
 //! `.md`; `relative_path` identifies nested files within the notebook.
 //!
 //! ## 锁模型
 //!
-//! ID-cache mutations use `current_index_io` to serialize their read-modify-
-//! write sequence. Internal `_locked` methods are called while holding it.
+//! Index mutations use `current_index_io` to serialize their read-modify-write
+//! sequence. Internal `_locked` methods are called while holding it.
 
 use std::fs;
 use std::path::{Path, PathBuf};
 
-use rusqlite::OptionalExtension;
-
 use super::derivation::{apply_derived_memo_fields, extract_title_and_preview};
 pub(super) use super::file_io::{atomic_create_bytes, atomic_write_bytes, rename_file_noclobber};
 use super::frontmatter::extract_document_metadata_preserving_invalid_tag_paths;
 use super::frontmatter::{
     extract_document_metadata_tolerant,
-    is_system_frontmatter_key, merge_frontmatter, replace_frontmatter_tags,
+    merge_frontmatter, replace_frontmatter_tags,
     replace_frontmatter_tags_preserving_invalid_paths, MergeOverrides,
 };
 use super::extract_document_metadata;
@@ -216,15 +208,6 @@ fn normalize_for_compare(path: &Path) -> PathBuf {
 }
 
 impl MemoFile {
-    fn generate_global_memo_id(&self) -> String {
-        loop {
-            let id = nanoid::nanoid!(8, &super::MEMO_ID_ALPHABET);
-            if self.resolve_memo_location(&id).ok().flatten().is_none() {
-                return id;
-            }
-        }
-    }
-
     pub(crate) fn memo_base_for_notebook_id_result(
         &self,
         notebook_id: &str,
@@ -234,13 +217,17 @@ impl MemoFile {
             .ok_or_else(|| format!("notebook {notebook_id} not found"))
     }
 
-    pub fn read_memo_for_notebook_id(&self, notebook_id: &str, id: &str) -> Option<Memo> {
+    pub fn read_memo_for_notebook_id(
+        &self,
+        notebook_id: &str,
+        relative_path: &str,
+    ) -> Option<Memo> {
         self.read_index_for_notebook_id(Some(notebook_id))
             .ok()
             .flatten()?
             .memos
             .into_iter()
-            .find(|entry| entry.id == id)
+            .find(|entry| entry.relative_path == relative_path)
             .map(|entry| MemoFile::index_entry_to_memo(&entry))
     }
 
diff --git a/app/flowix-core/src/memo_file/ops/crud.rs b/app/flowix-core/src/memo_file/ops/crud.rs
index a28a476fe..63eea49cd 100644
--- a/app/flowix-core/src/memo_file/ops/crud.rs
+++ b/app/flowix-core/src/memo_file/ops/crud.rs
@@ -23,9 +23,9 @@ fn same_title_with_generated_conflict_suffix(current_base: &str, derived_title:
 }
 
 impl MemoFile {
-    /// 创建一个 memo: 写 .md + 写 memo index。返回新建的 Memo (含 id / filename)。
+    /// Create a Markdown note and return its path-keyed compatibility DTO.
     pub fn create_memo(&self, title: &str, body: &str, tag: Option<&str>) -> std::io::Result<Memo> {
-        self.create_memo_inner(None, title, body, tag, false)
+        self.create_memo_inner(None, title, body, tag)
     }
 
     /// Create in a registered notebook without changing the process-local current notebook.
@@ -36,7 +36,7 @@ impl MemoFile {
         body: &str,
         tag: Option<&str>,
     ) -> std::io::Result<Memo> {
-        self.create_memo_inner(Some(notebook_id), title, body, tag, false)
+        self.create_memo_inner(Some(notebook_id), title, body, tag)
     }
 
     /// Create in an existing notebook subdirectory. The directory is expressed
@@ -55,12 +55,11 @@ impl MemoFile {
             title,
             body,
             tag,
-            false,
         )
     }
 
-    /// Create from a separate CLI/MCP process and leave an explicit marker for
-    /// Desktop's filesystem watcher before the markdown file becomes visible.
+    /// Compatibility wrapper for external callers. The watcher indexes the
+    /// created file by notebook-relative path when it becomes visible.
     pub fn create_external_memo_for_notebook_id(
         &self,
         notebook_id: &str,
@@ -68,7 +67,7 @@ impl MemoFile {
         body: &str,
         tag: Option<&str>,
     ) -> std::io::Result<Memo> {
-        self.create_memo_inner(Some(notebook_id), title, body, tag, true)
+        self.create_memo_inner(Some(notebook_id), title, body, tag)
     }
 
     fn create_memo_inner(
@@ -77,16 +76,8 @@ impl MemoFile {
         title: &str,
         body: &str,
         tag: Option<&str>,
-        mark_external_create: bool,
     ) -> std::io::Result<Memo> {
-        self.create_memo_inner_in_directory(
-            notebook_id,
-            None,
-            title,
-            body,
-            tag,
-            mark_external_create,
-        )
+        self.create_memo_inner_in_directory(notebook_id, None, title, body, tag)
     }
 
     fn create_memo_inner_in_directory(
@@ -96,7 +87,6 @@ impl MemoFile {
         title: &str,
         body: &str,
         tag: Option<&str>,
-        mark_external_create: bool,
     ) -> std::io::Result<Memo> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
         let (base, resolved_notebook_id) = if let Some(notebook_id) = notebook_id {
@@ -136,7 +126,6 @@ impl MemoFile {
             None => base.clone(),
         };
 
-        let id = self.generate_global_memo_id();
         let now = chrono::Utc::now().timestamp_millis();
         let candidate = base_filename(title);
         // Check indexed names as well as disk existence before atomically
@@ -146,7 +135,7 @@ impl MemoFile {
             parent_relative_path.filter(|path| !path.is_empty()),
         )?;
 
-        // Preserve supplied Markdown; its legacy key is not used as the cache ID.
+        // Preserve supplied Markdown; the notebook-relative path is the cache key.
         let prepared_content = body.to_string();
         let initial_content = match tag {
             Some(tag) if !tag.trim().is_empty() => {
@@ -163,10 +152,6 @@ impl MemoFile {
             _ => prepared_content,
         };
         validate_document_frontmatter(&initial_content)?;
-        let persisted_id = id;
-        if mark_external_create {
-            self.mark_pending_external_memo_create(&persisted_id, &resolved_notebook_id)?;
-        }
         let filename = loop {
             let filename = resolve_filename_conflict(&create_base, &candidate, &occupied);
             let path = create_base.join(&filename);
@@ -175,22 +160,17 @@ impl MemoFile {
                 Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
                     occupied.push(filename);
                 }
-                Err(error) => {
-                    if mark_external_create {
-                        let _ = self.clear_pending_external_memo_create(&persisted_id);
-                    }
-                    return Err(error);
-                }
+                Err(error) => return Err(error),
             }
         };
 
+        let relative_path = parent_relative_path
+            .filter(|path| !path.is_empty())
+            .map(|parent| format!("{parent}/{filename}"))
+            .unwrap_or_else(|| filename.clone());
         let mut memo = Memo {
-            id: persisted_id,
             filename: filename.clone(),
-            relative_path: parent_relative_path
-                .filter(|path| !path.is_empty())
-                .map(|parent| format!("{parent}/{filename}"))
-                .unwrap_or_else(|| filename.clone()),
+            relative_path,
             preview: String::new(),
             thumbnail: None,
             tags: vec![],
@@ -213,9 +193,6 @@ impl MemoFile {
             if fs::read_to_string(&path).ok().as_deref() == Some(initial_content.as_str()) {
                 let _ = fs::remove_file(path);
             }
-            if mark_external_create {
-                let _ = self.clear_pending_external_memo_create(&memo.id);
-            }
             return Err(error);
         }
         Ok(memo)
@@ -224,12 +201,12 @@ impl MemoFile {
     /// 改名: 物理文件可能 rename, memo index entry.filename 同步更新。
     /// `new_title` 为空字符串时**不**重命名, 仅刷新派生字段 (no-op)。
     /// 冲突自动追加 `-1` / `-2`。
-    pub fn rename_memo(&self, id: &str, new_title: &str) -> std::io::Result<Memo> {
+    pub fn rename_memo(&self, relative_path: &str, new_title: &str) -> std::io::Result<Memo> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
+        let notebook_id = self.current_notebook_id_for_index();
         let location = self
-            .resolve_memo_location(id)?
-            .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "memo not found"))?;
-        let notebook_id = location.notebook.id;
+            .resolve_note_location_for_notebook_id(&notebook_id, relative_path)?
+            .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "note not found"))?;
         let base = PathBuf::from(location.notebook.path);
         let mut memo = MemoFile::index_entry_to_memo(&location.memo);
         let old_filename = memo.filename.clone();
@@ -252,7 +229,7 @@ impl MemoFile {
                 .map(|l| {
                     l.memos
                         .into_iter()
-                        .filter(|e| e.id != memo.id)
+                        .filter(|e| e.relative_path != memo.relative_path)
                         .map(|e| e.relative_path)
                         .collect()
                 })
@@ -284,80 +261,25 @@ impl MemoFile {
         memo.relative_path = new_relative_path;
         memo.updated_at = chrono::Utc::now().timestamp_millis();
         apply_derived_memo_fields(&mut memo, &new_content);
+        if memo.relative_path != old_relative_path {
+            MemoFile::sync_index_on_delete_for_notebook_id_locked(self, &notebook_id, &old_relative_path)?;
+        }
         MemoFile::sync_index_on_write_for_notebook_id_locked(self, &notebook_id, &memo)?;
         Ok(memo)
     }
 
     /// 写入 body (不改 title)。物理文件不 rename, 仅重写 .md + 同步 memo index 派生字段。
-    pub fn write_memo(&self, id: &str, body: &str) -> std::io::Result<Memo> {
+    pub fn write_memo(&self, relative_path: &str, body: &str) -> std::io::Result<Memo> {
         let _guard = self.current_index_io.lock().expect("index_io poisoned");
         self.ensure_dirs()?;
-        self.write_memo_inner_locked(id, body)
-    }
-
-    /// Write a globally resolved memo without renaming its file or switching notebooks.
-    pub fn write_memo_preserving_filename_global(
-        &self,
-        id: &str,
-        body: &str,
-    ) -> std::io::Result<Memo> {
-        let _guard = self.current_index_io.lock().expect("index_io poisoned");
-        let (memo, notebook_id) = self.write_memo_preserving_filename_content(id, body, None)?;
-        MemoFile::sync_index_on_write_for_notebook_id_locked(self, &notebook_id, &memo)?;
-        Ok(memo)
-    }
-
-    /// The caller holds the file lock. Keep content I/O outside the legacy
-    /// process-local index mutex so independent files can write concurrently.
-    pub(crate) fn write_memo_preserving_filename_under_file_lock(
-        &self,
-        id: &str,
-        body: &str,
-        file_guard: &super::super::FileWriteGuard,
-    ) -> std::io::Result<Memo> {
-        let (memo, notebook_id) = self.write_memo_preserving_filename_content(id, body, Some(file_guard))?;
-        let _guard = self.current_index_io.lock().expect("index_io poisoned");
-        MemoFile::sync_index_on_write_for_notebook_id_locked(self, &notebook_id, &memo)?;
-        Ok(memo)
-    }
-
-    fn write_memo_preserving_filename_content(
-        &self,
-        id: &str,
-        body: &str,
-        file_guard: Option<&super::super::FileWriteGuard>,
-    ) -> std::io::Result<(Memo, String)> {
-        let location = self.resolve_memo_location(id)?.ok_or_else(|| {
-            std::io::Error::new(std::io::ErrorKind::NotFound, format!("memo {id} not found"))
-        })?;
-        let base = PathBuf::from(&location.notebook.path);
-        fs::create_dir_all(&base)?;
-        fs::create_dir_all(base.join(".flowix"))?;
-        fs::create_dir_all(base.join("attachments"))?;
-
-        let mut memo = MemoFile::index_entry_to_memo(&location.memo);
-        let merged = body.to_string();
-        validate_document_frontmatter(&merged)?;
-        let path = notebook_path_from_relative(&base, &memo.relative_path)
-            .map_err(std::io::Error::other)?;
-        fs::metadata(&path)?;
-        if let Some(file_guard) = file_guard {
-            if std::fs::canonicalize(&path)? != file_guard.path() {
-                return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, "file guard does not match memo path"));
-            }
-        }
-        atomic_write_bytes(&path, merged.as_bytes())?;
-
-        memo.updated_at = chrono::Utc::now().timestamp_millis();
-        apply_derived_memo_fields(&mut memo, &merged);
-        Ok((memo, location.notebook.id))
+        self.write_memo_inner_locked(relative_path, body)
     }
 
     /// 无锁版本的 [`Self::write_memo`]。调用方已持 `current_index_io` 锁。
     /// 抽出供 [`Self::write_memo_renaming_on_title_change`] 单事务合用。
-    fn write_memo_inner_locked(&self, id: &str, body: &str) -> std::io::Result<Memo> {
-        let mut memo = self.read_current_memo(id).ok_or_else(|| {
-            std::io::Error::new(std::io::ErrorKind::NotFound, format!("memo {id} not found"))
+    fn write_memo_inner_locked(&self, relative_path: &str, body: &str) -> std::io::Result<Memo> {
+        let mut memo = self.read_current_memo(relative_path).ok_or_else(|| {
+            std::io::Error::new(std::io::ErrorKind::NotFound, format!("note path {relative_path} not found"))
         })?;
         let merged = body.to_string();
         validate_document_frontmatter(&merged)?;
@@ -383,14 +305,14 @@ impl MemoFile {
     /// 调用方: `commands::memo::write_document` (Tiptap 编辑保存 IPC 入口)。
     pub fn write_memo_renaming_on_title_change(
         &self,
-        id: &str,
+        relative_path: &str,
         body: &str,
     ) -> std::io::Result<Memo> {
         let _guard = self.current_index_io.lock().expect("index_io poisoned");
         self.ensure_dirs()?;
 
         // 先 write_memo (含 key 注入 + memo index 同步)
-        let memo = self.write_memo_inner_locked(id, body)?;
+        let memo = self.write_memo_inner_locked(relative_path, body)?;
 
         // 抽最终磁盘内容(同锁内, 写盘已完成, 文件可读)
         let path = notebook_path_from_relative(&self.get_memo_base(), &memo.relative_path)
@@ -422,7 +344,7 @@ impl MemoFile {
             .map(|l| {
                 l.memos
                     .into_iter()
-                    .filter(|e| e.id != memo.id)
+                    .filter(|e| e.relative_path != memo.relative_path)
                     .map(|e| e.relative_path)
                     .collect()
             })
@@ -461,25 +383,29 @@ impl MemoFile {
         let new_content = existing;
         atomic_write_bytes(&new_path, new_content.as_bytes())?;
 
+        let old_relative_path = memo.relative_path.clone();
         let mut updated = memo;
         updated.filename = new_filename;
         updated.relative_path = new_relative_path;
         updated.updated_at = chrono::Utc::now().timestamp_millis();
         apply_derived_memo_fields(&mut updated, &new_content);
+        if updated.relative_path != old_relative_path {
+            MemoFile::sync_index_on_delete_locked(self, &old_relative_path)?;
+        }
         MemoFile::sync_index_on_write_locked(self, &updated)?;
         Ok(updated)
     }
 
     pub fn write_memo_renaming_on_title_change_global(
         &self,
-        id: &str,
+        relative_path: &str,
         body: &str,
     ) -> std::io::Result<Memo> {
         let _guard = self.current_index_io.lock().expect("index_io poisoned");
-        let location = self.resolve_memo_location(id)?.ok_or_else(|| {
-            std::io::Error::new(std::io::ErrorKind::NotFound, format!("memo {id} not found"))
+        let notebook_id = self.current_notebook_id_for_index();
+        let location = self.resolve_note_location_for_notebook_id(&notebook_id, relative_path)?.ok_or_else(|| {
+            std::io::Error::new(std::io::ErrorKind::NotFound, format!("note path {relative_path} not found"))
         })?;
-        let notebook_id = location.notebook.id;
         let base = PathBuf::from(location.notebook.path);
         fs::create_dir_all(&base)?;
         fs::create_dir_all(base.join(".flowix"))?;
@@ -520,7 +446,7 @@ impl MemoFile {
             .map(|l| {
                 l.memos
                     .into_iter()
-                    .filter(|e| e.id != memo.id)
+                    .filter(|e| e.relative_path != memo.relative_path)
                     .map(|e| e.relative_path)
                     .collect()
             })
@@ -566,18 +492,18 @@ impl MemoFile {
     /// 删除: 删 .md + memo index 移除 entry。
     /// 物理文件已不在 (例如外部 `rm`) 但 memo index 仍残留 → 清 list, 视为成功。
     /// 完全找不到 (list 也没有) → false。
-    pub fn delete_memo(&self, id: &str) -> bool {
-        self.delete_memo_result(id).unwrap_or(false)
+    pub fn delete_memo(&self, relative_path: &str) -> bool {
+        self.delete_memo_result(relative_path).unwrap_or(false)
     }
 
     /// 删除并返回真实 IO 结果。
     ///
     /// 保留 [`Self::delete_memo`] 的布尔兼容 API，CLI/JSON-RPC 使用本方法避免
     /// 把 remove/index 写入失败伪装成成功。
-    pub fn delete_memo_result(&self, id: &str) -> std::io::Result<bool> {
+    pub fn delete_memo_result(&self, relative_path: &str) -> std::io::Result<bool> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
 
-        let memo = self.read_current_memo(id);
+        let memo = self.read_current_memo(relative_path);
         let path = memo.as_ref().and_then(|m| {
             notebook_path_from_relative(&self.get_memo_base(), &m.relative_path).ok()
         });
@@ -588,18 +514,19 @@ impl MemoFile {
             }
             _ => {
                 // 物理文件已无, 但 memo index 仍残留 → 兜底清 list
-                self.read_current_memo(id).is_some()
+                self.read_current_memo(relative_path).is_some()
             }
         };
         if removed {
-            MemoFile::sync_index_on_delete_locked(self, id)?;
+            MemoFile::sync_index_on_delete_locked(self, relative_path)?;
         }
         Ok(removed)
     }
 
-    pub fn delete_memo_result_global(&self, id: &str) -> std::io::Result<bool> {
+    pub fn delete_memo_result_global(&self, relative_path: &str) -> std::io::Result<bool> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
-        let Some(location) = self.resolve_memo_location(id)? else {
+        let notebook_id = self.current_notebook_id_for_index();
+        let Some(location) = self.resolve_note_location_for_notebook_id(&notebook_id, relative_path)? else {
             return Ok(false);
         };
 
@@ -615,7 +542,7 @@ impl MemoFile {
             true
         };
         if removed {
-            MemoFile::sync_index_on_delete_for_notebook_id_locked(self, &location.notebook.id, id)?;
+            MemoFile::sync_index_on_delete_for_notebook_id_locked(self, &notebook_id, relative_path)?;
         }
         Ok(removed)
     }
@@ -626,7 +553,7 @@ impl MemoFile {
         &self,
         notebook_id: &str,
         relative_path: &str,
-        expected_id: &str,
+        expected_relative_path: &str,
     ) -> std::io::Result<bool> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
         let base = self.memo_base_for_notebook_id_result(notebook_id).map_err(std::io::Error::other)?;
@@ -639,25 +566,25 @@ impl MemoFile {
         let Some(memo) = self.find_memo_by_relative_path_for_notebook_id(notebook_id, relative_path) else {
             return Ok(true);
         };
-        if memo.id != expected_id {
+        if memo.relative_path != expected_relative_path {
             return Ok(false);
         }
-        MemoFile::sync_index_on_delete_for_notebook_id_locked(self, notebook_id, expected_id)?;
+        MemoFile::sync_index_on_delete_for_notebook_id_locked(self, notebook_id, expected_relative_path)?;
         Ok(true)
     }
 
     /// Delete a memo only when it belongs to the requested notebook.
     ///
-    /// Cloud synchronization must never resolve an incoming note ID globally:
-    /// a duplicate/malicious remote ID from another notebook must not remove
+    /// Cloud synchronization must never resolve a note path globally:
+    /// the same relative path in another notebook must not remove
     /// that notebook's local file.
     pub fn delete_memo_result_for_notebook_id(
         &self,
         notebook_id: &str,
-        id: &str,
+        relative_path: &str,
     ) -> std::io::Result<bool> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
-        let Some(memo) = self.read_memo_for_notebook_id(notebook_id, id) else {
+        let Some(memo) = self.read_memo_for_notebook_id(notebook_id, relative_path) else {
             return Ok(false);
         };
         let base = self
@@ -668,7 +595,7 @@ impl MemoFile {
         if path.exists() {
             fs::remove_file(&path)?;
         }
-        MemoFile::sync_index_on_delete_for_notebook_id_locked(self, notebook_id, id)?;
+        MemoFile::sync_index_on_delete_for_notebook_id_locked(self, notebook_id, relative_path)?;
         Ok(true)
     }
 }
diff --git a/app/flowix-core/src/memo_file/ops/reconcile.rs b/app/flowix-core/src/memo_file/ops/reconcile.rs
index af0e0da1d..242c554ad 100644
--- a/app/flowix-core/src/memo_file/ops/reconcile.rs
+++ b/app/flowix-core/src/memo_file/ops/reconcile.rs
@@ -54,7 +54,7 @@ impl MemoFile {
         // '/' sorts immediately before '0': this range selects only descendants
         // and lets path indexes bound the update, including '%' or '_' in names.
         let upper_bound = format!("{previous}0");
-        for table in ["notes", "note_tags", "note_todos", "note_agents", "note_search_fts"] {
+        for table in ["notes", "note_search_fts"] {
             tx.execute(
                 &format!("UPDATE {table} SET relative_path=?2 || substr(relative_path,length(?1)+1) WHERE relative_path>=?1 AND relative_path<?3"),
                 params![previous_prefix, next_prefix, upper_bound],
@@ -65,11 +65,36 @@ impl MemoFile {
              WHERE notebook_id=?4 AND relative_path>=?1 AND relative_path<?3",
             params![previous_prefix, next_prefix, upper_bound, notebook_id],
         ).map_err(sqlite_to_io)?;
-        tx.execute(
-            "UPDATE media_resources SET relative_path=?2 || substr(relative_path,length(?1)+1)
-             WHERE notebook_id=?4 AND relative_path>=?1 AND relative_path<?3 AND missing_since IS NULL AND deleted_at IS NULL",
-            params![previous_prefix, next_prefix, upper_bound, notebook_id],
-        ).map_err(sqlite_to_io)?;
+        let media_rows = {
+            let mut statement = tx.prepare(
+                "SELECT id, relative_path FROM media_resources
+                 WHERE notebook_id=?1 AND relative_path>=?2 AND relative_path<?3
+                   AND missing_since IS NULL AND deleted_at IS NULL",
+            ).map_err(sqlite_to_io)?;
+            let rows = statement.query_map(params![notebook_id, previous_prefix, upper_bound], |row| {
+                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
+            }).map_err(sqlite_to_io)?;
+            rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?
+        };
+        let media_moves = media_rows.into_iter().map(|(old_id, old_path)| {
+            let next_path = format!("{next}/{}", old_path.strip_prefix(&previous_prefix).unwrap_or_default());
+            let next_id = crate::memo_file::media_resource_id(notebook_id, &next_path)
+                .map_err(std::io::Error::other)?;
+            let temporary_id = format!("__flowix_media_move__{}", uuid::Uuid::now_v7().simple());
+            Ok((old_id, temporary_id, next_path, next_id))
+        }).collect::<std::io::Result<Vec<_>>>()?;
+        for (old_id, temporary_id, _, _) in &media_moves {
+            tx.execute(
+                "UPDATE media_resources SET id=?1 WHERE notebook_id=?2 AND id=?3",
+                params![temporary_id, notebook_id, old_id],
+            ).map_err(sqlite_to_io)?;
+        }
+        for (_, temporary_id, next_path, next_id) in media_moves {
+            tx.execute(
+                "UPDATE media_resources SET id=?1, relative_path=?2 WHERE notebook_id=?3 AND id=?4",
+                params![next_id, next_path, notebook_id, temporary_id],
+            ).map_err(sqlite_to_io)?;
+        }
         tx.commit().map_err(sqlite_to_io)
     }
 
@@ -79,7 +104,8 @@ impl MemoFile {
         &self,
         source: &Path,
         target: &Path,
-    ) -> std::io::Result<Vec<(String, Memo, Memo)>> {
+    ) -> std::io::Result<()> {
+        let source_is_directory = source.is_dir();
         let notebook_ids = self.notebook_ids_for_paths(&[source, target])?;
         let _change_guard = if notebook_ids.is_empty() {
             None
@@ -99,62 +125,54 @@ impl MemoFile {
             ));
         }
         let _guard = self.current_index_io.lock().expect("index_io poisoned");
-        let mut changes = Vec::new();
-        for notebook in self.read_notebook_configs()? {
-            let base = PathBuf::from(&notebook.path);
-            for before in self.read_all_memos_for_notebook_id(Some(&notebook.id)) {
-                let old = notebook_path_from_relative(&base, &before.relative_path)
-                    .map_err(std::io::Error::other)?;
-                let Ok(suffix) = old.strip_prefix(source) else {
-                    continue;
-                };
-                let next = if suffix.as_os_str().is_empty() {
-                    target.to_path_buf()
-                } else {
-                    target.join(suffix)
-                };
-                let relative =
-                    notebook_relative_path(&base, &next).map_err(std::io::Error::other)?;
-                if self
-                    .find_memo_by_relative_path_for_notebook_id(&notebook.id, &relative)
-                    .is_some_and(|m| m.id != before.id)
-                {
-                    return Err(std::io::Error::new(
-                        std::io::ErrorKind::AlreadyExists,
-                        "destination is already indexed",
-                    ));
-                }
-                let mut after = before.clone();
-                after.filename = filename_from_notebook_relative_path(&relative);
-                after.relative_path = relative;
-                changes.push((notebook.id.clone(), before, after));
+        let mut directory_rebases: Vec<(String, String, String)> = Vec::new();
+        if source_is_directory {
+            let source_absolute = std::fs::canonicalize(source)?;
+            let target_parent = target.parent().ok_or_else(|| {
+                std::io::Error::new(std::io::ErrorKind::InvalidInput, "path has no parent")
+            })?;
+            let target_absolute = std::fs::canonicalize(target_parent)?.join(
+                target.file_name().ok_or_else(|| {
+                    std::io::Error::new(std::io::ErrorKind::InvalidInput, "path has no name")
+                })?,
+            );
+            for notebook_id in &notebook_ids {
+                let notebook = self.get_notebook_config_by_id(notebook_id).ok_or_else(|| {
+                    std::io::Error::new(std::io::ErrorKind::NotFound, "notebook not found")
+                })?;
+                let root = std::fs::canonicalize(notebook.path)?;
+                let previous = source_absolute
+                    .strip_prefix(&root)
+                    .map_err(std::io::Error::other)?
+                    .to_string_lossy().replace('\\', "/");
+                let next = target_absolute
+                    .strip_prefix(&root)
+                    .map_err(std::io::Error::other)?
+                    .to_string_lossy().replace('\\', "/");
+                self.validate_directory_index_rebase(notebook_id, &previous, &next)?;
+                directory_rebases.push((notebook_id.clone(), previous, next));
             }
         }
         rename_file_noclobber(source, target)?;
-        for (notebook, _, after) in &changes {
-            if let Err(error) =
-                Self::sync_index_on_write_for_notebook_id_locked_without_projection(self, notebook, after)
-            {
-                // Restore the original address on a failed index commit.
-                rename_file_noclobber(target, source)?;
-                for (notebook, before, _) in &changes {
-                    Self::sync_index_on_write_for_notebook_id_locked_without_projection(self, notebook, before)?;
+        let mut rebased_directories: Vec<(String, String, String)> = Vec::new();
+        for (notebook_id, previous, next) in &directory_rebases {
+            if let Err(error) = self.rebase_directory_indexes(notebook_id, previous, next) {
+                for (applied_notebook, applied_previous, applied_next) in rebased_directories.iter().rev() {
+                    if let Err(rollback_error) = self.rebase_directory_indexes(
+                        applied_notebook, applied_next, applied_previous,
+                    ) {
+                        tracing::error!(notebook_id = %applied_notebook, "failed to roll back directory index rebase: {rollback_error}");
+                    }
                 }
+                rename_file_noclobber(target, source)?;
                 return Err(error);
             }
+            rebased_directories.push((notebook_id.clone(), previous.clone(), next.clone()));
         }
         drop(_guard);
         drop(_change_guard);
         drop(_legacy_guard);
-        for (notebook_id, before, after) in &changes {
-            for relative_path in [&before.relative_path, &after.relative_path] {
-                if let Err(error) = self.refresh_note_path(notebook_id, relative_path) {
-                    let _ = self.mark_note_index_refresh_pending_for_notebook(notebook_id);
-                    tracing::warn!(notebook_id, relative_path, "path moved but note index refresh failed: {error}");
-                }
-            }
-        }
-        Ok(changes)
+        Ok(())
     }
 
     /// 启动 / 切 notebook 时调用: 递归扫描 notebook 内 .md, 把 memo index 没记录的补进来。
@@ -522,11 +540,11 @@ impl MemoFile {
         })
     }
 
-    pub fn reload_memo_from_disk(&self, id: &str) -> Result<Memo, String> {
+    pub fn reload_memo_from_disk(&self, relative_path: &str) -> Result<Memo, String> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
         let memo = self
-            .read_current_memo(id)
-            .ok_or_else(|| format!("memo {id} not in memo index"))?;
+            .read_current_memo(relative_path)
+            .ok_or_else(|| format!("note path {relative_path} not in index"))?;
         self.reload_memo_inner_locked(memo)
     }
 
@@ -611,16 +629,10 @@ impl MemoFile {
             .map(|e| MemoFile::index_entry_to_memo(&e))
     }
 
-    /// 按 id 找 memo 物理文件绝对路径。文件可能已不在 (返回路径不保证存在)。
-    pub fn find_memo_file_path(&self, id: &str) -> Option<PathBuf> {
-        let location = self.resolve_memo_location(id).ok().flatten()?;
-        Some(
-            notebook_path_from_relative(
-                &PathBuf::from(location.notebook.path),
-                &location.memo.relative_path,
-            )
-            .ok()?,
-        )
+    /// 按 notebook-relative path 取得笔记绝对路径。文件可能已不在。
+    pub fn find_memo_file_path(&self, relative_path: &str) -> Option<PathBuf> {
+        let base = self.get_memo_base();
+        notebook_path_from_relative(&base, relative_path).ok()
     }
 
     /// 按 filename 拼绝对路径。
@@ -652,12 +664,10 @@ impl MemoFile {
         .collect();
         if let serde_json::Value::Object(properties) = &memo.properties {
             for (key, value) in properties {
-                if is_system_frontmatter_key(key)
-                    || matches!(
-                        key.as_str(),
-                        "tag" | "tags" | "flowix_favorited" | "flowix_icon" | "flowix_colors"
-                    )
-                {
+                if matches!(
+                    key.as_str(),
+                    "tag" | "tags" | "flowix_favorited" | "flowix_icon" | "flowix_colors"
+                ) {
                     continue;
                 }
                 overrides.insert(
@@ -684,10 +694,7 @@ impl MemoFile {
 
     pub fn sync_metadata_only_global(&self, memo: &Memo) -> std::io::Result<()> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
-        let notebook_id = self
-            .resolve_memo_location(&memo.id)?
-            .map(|location| location.notebook.id)
-            .unwrap_or_else(|| self.current_notebook_id_for_index());
+        let notebook_id = self.current_notebook_id_for_index();
         let rebuilt = self.persist_memo_metadata_to_markdown(&notebook_id, memo)?;
         MemoFile::sync_index_on_write_for_notebook_id_locked(self, &notebook_id, &rebuilt)
     }
@@ -715,7 +722,7 @@ impl MemoFile {
             );
             return false;
         }
-        MemoFile::sync_index_on_delete_locked(self, &memo.id).is_ok()
+        MemoFile::sync_index_on_delete_locked(self, &memo.relative_path).is_ok()
     }
 
     pub fn unregister_memo_by_path_for_notebook_id(
@@ -752,7 +759,7 @@ impl MemoFile {
             // macOS /var vs /private/var / 大小写 / trailing slash 等表示差异,
             // 不应阻断 watcher Remove -> emit Deleted (否则外部 rm / claude code
             // 删除不会更新 memo list, 与 Create 走 watcher 正常工作的不对称)。
-            // `sync_index_on_delete` 按 memo.id 注销, 与 abs_path 表示无关,
+            // `sync_index_on_delete` 按 memo.relative_path 注销, 与 abs_path 表示无关,
             // 继续 unregister 不存在误删风险。
             tracing::debug!(
                 "[watcher-delete] unregister_memo_by_path_for_notebook_id path mismatch (continuing): expected={} actual={}",
@@ -760,7 +767,7 @@ impl MemoFile {
                 abs_path.display()
             );
         }
-        MemoFile::sync_index_on_delete_for_notebook_id_locked(self, notebook_id, &memo.id).is_ok()
+        MemoFile::sync_index_on_delete_for_notebook_id_locked(self, notebook_id, &memo.relative_path).is_ok()
     }
 
     /// Idempotently sync an existing memo entry to the filename currently on disk.
@@ -768,17 +775,18 @@ impl MemoFile {
     /// The watcher can observe `Create/Modify(new_path)` while an internal save is
     /// still holding `current_index_io`. By the time this method obtains the lock,
     /// the save path may already have updated the index to `new_path`. Resolve by
-    /// memo id inside the lock so both states converge and still produce an update.
+    /// relative path inside the lock so both states converge and still produce an update.
     pub fn sync_memo_filename_from_disk_key(
         &self,
-        id: &str,
+        relative_path: &str,
         new_path: &Path,
     ) -> Result<Memo, String> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
+        let notebook_id = self.current_notebook_id_for_index();
         let location = self
-            .resolve_memo_location(id)
+            .resolve_note_location_for_notebook_id(&notebook_id, relative_path)
             .map_err(|e| format!("resolve memo location failed: {e}"))?
-            .ok_or_else(|| format!("memo id not in index: {id}"))?;
+            .ok_or_else(|| format!("note path not in index: {relative_path}"))?;
 
         if !new_path.is_md() {
             return Err(format!("new path is not markdown: {}", new_path.display()));
@@ -813,11 +821,11 @@ impl MemoFile {
         if let Some(existing) = list
             .memos
             .iter()
-            .find(|entry| entry.relative_path == new_relative_path && entry.id != id)
+            .find(|entry| entry.relative_path == new_relative_path && entry.relative_path != relative_path)
         {
             return Err(format!(
-                "new filename already occupied by another memo (id={})",
-                existing.id
+                "new filename already occupied by another note (path={})",
+                existing.relative_path
             ));
         }
 
@@ -829,6 +837,14 @@ impl MemoFile {
         apply_derived_memo_fields(&mut memo, &content);
         memo.updated_at = chrono::Utc::now().timestamp_millis();
 
+        if current_relative_path != memo.relative_path {
+            MemoFile::sync_index_on_delete_for_notebook_id_locked(
+                self,
+                &location.notebook.id,
+                &current_relative_path,
+            )
+            .map_err(|e| format!("remove old note index row failed: {e}"))?;
+        }
         MemoFile::sync_index_on_write_for_notebook_id_locked(self, &location.notebook.id, &memo)
             .map_err(|e| format!("sync memo index failed: {e}"))?;
         Ok(memo)
@@ -837,13 +853,13 @@ impl MemoFile {
     pub fn sync_memo_filename_from_disk_key_for_notebook_id(
         &self,
         notebook_id: &str,
-        id: &str,
+        relative_path: &str,
         new_path: &Path,
     ) -> Result<Memo, String> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
         let existing = self
-            .read_memo_for_notebook_id(notebook_id, id)
-            .ok_or_else(|| format!("memo id not in notebook {notebook_id}: {id}"))?;
+            .read_memo_for_notebook_id(notebook_id, relative_path)
+            .ok_or_else(|| format!("note path not in notebook {notebook_id}: {relative_path}"))?;
 
         if !new_path.is_md() {
             return Err(format!("new path is not markdown: {}", new_path.display()));
@@ -877,34 +893,41 @@ impl MemoFile {
         if let Some(occupied) = list
             .memos
             .iter()
-            .find(|entry| entry.relative_path == new_relative_path && entry.id != id)
+            .find(|entry| entry.relative_path == new_relative_path && entry.relative_path != relative_path)
         {
             return Err(format!(
-                "new filename already occupied by another memo (id={})",
-                occupied.id
+                "new filename already occupied by another note (path={})",
+                occupied.relative_path
             ));
         }
 
         let content = std::fs::read_to_string(new_path)
             .map_err(|e| format!("failed to read new path {}: {e}", new_path.display()))?;
+        let existing_relative_path = existing.relative_path.clone();
         let mut memo = existing;
         memo.filename = new_filename;
         memo.relative_path = new_relative_path;
         apply_derived_memo_fields(&mut memo, &content);
         memo.updated_at = chrono::Utc::now().timestamp_millis();
 
+        if existing_relative_path != memo.relative_path {
+            MemoFile::sync_index_on_delete_for_notebook_id_locked(
+                self,
+                notebook_id,
+                &existing_relative_path,
+            )
+            .map_err(|e| format!("remove old note index row failed: {e}"))?;
+        }
         MemoFile::sync_index_on_write_for_notebook_id_locked(self, notebook_id, &memo)
             .map_err(|e| format!("sync memo index failed: {e}"))?;
         Ok(memo)
     }
 
     /// 物理 rename 同步: 把 memo index entry 从 old_filename 改成 new_filename,
-    /// **保留 id**。 物理文件已由调用方 (OS / 用户) 搬好, 我们不动磁盘。
+    /// 按新的 notebook-relative path 更新索引。物理文件已由调用方搬好。
     ///
     /// 跟 `unregister_memo_by_path` + `register_existing_file` 的"双 register"
-    /// 区别: 后者会生成**新** id, 把同一份磁盘内容当新 memo 入库;
-    /// rename_memo_file 保留 id, 让 memo index 跟着物理 mv 走, 触发
-    /// `MemoEvent::Updated` (id 永不变, 前端 store 按 id patch 即可)。
+    /// 旧路径的索引行会删除，新路径的索引行从 Markdown 重新生成。
     ///
     /// 失败条件:
     /// - old_filename 不在 memo index (没记录)
@@ -912,7 +935,7 @@ impl MemoFile {
     /// - new_filename 不是 .md 后缀
     /// - 任一路径规范化后不在当前 notebook base 下
     ///
-    /// 物理文件 invariant: 调用方负责保证 new_path 实际指向同 id 的内容
+    /// 物理文件 invariant: 调用方负责保证 new_path 实际指向已移动的内容
     /// (即 OS 层 mv 已经完成)。 我们只更新 memo index 索引。
     pub fn rename_memo_file(&self, old_path: &Path, new_path: &Path) -> Result<Memo, String> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
@@ -926,7 +949,7 @@ impl MemoFile {
             Some(m) => m.clone(),
             None => return Err(format!("old path not in memo index: {old_relative_path}")),
         };
-        let id = memo.id.clone();
+        let old_relative_path = memo.relative_path.clone();
 
         // 2. 旧路径在不在当前 notebook base 下 (规范化检查)
         let expected_old_abs = notebook_path_from_relative(&base, &old_relative_path)?;
@@ -944,10 +967,10 @@ impl MemoFile {
 
         // 4. new_filename 不能已在 memo index (会跟另一条 entry 撞名)
         if let Some(existing) = self.find_memo_by_relative_path(&new_relative_path) {
-            if existing.id != id {
+            if existing.relative_path != old_relative_path {
                 return Err(format!(
-                    "new filename already occupied by another memo (id={})",
-                    existing.id
+                    "new filename already occupied by another note (path={})",
+                    existing.relative_path
                 ));
             }
         }
@@ -963,7 +986,12 @@ impl MemoFile {
         let now = chrono::Utc::now().timestamp_millis();
         memo.updated_at = now;
 
-        // 6. 同步 memo index (沿用 sync_index_on_write_locked, 它走 filename 做索引)
+        // A relative path is the note key, so moving the file retires the old
+        // row and rebuilds the new one from Markdown.
+        if old_relative_path != memo.relative_path {
+            MemoFile::sync_index_on_delete_locked(self, &old_relative_path)
+                .map_err(|e| format!("remove old note index row failed: {e}"))?;
+        }
         MemoFile::sync_index_on_write_locked(self, &memo)
             .map_err(|e| format!("sync memo index failed: {e}"))?;
         Ok(memo)
@@ -984,14 +1012,14 @@ impl MemoFile {
     pub fn move_memo_to_directory_for_notebook_id(
         &self,
         notebook_id: &str,
-        memo_id: &str,
+        relative_path: &str,
         parent_relative_path: &str,
     ) -> Result<(Memo, PathBuf, PathBuf), String> {
         let _index_io_guard = self.current_index_io.lock().expect("index_io poisoned");
         let base = self.memo_base_for_notebook_id_result(notebook_id)?;
         let memo = self
-            .read_memo_for_notebook_id(notebook_id, memo_id)
-            .ok_or_else(|| format!("memo id not in notebook {notebook_id}: {memo_id}"))?;
+            .read_memo_for_notebook_id(notebook_id, relative_path)
+            .ok_or_else(|| format!("note path not in notebook {notebook_id}: {relative_path}"))?;
         let old_path = notebook_path_from_relative(&base, &memo.relative_path)?;
         let parent = if parent_relative_path.trim().is_empty() {
             base.clone()
@@ -1054,7 +1082,7 @@ impl MemoFile {
             Some(m) => m,
             None => return Err(format!("old path not in memo index: {old_relative_path}")),
         };
-        let id = memo.id.clone();
+        let old_relative_path = memo.relative_path.clone();
 
         let expected_old_abs = notebook_path_from_relative(&base, &old_relative_path)?;
         if normalize_for_compare(&expected_old_abs) != normalize_for_compare(old_path) {
@@ -1071,10 +1099,10 @@ impl MemoFile {
         if let Some(existing) =
             self.find_memo_by_relative_path_for_notebook_id(notebook_id, &new_relative_path)
         {
-            if existing.id != id {
+            if existing.relative_path != old_relative_path {
                 return Err(format!(
-                    "new filename already occupied by another memo (id={})",
-                    existing.id
+                    "new filename already occupied by another note (path={})",
+                    existing.relative_path
                 ));
             }
         }
@@ -1087,6 +1115,14 @@ impl MemoFile {
         apply_derived_memo_fields(&mut memo, &content);
         memo.updated_at = chrono::Utc::now().timestamp_millis();
 
+        if old_relative_path != memo.relative_path {
+            MemoFile::sync_index_on_delete_for_notebook_id_locked(
+                self,
+                notebook_id,
+                &old_relative_path,
+            )
+            .map_err(|e| format!("remove old note index row failed: {e}"))?;
+        }
         MemoFile::sync_index_on_write_for_notebook_id_locked(self, notebook_id, &memo)
             .map_err(|e| format!("sync memo index failed: {e}"))?;
         Ok(memo)
diff --git a/app/flowix-core/src/memo_file/ops/registration.rs b/app/flowix-core/src/memo_file/ops/registration.rs
index 3076bf47c..7e561d26e 100644
--- a/app/flowix-core/src/memo_file/ops/registration.rs
+++ b/app/flowix-core/src/memo_file/ops/registration.rs
@@ -20,14 +20,6 @@ impl MemoFile {
         self.register_existing_file_for_notebook_id_locked(notebook_id, path)
     }
 
-    pub fn register_existing_file_for_notebook_id_without_frontmatter(
-        &self,
-        notebook_id: &str,
-        path: &Path,
-    ) -> Result<Memo, String> {
-        self.register_existing_file_for_notebook_id(notebook_id, path)
-    }
-
     pub fn register_existing_file_as_new_for_notebook_id(
         &self,
         notebook_id: &str,
@@ -47,30 +39,18 @@ impl MemoFile {
         )
     }
 
-    /// Cloud protocol association lives in the index, never in authored Markdown.
-    pub fn register_existing_file_with_cache_id(
-        &self,
-        notebook_id: &str,
-        path: &Path,
-        cache_id: &str,
-    ) -> Result<Memo, String> {
-        let _guard = self.current_index_io.lock().expect("index_io poisoned");
-        self.register_path_locked(notebook_id, path, Some(cache_id))
-    }
-
     pub(super) fn register_existing_file_for_notebook_id_locked(
         &self,
         notebook_id: &str,
         path: &Path,
     ) -> Result<Memo, String> {
-        self.register_path_locked(notebook_id, path, None)
+        self.register_path_locked(notebook_id, path)
     }
 
     fn register_path_locked(
         &self,
         notebook_id: &str,
         path: &Path,
-        cache_id: Option<&str>,
     ) -> Result<Memo, String> {
         if !path.is_md() || !path.is_file() {
             return Err(format!("not an existing Markdown file: {}", path.display()));
@@ -80,27 +60,11 @@ impl MemoFile {
         if let Some(memo) =
             self.find_memo_by_relative_path_for_notebook_id(notebook_id, &relative_path)
         {
-            if cache_id.is_some_and(|id| id != memo.id) {
-                return Err("path already belongs to another cache entry".into());
-            }
             return self.reload_memo_inner_for_notebook_id_locked(notebook_id, memo);
         }
         let content = fs::read_to_string(path).map_err(|error| error.to_string())?;
-        if let Some(id) = cache_id {
-            if self
-                .resolve_memo_location(id)
-                .map_err(|e| e.to_string())?
-                .is_some()
-            {
-                return Err("cache entry already belongs to another path".into());
-            }
-        }
         let now = chrono::Utc::now().timestamp_millis();
         let mut memo = Memo {
-            // Internal cache/history association only; never a Markdown identity.
-            id: cache_id
-                .map(str::to_string)
-                .unwrap_or_else(|| self.generate_global_memo_id()),
             filename: filename_from_notebook_relative_path(&relative_path),
             relative_path,
             preview: String::new(),
diff --git a/app/flowix-core/src/memo_file/ops/tags.rs b/app/flowix-core/src/memo_file/ops/tags.rs
index 5c76aced3..31967a8f1 100644
--- a/app/flowix-core/src/memo_file/ops/tags.rs
+++ b/app/flowix-core/src/memo_file/ops/tags.rs
@@ -28,10 +28,6 @@ impl MemoFile {
         const MIGRATION_KEY: &str = "yaml-body-tag-union-index";
         const MIGRATION_VERSION: u32 = 1;
 
-        let _guard = self
-            .current_index_io
-            .lock()
-            .unwrap_or_else(|poisoned| poisoned.into_inner());
         if self
             .notebook_data_migration_version(notebook_id, MIGRATION_KEY)?
             .unwrap_or_default()
@@ -40,41 +36,14 @@ impl MemoFile {
             return Ok(0);
         }
 
-        let base = self
-            .memo_base_for_notebook_id_result(notebook_id)
+        // Tags are derived directly from Markdown into notes.tags. This
+        // migration now rebuilds the path index instead of backfilling the
+        // duplicate path projection.
+        let report = self
+            .reconcile_note_index(notebook_id)
             .map_err(std::io::Error::other)?;
-        let entries = self
-            .read_index_for_notebook_id(Some(notebook_id))?
-            .unwrap_or_default()
-            .memos;
-        let mut updated = 0usize;
-        for entry in entries {
-            let path = super::super::notebook_path_from_relative(&base, &entry.relative_path)
-                .map_err(std::io::Error::other)
-                .unwrap_or_else(|_| base.join(&entry.filename));
-            let content = match std::fs::read_to_string(&path) {
-                Ok(content) => content,
-                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
-                    tracing::debug!(
-                        notebook = %notebook_id,
-                        path = %path.display(),
-                        "skip tag migration for missing memo file"
-                    );
-                    continue;
-                }
-                Err(error) => return Err(error),
-            };
-            let before = entry.tags.clone();
-            let mut memo = MemoFile::index_entry_to_memo(&entry);
-            apply_derived_memo_fields(&mut memo, &content);
-            if memo.tags != before {
-                MemoFile::sync_index_on_write_for_notebook_id_locked(self, notebook_id, &memo)?;
-                updated += 1;
-            }
-        }
-
         self.mark_notebook_data_migration(notebook_id, MIGRATION_KEY, MIGRATION_VERSION)?;
-        Ok(updated)
+        Ok(report.updated + report.added)
     }
 
     pub fn move_memo_tag_locked(
@@ -143,26 +112,18 @@ impl MemoFile {
             .map(str::to_string)
             .unwrap_or_else(|| self.current_notebook_id_for_index());
 
-        // 4. 冲突检查: new_path 在该 notebook 是否已存在
-        let conn = self.open_memo_index_db_for_notebook_id(&notebook_id_owned)?;
         let prefix = format!("{old_path}/");
-        let mut catalog_stmt = conn
-            .prepare(
-                "SELECT path FROM notebook_tags
-                 WHERE notebook_id = ?1
-                   AND (path = ?2 OR path LIKE ?3 ESCAPE '\\')
-                 ORDER BY length(path) ASC, path ASC",
-            )
-            .map_err(sqlite_to_io)?;
-        let catalog_paths: Vec<String> = catalog_stmt
-            .query_map(
-                rusqlite::params![&notebook_id_owned, &old_path, format!("{prefix}%")],
-                |row| row.get(0),
-            )
-            .map_err(sqlite_to_io)?
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(sqlite_to_io)?;
-        drop(catalog_stmt);
+        // Tags are derived from notes.tags. Moving a subtree changes the
+        // Markdown source and never writes a separate tag catalog.
+        let existing_tag_paths: std::collections::HashSet<String> = self
+            .read_notebook_tag_paths(Some(&notebook_id_owned))?
+            .into_iter()
+            .collect();
+        let catalog_paths: Vec<String> = existing_tag_paths
+            .iter()
+            .cloned()
+            .filter(|path| path == &old_path || path.starts_with(&prefix))
+            .collect();
         let renamed_catalog_paths: Vec<(String, String)> = catalog_paths
             .iter()
             .map(|path| {
@@ -173,19 +134,7 @@ impl MemoFile {
         let moving_paths: std::collections::HashSet<&str> =
             catalog_paths.iter().map(String::as_str).collect();
         for (_, target) in &renamed_catalog_paths {
-            let collision: Option<String> = conn
-                .query_row(
-                    "SELECT path FROM notebook_tags
-                     WHERE notebook_id = ?1 AND path = ?2 LIMIT 1",
-                    rusqlite::params![&notebook_id_owned, target],
-                    |row| row.get(0),
-                )
-                .optional()
-                .map_err(sqlite_to_io)?;
-            if collision
-                .as_deref()
-                .is_some_and(|path| !moving_paths.contains(path))
-            {
+            if existing_tag_paths.contains(target) && !moving_paths.contains(target.as_str()) {
                 return Err(std::io::Error::new(
                     std::io::ErrorKind::AlreadyExists,
                     format!("target tag already exists in notebook: {target}"),
@@ -193,15 +142,14 @@ impl MemoFile {
             }
         }
 
-        let new_exists = self.note_tag_exists(&notebook_id_owned, &new_path)?;
-        if new_exists {
+        if existing_tag_paths.contains(&new_path) && !moving_paths.contains(new_path.as_str()) {
             return Err(std::io::Error::new(
                 std::io::ErrorKind::AlreadyExists,
                 format!("target tag already exists in notebook: {new_path}"),
             ));
         }
 
-        // 5. 找所有 affected note relative_path (note_tags 里有 old_path 或 old_path/*)
+        // 5. Find notes whose derived tags match this path or a descendant.
         let affected_paths: Vec<String> =
             self.note_paths_with_tag(&notebook_id_owned, &old_path)?;
         if catalog_paths.is_empty() && affected_paths.is_empty() {
@@ -283,7 +231,7 @@ impl MemoFile {
 
             atomic_write_bytes(&path, merged.as_bytes())?;
 
-            // 重新派生 Note 投影 + note_tags。
+            // Refresh the path projection from the edited Markdown.
             self.refresh_note_path(&notebook_id_owned, relative_path)?;
 
             // 写盘 + 投影同步完成后, 把 relative_path 交回调用方 ── 调用方
@@ -294,29 +242,6 @@ impl MemoFile {
             report.affected_memos += 1;
         }
 
-        let mut catalog_conn = self.open_memo_index_db_for_notebook_id(&notebook_id_owned)?;
-        let catalog_tx = catalog_conn.transaction().map_err(sqlite_to_io)?;
-        for old in &catalog_paths {
-            catalog_tx
-                .execute(
-                    "DELETE FROM notebook_tags WHERE notebook_id = ?1 AND path = ?2",
-                    rusqlite::params![&notebook_id_owned, old],
-                )
-                .map_err(sqlite_to_io)?;
-        }
-        let now = chrono::Utc::now().timestamp_millis();
-        for (_, new) in &renamed_catalog_paths {
-            catalog_tx
-                .execute(
-                    "INSERT OR REPLACE INTO notebook_tags
-                        (notebook_id, path, created_at, updated_at)
-                     VALUES (?1, ?2, ?3, ?3)",
-                    rusqlite::params![&notebook_id_owned, new, now],
-                )
-                .map_err(sqlite_to_io)?;
-        }
-        catalog_tx.commit().map_err(sqlite_to_io)?;
-
         Ok(report)
     }
 
@@ -324,15 +249,15 @@ impl MemoFile {
     /// under `tag_path/`) from YAML, body tokens, and the memo index.
     ///
     /// Semantics:
-    /// - `tag_path` itself: removed from `memo_tags`, YAML, and body tokens.
+    /// - `tag_path` itself: removed from the note index, YAML, and body tokens.
     /// - `tag_path/<...>` subtree (any depth): all of them are removed in
     ///   one shot from both sources and the derived index.
     /// - Other tags and non-tag body text are untouched.
     ///
     /// Constraints (caller has roughly validated; we re-validate defensively):
     /// 1. `tag_path` must pass [`normalize_tag_path`] (legal path).
-    /// 2. `tag_path` must exist in this notebook (`memo_tags` table has at
-    ///    least one `tag = tag_path` or `tag LIKE tag_path/%` entry);
+    /// 2. `tag_path` must exist in this notebook's `notes.tags` projection
+    ///    at the given path or somewhere in its descendant subtree;
     ///    otherwise we error out.
     ///
     /// Locking: same as `move_memo_tag_locked` -- enters holding
@@ -383,28 +308,14 @@ impl MemoFile {
             .map(str::to_string)
             .unwrap_or_else(|| self.current_notebook_id_for_index());
 
-        let conn = self.open_memo_index_db_for_notebook_id(&notebook_id_owned)?;
-
         // 3. collect every tag path to delete: `tag_path` itself + every
         //    subtree tag at any depth.
         let prefix = format!("{tag_path}/");
-        let mut stmt = conn
-            .prepare(
-                "SELECT path FROM notebook_tags
-                 WHERE notebook_id = ?1
-                   AND (path = ?2 OR path LIKE ?3 ESCAPE '\\')
-                 ORDER BY length(path) DESC, path ASC",
-            )
-            .map_err(sqlite_to_io)?;
-        let deleted_tags: Vec<String> = stmt
-            .query_map(
-                rusqlite::params![&notebook_id_owned, &tag_path, format!("{prefix}%")],
-                |row| row.get(0),
-            )
-            .map_err(sqlite_to_io)?
-            .collect::<Result<Vec<_>, _>>()
-            .map_err(sqlite_to_io)?;
-        drop(stmt);
+        let deleted_tags: Vec<String> = self
+            .read_notebook_tag_paths(Some(&notebook_id_owned))?
+            .into_iter()
+            .filter(|path| path == &tag_path || path.starts_with(&prefix))
+            .collect();
 
         // 4. collect affected note relative_paths
         let affected_paths: Vec<String> =
@@ -472,18 +383,6 @@ impl MemoFile {
             report.affected_memos += 1;
         }
 
-        let mut catalog_conn = self.open_memo_index_db_for_notebook_id(&notebook_id_owned)?;
-        let catalog_tx = catalog_conn.transaction().map_err(sqlite_to_io)?;
-        for deleted in &report.deleted_tags {
-            catalog_tx
-                .execute(
-                    "DELETE FROM notebook_tags WHERE notebook_id = ?1 AND path = ?2",
-                    rusqlite::params![&notebook_id_owned, deleted],
-                )
-                .map_err(sqlite_to_io)?;
-        }
-        catalog_tx.commit().map_err(sqlite_to_io)?;
-
         Ok(report)
     }
 }
diff --git a/app/flowix-core/src/memo_file/registration.rs b/app/flowix-core/src/memo_file/registration.rs
index 694a9bfd3..26ccdf473 100644
--- a/app/flowix-core/src/memo_file/registration.rs
+++ b/app/flowix-core/src/memo_file/registration.rs
@@ -1,4 +1,2 @@
-//! Legacy memo-ID registration and disk reconciliation live in
-//! `ops::registration` and `ops::reconcile`. Registering an
-//! existing Markdown file associates its notebook-relative path with an
-//! internal cache ID without changing the file or reading `flowix_key`.
+//! Markdown registration and disk reconciliation live in
+//! `ops::registration` and `ops::reconcile`.
diff --git a/app/flowix-core/src/memo_file/storage_repair.rs b/app/flowix-core/src/memo_file/storage_repair.rs
new file mode 100644
index 000000000..421aeb62c
--- /dev/null
+++ b/app/flowix-core/src/memo_file/storage_repair.rs
@@ -0,0 +1,327 @@
+//! Small startup helpers for recreatable application storage.
+use std::{
+    error::Error,
+    fs, io,
+    path::{Path, PathBuf},
+};
+
+/// Preserve a database and all its SQLite companions in one backup directory.
+/// No replacement is attempted unless every existing component was preserved.
+pub fn backup_database(path: &Path) -> io::Result<Option<PathBuf>> {
+    backup_files(path, &["", "-wal", "-shm", "-journal"])
+}
+
+pub fn backup_storage_file(path: &Path) -> io::Result<Option<PathBuf>> {
+    backup_files(path, &[""])
+}
+
+fn backup_files(path: &Path, suffixes: &[&str]) -> io::Result<Option<PathBuf>> {
+    let mut sources = Vec::new();
+    for suffix in suffixes {
+        let mut name = path.as_os_str().to_os_string();
+        name.push(suffix);
+        let source = PathBuf::from(name);
+        match fs::symlink_metadata(&source) {
+            Ok(_) => sources.push(source),
+            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+            Err(error) => return Err(error),
+        }
+    }
+    if sources.is_empty() {
+        return Ok(None);
+    }
+    let parent = path
+        .parent()
+        .ok_or_else(|| io::Error::other("storage path has no parent"))?;
+    let backup = parent
+        .join("rebuild-backups")
+        .join(uuid::Uuid::new_v4().to_string());
+    fs::create_dir_all(&backup)?;
+    let mut moved: Vec<(PathBuf, PathBuf)> = Vec::new();
+    for source in sources {
+        let target = backup.join(source.file_name().unwrap());
+        if let Err(error) = fs::rename(&source, &target) {
+            for (source, target) in moved.iter().rev() {
+                if let Err(rollback) = fs::rename(target, source) {
+                    return Err(io::Error::other(format!(
+                        "backup failed: {error}; rollback failed: {rollback}; preserved files: {}",
+                        backup.display()
+                    )));
+                }
+            }
+            return Err(error);
+        }
+        moved.push((source, target));
+    }
+    tracing::warn!(path = %path.display(), backup = %backup.display(), "preserved abnormal application storage before rebuilding");
+    Ok(Some(backup))
+}
+
+/// Busy, permission, disk-full and I/O errors must never move a live database.
+pub fn is_rebuildable_storage_error(error: &(dyn Error + 'static)) -> bool {
+    let mut current = Some(error);
+    while let Some(error) = current {
+        if let Some(sqlite) = error.downcast_ref::<rusqlite::Error>() {
+            return match sqlite {
+                rusqlite::Error::SqlInputError { msg, .. } => [
+                    "no such table",
+                    "no such column",
+                    "has no column",
+                    "malformed",
+                ]
+                .iter()
+                .any(|part| msg.contains(part)),
+                rusqlite::Error::SqliteFailure(code, Some(message))
+                    if code.code == rusqlite::ErrorCode::Unknown =>
+                {
+                    [
+                        "no such table",
+                        "no such column",
+                        "has no column",
+                        "malformed",
+                    ]
+                    .iter()
+                    .any(|part| message.contains(part))
+                }
+                rusqlite::Error::SqliteFailure(code, _) => matches!(
+                    code.code,
+                    rusqlite::ErrorCode::DatabaseCorrupt
+                        | rusqlite::ErrorCode::NotADatabase
+                        | rusqlite::ErrorCode::SchemaChanged
+                ),
+                rusqlite::Error::InvalidColumnName(_)
+                | rusqlite::Error::InvalidColumnType(..)
+                | rusqlite::Error::FromSqlConversionFailure(..) => true,
+                _ => false,
+            };
+        }
+        if let Some(io) = error.downcast_ref::<io::Error>() {
+            if io.kind() == io::ErrorKind::InvalidData {
+                return true;
+            }
+            if let Some(inner) = io.get_ref() {
+                current = Some(inner);
+                continue;
+            }
+        }
+        current = error.source();
+    }
+    false
+}
+
+/// The operation must release its connections before returning an error.
+pub fn with_database_rebuild<T>(
+    path: &Path,
+    mut initialize: impl FnMut() -> io::Result<T>,
+) -> io::Result<T> {
+    // Serialize initialization and repair across processes. Ordinary database
+    // access must not call this helper or rename storage held by other readers.
+    if let Some(parent) = path.parent() { ensure_storage_directory(parent)?; }
+    let mut lock_path = path.as_os_str().to_os_string();
+    lock_path.push(".rebuild.lock");
+    let lock = fs::OpenOptions::new().create(true).truncate(false)
+        .read(true).write(true).open(PathBuf::from(lock_path))?;
+    fs2::FileExt::lock_exclusive(&lock)?;
+    match fs::symlink_metadata(path) {
+        Ok(metadata) if !metadata.file_type().is_file() => {
+            backup_database(path)?;
+        }
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {
+            backup_database(path)?;
+        }
+        _ => {}
+    }
+    match initialize() {
+        Ok(value) => Ok(value),
+        Err(error) if is_rebuildable_storage_error(&error) => {
+            tracing::warn!(%error, path = %path.display(), "recreating abnormal application database");
+            backup_database(path)?;
+            initialize()
+        }
+        Err(error) => Err(error),
+    }
+}
+
+pub fn ensure_storage_directory(path: &Path) -> io::Result<()> {
+    if fs::symlink_metadata(path).is_ok() && !path.is_dir() {
+        backup_storage_file(path)?;
+    }
+    fs::create_dir_all(path)
+}
+
+/// JSON owned by the application: preserve malformed input, then persist defaults.
+pub fn read_or_create_json<T>(path: &Path, default: impl FnOnce() -> T) -> io::Result<T>
+where
+    T: serde::de::DeserializeOwned + serde::Serialize,
+{
+    if let Some(parent) = path.parent() { ensure_storage_directory(parent)?; }
+    match fs::read(path) {
+        Ok(bytes) => match serde_json::from_slice(&bytes) {
+            Ok(value) => return Ok(value),
+            Err(_) => {
+                backup_storage_file(path)?;
+            }
+        },
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+        Err(error) if error.kind() == io::ErrorKind::IsADirectory => {
+            backup_storage_file(path)?;
+        }
+        Err(error) => return Err(error),
+    }
+    let value = default();
+    let bytes = serde_json::to_vec_pretty(&value).map_err(io::Error::other)?;
+    super::atomic_write_bytes(path, &bytes)?;
+    Ok(value)
+}
+
+#[cfg(test)]
+mod storage_rebuild_tests {
+    use super::*;
+    use crate::memo_file::{prepare_database_directory, MemoFile, NotebookConfig};
+
+    #[test]
+    fn preserves_complete_sqlite_group() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("local.db");
+        for suffix in ["", "-wal", "-shm", "-journal"] {
+            fs::write(
+                temp.path().join(format!("local.db{suffix}")),
+                suffix.as_bytes(),
+            )
+            .unwrap();
+        }
+        let backup = backup_database(&path).unwrap().unwrap();
+        for suffix in ["", "-wal", "-shm", "-journal"] {
+            assert_eq!(
+                fs::read(backup.join(format!("local.db{suffix}"))).unwrap(),
+                suffix.as_bytes()
+            );
+            assert!(!temp.path().join(format!("local.db{suffix}")).exists());
+        }
+    }
+
+    #[test]
+    fn canonical_database_does_not_receive_legacy_wal() {
+        let temp = tempfile::tempdir().unwrap();
+        fs::create_dir(temp.path().join("db")).unwrap();
+        fs::write(temp.path().join("local.db"), b"legacy").unwrap();
+        fs::write(temp.path().join("local.db-wal"), b"legacy wal").unwrap();
+        fs::write(temp.path().join("db/local.db"), b"canonical").unwrap();
+        prepare_database_directory(temp.path(), &["local.db"]).unwrap();
+        assert_eq!(
+            fs::read(temp.path().join("db/local.db")).unwrap(),
+            b"canonical"
+        );
+        assert!(!temp.path().join("db/local.db-wal").exists());
+        assert_eq!(
+            fs::read(temp.path().join("local.db-wal")).unwrap(),
+            b"legacy wal"
+        );
+    }
+
+    #[test]
+    fn invalid_registry_rebuilds_and_legacy_input_cannot_block_startup() {
+        let temp = tempfile::tempdir().unwrap();
+        fs::create_dir(temp.path().join("db")).unwrap();
+        fs::write(temp.path().join("db/local.db"), b"broken registry").unwrap();
+        fs::write(temp.path().join("db/index.db"), b"broken legacy").unwrap();
+        let memo = MemoFile::new(temp.path().to_path_buf());
+        memo.initialize_registry_storage().unwrap();
+        assert!(memo.read_notebook_configs().unwrap().is_empty());
+        assert!(memo.read_notebook_workspace().unwrap().notebooks.is_empty());
+        let backups = fs::read_dir(temp.path().join("db/rebuild-backups"))
+            .unwrap()
+            .count();
+        assert_eq!(backups, 1);
+        memo.initialize_registry_storage().unwrap();
+        assert_eq!(
+            fs::read_dir(temp.path().join("db/rebuild-backups"))
+                .unwrap()
+                .count(),
+            1
+        );
+    }
+
+    #[test]
+    fn malformed_registry_schema_is_recreated() {
+        let temp = tempfile::tempdir().unwrap();
+        fs::create_dir(temp.path().join("db")).unwrap();
+        let path = temp.path().join("db/local.db");
+        let conn = rusqlite::Connection::open(&path).unwrap();
+        conn.execute_batch("CREATE TABLE notebooks(id TEXT);")
+            .unwrap();
+        drop(conn);
+        let memo = MemoFile::new(temp.path().to_path_buf());
+        memo.initialize_registry_storage().unwrap();
+        assert!(memo.read_notebook_configs().unwrap().is_empty());
+        assert!(path.parent().unwrap().join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn malformed_json_is_preserved_and_defaults_are_persisted() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("preference.json");
+        fs::write(&path, b"{broken").unwrap();
+        let value: serde_json::Value =
+            read_or_create_json(&path, || serde_json::json!({"language":"zh-CN"})).unwrap();
+        assert_eq!(value["language"], "zh-CN");
+        assert_eq!(
+            serde_json::from_slice::<serde_json::Value>(&fs::read(&path).unwrap()).unwrap(),
+            value
+        );
+        assert!(temp.path().join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn busy_database_is_not_moved_or_rebuilt() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("local.db");
+        fs::write(&path, b"keep").unwrap();
+        let result: io::Result<()> = with_database_rebuild(&path, || {
+            Err(io::Error::other(rusqlite::Error::SqliteFailure(
+                rusqlite::ffi::Error::new(rusqlite::ffi::SQLITE_BUSY),
+                None,
+            )))
+        });
+        assert!(result.is_err());
+        assert_eq!(fs::read(&path).unwrap(), b"keep");
+        assert!(!temp.path().join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn notebook_database_rebuild_keeps_markdown_and_attachments() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path().join("notebook");
+        fs::create_dir_all(root.join(".flowix")).unwrap();
+        fs::create_dir_all(root.join("attachments")).unwrap();
+        fs::write(root.join("kept.md"), b"# Keep this note\n").unwrap();
+        fs::write(root.join("attachments/kept.bin"), b"attachment").unwrap();
+        fs::write(
+            root.join(".flowix/notebook.db"),
+            b"invalid notebook database",
+        )
+        .unwrap();
+        let memo = MemoFile::new(temp.path().join("config"));
+        memo.write_notebook_configs(&[NotebookConfig {
+            id: "nb_kept".into(),
+            name: "Kept".into(),
+            icon: None,
+            path: root.to_string_lossy().into_owned(),
+            is_default: false,
+            sort: 0,
+            created_at: 0,
+            updated_at: 0,
+        }])
+        .unwrap();
+        memo.reconcile_note_index_blocking("nb_kept").unwrap();
+        assert_eq!(
+            fs::read(root.join("kept.md")).unwrap(),
+            b"# Keep this note\n"
+        );
+        assert_eq!(
+            fs::read(root.join("attachments/kept.bin")).unwrap(),
+            b"attachment"
+        );
+        assert!(root.join(".flowix/rebuild-backups").exists());
+    }
+}
diff --git a/app/flowix-core/src/memo_file/tests.rs b/app/flowix-core/src/memo_file/tests.rs
index b223f9010..8191e3ad9 100644
--- a/app/flowix-core/src/memo_file/tests.rs
+++ b/app/flowix-core/src/memo_file/tests.rs
@@ -17,7 +17,6 @@ use super::ops::{
 use super::types::MemoIndexFile;
 use super::MemoFile;
 use std::fs;
-use std::path::Path;
 use std::path::PathBuf;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
@@ -26,7 +25,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 // =====================================================================
 
 /// 测试 fixture: 构造一个 MemoFile 指向 tempdir, 模拟 "default notebook"。
-/// `read_notebook_configs` 走 `index.db` (SQLite), `get_memo_base` 通过
+/// `read_notebook_configs` 走 `local.db` (SQLite), `get_memo_base` 通过
 /// `set_current_notebook` 走当前 notebook id 而不是 fallback。helper 只负责
 /// 给 `MemoFile` 传两个路径 + 切到 "nb_test", 不再写任何
 /// legacy JSON。`AtomicUsize` + nanos 后缀防并行 cargo test 撞名。
@@ -63,23 +62,19 @@ fn fresh_memo_file() -> (MemoFile, PathBuf) {
 }
 
 #[test]
-fn create_memo_generates_eight_char_id() {
+fn create_memo_uses_relative_path_as_compatibility_key() {
     let (mf, _tmp) = fresh_memo_file();
     let memo = mf.create_memo("Eight", "body", None).unwrap();
 
-    assert_eq!(memo.id.len(), super::MEMO_ID_LENGTH);
-    assert!(memo
-        .id
-        .chars()
-        .all(|c| c.is_ascii_digit() || c.is_ascii_lowercase()));
+    assert_eq!(memo.relative_path, memo.relative_path);
 
     let content = fs::read_to_string(mf.get_memo_base().join(&memo.filename)).unwrap();
-    assert_eq!(super::frontmatter::extract_frontmatter_key(&content), None);
+    assert!(!content.contains("flowix_key:"));
 }
 
 /// 读 memo index 原始 JSON 字符串 (不反序列化, 用于 schema 断言)。
 #[test]
-fn notebook_json_is_migrated_to_index_db() {
+fn notebook_json_is_migrated_to_local_db() {
     let (mf, _tmp) = fresh_memo_file();
 
     let configs = mf.read_notebook_configs().expect("read notebooks");
@@ -154,80 +149,6 @@ fn selected_notebook_state_is_shared_and_rejects_unknown_ids() {
     assert_eq!(other_process.read_selected_notebook_id().unwrap(), None);
 }
 
-#[test]
-fn content_revision_is_created_and_advanced_only_for_changed_bytes() {
-    let (mf, _tmp) = fresh_memo_file();
-    let memo = mf.create_memo("Revision", "# Revision", None).unwrap();
-
-    let first = mf
-        .commit_memo_content_revision(&memo.id, "nb_test", "hash-a", "change-a")
-        .unwrap();
-    assert!(first.changed);
-    assert_eq!(first.state.revision, 1);
-    assert_eq!(first.state.change_id, "change-a");
-
-    let duplicate = mf
-        .commit_memo_content_revision(&memo.id, "nb_test", "hash-a", "discarded")
-        .unwrap();
-    assert!(!duplicate.changed);
-    assert_eq!(duplicate.state.revision, 1);
-    assert_eq!(duplicate.state.change_id, "change-a");
-
-    let second = mf
-        .commit_memo_content_revision(&memo.id, "nb_test", "hash-b", "change-b")
-        .unwrap();
-    assert!(second.changed);
-    assert_eq!(second.state.revision, 2);
-    assert_eq!(second.state.change_id, "change-b");
-
-    let reverted = mf
-        .commit_memo_content_revision(&memo.id, "nb_test", "hash-a", "change-c")
-        .unwrap();
-    assert!(reverted.changed);
-    assert_eq!(reverted.state.revision, 3);
-    assert_eq!(reverted.state.change_id, "change-c");
-    assert_eq!(
-        mf.read_memo_content_revision(&memo.id).unwrap(),
-        Some(reverted.state)
-    );
-
-    // Full metadata index rewrites must not reset the independent content
-    // revision stream.
-    let index = mf.read_index().unwrap();
-    mf.write_index(&index).unwrap();
-    assert_eq!(
-        mf.read_memo_content_revision(&memo.id)
-            .unwrap()
-            .unwrap()
-            .revision,
-        3,
-    );
-}
-
-#[test]
-fn opening_legacy_index_creates_content_revision_table() {
-    let (mf, _tmp) = fresh_memo_file();
-    // Legacy memo tables live in the per-notebook notebook.db, not the registry.
-    let notebook_db = mf.notebook_db_path("nb_test").unwrap();
-    let conn = rusqlite::Connection::open(&notebook_db).unwrap();
-    conn.execute_batch("DROP TABLE IF EXISTS memo_content_revisions;")
-        .unwrap();
-    drop(conn);
-
-    // Any memo-index operation runs the additive schema migration.
-    mf.invalidate_caches();
-    let _ = mf.read_index();
-    let conn = rusqlite::Connection::open(&notebook_db).unwrap();
-    let exists: i64 = conn
-        .query_row(
-            "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'memo_content_revisions'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert_eq!(exists, 1);
-}
-
 #[test]
 fn pending_data_migrations_run_once_and_persist_version() {
     let (mf, base) = fresh_memo_file();
@@ -247,167 +168,8 @@ fn pending_data_migrations_run_once_and_persist_version() {
     );
 }
 
-/// Global indexes written before the lifecycle refactor have `memos` but no
-/// `memo_lifecycles`. The legacy import must skip the missing table instead of
-/// failing startup data migrations (regression for
-/// "no such table: legacy_index.memo_lifecycles").
-#[test]
-fn legacy_global_index_without_memo_lifecycles_imports_cleanly() {
-    let (mf, base) = fresh_memo_file();
-    // Seed the registry db with a pre-lifecycle global index: `memos` exists,
-    // `memo_lifecycles` does not.
-    let legacy_path = mf.registry_db_path();
-    let legacy = rusqlite::Connection::open(&legacy_path).unwrap();
-    legacy
-        .execute_batch(
-            r#"
-            CREATE TABLE memos (
-                id TEXT PRIMARY KEY,
-                notebook_id TEXT NOT NULL,
-                filename TEXT NOT NULL,
-                relative_path TEXT NOT NULL,
-                preview TEXT,
-                thumbnail TEXT,
-                thumbnail_checked INTEGER NOT NULL DEFAULT 0,
-                agents_checked INTEGER NOT NULL DEFAULT 0,
-                created_at INTEGER NOT NULL,
-                updated_at INTEGER NOT NULL,
-                favorited INTEGER NOT NULL DEFAULT 0,
-                icon TEXT,
-                properties TEXT
-            );
-            INSERT INTO memos (id, notebook_id, filename, relative_path, created_at, updated_at)
-            VALUES ('memo-legacy-1', 'nb_test', 'Old.md', 'Old.md', 1, 1);
-            "#,
-        )
-        .unwrap();
-    drop(legacy);
-
-    let report = mf.run_pending_data_migrations().unwrap();
-    assert_eq!(report.to_version, super::LATEST_DATA_MIGRATION_VERSION);
-
-    // The legacy memo row is imported into the notebook-local index, and the
-    // lifecycle table is backfilled from the imported memos.
-    let notebook_db = mf.notebook_db_path("nb_test").unwrap();
-    let conn = rusqlite::Connection::open(&notebook_db).unwrap();
-    let memos: i64 = conn
-        .query_row(
-            "SELECT COUNT(*) FROM memos WHERE notebook_id = 'nb_test'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert_eq!(memos, 1);
-    let lifecycles: i64 = conn
-        .query_row(
-            "SELECT COUNT(*) FROM memo_lifecycles WHERE memo_id = 'memo-legacy-1'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert_eq!(lifecycles, 1);
-    assert!(base.join(".flowix/notebook.json").is_file());
-}
-
-/// Real-world pre-refactor global indexes (observed in the field) lack
-/// `memos.relative_path`, lack `memo_todos.todo_id`, and lack
-/// `memo_lifecycles` entirely. The import must adapt: filename becomes the
-/// relative path, todo ids are synthesized from rowids, and lifecycle rows
-/// are backfilled.
-#[test]
-fn legacy_global_index_with_pre_relative_path_schema_imports_cleanly() {
-    let (mf, _tmp) = fresh_memo_file();
-    let legacy_path = mf.registry_db_path();
-    let legacy = rusqlite::Connection::open(&legacy_path).unwrap();
-    legacy
-        .execute_batch(
-            r#"
-            CREATE TABLE memos (
-                id TEXT PRIMARY KEY,
-                notebook_id TEXT NOT NULL,
-                filename TEXT NOT NULL,
-                preview TEXT NOT NULL,
-                thumbnail TEXT,
-                thumbnail_checked INTEGER NOT NULL DEFAULT 0,
-                agents_checked INTEGER NOT NULL DEFAULT 0,
-                created_at INTEGER NOT NULL,
-                updated_at INTEGER NOT NULL,
-                favorited INTEGER NOT NULL,
-                icon TEXT,
-                properties TEXT NOT NULL DEFAULT '{}'
-            );
-            CREATE TABLE memo_todos (
-                memo_id TEXT NOT NULL,
-                content TEXT NOT NULL,
-                status TEXT NOT NULL,
-                priority TEXT NOT NULL,
-                time_range TEXT NOT NULL,
-                owner TEXT NOT NULL,
-                assignee TEXT NOT NULL,
-                created_at INTEGER NOT NULL,
-                updated_at INTEGER NOT NULL,
-                position INTEGER NOT NULL
-            );
-            CREATE TABLE memo_content_revisions (
-                memo_id TEXT PRIMARY KEY,
-                notebook_id TEXT NOT NULL,
-                content_hash TEXT NOT NULL,
-                local_revision INTEGER NOT NULL,
-                change_id TEXT NOT NULL,
-                updated_at INTEGER NOT NULL
-            );
-            INSERT INTO memos (id, notebook_id, filename, preview, created_at, updated_at, favorited)
-            VALUES ('memo-legacy-1', 'nb_test', 'Old.md', '# Old', 1, 1, 0);
-            INSERT INTO memo_todos (memo_id, content, status, priority, time_range, owner, assignee, created_at, updated_at, position)
-            VALUES ('memo-legacy-1', 'task', 'open', '', '', '', '', 1, 1, 0);
-            INSERT INTO memo_content_revisions (memo_id, notebook_id, content_hash, local_revision, change_id, updated_at)
-            VALUES ('memo-legacy-1', 'nb_test', 'hash-a', 1, 'change-a', 1);
-            "#,
-        )
-        .unwrap();
-    drop(legacy);
-
-    let report = mf.run_pending_data_migrations().unwrap();
-    assert_eq!(report.to_version, super::LATEST_DATA_MIGRATION_VERSION);
-
-    let notebook_db = mf.notebook_db_path("nb_test").unwrap();
-    let conn = rusqlite::Connection::open(&notebook_db).unwrap();
-    let (imported_relative_path, imported_preview): (String, String) = conn
-        .query_row(
-            "SELECT relative_path, preview FROM memos WHERE id = 'memo-legacy-1'",
-            [],
-            |row| Ok((row.get(0)?, row.get(1)?)),
-        )
-        .unwrap();
-    assert_eq!(imported_relative_path, "Old.md");
-    assert_eq!(imported_preview, "# Old");
-    let todo_id: String = conn
-        .query_row(
-            "SELECT todo_id FROM memo_todos WHERE memo_id = 'memo-legacy-1'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert!(todo_id.starts_with("todo-legacy-"));
-    let lifecycles: i64 = conn
-        .query_row(
-            "SELECT COUNT(*) FROM memo_lifecycles WHERE memo_id = 'memo-legacy-1'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert_eq!(lifecycles, 1);
-    // The revision row survives: its lifecycle FK target was backfilled.
-    let revisions: i64 = conn
-        .query_row(
-            "SELECT COUNT(*) FROM memo_content_revisions WHERE memo_id = 'memo-legacy-1'",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert_eq!(revisions, 1);
-}
-
+/// Global index rows are deliberately not imported into the rebuilt notebook
+/// database. Markdown files remain the note source of truth.
 #[test]
 fn pending_data_migrations_skip_unavailable_notebooks() {
     let (mf, base) = fresh_memo_file();
@@ -478,7 +240,7 @@ fn relative_path_migration_recovers_populated_replacement_table() {
     mf.invalidate_caches();
     let recovered = mf.read_index().expect("half-migrated index should recover");
     assert_eq!(recovered.memos.len(), 1);
-    assert_eq!(recovered.memos[0].id, memo.id);
+    assert_eq!(recovered.memos[0].relative_path, memo.relative_path);
 
     let conn = rusqlite::Connection::open(&notebook_db).unwrap();
     let replacement_exists: i64 = conn
@@ -510,56 +272,6 @@ fn relative_path_migration_recovers_populated_replacement_table() {
     );
 }
 
-#[test]
-fn late_revision_observation_cannot_overwrite_a_newer_commit() {
-    let (store, root) = fresh_memo_file();
-    let other = MemoFile::new(root.join("config"));
-    let first = store
-        .commit_memo_content_revision("memo", "nb_test", "old", "first")
-        .unwrap();
-    let newer = other
-        .commit_memo_content_revision("memo", "nb_test", "new", "second")
-        .unwrap();
-    assert!(store
-        .commit_memo_content_revision_if_current(
-            "memo",
-            "nb_test",
-            "old",
-            "late",
-            Some(&first.state)
-        )
-        .unwrap()
-        .is_none());
-    assert_eq!(
-        store.read_memo_content_revision("memo").unwrap(),
-        Some(newer.state)
-    );
-}
-
-#[test]
-fn missing_revision_observation_cannot_replace_a_first_commit() {
-    let (store, _) = fresh_memo_file();
-    let first = store
-        .commit_memo_content_revision_if_current("memo", "nb_test", "first", "first", None)
-        .unwrap()
-        .unwrap();
-    assert!(store
-        .commit_memo_content_revision_if_current("memo", "nb_test", "stale", "late", None)
-        .unwrap()
-        .is_none());
-    let next = store
-        .commit_memo_content_revision_if_current(
-            "memo",
-            "nb_test",
-            "next",
-            "next",
-            Some(&first.state),
-        )
-        .unwrap()
-        .unwrap();
-    assert_eq!(next.state.revision, first.state.revision + 1);
-}
-
 #[test]
 fn read_memos_for_notebook_id_does_not_switch_current_notebook() {
     let (mut mf, tmp) = fresh_memo_file();
@@ -591,9 +303,9 @@ fn read_memos_for_notebook_id_does_not_switch_current_notebook() {
 
     assert_eq!(mf.current_notebook_id_value().as_deref(), Some("nb_test"));
     assert_eq!(other_memos.len(), 1);
-    assert_eq!(other_memos[0].id, other_memo.id);
+    assert_eq!(other_memos[0].relative_path, other_memo.relative_path);
     assert_eq!(current_memos.len(), 1);
-    assert_eq!(current_memos[0].id, current_memo.id);
+    assert_eq!(current_memos[0].relative_path, current_memo.relative_path);
 }
 
 #[test]
@@ -628,18 +340,18 @@ fn register_existing_file_for_other_notebook_does_not_switch_current_notebook()
 
     let other_memos = mf.read_all_memos_for_notebook_id(Some("nb_other"));
     assert_eq!(other_memos.len(), 1);
-    assert_eq!(other_memos[0].id, registered.id);
+    assert_eq!(other_memos[0].relative_path, registered.relative_path);
     assert_eq!(other_memos[0].filename, "External Agent Note.md");
 
     let current_memos = mf.read_all_memos_for_notebook_id(Some("nb_test"));
     assert_eq!(current_memos.len(), 1);
-    assert_eq!(current_memos[0].id, current_memo.id);
+    assert_eq!(current_memos[0].relative_path, current_memo.relative_path);
 
     let conn = rusqlite::Connection::open(mf.notebook_db_path("nb_other").unwrap()).unwrap();
     let notebook_id: String = conn
         .query_row(
-            "SELECT notebook_id FROM memos WHERE id = ?1",
-            rusqlite::params![registered.id],
+            "SELECT notebook_id FROM memos WHERE relative_path = ?1",
+            rusqlite::params![registered.relative_path],
             |row| row.get(0),
         )
         .unwrap();
@@ -675,16 +387,15 @@ fn importing_a_copy_with_a_cross_notebook_key_rekeys_the_file() {
         .register_existing_file_for_notebook_id("nb_other", &imported_path)
         .unwrap();
 
-    assert_ne!(imported.id, original.id);
-    assert_eq!(
-        crate::memo_file::extract_frontmatter_key(&fs::read_to_string(&imported_path).unwrap()),
-        None
-    );
+    assert_ne!(imported.relative_path, original.relative_path);
+    assert!(!fs::read_to_string(&imported_path)
+        .unwrap()
+        .contains("flowix_key:"));
     assert!(mf
-        .read_memo_for_notebook_id("nb_test", &original.id)
+        .read_memo_for_notebook_id("nb_test", &original.relative_path)
         .is_some());
     assert!(mf
-        .read_memo_for_notebook_id("nb_other", &imported.id)
+        .read_memo_for_notebook_id("nb_other", &imported.relative_path)
         .is_some());
 }
 
@@ -709,18 +420,15 @@ fn startup_reconcile_treats_a_copy_as_new_memo_when_original_still_exists() {
     let copied = mf
         .find_memo_by_relative_path("Copied from original.md")
         .unwrap();
-    assert_ne!(copied.id, original.id);
-    assert_eq!(
-        crate::memo_file::extract_frontmatter_key(
-            &fs::read_to_string(base.join("Copied from original.md")).unwrap()
-        ),
-        None
-    );
+    assert_ne!(copied.relative_path, original.relative_path);
+    assert!(!fs::read_to_string(base.join("Copied from original.md"))
+        .unwrap()
+        .contains("flowix_key:"));
     assert!(base.join(&original.filename).exists());
 }
 
 #[test]
-fn read_memo_by_id_resolves_global_notebook_location() {
+fn read_memo_for_explicit_notebook_resolves_notebook_location() {
     let (mut mf, tmp) = fresh_memo_file();
     let current_memo = mf.create_memo("Current", "# Current", None).unwrap();
 
@@ -745,26 +453,22 @@ fn read_memo_by_id_resolves_global_notebook_location() {
     mf.set_current_notebook(Some("nb_test".to_string()));
 
     assert!(
-        mf.read_memo(&other_memo.id).is_none(),
+        mf.read_memo(&other_memo.relative_path).is_none(),
         "current-local read should not find other notebook memo"
     );
     let resolved = mf
-        .read_memo_global(&other_memo.id)
-        .expect("global memo found");
-    let path = mf
-        .find_memo_file_path(&other_memo.id)
-        .expect("global path found");
-    let (_entry, body) = mf
-        .read_memo_with_body_global(&other_memo.id)
-        .expect("global body found");
+        .read_memo_for_notebook_id("nb_other", &other_memo.relative_path)
+        .expect("memo found in the requested notebook");
+    let path = other_dir.join(&other_memo.filename);
+    let body = fs::read_to_string(&path).expect("memo body found");
 
     assert_eq!(mf.current_notebook_id_value().as_deref(), Some("nb_test"));
-    assert_eq!(resolved.id, other_memo.id);
+    assert_eq!(resolved.relative_path, other_memo.relative_path);
     assert_eq!(path, other_dir.join(&other_memo.filename));
     assert!(body.contains("# Other"));
     assert_eq!(
-        mf.read_all_memos_filtered("all", "createdAt", None)[0].id,
-        current_memo.id
+        mf.read_all_memos_filtered("all", "createdAt", None)[0].relative_path,
+        current_memo.relative_path
     );
 }
 
@@ -794,7 +498,7 @@ fn write_memo_by_id_updates_global_notebook_without_switching_current() {
     mf.set_current_notebook(Some("nb_test".to_string()));
 
     let updated = mf
-        .write_memo_renaming_on_title_change_global(&other_memo.id, "Renamed Other\nBody")
+        .write_memo_renaming_on_title_change_global(&other_memo.relative_path, "Renamed Other\nBody")
         .expect("global write ok");
     let other_list = mf
         .read_index_for_notebook_id(Some("nb_other"))
@@ -804,12 +508,12 @@ fn write_memo_by_id_updates_global_notebook_without_switching_current() {
     let final_content = fs::read_to_string(other_dir.join(&updated.filename)).unwrap();
 
     assert_eq!(mf.current_notebook_id_value().as_deref(), Some("nb_test"));
-    assert_eq!(updated.id, other_memo.id);
+    assert_eq!(updated.relative_path, other_memo.relative_path);
     assert_eq!(updated.filename, "Renamed Other.md");
     assert!(final_content.contains("Renamed Other"));
-    assert!(other_list.memos.iter().any(|memo| memo.id == other_memo.id));
+    assert!(other_list.memos.iter().any(|memo| memo.relative_path == other_memo.relative_path));
     assert_eq!(current_list.memos.len(), 1);
-    assert_eq!(current_list.memos[0].id, current_memo.id);
+    assert_eq!(current_list.memos[0].relative_path, current_memo.relative_path);
 }
 
 #[test]
@@ -842,7 +546,7 @@ fn write_memo_global_ignores_generated_conflict_suffix() {
     mf.set_current_notebook(Some("nb_test".to_string()));
 
     let updated = mf
-        .write_memo_renaming_on_title_change_global(&memo.id, "Stable\nnew body\n")
+        .write_memo_renaming_on_title_change_global(&memo.relative_path, "Stable\nnew body\n")
         .expect("global write ok");
 
     assert_eq!(updated.filename, "Stable-1.md");
@@ -878,7 +582,7 @@ fn pasted_file_with_key_from_other_notebook_gets_new_id_in_current_notebook() {
     let pasted_path = tmp.join("Copied.md");
     fs::write(
         &pasted_path,
-        format!("---\nflowix_key: {}\n---\n# Copied\n", other_memo.id),
+        format!("---\nflowix_key: {}\n---\n# Copied\n", other_memo.relative_path),
     )
     .unwrap();
     let copied = mf
@@ -886,14 +590,11 @@ fn pasted_file_with_key_from_other_notebook_gets_new_id_in_current_notebook() {
         .expect("register copied file");
     let copied_content = fs::read_to_string(&pasted_path).unwrap();
 
-    assert_ne!(copied.id, other_memo.id);
+    assert_ne!(copied.relative_path, other_memo.relative_path);
     assert_eq!(copied.filename, "Copied.md");
-    assert!(mf.read_memo(&other_memo.id).is_none());
-    assert!(mf.read_memo_global(&other_memo.id).is_some());
-    assert_eq!(
-        super::frontmatter::extract_frontmatter_key(&copied_content),
-        Some(other_memo.id)
-    );
+    assert!(mf.read_memo(&other_memo.relative_path).is_none());
+    assert!(mf.read_memo_for_notebook_id("nb_other", &other_memo.relative_path).is_some());
+    assert!(copied_content.contains(&format!("flowix_key: {}", other_memo.relative_path)));
 }
 
 // =====================================================================
@@ -965,10 +666,10 @@ fn create_memo_writes_file_and_entry() {
     assert!(path.exists(), "file should exist at {}", path.display());
     // entry 跟磁盘文件名一致, 含 .md
     assert_eq!(memo.filename, "Hello.md");
-    assert!(!memo.id.is_empty());
-    assert_eq!(memo.id.len(), super::MEMO_ID_LENGTH);
+    assert!(!memo.relative_path.is_empty());
+    assert_eq!(memo.relative_path, memo.relative_path);
     // memo index 已注册
-    let queried = mf.read_memo(&memo.id).expect("memo in list");
+    let queried = mf.read_memo(&memo.relative_path).expect("memo in list");
     assert_eq!(queried.filename, "Hello.md");
     // preview = 派生第二行 body, 单行 body 时为空
 }
@@ -994,11 +695,10 @@ fn create_memo_preserves_authored_frontmatter_without_identity() {
         1,
         "content must have one closing frontmatter fence: {content}"
     );
-    assert_eq!(super::frontmatter::extract_frontmatter_key(&content), None);
 }
 
 #[test]
-fn template_note_with_existing_flowix_key_creates_after_prior_nested_notes() {
+fn template_notes_with_historical_flowix_keys_are_addressed_by_path() {
     let (mf, base) = fresh_memo_file();
     let people_dir = base.join("人物/主要人物");
     fs::create_dir_all(&people_dir).unwrap();
@@ -1047,9 +747,9 @@ fn template_note_with_existing_flowix_key_creates_after_prior_nested_notes() {
         .expect("create next template note");
     let content = fs::read_to_string(base.join(&memo.relative_path)).unwrap();
 
-    assert_ne!(memo.id, template_key);
+    assert_eq!(memo.relative_path, memo.relative_path);
     assert_eq!(memo.relative_path, "人物/当前人物状态.md");
-    assert_eq!(super::frontmatter::extract_frontmatter_key(&content), Some(template_key.to_string()));
+    assert!(content.contains(&format!("flowix_key: {template_key}")));
 }
 
 #[test]
@@ -1059,26 +759,26 @@ fn read_index_backfills_missing_properties_from_frontmatter() {
         .create_memo("Backfill", "---\nstatus: review\n---\n# Backfill\n", None)
         .expect("create ok");
 
-    // Legacy memo rows live in the per-notebook notebook.db.
+    // Path-keyed memo rows live in the per-notebook notebook.db.
     let notebook_db = mf.notebook_db_path("nb_test").unwrap();
     {
         let conn = rusqlite::Connection::open(&notebook_db).unwrap();
         conn.execute(
-            "UPDATE memos SET properties = '{}' WHERE id = ?1",
-            rusqlite::params![memo.id],
+            "UPDATE memos SET properties = '{}' WHERE relative_path = ?1",
+            rusqlite::params![memo.relative_path],
         )
         .unwrap();
     }
     mf.invalidate_caches();
 
-    let from_index = mf.read_memo(&memo.id).expect("memo in index");
+    let from_index = mf.read_memo(&memo.relative_path).expect("memo in index");
     assert_eq!(from_index.properties["status"], "review");
 
     let conn = rusqlite::Connection::open(&notebook_db).unwrap();
     let properties: String = conn
         .query_row(
-            "SELECT properties FROM memos WHERE id = ?1",
-            rusqlite::params![memo.id],
+            "SELECT properties FROM memos WHERE relative_path = ?1",
+            rusqlite::params![memo.relative_path],
             |row| row.get(0),
         )
         .unwrap();
@@ -1093,7 +793,7 @@ fn create_memo_handles_title_conflict() {
     let b = mf.create_memo("Hello", "y", None).unwrap();
     assert_eq!(a.filename, "Hello.md");
     assert_eq!(b.filename, "Hello-1.md");
-    assert_ne!(a.id, b.id);
+    assert_ne!(a.relative_path, b.relative_path);
     assert!(base.join("Hello.md").exists());
     assert!(base.join("Hello-1.md").exists());
 }
@@ -1122,7 +822,7 @@ fn occupied_names_and_cache_follow_only_the_target_directory() {
         .read_index_for_notebook_id(Some("nb_test"))
         .unwrap()
         .unwrap();
-    assert!(index.memos.iter().any(|entry| entry.id == conflict.id));
+    assert!(index.memos.iter().any(|entry| entry.relative_path == conflict.relative_path));
 }
 
 #[test]
@@ -1133,11 +833,11 @@ fn delayed_remove_cannot_unregister_a_path_that_reappeared() {
 
     // A queued Remove may be delivered after a template writes this path.
     assert!(!mf.unregister_memo_by_path_for_notebook_id("nb_test", &path));
-    assert!(mf.read_memo_for_notebook_id("nb_test", &memo.id).is_some());
+    assert!(mf.read_memo_for_notebook_id("nb_test", &memo.relative_path).is_some());
 
     fs::remove_file(&path).unwrap();
     assert!(mf.unregister_memo_by_path_for_notebook_id("nb_test", &path));
-    assert!(mf.read_memo_for_notebook_id("nb_test", &memo.id).is_none());
+    assert!(mf.read_memo_for_notebook_id("nb_test", &memo.relative_path).is_none());
 }
 
 #[test]
@@ -1191,11 +891,11 @@ fn rename_memo_renames_file_and_updates_list() {
     let memo = mf.create_memo("Old", "body", None).unwrap();
     assert!(base.join("Old.md").exists());
 
-    let updated = mf.rename_memo(&memo.id, "New").expect("rename ok");
+    let updated = mf.rename_memo(&memo.relative_path, "New").expect("rename ok");
     assert_eq!(updated.filename, "New.md");
     assert!(!base.join("Old.md").exists(), "old file should be gone");
     assert!(base.join("New.md").exists());
-    let queried = mf.read_memo(&memo.id).expect("still in list");
+    let queried = mf.read_memo(&memo.relative_path).expect("still in list");
     assert_eq!(queried.filename, "New.md");
 }
 
@@ -1207,7 +907,7 @@ fn rename_memo_preserves_nested_directory() {
     fs::write(nested.join("Old.md"), "# Old\n").unwrap();
     let memo = mf.register_existing_file(&nested.join("Old.md")).unwrap();
 
-    let updated = mf.rename_memo(&memo.id, "New").unwrap();
+    let updated = mf.rename_memo(&memo.relative_path, "New").unwrap();
     assert_eq!(updated.relative_path, "projects/backend/New.md");
     assert!(!nested.join("Old.md").exists());
     assert!(nested.join("New.md").exists());
@@ -1219,18 +919,17 @@ fn rename_memo_handles_conflict() {
     let a = mf.create_memo("First", "a", None).unwrap();
     let _b = mf.create_memo("Second", "b", None).unwrap();
     // 把 a 改名为 "Second" → 冲突 → 用 Second-1.md
-    let updated = mf.rename_memo(&a.id, "Second").unwrap();
+    let updated = mf.rename_memo(&a.relative_path, "Second").unwrap();
     assert_eq!(updated.filename, "Second-1.md");
     assert!(base.join("Second-1.md").exists());
 }
 
 #[test]
-fn rename_memo_renames_disk_file_and_keeps_key_in_frontmatter() {
-    // 新 frontmatter 语义: rename 只改磁盘文件名 + memo index.filename,
-    // frontmatter 块内 `key` 保持与 memo index id 一致, 不再有 `filename` 字段。
+fn rename_memo_does_not_inject_identity_metadata() {
+    // Renaming changes the path projection and disk filename, not authored YAML.
     let (mf, _base) = fresh_memo_file();
     let memo = mf.create_memo("First", "body\n", None).unwrap();
-    let _ = mf.rename_memo(&memo.id, "Second").unwrap();
+    let _ = mf.rename_memo(&memo.relative_path, "Second").unwrap();
     let content = fs::read_to_string(_base.join("Second.md")).unwrap();
     assert!(!content.contains("flowix_key:"));
     assert!(
@@ -1243,7 +942,7 @@ fn rename_memo_renames_disk_file_and_keeps_key_in_frontmatter() {
 fn rename_memo_unchanged_title_is_noop() {
     let (mf, base) = fresh_memo_file();
     let memo = mf.create_memo("Same", "body", None).unwrap();
-    let updated = mf.rename_memo(&memo.id, "Same").unwrap();
+    let updated = mf.rename_memo(&memo.relative_path, "Same").unwrap();
     assert_eq!(updated.filename, "Same.md");
     assert!(base.join("Same.md").exists());
 }
@@ -1263,7 +962,7 @@ fn rename_memo_not_found_returns_io_error() {
 fn write_memo_updates_body_and_keeps_filename() {
     let (mf, base) = fresh_memo_file();
     let memo = mf.create_memo("Title", "old\n", None).unwrap();
-    let updated = mf.write_memo(&memo.id, "new\n").expect("write ok");
+    let updated = mf.write_memo(&memo.relative_path, "new\n").expect("write ok");
     assert_eq!(updated.filename, "Title.md");
     // single-line body → preview empty
     let content = fs::read_to_string(base.join("Title.md")).unwrap();
@@ -1275,7 +974,7 @@ fn write_memo_updates_body_and_keeps_filename() {
 fn write_memo_does_not_inject_identity() {
     let (mf, base) = fresh_memo_file();
     let memo = mf.create_memo("Stable", "body\n", None).unwrap();
-    let _ = mf.write_memo(&memo.id, "more\n").unwrap();
+    let _ = mf.write_memo(&memo.relative_path, "more\n").unwrap();
     let content = fs::read_to_string(base.join("Stable.md")).unwrap();
     assert!(!content.contains("flowix_key:"));
     assert!(
@@ -1302,14 +1001,14 @@ fn write_rename_changes_disk_when_first_line_changes() {
     assert!(base.join("Old.md").exists());
 
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "Renamed\nbody line 2\n")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "Renamed\nbody line 2\n")
         .expect("write+rename ok");
 
     // 派生 title = 整行 "Renamed" (经 strip_markdown 清洗, 无装饰), filename = "Renamed.md"
     assert_eq!(updated.filename, "Renamed.md");
     assert!(!base.join("Old.md").exists(), "old file should be gone");
     assert!(base.join("Renamed.md").exists());
-    let queried = mf.read_memo(&memo.id).expect("still in list");
+    let queried = mf.read_memo(&memo.relative_path).expect("still in list");
     assert_eq!(queried.filename, "Renamed.md");
 }
 
@@ -1322,10 +1021,10 @@ fn write_rename_noop_when_first_line_unchanged() {
     // 首行仍是 "Stable" (加新行不影响派生 title)
     let new_body = "Stable\nnew line 2\nnew line 3\n";
     let _ = mf
-        .write_memo_renaming_on_title_change(&memo.id, new_body)
+        .write_memo_renaming_on_title_change(&memo.relative_path, new_body)
         .expect("write ok");
     assert!(base.join("Stable.md").exists());
-    let queried = mf.read_memo(&memo.id).expect("still in list");
+    let queried = mf.read_memo(&memo.relative_path).expect("still in list");
     assert_eq!(queried.filename, "Stable.md");
 }
 
@@ -1341,7 +1040,7 @@ fn write_rename_ignores_generated_conflict_suffix_when_title_is_base() {
     assert_eq!(memo.filename, "Stable-1.md");
 
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "Stable\nnew body\n")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "Stable\nnew body\n")
         .expect("write ok");
 
     assert_eq!(updated.filename, "Stable-1.md");
@@ -1357,7 +1056,7 @@ fn write_rename_treats_suffix_in_new_title_as_a_title_change() {
         .unwrap();
 
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "Stable-1\nnew body\n")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "Stable-1\nnew body\n")
         .expect("write+rename ok");
 
     assert_eq!(updated.filename, "Stable-1.md");
@@ -1377,7 +1076,7 @@ fn write_rename_changes_generated_suffix_when_title_changes() {
     assert_eq!(memo.filename, "Stable-1.md");
 
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "Stable-2\nnew body\n")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "Stable-2\nnew body\n")
         .expect("write+rename ok");
 
     assert_eq!(updated.filename, "Stable-2.md");
@@ -1397,7 +1096,7 @@ fn write_rename_keeps_filename_when_title_includes_same_suffix() {
     assert_eq!(memo.filename, "Stable-1.md");
 
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "Stable-1\nnew body\n")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "Stable-1\nnew body\n")
         .expect("write ok");
 
     assert_eq!(updated.filename, "Stable-1.md");
@@ -1414,7 +1113,7 @@ fn write_rename_handles_conflict_with_dash_suffix() {
     let b = mf.create_memo("Second", "b\n", None).unwrap();
     // 把 b 的首行改成 "First" → 跟 a 冲突 → 走 First-1.md
     let updated = mf
-        .write_memo_renaming_on_title_change(&b.id, "First\nnew body\n")
+        .write_memo_renaming_on_title_change(&b.relative_path, "First\nnew body\n")
         .expect("write+rename ok");
     assert_eq!(updated.filename, "First-1.md");
     assert!(base.join("First-1.md").exists());
@@ -1427,7 +1126,7 @@ fn write_rename_does_not_inject_identity() {
     let (mf, base) = fresh_memo_file();
     let memo = mf.create_memo("Start", "Start\n", None).unwrap();
     let _ = mf
-        .write_memo_renaming_on_title_change(&memo.id, "End\nnew body\n")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "End\nnew body\n")
         .expect("write+rename ok");
     let content = fs::read_to_string(base.join("End.md")).unwrap();
     assert!(!content.contains("flowix_key:"));
@@ -1439,13 +1138,13 @@ fn write_rename_empty_body_uses_untitled_memo() {
     let (mf, base) = fresh_memo_file();
     let memo = mf.create_memo("Keep", "body\n", None).unwrap();
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "")
         .expect("write ok");
 
     assert_eq!(updated.filename, "Untitled Memo.md");
     assert!(!base.join("Keep.md").exists());
     assert!(base.join("Untitled Memo.md").exists());
-    let queried = mf.read_memo(&memo.id).expect("still in list");
+    let queried = mf.read_memo(&memo.relative_path).expect("still in list");
     assert_eq!(queried.filename, "Untitled Memo.md");
     assert_eq!(queried.preview, "");
 }
@@ -1456,7 +1155,7 @@ fn write_rename_empty_body_uses_untitled_memo_dash_suffix_on_conflict() {
     let _existing = mf.create_memo("Untitled Memo", "existing\n", None).unwrap();
     let memo = mf.create_memo("Keep", "body\n", None).unwrap();
     let updated = mf
-        .write_memo_renaming_on_title_change(&memo.id, "")
+        .write_memo_renaming_on_title_change(&memo.relative_path, "")
         .expect("write ok");
 
     assert_eq!(updated.filename, "Untitled Memo-1.md");
@@ -1474,10 +1173,10 @@ fn delete_memo_removes_file_and_index_entry() {
     let memo = mf.create_memo("Del", "x", None).unwrap();
     assert!(base.join("Del.md").exists());
 
-    let removed = mf.delete_memo(&memo.id);
+    let removed = mf.delete_memo(&memo.relative_path);
     assert!(removed);
     assert!(!base.join("Del.md").exists());
-    assert!(mf.read_memo(&memo.id).is_none());
+    assert!(mf.read_memo(&memo.relative_path).is_none());
 }
 
 #[test]
@@ -1486,9 +1185,9 @@ fn delete_memo_handles_orphan_index_entry() {
     let memo = mf.create_memo("Orphan", "x", None).unwrap();
     // 模拟外部 rm: 物理文件先没
     fs::remove_file(base.join("Orphan.md")).unwrap();
-    let removed = mf.delete_memo(&memo.id);
+    let removed = mf.delete_memo(&memo.relative_path);
     assert!(removed, "should clear memo index orphan entry");
-    assert!(mf.read_memo(&memo.id).is_none());
+    assert!(mf.read_memo(&memo.relative_path).is_none());
 }
 
 #[test]
@@ -1520,11 +1219,11 @@ fn scoped_delete_does_not_remove_same_id_from_another_notebook() {
     let other_path = other_dir.join(&other_memo.filename);
 
     assert!(!mf
-        .delete_memo_result_for_notebook_id("nb_test", &other_memo.id)
+        .delete_memo_result_for_notebook_id("nb_test", &other_memo.relative_path)
         .unwrap());
     assert!(other_path.exists());
     assert!(mf
-        .read_memo_for_notebook_id("nb_other", &other_memo.id)
+        .read_memo_for_notebook_id("nb_other", &other_memo.relative_path)
         .is_some());
 }
 
@@ -1540,7 +1239,7 @@ fn registration_never_rewrites_markdown() {
 
     let memo = mf.register_existing_file(&abs).expect("register ok");
     assert_eq!(memo.filename, "PreExisting.md");
-    assert!(!memo.id.is_empty());
+    assert!(!memo.relative_path.is_empty());
     let content = fs::read_to_string(&abs).unwrap();
     assert!(!content.contains("flowix_key:"));
     assert!(
@@ -1548,7 +1247,7 @@ fn registration_never_rewrites_markdown() {
         "original body must be preserved: {content}"
     );
     let queried = mf.find_memo_by_filename("PreExisting.md").expect("in list");
-    assert_eq!(queried.id, memo.id);
+    assert_eq!(queried.relative_path, memo.relative_path);
 }
 
 #[test]
@@ -1577,7 +1276,7 @@ fn register_existing_file_reload_when_already_in_list() {
     // 改盘 + 再次 register → 应走 reload, 不重复 push
     fs::write(&abs, "# title\nv2 body\n").unwrap();
     let memo2 = mf.register_existing_file(&abs).unwrap();
-    assert_eq!(memo1.id, memo2.id);
+    assert_eq!(memo1.relative_path, memo2.relative_path);
     let list = mf.read_index().expect("list");
     assert_eq!(list.memos.len(), 1);
     assert_eq!(memo2.preview, "v2 body"); // 第二行=
@@ -1696,7 +1395,7 @@ fn unobserved_directory_move_rebuilds_paths_without_guessing_identity() {
     let ids = mf
         .read_all_memos()
         .into_iter()
-        .map(|memo| (memo.filename, memo.id))
+        .map(|memo| (memo.filename, memo.relative_path))
         .collect::<std::collections::HashMap<_, _>>();
 
     fs::rename(base.join("docs/guide"), base.join("docs/manual")).unwrap();
@@ -1707,7 +1406,7 @@ fn unobserved_directory_move_rebuilds_paths_without_guessing_identity() {
     assert_eq!(report.removed, 2);
     for memo in mf.read_all_memos() {
         assert!(memo.relative_path.starts_with("docs/manual/"));
-        assert_ne!(ids.get(&memo.filename), Some(&memo.id));
+        assert_ne!(ids.get(&memo.filename), Some(&memo.relative_path));
     }
 }
 
@@ -1739,7 +1438,7 @@ fn reconcile_bidirectional_adds_orphans_and_removes_ghosts() {
     fs::remove_file(&ghost_path).unwrap();
     assert!(!ghost_path.exists(), "外部 rm 删了物理文件");
     // memo index 仍残留 ghost entry
-    assert!(mf.read_memo(&ghost.id).is_some());
+    assert!(mf.read_memo(&ghost.relative_path).is_some());
 
     // 准备: 在盘上建 NewOnDisk.md, 不通过 API 注册 (模拟外部 drop)
     fs::write(base.join("NewOnDisk.md"), "fresh content").unwrap();
@@ -1754,7 +1453,7 @@ fn reconcile_bidirectional_adds_orphans_and_removes_ghosts() {
     assert_eq!(report.removed, 1, "应清 Ghost.md 幽灵条目");
 
     // memo index: Ghost entry 已清, NewOnDisk 已注册
-    assert!(mf.read_memo(&ghost.id).is_none(), "ghost entry 应被清");
+    assert!(mf.read_memo(&ghost.relative_path).is_none(), "ghost entry 应被清");
     assert!(
         mf.find_memo_by_filename("NewOnDisk.md").is_some(),
         "新文件应被注册"
@@ -1779,7 +1478,7 @@ fn reconcile_bidirectional_is_idempotent() {
     let second = mf.reconcile_with_disk_bidirectional().unwrap();
     assert_eq!(second.added, 0);
     assert_eq!(second.removed, 0);
-    assert!(mf.read_memo(&ghost.id).is_none());
+    assert!(mf.read_memo(&ghost.relative_path).is_none());
 }
 
 #[test]
@@ -1807,7 +1506,7 @@ fn unobserved_move_is_delete_and_create() {
     let old_path = base.join("Original.md");
     fs::write(&old_path, "# Hello\nbody\n").unwrap();
     let initial = mf.register_existing_file(&old_path).expect("register");
-    let original_id = initial.id.clone();
+    let original_relative_path = initial.relative_path.clone();
     assert_eq!(initial.filename, "Original.md");
     let new_path = base.join("Renamed.md");
     fs::rename(&old_path, &new_path).unwrap();
@@ -1817,7 +1516,7 @@ fn unobserved_move_is_delete_and_create() {
     let list = mf.read_index().expect("list");
     assert_eq!(list.memos.len(), 1, "exactly one entry");
     assert_ne!(
-        list.memos[0].id, original_id,
+        list.memos[0].relative_path, original_relative_path,
         "unobserved move gets a new cache association"
     );
     assert_eq!(list.memos[0].filename, "Renamed.md", "filename updated");
@@ -1864,13 +1563,10 @@ fn reconcile_bidirectional_as_new_rekeys_existing_markdown() {
 
     assert_eq!(report.added, 1);
     let imported = mf.find_memo_by_filename("Imported.md").unwrap();
-    assert_ne!(imported.id, original.id);
+    assert_ne!(imported.relative_path, original.relative_path);
 
     let imported_content = fs::read_to_string(imported_path).unwrap();
-    assert_eq!(
-        super::frontmatter::extract_frontmatter_key(&imported_content),
-        None
-    );
+    assert!(!imported_content.contains("flowix_key:"));
 }
 
 #[test]
@@ -1881,7 +1577,7 @@ fn unregister_clears_ghost_entry_when_file_gone() {
     let memo = mf.create_memo("Ghost", "x", None).unwrap();
     fs::remove_file(base.join("Ghost.md")).unwrap();
     assert!(
-        mf.read_memo(&memo.id).is_some(),
+        mf.read_memo(&memo.relative_path).is_some(),
         "memo index 仍有 ghost entry"
     );
 
@@ -1889,7 +1585,7 @@ fn unregister_clears_ghost_entry_when_file_gone() {
     let abs = base.join("Ghost.md");
     let removed = mf.unregister_memo_by_path(&abs);
     assert!(removed);
-    assert!(mf.read_memo(&memo.id).is_none(), "ghost entry 已清");
+    assert!(mf.read_memo(&memo.relative_path).is_none(), "ghost entry 已清");
 }
 
 #[test]
@@ -1902,7 +1598,7 @@ fn unregister_refuses_when_filename_differs() {
     let bogus_abs = base.join("Bogus.md");
     let removed = mf.unregister_memo_by_path(&bogus_abs);
     assert!(!removed, "filename 不匹配应拒绝");
-    assert!(mf.read_memo(&memo.id).is_some(), "entry 仍保留");
+    assert!(mf.read_memo(&memo.relative_path).is_some(), "entry 仍保留");
 }
 
 // =====================================================================
@@ -1918,7 +1614,7 @@ fn reload_refreshes_preview_after_external_edit() {
         "---\nfilename: Reload\n---\n# title\nchanged body\n",
     )
     .unwrap();
-    let updated = mf.reload_memo_from_disk(&memo.id).expect("reload ok");
+    let updated = mf.reload_memo_from_disk(&memo.relative_path).expect("reload ok");
     assert_eq!(updated.filename, "Reload.md");
     assert!(updated.preview.contains("changed"));
 }
@@ -1934,7 +1630,7 @@ fn unregister_by_path_removes_index_entry() {
     let abs = base.join("Del.md");
     let removed = mf.unregister_memo_by_path(&abs);
     assert!(removed);
-    assert!(mf.read_memo(&memo.id).is_none());
+    assert!(mf.read_memo(&memo.relative_path).is_none());
 }
 
 #[test]
@@ -1955,13 +1651,13 @@ fn sync_metadata_only_persists_markdown_and_rebuilds_index() {
     let memo = mf.create_memo("Meta", "body\n", None).unwrap();
     let mut updated = memo.clone();
     updated.favorited = true;
-    updated.colors = vec![super::types::MemoColor::Red];
+    updated.colors = vec![super::types::NoteColor::Red];
     mf.sync_metadata_only(&updated).expect("sync ok");
 
     // memo index 字段已更新
-    let queried = mf.read_memo(&memo.id).unwrap();
+    let queried = mf.read_memo(&memo.relative_path).unwrap();
     assert!(queried.favorited);
-    assert_eq!(queried.colors, vec![super::types::MemoColor::Red]);
+    assert_eq!(queried.colors, vec![super::types::NoteColor::Red]);
     // Markdown is the source of truth for user-visible metadata.
     let after = fs::read_to_string(base.join("Meta.md")).unwrap();
     assert!(after.contains("flowix_favorited: true"));
@@ -1971,7 +1667,7 @@ fn sync_metadata_only_persists_markdown_and_rebuilds_index() {
     assert!(mf.unregister_memo_by_path(&path));
     let rebuilt = mf.register_existing_file(&path).unwrap();
     assert!(rebuilt.favorited);
-    assert_eq!(rebuilt.colors, vec![super::types::MemoColor::Red]);
+    assert_eq!(rebuilt.colors, vec![super::types::NoteColor::Red]);
 }
 
 // =====================================================================
@@ -2000,11 +1696,10 @@ fn index_filename_is_disk_filename_with_md_suffix() {
 }
 
 #[test]
-fn memo_struct_has_no_path_field() {
-    // 编译期保证: types::Memo 不应有 path 字段。本测试若通过, 表明 schema 正确。
+fn memo_struct_uses_relative_path_as_its_address() {
     let memo: super::types::Memo = serde_json::from_value(serde_json::json!({
-        "id": "abc",
         "filename": "X.md",
+        "relativePath": "X.md",
         "preview": "",
         "tags": [],
         "todos": [],
@@ -2016,6 +1711,7 @@ fn memo_struct_has_no_path_field() {
     }))
     .unwrap();
     assert_eq!(memo.filename, "X.md");
+    assert_eq!(memo.relative_path, "X.md");
 }
 
 // =====================================================================
@@ -2031,8 +1727,8 @@ fn read_all_memos_returns_list_entries_sorted_by_created_desc() {
     let memos = mf.read_all_memos();
     assert_eq!(memos.len(), 2);
     // 后建的排前
-    assert_eq!(memos[0].id, b.id);
-    assert_eq!(memos[1].id, a.id);
+    assert_eq!(memos[0].relative_path, b.relative_path);
+    assert_eq!(memos[1].relative_path, a.relative_path);
 }
 
 #[test]
@@ -2048,7 +1744,7 @@ fn read_all_memos_with_body_returns_bodies() {
 fn read_memo_with_body_returns_full_content() {
     let (mf, _base) = fresh_memo_file();
     let memo = mf.create_memo("Y", "body-of-y\n", None).unwrap();
-    let (entry, body) = mf.read_memo_with_body(&memo.id).unwrap();
+    let (entry, body) = mf.read_memo_with_body(&memo.relative_path).unwrap();
     assert_eq!(entry.filename, "Y.md");
     assert!(body.contains("body-of-y"));
 }
@@ -2057,7 +1753,7 @@ fn read_memo_with_body_returns_full_content() {
 fn find_memo_file_path_returns_disk_path() {
     let (mf, base) = fresh_memo_file();
     let memo = mf.create_memo("Find", "x", None).unwrap();
-    let p = mf.find_memo_file_path(&memo.id).expect("path found");
+    let p = mf.find_memo_file_path(&memo.relative_path).expect("path found");
     assert_eq!(p, base.join("Find.md"));
 }
 
@@ -2072,13 +1768,13 @@ fn read_all_memos_filtered_favorited() {
 
     let only_fav = mf.read_all_memos_filtered("favorited", "createdAt", None);
     assert_eq!(only_fav.len(), 1);
-    assert_eq!(only_fav[0].id, b.id);
+    assert_eq!(only_fav[0].relative_path, b.relative_path);
 
     let all = mf.read_all_memos_filtered("all", "createdAt", None);
     assert_eq!(all.len(), 2);
     // favorited 置顶
-    assert_eq!(all[0].id, b.id);
-    assert_eq!(all[1].id, a.id);
+    assert_eq!(all[0].relative_path, b.relative_path);
+    assert_eq!(all[1].relative_path, a.relative_path);
 }
 
 // 回归测试: 带标签筛选时 (filter == "tagged"), 置顶 memo 仍需靠前.
@@ -2103,15 +1799,15 @@ fn read_all_memos_filtered_tagged_pins_favorited() {
     let tagged = mf.read_all_memos_filtered("tagged", "createdAt", Some("t1"));
     assert_eq!(tagged.len(), 2);
     assert_eq!(
-        tagged[0].id, older.id,
+        tagged[0].relative_path, older.relative_path,
         "favorited tag 必须在 tagged 视图最前"
     );
-    assert_eq!(tagged[1].id, newer.id);
+    assert_eq!(tagged[1].relative_path, newer.relative_path);
 
     let tagged_by_updated = mf.read_all_memos_filtered("tagged", "updatedAt", Some("t1"));
     assert_eq!(tagged_by_updated.len(), 2);
-    assert_eq!(tagged_by_updated[0].id, older.id);
-    assert_eq!(tagged_by_updated[1].id, newer.id);
+    assert_eq!(tagged_by_updated[0].relative_path, older.relative_path);
+    assert_eq!(tagged_by_updated[1].relative_path, newer.relative_path);
 }
 
 // =====================================================================
@@ -2177,7 +1873,7 @@ fn no_duplicate_ids_after_concurrent_creates() {
         h.join().expect("join");
     }
     let list = mf.read().unwrap().read_index().expect("list");
-    let mut ids: Vec<String> = list.memos.iter().map(|e| e.id.clone()).collect();
+    let mut ids: Vec<String> = list.memos.iter().map(|e| e.relative_path.clone()).collect();
     ids.sort();
     ids.dedup();
     assert_eq!(ids.len(), N, "all ids unique");
@@ -2236,10 +1932,7 @@ fn independent_instances_create_without_lost_rows_or_file_overwrites() {
     assert_eq!(filenames.len(), PER_INSTANCE * 2);
     for memo in &list.memos {
         let content = fs::read_to_string(base.join(&memo.filename)).expect("memo file exists");
-        assert_eq!(
-            super::frontmatter::extract_frontmatter_key(&content).as_deref(),
-            None
-        );
+        assert!(!content.contains("flowix_key:"));
     }
 }
 
@@ -2260,7 +1953,7 @@ fn independent_instance_writes_are_visible_after_local_cache_was_populated() {
         .expect("peer create");
 
     let refreshed = first.read_index().expect("peer row visible");
-    assert!(refreshed.memos.iter().any(|memo| memo.id == created.id));
+    assert!(refreshed.memos.iter().any(|memo| memo.relative_path == created.relative_path));
 }
 
 // =====================================================================
@@ -2305,22 +1998,16 @@ fn _dummy_memo_list_file() -> MemoIndexFile {
 // =====================================================================
 
 #[test]
-fn rename_memo_file_updates_list_json_filename_preserves_id() {
-    // 场景: memo index 里有一条 entry { id, filename: "Hello.md" },
-    // 物理文件被外部 mv 成 "Hello-renamed.md"。rename_memo_file 应该:
-    // 1. 改 entry.filename → "Hello-renamed.md"
-    // 2. 保留 entry.id (register 时生成的)
-    // 3. 返回新的 Memo, 字段一致
+fn rename_memo_file_rekeys_entry_to_new_relative_path() {
     let (mf, _tmp) = fresh_memo_file();
 
-    // 先 register 一个文件。 register_existing_file 会自己生成 6 位 id 并注入
-    // frontmatter, 我们记下这个 id 用作断言。
+    // Register the file, then move it to a different relative path.
     let old_path = mf.get_memo_base().join("Hello.md");
     fs::write(&old_path, "# body content\n").unwrap();
     let initial = mf.register_existing_file(&old_path).expect("register ok");
-    let original_id = initial.id.clone();
+    let old_relative_path = initial.relative_path.clone();
     assert_eq!(initial.filename, "Hello.md");
-    assert!(!original_id.is_empty());
+    assert_eq!(initial.relative_path, "Hello.md");
 
     // 模拟物理 mv (外部工具 rename)
     let new_path = mf.get_memo_base().join("Hello-renamed.md");
@@ -2332,10 +2019,8 @@ fn rename_memo_file_updates_list_json_filename_preserves_id() {
     let updated = mf
         .rename_memo_file(&old_path, &new_path)
         .expect("rename_memo_file should succeed");
-    assert_eq!(
-        updated.id, original_id,
-        "id must be preserved across physical rename"
-    );
+    assert_eq!(updated.relative_path, "Hello-renamed.md");
+    assert_ne!(updated.relative_path, old_relative_path);
     assert_eq!(updated.filename, "Hello-renamed.md");
 
     // memo index 已经被同步: 旧 filename 不应再出现在 list 里
@@ -2343,17 +2028,17 @@ fn rename_memo_file_updates_list_json_filename_preserves_id() {
     let entry = list
         .memos
         .iter()
-        .find(|e| e.id == original_id)
-        .expect("entry still in list under original id");
+        .find(|e| e.relative_path == "Hello-renamed.md")
+        .expect("entry is indexed at the new path");
     assert_eq!(entry.filename, "Hello-renamed.md");
     assert!(
         list.memos.iter().all(|e| e.filename != "Hello.md"),
         "old filename must be gone from memo index"
     );
 
-    // 按 id 读 memo 仍能读到, filename 已是新值
-    let by_id = mf.read_memo(&original_id).expect("read by id");
-    assert_eq!(by_id.filename, "Hello-renamed.md");
+    assert!(list.memos.iter().all(|entry| entry.relative_path != old_relative_path));
+    let by_path = mf.read_memo("Hello-renamed.md").expect("read by path");
+    assert_eq!(by_path.filename, "Hello-renamed.md");
 }
 
 #[test]
@@ -2384,7 +2069,7 @@ fn rename_memo_file_rejects_when_new_filename_occupied() {
     fs::rename(&b, &b_tmp).unwrap();
     fs::rename(&a, &b).unwrap();
 
-    // rename_memo_file 应当拒绝: new filename "B.md" 已被另一条 entry (id=bbb) 占用
+    // rename_memo_file 应当拒绝: new path "B.md" 已被另一条 entry 占用
     let result = mf.rename_memo_file(&a, &b);
     assert!(
         result.is_err(),
@@ -2403,107 +2088,48 @@ fn rename_memo_file_rejects_when_new_filename_occupied() {
 // (例如重启后第一次 notify, 或 Windows 上没有稳定 inode)。processor
 // 走原 Create 分支, 调 `register_existing_file(new_path)`。
 //
-// 期望: memo index 里应该仍然是原来 id=abc123 的那条 entry, 仅仅
-// filename 字段从 "Hello.md" 变成 "Hello-renamed.md"。
-//
-// 实际 (用户报告 bug): memo index 出现 id=xyz789 的新 entry, 旧的
-// abc123 还在但 filename 还是 "Hello.md" (指向不存在的文件)。
+// 期望: 索引从旧相对路径迁到新相对路径，不残留指向不存在文件的旧行。
 
 #[test]
-fn explicit_path_rename_preserves_cache_association() {
+fn explicit_path_rename_rekeys_note_index() {
     let (mf, _tmp) = fresh_memo_file();
     let old_path = mf.get_memo_base().join("Hello.md");
     fs::write(&old_path, "# Hello\nworld\n").unwrap();
     let initial = mf.register_existing_file(&old_path).expect("register ok");
-    let original_id = initial.id.clone();
+    let old_relative_path = initial.relative_path.clone();
     assert_eq!(initial.filename, "Hello.md");
     let new_path = mf.get_memo_base().join("Hello-renamed.md");
     fs::rename(&old_path, &new_path).unwrap();
     let rereg = mf
         .rename_memo_file(&old_path, &new_path)
         .expect("explicit rename pair");
-    assert_eq!(
-        rereg.id, original_id,
-        "explicit rename must preserve the cache association"
-    );
+    assert_eq!(rereg.relative_path, "Hello-renamed.md");
+    assert_ne!(rereg.relative_path, old_relative_path);
     assert_eq!(rereg.filename, "Hello-renamed.md");
     let list = mf.read_index().expect("memo index");
-    let with_id = list.memos.iter().filter(|e| e.id == original_id).count();
-    assert_eq!(with_id, 1, "exactly one entry with original id");
-    let entry = list.memos.iter().find(|e| e.id == original_id).unwrap();
+    assert_eq!(list.memos.len(), 1);
+    let entry = list.memos.iter().find(|e| e.relative_path == rereg.relative_path).unwrap();
     assert_eq!(entry.filename, "Hello-renamed.md");
 }
 
-// =====================================================================
-// 端到端: 物理 rename 后磁盘 frontmatter 的 key 是否真的保持不变
-// =====================================================================
-#[test]
-fn physical_rename_does_not_change_frontmatter_key_on_disk() {
-    let (mf, _tmp) = fresh_memo_file();
-    // 1. register
-    let old_path = mf.get_memo_base().join("Hello.md");
-    fs::write(&old_path, "# Hello\nworld\n").unwrap();
-    let m = mf.register_existing_file(&old_path).expect("register");
-    let original_id = m.id.clone();
-    let key_after_register = read_key_from_disk(&old_path);
-    assert_eq!(
-        key_after_register.as_deref(),
-        None,
-        "after register, key on disk should match id"
-    );
-
-    // 2. physical rename
-    let new_path = mf.get_memo_base().join("Hello-renamed.md");
-    fs::rename(&old_path, &new_path).unwrap();
-    let key_after_rename = read_key_from_disk(&new_path);
-    assert_eq!(
-        key_after_rename.as_deref(),
-        None,
-        "after physical rename, key on disk should still be the original id"
-    );
-
-    // 3. what does rename_memo_file do to the disk?
-    mf.rename_memo_file(&old_path, &new_path).expect("rename");
-    let key_after_rename_memo_file = read_key_from_disk(&new_path);
-    eprintln!("original_id={:?}", original_id);
-    eprintln!(
-        "key on disk after rename_memo_file = {:?}",
-        key_after_rename_memo_file
-    );
-    // 这个断言**会失败**如果 rename_memo_file 把 disk key 改了
-    assert_eq!(
-        key_after_rename_memo_file.as_deref(),
-        None,
-        "rename_memo_file must NOT change frontmatter key on disk (it's id-bound)"
-    );
-}
-
-fn read_key_from_disk(path: &Path) -> Option<String> {
-    use super::frontmatter::extract_frontmatter_key;
-    let content = std::fs::read_to_string(path).ok()?;
-    extract_frontmatter_key(&content)
-}
-
 // =====================================================================
 // v2 inode-rename: 模拟 Remove(old) + Create(new) 事件序列 (不通过 notify)
-// 验证 memo index 的 entry 仍然只有 1 条, id 保留。
+// 验证 memo index 仅保留新相对路径的 entry。
 // =====================================================================
 #[test]
-fn rename_via_remove_create_pair_preserves_id() {
+fn rename_via_remove_create_pair_rekeys_relative_path() {
     // 这测的是 inode tracker 命中时 Remove 事件被拦截 + Create 走 rename 配对的
     // 协同行为, 但 MemoFile 层不直接持有 inode tracker, 测的是 memo index
     // 同步结果。 processor 层的 inode 检查是 desktop 端。
 
-    // 替代方案: 直接测 register_existing_file + unregister_memo_by_path 在
-    // inode 命中 (即 tracker 里有该 inode) 时的等价行为: 不 unregister,
-    // 让 register_existing_file 抽 frontmatter key 反查保留 id。
+    // 直接测物理 rename 事件配对后更新索引路径。
     let (mf, _tmp) = fresh_memo_file();
 
     // 1. 原始文件
     let old_path = mf.get_memo_base().join("Hello.md");
     fs::write(&old_path, "# Hello\nworld\n").unwrap();
     let initial = mf.register_existing_file(&old_path).expect("register ok");
-    let original_id = initial.id.clone();
+    let _old_relative_path = initial.relative_path.clone();
 
     // 2. 物理 rename
     let new_path = mf.get_memo_base().join("Hello-renamed.md");
@@ -2515,10 +2141,10 @@ fn rename_via_remove_create_pair_preserves_id() {
     mf.rename_memo_file(&old_path, &new_path)
         .expect("rename should succeed");
 
-    // 4. 关键断言: memo index 只有一条 entry, id 保留
+    // 4. 关键断言: memo index 只有一条 entry，键为新路径
     let list = mf.read_index().expect("list");
     assert_eq!(list.memos.len(), 1, "exactly one entry remains");
-    assert_eq!(list.memos[0].id, original_id, "id preserved");
+    assert_eq!(list.memos[0].relative_path, "Hello-renamed.md");
     assert_eq!(
         list.memos[0].filename, "Hello-renamed.md",
         "filename updated"
@@ -2526,12 +2152,12 @@ fn rename_via_remove_create_pair_preserves_id() {
 }
 
 #[test]
-fn unpaired_remove_create_cannot_resurrect_old_identity() {
+fn unpaired_remove_create_indexes_only_the_new_relative_path() {
     let (mf, _tmp) = fresh_memo_file();
     let old_path = mf.get_memo_base().join("Hello.md");
     fs::write(&old_path, "# Hello\nworld\n").unwrap();
     let initial = mf.register_existing_file(&old_path).expect("register ok");
-    let original_id = initial.id.clone();
+    let old_relative_path = initial.relative_path.clone();
 
     let new_path = mf.get_memo_base().join("Hello-renamed.md");
     fs::rename(&old_path, &new_path).unwrap();
@@ -2541,16 +2167,14 @@ fn unpaired_remove_create_cannot_resurrect_old_identity() {
     assert_eq!(list.memos.len(), 0, "list is empty after remove");
     let rereg = mf
         .register_existing_file(&new_path)
-        .expect("register should succeed via frontmatter key fallback");
-    assert_ne!(
-        rereg.id, original_id,
-        "unpaired events must not infer an old cache association"
-    );
+        .expect("register should recreate the path-keyed entry");
+    assert_eq!(rereg.relative_path, "Hello-renamed.md");
+    assert_ne!(rereg.relative_path, old_relative_path);
     assert_eq!(rereg.filename, "Hello-renamed.md");
 
     let list = mf.read_index().expect("list");
     assert_eq!(list.memos.len(), 1, "exactly one entry restored");
-    assert_eq!(list.memos[0].id, rereg.id);
+    assert_eq!(list.memos[0].relative_path, rereg.relative_path);
     assert_eq!(list.memos[0].filename, "Hello-renamed.md");
 }
 
@@ -2694,9 +2318,9 @@ fn index_cache_disk_and_memory_coherent_after_write() {
     let memo = mf.create_memo("Hello", "body1", None).unwrap();
 
     // write_memo 内部走 sync_index_on_write_locked → write_index (cache 同步)
-    let _ = mf.write_memo(&memo.id, "body2\n").expect("write ok");
+    let _ = mf.write_memo(&memo.relative_path, "body2\n").expect("write ok");
 
-    // cache 内容跟 index.db 一致
+    // cache 内容跟 local.db 一致
     let cached = mf.read_index().expect("cached list");
     mf.invalidate_caches();
     let from_db = mf.read_index().expect("db list");
@@ -2749,7 +2373,7 @@ fn notebook_configs_cache_survives_notebook_switch() {
     let _ = mf.read_notebook_configs().expect("read ok");
     assert!(mf.registry.configs_cache.read().unwrap().is_some());
 
-    // notebook registry 位置固定 (`index.db`), 切 notebook 不应清 cache
+    // notebook registry 位置固定 (`local.db`), 切 notebook 不应清 cache
     let mut mf = mf;
     mf.set_current_notebook(Some("nb_test".to_string()));
     mf.set_current_notebook(Some("nb_other".to_string()));
@@ -2791,13 +2415,12 @@ fn read_index_returns_none_for_missing_file_without_caching() {
 
 fn read_note_tags(mf: &MemoFile, relative_path: &str) -> Vec<String> {
     let conn = rusqlite::Connection::open(mf.notebook_db_path("nb_test").unwrap()).unwrap();
-    let mut stmt = conn
-        .prepare("SELECT tag FROM note_tags WHERE relative_path = ?1 ORDER BY tag ASC")
-        .unwrap();
-    stmt.query_map([relative_path], |row| row.get(0))
-        .unwrap()
-        .collect::<Result<Vec<_>, _>>()
-        .unwrap()
+    let tags: String = conn.query_row(
+        "SELECT tags FROM notes WHERE relative_path = ?1", [relative_path], |row| row.get(0),
+    ).unwrap();
+    let mut tags: Vec<String> = serde_json::from_str(&tags).unwrap();
+    tags.sort();
+    tags
 }
 
 fn read_body(mf: &MemoFile, filename: &str) -> String {
@@ -2839,7 +2462,7 @@ fn move_tag_rewrites_exact_match_in_both_sources() {
         vec!["中国/曼谷".to_string()]
     );
 
-    // 验证 note_tags 同步
+    // 验证 notes.tags 同步
     let tags = read_note_tags(&mf, &relative_path);
     assert_eq!(tags, vec!["中国/曼谷".to_string()]);
 }
@@ -3057,7 +2680,7 @@ fn move_tag_handles_multiple_memos() {
 }
 
 #[test]
-fn move_tag_preserves_frontmatter_key() {
+fn move_tag_updates_body_without_frontmatter_identity() {
     let (mf, _base) = fresh_memo_file();
     let relative_path = mf
         .create_note_by_path(
@@ -3072,9 +2695,7 @@ fn move_tag_preserves_frontmatter_key() {
         .unwrap();
 
     let body = read_body(&mf, &relative_path);
-    // frontmatter key 必须保留 (跟原 memo id 一致)
-    let key = super::frontmatter::extract_frontmatter_key(&body);
-    assert_eq!(key, None, "frontmatter key 必须在改写后保留: body = {body}");
+    assert!(body.contains("中国/曼谷"));
 }
 
 #[test]
@@ -3094,59 +2715,14 @@ fn move_tag_no_match_returns_zero_affected() {
 // Step 3+: 路径式 tag 选中某 segment 时 (e.g. `中国`), filter 应
 // 包含所有前缀匹配的 memo (`中国` / `中国/湖南` / `中国/湖南/长沙` 都命中)。
 #[test]
-fn empty_notebook_tag_can_be_created_and_listed() {
-    let (mf, _base) = fresh_memo_file();
-    let created = mf
-        .create_notebook_tag("nb_test", "projects/flowix")
-        .unwrap();
-
-    assert_eq!(created, "projects/flowix");
-    assert_eq!(
-        mf.read_notebook_tag_paths(Some("nb_test")).unwrap(),
-        vec!["projects".to_string(), "projects/flowix".to_string()]
-    );
-    assert!(mf
-        .read_all_memos_filtered("tagged", "createdAt", Some("projects/flowix"))
-        .is_empty());
-}
-
-#[test]
-fn deleting_last_tagged_memo_keeps_notebook_tag() {
+fn deleting_last_tagged_memo_removes_derived_tag() {
     let (mf, _base) = fresh_memo_file();
     let memo = mf
         .create_memo("Tagged", "body", Some("keep/empty"))
         .unwrap();
 
-    assert!(mf.delete_memo(&memo.id));
-    assert_eq!(
-        mf.read_notebook_tag_paths(Some("nb_test")).unwrap(),
-        vec!["keep".to_string(), "keep/empty".to_string()]
-    );
-}
-
-#[test]
-fn empty_notebook_tag_can_be_moved_and_deleted() {
-    let (mf, _base) = fresh_memo_file();
-    mf.create_notebook_tag("nb_test", "empty/old").unwrap();
-
-    let moved = mf
-        .move_memo_tag_locked(Some("nb_test"), "empty/old", "empty/new")
-        .unwrap();
-    assert_eq!(moved.affected_memos, 0);
-    assert_eq!(
-        moved.renamed_tags,
-        vec![("empty/old".to_string(), "empty/new".to_string())]
-    );
-
-    let deleted = mf
-        .delete_memo_tag_locked(Some("nb_test"), "empty/new")
-        .unwrap();
-    assert_eq!(deleted.affected_memos, 0);
-    assert_eq!(deleted.deleted_tags, vec!["empty/new".to_string()]);
-    assert_eq!(
-        mf.read_notebook_tag_paths(Some("nb_test")).unwrap(),
-        vec!["empty".to_string()]
-    );
+    assert!(mf.delete_memo(&memo.relative_path));
+    assert!(mf.read_notebook_tag_paths(Some("nb_test")).unwrap().is_empty());
 }
 
 #[test]
@@ -3171,37 +2747,37 @@ fn read_all_memos_filtered_tagged_with_path_prefix() {
 
     // 选 `中国` → 命中 3 条 (中国, 中国/湖南, 中国/湖南/长沙)
     let hit = mf.read_all_memos_filtered("tagged", "createdAt", Some("中国"));
-    let hit_ids: Vec<_> = hit.iter().map(|m| m.id.clone()).collect();
+    let hit_ids: Vec<_> = hit.iter().map(|m| m.relative_path.clone()).collect();
     assert_eq!(hit_ids.len(), 3, "中国 prefix 应命中 3 条: {hit_ids:?}");
-    assert!(hit_ids.contains(&m_china.id));
-    assert!(hit_ids.contains(&m_hunan.id));
-    assert!(hit_ids.contains(&m_changsha.id));
+    assert!(hit_ids.contains(&m_china.relative_path));
+    assert!(hit_ids.contains(&m_hunan.relative_path));
+    assert!(hit_ids.contains(&m_changsha.relative_path));
     assert!(
-        !hit_ids.contains(&m_thailand.id),
+        !hit_ids.contains(&m_thailand.relative_path),
         "泰国 不应被中国 prefix 命中"
     );
-    assert!(!hit_ids.contains(&m_unrelated.id));
+    assert!(!hit_ids.contains(&m_unrelated.relative_path));
 
     // 选 `中国/湖南` → 命中 2 条 (中国/湖南, 中国/湖南/长沙)
     let hit = mf.read_all_memos_filtered("tagged", "createdAt", Some("中国/湖南"));
-    let hit_ids: Vec<_> = hit.iter().map(|m| m.id.clone()).collect();
+    let hit_ids: Vec<_> = hit.iter().map(|m| m.relative_path.clone()).collect();
     assert_eq!(
         hit_ids.len(),
         2,
         "中国/湖南 prefix 应命中 2 条: {hit_ids:?}"
     );
-    assert!(hit_ids.contains(&m_hunan.id));
-    assert!(hit_ids.contains(&m_changsha.id));
+    assert!(hit_ids.contains(&m_hunan.relative_path));
+    assert!(hit_ids.contains(&m_changsha.relative_path));
     assert!(
-        !hit_ids.contains(&m_china.id),
+        !hit_ids.contains(&m_china.relative_path),
         "中国 自身不应被 中国/湖南 命中"
     );
 
     // 选 `中国/湖南/长沙` → 命中 1 条 (精确匹配)
     let hit = mf.read_all_memos_filtered("tagged", "createdAt", Some("中国/湖南/长沙"));
-    let hit_ids: Vec<_> = hit.iter().map(|m| m.id.clone()).collect();
+    let hit_ids: Vec<_> = hit.iter().map(|m| m.relative_path.clone()).collect();
     assert_eq!(hit_ids.len(), 1);
-    assert_eq!(hit_ids[0], m_changsha.id);
+    assert_eq!(hit_ids[0], m_changsha.relative_path);
 
     // 子串不命中: 选 `中` 不应匹配任何 (整段前缀, 不做 contains 模糊)
     let hit = mf.read_all_memos_filtered("tagged", "createdAt", Some("中"));
@@ -3371,9 +2947,9 @@ fn next_notebook_sort_returns_step_above_max() {
 }
 
 #[test]
-fn open_index_db_upgrades_legacy_schema_and_normalizes_sort() {
-    // 模拟 v3 之前的 index.db: 没有 sort 列, 已存在多条笔记本 sort=0 (默认)。
-    // 第一次 open_index_db 应该自动 ALTER + normalize, 让旧行 sort 变成 10/20/30...。
+fn local_db_initialization_upgrades_schema_and_normalizes_sort() {
+    // 模拟旧 local.db: 没有 sort 列, 已存在多条笔记本 sort=0 (默认)。
+    // 显式初始化应该 ALTER + normalize, 让旧行 sort 变成 10/20/30...。
     let tmp = std::env::temp_dir().join(format!(
         "flowix-notebook-legacy-{}-{}",
         std::process::id(),
@@ -3384,9 +2960,10 @@ fn open_index_db_upgrades_legacy_schema_and_normalizes_sort() {
     let config_dir = tmp.join("config");
     fs::create_dir_all(&config_dir).unwrap();
 
+    fs::create_dir_all(config_dir.join("db")).unwrap();
     // 直接打开一个 SQLite db, 用旧 schema 写两行 (不带 sort 列)
     {
-        let conn = rusqlite::Connection::open(config_dir.join("index.db")).unwrap();
+        let conn = rusqlite::Connection::open(config_dir.join("db/local.db")).unwrap();
         conn.execute_batch(
             r#"
             CREATE TABLE notebooks (
@@ -3434,6 +3011,7 @@ fn open_index_db_upgrades_legacy_schema_and_normalizes_sort() {
 
     // 现在用 MemoFile 打开同一份 db, 应该触发 ALTER + normalize。
     let mf = MemoFile::new(config_dir.clone());
+    mf.initialize_registry_storage().unwrap();
     let configs = mf.read_notebook_configs().expect("read ok");
 
     // normalize 走 ORDER BY created_at ASC, 所以 nb_beta (50) 在前, sort=10;
@@ -3458,7 +3036,7 @@ fn open_index_db_upgrades_legacy_schema_and_normalizes_sort() {
     });
     mf.write_notebook_configs(&next_configs).unwrap();
 
-    let conn = rusqlite::Connection::open(config_dir.join("index.db")).unwrap();
+    let conn = rusqlite::Connection::open(config_dir.join("db/local.db")).unwrap();
     let sort_alpha: i64 = conn
         .query_row(
             "SELECT sort FROM notebooks WHERE id = 'nb_alpha'",
@@ -3553,7 +3131,7 @@ fn removing_yaml_tag_keeps_membership_when_body_still_contains_it() {
         .unwrap();
 
     let updated = mf
-        .write_memo(&memo.id, "---\ntags: []\n---\nBody #shared")
+        .write_memo(&memo.relative_path, "---\ntags: []\n---\nBody #shared")
         .unwrap();
     assert_eq!(updated.tags, vec!["shared"]);
 
@@ -3579,7 +3157,7 @@ fn tag_union_index_upgrade_rebuilds_index_without_touching_markdown() {
         .unwrap();
 
     assert_eq!(updated, 0);
-    // note_tags is a set; assert membership without depending on row order.
+    // The tags JSON column is a set-like projection; assert membership without depending on order.
     let mut tags = read_note_tags(&mf, &memo.relative_path);
     tags.sort();
     assert_eq!(
diff --git a/app/flowix-core/src/memo_file/types.rs b/app/flowix-core/src/memo_file/types.rs
index fb68f9f5e..a8c5f457c 100644
--- a/app/flowix-core/src/memo_file/types.rs
+++ b/app/flowix-core/src/memo_file/types.rs
@@ -1,20 +1,12 @@
 //! 公开 DTO 类型 — `Memo` / `Notebook` / `TodoItem` / `MemoTag` /
-//! `NotebookConfig` / `MemoIndexFile` / `MemoIndexEntry` / `MemoTodoEntry` /
-//! `MemoMetadataFile`。
+//! `NotebookConfig` / notebook-relative-path projections。
 //!
 //! 拆分理由: 旧 `memo_file.rs` 把全部 DTO 堆在文件顶部, 跟 IO/CRUD/registration
 //! 混在一起, 1654 行 god module。DTO 是稳定边界 (前端 TS 镜像直接读这些字段),
 //! 单独放 `types.rs` 后改 IO 不影响类型签名。
 //!
-//! ## v3 — 2026/06 重构: `filename` 作为 path
-//!
-//! 旧版: `MemoIndexEntry` 不存物理路径, 物理文件名由 `entry.filename + entry.id` 拼成
-//! `{title}#xxxxxx.md`。`Memo` 额外带 `path` 字段 (内存拼出来的相对路径)。
-//!
-//! 现版: 物理文件 = `<notebook>/<filename>.md`, `entry.filename` 直接是磁盘文件名
-//! (含 `.md`)。`Memo` / `MemoIndexEntry` 都不再有 `path` 字段; 物理路径运行时
-//! 拼 `get_memo_base() + filename`。`Memo` 的 `filename` 字段即"磁盘文件名",
-//! 前端展示时去掉 `.md` 后缀即可。
+//! 笔记由 `(notebook_id, relative_path)` 定位。`filename` 是相对路径的末级文件名，
+//! 用于列表显示和文件树操作；索引不为笔记生成独立 ID。
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
@@ -25,7 +17,7 @@ use serde_json::Value;
 /// `"orange"` / ...), 数组形式存, 空数组即"无颜色"。
 /// 索引只缓存从 Markdown 解析出的值, 与 `icon` 字段同形。
 ///
-/// 旧版用单值 `Option<MemoColor>`, 现在切到 `Vec<NoteColor>`。memo index
+/// 旧版用单值 `Option<NoteColor>`, 现在切到 `Vec<NoteColor>`。memo index
 /// 老数据若含 `"color": "red"` / `"color": null` 会反序列化失败, 但本字段
 /// 是这次会话新加的, 没有真实数据, 走纯 breaking change 即可。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -40,20 +32,15 @@ pub enum NoteColor {
     Gray,
 }
 
-/// Compatibility name for older Memo-ID models and downstream callers.
-pub type MemoColor = NoteColor;
-
-/// 跨 IPC 边界返回的 memo 完整形态 (前端 TS `MemoItem` 镜像)。
+/// 跨 IPC 边界返回的笔记投影 (前端 TS `MemoItem` 镜像)。
 ///
 /// 字段语义:
-/// - `id`: 旧版兼容标识, 仍供深链及 noteReference 使用；路径是笔记索引主键。
+/// - `relative_path`: 相对于 notebook 根目录的笔记路径，也是索引键。
 /// - `filename`: 磁盘文件名, 含 `.md` 后缀 (如 `Hello.md` / `Hello-1.md`)。
-///   列表展示前端去掉 `.md`; 编辑器内展示用 `MemoItem.filename` 直接可。
-/// - `preview` / `tags` / `todos` / `agents`: 从 body 派生的 memo index 缓存字段。
+/// - `preview` / `tags` / `todos` / `agents`: from Markdown content, cached in the index.
 /// - `favorited` / `icon` / `colors`: 从 Markdown frontmatter 读取的持久属性。
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Memo {
-    pub id: String,
     /// 文件名本身，不包含笔记本内的目录部分。
     pub filename: String,
     /// 相对于所属笔记本根目录的规范化路径，使用 `/` 作为分隔符。
@@ -76,7 +63,7 @@ pub struct Memo {
     pub favorited: bool,
     pub icon: Option<String>,
     #[serde(default)]
-    pub colors: Vec<MemoColor>,
+    pub colors: Vec<NoteColor>,
     #[serde(default)]
     pub properties: Value,
 }
@@ -150,17 +137,46 @@ pub struct NotebookConfig {
 #[serde(rename_all = "camelCase")]
 pub struct NotebookSetupJob {
     pub notebook_id: String,
+    /// Stable identity for this logical setup task. Retries keep the same ID;
+    /// replacing or recreating a task gets a new ID.
+    #[serde(default)]
+    pub job_id: String,
     pub template_id: Option<String>,
     #[serde(default)]
     pub overwrite_existing: bool,
     #[serde(rename = "status")]
     pub status: NotebookSetupJobStatus,
-    pub stage: String,
-    pub completed_files: usize,
-    pub total_files: usize,
+    pub stage: NotebookSetupStage,
+    #[serde(default)]
+    pub revision: i64,
+    #[serde(default)]
+    pub run_id: String,
     pub message: Option<String>,
     pub report: Option<NotebookSetupReport>,
     pub updated_at: i64,
+    /// Persisted after the workspace is ready to let this job execute.
+    #[serde(default)]
+    pub execution_requested: bool,
+}
+
+/// Consistent registry snapshot used to reconcile missed events and removed
+/// notebook setup tasks in a WebView.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookSetupSnapshot {
+    pub revision: i64,
+    pub jobs: Vec<NotebookSetupJob>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum NotebookSetupStage {
+    #[serde(alias = "queued")]
+    Preparing,
+    #[serde(alias = "template")]
+    Writing,
+    Indexing,
+    Completed,
 }
 
 /// Aggregate result of a best-effort template application. Existing files are
@@ -204,15 +220,9 @@ pub struct MemoLocation {
     pub notebook: NotebookConfig,
 }
 
-// ============================================
-// Legacy memo-ID list entry persisted in the notebook-local database.
-// ============================================
-
-/// memo index 单条 memo 元数据。`filename` 即磁盘文件名, 含 `.md`。
-/// 旧版有 `path` 字段, 现版删除, 物理路径运行时拼。
+/// Rebuildable note projection row. The notebook-relative path is its key.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MemoIndexEntry {
-    pub id: String,
     /// 磁盘文件名, 含 `.md` 后缀。冲突时由 ops 层自动追加 `-1` / `-2`。
     pub filename: String,
     /// 相对于 notebook 根目录的规范化路径，使用 `/` 作为分隔符。
@@ -233,7 +243,7 @@ pub struct MemoIndexEntry {
     #[serde(rename = "icon")]
     pub icon: Option<String>,
     #[serde(default)]
-    pub colors: Vec<MemoColor>,
+    pub colors: Vec<NoteColor>,
     #[serde(default)]
     pub properties: Value,
 }
@@ -255,46 +265,6 @@ impl Default for MemoIndexFile {
     }
 }
 
-// ============================================
-// Legacy memo-ID todo metadata persisted in the notebook-local database.
-// ============================================
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct MemoTodoEntry {
-    #[serde(rename = "todoId", default)]
-    pub todo_id: String,
-    pub content: String,
-    pub status: String,
-    #[serde(rename = "memoId")]
-    pub memo_id: String,
-    pub priority: String,
-    #[serde(rename = "timeRange")]
-    pub time_range: String,
-    pub owner: String,
-    pub assignee: String,
-    #[serde(rename = "createdAt")]
-    pub created_at: i64,
-    #[serde(rename = "updatedAt")]
-    pub updated_at: i64,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct MemoMetadataFile {
-    pub version: u32,
-    pub last_updated: i64,
-    pub todos: Vec<MemoTodoEntry>,
-}
-
-impl Default for MemoMetadataFile {
-    fn default() -> Self {
-        Self {
-            version: 1,
-            last_updated: chrono::Utc::now().timestamp_millis(),
-            todos: Vec::new(),
-        }
-    }
-}
-
 /// [`crate::memo_file::MemoFile::reconcile_with_disk_bidirectional`] 的返回报告。
 ///
 /// - `added`: 磁盘上有但 `memo index` 没有的 .md 文件, 被注册进 memo index 的条数。
@@ -316,7 +286,7 @@ pub struct ReconcileReport {
 
 /// [`crate::memo_file::MemoFile::move_memo_tag_locked`] 的返回报告。
 ///
-/// - `affected_memos`: 实际被批量改写 YAML `tags` + 同步 memo index 的 memo
+/// - `affected_memos`: 实际被批量改写 YAML `tags` + 同步索引的笔记数
 ///   条数; 当 `old_path` 在任何 memo 都没出现时为 0。
 /// - `renamed_tags`: 操作涉及的 `(old, new)` tag name 对 (去重)。`old`
 ///   可以是 `old_path` 本身, 也可以是 `old_path/<...>` 的子树 tag。
@@ -331,7 +301,7 @@ pub struct MoveTagReport {
 
 /// [`crate::memo_file::MemoFile::delete_memo_tag_locked`] 的返回报告。
 ///
-/// - `affected_memos`: 实际被批量改写 YAML `tags` + 同步 memo index 的 memo
+/// - `affected_memos`: 实际被批量改写 YAML `tags` + 同步索引的笔记数
 ///   条数; 当 `tag_path` 在任何 memo 都没出现时为 0。
 /// - `deleted_tags`: 操作涉及的 (被删除的) tag 路径, 含 `tag_path` 自身
 ///   加上所有以 `tag_path/` 为前缀的子树 tag, **去重**。 前端用它把
diff --git a/app/flowix-core/src/memo_file/versions.rs b/app/flowix-core/src/memo_file/versions.rs
index 592ba57ec..f9fbc2a15 100644
--- a/app/flowix-core/src/memo_file/versions.rs
+++ b/app/flowix-core/src/memo_file/versions.rs
@@ -1,6 +1,11 @@
 use std::fs;
 use std::path::{Path, PathBuf};
 
+const VERSION_ID_ALPHABET: [char; 36] = [
+    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i',
+    'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z',
+];
+
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 
@@ -276,7 +281,7 @@ impl MemoFile {
         let id = format!(
             "v_{}_{}",
             now.format("%Y%m%d_%H%M%S"),
-            nanoid::nanoid!(6, &super::MEMO_ID_ALPHABET)
+            nanoid::nanoid!(6, &VERSION_ID_ALPHABET)
         );
         let meta = PathVersionMeta {
             id: id.clone(),
diff --git a/app/flowix-core/src/memo_file/workspace.rs b/app/flowix-core/src/memo_file/workspace.rs
new file mode 100644
index 000000000..43857a87c
--- /dev/null
+++ b/app/flowix-core/src/memo_file/workspace.rs
@@ -0,0 +1,450 @@
+//! Device-local notebook repository attachments. JSON files are upgrade inputs only.
+use super::notebook::sqlite_to_io;
+use super::{MemoFile, NotebookConfig};
+use rusqlite::{params, OptionalExtension, TransactionBehavior};
+use serde::{Deserialize, Serialize};
+use std::{collections::HashMap, fs, path::Path};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookAddDir {
+    pub id: String,
+    pub path: String,
+    pub label: String,
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+    #[serde(default)]
+    pub missing: bool,
+}
+fn default_enabled() -> bool {
+    true
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookWorkspaceConfig {
+    #[serde(default = "config_version")]
+    pub version: u32,
+    #[serde(default)]
+    pub revision: u64,
+    #[serde(default)]
+    pub add_dirs: Vec<NotebookAddDir>,
+}
+fn config_version() -> u32 {
+    1
+}
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookWorkspaceSnapshot {
+    pub notebooks: Vec<NotebookConfig>,
+    pub notebook_configs: HashMap<String, NotebookWorkspaceConfig>,
+}
+
+impl MemoFile {
+    pub(super) fn workspace_connection(&self) -> std::io::Result<rusqlite::Connection> {
+        let conn = self.open_registry_db()?;
+        conn.execute_batch("CREATE TABLE IF NOT EXISTS notebook_workspace_state (
+            notebook_id TEXT PRIMARY KEY REFERENCES notebooks(id) ON DELETE CASCADE,
+            revision INTEGER NOT NULL DEFAULT 0);
+            CREATE TABLE IF NOT EXISTS notebook_add_dirs (
+            id TEXT NOT NULL, notebook_id TEXT NOT NULL REFERENCES notebooks(id) ON DELETE CASCADE,
+            path TEXT NOT NULL, path_key TEXT NOT NULL, label TEXT NOT NULL, enabled INTEGER NOT NULL,
+            sort INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
+            PRIMARY KEY(notebook_id,id), UNIQUE(notebook_id,path_key));").map_err(sqlite_to_io)?;
+        Ok(conn)
+    }
+
+    /// This is the only remaining reader of old global Agent runtime defaults.
+    pub fn read_legacy_agent_runtime(&self) -> std::io::Result<Option<serde_json::Value>> {
+        Ok(self
+            .read_legacy_agent_access()?
+            .get("defaults")
+            .and_then(|d| d.get("runtime"))
+            .cloned())
+    }
+    fn read_legacy_agent_access(&self) -> std::io::Result<serde_json::Value> {
+        let path = self.registry.config_dir.join("agent-access.json");
+        match fs::read(&path) {
+            Ok(bytes) => match serde_json::from_slice(&bytes) {
+                Ok(value) => Ok(value),
+                Err(_) => {
+                    super::backup_storage_file(&path)?;
+                    Ok(serde_json::Value::Null)
+                }
+            },
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(serde_json::Value::Null),
+            Err(e) => Err(e),
+        }
+    }
+    pub fn read_notebook_workspace(&self) -> std::io::Result<NotebookWorkspaceSnapshot> {
+        let notebooks = self.read_notebook_configs()?;
+        let conn = self.workspace_connection()?;
+        let mut notebook_configs = HashMap::new();
+        for notebook in &notebooks {
+            let revision = conn
+                .query_row(
+                    "SELECT revision FROM notebook_workspace_state WHERE notebook_id=?1",
+                    [&notebook.id],
+                    |r| r.get(0),
+                )
+                .optional()
+                .map_err(sqlite_to_io)?
+                .unwrap_or(0);
+            let mut stmt = conn.prepare("SELECT id,path,label,enabled FROM notebook_add_dirs WHERE notebook_id=?1 ORDER BY sort,id").map_err(sqlite_to_io)?;
+            let add_dirs = stmt
+                .query_map([&notebook.id], |r| {
+                    let path: String = r.get(1)?;
+                    let missing = !Path::new(&path).is_dir();
+                    Ok(NotebookAddDir {
+                        id: r.get(0)?,
+                        path,
+                        label: r.get(2)?,
+                        enabled: r.get(3)?,
+                        missing,
+                    })
+                })
+                .map_err(sqlite_to_io)?
+                .collect::<Result<_, _>>()
+                .map_err(sqlite_to_io)?;
+            notebook_configs.insert(
+                notebook.id.clone(),
+                NotebookWorkspaceConfig {
+                    version: 1,
+                    revision,
+                    add_dirs,
+                },
+            );
+        }
+        Ok(NotebookWorkspaceSnapshot {
+            notebooks,
+            notebook_configs,
+        })
+    }
+    pub fn update_notebook_add_dir(
+        &self,
+        notebook_id: &str,
+        path: &str,
+        attach: bool,
+    ) -> std::io::Result<NotebookWorkspaceSnapshot> {
+        let notebook = self
+            .read_notebook_configs()?
+            .into_iter()
+            .find(|n| n.id == notebook_id)
+            .ok_or_else(|| std::io::Error::other("notebook not found"))?;
+        let normalized = normalized_directory(path);
+        let stored_path = normalized.to_string_lossy();
+        let key = directory_key(path);
+        if attach {
+            validate_add_dir(&notebook.path, path, true)?;
+        }
+        let mut conn = self.workspace_connection()?;
+        let tx = conn
+            .transaction_with_behavior(TransactionBehavior::Immediate)
+            .map_err(sqlite_to_io)?;
+        let now = chrono::Utc::now().timestamp_millis();
+        let changed = if attach {
+            let label = Path::new(path)
+                .file_name()
+                .unwrap_or_default()
+                .to_string_lossy()
+                .to_string();
+            tx.execute("INSERT INTO notebook_add_dirs (id,notebook_id,path,path_key,label,enabled,sort,created_at,updated_at) VALUES (?1,?2,?3,?4,?5,1,COALESCE((SELECT MAX(sort)+1 FROM notebook_add_dirs WHERE notebook_id=?2),0),?6,?6) ON CONFLICT(notebook_id,path_key) DO UPDATE SET enabled=1,updated_at=excluded.updated_at WHERE enabled=0", params![uuid::Uuid::new_v4().to_string(),notebook_id,stored_path,key,label,now]).map_err(sqlite_to_io)?
+        } else {
+            // Exact stored paths also allow removing a missing symlink after its target disappeared.
+            tx.execute(
+                "DELETE FROM notebook_add_dirs WHERE notebook_id=?1 AND (path_key=?2 OR path=?3)",
+                params![notebook_id, key, path],
+            )
+            .map_err(sqlite_to_io)?
+        };
+        if changed > 0 {
+            tx.execute("INSERT INTO notebook_workspace_state VALUES (?1,1) ON CONFLICT(notebook_id) DO UPDATE SET revision=revision+1",[notebook_id]).map_err(sqlite_to_io)?;
+        }
+        tx.commit().map_err(sqlite_to_io)?;
+        self.read_notebook_workspace()
+    }
+    pub fn attached_directory_paths(&self) -> std::io::Result<Vec<std::path::PathBuf>> {
+        let conn = self.workspace_connection()?;
+        let mut stmt = conn
+            .prepare("SELECT DISTINCT path FROM notebook_add_dirs WHERE enabled=1")
+            .map_err(sqlite_to_io)?;
+        let paths = stmt
+            .query_map([], |r| r.get::<_, String>(0))
+            .map_err(sqlite_to_io)?
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(sqlite_to_io)?;
+        Ok(paths
+            .into_iter()
+            .map(std::path::PathBuf::from)
+            .filter(|path| path.is_dir())
+            .collect())
+    }
+}
+fn normalized_directory(path: &str) -> std::path::PathBuf {
+    dunce::canonicalize(path).unwrap_or_else(|_| {
+        let mut normalized = std::path::PathBuf::new();
+        for component in Path::new(path).components() {
+            match component {
+                std::path::Component::CurDir => {}
+                std::path::Component::ParentDir => {
+                    normalized.pop();
+                }
+                other => normalized.push(other.as_os_str()),
+            }
+        }
+        normalized
+    })
+}
+fn directory_key(path: &str) -> String {
+    let key = normalized_directory(path).to_string_lossy().into_owned();
+    #[cfg(target_os = "windows")]
+    let key = key.to_lowercase();
+    key
+}
+fn validate_add_dir(notebook: &str, path: &str, require_exists: bool) -> std::io::Result<()> {
+    if !Path::new(path).is_absolute() || (require_exists && !Path::new(path).is_dir()) {
+        return Err(std::io::Error::other("add-dir is unavailable"));
+    }
+    let root = normalized_directory(notebook);
+    let target = normalized_directory(path);
+    if root.starts_with(&target) || target.starts_with(root.join(".flowix")) {
+        return Err(std::io::Error::other("invalid notebook add-dir scope"));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn fixture() -> (tempfile::TempDir, MemoFile, NotebookConfig) {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path().join("notes");
+        fs::create_dir(&root).unwrap();
+        let memo = MemoFile::new(temp.path().join("config"));
+        let notebook = NotebookConfig {
+            id: "one".into(),
+            name: "One".into(),
+            icon: None,
+            path: root.to_string_lossy().into(),
+            is_default: true,
+            sort: 0,
+            created_at: 1,
+            updated_at: 1,
+        };
+        memo.write_notebook_configs(std::slice::from_ref(&notebook))
+            .unwrap();
+        (temp, memo, notebook)
+    }
+    #[test]
+    fn imports_local_mounts_once_and_does_not_grant_orphan_global_entries() {
+        let (temp, memo, notebook) = fixture();
+        let repo = temp.path().join("repo");
+        fs::create_dir(&repo).unwrap();
+        let missing = temp.path().join("missing");
+        let source = Path::new(&notebook.path).join(".flowix/agent.json");
+        fs::write(
+            &source,
+            serde_json::json!({"version":1,"revision":4,"addDirs":[
+                {"id":"repo","path":repo,"label":"Repo","enabled":true},
+                {"id":"missing","path":missing,"label":"Missing","enabled":true}
+            ]})
+            .to_string(),
+        )
+        .unwrap();
+        fs::write(
+            temp.path().join("config/agent-access.json"),
+            r#"{"entries":[{"kind":"folder","path":"/orphan","enabled":true}]}"#,
+        )
+        .unwrap();
+        let first = memo.read_notebook_workspace().unwrap();
+        assert_eq!(first.notebook_configs["one"].add_dirs.len(), 2);
+        assert!(first.notebook_configs["one"].add_dirs[1].missing);
+        assert_eq!(
+            memo.attached_directory_paths().unwrap(),
+            vec![dunce::canonicalize(&repo).unwrap()]
+        );
+        memo.update_notebook_add_dir("one", repo.to_str().unwrap(), false)
+            .unwrap();
+        fs::write(&source, "invalid JSON").unwrap();
+        assert_eq!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["one"]
+                .add_dirs
+                .len(),
+            1
+        );
+        assert!(memo.attached_directory_paths().unwrap().is_empty());
+    }
+    #[test]
+    fn shares_paths_across_notebooks_and_cascades_deleted_notebook_mounts() {
+        let (temp, memo, one) = fixture();
+        let mut two = one.clone();
+        two.id = "two".into();
+        two.path = temp.path().join("two").to_string_lossy().into();
+        fs::create_dir(&two.path).unwrap();
+        memo.write_notebook_configs(&[one.clone(), two.clone()])
+            .unwrap();
+        let repo = temp.path().join("repo");
+        fs::create_dir(&repo).unwrap();
+        for id in ["one", "two"] {
+            memo.update_notebook_add_dir(id, repo.to_str().unwrap(), true)
+                .unwrap();
+        }
+        memo.update_notebook_add_dir("one", repo.to_str().unwrap(), true)
+            .unwrap();
+        assert_eq!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["one"]
+                .add_dirs
+                .len(),
+            1
+        );
+        memo.write_notebook_configs(&[two]).unwrap();
+        let conn = memo.workspace_connection().unwrap();
+        assert_eq!(
+            conn.query_row("SELECT COUNT(*) FROM notebook_add_dirs", [], |r| r
+                .get::<_, i64>(0))
+                .unwrap(),
+            1
+        );
+        assert_eq!(
+            memo.attached_directory_paths().unwrap(),
+            vec![dunce::canonicalize(&repo).unwrap()]
+        );
+    }
+    #[test]
+    fn imports_global_legacy_defaults_and_defers_unavailable_notebooks() {
+        let (temp, memo, notebook) = fixture();
+        let repo = temp.path().join("repo");
+        fs::create_dir(&repo).unwrap();
+        fs::write(
+            temp.path().join("config/agent-access.json"),
+            serde_json::json!({"defaults":{"files":{"one":{"folders":[repo]}}}}).to_string(),
+        )
+        .unwrap();
+        fs::rename(&notebook.path, temp.path().join("parked")).unwrap();
+        assert!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["one"]
+                .add_dirs
+                .is_empty()
+        );
+        fs::rename(temp.path().join("parked"), &notebook.path).unwrap();
+        assert_eq!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["one"]
+                .add_dirs
+                .len(),
+            1
+        );
+        assert!(memo
+            .update_notebook_add_dir("one", temp.path().to_str().unwrap(), true)
+            .is_err());
+    }
+    #[test]
+    fn invalid_legacy_json_remains_retryable() {
+        let (temp, memo, notebook) = fixture();
+        let source = Path::new(&notebook.path).join(".flowix/agent.json");
+        fs::write(&source, "broken").unwrap();
+        assert!(memo.read_notebook_workspace().is_err());
+        fs::write(&source, r#"{"version":1,"addDirs":[]}"#).unwrap();
+        assert!(memo.read_notebook_workspace().is_ok());
+        assert!(temp.path().join("config/db/local.db").is_file());
+    }
+}
+
+#[cfg(test)]
+mod concurrency_tests {
+    use super::*;
+    #[test]
+    fn concurrent_process_connections_preserve_independent_mounts() {
+        let temp = tempfile::tempdir().unwrap();
+        let config = temp.path().join("config");
+        let notes = temp.path().join("notes");
+        fs::create_dir(&notes).unwrap();
+        let memo = MemoFile::new(config.clone());
+        memo.write_notebook_configs(&[NotebookConfig {
+            id: "one".into(),
+            name: "One".into(),
+            icon: None,
+            path: notes.to_string_lossy().into(),
+            is_default: true,
+            sort: 0,
+            created_at: 1,
+            updated_at: 1,
+        }])
+        .unwrap();
+        memo.read_notebook_workspace().unwrap();
+        let paths: Vec<_> = (0..4)
+            .map(|i| {
+                let p = temp.path().join(format!("repo{i}"));
+                fs::create_dir(&p).unwrap();
+                p
+            })
+            .collect();
+        let barrier = std::sync::Arc::new(std::sync::Barrier::new(paths.len()));
+        let threads: Vec<_> = paths
+            .iter()
+            .cloned()
+            .map(|path| {
+                let config = config.clone();
+                let barrier = barrier.clone();
+                std::thread::spawn(move || {
+                    let memo = MemoFile::new(config);
+                    barrier.wait();
+                    memo.update_notebook_add_dir("one", path.to_str().unwrap(), true)
+                        .unwrap();
+                })
+            })
+            .collect();
+        for thread in threads {
+            thread.join().unwrap();
+        }
+        assert_eq!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["one"]
+                .add_dirs
+                .len(),
+            4
+        );
+        assert_eq!(memo.attached_directory_paths().unwrap().len(), 4);
+    }
+}
+
+#[cfg(test)]
+mod legacy_global_defaults_tests {
+    use super::*;
+    #[test]
+    fn stale_global_defaults_apply_only_to_preupgrade_notebooks() {
+        let temp = tempfile::tempdir().unwrap();
+        let notes = temp.path().join("old");
+        fs::create_dir(&notes).unwrap();
+        let repo = temp.path().join("repo");
+        fs::create_dir(&repo).unwrap();
+        let config = temp.path().join("config");
+        let memo = MemoFile::new(config.clone());
+        let old = NotebookConfig {
+            id: "old".into(),
+            name: "Old".into(),
+            icon: None,
+            path: notes.to_string_lossy().into(),
+            is_default: true,
+            sort: 0,
+            created_at: 0,
+            updated_at: 0,
+        };
+        memo.write_notebook_configs(std::slice::from_ref(&old))
+            .unwrap();
+        fs::write(config.join("agent-access.json"),serde_json::json!({"entries":[{"id":"old","kind":"notebook"}],"defaults":{"files":{"_global":{"folders":[repo]}}}}).to_string()).unwrap();
+        assert_eq!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["old"]
+                .add_dirs
+                .len(),
+            1
+        );
+        let mut new = old.clone();
+        new.id = "new".into();
+        new.path = temp.path().join("new").to_string_lossy().into();
+        fs::create_dir(&new.path).unwrap();
+        memo.write_notebook_configs(&[old, new]).unwrap();
+        assert!(
+            memo.read_notebook_workspace().unwrap().notebook_configs["new"]
+                .add_dirs
+                .is_empty()
+        );
+    }
+}
diff --git a/app/flowix-core/src/secret/mod.rs b/app/flowix-core/src/secret/mod.rs
index 028791bdc..e550ce940 100644
--- a/app/flowix-core/src/secret/mod.rs
+++ b/app/flowix-core/src/secret/mod.rs
@@ -3,9 +3,8 @@
 //!
 //! ## 存储
 //!
-//! - 数据库文件: `<config_dir>/default.db` (生产环境 `~/.flowix/default.db`),
-//!   与 `index.db` 同目录, 受 `~/.flowix` 目录 `0o700` 权限保护; unix 下
-//!   db 文件本身再设一次 `0o600`。
+//! - 数据库文件: `<config_dir>/db/default.db` (生产环境 `~/.flowix/db/default.db`),
+//!   Unix 下 db 文件权限为 `0o600`。
 //! - 表 `secret_kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)`, 通用
 //!   key-value 形态, 未来可承载其它敏感 / 关键配置, 不止 API key。
 //!
@@ -167,18 +166,14 @@ impl DbBackend {
         if self.db_path.exists() {
             set_file_owner_only_perms(&self.db_path)?;
         }
-        let conn = Connection::open(&self.db_path)
-            .map_err(|e| SecretStoreError::Platform(format!("open db: {e}")))?;
-        conn.execute_batch(
-            r#"
-            PRAGMA secure_delete = ON;
-            CREATE TABLE IF NOT EXISTS secret_kv (
-                key   TEXT PRIMARY KEY,
-                value TEXT NOT NULL
-            );
-            "#,
-        )
-        .map_err(|e| SecretStoreError::Platform(format!("init table: {e}")))?;
+        let conn = crate::memo_file::with_database_rebuild(&self.db_path, || {
+            let conn = Connection::open(&self.db_path).map_err(std::io::Error::other)?;
+            conn.execute_batch("PRAGMA secure_delete = ON;
+                CREATE TABLE IF NOT EXISTS secret_kv (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+                SELECT key, value FROM secret_kv LIMIT 0;")
+                .map_err(std::io::Error::other)?;
+            Ok(conn)
+        }).map_err(|error| SecretStoreError::Platform(format!("initialize secret database: {error}")))?;
         set_file_owner_only_perms(&self.db_path)?;
         Ok(conn)
     }
@@ -225,7 +220,7 @@ impl SecretBackend for DbBackend {
 ///
 /// 用法:
 /// ```ignore
-/// let store = SecretStore::new("~/.flowix/default.db");
+/// let store = SecretStore::new("~/.flowix/db/default.db");
 /// store.save("openai_responses::default", "sk-...")?;
 /// let key = store.load("openai_responses::default")?.unwrap();
 /// ```
@@ -235,7 +230,7 @@ pub struct SecretStore {
 
 impl SecretStore {
     /// 构造真实 SQLite 后端的 SecretStore ── db 路径由调用方 (UserConfigStore)
-    /// 按 config_dir 派生 (`~/.flowix/default.db`), desktop / CLI 共用。
+    /// 按 config_dir 派生 (`~/.flowix/db/default.db`), desktop / CLI 共用。
     pub fn new(db_path: impl AsRef<Path>) -> Self {
         Self {
             backend: Box::new(DbBackend::new(db_path)),
@@ -360,3 +355,20 @@ impl SecretBackend for MockBackend {
         self.backend_kind
     }
 }
+
+#[cfg(test)]
+mod storage_rebuild_tests {
+    use super::*;
+
+    #[test]
+    fn invalid_secret_database_is_preserved_before_creating_empty_credentials() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("default.db");
+        std::fs::write(&path, b"invalid credential database").unwrap();
+        let backend = DbBackend::new(path);
+        assert!(backend.load("missing-account").unwrap().is_none());
+        backend.save("new-account", "new-value").unwrap();
+        assert!(backend.load("new-account").unwrap().is_some());
+        assert!(temp.path().join("rebuild-backups").exists());
+    }
+}
diff --git a/app/flowix-core/src/service.rs b/app/flowix-core/src/service.rs
index a54acf745..24314cb45 100644
--- a/app/flowix-core/src/service.rs
+++ b/app/flowix-core/src/service.rs
@@ -1,56 +1,24 @@
 //! Application service boundary shared by desktop, CLI, MCP, and future transports.
 //!
 //! `MemoFile` remains the shared storage façade. `NoteService` is the public
-//! path-keyed Note API; `MemoService` retains Memo-ID compatibility use cases.
+//! path-keyed Note API.
 
-use std::cmp::Ordering;
-use std::collections::{HashMap, HashSet};
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
 
 use crate::memo_file::{
-    base_filename, normalize_search_tag_filter, notebook_path_from_relative,
-    resolve_filename_conflict, FileLockIntent, FileWriteGuard, Memo, MemoColor, MemoFile, MemoIndexEntry,
+    notebook_path_from_relative, MemoFile,
     NoteEntry, NoteSearchHit, NoteWriteOutcome, NotebookConfig,
 };
 
-const MAX_SEARCH_LIMIT: usize = 200;
 const DEFAULT_LIST_PAGE_SIZE: usize = 50;
 const MAX_LIST_PAGE_SIZE: usize = 100;
 const MAX_LIST_CURSOR_BYTES: usize = 4096;
 
-pub struct MemoSaveReceipt {
-    pub edited: EditedMemo,
-    pub content: String,
-    pub notebook_id: String,
-    pub commit: Option<crate::memo_file::NoteContentRevision>,
-}
-
-type TagUsageSummary = (Vec<String>, Vec<(String, usize)>, usize, usize, usize);
-
-/// Opaque-to-transport cursor for a memo list query. The query identity is
-/// included so a cursor cannot accidentally be reused after changing notebook,
-/// filter, tag, color, or sort.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-struct MemoListCursor {
-    notebook_id: Option<String>,
-    filter: String,
-    sort: String,
-    tag_id: Option<String>,
-    color: Option<String>,
-    favorited: bool,
-    sort_value: i64,
-    #[serde(default)]
-    sort_text: Option<String>,
-    #[serde(default)]
-    sort_tiebreaker: Option<String>,
-    id: String,
-}
-
-/// Opaque cursor for the path-keyed notebook list. The path, rather than a
-/// legacy memo id, is the stable tie breaker for every ordering.
+/// Opaque cursor for the path-keyed notebook list. Relative path is the stable
+/// tie breaker for every ordering.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct NoteListCursor {
     notebook_id: String,
@@ -65,13 +33,6 @@ struct NoteListCursor {
     relative_path: String,
 }
 
-#[derive(Debug, Clone)]
-pub struct MemoPage {
-    pub memos: Vec<Memo>,
-    pub next_cursor: Option<String>,
-    pub has_more: bool,
-}
-
 #[derive(Debug, Clone)]
 pub struct NotePage {
     pub notes: Vec<NoteEntry>,
@@ -97,22 +58,6 @@ pub enum FlowixError {
     Internal(String),
 }
 
-#[derive(Debug, Clone)]
-pub struct ResolvedMemo {
-    pub id: String,
-    pub entry: MemoIndexEntry,
-    pub notebook: NotebookConfig,
-    pub path: PathBuf,
-}
-
-#[derive(Debug, Clone)]
-pub struct MemoDocument {
-    pub entry: MemoIndexEntry,
-    pub notebook: NotebookConfig,
-    pub path: PathBuf,
-    pub body: String,
-}
-
 #[derive(Debug, Clone)]
 pub struct NoteDocument {
     pub entry: NoteEntry,
@@ -127,32 +72,8 @@ pub enum NoteSaveOutcome {
     Conflict { disk_content: String },
 }
 
-#[derive(Debug, Clone)]
-pub struct CreatedMemo {
-    pub memo: Memo,
-    pub notebook: NotebookConfig,
-    pub path: PathBuf,
-}
-
-#[derive(Debug, Clone)]
-pub struct EditedMemo {
-    pub id: String,
-    pub memo: Option<Memo>,
-    pub path: PathBuf,
-    pub old_bytes: usize,
-    pub new_bytes: usize,
-    pub dry_run: bool,
-}
-
-#[derive(Debug, Clone)]
-pub struct DeletedMemo {
-    pub id: String,
-    pub path: PathBuf,
-    pub file_removed: bool,
-}
-
-/// Path-identified Note use cases. This service does not resolve or retain
-/// Memo IDs; the path projection and Markdown file are its only identities.
+/// Path-identified Note use cases. The path projection and Markdown file are
+/// the note's only identities.
 pub struct NoteService<'a> {
     memo_file: &'a MemoFile,
 }
@@ -188,88 +109,8 @@ impl<'a> NoteService<'a> {
     }
 }
 
-/// Compatibility use-case facade over one `MemoFile` instance.
-///
-/// The service borrows the store instead of owning it, so Desktop can construct it from
-/// its managed `MemoFile` while CLI/MCP can construct it from a short-lived instance.
-/// Public path-identified Note operations belong to `NoteService`; this facade
-/// keeps Memo-ID lookups and legacy command use cases.
-pub struct MemoService<'a> {
-    memo_file: &'a MemoFile,
-}
-
-impl<'a> MemoService<'a> {
-    pub fn new(memo_file: &'a MemoFile) -> Self {
-        Self { memo_file }
-    }
-
-    fn lock_resolved_memo(&self, resolved: &ResolvedMemo, operation: &str) -> Result<FileWriteGuard, FlowixError> {
-        let guard = self.memo_file.operation_locks().file_write(
-            &resolved.notebook.id,
-            Path::new(&resolved.notebook.path),
-            &resolved.path,
-            FileLockIntent::Existing,
-            operation,
-        )?;
-        let current = self.memo_file.get_notebook_config_by_id(&resolved.notebook.id)
-            .ok_or_else(|| FlowixError::Conflict("notebook was removed while waiting for the file lock".into()))?;
-        if std::fs::canonicalize(&current.path)? != std::fs::canonicalize(&resolved.notebook.path)? {
-            return Err(FlowixError::Conflict("notebook root changed while waiting for the file lock".into()));
-        }
-        Ok(guard)
-    }
-
-    pub fn list_notebooks(&mut self) -> Result<Vec<NotebookConfig>, FlowixError> {
-        self.memo_file
-            .read_notebook_configs()
-            .map_err(FlowixError::Io)
-    }
-
-    pub fn notebook_note_counts(
-        &mut self,
-        configs: &[NotebookConfig],
-    ) -> Result<HashMap<String, usize>, FlowixError> {
-        let mut counts = self.memo_file.memo_counts_by_notebook()?;
-        let notebook_ids = configs
-            .iter()
-            .map(|config| config.id.as_str())
-            .collect::<HashSet<_>>();
-        counts.retain(|notebook_id, _| notebook_ids.contains(notebook_id.as_str()));
-        for config in configs {
-            counts.entry(config.id.clone()).or_insert(0);
-        }
-        Ok(counts)
-    }
-
-    pub fn list_memos(&mut self, notebook_key: &str) -> Result<Vec<MemoIndexEntry>, FlowixError> {
-        let notebook = self.resolve_notebook(notebook_key)?;
-        let mut entries = match self
-            .memo_file
-            .list_note_entries_with_legacy_ids(&notebook.id)?
-        {
-            Some(entries) => entries,
-            None => {
-                self.memo_file
-                    .read_index_for_notebook_id(Some(&notebook.id))?
-                    .unwrap_or_default()
-                    .memos
-            }
-        };
-        let policy = self.memo_file.file_management_policy(&notebook.id);
-        entries.retain(|entry| {
-            let relative_path = if entry.relative_path.is_empty() {
-                &entry.filename
-            } else {
-                &entry.relative_path
-            };
-            !policy.is_index_ignored_at(Path::new(&notebook.path), Path::new(relative_path))
-        });
-        Ok(entries)
-    }
-}
-
 impl NoteService<'_> {
-    /// List notes by notebook-relative path, without legacy memo identities.
+    /// List notes by notebook-relative path.
     pub(crate) fn list_notes_by_path(
         &mut self,
         notebook_key: &str,
@@ -446,7 +287,7 @@ impl NoteService<'_> {
         })
     }
 
-    /// Open a Markdown note by notebook and relative path, with no memo ID lookup.
+    /// Open a Markdown note by notebook and relative path.
     pub(crate) fn get_note_by_path(
         &mut self,
         notebook_key: &str,
@@ -560,884 +401,125 @@ impl NoteService<'_> {
     }
 }
 
-impl MemoService<'_> {
-    pub fn list_memos_filtered(
-        &mut self,
-        notebook_id: Option<&str>,
-        filter: &str,
-        sort: &str,
-        tag_id: Option<&str>,
-    ) -> Vec<Memo> {
-        self.memo_file
-            .read_all_memos_filtered_for_notebook_id(notebook_id, filter, sort, tag_id)
+impl<'a> NoteService<'a> {
+    pub fn list(&mut self, notebook: &str) -> Result<Vec<NoteEntry>, FlowixError> {
+        self.list_notes_by_path(notebook)
     }
 
-    /// Return one stable page from a memo query.
-    ///
-    /// The current index implementation still scans the local metadata index
-    /// to apply the existing filters, but only the requested page crosses the
-    /// transport boundary. This is intentionally layered on top of the
-    /// existing list query so filtering and ordering semantics stay identical.
-    pub fn list_memos_filtered_page(
+    pub fn list_page(
         &mut self,
-        notebook_id: Option<&str>,
+        notebook: &str,
         filter: &str,
         sort: &str,
         tag_id: Option<&str>,
         color: Option<&str>,
         cursor: Option<&str>,
-        requested_limit: Option<usize>,
-    ) -> Result<MemoPage, FlowixError> {
-        let limit = requested_limit
-            .unwrap_or(DEFAULT_LIST_PAGE_SIZE)
-            .clamp(1, MAX_LIST_PAGE_SIZE);
-        let normalized_color = color.map(str::to_string);
-        if let Some(value) = normalized_color.as_deref() {
-            match value {
-                "any" | "none" | "red" | "orange" | "yellow" | "green" | "cyan" | "blue"
-                | "gray" => {}
-                _ => {
-                    return Err(FlowixError::InvalidInput(format!(
-                        "unsupported memo color filter `{value}`"
-                    )))
-                }
-            }
-        }
-
-        let mut all = self.list_memos_filtered(notebook_id, filter, sort, tag_id);
-        if let Some(color) = normalized_color.as_deref() {
-            all.retain(|memo| match color {
-                "any" => !memo.colors.is_empty(),
-                "none" => memo.colors.is_empty(),
-                value => memo
-                    .colors
-                    .iter()
-                    .any(|memo_color| memo_color_name(*memo_color) == value),
-            });
-        }
-
-        let parsed_cursor = cursor
-            .map(|value| {
-                if value.len() > MAX_LIST_CURSOR_BYTES {
-                    return Err(FlowixError::InvalidInput(
-                        "memo list cursor is too large".to_string(),
-                    ));
-                }
-                serde_json::from_str::<MemoListCursor>(value)
-                    .map_err(|_| FlowixError::InvalidInput("invalid memo list cursor".to_string()))
-            })
-            .transpose()?;
-        if let Some(ref page_cursor) = parsed_cursor {
-            if page_cursor.notebook_id.as_deref() != notebook_id
-                || page_cursor.filter != filter
-                || page_cursor.sort != sort
-                || page_cursor.tag_id.as_deref() != tag_id
-                || page_cursor.color != normalized_color
-            {
-                return Err(FlowixError::InvalidInput(
-                    "memo list cursor does not match the current query".to_string(),
-                ));
-            }
-        }
-
-        let start = parsed_cursor
-            .as_ref()
-            .map(|page_cursor| {
-                all.iter()
-                    .position(|memo| memo_is_after_cursor(memo, page_cursor, sort))
-                    .unwrap_or(all.len())
-            })
-            .unwrap_or(0);
-        let end = start.saturating_add(limit).min(all.len());
-        let memos = all[start..end].to_vec();
-        let has_more = end < all.len();
-        let next_cursor = if has_more {
-            memos.last().map(|memo| {
-                serde_json::to_string(&MemoListCursor {
-                    notebook_id: notebook_id.map(str::to_string),
-                    filter: filter.to_string(),
-                    sort: sort.to_string(),
-                    tag_id: tag_id.map(str::to_string),
-                    color: normalized_color.clone(),
-                    favorited: memo.favorited,
-                    sort_value: memo_sort_value(memo, sort),
-                    sort_text: memo_sort_text(memo, sort),
-                    sort_tiebreaker: memo_sort_tiebreaker(memo, sort),
-                    id: memo.id.clone(),
-                })
-                .expect("memo list cursor serialization cannot fail")
-            })
-        } else {
-            None
-        };
-
-        Ok(MemoPage {
-            memos,
-            next_cursor,
-            has_more,
-        })
-    }
-
-    pub fn list_all_memos(&mut self, notebook_id: Option<&str>) -> Vec<Memo> {
-        self.memo_file.read_all_memos_for_notebook_id(notebook_id)
-    }
-
-    pub fn memo_metadata(&mut self, id_or_filename: &str) -> Result<Memo, FlowixError> {
-        let resolved = self.resolve_memo(id_or_filename)?;
-        Ok(MemoFile::index_entry_to_memo(&resolved.entry))
-    }
-
-    pub fn get_memo(&mut self, id_or_filename: &str) -> Result<MemoDocument, FlowixError> {
-        let resolved = self.resolve_memo(id_or_filename)?;
-        let body = std::fs::read_to_string(&resolved.path).map_err(|error| {
-            if error.kind() == std::io::ErrorKind::NotFound {
-                FlowixError::NotFound(format!(
-                    "note `{}` is indexed but its Markdown file is missing",
-                    resolved.id
-                ))
-            } else {
-                FlowixError::Io(error)
-            }
-        })?;
-        Ok(MemoDocument {
-            entry: resolved.entry,
-            notebook: resolved.notebook,
-            path: resolved.path,
-            body,
-        })
-    }
-
-    pub fn create_memo_named_with_tag_in_directory(
-        &mut self,
-        notebook_key: Option<&str>,
-        parent_relative_path: Option<&str>,
-        title: &str,
-        body: &str,
-        tag: Option<&str>,
-    ) -> Result<CreatedMemo, FlowixError> {
-        let _write_guard = self.memo_file.acquire_cross_process_write_lock()?;
-        let notebook = match notebook_key {
-            Some(key) => Some(self.resolve_notebook(key)?),
-            None => None,
-        };
-        let memo = if let Some(notebook) = notebook.as_ref() {
-            match parent_relative_path.filter(|path| !path.is_empty()) {
-                Some(parent) => self.memo_file.create_memo_for_notebook_id_in_directory(
-                    &notebook.id,
-                    parent,
-                    title,
-                    body,
-                    tag,
-                ),
-                None => self
-                    .memo_file
-                    .create_memo_for_notebook_id(&notebook.id, title, body, tag),
-            }
-        } else {
-            if parent_relative_path.is_some_and(|path| !path.is_empty()) {
-                return Err(FlowixError::InvalidInput(
-                    "a parent directory requires an explicit notebook".into(),
-                ));
-            }
-            self.memo_file.create_memo(title, body, tag)
-        }
-        .map_err(FlowixError::Io)?;
-        // Explicit notebook creation already resolved the target config, and the
-        // storage operation returns the memo it just persisted. Avoid a global
-        // cross-notebook id lookup here: a missed/stale catalog lookup used to
-        // report failure after both the Markdown file and its local index row
-        // had already been created.
-        let notebook = match notebook {
-            Some(notebook) => notebook,
-            None => {
-                self.memo_file
-                    .resolve_memo_location(&memo.id)?
-                    .ok_or_else(|| {
-                        FlowixError::Internal(format!(
-                            "created note `{}` could not be resolved from the index",
-                            memo.id
-                        ))
-                    })?
-                    .notebook
-            }
-        };
-        let path = notebook_path_from_relative(&PathBuf::from(&notebook.path), &memo.relative_path)
-            .unwrap_or_else(|_| PathBuf::from(&notebook.path).join(&memo.filename));
-        Ok(CreatedMemo {
-            memo,
-            notebook,
-            path,
-        })
+        limit: Option<usize>,
+    ) -> Result<NotePage, FlowixError> {
+        self.list_notes_by_path_page(notebook, filter, sort, tag_id, color, cursor, limit)
     }
 
-    pub fn move_memo_to_directory(
+    pub fn search(
         &mut self,
-        id_or_path: &str,
-        notebook_key: &str,
-        parent_relative_path: &str,
-    ) -> Result<EditedMemo, FlowixError> {
-        self.move_memo_to_directory_checked(id_or_path, notebook_key, parent_relative_path, None)
+        notebook: &str,
+        query: &str,
+        limit: usize,
+    ) -> Result<Vec<NoteSearchHit>, FlowixError> {
+        self.search_with_tag_filter(notebook, query, None, limit)
     }
 
-    pub fn move_memo_to_directory_checked(
+    pub fn search_with_tag_filter(
         &mut self,
-        id_or_path: &str,
-        notebook_key: &str,
-        parent_relative_path: &str,
-        expected_cache_id: Option<&str>,
-    ) -> Result<EditedMemo, FlowixError> {
-        let _write_guard = self.memo_file.acquire_cross_process_write_lock()?;
-        let resolved = self.resolve_memo(id_or_path)?;
-        if expected_cache_id.is_some_and(|expected| expected != resolved.id) {
-            return Err(FlowixError::Conflict(
-                "document at path was replaced".into(),
-            ));
-        }
-        let notebook = self.resolve_notebook(notebook_key)?;
-        if resolved.notebook.id != notebook.id {
-            return Err(FlowixError::Conflict(
-                "memo does not belong to the selected notebook".into(),
-            ));
-        }
-        let (memo, _old_path, path) = self
+        notebook: &str,
+        query: &str,
+        tag_filter: Option<&str>,
+        limit: usize,
+    ) -> Result<Vec<NoteSearchHit>, FlowixError> {
+        let notebook = self.resolve_notebook(notebook)?;
+        Ok(self
             .memo_file
-            .move_memo_to_directory_for_notebook_id(
-                &notebook.id,
-                &resolved.id,
-                parent_relative_path,
-            )
-            .map_err(FlowixError::InvalidInput)?;
-        Ok(EditedMemo {
-            id: resolved.id,
-            memo: Some(memo),
-            path,
-            old_bytes: 0,
-            new_bytes: 0,
-            dry_run: false,
-        })
-    }
-
-    /// Resolve the path that the next named create is expected to use. Desktop uses
-    /// this immediately before creation to suppress its own filesystem watcher event.
-    pub fn preview_create_path(
-        &mut self,
-        notebook_key: Option<&str>,
-        title: &str,
-    ) -> Result<PathBuf, FlowixError> {
-        self.preview_create_path_in_directory(notebook_key, None, title)
+            .search_notes_with_tag_filter(&notebook.id, query, tag_filter, limit)?)
     }
 
-    pub fn preview_create_path_in_directory(
+    pub fn create(
         &mut self,
-        notebook_key: Option<&str>,
-        parent_relative_path: Option<&str>,
+        notebook: &str,
+        parent: Option<&str>,
         title: &str,
-    ) -> Result<PathBuf, FlowixError> {
-        let (base, notebook_id) = if let Some(key) = notebook_key {
-            let notebook = self.resolve_notebook(key)?;
-            (PathBuf::from(notebook.path), notebook.id)
-        } else {
-            (
-                self.memo_file.get_memo_base(),
-                self.memo_file.current_notebook_id_for_index(),
-            )
-        };
-        let create_base = match parent_relative_path.filter(|path| !path.is_empty()) {
-            Some(relative) => {
-                notebook_path_from_relative(&base, relative).map_err(FlowixError::InvalidInput)?
-            }
-            None => base,
-        };
-        let candidate = base_filename(title);
-        let occupied = self.memo_file.occupied_filenames_in_directory(
-            &notebook_id,
-            parent_relative_path.filter(|path| !path.is_empty()),
-        )?;
-        Ok(create_base.join(resolve_filename_conflict(
-            &create_base,
-            &candidate,
-            &occupied,
-        )))
+        content: &str,
+    ) -> Result<NoteDocument, FlowixError> {
+        self.create_note_by_path(notebook, parent, title, content)
     }
 
-    pub fn edit_memo_exact(
+    pub fn get(
         &mut self,
-        id_or_filename: &str,
-        old: &str,
-        new: &str,
-        dry_run: bool,
-    ) -> Result<EditedMemo, FlowixError> {
-        if old.is_empty() {
-            return Err(FlowixError::InvalidInput(
-                "edit: old_string cannot be empty".into(),
-            ));
-        }
-        let resolved = self.resolve_memo(id_or_filename)?;
-        let _file_guard = self.lock_resolved_memo(&resolved, "edit_memo_exact")?;
-        let locked = self.resolve_memo(id_or_filename)?;
-        if locked.id != resolved.id || locked.path != resolved.path {
-            return Err(FlowixError::Conflict("document moved while waiting for the file lock".into()));
-        }
-        let current = std::fs::read_to_string(&resolved.path)?;
-        let matches = current.matches(old).count();
-        if matches == 0 {
-            return Err(FlowixError::Conflict(format!(
-                "edit: old_string not found in `{}` (whitespace, indentation, and line endings must match)",
-                resolved.id
-            )));
-        }
-        if matches > 1 {
-            return Err(FlowixError::Conflict(format!(
-                "edit: old_string matched {matches} times in `{}`; provide more surrounding context to make it unique",
-                resolved.id
-            )));
-        }
-
-        if dry_run {
-            return Ok(EditedMemo {
-                id: resolved.id,
-                memo: None,
-                path: resolved.path,
-                old_bytes: old.len(),
-                new_bytes: new.len(),
-                dry_run: true,
-            });
-        }
-
-        let body = current.replacen(old, new, 1);
-        let memo = self
-            .memo_file
-            .write_memo_preserving_filename_under_file_lock(&resolved.id, &body, &_file_guard)?;
-        let path = notebook_path_from_relative(
-            &PathBuf::from(&resolved.notebook.path),
-            &memo.relative_path,
-        )
-        .unwrap_or_else(|_| PathBuf::from(&resolved.notebook.path).join(&memo.filename));
-        Ok(EditedMemo {
-            id: resolved.id,
-            memo: Some(memo),
-            path,
-            old_bytes: old.len(),
-            new_bytes: new.len(),
-            dry_run: false,
-        })
+        notebook: &str,
+        relative_path: &str,
+    ) -> Result<NoteDocument, FlowixError> {
+        self.get_note_by_path(notebook, relative_path)
     }
 
-    pub fn replace_memo(
+    pub fn save(
         &mut self,
-        id_or_filename: &str,
-        body: &str,
-    ) -> Result<EditedMemo, FlowixError> {
-        if body.trim().is_empty() {
-            return Err(FlowixError::InvalidInput(
-                "empty body, note not modified".into(),
-            ));
-        }
-        self.save_memo(id_or_filename, body)
+        notebook: &str,
+        relative_path: &str,
+        content: &str,
+        expected_content: Option<&str>,
+    ) -> Result<NoteSaveOutcome, FlowixError> {
+        self.save_note_by_path(notebook, relative_path, content, expected_content)
     }
 
-    /// Save Desktop editor content, including an intentionally empty document.
-    pub fn save_memo(
+    pub fn rename(
         &mut self,
-        id_or_filename: &str,
-        body: &str,
-    ) -> Result<EditedMemo, FlowixError> {
-        self.save_memo_with_validation(id_or_filename, body, |_, _| Ok(()))
+        notebook: &str,
+        relative_path: &str,
+        title: &str,
+        expected_content: Option<&str>,
+    ) -> Result<NoteDocument, FlowixError> {
+        self.rename_note_by_path(notebook, relative_path, title, expected_content)
     }
 
-    pub fn save_memo_with_validation(
+    pub fn move_to(
         &mut self,
-        id_or_filename: &str,
-        body: &str,
-        validate: impl FnOnce(&ResolvedMemo, &str) -> Result<(), FlowixError>,
-    ) -> Result<EditedMemo, FlowixError> {
-        self.save_memo_with_snapshot(id_or_filename, body, validate)
-            .map(|(edited, _)| edited)
+        notebook: &str,
+        relative_path: &str,
+        parent: &str,
+    ) -> Result<NoteDocument, FlowixError> {
+        self.move_note_by_path(notebook, relative_path, parent)
     }
 
-    pub fn save_memo_with_snapshot(
-        &mut self,
-        id_or_filename: &str,
-        body: &str,
-        validate: impl FnOnce(&ResolvedMemo, &str) -> Result<(), FlowixError>,
-    ) -> Result<(EditedMemo, String), FlowixError> {
-        self.save_memo_with_receipt(id_or_filename, body, validate)
-            .map(|receipt| (receipt.edited, receipt.content))
+    pub fn delete(&mut self, notebook: &str, relative_path: &str) -> Result<bool, FlowixError> {
+        self.delete_note_by_path(notebook, relative_path)
     }
 
-    pub fn save_memo_with_receipt(
-        &mut self,
-        id_or_filename: &str,
-        body: &str,
-        validate: impl FnOnce(&ResolvedMemo, &str) -> Result<(), FlowixError>,
-    ) -> Result<MemoSaveReceipt, FlowixError> {
-        use sha2::{Digest, Sha256};
-        let resolved = self.resolve_memo(id_or_filename)?;
-        let _file_guard = self.lock_resolved_memo(&resolved, "save_memo_with_receipt")?;
-        let locked = self.resolve_memo(id_or_filename)?;
-        if locked.id != resolved.id || locked.path != resolved.path {
-            return Err(FlowixError::Conflict("document moved while waiting for the file lock".into()));
-        }
-        let current = std::fs::read_to_string(&resolved.path)?;
-        validate(&resolved, &current)?;
-        let old_bytes = current.len();
-        let memo = self
-            .memo_file
-            .write_memo_preserving_filename_under_file_lock(&resolved.id, body, &_file_guard)?;
-        let path = notebook_path_from_relative(
-            &PathBuf::from(&resolved.notebook.path),
-            &memo.relative_path,
-        )
-        .unwrap_or_else(|_| PathBuf::from(&resolved.notebook.path).join(&memo.filename));
-        let content = std::fs::read_to_string(&path)?;
-        let content_hash = format!("{:x}", Sha256::digest(content.as_bytes()));
-        let commit = match self.memo_file.commit_note_content_revision(
-            &resolved.notebook.id,
-            &memo.relative_path,
-            &content_hash,
-            &uuid::Uuid::new_v4().to_string(),
-        ) {
-            Ok(commit) => Some(commit.state),
-            Err(error) => {
-                tracing::warn!("Memo saved but revision persistence failed: {error}");
-                None
+    pub fn delete_checked(&mut self, notebook: &str, relative_path: &str, expected_content: &str) -> Result<bool, FlowixError> {
+        let notebook = self.resolve_notebook(notebook)?;
+        match self.memo_file.delete_note_by_path_checked(&notebook.id, relative_path, Some(expected_content)) {
+            Ok(removed) => Ok(removed),
+            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                Err(FlowixError::Conflict("note changed before delete".into()))
             }
-        };
-        Ok(MemoSaveReceipt {
-            edited: EditedMemo {
-                id: resolved.id,
-                memo: Some(memo),
-                path,
-                old_bytes,
-                new_bytes: content.len(),
-                dry_run: false,
-            },
-            content,
-            notebook_id: resolved.notebook.id,
-            commit,
-        })
-    }
-
-    pub fn save_memo_preserving_filename(
-        &mut self,
-        id_or_filename: &str,
-        body: &str,
-    ) -> Result<EditedMemo, FlowixError> {
-        let resolved = self.resolve_memo(id_or_filename)?;
-        let _file_guard = self.lock_resolved_memo(&resolved, "save_memo_preserving_filename")?;
-        let locked = self.resolve_memo(id_or_filename)?;
-        if locked.id != resolved.id || locked.path != resolved.path {
-            return Err(FlowixError::Conflict("document moved while waiting for the file lock".into()));
+            Err(error) => Err(FlowixError::Io(error)),
         }
-        let old_bytes = std::fs::metadata(&resolved.path)
-            .map(|metadata| metadata.len() as usize)
-            .unwrap_or(0);
-        let memo = self
-            .memo_file
-            .write_memo_preserving_filename_under_file_lock(&resolved.id, body, &_file_guard)?;
-        let path = notebook_path_from_relative(
-            &PathBuf::from(&resolved.notebook.path),
-            &memo.relative_path,
-        )
-        .unwrap_or_else(|_| PathBuf::from(&resolved.notebook.path).join(&memo.filename));
-        Ok(EditedMemo {
-            id: resolved.id,
-            memo: Some(memo),
-            path,
-            old_bytes,
-            new_bytes: body.len(),
-            dry_run: false,
-        })
     }
+}
 
-    pub fn rename_memo(
-        &mut self,
-        id_or_filename: &str,
-        new_title: &str,
-    ) -> Result<EditedMemo, FlowixError> {
-        self.rename_memo_with_validation(id_or_filename, new_title, |_| Ok(()))
-    }
+fn path_note_filename(relative_path: &str) -> &str {
+    relative_path.rsplit('/').next().unwrap_or(relative_path)
+}
 
-    pub fn rename_memo_with_validation(
-        &mut self,
-        id_or_filename: &str,
-        new_title: &str,
-        validate: impl FnOnce(&ResolvedMemo) -> Result<(), FlowixError>,
-    ) -> Result<EditedMemo, FlowixError> {
-        let _write_guard = self.memo_file.acquire_cross_process_write_lock()?;
-        let resolved = self.resolve_memo(id_or_filename)?;
-        validate(&resolved)?;
-        let memo = self.memo_file.rename_memo(&resolved.id, new_title)?;
-        let path = notebook_path_from_relative(
-            &PathBuf::from(&resolved.notebook.path),
-            &memo.relative_path,
-        )
-        .unwrap_or_else(|_| PathBuf::from(&resolved.notebook.path).join(&memo.filename));
-        Ok(EditedMemo {
-            id: resolved.id,
-            memo: Some(memo),
-            path,
-            old_bytes: 0,
-            new_bytes: 0,
-            dry_run: false,
-        })
+fn note_sort_value(note: &NoteEntry, sort: &str) -> i64 {
+    if sort == "updatedAt" {
+        note.updated_at
+    } else {
+        note.created_at
     }
+}
 
-    pub fn sync_memo_metadata(&mut self, memo: &Memo) -> Result<(), FlowixError> {
-        let _write_guard = self.memo_file.acquire_cross_process_write_lock()?;
-        self.memo_file.sync_metadata_only_global(memo)?;
-        Ok(())
-    }
-
-    pub fn delete_memo(&mut self, id_or_filename: &str) -> Result<DeletedMemo, FlowixError> {
-        self.delete_memo_checked(id_or_filename, None)
-    }
-
-    pub fn delete_memo_checked(
-        &mut self,
-        id_or_filename: &str,
-        expected_cache_id: Option<&str>,
-    ) -> Result<DeletedMemo, FlowixError> {
-        let _write_guard = self.memo_file.acquire_cross_process_write_lock()?;
-        let resolved = self.resolve_memo(id_or_filename)?;
-        if expected_cache_id.is_some_and(|expected| expected != resolved.id) {
-            return Err(FlowixError::Conflict(
-                "document at path was replaced".into(),
-            ));
-        }
-        let file_removed = self.memo_file.delete_memo_result_global(&resolved.id)?;
-        Ok(DeletedMemo {
-            id: resolved.id,
-            path: resolved.path,
-            file_removed,
-        })
-    }
-
-    pub fn tag_usage_summary(
-        &mut self,
-        notebook_id: Option<&str>,
-    ) -> Result<TagUsageSummary, FlowixError> {
-        self.memo_file
-            .read_tag_usage_summary_for_notebook_id(notebook_id)
-            .map_err(FlowixError::Io)
-    }
-
-    pub fn resolve_notebook(&mut self, key: &str) -> Result<NotebookConfig, FlowixError> {
-        let notebooks = self.list_notebooks()?;
-        notebooks
-            .iter()
-            .find(|config| config.id == key)
-            .or_else(|| notebooks.iter().find(|config| config.name == key))
-            .cloned()
-            .ok_or_else(|| FlowixError::NotFound(format!("notebook `{key}` not found")))
-    }
-
-    pub fn resolve_memo(&mut self, id_or_filename: &str) -> Result<ResolvedMemo, FlowixError> {
-        let requested = PathBuf::from(id_or_filename);
-        if requested.is_absolute() {
-            // Indexed ghosts have no file to canonicalize. Preserve exact path
-            // lookup so they can be removed without consulting a memo ID.
-            let requested = if requested.exists() {
-                dunce::canonicalize(&requested)?
-            } else {
-                requested
-            };
-            for notebook in self.list_notebooks()? {
-                let base = PathBuf::from(&notebook.path);
-                let canonical_base = if requested.exists() {
-                    dunce::canonicalize(&base).unwrap_or(base.clone())
-                } else {
-                    base.clone()
-                };
-                let Ok(relative) =
-                    crate::memo_file::notebook_relative_path(&canonical_base, &requested)
-                else {
-                    continue;
-                };
-                let list = self
-                    .memo_file
-                    .read_index_for_notebook_id(Some(&notebook.id))?
-                    .unwrap_or_default();
-                if let Some(entry) = list
-                    .memos
-                    .into_iter()
-                    .find(|entry| entry.relative_path == relative)
-                {
-                    return Ok(ResolvedMemo {
-                        id: entry.id.clone(),
-                        entry,
-                        notebook,
-                        path: requested,
-                    });
-                }
-            }
-            return Err(FlowixError::NotFound(format!(
-                "indexed note path {id_or_filename} not found"
-            )));
-        }
-        if let Some(location) = self.memo_file.resolve_memo_location(id_or_filename)? {
-            let path = notebook_path_from_relative(
-                &PathBuf::from(&location.notebook.path),
-                &location.memo.relative_path,
-            )
-            .unwrap_or_else(|_| {
-                PathBuf::from(&location.notebook.path).join(&location.memo.filename)
-            });
-            return Ok(ResolvedMemo {
-                id: location.memo.id.clone(),
-                entry: location.memo,
-                notebook: location.notebook,
-                path,
-            });
-        }
-
-        let wanted = if id_or_filename.ends_with(".md") {
-            id_or_filename.to_string()
-        } else {
-            format!("{id_or_filename}.md")
-        };
-        for notebook in self.list_notebooks()? {
-            let list = self
-                .memo_file
-                .read_index_for_notebook_id(Some(&notebook.id))?
-                .unwrap_or_default();
-            if let Some(entry) = list
-                .memos
-                .into_iter()
-                .find(|entry| entry.relative_path == wanted || entry.filename == wanted)
-            {
-                let path = notebook_path_from_relative(
-                    &PathBuf::from(&notebook.path),
-                    &entry.relative_path,
-                )
-                .unwrap_or_else(|_| PathBuf::from(&notebook.path).join(&entry.filename));
-                return Ok(ResolvedMemo {
-                    id: entry.id.clone(),
-                    entry,
-                    notebook,
-                    path,
-                });
-            }
-        }
-        Err(FlowixError::NotFound(format!(
-            "note `{id_or_filename}` not found"
-        )))
-    }
-
-    /// A title request may carry the path from before another view renamed
-    /// this memo. Recover only when its stable memo ID and expected filename
-    /// still identify the current indexed entry.
-    pub fn resolve_memo_for_title_rename(
-        &mut self,
-        requested_path: &str,
-        expected_id: Option<&str>,
-        expected_filename: Option<&str>,
-    ) -> Result<ResolvedMemo, FlowixError> {
-        let resolved = match self.resolve_memo(requested_path) {
-            Ok(resolved) => resolved,
-            Err(FlowixError::NotFound(_))
-                if expected_id.is_some() && expected_filename.is_some() =>
-            {
-                self.resolve_memo(expected_id.unwrap())?
-            }
-            Err(error) => return Err(error),
-        };
-        if expected_id.is_some_and(|id| id != resolved.id) {
-            return Err(FlowixError::Conflict(
-                "document at path was replaced".into(),
-            ));
-        }
-        if expected_filename.is_some_and(|name| name != resolved.entry.filename) {
-            return Err(FlowixError::Conflict(
-                "memo filename changed before rename".into(),
-            ));
-        }
-        Ok(resolved)
-    }
-}
-
-impl<'a> NoteService<'a> {
-    pub fn list(&mut self, notebook: &str) -> Result<Vec<NoteEntry>, FlowixError> {
-        self.list_notes_by_path(notebook)
-    }
-
-    pub fn list_page(
-        &mut self,
-        notebook: &str,
-        filter: &str,
-        sort: &str,
-        tag_id: Option<&str>,
-        color: Option<&str>,
-        cursor: Option<&str>,
-        limit: Option<usize>,
-    ) -> Result<NotePage, FlowixError> {
-        self.list_notes_by_path_page(notebook, filter, sort, tag_id, color, cursor, limit)
-    }
-
-    pub fn search(
-        &mut self,
-        notebook: &str,
-        query: &str,
-        limit: usize,
-    ) -> Result<Vec<NoteSearchHit>, FlowixError> {
-        self.search_with_tag_filter(notebook, query, None, limit)
-    }
-
-    pub fn search_with_tag_filter(
-        &mut self,
-        notebook: &str,
-        query: &str,
-        tag_filter: Option<&str>,
-        limit: usize,
-    ) -> Result<Vec<NoteSearchHit>, FlowixError> {
-        let notebook = self.resolve_notebook(notebook)?;
-        Ok(self
-            .memo_file
-            .search_notes_with_tag_filter(&notebook.id, query, tag_filter, limit)?)
-    }
-
-    pub fn create(
-        &mut self,
-        notebook: &str,
-        parent: Option<&str>,
-        title: &str,
-        content: &str,
-    ) -> Result<NoteDocument, FlowixError> {
-        self.create_note_by_path(notebook, parent, title, content)
-    }
-
-    pub fn get(
-        &mut self,
-        notebook: &str,
-        relative_path: &str,
-    ) -> Result<NoteDocument, FlowixError> {
-        self.get_note_by_path(notebook, relative_path)
-    }
-
-    pub fn save(
-        &mut self,
-        notebook: &str,
-        relative_path: &str,
-        content: &str,
-        expected_content: Option<&str>,
-    ) -> Result<NoteSaveOutcome, FlowixError> {
-        self.save_note_by_path(notebook, relative_path, content, expected_content)
-    }
-
-    pub fn rename(
-        &mut self,
-        notebook: &str,
-        relative_path: &str,
-        title: &str,
-        expected_content: Option<&str>,
-    ) -> Result<NoteDocument, FlowixError> {
-        self.rename_note_by_path(notebook, relative_path, title, expected_content)
-    }
-
-    pub fn move_to(
-        &mut self,
-        notebook: &str,
-        relative_path: &str,
-        parent: &str,
-    ) -> Result<NoteDocument, FlowixError> {
-        self.move_note_by_path(notebook, relative_path, parent)
-    }
-
-    pub fn delete(&mut self, notebook: &str, relative_path: &str) -> Result<bool, FlowixError> {
-        self.delete_note_by_path(notebook, relative_path)
-    }
-
-    pub fn delete_checked(&mut self, notebook: &str, relative_path: &str, expected_content: &str) -> Result<bool, FlowixError> {
-        let notebook = self.resolve_notebook(notebook)?;
-        match self.memo_file.delete_note_by_path_checked(&notebook.id, relative_path, Some(expected_content)) {
-            Ok(removed) => Ok(removed),
-            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
-                Err(FlowixError::Conflict("note changed before delete".into()))
-            }
-            Err(error) => Err(FlowixError::Io(error)),
-        }
-    }
-}
-
-fn memo_sort_value(memo: &Memo, sort: &str) -> i64 {
-    if sort == "updatedAt" {
-        memo.updated_at
-    } else {
-        memo.created_at
-    }
-}
-
-fn memo_sort_text(memo: &Memo, sort: &str) -> Option<String> {
-    match sort {
-        "filenameAsc" | "filenameDesc" => Some(memo.filename.to_lowercase()),
-        _ => None,
-    }
-}
-
-fn memo_sort_tiebreaker(memo: &Memo, sort: &str) -> Option<String> {
-    match sort {
-        "filenameAsc" | "filenameDesc" => Some(memo.filename.clone()),
-        _ => None,
-    }
-}
-
-fn memo_color_name(color: MemoColor) -> &'static str {
-    match color {
-        MemoColor::Red => "red",
-        MemoColor::Orange => "orange",
-        MemoColor::Yellow => "yellow",
-        MemoColor::Green => "green",
-        MemoColor::Cyan => "cyan",
-        MemoColor::Blue => "blue",
-        MemoColor::Gray => "gray",
-    }
-}
-
-fn memo_is_after_cursor(memo: &Memo, cursor: &MemoListCursor, sort: &str) -> bool {
-    if memo.favorited != cursor.favorited {
-        return memo.favorited < cursor.favorited;
-    }
-
-    if sort == "filenameAsc" || sort == "filenameDesc" {
-        let memo_key = memo.filename.to_lowercase();
-        let cursor_key = cursor.sort_text.as_deref().unwrap_or_default();
-        let filename_order = memo_key
-            .as_str()
-            .cmp(cursor_key)
-            .then_with(|| {
-                memo.filename
-                    .as_str()
-                    .cmp(cursor.sort_tiebreaker.as_deref().unwrap_or_default())
-            })
-            .then_with(|| memo.id.as_str().cmp(cursor.id.as_str()));
-        return if sort == "filenameDesc" {
-            filename_order == Ordering::Less
-        } else {
-            filename_order == Ordering::Greater
-        };
-    }
-
-    // The date list is sorted descending, so a lower key is later.
-    memo_sort_value(memo, sort) < cursor.sort_value
-        || (memo_sort_value(memo, sort) == cursor.sort_value && memo.id < cursor.id)
-}
-
-fn path_note_filename(relative_path: &str) -> &str {
-    relative_path.rsplit('/').next().unwrap_or(relative_path)
-}
-
-fn note_sort_value(note: &NoteEntry, sort: &str) -> i64 {
-    if sort == "updatedAt" {
-        note.updated_at
-    } else {
-        note.created_at
-    }
-}
-
-fn note_sort_text(note: &NoteEntry, sort: &str) -> Option<String> {
-    matches!(sort, "filenameAsc" | "filenameDesc")
-        .then(|| path_note_filename(&note.relative_path).to_lowercase())
-}
+fn note_sort_text(note: &NoteEntry, sort: &str) -> Option<String> {
+    matches!(sort, "filenameAsc" | "filenameDesc")
+        .then(|| path_note_filename(&note.relative_path).to_lowercase())
+}
 
 fn note_sort_tiebreaker(note: &NoteEntry, sort: &str) -> Option<String> {
     matches!(sort, "filenameAsc" | "filenameDesc")
@@ -1482,11 +564,6 @@ mod tests {
                 )
                 .unwrap();
         }
-        // Path creation does not write any memo-ID projection.
-        assert!(store
-            .list_note_entries_with_legacy_ids("work")
-            .unwrap()
-            .is_none());
         assert_eq!(
             store.read_note_entries("work").unwrap_err().kind(),
             std::io::ErrorKind::WouldBlock,
@@ -1611,681 +688,5 @@ mod tests {
         assert_eq!(paths, ["Alpha.md", "Beta.md", "Gamma.md"]);
     }
 
-    #[test]
-    fn path_delete_guards_replacement_and_removes_missing_index_entry() {
-        let (_temp, store) = service_fixture();
-        let mut service = MemoService::new(&store);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Plain\n", None).unwrap();
-        let path = created.path.to_string_lossy().into_owned();
-        assert!(service
-            .delete_memo_checked(&path, Some("anotherid"))
-            .is_err());
-        assert!(created.path.exists());
-        std::fs::remove_file(&created.path).unwrap();
-        assert!(
-            service
-                .delete_memo_checked(&path, Some(&created.memo.id))
-                .unwrap()
-                .file_removed
-        );
-        assert!(service.resolve_memo(&path).is_err());
-    }
-
-    #[test]
-    fn path_save_and_rename_need_no_frontmatter_identity() {
-        let (_temp, store) = service_fixture();
-        let mut service = MemoService::new(&store);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Plain\nbody\n", None).unwrap();
-        assert_eq!(
-            std::fs::read_to_string(&created.path).unwrap(),
-            "# Plain\nbody\n"
-        );
-        let old = created.path.to_string_lossy().into_owned();
-        let renamed = service.rename_memo(&old, "Renamed").unwrap();
-        assert!(!created.path.exists());
-        assert!(service.save_memo(&old, "stale overwrite").is_err());
-        assert!(!created.path.exists(), "stale path must never be recreated");
-        let content = "---\nflowix_colors: [blue]\n---\n# Plain\nupdated\n";
-        service
-            .save_memo(&renamed.path.to_string_lossy(), content)
-            .unwrap();
-        assert_eq!(std::fs::read_to_string(&renamed.path).unwrap(), content);
-        let memo = store.read_memo_global(&created.memo.id).unwrap();
-        assert_eq!(memo.colors.len(), 1);
-        assert_eq!(memo.relative_path, "Renamed.md");
-    }
-
-    #[test]
-    fn title_rename_recovers_a_stale_path_only_with_matching_id_and_filename() {
-        let (_temp, store) = service_fixture();
-        let mut service = MemoService::new(&store);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Plain\n", None).unwrap();
-        let original = created.path.to_string_lossy().into_owned();
-        let id = created.memo.id;
-        let renamed = service.rename_memo(&original, "Second").unwrap();
-        let renamed_filename = renamed.memo.as_ref().unwrap().filename.clone();
-        let current = service
-            .resolve_memo_for_title_rename(&original, Some(&id), Some(&renamed_filename))
-            .unwrap();
-        assert_eq!(current.id, id);
-        assert_eq!(current.path, renamed.path);
-        let third = service
-            .rename_memo_with_validation(&current.id, "Third", |_| Ok(()))
-            .unwrap();
-        assert!(third.path.exists());
-        assert!(!renamed.path.exists());
-        assert!(service
-            .resolve_memo_for_title_rename(&original, Some(&id), Some("Second.md"))
-            .is_err());
-        assert!(service
-            .resolve_memo_for_title_rename(&original, Some("wrong-id"), Some("Third.md"))
-            .is_err());
-        assert!(service
-            .resolve_memo_for_title_rename(&original, None, None)
-            .is_err());
-        std::fs::write(&original, "# Replacement\n").unwrap();
-        let replacement = store
-            .register_existing_file_for_notebook_id("work", &PathBuf::from(&original))
-            .unwrap();
-        assert_ne!(replacement.id, id);
-        assert!(service
-            .resolve_memo_for_title_rename(&original, Some(&id), Some("Third.md"))
-            .is_err());
-    }
-
-    #[test]
-    fn directory_move_rebases_all_children_without_touching_markdown() {
-        let (temp, store) = service_fixture();
-        let base = temp.path().join("notes");
-        let source = base.join("docs");
-        std::fs::create_dir_all(source.join("nested")).unwrap();
-        let content = "---\nflowix_colors: [green]\n---\n# Body\n";
-        let file = source.join("nested/One.md");
-        std::fs::write(&file, content).unwrap();
-        let original = store
-            .register_existing_file_for_notebook_id("work", &file)
-            .unwrap();
-        let target = base.join("manual");
-        let changes = store.rename_indexed_path(&source, &target).unwrap();
-        assert_eq!(changes.len(), 1);
-        let memo = store.read_memo_global(&original.id).unwrap();
-        assert_eq!(memo.relative_path, "manual/nested/One.md");
-        assert_eq!(
-            std::fs::read_to_string(target.join("nested/One.md")).unwrap(),
-            content
-        );
-        assert!(MemoService::new(&store)
-            .save_memo(&file.to_string_lossy(), "stale")
-            .is_err());
-        assert!(!source.exists());
-    }
-
-    #[test]
-    fn path_resolution_never_falls_back_to_same_filename() {
-        let (temp, store) = service_fixture();
-        let mut service = MemoService::new(&store);
-        service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Same\noriginal", None).unwrap();
-        let other = temp.path().join("outside/Same.md");
-        std::fs::create_dir_all(other.parent().unwrap()).unwrap();
-        std::fs::write(&other, "other").unwrap();
-        assert!(service
-            .save_memo(&other.to_string_lossy(), "wrong")
-            .is_err());
-        assert_eq!(std::fs::read_to_string(other).unwrap(), "other");
-    }
-
-    #[test]
-    fn save_snapshot_does_not_change_when_a_later_writer_saves() {
-        let (_directory, store) = service_fixture();
-        let mut service = MemoService::new(&store);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Note\noriginal\n", None).unwrap();
-        let (edited, snapshot) = service
-            .save_memo_with_snapshot(&created.memo.id, "# Note\nfirst\n", |_, _| Ok(()))
-            .unwrap();
-        service
-            .save_memo(&created.memo.id, "# Note\nsecond\n")
-            .unwrap();
-        assert!(snapshot.ends_with("# Note\nfirst\n"));
-        assert!(std::fs::read_to_string(edited.path)
-            .unwrap()
-            .ends_with("# Note\nsecond\n"));
-    }
 
-    #[test]
-    fn save_receipt_binds_revision_version_and_content_before_the_next_writer() {
-        use sha2::{Digest, Sha256};
-        let (_directory, store) = service_fixture();
-        let mut service = MemoService::new(&store);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Note\noriginal\n", None).unwrap();
-        let first = service
-            .save_memo_with_receipt(&created.memo.id, "# Note\nfirst\n", |_, _| Ok(()))
-            .unwrap();
-        let first_commit = first.commit.unwrap();
-        let second = service
-            .save_memo_with_receipt(&created.memo.id, "# Note\nsecond\n", |_, _| Ok(()))
-            .unwrap();
-        let second_commit = second.commit.unwrap();
-        assert_eq!(
-            first_commit.content_hash,
-            format!("{:x}", Sha256::digest(first.content.as_bytes()))
-        );
-        assert_eq!(
-            second_commit.content_hash,
-            format!("{:x}", Sha256::digest(second.content.as_bytes()))
-        );
-        assert!(second_commit.revision > first_commit.revision);
-        assert_ne!(first_commit.change_id, second_commit.change_id);
-        assert_eq!(first.notebook_id, "work");
-    }
-
-    #[test]
-    fn rejected_save_preserves_file_name_content_and_index() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        let created = service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Original\n\nimportant\n", None)
-            .unwrap();
-        let original = std::fs::read_to_string(&created.path).unwrap();
-        let before = service.get_memo(&created.memo.id).unwrap();
-        let result = service.save_memo_with_validation(
-            &created.memo.id,
-            "# Renamed\n\nreplacement\n",
-            |_, _| Err(FlowixError::Conflict("stale snapshot".to_string())),
-        );
-        assert!(matches!(result, Err(FlowixError::Conflict(_))));
-        assert_eq!(std::fs::read_to_string(&created.path).unwrap(), original);
-        let after = service.get_memo(&created.memo.id).unwrap();
-        assert_eq!(after.entry.filename, before.entry.filename);
-        assert_eq!(after.entry.updated_at, before.entry.updated_at);
-        assert!(!created.path.parent().unwrap().join("Renamed.md").exists());
-    }
-
-    #[test]
-    fn validation_holds_the_file_lock_and_allows_another_file() {
-        let (temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Note\nold\n", None).unwrap();
-        let other = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Other\nold\n", None).unwrap();
-        let lock_path = temp.path().join("config/.memo-write.lock");
-        let result = service
-            .save_memo_with_validation(&created.memo.id, "# Note\nnew\n", |_, current| {
-                assert!(current.contains("old"));
-                let probe = std::fs::OpenOptions::new()
-                    .read(true)
-                    .write(true)
-                    .open(&lock_path)
-                    .unwrap();
-                assert!(fs2::FileExt::try_lock_exclusive(&probe).is_err());
-                let _other_guard = memo_file.operation_locks().file_write(
-                    "work", other.path.parent().unwrap(), &other.path,
-                    crate::memo_file::FileLockIntent::Existing, "other_file_probe",
-                ).unwrap();
-                Ok(())
-            })
-            .unwrap();
-        assert!(std::fs::read_to_string(result.path)
-            .unwrap()
-            .contains("new"));
-    }
-
-    #[test]
-    fn concurrent_memo_saves_with_one_expected_snapshot_have_one_winner() {
-        use std::sync::{Arc, Barrier};
-        let (temp, memo_file) = service_fixture();
-        let created = MemoService::new(&memo_file)
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Note\nold\n", None)
-            .unwrap();
-        let expected = std::fs::read_to_string(&created.path).unwrap();
-        let barrier = Arc::new(Barrier::new(2));
-        let workers: Vec<_> = ["# Note\nfirst\n", "# Note\nsecond\n"]
-            .into_iter()
-            .map(|content| {
-                let store = MemoFile::new(temp.path().join("config"));
-                let id = created.memo.id.clone();
-                let expected = expected.clone();
-                let barrier = barrier.clone();
-                std::thread::spawn(move || {
-                    barrier.wait();
-                    (
-                        MemoService::new(&store).save_memo_with_validation(
-                            &id,
-                            content,
-                            |_, current| {
-                                if current != expected {
-                                    return Err(FlowixError::Conflict("stale snapshot".into()));
-                                }
-                                Ok(())
-                            },
-                        ),
-                        content,
-                    )
-                })
-            })
-            .collect();
-        let results: Vec<_> = workers
-            .into_iter()
-            .map(|worker| worker.join().unwrap())
-            .collect();
-        assert_eq!(
-            results.iter().filter(|(result, _)| result.is_ok()).count(),
-            1
-        );
-        assert_eq!(
-            results
-                .iter()
-                .filter(|(result, _)| matches!(result, Err(FlowixError::Conflict(_))))
-                .count(),
-            1
-        );
-        let winner = results.iter().find(|(result, _)| result.is_ok()).unwrap().1;
-        let stored = std::fs::read_to_string(&created.path).unwrap();
-        assert!(stored.ends_with(winner));
-    }
-
-    #[test]
-    fn service_covers_memo_lifecycle_and_filename_resolution() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        let created = service
-            .create_memo_named_with_tag_in_directory(Some("Work Notes"), None, "Untitled", "# Service note\n\nold text\n", None)
-            .unwrap();
-        assert!(created.path.exists());
-
-        let document = service.get_memo(&created.memo.id).unwrap();
-        assert_eq!(document.entry.id, created.memo.id);
-        assert!(document.body.contains("old text"));
-
-        let edited = service
-            .edit_memo_exact(&created.memo.id, "old text", "new text", false)
-            .unwrap();
-        assert!(!edited.dry_run);
-        assert!(service
-            .get_memo(&created.memo.id)
-            .unwrap()
-            .body
-            .contains("new text"));
-
-        let deleted = service.delete_memo(&created.memo.id).unwrap();
-        assert!(deleted.file_removed);
-        assert!(!deleted.path.exists());
-    }
-
-    #[test]
-    fn create_memo_keeps_filename_independent_from_markdown_first_line() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        let created = service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Body heading\n\ncontent", None)
-            .unwrap();
-
-        assert!(created.memo.filename.starts_with("Untitled"));
-        assert!(!created.memo.filename.starts_with("Body heading"));
-        assert!(service
-            .get_memo(&created.memo.id)
-            .unwrap()
-            .body
-            .contains("# Body heading"));
-    }
-
-    #[test]
-    fn creates_memo_in_existing_notebook_subdirectory() {
-        let (temp, memo_file) = service_fixture();
-        std::fs::create_dir_all(temp.path().join("notes/projects/alpha")).unwrap();
-        let mut service = MemoService::new(&memo_file);
-
-        let created = service
-            .create_memo_named_with_tag_in_directory(
-                Some("work"),
-                Some("projects/alpha"),
-                "Nested",
-                "",
-                None,
-            )
-            .unwrap();
-
-        assert_eq!(created.memo.relative_path, "projects/alpha/Nested.md");
-        assert_eq!(
-            created.path,
-            temp.path().join("notes/projects/alpha/Nested.md")
-        );
-        assert!(created.path.is_file());
-        assert_eq!(
-            service
-                .resolve_memo(&created.memo.id)
-                .unwrap()
-                .entry
-                .relative_path,
-            "projects/alpha/Nested.md"
-        );
-    }
-
-    #[test]
-    fn rejects_create_parent_outside_notebook() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-
-        let error = service
-            .create_memo_named_with_tag_in_directory(
-                Some("work"),
-                Some("../outside"),
-                "Escaped",
-                "",
-                None,
-            )
-            .unwrap_err();
-
-        assert!(matches!(error, FlowixError::Io(ref source)
-            if source.kind() == std::io::ErrorKind::InvalidInput));
-    }
-
-    #[test]
-    fn moves_memo_to_directory_and_updates_index_path() {
-        let (temp, memo_file) = service_fixture();
-        std::fs::create_dir_all(temp.path().join("notes/projects")).unwrap();
-        let mut service = MemoService::new(&memo_file);
-        let created = service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Move me\n", None).unwrap();
-        let old_path = created.path.clone();
-
-        let moved = service
-            .move_memo_to_directory(&created.memo.id, "work", "projects")
-            .unwrap();
-
-        assert_eq!(moved.path, temp.path().join("notes/projects/Untitled.md"));
-        assert!(!old_path.exists());
-        assert!(moved.path.exists());
-        assert_eq!(moved.memo.unwrap().relative_path, "projects/Untitled.md");
-    }
-
-    #[test]
-    fn memo_pages_are_stable_and_do_not_repeat_items() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        for index in 0..5 {
-            service
-                .create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", &format!("# Page note {index}\n"), None)
-                .unwrap();
-        }
-
-        let first = service
-            .list_memos_filtered_page(Some("work"), "all", "createdAt", None, None, None, Some(2))
-            .unwrap();
-        assert_eq!(first.memos.len(), 2);
-        assert!(first.has_more);
-        let second = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "all",
-                "createdAt",
-                None,
-                None,
-                first.next_cursor.as_deref(),
-                Some(2),
-            )
-            .unwrap();
-        assert_eq!(second.memos.len(), 2);
-        assert!(second.has_more);
-        assert!(first
-            .memos
-            .iter()
-            .all(|memo| !second.memos.iter().any(|next| next.id == memo.id)));
-
-        let third = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "all",
-                "createdAt",
-                None,
-                None,
-                second.next_cursor.as_deref(),
-                Some(2),
-            )
-            .unwrap();
-        assert_eq!(third.memos.len(), 1);
-        assert!(!third.has_more);
-        assert!(third.next_cursor.is_none());
-    }
-
-    #[test]
-    fn memo_pages_sort_by_filename_in_both_directions() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Zulu", "# Zulu\n", None)
-            .unwrap();
-        service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "alpha", "# alpha\n", None)
-            .unwrap();
-        service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "middle", "# middle\n", None)
-            .unwrap();
-
-        let asc = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "all",
-                "filenameAsc",
-                None,
-                None,
-                None,
-                Some(2),
-            )
-            .unwrap();
-        assert_eq!(
-            asc.memos
-                .iter()
-                .map(|memo| memo.filename.as_str())
-                .collect::<Vec<_>>(),
-            vec!["alpha.md", "middle.md"]
-        );
-        let asc_next = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "all",
-                "filenameAsc",
-                None,
-                None,
-                asc.next_cursor.as_deref(),
-                Some(2),
-            )
-            .unwrap();
-        assert_eq!(
-            asc_next
-                .memos
-                .iter()
-                .map(|memo| memo.filename.as_str())
-                .collect::<Vec<_>>(),
-            vec!["Zulu.md"]
-        );
-
-        let desc = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "all",
-                "filenameDesc",
-                None,
-                None,
-                None,
-                Some(2),
-            )
-            .unwrap();
-        assert_eq!(
-            desc.memos
-                .iter()
-                .map(|memo| memo.filename.as_str())
-                .collect::<Vec<_>>(),
-            vec!["Zulu.md", "middle.md"]
-        );
-        let desc_next = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "all",
-                "filenameDesc",
-                None,
-                None,
-                desc.next_cursor.as_deref(),
-                Some(2),
-            )
-            .unwrap();
-        assert_eq!(
-            desc_next
-                .memos
-                .iter()
-                .map(|memo| memo.filename.as_str())
-                .collect::<Vec<_>>(),
-            vec!["alpha.md"]
-        );
-    }
-
-    #[test]
-    fn memo_page_rejects_a_cursor_from_another_query() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Cursor note\n", None).unwrap();
-        service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Cursor note two\n", None).unwrap();
-        let first = service
-            .list_memos_filtered_page(Some("work"), "all", "createdAt", None, None, None, Some(1))
-            .unwrap();
-        let error = service
-            .list_memos_filtered_page(
-                Some("work"),
-                "favorited",
-                "createdAt",
-                None,
-                None,
-                first.next_cursor.as_deref(),
-                Some(1),
-            )
-            .unwrap_err();
-        assert!(matches!(error, FlowixError::InvalidInput(_)));
-    }
-
-    #[test]
-    fn notebook_note_counts_returns_every_notebook_from_one_index_read() {
-        let (temp, memo_file) = service_fixture();
-        let personal_path = temp.path().join("personal");
-        std::fs::create_dir_all(&personal_path).unwrap();
-        let mut configs = memo_file.read_notebook_configs().unwrap();
-        configs.push(NotebookConfig {
-            id: "personal".into(),
-            name: "Personal".into(),
-            icon: None,
-            path: format!("{}/", personal_path.display()),
-            is_default: false,
-            sort: 10,
-            created_at: 2,
-            updated_at: 2,
-        });
-        memo_file.write_notebook_configs(&configs).unwrap();
-
-        let mut service = MemoService::new(&memo_file);
-        service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Work one\n", None).unwrap();
-        service.create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Work two\n", None).unwrap();
-        service.create_memo_named_with_tag_in_directory(Some("personal"), None, "Untitled", "# Personal one\n", None).unwrap();
-
-        let configs = service.list_notebooks().unwrap();
-        let counts = service.notebook_note_counts(&configs).unwrap();
-        assert_eq!(counts.get("work"), Some(&2));
-        assert_eq!(counts.get("personal"), Some(&1));
-    }
-
-    #[test]
-    fn exact_edit_reports_typed_conflicts() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        let created = service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Conflict\n\nrepeat repeat\n", None)
-            .unwrap();
-        let error = service
-            .edit_memo_exact(&created.memo.id, "repeat", "changed", false)
-            .unwrap_err();
-        assert!(matches!(error, FlowixError::Conflict(_)));
-    }
-
-    #[test]
-    fn desktop_service_preserves_explicit_titles_empty_content_and_metadata() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-
-        let preview = service
-            .preview_create_path(Some("work"), "Imported title")
-            .unwrap();
-        let created = service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Imported title", "", None)
-            .unwrap();
-        assert_eq!(created.path, preview);
-        assert_eq!(created.memo.filename, "Imported title.md");
-
-        let saved = service.save_memo(&created.memo.id, "").unwrap();
-        assert_eq!(saved.memo.unwrap().filename, "Imported title.md");
-
-        let mut metadata = service.memo_metadata(&created.memo.id).unwrap();
-        metadata.favorited = true;
-        service.sync_memo_metadata(&metadata).unwrap();
-        assert!(service.memo_metadata(&created.memo.id).unwrap().favorited);
-
-    }
-
-    #[test]
-    fn rename_validation_rejects_a_stale_filename_before_mutation() {
-        let (_temp, memo_file) = service_fixture();
-        let mut service = MemoService::new(&memo_file);
-        let created = service
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Original", "body", None)
-            .unwrap();
-
-        let error = service
-            .rename_memo_with_validation(&created.memo.id, "Renamed", |resolved| {
-                if resolved.entry.filename != "Stale.md" {
-                    return Err(FlowixError::Conflict("stale filename".into()));
-                }
-                Ok(())
-            })
-            .unwrap_err();
-
-        assert!(matches!(error, FlowixError::Conflict(_)));
-        assert_eq!(
-            service.memo_metadata(&created.memo.id).unwrap().filename,
-            "Original.md"
-        );
-        assert!(created.path.exists());
-    }
-
-    #[test]
-    fn independent_services_serialize_exact_edits_to_the_same_memo() {
-        use std::sync::{Arc, Barrier};
-        use std::thread;
-
-        let (temp, memo_file) = service_fixture();
-        let created = MemoService::new(&memo_file)
-            .create_memo_named_with_tag_in_directory(Some("work"), None, "Untitled", "# Shared\n\nalpha beta\n", None)
-            .unwrap();
-        let memo_id = created.memo.id;
-        let config_dir = temp.path().join("config");
-        let barrier = Arc::new(Barrier::new(2));
-
-        let edits = [("alpha", "ALPHA"), ("beta", "BETA")];
-        let handles = edits
-            .into_iter()
-            .map(|(old, new)| {
-                let barrier = barrier.clone();
-                let config_dir = config_dir.clone();
-                let memo_id = memo_id.clone();
-                thread::spawn(move || {
-                    let memo_file = MemoFile::new(config_dir);
-                    let mut service = MemoService::new(&memo_file);
-                    barrier.wait();
-                    service
-                        .edit_memo_exact(&memo_id, old, new, false)
-                        .expect("serialized edit");
-                })
-            })
-            .collect::<Vec<_>>();
-        for handle in handles {
-            handle.join().expect("join");
-        }
-
-        let verifier = MemoFile::new(config_dir);
-        let body = MemoService::new(&verifier).get_memo(&memo_id).unwrap().body;
-        assert!(body.contains("ALPHA BETA"), "final body: {body}");
-    }
 }
diff --git a/app/flowix-core/tests/notebook_creation_performance.rs b/app/flowix-core/tests/notebook_creation_performance.rs
index ace3f8926..f501caffe 100644
--- a/app/flowix-core/tests/notebook_creation_performance.rs
+++ b/app/flowix-core/tests/notebook_creation_performance.rs
@@ -1,5 +1,5 @@
-use flowix_core::memo_file::{notebook_path_from_relative, MemoFile, NotebookConfig};
-use std::{fs, time::Instant};
+use flowix_core::memo_file::{MemoFile, NotebookConfig};
+use std::fs;
 
 fn fixture(count: usize) -> (tempfile::TempDir, MemoFile, Vec<NotebookConfig>) {
     let dir = tempfile::tempdir().unwrap();
@@ -26,56 +26,22 @@ fn scoped_revision_preserves_cas_and_notebook_isolation() {
     let (_dir, store, notebooks) = fixture(2);
     let a = &notebooks[0].id;
     let b = &notebooks[1].id;
-    assert!(store.read_memo_content_revision_for_notebook(a, "new-note").unwrap().is_none());
-    let first = store.commit_memo_content_revision("new-note", a, "hash-a", "first").unwrap();
-    let expected = store.read_memo_content_revision_for_notebook(a, "new-note").unwrap().unwrap();
+    assert!(store.read_note_content_revision_for_notebook(a, "new-note").unwrap().is_none());
+    let first = store.commit_note_content_revision(a, "new-note", "hash-a", "first").unwrap();
+    let expected = store.read_note_content_revision_for_notebook(a, "new-note").unwrap().unwrap();
     assert_eq!(expected, first.state);
-    assert!(store.read_memo_content_revision_for_notebook(b, "new-note").unwrap().is_none());
-    let next = store.commit_memo_content_revision_if_current("new-note", a, "hash-b", "next", Some(&expected)).unwrap().unwrap();
+    assert!(store.read_note_content_revision_for_notebook(b, "new-note").unwrap().is_none());
+    let next = store.commit_note_content_revision_if_current(a, "new-note", "hash-b", "next", Some(&expected)).unwrap().unwrap();
     assert_eq!(next.state.revision, 2);
-    assert!(store.commit_memo_content_revision_if_current("new-note", a, "stale", "late", Some(&expected)).unwrap().is_none());
+    assert!(store.commit_note_content_revision_if_current(a, "new-note", "stale", "late", Some(&expected)).unwrap().is_none());
 }
 
 #[test]
 fn scoped_revision_does_not_open_an_unrelated_broken_notebook() {
     let (_dir, store, notebooks) = fixture(2);
     let target = &notebooks[1].id;
-    let expected = store.commit_memo_content_revision("note", target, "hash", "change").unwrap();
+    let expected = store.commit_note_content_revision(target, "note", "hash", "change").unwrap();
     fs::write(std::path::Path::new(&notebooks[0].path).join(".flowix/notebook.db"), b"broken database").unwrap();
-    assert_eq!(store.read_memo_content_revision_for_notebook(target, "note").unwrap(), Some(expected.state));
-    assert!(store.read_memo_content_revision_for_notebook(target, "fresh").unwrap().is_none());
-}
-
-/// Compare the old Created-event lookups with the optimized path, on isolated
-/// notebook databases. This is a component benchmark, not desktop E2E timing.
-#[test]
-#[ignore = "manual notebook creation lookup benchmark"]
-fn benchmark_notebook_creation_event_lookups() {
-    let (_dir, store, notebooks) = fixture(8);
-    let target = notebooks.last().unwrap();
-    let memo = store.create_memo_for_notebook_id(&target.id, "Template note", "body", None).unwrap();
-    let mut old = std::time::Duration::ZERO;
-    let mut new = std::time::Duration::ZERO;
-    for pass in 0..6 {
-        for optimized in if pass % 2 == 0 { [false, true] } else { [true, false] } {
-            let start = Instant::now();
-            for _ in 0..12 {
-                let (path, revision) = if optimized {
-                    let config = store.get_notebook_config_by_id(&target.id).unwrap();
-                    (notebook_path_from_relative(std::path::Path::new(&config.path), &memo.relative_path).unwrap(),
-                     store.read_memo_content_revision_for_notebook(&target.id, &memo.id).unwrap())
-                } else {
-                    let location = store.resolve_memo_location(&memo.id).unwrap().unwrap();
-                    (notebook_path_from_relative(std::path::Path::new(&location.notebook.path), &location.memo.relative_path).unwrap(),
-                     store.read_memo_content_revision(&memo.id).unwrap())
-                };
-                assert!(path.is_file());
-                assert!(revision.is_none());
-            }
-            if optimized { new += start.elapsed(); } else { old += start.elapsed(); }
-        }
-    }
-    println!("8 notebooks, 12 Created-event lookups, 6 alternating passes: old_mean_ms={:.1}, new_mean_ms={:.1}, speedup={:.2}x",
-        old.as_secs_f64() * 1000.0 / 6.0, new.as_secs_f64() * 1000.0 / 6.0,
-        old.as_secs_f64() / new.as_secs_f64());
+    assert_eq!(store.read_note_content_revision_for_notebook(target, "note").unwrap(), Some(expected.state));
+    assert!(store.read_note_content_revision_for_notebook(target, "fresh").unwrap().is_none());
 }
diff --git a/app/flowix-desktop/Cargo.toml b/app/flowix-desktop/Cargo.toml
index 3c9a82eca..2f23b53c9 100644
--- a/app/flowix-desktop/Cargo.toml
+++ b/app/flowix-desktop/Cargo.toml
@@ -50,7 +50,6 @@ fs2 = { workspace = true }
 dunce = { workspace = true }
 uuid = { workspace = true }
 url = "2"
-mime_guess = "2"
 hostname = "0.4"
 machine-uid = "0.5"
 sha2 = { workspace = true }
@@ -65,7 +64,7 @@ tauri = { version = "2", features = ["test"] }
 
 [target.'cfg(target_os = "windows")'.dependencies]
 flowix-installer-helper = { path = "../flowix-installer-helper" }
-windows = { version = "0.61", features = ["Win32_Foundation", "Win32_Graphics_Dwm", "Win32_System_Diagnostics_ToolHelp", "Win32_System_Registry", "Win32_System_Threading", "Win32_UI_WindowsAndMessaging"] }
+windows = { version = "0.61", features = ["Win32_Foundation", "Win32_Graphics_Dwm", "Win32_Graphics_Gdi", "Win32_UI_HiDpi", "Win32_System_Diagnostics_ToolHelp", "Win32_System_Registry", "Win32_System_Threading", "Win32_System_SystemInformation", "Win32_UI_Input", "Win32_UI_WindowsAndMessaging"] }
 webview2-com = "0.38"
 
 [target.'cfg(target_os = "macos")'.dependencies]
diff --git a/app/flowix-desktop/build.rs b/app/flowix-desktop/build.rs
index 9de34ab40..c451cd877 100644
--- a/app/flowix-desktop/build.rs
+++ b/app/flowix-desktop/build.rs
@@ -72,8 +72,10 @@ fn main() {
         let info_plist = if dev_mode {
             let source = std::fs::read_to_string(manifest_dir.join("Info.plist"))
                 .expect("failed to read Info.plist");
+            println!("cargo:rerun-if-changed={}", manifest_dir.join("Info.plist").display());
             let dev = source.replace("<string>flowix</string>", "<string>flowix-dev</string>")
-                .replace("com.flowix.app.deeplink", "com.flowix.app.dev.deeplink");
+                .replace("<string>Flowix</string>", "<string>Flowix Dev</string>")
+                .replace("com.flowix.app.deeplink", "com.flowix-dev.app.deeplink");
             let generated = std::path::PathBuf::from(
                 std::env::var_os("OUT_DIR").expect("OUT_DIR is set"),
             ).join("Flowix-Dev-Info.plist");
diff --git a/app/flowix-desktop/entitlements.plist b/app/flowix-desktop/entitlements.plist
index 65948472e..f8afa6d70 100644
--- a/app/flowix-desktop/entitlements.plist
+++ b/app/flowix-desktop/entitlements.plist
@@ -66,19 +66,9 @@
     </array>
     -->
 
-    <!--
-      User-selected directories are persisted with security-scoped bookmarks
-      in `security_bookmark.rs`. These entitlements are required for the
-      standard macOS sandbox/bookmark model and are harmless for local
-      ad-hoc/dev builds that do not enable the app sandbox.
-
-      Do not enable `com.apple.security.app-sandbox` here yet: Flowix runs
-      local agents / CLI tools, and a full sandbox would need a broader
-      audit of child process and workspace access.
-    -->
+    <!-- Persist access explicitly granted through native file pickers. -->
     <key>com.apple.security.files.user-selected.read-write</key>
     <true/>
-
     <key>com.apple.security.files.bookmarks.app-scope</key>
     <true/>
 </dict>
diff --git a/app/flowix-desktop/src/agent_external/claude/mod.rs b/app/flowix-desktop/src/agent_external/claude/mod.rs
index 55ddd7ae4..69dc573ab 100644
--- a/app/flowix-desktop/src/agent_external/claude/mod.rs
+++ b/app/flowix-desktop/src/agent_external/claude/mod.rs
@@ -4,7 +4,7 @@ mod events;
 mod history;
 mod stream;
 
-pub const AGENT_TYPE: &str = "claude";
+pub const AGENT_TYPE: &str = "claudecode";
 
 // History API —— 读取 ~/.claude/projects/<encoded>/*.jsonl，还原为 ChatMessage 流。
 pub use history::{get_session, get_session_page, is_claude_session_id};
diff --git a/app/flowix-desktop/src/agent_external/codex/app_server.rs b/app/flowix-desktop/src/agent_external/codex/app_server.rs
index a34583bdb..841ce4a26 100644
--- a/app/flowix-desktop/src/agent_external/codex/app_server.rs
+++ b/app/flowix-desktop/src/agent_external/codex/app_server.rs
@@ -43,8 +43,65 @@ const MAX_PENDING_TURN_NOTIFICATIONS: usize = 4096;
 const CONTEXT_COMPACTION_MESSAGE_TYPE: &str = "context-compaction";
 const CODEX_COMMAND_MESSAGE_TYPE: &str = "codex-command";
 const CODEX_COMMENTARY_MESSAGE_TYPE: &str = "agent-commentary";
+const CODEX_MISSING_USER_ITEM_ID: &str = "flowix:codex:missing-user-item";
 const MIN_PAGINATED_CODEX_VERSION: &str = "0.150.0";
 
+fn codex_turn_error_message_id(turn_id: &str) -> String {
+    format!("msg:codex:turn-error:{turn_id}")
+}
+
+fn codex_command_message_id(turn_id: Option<&str>, source_id: &str) -> String {
+    match turn_id.filter(|id| !id.trim().is_empty()) {
+        Some(turn_id) => format!("flowix:codex:command:{turn_id}"),
+        // History has no shared turn key for older records that omit turn IDs.
+        None => format!("flowix:codex:command:unbound:{source_id}"),
+    }
+}
+
+fn codex_tool_call_message_id(turn_id: Option<&str>, call_id: &str) -> String {
+    format!(
+        "flowix:codex:tool-call:{}:{call_id}",
+        turn_id
+            .filter(|id| !id.trim().is_empty())
+            .unwrap_or("unbound")
+    )
+}
+
+fn codex_custom_tool_output_message_id(turn_id: Option<&str>, call_id: &str) -> String {
+    format!(
+        "flowix:codex:tool-output:{}:{call_id}",
+        turn_id
+            .filter(|id| !id.trim().is_empty())
+            .unwrap_or("unbound")
+    )
+}
+
+fn codex_fallback_item_message_id(
+    turn_id: &str,
+    role: &str,
+    content: &str,
+    occurrence: usize,
+) -> String {
+    let mut first = 0x811c_9dc5_u32;
+    let mut second = 0x9e37_79b9_u32;
+    for byte in content.as_bytes() {
+        first = (first ^ u32::from(*byte)).wrapping_mul(0x0100_0193);
+        second = (second ^ u32::from(*byte)).wrapping_mul(0x85eb_ca6b);
+    }
+    format!("flowix:codex:item:{turn_id}:{role}:{first:08x}{second:08x}:{occurrence}")
+}
+
+fn codex_turn_error_metadata(turn_id: Option<&str>) -> AgentChunkMetadata {
+    let Some(turn_id) = turn_id.filter(|id| !id.trim().is_empty()) else {
+        return AgentChunkMetadata::default();
+    };
+    AgentChunkMetadata {
+        codex_turn_id: Some(turn_id.to_string()),
+        message_id: Some(codex_turn_error_message_id(turn_id)),
+        ..AgentChunkMetadata::default()
+    }
+}
+
 fn is_stale_queued_submission_error(error: &str) -> bool {
     error
         .to_ascii_lowercase()
@@ -116,6 +173,7 @@ struct ActiveTurn {
     /// Turn-scoped notifications can beat the `turn/start` response. Ordinary
     /// chats keep them here until that response supplies the authoritative id.
     pending_notifications: Vec<Value>,
+    dropped_notifications: u64,
     turn_ready: Arc<tokio::sync::Notify>,
     /// The UI can stop a native command before Codex announces its provider
     /// turn. Keep the registry entry until that turn id arrives so the
@@ -134,7 +192,7 @@ struct ActiveTurn {
     /// `item/completed` and in the terminal turn payload. Keep the snapshots
     /// per active turn so the terminal payload remains a true fallback
     /// instead of a second delivery.
-    completed_agent_messages: Arc<Mutex<Vec<CompletedAgentMessage>>>,
+    completed_agent_messages: Arc<Mutex<Vec<SeenCompletedAgentMessage>>>,
     /// Runtime-owned receipts survive webview reloads until userMessage consumption.
     pending_steers: Vec<Value>,
 }
@@ -149,10 +207,15 @@ struct QueuedCodexFollowUp {
     run_id: String,
 }
 
-#[derive(Clone, Debug)]
-struct CompletedAgentMessage {
+struct CompletedAgentMessageCandidate {
+    id: Option<String>,
+    text: String,
+}
+
+struct SeenCompletedAgentMessage {
     id: Option<String>,
     text: String,
+    fallback_occurrence: Option<usize>,
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
@@ -190,11 +253,33 @@ fn unbound_notification_action(
 
 fn buffer_turn_notification(active: &mut ActiveTurn, message: &Value) {
     if active.pending_notifications.len() == MAX_PENDING_TURN_NOTIFICATIONS {
+        active.dropped_notifications = active.dropped_notifications.saturating_add(1);
+        if active.dropped_notifications.is_power_of_two() {
+            tracing::warn!(
+                thread_id = %active.flowix_thread_id,
+                run_id = %active.run_id,
+                dropped = active.dropped_notifications,
+                limit = MAX_PENDING_TURN_NOTIFICATIONS,
+                "Codex startup notification buffer overflow; oldest notifications dropped"
+            );
+        }
         active.pending_notifications.remove(0);
     }
     active.pending_notifications.push(message.clone());
 }
 
+/// Called under active_turns when registering ordinary work, so Stop cannot
+/// fall between publishing a cancellation and registering the active turn.
+fn take_pending_cancellation(
+    pending: &mut HashMap<String, String>,
+    thread_id: &str,
+    run_id: &str,
+) -> bool {
+    pending
+        .remove(thread_id)
+        .is_some_and(|expected| expected == run_id)
+}
+
 struct Inner {
     thread_manager: Arc<ThreadManager>,
     connection: Mutex<Option<Connection>>,
@@ -451,6 +536,7 @@ async fn bind_automatically_started_queue_turn(
                 codex_turn_id: codex_turn_id.to_string(),
                 binding: TurnBinding::StartedNotification,
                 pending_notifications: Vec::new(),
+                dropped_notifications: 0,
                 turn_ready: Arc::new(tokio::sync::Notify::new()),
                 cancel_requested: false,
                 stopping: false,
@@ -1066,26 +1152,48 @@ impl CodexAppServerManager {
             // so the real `item/completed(userMessage)` acknowledgement is not
             // dropped during that window. `turn/started` (or the RPC result)
             // fills in the concrete turn id below.
-            self.inner.active_turns.lock().await.insert(flowix_thread_id.clone(), ActiveTurn {
-                flowix_thread_id: flowix_thread_id.clone(),
-                run_id: run_id.clone(),
-                client_user_message_id: None,
-                codex_thread_id: codex_thread_id.clone(),
-                codex_turn_id: String::new(),
-                binding: TurnBinding::StartResponse,
-                pending_notifications: Vec::new(),
-                turn_ready: Arc::new(tokio::sync::Notify::new()),
-                cancel_requested: false,
-                stopping: false,
-                command_id: None,
-                command: None,
-                app_handle: app_handle.clone(),
-                started_at: chrono::Utc::now().timestamp_millis(),
-                last_event_at: chrono::Utc::now().timestamp_millis(),
-                stream_end_emitted: stream_end_emitted.clone(),
-                completed_agent_messages: completed_agent_messages.clone(),
-                pending_steers: Vec::new(),
-            });
+            let cancelled_before_start = {
+                let mut turns = self.inner.active_turns.lock().await;
+                let cancelled = take_pending_cancellation(
+                    &mut *self.inner.pending_cancellations.lock().await,
+                    &flowix_thread_id,
+                    &run_id,
+                );
+                if !cancelled {
+                    turns.insert(flowix_thread_id.clone(), ActiveTurn {
+                        flowix_thread_id: flowix_thread_id.clone(),
+                        run_id: run_id.clone(),
+                        client_user_message_id: None,
+                        codex_thread_id: codex_thread_id.clone(),
+                        codex_turn_id: String::new(),
+                        binding: TurnBinding::StartResponse,
+                        pending_notifications: Vec::new(),
+                        dropped_notifications: 0,
+                        turn_ready: Arc::new(tokio::sync::Notify::new()),
+                        cancel_requested: false,
+                        stopping: false,
+                        command_id: None,
+                        command: None,
+                        app_handle: app_handle.clone(),
+                        started_at: chrono::Utc::now().timestamp_millis(),
+                        last_event_at: chrono::Utc::now().timestamp_millis(),
+                        stream_end_emitted: stream_end_emitted.clone(),
+                        completed_agent_messages: completed_agent_messages.clone(),
+                        pending_steers: Vec::new(),
+                    });
+                }
+                cancelled
+            };
+            if cancelled_before_start {
+                self.emit_stream_end(
+                    app_handle,
+                    &flowix_thread_id,
+                    &run_id,
+                    Some(USER_STOPPED_REASON.to_string()),
+                    &stream_end_emitted,
+                ).await;
+                return Ok(());
+            }
             let mut turn_params = json!({
                 "threadId": codex_thread_id,
                 "input": input,
@@ -1656,6 +1764,7 @@ impl CodexAppServerManager {
                     codex_turn_id: String::new(),
                     binding: TurnBinding::StartResponse,
                     pending_notifications: Vec::new(),
+                    dropped_notifications: 0,
                     turn_ready: Arc::new(tokio::sync::Notify::new()),
                     cancel_requested: false,
                     stopping: false,
@@ -1925,17 +2034,16 @@ impl CodexAppServerManager {
         run_id: Option<&str>,
         app_handle: &tauri::AppHandle,
     ) -> bool {
-        if let Some(expected_run_id) = run_id.filter(|id| !id.trim().is_empty()) {
-            let turns = self.inner.active_turns.lock().await;
-            if turns
-                .get(thread_id)
-                .is_some_and(|active| active.run_id != expected_run_id)
-            {
-                return false;
-            }
-        }
         let active = {
             let mut active_turns = self.inner.active_turns.lock().await;
+            if let Some(expected) = run_id.filter(|id| !id.trim().is_empty()) {
+                if active_turns
+                    .get(thread_id)
+                    .is_some_and(|active| active.run_id != expected)
+                {
+                    return false;
+                }
+            }
             match active_turns.get_mut(thread_id) {
                 Some(active) if active.stopping => return false,
                 Some(active) if active.codex_turn_id.is_empty() => {
@@ -1945,29 +2053,27 @@ impl CodexAppServerManager {
                     // must receive turn/interrupt.
                     active.cancel_requested = true;
                     active.stopping = true;
-                    Some(active.clone())
+                    active.clone()
                 }
                 Some(active) => {
                     active.stopping = true;
-                    Some(active.clone())
+                    active.clone()
+                }
+                None => {
+                    // Ordinary chat and slash commands can both be stopped
+                    // before registering a native turn. Hold active_turns until
+                    // the scoped cancellation is visible to the startup path.
+                    if let Some(run_id) = run_id.filter(|id| !id.trim().is_empty()) {
+                        self.inner
+                            .pending_cancellations
+                            .lock()
+                            .await
+                            .insert(thread_id.to_string(), run_id.to_string());
+                        return true;
+                    }
+                    return false;
                 }
-                None => None,
-            }
-        };
-        let Some(active) = active else {
-            // The frontend can expose the command stop control before the
-            // slash-command task has entered active_turns. Remember only a
-            // scoped command run id; execute_slash_command consumes it before
-            // issuing any Codex RPC.
-            if let Some(run_id) = run_id.filter(|id| !id.trim().is_empty()) {
-                self.inner
-                    .pending_cancellations
-                    .lock()
-                    .await
-                    .insert(thread_id.to_string(), run_id.to_string());
-                return true;
             }
-            return false;
         };
         if !active.codex_turn_id.is_empty() {
             if let Err(error) = self
@@ -2545,24 +2651,53 @@ impl CodexAppServerManager {
             .filter(|id| !id.is_empty())
             .map(str::to_string)
             .unwrap_or_else(|| format!("codex-command-{}", uuid::Uuid::new_v4()));
+        let waits_for_provider_turn =
+            is_codex_compact_command(command) || is_codex_goal_mutation_command(command);
+        let ended = Arc::new(AtomicBool::new(false));
+        let completed_agent_messages = Arc::new(Mutex::new(Vec::new()));
+        // Native commands can either be an immediate thread operation or
+        // return/start a provider turn. `/goal` is a mutation RPC whose
+        // response is followed by an autonomous provider turn, as shown by
+        // Codex's `thread_goal_updated -> task_started` event sequence. Keep
+        // an empty turn id temporarily: `turn/started` can arrive before the
+        // command RPC response and fills it in. Register before emitting the
+        // optimistic lifecycle events so an immediate stop cannot miss it.
         let cancelled_before_start = {
-            let mut pending = self.inner.pending_cancellations.lock().await;
-            match pending.get(flowix_thread_id) {
-                Some(expected_run_id) if expected_run_id == &run_id => {
-                    pending.remove(flowix_thread_id);
-                    true
-                }
-                Some(_) => {
-                    // A stale stop for an older command must not affect this
-                    // newly-created command.
-                    pending.remove(flowix_thread_id);
-                    false
-                }
-                None => false,
+            let mut turns = self.inner.active_turns.lock().await;
+            let cancelled = take_pending_cancellation(
+                &mut *self.inner.pending_cancellations.lock().await,
+                flowix_thread_id,
+                &run_id,
+            );
+            if !cancelled {
+                turns.insert(
+                    flowix_thread_id.to_string(),
+                    ActiveTurn {
+                        flowix_thread_id: flowix_thread_id.to_string(),
+                        run_id: run_id.clone(),
+                        client_user_message_id: None,
+                        codex_thread_id: codex_thread_id.clone(),
+                        codex_turn_id: String::new(),
+                        binding: TurnBinding::StartedNotification,
+                        pending_notifications: Vec::new(),
+                        dropped_notifications: 0,
+                        turn_ready: Arc::new(tokio::sync::Notify::new()),
+                        cancel_requested: false,
+                        stopping: false,
+                        command_id: Some(command_id.clone()),
+                        command: Some(command.to_string()),
+                        app_handle: app_handle.clone(),
+                        started_at,
+                        last_event_at: chrono::Utc::now().timestamp_millis(),
+                        stream_end_emitted: ended.clone(),
+                        completed_agent_messages: completed_agent_messages.clone(),
+                        pending_steers: Vec::new(),
+                    },
+                );
             }
+            cancelled
         };
         if cancelled_before_start {
-            let ended = Arc::new(AtomicBool::new(false));
             self.emit_codex_command(
                 app_handle,
                 flowix_thread_id,
@@ -2584,40 +2719,6 @@ impl CodexAppServerManager {
             .await;
             return Ok(json!({ "cancelled": true }));
         }
-        let waits_for_provider_turn =
-            is_codex_compact_command(command) || is_codex_goal_mutation_command(command);
-        let ended = Arc::new(AtomicBool::new(false));
-        let completed_agent_messages = Arc::new(Mutex::new(Vec::new()));
-        // Native commands can either be an immediate thread operation or
-        // return/start a provider turn. `/goal` is a mutation RPC whose
-        // response is followed by an autonomous provider turn, as shown by
-        // Codex's `thread_goal_updated -> task_started` event sequence. Keep
-        // an empty turn id temporarily: `turn/started` can arrive before the
-        // command RPC response and fills it in. Register before emitting the
-        // optimistic lifecycle events so an immediate stop cannot miss it.
-        self.inner.active_turns.lock().await.insert(
-            flowix_thread_id.to_string(),
-            ActiveTurn {
-                flowix_thread_id: flowix_thread_id.to_string(),
-                run_id: run_id.clone(),
-                client_user_message_id: None,
-                codex_thread_id: codex_thread_id.clone(),
-                codex_turn_id: String::new(),
-                binding: TurnBinding::StartedNotification,
-                pending_notifications: Vec::new(),
-                turn_ready: Arc::new(tokio::sync::Notify::new()),
-                cancel_requested: false,
-                stopping: false,
-                command_id: Some(command_id.clone()),
-                command: Some(command.to_string()),
-                app_handle: app_handle.clone(),
-                started_at,
-                last_event_at: chrono::Utc::now().timestamp_millis(),
-                stream_end_emitted: ended.clone(),
-                completed_agent_messages: completed_agent_messages.clone(),
-                pending_steers: Vec::new(),
-            },
-        );
         self.emit_codex_command(
             app_handle,
             flowix_thread_id,
@@ -3499,11 +3600,16 @@ async fn dispatch_notification_inner(inner: &Arc<Inner>, message: &Value) {
                 if let Some((chunk, metadata)) =
                     completed_message_chunk(&flowix_thread_id, item, turn_id.as_deref())
                 {
-                    let should_emit = item.get("type").and_then(Value::as_str)
-                        != Some("agentMessage")
-                        || should_emit_completed_agent_message(&completed_agent_messages, item)
-                            .await;
-                    if should_emit {
+                    let mut metadata = metadata;
+                    if should_emit_completed_agent_message(
+                        &completed_agent_messages,
+                        item,
+                        turn_id.as_deref(),
+                        None,
+                        &mut metadata,
+                    )
+                    .await
+                    {
                         emit_notification_chunk_with_metadata(
                             inner,
                             &flowix_thread_id,
@@ -3583,35 +3689,42 @@ async fn dispatch_notification_inner(inner: &Arc<Inner>, message: &Value) {
                 // App Server normally finalizes messages through item/completed.
                 // The completed turn also carries the final agent message, so
                 // project it as an idempotent fallback before ending the stream.
-                if let Some(item) = params
-                    .pointer("/turn/items")
-                    .and_then(Value::as_array)
-                    .and_then(|items| {
-                        items.iter().rev().find(|item| {
+                if let Some(items) = params.pointer("/turn/items").and_then(Value::as_array) {
+                    if let Some((item_index, item)) =
+                        items.iter().enumerate().rev().find(|(_, item)| {
                             item.get("type").and_then(Value::as_str) == Some("agentMessage")
                         })
-                    })
-                {
-                    if let Some((chunk, metadata)) =
-                        completed_message_chunk(&flowix_thread_id, item, turn_id.as_deref())
                     {
-                        if should_emit_completed_agent_message(&completed_agent_messages, item)
-                            .await
+                        if let Some((chunk, metadata)) =
+                            completed_message_chunk(&flowix_thread_id, item, turn_id.as_deref())
                         {
-                            emit_notification_chunk_with_metadata(
-                                inner,
-                                &flowix_thread_id,
-                                &run_id,
-                                &app,
-                                chunk,
-                                metadata,
+                            let occurrence =
+                                codex_fallback_agent_message_occurrence(items, item_index, status);
+                            let mut metadata = metadata;
+                            if should_emit_completed_agent_message(
+                                &completed_agent_messages,
+                                item,
+                                turn_id.as_deref(),
+                                Some(occurrence),
+                                &mut metadata,
                             )
-                            .await;
+                            .await
+                            {
+                                emit_notification_chunk_with_metadata(
+                                    inner,
+                                    &flowix_thread_id,
+                                    &run_id,
+                                    &app,
+                                    chunk,
+                                    metadata,
+                                )
+                                .await;
+                            }
                         }
                     }
                 }
                 if let Some(reason) = &reason {
-                    emit_notification_chunk(
+                    emit_notification_chunk_with_metadata(
                         inner,
                         &flowix_thread_id,
                         &run_id,
@@ -3624,6 +3737,7 @@ async fn dispatch_notification_inner(inner: &Arc<Inner>, message: &Value) {
                                 "app-server",
                             )),
                         },
+                        codex_turn_error_metadata(turn_id.as_deref()),
                     )
                     .await;
                 }
@@ -3786,6 +3900,7 @@ fn item_metadata(item: &Value) -> AgentChunkMetadata {
     metadata.codex_turn_id = item
         .get("turnId")
         .and_then(Value::as_str)
+        .filter(|id| !id.trim().is_empty())
         .map(str::to_string);
     metadata.client_user_message_id = item
         .get("clientId")
@@ -3802,11 +3917,11 @@ fn item_metadata_from_id(item_id: Option<String>) -> AgentChunkMetadata {
     }
 }
 
-fn completed_agent_message(item: &Value) -> Option<CompletedAgentMessage> {
+fn completed_agent_message(item: &Value) -> Option<CompletedAgentMessageCandidate> {
     if item.get("type").and_then(Value::as_str) != Some("agentMessage") {
         return None;
     }
-    let message = CompletedAgentMessage {
+    let message = CompletedAgentMessageCandidate {
         id: item
             .get("id")
             .and_then(Value::as_str)
@@ -3822,33 +3937,97 @@ fn completed_agent_message(item: &Value) -> Option<CompletedAgentMessage> {
 }
 
 async fn should_emit_completed_agent_message(
-    messages: &Arc<Mutex<Vec<CompletedAgentMessage>>>,
+    messages: &Arc<Mutex<Vec<SeenCompletedAgentMessage>>>,
     item: &Value,
+    turn_id: Option<&str>,
+    terminal_occurrence: Option<usize>,
+    metadata: &mut AgentChunkMetadata,
 ) -> bool {
     let Some(candidate) = completed_agent_message(item) else {
         return true;
     };
     let mut seen = messages.lock().await;
-    let duplicate = seen
-        .iter()
-        .any(|previous| match (&candidate.id, &previous.id) {
-            // Stable provider ids are authoritative. Two different ids remain
-            // distinct even when the rendered text happens to match.
-            (Some(candidate_id), Some(previous_id)) => candidate_id == previous_id,
-            // If one side lacks an id, text is the only compatibility identity
-            // available for the terminal fallback. This branch is deliberately
-            // limited to that malformed/legacy boundary.
-            _ => candidate.text == previous.text,
-        });
-    if duplicate {
+    let fallback_occurrence = candidate.id.is_none().then(|| {
+        terminal_occurrence.unwrap_or_else(|| {
+            seen.iter()
+                .filter(|previous| previous.id.is_none() && previous.text == candidate.text)
+                .count()
+        })
+    });
+    let duplicate_id = candidate.id.as_deref().is_some_and(|candidate_id| {
+        seen.iter()
+            .any(|previous| previous.id.as_deref() == Some(candidate_id))
+    });
+    let terminal_duplicate = terminal_occurrence.is_some_and(|occurrence| {
+        seen.iter().any(|previous| {
+            previous.id.is_none()
+                && previous.text == candidate.text
+                && previous.fallback_occurrence == Some(occurrence)
+        })
+    });
+    if duplicate_id || terminal_duplicate {
         return false;
     }
-    seen.push(candidate);
+
+    if metadata.message_id.is_none() {
+        metadata.message_id = candidate.id.clone().or_else(|| {
+            let occurrence = fallback_occurrence.unwrap_or_default();
+            turn_id.filter(|id| !id.trim().is_empty()).map(|turn_id| {
+                codex_fallback_item_message_id(turn_id, "assistant", &candidate.text, occurrence)
+            })
+        });
+    }
+    seen.push(SeenCompletedAgentMessage {
+        id: candidate.id,
+        text: candidate.text,
+        fallback_occurrence,
+    });
     true
 }
 
+fn codex_fallback_agent_message_occurrence(
+    items: &[Value],
+    item_index: usize,
+    turn_status: &str,
+) -> usize {
+    let Some(item) = items.get(item_index) else {
+        return 0;
+    };
+    let Some(text) = item.get("text").and_then(Value::as_str) else {
+        return 0;
+    };
+    let interrupted_turn = matches!(turn_status, "failed" | "interrupted" | "cancelled");
+    items[..item_index]
+        .iter()
+        .filter(|previous| {
+            if previous.get("type").and_then(Value::as_str) != Some("agentMessage")
+                || previous
+                    .get("id")
+                    .and_then(Value::as_str)
+                    .is_some_and(|id| !id.trim().is_empty())
+                || previous.get("text").and_then(Value::as_str) != Some(text)
+            {
+                return false;
+            }
+            let interrupted_item =
+                previous
+                    .get("status")
+                    .and_then(Value::as_str)
+                    .is_some_and(|status| {
+                        matches!(
+                            status,
+                            "inProgress" | "failed" | "interrupted" | "cancelled"
+                        )
+                    });
+            !(interrupted_turn && interrupted_item)
+        })
+        .count()
+}
+
 fn with_turn_id(mut metadata: AgentChunkMetadata, turn_id: Option<&str>) -> AgentChunkMetadata {
-    metadata.codex_turn_id = turn_id.map(str::to_string);
+    metadata.codex_turn_id = turn_id
+        .filter(|id| !id.trim().is_empty())
+        .map(str::to_string);
     metadata
 }
 
@@ -3902,10 +4081,17 @@ fn completed_message_chunk(
             .get("id")
             .and_then(Value::as_str)
             .filter(|id| !id.trim().is_empty())
-            .unwrap_or("codex-context-compaction")
-            .to_string();
+            .map(str::to_string)
+            .or_else(|| {
+                turn_id
+                    .filter(|id| !id.trim().is_empty())
+                    .map(|turn_id| codex_fallback_item_message_id(turn_id, "system", "", 0))
+            })
+            .unwrap_or_else(|| "codex-context-compaction".to_string());
         let mut metadata = item_metadata(item);
-        metadata.codex_turn_id = turn_id.map(str::to_string);
+        metadata.codex_turn_id = turn_id
+            .filter(|id| !id.trim().is_empty())
+            .map(str::to_string);
         metadata.message_phase = Some("completed");
         metadata.content_mode = Some("snapshot");
         return Some((
@@ -3957,13 +4143,15 @@ fn completed_message_chunk(
         return None;
     }
     let chunk = if kind == "userMessage" {
+        let user_id = item
+            .get("id")
+            .and_then(Value::as_str)
+            .filter(|id| !id.trim().is_empty())
+            .unwrap_or(CODEX_MISSING_USER_ITEM_ID)
+            .to_string();
         AgentChunk::UserMessage {
             thread_id: thread_id.to_string(),
-            id: item
-                .get("id")
-                .and_then(Value::as_str)
-                .unwrap_or("codex-user")
-                .to_string(),
+            id: user_id,
             text,
             timestamp: chrono::Utc::now().timestamp_millis(),
             attachments: app_server_image_attachments(item.get("content")),
@@ -3980,7 +4168,9 @@ fn completed_message_chunk(
         }
     };
     let mut metadata = item_metadata(item);
-    metadata.codex_turn_id = turn_id.map(str::to_string);
+    metadata.codex_turn_id = turn_id
+        .filter(|id| !id.trim().is_empty())
+        .map(str::to_string);
     metadata.message_type = codex_message_type(item);
     // Completed item notifications do not repeat turnId in the item. The
     // caller fills it from the notification context before emitting.
@@ -4129,6 +4319,29 @@ fn app_server_approval_policy(permission: Option<&str>) -> &'static str {
 mod tests {
     use super::*;
 
+    #[test]
+    fn startup_cancellation_is_scoped_and_consumed_once() {
+        let mut pending = HashMap::from([
+            ("thread-a".to_string(), "run-a".to_string()),
+            ("thread-b".to_string(), "run-b".to_string()),
+        ]);
+        assert!(take_pending_cancellation(&mut pending, "thread-a", "run-a"));
+        assert!(!take_pending_cancellation(
+            &mut pending,
+            "thread-a",
+            "run-a"
+        ));
+        assert!(!take_pending_cancellation(
+            &mut pending,
+            "thread-b",
+            "new-run"
+        ));
+        assert!(
+            pending.is_empty(),
+            "a stale Stop must not cancel a later run"
+        );
+    }
+
     #[test]
     fn consumes_only_the_correlated_pending_steer_and_never_recreates_a_receipt() {
         let mut receipts = vec![
@@ -4466,6 +4679,20 @@ mod tests {
         assert_eq!(message.codex_turn_id.as_deref(), Some("turn-1"));
     }
 
+    #[test]
+    fn context_compaction_without_native_identity_uses_the_live_fallback() {
+        let messages = app_server_turn_messages(&[json!({
+            "status": "completed",
+            "items": [{ "type": "contextCompaction" }]
+        })]);
+
+        let marker = messages
+            .iter()
+            .find(|message| message.role == "system")
+            .expect("context compaction marker");
+        assert_eq!(marker.id, "codex-context-compaction");
+    }
+
     #[test]
     fn codex_history_only_confirms_assistant_rows_with_native_terminal_evidence() {
         let active = app_server_turn_messages(&[json!({
@@ -4527,7 +4754,11 @@ mod tests {
             messages[0].message_type.as_deref(),
             Some(CODEX_COMMAND_MESSAGE_TYPE)
         );
-        assert_eq!(messages[0].id, "codex-command-history-compaction-1");
+        assert_eq!(
+            messages[0].id,
+            codex_command_message_id(Some("turn-compact"), "")
+        );
+        assert_eq!(messages[0].id, "flowix:codex:command:turn-compact");
         assert_eq!(messages[0].codex_turn_id.as_deref(), Some("turn-compact"));
         assert_eq!(messages[1].role, "system");
         assert_eq!(
@@ -4536,6 +4767,159 @@ mod tests {
         );
     }
 
+    #[test]
+    fn history_commands_without_turn_ids_use_the_unbound_namespace() {
+        let compact = app_server_compact_command_message(
+            &json!({ "id": "compact-item", "type": "contextCompaction" }),
+            "2026-01-01T00:00:00Z",
+            0,
+            0,
+            None,
+        );
+        let goal = app_server_goal_command_message("Ship it", "2026-01-01T00:00:00Z", 2, None);
+
+        assert_eq!(compact.id, "flowix:codex:command:unbound:compact-item");
+        assert_eq!(goal.id, "flowix:codex:command:unbound:turn-2");
+    }
+
+    #[test]
+    fn codex_missing_item_ids_use_turn_content_and_occurrence() {
+        let messages = app_server_turn_messages(&[json!({
+            "id": "turn-fallback",
+            "status": "completed",
+            "items": [
+                { "type": "agentMessage", "text": "same reply" },
+                { "type": "agentMessage", "text": "same reply" },
+                { "type": "reasoning", "summary": "same thought" },
+                { "type": "reasoning", "summary": "same thought" }
+            ]
+        })]);
+
+        assert_eq!(messages.len(), 4);
+        assert_eq!(
+            messages[0].id,
+            codex_fallback_item_message_id("turn-fallback", "assistant", "same reply", 0)
+        );
+        assert_eq!(
+            messages[0].id,
+            "flowix:codex:item:turn-fallback:assistant:c9c3d78b64eaec57:0"
+        );
+        assert_eq!(
+            codex_fallback_item_message_id("t", "assistant", "你好🙂", 0),
+            "flowix:codex:item:t:assistant:71b13a3934f0304d:0"
+        );
+        assert_eq!(
+            messages[1].id,
+            codex_fallback_item_message_id("turn-fallback", "assistant", "same reply", 1)
+        );
+        assert_ne!(messages[0].id, messages[1].id);
+        assert_eq!(
+            messages[2].id,
+            codex_fallback_item_message_id("turn-fallback", "reasoning", "same thought", 0)
+        );
+        assert_eq!(
+            messages[3].id,
+            codex_fallback_item_message_id("turn-fallback", "reasoning", "same thought", 1)
+        );
+    }
+
+    #[test]
+    fn repeated_codex_user_items_without_ids_match_the_live_fallback_policy() {
+        let messages = app_server_turn_messages(&[json!({
+            "id": "turn-users",
+            "status": "completed",
+            "items": [
+                { "type": "userMessage", "content": "repeat" },
+                { "type": "userMessage", "content": "repeat" }
+            ]
+        })]);
+
+        assert_eq!(messages.len(), 2);
+        assert_eq!(
+            messages[0].id,
+            codex_fallback_item_message_id("turn-users", "user", "repeat", 0)
+        );
+        assert_eq!(
+            messages[1].id,
+            codex_fallback_item_message_id("turn-users", "user", "repeat", 1)
+        );
+    }
+
+    #[test]
+    fn orphan_custom_tool_history_uses_provider_output_id_or_call_fallback() {
+        let messages = app_server_turn_messages(&[json!({
+            "id": "turn-tools",
+            "status": "completed",
+            "items": [
+                { "id": "output-item", "type": "custom_tool_call_output", "call_id": "call-a", "output": "done" },
+                { "type": "custom_tool_call_output", "call_id": "call-b", "output": "done" }
+            ]
+        })]);
+
+        assert_eq!(messages.len(), 2);
+        assert_eq!(messages[0].id, "output-item");
+        assert_eq!(
+            messages[1].id,
+            codex_custom_tool_output_message_id(Some("turn-tools"), "call-b")
+        );
+        assert_eq!(messages[1].id, "flowix:codex:tool-output:turn-tools:call-b");
+    }
+
+    #[test]
+    fn custom_tool_call_without_item_id_uses_the_live_call_fallback() {
+        let messages = app_server_turn_messages(&[json!({
+            "id": "turn-tools",
+            "status": "completed",
+            "items": [{
+                "type": "custom_tool_call",
+                "call_id": "call-a",
+                "name": "future_connector",
+                "input": { "query": "x" }
+            }]
+        })]);
+
+        assert_eq!(messages.len(), 1);
+        assert_eq!(
+            messages[0].id,
+            codex_tool_call_message_id(Some("turn-tools"), "call-a")
+        );
+        assert_eq!(messages[0].id, "flowix:codex:tool-call:turn-tools:call-a");
+        assert_eq!(messages[0].tool_call_id.as_deref(), Some("call-a"));
+    }
+
+    #[test]
+    fn codex_tool_call_without_turn_or_item_id_uses_the_unbound_live_fallback() {
+        let messages = app_server_turn_messages(&[json!({
+            "status": "completed",
+            "items": [{
+                "type": "custom_tool_call",
+                "call_id": "call-a",
+                "name": "future_connector",
+                "input": { "query": "x" }
+            }]
+        })]);
+
+        assert_eq!(messages.len(), 1);
+        assert_eq!(messages[0].id, codex_tool_call_message_id(None, "call-a"));
+        assert_eq!(messages[0].id, "flowix:codex:tool-call:unbound:call-a");
+    }
+
+    #[test]
+    fn cancelled_turn_history_emits_the_same_error_identity_as_live() {
+        let messages = app_server_turn_messages(&[json!({
+            "id": "turn-cancelled",
+            "status": "cancelled",
+            "items": []
+        })]);
+
+        assert_eq!(messages.len(), 1);
+        assert_eq!(
+            messages[0].id,
+            codex_turn_error_message_id("turn-cancelled")
+        );
+        assert_eq!(messages[0].content, "Codex turn failed");
+    }
+
     #[test]
     fn restores_initial_goal_command_before_goal_tools_and_hides_internal_context() {
         let internal = r#"<codex_internal_context source="goal">
@@ -4775,41 +5159,122 @@ Budget:
     }
 
     #[tokio::test]
-    async fn suppresses_a_terminal_agent_snapshot_already_forwarded_for_the_turn() {
+    async fn preserves_distinct_identical_idless_agent_items_and_suppresses_terminal_replay() {
         let messages = Arc::new(Mutex::new(Vec::new()));
-        let completed = json!({
-            "id": "message-1",
-            "type": "agentMessage",
-            "text": "Final answer"
-        });
+        let first = json!({ "type": "agentMessage", "text": "Final answer" });
+        let second = json!({ "type": "agentMessage", "text": "Final answer" });
+        let mut first_metadata = AgentChunkMetadata::default();
+        let mut second_metadata = AgentChunkMetadata::default();
+        let first_should_emit = should_emit_completed_agent_message(
+            &messages,
+            &first,
+            Some("turn-1"),
+            None,
+            &mut first_metadata,
+        )
+        .await;
+        let second_should_emit = should_emit_completed_agent_message(
+            &messages,
+            &second,
+            Some("turn-1"),
+            None,
+            &mut second_metadata,
+        )
+        .await;
+
+        assert!(first_should_emit);
+        assert_eq!(
+            first_metadata.message_id.as_deref(),
+            Some(codex_fallback_item_message_id("turn-1", "assistant", "Final answer", 0).as_str())
+        );
+        assert!(second_should_emit);
+        assert_eq!(
+            second_metadata.message_id.as_deref(),
+            Some(codex_fallback_item_message_id("turn-1", "assistant", "Final answer", 1).as_str())
+        );
+
+        let history = app_server_turn_messages(&[json!({
+            "id": "turn-1",
+            "status": "completed",
+            "items": [first.clone(), second.clone()]
+        })]);
+        assert_eq!(
+            history
+                .iter()
+                .map(|message| message.id.as_str())
+                .collect::<Vec<_>>(),
+            [
+                first_metadata.message_id.as_deref().unwrap(),
+                second_metadata.message_id.as_deref().unwrap(),
+            ]
+        );
 
-        assert!(should_emit_completed_agent_message(&messages, &completed).await);
-        assert!(!should_emit_completed_agent_message(&messages, &completed).await);
+        let partial_stream = Arc::new(Mutex::new(Vec::new()));
+        let mut partial_metadata = AgentChunkMetadata::default();
         assert!(
             should_emit_completed_agent_message(
-                &messages,
-                &json!({ "id": "message-2", "type": "agentMessage", "text": "Final answer" }),
+                &partial_stream,
+                &first,
+                Some("turn-1"),
+                None,
+                &mut partial_metadata,
             )
             .await
         );
-    }
-
-    #[tokio::test]
-    async fn matches_legacy_terminal_snapshots_when_one_side_lacks_an_id() {
-        let messages = Arc::new(Mutex::new(Vec::new()));
-        let completed = json!({ "type": "agentMessage", "text": "Final answer" });
+        let mut terminal_second_metadata = AgentChunkMetadata::default();
+        assert!(
+            should_emit_completed_agent_message(
+                &partial_stream,
+                &second,
+                Some("turn-1"),
+                Some(1),
+                &mut terminal_second_metadata,
+            )
+            .await
+        );
+        assert_eq!(
+            terminal_second_metadata.message_id.as_deref(),
+            Some(codex_fallback_item_message_id("turn-1", "assistant", "Final answer", 1).as_str())
+        );
 
-        assert!(should_emit_completed_agent_message(&messages, &completed).await);
-        assert!(!should_emit_completed_agent_message(&messages, &completed).await);
+        let mut terminal_metadata = AgentChunkMetadata::default();
         assert!(
             !should_emit_completed_agent_message(
                 &messages,
-                &json!({ "id": "message-1", "type": "agentMessage", "text": "Final answer" }),
+                &second,
+                Some("turn-1"),
+                Some(1),
+                &mut terminal_metadata,
             )
             .await
         );
     }
 
+    #[tokio::test]
+    async fn uses_terminal_item_order_for_an_unseen_idless_snapshot() {
+        let items = vec![
+            json!({ "type": "agentMessage", "text": "Repeated", "status": "completed" }),
+            json!({ "type": "agentMessage", "text": "Repeated", "status": "completed" }),
+        ];
+        let occurrence = codex_fallback_agent_message_occurrence(&items, 1, "completed");
+        assert_eq!(occurrence, 1);
+
+        let mut metadata = AgentChunkMetadata::default();
+        let should_emit = should_emit_completed_agent_message(
+            &Arc::new(Mutex::new(Vec::new())),
+            &items[1],
+            Some("turn-1"),
+            Some(occurrence),
+            &mut metadata,
+        )
+        .await;
+        assert!(should_emit);
+        assert_eq!(
+            metadata.message_id.as_deref(),
+            Some(codex_fallback_item_message_id("turn-1", "assistant", "Repeated", 1).as_str())
+        );
+    }
+
     #[tokio::test]
     async fn does_not_mark_an_empty_agent_snapshot_as_completed() {
         let messages = Arc::new(Mutex::new(Vec::new()));
@@ -4824,9 +5289,37 @@ Budget:
             "text": "Final answer"
         });
 
-        assert!(should_emit_completed_agent_message(&messages, &empty).await);
-        assert!(should_emit_completed_agent_message(&messages, &complete).await);
-        assert!(!should_emit_completed_agent_message(&messages, &complete).await);
+        let mut metadata = AgentChunkMetadata::default();
+        assert!(
+            should_emit_completed_agent_message(
+                &messages,
+                &empty,
+                Some("turn-1"),
+                None,
+                &mut metadata,
+            )
+            .await
+        );
+        assert!(
+            should_emit_completed_agent_message(
+                &messages,
+                &complete,
+                Some("turn-1"),
+                None,
+                &mut metadata,
+            )
+            .await
+        );
+        assert!(
+            !should_emit_completed_agent_message(
+                &messages,
+                &complete,
+                Some("turn-1"),
+                None,
+                &mut metadata,
+            )
+            .await
+        );
     }
 
     #[test]
@@ -4955,6 +5448,25 @@ Budget:
         assert_eq!(metadata.message_phase.as_deref(), Some("completed"));
     }
 
+    #[test]
+    fn context_compaction_without_provider_ids_uses_shared_fallback_identity() {
+        for turn_id in [None, Some("")] {
+            let (chunk, metadata) = completed_message_chunk(
+                "thread-1",
+                &json!({ "type": "contextCompaction" }),
+                turn_id,
+            )
+            .expect("completed context compaction");
+
+            assert!(matches!(
+                chunk,
+                AgentChunk::ContextCompaction { id, .. }
+                    if id == "codex-context-compaction"
+            ));
+            assert!(metadata.message_id.is_none());
+        }
+    }
+
     #[test]
     fn projects_completed_reasoning_summary_as_authoritative_snapshot() {
         let (chunk, metadata) = completed_message_chunk(
@@ -5081,10 +5593,19 @@ Budget:
         assert_eq!(messages.len(), 2);
         assert_eq!(messages[1].role, "assistant");
         assert_eq!(messages[1].content, "rate limit exceeded");
-        assert_eq!(messages[1].id, "codex-turn-error-turn-1");
+        assert_eq!(messages[1].id, codex_turn_error_message_id("turn-1"));
         assert!(messages[1].error_details.is_some());
     }
 
+    #[test]
+    fn live_turn_error_metadata_uses_the_history_identity() {
+        let metadata = codex_turn_error_metadata(Some("turn-1"));
+        let expected_id = codex_turn_error_message_id("turn-1");
+
+        assert_eq!(metadata.codex_turn_id.as_deref(), Some("turn-1"));
+        assert_eq!(metadata.message_id.as_deref(), Some(expected_id.as_str()));
+    }
+
     #[test]
     fn keeps_tool_items_and_interruption_with_their_own_turn() {
         let turns = vec![
@@ -5115,7 +5636,14 @@ Budget:
                 .iter()
                 .map(|message| message.id.as_str())
                 .collect::<Vec<_>>(),
-            ["u1", "a1", "tool-1", "codex-turn-error-turn-1", "u2", "a2"],
+            [
+                "u1",
+                "a1",
+                "tool-1",
+                "msg:codex:turn-error:turn-1",
+                "u2",
+                "a2"
+            ],
         );
         assert_eq!(messages[2].role, "tool");
         assert_eq!(messages[3].content, "Codex turn interrupted");
@@ -5136,13 +5664,41 @@ Budget:
 
         let messages = app_server_turn_messages(&turns);
         assert_eq!(
-            messages.iter().map(|message| message.id.as_str()).collect::<Vec<_>>(),
-            ["u1", "answer", "codex-turn-error-turn-interrupted"],
+            messages
+                .iter()
+                .map(|message| message.id.as_str())
+                .collect::<Vec<_>>(),
+            ["u1", "answer", "msg:codex:turn-error:turn-interrupted"],
         );
         assert_eq!(messages[1].content, "Completed before stop");
         assert_eq!(messages[1].is_completed, Some(true));
     }
 
+    #[test]
+    fn history_fallback_ids_ignore_omitted_interrupted_items() {
+        let items = vec![
+            json!({ "type": "agentMessage", "status": "inProgress", "text": "Repeated" }),
+            json!({ "type": "agentMessage", "status": "completed", "text": "Repeated" }),
+        ];
+        let turn_id = "turn-interrupted";
+        let occurrence = codex_fallback_agent_message_occurrence(&items, 1, "interrupted");
+        let history = app_server_turn_messages(&[json!({
+            "id": turn_id,
+            "status": "interrupted",
+            "items": items
+        })]);
+        let assistant = history
+            .iter()
+            .find(|message| message.role == "assistant")
+            .expect("completed assistant message");
+
+        assert_eq!(occurrence, 0);
+        assert_eq!(
+            assistant.id,
+            codex_fallback_item_message_id(turn_id, "assistant", "Repeated", occurrence)
+        );
+    }
+
     #[test]
     fn pages_projected_history_on_complete_turn_boundaries() {
         let turns = (0..3)
diff --git a/app/flowix-desktop/src/agent_external/codex/app_server/history_projection.rs b/app/flowix-desktop/src/agent_external/codex/app_server/history_projection.rs
index e3b594023..40343f0d5 100644
--- a/app/flowix-desktop/src/agent_external/codex/app_server/history_projection.rs
+++ b/app/flowix-desktop/src/agent_external/codex/app_server/history_projection.rs
@@ -49,7 +49,11 @@ pub(super) fn app_server_turn_messages_with_offset(
     let mut messages = Vec::new();
     for (turn_offset, turn) in turns.iter().enumerate() {
         let turn_index = turn_index_offset + turn_offset;
-        let turn_id = turn.get("id").and_then(Value::as_str).map(str::to_string);
+        let turn_id = turn
+            .get("id")
+            .and_then(Value::as_str)
+            .filter(|id| !id.trim().is_empty())
+            .map(str::to_string);
         let turn_duration_ms = app_server_turn_duration_ms(turn);
         let turn_message_start = messages.len();
         let timestamp = app_server_timestamp_string(
@@ -67,6 +71,7 @@ pub(super) fn app_server_turn_messages_with_offset(
         }
         let is_manual_compact_turn = is_manual_compact_turn(turn);
         let mut compact_command_emitted = false;
+        let mut fallback_item_occurrences: HashMap<(String, String), usize> = HashMap::new();
         let turn_items = turn
             .get("items")
             .and_then(Value::as_array)
@@ -94,8 +99,6 @@ pub(super) fn app_server_turn_messages_with_offset(
                         messages.push(app_server_orphan_custom_tool_output_message(
                             item,
                             &timestamp,
-                            turn_index,
-                            item_index,
                             turn_id.as_deref(),
                         ));
                     }
@@ -138,14 +141,50 @@ pub(super) fn app_server_turn_messages_with_offset(
                 item_index,
                 turn_id.as_deref(),
             ) {
-                if matches!(message.role.as_str(), "assistant" | "reasoning") {
-                    let item_status = item.get("status").and_then(Value::as_str);
-                    let turn_status = turn.get("status").and_then(Value::as_str);
-                    let interrupted_turn = matches!(turn_status, Some("failed" | "interrupted" | "cancelled"));
-                    let interrupted_item = matches!(item_status, Some("inProgress" | "failed" | "interrupted" | "cancelled"));
-                    if interrupted_turn && interrupted_item {
-                        continue;
+                let item_status = item.get("status").and_then(Value::as_str);
+                let turn_status = turn.get("status").and_then(Value::as_str);
+                let interrupted_turn =
+                    matches!(turn_status, Some("failed" | "interrupted" | "cancelled"));
+                let interrupted_item = matches!(
+                    item_status,
+                    Some("inProgress" | "failed" | "interrupted" | "cancelled")
+                );
+                if matches!(message.role.as_str(), "assistant" | "reasoning")
+                    && interrupted_turn
+                    && interrupted_item
+                {
+                    continue;
+                }
+                if item
+                    .get("id")
+                    .and_then(Value::as_str)
+                    .map_or(true, |id| id.trim().is_empty())
+                {
+                    if message.role == "tool" {
+                        if let Some(call_id) = message.tool_call_id.as_deref() {
+                            message.id =
+                                super::codex_tool_call_message_id(turn_id.as_deref(), call_id);
+                        }
+                    } else if let Some(turn_id) =
+                        turn_id.as_deref().filter(|id| !id.trim().is_empty())
+                    {
+                        let key = (message.role.clone(), message.content.clone());
+                        let occurrence = fallback_item_occurrences.entry(key).or_default();
+                        message.id = super::codex_fallback_item_message_id(
+                            turn_id,
+                            &message.role,
+                            &message.content,
+                            *occurrence,
+                        );
+                        *occurrence += 1;
+                    } else if item.get("type").and_then(Value::as_str) == Some("contextCompaction")
+                    {
+                        // The live stream uses this stable marker when the provider omits both
+                        // the compaction item ID and its turn ID.
+                        message.id = "codex-context-compaction".to_string();
                     }
+                }
+                if matches!(message.role.as_str(), "assistant" | "reasoning") {
                     let item_terminal = item_status.is_some_and(is_terminal_native_status);
                     let turn_terminal = turn_status.is_some_and(is_terminal_native_status);
                     message.is_completed = Some(item_terminal || turn_terminal);
@@ -205,17 +244,10 @@ pub(super) fn app_server_compact_command_message(
         .get("id")
         .and_then(Value::as_str)
         .filter(|id| !id.trim().is_empty())
-        .or(turn_id)
         .map(str::to_string)
         .unwrap_or_else(|| format!("turn-{turn_index}-item-{item_index}"));
-    let mut message =
-        app_server_base_message(format!("codex-command-history-{source_id}"), timestamp);
-    message.role = "user".to_string();
-    message.message_type = Some(CODEX_COMMAND_MESSAGE_TYPE.to_string());
-    message.content = "/compact".to_string();
-    message.is_completed = Some(true);
-    message.codex_turn_id = turn_id.map(str::to_string);
-    message
+    let id = super::codex_command_message_id(turn_id, &source_id);
+    app_server_command_message(id, "/compact", timestamp, turn_id)
 }
 
 pub(super) fn app_server_goal_command_message(
@@ -224,16 +256,25 @@ pub(super) fn app_server_goal_command_message(
     turn_index: usize,
     turn_id: Option<&str>,
 ) -> ChatMessage {
-    let source_id = turn_id
-        .map(str::to_string)
-        .unwrap_or_else(|| format!("turn-{turn_index}"));
-    let mut message =
-        app_server_base_message(format!("codex-command-history-goal-{source_id}"), timestamp);
+    let source_id = format!("turn-{turn_index}");
+    let id = super::codex_command_message_id(turn_id, &source_id);
+    app_server_command_message(id, &format!("/goal {objective}"), timestamp, turn_id)
+}
+
+fn app_server_command_message(
+    id: String,
+    content: &str,
+    timestamp: &str,
+    turn_id: Option<&str>,
+) -> ChatMessage {
+    let mut message = app_server_base_message(id, timestamp);
     message.role = "user".to_string();
     message.message_type = Some(CODEX_COMMAND_MESSAGE_TYPE.to_string());
-    message.content = format!("/goal {objective}");
+    message.content = content.to_string();
     message.is_completed = Some(true);
-    message.codex_turn_id = turn_id.map(str::to_string);
+    message.codex_turn_id = turn_id
+        .filter(|id| !id.trim().is_empty())
+        .map(str::to_string);
     message
 }
 
@@ -257,16 +298,20 @@ pub(super) fn app_server_turn_error_message(
             .or_else(|| value.get("message").and_then(Value::as_str))
     });
     let text = match (status, error_text) {
-        ("failed", Some(message)) | ("interrupted", Some(message)) => message.to_string(),
+        ("failed", Some(message))
+        | ("interrupted", Some(message))
+        | ("cancelled", Some(message)) => message.to_string(),
         ("failed", None) => "Codex turn failed".to_string(),
         ("interrupted", None) => "Codex turn interrupted".to_string(),
+        ("cancelled", None) => "Codex turn failed".to_string(),
         _ => return None,
     };
     let id = turn
         .get("id")
         .and_then(Value::as_str)
-        .map(|id| format!("codex-turn-error-{id}"))
-        .unwrap_or_else(|| format!("codex-turn-error-{turn_index}"));
+        .filter(|id| !id.trim().is_empty())
+        .map(super::codex_turn_error_message_id)
+        .unwrap_or_else(|| super::codex_turn_error_message_id(&format!("index-{turn_index}")));
     let mut message = app_server_base_message(id, timestamp);
     message.role = "assistant".to_string();
     message.content = text.clone();
@@ -281,21 +326,19 @@ pub(super) fn app_server_turn_error_message(
 fn app_server_orphan_custom_tool_output_message(
     item: &Value,
     timestamp: &str,
-    turn_index: usize,
-    item_index: usize,
     turn_id: Option<&str>,
 ) -> ChatMessage {
     let call_id = custom_tool_output_call_id(item).unwrap_or("unknown-call");
     let output = codex_custom_tool_output(item)
         .map(codex_tool_payload_text)
         .unwrap_or_default();
-    let mut message = app_server_base_message(
-        format!(
-            "codex-custom-tool-output-{}-{turn_index}-{item_index}",
-            call_id
-        ),
-        timestamp,
-    );
+    let output_id = item
+        .get("id")
+        .and_then(Value::as_str)
+        .filter(|id| !id.trim().is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| super::codex_custom_tool_output_message_id(turn_id, call_id));
+    let mut message = app_server_base_message(output_id, timestamp);
     message.role = "tool".to_string();
     message.message_type = Some(CODEX_CUSTOM_TOOL_MESSAGE_TYPE.to_string());
     message.tool_call_id = Some(call_id.to_string());
@@ -303,7 +346,9 @@ fn app_server_orphan_custom_tool_output_message(
     message.tool_data = Some(output.clone());
     message.content = output;
     message.is_completed = Some(true);
-    message.codex_turn_id = turn_id.map(str::to_string);
+    message.codex_turn_id = turn_id
+        .filter(|id| !id.trim().is_empty())
+        .map(str::to_string);
     message
 }
 
@@ -322,7 +367,9 @@ pub(super) fn app_server_item_message(
         .map(str::to_string)
         .unwrap_or_else(|| format!("codex-{turn_index}-{item_index}"));
     let mut message = app_server_base_message(id, timestamp);
-    message.codex_turn_id = turn_id.map(str::to_string);
+    message.codex_turn_id = turn_id
+        .filter(|id| !id.trim().is_empty())
+        .map(str::to_string);
     message.message_type = codex_message_type(item).map(str::to_string);
     match kind {
         "userMessage" => {
diff --git a/app/flowix-desktop/src/agent_external/deepseek_harness/host_registry.rs b/app/flowix-desktop/src/agent_external/deepseek_harness/host_registry.rs
index 66f56f231..b19afe3d7 100644
--- a/app/flowix-desktop/src/agent_external/deepseek_harness/host_registry.rs
+++ b/app/flowix-desktop/src/agent_external/deepseek_harness/host_registry.rs
@@ -26,42 +26,8 @@ pub(crate) struct ProcessDshClientFactory;
 #[async_trait::async_trait]
 impl DshClientFactory for ProcessDshClientFactory {
     async fn spawn(&self, spec: &HostLaunchSpec) -> Result<Arc<dyn DshClient>, String> {
-        let (command, args) = app_server_command(&spec.dsh_home)?;
-        // Match the legacy host's strict child environment boundary. Do
-        // not leak arbitrary Desktop variables (especially credentials)
-        // into the App Server process.
-        let allowed = [
-            "PATH",
-            "Path",
-            "PATHEXT",
-            "SystemRoot",
-            "WINDIR",
-            "COMSPEC",
-            "TMPDIR",
-            "TMP",
-            "TEMP",
-            "LANG",
-            "LC_ALL",
-            "HOME",
-            "USERPROFILE",
-            "NODE_USE_ENV_PROXY",
-            "HTTP_PROXY",
-            "HTTPS_PROXY",
-            "ALL_PROXY",
-            "NO_PROXY",
-            "http_proxy",
-            "https_proxy",
-            "all_proxy",
-            "no_proxy",
-        ];
-        let mut env = allowed
-            .iter()
-            .filter_map(|key| {
-                std::env::var(key)
-                    .ok()
-                    .map(|value| ((*key).to_string(), value))
-            })
-            .collect::<std::collections::HashMap<_, _>>();
+        let launch = app_server_command(&spec.dsh_home)?;
+        let mut env = launch.environment;
         env.insert("FLOWIX_DSH_APPSERVER_STDIO".into(), "1".into());
         env.insert(
             "DSH_HOME".into(),
@@ -87,14 +53,23 @@ impl DshClientFactory for ProcessDshClientFactory {
             "FLOWIX_DSH_PLUGIN_SETTINGS_PATH".into(),
             spec.plugin_settings_path.to_string_lossy().into_owned(),
         );
-        let client = AppServerClient::spawn(&command, &args, &env).await?;
+        let client =
+            AppServerClient::spawn(&launch.executable.to_string_lossy(), &launch.args, &env)
+                .await?;
         let initialize =
             protocol::app_initialize_request(client.next_request_id(), env!("CARGO_PKG_VERSION"));
-        let initialized = client.request(initialize).await?;
+        let initialized = match client.request(initialize).await {
+            Ok(initialized) => initialized,
+            Err(error) => {
+                client.shutdown().await;
+                return Err(error);
+            }
+        };
         let version = initialized
             .get("protocolVersion")
             .and_then(serde_json::Value::as_u64);
         if version != Some(super::protocol::APP_SERVER_PROTOCOL_VERSION) {
+            client.shutdown().await;
             return Err(format!(
                 "dsh-appserver protocol version mismatch (server={version:?}, client={})",
                 super::protocol::APP_SERVER_PROTOCOL_VERSION
@@ -105,7 +80,7 @@ impl DshClientFactory for ProcessDshClientFactory {
     }
 }
 
-fn app_server_command(dsh_home: &std::path::Path) -> Result<(String, Vec<String>), String> {
+fn app_server_command(dsh_home: &std::path::Path) -> Result<crate::dsh::cli::DshCliLaunch, String> {
     if let Ok(command) = std::env::var("FLOWIX_DSH_APPSERVER_COMMAND") {
         let args = std::env::var("FLOWIX_DSH_APPSERVER_ARGS")
             .ok()
@@ -115,87 +90,20 @@ fn app_server_command(dsh_home: &std::path::Path) -> Result<(String, Vec<String>
             })
             .transpose()?
             .unwrap_or_default();
-        return Ok((command, args));
-    }
-
-    let launch = crate::dsh::managed_launch_spec()
-        .ok_or("DSH App Server is enabled but no managed DSH bundle is available".to_string())?;
-    // The child uses the per-session DSH_HOME below. Syncing only the durable
-    // install directory leaves that child on an old profile and lets the
-    // legacy SDK JSON-RPC server own model/config/read.
-    sync_flowix_profile(&launch.root, dsh_home)?;
-    let cli = launch
-        .cli_entrypoint
-        .ok_or("managed DSH bundle has no CLI entrypoint for App Server".to_string())?;
-    // The dsh CLI boots the named profile; dsh-appserver's profile config owns
-    // the stdio transport. `app-server` is not an upstream CLI subcommand and
-    // would be forwarded into the profile application as an unknown runtime
-    // argument.
-    let args = vec![
-        cli.to_string_lossy().into_owned(),
-        "--profile".into(),
-        "flowix".into(),
-    ];
-    // `executable` is the private Node binary for managed JS bundles. Native
-    // launchers can still provide an explicit command through the environment.
-    Ok((launch.executable.to_string_lossy().into_owned(), args))
-}
-
-fn sync_flowix_profile(
-    bundle_root: &std::path::Path,
-    dsh_home: &std::path::Path,
-) -> Result<(), String> {
-    let source = bundle_root.join("profile").join("flowix");
-    let target = dsh_home.join("profiles").join("flowix");
-    // Remove obsolete profile plugins instead of leaving them discoverable in
-    // a profile that is now exclusively owned by dsh-appserver.
-    for obsolete in [
-        target.join("node_modules/@flowix/dsh-flowix-bridge"),
-        target.join("node_modules/@deepseek-ai/dsh-sdk-jsonrpc-server"),
-    ] {
-        if obsolete.exists() {
-            std::fs::remove_dir_all(&obsolete).map_err(|error| {
-                format!("remove obsolete DSH plugin {}: {error}", obsolete.display())
-            })?;
-        }
-    }
-    for relative in [
-        std::path::Path::new("package.json"),
-        std::path::Path::new("cordis.patch.yml"),
-        std::path::Path::new("node_modules/dsh-appserver"),
-        std::path::Path::new("node_modules/dsh-flowix-memory"),
-    ] {
-        let from = source.join(relative);
-        let to = target.join(relative);
-        if !from.exists() {
-            return Err(format!("managed DSH profile is missing {}", from.display()));
-        }
-        copy_profile_tree(&from, &to)?;
+        return Ok(crate::dsh::cli::DshCliLaunch {
+            executable: PathBuf::from(command),
+            args,
+            environment: crate::dsh::cli::child_environment(),
+        });
     }
-    Ok(())
-}
 
-fn copy_profile_tree(source: &std::path::Path, target: &std::path::Path) -> Result<(), String> {
-    if source.is_dir() {
-        std::fs::create_dir_all(target).map_err(|error| {
-            format!("create DSH profile directory {}: {error}", target.display())
-        })?;
-        for entry in std::fs::read_dir(source)
-            .map_err(|error| format!("read DSH profile directory {}: {error}", source.display()))?
-        {
-            let entry = entry.map_err(|error| format!("read DSH profile entry: {error}"))?;
-            copy_profile_tree(&entry.path(), &target.join(entry.file_name()))?;
-        }
-    } else {
-        if let Some(parent) = target.parent() {
-            std::fs::create_dir_all(parent).map_err(|error| {
-                format!("create DSH profile parent {}: {error}", parent.display())
-            })?;
-        }
-        std::fs::copy(source, target)
-            .map_err(|error| format!("sync DSH profile {}: {error}", target.display()))?;
+    if !crate::dsh::flowix_profile_installed(dsh_home) {
+        return Err(
+            "DSH App Server profile is not installed; install it from Flowix Preferences"
+                .to_string(),
+        );
     }
-    Ok(())
+    crate::dsh::resolve_cli_launch(&["--profile", "flowix"])
 }
 
 pub(crate) struct HostRegistry {
@@ -544,4 +452,44 @@ mod tests {
         assert!(factory.client.lock().unwrap().as_ref().unwrap().is_closed());
         assert_eq!(registry.shutdown_all().await, 0);
     }
+
+    /// Run with FLOWIX_DSH_SMOKE_CLI and FLOWIX_DSH_SMOKE_HOME pointing at an
+    /// official npm-installed DSH and a disposable home containing the Flowix
+    /// profile. This covers the same resolver, environment and handshake used
+    /// for locally installed DSH users.
+    #[tokio::test]
+    #[ignore = "requires an official DSH CLI and disposable installed profile"]
+    async fn official_dsh_cli_starts_the_flowix_appserver_profile() {
+        let _env_lock = crate::agent_external::acquire_test_env_lock();
+        let cli = std::env::var("FLOWIX_DSH_SMOKE_CLI").expect("set FLOWIX_DSH_SMOKE_CLI");
+        let home = PathBuf::from(
+            std::env::var("FLOWIX_DSH_SMOKE_HOME").expect("set FLOWIX_DSH_SMOKE_HOME"),
+        );
+        let previous_cli = std::env::var_os("FLOWIX_DSH_CLI_PATH");
+        std::env::set_var("FLOWIX_DSH_CLI_PATH", &cli);
+        let spec = HostLaunchSpec {
+            session_root: home.join("sessions"),
+            settings_path: home.join("settings.yaml"),
+            credentials_path: home.join(".credentials.yaml"),
+            plugin_settings_path: home.join("plugin-settings.json"),
+            dsh_home: home,
+        };
+
+        let result = async {
+            let client = ProcessDshClientFactory.spawn(&spec).await?;
+            let request = protocol::model_settings_describe_request(client.next_request_id());
+            let settings = client.request(request).await;
+            client.shutdown().await;
+            settings
+        }
+        .await;
+
+        match previous_cli {
+            Some(value) => std::env::set_var("FLOWIX_DSH_CLI_PATH", value),
+            None => std::env::remove_var("FLOWIX_DSH_CLI_PATH"),
+        }
+        let settings =
+            result.expect("official DSH profile must complete handshake and read model settings");
+        assert!(settings.get("providers").is_some());
+    }
 }
diff --git a/app/flowix-desktop/src/agent_external/deepseek_harness/manager.rs b/app/flowix-desktop/src/agent_external/deepseek_harness/manager.rs
index 3a42798f3..ab0ee5543 100644
--- a/app/flowix-desktop/src/agent_external/deepseek_harness/manager.rs
+++ b/app/flowix-desktop/src/agent_external/deepseek_harness/manager.rs
@@ -145,9 +145,13 @@ impl DeepSeekHarnessManager {
         message: AgentUserMessage,
         app_handle: &tauri::AppHandle,
     ) -> Result<String, String> {
-        if !crate::dsh::status().installed {
+        let dsh_status = crate::dsh::status();
+        if !dsh_status.installed {
             return Err("DeepSeek Harness runtime is not installed".to_string());
         }
+        if !dsh_status.app_server_profile_installed {
+            return Err("DSH App Server profile is not installed; install it from Flowix Preferences".to_string());
+        }
 
         let thread_id = thread_id.to_string();
         let run_id = crate::agent_external::resolve_run_id(&thread_id, message.run_id.as_deref());
@@ -1124,45 +1128,6 @@ impl DeepSeekHarnessManager {
         Ok(())
     }
 
-    /// Move any key written by an older Flowix build into DSH, then remove
-    /// the duplicate only after DSH confirms ownership.
-    pub async fn migrate_legacy_credentials(
-        &self,
-        configs: &[crate::config::AiConfigFile],
-    ) -> Result<(), String> {
-        for config in configs {
-            let route = if config.model.provider_id.trim().is_empty() {
-                config.model.provider.trim()
-            } else {
-                config.model.provider_id.trim()
-            };
-            let Some(secret) = self
-                .user_config
-                .legacy_dsh_secret(route)
-                .map_err(|error| error.to_string())?
-                .filter(|value| !value.trim().is_empty())
-            else {
-                continue;
-            };
-            let reference = Self::credential_reference(&config.model);
-            if !self.credential_configured(&reference).await? {
-                let host = self.model_host().await?;
-                let result = timed_host_request(
-                    &host.client(),
-                    protocol::credential_set_request(host.next_request_id(), &reference, &secret),
-                )
-                .await;
-                result?;
-            }
-            if self.credential_configured(&reference).await? {
-                self.user_config
-                    .delete_legacy_dsh_secret(route)
-                    .map_err(|error| error.to_string())?;
-            }
-        }
-        Ok(())
-    }
-
     pub async fn persist_credential(&self, config: &AiModelConfig) -> Result<(), String> {
         let reference = Self::credential_reference(config);
         let route = if config.provider_id.trim().is_empty() {
diff --git a/app/flowix-desktop/src/agent_external/deepseek_harness/mod.rs b/app/flowix-desktop/src/agent_external/deepseek_harness/mod.rs
index 28623c10f..aa1125b56 100644
--- a/app/flowix-desktop/src/agent_external/deepseek_harness/mod.rs
+++ b/app/flowix-desktop/src/agent_external/deepseek_harness/mod.rs
@@ -16,4 +16,4 @@ mod transport;
 pub use config::resolve_runtime_config;
 pub use manager::{DeepSeekHarnessManager, DeepSeekHarnessSessionUsage};
 
-pub const AGENT_TYPE: &str = "deepseek-harness";
+pub const AGENT_TYPE: &str = "dsh";
diff --git a/app/flowix-desktop/src/agent_external/deepseek_harness/run_coordinator.rs b/app/flowix-desktop/src/agent_external/deepseek_harness/run_coordinator.rs
index e2ff484d9..7d95ab2fd 100644
--- a/app/flowix-desktop/src/agent_external/deepseek_harness/run_coordinator.rs
+++ b/app/flowix-desktop/src/agent_external/deepseek_harness/run_coordinator.rs
@@ -200,7 +200,7 @@ mod tests {
         runs.register("t", "r1", Some("s1"), Arc::new(AtomicBool::new(false)))
             .await.unwrap();
         runs.mark_stopping("t", "r1").await;
-        let snapshot = runs.running_threads("deepseek-harness").await;
+        let snapshot = runs.running_threads("dsh").await;
         assert_eq!(snapshot["t"].phase.as_deref(), Some("stopping"));
         assert!(runs.register("t", "r2", None, Arc::new(AtomicBool::new(false))).await.is_err());
         assert!(runs.remove_if_matches("t", "r1").await);
diff --git a/app/flowix-desktop/src/agent_external/lifecycle.rs b/app/flowix-desktop/src/agent_external/lifecycle.rs
index 5297826e4..014a803ae 100644
--- a/app/flowix-desktop/src/agent_external/lifecycle.rs
+++ b/app/flowix-desktop/src/agent_external/lifecycle.rs
@@ -233,7 +233,7 @@ mod tests {
             image_paths: Vec::new(),
             run_id: None,
             system_reminder_directory: None,
-            agent_type: Some("claude".to_string()),
+            agent_type: Some("claudecode".to_string()),
             runtime_config: None,
             permission_mode: None,
             codex_model: None,
diff --git a/app/flowix-desktop/src/agent_external/pi/config.rs b/app/flowix-desktop/src/agent_external/pi/config.rs
index 747f65192..00388cf05 100644
--- a/app/flowix-desktop/src/agent_external/pi/config.rs
+++ b/app/flowix-desktop/src/agent_external/pi/config.rs
@@ -1,5 +1,5 @@
 use serde::{Deserialize, Serialize};
-use serde_json::{json, Map, Value};
+use serde_json::{Map, Value, json};
 use std::fs::{self, OpenOptions};
 use std::io::Write;
 use std::path::Path;
@@ -14,6 +14,12 @@ pub struct PiModelEntry {
     #[serde(default)]
     pub name: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub subtitle: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub credit_multiplier: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider_icon_url: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub api: Option<String>,
     #[serde(default)]
     pub reasoning: bool,
@@ -30,8 +36,14 @@ pub struct PiModelEntry {
 pub struct PiProviderConfig {
     pub id: String,
     pub display_name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub icon_url: Option<String>,
     pub api: String,
     pub base_url: String,
+    /// Flowix-owned provider source, surfaced for settings UI classification.
+    /// Stored in Pi settings.json so Pi's native models.json stays provider-only.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
     #[serde(default)]
     pub api_key: Option<String>,
     #[serde(default)]
@@ -65,8 +77,10 @@ pub struct PiModelCatalog {
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PiFeatures {
-    pub code_mode: bool,
     pub tool_search: bool,
+    /// Read-only input for the one-time frontend preference migration.
+    #[serde(skip_deserializing, skip_serializing_if = "Option::is_none")]
+    pub legacy_code_mode: Option<bool>,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
@@ -79,9 +93,9 @@ pub struct PiMcpServer {
 pub fn features() -> Result<PiFeatures, String> {
     let dir = pi_config_dir()?;
     let settings = read_json(&dir.join("settings.json"))?;
-    let features: PiFeatures =
-        serde_json::from_value(settings.get("flowixFeatures").cloned().unwrap_or_default())
-            .unwrap_or_default();
+    let value = settings.get("flowixFeatures").cloned().unwrap_or_default();
+    let mut features: PiFeatures = serde_json::from_value(value.clone()).unwrap_or_default();
+    features.legacy_code_mode = value.get("codeMode").and_then(Value::as_bool);
     Ok(features)
 }
 
@@ -90,11 +104,26 @@ pub fn save_features(features: PiFeatures) -> Result<(), String> {
     fs::create_dir_all(&dir).map_err(|error| error.to_string())?;
     let path = dir.join("settings.json");
     let mut settings = read_json(&path)?;
-    settings["flowixFeatures"] =
-        serde_json::to_value(features).map_err(|error| error.to_string())?;
+    if !settings["flowixFeatures"].is_object() {
+        settings["flowixFeatures"] = json!({});
+    }
+    settings["flowixFeatures"]["toolSearch"] = json!(features.tool_search);
     write_json(&path, &settings)
 }
 
+pub fn clear_legacy_code_mode() -> Result<(), String> {
+    let path = pi_config_dir()?.join("settings.json");
+    let mut settings = read_json(&path)?;
+    let removed = settings
+        .get_mut("flowixFeatures")
+        .and_then(Value::as_object_mut)
+        .and_then(|features| features.remove("codeMode"));
+    if removed.is_some() {
+        write_json(&path, &settings)?;
+    }
+    Ok(())
+}
+
 fn mcp_config_path() -> Result<std::path::PathBuf, String> {
     Ok(pi_config_dir()?.join("mcp.json"))
 }
@@ -156,7 +185,10 @@ fn validate_mcp_server(name: &str, config: &Value) -> Result<(), String> {
         return Err("Pi MCP command and url values must be non-empty strings".into());
     }
     if command == url {
-        return Err("Configure exactly one Pi MCP transport: command (stdio) or url (streamable HTTP)".into());
+        return Err(
+            "Configure exactly one Pi MCP transport: command (stdio) or url (streamable HTTP)"
+                .into(),
+        );
     }
     if let Some(kind) = object.get("type").and_then(Value::as_str) {
         if !matches!(kind, "stdio" | "http" | "streamable-http") {
@@ -179,9 +211,11 @@ fn validate_mcp_server(name: &str, config: &Value) -> Result<(), String> {
         }
     }
     for key in ["env", "headers"] {
-        if object.get(key).and_then(Value::as_object).is_some_and(|values| {
-            values.values().any(|value| !value.is_string())
-        }) {
+        if object
+            .get(key)
+            .and_then(Value::as_object)
+            .is_some_and(|values| values.values().any(|value| !value.is_string()))
+        {
             return Err(format!("Pi MCP {key} values must be strings"));
         }
     }
@@ -203,7 +237,10 @@ fn validate_mcp_server(name: &str, config: &Value) -> Result<(), String> {
         }
     }
     if let Some(exposure) = object.get("exposure").and_then(Value::as_str) {
-        if !matches!(exposure, "codemode" | "codemode-deferred" | "deferred" | "direct" | "hidden") {
+        if !matches!(
+            exposure,
+            "codemode" | "codemode-deferred" | "deferred" | "direct" | "hidden"
+        ) {
             return Err("Pi MCP exposure must be codemode, deferred, direct or hidden".into());
         }
     }
@@ -215,7 +252,10 @@ pub fn save_mcp_server(name: &str, config: Value) -> Result<(), String> {
     let (path, mut file) = read_mcp_config()?;
     let servers = object_at(&mut file, "mcpServers")?;
     let normalized = name.replace('-', "_");
-    if servers.keys().any(|existing| existing != name && existing.replace('-', "_") == normalized) {
+    if servers
+        .keys()
+        .any(|existing| existing != name && existing.replace('-', "_") == normalized)
+    {
         return Err("Pi treats server names that differ only by - and _ as the same name".into());
     }
     servers.insert(name.to_string(), config);
@@ -224,7 +264,8 @@ pub fn save_mcp_server(name: &str, config: Value) -> Result<(), String> {
 
 pub fn delete_mcp_server(name: &str) -> Result<(), String> {
     let (path, mut file) = read_mcp_config()?;
-    let is_empty = if let Some(servers) = file.get_mut("mcpServers").and_then(Value::as_object_mut) {
+    let is_empty = if let Some(servers) = file.get_mut("mcpServers").and_then(Value::as_object_mut)
+    {
         servers.remove(name);
         servers.is_empty()
     } else {
@@ -343,20 +384,29 @@ pub fn list() -> Result<Vec<PiProviderConfig>, String> {
     let settings = read_json(&dir.join("settings.json"))?;
     let default_provider = settings.get("defaultProvider").and_then(Value::as_str);
     let default_model = settings.get("defaultModel").and_then(Value::as_str);
+    let cloud_provider_id = settings
+        .get("flowixCloudProviderId")
+        .and_then(Value::as_str);
     let providers = models
         .get("providers")
         .and_then(Value::as_object)
         .cloned()
         .unwrap_or_default();
+    let flowix_catalog = settings.get("flowixPiCatalog").and_then(Value::as_object);
     Ok(providers
         .into_iter()
         .filter_map(|(id, provider)| {
             let models = provider.get("models")?.as_array()?;
+            let provider_metadata = flowix_catalog.and_then(|catalog| catalog.get(&id));
+            let model_metadata = provider_metadata
+                .and_then(|metadata| metadata.get("models"))
+                .and_then(Value::as_object);
             let entries: Vec<PiModelEntry> =
                 models
                     .iter()
                     .filter_map(|entry| {
                         let id = entry.get("id")?.as_str()?.to_string();
+                        let metadata = model_metadata.and_then(|catalog| catalog.get(&id));
                         Some(PiModelEntry {
                             id,
                             name: entry
@@ -364,6 +414,18 @@ pub fn list() -> Result<Vec<PiProviderConfig>, String> {
                                 .and_then(Value::as_str)
                                 .unwrap_or_default()
                                 .to_string(),
+                            subtitle: metadata
+                                .and_then(|item| item.get("subtitle"))
+                                .and_then(Value::as_str)
+                                .map(str::to_string),
+                            credit_multiplier: metadata
+                                .and_then(|item| item.get("creditMultiplier"))
+                                .and_then(Value::as_f64)
+                                .filter(|value| value.is_finite() && (0.01..=10.0).contains(value)),
+                            provider_icon_url: metadata
+                                .and_then(|item| item.get("providerIconUrl"))
+                                .and_then(Value::as_str)
+                                .map(str::to_string),
                             api: entry.get("api").and_then(Value::as_str).map(str::to_string),
                             reasoning: entry
                                 .get("reasoning")
@@ -390,6 +452,10 @@ pub fn list() -> Result<Vec<PiProviderConfig>, String> {
                     .and_then(Value::as_str)
                     .unwrap_or(&id)
                     .to_string(),
+                icon_url: provider_metadata
+                    .and_then(|metadata| metadata.get("providerIconUrl"))
+                    .and_then(Value::as_str)
+                    .map(str::to_string),
                 api: provider
                     .get("api")
                     .and_then(Value::as_str)
@@ -400,6 +466,8 @@ pub fn list() -> Result<Vec<PiProviderConfig>, String> {
                     .and_then(Value::as_str)
                     .unwrap_or_default()
                     .to_string(),
+                source: (cloud_provider_id == Some(id.as_str()))
+                    .then(|| "flowix-cloud".to_string()),
                 api_key: None,
                 credential_configured: auth
                     .get(&id)
@@ -495,6 +563,7 @@ pub fn save(mut config: PiProviderConfig, app: &AppHandle) -> Result<(), String>
 
     let settings_path = dir.join("settings.json");
     let mut settings = read_json(&settings_path)?;
+    let mut settings_changed = false;
     if let Some(default_model) = config
         .default_model_id
         .as_deref()
@@ -502,12 +571,86 @@ pub fn save(mut config: PiProviderConfig, app: &AppHandle) -> Result<(), String>
     {
         settings["defaultProvider"] = json!(id);
         settings["defaultModel"] = json!(default_model);
-        write_json(&settings_path, &settings)?;
+        settings_changed = true;
     } else if settings.get("defaultProvider").and_then(Value::as_str) == Some(id.as_str()) {
         if let Some(settings) = settings.as_object_mut() {
             settings.remove("defaultProvider");
             settings.remove("defaultModel");
         }
+        settings_changed = true;
+    }
+    if config.source.as_deref() == Some("flowix-cloud") {
+        settings["flowixCloudProviderId"] = json!(id);
+        settings_changed = true;
+    }
+    let mut model_metadata = Map::new();
+    for model in &config.models {
+        let mut metadata = Map::new();
+        if let Some(subtitle) = model
+            .subtitle
+            .as_deref()
+            .filter(|value| !value.trim().is_empty())
+        {
+            metadata.insert("subtitle".into(), json!(subtitle.trim()));
+        }
+        if let Some(multiplier) = model
+            .credit_multiplier
+            .filter(|value| value.is_finite() && (0.01..=10.0).contains(value))
+        {
+            metadata.insert("creditMultiplier".into(), json!(multiplier));
+        }
+        if let Some(icon_url) = model
+            .provider_icon_url
+            .as_deref()
+            .filter(|value| !value.trim().is_empty())
+        {
+            metadata.insert("providerIconUrl".into(), json!(icon_url.trim()));
+        }
+        if !metadata.is_empty() {
+            model_metadata.insert(model.id.clone(), Value::Object(metadata));
+        }
+    }
+    let mut provider_metadata = Map::new();
+    if let Some(icon_url) = config
+        .icon_url
+        .as_deref()
+        .filter(|value| !value.trim().is_empty())
+    {
+        provider_metadata.insert("providerIconUrl".into(), json!(icon_url.trim()));
+    }
+    if !model_metadata.is_empty() {
+        provider_metadata.insert("models".into(), Value::Object(model_metadata));
+    }
+    if provider_metadata.is_empty() {
+        let removed = settings
+            .get_mut("flowixPiCatalog")
+            .and_then(Value::as_object_mut)
+            .is_some_and(|catalog| catalog.remove(&id).is_some());
+        if removed {
+            let catalog_empty = settings
+                .get("flowixPiCatalog")
+                .and_then(Value::as_object)
+                .is_some_and(Map::is_empty);
+            if catalog_empty {
+                settings
+                    .as_object_mut()
+                    .map(|settings| settings.remove("flowixPiCatalog"));
+            }
+            settings_changed = true;
+        }
+    } else {
+        let provider_metadata = Value::Object(provider_metadata);
+        let unchanged = settings
+            .get("flowixPiCatalog")
+            .and_then(Value::as_object)
+            .and_then(|catalog| catalog.get(&id))
+            == Some(&provider_metadata);
+        if !unchanged {
+            object_at(&mut settings, "flowixPiCatalog")?.insert(id.clone(), provider_metadata);
+            settings_changed = true;
+        }
+    }
+    if settings_changed {
         write_json(&settings_path, &settings)?;
     }
 
@@ -539,11 +682,41 @@ pub fn delete(provider_id: &str) -> Result<(), String> {
     write_json(&models_path, &models)?;
     let settings_path = dir.join("settings.json");
     let mut settings = read_json(&settings_path)?;
+    let mut settings_changed = false;
     if settings.get("defaultProvider").and_then(Value::as_str) == Some(id) {
         if let Some(settings) = settings.as_object_mut() {
             settings.remove("defaultProvider");
             settings.remove("defaultModel");
         }
+        settings_changed = true;
+    }
+    if settings
+        .get("flowixCloudProviderId")
+        .and_then(Value::as_str)
+        == Some(id)
+    {
+        if let Some(settings) = settings.as_object_mut() {
+            settings.remove("flowixCloudProviderId");
+        }
+        settings_changed = true;
+    }
+    let removed_catalog_metadata = settings
+        .get_mut("flowixPiCatalog")
+        .and_then(Value::as_object_mut)
+        .is_some_and(|catalog| catalog.remove(id).is_some());
+    if removed_catalog_metadata {
+        let catalog_empty = settings
+            .get("flowixPiCatalog")
+            .and_then(Value::as_object)
+            .is_some_and(Map::is_empty);
+        if catalog_empty {
+            settings
+                .as_object_mut()
+                .map(|settings| settings.remove("flowixPiCatalog"));
+        }
+        settings_changed = true;
+    }
+    if settings_changed {
         write_json(&settings_path, &settings)?;
     }
     let auth_path = dir.join("auth.json");
@@ -554,6 +727,201 @@ pub fn delete(provider_id: &str) -> Result<(), String> {
     write_json(&auth_path, &auth)
 }
 
+pub fn legacy_cloud_provider_id(api_base: &str) -> Result<Option<String>, String> {
+    let dir = pi_config_dir()?;
+    let models = read_json(&dir.join("models.json"))?;
+    let auth = read_json(&dir.join("auth.json"))?;
+    let provider_id = "flowix-cloud";
+    let expected_base_url = format!("{}/v1/ai", api_base.trim_end_matches('/'));
+    let provider = models
+        .get("providers")
+        .and_then(Value::as_object)
+        .and_then(|providers| providers.get(provider_id));
+    let looks_like_cloud_provider = provider.is_some_and(|provider| {
+        provider.get("name").and_then(Value::as_str) == Some("Flowix Cloud")
+            && provider.get("api").and_then(Value::as_str) == Some("openai-completions")
+            && provider.get("baseUrl").and_then(Value::as_str) == Some(&expected_base_url)
+    });
+    let has_cloud_credential = auth
+        .get(provider_id)
+        .and_then(|entry| entry.get("key"))
+        .and_then(Value::as_str)
+        .is_some_and(|key| key.starts_with("fai_"));
+    Ok((looks_like_cloud_provider && has_cloud_credential).then(|| provider_id.to_string()))
+}
+
+fn collect_cloud_provider_ids(
+    providers: impl IntoIterator<Item = (String, bool)>,
+    marked_provider_id: Option<&str>,
+    legacy_provider_id: Option<&str>,
+) -> Vec<String> {
+    let mut ids: Vec<String> = providers
+        .into_iter()
+        .filter_map(|(id, is_cloud)| is_cloud.then_some(id))
+        .collect();
+    for id in [marked_provider_id, legacy_provider_id]
+        .into_iter()
+        .flatten()
+        .map(str::trim)
+        .filter(|id| !id.is_empty())
+    {
+        if !ids.iter().any(|existing| existing == id) {
+            ids.push(id.to_string());
+        }
+    }
+    ids
+}
+
+/// Remove every Flowix Cloud Pi provider, including providers identified by
+/// the settings marker and the legacy provider shape.
+pub fn delete_cloud_providers(api_base: &str) -> Result<bool, String> {
+    let providers = list()?.into_iter().map(|provider| {
+        let is_cloud = provider.source.as_deref() == Some("flowix-cloud");
+        (provider.id, is_cloud)
+    });
+    let settings = read_json(&pi_config_dir()?.join("settings.json"))?;
+    let marked_provider_id = settings
+        .get("flowixCloudProviderId")
+        .and_then(Value::as_str);
+    let legacy_provider_id = legacy_cloud_provider_id(api_base)?;
+    let provider_ids =
+        collect_cloud_provider_ids(providers, marked_provider_id, legacy_provider_id.as_deref());
+    if provider_ids.is_empty() {
+        return Ok(false);
+    }
+    for provider_id in provider_ids {
+        delete(&provider_id)?;
+    }
+    Ok(true)
+}
+
+pub fn is_flowix_cloud_provider(provider_id: Option<&str>, api_base: &str) -> Result<bool, String> {
+    let dir = pi_config_dir()?;
+    let settings = read_json(&dir.join("settings.json"))?;
+    let selected_provider = provider_id
+        .filter(|value| !value.trim().is_empty())
+        .or_else(|| settings.get("defaultProvider").and_then(Value::as_str));
+    let Some(selected_provider) = selected_provider else {
+        return Ok(false);
+    };
+    let providers = list()?;
+    if providers.iter().any(|provider| {
+        provider.id == selected_provider && provider.source.as_deref() == Some("flowix-cloud")
+    }) {
+        return Ok(true);
+    }
+    Ok(legacy_cloud_provider_id(api_base)?.as_deref() == Some(selected_provider))
+}
+
+pub fn save_cloud_credential(
+    app: &AppHandle,
+    api_base: &str,
+    credential: flowix_sync::CloudAiCredential,
+) -> Result<(), String> {
+    let api_base = api_base.trim_end_matches('/');
+    let providers = list()?;
+    let legacy_cloud_id = legacy_cloud_provider_id(api_base)?;
+    let settings = read_json(&pi_config_dir()?.join("settings.json"))?;
+    let catalog = if credential.models.is_empty() {
+        vec![credential.model.clone()]
+    } else {
+        credential.models.clone()
+    };
+    let provider_icon_url = credential
+        .provider
+        .as_ref()
+        .and_then(|provider| provider.icon_url.clone());
+    let model_ids: Vec<String> = catalog.iter().map(|model| model.id.clone()).collect();
+    let current_cloud = providers
+        .iter()
+        .find(|provider| provider.source.as_deref() == Some("flowix-cloud"))
+        .or_else(|| {
+            legacy_cloud_id
+                .as_deref()
+                .and_then(|id| providers.iter().find(|provider| provider.id == id))
+        });
+    let saved_default = current_cloud
+        .and_then(|provider| provider.default_model_id.clone())
+        .filter(|id| model_ids.iter().any(|model_id| model_id == id));
+    let default_model_id = saved_default
+        .or_else(|| {
+            model_ids
+                .iter()
+                .find(|id| **id == credential.model.id)
+                .cloned()
+        })
+        .or_else(|| model_ids.first().cloned());
+    let provider_id = current_cloud
+        .map(|provider| provider.id.clone())
+        .unwrap_or_else(|| {
+            let existing_ids: std::collections::HashSet<&str> = providers
+                .iter()
+                .map(|provider| provider.id.as_str())
+                .collect();
+            let base_id = "flowix-cloud-member";
+            if !existing_ids.contains(base_id) {
+                return base_id.to_string();
+            }
+            let mut suffix = 2;
+            loop {
+                let candidate = format!("{base_id}-{suffix}");
+                if !existing_ids.contains(candidate.as_str()) {
+                    return candidate;
+                }
+                suffix += 1;
+            }
+        });
+    let default_model_id = if current_cloud.is_some()
+        && settings.get("defaultProvider").and_then(Value::as_str) != Some(provider_id.as_str())
+    {
+        None
+    } else {
+        default_model_id
+    };
+    save(
+        PiProviderConfig {
+            id: provider_id,
+            display_name: "Flowix Cloud".into(),
+            icon_url: provider_icon_url,
+            api: "openai-completions".into(),
+            base_url: format!("{api_base}/v1/ai"),
+            source: Some("flowix-cloud".into()),
+            api_key: Some(credential.api_key),
+            credential_configured: true,
+            default_model_id,
+            models: catalog
+                .into_iter()
+                .map(|model| {
+                    let id = model.id;
+                    let name = model
+                        .title
+                        .filter(|title| !title.trim().is_empty())
+                        .unwrap_or_else(|| id.clone());
+                    PiModelEntry {
+                        id,
+                        name,
+                        subtitle: model
+                            .subtitle
+                            .filter(|subtitle| !subtitle.trim().is_empty()),
+                        credit_multiplier: model
+                            .credit_multiplier
+                            .filter(|value| value.is_finite() && (0.01..=10.0).contains(value)),
+                        provider_icon_url: model
+                            .provider_icon_url
+                            .filter(|url| !url.trim().is_empty()),
+                        api: None,
+                        reasoning: false,
+                        vision: false,
+                        context_window: None,
+                        max_tokens: None,
+                    }
+                })
+                .collect(),
+        },
+        app,
+    )
+}
+
 pub async fn test_connection(config: PiProviderConfig) -> Result<u64, String> {
     let dir = pi_config_dir()?;
     let auth = read_json(&dir.join("auth.json"))?;
@@ -677,6 +1045,9 @@ pub async fn discover_models(config: PiProviderConfig) -> Result<Vec<PiModelEntr
                     .unwrap_or_default()
                     .to_string(),
                 id,
+                subtitle: None,
+                credit_multiplier: None,
+                provider_icon_url: None,
                 reasoning: false,
                 vision: false,
                 api: None,
@@ -686,3 +1057,30 @@ pub async fn discover_models(config: PiProviderConfig) -> Result<Vec<PiModelEntr
         })
         .collect())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::collect_cloud_provider_ids;
+
+    #[test]
+    fn cloud_provider_cleanup_includes_marked_and_legacy_ids_without_duplicates() {
+        let ids = collect_cloud_provider_ids(
+            [
+                ("flowix-cloud-member".to_string(), true),
+                ("custom-provider".to_string(), false),
+            ],
+            Some("flowix-cloud-member"),
+            Some("flowix-cloud"),
+        );
+
+        assert_eq!(ids, ["flowix-cloud-member", "flowix-cloud"]);
+    }
+
+    #[test]
+    fn cloud_provider_cleanup_ignores_empty_markers_and_non_cloud_providers() {
+        let ids =
+            collect_cloud_provider_ids([("custom-provider".to_string(), false)], Some("  "), None);
+
+        assert!(ids.is_empty());
+    }
+}
diff --git a/app/flowix-desktop/src/agent_external/pi/mod.rs b/app/flowix-desktop/src/agent_external/pi/mod.rs
index 12d58950c..b26886d44 100644
--- a/app/flowix-desktop/src/agent_external/pi/mod.rs
+++ b/app/flowix-desktop/src/agent_external/pi/mod.rs
@@ -1,7 +1,7 @@
 mod runtime;
 mod skill_resources;
 
-pub use runtime::installed_flowix_pi_binary;
+pub(crate) use runtime::resolve_pi_binary;
 pub use runtime::{PiHistoryPage, PiHistoryRevision, PiRpcManager, PiSessionSnapshot};
 pub mod config;
 
diff --git a/app/flowix-desktop/src/agent_external/pi/runtime.rs b/app/flowix-desktop/src/agent_external/pi/runtime.rs
index 26e5aaf3a..fdbff9d29 100644
--- a/app/flowix-desktop/src/agent_external/pi/runtime.rs
+++ b/app/flowix-desktop/src/agent_external/pi/runtime.rs
@@ -1,5 +1,6 @@
 use std::collections::{HashMap, VecDeque};
-use std::path::{Path, PathBuf};
+use std::future::Future;
+use std::path::PathBuf;
 use std::process::Stdio;
 use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};
 use std::sync::Arc;
@@ -7,8 +8,8 @@ use std::sync::Arc;
 use base64::Engine;
 use serde_json::Value;
 use sha2::{Digest, Sha256};
-use tauri::Manager;
-use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
+use tauri::{Emitter, Manager};
+use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncReadExt, AsyncWriteExt, BufReader};
 use tokio::process::{ChildStdin, Command};
 use tokio::sync::{mpsc, oneshot, Mutex, OwnedMutexGuard};
 use tokio::time::Duration;
@@ -25,8 +26,8 @@ use crate::agent_wire::{AgentChunk, AgentMessageAttachment, AgentUserMessage, Ru
 
 const PI_IDLE_SESSION_TTL_MS: i64 = 10 * 60 * 1000;
 const PI_RPC_REQUEST_TIMEOUT: Duration = Duration::from_secs(15);
-const PI_HISTORY_LOCK_TIMEOUT: Duration = Duration::from_secs(30);
 const PI_ABORT_SETTLE_TIMEOUT: Duration = Duration::from_secs(5);
+const PI_STDERR_TAIL_BYTES: usize = 64 * 1024;
 const PI_FORK_TIMEOUT: Duration = Duration::from_secs(20);
 
 const PI_FORK_EXTENSION: &str = r#"
@@ -290,6 +291,7 @@ struct PiSessionConfig {
     tool_search: bool,
     provider: Option<String>,
     model: Option<String>,
+    cloud_auth_generation: Option<u64>,
     thinking: Option<String>,
     startup_resources: PiStartupResources,
 }
@@ -308,6 +310,17 @@ pub struct PiSessionSnapshot {
     revision: PiHistoryRevision,
 }
 
+fn empty_pi_session_snapshot() -> PiSessionSnapshot {
+    PiSessionSnapshot {
+        messages: Vec::new(),
+        revision: PiHistoryRevision {
+            session_id: String::new(),
+            append_cursor: None,
+            leaf_id: None,
+        },
+    }
+}
+
 #[derive(serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PiHistoryPage {
@@ -390,6 +403,28 @@ async fn read_pi_rpc_record<R: AsyncBufRead + Unpin>(
     }
 }
 
+/// Keep diagnostics available while the process is alive, with bounded memory.
+async fn capture_pi_stderr<R: AsyncRead + Unpin>(
+    mut reader: R,
+    captured: Arc<Mutex<String>>,
+) -> std::io::Result<()> {
+    let mut tail = Vec::new();
+    let mut chunk = [0_u8; 4096];
+    loop {
+        let count = reader.read(&mut chunk).await?;
+        if count == 0 {
+            return Ok(());
+        }
+        tail.extend_from_slice(&chunk[..count]);
+        if tail.len() > PI_STDERR_TAIL_BYTES {
+            tail.drain(..tail.len() - PI_STDERR_TAIL_BYTES);
+        }
+        // Decode the retained bytes together so a UTF-8 character split across
+        // reads is restored once its remaining bytes arrive.
+        *captured.lock().await = String::from_utf8_lossy(&tail).into_owned();
+    }
+}
+
 #[derive(Default)]
 struct PiEntriesCache {
     entries: Arc<Vec<Value>>,
@@ -440,7 +475,6 @@ struct PiSession {
     config: PiSessionConfig,
     stdin: Arc<Mutex<ChildStdin>>,
     records: Mutex<mpsc::UnboundedReceiver<Result<Value, String>>>,
-    deferred_records: Mutex<VecDeque<Value>>,
     response_waiters: Arc<Mutex<HashMap<String, oneshot::Sender<Value>>>>,
     entries_cache: Mutex<PiEntriesCache>,
     child: Mutex<tokio::process::Child>,
@@ -457,6 +491,18 @@ impl PiSession {
     }
 
     async fn request(&self, id: &str, value: &Value) -> Result<Value, String> {
+        let response = self.request_response(id, value).await?;
+        if response.get("success").and_then(Value::as_bool) != Some(true) {
+            return Err(response
+                .get("error")
+                .and_then(Value::as_str)
+                .unwrap_or("Pi rejected the RPC command")
+                .to_string());
+        }
+        Ok(response)
+    }
+
+    async fn request_response(&self, id: &str, value: &Value) -> Result<Value, String> {
         let (sender, receiver) = oneshot::channel();
         self.response_waiters
             .lock()
@@ -474,13 +520,6 @@ impl PiSession {
                 return Err("Pi RPC command timed out".into());
             }
         };
-        if response.get("success").and_then(Value::as_bool) != Some(true) {
-            return Err(response
-                .get("error")
-                .and_then(Value::as_str)
-                .unwrap_or("Pi rejected the RPC command")
-                .to_string());
-        }
         Ok(response)
     }
 
@@ -501,9 +540,6 @@ impl PiSession {
     }
 
     async fn next_record(&self) -> Result<Value, String> {
-        if let Some(record) = self.deferred_records.lock().await.pop_front() {
-            return Ok(record);
-        }
         self.records
             .lock()
             .await
@@ -512,10 +548,9 @@ impl PiSession {
             .ok_or_else(|| "Pi RPC event reader closed".to_string())?
     }
 
-    /// Called only by the owner of `operation`. Read responses from the same
-    /// receiver and preserve interleaved agent events for the main event loop.
+    /// Serialize cursor updates while allowing the read RPC to run alongside
+    /// a prompt and its streamed events.
     async fn session_entries(&self) -> Result<(Arc<Vec<Value>>, Option<String>), String> {
-        static REQUEST_SEQUENCE: AtomicU64 = AtomicU64::new(0);
         let mut cache = self.entries_cache.lock().await;
         // The cursor follows append order, not the active leaf: branch switches
         // can move the leaf backwards without changing the append-only log.
@@ -526,23 +561,12 @@ impl PiSession {
             .and_then(Value::as_str)
             .map(str::to_owned);
         loop {
-            let request_id = format!(
-                "flowix-entries-{}",
-                REQUEST_SEQUENCE.fetch_add(1, Ordering::Relaxed)
-            );
+            let request_id = format!("flowix-entries-{}", next_pi_rpc_id());
             let mut request = serde_json::json!({"id": request_id, "type": "get_entries"});
             if let Some(cursor) = &since {
                 request["since"] = Value::String(cursor.clone());
             }
-            self.write(&request).await?;
-            let mut records = self.records.lock().await;
-            let mut deferred = self.deferred_records.lock().await;
-            let response = tokio::time::timeout(
-                PI_RPC_REQUEST_TIMEOUT,
-                receive_rpc_response(&mut records, &mut deferred, &request_id),
-            )
-            .await
-            .map_err(|_| "Pi session entries RPC timed out".to_string())??;
+            let response = self.request_response(&request_id, &request).await?;
             if response.get("success").and_then(Value::as_bool) != Some(true) {
                 if since.take().is_some() {
                     // A stale cursor or an older runtime can be recovered with
@@ -568,6 +592,17 @@ impl PiSession {
         }
     }
 
+    async fn session_messages(&self) -> Result<Vec<Value>, String> {
+        let request_id = format!("flowix-messages-{}", next_pi_rpc_id());
+        let request = serde_json::json!({"id":request_id, "type":"get_messages"});
+        let response = self.request(&request_id, &request).await?;
+        response
+            .pointer("/data/messages")
+            .and_then(Value::as_array)
+            .cloned()
+            .ok_or_else(|| "Pi get_messages response did not include messages".to_string())
+    }
+
     async fn is_alive(&self) -> bool {
         !self.invalidated.load(Ordering::Acquire)
             && matches!(self.child.lock().await.try_wait(), Ok(None))
@@ -607,6 +642,7 @@ struct ActivePiRun {
     run_id: String,
     started_at: i64,
     session: Mutex<Option<Arc<PiSession>>>,
+    session_state: tokio::sync::watch::Sender<Option<Arc<PiSession>>>,
     session_id: Mutex<Option<String>>,
     queued_messages: Mutex<HashMap<String, PiQueuedMessage>>,
     queue_lock: Mutex<()>,
@@ -633,6 +669,21 @@ struct PiProjectedUserMessage {
 }
 
 impl ActivePiRun {
+    async fn wait_for_session(&self) -> Option<Arc<PiSession>> {
+        let mut session_state = self.session_state.subscribe();
+        loop {
+            if let Some(session) = session_state.borrow().clone() {
+                return Some(session);
+            }
+            if self.finalizing.load(Ordering::Acquire) {
+                return None;
+            }
+            if session_state.changed().await.is_err() {
+                return None;
+            }
+        }
+    }
+
     async fn take_queued_user_message(&self, native_text: &str) -> Option<PiProjectedUserMessage> {
         let _queue_guard = self.queue_lock.lock().await;
         let mut queued = self.queued_messages.lock().await;
@@ -676,6 +727,51 @@ pub struct PiRpcManager {
     active_runs: Mutex<HashMap<String, Arc<ActivePiRun>>>,
     shutting_down: AtomicBool,
     history_snapshots: Mutex<VecDeque<(String, Arc<PiSessionSnapshot>)>>,
+    cloud_credential_generation: Mutex<Option<u64>>,
+    startup_cloud_refresh_results: Mutex<HashMap<u64, Result<bool, String>>>,
+}
+
+async fn run_startup_cloud_refresh_once<F, Fut>(
+    results: &Mutex<HashMap<u64, Result<bool, String>>>,
+    generation: u64,
+    refresh: F,
+) -> Result<bool, String>
+where
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<bool, String>>,
+{
+    // Keep the lock while refreshing so concurrent WebViews await the same
+    // result, including a failure, instead of treating an in-flight attempt
+    // as a successful refresh.
+    let mut results = results.lock().await;
+    if let Some(result) = results.get(&generation) {
+        return result.clone();
+    }
+
+    let result = refresh().await;
+    results.insert(generation, result.clone());
+    result
+}
+
+async fn run_startup_cloud_credential_refresh_once<F, Fut>(
+    results: &Mutex<HashMap<u64, Result<bool, String>>>,
+    credential_generation: &Mutex<Option<u64>>,
+    generation: u64,
+    refresh: F,
+) -> Result<bool, String>
+where
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<(), String>>,
+{
+    run_startup_cloud_refresh_once(results, generation, || async {
+        // Startup refreshes the live model catalog even if this process has
+        // already created a credential for the current Cloud login.
+        let mut credential_generation = credential_generation.lock().await;
+        refresh().await?;
+        *credential_generation = Some(generation);
+        Ok(true)
+    })
+    .await
 }
 
 #[async_trait::async_trait]
@@ -715,20 +811,6 @@ impl ExternalLifecycleEmitter for PiRpcManager {
 
 impl PiRpcManager {
     pub fn new(thread_manager: Arc<ThreadManager>) -> Self {
-        #[cfg(windows)]
-        {
-            static INITIALIZE_SESSIONS: std::sync::Once = std::sync::Once::new();
-            INITIALIZE_SESSIONS.call_once(|| {
-                if let Some(local) = std::env::var_os("LOCALAPPDATA") {
-                    if let Err(error) =
-                        crate::runtime_state::migrate_pi_sessions(std::path::Path::new(&local))
-                    {
-                        // Legacy conversations remain accessible in place.
-                        tracing::warn!("Pi session migration deferred: {error}");
-                    }
-                }
-            });
-        }
         Self {
             thread_manager,
             sessions: Mutex::new(HashMap::new()),
@@ -737,7 +819,185 @@ impl PiRpcManager {
             active_runs: Mutex::new(HashMap::new()),
             shutting_down: AtomicBool::new(false),
             history_snapshots: Mutex::new(VecDeque::new()),
+            cloud_credential_generation: Mutex::new(None),
+            startup_cloud_refresh_results: Mutex::new(HashMap::new()),
+        }
+    }
+
+    pub async fn connect_cloud_model_provider(
+        &self,
+        app: &tauri::AppHandle,
+        api_base: &str,
+    ) -> Result<(), String> {
+        let app_state = app.state::<crate::app::state::AppState>();
+        let cloud_sync = app_state.cloud_sync.clone();
+        let generation = cloud_sync.ai_credential_session_generation();
+        drop(app_state);
+
+        let mut cached_generation = self.cloud_credential_generation.lock().await;
+        self.create_and_save_cloud_credential(app, api_base, &cloud_sync, generation)
+            .await?;
+        *cached_generation = Some(generation);
+        Ok(())
+    }
+
+    /// Remove the local Flowix Cloud provider and its credential after logout.
+    pub async fn disconnect_cloud_model_provider(
+        &self,
+        app: &tauri::AppHandle,
+        api_base: &str,
+        logout_generation: u64,
+    ) -> Result<(), String> {
+        // Serialize with credential creation and refresh before reading the
+        // provider files, so a concurrent save cannot slip past this cleanup.
+        let mut cached_generation = self.cloud_credential_generation.lock().await;
+        let app_state = app.state::<crate::app::state::AppState>();
+        let cloud_sync = app_state.cloud_sync.clone();
+        drop(app_state);
+        if cloud_sync.ai_credential_session_generation() != logout_generation
+            || cloud_sync
+                .state()
+                .map_err(|error| error.to_string())?
+                .authenticated
+        {
+            return Ok(());
+        }
+        *cached_generation = None;
+        if super::config::delete_cloud_providers(api_base)? {
+            let _ = app.emit(
+                crate::commands::settings::USER_CONFIG_CHANGED_EVENT,
+                "pi_config",
+            );
         }
+        Ok(())
+    }
+
+    /// Refresh the saved Flowix Cloud model metadata once after workspace startup.
+    /// The generation guard deduplicates calls from multiple content WebViews.
+    pub async fn refresh_cloud_model_provider_at_startup(
+        &self,
+        app: &tauri::AppHandle,
+        api_base: &str,
+    ) -> Result<bool, String> {
+        let has_cloud_provider = super::config::list()?
+            .iter()
+            .any(|provider| provider.source.as_deref() == Some("flowix-cloud"));
+        if !has_cloud_provider {
+            return Ok(false);
+        }
+
+        let app_state = app.state::<crate::app::state::AppState>();
+        let cloud_sync = app_state.cloud_sync.clone();
+        if !cloud_sync
+            .state()
+            .map_err(|error| error.to_string())?
+            .authenticated
+        {
+            return Ok(false);
+        }
+        let generation = cloud_sync.ai_credential_session_generation();
+        drop(app_state);
+
+        run_startup_cloud_credential_refresh_once(
+            &self.startup_cloud_refresh_results,
+            &self.cloud_credential_generation,
+            generation,
+            || async {
+                self.create_and_save_cloud_credential(app, api_base, &cloud_sync, generation)
+                    .await
+            },
+        )
+        .await
+    }
+
+    /// Refresh the saved Flowix Cloud model catalog on an explicit user request.
+    pub async fn refresh_cloud_model_provider(
+        &self,
+        app: &tauri::AppHandle,
+        api_base: &str,
+    ) -> Result<bool, String> {
+        let has_cloud_provider = super::config::list()?
+            .iter()
+            .any(|provider| provider.source.as_deref() == Some("flowix-cloud"));
+        if !has_cloud_provider {
+            return Ok(false);
+        }
+
+        let app_state = app.state::<crate::app::state::AppState>();
+        let cloud_sync = app_state.cloud_sync.clone();
+        if !cloud_sync
+            .state()
+            .map_err(|error| error.to_string())?
+            .authenticated
+        {
+            return Ok(false);
+        }
+        let generation = cloud_sync.ai_credential_session_generation();
+        drop(app_state);
+
+        let mut cached_generation = self.cloud_credential_generation.lock().await;
+        self.create_and_save_cloud_credential(app, api_base, &cloud_sync, generation)
+            .await?;
+        *cached_generation = Some(generation);
+        Ok(true)
+    }
+
+    async fn ensure_cloud_credential(
+        &self,
+        app: &tauri::AppHandle,
+        provider_id: Option<&str>,
+        api_base: &str,
+    ) -> Result<Option<u64>, String> {
+        if !super::config::is_flowix_cloud_provider(provider_id, api_base)? {
+            return Ok(None);
+        }
+        let app_state = app.state::<crate::app::state::AppState>();
+        let cloud_sync = app_state.cloud_sync.clone();
+        let generation = cloud_sync.ai_credential_session_generation();
+        drop(app_state);
+        let mut cached_generation = self.cloud_credential_generation.lock().await;
+        if *cached_generation == Some(generation) {
+            return Ok(Some(generation));
+        }
+
+        self.create_and_save_cloud_credential(app, api_base, &cloud_sync, generation)
+            .await?;
+        *cached_generation = Some(generation);
+        Ok(Some(generation))
+    }
+
+    async fn create_and_save_cloud_credential(
+        &self,
+        app: &tauri::AppHandle,
+        api_base: &str,
+        cloud_sync: &flowix_sync::SyncManager,
+        generation: u64,
+    ) -> Result<(), String> {
+        let credential = cloud_sync
+            .create_ai_credential()
+            .await
+            .map_err(|error| error.to_string())?;
+        if cloud_sync.ai_credential_session_generation() != generation {
+            return Err(
+                "Flowix Cloud account changed while preparing the Pi model; retry the request"
+                    .into(),
+            );
+        }
+        if let Err(error) = super::config::save_cloud_credential(app, api_base, credential) {
+            if cloud_sync.ai_credential_session_generation() == generation {
+                if let Err(revoke_error) = cloud_sync.revoke_ai_credential().await {
+                    tracing::warn!(
+                        "failed to revoke an unconfigured Flowix Cloud Pi credential: {revoke_error}"
+                    );
+                }
+            }
+            return Err(error);
+        }
+        let _ = app.emit(
+            crate::commands::settings::USER_CONFIG_CHANGED_EVENT,
+            "pi_config",
+        );
+        Ok(())
     }
 
     pub async fn queue_message(
@@ -989,13 +1249,11 @@ impl PiRpcManager {
             session.shutdown(thread_id).await;
         }
         let mut deleted = false;
-        for candidate in pi_session_candidates(thread_id)? {
-            match std::fs::remove_dir_all(candidate) {
-                Ok(()) => deleted = true,
-                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
-                Err(error) => {
-                    return Err(format!("could not delete Pi conversation session: {error}"));
-                }
+        match std::fs::remove_dir_all(pi_session_dir(thread_id)?) {
+            Ok(()) => deleted = true,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => {
+                return Err(format!("could not delete Pi conversation session: {error}"));
             }
         }
         Ok(deleted)
@@ -1156,10 +1414,7 @@ impl PiRpcManager {
         let stderr = Arc::new(Mutex::new(String::new()));
         let stderr_capture = stderr.clone();
         tokio::spawn(async move {
-            let mut reader = BufReader::new(stderr_pipe);
-            let mut captured = String::new();
-            let _ = reader.read_to_string(&mut captured).await;
-            *stderr_capture.lock().await = captured;
+            let _ = capture_pi_stderr(stderr_pipe, stderr_capture).await;
         });
 
         let session = Arc::new(PiSession {
@@ -1167,7 +1422,6 @@ impl PiRpcManager {
             config: config.clone(),
             stdin,
             records: Mutex::new(record_rx),
-            deferred_records: Mutex::new(VecDeque::new()),
             response_waiters,
             entries_cache: Mutex::new(PiEntriesCache::default()),
             child: Mutex::new(child),
@@ -1502,17 +1756,12 @@ impl PiRpcManager {
             .get_external_session(thread_id, AGENT_TYPE)
             .await
             .map_err(|error| error.to_string())?;
-        let has_session =
-            mapped_session.is_some() || self.sessions.lock().await.contains_key(thread_id);
+        let active_run = self.active_runs.lock().await.get(thread_id).cloned();
+        let has_session = mapped_session.is_some()
+            || self.sessions.lock().await.contains_key(thread_id)
+            || active_run.is_some();
         if !has_session {
-            return Ok(PiSessionSnapshot {
-                messages: Vec::new(),
-                revision: PiHistoryRevision {
-                    session_id: String::new(),
-                    append_cursor: None,
-                    leaf_id: None,
-                },
-            });
+            return Ok(empty_pi_session_snapshot());
         }
         let cwd = self
             .thread_manager
@@ -1528,6 +1777,7 @@ impl PiRpcManager {
             tool_search: false,
             provider: None,
             model: None,
+            cloud_auth_generation: None,
             thinking: None,
             startup_resources: skill_resources::capture(
                 &cwd,
@@ -1535,72 +1785,71 @@ impl PiRpcManager {
                 &resolve_pi_session_dir(thread_id, true)?,
             )?,
         };
-        let session = self.ensure_session(app, thread_id, config, true).await?;
-        let _operation = tokio::time::timeout(
-            PI_HISTORY_LOCK_TIMEOUT,
-            self.lock_session_operation(thread_id, &session),
-        )
-        .await
-        .map_err(|_| {
-            "Pi history read timed out waiting for the active turn to finish".to_string()
-        })??;
-        session.touch();
-        let request_id = format!("flowix-history-{}", chrono::Utc::now().timestamp_millis());
-        if let Err(error) = session
-            .write(&serde_json::json!({"id":request_id,"type":"get_messages"}))
-            .await
-        {
-            drop(_operation);
-            self.remove_session_if_same(thread_id, &session).await;
-            return Err(error);
-        }
-        let response = tokio::time::timeout(PI_RPC_REQUEST_TIMEOUT, async {
-            loop {
-                let value = session.next_record().await?;
-                if value.get("id").and_then(Value::as_str) == Some(&request_id)
-                    && value.get("type").and_then(Value::as_str) == Some("response")
-                {
-                    return Ok::<Value, String>(value);
+        let session = if let Some(active_run) = active_run.as_ref() {
+            let active_session =
+                tokio::time::timeout(PI_RPC_REQUEST_TIMEOUT, active_run.wait_for_session())
+                    .await
+                    .map_err(|_| {
+                        "Pi session initialization timed out while reading history".to_string()
+                    })?;
+            if let Some(session) = active_session {
+                session
+            } else if let Some(session) = self.sessions.lock().await.get(thread_id).cloned() {
+                session
+            } else {
+                let mapped_session = self
+                    .thread_manager
+                    .get_external_session(thread_id, AGENT_TYPE)
+                    .await
+                    .map_err(|error| error.to_string())?;
+                if mapped_session.is_some() {
+                    self.ensure_session(app, thread_id, config, true).await?
+                } else {
+                    return Ok(empty_pi_session_snapshot());
                 }
             }
-        })
-        .await;
-        let value = match response {
-            Ok(Ok(value)) => value,
-            Ok(Err(error)) => {
-                drop(_operation);
-                self.remove_session_if_same(thread_id, &session).await;
-                return Err(error);
-            }
-            Err(_) => {
-                drop(_operation);
-                self.remove_session_if_same(thread_id, &session).await;
-                return Err("Pi history read timed out waiting for an RPC response".into());
-            }
+        } else {
+            self.ensure_session(app, thread_id, config, true).await?
         };
-        if value.get("success").and_then(Value::as_bool) != Some(true) {
-            return Err(value
-                .get("error")
-                .and_then(Value::as_str)
-                .unwrap_or("Pi could not read this session")
-                .to_string());
-        }
         session.touch();
-        let mut messages = value
-            .pointer("/data/messages")
-            .and_then(Value::as_array)
-            .cloned()
-            .unwrap_or_default();
-        let (entries, leaf_id) = match session.session_entries().await {
-            Ok(snapshot) => snapshot,
-            Err(error) => {
-                drop(_operation);
-                self.shutdown_and_remove_session_if_same(thread_id, &session)
-                    .await;
-                return Err(error);
+        // Pi keeps the operation lock for the whole prompt. History reads use
+        // correlated RPC waiters and a small revision fence instead, matching
+        // the behavior of Codex's concurrent live-turn/history reads.
+        let active_at_start = self.active_runs.lock().await.contains_key(thread_id);
+        let mut last_read = None;
+        let mut stable_revision_seen = false;
+        for attempt in 0..3 {
+            let (before_entries, before_leaf) = session.session_entries().await?;
+            let messages = session.session_messages().await?;
+            let (entries, leaf_id) = session.session_entries().await?;
+            let before_cursor = before_entries
+                .last()
+                .and_then(|entry| entry.get("id"))
+                .and_then(Value::as_str);
+            let after_cursor = entries
+                .last()
+                .and_then(|entry| entry.get("id"))
+                .and_then(Value::as_str);
+            let revision_matches = before_cursor == after_cursor && before_leaf == leaf_id;
+            last_read = Some((messages, entries, leaf_id));
+            if revision_matches {
+                stable_revision_seen = true;
+                break;
             }
-        };
-        attach_pi_session_message_ids(&mut messages, &entries, leaf_id.as_deref())?;
+            if attempt < 2 {
+                tokio::time::sleep(Duration::from_millis(10)).await;
+            }
+        }
+        let (mut messages, entries, leaf_id) =
+            last_read.ok_or_else(|| "Pi history read did not return a snapshot".to_string())?;
+        let active_during_read =
+            active_at_start || self.active_runs.lock().await.contains_key(thread_id);
+        attach_pi_session_message_ids_with_pending_tail(
+            &mut messages,
+            &entries,
+            leaf_id.as_deref(),
+            active_during_read || !stable_revision_seen,
+        )?;
         // Keep original Pi block positions even when thinking is hidden.
         for (sequence, message) in messages.iter_mut().enumerate() {
             if let Some(object) = message.as_object_mut() {
@@ -1627,6 +1876,7 @@ impl PiRpcManager {
             }
         }
         let native_session_id = session.session_id.lock().await.clone();
+        session.touch();
         Ok(PiSessionSnapshot {
             messages,
             revision: PiHistoryRevision {
@@ -1725,6 +1975,7 @@ impl PiRpcManager {
             run_id: run_id.clone(),
             started_at,
             session: Mutex::new(None),
+            session_state: tokio::sync::watch::channel(None).0,
             session_id: Mutex::new(None),
             queued_messages: Mutex::new(HashMap::new()),
             queue_lock: Mutex::new(()),
@@ -1768,6 +2019,9 @@ impl PiRpcManager {
         if active.finalizing.swap(true, Ordering::AcqRel) {
             return;
         }
+        active
+            .session_state
+            .send_replace(active.session.lock().await.clone());
         let stop_reason = active.stop_reason.lock().await.clone();
         let error = match stop_reason.as_deref() {
             Some(USER_STOPPED_REASON) => None,
@@ -1822,6 +2076,14 @@ impl PiRpcManager {
         let pi_features = super::config::features()?;
         let runtime_model =
             runtime_model.filter(|value| !value.trim().is_empty() && value != "inherit");
+        let cloud_api_base = app
+            .state::<crate::app::state::AppState>()
+            .cloud_environment
+            .api_base()
+            .to_string();
+        let cloud_auth_generation = self
+            .ensure_cloud_credential(app, provider.as_deref(), &cloud_api_base)
+            .await?;
         let thinking = message
             .reasoning_effort_for_runtime(AGENT_TYPE)
             .filter(|value| {
@@ -1834,12 +2096,11 @@ impl PiRpcManager {
         let config = PiSessionConfig {
             cwd: cwd.clone(),
             tools: pi_tools_for_permission_mode(permission_mode).into(),
-            code_mode: message
-                .code_mode_for_runtime(AGENT_TYPE)
-                .unwrap_or(pi_features.code_mode),
+            code_mode: message.code_mode_for_runtime(AGENT_TYPE).unwrap_or(false),
             tool_search: pi_features.tool_search,
             provider: provider.clone().filter(|value| !value.trim().is_empty()),
             model: runtime_model.clone(),
+            cloud_auth_generation,
             thinking,
             startup_resources: skill_resources::capture(
                 &cwd,
@@ -1849,6 +2110,7 @@ impl PiRpcManager {
         };
         let session = self.ensure_session(app, thread_id, config, false).await?;
         *active.session.lock().await = Some(session.clone());
+        active.session_state.send_replace(Some(session.clone()));
         let session_id = session.session_id.lock().await.clone();
         *active.session_id.lock().await = Some(session_id.clone());
         active
@@ -2947,8 +3209,9 @@ async fn run_pi_fork_extension(
                     if let Some(error) = value.get("error").and_then(Value::as_str) {
                         return Err(error.to_string());
                     }
-                    let fork: PiForkMetadata = serde_json::from_value(value)
-                        .map_err(|error| format!("Pi fork returned incomplete metadata: {error}"))?;
+                    let fork: PiForkMetadata = serde_json::from_value(value).map_err(|error| {
+                        format!("Pi fork returned incomplete metadata: {error}")
+                    })?;
                     if fork.session_id.trim().is_empty() || fork.session_id == expected_source_id {
                         return Err("Pi fork did not create a new session ID".into());
                     }
@@ -3006,14 +3269,6 @@ fn pi_session_dir(thread_id: &str) -> Result<PathBuf, String> {
     Ok(root.join(stable_name))
 }
 
-fn legacy_pi_session_dir(thread_id: &str) -> Result<PathBuf, String> {
-    let root = pi_session_root()?;
-    use std::hash::{Hash, Hasher};
-    let mut hasher = std::collections::hash_map::DefaultHasher::new();
-    thread_id.hash(&mut hasher);
-    Ok(root.join(format!("{:016x}", hasher.finish())))
-}
-
 fn pi_session_root() -> Result<PathBuf, String> {
     #[cfg(windows)]
     {
@@ -3026,57 +3281,8 @@ fn pi_session_root() -> Result<PathBuf, String> {
         .ok_or_else(|| "user data directory is unavailable".to_string())
 }
 
-fn pi_session_candidates(thread_id: &str) -> Result<Vec<PathBuf>, String> {
-    #[allow(unused_mut)]
-    let mut candidates = vec![
-        pi_session_dir(thread_id)?,
-        legacy_pi_session_dir(thread_id)?,
-    ];
-    #[cfg(windows)]
-    {
-        let local = std::env::var_os("LOCALAPPDATA").ok_or("LOCALAPPDATA is unavailable")?;
-        let old_root = PathBuf::from(local).join("Flowix").join("pi-sessions");
-        candidates.push(
-            old_root.join(
-                candidates[0]
-                    .file_name()
-                    .ok_or("Pi session path has no name")?,
-            ),
-        );
-        candidates.push(
-            old_root.join(
-                candidates[1]
-                    .file_name()
-                    .ok_or("Pi session path has no name")?,
-            ),
-        );
-    }
-    Ok(candidates)
-}
-
 fn resolve_pi_session_dir(thread_id: &str, create: bool) -> Result<PathBuf, String> {
-    #[cfg(windows)]
-    let path =
-        crate::runtime_state::resolve_pi_session_candidates(&pi_session_candidates(thread_id)?)?;
-    #[cfg(not(windows))]
-    let path = {
-        let stable = pi_session_dir(thread_id)?;
-        let legacy = legacy_pi_session_dir(thread_id)?;
-        if !stable.exists() && legacy.exists() {
-            std::fs::create_dir_all(stable.parent().ok_or("Pi session path has no parent")?)
-                .map_err(|error| format!("cannot create Pi session directory: {error}"))?;
-            match std::fs::rename(&legacy, &stable) {
-                Ok(()) => {}
-                Err(_) if stable.exists() => {}
-                Err(error) => {
-                    return Err(format!(
-                        "could not migrate Pi conversation session: {error}"
-                    ))
-                }
-            }
-        }
-        stable
-    };
+    let path = pi_session_dir(thread_id)?;
     if create {
         std::fs::create_dir_all(&path)
             .map_err(|error| format!("cannot create Pi session directory: {error}"))?;
@@ -3084,7 +3290,11 @@ fn resolve_pi_session_dir(thread_id: &str, create: bool) -> Result<PathBuf, Stri
     Ok(path)
 }
 
-/// The sole receiver owner preserves every agent event while waiting for RPC.
+fn pi_message_matches(left: &Value, right: &Value) -> bool {
+    left == right
+}
+
+#[cfg(test)]
 async fn receive_rpc_response(
     records: &mut mpsc::UnboundedReceiver<Result<Value, String>>,
     deferred: &mut VecDeque<Value>,
@@ -3101,10 +3311,6 @@ async fn receive_rpc_response(
     }
 }
 
-fn pi_message_matches(left: &Value, right: &Value) -> bool {
-    left == right
-}
-
 #[cfg(test)]
 fn pi_rpc_message_id(
     entries: &[Value],
@@ -3155,15 +3361,35 @@ fn pi_active_branch_entries<'a>(
     Ok(branch)
 }
 
+#[cfg(test)]
 fn attach_pi_session_message_ids(
-    messages: &mut [Value],
+    messages: &mut Vec<Value>,
+    entries: &[Value],
+    leaf_id: Option<&str>,
+) -> Result<(), String> {
+    attach_pi_session_message_ids_impl(messages, entries, leaf_id, false)
+}
+
+fn attach_pi_session_message_ids_with_pending_tail(
+    messages: &mut Vec<Value>,
+    entries: &[Value],
+    leaf_id: Option<&str>,
+    allow_pending_tail: bool,
+) -> Result<(), String> {
+    attach_pi_session_message_ids_impl(messages, entries, leaf_id, allow_pending_tail)
+}
+
+fn attach_pi_session_message_ids_impl(
+    messages: &mut Vec<Value>,
     entries: &[Value],
     leaf_id: Option<&str>,
+    allow_pending_tail: bool,
 ) -> Result<(), String> {
     let branch = pi_active_branch_entries(entries, leaf_id)?;
     let mut entry_index = 0;
+    let mut first_unmatched_renderable = None;
     let mut unmatched_renderable_messages = 0;
-    for message in messages {
+    for (message_index, message) in messages.iter_mut().enumerate() {
         let matched_index = branch[entry_index..].iter().position(|entry| {
             entry.get("type").and_then(Value::as_str) == Some("message")
                 && entry
@@ -3182,10 +3408,16 @@ fn attach_pi_session_message_ids(
                         | "compactionSummary"
                 )
             ) {
+                first_unmatched_renderable.get_or_insert(message_index);
                 unmatched_renderable_messages += 1;
             }
             continue;
         };
+        if first_unmatched_renderable.is_some() {
+            return Err(
+                "Pi history contains an unmatched message before a later committed message".into(),
+            );
+        }
         entry_index += relative_index;
         let entry = branch[entry_index];
         entry_index += 1;
@@ -3202,6 +3434,12 @@ fn attach_pi_session_message_ids(
         }
     }
     if unmatched_renderable_messages > 0 {
+        if allow_pending_tail {
+            if let Some(start) = first_unmatched_renderable {
+                messages.truncate(start);
+                return Ok(());
+            }
+        }
         return Err(format!(
             "Pi returned {unmatched_renderable_messages} history messages that could not be reconciled with native ids on the active session branch"
         ));
@@ -3209,70 +3447,164 @@ fn attach_pi_session_message_ids(
     Ok(())
 }
 
-fn resolve_pi_binary(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    if let Some(value) = std::env::var_os("PI_CLI_PATH") {
-        let candidate = PathBuf::from(value);
-        if candidate.is_file() {
-            return Ok(candidate);
-        }
-    }
-    #[cfg(target_os = "macos")]
-    let platform = "darwin";
-    #[cfg(target_os = "windows")]
-    let platform = "windows";
-    #[cfg(target_os = "linux")]
-    let platform = "linux";
+pub(crate) fn resolve_pi_binary(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let platform = match std::env::consts::OS {
+        "macos" => "darwin",
+        "windows" => "windows",
+        "linux" => "linux",
+        other => return Err(format!("Pi runtime is not bundled for {other}")),
+    };
     let arch = match std::env::consts::ARCH {
         "aarch64" => "arm64",
         "x86_64" => "x64",
-        other => other,
+        other => return Err(format!("Pi runtime is not bundled for {platform}-{other}")),
     };
+    let target = format!("{platform}-{arch}");
+    let executable = if cfg!(windows) { "pi.exe" } else { "pi" };
+    let mut roots = Vec::new();
+
     if let Ok(resources) = app.path().resource_dir() {
-        let name = if cfg!(windows) { "pi.exe" } else { "pi" };
-        let bundled_root = resources.join("pi").join(format!("{platform}-{arch}"));
-        let bundled_candidates = [
-            bundled_root.join("dist").join(name),
-            bundled_root.join(name),
-        ];
-        if let Some(bundled) = bundled_candidates
-            .into_iter()
-            .find(|candidate| candidate.is_file())
-        {
-            return Ok(bundled);
+        roots.push(resources.join("pi").join(&target));
+    }
+    #[cfg(debug_assertions)]
+    roots.push(
+        PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+            .join("../../.build/pi-runtime/resources")
+            .join(&target),
+    );
+
+    for root in roots {
+        for candidate in [root.join("dist").join(executable), root.join(executable)] {
+            if crate::agent_external::cli_resolver::is_executable_file(&candidate) {
+                return Ok(candidate);
+            }
         }
     }
-    if let Some(path) = crate::agent_external::cli_resolver::which_in_path(
-        if cfg!(windows) { "pi.exe" } else { "pi" },
-        std::env::var_os("PATH").as_deref(),
-    ) {
-        return Ok(path);
-    }
-    if let Some(path) = installed_flowix_pi_binary() {
-        return Ok(path);
-    }
-    Ok(
-        crate::agent_external::cli_resolver::resolve_external_cli_uncached(
-            &crate::agent_external::cli_resolver::ExternalCliSpec {
-                binary_name: "pi",
-                #[cfg(windows)]
-                windows_binary_name: "pi.exe",
-                env_vars: &["PI_CLI_PATH"],
-                extra_unix_candidates: crate::agent_external::cli_resolver::no_extra_candidates,
-                #[cfg(windows)]
-                extra_windows_candidates: crate::agent_external::cli_resolver::no_extra_candidates,
-            },
-        ),
-    )
+
+    Err(format!(
+        "Bundled Pi runtime is missing or not executable for {target}"
+    ))
 }
 
 #[cfg(test)]
 mod tests {
     use super::{
         attach_pi_session_message_ids, pi_active_branch_entries, pi_rpc_message_id,
-        receive_rpc_response,
+        receive_rpc_response, run_startup_cloud_credential_refresh_once,
+        run_startup_cloud_refresh_once,
     };
     use serde_json::json;
 
+    #[tokio::test]
+    async fn startup_cloud_refresh_shares_the_actual_failure_per_generation() {
+        use std::collections::HashMap;
+        use std::sync::atomic::{AtomicUsize, Ordering};
+        use std::sync::Arc;
+        use tokio::sync::Mutex;
+
+        let results = Arc::new(Mutex::new(HashMap::new()));
+        let refresh_count = Arc::new(AtomicUsize::new(0));
+        let run = |results: Arc<Mutex<HashMap<u64, Result<bool, String>>>>,
+                   refresh_count: Arc<AtomicUsize>| async move {
+            run_startup_cloud_refresh_once(&results, 7, || async move {
+                refresh_count.fetch_add(1, Ordering::SeqCst);
+                tokio::task::yield_now().await;
+                Err("credential refresh failed".to_string())
+            })
+            .await
+        };
+
+        let (first, concurrent) = tokio::join!(
+            run(results.clone(), refresh_count.clone()),
+            run(results.clone(), refresh_count.clone()),
+        );
+        assert_eq!(first, Err("credential refresh failed".to_string()));
+        assert_eq!(concurrent, Err("credential refresh failed".to_string()));
+        assert_eq!(refresh_count.load(Ordering::SeqCst), 1);
+
+        let cached = run_startup_cloud_refresh_once(&results, 7, || async { Ok(true) }).await;
+        assert_eq!(cached, Err("credential refresh failed".to_string()));
+        assert_eq!(refresh_count.load(Ordering::SeqCst), 1);
+
+        let next_generation =
+            run_startup_cloud_refresh_once(&results, 8, || async { Ok(true) }).await;
+        assert_eq!(next_generation, Ok(true));
+    }
+
+    #[tokio::test]
+    async fn startup_cloud_refresh_fetches_latest_catalog_once_even_if_credential_is_cached() {
+        use std::collections::HashMap;
+        use std::sync::atomic::{AtomicUsize, Ordering};
+        use std::sync::Arc;
+        use tokio::sync::Mutex;
+
+        let results = Mutex::new(HashMap::new());
+        let credential_generation = Mutex::new(Some(7));
+        let refresh_count = Arc::new(AtomicUsize::new(0));
+        let count = refresh_count.clone();
+        let refreshed = run_startup_cloud_credential_refresh_once(
+            &results,
+            &credential_generation,
+            7,
+            || async move {
+                count.fetch_add(1, Ordering::SeqCst);
+                Ok(())
+            },
+        )
+        .await;
+        assert_eq!(refreshed, Ok(true));
+        assert_eq!(refresh_count.load(Ordering::SeqCst), 1);
+
+        let count = refresh_count.clone();
+        let coalesced = run_startup_cloud_credential_refresh_once(
+            &results,
+            &credential_generation,
+            7,
+            || async move {
+                count.fetch_add(1, Ordering::SeqCst);
+                Ok(())
+            },
+        )
+        .await;
+        assert_eq!(coalesced, Ok(true));
+        assert_eq!(refresh_count.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn stderr_is_visible_before_eof_and_keeps_only_a_bounded_tail() {
+        use std::sync::Arc;
+        use tokio::io::AsyncWriteExt;
+        use tokio::sync::Mutex;
+        let (mut writer, reader) = tokio::io::duplex(4096);
+        let captured = Arc::new(Mutex::new(String::new()));
+        let task = tokio::spawn(super::capture_pi_stderr(reader, captured.clone()));
+        writer.write_all(b"startup diagnostic").await.unwrap();
+        tokio::time::timeout(std::time::Duration::from_secs(1), async {
+            loop {
+                if captured.lock().await.contains("startup diagnostic") {
+                    break;
+                }
+                tokio::task::yield_now().await;
+            }
+        })
+        .await
+        .unwrap();
+        assert!(
+            !task.is_finished(),
+            "diagnostics must be visible before EOF"
+        );
+        writer
+            .write_all(&vec![b'x'; super::PI_STDERR_TAIL_BYTES * 2])
+            .await
+            .unwrap();
+        writer.write_all("最新错误".as_bytes()).await.unwrap();
+        drop(writer);
+        task.await.unwrap().unwrap();
+        let text = captured.lock().await;
+        assert!(text.ends_with("最新错误"));
+        assert!(text.len() <= super::PI_STDERR_TAIL_BYTES);
+        assert!(!text.contains("startup diagnostic"));
+    }
     #[tokio::test]
     async fn pi_queue_rebuild_keeps_duplicate_message_attachments_with_the_right_item() {
         use super::{known_pi_queue_payloads, pi_queue_target_index, ActivePiRun, PiQueuedMessage};
@@ -3299,6 +3631,7 @@ mod tests {
             run_id: "test".into(),
             started_at: 0,
             session: Mutex::new(None),
+            session_state: tokio::sync::watch::channel(None).0,
             session_id: Mutex::new(None),
             queued_messages: Mutex::new(HashMap::from([
                 ("first".into(), first.clone()),
@@ -3523,66 +3856,3 @@ mod tests {
         assert!(error.contains("could not be reconciled with native ids"));
     }
 }
-
-/// Find Pi shipped inside a regular Flowix installation. Dev launches use
-/// this when Tauri does not preserve the `PI_CLI_PATH` set by tauri-dev.mjs.
-pub fn installed_flowix_pi_binary() -> Option<PathBuf> {
-    #[cfg(target_os = "macos")]
-    let platform = "darwin";
-    #[cfg(target_os = "windows")]
-    let platform = "windows";
-    #[cfg(target_os = "linux")]
-    let platform = "linux";
-    let arch = match std::env::consts::ARCH {
-        "aarch64" => "arm64",
-        "x86_64" => "x64",
-        other => other,
-    };
-    let executable = if cfg!(windows) { "pi.exe" } else { "pi" };
-    let mut app_roots = Vec::new();
-    if let Some(root) = std::env::var_os("FLOWIX_PROD_APP_PATH") {
-        app_roots.push(PathBuf::from(root));
-    }
-    #[cfg(target_os = "macos")]
-    {
-        app_roots.push(PathBuf::from("/Applications/Flowix.app"));
-        if let Some(home) = dirs::home_dir() {
-            app_roots.push(home.join("Applications").join("Flowix.app"));
-        }
-    }
-    #[cfg(target_os = "windows")]
-    {
-        if let Some(local_app_data) = std::env::var_os("LOCALAPPDATA") {
-            app_roots.push(
-                PathBuf::from(local_app_data)
-                    .join("Programs")
-                    .join("Flowix"),
-            );
-        }
-        if let Some(program_files) = std::env::var_os("ProgramFiles") {
-            app_roots.push(PathBuf::from(program_files).join("Flowix"));
-        }
-    }
-    #[cfg(target_os = "linux")]
-    {
-        app_roots.push(PathBuf::from("/opt/Flowix"));
-        app_roots.push(PathBuf::from("/usr/lib/flowix"));
-        app_roots.push(PathBuf::from("/usr/lib/Flowix"));
-    }
-
-    for app_root in app_roots {
-        #[cfg(target_os = "macos")]
-        let resource_roots = vec![app_root.join("Contents").join("Resources")];
-        #[cfg(not(target_os = "macos"))]
-        let resource_roots = vec![app_root.join("resources"), app_root];
-        for resource_root in resource_roots {
-            let root = resource_root.join("pi").join(format!("{platform}-{arch}"));
-            for candidate in [root.join("dist").join(executable), root.join(executable)] {
-                if crate::agent_external::cli_resolver::is_executable_file(&candidate) {
-                    return Some(candidate);
-                }
-            }
-        }
-    }
-    None
-}
diff --git a/app/flowix-desktop/src/agent_external/runtime_registry.rs b/app/flowix-desktop/src/agent_external/runtime_registry.rs
index b3f36fd39..bf0943227 100644
--- a/app/flowix-desktop/src/agent_external/runtime_registry.rs
+++ b/app/flowix-desktop/src/agent_external/runtime_registry.rs
@@ -45,7 +45,7 @@ impl ExternalRuntimeKind {
         Self::DeepSeekHarness,
     ];
 
-    pub const fn key(self) -> &'static str {
+    pub const fn id(self) -> &'static str {
         match self {
             Self::Codex => CODEX_AGENT_TYPE,
             Self::Claude => CLAUDE_AGENT_TYPE,
@@ -59,11 +59,11 @@ impl ExternalRuntimeKind {
     pub fn parse(value: &str) -> Result<Self, String> {
         match value.trim().to_ascii_lowercase().as_str() {
             "codex" => Ok(Self::Codex),
-            "claude" => Ok(Self::Claude),
+            "claudecode" | "claude" => Ok(Self::Claude),
             "hermes" => Ok(Self::Hermes),
             "opencode" => Ok(Self::OpenCode),
             "pi" => Ok(Self::Pi),
-            "deepseek-harness" | "deepseek_harness" | "dsh" => Ok(Self::DeepSeekHarness),
+            "dsh" | "deepseek-harness" | "deepseek_harness" => Ok(Self::DeepSeekHarness),
             other => Err(format!("unsupported agent type: {other}")),
         }
     }
@@ -73,8 +73,8 @@ impl ExternalRuntimeKind {
 pub trait ExternalCliRuntime: Send + Sync {
     fn kind(&self) -> ExternalRuntimeKind;
 
-    fn key(&self) -> &'static str {
-        self.kind().key()
+    fn id(&self) -> &'static str {
+        self.kind().id()
     }
 
     async fn chat_stream(
@@ -669,7 +669,7 @@ impl ExternalRuntimeRegistry {
             if registry.insert(kind, runtime).is_some() {
                 return Err(format!(
                     "external runtime is registered more than once for {}",
-                    kind.key()
+                    kind.id()
                 ));
             }
         }
@@ -1052,7 +1052,7 @@ fn merge_run_snapshot(target: &mut HashMap<String, RunInfo>, snapshot: RuntimeRu
             if snapshot.info.started_at > existing.started_at {
                 tracing::warn!(
                     thread_id = %snapshot.thread_id,
-                    kept_runtime = snapshot.runtime.key(),
+                    kept_runtime = snapshot.runtime.id(),
                     dropped_runtime = existing.agent_type.as_deref().unwrap_or("unknown"),
                     "multiple runtimes reported the same running thread; keeping the newest run"
                 );
@@ -1061,7 +1061,7 @@ fn merge_run_snapshot(target: &mut HashMap<String, RunInfo>, snapshot: RuntimeRu
                 tracing::warn!(
                     thread_id = %snapshot.thread_id,
                     kept_runtime = existing.agent_type.as_deref().unwrap_or("unknown"),
-                    dropped_runtime = snapshot.runtime.key(),
+                    dropped_runtime = snapshot.runtime.id(),
                     "multiple runtimes reported the same running thread; keeping the newest run"
                 );
             }
@@ -1157,17 +1157,17 @@ mod tests {
 
         let keys = registry
             .iter()
-            .map(ExternalCliRuntime::key)
+            .map(|runtime| runtime.id())
             .collect::<Vec<_>>();
         assert_eq!(
             keys,
             [
-                "codex",
-                "claude",
-                "hermes",
-                "opencode",
-                "pi",
-                "deepseek-harness"
+                CODEX_AGENT_TYPE,
+                CLAUDE_AGENT_TYPE,
+                HERMES_AGENT_TYPE,
+                OPENCODE_AGENT_TYPE,
+                PI_AGENT_TYPE,
+                DSH_AGENT_TYPE,
             ]
         );
         for kind in ExternalRuntimeKind::ALL {
diff --git a/app/flowix-desktop/src/agent_external/shared/lifecycle.rs b/app/flowix-desktop/src/agent_external/shared/lifecycle.rs
index 0d8517a55..fefa9124e 100644
--- a/app/flowix-desktop/src/agent_external/shared/lifecycle.rs
+++ b/app/flowix-desktop/src/agent_external/shared/lifecycle.rs
@@ -249,7 +249,7 @@ pub async fn persist_external_chunk_for_thread_with_metadata(
     // local journal is retained only for Claude. Codex and DSH messages must
     // come from their provider history APIs; their live chunks are runtime
     // state only and must never become a second local transcript.
-    if agent_type != "claude" {
+    if agent_type != "claudecode" {
         return;
     }
     let payload_json = match chunk_payload_json(chunk, agent_type, run_id, metadata) {
diff --git a/app/flowix-desktop/src/agent_external/shared/tests.rs b/app/flowix-desktop/src/agent_external/shared/tests.rs
index 340d68a2b..bd48def2b 100644
--- a/app/flowix-desktop/src/agent_external/shared/tests.rs
+++ b/app/flowix-desktop/src/agent_external/shared/tests.rs
@@ -76,6 +76,31 @@ fn chunk_payload_scopes_codex_fallback_identity_per_run() {
     assert_ne!(run_one.get("message_id"), run_two.get("message_id"));
 }
 
+#[test]
+fn chunk_payload_preserves_stable_codex_turn_error_identity() {
+    let turn_error_id = "msg:codex:turn-error:turn-1";
+    let chunk = AgentChunk::Error {
+        thread_id: "thread-1".to_string(),
+        message: "user_stopped".to_string(),
+        error_details: None,
+    };
+    let payload = chunk_payload_value(
+        &chunk,
+        "codex",
+        "run-1",
+        &AgentChunkMetadata {
+            codex_turn_id: Some("turn-1".to_string()),
+            message_id: Some(turn_error_id.to_string()),
+            ..AgentChunkMetadata::default()
+        },
+    )
+    .expect("serialize stable turn error");
+
+    assert_eq!(payload["codex_turn_id"], "turn-1");
+    assert_eq!(payload["message_id"], turn_error_id);
+    assert_eq!(payload["source_message_id"], turn_error_id);
+}
+
 #[test]
 fn pi_deltas_stay_draft_until_the_native_session_entry_id_arrives() {
     let text = AgentChunk::Text {
diff --git a/app/flowix-desktop/src/agent_external_config.rs b/app/flowix-desktop/src/agent_external_config.rs
index e6ef3b92b..aa47b924e 100644
--- a/app/flowix-desktop/src/agent_external_config.rs
+++ b/app/flowix-desktop/src/agent_external_config.rs
@@ -1,5 +1,5 @@
 //! External CLI path config ── 持久化在 `~/.flowix/agent-external-config.json`�?//!
-//! 作为�?external agent (codex / claude / gemini / hermes / openclaw) 执�?�?��
+//! External CLI paths for supported Agents are stored here.
 //! �?�?��参照":
 //! - �?��时探测一�?(`run_startup_detect`), 把命�?�� path 写入文件并灌�?//!   `agent_external::cli_resolver::REGISTRY`; 此后运�?�?`resolve_external_cli`
 //!   命中即用, 不再每条消息跑探测链�?//! - `source = "user"` 的条�?��动探测跳�? 尊重用户在偏好�?�?��手改的路径�?//! - path 失效 (文件�?��) 不自�?fallback ── �?`executable_available` �?false
@@ -9,21 +9,56 @@ use std::collections::HashMap;
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
-use std::sync::{RwLock, RwLockReadGuard, RwLockWriteGuard};
-
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    RwLock, RwLockReadGuard, RwLockWriteGuard,
+};
 use serde::{Deserialize, Serialize};
+use tokio::sync::Notify;
 
 use crate::agent_external::cli_resolver::{
     is_executable_file, set_external_cli_registry, update_external_cli_path,
 };
 use crate::agent_external::{claude, codex, hermes, opencode};
 
-/// 5 �?external agent �?binary_name (= AgentTypeKey = registry key)�?/// 顺序影响偏好设置列表呈现, 不影响逻辑�?
-pub const EXTERNAL_AGENT_KEYS: &[&str] = &["codex", "claude", "hermes", "opencode"];
+/// Stable IDs for the external CLI Agents configured by this module.
+pub const EXTERNAL_AGENT_KEYS: &[&str] = &["codex", "claudecode", "hermes", "opencode"];
+
+fn canonical_external_agent_key(agent_key: &str) -> Option<&'static str> {
+    match agent_key {
+        "codex" => Some("codex"),
+        "claude" | "claudecode" => Some("claudecode"),
+        "hermes" => Some("hermes"),
+        "opencode" => Some("opencode"),
+        _ => None,
+    }
+}
+
+fn external_binary_name(agent_key: &str) -> &str {
+    if agent_key == "claudecode" { "claude" } else { agent_key }
+}
+
+fn is_supported_external_agent_key(agent_key: &str) -> bool {
+    EXTERNAL_AGENT_KEYS.contains(&agent_key)
+}
 
 pub struct AgentExternalConfig {
     path: PathBuf,
     data: RwLock<AgentExternalConfigFile>,
+    startup_detect_complete: AtomicBool,
+    startup_detect_notify: Notify,
+}
+
+struct StartupDetectCompletion<'a> {
+    complete: &'a AtomicBool,
+    notify: &'a Notify,
+}
+
+impl Drop for StartupDetectCompletion<'_> {
+    fn drop(&mut self) {
+        self.complete.store(true, Ordering::Release);
+        self.notify.notify_waiters();
+    }
 }
 
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
@@ -42,6 +77,10 @@ pub struct AgentExternalEntry {
     /// `auto` = �?��探测写入 (�??下�?�?��覆盖); `user` = 用户手改 (�?��探测跳过)�?
     #[serde(default = "default_source")]
     pub source: AgentExternalSource,
+    /// Whether this path was explicitly configured or discovery has completed.
+    /// A missing path before that point means unknown, not uninstalled.
+    #[serde(default)]
+    pub detected: bool,
 }
 
 fn default_source() -> AgentExternalSource {
@@ -66,11 +105,44 @@ impl AgentExternalConfig {
         if let Some(parent) = path.parent() {
             fs::create_dir_all(parent)?;
         }
-        let data = Self::read_from_disk(&path).unwrap_or_default();
-        Ok(Self {
+        let mut data = flowix_core::memo_file::read_or_create_json(&path, AgentExternalConfigFile::default)?;
+        // Canonicalize the one renamed external Agent ID on first load. If a
+        // canonical entry already exists, it wins; otherwise carry the user's
+        // existing path/source/detection state across unchanged.
+        let migrated_legacy_key = if let Some(legacy) = data.agents.remove("claude") {
+            match data.agents.remove("claudecode") {
+                Some(current) => {
+                    let chosen = match (current.source, legacy.source) {
+                        (AgentExternalSource::User, _) => current,
+                        (_, AgentExternalSource::User) => legacy,
+                        _ if current.path.is_some() || current.detected => current,
+                        _ => legacy,
+                    };
+                    data.agents.insert("claudecode".to_string(), chosen);
+                }
+                None => {
+                    data.agents.insert("claudecode".to_string(), legacy);
+                }
+            }
+            true
+        } else {
+            false
+        };
+        let original_entry_count = data.agents.len();
+        data.agents
+            .retain(|key, _| is_supported_external_agent_key(key));
+        let removed_unsupported_entries = migrated_legacy_key || data.agents.len() != original_entry_count;
+        let config = Self {
             path,
             data: RwLock::new(data),
-        })
+            startup_detect_complete: AtomicBool::new(false),
+            startup_detect_notify: Notify::new(),
+        };
+        if removed_unsupported_entries {
+            let sanitized = config.read_data().clone();
+            config.flush(&sanitized)?;
+        }
+        Ok(config)
     }
 
     pub fn transient(path: PathBuf) -> Self {
@@ -81,6 +153,8 @@ impl AgentExternalConfig {
         Self {
             path,
             data: RwLock::new(AgentExternalConfigFile::default()),
+            startup_detect_complete: AtomicBool::new(false),
+            startup_detect_notify: Notify::new(),
         }
     }
 
@@ -98,22 +172,6 @@ impl AgentExternalConfig {
         })
     }
 
-    fn read_from_disk(path: &Path) -> Option<AgentExternalConfigFile> {
-        if !path.exists() {
-            return None;
-        }
-        let content = fs::read_to_string(path).ok()?;
-        match serde_json::from_str::<AgentExternalConfigFile>(&content) {
-            Ok(data) => Some(data),
-            Err(e) => {
-                tracing::warn!(
-                    "agent-external-config.json parse error: {e}, falling back to empty"
-                );
-                None
-            }
-        }
-    }
-
     fn flush(&self, data: &AgentExternalConfigFile) -> std::io::Result<()> {
         if let Some(parent) = self.path.parent() {
             fs::create_dir_all(parent)?;
@@ -138,9 +196,10 @@ impl AgentExternalConfig {
 
     /// 读取�?agent 的当前条�?(path + source)�?
     pub fn get_entry(&self, agent_key: &str) -> AgentExternalEntry {
-        self.read_data()
-            .agents
-            .get(agent_key)
+        let Some(agent_key) = canonical_external_agent_key(agent_key) else {
+            return AgentExternalEntry::default();
+        };
+        self.read_data().agents.get(agent_key)
             .cloned()
             .unwrap_or_default()
     }
@@ -156,16 +215,23 @@ impl AgentExternalConfig {
         agent_key: &str,
         path: PathBuf,
     ) -> std::io::Result<AgentExternalEntry> {
+        let Some(agent_key) = canonical_external_agent_key(agent_key) else {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                format!("unsupported external Agent: {agent_key}"),
+            ));
+        };
         let entry = AgentExternalEntry {
             path: Some(path.clone()),
             source: AgentExternalSource::User,
+            detected: true,
         };
         {
             let mut data = self.write_data();
             data.agents.insert(agent_key.to_string(), entry.clone());
             self.flush(&data)?;
         }
-        update_external_cli_path(agent_key, Some(path));
+        update_external_cli_path(external_binary_name(agent_key), Some(path));
         Ok(entry)
     }
 
@@ -174,6 +240,10 @@ impl AgentExternalConfig {
     /// 此刻注册表尚�?���?(`REGISTRY = None`), �?`resolve_*_binary` 会走原探测链
     /// (env > PATH > 鍊欓€?> shell), 涓庢敼閫犲墠琛屼负涓€鑷淬€?
     pub fn run_startup_detect(&self) {
+        let _completion = StartupDetectCompletion {
+            complete: &self.startup_detect_complete,
+            notify: &self.startup_detect_notify,
+        };
         let started = std::time::Instant::now();
         let pending: Vec<&str> = {
             let data = self.read_data();
@@ -201,6 +271,7 @@ impl AgentExternalConfig {
                 let entry = AgentExternalEntry {
                     path,
                     source: AgentExternalSource::Auto,
+                    detected: true,
                 };
                 data.agents.insert(key.to_string(), entry);
                 changed = true;
@@ -216,13 +287,28 @@ impl AgentExternalConfig {
         );
     }
 
+    /// Wait until startup discovery has published all detected CLI paths.
+    /// Register the notification before checking the flag so completion cannot
+    /// be missed between the check and the wait.
+    pub async fn wait_for_startup_detect(&self) {
+        loop {
+            let notified = self.startup_detect_notify.notified();
+            tokio::pin!(notified);
+            notified.as_mut().enable();
+            if self.startup_detect_complete.load(Ordering::Acquire) {
+                return;
+            }
+            notified.await;
+        }
+    }
+
     /// 把当�?JSON �?path 内存镜像灌进 `REGISTRY`�?
     pub fn load_into_registry(&self) {
         let data = self.read_data();
         let mut map: HashMap<String, PathBuf> = HashMap::new();
         for &key in EXTERNAL_AGENT_KEYS {
             if let Some(p) = data.agents.get(key).and_then(|e| e.path.clone()) {
-                map.insert(key.to_string(), p);
+                map.insert(external_binary_name(key).to_string(), p);
             }
         }
         set_external_cli_registry(map);
@@ -231,8 +317,14 @@ impl AgentExternalConfig {
     /// 重新探测单个 agent: 清注册表该项 -> 跑探�?-> �?`source = auto` ->
     /// 更新注册表。返回探测到�?path (`None` = 没探测到)�?
     pub fn redetect(&self, agent_key: &str) -> std::io::Result<Option<PathBuf>> {
+        let Some(agent_key) = canonical_external_agent_key(agent_key) else {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                format!("unsupported external Agent: {agent_key}"),
+            ));
+        };
         // Remove the cached path before running the fallback detection chain.
-        update_external_cli_path(agent_key, None);
+        update_external_cli_path(external_binary_name(agent_key), None);
         let detected = detect_external_binary(agent_key);
         {
             let mut data = self.write_data();
@@ -241,13 +333,14 @@ impl AgentExternalConfig {
                 AgentExternalEntry {
                     path: detected.clone(),
                     source: AgentExternalSource::Auto,
+                    detected: true,
                 },
             );
             self.flush(&data)?;
         }
         // 探测到才回填注册�? 没探测到保持移除状�?(�?agent �?unavailable)�?
         if let Some(p) = detected.clone() {
-            update_external_cli_path(agent_key, Some(p));
+            update_external_cli_path(external_binary_name(agent_key), Some(p));
         }
         Ok(detected)
     }
@@ -258,7 +351,7 @@ impl AgentExternalConfig {
 fn detect_external_binary(agent_key: &str) -> Option<PathBuf> {
     let path = match agent_key {
         "codex" => codex::resolve_codex_binary(),
-        "claude" => claude::cli::resolve_claude_binary(),
+        "claudecode" => claude::cli::resolve_claude_binary(),
         "hermes" => hermes::cli::resolve_hermes_binary(),
         "opencode" => opencode::resolve_opencode_binary(),
         other => {
diff --git a/app/flowix-desktop/src/agent_history.rs b/app/flowix-desktop/src/agent_history.rs
index bc9c9f2aa..9c71f2cb5 100644
--- a/app/flowix-desktop/src/agent_history.rs
+++ b/app/flowix-desktop/src/agent_history.rs
@@ -77,7 +77,7 @@ impl AgentHistoryService {
             if registry.insert(runtime, adapter).is_some() {
                 return Err(format!(
                     "history adapter is registered more than once for {}",
-                    runtime.key()
+                    runtime.id()
                 ));
             }
         }
@@ -136,13 +136,13 @@ impl AgentHistoryService {
             let before = page.oldest_sequence.ok_or_else(|| {
                 format!(
                     "{} history reported more pages without a cursor",
-                    runtime.key()
+                    runtime.id()
                 )
             })?;
             if previous_cursor == Some(before) {
                 return Err(format!(
                     "{} history cursor did not advance at {before}",
-                    runtime.key()
+                    runtime.id()
                 ));
             }
             previous_cursor = Some(before);
@@ -164,7 +164,7 @@ impl AgentHistoryService {
     fn adapter(&self, runtime: ExternalRuntimeKind) -> Result<&Arc<dyn HistoryAdapter>, String> {
         self.adapters
             .get(&runtime)
-            .ok_or_else(|| format!("history adapter is not registered for {}", runtime.key()))
+            .ok_or_else(|| format!("history adapter is not registered for {}", runtime.id()))
     }
 }
 
diff --git a/app/flowix-desktop/src/agent_history/adapters.rs b/app/flowix-desktop/src/agent_history/adapters.rs
index 666ff6faa..968452569 100644
--- a/app/flowix-desktop/src/agent_history/adapters.rs
+++ b/app/flowix-desktop/src/agent_history/adapters.rs
@@ -60,7 +60,7 @@ impl HistoryAdapter for CodexHistoryAdapter {
     ) -> Result<ThreadMessagesPage, String> {
         let session_id = self
             .threads
-            .get_external_session(request.thread_id, self.runtime().key())
+            .get_external_session(request.thread_id, self.runtime().id())
             .await
             .map_err(|error| error.to_string())?
             .unwrap_or_else(|| request.thread_id.to_string());
@@ -144,7 +144,7 @@ impl HistoryAdapter for ClaudeHistoryAdapter {
     }
     async fn list_threads(&self) -> Result<Vec<ThreadInfo>, String> {
         self.threads
-            .list_external_threads(self.runtime().key())
+            .list_external_threads(self.runtime().id())
             .await
             .map_err(|error| error.to_string())
     }
@@ -187,7 +187,7 @@ impl HistoryAdapter for HermesHistoryAdapter {
     }
     async fn list_threads(&self) -> Result<Vec<ThreadInfo>, String> {
         self.threads
-            .list_external_threads(self.runtime().key())
+            .list_external_threads(self.runtime().id())
             .await
             .map_err(|error| error.to_string())
     }
@@ -198,7 +198,7 @@ impl HistoryAdapter for HermesHistoryAdapter {
         if let Some(page) = self
             .threads
             .get_external_event_messages_page(
-                self.runtime().key(),
+                self.runtime().id(),
                 request.thread_id,
                 request.before_sequence,
                 request.limit,
diff --git a/app/flowix-desktop/src/agent_lifecycle.rs b/app/flowix-desktop/src/agent_lifecycle.rs
index 3d31bbb8e..d6e08588a 100644
--- a/app/flowix-desktop/src/agent_lifecycle.rs
+++ b/app/flowix-desktop/src/agent_lifecycle.rs
@@ -87,7 +87,7 @@ impl AgentLifecycleService {
             if registry.insert(runtime, adapter).is_some() {
                 return Err(format!(
                     "lifecycle adapter is registered more than once for {}",
-                    runtime.key()
+                    runtime.id()
                 ));
             }
         }
@@ -204,7 +204,7 @@ impl ThreadLifecycleAdapter for CodexLifecycleAdapter {
         //   3. otherwise the conversation never reached the provider
         let codex_thread_id = match self
             .threads
-            .get_external_session(thread_id, self.runtime().key())
+            .get_external_session(thread_id, self.runtime().id())
             .await
             .map_err(|error| error.to_string())?
         {
@@ -273,9 +273,9 @@ mod tests {
             .apply("claude", "thread-1", LifecycleAction::Delete)
             .await
             .unwrap());
-        // Unparseable types (local agents) keep local-only semantics too.
+        // Unsupported types keep local-only semantics too.
         assert!(!service
-            .apply("gemini", "thread-1", LifecycleAction::Delete)
+            .apply("unsupported-agent", "thread-1", LifecycleAction::Delete)
             .await
             .unwrap());
         // A never-started Codex conversation has no provider thread, so no
diff --git a/app/flowix-desktop/src/agent_session/migrations.rs b/app/flowix-desktop/src/agent_session/migrations.rs
index f13319575..8b3900c54 100644
--- a/app/flowix-desktop/src/agent_session/migrations.rs
+++ b/app/flowix-desktop/src/agent_session/migrations.rs
@@ -10,7 +10,7 @@ use rusqlite::{params, Connection};
 
 use super::error::ThreadError;
 
-pub(super) const THREAD_DB_SCHEMA_VERSION: i64 = 13;
+pub(super) const THREAD_DB_SCHEMA_VERSION: i64 = 16;
 pub(super) const WAL_AUTOCHECKPOINT_PAGES: i64 = 4000;
 pub(super) const WAL_JOURNAL_SIZE_LIMIT_BYTES: i64 = 64 * 1024 * 1024;
 
@@ -34,6 +34,12 @@ impl super::store::ThreadManager {
         let current_version: i64 =
             conn.pragma_query_value(None, "user_version", |row| row.get(0))?;
         if current_version == THREAD_DB_SCHEMA_VERSION {
+            // A version marker can survive manual table deletion. Validate only
+            // the essential schema; this does not scan conversation contents.
+            conn.execute_batch("SELECT thread_id FROM threads LIMIT 0;
+                SELECT id, thread_id, content FROM thread_messages LIMIT 0;
+                SELECT instance_id FROM agent_conversation_instances LIMIT 0;
+                SELECT id FROM threads_index LIMIT 0;")?;
             return Ok(());
         }
         if current_version > THREAD_DB_SCHEMA_VERSION {
@@ -99,11 +105,7 @@ impl super::store::ThreadManager {
                 source_kind TEXT NOT NULL DEFAULT 'thread-card',
                 source_document_path TEXT,
                 source_relative_path TEXT,
-                source_memo_id TEXT,
                 source_notebook_id TEXT,
-                role_memo_id TEXT,
-                role_address TEXT,
-                role_name TEXT,
                 created_at INTEGER NOT NULL,
                 updated_at INTEGER NOT NULL,
                 FOREIGN KEY(thread_id) REFERENCES threads(thread_id) ON DELETE CASCADE
@@ -155,13 +157,9 @@ impl super::store::ThreadManager {
         // cut-over happens in a later migration once all callers are moved.
         Self::ensure_simplified_thread_schema(conn)?;
         Self::ensure_pi_thread_metadata_columns(conn)?;
-        Self::ensure_path_and_legacy_role_columns(conn)?;
-        // Role files are no longer part of conversations. Clear values from
-        // historical columns before marking the schema current.
-        conn.execute_batch(
-            "UPDATE agent_conversation_instances SET role_memo_id = NULL, role_address = NULL, role_name = NULL;
-             UPDATE agent_instances SET role_memo_id = NULL, role_address = NULL, role_name = NULL;",
-        )?;
+        Self::ensure_path_columns(conn)?;
+        Self::migrate_agent_identity_ids(conn)?;
+        Self::drop_obsolete_note_reference_columns(conn)?;
         conn.execute_batch(
             "
             CREATE INDEX IF NOT EXISTS idx_agent_external_events_thread
@@ -178,6 +176,80 @@ impl super::store::ThreadManager {
         Ok(())
     }
 
+    /// Note references are addressed by notebook and relative path. Discard
+    /// retired identity and role-file columns while keeping session data.
+    fn drop_obsolete_note_reference_columns(conn: &Connection) -> Result<(), ThreadError> {
+        for (table, column) in [
+            ("agent_instances", "memo_id"),
+            ("agent_instances", "role_memo_id"),
+            ("agent_instances", "role_address"),
+            ("agent_instances", "role_name"),
+            ("agent_conversation_instances", "source_memo_id"),
+            ("agent_conversation_instances", "role_memo_id"),
+            ("agent_conversation_instances", "role_address"),
+            ("agent_conversation_instances", "role_name"),
+        ] {
+            let exists: bool = conn.query_row(
+                &format!("SELECT EXISTS(SELECT 1 FROM pragma_table_info('{table}') WHERE name = ?1)"),
+                [column],
+                |row| row.get(0),
+            )?;
+            if exists {
+                conn.execute_batch(&format!("ALTER TABLE {table} DROP COLUMN {column}"))?;
+            }
+        }
+        Ok(())
+    }
+
+    /// Move persisted provider identities to the stable product IDs. This is
+    /// deliberately data-only: messages, provider session IDs, and runtime
+    /// configuration snapshots are left untouched.
+    fn migrate_agent_identity_ids(conn: &mut Connection) -> Result<(), ThreadError> {
+        let tx = conn.transaction()?;
+        tx.execute_batch(
+            "
+            UPDATE threads SET agent_id = 'claudecode' WHERE agent_id = 'claude';
+            UPDATE threads SET agent_id = 'dsh' WHERE agent_id = 'deepseek-harness';
+
+            UPDATE agent_conversation_instances SET agent_type = 'claudecode' WHERE agent_type = 'claude';
+            UPDATE agent_conversation_instances SET agent_type = 'dsh' WHERE agent_type = 'deepseek-harness';
+
+            UPDATE agent_instances SET agent = 'claudecode' WHERE agent = 'claude';
+            UPDATE agent_instances SET agent = 'dsh' WHERE agent = 'deepseek-harness';
+
+            -- A canonical row wins if both old and new runtime bindings exist.
+            DELETE FROM thread_external_sessions
+             WHERE runtime IN ('claude', 'deepseek-harness')
+               AND EXISTS (
+                   SELECT 1 FROM thread_external_sessions current
+                   WHERE (current.thread_id = thread_external_sessions.thread_id
+                          OR current.external_session_id = thread_external_sessions.external_session_id)
+                     AND current.runtime = CASE thread_external_sessions.runtime
+                         WHEN 'claude' THEN 'claudecode' ELSE 'dsh' END
+               );
+            UPDATE thread_external_sessions SET runtime = 'claudecode' WHERE runtime = 'claude';
+            UPDATE thread_external_sessions SET runtime = 'dsh' WHERE runtime = 'deepseek-harness';
+
+            -- Event journals can contain idempotency keys. Remove only exact
+            -- old/new key collisions before changing the runtime discriminator.
+            DELETE FROM agent_external_events
+             WHERE runtime IN ('claude', 'deepseek-harness')
+               AND event_key IS NOT NULL AND trim(event_key) <> ''
+               AND EXISTS (
+                   SELECT 1 FROM agent_external_events current
+                   WHERE current.thread_id = agent_external_events.thread_id
+                     AND current.event_key = agent_external_events.event_key
+                     AND current.runtime = CASE agent_external_events.runtime
+                         WHEN 'claude' THEN 'claudecode' ELSE 'dsh' END
+               );
+            UPDATE agent_external_events SET runtime = 'claudecode' WHERE runtime = 'claude';
+            UPDATE agent_external_events SET runtime = 'dsh' WHERE runtime = 'deepseek-harness';
+            ",
+        )?;
+        tx.commit()?;
+        Ok(())
+    }
+
     /// Additive first phase of the thread-store migration.
     ///
     /// The new tables deliberately contain only product identity and external
@@ -194,11 +266,7 @@ impl super::store::ThreadManager {
                 source TEXT NOT NULL DEFAULT 'thread-card',
                 document_path TEXT,
                 relative_path TEXT,
-                memo_id TEXT,
                 notebook_id TEXT,
-                role_memo_id TEXT,
-                role_address TEXT,
-                role_name TEXT,
                 created_at INTEGER NOT NULL,
                 updated_at INTEGER NOT NULL
             );
@@ -276,13 +344,12 @@ impl super::store::ThreadManager {
         tx.execute_batch(
             "
             INSERT OR IGNORE INTO agent_instances (
-                id, agent, config_json, source, document_path, memo_id,
-                notebook_id, role_memo_id, role_name, created_at, updated_at
+                id, agent, config_json, source, document_path,
+                notebook_id, created_at, updated_at
             )
             SELECT
                 instance_id, agent_type, runtime_config, source_kind,
-                source_document_path, source_memo_id, source_notebook_id,
-                role_memo_id, role_name, created_at, updated_at
+                source_document_path, source_notebook_id, created_at, updated_at
             FROM agent_conversation_instances;
 
             -- Preserve legacy product threads that predate an instance row by
@@ -487,13 +554,13 @@ impl super::store::ThreadManager {
         Ok(())
     }
 
-    fn ensure_path_and_legacy_role_columns(conn: &Connection) -> Result<(), ThreadError> {
+    fn ensure_path_columns(conn: &Connection) -> Result<(), ThreadError> {
         for (table, required) in [
             (
                 "agent_conversation_instances",
-                &["role_address", "source_relative_path"][..],
+                &["source_relative_path"][..],
             ),
-            ("agent_instances", &["role_address", "relative_path"][..]),
+            ("agent_instances", &["relative_path"][..]),
         ] {
             let mut stmt = conn.prepare(&format!("PRAGMA table_info({table})"))?;
             let columns = stmt
@@ -565,8 +632,8 @@ impl super::store::ThreadManager {
                 -- The unique index was added after some releases had already
                 -- written more than one instance for the same product thread.
                 -- Pick one canonical row before creating the constraint. Prefer
-                -- the newest row; on a timestamp tie, retain the row with the
-                -- richer source linkage, then use instance_id for determinism.
+                -- the newest row; on a timestamp tie, retain the row with a
+                -- document path, then use instance_id for determinism.
                 DELETE FROM agent_conversation_instances
                 WHERE thread_id IS NOT NULL
                   AND EXISTS (
@@ -578,15 +645,9 @@ impl super::store::ThreadManager {
                         OR (
                             newer.updated_at = agent_conversation_instances.updated_at
                             AND (
-                                (newer.source_memo_id IS NOT NULL AND agent_conversation_instances.source_memo_id IS NULL)
+                                (newer.source_document_path IS NOT NULL AND agent_conversation_instances.source_document_path IS NULL)
                                 OR (
-                                    (newer.source_memo_id IS NOT NULL) = (agent_conversation_instances.source_memo_id IS NOT NULL)
-                                    AND newer.source_document_path IS NOT NULL
-                                    AND agent_conversation_instances.source_document_path IS NULL
-                                )
-                                OR (
-                                    (newer.source_memo_id IS NOT NULL) = (agent_conversation_instances.source_memo_id IS NOT NULL)
-                                    AND (newer.source_document_path IS NOT NULL) = (agent_conversation_instances.source_document_path IS NOT NULL)
+                                    (newer.source_document_path IS NOT NULL) = (agent_conversation_instances.source_document_path IS NOT NULL)
                                     AND newer.instance_id > agent_conversation_instances.instance_id
                                 )
                             )
@@ -689,10 +750,7 @@ impl super::store::ThreadManager {
                 frozen_cwd TEXT,
                 source_kind TEXT NOT NULL DEFAULT 'thread-card',
                 source_document_path TEXT,
-                source_memo_id TEXT,
                 source_notebook_id TEXT,
-                role_memo_id TEXT,
-                role_name TEXT,
                 created_at INTEGER NOT NULL,
                 updated_at INTEGER NOT NULL,
                 FOREIGN KEY(thread_id) REFERENCES threads(thread_id) ON DELETE CASCADE
@@ -700,13 +758,13 @@ impl super::store::ThreadManager {
 
             INSERT INTO agent_conversation_instances (
                 instance_id, agent_type, thread_id, runtime_config, frozen_cwd,
-                source_kind, source_document_path, source_memo_id, source_notebook_id,
-                role_memo_id, role_name, created_at, updated_at
+                source_kind, source_document_path, source_notebook_id,
+                created_at, updated_at
             )
             SELECT
                 instance_id, agent_type, thread_id, runtime_config, frozen_cwd,
-                source_kind, source_document_path, source_memo_id, source_notebook_id,
-                role_memo_id, role_name, created_at, updated_at
+                source_kind, source_document_path, source_notebook_id,
+                created_at, updated_at
             FROM agent_conversation_instances_legacy;
 
             DROP TABLE agent_conversation_instances_legacy;
@@ -999,7 +1057,6 @@ impl super::store::ThreadManager {
                     LIMIT 1
                 ), i.thread_id) AS canonical_thread_id,
                 i.updated_at,
-                i.source_memo_id,
                 i.source_document_path
             FROM agent_conversation_instances i
             WHERE i.thread_id IS NOT NULL;
@@ -1015,21 +1072,14 @@ impl super::store::ThreadManager {
                     OR (
                         newer.updated_at = stale.updated_at
                         AND (
-                            (newer.source_memo_id IS NOT NULL AND stale.source_memo_id IS NULL)
-                            OR (
-                                (newer.source_memo_id IS NOT NULL) = (stale.source_memo_id IS NOT NULL)
-                                AND newer.source_document_path IS NOT NULL
-                                AND stale.source_document_path IS NULL
-                            )
+                            (newer.source_document_path IS NOT NULL AND stale.source_document_path IS NULL)
                             OR (
-                                (newer.source_memo_id IS NOT NULL) = (stale.source_memo_id IS NOT NULL)
-                                AND (newer.source_document_path IS NOT NULL) = (stale.source_document_path IS NOT NULL)
+                                (newer.source_document_path IS NOT NULL) = (stale.source_document_path IS NOT NULL)
                                 AND newer.instance_id > stale.instance_id
                             )
-                        )
                     )
                  )
-            );
+              ));
 
             UPDATE agent_conversation_instances
             SET thread_id = (
diff --git a/app/flowix-desktop/src/agent_session/store.rs b/app/flowix-desktop/src/agent_session/store.rs
index aa0e46f78..9a78d4fb2 100644
--- a/app/flowix-desktop/src/agent_session/store.rs
+++ b/app/flowix-desktop/src/agent_session/store.rs
@@ -22,11 +22,12 @@ use super::error::ThreadError;
 
 pub struct ThreadManager {
     conn: Mutex<Connection>,
+    db_path: Option<PathBuf>,
 }
 
 fn external_default_title(runtime: &str) -> &'static str {
     match runtime {
-        "claude" => "Claude Code session",
+        "claudecode" => "Claude Code session",
         "hermes" => "Hermes session",
         "opencode" => "OpenCode session",
         _ => "Codex session",
@@ -42,18 +43,47 @@ impl ThreadManager {
     }
 
     pub fn new(db_path: PathBuf) -> Result<Self, ThreadError> {
-        let mut conn = Connection::open(db_path)?;
-        Self::run_migrations(&mut conn)?;
+        let manager = Self::new_uninitialized(db_path)?;
+        manager.initialize_storage()?;
+        Ok(manager)
+    }
+
+    /// Defer disk access and schema initialization to the startup worker.
+    pub fn new_uninitialized(db_path: PathBuf) -> Result<Self, ThreadError> {
+        // Disk initialization belongs to the startup worker, including repair.
+        let conn = Connection::open_in_memory()?;
         Ok(Self {
             conn: Mutex::new(conn),
+            db_path: Some(db_path),
         })
     }
 
+    pub fn initialize_storage(&self) -> Result<(), ThreadError> {
+        let mut connection = self.lock_conn();
+        let Some(path) = self.db_path.as_ref() else {
+            return Self::run_migrations(&mut connection);
+        };
+        // Always reopen the disk path on retry. A failed attempt must never
+        // turn the temporary connection into a successful in-memory store.
+        let old = std::mem::replace(&mut *connection, Connection::open_in_memory()?);
+        drop(old);
+        let initialized = flowix_core::memo_file::with_database_rebuild(path, || {
+            let mut conn = Connection::open(path).map_err(std::io::Error::other)?;
+            // A newer schema may contain user messages this binary cannot read.
+            // Unsupported versions are not corruption and must not be rebuilt.
+            Self::run_migrations(&mut conn).map_err(std::io::Error::other)?;
+            Ok(conn)
+        }).map_err(|error| ThreadError::Join(format!("initialize thread database: {error}")))?;
+        *connection = initialized;
+        Ok(())
+    }
+
     pub fn new_in_memory() -> Result<Self, ThreadError> {
         let mut conn = Connection::open_in_memory()?;
         Self::run_migrations(&mut conn)?;
         Ok(Self {
             conn: Mutex::new(conn),
+            db_path: None,
         })
     }
 
@@ -163,3 +193,40 @@ impl ThreadManager {
         Ok(())
     }
 }
+
+#[cfg(test)]
+mod storage_rebuild_tests {
+    use super::*;
+
+    #[test]
+    fn invalid_thread_database_is_backed_up_and_recreated() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("thread.db");
+        std::fs::write(&path, b"invalid thread database").unwrap();
+        let manager = ThreadManager::new(path).unwrap();
+        manager.initialize_storage().unwrap();
+        let count: i64 = manager
+            .lock_conn()
+            .query_row("SELECT COUNT(*) FROM threads", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(count, 0);
+        assert!(temp.path().join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn completed_schema_marker_does_not_hide_missing_tables() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("thread.db");
+        let manager = ThreadManager::new(path).unwrap();
+        manager
+            .lock_conn()
+            .execute_batch("PRAGMA foreign_keys=OFF; DROP TABLE thread_messages;")
+            .unwrap();
+        manager.initialize_storage().unwrap();
+        manager
+            .lock_conn()
+            .execute_batch("SELECT id FROM thread_messages LIMIT 0;")
+            .unwrap();
+        assert!(temp.path().join("rebuild-backups").exists());
+    }
+}
diff --git a/app/flowix-desktop/src/agent_session/store/conversations.rs b/app/flowix-desktop/src/agent_session/store/conversations.rs
index 0987b0639..4fef75057 100644
--- a/app/flowix-desktop/src/agent_session/store/conversations.rs
+++ b/app/flowix-desktop/src/agent_session/store/conversations.rs
@@ -3,8 +3,8 @@
 use super::ThreadManager;
 use crate::agent_session::error::ThreadError;
 use crate::agent_session::types::{
-    AgentConversationCursor, AgentConversationInstance,
-    AgentConversationSource, AgentConversationTypeCount, UpsertAgentConversationInstance,
+    AgentConversationCursor, AgentConversationInstance, AgentConversationSource,
+    AgentConversationTypeCount, UpsertAgentConversationInstance,
 };
 use rusqlite::{params, OptionalExtension};
 use std::path::PathBuf;
@@ -41,21 +41,44 @@ impl ThreadManager {
         let new_relative = new_relative.replace('\\', "/");
         let old_absolute = old_absolute.replace('\\', "/");
         let new_absolute = new_absolute.replace('\\', "/");
-        if old_notebook_id == new_notebook_id && old_relative == new_relative && old_absolute == new_absolute { return Ok(()); }
+        if old_notebook_id == new_notebook_id
+            && old_relative == new_relative
+            && old_absolute == new_absolute
+        {
+            return Ok(());
+        }
         let mut conn = self.lock_conn();
         let tx = conn.transaction()?;
         for (table, notebook_col, relative_col, document_col) in [
-            ("agent_instances", "notebook_id", "relative_path", "document_path"),
-            ("agent_conversation_instances", "source_notebook_id", "source_relative_path", "source_document_path"),
+            (
+                "agent_instances",
+                "notebook_id",
+                "relative_path",
+                "document_path",
+            ),
+            (
+                "agent_conversation_instances",
+                "source_notebook_id",
+                "source_relative_path",
+                "source_document_path",
+            ),
         ] {
             tx.execute(
-                &format!("UPDATE {table} SET
+                &format!(
+                    "UPDATE {table} SET
                     {notebook_col} = ?5,
                     {relative_col} = ?1 || substr({relative_col}, length(?2) + 1),
                     {document_col} = ?3 || substr({relative_col}, length(?2) + 1)
                   WHERE {notebook_col} = ?4 AND
-                    ({relative_col} = ?2 OR substr({relative_col}, 1, length(?2) + 1) = ?2 || '/')"),
-                params![new_relative, old_relative, new_absolute, old_notebook_id, new_notebook_id],
+                    ({relative_col} = ?2 OR substr({relative_col}, 1, length(?2) + 1) = ?2 || '/')"
+                ),
+                params![
+                    new_relative,
+                    old_relative,
+                    new_absolute,
+                    old_notebook_id,
+                    new_notebook_id
+                ],
             )?;
             tx.execute(
                 &format!("UPDATE {table} SET
@@ -103,15 +126,15 @@ impl ThreadManager {
         let mut stmt = conn.prepare(
             "SELECT
                 i.id, i.agent, ti.title, ti.id, i.config_json,
-                legacy.frozen_cwd, i.source, i.document_path, i.memo_id,
-                NULL, NULL, i.created_at, i.updated_at, i.notebook_id,
+                legacy.frozen_cwd, i.source, i.document_path,
+                i.created_at, i.updated_at, i.notebook_id,
                 COALESCE(
                     CASE i.agent
                         WHEN 'codex' THEN (SELECT external_id FROM threads_codex WHERE thread_id = ti.id)
-                        WHEN 'deepseek-harness' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
+                        WHEN 'dsh' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
                         WHEN 'opencode' THEN (SELECT external_id FROM threads_opencode WHERE thread_id = ti.id)
                         WHEN 'hermes' THEN (SELECT external_id FROM threads_hermes WHERE thread_id = ti.id)
-                        WHEN 'claude' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
+                        WHEN 'claudecode' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
                         WHEN 'pi' THEN (SELECT external_id FROM threads_pi WHERE thread_id = ti.id)
                     END,
                     (SELECT external_session_id FROM thread_external_sessions
@@ -187,15 +210,15 @@ impl ThreadManager {
         let mut stmt = conn.prepare(
             "SELECT
                 i.id, i.agent, ti.title, ti.id, i.config_json,
-                legacy.frozen_cwd, i.source, i.document_path, i.memo_id,
-                NULL, NULL, i.created_at, i.updated_at, i.notebook_id,
+                legacy.frozen_cwd, i.source, i.document_path,
+                i.created_at, i.updated_at, i.notebook_id,
                 COALESCE(
                     CASE i.agent
                         WHEN 'codex' THEN (SELECT external_id FROM threads_codex WHERE thread_id = ti.id)
-                        WHEN 'deepseek-harness' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
+                        WHEN 'dsh' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
                         WHEN 'opencode' THEN (SELECT external_id FROM threads_opencode WHERE thread_id = ti.id)
                         WHEN 'hermes' THEN (SELECT external_id FROM threads_hermes WHERE thread_id = ti.id)
-                        WHEN 'claude' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
+                        WHEN 'claudecode' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
                         WHEN 'pi' THEN (SELECT external_id FROM threads_pi WHERE thread_id = ti.id)
                     END,
                     (SELECT external_session_id FROM thread_external_sessions
@@ -270,15 +293,15 @@ impl ThreadManager {
         conn.query_row(
             "SELECT
                 i.id, i.agent, ti.title, ti.id, i.config_json,
-                legacy.frozen_cwd, i.source, i.document_path, i.memo_id,
-                NULL, NULL, i.created_at, i.updated_at, i.notebook_id,
+                legacy.frozen_cwd, i.source, i.document_path,
+                i.created_at, i.updated_at, i.notebook_id,
                 COALESCE(
                     CASE i.agent
                         WHEN 'codex' THEN (SELECT external_id FROM threads_codex WHERE thread_id = ti.id)
-                        WHEN 'deepseek-harness' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
+                        WHEN 'dsh' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
                         WHEN 'opencode' THEN (SELECT external_id FROM threads_opencode WHERE thread_id = ti.id)
                         WHEN 'hermes' THEN (SELECT external_id FROM threads_hermes WHERE thread_id = ti.id)
-                        WHEN 'claude' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
+                        WHEN 'claudecode' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
                         WHEN 'pi' THEN (SELECT external_id FROM threads_pi WHERE thread_id = ti.id)
                     END,
                     (SELECT external_session_id FROM thread_external_sessions
@@ -312,15 +335,15 @@ impl ThreadManager {
         conn.query_row(
             "SELECT
                 i.id, i.agent, ti.title, ti.id, i.config_json,
-                legacy.frozen_cwd, i.source, i.document_path, i.memo_id,
-                NULL, NULL, i.created_at, i.updated_at, i.notebook_id,
+                legacy.frozen_cwd, i.source, i.document_path,
+                i.created_at, i.updated_at, i.notebook_id,
                 COALESCE(
                     CASE i.agent
                         WHEN 'codex' THEN (SELECT external_id FROM threads_codex WHERE thread_id = ti.id)
-                        WHEN 'deepseek-harness' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
+                        WHEN 'dsh' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
                         WHEN 'opencode' THEN (SELECT external_id FROM threads_opencode WHERE thread_id = ti.id)
                         WHEN 'hermes' THEN (SELECT external_id FROM threads_hermes WHERE thread_id = ti.id)
-                        WHEN 'claude' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
+                        WHEN 'claudecode' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
                         WHEN 'pi' THEN (SELECT external_id FROM threads_pi WHERE thread_id = ti.id)
                     END,
                     (SELECT external_session_id FROM thread_external_sessions
@@ -406,16 +429,15 @@ impl ThreadManager {
         tx.execute(
             "INSERT INTO agent_conversation_instances (
                 instance_id, agent_type, thread_id,
-                runtime_config, source_kind, source_document_path, source_memo_id, source_notebook_id, source_relative_path,
+                runtime_config, source_kind, source_document_path, source_notebook_id, source_relative_path,
                 created_at, updated_at
-             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)
+             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
              ON CONFLICT(instance_id) DO UPDATE SET
                 agent_type = excluded.agent_type,
                 thread_id = excluded.thread_id,
                 runtime_config = excluded.runtime_config,
                 source_kind = excluded.source_kind,
                 source_document_path = excluded.source_document_path,
-                source_memo_id = excluded.source_memo_id,
                 source_notebook_id = excluded.source_notebook_id,
                 source_relative_path = excluded.source_relative_path,
                 updated_at = excluded.updated_at
@@ -427,7 +449,6 @@ impl ThreadManager {
                 runtime_config,
                 source_kind,
                 input.source.document_path,
-                Option::<String>::None,
                 input.source.notebook_id,
                 input.source.relative_path,
                 created_at,
@@ -441,15 +462,14 @@ impl ThreadManager {
         // repository methods.
         tx.execute(
             "INSERT INTO agent_instances (
-                id, agent, config_json, source, document_path, memo_id,
+                id, agent, config_json, source, document_path,
                 notebook_id, relative_path, created_at, updated_at
-             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
+             ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
              ON CONFLICT(id) DO UPDATE SET
                 agent = excluded.agent,
                 config_json = excluded.config_json,
                 source = excluded.source,
                 document_path = excluded.document_path,
-                memo_id = excluded.memo_id,
                 notebook_id = excluded.notebook_id,
                 relative_path = excluded.relative_path,
                 updated_at = excluded.updated_at
@@ -460,7 +480,6 @@ impl ThreadManager {
                 runtime_config,
                 source_kind,
                 input.source.document_path,
-                Option::<String>::None,
                 input.source.notebook_id,
                 input.source.relative_path,
                 created_at,
@@ -523,15 +542,15 @@ impl ThreadManager {
             .query_row(
                 "SELECT
                     i.id, i.agent, ti.title, ti.id, i.config_json,
-                    legacy.frozen_cwd, i.source, i.document_path, i.memo_id,
-                    NULL, NULL, i.created_at, i.updated_at, i.notebook_id,
+                    legacy.frozen_cwd, i.source, i.document_path,
+                    i.created_at, i.updated_at, i.notebook_id,
                     COALESCE(
                         CASE i.agent
                             WHEN 'codex' THEN (SELECT external_id FROM threads_codex WHERE thread_id = ti.id)
-                            WHEN 'deepseek-harness' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
+                            WHEN 'dsh' THEN (SELECT external_id FROM threads_dsh WHERE thread_id = ti.id)
                             WHEN 'opencode' THEN (SELECT external_id FROM threads_opencode WHERE thread_id = ti.id)
                             WHEN 'hermes' THEN (SELECT external_id FROM threads_hermes WHERE thread_id = ti.id)
-                            WHEN 'claude' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
+                            WHEN 'claudecode' THEN (SELECT external_id FROM threads_claude WHERE thread_id = ti.id)
                             WHEN 'pi' THEN (SELECT external_id FROM threads_pi WHERE thread_id = ti.id)
                         END,
                         (SELECT external_session_id FROM thread_external_sessions
@@ -899,20 +918,20 @@ impl ThreadManager {
         let source = AgentConversationSource {
             kind: row.get(6)?,
             document_path: row.get(7)?,
-            relative_path: row.get(15)?,
-            notebook_id: row.get(13)?,
+            relative_path: row.get(12)?,
+            notebook_id: row.get(10)?,
         };
         Ok(AgentConversationInstance {
             instance_id: row.get(0)?,
             agent_type: row.get(1)?,
             thread_title: row.get(2)?,
             thread_id: row.get(3)?,
-            session_id: row.get(14)?,
+            session_id: row.get(11)?,
             runtime_config: row.get(4)?,
             frozen_cwd: row.get(5)?,
             source,
-            created_at: row.get(11)?,
-            updated_at: row.get(12)?,
+            created_at: row.get(8)?,
+            updated_at: row.get(9)?,
         })
     }
 }
diff --git a/app/flowix-desktop/src/agent_session/store/external.rs b/app/flowix-desktop/src/agent_session/store/external.rs
index afdef4fc0..deeb44075 100644
--- a/app/flowix-desktop/src/agent_session/store/external.rs
+++ b/app/flowix-desktop/src/agent_session/store/external.rs
@@ -11,8 +11,8 @@ use crate::agent_types::AgentId;
 use rusqlite::{params, Connection, OptionalExtension};
 use sha2::{Digest, Sha256};
 use std::collections::{HashMap, HashSet};
-use std::sync::Arc;
 use std::path::PathBuf;
+use std::sync::Arc;
 
 const MAX_EXTERNAL_EVENTS_PER_THREAD: i64 = 10_000;
 const EXTERNAL_HISTORY_TRUNCATED_JSON: &str = r#"{"kind":"history_truncated","version":1}"#;
@@ -488,11 +488,11 @@ impl ThreadManager {
     ) -> Result<Option<ThreadMessagesPage>, ThreadError> {
         let thread_id = thread_id.to_string();
         self.run_blocking(move |tm| {
-            if !tm.external_event_history_exists_inner("claude", &thread_id)? {
+            if !tm.external_event_history_exists_inner("claudecode", &thread_id)? {
                 return Ok(None);
             }
             tm.get_external_event_messages_page_inner(
-                "claude",
+                "claudecode",
                 &thread_id,
                 before_event_id,
                 turn_limit,
@@ -649,7 +649,7 @@ impl ThreadManager {
 
         let messages = materialize_external_messages(events);
         Ok(ThreadMessagesPage {
-            messages: if runtime == "deepseek-harness" {
+            messages: if runtime == "dsh" {
                 normalize_legacy_deepseek_thinking(messages)
             } else {
                 messages
@@ -747,7 +747,7 @@ pub(crate) fn materialize_external_messages(events: Vec<AgentExternalEvent>) ->
                 };
                 let mut message_id =
                     external_run_scoped_id(&event.runtime, &payload, role, &message_id);
-                if event.runtime == "deepseek-harness" {
+                if event.runtime == "dsh" {
                     if let Some(run_key) = external_event_run_key(&event.runtime, &payload) {
                         let segment_key = format!("{run_key}:{message_id}");
                         let current_id = dsh_current_assistant_ids
@@ -804,7 +804,7 @@ pub(crate) fn materialize_external_messages(events: Vec<AgentExternalEvent>) ->
                 messages.push(message);
             }
             Some("tool_call") => {
-                if event.runtime == "deepseek-harness" {
+                if event.runtime == "dsh" {
                     if let Some(run_key) = external_event_run_key(&event.runtime, &payload) {
                         dsh_pending_assistant_segment.insert(run_key);
                     }
@@ -854,7 +854,7 @@ pub(crate) fn materialize_external_messages(events: Vec<AgentExternalEvent>) ->
                 }
             }
             Some("tool_result") => {
-                if event.runtime == "deepseek-harness" {
+                if event.runtime == "dsh" {
                     if let Some(run_key) = external_event_run_key(&event.runtime, &payload) {
                         dsh_pending_assistant_segment.insert(run_key);
                     }
diff --git a/app/flowix-desktop/src/agent_session/store/messages.rs b/app/flowix-desktop/src/agent_session/store/messages.rs
index 0a7636c08..8b7f9fff8 100644
--- a/app/flowix-desktop/src/agent_session/store/messages.rs
+++ b/app/flowix-desktop/src/agent_session/store/messages.rs
@@ -204,8 +204,8 @@ impl ThreadManager {
     /// Startup cleanup: reset all `is_loading = 1` rows, regardless of role.
     ///
     /// This handles crashes after a tool_use row was persisted but before its
-    /// tool_result arrived. The synchronous version is intentional: startup calls
-    /// this before the Tauri runtime is available, and the work is a single SQLite UPDATE.
+    /// tool_result arrived. Startup calls this before publishing native ready,
+    /// so it cannot clear loading rows created by a new interactive run.
     /// Returns the affected row count for startup logging.
     pub fn clear_all_loading(&self) -> Result<u64, ThreadError> {
         let conn = self.lock_conn();
diff --git a/app/flowix-desktop/src/agent_session/store/provider.rs b/app/flowix-desktop/src/agent_session/store/provider.rs
index 3f9c41152..418d7a011 100644
--- a/app/flowix-desktop/src/agent_session/store/provider.rs
+++ b/app/flowix-desktop/src/agent_session/store/provider.rs
@@ -25,10 +25,10 @@ impl ProviderThreadStore {
     pub(super) fn for_runtime(runtime: &str) -> Option<Self> {
         match runtime {
             "codex" => Some(Self::Codex),
-            "deepseek-harness" => Some(Self::Dsh),
+            "dsh" => Some(Self::Dsh),
             "opencode" => Some(Self::OpenCode),
             "hermes" => Some(Self::Hermes),
-            "claude" => Some(Self::Claude),
+            "claudecode" => Some(Self::Claude),
             "pi" => Some(Self::Pi),
             _ => None,
         }
diff --git a/app/flowix-desktop/src/agent_session/tests.rs b/app/flowix-desktop/src/agent_session/tests.rs
index 88c2d2a43..b11d9e17a 100644
--- a/app/flowix-desktop/src/agent_session/tests.rs
+++ b/app/flowix-desktop/src/agent_session/tests.rs
@@ -308,20 +308,20 @@ mod tests {
         let manager = ThreadManager::for_tests();
         let first = manager
             .ensure_thread(
-                "gemini-local-1",
-                AgentId("gemini".to_string()),
+                "codex-local-1",
+                AgentId("codex".to_string()),
                 "first title".to_string(),
             )
             .await
             .unwrap();
-        assert_eq!(first.thread_id, "gemini-local-1");
-        assert_eq!(first.agent_id.0, "gemini");
+        assert_eq!(first.thread_id, "codex-local-1");
+        assert_eq!(first.agent_id.0, "codex");
         assert_eq!(first.title, "first title");
 
         let second = manager
             .ensure_thread(
-                "gemini-local-1",
-                AgentId("gemini".to_string()),
+                "codex-local-1",
+                AgentId("codex".to_string()),
                 "second title".to_string(),
             )
             .await
@@ -550,14 +550,14 @@ mod tests {
             Some("Notes/Renamed.md")
         );
         let conn = manager.lock_conn();
-        let source_id: Option<String> = conn
-            .query_row(
-                "SELECT source_memo_id FROM agent_conversation_instances WHERE instance_id = ?1",
-                ["path-role"],
-                |row| row.get(0),
-            )
+        let columns = conn
+            .prepare("PRAGMA table_info(agent_conversation_instances)")
+            .unwrap()
+            .query_map([], |row| row.get::<_, String>(1))
+            .unwrap()
+            .collect::<Result<Vec<_>, _>>()
             .unwrap();
-        assert!(source_id.is_none());
+        assert!(!columns.iter().any(|column| column == "source_memo_id"));
     }
 
     #[tokio::test]
@@ -1368,31 +1368,38 @@ mod tests {
     }
 
     #[test]
-    fn migration_removes_persisted_role_file_selection() {
+    fn migration_drops_retired_role_note_columns() {
         let dir = tempfile::tempdir().expect("tempdir");
         let db_path = dir.path().join("thread.db");
         drop(ThreadManager::new(db_path.clone()).expect("create database"));
         let conn = rusqlite::Connection::open(&db_path).expect("open database");
         conn.execute_batch(
-            "INSERT INTO agent_conversation_instances
-                (instance_id, agent_type, source_kind, role_memo_id, role_address, role_name, created_at, updated_at)
-             VALUES ('legacy-role', 'codex', 'dedicated', 'old-id', 'nb::Role.md', 'Role', 1, 1);
+            "ALTER TABLE agent_conversation_instances ADD COLUMN role_address TEXT;
+             ALTER TABLE agent_conversation_instances ADD COLUMN role_name TEXT;
+             ALTER TABLE agent_instances ADD COLUMN role_address TEXT;
+             ALTER TABLE agent_instances ADD COLUMN role_name TEXT;
+             INSERT INTO agent_conversation_instances
+                (instance_id, agent_type, source_kind, role_address, role_name, created_at, updated_at)
+             VALUES ('legacy-role', 'codex', 'dedicated', 'nb::Role.md', 'Role', 1, 1);
              INSERT INTO agent_instances
-                (id, agent, source, role_memo_id, role_address, role_name, created_at, updated_at)
-             VALUES ('legacy-role', 'codex', 'dedicated', 'old-id', 'nb::Role.md', 'Role', 1, 1);
-             PRAGMA user_version = 10;",
+                (id, agent, source, role_address, role_name, created_at, updated_at)
+             VALUES ('legacy-role', 'codex', 'dedicated', 'nb::Role.md', 'Role', 1, 1);
+             PRAGMA user_version = 15;",
         ).expect("seed previous role data");
         drop(conn);
 
         drop(ThreadManager::new(db_path.clone()).expect("migrate role data"));
         let conn = rusqlite::Connection::open(&db_path).expect("open migrated database");
         for table in ["agent_conversation_instances", "agent_instances"] {
-            let remaining: i64 = conn.query_row(
-                &format!("SELECT count(*) FROM {table} WHERE role_memo_id IS NOT NULL OR role_address IS NOT NULL OR role_name IS NOT NULL"),
-                [],
-                |row| row.get(0),
-            ).expect("read cleared roles");
-            assert_eq!(remaining, 0);
+            let columns = conn
+                .prepare(&format!("PRAGMA table_info({table})"))
+                .expect("inspect migrated columns")
+                .query_map([], |row| row.get::<_, String>(1))
+                .expect("query migrated columns")
+                .collect::<Result<Vec<_>, _>>()
+                .expect("collect migrated columns");
+            assert!(!columns.iter().any(|column| column == "role_address"));
+            assert!(!columns.iter().any(|column| column == "role_name"));
         }
     }
 
@@ -1438,7 +1445,7 @@ mod tests {
     }
 
     #[test]
-    fn newer_thread_schema_is_rejected() {
+    fn newer_thread_schema_is_rejected_without_rebuilding_user_data() {
         let dir = tempfile::tempdir().expect("tempdir");
         let db_path = dir.path().join("thread.db");
         let conn = rusqlite::Connection::open(&db_path).expect("open database");
@@ -1450,17 +1457,11 @@ mod tests {
         .expect("set future schema version");
         drop(conn);
 
-        let error = match ThreadManager::new(db_path) {
-            Ok(_) => panic!("future schema must be rejected"),
-            Err(error) => error,
-        };
-        assert!(matches!(
-            error,
-            crate::agent_session::error::ThreadError::UnsupportedSchemaVersion {
-                found,
-                supported
-            } if found == supported + 1
-        ));
+        assert!(ThreadManager::new(db_path.clone()).is_err());
+        assert!(!dir.path().join("rebuild-backups").exists());
+        let preserved = rusqlite::Connection::open(db_path).unwrap();
+        let version: i64 = preserved.pragma_query_value(None, "user_version", |row| row.get(0)).unwrap();
+        assert_eq!(version, crate::agent_session::migrations::THREAD_DB_SCHEMA_VERSION + 1);
     }
 
     #[tokio::test]
diff --git a/app/flowix-desktop/src/agent_wire.rs b/app/flowix-desktop/src/agent_wire.rs
index 4fa5c89db..f8f27fef7 100644
--- a/app/flowix-desktop/src/agent_wire.rs
+++ b/app/flowix-desktop/src/agent_wire.rs
@@ -64,6 +64,8 @@ pub struct RuntimePathConfig {
 #[derive(Serialize, Deserialize, Clone, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct AgentRuntimeConfig {
+    /// Notebook scope used to validate persisted workspace paths before each run.
+    pub notebook_id: Option<String>,
     pub codex: Option<RuntimePathConfig>,
     pub claude: Option<RuntimePathConfig>,
     pub hermes: Option<RuntimePathConfig>,
@@ -165,11 +167,11 @@ impl AgentUserMessage {
         let config = self.runtime_config.as_ref()?;
         match runtime {
             "codex" => config.codex.as_ref(),
-            "claude" => config.claude.as_ref(),
+            "claudecode" => config.claude.as_ref(),
             "hermes" => config.hermes.as_ref(),
             "opencode" => config.opencode.as_ref(),
             "pi" => config.pi.as_ref(),
-            "deepseek-harness" => config.deepseek_harness.as_ref(),
+            "dsh" => config.deepseek_harness.as_ref(),
             _ => None,
         }
     }
diff --git a/app/flowix-desktop/src/app/bootstrap.rs b/app/flowix-desktop/src/app/bootstrap.rs
index a7c4f310e..951687be1 100644
--- a/app/flowix-desktop/src/app/bootstrap.rs
+++ b/app/flowix-desktop/src/app/bootstrap.rs
@@ -14,15 +14,13 @@ use crate::app::watchdog::spawn_external_agent_watchdog;
 use crate::cli_link;
 use crate::commands;
 use crate::config::user as user_config;
-use crate::config::AgentAccessStore;
-use crate::config::SecurityBookmarkStore;
 use crate::events as dispatcher;
 use crate::memo_events::{self, MemoChangeSource, MemoDerivedChanged, MemoEvent};
-use crate::plugin;
 use crate::runtime_log;
 use crate::system_data::SystemData;
 use crate::watcher::MemoWatcher;
 use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, RwLock};
 use std::time::{Duration, Instant};
 use tauri::{Emitter, Listener, Manager};
@@ -35,20 +33,13 @@ fn record_startup_stage(startup: &crate::app::startup::StartupCoordinator, stage
     );
 }
 
-fn record_slow_notebook_stage(notebook_id: &str, stage: &str, elapsed: Duration) {
-    if elapsed < Duration::from_millis(250) {
-        return;
-    }
-    runtime_log::record_event(
-        "info",
-        "startup.notebook_stage",
-        serde_json::json!({
-            "notebookId": notebook_id,
-            "stage": stage,
-            "elapsedMs": elapsed.as_millis(),
-        })
-        .to_string(),
-    );
+// Only the durable per-version completion record controls the first stage.
+// Missing migration journals, old settings, and rebuilt databases must never
+// move an initialized installation back into version initialization.
+fn version_initialization_pending(
+    device_registry: &crate::device_registration::DeviceRegistry,
+) -> bool {
+    !device_registry.is_version_initialization_complete()
 }
 
 pub fn run() {
@@ -80,13 +71,16 @@ pub fn run() {
 
     let user_config_dir = get_user_config_dir(&home_dir);
     std::fs::create_dir_all(&user_config_dir).ok();
-    if let Err(error) = plugin::ensure_builtin_plugins() {
-        tracing::warn!("[startup] failed to initialize plugins: {error}");
-    }
-    let thread_db_path = user_config_dir.join("thread.db");
+    // Only choose the canonical location here. Path migration uses VACUUM INTO
+    // and runs in the startup worker, where its progress can reach the WebView.
+    let database_dir = user_config_dir.join("db");
+    let thread_db_path = database_dir.join("thread.db");
     let user_config = Arc::new(user_config::UserConfigStore::new(home_dir.clone()));
+    let security_bookmarks = Arc::new(crate::config::SecurityBookmarkStore::new(
+        user_config_dir.clone(),
+    ));
 
-    // 笔�?�?��册表真源�?~/.flowix/index.db (SQLite); `MemoFile::open_index_db`
+    // 笔记本注册表真源为 ~/.flowix/db/local.db (SQLite); MemoFile 按需建表
     // 首�?�??时建表�?这里不需要任何�?盘迁�?── �?`notebook.json` �?��已废�?
     let memo_file = flowix_core::memo_file::MemoFile::new(user_config_dir.clone());
 
@@ -105,7 +99,7 @@ pub fn run() {
     };
 
     // External CLI 璺緞閰嶇疆 (~/.flowix/agent-external-config.json) 鈹€鈹€
-    // 作为 codex/claude/gemini/hermes/openclaw 执�?�?��的唯一参照�?
+    // Supported external Agents use agent-external-config as their path source.
     let agent_external_config_path = user_config_dir.join("agent-external-config.json");
     let agent_external_config = match AgentExternalConfig::new(agent_external_config_path.clone()) {
         Ok(store) => store,
@@ -120,7 +114,7 @@ pub fn run() {
 
     let memo_file_arc = Arc::new(RwLock::new(memo_file));
     let notebook_transition = Arc::new(std::sync::Mutex::new(()));
-    let thread_manager = match ThreadManager::new(thread_db_path.clone()) {
+    let thread_manager = match ThreadManager::new_uninitialized(thread_db_path.clone()) {
         Ok(manager) => manager,
         Err(err) => {
             tracing::error!(
@@ -133,16 +127,11 @@ pub fn run() {
         }
     };
     let thread_manager_arc = Arc::new(thread_manager);
-    // Orphaned tool loading rows are cleared after the first workspace paint.
+    // Orphaned tool loading rows are cleared before native ready is published.
     let user_config_arc = user_config.clone();
 
     // Agent �??�?���?store ── 必须�?notebook registry �?`memo_file_arc`
     // 都就�?��后构�?(�?store 会�? notebook registry �?? + 对账)�?
-    let security_bookmarks_arc = Arc::new(SecurityBookmarkStore::new(user_config_dir.clone()));
-    let agent_access_arc = Arc::new(AgentAccessStore::new(
-        user_config_dir.clone(),
-        &*crate::lock_utils::read_lock(&memo_file_arc, "memo_file"),
-    ));
 
     // 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
     // 监听 user-config-changed �?���?whitelist �? 也需�?user_config_arc,
@@ -152,9 +141,8 @@ pub fn run() {
     // 这里把构�?AppState 需要的子结�?clone 出来 (�?�� `move` 捕获),
     // 同时把另一�?clone 喂给 sub-component 构造函数�?
     let user_config_for_state = user_config_arc.clone();
+    let security_bookmarks_for_state = security_bookmarks.clone();
     let memo_file_for_state = memo_file_arc.clone();
-    let agent_access_for_state = agent_access_arc.clone();
-    let security_bookmarks_for_state = security_bookmarks_arc.clone();
     let thread_manager_for_state = thread_manager_arc.clone();
     let startup_for_state = startup_coordinator.clone();
     let notebook_transition_for_state = notebook_transition.clone();
@@ -213,6 +201,15 @@ pub fn run() {
         .plugin(crate::frame_scrollbar::init())
         .manage(crate::app_update::AppUpdateState::default())
         .manage(memo_watcher.clone())
+        .on_window_event(commands::window_shutdown::on_window_event)
+        .on_page_load(|webview, payload| {
+            #[cfg(windows)]
+            if payload.event() == tauri::webview::PageLoadEvent::Started {
+                commands::window_shutdown::clear_native_region(&webview.window());
+            }
+            #[cfg(not(windows))]
+            let _ = (webview, payload);
+        })
         .on_webview_event(|webview, event| {
             if let tauri::WebviewEvent::DragDrop(tauri::DragDropEvent::Drop { paths, .. }) = event {
                 let state = webview.state::<AppState>();
@@ -228,24 +225,8 @@ pub fn run() {
                 flowix_installer_helper::listen_for_shutdown(move || shutdown_app.exit(0));
             }
             record_startup_stage(&startup_coordinator, "native-setup-start");
-            if let Err(error) = crate::template_store::initialize(&user_config_dir_for_device) {
-                tracing::warn!("[startup] failed to initialize template directories: {error}");
-            }
-
-            // Read the notebook registry synchronously so AppState can be
-            // created. Structural migrations themselves are scheduled after
-            // AppState and IPC are available; the startup coordinator is the
-            // gate for the WebView and notebook-dependent commands.
-            let initial_notebooks = {
-                let memo_file = crate::lock_utils::read_lock(&memo_file_arc, "memo_file");
-                let notebooks = memo_file.read_notebook_configs()?;
-                for notebook in &notebooks {
-                    security_bookmarks_for_state
-                        .start_accessing_for_path(std::path::Path::new(&notebook.path));
-                }
-                notebooks
-            };
-
+            // Registry import and notebook inspection run in the startup
+            // initialization worker after AppState exists.
             // 鈹€鈹€ 0) 鍚姩璁惧鐧昏 / last_seen 鍒锋柊 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
             //   不阻�? spawn 一�?fire-and-forget tokio 任务, �?��内部
             //   �?sleep 10s �?POST, 与产品更�?7s 检查错开。远�?��
@@ -255,8 +236,19 @@ pub fn run() {
                 &user_config_dir_for_device,
                 app_version,
             ));
+            if version_initialization_pending(&device_registry) {
+                startup_coordinator.mark_running(
+                    crate::app::startup::StartupStage::Initialization,
+                    "versionInitialization",
+                );
+            } else {
+                startup_coordinator.mark_running(
+                    crate::app::startup::StartupStage::WorkspacePreparation,
+                    "preparingData",
+                );
+            }
             device_registry.clone().spawn_startup_registration();
-            app.manage(device_registry);
+            app.manage(device_registry.clone());
 
             // 鈹€鈹€ 1) 鍚姩鎺㈡祴 external CLI 璺緞 鈹€鈹€
             //   �?source=auto/缺失�?agent 跑探测链 (env>PATH>候�?shell),
@@ -264,6 +256,44 @@ pub fn run() {
             // can spawn processes, so run it after the first workspace paint.
             agent_external_config.load_into_registry();
 
+            let is_dev_build = option_env!("FLOWIX_DEV_MODE") == Some("1");
+            // A saved Preferences selection is the source of truth. The build
+            // target only supplies the initial/default environment.
+            let cloud_environment = if is_dev_build {
+                let saved_environment = user_config_for_state
+                    .get_preference()
+                    .cloud_environment;
+                flowix_sync::CloudEnvironment::parse(&saved_environment)
+                    .unwrap_or_else(flowix_sync::default_cloud_environment)
+            } else {
+                flowix_sync::CloudEnvironment::Prod
+            };
+            runtime_log::record_event(
+                "info",
+                "cloud.environment.selected",
+                format!(
+                    "environment={}, api_base={}",
+                    cloud_environment.name(),
+                    cloud_environment.api_base()
+                ),
+            );
+            let cloud_sync_db_path = if is_dev_build {
+                user_config_dir_for_device
+                    .join("db")
+                    .join(format!("sync-dev-{}.db", cloud_environment.name()))
+            } else {
+                user_config_dir_for_device.join("db").join("sync.db")
+            };
+            let cloud_refresh_token_store: Arc<dyn flowix_sync::RefreshTokenStore> =
+                if is_dev_build {
+                    Arc::new(crate::config::CloudDevRefreshTokenStore::new(
+                        user_config_for_state.clone(),
+                        cloud_environment,
+                    ))
+                } else {
+                    user_config_for_state.clone()
+                };
+
             let cloud_state_app = app.handle().clone();
             let cloud_state_notifier: Arc<dyn Fn(flowix_sync::CloudState) + Send + Sync> =
                 Arc::new(move |state| {
@@ -272,32 +302,40 @@ pub fn run() {
                     }
                 });
             let cloud_sync_for_state = Arc::new(
-                flowix_sync::SyncManager::new_with_session_dependencies(
-                    flowix_sync::DEFAULT_CLOUD_API_BASE,
-                    user_config_dir_for_device.join("sync.db"),
-                    user_config_for_state.clone(),
+                flowix_sync::SyncManager::new_with_session_dependencies_deferred(
+                    cloud_environment.api_base(),
+                    &cloud_sync_db_path,
+                    cloud_refresh_token_store.clone(),
                     cloud_state_notifier.clone(),
                 )
                 .unwrap_or_else(|error| {
                     tracing::error!(
                         "failed to initialize cloud sync database: {error}; using a temporary database"
                     );
-                    flowix_sync::SyncManager::new_with_session_dependencies(
-                        flowix_sync::DEFAULT_CLOUD_API_BASE,
+                    flowix_sync::SyncManager::new_with_session_dependencies_deferred(
+                        cloud_environment.api_base(),
                         std::env::temp_dir().join(format!("flowix-sync-{}.db", std::process::id())),
-                        user_config_for_state.clone(),
+                        cloud_refresh_token_store.clone(),
                         cloud_state_notifier.clone(),
                     )
                     .expect("failed to initialize temporary cloud sync database")
                 }),
             );
 
+            crate::dsh::set_user_selected_cli(
+                user_config_for_state
+                    .get_preference()
+                    .dsh_cli_path
+                    .map(std::path::PathBuf::from),
+            );
             let app_state = AppState {
                 upload_sessions: Default::default(),
                 document_access: Default::default(),
+                security_bookmarks: security_bookmarks_for_state.clone(),
                 export_access: Default::default(),
                 user_config: user_config_for_state.clone(),
                 cloud_sync: cloud_sync_for_state.clone(),
+                cloud_environment,
                 system_data,
                 agent_external_config,
                 memo_file: memo_file_for_state.clone(),
@@ -309,22 +347,25 @@ pub fn run() {
                 agent_history: agent_history.clone(),
                 agent_lifecycle: agent_lifecycle.clone(),
                 thread_manager: thread_manager_for_state.clone(),
-                agent_access: agent_access_for_state.clone(),
-                security_bookmarks: security_bookmarks_for_state.clone(),
                 plugin_runs: crate::plugin::PluginRunCoordinator::default(),
                 notebook_imports: Default::default(),
+                notebook_background: Default::default(),
                 notebook_template_initializations: Default::default(),
                 notebook_transition: notebook_transition_for_state,
                 startup: startup_for_state,
+                watcher_retry_stop: Arc::new(AtomicBool::new(false)),
             };
             app_state.upload_sessions.start_cleanup();
             app.manage(app_state);
-            let session_manager = cloud_sync_for_state.clone();
-            tauri::async_runtime::spawn(async move {
-                session_manager.run_session_service().await;
-            });
             external_runtimes.listen_for_terminal_events(app.handle());
+            #[cfg(windows)]
+            {
+                if let Err(error) = crate::native_close_region::start() {
+                    tracing::warn!("native close input retrying: {error}");
+                }
+            }
             if let Some(window) = app.get_webview_window("main") {
+                commands::window_shutdown::install_window(&window);
                 // �?��即�?齐主题背�?��, 消除冷启动白�?(尤其深色主�?)�?
                 let theme = app.state::<AppState>().user_config.get_preference().theme;
                 crate::window_chrome::apply_window_chrome_theme(&window, theme);
@@ -362,18 +403,6 @@ pub fn run() {
             app.manage(commands::file_browser_watch::FileBrowserWatchState::new(
                 app.handle().clone(),
             ));
-            // Restore security-scoped access for user-selected reference
-            // folders as well. External CLI children inherit the parent's
-            // active extensions, so this must happen before any agent spawn.
-            for entry in agent_access_for_state
-                .get_config()
-                .entries
-                .into_iter()
-                .filter(|entry| entry.enabled && !entry.missing)
-            {
-                security_bookmarks_for_state
-                    .start_accessing_for_path(std::path::Path::new(&entry.path));
-            }
             // �?��时把 preference.json::watcher 应用�?MemoWatcher;
             // 同时监听 user-config-changed，在偏好更新后热加载 watcher 规则。
             {
@@ -408,16 +437,18 @@ pub fn run() {
             }
 
             register_deep_links(app);
-            spawn_startup_reconciliation(
+            spawn_workbench_startup(
                 app.handle().clone(),
-                initial_notebooks.clone(),
                 memo_file_for_state.clone(),
+                cloud_sync_for_state.clone(),
                 memo_watcher.clone(),
                 user_config_for_watcher.clone(),
                 startup_coordinator.clone(),
                 external_runtimes.clone(),
                 user_config_dir_for_device.clone(),
                 thread_manager_for_state.clone(),
+                device_registry,
+                app.state::<AppState>().watcher_retry_stop.clone(),
             );
             record_startup_stage(&startup_coordinator, "native-setup-complete");
 
@@ -430,6 +461,7 @@ pub fn run() {
         .invoke_handler(tauri::generate_handler![
             // 偏好 (JSON, �?user_config)
             commands::product::get_product_info,
+            commands::product::set_cloud_environment,
             commands::product::open_log_dir,
             commands::product::open_file_with_default_app,
             commands::product::reveal_in_file_manager,
@@ -465,20 +497,16 @@ pub fn run() {
             commands::settings::delete_pi_mcp_server,
             commands::settings::get_pi_features,
             commands::settings::save_pi_features,
+            commands::settings::clear_pi_legacy_code_mode,
             commands::settings::get_pi_model_catalog,
             commands::settings::save_pi_model_config,
             commands::settings::delete_pi_model_config,
             commands::settings::test_pi_model_config,
             commands::settings::discover_pi_models,
             commands::dsh::dsh_status,
-            commands::dsh::dsh_check_update,
-            commands::dsh::dsh_archive_size,
-            commands::dsh::dsh_download_status,
-            commands::dsh::dsh_install_runtime,
-            commands::dsh::dsh_update,
-            commands::dsh::dsh_ensure_runtime,
-            commands::dsh::dsh_cancel_update,
-            commands::dsh::dsh_uninstall,
+            commands::dsh::dsh_select_cli_path,
+            commands::dsh::dsh_set_cli_path,
+            commands::dsh::dsh_install_appserver_profile,
             commands::dsh::dsh_manage_profile_plugin,
             crate::app_update::install_app_update,
             crate::app_update::check_app_update,
@@ -486,8 +514,10 @@ pub fn run() {
             crate::app_update::cancel_app_update,
             commands::boot::get_boot_features,
             commands::boot::set_boot_intro_displayed,
-            commands::boot::set_boot_onboarding_completed,
+            commands::boot::get_version_initialization_completed,
+            commands::boot::set_version_initialization_completed,
             commands::boot::get_startup_status,
+            commands::boot::retry_startup,
             commands::boot::get_startup_notebook_id,
             commands::boot::notify_startup_interactive,
             commands::boot::record_startup_stage,
@@ -506,8 +536,15 @@ pub fn run() {
             commands::cloud::cloud_link_notebook,
             commands::cloud::cloud_set_notebook_enabled,
             commands::cloud::cloud_refresh_membership,
+            commands::cloud::cloud_ai_credit_balance,
+            commands::cloud::cloud_connect_pi_model_provider,
+            commands::cloud::cloud_refresh_pi_model_provider_at_startup,
+            commands::cloud::cloud_refresh_pi_model_provider,
             commands::cloud::cloud_list_products,
+            commands::cloud::cloud_list_billing_orders,
+            commands::cloud::cloud_check_billing_order,
             commands::cloud::cloud_create_checkout,
+            commands::cloud::cloud_submit_feedback,
             commands::cloud::cloud_sync_now,
             commands::cloud::cloud_note_history,
             commands::cloud::list_local_path_archives,
@@ -517,11 +554,11 @@ pub fn run() {
             commands::cloud::cloud_resolve_markdown_conflict,
             commands::cloud::cloud_resolve_attachment_conflict,
             commands::cloud::cloud_restore_note_revision,
-            // agent 鍙闂洰褰?(JSON, 璧?agent_access)
-            commands::agent_access::get_agent_access,
-            commands::agent_access::set_agent_access,
-            commands::agent_access::get_notebook_agent_configs,
-            commands::agent_access::set_notebook_agent_config,
+            // Device-local notebook workspaces (local.db).
+            commands::agent_workspace::get_agent_workspace,
+            commands::agent_workspace::get_legacy_agent_preferences,
+            commands::agent_workspace::attach_notebook_directory,
+            commands::agent_workspace::detach_notebook_directory,
             // System metadata (JSON, ~/.flowix/boot/system.json)
             commands::kv::get_tag_system_metadata,
             commands::kv::set_tag_system_layout,
@@ -552,22 +589,22 @@ pub fn run() {
             commands::memo::reads::write_document,
             commands::document_operations::document_operation_status,
             commands::document_operations::acknowledge_document_operation,
-            commands::document_shutdown::register_document_window,
-            commands::document_shutdown::finish_document_shutdown,
-            commands::document_shutdown::flush_document_background,
+            commands::window_shutdown::register_document_window,
+            commands::window_shutdown::finish_document_shutdown,
+            commands::window_shutdown::finish_document_close,
             commands::recovery::write_recovery_draft,
             commands::recovery::read_recovery_draft,
             commands::recovery::clear_recovery_draft_through,
             commands::recovery::list_recovery_drafts,
             commands::external_document::read_external_document,
-            commands::external_document::get_external_document_mime_type,
+            commands::external_document::detect_external_document_text,
             commands::external_document::write_external_document,
             commands::memo::reads::get_launch_open_files,
             commands::memo::reads::search_path_notes,
             commands::memo::creates::add_path_document,
             commands::memo::creates::list_notebook_templates,
             commands::memo::creates::initialize_notebook_template,
-            commands::memo::creates::ensure_notebook_template_setup,
+            commands::notebook_setup::ensure_notebook_template_setup,
             commands::memo::creates::import_external_document_by_path,
             commands::memo::creates::rename_memo_title,
             commands::memo::creates::move_memo_to_directory,
@@ -582,20 +619,26 @@ pub fn run() {
             commands::memo::deletes::prune_missing_memo,
             // tag
             commands::tag::get_all_tags,
-            commands::tag::create_notebook_tag,
             commands::tag::move_memo_tag,
             commands::tag::delete_memo_tag,
             commands::tag::get_tag_prefix_counts,
             // notebook
             commands::notebook::get_notebooks,
+            commands::notebook::set_notebook_pinned,
+            commands::notebook::get_notebook_background_status,
+            commands::notebook::get_notebook_media_maintenance_status,
+            commands::notebook::request_notebook_media_maintenance,
+            commands::notebook::request_notebook_refresh,
             commands::notebook::get_default_notebook_path,
             commands::notebook::confirm_notebook_preset_overwrite,
             commands::notebook::ensure_default_notebook_path,
             commands::notebook::create_notebook,
             commands::notebook::create_notebook_from_cloud,
             commands::notebook::start_notebook_import,
-            commands::notebook::get_notebook_template_setup_status,
-            commands::notebook::start_notebook_template_setup,
+            commands::notebook_setup::get_notebook_template_setup_status,
+            commands::notebook_setup::start_notebook_template_setup,
+            commands::notebook_setup::start_or_resume_ready_notebook_template_setups,
+            commands::notebook_setup::get_notebook_template_setup_snapshot,
             commands::notebook::get_notebook_import_status,
             commands::notebook::update_notebook,
             commands::notebook::delete_notebook,
@@ -631,6 +674,7 @@ pub fn run() {
             commands::file::move_file,
             commands::file::move_folder,
             commands::file::import_file,
+            commands::file::folder_import::import_folder,
             commands::file::rename_folder,
             commands::file::delete_file,
             commands::file::delete_folder,
@@ -646,6 +690,7 @@ pub fn run() {
             commands::web::parse_web_page,
             // dialog
             commands::dialog::select_directory,
+            commands::dialog::select_import_directory,
             commands::dialog::select_files,
             commands::dialog::save_file_dialog,
             commands::dialog::write_export_file,
@@ -657,7 +702,7 @@ pub fn run() {
             commands::dialog::upload_sessions::cancel_attachment_upload,
             commands::dialog::copy_attachment_file,
             commands::dialog::open_attachment_file,
-            commands::agent_access::add_agent_access_folder_from_picker,
+            commands::agent_workspace::pick_notebook_directory,
             // agent
             commands::agent::external_config::agent_runtime_status,
             commands::agent::external_config::get_agent_external_config,
@@ -752,6 +797,8 @@ pub fn run() {
             // window
             commands::window::show_main_window,
             commands::window::open_preferences_window,
+            commands::window_input::set_window_close_region,
+            commands::window_input::native_close_routing_ready,
             commands::window::apply_window_theme,
             commands::window::apply_menu_language,
             commands::external_document_watch::watch_external_document,
@@ -767,302 +814,373 @@ pub fn run() {
         .run(handle_run_event);
 }
 
-fn spawn_startup_reconciliation(
+fn spawn_workbench_startup(
     app: tauri::AppHandle,
-    initial_notebooks: Vec<flowix_core::memo_file::NotebookConfig>,
     memo_file: Arc<RwLock<flowix_core::memo_file::MemoFile>>,
+    cloud_sync: Arc<flowix_sync::SyncManager>,
     memo_watcher: Arc<RwLock<MemoWatcher>>,
     user_config_for_watcher: Arc<user_config::UserConfigStore>,
     startup: Arc<crate::app::startup::StartupCoordinator>,
     external_runtimes: Arc<ExternalRuntimeRegistry>,
     user_config_dir: PathBuf,
     thread_manager: Arc<ThreadManager>,
+    device_registry: Arc<crate::device_registration::DeviceRegistry>,
+    watcher_retry_stop: Arc<AtomicBool>,
 ) {
     tauri::async_runtime::spawn_blocking(move || {
-        let started = Instant::now();
-        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            run_startup_reconciliation(
-                &app,
-                &initial_notebooks,
-                &memo_file,
-                &memo_watcher,
-                &user_config_for_watcher,
-                &startup,
-            )
-        }));
-
-        match result {
-            Ok(Ok(())) => {
-                startup.mark_ready();
-                record_startup_stage(&startup, "native-ready");
-                tracing::info!(
-                    elapsed_ms = started.elapsed().as_millis(),
-                    "[startup] workspace ready"
-                );
-                handle_cold_start_open_targets(&app);
-                if !startup.wait_until_interactive(Duration::from_secs(120)) {
-                    tracing::warn!(
-                        "[startup] first workspace paint was not reported within 120 seconds"
+        loop {
+            let started = Instant::now();
+            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                prepare_startup_storage(
+                    &device_registry,
+                    &memo_file,
+                    &thread_manager,
+                    &cloud_sync,
+                    &user_config_for_watcher,
+                    &user_config_dir,
+                    &startup,
+                )?;
+                let initial_notebooks = crate::lock_utils::read_lock(&memo_file, "memo_file")
+                    .read_notebook_configs()
+                    .map_err(|error| format!("reload notebook registry failed: {error}"))?;
+                prepare_notebook_selection(&initial_notebooks, &memo_file, &startup)?;
+                Ok::<_, String>(initial_notebooks)
+            }));
+
+            match result {
+                Ok(Ok(_)) => {
+                    // Clean crash leftovers before any workspace can start a new run.
+                    match thread_manager.clear_all_loading() {
+                        Ok(0) => tracing::debug!("[Startup] no orphan is_loading=1 rows"),
+                        Ok(n) => tracing::info!("[Startup] cleared {n} orphan is_loading=1 rows"),
+                        Err(error) => tracing::warn!("[Startup] clear_all_loading failed: {error}"),
+                    }
+                    startup.mark_ready();
+                    record_startup_stage(&startup, "native-ready");
+                    tracing::info!(
+                        elapsed_ms = started.elapsed().as_millis(),
+                        "[startup] workspace ready"
                     );
-                }
-                record_startup_stage(&startup, "background-start");
-                let app_for_cli_detection = app.clone();
-                tauri::async_runtime::spawn_blocking(move || {
-                    app_for_cli_detection
-                        .state::<AppState>()
-                        .agent_external_config
-                        .run_startup_detect();
-                });
-                match thread_manager.clear_all_loading() {
-                    Ok(0) => tracing::debug!("[Startup] no orphan is_loading=1 rows"),
-                    Ok(n) => tracing::info!("[Startup] cleared {n} orphan is_loading=1 rows"),
-                    Err(error) => tracing::warn!("[Startup] clear_all_loading failed: {error}"),
-                }
-                crate::maintenance::spawn_startup_maintenance(
-                    app.package_info().version.to_string(),
-                    user_config_dir,
-                    thread_manager,
-                );
-                start_post_startup_services(app.clone(), external_runtimes);
-                let current_notebook_id = crate::lock_utils::read_lock(&memo_file, "memo_file")
-                    .current_notebook_id_value();
-                {
-                    let mut watcher = memo_watcher
-                        .write()
-                        .unwrap_or_else(|poisoned| poisoned.into_inner());
-                    for notebook in &initial_notebooks {
-                        if current_notebook_id.as_deref() != Some(notebook.id.as_str())
-                            && !watcher.add_notebook_root(notebook)
-                        {
-                            tracing::warn!(notebook = %notebook.id, "[startup] background notebook watch unavailable");
+                    handle_cold_start_open_targets(&app);
+                    if !startup.wait_until_interactive(Duration::from_secs(120)) {
+                        tracing::warn!(
+                            "[startup] first workspace paint was not reported within 120 seconds; releasing independent services as a degraded liveness fallback"
+                        );
+                        record_startup_stage(&startup, "interactive-timeout-degraded-release");
+                    }
+                    record_startup_stage(&startup, "background-start");
+                    let app_for_cli_detection = app.clone();
+                    tauri::async_runtime::spawn_blocking(move || {
+                        app_for_cli_detection
+                            .state::<AppState>()
+                            .agent_external_config
+                            .run_startup_detect();
+                    });
+                    crate::maintenance::spawn_startup_maintenance(
+                        app.package_info().version.to_string(),
+                        user_config_dir,
+                        thread_manager,
+                    );
+                    // Cloud readiness/credentials are independent of local startup.
+                    let cloud_app = app.clone();
+                    let session_manager = cloud_sync.clone();
+                    tauri::async_runtime::spawn(async move {
+                        let mut delay = Duration::from_secs(2);
+                        loop {
+                            let manager = session_manager.clone();
+                            let initialized = tauri::async_runtime::spawn_blocking(move || {
+                                manager.initialize_storage()
+                            }).await;
+                            match initialized {
+                                Ok(Ok(())) => break,
+                                Ok(Err(error)) => tracing::warn!(%error, retry_in_ms = delay.as_millis(),
+                                    "background cloud storage unavailable; retry scheduled"),
+                                Err(error) => tracing::warn!(%error, retry_in_ms = delay.as_millis(),
+                                    "background cloud storage worker failed; retry scheduled"),
+                            }
+                            tokio::time::sleep(delay).await;
+                            delay = (delay * 2).min(Duration::from_secs(60));
                         }
+                        if let Ok(state) = session_manager.state() { let _ = cloud_app.emit("cloud-state-changed", state); }
+                        commands::cloud::start_cloud_sync_polling(cloud_app);
+                        tauri::async_runtime::spawn(async move { session_manager.run_session_service().await; });
+                    });
+                    if let Err(error) = user_config_for_watcher.clear_legacy_watcher_exclusions() {
+                        tracing::warn!(%error, "background watcher defaults could not be persisted");
                     }
-                }
-                for notebook in &initial_notebooks {
-                    if current_notebook_id.as_deref() != Some(notebook.id.as_str()) {
-                        let _ = reconcile_startup_notebook(&app, notebook, &memo_file);
+                    start_post_startup_services(app.clone(), external_runtimes);
+                    let background = app.state::<AppState>().notebook_background.clone();
+                    // This identity only sets queue priority. Release the global
+                    // MemoFile lock before taking the watcher binding lock.
+                    let current_notebook_id = crate::lock_utils::read_lock(&memo_file, "memo_file")
+                        .current_notebook_id_value();
+                    // Serialize a fresh independent registry snapshot + binding
+                    // with other rebinds, without nesting the global MemoFile lock.
+                    let initial_notebooks = {
+                        let mut watcher = memo_watcher.write().unwrap_or_else(|p| p.into_inner());
+                        let configs = crate::watcher::runtime::read_registered_notebooks(
+                            user_config_for_watcher.config_dir(),
+                        );
+                        watcher.set_whitelist(user_config_for_watcher.get_preference().watcher);
+                        match configs {
+                            Ok(configs) => {
+                                watcher.rebind_all(app.clone(), configs.clone());
+                                configs
+                            }
+                            Err(error) => {
+                                tracing::warn!(%error, "startup watcher snapshot unavailable; retry deferred");
+                                Vec::new()
+                            }
+                        }
+                    };
+                    if let Some(notebook) = initial_notebooks.iter().find(|n| Some(n.id.as_str()) == current_notebook_id.as_deref()) {
+                        background.prioritize(&notebook.id);
                     }
-                    let media_started = Instant::now();
-                    if let Err(error) = crate::lock_utils::read_lock(&memo_file, "memo_file")
-                        .reconcile_media_resources(&notebook.id)
-                    {
-                        tracing::warn!(notebook = %notebook.id, "[startup] media maintenance failed: {error}");
+                    background.start(app.clone(), user_config_for_watcher.config_dir().clone());
+                    for notebook in &initial_notebooks {
+                        if current_notebook_id.as_deref() != Some(notebook.id.as_str()) {
+                            background.request(&notebook.id, false, false);
+                        }
                     }
-                    tracing::info!(notebook = %notebook.id, elapsed_ms = media_started.elapsed().as_millis(), "[startup] media maintenance checked");
-                    record_slow_notebook_stage(
-                        &notebook.id,
-                        "media-reconcile",
-                        media_started.elapsed(),
+                    spawn_notebook_watch_retry(
+                        app.clone(),
+                        memo_watcher.clone(),
+                        user_config_for_watcher.config_dir().clone(),
+                        background.clone(),
+                        watcher_retry_stop.clone(),
+                    );
+                    tracing::info!(
+                        elapsed_ms = started.elapsed().as_millis(),
+                        "[startup] background services admitted"
                     );
-                    std::thread::yield_now();
+                    record_startup_stage(&startup, "background-services-admitted");
+                    return;
                 }
-                tracing::info!(
-                    elapsed_ms = started.elapsed().as_millis(),
-                    "[startup] background maintenance completed"
-                );
-                record_startup_stage(&startup, "background-complete");
+                Ok(Err(error)) => {
+                    tracing::error!("[startup] foreground preparation failed: {error}");
+                    crate::runtime_log::record_event("error", "startup.failed", serde_json::json!({
+                    "step": startup.status().step, "error": error,
+                    "elapsedMs": startup.elapsed_ms(), "attemptElapsedMs": started.elapsed().as_millis()
+                }).to_string());
+                    startup.mark_failed(error);
+                }
+                Err(_) => {
+                    tracing::error!("[startup] foreground preparation panicked");
+                    crate::runtime_log::record_event(
+                        "error",
+                        "startup.failed",
+                        "startup migration panicked",
+                    );
+                    startup.mark_failed("startup migration panicked");
+                }
+            }
+            startup.wait_for_retry();
+        }
+    });
+}
+
+/// Retry external/not-yet-mounted notebook roots independently of index work.
+/// A newly attached root gets one reconciliation pass to cover changes made
+/// while its volume was offline. The process exit signal stops this loop.
+fn spawn_notebook_watch_retry(
+    app: tauri::AppHandle,
+    memo_watcher: Arc<RwLock<MemoWatcher>>,
+    config_dir: PathBuf,
+    background: Arc<crate::app::notebook_background::NotebookBackground>,
+    stop: Arc<AtomicBool>,
+) {
+    tauri::async_runtime::spawn_blocking(move || {
+        loop {
+            for _ in 0..15 {
+                if stop.load(Ordering::Acquire) {
+                    return;
+                }
+                std::thread::sleep(Duration::from_secs(1));
             }
-            Ok(Err(error)) => {
-                tracing::error!("[startup] migration gate failed: {error}");
-                startup.mark_failed(error);
+            if stop.load(Ordering::Acquire) {
+                return;
             }
-            Err(_) => {
-                tracing::error!("[startup] migration gate panicked");
-                startup.mark_failed("startup migration panicked");
+            let Ok(mut watcher) = memo_watcher.write() else {
+                tracing::warn!("notebook watcher lock unavailable during root retry");
+                continue;
+            };
+            let configs = match crate::watcher::runtime::read_registered_notebooks(&config_dir)
+            {
+                Ok(configs) => configs,
+                Err(error) => {
+                    tracing::warn!(%error, "could not reload notebook roots for watcher retry");
+                    continue;
+                }
+            };
+            if !watcher.is_initialized() {
+                watcher.rebind_all(app.clone(), configs.clone());
+                // Binding alone cannot cover changes made while detached. Only
+                // reconcile roots that actually attached; offline roots retain
+                // their normal retry path and suspended roots stay untouched.
+                crate::watcher::runtime::reconcile_bound_roots(&watcher, &configs, &background);
+                continue;
+            }
+            for config in &configs {
+                if watcher.is_watching(&config.id)
+                    || watcher.is_notebook_suspended(&config.id)
+                    || !Path::new(&config.path).is_dir()
+                {
+                    continue;
+                }
+                if watcher.add_notebook_root(config) {
+                    tracing::info!(notebook_id = %config.id, root = %config.path,
+                        "attached notebook watcher after root became available");
+                    background.request(&config.id, false, true);
+                } else {
+                    tracing::debug!(notebook_id = %config.id, root = %config.path,
+                        "notebook watcher root retry is still unavailable");
+                }
             }
         }
     });
 }
 
-fn run_startup_reconciliation(
-    app: &tauri::AppHandle,
-    initial_notebooks: &[flowix_core::memo_file::NotebookConfig],
+fn prepare_startup_storage(
+    device_registry: &crate::device_registration::DeviceRegistry,
     memo_file: &Arc<RwLock<flowix_core::memo_file::MemoFile>>,
-    memo_watcher: &Arc<RwLock<MemoWatcher>>,
-    user_config_for_watcher: &Arc<user_config::UserConfigStore>,
+    thread_manager: &ThreadManager,
+    cloud_sync: &flowix_sync::SyncManager,
+    user_config: &crate::config::UserConfigStore,
+    user_config_dir: &Path,
     startup: &crate::app::startup::StartupCoordinator,
 ) -> Result<(), String> {
-    // MemoFile starts without an operation context. Resolve the persisted
-    // selection before deciding which notebook is on the startup critical path.
-    let current_notebook_id = {
-        let persisted = crate::lock_utils::read_lock(memo_file, "memo_file")
-            .read_selected_notebook_id()
-            .map_err(|error| format!("read selected notebook failed: {error}"))?;
-        let selected = persisted
-            .as_deref()
-            .and_then(|id| initial_notebooks.iter().find(|notebook| notebook.id == id))
-            .filter(|notebook| Path::new(&notebook.path).is_dir())
-            .or_else(|| {
-                initial_notebooks
-                    .iter()
-                    .find(|notebook| Path::new(&notebook.path).is_dir())
-            })
-            .map(|notebook| notebook.id.clone());
-        let mut memo_file = memo_file
-            .write()
-            .unwrap_or_else(|poisoned| poisoned.into_inner());
-        memo_file.set_current_notebook(selected.clone());
-        if persisted != selected {
-            memo_file
-                .write_selected_notebook_id(selected.as_deref())
-                .map_err(|error| format!("persist selected notebook failed: {error}"))?;
-        }
-        selected
-    };
-    tracing::info!(notebook = ?current_notebook_id, "[startup] selected notebook resolved");
-    let legacy_watcher = user_config_for_watcher.get_preference().watcher;
-    for notebook in initial_notebooks {
-        let root = Path::new(&notebook.path);
-        if root.is_dir() {
-            if let Err(error) = crate::commands::file::migrate_legacy_watcher_rules(
-                root,
-                &legacy_watcher,
-                &crate::lock_utils::read_lock(&memo_file, "memo_file"),
-            ) {
-                tracing::warn!(notebook = %notebook.id, %error, "legacy watcher rule migration deferred");
-            }
-        }
+    let version_init_pending = version_initialization_pending(device_registry);
+    if version_init_pending {
+        startup.mark_running(
+            crate::app::startup::StartupStage::Initialization,
+            "versionInitialization",
+        );
+        startup.set_progress(0, 0, 4, "prepareDatabasePaths");
+    } else {
+        // Also reset retry state here: even a failed rebuild stays in stage 2.
+        startup.mark_running(
+            crate::app::startup::StartupStage::WorkspacePreparation,
+            "preparingData",
+        );
+    }
+    if version_init_pending {
+        crate::storage_initialization::prepare_database_paths(user_config_dir)
+            .map_err(|error| format!("prepare database paths failed: {error}"))?;
+    } else {
+        flowix_core::memo_file::ensure_storage_directory(&user_config_dir.join("db"))
+            .map_err(|error| format!("prepare current database directory failed: {error}"))?;
+    }
+    if version_init_pending {
+        startup.set_progress(8, 1, 4, "prepareThreadDatabase");
+    }
+    thread_manager
+        .initialize_storage()
+        .map_err(|error| format!("initialize thread database failed: {error}"))?;
+    if version_init_pending {
+        startup.set_progress(16, 2, 4, "prepareSyncDatabase");
+    }
+    if version_init_pending {
+        cloud_sync.initialize_storage()
+            .map_err(|error| format!("initialize sync database failed: {error}"))?;
+    }
+    if version_init_pending {
+        startup.set_progress(24, 3, 4, "prepareNotebookRegistry");
     }
-    runtime_log::record_event(
-        "info",
-        "startup.selection",
-        serde_json::json!({ "notebookId": current_notebook_id.as_deref() }).to_string(),
-    );
-    record_startup_stage(startup, "selected-notebook-resolved");
-    startup.mark_running("dataMigrations");
-    let migration_started = Instant::now();
     {
-        let memo_file = crate::lock_utils::read_lock(memo_file, "memo_file");
-        let report = memo_file
-            .run_pending_data_migrations()
-            .map_err(|error| format!("startup data migration failed: {error}"))?;
-        if report.applied > 0 {
-            tracing::info!(
-                from_version = report.from_version,
-                to_version = report.to_version,
-                applied = report.applied,
-                "startup data migrations completed"
-            );
-        }
+        let memo = crate::lock_utils::read_lock(memo_file, "memo_file");
+        let result = if version_init_pending { memo.initialize_registry_storage() }
+            else { memo.initialize_current_registry_storage() };
+        result.map_err(|error| format!("initialize notebook registry failed: {error}"))?;
     }
-    tracing::info!(
-        elapsed_ms = migration_started.elapsed().as_millis(),
-        "[startup] data migrations checked"
-    );
-    record_startup_stage(startup, "data-migrations-checked");
-
-    startup.mark_running("migratingCurrentNotebook");
-    if let Some(notebook_id) = current_notebook_id.as_deref() {
-        {
-            let memo_file = crate::lock_utils::read_lock(memo_file, "memo_file");
-            let migration_started = Instant::now();
-            let report = memo_file
-                .ensure_notebook_migrations(notebook_id)
-                .map_err(|error| format!("current notebook migration failed: {error}"))?;
-            tracing::info!(notebook = %notebook_id, elapsed_ms = migration_started.elapsed().as_millis(), "[startup] current notebook migration completed");
-            if report.moved_files > 0 || report.rebuilt_tags > 0 {
-                tracing::info!(
-                    notebook = %notebook_id,
-                    moved_files = report.moved_files,
-                    rebuilt_tags = report.rebuilt_tags,
-                    "current notebook migrations completed"
-                );
-            }
-        }
+    if version_init_pending {
+        startup.set_progress(30, 4, 4, "prepareNotebookRegistry");
+    }
+    user_config.prepare_runtime_watcher_exclusions();
+    if !version_init_pending {
+        // Stage 2 only opens/rebuilds current runtime stores. Do not inspect or
+        // replay legacy jobs, even if their completion records were lost or a
+        // notebook was unavailable during the first initialization.
+        user_config.ensure_runtime_storage()?;
+        user_config.prepare_initialized_runtime();
+        tracing::info!("[startup] version initialization already completed for this app version");
+        record_startup_stage(startup, "version-initialization-skipped");
+        return Ok(());
     }
 
-    record_startup_stage(startup, "current-notebook-migrations-checked");
-    startup.mark_running("reconcilingCurrentNotebook");
-    if let Some(notebook) = initial_notebooks
-        .iter()
-        .find(|notebook| Some(notebook.id.as_str()) == current_notebook_id.as_deref())
+    if crate::lock_utils::read_lock(memo_file, "memo_file")
+        .local_migration_completed(crate::storage_initialization::CONFIG_LOCAL_MIGRATIONS_JOB)
+        .map_err(|error| format!("read configuration initialization progress failed: {error}"))?
     {
-        let _ = reconcile_startup_notebook(app, notebook, memo_file);
+        user_config.prepare_initialized_runtime();
     }
-    record_startup_stage(startup, "current-notebook-reconciled");
-
-    // Bind the watcher after structural migrations, before background scans.
-    // Its index updates share the memo index lock with reconciliation.
-    let watcher_started = Instant::now();
-    let current_watch_configs = initial_notebooks
-        .iter()
-        .filter(|notebook| Some(notebook.id.as_str()) == current_notebook_id.as_deref())
-        .cloned()
-        .collect();
-    memo_watcher
-        .write()
-        .unwrap_or_else(|poisoned| poisoned.into_inner())
-        .rebind_all(app.clone(), current_watch_configs);
-    let watcher_cfg = user_config_for_watcher.get_preference().watcher.clone();
-    memo_watcher
-        .write()
-        .unwrap_or_else(|poisoned| poisoned.into_inner())
-        .set_whitelist(watcher_cfg);
     tracing::info!(
-        elapsed_ms = watcher_started.elapsed().as_millis(),
-        "[startup] watcher bound"
+        previous_app_version = ?device_registry.last_successful_app_version(),
+        "[startup] starting version initialization"
     );
-    record_startup_stage(startup, "current-notebook-watcher-bound");
+    record_startup_stage(startup, "version-initialization-start");
+    device_registry.begin_version_initialization()?;
+
+    crate::storage_initialization::initialize_legacy_storage_with_progress(
+        device_registry,
+        &crate::lock_utils::read_lock(memo_file, "memo_file"),
+        user_config,
+        user_config_dir,
+        &get_app_data_path(),
+        |completed, total, task| {
+            let percent = 30 + (55 * completed / total.max(1)) as u8;
+            startup.set_progress(percent, completed, total, task);
+        },
+    )?;
 
+    startup.set_progress(88, 0, 2, "prepareRuntimeStorage");
+    user_config.ensure_runtime_storage()?;
+    startup.set_progress(95, 1, 2, "activateRuntime");
+    user_config.prepare_initialized_runtime();
+
+    crate::storage_initialization::retire_global_index_databases(user_config_dir);
+    device_registry.complete_version_initialization()?;
+    startup.set_progress(100, 2, 2, "completeInitialization");
+
+    record_startup_stage(startup, "version-initialization-complete");
     Ok(())
 }
 
-fn reconcile_startup_notebook(
-    _app: &tauri::AppHandle,
-    notebook: &flowix_core::memo_file::NotebookConfig,
+fn prepare_notebook_selection(
+    initial_notebooks: &[flowix_core::memo_file::NotebookConfig],
     memo_file: &Arc<RwLock<flowix_core::memo_file::MemoFile>>,
+    startup: &crate::app::startup::StartupCoordinator,
 ) -> Result<(), String> {
-    let started = Instant::now();
-    let memo_file = crate::lock_utils::read_lock(memo_file, "memo_file");
-    match memo_file.migrate_note_properties_for_notebook(&notebook.id) {
-        Ok(report) if report.notes_written > 0 => {
-            tracing::info!(notebook = %notebook.id, notes = report.notes_written, "[startup] note properties migrated")
-        }
-        Err(error) => {
-            tracing::warn!(notebook = %notebook.id, %error, "[startup] note property migration will retry")
-        }
-        _ => {}
-    }
-    match memo_file.migrate_note_todo_metadata_for_notebook(&notebook.id) {
-        Ok(report) if report.notes_written > 0 => {
-            tracing::info!(notebook = %notebook.id, notes = report.notes_written, "[startup] task metadata migrated")
-        }
-        Err(error) => {
-            tracing::warn!(notebook = %notebook.id, %error, "[startup] task migration will retry")
-        }
-        _ => {}
+    startup.mark_running(crate::app::startup::StartupStage::WorkspacePreparation, "preparingData");
+    // Resolve identity solely from local metadata. Probing every external disk
+    // or attached repository does not belong on the shell's critical path.
+    let persisted = crate::lock_utils::read_lock(memo_file, "memo_file")
+        .read_selected_notebook_id().map_err(|error| error.to_string())?;
+    let selected = persisted.as_deref().and_then(|id| initial_notebooks.iter().find(|n| n.id == id))
+        .or_else(|| initial_notebooks.first()).map(|n| n.id.clone());
+    let mut memo = memo_file.write().unwrap_or_else(|p| p.into_inner());
+    memo.set_current_notebook(selected.clone());
+    if persisted != selected {
+        memo.write_selected_notebook_id(selected.as_deref()).map_err(|error| error.to_string())?;
     }
-    let report = memo_file
-        .reconcile_note_index(&notebook.id)
-        .map_err(|error| {
-            format!(
-                "notebook {} path reconciliation failed: {error}",
-                notebook.id
-            )
-        })?;
-    tracing::info!(
-        notebook = %notebook.id,
-        added = report.added,
-        updated = report.updated,
-        removed = report.removed,
-        unchanged = report.unchanged,
-        elapsed_ms = started.elapsed().as_millis(),
-        "[startup] path index reconciled"
-    );
-    record_slow_notebook_stage(&notebook.id, "markdown-reconcile", started.elapsed());
+    record_startup_stage(startup, "selected-notebook-resolved");
     Ok(())
 }
+
 fn start_post_startup_services(
     app: tauri::AppHandle,
     external_runtimes: Arc<ExternalRuntimeRegistry>,
 ) {
-    commands::cloud::start_cloud_sync_polling(app.clone());
     spawn_external_agent_watchdog(app, external_runtimes);
 }
 
 fn handle_second_instance(app: &tauri::AppHandle, args: Vec<String>) {
     // 二�?�?��: 区分 markdown 文件�?���?flowix:// 深链�?    // 两个通道�?��同时触发 (用户�?`xdg-open foo.md flowix://memo/abc123` �?��)�?
     let app = app.clone();
+    // Launch Services starts a short-lived second process for a protocol URL.
+    // Bring the already-running window forward before waiting for app startup
+    // or parsing the URL, so even a malformed/stale callback cannot leave the
+    // browser's transient launch as the only visible activation.
+    focus_main_window(&app);
     tauri::async_runtime::spawn_blocking(move || {
         if let Err(error) = app.state::<AppState>().startup.wait_until_ready() {
             tracing::warn!("second-instance target deferred because startup failed: {error}");
@@ -1082,16 +1200,49 @@ fn handle_second_instance(app: &tauri::AppHandle, args: Vec<String>) {
     });
 }
 
+#[cfg(desktop)]
+fn focus_main_window(app: &tauri::AppHandle) {
+    #[cfg(target_os = "macos")]
+    {
+        // A protocol launch briefly activates its own helper process. Focusing
+        // the existing NSWindow alone does not reactivate the already-running
+        // app on macOS, so explicitly activate NSApp on the main thread first.
+        let app = app.clone();
+        let app_for_main_thread = app.clone();
+        let _ = app.run_on_main_thread(move || {
+            if let Some(mtm) = objc2::MainThreadMarker::new() {
+                objc2_app_kit::NSApp(mtm).activate();
+            }
+            if let Some(window) = app_for_main_thread.get_webview_window("main") {
+                let _ = window.show();
+                let _ = window.unminimize();
+                let _ = window.set_focus();
+            }
+        });
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    if let Some(window) = app.get_webview_window("main") {
+        let _ = window.show();
+        let _ = window.unminimize();
+        let _ = window.set_focus();
+    }
+}
+
 #[cfg(desktop)]
 fn dispatch_google_callback(app: &tauri::AppHandle, raw: &str) -> bool {
-    let Ok(url) = url::Url::parse(raw) else { return false; };
+    let Ok(url) = url::Url::parse(raw) else {
+        return false;
+    };
     let expected_scheme = if option_env!("FLOWIX_DEV_MODE") == Some("1") {
         "flowix-dev"
     } else {
         "flowix"
     };
-    if url.scheme() != expected_scheme || url.host_str() != Some("auth") ||
-        url.path() != "/google/callback" {
+    if url.scheme() != expected_scheme
+        || url.host_str() != Some("auth")
+        || url.path() != "/google/callback"
+    {
         return false;
     }
     let mut code = None;
@@ -1106,14 +1257,20 @@ fn dispatch_google_callback(app: &tauri::AppHandle, raw: &str) -> bool {
         }
     }
     let callback = match (auth_error, code, oauth_state) {
-        (Some(error), _, Some(state)) => Some(commands::cloud::GoogleCallback::Failure { error, state }),
-        (None, Some(code), Some(state)) => Some(commands::cloud::GoogleCallback::Success { code, state }),
+        (Some(error), _, Some(state)) => {
+            Some(commands::cloud::GoogleCallback::Failure { error, state })
+        }
+        (None, Some(code), Some(state)) => {
+            Some(commands::cloud::GoogleCallback::Success { code, state })
+        }
         _ => None,
     };
     if let Some(callback) = callback {
         let app = app.clone();
         tauri::async_runtime::spawn(async move {
-            if let Err(error) = commands::cloud::complete_google_deep_link(app.clone(), callback).await {
+            if let Err(error) =
+                commands::cloud::complete_google_deep_link(app.clone(), callback).await
+            {
                 let _ = app.emit("cloud-google-auth-error", error);
             }
         });
@@ -1125,7 +1282,11 @@ fn dispatch_google_callback(app: &tauri::AppHandle, raw: &str) -> bool {
 fn register_deep_links(app: &mut tauri::App) {
     use tauri_plugin_deep_link::DeepLinkExt;
 
-    let callback_scheme = if option_env!("FLOWIX_DEV_MODE") == Some("1") { "flowix-dev" } else { "flowix" };
+    let callback_scheme = if option_env!("FLOWIX_DEV_MODE") == Some("1") {
+        "flowix-dev"
+    } else {
+        "flowix"
+    };
     // Bundled app metadata owns registration on macOS; runtime registration
     // remains useful on platforms where the deep-link plugin supports it.
     let _ = app.deep_link().register(callback_scheme);
@@ -1140,6 +1301,7 @@ fn register_deep_links(app: &mut tauri::App) {
             .map(|url| url.to_string())
             .collect::<Vec<_>>();
         let app = app_handle.clone();
+        focus_main_window(&app);
         let startup = startup.clone();
         tauri::async_runtime::spawn_blocking(move || {
             if let Err(error) = startup.wait_until_ready() {
@@ -1175,6 +1337,7 @@ fn handle_cold_start_open_targets(app: &tauri::AppHandle) {
 }
 
 fn emit_open_target_batch_if_needed(app: &tauri::AppHandle, paths: &[String]) {
+    if commands::window_shutdown::is_exiting() { return; }
     let mut external_paths = Vec::new();
     let state = app.state::<AppState>();
     let configs = crate::lock_utils::read_lock(&state.memo_file, "memo_file")
@@ -1216,6 +1379,7 @@ fn emit_open_target_batch_if_needed(app: &tauri::AppHandle, paths: &[String]) {
 }
 
 fn emit_open_target_if_resolved(app: &tauri::AppHandle, raw: &str) {
+    if commands::window_shutdown::is_exiting() { return; }
     let state = app.state::<AppState>();
     let markdown_paths = commands::markdown_paths_from_args([raw.to_string()]);
     for path in &markdown_paths {
@@ -1261,7 +1425,6 @@ fn handle_run_event(app: &tauri::AppHandle, event: tauri::RunEvent) {
             event: tauri::WindowEvent::Destroyed,
             ..
         } => {
-            commands::document_shutdown::forget_window(app, &label);
             commands::document_operations::forget_window(&label);
             app.state::<AppState>().export_access.revoke(&label);
             app.state::<AppState>().document_access.revoke(&label);
@@ -1269,6 +1432,7 @@ fn handle_run_event(app: &tauri::AppHandle, event: tauri::RunEvent) {
         }
         #[cfg(target_os = "macos")]
         tauri::RunEvent::Opened { urls } => {
+            if commands::window_shutdown::is_exiting() { return; }
             let app = app.clone();
             tauri::async_runtime::spawn_blocking(move || {
                 if let Err(error) = app.state::<AppState>().startup.wait_until_ready() {
@@ -1290,16 +1454,28 @@ fn handle_run_event(app: &tauri::AppHandle, event: tauri::RunEvent) {
             });
         }
         tauri::RunEvent::ExitRequested { api, code, .. } => {
-            if !commands::document_shutdown::request_exit(app, code.unwrap_or(0)) {
+            if !commands::window_shutdown::request_exit(app, code.unwrap_or(0)) {
                 api.prevent_exit();
                 return;
             }
-            stop_external_agent_children(app, "exit");
-            checkpoint_thread_database(app, "exit");
-        }
-        tauri::RunEvent::Exit => {
-            stop_external_agent_children(app, "final exit");
-            checkpoint_thread_database(app, "final exit");
+            static CLEANUP_STARTED: AtomicBool = AtomicBool::new(false);
+            static CLEANUP_DONE: AtomicBool = AtomicBool::new(false);
+            if !CLEANUP_DONE.load(Ordering::Acquire) {
+                api.prevent_exit();
+                if !CLEANUP_STARTED.swap(true, Ordering::AcqRel) {
+                    let app = app.clone();
+                    std::thread::spawn(move || {
+                        // Run once off the UI thread. A blocked lock, panic or
+                        // checkpoint cannot outlive the independent watchdog.
+                        app.state::<AppState>().notebook_background.stop();
+                        app.state::<AppState>().watcher_retry_stop.store(true, Ordering::Release);
+                        stop_external_agent_children(&app, "exit");
+                        checkpoint_thread_database(&app, "exit");
+                        CLEANUP_DONE.store(true, Ordering::Release);
+                        app.exit(code.unwrap_or(0));
+                    });
+                }
+            }
         }
         _ => {}
     }
@@ -1317,19 +1493,25 @@ fn checkpoint_thread_database(app: &tauri::AppHandle, phase: &str) {
 pub(crate) fn prepare_for_update(app: &tauri::AppHandle) -> UpdateRuntimeGuard {
     // Construct before cleanup so unwinding also restores admission. This guard
     // stays on the same worker through cleanup and installer launch.
-    let guard = UpdateRuntimeGuard(app.state::<AppState>().pi.clone());
+    let state = app.state::<AppState>();
+    state.notebook_background.pause();
+    let guard = UpdateRuntimeGuard { pi: state.pi.clone(), background: state.notebook_background.clone() };
     stop_external_agent_children(app, "update");
     checkpoint_thread_database(app, "update");
     guard
 }
 
 #[cfg(windows)]
-pub(crate) struct UpdateRuntimeGuard(Arc<PiRpcManager>);
+pub(crate) struct UpdateRuntimeGuard {
+    pi: Arc<PiRpcManager>,
+    background: Arc<crate::app::notebook_background::NotebookBackground>,
+}
 
 #[cfg(windows)]
 impl Drop for UpdateRuntimeGuard {
     fn drop(&mut self) {
-        self.0.resume_after_failed_update();
+        self.pi.resume_after_failed_update();
+        self.background.resume();
     }
 }
 
@@ -1357,7 +1539,7 @@ fn stop_external_agent_children(app: &tauri::AppHandle, phase: &str) {
                 if total > 0 {
                     let summary = stopped
                         .iter()
-                        .map(|result| format!("{}={}", result.runtime.key(), result.affected))
+                        .map(|result| format!("{}={}", result.runtime.id(), result.affected))
                         .collect::<Vec<_>>()
                         .join(", ");
                     tracing::info!("stopped external agent children on {phase}: {summary}");
@@ -1371,3 +1553,264 @@ fn stop_external_agent_children(app: &tauri::AppHandle, phase: &str) {
         }
     });
 }
+
+#[cfg(test)]
+mod missing_dependency_tests {
+    use super::*;
+    use crate::app::startup::{StartupCoordinator, StartupStage};
+
+    fn prepare_storage(
+        config: &Path,
+        user: Arc<user_config::UserConfigStore>,
+        device: &crate::device_registration::DeviceRegistry,
+        memo: &Arc<RwLock<flowix_core::memo_file::MemoFile>>,
+        startup: &StartupCoordinator,
+    ) -> Result<(), String> {
+        let threads = ThreadManager::new_uninitialized(config.join("db/thread.db")).unwrap();
+        let sync = flowix_sync::SyncManager::new_with_session_dependencies_deferred(
+            flowix_sync::CloudEnvironment::Prod.api_base(),
+            config.join("db/sync.db"),
+            user.clone(),
+            Arc::new(|_| {}),
+        )
+        .unwrap();
+        prepare_startup_storage(device, memo, &threads, &sync, &user, config, startup)
+    }
+
+    #[test]
+    fn completed_version_skips_legacy_jobs_despite_old_settings_and_offline_notebooks() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().to_path_buf();
+        let config = get_user_config_dir(&home);
+        let user = user_config::UserConfigStore::new(home.clone());
+        let mut preference = user.get_preference();
+        preference.watcher.skip_dirs.push("legacy".into());
+        preference.watcher.skip_files.push("*.tmp".into());
+        user.set_preference(preference).unwrap();
+        let device = crate::device_registration::DeviceRegistry::load(&config, "test");
+        device.set_version_initialization_completed(true).unwrap();
+        // An older installation can have a completed version but no reset flag.
+        assert_eq!(device.notebook_storage_reset_version(), 0);
+        let boot_before = std::fs::read(config.join("boot/boot.json")).unwrap();
+        let memo = flowix_core::memo_file::MemoFile::new(config.clone());
+        memo.initialize_registry_storage().unwrap();
+        memo.mark_local_migration_completed("config_watcher_exclusions_v1")
+            .unwrap();
+        let root = home.join("notebook");
+        std::fs::create_dir_all(root.join(".flowix")).unwrap();
+        let preferences_path = root.join(".flowix/view-preferences.json");
+        let custom_preferences = b"{\"default_create_folder\":\"custom\"}";
+        std::fs::write(&preferences_path, custom_preferences).unwrap();
+        let notebooks: Vec<_> = [("online", root), ("offline", home.join("unavailable"))]
+            .into_iter()
+            .map(|(id, path)| flowix_core::memo_file::NotebookConfig {
+                id: id.into(),
+                name: id.into(),
+                icon: None,
+                path: path.to_string_lossy().into_owned(),
+                is_default: false,
+                sort: 0,
+                created_at: 0,
+                updated_at: 0,
+            })
+            .collect();
+        memo.write_notebook_configs(&notebooks).unwrap();
+        assert!(memo.has_pending_notebook_storage_initialization().unwrap());
+        drop(memo);
+
+        // Reload all state as two independent launches would do.
+        for _ in 0..2 {
+            let user = Arc::new(user_config::UserConfigStore::new(home.clone()));
+            let device = crate::device_registration::DeviceRegistry::load(&config, "test");
+            let memo = Arc::new(RwLock::new(flowix_core::memo_file::MemoFile::new(
+                config.clone(),
+            )));
+            let startup = StartupCoordinator::new();
+            prepare_storage(&config, user.clone(), &device, &memo, &startup).unwrap();
+            assert_eq!(startup.status().stage, StartupStage::WorkspacePreparation);
+            assert!(startup.status().progress.is_none());
+            assert!(!user.has_legacy_watcher_exclusions());
+            assert!(device.is_version_initialization_complete());
+            assert_eq!(
+                std::fs::read(config.join("boot/boot.json")).unwrap(),
+                boot_before
+            );
+            // Stage 2 must not replay resets or fabricate legacy job completion.
+            assert!(memo
+                .read()
+                .unwrap()
+                .has_pending_notebook_storage_initialization()
+                .unwrap());
+            assert_eq!(
+                std::fs::read(&preferences_path).unwrap(),
+                custom_preferences
+            );
+        }
+    }
+
+    #[test]
+    fn stage_two_uses_watcher_defaults_without_persisting_configuration() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().to_path_buf();
+        let config = get_user_config_dir(&home);
+        let user = Arc::new(user_config::UserConfigStore::new(home));
+        let mut preference = user.get_preference();
+        preference.watcher.skip_files.push("*.tmp".into());
+        user.set_preference(preference).unwrap();
+        // A directory at the file path gives a deterministic I/O failure on
+        // Windows, macOS and Linux, without relying on Unix permission bits.
+        let path = config.join("boot/preference.json");
+        std::fs::remove_file(&path).unwrap();
+        std::fs::create_dir(&path).unwrap();
+        let device = crate::device_registration::DeviceRegistry::load(&config, "test");
+        device.set_version_initialization_completed(true).unwrap();
+        let memo = Arc::new(RwLock::new(flowix_core::memo_file::MemoFile::new(
+            config.clone(),
+        )));
+        let startup = StartupCoordinator::new();
+        for _ in 0..2 {
+            prepare_storage(&config, user.clone(), &device, &memo, &startup).unwrap();
+            assert_eq!(startup.status().stage, StartupStage::WorkspacePreparation);
+            assert!(startup.status().progress.is_none());
+            assert!(!user.has_legacy_watcher_exclusions());
+            assert!(path.is_dir());
+            assert!(
+                crate::device_registration::DeviceRegistry::load(&config, "test")
+                    .is_version_initialization_complete()
+            );
+        }
+    }
+
+    #[test]
+    fn new_version_initializes_once_then_prepares_workspace() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().to_path_buf();
+        let config = get_user_config_dir(&home);
+        let user = Arc::new(user_config::UserConfigStore::new(home));
+        let old = crate::device_registration::DeviceRegistry::load(&config, "old");
+        old.set_version_initialization_completed(true).unwrap();
+        let current = crate::device_registration::DeviceRegistry::load(&config, "current");
+        let memo = Arc::new(RwLock::new(flowix_core::memo_file::MemoFile::new(
+            config.clone(),
+        )));
+        std::fs::write(config.join("index.db"), b"retired root database").unwrap();
+        std::fs::create_dir_all(config.join("db")).unwrap();
+        std::fs::write(config.join("db/index.db"), b"retired canonical database").unwrap();
+        let startup = StartupCoordinator::new();
+        prepare_storage(&config, user.clone(), &current, &memo, &startup).unwrap();
+        assert!(!config.join("index.db").exists());
+        assert!(!config.join("db/index.db").exists());
+        assert!(config.join("rebuild-backups").is_dir());
+        assert!(config.join("db/rebuild-backups").is_dir());
+        assert_eq!(startup.status().stage, StartupStage::Initialization);
+        assert_eq!(startup.status().progress.unwrap().percent, 100);
+        let reloaded = crate::device_registration::DeviceRegistry::load(&config, "current");
+        assert!(reloaded.is_version_initialization_complete());
+        let startup = StartupCoordinator::new();
+        prepare_storage(&config, user, &reloaded, &memo, &startup).unwrap();
+        assert_eq!(startup.status().stage, StartupStage::WorkspacePreparation);
+        assert!(startup.status().progress.is_none());
+    }
+
+    #[test]
+    fn storage_rebuild_starts_with_three_invalid_databases() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().to_path_buf();
+        let config = get_user_config_dir(&home);
+        let user = Arc::new(user_config::UserConfigStore::new(home));
+        let device = crate::device_registration::DeviceRegistry::load(&config, "test");
+        device.set_version_initialization_completed(true).unwrap();
+        device.complete_notebook_storage_reset_version(1).unwrap();
+        std::fs::create_dir_all(config.join("db")).unwrap();
+        for name in ["local.db", "thread.db", "sync.db"] {
+            std::fs::write(config.join("db").join(name), b"invalid database").unwrap();
+        }
+        let threads = ThreadManager::new_uninitialized(config.join("db/thread.db")).unwrap();
+        let sync = flowix_sync::SyncManager::new_with_session_dependencies_deferred(
+            flowix_sync::CloudEnvironment::Prod.api_base(),
+            config.join("db/sync.db"),
+            user.clone(),
+            Arc::new(|_| {}),
+        )
+        .unwrap();
+        let memo = Arc::new(RwLock::new(flowix_core::memo_file::MemoFile::new(
+            config.clone(),
+        )));
+        let startup = StartupCoordinator::new();
+        prepare_startup_storage(&device, &memo, &threads, &sync, &user, &config, &startup)
+            .unwrap();
+        assert_eq!(startup.status().stage, StartupStage::WorkspacePreparation);
+        assert!(startup.status().progress.is_none());
+        assert!(memo
+            .read()
+            .unwrap()
+            .read_notebook_configs()
+            .unwrap()
+            .is_empty());
+        assert!(!user
+            .get_property_presets()
+            .unwrap()
+            .system_fields
+            .is_empty());
+        assert_eq!(
+            std::fs::read_dir(config.join("db/rebuild-backups"))
+                .unwrap()
+                .count(),
+            2
+        );
+        // Cloud storage is independently prepared after the shell, not in stage 2.
+        assert_eq!(std::fs::read(config.join("db/sync.db")).unwrap(), b"invalid database");
+        sync.initialize_storage().unwrap();
+        assert_eq!(std::fs::read_dir(config.join("db/rebuild-backups")).unwrap().count(), 3);
+    }
+
+    #[test]
+    fn missing_runtime_dependencies_start_with_completed_boot_marker() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().to_path_buf();
+        let config_dir = get_user_config_dir(&home);
+        let user_config = Arc::new(user_config::UserConfigStore::new(home));
+        let device = crate::device_registration::DeviceRegistry::load(&config_dir, "test");
+        device.set_version_initialization_completed(true).unwrap();
+        device.complete_notebook_storage_reset_version(1).unwrap();
+        let memo = Arc::new(RwLock::new(flowix_core::memo_file::MemoFile::new(
+            config_dir.clone(),
+        )));
+        memo.read().unwrap().initialize_registry_storage().unwrap();
+        user_config.ensure_runtime_storage().unwrap();
+        std::fs::remove_dir_all(config_dir.join("db")).unwrap();
+        let threads = ThreadManager::new_in_memory().unwrap();
+        let sync = flowix_sync::SyncManager::new_with_session_dependencies_deferred(
+            flowix_sync::CloudEnvironment::Prod.api_base(),
+            temp.path().join("sync.db"),
+            user_config.clone(),
+            Arc::new(|_| {}),
+        )
+        .unwrap();
+        let startup = crate::app::startup::StartupCoordinator::new();
+        prepare_startup_storage(
+            &device,
+            &memo,
+            &threads,
+            &sync,
+            &user_config,
+            &config_dir,
+            &startup,
+        )
+        .unwrap();
+        assert!(device.is_version_initialization_complete());
+        assert_eq!(startup.status().stage, StartupStage::WorkspacePreparation);
+        assert!(startup.status().progress.is_none());
+        assert!(memo
+            .read()
+            .unwrap()
+            .read_notebook_configs()
+            .unwrap()
+            .is_empty());
+        assert!(!user_config
+            .get_property_presets()
+            .unwrap()
+            .system_fields
+            .is_empty());
+    }
+}
diff --git a/app/flowix-desktop/src/app/document_access.rs b/app/flowix-desktop/src/app/document_access.rs
index 981b96e6e..5808fc3d9 100644
--- a/app/flowix-desktop/src/app/document_access.rs
+++ b/app/flowix-desktop/src/app/document_access.rs
@@ -5,6 +5,7 @@ use std::sync::RwLock;
 #[derive(Default)]
 pub struct DocumentAccess {
     paths: RwLock<HashSet<(String, PathBuf)>>,
+    directories: RwLock<HashSet<(String, PathBuf)>>,
     generations: RwLock<HashMap<String, u64>>,
 }
 
@@ -37,16 +38,43 @@ impl DocumentAccess {
         true
     }
 
+    pub fn grant_directory_for_generation(
+        &self,
+        window: &str,
+        generation: u64,
+        path: &Path,
+    ) -> bool {
+        let Ok(generations) = self.generations.read() else {
+            return false;
+        };
+        if *generations.get(window).unwrap_or(&0) != generation {
+            return false;
+        }
+        let Some(path) = existing_directory(path) else {
+            return false;
+        };
+        let Ok(mut directories) = self.directories.write() else {
+            return false;
+        };
+        directories.insert((window.to_string(), path));
+        true
+    }
+
     pub fn contains(&self, window: &str, path: &Path) -> bool {
         if self.generations.read().is_err() {
             return false;
         }
-        let Some(path) = existing_file(path) else {
+        let Some(path) = existing_path(path) else {
             return false;
         };
-        self.paths
+        let file_granted = path.is_file() && self.paths
             .read()
-            .is_ok_and(|paths| paths.contains(&(window.to_string(), path)))
+            .is_ok_and(|paths| paths.contains(&(window.to_string(), path.clone())));
+        file_granted || self.directories.read().is_ok_and(|directories| {
+            directories.iter().any(|(owner, directory)| {
+                owner == window && path.starts_with(directory)
+            })
+        })
     }
 
     pub fn revoke(&self, window: &str) {
@@ -58,6 +86,9 @@ impl DocumentAccess {
         if let Ok(mut paths) = self.paths.write() {
             paths.retain(|(owner, _)| owner != window);
         }
+        if let Ok(mut directories) = self.directories.write() {
+            directories.retain(|(owner, _)| owner != window);
+        }
     }
 }
 
@@ -69,6 +100,21 @@ fn existing_file(path: &Path) -> Option<PathBuf> {
     canonical.is_file().then_some(canonical)
 }
 
+fn existing_directory(path: &Path) -> Option<PathBuf> {
+    if !path.is_absolute() {
+        return None;
+    }
+    let canonical = dunce::canonicalize(path).ok()?;
+    canonical.is_dir().then_some(canonical)
+}
+
+fn existing_path(path: &Path) -> Option<PathBuf> {
+    if !path.is_absolute() {
+        return None;
+    }
+    dunce::canonicalize(path).ok()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/app/flowix-desktop/src/app/mod.rs b/app/flowix-desktop/src/app/mod.rs
index 23ce6c237..a04eb05de 100644
--- a/app/flowix-desktop/src/app/mod.rs
+++ b/app/flowix-desktop/src/app/mod.rs
@@ -2,6 +2,7 @@ pub mod bootstrap;
 pub mod document_access;
 pub mod export_access;
 pub mod native_menu;
+pub mod notebook_background;
 pub mod panic;
 pub mod paths;
 pub mod startup;
diff --git a/app/flowix-desktop/src/app/notebook_background.rs b/app/flowix-desktop/src/app/notebook_background.rs
new file mode 100644
index 000000000..af35e3d33
--- /dev/null
+++ b/app/flowix-desktop/src/app/notebook_background.rs
@@ -0,0 +1,520 @@
+//! Process-local admission for passive notebook maintenance. Accurate CLI/cloud
+//! snapshots keep their explicit blocking APIs and share the core OS locks.
+use std::collections::{HashMap, HashSet, VecDeque};
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Condvar, Mutex};
+use std::time::{Duration, Instant};
+
+use flowix_core::memo_file::MemoFile;
+use serde::Serialize;
+use tauri::{AppHandle, Emitter};
+
+pub const EVENT: &str = "flowix:notebook-maintenance";
+pub const MEDIA_EVENT: &str = "flowix:media-maintenance";
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookBackgroundStatus {
+    pub notebook_id: String,
+    pub state: &'static str,
+    pub revision: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub memo_count: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub missing: Option<bool>,
+    pub message: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookMediaMaintenanceStatus {
+    pub notebook_id: String,
+    pub state: &'static str,
+    pub revision: u64,
+    pub message: Option<String>,
+}
+
+#[derive(Default)]
+struct Queue {
+    pending: VecDeque<String>,
+    urgent: HashSet<String>,
+    active: Option<String>,
+    active_media: bool,
+    media: VecDeque<String>,
+    media_statuses: HashMap<String, NotebookMediaMaintenanceStatus>,
+    media_revision: u64,
+    preferred: Option<String>,
+    rerun: HashSet<String>,
+    statuses: HashMap<String, NotebookBackgroundStatus>,
+    finished: HashMap<String, Instant>,
+    revision: u64,
+}
+
+impl Queue {
+    fn enqueue(&mut self, id: String, urgent: bool, invalidate: bool) {
+        if self.active.as_deref() == Some(&id) && !self.active_media {
+            if invalidate {
+                self.rerun.insert(id);
+            }
+            return;
+        }
+        if urgent {
+            self.urgent.insert(id.clone());
+        }
+        if let Some(position) = self.pending.iter().position(|queued| queued == &id) {
+            if urgent {
+                self.pending.remove(position);
+                self.pending.push_front(id);
+            }
+            return;
+        }
+        // Passive queries cannot continuously retry an inaccessible disk.
+        if !invalidate
+            && self
+                .statuses
+                .get(&id)
+                .is_some_and(|status| status.state == "failed")
+            && self
+                .finished
+                .get(&id)
+                .is_some_and(|at| at.elapsed() < Duration::from_secs(2))
+        {
+            self.urgent.remove(&id);
+            return;
+        }
+        self.revision += 1;
+        let previous = self.statuses.get(&id);
+        self.statuses.insert(
+            id.clone(),
+            NotebookBackgroundStatus {
+                notebook_id: id.clone(),
+                state: "queued",
+                revision: self.revision,
+                memo_count: previous.and_then(|s| s.memo_count),
+                missing: previous.and_then(|s| s.missing),
+                message: None,
+            },
+        );
+        if urgent {
+            self.pending.push_front(id);
+        } else {
+            self.pending.push_back(id);
+        }
+    }
+
+    fn enqueue_media(&mut self, id: String, urgent: bool) -> NotebookMediaMaintenanceStatus {
+        if self.active_media && self.active.as_deref() == Some(&id) {
+            return self.media_statuses[&id].clone();
+        }
+        if let Some(position) = self.media.iter().position(|queued| queued == &id) {
+            if urgent && position != 0 {
+                self.media.remove(position);
+                self.media.push_front(id.clone());
+            }
+            return self.media_statuses[&id].clone();
+        }
+        self.media_revision += 1;
+        let status = NotebookMediaMaintenanceStatus {
+            notebook_id: id.clone(),
+            state: "queued",
+            revision: self.media_revision,
+            message: None,
+        };
+        self.media_statuses.insert(id.clone(), status.clone());
+        if urgent {
+            self.media.push_front(id);
+        } else {
+            self.media.push_back(id);
+        }
+        status
+    }
+
+    fn update_media_status(
+        &mut self,
+        id: &str,
+        state: &'static str,
+        message: Option<String>,
+    ) -> NotebookMediaMaintenanceStatus {
+        self.media_revision += 1;
+        let status = NotebookMediaMaintenanceStatus {
+            notebook_id: id.to_owned(),
+            state,
+            revision: self.media_revision,
+            message,
+        };
+        self.media_statuses.insert(id.to_owned(), status.clone());
+        status
+    }
+}
+
+#[derive(Default)]
+pub struct NotebookBackground {
+    queue: Mutex<Queue>,
+    wake: Condvar,
+    started: AtomicBool,
+    stopped: AtomicBool,
+    paused: AtomicBool,
+}
+
+impl NotebookBackground {
+    pub fn request(&self, id: &str, urgent: bool, invalidate: bool) {
+        if id.is_empty() || self.stopped.load(Ordering::Acquire) {
+            return;
+        }
+        let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+        // stop() and admission share the queue lock, closing the check/enqueue race.
+        if self.stopped.load(Ordering::Acquire) {
+            return;
+        }
+        queue.enqueue(id.to_owned(), urgent, invalidate);
+        self.wake.notify_one();
+    }
+
+    pub fn prioritize(&self, id: &str) {
+        self.queue
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .preferred = Some(id.to_owned());
+        self.request(id, true, true);
+    }
+
+    pub fn request_media(&self, id: &str) -> Option<NotebookMediaMaintenanceStatus> {
+        if id.is_empty() || self.stopped.load(Ordering::Acquire) {
+            return None;
+        }
+        let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+        if self.stopped.load(Ordering::Acquire) {
+            return None;
+        }
+        let status = queue.enqueue_media(id.to_owned(), true);
+        self.wake.notify_one();
+        Some(status)
+    }
+
+    pub fn media_snapshot(&self, id: &str) -> Option<NotebookMediaMaintenanceStatus> {
+        self.queue
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .media_statuses
+            .get(id)
+            .cloned()
+    }
+
+    pub fn media_statuses(&self) -> Vec<NotebookMediaMaintenanceStatus> {
+        self.queue
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .media_statuses
+            .values()
+            .cloned()
+            .collect()
+    }
+
+    pub fn pause(&self) {
+        let _queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+        self.paused.store(true, Ordering::Release);
+    }
+    pub fn resume(&self) {
+        let _queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+        self.paused.store(false, Ordering::Release);
+        self.wake.notify_all();
+    }
+
+    pub fn snapshot(&self, id: &str) -> Option<NotebookBackgroundStatus> {
+        self.queue
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .statuses
+            .get(id)
+            .cloned()
+    }
+
+    pub fn statuses(&self) -> Vec<NotebookBackgroundStatus> {
+        self.queue
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .statuses
+            .values()
+            .cloned()
+            .collect()
+    }
+
+    pub fn stop(&self) {
+        self.stopped.store(true, Ordering::Release);
+        let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+        queue.pending.clear();
+        queue.media.clear();
+        queue.rerun.clear();
+        self.wake.notify_all();
+    }
+
+    // Called only after the workbench has painted. Requests made before then
+    // are coalesced in the queue, without starting filesystem work.
+    pub fn start(self: &Arc<Self>, app: AppHandle, config: PathBuf) {
+        if self.started.swap(true, Ordering::AcqRel) {
+            return;
+        }
+        let worker = self.clone();
+        tauri::async_runtime::spawn_blocking(move || worker.run(app, config));
+    }
+
+    fn run(&self, app: AppHandle, config: PathBuf) {
+        loop {
+            let (id, urgent, media, media_status) = {
+                let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+                while ((queue.pending.is_empty() && queue.media.is_empty())
+                    || self.paused.load(Ordering::Acquire))
+                    && !self.stopped.load(Ordering::Acquire)
+                {
+                    queue = self.wake.wait(queue).unwrap_or_else(|p| p.into_inner());
+                }
+                if self.stopped.load(Ordering::Acquire) {
+                    return;
+                }
+                let preferred_media = queue
+                    .preferred
+                    .as_ref()
+                    .and_then(|id| queue.media.iter().position(|queued| queued == id));
+                let media = queue.pending.is_empty()
+                    || (queue.urgent.is_empty() && preferred_media.is_some());
+                let id = if media {
+                    if let Some(position) = preferred_media {
+                        queue.media.remove(position).unwrap()
+                    } else {
+                        queue.media.pop_front().unwrap()
+                    }
+                } else {
+                    queue.pending.pop_front().unwrap()
+                };
+                let urgent = if media {
+                    queue.preferred.as_deref() == Some(id.as_str())
+                } else {
+                    queue.urgent.remove(&id)
+                };
+                queue.active = Some(id.clone());
+                queue.active_media = media;
+                if !media {
+                    if let Some(status) = queue.statuses.get_mut(&id) {
+                        status.state = "running";
+                    }
+                }
+                let media_status = media.then(|| queue.update_media_status(&id, "running", None));
+                (id, urgent, media, media_status)
+            };
+            if media {
+                if let Some(status) = media_status {
+                    let _ = app.emit(MEDIA_EVENT, status);
+                }
+            } else {
+                if let Some(status) = self.snapshot(&id) {
+                    let _ = app.emit(EVENT, status);
+                }
+            }
+            let started = Instant::now();
+            let ticks = std::cell::Cell::new(0usize);
+            let keep_running = || {
+                if self.stopped.load(Ordering::Acquire) || self.paused.load(Ordering::Acquire) {
+                    return false;
+                }
+                let tick = ticks.get() + 1;
+                ticks.set(tick);
+                if tick % 32 != 0 {
+                    return true;
+                }
+                // Yield between batches, never while holding a SQLite transaction.
+                std::thread::sleep(Duration::from_millis(2));
+                let queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+                queue.urgent.is_empty()
+                    || (urgent && queue.preferred.as_deref() == Some(id.as_str()))
+            };
+            if media {
+                let memo = MemoFile::new(config.clone());
+                let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                    memo.reconcile_media_resources_background(&id, &keep_running)
+                }))
+                .unwrap_or_else(|_| Err(std::io::Error::other("media maintenance panicked")));
+                let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+                queue.active = None;
+                queue.active_media = false;
+                if self.stopped.load(Ordering::Acquire) {
+                    return;
+                }
+                let status = match result {
+                    Ok(_) => {
+                        let status = queue.update_media_status(&id, "ready", None);
+                        drop(queue);
+                        let _ = app.emit(
+                            "file-management-changed",
+                            serde_json::json!({ "notebookId": id,
+                            "notebookPath": memo.get_notebook_config_by_id(&id).map(|n| n.path) }),
+                        );
+                        let _ = app.emit(MEDIA_EVENT, status.clone());
+                        continue;
+                    }
+                    Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {
+                        queue.enqueue_media(id.clone(), false)
+                    }
+                    Err(error) => {
+                        tracing::warn!(notebook = %id, %error, "background media maintenance unavailable");
+                        queue.update_media_status(&id, "failed", Some(error.to_string()))
+                    }
+                };
+                drop(queue);
+                let _ = app.emit(MEDIA_EVENT, status);
+                continue;
+            }
+            // Use a separate facade: a full scan must not hold AppState's global
+            // MemoFile RwLock. Core per-file and cross-process locks still apply.
+            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                if !keep_running() {
+                    return Err(std::io::Error::from(std::io::ErrorKind::Interrupted));
+                }
+                let memo = MemoFile::new(config.clone());
+                memo.prepare_background_note_projection(&id)?;
+                memo.reconcile_note_index_background(&id, &keep_running)?;
+                if !keep_running() {
+                    return Err(std::io::Error::from(std::io::ErrorKind::Interrupted));
+                }
+                let count = memo.cached_note_count(&id)?.ok_or_else(|| {
+                    std::io::Error::new(
+                        std::io::ErrorKind::WouldBlock,
+                        "index is being prepared by another process",
+                    )
+                })?;
+                Ok::<_, std::io::Error>(count)
+            }))
+            .unwrap_or_else(|_| Err(std::io::Error::other("notebook maintenance panicked")));
+            let mut queue = self.queue.lock().unwrap_or_else(|p| p.into_inner());
+            queue.active = None;
+            queue.active_media = false;
+            if self.stopped.load(Ordering::Acquire) {
+                return;
+            }
+            let yielded = result
+                .as_ref()
+                .is_err_and(|e| e.kind() == std::io::ErrorKind::Interrupted);
+            let rerun = queue.rerun.remove(&id) || yielded;
+            if let Some(status) = queue.statuses.get_mut(&id) {
+                match result {
+                    Ok(count) => {
+                        status.state = "ready";
+                        status.memo_count = Some(count);
+                        status.missing = Some(false);
+                        status.message = None;
+                    }
+                    Err(error) => {
+                        status.state = if yielded { "queued" } else { "failed" };
+                        status.message = Some(error.to_string());
+                        if error.kind() == std::io::ErrorKind::NotFound {
+                            status.missing = Some(true);
+                        }
+                    }
+                }
+            }
+            queue.finished.insert(id.clone(), Instant::now());
+            let status = queue.statuses.get(&id).cloned();
+            let media_status = if status.as_ref().is_some_and(|s| s.state == "ready") {
+                Some(queue.enqueue_media(id.clone(), false))
+            } else { None };
+            if rerun {
+                queue.enqueue(id.clone(), false, true);
+            }
+            drop(queue);
+            tracing::info!(notebook = %id, elapsed_ms = started.elapsed().as_millis(),
+                files_checked = ticks.get(), "background notebook task settled");
+            if let Some(status) = status {
+                // Versioned completion also reconciles late frontend subscribers.
+                let _ = app.emit(EVENT, status);
+            }
+            if let Some(status) = media_status {
+                let _ = app.emit(MEDIA_EVENT, status);
+            }
+        }
+    }
+}
+
+/// Schedule a missing projection without turning a read into a blocking scan.
+pub fn query_error(
+    state: &crate::app::state::AppState,
+    id: &str,
+    error: impl std::fmt::Display,
+) -> String {
+    let message = error.to_string();
+    if message.contains("Note index is not ready") {
+        state.notebook_background.request(id, true, false);
+        if let Some(status) = state.notebook_background.snapshot(id) {
+            if status.state == "failed" {
+                return format!(
+                    "NOTE_INDEX_UNAVAILABLE: {}",
+                    status.message.unwrap_or_default()
+                );
+            }
+        }
+        "NOTE_INDEX_PENDING".into()
+    } else {
+        message
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn a_missing_projection_after_success_can_be_scheduled_immediately() {
+        let mut queue = Queue::default();
+        queue.enqueue("a".into(), false, false);
+        queue.pending.clear();
+        queue.statuses.get_mut("a").unwrap().state = "ready";
+        queue.finished.insert("a".into(), Instant::now());
+        queue.enqueue("a".into(), true, false);
+        assert_eq!(queue.pending.front().unwrap(), "a");
+    }
+
+    #[test]
+    fn failed_passive_reads_back_off_but_explicit_retry_is_admitted() {
+        let mut queue = Queue::default();
+        queue.enqueue("a".into(), false, false);
+        queue.pending.clear();
+        queue.statuses.get_mut("a").unwrap().state = "failed";
+        queue.finished.insert("a".into(), Instant::now());
+        queue.enqueue("a".into(), true, false);
+        assert!(queue.pending.is_empty());
+        queue.enqueue("a".into(), true, true);
+        assert_eq!(queue.pending.len(), 1);
+    }
+
+    #[test]
+    fn repeated_requests_coalesce_and_current_notebook_moves_first() {
+        let mut queue = Queue::default();
+        queue.enqueue("other".into(), false, false);
+        queue.enqueue("current".into(), false, false);
+        queue.enqueue("current".into(), true, false);
+        queue.enqueue("current".into(), true, false);
+        assert_eq!(
+            queue.pending.into_iter().collect::<Vec<_>>(),
+            ["current", "other"]
+        );
+    }
+    #[test]
+    fn active_queries_do_not_loop_but_changes_schedule_one_followup() {
+        let mut queue = Queue::default();
+        queue.active = Some("current".into());
+        queue.enqueue("current".into(), true, false);
+        assert!(queue.rerun.is_empty());
+        for _ in 0..10 {
+            queue.enqueue("current".into(), true, true);
+        }
+        assert_eq!(queue.rerun.len(), 1);
+        assert!(queue.pending.is_empty());
+    }
+    #[test]
+    fn shutdown_rejects_new_work() {
+        let queue = NotebookBackground::default();
+        queue.request("a", false, false);
+        queue.stop();
+        queue.request("b", true, false);
+        assert!(queue.queue.lock().unwrap().pending.is_empty());
+        assert!(queue.snapshot("b").is_none());
+    }
+}
diff --git a/app/flowix-desktop/src/app/paths.rs b/app/flowix-desktop/src/app/paths.rs
index 739e08cf5..0ee541fe0 100644
--- a/app/flowix-desktop/src/app/paths.rs
+++ b/app/flowix-desktop/src/app/paths.rs
@@ -1,6 +1,6 @@
 use std::path::PathBuf;
 
-/// 用户配置�?���?(~/.<NAME>/ 下放 index.db / boot/preference.json /
+/// 用户配置�?���?(~/.<NAME>/ 下放 db/*.db / boot/preference.json /
 /// agent-config.toml / boot/system.json 绛?銆?
 pub const USER_CONFIG_DIR_NAME: &str = ".flowix";
 
diff --git a/app/flowix-desktop/src/app/startup.rs b/app/flowix-desktop/src/app/startup.rs
index 63fa18321..b4b648c98 100644
--- a/app/flowix-desktop/src/app/startup.rs
+++ b/app/flowix-desktop/src/app/startup.rs
@@ -19,12 +19,30 @@ pub enum StartupPhase {
     Failed,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum StartupStage {
+    Initialization,
+    WorkspacePreparation,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StartupProgress {
+    pub percent: u8,
+    pub completed: usize,
+    pub total: usize,
+    pub task: String,
+}
+
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct StartupStatus {
     pub phase: StartupPhase,
+    pub stage: StartupStage,
     pub step: String,
     pub error: Option<String>,
+    pub progress: Option<StartupProgress>,
 }
 
 struct StartupState {
@@ -52,8 +70,10 @@ impl StartupCoordinator {
             state: Mutex::new(StartupState {
                 status: StartupStatus {
                     phase: StartupPhase::Pending,
-                    step: "initializing".to_string(),
+                    stage: StartupStage::Initialization,
+                    step: "initialization".to_string(),
                     error: None,
+                    progress: None,
                 },
                 interactive: false,
             }),
@@ -73,28 +93,83 @@ impl StartupCoordinator {
         self.started_at.elapsed().as_millis()
     }
 
-    pub fn mark_running(&self, step: impl Into<String>) {
+    pub fn mark_running(&self, stage: StartupStage, step: impl Into<String>) {
         self.update(StartupStatus {
             phase: StartupPhase::Running,
+            stage,
             step: step.into(),
             error: None,
+            progress: None,
+        });
+    }
+
+    pub fn set_progress(
+        &self,
+        percent: u8,
+        completed: usize,
+        total: usize,
+        task: impl Into<String>,
+    ) {
+        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
+        if state.status.stage != StartupStage::Initialization
+            || state.status.phase != StartupPhase::Running
+        {
+            return;
+        }
+        state.status.progress = Some(StartupProgress {
+            percent: percent.min(100),
+            completed,
+            total,
+            task: task.into(),
         });
+        self.changed.notify_all();
     }
 
     pub fn mark_ready(&self) {
         self.update(StartupStatus {
             phase: StartupPhase::Ready,
+            stage: StartupStage::WorkspacePreparation,
             step: "ready".to_string(),
             error: None,
+            progress: None,
         });
     }
 
     pub fn mark_failed(&self, error: impl Into<String>) {
-        self.update(StartupStatus {
-            phase: StartupPhase::Failed,
-            step: "failed".to_string(),
-            error: Some(error.into()),
-        });
+        // Preserve the stage and task that failed for retry UI and diagnostics.
+        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
+        state.status.phase = StartupPhase::Failed;
+        state.status.error = Some(error.into());
+        state.status.progress = None;
+        self.changed.notify_all();
+    }
+
+    /// Only a failed attempt may be retried; the existing worker owns all attempts.
+    pub fn request_retry(&self) -> Result<(), String> {
+        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
+        if state.status.phase != StartupPhase::Failed {
+            return Err("startup is not failed".into());
+        }
+        state.status = StartupStatus {
+            phase: StartupPhase::Pending,
+            stage: state.status.stage,
+            step: match state.status.stage {
+                StartupStage::Initialization => "initialization",
+                StartupStage::WorkspacePreparation => "preparingData",
+            }
+            .into(),
+            error: None,
+            progress: None,
+        };
+        self.changed.notify_all();
+        Ok(())
+    }
+
+    pub fn wait_for_retry(&self) {
+        let mut state = self.state.lock().unwrap_or_else(|p| p.into_inner());
+        while state.status.phase == StartupPhase::Failed {
+            state = self.changed.wait(state).unwrap_or_else(|p| p.into_inner());
+        }
     }
 
     pub fn wait_until_ready(&self) -> Result<(), String> {
@@ -156,6 +231,14 @@ impl StartupCoordinator {
             .state
             .lock()
             .unwrap_or_else(|poisoned| poisoned.into_inner());
+        // Once stage 2 starts, neither retries nor later maintenance may reopen
+        // version initialization. Keep this invariant at the status boundary.
+        if state.status.stage == StartupStage::WorkspacePreparation
+            && status.stage == StartupStage::Initialization
+        {
+            tracing::warn!(step = %status.step, "ignored startup transition back to initialization");
+            return;
+        }
         state.status = status;
         self.changed.notify_all();
     }
@@ -163,18 +246,32 @@ impl StartupCoordinator {
 
 #[cfg(test)]
 mod tests {
-    use super::{StartupCoordinator, StartupPhase};
+    use super::{StartupCoordinator, StartupPhase, StartupStage};
     use std::sync::Arc;
     use std::thread;
     use std::time::Duration;
 
+    #[test]
+    fn retry_only_reopens_failed_startup() {
+        let coordinator = StartupCoordinator::new();
+        assert!(coordinator.request_retry().is_err());
+        coordinator.mark_failed("interrupted");
+        coordinator.request_retry().unwrap();
+        coordinator.wait_for_retry();
+        assert_eq!(coordinator.status().phase, StartupPhase::Pending);
+        assert!(coordinator.status().error.is_none());
+        assert!(coordinator.request_retry().is_err());
+        coordinator.mark_ready();
+        assert!(coordinator.request_retry().is_err());
+    }
+
     #[test]
     fn waiters_are_released_when_startup_is_ready() {
         let coordinator = Arc::new(StartupCoordinator::new());
         let waiter = coordinator.clone();
         let handle = thread::spawn(move || waiter.wait_until_ready());
 
-        coordinator.mark_running("migrating");
+        coordinator.mark_running(StartupStage::Initialization, "migrating");
         coordinator.mark_ready();
 
         assert_eq!(handle.join().unwrap(), Ok(()));
@@ -192,6 +289,45 @@ mod tests {
         );
     }
 
+    #[test]
+    fn failure_retains_the_stage_and_task() {
+        let coordinator = StartupCoordinator::new();
+        coordinator.mark_running(StartupStage::WorkspacePreparation, "load-current-notebook");
+        coordinator.mark_failed("disk unavailable");
+        let status = coordinator.status();
+        assert_eq!(status.stage, StartupStage::WorkspacePreparation);
+        assert_eq!(status.step, "load-current-notebook");
+        coordinator.request_retry().unwrap();
+        assert_eq!(
+            coordinator.status().stage,
+            StartupStage::WorkspacePreparation
+        );
+    }
+
+    #[test]
+    fn workspace_preparation_cannot_return_to_initialization_or_publish_its_progress() {
+        let coordinator = StartupCoordinator::new();
+        coordinator.mark_running(StartupStage::Initialization, "migrating");
+        coordinator.set_progress(50, 1, 2, "migration");
+        assert!(coordinator.status().progress.is_some());
+        coordinator.mark_running(StartupStage::WorkspacePreparation, "preparingData");
+
+        for _ in 0..2 {
+            coordinator.mark_running(StartupStage::Initialization, "versionInitialization");
+            coordinator.set_progress(30, 0, 2, "prepareNotebookRegistry");
+            let status = coordinator.status();
+            assert_eq!(status.stage, StartupStage::WorkspacePreparation);
+            assert!(status.progress.is_none());
+            coordinator.mark_failed("database unavailable");
+            coordinator.request_retry().unwrap();
+            assert_eq!(
+                coordinator.status().stage,
+                StartupStage::WorkspacePreparation
+            );
+            coordinator.mark_running(StartupStage::WorkspacePreparation, "preparingData");
+        }
+    }
+
     #[test]
     fn maintenance_waits_for_the_first_interactive_workspace() {
         let coordinator = Arc::new(StartupCoordinator::new());
diff --git a/app/flowix-desktop/src/app/state.rs b/app/flowix-desktop/src/app/state.rs
index bc0fc7899..84e21a5bc 100644
--- a/app/flowix-desktop/src/app/state.rs
+++ b/app/flowix-desktop/src/app/state.rs
@@ -7,7 +7,7 @@ use crate::agent_external::runtime_registry::ExternalRuntimeRegistry;
 use crate::agent_external_config::AgentExternalConfig;
 use crate::agent_session::ThreadManager;
 use crate::app::startup::StartupCoordinator;
-use crate::config::{AgentAccessStore, SecurityBookmarkStore, UserConfigStore};
+use crate::config::{SecurityBookmarkStore, UserConfigStore};
 use crate::plugin::PluginRunCoordinator;
 use crate::system_data::SystemData;
 use flowix_core::memo_file::MemoFile;
@@ -39,9 +39,12 @@ pub struct NotebookImportStatus {
 pub struct AppState {
     pub upload_sessions: Arc<crate::commands::dialog::upload_sessions::UploadSessions>,
     pub document_access: crate::app::document_access::DocumentAccess,
+    pub security_bookmarks: Arc<SecurityBookmarkStore>,
     pub export_access: crate::app::export_access::ExportAccess,
     pub user_config: Arc<UserConfigStore>,
     pub cloud_sync: Arc<flowix_sync::SyncManager>,
+    /// Effective Cloud target selected at startup. Release builds always use prod.
+    pub cloud_environment: flowix_sync::CloudEnvironment,
     /// Legacy system metadata reader used to migrate notebook tag state into
     /// each notebook's `.flowix/system.json`.
     pub system_data: SystemData,
@@ -66,11 +69,6 @@ pub struct AppState {
     /// Runtimes without a lifecycle adapter keep Flowix-local semantics.
     pub agent_lifecycle: Arc<crate::agent_lifecycle::AgentLifecycleService>,
     pub thread_manager: Arc<ThreadManager>,
-    /// Agent 可访问目录 (notebook + 用户额外 folder), 持久化在
-    /// `~/.flowix/agent-access.json`。驱动 external agent 的
-    /// 工作区 / 资料目录过滤。
-    pub agent_access: Arc<AgentAccessStore>,
-    pub security_bookmarks: Arc<SecurityBookmarkStore>,
     pub plugin_runs: PluginRunCoordinator,
     /// Last known state for background notebook imports. Keeping the state in
     /// AppState lets a Webview recover when it subscribes after an event was
@@ -84,4 +82,7 @@ pub struct AppState {
     /// Native startup migrations are independent from WebView startup but
     /// remain a gate for commands that depend on a consistent memo library.
     pub startup: Arc<StartupCoordinator>,
+    pub notebook_background: Arc<crate::app::notebook_background::NotebookBackground>,
+    /// Stops the independent retry loop for offline notebook watcher roots.
+    pub watcher_retry_stop: Arc<std::sync::atomic::AtomicBool>,
 }
diff --git a/app/flowix-desktop/src/app/watchdog.rs b/app/flowix-desktop/src/app/watchdog.rs
index 821b65847..4466a778b 100644
--- a/app/flowix-desktop/src/app/watchdog.rs
+++ b/app/flowix-desktop/src/app/watchdog.rs
@@ -39,7 +39,7 @@ pub fn spawn_external_agent_watchdog(
             if total > 0 {
                 let summary = finalized
                     .iter()
-                    .map(|result| format!("{}={}", result.runtime.key(), result.affected))
+                    .map(|result| format!("{}={}", result.runtime.id(), result.affected))
                     .collect::<Vec<_>>()
                     .join(", ");
                 tracing::warn!(
diff --git a/app/flowix-desktop/src/app_update.rs b/app/flowix-desktop/src/app_update.rs
index 18e3d2efe..25f0a1fc2 100644
--- a/app/flowix-desktop/src/app_update.rs
+++ b/app/flowix-desktop/src/app_update.rs
@@ -1,22 +1,25 @@
 use futures::future::{AbortHandle, Abortable};
 use serde_json::json;
-use std::sync::{
-    atomic::{AtomicBool, AtomicU64, Ordering},
-    Arc, Mutex,
-};
+use std::sync::{Arc, Mutex};
 use tauri::{AppHandle, Emitter, State};
+use tauri_plugin_updater::Update;
 use tauri_plugin_updater::UpdaterExt;
 
-#[cfg(target_os = "windows")]
-use std::path::PathBuf;
-
+#[path = "app_update_cache.rs"]
+mod update_cache;
 #[path = "app_update_state.rs"]
 mod update_state;
-use update_state::UpdatePhase;
+use self::update_cache::{prepare_update_package, verify_cached_package, PreparedUpdate};
+use self::update_state::UpdatePhase;
 
-#[derive(Default)]
+#[cfg(target_os = "windows")]
+use std::path::PathBuf;
+
+#[derive(Clone, Default)]
 pub struct AppUpdateState {
     active: Arc<Mutex<ActiveUpdate>>,
+    check_lock: Arc<tokio::sync::Mutex<()>>,
+    prepared: Arc<Mutex<Option<PreparedUpdate>>>,
 }
 
 #[derive(Default)]
@@ -168,15 +171,10 @@ fn updater(app: &AppHandle) -> Result<tauri_plugin_updater::Updater, String> {
         .map_err(|error| format!("failed to initialize updater: {error}"))
 }
 
-#[tauri::command]
-pub async fn check_app_update(app: AppHandle) -> Result<Option<AppUpdateInfo>, String> {
-    let update = updater(&app)?
-        .check()
-        .await
-        .map_err(|error| format!("failed to check for update: {error}"))?;
-    Ok(update.map(|update| AppUpdateInfo {
-        current_version: update.current_version,
-        version: update.version,
+fn update_info(update: &Update) -> AppUpdateInfo {
+    AppUpdateInfo {
+        current_version: update.current_version.clone(),
+        version: update.version.clone(),
         // Unknown manifest fields are preserved by tauri-plugin-updater in
         // raw_json. Keep notifications enabled for older manifests.
         notify: update
@@ -184,14 +182,90 @@ pub async fn check_app_update(app: AppHandle) -> Result<Option<AppUpdateInfo>, S
             .get("notify")
             .and_then(serde_json::Value::as_bool)
             .unwrap_or(true),
-        date: update.date.map(|date| date.to_string()),
-        body: update.body,
-    }))
+        date: update.date.as_ref().map(|date| date.to_string()),
+        body: update.body.clone(),
+    }
+}
+
+fn ensure_update_is_idle(state: &AppUpdateState) -> Result<(), String> {
+    let active = state
+        .active
+        .lock()
+        .map_err(|_| "application update state is unavailable".to_string())?;
+    if active.phase == UpdatePhase::Idle {
+        Ok(())
+    } else {
+        Err("an application update is already in progress".to_string())
+    }
+}
+
+async fn download_requested_update(
+    app: &AppHandle,
+    prepared_state: &Arc<Mutex<Option<PreparedUpdate>>>,
+    version: &str,
+) -> Result<(Update, Vec<u8>), String> {
+    let update = updater(app)?
+        .check()
+        .await
+        .map_err(|error| format!("failed to check for update: {error}"))?
+        .ok_or_else(|| "no application update is available".to_string())?;
+    if update.version != version {
+        return Err(format!("requested update {version} is no longer available"));
+    }
+
+    let prepared = prepare_update_package(app, update, true).await?;
+    let bytes = tokio::fs::read(&prepared.package_path)
+        .await
+        .map_err(|error| format!("failed to read prepared application update: {error}"))?;
+    verify_cached_package(app, &prepared.update, &bytes)?;
+    *prepared_state
+        .lock()
+        .map_err(|_| "application update state is unavailable".to_string())? =
+        Some(prepared.clone());
+    Ok((prepared.update, bytes))
+}
+
+#[tauri::command]
+pub async fn check_app_update(
+    app: AppHandle,
+    state: State<'_, AppUpdateState>,
+) -> Result<Option<AppUpdateInfo>, String> {
+    ensure_update_is_idle(state.inner())?;
+    let _check_guard = state.check_lock.lock().await;
+    ensure_update_is_idle(state.inner())?;
+
+    let update = updater(&app)?
+        .check()
+        .await
+        .map_err(|error| format!("failed to check for update: {error}"))?;
+    let Some(update) = update else {
+        *state
+            .prepared
+            .lock()
+            .map_err(|_| "application update state is unavailable".to_string())? = None;
+        return Ok(None);
+    };
+
+    let info = update_info(&update);
+    if info.notify {
+        let prepared = prepare_update_package(&app, update, false).await?;
+        *state
+            .prepared
+            .lock()
+            .map_err(|_| "application update state is unavailable".to_string())? = Some(prepared);
+    } else {
+        *state
+            .prepared
+            .lock()
+            .map_err(|_| "application update state is unavailable".to_string())? = None;
+    }
+    Ok(Some(info))
 }
 
 #[tauri::command]
 pub async fn install_app_update(
     app: AppHandle,
+    version: String,
     state: State<'_, AppUpdateState>,
 ) -> Result<(), String> {
     let (abort_handle, abort_registration) = AbortHandle::new_pair();
@@ -208,56 +282,42 @@ pub async fn install_app_update(
     let active_guard = ActiveUpdateGuard(state.active.clone());
 
     let download_app = app.clone();
-    let downloaded_bytes = Arc::new(AtomicU64::new(0));
-    let started = Arc::new(AtomicBool::new(false));
+    let check_lock = state.check_lock.clone();
+    let prepared_state = state.prepared.clone();
     let task = async move {
-        let update = updater(&download_app)?
-            .check()
-            .await
-            .map_err(|error| format!("failed to check for update: {error}"))?
-            .ok_or_else(|| "no application update is available".to_string())?;
-        let progress_bytes = downloaded_bytes.clone();
-        let progress_started = started.clone();
-        let bytes = update
-            .download(
-                |chunk_length, content_length| {
-                    if !progress_started.swap(true, Ordering::Relaxed) {
-                        let _ = download_app.emit(
-                            "app-update-progress",
-                            json!({
-                                "phase": "started",
-                                "contentLength": content_length,
-                            }),
-                        );
+        let (update, bytes) = {
+            let _check_guard = check_lock.lock().await;
+            let prepared = prepared_state
+                .lock()
+                .map_err(|_| "application update state is unavailable".to_string())?
+                .clone()
+                .filter(|prepared| prepared.update.version == version);
+
+            if let Some(prepared) = prepared {
+                if let Ok(bytes) = tokio::fs::read(&prepared.package_path).await {
+                    if verify_cached_package(&download_app, &prepared.update, &bytes).is_ok() {
+                        (prepared.update, bytes)
+                    } else {
+                        let _ = tokio::fs::remove_file(&prepared.package_path).await;
+                        *prepared_state
+                            .lock()
+                            .map_err(|_| "application update state is unavailable".to_string())? =
+                            None;
+                        download_requested_update(&download_app, &prepared_state, &version).await?
                     }
-                    let downloaded = progress_bytes
-                        .fetch_add(chunk_length as u64, Ordering::Relaxed)
-                        + chunk_length as u64;
-                    let _ = download_app.emit(
-                        "app-update-progress",
-                        json!({
-                            "phase": "progress",
-                            "downloadedBytes": downloaded,
-                            "contentLength": content_length,
-                        }),
-                    );
-                },
-                || {
-                    let _ = download_app.emit(
-                        "app-update-progress",
-                        json!({
-                            "phase": "finished",
-                            "downloadedBytes": progress_bytes.load(Ordering::Relaxed),
-                        }),
-                    );
-                },
-            )
-            .await
-            .map_err(|error| format!("failed to download update: {error}"))?;
+                } else {
+                    download_requested_update(&download_app, &prepared_state, &version).await?
+                }
+            } else {
+                download_requested_update(&download_app, &prepared_state, &version).await?
+            }
+        };
+
+        verify_cached_package(&download_app, &update, &bytes)?;
 
         #[cfg(windows)]
         let document_guard =
-            crate::commands::document_shutdown::prepare_for_update(&download_app).await?;
+            crate::commands::window_shutdown::prepare_for_update(&download_app).await?;
         #[cfg(not(windows))]
         let document_guard = ();
         Ok::<_, String>((update, bytes, document_guard))
diff --git a/app/flowix-desktop/src/app_update_cache.rs b/app/flowix-desktop/src/app_update_cache.rs
new file mode 100644
index 000000000..7bd1e1932
--- /dev/null
+++ b/app/flowix-desktop/src/app_update_cache.rs
@@ -0,0 +1,189 @@
+use serde_json::json;
+use sha2::{Digest, Sha256};
+use std::{
+    fmt::Write as _,
+    path::PathBuf,
+    sync::{
+        atomic::{AtomicBool, AtomicU64, Ordering},
+        Arc,
+    },
+};
+use tauri::{AppHandle, Emitter, Manager};
+use tauri_plugin_updater::Update;
+
+#[derive(Clone)]
+pub(super) struct PreparedUpdate {
+    pub(super) update: Update,
+    pub(super) package_path: PathBuf,
+}
+
+fn update_cache_location(app: &AppHandle, update: &Update) -> Result<PathBuf, String> {
+    let mut hasher = Sha256::new();
+    for value in [
+        update.target.as_str(),
+        update.version.as_str(),
+        update.download_url.as_str(),
+        update.signature.as_str(),
+    ] {
+        hasher.update(value.as_bytes());
+        hasher.update([0]);
+    }
+    let digest = hasher.finalize();
+    let mut package_key = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        let _ = write!(package_key, "{byte:02x}");
+    }
+
+    let directory = app
+        .path()
+        .app_cache_dir()
+        .map_err(|error| format!("failed to locate application cache directory: {error}"))?
+        .join("app-updates");
+    Ok(directory.join(format!("update-{package_key}.bundle")))
+}
+
+pub(super) fn verify_cached_package(
+    app: &AppHandle,
+    update: &Update,
+    bytes: &[u8],
+) -> Result<(), String> {
+    use base64::Engine as _;
+
+    let encoded_key = app
+        .config()
+        .plugins
+        .0
+        .get("updater")
+        .and_then(|config| config.get("pubkey"))
+        .and_then(serde_json::Value::as_str)
+        .ok_or_else(|| {
+            "updater public key is missing from application configuration".to_string()
+        })?;
+    let key_text = base64::engine::general_purpose::STANDARD
+        .decode(encoded_key)
+        .map_err(|error| format!("failed to decode updater public key: {error}"))?;
+    let key_text = std::str::from_utf8(&key_text)
+        .map_err(|error| format!("updater public key is not valid UTF-8: {error}"))?;
+    let public_key = minisign_verify::PublicKey::decode(key_text)
+        .map_err(|error| format!("failed to parse updater public key: {error}"))?;
+
+    let signature_text = base64::engine::general_purpose::STANDARD
+        .decode(&update.signature)
+        .map_err(|error| format!("failed to decode update signature: {error}"))?;
+    let signature_text = std::str::from_utf8(&signature_text)
+        .map_err(|error| format!("update signature is not valid UTF-8: {error}"))?;
+    let signature = minisign_verify::Signature::decode(signature_text)
+        .map_err(|error| format!("failed to parse update signature: {error}"))?;
+    public_key
+        .verify(bytes, &signature, true)
+        .map_err(|error| format!("cached update signature verification failed: {error}"))
+}
+
+async fn remove_old_update_packages(directory: &std::path::Path, keep: &std::path::Path) {
+    let Ok(mut entries) = tokio::fs::read_dir(directory).await else {
+        return;
+    };
+    while let Ok(Some(entry)) = entries.next_entry().await {
+        let path = entry.path();
+        if path != keep {
+            let _ = tokio::fs::remove_file(path).await;
+        }
+    }
+}
+
+pub(super) async fn prepare_update_package(
+    app: &AppHandle,
+    update: Update,
+    report_progress: bool,
+) -> Result<PreparedUpdate, String> {
+    let package_path = update_cache_location(app, &update)?;
+    let directory = package_path
+        .parent()
+        .ok_or_else(|| "application update cache path has no parent directory".to_string())?;
+    tokio::fs::create_dir_all(directory)
+        .await
+        .map_err(|error| format!("failed to create application update cache: {error}"))?;
+
+    match tokio::fs::read(&package_path).await {
+        Ok(bytes) if verify_cached_package(app, &update, &bytes).is_ok() => {
+            remove_old_update_packages(directory, &package_path).await;
+            return Ok(PreparedUpdate {
+                update,
+                package_path,
+            });
+        }
+        Ok(_) => {
+            let _ = tokio::fs::remove_file(&package_path).await;
+        }
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+        Err(error) => {
+            return Err(format!("failed to read cached application update: {error}"));
+        }
+    }
+
+    let partial_path = package_path.with_extension("part");
+    let _ = tokio::fs::remove_file(&partial_path).await;
+    let downloaded_bytes = Arc::new(AtomicU64::new(0));
+    let started = Arc::new(AtomicBool::new(false));
+    let progress_app = report_progress.then(|| app.clone());
+    let chunk_app = progress_app.clone();
+    let chunk_bytes = downloaded_bytes.clone();
+    let chunk_started = started.clone();
+    let finish_bytes = downloaded_bytes.clone();
+    let bytes = update
+        .download(
+            move |chunk_length, content_length| {
+                let Some(progress_app) = chunk_app.as_ref() else {
+                    return;
+                };
+                if !chunk_started.swap(true, Ordering::Relaxed) {
+                    let _ = progress_app.emit(
+                        "app-update-progress",
+                        json!({ "phase": "started", "contentLength": content_length }),
+                    );
+                }
+                let downloaded = chunk_bytes.fetch_add(chunk_length as u64, Ordering::Relaxed)
+                    + chunk_length as u64;
+                let _ = progress_app.emit(
+                    "app-update-progress",
+                    json!({
+                        "phase": "progress",
+                        "downloadedBytes": downloaded,
+                        "contentLength": content_length,
+                    }),
+                );
+            },
+            move || {
+                if let Some(progress_app) = progress_app.as_ref() {
+                    let _ = progress_app.emit(
+                        "app-update-progress",
+                        json!({
+                            "phase": "finished",
+                            "downloadedBytes": finish_bytes.load(Ordering::Relaxed),
+                        }),
+                    );
+                }
+            },
+        )
+        .await
+        .map_err(|error| format!("failed to download update: {error}"))?;
+
+    // `Update::download` verifies the signature. Verify here as well so the
+    // same rule applies to freshly downloaded and previously cached bytes.
+    verify_cached_package(app, &update, &bytes)?;
+    tokio::fs::write(&partial_path, &bytes)
+        .await
+        .map_err(|error| format!("failed to write cached application update: {error}"))?;
+    if let Err(error) = tokio::fs::rename(&partial_path, &package_path).await {
+        let _ = tokio::fs::remove_file(&partial_path).await;
+        return Err(format!(
+            "failed to publish cached application update: {error}"
+        ));
+    }
+    remove_old_update_packages(directory, &package_path).await;
+
+    Ok(PreparedUpdate {
+        update,
+        package_path,
+    })
+}
diff --git a/app/flowix-desktop/src/commands/agent/chat.rs b/app/flowix-desktop/src/commands/agent/chat.rs
index 7a6fcdfed..e590ece3f 100644
--- a/app/flowix-desktop/src/commands/agent/chat.rs
+++ b/app/flowix-desktop/src/commands/agent/chat.rs
@@ -48,7 +48,7 @@ pub async fn chat_with_agent_stream(
     tracing::info!(
         "[Command] chat_with_agent_stream called for thread: {}, agent_type: {}",
         threadId,
-        runtime.key()
+        runtime.id()
     );
 
     if let Some(title) = message
@@ -61,46 +61,18 @@ pub async fn chat_with_agent_stream(
         manager
             .ensure_thread(
                 &threadId,
-                crate::agent_types::AgentId::new(runtime.key()),
+                crate::agent_types::AgentId::new(runtime.id()),
                 title,
             )
             .await
             .map_err(|error| error.to_string())?;
     }
 
-    // Refresh security-scoped access at every run, not only at startup. Start
-    // access before validating because a macOS bookmark may be what makes the
-    // directory visible to this process. Explicit runtime paths must never
-    // silently fall back to the application cwd when a frozen path disappears.
-    let runtime_cwd = message
-        .cwd_for_runtime(runtime.key())
-        .map(str::trim)
-        .filter(|path| !path.is_empty())
-        .map(str::to_string);
-    let runtime_workspace_paths = message.workspace_paths_for_runtime(runtime.key());
-    if let Some(path) = runtime_cwd.as_deref() {
-        state
-            .security_bookmarks
-            .start_accessing_for_path(Path::new(path));
-    }
-    for path in &runtime_workspace_paths {
-        state
-            .security_bookmarks
-            .start_accessing_for_path(Path::new(path));
-    }
-    if let Some(path) = runtime_cwd.as_deref() {
-        if !Path::new(path).is_dir() {
-            return Err(format!("Agent working directory is unavailable: {path}"));
-        }
-    }
-    for path in &runtime_workspace_paths {
-        if !Path::new(path).is_dir() {
-            return Err(format!("Agent workspace directory is unavailable: {path}"));
-        }
-    }
+    let (runtime_cwd, runtime_workspace_paths) =
+        validate_runtime_workspace(&message, runtime.id(), &state)?;
 
     if let Some(path) = runtime_cwd.as_deref() {
-        sync_native_agent_instructions(Path::new(path), runtime.key(), &runtime_workspace_paths)?;
+        sync_native_agent_instructions(Path::new(path), runtime.id(), &runtime_workspace_paths)?;
     }
 
     // runtime 的 `chat_stream` 内部已经 `tokio::spawn` ── IPC 立即返回,
@@ -113,12 +85,103 @@ pub async fn chat_with_agent_stream(
         .await;
     tracing::info!(
         "[Command] {} chat_with_agent_stream result: {:?}",
-        runtime.key(),
+        runtime.id(),
         result.is_ok()
     );
     result.map(|response| AgentChatResponse { response })
 }
 
+fn validate_runtime_workspace(
+    message: &AgentUserMessage,
+    runtime: &str,
+    state: &AppState,
+) -> Result<(Option<String>, Vec<String>), String> {
+    // Explicit runtime paths must never silently fall back to the application
+    // cwd when a frozen path disappears.
+    let runtime_cwd = message
+        .cwd_for_runtime(runtime)
+        .map(str::trim)
+        .filter(|path| !path.is_empty())
+        .map(str::to_string);
+    let runtime_workspace_paths = message.workspace_paths_for_runtime(runtime);
+    {
+        let memo = state
+            .memo_file
+            .read()
+            .map_err(|_| "memo file lock poisoned")?;
+        let workspace = memo.read_notebook_workspace().map_err(|e| e.to_string())?;
+        let scope = message
+            .runtime_config
+            .as_ref()
+            .and_then(|config| config.notebook_id.as_deref());
+        check_workspace_paths(
+            &workspace,
+            scope,
+            runtime_cwd
+                .iter()
+                .chain(runtime_workspace_paths.iter())
+                .map(String::as_str),
+        )?;
+    }
+    if let Some(path) = runtime_cwd.as_deref() {
+        if !Path::new(path).is_dir() {
+            return Err(format!("Agent working directory is unavailable: {path}"));
+        }
+    }
+    for path in &runtime_workspace_paths {
+        if !Path::new(path).is_dir() {
+            return Err(format!("Agent workspace directory is unavailable: {path}"));
+        }
+    }
+
+    Ok((runtime_cwd, runtime_workspace_paths))
+}
+
+fn check_workspace_paths<'a>(
+    workspace: &flowix_core::memo_file::NotebookWorkspaceSnapshot,
+    scope: Option<&str>,
+    paths: impl Iterator<Item = &'a str>,
+) -> Result<(), String> {
+    let mut roots = Vec::new();
+    for notebook in &workspace.notebooks {
+        if scope.is_some_and(|id| id != notebook.id) {
+            continue;
+        }
+        roots.push(notebook.path.as_str());
+        if let Some(config) = workspace.notebook_configs.get(&notebook.id) {
+            roots.extend(
+                config
+                    .add_dirs
+                    .iter()
+                    .filter(|d| d.enabled && !d.missing)
+                    .map(|d| d.path.as_str()),
+            );
+        }
+    }
+    for path in paths {
+        let path = Path::new(path);
+        if !roots
+            .iter()
+            .any(|root| crate::config::path_is_inside(path, Path::new(root)))
+        {
+            return Err(format!(
+                "Agent workspace directory is no longer mounted: {}",
+                path.display()
+            ));
+        }
+        if workspace.notebooks.iter().any(|notebook| {
+            crate::config::path_is_inside_reserved_directory(
+                path,
+                Path::new(&notebook.path),
+                ".flowix",
+            )
+        }) {
+            return Err("Agent workspace cannot use notebook internal storage".into());
+        }
+    }
+    Ok(())
+}
+
 /// Append input to the currently active steerable turn without creating a new run.
 #[tauri::command]
 #[allow(non_snake_case)]
@@ -130,6 +193,7 @@ pub async fn steer_agent_stream(
     state: State<'_, AppState>,
     app_handle: tauri::AppHandle,
 ) -> Result<(), String> {
+    validate_runtime_workspace(&message, runtime_from_message(&message)?.id(), &state)?;
     match message.agent_type.as_deref() {
         Some("codex") => {
             state
@@ -137,7 +201,7 @@ pub async fn steer_agent_stream(
                 .steer_codex(&threadId, message, clientUserMessageId, &app_handle)
                 .await
         }
-        Some("deepseek-harness") | Some("deepseek_harness") | Some("dsh") => {
+        Some("dsh") => {
             state
                 .external_runtimes
                 .steer_deepseek_harness(&threadId, message, clientUserMessageId, &app_handle)
@@ -276,10 +340,11 @@ pub async fn execute_deepseek_harness_command(
         .await?;
     if !matches!(
         message.agent_type.as_deref(),
-        Some("deepseek-harness") | Some("deepseek_harness") | Some("dsh") | None
+        Some("dsh") | None
     ) {
         return Err("DSH slash commands require the deepseek-harness agent".to_string());
     }
+    validate_runtime_workspace(&message, "dsh", &state)?;
     state
         .deepseek_harness
         .execute_command(&threadId, &command, &message, &app_handle)
@@ -296,7 +361,7 @@ pub async fn deepseek_harness_skill_catalog(
 ) -> Result<serde_json::Value, String> {
     if !matches!(
         message.agent_type.as_deref(),
-        Some("deepseek-harness") | Some("deepseek_harness") | Some("dsh") | None
+        Some("dsh") | None
     ) {
         return Err("DSH skills require the deepseek-harness agent".to_string());
     }
@@ -333,7 +398,7 @@ pub async fn stop_agent_stream(
     tracing::info!(
         "[Command] stop_agent_stream called for thread: {}, agent_type: {}, run_id: {}",
         threadId,
-        runtime.map(AgentRuntime::key).unwrap_or("unknown"),
+        runtime.map(AgentRuntime::id).unwrap_or("unknown"),
         runId.as_deref().unwrap_or("<any>")
     );
     let signalled = match runtime {
@@ -463,3 +528,73 @@ pub async fn codex_slash_command(
         )
         .await
 }
+
+#[cfg(test)]
+mod workspace_tests {
+    use super::*;
+    use flowix_core::memo_file::{
+        NotebookAddDir, NotebookConfig, NotebookWorkspaceConfig, NotebookWorkspaceSnapshot,
+    };
+    #[test]
+    fn runtime_paths_follow_notebook_mounts_and_protect_internal_storage() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path().join("notes");
+        let repo = temp.path().join("repo");
+        std::fs::create_dir_all(root.join(".flowix")).unwrap();
+        std::fs::create_dir(&repo).unwrap();
+        let root = root.to_string_lossy().into_owned();
+        let repo = repo.to_string_lossy().into_owned();
+        let mut workspace = NotebookWorkspaceSnapshot {
+            notebooks: vec![NotebookConfig {
+                id: "one".into(),
+                name: "One".into(),
+                icon: None,
+                path: root.clone(),
+                is_default: true,
+                sort: 0,
+                created_at: 0,
+                updated_at: 0,
+            }],
+            notebook_configs: HashMap::from([(
+                "one".into(),
+                NotebookWorkspaceConfig {
+                    version: 1,
+                    revision: 1,
+                    add_dirs: vec![NotebookAddDir {
+                        id: "repo".into(),
+                        path: repo.clone(),
+                        label: "Repo".into(),
+                        enabled: true,
+                        missing: false,
+                    }],
+                },
+            )]),
+        };
+        assert!(check_workspace_paths(
+            &workspace,
+            Some("one"),
+            [root.as_str(), repo.as_str()].into_iter()
+        )
+        .is_ok());
+        assert!(
+            check_workspace_paths(&workspace, Some("other"), [repo.as_str()].into_iter()).is_err()
+        );
+        let internal = Path::new(&root)
+            .join(".flowix")
+            .to_string_lossy()
+            .into_owned();
+        assert!(
+            check_workspace_paths(&workspace, Some("one"), [internal.as_str()].into_iter())
+                .is_err()
+        );
+        workspace
+            .notebook_configs
+            .get_mut("one")
+            .unwrap()
+            .add_dirs
+            .clear();
+        assert!(
+            check_workspace_paths(&workspace, Some("one"), [repo.as_str()].into_iter()).is_err()
+        );
+    }
+}
diff --git a/app/flowix-desktop/src/commands/agent/external_config.rs b/app/flowix-desktop/src/commands/agent/external_config.rs
index 45afa46df..4a9e416c8 100644
--- a/app/flowix-desktop/src/commands/agent/external_config.rs
+++ b/app/flowix-desktop/src/commands/agent/external_config.rs
@@ -12,26 +12,66 @@ use crate::app::state::AppState;
 const CODEX_VERSION_TOO_LOW_CODE: &str = "version-too-low";
 const CODEX_VERSION_TOO_LOW_REASON: &str = "Codex CLI version below 0.150.0";
 const MIN_CODEX_CLI_VERSION: (u64, u64, u64) = (0, 150, 0);
+const STARTUP_CLI_DETECTION_WAIT: std::time::Duration = std::time::Duration::from_secs(30);
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "kebab-case")]
+enum InstallationState {
+    Unknown,
+    Installed,
+    Missing,
+}
+
+#[derive(Clone, Copy, Debug, Serialize)]
+#[serde(rename_all = "kebab-case")]
+enum ReadinessState {
+    Unknown,
+    Ready,
+    Blocked,
+}
 
 #[derive(Clone, Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
-pub struct AgentRuntimeAvailability {
-    available: bool,
-    installed: bool,
+pub struct AgentRuntimeSnapshot {
+    installation: InstallationState,
+    readiness: ReadinessState,
     reason_code: Option<String>,
     reason: Option<String>,
 }
 
+impl AgentRuntimeSnapshot {
+    fn new(
+        installation: InstallationState,
+        readiness: ReadinessState,
+        reason_code: Option<&str>,
+        reason: Option<String>,
+    ) -> Self {
+        Self {
+            installation,
+            readiness,
+            reason_code: reason_code.map(str::to_string),
+            reason,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AgentRuntimeAgents {
+    pi: AgentRuntimeSnapshot,
+    codex: AgentRuntimeSnapshot,
+    #[serde(rename = "claudecode")]
+    claude_code: AgentRuntimeSnapshot,
+    opencode: AgentRuntimeSnapshot,
+    hermes: AgentRuntimeSnapshot,
+    #[serde(rename = "dsh")]
+    dsh: AgentRuntimeSnapshot,
+}
+
 #[derive(Clone, Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AgentRuntimeStatus {
-    codex: AgentRuntimeAvailability,
-    claude: AgentRuntimeAvailability,
-    hermes: AgentRuntimeAvailability,
-    opencode: AgentRuntimeAvailability,
-    pi: AgentRuntimeAvailability,
-    #[serde(rename = "deepseek-harness")]
-    deepseek_harness: AgentRuntimeAvailability,
+    agents: AgentRuntimeAgents,
 }
 
 fn executable_available(path: &Path) -> bool {
@@ -50,24 +90,37 @@ fn executable_available(path: &Path) -> bool {
 
 /// 基于 `agent-external-config` 里�?录的 path 算单�?external agent 的可用性�?/// `path = None` -> �?���?(�?��探测没探�?; `path = Some` 但失�?-> not found;
 /// �?�� -> `None` (调用方再叠加 preflight 错�?, �?codex �?Node 依赖)�?
-fn external_availability(entry: AgentExternalEntry, label: &str) -> AgentRuntimeAvailability {
+fn external_availability(entry: AgentExternalEntry, label: &str) -> AgentRuntimeSnapshot {
     let available = entry
         .path
         .as_ref()
         .map(|p| executable_available(p))
         .unwrap_or(false);
-    let reason = match &entry.path {
-        None => Some(format!(
-            "{label} not configured (click Redetect in preferences)"
-        )),
-        Some(p) if !available => Some(format!("{label} not found ({})", p.display())),
-        Some(_) => None,
-    };
-    AgentRuntimeAvailability {
-        available,
-        installed: available,
-        reason_code: None,
-        reason,
+    match (&entry.path, available, entry.detected) {
+        (None, _, false) => AgentRuntimeSnapshot::new(
+            InstallationState::Unknown,
+            ReadinessState::Unknown,
+            Some("path-not-detected"),
+            Some(format!("{label} path has not been detected")),
+        ),
+        (None, _, true) => AgentRuntimeSnapshot::new(
+            InstallationState::Missing,
+            ReadinessState::Unknown,
+            Some("runtime-not-installed"),
+            Some(format!("{label} was not found")),
+        ),
+        (Some(path), false, _) => AgentRuntimeSnapshot::new(
+            InstallationState::Missing,
+            ReadinessState::Unknown,
+            Some("configured-path-missing"),
+            Some(format!("{label} not found ({})", path.display())),
+        ),
+        (Some(_), true, _) => AgentRuntimeSnapshot::new(
+            InstallationState::Installed,
+            ReadinessState::Ready,
+            None,
+            None,
+        ),
     }
 }
 
@@ -105,67 +158,70 @@ pub async fn agent_runtime_status(
     app: tauri::AppHandle,
     state: State<'_, AppState>,
 ) -> Result<AgentRuntimeStatus, String> {
+    let startup_detection_finished = tokio::time::timeout(
+        STARTUP_CLI_DETECTION_WAIT,
+        state.agent_external_config.wait_for_startup_detect(),
+    )
+    .await
+    .is_ok();
+    if !startup_detection_finished {
+        tracing::warn!(
+            wait_seconds = STARTUP_CLI_DETECTION_WAIT.as_secs(),
+            "startup CLI detection did not finish before the runtime status deadline"
+        );
+    }
     // The external CLI path comes from agent-external-config.json. Runtime
     // preflight can still add dependency details without hiding the entry.
     let cfg = &state.agent_external_config;
     let mut codex = external_availability(cfg.get_entry("codex"), "Codex CLI");
-    if codex.available {
+    if matches!(codex.installation, InstallationState::Installed) {
         if codex_version_is_too_low().await {
-            codex.available = false;
+            codex.readiness = ReadinessState::Blocked;
             codex.reason_code = Some(CODEX_VERSION_TOO_LOW_CODE.to_string());
             codex.reason = Some(CODEX_VERSION_TOO_LOW_REASON.to_string());
         } else {
-            codex.reason = crate::agent_external::codex::preflight_codex().err();
+            if let Err(reason) = crate::agent_external::codex::preflight_codex() {
+                codex.readiness = ReadinessState::Blocked;
+                codex.reason_code = Some("preflight-failed".to_string());
+                codex.reason = Some(reason);
+            }
         }
     }
-    let claude = external_availability(cfg.get_entry("claude"), "Claude Code CLI");
+    let claude_code = external_availability(cfg.get_entry("claudecode"), "Claude Code CLI");
     let hermes = external_availability(cfg.get_entry("hermes"), "Hermes Agent CLI");
     let opencode = external_availability(cfg.get_entry("opencode"), "OpenCode CLI");
-    let pi = {
-        use tauri::Manager;
-        let platform = match std::env::consts::OS {
-            "macos" => "darwin",
-            other => other,
-        };
-        let bundled = app.path().resource_dir().ok().is_some_and(|resources| {
-            let name = if cfg!(windows) { "pi.exe" } else { "pi" };
-            let arch = match std::env::consts::ARCH {
-                "aarch64" => "arm64",
-                "x86_64" => "x64",
-                other => other,
-            };
-            let root = resources.join("pi").join(format!("{platform}-{arch}"));
-            root.join("dist").join(name).is_file() || root.join(name).is_file()
-        });
-        let env_path_available = std::env::var_os("PI_CLI_PATH")
-            .map(PathBuf::from)
-            .as_deref()
-            .is_some_and(crate::agent_external::cli_resolver::is_executable_file);
-        let path_available = crate::agent_external::cli_resolver::which_in_path(
-            if cfg!(windows) { "pi.exe" } else { "pi" },
-            std::env::var_os("PATH").as_deref(),
+    let pi = if crate::agent_external::pi::resolve_pi_binary(&app).is_ok() {
+        AgentRuntimeSnapshot::new(
+            InstallationState::Installed,
+            ReadinessState::Ready,
+            None,
+            None,
+        )
+    } else {
+        AgentRuntimeSnapshot::new(
+            InstallationState::Missing,
+            ReadinessState::Unknown,
+            Some("runtime-not-installed"),
+            Some("The bundled Pi runtime is missing or not executable".to_string()),
         )
-        .is_some();
-        let installed_flowix = crate::agent_external::pi::installed_flowix_pi_binary().is_some();
-        let available = bundled || env_path_available || path_available || installed_flowix;
-        AgentRuntimeAvailability {
-            available,
-            installed: available,
-            reason_code: None,
-            reason: (!available)
-                .then(|| "Pi runtime not installed (or not included in this build)".to_string()),
-        }
     };
     let dsh_status = crate::dsh::status();
     let deepseek_harness = if !dsh_status.installed {
-        AgentRuntimeAvailability {
-            available: false,
-            installed: false,
-            reason_code: None,
-            reason: dsh_status
+        AgentRuntimeSnapshot::new(
+            InstallationState::Missing,
+            ReadinessState::Unknown,
+            Some("runtime-not-installed"),
+            dsh_status
                 .message
                 .or_else(|| Some("DeepSeek Harness runtime is not installed".to_string())),
-        }
+        )
+    } else if !dsh_status.app_server_profile_installed {
+        AgentRuntimeSnapshot::new(
+            InstallationState::Installed,
+            ReadinessState::Blocked,
+            Some("appserver-profile-not-installed"),
+            Some("Install the DSH App Server plugin from Flowix Preferences".to_string()),
+        )
     } else {
         match state.deepseek_harness.dsh_model_configs().await {
             Ok(configs)
@@ -177,41 +233,43 @@ pub async fn agent_runtime_status(
                     .is_ok()
                 }) =>
             {
-                AgentRuntimeAvailability {
-                    available: true,
-                    installed: true,
-                    reason_code: None,
-                    reason: None,
-                }
+                AgentRuntimeSnapshot::new(
+                    InstallationState::Installed,
+                    ReadinessState::Ready,
+                    None,
+                    None,
+                )
             }
-            Ok(configs) if configs.is_empty() => AgentRuntimeAvailability {
-                available: false,
-                installed: true,
-                reason_code: None,
-                reason: Some("No DeepSeek Harness model is configured".to_string()),
-            },
-            Ok(_) => AgentRuntimeAvailability {
-                available: false,
-                installed: true,
-                reason_code: None,
-                reason: Some("DeepSeek Harness has no usable model configuration".to_string()),
-            },
-            Err(error) => AgentRuntimeAvailability {
-                available: false,
-                installed: true,
-                reason_code: None,
-                reason: Some(format!("Could not read DeepSeek Harness models: {error}")),
-            },
+            Ok(configs) if configs.is_empty() => AgentRuntimeSnapshot::new(
+                InstallationState::Installed,
+                ReadinessState::Blocked,
+                Some("no-model-configured"),
+                Some("No DeepSeek Harness model is configured".to_string()),
+            ),
+            Ok(_) => AgentRuntimeSnapshot::new(
+                InstallationState::Installed,
+                ReadinessState::Blocked,
+                Some("no-usable-model"),
+                Some("DeepSeek Harness has no usable model configuration".to_string()),
+            ),
+            Err(error) => AgentRuntimeSnapshot::new(
+                InstallationState::Installed,
+                ReadinessState::Unknown,
+                Some("status-check-failed"),
+                Some(format!("Could not read DeepSeek Harness models: {error}")),
+            ),
         }
     };
 
     Ok(AgentRuntimeStatus {
-        codex,
-        claude,
-        hermes,
-        opencode,
-        pi,
-        deepseek_harness,
+        agents: AgentRuntimeAgents {
+            pi,
+            codex,
+            claude_code,
+            opencode,
+            hermes,
+            dsh: deepseek_harness,
+        },
     })
 }
 
diff --git a/app/flowix-desktop/src/commands/agent/flowix_instructions.rs b/app/flowix-desktop/src/commands/agent/flowix_instructions.rs
index d493877a2..3f869b9ce 100644
--- a/app/flowix-desktop/src/commands/agent/flowix_instructions.rs
+++ b/app/flowix-desktop/src/commands/agent/flowix_instructions.rs
@@ -64,7 +64,7 @@ pub(crate) fn sync_native_agent_instructions(
     agent_type: &str,
     workspace_paths: &[String],
 ) -> Result<(), String> {
-    if !matches!(agent_type, "codex" | "deepseek-harness" | "pi") {
+    if !matches!(agent_type, "codex" | "dsh" | "pi") {
         return Ok(());
     }
     if !cwd.is_dir() {
diff --git a/app/flowix-desktop/src/commands/agent/model_catalog.rs b/app/flowix-desktop/src/commands/agent/model_catalog.rs
index 6cf4cd870..127bb9edc 100644
--- a/app/flowix-desktop/src/commands/agent/model_catalog.rs
+++ b/app/flowix-desktop/src/commands/agent/model_catalog.rs
@@ -33,7 +33,7 @@ pub async fn agent_supported_models(
         "codex" => state.codex_app_server.supported_models().await,
         "opencode" => state.opencode.supported_models().await,
         "pi" => state.pi.supported_models(&app).await,
-        "deepseek-harness" | "deepseek_harness" | "dsh" => {
+        "dsh" => {
             state.deepseek_harness.supported_models().await
         }
         _ => Ok(Vec::new()),
diff --git a/app/flowix-desktop/src/commands/agent/runtime.rs b/app/flowix-desktop/src/commands/agent/runtime.rs
index dda9e65f1..cdbc02121 100644
--- a/app/flowix-desktop/src/commands/agent/runtime.rs
+++ b/app/flowix-desktop/src/commands/agent/runtime.rs
@@ -39,9 +39,9 @@ pub(crate) async fn start_plugin_chat(
     app_handle: &tauri::AppHandle,
 ) -> Result<(), String> {
     let runtime = runtime_from_message(&message)?;
-    if let Some(cwd) = message.cwd_for_runtime(runtime.key()) {
-        let workspace_paths = message.workspace_paths_for_runtime(runtime.key());
-        sync_native_agent_instructions(std::path::Path::new(cwd), runtime.key(), &workspace_paths)?;
+    if let Some(cwd) = message.cwd_for_runtime(runtime.id()) {
+        let workspace_paths = message.workspace_paths_for_runtime(runtime.id());
+        sync_native_agent_instructions(std::path::Path::new(cwd), runtime.id(), &workspace_paths)?;
     }
     state.external_runtimes
         .dispatch_chat(thread_id, runtime, message, app_handle)
diff --git a/app/flowix-desktop/src/commands/agent_access.rs b/app/flowix-desktop/src/commands/agent_access.rs
deleted file mode 100644
index 7db72ba6c..000000000
--- a/app/flowix-desktop/src/commands/agent_access.rs
+++ /dev/null
@@ -1,633 +0,0 @@
-//! Agent 访问�?�� IPC —读写 `~/.flowix/agent-access.json`�?//!
-//! �?`commands::settings` 同形: 写操作成功后 emit `agent-access-changed`
-//! 事件, 其它窗口�?React 树收到后从�?盘重�?load�?前�? `set_agent_access`
-//! 走乐观更�?(改本地后�?await), 失败�?store �?`loadInitial` 回滚 ──
-//! 瑙?`app/flowix-web/lib/store/agent-access-store.ts`銆?
-use std::collections::HashMap;
-use std::fs;
-use std::io::Write;
-use std::path::{Path, PathBuf};
-
-use crate::events as dispatcher;
-use tauri::{AppHandle, State};
-
-use crate::config::{AgentAccessConfig, AgentAccessEntry, AgentAccessKind};
-
-use crate::app::state::AppState;
-
-/// 跨窗口同步事�?── 任一窗口成功写入 agent-access.json �?emit, 其它窗口
-/// 收到后从磁盘重新 load�?payload �?`()` (�?payload), 监听者直�?/// `loadInitial()` 拉整�?config ── 比按 entry diff 简单且不会错过任何字�?�?
-pub(super) const AGENT_ACCESS_CHANGED_EVENT: &str = "agent-access-changed";
-
-const NOTEBOOK_AGENT_CONFIG_VERSION: u32 = 1;
-
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct NotebookAddDir {
-    pub id: String,
-    pub path: String,
-    pub label: String,
-    #[serde(default = "default_true")]
-    pub enabled: bool,
-}
-
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct NotebookAgentConfig {
-    pub version: u32,
-    #[serde(default)]
-    pub revision: u64,
-    #[serde(default)]
-    pub add_dirs: Vec<NotebookAddDir>,
-}
-
-impl Default for NotebookAgentConfig {
-    fn default() -> Self {
-        Self {
-            version: NOTEBOOK_AGENT_CONFIG_VERSION,
-            revision: 0,
-            add_dirs: Vec::new(),
-        }
-    }
-}
-
-fn default_true() -> bool {
-    true
-}
-
-fn notebook_agent_path(root: &Path) -> PathBuf {
-    root.join(".flowix").join("agent.json")
-}
-
-fn read_notebook_agent_config(root: &Path) -> Result<Option<NotebookAgentConfig>, String> {
-    let flowix = root.join(".flowix");
-    if fs::symlink_metadata(&flowix)
-        .map(|metadata| metadata.file_type().is_symlink())
-        .unwrap_or(false)
-    {
-        return Err(format!(
-            "Flowix directory is a symbolic link: {}",
-            flowix.display()
-        ));
-    }
-    let path = notebook_agent_path(root);
-    if fs::symlink_metadata(&path)
-        .map(|metadata| metadata.file_type().is_symlink())
-        .unwrap_or(false)
-    {
-        return Err(format!(
-            "Notebook agent config is a symbolic link: {}",
-            path.display()
-        ));
-    }
-    if !path.exists() {
-        return Ok(None);
-    }
-    let content =
-        fs::read_to_string(&path).map_err(|error| format!("read {}: {error}", path.display()))?;
-    let config: NotebookAgentConfig = serde_json::from_str(&content)
-        .map_err(|error| format!("parse {}: {error}", path.display()))?;
-    if config.version != NOTEBOOK_AGENT_CONFIG_VERSION {
-        return Err(format!(
-            "unsupported notebook agent config version {} in {}",
-            config.version,
-            path.display()
-        ));
-    }
-    Ok(Some(config))
-}
-
-fn validate_notebook_agent_config(
-    root: &Path,
-    config: &mut NotebookAgentConfig,
-) -> Result<(), String> {
-    let notebook_canonical = fs::canonicalize(root).map_err(|error| error.to_string())?;
-    let mut seen = std::collections::HashSet::new();
-    for directory in &mut config.add_dirs {
-        directory.path = directory
-            .path
-            .trim()
-            .trim_end_matches(['/', '\\'])
-            .to_string();
-        if directory.path.is_empty()
-            || !Path::new(&directory.path).is_absolute()
-            || !Path::new(&directory.path).is_dir()
-        {
-            return Err(format!("add-dir is unavailable: {}", directory.path));
-        }
-        let canonical = fs::canonicalize(&directory.path).map_err(|error| error.to_string())?;
-        if canonical == notebook_canonical {
-            return Err("the notebook itself cannot be an add-dir".to_string());
-        }
-        if notebook_canonical.starts_with(&canonical) {
-            return Err(format!(
-                "an ancestor of the notebook cannot be an add-dir: {}",
-                directory.path
-            ));
-        }
-        let key = canonical.to_string_lossy().to_lowercase();
-        if !seen.insert(key) {
-            return Err(format!("duplicate add-dir: {}", directory.path));
-        }
-        if directory.id.trim().is_empty() {
-            directory.id = format!("dir_{}", nanoid::nanoid!(8));
-        }
-        if directory.label.trim().is_empty() {
-            directory.label = Path::new(&directory.path)
-                .file_name()
-                .and_then(|value| value.to_str())
-                .unwrap_or(&directory.path)
-                .to_string();
-        }
-    }
-    Ok(())
-}
-
-fn check_notebook_revision(expected: u64, current: u64) -> Result<(), String> {
-    if expected != current {
-        return Err(format!(
-            "notebook agent config conflict: expected revision {expected}, found {current}"
-        ));
-    }
-    Ok(())
-}
-
-fn write_notebook_agent_config(root: &Path, config: &NotebookAgentConfig) -> Result<(), String> {
-    let flowix = root.join(".flowix");
-    if fs::symlink_metadata(&flowix)
-        .map(|metadata| metadata.file_type().is_symlink())
-        .unwrap_or(false)
-    {
-        return Err(format!(
-            "Flowix directory is a symbolic link: {}",
-            flowix.display()
-        ));
-    }
-    fs::create_dir_all(&flowix).map_err(|error| format!("create {}: {error}", flowix.display()))?;
-    let path = notebook_agent_path(root);
-    if fs::symlink_metadata(&path)
-        .map(|metadata| metadata.file_type().is_symlink())
-        .unwrap_or(false)
-    {
-        return Err(format!(
-            "Notebook agent config is a symbolic link: {}",
-            path.display()
-        ));
-    }
-    let temporary = flowix.join("agent.json.tmp");
-    if fs::symlink_metadata(&temporary)
-        .map(|metadata| metadata.file_type().is_symlink())
-        .unwrap_or(false)
-    {
-        return Err(format!(
-            "Notebook agent temporary file is a symbolic link: {}",
-            temporary.display()
-        ));
-    }
-    let content = serde_json::to_vec_pretty(config).map_err(|error| error.to_string())?;
-    {
-        let mut file = fs::OpenOptions::new()
-            .create(true)
-            .truncate(true)
-            .write(true)
-            .open(&temporary)
-            .map_err(|error| format!("open {}: {error}", temporary.display()))?;
-        file.write_all(&content)
-            .and_then(|_| file.sync_all())
-            .map_err(|error| format!("write {}: {error}", temporary.display()))?;
-    }
-    fs::rename(&temporary, &path).map_err(|error| format!("replace {}: {error}", path.display()))
-}
-
-fn legacy_add_dirs(config: &AgentAccessConfig, notebook_id: &str) -> Vec<NotebookAddDir> {
-    let Some(defaults) = config.defaults.as_ref() else {
-        return Vec::new();
-    };
-    let Some(files) = defaults.get("files") else {
-        return Vec::new();
-    };
-    let selected = if files.get("folders").is_some() {
-        files
-    } else {
-        files
-            .get(notebook_id)
-            .or_else(|| files.get("_global"))
-            .unwrap_or(&serde_json::Value::Null)
-    };
-    selected
-        .get("folders")
-        .and_then(serde_json::Value::as_array)
-        .into_iter()
-        .flatten()
-        .filter_map(serde_json::Value::as_str)
-        .map(str::trim)
-        .filter(|path| !path.is_empty())
-        .enumerate()
-        .map(|(index, path)| NotebookAddDir {
-            id: format!("legacy_{}", index + 1),
-            path: path.trim_end_matches(['/', '\\']).to_string(),
-            label: Path::new(path)
-                .file_name()
-                .and_then(|value| value.to_str())
-                .unwrap_or(path)
-                .to_string(),
-            enabled: true,
-        })
-        .collect()
-}
-
-fn load_or_migrate_notebook_agent_config(
-    root: &Path,
-    notebook_id: &str,
-    legacy: &AgentAccessConfig,
-) -> Result<NotebookAgentConfig, String> {
-    if let Some(config) = read_notebook_agent_config(root)? {
-        return Ok(config);
-    }
-    let mut config = NotebookAgentConfig {
-        version: NOTEBOOK_AGENT_CONFIG_VERSION,
-        revision: 1,
-        add_dirs: legacy_add_dirs(legacy, notebook_id),
-    };
-    // Legacy defaults were user-editable JSON and may contain stale or unsafe
-    // paths.  Migrate only entries that pass the same validation as new writes;
-    // never widen access merely because an old file listed a directory.
-    let mut safe_dirs = Vec::with_capacity(config.add_dirs.len());
-    for directory in config.add_dirs.drain(..) {
-        let mut candidate = NotebookAgentConfig {
-            version: config.version,
-            revision: config.revision,
-            add_dirs: vec![directory],
-        };
-        if validate_notebook_agent_config(root, &mut candidate).is_ok() {
-            safe_dirs.extend(candidate.add_dirs);
-        }
-    }
-    config.add_dirs = safe_dirs;
-    write_notebook_agent_config(root, &config)?;
-    Ok(config)
-}
-
-fn remove_legacy_file_defaults(config: &mut AgentAccessConfig) -> bool {
-    let removed = config
-        .defaults
-        .as_mut()
-        .and_then(serde_json::Value::as_object_mut)
-        .and_then(|defaults| defaults.remove("files"))
-        .is_some();
-    if removed
-        && config
-            .defaults
-            .as_ref()
-            .and_then(serde_json::Value::as_object)
-            .is_some_and(|defaults| defaults.is_empty())
-    {
-        config.defaults = None;
-    }
-    removed
-}
-
-#[tauri::command]
-pub fn get_notebook_agent_configs(
-    state: State<AppState>,
-    app: AppHandle,
-) -> Result<HashMap<String, NotebookAgentConfig>, String> {
-    let notebooks = state
-        .memo_file
-        .read()
-        .map_err(|_| "memo file lock poisoned".to_string())?
-        .read_notebook_configs()
-        .map_err(|error| error.to_string())?;
-    let legacy = state.agent_access.get_config();
-    let mut result = HashMap::new();
-    let mut all_notebooks_migrated = true;
-    for notebook in notebooks {
-        let root = PathBuf::from(&notebook.path);
-        if !root.is_dir() {
-            all_notebooks_migrated = false;
-            continue;
-        }
-        let config = load_or_migrate_notebook_agent_config(&root, &notebook.id, &legacy)?;
-        result.insert(notebook.id, config);
-    }
-    // Once every registered, existing notebook has a local config, remove the
-    // obsolete global files defaults. Runtime defaults remain untouched. This
-    // is deliberately skipped when a notebook path is unavailable so a
-    // partially migrated installation keeps its rollback source.
-    if all_notebooks_migrated && !result.is_empty() {
-        let mut cleaned = legacy.clone();
-        let removed = remove_legacy_file_defaults(&mut cleaned);
-        if removed {
-            state
-                .agent_access
-                .replace_config(cleaned)
-                .map_err(|error| format!("remove legacy file defaults: {error}"))?;
-            dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
-        }
-    }
-    Ok(result)
-}
-
-#[tauri::command]
-pub fn set_notebook_agent_config(
-    notebook_id: String,
-    expected_revision: u64,
-    mut config: NotebookAgentConfig,
-    state: State<AppState>,
-    app: AppHandle,
-) -> Result<NotebookAgentConfig, String> {
-    let notebook = state
-        .memo_file
-        .read()
-        .map_err(|_| "memo file lock poisoned".to_string())?
-        .get_notebook_config_by_id(&notebook_id)
-        .ok_or_else(|| format!("notebook not found: {notebook_id}"))?;
-    let root = PathBuf::from(notebook.path);
-    let current = read_notebook_agent_config(&root)?.unwrap_or_default();
-    check_notebook_revision(expected_revision, current.revision)?;
-    config.version = NOTEBOOK_AGENT_CONFIG_VERSION;
-    config.revision = current.revision.saturating_add(1);
-    validate_notebook_agent_config(&root, &mut config)?;
-    write_notebook_agent_config(&root, &config)?;
-    dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
-    Ok(config)
-}
-
-/// 拉取当前 agent_access 整份 config�?每�?都从 store �? `missing` 字�?
-/// �?`get_config` 内重新算, 失联�?��会立刻拿到最�?disk 状态�?
-#[tauri::command]
-pub fn get_agent_access(state: State<AppState>) -> AgentAccessConfig {
-    state.agent_access.get_config()
-}
-
-/// 用整份新 config 覆盖 (前�?走乐观更�? 整份 set 避免一�?IPC 一份的
-/// 复杂协�?)�?先落�? �?emit, 成功才更新内�?(�?user_config �?set
-/// �?��完全对齐)�?
-#[tauri::command]
-pub fn set_agent_access(
-    config: AgentAccessConfig,
-    state: State<AppState>,
-    app: AppHandle,
-) -> Result<(), String> {
-    state
-        .agent_access
-        .replace_config(config)
-        .map(|_| {
-            dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
-            Ok(())
-        })
-        .map_err(|e| e.to_string())?
-}
-
-#[tauri::command]
-pub async fn add_agent_access_folder_from_picker(
-    app: AppHandle,
-    state: State<'_, AppState>,
-) -> Result<Option<AgentAccessEntry>, String> {
-    let picked = crate::commands::dialog::select_directory(app.clone()).await;
-    let Some(path) = picked else {
-        return Ok(None);
-    };
-    let trimmed = path.trim_end_matches(|c| c == '/' || c == '\\').to_string();
-    if trimmed.is_empty() {
-        return Ok(None);
-    }
-
-    let mut config = state.agent_access.get_config();
-    if let Some(existing) = reusable_tracked_folder(&config, &trimmed)? {
-        // Folder entries form a global metadata/bookmark pool while
-        // notebook `.flowix/agent.json` owns per-notebook attachments.
-        // Returning the existing folder lets a removed folder be attached
-        // again and lets multiple notebooks reference the same directory.
-        return Ok(Some(existing));
-    }
-
-    let now = chrono::Utc::now().timestamp_millis();
-    let name = Path::new(&trimmed)
-        .file_name()
-        .and_then(|value| value.to_str())
-        .unwrap_or(&trimmed)
-        .to_string();
-    let entry = AgentAccessEntry {
-        id: format!("fld_{}", nanoid::nanoid!(6)),
-        kind: AgentAccessKind::Folder,
-        path: trimmed,
-        name,
-        enabled: true,
-        workspace: false,
-        added_at: now,
-        updated_at: now,
-        missing: false,
-    };
-    config.entries.push(entry.clone());
-    state
-        .agent_access
-        .replace_config(config)
-        .map_err(|e| format!("agent access persist failed: {e}"))?;
-    dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
-    Ok(Some(entry))
-}
-
-#[cfg(test)]
-mod notebook_agent_tests {
-    use super::*;
-
-    fn legacy_with_folder(path: &str) -> AgentAccessConfig {
-        AgentAccessConfig {
-            version: 1,
-            entries: Vec::new(),
-            defaults: Some(serde_json::json!({
-                "files": { "folders": [path] }
-            })),
-        }
-    }
-
-    #[test]
-    fn migrates_legacy_defaults_into_notebook_config() {
-        let temp = tempfile::tempdir().unwrap();
-        let notebook = temp.path().join("notebook");
-        let add_dir = temp.path().join("资料");
-        fs::create_dir_all(&notebook).unwrap();
-        fs::create_dir_all(&add_dir).unwrap();
-        let config = load_or_migrate_notebook_agent_config(
-            &notebook,
-            "nb-1",
-            &legacy_with_folder(add_dir.to_str().unwrap()),
-        )
-        .unwrap();
-        assert_eq!(config.revision, 1);
-        assert_eq!(config.add_dirs.len(), 1);
-        assert_eq!(config.add_dirs[0].path, add_dir.to_string_lossy());
-        assert!(notebook.join(".flowix/agent.json").is_file());
-    }
-
-    #[test]
-    fn migration_skips_unsafe_legacy_paths() {
-        let temp = tempfile::tempdir().unwrap();
-        let notebook = temp.path().join("notebook");
-        let safe = temp.path().join("资料");
-        fs::create_dir_all(&notebook).unwrap();
-        fs::create_dir_all(&safe).unwrap();
-        let legacy = AgentAccessConfig {
-            version: 1,
-            entries: Vec::new(),
-            defaults: Some(serde_json::json!({
-                "files": { "folders": [notebook, safe] }
-            })),
-        };
-        let config = load_or_migrate_notebook_agent_config(&notebook, "nb-1", &legacy).unwrap();
-        assert_eq!(config.add_dirs.len(), 1);
-        assert_eq!(config.add_dirs[0].path, safe.to_string_lossy());
-    }
-
-    #[test]
-    fn removes_only_legacy_file_defaults_and_keeps_runtime_defaults() {
-        let mut config = AgentAccessConfig {
-            version: 1,
-            entries: Vec::new(),
-            defaults: Some(serde_json::json!({
-                "files": { "folders": ["/old"] },
-                "runtime": { "codex": { "model": { "key": "gpt" } } }
-            })),
-        };
-        assert!(remove_legacy_file_defaults(&mut config));
-        let defaults = config.defaults.unwrap();
-        assert!(defaults.get("files").is_none());
-        assert!(defaults.get("runtime").is_some());
-    }
-
-    #[test]
-    fn rejects_notebook_and_ancestor_add_dirs() {
-        let temp = tempfile::tempdir().unwrap();
-        let notebook = temp.path().join("root/notebook");
-        fs::create_dir_all(&notebook).unwrap();
-        for path in [&notebook, notebook.parent().unwrap()] {
-            let mut config = NotebookAgentConfig::default();
-            config.add_dirs.push(NotebookAddDir {
-                id: "x".into(),
-                path: path.to_string_lossy().into_owned(),
-                label: String::new(),
-                enabled: true,
-            });
-            let error = validate_notebook_agent_config(&notebook, &mut config).unwrap_err();
-            assert!(error.contains("cannot be an add-dir"));
-        }
-    }
-
-    #[test]
-    fn rejects_duplicate_add_dirs_and_revision_is_detected_before_write() {
-        let temp = tempfile::tempdir().unwrap();
-        let notebook = temp.path().join("notebook");
-        let add_dir = temp.path().join("资料");
-        fs::create_dir_all(&notebook).unwrap();
-        fs::create_dir_all(&add_dir).unwrap();
-        let mut config = NotebookAgentConfig::default();
-        config.add_dirs = vec![
-            NotebookAddDir {
-                id: "a".into(),
-                path: add_dir.to_string_lossy().into_owned(),
-                label: String::new(),
-                enabled: true,
-            },
-            NotebookAddDir {
-                id: "b".into(),
-                path: add_dir.to_string_lossy().into_owned(),
-                label: String::new(),
-                enabled: true,
-            },
-        ];
-        assert!(validate_notebook_agent_config(&notebook, &mut config)
-            .unwrap_err()
-            .contains("duplicate add-dir"));
-        let persisted = NotebookAgentConfig {
-            revision: 3,
-            ..Default::default()
-        };
-        write_notebook_agent_config(&notebook, &persisted).unwrap();
-        let current = read_notebook_agent_config(&notebook).unwrap().unwrap();
-        let error = check_notebook_revision(2, current.revision).unwrap_err();
-        assert!(error.contains("conflict"));
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn rejects_symlink_flowix_directory() {
-        let temp = tempfile::tempdir().unwrap();
-        let notebook = temp.path().join("notebook");
-        let target = temp.path().join("target");
-        fs::create_dir_all(&notebook).unwrap();
-        fs::create_dir_all(&target).unwrap();
-        std::os::unix::fs::symlink(&target, notebook.join(".flowix")).unwrap();
-        let error =
-            write_notebook_agent_config(&notebook, &NotebookAgentConfig::default()).unwrap_err();
-        assert!(error.contains("symbolic link"));
-    }
-}
-
-fn reusable_tracked_folder(
-    config: &AgentAccessConfig,
-    path: &str,
-) -> Result<Option<AgentAccessEntry>, String> {
-    let comparable = path
-        .trim_end_matches(|c| c == '/' || c == '\\')
-        .to_ascii_lowercase();
-    let Some(existing) = config.entries.iter().find(|entry| {
-        entry
-            .path
-            .trim_end_matches(|c| c == '/' || c == '\\')
-            .to_ascii_lowercase()
-            == comparable
-    }) else {
-        return Ok(None);
-    };
-    if existing.kind == AgentAccessKind::Folder {
-        Ok(Some(existing.clone()))
-    } else {
-        Err("path already tracked as notebook".to_string())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn entry(kind: AgentAccessKind, path: &str) -> AgentAccessEntry {
-        AgentAccessEntry {
-            id: "entry".to_string(),
-            kind,
-            path: path.to_string(),
-            name: "Entry".to_string(),
-            enabled: true,
-            workspace: false,
-            added_at: 1,
-            updated_at: 1,
-            missing: false,
-        }
-    }
-
-    #[test]
-    fn existing_folder_is_reusable_across_notebooks_and_after_removal() {
-        let config = AgentAccessConfig {
-            version: 1,
-            entries: vec![entry(AgentAccessKind::Folder, "/tmp/reference")],
-            defaults: None,
-        };
-
-        let reused = reusable_tracked_folder(&config, "/tmp/reference/")
-            .unwrap()
-            .expect("folder should be reused");
-
-        assert_eq!(reused.path, "/tmp/reference");
-    }
-
-    #[test]
-    fn notebook_path_is_not_reused_as_folder_metadata() {
-        let config = AgentAccessConfig {
-            version: 1,
-            entries: vec![entry(AgentAccessKind::Notebook, "/tmp/notebook")],
-            defaults: None,
-        };
-
-        assert!(reusable_tracked_folder(&config, "/tmp/notebook").is_err());
-    }
-}
diff --git a/app/flowix-desktop/src/commands/agent_workspace.rs b/app/flowix-desktop/src/commands/agent_workspace.rs
new file mode 100644
index 000000000..61c4edd1c
--- /dev/null
+++ b/app/flowix-desktop/src/commands/agent_workspace.rs
@@ -0,0 +1,87 @@
+//! Notebook workspace IPC. All active data is stored in db/local.db.
+use crate::{app::state::AppState, events as dispatcher};
+use flowix_core::memo_file::NotebookWorkspaceSnapshot;
+use tauri::{AppHandle, State};
+
+pub(crate) const AGENT_WORKSPACE_CHANGED_EVENT: &str = "agent-workspace-changed";
+
+#[tauri::command]
+pub fn get_agent_workspace(state: State<AppState>) -> Result<NotebookWorkspaceSnapshot, String> {
+    state
+        .memo_file
+        .read()
+        .map_err(|_| "memo file lock poisoned".to_string())?
+        .read_notebook_workspace()
+        .map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+pub fn get_legacy_agent_preferences(
+    state: State<AppState>,
+) -> Result<Option<serde_json::Value>, String> {
+    state
+        .memo_file
+        .read()
+        .map_err(|_| "memo file lock poisoned".to_string())?
+        .read_legacy_agent_runtime()
+        .map_err(|e| e.to_string())
+}
+
+#[tauri::command]
+pub fn attach_notebook_directory(
+    notebook_id: String,
+    path: String,
+    state: State<AppState>,
+    app: AppHandle,
+) -> Result<NotebookWorkspaceSnapshot, String> {
+    update(&state, &app, &notebook_id, &path, true)
+}
+
+#[tauri::command]
+pub fn detach_notebook_directory(
+    notebook_id: String,
+    path: String,
+    state: State<AppState>,
+    app: AppHandle,
+) -> Result<NotebookWorkspaceSnapshot, String> {
+    update(&state, &app, &notebook_id, &path, false)
+}
+
+#[tauri::command]
+pub async fn pick_notebook_directory(
+    notebook_id: String,
+    state: State<'_, AppState>,
+    app: AppHandle,
+) -> Result<Option<NotebookWorkspaceSnapshot>, String> {
+    // Reject an invalid scope before showing a picker or creating any state.
+    if state
+        .memo_file
+        .read()
+        .map_err(|_| "memo file lock poisoned")?
+        .get_notebook_config_by_id(&notebook_id)
+        .is_none()
+    {
+        return Err("notebook not found".into());
+    }
+    let Some(path) = super::dialog::select_directory(app.clone()).await else {
+        return Ok(None);
+    };
+    update(&state, &app, &notebook_id, &path, true).map(Some)
+}
+
+fn update(
+    state: &AppState,
+    app: &AppHandle,
+    notebook_id: &str,
+    path: &str,
+    attach: bool,
+) -> Result<NotebookWorkspaceSnapshot, String> {
+    let snapshot = state
+        .memo_file
+        .read()
+        .map_err(|_| "memo file lock poisoned")?
+        .update_notebook_add_dir(notebook_id, path, attach)
+        .map_err(|e| e.to_string())?;
+    dispatcher::emit_to(app, AGENT_WORKSPACE_CHANGED_EVENT, ());
+    Ok(snapshot)
+}
diff --git a/app/flowix-desktop/src/commands/artifact.rs b/app/flowix-desktop/src/commands/artifact.rs
index edaa2af41..23124aa8b 100644
--- a/app/flowix-desktop/src/commands/artifact.rs
+++ b/app/flowix-desktop/src/commands/artifact.rs
@@ -7,8 +7,8 @@ use crate::app::state::AppState;
 /// can be removed while its artifact remains a readable notebook document.
 #[tauri::command]
 pub fn artifact_resolve(
-    memo_id: String,
+    note_path: String,
     state: State<AppState>,
 ) -> Result<crate::artifact::ArtifactSession, String> {
-    crate::artifact::resolve(&memo_id, &state.memo_file)
+    crate::artifact::resolve(&note_path, &state.memo_file)
 }
diff --git a/app/flowix-desktop/src/commands/boot.rs b/app/flowix-desktop/src/commands/boot.rs
index 659283e0a..308beac92 100644
--- a/app/flowix-desktop/src/commands/boot.rs
+++ b/app/flowix-desktop/src/commands/boot.rs
@@ -2,7 +2,7 @@ use serde::Serialize;
 use std::sync::Arc;
 use tauri::{Manager, State};
 
-use crate::app::startup::StartupStatus;
+use crate::app::startup::{StartupPhase, StartupStatus};
 use crate::app::state::AppState;
 use crate::device_registration::DeviceRegistry;
 
@@ -11,7 +11,6 @@ use crate::device_registration::DeviceRegistry;
 pub struct BootFeatures {
     pub experimental: bool,
     pub is_introduct_displayed: bool,
-    pub is_onboarding_completed: bool,
 }
 
 #[tauri::command]
@@ -19,7 +18,6 @@ pub fn get_boot_features(registry: State<'_, Arc<DeviceRegistry>>) -> BootFeatur
     BootFeatures {
         experimental: registry.experimental(),
         is_introduct_displayed: registry.is_introduct_displayed(),
-        is_onboarding_completed: registry.is_onboarding_completed(),
     }
 }
 
@@ -29,10 +27,35 @@ pub fn set_boot_intro_displayed(registry: State<'_, Arc<DeviceRegistry>>) -> Res
 }
 
 #[tauri::command]
-pub fn set_boot_onboarding_completed(
+pub fn get_version_initialization_completed(
     registry: State<'_, Arc<DeviceRegistry>>,
+) -> Result<bool, String> {
+    if !crate::commands::product::is_dev_build() {
+        return Err(
+            "version initialization settings are only available in a development build".to_string(),
+        );
+    }
+    Ok(registry.is_version_initialization_complete())
+}
+
+#[tauri::command]
+pub fn set_version_initialization_completed(
+    completed: bool,
+    registry: State<'_, Arc<DeviceRegistry>>,
+    state: State<'_, AppState>,
 ) -> Result<(), String> {
-    registry.set_onboarding_completed(true)
+    if !crate::commands::product::is_dev_build() {
+        return Err(
+            "version initialization settings are only available in a development build".to_string(),
+        );
+    }
+    if matches!(
+        state.startup.status().phase,
+        StartupPhase::Pending | StartupPhase::Running
+    ) {
+        return Err("version initialization cannot be edited while startup is running".to_string());
+    }
+    registry.set_version_initialization_completed(completed)
 }
 
 #[tauri::command]
@@ -60,15 +83,20 @@ pub fn record_startup_stage(
     const ALLOWED: &[&str] = &[
         "native-ready",
         "notebook-selected",
-        "first-memo-query-ready",
-        "workspace-restored",
-        "initial-document-settled",
-        "initial-document-skipped",
-        "initial-document-superseded",
-        "initial-document-timeout",
         "first-workspace-paint",
+        "stage3-admitted",
+        "workspace-restore-settled",
+        "workspace-restore-superseded",
+        "foreground-degraded-paint",
+        "foreground-failed-paint",
     ];
-    if !ALLOWED.contains(&stage.as_str()) {
+    // Keep task-event identifiers bounded; task IDs contain only ASCII letters
+    // and separators.
+    let task_event = stage.starts_with("task:")
+        && stage.len() <= 96
+        && stage.bytes().all(|b| b.is_ascii_alphanumeric() || b"-_:".contains(&b))
+        && [":start", ":complete", ":failed"].iter().any(|suffix| stage.ends_with(*suffix));
+    if !ALLOWED.contains(&stage.as_str()) && !task_event {
         return;
     }
     if startup_attempt_id.len() > 64 || !startup_attempt_id.is_ascii() {
@@ -94,3 +122,8 @@ pub async fn wait_for_startup_ready(app: tauri::AppHandle) -> Result<(), String>
         .await
         .map_err(|error| format!("startup wait task failed: {error}"))?
 }
+
+#[tauri::command]
+pub fn retry_startup(state: State<'_, AppState>) -> Result<(), String> {
+    state.startup.request_retry()
+}
diff --git a/app/flowix-desktop/src/commands/cloud.rs b/app/flowix-desktop/src/commands/cloud.rs
index e22840277..964846f2a 100644
--- a/app/flowix-desktop/src/commands/cloud.rs
+++ b/app/flowix-desktop/src/commands/cloud.rs
@@ -1,39 +1,35 @@
 use std::collections::{HashMap, HashSet};
 mod coordinator;
 mod deletion;
-mod local_adapter;
 mod google_login;
-use google_login::PendingGoogleLogin;
-pub(crate) use google_login::GoogleCallback;
+mod local_adapter;
 pub(crate) use coordinator::{
     schedule_notebook_sync, schedule_notebook_sync_observation, start_cloud_sync_polling,
 };
+pub(crate) use google_login::GoogleCallback;
+use google_login::PendingGoogleLogin;
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
 use std::sync::{Arc, Mutex, OnceLock};
 use std::time::Duration;
 
 use chrono::Utc;
-use flowix_core::memo_file::{
-    notebook_path_from_relative, IsMd,
-};
+use flowix_core::memo_file::{notebook_path_from_relative, notebook_relative_path, IsMd};
 use flowix_sync::{
-    v2_content_hash, v2_local_content_diverged, CloudCheckout,
-    CloudMembership, CloudNotebook, CloudProduct, CloudState, SyncError, V2AccountSyncReport,
-    V2LocalNote, V2LocalNotebook, V2RemoteApply, V2SyncedNotebook,
+    v2_content_hash, v2_local_content_diverged, CloudAiCreditBalance, CloudCheckout,
+    CloudMembership, CloudNotebook, CloudOrder, CloudOrderCheck, CloudProduct, CloudState,
+    SyncError, V2AccountSyncReport, V2LocalNote, V2LocalNotebook, V2RemoteApply, V2SyncedNotebook,
 };
+use once_cell::sync::Lazy;
 use serde::Serialize;
 use tauri::{AppHandle, Emitter, Manager, State, WebviewWindow};
 use tokio::sync::{mpsc, oneshot};
 use tokio::time::Instant;
-use once_cell::sync::Lazy;
 
-static GOOGLE_OAUTH_LOGIN: Lazy<Mutex<Option<PendingGoogleLogin>>> =
-    Lazy::new(|| Mutex::new(None));
+static GOOGLE_OAUTH_LOGIN: Lazy<Mutex<Option<PendingGoogleLogin>>> = Lazy::new(|| Mutex::new(None));
 
 use crate::app::state::AppState;
 use crate::lock_utils::read_lock;
-use crate::memo_events::{self, MemoChangeSource, MemoDerivedChanged, MemoEvent};
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -163,21 +159,36 @@ pub async fn cloud_start_google_sign_in(app: AppHandle) -> Result<(), String> {
     use base64::Engine;
     use sha2::{Digest, Sha256};
 
-    let generation = app.state::<AppState>().cloud_sync.begin_google_sign_in();
-    let state = format!("{}{}", uuid::Uuid::new_v4().simple(), uuid::Uuid::new_v4().simple());
-    let code_verifier = format!("{}{}", uuid::Uuid::new_v4().simple(), uuid::Uuid::new_v4().simple());
+    let app_state = app.state::<AppState>();
+    let generation = app_state.cloud_sync.begin_google_sign_in();
+    let cloud_api_base = app_state.cloud_environment.api_base();
+    let state = format!(
+        "{}{}",
+        uuid::Uuid::new_v4().simple(),
+        uuid::Uuid::new_v4().simple()
+    );
+    let code_verifier = format!(
+        "{}{}",
+        uuid::Uuid::new_v4().simple(),
+        uuid::Uuid::new_v4().simple()
+    );
     let code_challenge = URL_SAFE_NO_PAD.encode(Sha256::digest(code_verifier.as_bytes()));
     {
-        *GOOGLE_OAUTH_LOGIN.lock().unwrap_or_else(|p| p.into_inner()) =
-            Some(PendingGoogleLogin::new(state.clone(), code_verifier, generation));
-    }
-    let mut url = url::Url::parse(&format!(
-        "{}/v1/auth/google/start",
-        flowix_sync::DEFAULT_CLOUD_API_BASE
-    ))
-    .map_err(|error| error.to_string())?;
+        *GOOGLE_OAUTH_LOGIN.lock().unwrap_or_else(|p| p.into_inner()) = Some(
+            PendingGoogleLogin::new(state.clone(), code_verifier, generation),
+        );
+    }
+    let mut url = url::Url::parse(&format!("{cloud_api_base}/v1/auth/google/start"))
+        .map_err(|error| error.to_string())?;
     url.query_pairs_mut()
-        .append_pair("mode", if option_env!("FLOWIX_DEV_MODE") == Some("1") { "desktop-dev" } else { "desktop" })
+        .append_pair(
+            "mode",
+            if option_env!("FLOWIX_DEV_MODE") == Some("1") {
+                "desktop-dev"
+            } else {
+                "desktop"
+            },
+        )
         .append_pair("state", &state)
         .append_pair("code_challenge", &code_challenge);
     app.opener()
@@ -190,7 +201,10 @@ pub(crate) async fn complete_google_deep_link(
     callback: GoogleCallback,
 ) -> Result<(), String> {
     match callback {
-        GoogleCallback::Success { code, state: oauth_state } => {
+        GoogleCallback::Success {
+            code,
+            state: oauth_state,
+        } => {
             let claimed = {
                 let mut pending = GOOGLE_OAUTH_LOGIN.lock().unwrap_or_else(|p| p.into_inner());
                 let attempt = pending.as_mut().ok_or_else(|| {
@@ -198,21 +212,42 @@ pub(crate) async fn complete_google_deep_link(
                 })?;
                 attempt.claim(&oauth_state).map_err(str::to_string)?
             };
-            let Some((code_verifier, generation)) = claimed else { return Ok(()); };
-            let state = app.state::<AppState>();
-            state.cloud_sync
+            let Some((code_verifier, generation)) = claimed else {
+                return Ok(());
+            };
+            let app_state = app.state::<AppState>();
+            app_state
+                .cloud_sync
                 .sign_in_with_google_desktop(&code, &oauth_state, &code_verifier, generation)
                 .await
-                .map_err(sync_error)
-                .map(|_| ())
+                .map_err(sync_error)?;
+            if let Err(error) = crate::commands::window::open_preferences_window_inner(
+                &app,
+                &app_state,
+                Some("cloudSync"),
+            ) {
+                tracing::warn!(
+                    "Google sign-in succeeded but account preferences could not open: {error}"
+                );
+            }
+            Ok(())
         }
-        GoogleCallback::Failure { error, state: oauth_state } => {
+        GoogleCallback::Failure {
+            error,
+            state: oauth_state,
+        } => {
             let accepted = {
                 let mut pending = GOOGLE_OAUTH_LOGIN.lock().unwrap_or_else(|p| p.into_inner());
-                let Some(attempt) = pending.as_mut() else { return Ok(()); };
-                attempt.claim_failure(&oauth_state).map_err(str::to_string)?
+                let Some(attempt) = pending.as_mut() else {
+                    return Ok(());
+                };
+                attempt
+                    .claim_failure(&oauth_state)
+                    .map_err(str::to_string)?
             };
-            if accepted { let _ = app.emit("cloud-google-auth-error", error); }
+            if accepted {
+                let _ = app.emit("cloud-google-auth-error", error);
+            }
             Ok(())
         }
     }
@@ -239,11 +274,28 @@ pub async fn cloud_link_apple(
 
 #[tauri::command]
 pub async fn cloud_logout(
+    app: AppHandle,
     state: State<'_, AppState>,
 ) -> Result<CloudState, String> {
-    let logout_result = state.cloud_sync.logout().await.map_err(sync_error);
-    let next_state = state.cloud_sync.state().map_err(sync_error)?;
-    logout_result?;
+    let pi = state.pi.clone();
+    let api_base = state.cloud_environment.api_base().to_string();
+    let pending_logout = state.cloud_sync.begin_logout();
+    let logout_generation = state.cloud_sync.ai_credential_session_generation();
+    let next_state = state.cloud_sync.state().map_err(sync_error);
+    let pi_cleanup = async {
+        match &next_state {
+            Ok(next_state) if !next_state.authenticated => {
+                pi.disconnect_cloud_model_provider(&app, &api_base, logout_generation)
+                    .await
+            }
+            _ => Ok(()),
+        }
+    };
+    let logout = state.cloud_sync.finish_logout(pending_logout);
+    let (pi_cleanup, logout_result) = tokio::join!(pi_cleanup, logout);
+    let next_state = next_state?;
+    pi_cleanup?;
+    logout_result.map_err(sync_error)?;
     Ok(next_state)
 }
 
@@ -344,11 +396,71 @@ pub async fn cloud_refresh_membership(
     membership_result.map_err(sync_error)
 }
 
+#[tauri::command]
+pub async fn cloud_ai_credit_balance(
+    state: State<'_, AppState>,
+) -> Result<CloudAiCreditBalance, String> {
+    state
+        .cloud_sync
+        .ai_credit_balance()
+        .await
+        .map_err(sync_error)
+}
+
+#[tauri::command]
+pub async fn cloud_connect_pi_model_provider(
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let api_base = state.cloud_environment.api_base().trim_end_matches('/');
+    state.pi.connect_cloud_model_provider(&app, api_base).await
+}
+
+#[tauri::command]
+pub async fn cloud_refresh_pi_model_provider_at_startup(
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<bool, String> {
+    let api_base = state.cloud_environment.api_base().trim_end_matches('/');
+    state
+        .pi
+        .refresh_cloud_model_provider_at_startup(&app, api_base)
+        .await
+}
+
+#[tauri::command]
+pub async fn cloud_refresh_pi_model_provider(
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<bool, String> {
+    let api_base = state.cloud_environment.api_base().trim_end_matches('/');
+    state.pi.refresh_cloud_model_provider(&app, api_base).await
+}
+
 #[tauri::command]
 pub async fn cloud_list_products(state: State<'_, AppState>) -> Result<Vec<CloudProduct>, String> {
     state.cloud_sync.products().await.map_err(sync_error)
 }
 
+#[tauri::command]
+pub async fn cloud_list_billing_orders(
+    state: State<'_, AppState>,
+) -> Result<Vec<CloudOrder>, String> {
+    state.cloud_sync.billing_orders().await.map_err(sync_error)
+}
+
+#[tauri::command]
+pub async fn cloud_check_billing_order(
+    order_id: String,
+    state: State<'_, AppState>,
+) -> Result<CloudOrderCheck, String> {
+    state
+        .cloud_sync
+        .check_billing_order(&order_id)
+        .await
+        .map_err(sync_error)
+}
+
 #[tauri::command]
 pub async fn cloud_create_checkout(
     product_id: String,
@@ -362,6 +474,30 @@ pub async fn cloud_create_checkout(
     checkout_result.map_err(sync_error)
 }
 
+#[tauri::command]
+pub async fn cloud_submit_feedback(
+    device_id: String,
+    kind: String,
+    content: String,
+    app_version: String,
+    platform: String,
+    attachments: Vec<serde_json::Value>,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    state
+        .cloud_sync
+        .submit_feedback(
+            &device_id,
+            &kind,
+            &content,
+            &app_version,
+            &platform,
+            &attachments,
+        )
+        .await
+        .map_err(sync_error)
+}
+
 #[tauri::command]
 pub async fn cloud_sync_now(
     notebook_id: Option<String>,
@@ -377,7 +513,11 @@ pub async fn cloud_note_history(
     state: State<'_, AppState>,
 ) -> Result<flowix_sync::V2History, String> {
     let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
-    let history = state.cloud_sync.v2_history(&note_id).await.map_err(sync_error)?;
+    let history = state
+        .cloud_sync
+        .v2_history(&note_id)
+        .await
+        .map_err(sync_error)?;
     if history.notebook_id != notebook_id || history.note_id != note_id {
         return Err("CLOUD_HISTORY_ID_MISMATCH".into());
     }
@@ -400,8 +540,12 @@ pub fn restore_local_path_version(
     state: State<'_, AppState>,
 ) -> Result<(), String> {
     let memo_file = read_lock(&state.memo_file, "memo_file");
-    let _guard = memo_file.operation_locks().notebook_change(&[&notebook_id], "restore_local_path_version").map_err(sync_error)?;
-    let notebook = memo_file.get_notebook_config_by_id(&notebook_id)
+    let _guard = memo_file
+        .operation_locks()
+        .notebook_change(&[&notebook_id], "restore_local_path_version")
+        .map_err(sync_error)?;
+    let notebook = memo_file
+        .get_notebook_config_by_id(&notebook_id)
         .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
     let root = Path::new(&notebook.path);
     let attachment = relative_path.starts_with("attachments/");
@@ -409,7 +553,8 @@ pub fn restore_local_path_version(
         return Err("CLOUD_HISTORY_INVALID_PATH".into());
     }
     let path = local_adapter::safe_cloud_file_path(root, &relative_path, attachment)?;
-    let target = memo_file.read_path_version_bytes(&notebook_id, &relative_path, &version_id)
+    let target = memo_file
+        .read_path_version_bytes(&notebook_id, &relative_path, &version_id)
         .ok_or_else(|| "CLOUD_HISTORY_VERSION_NOT_FOUND".to_string())?;
     if !attachment && std::str::from_utf8(&target).is_err() {
         return Err("CLOUD_HISTORY_INVALID_MARKDOWN".into());
@@ -419,26 +564,44 @@ pub fn restore_local_path_version(
         Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
         Err(error) => return Err(sync_error(error)),
     };
-    if current.as_deref() == Some(target.as_slice()) { return Ok(()); }
+    if current.as_deref() == Some(target.as_slice()) {
+        return Ok(());
+    }
     if let Some(bytes) = current.as_deref() {
-        memo_file.create_path_version_bytes(
-            &notebook_id, &relative_path, bytes,
-            flowix_core::memo_file::MemoVersionSource::RestoreBackup,
-        ).map_err(sync_error)?;
+        memo_file
+            .create_path_version_bytes(
+                &notebook_id,
+                &relative_path,
+                bytes,
+                flowix_core::memo_file::MemoVersionSource::RestoreBackup,
+            )
+            .map_err(sync_error)?;
+    }
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).map_err(sync_error)?;
     }
-    if let Some(parent) = path.parent() { std::fs::create_dir_all(parent).map_err(sync_error)?; }
     let fallback = local_adapter::cloud_conflict_copy_path(&path, &format!("restore-{version_id}"));
     match local_adapter::safely_replace_cloud_file(
-        &path, current.as_deref(), &target, &format!("restore-{version_id}"), &fallback,
+        &path,
+        current.as_deref(),
+        &target,
+        &format!("restore-{version_id}"),
+        &fallback,
     )? {
-        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {},
+        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {}
         outcome => {
             let preserved = match outcome {
                 local_adapter::ConflictFileOutcome::Applied { preserved }
                 | local_adapter::ConflictFileOutcome::Interrupted { preserved } => preserved,
             };
             if let Some(preserved) = preserved {
-                local_adapter::register_preserved_conflict_copy(&memo_file, &notebook_id, root, &preserved, attachment)?;
+                local_adapter::register_preserved_conflict_copy(
+                    &memo_file,
+                    &notebook_id,
+                    root,
+                    &preserved,
+                    attachment,
+                )?;
             }
             return Err("CLOUD_HISTORY_LOCAL_CHANGED".into());
         }
@@ -448,16 +611,22 @@ pub fn restore_local_path_version(
     // or media refresh below fails after the watcher self-write marker.
     schedule_notebook_sync_observation(app.clone(), notebook_id.clone(), true);
     if attachment {
-        memo_file.refresh_media_resource_path(&notebook_id, &relative_path).map_err(sync_error)?;
-        let _ = app.emit("media-properties-changed", serde_json::json!({ "notebookId": notebook_id }));
+        memo_file
+            .refresh_media_resource_path(&notebook_id, &relative_path)
+            .map_err(sync_error)?;
+        let _ = app.emit(
+            "media-properties-changed",
+            serde_json::json!({ "notebookId": notebook_id }),
+        );
     } else {
-        let updated = memo_file.register_existing_file_for_notebook_id(&notebook_id, &path).map_err(sync_error)?;
-        memo_events::emit(&app, MemoEvent::Updated {
-            id: updated.id.clone(), path: path.to_string_lossy().into_owned(),
-            notebook_id: notebook_id.clone(),
-            derived_changed: MemoDerivedChanged { tags: true, todos: true, agents: true },
-            memo: updated, source: MemoChangeSource::CloudSync,
-        });
+        memo_file
+            .refresh_note_path(&notebook_id, &relative_path)
+            .map_err(sync_error)?;
+        crate::commands::path_change::NotebookPathInvalidated::new(
+            notebook_id.clone(),
+            relative_path.clone(),
+        )
+        .emit(&app);
     }
     Ok(())
 }
@@ -474,11 +643,17 @@ pub async fn cloud_preview_note_revision(
         return Err("CLOUD_PREVIEW_MARKDOWN_ONLY".into());
     }
     let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
-    let (history, bytes) = state.cloud_sync.v2_historical_bytes(&note_id, &revision).await.map_err(sync_error)?;
+    let (history, bytes) = state
+        .cloud_sync
+        .v2_historical_bytes(&note_id, &revision)
+        .await
+        .map_err(sync_error)?;
     if history.notebook_id != notebook_id || history.note_id != note_id {
         return Err("CLOUD_HISTORY_ID_MISMATCH".into());
     }
-    if bytes.len() > 2 * 1024 * 1024 { return Err("CLOUD_PREVIEW_TOO_LARGE".into()); }
+    if bytes.len() > 2 * 1024 * 1024 {
+        return Err("CLOUD_PREVIEW_TOO_LARGE".into());
+    }
     String::from_utf8(bytes).map_err(|_| "CLOUD_PREVIEW_NOT_UTF8".into())
 }
 
@@ -488,19 +663,34 @@ pub fn cloud_list_conflicts(
     state: State<'_, AppState>,
 ) -> Result<Vec<String>, String> {
     let memo_file = read_lock(&state.memo_file, "memo_file");
-    let notebook = memo_file.get_notebook_config_by_id(&notebook_id)
+    let notebook = memo_file
+        .get_notebook_config_by_id(&notebook_id)
         .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
-    let mut paths: Vec<String> = memo_file.read_all_memos_for_notebook_id(Some(&notebook_id))
+    let notes = match memo_file.read_note_entries(&notebook_id) {
+        Ok(notes) => notes,
+        Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+            memo_file
+                .reconcile_note_index_blocking(&notebook_id)
+                .map_err(|error| error.to_string())?;
+            memo_file
+                .read_note_entries(&notebook_id)
+                .map_err(|error| error.to_string())?
+        }
+        Err(error) => return Err(error.to_string()),
+    };
+    let mut paths: Vec<String> = notes
         .into_iter()
-        .filter(|memo| memo.relative_path.contains("(Flowix conflict "))
-        .map(|memo| memo.relative_path)
+        .filter(|note| note.relative_path.contains("(Flowix conflict "))
+        .map(|note| note.relative_path)
         .collect();
     let mut attachments = Vec::new();
     let root = Path::new(&notebook.path);
     local_adapter::scan_cloud_attachments(root, &root.join("attachments"), &mut attachments)?;
     for path in attachments {
         let relative = flowix_core::memo_file::notebook_relative_path(root, &path)?;
-        if relative.contains("(Flowix conflict ") { paths.push(relative); }
+        if relative.contains("(Flowix conflict ") {
+            paths.push(relative);
+        }
     }
     paths.sort();
     paths.dedup();
@@ -517,104 +707,178 @@ pub fn cloud_resolve_markdown_conflict(
     state: State<'_, AppState>,
 ) -> Result<(), String> {
     let memo_file = read_lock(&state.memo_file, "memo_file");
-    let _guard = memo_file.operation_locks().notebook_change(&[&notebook_id], "resolve_markdown_conflict").map_err(sync_error)?;
-    let notebook = memo_file.get_notebook_config_by_id(&notebook_id)
+    let _guard = memo_file
+        .operation_locks()
+        .notebook_change(&[&notebook_id], "resolve_markdown_conflict")
+        .map_err(sync_error)?;
+    let notebook = memo_file
+        .get_notebook_config_by_id(&notebook_id)
         .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
     let root = Path::new(&notebook.path);
     let original = local_adapter::safe_cloud_note_path(root, &relative_path)?;
     let copy = local_adapter::safe_cloud_note_path(root, &conflict_path)?;
-    if !conflict_path.contains("(Flowix conflict ") || original.parent() != copy.parent()
-        || original == copy {
+    let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
+    if !conflict_path.contains("(Flowix conflict ")
+        || original.parent() != copy.parent()
+        || original == copy
+    {
         return Err("CLOUD_INVALID_CONFLICT_COPY".into());
     }
-    let copy_memo = memo_file.find_memo_by_relative_path_for_notebook_id(&notebook_id, &conflict_path)
-        .ok_or_else(|| "CLOUD_CONFLICT_COPY_MISSING".to_string())?;
+    if !copy.is_file() {
+        return Err("CLOUD_CONFLICT_COPY_MISSING".to_string());
+    }
     let copy_bytes = std::fs::read(&copy).map_err(sync_error)?;
     local_adapter::record_rejected_cloud_version(
-        &memo_file, &notebook_id, root, &original, &copy_bytes,
+        &memo_file,
+        &notebook_id,
+        root,
+        &original,
+        &copy_bytes,
     )?;
     if use_local {
-        let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
         let current = match std::fs::read(&original) {
             Ok(bytes) => Some(bytes),
             Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
             Err(error) => return Err(sync_error(error)),
         };
         let chosen = copy_bytes.clone();
-        let baseline = state.cloud_sync.v2_note_state(&note_id).map_err(sync_error)?
+        let baseline = state
+            .cloud_sync
+            .v2_note_state(&note_id)
+            .map_err(sync_error)?
             .ok_or_else(|| "CLOUD_CONFLICT_ORIGINAL_NOT_SYNCED".to_string())?;
         let current_hash = current.as_ref().map(|bytes| v2_content_hash(bytes));
         if baseline.deleted != current.is_none()
             || baseline.content_hash.as_deref() != current_hash.as_deref()
-            || state.cloud_sync.has_pending_v2_note_change(&note_id).map_err(sync_error)? {
+            || state
+                .cloud_sync
+                .has_pending_v2_note_change(&note_id)
+                .map_err(sync_error)?
+        {
             return Err("CLOUD_CONFLICT_ORIGINAL_CHANGED".into());
         }
         if let Some(current) = current.as_ref() {
-            let stem = original.file_stem().and_then(|value| value.to_str()).unwrap_or("Note");
-            let backup = original.with_file_name(format!("{stem} (Flowix before conflict resolve {}).md", baseline.revision));
+            let stem = original
+                .file_stem()
+                .and_then(|value| value.to_str())
+                .unwrap_or("Note");
+            let backup = original.with_file_name(format!(
+                "{stem} (Flowix before conflict resolve {}).md",
+                baseline.revision
+            ));
             if !backup.exists() {
-                flowix_core::memo_file::atomic_create_bytes(&backup, &current).map_err(sync_error)?;
-                memo_file.register_existing_file_for_notebook_id(&notebook_id, &backup).map_err(sync_error)?;
-                let backup_relative = flowix_core::memo_file::notebook_relative_path(root, &backup)?;
-                state.cloud_sync.record_v2_local_change(&notebook_id,
-                    &flowix_sync::v2_path_note_id(&notebook_id, &backup_relative),
-                    flowix_sync::LocalChangeKind::Put, &v2_content_hash(&current)).map_err(sync_error)?;
+                flowix_core::memo_file::atomic_create_bytes(&backup, &current)
+                    .map_err(sync_error)?;
+                let backup_relative =
+                    flowix_core::memo_file::notebook_relative_path(root, &backup)?;
+                memo_file
+                    .refresh_note_path(&notebook_id, &backup_relative)
+                    .map_err(sync_error)?;
+                state
+                    .cloud_sync
+                    .record_v2_local_change(
+                        &notebook_id,
+                        &flowix_sync::v2_path_note_id(&notebook_id, &backup_relative),
+                        flowix_sync::LocalChangeKind::Put,
+                        &v2_content_hash(&current),
+                    )
+                    .map_err(sync_error)?;
             } else if std::fs::read(&backup).map_err(sync_error)? != *current {
                 return Err("CLOUD_CONFLICT_BACKUP_COLLISION".into());
             }
         }
-        if let Some(parent) = original.parent() { std::fs::create_dir_all(parent).map_err(sync_error)?; }
+        if let Some(parent) = original.parent() {
+            std::fs::create_dir_all(parent).map_err(sync_error)?;
+        }
         crate::watcher::runtime::mark_self_write_for(&app, &original);
-        let preserved_path = local_adapter::cloud_conflict_copy_path(&original, &format!("resolve-{note_id}"));
-        match local_adapter::safely_replace_cloud_file(&original, current.as_deref(), &chosen,
-            &format!("resolve-{note_id}"), &preserved_path)? {
-            local_adapter::ConflictFileOutcome::Applied { preserved: None } => {},
+        let preserved_path =
+            local_adapter::cloud_conflict_copy_path(&original, &format!("resolve-{note_id}"));
+        match local_adapter::safely_replace_cloud_file(
+            &original,
+            current.as_deref(),
+            &chosen,
+            &format!("resolve-{note_id}"),
+            &preserved_path,
+        )? {
+            local_adapter::ConflictFileOutcome::Applied { preserved: None } => {}
             outcome => {
                 let preserved = match outcome {
                     local_adapter::ConflictFileOutcome::Applied { preserved }
                     | local_adapter::ConflictFileOutcome::Interrupted { preserved } => preserved,
                 };
                 if let Some(preserved) = preserved {
-                    local_adapter::register_preserved_conflict_copy(&memo_file, &notebook_id,
-                        root, &preserved, false)?;
+                    local_adapter::register_preserved_conflict_copy(
+                        &memo_file,
+                        &notebook_id,
+                        root,
+                        &preserved,
+                        false,
+                    )?;
                 }
                 return Err("CLOUD_CONFLICT_ORIGINAL_CHANGED".into());
             }
         }
-        let updated = memo_file.register_existing_file_for_notebook_id(&notebook_id, &original).map_err(sync_error)?;
-        memo_events::emit(&app, MemoEvent::Updated {
-            id: updated.id.clone(), path: original.to_string_lossy().into_owned(),
-            notebook_id: notebook_id.clone(),
-            derived_changed: MemoDerivedChanged { tags: true, todos: true, agents: true },
-            memo: updated, source: MemoChangeSource::CloudSync,
-        });
-        state.cloud_sync.record_v2_local_change(&notebook_id, &note_id,
-            flowix_sync::LocalChangeKind::Put, &v2_content_hash(&chosen)).map_err(sync_error)?;
+        memo_file
+            .refresh_note_path(&notebook_id, &relative_path)
+            .map_err(sync_error)?;
+        crate::commands::path_change::NotebookPathInvalidated::new(
+            notebook_id.clone(),
+            relative_path.clone(),
+        )
+        .emit(&app);
+        state
+            .cloud_sync
+            .record_v2_local_change(
+                &notebook_id,
+                &note_id,
+                flowix_sync::LocalChangeKind::Put,
+                &v2_content_hash(&chosen),
+            )
+            .map_err(sync_error)?;
     }
     crate::watcher::runtime::mark_self_write_for(&app, &copy);
-    let preserved_path = local_adapter::cloud_conflict_copy_path(&copy, &format!("remove-{}", copy_memo.id));
-    match local_adapter::safely_remove_conflict_file(&copy, &copy_bytes,
-        &format!("remove-{}", copy_memo.id), &preserved_path)? {
-        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {},
+    let copy_note_id = flowix_sync::v2_path_note_id(&notebook_id, &conflict_path);
+    let preserved_path =
+        local_adapter::cloud_conflict_copy_path(&copy, &format!("remove-{copy_note_id}"));
+    match local_adapter::safely_remove_conflict_file(
+        &copy,
+        &copy_bytes,
+        &format!("remove-{copy_note_id}"),
+        &preserved_path,
+    )? {
+        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {}
         outcome => {
             let preserved = match outcome {
                 local_adapter::ConflictFileOutcome::Applied { preserved }
                 | local_adapter::ConflictFileOutcome::Interrupted { preserved } => preserved,
             };
             if let Some(preserved) = preserved {
-                local_adapter::register_preserved_conflict_copy(&memo_file, &notebook_id,
-                    root, &preserved, false)?;
+                local_adapter::register_preserved_conflict_copy(
+                    &memo_file,
+                    &notebook_id,
+                    root,
+                    &preserved,
+                    false,
+                )?;
             }
             return Err("CLOUD_CONFLICT_COPY_CHANGED".into());
         }
     }
-    if !memo_file.prune_deleted_memo_for_notebook_id(&notebook_id, &conflict_path, &copy_memo.id)
-        .map_err(sync_error)? {
+    if copy.exists() {
         return Err("CLOUD_CONFLICT_COPY_CHANGED".into());
     }
-    state.cloud_sync.record_v2_local_change(&notebook_id,
-        &flowix_sync::v2_path_note_id(&notebook_id, &conflict_path),
-        flowix_sync::LocalChangeKind::Delete, "deleted").map_err(sync_error)?;
+    memo_file
+        .refresh_note_path(&notebook_id, &conflict_path)
+        .map_err(sync_error)?;
+    state
+        .cloud_sync
+        .record_v2_local_change(
+            &notebook_id,
+            &copy_note_id,
+            flowix_sync::LocalChangeKind::Delete,
+            "deleted",
+        )
+        .map_err(sync_error)?;
     drop(_guard);
     drop(memo_file);
     schedule_notebook_sync_observation(app, notebook_id, true);
@@ -631,19 +895,29 @@ pub fn cloud_resolve_attachment_conflict(
     state: State<'_, AppState>,
 ) -> Result<(), String> {
     let memo_file = read_lock(&state.memo_file, "memo_file");
-    let _guard = memo_file.operation_locks().notebook_change(&[&notebook_id], "resolve_attachment_conflict").map_err(sync_error)?;
-    let notebook = memo_file.get_notebook_config_by_id(&notebook_id)
+    let _guard = memo_file
+        .operation_locks()
+        .notebook_change(&[&notebook_id], "resolve_attachment_conflict")
+        .map_err(sync_error)?;
+    let notebook = memo_file
+        .get_notebook_config_by_id(&notebook_id)
         .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
     let root = Path::new(&notebook.path);
     let original = local_adapter::safe_cloud_file_path(root, &relative_path, true)?;
     let copy = local_adapter::safe_cloud_file_path(root, &conflict_path, true)?;
-    if !conflict_path.contains("(Flowix conflict ") || original.parent() != copy.parent()
-        || original == copy {
+    if !conflict_path.contains("(Flowix conflict ")
+        || original.parent() != copy.parent()
+        || original == copy
+    {
         return Err("CLOUD_INVALID_CONFLICT_COPY".into());
     }
     let chosen = std::fs::read(&copy).map_err(sync_error)?;
     local_adapter::record_rejected_cloud_version(
-        &memo_file, &notebook_id, root, &original, &chosen,
+        &memo_file,
+        &notebook_id,
+        root,
+        &original,
+        &chosen,
     )?;
     if use_local {
         let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
@@ -652,86 +926,156 @@ pub fn cloud_resolve_attachment_conflict(
             Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
             Err(error) => return Err(sync_error(error)),
         };
-        let baseline = state.cloud_sync.v2_note_state(&note_id).map_err(sync_error)?
+        let baseline = state
+            .cloud_sync
+            .v2_note_state(&note_id)
+            .map_err(sync_error)?
             .ok_or_else(|| "CLOUD_CONFLICT_ORIGINAL_NOT_SYNCED".to_string())?;
         let current_hash = current.as_ref().map(|bytes| v2_content_hash(bytes));
         if baseline.deleted != current.is_none()
             || baseline.content_hash.as_deref() != current_hash.as_deref()
-            || state.cloud_sync.has_pending_v2_note_change(&note_id).map_err(sync_error)? {
+            || state
+                .cloud_sync
+                .has_pending_v2_note_change(&note_id)
+                .map_err(sync_error)?
+        {
             return Err("CLOUD_CONFLICT_ORIGINAL_CHANGED".into());
         }
         if let Some(current) = current.as_ref() {
-            let stem = original.file_stem().and_then(|value| value.to_str()).unwrap_or("attachment");
-            let extension = original.extension().and_then(|value| value.to_str()).unwrap_or("");
+            let stem = original
+                .file_stem()
+                .and_then(|value| value.to_str())
+                .unwrap_or("attachment");
+            let extension = original
+                .extension()
+                .and_then(|value| value.to_str())
+                .unwrap_or("");
             let backup_name = if extension.is_empty() {
-                format!("{stem} (Flowix before conflict resolve {})", baseline.revision)
+                format!(
+                    "{stem} (Flowix before conflict resolve {})",
+                    baseline.revision
+                )
             } else {
-                format!("{stem} (Flowix before conflict resolve {}).{extension}", baseline.revision)
+                format!(
+                    "{stem} (Flowix before conflict resolve {}).{extension}",
+                    baseline.revision
+                )
             };
             let backup = original.with_file_name(backup_name);
             if !backup.exists() {
-                flowix_core::memo_file::atomic_create_bytes(&backup, &current).map_err(sync_error)?;
-                let backup_relative = flowix_core::memo_file::notebook_relative_path(root, &backup)?;
+                flowix_core::memo_file::atomic_create_bytes(&backup, &current)
+                    .map_err(sync_error)?;
+                let backup_relative =
+                    flowix_core::memo_file::notebook_relative_path(root, &backup)?;
                 if flowix_core::memo_file::media_kind_for_path(&backup).is_some() {
-                    memo_file.refresh_media_resource_path(&notebook_id, &backup_relative).map_err(sync_error)?;
+                    memo_file
+                        .refresh_media_resource_path(&notebook_id, &backup_relative)
+                        .map_err(sync_error)?;
                 }
-                state.cloud_sync.record_v2_local_change(&notebook_id,
-                    &flowix_sync::v2_path_note_id(&notebook_id, &backup_relative),
-                    flowix_sync::LocalChangeKind::Put, &v2_content_hash(&current)).map_err(sync_error)?;
+                state
+                    .cloud_sync
+                    .record_v2_local_change(
+                        &notebook_id,
+                        &flowix_sync::v2_path_note_id(&notebook_id, &backup_relative),
+                        flowix_sync::LocalChangeKind::Put,
+                        &v2_content_hash(&current),
+                    )
+                    .map_err(sync_error)?;
             } else if std::fs::read(&backup).map_err(sync_error)? != *current {
                 return Err("CLOUD_CONFLICT_BACKUP_COLLISION".into());
             }
         }
         crate::watcher::runtime::mark_self_write_for(&app, &original);
-        let preserved_path = local_adapter::cloud_conflict_copy_path(&original, &format!("resolve-{note_id}"));
-        match local_adapter::safely_replace_cloud_file(&original, current.as_deref(), &chosen,
-            &format!("resolve-{note_id}"), &preserved_path)? {
-            local_adapter::ConflictFileOutcome::Applied { preserved: None } => {},
+        let preserved_path =
+            local_adapter::cloud_conflict_copy_path(&original, &format!("resolve-{note_id}"));
+        match local_adapter::safely_replace_cloud_file(
+            &original,
+            current.as_deref(),
+            &chosen,
+            &format!("resolve-{note_id}"),
+            &preserved_path,
+        )? {
+            local_adapter::ConflictFileOutcome::Applied { preserved: None } => {}
             outcome => {
                 let preserved = match outcome {
                     local_adapter::ConflictFileOutcome::Applied { preserved }
                     | local_adapter::ConflictFileOutcome::Interrupted { preserved } => preserved,
                 };
                 if let Some(preserved) = preserved {
-                    local_adapter::register_preserved_conflict_copy(&memo_file, &notebook_id,
-                        root, &preserved, true)?;
+                    local_adapter::register_preserved_conflict_copy(
+                        &memo_file,
+                        &notebook_id,
+                        root,
+                        &preserved,
+                        true,
+                    )?;
                 }
                 return Err("CLOUD_CONFLICT_ORIGINAL_CHANGED".into());
             }
         }
         crate::watcher::runtime::mark_self_write_for(&app, &original);
         if flowix_core::memo_file::media_kind_for_path(&original).is_some() {
-            memo_file.refresh_media_resource_path(&notebook_id, &relative_path).map_err(sync_error)?;
+            memo_file
+                .refresh_media_resource_path(&notebook_id, &relative_path)
+                .map_err(sync_error)?;
         }
-        state.cloud_sync.record_v2_local_change(&notebook_id, &note_id,
-            flowix_sync::LocalChangeKind::Put, &v2_content_hash(&chosen)).map_err(sync_error)?;
+        state
+            .cloud_sync
+            .record_v2_local_change(
+                &notebook_id,
+                &note_id,
+                flowix_sync::LocalChangeKind::Put,
+                &v2_content_hash(&chosen),
+            )
+            .map_err(sync_error)?;
     }
     crate::watcher::runtime::mark_self_write_for(&app, &copy);
-    let preserved_path = local_adapter::cloud_conflict_copy_path(&copy, &format!("remove-{conflict_path}"));
-    match local_adapter::safely_remove_conflict_file(&copy, &chosen,
-        &format!("remove-{conflict_path}"), &preserved_path)? {
-        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {},
+    let preserved_path =
+        local_adapter::cloud_conflict_copy_path(&copy, &format!("remove-{conflict_path}"));
+    match local_adapter::safely_remove_conflict_file(
+        &copy,
+        &chosen,
+        &format!("remove-{conflict_path}"),
+        &preserved_path,
+    )? {
+        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {}
         outcome => {
             let preserved = match outcome {
                 local_adapter::ConflictFileOutcome::Applied { preserved }
                 | local_adapter::ConflictFileOutcome::Interrupted { preserved } => preserved,
             };
             if let Some(preserved) = preserved {
-                local_adapter::register_preserved_conflict_copy(&memo_file, &notebook_id,
-                    root, &preserved, true)?;
+                local_adapter::register_preserved_conflict_copy(
+                    &memo_file,
+                    &notebook_id,
+                    root,
+                    &preserved,
+                    true,
+                )?;
             }
             return Err("CLOUD_CONFLICT_COPY_CHANGED".into());
         }
     }
     if flowix_core::memo_file::media_kind_for_path(&copy).is_some() {
-        memo_file.refresh_media_resource_path(&notebook_id, &conflict_path).map_err(sync_error)?;
+        memo_file
+            .refresh_media_resource_path(&notebook_id, &conflict_path)
+            .map_err(sync_error)?;
     }
-    state.cloud_sync.record_v2_local_change(&notebook_id,
-        &flowix_sync::v2_path_note_id(&notebook_id, &conflict_path),
-        flowix_sync::LocalChangeKind::Delete, "deleted").map_err(sync_error)?;
+    state
+        .cloud_sync
+        .record_v2_local_change(
+            &notebook_id,
+            &flowix_sync::v2_path_note_id(&notebook_id, &conflict_path),
+            flowix_sync::LocalChangeKind::Delete,
+            "deleted",
+        )
+        .map_err(sync_error)?;
     drop(_guard);
     drop(memo_file);
-    let _ = app.emit("media-properties-changed", serde_json::json!({ "notebookId": notebook_id }));
+    let _ = app.emit(
+        "media-properties-changed",
+        serde_json::json!({ "notebookId": notebook_id }),
+    );
     schedule_notebook_sync_observation(app, notebook_id, true);
     Ok(())
 }
@@ -745,13 +1089,21 @@ pub async fn cloud_restore_note_revision(
     state: State<'_, AppState>,
 ) -> Result<(), String> {
     let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
-    let (history, bytes) = state.cloud_sync.v2_historical_bytes(&note_id, &revision).await.map_err(sync_error)?;
+    let (history, bytes) = state
+        .cloud_sync
+        .v2_historical_bytes(&note_id, &revision)
+        .await
+        .map_err(sync_error)?;
     if history.notebook_id != notebook_id || history.note_id != note_id {
         return Err("CLOUD_HISTORY_ID_MISMATCH".into());
     }
     let memo_file = read_lock(&state.memo_file, "memo_file");
-    let _guard = memo_file.operation_locks().notebook_change(&[&notebook_id], "restore_cloud_note_revision").map_err(sync_error)?;
-    let notebook = memo_file.get_notebook_config_by_id(&notebook_id)
+    let _guard = memo_file
+        .operation_locks()
+        .notebook_change(&[&notebook_id], "restore_cloud_note_revision")
+        .map_err(sync_error)?;
+    let notebook = memo_file
+        .get_notebook_config_by_id(&notebook_id)
         .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
     let root = Path::new(&notebook.path);
     let attachment = relative_path.starts_with("attachments/");
@@ -761,18 +1113,33 @@ pub async fn cloud_restore_note_revision(
         Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
         Err(error) => return Err(sync_error(error)),
     };
-    let baseline = state.cloud_sync.v2_note_state(&note_id).map_err(sync_error)?
+    let baseline = state
+        .cloud_sync
+        .v2_note_state(&note_id)
+        .map_err(sync_error)?
         .ok_or_else(|| "CLOUD_RESTORE_NO_LOCAL_BASE".to_string())?;
     let current_hash = current.as_ref().map(|bytes| v2_content_hash(bytes));
     if baseline.deleted != current.is_none()
         || baseline.content_hash.as_deref() != current_hash.as_deref()
-        || state.cloud_sync.has_pending_v2_note_change(&note_id).map_err(sync_error)? {
+        || state
+            .cloud_sync
+            .has_pending_v2_note_change(&note_id)
+            .map_err(sync_error)?
+    {
         return Err("CLOUD_RESTORE_LOCAL_CHANGED: save or resolve local edits first".into());
     }
-    if current.as_deref() == Some(bytes.as_slice()) { return Ok(()); }
+    if current.as_deref() == Some(bytes.as_slice()) {
+        return Ok(());
+    }
     if let Some(current) = current.as_ref() {
-        let stem = path.file_stem().and_then(|value| value.to_str()).unwrap_or("Note");
-        let extension = path.extension().and_then(|value| value.to_str()).unwrap_or("");
+        let stem = path
+            .file_stem()
+            .and_then(|value| value.to_str())
+            .unwrap_or("Note");
+        let extension = path
+            .extension()
+            .and_then(|value| value.to_str())
+            .unwrap_or("");
         let backup_name = if extension.is_empty() {
             format!("{stem} (Flowix before restore {})", revision)
         } else {
@@ -782,33 +1149,57 @@ pub async fn cloud_restore_note_revision(
         if !backup.exists() {
             flowix_core::memo_file::atomic_create_bytes(&backup, &current).map_err(sync_error)?;
             if !attachment {
-                memo_file.register_existing_file_for_notebook_id(&notebook_id, &backup).map_err(sync_error)?;
+                let backup_relative = notebook_relative_path(root, &backup)?;
+                memo_file
+                    .refresh_note_path(&notebook_id, &backup_relative)
+                    .map_err(sync_error)?;
             }
             let backup_relative = flowix_core::memo_file::notebook_relative_path(root, &backup)?;
             if attachment && flowix_core::memo_file::media_kind_for_path(&backup).is_some() {
-                memo_file.refresh_media_resource_path(&notebook_id, &backup_relative).map_err(sync_error)?;
+                memo_file
+                    .refresh_media_resource_path(&notebook_id, &backup_relative)
+                    .map_err(sync_error)?;
             }
-            state.cloud_sync.record_v2_local_change(&notebook_id,
-                &flowix_sync::v2_path_note_id(&notebook_id, &backup_relative),
-                flowix_sync::LocalChangeKind::Put, &v2_content_hash(&current)).map_err(sync_error)?;
+            state
+                .cloud_sync
+                .record_v2_local_change(
+                    &notebook_id,
+                    &flowix_sync::v2_path_note_id(&notebook_id, &backup_relative),
+                    flowix_sync::LocalChangeKind::Put,
+                    &v2_content_hash(&current),
+                )
+                .map_err(sync_error)?;
         } else if std::fs::read(&backup).map_err(sync_error)? != *current {
             return Err("CLOUD_RESTORE_BACKUP_COLLISION".into());
         }
     }
-    if let Some(parent) = path.parent() { std::fs::create_dir_all(parent).map_err(sync_error)?; }
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).map_err(sync_error)?;
+    }
     crate::watcher::runtime::mark_self_write_for(&app, &path);
-    let conflict_copy = local_adapter::cloud_conflict_copy_path(&path, &format!("restore-{revision}"));
-    match local_adapter::safely_replace_cloud_file(&path, current.as_deref(), &bytes,
-        &format!("restore-{revision}"), &conflict_copy)? {
-        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {},
+    let conflict_copy =
+        local_adapter::cloud_conflict_copy_path(&path, &format!("restore-{revision}"));
+    match local_adapter::safely_replace_cloud_file(
+        &path,
+        current.as_deref(),
+        &bytes,
+        &format!("restore-{revision}"),
+        &conflict_copy,
+    )? {
+        local_adapter::ConflictFileOutcome::Applied { preserved: None } => {}
         outcome => {
             let preserved = match outcome {
                 local_adapter::ConflictFileOutcome::Applied { preserved }
                 | local_adapter::ConflictFileOutcome::Interrupted { preserved } => preserved,
             };
             if let Some(preserved) = preserved {
-                local_adapter::register_preserved_conflict_copy(&memo_file, &notebook_id,
-                    root, &preserved, attachment)?;
+                local_adapter::register_preserved_conflict_copy(
+                    &memo_file,
+                    &notebook_id,
+                    root,
+                    &preserved,
+                    attachment,
+                )?;
             }
             return Err("CLOUD_RESTORE_LOCAL_CHANGED: local file preserved".into());
         }
@@ -816,22 +1207,33 @@ pub async fn cloud_restore_note_revision(
     if attachment {
         crate::watcher::runtime::mark_self_write_for(&app, &path);
         if flowix_core::memo_file::media_kind_for_path(&path).is_some() {
-            memo_file.refresh_media_resource_path(&notebook_id, &relative_path).map_err(sync_error)?;
+            memo_file
+                .refresh_media_resource_path(&notebook_id, &relative_path)
+                .map_err(sync_error)?;
         }
-        let _ = app.emit("media-properties-changed", serde_json::json!({ "notebookId": notebook_id }));
+        let _ = app.emit(
+            "media-properties-changed",
+            serde_json::json!({ "notebookId": notebook_id }),
+        );
     } else {
-        let updated = memo_file.register_existing_file_for_notebook_id(&notebook_id, &path).map_err(sync_error)?;
-        memo_events::emit(&app, MemoEvent::Updated {
-            id: updated.id.clone(), path: path.to_string_lossy().into_owned(),
-            notebook_id: notebook_id.clone(),
-            derived_changed: MemoDerivedChanged { tags: true, todos: true, agents: true },
-            memo: updated, source: MemoChangeSource::CloudSync,
-        });
-    }
-    state.cloud_sync.record_v2_local_change(
-        &notebook_id, &note_id, flowix_sync::LocalChangeKind::Put,
-        &v2_content_hash(&bytes),
-    ).map_err(sync_error)?;
+        memo_file
+            .refresh_note_path(&notebook_id, &relative_path)
+            .map_err(sync_error)?;
+        crate::commands::path_change::NotebookPathInvalidated::new(
+            notebook_id.clone(),
+            relative_path.clone(),
+        )
+        .emit(&app);
+    }
+    state
+        .cloud_sync
+        .record_v2_local_change(
+            &notebook_id,
+            &note_id,
+            flowix_sync::LocalChangeKind::Put,
+            &v2_content_hash(&bytes),
+        )
+        .map_err(sync_error)?;
     drop(_guard);
     drop(memo_file);
     schedule_notebook_sync_observation(app, notebook_id, true);
diff --git a/app/flowix-desktop/src/commands/cloud/coordinator.rs b/app/flowix-desktop/src/commands/cloud/coordinator.rs
index fb6b4bb60..6563e3035 100644
--- a/app/flowix-desktop/src/commands/cloud/coordinator.rs
+++ b/app/flowix-desktop/src/commands/cloud/coordinator.rs
@@ -1,6 +1,6 @@
 //! Serializes manual, automatic and polling sync work, including retries.
-use super::*;
 use super::local_adapter::*;
+use super::*;
 
 static ACCOUNT_SYNC_LOCK: OnceLock<Arc<tokio::sync::Mutex<()>>> = OnceLock::new();
 
@@ -255,22 +255,37 @@ async fn sync_v2_account_pass(
         "snapshot",
         None,
     );
-    let (mut notebooks, mut notes) = v2_account_snapshot(state, full_local_snapshot, notebook_scope)?;
+    let (mut notebooks, mut notes) =
+        v2_account_snapshot(state, full_local_snapshot, notebook_scope)?;
     if full_local_snapshot {
         let present: HashSet<_> = notes.iter().map(|note| note.id.as_str()).collect();
-        let moving: HashSet<_> = state.cloud_sync.v2_pending_moves().map_err(sync_error)?
-            .into_iter().map(|item| item.from_note_id).collect();
-        let enabled_ids: HashSet<_> = enabled.iter().map(|item| item.notebook_id.as_str()).collect();
+        let moving: HashSet<_> = state
+            .cloud_sync
+            .v2_pending_moves()
+            .map_err(sync_error)?
+            .into_iter()
+            .map(|item| item.from_note_id)
+            .collect();
+        let enabled_ids: HashSet<_> = enabled
+            .iter()
+            .map(|item| item.notebook_id.as_str())
+            .collect();
         for previous in state.cloud_sync.v2_all_note_states().map_err(sync_error)? {
-            if !previous.deleted && enabled_ids.contains(previous.notebook_id.as_str())
+            if !previous.deleted
+                && enabled_ids.contains(previous.notebook_id.as_str())
                 && notebook_scope.is_none_or(|scope| scope == previous.notebook_id)
                 && !present.contains(previous.note_id.as_str())
                 && !moving.contains(&previous.note_id)
             {
-                state.cloud_sync.record_v2_local_change(
-                    &previous.notebook_id, &previous.note_id,
-                    flowix_sync::LocalChangeKind::Delete, "deleted",
-                ).map_err(sync_error)?;
+                state
+                    .cloud_sync
+                    .record_v2_local_change(
+                        &previous.notebook_id,
+                        &previous.note_id,
+                        flowix_sync::LocalChangeKind::Delete,
+                        "deleted",
+                    )
+                    .map_err(sync_error)?;
             }
         }
     }
@@ -303,19 +318,27 @@ async fn sync_v2_account_pass(
         match result {
             Err(SyncError::MoveConflict { operation_id, .. }) if conflict_attempts < 3 => {
                 conflict_attempts += 1;
-                let movement = state.cloud_sync.v2_pending_move(&operation_id)
+                let movement = state
+                    .cloud_sync
+                    .v2_pending_move(&operation_id)
                     .map_err(sync_error)?
                     .ok_or_else(|| "CLOUD_MOVE_CONFLICT_QUEUE_MISSING".to_string())?;
                 resolve_v2_move_conflict(state, app, &movement)?;
                 (notebooks, notes) = v2_account_snapshot(state, true, notebook_scope)?;
             }
             Err(SyncError::RevisionConflict {
-                notebook_id, note_id, operation_id, operation_kind, ..
+                notebook_id,
+                note_id,
+                operation_id,
+                operation_kind,
+                ..
             }) if matches!(operation_kind.as_str(), "put" | "delete") && conflict_attempts < 3 => {
                 conflict_attempts += 1;
-                let material = state.cloud_sync
+                let material = state
+                    .cloud_sync
                     .v2_conflict_material(&notebook_id, &note_id, &operation_id)
-                    .await.map_err(cloud_error)?;
+                    .await
+                    .map_err(cloud_error)?;
                 if operation_kind == "delete" {
                     resolve_v2_delete_conflict(state, app, &material)?;
                 } else {
@@ -341,7 +364,9 @@ async fn sync_v2_account_pass(
             apply_v2_report(state, app, &report).map_err(SyncError::InvalidState)
         })
         .map_err(sync_error)?;
-    if full_local_snapshot { record_full_local_snapshot(notebook_scope); }
+    if full_local_snapshot {
+        record_full_local_snapshot(notebook_scope);
+    }
     Ok(report)
 }
 
@@ -569,7 +594,15 @@ async fn run_sync_activity(
         let mut first_head = None;
         let mut previous_cursor = None;
         loop {
-            let mut report = match sync_v2_account_pass(state.inner(), app, &target, &enabled, &activity).await {
+            let mut report = match sync_v2_account_pass(
+                state.inner(),
+                app,
+                &target,
+                &enabled,
+                &activity,
+            )
+            .await
+            {
                 Ok(report) => report,
                 Err(error) => {
                     return Err(fail_sync_activity(
@@ -587,19 +620,25 @@ async fn run_sync_activity(
                     async {
                         let next = tokio::time::timeout(
                             CLOUD_SYNC_PASS_TIMEOUT,
-                            state.cloud_sync.v2_continue_bootstrap(&report, target.notebook_scope()),
+                            state
+                                .cloud_sync
+                                .v2_continue_bootstrap(&report, target.notebook_scope()),
                         )
                         .await
                         .map_err(|_| {
-                            "云端笔记初始化超过 3 分钟仍未完成，请检查网络后重试。"
-                                .to_string()
+                            "云端笔记初始化超过 3 分钟仍未完成，请检查网络后重试。".to_string()
                         })?
                         .map_err(cloud_error)?;
-                        state.cloud_sync.complete_v2_sync_with_apply(&next, target.notebook_scope(), || {
-                            apply_v2_report(state.inner(), app, &next).map_err(SyncError::InvalidState)
-                        }).map_err(sync_error)?;
+                        state
+                            .cloud_sync
+                            .complete_v2_sync_with_apply(&next, target.notebook_scope(), || {
+                                apply_v2_report(state.inner(), app, &next)
+                                    .map_err(SyncError::InvalidState)
+                            })
+                            .map_err(sync_error)?;
                         Ok::<_, String>(next)
-                    }.await
+                    }
+                    .await
                 };
                 report = match next {
                     Ok(next) => next,
@@ -612,7 +651,9 @@ async fn run_sync_activity(
                 activity.absorb_report(&report);
             }
             let head = *first_head.get_or_insert(report.head_cursor);
-            if report.cursor >= head { break; }
+            if report.cursor >= head {
+                break;
+            }
             if previous_cursor.is_some_and(|cursor| report.cursor <= cursor) {
                 return Err(fail_sync_activity(
                     app,
@@ -757,7 +798,10 @@ pub(crate) fn start_cloud_sync_polling(app: AppHandle) {
                 let cloud_state = state.cloud_sync.state().ok();
                 matches!(
                     cloud_state,
-                    Some(CloudState { authenticated: true, .. })
+                    Some(CloudState {
+                        authenticated: true,
+                        ..
+                    })
                 ) && !state
                     .cloud_sync
                     .v2_enabled_notebooks()
@@ -773,7 +817,6 @@ pub(crate) fn start_cloud_sync_polling(app: AppHandle) {
     });
 }
 
-
 pub(super) async fn sync_now(
     notebook_id: Option<String>,
     app: AppHandle,
@@ -789,12 +832,13 @@ pub(super) async fn sync_now(
     )?;
     match tokio::time::timeout(MANUAL_SYNC_TIMEOUT, response).await {
         Ok(Ok(result)) => result,
-        Ok(Err(_)) => Err("cloud sync coordinator stopped before completing the request".to_string()),
+        Ok(Err(_)) => {
+            Err("cloud sync coordinator stopped before completing the request".to_string())
+        }
         Err(_) => Err("云同步超过 5 分钟仍未完成，请检查网络后重试。".to_string()),
     }
 }
 
-
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/app/flowix-desktop/src/commands/cloud/deletion.rs b/app/flowix-desktop/src/commands/cloud/deletion.rs
index 223145044..e7a7b1e6b 100644
--- a/app/flowix-desktop/src/commands/cloud/deletion.rs
+++ b/app/flowix-desktop/src/commands/cloud/deletion.rs
@@ -1,10 +1,10 @@
 use std::path::Path;
 
 use super::local_adapter::{
-    cloud_conflict_copy_path, register_preserved_conflict_copy, safely_remove_conflict_file,
-    ConflictFileOutcome,
+    cloud_conflict_copy_path, register_preserved_conflict_copy, safe_cloud_note_path,
+    safely_remove_conflict_file, ConflictFileOutcome,
 };
-use flowix_core::memo_file::{notebook_path_from_relative, Memo, MemoFile};
+use flowix_core::memo_file::MemoFile;
 use flowix_sync::{v2_content_hash, v2_local_content_diverged, SyncManager};
 
 pub(super) fn delete_cloud_note_locked(
@@ -14,16 +14,12 @@ pub(super) fn delete_cloud_note_locked(
     note_id: &str,
     relative_path: &str,
     before_delete: impl FnOnce(&Path),
-) -> Result<Option<Memo>, String> {
-    // Cloud v2 note ids are path-derived; the local note is addressed by the
-    // same relative path. Legacy id-based lookup is no longer supported.
-    let memo = memo_file.find_memo_by_relative_path_for_notebook_id(notebook_id, relative_path);
-    let Some(memo) = memo else { return Ok(None) };
+) -> Result<bool, String> {
     let notebook = memo_file
         .get_notebook_config_by_id(notebook_id)
         .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
-    let path = notebook_path_from_relative(Path::new(&notebook.path), &memo.relative_path)
-        .unwrap_or_else(|_| Path::new(&notebook.path).join(&memo.filename));
+    let path = safe_cloud_note_path(Path::new(&notebook.path), relative_path)?;
+
     let local_bytes = match std::fs::read(&path) {
         Ok(bytes) => Some(bytes),
         Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
@@ -54,6 +50,7 @@ pub(super) fn delete_cloud_note_locked(
         ));
     }
     before_delete(&path);
+    let had_local_file = local_bytes.is_some();
     if let Some(expected) = local_bytes.as_deref() {
         let copy = cloud_conflict_copy_path(&path, note_id);
         match safely_remove_conflict_file(&path, expected, note_id, &copy)? {
@@ -79,16 +76,16 @@ pub(super) fn delete_cloud_note_locked(
             }
         }
     }
-    if !memo_file
-        .prune_deleted_memo_for_notebook_id(notebook_id, &memo.relative_path, &memo.id)
-        .map_err(|error| error.to_string())?
-    {
+    memo_file
+        .refresh_note_path(notebook_id, relative_path)
+        .map_err(|error| format!("CLOUD_DELETE_INDEX_FAILED: {error}"))?;
+    if path.exists() {
         return Err(format!(
             "CLOUD_DELETE_CONFLICT: path was recreated: {}",
             path.display()
         ));
     }
-    Ok(Some(memo))
+    Ok(had_local_file)
 }
 
 #[cfg(test)]
diff --git a/app/flowix-desktop/src/commands/cloud/deletion/tests.rs b/app/flowix-desktop/src/commands/cloud/deletion/tests.rs
index 79198f506..d00793dc4 100644
--- a/app/flowix-desktop/src/commands/cloud/deletion/tests.rs
+++ b/app/flowix-desktop/src/commands/cloud/deletion/tests.rs
@@ -1,6 +1,6 @@
 use super::*;
 use flowix_core::memo_file::NotebookConfig;
-use flowix_core::MemoService;
+use flowix_core::NoteService;
 use flowix_sync::{V2EntityType, V2NoteState, V2OperationKind};
 use std::path::PathBuf;
 
@@ -28,15 +28,10 @@ fn fixture() -> (
             updated_at: 1,
         }])
         .unwrap();
-    let created = MemoService::new(&store)
-        .create_memo_named_with_tag_in_directory(
-            Some("work"),
-            None,
-            "Untitled",
-            "# Note\noriginal\n",
-            None,
-        )
+    let created = NoteService::new(&store)
+        .create("work", None, "Untitled", "# Note\noriginal\n")
         .unwrap();
+    let note_id = "remote-note-id".to_string();
     let sync = SyncManager::new(
         "https://cloud.example.test",
         directory.path().join("sync.db"),
@@ -45,11 +40,11 @@ fn fixture() -> (
     let content = std::fs::read(&created.path).unwrap();
     sync.store()
         .save_v2_note_state(&V2NoteState {
-            note_id: created.memo.id.clone(),
+            note_id: note_id.clone(),
             notebook_id: "work".into(),
             revision: "revision-1".into(),
             content_hash: Some(v2_content_hash(&content)),
-            filename: created.memo.filename.clone(),
+            filename: "Untitled.md".to_string(),
             deleted: false,
             last_seq: 1,
             attachments: Vec::new(),
@@ -59,9 +54,9 @@ fn fixture() -> (
         directory,
         store,
         sync,
-        created.memo.id,
+        note_id,
         created.path,
-        created.memo.relative_path,
+        created.entry.relative_path,
     )
 }
 
@@ -82,7 +77,8 @@ fn remote_delete_preserves_edits_before_watcher_marks_dirty() {
     assert!(error.starts_with("CLOUD_DELETE_CONFLICT:"));
     assert_eq!(std::fs::read_to_string(&path).unwrap(), edited);
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_some());
     assert_eq!(sync.v2_note_state(&id).unwrap(), baseline);
     assert_eq!(sync.store().v2_cursor().unwrap(), cursor);
@@ -111,7 +107,8 @@ fn remote_delete_preserves_pending_changes_even_when_body_hash_matches() {
     );
     assert_eq!(std::fs::read(&path).unwrap(), original);
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_some());
     let dirty_after = sync.store().v2_dirty_entities().unwrap();
     assert_eq!(dirty_after.len(), dirty_before.len());
@@ -136,15 +133,14 @@ fn remote_delete_removes_unchanged_file_and_index_entry() {
     )
     .unwrap();
     assert!(acknowledged);
-    assert_eq!(removed.unwrap().id, id);
+    assert!(removed);
     assert!(!path.exists());
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_none());
     assert!(
-        delete_cloud_note_locked(&store, &sync, "work", &id, relative.as_str(), |_| {})
-            .unwrap()
-            .is_none()
+        !delete_cloud_note_locked(&store, &sync, "work", &id, relative.as_str(), |_| {}).unwrap()
     );
 }
 
@@ -166,7 +162,8 @@ fn remote_delete_preserves_external_save_during_delete() {
     assert!(error.starts_with("CLOUD_DELETE_CONFLICT:"));
     assert_eq!(std::fs::read(&path).unwrap(), b"external save");
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_some());
 }
 
@@ -183,7 +180,8 @@ fn remote_delete_does_not_treat_read_failure_as_a_missing_file() {
     );
     assert!(path.is_dir());
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_some());
 }
 
@@ -194,13 +192,12 @@ fn remote_delete_ignores_a_note_path_missing_in_the_target_notebook() {
     // Path-based lookup: the same relative path simply does not exist in the
     // other notebook, so the deletion is a no-op there.
     assert!(
-        delete_cloud_note_locked(&store, &sync, "other", &id, relative.as_str(), |_| {})
-            .unwrap()
-            .is_none()
+        delete_cloud_note_locked(&store, &sync, "other", &id, relative.as_str(), |_| {}).unwrap()
     );
     assert!(path.exists());
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_some());
 }
 
@@ -219,7 +216,8 @@ fn remote_delete_preserves_a_local_file_without_an_acknowledged_hash() {
     );
     assert_eq!(std::fs::read(&path).unwrap(), original);
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_some());
 }
 
@@ -229,11 +227,10 @@ fn remote_delete_cleans_an_already_missing_file_from_the_index() {
     store.delete_file(&path).unwrap();
     let _guard = store.acquire_cross_process_write_lock().unwrap();
     assert!(
-        delete_cloud_note_locked(&store, &sync, "work", &id, relative.as_str(), |_| {})
-            .unwrap()
-            .is_some()
+        !delete_cloud_note_locked(&store, &sync, "work", &id, relative.as_str(), |_| {}).unwrap()
     );
     assert!(store
-        .find_memo_by_relative_path_for_notebook_id("work", &relative)
+        .read_note_entry_by_path("work", &relative)
+        .unwrap()
         .is_none());
 }
diff --git a/app/flowix-desktop/src/commands/cloud/google_login.rs b/app/flowix-desktop/src/commands/cloud/google_login.rs
index 4984d5fca..069ceb8c2 100644
--- a/app/flowix-desktop/src/commands/cloud/google_login.rs
+++ b/app/flowix-desktop/src/commands/cloud/google_login.rs
@@ -15,11 +15,19 @@ pub(crate) enum GoogleCallback {
 
 impl PendingGoogleLogin {
     pub(super) fn new(state: String, code_verifier: String, generation: u64) -> Self {
-        Self { state, code_verifier, generation, created_at: Instant::now(), callback_received: false }
+        Self {
+            state,
+            code_verifier,
+            generation,
+            created_at: Instant::now(),
+            callback_received: false,
+        }
     }
 
     fn claim_once(&mut self, state: &str) -> Result<bool, &'static str> {
-        if self.state != state { return Ok(false); }
+        if self.state != state {
+            return Ok(false);
+        }
         // Browser fallback links and OS delivery can repeat the same callback.
         // Exchange its one-time code at most once, including while in flight.
         if self.callback_received {
@@ -33,16 +41,22 @@ impl PendingGoogleLogin {
     }
 
     pub(super) fn claim(&mut self, state: &str) -> Result<Option<(String, u64)>, &'static str> {
-        if !self.claim_once(state)? { return Ok(None); }
-        Ok(Some((std::mem::take(&mut self.code_verifier), self.generation)))
+        if !self.claim_once(state)? {
+            return Ok(None);
+        }
+        Ok(Some((
+            std::mem::take(&mut self.code_verifier),
+            self.generation,
+        )))
     }
 
     pub(super) fn claim_failure(&mut self, state: &str) -> Result<bool, &'static str> {
         let claimed = self.claim_once(state)?;
-        if claimed { self.code_verifier.clear(); }
+        if claimed {
+            self.code_verifier.clear();
+        }
         Ok(claimed)
     }
-
 }
 
 #[cfg(test)]
@@ -68,7 +82,10 @@ mod tests {
     fn expired_attempt_cannot_be_exchanged() {
         let mut attempt = PendingGoogleLogin::new("state".into(), "verifier".into(), 7);
         attempt.created_at -= Duration::from_secs(301);
-        assert_eq!(attempt.claim("state"), Err("Google sign-in expired; please try again"));
+        assert_eq!(
+            attempt.claim("state"),
+            Err("Google sign-in expired; please try again")
+        );
         assert!(!attempt.callback_received);
     }
 
@@ -85,7 +102,10 @@ mod tests {
     fn expired_failure_callback_is_reported_only_for_the_matching_attempt() {
         let mut attempt = PendingGoogleLogin::new("state".into(), "verifier".into(), 7);
         attempt.created_at -= Duration::from_secs(301);
-        assert_eq!(attempt.claim_failure("state"), Err("Google sign-in expired; please try again"));
+        assert_eq!(
+            attempt.claim_failure("state"),
+            Err("Google sign-in expired; please try again")
+        );
         assert!(!attempt.callback_received);
     }
 }
diff --git a/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_files.rs b/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_files.rs
index 48fb13d77..6262dd94e 100644
--- a/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_files.rs
+++ b/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_files.rs
@@ -337,9 +337,9 @@ pub(crate) fn register_preserved_conflict_copy(
             .refresh_media_resource_path(notebook_id, &relative)
             .map_err(sync_error)
     } else {
+        let relative = flowix_core::memo_file::notebook_relative_path(notebook_root, path)?;
         memo_file
-            .register_existing_file_for_notebook_id(notebook_id, path)
-            .map(|_| ())
+            .refresh_note_path(notebook_id, &relative)
             .map_err(sync_error)
     }
 }
diff --git a/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/file_put.rs b/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/file_put.rs
index 5d4982199..e99460310 100644
--- a/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/file_put.rs
+++ b/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/file_put.rs
@@ -133,6 +133,12 @@ pub(crate) fn resolve_v2_file_put_conflict(
                     let _ = flowix_core::memo_file::rename_file_noclobber(&destination, &path);
                     return Err(sync_error(error));
                 }
+                crate::commands::document_list::rebase_collection_paths(
+                    &memo_file,
+                    &material.notebook_id,
+                    &material.remote.filename,
+                    &target.filename,
+                );
             }
             destination
         } else {
@@ -173,16 +179,24 @@ pub(crate) fn resolve_v2_file_put_conflict(
                     && destination.exists()
                     && flowix_core::memo_file::rename_file_noclobber(&destination, &path).is_ok()
                 {
-                    let _ = memo_file.move_media_resource_path(
+                    let restored = memo_file.move_media_resource_path(
                         &material.notebook_id,
                         material
                             .relocated
                             .as_ref()
                             .map_or(material.remote.filename.as_str(), |item| {
                                 item.filename.as_str()
-                            }),
+                        }),
                         &material.remote.filename,
                     );
+                    if restored.is_ok() {
+                        crate::commands::document_list::rebase_collection_paths(
+                            &memo_file,
+                            &material.notebook_id,
+                            material.relocated.as_ref().map_or(material.remote.filename.as_str(), |item| item.filename.as_str()),
+                            &material.remote.filename,
+                        );
+                    }
                 }
                 return Err(
                     "CLOUD_CONFLICT_LOCAL_CHANGED: attachment changed during recovery".into(),
@@ -219,16 +233,10 @@ pub(crate) fn resolve_v2_file_put_conflict(
                 .map_err(sync_error)
         };
     }
-    let memo = memo_file
-        .find_memo_by_relative_path_for_notebook_id(
-            &material.notebook_id,
-            &material.remote.filename,
-        )
-        .ok_or_else(|| "CLOUD_CONFLICT_LOCAL_NOTE_NOT_FOUND".to_string())?;
-    if material.remote.filename != memo.relative_path {
-        return Err("CLOUD_PATH_OR_DELETE_CONFLICT: local changes preserved".to_string());
+    let path = safe_cloud_note_path(Path::new(&notebook.path), &material.remote.filename)?;
+    if !path.is_file() {
+        return Err("CLOUD_CONFLICT_LOCAL_NOTE_NOT_FOUND".to_string());
     }
-    let path = notebook_path_from_relative(Path::new(&notebook.path), &memo.relative_path)?;
     let conflict_copy = path.with_file_name(format!(
         "{} (Flowix conflict {}).md",
         path.file_stem()
@@ -288,14 +296,10 @@ pub(crate) fn resolve_v2_file_put_conflict(
             }
         }
         crate::watcher::runtime::mark_self_write_for(app, &path);
-        if !memo_file
-            .prune_deleted_memo_for_notebook_id(
-                &material.notebook_id,
-                &material.remote.filename,
-                &memo.id,
-            )
-            .map_err(sync_error)?
-        {
+        memo_file
+            .refresh_note_path(&material.notebook_id, &material.remote.filename)
+            .map_err(sync_error)?;
+        if path.exists() {
             return Err(
                 "CLOUD_CONFLICT_LOCAL_CHANGED: local note reappeared during recovery".into(),
             );
@@ -336,10 +340,10 @@ pub(crate) fn resolve_v2_file_put_conflict(
         crate::watcher::runtime::mark_self_write_for(app, &destination);
         flowix_core::memo_file::rename_file_noclobber(&path, &destination).map_err(sync_error)?;
         if let Err(error) =
-            memo_file.rename_memo_file_for_notebook_id(&material.notebook_id, &path, &destination)
+            memo_file.refresh_note_path(&material.notebook_id, &material.remote.filename)
         {
             let _ = flowix_core::memo_file::rename_file_noclobber(&destination, &path);
-            return Err(error);
+            return Err(sync_error(error));
         }
         destination
     } else {
@@ -379,34 +383,29 @@ pub(crate) fn resolve_v2_file_put_conflict(
                 && destination.exists()
                 && flowix_core::memo_file::rename_file_noclobber(&destination, &path).is_ok()
             {
-                let _ = memo_file.rename_memo_file_for_notebook_id(
-                    &material.notebook_id,
+                if let Ok(relative) = flowix_core::memo_file::notebook_relative_path(
+                    Path::new(&notebook.path),
                     &destination,
-                    &path,
-                );
+                ) {
+                    let _ = memo_file.refresh_note_path(&material.notebook_id, &relative);
+                }
+                let _ =
+                    memo_file.refresh_note_path(&material.notebook_id, &material.remote.filename);
             }
             return Err("CLOUD_CONFLICT_LOCAL_CHANGED: local note changed during recovery".into());
         }
     }
     crate::watcher::runtime::mark_self_write_content_for(app, &destination, &next);
-    let updated = memo_file
-        .register_existing_file_for_notebook_id(&material.notebook_id, &destination)
+    let relative_path =
+        flowix_core::memo_file::notebook_relative_path(Path::new(&notebook.path), &destination)?;
+    memo_file
+        .refresh_note_path(&material.notebook_id, &relative_path)
         .map_err(sync_error)?;
-    memo_events::emit(
-        app,
-        MemoEvent::Updated {
-            id: updated.id.clone(),
-            path: destination.to_string_lossy().into_owned(),
-            notebook_id: material.notebook_id.clone(),
-            derived_changed: MemoDerivedChanged {
-                tags: true,
-                todos: true,
-                agents: true,
-            },
-            memo: updated,
-            source: MemoChangeSource::CloudSync,
-        },
-    );
+    crate::commands::path_change::NotebookPathInvalidated::new(
+        material.notebook_id.clone(),
+        relative_path,
+    )
+    .emit(app);
     if let Some(target) = &material.relocated {
         state
             .cloud_sync
diff --git a/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/move_delete.rs b/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/move_delete.rs
index 26efc4405..fdfd7a370 100644
--- a/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/move_delete.rs
+++ b/app/flowix-desktop/src/commands/cloud/local_adapter/conflict_resolution/move_delete.rs
@@ -70,15 +70,9 @@ pub(crate) fn resolve_v2_move_conflict(
             memo_file
                 .refresh_media_resource_path(&movement.notebook_id, &movement.to_path)
                 .map_err(sync_error)?;
-        } else if let Some(memo) = memo_file
-            .find_memo_by_relative_path_for_notebook_id(&movement.notebook_id, &movement.to_path)
-        {
-            let _ = memo_file
-                .prune_deleted_memo_for_notebook_id(
-                    &movement.notebook_id,
-                    &movement.to_path,
-                    &memo.id,
-                )
+        } else {
+            memo_file
+                .refresh_note_path(&movement.notebook_id, &movement.to_path)
                 .map_err(sync_error)?;
         }
     }
diff --git a/app/flowix-desktop/src/commands/cloud/local_adapter/local_snapshot.rs b/app/flowix-desktop/src/commands/cloud/local_adapter/local_snapshot.rs
index 80e3faf09..b3aed3a51 100644
--- a/app/flowix-desktop/src/commands/cloud/local_adapter/local_snapshot.rs
+++ b/app/flowix-desktop/src/commands/cloud/local_adapter/local_snapshot.rs
@@ -102,7 +102,9 @@ pub(crate) fn v2_account_snapshot(
     } else {
         Some(state.cloud_sync.v2_dirty_note_ids().map_err(sync_error)?)
     };
-    let memo_file = read_lock(&state.memo_file, "memo_file");
+    // A complete sync snapshot may scan files. It must not hold the global
+    // facade lock needed by foreground notebook switching.
+    let memo_file = flowix_core::memo_file::MemoFile::new(state.user_config.config_dir().clone());
     let configs = memo_file.read_notebook_configs().map_err(sync_error)?;
     let mut notebooks = Vec::new();
     let mut notes = Vec::new();
@@ -118,22 +120,33 @@ pub(crate) fn v2_account_snapshot(
         if full_scan {
             memo_file.reconcile_notebook_with_disk_bidirectional(&config.id)?;
         }
-        for memo in memo_file.read_all_memos_for_notebook_id(Some(&config.id)) {
-            let cloud_id = flowix_sync::v2_path_note_id(&config.id, &memo.relative_path);
+        let indexed_notes = match memo_file.read_note_entries(&config.id) {
+            Ok(notes) => notes,
+            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                memo_file
+                    .reconcile_note_index_blocking(&config.id)
+                    .map_err(|error| error.to_string())?;
+                memo_file
+                    .read_note_entries(&config.id)
+                    .map_err(|error| error.to_string())?
+            }
+            Err(error) => return Err(error.to_string()),
+        };
+        for note in indexed_notes {
+            let cloud_id = flowix_sync::v2_path_note_id(&config.id, &note.relative_path);
             if dirty_note_ids
                 .as_ref()
                 .is_some_and(|ids| !ids.contains(&cloud_id))
             {
                 continue;
             }
-            let path = notebook_path_from_relative(Path::new(&config.path), &memo.relative_path)
-                .unwrap_or_else(|_| PathBuf::from(&config.path).join(&memo.filename));
+            let path = notebook_path_from_relative(Path::new(&config.path), &note.relative_path)?;
             let content = std::fs::read(&path)
                 .map_err(|error| format!("READ_NOTE_FAILED {}: {error}", path.display()))?;
             notes.push(V2LocalNote {
                 id: cloud_id,
                 notebook_id: config.id.clone(),
-                filename: memo.relative_path,
+                filename: note.relative_path,
                 content,
                 attachments: Vec::new(),
             });
diff --git a/app/flowix-desktop/src/commands/cloud/local_adapter/remote_apply.rs b/app/flowix-desktop/src/commands/cloud/local_adapter/remote_apply.rs
index c04b1ae94..9874a1544 100644
--- a/app/flowix-desktop/src/commands/cloud/local_adapter/remote_apply.rs
+++ b/app/flowix-desktop/src/commands/cloud/local_adapter/remote_apply.rs
@@ -79,6 +79,32 @@ fn apply_v2_note_changes(
     app: &AppHandle,
     notebook_id: &str,
     changes: &[&V2RemoteApply],
+) -> Result<(), String> {
+    apply_v2_note_changes_locked(state, app, notebook_id, changes)?;
+    let memo_file = read_lock(&state.memo_file, "memo_file");
+    for relative_path in changes.iter().filter_map(|change| {
+        let V2RemoteApply::Note {
+            filename, deleted, ..
+        } = *change
+        else {
+            return None;
+        };
+        (*deleted && !filename.starts_with("attachments/")).then_some(filename.as_str())
+    }) {
+        crate::commands::document_list::remove_table_note_records(
+            &memo_file,
+            notebook_id,
+            relative_path,
+        );
+    }
+    Ok(())
+}
+
+fn apply_v2_note_changes_locked(
+    state: &AppState,
+    app: &AppHandle,
+    notebook_id: &str,
+    changes: &[&V2RemoteApply],
 ) -> Result<(), String> {
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let _write_guard = memo_file
@@ -194,29 +220,19 @@ fn apply_v2_note_changes(
             continue;
         }
         if *deleted {
-            if let Some(memo) = deletion::delete_cloud_note_locked(
+            deletion::delete_cloud_note_locked(
                 &memo_file,
                 &state.cloud_sync,
                 notebook_id,
                 note_id,
                 filename,
                 |path| crate::watcher::runtime::mark_self_write_for(app, path),
-            )? {
-                let path = notebook_path_from_relative(&base, &memo.relative_path)
-                    .unwrap_or_else(|_| base.join(&memo.filename));
-                let derived_changed = MemoDerivedChanged::from_deleted(&memo);
-                memo_events::emit(
-                    app,
-                    MemoEvent::Deleted {
-                        id: memo.id.clone(),
-                        path: path.to_string_lossy().into_owned(),
-                        relative_path: memo.relative_path.clone(),
-                        notebook_id: notebook_id.to_string(),
-                        derived_changed,
-                        source: MemoChangeSource::CloudSync,
-                    },
-                );
-            }
+            )?;
+            crate::commands::path_change::NotebookPathDeleted::new(
+                notebook_id.to_string(),
+                filename.to_string(),
+            )
+            .emit(app);
         } else {
             let bytes = content
                 .as_ref()
@@ -233,17 +249,30 @@ fn apply_v2_note_changes(
             let markdown = std::str::from_utf8(bytes)
                 .map_err(|_| format!("CLOUD_NOTE_NOT_UTF8: {note_id}"))?;
             write_cloud_attachments(&base, attachments)?;
-            let current_memo =
-                memo_file.find_memo_by_relative_path_for_notebook_id(notebook_id, filename);
-            let old_path = current_memo.as_ref().map(|memo| {
-                notebook_path_from_relative(&base, &memo.relative_path)
-                    .unwrap_or_else(|_| base.join(&memo.filename))
-            });
             let desired_path = safe_cloud_note_path(&base, filename)?;
+            let is_indexed = match memo_file.read_note_entry_by_path(notebook_id, filename) {
+                Ok(entry) => entry.is_some(),
+                Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                    memo_file
+                        .reconcile_note_index(notebook_id)
+                        .map_err(sync_error)?;
+                    memo_file
+                        .read_note_entry_by_path(notebook_id, filename)
+                        .map_err(sync_error)?
+                        .is_some()
+                }
+                Err(error) => return Err(sync_error(error)),
+            };
+            let old_path = is_indexed.then(|| desired_path.clone());
             if desired_path.exists() && old_path.as_ref() != Some(&desired_path) {
                 memo_file
-                    .register_existing_file_for_notebook_id(notebook_id, &desired_path)
+                    .refresh_note_path(notebook_id, filename)
                     .map_err(sync_error)?;
+                crate::commands::path_change::NotebookPathInvalidated::new(
+                    notebook_id.to_string(),
+                    filename.to_string(),
+                )
+                .emit(app);
                 if std::fs::read(&desired_path).map_err(sync_error)? != *bytes {
                     return Err(format!(
                         "CLOUD_PATH_COLLISION: local file preserved at {filename}"
@@ -270,10 +299,9 @@ fn apply_v2_note_changes(
             if matches!(&old_path, Some(path) if path == &desired_path)
                 && disk_hash.as_deref() == Some(expected_hash)
             {
-                let memo = memo_file
-                    .register_existing_file_for_notebook_id(notebook_id, &desired_path)
+                memo_file
+                    .refresh_note_path(notebook_id, filename)
                     .map_err(sync_error)?;
-                let _ = memo;
                 continue;
             }
 
@@ -338,29 +366,19 @@ fn apply_v2_note_changes(
                     ));
                 }
             }
-            let memo = memo_file
-                .register_existing_file_for_notebook_id(notebook_id, &desired_path)
+            memo_file
+                .refresh_note_path(notebook_id, filename)
                 .map_err(sync_error)?;
             if let Some(path) = old_path.filter(|path| path != &desired_path) {
                 if path.exists() {
                     std::fs::remove_file(&path).map_err(sync_error)?;
                 }
             }
-            memo_events::emit(
-                app,
-                MemoEvent::Updated {
-                    id: memo.id.clone(),
-                    path: desired_path.to_string_lossy().into_owned(),
-                    notebook_id: notebook_id.to_string(),
-                    derived_changed: MemoDerivedChanged {
-                        tags: true,
-                        todos: true,
-                        agents: true,
-                    },
-                    memo,
-                    source: MemoChangeSource::CloudSync,
-                },
-            );
+            crate::commands::path_change::NotebookPathInvalidated::new(
+                notebook_id.to_string(),
+                filename.to_string(),
+            )
+            .emit(app);
         }
     }
     Ok(())
@@ -412,13 +430,6 @@ pub(crate) fn apply_v2_report(
                 .is_some_and(|(_, _, _, deleted)| *deleted);
             if deleted {
                 changed = true;
-                if state.agent_access.remove_notebook(&config.id) {
-                    crate::events::emit_to(
-                        app,
-                        crate::commands::agent_access::AGENT_ACCESS_CHANGED_EVENT,
-                        (),
-                    );
-                }
             }
             !deleted
         });
@@ -451,6 +462,11 @@ pub(crate) fn apply_v2_report(
                 .write_notebook_configs(&configs)
                 .map_err(sync_error)?;
             drop(memo_file);
+            crate::events::emit_to(
+                app,
+                crate::commands::agent_workspace::AGENT_WORKSPACE_CHANGED_EVENT,
+                (),
+            );
             crate::events::emit_to(app, crate::commands::notebook::NOTEBOOKS_CHANGED_EVENT, ());
             crate::commands::helpers::refresh_watcher_roots(state, app);
         }
diff --git a/app/flowix-desktop/src/commands/collection.rs b/app/flowix-desktop/src/commands/collection.rs
index 630378122..205cf64a4 100644
--- a/app/flowix-desktop/src/commands/collection.rs
+++ b/app/flowix-desktop/src/commands/collection.rs
@@ -2,7 +2,7 @@
 use crate::{app::state::AppState, lock_utils::read_lock};
 use flowix_core::{
     collection::{
-        valid_id, validate_properties, CollectionDocument, CollectionPlacement, CollectionProperty,
+        display_name_for_path, valid_id, validate_properties, CollectionDocument, CollectionPlacement, CollectionProperty,
         CollectionType,
     },
     memo_file::{
@@ -269,7 +269,7 @@ impl CollectionCatalog {
             Ok(document) => {
                 item.collection_type = document.collection.kind;
                 item.collection_id = Some(document.collection.id.clone());
-                item.name = document.collection.name.clone();
+                item.name = display_name_for_path(path, document.collection.placement);
                 item.schema_version = Some(document.schema_version);
                 item.payload_schema_version = document.payload["schema_version"].as_i64();
                 item.revision = Some(document.collection.revision);
@@ -535,7 +535,7 @@ impl CollectionCatalog {
                 let (item, _, content, document) = self.read(&operation.collection_id)?;
                 complete(&CollectionMutationResult {
                     operation_id: operation.operation_id.clone(), status: "completed".into(),
-                    collection_id: operation.collection_id.clone(), actual_name: document.collection.name,
+                    collection_id: operation.collection_id.clone(), actual_name: item.name.clone(),
                     previous_relative_path: operation.previous_path.clone(), notebook_path: self.root.to_string_lossy().into_owned(),
                     actual_relative_path: item.relative_path, actual_revision: document.collection.revision,
                     index_sequence: item.index_sequence, content, error_code: None,
@@ -639,7 +639,7 @@ impl CollectionCatalog {
             let path = self.root.join(&item.relative_path);
             let source = fs::read_to_string(&path).map_err(|error| error.to_string())?;
             let mut document = CollectionDocument::parse(&source)?.normalized_v2()?;
-            if !document.rebase_paths(&previous, &next) { continue; }
+            if !document.rebase_paths_for_notebook(&self.notebook_id, &previous, &next)? { continue; }
             document.revise()?;
             if fs::read_to_string(&path).map_err(|error| error.to_string())? != source {
                 return Err("COLLECTION_CONTENT_CONFLICT".into());
@@ -775,17 +775,19 @@ fn target_relative_path(
     }
 
     if document.collection.placement == CollectionPlacement::Folder {
+        let name = request.new_name.as_deref().ok_or("INVALID_COLLECTION_NAME")?.trim();
         let folder = Path::new(&item.relative_path).parent()
             .filter(|path| !path.as_os_str().is_empty())
             .ok_or("NOTEBOOK_ROOT_RENAME_FORBIDDEN")?;
         return Ok(folder.parent().unwrap_or(Path::new(""))
-            .join(&document.collection.name).join(".index.yaml")
+            .join(name).join(".index.yaml")
             .to_string_lossy().replace('\\', "/"));
     }
+    let name = request.new_name.as_deref().ok_or("INVALID_COLLECTION_NAME")?.trim();
     Ok(Path::new(&item.relative_path)
         .parent()
         .unwrap_or(Path::new(""))
-        .join(format!("{}.index.yaml", document.collection.name))
+        .join(format!("{}.index.yaml", name))
         .to_string_lossy()
         .replace('\\', "/"))
 }
@@ -910,7 +912,6 @@ fn mutate_locked(
             {
                 return Err("INVALID_COLLECTION_NAME".into());
             }
-            document.collection.name = name.to_owned();
         }
         if let Some(patch) = &request.properties {
             for (key, value) in patch {
@@ -976,11 +977,13 @@ fn mutate_locked(
             || (request.target_relative_path.is_some() && document.schema_version == 1);
         if rewrite_content {
             document = document.normalized_v2()?;
+            document.normalize_media_resource_ids(&request.notebook_id)?;
             if directory_move {
-                document.rebase_paths(
+                document.rebase_paths_for_notebook(
+                    &request.notebook_id,
                     &Path::new(&item.relative_path).parent().ok_or("INVALID_COLLECTION_PATH")?.to_string_lossy().replace('\\', "/"),
                     &Path::new(&target_relative).parent().ok_or("INVALID_COLLECTION_PATH")?.to_string_lossy().replace('\\', "/"),
-                );
+                )?;
             }
             document.revise()?;
         }
@@ -1092,13 +1095,38 @@ pub async fn mutate_collection(
 ) -> Result<CollectionMutationResult, String> {
     let memo = state.memo_file.clone();
     crate::commands::document_operations::run("mutate_collection", operation_id, window.label().to_owned(), move||{
-        let result=mutate_with_completion(&read_lock(&memo,"memo_file"),&request, &|result| emit_mutation_result(&app, &request.notebook_id, result))?;
+        let memo = read_lock(&memo, "memo_file");
+        // Recovery may finish a prior directory move too, so protect the
+        // notebook's open documents until completion has rebased their leases.
+        let _watch_move = memo.get_notebook_config_by_id(&request.notebook_id)
+            .and_then(|notebook| crate::commands::external_document_watch::begin_path_move(&app, Path::new(&notebook.path)));
+        let result=mutate_with_completion(&memo,&request, &|result| emit_mutation_result(&app, &request.notebook_id, result))?;
         Ok(result)
     }).await
 }
 
+pub(crate) fn path_change_for_result(notebook_id: &str, result: &CollectionMutationResult) -> Option<super::path_change::NotebookPathMove> {
+    let (previous, next, directory) = match &result.directory_move {
+        Some(moved) => (&moved.previous_relative_path, &moved.relative_path, true),
+        None if result.previous_relative_path != result.actual_relative_path =>
+            (&result.previous_relative_path, &result.actual_relative_path, false),
+        None => return None,
+    };
+    Some(super::path_change::NotebookPathMove {
+        change_id: format!("collection:{}:{}", notebook_id, result.operation_id),
+        notebook_id: notebook_id.to_owned(), previous_relative_path: previous.clone(),
+        relative_path: next.clone(), directory,
+    })
+}
+
 pub(crate) fn emit_mutation_result(app: &tauri::AppHandle, notebook_id: &str, result: &CollectionMutationResult) {
-    let _=app.emit("collection-changed",serde_json::json!({"notebookId":notebook_id,"collectionId":result.collection_id,"operationId":result.operation_id,"indexSequence":result.index_sequence,"relativePath":result.actual_relative_path,"previousRelativePath":result.previous_relative_path,"notebookPath":result.notebook_path,"name":result.actual_name,"revision":result.actual_revision}));
+    if let Some(moved) = &result.directory_move {
+        let root = Path::new(&result.notebook_path);
+        crate::commands::external_document_watch::rebase_path(
+            app, &root.join(&moved.previous_relative_path), &root.join(&moved.relative_path),
+        );
+    }
+    let _=app.emit("collection-changed",serde_json::json!({"notebookId":notebook_id,"collectionId":result.collection_id,"operationId":result.operation_id,"indexSequence":result.index_sequence,"relativePath":result.actual_relative_path,"previousRelativePath":result.previous_relative_path,"notebookPath":result.notebook_path,"name":result.actual_name,"revision":result.actual_revision,"directoryMove":result.directory_move}));
     if let Some(moved) = &result.directory_move {
         if let Some(state) = app.try_state::<AppState>() {
             let root = Path::new(&result.notebook_path);
@@ -1107,12 +1135,9 @@ pub(crate) fn emit_mutation_result(app: &tauri::AppHandle, notebook_id: &str, re
                 &root.join(&moved.previous_relative_path).to_string_lossy(), &root.join(&moved.relative_path).to_string_lossy(),
             ) { tracing::warn!(notebook_id, "agent references after collection folder move failed: {error}"); }
         }
-        let _ = app.emit("flowix:path-note-changed", serde_json::json!({
-            "notebookId": notebook_id, "previousRelativePath": moved.previous_relative_path,
-            "relativePath": moved.relative_path, "kind": "path", "directory": true, "deleted": false,
-        }));
-        let _ = app.emit("file-management-changed", serde_json::json!({ "notebookId": notebook_id, "notebookPath": result.notebook_path }));
+        let _ = app.emit("file-management-changed", serde_json::json!({ "notebookId": notebook_id, "notebookPath": result.notebook_path, "operationId": result.operation_id }));
     }
+    if let Some(change) = path_change_for_result(notebook_id, result) { change.emit(app); }
 }
 
 /// Tree and title actions share the same collection operation when the directory owns an index.
@@ -1133,6 +1158,7 @@ pub(crate) fn rename_folder_collection_at_path(memo: &MemoFile, folder: &Path, n
         expected_revision: document.collection.revision, operation_id: uuid::Uuid::now_v7().to_string(),
         new_name: Some(name.to_owned()), target_relative_path: None, properties: None,
     };
+    let _watch_move = crate::commands::external_document_watch::begin_path_move(app, Path::new(&notebook.path));
     let result = mutate_with_completion(memo, &request, &|result| emit_mutation_result(app, &request.notebook_id, result))?;
     Ok(Some((notebook.id, result)))
 }
@@ -1184,6 +1210,7 @@ pub async fn make_collection_identity_unique(
                         return Err("COLLECTION_ID_NOT_DUPLICATED".into());
                     }
                     document = document.normalized_v2()?;
+                    document.normalize_media_resource_ids(&notebook_id)?;
                     document.collection.id = format!("col_{}", uuid::Uuid::now_v7().simple());
                     document.revise()?;
                     atomic_write_bytes(&path, document.serialize()?.as_bytes())
@@ -1291,17 +1318,20 @@ mod tests {
         assert!(!root.join("Old").exists());
         assert!(root.join("New/note.md").is_file());
         let moved = memo.read_media_resource(&book, "New/photo.png").unwrap().unwrap();
-        assert_eq!(moved.id, resource.id);
+        assert_eq!(moved.id, flowix_core::memo_file::media_resource_id(&book, "New/photo.png").unwrap());
         assert_eq!(moved.properties["caption"], "keep");
         let next = CollectionDocument::parse(&result.content).unwrap();
         assert_eq!(next.collection.id, original.collection.id);
         assert_eq!(next.payload["dataset"]["records"]["include"][0]["relative_path"], "New/photo.png");
+        assert_eq!(next.payload["dataset"]["records"]["include"][0]["resource_id"], moved.id);
         let other = CollectionDocument::parse(&fs::read_to_string(root.join("Outside.lib.yaml")).unwrap()).unwrap();
         assert_eq!(other.collection.id, outside.collection.id);
         assert_eq!(other.collection.revision, 1);
         assert_eq!(other.payload["dataset"]["source"]["path"], "New");
         assert_eq!(other.payload["dataset"]["records"]["include"][0]["relative_path"], "New/photo.png");
+        assert_eq!(other.payload["dataset"]["records"]["include"][0]["resource_id"], moved.id);
         assert_eq!(other.payload["dataset"]["records"]["exclude"][0]["relative_path"], "New/hidden.png");
+        assert_eq!(other.payload["dataset"]["records"]["exclude"][0]["resource_id"], format!("{book}::New/hidden.png"));
         with_catalog(&memo, &book, |catalog| {
             assert_eq!(catalog.resolve(&child.collection.id)?.relative_path, "New/child/.index.yaml");
             Ok(())
diff --git a/app/flowix-desktop/src/commands/dialog.rs b/app/flowix-desktop/src/commands/dialog.rs
index c1397c221..f30920a87 100644
--- a/app/flowix-desktop/src/commands/dialog.rs
+++ b/app/flowix-desktop/src/commands/dialog.rs
@@ -6,14 +6,13 @@ use tauri_plugin_opener::OpenerExt;
 
 use crate::lock_utils::read_lock;
 
-use super::helpers::start_security_bookmark_access;
 use crate::app::state::AppState;
 
 // ==================== 鍩熷唴 helper ====================
 
+mod attachment_fingerprint;
 mod attachments;
 mod base64_input;
-mod attachment_fingerprint;
 mod upload_quota;
 pub(crate) mod upload_sessions;
 
@@ -21,60 +20,56 @@ pub(crate) mod upload_sessions;
 
 #[tauri::command]
 pub async fn select_directory(app: tauri::AppHandle) -> Option<String> {
-    use std::sync::mpsc;
-    #[cfg(not(target_os = "macos"))]
     use tauri_plugin_dialog::DialogExt;
-    #[cfg(not(target_os = "macos"))]
-    use tokio::task;
-
-    let (tx, rx) = mpsc::channel();
-
-    #[cfg(target_os = "macos")]
-    {
-        let handle = app.clone();
-        let state_handle = handle.clone();
-        handle
-            .run_on_main_thread(move || {
-                let result = crate::config::pick_directory_with_bookmark("选择笔记本文件夹").map(
-                    |(path, bookmark)| {
-                        let state = state_handle.state::<AppState>();
-                        if let Err(e) = state
-                            .security_bookmarks
-                            .record_directory_bookmark(Path::new(&path), bookmark)
-                        {
-                            tracing::warn!("[select_directory] failed to persist bookmark: {e}");
-                        }
-                        path
-                    },
-                );
-                tx.send(result).ok();
+    tokio::task::spawn_blocking(move || {
+        app.dialog()
+            .file()
+            .set_title("选择笔记本文件夹")
+            .blocking_pick_folder()
+            .map(|p| {
+                let path = Path::new(&p.to_string()).to_path_buf();
+                record_bookmark_directory(&app, &path);
+                path.to_string_lossy().into_owned()
             })
-            .ok()?;
-        return tokio::task::spawn_blocking(move || rx.recv().ok().flatten())
-            .await
-            .ok()
-            .flatten();
-    }
+    })
+    .await
+    .ok()
+    .flatten()
+}
 
-    #[cfg(not(target_os = "macos"))]
-    // Run blocking dialog in a background thread to avoid freezing the UI
+#[tauri::command]
+pub async fn select_import_directory(
+    app: tauri::AppHandle,
+    window: tauri::WebviewWindow,
+) -> Option<String> {
+    let generation = app
+        .state::<AppState>()
+        .document_access
+        .generation(window.label());
+    use tauri_plugin_dialog::DialogExt;
     let handle = app.clone();
-    #[cfg(not(target_os = "macos"))]
-    task::spawn_blocking(move || {
-        let result = handle
+    let window_label = window.label().to_owned();
+    tokio::task::spawn_blocking(move || {
+        handle
             .dialog()
             .file()
-            .set_title("选择笔记本文件夹")
+            .set_title("选择要导入的文件夹")
             .blocking_pick_folder()
-            .map(|p| p.to_string());
-        tx.send(result).ok();
-    });
-
-    #[cfg(not(target_os = "macos"))]
-    tokio::task::spawn_blocking(move || rx.recv().ok().flatten())
-        .await
-        .ok()
-        .flatten()
+            .and_then(|path| {
+                let path = Path::new(&path.to_string()).to_path_buf();
+                let granted = handle
+                    .state::<AppState>()
+                    .document_access
+                    .grant_directory_for_generation(&window_label, generation, &path);
+                if granted {
+                    record_bookmark_directory(&handle, &path);
+                }
+                granted.then(|| path.to_string_lossy().into_owned())
+            })
+    })
+    .await
+    .ok()
+    .flatten()
 }
 
 #[tauri::command]
@@ -133,11 +128,22 @@ pub async fn select_files(
                 .into_iter()
                 .filter_map(|path| {
                     let path = path.to_string();
-                    handle
+                    let granted = handle
                         .state::<AppState>()
                         .document_access
-                        .grant_for_generation(window.label(), generation, Path::new(&path))
-                        .then_some(path)
+                        .grant_for_generation(window.label(), generation, Path::new(&path));
+                    if granted {
+                        if let Err(error) = handle
+                            .state::<AppState>()
+                            .security_bookmarks
+                            .record_file(Path::new(&path))
+                        {
+                            tracing::warn!(%error, "cannot persist selected file bookmark");
+                        }
+                        Some(path)
+                    } else {
+                        None
+                    }
                 })
                 .collect::<Vec<String>>()
         });
@@ -148,6 +154,22 @@ pub async fn select_files(
     .flatten()
 }
 
+fn record_bookmark_directory(app: &tauri::AppHandle, path: &Path) {
+    #[cfg(target_os = "macos")]
+    if let Err(error) = app
+        .state::<AppState>()
+        .security_bookmarks
+        .record_directory(path)
+    {
+        tracing::warn!(
+            "failed to persist macOS folder bookmark for {}: {error}",
+            path.display()
+        );
+    }
+    #[cfg(not(target_os = "macos"))]
+    let _ = (app, path);
+}
+
 #[tauri::command]
 pub async fn save_file_dialog(
     app: tauri::AppHandle,
@@ -215,7 +237,6 @@ pub async fn save_notebook_asset(
 ) -> Result<Option<attachments::SavedNotebookAsset>, String> {
     let permit = upload_quota::UPLOAD_QUOTA.acquire()?;
     let source = Path::new(&source_path);
-    start_security_bookmark_access(&state, source);
     let source = dunce::canonicalize(source).map_err(|error| error.to_string())?;
     if !super::helpers::can_access_document_path(&source, window.label(), &state) {
         return Err("Notebook asset source is not authorized".to_string());
@@ -240,7 +261,6 @@ pub async fn save_notebook_asset(
                 .map_err(|error| error.to_string())?;
         attachments::notebook_root(&store, Some(&owner)).map_err(|error| error.to_string())?
     };
-    start_security_bookmark_access(&state, &root);
     // Notebook-local assets are already durable workspace files. Return their
     // canonical path instead of making an attachment copy.
     if reuse_notebook_file.unwrap_or(false) && source.starts_with(&root) {
@@ -291,8 +311,6 @@ pub async fn copy_attachment_file(
     .map_err(|error| error.to_string())?;
     let source = source.as_path();
 
-    start_security_bookmark_access(&state, source);
-    start_security_bookmark_access(&state, Path::new(&target_path));
     let mut reader = fs::File::open(source).map_err(|error| error.to_string())?;
     state
         .export_access
@@ -319,7 +337,6 @@ pub async fn open_attachment_file(
     .map_err(|error| error.to_string())?;
     let source = source.as_path();
 
-    start_security_bookmark_access(&state, source);
     app.opener()
         .open_path(source.display().to_string(), None::<String>)
         .map_err(|e| e.to_string())
diff --git a/app/flowix-desktop/src/commands/dialog/attachment_fingerprint.rs b/app/flowix-desktop/src/commands/dialog/attachment_fingerprint.rs
index f94635e53..49af01751 100644
--- a/app/flowix-desktop/src/commands/dialog/attachment_fingerprint.rs
+++ b/app/flowix-desktop/src/commands/dialog/attachment_fingerprint.rs
@@ -1,6 +1,6 @@
+use sha2::{Digest, Sha256};
 use std::fs::File;
 use std::io::{self, Read, Seek, SeekFrom};
-use sha2::{Digest, Sha256};
 
 pub(super) fn fingerprint(file: &mut File) -> io::Result<(String, u64)> {
     file.seek(SeekFrom::Start(0))?;
diff --git a/app/flowix-desktop/src/commands/dialog/attachments/tests.rs b/app/flowix-desktop/src/commands/dialog/attachments/tests.rs
index 31c5ad044..0eed96473 100644
--- a/app/flowix-desktop/src/commands/dialog/attachments/tests.rs
+++ b/app/flowix-desktop/src/commands/dialog/attachments/tests.rs
@@ -39,19 +39,13 @@ fn explicit_destination_does_not_switch_current_notebook() {
 #[test]
 fn note_owner_resolves_notebook_from_absolute_path() {
     let (directory, store) = fixture();
-    let created = flowix_core::MemoService::new(&store)
-        .create_memo_named_with_tag_in_directory(
-            Some("second"),
-            None,
-            "Untitled",
-            "# Note\nbody\n",
-            None,
-        )
+    let created = flowix_core::NoteService::new(&store)
+        .create("second", None, "Untitled", "# Note\nbody\n")
         .unwrap();
     let note = directory
         .path()
         .join("second")
-        .join(&created.memo.relative_path);
+        .join(&created.entry.relative_path);
     assert_eq!(
         resolve_note_owner(&store, None, Some(note.to_str().unwrap())).unwrap(),
         ("second".to_string(), Some("Untitled.md".to_string()))
@@ -77,19 +71,13 @@ fn missing_or_unknown_owner_never_falls_back_to_current_notebook() {
 fn owned_save_validates_identity_before_creating_attachments() {
     let (directory, store) = fixture();
     assert!(save_for_owner(&store, None, None, "data", &mut &b"data"[..], false).is_err());
-    let created = flowix_core::MemoService::new(&store)
-        .create_memo_named_with_tag_in_directory(
-            Some("second"),
-            None,
-            "Untitled",
-            "# Owner\nbody\n",
-            None,
-        )
+    let created = flowix_core::NoteService::new(&store)
+        .create("second", None, "Untitled", "# Owner\nbody\n")
         .unwrap();
     let note = directory
         .path()
         .join("second")
-        .join(&created.memo.relative_path);
+        .join(&created.entry.relative_path);
     assert!(save_for_owner(
         &store,
         Some("first"),
diff --git a/app/flowix-desktop/src/commands/dialog/upload_sessions.rs b/app/flowix-desktop/src/commands/dialog/upload_sessions.rs
index 5c01c4858..eaa35ecdd 100644
--- a/app/flowix-desktop/src/commands/dialog/upload_sessions.rs
+++ b/app/flowix-desktop/src/commands/dialog/upload_sessions.rs
@@ -222,9 +222,6 @@ pub fn begin_attachment_upload(
     let store = read_lock(&state.memo_file, "memo_file");
     let (notebook_id, owner_note) = attachments::resolve_note_owner(&store, None, Some(&note_path))
         .map_err(|error| error.to_string())?;
-    let root = attachments::notebook_root(&store, Some(&notebook_id))
-        .map_err(|error| error.to_string())?;
-    super::start_security_bookmark_access(&state, &root);
     state.upload_sessions.begin(
         window.label(),
         generation,
diff --git a/app/flowix-desktop/src/commands/document_list.rs b/app/flowix-desktop/src/commands/document_list.rs
index 446baa029..c2fc7d46a 100644
--- a/app/flowix-desktop/src/commands/document_list.rs
+++ b/app/flowix-desktop/src/commands/document_list.rs
@@ -89,9 +89,9 @@ pub(crate) fn refresh_view_document_catalog(memo: &MemoFile, id: &str, root: &Pa
     }
 }
 
-fn rebase_collection_document_paths(source: &str, old_path: &str, new_path: &str) -> Option<String> {
+fn rebase_collection_document_paths(source: &str, notebook_id: &str, old_path: &str, new_path: &str) -> Option<String> {
     let mut document = flowix_core::collection::CollectionDocument::parse(source).ok()?.normalized_v2().ok()?;
-    if !document.rebase_paths(old_path, new_path) { return None; }
+    if !document.rebase_paths_for_notebook(notebook_id, old_path, new_path).ok()? { return None; }
     document.revise().ok()?;
     document.serialize().ok()
 }
@@ -215,7 +215,7 @@ pub(crate) fn rebase_collection_paths(
         let Ok(source) = fs::read_to_string(&path) else {
             continue;
         };
-        let Some(next) = rebase_collection_document_paths(&source, old_relative_path, new_relative_path)
+        let Some(next) = rebase_collection_document_paths(&source, notebook_id, old_relative_path, new_relative_path)
         else {
             continue;
         };
diff --git a/app/flowix-desktop/src/commands/document_shutdown.rs b/app/flowix-desktop/src/commands/document_shutdown.rs
deleted file mode 100644
index 7b58457f4..000000000
--- a/app/flowix-desktop/src/commands/document_shutdown.rs
+++ /dev/null
@@ -1,171 +0,0 @@
-use std::{
-    collections::HashSet,
-    sync::{Mutex, OnceLock},
-};
-use tauri::{AppHandle, Emitter};
-
-#[path = "document_shutdown_state.rs"]
-mod shutdown_state;
-
-#[derive(Default)]
-struct Shutdown {
-    windows: HashSet<String>,
-    waiting: Option<(u64, HashSet<String>, Completion)>,
-    sequence: u64,
-    approved: bool,
-}
-enum Completion {
-    Exit(i32),
-    #[cfg(windows)]
-    Prepared(tokio::sync::oneshot::Sender<UpdatePreparation>),
-}
-fn state() -> &'static Mutex<Shutdown> {
-    static STATE: OnceLock<Mutex<Shutdown>> = OnceLock::new();
-    STATE.get_or_init(Mutex::default)
-}
-
-#[tauri::command]
-pub fn register_document_window(window: tauri::WebviewWindow) {
-    state()
-        .lock()
-        .unwrap_or_else(|e| e.into_inner())
-        .windows
-        .insert(window.label().into());
-}
-
-pub fn forget_window(app: &AppHandle, label: &str) {
-    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
-    state.windows.remove(label);
-    finish_window(app, state, label);
-}
-
-/// Return false while registered editor windows protect their drafts.
-pub fn request_exit(app: &AppHandle, code: i32) -> bool {
-    begin_request(app, Completion::Exit(code))
-}
-
-/// Tauri's Windows updater uses process::exit, so saving must finish before
-/// handing it the installation payload. Cancellation never exits the app.
-#[cfg(windows)]
-pub async fn prepare_for_update(app: &AppHandle) -> Result<UpdatePreparation, String> {
-    let (sender, receiver) = tokio::sync::oneshot::channel();
-    begin_request(app, Completion::Prepared(sender));
-    receiver.await.map_err(|_| {
-        "Update cancelled: documents could not finish saving. Save your documents and retry."
-            .to_string()
-    })
-}
-
-/// Unfreeze the editor if launching installation fails or the task is cancelled.
-#[cfg(windows)]
-pub struct UpdatePreparation {
-    app: AppHandle,
-    request: u64,
-}
-#[cfg(windows)]
-impl Drop for UpdatePreparation {
-    fn drop(&mut self) {
-        let _ = self.app.emit("document:exit-cancelled", self.request);
-    }
-}
-
-fn begin_request(app: &AppHandle, completion: Completion) -> bool {
-    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
-    if (state.approved && matches!(&completion, Completion::Exit(_))) || state.windows.is_empty() {
-        #[cfg(windows)]
-        if let Completion::Prepared(sender) = completion {
-            let _ = sender.send(UpdatePreparation {
-                app: app.clone(),
-                request: 0,
-            });
-        }
-        return true;
-    }
-    if state.waiting.is_some() {
-        return false;
-    }
-    state.sequence += 1;
-    let request = state.sequence;
-    let windows = state.windows.clone();
-    state.waiting = Some((request, windows.clone(), completion));
-    drop(state);
-    let timeout_app = app.clone();
-    tauri::async_runtime::spawn(async move {
-        tokio::time::sleep(std::time::Duration::from_secs(20)).await;
-        if state_reset(request) {
-            let _ = timeout_app.emit("document:exit-cancelled", request);
-        }
-    });
-    for window in windows {
-        if let Err(error) = app.emit_to(&window, "document:prepare-exit", request) {
-            tracing::error!("cannot prepare document window for exit: {error}");
-            if state_reset(request) {
-                let _ = app.emit("document:exit-cancelled", request);
-            }
-        }
-    }
-    false
-}
-
-fn state_reset(request: u64) -> bool {
-    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
-    if state
-        .waiting
-        .as_ref()
-        .is_some_and(|(id, _, _)| *id == request)
-    {
-        state.waiting = None;
-        true
-    } else {
-        false
-    }
-}
-
-#[tauri::command]
-pub async fn flush_document_background() -> bool {
-    crate::document_derived::flush().await
-}
-
-#[tauri::command]
-pub fn finish_document_shutdown(
-    window: tauri::WebviewWindow,
-    app: AppHandle,
-    request: u64,
-    ready: bool,
-) {
-    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
-    let Some((active_request, _, _)) = state.waiting.as_ref() else {
-        return;
-    };
-    if *active_request != request {
-        return;
-    }
-    if !ready {
-        state.waiting = None;
-        drop(state);
-        let _ = app.emit("document:exit-cancelled", request);
-        return;
-    }
-    finish_window(&app, state, window.label());
-}
-
-/// Both acknowledgements and window destruction can release the last draft.
-fn finish_window(app: &AppHandle, mut state: std::sync::MutexGuard<'_, Shutdown>, label: &str) {
-    let Some((request, completion)) = shutdown_state::finish_window(&mut state.waiting, label)
-    else {
-        return;
-    };
-    state.approved = matches!(&completion, Completion::Exit(_));
-    drop(state);
-    match completion {
-        Completion::Exit(code) => app.exit(code),
-        #[cfg(windows)]
-        Completion::Prepared(sender) => {
-            // An unread queued guard is also dropped when an update is cancelled.
-            let _ = sender.send(UpdatePreparation {
-                app: app.clone(),
-                request,
-            });
-        }
-    }
-}
diff --git a/app/flowix-desktop/src/commands/document_shutdown_state.rs b/app/flowix-desktop/src/commands/document_shutdown_state.rs
deleted file mode 100644
index 2e2b6cac4..000000000
--- a/app/flowix-desktop/src/commands/document_shutdown_state.rs
+++ /dev/null
@@ -1,54 +0,0 @@
-use std::collections::HashSet;
-
-/// Release a ready or destroyed window and complete only after the last participant.
-pub(crate) fn finish_window<C>(
-    waiting: &mut Option<(u64, HashSet<String>, C)>,
-    label: &str,
-) -> Option<(u64, C)> {
-    if let Some((_, windows, _)) = waiting.as_mut() {
-        windows.remove(label);
-    }
-    if waiting
-        .as_ref()
-        .is_some_and(|(_, windows, _)| windows.is_empty())
-    {
-        waiting
-            .take()
-            .map(|(request, _, completion)| (request, completion))
-    } else {
-        None
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn pending() -> Option<(u64, HashSet<String>, i32)> {
-        Some((7, ["editor-a".into(), "editor-b".into()].into(), 42))
-    }
-
-    #[test]
-    fn acknowledgements_complete_only_after_last_window() {
-        let mut waiting = pending();
-        assert_eq!(finish_window(&mut waiting, "editor-a"), None);
-        assert_eq!(finish_window(&mut waiting, "editor-b"), Some((7, 42)));
-        assert!(waiting.is_none());
-        assert_eq!(finish_window(&mut waiting, "editor-b"), None);
-    }
-
-    #[test]
-    fn destruction_completes_only_after_last_pending_window() {
-        let mut waiting = pending();
-        assert_eq!(finish_window(&mut waiting, "unregistered-window"), None);
-        assert_eq!(finish_window(&mut waiting, "editor-b"), None);
-        assert_eq!(finish_window(&mut waiting, "editor-b"), None);
-        assert_eq!(finish_window(&mut waiting, "editor-a"), Some((7, 42)));
-    }
-
-    #[test]
-    fn cancellation_does_not_produce_completion() {
-        let mut waiting: Option<(u64, HashSet<String>, i32)> = None;
-        assert_eq!(finish_window(&mut waiting, "editor-a"), None);
-    }
-}
diff --git a/app/flowix-desktop/src/commands/dsh.rs b/app/flowix-desktop/src/commands/dsh.rs
index 3559149ef..3c5a0984b 100644
--- a/app/flowix-desktop/src/commands/dsh.rs
+++ b/app/flowix-desktop/src/commands/dsh.rs
@@ -1,7 +1,8 @@
-//! DSH Runtime installation and Flowix plugin integration commands.
+//! DSH discovery and Flowix plugin integration commands.
 
 use crate::app::state::AppState;
 use crate::events as dispatcher;
+use std::path::PathBuf;
 use tauri::State;
 
 pub const DSH_RUNTIME_STATUS_CHANGED_EVENT: &str = "dsh-runtime-status-changed";
@@ -11,125 +12,75 @@ fn emit_runtime_status(app: &tauri::AppHandle, status: &crate::dsh::DshStatus) {
 }
 
 #[tauri::command]
-pub fn dsh_status() -> crate::dsh::DshStatus {
+pub fn dsh_status(state: State<'_, AppState>) -> crate::dsh::DshStatus {
+    let selected = state.user_config.get_preference().dsh_cli_path.map(PathBuf::from);
+    crate::dsh::set_user_selected_cli(selected);
     crate::dsh::status()
 }
 
 #[tauri::command]
-pub async fn dsh_check_update() -> Result<crate::dsh::DshUpdateCheck, String> {
-    tauri::async_runtime::spawn_blocking(crate::dsh::check_for_update)
-        .await
-        .map_err(|error| format!("DSH update check task failed: {error}"))?
-}
-
-#[tauri::command]
-pub async fn dsh_archive_size() -> Option<u64> {
-    tauri::async_runtime::spawn_blocking(crate::dsh::latest_archive_size)
-        .await
-        .ok()
-        .flatten()
-}
+pub async fn dsh_select_cli_path(app: tauri::AppHandle) -> Option<String> {
+    use std::sync::mpsc;
+    use tauri_plugin_dialog::DialogExt;
 
-#[tauri::command]
-pub fn dsh_download_status() -> Option<crate::dsh::DshDownloadProgress> {
-    crate::dsh::download_progress()
+    let (tx, rx) = mpsc::channel();
+    let handle = app.clone();
+    tokio::task::spawn_blocking(move || {
+        let result = handle
+            .dialog()
+            .file()
+            .set_title("Select DSH executable")
+            .blocking_pick_file()
+            .map(|path| path.to_string());
+        let _ = tx.send(result);
+    });
+    rx.recv().ok().flatten()
 }
 
 #[tauri::command]
-pub async fn dsh_install_runtime(
+pub fn dsh_set_cli_path(
+    path: String,
     state: State<'_, AppState>,
     app: tauri::AppHandle,
 ) -> Result<crate::dsh::DshStatus, String> {
-    ensure_runtime_replaceable(&state).await?;
-    let manager = state.deepseek_harness.clone();
-    let install_app = app.clone();
-    let status = tauri::async_runtime::spawn_blocking(move || {
-        crate::dsh::install_runtime_with_progress_before_publish(Some(install_app), move || {
-            tauri::async_runtime::block_on(manager.invalidate_hosts())
-                .map_err(|error| format!("stop DeepSeek Harness before install: {error}"))
-        })
-    })
-    .await
-    .map_err(|error| format!("DSH installer task failed: {error}"))??;
-    emit_runtime_status(&app, &status);
-    Ok(status)
-}
-
-#[tauri::command]
-pub async fn dsh_update(
-    state: State<'_, AppState>,
-    app: tauri::AppHandle,
-) -> Result<crate::dsh::DshStatus, String> {
-    ensure_runtime_replaceable(&state).await?;
-    let manager = state.deepseek_harness.clone();
-    let update_app = app.clone();
-    let status = tauri::async_runtime::spawn_blocking(move || {
-        crate::dsh::install_runtime_with_progress_before_publish(Some(update_app), move || {
-            tauri::async_runtime::block_on(manager.invalidate_hosts())
-                .map_err(|error| format!("stop DeepSeek Harness before update: {error}"))
-        })
-    })
-    .await
-    .map_err(|error| format!("DSH updater task failed: {error}"))??;
-    emit_runtime_status(&app, &status);
-    Ok(status)
-}
-
-/// Start or resume the managed runtime installation/update through one
-/// command shared by the main window and Preferences.
-#[tauri::command]
-pub async fn dsh_ensure_runtime(
-    state: State<'_, AppState>,
-    app: tauri::AppHandle,
-) -> Result<crate::dsh::DshStatus, String> {
-    ensure_runtime_replaceable(&state).await?;
-    let manager = state.deepseek_harness.clone();
-    let ensure_app = app.clone();
-    let status = tauri::async_runtime::spawn_blocking(move || {
-        crate::dsh::install_runtime_with_progress_before_publish(Some(ensure_app), move || {
-            tauri::async_runtime::block_on(manager.invalidate_hosts())
-                .map_err(|error| format!("stop DeepSeek Harness before install/update: {error}"))
-        })
-    })
-    .await
-    .map_err(|error| format!("DSH ensure task failed: {error}"))??;
+    let path = PathBuf::from(path);
+    if !crate::dsh::is_valid_cli_path(&path) {
+        return Err("所选路径不是可执行的 DSH CLI".to_string());
+    }
+    state
+        .user_config
+        .patch_preference(serde_json::json!({"dshCliPath": path.to_string_lossy()}))
+        .map_err(|error| error.to_string())?;
+    crate::dsh::set_user_selected_cli(Some(path));
+    let status = crate::dsh::status();
     emit_runtime_status(&app, &status);
     Ok(status)
 }
 
-async fn ensure_runtime_replaceable(state: &State<'_, AppState>) -> Result<(), String> {
-    if crate::dsh::status().installed {
-        state
-            .deepseek_harness
-            .ensure_hosts_replaceable()
-            .await
-            .map_err(|error| format!("prepare DeepSeek Harness install/update: {error}"))?;
-    }
-    Ok(())
-}
-
-#[tauri::command]
-pub fn dsh_cancel_update() -> bool {
-    crate::dsh::cancel_update();
-    true
-}
-
-/// Shut down every running dsh-host, then remove the managed runtime tree.
-/// User state under `~/.dsh` (settings, sessions) is preserved; reinstalling
-/// from the Runtime tab restores a clean runtime.
+/// Install the Flowix App Server profile after the user requests it from
+/// Preferences. Runtime discovery at startup is read-only and never installs.
 #[tauri::command]
-pub async fn dsh_uninstall(
+pub async fn dsh_install_appserver_profile(
     state: State<'_, AppState>,
     app: tauri::AppHandle,
 ) -> Result<crate::dsh::DshStatus, String> {
     state
         .deepseek_harness
-        .prepare_uninstall()
-        .await
-        .map_err(|error| format!("stop DeepSeek Harness before uninstall: {error}"))?;
-    let status = tauri::async_runtime::spawn_blocking(crate::dsh::uninstall_runtime)
+        .ensure_hosts_replaceable()
         .await
-        .map_err(|error| format!("DSH uninstall task failed: {error}"))??;
+        .map_err(|error| format!("stop DSH before installing App Server: {error}"))?;
+    state.deepseek_harness.invalidate_hosts().await?;
+    let install_app = app.clone();
+    tauri::async_runtime::spawn_blocking(move || {
+        crate::dsh::install_appserver_profile(&install_app)
+    })
+    .await
+    .map_err(|error| format!("DSH App Server installer task failed: {error}"))??;
+    if let Err(error) = state.deepseek_harness.dsh_model_configs().await {
+        let _ = state.deepseek_harness.invalidate_hosts().await;
+        return Err(format!("DSH App Server 安装后连接检查失败：{error}"));
+    }
+    let status = crate::dsh::status();
     emit_runtime_status(&app, &status);
     Ok(status)
 }
diff --git a/app/flowix-desktop/src/commands/external_document.rs b/app/flowix-desktop/src/commands/external_document.rs
index 0d8f2e804..f5cad0972 100644
--- a/app/flowix-desktop/src/commands/external_document.rs
+++ b/app/flowix-desktop/src/commands/external_document.rs
@@ -8,17 +8,35 @@ use crate::app::state::AppState;
 use crate::commands::external_document_watch::ExternalDocumentWatchState;
 use crate::commands::helpers::{
     can_access_document_path, can_access_scoped_file, refresh_notebook_note_index,
-    start_security_bookmark_access,
 };
 use crate::lock_utils::read_lock;
 use flowix_core::memo_file::{FileWriteOutcome, MergedFileWriteOutcome};
 
 #[tauri::command]
-pub fn get_external_document_mime_type(file_path: String) -> String {
-    mime_guess::from_path(file_path)
-        .first_or_octet_stream()
-        .essence_str()
-        .to_string()
+pub async fn detect_external_document_text(
+    window: tauri::WebviewWindow,
+    file_path: String,
+    #[allow(non_snake_case)] scopePath: Option<String>,
+    app: tauri::AppHandle,
+) -> Result<bool, String> {
+    let window_label = window.label().to_string();
+    crate::document_io::run("external_document_text_detection", move || {
+        let state = app.state::<AppState>();
+        let path = PathBuf::from(file_path);
+        if !path.is_absolute() || !path.is_file() {
+            return Err("external document is unavailable".to_string());
+        }
+        if !can_access_document_path(&path, &window_label, &state)
+            && !can_access_scoped_file(&path, scopePath.as_deref(), &state)
+        {
+            return Err("external document is outside its authorized scope".to_string());
+        }
+
+        // A local file has no HTTP Content-Type header. This is only a text
+        // readability probe for unknown paths, not a MIME type resolver.
+        Ok(looks_like_utf8_text_file(&path))
+    })
+    .await?
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -185,7 +203,6 @@ pub(crate) fn exact_existing_external_path(
     {
         return Err("external document is outside its authorized scope".to_string());
     }
-    start_security_bookmark_access(state.inner(), &requested);
     if !supported_text_document_path(&requested) {
         return Err("external document is not a supported text file".to_string());
     }
diff --git a/app/flowix-desktop/src/commands/external_document_watch.rs b/app/flowix-desktop/src/commands/external_document_watch.rs
index 47840c359..3ee648bfb 100644
--- a/app/flowix-desktop/src/commands/external_document_watch.rs
+++ b/app/flowix-desktop/src/commands/external_document_watch.rs
@@ -30,6 +30,7 @@ struct WatchRegistry {
     delivering: HashSet<String>,
     delivery_epochs: HashMap<String, u64>,
     active_writes: HashMap<PathBuf, usize>,
+    active_path_moves: HashMap<usize, PathBuf>,
     completed_writes: HashMap<PathBuf, (String, String, String)>,
 }
 
@@ -47,7 +48,87 @@ struct ExternalDocumentChangedPayload {
 pub struct ExternalDocumentWatchState {
     registry: Arc<Mutex<WatchRegistry>>,
     watcher: Mutex<Option<RecommendedWatcher>>,
-    next_lease: AtomicUsize,
+    next_id: AtomicUsize,
+}
+
+// A local move can spend time updating indexes after the filesystem rename.
+// Keep old-path polls silent until its confirmed path mapping has been applied.
+pub(crate) struct PathMoveGuard {
+    registry: Arc<Mutex<WatchRegistry>>,
+    id: usize,
+}
+
+impl Drop for PathMoveGuard {
+    fn drop(&mut self) {
+        if let Ok(mut registry) = self.registry.lock() {
+            registry.active_path_moves.remove(&self.id);
+        }
+    }
+}
+
+fn watch_prefix(path: &Path) -> PathBuf {
+    // Resolve the parent even after a move, retaining the old basename for
+    // case-only renames on case-insensitive filesystems.
+    path.parent()
+        .and_then(|parent| dunce::canonicalize(parent).ok())
+        .zip(path.file_name())
+        .map(|(parent, name)| parent.join(name))
+        .unwrap_or_else(|| path.to_path_buf())
+}
+
+pub(crate) fn begin_path_move(app: &tauri::AppHandle, path: &Path) -> Option<PathMoveGuard> {
+    let state = app.try_state::<ExternalDocumentWatchState>()?;
+    let path = watch_prefix(path);
+    let mut registry = state.registry.lock().ok()?;
+    let id = state.next_id.fetch_add(1, Ordering::Relaxed);
+    registry.active_path_moves.insert(id, path);
+    Some(PathMoveGuard {
+        registry: state.registry.clone(),
+        id,
+    })
+}
+
+/// Called by both local mutations and confirmed native rename pairs before
+/// publishing the existing UI path-move event.
+pub(crate) fn rebase_path(app: &tauri::AppHandle, previous: &Path, next: &Path) {
+    if let Some(state) = app.try_state::<ExternalDocumentWatchState>() {
+        state.rebase_path(&watch_prefix(previous), &watch_prefix(next));
+    }
+}
+
+fn rebase_registry_paths(registry: &mut WatchRegistry, previous: &Path, next: &Path) {
+    if previous == next {
+        return;
+    }
+    let moved = registry
+        .leases
+        .iter()
+        .filter_map(|(id, lease)| {
+            let suffix = lease.path.strip_prefix(previous).ok()?;
+            Some((id.clone(), next.join(suffix)))
+        })
+        .collect::<Vec<_>>();
+    for (id, path) in moved {
+        registry.leases.get_mut(&id).expect("existing lease").path = path;
+        *registry.generations.entry(id.clone()).or_default() += 1;
+        invalidate_delivery(registry, &id);
+        // Preserve the last observed revision: a content change concurrent
+        // with the move must still be delivered at the new path.
+    }
+    // A native rename can arrive before the local command finishes. Its
+    // notification pause follows the prefix until the same guard is released.
+    for prefix in registry.active_path_moves.values_mut() {
+        if let Ok(suffix) = prefix.strip_prefix(previous) {
+            *prefix = next.join(suffix);
+        }
+    }
+    registry.path_ref_counts.clear();
+    for lease in registry.leases.values() {
+        *registry
+            .path_ref_counts
+            .entry(lease.path.clone())
+            .or_default() += 1;
+    }
 }
 
 impl ExternalDocumentWatchState {
@@ -72,7 +153,55 @@ impl ExternalDocumentWatchState {
         Self {
             registry,
             watcher: Mutex::new(watcher),
-            next_lease: AtomicUsize::new(1),
+            next_id: AtomicUsize::new(1),
+        }
+    }
+
+    fn rebase_path(&self, previous: &Path, next: &Path) {
+        let Ok(mut registry) = self.registry.lock() else {
+            return;
+        };
+        if previous == next {
+            return;
+        }
+        let old_paths = registry
+            .path_ref_counts
+            .keys()
+            .cloned()
+            .collect::<HashSet<_>>();
+        let moved_paths = old_paths
+            .iter()
+            .filter_map(|path| {
+                path.strip_prefix(previous)
+                    .ok()
+                    .map(|suffix| next.join(suffix))
+            })
+            .collect::<HashSet<_>>();
+        rebase_registry_paths(&mut registry, previous, next);
+        if moved_paths.is_empty() {
+            return;
+        }
+        // Use the same registry -> watcher lock order as registration. Keep
+        // lease changes and native watch changes together for concurrent opens.
+        let Ok(mut watcher) = self.watcher.lock() else {
+            return;
+        };
+        if let Some(watcher) = watcher.as_mut() {
+            for path in &old_paths {
+                if !registry.path_ref_counts.contains_key(path) {
+                    watcher.unwatch(path).ok();
+                }
+            }
+            for path in &moved_paths {
+                watcher.unwatch(path).ok();
+                if let Err(error) = watcher.watch(path, RecursiveMode::NonRecursive) {
+                    // Revision polling remains available if native rebinding fails.
+                    tracing::warn!(
+                        "[external-watch] failed to watch moved path {}: {error}",
+                        path.display()
+                    );
+                }
+            }
         }
     }
 
@@ -80,7 +209,7 @@ impl ExternalDocumentWatchState {
         let lease_id = format!(
             "external-watch:{}:{}",
             window_label,
-            self.next_lease.fetch_add(1, Ordering::Relaxed)
+            self.next_id.fetch_add(1, Ordering::Relaxed)
         );
 
         let mut registry = self
@@ -179,7 +308,10 @@ impl ExternalDocumentWatchState {
 
     pub fn begin_window_write(&self, path: &Path) {
         if let Ok(mut registry) = self.registry.lock() {
-            *registry.active_writes.entry(path.to_path_buf()).or_default() += 1;
+            *registry
+                .active_writes
+                .entry(path.to_path_buf())
+                .or_default() += 1;
         }
     }
 
@@ -214,7 +346,9 @@ impl ExternalDocumentWatchState {
                     if written_revision == file_revision(path)
                         && std::fs::read_to_string(path).is_ok_and(|disk| disk == written_content)
                     {
-                        let leases = registry.leases.iter()
+                        let leases = registry
+                            .leases
+                            .iter()
                             .filter(|(_, lease)| lease.path == path)
                             .map(|(id, lease)| (id.clone(), lease.clone()))
                             .collect::<Vec<_>>();
@@ -222,7 +356,11 @@ impl ExternalDocumentWatchState {
                             invalidate_delivery(&mut registry, &id);
                             let delivered = lease.window_label == origin
                                 || emit_external_document_changed(
-                                    app, &lease, written_revision.clone(), "user_edit", Some(&origin),
+                                    app,
+                                    &lease,
+                                    written_revision.clone(),
+                                    "user_edit",
+                                    Some(&origin),
                                 );
                             if delivered {
                                 registry.revisions.insert(id, written_revision.clone());
@@ -301,22 +439,18 @@ fn emit_if_revision_changed(
     lease_id: &str,
     lease: &WatchLease,
 ) {
-    let revision = file_revision(&lease.path);
-    let delivery_epoch = {
-        let Ok(mut registry) = registry.lock() else {
-            return;
-        };
-        try_claim_revision(&mut registry, lease_id, &lease.path, &revision)
-            .then(|| registry.delivery_epochs.get(lease_id).copied())
-            .flatten()
-    };
-    let Some(delivery_epoch) = delivery_epoch else {
+    // Serialize claim + emission with path rebasing. Otherwise a poll can
+    // claim an old-path deletion, then emit it after the lease has moved.
+    let Ok(mut registry) = registry.lock() else {
         return;
     };
-    let delivered = emit_external_document_changed(app, lease, revision.clone(), "external", None);
-    if let Ok(mut registry) = registry.lock() {
-        complete_revision_delivery(&mut registry, lease_id, delivery_epoch, delivered, revision);
+    let revision = file_revision(&lease.path);
+    if !try_claim_revision(&mut registry, lease_id, &lease.path, &revision) {
+        return;
     }
+    let delivery_epoch = registry.delivery_epochs[lease_id];
+    let delivered = emit_external_document_changed(app, lease, revision.clone(), "external", None);
+    complete_revision_delivery(&mut registry, lease_id, delivery_epoch, delivered, revision);
 }
 
 /// Pure state transition: mark a lease as "delivering" for a given revision.
@@ -330,22 +464,33 @@ fn try_claim_revision(
     lease_path: &Path,
     revision: &str,
 ) -> bool {
-    if registry.active_writes.contains_key(lease_path)
-        || registry.leases
-        .get(lease_id)
-        .is_none_or(|current| current.path != lease_path)
+    if registry
+        .active_path_moves
+        .values()
+        .any(|prefix| lease_path.starts_with(prefix))
+        || registry.active_writes.contains_key(lease_path)
+        || registry
+            .leases
+            .get(lease_id)
+            .is_none_or(|current| current.path != lease_path)
         || registry.revisions.get(lease_id).map(String::as_str) == Some(revision)
         || registry.delivering.contains(lease_id)
     {
         return false;
     }
     registry.delivering.insert(lease_id.to_string());
-    *registry.delivery_epochs.entry(lease_id.to_string()).or_default() += 1;
+    *registry
+        .delivery_epochs
+        .entry(lease_id.to_string())
+        .or_default() += 1;
     true
 }
 
 fn invalidate_delivery(registry: &mut WatchRegistry, lease_id: &str) {
-    *registry.delivery_epochs.entry(lease_id.to_string()).or_default() += 1;
+    *registry
+        .delivery_epochs
+        .entry(lease_id.to_string())
+        .or_default() += 1;
     registry.delivering.remove(lease_id);
 }
 
@@ -521,6 +666,193 @@ pub fn unwatch_external_document(
 mod tests {
     use super::*;
 
+    fn add_lease(registry: &mut WatchRegistry, id: &str, path: &Path) {
+        registry.leases.insert(
+            id.into(),
+            WatchLease {
+                window_label: id.into(),
+                path: path.into(),
+            },
+        );
+        *registry.path_ref_counts.entry(path.into()).or_default() += 1;
+        registry.revisions.insert(id.into(), file_revision(path));
+    }
+
+    #[test]
+    fn native_watch_is_rebound_to_the_moved_document() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = dunce::canonicalize(temp.path()).unwrap();
+        let old = root.join("Old");
+        let new = root.join("New");
+        std::fs::create_dir(&old).unwrap();
+        let old_note = old.join("note.md");
+        let new_note = new.join("note.md");
+        std::fs::write(&old_note, "original").unwrap();
+        let (tx, rx) = std::sync::mpsc::channel();
+        let mut watcher = notify::recommended_watcher(move |event| {
+            let _ = tx.send(event);
+        })
+        .unwrap();
+        watcher
+            .watch(&old_note, RecursiveMode::NonRecursive)
+            .unwrap();
+        let mut registry = WatchRegistry::default();
+        add_lease(&mut registry, "main", &old_note);
+        let state = ExternalDocumentWatchState {
+            registry: Arc::new(Mutex::new(registry)),
+            watcher: Mutex::new(Some(watcher)),
+            next_id: AtomicUsize::new(2),
+        };
+        std::fs::rename(&old, &new).unwrap();
+        state.rebase_path(&old, &new);
+        std::fs::write(&new_note, "external change at the new path").unwrap();
+        let deadline = std::time::Instant::now() + Duration::from_secs(5);
+        loop {
+            let remaining = deadline.saturating_duration_since(std::time::Instant::now());
+            let event = rx
+                .recv_timeout(remaining)
+                .expect("native event for the moved file")
+                .unwrap();
+            if event
+                .paths
+                .iter()
+                .any(|path| event_matches_watched_file(path, &new_note))
+            {
+                break;
+            }
+        }
+        assert_eq!(state.registry.lock().unwrap().leases["main"].path, new_note);
+    }
+
+    #[test]
+    fn folder_move_preserves_revisions_and_rejects_stale_deletes_across_windows() {
+        let temp = tempfile::tempdir().unwrap();
+        let old = temp.path().join("Old");
+        let new = temp.path().join("New");
+        std::fs::create_dir_all(old.join("sub")).unwrap();
+        let old_note = old.join("sub/note.md");
+        let new_note = new.join("sub/note.md");
+        std::fs::write(&old_note, "original").unwrap();
+        let mut registry = WatchRegistry::default();
+        add_lease(&mut registry, "main", &old_note);
+        add_lease(&mut registry, "second", &old_note);
+        let unrelated = temp.path().join("Old-other/note.md");
+        add_lease(&mut registry, "other", &unrelated);
+        // An already-registered destination must share its native watch.
+        add_lease(&mut registry, "destination", &new_note);
+        assert!(try_claim_revision(
+            &mut registry,
+            "main",
+            &old_note,
+            "stale"
+        ));
+        let stale_epoch = registry.delivery_epochs["main"];
+        let observed = registry.revisions["main"].clone();
+
+        std::fs::rename(&old, &new).unwrap();
+        rebase_registry_paths(&mut registry, &old, &new);
+        rebase_registry_paths(&mut registry, &old, &new); // duplicate native rename pair
+        assert_eq!(registry.leases["main"].path, new_note);
+        assert_eq!(registry.leases["second"].path, new_note);
+        assert_eq!(registry.leases["other"].path, unrelated);
+        assert_eq!(registry.path_ref_counts[&new_note], 3);
+        assert!(!registry.path_ref_counts.contains_key(&old_note));
+        assert!(!try_claim_revision(
+            &mut registry,
+            "main",
+            &old_note,
+            "deleted"
+        ));
+        complete_revision_delivery(&mut registry, "main", stale_epoch, true, "deleted".into());
+        assert_eq!(registry.revisions["main"], observed);
+        assert!(!try_claim_revision(
+            &mut registry,
+            "main",
+            &new_note,
+            &file_revision(&new_note)
+        ));
+
+        std::fs::write(&new_note, "genuine external content change").unwrap();
+        let changed = file_revision(&new_note);
+        assert!(try_claim_revision(
+            &mut registry,
+            "main",
+            &new_note,
+            &changed
+        ));
+        let epoch = registry.delivery_epochs["main"];
+        complete_revision_delivery(&mut registry, "main", epoch, true, changed);
+        std::fs::remove_file(&new_note).unwrap();
+        assert!(try_claim_revision(
+            &mut registry,
+            "main",
+            &new_note,
+            &file_revision(&new_note)
+        ));
+        assert_eq!(decrement_path_ref_count(&mut registry, &new_note), None);
+        assert_eq!(registry.path_ref_counts[&new_note], 2);
+    }
+
+    #[test]
+    fn path_move_guard_defers_only_its_subtree_and_releases_on_failure() {
+        let prefix = PathBuf::from("/notes/old");
+        let note = prefix.join("note.md");
+        let other = PathBuf::from("/notes/old-other/note.md");
+        let registry = Arc::new(Mutex::new(WatchRegistry::default()));
+        {
+            let mut state = registry.lock().unwrap();
+            add_lease(&mut state, "note", &note);
+            add_lease(&mut state, "other", &other);
+            state.active_path_moves.insert(1, prefix.clone());
+            state.active_path_moves.insert(2, prefix.clone());
+            assert!(!try_claim_revision(&mut state, "note", &note, "deleted"));
+            assert!(try_claim_revision(&mut state, "other", &other, "changed"));
+        }
+        let outer = PathMoveGuard {
+            registry: registry.clone(),
+            id: 1,
+        };
+        let inner = PathMoveGuard {
+            registry: registry.clone(),
+            id: 2,
+        };
+        drop(inner);
+        {
+            let mut state = registry.lock().unwrap();
+            assert_eq!(state.active_path_moves.len(), 1);
+            let next = Path::new("/notes/new");
+            rebase_registry_paths(&mut state, &prefix, next);
+            assert_eq!(state.active_path_moves[&1], next);
+            assert!(!try_claim_revision(
+                &mut state,
+                "note",
+                &next.join("note.md"),
+                "changed"
+            ));
+        }
+        drop(outer); // also runs when a mutation returns an error
+        let mut state = registry.lock().unwrap();
+        assert!(state.active_path_moves.is_empty());
+        assert!(try_claim_revision(
+            &mut state,
+            "note",
+            Path::new("/notes/new/note.md"),
+            "genuine-delete"
+        ));
+    }
+
+    #[test]
+    fn case_only_move_updates_the_lease_spelling() {
+        let mut registry = WatchRegistry::default();
+        add_lease(&mut registry, "note", Path::new("/notes/Old/a.md"));
+        rebase_registry_paths(
+            &mut registry,
+            Path::new("/notes/Old"),
+            Path::new("/notes/old"),
+        );
+        assert_eq!(registry.leases["note"].path, Path::new("/notes/old/a.md"));
+    }
+
     #[test]
     fn file_reference_count_releases_only_the_last_lease() {
         let path = PathBuf::from("/tmp/flowix-external-watch/Reference.md");
@@ -593,11 +925,20 @@ mod tests {
     fn local_write_defers_file_notifications_until_write_settles() {
         let path = PathBuf::from("/tmp/flowix-external-watch/docs/Reference.md");
         let mut registry = WatchRegistry::default();
-        registry.leases.insert("lease".into(), WatchLease {
-            window_label: "main".into(), path: path.clone(),
-        });
+        registry.leases.insert(
+            "lease".into(),
+            WatchLease {
+                window_label: "main".into(),
+                path: path.clone(),
+            },
+        );
         registry.active_writes.insert(path.clone(), 1);
-        assert!(!try_claim_revision(&mut registry, "lease", &path, "changed"));
+        assert!(!try_claim_revision(
+            &mut registry,
+            "lease",
+            &path,
+            "changed"
+        ));
         registry.active_writes.remove(&path);
         assert!(try_claim_revision(&mut registry, "lease", &path, "changed"));
     }
@@ -637,9 +978,13 @@ mod tests {
         let path = PathBuf::from("/tmp/flowix-external-watch/docs/Reference.md");
         let lease_id = "lease".to_string();
         let mut registry = WatchRegistry::default();
-        registry.leases.insert(lease_id.clone(), WatchLease {
-            window_label: "main".into(), path: path.clone(),
-        });
+        registry.leases.insert(
+            lease_id.clone(),
+            WatchLease {
+                window_label: "main".into(),
+                path: path.clone(),
+            },
+        );
         assert!(try_claim_revision(&mut registry, &lease_id, &path, "old"));
         let old_epoch = registry.delivery_epochs[&lease_id];
 
diff --git a/app/flowix-desktop/src/commands/file.rs b/app/flowix-desktop/src/commands/file.rs
index 50ea0a54e..5f108dbd8 100644
--- a/app/flowix-desktop/src/commands/file.rs
+++ b/app/flowix-desktop/src/commands/file.rs
@@ -16,18 +16,35 @@ use crate::config::path_is_inside;
 use crate::lock_utils::read_lock;
 use flowix_core::memo_file::{
     media_kind_for_path, notebook_path_from_relative, FileManagementPolicy, MediaResourceKind,
-    MemoColor, MemoFile,
+    NoteColor, MemoFile,
 };
 use sha2::{Digest, Sha256};
 use tokio::sync::{Notify, Semaphore};
 
 use super::helpers::{
-    can_access_document_path, can_access_scoped_file, is_agent_access_folder,
+    can_access_document_path, can_access_scoped_file, is_attached_notebook_directory,
     is_internal_notebook_path, is_registered_notebook_path, is_registered_notebook_root,
-    refresh_notebook_note_index, start_security_bookmark_access,
+    refresh_notebook_note_index, FileOperationFailure,
 };
 use crate::app::state::AppState;
 
+pub mod folder_import;
+
+#[cfg(target_os = "macos")]
+fn is_cloud_file_not_downloaded(path: &Path) -> bool {
+    use std::os::macos::fs::MetadataExt;
+
+    // macOS marks cloud-only placeholders with UF_DATALESS.
+    const UF_DATALESS: u32 = 0x4000_0000;
+    fs::symlink_metadata(path)
+        .is_ok_and(|metadata| metadata.st_flags() & UF_DATALESS != 0)
+}
+
+#[cfg(not(target_os = "macos"))]
+fn is_cloud_file_not_downloaded(_path: &Path) -> bool {
+    false
+}
+
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DocTreeItem {
@@ -64,9 +81,8 @@ pub enum DocTreeResourceKind {
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DocTreeMemoMeta {
-    pub id: String,
     pub icon: Option<String>,
-    pub colors: Vec<MemoColor>,
+    pub colors: Vec<NoteColor>,
     pub favorited: bool,
 }
 
@@ -196,20 +212,20 @@ fn memo_tree_metadata_for_directory(
         .strip_prefix(&notebook_root)
         .ok()?
         .to_path_buf();
-    let index = memo_file
-        .read_index_for_notebook_id(Some(&config.id))
-        .ok()??;
+    let notes = match memo_file.read_note_entries(&config.id) {
+        Ok(notes) => notes,
+        Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+            state.notebook_background.request(&config.id, true, false);
+            return None;
+        }
+        Err(_) => return None,
+    };
 
     Some(
-        index
-            .memos
+        notes
             .into_iter()
             .filter_map(|entry| {
-                let relative_path = if entry.relative_path.is_empty() {
-                    entry.filename
-                } else {
-                    entry.relative_path
-                };
+                let relative_path = entry.relative_path;
                 if !relative_memo_is_direct_child(Path::new(&relative_path), &relative_directory) {
                     return None;
                 }
@@ -220,7 +236,6 @@ fn memo_tree_metadata_for_directory(
                     MemoTreeMetadata {
                         created_ms: u64::try_from(entry.created_at).ok(),
                         memo: DocTreeMemoMeta {
-                            id: entry.id,
                             icon: entry.icon,
                             colors: entry.colors,
                             favorited: entry.favorited,
@@ -444,20 +459,14 @@ pub(crate) fn default_create_folder_for_notebook(root: &Path) -> Result<Option<S
     flowix_core::memo_file::default_create_folder_for_notebook(root)
 }
 
-pub(crate) fn migrate_legacy_watcher_rules(
-    root: &Path,
-    config: &crate::watcher::WhitelistConfig,
-    memo: &MemoFile,
-) -> Result<(), String> {
-    if read_notebook_view_preferences(root)
-        .file_management
-        .legacy_watcher_migrated
-    {
-        return Ok(());
-    }
-    with_registered_notebook_change(root, memo, "migrate_file_management_preferences", || {
-        migrate_legacy_watcher_rules_locked(root, config)
-    })
+pub(crate) fn write_default_notebook_view_preferences(root: &Path) -> Result<(), String> {
+    let path = notebook_preferences_path(root)?;
+    fs::create_dir_all(path.parent().ok_or("INVALID_NOTEBOOK_CONFIG_DIRECTORY")?)
+        .map_err(|error| format!("create notebook config directory failed: {error}"))?;
+    let bytes = serde_json::to_vec_pretty(&NotebookViewPreferences::default())
+        .map_err(|error| format!("serialize default notebook preferences failed: {error}"))?;
+    flowix_core::memo_file::atomic_write_bytes(&path, &bytes)
+        .map_err(|error| format!("write default notebook preferences failed: {error}"))
 }
 
 fn with_registered_notebook_change<T>(
@@ -470,61 +479,6 @@ fn with_registered_notebook_change<T>(
         .map_err(|error| error.to_string())?
 }
 
-fn migrate_legacy_watcher_rules_locked(
-    root: &Path,
-    config: &crate::watcher::WhitelistConfig,
-) -> Result<(), String> {
-    let mut preferences = read_notebook_view_preferences(root);
-    if preferences.file_management.legacy_watcher_migrated {
-        return Ok(());
-    }
-    let policy = &mut preferences.file_management;
-    policy.legacy_skip_dirs = config
-        .skip_dirs
-        .iter()
-        .filter(|name| {
-            !matches!(
-                name.as_str(),
-                ".flowix"
-                    | ".plugin-output"
-                    | ".git"
-                    | ".DS_Store"
-                    | "node_modules"
-                    | ".cache"
-                    | ".trash"
-                    | "attachments"
-                    | "attachments-cache"
-            )
-        })
-        .cloned()
-        .collect();
-    policy.legacy_skip_files = config
-        .skip_files
-        .iter()
-        .filter(|name| {
-            !matches!(
-                name.as_str(),
-                "*.tmp" | "*.swp" | "*~" | ".DS_Store" | "Thumbs.db" | "*.bak" | "*.lock"
-            )
-        })
-        .cloned()
-        .collect();
-    policy.legacy_watcher_migrated = true;
-    let path = notebook_preferences_path(root)?;
-    fs::create_dir_all(path.parent().ok_or("INVALID_NOTEBOOK_CONFIG_DIRECTORY")?)
-        .map_err(|error| error.to_string())?;
-    if !policy.legacy_skip_dirs.is_empty() || !policy.legacy_skip_files.is_empty() {
-        flowix_core::memo_file::atomic_write_bytes(
-            &root.join(".flowix/file-management-refresh-pending"),
-            uuid::Uuid::new_v4().to_string().as_bytes(),
-        )
-        .map_err(|error| error.to_string())?;
-    }
-    let bytes = serde_json::to_vec_pretty(&preferences).map_err(|error| error.to_string())?;
-    flowix_core::memo_file::atomic_write_bytes(&path, &bytes).map_err(|error| error.to_string())?;
-    Ok(())
-}
-
 fn normalize_relative_folder_paths(folders: Vec<String>) -> Result<Vec<String>, String> {
     let mut normalized = Vec::new();
     for folder in folders {
@@ -571,11 +525,6 @@ pub fn get_notebook_view_preferences(
     if !is_registered_notebook_root(root, &state) {
         return Err("NOTEBOOK_NOT_REGISTERED".to_string());
     }
-    migrate_legacy_watcher_rules(
-        root,
-        &state.user_config.get_preference().watcher,
-        &read_lock(&state.memo_file, "memo_file"),
-    )?;
     if root
         .join(".flowix/file-management-refresh-pending")
         .exists()
@@ -656,11 +605,6 @@ pub fn get_file_management_candidates(
     if !is_registered_notebook_root(root, &state) {
         return Err("NOTEBOOK_NOT_REGISTERED".to_string());
     }
-    migrate_legacy_watcher_rules(
-        root,
-        &state.user_config.get_preference().watcher,
-        &read_lock(&state.memo_file, "memo_file"),
-    )?;
     let policy = read_notebook_view_preferences(root).file_management;
     let defaults = FileManagementPolicy::default();
     let mut pending = vec![root.to_path_buf()];
@@ -689,7 +633,6 @@ pub fn get_file_management_candidates(
             let is_directory = metadata.is_dir();
             let name = Path::new(entry.file_name().as_os_str()).to_path_buf();
             let own_name_ignored = defaults.is_ignored(&name)
-                || policy.matches_legacy_entry(&path)
                 || FileManagementPolicy::has_hidden_attribute(&path);
             if FileManagementPolicy::is_locked_name(&entry.file_name().to_string_lossy()) {
                 continue;
@@ -783,7 +726,6 @@ fn collect_notebook_settings_tree(
         let relative_path = relative.to_string_lossy().replace('\\', "/");
         let hidden = policy.is_tree_hidden_at(root, relative);
         let default_hidden = FileManagementPolicy::default().is_ignored_at(root, relative)
-            || policy.matches_legacy_entry(&path)
             || FileManagementPolicy::has_hidden_attribute(&path);
         if metadata.is_dir() {
             let is_flowix_dir = relative_path == ".flowix";
@@ -857,10 +799,6 @@ pub fn set_notebook_view_preferences(
             &read_lock(&state.memo_file, "memo_file"),
             "set_notebook_view_preferences",
             || {
-                migrate_legacy_watcher_rules_locked(
-                    &root,
-                    &state.user_config.get_preference().watcher,
-                )?;
                 let previous_preferences = read_notebook_view_preferences(&root);
                 let previous_policy = previous_preferences.file_management.clone();
                 let path = notebook_preferences_path(&root)?;
@@ -883,9 +821,6 @@ pub fn set_notebook_view_preferences(
                         excluded_index_paths: normalize_excluded_index_paths(
                             preferences.file_management.excluded_index_paths,
                         )?,
-                        legacy_skip_dirs: previous_policy.legacy_skip_dirs.clone(),
-                        legacy_skip_files: previous_policy.legacy_skip_files.clone(),
-                        legacy_watcher_migrated: previous_policy.legacy_watcher_migrated,
                     },
                     refresh_pending: false,
                 };
@@ -975,7 +910,6 @@ fn normalize_default_create_folder(folder: Option<String>) -> Result<Option<Stri
 #[tauri::command]
 pub fn get_file_tree(space_path: String, state: State<AppState>) -> Option<Vec<DocTreeItem>> {
     let path = Path::new(&space_path);
-    start_security_bookmark_access(&state, path);
     if !path.exists()
         || is_internal_notebook_path(path, &state)
         || !is_browsable_scope(path, &state)
@@ -996,7 +930,6 @@ pub fn get_file_tree(space_path: String, state: State<AppState>) -> Option<Vec<D
 #[tauri::command]
 pub fn get_dir_children(dir_path: String, state: State<AppState>) -> Vec<DocTreeItem> {
     let path = Path::new(&dir_path);
-    start_security_bookmark_access(&state, path);
     if !path.exists()
         || is_internal_notebook_path(path, &state)
         || !is_browsable_scope(path, &state)
@@ -1019,7 +952,7 @@ pub fn get_dir_children(dir_path: String, state: State<AppState>) -> Vec<DocTree
 /// `path_is_inside` 一并放行)。
 fn is_browsable_scope(path: &Path, state: &State<AppState>) -> bool {
     !is_internal_notebook_path(path, state)
-        && (is_registered_notebook_path(path, state) || is_agent_access_folder(path, state))
+        && (is_registered_notebook_path(path, state) || is_attached_notebook_directory(path, state))
 }
 
 #[tauri::command]
@@ -1032,7 +965,6 @@ pub fn read_file(
         eprintln!("[read_file] refused out-of-scope path: {}", file_path);
         return None;
     }
-    start_security_bookmark_access(&state, Path::new(&file_path));
     fs::read_to_string(&file_path).ok()
 }
 
@@ -1065,7 +997,6 @@ fn authorized_docx_path(
     {
         return Err("DOCX_FORBIDDEN: file is outside its authorized space".to_string());
     }
-    start_security_bookmark_access(state, &path);
     Ok(path)
 }
 
@@ -1278,7 +1209,6 @@ fn create_docx_markdown_with_images(
         {
             return Err("DOCX_FORBIDDEN: attachment directory escapes this space".to_string());
         }
-        start_security_bookmark_access(state, &attachment_directory);
 
         for (index, image) in prepared_images.iter().enumerate() {
             match create_docx_image_file(&attachment_directory, space_path, state, image, index) {
@@ -1401,7 +1331,6 @@ pub fn read_image_file(
         eprintln!("[read_image_file] refused file: {}", file_path);
         return None;
     }
-    start_security_bookmark_access(&state, path);
     let bytes = fs::read(path).ok()?;
     Some(format!(
         "data:{mime};base64,{}",
@@ -1422,7 +1351,6 @@ pub async fn read_image_preview(
     if !can_access_scoped_file(path, space_path.as_deref(), &state) || !path.is_file() {
         return Ok(None);
     }
-    start_security_bookmark_access(&state, path);
     let path = path.to_path_buf();
     let max_dimension = preview_max_dimension(max_dimension);
     let slots = MEDIA_PREVIEW_SLOTS
@@ -1552,7 +1480,6 @@ pub async fn get_media_thumbnail(
     if !is_image && !is_video {
         return Err("unsupported media thumbnail kind".to_string());
     }
-    start_security_bookmark_access(&state, &path);
 
     let metadata = fs::metadata(&path).map_err(|error| error.to_string())?;
     let modified_ns = metadata
@@ -1901,7 +1828,6 @@ pub fn read_video_preview(
         eprintln!("[read_video_preview] refused file: {}", file_path);
         return None;
     }
-    start_security_bookmark_access(&state, path);
 
     #[cfg(target_os = "macos")]
     {
@@ -1957,7 +1883,6 @@ pub fn write_file(
         eprintln!("[write_file] refused out-of-scope path: {}", file_path);
         return false;
     }
-    start_security_bookmark_access(&state, Path::new(&file_path));
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let path = Path::new(&file_path);
     let notebook_ids = match memo_file.notebook_ids_for_paths(&[path]) {
@@ -2002,7 +1927,6 @@ pub fn create_file(
     if !path.parent().is_some_and(Path::is_dir) {
         return Err("FILE_NOT_FOUND: parent directory does not exist".to_string());
     }
-    start_security_bookmark_access(&state, path);
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let notebook_ids = memo_file
         .notebook_ids_for_paths(&[path])
@@ -2031,7 +1955,6 @@ pub fn delete_file(file_path: String, space_path: Option<String>, state: State<A
         eprintln!("[delete_file] refused out-of-scope path: {}", file_path);
         return false;
     }
-    start_security_bookmark_access(&state, Path::new(&file_path));
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let path = Path::new(&file_path);
     let notebook_ids = match memo_file.notebook_ids_for_paths(&[path]) {
@@ -2081,7 +2004,6 @@ pub fn delete_folder(
         );
         return Err("FILE_PERMISSION_DENIED".to_string());
     }
-    start_security_bookmark_access(&state, folder);
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let notebook_ids = memo_file
         .notebook_ids_for_paths(&[folder])
@@ -2168,6 +2090,14 @@ fn file_mutation_error(error: std::io::Error) -> String {
     format!("{code}: {error}")
 }
 
+fn target_directory_error(error: std::io::Error) -> String {
+    if error.kind() == std::io::ErrorKind::NotFound {
+        "TARGET_NOT_DIRECTORY".to_string()
+    } else {
+        file_mutation_error(error)
+    }
+}
+
 fn validate_file_name(name: &str) -> Result<(), String> {
     if name.trim().is_empty()
         || name == "."
@@ -2191,18 +2121,13 @@ fn rename_path_and_notify(
     target: &Path,
     state: &AppState,
     app: &tauri::AppHandle,
-) -> Result<(), String> {
+) -> Result<Option<super::path_change::NotebookPathMove>, String> {
     let source_was_directory = source.is_dir();
-    let source_was_markdown = source
-        .extension()
-        .and_then(|extension| extension.to_str())
-        .is_some_and(|extension| {
-            matches!(extension.to_ascii_lowercase().as_str(), "md" | "markdown")
-        });
     let mf = read_lock(&state.memo_file, "memo_file");
-    let changes = mf
-        .rename_indexed_path(source, target)
+    let _watch_move = crate::commands::external_document_watch::begin_path_move(app, source);
+    mf.rename_indexed_path(source, target)
         .map_err(file_mutation_error)?;
+    crate::commands::external_document_watch::rebase_path(app, source, target);
     if target.is_dir() {
         let configs = mf.read_notebook_configs().unwrap_or_default();
         if let Some(config) = configs.into_iter().find(|config| {
@@ -2232,13 +2157,8 @@ fn rename_path_and_notify(
         crate::commands::document_list::refresh_view_document_path(&mf, source);
         crate::commands::document_list::refresh_view_document_path(&mf, target);
     }
-    let target_is_markdown = target
-        .extension()
-        .and_then(|extension| extension.to_str())
-        .is_some_and(|extension| {
-            matches!(extension.to_ascii_lowercase().as_str(), "md" | "markdown")
-        });
-    if source_was_directory || (source_was_markdown && target_is_markdown) {
+    let mut notebook_change = None;
+    {
         crate::commands::document_list::rebase_collection_paths_for_move(&mf, source, target);
         if let Some((notebook_id, relative_path, previous_path)) = mf
             .read_notebook_configs()
@@ -2258,39 +2178,15 @@ fn rename_path_and_notify(
                 ))
             })
         {
-            let _ = app.emit(
-                "flowix:path-note-changed",
-                serde_json::json!({
-                    "notebookId": notebook_id,
-                    "relativePath": relative_path,
-                    "previousRelativePath": previous_path,
-                    "kind": "path",
-                    "directory": source_was_directory,
-                    "deleted": false,
-                }),
-            );
+            if let Some(previous_path) = previous_path {
+                let change = super::path_change::NotebookPathMove::new(
+                    notebook_id, previous_path, relative_path, source_was_directory,
+                );
+                change.emit(app);
+                notebook_change = Some(change);
+            }
         }
     }
-    for (notebook_id, before, memo) in changes {
-        let Some(config) = mf.get_notebook_config_by_id(&notebook_id) else {
-            continue;
-        };
-        let path = notebook_path_from_relative(Path::new(&config.path), &memo.relative_path)?;
-        crate::memo_events::emit(
-            app,
-            crate::memo_events::MemoEvent::Updated {
-                id: memo.id.clone(),
-                path: path.to_string_lossy().into_owned(),
-                notebook_id,
-                derived_changed: crate::memo_events::MemoDerivedChanged::from_memos(
-                    Some(&before),
-                    &memo,
-                ),
-                memo,
-                source: crate::memo_events::MemoChangeSource::UserEdit,
-            },
-        );
-    }
     let notebooks = mf.read_notebook_configs().unwrap_or_default();
     let address_for = |path: &Path| {
         notebooks.iter().find_map(|notebook| {
@@ -2321,7 +2217,7 @@ fn rename_path_and_notify(
             );
         }
     }
-    Ok(())
+    Ok(notebook_change)
 }
 
 #[tauri::command]
@@ -2332,7 +2228,7 @@ pub async fn rename_file(
     name: String,
     space_path: String,
     app: tauri::AppHandle,
-) -> Result<String, String> {
+) -> Result<super::path_change::PathMutationResult, String> {
     crate::commands::document_operations::run(
         "rename_external",
         operation_id,
@@ -2348,15 +2244,14 @@ pub async fn rename_file(
             {
                 return Err("FILE_PERMISSION_DENIED".to_string());
             }
-            start_security_bookmark_access(&state, source);
             if !fs::symlink_metadata(source)
                 .map_err(file_mutation_error)?
                 .is_file()
             {
                 return Err("SOURCE_NOT_REGULAR_FILE".to_string());
             }
-            rename_path_and_notify(source, &target, state.inner(), &app)?;
-            Ok(target.to_string_lossy().into_owned())
+            let notebook_change = rename_path_and_notify(source, &target, state.inner(), &app)?;
+            Ok(super::path_change::PathMutationResult { path: target.to_string_lossy().into_owned(), notebook_change })
         },
     )
     .await
@@ -2372,7 +2267,7 @@ pub fn move_file(
     space_path: String,
     state: State<AppState>,
     app: tauri::AppHandle,
-) -> Result<String, String> {
+) -> Result<super::path_change::PathMutationResult, FileOperationFailure> {
     let source = Path::new(&file_path);
     let target_directory = Path::new(&target_directory_path);
     let scope = Path::new(&space_path);
@@ -2380,38 +2275,41 @@ pub fn move_file(
         || !can_access_scoped_file(source, Some(&space_path), &state)
         || !can_access_scoped_file(target_directory, Some(&space_path), &state)
     {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
-    start_security_bookmark_access(&state, source);
-    start_security_bookmark_access(&state, target_directory);
     if !fs::symlink_metadata(source)
         .map_err(file_mutation_error)?
         .is_file()
     {
-        return Err("SOURCE_NOT_REGULAR_FILE".to_string());
+        return Err(FileOperationFailure::code("SOURCE_NOT_REGULAR_FILE"));
     }
     if !fs::symlink_metadata(target_directory)
-        .map_err(file_mutation_error)?
+        .map_err(target_directory_error)?
         .is_dir()
     {
-        return Err("TARGET_NOT_DIRECTORY".to_string());
+        return Err(FileOperationFailure::code("TARGET_NOT_DIRECTORY"));
     }
-    let file_name = source.file_name().ok_or("INVALID_FILE_PATH")?;
+    let file_name = source
+        .file_name()
+        .ok_or_else(|| FileOperationFailure::code("INVALID_FILE_PATH"))?;
     let target = target_directory.join(file_name);
     if !can_access_scoped_file(&target, Some(&space_path), &state) {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
     if source == target {
-        return Ok(source.to_string_lossy().into_owned());
+        return Ok(super::path_change::PathMutationResult { path: source.to_string_lossy().into_owned(), notebook_change: None });
     }
     if fs::symlink_metadata(&target).is_ok() {
-        return Err(file_mutation_error(std::io::Error::new(
-            std::io::ErrorKind::AlreadyExists,
-            "target already exists",
-        )));
+        return Err(
+            file_mutation_error(std::io::Error::new(
+                std::io::ErrorKind::AlreadyExists,
+                "target already exists",
+            ))
+            .into(),
+        );
     }
-    rename_path_and_notify(source, &target, state.inner(), &app)?;
-    Ok(target.to_string_lossy().into_owned())
+    let notebook_change = rename_path_and_notify(source, &target, state.inner(), &app)?;
+    Ok(super::path_change::PathMutationResult { path: target.to_string_lossy().into_owned(), notebook_change })
 }
 
 /// Move a folder within the caller's notebook/access-folder scope.
@@ -2422,7 +2320,7 @@ pub fn move_folder(
     space_path: String,
     state: State<AppState>,
     app: tauri::AppHandle,
-) -> Result<String, String> {
+) -> Result<super::path_change::PathMutationResult, FileOperationFailure> {
     let source = Path::new(&folder_path);
     let target_directory = Path::new(&target_directory_path);
     let scope = Path::new(&space_path);
@@ -2433,41 +2331,44 @@ pub fn move_folder(
         || is_internal_notebook_path(source, &state)
         || is_internal_notebook_path(target_directory, &state)
     {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
-    start_security_bookmark_access(&state, source);
-    start_security_bookmark_access(&state, target_directory);
     if !fs::symlink_metadata(source)
         .map_err(file_mutation_error)?
         .is_dir()
     {
-        return Err("SOURCE_NOT_DIRECTORY".to_string());
+        return Err(FileOperationFailure::code("SOURCE_NOT_DIRECTORY"));
     }
     if !fs::symlink_metadata(target_directory)
-        .map_err(file_mutation_error)?
+        .map_err(target_directory_error)?
         .is_dir()
     {
-        return Err("TARGET_NOT_DIRECTORY".to_string());
+        return Err(FileOperationFailure::code("TARGET_NOT_DIRECTORY"));
     }
     if path_is_inside(target_directory, source) {
-        return Err("INVALID_MOVE_TARGET".to_string());
+        return Err(FileOperationFailure::code("INVALID_MOVE_TARGET"));
     }
-    let folder_name = source.file_name().ok_or("INVALID_FILE_PATH")?;
+    let folder_name = source
+        .file_name()
+        .ok_or_else(|| FileOperationFailure::code("INVALID_FILE_PATH"))?;
     let target = target_directory.join(folder_name);
     if !path_is_inside(&target, scope) || is_internal_notebook_path(&target, &state) {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
     if source == target {
-        return Ok(source.to_string_lossy().into_owned());
+        return Ok(super::path_change::PathMutationResult { path: source.to_string_lossy().into_owned(), notebook_change: None });
     }
     if fs::symlink_metadata(&target).is_ok() {
-        return Err(file_mutation_error(std::io::Error::new(
-            std::io::ErrorKind::AlreadyExists,
-            "target already exists",
-        )));
+        return Err(
+            file_mutation_error(std::io::Error::new(
+                std::io::ErrorKind::AlreadyExists,
+                "target already exists",
+            ))
+            .into(),
+        );
     }
-    rename_path_and_notify(source, &target, state.inner(), &app)?;
-    Ok(target.to_string_lossy().into_owned())
+    let notebook_change = rename_path_and_notify(source, &target, state.inner(), &app)?;
+    Ok(super::path_change::PathMutationResult { path: target.to_string_lossy().into_owned(), notebook_change })
 }
 
 /// Copy a supported external resource into the caller's notebook scope.
@@ -2480,14 +2381,14 @@ pub async fn import_file(
     target_directory_path: String,
     space_path: String,
     state: State<'_, AppState>,
-) -> Result<String, String> {
+) -> Result<String, FileOperationFailure> {
     let source = Path::new(&file_path);
     let target_directory = Path::new(&target_directory_path);
     let scope = Path::new(&space_path);
     if !is_browsable_scope(scope, &state)
         || !can_access_scoped_file(target_directory, Some(&space_path), &state)
     {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
     // WebView2 can invoke this command just before Tauri's Drop RunEvent has
     // recorded the exact external path in DocumentAccess. Wait briefly for
@@ -2503,35 +2404,41 @@ pub async fn import_file(
             || can_access_scoped_file(source, Some(&space_path), &state);
     }
     if !source_allowed {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
-    start_security_bookmark_access(&state, source);
-    start_security_bookmark_access(&state, target_directory);
     if !fs::symlink_metadata(source)
         .map_err(file_mutation_error)?
         .is_file()
     {
-        return Err("SOURCE_NOT_REGULAR_FILE".to_string());
+        return Err(FileOperationFailure::code("SOURCE_NOT_REGULAR_FILE"));
+    }
+    if is_cloud_file_not_downloaded(source) {
+        return Err(FileOperationFailure::code("CLOUD_FILE_NOT_DOWNLOADED"));
     }
     if !fs::symlink_metadata(target_directory)
-        .map_err(file_mutation_error)?
+        .map_err(target_directory_error)?
         .is_dir()
     {
-        return Err("TARGET_NOT_DIRECTORY".to_string());
+        return Err(FileOperationFailure::code("TARGET_NOT_DIRECTORY"));
     }
-    let file_name = source.file_name().ok_or("INVALID_FILE_PATH")?;
+    let file_name = source
+        .file_name()
+        .ok_or_else(|| FileOperationFailure::code("INVALID_FILE_PATH"))?;
     let target = target_directory.join(file_name);
     if !can_access_scoped_file(&target, Some(&space_path), &state) {
-        return Err("FILE_PERMISSION_DENIED".to_string());
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
     }
     if source == target {
         return Ok(target.to_string_lossy().into_owned());
     }
     if fs::symlink_metadata(&target).is_ok() {
-        return Err(file_mutation_error(std::io::Error::new(
-            std::io::ErrorKind::AlreadyExists,
-            "target already exists",
-        )));
+        return Err(
+            file_mutation_error(std::io::Error::new(
+                std::io::ErrorKind::AlreadyExists,
+                "target already exists",
+            ))
+            .into(),
+        );
     }
 
     let source = source.to_path_buf();
@@ -2589,7 +2496,7 @@ pub async fn rename_folder(
     name: String,
     space_path: String,
     app: tauri::AppHandle,
-) -> Result<String, String> {
+) -> Result<super::path_change::PathMutationResult, String> {
     crate::commands::document_operations::run(
         "rename_folder",
         operation_id,
@@ -2614,7 +2521,6 @@ pub async fn rename_folder(
             {
                 return Err("FILE_PERMISSION_DENIED".to_string());
             }
-            start_security_bookmark_access(&state, source);
             if !fs::symlink_metadata(source)
                 .map_err(file_mutation_error)?
                 .is_dir()
@@ -2627,7 +2533,10 @@ pub async fn rename_folder(
             };
             if let Some((_notebook_id, result)) = collection_move {
                 let path = Path::new(&result.notebook_path).join(&result.actual_relative_path);
-                return Ok(path.parent().ok_or("INVALID_COLLECTION_PATH")?.to_string_lossy().into_owned());
+                return Ok(super::path_change::PathMutationResult {
+                    path: path.parent().ok_or("INVALID_COLLECTION_PATH")?.to_string_lossy().into_owned(),
+                    notebook_change: super::collection::path_change_for_result(&_notebook_id, &result),
+                });
             }
             if fs::symlink_metadata(&target).is_ok() {
                 return Err(file_mutation_error(std::io::Error::new(
@@ -2635,8 +2544,8 @@ pub async fn rename_folder(
                     "target already exists",
                 )));
             }
-            rename_path_and_notify(source, &target, state.inner(), &app)?;
-            Ok(target.to_string_lossy().into_owned())
+            let notebook_change = rename_path_and_notify(source, &target, state.inner(), &app)?;
+            Ok(super::path_change::PathMutationResult { path: target.to_string_lossy().into_owned(), notebook_change })
         },
     )
     .await
@@ -2661,7 +2570,6 @@ pub fn create_folder(
         );
         return None;
     }
-    start_security_bookmark_access(&state, &target_path);
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let notebook_ids = memo_file.notebook_ids_for_paths(&[&target_path]).ok()?;
     if notebook_ids.is_empty() {
@@ -2715,7 +2623,6 @@ pub fn create_document(
         );
         return Err("FILE_PERMISSION_DENIED".to_string());
     }
-    start_security_bookmark_access(&state, &target_path);
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let notebook_ids = memo_file
         .notebook_ids_for_paths(&[&target_path])
@@ -2804,9 +2711,8 @@ mod tests {
             MemoTreeMetadata {
                 created_ms: Some(42),
                 memo: DocTreeMemoMeta {
-                    id: "memo-1".to_string(),
                     icon: Some("flashlight".to_string()),
-                    colors: vec![MemoColor::Blue],
+                    colors: vec![NoteColor::Blue],
                     favorited: true,
                 },
             },
@@ -2815,9 +2721,8 @@ mod tests {
         let items = read_dir_single_level(directory.path(), Some(&metadata));
         assert_eq!(items[0].memo_created_ms, Some(42));
         let memo = items[0].memo_meta.as_ref().expect("indexed memo metadata");
-        assert_eq!(memo.id, "memo-1");
         assert_eq!(memo.icon.as_deref(), Some("flashlight"));
-        assert_eq!(memo.colors, vec![MemoColor::Blue]);
+        assert_eq!(memo.colors, vec![NoteColor::Blue]);
         assert!(memo.favorited);
     }
 
diff --git a/app/flowix-desktop/src/commands/file/folder_import.rs b/app/flowix-desktop/src/commands/file/folder_import.rs
new file mode 100644
index 000000000..ca77f15d7
--- /dev/null
+++ b/app/flowix-desktop/src/commands/file/folder_import.rs
@@ -0,0 +1,198 @@
+use super::*;
+
+const MAX_IMPORT_FOLDER_FILES: usize = 2_000;
+const MAX_IMPORT_FOLDER_ENTRIES: usize = 5_000;
+const MAX_IMPORT_FOLDER_DEPTH: usize = 32;
+const MAX_IMPORT_FOLDER_BYTES: u64 = 5 * 1024 * 1024 * 1024;
+
+/// Import a selected directory while preserving its internal folder structure.
+/// Limits are checked before creating anything in the destination.
+#[tauri::command]
+pub async fn import_folder(
+    window: WebviewWindow,
+    source_directory_path: String,
+    target_directory_path: String,
+    space_path: String,
+    state: State<'_, AppState>,
+) -> Result<String, FileOperationFailure> {
+    let source_directory = Path::new(&source_directory_path);
+    let target_directory = Path::new(&target_directory_path);
+    let scope = Path::new(&space_path);
+    if !can_access_document_path(source_directory, window.label(), &state)
+        || !is_browsable_scope(scope, &state)
+        || !can_access_scoped_file(target_directory, Some(&space_path), &state)
+    {
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
+    }
+    let source_metadata = fs::symlink_metadata(source_directory).map_err(file_mutation_error)?;
+    if !source_metadata.is_dir() || source_metadata.file_type().is_symlink() {
+        return Err(FileOperationFailure::code("SOURCE_NOT_DIRECTORY"));
+    }
+    if !fs::symlink_metadata(target_directory)
+        .map_err(target_directory_error)?
+        .is_dir()
+    {
+        return Err(FileOperationFailure::code("TARGET_NOT_DIRECTORY"));
+    }
+    let folder_name = source_directory
+        .file_name()
+        .ok_or_else(|| FileOperationFailure::code("INVALID_FILE_PATH"))?;
+    let target_root = target_directory.join(folder_name);
+    if !can_access_scoped_file(&target_root, Some(&space_path), &state) {
+        return Err(FileOperationFailure::code("FILE_PERMISSION_DENIED"));
+    }
+    if fs::symlink_metadata(&target_root).is_ok() {
+        return Err(FileOperationFailure::code("FILE_EXISTS"));
+    }
+
+    let source = dunce::canonicalize(source_directory).map_err(file_mutation_error)?;
+    let memo_file = state.memo_file.clone();
+
+    tokio::task::spawn_blocking(move || {
+        use walkdir::WalkDir;
+
+        let mut directories = Vec::new();
+        let mut files = Vec::new();
+        let mut entry_count = 0usize;
+        let mut total_bytes = 0u64;
+        let walker = WalkDir::new(&source)
+            .follow_links(false)
+            .min_depth(1)
+            .into_iter()
+            .filter_entry(|entry| {
+                entry.depth() == 0
+                    || !matches!(entry.file_name().to_str(), Some(".flowix" | ".DS_Store"))
+            });
+        for entry in walker {
+            let entry = entry.map_err(|_| FileOperationFailure::code("IMPORT_FOLDER_SCAN_FAILED"))?;
+            let relative = entry
+                .path()
+                .strip_prefix(&source)
+                .map_err(|_| FileOperationFailure::code("INVALID_FILE_PATH"))?;
+            entry_count += 1;
+            if entry_count > MAX_IMPORT_FOLDER_ENTRIES {
+                return Err(FileOperationFailure::code("IMPORT_FOLDER_TOO_MANY_ENTRIES"));
+            }
+            let relative_depth = relative.components().count();
+            let depth = if entry.file_type().is_dir() {
+                relative_depth
+            } else {
+                relative_depth.saturating_sub(1)
+            };
+            if depth > MAX_IMPORT_FOLDER_DEPTH {
+                return Err(FileOperationFailure::code("IMPORT_FOLDER_TOO_DEEP"));
+            }
+            if entry.file_type().is_symlink() {
+                continue;
+            }
+            if entry.file_type().is_dir() {
+                directories.push(relative.to_path_buf());
+                continue;
+            }
+            if !entry.file_type().is_file() {
+                continue;
+            }
+            if is_cloud_file_not_downloaded(entry.path()) {
+                return Err(FileOperationFailure::code("CLOUD_FILE_NOT_DOWNLOADED"));
+            }
+            let size = entry
+                .metadata()
+                .map_err(|_| FileOperationFailure::code("IMPORT_FOLDER_SCAN_FAILED"))?
+                .len();
+            total_bytes = total_bytes.saturating_add(size);
+            if total_bytes > MAX_IMPORT_FOLDER_BYTES {
+                return Err(FileOperationFailure::code("IMPORT_FOLDER_TOO_LARGE"));
+            }
+            files.push((entry.path().to_path_buf(), relative.to_path_buf()));
+            if files.len() > MAX_IMPORT_FOLDER_FILES {
+                return Err(FileOperationFailure::code("IMPORT_FOLDER_TOO_MANY_FILES"));
+            }
+        }
+
+        // Create the full tree only after the source passes all import limits.
+        fs::create_dir(&target_root).map_err(file_mutation_error)?;
+        let copy_result = (|| -> Result<(), FileOperationFailure> {
+            for relative in &directories {
+                fs::create_dir_all(target_root.join(relative)).map_err(file_mutation_error)?;
+            }
+            for (source_file, relative) in &files {
+                let target = target_root.join(relative);
+                if let Some(parent) = target.parent() {
+                    fs::create_dir_all(parent).map_err(file_mutation_error)?;
+                }
+                let store = read_lock(&memo_file, "memo_file");
+                let ids = store
+                    .notebook_ids_for_paths(&[&target])
+                    .map_err(file_mutation_error)?;
+                let copy = |destination: &Path| -> std::io::Result<()> {
+                    let metadata = fs::symlink_metadata(source_file)?;
+                    if !metadata.is_file() || metadata.file_type().is_symlink() {
+                        return Err(std::io::Error::new(
+                            std::io::ErrorKind::InvalidInput,
+                            "source is not a regular file",
+                        ));
+                    }
+                    let canonical_source = dunce::canonicalize(source_file)?;
+                    if !canonical_source.starts_with(&source) {
+                        return Err(std::io::Error::new(
+                            std::io::ErrorKind::PermissionDenied,
+                            "source escaped selected folder",
+                        ));
+                    }
+                    let mut input = fs::File::open(canonical_source)?;
+                    let mut output = fs::OpenOptions::new()
+                        .write(true)
+                        .create_new(true)
+                        .open(destination)?;
+                    if let Err(error) = std::io::copy(&mut input, &mut output) {
+                        let _ = fs::remove_file(destination);
+                        return Err(error);
+                    }
+                    output.sync_all()
+                };
+                match ids.as_slice() {
+                    [notebook_id] => store.with_file_write(
+                        notebook_id,
+                        &target,
+                        flowix_core::memo_file::FileLockIntent::Create,
+                        "import_folder_file",
+                        copy,
+                    ),
+                    [] => {
+                        let _guard = store
+                            .acquire_cross_process_write_lock()
+                            .map_err(file_mutation_error)?;
+                        copy(&target)
+                    }
+                    _ => store.with_registered_path_change(
+                        &[&target],
+                        "import_folder_nested_notebooks",
+                        || copy(&target),
+                    ),
+                }
+                .map_err(file_mutation_error)?;
+            }
+            Ok(())
+        })();
+        if let Err(import_error) = copy_result {
+            if let Err(cleanup_error) = fs::remove_dir_all(&target_root) {
+                tracing::warn!(
+                    target = %target_root.display(),
+                    error = %cleanup_error,
+                    "failed to clean up partially imported folder"
+                );
+                return Err(FileOperationFailure {
+                    code: "IMPORT_FOLDER_CLEANUP_FAILED".to_string(),
+                    message: Some(format!(
+                        "Import failed ({}) and partial files could not be removed ({cleanup_error})",
+                        import_error.code
+                    )),
+                });
+            }
+            return Err(import_error);
+        }
+        Ok(target_root.to_string_lossy().into_owned())
+    })
+    .await
+    .map_err(|error| FileOperationFailure::code(&format!("FILE_OPERATION_FAILED: {error}")))?
+}
diff --git a/app/flowix-desktop/src/commands/file_browser_watch.rs b/app/flowix-desktop/src/commands/file_browser_watch.rs
index d36cf3f4b..7003eb12d 100644
--- a/app/flowix-desktop/src/commands/file_browser_watch.rs
+++ b/app/flowix-desktop/src/commands/file_browser_watch.rs
@@ -19,8 +19,7 @@ use tauri::{Emitter, Manager};
 
 use crate::app::state::AppState;
 use crate::commands::helpers::{
-    is_agent_access_folder_with_state, is_registered_notebook_path_with_state,
-    start_security_bookmark_access,
+    is_attached_notebook_directory_with_state, is_registered_notebook_path_with_state,
 };
 use crate::config::path_is_inside;
 
@@ -354,6 +353,11 @@ fn emit_directory_changes(
         return;
     };
 
+    // A mounted tab can outlive the mount itself; stop publishing revoked roots.
+    let Some(state) = app.try_state::<AppState>() else { return; };
+    if !is_registered_notebook_path_with_state(&root_path, &state)
+        && !is_attached_notebook_directory_with_state(&root_path, &state) { return; }
+
     let mut directories = directories.into_iter().collect::<Vec<_>>();
     directories.sort();
     let mut paths = paths.into_iter().collect::<Vec<_>>();
@@ -390,10 +394,9 @@ pub fn watch_file_browser_root(
     root_path: String,
 ) -> Result<String, String> {
     let path = PathBuf::from(&root_path);
-    start_security_bookmark_access(&app_state, &path);
     if !path.is_dir()
         || (!is_registered_notebook_path_with_state(&path, &app_state)
-            && !is_agent_access_folder_with_state(&path, &app_state))
+            && !is_attached_notebook_directory_with_state(&path, &app_state))
     {
         return Err(format!(
             "file browser root is not accessible: {}",
diff --git a/app/flowix-desktop/src/commands/helpers.rs b/app/flowix-desktop/src/commands/helpers.rs
index 5fda54d86..2fc770801 100644
--- a/app/flowix-desktop/src/commands/helpers.rs
+++ b/app/flowix-desktop/src/commands/helpers.rs
@@ -2,19 +2,90 @@
 
 use std::path::Path;
 
+use serde::Serialize;
 use tauri::{AppHandle, Emitter, State};
 
 use crate::config::{path_is_inside, path_is_inside_reserved_directory};
-use crate::lock_utils::{read_lock, write_lock};
+use crate::lock_utils::read_lock;
 use crate::watcher::runtime::current_watcher;
 
 use crate::app::state::AppState;
-use flowix_core::memo_file::{
-    notebook_relative_path, MemoFile, NotebookConfig,
-};
+use flowix_core::memo_file::{notebook_relative_path, MemoFile, NotebookConfig};
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FileOperationFailure {
+    pub code: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub message: Option<String>,
+}
+
+impl FileOperationFailure {
+    pub fn code(code: &str) -> Self {
+        Self {
+            code: code.to_string(),
+            message: None,
+        }
+    }
+}
+
+impl From<String> for FileOperationFailure {
+    fn from(value: String) -> Self {
+        let (code, message) = value.split_once(": ").unwrap_or((value.as_str(), ""));
+        Self {
+            code: code.to_string(),
+            message: (!message.is_empty()).then(|| message.to_string()),
+        }
+    }
+}
+
+impl From<&str> for FileOperationFailure {
+    fn from(value: &str) -> Self {
+        Self::from(value.to_string())
+    }
+}
+
+impl From<flowix_core::FlowixError> for FileOperationFailure {
+    fn from(error: flowix_core::FlowixError) -> Self {
+        use flowix_core::FlowixError;
+
+        match error {
+            FlowixError::Io(error) => {
+                let code = match error.kind() {
+                    std::io::ErrorKind::AlreadyExists => "FILE_EXISTS",
+                    std::io::ErrorKind::NotFound => "FILE_NOT_FOUND",
+                    std::io::ErrorKind::PermissionDenied => "FILE_PERMISSION_DENIED",
+                    _ => "FILE_OPERATION_FAILED",
+                };
+                Self {
+                    code: code.to_string(),
+                    message: Some(error.to_string()),
+                }
+            }
+            FlowixError::NotFound(message) => Self {
+                code: "FILE_NOT_FOUND".to_string(),
+                message: Some(message),
+            },
+            FlowixError::PermissionDenied(message) => Self {
+                code: "FILE_PERMISSION_DENIED".to_string(),
+                message: Some(message),
+            },
+            FlowixError::InvalidInput(message) => Self {
+                code: "INVALID_MOVE_TARGET".to_string(),
+                message: Some(message),
+            },
+            error => Self {
+                code: "FILE_OPERATION_FAILED".to_string(),
+                message: Some(error.to_string()),
+            },
+        }
+    }
+}
 
 pub(crate) fn watch_created_notebook(state: &AppState, app: &AppHandle, config: &NotebookConfig) {
-    start_security_bookmark_access(state, Path::new(&config.path));
+    state
+        .security_bookmarks
+        .record_accessible_directory(Path::new(&config.path));
     if let Some(watcher) = current_watcher(app) {
         if let Ok(mut guard) = watcher.write() {
             if guard.add_notebook_root(config) {
@@ -25,10 +96,6 @@ pub(crate) fn watch_created_notebook(state: &AppState, app: &AppHandle, config:
     refresh_watcher_roots(state, app);
 }
 
-pub(crate) fn start_security_bookmark_access(state: &AppState, path: &Path) {
-    state.security_bookmarks.start_accessing_for_path(path);
-}
-
 /// Resolve a notebook-relative Markdown address without consulting the legacy
 /// memo ID table. `None` means the path is outside notebooks or is not Markdown.
 pub(crate) fn notebook_note_address(
@@ -48,7 +115,10 @@ pub(crate) fn notebook_note_address(
             continue;
         };
         let relative = Path::new(&relative_path);
-        if memo_file.file_management_policy(&notebook.id).is_index_ignored_at(&root, relative) {
+        if memo_file
+            .file_management_policy(&notebook.id)
+            .is_index_ignored_at(&root, relative)
+        {
             return Err("document path is inside an ignored notebook directory".into());
         }
         if !relative
@@ -88,31 +158,23 @@ pub(crate) fn refresh_notebook_note_index(memo_file: &MemoFile, path: &Path) {
 }
 
 pub(crate) fn refresh_watcher_roots(state: &AppState, app: &AppHandle) {
-    let configs = {
-        let memo_file = read_lock(&state.memo_file, "memo_file");
-        memo_file.read_notebook_configs().unwrap_or_default()
-    };
-    for config in &configs {
-        start_security_bookmark_access(state, Path::new(&config.path));
-    }
-    if let Some(watcher) = current_watcher(app) {
-        if let Ok(mut guard) = watcher.write() {
-            guard.rebind_all(app.clone(), configs.clone());
+    let Some(watcher) = current_watcher(app) else { return; };
+    let Ok(mut guard) = watcher.write() else { return; };
+    // Snapshot under the same lock as binding so delayed callers cannot
+    // overwrite a newer bind with metadata read before taking the lock.
+    let configs = match crate::watcher::runtime::read_registered_notebooks(state.user_config.config_dir()) {
+        Ok(configs) => configs,
+        Err(error) => {
+            tracing::warn!(%error, "watcher roots snapshot unavailable; retaining current bindings");
+            return;
         }
-    }
+    };
+    guard.rebind_all(app.clone(), configs.clone());
+    drop(guard);
     // A full rebind has a short gap. Reconcile once after binding so changes
     // made during that gap are included even if no filesystem event arrives.
-    let memo_file = read_lock(&state.memo_file, "memo_file");
     for config in &configs {
-        match memo_file.reconcile_note_index(&config.id) {
-            Ok(report) if report.added + report.updated + report.removed > 0 => {
-                let _ = app.emit("flowix:path-note-changed", serde_json::json!({
-                    "notebookId": config.id, "relativePath": "", "deleted": false,
-                }));
-            }
-            Err(error) => tracing::warn!(notebook_id = %config.id, "watcher rebind reconciliation failed: {error}"),
-            _ => {}
-        }
+        state.notebook_background.request(&config.id, false, true);
     }
 }
 
@@ -131,21 +193,12 @@ pub(crate) fn retry_notebook_watch(state: &AppState, app: &AppHandle, notebook_i
     if watcher.is_watching(notebook_id) {
         return;
     }
-    start_security_bookmark_access(state, Path::new(&config.path));
     if !watcher.add_notebook_root(&config) {
         tracing::warn!(notebook_id, "notebook watch retry failed");
         return;
     }
     drop(watcher);
-    match read_lock(&state.memo_file, "memo_file").reconcile_note_index(notebook_id) {
-        Ok(report) if report.added + report.updated + report.removed > 0 => {
-            let _ = app.emit("flowix:path-note-changed", serde_json::json!({
-                "notebookId": notebook_id, "relativePath": "", "deleted": false,
-            }));
-        }
-        Err(error) => tracing::warn!(notebook_id, "notebook watch retry reconciliation failed: {error}"),
-        _ => {}
-    }
+    state.notebook_background.request(notebook_id, true, true);
 }
 
 pub(crate) fn set_notebook_watching_suspended(app: &AppHandle, notebook_id: &str, suspended: bool) {
@@ -171,24 +224,21 @@ pub(crate) fn refresh_notebook_watcher(state: &AppState, app: &AppHandle, notebo
 
 pub(crate) fn switch_notebook_trusting_index(
     state: &AppState,
-    app: &AppHandle,
     notebook_id: Option<String>,
 ) -> Result<(), String> {
-    switch_notebook(state, app, notebook_id)
+    switch_notebook(state, notebook_id)
 }
 
-fn switch_notebook(
-    state: &AppState,
-    app: &AppHandle,
-    notebook_id: Option<String>,
-) -> Result<(), String> {
+fn switch_notebook(state: &AppState, notebook_id: Option<String>) -> Result<(), String> {
     let prev = read_lock(&state.memo_file, "memo_file").current_notebook_id_value();
     if let Some(target_id) = notebook_id.as_deref() {
         let target_path = read_lock(&state.memo_file, "memo_file")
             .get_notebook_config_by_id(target_id)
             .map(|config| std::path::PathBuf::from(config.path))
             .ok_or_else(|| format!("notebook {target_id} not found"))?;
-        start_security_bookmark_access(state, &target_path);
+        state
+            .security_bookmarks
+            .record_accessible_directory(&target_path);
         if !target_path.is_dir() {
             return Err(format!(
                 "notebook {target_id} path is missing: {}",
@@ -198,20 +248,6 @@ fn switch_notebook(
     }
 
     if prev == notebook_id {
-        if let Some(notebook_id) = notebook_id.as_deref() {
-            {
-                let memo_file = read_lock(&state.memo_file, "memo_file");
-                let report = memo_file
-                    .ensure_notebook_migrations(notebook_id)
-                    .map_err(|error| format!("notebook migration failed: {error}"))?;
-                tracing::debug!(
-                    notebook = %notebook_id,
-                    moved_files = report.moved_files,
-                    rebuilt_tags = report.rebuilt_tags,
-                    "notebook migrations checked"
-                );
-            };
-        }
         return Ok(());
     }
 
@@ -224,23 +260,6 @@ fn switch_notebook(
         })
         .set_current_notebook(notebook_id.clone());
 
-    if let Some(notebook_id) = notebook_id.as_deref() {
-        {
-            let memo_file = read_lock(&state.memo_file, "memo_file");
-            let report = memo_file
-                .ensure_notebook_migrations(notebook_id)
-                .map_err(|error| format!("notebook migration failed: {error}"))?;
-            if report.moved_files > 0 || report.rebuilt_tags > 0 {
-                tracing::info!(
-                    notebook = %notebook_id,
-                    moved_files = report.moved_files,
-                    rebuilt_tags = report.rebuilt_tags,
-                    "notebook migrations completed"
-                );
-            }
-        };
-    }
-
     Ok(())
 }
 
@@ -286,9 +305,14 @@ pub(crate) fn is_registered_notebook_path_with_state(path: &Path, state: &AppSta
 }
 
 pub(crate) fn can_access_document_path(path: &Path, window: &str, state: &State<AppState>) -> bool {
-    is_registered_notebook_path(path, state)
-        || is_agent_access_folder(path, state)
-        || state.document_access.contains(window, path)
+    state.security_bookmarks.start_accessing_for_path(path);
+    let allowed = is_registered_notebook_path(path, state)
+        || is_attached_notebook_directory(path, state)
+        || state.document_access.contains(window, path);
+    if allowed && path.is_dir() {
+        state.security_bookmarks.record_accessible_directory(path);
+    }
+    allowed
 }
 
 pub(crate) fn can_access_scoped_file(
@@ -312,7 +336,7 @@ pub(crate) fn can_access_scoped_file_with_state(
     };
     let root = Path::new(space_path);
     (is_registered_notebook_path_with_state(root, state)
-        || is_agent_access_folder_with_state(root, state))
+        || is_attached_notebook_directory_with_state(root, state))
         && path_is_inside(file_path, root)
 }
 
@@ -333,19 +357,14 @@ pub(crate) fn is_internal_notebook_path_with_state(path: &Path, state: &AppState
         .any(|config| path_is_inside_reserved_directory(path, Path::new(&config.path), ".flowix"))
 }
 
-/// 侧栏"资料"文件夹作用域 ── agent access 配置里登记的 folder entry。
-/// `get_file_tree` / `read_file` 等文件树 IPC 用它放行用户添加的资料
-/// 文件夹 (这些目录不在注册笔记本列表里, `is_registered_notebook_path`
-/// 对它们返回 false)。
-pub(crate) fn is_agent_access_folder(path: &Path, state: &State<AppState>) -> bool {
-    is_agent_access_folder_with_state(path, state.inner())
+/// External file scopes come from enabled notebook mounts in local.db.
+pub(crate) fn is_attached_notebook_directory(path: &Path, state: &State<AppState>) -> bool {
+    is_attached_notebook_directory_with_state(path, state.inner())
 }
 
-pub(crate) fn is_agent_access_folder_with_state(path: &Path, state: &AppState) -> bool {
-    let config = state.agent_access.get_config();
-    config.entries.iter().any(|entry| {
-        entry.kind == crate::config::AgentAccessKind::Folder
-            && entry.enabled
-            && path_is_inside(path, Path::new(&entry.path))
-    })
+pub(crate) fn is_attached_notebook_directory_with_state(path: &Path, state: &AppState) -> bool {
+    let memo = read_lock(&state.memo_file, "memo_file");
+    memo.attached_directory_paths()
+        .map(|roots| roots.iter().any(|root| path_is_inside(path, root)))
+        .unwrap_or(false)
 }
diff --git a/app/flowix-desktop/src/commands/kv.rs b/app/flowix-desktop/src/commands/kv.rs
index ad8792c6f..6a287c6f9 100644
--- a/app/flowix-desktop/src/commands/kv.rs
+++ b/app/flowix-desktop/src/commands/kv.rs
@@ -4,7 +4,6 @@
 //! stored in each notebook's `.flowix/system.json`. The legacy global system
 //! store is read only to migrate a notebook the first time it is accessed.
 
-use std::collections::HashMap;
 use std::path::PathBuf;
 
 use tauri::State;
@@ -12,7 +11,7 @@ use tauri::State;
 use crate::app::state::AppState;
 use crate::system_data::{
     NotebookCustomViewsData, NotebookFeaturedNotesData,
-    NotebookFileTreePreferences, NotebookTagSystemData, SystemFile, TagLayoutItem, TagSystemData,
+    NotebookFileTreePreferences, NotebookTagSystemData, SystemFile, TagLayoutItem,
 };
 
 const FEATURED_NOTES_ALLOWED_OPERATORS: [&str; 3] = ["equals", "contains", "excludes"];
@@ -43,7 +42,6 @@ pub fn set_tag_system_layout(
 ) -> Result<(), String> {
     let mut file = load_notebook_system(&notebook_id, &state)?;
     let notebook = file.tag.notebooks.entry(notebook_id.clone()).or_default();
-    notebook.order = layout.iter().map(|item| item.id.clone()).collect();
     notebook.layout = layout;
     persist_notebook_system(&notebook_id, &state, &file)
 }
@@ -88,15 +86,9 @@ fn load_notebook_system(notebook_id: &str, state: &State<AppState>) -> Result<Sy
     {
         return Ok(file);
     }
-    let legacy = state.system_data.get_tag_metadata(notebook_id);
-    let mut notebooks = HashMap::new();
-    notebooks.insert(notebook_id.to_string(), legacy);
-    let file = SystemFile {
-        tag: TagSystemData { notebooks },
-        featured_notes: Default::default(),
-        custom_views: Default::default(),
-        file_tree: Default::default(),
-    };
+    // Legacy global tag metadata is intentionally not imported. A reset starts
+    // notebook-scoped system data with defaults; users can configure it again.
+    let file = SystemFile::default();
     crate::system_data::SystemData::write_notebook(&root, &file)
         .map_err(|error| error.to_string())?;
     Ok(file)
diff --git a/app/flowix-desktop/src/commands/media.rs b/app/flowix-desktop/src/commands/media.rs
index 769606f06..3f8d0bc03 100644
--- a/app/flowix-desktop/src/commands/media.rs
+++ b/app/flowix-desktop/src/commands/media.rs
@@ -16,7 +16,7 @@ use flowix_core::memo_file::{
 use crate::app::state::AppState;
 use crate::lock_utils::read_lock;
 
-use super::helpers::{can_access_scoped_file, start_security_bookmark_access};
+use super::helpers::can_access_scoped_file;
 
 fn registered_notebook_for_path(
     memo_file: &MemoFile,
@@ -131,7 +131,6 @@ pub async fn get_media_resource(
         let resource = memo_file
             .ensure_media_resource(&notebook_id, &relative, kind, &file)
             .map_err(|error| error.to_string())?;
-        start_security_bookmark_access(&state, &file);
         Ok(MediaResourceResponse { resource })
     }).await?
 }
@@ -207,7 +206,6 @@ pub async fn delete_media_resource(
         let resource = memo_file
             .ensure_media_resource(&notebook_id, &relative, kind, &file)
             .map_err(|error| error.to_string())?;
-        start_security_bookmark_access(&state, &file);
         memo_file
             .delete_file_for_notebook(&notebook_id, &file)
             .map_err(|error| error.to_string())?;
diff --git a/app/flowix-desktop/src/commands/memo/creates.rs b/app/flowix-desktop/src/commands/memo/creates.rs
index ff6e265f3..b6b43ae40 100644
--- a/app/flowix-desktop/src/commands/memo/creates.rs
+++ b/app/flowix-desktop/src/commands/memo/creates.rs
@@ -13,12 +13,12 @@ use std::path::{Component, Path, PathBuf};
 use tauri::{AppHandle, Emitter, Manager, State};
 
 use crate::lock_utils::read_lock;
-use crate::memo_events::{self, MemoChangeSource, MemoDerivedChanged, MemoEvent};
+use crate::commands::helpers::FileOperationFailure;
 use crate::USER_CONFIG_DIR_NAME;
 use flowix_core::memo_file::{
     atomic_create_bytes, atomic_write_bytes, extract_body_content, extract_document_metadata,
     FileManagementPolicy, Memo, MemoFile, NotebookSetupJob, NotebookSetupJobStatus,
-    NotebookSetupReport,
+    NotebookSetupReport, NotebookSetupStage,
 };
 use flowix_core::NoteService;
 
@@ -44,6 +44,13 @@ pub struct CreatedPathDocumentResult {
     path: String,
     initial_content: String,
     entry: flowix_core::memo_file::NoteEntry,
+    notebook_change: super::super::path_change::NotebookPathCreated,
+}
+
+impl CreatedPathDocumentResult {
+    fn publish_created(&self, app: &AppHandle) {
+        self.notebook_change.emit(app);
+    }
 }
 
 fn default_parent_relative_path(
@@ -64,8 +71,10 @@ pub async fn add_path_document(
     notebook_id: String,
     // None uses the notebook's default create folder; Some("") explicitly uses its root.
     parent_relative_path: Option<String>,
+    window: tauri::WebviewWindow,
     app: AppHandle,
 ) -> Result<CreatedPathDocumentResult, MemoCreateError> {
+    let origin_window_label = window.label().to_string();
     let title = title.filter(|value| !value.trim().is_empty())
         .unwrap_or_else(|| chrono::Local::now().format("%Y-%m-%d").to_string());
     crate::document_io::run("create_path_document", move || {
@@ -83,13 +92,21 @@ pub async fn add_path_document(
         let created = NoteService::new(&memo_file)
             .create(&notebook_id, effective_parent.as_deref(), &title, &body)?;
         mark_self_write_for(&app, &created.path);
-        Ok::<_, MemoCreateError>(CreatedPathDocumentResult {
+        let notebook_change = super::super::path_change::NotebookPathCreated::from_window(
+            created.notebook.id.clone(),
+            created.entry.relative_path.clone(),
+            origin_window_label,
+        );
+        let result = CreatedPathDocumentResult {
             notebook_id: created.notebook.id,
             relative_path: created.entry.relative_path.clone(),
             path: created.path.to_string_lossy().to_string(),
             initial_content: created.body,
             entry: created.entry,
-        })
+            notebook_change,
+        };
+        result.publish_created(&app);
+        Ok::<_, MemoCreateError>(result)
     }).await.map_err(|message| MemoCreateError { code: "INTERNAL_ERROR", message })?
 }
 
@@ -232,6 +249,7 @@ pub fn create_path_from_template(
     template_id: String,
     notebook_id: String,
     state: State<AppState>,
+    window: tauri::WebviewWindow,
     app: AppHandle,
 ) -> Result<CreatedPathDocumentResult, String> {
     let template_name = Path::new(&template_id).file_name().and_then(|name| name.to_str())
@@ -250,13 +268,21 @@ pub fn create_path_from_template(
         .create(&notebook_id, parent.as_deref(), &title, body)
         .map_err(|e| e.to_string())?;
     mark_self_write_for(&app, &created.path);
-    Ok(CreatedPathDocumentResult {
+    let notebook_change = super::super::path_change::NotebookPathCreated::from_window(
+        created.notebook.id.clone(),
+        created.entry.relative_path.clone(),
+        window.label().to_string(),
+    );
+    let result = CreatedPathDocumentResult {
         notebook_id: created.notebook.id,
         relative_path: created.entry.relative_path.clone(),
         path: created.path.to_string_lossy().to_string(),
         initial_content: created.body,
         entry: created.entry,
-    })
+        notebook_change,
+    };
+    result.publish_created(&app);
+    Ok(result)
 }
 
 #[tauri::command]
@@ -266,6 +292,7 @@ pub fn import_external_document_by_path(
     content: String,
     notebook_id: String,
     state: State<AppState>,
+    window: tauri::WebviewWindow,
     app: AppHandle,
 ) -> Result<CreatedPathDocumentResult, String> {
     let title = Path::new(&file_path).file_stem().and_then(|stem| stem.to_str())
@@ -277,13 +304,21 @@ pub fn import_external_document_by_path(
         .create(&notebook_id, parent.as_deref(), title, &content)
         .map_err(|error| error.to_string())?;
     mark_self_write_for(&app, &created.path);
-    Ok(CreatedPathDocumentResult {
+    let notebook_change = super::super::path_change::NotebookPathCreated::from_window(
+        created.notebook.id.clone(),
+        created.entry.relative_path.clone(),
+        window.label().to_string(),
+    );
+    let result = CreatedPathDocumentResult {
         notebook_id: created.notebook.id,
         relative_path: created.entry.relative_path.clone(),
         path: created.path.to_string_lossy().to_string(),
         initial_content: created.body,
         entry: created.entry,
-    })
+        notebook_change,
+    };
+    result.publish_created(&app);
+    Ok(result)
 }
 
 #[derive(serde::Deserialize, serde::Serialize, Clone)]
@@ -315,7 +350,7 @@ const MAX_NOTEBOOK_TEMPLATE_FILES: usize = 2_000;
 const MAX_NOTEBOOK_TEMPLATE_BYTES: usize = 10 * 1024 * 1024;
 const NOTEBOOK_TEMPLATE_INIT_MARKER: &str = ".flowix/notebook-template-initializing.json";
 
-fn validate_notebook_template(template: &NotebookTemplate) -> Result<(), String> {
+pub(crate) fn validate_notebook_template(template: &NotebookTemplate) -> Result<(), String> {
     if template.id.trim().is_empty()
         || template.id.len() > 128
         || template.id.chars().any(char::is_control)
@@ -334,6 +369,8 @@ fn validate_notebook_template(template: &NotebookTemplate) -> Result<(), String>
 }
 
 fn read_notebook_template_index() -> Result<Vec<NotebookTemplate>, String> {
+    let home = dirs::home_dir().ok_or_else(|| "template directory not available".to_string())?;
+    template_store::initialize_notebook_templates(&home.join(USER_CONFIG_DIR_NAME))?;
     let directory =
         notebook_template_dir().ok_or_else(|| "template directory not available".to_string())?;
     let path = directory.join("index.json");
@@ -354,10 +391,10 @@ fn read_notebook_template_index() -> Result<Vec<NotebookTemplate>, String> {
 }
 
 #[tauri::command]
-pub fn list_notebook_templates() -> Result<Vec<NotebookTemplate>, String> {
-    let home = dirs::home_dir().ok_or_else(|| "template directory not available".to_string())?;
-    template_store::initialize_notebook_templates(&home.join(USER_CONFIG_DIR_NAME))?;
-    read_notebook_template_index()
+pub async fn list_notebook_templates() -> Result<Vec<NotebookTemplate>, String> {
+    tauri::async_runtime::spawn_blocking(read_notebook_template_index)
+        .await
+        .map_err(|error| format!("notebook template list task failed: {error}"))?
 }
 
 pub(crate) fn validate_notebook_template_id(template_id: &str) -> Result<(), String> {
@@ -374,86 +411,42 @@ pub(crate) fn validate_notebook_template_id(template_id: &str) -> Result<(), Str
     }
 }
 
-/// Attach a deferred template to an already registered notebook.
-/// This is used by retry-safe onboarding when its chosen default path was
-/// registered before the current onboarding attempt.
-#[tauri::command]
-pub fn ensure_notebook_template_setup(
-    notebook_id: String,
-    template_id: String,
-    overwrite_existing: Option<bool>,
-    state: State<AppState>,
-) -> Result<NotebookSetupJob, String> {
-    validate_notebook_template_id(&template_id)?;
-    let running = state
-        .notebook_template_initializations
-        .lock()
-        .unwrap_or_else(|poisoned| poisoned.into_inner());
-    let memo_file = read_lock(&state.memo_file, "memo_file");
-    let notebook = memo_file
-        .get_notebook_config_by_id(&notebook_id)
-        .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
-    let existing = memo_file
-        .get_notebook_setup_job(&notebook_id)
-        .map_err(|error| format!("read notebook setup status failed: {error}"))?;
-    if let Some(existing) = &existing {
-        if existing.template_id.as_deref() != Some(template_id.as_str()) {
-            return Err("NOTEBOOK_TEMPLATE_SELECTION_CONFLICT".to_string());
-        }
-    }
+pub(crate) fn resolve_notebook_template(template_id: &str) -> Result<NotebookTemplate, String> {
+    let templates = read_notebook_template_index()?;
+    find_notebook_template(&templates, template_id)
+        .cloned()
+        .ok_or_else(|| "UNKNOWN_NOTEBOOK_TEMPLATE".to_string())
+}
 
-    let notebook_root = PathBuf::from(&notebook.path);
-    if !notebook_root.is_dir() {
-        return Err("PATH_MISSING".to_string());
-    }
-    let overwrite_existing = overwrite_existing.unwrap_or(false);
-    if existing.is_none()
-        && !overwrite_existing
-        && super::super::notebook::notebook_folder_has_content(&notebook_root)?
-    {
-        return Err("NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED".to_string());
-    }
-    if overwrite_existing
-        && existing.as_ref().is_some_and(|job| !job.overwrite_existing)
-        && running.contains(&notebook_id)
-    {
-        return Err("NOTEBOOK_TEMPLATE_SETUP_IN_PROGRESS".to_string());
-    }
-    MemoFile::ensure_notebook_scene_id(&notebook, &template_id)
-        .map_err(|error| format!("NOTEBOOK_SCENE_ID_WRITE_FAILED: {error}"))?;
-
-    if let Some(mut existing) = existing {
-        if overwrite_existing && !existing.overwrite_existing {
-            existing.overwrite_existing = true;
-            existing.status = NotebookSetupJobStatus::Pending;
-            existing.stage = "template".to_string();
-            existing.completed_files = 0;
-            existing.total_files = 0;
-            existing.message = None;
-            existing.report = None;
-            existing.updated_at = chrono::Utc::now().timestamp_millis();
-            memo_file
-                .write_notebook_setup_job(&existing)
-                .map_err(|error| format!("persist notebook setup status failed: {error}"))?;
-        }
-        return Ok(existing);
+fn find_notebook_template<'a>(
+    templates: &'a [NotebookTemplate],
+    template_id: &str,
+) -> Option<&'a NotebookTemplate> {
+    templates
+        .iter()
+        .find(|template| template.id == template_id)
+        .or_else(|| {
+            // Preserve the legacy scene-to-preset mapping for durable jobs and markers.
+            template_id
+                .strip_prefix("scene-")
+                .and_then(|number| number.parse::<usize>().ok())
+                .and_then(|number| number.checked_sub(1))
+                .and_then(|index| templates.get(index))
+        })
+}
+
+pub(crate) fn notebook_template_ids_match(left: &str, right: &str) -> Result<bool, String> {
+    if left == right {
+        return Ok(true);
     }
-    let job = NotebookSetupJob {
-        notebook_id,
-        template_id: Some(template_id),
-        overwrite_existing,
-        status: NotebookSetupJobStatus::Pending,
-        stage: "template".to_string(),
-        completed_files: 0,
-        total_files: 0,
-        message: None,
-        report: None,
-        updated_at: chrono::Utc::now().timestamp_millis(),
-    };
-    memo_file
-        .write_notebook_setup_job(&job)
-        .map_err(|error| format!("persist notebook setup status failed: {error}"))?;
-    Ok(job)
+    let templates = read_notebook_template_index()?;
+    Ok(match (
+        find_notebook_template(&templates, left),
+        find_notebook_template(&templates, right),
+    ) {
+        (Some(left), Some(right)) => left.id == right.id,
+        _ => false,
+    })
 }
 
 fn load_notebook_template_files(
@@ -497,9 +490,8 @@ fn load_notebook_template_files_with_failures(
         return Err("INVALID_NOTEBOOK_TEMPLATE_DIRECTORY".to_string());
     }
 
-    let mut files = Vec::new();
     let mut failures = Vec::new();
-    let mut total_bytes = 0usize;
+    let mut sources = Vec::new();
     let mut scanned_files = 0usize;
     for entry in walkdir::WalkDir::new(&source).follow_links(false) {
         let entry = match entry {
@@ -544,7 +536,13 @@ fn load_notebook_template_files_with_failures(
         if scanned_files > MAX_NOTEBOOK_TEMPLATE_FILES {
             return Err("NOTEBOOK_TEMPLATE_TOO_LARGE".to_string());
         }
-        match fs::read(entry.path()) {
+        sources.push((path, entry.path().to_path_buf()));
+    }
+
+    let mut files = Vec::with_capacity(sources.len());
+    let mut total_bytes = 0usize;
+    for (path, source_path) in sources {
+        match fs::read(source_path) {
             Ok(content) => {
                 total_bytes = total_bytes
                     .checked_add(path.len())
@@ -557,7 +555,6 @@ fn load_notebook_template_files_with_failures(
             }
             Err(error) => failures.push((path, error.to_string())),
         }
-
     }
 
     files.sort_by(|left, right| left.path.cmp(&right.path));
@@ -723,15 +720,15 @@ mod notebook_template_content_tests {
         validate_notebook_template_path, NotebookTemplateIndex,
     };
     use flowix_core::memo_file::{
-        atomic_write_bytes, extract_frontmatter_key, is_ignored_notebook_relative_path, MemoFile,
+        atomic_write_bytes, is_ignored_notebook_relative_path, MemoFile,
         NotebookConfig,
     };
-    use flowix_core::MemoService;
+    use flowix_core::NoteService;
     use std::fs;
     use std::path::Path;
 
     #[test]
-    fn scenario_template_creates_all_indexed_notes_and_replaces_source_keys() {
+    fn scenario_template_indexes_markdown_notes_by_path() {
         let directory = tempfile::tempdir().expect("temporary template test directory");
         let config_dir = directory.path().join("config");
         crate::template_store::initialize_notebook_templates(&config_dir)
@@ -802,16 +799,10 @@ mod notebook_template_content_tests {
                     .unwrap_or_else(|error| panic!("decode {}: {error}", file.path));
                 let parent_relative =
                     parent_relative.map(|parent| parent.to_string_lossy().replace('\\', "/"));
-                let created = MemoService::new(&memo_file)
-                    .create_memo_named_with_tag_in_directory(
-                        Some("nb_template_test"),
-                        parent_relative.as_deref(),
-                        title,
-                        content,
-                        None,
-                    )
+                let created = NoteService::new(&memo_file)
+                    .create("nb_template_test", parent_relative.as_deref(), title, content)
                     .unwrap_or_else(|error| panic!("create {}: {error}", file.path));
-                created_notes.push((created.memo.id, created.path));
+                created_notes.push(created.path);
             } else {
                 atomic_write_bytes(&parent.join(filename), &file.content)
                     .unwrap_or_else(|error| panic!("copy {}: {error}", file.path));
@@ -819,9 +810,9 @@ mod notebook_template_content_tests {
         }
 
         assert_eq!(created_notes.len(), expected_note_count);
-        for (_id, path) in created_notes {
+        for path in created_notes {
             let content = fs::read_to_string(path).expect("read created template note");
-            assert_eq!(extract_frontmatter_key(&content), None);
+            assert!(!content.contains("flowix_key:"));
         }
     }
 }
@@ -853,13 +844,58 @@ fn read_notebook_template_init_marker(path: &Path) -> Result<Option<String>, Str
     Ok(Some(marker.template_id))
 }
 
+/// Remove a template initialization marker left behind if the process exited
+/// after persisting the indexing stage but before normal marker cleanup.
+pub(crate) fn clear_notebook_template_init_marker(
+    notebook_id: &str,
+    template_id: &str,
+    state: &AppState,
+) -> Result<(), String> {
+    let notebook_root = read_lock(&state.memo_file, "memo_file")
+        .get_notebook_config_by_id(notebook_id)
+        .map(|config| PathBuf::from(config.path))
+        .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
+    let notebook_root = fs::canonicalize(&notebook_root)
+        .map_err(|error| format!("resolve notebook directory failed: {error}"))?;
+    let internal_dir = notebook_root.join(".flowix");
+    let internal_metadata = match fs::symlink_metadata(&internal_dir) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(error) => return Err(format!("inspect notebook metadata directory failed: {error}")),
+    };
+    if !internal_metadata.is_dir() && !internal_metadata.file_type().is_symlink() {
+        return Err("TEMPLATE_PATH_OUTSIDE_NOTEBOOK".to_string());
+    }
+    let canonical_internal_dir = fs::canonicalize(&internal_dir)
+        .map_err(|error| format!("resolve notebook metadata directory failed: {error}"))?;
+    if !canonical_internal_dir.starts_with(&notebook_root)
+        || !fs::metadata(&canonical_internal_dir)
+            .map_err(|error| format!("inspect notebook metadata directory failed: {error}"))?
+            .is_dir()
+    {
+        return Err("TEMPLATE_PATH_OUTSIDE_NOTEBOOK".to_string());
+    }
+
+    let marker_path = canonical_internal_dir.join("notebook-template-initializing.json");
+    match read_notebook_template_init_marker(&marker_path)? {
+        None => Ok(()),
+        Some(existing) => {
+            if !notebook_template_ids_match(&existing, template_id)? {
+                return Err("NOTEBOOK_TEMPLATE_INITIALIZATION_IN_PROGRESS".to_string());
+            }
+            fs::remove_file(&marker_path)
+                .map_err(|error| format!("remove template initialization marker failed: {error}"))
+        }
+    }
+}
+
 fn begin_notebook_template_initialization(
     notebook_root: &Path,
     template_id: &str,
 ) -> Result<PathBuf, String> {
     let marker_path = notebook_root.join(NOTEBOOK_TEMPLATE_INIT_MARKER);
     if let Some(existing_template_id) = read_notebook_template_init_marker(&marker_path)? {
-        if existing_template_id == template_id {
+        if notebook_template_ids_match(&existing_template_id, template_id)? {
             return Ok(marker_path);
         }
         return Err("NOTEBOOK_TEMPLATE_INITIALIZATION_IN_PROGRESS".to_string());
@@ -898,7 +934,7 @@ fn begin_notebook_template_initialization(
         Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
             let existing_template_id = read_notebook_template_init_marker(&marker_path)?
                 .ok_or_else(|| "INVALID_NOTEBOOK_TEMPLATE_MARKER".to_string())?;
-            if existing_template_id != template_id {
+            if !notebook_template_ids_match(&existing_template_id, template_id)? {
                 return Err("NOTEBOOK_TEMPLATE_INITIALIZATION_IN_PROGRESS".to_string());
             }
         }
@@ -930,14 +966,12 @@ pub async fn initialize_notebook_template(
             false,
             state.inner(),
             &app,
+            None,
             |_| Ok(()),
         )?;
 
         let index_report = {
             let memo_file = read_lock(&state.memo_file, "memo_file");
-            memo_file
-                .ensure_notebook_migrations(&notebook_id)
-                .map_err(|error| format!("notebook import migration failed: {error}"))?;
             memo_file
                 .reconcile_note_index(&notebook_id)
                 .map_err(|error| format!("notebook path reconciliation failed: {error}"))?
@@ -955,6 +989,19 @@ pub async fn initialize_notebook_template(
     .map_err(|error| format!("notebook template initialization task failed: {error}"))?
 }
 
+struct NotebookTemplateWatchSuspension<'a> {
+    state: &'a AppState,
+    app: &'a AppHandle,
+    notebook_id: &'a str,
+}
+
+impl Drop for NotebookTemplateWatchSuspension<'_> {
+    fn drop(&mut self) {
+        crate::commands::helpers::set_notebook_watching_suspended(self.app, self.notebook_id, false);
+        crate::commands::helpers::refresh_notebook_watcher(self.state, self.app, self.notebook_id);
+    }
+}
+
 pub(crate) fn initialize_notebook_template_for_notebook(
     notebook_id: &str,
     template_id: &str,
@@ -962,10 +1009,17 @@ pub(crate) fn initialize_notebook_template_for_notebook(
     overwrite_existing: bool,
     state: &AppState,
     app: &AppHandle,
+    setup_job: Option<&NotebookSetupJob>,
     after_template_files_written: impl FnOnce(&NotebookSetupReport) -> Result<(), String>,
 ) -> Result<NotebookSetupReport, String> {
     let watched_notebook_id = notebook_id.to_string();
     let started = std::time::Instant::now();
+    // Drop restores the watch even when template loading or writing panics.
+    let watching_suspension = NotebookTemplateWatchSuspension {
+        state,
+        app,
+        notebook_id,
+    };
     // A retried template may already be watched; unbind it before any writes.
     crate::commands::helpers::set_notebook_watching_suspended(app, notebook_id, true);
     crate::commands::helpers::refresh_notebook_watcher(state, app, notebook_id);
@@ -978,12 +1032,12 @@ pub(crate) fn initialize_notebook_template_for_notebook(
         _is_new_notebook,
         state,
         app,
+        setup_job,
         after_template_files_written,
     );
     let write_ms = write_started.elapsed().as_millis();
     let resume_started = std::time::Instant::now();
-    crate::commands::helpers::set_notebook_watching_suspended(app, notebook_id, false);
-    crate::commands::helpers::refresh_notebook_watcher(state, app, notebook_id);
+    drop(watching_suspension);
     crate::runtime_log::record_event(
         "info", "notebook.template.timing",
         format!("notebook={} suspend_ms={} write_ms={} resume_ms={} total_ms={} success={} created={}",
@@ -1001,28 +1055,23 @@ fn initialize_notebook_template_inner(
     _is_new_notebook: bool,
     state: &AppState,
     app: &AppHandle,
+    setup_job: Option<&NotebookSetupJob>,
     after_template_files_written: impl FnOnce(&NotebookSetupReport) -> Result<(), String>,
 ) -> Result<NotebookSetupReport, String> {
     if notebook_id.trim().is_empty() {
         return Err("INVALID_NOTEBOOK_TEMPLATE".to_string());
     }
 
-    let templates = read_notebook_template_index()?;
-    let template = templates
-        .iter()
-        .find(|template| template.id == template_id)
-        .or_else(|| {
-            // Resume setup jobs written by earlier versions before the scene
-            // IDs were renamed to preset IDs.
-            template_id
-                .strip_prefix("scene-")
-                .and_then(|number| number.parse::<usize>().ok())
-                .filter(|number| (1..=templates.len()).contains(number))
-                .and_then(|number| templates.get(number - 1))
-        })
-        .cloned()
-        .ok_or_else(|| "UNKNOWN_NOTEBOOK_TEMPLATE".to_string())?;
+    let template = resolve_notebook_template(&template_id)?;
     let template_id = template.id.clone();
+    if let Some(setup_job) = setup_job {
+        let mut preparing = setup_job.clone();
+        preparing.stage = NotebookSetupStage::Preparing;
+        preparing.message = None;
+        preparing.report = None;
+        preparing.updated_at = chrono::Utc::now().timestamp_millis();
+        super::super::notebook_setup::persist_notebook_setup_job(state, app, preparing)?;
+    }
     let (files, source_failures) = load_notebook_template_files(&template)?;
 
     let notebook_root = read_lock(&state.memo_file, "memo_file")
@@ -1044,99 +1093,109 @@ fn initialize_notebook_template_inner(
     for (path, reason) in source_failures {
         record_notebook_template_failure(&mut report, &path, reason);
     }
+    if let Some(setup_job) = setup_job {
+        let mut writing_status = setup_job.clone();
+        writing_status.stage = NotebookSetupStage::Writing;
+        writing_status.message = None;
+        writing_status.report = Some(report.clone());
+        writing_status.updated_at = chrono::Utc::now().timestamp_millis();
+        super::super::notebook_setup::persist_notebook_setup_job(state, app, writing_status)?;
+    }
     for file in files {
-        let relative = match validate_notebook_template_path(&file.path) {
-            Ok(relative) => relative,
-            Err(error) => {
-                record_notebook_template_failure(&mut report, &file.path, error);
-                continue;
-            }
-        };
-        if !seen_paths.insert(relative.clone()) {
-            record_notebook_template_failure(
-                &mut report,
-                &file.path,
-                "DUPLICATE_TEMPLATE_PATH",
-            );
-            continue;
-        }
-
-        let parent_relative = relative
-            .parent()
-            .filter(|parent| !parent.as_os_str().is_empty());
-        let parent = match ensure_notebook_template_parent(&notebook_root, parent_relative) {
-            Ok(parent) => parent,
-            Err(error) => {
-                record_notebook_template_failure(&mut report, &file.path, error);
-                continue;
-            }
-        };
-
-        let Some(filename) = relative.file_name() else {
-            record_notebook_template_failure(&mut report, &file.path, "INVALID_TEMPLATE_PATH");
-            continue;
-        };
-        let target = parent.join(filename);
-        match fs::symlink_metadata(&target) {
-            Ok(metadata) if metadata.file_type().is_file() && !overwrite_existing => {
-                report.skipped_existing_files += 1;
-                continue;
-            }
-            Ok(metadata) if metadata.file_type().is_file() => {}
-            Ok(_) => {
+        'process_file: {
+            let relative = match validate_notebook_template_path(&file.path) {
+                Ok(relative) => relative,
+                Err(error) => {
+                    record_notebook_template_failure(&mut report, &file.path, error);
+                    break 'process_file;
+                }
+            };
+            if !seen_paths.insert(relative.clone()) {
                 record_notebook_template_failure(
                     &mut report,
                     &file.path,
-                    "template destination exists but is not a regular file",
+                    "DUPLICATE_TEMPLATE_PATH",
                 );
-                continue;
-            }
-            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
-            Err(error) => {
-                record_notebook_template_failure(&mut report, &file.path, error);
-                continue;
+                break 'process_file;
             }
-        }
 
-        let is_markdown = relative
-            .extension()
-            .and_then(|extension| extension.to_str())
-            .is_some_and(|extension| extension.eq_ignore_ascii_case("md"));
-        if is_markdown && !file_management_policy.is_ignored_at(&notebook_root, &relative) {
-            let content = match std::str::from_utf8(&file.content) {
-                Ok(content) => content,
+            let parent_relative = relative
+                .parent()
+                .filter(|parent| !parent.as_os_str().is_empty());
+            let parent = match ensure_notebook_template_parent(&notebook_root, parent_relative) {
+                Ok(parent) => parent,
                 Err(error) => {
+                    record_notebook_template_failure(&mut report, &file.path, error);
+                    break 'process_file;
+                }
+            };
+
+            let Some(filename) = relative.file_name() else {
+                record_notebook_template_failure(&mut report, &file.path, "INVALID_TEMPLATE_PATH");
+                break 'process_file;
+            };
+            let target = parent.join(filename);
+            match fs::symlink_metadata(&target) {
+                Ok(metadata) if metadata.file_type().is_file() && !overwrite_existing => {
+                    report.skipped_existing_files += 1;
+                    break 'process_file;
+                }
+                Ok(metadata) if metadata.file_type().is_file() => {}
+                Ok(_) => {
                     record_notebook_template_failure(
                         &mut report,
                         &file.path,
-                        format!("invalid markdown template encoding: {error}"),
+                        "template destination exists but is not a regular file",
                     );
-                    continue;
+                    break 'process_file;
+                }
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                Err(error) => {
+                    record_notebook_template_failure(&mut report, &file.path, error);
+                    break 'process_file;
                 }
-            };
-            if let Err(error) = extract_document_metadata(content) {
-                record_notebook_template_failure(&mut report, &file.path, error);
-                continue;
             }
-        }
 
-        // Use an exclusive atomic create for every template file. In
-        // particular, a user-created file racing this background task must
-        // never be replaced by atomic_write_bytes.
-        let write_result = if overwrite_existing {
-            atomic_write_bytes(&target, &file.content)
-        } else {
-            atomic_create_bytes(&target, &file.content)
-        };
-        match write_result {
-            Ok(()) => {
-                report.written_files += 1;
-                mark_self_write_for(app, &target);
+            let is_markdown = relative
+                .extension()
+                .and_then(|extension| extension.to_str())
+                .is_some_and(|extension| extension.eq_ignore_ascii_case("md"));
+            if is_markdown && !file_management_policy.is_ignored_at(&notebook_root, &relative) {
+                let content = match std::str::from_utf8(&file.content) {
+                    Ok(content) => content,
+                    Err(error) => {
+                        record_notebook_template_failure(
+                            &mut report,
+                            &file.path,
+                            format!("invalid markdown template encoding: {error}"),
+                        );
+                        break 'process_file;
+                    }
+                };
+                if let Err(error) = extract_document_metadata(content) {
+                    record_notebook_template_failure(&mut report, &file.path, error);
+                    break 'process_file;
+                }
             }
-            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
-                report.skipped_existing_files += 1;
+
+            // Use an exclusive atomic create for every template file. In
+            // particular, a user-created file racing this background task must
+            // never be replaced by atomic_write_bytes.
+            let write_result = if overwrite_existing {
+                atomic_write_bytes(&target, &file.content)
+            } else {
+                atomic_create_bytes(&target, &file.content)
+            };
+            match write_result {
+                Ok(()) => {
+                    report.written_files += 1;
+                    mark_self_write_for(app, &target);
+                }
+                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
+                    report.skipped_existing_files += 1;
+                }
+                Err(error) => record_notebook_template_failure(&mut report, &file.path, error),
             }
-            Err(error) => record_notebook_template_failure(&mut report, &file.path, error),
         }
     }
 
@@ -1170,6 +1229,7 @@ fn record_notebook_template_failure(
 #[derive(serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct RenameMemoTitleResult {
+    pub notebook_change: super::super::path_change::NotebookPathMove,
     pub memo: Option<Memo>,
     pub path: String,
     pub filename: String,
@@ -1178,11 +1238,11 @@ pub struct RenameMemoTitleResult {
 #[derive(serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MoveMemoResult {
+    pub notebook_change: super::super::path_change::NotebookPathMove,
     pub path: String,
 }
 
-/// Move a notebook note by relative path. Updating the legacy memo projection
-/// is optional and happens only when a compatibility row already exists.
+/// Move a notebook note by relative path.
 #[tauri::command]
 pub fn move_memo_to_directory(
     file_path: String,
@@ -1190,12 +1250,13 @@ pub fn move_memo_to_directory(
     parent_relative_path: String,
     state: State<AppState>,
     app: AppHandle,
-) -> Result<MoveMemoResult, String> {
+) -> Result<MoveMemoResult, FileOperationFailure> {
     let requested_path = Path::new(&file_path);
     if !requested_path.is_absolute() {
         return Err("absolute document path required".into());
     }
-    let (moved, before, compatibility_memo, old_relative, old_path) = {
+    let _watch_move = crate::commands::external_document_watch::begin_path_move(&app, requested_path);
+    let (moved, old_relative, old_path) = {
         let memo_file = read_lock(&state.memo_file, "memo_file");
         let (source_notebook_id, relative_path) =
             notebook_note_address(&memo_file, requested_path)?.ok_or_else(|| {
@@ -1204,29 +1265,19 @@ pub fn move_memo_to_directory(
         if source_notebook_id != notebook_id {
             return Err("note does not belong to the selected notebook".into());
         }
-        let before = memo_file
-            .find_memo_by_relative_path_for_notebook_id(&source_notebook_id, &relative_path);
         let mut service = NoteService::new(&memo_file);
         let original = service
             .get(&source_notebook_id, &relative_path)
-            .map_err(|error| error.to_string())?;
+            .map_err(FileOperationFailure::from)?;
         mark_self_write_for(&app, &original.path);
         let moved = service
             .move_to(&source_notebook_id, &relative_path, &parent_relative_path)
-            .map_err(|error| error.to_string())?;
+            .map_err(FileOperationFailure::from)?;
         drop(service);
         mark_self_write_for(&app, &moved.path);
-        let compatibility_memo = before.as_ref().and_then(|_| {
-            memo_file
-                .rename_memo_file_for_notebook_id(
-                    &source_notebook_id,
-                    &original.path,
-                    &moved.path,
-                )
-                .ok()
-        });
-        (moved, before, compatibility_memo, relative_path, original.path)
+        (moved, relative_path, original.path)
     };
+    crate::commands::external_document_watch::rebase_path(&app, requested_path, &moved.path);
     {
         let memo_file = read_lock(&state.memo_file, "memo_file");
         crate::commands::document_list::rebase_collection_paths(
@@ -1247,31 +1298,12 @@ pub fn move_memo_to_directory(
             "note was moved but agent note references could not be rebased: {error}"
         );
     }
-    let _ = app.emit("flowix:path-note-changed", serde_json::json!({
-        "notebookId": notebook_id.clone(),
-        "relativePath": moved.entry.relative_path.clone(),
-        "deleted": false,
-    }));
-    if let Some(memo) = compatibility_memo.as_ref() {
-        let derived_changed = MemoDerivedChanged::from_memos(before.as_ref(), memo);
-        emit_updated_memo_event(
-            &app,
-            &memo.id,
-            moved.path.to_string_lossy().into_owned(),
-            memo.clone(),
-            moved.notebook.id.clone(),
-            derived_changed,
-            MemoChangeSource::UserEdit,
-            None,
-        );
-    } else if before.is_some() {
-        tracing::warn!(
-            notebook_id = %moved.notebook.id,
-            relative_path = %moved.entry.relative_path,
-            "path-based note move succeeded; legacy memo projection could not be updated"
-        );
-    }
+    let notebook_change = super::super::path_change::NotebookPathMove::new(
+        notebook_id.clone(), old_relative, moved.entry.relative_path.clone(), false,
+    );
+    notebook_change.emit(&app);
     Ok(MoveMemoResult {
+        notebook_change,
         path: moved.path.to_string_lossy().into_owned(),
     })
 }
@@ -1326,6 +1358,7 @@ fn rename_memo_title_blocking(
     if !requested_path.is_absolute() {
         return Err("absolute document path required".into());
     }
+    let _watch_move = crate::commands::external_document_watch::begin_path_move(&app, requested_path);
     let (renamed, old_relative, old_path) = {
         let memo_file = read_lock(&state.memo_file, "memo_file");
         let (notebook_id, relative_path) = notebook_note_address(&memo_file, requested_path)?
@@ -1350,6 +1383,7 @@ fn rename_memo_title_blocking(
         mark_self_write_for(&app, &renamed.path);
         (renamed, relative_path, original.path)
     };
+    crate::commands::external_document_watch::rebase_path(&app, requested_path, &renamed.path);
     {
         let memo_file = read_lock(&state.memo_file, "memo_file");
         crate::commands::document_list::rebase_collection_paths(
@@ -1371,11 +1405,12 @@ fn rename_memo_title_blocking(
         );
     }
     let path = renamed.path.to_string_lossy().into_owned();
-    let _ = app.emit("flowix:path-note-changed", serde_json::json!({
-        "notebookId": renamed.notebook.id,
-        "relativePath": renamed.entry.relative_path,
-    }));
+    let notebook_change = super::super::path_change::NotebookPathMove::new(
+        renamed.notebook.id.clone(), old_relative, renamed.entry.relative_path.clone(), false,
+    );
+    notebook_change.emit(&app);
     Ok(RenameMemoTitleResult {
+        notebook_change,
         memo: None,
         path,
         filename: renamed
diff --git a/app/flowix-desktop/src/commands/memo/deletes.rs b/app/flowix-desktop/src/commands/memo/deletes.rs
index 72f96170f..13f31e9f7 100644
--- a/app/flowix-desktop/src/commands/memo/deletes.rs
+++ b/app/flowix-desktop/src/commands/memo/deletes.rs
@@ -5,12 +5,10 @@ use std::path::Path;
 use tauri::{AppHandle, State};
 
 use crate::lock_utils::read_lock;
-use crate::memo_events::{self, MemoChangeSource, MemoDerivedChanged, MemoEvent};
 
 use crate::app::state::AppState;
 use crate::watcher::runtime::mark_self_write_for;
-use flowix_core::memo_file::notebook_path_from_relative;
-use flowix_core::{MemoService, NoteService};
+use flowix_core::NoteService;
 
 #[derive(serde::Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -26,6 +24,14 @@ pub enum PruneMissingMemoOutcome {
     MissingCleaned,
 }
 
+fn emit_deleted_path(app: &AppHandle, notebook_id: &str, relative_path: &str) {
+    crate::commands::path_change::NotebookPathDeleted::new(
+        notebook_id.to_string(),
+        relative_path.to_string(),
+    )
+    .emit(app);
+}
+
 fn delete_note_path_internal(
     file_path: &Path,
     state: &AppState,
@@ -38,7 +44,6 @@ fn delete_note_path_internal(
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let (notebook_id, relative_path) = super::helpers::notebook_note_address(&memo_file, file_path)?
         .ok_or_else(|| "note path is outside a notebook or is not Markdown".to_string())?;
-    let before = memo_file.find_memo_by_relative_path_for_notebook_id(&notebook_id, &relative_path);
     let artifact_path = match crate::artifact::path_for_note(
         &notebook_id,
         &relative_path,
@@ -78,34 +83,12 @@ fn delete_note_path_internal(
         &relative_path,
     );
 
-    let Some(before) = before else {
-        return Ok(Some(outcome));
-    };
-
-    // The Markdown deletion is authoritative. Clean up optional ID-keyed
-    // history and projections afterward without making them a prerequisite.
-    let legacy_cleanup = read_lock(&state.memo_file, "memo_file")
-        .prune_deleted_memo_for_notebook_id(&notebook_id, &relative_path, &before.id)
-        .map_err(|error| error.to_string())?;
-    if !legacy_cleanup {
-        return Ok(None);
-    }
     if let Some(artifact_path) = artifact_path {
         if let Err(error) = crate::artifact::remove_path(&artifact_path) {
             tracing::warn!(path = %artifact_path.display(), "plugin artifact cleanup failed: {error}");
         }
     }
-    memo_events::emit(
-        app,
-        MemoEvent::Deleted {
-            id: before.id.clone(),
-            path: absolute_path.display().to_string(),
-            relative_path: relative_path.clone(),
-            notebook_id,
-            derived_changed: MemoDerivedChanged::from_deleted(&before),
-            source: MemoChangeSource::UserDelete,
-        },
-    );
+    emit_deleted_path(app, &notebook_id, &relative_path);
     Ok(Some(outcome))
 }
 
diff --git a/app/flowix-desktop/src/commands/memo/helpers.rs b/app/flowix-desktop/src/commands/memo/helpers.rs
index 8d10681a7..191378efc 100644
--- a/app/flowix-desktop/src/commands/memo/helpers.rs
+++ b/app/flowix-desktop/src/commands/memo/helpers.rs
@@ -4,12 +4,8 @@
 // `pub(super)` so the sibling sections (`reads`, `creates`, `versions`,
 // `deletes`) can call them directly without leaking them outside `memo`.
 
-use tauri::AppHandle;
-
-use crate::document_mutation::DocumentCommit;
 use crate::lock_utils::read_lock;
-use crate::memo_events::{self, MemoChangeSource, MemoDerivedChanged, MemoEvent};
-use flowix_core::memo_file::{extract_body_content, is_system_frontmatter_key, Memo};
+use flowix_core::memo_file::extract_body_content;
 
 use crate::app::state::AppState;
 pub(super) use crate::commands::helpers::notebook_note_address;
@@ -20,31 +16,6 @@ pub(super) fn current_notebook_id(state: &AppState) -> String {
         .unwrap_or_else(|| "nb_default".to_string())
 }
 
-pub(super) fn emit_updated_memo_event(
-    app: &AppHandle,
-    id: &str,
-    path: String,
-    memo: Memo,
-    notebook_id: String,
-    derived_changed: MemoDerivedChanged,
-    source: MemoChangeSource,
-    origin_window_label: Option<&str>,
-) -> Option<DocumentCommit> {
-    crate::document_derived::schedule(app, id);
-    memo_events::emit_with_commit_from_window(
-        app,
-        MemoEvent::Updated {
-            id: id.to_string(),
-            path,
-            notebook_id,
-            memo,
-            derived_changed,
-            source,
-        },
-        origin_window_label,
-    )
-}
-
 /// Lightweight CAS fallback normalization.
 ///
 /// The fast path stays byte-for-byte equality. This is only used after that
@@ -119,20 +90,7 @@ pub(super) fn cas_content_matches(current: &str, expected: &str, incoming: &str)
         return true;
     }
 
-    let metadata = |content: &str| {
-        flowix_core::memo_file::extract_document_metadata(content)
-            .ok()
-            .map(|mut metadata| {
-                if let Some(properties) = metadata.properties.as_object_mut() {
-                    for key in properties.keys().cloned().collect::<Vec<_>>() {
-                        if is_system_frontmatter_key(&key) {
-                            properties.remove(&key);
-                        }
-                    }
-                }
-                metadata
-            })
-    };
+    let metadata = |content: &str| flowix_core::memo_file::extract_document_metadata(content).ok();
     matches!((metadata(current), metadata(expected)), (Some(current), Some(expected)) if current == expected)
         && code_content_for_cas(current) == code_content_for_cas(expected)
         && normalize_markdown_for_cas(current) == normalize_markdown_for_cas(expected)
@@ -182,8 +140,8 @@ mod tests {
     #[test]
     fn cas_accepts_markdown_serialization_noise() {
         let current = "---\nflowix_key: abc123\nkey: legacy-current\n---\r\n\r\n# Title\r\n&nbsp;\r\nBody  \r\n";
-        let expected = "---\nflowix_key: oldkey\nkey: legacy-expected\n---\n\n# Title\n\nBody\n";
-        let incoming = "---\nflowix_key: abc123\n---\n\n# Title\n&nbsp;\nBody\n";
+        let expected = "---\nflowix_key: abc123\nkey: legacy-current\n---\n\n# Title\n\nBody\n";
+        let incoming = "---\nflowix_key: abc123\nkey: legacy-current\n---\n\n# Title\n&nbsp;\nBody\n";
 
         assert!(cas_content_matches(current, expected, incoming));
     }
diff --git a/app/flowix-desktop/src/commands/memo/mod.rs b/app/flowix-desktop/src/commands/memo/mod.rs
index c4f036bd5..fe85cde89 100644
--- a/app/flowix-desktop/src/commands/memo/mod.rs
+++ b/app/flowix-desktop/src/commands/memo/mod.rs
@@ -1,8 +1,7 @@
 //! Memo and document IPC commands.
 //!
-//! Note file CRUD addresses Markdown by notebook-relative path. Internal IDs
-//! remain temporarily in compatibility projections, version history, and cloud
-//! association while their callers migrate independently.
+//! Note file CRUD and identity use notebook-relative paths. The `memo` module
+//! name is retained for the existing IPC command namespace and UI terminology.
 //!
 //! File layout (split from the original 1414-line `commands/memo.rs` because
 //! the file carried five distinct sub-domains):
diff --git a/app/flowix-desktop/src/commands/memo/reads.rs b/app/flowix-desktop/src/commands/memo/reads.rs
index 4667ef8f1..296fc52ee 100644
--- a/app/flowix-desktop/src/commands/memo/reads.rs
+++ b/app/flowix-desktop/src/commands/memo/reads.rs
@@ -12,10 +12,9 @@ use flowix_core::memo_file::{
     NoteEntry,
 };
 use flowix_core::service::NoteSaveOutcome;
-use flowix_core::{FlowixError, MemoPage, MemoService, NoteService};
+use flowix_core::{FlowixError, NoteService};
 
 use crate::app::state::AppState;
-use crate::commands::helpers::start_security_bookmark_access;
 use crate::watcher::runtime::mark_self_write_for;
 
 use super::helpers::*;
@@ -57,7 +56,7 @@ pub fn note_path_status(file_path: String, state: State<AppState>) -> Result<Not
     }
 }
 
-/// Classify a Markdown file independently of its opening UI and legacy memo ID.
+/// Classify a Markdown file by notebook-relative path, independently of its opening UI.
 #[tauri::command]
 #[allow(non_snake_case)]
 pub async fn resolve_markdown_location(
@@ -102,8 +101,7 @@ pub async fn resolve_markdown_location(
         })
     }).await.map_err(|error| format!("Markdown location task failed: {error}"))?
 }
-/// List the notebook's rebuildable note projection by relative path. This is
-/// the ID-free list boundary for callers migrating off the legacy memo table.
+/// List the notebook's rebuildable note projection, keyed by relative path.
 #[tauri::command]
 pub async fn list_notes_by_path(
     notebook_id: String,
@@ -114,7 +112,7 @@ pub async fn list_notes_by_path(
         let memo_file = read_lock(&state.memo_file, "memo_file");
         NoteService::new(&memo_file)
             .list(&notebook_id)
-            .map_err(|error| error.to_string())
+            .map_err(|error| crate::app::notebook_background::query_error(state.inner(), &notebook_id, error))
     })
     .await
     .map_err(|error| format!("path-based note list task failed: {error}"))?
@@ -164,7 +162,7 @@ pub async fn get_path_notes(
                 cursor.as_deref(),
                 limit,
             )
-            .map_err(|error: FlowixError| error.to_string())?;
+            .map_err(|error: FlowixError| crate::app::notebook_background::query_error(state.inner(), &notebook_id, error))?;
         Ok(GetPathNotesResponse {
             notes: page.notes,
             next_cursor: page.next_cursor,
@@ -181,11 +179,12 @@ pub async fn get_used_memo_tag_ids(
 ) -> Result<UsedMemoTagIdsResponse, String> {
     tauri::async_runtime::spawn_blocking(move || {
         let state = app.state::<AppState>();
+        let memo_file = read_lock(&state.memo_file, "memo_file");
+        let id = notebook_id.or_else(|| memo_file.current_notebook_id_value()).unwrap_or_default();
         let (used_tag_ids, tag_counts, total_memo_count, agent_memo_count, todo_memo_count) =
-            MemoService::new(&read_lock(&state.memo_file, "memo_file"))
-                .tag_usage_summary(notebook_id.as_deref())
-                .unwrap_or_default();
-        UsedMemoTagIdsResponse {
+            memo_file.read_tag_usage_summary_for_notebook_id(Some(&id))
+                .map_err(|error| crate::app::notebook_background::query_error(state.inner(), &id, error))?;
+        Ok(UsedMemoTagIdsResponse {
             used_tag_ids,
             tag_counts: tag_counts
                 .into_iter()
@@ -194,10 +193,10 @@ pub async fn get_used_memo_tag_ids(
             total_memo_count,
             agent_memo_count,
             todo_memo_count,
-        }
+        })
     })
     .await
-    .map_err(|error| format!("tag summary task failed: {error}"))
+    .map_err(|error| format!("tag summary task failed: {error}"))?
 }
 
 #[tauri::command]
@@ -217,7 +216,6 @@ pub async fn read_document(
             return None;
         }
         let requested_path = Path::new(&file_path);
-        start_security_bookmark_access(&state, requested_path);
         let memo_file = read_lock(&state.memo_file, "memo_file");
         match notebook_note_address(&memo_file, requested_path) {
             Ok(Some((notebook_id, relative_path))) => {
@@ -257,7 +255,6 @@ pub async fn get_document_modified_at(
         if !crate::commands::helpers::can_access_document_path(path, window.label(), &state) {
             return None;
         }
-        start_security_bookmark_access(&state, path);
         fs::metadata(path).ok()?.modified().ok()?
             .duration_since(std::time::UNIX_EPOCH).ok()
             .map(|duration| duration.as_millis() as u64)
@@ -317,7 +314,6 @@ fn write_document_internal(
     if !Path::new(file_path).is_absolute() {
         return Err("absolute document path required".into());
     }
-    start_security_bookmark_access(state.inner(), Path::new(file_path));
     let requested_path = Path::new(file_path);
     let (notebook_id, relative_path) =
         notebook_note_address(&read_lock(&state.memo_file, "memo_file"), requested_path)?
diff --git a/app/flowix-desktop/src/commands/memo/versions.rs b/app/flowix-desktop/src/commands/memo/versions.rs
index fece75a8a..dc6db2a9f 100644
--- a/app/flowix-desktop/src/commands/memo/versions.rs
+++ b/app/flowix-desktop/src/commands/memo/versions.rs
@@ -10,7 +10,6 @@ use crate::lock_utils::read_lock;
 use flowix_core::memo_file::{atomic_write_bytes, FileLockIntent, IsMd, MemoVersionSource, PathVersionMeta};
 
 use crate::app::state::AppState;
-use crate::commands::helpers::start_security_bookmark_access;
 use crate::watcher::runtime::mark_self_write_for;
 
 
@@ -35,7 +34,6 @@ pub fn list_path_versions(notebook_id: String, relative_path: String, state: Sta
 #[tauri::command]
 pub fn create_path_version(notebook_id: String, relative_path: String, source: Option<MemoVersionSource>, state: State<AppState>) -> Option<PathVersionMeta> {
     let path = path_archive_document(&state, &notebook_id, &relative_path)?;
-    start_security_bookmark_access(&state, &path);
     let memo_file = read_lock(&state.memo_file, "memo_file");
     memo_file.with_file_write(&notebook_id, &path, FileLockIntent::Existing,
         "create_path_version", |locked_path| {
@@ -49,7 +47,6 @@ pub fn create_path_version(notebook_id: String, relative_path: String, source: O
 pub fn restore_path_version(notebook_id: String, relative_path: String, version_id: String,
     expected_content: Option<String>, state: State<AppState>, app: AppHandle) -> Option<String> {
     let path = path_archive_document(&state, &notebook_id, &relative_path)?;
-    start_security_bookmark_access(&state, &path);
     let memo_file = read_lock(&state.memo_file, "memo_file");
     let target = memo_file.read_path_version(&notebook_id, &relative_path, &version_id)?;
     let restored = memo_file.with_file_write(&notebook_id, &path, FileLockIntent::Existing,
diff --git a/app/flowix-desktop/src/commands/mod.rs b/app/flowix-desktop/src/commands/mod.rs
index 063709cfd..e382a2f80 100644
--- a/app/flowix-desktop/src/commands/mod.rs
+++ b/app/flowix-desktop/src/commands/mod.rs
@@ -28,11 +28,12 @@
 
 // 子模块一�?`pub` —`tauri::generate_handler![commands::<sub>::xxx]` �?// `lib.rs::run()` 里走完整�?��, 需�?`pub` �??性。`#[tauri::command]` �?// 生成�?`__cmd__xxx` 兄弟宏也要求子模块是 `pub`, 否则宏解析不到�?
 pub mod agent;
-pub mod agent_access;
+pub mod agent_workspace;
 pub mod artifact;
 pub mod boot;
 pub mod cli;
 pub mod cloud;
+pub mod path_change;
 pub mod dialog;
 pub mod dsh;
 pub mod export;
@@ -48,10 +49,12 @@ pub mod kv;
 pub mod media;
 pub mod memo;
 pub mod notebook;
+pub mod notebook_setup;
 pub mod plugin;
 pub mod product;
 pub mod recovery;
-pub mod document_shutdown;
+pub mod window_shutdown;
+pub mod window_input;
 pub mod document_operations;
 pub mod settings;
 pub mod tag;
diff --git a/app/flowix-desktop/src/commands/notebook.rs b/app/flowix-desktop/src/commands/notebook.rs
index ca2b22710..36f9a8c55 100644
--- a/app/flowix-desktop/src/commands/notebook.rs
+++ b/app/flowix-desktop/src/commands/notebook.rs
@@ -1,35 +1,29 @@
-//! Notebook IPC —增删改查 + 切换当前 notebook�?//!
-//! `set_current_notebook` �?`switch_notebook_and_rebuild` helper, 触发
-//! watcher rebind + 磁盘对账 + 后台索引 rebuild�?//!
-//! �?/ �?/ �?/ 清空 四个写操作都会同步更�?`agent_access` store
-//! (`~/.flowix/agent-access.json`), 任何 entry 真改了之�?emit
-//! `agent-access-changed` 事件, 其它窗口 React 树收到后从�?盘重�?load�?
+//! Notebook lifecycle and device-local registration in db/local.db.
 use crate::events as dispatcher;
 use serde::Serialize;
 use std::path::{Path, PathBuf};
-use tauri::{AppHandle, Manager, State};
+use tauri::{AppHandle, Emitter, Manager, State};
 
 use crate::lock_utils::{read_lock, write_lock};
 use flowix_core::memo_file::{
     MemoFile, Notebook, NotebookConfig, NotebookSetupJob, NotebookSetupJobStatus,
+    NotebookSetupStage,
 };
-use flowix_core::MemoService;
 use flowix_sync::V2LocalNotebook;
 
-use super::agent_access::AGENT_ACCESS_CHANGED_EVENT;
+use super::agent_workspace::AGENT_WORKSPACE_CHANGED_EVENT;
 use super::helpers::{
     refresh_watcher_roots, switch_notebook_trusting_index, watch_created_notebook,
 };
 use crate::app::state::{AppState, NotebookImportStatus, NotebookImportStatusKind};
 
 const NOTEBOOK_IMPORT_COMPLETE_EVENT: &str = "notebook-import-complete";
-const NOTEBOOK_SETUP_STATUS_EVENT: &str = "notebook-setup-status";
 /// 笔�?�?��表发生变�?(reorder / create / update / delete) �?emit, 其它窗口
 /// store 监听�?reload。前�?TS 类型 `notebooks-changed` 事件 payload �?unit�?
 pub(crate) const NOTEBOOKS_CHANGED_EVENT: &str = "notebooks-changed";
 const NOTEBOOK_IMPORT_STATUS_EVENT: &str = "notebook-import-status";
 
-fn emit_notebook_import_status(
+pub(crate) fn emit_notebook_import_status(
     state: &AppState,
     app: &AppHandle,
     notebook_id: &str,
@@ -122,8 +116,12 @@ fn notebook_from_config(config: NotebookConfig) -> Notebook {
 #[serde(rename_all = "camelCase")]
 pub struct NotebookListItem {
     #[serde(flatten)]
-    notebook: Notebook,
-    memo_count: usize,
+    notebook: NotebookConfig,
+    pinned: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    memo_count: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    missing: Option<bool>,
 }
 
 fn create_notebook_registry(
@@ -256,7 +254,9 @@ fn create_notebook_registry_with_id_and_template(
 
     // 创建顺序: 1) 先�?现有 configs 验证�?��不冲�? 2) �?next sort;
     // 3) 组�? NotebookConfig 写盘。sort �?MAX(sort)+10 让新行落到末�?    // (ORDER BY sort ASC), 不取 len �?���?reorder �?sort �?��疏的�?
-    let mut configs = memo_file.read_notebook_configs().unwrap_or_default();
+    let mut configs = memo_file
+        .read_notebook_configs()
+        .map_err(|error| format!("INDEX_READ_FAILED: {error}"))?;
     if configs
         .iter()
         .any(|notebook| comparable_notebook_path(&notebook.path) == comparable_path)
@@ -287,15 +287,17 @@ fn create_notebook_registry_with_id_and_template(
             let relocated = existing.clone();
             let setup_job = template_id.map(|template_id| NotebookSetupJob {
                 notebook_id: relocated.id.clone(),
+                job_id: uuid::Uuid::now_v7().to_string(),
                 template_id: Some(template_id.to_string()),
                 overwrite_existing,
                 status: NotebookSetupJobStatus::Pending,
-                stage: "template".to_string(),
-                completed_files: 0,
-                total_files: 0,
+                stage: NotebookSetupStage::Preparing,
+                revision: 0,
+                run_id: String::new(),
                 message: None,
                 report: None,
                 updated_at: now,
+                execution_requested: false,
             });
             memo_file
                 .write_notebook_configs_with_setup_job(&configs, setup_job.as_ref())
@@ -327,15 +329,17 @@ fn create_notebook_registry_with_id_and_template(
     configs.push(config.clone());
     let setup_job = template_id.map(|template_id| NotebookSetupJob {
         notebook_id: config.id.clone(),
+        job_id: uuid::Uuid::now_v7().to_string(),
         template_id: Some(template_id.to_string()),
         overwrite_existing,
         status: NotebookSetupJobStatus::Pending,
-        stage: "template".to_string(),
-        completed_files: 0,
-        total_files: 0,
+        stage: NotebookSetupStage::Preparing,
+        revision: 0,
+        run_id: String::new(),
         message: None,
         report: None,
         updated_at: now,
+        execution_requested: false,
     });
     memo_file
         .write_notebook_configs_with_setup_job(&configs, setup_job.as_ref())
@@ -358,11 +362,8 @@ fn cloud_restore_directory_is_empty(path: &Path) -> Result<bool, String> {
     Ok(true)
 }
 
-fn sync_notebook_agent_access(config: &NotebookConfig, state: &AppState, app: &AppHandle) {
-    // 同�?往 agent_access 列表里加一�?(默�? enabled), 写盘后才�?    // 同�?完成 ── store 内部走原子写, 失败会回滚内存�?
-    if state.agent_access.add_or_update_notebook(config) {
-        dispatcher::emit_to(app, AGENT_ACCESS_CHANGED_EVENT, ());
-    }
+fn notify_notebook_workspace_changed(app: &AppHandle) {
+    dispatcher::emit_to(app, AGENT_WORKSPACE_CHANGED_EVENT, ());
 }
 
 fn set_current_notebook_inner(
@@ -382,8 +383,8 @@ fn set_current_notebook_inner(
 
     // Fast path for ordinary switching: trust memo index and avoid synchronous
     // disk reconciliation. Search index rebuild is lazy, triggered by search.
-    if let Err(error) = switch_notebook_trusting_index(state, app, notebook_id.clone()) {
-        if let Err(restore_error) = switch_notebook_trusting_index(state, app, previous_id) {
+    if let Err(error) = switch_notebook_trusting_index(state, notebook_id.clone()) {
+        if let Err(restore_error) = switch_notebook_trusting_index(state, previous_id) {
             tracing::error!(
                 "[set_current_notebook] failed to restore previous notebook after switch error: {restore_error}"
             );
@@ -397,7 +398,7 @@ fn set_current_notebook_inner(
     {
         // Keep the process-local and persisted selection aligned if the second
         // half of the switch fails. The original error remains authoritative.
-        if let Err(restore_error) = switch_notebook_trusting_index(state, app, previous_id) {
+        if let Err(restore_error) = switch_notebook_trusting_index(state, previous_id) {
             tracing::error!(
                 "[set_current_notebook] failed to restore previous notebook after persistence error: {restore_error}"
             );
@@ -406,6 +407,7 @@ fn set_current_notebook_inner(
     }
 
     if let Some(notebook_id) = notebook_id.as_deref() {
+        state.notebook_background.prioritize(notebook_id);
         crate::commands::helpers::retry_notebook_watch(state, app, notebook_id);
     }
     Ok(())
@@ -424,7 +426,7 @@ fn activate_created_notebook(
     Ok(())
 }
 
-fn run_notebook_import(app: AppHandle, notebook_id: String, seed_onboarding_docs: bool) -> bool {
+pub(crate) fn run_notebook_import(app: AppHandle, notebook_id: String, seed_onboarding_docs: bool) -> bool {
     let started = std::time::Instant::now();
     tracing::info!(
         "[create_notebook] background import start id={}",
@@ -437,9 +439,15 @@ fn run_notebook_import(app: AppHandle, notebook_id: String, seed_onboarding_docs
         let mut onboarding_docs_seeded = false;
         {
             let memo_file = read_lock(&app_state.memo_file, "memo_file");
-            memo_file
-                .ensure_notebook_migrations(&notebook_id)
-                .map_err(|error| format!("notebook import migration failed: {error}"))?;
+            match memo_file.has_legacy_notebook_internal_data(&notebook_id) {
+                Ok(true) => {
+                    if let Err(error) = memo_file.ensure_notebook_structure_migration(&notebook_id) {
+                        tracing::warn!(notebook = %notebook_id, %error, "legacy plugin artifact migration deferred");
+                    }
+                }
+                Ok(false) => {}
+                Err(error) => tracing::warn!(notebook = %notebook_id, %error, "legacy plugin artifact check deferred"),
+            }
             tracing::info!(
                 "[create_notebook] import/reconcile start id={}",
                 notebook_id
@@ -516,201 +524,75 @@ fn spawn_notebook_import(app: AppHandle, notebook_id: String) {
     std::thread::spawn(move || run_notebook_import(app, notebook_id, true));
 }
 
-fn persist_notebook_setup_job(
-    state: &AppState,
-    app: &AppHandle,
-    job: NotebookSetupJob,
-) -> Result<NotebookSetupJob, String> {
-    read_lock(&state.memo_file, "memo_file")
-        .write_notebook_setup_job(&job)
-        .map_err(|error| format!("persist notebook setup status failed: {error}"))?;
-    dispatcher::emit_to(app, NOTEBOOK_SETUP_STATUS_EVENT, job.clone());
-    Ok(job)
-}
-
-fn finish_notebook_template_setup(app: AppHandle, mut job: NotebookSetupJob) {
-    let state = app.state::<AppState>();
-    let mut report = job.report.clone().unwrap_or_default();
-    let result = (|| {
-        if job.stage != "indexing" {
-            let notebook_id = job.notebook_id.clone();
-            let template_id = job
-                .template_id
-                .clone()
-                .ok_or_else(|| "NOTEBOOK_TEMPLATE_NOT_SELECTED".to_string())?;
-            let mut next_stage_job = job.clone();
-            super::memo::creates::initialize_notebook_template_for_notebook(
-                &notebook_id,
-                &template_id,
-                true,
-                job.overwrite_existing,
-                state.inner(),
-                &app,
-                |report| {
-                    next_stage_job.stage = "indexing".to_string();
-                    next_stage_job.completed_files = report.total_files;
-                    next_stage_job.total_files = report.total_files;
-                    next_stage_job.message = None;
-                    next_stage_job.report = Some(report.clone());
-                    next_stage_job.updated_at = chrono::Utc::now().timestamp_millis();
-                    persist_notebook_setup_job(state.inner(), &app, next_stage_job.clone())
-                        .map(|_| ())
-                },
-            )?;
-            report = next_stage_job.report.clone().unwrap_or_default();
-            job = next_stage_job;
-        }
-
-        emit_notebook_import_status(
-            state.inner(),
-            &app,
-            &job.notebook_id,
-            NotebookImportStatusKind::Started,
-            None,
-        );
-        if !run_notebook_import(app.clone(), job.notebook_id.clone(), false) {
-            let message = state
-                .notebook_imports
-                .lock()
-                .ok()
-                .and_then(|imports| imports.get(&job.notebook_id).and_then(|status| status.message.clone()))
-                .unwrap_or_else(|| "NOTEBOOK_IMPORT_FAILED".to_string());
-            return Err(message);
-        }
-        Ok(())
-    })();
-
-    job.updated_at = chrono::Utc::now().timestamp_millis();
-    match result {
-        Ok(()) => {
-            job.report = Some(report.clone());
-            if report.failed_files > 0 {
-                job.status = NotebookSetupJobStatus::Partial;
-                job.stage = "template".to_string();
-            } else {
-                job.status = NotebookSetupJobStatus::Completed;
-                job.stage = "completed".to_string();
-            }
-            job.message = None;
-        }
-        Err(message) => {
-            job.status = NotebookSetupJobStatus::Failed;
-            if report.failed_files > 0 || job.stage != "indexing" {
-                job.stage = "template".to_string();
+#[tauri::command]
+pub async fn get_notebooks(app: AppHandle) -> Result<Vec<NotebookListItem>, String> {
+    tauri::async_runtime::spawn_blocking(move || {
+        let state = app.state::<AppState>();
+        let memo_file = read_lock(&state.memo_file, "memo_file");
+        let configs = memo_file.read_notebook_configs().map_err(|error| error.to_string())?;
+        let pinned_ids = memo_file.read_notebook_pin_states().map_err(|error| error.to_string())?;
+        // Metadata-only read: no path probes, count queries or filesystem scans.
+        Ok::<_, String>(configs.into_iter().map(|config| {
+            let cached = state.notebook_background.snapshot(&config.id);
+            NotebookListItem {
+                pinned: pinned_ids.contains(&config.id),
+                memo_count: cached.as_ref().and_then(|status| status.memo_count),
+                missing: cached.as_ref().and_then(|status| status.missing),
+                notebook: config,
             }
-            job.report = Some(report);
-            job.message = Some(message);
-        }
-    }
-    if let Err(error) = persist_notebook_setup_job(state.inner(), &app, job.clone()) {
-        tracing::error!("failed to persist notebook setup terminal state: {error}");
-    }
-    if let Ok(mut running) = state.notebook_template_initializations.lock() {
-        running.remove(&job.notebook_id);
-    };
+        }).collect::<Vec<_>>())
+    })
+    .await
+    .map_err(|error| format!("notebook list task failed: {error}"))?
 }
 
 #[tauri::command]
-pub fn get_notebook_template_setup_status(
+pub fn set_notebook_pinned(
     notebook_id: String,
+    pinned: bool,
     state: State<AppState>,
-) -> Result<Option<NotebookSetupJob>, String> {
-    read_lock(&state.memo_file, "memo_file")
-        .get_notebook_setup_job(&notebook_id)
-        .map_err(|error| format!("read notebook setup status failed: {error}"))
-}
-
-/// Start or resume template preparation for an opened notebook. Failed and
-/// partial jobs only restart when the user explicitly requests a retry.
-#[tauri::command]
-pub fn start_notebook_template_setup(
-    notebook_id: String,
-    retry: Option<bool>,
     app: AppHandle,
-) -> Result<Option<NotebookSetupJob>, String> {
-    let state = app.state::<AppState>();
-    let mut running = state
-        .notebook_template_initializations
-        .lock()
-        .unwrap_or_else(|poisoned| poisoned.into_inner());
-    let memo_file = read_lock(&state.memo_file, "memo_file");
-    let Some(mut job) = memo_file
-        .get_notebook_setup_job(&notebook_id)
-        .map_err(|error| format!("read notebook setup status failed: {error}"))?
-    else {
-        return Ok(None);
-    };
+) -> Result<bool, String> {
+    let memo_file = write_lock(&state.memo_file, "memo_file");
+    let changed = memo_file
+        .set_notebook_pinned(&notebook_id, pinned)
+        .map_err(|error| format!("INDEX_WRITE_FAILED: {error}"))?;
     drop(memo_file);
-
-    if job.status == NotebookSetupJobStatus::Completed {
-        return Ok(Some(job));
-    }
-    if matches!(job.status, NotebookSetupJobStatus::Partial | NotebookSetupJobStatus::Failed)
-        && retry != Some(true)
-    {
-        return Ok(Some(job));
-    }
-    if job.status == NotebookSetupJobStatus::Partial && retry == Some(true) {
-        job.status = NotebookSetupJobStatus::Pending;
-        job.stage = "template".to_string();
-        job.message = None;
-        job.report = None;
-    } else if job.status == NotebookSetupJobStatus::Failed && retry == Some(true) {
-        job.status = NotebookSetupJobStatus::Pending;
-        job.message = None;
-        if job.stage != "indexing" {
-            job.stage = "template".to_string();
-            job.report = None;
-        }
+    if changed {
+        dispatcher::emit_to(&app, NOTEBOOKS_CHANGED_EVENT, ());
     }
+    Ok(changed)
+}
 
-    if !running.insert(notebook_id.clone()) {
-        return Ok(Some(job));
-    }
+#[tauri::command]
+pub fn get_notebook_background_status(state: State<AppState>) -> Vec<crate::app::notebook_background::NotebookBackgroundStatus> {
+    state.notebook_background.statuses()
+}
 
-    job.status = NotebookSetupJobStatus::Running;
-    job.message = None;
-    job.updated_at = chrono::Utc::now().timestamp_millis();
-    let job = match persist_notebook_setup_job(state.inner(), &app, job) {
-        Ok(job) => job,
-        Err(error) => {
-            running.remove(&notebook_id);
-            return Err(error);
-        }
-    };
-    drop(running);
+#[tauri::command]
+pub fn get_notebook_media_maintenance_status(
+    state: State<AppState>,
+) -> Vec<crate::app::notebook_background::NotebookMediaMaintenanceStatus> {
+    state.notebook_background.media_statuses()
+}
 
-    std::thread::spawn({
-        let app = app.clone();
-        let job = job.clone();
-        move || finish_notebook_template_setup(app, job)
-    });
-    Ok(Some(job))
+#[tauri::command]
+pub fn request_notebook_media_maintenance(
+    notebook_id: String,
+    app: AppHandle,
+    state: State<AppState>,
+) -> Result<(), String> {
+    let status = state
+        .notebook_background
+        .request_media(&notebook_id)
+        .ok_or_else(|| "媒体维护队列已停止".to_string())?;
+    let _ = app.emit(crate::app::notebook_background::MEDIA_EVENT, status);
+    Ok(())
 }
 
 #[tauri::command]
-pub async fn get_notebooks(app: AppHandle) -> Result<Vec<NotebookListItem>, String> {
-    tauri::async_runtime::spawn_blocking(move || {
-        let state = app.state::<AppState>();
-        let memo_file = read_lock(&state.memo_file, "memo_file");
-        let configs = memo_file.read_notebook_configs().unwrap_or_default();
-        let counts = MemoService::new(&memo_file)
-            .notebook_note_counts(&configs)
-            .unwrap_or_default();
-
-        configs
-            .into_iter()
-            .map(|config| {
-                let memo_count = counts.get(&config.id).copied().unwrap_or(0);
-                NotebookListItem {
-                    notebook: notebook_from_config(config),
-                    memo_count,
-                }
-            })
-            .collect::<Vec<_>>()
-    })
-    .await
-    .map_err(|error| format!("notebook list task failed: {error}"))
+pub fn request_notebook_refresh(notebook_id: String, state: State<AppState>) {
+    state.notebook_background.request(&notebook_id, true, true);
 }
 
 #[tauri::command]
@@ -747,9 +629,6 @@ pub async fn create_notebook(
                     .ok_or_else(|| "PATH_INVALID_UTF8".to_string())?
             }
         };
-        let has_bookmark_access = state
-            .security_bookmarks
-            .start_accessing_for_path(Path::new(trimmed_path));
         if !Path::new(trimmed_path).is_dir() {
             return Err("PATH_MISSING".to_string());
         }
@@ -772,13 +651,8 @@ pub async fn create_notebook(
         {
             return Err("NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED".to_string());
         }
-        if !has_bookmark_access {
-            state
-                .security_bookmarks
-                .record_directory(Path::new(trimmed_path))
-                .map_err(|e| format!("BOOKMARK_WRITE_FAILED: {e}"))?;
-        }
-
+        // Also handles dependency deletion while the window stayed open.
+        state.user_config.ensure_runtime_storage()?;
         let config = {
             let memo_file = write_lock(&state.memo_file, "memo_file");
             create_notebook_registry_with_id_and_template(
@@ -791,7 +665,7 @@ pub async fn create_notebook(
                 &memo_file,
             )?
         };
-        sync_notebook_agent_access(&config, state.inner(), &app);
+        notify_notebook_workspace_changed(&app);
         if activate.unwrap_or(true) {
             activate_created_notebook(&config, state.inner(), &app)?;
         } else {
@@ -805,6 +679,9 @@ pub async fn create_notebook(
     })
     .await
     .map_err(|error| format!("notebook creation task failed: {error}"))?;
+    if let Err(error) = &result {
+        crate::runtime_log::record_event("error", "notebook.create.failed", error);
+    }
     crate::runtime_log::record_event(
         "info",
         "notebook.create.timing",
@@ -879,6 +756,7 @@ pub fn create_notebook_from_cloud(
     name: String,
     path: String,
     icon: Option<String>,
+    activate: Option<bool>,
     state: State<AppState>,
     app: AppHandle,
 ) -> Result<Notebook, String> {
@@ -895,26 +773,22 @@ pub fn create_notebook_from_cloud(
     }
 
     let directory = Path::new(trimmed_path);
-    let has_bookmark_access = state.security_bookmarks.start_accessing_for_path(directory);
     if !directory.is_dir() {
         return Err("PATH_MISSING".to_string());
     }
     if !cloud_restore_directory_is_empty(directory)? {
         return Err("PATH_NOT_EMPTY".to_string());
     }
-    if !has_bookmark_access {
-        state
-            .security_bookmarks
-            .record_directory(directory)
-            .map_err(|e| format!("BOOKMARK_WRITE_FAILED: {e}"))?;
-    }
-
     let config = {
         let memo_file = write_lock(&state.memo_file, "memo_file");
         create_notebook_registry_with_id(trimmed_name, trimmed_path, icon, Some(&id), &memo_file)?
     };
-    sync_notebook_agent_access(&config, state.inner(), &app);
-    activate_created_notebook(&config, state.inner(), &app)?;
+    notify_notebook_workspace_changed(&app);
+    if activate.unwrap_or(true) {
+        activate_created_notebook(&config, state.inner(), &app)?;
+    } else {
+        watch_created_notebook(state.inner(), &app, &config);
+    }
     dispatcher::emit_to(&app, NOTEBOOKS_CHANGED_EVENT, ());
 
     Ok(notebook_from_config(config))
@@ -946,10 +820,7 @@ pub fn update_notebook(
     let updated = configs[index].clone();
     drop(memo_file);
 
-    // 名字 / �?��变更都同步到 agent_access ── store �?��判定�?��真改�?
-    if state.agent_access.add_or_update_notebook(&updated) {
-        dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
-    }
+    notify_notebook_workspace_changed(&app);
     refresh_watcher_roots(state.inner(), &app);
     record_notebook_metadata_change(state.inner(), &app, &updated);
 
@@ -1064,10 +935,7 @@ pub fn delete_notebook(
         crate::commands::cloud::schedule_notebook_sync(app.clone(), id.clone());
     }
 
-    // 同�?把�?应的 agent_access entry 也删�? 状态栏�?文件权限"子菜�?    // 会少一�?── 用户没主动去勾�? 不应该留�??儿在那里�?
-    if state.agent_access.remove_notebook(&id) {
-        dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
-    }
+    notify_notebook_workspace_changed(&app);
     refresh_watcher_roots(state.inner(), &app);
     dispatcher::emit_to(&app, NOTEBOOKS_CHANGED_EVENT, ());
     Ok(true)
@@ -1170,20 +1038,14 @@ pub fn clear_notebooks(state: State<AppState>, app: AppHandle) -> Result<bool, S
     drop(setup_guard);
 
     // 把�?清掉的非默�? notebook �?access 列表里也清掉, 然后 emit 一欰�?
-    let mut any_removed = false;
     for id in before_ids {
         if let Err(error) = state.cloud_sync.record_v2_notebook_delete(&id) {
             tracing::warn!("failed to persist cleared cloud notebook {id}: {error}");
         } else {
             crate::commands::cloud::schedule_notebook_sync(app.clone(), id.clone());
         }
-        if state.agent_access.remove_notebook(&id) {
-            any_removed = true;
-        }
-    }
-    if any_removed {
-        dispatcher::emit_to(&app, AGENT_ACCESS_CHANGED_EVENT, ());
     }
+    notify_notebook_workspace_changed(&app);
     refresh_watcher_roots(state.inner(), &app);
     Ok(ok)
 }
@@ -1228,6 +1090,17 @@ mod tests {
         MemoFile::new(config_dir)
     }
 
+    #[test]
+    fn notebook_list_distinguishes_unknown_statistics_from_a_known_empty_index() {
+        let config = NotebookConfig { id: "offline".into(), name: "Offline".into(), icon: None,
+            path: "/unavailable/notebook".into(), is_default: false, sort: 0, created_at: 0, updated_at: 0 };
+        let unknown = serde_json::to_value(NotebookListItem { notebook: config.clone(), pinned: false, memo_count: None, missing: None }).unwrap();
+        assert!(unknown.get("memoCount").is_none());
+        assert!(unknown.get("missing").is_none());
+        let empty = serde_json::to_value(NotebookListItem { notebook: config, pinned: false, memo_count: Some(0), missing: Some(false) }).unwrap();
+        assert_eq!(empty["memoCount"], 0);
+    }
+
     #[test]
     fn preset_content_check_ignores_metadata_but_detects_existing_folders() {
         let root = temp_root();
@@ -1318,6 +1191,32 @@ mod tests {
         assert_eq!(configs[0].path, config.path);
     }
 
+    #[test]
+    fn missing_runtime_dependencies_allow_notebook_creation() {
+        let temp = tempfile::tempdir().unwrap();
+        let config_dir = temp.path().join("config");
+        let memo = MemoFile::new(config_dir.clone());
+        memo.initialize_registry_storage().unwrap();
+        memo.mark_local_migration_completed("config_local_migrations_v1")
+            .unwrap();
+        fs::create_dir_all(config_dir.join("boot")).unwrap();
+        fs::write(
+            config_dir.join("boot/boot.json"),
+            "{\"versionInitialization\":{\"completed\":true}}",
+        )
+        .unwrap();
+        fs::remove_dir_all(config_dir.join("db")).unwrap();
+        // Keep the same in-memory MemoFile, as with an already open Dev window.
+        assert!(memo.read_notebook_configs().unwrap().is_empty());
+        assert!(memo.read_selected_notebook_id().unwrap().is_none());
+        assert!(memo.read_notebook_workspace().unwrap().notebooks.is_empty());
+        let path = temp.path().join("new-notebook");
+        fs::create_dir_all(&path).unwrap();
+        let created = create_notebook_registry("New", path.to_str().unwrap(), None, &memo).unwrap();
+        assert_eq!(memo.read_notebook_configs().unwrap()[0].id, created.id);
+        assert!(config_dir.join("boot/boot.json").exists());
+    }
+
     #[test]
     fn new_notebook_ids_use_uuid_v7() {
         let id = generate_notebook_id();
diff --git a/app/flowix-desktop/src/commands/notebook_setup.rs b/app/flowix-desktop/src/commands/notebook_setup.rs
new file mode 100644
index 000000000..827dbf74b
--- /dev/null
+++ b/app/flowix-desktop/src/commands/notebook_setup.rs
@@ -0,0 +1,545 @@
+//! Durable lifecycle and worker coordination for notebook template setup.
+
+use crate::app::state::{AppState, NotebookImportStatusKind};
+use crate::events as dispatcher;
+use crate::lock_utils::read_lock;
+use flowix_core::memo_file::{
+    MemoFile, NotebookSetupJob, NotebookSetupJobStatus, NotebookSetupSnapshot, NotebookSetupStage,
+};
+use std::path::PathBuf;
+use tauri::{AppHandle, Manager, State};
+
+use super::notebook::{emit_notebook_import_status, run_notebook_import};
+
+const NOTEBOOK_SETUP_STATUS_EVENT: &str = "notebook-setup-status";
+
+pub(crate) fn persist_notebook_setup_job(
+    state: &AppState,
+    app: &AppHandle,
+    job: NotebookSetupJob,
+) -> Result<NotebookSetupJob, String> {
+    let persisted = read_lock(&state.memo_file, "memo_file")
+        .write_notebook_setup_job(&job)
+        .map_err(|error| format!("persist notebook setup status failed: {error}"))?;
+    emit_notebook_setup_job(app, persisted.clone());
+    Ok(persisted)
+}
+
+pub(crate) fn emit_notebook_setup_job(app: &AppHandle, job: NotebookSetupJob) {
+    dispatcher::emit_to(app, NOTEBOOK_SETUP_STATUS_EVENT, job);
+}
+
+fn persist_notebook_setup_run_start(
+    state: &AppState,
+    app: &AppHandle,
+    job: &NotebookSetupJob,
+    expected_run_id: &str,
+) -> Result<NotebookSetupJob, String> {
+    let persisted = read_lock(&state.memo_file, "memo_file")
+        .start_notebook_setup_job(job, expected_run_id)
+        .map_err(|error| format!("persist notebook setup run start failed: {error}"))?;
+    emit_notebook_setup_job(app, persisted.clone());
+    Ok(persisted)
+}
+
+fn release_notebook_template_setup(state: &AppState, notebook_id: &str) {
+    state
+        .notebook_template_initializations
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .remove(notebook_id);
+}
+
+fn read_current_notebook_setup_run(
+    state: &AppState,
+    notebook_id: &str,
+    job_id: &str,
+    run_id: &str,
+) -> Option<NotebookSetupJob> {
+    let mut delay = std::time::Duration::from_millis(250);
+    loop {
+        match read_lock(&state.memo_file, "memo_file").get_notebook_setup_job(notebook_id) {
+            Ok(Some(job)) if job.job_id == job_id && job.run_id == run_id => return Some(job),
+            Ok(_) => return None,
+            Err(error) => {
+                tracing::error!(
+                    notebook_id = %notebook_id,
+                    error = %error,
+                    "retrying notebook setup checkpoint read"
+                );
+                std::thread::sleep(delay);
+                delay = (delay * 2).min(std::time::Duration::from_secs(30));
+            }
+        }
+    }
+}
+
+fn persist_notebook_setup_terminal_until_committed(
+    state: &AppState,
+    app: &AppHandle,
+    job: NotebookSetupJob,
+) {
+    let mut delay = std::time::Duration::from_millis(250);
+    loop {
+        match persist_notebook_setup_job(state, app, job.clone()) {
+            Ok(_) => return,
+            Err(error) => {
+                if error.contains("NOTEBOOK_SETUP_JOB_SUPERSEDED")
+                    || error.contains("NOTEBOOK_SETUP_RUN_SUPERSEDED")
+                    || error.contains("NOTEBOOK_SETUP_JOB_MISSING")
+                {
+                    tracing::warn!(
+                        notebook_id = %job.notebook_id,
+                        job_id = %job.job_id,
+                        "discarding terminal result for a superseded notebook setup job"
+                    );
+                    return;
+                }
+
+                let current = read_lock(&state.memo_file, "memo_file")
+                    .get_notebook_setup_job(&job.notebook_id);
+                match current {
+                    Ok(Some(current))
+                        if current.job_id != job.job_id || current.run_id != job.run_id =>
+                    {
+                        tracing::warn!(
+                            notebook_id = %job.notebook_id,
+                            job_id = %job.job_id,
+                            "discarding terminal result after setup identity changed"
+                        );
+                        return;
+                    }
+                    Ok(None) => return,
+                    _ => {}
+                }
+
+                tracing::error!(
+                    notebook_id = %job.notebook_id,
+                    error = %error,
+                    "retrying notebook setup terminal-state persistence"
+                );
+                std::thread::sleep(delay);
+                delay = (delay * 2).min(std::time::Duration::from_secs(30));
+            }
+        }
+    }
+}
+
+fn fail_notebook_template_setup_after_panic(app: AppHandle, mut job: NotebookSetupJob) {
+    let state = app.state::<AppState>();
+    let Some(latest) = read_current_notebook_setup_run(
+        state.inner(),
+        &job.notebook_id,
+        &job.job_id,
+        &job.run_id,
+    ) else {
+        release_notebook_template_setup(state.inner(), &job.notebook_id);
+        return;
+    };
+    if matches!(
+        latest.status,
+        NotebookSetupJobStatus::Completed
+            | NotebookSetupJobStatus::Partial
+            | NotebookSetupJobStatus::Failed
+    ) {
+        release_notebook_template_setup(state.inner(), &job.notebook_id);
+        return;
+    }
+
+    job.stage = latest.stage;
+    job.report = latest.report;
+    job.status = NotebookSetupJobStatus::Failed;
+    job.message = Some("NOTEBOOK_TEMPLATE_WORKER_PANICKED".to_string());
+    job.updated_at = chrono::Utc::now().timestamp_millis();
+    persist_notebook_setup_terminal_until_committed(state.inner(), &app, job);
+    release_notebook_template_setup(state.inner(), &latest.notebook_id);
+}
+
+fn finish_notebook_template_setup(app: AppHandle, mut job: NotebookSetupJob) {
+    let state = app.state::<AppState>();
+    let mut report = job.report.clone().unwrap_or_default();
+    let result = (|| {
+        let template_id = job
+            .template_id
+            .as_deref()
+            .ok_or_else(|| "NOTEBOOK_TEMPLATE_NOT_SELECTED".to_string())?;
+        if template_id.starts_with("scene-") {
+            let template = super::memo::creates::resolve_notebook_template(template_id)?;
+            if template.id != template_id {
+                job.template_id = Some(template.id);
+                job.updated_at = chrono::Utc::now().timestamp_millis();
+                job = persist_notebook_setup_job(state.inner(), &app, job.clone())?;
+            }
+        }
+        if job.stage != NotebookSetupStage::Indexing {
+            let notebook_id = job.notebook_id.clone();
+            let template_id = job
+                .template_id
+                .clone()
+                .ok_or_else(|| "NOTEBOOK_TEMPLATE_NOT_SELECTED".to_string())?;
+            let mut next_stage_job = job.clone();
+            super::memo::creates::initialize_notebook_template_for_notebook(
+                &notebook_id,
+                &template_id,
+                true,
+                job.overwrite_existing,
+                state.inner(),
+                &app,
+                Some(&job),
+                |report| {
+                    next_stage_job.stage = NotebookSetupStage::Indexing;
+                    next_stage_job.message = None;
+                    next_stage_job.report = Some(report.clone());
+                    next_stage_job.updated_at = chrono::Utc::now().timestamp_millis();
+                    next_stage_job = persist_notebook_setup_job(
+                        state.inner(),
+                        &app,
+                        next_stage_job.clone(),
+                    )?;
+                    Ok(())
+                },
+            )?;
+            report = next_stage_job.report.clone().unwrap_or_default();
+            job = next_stage_job;
+        }
+
+        if job.stage == NotebookSetupStage::Indexing {
+            let template_id = job
+                .template_id
+                .as_deref()
+                .ok_or_else(|| "NOTEBOOK_TEMPLATE_NOT_SELECTED".to_string())?;
+            super::memo::creates::clear_notebook_template_init_marker(
+                &job.notebook_id,
+                template_id,
+                state.inner(),
+            )?;
+        }
+
+        emit_notebook_import_status(
+            state.inner(),
+            &app,
+            &job.notebook_id,
+            NotebookImportStatusKind::Started,
+            None,
+        );
+        if !run_notebook_import(app.clone(), job.notebook_id.clone(), false) {
+            let message = state
+                .notebook_imports
+                .lock()
+                .ok()
+                .and_then(|imports| imports.get(&job.notebook_id).and_then(|status| status.message.clone()))
+                .unwrap_or_else(|| "NOTEBOOK_IMPORT_FAILED".to_string());
+            return Err(message);
+        }
+        Ok(())
+    })();
+
+    if result.is_err() {
+        let Some(latest) = read_current_notebook_setup_run(
+            state.inner(),
+            &job.notebook_id,
+            &job.job_id,
+            &job.run_id,
+        ) else {
+            release_notebook_template_setup(state.inner(), &job.notebook_id);
+            return;
+        };
+        job.stage = latest.stage;
+        if let Some(latest_report) = latest.report {
+            report = latest_report;
+        }
+    }
+
+    job.updated_at = chrono::Utc::now().timestamp_millis();
+    match result {
+        Ok(()) => {
+            job.report = Some(report.clone());
+            if report.failed_files > 0 {
+                job.status = NotebookSetupJobStatus::Partial;
+                job.stage = NotebookSetupStage::Writing;
+            } else {
+                job.status = NotebookSetupJobStatus::Completed;
+                job.stage = NotebookSetupStage::Completed;
+            }
+            job.message = None;
+        }
+        Err(message) => {
+            job.status = NotebookSetupJobStatus::Failed;
+            if report.failed_files > 0 && job.stage != NotebookSetupStage::Indexing {
+                job.stage = NotebookSetupStage::Writing;
+            }
+            job.report = Some(report);
+            job.message = Some(message);
+        }
+    }
+    persist_notebook_setup_terminal_until_committed(state.inner(), &app, job.clone());
+    release_notebook_template_setup(state.inner(), &job.notebook_id);
+}
+
+#[tauri::command]
+pub fn get_notebook_template_setup_status(
+    notebook_id: String,
+    state: State<AppState>,
+) -> Result<Option<NotebookSetupJob>, String> {
+    read_lock(&state.memo_file, "memo_file")
+        .get_notebook_setup_job(&notebook_id)
+        .map_err(|error| format!("read notebook setup status failed: {error}"))
+}
+
+#[tauri::command]
+pub async fn get_notebook_template_setup_snapshot(
+    app: AppHandle,
+) -> Result<NotebookSetupSnapshot, String> {
+    tauri::async_runtime::spawn_blocking(move || {
+        let state = app.state::<AppState>();
+        let snapshot = read_lock(&state.memo_file, "memo_file")
+            .get_notebook_setup_snapshot()
+            .map_err(|error| format!("read notebook setup snapshot failed: {error}"));
+        snapshot
+    })
+    .await
+    .map_err(|error| format!("notebook setup snapshot task failed: {error}"))?
+}
+
+/// Start or resume template preparation for an opened notebook. Failed and
+/// partial jobs only restart when the user explicitly requests a retry.
+#[tauri::command]
+pub fn start_notebook_template_setup(
+    notebook_id: String,
+    retry: Option<bool>,
+    app: AppHandle,
+) -> Result<Option<NotebookSetupJob>, String> {
+    let state = app.state::<AppState>();
+    let mut running = state
+        .notebook_template_initializations
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    let memo_file = read_lock(&state.memo_file, "memo_file");
+    let Some(mut job) = memo_file
+        .get_notebook_setup_job(&notebook_id)
+        .map_err(|error| format!("read notebook setup status failed: {error}"))?
+    else {
+        return Ok(None);
+    };
+    drop(memo_file);
+
+    if job.status == NotebookSetupJobStatus::Completed {
+        return Ok(Some(job));
+    }
+    if matches!(job.status, NotebookSetupJobStatus::Partial | NotebookSetupJobStatus::Failed)
+        && retry != Some(true)
+    {
+        return Ok(Some(job));
+    }
+    if job.status == NotebookSetupJobStatus::Partial && retry == Some(true) {
+        job.status = NotebookSetupJobStatus::Pending;
+        job.stage = NotebookSetupStage::Preparing;
+        job.message = None;
+        job.report = None;
+    } else if job.status == NotebookSetupJobStatus::Failed && retry == Some(true) {
+        job.status = NotebookSetupJobStatus::Pending;
+        job.message = None;
+        if job.stage != NotebookSetupStage::Indexing {
+            job.stage = NotebookSetupStage::Preparing;
+            job.report = None;
+        }
+    }
+
+    if !running.insert(notebook_id.clone()) {
+        return Ok(Some(job));
+    }
+
+    job.execution_requested = true;
+    job.status = NotebookSetupJobStatus::Running;
+    // Fresh/retried template setup starts by resolving and loading files.
+    // Preserve indexing retries so already-written templates are not applied again.
+    if job.stage != NotebookSetupStage::Indexing {
+        job.stage = NotebookSetupStage::Preparing;
+    }
+    let expected_run_id = job.run_id.clone();
+    job.run_id = uuid::Uuid::now_v7().to_string();
+    job.message = None;
+    job.updated_at = chrono::Utc::now().timestamp_millis();
+    let job = match persist_notebook_setup_run_start(state.inner(), &app, &job, &expected_run_id) {
+        Ok(job) => job,
+        Err(error) => {
+            running.remove(&notebook_id);
+            return Err(error);
+        }
+    };
+    drop(running);
+
+    let worker_app = app.clone();
+    let worker_job = job.clone();
+    let panic_app = app.clone();
+    let panic_job = job.clone();
+    if let Err(error) = std::thread::Builder::new()
+        .name(format!("notebook-setup-{}", job.notebook_id))
+        .spawn(move || {
+            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                finish_notebook_template_setup(worker_app, worker_job)
+            }));
+            if result.is_err() {
+                fail_notebook_template_setup_after_panic(panic_app, panic_job);
+            }
+        })
+    {
+        let mut failed = job.clone();
+        failed.status = NotebookSetupJobStatus::Failed;
+        failed.message = Some(format!("NOTEBOOK_SETUP_WORKER_START_FAILED:{error}"));
+        failed.updated_at = chrono::Utc::now().timestamp_millis();
+        persist_notebook_setup_terminal_until_committed(state.inner(), &app, failed);
+        release_notebook_template_setup(state.inner(), &notebook_id);
+        return Err(format!("failed to spawn notebook setup worker: {error}"));
+    }
+    Ok(Some(job))
+}
+
+/// Resume requested or interrupted jobs after workspace preparation. Also
+/// start a pending job when its notebook is the active, ready workspace.
+#[tauri::command]
+pub async fn start_or_resume_ready_notebook_template_setups(
+    active_notebook_id: Option<String>,
+    app: AppHandle,
+) -> Result<(), String> {
+    tauri::async_runtime::spawn_blocking(move || {
+        let state = app.state::<AppState>();
+        let candidates = read_lock(&state.memo_file, "memo_file")
+            .list_notebook_setup_jobs()
+            .map_err(|error| format!("read notebook setup jobs failed: {error}"))?
+            .into_iter()
+            .filter(|job| {
+                job.status == NotebookSetupJobStatus::Running
+                    || (job.status == NotebookSetupJobStatus::Pending
+                        && (job.execution_requested
+                            || active_notebook_id.as_deref() == Some(job.notebook_id.as_str())))
+            })
+            .map(|job| job.notebook_id)
+            .collect::<Vec<_>>();
+        let mut failures = Vec::new();
+        for notebook_id in candidates {
+            match start_notebook_template_setup(notebook_id, None, app.clone()) {
+                Ok(Some(_)) => {}
+                Ok(None) => {}
+                Err(error) => {
+                    tracing::warn!("failed to resume notebook template setup: {error}");
+                    failures.push(error);
+                }
+            }
+        }
+        if !failures.is_empty() {
+            return Err(format!(
+                "failed to resume {} notebook template setup job(s): {}",
+                failures.len(),
+                failures.join("; ")
+            ));
+        }
+        Ok(())
+    })
+    .await
+    .map_err(|error| format!("notebook setup recovery task failed: {error}"))?
+}
+
+/// Attach a deferred template to an already registered notebook.
+/// This is used by retry-safe onboarding when its chosen default path was
+/// registered before the current onboarding attempt.
+#[tauri::command]
+pub async fn ensure_notebook_template_setup(
+    notebook_id: String,
+    template_id: String,
+    overwrite_existing: Option<bool>,
+    app: AppHandle,
+) -> Result<NotebookSetupJob, String> {
+    let event_app = app.clone();
+    let job = tauri::async_runtime::spawn_blocking(move || {
+        super::memo::creates::validate_notebook_template_id(&template_id)?;
+        let state = app.state::<AppState>();
+        let running = state
+            .notebook_template_initializations
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let memo_file = read_lock(&state.memo_file, "memo_file");
+        let notebook = memo_file
+            .get_notebook_config_by_id(&notebook_id)
+            .ok_or_else(|| "NOTEBOOK_NOT_FOUND".to_string())?;
+        let existing = memo_file
+            .get_notebook_setup_job(&notebook_id)
+            .map_err(|error| format!("read notebook setup status failed: {error}"))?;
+        if let Some(existing) = &existing {
+            let matches = match existing.template_id.as_deref() {
+                Some(existing_id) => {
+                    super::memo::creates::notebook_template_ids_match(existing_id, &template_id)?
+                }
+                None => false,
+            };
+            if !matches {
+                return Err("NOTEBOOK_TEMPLATE_SELECTION_CONFLICT".to_string());
+            }
+        }
+
+        let notebook_root = PathBuf::from(&notebook.path);
+        if !notebook_root.is_dir() {
+            return Err("PATH_MISSING".to_string());
+        }
+        let overwrite_existing = overwrite_existing.unwrap_or(false);
+        if existing.is_none()
+            && !overwrite_existing
+            && super::notebook::notebook_folder_has_content(&notebook_root)?
+        {
+            return Err("NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED".to_string());
+        }
+        if overwrite_existing
+            && existing.as_ref().is_some_and(|job| !job.overwrite_existing)
+            && running.contains(&notebook_id)
+        {
+            return Err("NOTEBOOK_TEMPLATE_SETUP_IN_PROGRESS".to_string());
+        }
+        MemoFile::ensure_notebook_scene_id(&notebook, &template_id)
+            .map_err(|error| format!("NOTEBOOK_SCENE_ID_WRITE_FAILED: {error}"))?;
+
+        if let Some(mut existing) = existing {
+            let normalize_template_id = !running.contains(&notebook_id)
+                && existing.template_id.as_deref() != Some(template_id.as_str());
+            let enable_overwrite = overwrite_existing && !existing.overwrite_existing;
+            if normalize_template_id {
+                existing.template_id = Some(template_id);
+            }
+            if enable_overwrite {
+                existing.overwrite_existing = true;
+                existing.status = NotebookSetupJobStatus::Pending;
+                existing.stage = NotebookSetupStage::Preparing;
+                existing.message = None;
+                existing.report = None;
+            }
+            if normalize_template_id || enable_overwrite {
+                existing.updated_at = chrono::Utc::now().timestamp_millis();
+                existing = memo_file
+                    .write_notebook_setup_job(&existing)
+                    .map_err(|error| format!("persist notebook setup status failed: {error}"))?;
+            }
+            return Ok(existing);
+        }
+        let job = NotebookSetupJob {
+            notebook_id,
+            job_id: uuid::Uuid::now_v7().to_string(),
+            template_id: Some(template_id),
+            overwrite_existing,
+            status: NotebookSetupJobStatus::Pending,
+            stage: NotebookSetupStage::Preparing,
+            revision: 0,
+            run_id: String::new(),
+            message: None,
+            report: None,
+            updated_at: chrono::Utc::now().timestamp_millis(),
+            execution_requested: false,
+        };
+        let job = memo_file
+            .write_notebook_setup_job(&job)
+            .map_err(|error| format!("persist notebook setup status failed: {error}"))?;
+        Ok(job)
+    })
+    .await
+    .map_err(|error| format!("notebook template setup registration task failed: {error}"))??;
+    emit_notebook_setup_job(&event_app, job.clone());
+    Ok(job)
+}
diff --git a/app/flowix-desktop/src/commands/path_change.rs b/app/flowix-desktop/src/commands/path_change.rs
new file mode 100644
index 000000000..5b010b220
--- /dev/null
+++ b/app/flowix-desktop/src/commands/path_change.rs
@@ -0,0 +1,130 @@
+use serde::Serialize;
+use tauri::Emitter;
+
+/// The same confirmed fact is returned by a command and broadcast to windows.
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookPathMove {
+    pub change_id: String,
+    pub notebook_id: String,
+    pub previous_relative_path: String,
+    pub relative_path: String,
+    pub directory: bool,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookPathCreated {
+    pub change_id: String,
+    pub notebook_id: String,
+    pub relative_path: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<&'static str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub origin_window_label: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookPathDeleted {
+    pub change_id: String,
+    pub notebook_id: String,
+    pub relative_path: String,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NotebookPathInvalidated {
+    pub change_id: String,
+    pub notebook_id: String,
+    pub relative_path: String,
+}
+
+impl NotebookPathCreated {
+    pub fn from_window(
+        notebook_id: String,
+        relative_path: String,
+        origin_window_label: String,
+    ) -> Self {
+        Self {
+            change_id: uuid::Uuid::new_v4().to_string(),
+            notebook_id,
+            relative_path,
+            source: None,
+            origin_window_label: Some(origin_window_label),
+        }
+    }
+
+    pub fn from_external_tool(notebook_id: String, relative_path: String) -> Self {
+        Self {
+            change_id: uuid::Uuid::new_v4().to_string(),
+            notebook_id,
+            relative_path,
+            source: Some("external_tool"),
+            origin_window_label: None,
+        }
+    }
+
+    pub fn emit(&self, app: &tauri::AppHandle) {
+        let mut payload = serde_json::json!({
+            "changeId": self.change_id,
+            "notebookId": self.notebook_id,
+            "relativePath": self.relative_path,
+            "created": true,
+            "deleted": false,
+        });
+        if let Some(source) = self.source {
+            payload["source"] = serde_json::json!(source);
+        }
+        if let Some(origin) = &self.origin_window_label {
+            payload["originWindowLabel"] = serde_json::json!(origin);
+        }
+        let _ = app.emit("flowix:path-note-changed", payload);
+    }
+}
+
+impl NotebookPathDeleted {
+    pub fn new(notebook_id: String, relative_path: String) -> Self {
+        Self { change_id: uuid::Uuid::new_v4().to_string(), notebook_id, relative_path }
+    }
+
+    pub fn emit(&self, app: &tauri::AppHandle) {
+        let payload = serde_json::json!({
+            "changeId": self.change_id,
+            "notebookId": self.notebook_id,
+            "relativePath": self.relative_path,
+            "deleted": true,
+        });
+        let _ = app.emit("flowix:path-note-changed", payload);
+    }
+}
+
+impl NotebookPathInvalidated {
+    pub fn new(notebook_id: String, relative_path: String) -> Self {
+        Self { change_id: uuid::Uuid::new_v4().to_string(), notebook_id, relative_path }
+    }
+
+    pub fn emit(&self, app: &tauri::AppHandle) {
+        let _ = app.emit("flowix:path-note-changed", self);
+    }
+}
+
+impl NotebookPathMove {
+    pub fn new(notebook_id: String, previous: String, next: String, directory: bool) -> Self {
+        Self {
+            change_id: uuid::Uuid::new_v4().to_string(), notebook_id,
+            previous_relative_path: previous, relative_path: next, directory,
+        }
+    }
+
+    pub fn emit(&self, app: &tauri::AppHandle) {
+        let _ = app.emit("flowix:path-note-changed", self);
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PathMutationResult {
+    pub path: String,
+    pub notebook_change: Option<NotebookPathMove>,
+}
diff --git a/app/flowix-desktop/src/commands/product.rs b/app/flowix-desktop/src/commands/product.rs
index 265c9de98..c05f66e17 100644
--- a/app/flowix-desktop/src/commands/product.rs
+++ b/app/flowix-desktop/src/commands/product.rs
@@ -6,7 +6,7 @@ use tauri_plugin_opener::OpenerExt;
 
 use crate::app::state::AppState;
 use crate::commands::helpers::{
-    can_access_document_path, can_access_scoped_file, start_security_bookmark_access,
+    can_access_document_path, can_access_scoped_file,
 };
 use crate::runtime_log;
 
@@ -20,9 +20,15 @@ pub struct ProductInfo {
     pub log_dir: String,
     pub os: &'static str,
     pub arch: &'static str,
+    pub is_dev_build: bool,
+    pub cloud_environment: &'static str,
 }
 
-fn product_info() -> ProductInfo {
+pub(crate) fn is_dev_build() -> bool {
+    option_env!("FLOWIX_DEV_MODE") == Some("1")
+}
+
+fn product_info(cloud_environment: flowix_sync::CloudEnvironment) -> ProductInfo {
     ProductInfo {
         product_name: runtime_log::PRODUCT_NAME,
         version: runtime_log::APP_VERSION,
@@ -31,12 +37,37 @@ fn product_info() -> ProductInfo {
         log_dir: runtime_log::log_dir().display().to_string(),
         os: std::env::consts::OS,
         arch: std::env::consts::ARCH,
+        is_dev_build: is_dev_build(),
+        cloud_environment: cloud_environment.name(),
     }
 }
 
 #[tauri::command]
-pub fn get_product_info() -> ProductInfo {
-    product_info()
+pub fn get_product_info(state: State<AppState>) -> ProductInfo {
+    product_info(state.cloud_environment)
+}
+
+#[tauri::command]
+pub fn set_cloud_environment(
+    environment: String,
+    state: State<AppState>,
+) -> Result<(), String> {
+    if !is_dev_build() {
+        return Err("Cloud environment can only be changed in a development build".to_string());
+    }
+    let Some(target) = flowix_sync::CloudEnvironment::parse(&environment) else {
+        return Err(format!("unsupported Cloud environment: {environment}"));
+    };
+
+    let saved_environment = state.user_config.get_preference().cloud_environment;
+    if saved_environment == target.name() {
+        return Ok(());
+    }
+
+    state
+        .user_config
+        .patch_preference(serde_json::json!({ "cloudEnvironment": target.name() }))
+        .map_err(|error| error.to_string())
 }
 
 #[tauri::command]
@@ -70,7 +101,6 @@ pub fn open_file_with_default_app(
         return Err("File is outside its authorized scope".to_string());
     }
 
-    start_security_bookmark_access(state.inner(), &path);
     let mut command = if cfg!(target_os = "macos") {
         Command::new("open")
     } else if cfg!(target_os = "windows") {
diff --git a/app/flowix-desktop/src/commands/settings.rs b/app/flowix-desktop/src/commands/settings.rs
index bdb53fe0c..e3fa83aec 100644
--- a/app/flowix-desktop/src/commands/settings.rs
+++ b/app/flowix-desktop/src/commands/settings.rs
@@ -14,7 +14,7 @@ use crate::app::state::AppState;
 
 /// 跨窗口同步事�?—任一窗口成功写入偏好 / AI 配置�?emit, 其它窗口
 /// (主窗�?/ 偏好窗口 / �?��的�?窗口) 收到后从磁盘重新 load�?/// 解决: 两个 Tauri 窗口各跑�?�� React �?+ �?�� zustand store, 一�?/// 改动另一边看不到的问题�?
-pub(super) const USER_CONFIG_CHANGED_EVENT: &str = "user-config-changed";
+pub(crate) const USER_CONFIG_CHANGED_EVENT: &str = "user-config-changed";
 
 /// 用户偏好 (preference.json) —�?~/.flowix/boot/preference.json
 #[tauri::command]
@@ -62,7 +62,7 @@ pub async fn get_deepseek_harness_config(
     state: State<'_, AppState>,
 ) -> Result<AiConfigFile, String> {
     let mut configs = load_dsh_model_configs(&state).await?;
-    hydrate_dsh_credentials_without_blocking(&state, &mut configs).await;
+    hydrate_dsh_credential_statuses_without_blocking(&state, &mut configs).await;
     Ok(configs.into_iter().next().unwrap_or_default())
 }
 
@@ -71,7 +71,7 @@ pub async fn get_deepseek_harness_configs(
     state: State<'_, AppState>,
 ) -> Result<Vec<AiConfigFile>, String> {
     let mut configs = load_dsh_model_configs(&state).await?;
-    hydrate_dsh_credentials_without_blocking(&state, &mut configs).await;
+    hydrate_dsh_credential_statuses_without_blocking(&state, &mut configs).await;
     Ok(configs)
 }
 
@@ -79,21 +79,12 @@ async fn load_dsh_model_configs(state: &State<'_, AppState>) -> Result<Vec<AiCon
     state.deepseek_harness.dsh_model_configs().await
 }
 
-/// Preferences must remain usable when Flowix has just installed an older or
-/// temporarily unavailable remote DSH runtime. Credential migration/status is
-/// best-effort here; save and connection-test commands still return actionable
-/// runtime errors when the user explicitly invokes them.
-async fn hydrate_dsh_credentials_without_blocking(
+/// Credential status is best-effort here; save and connection-test commands
+/// still return actionable runtime errors when the user explicitly invokes them.
+async fn hydrate_dsh_credential_statuses_without_blocking(
     state: &State<'_, AppState>,
     configs: &mut [AiConfigFile],
 ) {
-    if let Err(error) = state
-        .deepseek_harness
-        .migrate_legacy_credentials(configs)
-        .await
-    {
-        tracing::warn!(%error, "could not migrate legacy Flowix credentials to DSH");
-    }
     if let Err(error) = state
         .deepseek_harness
         .hydrate_credential_statuses(configs)
@@ -222,6 +213,11 @@ pub fn save_pi_features(features: crate::agent_external::pi::config::PiFeatures)
     pi_model_config::save_features(features)
 }
 
+#[tauri::command]
+pub fn clear_pi_legacy_code_mode() -> Result<(), String> {
+    pi_model_config::clear_legacy_code_mode()
+}
+
 #[tauri::command]
 pub fn get_pi_model_catalog(
     app: AppHandle,
diff --git a/app/flowix-desktop/src/commands/shutdown_watchdog.rs b/app/flowix-desktop/src/commands/shutdown_watchdog.rs
new file mode 100644
index 000000000..8157142a6
--- /dev/null
+++ b/app/flowix-desktop/src/commands/shutdown_watchdog.rs
@@ -0,0 +1,26 @@
+//! Lock-free deadline enforcement. Callbacks must not depend on the UI/runtime.
+use std::time::{Duration, Instant};
+
+/// Total close/quit budget measured from native request receipt, not save start.
+pub(super) const CLOSE_BUDGET: Duration = Duration::from_secs(1);
+
+pub(super) fn arm(deadline: Instant, force: impl FnOnce() + Send + 'static) {
+    std::thread::spawn(move || {
+        std::thread::sleep(deadline.saturating_duration_since(Instant::now()));
+        force();
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::mpsc;
+    #[test]
+    fn expired_deadline_is_not_restarted_when_work_is_delayed() {
+        let (sender, receiver) = mpsc::channel();
+        arm(Instant::now() - Duration::from_secs(1), move || {
+            let _ = sender.send(());
+        });
+        receiver.recv_timeout(Duration::from_millis(100)).unwrap();
+    }
+}
diff --git a/app/flowix-desktop/src/commands/tag.rs b/app/flowix-desktop/src/commands/tag.rs
index 6af97e35a..b549283d9 100644
--- a/app/flowix-desktop/src/commands/tag.rs
+++ b/app/flowix-desktop/src/commands/tag.rs
@@ -37,22 +37,18 @@ pub struct TagWithId {
     pub name: String,
 }
 
-#[derive(Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct CreateTagReport {
-    pub path: String,
-}
-
 #[tauri::command]
 pub async fn get_all_tags(
     notebook_id: Option<String>,
     app: AppHandle,
 ) -> Result<GetAllTagsResponse, String> {
-    tauri::async_runtime::spawn_blocking(move || {
+    tauri::async_runtime::spawn_blocking(move || -> Result<GetAllTagsResponse, String> {
         let state = app.state::<AppState>();
-        let tags = read_lock(&state.memo_file, "memo_file")
-            .derived_tags_for_notebook_id(notebook_id.as_deref());
-        GetAllTagsResponse {
+        let memo_file = read_lock(&state.memo_file, "memo_file");
+        let id = notebook_id.or_else(|| memo_file.current_notebook_id_value()).unwrap_or_default();
+        let tags = memo_file.derived_tags_for_notebook_id(Some(&id))
+            .map_err(|error| crate::app::notebook_background::query_error(state.inner(), &id, error))?;
+        Ok(GetAllTagsResponse {
             tags: tags
                 .into_iter()
                 .map(|t| TagWithId {
@@ -60,22 +56,10 @@ pub async fn get_all_tags(
                     name: t.name,
                 })
                 .collect(),
-        }
+        })
     })
     .await
-    .map_err(|error| format!("tag list task failed: {error}"))
-}
-
-#[tauri::command]
-pub fn create_notebook_tag(
-    notebook_id: String,
-    path: String,
-    state: State<AppState>,
-) -> Result<CreateTagReport, String> {
-    let path = read_lock(&state.memo_file, "memo_file")
-        .create_notebook_tag(&notebook_id, &path)
-        .map_err(|error| error.to_string())?;
-    Ok(CreateTagReport { path })
+    .map_err(|error| format!("tag list task failed: {error}"))?
 }
 
 /// 移动 subtag: �?`old_path` 整棵子树重命�?(�?prefix 替换),
@@ -111,10 +95,6 @@ pub fn move_memo_tag(
     };
 
     let sync_notebook_id = notebook_id.as_deref().unwrap_or("nb_default");
-    // read lock 已释放: 逐条 emit MemoEvent::Updated, 让前端 memo 卡片 /
-    // 标签树刷新 (derived_changed.tags -> refreshSelectedNotebookMetadata)。
-    for path in &affected_relative_paths {
-    }
     mark_tagged_memos_cloud_dirty(state.inner(), sync_notebook_id, &affected_relative_paths);
     if !affected_relative_paths.is_empty() {
         crate::commands::cloud::schedule_notebook_sync(app.clone(), sync_notebook_id.to_string());
@@ -158,11 +138,6 @@ pub fn delete_memo_tag(
     };
 
     let sync_notebook_id = notebook_id.as_deref().unwrap_or("nb_default");
-    // read lock released:
-    // 1) refresh search index per affected note (tag removed from body,
-    //    search index must follow -- otherwise stale hits leak through).
-    for path in &affected_relative_paths {
-    }
     mark_tagged_memos_cloud_dirty(state.inner(), sync_notebook_id, &affected_relative_paths);
     if !affected_relative_paths.is_empty() {
         crate::commands::cloud::schedule_notebook_sync(app.clone(), sync_notebook_id.to_string());
@@ -195,8 +170,11 @@ pub async fn get_tag_prefix_counts(
         });
         memo_file
             .read_tag_prefix_counts_for_notebook_id(notebook_id.as_deref())
-            .unwrap_or_default()
+            .map_err(|error| {
+                let id = notebook_id.clone().or_else(|| memo_file.current_notebook_id_value()).unwrap_or_default();
+                crate::app::notebook_background::query_error(state.inner(), &id, error)
+            })
     })
     .await
-    .map_err(|error| format!("tag count task failed: {error}"))
+    .map_err(|error| format!("tag count task failed: {error}"))?
 }
diff --git a/app/flowix-desktop/src/commands/thread.rs b/app/flowix-desktop/src/commands/thread.rs
index cbc4ea776..e45a94ad7 100644
--- a/app/flowix-desktop/src/commands/thread.rs
+++ b/app/flowix-desktop/src/commands/thread.rs
@@ -256,20 +256,28 @@ pub async fn agent_conversation_list(
 
 #[tauri::command]
 pub async fn agent_conversation_list_page(
-    notebook_id: Option<String>,
+    notebook_id: String,
     agent_type: Option<String>,
     cursor: Option<AgentConversationCursor>,
     limit: usize,
     state: State<'_, AppState>,
 ) -> Result<AgentConversationPage, String> {
     let page_size = limit.clamp(1, 100);
-    let notebook_id = notebook_id.filter(|value| !value.trim().is_empty());
+    let notebook_id = notebook_id.trim();
+    if notebook_id.is_empty() {
+        return Err("NOTEBOOK_ID_REQUIRED".to_string());
+    }
     let agent_type = agent_type
         .map(|value| value.trim().to_ascii_lowercase())
         .filter(|value| !value.is_empty());
     let manager = &state.thread_manager;
     let items = manager
-        .list_agent_conversation_instances_page(notebook_id, agent_type, cursor, page_size + 1)
+        .list_agent_conversation_instances_page(
+            Some(notebook_id.to_string()),
+            agent_type,
+            cursor,
+            page_size + 1,
+        )
         .await
         .map_err(|e| e.to_string())?;
     let has_more = items.len() > page_size;
@@ -287,24 +295,32 @@ pub async fn agent_conversation_list_page(
 
 #[tauri::command]
 pub async fn agent_conversation_count_by_notebook(
-    notebook_id: Option<String>,
+    notebook_id: String,
     state: State<'_, AppState>,
 ) -> Result<usize, String> {
+    let notebook_id = notebook_id.trim();
+    if notebook_id.is_empty() {
+        return Err("NOTEBOOK_ID_REQUIRED".to_string());
+    }
     let manager = &state.thread_manager;
     manager
-        .count_agent_conversation_instances_by_notebook(notebook_id)
+        .count_agent_conversation_instances_by_notebook(Some(notebook_id.to_string()))
         .await
         .map_err(|e| e.to_string())
 }
 
 #[tauri::command]
 pub async fn agent_conversation_type_counts_by_notebook(
-    notebook_id: Option<String>,
+    notebook_id: String,
     state: State<'_, AppState>,
 ) -> Result<Vec<AgentConversationTypeCount>, String> {
+    let notebook_id = notebook_id.trim();
+    if notebook_id.is_empty() {
+        return Err("NOTEBOOK_ID_REQUIRED".to_string());
+    }
     state
         .thread_manager
-        .list_agent_conversation_type_counts_by_notebook(notebook_id)
+        .list_agent_conversation_type_counts_by_notebook(Some(notebook_id.to_string()))
         .await
         .map_err(|e| e.to_string())
 }
@@ -507,7 +523,7 @@ pub async fn claude_thread_session_id(
 
     let manager = &state.thread_manager;
     manager
-        .get_external_session(&thread_id, "claude")
+        .get_external_session(&thread_id, "claudecode")
         .await
         .map_err(|e| e.to_string())
 }
@@ -617,7 +633,7 @@ pub async fn deepseek_harness_thread_session_id(
 ) -> Result<Option<String>, String> {
     state
         .thread_manager
-        .get_external_session(&thread_id, "deepseek-harness")
+        .get_external_session(&thread_id, "dsh")
         .await
         .map_err(|error| error.to_string())
 }
@@ -637,7 +653,7 @@ pub async fn deepseek_harness_thread_fork(
     let child = state
         .thread_manager
         .create_thread(
-            crate::agent_types::AgentId("deepseek-harness".to_string()),
+            crate::agent_types::AgentId("dsh".to_string()),
             format!("{} (fork)", source.info.title),
         )
         .await
diff --git a/app/flowix-desktop/src/commands/window.rs b/app/flowix-desktop/src/commands/window.rs
index 289a26327..6a660edd3 100644
--- a/app/flowix-desktop/src/commands/window.rs
+++ b/app/flowix-desktop/src/commands/window.rs
@@ -40,6 +40,9 @@ mod navigation_tests {
 
 #[tauri::command]
 pub fn show_main_window(app: tauri::AppHandle) -> Result<(), String> {
+    if crate::commands::window_shutdown::is_exiting() {
+        return Ok(());
+    }
     let Some(window) = app.get_webview_window("main") else {
         return Ok(());
     };
@@ -55,8 +58,19 @@ pub async fn open_preferences_window(
     app: tauri::AppHandle,
     state: tauri::State<'_, AppState>,
     tab: Option<String>,
+) -> Result<(), String> {
+    open_preferences_window_inner(&app, &state, tab.as_deref())
+}
+
+pub(crate) fn open_preferences_window_inner(
+    app: &tauri::AppHandle,
+    state: &AppState,
+    tab: Option<&str>,
 ) -> Result<(), String> {
     use tauri::WebviewWindowBuilder;
+    if crate::commands::window_shutdown::is_exiting() {
+        return Err("Application is closing".into());
+    }
 
     let boot_theme = match state.user_config.get_preference().theme {
         Theme::System => None,
@@ -69,27 +83,26 @@ pub async fn open_preferences_window(
         Some(theme) => format!("index.html?bootTheme={theme}"),
         None => "index.html".to_string(),
     };
-    let url = match tab {
-        Some(tab) => format!("{base}#preferences/{tab}"),
-        None => format!("{base}#preferences"),
+    let hash = match tab {
+        Some(tab) => format!("preferences/{tab}"),
+        None => "preferences".to_string(),
     };
+    let url = format!("{base}#{hash}");
 
     if let Some(window) = app.get_webview_window("preferences") {
-        window.set_focus().ok();
         window
-            .eval(preferences_navigation_script(
-                url.split_once('#').map(|(_, hash)| hash).unwrap_or(""),
-            )?)
-            .ok();
+            .eval(preferences_navigation_script(&hash)?)
+            .map_err(|error| error.to_string())?;
+        window.set_focus().map_err(|error| error.to_string())?;
         return Ok(());
     }
 
-    let builder =
-        WebviewWindowBuilder::new(&app, "preferences", tauri::WebviewUrl::App(url.into()))
-            .title("Preferences")
-            .inner_size(800.0, 600.0)
-            .center()
-            .devtools(cfg!(debug_assertions));
+    let builder = WebviewWindowBuilder::new(app, "preferences", tauri::WebviewUrl::App(url.into()))
+        .title("Preferences")
+        .visible(false)
+        .inner_size(800.0, 600.0)
+        .center()
+        .devtools(cfg!(debug_assertions));
 
     #[cfg(target_os = "macos")]
     let builder = builder
@@ -102,9 +115,11 @@ pub async fn open_preferences_window(
     let builder = builder.decorations(false);
 
     let window = builder.build().map_err(|e| e.to_string())?;
+    crate::commands::window_shutdown::install_window(&window);
     // 新窗口即刻�?齐主题背�?�� (与主窗口�?��一�?, 避免冷启动白�?�?
     let theme = state.user_config.get_preference().theme;
     crate::window_chrome::apply_window_chrome_theme(&window, theme);
+    window.show().map_err(|error| error.to_string())?;
     Ok(())
 }
 
diff --git a/app/flowix-desktop/src/commands/window_input.rs b/app/flowix-desktop/src/commands/window_input.rs
new file mode 100644
index 000000000..e0637f1b1
--- /dev/null
+++ b/app/flowix-desktop/src/commands/window_input.rs
@@ -0,0 +1,44 @@
+//! Thin IPC adapter for native input routing.
+/// Publish visual button geometry; routing itself lives outside the WebView.
+#[tauri::command]
+pub async fn set_window_close_region(
+    window: tauri::WebviewWindow,
+    revision: u64,
+    region: Option<crate::native_close_region::CloseRegion>,
+) -> Result<(), String> {
+    if region.is_some_and(|region| !region.valid()) {
+        return Err("Invalid close region".into());
+    }
+    #[cfg(windows)]
+    {
+        let hwnd = window.hwnd().map_err(|error| error.to_string())?.0 as usize;
+        let route = crate::commands::window_shutdown::close_route(&window)?;
+        let (sender, receiver) = tokio::sync::oneshot::channel();
+        window
+            .run_on_main_thread(move || {
+                let _ = sender.send(crate::native_close_region::set(
+                    hwnd, route, revision, region,
+                ));
+            })
+            .map_err(|error| error.to_string())?;
+        return receiver.await.map_err(|error| error.to_string())?;
+    }
+    #[cfg(not(windows))]
+    {
+        let _ = (window, revision, region);
+        Ok(())
+    }
+}
+
+/// Actual receiver health, not merely whether initialization was attempted.
+#[tauri::command]
+pub fn native_close_routing_ready() -> bool {
+    #[cfg(windows)]
+    {
+        crate::native_close_region::routing_ready()
+    }
+    #[cfg(not(windows))]
+    {
+        true
+    }
+}
diff --git a/app/flowix-desktop/src/commands/window_lifetime.rs b/app/flowix-desktop/src/commands/window_lifetime.rs
new file mode 100644
index 000000000..d11db8000
--- /dev/null
+++ b/app/flowix-desktop/src/commands/window_lifetime.rs
@@ -0,0 +1,93 @@
+//! Identity and liveness belong to a native window instance, never its label.
+use std::sync::{
+    atomic::{AtomicU64, AtomicU8, Ordering},
+    Arc,
+};
+
+const ALIVE: u8 = 0;
+const DESTROYED: u8 = 1;
+const FORCE_COMMITTED: u8 = 2;
+
+pub(super) struct WindowLifetime {
+    id: u64,
+    state: AtomicU8,
+}
+impl WindowLifetime {
+    pub(super) fn new() -> Arc<Self> {
+        static NEXT: AtomicU64 = AtomicU64::new(1);
+        Arc::new(Self {
+            id: NEXT.fetch_add(1, Ordering::Relaxed),
+            state: AtomicU8::new(ALIVE),
+        })
+    }
+    pub(super) fn id(&self) -> u64 {
+        self.id
+    }
+    pub(super) fn is_alive(&self) -> bool {
+        self.state.load(Ordering::Acquire) == ALIVE
+    }
+    pub(super) fn destroyed(&self) {
+        let _ = self
+            .state
+            .compare_exchange(ALIVE, DESTROYED, Ordering::AcqRel, Ordering::Acquire);
+    }
+    /// Destruction and forced termination race through one atomic transition.
+    /// A stale callback cannot force after Destroyed wins, nor can a late task
+    /// target a replacement window with the same label.
+    pub(super) fn force_if_alive(&self, force: impl FnOnce()) {
+        if self
+            .state
+            .compare_exchange(ALIVE, FORCE_COMMITTED, Ordering::AcqRel, Ordering::Acquire)
+            .is_ok()
+        {
+            force();
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::{
+        sync::{mpsc, Barrier},
+        time::Duration,
+    };
+    #[test]
+    fn worker_resuming_after_destroy_cannot_force_a_replacement() {
+        let old = WindowLifetime::new();
+        let replacement = WindowLifetime::new();
+        let paused = Arc::new(Barrier::new(2));
+        let (sender, receiver) = mpsc::channel();
+        let worker = old.clone();
+        let gate = paused.clone();
+        let thread = std::thread::spawn(move || {
+            gate.wait();
+            worker.force_if_alive(|| {
+                sender.send(()).unwrap();
+            });
+        });
+        // This is the old race: dispatch already captured its target, but
+        // Destroyed is processed before dispatch registers/arms a close.
+        old.destroyed();
+        paused.wait();
+        thread.join().unwrap();
+        assert!(receiver.recv_timeout(Duration::from_millis(10)).is_err());
+        assert_ne!(old.id(), replacement.id());
+        assert!(replacement.is_alive());
+    }
+    #[test]
+    fn every_duplicate_observes_the_same_destroyed_flag() {
+        let first = WindowLifetime::new();
+        let duplicate = first.clone();
+        first.destroyed();
+        duplicate.force_if_alive(|| panic!("late force callback ran"));
+    }
+    #[test]
+    fn an_unclosed_window_still_requires_force() {
+        let lifetime = WindowLifetime::new();
+        let mut forced = false;
+        lifetime.force_if_alive(|| forced = true);
+        assert!(forced);
+        assert!(!lifetime.is_alive());
+    }
+}
diff --git a/app/flowix-desktop/src/commands/window_shutdown.rs b/app/flowix-desktop/src/commands/window_shutdown.rs
new file mode 100644
index 000000000..d1e6f64bb
--- /dev/null
+++ b/app/flowix-desktop/src/commands/window_shutdown.rs
@@ -0,0 +1,539 @@
+use std::{
+    collections::{HashMap, HashSet},
+    sync::{
+        atomic::{AtomicBool, AtomicU64, Ordering},
+        Arc, Mutex, OnceLock,
+    },
+};
+use tauri::{AppHandle, Emitter, Manager};
+
+#[path = "window_lifetime.rs"]
+mod lifetime;
+#[path = "window_shutdown_state.rs"]
+mod shutdown_state;
+#[path = "shutdown_watchdog.rs"]
+mod watchdog;
+use lifetime::WindowLifetime;
+use shutdown_state::ExitRequest;
+use std::time::Instant;
+use watchdog::CLOSE_BUDGET;
+
+#[derive(Default)]
+struct Shutdown {
+    windows: HashSet<shutdown_state::WindowId>,
+    waiting: Option<(u64, HashSet<shutdown_state::WindowId>, Completion)>,
+    approved: bool,
+    targets: HashMap<u64, Arc<CloseTarget>>,
+}
+pub(crate) struct CloseTarget {
+    lifetime: Arc<WindowLifetime>,
+    window: tauri::WebviewWindow,
+    closing: OnceLock<CloseAttempt>,
+}
+struct CloseAttempt {
+    request: u64,
+    started: Instant,
+}
+
+/// A resource in the native Window's own table survives label reuse and JS
+/// reloads. It contains no Window/App handle, so there is no ownership cycle.
+struct WindowIdentity(Arc<WindowLifetime>);
+impl tauri::Resource for WindowIdentity {}
+fn window_lifetime<R: tauri::Runtime>(window: &tauri::Window<R>) -> Arc<WindowLifetime> {
+    let mut resources = window.resources_table();
+    let existing = resources
+        .names()
+        .find(|(_, name)| name.as_ref() == std::any::type_name::<WindowIdentity>())
+        .and_then(|(id, _)| resources.get::<WindowIdentity>(id).ok());
+    if let Some(identity) = existing {
+        return identity.0.clone();
+    }
+    let lifetime = WindowLifetime::new();
+    resources.add(WindowIdentity(lifetime.clone()));
+    lifetime
+}
+fn native_window(window: &tauri::WebviewWindow) -> tauri::Window {
+    let webview: &tauri::Webview = window.as_ref();
+    webview.window()
+}
+fn next_request() -> u64 {
+    static NEXT: AtomicU64 = AtomicU64::new(1);
+    NEXT.fetch_add(1, Ordering::Relaxed)
+}
+
+enum Completion {
+    Exit(i32),
+    #[cfg(windows)]
+    Prepared(tokio::sync::oneshot::Sender<UpdatePreparation>),
+}
+fn state() -> &'static Mutex<Shutdown> {
+    static STATE: OnceLock<Mutex<Shutdown>> = OnceLock::new();
+    STATE.get_or_init(Mutex::default)
+}
+
+// These deadlines run on OS threads, independently of WebView/Tokio/UI progress.
+const UPDATE_SAVE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(8);
+
+static EXITING: AtomicBool = AtomicBool::new(false);
+
+pub(crate) fn is_exiting() -> bool {
+    EXITING.load(Ordering::Acquire)
+}
+
+fn arm_exit_watchdog(code: i32, started: Instant) {
+    if EXITING.swap(true, Ordering::AcqRel) {
+        return;
+    }
+    watchdog::arm(started + CLOSE_BUDGET, move || hard_exit(code));
+}
+
+#[cfg(test)]
+fn spawn_hard_exit(code: i32, deadline: std::time::Duration) {
+    watchdog::arm(Instant::now() + deadline, move || hard_exit(code));
+}
+
+fn hard_exit(code: i32) -> ! {
+    // Bypass atexit handlers and Rust destructors: they may hold the very locks
+    // that prevented orderly shutdown.
+    #[cfg(unix)]
+    unsafe {
+        libc::_exit(code);
+    }
+    #[cfg(windows)]
+    unsafe {
+        use windows::Win32::System::Threading::{GetCurrentProcess, TerminateProcess};
+        let _ = TerminateProcess(GetCurrentProcess(), code as u32);
+    }
+    #[allow(unreachable_code)]
+    std::process::abort()
+}
+
+/// Call during native construction, before showing a window. Repeated calls
+/// for the same instance are harmless; a dead instance is never reinstalled.
+pub(crate) fn install_window(window: &tauri::WebviewWindow) -> Option<Arc<CloseTarget>> {
+    let lifetime = window_lifetime(&native_window(window));
+    if !lifetime.is_alive() {
+        return None;
+    }
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    if !lifetime.is_alive() {
+        return None;
+    }
+    if let Some(target) = state.targets.get(&lifetime.id()) {
+        return Some(target.clone());
+    }
+    let target = Arc::new(CloseTarget {
+        lifetime,
+        window: window.clone(),
+        closing: OnceLock::new(),
+    });
+    state.targets.insert(target.lifetime.id(), target.clone());
+    Some(target)
+}
+
+/// This global native listener receives the actual Window instance, not only
+/// its reusable label. Destruction updates the shared flag even before a late
+/// constructor/input worker manages to register its coordinator record.
+pub(crate) fn on_window_event(window: &tauri::Window, event: &tauri::WindowEvent) {
+    match event {
+        tauri::WindowEvent::CloseRequested { api, .. } => {
+            api.prevent_close();
+            let lifetime = window_lifetime(window);
+            if !lifetime.is_alive() {
+                return;
+            }
+            let target = state()
+                .lock()
+                .unwrap_or_else(|e| e.into_inner())
+                .targets
+                .get(&lifetime.id())
+                .cloned();
+            let target = target.or_else(|| {
+                window
+                    .get_webview_window(window.label())
+                    .and_then(|webview| {
+                        let target = install_window(&webview)?;
+                        (target.lifetime.id() == lifetime.id()).then_some(target)
+                    })
+            });
+            if let Some(target) = target {
+                request_target(target, Instant::now());
+            }
+        }
+        tauri::WindowEvent::Destroyed => {
+            let lifetime = window_lifetime(window);
+            lifetime.destroyed(); // atomic; all stale input/deadline clones see it
+            forget_instance(window.app_handle(), &lifetime);
+        }
+        _ => {}
+    }
+}
+
+fn request_target(target: Arc<CloseTarget>, started: Instant) {
+    if !target.lifetime.is_alive() {
+        return;
+    }
+    let mut first = false;
+    let closing = target.closing.get_or_init(|| {
+        first = true;
+        CloseAttempt {
+            request: next_request(),
+            started,
+        }
+    });
+    if !first {
+        return;
+    }
+    // Arm once per native close attempt, before taking the coordinator lock.
+    // Every callback captures this instance's liveness, never its reusable label.
+    let lifetime = target.lifetime.clone();
+    watchdog::arm(started + CLOSE_BUDGET, move || {
+        lifetime.force_if_alive(|| hard_exit(0))
+    });
+    if !target.lifetime.is_alive() {
+        return;
+    }
+    let request = closing.request;
+    let app = target.window.app_handle();
+    let label = target.window.label();
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    if !target.lifetime.is_alive() {
+        return;
+    }
+    let cancelled_update = if state
+        .waiting
+        .as_ref()
+        .is_some_and(|(_, _, completion)| !matches!(completion, Completion::Exit(_)))
+    {
+        state.waiting.take().map(|(request, _, _)| request)
+    } else {
+        None
+    };
+    let needs_save = state.windows.contains(&target.lifetime.id());
+    drop(state);
+    if let Some(request) = cancelled_update {
+        let _ = app.emit("document:exit-cancelled", request);
+    }
+    if !needs_save
+        || app
+            .emit_to(label, "document:prepare-close", request)
+            .is_err()
+    {
+        complete_close(&target, request);
+    }
+}
+
+fn complete_close(target: &CloseTarget, request: u64) {
+    if target.lifetime.is_alive()
+        && target
+            .closing
+            .get()
+            .is_some_and(|closing| closing.request == request)
+    {
+        let _ = target.window.destroy(); // success only when Destroyed is observed
+    }
+}
+
+/// Input routes capture a specific instance. No label lookup happens later on
+/// the native input worker, so an old click cannot close a replacement window.
+#[cfg(windows)]
+pub(crate) fn close_route(
+    window: &tauri::WebviewWindow,
+) -> Result<crate::native_close_region::CloseRoute, String> {
+    let target = install_window(window).ok_or("Window has already been destroyed")?;
+    let lifetime = target.lifetime.clone();
+    Ok(crate::native_close_region::CloseRoute::new(
+        target.lifetime.id(),
+        move || lifetime.is_alive(),
+        move |started| {
+            request_target(target.clone(), started);
+        },
+    ))
+}
+#[cfg(windows)]
+pub(crate) fn clear_native_region(window: &tauri::Window) {
+    crate::native_close_region::remove(window_lifetime(window).id());
+}
+
+#[tauri::command]
+pub fn finish_document_close(window: tauri::WebviewWindow, request: u64, ready: bool) {
+    if let Some(target) = install_window(&window) {
+        complete_close(&target, request);
+    }
+    if !ready {
+        tracing::warn!("closing window despite incomplete document persistence");
+    }
+}
+
+#[tauri::command]
+pub fn register_document_window(window: tauri::WebviewWindow, app: AppHandle) {
+    let Some(target) = install_window(&window) else {
+        return;
+    };
+    if is_exiting() {
+        let _ = window.destroy();
+        return;
+    }
+    let label = window.label().to_string();
+    let pending_request = {
+        let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+        if !target.lifetime.is_alive() {
+            return;
+        }
+        state.windows.insert(target.lifetime.id());
+        state.waiting.as_mut().map(|(request, windows, _)| {
+            windows.insert(target.lifetime.id());
+            *request
+        })
+    };
+    if let Some(request) = pending_request {
+        let _ = app.emit_to(&label, "document:prepare-exit", request);
+    }
+}
+
+fn forget_instance(app: &AppHandle, lifetime: &WindowLifetime) {
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    let Some(target) = state.targets.remove(&lifetime.id()) else {
+        return;
+    };
+    state.windows.remove(&lifetime.id());
+    if !state
+        .targets
+        .values()
+        .any(|other| other.lifetime.is_alive())
+    {
+        if let Some(closing) = target.closing.get() {
+            // Only actual destruction of the last registered instance promotes
+            // its original close deadline to an unconditional process deadline.
+            arm_exit_watchdog(0, closing.started);
+        }
+    }
+    let require_saved = state
+        .waiting
+        .as_ref()
+        .is_some_and(|(_, _, completion)| !matches!(completion, Completion::Exit(_)));
+    let outcome = shutdown_state::destroyed(&mut state.waiting, lifetime.id(), require_saved);
+    #[cfg(windows)]
+    crate::native_close_region::remove(lifetime.id());
+    resolve_outcome(app, state, outcome);
+}
+
+/// Briefly defer exit for best-effort saving; failure can never veto user exit.
+pub fn request_exit(app: &AppHandle, code: i32) -> bool {
+    arm_exit_watchdog(code, Instant::now());
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    let cancelled = match shutdown_state::prepare_user_exit(&mut state.waiting, |completion| {
+        matches!(completion, Completion::Exit(_))
+    }) {
+        ExitRequest::AlreadyPending => return false,
+        ExitRequest::Start { cancelled } => cancelled,
+    };
+    drop(state);
+    if let Some((request, completion)) = cancelled {
+        drop(completion);
+        let _ = app.emit("document:exit-cancelled", request);
+    }
+    begin_request(app, Completion::Exit(code))
+}
+
+/// Tauri's Windows updater uses process::exit, so saving must finish before
+/// handing it the installation payload. Cancellation never exits the app.
+#[cfg(windows)]
+pub async fn prepare_for_update(app: &AppHandle) -> Result<UpdatePreparation, String> {
+    if is_exiting() {
+        return Err("Application is closing".into());
+    }
+    let (sender, receiver) = tokio::sync::oneshot::channel();
+    begin_request(app, Completion::Prepared(sender));
+    receiver.await.map_err(|_| {
+        "Update cancelled: documents could not finish saving. Save your documents and retry."
+            .to_string()
+    })
+}
+
+/// Unfreeze the editor if launching installation fails or the task is cancelled.
+#[cfg(windows)]
+pub struct UpdatePreparation {
+    app: AppHandle,
+    request: u64,
+}
+#[cfg(windows)]
+impl Drop for UpdatePreparation {
+    fn drop(&mut self) {
+        let _ = self.app.emit("document:exit-cancelled", self.request);
+    }
+}
+
+fn begin_request(app: &AppHandle, completion: Completion) -> bool {
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    if (state.approved && matches!(&completion, Completion::Exit(_))) || state.windows.is_empty() {
+        #[cfg(windows)]
+        if let Completion::Prepared(sender) = completion {
+            let _ = sender.send(UpdatePreparation {
+                app: app.clone(),
+                request: 0,
+            });
+        }
+        return true;
+    }
+    if state.waiting.is_some() {
+        return false;
+    }
+    let request = next_request();
+    let windows = state.windows.clone();
+    let targets = windows
+        .iter()
+        .map(|window_id| {
+            let label = state
+                .targets
+                .get(window_id)
+                .filter(|target| target.lifetime.is_alive())
+                .map(|target| target.window.label().to_string());
+            (*window_id, label)
+        })
+        .collect::<Vec<_>>();
+    let budget = if matches!(&completion, Completion::Exit(_)) {
+        CLOSE_BUDGET
+    } else {
+        UPDATE_SAVE_DEADLINE
+    };
+    state.waiting = Some((request, windows.clone(), completion));
+    drop(state);
+    let timeout_app = app.clone();
+    std::thread::spawn(move || {
+        std::thread::sleep(budget);
+        expire_request(&timeout_app, request);
+    });
+    for (window_id, label) in targets {
+        let Some(label) = label else {
+            finish_failed_window(app, window_id, request);
+            continue;
+        };
+        if let Err(error) = app.emit_to(&label, "document:prepare-exit", request) {
+            tracing::error!("cannot prepare document window for exit: {error}");
+            finish_failed_window(app, window_id, request);
+        }
+    }
+    false
+}
+
+fn expire_request(app: &AppHandle, request: u64) {
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    let Some((_, completion)) = shutdown_state::expire(&mut state.waiting, request) else {
+        return;
+    };
+    state.approved = matches!(&completion, Completion::Exit(_));
+    drop(state);
+    match completion {
+        Completion::Exit(code) => app.exit(code),
+        #[cfg(windows)]
+        Completion::Prepared(_) => {
+            let _ = app.emit("document:exit-cancelled", request);
+        }
+    }
+}
+
+fn finish_failed_window(app: &AppHandle, window_id: shutdown_state::WindowId, request: u64) {
+    report_window(app, window_id, request, false);
+}
+
+fn report_window(app: &AppHandle, window_id: shutdown_state::WindowId, request: u64, ready: bool) {
+    let mut state = state().lock().unwrap_or_else(|e| e.into_inner());
+    let Some((id, _, completion)) = state.waiting.as_ref() else {
+        return;
+    };
+    if *id != request {
+        return;
+    }
+    let require_saved = !matches!(completion, Completion::Exit(_));
+    let outcome = shutdown_state::report(&mut state.waiting, window_id, ready, require_saved);
+    resolve_outcome(app, state, outcome);
+}
+
+fn resolve_outcome(
+    app: &AppHandle,
+    mut state: std::sync::MutexGuard<'_, Shutdown>,
+    outcome: shutdown_state::Report<Completion>,
+) {
+    match outcome {
+        shutdown_state::Report::Pending => {}
+        shutdown_state::Report::Cancelled(request) => {
+            drop(state);
+            let _ = app.emit("document:exit-cancelled", request);
+        }
+        shutdown_state::Report::Complete(request, completion) => {
+            state.approved = matches!(&completion, Completion::Exit(_));
+            drop(state);
+            complete_request(app, request, completion);
+        }
+    }
+}
+
+#[tauri::command]
+pub fn finish_document_shutdown(
+    window: tauri::WebviewWindow,
+    app: AppHandle,
+    request: u64,
+    ready: bool,
+) {
+    if !ready {
+        tracing::warn!("document persistence incomplete during shutdown");
+    }
+    let window_id = window_lifetime(&native_window(&window)).id();
+    report_window(&app, window_id, request, ready);
+}
+
+fn complete_request(app: &AppHandle, _request: u64, completion: Completion) {
+    match completion {
+        Completion::Exit(code) => app.exit(code),
+        #[cfg(windows)]
+        Completion::Prepared(sender) => {
+            // An unread queued guard is also dropped when an update is cancelled.
+            let _ = sender.send(UpdatePreparation {
+                app: app.clone(),
+                request: _request,
+            });
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hard_deadline_ignores_blocked_cleanup() {
+        const CHILD: &str = "FLOWIX_SHUTDOWN_WATCHDOG_TEST_CHILD";
+        if std::env::var_os(CHILD).is_some() {
+            spawn_hard_exit(73, CLOSE_BUDGET);
+            let mutex = Mutex::new(());
+            let _held = mutex.lock().unwrap();
+            // Deliberately deadlock this process; only the native watchdog can
+            // finish it. No Tauri event loop or Tokio runtime is present.
+            let _blocked = mutex.lock().unwrap();
+            unreachable!();
+        }
+        let mut child = std::process::Command::new(std::env::current_exe().unwrap())
+            .args([
+                "--exact",
+                "commands::window_shutdown::tests::hard_deadline_ignores_blocked_cleanup",
+            ])
+            .env(CHILD, "1")
+            .stdout(std::process::Stdio::null())
+            .spawn()
+            .unwrap();
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(3);
+        loop {
+            if let Some(status) = child.try_wait().unwrap() {
+                assert_eq!(status.code(), Some(73));
+                break;
+            }
+            if std::time::Instant::now() >= deadline {
+                let _ = child.kill();
+                let _ = child.wait();
+                panic!("watchdog failed to terminate a blocked process");
+            }
+            std::thread::sleep(std::time::Duration::from_millis(10));
+        }
+    }
+}
diff --git a/app/flowix-desktop/src/commands/window_shutdown_state.rs b/app/flowix-desktop/src/commands/window_shutdown_state.rs
new file mode 100644
index 000000000..6e0524d77
--- /dev/null
+++ b/app/flowix-desktop/src/commands/window_shutdown_state.rs
@@ -0,0 +1,243 @@
+use std::collections::HashSet;
+
+pub(super) type WindowId = u64;
+
+pub(super) enum ExitRequest<C> {
+    AlreadyPending,
+    Start { cancelled: Option<(u64, C)> },
+}
+
+/// A repeated user quit must remain deferred while the existing save pass runs.
+/// A user quit may supersede updater preparation, but never an earlier user quit.
+pub(super) fn prepare_user_exit<C>(
+    waiting: &mut Option<(u64, HashSet<WindowId>, C)>,
+    is_exit: impl FnOnce(&C) -> bool,
+) -> ExitRequest<C> {
+    if waiting
+        .as_ref()
+        .is_some_and(|(_, _, completion)| is_exit(completion))
+    {
+        return ExitRequest::AlreadyPending;
+    }
+    ExitRequest::Start {
+        cancelled: waiting
+            .take()
+            .map(|(request, _, completion)| (request, completion)),
+    }
+}
+
+/// Saving is mandatory for an installer, but only best effort for user exit.
+pub(super) enum Report<C> {
+    Pending,
+    Complete(u64, C),
+    Cancelled(u64),
+}
+
+/// Release a window after a successful save acknowledgement.
+fn finish_window<C>(
+    waiting: &mut Option<(u64, HashSet<WindowId>, C)>,
+    window_id: WindowId,
+) -> Option<(u64, C)> {
+    if let Some((_, windows, _)) = waiting.as_mut() {
+        windows.remove(&window_id);
+    }
+    if waiting
+        .as_ref()
+        .is_some_and(|(_, windows, _)| windows.is_empty())
+    {
+        waiting
+            .take()
+            .map(|(request, _, completion)| (request, completion))
+    } else {
+        None
+    }
+}
+
+/// Destruction is acceptable for best-effort user exit, but it cannot satisfy
+/// the installer's durable-save requirement.
+pub(super) fn destroyed<C>(
+    waiting: &mut Option<(u64, HashSet<WindowId>, C)>,
+    window_id: WindowId,
+    require_saved: bool,
+) -> Report<C> {
+    let Some((request, windows, _)) = waiting.as_ref() else {
+        return Report::Pending;
+    };
+    if !windows.contains(&window_id) {
+        return Report::Pending;
+    }
+    if require_saved {
+        let request = *request;
+        waiting.take();
+        return Report::Cancelled(request);
+    }
+    match finish_window(waiting, window_id) {
+        Some((request, completion)) => Report::Complete(request, completion),
+        None => Report::Pending,
+    }
+}
+
+pub(super) fn report<C>(
+    waiting: &mut Option<(u64, HashSet<WindowId>, C)>,
+    window_id: WindowId,
+    ready: bool,
+    require_saved: bool,
+) -> Report<C> {
+    let Some((request, windows, _)) = waiting.as_ref() else {
+        return Report::Pending;
+    };
+    if !windows.contains(&window_id) {
+        return Report::Pending;
+    }
+    if !ready && require_saved {
+        let request = *request;
+        waiting.take();
+        return Report::Cancelled(request);
+    }
+    match finish_window(waiting, window_id) {
+        Some((request, completion)) => Report::Complete(request, completion),
+        None => Report::Pending,
+    }
+}
+
+pub(super) fn expire<C>(
+    waiting: &mut Option<(u64, HashSet<WindowId>, C)>,
+    request: u64,
+) -> Option<(u64, C)> {
+    if waiting.as_ref().is_some_and(|(id, _, _)| *id == request) {
+        waiting.take().map(|(id, _, completion)| (id, completion))
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn pending() -> Option<(u64, HashSet<WindowId>, i32)> {
+        Some((7, [11, 12].into(), 42))
+    }
+
+    #[test]
+    fn acknowledgements_complete_only_after_last_window() {
+        let mut waiting = pending();
+        assert!(matches!(
+            report(&mut waiting, 11, true, false),
+            Report::Pending
+        ));
+        assert!(matches!(
+            report(&mut waiting, 12, true, false),
+            Report::Complete(7, 42)
+        ));
+        assert!(waiting.is_none());
+        assert!(matches!(
+            report(&mut waiting, 12, true, false),
+            Report::Pending
+        ));
+    }
+
+    #[test]
+    fn destruction_completes_only_after_last_pending_window() {
+        let mut waiting = pending();
+        assert!(matches!(
+            destroyed(&mut waiting, 99, false),
+            Report::Pending
+        ));
+        assert!(matches!(
+            destroyed(&mut waiting, 12, false),
+            Report::Pending
+        ));
+        assert!(matches!(
+            destroyed(&mut waiting, 12, false),
+            Report::Pending
+        ));
+        assert!(matches!(
+            destroyed(&mut waiting, 11, false),
+            Report::Complete(7, 42)
+        ));
+    }
+
+    #[test]
+    fn cancellation_does_not_produce_completion() {
+        let mut waiting: Option<(u64, HashSet<WindowId>, i32)> = None;
+        assert!(matches!(
+            destroyed(&mut waiting, 11, false),
+            Report::Pending
+        ));
+    }
+    #[test]
+    fn failed_save_cannot_veto_user_exit() {
+        let mut waiting = pending();
+        assert!(matches!(
+            report(&mut waiting, 11, false, false),
+            Report::Pending
+        ));
+        assert!(matches!(
+            report(&mut waiting, 12, false, false),
+            Report::Complete(7, 42)
+        ));
+        assert!(waiting.is_none());
+    }
+
+    #[test]
+    fn updater_still_requires_durable_documents() {
+        let mut waiting = pending();
+        assert!(matches!(
+            report(&mut waiting, 11, false, true),
+            Report::Cancelled(7)
+        ));
+        assert!(waiting.is_none());
+    }
+
+    #[test]
+    fn destroyed_updater_participant_cancels_instead_of_approving_update() {
+        let mut waiting = pending();
+        assert!(matches!(
+            destroyed(&mut waiting, 11, true),
+            Report::Cancelled(7)
+        ));
+        assert!(waiting.is_none());
+    }
+
+    #[test]
+    fn stale_timeout_cannot_end_new_request() {
+        let mut waiting = pending();
+        assert_eq!(expire(&mut waiting, 6), None);
+        assert!(waiting.is_some());
+        assert_eq!(expire(&mut waiting, 7), Some((7, 42)));
+        assert_eq!(expire(&mut waiting, 7), None);
+    }
+
+    #[test]
+    fn unregistered_report_cannot_cancel_update() {
+        let mut waiting = pending();
+        assert!(matches!(
+            report(&mut waiting, 99, false, true),
+            Report::Pending
+        ));
+        assert!(waiting.is_some());
+    }
+
+    #[test]
+    fn repeated_user_exit_keeps_original_save_request_pending() {
+        let mut waiting = Some((7, [11].into(), true));
+        assert!(matches!(
+            prepare_user_exit(&mut waiting, |is_exit| *is_exit),
+            ExitRequest::AlreadyPending
+        ));
+        assert_eq!(waiting, Some((7, [11].into(), true)));
+    }
+
+    #[test]
+    fn user_exit_supersedes_updater_request_without_losing_its_identity() {
+        let mut waiting = Some((7, [11].into(), false));
+        match prepare_user_exit(&mut waiting, |is_exit| *is_exit) {
+            ExitRequest::Start { cancelled } => {
+                assert_eq!(cancelled, Some((7, false)))
+            }
+            ExitRequest::AlreadyPending => panic!("updater request should be superseded"),
+        }
+        assert!(waiting.is_none());
+    }
+}
diff --git a/app/flowix-desktop/src/config/access.rs b/app/flowix-desktop/src/config/access.rs
deleted file mode 100644
index 4dbbf862d..000000000
--- a/app/flowix-desktop/src/config/access.rs
+++ /dev/null
@@ -1,420 +0,0 @@
-use std::path::{Path, PathBuf};
-use std::sync::RwLock;
-
-use flowix_core::memo_file::{MemoFile, NotebookConfig};
-use serde::{Deserialize, Serialize};
-
-use crate::config::user::{atomic_write_json, UserConfigError};
-
-pub const AGENT_ACCESS_FILE_NAME: &str = "agent-access.json";
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "lowercase")]
-pub enum AgentAccessKind {
-    Notebook,
-    Folder,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentAccessEntry {
-    pub id: String,
-    pub kind: AgentAccessKind,
-    pub path: String,
-    pub name: String,
-    pub enabled: bool,
-    /// Legacy field; notebook workspace ownership now lives in `.flowix`.
-    #[serde(default, skip_serializing)]
-    pub workspace: bool,
-    pub added_at: i64,
-    pub updated_at: i64,
-    #[serde(default, skip_deserializing)]
-    pub missing: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AgentAccessConfig {
-    pub version: u32,
-    #[serde(default)]
-    pub entries: Vec<AgentAccessEntry>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub defaults: Option<serde_json::Value>,
-}
-
-impl Default for AgentAccessConfig {
-    fn default() -> Self {
-        Self {
-            version: 1,
-            entries: Vec::new(),
-            defaults: None,
-        }
-    }
-}
-
-pub struct AgentAccessStore {
-    config_dir: PathBuf,
-    inner: RwLock<AgentAccessConfig>,
-}
-
-impl AgentAccessStore {
-    pub fn new(config_dir: PathBuf, memo_file: &MemoFile) -> Self {
-        let mut config: AgentAccessConfig = read_from_disk(&config_dir)
-            .ok()
-            .flatten()
-            .unwrap_or_default();
-
-        match config.version {
-            1 => {}
-            other => tracing::warn!(
-                "agent-access.json version {} is unknown, treating as v1",
-                other
-            ),
-        }
-
-        let notebook_configs = memo_file.read_notebook_configs().unwrap_or_default();
-        let pre_reconcile_entries = config.entries.clone();
-        reconcile_with_notebook_configs(&mut config.entries, &notebook_configs);
-        let is_dirty = !entries_semantically_equal(&pre_reconcile_entries, &config.entries);
-
-        let store = Self {
-            config_dir,
-            inner: RwLock::new(config),
-        };
-        if is_dirty {
-            if let Err(e) = store.persist() {
-                tracing::warn!("failed to persist agent_access on startup: {e}");
-            } else {
-                tracing::debug!(
-                    "agent_access reconciled on startup; entries count changed: {} -> {}",
-                    pre_reconcile_entries.len(),
-                    store.get_config().entries.len(),
-                );
-            }
-        }
-        store
-    }
-
-    pub fn get_config(&self) -> AgentAccessConfig {
-        let guard = self.inner.read().unwrap_or_else(|p| p.into_inner());
-        let mut config = guard.clone();
-        refresh_missing_flags(&mut config.entries);
-        config
-    }
-
-    pub fn replace_config(
-        &self,
-        mut config: AgentAccessConfig,
-    ) -> Result<AgentAccessConfig, UserConfigError> {
-        // `missing` is derived from disk and must never trust a stale Webview
-        // snapshot. Recompute before both persistence and the in-memory swap.
-        refresh_missing_flags(&mut config.entries);
-        let content = serde_json::to_string_pretty(&config)?;
-        let path = self.config_dir.join(AGENT_ACCESS_FILE_NAME);
-        atomic_write_json(&path, &content)?;
-        let mut guard = self.inner.write().unwrap_or_else(|p| p.into_inner());
-        *guard = config.clone();
-        Ok(config)
-    }
-
-    pub fn add_or_update_notebook(&self, nb: &NotebookConfig) -> bool {
-        let now = chrono::Utc::now().timestamp_millis();
-        let trimmed_path = trim_path(&nb.path);
-        let mut guard = self.inner.write().unwrap_or_else(|p| p.into_inner());
-        let mut changed = false;
-
-        match guard
-            .entries
-            .iter_mut()
-            .find(|e| e.kind == AgentAccessKind::Notebook && e.id == nb.id)
-        {
-            Some(entry) => {
-                if entry.path != trimmed_path || entry.name != nb.name {
-                    entry.path = trimmed_path;
-                    entry.name = nb.name.clone();
-                    entry.updated_at = now;
-                    changed = true;
-                }
-            }
-            None => {
-                guard.entries.push(AgentAccessEntry {
-                    id: nb.id.clone(),
-                    kind: AgentAccessKind::Notebook,
-                    path: trimmed_path,
-                    name: nb.name.clone(),
-                    enabled: true,
-                    workspace: false,
-                    added_at: now,
-                    updated_at: now,
-                    missing: false,
-                });
-                changed = true;
-            }
-        }
-
-        if changed {
-            let _ = self.persist_locked(&guard);
-        }
-        changed
-    }
-
-    pub fn remove_notebook(&self, notebook_id: &str) -> bool {
-        let mut guard = self.inner.write().unwrap_or_else(|p| p.into_inner());
-        let before = guard.entries.len();
-        guard
-            .entries
-            .retain(|e| !(e.kind == AgentAccessKind::Notebook && e.id == notebook_id));
-        let removed = guard.entries.len() != before;
-        if removed {
-            let _ = self.persist_locked(&guard);
-        }
-        removed
-    }
-
-    fn persist(&self) -> Result<(), UserConfigError> {
-        let guard = self.inner.read().unwrap_or_else(|p| p.into_inner());
-        self.persist_locked(&guard)
-    }
-
-    fn persist_locked(&self, config: &AgentAccessConfig) -> Result<(), UserConfigError> {
-        let content = serde_json::to_string_pretty(config)?;
-        let path = self.config_dir.join(AGENT_ACCESS_FILE_NAME);
-        Ok(atomic_write_json(&path, &content)?)
-    }
-}
-
-fn read_from_disk(config_dir: &Path) -> std::io::Result<Option<AgentAccessConfig>> {
-    let path = config_dir.join(AGENT_ACCESS_FILE_NAME);
-    if !path.exists() {
-        return Ok(None);
-    }
-    let content = std::fs::read_to_string(&path)?;
-    if content.trim().is_empty() {
-        return Ok(None);
-    }
-    let cfg: AgentAccessConfig = serde_json::from_str(&content).unwrap_or_default();
-    Ok(Some(cfg))
-}
-
-fn reconcile_with_notebook_configs(
-    entries: &mut Vec<AgentAccessEntry>,
-    notebooks: &[NotebookConfig],
-) {
-    let now = chrono::Utc::now().timestamp_millis();
-    let registry_ids: std::collections::HashSet<&str> =
-        notebooks.iter().map(|n| n.id.as_str()).collect();
-
-    entries.retain(|e| {
-        !(e.kind == AgentAccessKind::Notebook && !registry_ids.contains(e.id.as_str()))
-    });
-
-    for nb in notebooks {
-        let trimmed_path = trim_path(&nb.path);
-        match entries
-            .iter_mut()
-            .find(|e| e.kind == AgentAccessKind::Notebook && e.id == nb.id)
-        {
-            Some(entry) => {
-                if entry.path != trimmed_path {
-                    entry.path = trimmed_path.clone();
-                    entry.updated_at = now;
-                }
-                if entry.name != nb.name {
-                    entry.name = nb.name.clone();
-                    entry.updated_at = now;
-                }
-            }
-            None => {
-                entries.push(AgentAccessEntry {
-                    id: nb.id.clone(),
-                    kind: AgentAccessKind::Notebook,
-                    path: trimmed_path,
-                    name: nb.name.clone(),
-                    enabled: true,
-                    workspace: false,
-                    added_at: now,
-                    updated_at: now,
-                    missing: false,
-                });
-            }
-        }
-    }
-}
-
-fn entries_semantically_equal(a: &[AgentAccessEntry], b: &[AgentAccessEntry]) -> bool {
-    if a.len() != b.len() {
-        return false;
-    }
-    a.iter().zip(b.iter()).all(|(x, y)| {
-        x.id == y.id
-            && x.kind == y.kind
-            && x.path == y.path
-            && x.name == y.name
-            && x.enabled == y.enabled
-    })
-}
-
-fn trim_path(path: &str) -> String {
-    path.trim_end_matches(|c| c == '/' || c == '\\').to_string()
-}
-
-fn refresh_missing_flags(entries: &mut [AgentAccessEntry]) {
-    for entry in entries {
-        entry.missing = !Path::new(&entry.path).is_dir();
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn nb(id: &str, name: &str, path: &str) -> NotebookConfig {
-        NotebookConfig {
-            id: id.to_string(),
-            name: name.to_string(),
-            icon: Some("馃摌".to_string()),
-            path: path.to_string(),
-            is_default: false,
-            sort: 0,
-            created_at: 0,
-            updated_at: 0,
-        }
-    }
-
-    fn entry(
-        id: &str,
-        kind: AgentAccessKind,
-        path: &str,
-        name: &str,
-        enabled: bool,
-        updated_at: i64,
-    ) -> AgentAccessEntry {
-        AgentAccessEntry {
-            id: id.to_string(),
-            kind,
-            path: path.to_string(),
-            name: name.to_string(),
-            enabled,
-            workspace: false,
-            added_at: 1,
-            updated_at,
-            missing: false,
-        }
-    }
-
-    #[test]
-    fn seed_populates_from_notebook_configs() {
-        let mut entries = Vec::new();
-        let notebooks = vec![
-            nb("nb_1", "First", "/tmp/a/"),
-            nb("nb_2", "Second", "/tmp/b/"),
-        ];
-
-        reconcile_with_notebook_configs(&mut entries, &notebooks);
-
-        assert_eq!(entries.len(), 2);
-        assert_eq!(entries[0].path, "/tmp/a");
-        assert!(entries.iter().all(|entry| entry.enabled));
-    }
-
-    #[test]
-    fn reconcile_removes_deleted_notebooks() {
-        let mut entries = vec![
-            entry("nb_1", AgentAccessKind::Notebook, "/a", "A", true, 1),
-            entry("nb_2", AgentAccessKind::Notebook, "/b", "B", true, 1),
-            entry("fld_1", AgentAccessKind::Folder, "/c", "C", true, 1),
-        ];
-        let notebooks = vec![nb("nb_1", "A", "/a")];
-
-        reconcile_with_notebook_configs(&mut entries, &notebooks);
-
-        assert_eq!(entries.len(), 2);
-        assert!(entries.iter().any(|entry| entry.id == "nb_1"));
-        assert!(entries.iter().any(|entry| entry.id == "fld_1"));
-    }
-
-    #[test]
-    fn entries_semantically_equal_ignores_updated_at_and_workspace() {
-        let a = vec![entry(
-            "nb_1",
-            AgentAccessKind::Notebook,
-            "/a",
-            "A",
-            true,
-            100,
-        )];
-        let mut b = a.clone();
-        b[0].updated_at = 200;
-        b[0].workspace = true;
-
-        assert!(entries_semantically_equal(&a, &b));
-    }
-
-    #[test]
-    fn entries_semantically_equal_detects_path_and_enabled_changes() {
-        let a = vec![entry(
-            "nb_1",
-            AgentAccessKind::Notebook,
-            "/old",
-            "A",
-            true,
-            100,
-        )];
-        let mut b = a.clone();
-        b[0].path = "/new".to_string();
-        assert!(!entries_semantically_equal(&a, &b));
-
-        let mut c = a.clone();
-        c[0].enabled = false;
-        assert!(!entries_semantically_equal(&a, &c));
-    }
-
-    #[test]
-    fn config_defaults_round_trip_shape() {
-        let defaults = serde_json::json!({
-            "runtime": { "deepseek-harness": { "model": "gpt-5" } },
-            "files": { "workspacePaths": ["/tmp"] }
-        });
-        let cfg = AgentAccessConfig {
-            version: 1,
-            entries: Vec::new(),
-            defaults: Some(defaults.clone()),
-        };
-
-        let encoded = serde_json::to_string(&cfg).unwrap();
-        let decoded: AgentAccessConfig = serde_json::from_str(&encoded).unwrap();
-
-        assert_eq!(decoded.defaults, Some(defaults));
-    }
-
-    #[test]
-    fn refresh_missing_flags_tracks_directories_on_disk() {
-        let temp = tempfile::tempdir().unwrap();
-        let present = temp.path().join("present");
-        std::fs::create_dir_all(&present).unwrap();
-        let absent = temp.path().join("absent");
-        let mut entries = vec![
-            entry(
-                "present",
-                AgentAccessKind::Folder,
-                &present.to_string_lossy(),
-                "Present",
-                true,
-                1,
-            ),
-            entry(
-                "absent",
-                AgentAccessKind::Folder,
-                &absent.to_string_lossy(),
-                "Absent",
-                true,
-                1,
-            ),
-        ];
-
-        refresh_missing_flags(&mut entries);
-
-        assert!(!entries[0].missing);
-        assert!(entries[1].missing);
-    }
-}
diff --git a/app/flowix-desktop/src/config/mod.rs b/app/flowix-desktop/src/config/mod.rs
index d4c2a557e..1e2e7cb45 100644
--- a/app/flowix-desktop/src/config/mod.rs
+++ b/app/flowix-desktop/src/config/mod.rs
@@ -1,43 +1,20 @@
-//! Configuration & access-control layer for the agent runtime.
+//! Configuration and access-control layer for the agent runtime.
 //!
-//! Four closely related concerns live here:
-//!
-//! - [`user`] 鈥?user-level settings: legacy AI migration data, preferences
-//!   (json), theme, agent persona. Legacy data is persisted at
-//!   `~/.flowix/agent-config.toml`; active DSH settings use its own YAML file.
-//!   Owns the `atomic_write_json`
-//!   helper used by sibling stores.
-//! - [`access`] 鈥?agent-access registry: which folders + notebooks the AI
-//!   agent is allowed to see. Persisted at `~/.flowix/agent-access.json`.
-//!   Distinct from the notebook registry so users can grant/revoke AI access
-//!   without touching the notebook registry itself.
-//! - [`path_scope`] 鈥?tiny pure helper: is `path` inside `root`? Used by
-//!   access checks, dialog code, and security-bookmark filtering.
-//! - [`security_bookmark`] 鈥?macOS security-scoped bookmarks for
-//!   user-selected directories that survive across launches. Sibling of
-//!   `user`/`access` but only meaningful on macOS; on other platforms the
-//!   store is still constructed but never gains entries.
-//!
-//! All four write through `user::atomic_write_json` so disk failures never
-//! leave the in-memory state ahead of disk.
+//! `user` stores user-level preferences; `db/local.db` stores notebook mounts,
+//! and `path_scope` provides the shared path containment checks.
 
-pub mod access;
 pub mod path_scope;
 pub mod property_presets;
 pub mod security_bookmark;
 pub mod user;
 
-// Re-export the public surface at the `config::` namespace so callers can
-// write `crate::config::UserConfigStore` without dropping into `user`.
-pub use access::{AgentAccessConfig, AgentAccessEntry, AgentAccessKind, AgentAccessStore};
 pub use path_scope::{path_is_inside, path_is_inside_reserved_directory};
 pub use property_presets::{PropertyPresetChange, PropertyPresetRegistry, PropertyPresetStore};
-#[cfg(target_os = "macos")]
-pub use security_bookmark::pick_directory_with_bookmark;
 pub use security_bookmark::SecurityBookmarkStore;
 pub use user::{
-    dsh_credential_ref_for_route, AiConfigFile, AiModelConfig, AiModelEntry, PreferenceFile, Theme,
-    UserConfigError, UserConfigStore, DSH_SETTINGS_FILE_NAME,
+    dsh_credential_ref_for_route, AiConfigFile, AiModelConfig, AiModelEntry,
+    CloudDevRefreshTokenStore, PreferenceFile, Theme, UserConfigError, UserConfigStore,
+    DSH_SETTINGS_FILE_NAME,
 };
 pub(crate) use user::{
     merge_harness_provider, DeepSeekHarnessProviderSettings, DeepSeekHarnessSettingsFile,
diff --git a/app/flowix-desktop/src/config/property_presets.rs b/app/flowix-desktop/src/config/property_presets.rs
index 48d61178d..572fd4ac1 100644
--- a/app/flowix-desktop/src/config/property_presets.rs
+++ b/app/flowix-desktop/src/config/property_presets.rs
@@ -149,7 +149,7 @@ impl PropertyPresetStore {
         if let Some(parent) = self.path.parent() {
             std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
         }
-        let mut connection = Connection::open(&self.path).map_err(|error| error.to_string())?;
+        let connection = Connection::open(&self.path).map_err(|error| error.to_string())?;
         connection
             .busy_timeout(Duration::from_secs(10))
             .map_err(|error| error.to_string())?;
@@ -158,8 +158,8 @@ impl PropertyPresetStore {
                 "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA foreign_keys=ON;",
             )
             .map_err(|error| error.to_string())?;
-        migrate_legacy_schema(&mut connection)?;
-        connection.execute_batch(
+        let migration_connection = connection;
+        migration_connection.execute_batch(
             "CREATE TABLE IF NOT EXISTS property_presets (
                 scope TEXT NOT NULL CHECK(scope IN ('system', 'user', 'deleted_user')),
                 id TEXT NOT NULL,
@@ -188,25 +188,30 @@ impl PropertyPresetStore {
                 completed_at INTEGER NOT NULL
              );",
         ).map_err(|error| error.to_string())?;
-        let has_position = {
-            let mut statement = connection
-                .prepare("PRAGMA table_info(property_presets)")
-                .map_err(|error| error.to_string())?;
-            let columns = statement
-                .query_map([], |row| row.get::<_, String>(1))
-                .map_err(|error| error.to_string())?
-                .collect::<Result<Vec<_>, _>>()
-                .map_err(|error| error.to_string())?;
-            columns.iter().any(|column| column == "position")
-        };
-        if !has_position {
-            connection
-                .execute_batch(
-                    "ALTER TABLE property_presets ADD COLUMN position INTEGER NOT NULL DEFAULT 0",
-                )
-                .map_err(|error| error.to_string())?;
+        Ok(migration_connection)
+    }
+
+    /// Apply legacy SQLite shape changes from the explicit startup
+    /// initialization phase. Normal reads only open the current schema.
+    pub fn initialize_legacy_schema(&self) -> Result<(), String> {
+        if let Some(parent) = self.path.parent() {
+            std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
         }
-        Ok(connection)
+        let mut connection = Connection::open(&self.path).map_err(|error| error.to_string())?;
+        connection
+            .busy_timeout(Duration::from_secs(10))
+            .map_err(|error| error.to_string())?;
+        connection
+            .execute_batch(
+                "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA foreign_keys=ON;",
+            )
+            .map_err(|error| error.to_string())?;
+        flowix_core::memo_file::initialize_local_migration_table(&mut connection)
+            .map_err(|error| error.to_string())?;
+        migrate_legacy_schema(&mut connection)?;
+        drop(connection);
+        let _ = self.open()?;
+        Ok(())
     }
 
     pub fn get(&self) -> Result<PropertyPresetRegistry, String> {
@@ -405,8 +410,6 @@ impl PropertyPresetStore {
             if change.field.key.trim().is_empty()
                 || [
                     "flowix_property_types",
-                    "flowix_key",
-                    "key",
                     "flowix_plugin",
                 ]
                 .contains(&change.field.key.as_str())
@@ -471,6 +474,7 @@ impl PropertyPresetStore {
     /// Import the former preference.json registry once. Existing DB data wins.
     /// The marker and imported rows are committed atomically.
     pub fn migrate_legacy_once(&self, registry: &PropertyPresetRegistry) -> Result<bool, String> {
+        self.initialize_legacy_schema()?;
         let mut connection = self.open()?;
         let transaction = connection
             .transaction_with_behavior(TransactionBehavior::Immediate)
diff --git a/app/flowix-desktop/src/config/security_bookmark.rs b/app/flowix-desktop/src/config/security_bookmark.rs
index 37c01ee94..7a3858afc 100644
--- a/app/flowix-desktop/src/config/security_bookmark.rs
+++ b/app/flowix-desktop/src/config/security_bookmark.rs
@@ -1,7 +1,7 @@
-//! macOS security-scoped bookmarks for user-selected directories.
+//! macOS security-scoped bookmarks for authorized directories and selected files.
 //!
-//! The app stores bookmark data separately from notebook / agent-access config
-//! because both features can point at the same directory.
+//! OS grants are persisted separately from Flowix notebook and document grants.
+//! A file bookmark never authorizes its parent directory.
 
 use std::collections::BTreeMap;
 use std::io;
@@ -13,7 +13,14 @@ use serde::{Deserialize, Serialize};
 use crate::config::user::{atomic_write_json, UserConfigError};
 
 const BOOT_DIR_NAME: &str = "boot";
-const BOOKMARKS_FILE_NAME: &str = "security-bookmarks.json";
+
+fn bookmarks_file_name() -> &'static str {
+    if option_env!("FLOWIX_DEV_MODE") == Some("1") {
+        "bookmark.dev.json"
+    } else {
+        "bookmark.json"
+    }
+}
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -21,9 +28,11 @@ struct BookmarkEntry {
     path: String,
     bookmark: String,
     updated_at: i64,
+    #[serde(default = "directory_default")]
+    directory: bool,
 }
 
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 struct BookmarkConfig {
     #[serde(default = "default_version")]
@@ -32,14 +41,33 @@ struct BookmarkConfig {
     entries: BTreeMap<String, BookmarkEntry>,
 }
 
+impl Default for BookmarkConfig {
+    fn default() -> Self {
+        Self {
+            version: 1,
+            entries: BTreeMap::new(),
+        }
+    }
+}
+
+fn directory_default() -> bool {
+    true
+}
+
 fn default_version() -> u32 {
     1
 }
 
 fn normalize_path(path: &Path) -> String {
-    path.to_string_lossy()
-        .trim_end_matches(|c| c == '/' || c == '\\')
-        .to_string()
+    let path = dunce::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
+    let normalized = path.to_string_lossy().to_string();
+    if normalized.len() > 1 {
+        normalized
+            .trim_end_matches(|c| c == '/' || c == '\\')
+            .to_string()
+    } else {
+        normalized
+    }
 }
 
 pub struct SecurityBookmarkStore {
@@ -56,7 +84,6 @@ impl SecurityBookmarkStore {
             .ok()
             .flatten()
             .unwrap_or_default();
-        migrate_legacy_bookmarks_if_needed(&config_dir, &config);
         let store = Self {
             config_dir,
             inner: RwLock::new(config),
@@ -86,12 +113,82 @@ impl SecurityBookmarkStore {
         Ok(())
     }
 
+    pub fn record_file(&self, path: &Path) -> Result<(), UserConfigError> {
+        #[cfg(target_os = "macos")]
+        {
+            let url = objc2_foundation::NSURL::from_file_path(path).ok_or_else(|| {
+                io::Error::new(io::ErrorKind::InvalidInput, "invalid selected file URL")
+            })?;
+            let bookmark = macos::bookmark_for_url(&url).ok_or_else(|| {
+                io::Error::new(
+                    io::ErrorKind::PermissionDenied,
+                    "cannot bookmark selected file",
+                )
+            })?;
+            self.upsert(path, bookmark, false)?;
+            self.start_accessing_path(path);
+        }
+        #[cfg(not(target_os = "macos"))]
+        let _ = path;
+        Ok(())
+    }
+
+    /// Called only for a directory already authorized by Flowix. Successful
+    /// enumeration means macOS has allowed access (including a TCC prompt).
+    pub fn record_accessible_directory(&self, path: &Path) {
+        #[cfg(target_os = "macos")]
+        {
+            if self.start_accessing_for_path(path) {
+                return;
+            }
+            if std::fs::read_dir(path).is_ok() {
+                if let Err(error) = self.record_directory(path) {
+                    tracing::warn!(%error, path = %path.display(), "cannot persist granted directory access");
+                }
+            }
+        }
+        #[cfg(not(target_os = "macos"))]
+        let _ = path;
+    }
+
+    #[cfg(target_os = "macos")]
+    fn refresh_stale(&self, old_path: &str, directory: bool, access: &macos::ScopedAccess) {
+        if !access.is_stale() {
+            return;
+        }
+        let Some(bookmark) = access.refreshed_bookmark() else {
+            return;
+        };
+        let mut current = self.inner.write().unwrap_or_else(|p| p.into_inner());
+        let mut next = current.clone();
+        next.entries.remove(old_path);
+        let path = access.path_key().to_string();
+        next.entries.insert(
+            path.clone(),
+            BookmarkEntry {
+                path,
+                bookmark,
+                directory,
+                updated_at: chrono::Utc::now().timestamp_millis(),
+            },
+        );
+        match serde_json::to_string_pretty(&next) {
+            Ok(content) => {
+                match atomic_write_json(&bookmarks_file_path(&self.config_dir), &content) {
+                    Ok(()) => *current = next,
+                    Err(error) => tracing::warn!(%error, "cannot refresh stale bookmark"),
+                }
+            }
+            Err(error) => tracing::warn!(%error, "cannot serialize refreshed bookmark"),
+        }
+    }
+
     pub fn record_directory_bookmark(
         &self,
         path: &Path,
         bookmark: String,
     ) -> Result<(), UserConfigError> {
-        self.upsert(path, bookmark)?;
+        self.upsert(path, bookmark, true)?;
         self.start_accessing_path(path);
         Ok(())
     }
@@ -111,7 +208,10 @@ impl SecurityBookmarkStore {
             active.clear();
             for entry in entries {
                 match macos::resolve_bookmark(&entry.bookmark) {
-                    Some(access) => active.push(access),
+                    Some(access) => {
+                        self.refresh_stale(&entry.path, entry.directory, &access);
+                        active.push(access);
+                    }
                     None => tracing::warn!(
                         "[security_bookmark] failed to resolve bookmark for {}",
                         entry.path
@@ -158,10 +258,27 @@ impl SecurityBookmarkStore {
 
     #[cfg(target_os = "macos")]
     fn activate_bookmark(&self, key: String, bookmark: String, requested_path: &Path) -> bool {
+        if self
+            .active
+            .read()
+            .is_ok_and(|active| active.iter().any(|existing| existing.path_key() == key))
+        {
+            return true;
+        }
         if let Some(access) = macos::resolve_bookmark(&bookmark) {
+            let directory = self
+                .inner
+                .read()
+                .unwrap_or_else(|p| p.into_inner())
+                .entries
+                .get(&key)
+                .map(|entry| entry.directory)
+                .unwrap_or(true);
+            self.refresh_stale(&key, directory, &access);
             let mut active = self.active.write().unwrap_or_else(|p| p.into_inner());
-            active.retain(|existing| existing.path_key() != key);
-            active.push(access);
+            if !active.iter().any(|existing| existing.path_key() == key) {
+                active.push(access);
+            }
             return true;
         }
         tracing::warn!(
@@ -179,64 +296,48 @@ impl SecurityBookmarkStore {
             .unwrap_or_else(|p| p.into_inner())
             .entries
             .iter()
-            .filter(|(_, entry)| super::path_scope::path_is_inside(path, Path::new(&entry.path)))
+            .filter(|(_, entry)| {
+                if entry.directory {
+                    super::path_scope::path_is_inside(path, Path::new(&entry.path))
+                } else {
+                    normalize_path(path) == entry.path
+                }
+            })
             .max_by_key(|(key, _)| key.len())
             .map(|(key, entry)| (key.clone(), entry.bookmark.clone()))
     }
 
-    fn upsert(&self, path: &Path, bookmark: String) -> Result<(), UserConfigError> {
+    fn upsert(
+        &self,
+        path: &Path,
+        bookmark: String,
+        directory: bool,
+    ) -> Result<(), UserConfigError> {
         let key = normalize_path(path);
-        let mut next = self.inner.read().unwrap_or_else(|p| p.into_inner()).clone();
+        let mut current = self.inner.write().unwrap_or_else(|p| p.into_inner());
+        let mut next = current.clone();
         next.entries.insert(
             key,
             BookmarkEntry {
                 path: normalize_path(path),
                 bookmark,
                 updated_at: chrono::Utc::now().timestamp_millis(),
+                directory,
             },
         );
         let content = serde_json::to_string_pretty(&next)?;
         atomic_write_json(&bookmarks_file_path(&self.config_dir), &content)?;
-        *self.inner.write().unwrap_or_else(|p| p.into_inner()) = next;
+        *current = next;
         Ok(())
     }
 }
 
 fn bookmarks_file_path(config_dir: &Path) -> PathBuf {
-    config_dir.join(BOOT_DIR_NAME).join(BOOKMARKS_FILE_NAME)
-}
-
-fn legacy_bookmarks_file_path(config_dir: &Path) -> PathBuf {
-    config_dir.join(BOOKMARKS_FILE_NAME)
-}
-
-fn migrate_legacy_bookmarks_if_needed(config_dir: &Path, config: &BookmarkConfig) {
-    let path = bookmarks_file_path(config_dir);
-    if path.exists() || !legacy_bookmarks_file_path(config_dir).exists() {
-        return;
-    }
-    match serde_json::to_string_pretty(config) {
-        Ok(content) => {
-            if let Err(e) = atomic_write_json(&path, &content) {
-                tracing::warn!(
-                    "[security_bookmark] failed to migrate bookmarks to {}: {e}",
-                    path.display()
-                );
-            }
-        }
-        Err(e) => tracing::warn!("[security_bookmark] failed to serialize bookmarks: {e}"),
-    }
+    config_dir.join(BOOT_DIR_NAME).join(bookmarks_file_name())
 }
 
 fn read_from_disk(config_dir: &Path) -> std::io::Result<Option<BookmarkConfig>> {
-    let path = bookmarks_file_path(config_dir);
-    if !path.exists() {
-        let legacy_path = legacy_bookmarks_file_path(config_dir);
-        if legacy_path.exists() {
-            return read_bookmark_config_file(&legacy_path);
-        }
-    }
-    read_bookmark_config_file(&path)
+    read_bookmark_config_file(&bookmarks_file_path(config_dir))
 }
 
 fn read_bookmark_config_file(path: &Path) -> std::io::Result<Option<BookmarkConfig>> {
@@ -266,12 +367,21 @@ mod macos {
         url: Retained<NSURL>,
         path_key: String,
         active: bool,
+        stale: bool,
     }
 
     impl ScopedAccess {
         pub fn path_key(&self) -> &str {
             &self.path_key
         }
+
+        pub fn refreshed_bookmark(&self) -> Option<String> {
+            bookmark_for_url(&self.url)
+        }
+
+        pub fn is_stale(&self) -> bool {
+            self.stale
+        }
     }
 
     impl Drop for ScopedAccess {
@@ -284,6 +394,10 @@ mod macos {
 
     pub fn bookmark_for_directory(path: &Path) -> Option<String> {
         let url = NSURL::from_directory_path(path)?;
+        bookmark_for_url(&url)
+    }
+
+    pub fn bookmark_for_url(url: &NSURL) -> Option<String> {
         let data = url
             .bookmarkDataWithOptions_includingResourceValuesForKeys_relativeToURL_error(
                 NSURLBookmarkCreationOptions::WithSecurityScope,
@@ -292,8 +406,8 @@ mod macos {
             )
             .map_err(|e| {
                 tracing::warn!(
-                    "[security_bookmark] failed to create bookmark for {}: {:?}",
-                    path.display(),
+                    "[security_bookmark] failed to create bookmark for {:?}: {:?}",
+                    url,
                     e
                 );
             })
@@ -323,38 +437,20 @@ mod macos {
             tracing::warn!("[security_bookmark] resolved stale bookmark");
         }
         let active = unsafe { url.startAccessingSecurityScopedResource() };
+        if !active {
+            tracing::warn!("[security_bookmark] macOS refused scoped access for resolved bookmark");
+            return None;
+        }
         let path = url.to_file_path().unwrap_or_else(PathBuf::new);
         Some(ScopedAccess {
             path_key: normalize_path(&path),
             url,
             active,
+            stale: stale.as_bool(),
         })
     }
 }
 
-#[cfg(target_os = "macos")]
-pub fn pick_directory_with_bookmark(title: &str) -> Option<(String, String)> {
-    use objc2::MainThreadMarker;
-    use objc2_app_kit::{NSModalResponseOK, NSOpenPanel};
-
-    let mtm = MainThreadMarker::new()?;
-    let panel = NSOpenPanel::openPanel(mtm);
-    panel.setCanChooseDirectories(true);
-    panel.setCanChooseFiles(false);
-    panel.setCanCreateDirectories(true);
-    panel.setAllowsMultipleSelection(false);
-    let title = objc2_foundation::NSString::from_str(title);
-    panel.setTitle(Some(&title));
-    let ok = panel.runModal();
-    if ok != NSModalResponseOK {
-        return None;
-    }
-    let url = panel.URL()?;
-    let path = url.to_file_path()?;
-    let bookmark = macos::bookmark_for_directory(&path)?;
-    Some((path.to_string_lossy().to_string(), bookmark))
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -367,6 +463,7 @@ mod tests {
                 path: "/tmp/flowix-bookmark-test".to_string(),
                 bookmark: "bookmark-data".to_string(),
                 updated_at: 1,
+                directory: true,
             },
         );
         config
@@ -384,32 +481,4 @@ mod tests {
         assert_eq!(loaded.entries.len(), 1);
         assert!(loaded.entries.contains_key("/tmp/flowix-bookmark-test"));
     }
-
-    #[test]
-    fn migrates_legacy_bookmarks_to_boot_dir() {
-        let tmp = tempfile::tempdir().unwrap();
-        let config = sample_config();
-        let content = serde_json::to_string_pretty(&config).unwrap();
-        atomic_write_json(&legacy_bookmarks_file_path(tmp.path()), &content).unwrap();
-
-        migrate_legacy_bookmarks_if_needed(tmp.path(), &config);
-
-        assert!(bookmarks_file_path(tmp.path()).exists());
-        let migrated = read_bookmark_config_file(&bookmarks_file_path(tmp.path()))
-            .unwrap()
-            .unwrap();
-        assert_eq!(migrated.entries.len(), 1);
-    }
-
-    #[cfg(target_os = "macos")]
-    #[test]
-    fn macos_bookmark_round_trips() {
-        let tmp = tempfile::tempdir().unwrap();
-        let bookmark = macos::bookmark_for_directory(tmp.path())
-            .expect("a temporary directory should produce bookmark data");
-        let access = macos::resolve_bookmark(&bookmark)
-            .expect("newly created bookmark data should resolve immediately");
-        let canonical = std::fs::canonicalize(tmp.path()).unwrap();
-        assert_eq!(access.path_key(), normalize_path(&canonical));
-    }
 }
diff --git a/app/flowix-desktop/src/config/user.rs b/app/flowix-desktop/src/config/user.rs
index 2ab5934ec..187b6e6f0 100644
--- a/app/flowix-desktop/src/config/user.rs
+++ b/app/flowix-desktop/src/config/user.rs
@@ -3,21 +3,31 @@ use std::collections::{BTreeMap, HashMap};
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
-use std::sync::RwLock;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, RwLock};
 
+use super::property_presets::{PropertyPresetChange, PropertyPresetRegistry, PropertyPresetStore};
 use crate::USER_CONFIG_DIR_NAME;
 use flowix_core::secret::{entry_name, SecretStore};
-use super::property_presets::{PropertyPresetChange, PropertyPresetRegistry, PropertyPresetStore};
 
 /// AI 模型配置文件�?── TOML 格式, 便于人手编辑与注释�?///
 /// TOML 格式便于用户手改磁盘配置时写注释 (TOML 原生 `# ...`), 避免�?��字�?�?/// �?Flowix 的其它配�?���?(`boot/preference.json` /
-///    `boot/system.json` / `index.db`) 鍖哄垎寰楁洿鏄剧溂
+///    `boot/system.json` / `local.db`) 鍖哄垎寰楁洿鏄剧溂
 ///    (TOML 格式 + 显式 `agent-` 前缀, 不会出现"�?��文件该用 JSON"的�?�?
 pub const AI_CONFIG_FILE_NAME: &str = "agent-config.toml";
 /// DeepSeek Harness uses its official user-global home (`~/.dsh`). Flowix
 /// owns a profile below that home, but does not introduce a second harness
 /// root below `~/.flowix`.
 pub const DSH_DIR_NAME: &str = ".dsh";
+
+/// Resolve the official DSH home for both profile installation and runtime IO.
+pub(crate) fn resolve_dsh_home(home: &Path) -> PathBuf {
+    std::env::var_os("DSH_HOME")
+        .filter(|path| !path.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or_else(|| home.join(DSH_DIR_NAME))
+}
+
 pub const DSH_SESSIONS_DIR_NAME: &str = "sessions";
 pub const DSH_SETTINGS_FILE_NAME: &str = "settings.yaml";
 pub const DSH_PLUGIN_SETTINGS_FILE_NAME: &str = "plugin-settings.json";
@@ -27,6 +37,8 @@ const PREFERENCE_FILE_NAME: &str = "preference.json";
 const DEFAULT_SECRET_DB_NAME: &str = "default.db";
 const SECRET_ACCOUNT_NAME: &str = "default";
 const CLOUD_SECRET_PROVIDER: &str = "flowix_cloud_refresh";
+const CLOUD_DEV_STAGING_SECRET_PROVIDER: &str = "flowix_cloud_dev_staging_refresh";
+const CLOUD_DEV_PRODUCTION_SECRET_PROVIDER: &str = "flowix_cloud_dev_production_refresh";
 
 /// ~/.flowix/boot/preference.json —用户偏好设置
 /// 瀛楁鍏ㄩ儴 #[serde(default)], 鏂囦欢鎹熷潖鎴栫己澶辨椂鍥為€€鍒伴粯璁ゅ€笺€?
@@ -179,6 +191,13 @@ pub struct PreferenceFile {
     /// Installation region detected by the frontend on first launch.
     #[serde(default)]
     pub region: String,
+    /// Explicit path to the user's DSH CLI, when automatic discovery is insufficient.
+    #[serde(default)]
+    pub dsh_cli_path: Option<String>,
+    /// Saved Cloud target name for development builds. Unknown legacy values
+    /// fall back to the build default; release builds always use production.
+    #[serde(default)]
+    pub cloud_environment: String,
     /// Memo list card presentation ("detailed" | "compact").
     #[serde(default)]
     pub memo_card_variant: String,
@@ -219,6 +238,8 @@ impl Default for PreferenceFile {
             theme: Theme::default(),
             language: String::default(),
             region: String::default(),
+            dsh_cli_path: None,
+            cloud_environment: String::default(),
             memo_card_variant: String::default(),
             memo_list_view: String::default(),
             auto_open_created_notes_in_browser: true,
@@ -586,7 +607,7 @@ pub struct UserConfigStore {
     ai_config: RwLock<AiConfigFile>,
     secrets: SecretStore,
     property_presets: PropertyPresetStore,
-    property_presets_migration_complete: bool,
+    property_presets_migration_complete: Arc<AtomicBool>,
 }
 
 /// 用户配置 (boot/preference.json / agent-config.toml) 写盘错�?。`Io` �?���?/// `std::io::Error` �? `Json` �?`serde_json::Error` �?(preference.json
@@ -640,10 +661,11 @@ impl UserConfigStore {
     }
 
     pub fn new(home_dir: PathBuf) -> Self {
-        // 鍑嵁 db 钀藉湪 config_dir/default.db (鐢熶骇鐜 ~/.flowix/default.db),
-        // �?index.db 同目�?── �?0o700 �?�� + 0o600 文件权限保护�?
+        // 凭据数据库位于 config_dir/db/default.db (生产环境 ~/.flowix/db/default.db),
+        // �?local.db 同目�?── �?0o700 �?�� + 0o600 文件权限保护�?
         let db_path = home_dir
             .join(USER_CONFIG_DIR_NAME)
+            .join("db")
             .join(DEFAULT_SECRET_DB_NAME);
         Self::new_with_secret_store(home_dir, SecretStore::new(db_path))
     }
@@ -653,39 +675,19 @@ impl UserConfigStore {
         let _ = fs::create_dir_all(&config_dir);
         // Restrict the configuration directory to its owner.
         set_dir_owner_only_perms(&config_dir);
-        migrate_dsh_layout(&config_dir);
-
-        let mut preference = Self::read_preference_from_disk(&config_dir).unwrap_or_default();
-        let had_legacy_property_registry = !preference.properties.system_fields.is_empty()
-            || !preference.properties.fields.is_empty()
-            || !preference.properties.deleted_fields.is_empty();
-        let property_presets = PropertyPresetStore::new(config_dir.join("local.db"));
-        let property_presets_migration_complete = match property_presets.migrate_legacy_once(&PropertyPresetRegistry {
-                system_fields: preference.properties.system_fields.clone(),
-                fields: preference.properties.fields.clone(),
-                deleted_fields: preference.properties.deleted_fields.clone(),
-            }).and_then(|migrated| property_presets.initialize_system_presets().map(|_| migrated)) {
-            Ok(_) if had_legacy_property_registry => {
-                preference.properties = PropertiesConfig::default();
-                match preference_json_without_property_registry(&preference) {
-                    Ok(content) => if let Err(error) = atomic_write_json(&preference_file_path(&config_dir), &content) {
-                        tracing::warn!(%error, "property presets were migrated, but legacy preference data could not be removed");
-                    },
-                    Err(error) => tracing::warn!(%error, "property presets were migrated, but legacy preference data could not be serialized"),
-                }
-                true
-            }
-            Ok(_) => { preference.properties = PropertiesConfig::default(); true }
-            Err(error) => {
-                tracing::error!(%error, "property preset migration failed; legacy preference data was retained on disk");
-                false
-            }
-        };
+        let preference = flowix_core::memo_file::read_or_create_json(
+            &preference_file_path(&config_dir),
+            PreferenceFile::default,
+        )
+        .unwrap_or_else(|error| {
+            tracing::warn!(%error, "preferences unavailable; using defaults");
+            PreferenceFile::default()
+        });
+        let property_presets = PropertyPresetStore::new(config_dir.join("db").join("local.db"));
         // Once the official DSH settings document exists, do not even load
-        // the legacy TOML into the process. This makes the source-of-truth
-        // boundary explicit: agent-config.toml is read only during the
-        // one-time migration performed by
-        // read_or_migrate_deepseek_harness_settings().
+        // the legacy TOML into the compatibility accessor. If it does not
+        // exist, this accessor may still expose the old standalone AI config;
+        // DSH settings reads themselves never migrate from it.
         let ai_config = if dsh_settings_path(&config_dir).is_file() {
             AiConfigFile::default()
         } else {
@@ -697,8 +699,92 @@ impl UserConfigStore {
             ai_config: RwLock::new(ai_config),
             secrets,
             property_presets,
-            property_presets_migration_complete,
+            property_presets_migration_complete: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    /// Run local configuration imports during the explicit version
+    /// initialization phase, before settings IPC is enabled.
+    pub fn initialize_legacy_config_migrations(&self) -> Result<(), String> {
+        self.with_runtime_storage_rebuild(|| self.initialize_legacy_config_migrations_inner())
+    }
+
+    fn initialize_legacy_config_migrations_inner(&self) -> Result<(), String> {
+        let mut preference = self.write_preference();
+        let had_legacy_properties = !preference.properties.system_fields.is_empty()
+            || !preference.properties.fields.is_empty()
+            || !preference.properties.deleted_fields.is_empty();
+        let registry = PropertyPresetRegistry {
+            system_fields: preference.properties.system_fields.clone(),
+            fields: preference.properties.fields.clone(),
+            deleted_fields: preference.properties.deleted_fields.clone(),
+        };
+        self.property_presets
+            .migrate_legacy_once(&registry)
+            .and_then(|_| self.property_presets.initialize_system_presets())
+            .map_err(|error| format!("initialize property presets failed: {error}"))?;
+        if had_legacy_properties {
+            preference.properties = PropertiesConfig::default();
+            let content = preference_json_without_property_registry(&preference)
+                .map_err(|error| format!("serialize cleaned preferences failed: {error}"))?;
+            atomic_write_json(&preference_file_path(&self.config_dir), &content)
+                .map_err(|error| format!("write cleaned preferences failed: {error}"))?;
         }
+        preference.properties = PropertiesConfig::default();
+        Ok(())
+    }
+
+    /// Ensure current runtime defaults even when one-time migrations already ran.
+    /// Opening the store recreates a missing database/tables; existing presets
+    /// retain their identities and user values.
+    pub fn ensure_runtime_storage(&self) -> Result<(), String> {
+        self.with_runtime_storage_rebuild(|| {
+            self.property_presets.initialize_legacy_schema()?;
+            self.property_presets.initialize_system_presets()
+        })
+    }
+
+    fn with_runtime_storage_rebuild(
+        &self,
+        mut operation: impl FnMut() -> Result<(), String>,
+    ) -> Result<(), String> {
+        flowix_core::memo_file::with_database_rebuild(&self.config_dir.join("db/local.db"), || {
+            operation().map_err(|message| {
+                let invalid_data = [
+                    "no such",
+                    "has no column",
+                    "malformed",
+                    "not a database",
+                    "Invalid column",
+                    "invalid column",
+                    "datatype mismatch",
+                ]
+                .iter()
+                .any(|pattern| message.contains(pattern));
+                std::io::Error::new(
+                    if invalid_data {
+                        std::io::ErrorKind::InvalidData
+                    } else {
+                        std::io::ErrorKind::Other
+                    },
+                    message,
+                )
+            })
+        })
+        .map_err(|error| error.to_string())
+    }
+
+    /// Restore process-local state after persistent migration completion.
+    /// This runs on every startup, including when migration jobs are skipped.
+    pub fn prepare_initialized_runtime(&self) {
+        self.write_preference().properties = PropertiesConfig::default();
+        self.property_presets_migration_complete
+            .store(true, Ordering::Release);
+    }
+
+    /// Migrate the old Flowix DSH directory layout in its own retryable step.
+    pub fn initialize_legacy_dsh_layout(&self) -> Result<(), String> {
+        migrate_dsh_layout(&self.config_dir)
     }
 
     #[allow(dead_code)]
@@ -710,10 +796,11 @@ impl UserConfigStore {
     /// `profiles/flowix` namespace inside it and leaves plugin/profile state
     /// to the official DSH CLI.
     pub fn dsh_dir(&self) -> PathBuf {
-        self.config_dir
-            .parent()
-            .unwrap_or(self.config_dir.as_path())
-            .join(DSH_DIR_NAME)
+        resolve_dsh_home(
+            self.config_dir
+                .parent()
+                .unwrap_or(self.config_dir.as_path()),
+        )
     }
 
     pub fn dsh_settings_path(&self) -> PathBuf {
@@ -766,17 +853,34 @@ impl UserConfigStore {
         self.read_preference().clone()
     }
 
+    pub fn has_legacy_watcher_exclusions(&self) -> bool {
+        let preference = self.read_preference();
+        let defaults = crate::watcher::WhitelistConfig::default();
+        preference.watcher.skip_dirs != defaults.skip_dirs
+            || preference.watcher.skip_files != defaults.skip_files
+    }
+
     pub fn get_property_presets(&self) -> Result<PropertyPresetRegistry, UserConfigError> {
-        self.property_presets.get().map_err(UserConfigError::InvalidConfig)
+        self.property_presets
+            .get()
+            .map_err(UserConfigError::InvalidConfig)
     }
 
-    pub fn patch_property_presets(&self, changes: &[PropertyPresetChange]) -> Result<PropertyPresetRegistry, UserConfigError> {
-        self.property_presets.patch(changes).map_err(UserConfigError::InvalidConfig)
+    pub fn patch_property_presets(
+        &self,
+        changes: &[PropertyPresetChange],
+    ) -> Result<PropertyPresetRegistry, UserConfigError> {
+        self.property_presets
+            .patch(changes)
+            .map_err(UserConfigError::InvalidConfig)
     }
 
     /// 先把 JSON 落盘 (tmp + fsync + rename, 0o600), 成功后才更新内存�?    /// 任一写�?骤失�?�?内存保持旧�? 磁盘保持旧文�? 不出�?内存新�?盘旧"�?    /// "半写�?��"的损坏状态�?
     pub fn set_preference(&self, mut p: PreferenceFile) -> Result<(), UserConfigError> {
-        let content = if self.property_presets_migration_complete {
+        let content = if self
+            .property_presets_migration_complete
+            .load(Ordering::Acquire)
+        {
             p.properties = PropertiesConfig::default();
             preference_json_without_property_registry(&p)?
         } else {
@@ -789,18 +893,81 @@ impl UserConfigStore {
         Ok(())
     }
 
+    /// Stage-2 defaults are process-local. Persisting them is background work.
+    pub fn prepare_runtime_watcher_exclusions(&self) {
+        let defaults = crate::watcher::WhitelistConfig::default();
+        let mut preference = self.write_preference();
+        preference.watcher.skip_dirs = defaults.skip_dirs;
+        preference.watcher.skip_files = defaults.skip_files;
+    }
+
+    /// Clear the legacy global watcher name exclusions. New file-management
+    /// rules are notebook-local and are initialized from their current defaults.
+    pub fn clear_legacy_watcher_exclusions(&self) -> Result<(), UserConfigError> {
+        let mut preference = self.write_preference();
+        let defaults = crate::watcher::WhitelistConfig::default();
+        // Patch the raw document so unknown or newer preference fields survive
+        // this one-time cleanup as well.
+        let path = preference_file_path(&self.config_dir);
+        let mut document = match fs::read(&path) {
+            Ok(bytes) => serde_json::from_slice::<serde_json::Value>(&bytes)?,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                serde_json::to_value(&*preference)?
+            }
+            Err(error) => return Err(error.into()),
+        };
+        let root = document.as_object_mut().ok_or_else(|| {
+            UserConfigError::InvalidConfig("preference.json must contain a JSON object".into())
+        })?;
+        let watcher = root
+            .entry("watcher")
+            .or_insert_with(|| serde_json::json!({}));
+        let watcher = watcher.as_object_mut().ok_or_else(|| {
+            UserConfigError::InvalidConfig(
+                "preference.json watcher must contain a JSON object".into(),
+            )
+        })?;
+        if watcher.get("skip_dirs") == Some(&serde_json::to_value(&defaults.skip_dirs)?)
+            && watcher.get("skip_files") == Some(&serde_json::to_value(&defaults.skip_files)?)
+        {
+            preference.watcher.skip_dirs = defaults.skip_dirs;
+            preference.watcher.skip_files = defaults.skip_files;
+            return Ok(());
+        }
+        watcher.insert(
+            "skip_dirs".into(),
+            serde_json::to_value(&defaults.skip_dirs)?,
+        );
+        watcher.insert(
+            "skip_files".into(),
+            serde_json::to_value(&defaults.skip_files)?,
+        );
+        let content = serde_json::to_string_pretty(&document)?;
+        atomic_write_json(&path, &content)?;
+
+        preference.watcher.skip_dirs = defaults.skip_dirs;
+        preference.watcher.skip_files = defaults.skip_files;
+        Ok(())
+    }
+
     /// Merge a partial JSON preference patch with the current value under the
     /// preference lock, so separate windows cannot overwrite unrelated fields.
     pub fn patch_preference(&self, patch: serde_json::Value) -> Result<(), UserConfigError> {
         let mut preference = self.write_preference();
         let legacy_properties = preference.properties.clone();
         let mut value = serde_json::to_value(&*preference)?;
-        if self.property_presets_migration_complete {
+        if self
+            .property_presets_migration_complete
+            .load(Ordering::Acquire)
+        {
             value["properties"] = serde_json::to_value(PropertiesConfig::default())?;
         }
         merge_preference_patch(&mut value, patch);
         let mut next: PreferenceFile = serde_json::from_value(value)?;
-        let content = if self.property_presets_migration_complete {
+        let content = if self
+            .property_presets_migration_complete
+            .load(Ordering::Acquire)
+        {
             next.properties = PropertiesConfig::default();
             preference_json_without_property_registry(&next)?
         } else {
@@ -838,12 +1005,10 @@ impl UserConfigStore {
         config
     }
 
-    /// Load the DeepSeek Harness model configuration from the llm-pi-ai
-    /// settings document. Existing installations are migrated lazily from
-    /// agent-config.toml on first access; after that, the legacy document is
-    /// not consulted again.
+    /// Load DeepSeek Harness model configuration from the official settings
+    /// document. Missing settings start empty; retired Flowix TOML is ignored.
     pub fn get_deepseek_harness_config(&self) -> Result<AiConfigFile, UserConfigError> {
-        let settings = self.read_or_migrate_deepseek_harness_settings()?;
+        let settings = self.read_deepseek_harness_settings()?.unwrap_or_default();
         Ok(settings.to_ai_config())
     }
 
@@ -852,7 +1017,7 @@ impl UserConfigStore {
     /// independent routes and their model cards carry different endpoints
     /// and credentials.
     pub fn get_deepseek_harness_configs(&self) -> Result<Vec<AiConfigFile>, UserConfigError> {
-        let settings = self.read_or_migrate_deepseek_harness_settings()?;
+        let settings = self.read_deepseek_harness_settings()?.unwrap_or_default();
         Ok(settings.to_ai_configs())
     }
 
@@ -918,24 +1083,6 @@ impl UserConfigStore {
         }
     }
 
-    /// Read the official DSH settings document, or create it once from the
-    /// legacy Flowix TOML when upgrading an older installation. After this
-    /// write succeeds, subsequent reads never consult `agent-config.toml`.
-    fn read_or_migrate_deepseek_harness_settings(
-        &self,
-    ) -> Result<DeepSeekHarnessSettingsFile, UserConfigError> {
-        if let Some(settings) = self.read_deepseek_harness_settings()? {
-            return Ok(settings);
-        }
-
-        let mut legacy = self.read_ai_config().clone();
-        self.hydrate_ai_config_secrets(&mut legacy);
-        let settings = DeepSeekHarnessSettingsFile::from_ai_config(&legacy);
-        let content = serde_yaml::to_string(&settings)?;
-        atomic_write_yaml(&self.dsh_settings_path(), &content)?;
-        Ok(settings)
-    }
-
     /// Render a standalone Harness settings document for a one-shot probe.
     ///
     /// A probe must be able to validate a model that has not been saved yet.
@@ -1025,23 +1172,6 @@ impl UserConfigStore {
             .map_err(|err| UserConfigError::SecretStore(err.to_string()))
     }
 
-    /// Read a pre-DSH-owned credential for one route during the one-time
-    /// migration. New DSH settings code must not use this as a runtime source.
-    pub(crate) fn legacy_dsh_secret(
-        &self,
-        provider: &str,
-    ) -> Result<Option<String>, UserConfigError> {
-        let account = entry_name(provider, SECRET_ACCOUNT_NAME);
-        self.secrets
-            .load(&account)
-            .map(|value| value.map(|secret| secret.into_inner()))
-            .map_err(|err| UserConfigError::SecretStore(err.to_string()))
-    }
-
-    pub(crate) fn delete_legacy_dsh_secret(&self, provider: &str) -> Result<(), UserConfigError> {
-        self.delete_provider_secret(provider)
-    }
-
     pub fn save_cloud_refresh_token(&self, token: &str) -> Result<(), UserConfigError> {
         self.save_provider_secret(CLOUD_SECRET_PROVIDER, token)
     }
@@ -1058,24 +1188,59 @@ impl UserConfigStore {
         self.delete_provider_secret(CLOUD_SECRET_PROVIDER)
     }
 
-    fn read_preference_from_disk(dir: &PathBuf) -> Option<PreferenceFile> {
-        let path = preference_file_path(dir);
-        if !path.exists() {
-            return None;
+    fn cloud_dev_secret_provider(environment: flowix_sync::CloudEnvironment) -> &'static str {
+        match environment {
+            flowix_sync::CloudEnvironment::Staging => CLOUD_DEV_STAGING_SECRET_PROVIDER,
+            flowix_sync::CloudEnvironment::Prod => CLOUD_DEV_PRODUCTION_SECRET_PROVIDER,
         }
-        fs::read_to_string(&path)
-            .ok()
-            .and_then(|s| serde_json::from_str(&s).ok())
+    }
+
+    pub fn save_cloud_dev_refresh_token(
+        &self,
+        environment: flowix_sync::CloudEnvironment,
+        token: &str,
+    ) -> Result<(), UserConfigError> {
+        self.save_provider_secret(Self::cloud_dev_secret_provider(environment), token)
+    }
+
+    pub fn load_cloud_dev_refresh_token(
+        &self,
+        environment: flowix_sync::CloudEnvironment,
+    ) -> Result<Option<String>, UserConfigError> {
+        let provider = Self::cloud_dev_secret_provider(environment);
+        let account = entry_name(provider, SECRET_ACCOUNT_NAME);
+        self.secrets
+            .load(&account)
+            .map(|value| value.map(|secret| secret.into_inner()))
+            .map_err(|err| UserConfigError::SecretStore(err.to_string()))
+    }
+
+    pub fn delete_cloud_dev_refresh_token(
+        &self,
+        environment: flowix_sync::CloudEnvironment,
+    ) -> Result<(), UserConfigError> {
+        self.delete_provider_secret(Self::cloud_dev_secret_provider(environment))
     }
 
     fn read_ai_config_from_disk(dir: &PathBuf) -> Option<AiConfigFile> {
         let path = dir.join(AI_CONFIG_FILE_NAME);
-        if !path.exists() {
-            return None;
+        match fs::read(&path) {
+            Ok(bytes) => match std::str::from_utf8(&bytes)
+                .ok()
+                .and_then(|text| toml::from_str(text).ok())
+            {
+                Some(config) => return Some(config),
+                None => {
+                    flowix_core::memo_file::backup_storage_file(&path).ok()?;
+                }
+            },
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(_) => return None,
         }
-        fs::read_to_string(&path)
-            .ok()
-            .and_then(|s| toml::from_str(&s).ok())
+        let config = AiConfigFile::default();
+        let text = toml::to_string_pretty(&config).ok()?;
+        flowix_core::memo_file::atomic_write_bytes(&path, text.as_bytes()).ok()?;
+        Some(config)
     }
 }
 
@@ -1096,6 +1261,43 @@ impl flowix_sync::RefreshTokenStore for UserConfigStore {
     }
 }
 
+pub struct CloudDevRefreshTokenStore {
+    user_config: std::sync::Arc<UserConfigStore>,
+    environment: flowix_sync::CloudEnvironment,
+}
+
+impl CloudDevRefreshTokenStore {
+    pub fn new(
+        user_config: std::sync::Arc<UserConfigStore>,
+        environment: flowix_sync::CloudEnvironment,
+    ) -> Self {
+        Self {
+            user_config,
+            environment,
+        }
+    }
+}
+
+impl flowix_sync::RefreshTokenStore for CloudDevRefreshTokenStore {
+    fn load(&self) -> Result<Option<String>, String> {
+        self.user_config
+            .load_cloud_dev_refresh_token(self.environment)
+            .map_err(|error| error.to_string())
+    }
+
+    fn save(&self, token: &str) -> Result<(), String> {
+        self.user_config
+            .save_cloud_dev_refresh_token(self.environment, token)
+            .map_err(|error| error.to_string())
+    }
+
+    fn delete(&self) -> Result<(), String> {
+        self.user_config
+            .delete_cloud_dev_refresh_token(self.environment)
+            .map_err(|error| error.to_string())
+    }
+}
+
 fn merge_preference_patch(target: &mut serde_json::Value, patch: serde_json::Value) {
     match patch {
         serde_json::Value::Object(patch_fields) => {
@@ -1155,7 +1357,9 @@ fn preference_file_path(config_dir: &Path) -> PathBuf {
     config_dir.join(BOOT_DIR_NAME).join(PREFERENCE_FILE_NAME)
 }
 
-fn preference_json_without_property_registry(preference: &PreferenceFile) -> Result<String, UserConfigError> {
+fn preference_json_without_property_registry(
+    preference: &PreferenceFile,
+) -> Result<String, UserConfigError> {
     let mut value = serde_json::to_value(preference)?;
     if let Some(object) = value.as_object_mut() {
         object.remove("properties");
@@ -1172,7 +1376,7 @@ fn dsh_settings_path(config_dir: &Path) -> PathBuf {
 }
 
 /// 原子�?JSON: �?.tmp �?fsync �?0o600 �?rename 到目标�?/// 失败�?.tmp 残留由下次启动�?�? 不影响主文件�?///
-/// `pub(crate)` —`agent_access` 等同形态的 JSON 配置文件 (�?boot/preference.json)
+/// `pub(crate)` —其他同形态的 JSON 配置文件 (�?boot/preference.json)
 /// 同目�? 复用这个落盘逻辑, 不�?制�?二份�?
 pub(crate) fn atomic_write_json(path: &Path, content: &str) -> std::io::Result<()> {
     if let Some(parent) = path.parent() {
@@ -1241,89 +1445,134 @@ pub(crate) fn atomic_write_yaml(path: &Path, content: &str) -> std::io::Result<(
 /// `~/.dsh/` home without overwriting anything already created there. The
 /// old `~/.flowix/dsh/` directory is moved as one unit when possible; the
 /// older flat files are handled individually. Nothing is deleted.
-fn migrate_dsh_layout(config_dir: &Path) {
+fn migrate_dsh_layout(config_dir: &Path) -> Result<(), String> {
     let old_dsh_dir = config_dir.join("dsh");
     let dsh_dir = config_dir.parent().unwrap_or(config_dir).join(DSH_DIR_NAME);
     let legacy_settings = config_dir.join("dsh-settings.yaml");
     let legacy_plugin_settings = config_dir.join("dsh-plugin-settings.json");
     let legacy_sessions = config_dir.join("dsh-sessions");
 
-    if old_dsh_dir.is_dir() && !dsh_dir.exists() {
-        if fs::rename(&old_dsh_dir, &dsh_dir).is_ok() {
-            set_dir_owner_only_perms(&dsh_dir);
-        }
+    if path_is_directory(&old_dsh_dir)? && !path_exists(&dsh_dir)? {
+        fs::rename(&old_dsh_dir, &dsh_dir)
+            .map_err(|error| format!("move legacy DSH directory failed: {error}"))?;
+        set_dir_owner_only_perms(&dsh_dir);
     }
 
-    if legacy_settings.exists() || legacy_plugin_settings.exists() || legacy_sessions.exists() {
-        let _ = fs::create_dir_all(&dsh_dir);
+    if path_exists(&legacy_settings)?
+        || path_exists(&legacy_plugin_settings)?
+        || path_exists(&legacy_sessions)?
+    {
+        fs::create_dir_all(&dsh_dir)
+            .map_err(|error| format!("create DSH directory failed: {error}"))?;
         set_dir_owner_only_perms(&dsh_dir);
     }
 
-    migrate_into(&legacy_settings, &dsh_dir.join(DSH_SETTINGS_FILE_NAME));
+    migrate_into(&legacy_settings, &dsh_dir.join(DSH_SETTINGS_FILE_NAME))?;
     migrate_into(
         &legacy_plugin_settings,
         &dsh_dir.join(DSH_PLUGIN_SETTINGS_FILE_NAME),
-    );
-    migrate_into(&legacy_sessions, &dsh_dir.join(DSH_SESSIONS_DIR_NAME));
-    flatten_dsh_session_wrappers(&dsh_dir.join(DSH_SESSIONS_DIR_NAME));
+    )?;
+    migrate_into(&legacy_sessions, &dsh_dir.join(DSH_SESSIONS_DIR_NAME))?;
+    flatten_dsh_session_wrappers(&dsh_dir.join(DSH_SESSIONS_DIR_NAME))?;
+    Ok(())
+}
+
+fn path_exists(path: &Path) -> Result<bool, String> {
+    match fs::symlink_metadata(path) {
+        Ok(_) => Ok(true),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
+        Err(error) => Err(format!("inspect {} failed: {error}", path.display())),
+    }
+}
+
+fn path_is_directory(path: &Path) -> Result<bool, String> {
+    match fs::metadata(path) {
+        Ok(metadata) => Ok(metadata.is_dir()),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
+        Err(error) => Err(format!("inspect {} failed: {error}", path.display())),
+    }
 }
 
 /// Rename `source` to `target` when the source exists and the target is
 /// absent, then reapply owner-only permissions. Never overwrites an existing
 /// target; the directory case keeps the execute bit so it stays traversable.
-fn migrate_into(source: &Path, target: &Path) {
-    if !source.exists() || target.exists() {
-        return;
+fn migrate_into(source: &Path, target: &Path) -> Result<(), String> {
+    if !path_exists(source)? || path_exists(target)? {
+        return Ok(());
     }
     if let Some(parent) = target.parent() {
-        let _ = fs::create_dir_all(parent);
+        fs::create_dir_all(parent)
+            .map_err(|error| format!("create DSH migration target directory failed: {error}"))?;
         set_dir_owner_only_perms(parent);
     }
-    if fs::rename(source, target).is_ok() {
-        if target.is_dir() {
-            set_dir_owner_only_perms(target);
-        } else {
-            set_file_owner_only_perms(target);
-        }
+    fs::rename(source, target)
+        .map_err(|error| format!("move DSH migration source failed: {error}"))?;
+    if path_is_directory(target)? {
+        set_dir_owner_only_perms(target);
+    } else {
+        set_file_owner_only_perms(target);
     }
+    Ok(())
 }
 
 /// Remove the temporary Flowix-owned `<session-id>/` wrapper that was used
 /// before the persistence root matched Harness' official layout. Only
 /// directories that clearly contain project directories are flattened; other
 /// entries such as `.runtime` are left untouched.
-fn flatten_dsh_session_wrappers(sessions_dir: &Path) {
-    let Ok(entries) = fs::read_dir(sessions_dir) else {
-        return;
+fn flatten_dsh_session_wrappers(sessions_dir: &Path) -> Result<(), String> {
+    let entries = match fs::read_dir(sessions_dir) {
+        Ok(entries) => entries,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(error) => return Err(format!("read DSH sessions directory failed: {error}")),
     };
-    for entry in entries.flatten() {
+    for entry in entries {
+        let entry = entry.map_err(|error| format!("read DSH session entry failed: {error}"))?;
         let wrapper = entry.path();
-        if !wrapper.is_dir() || entry.file_name() == ".runtime" {
+        let file_type = entry
+            .file_type()
+            .map_err(|error| format!("inspect DSH session entry failed: {error}"))?;
+        if !file_type.is_dir() || entry.file_name() == ".runtime" {
             continue;
         }
-        let Ok(projects) = fs::read_dir(&wrapper) else {
-            continue;
-        };
-        let projects = projects
-            .flatten()
-            .filter(|project| {
-                let project_name = project.file_name().to_string_lossy().into_owned();
-                project.path().is_dir()
-                    && (project_name == "_no-cwd"
-                        || (project_name.starts_with("--") && project_name.ends_with("--")))
-            })
-            .collect::<Vec<_>>();
+        let candidates = fs::read_dir(&wrapper)
+            .map_err(|error| format!("read DSH session wrapper failed: {error}"))?
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(|error| format!("read DSH wrapped session entry failed: {error}"))?;
+        let mut projects = Vec::new();
+        for project in candidates {
+            let project_name = project.file_name().to_string_lossy().into_owned();
+            if (project_name == "_no-cwd"
+                || (project_name.starts_with("--") && project_name.ends_with("--")))
+                && path_is_directory(&project.path())?
+            {
+                projects.push(project);
+            }
+        }
         if projects.is_empty() {
             continue;
         }
         for project in projects {
             let target = sessions_dir.join(project.file_name());
-            if !target.exists() {
-                let _ = fs::rename(project.path(), target);
+            if !path_exists(&target)? {
+                fs::rename(project.path(), &target)
+                    .map_err(|error| format!("flatten DSH session wrapper failed: {error}"))?;
+            }
+        }
+        let mut remaining = fs::read_dir(&wrapper)
+            .map_err(|error| format!("inspect DSH session wrapper failed: {error}"))?;
+        let is_empty = match remaining.next() {
+            None => true,
+            Some(Ok(_)) => false,
+            Some(Err(error)) => {
+                return Err(format!("inspect DSH session wrapper entry failed: {error}"));
             }
+        };
+        if is_empty {
+            fs::remove_dir(&wrapper)
+                .map_err(|error| format!("remove empty DSH session wrapper failed: {error}"))?;
         }
-        let _ = fs::remove_dir(&wrapper);
     }
+    Ok(())
 }
 
 #[cfg(unix)]
@@ -1405,6 +1654,43 @@ mod tests {
         )
     }
 
+    #[test]
+    fn storage_rebuild_replaces_invalid_preferences_and_toml() {
+        let home = tempfile::tempdir().unwrap();
+        let config = home.path().join(USER_CONFIG_DIR_NAME);
+        std::fs::create_dir_all(config.join("boot")).unwrap();
+        std::fs::write(config.join("boot/preference.json"), b"invalid json").unwrap();
+        std::fs::write(config.join(AI_CONFIG_FILE_NAME), [0xff, 0xfe]).unwrap();
+        let _store = test_user_config_store(home.path().to_path_buf());
+        let json = std::fs::read(config.join("boot/preference.json")).unwrap();
+        serde_json::from_slice::<PreferenceFile>(&json).unwrap();
+        let toml = std::fs::read_to_string(config.join(AI_CONFIG_FILE_NAME)).unwrap();
+        toml::from_str::<AiConfigFile>(&toml).unwrap();
+        assert!(config.join("boot/rebuild-backups").exists());
+        assert!(config.join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn missing_runtime_dependencies_recreate_defaults_after_initialization() {
+        let home = tempfile::tempdir().unwrap();
+        let store = test_user_config_store(home.path().to_path_buf());
+        store.initialize_legacy_config_migrations().unwrap();
+        store.prepare_initialized_runtime();
+        let expected = store.get_property_presets().unwrap().system_fields.len();
+        assert!(expected > 0);
+        std::fs::remove_dir_all(store.config_dir().join("db")).unwrap();
+        store.ensure_runtime_storage().unwrap();
+        assert_eq!(
+            store.get_property_presets().unwrap().system_fields.len(),
+            expected
+        );
+        store.ensure_runtime_storage().unwrap();
+        assert_eq!(
+            store.get_property_presets().unwrap().system_fields.len(),
+            expected
+        );
+    }
+
     #[test]
     fn legacy_json_property_presets_migrate_to_local_database() {
         let home = tempfile::tempdir().unwrap();
@@ -1417,18 +1703,32 @@ mod tests {
             r#type: "Tag".into(),
             ..PropertyFieldConfig::default()
         });
-        atomic_write_json(&preference_file_path(&config_dir), &serde_json::to_string(&legacy).unwrap()).unwrap();
+        atomic_write_json(
+            &preference_file_path(&config_dir),
+            &serde_json::to_string(&legacy).unwrap(),
+        )
+        .unwrap();
 
         let store = test_user_config_store(home.path().to_path_buf());
         let migrated = store.get_property_presets().unwrap();
         assert_eq!(migrated.fields.len(), 1);
-        assert!(migrated.fields[0].id.as_deref().is_some_and(|id| id.starts_with("fld_")));
-        assert!(config_dir.join("local.db").is_file());
+        assert!(migrated.fields[0]
+            .id
+            .as_deref()
+            .is_some_and(|id| id.starts_with("fld_")));
+        assert!(config_dir.join("db/local.db").is_file());
 
-        store.patch_preference(serde_json::json!({"language": "zh-CN"})).unwrap();
-        let saved: serde_json::Value = serde_json::from_slice(&std::fs::read(preference_file_path(&config_dir)).unwrap()).unwrap();
+        store
+            .patch_preference(serde_json::json!({"language": "zh-CN"}))
+            .unwrap();
+        let saved: serde_json::Value =
+            serde_json::from_slice(&std::fs::read(preference_file_path(&config_dir)).unwrap())
+                .unwrap();
         assert!(saved.get("properties").is_none());
-        assert_eq!(store.get_property_presets().unwrap().fields[0].key, "topics");
+        assert_eq!(
+            store.get_property_presets().unwrap().fields[0].key,
+            "topics"
+        );
     }
 
     #[test]
@@ -1538,7 +1838,7 @@ mod tests {
     }
 
     #[test]
-    fn first_dsh_read_migrates_legacy_toml_once() {
+    fn dsh_read_ignores_legacy_toml() {
         let home = tempfile::tempdir().unwrap();
         let config_dir = home.path().join(USER_CONFIG_DIR_NAME);
         std::fs::create_dir_all(&config_dir).unwrap();
@@ -1558,31 +1858,13 @@ mod tests {
 
         let store = test_user_config_store(home.path().to_path_buf());
         let loaded = store.get_deepseek_harness_config().unwrap();
-        assert_eq!(loaded.model.provider, "legacy-provider");
-        assert_eq!(loaded.model.model, "legacy-model");
-
-        // A later change to the old file must not affect the already-created
-        // DSH settings document.
-        let replacement = AiConfigFile {
-            model: AiModelConfig {
-                provider: "replacement-provider".into(),
-                model: "replacement-model".into(),
-                api_url: "https://replacement.example/v1".into(),
-                ..AiModelConfig::default()
-            },
-        };
-        std::fs::write(
-            config_dir.join(AI_CONFIG_FILE_NAME),
-            toml::to_string_pretty(&replacement).unwrap(),
-        )
-        .unwrap();
-        let loaded_again = store.get_deepseek_harness_config().unwrap();
-        assert_eq!(loaded_again.model.provider, "legacy-provider");
-        assert!(home
+        assert!(loaded.model.provider.is_empty());
+        assert!(loaded.model.model.is_empty());
+        assert!(!home
             .path()
             .join(DSH_DIR_NAME)
             .join(DSH_SETTINGS_FILE_NAME)
-            .is_file());
+            .exists());
     }
 
     #[test]
@@ -1692,6 +1974,28 @@ apiKey = "k"
         assert_eq!(cfg.model.model, "gpt-4o");
     }
 
+    #[test]
+    fn initialization_runtime_preparation_survives_process_restart() {
+        let home = tempfile::tempdir().unwrap();
+        {
+            let store = test_user_config_store(home.path().to_path_buf());
+            store.initialize_legacy_config_migrations().unwrap();
+        }
+        // The persistent migration is already complete; the new process only
+        // restores runtime state before saving ordinary preferences.
+        let store = test_user_config_store(home.path().to_path_buf());
+        store.prepare_initialized_runtime();
+        store
+            .patch_preference(serde_json::json!({"language": "en"}))
+            .unwrap();
+        let document: serde_json::Value = serde_json::from_slice(
+            &std::fs::read(preference_file_path(&store.config_dir)).unwrap(),
+        )
+        .unwrap();
+        assert!(document.get("properties").is_none());
+        assert_eq!(document["language"], "en");
+    }
+
     #[test]
     fn set_preference_writes_to_boot_dir() {
         let home = tempfile::tempdir().unwrap();
diff --git a/app/flowix-desktop/src/device_registration.rs b/app/flowix-desktop/src/device_registration.rs
index fc1f724de..733e35994 100644
--- a/app/flowix-desktop/src/device_registration.rs
+++ b/app/flowix-desktop/src/device_registration.rs
@@ -43,20 +43,35 @@ const DEFAULT_SUPABASE_ANON_KEY: &str = "sb_publishable_l6AmH0K0Uq8_roThQHSnnQ_2
 pub struct BootFile {
     pub schema_version: u32,
     #[serde(default)]
+    pub version_initialization: VersionInitializationState,
+    /// Most recent app version whose one-time version initialization completed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_successful_app_version: Option<String>,
+    /// Version of the one-time on-disk storage reset already completed.
+    /// This is separate from app-version initialization so later releases do
+    /// not repeatedly discard derived indexes or user-created plugin files.
+    #[serde(default)]
+    pub notebook_storage_reset_version: u32,
+    #[serde(default)]
     pub experimental: bool,
     /// Whether the first-run DeepSeek Harness introduction has been shown.
     /// Keep the on-disk key in snake_case for the boot.json contract.
     #[serde(default, rename = "is_introduct_displayed")]
     pub is_introduct_displayed: bool,
-    /// Whether the first-run workspace onboarding has been completed.
-    /// Development builds intentionally keep this false so the flow can be
-    /// exercised on every launch.
-    #[serde(default, rename = "is_onboarding_completed")]
-    pub is_onboarding_completed: bool,
     #[serde(default)]
     pub user_info: UserInfo,
 }
 
+/// Completion state for the one-time initialization associated with an app version.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct VersionInitializationState {
+    #[serde(default)]
+    pub app_version: Option<String>,
+    #[serde(default)]
+    pub completed: bool,
+}
+
 /// 设备登记子对象：保存随机设备 ID 和登记尝试状态。
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -91,20 +106,32 @@ impl DeviceRegistry {
         let app_version = app_version.into();
         if let Some(parent) = path.parent() {
             // best-effort, 文件已存在就能�?常�?�? 不存在时 `read_from_disk` 返回 None
-            let _ = std::fs::create_dir_all(parent);
+            let _ = flowix_core::memo_file::ensure_storage_directory(parent);
         }
-        let boot = Self::read_from_disk(&path).unwrap_or_else(|| {
+        let loaded = Self::read_from_disk(&path);
+        let mut save_defaults = loaded.is_none();
+        let boot = loaded.unwrap_or_else(|| {
+            if let Err(error) = flowix_core::memo_file::backup_storage_file(&path) {
+                save_defaults = false;
+                tracing::warn!(%error, "could not preserve invalid boot configuration");
+            }
             tracing::info!(
                 "[device-reg] no boot.json at {}; creating a fresh registration record",
                 path.display()
             );
             Self::fresh()
         });
-        Self {
+        let registry = Self {
             path,
             app_version,
             inner: RwLock::new(boot),
+        };
+        if save_defaults {
+            if let Err(error) = registry.flush(&registry.read()) {
+                tracing::warn!(%error, "could not persist boot configuration");
+            }
         }
+        registry
     }
 
     /// 异�?上报入口�?Fire-and-forget: �?�� `tauri::async_runtime::spawn`,
@@ -122,33 +149,82 @@ impl DeviceRegistry {
         self.read().experimental
     }
 
-    /// Whether the DeepSeek Harness introduction has already been displayed.
-    pub fn is_introduct_displayed(&self) -> bool {
-        self.read().is_introduct_displayed
+    /// App version whose one-time version initialization most recently completed.
+    pub fn last_successful_app_version(&self) -> Option<String> {
+        self.read().last_successful_app_version.clone()
     }
 
-    /// Persist the DeepSeek Harness introduction display state.
-    pub fn set_introduct_displayed(&self, displayed: bool) -> Result<(), String> {
+    /// Whether the current app version has completed its one-time initialization.
+    pub fn is_version_initialization_complete(&self) -> bool {
+        let boot = self.read();
+        // `last_successful_app_version` is the durable fallback if the in-flight
+        // marker was restored from an older backup or otherwise became stale.
+        // Once this version has completed successfully, do not replay one-time
+        // initialization because the secondary progress flag disagrees.
+        boot.last_successful_app_version.as_deref() == Some(self.app_version.as_str())
+            || (boot.version_initialization.app_version.as_deref()
+                == Some(self.app_version.as_str())
+                && boot.version_initialization.completed)
+    }
+
+    /// Update the current app version's initialization flag from dev settings.
+    pub fn set_version_initialization_completed(&self, completed: bool) -> Result<(), String> {
         let mut boot = self.write();
-        boot.is_introduct_displayed = displayed;
+        boot.version_initialization.app_version = Some(self.app_version.clone());
+        boot.version_initialization.completed = completed;
+        if completed {
+            boot.last_successful_app_version = Some(self.app_version.clone());
+        } else if boot.last_successful_app_version.as_deref() == Some(self.app_version.as_str()) {
+            // Preserve the explicit development setting that requests a rerun.
+            boot.last_successful_app_version = None;
+        }
+        self.flush(&boot)
+            .map_err(|error| format!("persist boot.json: {error}"))
+    }
+
+    /// Persist an incomplete marker before running version-specific migrations.
+    pub fn begin_version_initialization(&self) -> Result<(), String> {
+        let mut boot = self.write();
+        boot.version_initialization.app_version = Some(self.app_version.clone());
+        boot.version_initialization.completed = false;
+        self.flush(&boot)
+            .map_err(|error| format!("persist boot.json: {error}"))
+    }
+
+    /// Mark the current app version initialized after all one-time steps succeed.
+    /// The same atomic boot.json write advances the previous successful version
+    /// so it remains available until this initialization has fully completed.
+    pub fn complete_version_initialization(&self) -> Result<(), String> {
+        let mut boot = self.write();
+        if boot.version_initialization.app_version.as_deref() != Some(self.app_version.as_str()) {
+            return Err("version initialization marker changed while running".to_string());
+        }
+        boot.version_initialization.completed = true;
+        boot.last_successful_app_version = Some(self.app_version.clone());
         self.flush(&boot)
             .map_err(|error| format!("persist boot.json: {error}"))
     }
 
-    /// Whether the first-run workspace onboarding has been completed.
-    ///
-    /// 与线上行为一致: 直接读 `boot.json`, 开发构建不再强制返回 false ——
-    /// 否则每次 `tauri:dev` 都会重走引导, 无法验证"完成一次后不再展示"。
-    /// 开发期想重现首次启动, 删掉 `~/.flowix/boot/boot.json` 里的
-    /// `is_onboarding_completed`(或整个文件) 即可。
-    pub fn is_onboarding_completed(&self) -> bool {
-        self.read().is_onboarding_completed
+    pub fn notebook_storage_reset_version(&self) -> u32 {
+        self.read().notebook_storage_reset_version
     }
 
-    /// Persist onboarding completion.
-    pub fn set_onboarding_completed(&self, completed: bool) -> Result<(), String> {
+    pub fn complete_notebook_storage_reset_version(&self, version: u32) -> Result<(), String> {
         let mut boot = self.write();
-        boot.is_onboarding_completed = completed;
+        boot.notebook_storage_reset_version = boot.notebook_storage_reset_version.max(version);
+        self.flush(&boot)
+            .map_err(|error| format!("persist boot.json: {error}"))
+    }
+
+    /// Whether the DeepSeek Harness introduction has already been displayed.
+    pub fn is_introduct_displayed(&self) -> bool {
+        self.read().is_introduct_displayed
+    }
+
+    /// Persist the DeepSeek Harness introduction display state.
+    pub fn set_introduct_displayed(&self, displayed: bool) -> Result<(), String> {
+        let mut boot = self.write();
+        boot.is_introduct_displayed = displayed;
         self.flush(&boot)
             .map_err(|error| format!("persist boot.json: {error}"))
     }
@@ -296,9 +372,11 @@ impl DeviceRegistry {
     fn fresh() -> BootFile {
         BootFile {
             schema_version: BOOT_SCHEMA_VERSION,
+            version_initialization: VersionInitializationState::default(),
+            last_successful_app_version: None,
+            notebook_storage_reset_version: 0,
             experimental: false,
             is_introduct_displayed: false,
-            is_onboarding_completed: false,
             user_info: UserInfo {
                 device_id: Uuid::new_v4(),
                 installed_at: Utc::now(),
@@ -431,7 +509,6 @@ mod tests {
         assert_eq!(b.schema_version, BOOT_SCHEMA_VERSION);
         assert!(!b.experimental);
         assert!(!b.is_introduct_displayed);
-        assert!(!b.is_onboarding_completed);
         assert!(!b.user_info.registered);
         assert_eq!(b.user_info.attempts, 0);
         assert!(b.user_info.registered_at.is_none());
@@ -444,11 +521,9 @@ mod tests {
         b.experimental = true;
         let s = serde_json::to_string(&b).unwrap();
         assert!(s.contains("\"is_introduct_displayed\":false"));
-        assert!(s.contains("\"is_onboarding_completed\":false"));
         let v: BootFile = serde_json::from_str(&s).unwrap();
         assert!(v.experimental);
         assert!(!v.is_introduct_displayed);
-        assert!(!v.is_onboarding_completed);
         assert_eq!(b.user_info.device_id, v.user_info.device_id);
         assert_eq!(b.user_info.installed_at, v.user_info.installed_at);
         assert_eq!(
@@ -476,49 +551,9 @@ mod tests {
         assert!(!boot.is_introduct_displayed);
     }
 
-    #[test]
-    fn missing_onboarding_completed_defaults_to_false() {
-        let mut value = serde_json::to_value(fresh_boot()).unwrap();
-        value
-            .as_object_mut()
-            .unwrap()
-            .remove("is_onboarding_completed");
-        let boot: BootFile = serde_json::from_value(value).unwrap();
-        assert!(!boot.is_onboarding_completed);
-    }
-
-    #[test]
-    fn onboarding_completion_survives_reload() {
-        // 线上行为: 完成一次就落盘, 重新加载后不再展示引导。
-        // (回归保护: 曾经 debug 构建读写两端都强制 false, 导致 dev 每次重走引导。)
-        //
-        // 注意用 `tempfile::tempdir()` 而不是 `tempdir_path()`: 后者返回的裸路径
-        // 既不当文件建也不当目录建, 而 `flush()` 会在其下再建 `boot/` —— 一旦与
-        // 其它用例的时间戳撞车 (macOS 上 `timestamp_nanos` 分辨率不足以区分并发
-        // 用例), 就会出现 "文件已存在" / "Not a directory" 的偶发失败。
-        let temp = tempfile::tempdir().unwrap();
-        let dir = temp.path();
-        let registry = DeviceRegistry::load(dir, "test-version");
-        assert!(!registry.is_onboarding_completed());
-
-        registry.set_onboarding_completed(true).unwrap();
-        assert!(registry.is_onboarding_completed());
-
-        let reloaded = DeviceRegistry::load(dir, "test-version");
-        assert!(
-            reloaded.is_onboarding_completed(),
-            "completion must be read back from boot.json, not reset per launch"
-        );
-
-        // 反向同样生效 (便于开发期手动重置)。
-        reloaded.set_onboarding_completed(false).unwrap();
-        assert!(!DeviceRegistry::load(dir, "test-version").is_onboarding_completed());
-    }
-
     #[test]
     fn intro_displayed_survives_reload() {
-        // 与 onboarding 同一条持久化路径, 一并锁住, 避免将来又被构建类型短路。
-        // 同上: 必须用独立临时目录, 不能复用 `tempdir_path()`。
+        // 必须用独立临时目录, 不能复用 `tempdir_path()`。
         let temp = tempfile::tempdir().unwrap();
         let dir = temp.path();
         let registry = DeviceRegistry::load(dir, "test-version");
diff --git a/app/flowix-desktop/src/document_derived.rs b/app/flowix-desktop/src/document_derived.rs
deleted file mode 100644
index e9ba72ece..000000000
--- a/app/flowix-desktop/src/document_derived.rs
+++ /dev/null
@@ -1,78 +0,0 @@
-//! One coalescing worker for derived search work, outside save receipts.
-use crate::app::state::AppState;
-use std::{
-    collections::BTreeMap,
-    sync::{Mutex, OnceLock},
-};
-use tauri::{AppHandle, Manager};
-
-struct Job {
-    app: AppHandle,
-    memo_id: String,
-}
-#[derive(Default)]
-struct Pending {
-    running: bool,
-    jobs: BTreeMap<String, Job>,
-}
-fn pending() -> &'static Mutex<Pending> {
-    static PENDING: OnceLock<Mutex<Pending>> = OnceLock::new();
-    PENDING.get_or_init(Mutex::default)
-}
-
-pub fn schedule(app: &AppHandle, memo_id: &str) {
-    let mut state = pending().lock().unwrap_or_else(|e| e.into_inner());
-    state.jobs.entry(memo_id.into()).or_insert_with(|| Job {
-        app: app.clone(),
-        memo_id: memo_id.into(),
-    });
-    if state.running {
-        return;
-    }
-    state.running = true;
-    drop(state);
-    tauri::async_runtime::spawn(async {
-        loop {
-            let job = {
-                let mut state = pending().lock().unwrap_or_else(|e| e.into_inner());
-                match state.jobs.pop_first() {
-                    Some((_, job)) => job,
-                    None => {
-                        state.running = false;
-                        break;
-                    }
-                }
-            };
-            let result = crate::document_io::run("derive", move || {
-                let state = job.app.state::<AppState>();
-                // A delayed local snapshot must not overwrite a newer external
-                // search update, or resurrect an entry deleted meanwhile.
-                // 旧 memo id → notebook + relative_path，再刷新 search index。
-                let target = crate::lock_utils::read_lock(&state.memo_file, "memo_file")
-                    .resolve_memo_location(&job.memo_id)
-                    .ok()
-                    .flatten()
-                    .map(|location| (location.notebook.id, location.memo.relative_path));
-                if let Some((notebook_id, relative_path)) = target {
-                }
-                Ok::<(), flowix_core::FlowixError>(())
-            })
-            .await;
-            match result {
-                Err(error) => tracing::error!("document derived worker failed: {error}"),
-                Ok(Err(error)) => tracing::error!("document derived work failed: {error}"),
-                Ok(Ok(())) => {}
-            }
-        }
-    });
-}
-
-pub async fn flush() -> bool {
-    for _ in 0..100 {
-        if !pending().lock().unwrap_or_else(|e| e.into_inner()).running {
-            return true;
-        }
-        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
-    }
-    false
-}
diff --git a/app/flowix-desktop/src/dsh.rs b/app/flowix-desktop/src/dsh.rs
index 1c71ddb91..900c1ebf0 100644
--- a/app/flowix-desktop/src/dsh.rs
+++ b/app/flowix-desktop/src/dsh.rs
@@ -20,6 +20,8 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::mpsc;
 use std::sync::{Arc, Mutex, OnceLock};
 use std::time::{Duration, Instant};
+#[cfg(not(debug_assertions))]
+use tauri::Manager;
 use tauri::{AppHandle, Emitter};
 
 use crate::app::paths::get_app_data_path;
@@ -27,6 +29,14 @@ use crate::app::paths::get_app_data_path;
 mod activation;
 mod archive;
 mod cleanup;
+pub(crate) mod cli;
+pub(crate) use cli::resolve_cli_launch;
+pub(crate) fn set_user_selected_cli(path: Option<PathBuf>) {
+    cli::set_user_selected_dsh_cli(path);
+}
+pub(crate) fn is_valid_cli_path(path: &Path) -> bool {
+    cli::is_valid_dsh_cli_path(path)
+}
 mod download;
 mod environment;
 mod manifest;
@@ -66,6 +76,10 @@ static DSH_DOWNLOAD_PROGRESS: OnceLock<Mutex<Option<DshDownloadProgress>>> = Onc
 #[serde(rename_all = "camelCase")]
 pub struct DshStatus {
     pub installed: bool,
+    pub local_installed: bool,
+    pub managed_installed: bool,
+    pub app_server_profile_installed: bool,
+    pub app_server_profile_update_available: bool,
     pub executable_path: Option<String>,
     pub version: Option<String>,
     pub harness_version: Option<String>,
@@ -208,33 +222,55 @@ pub struct ManagedDshLaunch {
 }
 
 pub fn status() -> DshStatus {
-    if let Some(result) = development_bundle_launch_spec() {
-        return match result {
-            Ok(launch) => DshStatus {
-                installed: true,
-                executable_path: Some(launch.executable.display().to_string()),
-                version: Some("dev".to_string()),
-                harness_version: harness_version_from_root(&launch.root),
-                source: Some("flowix-dev-bundle".to_string()),
-                profile: DEFAULT_PROFILE.to_string(),
-                message: None,
-                archive_size: None,
-            },
-            Err(message) => DshStatus {
-                installed: false,
-                executable_path: None,
-                version: None,
-                harness_version: None,
-                source: Some("flowix-dev-bundle".to_string()),
-                profile: DEFAULT_PROFILE.to_string(),
-                message: Some(message),
-                archive_size: None,
-            },
+    let development = development_bundle_launch_spec();
+    let local = local_dsh_executable();
+    let managed = current_installation();
+    let dsh_home = dsh_home_path();
+    let profile_owned = flowix_profile_owned(&dsh_home);
+    let app_server_profile_installed = flowix_profile_installed(&dsh_home);
+    let app_server_profile_update_available = profile_owned && !app_server_profile_installed;
+    if let Some(executable) = local.as_ref() {
+        let version = local_dsh_version(executable);
+        return DshStatus {
+            installed: true,
+            local_installed: true,
+            managed_installed: managed.is_some()
+                || development
+                    .as_ref()
+                    .map(|result| result.is_ok())
+                    .unwrap_or(false),
+            executable_path: Some(executable.display().to_string()),
+            version,
+            harness_version: None,
+            source: Some("local-cli".to_string()),
+            profile: DEFAULT_PROFILE.to_string(),
+            message: None,
+            archive_size: None,
+            app_server_profile_installed,
+            app_server_profile_update_available,
         };
     }
-    match current_installation() {
+    if let Some(Ok(launch)) = development.as_ref() {
+        return DshStatus {
+            installed: true,
+            local_installed: false,
+            managed_installed: true,
+            executable_path: Some(launch.executable.display().to_string()),
+            version: Some("dev".to_string()),
+            harness_version: harness_version_from_root(&launch.root),
+            source: Some("flowix-dev-bundle".to_string()),
+            profile: DEFAULT_PROFILE.to_string(),
+            message: None,
+            archive_size: None,
+            app_server_profile_installed,
+            app_server_profile_update_available,
+        };
+    }
+    match managed {
         Some(installation) => DshStatus {
             installed: true,
+            local_installed: false,
+            managed_installed: true,
             executable_path: Some(installation.host_path.display().to_string()),
             version: Some(installation.version.clone()),
             harness_version: installation.harness_version.clone(),
@@ -242,20 +278,422 @@ pub fn status() -> DshStatus {
             profile: DEFAULT_PROFILE.to_string(),
             message: None,
             archive_size: installation.archive_size,
+            app_server_profile_installed,
+            app_server_profile_update_available,
         },
         None => DshStatus {
             installed: false,
+            local_installed: false,
+            managed_installed: false,
             executable_path: None,
             version: None,
             harness_version: None,
             source: None,
             profile: DEFAULT_PROFILE.to_string(),
-            message: Some("DeepSeek Harness is not installed".to_string()),
+            message: development
+                .and_then(Result::err)
+                .or_else(|| Some("DeepSeek Harness is not installed".to_string())),
             archive_size: None,
+            app_server_profile_installed: false,
+            app_server_profile_update_available: false,
         },
     }
 }
 
+fn dsh_home_path() -> PathBuf {
+    crate::config::user::resolve_dsh_home(&dirs::home_dir().unwrap_or_else(|| PathBuf::from(".")))
+}
+
+pub(crate) fn flowix_profile_installed(dsh_home: &Path) -> bool {
+    flowix_profile_present(dsh_home)
+        && flowix_profile_version(dsh_home).as_deref() == Some(env!("CARGO_PKG_VERSION"))
+}
+
+fn flowix_profile_present(dsh_home: &Path) -> bool {
+    let profile = dsh_home.join("profiles").join(DEFAULT_PROFILE);
+    if !profile
+        .join("node_modules/dsh-appserver/src/cordis-plugin.js")
+        .is_file()
+        || !profile
+            .join("node_modules/dsh-flowix-memory/launcher.mjs")
+            .is_file()
+        || !profile.join("cordis.patch.yml").is_file()
+    {
+        return false;
+    }
+    let Ok(package_bytes) = fs::read(profile.join("package.json")) else {
+        return false;
+    };
+    let Ok(package) = serde_json::from_slice::<serde_json::Value>(&package_bytes) else {
+        return false;
+    };
+    package
+        .pointer("/dsh/profile/bundles")
+        .and_then(serde_json::Value::as_array)
+        .is_some_and(|bundles| {
+            ["dsh-appserver", "dsh-flowix-memory"]
+                .iter()
+                .all(|required| {
+                    bundles
+                        .iter()
+                        .any(|bundle| bundle.as_str() == Some(required))
+                })
+        })
+}
+
+fn flowix_profile_owned(dsh_home: &Path) -> bool {
+    let package = fs::read(
+        dsh_home
+            .join("profiles")
+            .join(DEFAULT_PROFILE)
+            .join("package.json"),
+    )
+    .ok()
+    .and_then(|bytes| serde_json::from_slice::<serde_json::Value>(&bytes).ok());
+    package
+        .as_ref()
+        .and_then(|package| package.get("name"))
+        .and_then(serde_json::Value::as_str)
+        == Some("dsh-profile-flowix")
+}
+
+fn flowix_profile_version(dsh_home: &Path) -> Option<String> {
+    let package = fs::read(
+        dsh_home
+            .join("profiles")
+            .join(DEFAULT_PROFILE)
+            .join("package.json"),
+    )
+    .ok()
+    .and_then(|bytes| serde_json::from_slice::<serde_json::Value>(&bytes).ok())?;
+    package
+        .pointer("/flowix/profileVersion")
+        .and_then(serde_json::Value::as_str)
+        .map(str::to_string)
+}
+
+fn local_dsh_executable() -> Option<PathBuf> {
+    cli::local_dsh_executable()
+}
+
+fn local_dsh_version(cli: &Path) -> Option<String> {
+    let canonical = fs::canonicalize(cli).unwrap_or_else(|_| cli.to_path_buf());
+    for executable in [canonical.as_path(), cli] {
+        let mut directory = executable.parent();
+        while let Some(current) = directory {
+            let manifest = current.join("package.json");
+            if let Ok(bytes) = fs::read(&manifest) {
+                if let Ok(package) = serde_json::from_slice::<serde_json::Value>(&bytes) {
+                    if package.get("name").and_then(serde_json::Value::as_str)
+                        == Some("@deepseek-ai/dsh")
+                    {
+                        if let Some(version) =
+                            package.get("version").and_then(serde_json::Value::as_str)
+                        {
+                            return Some(version.to_string());
+                        }
+                    }
+                }
+            }
+            for relative in [
+                Path::new("node_modules/@deepseek-ai/dsh/package.json"),
+                Path::new("lib/node_modules/@deepseek-ai/dsh/package.json"),
+            ] {
+                let manifest = current.join(relative);
+                if let Ok(bytes) = fs::read(manifest) {
+                    if let Ok(package) = serde_json::from_slice::<serde_json::Value>(&bytes) {
+                        if package.get("name").and_then(serde_json::Value::as_str)
+                            == Some("@deepseek-ai/dsh")
+                        {
+                            if let Some(version) =
+                                package.get("version").and_then(serde_json::Value::as_str)
+                            {
+                                return Some(version.to_string());
+                            }
+                        }
+                    }
+                }
+            }
+            directory = current.parent();
+        }
+    }
+    None
+}
+
+/// Install the Flowix App Server profile after an explicit user action.
+/// Startup only probes this state; it never calls this function implicitly.
+pub fn install_appserver_profile(app: &AppHandle) -> Result<DshStatus, String> {
+    let _operation_guard = try_acquire_operation_lock()?;
+    let current_status = status();
+    if !current_status.installed {
+        return Err("请先安装 DSH，再安装 Flowix App Server 插件".to_string());
+    }
+
+    let home = dsh_home_path();
+    let source = appserver_profile_resource(app)?;
+
+    install_profile_from_source(&home, &source)?;
+    Ok(status())
+}
+
+pub(crate) fn install_profile_from_source(home: &Path, source: &Path) -> Result<(), String> {
+    let target = home.join("profiles").join(DEFAULT_PROFILE);
+    let had_flowix_profile = target.exists();
+    if had_flowix_profile {
+        let package_path = target.join("package.json");
+        let package = fs::read(&package_path)
+            .ok()
+            .and_then(|bytes| serde_json::from_slice::<serde_json::Value>(&bytes).ok());
+        if package
+            .as_ref()
+            .and_then(|value| value.get("name"))
+            .and_then(serde_json::Value::as_str)
+            != Some("dsh-profile-flowix")
+        {
+            return Err(format!(
+                "DSH profile '{}' 已存在且不属于 Flowix；为避免覆盖用户配置，请先在 DSH 中更换 profile 名称",
+                DEFAULT_PROFILE
+            ));
+        }
+    }
+
+    let parent = target.parent().ok_or("invalid DSH profile path")?;
+    fs::create_dir_all(parent)
+        .map_err(|error| format!("create DSH profiles directory: {error}"))?;
+    let transaction_id = uuid::Uuid::new_v4();
+    let staging = parent.join(format!(".flowix-profile-install-{transaction_id}"));
+    let backup = parent.join(format!(".flowix-profile-backup-{transaction_id}"));
+    let staged = if had_flowix_profile {
+        copy_profile_tree(&target, &staging).and_then(|()| {
+            for bundle in ["dsh-appserver", "dsh-flowix-memory"] {
+                let installed = staging.join("node_modules").join(bundle);
+                if installed.exists() {
+                    fs::remove_dir_all(&installed)
+                        .map_err(|error| format!("replace Flowix DSH bundle {bundle}: {error}"))?;
+                }
+                copy_profile_tree(&source.join("node_modules").join(bundle), &installed)?;
+            }
+            merge_flowix_profile_package(
+                &staging.join("package.json"),
+                &source.join("package.json"),
+            )?;
+            repair_flowix_profile_patch(
+                &staging.join("cordis.patch.yml"),
+                &source.join("cordis.patch.yml"),
+            )
+            .and_then(|()| stamp_flowix_profile_version(&staging))
+        })
+    } else {
+        copy_profile_tree(&source, &staging).and_then(|()| stamp_flowix_profile_version(&staging))
+    };
+    if let Err(error) = staged {
+        let _ = fs::remove_dir_all(&staging);
+        return Err(error);
+    }
+    if target.exists() {
+        fs::rename(&target, &backup)
+            .map_err(|error| format!("preserve existing Flowix DSH profile: {error}"))?;
+    }
+    if let Err(error) = fs::rename(&staging, &target) {
+        let _ = fs::remove_dir_all(&staging);
+        if backup.exists() {
+            let _ = fs::rename(&backup, &target);
+        }
+        return Err(format!("publish Flowix DSH profile: {error}"));
+    }
+    if backup.exists() {
+        let _ = fs::remove_dir_all(&backup);
+    }
+    Ok(())
+}
+
+/// Add missing Flowix patch entries while preserving existing user settings.
+fn repair_flowix_profile_patch(target: &Path, source: &Path) -> Result<(), String> {
+    if !target.exists() {
+        fs::copy(source, target)
+            .map_err(|error| format!("restore Flowix profile patch: {error}"))?;
+        return Ok(());
+    }
+    let read_patch = |path: &Path| -> Result<Vec<serde_yaml::Value>, String> {
+        let bytes = fs::read(path).map_err(|error| format!("read DSH profile patch: {error}"))?;
+        serde_yaml::from_slice(&bytes).map_err(|error| format!("parse DSH profile patch: {error}"))
+    };
+    let mut patch = read_patch(target)?;
+    let required = read_patch(source)?;
+    let mut changed = false;
+    for entry in required {
+        let id = entry.get("id").and_then(serde_yaml::Value::as_str);
+        if let Some(id) = id {
+            if let Some(existing) = patch
+                .iter_mut()
+                .find(|existing| existing.get("id").and_then(serde_yaml::Value::as_str) == Some(id))
+            {
+                changed |= merge_required_patch_fields(existing, &entry);
+                continue;
+            }
+        }
+        // Entries without an id (e.g. insert operations) use structural equality.
+        if id.is_none() && patch.contains(&entry) {
+            continue;
+        }
+        patch.push(entry);
+        changed = true;
+    }
+    if changed {
+        let yaml = serde_yaml::to_string(&patch)
+            .map_err(|error| format!("serialize DSH profile patch: {error}"))?;
+        fs::write(target, yaml).map_err(|error| format!("repair DSH profile patch: {error}"))?;
+    }
+    Ok(())
+}
+
+/// Refresh Flowix-owned patch fields while retaining user-added fields and
+/// entries. Required values from the shipped patch take precedence.
+fn merge_required_patch_fields(
+    existing: &mut serde_yaml::Value,
+    required: &serde_yaml::Value,
+) -> bool {
+    match (existing, required) {
+        (serde_yaml::Value::Mapping(existing), serde_yaml::Value::Mapping(required)) => {
+            let mut changed = false;
+            for (key, required_value) in required {
+                if let Some(existing_value) = existing.get_mut(key) {
+                    changed |= merge_required_patch_fields(existing_value, required_value);
+                } else {
+                    existing.insert(key.clone(), required_value.clone());
+                    changed = true;
+                }
+            }
+            changed
+        }
+        (existing, required) if existing != required => {
+            *existing = required.clone();
+            true
+        }
+        _ => false,
+    }
+}
+
+fn merge_flowix_profile_package(target: &Path, source: &Path) -> Result<(), String> {
+    let mut target_json: serde_json::Value = serde_json::from_slice(
+        &fs::read(target).map_err(|error| format!("read existing DSH profile package: {error}"))?,
+    )
+    .map_err(|error| format!("parse existing DSH profile package: {error}"))?;
+    let source_json: serde_json::Value = serde_json::from_slice(
+        &fs::read(source).map_err(|error| format!("read Flowix DSH profile package: {error}"))?,
+    )
+    .map_err(|error| format!("parse Flowix DSH profile package: {error}"))?;
+    let bundles = target_json
+        .pointer_mut("/dsh/profile/bundles")
+        .and_then(serde_json::Value::as_array_mut)
+        .ok_or("existing Flowix DSH profile has no bundle list")?;
+    for required in [
+        "@deepseek-ai/dsh-base",
+        "dsh-appserver",
+        "dsh-flowix-memory",
+    ] {
+        if !bundles
+            .iter()
+            .any(|bundle| bundle.as_str() == Some(required))
+        {
+            bundles.push(serde_json::Value::String(required.to_string()));
+        }
+    }
+    if target_json
+        .get("name")
+        .and_then(serde_json::Value::as_str)
+        .is_none()
+    {
+        target_json["name"] = source_json["name"].clone();
+    }
+    fs::write(
+        target,
+        serde_json::to_vec_pretty(&target_json)
+            .map_err(|error| format!("serialize Flowix DSH profile package: {error}"))?,
+    )
+    .map_err(|error| format!("write Flowix DSH profile package: {error}"))
+}
+
+fn stamp_flowix_profile_version(profile: &Path) -> Result<(), String> {
+    let package_path = profile.join("package.json");
+    let mut package: serde_json::Value = serde_json::from_slice(
+        &fs::read(&package_path)
+            .map_err(|error| format!("read Flowix DSH profile package: {error}"))?,
+    )
+    .map_err(|error| format!("parse Flowix DSH profile package: {error}"))?;
+    package["flowix"]["profileVersion"] =
+        serde_json::Value::String(env!("CARGO_PKG_VERSION").to_string());
+    fs::write(
+        &package_path,
+        serde_json::to_vec_pretty(&package)
+            .map_err(|error| format!("serialize Flowix DSH profile package: {error}"))?,
+    )
+    .map_err(|error| format!("write Flowix DSH profile version: {error}"))
+}
+
+fn appserver_profile_resource(_app: &AppHandle) -> Result<PathBuf, String> {
+    #[cfg(debug_assertions)]
+    {
+        let repo = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+        let source = repo.join(".build/dsh-runtime-dev");
+        if source.is_dir() {
+            let platform = if cfg!(target_os = "macos") {
+                "macos"
+            } else if cfg!(target_os = "windows") {
+                "windows"
+            } else {
+                "linux"
+            };
+            let arch = if cfg!(target_arch = "aarch64") {
+                "arm64"
+            } else {
+                "x64"
+            };
+            let candidate = source.join(format!("node24-{platform}-{arch}/profile/flowix"));
+            if candidate.is_dir() {
+                return Ok(candidate);
+            }
+        }
+        let staged = repo.join(".build/dsh-appserver-profile/flowix");
+        for bundle in ["dsh-appserver", "dsh-flowix-memory"] {
+            let plugin_target = staged.join("node_modules").join(bundle);
+            if plugin_target.exists() {
+                fs::remove_dir_all(&plugin_target)
+                    .map_err(|error| format!("refresh local DSH bundle {bundle}: {error}"))?;
+            }
+            copy_profile_tree(&repo.join(bundle), &plugin_target)?;
+        }
+        fs::create_dir_all(&staged)
+            .map_err(|error| format!("create local DSH profile template: {error}"))?;
+        fs::copy(
+            repo.join("scripts/dsh-dev-profile.patch.yml"),
+            staged.join("cordis.patch.yml"),
+        )
+        .map_err(|error| format!("stage DSH App Server profile patch: {error}"))?;
+        fs::write(
+            staged.join("package.json"),
+            br#"{
+  "name": "dsh-profile-flowix",
+  "private": true,
+  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "dsh-appserver", "dsh-flowix-memory"] } }
+}
+"#,
+        )
+        .map_err(|error| format!("stage DSH App Server profile manifest: {error}"))?;
+        Ok(staged)
+    }
+    #[cfg(not(debug_assertions))]
+    {
+        let resource = _app
+            .path()
+            .resource_dir()
+            .ok()
+            .map(|root| root.join("dsh-profile/flowix"))
+            .filter(|path| path.is_dir());
+        resource.ok_or_else(|| "Flowix App Server installation files are missing".to_string())
+    }
+}
+
 /// Check the published DSH manifest without downloading or changing the
 /// installed runtime. Development bundles deliberately skip remote checks.
 pub fn check_for_update() -> Result<DshUpdateCheck, String> {
@@ -428,7 +866,6 @@ pub fn run_profile_plugin(
     package: Option<&str>,
 ) -> Result<String, String> {
     let _operation_guard = try_acquire_operation_lock()?;
-    let launch = managed_launch_spec().ok_or("DeepSeek Harness runtime is not installed")?;
     let action = action.trim();
     if !matches!(action, "add" | "remove" | "update") {
         return Err("unsupported DSH plugin action".to_string());
@@ -447,23 +884,18 @@ pub fn run_profile_plugin(
         return Err("invalid DSH plugin package spec".to_string());
     }
 
+    let mut args = vec!["plugin", "--profile", DEFAULT_PROFILE, action];
+    if let Some(package) = package {
+        args.push(package);
+    }
+    let launch = resolve_cli_launch(&args)?;
     let mut command = Command::new(&launch.executable);
     crate::process_window::hide_std_command_window(&mut command);
-    if let Some(cli) = launch.cli_entrypoint.as_ref() {
-        command.arg(cli);
-    } else {
-        command.env("DSH_EMBEDDED_CLI_MODE", "1");
-    }
     command
+        .args(&launch.args)
         .env_clear()
-        .envs(dsh_plugin_environment())
-        .envs(managed_child_environment(&launch.root))
-        .env("DSH_HOME", dsh_home)
-        .env("FLOWIX_DSH_ROOT", &launch.root)
-        .args(["plugin", "--profile", DEFAULT_PROFILE, action]);
-    if let Some(package) = package {
-        command.arg(package);
-    }
+        .envs(launch.environment)
+        .env("DSH_HOME", dsh_home);
     let output = command
         .output()
         .map_err(|error| format!("start official dsh plugin command: {error}"))?;
@@ -1376,7 +1808,7 @@ mod tests {
     use super::{
         archive::safe_archive_path, dsh_version_is_at_least, validate_manifest_version, DshArtifact,
     };
-    use std::path::Path;
+    use std::path::{Path, PathBuf};
 
     #[cfg(unix)]
     use super::DshManifest;
@@ -1402,6 +1834,59 @@ mod tests {
         assert_eq!(std::fs::read(&stale).unwrap(), b"b");
     }
 
+    #[test]
+    fn repairs_appserver_bundle_and_patch_in_an_existing_flowix_profile() {
+        let temp = tempfile::tempdir().unwrap();
+        let source = temp.path().join("source");
+        let home = temp.path().join("official-dsh-home");
+        let target = home.join("profiles/flowix");
+        std::fs::create_dir_all(source.join("node_modules/dsh-appserver/src")).unwrap();
+        std::fs::create_dir_all(source.join("node_modules/dsh-flowix-memory/src")).unwrap();
+        std::fs::create_dir_all(&target).unwrap();
+        std::fs::write(
+            source.join("node_modules/dsh-appserver/src/cordis-plugin.js"),
+            "export {};",
+        )
+        .unwrap();
+        std::fs::write(
+            source.join("node_modules/dsh-flowix-memory/src/index.js"),
+            "export {};",
+        )
+        .unwrap();
+        std::fs::write(source.join("package.json"), br#"{"name":"dsh-profile-flowix","private":true,"dsh":{"profile":{"bundles":["@deepseek-ai/dsh-base","dsh-appserver","dsh-flowix-memory"]}}}"#).unwrap();
+        let repo = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
+        let patch_source = repo.join("scripts/dsh-dev-profile.patch.yml");
+        std::fs::copy(&patch_source, source.join("cordis.patch.yml")).unwrap();
+        std::fs::write(target.join("package.json"), br#"{"name":"dsh-profile-flowix","dsh":{"profile":{"bundles":["@deepseek-ai/dsh-base"]}}}"#).unwrap();
+        std::fs::write(
+            target.join("cordis.patch.yml"),
+            "- id: user-custom-plugin\n  config:\n    enabled: true\n",
+        )
+        .unwrap();
+
+        super::install_profile_from_source(&home, &source).unwrap();
+        assert!(super::flowix_profile_installed(&home));
+        let package: serde_json::Value =
+            serde_json::from_slice(&std::fs::read(target.join("package.json")).unwrap()).unwrap();
+        let bundles = package
+            .pointer("/dsh/profile/bundles")
+            .unwrap()
+            .as_array()
+            .unwrap();
+        assert!(bundles.iter().any(|bundle| bundle == "dsh-appserver"));
+        let patch: Vec<serde_yaml::Value> =
+            serde_yaml::from_slice(&std::fs::read(target.join("cordis.patch.yml")).unwrap())
+                .unwrap();
+        assert!(patch
+            .iter()
+            .any(|entry| entry.get("id").and_then(serde_yaml::Value::as_str)
+                == Some("user-custom-plugin")));
+        assert!(patch
+            .iter()
+            .any(|entry| entry.get("id").and_then(serde_yaml::Value::as_str)
+                == Some("dsh-appserver-extension")));
+    }
+
     #[test]
     fn protects_only_flowix_profile_requirements_from_managed_removal() {
         assert!(super::is_required_flowix_profile_bundle(
diff --git a/app/flowix-desktop/src/dsh/cli.rs b/app/flowix-desktop/src/dsh/cli.rs
new file mode 100644
index 000000000..1b79e3bde
--- /dev/null
+++ b/app/flowix-desktop/src/dsh/cli.rs
@@ -0,0 +1,194 @@
+//! One CLI resolver and child environment for official and managed DSH.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{OnceLock, RwLock};
+
+use crate::agent_external::cli_resolver::{
+    is_executable_file, resolve_external_cli_uncached, ExternalCliSpec,
+};
+
+static USER_SELECTED_DSH_CLI: OnceLock<RwLock<Option<PathBuf>>> = OnceLock::new();
+
+pub(crate) fn set_user_selected_dsh_cli(path: Option<PathBuf>) {
+    if let Ok(mut selected) = USER_SELECTED_DSH_CLI
+        .get_or_init(|| RwLock::new(None))
+        .write()
+    {
+        *selected = path;
+    }
+}
+
+pub(crate) fn is_valid_dsh_cli_path(path: &Path) -> bool {
+    if is_executable_file(path) {
+        return true;
+    }
+    let is_node_script = path
+        .extension()
+        .and_then(|extension| extension.to_str())
+        .map(|extension| matches!(extension, "js" | "mjs" | "cjs"))
+        .unwrap_or(false);
+    is_node_script
+        && std::fs::metadata(path)
+            .map(|metadata| metadata.is_file())
+            .unwrap_or(false)
+}
+
+pub(crate) struct DshCliLaunch {
+    pub executable: PathBuf,
+    pub args: Vec<String>,
+    pub environment: HashMap<String, String>,
+}
+
+fn extra_candidates() -> Vec<PathBuf> {
+    let mut paths = vec![super::dsh_home_path().join("bin/dsh")];
+    if let Some(home) = dirs::home_dir() {
+        paths.push(home.join(".local/share/pnpm/dsh"));
+    }
+    paths
+}
+
+#[cfg(windows)]
+fn windows_candidates() -> Vec<PathBuf> {
+    let mut directories = std::env::var_os("PATH")
+        .map(|path| std::env::split_paths(&path).collect::<Vec<_>>())
+        .unwrap_or_default();
+    directories.push(super::dsh_home_path().join("bin"));
+    if let Some(app_data) = std::env::var_os("APPDATA") {
+        directories.push(PathBuf::from(app_data).join("npm"));
+    }
+    directories
+        .into_iter()
+        .flat_map(|directory| {
+            ["dsh.exe", "dsh.cmd", "dsh.bat"]
+                .into_iter()
+                .map(move |name| directory.join(name))
+        })
+        .collect()
+}
+
+pub(super) fn local_dsh_executable() -> Option<PathBuf> {
+    let selected = USER_SELECTED_DSH_CLI
+        .get_or_init(|| RwLock::new(None))
+        .read()
+        .ok()
+        .and_then(|selected| selected.clone())
+        .filter(|path| is_valid_dsh_cli_path(path));
+    if selected.is_some() {
+        return selected;
+    }
+    let path = resolve_external_cli_uncached(&ExternalCliSpec {
+        binary_name: "dsh",
+        #[cfg(windows)]
+        windows_binary_name: "dsh.cmd",
+        env_vars: &["FLOWIX_DSH_CLI_PATH"],
+        extra_unix_candidates: extra_candidates,
+        #[cfg(windows)]
+        extra_windows_candidates: windows_candidates,
+    });
+    path.is_absolute()
+        .then_some(path)
+        .filter(|path| is_executable_file(path))
+}
+
+fn local_node(cli: &Path) -> Option<PathBuf> {
+    if let Some(node) = std::env::var_os("FLOWIX_DSH_NODE_PATH")
+        .map(PathBuf::from)
+        .filter(|path| is_executable_file(path))
+    {
+        return Some(node);
+    }
+    // npm/nvm install their CLI shims alongside the matching Node binary.
+    let name = if cfg!(windows) { "node.exe" } else { "node" };
+    if let Some(node) = cli
+        .parent()
+        .map(|parent| parent.join(name))
+        .filter(|path| is_executable_file(path))
+    {
+        return Some(node);
+    }
+    if let Some(node) = crate::agent_external::node::resolve_node_binary("FLOWIX_DSH_NODE_PATH") {
+        return Some(node);
+    }
+    let node = resolve_external_cli_uncached(&ExternalCliSpec {
+        binary_name: "node",
+        #[cfg(windows)]
+        windows_binary_name: "node.exe",
+        env_vars: &["FLOWIX_DSH_NODE_PATH"],
+        extra_unix_candidates: crate::agent_external::cli_resolver::no_extra_candidates,
+        #[cfg(windows)]
+        extra_windows_candidates: crate::agent_external::cli_resolver::no_extra_candidates,
+    });
+    is_executable_file(&node).then_some(node)
+}
+
+pub(super) fn local_launch(cli: PathBuf, args: &[&str]) -> Result<DshCliLaunch, String> {
+    let mut environment = super::dsh_plugin_environment();
+    let node = local_node(&cli);
+    let key = if cfg!(windows) { "Path" } else { "PATH" };
+    let mut paths = cli
+        .parent()
+        .map(Path::to_path_buf)
+        .into_iter()
+        .collect::<Vec<_>>();
+    if let Some(parent) = node.as_ref().and_then(|node| node.parent()) {
+        paths.push(parent.to_path_buf());
+    }
+    if let Some(path) = std::env::var_os(key).or_else(|| std::env::var_os("PATH")) {
+        paths.extend(std::env::split_paths(&path));
+    }
+    let path =
+        std::env::join_paths(paths).map_err(|error| format!("prepare DSH CLI PATH: {error}"))?;
+    #[cfg(windows)]
+    environment.remove("PATH");
+    environment.insert(key.into(), path.to_string_lossy().into_owned());
+
+    let resolved = std::fs::canonicalize(&cli).unwrap_or_else(|_| cli.clone());
+    let mut cli_args = Vec::new();
+    let executable = match resolved
+        .extension()
+        .and_then(|extension| extension.to_str())
+    {
+        Some("js" | "mjs" | "cjs") => {
+            cli_args.push(resolved.to_string_lossy().into_owned());
+            node.ok_or("DSH requires Node.js; install Node.js or set FLOWIX_DSH_NODE_PATH")?
+        }
+        _ => cli,
+    };
+    cli_args.extend(args.iter().map(|arg| (*arg).to_string()));
+    Ok(DshCliLaunch {
+        executable,
+        args: cli_args,
+        environment,
+    })
+}
+
+pub(crate) fn resolve_cli_launch(args: &[&str]) -> Result<DshCliLaunch, String> {
+    if let Some(cli) = local_dsh_executable() {
+        return local_launch(cli, args);
+    }
+    let launch = super::managed_launch_spec().ok_or("DeepSeek Harness runtime is not installed")?;
+    let mut environment = super::dsh_plugin_environment();
+    environment.extend(super::managed_child_environment(&launch.root));
+    environment.insert(
+        "FLOWIX_DSH_ROOT".into(),
+        launch.root.to_string_lossy().into_owned(),
+    );
+    let mut cli_args = Vec::new();
+    if let Some(cli) = launch.cli_entrypoint {
+        cli_args.push(cli.to_string_lossy().into_owned());
+    } else {
+        environment.insert("DSH_EMBEDDED_CLI_MODE".into(), "1".into());
+    }
+    cli_args.extend(args.iter().map(|arg| (*arg).to_string()));
+    Ok(DshCliLaunch {
+        executable: launch.executable,
+        args: cli_args,
+        environment,
+    })
+}
+
+/// The explicit App Server command override keeps the same environment boundary.
+pub(crate) fn child_environment() -> HashMap<String, String> {
+    super::dsh_plugin_environment()
+}
diff --git a/app/flowix-desktop/src/lib.rs b/app/flowix-desktop/src/lib.rs
index 9a31f61b7..28d1ece7f 100644
--- a/app/flowix-desktop/src/lib.rs
+++ b/app/flowix-desktop/src/lib.rs
@@ -18,7 +18,6 @@ mod connection_probe;
 mod device_registration;
 mod document_mutation;
 mod document_io;
-mod document_derived;
 mod dsh;
 mod events;
 mod frame_scrollbar;
@@ -31,10 +30,12 @@ mod runtime_log;
 #[cfg(windows)]
 mod runtime_state;
 mod system_data;
+mod storage_initialization;
 mod template_store;
 mod update_security;
 mod watcher;
 mod window_chrome;
+mod native_close_region;
 
 pub use app::{get_app_data_path, get_user_config_dir, APP_DATA_DIR_NAME, USER_CONFIG_DIR_NAME};
 
diff --git a/app/flowix-desktop/src/maintenance/mod.rs b/app/flowix-desktop/src/maintenance/mod.rs
index 48db7493a..879320b44 100644
--- a/app/flowix-desktop/src/maintenance/mod.rs
+++ b/app/flowix-desktop/src/maintenance/mod.rs
@@ -28,7 +28,7 @@ pub(crate) fn spawn_startup_maintenance(
         if let Err(error) = debug_dumps::cleanup(&user_config_dir.join("debug")) {
             tracing::warn!("startup debug maintenance failed: {error}");
         }
-        if let Err(error) = backups::prune(&user_config_dir) {
+        if let Err(error) = backups::prune(&user_config_dir.join("db")) {
             tracing::warn!("startup backup maintenance failed: {error}");
         }
 
diff --git a/app/flowix-desktop/src/memo_events.rs b/app/flowix-desktop/src/memo_events.rs
index 4c5028b67..e3fd96569 100644
--- a/app/flowix-desktop/src/memo_events.rs
+++ b/app/flowix-desktop/src/memo_events.rs
@@ -1,8 +1,9 @@
-//! Unified memo event bus for UI, Agent, cloud, and external-editor writes.
+//! Event bus for writes that still use the legacy Memo-shaped domain model.
 //!
 //! Created, updated, and deleted mutations share `MEMO_EVENT`. Content
 //! commits carry revision/changeId metadata, while in-app editor writes also
 //! carry originWindowLabel so only sibling windows reload the committed bytes.
+//! Path-first notebook writes use `flowix:path-note-changed` instead.
 use serde::Serialize;
 use tauri::{AppHandle, Emitter, Manager};
 
@@ -12,8 +13,7 @@ use flowix_core::memo_file::Memo;
 
 pub const MEMO_EVENT: &str = "memo-event";
 
-/// 写者标�?—�?informational, 前�?不用于分�?��由�?///
-/// Plan B �?Agent 不再手动 emit, watcher �?Agent / 外部工具的�?�?/// 变更统一归到 `ExternalTool`。`AgentEdit` / `AgentWrite` 这两�?���?/// 已删�?(历史 comment 提到「前�?��用它分支�? 合并后�?义一�?�?
+/// MemoEvent 写者来源，供前端展示行为与诊断使用。
 #[derive(Serialize, Clone, Debug)]
 #[serde(rename_all = "snake_case")]
 pub enum MemoChangeSource {
@@ -27,8 +27,9 @@ pub enum MemoChangeSource {
     UserEdit,
     /// User explicitly deleted a note.
     UserDelete,
-    /// 外部编辑�?/ 其他 AI / Agent 改�?�? 文件监听器�?察到 ──
-    /// v3 鍚庢墍鏈夐潪鐢ㄦ埛涓诲姩淇濆瓨鐨勮矾寰勯兘鍚堝埌杩欓噷
+    /// Reserved for external-tool writes that still produce a MemoEvent.
+    /// Path-based Agent/CLI writes instead publish notebook path changes;
+    /// they do not fabricate a legacy Memo row.
     ExternalTool,
     /// Flowix Cloud pull applied this write locally. Automatic push scheduling
     /// must ignore this source to avoid a sync loop.
@@ -76,7 +77,7 @@ impl MemoDerivedChanged {
 #[derive(Serialize, Clone, Debug)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum MemoEvent {
-    /// 新笔记落�?(新建 / 拖拽 / 粘贴 / import / Agent write 新文�?
+    /// A note created through the legacy Memo-shaped command surface.
     Created {
         memo: Memo,
         #[serde(rename = "notebookId")]
@@ -89,7 +90,6 @@ pub enum MemoEvent {
     /// Agent edit / 外部工具改�?�?/ 收藏状态变�?。`path` 用于前�?编辑�?
     /// path 匹配�?
     Updated {
-        id: String,
         path: String,
         #[serde(rename = "notebookId")]
         notebook_id: String,
@@ -104,7 +104,6 @@ pub enum MemoEvent {
     },
     /// 笔�?�?���?(用户删除 / `clear_memos` / 外部工具 rm 文件)
     Deleted {
-        id: String,
         path: String,
         /// Notebook-relative path of the deleted note; the path-keyed
         /// identity that survives the deletion of the legacy id.
@@ -120,7 +119,7 @@ pub enum MemoEvent {
     /// 之前每个 affected memo 都发一次 Updated 的方案。后端已经批量改写
     /// 了所有受影响 memo 的 .md body + 同步了 memo index, 这里告诉前端:
     /// - 哪些路径被重命名 ([old, new], 可能多个 — move 整棵子树时一并改)
-    /// - 哪些 memo 的 tags 字段需要被前端局部 patch (affected_memo_ids)
+    /// - 哪些笔记的 tags 字段需要被前端局部 patch (affected_relative_paths)
     ///
     /// 跟 Updated 区别: 这是 metadata 操作, 不是单条 memo 写入。前端不
     /// 需要把 memo 整体替换 (body/preview/todos 都未变, 只有 tags 数组
@@ -144,13 +143,13 @@ pub enum MemoEvent {
     },
     /// 整棵 tag 子树删除完成 (delete_memo_tag IPC): 一次性发出, 替代
     /// 之前每个 affected memo 都发一次 Updated 的方案。后端已经从
-    /// memo_tags + memo index 移除所有相关条目, 也从 .md body 里清理了
+    /// notes.tags 投影移除相关条目, 也从 Markdown 中清理了标签来源
     /// `#tag` token, 这里告诉前端:
     /// - 哪些 tag 路径被删除 (deleted_tags, 含 tag_path 自身 + 子树)
-    /// - 哪些 memo 的 tags 字段需要被前端局部清理 (affected_memo_ids)
+    /// - 哪些笔记的 tags 字段需要被前端局部清理 (affected_relative_paths)
     ///
     /// 跟 TagsRenamed 是对称的姊妹事件, 但语义不同: rename 是改写 token,
-    /// delete 是移除 token。 前端 dispatch 路径用同一套 memo.ids 收窄,
+    /// delete 是移除 token。前端按相对路径定位受影响的笔记，
     /// 但处理逻辑不同 (rename → rebase, delete → filter out)。
     TagsDeleted {
         #[serde(rename = "notebookId")]
@@ -167,24 +166,6 @@ pub enum MemoEvent {
     },
 }
 
-impl MemoEvent {
-    /// 事件关联�?memo id。Deleted 总是�?id; Created �?memo 里拿; Updated
-    /// 直接读字段。没�?id (例�? unregister_memo_by_path 后的 Deleted) 返回
-    /// 当前�?��业务逻辑�?���?���? 保留作内部接口�?
-    pub(crate) fn memo_id(&self) -> &str {
-        match self {
-            MemoEvent::Created { memo, .. } => &memo.id,
-            MemoEvent::Updated { id, .. } => id,
-            MemoEvent::Deleted { id, .. } => id,
-            // TagsRenamed / TagsDeleted 不是单条 memo 事件; 调用方按
-            // affected_memo_ids 自行处理。 这里返回空串兜底 (不参与
-            // memo-event dedup 的 key)。
-            MemoEvent::TagsRenamed { .. } => "",
-            MemoEvent::TagsDeleted { .. } => "",
-        }
-    }
-}
-
 /// 触发 emit 的薄包�?。失败不 panic (let _ = 吞掉 emit 错�?, �?`agent-chunk`
 /// �?emit 风格保持一�?—IPC 通道关闭时不该�?业务逻辑�?�?///
 /// v3 改造后物理 rename 不再发生, 不再需�?id 二级兜底�?
@@ -237,27 +218,27 @@ pub(crate) fn emit_with_recorded_commit_from_window(
             ..
         } if !matches!(source, MemoChangeSource::CloudSync) => Some((
             notebook_id.clone(),
-            memo.id.clone(),
+            memo.relative_path.clone(),
             flowix_sync::LocalChangeKind::Put,
         )),
         MemoEvent::Updated {
-            id,
+            memo,
             notebook_id,
             source,
             ..
         } if !matches!(source, MemoChangeSource::CloudSync) => Some((
             notebook_id.clone(),
-            id.clone(),
+            memo.relative_path.clone(),
             flowix_sync::LocalChangeKind::Put,
         )),
         MemoEvent::Deleted {
-            id,
+            relative_path,
             notebook_id,
             source,
             ..
         } if !matches!(source, MemoChangeSource::CloudSync) => Some((
             notebook_id.clone(),
-            id.clone(),
+            relative_path.clone(),
             flowix_sync::LocalChangeKind::Delete,
         )),
         _ => None,
@@ -294,7 +275,7 @@ pub(crate) fn emit_with_recorded_commit_from_window(
                 _ => None,
             };
             let Some(relative_path) = relative_path else {
-                tracing::warn!(notebook_id, memo_id = %note_id, "cloud change has no valid notebook-relative path");
+                tracing::warn!(notebook_id, note_path = %note_id, "cloud change has no valid notebook-relative path");
                 return commit;
             };
             let note_id = flowix_sync::v2_path_note_id(&notebook_id, &relative_path);
@@ -425,7 +406,6 @@ fn emit_committed_via_dispatcher(
     commit: Option<&DocumentCommit>,
     origin_window_label: Option<&str>,
 ) {
-    let _ = event.memo_id();
     let payload = serde_json::to_value(MemoEventPayload {
         derived_only: false,
         event,
@@ -438,14 +418,13 @@ fn emit_committed_via_dispatcher(
 
 #[cfg(test)]
 mod tests {
-    //! serde wire-format 测试 —保证与前�?TypeScript 镜像 (app/flowix-web/types/memo.ts)
-    //! 的硬契约。`kind` 必须�?snake_case, 字�?命名 (memo/id/path/source) �?    //! �?IPC 边界的硬约定, 不�?随便改�?
+    //! Serde wire-format tests for the TypeScript MemoEvent mirror. Event fields
+    //! are the IPC contract; note entries are addressed by relative path.
     use super::*;
     use flowix_core::memo_file::Memo;
 
     fn sample_memo() -> Memo {
         Memo {
-            id: "abc123".to_string(),
             filename: "Sample.md".to_string(),
             relative_path: "Sample.md".to_string(),
             preview: "preview text".to_string(),
@@ -479,8 +458,8 @@ mod tests {
         assert_eq!(v["source"], "user_new");
         assert_eq!(v["notebookId"], "nb_default");
         assert_eq!(v["derivedChanged"]["tags"], true);
-        // memo 字�?保持 camelCase (Memo struct �?���?#[serde(rename = "createdAt")] �?
-        assert_eq!(v["memo"]["id"], "abc123");
+        assert_eq!(v["memo"]["relativePath"], "Sample.md");
+        assert!(v["memo"].get("id").is_none());
         assert_eq!(v["memo"]["filename"], "Sample.md");
         assert_eq!(v["memo"]["thumbnail"], "https://example.com/cover.png");
         assert_eq!(v["memo"]["createdAt"], 1_700_000_000_000i64);
@@ -489,7 +468,6 @@ mod tests {
     #[test]
     fn updated_serializes_with_snake_case_tag() {
         let event = MemoEvent::Updated {
-            id: "m_abc".to_string(),
             path: "/tmp/foo.md".to_string(),
             notebook_id: "nb_default".to_string(),
             memo: sample_memo(),
@@ -498,7 +476,7 @@ mod tests {
         };
         let v: serde_json::Value = serde_json::to_value(&event).unwrap();
         assert_eq!(v["kind"], "updated");
-        assert_eq!(v["id"], "m_abc");
+        assert!(v.get("id").is_none());
         assert_eq!(v["path"], "/tmp/foo.md");
         assert_eq!(v["source"], "external_tool");
     }
@@ -506,7 +484,6 @@ mod tests {
     #[test]
     fn committed_event_flattens_revision_contract_in_camel_case() {
         let event = MemoEvent::Updated {
-            id: "m_abc".to_string(),
             path: "/tmp/foo.md".to_string(),
             notebook_id: "nb_default".to_string(),
             memo: sample_memo(),
@@ -545,7 +522,6 @@ mod tests {
     #[test]
     fn deleted_serializes_with_snake_case_tag() {
         let event = MemoEvent::Deleted {
-            id: "m_abc".to_string(),
             path: "/tmp/foo.md".to_string(),
             relative_path: "foo.md".to_string(),
             notebook_id: "nb_default".to_string(),
@@ -558,7 +534,7 @@ mod tests {
         };
         let v: serde_json::Value = serde_json::to_value(&event).unwrap();
         assert_eq!(v["kind"], "deleted");
-        assert_eq!(v["id"], "m_abc");
+        assert!(v.get("id").is_none());
         assert_eq!(v["path"], "/tmp/foo.md");
         assert_eq!(v["notebookId"], "nb_default");
         assert_eq!(v["derivedChanged"]["todos"], true);
diff --git a/app/flowix-desktop/src/native_close_region.rs b/app/flowix-desktop/src/native_close_region.rs
new file mode 100644
index 000000000..6a098094f
--- /dev/null
+++ b/app/flowix-desktop/src/native_close_region.rs
@@ -0,0 +1,402 @@
+//! Renderer-independent mouse routing for the existing frameless close button.
+//! DOM owns appearance/geometry; a dedicated Raw Input thread observes clicks.
+//! Input is never suppressed; window-instance routing deduplicates JS/native intent.
+
+#[derive(Clone, Copy, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct CloseRegion {
+    pub right_inset: f64,
+    pub top: f64,
+    pub width: f64,
+    pub height: f64,
+}
+
+impl CloseRegion {
+    pub(crate) fn valid(self) -> bool {
+        [self.right_inset, self.top, self.width, self.height]
+            .iter()
+            .all(|n| n.is_finite())
+            && self.right_inset >= 0.0
+            && self.top >= 0.0
+            && self.width > 0.0
+            && self.height > 0.0
+            && self.width <= 256.0
+            && self.height <= 256.0
+            && self.top <= 256.0
+    }
+
+    #[cfg(any(windows, test))]
+    fn contains(self, x: f64, y: f64, client_width: f64, scale: f64) -> bool {
+        let right = client_width - self.right_inset * scale;
+        x >= right - self.width * scale
+            && x < right
+            && y >= self.top * scale
+            && y < (self.top + self.height) * scale
+    }
+}
+
+/// A route owns a window-instance callback, never a reusable window label.
+#[cfg(any(windows, test))]
+#[derive(Clone)]
+pub(crate) struct CloseRoute {
+    pub(crate) id: u64,
+    is_alive: std::sync::Arc<dyn Fn() -> bool + Send + Sync>,
+    callback: std::sync::Arc<dyn Fn(std::time::Instant) + Send + Sync>,
+}
+#[cfg(any(windows, test))]
+impl CloseRoute {
+    pub(crate) fn new(
+        id: u64,
+        is_alive: impl Fn() -> bool + Send + Sync + 'static,
+        callback: impl Fn(std::time::Instant) + Send + Sync + 'static,
+    ) -> Self {
+        Self {
+            id,
+            is_alive: std::sync::Arc::new(is_alive),
+            callback: std::sync::Arc::new(callback),
+        }
+    }
+    fn is_alive(&self) -> bool {
+        (self.is_alive)()
+    }
+    fn dispatch(&self, started: std::time::Instant) {
+        (self.callback)(started);
+    }
+}
+
+#[cfg(any(windows, test))]
+#[path = "native_input_health.rs"]
+mod health;
+#[cfg(windows)]
+pub(crate) use windows_impl::{remove, routing_ready, set, start};
+
+#[cfg(windows)]
+mod windows_impl {
+    use super::{health::RoutingHealth, CloseRegion, CloseRoute};
+    use std::{
+        collections::HashMap,
+        sync::{mpsc, Arc, Mutex, OnceLock},
+        time::{Duration, Instant},
+    };
+    use windows::{
+        core::w,
+        Win32::{
+            Foundation::{HWND, RECT},
+            Graphics::Gdi::ScreenToClient,
+            System::{SystemInformation::GetTickCount64, Threading::GetCurrentProcessId},
+            UI::{
+                HiDpi::{
+                    GetDpiForWindow, SetThreadDpiAwarenessContext,
+                    DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2,
+                },
+                Input::*,
+                WindowsAndMessaging::*,
+            },
+        },
+    };
+
+    #[derive(Clone)]
+    struct Entry {
+        route: CloseRoute,
+        revision: u64,
+        region: Option<CloseRegion>,
+        dpi: u32,
+    }
+    fn regions() -> &'static Mutex<HashMap<usize, Entry>> {
+        static REGIONS: OnceLock<Mutex<HashMap<usize, Entry>>> = OnceLock::new();
+        REGIONS.get_or_init(Mutex::default)
+    }
+    struct Router {
+        health: Arc<RoutingHealth>,
+    }
+    static ROUTER: OnceLock<Router> = OnceLock::new();
+
+    /// Raw Input is process-owned, read-only mouse input. It cannot be silently
+    /// removed by LowLevelHooksTimeout, and it never suppresses normal clicks.
+    /// This module must remain the application's only raw mouse registration.
+    pub(crate) fn start() -> Result<(), String> {
+        let router = ROUTER.get_or_init(|| {
+            let health = Arc::new(RoutingHealth::new());
+            let (sender, receiver) = mpsc::channel::<(CloseRoute, Instant)>();
+            std::thread::spawn(move || {
+                for (route, started) in receiver {
+                    // Blocking one Tauri dispatch cannot block input delivery.
+                    std::thread::spawn(move || route.dispatch(started));
+                }
+            });
+            let state = health.clone();
+            std::thread::spawn(move || loop {
+                state.retrying();
+                // Initialization and GetMessage failures are recoverable. The
+                // initialized singleton is never confused with active routing.
+                if unsafe { input_pump(&sender, &state) }.is_err() {
+                    state.retrying();
+                }
+                std::thread::sleep(Duration::from_secs(1));
+            });
+            Router { health }
+        });
+        // Give first registration a small startup opportunity; never wait for
+        // the UI thread or indefinitely block application startup.
+        let until = Instant::now() + Duration::from_millis(100);
+        while !router.health.ready(Instant::now()) && Instant::now() < until {
+            std::thread::sleep(Duration::from_millis(5));
+        }
+        if routing_ready() {
+            Ok(())
+        } else {
+            Err("Native close input is recovering; automatic retry is active".into())
+        }
+    }
+    pub(crate) fn routing_ready() -> bool {
+        ROUTER
+            .get()
+            .is_some_and(|router| router.health.ready(Instant::now()))
+    }
+
+    unsafe fn input_pump(
+        sender: &mpsc::Sender<(CloseRoute, Instant)>,
+        health: &RoutingHealth,
+    ) -> Result<(), String> {
+        if SetThreadDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)
+            .0
+            .is_null()
+        {
+            return Err("Per-monitor DPI awareness is unavailable for native close input".into());
+        }
+        let hwnd = CreateWindowExW(
+            WINDOW_EX_STYLE::default(),
+            w!("STATIC"),
+            w!("Flowix close input"),
+            WINDOW_STYLE::default(),
+            0,
+            0,
+            0,
+            0,
+            Some(HWND_MESSAGE),
+            None,
+            None,
+            None,
+        )
+        .map_err(|error| error.to_string())?;
+        let result = pump_registered(hwnd, sender, health);
+        health.retrying();
+        let _ = RegisterRawInputDevices(
+            &[RAWINPUTDEVICE {
+                usUsagePage: 1,
+                usUsage: 2,
+                dwFlags: RIDEV_REMOVE,
+                hwndTarget: HWND::default(),
+            }],
+            std::mem::size_of::<RAWINPUTDEVICE>() as u32,
+        );
+        let _ = DestroyWindow(hwnd);
+        result
+    }
+    unsafe fn pump_registered(
+        hwnd: HWND,
+        sender: &mpsc::Sender<(CloseRoute, Instant)>,
+        health: &RoutingHealth,
+    ) -> Result<(), String> {
+        RegisterRawInputDevices(
+            &[RAWINPUTDEVICE {
+                usUsagePage: 1,
+                usUsage: 2,
+                dwFlags: RIDEV_INPUTSINK,
+                hwndTarget: hwnd,
+            }],
+            std::mem::size_of::<RAWINPUTDEVICE>() as u32,
+        )
+        .map_err(|error| error.to_string())?;
+        if SetTimer(Some(hwnd), 1, 1000, None) == 0 {
+            return Err("Native input heartbeat unavailable".into());
+        }
+        health.heartbeat(Instant::now());
+        let mut pressed: Option<(usize, CloseRoute)> = None;
+        let mut message = MSG::default();
+        loop {
+            let result = GetMessageW(&mut message, None, 0, 0).0;
+            if result <= 0 {
+                return Err("Native input message pump stopped".into());
+            }
+            // Refresh on any message as well as the timer. Continuous mouse
+            // traffic can defer WM_TIMER because Windows queues timers last.
+            health.heartbeat(Instant::now());
+            if message.message == WM_INPUT {
+                let mut raw = RAWINPUT::default();
+                let mut size = std::mem::size_of::<RAWINPUT>() as u32;
+                let copied = GetRawInputData(
+                    HRAWINPUT(message.lParam.0 as _),
+                    RID_INPUT,
+                    Some((&mut raw as *mut RAWINPUT).cast()),
+                    &mut size,
+                    std::mem::size_of::<RAWINPUTHEADER>() as u32,
+                );
+                if copied != u32::MAX
+                    && copied >= std::mem::size_of::<RAWINPUT>() as u32
+                    && raw.header.dwType == RIM_TYPEMOUSE.0
+                {
+                    let flags = raw.data.mouse.Anonymous.Anonymous.usButtonFlags as u32;
+                    if flags & (RI_MOUSE_LEFT_BUTTON_DOWN | RI_MOUSE_LEFT_BUTTON_UP) != 0 {
+                        // MSG.pt/time are sampled when input was posted, rather
+                        // than using today's cursor position after queue delay.
+                        let hit = hit_region(message.pt);
+                        if flags & RI_MOUSE_LEFT_BUTTON_DOWN != 0 {
+                            pressed = hit.clone();
+                        }
+                        if flags & RI_MOUSE_LEFT_BUTTON_UP != 0 {
+                            if let Some((down, route)) = pressed.take() {
+                                if hit.is_some_and(|(up, entry)| up == down && entry.id == route.id)
+                                {
+                                    let age = (GetTickCount64() as u32).wrapping_sub(message.time);
+                                    let now = Instant::now();
+                                    let started = now
+                                        .checked_sub(Duration::from_millis(age as u64))
+                                        .unwrap_or(now);
+                                    let _ = sender.send((route, started));
+                                }
+                            }
+                        }
+                    }
+                }
+                // Raw Input foreground messages require native buffer cleanup.
+                DefWindowProcW(
+                    message.hwnd,
+                    message.message,
+                    message.wParam,
+                    message.lParam,
+                );
+            } else {
+                let _ = TranslateMessage(&message);
+                DispatchMessageW(&message);
+            }
+        }
+    }
+
+    unsafe fn hit_region(
+        mut point: windows::Win32::Foundation::POINT,
+    ) -> Option<(usize, CloseRoute)> {
+        let root = GetAncestor(WindowFromPoint(point), GA_ROOT);
+        let hwnd = root.0 as usize;
+        let mut process = 0;
+        GetWindowThreadProcessId(root, Some(&mut process));
+        if process != GetCurrentProcessId() {
+            return None;
+        }
+        let entry = regions().try_lock().ok()?.get(&hwnd)?.clone();
+        let region = entry.region?;
+        let mut client = RECT::default();
+        if !ScreenToClient(root, &mut point).as_bool() || GetClientRect(root, &mut client).is_err()
+        {
+            return None;
+        }
+        region
+            .contains(
+                point.x as f64,
+                point.y as f64,
+                client.right as f64,
+                GetDpiForWindow(root).max(96) as f64 / entry.dpi as f64,
+            )
+            .then_some((hwnd, entry.route))
+    }
+
+    pub(crate) fn set(
+        hwnd: usize,
+        route: CloseRoute,
+        revision: u64,
+        region: Option<CloseRegion>,
+    ) -> Result<(), String> {
+        if region.is_some_and(|region| !region.valid()) {
+            return Err("Invalid close region".into());
+        }
+        let mut process = 0;
+        unsafe {
+            GetWindowThreadProcessId(HWND(hwnd as _), Some(&mut process));
+        }
+        if process != unsafe { GetCurrentProcessId() } {
+            return Err("Close region is not an application window".into());
+        }
+        let dpi = unsafe { GetDpiForWindow(HWND(hwnd as _)) }.max(96);
+        let mut entries = regions().lock().unwrap_or_else(|e| e.into_inner());
+        // A delayed IPC from a destroyed window must not replace a new
+        // instance's route after Windows reuses the same HWND.
+        if !route.is_alive() {
+            return Err("Window has already been destroyed".into());
+        }
+        if entries
+            .get(&hwnd)
+            .is_some_and(|entry| entry.route.id == route.id && entry.revision >= revision)
+        {
+            return Ok(());
+        }
+        entries.insert(
+            hwnd,
+            Entry {
+                route,
+                revision,
+                region,
+                dpi,
+            },
+        );
+        Ok(())
+    }
+    pub(crate) fn remove(id: u64) {
+        regions()
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .retain(|_, entry| entry.route.id != id);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    };
+    fn button() -> CloseRegion {
+        CloseRegion {
+            right_inset: 0.0,
+            top: 0.0,
+            width: 42.0,
+            height: 36.0,
+        }
+    }
+    #[test]
+    fn close_does_not_capture_adjacent_maximize_or_content() {
+        let button = button();
+        assert!(button.contains(999.0, 35.0, 1000.0, 1.0));
+        assert!(!button.contains(957.0, 10.0, 1000.0, 1.0));
+        assert!(!button.contains(990.0, 36.0, 1000.0, 1.0));
+    }
+    #[test]
+    fn region_follows_resize_and_dpi_without_renderer_updates() {
+        assert!(button().contains(1999.0, 71.0, 2000.0, 2.0));
+        assert!(!button().contains(1915.0, 10.0, 2000.0, 2.0));
+        assert!(button().contains(499.0, 10.0, 500.0, 1.0));
+    }
+    #[test]
+    fn invalid_region_cannot_capture_window_content() {
+        assert!(!CloseRegion {
+            width: f64::NAN,
+            ..button()
+        }
+        .valid());
+        assert!(!CloseRegion {
+            height: 1000.0,
+            ..button()
+        }
+        .valid());
+    }
+
+    #[test]
+    fn captured_close_route_stops_accepting_input_after_its_window_dies() {
+        let alive = Arc::new(AtomicBool::new(true));
+        let route_alive = alive.clone();
+        let route = CloseRoute::new(7, move || route_alive.load(Ordering::Acquire), |_| {});
+        assert!(route.is_alive());
+        alive.store(false, Ordering::Release);
+        assert!(!route.is_alive());
+    }
+}
diff --git a/app/flowix-desktop/src/native_input_health.rs b/app/flowix-desktop/src/native_input_health.rs
new file mode 100644
index 000000000..3c46caa16
--- /dev/null
+++ b/app/flowix-desktop/src/native_input_health.rs
@@ -0,0 +1,58 @@
+//! Initialization is not availability. Heartbeats expire and retry can recover.
+use std::{
+    sync::Mutex,
+    time::{Duration, Instant},
+};
+
+pub(super) struct RoutingHealth {
+    last_heartbeat: Mutex<Option<Instant>>,
+}
+impl RoutingHealth {
+    pub(super) fn new() -> Self {
+        Self {
+            last_heartbeat: Mutex::new(None),
+        }
+    }
+    pub(super) fn retrying(&self) {
+        *self
+            .last_heartbeat
+            .lock()
+            .unwrap_or_else(|e| e.into_inner()) = None;
+    }
+    pub(super) fn heartbeat(&self, now: Instant) {
+        *self
+            .last_heartbeat
+            .lock()
+            .unwrap_or_else(|e| e.into_inner()) = Some(now);
+    }
+    pub(super) fn ready(&self, now: Instant) -> bool {
+        self.last_heartbeat
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .is_some_and(|last| now.saturating_duration_since(last) < Duration::from_secs(3))
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn failed_initialization_is_not_reported_as_ready_on_retry() {
+        let status = RoutingHealth::new();
+        let now = Instant::now();
+        status.retrying();
+        assert!(!status.ready(now));
+        status.retrying();
+        assert!(!status.ready(now));
+        status.heartbeat(now);
+        assert!(status.ready(now));
+    }
+    #[test]
+    fn stalled_pump_is_detected_and_a_recovered_pump_becomes_ready() {
+        let status = RoutingHealth::new();
+        let now = Instant::now();
+        status.heartbeat(now);
+        assert!(!status.ready(now + Duration::from_secs(4)));
+        status.heartbeat(now + Duration::from_secs(4));
+        assert!(status.ready(now + Duration::from_secs(4)));
+    }
+}
diff --git a/app/flowix-desktop/src/plugin.rs b/app/flowix-desktop/src/plugin.rs
index d3a114b26..bca86fb8f 100644
--- a/app/flowix-desktop/src/plugin.rs
+++ b/app/flowix-desktop/src/plugin.rs
@@ -119,7 +119,7 @@ pub fn emit_run_event(app_handle: &tauri::AppHandle, event: PluginRunEvent) -> R
 fn plugin_root() -> Result<PathBuf, String> {
     let home = dirs::home_dir().ok_or_else(|| "Home directory is unavailable".to_string())?;
     let root = get_user_config_dir(&home).join("plugin");
-    fs::create_dir_all(&root).map_err(|e| format!("create plugin directory: {e}"))?;
+    flowix_core::memo_file::ensure_storage_directory(&root).map_err(|e| format!("create plugin directory: {e}"))?;
     let metadata = fs::symlink_metadata(&root)
         .map_err(|error| format!("inspect plugin directory: {error}"))?;
     if metadata.file_type().is_symlink() || !metadata.is_dir() {
@@ -169,43 +169,38 @@ fn ensure_builtin_plugin(
     let plugin = root.join(plugin_id);
     match fs::symlink_metadata(&plugin) {
         Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
-            return Err(format!("built-in {plugin_id} plugin path is invalid"));
+            flowix_core::memo_file::backup_storage_file(&plugin)
+                .map_err(|error| error.to_string())?;
+            fs::create_dir_all(&plugin).map_err(|error| error.to_string())?;
         }
+        // Existing files stay untouched; missing files use fresh-install assets.
         Ok(_) => {}
         Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
             fs::create_dir_all(&plugin).map_err(|e| format!("create {plugin_id} plugin: {e}"))?;
         }
         Err(error) => return Err(format!("inspect {plugin_id} plugin: {error}")),
     }
-    let manifest = plugin.join("plugin.json");
-    // The built-in plugin is versioned with the host application.  Older
-    // installations may still have the pre-declaration manifest (including
-    // the removed agent selector), which would fail validation and silently
-    // disappear from the sidebar.  Reconcile it on every startup so the
-    // built-in definition is migrated before plugin discovery runs.
-    let needs_manifest_migration = match fs::read_to_string(&manifest) {
-        Ok(existing) => existing != expected_manifest,
-        Err(error) if error.kind() == std::io::ErrorKind::NotFound => true,
-        Err(error) => {
-            return Err(format!("read {plugin_id} manifest: {error}"));
+    for (name, content) in [
+        ("plugin.json", expected_manifest),
+        ("SKILL.md", expected_skill),
+    ] {
+        let path = plugin.join(name);
+        match fs::read(&path) {
+            Ok(bytes) if bytes == content.as_bytes() => continue,
+            Ok(_) => {
+                flowix_core::memo_file::backup_storage_file(&path)
+                    .map_err(|error| error.to_string())?;
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => return Err(format!("read {plugin_id} {name}: {error}")),
         }
-    };
-    if needs_manifest_migration {
-        fs::write(&manifest, expected_manifest)
-            .map_err(|e| format!("write {plugin_id} manifest: {e}"))?;
-    }
-    let skill = plugin.join("SKILL.md");
-    let needs_skill_migration = match fs::read_to_string(&skill) {
-        Ok(existing) => existing != expected_skill,
-        Err(error) if error.kind() == std::io::ErrorKind::NotFound => true,
-        Err(error) => return Err(format!("read {plugin_id} skill: {error}")),
-    };
-    if needs_skill_migration {
-        fs::write(&skill, expected_skill).map_err(|e| format!("write {plugin_id} skill: {e}"))?;
+        flowix_core::memo_file::atomic_create_bytes(&path, content.as_bytes())
+            .map_err(|error| format!("create {plugin_id} {name}: {error}"))?;
     }
     Ok(())
 }
 
+
 fn read_plugin(path: &Path) -> Result<PluginDescriptor, String> {
     let expected_id = path
         .file_name()
@@ -509,7 +504,8 @@ fn scan_plugin_catalog() -> Result<PluginCatalogSnapshot, String> {
     };
     for entry in fs::read_dir(&root).map_err(|e| format!("scan plugins: {e}"))? {
         let entry = entry.map_err(|e| format!("scan plugin entry: {e}"))?;
-        if !entry.path().is_dir() || entry.file_name().to_string_lossy().starts_with('.') {
+        if !entry.path().is_dir() || entry.file_name().to_string_lossy().starts_with('.')
+            || entry.file_name() == "rebuild-backups" {
             continue;
         }
         match read_plugin(&entry.path()) {
@@ -784,6 +780,24 @@ mod tests {
         PluginRuntime, MINDMAP_MANIFEST, MINDMAP_SKILL,
     };
 
+    #[test]
+    fn missing_runtime_dependencies_recreate_invalid_plugin_files() {
+        let temp = tempfile::tempdir().unwrap();
+        super::ensure_builtin_plugin(temp.path(), "mindmap", MINDMAP_MANIFEST, MINDMAP_SKILL).unwrap();
+        let dir = temp.path().join("mindmap");
+        std::fs::write(dir.join("plugin.json"), "existing manifest").unwrap();
+        std::fs::remove_file(dir.join("SKILL.md")).unwrap();
+        super::ensure_builtin_plugin(temp.path(), "mindmap", MINDMAP_MANIFEST, MINDMAP_SKILL).unwrap();
+        assert_eq!(
+            std::fs::read_to_string(dir.join("plugin.json")).unwrap(),
+            MINDMAP_MANIFEST
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.join("SKILL.md")).unwrap(),
+            MINDMAP_SKILL
+        );
+    }
+
     #[test]
     fn plugin_workspace_requires_a_registered_root_before_execution() {
         use flowix_core::memo_file::{MemoFile, NotebookConfig};
diff --git a/app/flowix-desktop/src/runtime_state.rs b/app/flowix-desktop/src/runtime_state.rs
index 7a9c7378c..becc5bf1e 100644
--- a/app/flowix-desktop/src/runtime_state.rs
+++ b/app/flowix-desktop/src/runtime_state.rs
@@ -1,183 +1,8 @@
 //! Mutable Windows state must not share the executable installation directory.
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 pub fn windows_state_dir() -> Result<PathBuf, String> {
     std::env::var_os("LOCALAPPDATA")
         .map(|root| PathBuf::from(root).join("FlowixData"))
         .ok_or_else(|| "LOCALAPPDATA is unavailable".to_string())
 }
-
-pub fn migrate_pi_sessions(local_data: &Path) -> Result<PathBuf, String> {
-    let old = local_data.join("Flowix").join("pi-sessions");
-    let new = local_data.join("FlowixData").join("pi-sessions");
-    if old.exists() {
-        if new.exists() {
-            // Coexisting stores are resolved per conversation without merging.
-            return Ok(new);
-        }
-        std::fs::create_dir_all(new.parent().unwrap()).map_err(|e| e.to_string())?;
-        // Move only this known data directory. Never overwrite, merge or remove
-        // installation files. Failure leaves the legacy data available.
-        std::fs::rename(&old, &new).map_err(|e| {
-            format!(
-                "Cannot migrate Pi sessions from {} to {}: {e}",
-                old.display(),
-                new.display()
-            )
-        })?;
-    }
-    Ok(new)
-}
-
-/// Select existing history in place, without overwriting or hiding a conflict.
-pub fn resolve_pi_session_candidates(candidates: &[PathBuf]) -> Result<PathBuf, String> {
-    let mut selected: Option<&PathBuf> = None;
-    for candidate in candidates {
-        if candidate.try_exists().map_err(|error| {
-            format!(
-                "cannot inspect Pi session directory {}: {error}",
-                candidate.display()
-            )
-        })? {
-            if let Some(previous) = selected {
-                return Err(format!(
-                    "Pi conversation has histories at both {} and {}; preserve both and resolve this conversation's conflict before continuing",
-                    previous.display(), candidate.display()
-                ));
-            }
-            selected = Some(candidate);
-        }
-    }
-    selected
-        .or_else(|| candidates.first())
-        .cloned()
-        .ok_or_else(|| "Pi session has no candidate directory".to_string())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    struct Fixture(PathBuf);
-    impl Fixture {
-        fn new() -> Self {
-            let path = std::env::temp_dir().join(format!(
-                "flowix-state-{}-{}",
-                std::process::id(),
-                std::time::SystemTime::now()
-                    .duration_since(std::time::UNIX_EPOCH)
-                    .unwrap()
-                    .as_nanos()
-            ));
-            std::fs::create_dir_all(&path).unwrap();
-            Self(path)
-        }
-    }
-    impl Drop for Fixture {
-        fn drop(&mut self) {
-            let _ = std::fs::remove_dir_all(&self.0);
-        }
-    }
-    #[test]
-    fn migrates_nested_sessions_once_without_touching_program_files() {
-        let f = Fixture::new();
-        let old = f.0.join("Flowix/pi-sessions/thread");
-        std::fs::create_dir_all(&old).unwrap();
-        std::fs::write(old.join("history.jsonl"), b"saved conversation").unwrap();
-        std::fs::write(f.0.join("Flowix/Flowix.exe"), b"program").unwrap();
-        let new = migrate_pi_sessions(&f.0).unwrap();
-        assert_eq!(
-            std::fs::read(new.join("thread/history.jsonl")).unwrap(),
-            b"saved conversation"
-        );
-        assert_eq!(migrate_pi_sessions(&f.0).unwrap(), new);
-        assert_eq!(
-            std::fs::read(f.0.join("Flowix/Flowix.exe")).unwrap(),
-            b"program"
-        );
-    }
-    #[test]
-    fn never_overwrites_an_existing_session_store() {
-        let f = Fixture::new();
-        for base in ["Flowix", "FlowixData"] {
-            let dir = f.0.join(base).join("pi-sessions");
-            std::fs::create_dir_all(&dir).unwrap();
-            std::fs::write(dir.join("session"), base).unwrap();
-        }
-        assert_eq!(
-            migrate_pi_sessions(&f.0).unwrap(),
-            f.0.join("FlowixData/pi-sessions")
-        );
-        assert_eq!(
-            std::fs::read(f.0.join("Flowix/pi-sessions/session")).unwrap(),
-            b"Flowix"
-        );
-        assert_eq!(
-            std::fs::read(f.0.join("FlowixData/pi-sessions/session")).unwrap(),
-            b"FlowixData"
-        );
-    }
-
-    #[test]
-    fn coexisting_stores_resolve_distinct_conversations_and_new_sessions() {
-        let f = Fixture::new();
-        let old_root = f.0.join("Flowix/pi-sessions");
-        let new_root = f.0.join("FlowixData/pi-sessions");
-        std::fs::create_dir_all(old_root.join("old-thread")).unwrap();
-        std::fs::create_dir_all(new_root.join("new-thread")).unwrap();
-        assert_eq!(migrate_pi_sessions(&f.0).unwrap(), new_root);
-        assert_eq!(migrate_pi_sessions(&f.0).unwrap(), new_root);
-        for (name, expected) in [
-            ("old-thread", old_root.join("old-thread")),
-            ("new-thread", new_root.join("new-thread")),
-            ("fresh", new_root.join("fresh")),
-        ] {
-            assert_eq!(
-                resolve_pi_session_candidates(&[new_root.join(name), old_root.join(name)]).unwrap(),
-                expected
-            );
-        }
-        assert!(!new_root.join("old-thread").exists());
-        assert!(!new_root.join("fresh").exists());
-    }
-
-    #[test]
-    fn duplicate_conversation_preserves_both_histories() {
-        let f = Fixture::new();
-        let candidates = [f.0.join("new/thread"), f.0.join("old/thread")];
-        for (index, path) in candidates.iter().enumerate() {
-            std::fs::create_dir_all(path).unwrap();
-            std::fs::write(path.join("history.jsonl"), index.to_string()).unwrap();
-        }
-        assert!(resolve_pi_session_candidates(&candidates)
-            .unwrap_err()
-            .contains("both"));
-        for (index, path) in candidates.iter().enumerate() {
-            assert_eq!(
-                std::fs::read_to_string(path.join("history.jsonl")).unwrap(),
-                index.to_string()
-            );
-        }
-    }
-
-    #[test]
-    fn legacy_hash_directory_remains_accessible_without_renaming() {
-        let f = Fixture::new();
-        let candidates = [
-            f.0.join("FlowixData/pi-sessions/stable"),
-            f.0.join("FlowixData/pi-sessions/legacy"),
-            f.0.join("Flowix/pi-sessions/stable"),
-            f.0.join("Flowix/pi-sessions/legacy"),
-        ];
-        std::fs::create_dir_all(&candidates[3]).unwrap();
-        std::fs::write(candidates[3].join("history.jsonl"), b"legacy").unwrap();
-        assert_eq!(
-            resolve_pi_session_candidates(&candidates).unwrap(),
-            candidates[3]
-        );
-        assert_eq!(
-            std::fs::read(candidates[3].join("history.jsonl")).unwrap(),
-            b"legacy"
-        );
-        assert!(!candidates[0].exists());
-    }
-}
diff --git a/app/flowix-desktop/src/storage_initialization.rs b/app/flowix-desktop/src/storage_initialization.rs
new file mode 100644
index 000000000..680e9f6b3
--- /dev/null
+++ b/app/flowix-desktop/src/storage_initialization.rs
@@ -0,0 +1,732 @@
+//! One-time cleanup and rebuilding of legacy user storage.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use flowix_core::memo_file::{MemoFile, NotebookConfig, NotebookInitializationJob};
+use rusqlite::Connection;
+
+use crate::device_registration::DeviceRegistry;
+
+const NOTEBOOK_STORAGE_RESET_VERSION: u32 = 1;
+// An interruption signal, not a completion record. Keep it until the single
+// reset job completion has been persisted in local.db.
+const NOTEBOOK_RESET_PENDING_FILE: &str = "storage-reset-pending";
+
+pub const CONFIG_LOCAL_MIGRATIONS_JOB: &str = "config_local_migrations_v1";
+
+#[derive(Clone, Copy)]
+enum GlobalInitializationJob {
+    AgentLayout,
+    LocalConfiguration,
+    WatcherSettings,
+    Templates,
+}
+
+impl GlobalInitializationJob {
+    const ALL: [Self; 4] = [
+        Self::AgentLayout,
+        Self::LocalConfiguration,
+        Self::WatcherSettings,
+        Self::Templates,
+    ];
+
+    fn key(self) -> &'static str {
+        match self {
+            Self::AgentLayout => "config_dsh_layout_v2",
+            Self::LocalConfiguration => CONFIG_LOCAL_MIGRATIONS_JOB,
+            Self::WatcherSettings => "config_watcher_exclusions_v1",
+            Self::Templates => "templates_v1",
+        }
+    }
+
+    fn is_optional(self) -> bool {
+        matches!(
+            self,
+            Self::AgentLayout | Self::WatcherSettings | Self::Templates
+        )
+    }
+
+    fn run(
+        self,
+        user_config: &crate::config::UserConfigStore,
+        user_config_dir: &Path,
+    ) -> Result<(), String> {
+        match self {
+            Self::AgentLayout => user_config.initialize_legacy_dsh_layout(),
+            Self::LocalConfiguration => user_config.initialize_legacy_config_migrations(),
+            Self::WatcherSettings => user_config
+                .clear_legacy_watcher_exclusions()
+                .map_err(|error| format!("clear legacy watcher exclusions failed: {error}")),
+            Self::Templates => crate::template_store::initialize(user_config_dir)
+                .map_err(|error| format!("initialize templates failed: {error}")),
+        }
+    }
+}
+
+const RETIRED_INITIALIZATION_JOB_IDS: [&str; 6] = [
+    "storage_reset_v1:plugin",
+    "storage_reset_v1:notebook_settings",
+    "storage_reset_v1:index",
+    "storage_reset_v1:recovery",
+    "storage_reset_v1:db_artifacts",
+    "builtin_plugins_v1",
+];
+
+/// Move global databases before any store opens a connection.
+pub fn prepare_database_paths(config_dir: &Path) -> io::Result<PathBuf> {
+    let database_dir = flowix_core::memo_file::prepare_database_directory(
+        config_dir,
+        &["local.db", "sync.db", "thread.db", "default.db"],
+    )?;
+    // Credentials in the secret store must remain private after VACUUM INTO
+    // publishes the migrated snapshot.
+    #[cfg(unix)]
+    if database_dir.join("default.db").is_file() {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(
+            database_dir.join("default.db"),
+            fs::Permissions::from_mode(0o600),
+        )?;
+    }
+    Ok(database_dir)
+}
+
+/// Retire the unused global index only after current storage initialization succeeds.
+/// Preserve both layouts and SQLite companions for manual recovery; never open or
+/// import the retired database. Cleanup failures never block initialization.
+pub fn retire_global_index_databases(config_dir: &Path) {
+    for path in [config_dir.join("index.db"), config_dir.join("db/index.db")] {
+        if let Err(error) = flowix_core::memo_file::backup_database(&path) {
+            tracing::warn!(path = %path.display(), %error, "skipping retired index cleanup");
+        }
+    }
+}
+
+/// Run unfinished one-time initialization jobs and retry notebooks that were
+/// offline when initialization first ran. Notebook content is never removed.
+pub fn initialize_legacy_storage(
+    device_registry: &DeviceRegistry,
+    memo_file: &MemoFile,
+    user_config: &crate::config::UserConfigStore,
+    user_config_dir: &Path,
+    app_data_dir: &Path,
+) -> Result<(), String> {
+    initialize_legacy_storage_with_progress(
+        device_registry,
+        memo_file,
+        user_config,
+        user_config_dir,
+        app_data_dir,
+        |_, _, _| {},
+    )
+}
+
+pub fn initialize_legacy_storage_with_progress(
+    device_registry: &DeviceRegistry,
+    memo_file: &MemoFile,
+    user_config: &crate::config::UserConfigStore,
+    user_config_dir: &Path,
+    _app_data_dir: &Path,
+    mut report: impl FnMut(usize, usize, &str),
+) -> Result<(), String> {
+    let notebooks = memo_file
+        .read_notebook_configs()
+        .map_err(|error| error.to_string())?;
+    // Four global jobs, six retired markers, and the per-notebook jobs.
+    // Offline notebook jobs resolve as deferred units instead of stalling progress.
+    let total = GlobalInitializationJob::ALL.len()
+        + RETIRED_INITIALIZATION_JOB_IDS.len()
+        + notebooks.len() * NotebookInitializationJob::ALL.len();
+    let mut completed = 0usize;
+    for job in GlobalInitializationJob::ALL {
+        let result = run_job_with_progress(
+            memo_file,
+            job.key(),
+            || job.run(user_config, user_config_dir),
+            &mut report,
+            &mut completed,
+            total,
+        );
+        if let Err(error) = result {
+            if !job.is_optional() {
+                return Err(error);
+            }
+            tracing::warn!(job_id = job.key(), %error, "optional initialization job deferred");
+        }
+    }
+    let reset_version = device_registry.notebook_storage_reset_version();
+    // Missing completion records are not permission to delete surviving data.
+    // Retire the old global cleanup jobs; fresh installs and rebuilt registries
+    // now create only the dependencies they need.
+    for key in RETIRED_INITIALIZATION_JOB_IDS {
+        report(completed, total, key);
+        memo_file
+            .mark_local_migration_completed(key)
+            .map_err(|error| error.to_string())?;
+        completed += 1;
+        report(completed, total, key);
+    }
+
+    reset_pending_notebooks_with_progress(
+        memo_file,
+        &notebooks,
+        &mut report,
+        &mut completed,
+        total,
+    )?;
+    if reset_version < NOTEBOOK_STORAGE_RESET_VERSION {
+        device_registry.complete_notebook_storage_reset_version(NOTEBOOK_STORAGE_RESET_VERSION)?;
+    }
+    tracing::info!(
+        completed_reset_version = reset_version.max(NOTEBOOK_STORAGE_RESET_VERSION),
+        "legacy notebook storage reset completed"
+    );
+    Ok(())
+}
+
+fn run_job_with_progress(
+    memo_file: &MemoFile,
+    key: &str,
+    operation: impl FnOnce() -> Result<(), String>,
+    report: &mut impl FnMut(usize, usize, &str),
+    completed: &mut usize,
+    total: usize,
+) -> Result<(), String> {
+    report(*completed, total, key);
+    let result = run_job(memo_file, key, operation);
+    *completed += 1;
+    report(*completed, total, key);
+    result
+}
+
+fn run_job(
+    memo_file: &MemoFile,
+    key: &str,
+    operation: impl FnOnce() -> Result<(), String>,
+) -> Result<(), String> {
+    if memo_file
+        .local_migration_completed(key)
+        .map_err(|error| format!("read initialization job {key} progress failed: {error}"))?
+    {
+        tracing::debug!(job_id = key, "initialization job already completed");
+        return Ok(());
+    }
+    let started = std::time::Instant::now();
+    tracing::info!(job_id = key, "initialization job started");
+    if let Err(error) = operation() {
+        crate::runtime_log::record_event(
+            "error",
+            "startup.job_failed",
+            serde_json::json!({
+                "jobId": key, "error": error, "elapsedMs": started.elapsed().as_millis()
+            })
+            .to_string(),
+        );
+        return Err(format!("initialization job {key} failed: {error}"));
+    }
+    memo_file
+        .mark_local_migration_completed(key)
+        .map_err(|error| format!("record initialization job {key} completion failed: {error}"))?;
+    tracing::info!(job_id = key, "initialization job completed");
+    Ok(())
+}
+
+fn reset_pending_notebooks(memo_file: &MemoFile) -> Result<(), String> {
+    let notebooks = memo_file
+        .read_notebook_configs()
+        .map_err(|error| format!("read notebooks for storage reset retry failed: {error}"))?;
+    let total = notebooks.len() * NotebookInitializationJob::ALL.len();
+    let mut completed = 0;
+    reset_pending_notebooks_with_progress(
+        memo_file,
+        &notebooks,
+        &mut |_, _, _| {},
+        &mut completed,
+        total,
+    )
+}
+
+fn reset_pending_notebooks_with_progress(
+    memo_file: &MemoFile,
+    notebooks: &[NotebookConfig],
+    report: &mut impl FnMut(usize, usize, &str),
+    completed: &mut usize,
+    total: usize,
+) -> Result<(), String> {
+    for notebook in notebooks {
+        for (job_index, job) in NotebookInitializationJob::ALL.into_iter().enumerate() {
+            let key = job.key(&notebook.id);
+            if memo_file
+                .local_migration_completed(&key)
+                .map_err(|error| error.to_string())?
+            {
+                // This job is recorded once, but notebook schemas evolve over
+                // time. Re-run the idempotent schema initializers on every
+                // startup so existing notebooks receive newer columns and
+                // data migrations after the one-time job has completed.
+                if matches!(job, NotebookInitializationJob::InitializeSchema) {
+                    if !Path::new(&notebook.path).is_dir() {
+                        tracing::warn!(job_id = %key, notebook = %notebook.id,
+                            "notebook schema refresh deferred until the notebook is available");
+                        break;
+                    }
+                    memo_file
+                        .retire_legacy_memo_index(&notebook.id)
+                        .and_then(|_| memo_file.initialize_media_resource_schema(&notebook.id))
+                        .map_err(|error| {
+                            format!("refresh notebook {} database schema failed: {error}", notebook.id)
+                        })?;
+                }
+                report(*completed, total, &key);
+                *completed += 1;
+                report(*completed, total, &key);
+                if matches!(job, NotebookInitializationJob::ResetLegacyStorage) {
+                    clear_notebook_reset_signal_best_effort(notebook);
+                }
+                continue;
+            }
+            if !Path::new(&notebook.path).is_dir() {
+                tracing::warn!(job_id = %key, notebook = %notebook.id,
+                    "notebook initialization deferred until the notebook is available");
+                for deferred_job in NotebookInitializationJob::ALL.iter().skip(job_index) {
+                    let deferred_key = deferred_job.key(&notebook.id);
+                    *completed += 1;
+                    report(*completed, total, &format!("deferred:{deferred_key}"));
+                }
+                break;
+            }
+            run_job_with_progress(
+                memo_file,
+                &key,
+                || match job {
+                    NotebookInitializationJob::ResetLegacyStorage => {
+                        if notebook_requires_reset(memo_file, notebook)? {
+                            reset_notebook(memo_file, notebook)?;
+                        }
+                        Ok(())
+                    }
+                    NotebookInitializationJob::InitializeSchema => {
+                        // Retrying schema preparation must preserve a database
+                        // already rebuilt by a successful reset job.
+                        memo_file
+                            .retire_legacy_memo_index(&notebook.id)
+                            .and_then(|_| memo_file.initialize_media_resource_schema(&notebook.id))
+                            .map_err(|error| {
+                                format!(
+                                    "initialize notebook {} database schema failed: {error}",
+                                    notebook.id
+                                )
+                            })
+                    }
+                    NotebookInitializationJob::MigrateMediaResourceIdentity => memo_file
+                        .migrate_media_resource_identities(&notebook.id)
+                        .map(|count| {
+                            tracing::info!(notebook_id = %notebook.id, changed = count,
+                                "media resource identity migration completed");
+                        })
+                        .map_err(|error| format!("migrate notebook {} media identities failed: {error}", notebook.id)),
+                },
+                report,
+                completed,
+                total,
+            )?;
+            if matches!(job, NotebookInitializationJob::ResetLegacyStorage) {
+                clear_notebook_reset_signal_best_effort(notebook);
+            }
+        }
+    }
+    Ok(())
+}
+
+fn clear_notebook_reset_signal_best_effort(notebook: &NotebookConfig) {
+    let dir = Path::new(&notebook.path).join(".flowix");
+    match fs::symlink_metadata(&dir) {
+        // Never follow a replaced .flowix symlink to delete a signal elsewhere.
+        Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
+            if let Err(error) = remove_path(&dir.join(NOTEBOOK_RESET_PENDING_FILE)) {
+                tracing::warn!(notebook_id = %notebook.id, %error,
+                    "remove completed notebook reset signal failed");
+            }
+        }
+        Ok(_) => {}
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+        Err(error) => tracing::warn!(notebook_id = %notebook.id, %error,
+            "inspect completed notebook reset directory failed"),
+    }
+}
+
+fn notebook_requires_reset(
+    memo_file: &MemoFile,
+    notebook: &NotebookConfig,
+) -> Result<bool, String> {
+    let root = Path::new(&notebook.path);
+    let flowix = root.join(".flowix");
+    if memo_file
+        .has_legacy_notebook_internal_data(&notebook.id)
+        .map_err(|error| format!("inspect notebook artifacts failed: {error}"))?
+        || [
+            flowix.join("agent.json"),
+            flowix.join(NOTEBOOK_RESET_PENDING_FILE),
+        ]
+        .iter()
+        .any(|path| path.exists())
+    {
+        return Ok(true);
+    }
+    // Read old checkpoints only to resume resets interrupted before this
+    // simplified implementation. New resets never write stage completions.
+    for stage in [
+        "plugin-artifacts",
+        "derived-reset",
+        "note-index",
+        "media-index",
+    ] {
+        let key = format!("storage_reset_v1:notebook:{}:{stage}", notebook.id);
+        if memo_file
+            .local_migration_completed(&key)
+            .map_err(|error| error.to_string())?
+        {
+            return Ok(true);
+        }
+    }
+    legacy_notebook_database(&flowix.join("notebook.db"))
+        .map_err(|error| format!("inspect notebook database failed: {error}"))
+}
+
+fn legacy_notebook_database(path: &Path) -> io::Result<bool> {
+    if !path.is_file() {
+        return Ok(false);
+    }
+    let conn = Connection::open(path).map_err(sqlite_to_io)?;
+    let names = {
+        let mut statement = conn
+            .prepare(
+                "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'",
+            )
+            .map_err(sqlite_to_io)?;
+        let rows = statement
+            .query_map([], |row| row.get::<_, String>(0))
+            .map_err(sqlite_to_io)?;
+        rows.collect::<Result<Vec<_>, _>>().map_err(sqlite_to_io)?
+    };
+    let has_old_memos = names.iter().any(|name| name == "memos");
+    let has_old_v2_projection = names.iter().any(|name| name.starts_with("v2_"));
+    // Memo tables are migrated in place by the schema job so their
+    // non-derivable properties can be preserved before they are retired.
+    Ok(has_old_v2_projection && !has_old_memos)
+}
+
+fn path_entry_exists(path: &Path) -> io::Result<bool> {
+    match fs::symlink_metadata(path) {
+        Ok(_) => Ok(true),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(false),
+        Err(error) => Err(error),
+    }
+}
+
+// Retry the complete reset safely. Only the enclosing run_job records success.
+fn reset_notebook(memo_file: &MemoFile, notebook: &NotebookConfig) -> Result<(), String> {
+    let root = Path::new(&notebook.path);
+    let flowix_dir = root.join(".flowix");
+    if fs::symlink_metadata(&flowix_dir).is_ok_and(|metadata| metadata.file_type().is_symlink()) {
+        return Err(format!(
+            "notebook .flowix directory is a symbolic link: {}",
+            flowix_dir.display()
+        ));
+    }
+    fs::create_dir_all(&flowix_dir)
+        .map_err(|error| format!("create notebook Flowix directory failed: {error}"))?;
+    // Write before moving any legacy source or deleting any derived data.
+    flowix_core::memo_file::atomic_write_bytes(&flowix_dir.join(NOTEBOOK_RESET_PENDING_FILE), b"1")
+        .map_err(|error| format!("persist notebook reset interruption signal failed: {error}"))?;
+
+    MemoFile::ensure_notebook_manifest(notebook)
+        .map_err(|error| format!("restore notebook identity manifest failed: {error}"))?;
+    let migration = memo_file
+        .migrate_notebook_internal_data(&notebook.id)
+        .map_err(|error| format!("preserve notebook plugin artifacts failed: {error}"))?;
+    if !migration.completed {
+        return Err(format!(
+            "notebook {} plugin artifact migration is incomplete: {:?}",
+            notebook.id, migration.warnings
+        ));
+    }
+
+    // Rebuild the path index from Markdown, then discard the old Memo-ID
+    // projection. Derived note metadata is recreated from the source files.
+    memo_file
+        .retire_legacy_memo_index(&notebook.id)
+        .map_err(|error| format!("migrate notebook note index failed: {error}"))?;
+    memo_file
+        .initialize_media_resource_schema(&notebook.id)
+        .map_err(|error| format!("initialize notebook media schema failed: {error}"))?;
+    memo_file.invalidate_caches();
+    for name in [
+        "view-preferences.json",
+        "system.json",
+        "file-management-refresh-pending",
+    ] {
+        flowix_core::memo_file::backup_storage_file(&flowix_dir.join(name))
+            .map_err(|error| format!("preserve notebook {name} failed: {error}"))?;
+    }
+    crate::commands::file::write_default_notebook_view_preferences(root)?;
+    memo_file
+        .reconcile_note_index_blocking(&notebook.id)
+        .map_err(|error| format!("rebuild notebook note index failed: {error}"))?;
+    memo_file
+        .reconcile_media_resources(&notebook.id)
+        .map_err(|error| format!("rebuild notebook media index failed: {error}"))?;
+
+    // Discard the obsolete configuration after preservation and rebuilding.
+    // The pending signal survives until run_job has recorded overall success.
+    for name in ["agent.json", "notebook-template-initializing.json"] {
+        remove_path(&flowix_dir.join(name))
+            .map_err(|error| format!("remove notebook {name} failed: {error}"))?;
+    }
+    Ok(())
+}
+
+fn remove_path(path: &Path) -> io::Result<()> {
+    match fs::symlink_metadata(path) {
+        Ok(metadata) if metadata.file_type().is_symlink() || metadata.is_file() => {
+            fs::remove_file(path)
+        }
+        Ok(metadata) if metadata.is_dir() => fs::remove_dir_all(path),
+        Ok(_) => Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            format!("unsupported path type: {}", path.display()),
+        )),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(error),
+    }
+}
+
+fn sqlite_to_io(error: rusqlite::Error) -> io::Error {
+    io::Error::other(error)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fixture() -> (tempfile::TempDir, MemoFile, NotebookConfig) {
+        let temp = tempfile::tempdir().unwrap();
+        let memo = MemoFile::new(temp.path().join("config"));
+        memo.initialize_registry_storage().unwrap();
+        let root = temp.path().join("notebook");
+        fs::create_dir_all(&root).unwrap();
+        let notebook = NotebookConfig {
+            id: "test".into(),
+            name: "notebook".into(),
+            icon: None,
+            path: root.to_string_lossy().into_owned(),
+            is_default: true,
+            sort: 0,
+            created_at: 0,
+            updated_at: 0,
+        };
+        memo.write_notebook_configs(&[notebook.clone()]).unwrap();
+        (temp, memo, notebook)
+    }
+
+    #[test]
+    fn storage_rebuild_missing_markers_preserves_plugins_and_drafts() {
+        let temp = tempfile::tempdir().unwrap();
+        let home = temp.path().to_path_buf();
+        let config = home.join(crate::USER_CONFIG_DIR_NAME);
+        let app_data = home.join("app-data");
+        fs::create_dir_all(config.join("plugin/custom")).unwrap();
+        fs::write(config.join("plugin/custom/kept.txt"), b"custom plugin").unwrap();
+        fs::create_dir_all(app_data.join("recovery-drafts")).unwrap();
+        fs::write(app_data.join("recovery-drafts/kept.md"), b"draft").unwrap();
+        let user = crate::config::UserConfigStore::new(home);
+        let device = DeviceRegistry::load(&config, "test");
+        let memo = MemoFile::new(config.clone());
+        memo.initialize_registry_storage().unwrap();
+        initialize_legacy_storage(&device, &memo, &user, &config, &app_data).unwrap();
+        assert_eq!(
+            fs::read(config.join("plugin/custom/kept.txt")).unwrap(),
+            b"custom plugin"
+        );
+        assert_eq!(
+            fs::read(app_data.join("recovery-drafts/kept.md")).unwrap(),
+            b"draft"
+        );
+    }
+
+    #[test]
+    fn registry_initialization_prepares_workspace_tables() {
+        let temp = tempfile::tempdir().unwrap();
+        let memo = MemoFile::new(temp.path().join("config"));
+        memo.initialize_registry_storage().unwrap();
+        let conn = Connection::open(memo.registry_db_path()).unwrap();
+        for table in ["notebook_add_dirs", "notebook_workspace_state"] {
+            let count: i64 = conn
+                .query_row(&format!("SELECT COUNT(*) FROM {table}"), [], |r| r.get(0))
+                .unwrap();
+            assert_eq!(count, 0);
+        }
+    }
+
+    #[test]
+    fn current_view_preferences_do_not_require_reset() {
+        let (_temp, memo, notebook) = fixture();
+        crate::commands::file::write_default_notebook_view_preferences(Path::new(&notebook.path))
+            .unwrap();
+        assert!(!notebook_requires_reset(&memo, &notebook).unwrap());
+    }
+
+    #[test]
+    fn schema_retry_preserves_database_after_completed_reset() {
+        let (_temp, memo, notebook) = fixture();
+        crate::commands::file::write_default_notebook_view_preferences(Path::new(&notebook.path))
+            .unwrap();
+        let path = Path::new(&notebook.path).join(".flowix/notebook.db");
+        Connection::open(&path).unwrap().execute_batch("CREATE TABLE retained_probe (value TEXT); INSERT INTO retained_probe VALUES ('keep');").unwrap();
+        memo.mark_local_migration_completed(
+            &NotebookInitializationJob::ResetLegacyStorage.key(&notebook.id),
+        )
+        .unwrap();
+        reset_pending_notebooks(&memo).unwrap();
+        let value: String = Connection::open(path)
+            .unwrap()
+            .query_row("SELECT value FROM retained_probe", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(value, "keep");
+        assert!(!memo.has_pending_notebook_storage_initialization().unwrap());
+    }
+
+    #[test]
+    fn current_status_markers_do_not_reset_preferences() {
+        let (_temp, memo, notebook) = fixture();
+        let flowix = Path::new(&notebook.path).join(".flowix");
+        fs::create_dir_all(&flowix).unwrap();
+        fs::write(
+            flowix.join("view-preferences.json"),
+            b"{\"default_create_folder\":\"custom\"}",
+        )
+        .unwrap();
+        fs::write(flowix.join("file-management-refresh-pending"), b"refresh").unwrap();
+        fs::write(flowix.join("notebook-template-initializing.json"), b"{}").unwrap();
+        assert!(!notebook_requires_reset(&memo, &notebook).unwrap());
+        reset_pending_notebooks(&memo).unwrap();
+        assert_eq!(
+            fs::read(flowix.join("view-preferences.json")).unwrap(),
+            b"{\"default_create_folder\":\"custom\"}"
+        );
+        assert!(flowix.join("file-management-refresh-pending").exists());
+        assert!(flowix.join("notebook-template-initializing.json").exists());
+    }
+
+    fn assert_reset_rebuilds_note(memo: &MemoFile, notebook: &NotebookConfig) {
+        let root = Path::new(&notebook.path);
+        fs::write(root.join("retained.md"), "# Retained note\nbody").unwrap();
+        reset_pending_notebooks(memo).unwrap();
+        let conn = Connection::open(root.join(".flowix/notebook.db")).unwrap();
+        let count: i64 = conn
+            .query_row(
+                "SELECT COUNT(*) FROM notes WHERE relative_path = 'retained.md'",
+                [],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(count, 1);
+        assert_eq!(
+            fs::read_to_string(root.join("retained.md")).unwrap(),
+            "# Retained note\nbody"
+        );
+        assert!(!root
+            .join(".flowix")
+            .join(NOTEBOOK_RESET_PENDING_FILE)
+            .exists());
+        assert!(memo
+            .local_migration_completed(
+                &NotebookInitializationJob::ResetLegacyStorage.key(&notebook.id)
+            )
+            .unwrap());
+    }
+
+    #[test]
+    fn interrupted_reset_rebuilds_indexes_and_records_only_overall_completion() {
+        let (_temp, memo, notebook) = fixture();
+        let flowix = Path::new(&notebook.path).join(".flowix");
+        fs::create_dir_all(&flowix).unwrap();
+        // Simulate interruption after legacy sources and derived DB disappeared.
+        fs::write(flowix.join(NOTEBOOK_RESET_PENDING_FILE), b"1").unwrap();
+        assert_reset_rebuilds_note(&memo, &notebook);
+        let conn = Connection::open(memo.registry_db_path()).unwrap();
+        let count: i64 = conn.query_row("SELECT COUNT(*) FROM local_migrations WHERE migration_key LIKE 'storage_reset_v1:notebook:test:%'", [], |row| row.get(0)).unwrap();
+        assert_eq!(count, 0, "new resets must not write stage completions");
+    }
+
+    #[test]
+    fn legacy_partial_reset_is_retried_without_original_sources() {
+        let (_temp, memo, notebook) = fixture();
+        memo.mark_local_migration_completed("storage_reset_v1:notebook:test:derived-reset")
+            .unwrap();
+        assert_reset_rebuilds_note(&memo, &notebook);
+    }
+
+    #[test]
+    fn failed_job_retries_and_completed_job_skips() {
+        let (_temp, memo, _) = fixture();
+        assert!(run_job(&memo, "test_retry", || Err("interrupted".into())).is_err());
+        assert!(!memo.local_migration_completed("test_retry").unwrap());
+        run_job(&memo, "test_retry", || Ok(())).unwrap();
+        run_job(&memo, "test_retry", || panic!("completed job ran again")).unwrap();
+    }
+}
+
+#[cfg(test)]
+mod retired_index_tests {
+    use super::*;
+
+    #[test]
+    fn cleanup_failure_does_not_prevent_retiring_the_other_layout() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        fs::create_dir(root.join("db")).unwrap();
+        fs::write(root.join("index.db"), b"blocked legacy database").unwrap();
+        // A file where the backup directory belongs fails on every platform,
+        // including when tests run with elevated filesystem permissions.
+        fs::write(root.join("rebuild-backups"), b"blocked").unwrap();
+        fs::write(root.join("db/index.db"), b"other legacy database").unwrap();
+
+        retire_global_index_databases(root);
+
+        assert_eq!(fs::read(root.join("index.db")).unwrap(), b"blocked legacy database");
+        assert!(!root.join("db/index.db").exists());
+        assert!(root.join("db/rebuild-backups").is_dir());
+    }
+
+    #[test]
+    fn retirement_preserves_both_layouts_and_sidecars_without_touching_current_stores() {
+        let temp = tempfile::tempdir().unwrap();
+        let root = temp.path();
+        fs::create_dir(root.join("db")).unwrap();
+        for directory in [root.to_path_buf(), root.join("db")] {
+            for suffix in ["", "-wal", "-shm", "-journal"] {
+                fs::write(directory.join(format!("index.db{suffix}")), suffix.as_bytes()).unwrap();
+            }
+        }
+        fs::write(root.join("db/local.db"), b"current registry").unwrap();
+        fs::write(root.join("db/default.db"), b"credentials").unwrap();
+        for _ in 0..2 {
+            retire_global_index_databases(root);
+        }
+        for directory in [root.to_path_buf(), root.join("db")] {
+            let backups: Vec<_> = fs::read_dir(directory.join("rebuild-backups"))
+                .unwrap().map(|entry| entry.unwrap().path()).collect();
+            assert_eq!(backups.len(), 1);
+            for suffix in ["", "-wal", "-shm", "-journal"] {
+                let name = format!("index.db{suffix}");
+                assert!(!directory.join(&name).exists());
+                assert_eq!(fs::read(backups[0].join(name)).unwrap(), suffix.as_bytes());
+            }
+        }
+        assert_eq!(fs::read(root.join("db/local.db")).unwrap(), b"current registry");
+        assert_eq!(fs::read(root.join("db/default.db")).unwrap(), b"credentials");
+    }
+}
diff --git a/app/flowix-desktop/src/system_data.rs b/app/flowix-desktop/src/system_data.rs
index 608375d9d..231bce2d4 100644
--- a/app/flowix-desktop/src/system_data.rs
+++ b/app/flowix-desktop/src/system_data.rs
@@ -156,7 +156,7 @@ impl SystemData {
         if let Some(parent) = path.parent() {
             fs::create_dir_all(parent)?;
         }
-        let data = Self::read_from_disk(&path).unwrap_or_default();
+        let data = flowix_core::memo_file::read_or_create_json(&path, SystemFile::default)?;
         Ok(Self {
             path,
             data: RwLock::new(data),
@@ -188,20 +188,6 @@ impl SystemData {
         })
     }
 
-    fn read_from_disk(path: &PathBuf) -> Option<SystemFile> {
-        if !path.exists() {
-            return None;
-        }
-        let content = fs::read_to_string(path).ok()?;
-        match serde_json::from_str::<SystemFile>(&content) {
-            Ok(data) => Some(data),
-            Err(e) => {
-                tracing::warn!("system.json parse error: {e}, falling back to empty");
-                None
-            }
-        }
-    }
-
     fn flush(&self, data: &SystemFile) -> std::io::Result<()> {
         if let Some(parent) = self.path.parent() {
             fs::create_dir_all(parent)?;
@@ -324,7 +310,6 @@ impl SystemData {
             .notebooks
             .entry(notebook_id.to_string())
             .or_default();
-        notebook.order = layout.iter().map(|item| item.id.clone()).collect();
         notebook.layout = layout;
         self.flush(&data)
     }
diff --git a/app/flowix-desktop/src/template_store.rs b/app/flowix-desktop/src/template_store.rs
index dbbb54d69..9db4dcad3 100644
--- a/app/flowix-desktop/src/template_store.rs
+++ b/app/flowix-desktop/src/template_store.rs
@@ -1,27 +1,26 @@
-use std::fs::{self, OpenOptions};
-use std::io::Write;
+use std::fs;
 use std::path::{Component, Path, PathBuf};
 
 include!(concat!(env!("OUT_DIR"), "/notebook_template_assets.rs"));
 
-const LEGACY_NOTES_MIGRATION_MARKER: &str = ".notes-template-migration-v1-complete";
-
 pub fn initialize(user_config_dir: &Path) -> Result<(), String> {
     initialize_notebook_templates(user_config_dir)?;
 
     let templates_dir = user_config_dir.join("templates");
     let notes_templates_dir = templates_dir.join("notes");
 
-    fs::create_dir_all(&notes_templates_dir)
+    flowix_core::memo_file::ensure_storage_directory(&notes_templates_dir)
         .map_err(|error| format!("create note template directory failed: {error}"))?;
-    migrate_legacy_note_templates(user_config_dir, &templates_dir, &notes_templates_dir)?;
+    migrate_legacy_note_templates(user_config_dir, &notes_templates_dir)?;
 
     Ok(())
 }
 
 pub fn initialize_notebook_templates(user_config_dir: &Path) -> Result<(), String> {
-    let notebook_templates_dir = user_config_dir.join("templates").join("notebook-templates");
-    fs::create_dir_all(&notebook_templates_dir)
+    let templates_dir = user_config_dir.join("templates");
+    flowix_core::memo_file::ensure_storage_directory(&templates_dir).map_err(|error| error.to_string())?;
+    let notebook_templates_dir = templates_dir.join("notebook-templates");
+    flowix_core::memo_file::ensure_storage_directory(&notebook_templates_dir)
         .map_err(|error| format!("create notebook template directory failed: {error}"))?;
     seed_notebook_templates_if_needed(&notebook_templates_dir)
 }
@@ -36,10 +35,23 @@ pub fn notes_templates_dir(user_config_dir: &Path) -> PathBuf {
 
 fn seed_notebook_templates_if_needed(target_dir: &Path) -> Result<(), String> {
     let index_path = target_dir.join("index.json");
+    if index_path.is_file() {
+        let bytes = fs::read(&index_path).map_err(|error| error.to_string())?;
+        let valid = serde_json::from_slice::<serde_json::Value>(&bytes).ok()
+            .and_then(|index| index.get("templates").cloned())
+            .and_then(|templates| serde_json::from_value::<Vec<crate::commands::memo::creates::NotebookTemplate>>(templates).ok())
+            .is_some_and(|templates| {
+                let mut ids = std::collections::HashSet::new();
+                templates.iter().all(|template| crate::commands::memo::creates::validate_notebook_template(template).is_ok() && ids.insert(template.id.clone()))
+            });
+        if !valid {
+            flowix_core::memo_file::backup_storage_file(&index_path).map_err(|error| error.to_string())?;
+        }
+    }
     if index_path.exists() {
         if !is_legacy_builtin_notebook_template_index(&index_path)? {
             migrate_builtin_scenario_ids_and_cover_urls(&index_path)?;
-            return Ok(());
+            return ensure_bundled_template_files(target_dir);
         }
 
         // Replace the previous built-in collection on upgrade. A custom
@@ -65,6 +77,12 @@ fn seed_notebook_templates_if_needed(target_dir: &Path) -> Result<(), String> {
             .map_err(|error| format!("replace legacy notebook template index failed: {error}"))?;
     }
 
+    ensure_bundled_template_files(target_dir)
+}
+
+// Called when templates are used, so partial deletion does not require a
+// version change or a startup scan. Existing files and custom indexes survive.
+fn ensure_bundled_template_files(target_dir: &Path) -> Result<(), String> {
     for &(relative, content) in NOTEBOOK_TEMPLATE_ASSETS
         .iter()
         .filter(|(relative, _)| *relative != "index.json")
@@ -90,7 +108,7 @@ fn seed_notebook_templates_if_needed(target_dir: &Path) -> Result<(), String> {
         .iter()
         .find_map(|(relative, content)| (*relative == "index.json").then_some(*content))
         .ok_or_else(|| "bundled notebook template index is missing".to_string())?;
-    write_if_missing(&index_path, index_content)?;
+    write_if_missing(&target_dir.join("index.json"), index_content)?;
 
     Ok(())
 }
@@ -258,61 +276,99 @@ fn migrate_builtin_scenario_ids_and_cover_urls(index_path: &Path) -> Result<(),
 
 fn migrate_legacy_note_templates(
     user_config_dir: &Path,
-    templates_dir: &Path,
     notes_templates_dir: &Path,
 ) -> Result<(), String> {
     let legacy_dir = user_config_dir.join("template");
-    if !legacy_dir.is_dir() {
-        return Ok(());
+    let metadata = match fs::symlink_metadata(&legacy_dir) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(error) => return Err(format!("inspect legacy note template directory failed: {error}")),
+    };
+    if metadata.file_type().is_symlink() || !metadata.is_dir() {
+        return Err("legacy note template path is not a regular directory".to_string());
     }
+    copy_legacy_template_tree(&legacy_dir, &legacy_dir, notes_templates_dir)?;
 
-    let marker = templates_dir.join(LEGACY_NOTES_MIGRATION_MARKER);
-    if marker.exists() {
-        return Ok(());
-    }
+    fs::remove_dir_all(&legacy_dir)
+        .map_err(|error| format!("remove legacy note template directory failed: {error}"))
+}
 
-    let entries = fs::read_dir(&legacy_dir)
+fn copy_legacy_template_tree(
+    root: &Path,
+    source: &Path,
+    destination: &Path,
+) -> Result<(), String> {
+    let entries = fs::read_dir(source)
         .map_err(|error| format!("read legacy note template directory failed: {error}"))?;
     for entry in entries {
         let entry = entry.map_err(|error| format!("read legacy note template failed: {error}"))?;
         let file_type = entry
             .file_type()
             .map_err(|error| format!("inspect legacy note template failed: {error}"))?;
-        if !file_type.is_file() {
+        if file_type.is_symlink() {
             continue;
         }
-
-        let source = entry.path();
-        let extension = source
-            .extension()
-            .and_then(|extension| extension.to_str())
-            .unwrap_or_default();
-        if !matches!(extension.to_ascii_lowercase().as_str(), "md" | "markdown") {
+        let path = entry.path();
+        let relative = path
+            .strip_prefix(root)
+            .map_err(|error| format!("resolve legacy note template path failed: {error}"))?;
+        if relative.components().any(|component| {
+            !matches!(component, Component::Normal(_))
+        }) {
             continue;
         }
-
-        let filename = source
-            .file_name()
-            .ok_or_else(|| "invalid legacy note template filename".to_string())?;
-        let target = notes_templates_dir.join(filename);
-        let content = fs::read(&source)
-            .map_err(|error| format!("read legacy note template failed: {error}"))?;
-        write_if_missing(&target, &content)?;
+        let target = destination.join(relative);
+        if file_type.is_dir() {
+            fs::create_dir_all(&target)
+                .map_err(|error| format!("create note template directory failed: {error}"))?;
+            copy_legacy_template_tree(root, &path, destination)?;
+        } else if file_type.is_file() {
+            let content = fs::read(&path)
+                .map_err(|error| format!("read legacy note template failed: {error}"))?;
+            write_if_missing(&target, &content)?;
+        }
     }
-
-    write_if_missing(&marker, b"completed\n")
+    Ok(())
 }
 
 fn write_if_missing(path: &Path, content: &[u8]) -> Result<(), String> {
-    let mut file = match OpenOptions::new().write(true).create_new(true).open(path) {
-        Ok(file) => file,
-        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => return Ok(()),
-        Err(error) => return Err(format!("create template file failed: {error}")),
-    };
+    match flowix_core::memo_file::atomic_create_bytes(path, content) {
+        Ok(()) => Ok(()),
+        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => Ok(()),
+        Err(error) => Err(format!("create template file failed: {error}")),
+    }
+}
 
-    if let Err(error) = file.write_all(content) {
-        let _ = fs::remove_file(path);
-        return Err(format!("write template file failed: {error}"));
+#[cfg(test)]
+mod missing_dependency_tests {
+    use super::*;
+
+    #[test]
+    fn storage_rebuild_replaces_invalid_template_index() {
+        let temp = tempfile::tempdir().unwrap();
+        initialize_notebook_templates(temp.path()).unwrap();
+        let root = notebook_templates_dir(temp.path());
+        fs::write(root.join("index.json"), b"{broken").unwrap();
+        initialize_notebook_templates(temp.path()).unwrap();
+        let index: serde_json::Value =
+            serde_json::from_slice(&fs::read(root.join("index.json")).unwrap()).unwrap();
+        assert!(index["templates"].is_array());
+        assert!(root.join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn missing_runtime_dependencies_recreate_template_file_with_existing_index() {
+        let temp = tempfile::tempdir().unwrap();
+        initialize_notebook_templates(temp.path()).unwrap();
+        let root = notebook_templates_dir(temp.path());
+        let (relative, content) = NOTEBOOK_TEMPLATE_ASSETS
+            .iter()
+            .find(|(path, _)| *path != "index.json")
+            .unwrap();
+        let index = fs::read(root.join("index.json")).unwrap();
+        fs::remove_file(root.join(relative)).unwrap();
+        initialize_notebook_templates(temp.path()).unwrap();
+        assert_eq!(fs::read(root.join(relative)).unwrap(), *content);
+        assert_eq!(fs::read(root.join("index.json")).unwrap(), index);
     }
-    Ok(())
 }
diff --git a/app/flowix-desktop/src/watcher/manager.rs b/app/flowix-desktop/src/watcher/manager.rs
index 23dedc434..bbec54b85 100644
--- a/app/flowix-desktop/src/watcher/manager.rs
+++ b/app/flowix-desktop/src/watcher/manager.rs
@@ -29,6 +29,7 @@ pub struct MemoWatcher {
     watched_roots: Arc<std::sync::RwLock<Vec<NotebookWatchContext>>>,
     suspended_notebook_ids: HashMap<String, usize>,
     recent_self_writes: Arc<Mutex<SelfWriteMap>>,
+    rename_tracker: Arc<Mutex<super::rename_tracker::RenameTracker>>,
     remove_coalescer: Option<RemoveCoalescer>,
     memo_file: Arc<std::sync::RwLock<MemoFile>>,
     whitelist: Arc<std::sync::RwLock<WhitelistConfig>>,
@@ -63,6 +64,10 @@ impl MemoWatcher {
             .collect();
         drop(roots);
         for root in previous {
+            self.rename_tracker
+                .lock()
+                .unwrap_or_else(|p| p.into_inner())
+                .forget_root(&root);
             if watcher.unwatch(&root).is_err() {
                 return false;
             }
@@ -76,7 +81,23 @@ impl MemoWatcher {
             return true;
         }
         let root = PathBuf::from(&config.path);
-        if !root.is_dir() || watcher.watch(&root, RecursiveMode::Recursive).is_err() {
+        if !root.is_dir() {
+            return false;
+        }
+        let context = NotebookWatchContext {
+            notebook_id: config.id.clone(),
+            root: root.clone(),
+        };
+        let seed = super::rename_tracker::RenameTracker::seed_root(&context);
+        self.rename_tracker
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .merge_seed(seed);
+        if watcher.watch(&root, RecursiveMode::Recursive).is_err() {
+            self.rename_tracker
+                .lock()
+                .unwrap_or_else(|p| p.into_inner())
+                .forget_root(&root);
             return false;
         }
         if let Ok(mut roots) = self.watched_roots.write() {
@@ -86,6 +107,11 @@ impl MemoWatcher {
             });
             true
         } else {
+            let _ = watcher.unwatch(&root);
+            self.rename_tracker
+                .lock()
+                .unwrap_or_else(|p| p.into_inner())
+                .forget_root(&root);
             false
         }
     }
@@ -106,7 +132,20 @@ impl MemoWatcher {
         if !root.is_dir() {
             return false;
         }
+        let context = NotebookWatchContext {
+            notebook_id: config.id.clone(),
+            root: root.clone(),
+        };
+        let seed = super::rename_tracker::RenameTracker::seed_root(&context);
+        self.rename_tracker
+            .lock()
+            .unwrap_or_else(|p| p.into_inner())
+            .merge_seed(seed);
         if watcher.watch(&root, RecursiveMode::Recursive).is_err() {
+            self.rename_tracker
+                .lock()
+                .unwrap_or_else(|p| p.into_inner())
+                .forget_root(&root);
             return false;
         }
         match self.watched_roots.write() {
@@ -116,6 +155,10 @@ impl MemoWatcher {
             }
             Err(_) => {
                 let _ = watcher.unwatch(&root);
+                self.rename_tracker
+                    .lock()
+                    .unwrap_or_else(|p| p.into_inner())
+                    .forget_root(&root);
                 false
             }
         }
@@ -128,12 +171,21 @@ impl MemoWatcher {
             })
     }
 
+    pub fn is_initialized(&self) -> bool {
+        self._watcher.is_some()
+    }
+
+    pub fn is_notebook_suspended(&self, notebook_id: &str) -> bool {
+        self.suspended_notebook_ids.contains_key(notebook_id)
+    }
+
     pub fn new(memo_file: Arc<std::sync::RwLock<MemoFile>>) -> Self {
         Self {
             _watcher: None,
             watched_roots: Arc::new(std::sync::RwLock::new(Vec::new())),
             suspended_notebook_ids: HashMap::new(),
             recent_self_writes: Arc::new(Mutex::new(HashMap::new())),
+            rename_tracker: Arc::new(Mutex::new(super::rename_tracker::RenameTracker::default())),
             remove_coalescer: None,
             memo_file,
             whitelist: Arc::new(std::sync::RwLock::new(WhitelistConfig::load_or_default())),
@@ -147,7 +199,8 @@ impl MemoWatcher {
     pub fn set_whitelist(&self, new_cfg: WhitelistConfig) {
         if let Ok(mut g) = self.whitelist.write() {
             let mut config = new_cfg;
-            // Legacy name rules are migrated into each notebook policy.
+            // Name exclusions now come from the new notebook-local policy.
+            // Keep only the internal directories in the global event filter.
             config.skip_dirs = vec![".flowix".into(), ".plugin-output".into()];
             config.skip_files.clear();
             config.allowed_filename_patterns.clear();
@@ -200,10 +253,6 @@ impl MemoWatcher {
             })
             .collect();
         if let Ok(mut watched) = self.watched_roots.write() { watched.clear(); }
-        if roots.is_empty() {
-            return;
-        }
-
         let remove_coalescer =
             RemoveCoalescer::new(app.clone(), self.memo_file.clone(), REMOVE_TOMBSTONE_DELAY);
         let remove_coalescer_for_callback = remove_coalescer.clone();
@@ -214,22 +263,32 @@ impl MemoWatcher {
 
         // notify 共享事件线程 -> 单 worker 线程的派发通道。notify 回调只做廉价的
         // filter / debounce / 自写抑制 + 入队 (`send` 非阻塞), 重 `process` 交给 worker。
-        // tx 给回调, rx 留给下方 watched_count>0 后 spawn 的 worker。
+        // tx 给回调, rx 交给 worker；即使当前没有可用根，worker 也保持就绪，
+        // 供后续离线根恢复挂载后接收事件。
         let (worker_tx, worker_rx) =
             std::sync::mpsc::channel::<(RawFsEvent, NotebookWatchContext)>();
         let worker_tx_for_callback = worker_tx.clone();
 
-        let mut rename_tracker = super::rename_tracker::RenameTracker::seed(&roots);
+        let rename_tracker = Arc::new(Mutex::new(
+            super::rename_tracker::RenameTracker::seed(&roots),
+        ));
+        self.rename_tracker = rename_tracker.clone();
+        let rename_tracker_for_callback = rename_tracker.clone();
         let mut watcher: RecommendedWatcher =
             match notify::recommended_watcher(move |res: notify::Result<Event>| {
                 let Ok(event) = res else {
                     return;
                 };
-                let removed_known_directories: std::collections::HashSet<PathBuf> = event.paths.iter()
-                    .filter(|path| rename_tracker.was_directory(path))
-                    .cloned()
-                    .collect();
-                let event = rename_tracker.correlate(event);
+                let (event, removed_known_directories) = {
+                    let mut rename_tracker = rename_tracker_for_callback
+                        .lock()
+                        .unwrap_or_else(|p| p.into_inner());
+                    let removed_known_directories: std::collections::HashSet<PathBuf> = event.paths.iter()
+                        .filter(|path| rename_tracker.was_directory(path))
+                        .cloned()
+                        .collect();
+                    (rename_tracker.correlate(event), removed_known_directories)
+                };
                 handle_notify_event(
                     &remove_coalescer_for_callback,
                     &whitelist,
@@ -267,7 +326,7 @@ impl MemoWatcher {
             watched_count += 1;
         }
         if watched_count == 0 {
-            return;
+            tracing::info!("[MemoWatcher] initialized with no available notebook roots; offline roots can be retried later");
         }
 
         // 单 worker 串行 drain -> 保 FIFO (同路径事件顺序不乱)。`process` 含
@@ -613,6 +672,31 @@ fn context_for_path(
 mod tests {
     use super::*;
 
+    #[test]
+    fn recovered_bindings_reconcile_attached_roots_but_not_offline_or_suspended_roots() {
+        let temp = tempfile::tempdir().unwrap();
+        let memo = Arc::new(std::sync::RwLock::new(MemoFile::new(temp.path().join("config"))));
+        let mut manager = MemoWatcher::new(memo);
+        manager._watcher = Some(notify::recommended_watcher(|_: notify::Result<Event>| {}).unwrap());
+        let configs: Vec<_> = (0..3).map(|index| {
+            let path = temp.path().join(format!("book-{index}"));
+            if index != 1 { std::fs::create_dir_all(&path).unwrap(); }
+            NotebookConfig {
+                id: format!("nb_{index}"), name: format!("Book {index}"),
+                path: path.to_string_lossy().into_owned(), icon: None,
+                is_default: false, sort: 0, created_at: 1, updated_at: 1,
+            }
+        }).collect();
+        manager.set_notebook_suspended(&configs[2].id, true);
+        for config in &configs { manager.add_notebook_root(config); }
+        let background = crate::app::notebook_background::NotebookBackground::default();
+        crate::watcher::runtime::reconcile_bound_roots(&manager, &configs, &background);
+        let statuses = background.statuses();
+        assert_eq!(statuses.len(), 1);
+        assert_eq!(statuses[0].notebook_id, configs[0].id);
+        assert_eq!(statuses[0].state, "queued");
+    }
+
     #[test]
     fn template_suspension_only_rebinds_its_own_root() {
         let directory = tempfile::tempdir().unwrap();
diff --git a/app/flowix-desktop/src/watcher/processor.rs b/app/flowix-desktop/src/watcher/processor.rs
index ae7200bea..43d749c01 100644
--- a/app/flowix-desktop/src/watcher/processor.rs
+++ b/app/flowix-desktop/src/watcher/processor.rs
@@ -212,7 +212,20 @@ impl PathNoteEventProcessor {
         memo_file: &Arc<std::sync::RwLock<MemoFile>>,
         ctx: &NotebookWatchContext,
     ) {
+        if let Some(previous) = &event.rename_from {
+            crate::commands::external_document_watch::rebase_path(app, previous, &event.path);
+        }
+
         if process_media_event(event, memo_file, ctx) {
+            if let Some(old_path) = event.rename_from.as_ref() {
+                if let Ok(memo_file) = memo_file.read() {
+                    crate::commands::document_list::rebase_collection_paths_for_move(
+                        &memo_file,
+                        old_path,
+                        &event.path,
+                    );
+                }
+            }
             let old_media_path = event.rename_from.as_ref().and_then(|old_path| {
                 let old_ctx = NotebookWatchContext {
                     notebook_id: event.rename_from_notebook_id.clone().unwrap_or_else(|| ctx.notebook_id.clone()),
@@ -291,9 +304,8 @@ impl PathNoteEventProcessor {
                 // references before publishing its completion event.
                 return;
             }
-            if let Err(error) = memo_file.reconcile_note_index(&ctx.notebook_id) {
-                tracing::warn!(notebook_id = %ctx.notebook_id, "path rename reconciliation failed: {error}");
-            }
+            app.state::<crate::app::state::AppState>().notebook_background
+                .request(&ctx.notebook_id, true, true);
             drop(_write_guard);
             let old_path_is_markdown = is_markdown_path(old_path);
             let new_path_is_markdown = is_markdown_path(&event.path);
@@ -351,7 +363,21 @@ impl PathNoteEventProcessor {
         }
 
         match event.kind {
-            FsEventKind::Create | FsEventKind::Modify | FsEventKind::Remove => {
+            FsEventKind::Create => {
+                crate::commands::document_list::refresh_view_document_path(&memo_file, &event.path);
+                match refresh_path(&memo_file, ctx, &event.path) {
+                    Ok(DispatchOutcome::PathIndexed { relative_path }) => {
+                        crate::commands::path_change::NotebookPathCreated::from_external_tool(
+                            ctx.notebook_id.clone(),
+                            relative_path.clone(),
+                        )
+                        .emit(app);
+                        record_cloud_path_change(app, ctx, &relative_path, false);
+                    }
+                    Err(error) => tracing::debug!(path = %event.path.display(), "path refresh skipped: {error}"),
+                }
+            }
+            FsEventKind::Modify | FsEventKind::Remove => {
                 crate::commands::document_list::refresh_view_document_path(&memo_file, &event.path);
                 match refresh_path(&memo_file, ctx, &event.path) {
                     Ok(DispatchOutcome::PathIndexed { relative_path }) => {
@@ -369,26 +395,9 @@ impl PathNoteEventProcessor {
 
     fn reconcile_directory_change(app: &AppHandle, memo_file: &MemoFile, ctx: &NotebookWatchContext) {
         crate::commands::document_list::refresh_view_document_catalog(memo_file, &ctx.notebook_id, &ctx.root);
-        match memo_file.reconcile_note_index(&ctx.notebook_id) {
-            Ok(report) => tracing::info!(notebook_id = %ctx.notebook_id,
-                added = report.added, updated = report.updated, removed = report.removed,
-                "path index reconciliation completed"),
-            Err(error) => tracing::warn!(notebook_id = %ctx.notebook_id,
-                "path index reconciliation failed: {error}"),
-        }
+        app.state::<crate::app::state::AppState>().notebook_background
+            .request(&ctx.notebook_id, false, true);
         emit_path_changed(app, ctx, "", false);
-        match memo_file.reconcile_media_resources(&ctx.notebook_id) {
-            Ok(count) => {
-                tracing::debug!(notebook_id = %ctx.notebook_id, count, "media catalog reconciliation completed");
-                // Directory notifications can reach the UI before a large media scan
-                // finishes. Publish completion so an empty early query is refreshed.
-                let _ = app.emit(
-                    "file-management-changed",
-                    serde_json::json!({ "notebookId": ctx.notebook_id, "notebookPath": ctx.root.to_string_lossy() }),
-                );
-            }
-            Err(error) => tracing::warn!(notebook_id = %ctx.notebook_id, "media catalog reconciliation failed: {error}"),
-        }
     }
 
     pub(crate) fn unregister_and_emit(
diff --git a/app/flowix-desktop/src/watcher/rename_tracker.rs b/app/flowix-desktop/src/watcher/rename_tracker.rs
index 7f3ce7d42..5870936d5 100644
--- a/app/flowix-desktop/src/watcher/rename_tracker.rs
+++ b/app/flowix-desktop/src/watcher/rename_tracker.rs
@@ -11,6 +11,7 @@ use std::time::{Duration, Instant};
 
 #[derive(Default)]
 pub struct RenameTracker {
+    roots: HashSet<PathBuf>,
     known: HashMap<PathBuf, (u64, u64)>,
     known_directories: HashSet<PathBuf>,
     pending: HashMap<PathBuf, ((u64, u64), Instant)>,
@@ -43,30 +44,52 @@ impl RenameTracker {
     pub fn seed(roots: &[NotebookWatchContext]) -> Self {
         let mut tracker = Self::default();
         for root in roots {
-            let policy = FileManagementPolicy::from_notebook_root(&root.root);
-            for entry in walkdir::WalkDir::new(&root.root)
-                .follow_links(false)
-                .into_iter()
-                .filter_entry(|entry| {
-                    entry
-                        .path()
-                        .strip_prefix(&root.root)
-                        .is_ok_and(|relative| !policy.is_index_ignored_at(&root.root, relative))
-                })
-                .filter_map(Result::ok)
+            tracker.add_root(root);
+        }
+        tracker
+    }
+    pub fn seed_root(root: &NotebookWatchContext) -> Self {
+        let mut tracker = Self::default();
+        tracker.add_root(root);
+        tracker
+    }
+    pub fn merge_seed(&mut self, seed: Self) {
+        self.roots.extend(seed.roots);
+        self.known.extend(seed.known);
+        self.known_directories.extend(seed.known_directories);
+    }
+    pub fn add_root(&mut self, root: &NotebookWatchContext) {
+        self.roots.insert(root.root.clone());
+        let policy = FileManagementPolicy::from_notebook_root(&root.root);
+        for entry in walkdir::WalkDir::new(&root.root)
+            .follow_links(false)
+            .into_iter()
+            .filter_entry(|entry| {
+                entry
+                    .path()
+                    .strip_prefix(&root.root)
+                    .is_ok_and(|relative| !policy.is_index_ignored_at(&root.root, relative))
+            })
+            .filter_map(Result::ok)
+        {
+            if entry.file_type().is_dir()
+                || entry
+                    .path()
+                    .extension()
+                    .is_some_and(|ext| ext.eq_ignore_ascii_case("md"))
+                || media_kind_for_path(entry.path()).is_some()
             {
-                if entry.file_type().is_dir()
-                    || entry
-                        .path()
-                        .extension()
-                        .is_some_and(|ext| ext.eq_ignore_ascii_case("md"))
-                    || media_kind_for_path(entry.path()).is_some()
-                {
-                    tracker.observe(entry.path());
-                }
+                self.observe(entry.path());
             }
         }
-        tracker
+    }
+    pub fn forget_root(&mut self, root: &Path) {
+        self.roots.remove(root);
+        let roots = &self.roots;
+        let belongs_to_watched_root = |path: &Path| roots.iter().any(|base| path.starts_with(base));
+        self.known.retain(|path, _| belongs_to_watched_root(path));
+        self.known_directories.retain(|path| belongs_to_watched_root(path));
+        self.pending.retain(|path, _| belongs_to_watched_root(path));
     }
     fn observe(&mut self, path: &Path) {
         if let Some(identity) = filesystem_identity(path) {
diff --git a/app/flowix-desktop/src/watcher/runtime.rs b/app/flowix-desktop/src/watcher/runtime.rs
index 5333f5536..b63ce42fb 100644
--- a/app/flowix-desktop/src/watcher/runtime.rs
+++ b/app/flowix-desktop/src/watcher/runtime.rs
@@ -6,6 +6,31 @@ use tauri::{AppHandle, Manager};
 use crate::watcher::manager::MemoWatcher;
 use flowix_core::memo_file::atomic_write_bytes;
 
+/// Read a fresh registry snapshot without acquiring AppState's MemoFile lock.
+/// Call while holding the watcher binding lock, so delayed rebinds cannot apply
+/// older snapshots. Never replace this with a global MemoFile read: document
+/// operations hold that lock while recording watcher self-write marks.
+/// The facade uses the current registry path and does not run legacy migrations.
+pub(crate) fn read_registered_notebooks(
+    config_dir: &Path,
+) -> std::io::Result<Vec<flowix_core::memo_file::NotebookConfig>> {
+    flowix_core::memo_file::MemoFile::new(config_dir.to_path_buf()).read_notebook_configs()
+}
+
+/// After recovery, reconcile the roots that really attached. The integration
+/// layer owns queue admission; the watcher manager only owns OS bindings.
+pub(crate) fn reconcile_bound_roots(
+    watcher: &MemoWatcher,
+    configs: &[flowix_core::memo_file::NotebookConfig],
+    background: &crate::app::notebook_background::NotebookBackground,
+) {
+    for config in configs {
+        if watcher.is_watching(&config.id) {
+            background.request(&config.id, false, true);
+        }
+    }
+}
+
 pub fn current_watcher(app: &AppHandle) -> Option<Arc<RwLock<MemoWatcher>>> {
     app.try_state::<Arc<RwLock<MemoWatcher>>>()
         .map(|s| s.inner().clone())
@@ -51,3 +76,61 @@ pub(crate) fn write_note_atomic(
     mark_self_write_content_for(app, path, content);
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use flowix_core::memo_file::{MemoFile, NotebookConfig};
+
+    fn notebook(root: &Path) -> NotebookConfig {
+        NotebookConfig {
+            id: "notebook".into(), name: "Notebook".into(), icon: None,
+            path: root.to_string_lossy().into_owned(), is_default: false,
+            sort: 0, created_at: 1, updated_at: 1,
+        }
+    }
+
+    #[test]
+    fn registry_snapshot_observes_updates_from_another_facade() {
+        let temp = tempfile::tempdir().unwrap();
+        let memo = MemoFile::new(temp.path().to_path_buf());
+        let mut config = notebook(&temp.path().join("book"));
+        memo.write_notebook_configs(&[config.clone()]).unwrap();
+        assert_eq!(read_registered_notebooks(temp.path()).unwrap()[0].name, "Notebook");
+        config.name = "Renamed".into();
+        memo.write_notebook_configs(&[config]).unwrap();
+        assert_eq!(read_registered_notebooks(temp.path()).unwrap()[0].name, "Renamed");
+        memo.write_notebook_configs(&[]).unwrap();
+        assert!(read_registered_notebooks(temp.path()).unwrap().is_empty());
+    }
+
+    #[test]
+    fn registry_snapshot_under_watcher_lock_does_not_wait_for_global_memo_lock() {
+        let temp = tempfile::tempdir().unwrap();
+        let memo = Arc::new(RwLock::new(MemoFile::new(temp.path().to_path_buf())));
+        memo.read().unwrap().write_notebook_configs(&[notebook(&temp.path().join("book"))]).unwrap();
+        let watcher = Arc::new(RwLock::new(MemoWatcher::new(memo.clone())));
+        let held_memo = memo.write().unwrap();
+        let config_dir = temp.path().to_path_buf();
+        let (tx, rx) = std::sync::mpsc::channel();
+        let worker = std::thread::spawn(move || {
+            let _binding = watcher.write().unwrap();
+            tx.send(read_registered_notebooks(&config_dir).map(|configs| configs.len())).unwrap();
+        });
+        let snapshot = rx.recv_timeout(std::time::Duration::from_secs(3));
+        // Release before asserting/joining so a regression cannot strand a thread.
+        drop(held_memo);
+        worker.join().unwrap();
+        assert_eq!(snapshot.unwrap().unwrap(), 1);
+    }
+
+    #[test]
+    fn unreadable_registry_is_an_error_not_an_empty_snapshot_or_rebuild() {
+        let temp = tempfile::tempdir().unwrap();
+        std::fs::create_dir_all(temp.path().join("db")).unwrap();
+        let db = temp.path().join("db/local.db");
+        std::fs::write(&db, b"invalid database").unwrap();
+        assert!(read_registered_notebooks(temp.path()).is_err());
+        assert_eq!(std::fs::read(db).unwrap(), b"invalid database");
+    }
+}
diff --git a/app/flowix-desktop/tauri.conf.dev.json b/app/flowix-desktop/tauri.conf.dev.json
index 320956f8d..6158c24fe 100644
--- a/app/flowix-desktop/tauri.conf.dev.json
+++ b/app/flowix-desktop/tauri.conf.dev.json
@@ -2,7 +2,7 @@
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Flowix Dev",
   "mainBinaryName": "Flowix Dev",
-  "identifier": "com.flowix.app.dev",
+  "identifier": "com.flowix-dev.app",
   "plugins": {
     "deep-link": {
       "desktop": { "schemes": ["flowix-dev"] }
diff --git a/app/flowix-desktop/tauri.conf.json b/app/flowix-desktop/tauri.conf.json
index 5cf71c3c8..6785a4fdb 100644
--- a/app/flowix-desktop/tauri.conf.json
+++ b/app/flowix-desktop/tauri.conf.json
@@ -2,7 +2,7 @@
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Flowix",
   "mainBinaryName": "Flowix",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "identifier": "com.flowix.app",
   "build": {
     "beforeDevCommand": "npm run dev",
@@ -40,7 +40,11 @@
   },
   "plugins": {
     "deep-link": {
-      "desktop": { "schemes": ["flowix"] }
+      "desktop": {
+        "schemes": [
+          "flowix"
+        ]
+      }
     },
     "updater": {
       "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXkgRUEyNzZBMzYyMDQyNEI1MApSV1JRUzBJZ05tb242a1lBZDlLYnZJYkVXNm84VFIvTWZ2ODhLS29kM2lFaGVWSzBwejF2TEQyWgo=",
diff --git a/app/flowix-desktop/tauri.windows.dev.conf.json b/app/flowix-desktop/tauri.windows.dev.conf.json
index 5cfa24b74..37239c729 100644
--- a/app/flowix-desktop/tauri.windows.dev.conf.json
+++ b/app/flowix-desktop/tauri.windows.dev.conf.json
@@ -2,7 +2,7 @@
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Flowix Dev",
   "mainBinaryName": "Flowix Dev",
-  "identifier": "com.flowix.app.dev",
+  "identifier": "com.flowix-dev.app",
   "plugins": {
     "deep-link": {
       "desktop": { "schemes": ["flowix-dev"] }
diff --git a/app/flowix-sync/Cargo.toml b/app/flowix-sync/Cargo.toml
index acbc01bf4..c217e4cdd 100644
--- a/app/flowix-sync/Cargo.toml
+++ b/app/flowix-sync/Cargo.toml
@@ -3,6 +3,7 @@ name = "flowix-sync"
 version.workspace = true
 description = "Flowix Cloud authentication and notebook synchronization engine"
 edition.workspace = true
+build = "build.rs"
 
 [lib]
 name = "flowix_sync"
diff --git a/app/flowix-sync/build.rs b/app/flowix-sync/build.rs
new file mode 100644
index 000000000..9adb81f7a
--- /dev/null
+++ b/app/flowix-sync/build.rs
@@ -0,0 +1,18 @@
+fn main() {
+    println!("cargo:rerun-if-env-changed=FLOWIX_CLOUD_ENVIRONMENT");
+    println!("cargo:rerun-if-env-changed=FLOWIX_DEV_MODE");
+
+    let is_dev_build = matches!(std::env::var("FLOWIX_DEV_MODE").as_deref(), Ok("1"));
+    let configured_environment = std::env::var("FLOWIX_CLOUD_ENVIRONMENT")
+        .unwrap_or_else(|_| "prod".to_owned());
+    let environment = if is_dev_build {
+        configured_environment.as_str()
+    } else {
+        "prod"
+    };
+    match environment {
+        "staging" | "prod" => (),
+        other => panic!("FLOWIX_CLOUD_ENVIRONMENT must be staging or prod, got {other:?}"),
+    }
+    println!("cargo:rustc-env=FLOWIX_CLOUD_ENVIRONMENT={environment}");
+}
diff --git a/app/flowix-sync/src/client.rs b/app/flowix-sync/src/client.rs
index 7c3ca47b9..5acf8cba0 100644
--- a/app/flowix-sync/src/client.rs
+++ b/app/flowix-sync/src/client.rs
@@ -4,8 +4,9 @@ use serde_json::json;
 
 use crate::error::SyncError;
 use crate::models::{
-    ApiErrorEnvelope, AppleAuthChallenge, AppleAuthorization, AuthData, CloudCheckout,
-    CloudProduct, DataEnvelope, EntitlementData, MeData, RefreshData,
+    ApiErrorEnvelope, AppleAuthChallenge, AppleAuthorization, AuthData, CloudAiCredential,
+    CloudCheckout, CloudOrder, CloudOrderCheck, CloudProduct, DataEnvelope, EntitlementData,
+    MeData, RefreshData,
 };
 use crate::v2::{
     V2BlobDownloadEnvelope, V2BlobReservationEnvelope, V2Bootstrap, V2ChangesPage, V2History,
@@ -133,7 +134,6 @@ impl CloudClient {
             .json(&json!({
                 "productId": product_id,
                 "successUrl": "flowix://billing/success",
-                "cancelUrl": "flowix://billing/cancel",
             }))
             .send()
             .await?;
@@ -142,6 +142,61 @@ impl CloudClient {
             .map(|value| value.data)
     }
 
+    pub(crate) async fn billing_orders(
+        &self,
+        access_token: &str,
+    ) -> Result<Vec<CloudOrder>, SyncError> {
+        self.send::<DataEnvelope<Vec<CloudOrder>>>(
+            Method::GET,
+            "/v2/billing/orders",
+            Some(access_token),
+            None,
+        )
+        .await
+        .map(|value| value.data)
+    }
+
+    pub(crate) async fn check_billing_order(
+        &self,
+        access_token: &str,
+        order_id: &str,
+    ) -> Result<CloudOrderCheck, SyncError> {
+        self.send::<DataEnvelope<CloudOrderCheck>>(
+            Method::POST,
+            &format!("/v2/billing/orders/{order_id}/check"),
+            Some(access_token),
+            Some(json!({})),
+        )
+        .await
+        .map(|value| value.data)
+    }
+
+    pub(crate) async fn submit_feedback(
+        &self,
+        device_id: &str,
+        kind: &str,
+        content: &str,
+        app_version: &str,
+        platform: &str,
+        attachments: &[serde_json::Value],
+    ) -> Result<(), SyncError> {
+        self.send::<serde_json::Value>(
+            Method::POST,
+            "/v1/feedback",
+            None,
+            Some(json!({
+                "deviceId": device_id,
+                "type": kind,
+                "content": content,
+                "appVersion": app_version,
+                "platform": platform,
+                "attachments": attachments,
+            })),
+        )
+        .await
+        .map(|_| ())
+    }
+
     pub(crate) async fn register(
         &self,
         email: &str,
@@ -279,6 +334,45 @@ impl CloudClient {
         .map(|value| value.data)
     }
 
+    pub(crate) async fn create_ai_credential(
+        &self,
+        access_token: &str,
+    ) -> Result<CloudAiCredential, SyncError> {
+        self.send::<DataEnvelope<CloudAiCredential>>(
+            Method::POST,
+            "/v1/ai/credentials",
+            Some(access_token),
+            Some(json!({})),
+        )
+        .await
+        .map(|value| value.data)
+    }
+
+    pub(crate) async fn ai_credit_balance(
+        &self,
+        access_token: &str,
+    ) -> Result<crate::models::CloudAiCreditBalance, SyncError> {
+        self.send::<DataEnvelope<crate::models::CloudAiCreditBalance>>(
+            Method::GET,
+            "/v1/account/ai-credits",
+            Some(access_token),
+            None,
+        )
+        .await
+        .map(|value| value.data)
+    }
+
+    pub(crate) async fn revoke_ai_credential(&self, access_token: &str) -> Result<(), SyncError> {
+        self.send::<DataEnvelope<serde_json::Value>>(
+            Method::DELETE,
+            "/v1/ai/credentials/current",
+            Some(access_token),
+            None,
+        )
+        .await
+        .map(|_| ())
+    }
+
     pub async fn v2_sync_status(
         &self,
         access_token: &str,
diff --git a/app/flowix-sync/src/environment.rs b/app/flowix-sync/src/environment.rs
new file mode 100644
index 000000000..fb6c3963a
--- /dev/null
+++ b/app/flowix-sync/src/environment.rs
@@ -0,0 +1,34 @@
+/// Cloud target used by the desktop application.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CloudEnvironment {
+    Staging,
+    Prod,
+}
+
+impl CloudEnvironment {
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::Staging => "staging",
+            Self::Prod => "prod",
+        }
+    }
+
+    pub const fn api_base(self) -> &'static str {
+        match self {
+            Self::Staging => "https://staging-cloud.flowix.cc",
+            Self::Prod => "https://cloud.flowix.cc",
+        }
+    }
+
+    pub fn parse(name: &str) -> Option<Self> {
+        match name {
+            "staging" => Some(Self::Staging),
+            "prod" => Some(Self::Prod),
+            _ => None,
+        }
+    }
+}
+
+pub fn default_cloud_environment() -> CloudEnvironment {
+    CloudEnvironment::parse(env!("FLOWIX_CLOUD_ENVIRONMENT")).unwrap_or(CloudEnvironment::Prod)
+}
diff --git a/app/flowix-sync/src/lib.rs b/app/flowix-sync/src/lib.rs
index 5e1e22ab9..401264cd9 100644
--- a/app/flowix-sync/src/lib.rs
+++ b/app/flowix-sync/src/lib.rs
@@ -5,6 +5,7 @@
 //! HTTP contract, sync state database, revisions, cursors and conflict plans.
 
 mod client;
+mod environment;
 mod error;
 mod manager;
 mod models;
@@ -12,28 +13,26 @@ mod store;
 mod v2;
 
 pub use client::CloudClient;
+pub use environment::{default_cloud_environment, CloudEnvironment};
 pub use error::SyncError;
-pub use manager::SyncManager;
+pub use manager::{PendingLogout, SyncManager};
 pub use models::{
-    AppleAuthChallenge, AppleAuthorization, CloudAuthStatus, CloudCheckout,
-    CloudMembership,
-    CloudNotebook, CloudPrice, CloudProduct, CloudState, CloudUser, LocalChangeKind,
+    AppleAuthChallenge, AppleAuthorization, CloudAiCredential, CloudAiCreditBalance, CloudAiModel,
+    CloudAiProvider, CloudAuthStatus, CloudCheckout, CloudMembership, CloudNotebook, CloudOrder,
+    CloudOrderCheck, CloudPrice, CloudProduct, CloudState, CloudUser, LocalChangeKind,
     ProductDuration, ProductEntitlement, RefreshTokenStore,
 };
 pub use store::SyncStore;
 pub use v2::{
     collect_v2_attachments, new_v2_operation_id, referenced_attachment_paths, v2_content_hash,
-    v2_local_content_diverged, v2_notebook_metadata_hash, v2_path_note_id, V2AccountSyncReport, V2Attachment,
-    V2BlobDownload, V2BlobDownloadCapability, V2BlobDownloadEnvelope, V2BlobReservation,
-    V2BlobReservationEnvelope, V2BlobUpload, V2Bootstrap, V2BootstrapNote, V2Change, V2ChangesPage, V2CloudAccount,
-    V2History, V2HistoryRevision,
-    V2ConflictMaterial,
-    V2DirtyEntity, V2EntityType, V2FreezeOperation, V2InflightOperation, V2LocalAttachment,
+    v2_local_content_diverged, v2_notebook_metadata_hash, v2_path_note_id, V2AccountSyncReport,
+    V2Attachment, V2BlobDownload, V2BlobDownloadCapability, V2BlobDownloadEnvelope,
+    V2BlobReservation, V2BlobReservationEnvelope, V2BlobUpload, V2Bootstrap, V2BootstrapNote,
+    V2Change, V2ChangesPage, V2CloudAccount, V2ConflictMaterial, V2DirtyEntity, V2EntityType,
+    V2FreezeOperation, V2History, V2HistoryRevision, V2InflightOperation, V2LocalAttachment,
     V2LocalNote, V2LocalNotebook, V2NoteState, V2NotebookState, V2OperationError, V2OperationKind,
-    V2PendingMove,
-    V2PushOperation, V2PushResult, V2RemoteApply, V2RemoteAttachment, V2SyncStatus,
+    V2PendingMove, V2PushOperation, V2PushResult, V2RemoteApply, V2RemoteAttachment, V2SyncStatus,
     V2SyncedNotebook, PROTOCOL_EPOCH,
 };
 
-pub const DEFAULT_CLOUD_API_BASE: &str = "https://cloud.flowix.cc";
 pub mod text_merge;
diff --git a/app/flowix-sync/src/manager.rs b/app/flowix-sync/src/manager.rs
index d60ad7e73..c736b2f8f 100644
--- a/app/flowix-sync/src/manager.rs
+++ b/app/flowix-sync/src/manager.rs
@@ -6,7 +6,8 @@ use crate::client::CloudClient;
 use crate::error::SyncError;
 use crate::models::{
     AppleAuthChallenge, AppleAuthorization, CloudAuthStatus, CloudCheckout, CloudMembership,
-    CloudProduct, CloudState, LocalChangeKind, RefreshTokenStore, RuntimeSession,
+    CloudOrder, CloudOrderCheck, CloudProduct, CloudState, LocalChangeKind, RefreshTokenStore,
+    RuntimeSession,
 };
 use crate::store::SyncStore;
 use crate::v2::{
@@ -31,6 +32,12 @@ pub struct SyncManager {
     state_notifier: Arc<dyn Fn(CloudState) + Send + Sync>,
 }
 
+/// Local logout has completed; finish this value to revoke its server session.
+pub struct PendingLogout {
+    refresh_token: Option<String>,
+    local_cleanup: Result<(), SyncError>,
+}
+
 struct AuthState {
     session: Option<RuntimeSession>,
     status: CloudAuthStatus,
diff --git a/app/flowix-sync/src/manager/auth.rs b/app/flowix-sync/src/manager/auth.rs
index 8befe0b95..5f414d623 100644
--- a/app/flowix-sync/src/manager/auth.rs
+++ b/app/flowix-sync/src/manager/auth.rs
@@ -181,22 +181,24 @@ impl SyncManager {
         Ok(next_generation)
     }
 
-    pub async fn logout(&self) -> Result<(), SyncError> {
-        self.logout_with_cleanup(|| self.delete_persisted_refresh_token())
-            .await
+    /// Clear local authentication immediately and return a handle for remote revocation.
+    pub fn begin_logout(&self) -> PendingLogout {
+        let (refresh_token, local_cleanup) =
+            self.clear_auth_with_cleanup(|| self.delete_persisted_refresh_token());
+        PendingLogout {
+            refresh_token,
+            local_cleanup,
+        }
     }
 
-    async fn logout_with_cleanup(
-        &self,
-        cleanup: impl FnOnce() -> Result<(), SyncError>,
-    ) -> Result<(), SyncError> {
-        let (refresh_token, local_cleanup) = self.clear_auth_with_cleanup(cleanup);
-        let remote_logout = if let Some(refresh_token) = refresh_token {
+    /// Revoke a session after its local state and dependent UI have been cleared.
+    pub async fn finish_logout(&self, pending: PendingLogout) -> Result<(), SyncError> {
+        let remote_logout = if let Some(refresh_token) = pending.refresh_token {
             self.client.logout_with_refresh_token(&refresh_token).await
         } else {
             Ok(())
         };
-        if let Err(error) = local_cleanup {
+        if let Err(error) = pending.local_cleanup {
             if let Err(remote_error) = remote_logout {
                 tracing::warn!(
                     "failed to revoke Flowix Cloud session during local logout: {remote_error}"
@@ -207,6 +209,10 @@ impl SyncManager {
         remote_logout
     }
 
+    pub async fn logout(&self) -> Result<(), SyncError> {
+        self.finish_logout(self.begin_logout()).await
+    }
+
     fn clear_auth_with_cleanup(
         &self,
         cleanup: impl FnOnce() -> Result<(), SyncError>,
@@ -426,7 +432,6 @@ mod tests {
                         id: token.into(),
                         email: "test@example.test".into(),
                         display_name: "Test".into(),
-                        system_role: "user".into(),
                     },
                     protocol_epoch: crate::v2::PROTOCOL_EPOCH,
                 },
@@ -551,6 +556,24 @@ mod tests {
         }
     }
 
+    #[test]
+    fn begin_logout_clears_local_session_before_remote_revocation() {
+        let directory = tempfile::tempdir().unwrap();
+        let manager = SyncManager::new(
+            "https://cloud.example.test",
+            directory.path().join("sync.db"),
+        )
+        .unwrap();
+        let generation = sign_in(&manager, "current");
+
+        let pending = manager.begin_logout();
+
+        assert!(!manager.state().unwrap().authenticated);
+        assert!(manager.session_generation() > generation);
+        assert_eq!(pending.refresh_token.as_deref(), Some("current"));
+        assert!(pending.local_cleanup.is_ok());
+    }
+
     #[test]
     fn late_refresh_cannot_restore_a_logged_out_session() {
         let directory = tempfile::tempdir().unwrap();
diff --git a/app/flowix-sync/src/manager/catalog.rs b/app/flowix-sync/src/manager/catalog.rs
index 9288a0db4..bab57af98 100644
--- a/app/flowix-sync/src/manager/catalog.rs
+++ b/app/flowix-sync/src/manager/catalog.rs
@@ -1,6 +1,59 @@
 use super::*;
 
 impl SyncManager {
+    /// Monotonic identity for the current in-memory Cloud login session.
+    /// Runtime adapters use this to refresh session-bound API credentials only
+    /// after a sign-in transition, not before every request.
+    pub fn ai_credential_session_generation(&self) -> u64 {
+        self.auth_generation()
+    }
+
+    pub async fn ai_credit_balance(
+        &self,
+    ) -> Result<crate::models::CloudAiCreditBalance, SyncError> {
+        let generation = self.auth_generation();
+        let access_token = self.access_token(generation).await?;
+        let first = self.client.ai_credit_balance(&access_token).await;
+        let balance = if first.as_ref().is_err_and(SyncError::is_unauthorized) {
+            let refreshed = self.force_refresh_access_token(generation).await?;
+            self.client.ai_credit_balance(&refreshed).await?
+        } else {
+            first?
+        };
+        let _generation = self.require_auth_generation(generation)?;
+        Ok(balance)
+    }
+
+    pub async fn create_ai_credential(
+        &self,
+    ) -> Result<crate::models::CloudAiCredential, SyncError> {
+        let generation = self.auth_generation();
+        let access_token = self.access_token(generation).await?;
+        let first = self.client.create_ai_credential(&access_token).await;
+        let credential = if first.as_ref().is_err_and(SyncError::is_unauthorized) {
+            let refreshed = self.force_refresh_access_token(generation).await?;
+            self.client.create_ai_credential(&refreshed).await?
+        } else {
+            first?
+        };
+        let _generation = self.require_auth_generation(generation)?;
+        Ok(credential)
+    }
+
+    pub async fn revoke_ai_credential(&self) -> Result<(), SyncError> {
+        let generation = self.auth_generation();
+        let access_token = self.access_token(generation).await?;
+        let first = self.client.revoke_ai_credential(&access_token).await;
+        if first.as_ref().is_err_and(SyncError::is_unauthorized) {
+            let refreshed = self.force_refresh_access_token(generation).await?;
+            self.client.revoke_ai_credential(&refreshed).await?;
+        } else {
+            first?;
+        }
+        let _generation = self.require_auth_generation(generation)?;
+        Ok(())
+    }
+
     pub async fn refresh_membership(&self) -> Result<CloudMembership, SyncError> {
         let generation = self.auth_generation();
         let mut refresh = match self.membership_refresh.try_lock() {
@@ -49,6 +102,48 @@ impl SyncManager {
         self.client.products().await
     }
 
+    pub async fn billing_orders(&self) -> Result<Vec<CloudOrder>, SyncError> {
+        let generation = self.auth_generation();
+        let token = self.access_token(generation).await?;
+        let first = self.client.billing_orders(&token).await;
+        let result = if first.as_ref().is_err_and(SyncError::is_unauthorized) {
+            let refreshed = self.force_refresh_access_token(generation).await?;
+            self.client.billing_orders(&refreshed).await
+        } else {
+            first
+        };
+        let _generation = self.require_auth_generation(generation)?;
+        result
+    }
+
+    pub async fn check_billing_order(&self, order_id: &str) -> Result<CloudOrderCheck, SyncError> {
+        let generation = self.auth_generation();
+        let token = self.access_token(generation).await?;
+        let first = self.client.check_billing_order(&token, order_id).await;
+        let result = if first.as_ref().is_err_and(SyncError::is_unauthorized) {
+            let refreshed = self.force_refresh_access_token(generation).await?;
+            self.client.check_billing_order(&refreshed, order_id).await
+        } else {
+            first
+        };
+        let _generation = self.require_auth_generation(generation)?;
+        result
+    }
+
+    pub async fn submit_feedback(
+        &self,
+        device_id: &str,
+        kind: &str,
+        content: &str,
+        app_version: &str,
+        platform: &str,
+        attachments: &[serde_json::Value],
+    ) -> Result<(), SyncError> {
+        self.client
+            .submit_feedback(device_id, kind, content, app_version, platform, attachments)
+            .await
+    }
+
     pub async fn create_checkout(
         &self,
         product_id: &str,
diff --git a/app/flowix-sync/src/manager/lifecycle/tests.rs b/app/flowix-sync/src/manager/lifecycle/tests.rs
index 5037a23e0..58e8603b2 100644
--- a/app/flowix-sync/src/manager/lifecycle/tests.rs
+++ b/app/flowix-sync/src/manager/lifecycle/tests.rs
@@ -89,7 +89,7 @@ impl Drop for Server {
 }
 
 fn user(id: &str) -> Value {
-    json!({ "id": id, "email": format!("{id}@example.test"), "displayName": id, "systemRole": "user" })
+    json!({ "id": id, "email": format!("{id}@example.test"), "displayName": id })
 }
 fn session(id: &str) -> Value {
     json!({ "accessToken": format!("access-{id}"), "accessTokenExpiresAt": 4_102_444_800_000_i64,
diff --git a/app/flowix-sync/src/manager/state.rs b/app/flowix-sync/src/manager/state.rs
index 3f9df6d47..956d8fdfd 100644
--- a/app/flowix-sync/src/manager/state.rs
+++ b/app/flowix-sync/src/manager/state.rs
@@ -25,6 +25,17 @@ impl SyncManager {
         Self::create(api_base, database_path, Some(token_store), state_notifier)
     }
 
+    /// Desktop startup variant: defer database migrations and credential
+    /// restoration to the initialization worker.
+    pub fn new_with_session_dependencies_deferred(
+        api_base: &str,
+        database_path: impl AsRef<Path>,
+        token_store: Arc<dyn RefreshTokenStore>,
+        state_notifier: Arc<dyn Fn(CloudState) + Send + Sync>,
+    ) -> Result<Self, SyncError> {
+        Self::create_deferred(api_base, database_path, Some(token_store), state_notifier)
+    }
+
     fn create(
         api_base: &str,
         database_path: impl AsRef<Path>,
@@ -32,24 +43,37 @@ impl SyncManager {
         state_notifier: Arc<dyn Fn(CloudState) + Send + Sync>,
     ) -> Result<Self, SyncError> {
         let sync_store = SyncStore::new(database_path)?;
-        let restore_blocked = sync_store.session_restore_blocked()?;
         let credential_retry = Arc::new(tokio::sync::Notify::new());
+        let manager = Self {
+            client: CloudClient::new(api_base)?,
+            store: sync_store,
+            auth: Arc::new(RwLock::new(AuthState::default())),
+            membership: Arc::new(RwLock::new(None)),
+            membership_refresh: Arc::new(tokio::sync::Mutex::new(None)),
+            refresh_lock: Arc::new(tokio::sync::Mutex::new(())),
+            auth_generation: Arc::new(std::sync::Mutex::new(0)),
+            account_sync_lock: Arc::new(tokio::sync::Mutex::new(())),
+            refresh_token_store: token_store,
+            credential_retry,
+            state_notifier,
+        };
+        manager.initialize_storage()?;
+        Ok(manager)
+    }
+
+    fn create_deferred(
+        api_base: &str,
+        database_path: impl AsRef<Path>,
+        token_store: Option<Arc<dyn RefreshTokenStore>>,
+        state_notifier: Arc<dyn Fn(CloudState) + Send + Sync>,
+    ) -> Result<Self, SyncError> {
         let mut auth = AuthState::default();
-        if let Some(store) = token_store.as_ref() {
-            if restore_blocked {
-                auth.pending_credential = Some(CredentialWrite::Delete);
-                credential_retry.notify_one();
-            } else {
-                match store.load() {
-                    Ok(Some(_)) => auth.status = CloudAuthStatus::Restoring,
-                    Ok(None) => {}
-                    Err(error) => auth.error = Some(error),
-                }
-            }
+        if token_store.is_some() {
+            auth.status = CloudAuthStatus::Restoring;
         }
         Ok(Self {
             client: CloudClient::new(api_base)?,
-            store: sync_store,
+            store: SyncStore::new_uninitialized(database_path),
             auth: Arc::new(RwLock::new(auth)),
             membership: Arc::new(RwLock::new(None)),
             membership_refresh: Arc::new(tokio::sync::Mutex::new(None)),
@@ -57,11 +81,59 @@ impl SyncManager {
             auth_generation: Arc::new(std::sync::Mutex::new(0)),
             account_sync_lock: Arc::new(tokio::sync::Mutex::new(())),
             refresh_token_store: token_store,
-            credential_retry,
+            credential_retry: Arc::new(tokio::sync::Notify::new()),
             state_notifier,
         })
     }
 
+    pub fn initialize_storage(&self) -> Result<(), SyncError> {
+        self.store.initialize_schema()?;
+        let restore_blocked = self.store.session_restore_blocked()?;
+        let Some(token_store) = self.refresh_token_store.as_ref() else {
+            return Ok(());
+        };
+        // Reading the OS credential store may block. Do not hold the auth lock,
+        // and never overwrite login/logout that happened after the shell opened.
+        if self.auth_generation() != 0 {
+            return Ok(());
+        }
+        let token = if restore_blocked {
+            Ok(None)
+        } else {
+            token_store.load()
+        };
+        let Ok(generation_guard) = self.require_auth_generation(0) else {
+            return Ok(());
+        };
+        let mut auth = self.auth.write().unwrap_or_else(|p| p.into_inner());
+        if auth.session.is_none() {
+            let previous = (auth.status, auth.error.clone());
+            auth.error = None;
+            if restore_blocked {
+                auth.status = CloudAuthStatus::SignedOut;
+                auth.pending_credential = Some(CredentialWrite::Delete);
+                self.credential_retry.notify_one();
+            } else {
+                match token {
+                    Ok(Some(_)) => auth.status = CloudAuthStatus::Restoring,
+                    Ok(None) => auth.status = CloudAuthStatus::SignedOut,
+                    Err(error) => {
+                        auth.status = CloudAuthStatus::Restoring;
+                        auth.error = Some(error);
+                    }
+                }
+            }
+            // The deferred initial snapshot can still be in flight when the
+            // background result is emitted. Give a changed result a newer revision.
+            if previous != (auth.status, auth.error.clone()) {
+                auth.revision = auth.revision.saturating_add(1);
+            }
+        }
+        drop(auth);
+        drop(generation_guard);
+        Ok(())
+    }
+
     pub fn store(&self) -> &SyncStore {
         &self.store
     }
@@ -86,3 +158,97 @@ impl SyncManager {
         })
     }
 }
+
+#[cfg(test)]
+mod deferred_startup_tests {
+    use super::*;
+    use std::sync::{mpsc, Mutex};
+    use std::time::Duration;
+
+    struct DelayedTokenStore {
+        entered: mpsc::Sender<()>,
+        release: Mutex<mpsc::Receiver<()>>,
+    }
+    impl RefreshTokenStore for DelayedTokenStore {
+        fn load(&self) -> Result<Option<String>, String> {
+            self.entered.send(()).unwrap();
+            self.release
+                .lock()
+                .unwrap()
+                .recv_timeout(Duration::from_secs(3))
+                .unwrap();
+            Ok(Some("old-session".into()))
+        }
+        fn save(&self, _: &str) -> Result<(), String> {
+            Ok(())
+        }
+        fn delete(&self) -> Result<(), String> {
+            Ok(())
+        }
+    }
+
+    struct EmptyTokenStore;
+    impl RefreshTokenStore for EmptyTokenStore {
+        fn load(&self) -> Result<Option<String>, String> {
+            Ok(None)
+        }
+        fn save(&self, _: &str) -> Result<(), String> {
+            Ok(())
+        }
+        fn delete(&self) -> Result<(), String> {
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn deferred_credential_result_has_a_newer_revision_than_initial_snapshot() {
+        let temp = tempfile::tempdir().unwrap();
+        let manager = SyncManager::new_with_session_dependencies_deferred(
+            "http://127.0.0.1:1",
+            temp.path().join("sync.db"),
+            Arc::new(EmptyTokenStore),
+            Arc::new(|_| {}),
+        )
+        .unwrap();
+        let before = manager.state().unwrap();
+        assert_eq!(before.auth_status, CloudAuthStatus::Restoring);
+        manager.initialize_storage().unwrap();
+        let after = manager.state().unwrap();
+        assert_eq!(after.auth_status, CloudAuthStatus::SignedOut);
+        assert!(after.revision > before.revision);
+        manager.initialize_storage().unwrap();
+        assert_eq!(manager.state().unwrap().revision, after.revision);
+    }
+
+    #[tokio::test]
+    async fn delayed_startup_credentials_cannot_overwrite_explicit_logout() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("sync.db");
+        let (entered, started) = mpsc::channel();
+        let (release, wait) = mpsc::channel();
+        let manager = Arc::new(
+            SyncManager::new_with_session_dependencies_deferred(
+                "http://127.0.0.1:1",
+                &path,
+                Arc::new(DelayedTokenStore {
+                    entered,
+                    release: Mutex::new(wait),
+                }),
+                Arc::new(|_| {}),
+            )
+            .unwrap(),
+        );
+        assert!(!path.exists());
+        assert!(started.try_recv().is_err());
+        let worker_manager = manager.clone();
+        let worker = std::thread::spawn(move || worker_manager.initialize_storage());
+        started.recv_timeout(Duration::from_secs(3)).unwrap();
+        manager.logout().await.unwrap();
+        release.send(()).unwrap();
+        worker.join().unwrap().unwrap();
+        assert_eq!(
+            manager.state().unwrap().auth_status,
+            CloudAuthStatus::SignedOut
+        );
+    }
+}
diff --git a/app/flowix-sync/src/models.rs b/app/flowix-sync/src/models.rs
index 54f475f45..240f904ce 100644
--- a/app/flowix-sync/src/models.rs
+++ b/app/flowix-sync/src/models.rs
@@ -6,7 +6,6 @@ pub struct CloudUser {
     pub id: String,
     pub email: String,
     pub display_name: String,
-    pub system_role: String,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -121,6 +120,50 @@ pub struct CloudMembership {
     pub read_only: bool,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudAiCredential {
+    pub api_key: String,
+    pub model: CloudAiModel,
+    #[serde(default)]
+    pub models: Vec<CloudAiModel>,
+    #[serde(default)]
+    pub provider: Option<CloudAiProvider>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudAiCreditBalance {
+    pub balance_microcredits: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudAiModel {
+    pub id: String,
+    #[serde(default)]
+    pub title: Option<String>,
+    #[serde(default)]
+    pub subtitle: Option<String>,
+    #[serde(default)]
+    pub credit_multiplier: Option<f64>,
+    #[serde(default)]
+    pub provider_id: Option<String>,
+    #[serde(default)]
+    pub provider_name: Option<String>,
+    #[serde(default)]
+    pub provider_icon_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudAiProvider {
+    pub id: String,
+    pub display_name: String,
+    #[serde(default)]
+    pub icon_url: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CloudProduct {
@@ -160,6 +203,27 @@ pub struct CloudCheckout {
     pub expires_at: Option<i64>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudOrder {
+    pub id: String,
+    pub product_id: String,
+    pub product_name: String,
+    pub amount: i64,
+    pub currency: String,
+    pub status: String,
+    pub created_at: i64,
+    pub paid_at: Option<i64>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudOrderCheck {
+    pub status: String,
+    pub confirmed: bool,
+    pub check_status: String,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CloudState {
diff --git a/app/flowix-sync/src/store.rs b/app/flowix-sync/src/store.rs
index 0ac78999d..b0a6c2fad 100644
--- a/app/flowix-sync/src/store.rs
+++ b/app/flowix-sync/src/store.rs
@@ -8,6 +8,8 @@ use crate::error::SyncError;
 #[derive(Clone)]
 pub struct SyncStore {
     path: PathBuf,
+    schema_ready: std::sync::Arc<std::sync::atomic::AtomicBool>,
+    schema_lock: std::sync::Arc<std::sync::Mutex<()>>,
 }
 
 mod schema;
diff --git a/app/flowix-sync/src/store/schema.rs b/app/flowix-sync/src/store/schema.rs
index d6f8e0b5f..21cbd008f 100644
--- a/app/flowix-sync/src/store/schema.rs
+++ b/app/flowix-sync/src/store/schema.rs
@@ -2,14 +2,57 @@ use super::*;
 
 impl SyncStore {
     pub fn new(path: impl AsRef<Path>) -> Result<Self, SyncError> {
-        let store = Self {
-            path: path.as_ref().to_path_buf(),
-        };
-        store.open()?;
+        let store = Self::new_uninitialized(path);
+        store.initialize_schema()?;
         Ok(store)
     }
 
+    pub fn new_uninitialized(path: impl AsRef<Path>) -> Self {
+        Self {
+            path: path.as_ref().to_path_buf(),
+            schema_ready: Default::default(),
+            schema_lock: Default::default(),
+        }
+    }
+
+    pub fn initialize_schema(&self) -> Result<(), SyncError> {
+        let _guard = self.schema_lock.lock().unwrap_or_else(|p| p.into_inner());
+        self.initialize_schema_locked()
+    }
+
+    fn initialize_schema_locked(&self) -> Result<(), SyncError> {
+        flowix_core::memo_file::with_database_rebuild(&self.path, || {
+            let connection = self.open_raw().map_err(std::io::Error::other)?;
+            Self::initialize_v2_schema(&connection).map_err(std::io::Error::other)?;
+            connection
+                .query_row(
+                    "SELECT blocked FROM session_restore_policy WHERE singleton=1",
+                    [],
+                    |row| row.get::<_, bool>(0),
+                )
+                .optional()
+                .map_err(std::io::Error::other)?;
+            Ok(())
+        })
+        .map_err(|error| SyncError::InvalidState(format!("initialize sync database: {error}")))?;
+        self.schema_ready
+            .store(true, std::sync::atomic::Ordering::Release);
+        Ok(())
+    }
+
     pub(super) fn open(&self) -> Result<Connection, SyncError> {
+        // Early Cloud UI/API requests initialize on demand; the local shell
+        // never waits for this database or the operating-system credential store.
+        if !self.schema_ready.load(std::sync::atomic::Ordering::Acquire) {
+            let _guard = self.schema_lock.lock().unwrap_or_else(|p| p.into_inner());
+            if !self.schema_ready.load(std::sync::atomic::Ordering::Acquire) {
+                self.initialize_schema_locked()?;
+            }
+        }
+        self.open_raw()
+    }
+
+    fn open_raw(&self) -> Result<Connection, SyncError> {
         if let Some(parent) = self.path.parent() {
             std::fs::create_dir_all(parent).map_err(|error| {
                 SyncError::InvalidState(format!("create sync directory: {error}"))
@@ -24,7 +67,40 @@ impl SyncStore {
             PRAGMA foreign_keys = ON;
             "#,
         )?;
-        Self::initialize_v2_schema(&connection)?;
         Ok(connection)
     }
 }
+
+#[cfg(test)]
+mod storage_rebuild_tests {
+    use super::*;
+
+    #[test]
+    fn deferred_store_initializes_on_first_use_and_coalesces_concurrent_readers() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("cloud/sync.db");
+        let store = SyncStore::new_uninitialized(&path);
+        assert!(!path.exists());
+        let handles: Vec<_> = (0..4)
+            .map(|_| {
+                let store = store.clone();
+                std::thread::spawn(move || store.session_restore_blocked().unwrap())
+            })
+            .collect();
+        for handle in handles {
+            assert!(!handle.join().unwrap());
+        }
+        assert!(path.is_file());
+        assert!(!path.parent().unwrap().join("rebuild-backups").exists());
+    }
+
+    #[test]
+    fn invalid_sync_database_is_backed_up_and_recreated() {
+        let temp = tempfile::tempdir().unwrap();
+        let path = temp.path().join("sync.db");
+        std::fs::write(&path, b"invalid sync database").unwrap();
+        let store = SyncStore::new(&path).unwrap();
+        assert!(!store.session_restore_blocked().unwrap());
+        assert!(temp.path().join("rebuild-backups").exists());
+    }
+}
diff --git a/app/flowix-sync/src/store/v2_tests.rs b/app/flowix-sync/src/store/v2_tests.rs
index 2abbdf8d0..4deae3a51 100644
--- a/app/flowix-sync/src/store/v2_tests.rs
+++ b/app/flowix-sync/src/store/v2_tests.rs
@@ -14,7 +14,6 @@ fn v2_state_uses_one_account_cursor_and_same_notebook_id() {
             id: "usr_1".into(),
             email: "user@example.com".into(),
             display_name: "User".into(),
-            system_role: "user".into(),
         },
         protocol_epoch: PROTOCOL_EPOCH,
     };
@@ -419,7 +418,6 @@ fn switching_users_clears_user_scoped_sync_state() {
             id: id.into(),
             email: format!("{id}@example.com"),
             display_name: id.into(),
-            system_role: "user".into(),
         },
         protocol_epoch: PROTOCOL_EPOCH,
     };
@@ -443,7 +441,6 @@ fn clearing_account_removes_user_scoped_sync_state() {
                 id: "usr_a".into(),
                 email: "a@example.com".into(),
                 display_name: "A".into(),
-                system_role: "user".into(),
             },
             protocol_epoch: PROTOCOL_EPOCH,
         })
diff --git a/app/flowix-web/app/agent-window-effects.test.ts b/app/flowix-web/app/agent-window-effects.test.ts
index a88c55d2a..bbf39e667 100644
--- a/app/flowix-web/app/agent-window-effects.test.ts
+++ b/app/flowix-web/app/agent-window-effects.test.ts
@@ -3,11 +3,17 @@ import { createRoot } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
+  waitForStartupReady: vi.fn(async (): Promise<void> => undefined),
+  waitForWorkspaceRestoration: vi.fn(async (): Promise<void> => undefined),
   useAgentEvents: vi.fn(),
   refreshRuntime: vi.fn(async () => undefined),
-  loadAccess: vi.fn(async () => undefined),
-  listenAccess: vi.fn(),
-  unlistenAccess: vi.fn(),
+  refreshCloudPiModelProviderAtStartup: vi.fn(async () => true),
+  refreshAgentModelCatalog: vi.fn(async () => ({ items: [] })),
+  loadWorkspace: vi.fn(async (): Promise<void> => undefined),
+  initializePiMode: vi.fn(async () => undefined),
+  initializeLegacyPreferences: vi.fn(async () => undefined),
+  listenWorkspace: vi.fn(),
+  unlistenWorkspace: vi.fn(),
   invalidateNotebookCache: vi.fn(),
   prewarmNotebookCache: vi.fn(async () => undefined),
   invalidateMentionNotes: vi.fn(),
@@ -16,6 +22,13 @@ const mocks = vi.hoisted(() => ({
   releaseMemoEventBridge: vi.fn(),
 }));
 
+vi.mock('./main-window-startup', () => ({ waitForWorkspaceRestoration: mocks.waitForWorkspaceRestoration }));
+vi.mock('@features/agent/services/agent-catalog-service', () => ({
+  prefetchAvailableAgentModels: vi.fn(),
+  prefetchNotebookSkills: vi.fn(),
+  refreshAgentModelCatalog: mocks.refreshAgentModelCatalog,
+}));
+vi.mock('@features/memo/store/note-store', () => ({ useNoteStore: (selector: (state: { selectedNotebook: null }) => unknown) => selector({ selectedNotebook: null }) }));
 vi.mock('@features/agent/hooks/use-agent-events', () => ({
   useAgentEvents: mocks.useAgentEvents,
 }));
@@ -24,9 +37,17 @@ vi.mock('@features/agent/store/agent-runtime-store', () => ({
     selector({ refresh: mocks.refreshRuntime })
   ),
 }));
-vi.mock('@features/agent/store/agent-access-store', () => ({
-  useAgentAccessStore: (selector: (state: { loadInitial: typeof mocks.loadAccess }) => unknown) => (
-    selector({ loadInitial: mocks.loadAccess })
+vi.mock('@features/agent/store/agent-data-store', () => ({
+  ensureAgentPreferencesReady: async () => {
+    await Promise.all([mocks.initializePiMode(), mocks.initializeLegacyPreferences()]);
+  },
+  useAgentDataStore: (selector: (state: { initializePiMode: typeof mocks.initializePiMode; initializeLegacyPreferences: typeof mocks.initializeLegacyPreferences }) => unknown) => (
+    selector({ initializePiMode: mocks.initializePiMode, initializeLegacyPreferences: mocks.initializeLegacyPreferences })
+  ),
+}));
+vi.mock('@features/agent/store/agent-workspace-store', () => ({
+  useAgentWorkspaceStore: (selector: (state: { workspaceActions: { loadInitial: typeof mocks.loadWorkspace } }) => unknown) => (
+    selector({ workspaceActions: { loadInitial: mocks.loadWorkspace } })
   ),
 }));
 vi.mock('@features/editor/extensions/note-link', () => ({
@@ -40,7 +61,9 @@ vi.mock('@features/editor/extensions/tag-mention', () => ({
   invalidateMentionTags: mocks.invalidateMentionTags,
 }));
 vi.mock('@platform/tauri/client', () => ({
-  listenToAgentAccessChanges: mocks.listenAccess,
+  boot: { waitForStartupReady: mocks.waitForStartupReady },
+  cloud: { refreshPiModelProviderAtStartup: mocks.refreshCloudPiModelProviderAtStartup },
+  listenToAgentWorkspaceChanges: mocks.listenWorkspace,
 }));
 vi.mock('@/lib/memo-dispatcher', () => ({
   acquireMemoEventBridge: () => {
@@ -50,68 +73,163 @@ vi.mock('@/lib/memo-dispatcher', () => ({
 }));
 
 import { AgentWindowEffects } from './agent-window-effects';
-import { useAgentAccessWindowSync } from './use-agent-access-window-sync';
+import { useAgentWorkspaceWindowLifecycle } from './use-agent-workspace-window-lifecycle';
+import { admitStartupStage3 } from '@/lib/startup-stage3';
 
-function PreferencesAccessSync() {
-  useAgentAccessWindowSync();
+function PreferencesWorkspaceLifecycle() {
+  useAgentWorkspaceWindowLifecycle();
   return null;
 }
 
 describe('AgentWindowEffects', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mocks.listenAccess.mockReturnValue(mocks.unlistenAccess);
+    mocks.listenWorkspace.mockReturnValue(mocks.unlistenWorkspace);
   });
 
   afterEach(() => {
     document.body.replaceChildren();
   });
 
-  it('loads and synchronizes access preferences without mounting the Agent runtime', async () => {
+  it('loads preferences window Agent data without mounting the Agent runtime', async () => {
     const container = document.createElement('div');
     document.body.appendChild(container);
     const root = createRoot(container);
 
-    await act(async () => root.render(createElement(PreferencesAccessSync)));
+    await act(async () => root.render(createElement(PreferencesWorkspaceLifecycle)));
 
-    expect(mocks.loadAccess).toHaveBeenCalledOnce();
-    expect(mocks.listenAccess).toHaveBeenCalledOnce();
+    expect(mocks.loadWorkspace).toHaveBeenCalledOnce();
+    expect(mocks.initializePiMode).toHaveBeenCalledOnce();
+    expect(mocks.initializeLegacyPreferences).toHaveBeenCalledOnce();
+    expect(mocks.listenWorkspace).toHaveBeenCalledOnce();
     expect(mocks.refreshRuntime).not.toHaveBeenCalled();
     expect(mocks.useAgentEvents).not.toHaveBeenCalled();
     expect(mocks.prewarmNotebookCache).not.toHaveBeenCalled();
 
-    await act(async () => mocks.listenAccess.mock.calls[0][0]());
-    expect(mocks.loadAccess).toHaveBeenCalledTimes(2);
+    await act(async () => mocks.listenWorkspace.mock.calls[0][0]());
+    expect(mocks.loadWorkspace).toHaveBeenCalledTimes(2);
 
-    const { onListenerReady } = mocks.listenAccess.mock.calls[0][1];
+    const { onListenerReady } = mocks.listenWorkspace.mock.calls[0][1];
     await act(async () => onListenerReady());
-    expect(mocks.loadAccess).toHaveBeenCalledTimes(3);
+    expect(mocks.loadWorkspace).toHaveBeenCalledTimes(3);
     // Reconcile again if the native listener reconnects after a failure.
     await act(async () => onListenerReady());
-    expect(mocks.loadAccess).toHaveBeenCalledTimes(4);
+    expect(mocks.loadWorkspace).toHaveBeenCalledTimes(4);
 
     await act(async () => root.unmount());
-    expect(mocks.unlistenAccess).toHaveBeenCalledOnce();
+    expect(mocks.unlistenWorkspace).toHaveBeenCalledOnce();
+  });
+
+  it('waits for native startup before reading workspace data', async () => {
+    Object.defineProperty(window, '__TAURI_INTERNALS__', { value: {}, configurable: true });
+    let ready!: () => void;
+    mocks.waitForStartupReady.mockImplementationOnce(() => new Promise<void>((resolve) => { ready = resolve; }));
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    try {
+      await act(async () => root.render(createElement(PreferencesWorkspaceLifecycle)));
+      expect(mocks.loadWorkspace).not.toHaveBeenCalled();
+      expect(mocks.initializePiMode).not.toHaveBeenCalled();
+      expect(mocks.listenWorkspace).not.toHaveBeenCalled();
+      await act(async () => ready());
+      expect(mocks.loadWorkspace).toHaveBeenCalledOnce();
+    } finally {
+      await act(async () => root.unmount());
+      Reflect.deleteProperty(window, '__TAURI_INTERNALS__');
+    }
+  });
+
+  it('does not read workspace data when native initialization fails', async () => {
+    Object.defineProperty(window, '__TAURI_INTERNALS__', { value: {}, configurable: true });
+    mocks.waitForStartupReady.mockRejectedValueOnce(new Error('migration failed'));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const root = createRoot(document.createElement('div'));
+    try {
+      await act(async () => root.render(createElement(PreferencesWorkspaceLifecycle)));
+      expect(mocks.loadWorkspace).not.toHaveBeenCalled();
+      expect(mocks.initializePiMode).not.toHaveBeenCalled();
+      expect(mocks.listenWorkspace).not.toHaveBeenCalled();
+    } finally {
+      await act(async () => root.unmount());
+      warn.mockRestore();
+      Reflect.deleteProperty(window, '__TAURI_INTERNALS__');
+    }
   });
 
   it('owns the shared Agent lifecycle for a content-capable Webview', async () => {
+    function MainWorkspaceSync({ revision }: { revision: string }) {
+      useAgentWorkspaceWindowLifecycle({ deferUntilStage3: true });
+      return createElement('span', { 'data-revision': revision });
+    }
     const container = document.createElement('div');
     document.body.appendChild(container);
     const root = createRoot(container);
+    let finishSnapshot!: () => void;
+    mocks.loadWorkspace.mockImplementationOnce(() => new Promise<void>((resolve) => { finishSnapshot = resolve; }));
 
     await act(async () => {
-      root.render(createElement(AgentWindowEffects));
+      root.render(createElement('div', null,
+        createElement(MainWorkspaceSync, { key: 'initial', revision: 'initial' }),
+        createElement(AgentWindowEffects),
+      ));
     });
 
+    expect(mocks.listenWorkspace).toHaveBeenCalledTimes(2);
+    await act(async () => mocks.listenWorkspace.mock.calls[0][0]());
+    expect(mocks.loadWorkspace).not.toHaveBeenCalled();
+    expect(mocks.initializePiMode).not.toHaveBeenCalled();
+    expect(mocks.initializeLegacyPreferences).not.toHaveBeenCalled();
     expect(mocks.useAgentEvents).toHaveBeenCalledOnce();
     expect(mocks.acquireMemoEventBridge).toHaveBeenCalledOnce();
+    expect(mocks.refreshRuntime).not.toHaveBeenCalled();
+    expect(mocks.loadWorkspace).not.toHaveBeenCalled();
+    expect(mocks.listenWorkspace).toHaveBeenCalledTimes(2);
+    expect(mocks.prewarmNotebookCache).not.toHaveBeenCalled();
+    expect(mocks.refreshCloudPiModelProviderAtStartup).not.toHaveBeenCalled();
+
+    let finishWorkspaceRestoration!: () => void;
+    mocks.waitForWorkspaceRestoration.mockImplementationOnce(() => new Promise<void>((resolve) => {
+      finishWorkspaceRestoration = resolve;
+    }));
+    await act(async () => admitStartupStage3());
+    expect(mocks.loadWorkspace).toHaveBeenCalledOnce();
+    expect(mocks.initializePiMode).toHaveBeenCalledOnce();
+    expect(mocks.initializeLegacyPreferences).toHaveBeenCalledOnce();
     expect(mocks.refreshRuntime).toHaveBeenCalledWith({ force: true });
-    expect(mocks.loadAccess).not.toHaveBeenCalled();
-    expect(mocks.listenAccess).toHaveBeenCalledOnce();
     expect(mocks.prewarmNotebookCache).toHaveBeenCalledOnce();
+    expect(mocks.waitForWorkspaceRestoration).toHaveBeenCalledOnce();
+    expect(mocks.refreshCloudPiModelProviderAtStartup).not.toHaveBeenCalled();
+
+    await act(async () => root.render(createElement('div', null,
+      createElement(MainWorkspaceSync, { key: 'during', revision: 'during' }),
+      createElement(AgentWindowEffects),
+    )));
+    expect(mocks.loadWorkspace).toHaveBeenCalledOnce();
+    await act(async () => mocks.listenWorkspace.mock.calls[2][0]());
+    expect(mocks.loadWorkspace).toHaveBeenCalledOnce();
+
+    await act(async () => finishWorkspaceRestoration());
+    expect(mocks.refreshCloudPiModelProviderAtStartup).toHaveBeenCalledOnce();
+    expect(mocks.refreshAgentModelCatalog).toHaveBeenCalledWith('pi');
+
+    await act(async () => finishSnapshot());
+    expect(mocks.loadWorkspace).toHaveBeenCalledTimes(2);
+
+    mocks.listenWorkspace.mockImplementationOnce((_reload, { onListenerReady }) => {
+      onListenerReady();
+      return mocks.unlistenWorkspace;
+    });
+    await act(async () => root.render(createElement('div', null,
+      createElement(MainWorkspaceSync, { key: 'after', revision: 'after' }),
+      createElement(AgentWindowEffects),
+    )));
+    expect(mocks.loadWorkspace).toHaveBeenCalledTimes(3);
+    await act(async () => mocks.listenWorkspace.mock.calls[mocks.listenWorkspace.mock.calls.length - 1][0]());
+    expect(mocks.loadWorkspace).toHaveBeenCalledTimes(4);
 
     await act(async () => root.unmount());
-    expect(mocks.unlistenAccess).toHaveBeenCalledOnce();
+    expect(mocks.unlistenWorkspace).toHaveBeenCalledTimes(4);
     expect(mocks.releaseMemoEventBridge).toHaveBeenCalledOnce();
   });
 });
diff --git a/app/flowix-web/app/agent-window-effects.tsx b/app/flowix-web/app/agent-window-effects.tsx
index 9c01b9a7f..41e606701 100644
--- a/app/flowix-web/app/agent-window-effects.tsx
+++ b/app/flowix-web/app/agent-window-effects.tsx
@@ -6,8 +6,11 @@ import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store'
 import { invalidateNotebookCache, prewarmNotebookCache } from '@features/editor/extensions/note-link';
 import { invalidateMentionNotes } from '@features/editor/extensions/note-mention';
 import { invalidateMentionTags } from '@features/editor/extensions/tag-mention';
-import { listenToAgentAccessChanges } from '@platform/tauri/client';
+import { cloud, listenToAgentWorkspaceChanges } from '@platform/tauri/client';
+import { refreshAgentModelCatalog } from '@features/agent/services/agent-catalog-service';
 import { acquireMemoEventBridge } from '@/lib/memo-dispatcher';
+import { runStartupStage3Task } from '@/lib/startup-stage3';
+import { waitForWorkspaceRestoration } from './main-window-startup';
 
 /**
  * Agent infrastructure shared by every content-capable Webview.
@@ -17,15 +20,33 @@ import { acquireMemoEventBridge } from '@/lib/memo-dispatcher';
  * infrastructure; preferences intentionally does not mount this component.
  */
 export function AgentWindowEffects() {
-  useAgentEvents();
+  useAgentEvents(waitForWorkspaceRestoration);
   useEffect(() => acquireMemoEventBridge(), []);
   const refreshAgentRuntime = useAgentRuntimeStore((state) => state.refresh);
   useEffect(() => {
-    void refreshAgentRuntime({ force: true });
+    void runStartupStage3Task('agent-runtime-status-refresh', () => {
+      // The native status command owns the CLI-discovery dependency for every
+      // consumer, including refreshes initiated by feature-specific views.
+      return refreshAgentRuntime({ force: true });
+    });
   }, [refreshAgentRuntime]);
 
   useEffect(() => {
-    return listenToAgentAccessChanges(() => {
+    void runStartupStage3Task('pi-cloud-model-catalog-refresh', async () => {
+      // Stage 3 releases low-priority work after the shell paints, while the
+      // selected workspace may still be restoring its initial surface.
+      await waitForWorkspaceRestoration();
+      const connected = await cloud.refreshPiModelProviderAtStartup();
+      if (connected) await refreshAgentModelCatalog('pi');
+    });
+  }, []);
+
+  useEffect(() => {
+    void runStartupStage3Task('agent-note-link-cache-prewarm', prewarmNotebookCache);
+  }, []);
+
+  useEffect(() => {
+    return listenToAgentWorkspaceChanges(() => {
       invalidateNotebookCache();
       invalidateMentionNotes();
       invalidateMentionTags();
@@ -33,9 +54,5 @@ export function AgentWindowEffects() {
     });
   }, []);
 
-  useEffect(() => {
-    void prewarmNotebookCache();
-  }, []);
-
   return null;
 }
diff --git a/app/flowix-web/app/app.tsx b/app/flowix-web/app/app.tsx
index 5f6abd94f..6b199d373 100644
--- a/app/flowix-web/app/app.tsx
+++ b/app/flowix-web/app/app.tsx
@@ -1,28 +1,38 @@
 'use client';
 
-import { lazy, Suspense, useEffect, useState } from "react";
+import { lazy, Suspense, useEffect, useRef, useState } from "react";
+import { CenteredLoadingSpinner } from "@shared/ui/centered-loading-spinner";
+import { useWorkspaceStartupStore, applyNativeStartupStatus } from "@/lib/store/workspace-startup-store";
 import { ErrorBoundary } from "@shared/error-boundary";
-import { Toaster } from "sonner";
+import { Toaster, toast } from "sonner";
 import { useAppPreferencesViewModel } from "@features/preferences/public/app-api";
 import { useAppAgentRuntimeViewModel } from "@features/agent/public/app-api";
 import { useApplyFontSettings } from "@features/preferences/public/app-api";
 import { ThemeProvider } from "@features/theme";
 import { NativeEditMenuBridge, ShortcutsProvider } from "@features/shortcuts";
-import { I18nProvider } from "@/lib/i18n";
+import { I18nProvider, useI18n, type I18nKey } from "@/lib/i18n";
 import { TooltipProvider } from "@shared/ui/tooltip";
 import "@features/shortcuts/actions";
-import { listenToUserConfigChanges, windows } from "@platform/tauri/client";
+import { boot, listenToUserConfigChanges, windows } from "@platform/tauri/client";
 import { syncUserConfigChange } from "./user-config-sync";
-import { useAgentAccessWindowSync } from "./use-agent-access-window-sync";
+import { useAgentWorkspaceWindowLifecycle } from "./use-agent-workspace-window-lifecycle";
 import { invalidateDshModelConfigs } from "@features/agent/public/app-api";
 import { createLogger } from "@/lib/logger";
 import { ActionableNoticeHost } from "@features/notifications/actionable-notice-host";
+import { NotebookSetupNoticeHost } from "@features/memo/components/notebook-setup-notice-host";
+import { NotebookSetupCoordinator } from "@features/memo/components/notebook-setup-coordinator";
+import { useAgentPersistenceError } from "@features/agent/public/app-api";
+import { translate, type AppLanguage } from "@/lib/i18n";
 
 const DocumentSaveNotifications = lazy(() => import('@features/document/public/app-api')
   .then(module => ({ default: module.DocumentSaveNotifications })));
 
 const logger = createLogger("app");
 
+function removeAppLoading() {
+  document.getElementById("app-loading")?.remove();
+}
+
 const MainWindow = lazy(() =>
   import("./main-window/main-window")
     .then((module) => ({ default: module.MainWindow }))
@@ -47,7 +57,93 @@ const AgentWindowEffects = lazy(() =>
   import("./agent-window-effects").then((module) => ({ default: module.AgentWindowEffects }))
 );
 
-function AppToaster() {
+function isTauriRuntime(): boolean {
+  return typeof window !== 'undefined'
+    && ('__TAURI_INTERNALS__' in window || '__TAURI__' in window);
+}
+
+const startupProgressLabels: Record<string, I18nKey> = {
+  prepareDatabasePaths: 'startup.progress.prepareDatabasePaths',
+  prepareThreadDatabase: 'startup.progress.prepareThreadDatabase',
+  prepareSyncDatabase: 'startup.progress.prepareSyncDatabase',
+  prepareNotebookRegistry: 'startup.progress.prepareNotebookRegistry',
+  runMigrations: 'startup.progress.runMigrations',
+  config_dsh_layout_v2: 'startup.progress.migrateAgentLayout',
+  config_local_migrations_v1: 'startup.progress.migrateLocalConfiguration',
+  config_watcher_exclusions_v1: 'startup.progress.migrateWatcherSettings',
+  templates_v1: 'startup.progress.prepareTemplates',
+  prepareRuntimeStorage: 'startup.progress.prepareRuntimeStorage',
+  activateRuntime: 'startup.progress.activateRuntime',
+  completeInitialization: 'startup.progress.completeInitialization',
+};
+
+function startupProgressLabel(task: string): I18nKey {
+  if (task.startsWith('deferred:')) return 'startup.progress.deferredNotebookJobs';
+  if (task.includes(':notebook:')) return 'startup.progress.migrateNotebookStorage';
+  return startupProgressLabels[task] ?? 'startup.progress.runMigrations';
+}
+
+function StartupLoadingOverlay() {
+  const nativePhase = useWorkspaceStartupStore((state) => state.nativePhase);
+  const nativeStage = useWorkspaceStartupStore((state) => state.nativeStage);
+  const nativeStep = useWorkspaceStartupStore((state) => state.nativeStep);
+  const nativeProgress = useWorkspaceStartupStore((state) => state.nativeProgress);
+  const workspaceStatus = useWorkspaceStartupStore((state) => state.status);
+  const workbenchMounted = useWorkspaceStartupStore((state) => state.workbenchMounted);
+  const { t } = useI18n();
+  const visible = nativePhase === 'pending' || nativePhase === 'running'
+    || (nativePhase === 'ready' && (
+      workspaceStatus === 'idle'
+      || workspaceStatus === 'running'
+      || (workspaceStatus === 'ready' && !workbenchMounted)
+    ));
+  if (!visible) return null;
+  return (
+    <div className="fixed inset-0 z-[2147483646] flex items-center justify-center bg-[var(--frame-bg)]">
+      {nativePhase === 'running' && nativeStage === 'initialization' && nativeProgress ? (
+        <div className="flex w-72 flex-col items-center gap-3 text-sm text-[var(--muted-foreground)]">
+          <CenteredLoadingSpinner label={t('memo.navigation.preparingVersion')} />
+          <div className="h-1.5 w-full overflow-hidden rounded-full bg-[var(--muted)]" role="progressbar"
+            aria-label={t('memo.navigation.preparingVersion')}
+            aria-valuemin={0} aria-valuemax={100} aria-valuenow={nativeProgress.percent}>
+            <div className="h-full rounded-full bg-[var(--brand)] transition-[width] duration-300 ease-out"
+              style={{ width: `${nativeProgress.percent}%` }} />
+          </div>
+          <span className="text-xs">
+            {t(startupProgressLabel(nativeProgress.task))}
+            {(!['prepareDatabasePaths', 'prepareThreadDatabase', 'prepareSyncDatabase', 'prepareNotebookRegistry',
+              'prepareRuntimeStorage', 'activateRuntime', 'completeInitialization'].includes(nativeProgress.task))
+              ? ` (${nativeProgress.completed}/${nativeProgress.total})`
+              : ''}
+          </span>
+        </div>
+      ) : (
+        <CenteredLoadingSpinner
+          label={nativePhase === 'running'
+            && nativeStage === 'initialization'
+            && nativeStep === 'versionInitialization'
+            ? t('memo.navigation.preparingVersion')
+            : undefined}
+        />
+      )}
+    </div>
+  );
+}
+
+function AppToaster({ language }: { language: AppLanguage }) {
+  const persistenceError = useAgentPersistenceError();
+  const lastPersistenceError = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!persistenceError) {
+      lastPersistenceError.current = null;
+      return;
+    }
+    if (lastPersistenceError.current === persistenceError) return;
+    lastPersistenceError.current = persistenceError;
+    toast.error(translate(language, "preferences.agents.cacheWriteFailed"));
+  }, [language, persistenceError]);
+
   return (
     <>
     <Toaster
@@ -57,15 +153,13 @@ function AppToaster() {
       closeButton={false}
     />
     <Suspense fallback={null}><DocumentSaveNotifications /></Suspense>
+    <NotebookSetupCoordinator />
+    <NotebookSetupNoticeHost />
     <ActionableNoticeHost />
     </>
   );
 }
 
-function removeAppLoading() {
-  document.getElementById("app-loading")?.remove();
-}
-
 function AppReadySignal() {
   useEffect(() => {
     removeAppLoading();
@@ -112,8 +206,8 @@ function useUnexpectedControlInputGuard() {
 
 function App() {
   useUnexpectedControlInputGuard();
-  useAgentAccessWindowSync();
   const [hash, setHash] = useState(() => window.location.hash);
+  useAgentWorkspaceWindowLifecycle({ deferUntilStage3: !hash.startsWith('#preferences') });
   const {
     language,
     format,
@@ -124,6 +218,62 @@ function App() {
   const { refreshAgentRuntime } = useAppAgentRuntimeViewModel();
   useApplyFontSettings(format);
 
+  useEffect(() => {
+    const setNativeReady = () => useWorkspaceStartupStore.setState((state) => (
+      state.nativePhase === 'ready'
+        && state.nativeStage === 'workspacePreparation'
+        && state.nativeStep === 'ready'
+        && state.nativeError === null
+        && state.nativeProgress === null
+        ? state
+        : { ...state, nativePhase: 'ready', nativeStage: 'workspacePreparation', nativeStep: 'ready', nativeError: null, nativeProgress: null }
+    ));
+    if (hash.startsWith("#preferences") || !isTauriRuntime()) {
+      setNativeReady();
+      return;
+    }
+    let active = true;
+    let inFlight = false;
+    let timer: number | undefined;
+    const refresh = async () => {
+      if (inFlight) return;
+      inFlight = true;
+      try {
+        const status = await boot.getStartupStatus();
+        if (!active) return;
+        applyNativeStartupStatus(status);
+        if (status.phase === 'ready' || status.phase === 'failed') {
+          if (timer !== undefined) window.clearInterval(timer);
+          timer = undefined;
+        }
+      } catch {
+        if (active) setNativeReady();
+        if (timer !== undefined) window.clearInterval(timer);
+        timer = undefined;
+      } finally { inFlight = false; }
+    };
+    void refresh();
+    timer = window.setInterval(() => void refresh(), 250);
+    return () => {
+      active = false;
+      if (timer !== undefined) window.clearInterval(timer);
+    };
+  }, [hash]);
+
+  useEffect(() => {
+    const root = document.documentElement;
+    const handleFocus = () => { root.dataset.windowFocused = "true"; };
+    const handleBlur = () => { root.dataset.windowFocused = "false"; };
+    root.dataset.windowFocused = String(document.hasFocus());
+    window.addEventListener("focus", handleFocus);
+    window.addEventListener("blur", handleBlur);
+    return () => {
+      window.removeEventListener("focus", handleFocus);
+      window.removeEventListener("blur", handleBlur);
+      delete root.dataset.windowFocused;
+    };
+  }, []);
+
   useEffect(() => {
     void windows.applyMenuLanguage(language).catch((error) => {
       logger.error("apply native menu language failed", { error });
@@ -176,8 +326,8 @@ function App() {
     const tab = hash.split("/")[1] || undefined;
     return (
       <ErrorBoundary language={language}>
-        <AppToaster />
         <I18nProvider language={language}>
+          <AppToaster language={language} />
           <ThemeProvider>
             <TooltipProvider>
               <ShortcutsProvider overrides={shortcutOverrides}>
@@ -196,9 +346,10 @@ function App() {
 
   return (
     <ErrorBoundary language={language}>
-      <AppToaster />
       <I18nProvider language={language}>
+        <AppToaster language={language} />
         <ThemeProvider>
+          <StartupLoadingOverlay />
           <Suspense fallback={null}>
             <AgentWindowEffects />
           </Suspense>
@@ -208,6 +359,7 @@ function App() {
           <TooltipProvider>
             <ShortcutsProvider overrides={shortcutOverrides}>
               <NativeEditMenuBridge />
+              {/* The root startup overlay stays mounted while this code loads. */}
               <Suspense fallback={null}>
                 <MainWindow />
                 <MainWindowReadySignal />
diff --git a/app/flowix-web/app/desktop-shutdown.test.ts b/app/flowix-web/app/desktop-shutdown.test.ts
new file mode 100644
index 000000000..b7b33afe0
--- /dev/null
+++ b/app/flowix-web/app/desktop-shutdown.test.ts
@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({ surfaces: vi.fn(), preferences: vi.fn(), flush: vi.fn(), diagnostics: vi.fn(), invoke: vi.fn(), subscribe: vi.fn() }));
+vi.mock('@platform/tauri/core', () => ({ invoke: mocks.invoke }));
+vi.mock('@platform/tauri/event-bus', () => ({ subscribe: mocks.subscribe }));
+vi.mock('@platform/tauri/runtime', () => ({ isTauriDesktopRuntime: () => true }));
+vi.mock('@features/document/public/shutdown-api', () => ({ flushDocumentsForShutdown: mocks.flush, documentShutdownDiagnostics: mocks.diagnostics }));
+vi.mock('@features/workspace/public/shutdown-api', () => ({ flushWorkspaceSurfacesForShutdown: mocks.surfaces }));
+vi.mock('@features/preferences/public/shutdown-api', () => ({ flushPreferencesForShutdown: mocks.preferences }));
+async function tick() { for (let i = 0; i < 50; i++) await Promise.resolve(); }
+async function install() { const module = await import('./desktop-shutdown'); module.installDesktopShutdown(); await tick(); return module; }
+function emit(name: string, request: number) { mocks.subscribe.mock.calls.find(([event]) => event === name)![1](request); }
+describe('native-owned shutdown preparation', () => {
+  beforeEach(() => {
+    vi.resetModules(); Object.values(mocks).forEach(mock => mock.mockReset());
+    mocks.surfaces.mockResolvedValue(true); mocks.preferences.mockResolvedValue(undefined); mocks.flush.mockResolvedValue(true); mocks.invoke.mockResolvedValue(undefined);
+  });
+  afterEach(() => { vi.useRealTimers(); });
+  it('installs once without a JS native-close interceptor', async () => {
+    const module = await install(); module.installDesktopShutdown();
+    expect(mocks.subscribe).toHaveBeenCalledTimes(3);
+  });
+  it('reports persistence success and leaves destruction to Rust', async () => {
+    await install(); emit('document:prepare-close', 1); await tick();
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 1, ready: true });
+    expect(document.querySelector('dialog')).toBeNull();
+  });
+  it.each(['false', 'reject'])('still acknowledges close after save %s', async failure => {
+    if (failure === 'false') mocks.flush.mockResolvedValue(false);
+    else mocks.flush.mockRejectedValue(new Error('disk unavailable'));
+    await install(); emit('document:prepare-close', 2); await tick();
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 2, ready: false });
+    expect(document.querySelector('dialog')).toBeNull();
+  });
+  it('leaves a stuck save to the native deadline without starting a second timer', async () => {
+    vi.useFakeTimers(); mocks.flush.mockReturnValue(new Promise(() => {}));
+    await install(); emit('document:prepare-close', 3); await tick();
+    await vi.advanceTimersByTimeAsync(2_000);
+    expect(mocks.invoke).not.toHaveBeenCalledWith('finish_document_close', expect.anything());
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('global quit captures fresh inputs and ignores the superseded acknowledgement', async () => {
+    let finish!: (value: boolean) => void;
+    mocks.flush.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+    await install(); emit('document:prepare-close', 4); await tick();
+    emit('document:prepare-exit', 5); await tick(); finish(false); await tick();
+    expect(mocks.flush).toHaveBeenCalledTimes(2);
+    expect(mocks.invoke).not.toHaveBeenCalledWith('finish_document_close', expect.anything());
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_shutdown', { request: 5, ready: true });
+  });
+  it('restores interaction when the updater cancels', async () => {
+    await install(); emit('document:prepare-exit', 6); emit('document:exit-cancelled', 6); await tick();
+    expect(document.querySelector('dialog')).toBeNull();
+    expect(mocks.invoke).not.toHaveBeenCalledWith('finish_document_shutdown', expect.anything());
+  });
+  it('diagnostics failure cannot prevent persistence or acknowledgement', async () => {
+    mocks.diagnostics.mockImplementation(() => { throw new Error('diagnostics unavailable'); });
+    await install(); emit('document:prepare-close', 11); await tick();
+    expect(mocks.flush).toHaveBeenCalledTimes(1);
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 11, ready: true });
+  });
+  it('does not show a blocking notice while persistence is pending', async () => {
+    let finish!: (value: boolean) => void;
+    mocks.flush.mockImplementationOnce(() => new Promise<boolean>(resolve => { finish = resolve; }));
+    await install(); emit('document:prepare-close', 12); await tick();
+    expect(document.querySelector('dialog')).toBeNull();
+    expect(mocks.invoke).not.toHaveBeenCalledWith('finish_document_close', expect.anything());
+    finish(true); await tick();
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 12, ready: true });
+  });
+  it('closes immediately when all saves finish, without waiting one second', async () => {
+    vi.useFakeTimers();
+    await install(); emit('document:prepare-close', 8); await tick();
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 8, ready: true });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('starts preferences and documents together and waits for both', async () => {
+    let finish!: () => void;
+    mocks.preferences.mockImplementationOnce(() => new Promise<void>(resolve => { finish = resolve; }));
+    await install(); emit('document:prepare-close', 9); await tick();
+    expect(mocks.flush).toHaveBeenCalledTimes(1);
+    expect(mocks.preferences).toHaveBeenCalledTimes(1);
+    expect(mocks.invoke).not.toHaveBeenCalledWith('finish_document_close', expect.anything());
+    finish(); await tick();
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 9, ready: true });
+  });
+  it('preference failure cannot veto closing', async () => {
+    mocks.preferences.mockRejectedValueOnce(new Error('settings locked'));
+    await install(); emit('document:prepare-close', 10); await tick();
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 10, ready: false });
+  });
+
+  it('flushes fresh preferences and surfaces after updater cancellation', async () => {
+    let finish!: (value: boolean) => void;
+    mocks.flush.mockImplementationOnce(() => new Promise<boolean>(resolve => { finish = resolve; }));
+    await install(); emit('document:prepare-exit', 21); await tick();
+    emit('document:exit-cancelled', 21);
+    // The previous document write is still pending; new edits may now exist.
+    emit('document:prepare-close', 22); await tick();
+    expect(mocks.preferences).toHaveBeenCalledTimes(2);
+    expect(mocks.surfaces).toHaveBeenCalledTimes(2);
+    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_close', { request: 22, ready: true });
+    finish(true); await tick();
+    expect(mocks.invoke).not.toHaveBeenCalledWith('finish_document_shutdown', { request: 21, ready: true });
+  });
+
+});
diff --git a/app/flowix-web/app/desktop-shutdown.ts b/app/flowix-web/app/desktop-shutdown.ts
new file mode 100644
index 000000000..9fa74ea33
--- /dev/null
+++ b/app/flowix-web/app/desktop-shutdown.ts
@@ -0,0 +1,118 @@
+import { createLogger } from '@/lib/logger';
+import { invoke } from '@platform/tauri/core';
+import { subscribe } from '@platform/tauri/event-bus';
+import { isTauriDesktopRuntime } from '@platform/tauri/runtime';
+import { flushDocumentsForShutdown, documentShutdownDiagnostics } from '@features/document/public/shutdown-api';
+import { flushWorkspaceSurfacesForShutdown } from '@features/workspace/public/shutdown-api';
+import { flushPreferencesForShutdown } from '@features/preferences/public/shutdown-api';
+
+const log = createLogger('window:shutdown');
+let installed = false;
+
+type ShutdownKind = 'close' | 'exit';
+type ShutdownAttempt = {
+  request: number;
+  kind: ShutdownKind;
+};
+
+function safeDiagnostics(): object {
+  try {
+    return documentShutdownDiagnostics();
+  } catch {
+    return { unavailable: true };
+  }
+}
+
+function logFailure(level: 'warn' | 'error', message: string, detail?: unknown): void {
+  try {
+    const context = detail === undefined
+      ? undefined
+      : detail !== null && typeof detail === 'object' && !Array.isArray(detail)
+        ? detail as Readonly<Record<string, unknown>>
+        : { error: detail };
+    log[level](message, context);
+  } catch {
+    // Logging is diagnostic and must not become part of the close protocol.
+  }
+}
+
+/** This is a best-effort report, never permission to close. Rust owns deadlines. */
+async function prepare(): Promise<boolean> {
+  const started = Date.now();
+  try {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(flushDocumentsForShutdown),
+      Promise.resolve().then(flushPreferencesForShutdown),
+      Promise.resolve().then(flushWorkspaceSurfacesForShutdown),
+    ]);
+    const ready = results.every(result => result.status === 'fulfilled' && result.value !== false);
+    try {
+      log.info('prepare settled', { ready, elapsedMs: Date.now() - started, ...safeDiagnostics() });
+    } catch {
+      // A diagnostics or logger failure cannot veto the close acknowledgement.
+    }
+    return ready;
+  } catch (error) {
+    logFailure('warn', 'shutdown preparation failed', error);
+    return false;
+  }
+}
+
+async function acknowledge(attempt: ShutdownAttempt, ready: boolean): Promise<void> {
+  try {
+    await invoke(attempt.kind === 'close' ? 'finish_document_close' : 'finish_document_shutdown', {
+      request: attempt.request,
+      ready,
+    });
+  } catch (error) {
+    logFailure('warn', 'shutdown acknowledgement failed; native deadline remains active', {
+      request: attempt.request,
+      kind: attempt.kind,
+      error,
+    });
+  }
+}
+
+/** Install once. Native CloseRequested must never depend on a JS listener. */
+export function installDesktopShutdown(): void {
+  if (installed || !isTauriDesktopRuntime()) return;
+  installed = true;
+
+  let active: ShutdownAttempt | null = null;
+  const clear = () => { active = null; };
+
+  const begin = (request: number, kind: ShutdownKind) => {
+    if (active?.request === request && active.kind === kind) return;
+    clear();
+    const attempt: ShutdownAttempt = { request, kind };
+    active = attempt;
+
+    // Persistence is background work; native Rust owns the hard close deadline.
+    const preparation = prepare();
+
+    void preparation.then(async ready => {
+      if (active !== attempt) return;
+      await acknowledge(attempt, ready);
+    }).catch(async error => {
+      logFailure('error', 'shutdown preparation failed; reporting best-effort close', {
+        request,
+        kind,
+        error,
+      });
+      if (active === attempt) await acknowledge(attempt, false);
+    });
+  };
+
+  subscribe<number>('document:prepare-close', request => begin(request, 'close'));
+  subscribe<number>('document:exit-cancelled', request => {
+    // Only the updater can cancel. Ordinary user close/quit never emits this.
+    if (active?.kind === 'exit' && active.request === request) clear();
+  });
+  subscribe<number>('document:prepare-exit', request => begin(request, 'exit'), {
+    onListenerReady: () => {
+      void invoke('register_document_window').catch(error => {
+        logFailure('error', 'window registration failed', error);
+      });
+    },
+  });
+}
diff --git a/app/flowix-web/app/main-window-effects.tsx b/app/flowix-web/app/main-window-effects.tsx
index a3be01c45..59fccd4c9 100644
--- a/app/flowix-web/app/main-window-effects.tsx
+++ b/app/flowix-web/app/main-window-effects.tsx
@@ -1,11 +1,13 @@
 'use client';
 
 import { useEffect } from "react";
-import { subscribe } from '@platform/tauri/event-bus';
+import { subscribeNotebookChanges } from '@platform/tauri/notebook-change-events';
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { useI18n } from "@/lib/i18n";
 import { subscribeAppActiveAgentConversation } from "@features/document/public/app-api";
 import {
+  mountNotebookBackgroundUpdates,
+  mountMemoListRefreshService,
   applyAppMemoCreated,
   applyAppMemoDeleted,
   applyAppMemoUpdated,
@@ -32,23 +34,58 @@ import {
 import { initializeMainWindowStartup } from './main-window-startup';
 import { createLogger } from '@/lib/logger';
 import { joinNotebookMemoPath } from '@/lib/path';
+import { useUserSettingsStore } from '@features/preferences/store/user-settings-store';
 import { resumePendingNoteLinkUpdates } from '@features/memo/public/app-api';
-import { subscribeWorkspaceDocumentSaves } from '@features/document/public/workspace-api';
+import { subscribeWorkspaceDocumentSaves, rebaseStoredRecoveryDraftPaths } from '@features/document/public/workspace-api';
 import {
   syncAppAgentConversationRestore,
-  openBrowserColumnNotebookNote,
   removeBrowserColumnTabsByPath,
   applyNotebookPathMove,
 } from '@features/workspace/public/app-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { clearWorkspaceTargetForDeletedFile } from '@features/workspace/public/shell-api';
+import {
+  dismissNavigationFailure,
+  retryLastNavigation,
+  useWorkspaceNavigationFailure,
+} from '@features/workspace/public/main-window-api';
+import {
+  clearActionableNotice,
+  upsertActionableNotice,
+} from '@features/notifications/actionable-notice-store';
 
 const logger = createLogger('main-window-effects');
+const NAVIGATION_FAILURE_NOTICE_ID = 'workspace-navigation-failure';
 
 export function MainWindowEffects() {
   const { t } = useI18n();
   const mainWindowTitle = t("window.main.title");
+  const navigationFailure = useWorkspaceNavigationFailure();
+
+  useEffect(() => {
+    if (!navigationFailure) {
+      clearActionableNotice(NAVIGATION_FAILURE_NOTICE_ID);
+      return;
+    }
+    upsertActionableNotice({
+      id: NAVIGATION_FAILURE_NOTICE_ID,
+      priority: 100,
+      tone: 'error',
+      title: t('shell.navigation.failed'),
+      message: navigationFailure.message,
+      actions: [{ id: 'retry', label: t('error.retry'), run: retryLastNavigation }],
+      dismissible: true,
+      onDismiss: dismissNavigationFailure,
+      revision: navigationFailure.requestId,
+    });
+  }, [navigationFailure, t]);
+
+  useEffect(() => () => clearActionableNotice(NAVIGATION_FAILURE_NOTICE_ID), []);
+
+  useEffect(() => mountNotebookBackgroundUpdates(), []);
+  useEffect(() => mountMemoListRefreshService(), []);
 
   useEffect(() => {
-    resumePendingNoteLinkUpdates();
     return subscribeWorkspaceDocumentSaves(resumePendingNoteLinkUpdates);
   }, []);
 
@@ -82,27 +119,55 @@ export function MainWindowEffects() {
   }, [mainWindowTitle]);
 
   useEffect(() => {
-    let moveChain = Promise.resolve();
+    let pathChangeChain = Promise.resolve();
     let disposed = false;
-    const unsubscribe = subscribe<{ notebookId: string; relativePath: string; previousRelativePath?: string; directory?: boolean; deleted?: boolean }>(
-      'flowix:path-note-changed',
-      ({ notebookId, relativePath, previousRelativePath, directory, deleted }) => {
+    const unsubscribe = subscribeNotebookChanges(
+      (change) => {
+        const { notebookId } = change;
         invalidateMentionNotes();
         invalidateMentionTags();
         refreshAppPathNoteMetadata(notebookId);
-        if (previousRelativePath && relativePath && !deleted) {
-          moveChain = moveChain.then(async () => {
+        if (change.kind === 'resource-created'
+          && change.source === 'external_tool'
+          && change.relativePath.split('/').pop() !== 'AGENTS.md'
+          && useUserSettingsStore.getState().settings.autoOpenCreatedNotesInBrowser) {
+          const { relativePath } = change;
+          pathChangeChain = pathChangeChain.then(async () => {
+            if (disposed) return;
             const notebookPath = await getAppNotebookPath(notebookId);
-            if (!disposed && notebookPath) applyNotebookPathMove({
-              notebookId, notebookPath, previousRelativePath, relativePath,
-              directory: directory === true,
+            const path = notebookPath && joinNotebookMemoPath(notebookPath, relativePath);
+            if (disposed || !path || !notebookPath) return;
+            await openWorkspaceSurface({
+              host: 'browser-column',
+              target: { kind: 'external', path, scopePath: notebookPath, transitionId: null },
+              options: { notebookId },
             });
+          }).catch((error) => logger.warn('open externally created note failed', { error, notebookId, relativePath }));
+        }
+        if (change.kind === 'path-moved') {
+          const { previousRelativePath, relativePath, directory } = change;
+          pathChangeChain = pathChangeChain.then(async () => {
+            if (disposed) return;
+            const notebookPath = await getAppNotebookPath(notebookId);
+            if (!disposed && notebookPath) {
+              applyNotebookPathMove({ notebookId, notebookPath, previousRelativePath, relativePath, directory });
+              const previous = joinNotebookMemoPath(notebookPath, previousRelativePath);
+              const next = joinNotebookMemoPath(notebookPath, relativePath);
+              if (previous && next) await rebaseStoredRecoveryDraftPaths(previous, next, directory);
+            }
           }).catch((error) => logger.warn('rebase moved note path failed', { error, notebookId, relativePath }));
         }
-        if (deleted && relativePath) {
-          void getAppNotebookPath(notebookId).then((notebookPath) => {
+        if (change.kind === 'resource-deleted') {
+          const { relativePath } = change;
+          pathChangeChain = pathChangeChain.then(async () => {
+            if (disposed) return;
+            const notebookPath = await getAppNotebookPath(notebookId);
+            if (disposed) return;
             const path = notebookPath && joinNotebookMemoPath(notebookPath, relativePath);
-            if (path) removeBrowserColumnTabsByPath(path);
+            if (path) {
+              removeBrowserColumnTabsByPath(path);
+              await clearWorkspaceTargetForDeletedFile(path);
+            }
           }).catch((error) => logger.warn('resolve deleted note path failed', { error, notebookId, relativePath }));
         }
       },
@@ -137,7 +202,11 @@ export function MainWindowEffects() {
             const notebookPath = await getAppNotebookPath(notebookId);
             const path = notebookPath && joinNotebookMemoPath(notebookPath, relativePath);
             if (!path) throw new Error('Created note path is unavailable');
-            await openBrowserColumnNotebookNote(path, notebookId, notebookPath);
+            await openWorkspaceSurface({
+              host: 'browser-column',
+              target: { kind: 'external', path, scopePath: notebookPath, transitionId: null },
+              options: { notebookId },
+            });
           },
           reportOpenFailure: (error) => {
             logger.warn('open created note in browser column failed', { error });
@@ -147,6 +216,10 @@ export function MainWindowEffects() {
           handleMemoUpdated: applyAppMemoUpdated,
           handleMemoDeleted: applyAppMemoDeleted,
           removeBrowserColumnTabsByPath: (path) => removeBrowserColumnTabsByPath(path),
+          clearWorkspaceTargetByPath: (path) => {
+            void clearWorkspaceTargetForDeletedFile(path).catch((error) =>
+              logger.warn('clear deleted document target failed', { error, path }));
+          },
           handleTagsRenamed: applyAppTagsRenamed,
           handleTagsDeleted: applyAppTagsDeleted,
           refreshSelectedNotebookMetadata,
diff --git a/app/flowix-web/app/main-window-memo-event-handler.test.ts b/app/flowix-web/app/main-window-memo-event-handler.test.ts
index 767ea7a42..2476fa4af 100644
--- a/app/flowix-web/app/main-window-memo-event-handler.test.ts
+++ b/app/flowix-web/app/main-window-memo-event-handler.test.ts
@@ -8,7 +8,7 @@ import type { MemoEvent } from '@/types/memo';
 import type { MemoItem } from '@/types/memo-item';
 
 const memo: MemoItem = {
-  id: 'memo-b',
+  relativePath: 'Created.md',
   filename: 'Created.md',
   preview: '',
   tags: [],
@@ -135,7 +135,6 @@ describe('handleMainWindowMemoEvent', () => {
     const actions = createActions('notebook-b');
     const event: MemoEvent = {
       kind: 'updated',
-      id: memo.id,
       path: '/notebook-b/Renamed.md',
       memo: { ...memo, filename: 'Renamed.md' },
       notebookId: 'notebook-b',
diff --git a/app/flowix-web/app/main-window-memo-event-handler.ts b/app/flowix-web/app/main-window-memo-event-handler.ts
index 4fd60db14..f949c5909 100644
--- a/app/flowix-web/app/main-window-memo-event-handler.ts
+++ b/app/flowix-web/app/main-window-memo-event-handler.ts
@@ -11,6 +11,7 @@ export interface MainWindowMemoEventActions {
   handleMemoUpdated: (memo: MemoItem) => void;
   handleMemoDeleted: () => void;
   removeBrowserColumnTabsByPath: (path: string) => void;
+  clearWorkspaceTargetByPath?: (path: string) => void;
   handleTagsRenamed: (event: Extract<MemoEvent, { kind: 'tags_renamed' }>) => void;
   handleTagsDeleted: (event: Extract<MemoEvent, { kind: 'tags_deleted' }>) => void;
   refreshSelectedNotebookMetadata: (event: MemoEvent) => void;
@@ -20,10 +21,11 @@ export interface MainWindowMemoEventActions {
 /**
  * Route one memo event inside the main Webview.
  *
- * Externally created notes and notes created in a background notebook may
- * auto-open according to the user preference. Template notes skip that side
- * effect. List and tag metadata updates remain scoped to the selected
- * notebook, while notebook-keyed todo counts refresh in background.
+ * Legacy Memo events for externally created notes and notes created in a
+ * background notebook may auto-open according to the user preference.
+ * Path-first external creates are handled by the notebook path event instead.
+ * Template notes skip auto-open. List and tag metadata updates remain scoped
+ * to the selected notebook, while notebook-keyed todo counts refresh in background.
  *
  * `tags_renamed` / `tags_deleted` 都是 tag 子树操作的收口事件, 后端已经
  * 完成所有 affected memo 的 body 改写 + index 同步。 这里只走
@@ -58,6 +60,7 @@ export function handleMainWindowMemoEvent(
   // events, otherwise a later tab activation can resurrect the old filename.
   if (event.kind === 'deleted') {
     actions.removeBrowserColumnTabsByPath(event.path);
+    actions.clearWorkspaceTargetByPath?.(event.path);
   }
 
   const selectedNotebookId = actions.getSelectedNotebookId();
diff --git a/app/flowix-web/app/main-window-startup.test.ts b/app/flowix-web/app/main-window-startup.test.ts
index 5da92136b..b4cd6630c 100644
--- a/app/flowix-web/app/main-window-startup.test.ts
+++ b/app/flowix-web/app/main-window-startup.test.ts
@@ -1,122 +1,115 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { boot } from '@platform/tauri/client';
-import { useNoteStore } from '@features/memo/store/note-store';
-import { useDocumentStore } from '@features/document/store/document-store';
-import { waitForInitialDocumentLoad } from '@features/document/public/startup-api';
+import { useWorkspaceStartupStore } from '@/lib/store/workspace-startup-store';
+import { notifyWorkbenchMounted } from '@/lib/workbench-mount';
 
 const mocks = vi.hoisted(() => ({
-  initializeNoteLibrary: vi.fn(),
-  captureWorkspaceRestoreTarget: vi.fn(),
-  restoreExternalDocumentWorkspace: vi.fn(),
-  restoreMediaWorkspace: vi.fn(),
-  restoreTableWorkspace: vi.fn(),
-  restoreCollectionWorkspace: vi.fn(),
-  setWorkspaceRestoreStatus: vi.fn(),
-  restoreAgentConversationWorkspace: vi.fn(),
-  calls: [] as string[],
+  context: vi.fn(), markError: vi.fn(), resumeNoteLinks: vi.fn(), target: vi.fn(), restore: vi.fn(), restoreStatus: vi.fn(),
+  native: vi.fn(), notebook: vi.fn(), notify: vi.fn(), record: vi.fn(), revision: 0,
 }));
-
-vi.mock('@features/memo/public/app-api', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('@features/memo/public/app-api')>()),
-  initializeNotebookContext: mocks.initializeNoteLibrary,
+vi.mock('@platform/tauri/client', () => ({ boot: {
+  waitForStartupReady: mocks.native, getStartupNotebookId: mocks.notebook,
+  notifyStartupInteractive: mocks.notify, recordStartupStage: mocks.record,
+} }));
+vi.mock('@features/memo/public/app-api', () => ({
+  initializeNotebookContext: mocks.context,
+  markMemoLibraryStartupError: mocks.markError,
+  resumePendingNoteLinkUpdates: mocks.resumeNoteLinks,
 }));
 vi.mock('@features/workspace/public/startup-api', () => ({
-  captureWorkspaceRestoreTarget: mocks.captureWorkspaceRestoreTarget,
-  restoreExternalDocumentWorkspace: mocks.restoreExternalDocumentWorkspace,
-  restoreMediaWorkspace: mocks.restoreMediaWorkspace,
-  restoreTableWorkspace: mocks.restoreTableWorkspace,
-  restoreCollectionWorkspace: mocks.restoreCollectionWorkspace,
-  setWorkspaceRestoreStatus: mocks.setWorkspaceRestoreStatus,
-  restoreAgentConversationWorkspace: mocks.restoreAgentConversationWorkspace,
+  captureWorkspaceRestoreTarget: mocks.target, setWorkspaceRestoreStatus: mocks.restoreStatus,
+  restoreExternalDocumentWorkspace: mocks.restore, restoreMediaWorkspace: mocks.restore,
+  restoreTableWorkspace: mocks.restore, restoreCollectionWorkspace: mocks.restore,
+  restoreFolderCollectionWorkspace: mocks.restore, restoreLegacyFolderListWorkspace: mocks.restore,
+  restoreAgentConversationWorkspace: mocks.restore,
 }));
-
+vi.mock('@features/memo/public/workspace-api', () => ({
+  getWorkspaceMemoState: () => ({ notebooks: [{ id: 'notebook-a' }] }),
+}));
+vi.mock('@features/workspace/public/shell-api', () => ({ getWorkspaceNavigationRevision: () => mocks.revision }));
 import { initializeMainWindowStartup } from './main-window-startup';
 
-describe('initializeMainWindowStartup', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-    Reflect.deleteProperty(window, '__TAURI_INTERNALS__');
-    useNoteStore.getState().setStartupPhase('idle');
-    useDocumentStore.setState({ isDocumentTransitioning: false, documentTransitionId: 0 });
-    mocks.calls.length = 0;
-    mocks.initializeNoteLibrary.mockReset().mockImplementation(async () => {
-      mocks.calls.push('memo-library');
-    });
-    mocks.captureWorkspaceRestoreTarget.mockReset().mockReturnValue(null);
-    mocks.restoreExternalDocumentWorkspace.mockReset();
-    mocks.restoreMediaWorkspace.mockReset();
-    mocks.setWorkspaceRestoreStatus.mockReset();
-    mocks.restoreAgentConversationWorkspace.mockReset().mockImplementation(async () => {
-      mocks.calls.push('agent-workspace');
-    });
-  });
+beforeEach(() => {
+  vi.resetAllMocks();
+  Object.defineProperty(window, '__TAURI_INTERNALS__', { value: {}, configurable: true });
+  vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => { callback(0); return 1; });
+  useWorkspaceStartupStore.setState({ status: 'idle', task: null, error: null });
+  notifyWorkbenchMounted();
+  mocks.revision = 0;
+  mocks.native.mockResolvedValue(undefined); mocks.notebook.mockResolvedValue('notebook-a');
+  mocks.context.mockResolvedValue(undefined); mocks.notify.mockResolvedValue(undefined);
+  mocks.record.mockResolvedValue(undefined); mocks.target.mockReturnValue(null);
+  mocks.restore.mockResolvedValue(undefined);
+});
 
-  it('runs startup stages in dependency order', async () => {
+describe('workbench startup', () => {
+  it('resolves metadata before releasing the shell and starting content restoration', async () => {
+    const order: string[] = [];
+    mocks.context.mockImplementation(async () => { order.push('context'); });
+    mocks.target.mockReturnValue({ kind: 'external', path: '/notes/a.md', scopePath: '/notes' });
+    mocks.notify.mockImplementation(async () => { order.push('interactive'); });
+    mocks.restore.mockImplementation(async () => { order.push('restore'); });
     await initializeMainWindowStartup();
-
-    expect(mocks.calls).toEqual([
-      'memo-library',
-    ]);
+    expect(order).toEqual(['context', 'interactive', 'restore']);
+    expect(useWorkspaceStartupStore.getState().status).toBe('ready');
   });
 
-  it('stops dependent restoration when library initialization fails', async () => {
-    mocks.initializeNoteLibrary.mockRejectedValueOnce(new Error('backend unavailable'));
+  it('does not hold stage 2 open while a restored document is unresolved', async () => {
+    let finish!: () => void;
+    mocks.target.mockReturnValue({ kind: 'external', path: '/slow.md', scopePath: null });
+    mocks.restore.mockImplementation(() => new Promise<void>((resolve) => { finish = resolve; }));
+    await initializeMainWindowStartup();
+    expect(mocks.restore).toHaveBeenCalledOnce();
+    expect(mocks.notify).toHaveBeenCalledOnce();
+    expect(useWorkspaceStartupStore.getState().status).toBe('ready');
+    finish();
+    await vi.waitFor(() => expect(mocks.restoreStatus).toHaveBeenLastCalledWith('restored'));
+  });
 
-    await expect(initializeMainWindowStartup()).rejects.toThrow('backend unavailable');
-    expect(mocks.restoreExternalDocumentWorkspace).not.toHaveBeenCalled();
-    expect(mocks.restoreAgentConversationWorkspace).not.toHaveBeenCalled();
+  it('keeps restoration errors local after the workbench is interactive', async () => {
+    mocks.target.mockReturnValue({ kind: 'external', path: '/missing.md', scopePath: null });
+    mocks.restore.mockRejectedValue(new Error('file unavailable'));
+    await initializeMainWindowStartup();
+    await vi.waitFor(() => expect(mocks.restoreStatus).toHaveBeenLastCalledWith('unavailable'));
+    expect(useWorkspaceStartupStore.getState()).toMatchObject({ status: 'ready', error: null });
   });
 
-  it('shows a retryable error when the native notebook identity cannot be read', async () => {
-    Object.defineProperty(window, '__TAURI_INTERNALS__', { value: {}, configurable: true });
-    vi.spyOn(boot, 'waitForStartupReady').mockResolvedValue();
-    vi.spyOn(boot, 'getStartupNotebookId').mockRejectedValue(new Error('notebook identity unavailable'));
-    const notifyInteractive = vi.spyOn(boot, 'notifyStartupInteractive').mockResolvedValue();
-    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
-      callback(0);
-      return 1;
+  it('does not restore an old target after the user navigates during paint', async () => {
+    mocks.target.mockReturnValue({ kind: 'external', path: '/old.md', scopePath: null });
+    vi.mocked(window.requestAnimationFrame).mockImplementation((callback) => {
+      mocks.revision = 1; callback(0); return 1;
     });
-
-    await expect(initializeMainWindowStartup()).rejects.toThrow('notebook identity unavailable');
-
-    expect(mocks.initializeNoteLibrary).not.toHaveBeenCalled();
-    expect(useNoteStore.getState().startupPhase).toBe('error');
-    expect(notifyInteractive).toHaveBeenCalledOnce();
+    await initializeMainWindowStartup();
+    expect(mocks.restore).not.toHaveBeenCalled();
+    expect(useWorkspaceStartupStore.getState().status).toBe('ready');
   });
 
-  it('holds background maintenance until the restored document finishes loading', async () => {
-    Object.defineProperty(window, '__TAURI_INTERNALS__', { value: {}, configurable: true });
-    vi.spyOn(boot, 'waitForStartupReady').mockResolvedValue();
-    vi.spyOn(boot, 'getStartupNotebookId').mockResolvedValue('notebook-a');
-    vi.spyOn(boot, 'recordStartupStage').mockResolvedValue();
-    const notifyInteractive = vi.spyOn(boot, 'notifyStartupInteractive').mockResolvedValue();
-    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
-      callback(0);
-      return 1;
-    });
-    mocks.captureWorkspaceRestoreTarget.mockReturnValue({ kind: 'external', path: '/notes/active.md', scopePath: '/notes' });
-    mocks.restoreExternalDocumentWorkspace.mockImplementationOnce(async () => {
-      useDocumentStore.setState({ isDocumentTransitioning: true, documentTransitionId: 1 });
-    });
+  it('exposes a metadata failure without starting dependent content restoration', async () => {
+    mocks.context.mockRejectedValue(new Error('registry unavailable'));
+    await expect(initializeMainWindowStartup()).rejects.toThrow('registry unavailable');
+    expect(useWorkspaceStartupStore.getState()).toMatchObject({ status: 'failed', task: 'notebook-context' });
+    expect(mocks.restore).not.toHaveBeenCalled();
+    expect(mocks.notify).toHaveBeenCalledOnce();
+  });
 
-    const startup = initializeMainWindowStartup();
-    await vi.waitFor(() => expect(useDocumentStore.getState().isDocumentTransitioning).toBe(true));
-    expect(notifyInteractive).not.toHaveBeenCalled();
+  it('does not start background work when native preparation fails', async () => {
+    mocks.native.mockRejectedValue(new Error('storage unavailable'));
+    await expect(initializeMainWindowStartup()).rejects.toThrow('storage unavailable');
+    expect(mocks.notify).not.toHaveBeenCalled(); expect(mocks.context).not.toHaveBeenCalled();
+  });
 
-    useDocumentStore.getState().finishDocumentTransition(1);
-    await startup;
-    expect(notifyInteractive).toHaveBeenCalledOnce();
+  it('retains the identity error and releases an error screen for retry', async () => {
+    mocks.notebook.mockRejectedValue(new Error('identity unavailable'));
+    await expect(initializeMainWindowStartup()).rejects.toThrow('identity unavailable');
+    expect(mocks.markError).toHaveBeenCalledOnce(); expect(mocks.notify).toHaveBeenCalledOnce();
   });
 
-  it('releases the initial document barrier if its load stalls', async () => {
-    vi.useFakeTimers();
-    try {
-      useDocumentStore.setState({ isDocumentTransitioning: true, documentTransitionId: 1 });
-      const wait = waitForInitialDocumentLoad(100);
-      await vi.advanceTimersByTimeAsync(100);
-      await expect(wait).resolves.toBe('timeout');
-    } finally {
-      vi.useRealTimers();
-    }
+  it('coalesces concurrent startup calls', async () => {
+    let finish!: () => void;
+    mocks.context.mockImplementation(() => new Promise<void>((resolve) => { finish = resolve; }));
+    const first = initializeMainWindowStartup(); const second = initializeMainWindowStartup();
+    expect(second).toBe(first);
+    await vi.waitFor(() => expect(mocks.context).toHaveBeenCalledOnce());
+    finish(); await first;
+    expect(useWorkspaceStartupStore.getState().status).toBe('ready');
   });
 });
diff --git a/app/flowix-web/app/main-window-startup.ts b/app/flowix-web/app/main-window-startup.ts
index da2049e45..aaa64dbc9 100644
--- a/app/flowix-web/app/main-window-startup.ts
+++ b/app/flowix-web/app/main-window-startup.ts
@@ -1,106 +1,194 @@
 import {
   initializeNotebookContext,
   markMemoLibraryStartupError,
+  resumePendingNoteLinkUpdates,
 } from '@features/memo/public/app-api';
-import { waitForInitialDocumentLoad } from '@features/document/public/startup-api';
 import {
   captureWorkspaceRestoreTarget,
-  restoreDocumentListWorkspace,
+  restoreLegacyFolderListWorkspace,
   restoreAgentConversationWorkspace,
   restoreExternalDocumentWorkspace,
   restoreMediaWorkspace,
   restoreTableWorkspace,
   restoreCollectionWorkspace,
+  restoreFolderCollectionWorkspace,
   setWorkspaceRestoreStatus,
   type PersistedWorkspaceTarget,
 } from '@features/workspace/public/startup-api';
 import { boot } from '@platform/tauri/client';
+import { useWorkspaceStartupStore } from '@/lib/store/workspace-startup-store';
+import { getWorkspaceNavigationRevision } from '@features/workspace/public/shell-api';
+import { getWorkspaceMemoState } from '@features/memo/public/workspace-api';
+import { admitStartupStage3, runStartupStage3Task } from '@/lib/startup-stage3';
+import { waitForWorkbenchMounted } from '@/lib/workbench-mount';
 
 let startupAttemptSequence = 0;
+let startupPromise: Promise<void> | null = null;
+let workspaceRestorationPromise: Promise<void> = Promise.resolve();
+
+/** Agent history catch-up yields to the selected target, with a liveness bound. */
+export async function waitForWorkspaceRestoration(maxWaitMs = 2_000): Promise<void> {
+  let timeout: number | undefined;
+  await Promise.race([
+    workspaceRestorationPromise,
+    new Promise<void>((resolve) => {
+      timeout = window.setTimeout(resolve, maxWaitMs);
+    }),
+  ]);
+  if (timeout !== undefined) window.clearTimeout(timeout);
+}
 
 /**
- * Run the main-window startup stages in one failure-aware transaction.
- *
- * Notebook identity is resolved before workspace restoration. The cards query
- * then loads independently inside its view, so it cannot block folders or
- * conversations.
+ * Stage 2 ends when notebook identity and the interactive shell are available.
+ * Restored content loads independently, with view-local loading/error states.
  */
-export async function initializeMainWindowStartup(): Promise<void> {
+export function initializeMainWindowStartup(): Promise<void> {
+  if (startupPromise) return startupPromise;
+  const { status } = useWorkspaceStartupStore.getState();
+  if (status === 'ready' || status === 'degraded') {
+    admitStartupStage3();
+    void runStartupStage3Task('pending-note-link-updates', resumePendingNoteLinkUpdates);
+    return Promise.resolve();
+  }
+  startupPromise = performMainWindowStartup().finally(() => { startupPromise = null; });
+  return startupPromise;
+}
+
+async function performMainWindowStartup(): Promise<void> {
   const startedAt = performance.now();
   const nativeRuntime = isTauriRuntime();
+  let nativeReady = !nativeRuntime;
   const startupAttemptId = `${Date.now()}-${++startupAttemptSequence}`;
   const logStage = (stage: string) => {
     const elapsedMs = Math.round(performance.now() - startedAt);
     console.info('[perf:startup]', stage, { elapsedMs });
     if (nativeRuntime) void boot.recordStartupStage(stage, elapsedMs, startupAttemptId).catch(() => undefined);
   };
-  let startupNotebookId: string | null = null;
-  if (nativeRuntime) {
-    await boot.waitForStartupReady();
-    logStage('native-ready');
-  }
+  // Keep only workbench prerequisites in this awaited chain. Content hydration
+  // and optional services start after the shell has painted.
+  const runTask = async <T,>(task: string, operation: () => Promise<T>): Promise<T> => {
+    useWorkspaceStartupStore.setState({ task });
+    logStage(`task:${task}:start`);
+    const result = await operation();
+    logStage(`task:${task}:complete`);
+    return result;
+  };
+  useWorkspaceStartupStore.setState({
+    status: 'running', task: 'native-ready', error: null,
+  });
   try {
     if (nativeRuntime) {
-      try {
-        startupNotebookId = await boot.getStartupNotebookId();
-        logStage('notebook-selected');
-      } catch (error) {
-        markMemoLibraryStartupError(error);
-        throw error;
-      }
+      await boot.waitForStartupReady();
+      nativeReady = true;
+      useWorkspaceStartupStore.setState({ nativePhase: 'ready', nativeStage: 'workspacePreparation', nativeProgress: null, nativeError: null });
+      logStage('native-ready');
+    }
+    const startupNotebookId = nativeRuntime
+      ? await runTask('notebook-selection', async () => {
+          try {
+            return await boot.getStartupNotebookId();
+          } catch (error) {
+            markMemoLibraryStartupError(error);
+            throw error;
+          }
+        })
+      : null;
+    logStage('notebook-selected');
+    await runTask('notebook-context', () => initializeNotebookContext(startupNotebookId));
+    const hasNotebook = getWorkspaceMemoState().notebooks.length > 0;
+    const desiredTarget = hasNotebook ? captureWorkspaceRestoreTarget() : null;
+    const navigationRevision = getWorkspaceNavigationRevision();
+    // Release the shell before reading documents, tables or agent histories.
+    useWorkspaceStartupStore.setState({ status: 'ready', task: null, error: null });
+    setWorkspaceRestoreStatus(desiredTarget ? 'restoring' : 'restored');
+    await waitForWorkbenchMounted();
+    await afterShellPaint();
+    if (nativeRuntime) {
+      logStage('first-workspace-paint');
+      await boot.notifyStartupInteractive().catch(() => undefined);
     }
-    await initializeNotebookContext(startupNotebookId);
-    logStage('notebook-context-ready');
-    const desiredTarget = captureWorkspaceRestoreTarget();
-    setWorkspaceRestoreStatus('restoring');
-    try {
-      await restoreDesiredTarget(desiredTarget);
-      logStage('workspace-restored');
+    const shouldRestoreTarget = getWorkspaceNavigationRevision() === navigationRevision;
+    const restorePromise = shouldRestoreTarget
+      ? restoreDesiredTarget(desiredTarget, navigationRevision)
+      : Promise.resolve();
+    // Do not let low-priority Agent history recovery race the selected surface.
+    // The promise is observed without blocking the workbench startup barrier.
+    workspaceRestorationPromise = restorePromise.then(() => undefined, () => undefined);
+    admitStartupStage3();
+    void runStartupStage3Task('pending-note-link-updates', resumePendingNoteLinkUpdates);
+    logStage('stage3-admitted');
+    nativeReady = false; // The success path already released native startup.
+    if (!shouldRestoreTarget) {
       setWorkspaceRestoreStatus('restored');
-      const outcome = await waitForInitialDocumentLoad();
-      logStage(`initial-document-${outcome}`);
-    } catch (error) {
-      // Keep desiredTarget unchanged. Temporary permission, mount, or IPC
-      // failures can then be retried on the next launch.
-      setWorkspaceRestoreStatus('unavailable');
-      throw error;
+      return;
     }
+    // Do not await hydration from the startup barrier. Each navigation operation
+    // owns its cancellation identity so later user navigation wins.
+    void restorePromise.then(() => {
+      logStage('workspace-restore-settled');
+      setWorkspaceRestoreStatus('restored');
+    }).catch((error) => {
+      const targetStillDesired = JSON.stringify(captureWorkspaceRestoreTarget()) === JSON.stringify(desiredTarget);
+      if (targetStillDesired) {
+        console.warn('Workspace content restoration unavailable:', error);
+        setWorkspaceRestoreStatus('unavailable');
+      } else {
+        logStage('workspace-restore-superseded');
+        setWorkspaceRestoreStatus('restored');
+      }
+    });
+  } catch (error) {
+    useWorkspaceStartupStore.setState({
+      status: 'failed',
+      error: error instanceof Error ? error.message : String(error),
+    });
+    logStage(`task:${useWorkspaceStartupStore.getState().task}:failed`);
+    throw error;
   } finally {
-    if (nativeRuntime) {
-      // The first callback runs before paint; the second frame confirms that
-      // the restored content had a chance to appear before disk scans begin.
-      await new Promise<void>((resolve) => window.requestAnimationFrame(() => {
-        window.requestAnimationFrame(() => resolve());
-      }));
-      logStage('first-workspace-paint');
+    if (nativeRuntime && nativeReady) {
+      // A stage-2 retry screen can also paint and release independent work.
+      await waitForWorkbenchMounted();
+      await afterShellPaint();
+      const status = useWorkspaceStartupStore.getState().status;
+      logStage(status === 'ready' ? 'first-workspace-paint' : `foreground-${status}-paint`);
       await boot.notifyStartupInteractive().catch(() => undefined);
     }
   }
 }
 
-async function restoreDesiredTarget(target: PersistedWorkspaceTarget | null): Promise<void> {
-  if (!target) return;
+function afterShellPaint(): Promise<void> {
+  return new Promise((resolve) => window.requestAnimationFrame(() => {
+    window.requestAnimationFrame(() => resolve());
+  }));
+}
+
+async function restoreDesiredTarget(target: PersistedWorkspaceTarget | null, requestId: number): Promise<void> {
+  if (!target || getWorkspaceNavigationRevision() !== requestId) return;
   if (target.kind === 'external') {
-    await restoreExternalDocumentWorkspace(target);
+    await restoreExternalDocumentWorkspace(target, requestId);
     return;
   }
   if (target.kind === 'media') {
-    await restoreMediaWorkspace(target);
+    await restoreMediaWorkspace(target, requestId);
     return;
   }
   if (target.kind === 'collection') {
-    await restoreCollectionWorkspace(target);
+    await restoreCollectionWorkspace(target, requestId);
+    return;
+  }
+  if (target.kind === 'folder-collection') {
+    await restoreFolderCollectionWorkspace(target, requestId);
     return;
   }
   if (target.kind === 'table') {
-    await restoreTableWorkspace(target);
+    await restoreTableWorkspace(target, requestId);
     return;
   }
   if (target.kind === 'document-list') {
-    restoreDocumentListWorkspace(target);
+    await restoreLegacyFolderListWorkspace(target, requestId);
     return;
   }
-  await restoreAgentConversationWorkspace();
+  await restoreAgentConversationWorkspace(requestId);
 }
 
 function isTauriRuntime(): boolean {
diff --git a/app/flowix-web/app/main-window/main-window.tsx b/app/flowix-web/app/main-window/main-window.tsx
index b373f731d..2f5dbea05 100644
--- a/app/flowix-web/app/main-window/main-window.tsx
+++ b/app/flowix-web/app/main-window/main-window.tsx
@@ -1,7 +1,8 @@
-import { lazy, Suspense } from 'react';
+import { lazy, Suspense, useEffect } from 'react';
 import { useMainWindowBusinessController } from './use-main-window-business-controller';
 import { useMainWindowSystemController } from './use-main-window-system-controller';
 import { ensureFileDisplayTrackingStarted } from '@features/workspace/public/app-api';
+import { notifyWorkbenchMounted } from '@/lib/workbench-mount';
 
 // Initialize before the first persisted surface is rendered.
 if (typeof window !== 'undefined') ensureFileDisplayTrackingStarted();
@@ -16,6 +17,12 @@ export function MainWindow() {
   return (
     <Suspense fallback={null}>
       <MainLayout business={business} system={system} />
+      <WorkbenchMountedSignal />
     </Suspense>
   );
 }
+
+function WorkbenchMountedSignal() {
+  useEffect(() => notifyWorkbenchMounted(), []);
+  return null;
+}
diff --git a/app/flowix-web/app/main-window/use-main-window-business-controller.ts b/app/flowix-web/app/main-window/use-main-window-business-controller.ts
index 88691ac38..00997745e 100644
--- a/app/flowix-web/app/main-window/use-main-window-business-controller.ts
+++ b/app/flowix-web/app/main-window/use-main-window-business-controller.ts
@@ -14,14 +14,17 @@ import {
 } from '@features/memo/public/workspace-api';
 import {
   clearPluginWorkbenchTarget,
-  flushWorkspaceDocument,
-  openCollectionTarget,
-  openPluginWorkbench,
   reconcileDeletedNotebook,
   selectNotebook,
   useWorkspaceNavigationPhase,
   useWorkspaceTargetKind,
 } from '@features/workspace/public/main-window-api';
+import {
+  documentIdentityFromFile,
+  getWorkspaceDocumentState,
+  saveWorkspaceDocumentPath,
+} from '@features/document/public/workspace-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { switchFolderCollectionType, type CollectionType } from '@features/collection/public/folder-api';
 
 const logger = createLogger('main-window-business-controller');
@@ -104,7 +107,17 @@ export function useMainWindowBusinessController(): MainWindowBusinessController
     const target = notebookToDelete;
     if (!target) return;
     try {
-      if (selectedNotebook?.id === target.id) await flushWorkspaceDocument();
+      if (selectedNotebook?.id === target.id) {
+        const active = getWorkspaceDocumentState().activeExternalSession;
+        if (active && !await saveWorkspaceDocumentPath(
+          documentIdentityFromFile(active.fileIdentity),
+          active.fileIdentity.path,
+          active.scopePath,
+        )) {
+          toast.error(t('notebook.delete.saveCurrentDocumentFailed'));
+          return;
+        }
+      }
       const deleted = await notebooksClient.delete(target.id, deleteLocalFiles);
       if (!deleted) {
         toast.error(t('shell.notebook.deleteFailed'));
@@ -132,7 +145,7 @@ export function useMainWindowBusinessController(): MainWindowBusinessController
       return;
     }
     try {
-      await openPluginWorkbench(plugin);
+      await openWorkspaceSurface({ host: 'main-third', target: { kind: 'plugin-workbench', plugin } });
       setMemoListVisible(true);
     } catch (error) {
       logger.warn('open plugin failed to clear document', { error });
@@ -145,10 +158,11 @@ export function useMainWindowBusinessController(): MainWindowBusinessController
   ) => {
     try {
       const collectionId = await switchFolderCollectionType(target.filePath, target.notebookPath, type);
-      await openCollectionTarget(
-        { notebookId: target.notebookId, collectionId, viewId: null },
-        { destination: 'main-third', history: 'skip' },
-      );
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'collection-reference', notebookId: target.notebookId, collectionId, viewId: null, collectionKind: type },
+        options: { history: 'skip', refresh: true },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : '切换视图类型失败');
     }
diff --git a/app/flowix-web/app/main-window/use-main-window-system-controller.ts b/app/flowix-web/app/main-window/use-main-window-system-controller.ts
index a645f10e8..adbda88c6 100644
--- a/app/flowix-web/app/main-window/use-main-window-system-controller.ts
+++ b/app/flowix-web/app/main-window/use-main-window-system-controller.ts
@@ -1,11 +1,9 @@
-import { useCallback, useEffect, useState } from 'react';
-import { boot, consumeAppUpdateResult, dshIntegration, type DshDownloadProgress } from '@platform/tauri/client';
-import { subscribe } from '@platform/tauri/event-bus';
-import { useAppUpdatePreferences } from '@features/preferences/public/app-api';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import {
-  useDshRuntimeInstaller,
-  type DshRuntimeInstallerState,
-} from '@features/preferences/public/system-api';
+  consumeAppUpdateResult,
+  type AppUpdateInstallResult,
+} from '@platform/tauri/client';
+import { useAppUpdatePreferences } from '@features/preferences/public/app-api';
 import {
   useAppUpdater,
   type AppUpdaterState,
@@ -13,113 +11,70 @@ import {
 import { createLogger } from '@/lib/logger';
 import { toast } from '@/lib/toast';
 import { useI18n } from '@/lib/i18n';
+import { useWorkspaceMemoViewModel } from '@features/memo/public/workspace-api';
 
 const logger = createLogger('main-window-system-controller');
 
-function isActiveDshDownload(progress: DshDownloadProgress | null): boolean {
-  return progress?.phase === 'checking'
-    || progress?.phase === 'downloading'
-    || progress?.phase === 'downloaded'
-    || progress?.phase === 'installing';
-}
-
 export interface MainWindowSystemController {
-  dshDownload: DshDownloadProgress | null;
-  dshInstallPromptOpen: boolean;
   onboardingOpen: boolean;
   onboardingLoading: boolean;
   updater: AppUpdaterState;
-  dshInstaller: DshRuntimeInstallerState;
-  closeDshInstallPrompt(): void;
-  markDshIntroDisplayed(): void;
-  completeDshInstallPrompt(): void;
+  hasPendingAppUpdateResult: boolean;
+  presentPendingAppUpdateResult(): void;
   completeOnboarding(): Promise<void>;
 }
 
 export function useMainWindowSystemController(): MainWindowSystemController {
-  const [dshDownload, setDshDownload] = useState<DshDownloadProgress | null>(null);
-  const [dshInstallPromptOpen, setDshInstallPromptOpen] = useState(false);
   const [onboardingOpen, setOnboardingOpen] = useState(false);
   const [onboardingLoading, setOnboardingLoading] = useState(true);
+  const onboardingDecisionMade = useRef(false);
+  const { notebooks, startupPhase } = useWorkspaceMemoViewModel();
+  const [pendingAppUpdateResult, setPendingAppUpdateResult] = useState<AppUpdateInstallResult | null>(null);
   const { t } = useI18n();
   const updatePreferences = useAppUpdatePreferences();
   const updater = useAppUpdater({
     autoCheck: !updatePreferences.loading,
     enabled: updatePreferences.enabled,
   });
-  const dshInstaller = useDshRuntimeInstaller();
 
   useEffect(() => {
     void consumeAppUpdateResult().then((result) => {
-      if (!result) return;
-      if (result.status === 'failed') {
-        toast.error(`${t('appUpdates.previousInstallFailed')}${result.message ? `: ${result.message}` : ''}`);
-      } else {
-        toast.success(t('appUpdates.installSucceeded'));
-      }
+      if (result) setPendingAppUpdateResult(result);
     }).catch((error) => {
       logger.warn('read previous app update result failed', { error });
     });
-  }, [t]);
-
-  useEffect(() => {
-    const applyProgress = (progress: DshDownloadProgress) => {
-      setDshDownload(isActiveDshDownload(progress) ? progress : null);
-    };
-    const unsubscribe = subscribe<DshDownloadProgress>('dsh-download-progress', applyProgress);
-    void dshIntegration.downloadStatus()
-      .then((progress) => {
-        if (progress) applyProgress(progress);
-      })
-      .catch(() => {
-        // Preferences remains the detailed recovery surface.
-      });
-    return unsubscribe;
   }, []);
 
   useEffect(() => {
-    let cancelled = false;
-    void boot.getFeatures().then((features) => {
-      if (cancelled) return;
-      if (!features.isOnboardingCompleted) {
-        setOnboardingOpen(true);
-        return;
-      }
-      // Notebook-only onboarding must not schedule the legacy Agent intro on a later launch.
-    }).catch(() => {
-      // Do not show onboarding when its durable state cannot be read.
-    }).finally(() => {
-      if (!cancelled) setOnboardingLoading(false);
-    });
-    return () => { cancelled = true; };
-  }, []);
-
-  const markDshIntroDisplayed = useCallback(() => {
-    void boot.setIntroDisplayed().catch((error) => {
-      logger.warn('persist DSH intro display state failed', { error });
-    });
-  }, []);
-
-  const closeDshInstallPrompt = useCallback(() => {
-    markDshIntroDisplayed();
-    setDshInstallPromptOpen(false);
-  }, [markDshIntroDisplayed]);
+    if (startupPhase !== 'ready' || onboardingDecisionMade.current) return;
+    // Notebook identity is resolved in stage 2. Show first-run onboarding only
+    // when the notebook list is empty; do not wait for stage 3 or another read.
+    onboardingDecisionMade.current = true;
+    setOnboardingOpen(notebooks.length === 0);
+    setOnboardingLoading(false);
+  }, [notebooks.length, startupPhase]);
 
   const completeOnboarding = useCallback(async () => {
-    await boot.setOnboardingCompleted();
     setOnboardingOpen(false);
   }, []);
 
+  const presentPendingAppUpdateResult = useCallback(() => {
+    if (!pendingAppUpdateResult) return;
+    const result = pendingAppUpdateResult;
+    setPendingAppUpdateResult(null);
+    if (result.status === 'failed') {
+      toast.error(`${t('appUpdates.previousInstallFailed')}${result.message ? `: ${result.message}` : ''}`);
+    } else {
+      toast.success(t('appUpdates.installSucceeded'));
+    }
+  }, [pendingAppUpdateResult, t]);
+
   return {
-    dshDownload,
-    dshInstallPromptOpen,
     onboardingOpen,
     onboardingLoading,
     updater,
-    dshInstaller,
-    closeDshInstallPrompt,
-    markDshIntroDisplayed,
-    completeDshInstallPrompt: () => setDshInstallPromptOpen(false),
+    hasPendingAppUpdateResult: pendingAppUpdateResult !== null,
+    presentPendingAppUpdateResult,
     completeOnboarding,
   };
 }
diff --git a/app/flowix-web/app/memo-dispatcher-integration.test.ts b/app/flowix-web/app/memo-dispatcher-integration.test.ts
index 6ef0775dd..09706ac0f 100644
--- a/app/flowix-web/app/memo-dispatcher-integration.test.ts
+++ b/app/flowix-web/app/memo-dispatcher-integration.test.ts
@@ -24,7 +24,7 @@ describe('memo dispatcher window isolation', () => {
     const releaseDocument = memoDispatcher.subscribe(documentHandler);
     const releaseRefresh = registerMemoDerivedRefreshHandler(refresh);
     const event: MemoEvent = {
-      kind: 'deleted', id: 'memo', path: '/memo.md', relativePath: 'memo.md', notebookId: 'notebook',
+      kind: 'deleted', path: '/memo.md', relativePath: 'memo.md', notebookId: 'notebook',
       source: 'external_tool', derivedOnly: true,
       derivedChanged: { tags: true, todos: true, agents: false },
     };
@@ -141,8 +141,8 @@ describe('memo dispatcher window isolation', () => {
     bridge?.({
       kind: 'created',
       memo: {
-        id: 'memo-external',
         filename: 'External.md',
+        relativePath: 'External.md',
         preview: '',
         tags: [],
         todos: [],
diff --git a/app/flowix-web/app/use-agent-access-window-sync.ts b/app/flowix-web/app/use-agent-access-window-sync.ts
deleted file mode 100644
index bf7a5d548..000000000
--- a/app/flowix-web/app/use-agent-access-window-sync.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { useEffect } from 'react';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
-import { listenToAgentAccessChanges } from '@platform/tauri/client';
-
-/** Each Webview owns a store, including the preferences window. */
-export function useAgentAccessWindowSync() {
-  const loadInitial = useAgentAccessStore((state) => state.loadInitial);
-  useEffect(() => {
-    const reload = () => { void loadInitial(); };
-    const unlisten = listenToAgentAccessChanges(reload, { onListenerReady: reload });
-    reload();
-    return unlisten;
-  }, [loadInitial]);
-}
diff --git a/app/flowix-web/app/use-agent-workspace-window-lifecycle.ts b/app/flowix-web/app/use-agent-workspace-window-lifecycle.ts
new file mode 100644
index 000000000..6105adab4
--- /dev/null
+++ b/app/flowix-web/app/use-agent-workspace-window-lifecycle.ts
@@ -0,0 +1,87 @@
+import { ensureAgentPreferencesReady } from "@features/agent/store/agent-data-store";
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
+import { useEffect } from 'react';
+import { listenToAgentWorkspaceChanges, boot } from '@platform/tauri/client';
+import { runStartupStage3Task, waitForStartupStage3 } from '@/lib/startup-stage3';
+
+interface AgentWorkspaceWindowLifecycleOptions {
+  /** Defer main-window Agent data until its shell paints; the preferences window loads on mount. */
+  deferUntilStage3?: boolean;
+}
+
+// Shared snapshot state outlives effect instances, just like the named task.
+let startupSnapshotRequested = false;
+
+/** Initialize per-Webview Agent data and keep its workspace snapshot in sync. */
+export function useAgentWorkspaceWindowLifecycle(
+  { deferUntilStage3 = false }: AgentWorkspaceWindowLifecycleOptions = {},
+) {
+  const loadInitial = useAgentWorkspaceStore((state) => state.workspaceActions.loadInitial);
+  useEffect(() => {
+    let active = true;
+    let initialLoadStarted = false;
+    let initialLoadSettled = false;
+    let reloadQueued = false;
+    let reloadInFlight = false;
+    let unlisten: (() => void) | undefined;
+    const runQueuedReload = () => {
+      if (!active || !initialLoadSettled || !reloadQueued || reloadInFlight) return;
+      reloadQueued = false;
+      reloadInFlight = true;
+      void loadInitial().catch((error) => {
+        console.warn('Workspace reload failed:', error);
+      }).finally(() => {
+        reloadInFlight = false;
+        runQueuedReload();
+      });
+    };
+    const reload = () => {
+      if (!active) return;
+      if (!initialLoadSettled || reloadInFlight) {
+        reloadQueued = true;
+        return;
+      }
+      reloadQueued = true;
+      runQueuedReload();
+    };
+    const initialize = async () => {
+      if ('__TAURI_INTERNALS__' in window || '__TAURI__' in window) {
+        await boot.waitForStartupReady();
+      }
+      if (!active) return;
+      unlisten = listenToAgentWorkspaceChanges(reload, {
+        onListenerReady: () => {
+          // The initial snapshot covers first registration when it has not
+          // started yet; reconnects after that need a fresh snapshot.
+          if (initialLoadStarted || (deferUntilStage3 && startupSnapshotRequested)) reload();
+        },
+      });
+
+      // Stage 3 owns scheduling; each store loads its own state independently.
+      const markInitialLoadSettled = () => {
+        if (!active) return;
+        initialLoadSettled = true;
+        runQueuedReload();
+      };
+      const initializeAgentPreferences = () => ensureAgentPreferencesReady().catch((error) => {
+        console.warn('Pi mode initialization failed:', error);
+      });
+
+      const workspaceTask = deferUntilStage3
+        ? runStartupStage3Task('agent-workspace-snapshot-load', async () => { await loadInitial(); })
+        : loadInitial();
+      const preferencesTask = deferUntilStage3
+        ? runStartupStage3Task('agent-preferences-initialize', initializeAgentPreferences)
+        : initializeAgentPreferences();
+      void workspaceTask.finally(markInitialLoadSettled);
+
+      if (deferUntilStage3) await waitForStartupStage3();
+      if (!active) return;
+      initialLoadStarted = true;
+      if (deferUntilStage3) startupSnapshotRequested = true;
+      await Promise.all([workspaceTask, preferencesTask]);
+    };
+    void initialize().catch((error) => console.warn('Workspace initialization deferred:', error));
+    return () => { active = false; unlisten?.(); };
+  }, [deferUntilStage3, loadInitial]);
+}
diff --git a/app/flowix-web/app/user-config-sync.ts b/app/flowix-web/app/user-config-sync.ts
index 2c357000d..e8ff15385 100644
--- a/app/flowix-web/app/user-config-sync.ts
+++ b/app/flowix-web/app/user-config-sync.ts
@@ -25,7 +25,12 @@ export function syncUserConfigChange(
     void actions.reloadPreferences();
     return;
   }
-  if (kind === 'pi_config') return;
+  if (kind === 'pi_config') {
+    void import('@features/agent/services/agent-catalog-service')
+      .then(({ refreshAgentModelCatalog }) => refreshAgentModelCatalog('pi'))
+      .catch((error) => console.warn('Failed to refresh the Pi model catalog after its configuration changed', error));
+    return;
+  }
 
   // Runtime freshness currently has one timestamp for the complete status
   // snapshot. Refresh the complete snapshot so unrelated agent statuses are
diff --git a/app/flowix-web/assets/skill-library.svg b/app/flowix-web/assets/skill-library.svg
new file mode 100644
index 000000000..2e876bc76
--- /dev/null
+++ b/app/flowix-web/assets/skill-library.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false" class="agent-composer__skill-token-icon">
+  <g transform="translate(1.32 1.32) scale(0.64)">
+    <rect width="8" height="18" x="3" y="3" rx="1" vector-effect="non-scaling-stroke" />
+    <path d="M7 3v18" vector-effect="non-scaling-stroke" />
+    <path d="M20.4 18.9c.2.5-.1 1.1-.6 1.3l-1.9.7c-.5.2-1.1-.1-1.3-.6L11.1 5.1c-.2-.5.1-1.1.6-1.3l1.9-.7c.5-.2 1.1.1 1.3.6Z" vector-effect="non-scaling-stroke" />
+  </g>
+</svg>
diff --git a/app/flowix-web/entrypoints/desktop.tsx b/app/flowix-web/entrypoints/desktop.tsx
index 541a2e4a0..d1349e11f 100644
--- a/app/flowix-web/entrypoints/desktop.tsx
+++ b/app/flowix-web/entrypoints/desktop.tsx
@@ -1,6 +1,7 @@
 import { createRoot } from "react-dom/client";
 
 import App from "@app/app";
+import { installDesktopShutdown } from "@app/desktop-shutdown";
 import "@/styles/index.css";
 import "sonner/dist/styles.css";
 import { initTauriClient } from "@platform/tauri/client";
@@ -17,4 +18,6 @@ try {
   console.error("[desktop entry] Failed to initialize Tauri:", error);
 }
 
+installDesktopShutdown();
+
 createRoot(document.getElementById("root")!).render(<App />);
diff --git a/app/flowix-web/features/agent/agent-setup.ts b/app/flowix-web/features/agent/agent-setup.ts
index 23d54664f..e4fa167ce 100644
--- a/app/flowix-web/features/agent/agent-setup.ts
+++ b/app/flowix-web/features/agent/agent-setup.ts
@@ -4,10 +4,8 @@ import { isAgentTypeComingSoon } from '@/lib/agent-types';
 
 const AGENT_SETUP_URLS: Partial<Record<AgentTypeKey, string>> = {
   codex: 'https://developers.openai.com/codex/cli',
-  claude: 'https://code.claude.com/docs/en/setup',
-  gemini: 'https://google-gemini.github.io/gemini-cli/docs/cli/headless.html',
+  claudecode: 'https://code.claude.com/docs/en/setup',
   hermes: 'https://hermes-agent.nousresearch.com/docs/user-guide/cli',
-  openclaw: 'https://docs.openclaw.ai/cli',
   opencode: 'https://opencode.ai/docs/cli/',
 };
 
diff --git a/app/flowix-web/features/agent/components/agent-background-terminals.tsx b/app/flowix-web/features/agent/components/agent-background-terminals.tsx
index 46e6b95d0..7c4bebde8 100644
--- a/app/flowix-web/features/agent/components/agent-background-terminals.tsx
+++ b/app/flowix-web/features/agent/components/agent-background-terminals.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useMemo, useState } from 'react';
-import { ArrowBendDownRightIcon, TrashSimpleIcon } from '@phosphor-icons/react';
+import { ArrowBendDownRightIcon } from '@phosphor-icons/react';
 import { useI18n } from '@/lib/i18n';
 import { agentClient } from '@features/agent/store/agent-client';
 
@@ -36,7 +36,7 @@ function readTerminals(value: unknown): BackgroundTerminal[] {
   });
 }
 
-export function AgentBackgroundTerminals({ threadId, agentType, enabled, queuedMessages = [], onPromoteFollowUp, onDeleteQueuedMessage }: { threadId: string | null; agentType: 'codex' | 'deepseek-harness'; enabled: boolean; queuedMessages?: readonly QueuedAgentMessage[]; onPromoteFollowUp?: (messageId: string) => void; onDeleteQueuedMessage?: (messageId: string) => void }) {
+export function AgentBackgroundTerminals({ threadId, agentType, enabled, queuedMessages = [], onPromoteFollowUp, onDeleteQueuedMessage }: { threadId: string | null; agentType: 'codex' | 'dsh'; enabled: boolean; queuedMessages?: readonly QueuedAgentMessage[]; onPromoteFollowUp?: (messageId: string) => void; onDeleteQueuedMessage?: (messageId: string) => void }) {
   const { t } = useI18n();
   const [terminals, setTerminals] = useState<BackgroundTerminal[]>([]);
   const [expanded, setExpanded] = useState(false);
@@ -145,19 +145,19 @@ function QueuedMessages({ messages, label, onPromoteFollowUp, onDeleteQueuedMess
               {message.deliveryStatus === 'starting' && (
                 <span className="agent-background-terminals__queue-soon" role="status">{t('agent.queue.sendingSoon')}</span>
               )}
-              {message.deliveryMode === 'follow_up' && message.deliveryStatus !== 'starting' && onPromoteFollowUp && (
-                <button type="button" className="agent-background-terminals__queue-steer" disabled={message.actionsDisabled} onClick={() => onPromoteFollowUp(message.id)}>
-                  {t('agent.queue.steerNow')}
-                </button>
-              )}
               {message.deliveryMode === 'steer' && onDeleteQueuedMessage && (
                 <span className="agent-background-terminals__queue-soon" role="status">
                   {message.deliveryStatus === 'cleanup_failed' ? t('agent.queue.cleanupFailed') : t('agent.queue.sendingSoon')}
                 </span>
               )}
               {onDeleteQueuedMessage && message.canDelete !== false && <button type="button" className="agent-background-terminals__queue-delete" disabled={message.actionsDisabled} aria-label={t('agent.queue.deleteQueued')} title={t('agent.queue.deleteQueued')} onClick={() => onDeleteQueuedMessage(message.id)}>
-                <TrashSimpleIcon aria-hidden="true" />
+                {t('agent.queue.deleteQueued')}
               </button>}
+              {message.deliveryMode === 'follow_up' && message.deliveryStatus !== 'starting' && onPromoteFollowUp && (
+                <button type="button" className="agent-background-terminals__queue-steer" disabled={message.actionsDisabled} onClick={() => onPromoteFollowUp(message.id)}>
+                  {t('agent.queue.steerNow')}
+                </button>
+              )}
             </span>
           )}
         </div>
diff --git a/app/flowix-web/features/agent/components/agent-conversation-detail-submit.ts b/app/flowix-web/features/agent/components/agent-conversation-detail-submit.ts
index e0f1c0046..e5413acb1 100644
--- a/app/flowix-web/features/agent/components/agent-conversation-detail-submit.ts
+++ b/app/flowix-web/features/agent/components/agent-conversation-detail-submit.ts
@@ -1,3 +1,4 @@
+import { ensureAgentWorkspaceReady } from "@features/agent/store/agent-workspace-store";
 import type { AgentTypeKey, RuntimeConfig } from "@/types/agent";
 import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
 import { buildInitialInstanceRuntimeConfig } from "@features/agent/store/initial-runtime-config";
@@ -64,6 +65,7 @@ export async function ensureAgentConversationDetailThread(input: {
     runtimeConfig:
       instance.runtimeConfig ?? buildInitialInstanceRuntimeConfig(ensured.typeKey),
   });
+  await ensureAgentWorkspaceReady();
   const runtimeConfig = ensureConversationWorkspaceSnapshot(input.instanceId);
   markConversationWorkspaceStarted(input.instanceId);
   return { threadId: ensured.threadId, title: ensured.title, runtimeConfig };
diff --git a/app/flowix-web/features/agent/components/agent-conversation-detail.tsx b/app/flowix-web/features/agent/components/agent-conversation-detail.tsx
index 49fe42a1f..37cf94dbd 100644
--- a/app/flowix-web/features/agent/components/agent-conversation-detail.tsx
+++ b/app/flowix-web/features/agent/components/agent-conversation-detail.tsx
@@ -2,13 +2,16 @@
 
 import { useCallback, useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type UIEventHandler, type WheelEventHandler } from 'react';
 
+import type { SurfacePresentationUpdate } from '@features/workspace/model/surface-contract';
 import { DEFAULT_AGENT_TYPE_KEY } from '@/lib/agent-types';
 import type { AgentTypeKey } from '@/types/agent';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
 import { createLogger } from '@/lib/logger';
 import { agent } from '@platform/tauri/client/agent';
+import { useAgentConversationSurface } from './use-agent-conversation-surface';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
+import { createAndOpenAgentConversation } from '@features/agent/use-cases/new-conversation';
 import { canActOnQueuedMessage } from '@features/agent/store/follow-up-queue-slice';
 import type { AgentConversationInstance } from '@features/agent/store/agent-conversation-types';
 import { useNoteStore } from '@features/memo/store/note-store';
@@ -23,7 +26,8 @@ import {
   ComposerSubmissionController,
   getComposerRuntimeState,
   ComposerDraftController,
-  ComposerImageController,
+  ComposerAttachmentController,
+  ComposerAttachmentDocument,
   ComposerAddMenuController,
   getCurrentNotebookComposerFolders,
   createAgentComposerDom,
@@ -41,7 +45,7 @@ import { AgentBackgroundTerminals } from '@features/agent/components/agent-backg
 import { CodexApprovalQueue } from '@features/agent/components/codex-approval-queue';
 import { buildInitialInstanceRuntimeConfig } from '@features/agent/store/initial-runtime-config';
 import { defaultThreadTitle } from '@features/agent/store/thread-titles';
-import { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
 import {
   agentFileScopePathForRuntime,
@@ -61,6 +65,13 @@ import { Button } from '@shared/ui/button';
 import { createRunId } from '@features/agent/events/agent-event-mapper';
 import { completedRunUserMessageId } from '@features/agent/events/message-identity';
 import { createAgentMessageAttachments, prepareUserMessage } from '@features/agent/store/user-message';
+import { isAgentThreadCardImageAttachment } from '@features/agent/thread-card/composer/composer-attachment-types';
+import {
+  getAgentMessageTypographyCssVars,
+  useAgentMessageFontStore,
+} from '@features/agent/store/agent-message-font-store';
+import { ensureDownloadedFontRegistered } from '@features/preferences/public/font-api';
+import { getTypographyFontId } from '@/lib/typography-font-mode';
 
 const BOTTOM_FOLLOW_THRESHOLD_PX = 96;
 const TOP_HISTORY_LOAD_THRESHOLD_PX = 48;
@@ -68,6 +79,12 @@ const SCROLL_DELTA_EPSILON_PX = 0.5;
 const INPUT_DRAFT_MAX_CHARS = 500;
 const EMPTY_MESSAGES: ThreadState['messages'] = [];
 const EMPTY_PENDING_CODEX_MESSAGES: readonly [] = [];
+
+function isMissingHistorySession(error: string | null | undefined): boolean {
+  if (!error) return false;
+  return Boolean(error.match(/session\s+["'][^"']+["']\s+not found/i)
+    ?? error.match(/session\s+not found:\s*["']?[\w.-]+["']?/i));
+}
 const DETAIL_DRAFT_KEY_PREFIX = 'flowix:agent-conversation-draft:';
 const logger = createLogger('agent-conversation-detail');
 
@@ -115,48 +132,26 @@ function persistDetailDraft(instanceId: string, draft: string | null): void {
  */
 export function AgentConversationDetail({
   instanceId,
+  reportPresentation,
 }: {
   instanceId: string;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
 }) {
   const { t } = useI18n();
-  const instance = useAgentSessionStore((state) => state.getInstance(instanceId));
-  const [loadState, setLoadState] = useState<{
-    instanceId: string;
-    status: 'loading' | 'not-found' | 'error';
-  } | null>(null);
-  const [retryCount, setRetryCount] = useState(0);
-  useEffect(() => {
-    if (instance) return;
-
-    let cancelled = false;
-    setLoadState({ instanceId, status: 'loading' });
-    void useAgentSessionStore.getState().hydrateInstance(instanceId)
-      .then((restored) => {
-        if (!cancelled && !restored) setLoadState({ instanceId, status: 'not-found' });
-      })
-      .catch(() => {
-        if (!cancelled) setLoadState({ instanceId, status: 'error' });
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [instance, instanceId, retryCount]);
+  const { instance, status, retry } = useAgentConversationSurface(instanceId, reportPresentation);
 
   if (instance) {
     return <AgentConversationDetailContent key={instanceId} instanceId={instanceId} instance={instance} />;
   }
 
-  const status = loadState?.instanceId === instanceId ? loadState.status : 'loading';
+  if (reportPresentation) return null;
   return (
     <WorkspaceEmptyState
       tone="agent"
       message={status === 'loading' ? t('status.agent.loadingConversations') : (
         <span className="flex flex-col items-center gap-3">
           <span>{t(status === 'error' ? 'status.agent.loadConversationsFailed' : 'status.agent.conversationNotFound')}</span>
-          <Button variant="outline" size="sm" className="rounded-lg" onClick={() => {
-            setLoadState({ instanceId, status: 'loading' });
-            setRetryCount((count) => count + 1);
-          }}>
+          <Button variant="outline" size="sm" className="rounded-lg" onClick={retry}>
             {t('error.retry')}
           </Button>
         </span>
@@ -174,6 +169,17 @@ function AgentConversationDetailContent({
   instance: AgentConversationInstance;
 }) {
   const { language, t } = useI18n();
+  const selectedNotebookId = useNoteStore((state) => state.selectedNotebook?.id ?? null);
+  const messageFontMode = useAgentMessageFontStore((state) => state.fontMode);
+  const messageSizeMode = useAgentMessageFontStore((state) => state.sizeMode);
+  useEffect(() => {
+    if (messageFontMode === 'standard') return;
+    const fontId = getTypographyFontId(messageFontMode);
+    void ensureDownloadedFontRegistered(fontId).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      toast.error(t('preferences.format.fontDownloadFailed', { message }));
+    });
+  }, [messageFontMode, t]);
   const threadId = instance.threadId;
   const renderThreadId = threadId;
   const projection = useAgentSessionStore((state) => (
@@ -202,12 +208,14 @@ function AgentConversationDetailContent({
   );
   const initialHistoryStatus = projection?.pagination.initialStatus ?? 'idle';
   const initialHistoryError = projection?.pagination.initialError;
+  const missingSession = isMissingHistorySession(initialHistoryError);
   const isInitialHistoryLoading = shouldShowInitialHistorySkeleton(
     threadId,
     messages.length,
     initialHistoryStatus,
   );
   const showHistoryError = initialHistoryStatus === 'error' && messages.length === 0;
+  const showHistoryWarning = initialHistoryStatus === 'error' && messages.length > 0;
   const domRef = useRef<HTMLDivElement>(null);
   const bodyRef = useRef<HTMLDivElement>(null);
   const composerMountRef = useRef<HTMLDivElement>(null);
@@ -215,7 +223,7 @@ function AgentConversationDetailContent({
   const inputRef = useRef<HTMLDivElement>(null);
   const messagesControllerRef = useRef<AgentThreadCardMessagesController | null>(null);
   const composerControllerRef = useRef<ComposerController | null>(null);
-  const composerImagesControllerRef = useRef<ComposerImageController | null>(null);
+  const composerAttachmentsControllerRef = useRef<ComposerAttachmentController | null>(null);
   const externalSettingsRef = useRef<ExternalAgentSettingsController | null>(null);
   const addMenuRef = useRef<ComposerAddMenuController | null>(null);
   const notebookAgentSettingsDialogRef = useRef<NotebookAgentSettingsDialogController | null>(null);
@@ -242,9 +250,9 @@ function AgentConversationDetailContent({
     const currentInstance = instanceRef.current;
     const sourceThreadId = threadIdRef.current;
     const agentType = currentInstance?.agentType;
-    if (!currentInstance || !sourceThreadId || (agentType !== 'codex' && agentType !== 'deepseek-harness' && agentType !== 'pi')) return;
+    if (!currentInstance || !sourceThreadId || (agentType !== 'codex' && agentType !== 'dsh' && agentType !== 'pi')) return;
     if (agentType === 'codex' && !message.codexTurnId) return;
-    if (agentType === 'deepseek-harness' && message.sourceSequence === undefined) return;
+    if (agentType === 'dsh' && message.sourceSequence === undefined) return;
     if (agentType === 'pi' && !message.messageId) return;
 
     if (destroyedRef.current) return;
@@ -252,7 +260,7 @@ function AgentConversationDetailContent({
     try {
       const result = agentType === 'codex'
         ? await agent.forkCodexThread(sourceThreadId, message.codexTurnId!)
-        : agentType === 'deepseek-harness'
+        : agentType === 'dsh'
           ? await agent.forkDeepSeekHarnessThread(sourceThreadId, message.sourceSequence!)
           : await agent.forkPiThread(sourceThreadId, message.messageId!);
       const fork = useAgentSessionStore.getState().createInstance({
@@ -265,7 +273,7 @@ function AgentConversationDetailContent({
         },
         source: { kind: 'dedicated', notebookId: currentInstance.source.notebookId ?? null },
       });
-      await selectAndOpenAgentConversation(fork.instanceId);
+      await openWorkspaceSurface({ target: { kind: 'agent-conversation', instanceId: fork.instanceId } });
     } catch (error) {
       logger.error(`Failed to fork ${agentType} conversation`, { error });
       toast.error(error instanceof Error ? error.message : String(error));
@@ -310,7 +318,7 @@ function AgentConversationDetailContent({
   }, [instanceId]);
 
   const ensureDshCommandConversation = useCallback(async (command: string) => {
-    if (typeKeyRef.current !== 'deepseek-harness') {
+    if (typeKeyRef.current !== 'dsh') {
       throw new Error('This slash command is only available for DSH');
     }
     const currentInstance = instanceRef.current;
@@ -322,7 +330,7 @@ function AgentConversationDetailContent({
       }
       const ensured = await ensureAgentConversationDetailThread({
         instanceId: currentInstance.instanceId,
-        typeKey: 'deepseek-harness',
+        typeKey: 'dsh',
         prompt: command,
         runtimeHandleId: runtimeHandleRef.current,
       });
@@ -375,7 +383,7 @@ function AgentConversationDetailContent({
 
   const submit = useCallback(async () => {
     const composer = composerControllerRef.current;
-    const images = composerImagesControllerRef.current;
+    const images = composerAttachmentsControllerRef.current;
     const currentInstance = instanceRef.current;
     if (!composer || !images || !currentInstance) return;
     const isDisposed = () => destroyedRef.current || composerControllerRef.current !== composer;
@@ -397,7 +405,9 @@ function AgentConversationDetailContent({
             content: snapshot.prompt,
             agentType: currentInstance.agentType,
             isFirstMessage: true,
-            attachments: createAgentMessageAttachments(snapshot.images.map((image) => image.path)),
+            attachments: createAgentMessageAttachments(
+              snapshot.attachments.filter(isAgentThreadCardImageAttachment),
+            ),
           });
           userMessage.id = completedRunUserMessageId(currentInstance.agentType, runId);
           userMessage.renderKey = userMessage.id;
@@ -465,7 +475,6 @@ function AgentConversationDetailContent({
     composerMount.append(composerParts.composer);
     const {
       composer,
-      composerImages,
       composerActions,
       composerRoleIcon: composerRoleButton,
       input,
@@ -516,10 +525,9 @@ function AgentConversationDetailContent({
         persistDetailDraft(instanceId, draft);
       },
     });
-    const composerImagesController = new ComposerImageController({
+    const composerAttachmentsController = new ComposerAttachmentController({
       input,
-      container: composerImages,
-      initialImages: [],
+      initialAttachments: [],
       onChange: () => undefined,
       onStateChange: () => composerControllerRef.current?.setSendButtonState(),
       onError: (message) => toast.error(message),
@@ -574,7 +582,7 @@ function AgentConversationDetailContent({
       t: (key) => tRef.current(key),
         createThreadCacheSkeleton: () => createThreadCacheSkeleton(tRef.current('editor.threadCard.loadingThreadCache')),
         createExternalAgentEmptySettings: () =>
-          externalSettings.createEmptySettings({ showControls: false }),
+          externalSettings.createEmptySettings({ presentation: "expanded" }),
         onForkMessage: forkFromMessage,
       },
       composerOptions: {
@@ -584,11 +592,20 @@ function AgentConversationDetailContent({
         getUserHistoryMessages: () => getAgentThreadCardUserHistoryMessagesFromMessages(messagesRef.current),
         getSendLabel: (label) => tRef.current(`editor.threadCard.${label}`),
         getRuntimeState: composerRuntimeState,
-        getHasAttachments: () => composerImagesController.hasImages,
-        getHasPendingAttachments: () => composerImagesController.hasPending,
+        getHasAttachments: () => composerAttachmentsController.hasAttachments,
+        getHasPendingAttachments: () => composerAttachmentsController.hasPending,
         agentType: typeKeyRef.current,
+        getSkillsScopeId: () => {
+          const current = instanceRef.current;
+          const runtime = current?.runtimeConfig;
+          return runtime?.notebookId
+            ?? runtime?.workspaceSnapshot?.notebookId
+            ?? current?.source.notebookId
+            ?? runtime?.workspaceSnapshot?.notebookPath
+            ?? runtime?.cwd;
+        },
         listDshSkills: async () => {
-          if (typeKeyRef.current !== 'deepseek-harness') return [];
+          if (typeKeyRef.current !== 'dsh') return [];
           const ensured = await ensureDshCommandConversation('/skill');
           return listDshSkills({
             threadId: ensured.threadId,
@@ -632,6 +649,9 @@ function AgentConversationDetailContent({
     });
     messageController = surface.messages;
     const composerController = surface.composer;
+    composerAttachmentsController.connectDocument(
+      new ComposerAttachmentDocument(composerController.editorInstance),
+    );
     const notePicker = new NotePickerController({
       trigger: composerRoleButton,
       popover: rolePopover,
@@ -647,7 +667,7 @@ function AgentConversationDetailContent({
       popover: addPopover,
       notePopover: rolePopover,
       notePicker,
-      images: composerImagesController,
+      attachments: composerAttachmentsController,
       t: (key) => tRef.current(key),
       isDestroyed: () => destroyedRef.current,
       openNotebookAgentSettings: () => {
@@ -672,7 +692,7 @@ function AgentConversationDetailContent({
     messagesControllerRef.current = messageController;
     composerControllerRef.current = composerController;
     surfaceRef.current = surface;
-    composerImagesControllerRef.current = composerImagesController;
+    composerAttachmentsControllerRef.current = composerAttachmentsController;
     addMenuRef.current = addMenu;
     composerController.updateMultiLineState();
     // Paint the selected thread's initial state in the same layout pass. The
@@ -686,7 +706,7 @@ function AgentConversationDetailContent({
       body.removeEventListener('click', handleMessageLinkClick);
       composerController.flushPendingDraft();
       surface.dispose();
-      composerImagesController.dispose();
+      composerAttachmentsController.dispose();
       notePicker.dispose();
       addMenu.dispose();
       externalSettings.dispose();
@@ -698,7 +718,7 @@ function AgentConversationDetailContent({
       messagesControllerRef.current = null;
       composerControllerRef.current = null;
       surfaceRef.current = null;
-      composerImagesControllerRef.current = null;
+      composerAttachmentsControllerRef.current = null;
       addMenuRef.current = null;
       pendingFirstMessageRef.current = null;
     };
@@ -742,7 +762,10 @@ function AgentConversationDetailContent({
   );
 
   return (
-    <section className="agent-conversation-detail markdown-editor flex h-full min-h-0 flex-col">
+    <section
+      className="agent-conversation-detail agent-conversation-surface markdown-editor flex h-full min-h-0 flex-col"
+      style={getAgentMessageTypographyCssVars(messageFontMode, messageSizeMode) as CSSProperties}
+    >
       <div ref={domRef} className="agent-thread-card agent-conversation-detail__card flex min-h-0 flex-1 flex-col">
         <div className="agent-conversation-detail__body-shell" data-no-context-menu-scroll>
           {document.documentElement.dataset.platform === 'mac' ? (
@@ -781,34 +804,74 @@ function AgentConversationDetailContent({
                 tone="agent"
                 message={(
                   <span className="flex flex-col items-center gap-3">
-                    <span>{t('status.agent.loadHistoryFailed')}</span>
-                    {initialHistoryError && (
-                      <span className="max-w-xl break-words text-center text-xs text-[var(--muted-foreground)]">
-                        {initialHistoryError}
-                      </span>
+                    <span>{missingSession ? t('status.agent.historySessionNotFound') : t('status.agent.loadHistoryFailed')}</span>
+                    {missingSession ? (
+                      <Button
+                        variant="outline"
+                        size="sm"
+                        className="rounded-lg"
+                        onClick={() => {
+                          const notebookId = instance.source.notebookId ?? selectedNotebookId;
+                          if (notebookId) createAndOpenAgentConversation(instance.agentType, notebookId);
+                        }}
+                        disabled={!instance.source.notebookId && !selectedNotebookId}
+                      >
+                        {t('status.agent.newConversation')}
+                      </Button>
+                    ) : (
+                      <Button
+                        variant="outline"
+                        size="sm"
+                        className="rounded-lg"
+                        onClick={() => {
+                          if (threadId) void useAgentSessionStore.getState().loadMessages(instance.agentType, threadId);
+                        }}
+                      >
+                        {t('error.retry')}
+                      </Button>
                     )}
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      className="rounded-lg"
-                      onClick={() => {
-                        if (threadId) void useAgentSessionStore.getState().loadMessages(instance.agentType, threadId);
-                      }}
-                    >
-                      {t('error.retry')}
-                    </Button>
                   </span>
                 )}
               />
             </div>
           )}
+          {showHistoryWarning && (
+            <div className="absolute inset-x-3 top-3 z-[4] flex items-center justify-center gap-3 rounded-lg border border-[var(--border)] bg-[var(--background)]/95 px-3 py-2 text-xs text-[var(--muted-foreground)] shadow-sm" role="alert">
+              <span>{missingSession ? t('status.agent.historySessionNotFound') : t('status.agent.historyRefreshFailed')}</span>
+              {missingSession ? (
+                <Button
+                  variant="outline"
+                  size="xs"
+                  className="rounded-lg"
+                  onClick={() => {
+                    const notebookId = instance.source.notebookId ?? selectedNotebookId;
+                    if (notebookId) createAndOpenAgentConversation(instance.agentType, notebookId);
+                  }}
+                  disabled={!instance.source.notebookId && !selectedNotebookId}
+                >
+                  {t('status.agent.newConversation')}
+                </Button>
+              ) : (
+                <Button
+                  variant="ghost"
+                  size="xs"
+                  className="rounded-lg"
+                  onClick={() => {
+                    if (threadId) void useAgentSessionStore.getState().loadMessages(instance.agentType, threadId);
+                  }}
+                >
+                  {t('error.retry')}
+                </Button>
+              )}
+            </div>
+          )}
         </div>
         <div className="agent-conversation-detail__composer-stack">
           {instance.agentType === 'codex' && <CodexApprovalQueue threadId={threadId} />}
           <AgentBackgroundTerminals
             threadId={threadId}
-            agentType={instance.agentType === 'codex' ? 'codex' : 'deepseek-harness'}
-            enabled={instance.agentType === 'codex' || instance.agentType === 'deepseek-harness'}
+            agentType={instance.agentType === 'codex' ? 'codex' : 'dsh'}
+            enabled={instance.agentType === 'codex' || instance.agentType === 'dsh'}
             queuedMessages={pendingSteeringMessages.map((message) => ({
               ...message,
               actionsDisabled: !canActOnQueuedMessage(
diff --git a/app/flowix-web/features/agent/components/agent-conversation-identity.tsx b/app/flowix-web/features/agent/components/agent-conversation-identity.tsx
new file mode 100644
index 000000000..f3d6a0e49
--- /dev/null
+++ b/app/flowix-web/features/agent/components/agent-conversation-identity.tsx
@@ -0,0 +1,166 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { AgentTypeKey } from '@/types/agent';
+import { useI18n } from '@/lib/i18n';
+import { useTitleEditCaret } from '@shared/hooks/use-title-edit-caret';
+import { getAgentType } from '@/lib/agent-types';
+import { useAgentDataStore } from '@features/agent/store/agent-data-store';
+import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
+import { AgentIcon } from '@features/agent/components/agent-icon';
+import { BadgeHoverCard } from '@features/agent/thread-card/badge-hover-card';
+import { computeAgentThreadCardBadgeData } from '@features/agent/thread-card/runtime/run-status-presenter';
+import { createRuntimeInfoRequester } from '@features/agent/thread-card/runtime/runtime-info-requester';
+import { getResolvedExternalSessionId } from '@features/agent/services/external-agent-runtime-service';
+import { getAgentConversationRuntimeCwd } from '@features/agent/conversation-presentation';
+
+export interface AgentConversationIdentityProps {
+  instanceId: string | null;
+  title: string;
+  typeKey: AgentTypeKey;
+  threadId?: string | null;
+  sessionId?: string | null;
+  cwd?: string;
+  renameRequest?: number;
+  className?: string;
+}
+
+/** Shared Agent icon, runtime badge, conversation title, and title editing. */
+export function AgentConversationIdentity({
+  instanceId,
+  title: fallbackTitle,
+  typeKey: fallbackTypeKey,
+  threadId: fallbackThreadId,
+  sessionId: fallbackSessionId,
+  cwd: fallbackCwd,
+  renameRequest = 0,
+  className = '',
+}: AgentConversationIdentityProps) {
+  const { t } = useI18n();
+  const instance = useAgentSessionStore((state) =>
+    instanceId ? state.getInstance(instanceId) : null,
+  );
+  const threadId = instance?.threadId ?? fallbackThreadId ?? null;
+  const projection = useAgentSessionStore((state) =>
+    threadId ? state.threadProjections[threadId] : undefined,
+  );
+  const codexModel = useAgentDataStore((state) => state.agents.codex.user.model?.id ?? 'inherit');
+  const piCodeMode = useAgentDataStore((state) => state.agents.pi.user.mode === 'code');
+  const [isEditingTitle, setIsEditingTitle] = useState(false);
+  const [titleDraft, setTitleDraft] = useState('');
+  const lastRenameRequest = useRef(renameRequest);
+  const { inputRef: titleInputRef, captureCaret } = useTitleEditCaret(isEditingTitle);
+
+  const typeKey = instance?.agentType ?? fallbackTypeKey;
+  const title = instance?.title?.trim() || fallbackTitle || t('common.untitled');
+  const productThreadId = threadId ?? '';
+  const sessionId = instance?.providerSessionId ?? fallbackSessionId ?? (
+    productThreadId ? getResolvedExternalSessionId(productThreadId) : null
+  );
+  const cwd = getAgentConversationRuntimeCwd(instance) ?? fallbackCwd;
+  const agent = getAgentType(typeKey);
+
+  const badgeData = useMemo(() => computeAgentThreadCardBadgeData({
+    threadState: projection ? {
+      lastRun: projection.runs.lastRun,
+      activeRunId: projection.runs.activeRunId,
+      runs: projection.runs.runs,
+    } : undefined,
+    codexModel,
+    typeKey,
+  }), [codexModel, projection, typeKey]);
+
+  useEffect(() => {
+    if (lastRenameRequest.current === renameRequest) return;
+    lastRenameRequest.current = renameRequest;
+    setTitleDraft(title);
+    setIsEditingTitle(true);
+  }, [renameRequest, title]);
+
+  const commitTitle = () => {
+    const nextTitle = titleDraft.trim();
+    if (nextTitle && nextTitle !== title && instanceId) {
+      void useAgentSessionStore.getState().renameAgentConversation({
+        instanceId,
+        threadId,
+        title: nextTitle,
+        typeKey,
+      });
+    }
+    setIsEditingTitle(false);
+  };
+
+  return (
+    <div className={`agent-conversation-identity ${className}`.trim()} data-tauri-drag-region>
+      <span className="agent-conversation-identity__badge-anchor">
+        <BadgeHoverCard
+          threadId={productThreadId || undefined}
+          sessionId={sessionId ?? undefined}
+          runId={badgeData.runId}
+          model={badgeData.model}
+          usage={badgeData.usage}
+          onRequestRuntimeInfo={createRuntimeInfoRequester(
+            typeKey,
+            () => {
+              const current = instanceId
+                ? useAgentSessionStore.getState().getInstance(instanceId)
+                : null;
+              return current?.threadId ?? fallbackThreadId;
+            },
+            () => {
+              const current = instanceId
+                ? useAgentSessionStore.getState().getInstance(instanceId)
+                : null;
+              const currentThreadId = current?.threadId ?? fallbackThreadId;
+              return current?.providerSessionId ?? fallbackSessionId ?? (
+                currentThreadId ? getResolvedExternalSessionId(currentThreadId) : null
+              );
+            },
+          )}
+          agentType={typeKey}
+          piMode={typeKey === 'pi' ? (piCodeMode ? 'code' : 'writing') : undefined}
+          cwd={cwd}
+        />
+        <span className="agent-type-badge shrink-0" aria-hidden="true" title={agent.desc}>
+          <AgentIcon typeKey={agent.id} alt="" className="agent-type-badge__icon" />
+        </span>
+      </span>
+      {isEditingTitle ? (
+        <div className="agent-conversation-identity__title-wrap">
+          <input
+            ref={titleInputRef}
+            value={titleDraft}
+            aria-label={t('agent.chat.conversation.rename')}
+            className="agent-conversation-identity__title-input"
+            onChange={(event) => setTitleDraft(event.target.value)}
+            onBlur={commitTitle}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' && (event.nativeEvent.isComposing || event.keyCode === 229)) return;
+              if (event.key === 'Enter') {
+                event.preventDefault();
+                commitTitle();
+              }
+              if (event.key === 'Escape') setIsEditingTitle(false);
+            }}
+          />
+        </div>
+      ) : (
+        <span
+          className="agent-conversation-identity__title"
+          onPointerDown={(event) => event.stopPropagation()}
+          onMouseDown={(event) => event.stopPropagation()}
+          onClick={(event) => event.stopPropagation()}
+          onDoubleClick={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            captureCaret(event.currentTarget, event.clientX, event.clientY);
+            setTitleDraft(title);
+            setIsEditingTitle(true);
+          }}
+        >
+          {title}
+        </span>
+      )}
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/agent/components/agent-conversation-list.tsx b/app/flowix-web/features/agent/components/agent-conversation-list.tsx
index 50804c2c5..18b8bfcbf 100644
--- a/app/flowix-web/features/agent/components/agent-conversation-list.tsx
+++ b/app/flowix-web/features/agent/components/agent-conversation-list.tsx
@@ -11,24 +11,21 @@ import {
 import { MessageCirclePlus, MoreHorizontal } from 'lucide-react';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
 import type { AgentConversationInstance } from '@features/agent/store/agent-conversation-types';
-import { createAndOpenAgentConversation } from '@features/agent/public/shell-api';
+import {
+  createAndOpenAgentConversation,
+  requestNewConversationAgentSelection,
+} from '@features/agent/use-cases/new-conversation';
 import { useWorkspaceRestoreStore } from '@features/workspace/store/workspace-restore-store';
-import { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
-import { openBrowserColumnAgentConversation } from '@features/workspace/use-cases/browser-column-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { isAgentConversationRunning } from '@features/agent/store/conversation-run-index';
-import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
+import { useNewConversationAgentSelection } from '@features/agent/hooks/use-new-conversation-agent-selection';
 import {
   AGENT_TYPES,
   getAgentType,
   isAgentTypeSelectable,
-  isAlwaysVisibleNewConversationAgent,
 } from '@/lib/agent-types';
-import type { AgentTypeKey } from '@/types/agent';
-import {
-  isAgentRuntimeInstalledState,
-  normalizeAgentRuntimeStatus,
-} from '@features/agent/runtime/agent-runtime-status';
+import type { AgentType, AgentTypeKey } from '@/types/agent';
 import { formatTimeAgo } from '@/lib/format-time-ago';
 import { createLogger } from '@/lib/logger';
 import { toast } from '@/lib/toast';
@@ -41,8 +38,8 @@ import {
 import { useI18n } from '@/lib/i18n';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
 import {
-  ListSurfaceInlineLoadingState,
   ListSurfaceLoadingState,
+  ListSurfaceSpinner,
   ListSurfaceViewport,
 } from '@shared/ui/list-surface';
 import {
@@ -125,9 +122,6 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
   // Rows can therefore read their running state in O(1) without rebuilding an
   // index by scanning every loaded conversation.
   const conversationRunIndex = useAgentSessionStore((state) => state.threadRunSignatures);
-  const agentRuntimeStatusByType = useAgentRuntimeStore((state) => state.statusByType);
-  const agentRuntimeIsChecking = useAgentRuntimeStore((state) => state.isChecking);
-  const refreshAgentRuntimeIfStale = useAgentRuntimeStore((state) => state.refreshIfStale);
   const currentNotebookId = useNoteStore((state) => state.selectedNotebook?.id ?? null);
   const selectedInstanceId = useWorkspaceRestoreStore(
     (state) => state.agentConversation.selectedInstanceId,
@@ -181,17 +175,6 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
     setShowScrollTopHint(false);
   }, [isActive]);
 
-  useEffect(() => {
-    const handleOpenCreateMenu = () => setNewConversationMenuOpen(true);
-    window.addEventListener('flowix:open-agent-create-menu', handleOpenCreateMenu);
-    return () => window.removeEventListener('flowix:open-agent-create-menu', handleOpenCreateMenu);
-  }, []);
-
-  useEffect(() => {
-    if (!newConversationMenuOpen) return;
-    void refreshAgentRuntimeIfStale();
-  }, [newConversationMenuOpen, refreshAgentRuntimeIfStale]);
-
   const toggleFavorite = useCallback((instanceId: string) => {
     setFavoriteIds(toggleFavoriteConversation(instanceId));
     setOpenMenuId(null);
@@ -299,8 +282,8 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
     const counts = new Map<AgentTypeKey, number>();
     if (Object.keys(agentTypeCounts).length > 0) {
       for (const type of AGENT_TYPES) {
-        const count = agentTypeCounts[type.key];
-        if (count && isAgentTypeSelectable(type.key)) counts.set(type.key, count);
+        const count = agentTypeCounts[type.id];
+        if (count && isAgentTypeSelectable(type.id)) counts.set(type.id, count);
       }
     } else {
       for (const instance of scopedConversations) {
@@ -309,14 +292,14 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
       }
     }
     return AGENT_TYPES
-      .filter((type) => counts.has(type.key))
-      .map((type) => ({ type, count: counts.get(type.key) ?? 0 }));
+      .filter((type) => counts.has(type.id))
+      .map((type) => ({ type, count: counts.get(type.id) ?? 0 }));
   }, [agentTypeCounts, scopedConversations]);
 
   // 对话可能在筛选期间变成空集 (例如全部删除) ── 若当前筛选的类型已不再激活，
   // 自动回退到"全部"，避免列表卡在空状态。
   const effectiveFilter: AgentTypeKey | null =
-    filterType && activeAgentTypes.some((entry) => entry.type.key === filterType)
+    filterType && activeAgentTypes.some((entry) => entry.type.id === filterType)
       ? filterType
       : null;
 
@@ -412,20 +395,16 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
     }
   };
 
-  const displayName = (type: (typeof AGENT_TYPES)[number]): string =>
+  const displayName = (type: AgentType): string =>
     type.nameKey ? t(type.nameKey as Parameters<typeof t>[0]) : type.name;
 
-  const newConversationAgentTypes = useMemo(
-    () => AGENT_TYPES.filter((type) => {
-      if (!isAgentTypeSelectable(type.key)) return false;
-      if (isAlwaysVisibleNewConversationAgent(type.key)) return true;
-      return isAgentRuntimeInstalledState(normalizeAgentRuntimeStatus(
-        agentRuntimeStatusByType[type.key],
-        agentRuntimeIsChecking,
-      ));
-    }),
-    [agentRuntimeIsChecking, agentRuntimeStatusByType],
-  );
+  const newConversationSelection = useNewConversationAgentSelection();
+
+  useEffect(() => {
+    if (newConversationMenuOpen && newConversationSelection.kind !== 'choose') {
+      setNewConversationMenuOpen(false);
+    }
+  }, [newConversationMenuOpen, newConversationSelection]);
 
   const prepareConversation = useCallback((instance: AgentConversationInstance) => {
     // The durable list snapshot may arrive before the Zustand session store
@@ -456,19 +435,18 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
 
     prepareConversation(instance);
 
-    await selectAndOpenAgentConversation(instance.instanceId);
+    await openWorkspaceSurface({ target: { kind: 'agent-conversation', instanceId: instance.instanceId } });
   }, [markThreadRead, prepareConversation]);
 
   const openConversationInBrowserColumn = useCallback((instance: AgentConversationInstance) => {
     prepareConversation(instance);
-    void openBrowserColumnAgentConversation(instance.instanceId).catch((error) => {
+    void openWorkspaceSurface({ host: 'browser-column', target: { kind: 'agent-conversation', instanceId: instance.instanceId } }).catch((error) => {
       logger.error('Failed to open conversation in browser column', { error });
       toast.error(error instanceof Error ? error.message : String(error));
     });
   }, [prepareConversation]);
 
-  // 独立对话没有文档来源，但归属当前选中的
-  // notebook。notebook 未选中时不可新建 (cwd 无法解析到笔记本路径)。
+  // 独立对话没有文档来源，但归属当前选中的 notebook。
   const createConversation = useCallback(
     (typeKey: AgentTypeKey) => {
       if (!currentNotebookId) return;
@@ -477,6 +455,21 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
     [currentNotebookId],
   );
 
+  const requestNewConversation = useCallback(() => {
+    const selection = requestNewConversationAgentSelection();
+    if (selection.kind === 'create') {
+      createConversation(selection.agentType);
+      setNewConversationMenuOpen(false);
+      return;
+    }
+    setNewConversationMenuOpen(selection.kind === 'choose');
+  }, [createConversation]);
+
+  useEffect(() => {
+    window.addEventListener('flowix:open-agent-create-menu', requestNewConversation);
+    return () => window.removeEventListener('flowix:open-agent-create-menu', requestNewConversation);
+  }, [requestNewConversation]);
+
   return (
     <section className="relative flex h-full min-h-0 flex-1 flex-col bg-[var(--list-bg)]" aria-label={t('memo.navigation.conversations')}>
       {/* 标题行 ── 与 MemoList / FolderFileTree 共用同一套中间列头部结构:
@@ -493,19 +486,19 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
                 aria-label={t('document.agent.filterByAgent')}
               >
                 {activeAgentTypes.map(({ type, count }) => {
-                  const active = effectiveFilter === type.key;
+                  const active = effectiveFilter === type.id;
                   const label = t('document.agent.filterByAgentCount', {
                     name: displayName(type),
                     count,
                   });
                   return (
                     <button
-                      key={type.key}
+                      key={type.id}
                       type="button"
                       aria-pressed={active}
                       title={label}
                       aria-label={label}
-                      onClick={() => setFilterType((prev) => (prev === type.key ? null : type.key))}
+                      onClick={() => setFilterType((prev) => (prev === type.id ? null : type.id))}
                       className={cn(
                         'flex h-4 w-4 shrink-0 items-center justify-center rounded-full border transition-colors',
                         active
@@ -513,7 +506,7 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
                           : 'border-[var(--border)] opacity-20 hover:opacity-100',
                       )}
                     >
-                      <AgentIcon typeKey={type.key} alt="" className="h-full w-full object-contain" />
+                      <AgentIcon typeKey={type.id} alt="" className="h-full w-full object-contain" />
                     </button>
                   );
                 })}
@@ -523,12 +516,15 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
           <div className="flex items-center gap-1 shrink-0">
             <DropdownMenu
               open={newConversationMenuOpen}
-              onOpenChange={setNewConversationMenuOpen}
+              onOpenChange={(open) => {
+                if (open) requestNewConversation();
+                else setNewConversationMenuOpen(false);
+              }}
             >
               <DropdownMenuTrigger asChild>
                 <button
                   type="button"
-                  disabled={!currentNotebookId}
+                  disabled={!currentNotebookId || newConversationSelection.kind === 'none'}
                   aria-label={t('agent.chat.newThread')}
                   title={currentNotebookId ? t('agent.chat.newThread') : t('memo.list.selectNotebook')}
                   className="group flex h-[30px] w-[30px] shrink-0 items-center justify-center rounded-xl border border-[var(--border)] bg-[var(--card)] p-0 text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] disabled:cursor-not-allowed disabled:opacity-40"
@@ -543,27 +539,16 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
                 <DropdownMenuLabel className="flex items-center gap-1.5 px-[0.375rem] pb-[0.35rem] pt-[0.35rem] text-xs font-normal leading-[1.2] text-[var(--muted-foreground)]">
                   {t('agent.chat.newThread')}
                 </DropdownMenuLabel>
-                {newConversationAgentTypes.map((type) => {
-                  const runtimeStatus = normalizeAgentRuntimeStatus(
-                    agentRuntimeStatusByType[type.key],
-                    agentRuntimeIsChecking,
-                  );
-                  const showNotInstalled = isAlwaysVisibleNewConversationAgent(type.key)
-                    && runtimeStatus.state === 'not-installed';
+                {newConversationSelection.options.map((type) => {
                   return (
                     <DropdownMenuItem
-                      key={type.key}
+                      key={type.id}
                       disabled={!currentNotebookId}
-                      onClick={() => createConversation(type.key)}
+                      onClick={() => createConversation(type.id)}
                       className="agent-conversation-new-agent-item group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
                     >
-                      <AgentIcon typeKey={type.key} alt="" className="h-4 w-4 shrink-0 object-contain" />
+                      <AgentIcon typeKey={type.id} alt="" className="h-4 w-4 shrink-0 object-contain" />
                       <span className="min-w-0 flex-1 truncate">{displayName(type)}</span>
-                      {showNotInstalled && (
-                        <span className="shrink-0 text-xs text-[var(--muted-foreground)] group-hover:text-[var(--primary-foreground)]">
-                          {t('agent.status.notInstalled')}
-                        </span>
-                      )}
                     </DropdownMenuItem>
                   );
                 })}
@@ -579,11 +564,11 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
           onScroll={handleListScroll}
         >
           {isLoading && scopedConversations.length === 0 ? (
-            <ListSurfaceLoadingState label={t('status.agent.loadingConversations')} />
+            <ListSurfaceLoadingState ariaLabel={t('status.agent.loadingConversations')} />
           ) : loadError && scopedConversations.length === 0 ? (
             <div className="flex h-full min-h-0 w-full flex-col items-center justify-center gap-3 px-4 text-center text-sm text-[var(--muted-foreground)]" role="alert">
               <span>{t('status.agent.loadConversationsFailed')}</span>
-              <Button size="sm" onClick={retryFirstPage}>{t('error.retry')}</Button>
+              <Button size="sm" className="rounded-lg" onClick={retryFirstPage}>{t('error.retry')}</Button>
             </div>
           ) : scopedConversations.length === 0 ? (
             <div className="flex h-full w-full items-center justify-center px-4 text-center text-sm text-[var(--muted-foreground)]">
@@ -595,13 +580,15 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
               loadError ? (
                 <div className="flex items-center justify-center gap-2 px-2 py-1 text-xs text-[var(--muted-foreground)]" role="alert">
                   <span>{t('status.agent.loadConversationsFailed')}</span>
-                  <Button size="xs" variant="ghost" onClick={retryFirstPage}>{t('error.retry')}</Button>
+                  <Button size="xs" variant="ghost" className="rounded-lg" onClick={retryFirstPage}>{t('error.retry')}</Button>
                 </div>
               ) : (
-                <ListSurfaceInlineLoadingState
-                  label={t('status.agent.loadingConversations')}
-                  className="py-1"
-                />
+                <div className="flex items-center justify-center px-2 py-1">
+                  <ListSurfaceSpinner
+                    className="h-3.5 w-3.5"
+                    ariaLabel={t('status.agent.loadingConversations')}
+                  />
+                </div>
               )
             )}
             <div className="relative min-h-full" style={{ height: totalSize }}>
@@ -624,12 +611,16 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
 
                 if (item.kind === 'loading') {
                   return (
-                    <ListSurfaceInlineLoadingState
+                    <div
                       key={item.key}
-                      label={t('status.agent.loadingMoreConversations')}
-                      className="absolute inset-x-0 top-0"
+                      className="absolute inset-x-0 top-0 flex items-center justify-center"
                       style={{ height: size, transform: `translateY(${start}px)` }}
-                    />
+                    >
+                      <ListSurfaceSpinner
+                        className="h-3.5 w-3.5"
+                        ariaLabel={t('status.agent.loadingMoreConversations')}
+                      />
+                    </div>
                   );
                 }
 
@@ -642,7 +633,7 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
                       role="alert"
                     >
                       <span>{t('status.agent.loadConversationsFailed')}</span>
-                      <Button size="xs" variant="ghost" onClick={() => void loadMoreConversations(true)}>{t('error.retry')}</Button>
+                      <Button size="xs" variant="ghost" className="rounded-lg" onClick={() => void loadMoreConversations(true)}>{t('error.retry')}</Button>
                     </div>
                   );
                 }
@@ -674,7 +665,7 @@ export function AgentConversationList({ isActive = true }: AgentConversationList
                           'relative flex h-4 w-4 shrink-0 items-center justify-center rounded-full',
                           running && 'agent-conversation-list__icon--running',
                         )}>
-                          <AgentIcon typeKey={agent.key} alt="" className="h-4 w-4 object-contain" />
+                          <AgentIcon typeKey={agent.id} alt="" className="h-4 w-4 object-contain" />
                           {(running || (!!instance.threadId
                             && latestCompletedRunIds[instance.threadId] !== readThroughRunIds[instance.threadId]
                             && !(conversationDetailOpen && selectedInstanceId === instance.instanceId))) && (
diff --git a/app/flowix-web/features/agent/components/agent-conversation-more-menu.tsx b/app/flowix-web/features/agent/components/agent-conversation-more-menu.tsx
new file mode 100644
index 000000000..64913d400
--- /dev/null
+++ b/app/flowix-web/features/agent/components/agent-conversation-more-menu.tsx
@@ -0,0 +1,136 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { MoreHorizontal } from 'lucide-react';
+import {
+  ArchiveIcon,
+  PencilSimpleIcon,
+  SquareSplitHorizontalIcon,
+  StarIcon,
+  TrashSimpleIcon,
+} from '@phosphor-icons/react';
+import { useI18n } from '@/lib/i18n';
+import { toast } from '@/lib/toast';
+import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
+import type { AgentConversationInstance } from '@features/agent/store/agent-conversation-types';
+import { AgentMessageFontSwitcher, useAgentMessageFontSwitch } from '@features/agent/components/agent-message-font-switcher';
+import {
+  isFavoriteConversation,
+  subscribeToFavoriteConversationChanges,
+  toggleFavoriteConversation,
+} from '@features/agent/conversation-favorites';
+import { openBrowserColumnAgentConversation } from '@features/workspace/use-cases/browser-column-navigation';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@shared/ui/dropdown-menu';
+
+const itemClass = 'group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]';
+
+/** Shared Agent conversation actions used by both dedicated and fullscreen embedded conversations. */
+export function AgentConversationMoreMenu({
+  instance,
+  iconButtonClass,
+  onRename,
+}: {
+  instance: AgentConversationInstance;
+  iconButtonClass: string;
+  onRename: () => void;
+}) {
+  const { t } = useI18n();
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label={t('document.agent.moreActions')}
+          title={t('document.agent.moreActions')}
+          className={`${iconButtonClass} [-webkit-app-region:no-drag]`}
+        >
+          <MoreHorizontal className="h-4 w-4" aria-hidden="true" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-[202px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+        <AgentConversationMoreMenuItems instance={instance} onRename={onRename} />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+export function AgentConversationMoreMenuItems({
+  instance,
+  onRename,
+}: {
+  instance: AgentConversationInstance;
+  onRename: () => void;
+}) {
+  const { t } = useI18n();
+  const fontSwitch = useAgentMessageFontSwitch();
+  const [isFavorite, setIsFavorite] = useState(() => isFavoriteConversation(instance.instanceId));
+
+  useEffect(() => {
+    setIsFavorite(isFavoriteConversation(instance.instanceId));
+    return subscribeToFavoriteConversationChanges(() => {
+      setIsFavorite(isFavoriteConversation(instance.instanceId));
+    });
+  }, [instance.instanceId]);
+
+  const removeConversation = async (action: 'archive' | 'delete') => {
+    if (action === 'delete' && !window.confirm(t('agent.chat.conversation.deleteConfirm'))) return;
+    try {
+      const session = useAgentSessionStore.getState();
+      if (instance.threadId) {
+        await (action === 'archive'
+          ? session.archiveThread(instance.threadId)
+          : session.deleteThread(instance.threadId));
+      } else {
+        session.removeInstance(instance.instanceId);
+      }
+      toast.success(t(action === 'archive' ? 'status.agent.archiveSuccess' : 'status.agent.deleteSuccess'));
+    } catch (error) {
+      toast.error(error instanceof Error
+        ? error.message
+        : t(action === 'archive' ? 'status.agent.archiveFailed' : 'status.agent.deleteFailed'));
+    }
+  };
+
+  return (
+    <>
+      <AgentMessageFontSwitcher
+        fontMode={fontSwitch.fontMode}
+        sizeMode={fontSwitch.sizeMode}
+        downloadingMode={fontSwitch.downloadingMode}
+        percent={fontSwitch.percent}
+        onSelect={fontSwitch.selectFontMode}
+      />
+      <DropdownMenuItem
+        onClick={() => void openBrowserColumnAgentConversation(instance.instanceId).catch((error) =>
+          toast.error(error instanceof Error ? error.message : String(error)))}
+        className={itemClass}
+      >
+        <SquareSplitHorizontalIcon className="h-4 w-4" /> {t('workColumn.context.openInBrowserColumn')}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        onClick={() => setIsFavorite(toggleFavoriteConversation(instance.instanceId).has(instance.instanceId))}
+        className={itemClass}
+      >
+        <StarIcon className="h-4 w-4" weight={isFavorite ? 'fill' : 'regular'} />
+        {isFavorite ? t('agent.chat.conversation.unfavorite') : t('agent.chat.conversation.favorite')}
+      </DropdownMenuItem>
+      <DropdownMenuItem onClick={onRename} className={itemClass}>
+        <PencilSimpleIcon className="h-4 w-4" /> {t('agent.chat.conversation.rename')}
+      </DropdownMenuItem>
+      <DropdownMenuItem onClick={() => void removeConversation('archive')} className={itemClass}>
+        <ArchiveIcon className="h-4 w-4" /> {t('document.agent.archiveConversation')}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        onClick={() => void removeConversation('delete')}
+        className="group h-7 items-center gap-2 rounded-lg px-2 py-0 hover:bg-transparent hover:text-[var(--destructive)]"
+      >
+        <TrashSimpleIcon className="h-4 w-4" /> {t('document.agent.deleteConversation')}
+      </DropdownMenuItem>
+    </>
+  );
+}
diff --git a/app/flowix-web/features/agent/components/agent-conversation-status-bar.tsx b/app/flowix-web/features/agent/components/agent-conversation-status-bar.tsx
index b684e8374..83d1ad6cf 100644
--- a/app/flowix-web/features/agent/components/agent-conversation-status-bar.tsx
+++ b/app/flowix-web/features/agent/components/agent-conversation-status-bar.tsx
@@ -8,7 +8,7 @@ import {
   type ConversationRunSummary,
 } from '@features/agent/store/conversation-run-index';
 import { useWorkspaceRestoreStore } from '@features/workspace/store/workspace-restore-store';
-import { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { getAgentType } from '@/lib/agent-types';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
@@ -87,7 +87,7 @@ export function AgentConversationStatusBar() {
 
   const openConversation = useCallback((instance: AgentConversationInstance) => {
     if (instance.threadId) markThreadRead(instance.threadId);
-    void selectAndOpenAgentConversation(instance.instanceId).catch((error) => {
+    void openWorkspaceSurface({ target: { kind: 'agent-conversation', instanceId: instance.instanceId } }).catch((error) => {
       toast.error(error instanceof Error ? error.message : t('status.agent.conversationNotFound'));
     });
   }, [markThreadRead, t]);
@@ -130,7 +130,7 @@ export function AgentConversationStatusBar() {
               aria-label={title}
             >
               <AgentIcon
-                typeKey={agent.key}
+                typeKey={agent.id}
                 alt=""
                 className="h-3.5 w-3.5 object-contain"
               />
diff --git a/app/flowix-web/features/agent/components/agent-conversation-titlebar.tsx b/app/flowix-web/features/agent/components/agent-conversation-titlebar.tsx
index c57f8fb92..c2e7003ac 100644
--- a/app/flowix-web/features/agent/components/agent-conversation-titlebar.tsx
+++ b/app/flowix-web/features/agent/components/agent-conversation-titlebar.tsx
@@ -1,18 +1,12 @@
 'use client';
 
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
 import {
-  ArchiveIcon,
   FileTextIcon,
   LinkBreakIcon,
-  PencilSimpleIcon,
-  SquareSplitHorizontalIcon,
-  StarIcon,
-  TrashSimpleIcon,
 } from '@phosphor-icons/react';
 
-import { useTitleEditCaret } from '@shared/hooks/use-title-edit-caret';
 import { useI18n } from '@/lib/i18n';
 import { isWindowsPlatform } from '@features/shortcuts';
 import { SidebarToggleIcon } from '@shared/icons/sidebar-toggle-icon';
@@ -21,118 +15,23 @@ import {
   DOCUMENT_TITLEBAR_ICON_BUTTON_MAC,
   DOCUMENT_TITLEBAR_ICON_BUTTON_WIN,
 } from '@features/document/components/document-titlebar-shared';
-import { DEFAULT_AGENT_TYPE_KEY, getAgentType } from '@/lib/agent-types';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
-import { openNoteByNotebookPath, openNoteByPhysicalPath } from '@features/memo/use-cases/open-by-target';
-import { openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
+import { openNoteByNotebookPath, openNoteByPhysicalPath } from '@features/memo/public/note-navigation-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { getAgentConversationPresentation } from '@features/agent/conversation-presentation';
-import { AgentIcon } from '@features/agent/components/agent-icon';
-import { BadgeHoverCard } from '@features/agent/thread-card/badge-hover-card';
-import { computeAgentThreadCardBadgeData } from '@features/agent/thread-card/runtime/run-status-presenter';
-import { getResolvedExternalSessionId } from '@features/agent/services/external-agent-runtime-service';
-import { createRuntimeInfoRequester } from '@features/agent/thread-card/runtime/runtime-info-requester';
 import { toast } from '@/lib/toast';
 import { WorkColumnTitlebarShell } from '@features/shell/components/work-column-titlebar-shell';
-import { openBrowserColumnAgentConversation } from '@features/workspace/use-cases/browser-column-navigation';
-import {
-  isFavoriteConversation,
-  subscribeToFavoriteConversationChanges,
-  toggleFavoriteConversation,
-} from '@features/agent/conversation-favorites';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@shared/ui/dropdown-menu';
+import { AgentConversationMoreMenu } from '@features/agent/components/agent-conversation-more-menu';
+import { AgentConversationIdentity } from '@features/agent/components/agent-conversation-identity';
 
 function AgentConversationHeader({ instanceId }: { instanceId: string }) {
   const { t } = useI18n();
   const isWindows = isWindowsPlatform();
   const instance = useAgentSessionStore((state) => state.getInstance(instanceId));
-  const projection = useAgentSessionStore((state) => {
-    const threadId = state.getInstance(instanceId)?.threadId;
-    return threadId ? state.threadProjections[threadId] : undefined;
-  });
-  const codexModel = useAgentSessionStore((state) => state.sessionMeta.settings.agentCodexModel);
-  const piCodeMode = useAgentAccessStore((state) =>
-    state.config.defaults?.runtime?.pi?.piCodeMode ?? false,
-  );
-  const [isEditingTitle, setIsEditingTitle] = useState(false);
-  const { inputRef: titleInputRef, captureCaret: captureTitleCaret } = useTitleEditCaret(isEditingTitle);
-  const [titleDraft, setTitleDraft] = useState('');
-  const [isFavorite, setIsFavorite] = useState(() => isFavoriteConversation(instanceId));
-
-  useEffect(() => {
-    setIsFavorite(isFavoriteConversation(instanceId));
-    return subscribeToFavoriteConversationChanges(() => {
-      setIsFavorite(isFavoriteConversation(instanceId));
-    });
-  }, [instanceId]);
-
-  // archive/delete 由 store 端到端完成 (含 closeAgentConversation), instance
-  // 消失时父级会立刻 unmount 这个组件; 不再渲染兜底空态、不再做"instance 缺
-  // 失时" 的 hooks 防御。
+  const [renameRequest, setRenameRequest] = useState(0);
   const presentation = instance
     ? getAgentConversationPresentation(instance, t('common.untitled'))
     : null;
-  const agent = getAgentType(instance?.agentType ?? DEFAULT_AGENT_TYPE_KEY);
-  const productThreadId = instance?.threadId ?? '';
-  const providerSessionId = instance?.providerSessionId ?? (
-    productThreadId ? getResolvedExternalSessionId(productThreadId) : null
-  );
-
-  const badgeData = useMemo(() => computeAgentThreadCardBadgeData({
-    threadState: projection ? {
-      lastRun: projection.runs.lastRun,
-      activeRunId: projection.runs.activeRunId,
-      runs: projection.runs.runs,
-    } : undefined,
-    codexModel,
-    typeKey: instance?.agentType ?? DEFAULT_AGENT_TYPE_KEY,
-  }), [codexModel, instance?.agentType, projection]);
-
-  const onRemove = useCallback(async (
-    target: NonNullable<typeof instance>,
-    action: 'archive' | 'delete',
-  ) => {
-    if (action === 'delete' && !window.confirm(t('agent.chat.conversation.deleteConfirm'))) return;
-
-    try {
-      const session = useAgentSessionStore.getState();
-      if (target.threadId) {
-        await (action === 'archive'
-          ? session.archiveThread(target.threadId)
-          : session.deleteThread(target.threadId));
-      } else {
-        session.removeInstance(target.instanceId);
-      }
-      toast.success(t(action === 'archive' ? 'status.agent.archiveSuccess' : 'status.agent.deleteSuccess'));
-    } catch (error) {
-      toast.error(
-        error instanceof Error
-          ? error.message
-          : t(action === 'archive' ? 'status.agent.archiveFailed' : 'status.agent.deleteFailed'),
-      );
-    }
-  }, [t]);
-
-  const onOpenInBrowserColumn = useCallback((target: NonNullable<typeof instance>) => {
-    void openBrowserColumnAgentConversation(target.instanceId).catch((error) => {
-      toast.error(error instanceof Error ? error.message : String(error));
-    });
-  }, []);
-
-  const onToggleFavorite = useCallback(() => {
-    const next = toggleFavoriteConversation(instanceId);
-    setIsFavorite(next.has(instanceId));
-  }, [instanceId]);
-
-  const onRename = useCallback((target: NonNullable<typeof instance>) => {
-    setTitleDraft(target.title?.trim() || '');
-    setIsEditingTitle(true);
-  }, []);
 
   const onOpenSourceDocument = useCallback(() => {
     if (!instance || !presentation?.hasSourceDocument) return;
@@ -140,135 +39,57 @@ function AgentConversationHeader({ instanceId }: { instanceId: string }) {
     const open = source?.notebookId && source.relativePath
       ? openNoteByNotebookPath(source.notebookId, source.relativePath)
       : source?.documentPath
-        ? openNoteByPhysicalPath(source.documentPath).catch(() => openExternalTarget(source.documentPath!))
+        ? openNoteByPhysicalPath(source.documentPath).catch(() => openWorkspaceSurface({
+          host: 'main-third',
+          target: { kind: 'external', path: source.documentPath!, scopePath: null, transitionId: null },
+        }).then(() => undefined))
         : Promise.resolve();
     void open.catch(() => toast.error(t('status.agent.originUnavailable')));
   }, [instance, presentation, t]);
 
-  const commitTitle = useCallback(() => {
-    const title = titleDraft.trim();
-    if (title && instance) {
-      void useAgentSessionStore.getState().renameAgentConversation({
-        instanceId: instance.instanceId,
-        threadId: instance.threadId,
-        title,
-        typeKey: instance.agentType,
-      });
-    }
-    setIsEditingTitle(false);
-  }, [instance, titleDraft]);
-
   if (!instance || !presentation) return null;
-  const { hasSourceDocument, runtimeCwd } = presentation;
   const actionButtonClass = isWindows
     ? DOCUMENT_TITLEBAR_ICON_BUTTON_WIN
     : DOCUMENT_TITLEBAR_ICON_BUTTON_MAC;
 
   return (
-    <div
-      data-tauri-drag-region
-      className="relative flex h-full min-w-0 flex-1 items-center gap-2 pl-3"
-    >
-      <span className="agent-thread-card__badge-hover-wrapper shrink-0 [-webkit-app-region:no-drag]">
-        <BadgeHoverCard
-          threadId={productThreadId || undefined}
-          sessionId={providerSessionId ?? undefined}
-          runId={badgeData.runId}
-          model={badgeData.model}
-          usage={badgeData.usage}
-          onRequestRuntimeInfo={createRuntimeInfoRequester(
-            instance.agentType,
-            () => useAgentSessionStore.getState().getInstance(instanceId)?.threadId,
-            () => {
-              const current = useAgentSessionStore.getState().getInstance(instanceId);
-              return current?.providerSessionId ?? (
-                current?.threadId
-                  ? getResolvedExternalSessionId(current.threadId)
-                  : null
-              );
-            },
-          )}
-          agentType={instance.agentType}
-          piMode={instance.agentType === 'pi' ? (piCodeMode ? 'code' : 'writing') : undefined}
-          cwd={runtimeCwd}
-        />
-        <span className="agent-type-badge" aria-hidden="true" title={agent.desc}>
-          <AgentIcon typeKey={agent.key} alt="" className="agent-type-badge__icon" />
-        </span>
-      </span>
-      {isEditingTitle ? (
-        <div className="min-w-0 flex-[0_1_auto] truncate rounded px-0.5 py-1 text-sm font-semibold leading-none text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] focus-within:bg-[var(--muted)] [-webkit-app-region:no-drag]">
-          <input ref={titleInputRef} value={titleDraft}
-            className="agent-thread-card__title-input box-border h-[14px] max-w-full min-w-0 border-0 bg-transparent p-0 font-inherit leading-none text-[var(--foreground)] shadow-none outline-none ring-0 focus:border-0 focus:bg-transparent focus:outline-none focus:ring-0 [-webkit-app-region:no-drag]"
-            onChange={(event) => setTitleDraft(event.target.value)} onBlur={commitTitle}
-            onKeyDown={(event) => {
-              // Enter is also emitted while an IME is confirming its current
-              // candidate. Let the composition finish before allowing the
-              // title editor to commit and blur.
-              if (event.key === 'Enter' && (event.nativeEvent.isComposing || event.keyCode === 229)) return;
-              if (event.key === 'Enter') { event.preventDefault(); commitTitle(); }
-              if (event.key === 'Escape') setIsEditingTitle(false);
-            }} />
-        </div>
-      ) : (
-        <div
-          className="min-w-0 flex-[0_1_auto] truncate rounded px-0.5 py-1 text-sm font-semibold leading-none text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] [-webkit-app-region:no-drag]"
-          onPointerDown={(event) => event.stopPropagation()}
-          onMouseDown={(event) => event.stopPropagation()}
-          onClick={(event) => event.stopPropagation()}
-          onDoubleClick={(event) => {
-            event.preventDefault();
-            event.stopPropagation();
-            captureTitleCaret(event.currentTarget, event.clientX, event.clientY);
-            setTitleDraft(instance.title?.trim() || '');
-            setIsEditingTitle(true);
-          }}
-        >
-          {presentation.title}
-        </div>
-      )}
+    <div className="relative flex h-full min-w-0 flex-1 items-center gap-2 pl-3">
+      <AgentConversationIdentity
+        instanceId={instance.instanceId}
+        title={presentation.title}
+        typeKey={instance.agentType}
+        threadId={instance.threadId}
+        sessionId={instance.providerSessionId}
+        cwd={presentation.runtimeCwd}
+        renameRequest={renameRequest}
+        className="h-full flex-1 pl-0"
+      />
       <div className={`ml-auto flex shrink-0 items-center ${isWindows ? 'gap-2 pr-3' : 'gap-3 pr-3'}`}>
-        {hasSourceDocument ? <>
-            <button type="button" onClick={onOpenSourceDocument} aria-label={t('document.agent.viewInNote')}
-              title={t('document.agent.viewInNote')} className={`${actionButtonClass} [-webkit-app-region:no-drag]`}>
-              <FileTextIcon className="h-4 w-4" />
-            </button>
-          </> : (
-            <span
-              className="agent-thread-card__no-source"
-              role="img"
-              aria-label={t('document.agent.noSourceNote')}
-              title={t('document.agent.noSourceNote')}
-            >
-              <LinkBreakIcon className="agent-thread-card__fullscreen-icon" aria-hidden="true" />
-            </span>
-          )}
-        <DropdownMenu>
-            <DropdownMenuTrigger asChild>
-              <button type="button" aria-label={t('document.agent.moreActions')} title={t('document.agent.moreActions')}
-                className={`${actionButtonClass} [-webkit-app-region:no-drag]`}>
-                <MoreHorizontal className="h-4 w-4" aria-hidden="true" />
-              </button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent align="end" className="w-[180px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-              <DropdownMenuItem onClick={() => onOpenInBrowserColumn(instance)} className="group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]">
-                <SquareSplitHorizontalIcon className="h-4 w-4" /> {t('workColumn.context.openInBrowserColumn')}
-              </DropdownMenuItem>
-              <DropdownMenuItem onClick={onToggleFavorite} className="group h-7 items-center gap-2 rounded-lg px-2 py-0 hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]">
-                <StarIcon className="h-4 w-4" weight={isFavorite ? 'fill' : 'regular'} />
-                {isFavorite ? t('agent.chat.conversation.unfavorite') : t('agent.chat.conversation.favorite')}
-              </DropdownMenuItem>
-              <DropdownMenuItem onClick={() => onRename(instance)} className="group h-7 items-center gap-2 rounded-lg px-2 py-0 hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]">
-                <PencilSimpleIcon className="h-4 w-4" /> {t('agent.chat.conversation.rename')}
-              </DropdownMenuItem>
-              <DropdownMenuItem onClick={() => void onRemove(instance, 'archive')} className="group h-7 items-center gap-2 rounded-lg px-2 py-0 hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]">
-                <ArchiveIcon className="h-4 w-4" /> {t('document.agent.archiveConversation')}
-              </DropdownMenuItem>
-              <DropdownMenuItem onClick={() => void onRemove(instance, 'delete')} className="group h-7 items-center gap-2 rounded-lg px-2 py-0 hover:bg-transparent hover:text-[var(--destructive)]">
-                <TrashSimpleIcon className="h-4 w-4" /> {t('document.agent.deleteConversation')}
-              </DropdownMenuItem>
-            </DropdownMenuContent>
-        </DropdownMenu>
+        {presentation.hasSourceDocument ? (
+          <button
+            type="button"
+            onClick={onOpenSourceDocument}
+            aria-label={t('document.agent.viewInNote')}
+            title={t('document.agent.viewInNote')}
+            className={`${actionButtonClass} [-webkit-app-region:no-drag]`}
+          >
+            <FileTextIcon className="h-4 w-4" />
+          </button>
+        ) : (
+          <span
+            className="agent-thread-card__no-source"
+            role="img"
+            aria-label={t('document.agent.noSourceNote')}
+            title={t('document.agent.noSourceNote')}
+          >
+            <LinkBreakIcon className="agent-thread-card__fullscreen-icon" aria-hidden="true" />
+          </span>
+        )}
+        <AgentConversationMoreMenu
+          instance={instance}
+          iconButtonClass={actionButtonClass}
+          onRename={() => setRenameRequest((request) => request + 1)}
+        />
       </div>
     </div>
   );
diff --git a/app/flowix-web/features/agent/components/agent-icon.tsx b/app/flowix-web/features/agent/components/agent-icon.tsx
index 864e5520f..7a913f447 100644
--- a/app/flowix-web/features/agent/components/agent-icon.tsx
+++ b/app/flowix-web/features/agent/components/agent-icon.tsx
@@ -12,7 +12,7 @@ import { cn } from '@/lib/utils';
 export { isThemeAdaptiveAgentIcon, THEME_ADAPTIVE_AGENT_ICON_KEYS };
 
 const DEFAULT_AGENT_ICON_COLORS: Partial<Record<AgentTypeKey, string>> = {
-  'deepseek-harness': '#484848',
+  dsh: '#484848',
 };
 
 export interface AgentIconProps {
diff --git a/app/flowix-web/features/agent/components/agent-message-font-switcher.tsx b/app/flowix-web/features/agent/components/agent-message-font-switcher.tsx
new file mode 100644
index 000000000..55487533f
--- /dev/null
+++ b/app/flowix-web/features/agent/components/agent-message-font-switcher.tsx
@@ -0,0 +1,84 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { useI18n } from '@/lib/i18n';
+import { toast } from '@/lib/toast';
+import { subscribe } from '@platform/tauri/event-bus';
+import type { FontDownloadProgress } from '@platform/tauri/client/general';
+import { ensureDownloadedFontRegistered } from '@features/preferences/public/font-api';
+import { TypographyFontSwitcher } from '@shared/ui/typography-font-switcher';
+import { FontSizeSwitcher } from '@shared/ui/font-size-switcher';
+import { getTypographyFontId } from '@/lib/typography-font-mode';
+import {
+  useAgentMessageFontStore,
+  type AgentMessageFontMode,
+  type AgentMessageSizeMode,
+} from '@features/agent/store/agent-message-font-store';
+
+export function useAgentMessageFontSwitch() {
+  const { t } = useI18n();
+  const fontMode = useAgentMessageFontStore((state) => state.fontMode);
+  const sizeMode = useAgentMessageFontStore((state) => state.sizeMode);
+  const setFontMode = useAgentMessageFontStore((state) => state.setFontMode);
+  const [downloadingMode, setDownloadingMode] = useState<Exclude<AgentMessageFontMode, 'standard'> | null>(null);
+  const [percent, setPercent] = useState<number | null>(null);
+  const requestId = useRef(0);
+  const downloadingFontId = useRef<string | null>(null);
+
+  useEffect(() => subscribe<FontDownloadProgress>('font-download-progress', (progress) => {
+    if (progress.fontId === downloadingFontId.current) setPercent(progress.percent);
+  }), []);
+
+  useEffect(() => () => {
+    requestId.current += 1;
+    downloadingFontId.current = null;
+  }, []);
+
+  async function selectFontMode(mode: AgentMessageFontMode) {
+    const request = ++requestId.current;
+    const fontId = getTypographyFontId(mode);
+    downloadingFontId.current = mode === 'standard' ? null : fontId;
+    setDownloadingMode(mode === 'standard' ? null : mode);
+    setPercent(null);
+
+    try {
+      if (mode !== 'standard') await ensureDownloadedFontRegistered(fontId);
+      if (requestId.current !== request) return;
+      setFontMode(mode);
+    } catch (error) {
+      if (requestId.current !== request) return;
+      const message = error instanceof Error ? error.message : String(error);
+      toast.error(t('preferences.format.fontDownloadFailed', { message }));
+    } finally {
+      if (requestId.current === request) {
+        downloadingFontId.current = null;
+        setDownloadingMode(null);
+        setPercent(null);
+      }
+    }
+  }
+
+  return { fontMode, sizeMode, downloadingMode, percent, selectFontMode };
+}
+
+export function AgentMessageFontSwitcher({
+  fontMode,
+  sizeMode,
+  downloadingMode,
+  percent,
+  onSelect,
+}: {
+  fontMode: AgentMessageFontMode;
+  sizeMode: AgentMessageSizeMode;
+  downloadingMode: Exclude<AgentMessageFontMode, 'standard'> | null;
+  percent: number | null;
+  onSelect: (mode: AgentMessageFontMode) => void;
+}) {
+  const setSizeMode = useAgentMessageFontStore((state) => state.setSizeMode);
+  return (
+    <div>
+      <TypographyFontSwitcher fontMode={fontMode} downloadingMode={downloadingMode} percent={percent} onSelect={onSelect} />
+      <FontSizeSwitcher sizeMode={sizeMode} onSelect={setSizeMode} />
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/agent/components/agent-runtime-status-list.tsx b/app/flowix-web/features/agent/components/agent-runtime-status-list.tsx
index 76bc46c6c..ed0702e96 100644
--- a/app/flowix-web/features/agent/components/agent-runtime-status-list.tsx
+++ b/app/flowix-web/features/agent/components/agent-runtime-status-list.tsx
@@ -4,8 +4,7 @@ import type { ReactNode } from 'react';
 import { AGENT_TYPES, isAgentTypeComingSoon } from '@/lib/agent-types';
 import { cn } from '@/lib/utils';
 import { useI18n, type I18nKey } from '@/lib/i18n';
-import type { AgentTypeKey } from '@/types/agent';
-import type { AgentRuntimeAvailability } from '@platform/tauri/client';
+import type { AgentRuntimeSnapshot, AgentTypeKey } from '@/types/agent';
 import {
   normalizeAgentRuntimeStatus,
   type AgentRuntimeStatusView,
@@ -14,7 +13,7 @@ import { Button } from '@shared/ui/button';
 import { useAgentVisibilityPreferences } from '@features/preferences/public/runtime-api';
 import { AgentIcon } from '@features/agent/components/agent-icon';
 
-type AgentRuntimeStatusByType = Partial<Record<AgentTypeKey, AgentRuntimeAvailability>>;
+type AgentRuntimeStatusByType = Partial<Record<AgentTypeKey, AgentRuntimeSnapshot>>;
 
 interface AgentRuntimeStatusListProps {
   statusByType: AgentRuntimeStatusByType;
@@ -42,9 +41,8 @@ interface AgentRuntimeStatusListProps {
    */
   onCardClick?: (typeKey: AgentTypeKey) => void;
   /**
-   * 需要隐藏的 agent key 集合 ── 调用方传进来后, 这些 agent 既不渲染行
-   * 也不计入后续的 `renderAfterRow` / `onCardClick` 调用。偏好设置用来
-   * 临时下线尚未发布的 agent (openclaw / gemini) 而不影响其他入口。
+   * 需要隐藏的 agent key 集合。隐藏项既不渲染，也不会传给
+   * `renderAfterRow` / `onCardClick`。
    */
   hiddenKeys?: ReadonlySet<AgentTypeKey>;
 }
@@ -56,7 +54,7 @@ export function getAgentRuntimeStatusText({
   t,
 }: {
   typeKey?: AgentTypeKey;
-  status: AgentRuntimeAvailability | undefined;
+  status: AgentRuntimeSnapshot | undefined;
   isChecking: boolean;
   t?: (key: I18nKey) => string;
 }): string {
@@ -97,9 +95,9 @@ export function AgentRuntimeStatusList({
 }: AgentRuntimeStatusListProps) {
   const isVisible = (typeKey: AgentTypeKey) =>
     !hiddenKeys?.has(typeKey);
-  const visibleAgentTypes = AGENT_TYPES.filter((type) => isVisible(type.key));
+  const visibleAgentTypes = AGENT_TYPES.filter((type) => isVisible(type.id));
   const { t } = useI18n();
-  const { enabledByType: agentVisibility, setEnabled } = useAgentVisibilityPreferences();
+  const { enabledByType: agentEnabledByType, setEnabled } = useAgentVisibilityPreferences();
 
   // 解析 i18n 文案 ── 卡片有 nameKey/descKey 就走 t(), 缺省回退到 type.name
   // / type.desc 的硬编码英文 (供编辑器节点等非 React 上下文用)。
@@ -108,7 +106,7 @@ export function AgentRuntimeStatusList({
   const displayDesc = (type: (typeof AGENT_TYPES)[number]): string =>
     type.descKey ? t(type.descKey as Parameters<typeof t>[0]) : type.desc;
 
-  const setAgentSlashEnabled = (typeKey: AgentTypeKey, enabled: boolean) => {
+  const setAgentEnabled = (typeKey: AgentTypeKey, enabled: boolean) => {
     void setEnabled(typeKey, enabled);
   };
 
@@ -116,21 +114,21 @@ export function AgentRuntimeStatusList({
     return (
       <div>
         {visibleAgentTypes.map((type) => {
-          const status = statusByType[type.key];
-          const comingSoon = isAgentTypeComingSoon(type.key);
+          const status = statusByType[type.id];
+          const comingSoon = isAgentTypeComingSoon(type.id);
           const runtimeStatus = normalizeAgentRuntimeStatus(status, isChecking);
           const unavailable = comingSoon || isRuntimeUnavailable(runtimeStatus);
-          const statusText = getAgentRuntimeStatusText({ typeKey: type.key, status, isChecking, t });
+          const statusText = getAgentRuntimeStatusText({ typeKey: type.id, status, isChecking, t });
           const canSetup = !comingSoon && isRuntimeUnavailable(runtimeStatus) && Boolean(onSetupClick);
           const available = !comingSoon && runtimeStatus.state === 'ready';
-          const slashEnabled = agentVisibility[type.key] ?? true;
+          const agentEnabled = agentEnabledByType[type.id] ?? true;
 
           return (
             <div
-              key={type.key}
+              key={type.id}
               className={cn(
                 'rounded-lg border border-[var(--border)] overflow-hidden px-3 [&+&]:mt-3',
-                highlightedKey === type.key && 'bg-[var(--document-bg)]',
+                highlightedKey === type.id && 'bg-[var(--document-bg)]',
               )}
             >
               <div
@@ -141,12 +139,12 @@ export function AgentRuntimeStatusList({
                   // 行内已有的 stopPropagation 子节点 (switch / Setup 按钮 /
                   // headerAction) 不会冒泡到这里; 其它位置 (icon / name /
                   // desc / 空白) 落到这里触发展开。
-                  onCardClick(type.key);
+                  onCardClick(type.id);
                 } : undefined}
                 onKeyDown={onCardClick ? (e) => {
                   if (e.key === 'Enter' || e.key === ' ') {
                     e.preventDefault();
-                    onCardClick(type.key);
+                    onCardClick(type.id);
                   }
                 } : undefined}
                 className={cn(
@@ -158,7 +156,7 @@ export function AgentRuntimeStatusList({
                 <div className="flex min-w-0 items-center gap-3">
                   <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full border border-[var(--border)] p-1">
                     <AgentIcon
-                      typeKey={type.key}
+                      typeKey={type.id}
                       alt={displayName(type)}
                       className={cn(
                         'h-full w-full object-contain',
@@ -191,13 +189,13 @@ export function AgentRuntimeStatusList({
                     <button
                       type="button"
                       role="switch"
-                      aria-checked={slashEnabled}
-                      aria-label={`${displayName(type)} slash menu visibility`}
-                      onClick={() => setAgentSlashEnabled(type.key, !slashEnabled)}
+                      aria-checked={agentEnabled}
+                      aria-label={t('preferences.agents.enableAgent', { name: displayName(type) })}
+                      onClick={() => setAgentEnabled(type.id, !agentEnabled)}
                       className={cn(
                         'relative h-5 w-9 rounded-full border transition-colors outline-none',
                         'focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:ring-offset-2',
-                        slashEnabled
+                        agentEnabled
                           ? 'border-[var(--primary)] bg-[var(--primary)]'
                           : 'border-[var(--border)] bg-[var(--muted)]'
                       )}
@@ -205,11 +203,11 @@ export function AgentRuntimeStatusList({
                       <span
                         className={cn(
                           'absolute left-0.5 top-1/2 h-4 w-4 -translate-y-1/2 rounded-full bg-[var(--card)] shadow-sm transition-transform',
-                          slashEnabled ? 'translate-x-4' : 'translate-x-0'
+                          agentEnabled ? 'translate-x-4' : 'translate-x-0'
                         )}
                       />
                     </button>
-                    {headerAction?.(type.key)}
+                    {headerAction?.(type.id)}
                   </div>
                 ) : canSetup ? (
                   <div
@@ -219,11 +217,11 @@ export function AgentRuntimeStatusList({
                     <Button
                       variant="outline"
                       className="px-3"
-                      onClick={() => onSetupClick?.(type.key)}
+                      onClick={() => onSetupClick?.(type.id)}
                     >
                       {t('agent.status.setup')}
                     </Button>
-                    {headerAction?.(type.key)}
+                    {headerAction?.(type.id)}
                   </div>
                 ) : (
                   <div
@@ -238,11 +236,11 @@ export function AgentRuntimeStatusList({
                     >
                       {statusText}
                     </span>
-                    {headerAction?.(type.key)}
+                    {headerAction?.(type.id)}
                   </div>
                 )}
               </div>
-              {renderAfterRow?.(type.key)}
+              {renderAfterRow?.(type.id)}
             </div>
           );
         })}
@@ -253,19 +251,19 @@ export function AgentRuntimeStatusList({
   return (
     <div className="space-y-0.5">
       {visibleAgentTypes.map((type) => {
-        const status = statusByType[type.key];
-        const comingSoon = isAgentTypeComingSoon(type.key);
+        const status = statusByType[type.id];
+        const comingSoon = isAgentTypeComingSoon(type.id);
         const runtimeStatus = normalizeAgentRuntimeStatus(status, isChecking);
         const unavailable = comingSoon || isRuntimeUnavailable(runtimeStatus);
-        const statusText = getAgentRuntimeStatusText({ typeKey: type.key, status, isChecking, t });
+        const statusText = getAgentRuntimeStatusText({ typeKey: type.id, status, isChecking, t });
         const interactive = !comingSoon && isRuntimeUnavailable(runtimeStatus) && Boolean(onSetupClick);
 
         return (
           <button
-            key={type.key}
+            key={type.id}
             type="button"
             disabled={!interactive}
-            onClick={() => onSetupClick?.(type.key)}
+            onClick={() => onSetupClick?.(type.id)}
             title={comingSoon ? statusText : unavailable ? runtimeStatus.reason ?? `${displayName(type)} is unavailable` : displayDesc(type)}
             className={cn(
               'group flex h-7 w-full items-center gap-2 rounded-md px-2 text-left outline-none transition-colors',
@@ -276,7 +274,7 @@ export function AgentRuntimeStatusList({
           >
             <span className="flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-[var(--border)] p-1">
               <AgentIcon
-                typeKey={type.key}
+                typeKey={type.id}
                 alt=""
                 className={cn(
                   'h-full w-full object-contain',
diff --git a/app/flowix-web/features/agent/components/agent-tasks-section.tsx b/app/flowix-web/features/agent/components/agent-tasks-section.tsx
index c659fa51f..0ba88468a 100644
--- a/app/flowix-web/features/agent/components/agent-tasks-section.tsx
+++ b/app/flowix-web/features/agent/components/agent-tasks-section.tsx
@@ -2,12 +2,13 @@
 
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type MouseEvent, type ReactNode } from 'react';
 import { ArchiveIcon, PencilSimpleIcon, SquareSplitHorizontalIcon, StarIcon, TrashSimpleIcon } from '@phosphor-icons/react';
-import { ChevronRight, MoreHorizontal, Plus } from 'lucide-react';
+import { ArrowRight, ChevronRight, MoreHorizontal, Plus } from 'lucide-react';
 import { AgentIcon } from '@features/agent/components/agent-icon';
-import { AGENT_TYPES, isAgentTypeSelectable, isAlwaysVisibleNewConversationAgent } from '@/lib/agent-types';
-import { buildInitialInstanceRuntimeConfig } from '@features/agent/store/initial-runtime-config';
-import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
-import { isAgentRuntimeInstalledState, normalizeAgentRuntimeStatus } from '@features/agent/runtime/agent-runtime-status';
+import { useNewConversationAgentSelection } from '@features/agent/hooks/use-new-conversation-agent-selection';
+import {
+  createAndOpenAgentConversation,
+  requestNewConversationAgentSelection,
+} from '@features/agent/use-cases/new-conversation';
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from '@shared/ui/dropdown-menu';
 import {
   isSyntheticOpenCodeHistoryInstance,
@@ -17,10 +18,8 @@ import { agentClient } from '@features/agent/store/agent-client';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
 import type { AgentConversationInstance } from '@features/agent/store/agent-conversation-types';
 import { isAgentConversationRunning } from '@features/agent/store/conversation-run-index';
-import { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
-import { openBrowserColumnAgentConversation } from '@features/workspace/use-cases/browser-column-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
-import { showAgentConversationsView } from '@features/memo/public/shell-api';
 import { useI18n } from '@/lib/i18n';
 import { cn } from '@/lib/utils';
 import { readFavoriteConversationIds, subscribeToFavoriteConversationChanges, toggleFavoriteConversation } from '@features/agent/conversation-favorites';
@@ -37,12 +36,14 @@ export function AgentTasksSection({
   edgeGutter = 6,
   order,
   onHeightChange,
+  onShowAllConversations,
   sectionActions,
 }: {
   notebookId: string;
   edgeGutter?: number;
   order: number;
   onHeightChange: (height: number) => void;
+  onShowAllConversations: () => void;
   sectionActions?: ReactNode;
 }) {
   const { t } = useI18n();
@@ -60,9 +61,6 @@ export function AgentTasksSection({
   const conversationRunIndex = useAgentSessionStore((state) => state.threadRunSignatures);
   const latestCompletedRunIds = useAgentSessionStore((state) => state.latestCompletedRunIds);
   const readThroughRunIds = useAgentSessionStore((state) => state.readThroughRunIds);
-  const agentRuntimeStatusByType = useAgentRuntimeStore((state) => state.statusByType);
-  const agentRuntimeIsChecking = useAgentRuntimeStore((state) => state.isChecking);
-  const refreshAgentRuntimeIfStale = useAgentRuntimeStore((state) => state.refreshIfStale);
   const activeConversationInstanceId = useWorkColumnStore((state) => (
     state.navigation.target.kind === 'agent-conversation'
       ? state.navigation.target.instanceId
@@ -131,7 +129,7 @@ export function AgentTasksSection({
         activeAgentTypeKey: instance.agentType,
       }));
     }
-    await selectAndOpenAgentConversation(instance.instanceId);
+    await openWorkspaceSurface({ target: { kind: 'agent-conversation', instanceId: instance.instanceId } });
   }, []);
 
   const prepareConversation = useCallback((instance: AgentConversationInstance) => {
@@ -150,7 +148,7 @@ export function AgentTasksSection({
 
   const openConversationInBrowserColumn = useCallback((instance: AgentConversationInstance) => {
     prepareConversation(instance);
-    void openBrowserColumnAgentConversation(instance.instanceId).catch((error) => {
+    void openWorkspaceSurface({ host: 'browser-column', target: { kind: 'agent-conversation', instanceId: instance.instanceId } }).catch((error) => {
       logger.error('Failed to open conversation in browser column', { error });
       toast.error(error instanceof Error ? error.message : String(error));
     });
@@ -208,29 +206,18 @@ export function AgentTasksSection({
     setOpenMenuId(instanceId);
   }, []);
 
-  const newConversationAgentTypes = useMemo(
-    () => AGENT_TYPES.filter((type) => {
-      if (!isAgentTypeSelectable(type.key)) return false;
-      if (isAlwaysVisibleNewConversationAgent(type.key)) return true;
-      return isAgentRuntimeInstalledState(normalizeAgentRuntimeStatus(
-        agentRuntimeStatusByType[type.key],
-        agentRuntimeIsChecking,
-      ));
-    }),
-    [agentRuntimeIsChecking, agentRuntimeStatusByType],
-  );
+  const newConversationSelection = useNewConversationAgentSelection();
 
   const createConversation = useCallback((typeKey: AgentConversationInstance['agentType']) => {
-    const instance = useAgentSessionStore.getState().createInstance({
-      agentType: typeKey,
-      title: '',
-      threadId: null,
-      source: { kind: 'dedicated', notebookId, documentPath: null },
-      runtimeConfig: buildInitialInstanceRuntimeConfig(typeKey),
-    });
-    void selectAndOpenAgentConversation(instance.instanceId, { blankIfMissing: true });
+    createAndOpenAgentConversation(typeKey, notebookId);
   }, [notebookId]);
 
+  useEffect(() => {
+    if (createMenuOpen && newConversationSelection.kind !== 'choose') {
+      setCreateMenuOpen(false);
+    }
+  }, [createMenuOpen, newConversationSelection]);
+
   const width = `calc(100% - ${edgeGutter * 2}px)`;
 
   return (
@@ -256,17 +243,36 @@ export function AgentTasksSection({
           <ChevronRight className={`h-3.5 w-3.5 opacity-0 transition-[opacity,transform] group-hover:opacity-100 group-focus-within:opacity-100 ${collapsed ? 'opacity-100' : 'rotate-90'}`} />
         </button>
         <div className="ml-auto flex items-center">
+          <button
+            type="button"
+            onClick={onShowAllConversations}
+            aria-label={t('memo.fileTree.openAllConversations')}
+            title={t('memo.fileTree.openAllConversations')}
+            className="flex h-6 w-6 items-center justify-center rounded-md text-[var(--muted-foreground)] opacity-0 transition-[color,opacity] hover:bg-[var(--muted)] hover:text-[var(--foreground)] focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)] group-hover:opacity-100"
+          >
+            <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
+          </button>
           {sectionActions}
           <DropdownMenu
             open={createMenuOpen}
             onOpenChange={(open) => {
-              setCreateMenuOpen(open);
-              if (open) void refreshAgentRuntimeIfStale();
+              if (!open) {
+                setCreateMenuOpen(false);
+                return;
+              }
+              const selection = requestNewConversationAgentSelection();
+              if (selection.kind === 'create') {
+                createConversation(selection.agentType);
+                setCreateMenuOpen(false);
+                return;
+              }
+              setCreateMenuOpen(selection.kind === 'choose');
             }}
           >
             <DropdownMenuTrigger asChild>
               <button
                 type="button"
+                disabled={newConversationSelection.kind === 'none'}
                 aria-label={t('agent.chat.newThread')}
                 title={t('agent.chat.newThread')}
                 className="flex h-6 w-6 items-center justify-center rounded-md text-[var(--muted-foreground)] transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
@@ -278,27 +284,16 @@ export function AgentTasksSection({
               <DropdownMenuLabel className="flex items-center gap-1.5 px-[0.375rem] pb-[0.35rem] pt-[0.35rem] text-xs font-normal leading-[1.2] text-[var(--muted-foreground)]">
                 {t('agent.chat.newThread')}
               </DropdownMenuLabel>
-              {newConversationAgentTypes.map((type) => {
-                const runtimeStatus = normalizeAgentRuntimeStatus(
-                  agentRuntimeStatusByType[type.key],
-                  agentRuntimeIsChecking,
-                );
-                const showNotInstalled = isAlwaysVisibleNewConversationAgent(type.key)
-                  && runtimeStatus.state === 'not-installed';
+              {newConversationSelection.options.map((type) => {
                 const name = type.nameKey ? t(type.nameKey as Parameters<typeof t>[0]) : type.name;
                 return (
                   <DropdownMenuItem
-                    key={type.key}
-                    onClick={() => createConversation(type.key)}
+                    key={type.id}
+                    onClick={() => createConversation(type.id)}
                     className="agent-conversation-new-agent-item group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
                   >
-                    <AgentIcon typeKey={type.key} alt="" className="h-4 w-4 shrink-0 object-contain" />
+                    <AgentIcon typeKey={type.id} alt="" className="h-4 w-4 shrink-0 object-contain" />
                     <span className="min-w-0 flex-1 truncate">{name}</span>
-                    {showNotInstalled && (
-                      <span className="shrink-0 text-xs text-[var(--muted-foreground)] group-hover:text-[var(--primary-foreground)]">
-                        {t('agent.status.notInstalled')}
-                      </span>
-                    )}
                   </DropdownMenuItem>
                 );
               })}
@@ -397,16 +392,6 @@ export function AgentTasksSection({
           {t('memo.fileTree.agentsEmpty')}
         </div>
       ))}
-      {!collapsed && tasks.length > 5 && (
-        <button
-          type="button"
-          onClick={showAgentConversationsView}
-          className="flex h-7 items-center rounded-lg px-1.5 text-left text-xs text-[color-mix(in_oklch,var(--muted-foreground)_67%,var(--background))] transition-colors hover:text-[var(--foreground)]"
-          style={{ marginLeft: edgeGutter, width }}
-        >
-          {t('memo.fileTree.moreAgents')}
-        </button>
-      )}
       <Dialog open={renameTarget !== null} onOpenChange={(open) => !open && !renameSaving && setRenameTarget(null)}>
         <DialogContent className="rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
           <DialogHeader><DialogTitle>{t('agent.chat.conversation.rename')}</DialogTitle></DialogHeader>
diff --git a/app/flowix-web/features/agent/components/conversation-list-pagination.ts b/app/flowix-web/features/agent/components/conversation-list-pagination.ts
index c50f49470..a906db7de 100644
--- a/app/flowix-web/features/agent/components/conversation-list-pagination.ts
+++ b/app/flowix-web/features/agent/components/conversation-list-pagination.ts
@@ -59,8 +59,6 @@ function isFallbackTitle(instance: AgentConversationInstance): boolean {
     'hermes 会话',
     'opencode session',
     'opencode 会话',
-    'openclaw session',
-    'openclaw 会话',
   ]).has(title);
 }
 
diff --git a/app/flowix-web/features/agent/components/use-agent-conversation-surface.ts b/app/flowix-web/features/agent/components/use-agent-conversation-surface.ts
new file mode 100644
index 000000000..8811b1cf3
--- /dev/null
+++ b/app/flowix-web/features/agent/components/use-agent-conversation-surface.ts
@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useI18n } from '@/lib/i18n';
+import { getAgentType } from '@/lib/agent-types';
+import { getAgentConversationPresentation } from '@features/agent/conversation-presentation';
+import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
+import type { SurfacePresentationUpdate, SurfaceState } from '@features/workspace/model/surface-contract';
+
+/** Domain hydration and display data shared by both workspace hosts. */
+export function useAgentConversationSurface(instanceId: string, reportPresentation?: (update: SurfacePresentationUpdate) => void) {
+  const { t } = useI18n();
+  const instance = useAgentSessionStore((state) => state.getInstance(instanceId));
+  const [loadState, setLoadState] = useState<{
+    instanceId: string;
+    status: 'loading' | 'not-found' | 'error';
+  } | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+  useEffect(() => {
+    if (instance) return;
+
+    let cancelled = false;
+    setLoadState({ instanceId, status: 'loading' });
+    void useAgentSessionStore.getState().hydrateInstance(instanceId)
+      .then((restored) => {
+        if (!cancelled && !restored) setLoadState({ instanceId, status: 'not-found' });
+      })
+      .catch(() => {
+        if (!cancelled) setLoadState({ instanceId, status: 'error' });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [instance, instanceId, retryCount]);
+
+  const retry = useCallback(() => {
+    setLoadState({ instanceId, status: 'loading' });
+    setRetryCount((count) => count + 1);
+  }, [instanceId]);
+  const status = instance ? 'ready' : loadState?.instanceId === instanceId ? loadState.status : 'loading';
+  const title = instance ? getAgentConversationPresentation(instance, t('common.untitled')).title : t('common.untitled');
+  const icon = instance ? getAgentType(instance.agentType).icon : undefined;
+  useEffect(() => {
+    const actions = [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retry }];
+    const state: SurfaceState = status === 'ready' ? { status: 'ready' }
+      : status === 'loading' ? { status: 'loading', phase: 'content', message: { key: 'status.agent.loadingConversations' }, retainContent: false }
+        : status === 'not-found' ? { status: 'unavailable', reason: 'missing', message: { key: 'status.agent.conversationNotFound' }, actions }
+          : { status: 'error', message: { key: 'status.agent.loadConversationsFailed' }, actions };
+    reportPresentation?.({ title, icon, state });
+  }, [icon, reportPresentation, retry, status, title]);
+
+  return { instance, status, retry };
+}
diff --git a/app/flowix-web/features/agent/components/use-conversation-list-data.ts b/app/flowix-web/features/agent/components/use-conversation-list-data.ts
index bd41811b1..2b46356dd 100644
--- a/app/flowix-web/features/agent/components/use-conversation-list-data.ts
+++ b/app/flowix-web/features/agent/components/use-conversation-list-data.ts
@@ -14,6 +14,15 @@ import {
 const logger = createLogger('conversation-list-data');
 const CONVERSATION_PAGE_SIZE = 30;
 
+function firstPageQueryKey(
+  notebookId: string | null,
+  agentType: AgentTypeKey | null,
+  lifecycleVersion: number,
+  retry: number,
+): string {
+  return `${notebookId ?? ''}\u001f${agentType ?? ''}\u001f${lifecycleVersion}\u001f${retry}`;
+}
+
 interface ConversationListDataOptions {
   notebookId: string | null;
   agentType: AgentTypeKey | null;
@@ -31,6 +40,7 @@ export function useConversationListData({
   );
   const [isLoading, setIsLoading] = useState(true);
   const [loadError, setLoadError] = useState(false);
+  const [settledQueryKey, setSettledQueryKey] = useState<string | null>(null);
   const [firstPageRetry, setFirstPageRetry] = useState(0);
   const [isLoadingMore, setIsLoadingMore] = useState(false);
   const [loadMoreError, setLoadMoreError] = useState(false);
@@ -46,7 +56,24 @@ export function useConversationListData({
   // hydrated wholesale just to render the sidebar.
   useEffect(() => {
     let active = true;
-    const queryKey = `${notebookId ?? ''}\u001f${agentType ?? ''}`;
+    const queryKey = firstPageQueryKey(notebookId, agentType, lifecycleVersion, firstPageRetry);
+    if (!notebookId) {
+      requestSequenceRef.current += 1;
+      loadingMoreRef.current = false;
+      listQueryKeyRef.current = queryKey;
+      nextCursorRef.current = null;
+      setConversationPage(EMPTY_CONVERSATION_PAGE_STATE);
+      setHasMore(false);
+      setLoadError(false);
+      setLoadMoreError(false);
+      setIsLoadingMore(false);
+      setAgentTypeCounts({});
+      setIsLoading(false);
+      setSettledQueryKey(queryKey);
+      return () => {
+        active = false;
+      };
+    }
     const query = { notebookId, agentType, cursor: null } as const;
     const queryChanged = listQueryKeyRef.current !== queryKey;
     // Invalidate any in-flight page request before starting a new first page.
@@ -62,6 +89,7 @@ export function useConversationListData({
       setLoadMoreError(false);
     }
     setLoadError(false);
+    setSettledQueryKey(null);
     // Lifecycle changes can trigger a fresh first page after the view is
     // mounted, keeping deletion/archive state aligned with the backend.
     setIsLoading(true);
@@ -80,7 +108,10 @@ export function useConversationListData({
         if (active) setLoadError(true);
       })
       .finally(() => {
-        if (active) setIsLoading(false);
+        if (active) {
+          setIsLoading(false);
+          setSettledQueryKey(queryKey);
+        }
       });
     return () => {
       active = false;
@@ -92,6 +123,12 @@ export function useConversationListData({
   // rows themselves remain cursor-paginated.
   useEffect(() => {
     let active = true;
+    if (!notebookId) {
+      setAgentTypeCounts({});
+      return () => {
+        active = false;
+      };
+    }
     void agentClient.listConversationTypeCountsByNotebook(notebookId)
       .then((counts) => {
         if (!active) return;
@@ -108,11 +145,11 @@ export function useConversationListData({
   }, [notebookId, lifecycleVersion]);
 
   const loadMoreConversations = useCallback(async (retry = false) => {
-    if (loadingMoreRef.current || !hasMore || isLoading || loadError || (loadMoreError && !retry)) return;
+    if (!notebookId || loadingMoreRef.current || !hasMore || isLoading || loadError || (loadMoreError && !retry)) return;
     loadingMoreRef.current = true;
     setIsLoadingMore(true);
     setLoadMoreError(false);
-    const queryKey = `${notebookId ?? ''}\u001f${agentType ?? ''}`;
+    const queryKey = firstPageQueryKey(notebookId, agentType, lifecycleVersion, firstPageRetry);
     const requestSequence = ++requestSequenceRef.current;
     try {
       const query = { notebookId, agentType, cursor: nextCursorRef.current };
@@ -142,7 +179,16 @@ export function useConversationListData({
         setIsLoadingMore(false);
       }
     }
-  }, [notebookId, agentType, hasMore, isLoading, loadError, loadMoreError]);
+  }, [
+    notebookId,
+    agentType,
+    lifecycleVersion,
+    firstPageRetry,
+    hasMore,
+    isLoading,
+    loadError,
+    loadMoreError,
+  ]);
 
   const retryFirstPage = useCallback(() => {
     setFirstPageRetry((value) => value + 1);
@@ -160,6 +206,8 @@ export function useConversationListData({
     loadMoreError,
     hasMore,
     agentTypeCounts,
+    settledQueryKey,
+    queryKey: firstPageQueryKey(notebookId, agentType, lifecycleVersion, firstPageRetry),
     loadMore: loadMoreConversations,
     retryFirstPage,
     updateTitle,
diff --git a/app/flowix-web/features/agent/config/agent-model-options.ts b/app/flowix-web/features/agent/config/agent-model-options.ts
new file mode 100644
index 000000000..4167271ef
--- /dev/null
+++ b/app/flowix-web/features/agent/config/agent-model-options.ts
@@ -0,0 +1,16 @@
+import type { AgentTypeKey } from "@/types/agent";
+import { CODEX_MODEL_OPTIONS, formatModelDisplayLabel } from "./codex-options";
+import { normalizeAgentId } from "@/lib/agent-types";
+
+/** Built-in models shown before an Agent catalog has loaded. */
+export function getFallbackAgentModelOptions(agentType: AgentTypeKey): Array<{ id: string; label: string }> {
+  const id = normalizeAgentId(agentType);
+  if (id === "codex") {
+    return CODEX_MODEL_OPTIONS.map(({ id, label }) => ({ id, label }));
+  }
+  if (id === "claudecode") {
+    return ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"]
+      .map((id) => ({ id, label: formatModelDisplayLabel(id) }));
+  }
+  return [];
+}
diff --git a/app/flowix-web/features/agent/events/agent-event-mapper.test.ts b/app/flowix-web/features/agent/events/agent-event-mapper.test.ts
index b99e956d4..afdaa1bba 100644
--- a/app/flowix-web/features/agent/events/agent-event-mapper.test.ts
+++ b/app/flowix-web/features/agent/events/agent-event-mapper.test.ts
@@ -20,7 +20,7 @@ describe("agent event mapper", () => {
         id: "user-1",
         text: "question",
         timestamp: 456,
-        agent_type: "claude",
+        agent_type: "claudecode",
         run_id: "run-1",
       },
       state(),
@@ -29,9 +29,9 @@ describe("agent event mapper", () => {
 
     expect(event).toMatchObject({
       kind: "user_message",
-      id: "msg:claude:run-1:user:user-1",
+      id: "msg:claudecode:run-1:user:user-1",
       text: "question",
-      messageId: "msg:claude:run-1:user:user-1",
+      messageId: "msg:claudecode:run-1:user:user-1",
       sourceTimestamp: 456,
       sourceSequence: 0,
     });
@@ -46,7 +46,7 @@ describe("agent event mapper", () => {
         text: "目标执行中：在吗（第 1/256 轮）",
         timestamp: 456,
         message_type: "goal-round",
-        agent_type: "deepseek-harness",
+        agent_type: "dsh",
         run_id: "run-1",
       },
       state(),
@@ -66,7 +66,7 @@ describe("agent event mapper", () => {
         kind: "text",
         thread_id: "flowix-thread",
         text: "hello",
-        agent_type: "deepseek-harness",
+        agent_type: "dsh",
         run_id: "run-1",
       },
       state(),
@@ -150,7 +150,7 @@ describe("agent event mapper", () => {
         kind: "error",
         thread_id: "claude-thread",
         run_id: "run-1",
-        agent_type: "claude",
+        agent_type: "claudecode",
         message: "Claude Code CLI exited with status exit status: 1",
         error_details: {
           category: "rate_limited",
@@ -166,7 +166,7 @@ describe("agent event mapper", () => {
 
     expect(event).toMatchObject({
       kind: "error",
-      messageId: "msg:claude:run-1:error:error",
+      messageId: "msg:claudecode:run-1:error:error",
       message: "Claude Code CLI exited with status exit status: 1",
       errorDetails: {
         category: "rate_limited",
@@ -226,7 +226,7 @@ describe("agent event mapper", () => {
         kind: "reasoning",
         thread_id: "thread-1",
         text: "thinking",
-        agent_type: "deepseek-harness",
+        agent_type: "dsh",
       },
       state(),
       () => 123,
@@ -238,7 +238,7 @@ describe("agent event mapper", () => {
       {
         kind: "usage",
         thread_id: "thread-1",
-        agent_type: "deepseek-harness",
+        agent_type: "dsh",
         usage: { input_tokens: 10, output_tokens: 4 },
       },
       state(),
@@ -253,7 +253,7 @@ describe("agent event mapper", () => {
         kind: "reasoning",
         thread_id: "claude-thread",
         text: "first",
-        agent_type: "claude",
+        agent_type: "claudecode",
         run_id: "run-1",
         message_id: "reasoning-provider-message-1-block-0",
       },
@@ -264,7 +264,7 @@ describe("agent event mapper", () => {
         kind: "reasoning",
         thread_id: "claude-thread",
         text: "second",
-        agent_type: "claude",
+        agent_type: "claudecode",
         run_id: "run-1",
         message_id: "reasoning-provider-message-2-block-0",
       },
@@ -272,7 +272,7 @@ describe("agent event mapper", () => {
     );
 
     expect(first.messageId).toBe(
-      "msg:claude:run-1:reasoning:reasoning-run-1",
+      "msg:claudecode:run-1:reasoning:reasoning-run-1",
     );
     expect(second.messageId).toBe(first.messageId);
   });
@@ -283,7 +283,7 @@ describe("agent event mapper", () => {
         kind: "text",
         thread_id: "claude-thread",
         text: "fragment",
-        agent_type: "claude",
+        agent_type: "claudecode",
         run_id: "run-1",
         message_id:
           "assistant-d9193ae4-86b5-47a6-9e85-1bb4ef0acc1c-block-1",
@@ -295,7 +295,7 @@ describe("agent event mapper", () => {
 
     expect(event).toMatchObject({
       kind: "text_delta",
-      agentType: "claude",
+      agentType: "claudecode",
       text: "fragment",
     });
     expect(event.messageId).toBeUndefined();
@@ -307,7 +307,7 @@ describe("agent event mapper", () => {
         kind: "text",
         thread_id: "claude-thread",
         text: "fragment",
-        agent_type: "claude",
+        agent_type: "claudecode",
         run_id: "run-1",
         message_id: "assistant-06bbbb1512785f3d1da3e1f495c31702-block-1",
         message_phase: "updated",
@@ -317,7 +317,7 @@ describe("agent event mapper", () => {
     );
 
     expect(event.messageId).toBe(
-      "msg:claude:run-1:assistant:assistant-06bbbb1512785f3d1da3e1f495c31702-block-1",
+      "msg:claudecode:run-1:assistant:assistant-06bbbb1512785f3d1da3e1f495c31702-block-1",
     );
   });
 
@@ -354,7 +354,7 @@ describe("agent event mapper", () => {
         args: "",
         status: "pending",
         timestamp: 456,
-        agent_type: "deepseek-harness",
+        agent_type: "dsh",
         run_id: "dsh-command-run-1",
       },
       state(),
diff --git a/app/flowix-web/features/agent/events/agent-event-mapper.ts b/app/flowix-web/features/agent/events/agent-event-mapper.ts
index eee5242eb..d0c95b8ef 100644
--- a/app/flowix-web/features/agent/events/agent-event-mapper.ts
+++ b/app/flowix-web/features/agent/events/agent-event-mapper.ts
@@ -32,7 +32,7 @@ function resolveTextMessageId(
   // on every delta. Dropping only that known-bad delta id lets pendingAssistantId
   // join contiguous text while tool calls still form an explicit boundary.
   if (
-    agentType === "claude" &&
+    agentType === "claudecode" &&
     contentMode === "delta" &&
     messageId &&
     CLAUDE_ENVELOPE_TEXT_MESSAGE_ID.test(messageId)
@@ -127,7 +127,7 @@ export function mapAgentChunkToEvent(
           base.agentType,
           base.runId,
           "reasoning",
-          base.agentType === "claude" &&
+          base.agentType === "claudecode" &&
             !base.messageId?.startsWith("msg:")
             ? `reasoning-${base.runId}`
             : base.messageId,
diff --git a/app/flowix-web/features/agent/events/codex-message-identity.ts b/app/flowix-web/features/agent/events/codex-message-identity.ts
new file mode 100644
index 000000000..6bbe7411f
--- /dev/null
+++ b/app/flowix-web/features/agent/events/codex-message-identity.ts
@@ -0,0 +1,49 @@
+/** Shared marker used when Codex omits a user item's native ID. */
+export const CODEX_MISSING_USER_ITEM_ID = "flowix:codex:missing-user-item";
+
+export function codexCommandMessageId(turnId: string): string {
+  return `flowix:codex:command:${turnId}`;
+}
+
+/** Temporary identity while the provider has not attached a turn ID yet. */
+export function codexPendingCommandMessageId(commandId: string): string {
+  return `flowix:codex:command:pending:${commandId}`;
+}
+
+export function codexToolCallMessageId(
+  turnId: string | undefined,
+  callId: string,
+): string {
+  return `flowix:codex:tool-call:${turnId?.trim() ? turnId : "unbound"}:${callId}`;
+}
+
+export function codexCustomToolOutputMessageId(
+  turnId: string | undefined,
+  callId: string,
+): string {
+  return `flowix:codex:tool-output:${turnId?.trim() ? turnId : "unbound"}:${callId}`;
+}
+
+/**
+ * Fallback for a completed provider item that has no native id. Hash UTF-8
+ * bytes so Rust history projection and the browser live projection produce
+ * the same value. The occurrence distinguishes repeated identical items in
+ * the same turn.
+ */
+export function codexFallbackItemMessageId(
+  turnId: string,
+  role: string,
+  content: string,
+  occurrence: number,
+): string {
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  for (const byte of new TextEncoder().encode(content)) {
+    first = Math.imul(first ^ byte, 0x01000193) >>> 0;
+    second = Math.imul(second ^ byte, 0x85ebca6b) >>> 0;
+  }
+  const fingerprint = `${first.toString(16).padStart(8, "0")}${second
+    .toString(16)
+    .padStart(8, "0")}`;
+  return `flowix:codex:item:${turnId}:${role}:${fingerprint}:${occurrence}`;
+}
diff --git a/app/flowix-web/features/agent/events/message-identity.test.ts b/app/flowix-web/features/agent/events/message-identity.test.ts
index c6586afda..e6ca6ff04 100644
--- a/app/flowix-web/features/agent/events/message-identity.test.ts
+++ b/app/flowix-web/features/agent/events/message-identity.test.ts
@@ -5,7 +5,7 @@ import {
 } from "@features/agent/events/message-identity";
 
 describe("canonical agent message identity", () => {
-  it.each(["claude", "hermes", "opencode", "deepseek-harness"] as const)(
+  it.each(["claudecode", "hermes", "opencode", "dsh"] as const)(
     "uses the shared rule for %s",
     (agentType) => {
       expect(
@@ -44,8 +44,15 @@ describe("canonical agent message identity", () => {
     expect(
       canonicalAgentMessageId("codex", "run-1", "assistant", canonical),
     ).toBe(canonical);
-    expect(completedRunUserMessageId("deepseek-harness", "run-1")).toBe(
-      "msg:deepseek-harness:run-1:user:user-run-1",
+    expect(completedRunUserMessageId("dsh", "run-1")).toBe(
+      "msg:dsh:run-1:user:user-run-1",
     );
   });
+
+  it("preserves the shared Codex turn-error identity", () => {
+    const turnErrorId = "msg:codex:turn-error:turn-1";
+    expect(
+      canonicalAgentMessageId("codex", "run-1", "error", turnErrorId),
+    ).toBe(turnErrorId);
+  });
 });
diff --git a/app/flowix-web/features/agent/events/message-identity.ts b/app/flowix-web/features/agent/events/message-identity.ts
index 81dba2866..d73724cee 100644
--- a/app/flowix-web/features/agent/events/message-identity.ts
+++ b/app/flowix-web/features/agent/events/message-identity.ts
@@ -2,11 +2,11 @@ import type { AgentTypeKey } from "@/types/agent";
 
 const CANONICAL_EXTERNAL_AGENTS = new Set<AgentTypeKey>([
   "codex",
-  "claude",
+  "claudecode",
   "hermes",
   "pi",
   "opencode",
-  "deepseek-harness",
+  "dsh",
 ]);
 
 export function canonicalAgentMessageId(
diff --git a/app/flowix-web/features/agent/hooks/use-agent-events.ts b/app/flowix-web/features/agent/hooks/use-agent-events.ts
index f25b92537..22a1fcb6c 100644
--- a/app/flowix-web/features/agent/hooks/use-agent-events.ts
+++ b/app/flowix-web/features/agent/hooks/use-agent-events.ts
@@ -6,6 +6,7 @@ import {
 } from '@features/agent/store/agent-session-store';
 import { isProjectionRunActive } from '@features/agent/store/session-reducer';
 import { getInterestedThreadIds } from '@features/agent/store/thread-interest';
+import { runStartupStage3Task } from '@/lib/startup-stage3';
 
 export async function reconcileAgentRunsAndRefreshEndedHistory(): Promise<void> {
   // Canonical run state lives in AgentSessionStore projections.
@@ -56,7 +57,9 @@ export async function reconcileAgentRunsAndRefreshEndedHistory(): Promise<void>
     refreshTargets.set(threadId, agentType);
   }
 
-  for (const interestedThreadId of getInterestedThreadIds()) {
+  const interestedThreadIds = getInterestedThreadIds();
+  const priorityThreadIds = new Set(interestedThreadIds);
+  for (const interestedThreadId of interestedThreadIds) {
     refreshTargets.set(
       interestedThreadId,
       after.sessionMeta.threadTypes[interestedThreadId] ??
@@ -70,16 +73,23 @@ export async function reconcileAgentRunsAndRefreshEndedHistory(): Promise<void>
       .map((target) => [target.threadId, target]),
   );
 
-  await Promise.allSettled(
-    [...refreshTargets].map(([threadId, agentType]) => {
-      const completed = completedTargets.get(threadId);
-      return completed
-        ? useAgentSessionStore
-            .getState()
-            .reconcileCompletedRun(agentType, threadId, completed.runId)
-        : useAgentSessionStore.getState().loadMessages(agentType, threadId);
-    }),
-  );
+  const targets = [...refreshTargets];
+  const priorityTargets = targets.filter(([threadId]) => priorityThreadIds.has(threadId));
+  const backgroundTargets = targets.filter(([threadId]) => !priorityThreadIds.has(threadId));
+  const refreshTarget = ([threadId, agentType]: [string, typeof after.sessionMeta.activeAgentTypeKey]) => {
+    const completed = completedTargets.get(threadId);
+    return completed
+      ? useAgentSessionStore
+          .getState()
+          .reconcileCompletedRun(agentType, threadId, completed.runId)
+      : useAgentSessionStore.getState().loadMessages(agentType, threadId);
+  };
+
+  // Refresh visible conversations first; catch up hidden sessions two at a time.
+  await Promise.allSettled(priorityTargets.map(refreshTarget));
+  for (let index = 0; index < backgroundTargets.length; index += 2) {
+    await Promise.allSettled(backgroundTargets.slice(index, index + 2).map(refreshTarget));
+  }
 }
 
 /**
@@ -88,13 +98,15 @@ export async function reconcileAgentRunsAndRefreshEndedHistory(): Promise<void>
  * This is mounted by AgentWindowEffects in content Webviews, but not
  * preferences. The bridge itself is idempotent within each Webview realm.
  */
-export function useAgentEvents(): void {
+export function useAgentEvents(waitForWorkspaceRestore?: () => Promise<void>): void {
   useEffect(() => {
     let disposed = false;
+    let startupRecoveryReady = false;
+    let reconcileAfterStartupRecovery = false;
     let lastReconcileAt = 0;
 
     const reconcileRunningRuns = async (force = false) => {
-      if (disposed) return;
+      if (disposed || !startupRecoveryReady) return;
       const now = Date.now();
       if (!force && now - lastReconcileAt < 1000) return;
       lastReconcileAt = now;
@@ -105,18 +117,29 @@ export function useAgentEvents(): void {
       // Listener readiness is a recovery boundary. Force a snapshot even if
       // the normal focus/visibility throttle ran recently, because stream_end
       // may have been missed while Tauri registration was unavailable.
+      if (!startupRecoveryReady) {
+        reconcileAfterStartupRecovery = true;
+        return;
+      }
       void reconcileRunningRuns(true).catch((err) => {
         console.warn('[useAgentEvents] post-listen reconciliation failed:', err);
       });
     });
 
-    (async () => {
-      try {
-        await reconcileRunningRuns();
-      } catch (err) {
-        console.warn('[useAgentEvents] agent_running_threads failed:', err);
-      }
-    })();
+    void runStartupStage3Task('agent-session-recovery', async () => {
+      await waitForWorkspaceRestore?.();
+      await reconcileAgentRunsAndRefreshEndedHistory();
+    })
+      .then(() => {
+        if (disposed) return;
+        startupRecoveryReady = true;
+        if (reconcileAfterStartupRecovery) {
+          reconcileAfterStartupRecovery = false;
+          void reconcileRunningRuns(true).catch((err) => {
+            console.warn('[useAgentEvents] deferred post-listen reconciliation failed:', err);
+          });
+        }
+      });
 
     const handleVisibilityChange = () => {
       if (document.visibilityState !== 'visible') return;
@@ -138,5 +161,5 @@ export function useAgentEvents(): void {
       window.removeEventListener('focus', handleFocus);
       document.removeEventListener('visibilitychange', handleVisibilityChange);
     };
-  }, []);
+  }, [waitForWorkspaceRestore]);
 }
diff --git a/app/flowix-web/features/agent/hooks/use-new-conversation-agent-selection.ts b/app/flowix-web/features/agent/hooks/use-new-conversation-agent-selection.ts
new file mode 100644
index 000000000..a0e50f0ba
--- /dev/null
+++ b/app/flowix-web/features/agent/hooks/use-new-conversation-agent-selection.ts
@@ -0,0 +1,19 @@
+import { useMemo } from 'react';
+import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
+import { useAgentVisibilityPreferences } from '@features/preferences/public/runtime-api';
+import { getNewConversationAgentSelection } from '@features/agent/runtime/new-conversation-agent-selection';
+
+export function useNewConversationAgentSelection() {
+  const statusByType = useAgentRuntimeStore((state) => state.statusByType);
+  const isChecking = useAgentRuntimeStore((state) => state.isChecking);
+  const { enabledByType } = useAgentVisibilityPreferences();
+
+  return useMemo(
+    () => getNewConversationAgentSelection(
+      statusByType,
+      isChecking,
+      (typeKey) => enabledByType[typeKey] ?? true,
+    ),
+    [enabledByType, isChecking, statusByType],
+  );
+}
diff --git a/app/flowix-web/features/agent/message/agent-message.ts b/app/flowix-web/features/agent/message/agent-message.ts
index ba2f9df07..230f2c4db 100644
--- a/app/flowix-web/features/agent/message/agent-message.ts
+++ b/app/flowix-web/features/agent/message/agent-message.ts
@@ -8,6 +8,7 @@ import {
   formatDeepSeekHarnessReconnectError,
   isDeepSeekHarnessReconnectError,
 } from "@features/agent/message/error-format";
+import { cloudModelAccessErrorMessage } from "@platform/tauri/errors";
 import { translate, type AppLanguage, type I18nKey } from "@/lib/i18n";
 import { getAgentToolInputSummary as getFallbackAgentToolInputSummary } from "@features/agent/tool-display";
 
@@ -105,7 +106,7 @@ export function getAgentMessageVisibleContent(
     if (isDeepSeekHarnessReconnectError(message)) {
       return formatDeepSeekHarnessReconnectError(message, language);
     }
-    return formatAgentErrorMessage(
+    const formattedError = formatAgentErrorMessage(
       formatExternalAgentErrorMessage(
         message.content || "",
         message.errorDetails,
@@ -114,6 +115,10 @@ export function getAgentMessageVisibleContent(
           message.errorDetails?.source === "dsh-history",
       ),
     );
+    return cloudModelAccessErrorMessage(
+      formattedError,
+      (key, params) => translate(language, key, params),
+    );
   }
 
   return message.content || "";
diff --git a/app/flowix-web/features/agent/message/format.ts b/app/flowix-web/features/agent/message/format.ts
index 865fd21fb..8a5534c5a 100644
--- a/app/flowix-web/features/agent/message/format.ts
+++ b/app/flowix-web/features/agent/message/format.ts
@@ -14,11 +14,10 @@ export function truncateStart(path: string, maxChars: number = 20): string {
 
 /**
  * Extracts a compact file name for tool message summaries.
- * Removes the memo id suffix in the #xxxxxx format and then the extension.
+ * Removes the file extension from a path's final component.
  */
 export function extractFileName(path: string): string {
-  // v3 改造: filename 已经是磁盘文件名 (xxx.md), 不再带 #memoid 后缀,
-  // 因此 memoIdPattern 分支移除 ── 直接按扩展名规则剥掉 .md / .txt 等。
+  // Strip the extension from the on-disk filename.
   const fileName = path.split("/").pop() ?? path.split("\\").pop() ?? path;
 
   const lastDot = fileName.lastIndexOf(".");
diff --git a/app/flowix-web/features/agent/message/tools.test.ts b/app/flowix-web/features/agent/message/tools.test.ts
index 9f614b0c5..b9aec7d2a 100644
--- a/app/flowix-web/features/agent/message/tools.test.ts
+++ b/app/flowix-web/features/agent/message/tools.test.ts
@@ -99,7 +99,7 @@ describe("DeepSeek Harness tool metadata", () => {
     ["cordis_inspect_self", "Cordis 插件", TOOL_ICON_PATHS.plug],
     ["todo_write", "计划", TOOL_ICON_PATHS.checks],
   ] as const)("maps %s to label and icon via wildcard", (toolName, label, iconPath) => {
-    const lookup = { agentType: "deepseek-harness" as const, toolName };
+    const lookup = { agentType: "dsh" as const, toolName };
     expect(getToolLabel(lookup, "zh-CN")).toBe(label);
     expect(getToolIconPath(lookup)).toBe(iconPath);
   });
diff --git a/app/flowix-web/features/agent/public/app-api.ts b/app/flowix-web/features/agent/public/app-api.ts
index d9936ebda..865ec406a 100644
--- a/app/flowix-web/features/agent/public/app-api.ts
+++ b/app/flowix-web/features/agent/public/app-api.ts
@@ -1,3 +1,4 @@
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
 import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
 export { invalidateDshModelConfigs } from '@features/agent/store/dsh-model-config-store';
 
@@ -8,3 +9,7 @@ export function useAppAgentRuntimeViewModel() {
   const refreshAgentRuntime = useAgentRuntimeStore((state) => state.refresh);
   return { refreshAgentRuntime };
 }
+
+export function useAgentPersistenceError(): string | null {
+  return useAgentDataStore((state) => state.persistenceError);
+}
diff --git a/app/flowix-web/features/agent/public/dsh-onboarding-api.ts b/app/flowix-web/features/agent/public/dsh-onboarding-api.ts
deleted file mode 100644
index 61ef92e7e..000000000
--- a/app/flowix-web/features/agent/public/dsh-onboarding-api.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { agent } from '@platform/tauri/client';
-
-export { AgentIcon } from '@features/agent/components/agent-icon';
-
-export function getLocalAgentRuntimeStatus() {
-  return agent.runtimeStatus();
-}
-
diff --git a/app/flowix-web/features/agent/public/runtime-status-api.ts b/app/flowix-web/features/agent/public/runtime-status-api.ts
index 530c0540f..6b4aefc0e 100644
--- a/app/flowix-web/features/agent/public/runtime-status-api.ts
+++ b/app/flowix-web/features/agent/public/runtime-status-api.ts
@@ -1,3 +1,6 @@
+import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
+import type { AgentRuntimeSnapshot, AgentTypeKey } from '@/types/agent';
+
 export {
   isAgentRuntimeInstalledState,
   normalizeAgentRuntimeStatus,
@@ -6,3 +9,32 @@ export {
   type AgentRuntimeStatusView,
   type AgentRuntimeStatusViewByType,
 } from '@features/agent/runtime/agent-runtime-status';
+export { getAvailableAgentTypes } from '@features/agent/runtime/agent-availability';
+
+export interface AgentRuntimeStatusSnapshot {
+  statusByType: Partial<Record<AgentTypeKey, AgentRuntimeSnapshot>>;
+  isChecking: boolean;
+  /** True after at least one runtime status check has succeeded. */
+  hasChecked: boolean;
+}
+
+export function getAgentRuntimeStatusSnapshot(): AgentRuntimeStatusSnapshot {
+  const { statusByType, isChecking, lastCheckedAt } = useAgentRuntimeStore.getState();
+  return { statusByType, isChecking, hasChecked: lastCheckedAt !== null };
+}
+
+/** Notify consumers when reported status or check progress changes. */
+export function subscribeAgentRuntimeStatus(listener: () => void): () => void {
+  return useAgentRuntimeStore.subscribe((state, previous) => {
+    if (state.statusByType !== previous.statusByType
+      || state.isChecking !== previous.isChecking
+      || state.lastCheckedAt !== previous.lastCheckedAt) {
+      listener();
+    }
+  });
+}
+
+/** Start a background status refresh only when the cached report is stale. */
+export function refreshAgentRuntimeStatusIfStale(): Promise<void> {
+  return useAgentRuntimeStore.getState().refreshIfStale();
+}
diff --git a/app/flowix-web/features/agent/public/shell-api.ts b/app/flowix-web/features/agent/public/shell-api.ts
index 93085ec29..539cba0e3 100644
--- a/app/flowix-web/features/agent/public/shell-api.ts
+++ b/app/flowix-web/features/agent/public/shell-api.ts
@@ -4,78 +4,17 @@ export { AgentConversationStatusBar } from '@features/agent/components/agent-con
 export { AgentIcon } from '@features/agent/components/agent-icon';
 export { AgentTasksSection } from '@features/agent/components/agent-tasks-section';
 
-import { buildInitialInstanceRuntimeConfig } from '@features/agent/store/initial-runtime-config';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
-import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
-import { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
-import { useNoteStore } from '@features/memo/store/note-store';
-import type { AgentTypeKey } from '@/types/agent';
 
 export { isAgentRuntimeInstalledState, normalizeAgentRuntimeStatus } from '@features/agent/runtime/agent-runtime-status';
+export {
+  createAndOpenAgentConversation,
+  createAndOpenPiConversation,
+  createBrowserColumnAgentConversation,
+  requestNewConversationAgentSelection,
+} from '@features/agent/use-cases/new-conversation';
 
 export function useBrowserColumnAgentHeaderModel() {
-  const statusByType = useAgentRuntimeStore((state) => state.statusByType);
-  const isChecking = useAgentRuntimeStore((state) => state.isChecking);
-  const refreshIfStale = useAgentRuntimeStore((state) => state.refreshIfStale);
   const conversationInstances = useAgentSessionStore((state) => state.conversationRegistry.instances);
-  return { statusByType, isChecking, refreshIfStale, conversationInstances };
-}
-
-export function createBrowserColumnAgentConversation(typeKey: AgentTypeKey, notebookId: string): string {
-  return useAgentSessionStore.getState().createInstance({
-    agentType: typeKey,
-    title: '',
-    threadId: null,
-    source: { kind: 'dedicated', notebookId, documentPath: null },
-    runtimeConfig: buildInitialInstanceRuntimeConfig(typeKey),
-  }).instanceId;
-}
-
-export function createAndOpenAgentConversation(typeKey: AgentTypeKey, notebookId: string): void {
-  const instance = useAgentSessionStore.getState().createInstance({
-    agentType: typeKey,
-    title: '',
-    threadId: null,
-    source: {
-      kind: 'dedicated',
-      notebookId,
-      documentPath: null,
-    },
-    runtimeConfig: buildInitialInstanceRuntimeConfig(typeKey),
-  });
-  void selectAndOpenAgentConversation(instance.instanceId, { blankIfMissing: true });
-}
-
-/** Create and open a blank, notebook-scoped DSH conversation. */
-export function createAndOpenDshConversation(): void {
-  const notebookId = useNoteStore.getState().selectedNotebook?.id ?? null;
-  const instance = useAgentSessionStore.getState().createInstance({
-    agentType: 'deepseek-harness',
-    title: '',
-    threadId: null,
-    source: {
-      kind: 'dedicated',
-      notebookId,
-      documentPath: null,
-    },
-    runtimeConfig: buildInitialInstanceRuntimeConfig('deepseek-harness'),
-  });
-  void selectAndOpenAgentConversation(instance.instanceId, { blankIfMissing: true });
-}
-
-/** Create and open a blank, notebook-scoped Pi conversation. */
-export function createAndOpenPiConversation(): void {
-  const notebookId = useNoteStore.getState().selectedNotebook?.id ?? null;
-  const instance = useAgentSessionStore.getState().createInstance({
-    agentType: 'pi',
-    title: '',
-    threadId: null,
-    source: {
-      kind: 'dedicated',
-      notebookId,
-      documentPath: null,
-    },
-    runtimeConfig: buildInitialInstanceRuntimeConfig('pi'),
-  });
-  void selectAndOpenAgentConversation(instance.instanceId, { blankIfMissing: true });
+  return { conversationInstances };
 }
diff --git a/app/flowix-web/features/agent/public/workspace-api.ts b/app/flowix-web/features/agent/public/workspace-api.ts
index 12e5d3dad..8aa352850 100644
--- a/app/flowix-web/features/agent/public/workspace-api.ts
+++ b/app/flowix-web/features/agent/public/workspace-api.ts
@@ -1,7 +1,5 @@
-import { resolveNotebookAgentFiles } from '@/lib/agent-access-defaults';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
+import { useAgentWorkspaceStore } from '@features/agent/store/agent-workspace-store';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
-import { normalizeWorkspacePath } from '@features/agent/runtime/workspace-path';
 
 export interface WorkspaceAgentRepository {
   path: string;
@@ -21,12 +19,10 @@ export function hasWorkspaceAgentConversation(instanceId: string): boolean {
 
 /** Resolve resource roots without exposing Agent access configuration stores. */
 export function getWorkspaceAgentResourceFolders(notebookId: string | null): string[] {
-  const access = useAgentAccessStore.getState();
-  return resolveNotebookAgentFiles(
-    access.config,
-    access.notebookConfigs,
-    notebookId,
-  )?.folders ?? [];
+  if (!notebookId) return [];
+  return useAgentWorkspaceStore.getState().workspace.byNotebookId[notebookId]
+    ?.addDirs.filter((directory) => directory.enabled && !directory.missing)
+    .map((directory) => directory.path) ?? [];
 }
 
 /** Resolve the same notebook-scoped repository list used by Agent access settings. */
@@ -34,29 +30,12 @@ export function getWorkspaceAgentRepositories(
   notebookId: string | null,
 ): WorkspaceAgentRepository[] {
   if (!notebookId) return [];
-  const access = useAgentAccessStore.getState();
-  const paths = resolveNotebookAgentFiles(
-    access.config,
-    access.notebookConfigs,
-    notebookId,
-  )?.folders ?? [];
-  const localDirectories = access.notebookConfigs[notebookId]?.addDirs ?? [];
-  return paths.map((path) => {
-    const key = normalizeWorkspacePath(path).toLowerCase();
-    const local = localDirectories.find(
-      (item) => normalizeWorkspacePath(item.path).toLowerCase() === key,
-    );
-    const entry = access.config.entries.find(
-      (item) => normalizeWorkspacePath(item.path).toLowerCase() === key,
-    );
-    const trimmed = path.replace(/[\\/]+$/, '');
-    return {
-      path,
-      name: local?.label?.trim()
-        || entry?.name?.trim()
-        || trimmed.split(/[\\/]/).pop()
-        || trimmed,
-      missing: entry ? entry.missing === true : true,
-    };
-  });
+  const notebook = useAgentWorkspaceStore.getState().workspace.byNotebookId[notebookId];
+  return (notebook?.addDirs ?? [])
+    .filter((directory) => directory.enabled && !directory.missing)
+    .map((directory) => ({
+      path: directory.path,
+      name: directory.label,
+      missing: directory.missing,
+    }));
 }
diff --git a/app/flowix-web/features/agent/runtime/agent-availability.ts b/app/flowix-web/features/agent/runtime/agent-availability.ts
new file mode 100644
index 000000000..99c89228b
--- /dev/null
+++ b/app/flowix-web/features/agent/runtime/agent-availability.ts
@@ -0,0 +1,18 @@
+import type { AgentRuntimeSnapshot, AgentType, AgentTypeKey } from '@/types/agent';
+import { AGENT_TYPES, isAgentTypeSelectable } from '@/lib/agent-types';
+import { normalizeAgentRuntimeStatus } from './agent-runtime-status';
+
+type RuntimeStatusByType = Partial<Record<AgentTypeKey, AgentRuntimeSnapshot>>;
+
+/** Agent choices shared by menus require a ready runtime and an enabled preference. */
+export function getAvailableAgentTypes(
+  statusByType: RuntimeStatusByType,
+  isChecking: boolean,
+  isEnabled: (typeKey: AgentTypeKey) => boolean,
+): AgentType[] {
+  return AGENT_TYPES.filter((type) => (
+    isAgentTypeSelectable(type.id)
+      && isEnabled(type.id)
+      && normalizeAgentRuntimeStatus(statusByType[type.id], isChecking).state === 'ready'
+  ));
+}
diff --git a/app/flowix-web/features/agent/runtime/agent-runtime-spec.test.ts b/app/flowix-web/features/agent/runtime/agent-runtime-spec.test.ts
index 6bf5b2312..62903f401 100644
--- a/app/flowix-web/features/agent/runtime/agent-runtime-spec.test.ts
+++ b/app/flowix-web/features/agent/runtime/agent-runtime-spec.test.ts
@@ -25,8 +25,8 @@ describe("workspace capabilities", () => {
     expect(codex.switchBetweenRuns).toBe(false);
     expect(codex.switchRequiresRuntimeRestart).toBe(false);
     expect(codex.preservesConversationSession).toBe(true);
-    expect(getAgentRuntimeSpec("deepseek-harness").workspace.switchBetweenRuns).toBe(false);
-    for (const type of ["claude", "opencode"] as const) {
+    expect(getAgentRuntimeSpec("dsh").workspace.switchBetweenRuns).toBe(false);
+    for (const type of ["claudecode", "opencode"] as const) {
       expect(getAgentRuntimeSpec(type).workspace.switchBetweenRuns).toBe(false);
     }
   });
@@ -70,7 +70,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("完全没输入时返回 cwd=undefined / workspacePaths=[] (dispatch 据此判断是否拦截)", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "claude",
+      typeKey: "claudecode",
       permissionMode: "workspace-write",
       codexModel: "inherit",
       codexReasoningEffort: "low",
@@ -81,7 +81,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("资料目录始终是 add-dir, cwd 固定为当前笔记本", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "D:\\当前笔记本",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -101,7 +101,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("没有显式主空间时 cwd 仍固定为笔记本", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "D:\\当前笔记本",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -118,7 +118,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("资料列表为空 (没添加资料), cwd 退到当前笔记本路径", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "D:\\当前笔记本",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -131,7 +131,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("未传 defaultFiles 时, 仅当前笔记本作为 cwd", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "claude",
+      typeKey: "claudecode",
       notebookPath: "D:\\当前笔记本",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -189,7 +189,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("DeepSeek Harness exposes model before mode and permission and sends the card overrides", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "/tmp/notebook",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -203,7 +203,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
     expect(result.deepseekHarness?.mode).toBe("code");
     expect(result.deepseekHarness?.model).toBe("deepseek-v4-pro");
     expect(result.deepseekHarness?.providerId).toBe("provider-b");
-    expect(getAgentRuntimeSpec("deepseek-harness").emptySettings).toEqual([
+    expect(getAgentRuntimeSpec("dsh").emptySettings).toEqual([
       "model",
       "mode",
       "permission",
@@ -212,7 +212,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("DeepSeek Harness inherit 时不序列化模型, 选定后透传卡片模型", () => {
     const inherited = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "/tmp/project",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -221,7 +221,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
     expect(inherited.deepseekHarness?.model).toBe("inherit");
 
     const selected = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "/tmp/project",
       permissionMode: "workspace-write",
       codexModel: "deepseek-v4-pro",
@@ -231,13 +231,13 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
   });
 
   it("DeepSeek Harness supports empty-card runtime settings for files (空状态设置区仍可用)", () => {
-    expect(supportsAgentEmptySettings("deepseek-harness")).toBe(true);
+    expect(supportsAgentEmptySettings("dsh")).toBe(true);
     expect(supportsAgentEmptySettings("codex")).toBe(true);
-    expect(supportsAgentEmptySettings("claude")).toBe(true);
-    expect(supportsAgentEmptySettings("deepseek-harness")).toBe(true);
-    expect(supportsAgentRuntimeSetting("deepseek-harness", "model")).toBe(true);
-    expect(supportsAgentRuntimeSetting("deepseek-harness", "mode")).toBe(true);
-    expect(supportsAgentRuntimeSetting("deepseek-harness", "permission")).toBe(true);
+    expect(supportsAgentEmptySettings("claudecode")).toBe(true);
+    expect(supportsAgentEmptySettings("dsh")).toBe(true);
+    expect(supportsAgentRuntimeSetting("dsh", "model")).toBe(true);
+    expect(supportsAgentRuntimeSetting("dsh", "mode")).toBe(true);
+    expect(supportsAgentRuntimeSetting("dsh", "permission")).toBe(true);
   });
 
   it("omits yolo from Codex App Server access options", () => {
@@ -246,7 +246,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
       "workspace-write",
       "read-only",
     ]);
-    expect(getAgentAccessOptions("claude").map((option) => option.id)).not.toContain(
+    expect(getAgentAccessOptions("claudecode").map((option) => option.id)).not.toContain(
       "yolo",
     );
   });
@@ -266,7 +266,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("migrates legacy Claude yolo selection to full access", () => {
     const result = buildAgentRuntimeConfig({
-      typeKey: "claude",
+      typeKey: "claudecode",
       notebookPath: "/tmp/project",
       permissionMode: "yolo",
       codexModel: "inherit",
@@ -294,7 +294,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
 
   it("DeepSeek Harness 卡片显式选择的权限仍生效", () => {
     const explicit = buildAgentRuntimeConfig({
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
       notebookPath: "/tmp/project",
       permissionMode: "workspace-write",
       codexModel: "inherit",
@@ -307,7 +307,7 @@ describe("buildAgentRuntimeConfig — 「资料列表 + 当前笔记本」派生
   });
 
   it("DeepSeek Harness 权限选项不含 yolo, 默认完全访问", () => {
-    expect(getAgentAccessOptions("deepseek-harness").map((o) => o.id)).toEqual([
+    expect(getAgentAccessOptions("dsh").map((o) => o.id)).toEqual([
       "danger-full-access",
       "workspace-write",
       "read-only",
diff --git a/app/flowix-web/features/agent/runtime/agent-runtime-spec.ts b/app/flowix-web/features/agent/runtime/agent-runtime-spec.ts
index 8aa735591..aa8541205 100644
--- a/app/flowix-web/features/agent/runtime/agent-runtime-spec.ts
+++ b/app/flowix-web/features/agent/runtime/agent-runtime-spec.ts
@@ -4,6 +4,7 @@ import type {
   AgentCodexServiceTier,
   AgentPermissionMode,
   AgentRuntimeConfig,
+  AgentId,
   AgentTypeKey,
   FilesConfig,
   RuntimeConfig,
@@ -16,6 +17,7 @@ import {
 } from "@features/agent/config/codex-options";
 import { resolvePrimaryWorkspace } from "@features/agent/runtime/primary-workspace";
 import { normalizeWorkspacePath } from "@features/agent/runtime/workspace-path";
+import { normalizeAgentId } from "@/lib/agent-types";
 
 export type AgentRuntimeSettingKind =
   | "model"
@@ -31,6 +33,25 @@ export interface AgentAccessOption {
   labelKey?: I18nKey;
 }
 
+export interface AgentModeOption {
+  id: string;
+  label: string;
+  labelKey?: I18nKey;
+  descriptionKey?: I18nKey;
+}
+
+export const DEEPSEEK_HARNESS_MODE_OPTIONS = [
+  { id: "standard", label: "Standard", labelKey: "agent.mode.standard", descriptionKey: "agent.mode.standard.description" },
+  { id: "code", label: "Code", labelKey: "agent.mode.code", descriptionKey: "agent.mode.code.description" },
+  { id: "minimal", label: "Minimal", labelKey: "agent.mode.minimal", descriptionKey: "agent.mode.minimal.description" },
+  { id: "cordis", label: "Cordis", labelKey: "agent.mode.cordis", descriptionKey: "agent.mode.cordis.description" },
+] as const satisfies readonly AgentModeOption[];
+
+export const PI_MODE_OPTIONS = [
+  { id: "writing", label: "Writing", labelKey: "agent.mode.writing" },
+  { id: "code", label: "Code", labelKey: "agent.mode.piCode" },
+] as const satisfies readonly AgentModeOption[];
+
 export interface BuildAgentRuntimeConfigInput {
   typeKey: AgentTypeKey;
   /** 当前笔记本路径 (= systemReminderDirectory), always used as cwd. */
@@ -52,6 +73,7 @@ export interface AgentRuntimeSpec {
   typeKey: AgentTypeKey;
   emptySettings: readonly AgentRuntimeSettingKind[];
   accessOptions: readonly AgentAccessOption[];
+  modeOptions: readonly AgentModeOption[];
   workspace: {
     selectBeforeFirstRun: boolean;
     /** Whether selection remains editable while the current run is active. */
@@ -82,8 +104,6 @@ const DSH_ACCESS_OPTIONS: readonly AgentAccessOption[] = [
 
 const CLAUDE_ACCESS_OPTIONS = SHARED_ACCESS_OPTIONS;
 
-const NO_ACCESS_OPTIONS: readonly AgentAccessOption[] = [];
-
 export function normalizeCodexPermissionMode(
   mode: AgentPermissionMode | undefined,
 ): AgentPermissionMode {
@@ -109,11 +129,12 @@ export function normalizeDshPermissionMode(
     : "danger-full-access";
 }
 
-const AGENT_RUNTIME_SPECS: Record<AgentTypeKey, AgentRuntimeSpec> = {
+const AGENT_RUNTIME_SPECS: Record<AgentId, AgentRuntimeSpec> = {
   codex: {
     typeKey: "codex",
     emptySettings: ["model", "reasoning", "permission"],
     accessOptions: CODEX_APP_SERVER_ACCESS_OPTIONS,
+    modeOptions: [],
     // The notebook owns cwd; conversation snapshots freeze it at first send.
     workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: false, preservesConversationSession: true },
     buildRuntimeConfig: ({
@@ -134,10 +155,11 @@ const AGENT_RUNTIME_SPECS: Record<AgentTypeKey, AgentRuntimeSpec> = {
       },
     }),
   },
-  claude: {
-    typeKey: "claude",
+  claudecode: {
+    typeKey: "claudecode",
     emptySettings: ["model", "permission"],
     accessOptions: CLAUDE_ACCESS_OPTIONS,
+    modeOptions: [],
     workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: false, preservesConversationSession: false },
     buildRuntimeConfig: ({ cwd, workspacePaths, permissionMode, codexModel }) => ({
       // 统一归一化: 持久化或历史数据中的 yolo 视作 danger-full-access,
@@ -145,37 +167,21 @@ const AGENT_RUNTIME_SPECS: Record<AgentTypeKey, AgentRuntimeSpec> = {
       claude: { cwd, workspacePaths, permissionMode: normalizeCodexPermissionMode(permissionMode), model: codexModel },
     }),
   },
-  gemini: {
-    typeKey: "gemini",
-    emptySettings: [],
-    accessOptions: NO_ACCESS_OPTIONS,
-    workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: false, preservesConversationSession: false },
-    buildRuntimeConfig: ({ cwd, workspacePaths }) => ({
-      gemini: { cwd, workspacePaths },
-    }),
-  },
   hermes: {
     typeKey: "hermes",
     emptySettings: ["permission"],
     accessOptions: HERMES_ACCESS_OPTIONS,
+    modeOptions: [],
     workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: false, preservesConversationSession: false },
     buildRuntimeConfig: ({ cwd, workspacePaths, permissionMode }) => ({
       hermes: { cwd, workspacePaths, permissionMode },
     }),
   },
-  openclaw: {
-    typeKey: "openclaw",
-    emptySettings: [],
-    accessOptions: NO_ACCESS_OPTIONS,
-    workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: false, preservesConversationSession: false },
-    buildRuntimeConfig: ({ cwd, workspacePaths }) => ({
-      openclaw: { cwd, workspacePaths },
-    }),
-  },
   opencode: {
     typeKey: "opencode",
     emptySettings: ["model", "permission"],
     accessOptions: SHARED_ACCESS_OPTIONS,
+    modeOptions: [],
     workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: false, preservesConversationSession: false },
     buildRuntimeConfig: ({ cwd, workspacePaths, permissionMode, codexModel }) => ({
       opencode: { cwd, workspacePaths, permissionMode, model: codexModel },
@@ -188,6 +194,7 @@ const AGENT_RUNTIME_SPECS: Record<AgentTypeKey, AgentRuntimeSpec> = {
     // codemode follows the shared Pi preference across conversations.
     emptySettings: ["model", "mode", "permission"],
     accessOptions: SHARED_ACCESS_OPTIONS,
+    modeOptions: PI_MODE_OPTIONS,
     workspace: { selectBeforeFirstRun: false, switchWhileRunning: false, switchBetweenRuns: false, switchRequiresRuntimeRestart: true, preservesConversationSession: true },
     buildRuntimeConfig: ({ cwd, workspacePaths, permissionMode, codexModel }) => ({
       pi: {
@@ -199,14 +206,15 @@ const AGENT_RUNTIME_SPECS: Record<AgentTypeKey, AgentRuntimeSpec> = {
       },
     }),
   },
-  "deepseek-harness": {
-    typeKey: "deepseek-harness",
+  dsh: {
+    typeKey: "dsh",
     // DSH follows the native llm-pi-ai provider configuration but allows a per-card
     // model override (runtime_config.deepseek_harness.model, "inherit" falls
     // back to the global dsh-settings model). Its tool Agent preset and
     // per-card permission mode are configurable here as well.
     emptySettings: ["model", "mode", "permission"],
     accessOptions: DSH_ACCESS_OPTIONS,
+    modeOptions: DEEPSEEK_HARNESS_MODE_OPTIONS,
     // Harness session resume restores the session's original cwd. Until DSH
     // exposes a resume-with-cwd capability, changing workspace would be
     // misleading, even if Flowix can restart the transport.
@@ -229,7 +237,7 @@ const AGENT_RUNTIME_SPECS: Record<AgentTypeKey, AgentRuntimeSpec> = {
 };
 
 export function getAgentRuntimeSpec(typeKey: AgentTypeKey): AgentRuntimeSpec {
-  return AGENT_RUNTIME_SPECS[typeKey];
+  return AGENT_RUNTIME_SPECS[normalizeAgentId(typeKey) ?? "codex"];
 }
 
 export function supportsAgentRuntimeSetting(
@@ -252,6 +260,12 @@ export function getAgentAccessOptions(
   return getAgentRuntimeSpec(typeKey).accessOptions;
 }
 
+export function getAgentModeOptions(
+  typeKey: AgentTypeKey,
+): readonly AgentModeOption[] {
+  return getAgentRuntimeSpec(typeKey).modeOptions;
+}
+
 export function buildAgentRuntimeConfig({
   typeKey,
   notebookPath,
@@ -265,7 +279,7 @@ export function buildAgentRuntimeConfig({
   workspaceSnapshot,
 }: BuildAgentRuntimeConfigInput): AgentRuntimeConfig {
   // cwd is always the selected notebook path.  `defaultFiles.folders` are
-  // notebook-local add-dir roots from `.flowix/agent.json`; they are sent as
+  // notebook add-dir roots from local.db; they are sent as
   // workspacePaths and are kept separate from cwd.  Once a run starts, the
   // persisted workspace snapshot remains authoritative for later turns.
   const frozenPaths = (workspaceSnapshot?.workspacePaths ?? [])
@@ -301,7 +315,8 @@ export function buildAgentRuntimeConfig({
     codexServiceTier:
       instanceRuntimeConfig?.serviceTier ?? codexServiceTier,
   });
-  if (typeKey === "deepseek-harness" && runtimeConfig.deepseekHarness) {
+  runtimeConfig.notebookId = workspaceSnapshot?.notebookId ?? instanceRuntimeConfig?.notebookId;
+  if (normalizeAgentId(typeKey) === "dsh" && runtimeConfig.deepseekHarness) {
     runtimeConfig.deepseekHarness.mode =
       instanceRuntimeConfig?.deepseekHarness?.mode ?? "standard";
     runtimeConfig.deepseekHarness.providerId =
diff --git a/app/flowix-web/features/agent/runtime/agent-runtime-status.test.ts b/app/flowix-web/features/agent/runtime/agent-runtime-status.test.ts
index 3843ec3e6..c8da19118 100644
--- a/app/flowix-web/features/agent/runtime/agent-runtime-status.test.ts
+++ b/app/flowix-web/features/agent/runtime/agent-runtime-status.test.ts
@@ -17,10 +17,10 @@ describe('normalizeAgentRuntimeStatus', () => {
     });
   });
 
-  it('maps an unavailable runtime without installation to not-installed', () => {
+  it('maps a missing installation to not-installed', () => {
     expect(normalizeAgentRuntimeStatus({
-      available: false,
-      installed: false,
+      installation: 'missing',
+      readiness: 'unknown',
       reason: 'CLI not configured',
     })).toEqual({
       state: 'not-installed',
@@ -30,8 +30,8 @@ describe('normalizeAgentRuntimeStatus', () => {
 
   it('keeps installed-but-unready distinct from not-installed', () => {
     expect(normalizeAgentRuntimeStatus({
-      available: false,
-      installed: true,
+      installation: 'installed',
+      readiness: 'blocked',
       reason: 'No model configured',
     })).toEqual({
       state: 'not-ready',
@@ -39,26 +39,30 @@ describe('normalizeAgentRuntimeStatus', () => {
     });
   });
 
-  it('supports legacy payloads that only contain available', () => {
-    expect(normalizeAgentRuntimeStatus({ available: true })).toEqual({
-      state: 'ready',
-      reason: null,
-    });
-    expect(normalizeAgentRuntimeStatus({ available: false })).toEqual({
-      state: 'not-installed',
-      reason: null,
+  it('keeps unknown detection separate from a missing installation', () => {
+    expect(normalizeAgentRuntimeStatus({
+      installation: 'unknown',
+      readiness: 'unknown',
+      reason: 'Detection pending',
+    })).toEqual({
+      state: 'unknown',
+      reason: 'Detection pending',
     });
+    expect(normalizeAgentRuntimeStatus({
+      installation: 'installed',
+      readiness: 'ready',
+    })).toEqual({ state: 'ready', reason: null });
   });
 });
 
 describe('normalizeAgentRuntimeStatusByType', () => {
   it('normalizes the known entries without inventing missing entries', () => {
     expect(normalizeAgentRuntimeStatusByType({
-      codex: { available: true, installed: true },
-      claude: { available: false, installed: true, reason: 'Needs setup' },
+      codex: { installation: 'installed', readiness: 'ready' },
+      claudecode: { installation: 'installed', readiness: 'blocked', reason: 'Needs setup' },
     })).toEqual({
       codex: { state: 'ready', reason: null },
-      claude: { state: 'not-ready', reason: 'Needs setup' },
+      claudecode: { state: 'not-ready', reason: 'Needs setup' },
     });
   });
 });
diff --git a/app/flowix-web/features/agent/runtime/agent-runtime-status.ts b/app/flowix-web/features/agent/runtime/agent-runtime-status.ts
index 7c1792a8e..76c7d15e4 100644
--- a/app/flowix-web/features/agent/runtime/agent-runtime-status.ts
+++ b/app/flowix-web/features/agent/runtime/agent-runtime-status.ts
@@ -1,13 +1,10 @@
-import type { AgentRuntimeAvailability } from '@platform/tauri/client';
-import type { AgentTypeKey } from '@/types/agent';
+import type { AgentTypeKey, AgentRuntimeSnapshot } from '@/types/agent';
 
 /**
  * Small, UI-facing state model for one local Agent runtime.
  *
- * `AgentRuntimeAvailability` is the IPC shape and intentionally stays close
- * to the backend. Consumers should eventually depend on this normalized state
- * instead of reconstructing meaning from `available`, `installed`, and
- * free-form `reason` independently.
+ * Runtime status is split into installation presence and launch readiness.
+ * UI state is derived here so consumers don't reinterpret those facts.
  */
 export type AgentRuntimeState =
   | 'unknown'
@@ -27,14 +24,9 @@ export function isAgentRuntimeInstalledState(status: AgentRuntimeStatusView): bo
   return status.state === 'ready' || status.state === 'not-ready';
 }
 
-/**
- * Convert the backend availability shape into the shared UI vocabulary.
- *
- * The optional `installed` field keeps this compatible with older IPC payloads:
- * before the field exists, `available` is the best available installation hint.
- */
+/** Convert the backend installation/readiness protocol into shared UI states. */
 export function normalizeAgentRuntimeStatus(
-  status: AgentRuntimeAvailability | undefined,
+  status: AgentRuntimeSnapshot | undefined,
   isChecking = false,
 ): AgentRuntimeStatusView {
   if (!status) {
@@ -44,19 +36,22 @@ export function normalizeAgentRuntimeStatus(
     };
   }
 
-  const installed = status.installed ?? status.available;
+  if (status.installation === 'missing') {
+    return { state: 'not-installed', reason: status.reason ?? null };
+  }
+
+  if (status.installation === 'unknown' || status.readiness === 'unknown') {
+    return { state: isChecking ? 'checking' : 'unknown', reason: status.reason ?? null };
+  }
+
   return {
-    state: !installed
-      ? 'not-installed'
-      : status.available
-        ? 'ready'
-        : 'not-ready',
+    state: status.readiness === 'ready' ? 'ready' : 'not-ready',
     reason: status.reason ?? null,
   };
 }
 
 export function normalizeAgentRuntimeStatusByType(
-  statusByType: Partial<Record<AgentTypeKey, AgentRuntimeAvailability>>,
+  statusByType: Partial<Record<AgentTypeKey, AgentRuntimeSnapshot>>,
   isChecking = false,
 ): AgentRuntimeStatusViewByType {
   return Object.fromEntries(
diff --git a/app/flowix-web/features/agent/runtime/new-conversation-agent-selection.ts b/app/flowix-web/features/agent/runtime/new-conversation-agent-selection.ts
new file mode 100644
index 000000000..9d530f473
--- /dev/null
+++ b/app/flowix-web/features/agent/runtime/new-conversation-agent-selection.ts
@@ -0,0 +1,29 @@
+import type { AgentRuntimeSnapshot, AgentType, AgentTypeKey } from '@/types/agent';
+import { getAgentType } from '@/lib/agent-types';
+import { getAvailableAgentTypes } from './agent-availability';
+
+type RuntimeStatusByType = Partial<Record<AgentTypeKey, AgentRuntimeSnapshot>>;
+
+export type NewConversationAgentSelection =
+  | { kind: 'create'; agentType: AgentTypeKey; options: AgentType[] }
+  | { kind: 'choose'; options: AgentType[] }
+  | { kind: 'none'; options: [] };
+
+/** Prefer ready, enabled runtimes; use Pi as a fallback unless the user disabled it. */
+export function getNewConversationAgentSelection(
+  statusByType: RuntimeStatusByType,
+  isChecking: boolean,
+  isEnabled: (typeKey: AgentTypeKey) => boolean,
+): NewConversationAgentSelection {
+  const availableAgents = getAvailableAgentTypes(statusByType, isChecking, isEnabled);
+  const options = availableAgents.length > 0
+    ? availableAgents
+    : isEnabled('pi') ? [getAgentType('pi')] : [];
+
+  if (options.length === 0) return { kind: 'none', options: [] };
+
+  if (options.length === 1) {
+    return { kind: 'create', agentType: options[0]!.id, options };
+  }
+  return { kind: 'choose', options };
+}
diff --git a/app/flowix-web/features/agent/runtime/pi-history.ts b/app/flowix-web/features/agent/runtime/pi-history.ts
index abb36809d..0acf9f93c 100644
--- a/app/flowix-web/features/agent/runtime/pi-history.ts
+++ b/app/flowix-web/features/agent/runtime/pi-history.ts
@@ -30,6 +30,22 @@ function toolResultText(message: JsonRecord): string {
   return message.isError === true ? `[error] ${text || "Tool failed"}` : text;
 }
 
+function codemodeChildCallIds(messages: JsonRecord[]): Set<string> {
+  const ids = new Set<string>();
+  for (const message of messages) {
+    if (message.role !== "toolResult" || message.toolName !== "codemode") continue;
+    for (const container of [record(message.nestedCalls), record(message.details)]) {
+      const calls = container?.calls;
+      if (!Array.isArray(calls)) continue;
+      for (const value of calls) {
+        const id = record(value)?.id;
+        if (typeof id === "string" && id) ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
 function bashExecutionText(message: JsonRecord): string {
   const output = typeof message.output === "string" ? message.output : "";
   const exitCode = typeof message.exitCode === "number" ? message.exitCode : null;
@@ -59,6 +75,7 @@ export function parsePiHistoryMessages(
   if (!Array.isArray(values)) return [];
   const native = values.map(record).filter((value): value is JsonRecord => value !== null);
   const resultsByCallId = new Map<string, JsonRecord>();
+  const nestedCodemodeCallIds = codemodeChildCallIds(native);
   for (const message of native) {
     if (message.role === "toolResult" && typeof message.toolCallId === "string") {
       resultsByCallId.set(message.toolCallId, message);
@@ -118,7 +135,11 @@ export function parsePiHistoryMessages(
           rows.push(textRow);
         } else if (block.type === "thinking" && typeof block.thinking === "string" && block.thinking) {
           rows.push({ order: blockIndex, type: "thinking", content: block.thinking });
-        } else if (block.type === "toolCall" && typeof block.id === "string") {
+        } else if (
+          block.type === "toolCall" &&
+          typeof block.id === "string" &&
+          !nestedCodemodeCallIds.has(block.id)
+        ) {
           rows.push({ order: blockIndex, type: "tool", block });
         }
       });
diff --git a/app/flowix-web/features/agent/runtime/primary-workspace.ts b/app/flowix-web/features/agent/runtime/primary-workspace.ts
index da4a3f1fb..e85dd469d 100644
--- a/app/flowix-web/features/agent/runtime/primary-workspace.ts
+++ b/app/flowix-web/features/agent/runtime/primary-workspace.ts
@@ -1,6 +1,6 @@
 /**
  * Resolve the sole primary workspace.  A notebook is always the agent cwd;
- * folders from `.flowix/agent.json` are add-dir roots and never participate
+ * folders from `local.db` are add-dir roots and never participate
  * in cwd selection.  The `defaultFiles` argument remains for API compatibility
  * with persisted/legacy callers, but is intentionally ignored here.
  */
diff --git a/app/flowix-web/features/agent/runtime/workspace-snapshot.test.ts b/app/flowix-web/features/agent/runtime/workspace-snapshot.test.ts
index f41242b93..7ff41d2c2 100644
--- a/app/flowix-web/features/agent/runtime/workspace-snapshot.test.ts
+++ b/app/flowix-web/features/agent/runtime/workspace-snapshot.test.ts
@@ -63,9 +63,25 @@ vi.mock("@features/memo/store/note-store", () => ({
   },
 }));
 
-vi.mock("@features/agent/store/agent-access-store", () => ({
-  useAgentAccessStore: { getState: () => ({ config: state.accessConfig }) },
-}));
+vi.mock("@features/agent/store/agent-workspace-store", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@features/agent/store/agent-workspace-store")>();
+  const getState = () => ({
+      ...actual.useAgentWorkspaceStore.getState(),
+      workspaceActions: {
+        ...actual.useAgentWorkspaceStore.getState().workspaceActions,
+        getNotebookFiles: () => ({
+          workspace: null,
+          folders: state.accessConfig.defaults.files["nb-1"].folders,
+          notebooks: [],
+        }),
+      },
+    });
+  return { ...actual, useAgentWorkspaceStore: Object.assign(
+    (selector: Parameters<typeof actual.useAgentWorkspaceStore>[0]) => selector ? selector(getState()) : getState(),
+    actual.useAgentWorkspaceStore,
+    { getState },
+  ) };
+});
 
 describe("conversation workspace snapshot", () => {
   beforeEach(() => {
diff --git a/app/flowix-web/features/agent/runtime/workspace-snapshot.ts b/app/flowix-web/features/agent/runtime/workspace-snapshot.ts
index c43e1a39f..96fed679e 100644
--- a/app/flowix-web/features/agent/runtime/workspace-snapshot.ts
+++ b/app/flowix-web/features/agent/runtime/workspace-snapshot.ts
@@ -1,8 +1,7 @@
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
 import type { RuntimeConfig, WorkspaceSnapshot } from "@/types/agent";
-import { resolveNotebookAgentFiles } from "@/lib/agent-access-defaults";
 import { resolvePrimaryWorkspace } from "@features/agent/runtime/primary-workspace";
 import { normalizeWorkspacePath } from "@features/agent/runtime/workspace-path";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
 import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
 import { useNoteStore } from "@features/memo/store/note-store";
 import {
@@ -146,12 +145,7 @@ export function ensureConversationWorkspaceSnapshot(
 
   let snapshot = migrateLegacyWorkspace(runtimeConfig, notebookId, notebookPath);
   if (!snapshot) {
-    const accessState = useAgentAccessStore.getState();
-    const defaultFiles = resolveNotebookAgentFiles(
-      accessState.config,
-      accessState.notebookConfigs,
-      notebookId,
-    );
+    const defaultFiles = useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles(notebookId);
     const primary = resolvePrimaryWorkspace({ defaultFiles, notebookPath });
     if (primary.kind === "empty") {
       // Do not permanently freeze an empty startup/hydration race.
diff --git a/app/flowix-web/features/agent/services/agent-catalog-service.ts b/app/flowix-web/features/agent/services/agent-catalog-service.ts
new file mode 100644
index 000000000..ce99e7c37
--- /dev/null
+++ b/app/flowix-web/features/agent/services/agent-catalog-service.ts
@@ -0,0 +1,186 @@
+import type { AgentCodexReasoningEffort, AgentTypeKey } from "@/types/agent";
+import { getFallbackAgentModelOptions } from "@features/agent/config/agent-model-options";
+import { formatModelDisplayLabel } from "@features/agent/config/codex-options";
+import { listCodexSkillCatalog } from "@features/agent/services/codex-slash-command-service";
+import { listPiSkills } from "@features/agent/services/pi-slash-command-service";
+import {
+  type AgentCatalogModel,
+  type AgentCatalogSkill,
+  type AgentModelCatalog,
+  useAgentDataStore,
+} from "@features/agent/store/agent-data-store";
+import { agent, deepseekHarness, piModels } from "@platform/tauri/client";
+
+const SUPPORTED_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"];
+
+/** Loads a provider catalog through the shared persistent cache. */
+export function loadAgentModelCatalog(
+  agentType: AgentTypeKey,
+  options: { force?: boolean } = {},
+): Promise<AgentModelCatalog> {
+  const store = useAgentDataStore.getState();
+  return store.loadModelCatalog(
+    agentType,
+    () => fetchAgentModelCatalog(agentType),
+    { force: options.force },
+  ).catch((error) => {
+    const cached = useAgentDataStore.getState().agents[agentType].catalog.models;
+    if (cached.items.length) return cached;
+    const fallback = getStaticModelCatalog(agentType);
+    if (!fallback.items.length) throw error;
+    store.setModelCatalog(agentType, fallback);
+    return fallback;
+  });
+}
+
+/** Start catalog refreshes after runtime discovery without blocking the UI. */
+export function prefetchAvailableAgentModels(
+  available: Partial<Record<AgentTypeKey, boolean>>,
+): void {
+  for (const [agentType, isAvailable] of Object.entries(available) as [AgentTypeKey, boolean][]) {
+    if (!isAvailable) continue;
+    void loadAgentModelCatalog(agentType).catch((error) => {
+      console.warn(`[agent-catalog] failed to load ${agentType} models`, error);
+    });
+  }
+}
+
+/** Warm project skills for notebook-scoped Agent adapters that need no session. */
+export function prefetchNotebookSkills(
+  agentType: "codex" | "pi",
+  notebookId: string,
+  notebookPath: string,
+): void {
+  void loadNotebookSkillCatalog(agentType, notebookId, notebookPath).catch((error) => {
+    console.warn(`[agent-catalog] failed to load ${agentType} skills`, error);
+  });
+}
+
+/** Load a notebook-scoped skill catalog through the shared persistent cache. */
+export function loadNotebookSkillCatalog(
+  agentType: "codex" | "pi",
+  notebookId: string,
+  notebookPath: string,
+  options: { force?: boolean } = {},
+): Promise<AgentCatalogSkill[]> {
+  const path = notebookPath.trim();
+  if (!path) return Promise.resolve([]);
+  const loader = agentType === "codex"
+    ? () => listCodexSkillCatalog(path)
+    : () => listPiSkills(path);
+  return useAgentDataStore.getState().loadSkillCatalog(
+    agentType,
+    notebookId,
+    async () => [...await loader()] as AgentCatalogSkill[],
+    { force: options.force },
+  );
+}
+
+export function invalidateAgentModelCatalog(agentType: AgentTypeKey): void {
+  useAgentDataStore.getState().invalidateModelCatalog(agentType);
+}
+
+/** Invalidate and immediately refresh a model catalog after its config changes. */
+export function refreshAgentModelCatalog(agentType: AgentTypeKey): Promise<AgentModelCatalog> {
+  invalidateAgentModelCatalog(agentType);
+  return loadAgentModelCatalog(agentType, { force: true });
+}
+
+export function invalidateNotebookSkills(agentType: AgentTypeKey, notebookId: string): void {
+  useAgentDataStore.getState().invalidateSkillCatalog(agentType, notebookId);
+}
+
+async function fetchAgentModelCatalog(agentType: AgentTypeKey): Promise<AgentModelCatalog> {
+  if (agentType === "pi") {
+    const [providers, models] = await Promise.all([piModels.list(), agent.listSupportedModels("pi")]);
+    const defaultProvider = providers.find((provider) => provider.defaultModelId);
+    const providerById = new Map(providers.map((provider) => [provider.id, provider]));
+    const seen = new Set<string>();
+    const items = models.flatMap((model): AgentCatalogModel[] => {
+      const separator = model.indexOf("::");
+      if (separator < 1) return [];
+      const providerId = model.slice(0, separator);
+      const id = model.slice(separator + 2);
+      const key = `${providerId}\u0000${id}`;
+      if (!id || seen.has(key)) return [];
+      seen.add(key);
+      const provider = providerById.get(providerId);
+      const modelConfig = provider?.models.find((entry) => entry.id === id);
+      return [{
+        id,
+        label: modelConfig?.name?.trim() || formatModelDisplayLabel(id),
+        ...(modelConfig?.subtitle?.trim() ? { subtitle: modelConfig.subtitle.trim() } : {}),
+        ...(modelConfig?.creditMultiplier != null ? { creditMultiplier: modelConfig.creditMultiplier } : {}),
+        ...(modelConfig?.providerIconUrl || provider?.iconUrl
+          ? { iconUrl: modelConfig?.providerIconUrl || provider?.iconUrl }
+          : {}),
+        providerId,
+        providerName: provider?.displayName ?? providerId,
+      }];
+    });
+    return {
+      items,
+      defaultModel: defaultProvider?.defaultModelId ?? "",
+      defaultProviderId: defaultProvider?.id,
+    };
+  }
+
+  if (agentType === "dsh") {
+    const configs = await deepseekHarness.list();
+    const preference = useAgentDataStore.getState().agents[agentType].user.model;
+    const firstConfig = configs[0]?.model;
+    const defaultModel = preference?.id && preference.id !== "inherit"
+      ? preference
+      : { id: firstConfig?.model.trim() ?? "", providerId: firstConfig?.providerId?.trim() || undefined };
+    const seen = new Set<string>();
+    const items = configs.flatMap((file): AgentCatalogModel[] => {
+      const config = file.model;
+      const providerId = config.providerId?.trim() || undefined;
+      const providerName = config.displayName?.trim() || config.provider;
+      const models = config.models?.length
+        ? config.models
+        : config.model.trim() ? [{ id: config.model, name: "" }] : [];
+      return models
+        .map((model) => ({ id: model.id.trim(), label: formatModelDisplayLabel(model.id), providerId, providerName }))
+        .filter((model) => model.id.length > 0)
+        .filter((model) => {
+          const key = `${model.providerId ?? model.providerName}\u0000${model.id}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        });
+    });
+    return { items, defaultModel: defaultModel.id, defaultProviderId: defaultModel.providerId };
+  }
+
+  if (agentType === "codex") {
+    const [catalog, defaultModel] = await Promise.all([
+      agent.listCodexModelCatalog(),
+      agent.getCodexDefaultModel().catch(() => ""),
+    ]);
+    const items = catalog.map((model) => ({
+        id: model.id,
+        label: formatModelDisplayLabel(model.id),
+        ...(model.reasoningEfforts?.length
+          ? { reasoningEfforts: model.reasoningEfforts.filter((effort): effort is AgentCodexReasoningEffort =>
+              SUPPORTED_REASONING_EFFORTS.includes(effort),
+            ) }
+          : {}),
+      }));
+    return {
+      items: items.length ? items : getStaticModelCatalog("codex").items,
+      defaultModel: defaultModel.trim(),
+    };
+  }
+
+  const models = await agent.listSupportedModels(agentType);
+  const items = [...new Set(models.map((model) => model.trim()).filter(Boolean))]
+    .map((id) => ({ id, label: formatModelDisplayLabel(id) }));
+  return {
+    items: items.length ? items : getStaticModelCatalog(agentType).items,
+  };
+}
+
+function getStaticModelCatalog(agentType: AgentTypeKey): AgentModelCatalog {
+  return { items: getFallbackAgentModelOptions(agentType) };
+}
diff --git a/app/flowix-web/features/agent/services/codex-slash-command-service.test.ts b/app/flowix-web/features/agent/services/codex-slash-command-service.test.ts
index 5cc06833a..a7d4adbef 100644
--- a/app/flowix-web/features/agent/services/codex-slash-command-service.test.ts
+++ b/app/flowix-web/features/agent/services/codex-slash-command-service.test.ts
@@ -79,7 +79,7 @@ describe("Codex command lifecycle", () => {
     let projection = useAgentSessionStore.getState().threadProjections[threadId];
     expect(projection?.messages).toMatchObject([
       {
-        id: `codex-command:live:${lifecycle.commandId}`,
+        id: `flowix:codex:command:pending:${lifecycle.commandId}`,
         content: command,
         isLoading: true,
       },
diff --git a/app/flowix-web/features/agent/services/codex-slash-command-service.ts b/app/flowix-web/features/agent/services/codex-slash-command-service.ts
index ac06d0828..37ddfc028 100644
--- a/app/flowix-web/features/agent/services/codex-slash-command-service.ts
+++ b/app/flowix-web/features/agent/services/codex-slash-command-service.ts
@@ -119,10 +119,16 @@ function asCatalogItem(value: unknown): CodexSkillCatalogItem | null {
 
 /** Read project-scoped Codex skills without creating a model turn. */
 export async function listCodexSkills(cwd: string): Promise<readonly ComposerSlashSkill[]> {
+  if (!cwd.trim()) return [];
+  return parseCodexSkills(await listCodexSkillCatalog(cwd));
+}
+
+/** Read the full Codex skill catalog, including source metadata used by settings. */
+export async function listCodexSkillCatalog(cwd: string): Promise<readonly CodexSkillCatalogItem[]> {
   if (!cwd.trim()) return [];
   const capabilities = await agent.getCodexProjectCapabilities(cwd);
   if (!capabilities.skills.ok) throw new Error(capabilities.skills.error ?? "Failed to load Codex skills");
-  return parseCodexSkills(capabilities.skills.value);
+  return parseCodexSkillCatalog(capabilities.skills.value);
 }
 
 /** Native Codex commands occupy the same thread as model turns and must keep
diff --git a/app/flowix-web/features/agent/services/composer-submission-service.ts b/app/flowix-web/features/agent/services/composer-submission-service.ts
index 4469b3a72..d64be4674 100644
--- a/app/flowix-web/features/agent/services/composer-submission-service.ts
+++ b/app/flowix-web/features/agent/services/composer-submission-service.ts
@@ -3,8 +3,10 @@ import { createLogger } from "@/lib/logger";
 import { toast } from "@/lib/toast";
 import { dialogs } from "@platform/tauri/client/desktop";
 import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
+import { createAgentMessageAttachments } from "@features/agent/store/user-message";
 import { markConversationWorkspaceStarted } from "@features/agent/runtime/workspace-snapshot";
 import type { ComposerSubmissionSnapshot } from "@features/agent/thread-card/composer/composer-submission-controller";
+import { isAgentThreadCardImageAttachment } from "@features/agent/thread-card/composer/composer-attachment-types";
 import type { ComposerSubmissionKind } from "@features/agent/thread-card/composer/composer-submission-state";
 import { runDshCommand } from "./dsh-command-service";
 import {
@@ -31,17 +33,20 @@ export async function acceptComposerSubmission(
   kind: ComposerSubmissionKind,
   documentContext?: string,
 ): Promise<void> {
-  const imagePaths = snapshot.images.map((image) => image.path);
+  const imageAttachments = snapshot.attachments.filter(isAgentThreadCardImageAttachment);
+  const imagePaths = imageAttachments.map((image) => image.path);
   if (kind === "message") {
     await useAgentSessionStore.getState().sendMessageToThread(
       bound.threadId, snapshot.prompt, bound.typeKey, {
         instanceId: bound.instanceId, conversationTitle: bound.title,
         runtimeConfig: bound.runtimeConfig, isFirstMessage: bound.isFirstMessage,
         runId: bound.runId,
-        currentNoteContent: documentContext, imagePaths, rejectOnFailure: true,
+        currentNoteContent: documentContext, imagePaths,
+        attachments: createAgentMessageAttachments(imageAttachments),
+        rejectOnFailure: true,
       },
     );
-  } else if (bound.typeKey === "deepseek-harness") {
+  } else if (bound.typeKey === "dsh") {
     await runDshCommand({
       command: snapshot.prompt, imagePaths, rejectOnFailure: true,
       ensureConversation: async () => bound,
diff --git a/app/flowix-web/features/agent/services/dsh-command-service.test.ts b/app/flowix-web/features/agent/services/dsh-command-service.test.ts
index c45af4b7f..576552fb2 100644
--- a/app/flowix-web/features/agent/services/dsh-command-service.test.ts
+++ b/app/flowix-web/features/agent/services/dsh-command-service.test.ts
@@ -12,14 +12,13 @@ vi.mock("@features/agent/store/agent-session-store", () => ({
     reloadMessagesFromHistory: mocks.reload,
   }) },
 }));
-vi.mock("@features/agent/store/agent-access-store", () => ({
-  useAgentAccessStore: { getState: () => ({ config: { entries: [] } }) },
-}));
 vi.mock("@features/memo/store/note-store", () => ({
   useNoteStore: { getState: () => ({ selectedNotebook: null, notebooks: [] }) },
 }));
 vi.mock("@features/agent/runtime/agent-runtime-spec", () => ({
   buildAgentRuntimeConfig: () => ({}),
+  getAgentAccessOptions: () => [],
+  getAgentModeOptions: () => [],
 }));
 
 import { runDshCommand } from "./dsh-command-service";
diff --git a/app/flowix-web/features/agent/services/dsh-command-service.ts b/app/flowix-web/features/agent/services/dsh-command-service.ts
index a57da855c..8f1099812 100644
--- a/app/flowix-web/features/agent/services/dsh-command-service.ts
+++ b/app/flowix-web/features/agent/services/dsh-command-service.ts
@@ -1,3 +1,5 @@
+import { resolveAgentPreferenceRuntimeConfig } from "@features/agent/store/agent-user-preferences";
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
 import type { ChatMessage } from "@/types";
 import { errorMessage } from "@/lib/error-message";
 import type { AgentRuntimeConfig, AgentTypeKey, RuntimeConfig } from "@/types/agent";
@@ -6,13 +8,12 @@ import {
   normalizeWorkspaceSnapshot,
 } from "@features/agent/runtime/workspace-snapshot";
 import { normalizeConversationWorkspaceState } from "@features/agent/runtime/conversation-workspace";
-import { resolveNotebookAgentFiles } from "@/lib/agent-access-defaults";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
 import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
+import { ensureAgentPreferencesReady } from "@features/agent/store/agent-data-store";
 import { useNoteStore } from "@features/memo/store/note-store";
 import { agentClient } from "@features/agent/store/agent-client";
 
-export const DSH_AGENT_TYPE = "deepseek-harness" as const satisfies AgentTypeKey;
+export const DSH_AGENT_TYPE = "dsh" as const satisfies AgentTypeKey;
 
 export function isDshCompactCommand(command: string): boolean {
   return /^\/compact(?:[\t\n\r ]*)$/iu.test(command.trim());
@@ -73,8 +74,7 @@ export function buildDshCommandMessage(
   instanceRuntimeConfig?: RuntimeConfig | null,
   imagePaths: string[] = [],
 ): DshCommandMessage {
-  const session = useAgentSessionStore.getState();
-  const settings = session.sessionMeta.settings;
+  const preferences = resolveAgentPreferenceRuntimeConfig(DSH_AGENT_TYPE, instanceRuntimeConfig ?? undefined);
   const workspaceSnapshot =
     normalizeConversationWorkspaceState(instanceRuntimeConfig)?.desired ??
     normalizeWorkspaceSnapshot(instanceRuntimeConfig?.workspaceSnapshot);
@@ -82,18 +82,17 @@ export function buildDshCommandMessage(
   const notebook = notebookId
     ? useNoteStore.getState().notebooks.find((item) => item.id === notebookId)
     : useNoteStore.getState().selectedNotebook;
-  const accessState = useAgentAccessStore.getState();
   const defaultFiles = !workspaceSnapshot && notebookId
-    ? resolveNotebookAgentFiles(accessState.config, accessState.notebookConfigs, notebookId)
+    ? useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles(notebookId)
     : undefined;
 
   const runtimeConfig = buildAgentRuntimeConfig({
     typeKey: DSH_AGENT_TYPE,
     notebookPath: workspaceSnapshot?.notebookPath ?? notebook?.path,
-    permissionMode: settings.agentPermissionMode,
-    codexModel: settings.agentCodexModel,
-    codexReasoningEffort: settings.agentCodexReasoningEffort,
-    instanceRuntimeConfig: instanceRuntimeConfig ?? undefined,
+    permissionMode: preferences.access?.sandbox ?? "danger-full-access",
+    codexModel: preferences.model?.key ?? "inherit",
+    codexReasoningEffort: preferences.reasoningEffort ?? "medium",
+    instanceRuntimeConfig: preferences,
     defaultFiles,
     workspaceSnapshot,
   });
@@ -113,6 +112,7 @@ export async function executeDshCommand(input: {
   runtimeConfig?: RuntimeConfig | null;
   imagePaths?: string[];
 }): Promise<unknown> {
+  await ensureAgentPreferencesReady(DSH_AGENT_TYPE);
   return agentClient.executeDeepSeekHarnessCommand(
     input.threadId,
     input.command,
diff --git a/app/flowix-web/features/agent/services/external-agent-runtime-adapters.ts b/app/flowix-web/features/agent/services/external-agent-runtime-adapters.ts
index f96583c27..5896b3cfc 100644
--- a/app/flowix-web/features/agent/services/external-agent-runtime-adapters.ts
+++ b/app/flowix-web/features/agent/services/external-agent-runtime-adapters.ts
@@ -3,7 +3,7 @@ import type { AgentTypeKey } from '@/types/agent';
 
 export type ExternalAgentTypeKey = Extract<
   AgentTypeKey,
-  'codex' | 'claude' | 'hermes' | 'opencode' | 'deepseek-harness'
+  'codex' | 'claudecode' | 'hermes' | 'opencode' | 'dsh'
 >;
 
 export interface ExternalAgentRuntimeAdapter {
@@ -15,7 +15,8 @@ export interface ExternalAgentRuntimeAdapter {
 
 function createPrefixRuntimeAdapter(
   typeKey: ExternalAgentTypeKey,
-  resolveSessionId: (threadId: string) => Promise<string | null>
+  resolveSessionId: (threadId: string) => Promise<string | null>,
+  legacyPrefixes: readonly string[] = [],
 ): ExternalAgentRuntimeAdapter {
   return {
     typeKey,
@@ -23,9 +24,11 @@ function createPrefixRuntimeAdapter(
       return `${typeKey}-local-${instanceId}`;
     },
     isLocalThreadId(threadId) {
-      return threadId.startsWith(`${typeKey}-local-`) ||
+      return [typeKey, ...legacyPrefixes].some((prefix) =>
+        threadId.startsWith(`${prefix}-local-`) ||
         // Legacy local ids created before instance-backed routing.
-        threadId.startsWith(`${typeKey}-pending-`);
+        threadId.startsWith(`${prefix}-pending-`),
+      );
     },
     resolveSessionId,
   };
@@ -33,12 +36,13 @@ function createPrefixRuntimeAdapter(
 
 const externalAgentRuntimeAdapters: Record<ExternalAgentTypeKey, ExternalAgentRuntimeAdapter> = {
   codex: createPrefixRuntimeAdapter('codex', (threadId) => agent.getCodexSessionId(threadId)),
-  claude: createPrefixRuntimeAdapter('claude', (threadId) => agent.getClaudeSessionId(threadId)),
+  claudecode: createPrefixRuntimeAdapter('claudecode', (threadId) => agent.getClaudeSessionId(threadId), ['claude']),
   hermes: createPrefixRuntimeAdapter('hermes', (threadId) => agent.getHermesSessionId(threadId)),
   opencode: createPrefixRuntimeAdapter('opencode', (threadId) => agent.getOpenCodeSessionId(threadId)),
-  'deepseek-harness': createPrefixRuntimeAdapter(
-    'deepseek-harness',
+  dsh: createPrefixRuntimeAdapter(
+    'dsh',
     (threadId) => agent.getDeepSeekHarnessSessionId(threadId),
+    ['deepseek-harness'],
   ),
 };
 
@@ -47,10 +51,10 @@ export function getExternalAgentRuntimeAdapter(
 ): ExternalAgentRuntimeAdapter | null {
   if (
     typeKey === 'codex' ||
-    typeKey === 'claude' ||
+    typeKey === 'claudecode' ||
     typeKey === 'hermes' ||
     typeKey === 'opencode' ||
-    typeKey === 'deepseek-harness'
+    typeKey === 'dsh'
   ) {
     return externalAgentRuntimeAdapters[typeKey];
   }
diff --git a/app/flowix-web/features/agent/services/external-agent-runtime-service.test.ts b/app/flowix-web/features/agent/services/external-agent-runtime-service.test.ts
index 82754455c..e8fae7322 100644
--- a/app/flowix-web/features/agent/services/external-agent-runtime-service.test.ts
+++ b/app/flowix-web/features/agent/services/external-agent-runtime-service.test.ts
@@ -12,7 +12,7 @@ const sessionStoreMock = vi.hoisted(() => ({
   state: {
     sessionMeta: {
       activeThreadIds: {} as Record<string, string | undefined>,
-      activeAgentTypeKey: "deepseek-harness" as const,
+      activeAgentTypeKey: "dsh" as const,
       threadTypes: {},
       externalSessionResolutions: {} as Record<string, string>,
       lastRunningRunsReconciledAt: null,
@@ -112,7 +112,7 @@ describe('external agent runtime service', () => {
 
     await expect(resolveExternalSessionId('codex-local-inst-1', 'codex'))
       .resolves.toBe('codex-real-session');
-    await expect(resolveExternalSessionId('claude-local-inst-1', 'claude'))
+    await expect(resolveExternalSessionId('claude-local-inst-1', 'claudecode'))
       .resolves.toBe('claude-real-session');
 
     expect(agent.getCodexSessionId).toHaveBeenCalledWith('codex-local-inst-1');
diff --git a/app/flowix-web/features/agent/store/agent-access-store.test.ts b/app/flowix-web/features/agent/store/agent-access-store.test.ts
deleted file mode 100644
index 54300f596..000000000
--- a/app/flowix-web/features/agent/store/agent-access-store.test.ts
+++ /dev/null
@@ -1,215 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const agentAccessMock = vi.hoisted(() => ({
-  config: {
-    version: 1,
-    entries: [] as Array<Record<string, unknown>>,
-  } as {
-    version: number;
-    entries: Array<Record<string, unknown>>;
-    defaults?: { runtime?: { pi?: { piCodeMode?: boolean } } };
-  },
-  get: vi.fn(),
-  set: vi.fn(),
-  addFolderFromPicker: vi.fn(),
-}));
-
-vi.mock("@platform/tauri/client", () => ({
-  agentAccess: {
-    get: agentAccessMock.get,
-    set: agentAccessMock.set,
-    addFolderFromPicker: agentAccessMock.addFolderFromPicker,
-  },
-}));
-
-type TestEntry = {
-  id: string;
-  kind: "folder" | "notebook";
-  path: string;
-  name: string;
-  enabled: boolean;
-  workspace: boolean;
-  missing: boolean;
-  addedAt: number;
-  updatedAt: number;
-};
-
-function makeFolder(
-  overrides: Partial<TestEntry> & { id: string; path: string },
-): TestEntry {
-  return {
-    id: overrides.id,
-    kind: "folder",
-    path: overrides.path,
-    name: overrides.name ?? overrides.path,
-    enabled: overrides.enabled ?? true,
-    workspace: overrides.workspace ?? false,
-    missing: overrides.missing ?? false,
-    addedAt: overrides.addedAt ?? 1,
-    updatedAt: overrides.updatedAt ?? 1,
-  };
-}
-
-function entriesWithWorkspace(items: TestEntry[]): {
-  version: 1;
-  entries: TestEntry[];
-} {
-  return { version: 1, entries: items };
-}
-
-describe("agent-access-store workspace selection", () => {
-  beforeEach(async () => {
-    vi.clearAllMocks();
-    agentAccessMock.config = { version: 1, entries: [] };
-    agentAccessMock.get.mockImplementation(async () => agentAccessMock.config);
-    agentAccessMock.set.mockImplementation(async (config) => {
-      agentAccessMock.config = config;
-    });
-    agentAccessMock.addFolderFromPicker.mockImplementation(async () => null);
-    const { useAgentAccessStore } =
-      await import("@features/agent/store/agent-access-store");
-    useAgentAccessStore.setState({
-      config: { version: 1, entries: [] },
-      isLoading: false,
-      hasLoaded: false,
-      loadError: null,
-    });
-  });
-
-  it('exposes initial load failures and clears them after retry', async () => {
-    const { useAgentAccessStore } = await import('@features/agent/store/agent-access-store');
-    agentAccessMock.get.mockRejectedValueOnce(new Error('read failed'));
-    await useAgentAccessStore.getState().loadInitial();
-    expect(useAgentAccessStore.getState()).toMatchObject({
-      hasLoaded: false, isLoading: false, loadError: 'read failed',
-    });
-    agentAccessMock.config = {
-      version: 1, entries: [], defaults: { runtime: { pi: { piCodeMode: true } } },
-    };
-    await useAgentAccessStore.getState().loadInitial();
-    expect(useAgentAccessStore.getState()).toMatchObject({
-      hasLoaded: true, isLoading: false, loadError: null,
-      config: agentAccessMock.config,
-    });
-
-    agentAccessMock.get.mockRejectedValueOnce(new Error('refresh failed'));
-    await useAgentAccessStore.getState().loadInitial();
-    expect(useAgentAccessStore.getState()).toMatchObject({
-      hasLoaded: true, isLoading: false, loadError: 'refresh failed',
-      config: agentAccessMock.config,
-    });
-  });
-
-  it.each([true, false])('keeps the newest overlapping snapshot (newest resolves first: %s)', async (newestFirst) => {
-    const { useAgentAccessStore } = await import('@features/agent/store/agent-access-store');
-    let resolveOld!: (config: typeof agentAccessMock.config) => void;
-    let resolveNew!: (config: typeof agentAccessMock.config) => void;
-    agentAccessMock.get
-      .mockReturnValueOnce(new Promise((resolve) => { resolveOld = resolve; }))
-      .mockReturnValueOnce(new Promise((resolve) => { resolveNew = resolve; }));
-    const oldLoad = useAgentAccessStore.getState().loadInitial();
-    const newLoad = useAgentAccessStore.getState().loadInitial();
-    const oldConfig = { version: 1 as const, entries: [], defaults: { runtime: { pi: { piCodeMode: false } } } };
-    const newConfig = { version: 1 as const, entries: [], defaults: { runtime: { pi: { piCodeMode: true } } } };
-    if (newestFirst) {
-      resolveNew(newConfig);
-      await newLoad;
-      resolveOld(oldConfig);
-      await oldLoad;
-    } else {
-      resolveOld(oldConfig);
-      await oldLoad;
-      expect(useAgentAccessStore.getState().hasLoaded).toBe(false);
-      resolveNew(newConfig);
-      await newLoad;
-    }
-    expect(useAgentAccessStore.getState()).toMatchObject({
-      config: newConfig, hasLoaded: true, isLoading: false, loadError: null,
-    });
-  });
-
-  it("does NOT auto-promote a folder to workspace on initial load", async () => {
-    // 新契约: workspace 完全由 setWorkspace 显式触发, loadInitial 不会把
-    // 第一个 enabled folder 自动升为主空间。 磁盘原值原样落库。
-    const { useAgentAccessStore } =
-      await import("@features/agent/store/agent-access-store");
-    agentAccessMock.config = entriesWithWorkspace([
-      makeFolder({
-        id: "folder-1",
-        path: "D:\\projects\\first",
-        name: "First",
-      }),
-      makeFolder({
-        id: "folder-2",
-        path: "D:\\projects\\second",
-        name: "Second",
-      }),
-    ]);
-
-    await useAgentAccessStore.getState().loadInitial();
-
-    const entries = useAgentAccessStore.getState().config.entries;
-    expect(entries.every((entry) => entry.workspace === false)).toBe(true);
-  });
-
-  it("keeps a Pi writing selection made while initial settings are loading", async () => {
-    const { useAgentAccessStore } =
-      await import("@features/agent/store/agent-access-store");
-    let resolveGet!: (config: typeof agentAccessMock.config) => void;
-    agentAccessMock.get.mockReturnValueOnce(
-      new Promise((resolve) => { resolveGet = resolve; }),
-    );
-
-    const load = useAgentAccessStore.getState().loadInitial();
-    await useAgentAccessStore.getState().setDefaultRuntime("pi", {
-      piCodeMode: false,
-    });
-    resolveGet({
-      version: 1,
-      entries: [{ id: "loaded-entry" }],
-      defaults: { runtime: { pi: { piCodeMode: true } } },
-    });
-    await load;
-
-    expect(
-      useAgentAccessStore.getState().config.defaults?.runtime?.pi?.piCodeMode,
-    ).toBe(false);
-    expect(useAgentAccessStore.getState().config.entries).toEqual([
-      { id: "loaded-entry" },
-    ]);
-    expect(agentAccessMock.config.defaults?.runtime?.pi?.piCodeMode).toBe(false);
-  });
-
-
-  it("addFolder does not persist the removed workspace field", async () => {
-    const { useAgentAccessStore } =
-      await import("@features/agent/store/agent-access-store");
-    useAgentAccessStore.setState({
-      config: { version: 1, entries: [] },
-      isLoading: false,
-    });
-
-    const result = await useAgentAccessStore
-      .getState()
-      .addFolder("D:\\projects\\new");
-    expect(result.ok).toBe(true);
-
-    const entries = useAgentAccessStore.getState().config.entries;
-    expect(entries).toHaveLength(1);
-    expect(entries[0]?.enabled).toBe(true);
-    expect(entries[0]?.workspace).toBeUndefined();
-  });
-
-  it("does not write legacy global file defaults without a notebook id", async () => {
-    const { useAgentAccessStore } =
-      await import("@features/agent/store/agent-access-store");
-    const result = await useAgentAccessStore.getState().setDefaultFiles(undefined, {
-      workspace: null,
-      folders: ["D:\\projects\\legacy"],
-      notebooks: [],
-    });
-    expect(result).toBe(false);
-    expect(agentAccessMock.set).not.toHaveBeenCalled();
-    expect(useAgentAccessStore.getState().config.defaults?.files).toBeUndefined();
-  });
-});
diff --git a/app/flowix-web/features/agent/store/agent-access-store.ts b/app/flowix-web/features/agent/store/agent-access-store.ts
deleted file mode 100644
index 78ceed8ab..000000000
--- a/app/flowix-web/features/agent/store/agent-access-store.ts
+++ /dev/null
@@ -1,292 +0,0 @@
-import { createLogger } from '@/lib/logger';
-const logger = createLogger('agent-access-store');
-/**
- * Agent 可访问目录 store ── zustand 镜像后端
- * `~/.flowix/agent-access.json` 的整份 config。 与 `user-settings-store`
- * 不同, 本 store 没有 persist (后端是真源), 走 IPC + 跨窗口事件同步。
- *
- * 写操作 (`addFolder`) 走乐观更新: 本地先
- * 改 `entries` 再 `await agentAccess.set` 整份, 失败时 `loadInitial`
- * 回滚到磁盘真值。 跨窗口同步靠 app.tsx 顶层挂的 `listenToAgentAccessChanges`,
- * 收到事件后从磁盘拉整份覆盖内存。
- */
-
-import { create } from "zustand";
-import { agentAccess } from "@platform/tauri/client";
-import type {
-  AgentAccessConfig,
-  AgentAccessDefaultRuntime,
-  AgentAccessEntry,
-  NotebookAgentConfig,
-} from "@/lib/types/agent-access";
-import type { AgentTypeKey, FilesConfig } from "@/types/agent";
-
-// This store mirrors `~/.flowix/agent-access.json`.
-// It owns defaults for newly created agent-thread-card instances and keeps the
-// global entries list (folder metadata pool: name / missing / bookmark).
-// Real conversation runs derive cwd from the current notebook and add-dir
-// roots from that notebook's `.flowix/agent.json` (see
-// agent-runtime-spec::buildAgentRuntimeConfig), not from instance.files.
-
-export type AgentAccessErrorCode =
-  "not-selected" | "already-tracked" | "save-failed";
-
-export interface AgentAccessState {
-  config: AgentAccessConfig;
-  notebookConfigs: Record<string, NotebookAgentConfig>;
-  isLoading: boolean;
-  hasLoaded: boolean;
-  loadError: string | null;
-
-  /** 从磁盘拉整份 config ── 启动 / 跨窗口事件 / 写失败回滚都走它。 */
-  loadInitial: () => Promise<void>;
-/**
-   * 加一个 folder。 走后端 picker 让用户挑本地目录, 后端同时保存
-   * macOS security-scoped bookmark。路径已存在 (notebook 同路径或
-   * 已加的 folder) 时后端返回 `PathConflict`, UI 弹 toast 但不动 store。
-   */
-  addFolderFromPicker: () => Promise<
-    | { ok: true; entry: AgentAccessEntry }
-    | { ok: false; code: AgentAccessErrorCode }
-  >;
-
-  /**
-   * 直接以给定路径加 folder ── 跳过 dialog picker, 给测试 / 偏好窗口
-   * 等场景复用。 UI 层用 `addFolderFromPicker`。
-   */
-  addFolder: (
-    path: string,
-    name?: string,
-  ) => Promise<
-    | { ok: true; entry: AgentAccessEntry }
-    | { ok: false; code: AgentAccessErrorCode }
-  >;
-
-  setDefaultRuntime: (
-    agentType: AgentTypeKey,
-    patch: AgentAccessDefaultRuntime,
-  ) => Promise<void>;
-  /** Persist notebook add-dir roots to `.flowix/agent.json`. */
-  setDefaultFiles: (
-    notebookId: string | null | undefined,
-    files: FilesConfig,
-  ) => Promise<boolean>;
-}
-
-const EMPTY_CONFIG: AgentAccessConfig = { version: 1, entries: [], defaults: {} };
-let loadGeneration = 0;
-
-function mergeConcurrentConfigWrite(
-  loaded: AgentAccessConfig,
-  initial: AgentAccessConfig,
-  latest: AgentAccessConfig,
-): AgentAccessConfig {
-  if (latest === initial) return loaded;
-
-  const entries = latest.entries === initial.entries
-    ? loaded.entries
-    : [...new Map(
-        [...loaded.entries, ...latest.entries].map((entry) => [entry.id, entry]),
-      ).values()];
-
-  let defaults = loaded.defaults;
-  if (latest.defaults !== initial.defaults && latest.defaults) {
-    const runtime = { ...loaded.defaults?.runtime };
-    for (const agentType of Object.keys(latest.defaults.runtime ?? {}) as AgentTypeKey[]) {
-      runtime[agentType] = {
-        ...loaded.defaults?.runtime?.[agentType],
-        ...latest.defaults.runtime?.[agentType],
-      };
-    }
-    defaults = {
-      ...loaded.defaults,
-      ...latest.defaults,
-      ...(loaded.defaults?.runtime || latest.defaults.runtime ? { runtime } : {}),
-    };
-  }
-
-  return { ...loaded, entries, defaults };
-}
-
-export const useAgentAccessStore = create<AgentAccessState>((set, get) => ({
-  config: EMPTY_CONFIG,
-  notebookConfigs: {},
-  isLoading: false,
-  hasLoaded: false,
-  loadError: null,
-
-  loadInitial: async () => {
-    const generation = ++loadGeneration;
-    const configAtStart = get().config;
-    set({ isLoading: true, loadError: null });
-    try {
-      // Notebook-local config is the source of truth for add-dir roots.
-      const [config, notebookConfigs] = await Promise.all([
-        agentAccess.get(),
-        agentAccess.getNotebookConfigs?.() ?? Promise.resolve({}),
-      ]);
-      // Initial hydration and listener-ready reconciliation may overlap.
-      if (generation !== loadGeneration) return;
-      // Preserve a local settings write made while this read was in flight.
-      const latestConfig = get().config;
-      set({
-        config: mergeConcurrentConfigWrite(config, configAtStart, latestConfig),
-        notebookConfigs,
-        isLoading: false,
-        hasLoaded: true,
-      });
-    } catch (e) {
-      if (generation !== loadGeneration) return;
-      logger.error("agentAccess.loadInitial failed:", { error: e });
-      set({ isLoading: false, loadError: e instanceof Error ? e.message : String(e) });
-    }
-  },  addFolder: async (path: string, name?: string) => {
-    const entry = makeLocalFolderEntry(path, name);
-    const prev = get().config;
-    // Global entries are metadata/authorization only; notebook add-dir
-    // membership is persisted separately in `.flowix/agent.json`.
-    const optimistic = {
-      ...prev,
-      entries: [...prev.entries, entry],
-    };
-    set({ config: optimistic });
-    try {
-      await agentAccess.set(optimistic);
-      return { ok: true, entry };
-    } catch (e) {
-      const reason = extractReason(e);
-      if (reason === "path conflict") {
-        // 用户选了一个已经跟踪的路径, 不写盘也不留乐观条目 ── 回滚到
-        // 真正的"没加"状态, 让用户看到原列表。
-        set({ config: prev });
-        return { ok: false, code: "already-tracked" };
-      }
-      logger.error("agentAccess.addFolder failed, rolling back:", { error: e });
-      await get().loadInitial();
-      return { ok: false, code: "save-failed" };
-    }
-  },
-
-  addFolderFromPicker: async () => {
-    try {
-      const entry = await agentAccess.addFolderFromPicker();
-      if (!entry) {
-        return { ok: false, code: "not-selected" };
-      }
-      await get().loadInitial();
-      return { ok: true, entry };
-    } catch (e) {
-      const reason = extractReason(e);
-      if (reason === "path conflict") {
-        await get().loadInitial();
-        return { ok: false, code: "already-tracked" };
-      }
-      logger.error("agentAccess.addFolderFromPicker failed:", { error: e });
-      await get().loadInitial();
-      return { ok: false, code: "save-failed" };
-    }
-  },
-  setDefaultRuntime: async (agentType, patch) => {
-    const prev = get().config;
-    const optimistic: AgentAccessConfig = {
-      ...prev,
-      defaults: {
-        ...(prev.defaults ?? {}),
-        runtime: {
-          ...(prev.defaults?.runtime ?? {}),
-          [agentType]: {
-            ...(prev.defaults?.runtime?.[agentType] ?? {}),
-            ...patch,
-          },
-        },
-      },
-    };
-    set({ config: optimistic });
-    try {
-      await agentAccess.set(optimistic);
-    } catch (e) {
-      logger.error("agentAccess.setDefaultRuntime failed, rolling back:", { error: e });
-      await get().loadInitial();
-    }
-  },
-
-  setDefaultFiles: async (notebookId, files) => {
-    if (!notebookId) {
-      // Notebook scope is mandatory. Keep the old config read-only for
-      // migration, but never write new folder defaults to the global file.
-      logger.warn("agentAccess.setDefaultFiles ignored without notebookId");
-      return false;
-    }
-    const prevNotebookConfig = get().notebookConfigs[notebookId] ?? {
-        version: 1 as const,
-        revision: 0,
-        addDirs: [],
-      };
-      const priorByPath = new Map(
-        prevNotebookConfig.addDirs.map((directory) => [
-          directory.path.trim().replace(/[\\/]+$/, '').toLowerCase(),
-          directory,
-        ]),
-      );
-      const nextConfig: NotebookAgentConfig = {
-        version: 1,
-        revision: prevNotebookConfig.revision,
-        addDirs: files.folders.map((path) => {
-          const key = path.trim().replace(/[\\/]+$/, '').toLowerCase();
-          const existing = priorByPath.get(key);
-          return existing ?? {
-            id: `dir_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
-            path,
-            label: path.replace(/[\\/]+$/, '').split(/[\\/]/).pop() || path,
-            enabled: true,
-          };
-        }),
-      };
-      try {
-        const saved = await agentAccess.setNotebookConfig(
-          notebookId,
-          prevNotebookConfig.revision,
-          nextConfig,
-        );
-        set((state) => ({
-          notebookConfigs: { ...state.notebookConfigs, [notebookId]: saved },
-        }));
-        return true;
-      } catch (e) {
-        logger.error("agentAccess.setDefaultFiles failed:", { error: e });
-        await get().loadInitial();
-        return false;
-      }
-  },
-}));
-/** 在前端构造一条 Folder entry ── 路径 / 名字都是用户给的值, id 用时间戳
- * + 随机段保证与后端 `fld_<6位>` 不冲突即可 (后端写盘后会刷新 missing 字段)。 */
-function makeLocalFolderEntry(path: string, name?: string): AgentAccessEntry {
-  const trimmed = path.replace(/[\\/]+$/, "");
-  const derived = name?.trim() || trimmed.split(/[\\/]/).pop() || trimmed;
-  const now = Date.now();
-  return {
-    id: `fld_${now}_${Math.random().toString(36).slice(2, 6)}`,
-    kind: "folder",
-    path: trimmed,
-    name: derived,
-    enabled: true,
-    addedAt: now,
-    updatedAt: now,
-    missing: false,
-  };
-}
-
-/** 后端 IPC 失败时, Tauri 抛的 Error 里 `message` 是 `String`, 我们要
- * 识别 "path already tracked" 这条 user-facing 消息 → 走"回滚 + 友好
- * 提示"分支。 */
-function extractReason(e: unknown): string | null {
-  if (e && typeof e === "object" && "message" in e) {
-    const msg = (e as { message: unknown }).message;
-    if (typeof msg === "string") {
-      if (msg.includes("path already tracked")) return "path conflict";
-      return msg;
-    }
-  }
-  return null;
-}
diff --git a/app/flowix-web/features/agent/store/agent-data-store.ts b/app/flowix-web/features/agent/store/agent-data-store.ts
new file mode 100644
index 000000000..0e18a8580
--- /dev/null
+++ b/app/flowix-web/features/agent/store/agent-data-store.ts
@@ -0,0 +1,878 @@
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+import { createLogger } from "@/lib/logger";
+import { STORAGE_KEYS } from "@/lib/constants";
+import { agentWorkspace, piModels } from "@platform/tauri/client";
+import type {
+  AgentCodexReasoningEffort,
+  AgentCodexServiceTier,
+  AgentPermissionMode,
+  AgentTypeKey,
+} from "@/types/agent";
+import type {
+  LegacyAgentRuntimePreference,
+  LegacyAgentRuntimePreferences,
+} from "@/lib/types/agent-workspace";
+import {
+  getAgentAccessOptions,
+  getAgentModeOptions,
+  type AgentAccessOption,
+  type AgentModeOption,
+} from "@features/agent/runtime/agent-runtime-spec";
+import { getFallbackAgentModelOptions } from "@features/agent/config/agent-model-options";
+import { normalizeAgentId } from "@/lib/agent-types";
+
+const logger = createLogger("agent-data-store");
+const PERSISTENCE_STATUS_EVENT = "flowix-agent-data-persistence-status";
+let lastPersistenceError: string | null = null;
+
+function updatePersistenceError(error: string | null): void {
+  if (lastPersistenceError === error) return;
+  lastPersistenceError = error;
+  if (typeof window === "undefined") return;
+  queueMicrotask(() => {
+    window.dispatchEvent(new CustomEvent(PERSISTENCE_STATUS_EVENT, { detail: { error } }));
+  });
+}
+
+// A failed browser-cache write must not prevent backend-owned workspace loading.
+const agentStorage = {
+  getItem: (name: string): string | null => {
+    try { return localStorage.getItem(name); }
+    catch (error) { logger.warn("Agent cache read failed", { error }); updatePersistenceError(errorMessage(error)); return null; }
+  },
+  setItem: (name: string, value: string): void => {
+    try {
+      const mergedValue = mergeSerializedAgentData(localStorage.getItem(name), value);
+      localStorage.setItem(name, mergedValue);
+      updatePersistenceError(null);
+    } catch (error) {
+      logger.warn("Agent cache write failed", { error });
+      updatePersistenceError(errorMessage(error));
+    }
+  },
+  removeItem: (name: string): void => {
+    try { localStorage.removeItem(name); }
+    catch (error) { logger.warn("Agent cache removal failed", { error }); updatePersistenceError(errorMessage(error)); }
+  },
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export interface AgentCatalogModel {
+  id: string;
+  label: string;
+  description?: string;
+  subtitle?: string;
+  creditMultiplier?: number;
+  iconUrl?: string;
+  providerId?: string;
+  providerName?: string;
+  reasoningEfforts?: AgentCodexReasoningEffort[];
+}
+
+export interface AgentCatalogSkill {
+  name: string;
+  description: string;
+  displayName?: string;
+  shortDescription?: string;
+  whenToUse?: string;
+  modelInvocable?: boolean;
+  scope?: string;
+  path?: string;
+  enabled?: boolean;
+}
+
+export interface AgentModelCatalog {
+  items: AgentCatalogModel[];
+  defaultModel?: string;
+  defaultProviderId?: string;
+  updatedAt?: number;
+}
+
+export interface AgentCapabilities {
+  permissions: readonly AgentAccessOption[];
+  modes: readonly AgentModeOption[];
+}
+
+export interface AgentUserPreference {
+  model?: { id: string; providerId?: string };
+  permission?: AgentPermissionMode;
+  mode?: string;
+  reasoningEffort?: AgentCodexReasoningEffort;
+  reasoningByModel?: Record<string, AgentCodexReasoningEffort>;
+  serviceTier?: AgentCodexServiceTier;
+}
+
+interface AgentCatalogState {
+  models: AgentModelCatalog;
+  skillsByNotebookId: Record<string, {
+    items: AgentCatalogSkill[];
+    updatedAt?: number;
+  }>;
+  /** Built from the current runtime spec and omitted from the persisted snapshot. */
+  capabilities: AgentCapabilities;
+}
+
+interface AgentDataRecord {
+  catalog: AgentCatalogState;
+  user: AgentUserPreference;
+}
+
+interface AgentDataLoadState {
+  piMode: { status: 'idle' | 'loading' | 'ready' | 'error'; error?: string };
+}
+
+export interface AgentDataStoreState {
+  /** One-time import of legacy runtime/session defaults. */
+  legacyPreferencesMigrated: boolean;
+  /** Per-field revisions make user choices mergeable across app windows. */
+  userPreferenceRevisions: Partial<Record<AgentTypeKey, Record<string, string>>>;
+  /** Transient UI status; deliberately excluded from localStorage. */
+  persistenceError: string | null;
+  agents: Record<AgentTypeKey, AgentDataRecord>;
+  loadState: AgentDataLoadState;
+  initializePiMode: () => Promise<void>;
+  initializeLegacyPreferences: () => Promise<void>;
+  setModelCatalog: (agentType: AgentTypeKey, catalog: AgentModelCatalog) => void;
+  invalidateModelCatalog: (agentType: AgentTypeKey) => void;
+  invalidateSkillCatalog: (agentType: AgentTypeKey, notebookId: string) => void;
+  loadModelCatalog: (
+    agentType: AgentTypeKey,
+    loader: () => Promise<AgentModelCatalog>,
+    options?: { force?: boolean; maxAgeMs?: number },
+  ) => Promise<AgentModelCatalog>;
+  setSkillCatalog: (
+    agentType: AgentTypeKey,
+    notebookId: string,
+    items: AgentCatalogSkill[],
+  ) => void;
+  loadSkillCatalog: (
+    agentType: AgentTypeKey,
+    notebookId: string,
+    loader: () => Promise<AgentCatalogSkill[]>,
+    options?: { force?: boolean; maxAgeMs?: number },
+  ) => Promise<AgentCatalogSkill[]>;
+  setUserPreference: (
+    agentType: AgentTypeKey,
+    patch: Partial<AgentUserPreference>,
+  ) => void;
+  rememberModelReasoning: (
+    agentType: AgentTypeKey,
+    model: { id: string; providerId?: string } | undefined,
+    effort: AgentCodexReasoningEffort,
+  ) => void;
+  migrateLegacyPreferences: (
+    runtime: LegacyAgentRuntimePreferences | undefined,
+    codexSessionSettings?: {
+      agentCodexModel: string;
+      agentPermissionMode: AgentPermissionMode;
+      agentCodexReasoningEffort: AgentCodexReasoningEffort;
+    },
+  ) => void;
+}
+
+const AGENT_TYPES: AgentTypeKey[] = [
+  "codex", "claudecode", "hermes", "opencode", "pi", "dsh",
+];
+
+function canonicalAgentMap<T>(source: object | undefined): Partial<Record<AgentTypeKey, T>> {
+  const result: Partial<Record<AgentTypeKey, T>> = {};
+  if (!source) return result;
+  // Merge legacy fields first, then let explicitly canonical values win field
+  // conflicts while retaining any fields present only in the old record.
+  const entries = Object.entries(source as Record<string, T>).sort(([left], [right]) =>
+    Number(left === normalizeAgentId(left)) - Number(right === normalizeAgentId(right)),
+  );
+  for (const [key, value] of entries) {
+    const id = normalizeAgentId(key);
+    if (!id) continue;
+    const previous = result[id];
+    if (!previous || typeof previous !== "object" || !value || typeof value !== "object") {
+      result[id] = value;
+      continue;
+    }
+    const merged = { ...(previous as Record<string, unknown>), ...(value as Record<string, unknown>) };
+    for (const nestedKey of Object.keys(value as Record<string, unknown>)) {
+      const before = (previous as Record<string, unknown>)[nestedKey];
+      const after = (value as Record<string, unknown>)[nestedKey];
+      if (before && after && typeof before === "object" && typeof after === "object") {
+        merged[nestedKey] = { ...(before as object), ...(after as object) };
+      }
+    }
+    result[id] = merged as T;
+  }
+  return result;
+}
+
+function createAgentRecord(agentType: AgentTypeKey): AgentDataRecord {
+  return {
+    catalog: {
+      models: { items: getFallbackAgentModelOptions(agentType) },
+      skillsByNotebookId: {},
+      capabilities: {
+        permissions: getAgentAccessOptions(agentType),
+        modes: getAgentModeOptions(agentType),
+      },
+    },
+    user: {},
+  };
+}
+
+function createInitialAgents(): Record<AgentTypeKey, AgentDataRecord> {
+  return Object.fromEntries(
+    AGENT_TYPES.map((agentType) => [agentType, createAgentRecord(agentType)]),
+  ) as Record<AgentTypeKey, AgentDataRecord>;
+}
+
+const MODEL_CATALOG_MAX_AGE_MS = 5 * 60 * 1000;
+const SKILL_CATALOG_MAX_AGE_MS = 60 * 1000;
+const pendingModelLoads = new Map<AgentTypeKey, Promise<AgentModelCatalog>>();
+const pendingSkillLoads = new Map<string, Promise<AgentCatalogSkill[]>>();
+let pendingPiModeInitialization: Promise<void> | null = null;
+let pendingLegacyPreferencesInitialization: Promise<void> | null = null;
+
+async function readLegacyPiModePreference(): Promise<'code' | 'writing' | undefined> {
+  const legacy = (await agentWorkspace.getLegacyPreferences())?.pi;
+  if (legacy?.piCodeMode !== undefined) return legacy.piCodeMode ? 'code' : 'writing';
+  const mode: unknown = legacy?.mode;
+  return mode === 'code' || mode === 'writing' ? mode : undefined;
+}
+
+function skillLoadKey(agentType: AgentTypeKey, notebookId: string): string {
+  return `${agentType}:${notebookId}`;
+}
+
+export function modelPreferenceKey(model: { id: string; providerId?: string }): string {
+  return JSON.stringify([model.providerId?.trim() ?? "", model.id.trim()]);
+}
+
+function nextPreferenceRevision(): string {
+  return `${Date.now().toString().padStart(13, "0")}:${Math.random().toString(36).slice(2)}`;
+}
+
+function compareRevisions(left?: string, right?: string): number {
+  if (left === right) return 0;
+  if (!left) return -1;
+  if (!right) return 1;
+  return left.localeCompare(right);
+}
+
+// Defaults must lose to imported preferences, which must lose to user choices.
+const DEFAULT_PREFERENCE_REVISION = "0000000000000:default";
+function isImportedPreferenceRevision(revision?: string): boolean {
+  return revision?.startsWith("0000000000000:") ?? false;
+}
+
+function preferenceValueChanged(left: unknown, right: unknown): boolean {
+  return stableSerialize(left) !== stableSerialize(right);
+}
+
+function stampChangedPreferenceFields(
+  revisions: Record<string, string>,
+  before: AgentUserPreference,
+  after: AgentUserPreference,
+): Record<string, string> {
+  const next = { ...revisions };
+  for (const key of new Set([
+    ...Object.keys(before).filter((name) => name !== "reasoningByModel"),
+    ...Object.keys(after).filter((name) => name !== "reasoningByModel"),
+  ])) {
+    if (preferenceValueChanged(before[key as keyof AgentUserPreference], after[key as keyof AgentUserPreference])) {
+      next[key] = nextPreferenceRevision();
+    }
+  }
+  const beforeReasoning = before.reasoningByModel ?? {};
+  const afterReasoning = after.reasoningByModel ?? {};
+  for (const key of new Set([...Object.keys(beforeReasoning), ...Object.keys(afterReasoning)])) {
+    if (beforeReasoning[key] !== afterReasoning[key]) {
+      next[`reasoningByModel:${key}`] = nextPreferenceRevision();
+    }
+  }
+  return next;
+}
+
+function stampLegacyPreferenceFields(
+  revisions: Record<string, string>,
+  before: AgentUserPreference,
+  after: AgentUserPreference,
+): Record<string, string> {
+  const next = { ...revisions };
+  const legacyRevision = "0000000000000:legacy";
+  for (const key of new Set([
+    ...Object.keys(before).filter((name) => name !== "reasoningByModel"),
+    ...Object.keys(after).filter((name) => name !== "reasoningByModel"),
+  ])) {
+    if (preferenceValueChanged(before[key as keyof AgentUserPreference], after[key as keyof AgentUserPreference])) {
+      next[key] = legacyRevision;
+    }
+  }
+  const beforeReasoning = before.reasoningByModel ?? {};
+  const afterReasoning = after.reasoningByModel ?? {};
+  for (const key of new Set([...Object.keys(beforeReasoning), ...Object.keys(afterReasoning)])) {
+    if (beforeReasoning[key] !== afterReasoning[key]) {
+      next[`reasoningByModel:${key}`] = legacyRevision;
+    }
+  }
+  return next;
+}
+
+function mergeUserPreferenceSnapshots(
+  left: AgentUserPreference | undefined,
+  right: AgentUserPreference | undefined,
+  leftRevisions: Record<string, string> = {},
+  rightRevisions: Record<string, string> = {},
+): AgentUserPreference {
+  const leftUser = left ?? {};
+  const rightUser = right ?? {};
+  const merged: AgentUserPreference = {};
+  const fields = new Set([
+    ...Object.keys(leftUser).filter((key) => key !== "reasoningByModel"),
+    ...Object.keys(rightUser).filter((key) => key !== "reasoningByModel"),
+    ...Object.keys(leftRevisions).filter((key) => !key.startsWith("reasoningByModel:")),
+    ...Object.keys(rightRevisions).filter((key) => !key.startsWith("reasoningByModel:")),
+  ]);
+  for (const field of fields) {
+    const leftRevision = leftRevisions[field];
+    const rightRevision = rightRevisions[field];
+    const leftHasValue = Object.prototype.hasOwnProperty.call(leftUser, field);
+    const rightHasValue = Object.prototype.hasOwnProperty.call(rightUser, field);
+    const useRight = isImportedPreferenceRevision(rightRevision) && !leftRevision && leftHasValue
+      ? false
+      : isImportedPreferenceRevision(leftRevision) && !rightRevision && rightHasValue
+        ? true
+        : compareRevisions(leftRevision, rightRevision) <= 0;
+    const chosen = useRight ? rightUser : leftUser;
+    const hasValue = Object.prototype.hasOwnProperty.call(chosen, field);
+    const value = chosen[field as keyof AgentUserPreference];
+    if (hasValue && value !== undefined) (merged as Record<string, unknown>)[field] = value;
+  }
+
+  const leftReasoning = leftUser.reasoningByModel ?? {};
+  const rightReasoning = rightUser.reasoningByModel ?? {};
+  const reasoningKeys = new Set([
+    ...Object.keys(leftReasoning),
+    ...Object.keys(rightReasoning),
+    ...Object.keys(leftRevisions).filter((key) => key.startsWith("reasoningByModel:")).map((key) => key.slice("reasoningByModel:".length)),
+    ...Object.keys(rightRevisions).filter((key) => key.startsWith("reasoningByModel:")).map((key) => key.slice("reasoningByModel:".length)),
+  ]);
+  const reasoningByModel: Record<string, AgentCodexReasoningEffort> = {};
+  for (const key of reasoningKeys) {
+    const revisionKey = `reasoningByModel:${key}`;
+    const leftRevision = leftRevisions[revisionKey];
+    const rightRevision = rightRevisions[revisionKey];
+    const leftHasValue = Object.prototype.hasOwnProperty.call(leftReasoning, key);
+    const rightHasValue = Object.prototype.hasOwnProperty.call(rightReasoning, key);
+    const useRight = isImportedPreferenceRevision(rightRevision) && !leftRevision && leftHasValue
+      ? false
+      : isImportedPreferenceRevision(leftRevision) && !rightRevision && rightHasValue
+        ? true
+        : compareRevisions(leftRevision, rightRevision) <= 0;
+    const value = useRight ? rightReasoning[key] : leftReasoning[key];
+    if (value !== undefined) reasoningByModel[key] = value;
+  }
+  if (Object.keys(reasoningByModel).length) merged.reasoningByModel = reasoningByModel;
+  return merged;
+}
+
+function mergeRevisionMaps(
+  left: AgentDataStoreState["userPreferenceRevisions"] | undefined,
+  right: AgentDataStoreState["userPreferenceRevisions"] | undefined,
+): AgentDataStoreState["userPreferenceRevisions"] {
+  const merged: NonNullable<AgentDataStoreState["userPreferenceRevisions"]> = {};
+  left = canonicalAgentMap(left);
+  right = canonicalAgentMap(right);
+  for (const agentType of AGENT_TYPES) {
+    const leftFields = left?.[agentType] ?? {};
+    const rightFields = right?.[agentType] ?? {};
+    const fields: Record<string, string> = {};
+    for (const key of new Set([...Object.keys(leftFields), ...Object.keys(rightFields)])) {
+      fields[key] = compareRevisions(leftFields[key], rightFields[key]) <= 0
+        ? rightFields[key]
+        : leftFields[key];
+    }
+    if (Object.keys(fields).length) merged[agentType] = fields;
+  }
+  return merged;
+}
+
+function mergeCatalogSnapshots(
+  left: AgentCatalogState | undefined,
+  right: AgentCatalogState | undefined,
+): AgentCatalogState {
+  const leftCatalog: AgentCatalogState = left ?? {
+    models: { items: [] },
+    skillsByNotebookId: {},
+    capabilities: { permissions: [], modes: [] },
+  };
+  const rightCatalog = right ?? leftCatalog;
+  const leftModelsAt = leftCatalog.models.updatedAt ?? -1;
+  const rightModelsAt = rightCatalog.models.updatedAt ?? -1;
+  const skillsByNotebookId = { ...leftCatalog.skillsByNotebookId };
+  for (const [notebookId, skillCatalog] of Object.entries(rightCatalog.skillsByNotebookId)) {
+    if ((skillCatalog.updatedAt ?? -1) >= (skillsByNotebookId[notebookId]?.updatedAt ?? -1)) {
+      skillsByNotebookId[notebookId] = skillCatalog;
+    }
+  }
+  return {
+    models: rightModelsAt >= leftModelsAt ? rightCatalog.models : leftCatalog.models,
+    skillsByNotebookId,
+    capabilities: rightCatalog.capabilities ?? leftCatalog.capabilities,
+  };
+}
+
+function mergeAgentSnapshots(
+  leftAgents: Partial<Record<AgentTypeKey, AgentDataRecord>> | undefined,
+  rightAgents: Partial<Record<AgentTypeKey, AgentDataRecord>> | undefined,
+  leftRevisions: AgentDataStoreState["userPreferenceRevisions"] | undefined,
+  rightRevisions: AgentDataStoreState["userPreferenceRevisions"] | undefined,
+): Record<AgentTypeKey, AgentDataRecord> {
+  leftAgents = canonicalAgentMap(leftAgents);
+  rightAgents = canonicalAgentMap(rightAgents);
+  const merged = createInitialAgents();
+  for (const agentType of AGENT_TYPES) {
+    const left = leftAgents?.[agentType] ?? merged[agentType];
+    const right = rightAgents?.[agentType] ?? left;
+    merged[agentType] = {
+      catalog: mergeCatalogSnapshots(left.catalog, right.catalog),
+      user: mergeUserPreferenceSnapshots(
+        left.user,
+        right.user,
+        leftRevisions?.[agentType],
+        rightRevisions?.[agentType],
+      ),
+    };
+  }
+  return merged;
+}
+
+function mergePersistedAgentSlices(left: Record<string, any>, right: Record<string, any>): Record<string, any> {
+  const leftRevisions = left.userPreferenceRevisions as AgentDataStoreState["userPreferenceRevisions"] | undefined;
+  const rightRevisions = right.userPreferenceRevisions as AgentDataStoreState["userPreferenceRevisions"] | undefined;
+  const revisions = mergeRevisionMaps(leftRevisions, rightRevisions);
+  return {
+    ...left,
+    ...right,
+    legacyPreferencesMigrated: !!left.legacyPreferencesMigrated || !!right.legacyPreferencesMigrated,
+    userPreferenceRevisions: revisions,
+    agents: mergeAgentSnapshots(left.agents, right.agents, leftRevisions, rightRevisions),
+  };
+}
+
+function mergeSerializedAgentData(existing: string | null, incoming: string): string {
+  if (!existing) return incoming;
+  try {
+    const existingEnvelope = JSON.parse(existing) as { state?: Record<string, any>; version?: number };
+    const incomingEnvelope = JSON.parse(incoming) as { state?: Record<string, any>; version?: number };
+    if (!existingEnvelope.state || !incomingEnvelope.state) return incoming;
+    const mergedState = mergePersistedAgentSlices(existingEnvelope.state, incomingEnvelope.state);
+    return JSON.stringify({
+      ...incomingEnvelope,
+      state: persistedAgentDataState(mergedState as AgentDataStoreState),
+    });
+  } catch {
+    return incoming;
+  }
+}
+
+function stableSerialize(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableSerialize).join(",")}]`;
+  if (value && typeof value === "object") {
+    const object = value as Record<string, unknown>;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableSerialize(object[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "undefined";
+}
+
+function persistedAgentDataState(state: AgentDataStoreState): Record<string, unknown> {
+  return {
+    legacyPreferencesMigrated: state.legacyPreferencesMigrated,
+    userPreferenceRevisions: state.userPreferenceRevisions,
+    agents: Object.fromEntries(AGENT_TYPES.map((agentType) => {
+      const agent = state.agents[agentType];
+      return [agentType, {
+        catalog: {
+          models: agent.catalog.models,
+          skillsByNotebookId: agent.catalog.skillsByNotebookId,
+        },
+        user: agent.user,
+      }];
+    })),
+
+  };
+}
+
+function mapLegacyRuntimePreference(legacy: LegacyAgentRuntimePreference): AgentUserPreference {
+  const patch: AgentUserPreference = {};
+  if (legacy.model?.key && legacy.model.key !== "inherit") {
+    patch.model = { id: legacy.model.key, ...(legacy.model.providerId ? { providerId: legacy.model.providerId } : {}) };
+  }
+  if (legacy.access?.sandbox) patch.permission = legacy.access.sandbox;
+  if (legacy.mode) patch.mode = legacy.mode;
+  if (legacy.piCodeMode !== undefined) patch.mode = legacy.piCodeMode ? "code" : "writing";
+  if (legacy.reasoningEffort) {
+    patch.reasoningEffort = legacy.reasoningEffort;
+    if (legacy.model?.key && legacy.model.key !== "inherit") {
+      patch.reasoningByModel = {
+        [modelPreferenceKey({ id: legacy.model.key, providerId: legacy.model.providerId })]: legacy.reasoningEffort,
+      };
+    }
+  }
+  if (legacy.serviceTier) patch.serviceTier = legacy.serviceTier;
+  return patch;
+}
+
+export const useAgentDataStore = create<AgentDataStoreState>()(
+  persist(
+    (set, get) => ({
+      legacyPreferencesMigrated: false,
+      userPreferenceRevisions: {},
+      persistenceError: lastPersistenceError,
+      agents: createInitialAgents(),
+      loadState: { piMode: { status: "idle" } },
+
+      initializePiMode: () => {
+        if (pendingPiModeInitialization) return pendingPiModeInitialization;
+        if (get().loadState.piMode.status === "ready") return Promise.resolve();
+        set((state) => ({ loadState: { ...state.loadState, piMode: { status: "loading" } } }));
+        const request = (async () => {
+          if (get().agents.pi.user.mode === undefined) {
+            const [features, legacyMode] = await Promise.all([
+              piModels.getFeatures(),
+              get().legacyPreferencesMigrated ? undefined : readLegacyPiModePreference(),
+            ]);
+            // Another window may have migrated and cleared the old source already.
+            await useAgentDataStore.persist.rehydrate();
+            const importedMode = legacyMode ?? (features.legacyCodeMode === undefined
+              ? undefined : features.legacyCodeMode ? "code" : "writing");
+            set((state) => {
+              // A choice made during this read always wins over migration.
+              const previous = state.agents.pi.user;
+              if (previous.mode !== undefined) return {};
+              const user = { ...previous, mode: importedMode ?? "writing" };
+              const revisions = stampLegacyPreferenceFields(state.userPreferenceRevisions.pi ?? {}, previous, user);
+              if (importedMode === undefined) revisions.mode = DEFAULT_PREFERENCE_REVISION;
+              return {
+                agents: { ...state.agents, pi: { ...state.agents.pi, user } },
+                userPreferenceRevisions: {
+                  ...state.userPreferenceRevisions,
+                  pi: revisions,
+                },
+              };
+            });
+            // The persistence merge can retain a stronger choice from another window.
+            await useAgentDataStore.persist.rehydrate();
+          }
+          // Remove the legacy source only after the migrated preference is durable.
+          try {
+            const saved = JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA) ?? "null");
+            if (saved?.state?.agents?.pi?.user?.mode === get().agents.pi.user.mode) {
+              await piModels.clearLegacyCodeMode();
+            }
+          } catch (error) {
+            logger.warn("Pi legacy mode cleanup deferred", { error });
+          }
+          set((state) => ({ loadState: { ...state.loadState, piMode: { status: "ready" } } }));
+        })().catch((error) => {
+          set((state) => ({ loadState: { ...state.loadState, piMode: { status: "error", error: errorMessage(error) } } }));
+          throw error;
+        }).finally(() => { pendingPiModeInitialization = null; });
+        pendingPiModeInitialization = request;
+        return request;
+      },
+
+      initializeLegacyPreferences: () => {
+        if (get().legacyPreferencesMigrated) return Promise.resolve();
+        if (pendingLegacyPreferencesInitialization) return pendingLegacyPreferencesInitialization;
+        const request = (async () => {
+          const legacy = await agentWorkspace.getLegacyPreferences();
+          const { useAgentSessionStore } = await import('./agent-session-store');
+          get().migrateLegacyPreferences(
+            legacy ?? undefined,
+            useAgentSessionStore.getState().sessionMeta.settings,
+          );
+          try {
+            const saved = JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA) ?? 'null');
+            if (!saved?.state?.legacyPreferencesMigrated) {
+              logger.warn('Agent preference migration has not reached durable storage');
+            }
+          } catch (error) {
+            logger.warn('Agent preference migration persistence check failed', { error });
+          }
+        })().finally(() => { pendingLegacyPreferencesInitialization = null; });
+        pendingLegacyPreferencesInitialization = request;
+        return request;
+      },
+
+      setModelCatalog: (agentType, catalog) => set((state) => ({
+        agents: {
+          ...state.agents,
+          [agentType]: {
+            ...state.agents[agentType],
+            catalog: { ...state.agents[agentType].catalog, models: catalog },
+          },
+        },
+      })),
+
+      invalidateModelCatalog: (agentType) => set((state) => ({
+        agents: {
+          ...state.agents,
+          [agentType]: {
+            ...state.agents[agentType],
+            catalog: {
+              ...state.agents[agentType].catalog,
+              models: { ...state.agents[agentType].catalog.models, updatedAt: 0 },
+            },
+          },
+        },
+      })),
+
+      invalidateSkillCatalog: (agentType, notebookId) => set((state) => {
+        const current = state.agents[agentType].catalog.skillsByNotebookId[notebookId];
+        if (!current) return state;
+        return {
+          agents: {
+            ...state.agents,
+            [agentType]: {
+              ...state.agents[agentType],
+              catalog: {
+                ...state.agents[agentType].catalog,
+                skillsByNotebookId: {
+                  ...state.agents[agentType].catalog.skillsByNotebookId,
+                  [notebookId]: { ...current, updatedAt: 0 },
+                },
+              },
+            },
+          },
+        };
+      }),
+
+      loadModelCatalog: (agentType, loader, options) => {
+        const cached = get().agents[agentType].catalog.models;
+        const maxAgeMs = options?.maxAgeMs ?? MODEL_CATALOG_MAX_AGE_MS;
+        const isFresh = !!cached.updatedAt && Date.now() - cached.updatedAt < maxAgeMs;
+        if (!options?.force && isFresh) return Promise.resolve(cached);
+        const pending = pendingModelLoads.get(agentType);
+        if (pending) {
+          if (!options?.force) return pending;
+          return pending.catch(() => undefined).then(() => {
+            const nextPending = pendingModelLoads.get(agentType);
+            return nextPending ?? get().loadModelCatalog(agentType, loader, options);
+          });
+        }
+
+        const request = loader()
+          .then((catalog) => {
+            const stored = { ...catalog, updatedAt: catalog.updatedAt ?? Date.now() };
+            get().setModelCatalog(agentType, stored);
+            return stored;
+          })
+          .finally(() => pendingModelLoads.delete(agentType));
+        pendingModelLoads.set(agentType, request);
+        return request;
+      },
+
+      setSkillCatalog: (agentType, notebookId, items) => set((state) => ({
+        agents: {
+          ...state.agents,
+          [agentType]: {
+            ...state.agents[agentType],
+            catalog: {
+              ...state.agents[agentType].catalog,
+              skillsByNotebookId: {
+                ...state.agents[agentType].catalog.skillsByNotebookId,
+                [notebookId]: { items, updatedAt: Date.now() },
+              },
+            },
+          },
+        },
+      })),
+
+      loadSkillCatalog: (agentType, notebookId, loader, options) => {
+        const cached = get().agents[agentType].catalog.skillsByNotebookId[notebookId];
+        const maxAgeMs = options?.maxAgeMs ?? SKILL_CATALOG_MAX_AGE_MS;
+        const isFresh = !!cached?.updatedAt && Date.now() - cached.updatedAt < maxAgeMs;
+        if (!options?.force && isFresh) return Promise.resolve(cached.items);
+        const key = skillLoadKey(agentType, notebookId);
+        const pending = pendingSkillLoads.get(key);
+        if (pending) {
+          if (!options?.force) return pending;
+          return pending.catch(() => undefined).then(() => {
+            const nextPending = pendingSkillLoads.get(key);
+            return nextPending ?? get().loadSkillCatalog(agentType, notebookId, loader, options);
+          });
+        }
+
+        const request = loader()
+          .then((items) => {
+            get().setSkillCatalog(agentType, notebookId, items);
+            return items;
+          })
+          .finally(() => pendingSkillLoads.delete(key));
+        pendingSkillLoads.set(key, request);
+        return request;
+      },
+
+      setUserPreference: (agentType, patch) => set((state) => {
+        const previous = state.agents[agentType].user;
+        const nextUser = { ...previous, ...patch };
+        const revisions = stampChangedPreferenceFields(
+          state.userPreferenceRevisions[agentType] ?? {}, previous, nextUser,
+        );
+        // Explicitly selecting an existing default/import is still a user choice.
+        for (const field of Object.keys(patch)) {
+          if (field !== "reasoningByModel" && (!revisions[field] || isImportedPreferenceRevision(revisions[field]))) {
+            revisions[field] = nextPreferenceRevision();
+          }
+        }
+        const userPreferenceRevisions = {
+          ...state.userPreferenceRevisions,
+          [agentType]: revisions,
+        };
+        return {
+          agents: {
+            ...state.agents,
+            [agentType]: { ...state.agents[agentType], user: nextUser },
+          },
+          userPreferenceRevisions,
+        };
+      }),
+
+      rememberModelReasoning: (agentType, model, effort) => {
+        const current = get().agents[agentType].user;
+        const reasoningByModel = { ...current.reasoningByModel };
+        if (model) reasoningByModel[modelPreferenceKey(model)] = effort;
+        get().setUserPreference(agentType, { reasoningEffort: effort, reasoningByModel });
+      },
+
+      migrateLegacyPreferences: (runtime, codexSessionSettings) => {
+        if (get().legacyPreferencesMigrated) return;
+        if (!runtime && !codexSessionSettings) {
+          set({ legacyPreferencesMigrated: true });
+          return;
+        }
+        set((state) => {
+          const agents = { ...state.agents };
+          const userPreferenceRevisions = { ...state.userPreferenceRevisions };
+          for (const agentType of AGENT_TYPES) {
+            const legacyRuntimeKey = agentType === "claudecode" ? "claude" : agentType === "dsh" ? "deepseek-harness" : agentType;
+            const legacy = runtime?.[legacyRuntimeKey];
+            const sessionFallback: AgentUserPreference = agentType === "codex" && codexSessionSettings
+              ? {
+                  ...(codexSessionSettings.agentCodexModel && codexSessionSettings.agentCodexModel !== "inherit"
+                    ? { model: { id: codexSessionSettings.agentCodexModel } }
+                    : {}),
+                  ...(codexSessionSettings.agentPermissionMode
+                    ? { permission: codexSessionSettings.agentPermissionMode }
+                    : {}),
+                  ...(codexSessionSettings.agentCodexReasoningEffort
+                    ? {
+                        reasoningEffort: codexSessionSettings.agentCodexReasoningEffort,
+                        ...(codexSessionSettings.agentCodexModel && codexSessionSettings.agentCodexModel !== "inherit"
+                          ? { reasoningByModel: {
+                              [modelPreferenceKey({ id: codexSessionSettings.agentCodexModel })]: codexSessionSettings.agentCodexReasoningEffort,
+                            } }
+                          : {}),
+                      }
+                    : {}),
+                }
+              : {};
+            const migrated = legacy
+              ? { ...sessionFallback, ...mapLegacyRuntimePreference(legacy) }
+              : sessionFallback;
+            if (!Object.keys(migrated).length) continue;
+            const previousUser = agents[agentType].user;
+            const nextUser = {
+              ...migrated,
+              ...previousUser,
+              ...(migrated.reasoningByModel || previousUser.reasoningByModel
+                ? { reasoningByModel: { ...migrated.reasoningByModel, ...previousUser.reasoningByModel } }
+                : {}),
+            };
+            userPreferenceRevisions[agentType] = stampLegacyPreferenceFields(
+              userPreferenceRevisions[agentType] ?? {},
+              previousUser,
+              nextUser,
+            );
+            agents[agentType] = {
+              ...agents[agentType],
+              user: nextUser,
+            };
+          }
+          return { agents, userPreferenceRevisions, legacyPreferencesMigrated: true };
+        });
+      },
+
+    }),
+    {
+      name: STORAGE_KEYS.AGENT_DATA,
+      version: 2,
+      storage: createJSONStorage(() => agentStorage),
+      partialize: persistedAgentDataState,
+      migrate: (persisted) => mergePersistedAgentSlices({}, persisted as Record<string, any>),
+      merge: (persisted, current) => {
+        const stored = persisted as Partial<AgentDataStoreState>;
+        const merged = mergePersistedAgentSlices(current as unknown as Record<string, any>, stored as Record<string, any>);
+        const agents = merged.agents as Record<AgentTypeKey, AgentDataRecord>;
+        for (const agentType of AGENT_TYPES) {
+          agents[agentType] = {
+            ...current.agents[agentType],
+            ...agents[agentType],
+            catalog: {
+              ...current.agents[agentType].catalog,
+              ...agents[agentType].catalog,
+              capabilities: current.agents[agentType].catalog.capabilities,
+            },
+          };
+        }
+        return {
+          ...current,
+          agents,
+          legacyPreferencesMigrated: !!merged.legacyPreferencesMigrated,
+          userPreferenceRevisions: merged.userPreferenceRevisions,
+        };
+      },
+    },
+  ),
+);
+
+/** Resolve legacy defaults before a runtime config is built for a request. */
+export async function ensureAgentPreferencesReady(agentType?: AgentTypeKey): Promise<void> {
+  const state = useAgentDataStore.getState();
+  await state.initializeLegacyPreferences().catch((error) => {
+    logger.warn("Agent preference migration deferred", { error });
+  });
+  if (!agentType || agentType === "pi") {
+    await state.initializePiMode();
+  }
+}
+
+if (typeof window !== "undefined") {
+  window.addEventListener(PERSISTENCE_STATUS_EVENT, (event) => {
+    const error = (event as CustomEvent<{ error: string | null }>).detail?.error ?? null;
+    if (useAgentDataStore.getState().persistenceError !== error) {
+      useAgentDataStore.setState({ persistenceError: error });
+    }
+  });
+  window.addEventListener("storage", (event) => {
+    if (event.key === STORAGE_KEYS.AGENT_DATA || event.key === null) {
+      void Promise.resolve(useAgentDataStore.persist.rehydrate()).then(() => {
+        const raw = agentStorage.getItem(STORAGE_KEYS.AGENT_DATA);
+        if (!raw) return;
+        try {
+          const persisted = JSON.parse(raw) as { state?: Record<string, unknown> };
+          const currentSnapshot = persistedAgentDataState(useAgentDataStore.getState());
+          if (persisted.state && stableSerialize(currentSnapshot) !== stableSerialize(persisted.state)) {
+            // Re-write the field-wise merge so simultaneous windows converge
+            // even when both tabs wrote a stale whole-store snapshot.
+            useAgentDataStore.setState((state) => ({ ...state }));
+          }
+        } catch (error) {
+          logger.warn("Agent cache reconciliation failed", { error });
+        }
+      });
+    }
+  });
+}
diff --git a/app/flowix-web/features/agent/store/agent-history-adapters.test.ts b/app/flowix-web/features/agent/store/agent-history-adapters.test.ts
index 2e725aedd..e3c0cdaab 100644
--- a/app/flowix-web/features/agent/store/agent-history-adapters.test.ts
+++ b/app/flowix-web/features/agent/store/agent-history-adapters.test.ts
@@ -95,7 +95,7 @@ describe("Pi backend history pages", () => {
 });
 
 describe.each([
-  ["claude", client.getClaudeThreadPage],
+  ["claudecode", client.getClaudeThreadPage],
   ["opencode", client.getOpenCodeThreadPage],
 ] as const)("%s full history", (runtime, getPage) => {
   beforeEach(() => getPage.mockReset());
diff --git a/app/flowix-web/features/agent/store/agent-history-adapters.ts b/app/flowix-web/features/agent/store/agent-history-adapters.ts
index 9ba9b2e84..3d2687d23 100644
--- a/app/flowix-web/features/agent/store/agent-history-adapters.ts
+++ b/app/flowix-web/features/agent/store/agent-history-adapters.ts
@@ -171,11 +171,11 @@ function createCodexHistoryAdapter(): AgentHistoryAdapter {
 
 function createClaudeHistoryAdapter(): AgentHistoryAdapter {
   return {
-    typeKey: "claude",
+    typeKey: "claudecode",
     externalSessionBacked: true,
     listThreads: () => agentClient.listClaudeThreads(),
     async getFullHistory(threadId) {
-      return readAllHistoryPages("claude", threadId);
+      return readAllHistoryPages("claudecode", threadId);
     },
     getInitialHistory: (threadId, limit) =>
       agentClient.getClaudeThreadPage(threadId, null, limit),
@@ -280,7 +280,7 @@ function createPiHistoryAdapter(): AgentHistoryAdapter {
 
 function createDeepSeekHarnessHistoryAdapter(): AgentHistoryAdapter {
   return {
-    typeKey: "deepseek-harness",
+    typeKey: "dsh",
     externalSessionBacked: true,
     listThreads: () => agentClient.listDeepSeekHarnessThreads(),
     async getFullHistory(threadId) {
@@ -302,11 +302,11 @@ const historyAdapters: Partial<Record<AgentTypeKey, AgentHistoryAdapter>> = {
   // Codex history is projected by the backend from Codex App Server threads.
   codex: createCodexHistoryAdapter(),
   pi: createPiHistoryAdapter(),
-  claude: createClaudeHistoryAdapter(),
+  claudecode: createClaudeHistoryAdapter(),
   hermes: createHermesHistoryAdapter(),
   // OpenCode reads its provider session through the ACP session/load path.
   opencode: createOpenCodeHistoryAdapter(),
-  "deepseek-harness": createDeepSeekHarnessHistoryAdapter(),
+  dsh: createDeepSeekHarnessHistoryAdapter(),
 };
 
 export function getAgentHistoryAdapter(typeKey: AgentTypeKey): AgentHistoryAdapter {
diff --git a/app/flowix-web/features/agent/store/agent-message-font-store.ts b/app/flowix-web/features/agent/store/agent-message-font-store.ts
new file mode 100644
index 000000000..295eacf6b
--- /dev/null
+++ b/app/flowix-web/features/agent/store/agent-message-font-store.ts
@@ -0,0 +1,81 @@
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+import { STORAGE_KEYS } from '@/lib/constants';
+import {
+  getTypographyFontFamily,
+  TYPOGRAPHY_FONT_MODES,
+  type TypographyFontMode,
+} from '@/lib/typography-font-mode';
+
+export type AgentMessageFontMode = TypographyFontMode;
+export const AGENT_MESSAGE_SIZE_MODES = ['small', 'medium', 'large'] as const;
+export type AgentMessageSizeMode = (typeof AGENT_MESSAGE_SIZE_MODES)[number];
+
+export const AGENT_MESSAGE_SIZE_SCALE: Record<AgentMessageSizeMode, number> = {
+  small: 14 / 15,
+  medium: 1,
+  large: 16 / 15,
+};
+
+export function getAgentMessageTypographyCssVars(
+  fontMode: AgentMessageFontMode,
+  sizeMode: AgentMessageSizeMode,
+) {
+  return {
+    '--agent-message-font-family': `'Flowix Small Emoji', ${getTypographyFontFamily(fontMode)}`,
+    '--agent-message-base-font-size': '15px',
+    '--agent-message-size-scale': AGENT_MESSAGE_SIZE_SCALE[sizeMode],
+  } as const;
+}
+
+interface AgentMessageFontStore {
+  fontMode: AgentMessageFontMode;
+  setFontMode: (fontMode: AgentMessageFontMode) => void;
+  sizeMode: AgentMessageSizeMode;
+  setSizeMode: (sizeMode: AgentMessageSizeMode) => void;
+}
+
+function isAgentMessageFontMode(value: unknown): value is AgentMessageFontMode {
+  return typeof value === 'string' && (TYPOGRAPHY_FONT_MODES as readonly string[]).includes(value);
+}
+
+function isAgentMessageSizeMode(value: unknown): value is AgentMessageSizeMode {
+  return typeof value === 'string' && (AGENT_MESSAGE_SIZE_MODES as readonly string[]).includes(value);
+}
+
+export const useAgentMessageFontStore = create<AgentMessageFontStore>()(
+  persist(
+    (set) => ({
+      fontMode: 'standard',
+      setFontMode: (fontMode) => set({ fontMode }),
+      sizeMode: 'medium',
+      setSizeMode: (sizeMode) => set({ sizeMode }),
+    }),
+    {
+      name: STORAGE_KEYS.AGENT_MESSAGE_FONT,
+      storage: createJSONStorage(() => localStorage),
+      partialize: ({ fontMode, sizeMode }) => ({ fontMode, sizeMode }),
+      merge: (persisted, current) => {
+        const storedMode = (persisted as Partial<AgentMessageFontStore> | undefined)?.fontMode;
+        return {
+          ...current,
+          fontMode: isAgentMessageFontMode(storedMode) ? storedMode : 'standard',
+          sizeMode: isAgentMessageSizeMode((persisted as Partial<AgentMessageFontStore> | undefined)?.sizeMode)
+            ? (persisted as Partial<AgentMessageFontStore>).sizeMode!
+            : 'medium',
+        };
+      },
+    },
+  ),
+);
+
+// Zustand's persist middleware writes localStorage but does not subscribe to
+// changes made by sibling windows. Keep dedicated conversation windows and
+// the editor's embedded Thread Cards on the same typography selection.
+if (typeof window !== 'undefined') {
+  window.addEventListener('storage', (event) => {
+    if (event.key === STORAGE_KEYS.AGENT_MESSAGE_FONT || event.key === null) {
+      void useAgentMessageFontStore.persist.rehydrate();
+    }
+  });
+}
diff --git a/app/flowix-web/features/agent/store/agent-runtime-store.ts b/app/flowix-web/features/agent/store/agent-runtime-store.ts
index 0a2b0b495..01f262171 100644
--- a/app/flowix-web/features/agent/store/agent-runtime-store.ts
+++ b/app/flowix-web/features/agent/store/agent-runtime-store.ts
@@ -1,13 +1,64 @@
 import { create } from 'zustand';
-import { agent, type AgentRuntimeAvailability } from '@platform/tauri/client';
+import { agent } from '@platform/tauri/client';
 import { subscribe } from '@platform/tauri/event-bus';
-import type { AgentTypeKey } from '@/types/agent';
+import type { AgentRuntimeSnapshot, AgentTypeKey } from '@/types/agent';
 
 const RUNTIME_STATUS_TTL_MS = 120_000;
 
-type RuntimeStatusByType = Partial<Record<AgentTypeKey, AgentRuntimeAvailability>>;
+type RuntimeStatusByType = Partial<Record<AgentTypeKey, AgentRuntimeSnapshot>>;
+
+type RuntimeStatusRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is RuntimeStatusRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Normalize the current nested protocol and the flat response returned by
+ * older desktop hosts. During development the web bundle can hot reload before
+ * the Tauri process is restarted, so the IPC boundary must tolerate both.
+ */
+function normalizeRuntimeStatusReport(report: unknown): RuntimeStatusByType {
+  if (!isRecord(report)) return {};
+  const source = isRecord(report.agents) ? report.agents : report;
+  const aliases: Record<AgentTypeKey, string[]> = {
+    pi: ['pi'],
+    codex: ['codex'],
+    claudecode: ['claudecode', 'claude'],
+    opencode: ['opencode'],
+    hermes: ['hermes'],
+    dsh: ['dsh', 'deepseek-harness', 'deepseek_harness'],
+  };
+  const result: RuntimeStatusByType = {};
+
+  for (const [agentId, keys] of Object.entries(aliases) as [AgentTypeKey, string[]][]) {
+    const value = keys.map((key) => source[key]).find(isRecord);
+    if (!value) continue;
+
+    if (
+      ['unknown', 'installed', 'missing'].includes(String(value.installation)) &&
+      ['unknown', 'ready', 'blocked'].includes(String(value.readiness))
+    ) {
+      result[agentId] = value as unknown as AgentRuntimeSnapshot;
+      continue;
+    }
+
+    // Compatibility with the former { available, installed, reason } shape.
+    const installed = value.installed === true || value.available === true;
+    const details = {
+      reasonCode: null,
+      reason: typeof value.reason === 'string' ? value.reason : null,
+    };
+    result[agentId] = installed
+      ? { ...details, installation: 'installed', readiness: value.available === false ? 'blocked' : 'ready' }
+      : { ...details, installation: 'missing', readiness: 'unknown' };
+  }
+
+  return result;
+}
 
 let inFlightRefresh: Promise<void> | null = null;
+let refreshGeneration = 0;
 let dshRuntimeStatusUnsubscribe: (() => void) | null = null;
 
 function ensureDshRuntimeStatusSubscription(): void {
@@ -21,7 +72,7 @@ export interface AgentRuntimeState {
   statusByType: RuntimeStatusByType;
   isChecking: boolean;
   lastCheckedAt: number | null;
-  refresh: (options?: { force?: boolean; type?: AgentTypeKey }) => Promise<void>;
+  refresh: (options?: { force?: boolean }) => Promise<void>;
   refreshIfStale: () => Promise<void>;
 }
 
@@ -36,43 +87,57 @@ export const useAgentRuntimeStore = create<AgentRuntimeState>((set, get) => ({
 
   refresh: async (options) => {
     ensureDshRuntimeStatusSubscription();
-    const { force = false, type } = options ?? {};
+    const { force = false } = options ?? {};
     if (!force && isFresh(get().lastCheckedAt)) return;
 
-    if (inFlightRefresh) {
-      await inFlightRefresh;
-      if (!force && isFresh(get().lastCheckedAt)) return;
-    }
+    if (force) refreshGeneration += 1;
+    if (!inFlightRefresh) {
+      const refreshTask = (async () => {
+        let completedGeneration = -1;
+        do {
+          const generationAtStart = refreshGeneration;
+          set({ isChecking: true });
+          let status: RuntimeStatusByType;
+          try {
+            const report = await agent.runtimeStatus();
+            status = normalizeRuntimeStatusReport(report);
+          } catch (err) {
+            // A force refresh that arrived during this request still needs its
+            // own attempt, even when the older request fails.
+            if (generationAtStart !== refreshGeneration) continue;
+            throw err;
+          }
+          completedGeneration = generationAtStart;
+          set({
+            statusByType: status,
+            lastCheckedAt: Date.now(),
+            isChecking: false,
+          });
+        } while (completedGeneration !== refreshGeneration);
+      })();
 
-    set({ isChecking: true });
-    const refreshTask = (async () => {
-      const status = await agent.runtimeStatus();
-      set((current) => {
-        const nextStatus: RuntimeStatusByType = type
-          ? { ...current.statusByType, [type]: status[type] }
-          : status;
-        return {
-          statusByType: nextStatus,
-          lastCheckedAt: Date.now(),
-          isChecking: false,
-        };
+      const handledRefreshTask = refreshTask.catch((err) => {
+        console.warn('[agent-runtime-store] Failed to refresh runtime status:', err);
+        set({ isChecking: false });
       });
-    })();
-
-    inFlightRefresh = refreshTask;
-    try {
-      await refreshTask;
-    } catch (err) {
-      console.warn('[agent-runtime-store] Failed to refresh runtime status:', err);
-      set({ isChecking: false });
-    } finally {
-      if (inFlightRefresh === refreshTask) {
-        inFlightRefresh = null;
+      inFlightRefresh = handledRefreshTask;
+      try {
+        await handledRefreshTask;
+      } finally {
+        if (inFlightRefresh === handledRefreshTask) inFlightRefresh = null;
       }
+      return;
     }
+
+    await inFlightRefresh;
   },
 
   refreshIfStale: async () => {
     await get().refresh();
   },
 }));
+
+// Recover a bad snapshot left in memory by a previously hot-reloaded bundle.
+if (!isRecord(useAgentRuntimeStore.getState().statusByType)) {
+  useAgentRuntimeStore.setState({ statusByType: {}, lastCheckedAt: null });
+}
diff --git a/app/flowix-web/features/agent/store/agent-session-actions.test.ts b/app/flowix-web/features/agent/store/agent-session-actions.test.ts
index eeffe1d9c..aa23b9485 100644
--- a/app/flowix-web/features/agent/store/agent-session-actions.test.ts
+++ b/app/flowix-web/features/agent/store/agent-session-actions.test.ts
@@ -138,13 +138,19 @@ vi.mock("@features/document/store/document-store", () => ({
   },
 }));
 
-vi.mock("@features/agent/store/agent-access-store", () => ({
-  useAgentAccessStore: {
-    getState: () => ({
-      config: agentAccessMock.config,
-    }),
-  },
-}));
+vi.mock("@features/agent/store/agent-workspace-store", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@features/agent/store/agent-workspace-store")>();
+  const getState = () => ({ ...actual.useAgentWorkspaceStore.getState(), workspaceActions: {
+    ...actual.useAgentWorkspaceStore.getState().workspaceActions,
+    getNotebookFiles: (notebookId: string | null | undefined) => notebookId
+      ? agentAccessMock.config.defaults?.files?.[notebookId] : undefined,
+  } });
+  return { ...actual, ensureAgentWorkspaceReady: vi.fn(async () => {}), useAgentWorkspaceStore: Object.assign(
+    (selector: Parameters<typeof actual.useAgentWorkspaceStore>[0]) => selector ? selector(getState()) : getState(),
+    actual.useAgentWorkspaceStore,
+    { getState },
+  ) };
+});
 
 vi.mock("@features/preferences/store/user-settings-store", () => ({
   useUserSettingsStore: {
@@ -254,7 +260,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     );
 
     const instance = useAgentSessionStore.getState().createInstance({
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       title: "First title",
       threadId: null,
       source: { kind: "thread-card" },
@@ -364,7 +370,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     useChatStore.getState().reconcileRunningRunsFromSnapshot({
       [threadId]: {
         runId: "run-ended-offline",
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         startedAt: Date.now() - 10_000,
         currentTool: null,
       },
@@ -378,7 +384,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     expect(useChatStore.getState().threadStates[threadId].isLoading).toBe(false);
     expect(reconcileCompletedRun).toHaveBeenCalledWith(
-      "deepseek-harness",
+      "dsh",
       threadId,
       "run-ended-offline",
     );
@@ -395,8 +401,8 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     );
     const threadId = "active-history-after-ipc-failure";
     useChatStore.setState({
-      activeThreadIds: { "deepseek-harness": threadId },
-      threadTypes: { [threadId]: "deepseek-harness" },
+      activeThreadIds: { "dsh": threadId },
+      threadTypes: { [threadId]: "dsh" },
     });
     vi.mocked(agent.runningThreads).mockRejectedValueOnce(
       new Error("ipc://localhost/agent_running_threads was blocked"),
@@ -407,7 +413,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     await reconcileAgentRunsAndRefreshEndedHistory();
 
-    expect(loadMessages).toHaveBeenCalledWith("deepseek-harness", threadId);
+    expect(loadMessages).toHaveBeenCalledWith("dsh", threadId);
   });
 
   it("routes streamed assistant text into the same thread state consumed by Thread Card", async () => {
@@ -418,7 +424,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "thread-card-flowix";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatchAgentChunk({ kind: "stream_start", thread_id: threadId, run_id: "run-flowix" });
     store.dispatchAgentChunk({
       kind: "text",
@@ -486,7 +492,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "thread-card-optimistic-user";
 
-    await store.sendMessageToThread(threadId, "Hello from user", "deepseek-harness");
+    await store.sendMessageToThread(threadId, "Hello from user", "dsh");
 
     const renderMessages =
       useAgentConversationStore.getState().messageStates[threadId]?.messages ??
@@ -529,7 +535,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const { useAgentSessionStore } = await import("@features/agent/store/agent-session-store");
     vi.mocked(agent.chatStream).mockRejectedValueOnce(new Error("request was rejected"));
     await expect(useAgentSessionStore.getState().sendMessageToThread(
-      "thread-rejected-dispatch", "keep input", "deepseek-harness", { rejectOnFailure: true },
+      "thread-rejected-dispatch", "keep input", "dsh", { rejectOnFailure: true },
     )).rejects.toThrow("request was rejected");
     expect(useAgentSessionStore.getState().threadProjections["thread-rejected-dispatch"].runs.isLoading).toBe(false);
   });
@@ -541,21 +547,21 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const activeThreadId = "thread-card-active-title";
     const cardThreadId = "thread-card-secondary-title";
     const cardInstance = useAgentConversationStore.getState().createInstance({
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       title: "B title",
       threadId: cardThreadId,
       source: { kind: "thread-card" },
     });
 
     useChatStore.setState({
-      activeThreadIds: { "deepseek-harness": activeThreadId },
+      activeThreadIds: { "dsh": activeThreadId },
       currentThreadTitles: { [activeThreadId]: "A title" },
     });
 
     await useChatStore.getState().sendMessageToThread(
       cardThreadId,
       "message from B",
-      "deepseek-harness",
+      "dsh",
       {
         instanceId: cardInstance.instanceId,
         conversationTitle: "B title",
@@ -564,7 +570,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     );
 
     expect(useChatStore.getState().currentThreadTitles[activeThreadId]).toBe("A title");
-    expect(useChatStore.getState().threadLists["deepseek-harness"]).toEqual([]);
+    expect(useChatStore.getState().threadLists["dsh"]).toEqual([]);
     expect(
       useAgentConversationStore
         .getState()
@@ -589,7 +595,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     await useChatStore.getState().sendMessageToThread(
       threadId,
       "follow up from canonical",
-      "deepseek-harness",
+      "dsh",
       {
         currentNoteContent: "note context should not be appended",
       },
@@ -609,7 +615,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const threadId = "thread-low-frequency-conversation-live";
     const toolCallId = "tool-live-state";
 
-    useChatStore.getState().bindThreadType(threadId, "deepseek-harness");
+    useChatStore.getState().bindThreadType(threadId, "dsh");
     await seedProjection(threadId, (projection) => ({
       ...projection,
       messages: [
@@ -633,7 +639,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       id: toolCallId,
       name: "Read",
       result: { content: "file contents from conversation state" },
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
     });
 
     const message =
@@ -661,19 +667,19 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const runId = "claude-live-reasoning-run";
     const store = useChatStore.getState();
 
-    store.bindThreadType(threadId, "claude");
+    store.bindThreadType(threadId, "claudecode");
     const chunks: AgentChunk[] = [
       {
         kind: "stream_start",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
       },
       {
         kind: "reasoning",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         text: "first thought\n\n",
         message_id: "reasoning-provider-message-1-block-0",
         message_phase: "updated",
@@ -686,7 +692,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "tool_call",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         id: "tool-cycle-1",
         name: "Bash",
         input: { command: "pwd" },
@@ -700,7 +706,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "tool_result",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         id: "tool-cycle-1",
         name: "Bash",
         result: { content: "/workspace" },
@@ -714,7 +720,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "reasoning",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         text: "second thought",
         message_id: "reasoning-provider-message-2-block-0",
         message_phase: "updated",
@@ -727,7 +733,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "text",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         text: "final answer",
         message_id: "assistant-provider-message-2-block-1",
         message_phase: "updated",
@@ -740,7 +746,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "stream_end",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         reason: null,
       },
     ];
@@ -755,13 +761,13 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     expect(reasoning).toHaveLength(1);
     expect(reasoning[0]).toMatchObject({
-      id: `msg:claude:${runId}:reasoning:reasoning-${runId}`,
+      id: `msg:claudecode:${runId}:reasoning:reasoning-${runId}`,
       content: "first thought\n\nsecond thought",
       isCompleted: true,
     });
     expect(tools).toHaveLength(1);
     expect(tools[0]).toMatchObject({
-      toolCallId: `msg:claude:${runId}:tool-call:tool-cycle-1`,
+      toolCallId: `msg:claudecode:${runId}:tool-call:tool-cycle-1`,
       isLoading: false,
     });
     expect(messages.map((message) => message.role)).toEqual([
@@ -786,18 +792,18 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const runId = "claude-reasoning-only-run";
     const store = useChatStore.getState();
 
-    store.bindThreadType(threadId, "claude");
+    store.bindThreadType(threadId, "claudecode");
     store.dispatchAgentChunk({
       kind: "stream_start",
       thread_id: threadId,
       run_id: runId,
-      agent_type: "claude",
+      agent_type: "claudecode",
     });
     store.dispatchAgentChunk({
       kind: "reasoning",
       thread_id: threadId,
       run_id: runId,
-      agent_type: "claude",
+      agent_type: "claudecode",
       text: "reasoning without final text",
       message_id: "reasoning-provider-message-only-block-0",
       message_phase: "updated",
@@ -807,7 +813,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       kind: "stream_end",
       thread_id: threadId,
       run_id: runId,
-      agent_type: "claude",
+      agent_type: "claudecode",
       reason: null,
     });
 
@@ -815,7 +821,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       useAgentConversationStore.getState().messageStates[threadId];
     expect(messageState.messages).toMatchObject([
       {
-        id: `msg:claude:${runId}:reasoning:reasoning-${runId}`,
+        id: `msg:claudecode:${runId}:reasoning:reasoning-${runId}`,
         role: "reasoning",
         content: "reasoning without final text",
         isCompleted: true,
@@ -834,13 +840,13 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const runId = "claude-live-envelope-run";
     const store = useChatStore.getState();
 
-    store.bindThreadType(threadId, "claude");
+    store.bindThreadType(threadId, "claudecode");
     const chunks: AgentChunk[] = [
       {
         kind: "stream_start",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
       },
       ...[
         ["d9193ae4-86b5-47a6-9e85-1bb4ef0acc1c", "first "],
@@ -850,7 +856,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
           kind: "text",
           thread_id: threadId,
           run_id: runId,
-          agent_type: "claude",
+          agent_type: "claudecode",
           text,
           message_id: `assistant-${envelopeId}-block-1`,
           message_phase: "updated",
@@ -864,7 +870,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "tool_call",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         id: "legacy-text-tool",
         name: "Bash",
         input: { command: "pwd" },
@@ -878,7 +884,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "tool_result",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         id: "legacy-text-tool",
         name: "Bash",
         result: { content: "/workspace" },
@@ -896,7 +902,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
           kind: "text",
           thread_id: threadId,
           run_id: runId,
-          agent_type: "claude",
+          agent_type: "claudecode",
           text,
           message_id: `assistant-${envelopeId}-block-1`,
           message_phase: "updated",
@@ -910,7 +916,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
         kind: "stream_end",
         thread_id: threadId,
         run_id: runId,
-        agent_type: "claude",
+        agent_type: "claudecode",
         reason: null,
       },
     ];
@@ -941,7 +947,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     );
     const threadId = "thread-buffered-conversation-live";
 
-    useChatStore.getState().bindThreadType(threadId, "deepseek-harness");
+    useChatStore.getState().bindThreadType(threadId, "dsh");
     // Phase 2 (2026-08-02): session-store 是真源, 直接 seed 它. mirror 会自动
     // 把同步状态写到 conv-store 与 chat-store, 断言仍走两个老 store.
     await seedProjection(threadId, (p) => ({
@@ -962,7 +968,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       thread_id: threadId,
       run_id: "run-buffered-live",
       text: "world",
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
     });
 
     await flushAnimationFrame();
@@ -987,12 +993,12 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "thread-card-missed-start";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatchAgentChunk({
       kind: "text",
       thread_id: threadId,
       run_id: "run-restored",
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
       text: "still running",
     });
 
@@ -1104,14 +1110,14 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     useChatStore.getState().reconcileRunningRunsFromSnapshot({
       [threadId]: {
         runId: "run-snapshot-instance-running",
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         startedAt: 1234,
         currentTool: "shell",
       },
     });
 
     expect(useAgentConversationStore.getState().findByThreadId(threadId)).toMatchObject({
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       title: "Snapshot restored title",
       threadId,
       source: { kind: "thread-card" },
@@ -1217,7 +1223,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "thread-card-stale-running";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatchAgentChunk({
       kind: "stream_start",
       thread_id: threadId,
@@ -1264,7 +1270,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     vi.mocked(agent.runningThreads).mockReturnValueOnce(new Promise((resolve) => { finishQuery = resolve; }));
     const pending = useAgentSessionStore.getState().reconcileRunningRuns();
     useAgentSessionStore.getState().dispatchAgentChunk({
-      kind: "stream_start", thread_id: threadId, run_id: "new-run", agent_type: "claude",
+      kind: "stream_start", thread_id: threadId, run_id: "new-run", agent_type: "claudecode",
     });
     now += 10_000;
     finishQuery({});
@@ -1318,8 +1324,8 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "thread-card-optimistic-run";
 
-    store.bindThreadType(threadId, "deepseek-harness");
-    await store.sendMessageToThread(threadId, "hello optimistic", "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
+    await store.sendMessageToThread(threadId, "hello optimistic", "dsh");
     expect(useChatStore.getState().threadStates[threadId].isLoading).toBe(true);
 
     store.reconcileRunningRunsFromSnapshot({});
@@ -1360,7 +1366,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     // 鍒涘缓涓€涓湁 content 鐨?thread, 鐒跺悗 dispatch 涓€浜?chunk 璁?threadStates
     // 绱Н messages / runs 鈹€鈹€ 杩欐槸 deleteThread 涔嬪墠鐨勭姸鎬併€?  
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatchAgentChunk({
       kind: "stream_start",
       thread_id: threadId,
@@ -1371,7 +1377,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       thread_id: threadId,
       run_id: "run-1",
       text: "answer body that should be wiped on delete",
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
     });
     store.dispatchAgentChunk({
       kind: "tool_call",
@@ -1380,7 +1386,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       id: "call-x",
       name: "read",
       input: {},
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
     });
 
     // rAF flush 璁?text chunk 鐪熸钀藉埌 messages / pendingAssistantId 涓?    // (涓?`routes streamed assistant text` 娴嬭瘯鍚屽舰 鈹€ 绂昏繖鍧楃殑璇?text
@@ -1406,7 +1412,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
   it("deleteThread clears threadTypes and reverse-mapped externalSessionResolutions", async () => {
     // 淇 #7: deleteThread 涔嬪墠娌℃竻 `state.threadTypes[threadId]`, 鐣欎笅瀛ゅ効
-    // 鏉＄洰 鈹€鈹€ 鍚庣画 `get().threadTypes[threadId] ?? "deepseek-harness"` 浼氭嬁鍒版棫 type,
+    // 鏉＄洰 鈹€鈹€ 鍚庣画 `get().threadTypes[threadId] ?? "dsh"` 浼氭嬁鍒版棫 type,
     // 璇垽 dispatch 璺緞銆?鍚屾椂鍙嶅悜鏄犲皠 `externalSessionResolutions[local] === threadId`
     // (鍗?local id 宸茬粡琚?resolve 鍒拌繖涓鍒犵殑 thread) 涔熻娓? 鍚﹀垯 findByThreadId
     // 浼氳鍛戒腑宸插垹 id銆?  
@@ -1974,7 +1980,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const secondThreadId = "thread-card-flowix";
 
     store.bindThreadType(firstThreadId, "codex");
-    store.bindThreadType(secondThreadId, "deepseek-harness");
+    store.bindThreadType(secondThreadId, "dsh");
 
     const chunks: AgentChunk[] = [
       { kind: "stream_start", thread_id: firstThreadId, run_id: "run-codex" },
@@ -2004,7 +2010,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       state.threadStates[secondThreadId].runs[
         state.threadStates[secondThreadId].activeRunId ?? ""
       ]?.agentType,
-    ).toBe("deepseek-harness");
+    ).toBe("dsh");
   });
 
   it("loads Codex history through paged IPC", async () => {
@@ -2135,7 +2141,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     const messages = await useAgentSessionStore
       .getState()
-      .reloadMessagesFromHistory("deepseek-harness", threadId);
+      .reloadMessagesFromHistory("dsh", threadId);
 
     expect(agent.getDeepSeekHarnessThread).toHaveBeenCalledWith(threadId);
     expect(messages).toEqual(
@@ -2218,14 +2224,14 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "claude-history-tool-merge";
 
-    store.bindThreadType(threadId, "claude");
+    store.bindThreadType(threadId, "claudecode");
     store.dispatchAgentChunk({
       kind: "tool_call",
       thread_id: threadId,
       id: "toolu_1",
       name: "Read",
       input: { file_path: "README.md" },
-      agent_type: "claude",
+      agent_type: "claudecode",
     });
     store.dispatchAgentChunk({
       kind: "tool_result",
@@ -2233,7 +2239,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       id: "toolu_1",
       name: "",
       result: { content: "file contents" },
-      agent_type: "claude",
+      agent_type: "claudecode",
     });
 
     vi.mocked(agent.listClaudeThreads).mockResolvedValueOnce([
@@ -2318,7 +2324,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const store = useChatStore.getState();
     const threadId = "thread-card-tool";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatchAgentChunk({ kind: "stream_start", thread_id: threadId, run_id: "run-tool" });
     store.dispatchAgentChunk({
       kind: "tool_call",
@@ -2574,7 +2580,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
     const store = useChatStore.getState();
 
-    // 鍒濆 activeAgentTypeKey (DEFAULT_AGENT_TYPE_KEY 閫氬父鏄?'deepseek-harness', 浣嗕笉渚濊禆鍏蜂綋鍊?
+    // 鍒濆 activeAgentTypeKey (DEFAULT_AGENT_TYPE_KEY 閫氬父鏄?'dsh', 浣嗕笉渚濊禆鍏蜂綋鍊?
     const initialType = useChatStore.getState().activeAgentTypeKey;
 
     // 鍒囧埌 codex thread 鈹€鈹€ 浠呮洿鏂?activeThreadIds.codex, 涓嶅姩 activeAgentTypeKey銆?  
@@ -2584,7 +2590,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     // 鍒囧埌 flowix thread 鈹€鈹€ 鍚屾牱涓嶅姩 activeAgentTypeKey銆?  
     store.setActiveThreadId("flowix-thread-1");
-    expect(useChatStore.getState().activeThreadIds["deepseek-harness"]).toBe("flowix-thread-1");
+    expect(useChatStore.getState().activeThreadIds["dsh"]).toBe("flowix-thread-1");
     expect(useChatStore.getState().activeAgentTypeKey).toBe(initialType);
 
     // setActiveAgentThread 浠嶇劧鍚屾涓よ€?鈹€鈹€ 杩欐槸璺?runtime 鍒囨崲鐨勬樉寮忓叆鍙ｃ€?  
@@ -2609,7 +2615,7 @@ describe("chat-store Agent Thread Card streaming flow", () => {
 
     // 鈹€鈹€ 鎯呭舰 2: thread 璺戣繃浣嗗凡鑷劧缁撴潫銆?  
     const finishedThreadId = "thread-stop-already-ended";
-    store.bindThreadType(finishedThreadId, "deepseek-harness");
+    store.bindThreadType(finishedThreadId, "dsh");
     store.dispatchAgentChunk({
       kind: "stream_start",
       thread_id: finishedThreadId,
@@ -2674,6 +2680,18 @@ describe("chat-store Agent Thread Card streaming flow", () => {
     expect(payload).not.toHaveProperty("codexModel");
   });
 
+  it("sends using canonical Agent preferences instead of stale session settings", async () => {
+    const { useAgentDataStore } = await import("./agent-data-store");
+    const { useAgentSessionStore } = await import("./agent-session-store");
+    const { agent } = await import("@platform/tauri/client");
+    const store = useAgentDataStore.getState();
+    store.setUserPreference("codex", { model: { id: "new-model" }, permission: "read-only" });
+    store.rememberModelReasoning("codex", { id: "new-model" }, "low");
+    useAgentSessionStore.getState().setSessionMeta((meta) => ({ ...meta, settings: { ...meta.settings, agentCodexModel: "stale-model", agentPermissionMode: "danger-full-access" } }));
+    await useAgentSessionStore.getState().sendMessageToThread("canonical-preferences", "hello", "codex");
+    expect(vi.mocked(agent.chatStream).mock.lastCall?.[1].runtimeConfig?.codex).toMatchObject({ model: "new-model", permissionMode: "read-only", reasoningEffort: "low" });
+  });
+
   it("derives Codex cwd and workspacePaths from notebook folder defaults + current notebook", async () => {
     const { agent } = await import("@platform/tauri/client");
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
@@ -2683,12 +2701,10 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       path: "D:\\projects\\flowix",
     };
     agentAccessMock.config = {
-      // defaults.folders 里的每个 folder 必须在 entries 里有对应的
-      // enabled && !missing 授权条目, 否则 resolveAuthorizedDefaultFiles
-      // 会把它收窄掉 (防越权)。
+      // The workspace adapter intersects notebook add-dirs with enabled access entries.
       entries: [
         { id: "e-notes-main", kind: "folder", path: "D:\\notes\\main", name: "main", enabled: true, missing: false },
-        { id: "e-flowix", kind: "folder", path: "D:\\projects\\flowix", name: "deepseek-harness", enabled: true, missing: false },
+        { id: "e-flowix", kind: "folder", path: "D:\\projects\\flowix", name: "dsh", enabled: true, missing: false },
       ],
       defaults: {
         files: {
@@ -2839,30 +2855,30 @@ describe("chat-store Agent Thread Card streaming flow", () => {
   it("renames local agent threads through the standard action", async () => {
     const { agent } = await import("@platform/tauri/client");
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
-    const threadId = "thread-card-rename-gemini";
+    const threadId = "thread-card-rename-codex";
     vi.mocked(agent.listLocalAgentThreads).mockResolvedValueOnce([
       { threadId, title: "New title", createdAt: 1, updatedAt: 2 },
     ]);
 
     useChatStore.setState((state) => ({
-      threadTypes: { ...state.threadTypes, [threadId]: "gemini" },
+      threadTypes: { ...state.threadTypes, [threadId]: "codex" },
       threadLists: {
         ...state.threadLists,
-        gemini: [{ threadId, title: "Old title", createdAt: 1, updatedAt: 1 }],
+        codex: [{ threadId, title: "Old title", createdAt: 1, updatedAt: 1 }],
       },
     }));
 
     await useChatStore
       .getState()
-      .renameThread(threadId, "  New   title  ", "gemini");
+      .renameThread(threadId, "  New   title  ", "codex");
 
     const state = useChatStore.getState();
     expect(state.currentThreadTitles[threadId]).toBe("New title");
-    expect(state.threadLists.gemini?.[0]?.title).toBe("New title");
+    expect(state.threadLists.codex?.[0]?.title).toBe("New title");
     expect(agent.updateThreadTitle).toHaveBeenCalledWith(
       threadId,
       "New title",
-      "gemini",
+      "codex",
     );
   });
 
@@ -2882,17 +2898,17 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       },
     ]);
     const instance = useAgentConversationStore.getState().createInstance({
-      agentType: "gemini",
+      agentType: "codex",
       title: "Old conversation title",
       threadId,
       source: { kind: "thread-card" },
     });
 
     useChatStore.setState((state) => ({
-      threadTypes: { ...state.threadTypes, [threadId]: "gemini" },
+      threadTypes: { ...state.threadTypes, [threadId]: "codex" },
       threadLists: {
         ...state.threadLists,
-        gemini: [
+        codex: [
           {
             threadId,
             title: "Old conversation title",
@@ -2912,13 +2928,13 @@ describe("chat-store Agent Thread Card streaming flow", () => {
       useAgentConversationStore.getState().getInstance(instance.instanceId)
         ?.title,
     ).toBe("New conversation title");
-    expect(useChatStore.getState().threadLists.gemini?.[0]?.title).toBe(
+    expect(useChatStore.getState().threadLists.codex?.[0]?.title).toBe(
       "New conversation title",
     );
     expect(agent.updateThreadTitle).toHaveBeenCalledWith(
       threadId,
       "New conversation title",
-      "gemini",
+      "codex",
     );
   });
 
diff --git a/app/flowix-web/features/agent/store/agent-session-runtime-bridges.ts b/app/flowix-web/features/agent/store/agent-session-runtime-bridges.ts
index 58c77b15c..f9ce7f728 100644
--- a/app/flowix-web/features/agent/store/agent-session-runtime-bridges.ts
+++ b/app/flowix-web/features/agent/store/agent-session-runtime-bridges.ts
@@ -1,6 +1,5 @@
 import type { AgentSessionStore } from '@features/agent/store/agent-session-store';
 import { createAgentChunkBridge } from '@features/agent/store/agent-chunk-bridge';
-import { installGlobalAgentSettingsSync } from '@features/agent/store/global-agent-settings-sync';
 import { resolveIncomingChunkThreadId } from '@features/agent/store/agent-chunk-routing';
 import { hasThreadInterest } from '@features/agent/store/thread-interest';
 
@@ -9,8 +8,6 @@ interface AgentSessionStoreAccess {
 }
 
 export function installAgentSessionRuntimeBridges(store: AgentSessionStoreAccess) {
-  installGlobalAgentSettingsSync((updater) => store.getState().setSessionMeta(updater));
-
   return createAgentChunkBridge((chunk) => {
     const canonicalThreadId = resolveIncomingChunkThreadId(chunk, store.getState());
     const runId = chunk.run_id?.trim();
diff --git a/app/flowix-web/features/agent/store/agent-session-store.test.ts b/app/flowix-web/features/agent/store/agent-session-store.test.ts
index cf344e0ef..4eb397602 100644
--- a/app/flowix-web/features/agent/store/agent-session-store.test.ts
+++ b/app/flowix-web/features/agent/store/agent-session-store.test.ts
@@ -10,7 +10,7 @@ import { DEFAULT_AGENT_TYPE_KEY } from "@/lib/agent-types";
 
 const streamStart = (runId: string, threadId = "t1") => ({
   kind: "stream_start" as const,
-  agentType: "deepseek-harness" as const,
+  agentType: "dsh" as const,
   threadId,
   runId,
   timestamp: 0,
@@ -19,7 +19,7 @@ const streamStart = (runId: string, threadId = "t1") => ({
 
 const textDelta = (text: string, runId: string, threadId = "t1") => ({
   kind: "text_delta" as const,
-  agentType: "deepseek-harness" as const,
+  agentType: "dsh" as const,
   threadId,
   runId,
   timestamp: 1000,
@@ -34,7 +34,7 @@ const textDelta = (text: string, runId: string, threadId = "t1") => ({
 
 const streamEnd = (runId: string, threadId = "t1") => ({
   kind: "stream_end" as const,
-  agentType: "deepseek-harness" as const,
+  agentType: "dsh" as const,
   threadId,
   runId,
   timestamp: 2000,
@@ -626,7 +626,7 @@ describe("useAgentSessionStore", () => {
     const store = useAgentSessionStore.getState();
     const threadId = "steer-stop-thread";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatch(streamStart("steer-stop-run", threadId));
     store.enqueueSteeringMessage({
       id: "pending-steer-stop",
@@ -646,7 +646,7 @@ describe("useAgentSessionStore", () => {
     const threadId = "steer-error-thread";
     const runId = "steer-error-run";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatch(streamStart(runId, threadId));
     store.enqueueSteeringMessage({
       id: "pending-steer-error",
@@ -657,7 +657,7 @@ describe("useAgentSessionStore", () => {
 
     store.dispatchAgentChunk({
       kind: "stream_end",
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
       thread_id: threadId,
       run_id: runId,
       reason: "provider exited unexpectedly",
@@ -670,7 +670,7 @@ describe("useAgentSessionStore", () => {
     const store = useAgentSessionStore.getState();
     const threadId = "steer-stale-end-thread";
 
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     store.dispatch(streamStart("steer-old-run", threadId));
     store.dispatch(streamStart("steer-new-run", threadId));
     store.enqueueSteeringMessage({
@@ -682,7 +682,7 @@ describe("useAgentSessionStore", () => {
 
     store.dispatchAgentEvent({
       kind: "stream_end",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId,
       runId: "steer-old-run",
       timestamp: 2,
@@ -737,7 +737,7 @@ describe("useAgentSessionStore", () => {
     const before = useAgentSessionStore.getState();
     before.dispatch({
       kind: "session_resolved",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "test-run",
       timestamp: 0,
@@ -811,7 +811,7 @@ describe("useAgentSessionStore persist", () => {
   });
 
   it("starts with current defaults when only obsolete CHAT data exists", async () => {
-    localStorage.setItem(STORAGE_KEYS.CHAT, JSON.stringify({ state: { activeAgentTypeKey: "claude" } }));
+    localStorage.setItem(STORAGE_KEYS.CHAT, JSON.stringify({ state: { activeAgentTypeKey: "claudecode" } }));
     const { useAgentSessionStore } = await import("@features/agent/store/agent-session-store");
     expect(useAgentSessionStore.getState().sessionMeta.activeAgentTypeKey).toBe(DEFAULT_AGENT_TYPE_KEY);
   });
@@ -852,7 +852,7 @@ describe("useAgentSessionStore persist", () => {
   it("ignores the obsolete CHAT key when AGENT_SESSION is present", async () => {
     localStorage.setItem(
       STORAGE_KEYS.CHAT,
-      JSON.stringify({ state: { activeAgentTypeKey: "claude" } }),
+      JSON.stringify({ state: { activeAgentTypeKey: "claudecode" } }),
     );
     localStorage.setItem(
       STORAGE_KEYS.AGENT_SESSION,
diff --git a/app/flowix-web/features/agent/store/agent-session-store.ts b/app/flowix-web/features/agent/store/agent-session-store.ts
index 3b566cdc9..9b8f863b4 100644
--- a/app/flowix-web/features/agent/store/agent-session-store.ts
+++ b/app/flowix-web/features/agent/store/agent-session-store.ts
@@ -224,17 +224,17 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
           }
           const state = get();
           const type = getAgentType(typeKey ?? state.sessionMeta.threadTypes[threadId] ?? state.sessionMeta.activeAgentTypeKey);
-          const productThreadId = resolveCommandThreadId(state, threadId, type.key);
+          const productThreadId = resolveCommandThreadId(state, threadId, type.id);
           if (!productThreadId) {
             if (options?.rejectOnFailure) throw new Error("Agent thread was not found");
             return;
           }
-          if (productThreadId !== threadId) return get().sendMessageToThread(productThreadId, content, type.key, options);
+          if (productThreadId !== threadId) return get().sendMessageToThread(productThreadId, content, type.id, options);
           if (state.threadTombstones[threadId] || state.threadMutationGuards[threadId]) {
             if (options?.rejectOnFailure) throw new Error("Agent thread is unavailable");
             return;
           }
-          state.bindThreadType(threadId, type.key);
+          state.bindThreadType(threadId, type.id);
           const isFirstMessage = options?.isFirstMessage ?? (state.threadProjections[threadId]?.messages.length ?? 0) === 0;
           const conversationTitle = normalizeThreadTitle(options?.conversationTitle);
           if (isFirstMessage && conversationTitle) {
@@ -251,7 +251,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
                 : {}),
               threadLists: {
                 ...meta.threadLists,
-                [type.key]: (meta.threadLists[type.key] ?? []).map((item) =>
+                [type.id]: (meta.threadLists[type.id] ?? []).map((item) =>
                   item.threadId === threadId
                     ? { ...item, title: conversationTitle }
                     : item,
@@ -262,7 +262,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
           const { userPayload, llmContent, userMessage } = prepareUserMessage({
             content: trimmed,
             isFirstMessage,
-            agentType: type.key,
+            agentType: type.id,
             currentNoteContent: options?.currentNoteContent,
             systemReminderDirectory:
               options?.runtimeConfig?.workspaceSnapshot?.notebookPath,
@@ -270,7 +270,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
               options?.attachments ?? createAgentMessageAttachments(options?.imagePaths),
           });
           if (
-            (type.key === "codex" || type.key === "deepseek-harness" || type.key === "pi") &&
+            (type.id === "codex" || type.id === "dsh" || type.id === "pi") &&
             isProjectionWorking(get().threadProjections[threadId])
           ) {
             const clientUserMessageId = `flowix-${createRunId(threadId)}`;
@@ -284,7 +284,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
               queuedAt: Date.now(),
               clientUserMessageId,
               llmContent,
-              deliveryMode: type.key === 'pi' || type.key === 'codex' ? 'follow_up' : 'steer',
+              deliveryMode: type.id === 'pi' || type.id === 'codex' ? 'follow_up' : 'steer',
               deliveryStatus: "submitting",
             });
             try {
@@ -292,10 +292,10 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
                 content: trimmed,
                 llmContent,
                 imagePaths: options?.imagePaths,
-                agentType: type.key,
+                agentType: type.id,
                 runtimeConfig: options?.runtimeConfig ?? undefined,
               };
-              if (type.key === "codex") {
+              if (type.id === "codex") {
                 await get().queueCodexFollowUp(
                   threadId,
                   activeTurnMessage,
@@ -307,16 +307,16 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
                   threadId,
                   activeTurnMessage,
                   clientUserMessageId,
-                  type.key === 'pi' ? 'follow_up' : 'steer',
+                  type.id === 'pi' ? 'follow_up' : 'steer',
                 );
                 get().updateSteeringMessage(threadId, pendingId, { deliveryStatus: "queued" });
               }
             } catch (err) {
               get().removeSteeringMessage(threadId, pendingId);
-              logger.error("Failed to queue active-turn message", { error: String(err), agentType: type.key });
+              logger.error("Failed to queue active-turn message", { error: String(err), agentType: type.id });
               get().dispatch({
                 kind: "error",
-                agentType: type.key,
+                agentType: type.id,
                 threadId,
                 runId: get().threadProjections[threadId]?.runs.activeRunId ?? createRunId(threadId),
                 timestamp: Date.now(),
@@ -327,20 +327,20 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
             return;
           }
           const runId = options?.runId ?? createRunId(threadId);
-          userMessage.id = completedRunUserMessageId(type.key, runId);
+          userMessage.id = completedRunUserMessageId(type.id, runId);
           userMessage.renderKey = userMessage.id;
-          if (type.key === "pi") userMessage.messageId = null;
+          if (type.id === "pi") userMessage.messageId = null;
           const startedAt = Date.now();
           state.dispatch({
             kind: "stream_start",
-            agentType: type.key,
+            agentType: type.id,
             threadId,
             runId,
             timestamp: startedAt,
           });
           state.dispatch({
             kind: "user_message",
-            agentType: type.key,
+            agentType: type.id,
             threadId,
             runId,
             timestamp: startedAt,
@@ -349,9 +349,8 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
             attachments: userMessage.attachments,
           });
           if (options?.instanceId) {
-            state.updateThread(options.instanceId, { threadId, agentType: type.key });
+            state.updateThread(options.instanceId, { threadId, agentType: type.id });
           }
-          const settings = get().sessionMeta.settings;
           try {
             await dispatchChatStream({
               threadId,
@@ -360,10 +359,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
               llmContent,
               runId,
               userPayload,
-              agentType: type.key,
-              permissionMode: settings.agentPermissionMode,
-              codexModel: settings.agentCodexModel,
-              codexReasoningEffort: settings.agentCodexReasoningEffort,
+              agentType: type.id,
               runtimeConfig: options?.runtimeConfig ?? undefined,
               imagePaths: options?.imagePaths,
               conversationTitle:
@@ -377,7 +373,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
             );
             get().dispatchAgentEvent({
               kind: "error",
-              agentType: type.key,
+              agentType: type.id,
               threadId,
               runId,
               timestamp: Date.now(),
@@ -389,7 +385,7 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
         stopStream: async () => {
           const meta = get().sessionMeta;
           const type = getAgentType(meta.activeAgentTypeKey);
-          const activeId = meta.activeThreadIds[type.key];
+          const activeId = meta.activeThreadIds[type.id];
           if (activeId) await get().stopThreadRun(activeId);
         },
         stopThreadRun: async (threadId, runId) => {
@@ -427,17 +423,17 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
               meta.threadTypes[threadId] ?? meta.activeAgentTypeKey,
             );
             let stopRunId = targetRunId ??
-              (type.key === "codex" ? pendingCodexCommandRunId : undefined);
+              (type.id === "codex" ? pendingCodexCommandRunId : undefined);
             if (!stopRunId) {
               const running = await agentClient.runningThreads();
               const candidate = Object.entries(running).find(([reportedThreadId, info]) =>
                 (reportedThreadId === threadId || info.pendingThreadId === threadId) &&
-                (!info.agentType || info.agentType === type.key));
+                (!info.agentType || info.agentType === type.id));
               stopRunId = candidate?.[1].runId;
               if (!stopRunId) return;
             }
-            accepted = await agentClient.stopChatStream(threadId, type.key, stopRunId);
-            if (accepted && type.key !== "codex" && (!runId || !activeRunIdBeforeStop || runId === activeRunIdBeforeStop)) {
+            accepted = await agentClient.stopChatStream(threadId, type.id, stopRunId);
+            if (accepted && type.id !== "codex" && (!runId || !activeRunIdBeforeStop || runId === activeRunIdBeforeStop)) {
               get().clearPendingSteeringMessages(threadId);
             }
           } catch (err) {
@@ -615,7 +611,12 @@ export const useAgentSessionStore = create<AgentSessionStore>()(
     },
     {
       name: STORAGE_KEYS.AGENT_SESSION,
+      version: 2,
       storage: createJSONStorage(() => createAgentSessionStateStorage()),
+      migrate: (persisted) => ({
+        ...(persisted as Record<string, unknown>),
+        sessionMeta: rehydrateSessionMeta(persisted),
+      }),
       partialize: (state) => ({
         sessionMeta: {
           ...state.sessionMeta,
diff --git a/app/flowix-web/features/agent/store/agent-session-test-facade.ts b/app/flowix-web/features/agent/store/agent-session-test-facade.ts
index a71d47ee3..98b7d6859 100644
--- a/app/flowix-web/features/agent/store/agent-session-test-facade.ts
+++ b/app/flowix-web/features/agent/store/agent-session-test-facade.ts
@@ -1,3 +1,4 @@
+import { useAgentDataStore } from "./agent-data-store";
 /**
  * Test-only legacy-shape facade over the canonical AgentSessionStore.
  *
@@ -132,6 +133,16 @@ function applyLegacyChatPatch(
     patch.agentPermissionMode !== undefined ||
     patch.agentCodexModel !== undefined ||
     patch.agentCodexReasoningEffort !== undefined;
+  if (hasSettings) {
+    const preferences = useAgentDataStore.getState();
+    preferences.setUserPreference("codex", {
+      ...(patch.agentPermissionMode !== undefined ? { permission: patch.agentPermissionMode } : {}),
+      ...(patch.agentCodexModel !== undefined ? { model: { id: patch.agentCodexModel } } : {}),
+    });
+    if (patch.agentCodexReasoningEffort !== undefined) {
+      preferences.rememberModelReasoning("codex", useAgentDataStore.getState().agents.codex.user.model, patch.agentCodexReasoningEffort);
+    }
+  }
   if (hasMeta || hasSettings) {
     useAgentSessionStore.getState().setSessionMeta((meta) => ({
       ...meta,
diff --git a/app/flowix-web/features/agent/store/agent-user-preferences.ts b/app/flowix-web/features/agent/store/agent-user-preferences.ts
new file mode 100644
index 000000000..4960fed40
--- /dev/null
+++ b/app/flowix-web/features/agent/store/agent-user-preferences.ts
@@ -0,0 +1,38 @@
+import type { AgentHarnessPreset, AgentTypeKey, RuntimeConfig } from "@/types/agent";
+import { modelPreferenceKey, useAgentDataStore } from "./agent-data-store";
+
+/** Apply this Agent's remembered preferences, preserving conversation overrides. */
+export function resolveAgentPreferenceRuntimeConfig(
+  agentType: AgentTypeKey,
+  runtimeConfig: RuntimeConfig = {},
+): RuntimeConfig {
+  const agent = useAgentDataStore.getState().agents[agentType];
+  const preference = agent.user;
+  const model = runtimeConfig.model ?? (preference.model
+    ? { key: preference.model.id, ...(preference.model.providerId ? { providerId: preference.model.providerId } : {}) }
+    : undefined);
+  const modelReasoning = model
+    ? preference.reasoningByModel?.[modelPreferenceKey({ id: model.key, providerId: model.providerId })]
+    : undefined;
+  const supportedEfforts = model
+    ? agent.catalog.models.items.find((item) => item.id === model.key && item.providerId === model.providerId)?.reasoningEfforts
+    : undefined;
+  const defaultEffort = supportedEfforts?.includes("medium") ? "medium" : supportedEfforts?.[0];
+  const reasoningEffort = runtimeConfig.reasoningEffort ?? modelReasoning
+    ?? (!model ? preference.reasoningEffort : defaultEffort);
+  const permission = runtimeConfig.access?.sandbox ?? preference.permission;
+  const serviceTier = runtimeConfig.serviceTier ?? preference.serviceTier;
+  const harnessMode = runtimeConfig.deepseekHarness?.mode ?? preference.mode;
+  // Historical Pi mode snapshots are ignored; Pi mode is shared across conversations.
+  const { pi: _legacyPiMode, ...conversationConfig } = runtimeConfig;
+  return {
+    ...conversationConfig,
+    ...(model ? { model } : {}),
+    ...(permission ? { access: { ...runtimeConfig.access, sandbox: permission } } : {}),
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+    ...(serviceTier ? { serviceTier } : {}),
+    ...(harnessMode && agentType === "dsh"
+      ? { deepseekHarness: { ...runtimeConfig.deepseekHarness, mode: harnessMode as AgentHarnessPreset } }
+      : {}),
+  };
+}
diff --git a/app/flowix-web/features/agent/store/agent-workspace-slice.test.ts b/app/flowix-web/features/agent/store/agent-workspace-slice.test.ts
new file mode 100644
index 000000000..2887151a6
--- /dev/null
+++ b/app/flowix-web/features/agent/store/agent-workspace-slice.test.ts
@@ -0,0 +1,246 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentWorkspaceSnapshot, LegacyAgentRuntimePreferences, NotebookWorkspaceConfig } from "@/lib/types/agent-workspace";
+import { STORAGE_KEYS } from "@/lib/constants";
+
+const backend = vi.hoisted(() => ({ get: vi.fn(), getLegacyPreferences: vi.fn(), attachDirectory: vi.fn(), detachDirectory: vi.fn(), pickDirectory: vi.fn() }));
+const piBackend = vi.hoisted(() => ({ getFeatures: vi.fn(), clearLegacyCodeMode: vi.fn() }));
+vi.mock("@platform/tauri/client", () => ({ agentWorkspace: backend, piModels: piBackend }));
+vi.mock("./agent-session-store", () => ({ useAgentSessionStore: { getState: () => ({ sessionMeta: { settings: {} } }) } }));
+import { ensureAgentPreferencesReady, useAgentDataStore } from "./agent-data-store";
+import { ensureAgentWorkspaceReady, useAgentWorkspaceStore } from "./agent-workspace-store";
+
+const notebook = (id: string) => ({ id, kind: "notebook" as const, path: `/notes/${id}`, name: id, enabled: true, missing: false, addedAt: 1, updatedAt: 1 });
+const resource = { ...notebook("resource"), kind: "folder" as const, path: "/projects/shared" };
+const localConfig: NotebookWorkspaceConfig = { version: 1, revision: 1, addDirs: [{ id: "dir", path: resource.path, label: "Shared", enabled: true }] };
+const snapshot = (): AgentWorkspaceSnapshot => ({ notebooks: [notebook("one"), notebook("two")], notebookConfigs: { one: structuredClone(localConfig), two: { version: 1, revision: 0, addDirs: [] } } });
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  localStorage.clear();
+  useAgentDataStore.setState(useAgentDataStore.getInitialState(), true);
+  useAgentWorkspaceStore.setState(useAgentWorkspaceStore.getInitialState(), true);
+  vi.resetAllMocks();
+  backend.get.mockImplementation(async () => snapshot());
+  backend.getLegacyPreferences.mockResolvedValue(null);
+  piBackend.getFeatures.mockResolvedValue({ toolSearch: false });
+  piBackend.clearLegacyCodeMode.mockResolvedValue(undefined);
+});
+
+describe("Pi mode startup migration", () => {
+  it("treats reselecting the default as an explicit choice ahead of a late migration", async () => {
+    await useAgentDataStore.getState().initializePiMode();
+    useAgentDataStore.getState().setUserPreference("pi", { mode: "writing" });
+    const otherWindow = JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!);
+    otherWindow.state.agents.pi.user.mode = "code";
+    otherWindow.state.userPreferenceRevisions.pi.mode = "0000000000000:legacy";
+    localStorage.setItem(STORAGE_KEYS.AGENT_DATA, JSON.stringify(otherWindow));
+    await useAgentDataStore.persist.rehydrate();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("writing");
+  });
+
+  it("keeps another window's migrated mode before its storage event arrives", async () => {
+    useAgentDataStore.setState({ legacyPreferencesMigrated: true });
+    let finish!: (features: { toolSearch: boolean }) => void;
+    piBackend.getFeatures.mockReturnValue(new Promise((resolve) => { finish = resolve; }));
+    const initializing = useAgentDataStore.getState().initializePiMode();
+    const otherWindow = JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!);
+    otherWindow.state.agents.pi.user.mode = "code";
+    otherWindow.state.userPreferenceRevisions.pi = { mode: "0000000000000:legacy" };
+    localStorage.setItem(STORAGE_KEYS.AGENT_DATA, JSON.stringify(otherWindow));
+    finish({ toolSearch: false });
+    await initializing;
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
+    expect(JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!).state.agents.pi.user.mode).toBe("code");
+  });
+
+  it("gives an imported mode priority over a stale default from another window", async () => {
+    await useAgentDataStore.getState().initializePiMode();
+    const staleDefault = localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!;
+    const imported = JSON.parse(staleDefault);
+    imported.state.agents.pi.user.mode = "code";
+    imported.state.userPreferenceRevisions.pi.mode = "0000000000000:legacy";
+    localStorage.setItem(STORAGE_KEYS.AGENT_DATA, JSON.stringify(imported));
+    await useAgentDataStore.persist.rehydrate();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
+    localStorage.setItem(STORAGE_KEYS.AGENT_DATA, staleDefault);
+    await useAgentDataStore.persist.rehydrate();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
+  });
+
+  it("uses an existing shared choice without reading legacy settings, even if cleanup fails", async () => {
+    useAgentDataStore.getState().setUserPreference("pi", { mode: "writing" });
+    piBackend.getFeatures.mockRejectedValue(new Error("old settings unavailable"));
+    piBackend.clearLegacyCodeMode.mockRejectedValue(new Error("cleanup unavailable"));
+    await useAgentDataStore.getState().initializePiMode();
+    expect(piBackend.getFeatures).not.toHaveBeenCalled();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("writing");
+    expect(useAgentDataStore.getState().loadState.piMode.status).toBe("ready");
+  });
+
+  it("imports the former Pi feature before notebook hydration and only cleans up a durable copy", async () => {
+    piBackend.getFeatures.mockResolvedValue({ toolSearch: true, legacyCodeMode: true });
+    piBackend.clearLegacyCodeMode.mockImplementation(async () => {
+      const persisted = JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!);
+      expect(persisted.state.agents.pi.user.mode).toBe("code");
+    });
+    await useAgentDataStore.getState().initializePiMode();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
+    expect(useAgentDataStore.getState().loadState.piMode.status).toBe("ready");
+    expect(useAgentWorkspaceStore.getState().loadState.workspace.status).toBe("idle");
+    expect(backend.get).not.toHaveBeenCalled();
+    expect(piBackend.clearLegacyCodeMode).toHaveBeenCalledOnce();
+  });
+
+  it("preserves the former Agent runtime default ahead of the Pi feature fallback", async () => {
+    backend.getLegacyPreferences.mockResolvedValue({ pi: { piCodeMode: true } });
+    await useAgentDataStore.getState().initializePiMode();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
+  });
+
+  it("deduplicates initialization and preserves a choice made while migration is reading", async () => {
+    let resolve!: (features: { toolSearch: boolean; legacyCodeMode: boolean }) => void;
+    piBackend.getFeatures.mockReturnValue(new Promise((done) => { resolve = done; }));
+    const first = useAgentDataStore.getState().initializePiMode();
+    const second = useAgentDataStore.getState().initializePiMode();
+    useAgentDataStore.getState().setUserPreference("pi", { mode: "writing" });
+    resolve({ toolSearch: false, legacyCodeMode: true });
+    await Promise.all([first, second]);
+    expect(piBackend.getFeatures).toHaveBeenCalledOnce();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("writing");
+  });
+
+  it("keeps the legacy value when browser persistence fails", async () => {
+    piBackend.getFeatures.mockResolvedValue({ toolSearch: false, legacyCodeMode: true });
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => { throw new Error("quota exceeded"); });
+    await useAgentDataStore.getState().initializePiMode();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
+    expect(piBackend.clearLegacyCodeMode).not.toHaveBeenCalled();
+  });
+
+  it("retries a failed migration without deleting the old preference", async () => {
+    piBackend.getFeatures.mockRejectedValueOnce(new Error("read failed"));
+    await expect(useAgentDataStore.getState().initializePiMode()).rejects.toThrow("read failed");
+    expect(useAgentDataStore.getState().loadState.piMode.status).toBe("error");
+    expect(piBackend.clearLegacyCodeMode).not.toHaveBeenCalled();
+    await useAgentDataStore.getState().initializePiMode();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("writing");
+  });
+});
+
+
+describe("local.db workspace projection", () => {
+  it("derives resources from mounts and excludes missing/disabled paths from runs", async () => {
+    const data = snapshot();
+    data.notebookConfigs.one.addDirs.push(
+      { id: 'missing', path: '/missing', label: 'Missing', enabled: true, missing: true },
+      { id: 'disabled', path: '/disabled', label: 'Disabled', enabled: false },
+    );
+    backend.get.mockResolvedValue(data);
+    expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('one')).toBeUndefined();
+    await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('one')?.folders).toEqual([resource.path]);
+    expect(useAgentWorkspaceStore.getState().workspace.resources).toHaveLength(3);
+  });
+  it("never persists or rehydrates a stale workspace cache", async () => {
+    await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    const persisted = JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!);
+    expect(persisted.state.workspace).toBeUndefined();
+    expect(persisted.state.agents.codex.catalog.capabilities).toBeUndefined();
+    const current = useAgentWorkspaceStore.getState().workspace;
+    persisted.state.workspace = { resources: [], byNotebookId: {}, validatedAt: Date.now()+1000 };
+    localStorage.setItem(STORAGE_KEYS.AGENT_DATA,JSON.stringify(persisted));
+    await useAgentDataStore.persist.rehydrate();
+    expect(useAgentWorkspaceStore.getState().workspace).toBe(current);
+  });
+  it.each(['attach-first','detach-first'])("serializes opposite path operations: %s", async order => {
+    let data = snapshot();
+    backend.attachDirectory.mockImplementation(async (id,path) => {
+      data.notebookConfigs[id].addDirs = [{ id:'saved', path, label:'Shared', enabled:true }];
+      return structuredClone(data);
+    });
+    backend.detachDirectory.mockImplementation(async id => {
+      data.notebookConfigs[id].addDirs=[];
+      return structuredClone(data);
+    });
+    await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    const actions = useAgentWorkspaceStore.getState().workspaceActions;
+    await Promise.all(order==='attach-first' ? [actions.attachFolderToNotebook('two',resource.path),actions.detachFolderFromNotebook('two',resource.path)] : [actions.detachFolderFromNotebook('one',resource.path),actions.attachFolderToNotebook('one',resource.path)]);
+    expect(actions.getNotebookFiles(order==='attach-first'?'two':'one')?.folders).toEqual(order==='attach-first'?[]:[resource.path]);
+  });
+  it("picks and mounts in one scoped call without creating a global resource", async () => {
+    const data = snapshot();
+    data.notebookConfigs.two.addDirs=structuredClone(localConfig.addDirs);
+    backend.pickDirectory.mockResolvedValue(data);
+    expect((await useAgentWorkspaceStore.getState().workspaceActions.addFolderFromPicker(null)).ok).toBe(false);
+    expect(backend.pickDirectory).not.toHaveBeenCalled();
+    expect((await useAgentWorkspaceStore.getState().workspaceActions.addFolderFromPicker('two')).ok).toBe(true);
+    expect(backend.pickDirectory).toHaveBeenCalledWith('two');
+    expect(backend.attachDirectory).not.toHaveBeenCalled();
+    expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('two')?.folders).toEqual([resource.path]);
+  });
+  it("ignores a read started before a committed mutation", async () => {
+    await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    let finish!: (data: AgentWorkspaceSnapshot) => void;
+    backend.get.mockReturnValueOnce(new Promise<AgentWorkspaceSnapshot>(resolve => {finish=resolve;}));
+    const reading=useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    const saved=snapshot(); saved.notebookConfigs.one.addDirs=[];
+    backend.detachDirectory.mockResolvedValue(saved);
+    await useAgentWorkspaceStore.getState().workspaceActions.detachFolderFromNotebook('one',resource.path);
+    finish(snapshot()); await reading;
+    expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('one')?.folders).toEqual([]);
+  });
+  it("migrates old user preferences without writing the legacy JSON", async () => {
+    backend.getLegacyPreferences.mockResolvedValue({codex:{model:{key:'legacy-model'}}});
+    await useAgentDataStore.getState().initializeLegacyPreferences();
+    expect(useAgentDataStore.getState().agents.codex.user.model?.id).toBe('legacy-model');
+    expect(JSON.parse(localStorage.getItem(STORAGE_KEYS.AGENT_DATA)!).state.legacyPreferencesMigrated).toBe(true);
+  });
+  it("waits for legacy preference migration before preparing an Agent request", async () => {
+    let finish!: (value: LegacyAgentRuntimePreferences | null) => void;
+    backend.getLegacyPreferences.mockReturnValueOnce(new Promise((resolve) => { finish = resolve; }));
+    const ready = ensureAgentPreferencesReady("codex");
+    await Promise.resolve();
+    expect(useAgentDataStore.getState().agents.codex.user.model).toBeUndefined();
+    finish({ codex: { model: { key: "legacy-model" } } });
+    await ready;
+    expect(useAgentDataStore.getState().agents.codex.user.model?.id).toBe("legacy-model");
+  });
+  it("reports a database failure and retries", async () => {
+    backend.get.mockRejectedValueOnce(new Error('database unavailable'));
+    await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    expect(useAgentWorkspaceStore.getState().loadState.workspace.status).toBe('error');
+    await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+    expect(useAgentWorkspaceStore.getState().loadState.workspace.status).toBe('ready');
+  });
+});
+
+it("waits for initial database hydration before allowing a workspace snapshot", async () => {
+  let finish!: (snapshot: AgentWorkspaceSnapshot) => void;
+  backend.get.mockReturnValueOnce(new Promise<AgentWorkspaceSnapshot>(resolve => { finish=resolve; }));
+  const ready = ensureAgentWorkspaceReady();
+  expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('one')).toBeUndefined();
+  finish(snapshot()); await ready;
+  expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('one')?.folders).toEqual([resource.path]);
+});
+
+it("loads database mounts even when importing old preferences fails", async () => {
+  backend.getLegacyPreferences.mockRejectedValue(new Error('legacy JSON unavailable'));
+  expect(await useAgentWorkspaceStore.getState().workspaceActions.loadInitial()).toBe(true);
+  await expect(useAgentDataStore.getState().initializeLegacyPreferences()).rejects.toThrow('legacy JSON unavailable');
+  expect(useAgentDataStore.getState().legacyPreferencesMigrated).toBe(false);
+  expect(useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles('one')?.folders).toEqual([resource.path]);
+});
+
+it("waits for the newer startup read when its own read was superseded", async () => {
+  let first!: (data: AgentWorkspaceSnapshot) => void;
+  let second!: (data: AgentWorkspaceSnapshot) => void;
+  backend.get.mockReturnValueOnce(new Promise<AgentWorkspaceSnapshot>(resolve => { first=resolve; }));
+  backend.get.mockReturnValueOnce(new Promise<AgentWorkspaceSnapshot>(resolve => { second=resolve; }));
+  const ready=ensureAgentWorkspaceReady();
+  const newer=useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+  first(snapshot());
+  await Promise.resolve(); await Promise.resolve();
+  second(snapshot());
+  await Promise.all([ready,newer]);
+  expect(useAgentWorkspaceStore.getState().loadState.workspace.status).toBe('ready');
+});
diff --git a/app/flowix-web/features/agent/store/agent-workspace-slice.ts b/app/flowix-web/features/agent/store/agent-workspace-slice.ts
new file mode 100644
index 000000000..bba7e4028
--- /dev/null
+++ b/app/flowix-web/features/agent/store/agent-workspace-slice.ts
@@ -0,0 +1,124 @@
+import { createLogger } from '@/lib/logger';
+import { agentWorkspace } from '@platform/tauri/client';
+import type { AgentWorkspaceSnapshot, AgentWorkspaceResource } from '@/lib/types/agent-workspace';
+import type { FilesConfig } from '@/types/agent';
+
+const logger = createLogger('agent-workspace');
+export type AgentAccessErrorCode = 'not-selected' | 'already-tracked' | 'save-failed';
+export interface AgentWorkspaceNotebook {
+  notebook: { id: string; name: string; path: string };
+  addDirs: Array<{
+    id: string;
+    path: string;
+    label: string;
+    enabled: boolean;
+    missing: boolean;
+  }>;
+}
+export interface AgentWorkspaceState {
+  /** In-memory projection of local.db; runtime authorization remains backend-owned. */
+  resources: AgentWorkspaceResource[];
+  byNotebookId: Record<string, AgentWorkspaceNotebook>;
+  validatedAt?: number;
+}
+export interface AgentWorkspaceActions {
+  loadInitial: () => Promise<boolean>;
+  getNotebookFiles: (notebookId: string | null | undefined) => FilesConfig | undefined;
+  /** The picker and mount commit share one notebook-scoped backend operation. */
+  addFolderFromPicker: (notebookId: string | null | undefined) => Promise<
+    { ok: true } | { ok: false; code: AgentAccessErrorCode }>;
+  attachFolderToNotebook: (notebookId: string | null | undefined, path: string) => Promise<'saved' | 'already-attached' | false>;
+  detachFolderFromNotebook: (notebookId: string | null | undefined, path: string) => Promise<'saved' | 'not-attached' | false>;
+}
+export type AgentWorkspaceLoadStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface AgentWorkspaceLoadState { status: AgentWorkspaceLoadStatus; error?: string }
+
+export interface AgentWorkspaceSliceStoreState {
+  workspace: AgentWorkspaceState;
+  loadState: { workspace: AgentWorkspaceLoadState };
+  workspaceActions: AgentWorkspaceActions;
+}
+
+export function createAgentWorkspaceSlice(
+  getStore: () => AgentWorkspaceSliceStoreState,
+  publishWorkspace: (snapshot: AgentWorkspaceSnapshot) => void,
+  setLoadState: (state: AgentWorkspaceLoadState) => void,
+): AgentWorkspaceActions {
+  let generation = 0;
+  let writeQueue: Promise<unknown> = Promise.resolve();
+  async function mutate<T>(operation: () => Promise<T>): Promise<T> {
+    const request = writeQueue.catch(() => undefined).then(async () => {
+      return operation();
+    });
+    writeQueue = request;
+    return request;
+  }
+  const publish = (snapshot: AgentWorkspaceSnapshot) => {
+    ++generation;
+    publishWorkspace(snapshot);
+    setLoadState({ status: 'ready' });
+  };
+  return {
+    getNotebookFiles: (notebookId) => {
+      if (!notebookId || getStore().loadState.workspace.status !== 'ready') return undefined;
+      const notebook = getStore().workspace.byNotebookId[notebookId];
+      if (!notebook) return undefined;
+      return { workspace: null, folders: notebook.addDirs.filter(d => d.enabled && !d.missing).map(d => d.path), notebooks: [] };
+    },
+    loadInitial: async () => {
+      const requestGeneration = ++generation;
+      if (!getStore().workspace.validatedAt) setLoadState({ status: 'loading' });
+      try {
+        const snapshot = await agentWorkspace.get();
+        if (requestGeneration !== generation) return false;
+        publish(snapshot);
+        return true;
+      } catch (error) {
+        if (requestGeneration === generation) setLoadState({ status: 'error', error: String(error) });
+        logger.error('Workspace hydration failed', { error });
+        return false;
+      }
+    },
+    addFolderFromPicker: async (notebookId) => {
+      if (!notebookId) return { ok: false, code: 'not-selected' };
+      return mutate(async () => {
+        try {
+          const picked = await agentWorkspace.pickDirectory(notebookId);
+          if (!picked) return { ok: false as const, code: 'not-selected' as const };
+          publish(picked);
+          return { ok: true as const };
+        } catch (error) {
+          logger.error('Directory picker failed', { error });
+          await getStore().workspaceActions.loadInitial();
+          return { ok: false as const, code: 'save-failed' as const };
+        }
+      });
+    },
+    attachFolderToNotebook: async (notebookId, path) => {
+      if (!notebookId) return false;
+      return mutate(async () => {
+        try {
+          publish(await agentWorkspace.attachDirectory(notebookId, path));
+          return 'saved' as const;
+        } catch (error) {
+          logger.error('Directory attachment failed', { error });
+          await getStore().workspaceActions.loadInitial();
+          return false;
+        }
+      });
+    },
+    detachFolderFromNotebook: async (notebookId, path) => {
+      if (!notebookId) return false;
+      return mutate(async () => {
+        try {
+          publish(await agentWorkspace.detachDirectory(notebookId, path));
+          return 'saved' as const;
+        } catch (error) {
+          logger.error('Directory removal failed', { error });
+          await getStore().workspaceActions.loadInitial();
+          return false;
+        }
+      });
+    },
+  };
+}
diff --git a/app/flowix-web/features/agent/store/agent-workspace-store.ts b/app/flowix-web/features/agent/store/agent-workspace-store.ts
new file mode 100644
index 000000000..0987a9731
--- /dev/null
+++ b/app/flowix-web/features/agent/store/agent-workspace-store.ts
@@ -0,0 +1,79 @@
+import { create } from 'zustand';
+import type { AgentWorkspaceSnapshot, AgentWorkspaceResource } from '@/lib/types/agent-workspace';
+import { createAgentWorkspaceSlice, type AgentWorkspaceSliceStoreState } from './agent-workspace-slice';
+
+export type {
+  AgentAccessErrorCode,
+  AgentWorkspaceActions,
+  AgentWorkspaceLoadState,
+  AgentWorkspaceLoadStatus,
+  AgentWorkspaceNotebook,
+  AgentWorkspaceState,
+} from './agent-workspace-slice';
+
+export interface AgentWorkspaceStoreState extends AgentWorkspaceSliceStoreState {}
+
+export function projectAgentWorkspace(
+  snapshot: AgentWorkspaceSnapshot,
+): Pick<AgentWorkspaceStoreState['workspace'], 'resources' | 'byNotebookId' | 'validatedAt'> {
+  const resourcesByPath = new Map<string, AgentWorkspaceResource>();
+  const byNotebookId: AgentWorkspaceStoreState['workspace']['byNotebookId'] = {};
+  for (const notebook of snapshot.notebooks) {
+    const addDirs = (snapshot.notebookConfigs[notebook.id]?.addDirs ?? []).map((directory) => {
+      const missing = !!directory.missing;
+      if (!resourcesByPath.has(directory.path)) {
+        resourcesByPath.set(directory.path, {
+          id: directory.id,
+          path: directory.path,
+          name: directory.label,
+          enabled: directory.enabled,
+          missing,
+        });
+      }
+      const resource = resourcesByPath.get(directory.path)!;
+      resource.enabled ||= directory.enabled;
+      return { ...directory, missing };
+    });
+    byNotebookId[notebook.id] = { notebook, addDirs };
+  }
+  return { resources: [...resourcesByPath.values()], byNotebookId, validatedAt: Date.now() };
+}
+
+export const useAgentWorkspaceStore = create<AgentWorkspaceStoreState>((set, get) => {
+  const workspaceActions = createAgentWorkspaceSlice(
+    get,
+    (snapshot) => set((state) => ({
+      workspace: { ...state.workspace, ...projectAgentWorkspace(snapshot) },
+    })),
+    (workspace) => set((state) => ({
+      loadState: { ...state.loadState, workspace },
+    })),
+  );
+
+  return {
+    workspace: { resources: [], byNotebookId: {} },
+    loadState: { workspace: { status: 'idle' } },
+    workspaceActions,
+  };
+});
+
+/** Agent submissions wait for the backend-owned notebook access snapshot. */
+export async function ensureAgentWorkspaceReady(): Promise<void> {
+  if (useAgentWorkspaceStore.getState().loadState.workspace.status === 'ready') return;
+  await useAgentWorkspaceStore.getState().workspaceActions.loadInitial();
+  if (useAgentWorkspaceStore.getState().loadState.workspace.status === 'loading') {
+    await new Promise<void>((resolve) => {
+      const unsubscribe = useAgentWorkspaceStore.subscribe((state) => {
+        if (state.loadState.workspace.status !== 'loading') {
+          unsubscribe();
+          resolve();
+        }
+      });
+    });
+  }
+
+  const loadState = useAgentWorkspaceStore.getState().loadState.workspace;
+  if (loadState.status !== 'ready') {
+    throw new Error(loadState.error ?? 'Workspace data is not ready');
+  }
+}
diff --git a/app/flowix-web/features/agent/store/chat-stream.pi-mode.test.ts b/app/flowix-web/features/agent/store/chat-stream.pi-mode.test.ts
new file mode 100644
index 000000000..020bc4a63
--- /dev/null
+++ b/app/flowix-web/features/agent/store/chat-stream.pi-mode.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, expect, it, vi } from "vitest";
+
+const backend = vi.hoisted(() => ({ getFeatures: vi.fn(), clearLegacyCodeMode: vi.fn(), chatStream: vi.fn() }));
+vi.mock("@platform/tauri/client", () => ({ piModels: backend, agentAccess: {} }));
+vi.mock("./agent-client", () => ({ agentClient: backend }));
+vi.mock("@features/agent/runtime/workspace-snapshot", () => ({
+  normalizeWorkspaceSnapshot: () => null,
+  markConversationWorkspaceStarted: vi.fn(),
+}));
+vi.mock("@features/agent/runtime/conversation-workspace", () => ({ normalizeConversationWorkspaceState: () => null }));
+
+import { dispatchChatStream } from "./chat-stream";
+import { useAgentDataStore } from "./agent-data-store";
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  localStorage.clear();
+  useAgentDataStore.setState(useAgentDataStore.getInitialState(), true);
+  useAgentDataStore.setState({ legacyPreferencesMigrated: true });
+  backend.clearLegacyCodeMode.mockResolvedValue(undefined);
+  backend.chatStream.mockResolvedValue(undefined);
+});
+
+const input = {
+  threadId: "pi-thread", content: "hello", llmContent: "hello", runId: "run",
+  userPayload: { llmContent: "hello", systemReminderDirectory: "/notes" },
+  agentType: "pi" as const,
+};
+
+it("waits for startup migration on first send and uses the shared mode on subsequent turns", async () => {
+  let finish!: (features: { toolSearch: boolean; legacyCodeMode: boolean }) => void;
+  backend.getFeatures.mockReturnValue(new Promise((resolve) => { finish = resolve; }));
+  const firstSend = dispatchChatStream({ ...input, runtimeConfig: { pi: { codeMode: false } } });
+  expect(backend.chatStream).not.toHaveBeenCalled();
+  finish({ toolSearch: false, legacyCodeMode: true });
+  await firstSend;
+  expect(backend.chatStream).toHaveBeenLastCalledWith("pi-thread", expect.objectContaining({
+    runtimeConfig: expect.objectContaining({ pi: expect.objectContaining({ codeMode: true }) }),
+  }));
+  useAgentDataStore.getState().setUserPreference("pi", { mode: "writing" });
+  await dispatchChatStream({ ...input, runtimeConfig: { pi: { codeMode: true } } });
+  expect(backend.chatStream).toHaveBeenLastCalledWith("pi-thread", expect.objectContaining({
+    runtimeConfig: expect.objectContaining({ pi: expect.objectContaining({ codeMode: false }) }),
+  }));
+});
+
+it("rejects a send when migration fails instead of silently using another mode", async () => {
+  backend.getFeatures.mockRejectedValueOnce(new Error("settings unavailable"));
+  await expect(dispatchChatStream(input)).rejects.toThrow("settings unavailable");
+  expect(backend.chatStream).not.toHaveBeenCalled();
+  expect(backend.clearLegacyCodeMode).not.toHaveBeenCalled();
+});
diff --git a/app/flowix-web/features/agent/store/chat-stream.ts b/app/flowix-web/features/agent/store/chat-stream.ts
index f31c18eca..15110a652 100644
--- a/app/flowix-web/features/agent/store/chat-stream.ts
+++ b/app/flowix-web/features/agent/store/chat-stream.ts
@@ -1,14 +1,12 @@
+import { resolveAgentPreferenceRuntimeConfig } from "./agent-user-preferences";
 import type {
-  AgentCodexModel,
-  AgentCodexReasoningEffort,
-  AgentPermissionMode,
   AgentTypeKey,
   RuntimeConfig,
 } from "@/types/agent";
 import { buildAgentRuntimeConfig } from "@features/agent/runtime/agent-runtime-spec";
 import { agentClient } from "@features/agent/store/agent-client";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
-import { resolveNotebookAgentFiles } from "@/lib/agent-access-defaults";
+import { ensureAgentPreferencesReady, useAgentDataStore } from "@features/agent/store/agent-data-store";
+import { ensureAgentWorkspaceReady, useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
 import type { OutgoingUserPayload } from "@features/agent/store/user-message";
 import {
   markConversationWorkspaceStarted,
@@ -24,9 +22,6 @@ export interface DispatchChatStreamArgs {
   runId: string;
   userPayload: OutgoingUserPayload;
   agentType: AgentTypeKey;
-  permissionMode: AgentPermissionMode;
-  codexModel: AgentCodexModel;
-  codexReasoningEffort: AgentCodexReasoningEffort;
   /** Runtime config snapshot from the conversation instance. */
   runtimeConfig?: RuntimeConfig;
   imagePaths?: string[];
@@ -50,33 +45,33 @@ export async function dispatchChatStream({
   runId,
   userPayload,
   agentType,
-  permissionMode,
-  codexModel,
-  codexReasoningEffort,
   runtimeConfig: instanceRuntimeConfig,
   imagePaths,
   conversationTitle,
 }: DispatchChatStreamArgs): Promise<void> {
+  await ensureAgentPreferencesReady(agentType);
   // Thread Card 首次运行前会冻结 workspaceSnapshot，后续 turn 只使用快照。
-  // 没有快照的调用读取 notebook-local `.flowix/agent.json` add-dirs。
+  // 没有快照的调用读取 local.db notebook add-dirs。
   const workspaceSnapshot =
     normalizeConversationWorkspaceState(instanceRuntimeConfig)?.desired ??
     normalizeWorkspaceSnapshot(instanceRuntimeConfig?.workspaceSnapshot);
   const notebookId = instanceRuntimeConfig?.notebookId;
-  const accessState = useAgentAccessStore.getState();
+  if (!workspaceSnapshot && notebookId) await ensureAgentWorkspaceReady();
+  const userDefaults = useAgentDataStore.getState().agents;
   const defaultFiles = !workspaceSnapshot && notebookId
-    ? resolveNotebookAgentFiles(accessState.config, accessState.notebookConfigs, notebookId)
+    ? useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles(notebookId)
     : undefined;
+  const preferences = resolveAgentPreferenceRuntimeConfig(agentType, instanceRuntimeConfig);
   const runtimeConfig = buildAgentRuntimeConfig({
     typeKey: agentType,
     notebookPath: userPayload.systemReminderDirectory,
-    permissionMode,
-    codexModel,
-    codexReasoningEffort,
-    codexServiceTier: accessState.config.defaults?.runtime?.codex?.serviceTier,
-    instanceRuntimeConfig,
+    permissionMode: preferences.access?.sandbox ?? "danger-full-access",
+    codexModel: preferences.model?.key ?? "inherit",
+    codexReasoningEffort: preferences.reasoningEffort ?? "medium",
+    codexServiceTier: preferences.serviceTier,
+    instanceRuntimeConfig: preferences,
     defaultFiles,
-    piCodeMode: accessState.config.defaults?.runtime?.pi?.piCodeMode,
+    piCodeMode: userDefaults.pi.user.mode === "code",
     workspaceSnapshot,
   });
   if (instanceId) markConversationWorkspaceStarted(instanceId);
diff --git a/app/flowix-web/features/agent/store/codex-history-reconciliation.test.ts b/app/flowix-web/features/agent/store/codex-history-reconciliation.test.ts
index 494a5ac64..a58e8d68c 100644
--- a/app/flowix-web/features/agent/store/codex-history-reconciliation.test.ts
+++ b/app/flowix-web/features/agent/store/codex-history-reconciliation.test.ts
@@ -121,6 +121,19 @@ describe("Codex turn reconciliation", () => {
     expect(result.map((item) => item.id)).toEqual(["u", "command", "a", "next"]);
   });
 
+  it("reconciles a completed native command by its shared turn identity", () => {
+    const command = {
+      ...row("flowix:codex:command:t1", "user", "t1", "/compact"),
+      messageType: "codex-command" as const,
+      isCompleted: true,
+    };
+
+    const result = reconcileCodexHistory(
+      [command], [{ ...command }], complete, [command],
+    );
+    expect(result.map((item) => item.id)).toEqual(["flowix:codex:command:t1"]);
+  });
+
   it("reuses a large loaded prefix and the array for an equivalent latest-page snapshot", () => {
     const current: ChatMessage[] = [];
     for (let turn = 0; turn < 2000; turn += 1) {
diff --git a/app/flowix-web/features/agent/store/context-block.test.ts b/app/flowix-web/features/agent/store/context-block.test.ts
index 414d1d796..af93a600f 100644
--- a/app/flowix-web/features/agent/store/context-block.test.ts
+++ b/app/flowix-web/features/agent/store/context-block.test.ts
@@ -71,7 +71,7 @@ describe("appendFirstMessageContext", () => {
       "@features/agent/store/context-block"
     );
 
-    const result = appendFirstMessageContext("question", true, "note", "claude");
+    const result = appendFirstMessageContext("question", true, "note", "claudecode");
 
     expect(result).toContain("# flowix CLI");
   });
diff --git a/app/flowix-web/features/agent/store/context-block.ts b/app/flowix-web/features/agent/store/context-block.ts
index e237871d2..e7cb90486 100644
--- a/app/flowix-web/features/agent/store/context-block.ts
+++ b/app/flowix-web/features/agent/store/context-block.ts
@@ -49,17 +49,17 @@ const FLOWIX_CLI_PROMPT_BLOCK = [
   "# flowix CLI",
   "非交互笔记与插件产物 CLI，--json 取 JSON 输出。",
   "",
-  '只在显式触发时调:用户说"搜/列/改/删/新建笔记",或给了 8 位 ID / 笔记本名要求"看/改/删"。',
+  '只在显式触发时调:用户说"搜/列/改/删/新建笔记",或给了笔记地址 / 笔记本名要求"看/改/删"。',
   "如果上下文包含当前任务标签, 创建新笔记时必须在正文写入该 #标签。",
   "",
   "- `flowix notebooks` — list all notebooks.",
   "- `flowix list <notebook>` — list notes in a notebook.",
-  "- `flowix show <id>` — print a note to stdout.",
+  "- `flowix show <address>` — print a note to stdout.",
   "- `flowix search <query> [-b <notebook>] [-l N]` — full-text search.",
-  "- `flowix edit <id> --old <text> --new <text>` — exact-string replace (always `read` first).",
-  "- `flowix write <id>` (body from stdin) — overwrite a note.",
+  "- `flowix edit <address> --old <text> --new <text>` — exact-string replace (always `read` first).",
+  "- `flowix write <address>` (body from stdin) — overwrite a note.",
   "- `flowix create <notebook>` (body from stdin) — create a note.",
-  "- `flowix delete <id>` — delete a note.",
+  "- `flowix delete <address>` — delete a note.",
   "- `flowix plugin create mindmap --notebook <name|id|path> [--source-note <id|path>] --json` — read final Markmap Markdown from stdin and create a Flowix mindmap document.",
   "",
   "仅当用户明确要求生成/创建思维导图时调用 mindmap 工具。先自行整理最终 Markdown（恰好一个一级根标题，分支使用二/三级标题和无序列表），再传给 stdin；不要手工创建 `.plugin-output` 文件。成功后向用户返回 title 和 noteId。",
@@ -67,7 +67,7 @@ const FLOWIX_CLI_PROMPT_BLOCK = [
 
 const NATIVE_AGENTS_INSTRUCTION_AGENT_TYPES = new Set<AgentTypeKey>([
   "codex",
-  "deepseek-harness",
+  "dsh",
 ]);
 
 export function appendFirstMessageContext(
diff --git a/app/flowix-web/features/agent/store/conversation-run-index.test.ts b/app/flowix-web/features/agent/store/conversation-run-index.test.ts
index 7e39785c5..d97e3fd00 100644
--- a/app/flowix-web/features/agent/store/conversation-run-index.test.ts
+++ b/app/flowix-web/features/agent/store/conversation-run-index.test.ts
@@ -19,7 +19,7 @@ describe('conversation run index', () => {
             runId: 'run-1',
             status: 'running' as const,
             startedAt: 42,
-            agentType: 'deepseek-harness' as const,
+            agentType: 'dsh' as const,
             threadId: 'thread',
           },
         },
@@ -52,7 +52,7 @@ describe('conversation run index', () => {
             runId: 'run-1',
             status: 'running' as const,
             startedAt: 42,
-            agentType: 'deepseek-harness' as const,
+            agentType: 'dsh' as const,
             threadId: 'thread',
           },
         },
@@ -69,7 +69,7 @@ describe('conversation run index', () => {
         lastRun: {
           runId: 'run-1',
           status: 'completed' as const,
-          agentType: 'deepseek-harness' as const,
+          agentType: 'dsh' as const,
           startedAt: 42,
           endedAt: 50,
         },
diff --git a/app/flowix-web/features/agent/store/dsh-model-config-store.ts b/app/flowix-web/features/agent/store/dsh-model-config-store.ts
index 226d95830..caf994f0a 100644
--- a/app/flowix-web/features/agent/store/dsh-model-config-store.ts
+++ b/app/flowix-web/features/agent/store/dsh-model-config-store.ts
@@ -1,6 +1,7 @@
 import { create } from "zustand";
 import type { AgentConfig } from "@platform/tauri/client/agent";
 import { deepseekHarness } from "@platform/tauri/client";
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
 
 export interface DshModelConfigSnapshot {
   model: AgentConfig;
@@ -37,4 +38,5 @@ export function loadDshModelConfigs(): Promise<DshModelConfigSnapshot[]> {
 
 export function invalidateDshModelConfigs(): void {
   useDshModelConfigStore.getState().setConfigs(null);
+  useAgentDataStore.getState().invalidateModelCatalog("dsh");
 }
diff --git a/app/flowix-web/features/agent/store/follow-up-queue-slice.ts b/app/flowix-web/features/agent/store/follow-up-queue-slice.ts
index 11b109726..7d0d5ca4e 100644
--- a/app/flowix-web/features/agent/store/follow-up-queue-slice.ts
+++ b/app/flowix-web/features/agent/store/follow-up-queue-slice.ts
@@ -283,13 +283,13 @@ export function createFollowUpQueueSlice(set: SessionSet, get: SessionGet): Foll
       const pending = get().pendingSteeringMessages[threadId]?.find((message) => message.id === messageId);
       if (!pending?.clientUserMessageId || pending.deliveryMode !== "follow_up") return;
       const type = getAgentType(get().sessionMeta.threadTypes[threadId] ?? get().sessionMeta.activeAgentTypeKey);
-      if (type.key === "pi") {
+      if (type.id === "pi") {
         if (!canActOnQueuedMessage(pending, "pi")) return;
         await agentClient.promotePiFollowUpToSteer(threadId, pending.clientUserMessageId);
         updateSteeringMessage(threadId, messageId, { deliveryMode: "steer", deliveryStatus: "queued" });
         return;
       }
-      if (type.key !== "codex" || !canActOnQueuedMessage(pending, "codex")) return;
+      if (type.id !== "codex" || !canActOnQueuedMessage(pending, "codex")) return;
 
       // Lock immediately, including the queue refresh, so the UI can show
       // pending delivery and repeated clicks cannot submit the same item.
@@ -348,13 +348,13 @@ export function createFollowUpQueueSlice(set: SessionSet, get: SessionGet): Foll
       const pending = get().pendingSteeringMessages[threadId]?.find((message) => message.id === messageId);
       if (!pending?.clientUserMessageId) return;
       const type = getAgentType(get().sessionMeta.threadTypes[threadId] ?? get().sessionMeta.activeAgentTypeKey);
-      if (type.key === "pi") {
+      if (type.id === "pi") {
         if (!canActOnQueuedMessage(pending, "pi")) return;
         await agentClient.deletePiQueuedMessage(threadId, pending.clientUserMessageId);
         removeMessage(set, threadId, messageId);
         return;
       }
-      if (type.key !== "codex" || !canActOnQueuedMessage(pending, "codex")) return;
+      if (type.id !== "codex" || !canActOnQueuedMessage(pending, "codex")) return;
       if (pending.deliveryMode === "steer" && pending.deliveryStatus !== "cleanup_failed") return;
       const current = get().pendingSteeringMessages[threadId]?.find((message) => message.id === messageId);
       if (!current || !current.providerQueueId) return;
diff --git a/app/flowix-web/features/agent/store/global-agent-settings-sync.test.ts b/app/flowix-web/features/agent/store/global-agent-settings-sync.test.ts
deleted file mode 100644
index b413077ff..000000000
--- a/app/flowix-web/features/agent/store/global-agent-settings-sync.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { STORAGE_KEYS } from "@/lib/constants";
-import { DEFAULT_AGENT_SESSION_META } from "@features/agent/store/session-state";
-import { installGlobalAgentSettingsSync } from "@features/agent/store/global-agent-settings-sync";
-
-describe("installGlobalAgentSettingsSync", () => {
-  it("applies settings written by another Webview", () => {
-    const update = vi.fn();
-    installGlobalAgentSettingsSync(update);
-    window.dispatchEvent(
-      new StorageEvent("storage", {
-        key: STORAGE_KEYS.AGENT_SESSION,
-        newValue: JSON.stringify({
-          state: {
-            sessionMeta: {
-              settings: {
-                ...DEFAULT_AGENT_SESSION_META.settings,
-                agentPermissionMode: "read-only",
-              },
-            },
-          },
-        }),
-      }),
-    );
-    expect(update).toHaveBeenCalledTimes(1);
-    expect(
-      update.mock.calls[0][0](DEFAULT_AGENT_SESSION_META).settings
-        .agentPermissionMode,
-    ).toBe("read-only");
-  });
-});
diff --git a/app/flowix-web/features/agent/store/global-agent-settings-sync.ts b/app/flowix-web/features/agent/store/global-agent-settings-sync.ts
deleted file mode 100644
index dbe3ec5fa..000000000
--- a/app/flowix-web/features/agent/store/global-agent-settings-sync.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { STORAGE_KEYS } from "@/lib/constants";
-import type { AgentSessionMeta } from "@features/agent/store/session-state";
-
-export function installGlobalAgentSettingsSync(
-  updateMeta: (
-    updater: (meta: AgentSessionMeta) => AgentSessionMeta,
-  ) => void,
-): void {
-  if (typeof window === "undefined") return;
-  window.addEventListener("storage", (event) => {
-    if (event.key !== STORAGE_KEYS.AGENT_SESSION || !event.newValue) return;
-    try {
-      const settings = (
-        JSON.parse(event.newValue) as {
-          state?: { sessionMeta?: Pick<AgentSessionMeta, "settings"> };
-        }
-      ).state?.sessionMeta?.settings;
-      if (!settings) return;
-      updateMeta((meta) => ({
-        ...meta,
-        settings: { ...meta.settings, ...settings },
-      }));
-    } catch {
-      // Ignore malformed external writes. Rehydration falls back safely.
-    }
-  });
-}
diff --git a/app/flowix-web/features/agent/store/index.ts b/app/flowix-web/features/agent/store/index.ts
index bdbd49eac..c0029c8a9 100644
--- a/app/flowix-web/features/agent/store/index.ts
+++ b/app/flowix-web/features/agent/store/index.ts
@@ -1,4 +1,19 @@
-export { useAgentAccessStore } from '@features/agent/store/agent-access-store';
+export { ensureAgentPreferencesReady, modelPreferenceKey, useAgentDataStore } from '@features/agent/store/agent-data-store';
+export type {
+  AgentCatalogModel,
+  AgentCatalogSkill,
+  AgentCapabilities,
+  AgentModelCatalog,
+  AgentUserPreference,
+} from '@features/agent/store/agent-data-store';
+export { ensureAgentWorkspaceReady, useAgentWorkspaceStore } from '@features/agent/store/agent-workspace-store';
+export type {
+  AgentWorkspaceActions,
+  AgentWorkspaceLoadState,
+  AgentWorkspaceLoadStatus,
+  AgentWorkspaceNotebook,
+  AgentWorkspaceState,
+} from '@features/agent/store/agent-workspace-store';
 export { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
 export type {
   AgentConversationInstance,
diff --git a/app/flowix-web/features/agent/store/initial-runtime-config.test.ts b/app/flowix-web/features/agent/store/initial-runtime-config.test.ts
index 29098ffcb..64f12ca5e 100644
--- a/app/flowix-web/features/agent/store/initial-runtime-config.test.ts
+++ b/app/flowix-web/features/agent/store/initial-runtime-config.test.ts
@@ -1,144 +1,56 @@
-/**
- * 新模型下 buildInitialInstanceRuntimeConfig 只种子 model / access /
- * reasoningEffort 的全局默认 + 创建时所属 notebookId ── 文件区域 (cwd /
- * folders / notebooks) 在提交时由 agent-runtime-spec 实时推导, 不再烧录
- * 进 instance.files, 也无 _frozen / lockInstanceFileSeed / backfill 机制。
- *
- * 旧版本测的 cwd / files / frozen seed / backfill / defaults.files 权威
- * 快照等场景已不再适用, 这份测试只盯 model / access / reasoningEffort /
- * notebookId 四条。
- */
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useAgentDataStore } from "./agent-data-store";
+import { resolveAgentPreferenceRuntimeConfig } from "./agent-user-preferences";
+import { buildInitialInstanceRuntimeConfig } from "./initial-runtime-config";
 
-const memoStateMock = vi.hoisted(() => ({
-  selectedNotebook: null as null | { id: string; path: string } | unknown,
-}));
-
-const accessStateMock = vi.hoisted(() => ({
-  config: {
-    version: 1,
-    entries: [] as Array<unknown>,
-  } as {
-    version: number;
-    entries: Array<unknown>;
-    defaults?: {
-      runtime?: Record<
-        string,
-        {
-          model?: { key: string };
-          access?: { sandbox: string };
-          reasoningEffort?: string;
-        }
-      >;
-    };
-  },
-}));
-
+const memoState = vi.hoisted(() => ({ selectedNotebook: null as null | { id: string; path: string } }));
 vi.mock("@features/memo/store/note-store", () => ({
-  useNoteStore: {
-    getState: () => ({
-      selectedNotebook: memoStateMock.selectedNotebook,
-    }),
-  },
+  useNoteStore: { getState: () => memoState },
 }));
 
-vi.mock("@features/agent/store/agent-access-store", () => ({
-  useAgentAccessStore: {
-    getState: () => ({
-      config: accessStateMock.config,
-    }),
-  },
-}));
+beforeEach(() => {
+  memoState.selectedNotebook = null;
+  useAgentDataStore.setState(useAgentDataStore.getInitialState(), true);
+});
 
-describe("buildInitialInstanceRuntimeConfig — 仅种子 model/access/reasoning/notebookId", () => {
-  beforeEach(() => {
-    memoStateMock.selectedNotebook = null;
-    accessStateMock.config = { version: 1, entries: [] };
+describe("initial runtime from unified Agent preferences", () => {
+  it("creates a minimal snapshot until preferences or a notebook are selected", () => {
+    expect(buildInitialInstanceRuntimeConfig()).toEqual({ notebookId: undefined });
   });
 
-  it("默认返回无 model/access/reasoning/notebookId 的最小快照", async () => {
-    const { buildInitialInstanceRuntimeConfig } =
-      await import("@features/agent/store/initial-runtime-config");
-
-    const config = buildInitialInstanceRuntimeConfig();
-
-    expect(config.model).toBeUndefined();
-    expect(config.access).toBeUndefined();
-    expect(config.reasoningEffort).toBeUndefined();
-    expect(config.notebookId).toBeUndefined();
-    // cwd / files 不再由 helper 生成 ── 提交时实时推导。
-    expect(config.cwd).toBeUndefined();
-    expect(config.files).toBeUndefined();
+  it("uses the selected notebook, model-specific reasoning and permission", () => {
+    memoState.selectedNotebook = { id: "nb-1", path: "/notes/one" };
+    const store = useAgentDataStore.getState();
+    store.setUserPreference("codex", { model: { id: "gpt-6.1-sol" }, permission: "workspace-write" });
+    store.rememberModelReasoning("codex", { id: "gpt-6.1-sol" }, "low");
+    store.rememberModelReasoning("codex", { id: "other-model" }, "high");
+    expect(buildInitialInstanceRuntimeConfig()).toEqual({
+      notebookId: "nb-1", model: { key: "gpt-6.1-sol" }, access: { sandbox: "workspace-write" }, reasoningEffort: "low",
+    });
   });
 
-  it("selectedNotebook 已 hydrate 时, 快照其 id 为 notebookId", async () => {
-    memoStateMock.selectedNotebook = { id: "nb-1", path: "/Users/notes/开发" };
-    const { buildInitialInstanceRuntimeConfig } =
-      await import("@features/agent/store/initial-runtime-config");
-
-    const config = buildInitialInstanceRuntimeConfig();
-
-    expect(config.notebookId).toBe("nb-1");
+  it("isolates Agent preferences without copying the global Pi mode into conversations", () => {
+    const store = useAgentDataStore.getState();
+    store.setUserPreference("claudecode", { model: { id: "claude-model" } });
+    store.setUserPreference("pi", { mode: "code" });
+    expect(buildInitialInstanceRuntimeConfig("dsh").model).toBeUndefined();
+    expect(buildInitialInstanceRuntimeConfig("pi").pi).toBeUndefined();
+    expect(resolveAgentPreferenceRuntimeConfig("pi", { pi: { codeMode: false } }).pi).toBeUndefined();
+    expect(useAgentDataStore.getState().agents.pi.user.mode).toBe("code");
   });
 
-  it("defaults.runtime[agentType] 里的 model / access / reasoningEffort 种子进 instance", async () => {
-    accessStateMock.config = {
-      version: 1,
-      entries: [],
-      defaults: {
-        runtime: {
-          codex: {
-            model: { key: "gpt-5.5" },
-            access: { sandbox: "workspace-write" },
-            reasoningEffort: "high",
-          },
-        },
-      },
-    };
-    const { buildInitialInstanceRuntimeConfig } =
-      await import("@features/agent/store/initial-runtime-config");
-
-    const config = buildInitialInstanceRuntimeConfig("codex");
-
-    expect(config.model).toEqual({ key: "gpt-5.5" });
-    expect(config.access).toEqual({ sandbox: "workspace-write" });
-    expect(config.reasoningEffort).toBe("high");
-  });
-
-  it("未选 notebook 时 notebookId=undefined (提交侧 defaultFiles 回落当前笔记本)", async () => {
-    accessStateMock.config = {
-      version: 1,
-      entries: [],
-      defaults: {
-        runtime: {
-          codex: { model: { key: "gpt-5.5" } },
-        },
-      },
-    };
-    const { buildInitialInstanceRuntimeConfig } =
-      await import("@features/agent/store/initial-runtime-config");
-
-    const config = buildInitialInstanceRuntimeConfig("codex");
-
-    expect(config.notebookId).toBeUndefined();
-    expect(config.model).toEqual({ key: "gpt-5.5" });
+  it("preserves conversation overrides while applying the selected model's remembered effort", () => {
+    const store = useAgentDataStore.getState();
+    store.setUserPreference("codex", { model: { id: "global" }, permission: "read-only" });
+    store.rememberModelReasoning("codex", { id: "conversation", providerId: "provider" }, "low");
+    const runtime = resolveAgentPreferenceRuntimeConfig("codex", {
+      model: { key: "conversation", providerId: "provider" }, access: { sandbox: "workspace-write" }, cwd: "/frozen",
+    });
+    expect(runtime).toMatchObject({ model: { key: "conversation", providerId: "provider" }, access: { sandbox: "workspace-write" }, reasoningEffort: "low", cwd: "/frozen" });
+    expect(useAgentDataStore.getState().agents.codex.user.model?.id).toBe("global");
   });
 
-  it("其它 agent type 的默认不会污染当前 agent", async () => {
-    accessStateMock.config = {
-      version: 1,
-      entries: [],
-      defaults: {
-        runtime: {
-          claude: { model: { key: "claude-opus-4-8" } },
-        },
-      },
-    };
-    const { buildInitialInstanceRuntimeConfig } =
-      await import("@features/agent/store/initial-runtime-config");
-
-    const config = buildInitialInstanceRuntimeConfig("deepseek-harness");
-
-    expect(config.model).toBeUndefined();
+  it("does not read legacy runtime defaults outside migration", () => {
+    expect(buildInitialInstanceRuntimeConfig().model).toBeUndefined();
   });
-});
\ No newline at end of file
+});
diff --git a/app/flowix-web/features/agent/store/initial-runtime-config.ts b/app/flowix-web/features/agent/store/initial-runtime-config.ts
index 4f3efd83f..8bb9cfc3c 100644
--- a/app/flowix-web/features/agent/store/initial-runtime-config.ts
+++ b/app/flowix-web/features/agent/store/initial-runtime-config.ts
@@ -6,36 +6,19 @@
  * 避免插入阶段 store 尚未 hydrate 的 race，也保证后续 turn 不随全局配置变化。
  *
  * 这里只种子 model / access / reasoningEffort 的全局默认, 以及创建时所属
- * notebookId ── 提交时据此读取该笔记本 `.flowix/agent.json` 中的 add-dir
+ * notebookId ── 提交时据此读取该笔记本 `local.db` 中的 add-dir
  * 配置。未选笔记本时 notebookId 为 undefined，提交侧不会附加资料目录。
  */
 import type { AgentTypeKey, RuntimeConfig } from "@/types/agent";
 import { DEFAULT_AGENT_TYPE_KEY } from "@/lib/agent-types";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
+import { resolveAgentPreferenceRuntimeConfig } from "./agent-user-preferences";
 import { useNoteStore } from "@features/memo/store/note-store";
 
 export function buildInitialInstanceRuntimeConfig(
   agentType: AgentTypeKey = DEFAULT_AGENT_TYPE_KEY,
 ): RuntimeConfig {
-  const accessState = useAgentAccessStore.getState();
-  const notebookId = useNoteStore.getState().selectedNotebook?.id ?? undefined;
-  const defaultRuntime = accessState.config.defaults?.runtime?.[agentType];
-
   return {
-    ...(defaultRuntime?.model ? { model: defaultRuntime.model } : {}),
-    ...(defaultRuntime?.access ? { access: defaultRuntime.access } : {}),
-    ...(defaultRuntime?.reasoningEffort
-      ? { reasoningEffort: defaultRuntime.reasoningEffort }
-      : {}),
-    ...(defaultRuntime?.serviceTier
-      ? { serviceTier: defaultRuntime.serviceTier }
-      : {}),
-    ...(defaultRuntime?.mode
-      ? { deepseekHarness: { mode: defaultRuntime.mode } }
-      : {}),
-    ...(defaultRuntime?.piCodeMode !== undefined
-      ? { pi: { codeMode: defaultRuntime.piCodeMode } }
-      : {}),
-    notebookId,
+    ...resolveAgentPreferenceRuntimeConfig(agentType),
+    notebookId: useNoteStore.getState().selectedNotebook?.id ?? undefined,
   };
 }
diff --git a/app/flowix-web/features/agent/store/session-meta-slice.ts b/app/flowix-web/features/agent/store/session-meta-slice.ts
index f634dbbb6..f9ff2a43c 100644
--- a/app/flowix-web/features/agent/store/session-meta-slice.ts
+++ b/app/flowix-web/features/agent/store/session-meta-slice.ts
@@ -1,3 +1,4 @@
+import { useAgentDataStore } from "./agent-data-store";
 import type {
   AgentCodexModel,
   AgentCodexReasoningEffort,
@@ -76,16 +77,16 @@ export function createSessionMetaSlice(
           ...state.sessionMeta,
           threadLists: {
             ...state.sessionMeta.threadLists,
-            "deepseek-harness": list,
+            dsh: list,
           },
         },
       })),
     setActiveThreadId: (threadId) =>
-      setActiveThread("deepseek-harness", threadId, false),
+      setActiveThread("dsh", threadId, false),
     setActiveCodexThreadId: (threadId) =>
       setActiveThread("codex", threadId, false),
     setActiveClaudeThreadId: (threadId) =>
-      setActiveThread("claude", threadId, false),
+      setActiveThread("claudecode", threadId, false),
     setActiveAgentTypeKey: (typeKey) =>
       set((state) => ({
         sessionMeta: { ...state.sessionMeta, activeAgentTypeKey: typeKey },
@@ -105,31 +106,12 @@ export function createSessionMetaSlice(
       }));
     },
     setAgentPermissionMode: (mode) =>
-      set((state) => ({
-        sessionMeta: {
-          ...state.sessionMeta,
-          settings: {
-            ...state.sessionMeta.settings,
-            agentPermissionMode: mode,
-          },
-        },
-      })),
+      useAgentDataStore.getState().setUserPreference("codex", { permission: mode }),
     setAgentCodexModel: (model) =>
-      set((state) => ({
-        sessionMeta: {
-          ...state.sessionMeta,
-          settings: { ...state.sessionMeta.settings, agentCodexModel: model },
-        },
-      })),
-    setAgentCodexReasoningEffort: (effort) =>
-      set((state) => ({
-        sessionMeta: {
-          ...state.sessionMeta,
-          settings: {
-            ...state.sessionMeta.settings,
-            agentCodexReasoningEffort: effort,
-          },
-        },
-      })),
+      useAgentDataStore.getState().setUserPreference("codex", { model: { id: model } }),
+    setAgentCodexReasoningEffort: (effort) => {
+      const store = useAgentDataStore.getState();
+      store.rememberModelReasoning("codex", store.agents.codex.user.model, effort);
+    },
   };
 }
diff --git a/app/flowix-web/features/agent/store/session-persistence.ts b/app/flowix-web/features/agent/store/session-persistence.ts
index 955ad1eae..f72037c07 100644
--- a/app/flowix-web/features/agent/store/session-persistence.ts
+++ b/app/flowix-web/features/agent/store/session-persistence.ts
@@ -1,8 +1,10 @@
 import {
   DEFAULT_AGENT_TYPE_KEY,
   isAgentTypeSelectable,
+  normalizeAgentId,
   normalizeAgentTypeKey,
 } from '@/lib/agent-types';
+import type { AgentId } from '@/types/agent';
 import { normalizeCodexPermissionMode } from '@features/agent/runtime/agent-runtime-spec';
 import {
   DEFAULT_AGENT_SESSION_META,
@@ -28,8 +30,31 @@ export function rehydrateSessionMeta(persisted: unknown): AgentSessionMeta {
     ? typeKey
     : DEFAULT_AGENT_TYPE_KEY;
   base.currentThreadTitles ??= {};
+  base.threadTypes = Object.fromEntries(
+    Object.entries(base.threadTypes ?? {}).flatMap(([threadId, legacyId]) => {
+      const id = normalizeAgentId(legacyId);
+      return id ? [[threadId, id]] : [];
+    }),
+  );
+  base.activeThreadIds = normalizeAgentKeyedRecord(base.activeThreadIds);
+  base.threadLists = normalizeAgentKeyedRecord(base.threadLists);
   base.settings.agentPermissionMode = normalizeCodexPermissionMode(
     base.settings.agentPermissionMode,
   );
   return base;
 }
+
+function normalizeAgentKeyedRecord<T>(value: unknown): Partial<Record<AgentId, T>> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const source = value as Record<string, T>;
+  const result: Partial<Record<AgentId, T>> = {};
+  for (const [key, item] of Object.entries(source)) {
+    const id = normalizeAgentId(key);
+    if (id && key === id) result[id] = item;
+  }
+  for (const [key, item] of Object.entries(source)) {
+    const id = normalizeAgentId(key);
+    if (id && result[id] === undefined) result[id] = item;
+  }
+  return result;
+}
diff --git a/app/flowix-web/features/agent/store/session-reducer/reduce-projection.test.ts b/app/flowix-web/features/agent/store/session-reducer/reduce-projection.test.ts
index 723d95617..2dcfd3798 100644
--- a/app/flowix-web/features/agent/store/session-reducer/reduce-projection.test.ts
+++ b/app/flowix-web/features/agent/store/session-reducer/reduce-projection.test.ts
@@ -5,6 +5,7 @@ import {
   reduceProjection,
 } from "@features/agent/store/session-reducer";
 import { mergeLiveMessagesIntoRenderableMessages } from "@features/agent/store/thread-history";
+import { codexFallbackItemMessageId } from "@features/agent/events/codex-message-identity";
 
 function event<K extends AgentEvent["kind"]>(
   kind: K,
@@ -15,7 +16,7 @@ function event<K extends AgentEvent["kind"]>(
 
 const userMessage = (text: string, id: string): AgentEvent =>
   event("user_message", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId: "r1",
     timestamp: 1000,
@@ -28,7 +29,7 @@ const userMessage = (text: string, id: string): AgentEvent =>
 
 const textDelta = (text: string, messageId?: string): AgentEvent =>
   event("text_delta", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId: "r1",
     timestamp: 2000,
@@ -43,7 +44,7 @@ const textDelta = (text: string, messageId?: string): AgentEvent =>
 
 const reasoningDelta = (text: string): AgentEvent =>
   event("reasoning_delta", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId: "r1",
     timestamp: 3000,
@@ -58,7 +59,7 @@ const reasoningDelta = (text: string): AgentEvent =>
 
 const streamStart = (runId: string): AgentEvent =>
   event("stream_start", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId,
     timestamp: 0,
@@ -71,7 +72,7 @@ const streamEnd = (
   durationMs?: number,
 ): AgentEvent =>
   event("stream_end", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId,
     timestamp: 9000,
@@ -81,7 +82,7 @@ const streamEnd = (
 
 const errorEvent = (message: string): AgentEvent =>
   event("error", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId: "r1",
     timestamp: 9500,
@@ -94,7 +95,7 @@ const toolCall = (
   reasoningBoundary = false,
 ): AgentEvent =>
   event("tool_call", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId: "r1",
     timestamp: 4000,
@@ -111,7 +112,7 @@ const toolCall = (
 
 const toolResult = (id: string, name: string): AgentEvent =>
   event("tool_result", {
-    agentType: "deepseek-harness",
+    agentType: "dsh",
     threadId: "t1",
     runId: "r1",
     timestamp: 5000,
@@ -253,6 +254,105 @@ describe("reduceProjection / text streaming lifecycle", () => {
     expect(p.messages.find((message) => message.id === "item-1")?.content).toBe("Hello");
   });
 
+  it("adopts a stable turn-scoped fallback ID when a completed Codex item has no provider ID", () => {
+    let p = emptyProjection();
+    p = reduceProjection(p, event("text_delta", {
+      agentType: "codex", threadId: "t1", runId: "run-1", timestamp: 1,
+      text: "same reply", codexTurnId: "turn-fallback",
+      contentMode: "delta", messagePhase: "updated",
+    }));
+    p = reduceProjection(p, event("text_delta", {
+      agentType: "codex", threadId: "t1", runId: "run-1", timestamp: 2,
+      text: "same reply", codexTurnId: "turn-fallback",
+      contentMode: "snapshot", messagePhase: "completed",
+    }));
+
+    const expected = codexFallbackItemMessageId(
+      "turn-fallback", "assistant", "same reply", 0,
+    );
+    expect(p.messages).toHaveLength(1);
+    expect(p.messages[0]).toMatchObject({
+      id: expected,
+      messageId: expected,
+      content: "same reply",
+      isCompleted: true,
+    });
+    expect(expected).toBe("flowix:codex:item:turn-fallback:assistant:c9c3d78b64eaec57:0");
+    expect(codexFallbackItemMessageId("t", "assistant", "你好🙂", 0)).toBe(
+      "flowix:codex:item:t:assistant:71b13a3934f0304d:0",
+    );
+  });
+
+  it("keeps distinct identical Codex items when the backend supplies their occurrence IDs", () => {
+    let p = emptyProjection();
+    for (const occurrence of [0, 1]) {
+      const messageId = codexFallbackItemMessageId(
+        "turn-repeat", "assistant", "same reply", occurrence,
+      );
+      const completed = event("text_delta", {
+        agentType: "codex", threadId: "t1", runId: "run-1", timestamp: occurrence + 1,
+        text: "same reply", messageId, codexTurnId: "turn-repeat",
+        contentMode: "snapshot", messagePhase: "completed",
+      });
+      p = reduceProjection(p, completed);
+      // The terminal turn snapshot can repeat the same identity; it remains an
+      // idempotent update while an equal-text item with another occurrence id
+      // stays a separate history row.
+      p = reduceProjection(p, completed);
+    }
+
+    expect(p.messages.filter((message) => message.role === "assistant")).toEqual([
+      expect.objectContaining({
+        id: codexFallbackItemMessageId("turn-repeat", "assistant", "same reply", 0),
+        content: "same reply",
+      }),
+      expect.objectContaining({
+        id: codexFallbackItemMessageId("turn-repeat", "assistant", "same reply", 1),
+        content: "same reply",
+      }),
+    ]);
+  });
+
+  it("keeps repeated identical idless Codex reasoning snapshots aligned with history", () => {
+    let p = emptyProjection();
+    for (const occurrence of [0, 1]) {
+      p = reduceProjection(p, event("reasoning_delta", {
+        agentType: "codex", threadId: "t1", runId: "run-1", timestamp: occurrence + 1,
+        text: "same thought", codexTurnId: "turn-reasoning",
+        contentMode: "snapshot", messagePhase: "completed",
+        sourceSequence: occurrence + 1,
+      }));
+    }
+
+    expect(p.messages.filter((message) => message.role === "reasoning")).toEqual([
+      expect.objectContaining({
+        id: codexFallbackItemMessageId("turn-reasoning", "reasoning", "same thought", 0),
+        content: "same thought",
+      }),
+      expect.objectContaining({
+        id: codexFallbackItemMessageId("turn-reasoning", "reasoning", "same thought", 1),
+        content: "same thought",
+      }),
+    ]);
+  });
+
+  it("assigns distinct matching fallbacks to repeated Codex user items without provider IDs", () => {
+    let p = emptyProjection();
+    const userEvent = (timestamp: number): AgentEvent => event("user_message", {
+      agentType: "codex", threadId: "t1", runId: "run-1", timestamp,
+      id: "flowix:codex:missing-user-item",
+      messageId: "flowix:codex:missing-user-item", text: "repeat",
+      codexTurnId: "turn-users", messagePhase: "completed", contentMode: "snapshot",
+    });
+    p = reduceProjection(p, userEvent(1));
+    p = reduceProjection(p, userEvent(2));
+
+    expect(p.messages.map((message) => message.id)).toEqual([
+      codexFallbackItemMessageId("turn-users", "user", "repeat", 0),
+      codexFallbackItemMessageId("turn-users", "user", "repeat", 1),
+    ]);
+  });
+
   it("stream_start → text_delta → text_delta appends content", () => {
     let p = emptyProjection();
     p = reduceProjection(p, streamStart("r1"));
@@ -277,23 +377,23 @@ describe("reduceProjection / text streaming lifecycle", () => {
     p = reduceProjection(
       p,
       event("user_message", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r2",
         timestamp: 2500,
         text: "second question",
-        id: "msg:deepseek-harness:r2:user:user-r2",
+        id: "msg:dsh:r2:user:user-r2",
       }),
     );
     p = reduceProjection(
       p,
       event("text_delta", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r2",
         timestamp: 2600,
         text: "second",
-        messageId: "msg:deepseek-harness:r2:assistant:stream",
+        messageId: "msg:dsh:r2:assistant:stream",
         messagePhase: "updated",
         contentMode: "delta",
       }),
@@ -338,7 +438,7 @@ describe("reduceProjection / text streaming lifecycle", () => {
     p = reduceProjection(
       p,
       event("reasoning_delta", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r1",
         timestamp: 6000,
@@ -360,13 +460,14 @@ describe("reduceProjection / text streaming lifecycle", () => {
     });
   });
 
-  it("stream_end clears an unfinished reasoning draft and pending state", () => {
+  it("stream_end retains and seals an unfinished reasoning draft", () => {
     let p = emptyProjection();
     p = reduceProjection(p, streamStart("r1"));
     p = reduceProjection(p, reasoningDelta("only thinking"));
     p = reduceProjection(p, streamEnd("r1"));
 
-    expect(p.messages).toHaveLength(0);
+    expect(p.messages).toHaveLength(1);
+    expect(p.messages[0].isCompleted).toBe(true);
     expect(p.runs.isLoading).toBe(false);
     expect(p.runs.activeRunId).toBeNull();
     expect(p.runs.lastRun?.status).toBe("completed");
@@ -377,16 +478,34 @@ describe("reduceProjection / text streaming lifecycle", () => {
   it.each([
     ["user stop", "user_stopped"],
     ["provider completion", null],
-  ] as const)("clears assistant drafts on %s", (_label, reason) => {
+  ] as const)("retains and seals assistant drafts on %s", (_label, reason) => {
     let p = emptyProjection();
     p = reduceProjection(p, streamStart("r1"));
     p = reduceProjection(p, textDelta("unfinished answer"));
     p = reduceProjection(p, streamEnd("r1", reason));
 
-    expect(p.messages).toHaveLength(0);
+    expect(p.messages).toHaveLength(1);
+    expect(p.messages[0].isCompleted).toBe(true);
     expect(p.pending.assistantId).toBeNull();
   });
 
+  it("does not delete a forced-stop Pi answer when the next run fails", () => {
+    let p = emptyProjection();
+    p = reduceProjection(p, { ...streamStart("r1"), agentType: "pi" });
+    // Multiple native blocks can exist without a committed message_end.
+    p = reduceProjection(p, { ...textDelta("first block"), agentType: "pi", messageId: undefined, sourceSubsequence: 0 });
+    p = reduceProjection(p, { ...textDelta("last block"), agentType: "pi", messageId: undefined, sourceSubsequence: 1 });
+    p = reduceProjection(p, { ...streamEnd("r1", "user_stopped"), agentType: "pi" });
+    p = reduceProjection(p, { ...streamStart("r2"), agentType: "pi" });
+    p = reduceProjection(p, { ...textDelta("failed draft", "block-2"), agentType: "pi", runId: "r2" });
+    p = reduceProjection(p, { ...errorEvent("startup failed"), agentType: "pi", runId: "r2" });
+    expect(p.messages.filter(row => row.role === "assistant").map(row => row.content))
+      .toEqual(["first block", "last block", "startup failed"]);
+    expect(p.messages.some(row => row.content === "failed draft")).toBe(false);
+    expect(p.messages.filter(row => row.role === "assistant").every(row => row.isCompleted)).toBe(true);
+    expect(p.messages.some(row => row.content === "startup failed")).toBe(true);
+  });
+
   it("clears unfinished output on provider error and retains the terminal error row", () => {
     let p = emptyProjection();
     p = reduceProjection(p, streamStart("r1"));
@@ -439,7 +558,7 @@ describe("reduceProjection / text streaming lifecycle", () => {
     p = reduceProjection(p, streamStart("r1"));
     p = reduceProjection(p, textDelta("answer"));
     p = reduceProjection(p, event("final_message", {
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "r1",
       timestamp: 8000,
@@ -475,11 +594,11 @@ describe("reduceProjection / text streaming lifecycle", () => {
   it("collapses duplicate stdout/process-exit errors for one run", () => {
     let p = emptyProjection();
     const base = {
-      agentType: "claude" as const,
+      agentType: "claudecode" as const,
       threadId: "t1",
       runId: "r1",
       timestamp: 9500,
-      messageId: "msg:claude:r1:error:error",
+      messageId: "msg:claudecode:r1:error:error",
     };
     p = reduceProjection(p, {
       kind: "error",
@@ -510,17 +629,17 @@ describe("reduceProjection / text streaming lifecycle", () => {
     p = reduceProjection(
       p,
       event("error", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r1",
         timestamp: 9500,
-        messageId: "msg:deepseek-harness:r1:error:error",
+        messageId: "msg:dsh:r1:error:error",
         message: "Request timed out.",
       }),
     );
 
     expect(p.messages[p.messages.length - 1]).toMatchObject({
-      id: "msg:deepseek-harness:r1:error:error",
+      id: "msg:dsh:r1:error:error",
       content: "Request timed out.",
       notice: "deepseek-harness-reconnect-failed",
     });
@@ -531,11 +650,11 @@ describe("reduceProjection / text streaming lifecycle", () => {
     p = reduceProjection(
       p,
       event("error", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r1",
         timestamp: 9600,
-        messageId: "msg:deepseek-harness:r1:error:quota",
+        messageId: "msg:dsh:r1:error:quota",
         message: "Token Plan exhausted",
         errorDetails: {
           category: "quota_exhausted",
@@ -559,7 +678,7 @@ describe("reduceProjection / tool call cycle", () => {
   it("keeps harness assistant segments separate while the run is still streaming", () => {
     const harnessText = (text: string, messageId: string) =>
       event("text_delta", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r1",
         timestamp: 2000,
@@ -569,24 +688,24 @@ describe("reduceProjection / tool call cycle", () => {
         contentMode: "delta",
       });
     const harnessToolCall = event("tool_call", {
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "r1",
       timestamp: 3000,
-      toolCallId: "msg:deepseek-harness:r1:tool-call:c1",
+      toolCallId: "msg:dsh:r1:tool-call:c1",
       name: "read",
       input: { file_path: "README.md" },
-      messageId: "msg:deepseek-harness:r1:tool:c1",
+      messageId: "msg:dsh:r1:tool:c1",
     });
     const harnessToolResult = event("tool_result", {
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "r1",
       timestamp: 4000,
-      toolCallId: "msg:deepseek-harness:r1:tool-call:c1",
+      toolCallId: "msg:dsh:r1:tool-call:c1",
       name: "read",
       result: "ok",
-      messageId: "msg:deepseek-harness:r1:tool:c1",
+      messageId: "msg:dsh:r1:tool:c1",
     });
     let p = emptyProjection();
     p = reduceProjection(p, streamStart("r1"));
@@ -594,7 +713,7 @@ describe("reduceProjection / tool call cycle", () => {
       p,
       harnessText(
         "before tool",
-        "msg:deepseek-harness:r1:assistant:assistant-stream-0",
+        "msg:dsh:r1:assistant:assistant-stream-0",
       ),
     );
     p = reduceProjection(p, harnessToolCall);
@@ -603,7 +722,7 @@ describe("reduceProjection / tool call cycle", () => {
       p,
       harnessText(
         "after tool",
-        "msg:deepseek-harness:r1:assistant:assistant-stream-1",
+        "msg:dsh:r1:assistant:assistant-stream-1",
       ),
     );
 
@@ -615,7 +734,7 @@ describe("reduceProjection / tool call cycle", () => {
       ["assistant", "after tool"],
     ]);
     expect(p.pending.assistantId).toBe(
-      "msg:deepseek-harness:r1:assistant:assistant-stream-1",
+      "msg:dsh:r1:assistant:assistant-stream-1",
     );
   });
 
@@ -695,7 +814,7 @@ describe("reduceProjection / DSH command operations", () => {
     p = reduceProjection(
       p,
       event("dsh_command", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "command-run-1",
         timestamp: 1000,
@@ -721,7 +840,7 @@ describe("reduceProjection / DSH command operations", () => {
     p = reduceProjection(
       p,
       event("dsh_command", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "command-run-1",
         timestamp: 2000,
@@ -750,7 +869,7 @@ describe("reduceProjection / DSH command operations", () => {
     p = reduceProjection(
       p,
       event("dsh_command", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "command-run-1",
         timestamp: 1000,
@@ -784,7 +903,7 @@ describe("reduceProjection / session_resolved is a no-op", () => {
     const after = reduceProjection(
       p,
       event("session_resolved", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "test-run",
         timestamp: 9999,
@@ -818,7 +937,7 @@ describe("reduceProjection / Codex command operations", () => {
 
     expect(p.messages).toMatchObject([
       {
-        id: "codex-command:live:codex-command-1",
+        id: "flowix:codex:command:pending:codex-command-1",
         role: "user",
         messageType: "codex-command",
         content: "/goal set ship it",
@@ -853,10 +972,11 @@ describe("reduceProjection / Codex command operations", () => {
     );
 
     expect(p.messages[0]).toMatchObject({
-      id: "codex-command:live:codex-command-1",
+      id: "flowix:codex:command:turn-goal-1",
       codexTurnId: "turn-goal-1",
       isCompleted: true,
     });
+    expect(p.messages).toHaveLength(1);
   });
 
   it.each(["error", "cancelled"] as const)(
@@ -882,7 +1002,7 @@ describe("reduceProjection / usage accumulates into runs", () => {
     p = reduceProjection(
       p,
       event("usage", {
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         threadId: "t1",
         runId: "r1",
         timestamp: 8000,
diff --git a/app/flowix-web/features/agent/store/session-reducer/reduce-projection.ts b/app/flowix-web/features/agent/store/session-reducer/reduce-projection.ts
index 3348e26d3..7a685bbcb 100644
--- a/app/flowix-web/features/agent/store/session-reducer/reduce-projection.ts
+++ b/app/flowix-web/features/agent/store/session-reducer/reduce-projection.ts
@@ -1,6 +1,12 @@
 import type { ChatMessage } from "@/types";
 import type { AgentEvent } from "@/types/agent";
 import { completedRunUserMessageId } from "@features/agent/events/message-identity";
+import {
+  CODEX_MISSING_USER_ITEM_ID,
+  codexCommandMessageId,
+  codexFallbackItemMessageId,
+  codexPendingCommandMessageId,
+} from "@features/agent/events/codex-message-identity";
 import {
   applyErrorChunk,
   applyReasoningChunk,
@@ -91,9 +97,16 @@ function applyUserMessageToProjection(
 
   const isOptimisticPiUser = event.agentType === "pi" &&
     event.id === completedRunUserMessageId(event.agentType, event.runId);
+  const codexUserHasSyntheticId = event.agentType === "codex" &&
+    event.id === CODEX_MISSING_USER_ITEM_ID && !!event.codexTurnId;
+  const codexUserId = codexUserHasSyntheticId
+    ? codexFallbackIdForCompletedItem(p, event, "user", event.text, null)
+    : undefined;
+  const messageId = codexUserId ?? event.id;
   const next = applyUserMessageChunk(p, event.text, {
-    id: event.id,
-    nativeMessageId: !isOptimisticPiUser && (event.agentType === "pi" || event.agentType === "codex")
+    id: messageId,
+    nativeMessageId: !isOptimisticPiUser && !codexUserHasSyntheticId &&
+      (event.agentType === "pi" || event.agentType === "codex")
       ? event.id : undefined,
     isOptimistic: isOptimisticPiUser,
     messageType: event.messageType,
@@ -117,6 +130,37 @@ function applyUserMessageToProjection(
   };
 }
 
+function codexFallbackIdForCompletedItem(
+  p: ThreadProjection,
+  event: AgentEvent,
+  role: "user" | "assistant" | "reasoning",
+  content: string,
+  pendingId: string | null,
+): string | undefined {
+  if (
+    event.agentType !== "codex" ||
+    (event.messageId && event.messageId !== CODEX_MISSING_USER_ITEM_ID) ||
+    event.contentMode !== "snapshot" || event.messagePhase !== "completed" ||
+    !event.codexTurnId
+  ) return undefined;
+
+  const prefix = `flowix:codex:item:${event.codexTurnId}:${role}:`;
+  const matching = p.messages.filter((message) =>
+    message.id !== pendingId &&
+    message.codexTurnId === event.codexTurnId &&
+    message.role === role &&
+    message.content === content &&
+    message.id.startsWith(prefix),
+  );
+  const pendingExists = pendingId != null && p.messages.some((message) => message.id === pendingId);
+  // Codex can replay the final assistant item in its terminal turn snapshot.
+  // Reasoning items have no such replay path and must retain their occurrence.
+  if (role === "assistant" && !pendingExists && matching.length > 0) {
+    return matching[matching.length - 1].id;
+  }
+  return codexFallbackItemMessageId(event.codexTurnId, role, content, matching.length);
+}
+
 function isLiveDshPlanPrompt(p: ThreadProjection, text: string): boolean {
   const prompt = text.split("\n<## CONTEXT PROMPT ##>", 1)[0].trim();
   if (!prompt) return false;
@@ -153,7 +197,10 @@ function applyTextDeltaToProjection(
   }
   const next = applyTextChunk(p, event.text, {
     id: event.agentType === "pi" && event.messageId && event.sourceSubsequence !== undefined
-      ? `${event.messageId}:block:${event.sourceSubsequence}` : event.messageId,
+      ? `${event.messageId}:block:${event.sourceSubsequence}`
+      : event.messageId ?? codexFallbackIdForCompletedItem(
+          p, event, "assistant", event.text, p.pending.assistantId,
+        ),
     nativeMessageId: event.agentType === "pi" || event.agentType === "codex" ? event.messageId : undefined,
     blockIndex: event.agentType === "pi" ? event.sourceSubsequence : undefined,
     phase: event.messagePhase,
@@ -183,7 +230,10 @@ function applyReasoningDeltaToProjection(
 ): ThreadProjection {
   const next = applyReasoningChunk(p, event.text, {
     id: event.agentType === "pi" && event.messageId && event.sourceSubsequence !== undefined
-      ? `${event.messageId}:block:${event.sourceSubsequence}` : event.messageId,
+      ? `${event.messageId}:block:${event.sourceSubsequence}`
+      : event.messageId ?? codexFallbackIdForCompletedItem(
+          p, event, "reasoning", event.text, p.pending.reasoningId,
+        ),
     nativeMessageId: event.agentType === "pi" || event.agentType === "codex" ? event.messageId : undefined,
     blockIndex: event.agentType === "pi" ? event.sourceSubsequence : undefined,
     phase: event.messagePhase,
@@ -233,7 +283,9 @@ function applyFinalMessageToProjection(
 ): ThreadProjection {
   // final_message 形态与 text_delta 一致, 仅 contentMode="snapshot" 且 phase="completed".
   const next = applyTextChunk(p, event.text, {
-    id: event.messageId,
+    id: event.messageId ?? codexFallbackIdForCompletedItem(
+      p, event, "assistant", event.text, p.pending.assistantId,
+    ),
     nativeMessageId: event.agentType === "codex" ? event.messageId : undefined,
     phase: event.messagePhase,
     contentMode: event.contentMode,
@@ -380,8 +432,13 @@ function applyCodexCommandToProjection(
   p: ThreadProjection,
   event: AgentEvent & { kind: "codex_command" },
 ): ThreadProjection {
-  const messageId = `codex-command:live:${event.id}`;
-  const existingIndex = p.messages.findIndex((message) => message.id === messageId);
+  const provisionalId = codexPendingCommandMessageId(event.id);
+  const messageId = event.codexTurnId
+    ? codexCommandMessageId(event.codexTurnId)
+    : provisionalId;
+  const existingIndex = p.messages.findIndex((message) =>
+    message.id === messageId || message.id === provisionalId,
+  );
   const message = {
     id: messageId,
     role: "user" as const,
@@ -447,19 +504,16 @@ function applyStreamEndToProjection(
 ): ThreadProjection {
   const runsNext = applyRunEndedCore(p.runs, event);
   if (runsNext === p.runs) return p;
-  // run 结束时把仍 loading 的 tool 行收尾为 isLoading=false (避免中断 tool 永久转圈)，
-  // 并完成仍 pending 的 reasoning 行。助手文本即使没有单独的 final 事件也要保留。
-  // 仅在最后一个 run 结束时执行，避免误改并发 run 的消息。
+  // Once no run remains active, retained output is terminal even if the
+  // provider never delivered its final snapshot (for example a forced Pi
+  // stop). Seal every draft block so a later run's error cannot delete it.
   const terminalMessages = !runsNext.isLoading
-    ? closeLoadingToolRows(
-        p.pending.reasoningId
-          ? p.messages.map((message) =>
-              message.id === p.pending.reasoningId && message.role === "reasoning"
-                ? { ...message, isCompleted: true }
-                : message,
-            )
-          : p.messages,
-      )
+    ? closeLoadingToolRows(p.messages.map((message) =>
+        (message.role === "assistant" || message.role === "reasoning") &&
+          message.isCompleted !== true
+          ? { ...message, isCompleted: true }
+          : message,
+      ))
     : p.messages;
   const messagesWithDuration =
     !runsNext.isLoading &&
@@ -543,7 +597,7 @@ function clearUnfinishedAssistantDrafts(messages: ChatMessage[]): ChatMessage[]
 function shouldUseDeepSeekHarnessReconnectNotice(
   event: AgentEvent & { kind: "error" },
 ): boolean {
-  if (event.agentType !== "deepseek-harness") return false;
+  if (event.agentType !== "dsh") return false;
 
   // A classified provider error has its own user-facing guidance. It must not
   // be presented as a transport/reconnect failure.
diff --git a/app/flowix-web/features/agent/store/session-state.ts b/app/flowix-web/features/agent/store/session-state.ts
index 70a440372..f13759f1f 100644
--- a/app/flowix-web/features/agent/store/session-state.ts
+++ b/app/flowix-web/features/agent/store/session-state.ts
@@ -22,6 +22,7 @@ export interface AgentSessionMeta {
   currentThreadTitles: Partial<Record<string, string | undefined>>;
   externalSessionResolutions: Record<string, string>;
   lastRunningRunsReconciledAt: number | null;
+  /** Legacy migration input; active preferences live in Agent Data Store. */
   settings: {
     agentPermissionMode: AgentPermissionMode;
     agentCodexModel: AgentCodexModel;
diff --git a/app/flowix-web/features/agent/store/thread-history-slice.test.ts b/app/flowix-web/features/agent/store/thread-history-slice.test.ts
index 7e1bcdac4..93c9b918d 100644
--- a/app/flowix-web/features/agent/store/thread-history-slice.test.ts
+++ b/app/flowix-web/features/agent/store/thread-history-slice.test.ts
@@ -2,7 +2,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { ChatMessage } from "@/types";
 import { attachHistoryCursor, HistoryChangedError, type ThreadHistoryPage } from "./agent-history-adapters";
 import type { ProjectionSlice } from "./projection-slice";
-import { emptyProjection } from "./session-reducer";
+import { emptyProjection, reduceProjection } from "./session-reducer";
 import { createThreadHistorySlice, type ThreadHistorySlice } from "./thread-history-slice";
 import { DEFAULT_AGENT_SESSION_META } from "./session-state";
 
@@ -31,7 +31,7 @@ function store(messages: ChatMessage[]) {
   let state: Context;
   state = {
     ...createThreadHistorySlice(() => state),
-    sessionMeta: { ...DEFAULT_AGENT_SESSION_META, threadTypes: { thread: "claude" }, externalSessionResolutions: { thread: "native-a" } },
+    sessionMeta: { ...DEFAULT_AGENT_SESSION_META, threadTypes: { thread: "claudecode" }, externalSessionResolutions: { thread: "native-a" } },
     threadProjections: { thread: { ...emptyProjection(), messages } },
     threadEpochs: {}, threadTombstones: {}, threadMutationGuards: {}, codexLiveTurns: {},
     threadRunSignatures: {}, latestCompletedRunIds: {}, readThroughRunIds: {}, runStateVersion: 0,
@@ -54,6 +54,32 @@ function store(messages: ChatMessage[]) {
 describe("Pi history request fences", () => {
   beforeEach(() => { adapter.getInitialHistory.mockReset(); adapter.getFullHistory.mockReset(); adapter.getPage.mockReset(); });
 
+  it("restores the first turn and second-turn prompt while the second turn keeps streaming after refresh", async () => {
+    const get = store([]);
+    const pending = deferred<ThreadHistoryPage>();
+    adapter.getInitialHistory.mockReturnValueOnce(pending.promise);
+    const loading = get().loadMessages("pi", "thread");
+    const stream = (text: string) => {
+      get().threadProjections.thread = reduceProjection(get().threadProjections.thread, {
+        kind: "text_delta", agentType: "pi", threadId: "thread", runId: "second-run",
+        timestamp: 2000, sourceSubsequence: 0, contentMode: "delta", text,
+      });
+    };
+    stream("second answer");
+    const history = [
+      { ...row("u1"), role: "user" as const }, row("a1"),
+      { ...row("u2"), role: "user" as const },
+    ];
+    pending.resolve(page(history, "u2"));
+    await loading;
+    expect(get().threadProjections.thread.messages.slice(0, 3)).toEqual(history);
+    stream(" continues");
+    const messages = get().threadProjections.thread.messages;
+    expect(messages.slice(0, 3)).toEqual(history);
+    expect(messages).toHaveLength(4);
+    expect(messages[3].content).toBe("second answer continues");
+  });
+
   it("keeps known-empty Pi history ready while refreshing before the first message", async () => {
     const get = store([]);
     get().updateThreadHistory("thread", (projection) => ({
@@ -160,7 +186,7 @@ describe("history binding request fences", () => {
     const get = store([row("visible")]);
     const pending = deferred<ThreadHistoryPage>();
     adapter.getInitialHistory.mockReturnValueOnce(pending.promise);
-    const loading = get().loadMessages("claude", "thread");
+    const loading = get().loadMessages("claudecode", "thread");
     get().sessionMeta.externalSessionResolutions.thread = "native-b";
     pending.resolve(page([row("stale")], "stale"));
     await loading;
@@ -171,9 +197,9 @@ describe("history binding request fences", () => {
     const get = store([]);
     const stale = deferred<ThreadHistoryPage>();
     adapter.getInitialHistory.mockReturnValueOnce(stale.promise).mockResolvedValueOnce(page([row("fresh")], "fresh"));
-    const oldLoad = get().loadMessages("claude", "thread");
+    const oldLoad = get().loadMessages("claudecode", "thread");
     get().sessionMeta.externalSessionResolutions.thread = "native-b";
-    await get().loadMessages("claude", "thread");
+    await get().loadMessages("claudecode", "thread");
     stale.resolve(page([row("stale")], "stale"));
     await oldLoad;
     expect(get().threadProjections.thread.messages.map((item) => item.id)).toEqual(["fresh"]);
@@ -184,8 +210,8 @@ describe("history binding request fences", () => {
     const get = store([]);
     const pending = deferred<ThreadHistoryPage>();
     adapter.getInitialHistory.mockReturnValueOnce(pending.promise);
-    const first = get().loadMessages("claude", "thread");
-    await get().loadMessages("claude", "thread");
+    const first = get().loadMessages("claudecode", "thread");
+    await get().loadMessages("claudecode", "thread");
     expect(adapter.getInitialHistory).toHaveBeenCalledTimes(1);
     pending.resolve(page([row("first")], "first"));
     await first;
@@ -195,7 +221,7 @@ describe("history binding request fences", () => {
     const get = store([]);
     const pending = deferred<ThreadHistoryPage>();
     adapter.getInitialHistory.mockReturnValueOnce(pending.promise);
-    const loading = get().loadMessages("claude", "thread");
+    const loading = get().loadMessages("claudecode", "thread");
     get().sessionMeta.externalSessionResolutions.thread = "native-b";
     pending.resolve(page([row("stale")], "stale"));
     await loading;
@@ -211,7 +237,7 @@ describe("history binding request fences", () => {
     }));
     const pending = deferred<ThreadHistoryPage>();
     adapter.getPage.mockReturnValueOnce(pending.promise);
-    const loading = get().loadMoreMessages("claude", "thread");
+    const loading = get().loadMoreMessages("claudecode", "thread");
     get().sessionMeta.externalSessionResolutions.thread = "native-b";
     pending.resolve(page([row("stale")], "stale"));
     await loading;
@@ -221,7 +247,7 @@ describe("history binding request fences", () => {
 
   it("merges a partial history page without dropping a live message", () => {
     const get = store([row("live")]);
-    get().applyHistoryPage("thread", "claude", { messages: [row("older")], coverage: "partial" });
+    get().applyHistoryPage("thread", "claudecode", { messages: [row("older")], coverage: "partial" });
     expect(get().threadProjections.thread.messages.map((item) => item.id)).toEqual(["older", "live"]);
   });
 
@@ -260,7 +286,7 @@ describe("full history refresh", () => {
     const get = store([old]);
     const pending = deferred<ChatMessage[]>();
     adapter.getFullHistory.mockReturnValueOnce(pending.promise);
-    const loading = get().reloadMessagesFromHistory("deepseek-harness", "thread");
+    const loading = get().reloadMessagesFromHistory("dsh", "thread");
     const live = { ...old, content: "new live content" };
     get().updateThreadHistory("thread", (projection) => ({ ...projection, messages: [live] }));
     pending.resolve([old]);
diff --git a/app/flowix-web/features/agent/store/thread-history.test.ts b/app/flowix-web/features/agent/store/thread-history.test.ts
index 32daf5baf..c25a5c07e 100644
--- a/app/flowix-web/features/agent/store/thread-history.test.ts
+++ b/app/flowix-web/features/agent/store/thread-history.test.ts
@@ -38,7 +38,7 @@ describe("mergeMessagesForThreadRender", () => {
     const time = "2026-01-01T00:00:00Z";
     const history = [message("user-old", "user", "first", time), message("answer-old", "assistant", "Done.", time)];
     const live = [message("user-new", "user", "second", time), message("answer-new", "assistant", "Done.", time)];
-    expect(mergeMessagesForThreadRender({ history, live, agentType: "claude" }).map((row) => row.id))
+    expect(mergeMessagesForThreadRender({ history, live, agentType: "claudecode" }).map((row) => row.id))
       .toEqual(["user-old", "answer-old", "user-new", "answer-new"]);
   });
   it("uses the new Pi projection order when existing render rows are reordered", () => {
@@ -354,7 +354,7 @@ describe("mergeHistoricalMessages", () => {
     const time = "2026-01-01T00:00:00Z";
     const existing = [message("user-new", "user", "second question", time), message("reply-new", "assistant", "Done.", time)];
     const historical = [message("user-old", "user", "first question", time), message("reply-old", "assistant", "Done.", time)];
-    expect(mergeHistoricalMessages(existing, historical, "claude").map((item) => item.id))
+    expect(mergeHistoricalMessages(existing, historical, "claudecode").map((item) => item.id))
       .toEqual(["user-old", "reply-old", "user-new", "reply-new"]);
   });
   it("keeps identical Codex replies from different native turns", () => {
@@ -393,7 +393,7 @@ describe("mergeHistoricalMessages", () => {
     const existing = [
       {
         ...message(
-          "codex-command:live:command-1",
+          "flowix:codex:command:turn-1",
           "user",
           "/compact",
           "2026-08-29T10:00:01.000Z",
@@ -406,7 +406,7 @@ describe("mergeHistoricalMessages", () => {
     const historical = [
       {
         ...message(
-          "codex-command-history-compaction-1",
+          "flowix:codex:command:turn-1",
           "user",
           "/compact",
           "2026-08-29T10:00:00.000Z",
@@ -428,7 +428,7 @@ describe("mergeHistoricalMessages", () => {
 
     expect(
       mergeHistoricalMessages(existing, historical, "codex").map((item) => item.id),
-    ).toEqual(["codex-command-history-compaction-1", "compaction-1"]);
+    ).toEqual(["flowix:codex:command:turn-1", "compaction-1"]);
   });
 });
 
@@ -616,7 +616,7 @@ describe("replaceCompletedRunWithHistory", () => {
     const existing = [
       message("old-user", "user", "same prompt", "2026-01-01T00:00:00.000Z"),
       message("old-assistant", "assistant", "old answer", "2026-01-01T00:00:01.000Z"),
-      message("msg:deepseek-harness:run-2:user:user-run-2", "user", "same prompt", "2026-01-01T00:00:02.000Z"),
+      message("msg:dsh:run-2:user:user-run-2", "user", "same prompt", "2026-01-01T00:00:02.000Z"),
       message("live-assistant", "assistant", "current answer", "2026-01-01T00:00:03.000Z"),
     ];
     const history = [
@@ -631,7 +631,7 @@ describe("replaceCompletedRunWithHistory", () => {
         existing,
         history,
         "run-2",
-        "deepseek-harness",
+        "dsh",
       ).map((item) => item.content),
     ).toEqual(["same prompt", "old answer", "same prompt", "current answer"]);
   });
diff --git a/app/flowix-web/features/agent/store/thread-lifecycle-slice.ts b/app/flowix-web/features/agent/store/thread-lifecycle-slice.ts
index a7a47d224..9d2881aae 100644
--- a/app/flowix-web/features/agent/store/thread-lifecycle-slice.ts
+++ b/app/flowix-web/features/agent/store/thread-lifecycle-slice.ts
@@ -64,10 +64,10 @@ async function loadThreadList(
 ): Promise<void> {
   const type = getAgentType(typeKey);
   try {
-    const threads = await listHistoryThreads(type.key);
+    const threads = await listHistoryThreads(type.id);
     get().setSessionMeta((meta) => ({
       ...meta,
-      threadLists: { ...meta.threadLists, [type.key]: threads },
+      threadLists: { ...meta.threadLists, [type.id]: threads },
     }));
   } catch (error) {
     logger.error(`Failed to load ${errorLabel} thread list`, { error: String(error) });
@@ -85,25 +85,25 @@ async function loadThread(
     get().activateThread(threadId);
     const meta = get().sessionMeta;
     const threadInfo = await findHistoryThreadInfo(
-      type.key,
+      type.id,
       threadId,
-      meta.threadLists[type.key] ?? [],
+      meta.threadLists[type.id] ?? [],
     );
     get().setSessionMeta((current) => ({
       ...current,
-      activeAgentTypeKey: type.key,
-      activeThreadIds: { ...current.activeThreadIds, [type.key]: threadId },
+      activeAgentTypeKey: type.id,
+      activeThreadIds: { ...current.activeThreadIds, [type.id]: threadId },
       threadTypes: {
         ...current.threadTypes,
-        [threadId]: current.threadTypes[threadId] ?? type.key,
+        [threadId]: current.threadTypes[threadId] ?? type.id,
       },
       currentThreadTitles: {
         ...current.currentThreadTitles,
-        [threadId]: threadInfo?.title ?? defaultThreadTitle(type.key),
+        [threadId]: threadInfo?.title ?? defaultThreadTitle(type.id),
       },
     }));
     get().clearThreadPending(threadId);
-    await get().loadMessages(type.key, threadId);
+    await get().loadMessages(type.id, threadId);
   } catch (error) {
     logger.error(`Failed to load ${type.name} thread`, { error: String(error) });
   }
@@ -116,9 +116,9 @@ async function reloadThreadListForType(
   typeKey: AgentTypeKey,
 ): Promise<void> {
   const store = get();
-  if (typeKey === "deepseek-harness") await store.loadThreadList();
+  if (typeKey === "dsh") await store.loadThreadList();
   else if (typeKey === "codex") await store.loadCodexThreadList();
-  else if (typeKey === "claude") await store.loadClaudeThreadList();
+  else if (typeKey === "claudecode") await store.loadClaudeThreadList();
   else if (typeKey === "hermes") await store.loadHermesThreadList();
   else await store.loadLocalAgentThreadList(typeKey);
 }
@@ -214,9 +214,9 @@ export function createThreadLifecycleSlice(
     // cleanup out of `finally` prevents the work-column conversation from
     // disappearing while archive/delete is still pending or has failed.
     if (action === "archive") {
-      await agentClient.archiveAgentThread(typeKey.key, threadId);
+      await agentClient.archiveAgentThread(typeKey.id, threadId);
     } else {
-      await agentClient.deleteAgentThread(typeKey.key, threadId);
+      await agentClient.deleteAgentThread(typeKey.id, threadId);
     }
 
     // Notify the UI as soon as the provider confirms success. Local instance
@@ -230,7 +230,7 @@ export function createThreadLifecycleSlice(
     closeConversationIfActive(threadId, get);
     // provider 侧列表 (codex thread/list 等) 不再返回该 thread, 刷新让
     // 侧栏与后端状态对齐; 失败不阻塞流程。
-    await reloadThreadListForType(get, typeKey.key).catch(() => undefined);
+    await reloadThreadListForType(get, typeKey.id).catch(() => undefined);
     set((state) => ({ lifecycleVersion: state.lifecycleVersion + 1 }));
     } finally {
       get().setThreadMutationGuard(threadId, false);
@@ -240,29 +240,29 @@ export function createThreadLifecycleSlice(
   return {
     lifecycleVersion: 0,
     loadThreadList: () =>
-      loadThreadList(get, "deepseek-harness", "DeepSeek Harness"),
-    loadThread: (threadId) => loadThread(get, "deepseek-harness", threadId),
+      loadThreadList(get, "dsh", "DeepSeek Harness"),
+    loadThread: (threadId) => loadThread(get, "dsh", threadId),
     loadCodexThreadList: () => loadThreadList(get, "codex", "Codex"),
     loadCodexThread: (threadId) => loadThread(get, "codex", threadId),
-    loadClaudeThreadList: () => loadThreadList(get, "claude", "Claude Code"),
-    loadClaudeThread: (threadId) => loadThread(get, "claude", threadId),
+    loadClaudeThreadList: () => loadThreadList(get, "claudecode", "Claude Code"),
+    loadClaudeThread: (threadId) => loadThread(get, "claudecode", threadId),
     loadHermesThreadList: () => loadThreadList(get, "hermes", "Hermes"),
     loadHermesThread: (threadId) => loadThread(get, "hermes", threadId),
     loadAgentThread: (typeKey, threadId) => loadThread(get, typeKey, threadId),
     loadLocalAgentThreadList: async (typeKey) => {
       const type = getAgentType(typeKey);
-      if (["deepseek-harness", "codex", "claude", "hermes"].includes(type.key)) return;
-      await loadThreadList(get, type.key, type.name);
+      if (["dsh", "codex", "claudecode", "hermes"].includes(type.id)) return;
+      await loadThreadList(get, type.id, type.name);
     },
     loadThreadCache: async (threadId) => {
       try {
-        await get().loadMessages("deepseek-harness", threadId);
+        await get().loadMessages("dsh", threadId);
       } catch (error) {
         logger.error("Failed to load thread cache", { error: String(error) });
       }
     },
     loadMoreHistory: async (typeKey, threadId) => {
-      await get().loadMoreMessages(getAgentType(typeKey).key, threadId);
+      await get().loadMoreMessages(getAgentType(typeKey).id, threadId);
     },
     deleteThread: (threadId, onProviderSuccess) =>
       runThreadLifecycle(threadId, "delete", onProviderSuccess),
@@ -281,12 +281,12 @@ export function createThreadLifecycleSlice(
       const initialProductThreadId = resolveProductThreadId(
         threadId,
         before.externalSessionResolutions,
-        type.key,
+        type.id,
         before.threadTypes,
         (id) => isKnownProductThreadId(id, get()),
       );
       const initialIds = new Set([threadId, initialProductThreadId]);
-      const previousList = before.threadLists[type.key] ?? [];
+      const previousList = before.threadLists[type.id] ?? [];
       const previousThreadTitles = before.currentThreadTitles;
       const applyTitle = (meta: typeof before, productThreadId: string) => {
         const currentThreadTitles = { ...meta.currentThreadTitles };
@@ -295,14 +295,14 @@ export function createThreadLifecycleSlice(
         }
         currentThreadTitles[productThreadId] = nextTitle;
 
-        const threadLists = (meta.threadLists[type.key] ?? []).map((item) =>
+        const threadLists = (meta.threadLists[type.id] ?? []).map((item) =>
           initialIds.has(item.threadId)
             ? { ...item, threadId: productThreadId, title: nextTitle }
             : item,
         );
         const activeThreadIds = { ...meta.activeThreadIds };
-        if (initialIds.has(activeThreadIds[type.key] ?? "")) {
-          activeThreadIds[type.key] = productThreadId;
+        if (initialIds.has(activeThreadIds[type.id] ?? "")) {
+          activeThreadIds[type.id] = productThreadId;
         }
         const externalSessionResolutions =
           productThreadId !== threadId
@@ -313,14 +313,14 @@ export function createThreadLifecycleSlice(
           ...meta,
           threadTypes: {
             ...meta.threadTypes,
-            [threadId]: type.key,
-            [productThreadId]: type.key,
+            [threadId]: type.id,
+            [productThreadId]: type.id,
           },
           activeThreadIds,
           currentThreadTitles,
           threadLists: {
             ...meta.threadLists,
-            [type.key]: threadLists,
+            [type.id]: threadLists,
           },
           externalSessionResolutions,
         };
@@ -332,7 +332,7 @@ export function createThreadLifecycleSlice(
         const persisted = await agentClient.updateThreadTitle(
           threadId,
           nextTitle,
-          type.key,
+          type.id,
         );
         const persistedProductThreadId =
           persisted?.threadId ?? initialProductThreadId;
@@ -344,7 +344,7 @@ export function createThreadLifecycleSlice(
         // The title and conversation instances are already updated
         // optimistically above. Provider history reloads can wake an external
         // runtime and take several seconds, so they must not block saving.
-        void reloadThreadListForType(get, type.key).catch((error) => {
+        void reloadThreadListForType(get, type.id).catch((error) => {
           logger.error("Failed to refresh thread list after rename", { error: String(error) });
         });
       } catch (error) {
@@ -355,7 +355,7 @@ export function createThreadLifecycleSlice(
           },
           threadLists: {
             ...meta.threadLists,
-            [type.key]: previousList,
+            [type.id]: previousList,
           },
         }));
         logger.error("Failed to update thread title", { error: String(error) });
diff --git a/app/flowix-web/features/agent/store/thread-runtime-state.test.ts b/app/flowix-web/features/agent/store/thread-runtime-state.test.ts
index 4d08c2f54..c5277d63a 100644
--- a/app/flowix-web/features/agent/store/thread-runtime-state.test.ts
+++ b/app/flowix-web/features/agent/store/thread-runtime-state.test.ts
@@ -57,7 +57,7 @@ describe("thread-runtime-state helpers", () => {
       ...t,
       isLoading: true,
       activeRunId: "run-1",
-      runs: { "run-1": { runId: "run-1", agentType: "deepseek-harness" as const, threadId: "t1", startedAt: 1, status: "running" as const } },
+      runs: { "run-1": { runId: "run-1", agentType: "dsh" as const, threadId: "t1", startedAt: 1, status: "running" as const } },
     };
     expect(isThreadRunActive(running)).toBe(true);
 
@@ -72,7 +72,7 @@ describe("thread-runtime-state helpers", () => {
     const t = emptyThreadState();
     const event: AgentEvent = {
       kind: "text_delta",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "run-1",
       text: "hello",
@@ -89,7 +89,7 @@ describe("thread-runtime-state helpers", () => {
     const t = emptyThreadState();
     const streamStart: AgentEvent = {
       kind: "stream_start",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "run-1",
       timestamp: 1234,
@@ -98,7 +98,7 @@ describe("thread-runtime-state helpers", () => {
 
     const usage: AgentEvent = {
       kind: "usage",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "run-1",
       timestamp: 1234,
@@ -118,7 +118,7 @@ describe("thread-runtime-state helpers", () => {
       runs: {
         "run-existing": {
           runId: "run-existing",
-          agentType: "deepseek-harness" as const,
+          agentType: "dsh" as const,
           threadId: "t1",
           startedAt: 1000,
           status: "running" as const,
@@ -127,7 +127,7 @@ describe("thread-runtime-state helpers", () => {
     };
     const event: AgentEvent = {
       kind: "tool_call",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "run-newer",
       toolCallId: "tc-1",
@@ -146,14 +146,14 @@ describe("thread-runtime-state helpers", () => {
       ...emptyThreadState(),
       lastRun: {
         runId: "run-1",
-        agentType: "deepseek-harness" as const,
+        agentType: "dsh" as const,
         startedAt: 1000,
         status: "cancelled" as const,
       },
     };
     const lateText: AgentEvent = {
       kind: "text_delta",
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       threadId: "t1",
       runId: "run-1",
       text: "leftover",
diff --git a/app/flowix-web/features/agent/store/thread-runtime-state.ts b/app/flowix-web/features/agent/store/thread-runtime-state.ts
index a36118868..3e30c7a37 100644
--- a/app/flowix-web/features/agent/store/thread-runtime-state.ts
+++ b/app/flowix-web/features/agent/store/thread-runtime-state.ts
@@ -36,8 +36,7 @@ export interface ThreadState {
    * 通用 metadata 协议 ── 最新一次 run 的展示快照。
    * runs[runId] 在正常完成时被清理,但 lastRun 仍保留 model / usage /
    * startedAt / endedAt 等关键 metadata,供 BadgeHoverCard 等"展示"层
-   * 在 run 结束后仍可读。Provider-agnostic:对 Codex / Claude / Gemini /
-   * Flowix / Hermes / OpenClaw 全部适用。
+   * 在 run 结束后仍可读。Provider-agnostic: 对 Codex / Claude / Flowix / Hermes 全部适用。
    */
   lastRun?: LastRunSnapshot;
   /** Layer 4: 当前 in-memory messages 中最早一条的 sequence (作下一页 cursor).
diff --git a/app/flowix-web/features/agent/store/thread-titles.test.ts b/app/flowix-web/features/agent/store/thread-titles.test.ts
index a4cfeabaf..0c1b4e7ab 100644
--- a/app/flowix-web/features/agent/store/thread-titles.test.ts
+++ b/app/flowix-web/features/agent/store/thread-titles.test.ts
@@ -26,64 +26,54 @@ describe("thread-titles helpers", () => {
   });
 
   it("isExternalAgentType returns true for all supported runtimes", () => {
-    expect(isExternalAgentType("deepseek-harness")).toBe(true);
+    expect(isExternalAgentType("dsh")).toBe(true);
     expect(isExternalAgentType("codex")).toBe(true);
-    expect(isExternalAgentType("claude")).toBe(true);
-    expect(isExternalAgentType("deepseek-harness")).toBe(true);
-    expect(isExternalAgentType("gemini")).toBe(true);
+    expect(isExternalAgentType("claudecode")).toBe(true);
+    expect(isExternalAgentType("dsh")).toBe(true);
     expect(isExternalAgentType("hermes")).toBe(true);
-    expect(isExternalAgentType("openclaw")).toBe(true);
   });
 
   it("persists every agent title in the product database", () => {
-    expect(canPersistThreadTitle("deepseek-harness")).toBe(true);
+    expect(canPersistThreadTitle("dsh")).toBe(true);
     expect(canPersistThreadTitle("codex")).toBe(true);
-    expect(canPersistThreadTitle("claude")).toBe(true);
-    expect(canPersistThreadTitle("deepseek-harness")).toBe(true);
+    expect(canPersistThreadTitle("claudecode")).toBe(true);
+    expect(canPersistThreadTitle("dsh")).toBe(true);
     expect(canPersistThreadTitle("hermes")).toBe(true);
-    expect(canPersistThreadTitle("gemini")).toBe(true);
-    expect(canPersistThreadTitle("openclaw")).toBe(true);
   });
 
   it("defaultExternalThreadTitle returns type-specific translated text", () => {
     expect(defaultExternalThreadTitle("codex")).toBe("Codex session");
     // 注意: Claude agent name 是 "Claude Code" 不是 "Claude", 因此 i18n 词条返回
     // "Claude Code session".
-    expect(defaultExternalThreadTitle("claude")).toBe("Claude Code session");
-    expect(defaultExternalThreadTitle("deepseek-harness")).toBe(
+    expect(defaultExternalThreadTitle("claudecode")).toBe("Claude Code session");
+    expect(defaultExternalThreadTitle("dsh")).toBe(
       "DeepSeek Harness session",
     );
     // Session fallback titles are localized per agent type.
     expect(defaultExternalThreadTitle("hermes")).toBe("Hermes session");
-    expect(defaultExternalThreadTitle("gemini")).toBe("Gemini CLI session");
     expect(defaultExternalThreadTitle("opencode")).toBe("OpenCode session");
-    expect(defaultExternalThreadTitle("openclaw")).toBe("OpenClaw session");
   });
 
   it("defaultThreadTitle falls back per agent family", () => {
-    expect(defaultThreadTitle("deepseek-harness")).toBe("DeepSeek Harness session");
+    expect(defaultThreadTitle("dsh")).toBe("DeepSeek Harness session");
     expect(defaultThreadTitle("hermes")).toBe("Hermes session");
     expect(defaultThreadTitle("codex")).toBe("Codex session");
-    expect(defaultThreadTitle("claude")).toBe("Claude Code session");
-    expect(defaultThreadTitle("deepseek-harness")).toBe("DeepSeek Harness session");
+    expect(defaultThreadTitle("claudecode")).toBe("Claude Code session");
+    expect(defaultThreadTitle("dsh")).toBe("DeepSeek Harness session");
     expect(defaultThreadTitle("opencode")).toBe("OpenCode session");
     expect(defaultThreadTitle("hermes")).toBe("Hermes session");
-    expect(defaultThreadTitle("gemini")).toBe("Gemini CLI session");
-    expect(defaultThreadTitle("openclaw")).toBe("OpenClaw session");
   });
 
   it("localizes DeepSeek Harness card and session titles", () => {
     languageState.language = "zh-CN";
-    expect(defaultExternalThreadTitle("deepseek-harness")).toBe(
+    expect(defaultExternalThreadTitle("dsh")).toBe(
       "DeepSeek Harness 会话",
     );
-    expect(defaultThreadTitle("deepseek-harness")).toBe(
+    expect(defaultThreadTitle("dsh")).toBe(
       "DeepSeek Harness 会话",
     );
     expect(defaultThreadTitle("opencode")).toBe("OpenCode 会话");
     expect(defaultThreadTitle("hermes")).toBe("Hermes 会话");
-    expect(defaultThreadTitle("gemini")).toBe("Gemini CLI 会话");
-    expect(defaultThreadTitle("openclaw")).toBe("OpenClaw 会话");
   });
 
   it("deriveThreadTitleFromPrompt strips system block, collapses whitespace, truncates", () => {
@@ -154,7 +144,7 @@ describe("thread-titles helpers", () => {
     expect(getConversationTitleForThread(state3, "codex", "t-missing")).toBe(
       "Codex session",
     );
-    expect(getConversationTitleForThread(state3, "deepseek-harness", "t-missing")).toBe(
+    expect(getConversationTitleForThread(state3, "dsh", "t-missing")).toBe(
       "DeepSeek Harness session",
     );
   });
diff --git a/app/flowix-web/features/agent/store/thread-titles.ts b/app/flowix-web/features/agent/store/thread-titles.ts
index c6ae8b41a..9b2bf2985 100644
--- a/app/flowix-web/features/agent/store/thread-titles.ts
+++ b/app/flowix-web/features/agent/store/thread-titles.ts
@@ -18,18 +18,16 @@ function isExternalAgentType(_type: AgentTypeKey): boolean {
 // title has been reviewed and localized.
 const AGENT_SESSION_TITLE_KEYS: Record<AgentTypeKey, I18nKey> = {
   codex: "agent.codexSession.title",
-  claude: "agent.claudeSession.title",
-  gemini: "agent.geminiSession.title",
+  claudecode: "agent.claudeSession.title",
   hermes: "agent.hermesSession.title",
-  openclaw: "agent.openclawSession.title",
   opencode: "agent.opencodeSession.title",
   pi: "agent.piSession.title",
-  "deepseek-harness": "agent.deepseekHarnessSession.title",
+  dsh: "agent.deepseekHarnessSession.title",
 };
 
 const AGENT_THREAD_CARD_TITLE_KEYS: Record<AgentTypeKey, I18nKey> = {
   ...AGENT_SESSION_TITLE_KEYS,
-  "deepseek-harness": "agent.deepseekHarnessChat.title",
+  dsh: "agent.deepseekHarnessChat.title",
 };
 
 function translateAgentTitle(
diff --git a/app/flowix-web/features/agent/store/tool-chunks.test.ts b/app/flowix-web/features/agent/store/tool-chunks.test.ts
index 7d0663255..0ffba2d2e 100644
--- a/app/flowix-web/features/agent/store/tool-chunks.test.ts
+++ b/app/flowix-web/features/agent/store/tool-chunks.test.ts
@@ -259,6 +259,9 @@ describe("tool chunk idempotency", () => {
       { content: "tool output" },
       "codex",
     );
+    expect(toolResult.messages[1].id).toBe(
+      "flowix:codex:tool-call:unbound:future-result-only",
+    );
     const afterTool = applyTextChunk(toolResult, "after", {
       contentMode: "delta",
     });
@@ -275,6 +278,44 @@ describe("tool chunk idempotency", () => {
     ]);
   });
 
+  it("uses stable turn and call identities for Codex custom tools without item IDs", () => {
+    const started = applyToolCallChunk(
+      emptyState(), "call-a", "future_connector", { query: "x" }, "codex",
+      { messageType: "codex-custom-tool", codexTurnId: "turn-tools" },
+    );
+    expect(started.messages[0]).toMatchObject({
+      id: "flowix:codex:tool-call:turn-tools:call-a",
+      messageId: "flowix:codex:tool-call:turn-tools:call-a",
+      toolCallId: "call-a",
+    });
+
+    const orphan = applyToolResultChunk(
+      emptyState(), "call-b", "future_connector", { content: "done" }, "codex",
+      { messageType: "codex-custom-tool", codexTurnId: "turn-tools" },
+    );
+    expect(orphan.messages[0]).toMatchObject({
+      id: "flowix:codex:tool-output:turn-tools:call-b",
+      messageId: "flowix:codex:tool-output:turn-tools:call-b",
+      toolCallId: "call-b",
+      content: "{\n  \"content\": \"done\"\n}",
+    });
+
+    const nativeTool = applyToolCallChunk(
+      emptyState(), "call-c", "exec_command", { cmd: "pwd" }, "codex",
+      { codexTurnId: "turn-tools" },
+    );
+    expect(nativeTool.messages[0].id).toBe(
+      "flowix:codex:tool-call:turn-tools:call-c",
+    );
+
+    const unboundTool = applyToolCallChunk(
+      emptyState(), "call-d", "exec_command", { cmd: "pwd" }, "codex",
+    );
+    expect(unboundTool.messages[0].id).toBe(
+      "flowix:codex:tool-call:unbound:call-d",
+    );
+  });
+
   it("inserts a reconciled tool before a later assistant by source time", () => {
     const assistant = applyTextChunk(emptyState(), "final answer", {
       id: "assistant-item-2",
@@ -314,14 +355,14 @@ describe("tool chunk idempotency", () => {
           { content: "修复展示", status: "pending" },
         ],
       },
-      "deepseek-harness",
+      "dsh",
     );
     const completed = applyToolResultChunk(
       started,
       "plan-1",
       "tool",
       { content: "ok" },
-      "deepseek-harness",
+      "dsh",
     );
 
     expect(completed.messages[0]).toMatchObject({
diff --git a/app/flowix-web/features/agent/store/tool-chunks.ts b/app/flowix-web/features/agent/store/tool-chunks.ts
index 1a5a726b8..104656834 100644
--- a/app/flowix-web/features/agent/store/tool-chunks.ts
+++ b/app/flowix-web/features/agent/store/tool-chunks.ts
@@ -12,6 +12,10 @@ import {
 } from "@features/agent/message/display-limits";
 import { insertAgentMessageBySourceOrder, orderPiMessageBlocks } from "@features/agent/store/message-order";
 import type { MessageChunkMetadata } from "@features/agent/store/message-chunks";
+import {
+  codexCustomToolOutputMessageId,
+  codexToolCallMessageId,
+} from "@features/agent/events/codex-message-identity";
 
 function toolMessageTimestamp(sourceTimestamp?: number): string {
   return Number.isFinite(sourceTimestamp)
@@ -42,10 +46,15 @@ export function applyToolCallChunk(
   metadata: MessageChunkMetadata = {},
 ): MessageProjection {
   const toolInput = normalizeToolInput(input);
+  const messageId = metadata.id ?? (
+    agentType === "codex"
+      ? codexToolCallMessageId(metadata.codexTurnId, id)
+      : `tool-${id || Date.now()}`
+  );
   const toolMessage: ChatMessage = {
-    id: metadata.id ?? `tool-${id || Date.now()}`,
-    renderKey: metadata.id ?? id,
-    messageId: agentType === "pi" || agentType === "codex" ? metadata.id ?? id : undefined,
+    id: messageId,
+    renderKey: messageId,
+    messageId: agentType === "pi" || agentType === "codex" ? messageId : undefined,
     role: "tool",
     messageType: metadata.messageType,
     content: "",
@@ -130,6 +139,13 @@ export function applyToolResultChunk(
   const hasMatchingCall = st.messages.some(
     (message) => message.role === "tool" && toolCallIdsMatch(message.toolCallId, id),
   );
+  const orphanMessageId = metadata.id ?? (
+    agentType === "codex"
+      ? metadata.messageType === "codex-custom-tool"
+        ? codexCustomToolOutputMessageId(metadata.codexTurnId, id)
+        : codexToolCallMessageId(metadata.codexTurnId, id)
+      : `tool-${id || Date.now()}`
+  );
   const messages = hasMatchingCall
     ? st.messages.map((m) =>
         m.role === "tool" && toolCallIdsMatch(m.toolCallId, id)
@@ -157,9 +173,9 @@ export function applyToolResultChunk(
           : m,
       )
     : insertAgentMessageBySourceOrder(st.messages, {
-        id: metadata.id ?? `tool-${id || Date.now()}`,
-        renderKey: metadata.id ?? id,
-        messageId: agentType === "pi" || agentType === "codex" ? metadata.id ?? id : undefined,
+        id: orphanMessageId,
+        renderKey: orphanMessageId,
+        messageId: agentType === "pi" || agentType === "codex" ? orphanMessageId : undefined,
         role: "tool" as const,
         messageType: metadata.messageType,
         content: resultContent,
diff --git a/app/flowix-web/features/agent/store/user-message.ts b/app/flowix-web/features/agent/store/user-message.ts
index 72f7ea8ea..60eea4cd0 100644
--- a/app/flowix-web/features/agent/store/user-message.ts
+++ b/app/flowix-web/features/agent/store/user-message.ts
@@ -32,6 +32,8 @@ export interface PrepareUserMessageOptions {
   attachments?: AgentMessageAttachment[];
 }
 
+type AgentMessageAttachmentSource = Pick<AgentMessageAttachment, "path" | "name" | "mimeType">;
+
 function attachmentMimeType(path: string): string {
   const extension = path.split(/[\\/]/u).pop()?.split(".").pop()?.toLowerCase();
   switch (extension) {
@@ -48,17 +50,20 @@ function attachmentMimeType(path: string): string {
   }
 }
 
-/** Build display metadata from the authorized cache paths used by the IPC. */
+/** Build image display metadata from cached paths or their existing metadata. */
 export function createAgentMessageAttachments(
-  paths: readonly string[] | undefined,
+  attachments: readonly (string | AgentMessageAttachmentSource)[] | undefined,
 ): AgentMessageAttachment[] {
-  return (paths ?? []).map((path, index) => {
-    const name = path.split(/[\\/]/u).pop() || `image-${index + 1}`;
+  return (attachments ?? []).map((attachment, index) => {
+    const path = typeof attachment === "string" ? attachment : attachment.path;
+    const name = typeof attachment === "string"
+      ? path.split(/[\\/]/u).pop() || `image-${index + 1}`
+      : attachment.name;
     return {
       type: "input_image",
       path,
       name,
-      mimeType: attachmentMimeType(path),
+      mimeType: typeof attachment === "string" ? attachmentMimeType(path) : attachment.mimeType,
       detail: "high",
     };
   });
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-cache.test.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-cache.test.ts
index 5b7033382..3442a602d 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-cache.test.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-cache.test.ts
@@ -17,7 +17,7 @@ const sessionStoreMock = vi.hoisted(() => ({
   >,
   sessionMeta: {
     externalSessionResolutions: {},
-    activeAgentTypeKey: "deepseek-harness",
+    activeAgentTypeKey: "dsh",
     threadTypes: {},
     threadLists: {},
     currentThreadTitles: {},
@@ -99,11 +99,11 @@ describe("agent thread card cache helper", () => {
 
     const result = await loadAgentThreadCardCache({
       threadId: "flowix-thread",
-      typeKey: "deepseek-harness",
+      typeKey: "dsh",
     });
 
     expect(sessionStoreMock.loadMessages).toHaveBeenCalledWith(
-      "deepseek-harness",
+      "dsh",
       "flowix-thread",
     );
     expect(result).toEqual({
@@ -160,11 +160,11 @@ describe("agent thread card cache helper", () => {
 
     const result = await loadAgentThreadCardCache({
       threadId: "claude-real-session",
-      typeKey: "claude",
+      typeKey: "claudecode",
     });
 
     expect(sessionStoreMock.loadMessages).toHaveBeenCalledWith(
-      "claude",
+      "claudecode",
       "claude-real-session",
     );
     expect(result.loadedThreadId).toBe("claude-real-session");
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-dom.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-dom.ts
index fe53d6fe2..28336b01e 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-dom.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-dom.ts
@@ -18,7 +18,7 @@ export function focusAgentThreadCardInput(
     if (!(dom instanceof HTMLElement)) return;
 
     const input = dom.querySelector<HTMLElement>(
-      ".agent-thread-card__composer-input",
+      ".agent-composer__input",
     );
     if (!input) return;
 
@@ -89,9 +89,9 @@ export function isAgentThreadCardInteractiveTarget(target: Element): boolean {
       "input",
       "select",
       '[role="button"]',
-      ".agent-thread-card__composer",
-      ".agent-thread-card__access-popover",
-      ".agent-thread-card__composer-note-popover",
+      ".agent-composer",
+      ".agent-composer__access-popover",
+      ".agent-composer__note-popover",
       ".agent-thread-card__message-reasoning-header",
     ].join(","),
   );
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-extension.tsx b/app/flowix-web/features/agent/thread-card/agent-thread-card-extension.tsx
index b15b2cddc..94f4cb01c 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-extension.tsx
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-extension.tsx
@@ -2,6 +2,7 @@ import { Node, mergeAttributes, type MarkdownToken } from "@tiptap/core";
 import { Plugin, TextSelection } from "@tiptap/pm/state";
 import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
 import type { AgentTypeKey } from "@/types/agent";
+import type { WorkspaceHostId } from "@features/workspace/public/host-api";
 import {
   DEFAULT_AGENT_TYPE_KEY,
   getAgentType,
@@ -15,8 +16,8 @@ import {
   parseFlowixAgentThreadCardComment,
   parseAgentThreadCardMarkdown,
   renderAgentThreadCardMarkdown,
-  encodeAgentThreadCardInputImages,
-  decodeAgentThreadCardInputImages,
+  encodeAgentThreadCardInputAttachments,
+  decodeAgentThreadCardInputAttachments,
 } from "@features/agent/thread-card/agent-thread-card-markdown";
 import { focusAgentThreadCardInput } from "@features/agent/thread-card/agent-thread-card-dom";
 import { AgentThreadCardView } from "@features/agent/thread-card/agent-thread-card-view";
@@ -25,6 +26,11 @@ import {
   terminateAgentThreadCardRuntime,
 } from "@features/agent/thread-card/agent-thread-card-cleanup";
 import { getCurrentThreadCardSource } from "@features/agent/thread-card/runtime/thread-card-source";
+import {
+  LEGACY_THREAD_CARD_IMAGES_HTML_ATTRIBUTE,
+  THREAD_CARD_ATTACHMENTS_ATTRIBUTE,
+  THREAD_CARD_ATTACHMENTS_HTML_ATTRIBUTE,
+} from "@features/agent/thread-card/composer/composer-attachment-compat";
 
 export const SKIP_AGENT_THREAD_CARD_CLEANUP_META =
   "flowixSkipAgentThreadCardCleanup";
@@ -69,7 +75,11 @@ declare module "@tiptap/core" {
   }
 }
 
-export const AgentThreadCard = Node.create({
+export const AgentThreadCard = Node.create<{ workspaceHost: WorkspaceHostId }>({
+  addOptions() {
+    return { workspaceHost: "main-third" };
+  },
+
   name: "agentThreadCard",
   group: "block",
   content: "",
@@ -91,7 +101,7 @@ export const AgentThreadCard = Node.create({
       initialPrompt: { default: null },
       autoSubmit: { default: false },
       inputDraft: { default: null },
-      inputImages: { default: [] },
+      [THREAD_CARD_ATTACHMENTS_ATTRIBUTE]: { default: [] },
     };
   },
 
@@ -111,8 +121,9 @@ export const AgentThreadCard = Node.create({
             collapsed: element.getAttribute("data-collapsed") === "true",
             fullscreen: element.getAttribute("data-fullscreen") === "true",
             inputDraft: element.getAttribute("data-input-draft") || null,
-            inputImages: decodeAgentThreadCardInputImages(
-              element.getAttribute("data-input-images"),
+            [THREAD_CARD_ATTACHMENTS_ATTRIBUTE]: decodeAgentThreadCardInputAttachments(
+              element.getAttribute(THREAD_CARD_ATTACHMENTS_HTML_ATTRIBUTE)
+                ?? element.getAttribute(LEGACY_THREAD_CARD_IMAGES_HTML_ATTRIBUTE),
             ),
           };
         },
@@ -129,7 +140,9 @@ export const AgentThreadCard = Node.create({
     const collapsed = !!node.attrs.collapsed;
     const fullscreen = !!node.attrs.fullscreen;
     const inputDraft = node.attrs.inputDraft || "";
-    const inputImages = encodeAgentThreadCardInputImages(node.attrs.inputImages);
+    const inputAttachments = encodeAgentThreadCardInputAttachments(
+      node.attrs[THREAD_CARD_ATTACHMENTS_ATTRIBUTE],
+    );
 
     return [
       "section",
@@ -141,7 +154,9 @@ export const AgentThreadCard = Node.create({
         "data-collapsed": collapsed ? "true" : "false",
         "data-fullscreen": fullscreen ? "true" : "false",
         "data-input-draft": inputDraft,
-        "data-input-images": inputImages,
+        [THREAD_CARD_ATTACHMENTS_HTML_ATTRIBUTE]: inputAttachments,
+        // Preserve copy/paste compatibility with releases that only read this key.
+        [LEGACY_THREAD_CARD_IMAGES_HTML_ATTRIBUTE]: inputAttachments,
         class: collapsed
           ? "agent-thread-card agent-thread-card--collapsed"
           : "agent-thread-card",
@@ -162,11 +177,11 @@ export const AgentThreadCard = Node.create({
         ],
         [
           "div",
-          { class: "agent-thread-card__composer" },
+          { class: "agent-composer" },
           [
             "div",
             {
-              class: "agent-thread-card__composer-input",
+              class: "agent-composer__input",
               contenteditable: "true",
             },
             inputDraft,
@@ -174,7 +189,7 @@ export const AgentThreadCard = Node.create({
           [
             "button",
             {
-              class: "agent-thread-card__send",
+              class: "agent-composer__send",
               type: "button",
               "aria-label": "Send",
             },
@@ -215,7 +230,7 @@ export const AgentThreadCard = Node.create({
             initialPrompt: options?.initialPrompt ?? null,
             autoSubmit: !!options?.autoSubmit,
             inputDraft: null,
-            inputImages: [],
+            [THREAD_CARD_ATTACHMENTS_ATTRIBUTE]: [],
           });
           const from = options?.replaceRange?.from ?? state.selection.from;
           const to = options?.replaceRange?.to ?? from;
@@ -272,6 +287,7 @@ export const AgentThreadCard = Node.create({
         props.node,
         props.view,
         typeof props.getPos === "function" ? props.getPos : undefined,
+        this.options.workspaceHost,
       );
   },
 
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-icons.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-icons.ts
index 1ffb63d98..6bd39d35b 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-icons.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-icons.ts
@@ -5,7 +5,7 @@ import { TrashSimpleIcon } from "@phosphor-icons/react";
 import { getToolIconPath } from "@features/agent/message/tools";
 
 export const ICON_STOP_PATH =
-  "M216,56V200a16,16,0,0,1-16,16H56a16,16,0,0,1-16-16V56A16,16,0,0,1,56,40H200A16,16,0,0,1,216,56Z";
+  "M216,68V188a28,28,0,0,1-28,28H68a28,28,0,0,1-28-28V68a28,28,0,0,1,28-28H188a28,28,0,0,1,28,28Z";
 
 const ICON_CHEVRON_UP_PATH = "M6 15l6-6 6 6";
 const ICON_CHEVRON_DOWN_PATH = "M6 9l6 6 6-6";
@@ -30,12 +30,12 @@ const ICON_ALERT_PATH =
   "M12 9v4M12 17h.01M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0Z";
 const ICON_LOADER_PATH = "M21 12a9 9 0 1 1-6.219-8.56";
 
-function createSvg(viewBox: string, className: string): SVGSVGElement {
+function createSvg(viewBox: string, ...classNames: string[]): SVGSVGElement {
   const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
   svg.setAttribute("viewBox", viewBox);
   svg.setAttribute("aria-hidden", "true");
   svg.setAttribute("focusable", "false");
-  svg.classList.add(className);
+  svg.classList.add(...classNames);
   return svg;
 }
 
@@ -92,7 +92,7 @@ export function createArrowBendDownRightIcon(): SVGSVGElement {
 
 export function createTrashIcon(): SVGSVGElement {
   return appendFillPath(
-    createSvg("0 0 256 256", "agent-thread-card__trash-icon"),
+    createSvg("0 0 256 256", "agent-icon__trash"),
     ICON_TRASH_PATH,
   );
 }
@@ -109,7 +109,7 @@ export function createTrashSimpleIcon(): SVGSVGElement {
   if (!(icon instanceof SVGSVGElement)) {
     throw new Error("Failed to render TrashSimpleIcon");
   }
-  icon.classList.add("agent-thread-card__trash-icon");
+  icon.classList.add("agent-icon__trash");
   return icon;
 }
 
@@ -132,42 +132,46 @@ export function createToolIcon(
 
 export function createFolderIcon(): SVGSVGElement {
   return appendFillPath(
-    createSvg("0 0 256 256", "agent-thread-card__access-row-icon"),
+    createSvg("0 0 256 256", "agent-composer__access-row-icon"),
     ICON_FOLDER_PATH,
   );
 }
 
 export function createLaptopIcon(): SVGSVGElement {
   return appendFillPath(
-    createSvg("0 0 256 256", "agent-thread-card__access-workspace-icon"),
+    createSvg("0 0 256 256", "agent-composer__access-workspace-icon"),
     ICON_LAPTOP_PATH,
   );
 }
 
 export function createPlusIcon(): SVGSVGElement {
   return appendFillPath(
-    createSvg("0 0 24 24", "agent-thread-card__access-add-icon"),
+    createSvg("0 0 24 24", "agent-composer__access-add-icon"),
     ICON_PLUS_PATH,
   );
 }
 
 export function createComposerAddIcon(): SVGSVGElement {
   return appendFillPath(
-    createSvg("0 0 24 24", "agent-thread-card__composer-add-button-empty"),
+    createSvg("0 0 24 24", "agent-composer__add-button-empty"),
     ICON_PLUS_PATH,
   );
 }
 
 export function createAlertIcon(): SVGSVGElement {
   return appendStrokePath(
-    createSvg("0 0 24 24", "agent-thread-card__access-alert-icon"),
+    createSvg("0 0 24 24", "agent-composer__access-alert-icon"),
     ICON_ALERT_PATH,
   );
 }
 
 export function createToolRunningLoadingIcon(): SVGSVGElement {
   return appendStrokePath(
-    createSvg("0 0 24 24", "agent-thread-card__tool-group-running-loading-icon"),
+    createSvg(
+      "0 0 24 24",
+      "agent-thread-card__tool-group-running-loading-icon",
+      "flowix-spin",
+    ),
     ICON_LOADER_PATH,
   );
 }
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-markdown.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-markdown.ts
index 9abe00675..56d059e08 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-markdown.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-markdown.ts
@@ -2,7 +2,11 @@ import { Marked } from "marked";
 import { createLogger } from "@/lib/logger";
 import { normalizeAgentTypeKey } from "@/lib/agent-types";
 import { sanitizeLinkHref } from "@/lib/safe-link";
-import type { AgentThreadCardInputImage } from "@features/agent/thread-card/composer/composer-image-controller";
+import type { AgentThreadCardInputAttachment } from "@features/agent/thread-card/composer/composer-attachment-types";
+import {
+  LEGACY_THREAD_CARD_IMAGES_ATTRIBUTE,
+  THREAD_CARD_ATTACHMENTS_ATTRIBUTE,
+} from "@features/agent/thread-card/composer/composer-attachment-compat";
 import {
   getShiki,
   loadHighlighter,
@@ -25,7 +29,6 @@ interface FlowixAgentThreadCardMetadata {
   collapsed: boolean;
   fullscreen: boolean;
   inputDraft: string;
-  inputImages: AgentThreadCardInputImage[];
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -252,39 +255,39 @@ export function decodeAgentThreadCardInputDraft(
   }
 }
 
-export function encodeAgentThreadCardInputImages(
-  images: AgentThreadCardInputImage[] | null | undefined,
+export function encodeAgentThreadCardInputAttachments(
+  attachments: AgentThreadCardInputAttachment[] | null | undefined,
 ): string {
-  return encodeURIComponent(JSON.stringify(images ?? []));
+  return encodeURIComponent(JSON.stringify(attachments ?? []));
 }
 
-export function decodeAgentThreadCardInputImages(
+export function decodeAgentThreadCardInputAttachments(
   value: string | null | undefined,
-): AgentThreadCardInputImage[] {
+): AgentThreadCardInputAttachment[] {
   if (!value) return [];
   try {
     const parsed = JSON.parse(decodeURIComponent(value));
     if (!Array.isArray(parsed)) return [];
     return parsed.filter(
-      (image): image is AgentThreadCardInputImage =>
-        !!image &&
-        typeof image.path === "string" &&
-        typeof image.mimeType === "string" &&
-        typeof image.name === "string",
+      (attachment): attachment is AgentThreadCardInputAttachment =>
+        !!attachment &&
+        typeof attachment.path === "string" &&
+        typeof attachment.mimeType === "string" &&
+        typeof attachment.name === "string",
     );
   } catch {
     return [];
   }
 }
 
-function parseAgentThreadCardInputImages(value: unknown): AgentThreadCardInputImage[] {
+function parseAgentThreadCardInputAttachments(value: unknown): AgentThreadCardInputAttachment[] {
   if (!Array.isArray(value)) return [];
   return value.filter(
-    (image): image is AgentThreadCardInputImage =>
-      !!image &&
-      typeof image.path === "string" &&
-      typeof image.mimeType === "string" &&
-      typeof image.name === "string",
+    (attachment): attachment is AgentThreadCardInputAttachment =>
+      !!attachment &&
+      typeof attachment.path === "string" &&
+      typeof attachment.mimeType === "string" &&
+      typeof attachment.name === "string",
   );
 }
 
@@ -295,6 +298,8 @@ function parseAgentThreadCardNodeAttrs(
   const stringValue = (value: unknown): string =>
     typeof value === "string" ? value : "";
   const inputDraftValue = stringValue(values.inputDraft);
+  const attachmentValue = values[THREAD_CARD_ATTACHMENTS_ATTRIBUTE]
+    ?? values[LEGACY_THREAD_CARD_IMAGES_ATTRIBUTE];
 
   return {
     threadId: stringValue(values.threadId) || null,
@@ -310,11 +315,11 @@ function parseAgentThreadCardNodeAttrs(
         ? decodeAgentThreadCardInputDraft(inputDraftValue)
         : inputDraftValue
       : null,
-    inputImages: inputDraftEncoded
-      ? decodeAgentThreadCardInputImages(
-        typeof values.inputImages === "string" ? values.inputImages : undefined,
+    [THREAD_CARD_ATTACHMENTS_ATTRIBUTE]: inputDraftEncoded
+      ? decodeAgentThreadCardInputAttachments(
+        typeof attachmentValue === "string" ? attachmentValue : undefined,
       )
-      : parseAgentThreadCardInputImages(values.inputImages),
+      : parseAgentThreadCardInputAttachments(attachmentValue),
   };
 }
 
@@ -511,9 +516,124 @@ cardMarked.use({
   ],
 });
 
+function splitPipeTableRow(line: string): string[] | null {
+  const trimmed = line.trim();
+  if (!trimmed.includes("|")) return null;
+
+  const cells: string[] = [];
+  let cell = "";
+  let escaped = false;
+  for (const character of trimmed) {
+    if (character === "|" && !escaped) {
+      cells.push(cell.trim());
+      cell = "";
+    } else {
+      cell += character;
+    }
+    if (character === "\\" && !escaped) escaped = true;
+    else escaped = false;
+  }
+  cells.push(cell.trim());
+
+  if (trimmed.startsWith("|") && cells[0] === "") cells.shift();
+  if (trimmed.endsWith("|") && cells[cells.length - 1] === "") cells.pop();
+  return cells.length > 1 ? cells : null;
+}
+
+function isPipeTableSeparator(line: string): boolean {
+  const cells = splitPipeTableRow(line);
+  return !!cells?.length && cells.every((cell) => /^:?-{1,}:?$/.test(cell));
+}
+
+/**
+ * Normalize Markdown for every Agent message role. Join blank-separated GFM
+ * table rows, and demote Setext headings so `xxx\n---` becomes text plus a
+ * horizontal rule. Fenced code is left untouched.
+ */
+function normalizeAgentThreadCardMarkdown(markdown: string): string {
+  const lines = markdown.split("\n");
+  const output: string[] = [];
+  let inFence = false;
+  let fenceCharacter = "";
+
+  for (let index = 0; index < lines.length;) {
+    const line = lines[index];
+    const fence = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (inFence) {
+      output.push(line);
+      if (fence && fence[1][0] === fenceCharacter) inFence = false;
+      index += 1;
+      continue;
+    }
+    if (fence) {
+      inFence = true;
+      fenceCharacter = fence[1][0];
+      output.push(line);
+      index += 1;
+      continue;
+    }
+
+    if (
+      /^ {0,3}(?:-{1,}|={1,})[ \t]*$/.test(line) &&
+      output.length > 0 &&
+      output[output.length - 1].trim()
+    ) {
+      if (/^ {0,3}-{3,}[ \t]*$/.test(line)) {
+        output.push("", line);
+      } else {
+        const indent = line.match(/^ */)?.[0] ?? "";
+        output.push(`${indent}\\${line.trim()}`);
+      }
+      index += 1;
+      continue;
+    }
+
+    const headerCells = splitPipeTableRow(line);
+    if (headerCells) {
+      let separatorIndex = index + 1;
+      while (separatorIndex < lines.length && !lines[separatorIndex].trim()) {
+        separatorIndex += 1;
+      }
+      const separatorLine = lines[separatorIndex] ?? "";
+      const separatorCells = splitPipeTableRow(separatorLine);
+      if (
+        separatorCells &&
+        isPipeTableSeparator(separatorLine) &&
+        separatorCells.length === headerCells.length
+      ) {
+        output.push(line, separatorLine);
+        let rowIndex = separatorIndex + 1;
+        while (rowIndex < lines.length) {
+          let nextRowIndex = rowIndex;
+          while (nextRowIndex < lines.length && !lines[nextRowIndex].trim()) {
+            nextRowIndex += 1;
+          }
+          const rowCells = splitPipeTableRow(lines[nextRowIndex] ?? "");
+          if (!rowCells) {
+            output.push(...lines.slice(rowIndex, nextRowIndex));
+            index = nextRowIndex;
+            break;
+          }
+          output.push(lines[nextRowIndex]);
+          rowIndex = nextRowIndex + 1;
+          index = rowIndex;
+        }
+        if (rowIndex >= lines.length) index = rowIndex;
+        continue;
+      }
+    }
+
+    output.push(line);
+    index += 1;
+  }
+
+  return output.join("\n");
+}
+
 export function renderAgentThreadCardMarkdownToHtml(content: string): string {
   if (!content || !content.trim()) return "";
-  const html = cardMarked.parse(content) as string;
+  const normalizedContent = normalizeAgentThreadCardMarkdown(content);
+  const html = cardMarked.parse(normalizedContent) as string;
   // A Thread Card is a ProseMirror NodeView and therefore lives below the
   // editor's `.tiptap` element. Mark fenced blocks so editor-wide `pre`
   // selectors can explicitly leave agent message content alone.
@@ -670,7 +790,7 @@ export function renderAgentThreadCardMarkdown(node: {
 }): string {
   const stringValue = (value: unknown): string =>
     typeof value === "string" ? value : "";
-  const metadata: FlowixAgentThreadCardMetadata = {
+  const metadata: FlowixAgentThreadCardMetadata & Record<string, unknown> = {
     version: FLOWIX_AGENT_THREAD_CARD_METADATA_VERSION,
     instanceId: stringValue(node.attrs?.instanceId),
     threadId: stringValue(node.attrs?.threadId),
@@ -680,7 +800,11 @@ export function renderAgentThreadCardMarkdown(node: {
     collapsed: !!node.attrs?.collapsed,
     fullscreen: !!node.attrs?.fullscreen,
     inputDraft: stringValue(node.attrs?.inputDraft),
-    inputImages: parseAgentThreadCardInputImages(node.attrs?.inputImages),
   };
+  // Keep writing the established metadata key for older Flowix versions;
+  // parsed editor attributes and application code use `inputAttachments`.
+  metadata[LEGACY_THREAD_CARD_IMAGES_ATTRIBUTE] = parseAgentThreadCardInputAttachments(
+    node.attrs?.[THREAD_CARD_ATTACHMENTS_ATTRIBUTE],
+  );
   return `<!-- ${FLOWIX_AGENT_THREAD_CARD_MARKER} ${JSON.stringify(metadata)} -->\n`;
 }
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-selectors.test.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-selectors.test.ts
index 648854f46..f6f7c71ca 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-selectors.test.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-selectors.test.ts
@@ -199,7 +199,7 @@ describe('agent thread card selectors', () => {
       }),
       isCreating: false,
       isLoading: false,
-      typeKey: 'deepseek-harness',
+      typeKey: 'dsh',
     });
 
     expect(runtime.status).toBe('running');
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-submit-controller.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-submit-controller.ts
index e5cbcf21a..ea564dd8c 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-submit-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-submit-controller.ts
@@ -1,3 +1,4 @@
+import { ensureAgentWorkspaceReady } from "@features/agent/store/agent-workspace-store";
 import type { AgentTypeKey } from "@/types/agent";
 import type { AgentConversationSource } from "@features/agent/store/agent-conversation-types";
 import { createConversationInstanceId } from "@features/agent/store/conversation-slice";
@@ -76,6 +77,7 @@ export async function ensureAgentThreadCardConversation(
     runtimeConfig: buildInitialInstanceRuntimeConfig(nextTypeKey),
   });
   nextInstanceId = conversation.instanceId;
+  await ensureAgentWorkspaceReady();
   const runtimeConfig = ensureConversationWorkspaceSnapshot(nextInstanceId);
   markConversationWorkspaceStarted(nextInstanceId);
   input.onThreadBound({
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.test.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.test.ts
index a0e715e44..aa60432ee 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.test.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.test.ts
@@ -79,7 +79,7 @@ describe('agent thread card submit helper', () => {
     const result = await ensureAgentThreadCardThread({
       prompt: 'hello flowix',
       fallbackTitle: 'AI',
-      typeKey: 'deepseek-harness',
+      typeKey: 'dsh',
       currentThreadId: null,
       runtimeHandleId: 'handle-1',
       instanceId: 'inst-1',
@@ -89,7 +89,7 @@ describe('agent thread card submit helper', () => {
     expect(agent.createThread).not.toHaveBeenCalled();
     expect(beginExternalAgentThreadCardRun).toHaveBeenCalledWith(
       'handle-1',
-      'deepseek-harness',
+      'dsh',
       null,
       'inst-1',
     );
@@ -98,7 +98,7 @@ describe('agent thread card submit helper', () => {
     expect(result).toEqual({
       threadId: 'codex-local-inst-1',
       title: 'Title: hello flowix',
-      typeKey: 'deepseek-harness',
+      typeKey: 'dsh',
     });
   });
 });
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.ts
index 67d93061c..fdb6869a6 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-submit.ts
@@ -33,11 +33,11 @@ export async function ensureAgentThreadCardThread(
   return {
     threadId: beginExternalAgentThreadCardRun(
       input.runtimeHandleId,
-      type.key,
+      type.id,
       input.currentThreadId,
       input.instanceId,
     ),
     title: nextTitle,
-    typeKey: type.key,
+    typeKey: type.id,
   };
 }
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card-view.tsx b/app/flowix-web/features/agent/thread-card/agent-thread-card-view.tsx
index 6b08adfa9..42f46719b 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card-view.tsx
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card-view.tsx
@@ -17,7 +17,7 @@ import { translate, type AppLanguage, type I18nKey, type I18nParams } from "@/li
 import { createLogger } from "@/lib/logger";
 import { errorMessage } from "@/lib/error-message";
 import type { AgentTypeKey } from "@/types/agent";
-import type { WorkspaceHostId } from "@features/workspace/store/workspace-focus-store";
+import type { WorkspaceHostId } from "@features/workspace/public/host-api";
 import { deriveThreadTitleFromPrompt, defaultThreadTitle } from "@features/agent/store/thread-titles";
 import { toast } from "@/lib/toast";
 import { useNoteStore } from "@features/memo/store/note-store";
@@ -42,7 +42,6 @@ import { listPiSkills } from "@features/agent/services/pi-slash-command-service"
 import {
   createArrowBendDownRightIcon,
   createFullscreenIcon,
-  createTrashSimpleIcon,
 } from "@features/agent/thread-card/agent-thread-card-icons";
 import { createAgentThreadCardDom } from "@features/agent/thread-card/view/agent-thread-card-dom-factory";
 import { AgentThreadCardChromeController } from "@features/agent/thread-card/chrome";
@@ -55,10 +54,11 @@ import {
   ComposerSubmissionController,
   getComposerRuntimeState,
   ComposerDraftController,
-  ComposerImageController,
+  ComposerAttachmentController,
+  ComposerAttachmentDocument,
   ComposerAddMenuController,
   getCurrentNotebookComposerFolders,
-  type AgentThreadCardInputImage,
+  type AgentThreadCardInputAttachment,
   getAgentThreadCardUserHistoryMessagesFromMessages,
 } from "@features/agent/thread-card/composer";
 
@@ -68,7 +68,11 @@ import {
 } from "@features/agent/thread-card/messages";
 import { AgentConversationSurfaceController } from "@features/agent/thread-card/surface/agent-conversation-surface-controller";
 import { getAgentConversationRuntimeCwd } from "@features/agent/conversation-presentation";
-import { selectAndOpenAgentConversation } from "@features/workspace/use-cases/agent-conversation-navigation";
+import { openWorkspaceSurface } from "@features/workspace/public/open-surface-api";
+import {
+  getAgentMessageTypographyCssVars,
+  useAgentMessageFontStore,
+} from "@features/agent/store/agent-message-font-store";
 
 import { acceptComposerSubmission } from "@features/agent/services/composer-submission-service";
 
@@ -123,11 +127,35 @@ const AGENT_THREAD_CARD_REQUEST_FULLSCREEN_EVENT =
   "flowix:agent-thread-card-request-fullscreen";
 const AGENT_THREAD_CARD_FULLSCREEN_RESTORE_CLASS =
   "agent-thread-card--restoring-fullscreen";
+const AGENT_THREAD_CARD_MESSAGE_SCROLL_ACTIVE_CLASS =
+  "agent-thread-card--message-scroll-active";
 const AGENT_THREAD_CARD_INPUT_DRAFT_MAX_CHARS = 500;
 // inputDraft 落盘 debounce: typing 停 2s 后写入 ProseMirror attrs。
 // submit / destroy / blur 会主动 flush, 避免卡片重挂载时用旧 attr 回填。
 const AGENT_THREAD_CARD_DRAFT_PERSIST_DEBOUNCE_MS = 2000;
 
+function wheelDeltaPixels(event: WheelEvent, scroller: HTMLElement): {
+  deltaX: number;
+  deltaY: number;
+} {
+  if (event.deltaMode === WheelEvent.DOM_DELTA_LINE) {
+    const styles = getComputedStyle(scroller);
+    const lineHeight = Number.parseFloat(styles.lineHeight);
+    const fontSize = Number.parseFloat(styles.fontSize) || 16;
+    const lineSize = Number.isFinite(lineHeight) ? lineHeight : fontSize * 1.5;
+    return { deltaX: event.deltaX * lineSize, deltaY: event.deltaY * lineSize };
+  }
+
+  if (event.deltaMode === WheelEvent.DOM_DELTA_PAGE) {
+    return {
+      deltaX: event.deltaX * scroller.clientWidth,
+      deltaY: event.deltaY * scroller.clientHeight,
+    };
+  }
+
+  return { deltaX: event.deltaX, deltaY: event.deltaY };
+}
+
 function buildTitle(prompt: string, fallback: string = ""): string {
   return deriveThreadTitleFromPrompt(prompt, fallback);
 }
@@ -163,7 +191,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
   private fullscreenLayout: FullscreenLayoutController;
   private composerDraft: ComposerDraftController;
   private composerController: ComposerController;
-  private composerImages: ComposerImageController;
+  private composerAttachments: ComposerAttachmentController;
   private messages: AgentThreadCardMessagesController;
   private surface: AgentConversationSurfaceController;
   private runtime: AgentThreadCardRuntimeController;
@@ -179,11 +207,13 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
   private isCreating = false;
   private isDestroyed = false;
   private disposeBodyScrollbar: () => void = () => {};
+  private disposeAgentMessageTypography: () => void = () => {};
   private readonly submission = new ComposerSubmissionController();
   private interestedThreadId: string | null = null;
   private hydratingInstanceId: string | null = null;
   private releaseThreadInterest: (() => void) | null = null;
   private isFullscreen = false;
+  private isMessageScrollActive = false;
   private isViewportVisible = false;
   private visibilityObserver: IntersectionObserver | null = null;
   private fullscreenRestoreGeneration = 0;
@@ -261,6 +291,18 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
   private boundHandleOutsidePointerDown = (event: PointerEvent): void => {
     this.blurOwnedFocusForOutsidePointer(event);
   };
+  private boundHandleMessageScrollModePointerDown = (event: PointerEvent): void => {
+    if (this.isDestroyed || this.isFullscreen || event.button !== 0) return;
+    const target = event.target;
+    if (!(target instanceof Node)) return;
+
+    const bodyFrame = this.body.parentElement;
+    const clickedMessageSurface =
+      this.body.contains(target) ||
+      (bodyFrame?.classList.contains("agent-thread-card__body-frame") === true &&
+        bodyFrame.contains(target));
+    this.setMessageScrollActive(clickedMessageSurface);
+  };
   /**
    * A fullscreen card remains a NodeView inside the outer ProseMirror DOM.
    * The fixed positioning prevents most pointer interaction with the note,
@@ -310,6 +352,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     node: ProseMirrorNode,
     view: EditorView,
     getPos?: () => number | undefined,
+    private readonly hostId: WorkspaceHostId = "main-third",
   ) {
     this.node = node;
     this.view = view;
@@ -341,7 +384,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       },
       onBodyClick: (event) => this.handleBodyClick(event),
       onBodyScroll: this.boundHandleBodyScroll,
-      onBodyWheel: (event) => this.messages.handleUserScrollIntent(event.deltaY),
+      onBodyWheel: (event) => this.handleBodyWheel(event),
       // composer 空区域 → 输入框 focus 已由 createAgentComposerDom
       // 工厂内部挂的 pointerdown 委托统一处理 (详见
       // composer-dom-factory.ts COMPOSER_FOCUS_INTERACTIVE_SELECTOR),
@@ -350,6 +393,19 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     });
 
     this.dom = domParts.dom;
+    const applyAgentMessageTypography = () => {
+      const typography = useAgentMessageFontStore.getState();
+      const cssVars = getAgentMessageTypographyCssVars(typography.fontMode, typography.sizeMode);
+      this.dom.style.setProperty('--agent-message-font-family', cssVars['--agent-message-font-family']);
+      this.dom.style.setProperty('--agent-message-base-font-size', cssVars['--agent-message-base-font-size']);
+      this.dom.style.setProperty('--agent-message-size-scale', String(cssVars['--agent-message-size-scale']));
+    };
+    applyAgentMessageTypography();
+    this.disposeAgentMessageTypography = useAgentMessageFontStore.subscribe((state, previous) => {
+      if (state.fontMode !== previous.fontMode || state.sizeMode !== previous.sizeMode) {
+        applyAgentMessageTypography();
+      }
+    });
     if (typeof IntersectionObserver !== "undefined") {
       this.visibilityObserver = new IntersectionObserver((entries) => {
         const visible = entries.some((entry) => entry.isIntersecting);
@@ -360,7 +416,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       });
       this.visibilityObserver.observe(this.dom);
     }
-    if (this.persistedFullscreen) {
+    if (this.persistedFullscreen && this.shouldRestorePersistedFullscreen()) {
       this.dom.classList.add(AGENT_THREAD_CARD_FULLSCREEN_RESTORE_CLASS);
     }
     this.chrome = new AgentThreadCardChromeController({
@@ -376,6 +432,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       getNodeSize: () => this.node.nodeSize,
       isFullscreen: () => this.isFullscreen,
       closeTransientUi: () => {
+        this.composerAddMenu?.close();
         this.setCodexSettingsPopoverOpen(false);
         this.notePicker.setOpen(false);
       },
@@ -420,6 +477,8 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       isDestroyed: () => this.isDestroyed,
       isRunning: () => this.currentRuntimeView().isRunning,
       consumeOutsidePointer: consumeEditorPopoverDismissPointer,
+      onPopoverStateChange: (open, anchor) =>
+        this.composerAddMenu?.syncSettingsSubmenuState(open, anchor),
       // 常用笔记卡片 → 直接注入 composer 输入框, 与文档引用走同一条路径。
       onSelectFeaturedNote: (ref) => this.injectMemoReference(ref),
       toast: (kind, message) => toast[kind](message),
@@ -465,11 +524,10 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       persistDelayMs: AGENT_THREAD_CARD_DRAFT_PERSIST_DEBOUNCE_MS,
       persist: (draft) => this.updateAttrs({ inputDraft: draft }),
     });
-    this.composerImages = new ComposerImageController({
+    this.composerAttachments = new ComposerAttachmentController({
       input: this.input,
-      container: domParts.composerImages,
-      initialImages: this.inputImages,
-      onChange: (images) => this.updateAttrs({ inputImages: images }),
+      initialAttachments: this.inputAttachments,
+      onChange: (attachments) => this.updateAttrs({ inputAttachments: attachments }),
       onStateChange: () => this.composerController?.setSendButtonState(),
       onError: (message) => toast.error(message),
       onLimitExceeded: (kind) => {
@@ -486,10 +544,46 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       trigger: this.composerRoleIcon,
       popover: composerAddPopover,
       notePopover: composerRolePopover,
+      settingsPopover: codexSettingsPopover,
       notePicker: this.notePicker,
-      images: this.composerImages,
+      attachments: this.composerAttachments,
       t: (key) => this.t(key),
       isDestroyed: () => this.isDestroyed,
+      settings: [
+        ...(composerModelButton
+          ? [{
+              label: "agent.model.title" as const,
+              popupRole: this.typeKey === "pi" ? "dialog" as const : "menu" as const,
+              onHover: (anchor: HTMLButtonElement) =>
+                this.externalAgentSettings.openComposerSettingsPopover("model", anchor),
+            }]
+          : []),
+        ...(composerModeButton
+          ? [{
+              label: "agent.mode.title" as const,
+              onHover: (anchor: HTMLButtonElement) =>
+                this.externalAgentSettings.openComposerSettingsPopover("mode", anchor),
+            }]
+          : []),
+        ...(composerPermissionButton
+          ? [{
+              label: "agent.permission.title" as const,
+              onHover: (anchor: HTMLButtonElement) =>
+                this.externalAgentSettings.openComposerSettingsPopover("permission", anchor),
+            }]
+          : []),
+        ...(composerWorkspaceButton
+          ? [{
+              label: "agent.workspace.access" as const,
+              onHover: (anchor: HTMLButtonElement) =>
+                this.externalAgentSettings.openComposerWorkspacePopover(anchor),
+            }]
+          : []),
+      ],
+      showSettings: () => !this.isFullscreen,
+      closeSettingsSubmenu: (anchor) =>
+        this.externalAgentSettings.closeComposerSettingsPopover(anchor),
+      consumeOutsidePointer: consumeEditorPopoverDismissPointer,
       openNotebookAgentSettings: () => {
         const notebookPath = this.notebookPath;
         if (notebookPath) this.notebookAgentSettingsDialog.open(notebookPath);
@@ -558,11 +652,21 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       getUserHistoryMessages: () => this.getUserHistoryMessages(),
       getSendLabel: (label) => this.t(`editor.threadCard.${label}`),
       getRuntimeState: () => this.composerRuntimeState(),
-      getHasAttachments: () => this.composerImages.hasImages,
-      getHasPendingAttachments: () => this.composerImages.hasPending,
+      getHasAttachments: () => this.composerAttachments.hasAttachments,
+      getHasPendingAttachments: () => this.composerAttachments.hasPending,
       agentType: this.typeKey,
+      getSkillsScopeId: () => {
+        const instance = this.instance;
+        const runtime = instance?.runtimeConfig;
+        return runtime?.notebookId
+          ?? runtime?.workspaceSnapshot?.notebookId
+          ?? instance?.source.notebookId
+          ?? runtime?.workspaceSnapshot?.notebookPath
+          ?? runtime?.cwd
+          ?? undefined;
+      },
       listDshSkills: async () => {
-        if (this.typeKey !== "deepseek-harness") return [];
+        if (this.typeKey !== "dsh") return [];
         const ensured = await this.ensureDshCommandConversation("/skill");
         return listDshSkills({
           threadId: ensured.threadId,
@@ -601,6 +705,9 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     });
     this.messages = this.surface.messages;
     this.composerController = this.surface.composer;
+    this.composerAttachments.connectDocument(
+      new ComposerAttachmentDocument(this.composerController.editorInstance),
+    );
     this.composerController.setSendButtonState("");
 
     this.refreshAttrs();
@@ -615,6 +722,11 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       this.boundHandleOutsidePointerDown,
       true,
     );
+    document.addEventListener(
+      "pointerdown",
+      this.boundHandleMessageScrollModePointerDown,
+      true,
+    );
     document.addEventListener(
       "pointerdown",
       this.boundHandleFullscreenPointerDown,
@@ -642,7 +754,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
   private async forkFromMessage(message: ThreadState["messages"][number]): Promise<void> {
     if (!this.threadId) return;
     const isCodex = this.typeKey === "codex";
-    const isDsh = this.typeKey === "deepseek-harness";
+    const isDsh = this.typeKey === "dsh";
     const isPi = this.typeKey === "pi";
     if (!isCodex && !isDsh && !isPi) return;
     if (isCodex && !message.codexTurnId) return;
@@ -669,7 +781,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
         },
         source: { kind: "dedicated", notebookId: source?.source.notebookId ?? null },
       });
-      await selectAndOpenAgentConversation(fork.instanceId);
+      await openWorkspaceSurface({ target: { kind: 'agent-conversation', instanceId: fork.instanceId } });
     } catch (error) {
       logger.error(`Failed to fork ${this.typeKey} conversation`, { error });
       toast.error(error instanceof Error ? error.message : String(error));
@@ -830,7 +942,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       threadId: existingThreadId,
       source: getCurrentThreadCardSource(),
       // 这里只记录 notebookId；cwd / paths 在首次 send 前解析并冻结，避免
-      // 此处 selectedNotebook / agent-access 尚未 hydrate 时写入空快照。
+      // 此处 selectedNotebook / workspace 尚未 hydrate 时写入空快照。
       runtimeConfig: buildInitialInstanceRuntimeConfig(this.typeKey),
     });
     this.updateAttrs({
@@ -849,9 +961,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
   }
 
   private get workspaceHost(): WorkspaceHostId | null {
-    const host = this.dom.closest<HTMLElement>("[data-workspace-host]")
-      ?.dataset.workspaceHost;
-    return host === "main-third" || host === "browser-column" ? host : null;
+    return this.hostId;
   }
 
   private get inputDraft(): string {
@@ -859,8 +969,8 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     return typeof value === "string" ? value : "";
   }
 
-  private get inputImages(): AgentThreadCardInputImage[] {
-    const value = this.node.attrs.inputImages;
+  private get inputAttachments(): AgentThreadCardInputAttachment[] {
+    const value = this.node.attrs.inputAttachments;
     return Array.isArray(value) ? value : [];
   }
 
@@ -897,7 +1007,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
 
   private createExternalAgentEmptySettings(): HTMLElement {
     return this.externalAgentSettings.createEmptySettings({
-      showControls: !this.isFullscreen,
+      presentation: this.isFullscreen ? "expanded" : "inline-card",
     });
   }
 
@@ -1056,6 +1166,17 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     this.setFullscreen(!this.isFullscreen);
   }
 
+  /**
+   * Whether this surface may restore a persisted fullscreen marker.
+   *
+   * Persisted fullscreen is restored in the primary work column only. Users
+   * can still enter fullscreen manually in either host; a browser-column copy
+   * stays inline when a note opens so its surrounding text remains visible.
+   */
+  private shouldRestorePersistedFullscreen(): boolean {
+    return this.workspaceHost === 'main-third';
+  }
+
   /**
    * Markdown may contain more than one stale fullscreen marker (for example
    * after a merge). Only the first marked card in document order is restored.
@@ -1067,7 +1188,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       window.cancelAnimationFrame(this.fullscreenRestoreFrame);
       this.fullscreenRestoreFrame = null;
     }
-    if (this.persistedFullscreen) {
+    if (this.persistedFullscreen && this.shouldRestorePersistedFullscreen()) {
       this.dom.classList.add(AGENT_THREAD_CARD_FULLSCREEN_RESTORE_CLASS);
     }
     queueMicrotask(() => this.restorePersistedFullscreenIfFirst(generation));
@@ -1097,6 +1218,11 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       return;
     }
 
+    if (!this.shouldRestorePersistedFullscreen()) {
+      this.finishPersistedFullscreenRestore(generation);
+      return;
+    }
+
     if (!this.isFirstPersistedFullscreenCard()) {
       this.finishPersistedFullscreenRestore(generation);
       return;
@@ -1179,6 +1305,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       this.cancelPersistedFullscreenRestore();
     }
     if (this.isFullscreen === fullscreen) return;
+    this.setMessageScrollActive(false);
 
     if (fullscreen) {
       this.captureFullscreenReturnAnchor();
@@ -1448,6 +1575,37 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     });
   }
 
+  private setMessageScrollActive(active: boolean): void {
+    if (this.isMessageScrollActive === active) return;
+    this.isMessageScrollActive = active;
+    this.dom.classList.toggle(
+      AGENT_THREAD_CARD_MESSAGE_SCROLL_ACTIVE_CLASS,
+      active,
+    );
+  }
+
+  private handleBodyWheel(event: WheelEvent): void {
+    if (this.isFullscreen || this.isMessageScrollActive) {
+      this.messages.handleUserScrollIntent(event.deltaY);
+      return;
+    }
+
+    const editorScroller = this.body.closest<HTMLElement>(".editor-content");
+    if (!editorScroller) {
+      this.messages.handleUserScrollIntent(event.deltaY);
+      return;
+    }
+
+    const { deltaX, deltaY } = wheelDeltaPixels(event, editorScroller);
+    if (deltaX === 0 && deltaY === 0) return;
+
+    // Before the message area is clicked, treat it as transparent to editor
+    // scrolling. Clicking outside the viewport returns to this default mode.
+    event.preventDefault();
+    editorScroller.scrollTop += deltaY;
+    editorScroller.scrollLeft += deltaX;
+  }
+
   private renderMetaState(
     state: ThreadState | undefined,
     isLoading: boolean,
@@ -1519,7 +1677,24 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
             soon.setAttribute("role", "status");
             soon.textContent = this.t("agent.queue.sendingSoon");
             actions.append(soon);
-          } else if (message.deliveryMode === "follow_up") {
+          }
+          if (message.canDelete !== false) {
+            const remove = document.createElement("button");
+            remove.type = "button";
+            remove.className = "agent-background-terminals__queue-delete";
+            remove.disabled = actionsDisabled;
+            remove.setAttribute("aria-label", this.t("agent.queue.deleteQueued"));
+            remove.title = this.t("agent.queue.deleteQueued");
+            remove.textContent = this.t("agent.queue.deleteQueued");
+            remove.addEventListener("click", () => {
+              const threadId = this.renderThreadId;
+              if (!threadId) return;
+              void useAgentSessionStore.getState().deleteQueuedFollowUp(threadId, message.id)
+                .catch((error) => toast.error(error instanceof Error ? error.message : String(error)));
+            });
+            actions.append(remove);
+          }
+          if (message.deliveryStatus !== "starting" && message.deliveryMode === "follow_up") {
             const steer = document.createElement("button");
             steer.type = "button";
             steer.className = "agent-background-terminals__queue-steer";
@@ -1541,22 +1716,6 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
               : this.t("agent.queue.sendingSoon");
             actions.append(soon);
           }
-          if (message.canDelete !== false) {
-            const remove = document.createElement("button");
-            remove.type = "button";
-            remove.className = "agent-background-terminals__queue-delete";
-            remove.disabled = actionsDisabled;
-            remove.setAttribute("aria-label", this.t("agent.queue.deleteQueued"));
-            remove.title = this.t("agent.queue.deleteQueued");
-            remove.append(createTrashSimpleIcon());
-            remove.addEventListener("click", () => {
-              const threadId = this.renderThreadId;
-              if (!threadId) return;
-              void useAgentSessionStore.getState().deleteQueuedFollowUp(threadId, message.id)
-                .catch((error) => toast.error(error instanceof Error ? error.message : String(error)));
-            });
-            actions.append(remove);
-          }
           row.append(actions);
         }
         return row;
@@ -1656,7 +1815,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
   }
 
   private async ensureDshCommandConversation(command: string) {
-    if (this.typeKey !== "deepseek-harness") {
+    if (this.typeKey !== "dsh") {
       throw new Error("This slash command is only available for DSH");
     }
     return ensureAgentThreadCardConversation({
@@ -1718,7 +1877,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     const isFirstMessage = this.currentMessages().length === 0;
     await this.submission.submit({
       composer: this.composerController,
-      images: this.composerImages,
+      images: this.composerAttachments,
       getRuntime: () => this.composerRuntimeState(),
       isDisposed: () => this.isDestroyed,
       bind: (snapshot) => ensureAgentThreadCardConversation({
@@ -1818,7 +1977,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     const activeElement = document.activeElement;
     if (
       activeElement instanceof HTMLElement &&
-      activeElement.closest(".agent-thread-card__composer")
+      activeElement.closest(".agent-composer")
     ) {
       return;
     }
@@ -1861,6 +2020,11 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
       this.boundHandleOutsidePointerDown,
       true,
     );
+    document.removeEventListener(
+      "pointerdown",
+      this.boundHandleMessageScrollModePointerDown,
+      true,
+    );
     document.removeEventListener(
       "pointerdown",
       this.boundHandleFullscreenPointerDown,
@@ -1884,6 +2048,7 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     this.surface.dispose();
     this.body.removeEventListener("scroll", this.boundHandleBodyScroll);
     this.disposeBodyScrollbar();
+    this.disposeAgentMessageTypography();
     this.runtime.dispose();
     this.externalAgentSettings.dispose();
     this.notePicker.dispose();
@@ -1892,6 +2057,6 @@ export class AgentThreadCardView implements ProseMirrorNodeView {
     this.fullscreenLayout.dispose();
     this.visibilityObserver?.disconnect();
     this.visibilityObserver = null;
-    this.composerImages.dispose();
+    this.composerAttachments.dispose();
   }
 }
diff --git a/app/flowix-web/features/agent/thread-card/agent-thread-card.test.ts b/app/flowix-web/features/agent/thread-card/agent-thread-card.test.ts
index 59109165a..ed6833c30 100644
--- a/app/flowix-web/features/agent/thread-card/agent-thread-card.test.ts
+++ b/app/flowix-web/features/agent/thread-card/agent-thread-card.test.ts
@@ -1,3 +1,4 @@
+import type { AgentAccessConfig } from "@/lib/types/agent-workspace.test-support";
 import { Editor } from "@tiptap/core";
 import { NodeSelection } from "@tiptap/pm/state";
 import { closeHistory } from "@tiptap/pm/history";
@@ -24,15 +25,7 @@ const memoStateMock = vi.hoisted(() => ({
 }));
 
 const agentAccessState = vi.hoisted(() => ({
-  config: { entries: [] as Array<Record<string, unknown>> } as {
-    entries: Array<Record<string, unknown>>;
-    defaults?: {
-      files?: Record<
-        string,
-        { workspace?: string; folders: string[]; notebooks: string[] }
-      >;
-    };
-  },
+  config: { version: 1, entries: [] } as AgentAccessConfig,
 }));
 
 const toastMock = vi.hoisted(() => ({
@@ -48,6 +41,9 @@ vi.mock("@features/workspace/use-cases/browser-column-navigation", () => ({
     tabId: 'file-browser:/Users/rop/Desktop/vibe/flowix-main',
     alreadyOpen: false,
   })),
+  openBrowserColumnNotebookNote: vi.fn(() => ({
+    host: 'browser-column', tabId: 'file:external-note', alreadyOpen: false,
+  })),
   openBrowserColumnText: vi.fn(() => ({
     host: 'browser-column', tabId: 'file:external-text', alreadyOpen: false,
   })),
@@ -71,19 +67,22 @@ vi.mock("@platform/tauri/client", () => ({
   agent: {
     ...createAgentClientMock(),
     listSupportedModels: vi.fn(async () => []),
-    cacheImage: vi.fn(async () => ({
+    cacheAttachment: vi.fn(async () => ({
       path: "/tmp/cached-agent-image.png",
       mimeType: "image/png",
       name: "cached-agent-image.png",
     })),
-    deleteCachedImage: vi.fn(async () => true),
-    readCachedImage: vi.fn(async () => null),
+    deleteCachedAttachment: vi.fn(async () => true),
+    readCachedAttachment: vi.fn(async () => null),
     getDeepSeekHarnessSessionId: vi.fn(async () => null),
     getCodexSessionId: vi.fn(async () => null),
     getClaudeSessionId: vi.fn(async () => null),
     getCodexDefaultModel: vi.fn(async () => "gpt-5.5"),
   },
+  agentWorkspace: { getLegacyPreferences: vi.fn(async () => null) },
   piModels: {
+    getFeatures: vi.fn(async () => ({ toolSearch: false })),
+    clearLegacyCodeMode: vi.fn(async () => undefined),
     list: vi.fn(async () => []),
   },
   notes: {
@@ -121,20 +120,32 @@ vi.mock("@platform/tauri/client", () => ({
   listenToAgentStream: vi.fn(),
 }));
 
-vi.mock("@features/agent/store/agent-access-store", () => ({
-  useAgentAccessStore: {
-    getState: () => ({
-      config: agentAccessState.config,
-      isLoading: false,
-      toggle: vi.fn(),
-      setWorkspace: vi.fn(),
-      addFolderFromPicker: vi.fn(async () => ({ ok: true })),
-      removeFolder: vi.fn(),
-      loadInitial: vi.fn(),
-    }),
-    subscribe: vi.fn(() => () => undefined),
-  },
-}));
+vi.mock("@features/agent/store/agent-workspace-store", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@features/agent/store/agent-workspace-store")>();
+  const getState = () => ({ ...actual.useAgentWorkspaceStore.getState(),
+    workspace: {
+      ...actual.useAgentWorkspaceStore.getState().workspace,
+      ...actual.projectAgentWorkspace({ notebooks: agentAccessState.config.entries.filter(e => e.kind === "notebook"), notebookConfigs: Object.fromEntries(
+        Object.entries(agentAccessState.config.defaults?.files ?? {}).map(([id, files]) => [id, {
+          version: 1, revision: 1, addDirs: files.folders.map((path) => ({ id: path, path, label: path, enabled: true })),
+        }]),
+      ) }),
+    },
+    workspaceActions: {
+      ...actual.useAgentWorkspaceStore.getState().workspaceActions,
+      addFolderFromPicker: vi.fn(async () => ({ ok: true as const })),
+      attachFolderToNotebook: vi.fn(async () => "saved" as const),
+      detachFolderFromNotebook: vi.fn(async () => "saved" as const),
+      getNotebookFiles: (id: string | null | undefined) => id ? agentAccessState.config.defaults?.files?.[id] : undefined,
+      loadInitial: vi.fn(async () => true),
+    },
+  });
+  return { ...actual, ensureAgentWorkspaceReady: vi.fn(async () => {}), useAgentWorkspaceStore: Object.assign(
+    (selector: Parameters<typeof actual.useAgentWorkspaceStore>[0]) => selector ? selector(getState()) : getState(),
+    actual.useAgentWorkspaceStore,
+    { getState },
+  ) };
+});
 
 vi.mock("@features/agent/store/agent-runtime-store", () => ({
   useAgentRuntimeStore: {
@@ -148,10 +159,13 @@ vi.mock("@features/agent/store/agent-runtime-store", () => ({
 }));
 
 vi.mock("@features/memo/store/note-store", () => ({
-  useNoteStore: {
-    getState: () => memoStateMock,
-    subscribe: vi.fn(() => () => undefined),
-  },
+  useNoteStore: Object.assign(
+    (selector: (state: typeof memoStateMock) => unknown) => selector(memoStateMock),
+    {
+      getState: () => memoStateMock,
+      subscribe: vi.fn(() => () => undefined),
+    },
+  ),
 }));
 
 vi.mock("@features/memo/components/notebook-icon", () => ({
@@ -180,7 +194,7 @@ vi.mock("@features/document/store/document-store", () => ({
   },
 }));
 
-vi.mock("@features/memo/use-cases/open-by-target", () => ({
+vi.mock("@features/memo/public/note-navigation-api", () => ({
   openNoteByDeepLink: vi.fn(),
 }));
 
@@ -212,7 +226,7 @@ type ComposerInput = HTMLDivElement & { editor?: Editor };
 
 function getComposerInput(root: ParentNode): ComposerInput {
   const input = root.querySelector<HTMLDivElement>(
-    ".agent-thread-card__composer-input",
+    ".agent-composer__input",
   ) as ComposerInput | null;
   if (!input) throw new Error("Composer input not found");
   return input;
@@ -262,7 +276,7 @@ async function waitForEnabledSendButton(
   let button: HTMLButtonElement | null = null;
   await vi.waitFor(() => {
     button = root.querySelector<HTMLButtonElement>(
-      "button.agent-thread-card__send",
+      "button.agent-composer__send",
     );
     expect(button).not.toBeNull();
     expect(button!.disabled).toBe(false);
@@ -271,7 +285,7 @@ async function waitForEnabledSendButton(
 }
 
 async function seedRenderableMessages(
-  _typeKey: "deepseek-harness" | "codex" | "claude" | "gemini" | "hermes" | "openclaw",
+  _typeKey: "dsh" | "codex" | "claudecode" | "hermes" | "opencode",
   threadId: string,
   messages: ChatMessage[],
 ): Promise<void> {
@@ -387,7 +401,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     const parsed = parseAgentThreadCardMarkdown({ attrs: markdown }).attrs;
     expect(parsed.title).toBe("");
     expect(parsed.fullscreen).toBe(true);
-    expect(parsed.inputImages).toEqual([{
+    expect(parsed.inputAttachments).toEqual([{
       path: "/tmp/pasted.png",
       mimeType: "image/png",
       name: "pasted.png",
@@ -524,7 +538,7 @@ describe("AgentThreadCard NodeView streaming", () => {
       true,
     );
     useAgentSessionStore.setState(useAgentSessionStore.getInitialState(), true);
-    agentAccessState.config = { entries: [] };
+    agentAccessState.config = { version: 1, entries: [] };
   });
 
   afterEach(() => {
@@ -555,7 +569,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "DOM Flow",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -567,7 +581,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     expect(card).not.toBeNull();
 
     const store = useChatStore.getState();
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     dispatchChunk(store, { kind: "stream_start", thread_id: threadId });
     dispatchChunk(store, {
       kind: "text",
@@ -922,7 +936,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
     const threadId = "thread-card-conversation-run-source";
     const instance = useAgentConversationStore.getState().createInstance({
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       title: "Conversation Run Source",
       threadId,
       source: { kind: "thread-card" },
@@ -931,7 +945,7 @@ describe("AgentThreadCard NodeView streaming", () => {
       kind: "stream_start",
       thread_id: threadId,
       run_id: "run-conversation-source",
-      agent_type: "deepseek-harness",
+      agent_type: "dsh",
     });
 
     const host = document.createElement("div");
@@ -949,7 +963,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: instance.instanceId,
               threadId,
               title: "Conversation Run Source",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -986,7 +1000,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     };
 
     useChatStore.setState((state) => ({
-      threadTypes: { ...state.threadTypes, [threadId]: "deepseek-harness" },
+      threadTypes: { ...state.threadTypes, [threadId]: "dsh" },
       threadStates: {
         ...state.threadStates,
         [threadId]: {
@@ -1002,7 +1016,7 @@ describe("AgentThreadCard NodeView streaming", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, [
+    await seedRenderableMessages("dsh", threadId, [
       firstMessage,
       streamingMessage,
     ]);
@@ -1018,7 +1032,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Incremental",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -1048,7 +1062,7 @@ describe("AgentThreadCard NodeView streaming", () => {
         },
       };
     });
-    await seedRenderableMessages("deepseek-harness", threadId, patchedMessages);
+    await seedRenderableMessages("dsh", threadId, patchedMessages);
 
     await flushAnimationFrame();
 
@@ -1071,7 +1085,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     const content = `${"A".repeat(ASSISTANT_MESSAGE_DISPLAY_MAX_CHARS + 20)}${tail}`;
 
     useChatStore.setState((state) => ({
-      threadTypes: { ...state.threadTypes, [threadId]: "deepseek-harness" },
+      threadTypes: { ...state.threadTypes, [threadId]: "dsh" },
       threadStates: {
         ...state.threadStates,
         [threadId]: {
@@ -1087,7 +1101,7 @@ describe("AgentThreadCard NodeView streaming", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, [
+    await seedRenderableMessages("dsh", threadId, [
       {
         id: "assistant-large",
         role: "assistant",
@@ -1107,7 +1121,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Display Budget",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -1145,7 +1159,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Editable title",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -1159,7 +1173,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     expect(title).not.toBeNull();
 
     const store = useChatStore.getState();
-    store.bindThreadType(threadId, "deepseek-harness");
+    store.bindThreadType(threadId, "dsh");
     dispatchChunk(store, { kind: "stream_start", thread_id: threadId });
     dispatchChunk(store, {
       kind: "text",
@@ -1210,7 +1224,7 @@ describe("AgentThreadCard NodeView streaming", () => {
       "@features/agent/thread-card/runtime/thread-card-conversation"
     );
     const instance = useAgentConversationStore.getState().createInstance({
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       title: "User renamed title",
       threadId: "thread-existing-title",
       source: { kind: "thread-card" },
@@ -1218,7 +1232,7 @@ describe("AgentThreadCard NodeView streaming", () => {
 
     const result = await upsertAgentThreadCardConversationInstance({
       instanceId: instance.instanceId,
-      agentType: "deepseek-harness",
+      agentType: "dsh",
       title: "Prompt generated title",
       threadId: "thread-existing-title",
       source: { kind: "thread-card" },
@@ -1305,7 +1319,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Submit Flow",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -1327,7 +1341,7 @@ describe("AgentThreadCard NodeView streaming", () => {
       threadId,
       expect.objectContaining({
         content: "write a short answer",
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         runtimeConfig: expect.objectContaining({
           deepseekHarness: expect.any(Object),
         }),
@@ -1378,7 +1392,7 @@ describe("AgentThreadCard NodeView streaming", () => {
           attrs: {
             threadId: "thread-awaited-initialization",
             title: "Awaited initialization",
-            typeKey: "deepseek-harness",
+            typeKey: "dsh",
             collapsed: false,
           },
         }],
@@ -1538,7 +1552,7 @@ describe("AgentThreadCard NodeView streaming", () => {
           attrs: {
             threadId: null,
             title: "Failed initialization",
-            typeKey: "deepseek-harness",
+            typeKey: "dsh",
             collapsed: false,
           },
         }],
@@ -1567,20 +1581,21 @@ describe("AgentThreadCard NodeView streaming", () => {
     editor = new Editor({
       element: host, extensions: [StarterKit, AgentThreadCard],
       content: { type: "doc", content: [{ type: "agentThreadCard", attrs: {
-        threadId: "thread-rejected-send", typeKey: "deepseek-harness", collapsed: false,
-        inputDraft: "please review", inputImages: images,
+        threadId: "thread-rejected-send", typeKey: "dsh", collapsed: false,
+        inputDraft: "please review", inputAttachments: images,
       } }] },
     });
     const input = getComposerInput(host);
+    const draftBeforeSend = getComposerValue(input);
     (await waitForEnabledSendButton(host)).click();
     await vi.waitFor(() => expect(toastMock.error).toHaveBeenCalledWith("backend rejected request"));
-    expect(getComposerValue(input)).toBe("please review");
-    expect(editor.getJSON().content?.[0]?.attrs?.inputImages).toEqual(images);
-    expect(host.querySelector<HTMLButtonElement>(".agent-thread-card__composer-image-remove")?.disabled).toBe(false);
-    expect(agent.deleteCachedImage).not.toHaveBeenCalled();
+    expect(getComposerValue(input)).toBe(draftBeforeSend);
+    expect(editor.getJSON().content?.[0]?.attrs?.inputAttachments).toEqual(images);
+    expect(host.querySelector(".agent-composer__attachment-token-label")?.textContent).toBe("retry.pdf");
+    expect(agent.deleteCachedAttachment).not.toHaveBeenCalled();
     (await waitForEnabledSendButton(host)).click();
     await vi.waitFor(() => expect(getComposerValue(input)).toBe(""));
-    expect(editor.getJSON().content?.[0]?.attrs?.inputImages).toEqual([]);
+    expect(editor.getJSON().content?.[0]?.attrs?.inputAttachments).toEqual([]);
   });
 
   it("persists short Thread Card composer drafts in node attrs", async () => {
@@ -1603,7 +1618,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-draft",
               title: "Draft",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -1647,7 +1662,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-long-draft",
               title: "Long Draft",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               inputDraft: "short",
             },
@@ -1690,7 +1705,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Clear Draft",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               inputDraft: "send me",
             },
@@ -1724,12 +1739,13 @@ describe("AgentThreadCard NodeView streaming", () => {
       path: "D:\\workspace\\main",
     };
     agentAccessState.config = {
+      version: 1,
       // defaults.folders 里的每个 folder 必须在 entries 里有对应的
       // enabled && !missing 授权条目, 否则 resolveAuthorizedDefaultFiles
       // 会把它收窄掉 (防越权)。
       entries: [
-        { id: "e-main", kind: "folder", path: "D:\\workspace\\main", name: "main", enabled: true, missing: false },
-        { id: "e-extra", kind: "folder", path: "D:\\workspace\\extra", name: "extra", enabled: true, missing: false },
+        { id: "e-main", kind: "folder", path: "D:\\workspace\\main", name: "main", enabled: true, missing: false, addedAt: 0, updatedAt: 0 },
+        { id: "e-extra", kind: "folder", path: "D:\\workspace\\extra", name: "extra", enabled: true, missing: false, addedAt: 0, updatedAt: 0 },
       ],
       defaults: {
         files: {
@@ -1779,6 +1795,7 @@ describe("AgentThreadCard NodeView streaming", () => {
         content: "check workspace",
         agentType: "codex",
         runtimeConfig: {
+          notebookId: "nb-current",
           codex: expect.objectContaining({
             cwd: "D:\\workspace\\main",
             workspacePaths: ["D:\\workspace\\extra"],
@@ -2019,7 +2036,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Collapsed History",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: true,
             },
           },
@@ -2072,7 +2089,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Cached",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -2083,7 +2100,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     await flushPromises();
     await flushAnimationFrame();
 
-    await seedRenderableMessages("deepseek-harness", threadId, [
+    await seedRenderableMessages("dsh", threadId, [
       {
         id: "assistant-cached",
         role: "assistant",
@@ -2166,7 +2183,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Skeleton History",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -2238,7 +2255,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Fullscreen Skeleton",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: true,
             },
           },
@@ -2330,7 +2347,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Viewport History",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -2384,7 +2401,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Fullscreen History",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: true,
             },
           },
@@ -2425,7 +2442,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-fullscreen-persist",
               threadId: "thread-fullscreen-persist",
               title: "Fullscreen Persist",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: false,
             },
@@ -2457,7 +2474,7 @@ describe("AgentThreadCard NodeView streaming", () => {
 
     editor = new Editor({
       element: host,
-      extensions: [StarterKit, AgentThreadCard],
+      extensions: [StarterKit, AgentThreadCard.configure({ workspaceHost: "browser-column" })],
       content: {
         type: "doc",
         content: [
@@ -2467,7 +2484,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-browser-column-fullscreen",
               threadId: "thread-browser-column-fullscreen",
               title: "Browser Column conversation",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: false,
             },
@@ -2515,7 +2532,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-work-column-fullscreen",
               threadId: "thread-work-column-fullscreen",
               title: "Work Column conversation",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: false,
             },
@@ -2572,7 +2589,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-fullscreen-first",
               threadId: "thread-fullscreen-first",
               title: "First Fullscreen",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: true,
             },
@@ -2583,7 +2600,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-fullscreen-second",
               threadId: "thread-fullscreen-second",
               title: "Second Fullscreen",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: true,
             },
@@ -2627,11 +2644,53 @@ describe("AgentThreadCard NodeView streaming", () => {
     expect(editor.state.doc.child(1).attrs.fullscreen).toBe(true);
   });
 
+  it("keeps a persisted fullscreen card inline in the browser column", async () => {
+    const { AgentThreadCard } =
+      await import("@features/agent/thread-card");
+    const workspaceHost = document.createElement("section");
+    workspaceHost.dataset.workspaceHost = "browser-column";
+    const host = document.createElement("div");
+    workspaceHost.append(host);
+    document.body.append(workspaceHost);
+
+    editor = new Editor({
+      element: host,
+      extensions: [StarterKit, AgentThreadCard.configure({ workspaceHost: "browser-column" })],
+      content: {
+        type: "doc",
+        content: [
+          {
+            type: "agentThreadCard",
+            attrs: {
+              instanceId: "instance-browser-column-restore",
+              threadId: "thread-browser-column-restore",
+              title: "Note conversation",
+              typeKey: "dsh",
+              collapsed: false,
+              fullscreen: true,
+            },
+          },
+        ],
+      },
+    });
+
+    await flushPromises();
+    await flushAnimationFrame();
+
+    const card = host.querySelector<HTMLElement>(".agent-thread-card");
+    // A secondary browser-column copy must not duplicate the conversation in
+    // fullscreen and hide the surrounding note content.
+    expect(card?.classList.contains("agent-thread-card--fullscreen")).toBe(false);
+    expect(host.querySelector(".agent-thread-card--restoring-fullscreen")).toBeNull();
+    // The persisted marker stays untouched so the primary surface can restore it.
+    expect(editor.state.doc.firstChild?.attrs.fullscreen).toBe(true);
+  });
+
   it("defaults cached messages to the bottom after restoring fullscreen", async () => {
     const { AgentThreadCard } =
       await import("@features/agent/thread-card");
     const threadId = "thread-restored-fullscreen-bottom";
-    await seedRenderableMessages("deepseek-harness", threadId, [
+    await seedRenderableMessages("dsh", threadId, [
       {
         id: "cached-assistant-message",
         role: "assistant",
@@ -2654,7 +2713,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-restored-fullscreen-bottom",
               threadId,
               title: "Restored Fullscreen Bottom",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: true,
             },
@@ -2693,7 +2752,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-legacy-fullscreen-restore",
               title: "Legacy Fullscreen Restore",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: true,
             },
@@ -2734,7 +2793,7 @@ describe("AgentThreadCard NodeView streaming", () => {
     });
 
     const threadId = "thread-stale-restore-frame";
-    await seedRenderableMessages("deepseek-harness", threadId, [
+    await seedRenderableMessages("dsh", threadId, [
       {
         id: "stale-frame-message",
         role: "assistant",
@@ -2756,7 +2815,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-stale-restore-frame",
               threadId,
               title: "Stale Restore Frame",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: true,
             },
@@ -2807,7 +2866,7 @@ describe("AgentThreadCard NodeView streaming", () => {
               instanceId: "instance-before-document-switch",
               threadId: "thread-before-document-switch",
               title: "Before Document Switch",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
               fullscreen: false,
             },
@@ -2826,7 +2885,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             instanceId: "instance-after-document-switch",
             threadId: "thread-after-document-switch",
             title: "After Document Switch",
-            typeKey: "deepseek-harness",
+            typeKey: "dsh",
             collapsed: false,
             fullscreen: true,
           },
@@ -2871,7 +2930,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId,
               title: "Fullscreen Selection",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -2918,7 +2977,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-fullscreen-input-focus",
               title: "Fullscreen Input Focus",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -2933,8 +2992,8 @@ describe("AgentThreadCard NodeView streaming", () => {
 
     const input = getComposerInput(host);
     const row = input.parentElement;
-    expect(row?.classList.contains("agent-thread-card__composer-input-row")).toBe(true);
-    expect(input.closest(".agent-thread-card__composer")?.classList.contains("agent-composer--expanded")).toBe(true);
+    expect(row?.classList.contains("agent-composer__input-row")).toBe(true);
+    expect(input.closest(".agent-composer")?.classList.contains("agent-composer--expanded")).toBe(true);
 
     input.blur();
     row?.dispatchEvent(
@@ -2952,7 +3011,7 @@ describe("AgentThreadCard NodeView streaming", () => {
       .querySelector<HTMLButtonElement>(".agent-thread-card__fullscreen")
       ?.click();
     await flushAnimationFrame();
-    expect(input.closest(".agent-thread-card__composer")?.classList.contains("agent-composer--expanded")).toBe(false);
+    expect(input.closest(".agent-composer")?.classList.contains("agent-composer--expanded")).toBe(false);
   });
 
   it("does not refocus the editor when clicking non-interactive card content", async () => {
@@ -2976,7 +3035,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-click-focus",
               title: "Click Focus",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3018,7 +3077,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-event-boundary",
               title: "Event Boundary",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3061,7 +3120,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-focus-deselect",
               title: "Focus Deselect",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3117,7 +3176,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-focus-first",
               title: "First",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3130,7 +3189,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-focus-second",
               title: "Second",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3180,7 +3239,7 @@ describe("AgentThreadCard NodeView streaming", () => {
             attrs: {
               threadId: "thread-card-outside-blur",
               title: "Outside Blur",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3416,7 +3475,7 @@ describe("AgentThreadCard input history navigation", () => {
 
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
     useChatStore.setState(useChatStore.getInitialState(), true);
-    agentAccessState.config = { entries: [] };
+    agentAccessState.config = { version: 1, entries: [] };
   });
 
   afterEach(() => {
@@ -3460,7 +3519,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Empty",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3495,7 +3554,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "History",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3537,7 +3596,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -3573,7 +3632,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Draft",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3603,7 +3662,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -3641,7 +3700,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Draft not overwritten",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3671,7 +3730,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -3726,7 +3785,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Down idle",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3755,7 +3814,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -3784,7 +3843,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Typing",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3814,7 +3873,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -3850,7 +3909,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Caret boundaries",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3880,7 +3939,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -3921,7 +3980,7 @@ describe("AgentThreadCard input history navigation", () => {
             attrs: {
               threadId,
               title: "Unmodified",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -3951,7 +4010,7 @@ describe("AgentThreadCard input history navigation", () => {
         },
       },
     }));
-    await seedRenderableMessages("deepseek-harness", threadId, messages);
+    await seedRenderableMessages("dsh", threadId, messages);
     await flushAnimationFrame();
 
     const input = getComposerInput(host);
@@ -4005,7 +4064,7 @@ describe("AgentThreadCard input latency optimizations", () => {
 
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
     useChatStore.setState(useChatStore.getInitialState(), true);
-    agentAccessState.config = { entries: [] };
+    agentAccessState.config = { version: 1, entries: [] };
   });
 
   afterEach(() => {
@@ -4038,7 +4097,7 @@ describe("AgentThreadCard input latency optimizations", () => {
             attrs: {
               threadId,
               title: "Lite",
-              typeKey: "deepseek-harness",
+              typeKey: "dsh",
               collapsed: false,
             },
           },
@@ -4155,7 +4214,7 @@ describe("AgentThreadCard composer during agent run", () => {
 
     const { useChatStore } = await import("@features/agent/store/agent-session-test-facade");
     useChatStore.setState(useChatStore.getInitialState(), true);
-    agentAccessState.config = { entries: [] };
+    agentAccessState.config = { version: 1, entries: [] };
   });
 
   afterEach(() => {
@@ -4165,7 +4224,7 @@ describe("AgentThreadCard composer during agent run", () => {
     vi.useRealTimers();
   });
 
-  it.each(["deepseek-harness", "pi"] as const)("queues a message while %s is running", async (agentType) => {
+  it.each(["dsh", "pi"] as const)("queues a message while %s is running", async (agentType) => {
     const { AgentThreadCard } =
       await import("@features/agent/thread-card");
     const { useAgentSessionStore } = await import(
diff --git a/app/flowix-web/features/agent/thread-card/badge-hover-card.test.ts b/app/flowix-web/features/agent/thread-card/badge-hover-card.test.ts
index 3ec2bd05f..93938a79d 100644
--- a/app/flowix-web/features/agent/thread-card/badge-hover-card.test.ts
+++ b/app/flowix-web/features/agent/thread-card/badge-hover-card.test.ts
@@ -58,7 +58,7 @@ describe("BadgeHoverCard", () => {
     await act(async () => {
       root.render(
         createElement(BadgeHoverCard, {
-          agentType: "deepseek-harness",
+          agentType: "dsh",
           sessionId: "provider-session-1",
           model: "deepseek-chat",
           usage: {
@@ -95,7 +95,7 @@ describe("BadgeHoverCard", () => {
     await act(async () => {
       root.render(
         createElement(BadgeHoverCard, {
-          agentType: "claude",
+          agentType: "claudecode",
           model: "gpt-5",
           usage: { input_tokens: 10, output_tokens: 2 },
         }),
diff --git a/app/flowix-web/features/agent/thread-card/badge-hover-card.tsx b/app/flowix-web/features/agent/thread-card/badge-hover-card.tsx
index 96ea36092..07de254d8 100644
--- a/app/flowix-web/features/agent/thread-card/badge-hover-card.tsx
+++ b/app/flowix-web/features/agent/thread-card/badge-hover-card.tsx
@@ -97,7 +97,7 @@ function percentageFromRate(rate: number | undefined): string {
 }
 
 /**
- * Agent Thread Card hover Agent 类型徽章弹出的卡片。
+ * Agent conversation identity badge 的运行信息卡片。
  *
  * 通用 metadata 协议字段均通过 props 传入,组件本身不读取 store。
  *
@@ -196,7 +196,7 @@ export function BadgeHoverCard({
       <HoverCardTrigger asChild>
         <span
           aria-hidden="true"
-          className="agent-thread-card__badge-hover-trigger"
+          className="agent-conversation-identity__badge-trigger"
           onPointerEnter={requestRuntimeInfo}
         />
       </HoverCardTrigger>
diff --git a/app/flowix-web/features/agent/thread-card/chrome/badge-chrome-controller.tsx b/app/flowix-web/features/agent/thread-card/chrome/badge-chrome-controller.tsx
index d38a713f6..a52c6f206 100644
--- a/app/flowix-web/features/agent/thread-card/chrome/badge-chrome-controller.tsx
+++ b/app/flowix-web/features/agent/thread-card/chrome/badge-chrome-controller.tsx
@@ -5,8 +5,7 @@ import { getAgentType } from "@/lib/agent-types";
 import { type ThreadState } from "@features/agent/store/thread-runtime-state";
 import { useAgentRuntimeStore } from "@features/agent/store/agent-runtime-store";
 import { normalizeAgentRuntimeStatus } from "@features/agent/runtime/agent-runtime-status";
-import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
 import { BadgeHoverCard } from "@features/agent/thread-card/badge-hover-card";
 import { computeAgentThreadCardBadgeData } from "@features/agent/thread-card/runtime/run-status-presenter";
 import { createRuntimeInfoRequester } from "@features/agent/thread-card/runtime/runtime-info-requester";
@@ -66,13 +65,13 @@ export class AgentThreadCardBadgeChromeController {
     this.badgeIcon.style.setProperty("--agent-icon-src", `url("${type.icon}")`);
     this.badgeIcon.classList.toggle(
       "agent-icon--masked",
-      isThemeAdaptiveAgentIcon(type.key),
+      isThemeAdaptiveAgentIcon(type.id),
     );
     this.badgeIcon.classList.toggle(
       "agent-type-badge__icon--image",
-      !isThemeAdaptiveAgentIcon(type.key),
+      !isThemeAdaptiveAgentIcon(type.id),
     );
-    this.badgeIcon.classList.toggle("agent-icon--pi", type.key === "pi");
+    this.badgeIcon.classList.toggle("agent-icon--pi", type.id === "pi");
     this.badgeName.textContent = type.name;
     this.syncRuntimeState();
     // Conversation instances may hydrate after the NodeView is mounted. Repaint
@@ -85,7 +84,7 @@ export class AgentThreadCardBadgeChromeController {
     const type = getAgentType(this.getTypeKey());
     const runtime = useAgentRuntimeStore.getState();
     const status = normalizeAgentRuntimeStatus(
-      runtime.statusByType[type.key],
+      runtime.statusByType[type.id],
       runtime.isChecking,
     );
     const unavailable = status.state === "not-installed" || status.state === "not-ready";
@@ -170,14 +169,14 @@ export class AgentThreadCardBadgeChromeController {
       this.getSessionId() ??
       (threadId ? getResolvedExternalSessionId(threadId) : null);
     const typeKey = this.getTypeKey();
-    const piCodeMode = useAgentAccessStore.getState().config.defaults
-      ?.runtime?.pi?.piCodeMode ?? false;
+    const preferredPiMode = useAgentDataStore.getState().agents.pi.user.mode;
+    const piCodeMode = preferredPiMode === "code";
     const { runId, model, usage } =
       computeAgentThreadCardBadgeData({
         threadState: this.getThreadState(),
         // Phase 4 (2026-08-02): 真源是 session-store.sessionMeta.settings.
         codexModel:
-          useAgentSessionStore.getState().sessionMeta.settings.agentCodexModel,
+          useAgentDataStore.getState().agents.codex.user.model?.id ?? "inherit",
         typeKey: this.getTypeKey(),
       });
     this.hoverCardRoot.render(
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-add-menu-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-add-menu-controller.ts
index 550b4bff1..e762706f2 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-add-menu-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-add-menu-controller.ts
@@ -1,29 +1,46 @@
 import type { I18nKey } from "@/lib/i18n";
 import type { NotePickerController } from "@features/agent/thread-card/note/note-picker-controller";
-import type { ComposerImageController } from "./composer-image-controller";
-import { COMPOSER_ATTACHMENT_ACCEPT } from "./composer-image-controller";
+import type { ComposerAttachmentController } from "./composer-attachment-controller";
+import { COMPOSER_ATTACHMENT_ACCEPT } from "./composer-attachment-controller";
 
 export interface ComposerAddMenuControllerOptions {
   trigger: HTMLButtonElement;
   popover: HTMLDivElement;
   notePopover: HTMLDivElement;
+  settingsPopover?: HTMLDivElement;
   notePicker: NotePickerController;
-  images: ComposerImageController;
+  attachments: ComposerAttachmentController;
   t: (key: I18nKey) => string;
   isDestroyed: () => boolean;
   openNotebookAgentSettings: () => void;
+  settings?: readonly {
+    label: I18nKey;
+    popupRole?: "menu" | "dialog";
+    onHover: (anchor: HTMLButtonElement) => void;
+  }[];
+  showSettings?: () => boolean;
+  closeSettingsSubmenu?: (anchor?: HTMLButtonElement) => void;
+  consumeOutsidePointer?: (event: PointerEvent) => void;
 }
 
 export class ComposerAddMenuController {
   private open = false;
   private disposed = false;
   private noteItem: HTMLButtonElement | null = null;
+  private activeSettingsItem: HTMLButtonElement | null = null;
+  private suppressSettingsFocusOpen = false;
   private submenuCloseTimer: ReturnType<typeof setTimeout> | null = null;
+  private settingsCloseTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(private readonly options: ComposerAddMenuControllerOptions) {
     options.trigger.addEventListener("click", this.handleTriggerClick);
     options.notePopover.addEventListener("pointerenter", this.cancelSubmenuClose);
     options.notePopover.addEventListener("pointerleave", this.handleSubmenuBoundaryLeave);
+    options.popover.addEventListener("pointerleave", this.handleSettingsBoundaryLeave);
+    options.popover.addEventListener("keydown", this.handleMenuKeydown);
+    options.settingsPopover?.addEventListener("pointerenter", this.cancelSettingsClose);
+    options.settingsPopover?.addEventListener("pointerleave", this.handleSettingsBoundaryLeave);
+    options.settingsPopover?.addEventListener("keydown", this.handleSettingsKeydown);
   }
 
   close(): void { this.setOpen(false); }
@@ -32,38 +49,68 @@ export class ComposerAddMenuController {
     if (this.disposed) return;
     this.disposed = true;
     this.cancelSubmenuClose();
+    this.cancelSettingsClose();
     this.setOpen(false);
     this.options.trigger.removeEventListener("click", this.handleTriggerClick);
     this.options.notePopover.removeEventListener("pointerenter", this.cancelSubmenuClose);
     this.options.notePopover.removeEventListener("pointerleave", this.handleSubmenuBoundaryLeave);
+    this.options.popover.removeEventListener("pointerleave", this.handleSettingsBoundaryLeave);
+    this.options.popover.removeEventListener("keydown", this.handleMenuKeydown);
+    this.options.settingsPopover?.removeEventListener("pointerenter", this.cancelSettingsClose);
+    this.options.settingsPopover?.removeEventListener("pointerleave", this.handleSettingsBoundaryLeave);
+    this.options.settingsPopover?.removeEventListener("keydown", this.handleSettingsKeydown);
     this.options.popover.remove();
   }
 
   private readonly handleTriggerClick = (event: MouseEvent): void => {
     event.preventDefault();
     event.stopPropagation();
-    this.setOpen(!this.open);
+    const shouldOpen = !this.open;
+    this.setOpen(shouldOpen);
+    if (shouldOpen && event.detail === 0) {
+      this.options.popover.querySelector<HTMLButtonElement>("[role='menuitem']")?.focus();
+    }
   };
 
   private setOpen(open: boolean): void {
     this.open = open;
     this.options.popover.hidden = !open;
     this.options.trigger.setAttribute("aria-expanded", String(open));
-    this.options.trigger.classList.toggle("agent-thread-card__composer-add-button--open", open);
+    this.options.trigger.classList.toggle("agent-composer__add-button--open", open);
     if (open) {
       this.render();
       this.position();
       document.addEventListener("pointerdown", this.handleOutsidePointer, true);
     } else {
+      this.cancelSettingsClose();
       this.noteItem = null;
       this.options.notePicker.setOpen(false);
+      this.options.closeSettingsSubmenu?.(this.activeSettingsItem ?? undefined);
+      this.activeSettingsItem = null;
       document.removeEventListener("pointerdown", this.handleOutsidePointer, true);
     }
   }
 
   private readonly handleOutsidePointer = (event: PointerEvent): void => {
     const target = event.target as Node | null;
-    if (target && (this.options.popover.contains(target) || this.options.notePopover.contains(target) || this.options.trigger.contains(target))) return;
+    if (
+      target
+      && (
+        this.options.popover.contains(target)
+        || this.options.notePopover.contains(target)
+        || this.options.settingsPopover?.contains(target)
+        || this.options.trigger.contains(target)
+      )
+    ) return;
+    if (
+      this.activeSettingsItem
+      && this.options.settingsPopover
+      && !this.options.settingsPopover.hidden
+    ) {
+      // The settings controller also listens for outside pointers. Closing the
+      // parent removes that listener, so consume editor clicks here first.
+      this.options.consumeOutsidePointer?.(event);
+    }
     this.setOpen(false);
   };
 
@@ -71,11 +118,21 @@ export class ComposerAddMenuController {
     this.noteItem?.removeEventListener("pointerleave", this.handleSubmenuBoundaryLeave);
     const note = this.createItem(this.options.t("editor.threadCard.addNote"), true);
     const attachment = this.createItem(this.options.t("editor.threadCard.addAttachment"), false);
-    const items = [note, attachment];
+    const items: HTMLElement[] = [note, attachment];
+    const settings = this.options.showSettings?.() === false
+      ? []
+      : (this.options.settings ?? []);
+    if (settings.length > 0) {
+      items.push(this.createSeparator());
+      settings.forEach(({ label, onHover, popupRole }) => {
+        items.push(this.createSettingsItem(this.options.t(label), onHover, popupRole));
+      });
+    }
     const projectAiSettings = this.createItem(this.options.t("editor.threadCard.projectAiSettings"), false, () => {
       this.setOpen(false);
       this.options.openNotebookAgentSettings();
     });
+    if (settings.length > 0) items.push(this.createSeparator());
     items.push(projectAiSettings);
     this.options.popover.replaceChildren(...items);
     this.noteItem = note;
@@ -88,7 +145,7 @@ export class ComposerAddMenuController {
     item.type = "button";
     // Reuse the permission/model dropdown item contract so copy and controls
     // keep exactly the same typography, spacing and hover treatment.
-    item.className = "agent-thread-card__codex-settings-item agent-thread-card__composer-add-item";
+    item.className = "agent-thread-card__codex-settings-item agent-composer__add-item";
     item.setAttribute("role", "menuitem");
     item.textContent = label;
     if (isNote) {
@@ -116,6 +173,117 @@ export class ComposerAddMenuController {
     return item;
   }
 
+  private createSettingsItem(
+    label: string,
+    onHover: (anchor: HTMLButtonElement) => void,
+    popupRole: "menu" | "dialog" = "menu",
+  ): HTMLButtonElement {
+    const item = document.createElement("button");
+    item.type = "button";
+    item.className = "agent-thread-card__codex-settings-item agent-composer__add-item";
+    item.classList.add("agent-composer__add-setting-item");
+    item.setAttribute("role", "menuitem");
+    item.setAttribute("aria-haspopup", popupRole);
+    item.setAttribute("aria-expanded", "false");
+    item.textContent = label;
+    item.append(this.chevron());
+    item.addEventListener("pointerenter", () => {
+      this.cancelSettingsClose();
+      this.activateSettingsItem(item);
+      onHover(item);
+    });
+    item.addEventListener("focus", () => {
+      if (this.suppressSettingsFocusOpen) return;
+      this.cancelSettingsClose();
+      this.activateSettingsItem(item);
+      onHover(item);
+    });
+    item.addEventListener("keydown", (event) => {
+      if (event.key !== "ArrowRight") return;
+      if (!this.options.settingsPopover || this.options.settingsPopover.hidden) return;
+      const firstSubmenuItem = this.options.settingsPopover?.querySelector<HTMLButtonElement>(
+        "button:not([disabled])",
+      );
+      if (!firstSubmenuItem) return;
+      event.preventDefault();
+      firstSubmenuItem.focus();
+    });
+    item.addEventListener("pointerleave", this.handleSettingsBoundaryLeave);
+    return item;
+  }
+
+  syncSettingsSubmenuState(open: boolean, anchor: HTMLButtonElement | null): void {
+    const activeItem = this.activeSettingsItem;
+    if (!activeItem) return;
+    if (open && anchor !== activeItem) {
+      activeItem.setAttribute("aria-expanded", "false");
+      this.activeSettingsItem = null;
+      return;
+    }
+    if (!open && anchor && anchor !== activeItem) return;
+    const focusWasInSubmenu =
+      !open && Boolean(this.options.settingsPopover?.contains(document.activeElement));
+    activeItem.setAttribute("aria-expanded", String(open));
+    if (!open) {
+      this.activeSettingsItem = null;
+      if (focusWasInSubmenu) this.focusSettingsItemWithoutOpening(activeItem);
+    }
+  }
+
+  private activateSettingsItem(item: HTMLButtonElement): void {
+    if (this.activeSettingsItem === item) return;
+    this.activeSettingsItem?.setAttribute("aria-expanded", "false");
+    this.activeSettingsItem = item;
+    item.setAttribute("aria-expanded", "false");
+  }
+
+  private focusSettingsItemWithoutOpening(item: HTMLButtonElement | null): void {
+    if (!item || !item.isConnected || document.activeElement === item) return;
+    this.suppressSettingsFocusOpen = true;
+    item.focus();
+    this.suppressSettingsFocusOpen = false;
+  }
+
+  private readonly handleMenuKeydown = (event: KeyboardEvent): void => {
+    if (event.key !== "Escape") return;
+    event.preventDefault();
+    if (
+      this.activeSettingsItem
+      && this.options.settingsPopover
+      && !this.options.settingsPopover.hidden
+    ) {
+      const activeItem = this.activeSettingsItem;
+      this.options.closeSettingsSubmenu?.(activeItem ?? undefined);
+      this.focusSettingsItemWithoutOpening(activeItem);
+      return;
+    }
+    this.setOpen(false);
+    this.options.trigger.focus();
+  };
+
+  private readonly handleSettingsKeydown = (event: KeyboardEvent): void => {
+    if (event.key !== "Escape" && event.key !== "ArrowLeft") return;
+    if (
+      event.key === "ArrowLeft"
+      && !(event.target instanceof Element && event.target.closest("[role='menuitem']"))
+    ) return;
+    const activeItem = this.activeSettingsItem;
+    if (!activeItem) return;
+    event.preventDefault();
+    event.stopPropagation();
+    if (event.key === "Escape") {
+      this.options.closeSettingsSubmenu?.(activeItem ?? undefined);
+    }
+    this.focusSettingsItemWithoutOpening(activeItem);
+  };
+
+  private createSeparator(): HTMLDivElement {
+    const separator = document.createElement("div");
+    separator.className = "agent-composer__add-separator";
+    separator.setAttribute("role", "separator");
+    return separator;
+  }
+
   private readonly handleSubmenuBoundaryLeave = (event: PointerEvent): void => {
     const next = event.relatedTarget as Node | null;
     if (next && (this.noteItem?.contains(next) || this.options.notePopover.contains(next))) return;
@@ -135,14 +303,42 @@ export class ComposerAddMenuController {
     }
   };
 
+  private readonly handleSettingsBoundaryLeave = (event: PointerEvent): void => {
+    const next = event.relatedTarget as Node | null;
+    const current = event.currentTarget as Node | null;
+    if (next && current?.contains(next)) return;
+    if (next && this.options.settingsPopover?.contains(next)) return;
+    if (next instanceof Element && this.options.popover.contains(next)) {
+      if (next.closest(".agent-composer__add-setting-item")) return;
+    }
+    this.cancelSettingsClose();
+    this.settingsCloseTimer = setTimeout(() => {
+      this.settingsCloseTimer = null;
+      this.options.closeSettingsSubmenu?.(this.activeSettingsItem ?? undefined);
+      this.activeSettingsItem = null;
+    }, 100);
+  };
+
+  private readonly cancelSettingsClose = (): void => {
+    if (this.settingsCloseTimer !== null) {
+      clearTimeout(this.settingsCloseTimer);
+      this.settingsCloseTimer = null;
+    }
+  };
+
   private pickAttachments(): void {
+    this.options.attachments.captureInsertionAnchor();
     const input = document.createElement("input");
     input.type = "file";
     input.accept = COMPOSER_ATTACHMENT_ACCEPT;
     input.multiple = true;
     input.hidden = true;
     input.addEventListener("change", () => {
-      this.options.images.addFiles(Array.from(input.files ?? []));
+      this.options.attachments.addFiles(Array.from(input.files ?? []));
+      input.remove();
+    }, { once: true });
+    input.addEventListener("cancel", () => {
+      this.options.attachments.cancelInsertionAnchor();
       input.remove();
     }, { once: true });
     document.body.append(input);
@@ -159,9 +355,10 @@ export class ComposerAddMenuController {
     const width = popoverRect.width || 168;
     const height = popoverRect.height || 80;
     const left = Math.max(padding, Math.min(rect.left, window.innerWidth - width - padding));
-    const top = rect.top >= height + offset + padding
+    const preferredTop = rect.top >= height + offset + padding
       ? rect.top - height - offset
       : rect.bottom + offset;
+    const top = Math.max(padding, Math.min(preferredTop, window.innerHeight - height - padding));
     Object.assign(this.options.popover.style, { left: `${left}px`, top: `${top}px` });
   }
 
@@ -169,7 +366,7 @@ export class ComposerAddMenuController {
     const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
     svg.setAttribute("viewBox", "0 0 24 24");
     svg.setAttribute("aria-hidden", "true");
-    svg.classList.add("agent-thread-card__composer-add-chevron");
+    svg.classList.add("agent-composer__add-chevron");
     const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
     path.setAttribute("d", "m9 6 6 6-6 6");
     path.setAttribute("fill", "none");
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-compat.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-compat.ts
new file mode 100644
index 000000000..e90fa7dde
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-compat.ts
@@ -0,0 +1,14 @@
+/**
+ * Persisted attachment names retained for old Thread Card drafts and HTML.
+ * Keep these aliases at the serialization boundary; editor code uses
+ * attachment terminology throughout.
+ */
+export const COMPOSER_ATTACHMENT_NODE_NAME = "composerAttachmentToken";
+
+export const COMPOSER_ATTACHMENT_HTML_ATTRIBUTE = "data-composer-attachment";
+export const LEGACY_COMPOSER_IMAGE_HTML_ATTRIBUTE = "data-composer-image";
+
+export const THREAD_CARD_ATTACHMENTS_ATTRIBUTE = "inputAttachments";
+export const LEGACY_THREAD_CARD_IMAGES_ATTRIBUTE = "inputImages";
+export const THREAD_CARD_ATTACHMENTS_HTML_ATTRIBUTE = "data-input-attachments";
+export const LEGACY_THREAD_CARD_IMAGES_HTML_ATTRIBUTE = "data-input-images";
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-controller.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-controller.test.ts
new file mode 100644
index 000000000..7cf3d075c
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-controller.test.ts
@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ComposerAttachmentDocumentPort } from './composer-attachment-document';
+import { ComposerAttachmentController, type AgentThreadCardInputAttachment } from './composer-attachment-controller';
+
+const mocks = vi.hoisted(() => ({ cacheAttachment: vi.fn(), deleteCachedAttachment: vi.fn(), readCachedAttachment: vi.fn() }));
+vi.mock('@platform/tauri/client', () => ({ agent: mocks }));
+const controllers: ComposerAttachmentController[] = [];
+function setup(initialAttachments: AgentThreadCardInputAttachment[] = []) {
+  const input = document.createElement('div');
+  document.body.append(input);
+  const onChange = vi.fn();
+  const onLimitExceeded = vi.fn();
+  const controller = new ComposerAttachmentController({
+    input, initialAttachments, onChange, onLimitExceeded, onError: vi.fn(), onStateChange: vi.fn(),
+  });
+  const insertAttachmentToken = vi.fn((_attachment: AgentThreadCardInputAttachment, point = { from: 1, to: 1 }) => ({ from: point.from + 1, to: point.from + 1 }));
+  const composer: ComposerAttachmentDocumentPort = {
+    captureAttachmentInsertionAnchor: () => undefined,
+    insertAttachmentToken,
+    removeAttachmentToken: vi.fn(),
+    setAttachmentTokensChanged: vi.fn(),
+    dispose: vi.fn(),
+  };
+  controller.connectDocument(composer);
+  controllers.push(controller);
+  return { controller, input, onChange, onLimitExceeded, insertAttachmentToken };
+}
+beforeEach(() => {
+  mocks.cacheAttachment.mockImplementation(async (_content: string, mimeType: string) => ({ path: `/tmp/${mocks.cacheAttachment.mock.calls.length}`, mimeType, name: 'generated' }));
+  mocks.readCachedAttachment.mockResolvedValue('data:image/png;base64,AQID');
+  mocks.deleteCachedAttachment.mockResolvedValue(true);
+});
+afterEach(() => {
+  controllers.splice(0).forEach((controller) => controller.dispose());
+  document.body.replaceChildren();
+  vi.resetAllMocks();
+});
+
+describe('ComposerAttachmentController', () => {
+  it('pastes an image into the editor and retains the original filename', async () => {
+    const { controller, input, insertAttachmentToken } = setup();
+    const file = new File(['image'], 'photo.png', { type: 'image/png' });
+    const event = new Event('paste', { bubbles: true, cancelable: true });
+    Object.defineProperty(event, 'clipboardData', { value: { items: [{ kind: 'file', type: file.type, getAsFile: () => file }] } });
+    input.dispatchEvent(event);
+    await vi.waitFor(() => expect(controller.hasPending).toBe(false));
+    expect(event.defaultPrevented).toBe(true);
+    expect(insertAttachmentToken).toHaveBeenCalledWith(expect.objectContaining({ name: 'photo.png' }), undefined);
+    expect(controller.readyAttachments[0].name).toBe('photo.png');
+  });
+
+  it('restores image and PDF attachments into the editor without an external preview container', () => {
+    const attachments = [
+      { path: '/tmp/photo.png', mimeType: 'image/png', name: 'photo.png' },
+      { path: '/tmp/report.pdf', mimeType: 'application/pdf', name: 'report.pdf' },
+    ];
+    const { insertAttachmentToken, controller } = setup(attachments);
+    expect(insertAttachmentToken.mock.calls.map(([attachment]) => attachment)).toEqual(attachments);
+    expect(controller.readyAttachments).toEqual(attachments);
+  });
+
+  it('keeps removed attachments available for undo and cleans them when the surface closes', () => {
+    const attachment = { path: '/tmp/report.pdf', mimeType: 'application/pdf', name: 'report.pdf' };
+    const { controller } = setup([attachment]);
+    controller.syncInlineAttachments([]);
+    expect(controller.hasAttachments).toBe(false);
+    expect(mocks.deleteCachedAttachment).not.toHaveBeenCalled();
+    controller.syncInlineAttachments([attachment]);
+    expect(controller.readyAttachments).toEqual([attachment]);
+    controller.syncInlineAttachments([]);
+    controller.dispose();
+    expect(mocks.deleteCachedAttachment).toHaveBeenCalledWith(attachment.path);
+  });
+
+  it('rebuilds attachments from persisted editor nodes even when host metadata is absent', () => {
+    const { controller } = setup();
+    const attachment = { path: '/tmp/report.pdf', mimeType: 'application/pdf', name: 'report.pdf' };
+    controller.syncInlineAttachments([attachment]);
+    expect(controller.readyAttachments).toEqual([attachment]);
+  });
+
+  it('does not delete files belonging to an in-flight submission when its visible draft clears', () => {
+    const attachment = { path: '/tmp/report.pdf', mimeType: 'application/pdf', name: 'report.pdf' };
+    const { controller } = setup([attachment]);
+    controller.setLocked(true);
+    controller.syncInlineAttachments([]);
+    controller.clearAfterSubmit();
+    expect(mocks.deleteCachedAttachment).not.toHaveBeenCalled();
+  });
+
+  it('reserves all queued upload slots and enforces the file size limit', async () => {
+    const { controller, onLimitExceeded } = setup();
+    const files = Array.from({ length: 6 }, (_, index) => new File(['x'], `${index}.pdf`, { type: 'application/pdf' }));
+    controller.addFiles([...files, new File([new Uint8Array(5 * 1024 * 1024 + 1)], 'large.pdf', { type: 'application/pdf' })]);
+    controller.addFiles([files[0]]);
+    await vi.waitFor(() => expect(controller.hasPending).toBe(false));
+    expect(mocks.cacheAttachment).toHaveBeenCalledTimes(5);
+    expect(onLimitExceeded).toHaveBeenCalledWith('count');
+    expect(onLimitExceeded).toHaveBeenCalledWith('size');
+  });
+
+  it('removes missing cached-image metadata and its inline node', async () => {
+    mocks.readCachedAttachment.mockResolvedValue(null);
+    const { controller, onChange } = setup([{ path: '/tmp/missing.png', name: 'missing.png', mimeType: 'image/png' }]);
+    await vi.waitFor(() => expect(controller.hasAttachments).toBe(false));
+    expect(onChange).toHaveBeenCalledWith([]);
+    expect(mocks.deleteCachedAttachment).not.toHaveBeenCalled();
+  });
+});
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-controller.ts
new file mode 100644
index 000000000..94f70219d
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-controller.ts
@@ -0,0 +1,290 @@
+import { agent } from "@platform/tauri/client";
+import type { ComposerInsertionAnchor, ComposerInsertionPoint } from "./composer-insertion-anchor";
+import type { ComposerAttachmentDocumentPort } from "./composer-attachment-document";
+import type { AgentThreadCardInputAttachment } from "./composer-attachment-types";
+
+export type { AgentThreadCardInputAttachment } from "./composer-attachment-types";
+
+const MAX_COMPOSER_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+const MAX_COMPOSER_ATTACHMENT_COUNT = 5;
+
+export const COMPOSER_ATTACHMENT_ACCEPT = [
+  "image/*", ".doc", ".docx", ".pdf", ".xls", ".xlsx", ".ppt", ".pptx",
+].join(",");
+
+const SUPPORTED_ATTACHMENT_MIME_TYPES = new Set([
+  "application/msword",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/pdf",
+  "application/vnd.ms-excel",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/vnd.ms-powerpoint",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+]);
+
+function isSupportedAttachment(file: File): boolean {
+  return Boolean(getAttachmentMimeType(file));
+}
+
+function getAttachmentMimeType(file: File): string | null {
+  const mimeType = file.type.toLowerCase();
+  if (mimeType.startsWith("image/") || SUPPORTED_ATTACHMENT_MIME_TYPES.has(mimeType)) {
+    return mimeType;
+  }
+  const extension = file.name.toLowerCase().split(".").pop();
+  const byExtension: Record<string, string> = {
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    pdf: "application/pdf",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  };
+  return (extension && byExtension[extension]) || null;
+}
+
+function isImageAttachment(file: { mimeType: string }): boolean {
+  return file.mimeType.toLowerCase().startsWith("image/");
+}
+
+export interface ComposerAttachmentControllerOptions {
+  input: HTMLElement;
+  initialAttachments: AgentThreadCardInputAttachment[];
+  onChange: (attachments: AgentThreadCardInputAttachment[]) => void;
+  onStateChange: () => void;
+  onError: (message: string) => void;
+  onLimitExceeded: (kind: "count" | "size") => void;
+}
+
+function readFileAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result ?? ""));
+    reader.onerror = () => reject(reader.error ?? new Error("Failed to read attachment"));
+    reader.readAsDataURL(file);
+  });
+}
+
+export class ComposerAttachmentController {
+  private attachments: AgentThreadCardInputAttachment[];
+  /** Detached tokens stay cached while editor undo/history can restore them. */
+  private readonly detachedAttachments = new Map<string, AgentThreadCardInputAttachment>();
+  private pending = 0;
+  private disposed = false;
+  private locked = false;
+  private readonly submittedPaths = new Set<string>();
+  private insertionAnchor?: ComposerInsertionAnchor;
+  private readonly activeAnchors = new Set<ComposerInsertionAnchor>();
+  private document?: ComposerAttachmentDocumentPort;
+
+  constructor(private readonly options: ComposerAttachmentControllerOptions) {
+    this.attachments = options.initialAttachments.slice(0, MAX_COMPOSER_ATTACHMENT_COUNT);
+    options.input.addEventListener("paste", this.handlePaste);
+    for (const image of this.attachments) {
+      if (isImageAttachment(image)) void this.validateCachedImage(image);
+    }
+  }
+
+  get readyAttachments(): AgentThreadCardInputAttachment[] {
+    return [...this.attachments];
+  }
+
+  get hasAttachments(): boolean {
+    return this.attachments.length > 0;
+  }
+
+  get hasPending(): boolean {
+    return this.pending > 0;
+  }
+
+  connectDocument(document: ComposerAttachmentDocumentPort): void {
+    if (this.disposed) return;
+    this.document?.dispose();
+    this.document = document;
+
+    // Restore persisted attachments into the editor before tracking removals.
+    let position: ComposerInsertionPoint = { from: 1, to: 1 };
+    for (const image of this.attachments) {
+      position = document.insertAttachmentToken(image, position) ?? position;
+    }
+    document.setAttachmentTokensChanged((attachments) => this.syncInlineAttachments(attachments));
+  }
+
+  captureInsertionAnchor(): void {
+    this.cancelInsertionAnchor();
+    this.insertionAnchor = this.document?.captureAttachmentInsertionAnchor();
+  }
+
+  cancelInsertionAnchor(): void {
+    this.insertionAnchor?.dispose();
+    this.insertionAnchor = undefined;
+  }
+
+  syncInlineAttachments(attachments: readonly AgentThreadCardInputAttachment[]): void {
+    if (this.disposed) return;
+    const paths = new Set(attachments.map((attachment) => attachment.path));
+    for (const image of this.attachments) {
+      if (!paths.has(image.path)) this.detachedAttachments.set(image.path, image);
+    }
+    const nextAttachments = [...new Map(attachments.map((attachment) => [attachment.path, attachment])).values()];
+    for (const image of nextAttachments) this.detachedAttachments.delete(image.path);
+
+    const unchanged = nextAttachments.length === this.attachments.length &&
+      nextAttachments.every((image, index) => image.path === this.attachments[index]?.path);
+    if (unchanged) return;
+    this.attachments = nextAttachments;
+    this.options.onChange(this.readyAttachments);
+    this.options.onStateChange();
+  }
+
+  /** Add picker-selected attachments through the same cache path as pasted attachments. */
+  addFiles(files: File[]): void {
+    if (this.locked || this.disposed) return;
+    const eligibleFiles = files.filter((file) => {
+      if (!isSupportedAttachment(file)) return false;
+      if (file.size <= MAX_COMPOSER_ATTACHMENT_BYTES) return true;
+      this.options.onLimitExceeded("size");
+      return false;
+    });
+    const availableSlots = Math.max(
+      0,
+      MAX_COMPOSER_ATTACHMENT_COUNT - this.attachments.length - this.pending,
+    );
+    if (eligibleFiles.length > availableSlots) {
+      this.options.onLimitExceeded("count");
+    }
+    const anchor = this.insertionAnchor;
+    this.insertionAnchor = undefined;
+    const acceptedFiles = eligibleFiles.slice(0, availableSlots);
+    this.pending += acceptedFiles.length;
+    this.options.onStateChange();
+    void this.cacheFilesInOrder(acceptedFiles, anchor);
+  }
+
+  clearAfterSubmit(): void {
+    this.attachments = [];
+    for (const image of this.detachedAttachments.values()) {
+      if (!this.submittedPaths.has(image.path)) {
+        void agent.deleteCachedAttachment(image.path).catch(() => undefined);
+      }
+    }
+    this.detachedAttachments.clear();
+    this.options.onChange([]);
+    // Acceptance may leave an edited follow-up draft visible. Rebuild from that document.
+    this.document?.setAttachmentTokensChanged((attachments) => this.syncInlineAttachments(attachments));
+    this.options.onStateChange();
+  }
+
+  /** Keep in-flight request files available until the request is accepted. */
+  setLocked(locked: boolean): void {
+    if (this.disposed || this.locked === locked) return;
+    this.locked = locked;
+    this.submittedPaths.clear();
+    if (locked) for (const image of this.attachments) this.submittedPaths.add(image.path);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.options.input.removeEventListener("paste", this.handlePaste);
+    this.document?.dispose();
+    this.document = undefined;
+    this.cancelInsertionAnchor();
+    for (const anchor of this.activeAnchors) anchor.dispose();
+    this.activeAnchors.clear();
+    for (const image of this.detachedAttachments.values()) {
+      if (!this.submittedPaths.has(image.path)) {
+        void agent.deleteCachedAttachment(image.path).catch(() => undefined);
+      }
+    }
+    this.detachedAttachments.clear();
+  }
+
+  private readonly handlePaste = (event: ClipboardEvent): void => {
+    const files = Array.from(event.clipboardData?.items ?? [])
+      .filter((item) => item.kind === "file" && item.type.startsWith("image/"))
+      .map((item) => item.getAsFile())
+      .filter((file): file is File => !!file);
+    if (files.length === 0) return;
+
+    // Clipboard image payloads often also contain a generated filename as text.
+    // Prevent that text from being inserted; genuine text-only paste stays native.
+    event.preventDefault();
+    this.captureInsertionAnchor();
+    this.addFiles(files);
+  };
+
+  private async cache(file: File, anchor?: ComposerInsertionAnchor): Promise<void> {
+    try {
+      const content = await readFileAsDataUrl(file);
+      const result = await agent.cacheAttachment(content, getAttachmentMimeType(file) ?? file.type);
+      const cached = { ...result, name: file.name };
+      if (this.disposed) {
+        void agent.deleteCachedAttachment(cached.path).catch(() => undefined);
+        return;
+      }
+      this.attachments = [...this.attachments, cached];
+      if (this.document) {
+        const nextPosition = this.document.insertAttachmentToken(cached, anchor?.resolve());
+        if (nextPosition) anchor?.advance(nextPosition);
+      }
+      this.options.onChange(this.readyAttachments);
+    } catch (error) {
+      if (!this.disposed) this.options.onError(error instanceof Error ? error.message : String(error));
+    } finally {
+      this.pending = Math.max(0, this.pending - 1);
+      if (!this.disposed) this.options.onStateChange();
+    }
+  }
+
+  private async cacheFilesInOrder(files: File[], anchor?: ComposerInsertionAnchor): Promise<void> {
+    if (anchor) this.activeAnchors.add(anchor);
+    let processed = 0;
+    try {
+      for (const file of files) {
+        if (this.disposed || this.locked) break;
+        await this.cache(file, anchor);
+        processed += 1;
+      }
+    } finally {
+      this.pending = Math.max(0, this.pending - (files.length - processed));
+      anchor?.dispose();
+      if (anchor) this.activeAnchors.delete(anchor);
+      if (!this.disposed) this.options.onStateChange();
+    }
+  }
+
+  private remove(
+    image: AgentThreadCardInputAttachment,
+    deleteCachedFile: boolean = true,
+  ): void {
+    if (this.locked && deleteCachedFile) return;
+    this.attachments = this.attachments.filter((candidate) => candidate.path !== image.path);
+    this.options.onChange(this.readyAttachments);
+    this.options.onStateChange();
+    if (deleteCachedFile) {
+      void agent.deleteCachedAttachment(image.path).catch(() => undefined);
+    } else {
+      this.document?.removeAttachmentToken(image.path);
+    }
+  }
+
+  private async validateCachedImage(image: AgentThreadCardInputAttachment): Promise<void> {
+    try {
+      const content = await agent.readCachedAttachment(image.path);
+      if (this.disposed) return;
+      if (!this.attachments.some((candidate) => candidate.path === image.path)) return;
+      if (!content) {
+        this.remove(image, false);
+        return;
+      }
+    } catch (error) {
+      if (!this.disposed) {
+        this.options.onError(
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+  }
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-document.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-document.ts
new file mode 100644
index 000000000..7221c60a5
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-document.ts
@@ -0,0 +1,124 @@
+import type { Editor } from "@tiptap/core";
+import type { AgentThreadCardInputAttachment } from "./composer-attachment-types";
+import { COMPOSER_ATTACHMENT_NODE_NAME } from "./composer-attachment-compat";
+import {
+  captureComposerInsertionAnchor,
+  type ComposerInsertionAnchor,
+  type ComposerInsertionPoint,
+} from "./composer-insertion-anchor";
+
+export interface ComposerAttachmentDocumentPort {
+  captureAttachmentInsertionAnchor(): ComposerInsertionAnchor | undefined;
+  insertAttachmentToken(
+    attachment: AgentThreadCardInputAttachment,
+    position?: ComposerInsertionPoint,
+  ): ComposerInsertionPoint | undefined;
+  removeAttachmentToken(path: string): void;
+  setAttachmentTokensChanged(
+    handler: (attachments: readonly AgentThreadCardInputAttachment[]) => void,
+  ): void;
+  dispose(): void;
+}
+
+export function insertComposerAttachmentToken(
+  editor: Editor,
+  attachment: AgentThreadCardInputAttachment,
+  position?: ComposerInsertionPoint,
+): ComposerInsertionPoint {
+  const { doc } = editor.state;
+  const maxPosition = Math.max(1, doc.content.size - 1);
+  const from = position ? Math.max(1, Math.min(position.from, maxPosition)) : 1;
+  const to = position ? Math.max(from, Math.min(position.to, maxPosition)) : from;
+  const before = from > 1 ? doc.textBetween(from - 1, from, "\n", "\n") : "";
+  const after = to < maxPosition ? doc.textBetween(to, to + 1, "\n", "\n") : "";
+  const content: Array<Record<string, unknown>> = [];
+  if (before && !/\s/u.test(before)) content.push({ type: "text", text: " " });
+  content.push({
+    type: COMPOSER_ATTACHMENT_NODE_NAME,
+    attrs: { path: attachment.path, name: attachment.name, mimeType: attachment.mimeType },
+  });
+  if (after && !/\s/u.test(after)) content.push({ type: "text", text: " " });
+  editor.chain().focus(null, { scrollIntoView: false }).insertContentAt({ from, to }, content).run();
+  const end = editor.state.selection.to;
+  return { from: end, to: end };
+}
+
+/** Tiptap document operations and token synchronization for composer files. */
+export class ComposerAttachmentDocument implements ComposerAttachmentDocumentPort {
+  private changed?: (attachments: readonly AgentThreadCardInputAttachment[]) => void;
+
+  constructor(private readonly editor: Editor) {
+    editor.on("transaction", this.handleTransaction);
+  }
+
+  dispose(): void {
+    this.changed = undefined;
+    if (!this.editor.isDestroyed) this.editor.off("transaction", this.handleTransaction);
+  }
+
+  captureAttachmentInsertionAnchor(): ComposerInsertionAnchor | undefined {
+    if (this.editor.isDestroyed) return undefined;
+    return captureComposerInsertionAnchor(this.editor);
+  }
+
+  insertAttachmentToken(
+    attachment: AgentThreadCardInputAttachment,
+    position?: ComposerInsertionPoint,
+  ): ComposerInsertionPoint | undefined {
+    if (this.editor.isDestroyed) return undefined;
+    let exists = false;
+    this.editor.state.doc.descendants((node) => {
+      if (node.type.name === COMPOSER_ATTACHMENT_NODE_NAME && node.attrs.path === attachment.path) {
+        exists = true;
+      }
+    });
+    return exists ? position : this.insert(attachment, position);
+  }
+
+  removeAttachmentToken(path: string): void {
+    if (this.editor.isDestroyed) return;
+    const matches: Array<{ from: number; to: number }> = [];
+    this.editor.state.doc.descendants((node, pos) => {
+      if (node.type.name === COMPOSER_ATTACHMENT_NODE_NAME && node.attrs.path === path) {
+        matches.push({ from: pos, to: pos + node.nodeSize });
+      }
+    });
+    if (matches.length === 0) return;
+    const transaction = this.editor.state.tr;
+    for (const match of matches.reverse()) transaction.delete(match.from, match.to);
+    this.editor.view.dispatch(transaction);
+  }
+
+  setAttachmentTokensChanged(
+    handler: (attachments: readonly AgentThreadCardInputAttachment[]) => void,
+  ): void {
+    this.changed = handler;
+    this.reportChanges();
+  }
+
+  private reportChanges(): void {
+    if (!this.changed || this.editor.isDestroyed) return;
+    const attachments = new Map<string, AgentThreadCardInputAttachment>();
+    this.editor.state.doc.descendants((node) => {
+      if (node.type.name !== COMPOSER_ATTACHMENT_NODE_NAME || !node.attrs.path) return;
+      const path = String(node.attrs.path);
+      attachments.set(path, {
+        path,
+        name: String(node.attrs.name ?? ""),
+        mimeType: String(node.attrs.mimeType ?? "application/octet-stream"),
+      });
+    });
+    this.changed([...attachments.values()]);
+  }
+
+  private readonly handleTransaction = ({ transaction }: { transaction: { docChanged: boolean } }): void => {
+    if (transaction.docChanged) this.reportChanges();
+  };
+
+  private insert(
+    attachment: AgentThreadCardInputAttachment,
+    position?: ComposerInsertionPoint,
+  ): ComposerInsertionPoint {
+    return insertComposerAttachmentToken(this.editor, attachment, position);
+  }
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-node-view.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-node-view.ts
new file mode 100644
index 000000000..a4c52d301
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-node-view.ts
@@ -0,0 +1,54 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import type { EditorView } from "@tiptap/pm/view";
+import {
+  createInlineAtomCloseIcon,
+  createInlineAtomNodeView,
+  deleteInlineAtomNode,
+} from "@features/editor/extensions/shared/inline-atom-nodeview";
+import { createComposerAttachmentPreview } from "./composer-attachment-preview";
+
+export function createComposerAttachmentNodeView(options: {
+  node: ProseMirrorNode;
+  view: EditorView;
+  getPos: (() => number | undefined) | boolean;
+}) {
+  const { node, view, getPos } = options;
+  const path = String(node.attrs.path ?? "");
+  const name = String(node.attrs.name ?? "");
+  const mimeType = String(node.attrs.mimeType ?? "application/octet-stream");
+  const content = document.createElement("span");
+  content.className = "agent-composer__attachment-token";
+  content.title = name;
+  content.setAttribute("aria-label", `附件 ${name}`);
+
+  const preview = createComposerAttachmentPreview(path, name, mimeType, content);
+  const label = document.createElement("span");
+  label.className = "agent-composer__attachment-token-label";
+  label.textContent = name;
+  label.title = name;
+  content.append(preview.element, label);
+
+  const nodeView = createInlineAtomNodeView({
+    caretGeometry: "single-line",
+    wrapperClassName: "agent-composer__inline-atom-wrapper agent-composer__attachment-token-wrapper",
+    content,
+    title: name,
+    onClick: () => preview.onClick(),
+    hoverActions: [{
+      ariaLabel: `移除附件 ${name}`,
+      icon: createInlineAtomCloseIcon(),
+      onClick: () => deleteInlineAtomNode(
+        view,
+        node,
+        () => typeof getPos === "function" ? getPos() : undefined,
+      ),
+    }],
+  });
+
+  return {
+    ...nodeView,
+    destroy: () => {
+      preview.destroy();
+    },
+  };
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-preview.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-preview.ts
new file mode 100644
index 000000000..e74a14c60
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-preview.ts
@@ -0,0 +1,143 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { agent } from "@platform/tauri/client";
+import { NotebookTreeResourceIcon } from "@features/memo/public/file-icon-api";
+
+const IMAGE_MIME_RE = /^image\//i;
+
+export interface ComposerAttachmentPreview {
+  element: Element;
+  onClick: () => void;
+  destroy: () => void;
+}
+
+/** Owns attachment thumbnail loading and the portaled click preview lifecycle. */
+export function createComposerAttachmentPreview(
+  path: string,
+  name: string,
+  mimeType: string,
+  anchor: HTMLElement,
+): ComposerAttachmentPreview {
+  if (!IMAGE_MIME_RE.test(mimeType)) {
+    const template = document.createElement("template");
+    template.innerHTML = renderToStaticMarkup(createElement(NotebookTreeResourceIcon, {
+      path: name,
+      className: "agent-composer__attachment-token-icon",
+    }));
+    const fileIcon = template.content.firstElementChild as SVGSVGElement;
+    return {
+      element: fileIcon,
+      onClick: () => undefined,
+      destroy: () => undefined,
+    };
+  }
+
+  const imagePreview = document.createElement("img");
+  imagePreview.className = "agent-composer__attachment-token-preview";
+  imagePreview.alt = "";
+  imagePreview.draggable = false;
+
+  let imageDataUrl: string | undefined;
+  let popover: HTMLDivElement | undefined;
+  let popoverImage: HTMLImageElement | undefined;
+  let popoverOpen = false;
+  let destroyed = false;
+
+  const positionPopover = (): void => {
+    if (!popoverOpen || !popover?.isConnected) return;
+    const anchorRect = anchor.getBoundingClientRect();
+    const popoverRect = popover.getBoundingClientRect();
+    const width = popoverRect.width || 272;
+    const height = popoverRect.height || 120;
+    const padding = 8;
+    const left = Math.min(
+      Math.max(anchorRect.left + (anchorRect.width - width) / 2, padding),
+      Math.max(padding, window.innerWidth - width - padding),
+    );
+    const top = Math.max(padding, anchorRect.top - height - 8);
+    popover.style.left = `${left}px`;
+    popover.style.top = `${top}px`;
+  };
+
+  const handleViewportChange = (): void => positionPopover();
+  function closePopover(): void {
+    popoverOpen = false;
+    if (popover) popover.hidden = true;
+    anchor.setAttribute("aria-expanded", "false");
+    window.removeEventListener("resize", handleViewportChange);
+    window.removeEventListener("scroll", handleViewportChange, true);
+    document.removeEventListener("pointerdown", handleOutsidePointer, true);
+    document.removeEventListener("keydown", handleKeyDown, true);
+  }
+  function openPopover(): void {
+    if (destroyed) return;
+    if (!popover) {
+      popover = document.createElement("div");
+      popover.className = "agent-composer__image-preview-popover";
+      popover.hidden = true;
+      popover.setAttribute("role", "dialog");
+      popover.setAttribute("aria-label", `图片预览：${name}`);
+      popoverImage = document.createElement("img");
+      popoverImage.alt = name;
+      popoverImage.draggable = false;
+      popoverImage.addEventListener("load", () => {
+        if (popoverOpen) positionPopover();
+      });
+      popover.append(popoverImage);
+      document.body.append(popover);
+    }
+    if (imageDataUrl && popoverImage && popoverImage.src !== imageDataUrl) {
+      popoverImage.src = imageDataUrl;
+    }
+    popoverOpen = true;
+    anchor.setAttribute("aria-expanded", "true");
+    popover.hidden = !imageDataUrl;
+    window.addEventListener("resize", handleViewportChange);
+    window.addEventListener("scroll", handleViewportChange, true);
+    document.addEventListener("pointerdown", handleOutsidePointer, true);
+    document.addEventListener("keydown", handleKeyDown, true);
+    if (imageDataUrl) positionPopover();
+  }
+
+  function handleOutsidePointer(event: PointerEvent): void {
+    const target = event.target as Node | null;
+    if (target && (anchor.contains(target) || popover?.contains(target))) return;
+    closePopover();
+  }
+  function handleKeyDown(event: KeyboardEvent): void {
+    if (event.key !== "Escape" || !popoverOpen) return;
+    event.preventDefault();
+    event.stopPropagation();
+    closePopover();
+  }
+  const togglePopover = (): void => {
+    if (popoverOpen) closePopover();
+    else openPopover();
+  };
+
+  anchor.setAttribute("aria-haspopup", "dialog");
+  anchor.setAttribute("aria-expanded", "false");
+
+  void agent.readCachedAttachment(path)
+    .then((dataUrl) => {
+      if (destroyed || !dataUrl) return;
+      imageDataUrl = dataUrl;
+      imagePreview.src = dataUrl;
+      if (popoverImage) popoverImage.src = dataUrl;
+      if (popoverOpen && popover) popover.hidden = false;
+      if (popoverOpen) positionPopover();
+    })
+    .catch(() => undefined);
+
+  return {
+    element: imagePreview,
+    onClick: togglePopover,
+    destroy: () => {
+      destroyed = true;
+      closePopover();
+      popover?.remove();
+      popover = undefined;
+      popoverImage = undefined;
+    },
+  };
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-token.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-token.test.ts
new file mode 100644
index 000000000..7786c9d93
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-token.test.ts
@@ -0,0 +1,124 @@
+import { Editor } from '@tiptap/core';
+import Document from '@tiptap/extension-document';
+import Paragraph from '@tiptap/extension-paragraph';
+import Text from '@tiptap/extension-text';
+import { UndoRedo } from '@tiptap/extensions/undo-redo';
+import { Markdown } from '@tiptap/markdown';
+import { closeHistory } from '@tiptap/pm/history';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ComposerAttachmentToken } from './composer-attachment-token';
+import { insertComposerAttachmentToken } from './composer-attachment-document';
+import { COMPOSER_ATTACHMENT_NODE_NAME } from './composer-attachment-compat';
+import { ComposerAttachmentController, type AgentThreadCardInputAttachment } from './composer-attachment-controller';
+import { captureComposerInsertionAnchor } from './composer-insertion-anchor';
+import { NotebookTreeResourceIcon } from '@features/memo/public/file-icon-api';
+
+const mocks = vi.hoisted(() => ({ cacheAttachment: vi.fn(), deleteCachedAttachment: vi.fn(), readCachedAttachment: vi.fn() }));
+vi.mock('@platform/tauri/client', () => ({ agent: mocks }));
+const cleanups: Array<() => void> = [];
+beforeEach(() => {
+  mocks.cacheAttachment.mockImplementation(async (_data: string, mimeType: string) => ({ path: `/tmp/${mocks.cacheAttachment.mock.calls.length}`, name: 'generated', mimeType }));
+  mocks.readCachedAttachment.mockResolvedValue('data:image/png;base64,AQID');
+  mocks.deleteCachedAttachment.mockResolvedValue(true);
+  Object.defineProperties(Range.prototype, {
+    getClientRects: { configurable: true, value: () => [] },
+    getBoundingClientRect: { configurable: true, value: () => ({ top: 0, bottom: 0, left: 0, right: 0, width: 0, height: 0 }) },
+  });
+});
+afterEach(() => {
+  cleanups.splice(0).forEach((cleanup) => cleanup());
+  document.body.replaceChildren();
+  vi.resetAllMocks();
+});
+function setup(content = '') {
+  const input = document.createElement('div');
+  document.body.append(input);
+  const editor = new Editor({ element: { mount: input }, extensions: [Document, Paragraph, Text, UndoRedo, Markdown, ComposerAttachmentToken], content, contentType: 'markdown' });
+  const attachments = new ComposerAttachmentController({ input, initialAttachments: [], onChange: vi.fn(), onStateChange: vi.fn(), onError: vi.fn(), onLimitExceeded: vi.fn() });
+  attachments.connectDocument({
+    captureAttachmentInsertionAnchor: () => captureComposerInsertionAnchor(editor),
+    insertAttachmentToken: (attachment, position) => insertComposerAttachmentToken(editor, attachment, position),
+    removeAttachmentToken: () => undefined,
+    setAttachmentTokensChanged(handler) {
+      const sync = () => {
+        const tokens: AgentThreadCardInputAttachment[] = [];
+        editor.state.doc.descendants((node) => {
+          if (node.type.name === COMPOSER_ATTACHMENT_NODE_NAME) tokens.push({ path: node.attrs.path, name: node.attrs.name, mimeType: node.attrs.mimeType });
+        });
+        handler(tokens);
+      };
+      editor.on('update', sync);
+      sync();
+    },
+    dispose: () => undefined,
+  });
+  cleanups.push(() => { attachments.dispose(); editor.destroy(); });
+  return { editor, attachments, input };
+}
+const pdf = (name: string) => new File(['pdf'], name, { type: 'application/pdf' });
+
+describe('Inline composer attachments', () => {
+  it('replaces the selected text once when uploading multiple files', async () => {
+    const { editor, attachments } = setup('before replace after');
+    editor.commands.setTextSelection({ from: 8, to: 15 });
+    attachments.captureInsertionAnchor();
+    attachments.addFiles([pdf('first.pdf'), pdf('second.pdf')]);
+    await vi.waitFor(() => expect(attachments.hasPending).toBe(false));
+    expect(editor.state.doc.textContent).toContain('before');
+    expect(editor.state.doc.textContent).toContain('after');
+    expect(editor.state.doc.textContent).not.toContain('replace');
+    expect(attachments.readyAttachments.map((attachment) => attachment.name)).toEqual(['first.pdf', 'second.pdf']);
+  });
+
+  it('maps the captured insertion position through edits made while the file caches', async () => {
+    const { editor, attachments } = setup('abcd');
+    let resolveCache!: (value: AgentThreadCardInputAttachment) => void;
+    mocks.cacheAttachment.mockImplementation(() => new Promise((resolve) => { resolveCache = resolve; }));
+    editor.commands.setTextSelection(5);
+    attachments.captureInsertionAnchor();
+    attachments.addFiles([pdf('report.pdf')]);
+    await vi.waitFor(() => expect(mocks.cacheAttachment).toHaveBeenCalled());
+    editor.commands.insertContentAt(1, 'prefix ');
+    resolveCache({ path: '/tmp/report.pdf', name: 'generated', mimeType: 'application/pdf' });
+    await vi.waitFor(() => expect(attachments.hasPending).toBe(false));
+    let attachmentPosition = -1;
+    editor.state.doc.descendants((node, pos) => { if (node.type.name === COMPOSER_ATTACHMENT_NODE_NAME) attachmentPosition = pos; });
+    expect(editor.state.doc.textBetween(0, attachmentPosition)).toBe('prefix abcd ');
+  });
+
+  it('keeps an attachment submit-ready after delete and undo', () => {
+    const { editor, attachments } = setup();
+    const attachment = { path: '/tmp/report.pdf', name: 'report.pdf', mimeType: 'application/pdf' };
+    insertComposerAttachmentToken(editor, attachment, { from: 1, to: 1 });
+    editor.view.dispatch(closeHistory(editor.state.tr));
+    editor.commands.deleteRange({ from: 1, to: 2 });
+    expect(attachments.readyAttachments).toEqual([]);
+    editor.commands.undo();
+    expect(attachments.readyAttachments).toEqual([attachment]);
+    expect(mocks.deleteCachedAttachment).not.toHaveBeenCalled();
+  });
+
+  it('uses the matching SVG icon from the workspace file tree for non-image attachments', () => {
+    const { editor, input } = setup();
+    insertComposerAttachmentToken(editor, { path: '/tmp/report.pdf', name: 'report.pdf', mimeType: 'application/pdf' });
+    const icon = input.querySelector<SVGSVGElement>('.agent-composer__attachment-token-icon');
+    const expectedTemplate = document.createElement('template');
+    expectedTemplate.innerHTML = renderToStaticMarkup(createElement(NotebookTreeResourceIcon, {
+      path: 'report.pdf',
+      className: 'agent-composer__attachment-token-icon',
+    }));
+    expect(icon?.outerHTML).toBe(expectedTemplate.content.firstElementChild?.outerHTML);
+  });
+
+  it('round-trips attachment cards in the saved Markdown draft', () => {
+    const { editor, attachments } = setup();
+    const attachment = { path: '/tmp/report.pdf', name: 'report.pdf', mimeType: 'application/pdf' };
+    insertComposerAttachmentToken(editor, attachment);
+    const markdown = editor.getMarkdown();
+    editor.commands.setContent(markdown, { contentType: 'markdown' });
+    expect(attachments.readyAttachments).toEqual([attachment]);
+    expect(editor.state.doc.firstChild?.firstChild?.type.name).toBe(COMPOSER_ATTACHMENT_NODE_NAME);
+  });
+});
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-token.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-token.ts
new file mode 100644
index 000000000..084331c5d
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-token.ts
@@ -0,0 +1,135 @@
+import { Node, type JSONContent, type MarkdownToken } from "@tiptap/core";
+import {
+  COMPOSER_ATTACHMENT_HTML_ATTRIBUTE,
+  COMPOSER_ATTACHMENT_NODE_NAME,
+  LEGACY_COMPOSER_IMAGE_HTML_ATTRIBUTE,
+} from "./composer-attachment-compat";
+import { createComposerAttachmentNodeView } from "./composer-attachment-node-view";
+import { deleteAdjacentInlineAtom } from "@features/editor/extensions/shared/inline-atom-nodeview";
+
+const TOKEN_RE = /^\u27e6attachment:([^:\u27e7]*):([^:\u27e7]*):([^:\u27e7]*)\u27e7/;
+const TOKEN_GLOBAL_RE = /\u27e6attachment:([^:\u27e7]*):([^:\u27e7]*):([^:\u27e7]*)\u27e7/g;
+
+function decode(value: string): string {
+  try { return decodeURIComponent(value); } catch { return value; }
+}
+
+/** Inline attachment data and serialization. View behavior lives in adjacent modules. */
+export const ComposerAttachmentToken = Node.create({
+  name: COMPOSER_ATTACHMENT_NODE_NAME,
+  priority: 1100,
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      name: { default: "" },
+      // Preserve the old image-token default for drafts created before MIME
+      // data was serialized; new generic attachments always store their type.
+      mimeType: { default: "image/png" },
+    };
+  },
+  parseHTML() {
+    return [{
+      tag: `span[${COMPOSER_ATTACHMENT_HTML_ATTRIBUTE}], span[${LEGACY_COMPOSER_IMAGE_HTML_ATTRIBUTE}]`,
+      getAttrs: (dom) => {
+        const element = dom as HTMLElement;
+        return {
+          path: element.getAttribute(COMPOSER_ATTACHMENT_HTML_ATTRIBUTE)
+            ?? element.getAttribute(LEGACY_COMPOSER_IMAGE_HTML_ATTRIBUTE)
+            ?? "",
+          name: element.getAttribute("data-name") ?? "",
+          mimeType: element.getAttribute("data-mime-type") ?? "image/png",
+        };
+      },
+    }];
+  },
+  renderHTML({ node }) {
+    const path = String(node.attrs.path ?? "");
+    return ["span", {
+      [COMPOSER_ATTACHMENT_HTML_ATTRIBUTE]: path,
+      // Older Flowix releases read this attribute when pasting saved HTML.
+      [LEGACY_COMPOSER_IMAGE_HTML_ATTRIBUTE]: path,
+      "data-name": String(node.attrs.name ?? ""),
+      "data-mime-type": String(node.attrs.mimeType ?? "application/octet-stream"),
+      class: "agent-composer__attachment-token",
+    }, String(node.attrs.name ?? "")];
+  },
+  markdownTokenizer: {
+    name: COMPOSER_ATTACHMENT_NODE_NAME,
+    level: "inline" as const,
+    start(src: string) { return src.indexOf("⟦attachment:"); },
+    tokenize(src: string) {
+      const match = TOKEN_RE.exec(src);
+      return match ? {
+        type: COMPOSER_ATTACHMENT_NODE_NAME,
+        raw: match[0],
+        path: decode(match[1]),
+        name: decode(match[2]),
+        mimeType: decode(match[3]),
+      } : undefined;
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    return {
+      type: COMPOSER_ATTACHMENT_NODE_NAME,
+      attrs: {
+        path: String(token.path ?? ""),
+        name: String(token.name ?? ""),
+        mimeType: String(token.mimeType ?? "image/png"),
+      },
+    };
+  },
+  renderMarkdown(node: JSONContent) {
+    const { path, name, mimeType } = node.attrs ?? {};
+    return `⟦attachment:${encodeURIComponent(String(path ?? ""))}:${encodeURIComponent(String(name ?? ""))}:${encodeURIComponent(String(mimeType ?? "image/png"))}⟧`;
+  },
+  addNodeView() {
+    return ({ node, view, getPos }) => createComposerAttachmentNodeView({ node, view, getPos });
+  },
+  addKeyboardShortcuts() {
+    return {
+      Backspace: () => deleteAdjacentInlineAtom(this.editor, COMPOSER_ATTACHMENT_NODE_NAME, "before"),
+      Delete: () => deleteAdjacentInlineAtom(this.editor, COMPOSER_ATTACHMENT_NODE_NAME, "after"),
+    };
+  },
+});
+
+function toLocalFileUrl(path: string): string {
+  const normalized = path.replace(/\\/g, "/");
+  const encodeSegments = (value: string) => value.split("/").map(encodeURIComponent).join("/");
+
+  if (normalized.startsWith("//")) {
+    const [host = "", ...segments] = normalized.slice(2).split("/");
+    return `file://${encodeURIComponent(host)}/${segments.map(encodeURIComponent).join("/")}`;
+  }
+  const windowsDrive = /^([a-z]):\/(.*)$/i.exec(normalized);
+  if (windowsDrive) {
+    return `file:///${windowsDrive[1].toUpperCase()}:/${encodeSegments(windowsDrive[2])}`;
+  }
+  const absolutePath = normalized.startsWith("/") ? normalized : `/${normalized}`;
+  return `file://${encodeSegments(absolutePath)}`;
+}
+
+function escapeMarkdownLinkLabel(label: string): string {
+  return label
+    .replace(/[\u0000-\u001f\u007f]/gu, " ")
+    .replace(/\\/g, "\\\\")
+    .replace(/([\[\]])/g, "\\$1");
+}
+
+export function composerAttachmentMarkdownToPrompt(markdown: string): string {
+  return markdown.replace(
+    TOKEN_GLOBAL_RE,
+    (_token, encodedPath: string, encodedName: string, encodedMimeType: string) => {
+      const path = decode(encodedPath);
+      const name = decode(encodedName) || path.split(/[\\/]/u).pop() || "Attachment";
+      const mimeType = decode(encodedMimeType).toLowerCase();
+      if (mimeType.startsWith("image/")) return "";
+      if (!path) return "";
+      return `[${escapeMarkdownLinkLabel(name)}](${toLocalFileUrl(path)})`;
+    },
+  );
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-attachment-types.ts b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-types.ts
new file mode 100644
index 000000000..6ba2a47c2
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-attachment-types.ts
@@ -0,0 +1,9 @@
+import type { CachedAgentAttachment } from "@platform/tauri/client";
+
+export type AgentThreadCardInputAttachment = CachedAgentAttachment;
+
+export function isAgentThreadCardImageAttachment(
+  attachment: Pick<AgentThreadCardInputAttachment, "mimeType">,
+): boolean {
+  return attachment.mimeType.toLowerCase().startsWith("image/");
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-commands.ts b/app/flowix-web/features/agent/thread-card/composer/composer-commands.ts
index bfef70782..bd0c19215 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-commands.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-commands.ts
@@ -14,13 +14,13 @@ export interface ComposerSlashCommand {
 }
 
 export const COMPOSER_SLASH_COMMANDS: readonly ComposerSlashCommand[] = [
-  { name: "compact", description: "压缩较早的对话上下文", agentType: "deepseek-harness", owner: "dsh", interaction: "direct", execution: "dsh-command" },
-  { name: "skill", description: "选择一个 DSH Skill", agentType: "deepseek-harness", owner: "dsh", interaction: "drilldown", execution: "dsh-skill" },
-  { name: "goal", description: "设置或查看长时任务目标", agentType: "deepseek-harness", owner: "dsh", interaction: "prompt", execution: "dsh-command" },
-  { name: "plan", description: "进入或退出计划模式", agentType: "deepseek-harness", owner: "dsh", interaction: "prompt", execution: "dsh-command" },
-  { name: "model", description: "选择本次会话使用的模型", agentType: "deepseek-harness", owner: "flowix", interaction: "drilldown", execution: "host-action" },
-  { name: "permission", description: "切换权限预设", agentType: "deepseek-harness", owner: "flowix", interaction: "drilldown", execution: "host-action" },
-  { name: "export", description: "导出当前 DSH 会话记录", agentType: "deepseek-harness", owner: "dsh", interaction: "direct", execution: "dsh-command" },
+  { name: "compact", description: "压缩较早的对话上下文", agentType: "dsh", owner: "dsh", interaction: "direct", execution: "dsh-command" },
+  { name: "skill", description: "选择一个 DSH Skill", agentType: "dsh", owner: "dsh", interaction: "drilldown", execution: "dsh-skill" },
+  { name: "goal", description: "设置或查看长时任务目标", agentType: "dsh", owner: "dsh", interaction: "prompt", execution: "dsh-command" },
+  { name: "plan", description: "进入或退出计划模式", agentType: "dsh", owner: "dsh", interaction: "prompt", execution: "dsh-command" },
+  { name: "model", description: "选择本次会话使用的模型", agentType: "dsh", owner: "flowix", interaction: "drilldown", execution: "host-action" },
+  { name: "permission", description: "切换权限预设", agentType: "dsh", owner: "flowix", interaction: "drilldown", execution: "host-action" },
+  { name: "export", description: "导出当前 DSH 会话记录", agentType: "dsh", owner: "dsh", interaction: "direct", execution: "dsh-command" },
   { name: "compact", description: "压缩较早的 Codex 对话上下文", agentType: "codex", owner: "flowix", interaction: "direct", execution: "codex-command" },
   { name: "skill", description: "选择一个 Codex Skill", agentType: "codex", owner: "flowix", interaction: "drilldown", execution: "codex-skill" },
   { name: "goal", description: "设置或查看 Codex 长时任务目标", agentType: "codex", owner: "flowix", interaction: "prompt", execution: "codex-command" },
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-controller.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-controller.test.ts
index 925a6be1a..56dbb908d 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-controller.test.ts
@@ -9,6 +9,7 @@ import {
   disposeAgentComposerDom,
   type ComposerControllerOptions,
 } from "./index";
+import { insertComposerAttachmentToken } from "./composer-attachment-document";
 import { insertComposerSkillToken } from "./composer-skill-token";
 
 const controllers: ComposerController[] = [];
@@ -84,7 +85,7 @@ describe("ComposerController note references", () => {
     controller.editorInstance.commands.setContent("hello", { contentType: "markdown" });
     const input = controller.getInputElement();
     input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }));
-    const button = () => document.querySelector<HTMLButtonElement>(".agent-thread-card__send")!;
+    const button = () => document.querySelector<HTMLButtonElement>(".agent-composer__send")!;
     await vi.waitFor(() => expect(button()?.disabled).toBe(true));
     button().click();
     expect(submit).not.toHaveBeenCalled();
@@ -210,7 +211,7 @@ describe("ComposerController note references", () => {
       .getInputElement()
       .parentElement;
 
-    expect(row?.classList.contains("agent-thread-card__composer-input-row")).toBe(true);
+    expect(row?.classList.contains("agent-composer__input-row")).toBe(true);
     row?.dispatchEvent(
       new MouseEvent("pointerdown", {
         bubbles: true,
@@ -238,7 +239,7 @@ describe("ComposerController note references", () => {
     draft.flush();
 
     expect(controller.getPrompt()).toBe(
-      "before [Reference](flowix://open?notebookId=notebook-a&relativePath=reference.md) after",
+      "before [reference](flowix://open?notebookId=notebook-a&relativePath=reference.md) after",
     );
     expect(editor.getJSON().content?.[0]?.content).toEqual(
       expect.arrayContaining([
@@ -246,7 +247,7 @@ describe("ComposerController note references", () => {
       ]),
     );
     expect(getPersistedDraft()).toBe(
-      "before [Reference](flowix://open?notebookId=notebook-a&relativePath=reference.md) after",
+      "before [reference](flowix://open?notebookId=notebook-a&relativePath=reference.md) after",
     );
   });
 
@@ -274,7 +275,7 @@ describe("ComposerController note references", () => {
       { contentType: "markdown" },
     );
 
-    expect(controller.getInputElement().querySelector(".agent-thread-card__skill-token")?.textContent)
+    expect(controller.getInputElement().querySelector(".agent-composer__skill-token-label")?.textContent)
       .toBe("Browser");
     expect(controller.getPrompt()).toBe("$browser:control-in-app-browser");
     expect(editor.getMarkdown()).toBe(
@@ -290,7 +291,7 @@ describe("ComposerController note references", () => {
       { contentType: "markdown" },
     );
 
-    expect(controller.getInputElement().querySelector(".agent-thread-card__skill-token")?.textContent)
+    expect(controller.getInputElement().querySelector(".agent-composer__skill-token-label")?.textContent)
       .toBe("control-in-app-browser");
     expect(controller.getPrompt()).toBe("$browser:control-in-app-browser");
   });
@@ -303,8 +304,29 @@ describe("ComposerController note references", () => {
       "Browser",
     );
 
-    expect(controller.getInputElement().querySelector(".agent-thread-card__skill-token")?.textContent)
+    expect(controller.getInputElement().querySelector(".agent-composer__skill-token-label")?.textContent)
       .toBe("Browser");
     expect(controller.getPrompt()).toBe("$browser:control-in-app-browser ");
   });
 });
+
+
+describe("composer draft history", () => {
+  it("restores inline attachments and skills when returning from message history", () => {
+    const { controller } = setup({ getUserHistoryMessages: () => ["previous message"] });
+    insertComposerSkillToken(controller.editorInstance, "figma:figma-use");
+    insertComposerAttachmentToken(controller.editorInstance, {
+      path: "/tmp/report.pdf",
+      name: "report.pdf",
+      mimeType: "application/pdf",
+    });
+    const draft = controller.getDraftMarkdown();
+    controller.editorInstance.commands.setTextSelection(1);
+    controller.getInputElement().dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowUp", bubbles: true, cancelable: true }));
+    expect(controller.getPrompt()).toBe("previous message");
+    controller.getInputElement().dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true }));
+    expect(controller.getDraftMarkdown()).toBe(draft);
+    expect(controller.getInputElement().querySelector(".agent-composer__attachment-token")).not.toBeNull();
+    expect(controller.getInputElement().querySelector(".agent-composer__skill-token")).not.toBeNull();
+  });
+});
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-controller.ts
index 471f501b2..1025c9adb 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-controller.ts
@@ -37,7 +37,10 @@ import type {
   ComposerSlashSkill,
 } from "@features/agent/thread-card/composer/composer-slash-command-controller";
 import type { AgentTypeKey } from "@/types/agent";
-import { NoteReference } from "@features/editor/extensions/note-link";
+import { ComposerNoteReference } from "@features/editor/extensions/note-link";
+import { ComposerStableCaret } from "@features/editor/extensions/stable-caret";
+import { ComposerAttachmentToken, composerAttachmentMarkdownToPrompt } from "./composer-attachment-token";
+import { ComposerInlineAtomCaret } from "./composer-inline-atom-caret";
 import type { MemoRef } from "@features/agent/thread-card/note/note-picker-controller";
 import type { Root } from "react-dom/client";
 
@@ -66,6 +69,7 @@ export interface ComposerControllerOptions {
   getHasAttachments: () => boolean;
   getHasPendingAttachments: () => boolean;
   agentType?: AgentTypeKey;
+  getSkillsScopeId?: () => string | undefined;
   listDshSkills?: () => Promise<readonly ComposerSlashSkill[]>;
   listCodexSkills?: () => Promise<readonly ComposerSlashSkill[]>;
   listPiSkills?: () => Promise<readonly ComposerSlashSkill[]>;
@@ -136,12 +140,15 @@ export class ComposerController {
         Text,
         HardBreak,
         UndoRedo,
+        ComposerStableCaret,
+        ComposerInlineAtomCaret,
         Markdown.configure({
           markedOptions: { gfm: true, breaks: true },
         }),
-        NoteReference,
+        ComposerNoteReference,
         ComposerSkillToken,
         ComposerFolderToken,
+        ComposerAttachmentToken,
         ComposerSlashToken.configure({
           onRemove: () => removeSlashToken?.(),
         }),
@@ -150,7 +157,7 @@ export class ComposerController {
       contentType: "markdown",
       editorProps: {
         attributes: {
-          class: "agent-thread-card__composer-editor",
+          class: "agent-composer__input-content",
           spellcheck: "true",
           "aria-label": this.input.dataset.placeholder ?? "",
         },
@@ -171,8 +178,8 @@ export class ComposerController {
     // Restore the composer-owned hooks after initialization so document
     // editor styles can explicitly exclude this nested editor.
     this.input.classList.add(
-      "agent-thread-card__composer-input",
-      "agent-thread-card__composer-editor",
+      "agent-composer__input",
+      "agent-composer__input-content",
     );
 
     this.slashCommands = new ComposerSlashCommandController({
@@ -180,6 +187,7 @@ export class ComposerController {
       input: this.input,
       composer: this.composer,
       agentType: options.agentType,
+      getSkillsScopeId: options.getSkillsScopeId,
       listDshSkills: options.listDshSkills,
       listCodexSkills: options.listCodexSkills,
       listPiSkills: options.listPiSkills,
@@ -238,6 +246,7 @@ export class ComposerController {
     // Capture before ProseMirror's own keymap so plain Enter submits without
     // first inserting an empty paragraph into the composer document.
     this.input.addEventListener("keydown", this.handleKeydown, true);
+    this.composer.addEventListener("pointermove", this.handleComposerPointerMove);
     this.input.addEventListener("beforeinput", this.handleBeforeInput, true);
     this.input.addEventListener("compositionstart", this.handleCompositionStart);
     this.input.addEventListener("compositionend", this.handleCompositionEnd);
@@ -258,9 +267,9 @@ export class ComposerController {
     // hardBreak. Markdown serializes that node as `  \n`; the agent protocol
     // should receive the same newline the user entered, without Markdown's
     // visual line-break marker becoming part of the prompt.
-    return composerFolderMarkdownToPrompt(
+    return composerAttachmentMarkdownToPrompt(composerFolderMarkdownToPrompt(
       composerSkillMarkdownToPrompt(composerSlashMarkdownToPrompt(this.getDraftMarkdown())),
-    )
+    ))
       .replace(/ {2}\n/g, "\n");
   }
 
@@ -297,6 +306,7 @@ export class ComposerController {
 
   clear(): void {
     if (this.editor.isDestroyed) return;
+    this.disableComposerHoverUntilPointerMove();
     this.editor
       .chain()
       .setContent("", { contentType: "markdown", emitUpdate: false })
@@ -315,11 +325,14 @@ export class ComposerController {
     options: { persistDraft?: boolean } = {},
   ): void {
     if (this.editor.isDestroyed) return;
+    this.disableComposerHoverUntilPointerMove();
     this.editor
       .chain()
       .setContent(content, { contentType: "markdown", emitUpdate: false })
       .focus("end", { scrollIntoView: false })
       .run();
+    // setContent intentionally suppresses editor updates for history navigation;
+    // keep inline attachments in sync with the newly loaded draft explicitly.
     if (options.persistDraft) this.persistInputDraft(content);
     this.updateMultiLineState();
   }
@@ -340,7 +353,6 @@ export class ComposerController {
     content.push({
       type: "noteReference",
       attrs: {
-        memoId: null,
         notebookId: ref.notebookId,
         relativePath: ref.relativePath,
         notebookName: "",
@@ -364,14 +376,14 @@ export class ComposerController {
   updateMultiLineState(): void {
     const prompt = this.getPrompt();
     if (prompt === "") {
-      this.composer.classList.remove("agent-thread-card__composer--multi-line");
+      this.composer.classList.remove("agent-composer--multi-line");
       this.setSendButtonState("");
       return;
     }
 
     const isMulti = this.input.scrollHeight > 30;
     this.composer.classList.toggle(
-      "agent-thread-card__composer--multi-line",
+      "agent-composer--multi-line",
       isMulti,
     );
     this.setSendButtonState(prompt.trim());
@@ -415,6 +427,7 @@ export class ComposerController {
     this.removeUndoHandler();
     this.removeRedoHandler();
     this.input.removeEventListener("keydown", this.handleKeydown, true);
+    this.composer.removeEventListener("pointermove", this.handleComposerPointerMove);
     this.input.removeEventListener("beforeinput", this.handleBeforeInput, true);
     this.input.removeEventListener("compositionstart", this.handleCompositionStart);
     this.input.removeEventListener("compositionend", this.handleCompositionEnd);
@@ -433,6 +446,7 @@ export class ComposerController {
 
   private readonly handleEditorUpdate = (): void => {
     if (this.suppressUpdates || this.disposed) return;
+    this.disableComposerHoverUntilPointerMove();
     if (!this.isCurrentHistoryEntryUnmodified()) this.resetHistoryNavigation();
     if (!this.isComposing) this.persistInputDraft();
     this.updateMultiLineState();
@@ -447,6 +461,17 @@ export class ComposerController {
     if (!this.disposed) this.slashCommands.refresh();
   };
 
+  private readonly handleComposerPointerMove = (event: PointerEvent): void => {
+    // Re-arm CSS hover only after physical mouse movement. The OS can hide the
+    // cursor while typing, but its stationary hit-test position remains active.
+    if (event.pointerType !== "mouse") return;
+    this.composer.classList.add("agent-composer--pointer-hover-ready");
+  };
+
+  private disableComposerHoverUntilPointerMove(): void {
+    this.composer.classList.remove("agent-composer--pointer-hover-ready");
+  }
+
   /**
    * Keep the caret visible when a hard break grows the editor past its
    * max-height. The editor height/class can change during the update, so wait
@@ -500,6 +525,7 @@ export class ComposerController {
   }
 
   private readonly handleKeydown = (event: KeyboardEvent): void => {
+    this.disableComposerHoverUntilPointerMove();
     if (this.isComposing || event.isComposing || event.keyCode === 229) return;
 
     // The composer is a nested contenteditable inside the document editor.
@@ -592,7 +618,7 @@ export class ComposerController {
 
     if (direction === "up") {
       if (this.historyCursor === null && this.preNavDraft === null) {
-        this.preNavDraft = this.getPrompt();
+        this.preNavDraft = this.getDraftMarkdown();
       }
       const next = this.historyCursor === null
         ? messages.length - 1
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.test.ts
index 7ed3a17fe..3775c1f2d 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.test.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.test.ts
@@ -105,12 +105,11 @@ describe("createAgentComposerDom click-to-focus delegation", () => {
     disposeAgentComposerDom(parts);
   });
 
-  it("focuses the textarea when clicking inside composer-images container", () => {
+  it("focuses the editor when clicking inside the factory-owned input row", () => {
     const parts = createAgentComposerDom({ t: noopT });
     document.body.append(parts.composer);
-    parts.composerImages.hidden = false;
     const imageSlot = document.createElement("span");
-    parts.composerImages.append(imageSlot);
+    parts.inputRow.append(imageSlot);
 
     dispatchPointerDown(imageSlot);
 
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.ts b/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.ts
index 5b5651dec..9714f68f7 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-dom-factory.ts
@@ -9,7 +9,7 @@ export interface AgentComposerDomFactoryOptions {
 
 export interface AgentComposerDomParts {
   composer: HTMLElement;
-  composerImages: HTMLDivElement;
+  inputRow: HTMLDivElement;
   composerActions: HTMLDivElement;
   composerRoleIcon: HTMLButtonElement;
   composerAddPopover: HTMLDivElement;
@@ -87,7 +87,7 @@ function handleComposerPointerDown(event: PointerEvent): void {
   // 所以不会影响发送、添加内容、模型选择等按钮的 click 行为。
   event.preventDefault();
   event.stopPropagation();
-  const input = composer.querySelector<HTMLDivElement>('.agent-thread-card__composer-input');
+  const input = composer.querySelector<HTMLDivElement>('.agent-composer__input');
   if (!input) return;
   focusComposerInput(composer, input);
 }
@@ -98,7 +98,7 @@ function handleComposerClick(event: MouseEvent): void {
   const target = event.target as Element | null;
   if (!target || isComposerInteractiveTarget(composer, target)) return;
   event.stopPropagation();
-  const input = composer.querySelector<HTMLDivElement>('.agent-thread-card__composer-input');
+  const input = composer.querySelector<HTMLDivElement>('.agent-composer__input');
   if (!input) return;
   focusComposerInput(composer, input);
 }
@@ -108,16 +108,15 @@ export function createAgentComposerDom(
   options: AgentComposerDomFactoryOptions,
 ): AgentComposerDomParts {
   const composer = document.createElement('div');
-  composer.className = 'agent-thread-card__composer';
+  composer.className = 'agent-composer';
   if (options.variant === 'expanded') {
     composer.classList.add('agent-composer--expanded');
   }
-  const composerImages = document.createElement('div');
-  composerImages.className = 'agent-thread-card__composer-images';
-  composerImages.hidden = true;
+  const inputRow = document.createElement('div');
+  inputRow.className = 'agent-composer__input-row';
   const composerRoleIcon = document.createElement('button');
   composerRoleIcon.type = 'button';
-  composerRoleIcon.className = 'agent-thread-card__composer-add-button';
+  composerRoleIcon.className = 'agent-composer__add-button';
   composerRoleIcon.setAttribute('aria-haspopup', 'menu');
   composerRoleIcon.setAttribute('aria-expanded', 'false');
   composerRoleIcon.setAttribute('aria-label', options.t('editor.threadCard.addContent'));
@@ -127,7 +126,7 @@ export function createAgentComposerDom(
   // point as a plain div lets the same imperative DOM contract work for both
   // the note-embedded NodeView and the standalone conversation surface.
   const input = document.createElement('div');
-  input.className = 'agent-thread-card__composer-input';
+  input.className = 'agent-composer__input';
   input.contentEditable = 'true';
   // Explicitly tabbable so the mount point remains focusable before Tiptap
   // initializes (and in embedded WebViews/jsdom where contenteditable alone
@@ -138,19 +137,19 @@ export function createAgentComposerDom(
   input.dataset.composerInitialDraft = options.inputDraft ?? '';
   input.spellcheck = true;
   const sendButtonMount = document.createElement('span');
-  sendButtonMount.className = 'agent-thread-card__send-tooltip';
+  sendButtonMount.className = 'agent-composer__send-tooltip';
   const composerActions = document.createElement('div');
-  composerActions.className = 'agent-thread-card__composer-actions';
+  composerActions.className = 'agent-composer__actions';
   const codexSettingsPopover = document.createElement('div');
   codexSettingsPopover.className = 'agent-thread-card__codex-settings-popover';
   codexSettingsPopover.setAttribute('role', 'menu');
   codexSettingsPopover.hidden = true;
   const composerRolePopover = document.createElement('div');
-  composerRolePopover.className = 'agent-thread-card__composer-note-popover';
+  composerRolePopover.className = 'agent-composer__note-popover';
   composerRolePopover.setAttribute('role', 'menu');
   composerRolePopover.hidden = true;
   const composerAddPopover = document.createElement('div');
-  composerAddPopover.className = 'agent-thread-card__composer-add-popover';
+  composerAddPopover.className = 'agent-composer__add-popover';
   composerAddPopover.setAttribute('role', 'menu');
   composerAddPopover.hidden = true;
   composerActions.append(composerRoleIcon);
@@ -158,7 +157,8 @@ export function createAgentComposerDom(
   // flex (默认 row, DOM 顺序 = 视觉顺序) 状态下添加按钮显示在 input
   // 左侧, 跟全屏态 grid 布局 `grid-column: 1` 把 actions 显式钉在第一列
   // ── 视觉位置对齐。 send button 仍以 sendButtonMount 收尾, 留在最右。
-  composer.append(composerImages, composerActions, input, sendButtonMount);
+  inputRow.append(input);
+  composer.append(composerActions, inputRow, sendButtonMount);
   document.body.append(codexSettingsPopover, composerAddPopover, composerRolePopover);
   // 空区域点击聚焦 ── 见上方 COMPOSER_FOCUS_INTERACTIVE_SELECTOR 注释。
   // 优先使用 pointerdown，避免 click 时浏览器先把焦点移到 body；
@@ -168,7 +168,7 @@ export function createAgentComposerDom(
   composer.addEventListener('click', handleComposerClick);
   return {
     composer,
-    composerImages,
+    inputRow,
     composerActions,
     composerRoleIcon,
     input,
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.test.ts
index 461afc8ac..607f94175 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.test.ts
@@ -155,7 +155,7 @@ describe("ComposerFolderController", () => {
     const markdown = editor.getMarkdown();
     expect(markdown).toContain("flowix://folder/%2FUsers%2Frop%2FDesktop%2Fvibe%2Fflowix-main");
     expect(composerFolderMarkdownToPrompt(markdown)).toBe("请操作 @flowix-main ");
-    expect(document.querySelector(".agent-thread-card__folder-token")?.textContent)
+    expect(document.querySelector(".agent-composer__folder-token")?.textContent)
       .toBe("@flowix-main");
 
     controller.dispose();
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.ts
index b18940b83..95dfe7de9 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-folder-controller.ts
@@ -13,6 +13,7 @@ export interface ComposerFolderReference {
 }
 
 const NOTE_SEARCH_DEBOUNCE_MS = 150;
+const MENU_SCROLLBAR_HIDE_DELAY_MS = 700;
 
 export interface ComposerFolderControllerOptions {
   editor: Editor;
@@ -49,6 +50,7 @@ export class ComposerFolderController {
   private notesLoading = false;
   private notesRequestGeneration = 0;
   private notesSearchTimer: ReturnType<typeof setTimeout> | null = null;
+  private menuScrollbarHideTimer: ReturnType<typeof setTimeout> | null = null;
   private activeIndex = 0;
   private isKeyboardNavigation = true;
   private dismissedValue: string | null = null;
@@ -296,12 +298,27 @@ export class ComposerFolderController {
       this.menu.className = "agent-composer-slash-menu agent-composer-slash-menu--folder";
       this.menu.setAttribute("role", "listbox");
       this.menu.setAttribute("aria-label", "资料和笔记");
+      this.menu.setAttribute("data-flowix-surface", "popover");
+      this.menu.addEventListener("scroll", this.handleMenuScroll, { passive: true });
       document.body.append(this.menu);
     }
     this.renderMenuItems();
     this.updateMenuPosition();
   }
 
+  private readonly handleMenuScroll = (): void => {
+    const menu = this.menu;
+    if (!menu) return;
+    menu.dataset.scrolling = "true";
+    if (this.menuScrollbarHideTimer !== null) {
+      clearTimeout(this.menuScrollbarHideTimer);
+    }
+    this.menuScrollbarHideTimer = setTimeout(() => {
+      if (this.menu === menu) delete menu.dataset.scrolling;
+      this.menuScrollbarHideTimer = null;
+    }, MENU_SCROLLBAR_HIDE_DELAY_MS);
+  };
+
   private renderMenuItems(): void {
     const menu = this.menu;
     if (!menu) return;
@@ -439,6 +456,10 @@ export class ComposerFolderController {
   }
 
   private closeMenu(): void {
+    if (this.menuScrollbarHideTimer !== null) {
+      clearTimeout(this.menuScrollbarHideTimer);
+      this.menuScrollbarHideTimer = null;
+    }
     this.menu?.remove();
     this.menu = null;
     this.mentionRange = null;
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-folder-data.ts b/app/flowix-web/features/agent/thread-card/composer/composer-folder-data.ts
index 5ffa301d8..8153dc584 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-folder-data.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-folder-data.ts
@@ -1,38 +1,15 @@
-import { resolveNotebookAgentFiles } from "@/lib/agent-access-defaults";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
+import { getWorkspaceAgentRepositories } from "@features/agent/public/workspace-api";
 import { useNoteStore } from "@features/memo/store/note-store";
 import type { ComposerFolderReference } from "./composer-folder-controller";
 
-function comparablePath(path: string): string {
-  return path.trim().replace(/[\\/]+$/, "").toLowerCase();
-}
-
-function fallbackFolderName(path: string): string {
-  const normalized = path.replace(/[\\/]+$/, "");
-  return normalized.split(/[\\/]/).pop() || normalized || path;
-}
-
 /** Read the folders configured for the notebook that owns the current note. */
 export function getCurrentNotebookComposerFolders(): readonly ComposerFolderReference[] {
   const memoState = useNoteStore.getState();
   const notebook = memoState.selectedNotebook;
   if (!notebook) return [];
 
-  const accessState = useAgentAccessStore.getState();
-  const configured = resolveNotebookAgentFiles(
-    accessState.config,
-    accessState.notebookConfigs,
-    notebook.id,
-  );
-  const entries = accessState.config.entries;
-  const entryByPath = new Map(
-    entries
-      .filter((entry) => entry.kind === "folder")
-      .map((entry) => [comparablePath(entry.path), entry]),
-  );
-
-  return (configured?.folders ?? []).map((path) => ({
-    path,
-    name: entryByPath.get(comparablePath(path))?.name || fallbackFolderName(path),
+  return getWorkspaceAgentRepositories(notebook.id).map((repository) => ({
+    path: repository.path,
+    name: repository.name,
   }));
 }
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-folder-token.ts b/app/flowix-web/features/agent/thread-card/composer/composer-folder-token.ts
index f3a67c2ab..d0d4c2ac9 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-folder-token.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-folder-token.ts
@@ -1,4 +1,11 @@
 import { Node, type Editor, type JSONContent, type MarkdownToken } from "@tiptap/core";
+import folderOutlineSvg from "@/assets/folder-outline.svg?raw";
+import {
+  createInlineAtomCloseIcon,
+  createInlineAtomNodeView,
+  deleteInlineAtomNode,
+  deleteAdjacentInlineAtom,
+} from "@features/editor/extensions/shared/inline-atom-nodeview";
 
 export interface ComposerFolderTokenValue {
   path: string;
@@ -59,7 +66,7 @@ export const ComposerFolderToken = Node.create({
     return ["span", {
       "data-composer-folder": path,
       "data-composer-folder-display-name": displayName,
-      class: "agent-thread-card__folder-token",
+      class: "agent-composer__folder-token",
     }, `@${displayName}`];
   },
 
@@ -110,20 +117,38 @@ export const ComposerFolderToken = Node.create({
         path,
         typeof node.attrs.displayName === "string" ? node.attrs.displayName : undefined,
       );
-      const button = document.createElement("button");
-      button.type = "button";
-      button.className = "agent-thread-card__folder-token";
-      button.textContent = `@${displayName}`;
-      button.title = path;
-      button.setAttribute("aria-label", `移除资料库 ${displayName}`);
-      button.addEventListener("mousedown", (event) => event.preventDefault());
-      button.addEventListener("click", () => {
-        const pos = typeof getPos === "function" ? getPos() : undefined;
-        if (pos === undefined) return;
-        view.dispatch(view.state.tr.delete(pos, pos + node.nodeSize));
-        view.focus();
+      const iconTemplate = document.createElement("template");
+      iconTemplate.innerHTML = folderOutlineSvg;
+      const folderIcon = iconTemplate.content.firstElementChild;
+      folderIcon?.classList.add("agent-composer__folder-token-icon");
+      const nodeView = createInlineAtomNodeView({
+        caretGeometry: 'single-line',
+        wrapperClassName: "agent-composer__inline-atom-wrapper agent-composer__folder-token-wrapper",
+        cardClassName: "agent-composer__folder-token",
+        leadingIcon: folderIcon ?? undefined,
+        label: displayName,
+        labelClassName: "agent-composer__folder-token-label",
+        title: path,
+        hoverActions: [{
+          ariaLabel: `移除资料库 ${displayName}`,
+          icon: createInlineAtomCloseIcon(),
+          onClick: () => deleteInlineAtomNode(
+            view,
+            node,
+            () => typeof getPos === "function" ? getPos() : undefined,
+          ),
+        }],
       });
-      return { dom: button };
+      nodeView.dom.setAttribute("data-composer-folder", path);
+      nodeView.dom.setAttribute("data-composer-folder-display-name", displayName);
+      return nodeView;
+    };
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      Backspace: () => deleteAdjacentInlineAtom(this.editor, "composerFolderToken", "before"),
+      Delete: () => deleteAdjacentInlineAtom(this.editor, "composerFolderToken", "after"),
     };
   },
 });
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-image-controller.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-image-controller.test.ts
deleted file mode 100644
index af6d06de9..000000000
--- a/app/flowix-web/features/agent/thread-card/composer/composer-image-controller.test.ts
+++ /dev/null
@@ -1,182 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-const mocks = vi.hoisted(() => ({
-  cacheImage: vi.fn(),
-  deleteCachedImage: vi.fn(),
-  readCachedImage: vi.fn(),
-}));
-
-vi.mock("@platform/tauri/client", () => ({
-  agent: {
-    cacheImage: mocks.cacheImage,
-    deleteCachedImage: mocks.deleteCachedImage,
-    readCachedImage: mocks.readCachedImage,
-  },
-}));
-
-import { ComposerImageController } from "./composer-image-controller";
-
-describe("ComposerImageController", () => {
-  afterEach(() => {
-    document.body.replaceChildren();
-    vi.clearAllMocks();
-  });
-
-  it("caches a pasted image, renders a card, and deletes it on request", async () => {
-    mocks.cacheImage.mockResolvedValue({
-      path: "/tmp/cached.png",
-      mimeType: "image/png",
-      name: "cached.png",
-    });
-    mocks.deleteCachedImage.mockResolvedValue(true);
-    const input = document.createElement("textarea");
-    const container = document.createElement("div");
-    const composer = document.createElement("div");
-    composer.append(container, input);
-    document.body.append(composer);
-    const onChange = vi.fn();
-    const controller = new ComposerImageController({
-      input,
-      container,
-      initialImages: [],
-      onChange,
-      onStateChange: vi.fn(),
-      onError: vi.fn(),
-      onLimitExceeded: vi.fn(),
-    });
-    const file = new File([new Uint8Array([1, 2, 3])], "paste.png", {
-      type: "image/png",
-    });
-    const paste = new Event("paste", { bubbles: true, cancelable: true });
-    Object.defineProperty(paste, "clipboardData", {
-      value: {
-        items: [{ kind: "file", type: "image/png", getAsFile: () => file }],
-      },
-    });
-    input.dispatchEvent(paste);
-
-    await vi.waitFor(() => {
-      expect(controller.hasPending).toBe(false);
-    });
-    expect(mocks.cacheImage).toHaveBeenCalled();
-    expect(container.querySelector("img")).not.toBeNull();
-    expect(onChange).toHaveBeenCalledWith([
-      expect.objectContaining({ path: "/tmp/cached.png" }),
-    ]);
-
-    (container.querySelector("button") as HTMLButtonElement).click();
-    expect(container.querySelector("img")).toBeNull();
-    expect(mocks.deleteCachedImage).toHaveBeenCalledWith("/tmp/cached.png");
-    controller.dispose();
-  });
-
-  it("loads persisted image previews through the guarded cache reader", async () => {
-    mocks.readCachedImage.mockResolvedValue("data:image/png;base64,AQID");
-    const input = document.createElement("textarea");
-    const container = document.createElement("div");
-    const composer = document.createElement("div");
-    composer.append(container, input);
-    document.body.append(composer);
-    const controller = new ComposerImageController({
-      input,
-      container,
-      initialImages: [{
-        path: "/tmp/persisted.png",
-        mimeType: "image/png",
-        name: "persisted.png",
-      }],
-      onChange: vi.fn(),
-      onStateChange: vi.fn(),
-      onError: vi.fn(),
-      onLimitExceeded: vi.fn(),
-    });
-
-    await Promise.resolve();
-    await Promise.resolve();
-    expect(mocks.readCachedImage).toHaveBeenCalledWith("/tmp/persisted.png");
-    expect(container.querySelector("img")?.src).toContain(
-      "data:image/png;base64,AQID",
-    );
-    controller.dispose();
-  });
-
-  it("removes persisted metadata when the cached file is missing", async () => {
-    mocks.readCachedImage.mockResolvedValue(null);
-    const input = document.createElement("textarea");
-    const container = document.createElement("div");
-    const composer = document.createElement("div");
-    composer.append(container, input);
-    const onChange = vi.fn();
-    const controller = new ComposerImageController({
-      input,
-      container,
-      initialImages: [{
-        path: "/tmp/missing.png",
-        mimeType: "image/png",
-        name: "missing.png",
-      }],
-      onChange,
-      onStateChange: vi.fn(),
-      onError: vi.fn(),
-      onLimitExceeded: vi.fn(),
-    });
-
-    await Promise.resolve();
-    await Promise.resolve();
-    expect(controller.hasImages).toBe(false);
-    expect(onChange).toHaveBeenCalledWith([]);
-    expect(mocks.deleteCachedImage).not.toHaveBeenCalled();
-    controller.dispose();
-  });
-
-  it("accepts at most five images and rejects files larger than 5 MB", async () => {
-    mocks.cacheImage.mockImplementation(async (_content: string, _type: string) => ({
-      path: `/tmp/${mocks.cacheImage.mock.calls.length}.png`,
-      mimeType: "image/png",
-      name: "cached.png",
-    }));
-    const input = document.createElement("textarea");
-    const container = document.createElement("div");
-    const composer = document.createElement("div");
-    composer.append(container, input);
-    const onError = vi.fn();
-    const onLimitExceeded = vi.fn();
-    const controller = new ComposerImageController({
-      input,
-      container,
-      initialImages: [],
-      onChange: vi.fn(),
-      onStateChange: vi.fn(),
-      onError,
-      onLimitExceeded,
-    });
-    const smallFiles = Array.from({ length: 6 }, (_, index) =>
-      new File([new Uint8Array([index])], `${index}.png`, { type: "image/png" }),
-    );
-    const oversized = new File(
-      [new Uint8Array(5 * 1024 * 1024 + 1)],
-      "large.png",
-      { type: "image/png" },
-    );
-    const paste = new Event("paste", { bubbles: true, cancelable: true });
-    Object.defineProperty(paste, "clipboardData", {
-      value: {
-        items: [...smallFiles, oversized].map((file) => ({
-          kind: "file",
-          type: "image/png",
-          getAsFile: () => file,
-        })),
-      },
-    });
-    input.dispatchEvent(paste);
-
-    await vi.waitFor(() => {
-      expect(controller.hasPending).toBe(false);
-    });
-    expect(mocks.cacheImage).toHaveBeenCalledTimes(5);
-    expect(onLimitExceeded).toHaveBeenCalledWith("size");
-    expect(onLimitExceeded).toHaveBeenCalledWith("count");
-    expect(onError).not.toHaveBeenCalled();
-    controller.dispose();
-  });
-});
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-image-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-image-controller.ts
deleted file mode 100644
index 61c7ea9e9..000000000
--- a/app/flowix-web/features/agent/thread-card/composer/composer-image-controller.ts
+++ /dev/null
@@ -1,252 +0,0 @@
-import { agent, type CachedAgentImage } from "@platform/tauri/client";
-
-export type AgentThreadCardInputImage = CachedAgentImage;
-
-const MAX_COMPOSER_IMAGE_BYTES = 5 * 1024 * 1024;
-const MAX_COMPOSER_IMAGE_COUNT = 5;
-
-export const COMPOSER_ATTACHMENT_ACCEPT = [
-  "image/*", ".doc", ".docx", ".pdf", ".xls", ".xlsx", ".ppt", ".pptx",
-].join(",");
-
-const SUPPORTED_ATTACHMENT_MIME_TYPES = new Set([
-  "application/msword",
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  "application/pdf",
-  "application/vnd.ms-excel",
-  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  "application/vnd.ms-powerpoint",
-  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-]);
-
-function isSupportedAttachment(file: File): boolean {
-  return Boolean(getAttachmentMimeType(file));
-}
-
-function getAttachmentMimeType(file: File): string | null {
-  const mimeType = file.type.toLowerCase();
-  if (mimeType.startsWith("image/") || SUPPORTED_ATTACHMENT_MIME_TYPES.has(mimeType)) {
-    return mimeType;
-  }
-  const extension = file.name.toLowerCase().split(".").pop();
-  const byExtension: Record<string, string> = {
-    doc: "application/msword",
-    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-    pdf: "application/pdf",
-    xls: "application/vnd.ms-excel",
-    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-    ppt: "application/vnd.ms-powerpoint",
-    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  };
-  return (extension && byExtension[extension]) || null;
-}
-
-function isImageAttachment(file: { mimeType: string }): boolean {
-  return file.mimeType.toLowerCase().startsWith("image/");
-}
-
-export interface ComposerImageControllerOptions {
-  input: HTMLElement;
-  container: HTMLElement;
-  initialImages: AgentThreadCardInputImage[];
-  onChange: (images: AgentThreadCardInputImage[]) => void;
-  onStateChange: () => void;
-  onError: (message: string) => void;
-  onLimitExceeded: (kind: "count" | "size") => void;
-}
-
-function readFileAsDataUrl(file: File): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => resolve(String(reader.result ?? ""));
-    reader.onerror = () => reject(reader.error ?? new Error("Failed to read image"));
-    reader.readAsDataURL(file);
-  });
-}
-
-export class ComposerImageController {
-  private images: AgentThreadCardInputImage[];
-  private readonly previews = new Map<string, string>();
-  private pending = 0;
-  private disposed = false;
-  private locked = false;
-
-  constructor(private readonly options: ComposerImageControllerOptions) {
-    this.images = options.initialImages.slice(0, MAX_COMPOSER_IMAGE_COUNT);
-    options.input.addEventListener("paste", this.handlePaste);
-    this.render();
-    for (const image of this.images) {
-      if (isImageAttachment(image)) void this.loadPreview(image);
-    }
-  }
-
-  get readyImages(): AgentThreadCardInputImage[] {
-    return [...this.images];
-  }
-
-  get hasImages(): boolean {
-    return this.images.length > 0;
-  }
-
-  get hasPending(): boolean {
-    return this.pending > 0;
-  }
-
-  /** Add picker-selected attachments through the same cache path as pasted images. */
-  addFiles(files: File[]): void {
-    if (this.locked || this.disposed) return;
-    const eligibleFiles = files.filter((file) => {
-      if (!isSupportedAttachment(file)) return false;
-      if (file.size <= MAX_COMPOSER_IMAGE_BYTES) return true;
-      this.options.onLimitExceeded("size");
-      return false;
-    });
-    const availableSlots = Math.max(
-      0,
-      MAX_COMPOSER_IMAGE_COUNT - this.images.length - this.pending,
-    );
-    if (eligibleFiles.length > availableSlots) {
-      this.options.onLimitExceeded("count");
-    }
-    for (const file of eligibleFiles.slice(0, availableSlots)) {
-      void this.cache(file);
-    }
-  }
-
-  clearAfterSubmit(): void {
-    this.images = [];
-    this.previews.clear();
-    this.options.onChange([]);
-    this.render();
-    this.options.onStateChange();
-  }
-
-  /** Keep in-flight request files available until the request is accepted. */
-  setLocked(locked: boolean): void {
-    if (this.disposed || this.locked === locked) return;
-    this.locked = locked;
-    this.render();
-  }
-
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.options.input.removeEventListener("paste", this.handlePaste);
-    this.options.container.replaceChildren();
-    this.previews.clear();
-  }
-
-  private readonly handlePaste = (event: ClipboardEvent): void => {
-    const files = Array.from(event.clipboardData?.items ?? [])
-      .filter((item) => item.kind === "file" && item.type.startsWith("image/"))
-      .map((item) => item.getAsFile())
-      .filter((file): file is File => !!file);
-    if (files.length === 0) return;
-
-    // Clipboard image payloads often also contain a generated filename as text.
-    // Prevent that text from being inserted; genuine text-only paste stays native.
-    event.preventDefault();
-    this.addFiles(files);
-  };
-
-  private async cache(file: File): Promise<void> {
-    this.pending += 1;
-    this.options.onStateChange();
-    try {
-      const content = await readFileAsDataUrl(file);
-      const cached = await agent.cacheImage(content, getAttachmentMimeType(file) ?? file.type);
-      if (this.disposed) {
-        void agent.deleteCachedImage(cached.path).catch(() => undefined);
-        return;
-      }
-      this.previews.set(cached.path, content);
-      this.images = [...this.images, cached];
-      this.options.onChange(this.readyImages);
-      this.render();
-    } catch (error) {
-      this.options.onError(error instanceof Error ? error.message : String(error));
-    } finally {
-      this.pending = Math.max(0, this.pending - 1);
-      this.options.onStateChange();
-    }
-  }
-
-  private remove(
-    image: AgentThreadCardInputImage,
-    deleteCachedFile: boolean = true,
-  ): void {
-    if (this.locked && deleteCachedFile) return;
-    this.images = this.images.filter((candidate) => candidate.path !== image.path);
-    this.previews.delete(image.path);
-    this.options.onChange(this.readyImages);
-    this.render();
-    this.options.onStateChange();
-    if (deleteCachedFile) {
-      void agent.deleteCachedImage(image.path).catch(() => undefined);
-    }
-  }
-
-  private async loadPreview(image: AgentThreadCardInputImage): Promise<void> {
-    try {
-      const content = await agent.readCachedImage(image.path);
-      if (this.disposed) return;
-      if (!content) {
-        this.remove(image, false);
-        return;
-      }
-      if (!this.images.some((candidate) => candidate.path === image.path)) return;
-      this.previews.set(image.path, content);
-      this.render();
-    } catch (error) {
-      if (!this.disposed) {
-        this.options.onError(
-          error instanceof Error ? error.message : String(error),
-        );
-      }
-    }
-  }
-
-  private render(): void {
-    const cards = this.images.map((image) => {
-      const card = document.createElement("span");
-      card.className = "agent-thread-card__composer-image";
-
-      const previewUrl = this.previews.get(image.path);
-      const preview = previewUrl ? document.createElement("img") : null;
-      if (preview && previewUrl) {
-        preview.src = previewUrl;
-        preview.alt = image.name;
-        preview.draggable = false;
-      }
-
-      const remove = document.createElement("button");
-      remove.type = "button";
-      remove.disabled = this.locked;
-      remove.className = "agent-thread-card__composer-image-remove";
-      remove.setAttribute("aria-label", "Remove image");
-      remove.textContent = "×";
-      remove.addEventListener("click", (event) => {
-        event.preventDefault();
-        event.stopPropagation();
-        this.remove(image);
-      });
-      if (preview) {
-        card.append(preview);
-      } else if (!isImageAttachment(image)) {
-        const name = document.createElement("span");
-        name.className = "agent-thread-card__composer-attachment-name";
-        name.textContent = image.name;
-        name.title = image.name;
-        card.append(name);
-      }
-      card.append(remove);
-      return card;
-    });
-    this.options.container.replaceChildren(...cards);
-    this.options.container.hidden = cards.length === 0;
-    this.options.container.parentElement?.classList.toggle(
-      "agent-thread-card__composer--has-images",
-      cards.length > 0,
-    );
-  }
-}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-inline-atom-caret.ts b/app/flowix-web/features/agent/thread-card/composer/composer-inline-atom-caret.ts
new file mode 100644
index 000000000..eabaa0d2a
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-inline-atom-caret.ts
@@ -0,0 +1,39 @@
+import { Extension } from "@tiptap/core";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { DecorationSet } from "@tiptap/pm/view";
+import { createTerminalInlineAtomCaretDecorations } from "@features/editor/extensions/shared/terminal-inline-atom-caret";
+import { COMPOSER_ATTACHMENT_NODE_NAME } from "./composer-attachment-compat";
+
+const composerInlineAtomCaretPluginKey = new PluginKey<DecorationSet>(
+  "composerInlineAtomCaret",
+);
+
+/** Supplies a terminal caret anchor so browser trailing breaks do not add an
+ * extra line after composer-only inline chips. */
+export const ComposerInlineAtomCaret = Extension.create({
+  name: "composerInlineAtomCaret",
+
+  addProseMirrorPlugins() {
+    const nodeNames = [
+      "composerFolderToken",
+      "composerSkillToken",
+      COMPOSER_ATTACHMENT_NODE_NAME,
+    ];
+
+    return [new Plugin({
+      key: composerInlineAtomCaretPluginKey,
+      state: {
+        init: (_, state) => createTerminalInlineAtomCaretDecorations(state.doc, nodeNames),
+        apply: (transaction, value, _oldState, newState) => (
+          transaction.docChanged
+            ? createTerminalInlineAtomCaretDecorations(newState.doc, nodeNames)
+            : value
+        ),
+      },
+      props: {
+        decorations: (state) => composerInlineAtomCaretPluginKey.getState(state)
+          ?? DecorationSet.empty,
+      },
+    })];
+  },
+});
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-insertion-anchor.ts b/app/flowix-web/features/agent/thread-card/composer/composer-insertion-anchor.ts
new file mode 100644
index 000000000..0aef01f1d
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-insertion-anchor.ts
@@ -0,0 +1,36 @@
+import type { Editor } from '@tiptap/core';
+import { TextSelection, type Transaction } from '@tiptap/pm/state';
+
+export interface ComposerInsertionPoint { from: number; to: number }
+
+/** A saved editor selection mapped through every transaction while files load. */
+export interface ComposerInsertionAnchor {
+  resolve(): ComposerInsertionPoint | undefined;
+  advance(point: ComposerInsertionPoint): void;
+  dispose(): void;
+}
+
+export function captureComposerInsertionAnchor(editor: Editor): ComposerInsertionAnchor {
+  let bookmark = editor.state.selection.getBookmark();
+  let disposed = false;
+  const mapBookmark = ({ transaction }: { transaction: Transaction }) => {
+    bookmark = bookmark.map(transaction.mapping);
+  };
+  editor.on('transaction', mapBookmark);
+  return {
+    resolve() {
+      if (disposed || editor.isDestroyed) return undefined;
+      const selection = bookmark.resolve(editor.state.doc);
+      return { from: selection.from, to: selection.to };
+    },
+    advance(point) {
+      if (disposed || editor.isDestroyed) return;
+      bookmark = TextSelection.create(editor.state.doc, point.to).getBookmark();
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      editor.off('transaction', mapBookmark);
+    },
+  };
+}
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-skill-token.ts b/app/flowix-web/features/agent/thread-card/composer/composer-skill-token.ts
index 4131395b5..93645ccda 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-skill-token.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-skill-token.ts
@@ -1,4 +1,11 @@
 import { Node, type Editor, type JSONContent, type MarkdownToken } from "@tiptap/core";
+import skillLibraryIconSvg from "@/assets/skill-library.svg?raw";
+import {
+  createInlineAtomCloseIcon,
+  createInlineAtomNodeView,
+  deleteInlineAtomNode,
+  deleteAdjacentInlineAtom,
+} from "@features/editor/extensions/shared/inline-atom-nodeview";
 
 export interface ComposerSkillTokenValue {
   name: string;
@@ -64,7 +71,7 @@ export const ComposerSkillToken = Node.create({
     return ["span", {
       "data-composer-skill": name,
       ...(displayName ? { "data-composer-skill-display-name": displayName } : {}),
-      class: "agent-thread-card__skill-token",
+      class: "agent-composer__skill-token",
     }, displayNameForComposerSkill(name, displayName)];
   },
 
@@ -115,20 +122,34 @@ export const ComposerSkillToken = Node.create({
         name,
         typeof node.attrs.displayName === "string" ? node.attrs.displayName : undefined,
       );
-      const button = document.createElement("button");
-      button.type = "button";
-      button.className = "agent-thread-card__skill-token";
-      button.textContent = displayName;
-      button.title = `$${name}`;
-      button.setAttribute("aria-label", `移除 Skill ${displayName}`);
-      button.addEventListener("mousedown", (event) => event.preventDefault());
-      button.addEventListener("click", () => {
-        const pos = typeof getPos === "function" ? getPos() : undefined;
-        if (pos === undefined) return;
-        view.dispatch(view.state.tr.delete(pos, pos + node.nodeSize));
-        view.focus();
+      const iconTemplate = document.createElement("template");
+      iconTemplate.innerHTML = skillLibraryIconSvg;
+      const nodeView = createInlineAtomNodeView({
+        caretGeometry: 'single-line',
+        wrapperClassName: "agent-composer__inline-atom-wrapper agent-composer__skill-token-wrapper",
+        cardClassName: "agent-composer__skill-token",
+        leadingIcon: iconTemplate.content.firstElementChild ?? undefined,
+        label: displayName,
+        labelClassName: "agent-composer__skill-token-label",
+        title: `$${name}`,
+        hoverActions: [{
+          ariaLabel: `移除 Skill ${displayName}`,
+          icon: createInlineAtomCloseIcon(),
+          onClick: () => deleteInlineAtomNode(
+            view,
+            node,
+            () => typeof getPos === "function" ? getPos() : undefined,
+          ),
+        }],
       });
-      return { dom: button };
+      return nodeView;
+    };
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      Backspace: () => deleteAdjacentInlineAtom(this.editor, "composerSkillToken", "before"),
+      Delete: () => deleteAdjacentInlineAtom(this.editor, "composerSkillToken", "after"),
     };
   },
 });
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.test.ts
index e366559d9..735d003cf 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.test.ts
@@ -1,6 +1,8 @@
 import { Editor } from '@tiptap/core';
 import StarterKit from '@tiptap/starter-kit';
 import { Markdown } from '@tiptap/markdown';
+import { translate } from '@/lib/i18n';
+import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
@@ -12,7 +14,7 @@ import {
 import { ComposerSlashToken } from './composer-slash-token';
 
 function setup(options: {
-  agentType?: 'deepseek-harness' | 'codex';
+  agentType?: 'dsh' | 'codex';
   onModelSelect?: () => void;
   onPermissionSelect?: () => void;
   onDirectCommand?: (command: ComposerSlashCommand) => void;
@@ -21,7 +23,10 @@ function setup(options: {
   const composer = document.createElement('div');
   const input = document.createElement('div');
   input.contentEditable = 'true';
-  composer.append(input);
+  const inputRow = document.createElement('div');
+  inputRow.className = 'agent-composer__input-row';
+  inputRow.append(input);
+  composer.append(inputRow);
   document.body.append(composer);
   vi.spyOn(composer, 'getBoundingClientRect').mockReturnValue({
     x: 20,
@@ -36,8 +41,7 @@ function setup(options: {
   });
   const editor = new Editor({
     // Use the same mount contract as ComposerController. The input itself is
-    // ProseMirror's root; the slash controller then moves that root into the
-    // input row without introducing a nested editor.
+    // ProseMirror's root inside the factory-owned input row.
     element: { mount: input },
     extensions: [StarterKit, Markdown, ComposerSlashToken],
     content: '',
@@ -47,7 +51,7 @@ function setup(options: {
     input,
     composer,
     editor,
-    agentType: options.agentType ?? 'deepseek-harness',
+    agentType: options.agentType ?? 'dsh',
     onModelSelect: options.onModelSelect,
     onPermissionSelect: options.onPermissionSelect,
     onDirectCommand: options.onDirectCommand,
@@ -73,7 +77,7 @@ describe('ComposerSlashCommandController', () => {
     type(editor, '/export');
     input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
     expect(onDirectCommand).toHaveBeenCalledWith(expect.objectContaining({ name: 'export' }));
-    expect(editor.getMarkdown()).toContain('flowix://slash/deepseek-harness/export');
+    expect(editor.getMarkdown()).toContain('flowix://slash/dsh/export');
     controller.dispose();
     editor.destroy();
   });
@@ -99,7 +103,7 @@ describe('ComposerSlashCommandController', () => {
     const { input, editor, controller } = setup();
     const row = input.parentElement;
 
-    expect(row?.classList.contains('agent-thread-card__composer-input-row')).toBe(true);
+    expect(row?.classList.contains('agent-composer__input-row')).toBe(true);
     input.blur();
     row?.dispatchEvent(new MouseEvent('mousedown', {
       bubbles: true,
@@ -149,16 +153,16 @@ describe('ComposerSlashCommandController', () => {
     type(editor, '/goal');
     input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
 
-    expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/deepseek-harness/goal) ');
-    expect(composer.querySelector('.agent-thread-card__slash-token')?.textContent).toBe('/goal');
+    expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/dsh/goal) ');
+    expect(composer.querySelector('.agent-thread-card__slash-token')?.textContent).toBe(translate(getCurrentAppLanguage(), 'editor.threadCard.composer.longTask'));
     expect(composer.querySelector('.agent-thread-card__slash-token--control')).not.toBeNull();
     const wrapper = composer.querySelector('.agent-thread-card__slash-token-wrapper');
-    expect(wrapper?.childNodes).toHaveLength(2);
-    expect(wrapper?.firstChild?.textContent).toBe('/goal');
+    expect(wrapper?.childNodes).toHaveLength(3);
+    expect(wrapper?.firstChild?.textContent).toBe('\u200B');
     expect(wrapper?.lastChild?.textContent).toBe('\u200B');
 
     editor.commands.insertContent('继续输入');
-    expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/deepseek-harness/goal) 继续输入');
+    expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/dsh/goal) 继续输入');
 
     editor.commands.focus('start');
     input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Backspace', bubbles: true }));
@@ -198,7 +202,10 @@ describe('ComposerSlashCommandController', () => {
     const onModelSelect = vi.fn();
     const composer = document.createElement('div');
     const input = document.createElement('div');
-    composer.append(input);
+    const inputRow = document.createElement('div');
+  inputRow.className = 'agent-composer__input-row';
+  inputRow.append(input);
+  composer.append(inputRow);
     document.body.append(composer);
     const editor = new Editor({
       element: { mount: input },
@@ -282,7 +289,7 @@ describe('ComposerSlashCommandController', () => {
     )].find((candidate) => candidate.textContent?.includes('/goal'));
     item?.click();
 
-    expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/deepseek-harness/goal) ');
+    expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/dsh/goal) ');
     expect(document.querySelector('.agent-composer-slash-menu')).toBeNull();
     controller.dispose();
     editor.destroy();
@@ -293,7 +300,7 @@ describe('ComposerSlashCommandController', () => {
     editor.commands.setContent('[/goal](flowix://slash/goal)', { contentType: 'markdown' });
 
     expect(editor.getMarkdown()).toBe('[/goal](flowix://slash/goal)');
-    expect(composer.querySelector('.agent-thread-card__slash-token')?.textContent).toBe('/goal');
+    expect(composer.querySelector('.agent-thread-card__slash-token')?.textContent).toBe(translate(getCurrentAppLanguage(), 'editor.threadCard.composer.longTask'));
 
     controller.dispose();
     editor.destroy();
@@ -302,7 +309,10 @@ describe('ComposerSlashCommandController', () => {
   it('shows only Codex-supported commands in Codex composers', () => {
     const composer = document.createElement('div');
     const input = document.createElement('div');
-    composer.append(input);
+    const inputRow = document.createElement('div');
+  inputRow.className = 'agent-composer__input-row';
+  inputRow.append(input);
+  composer.append(inputRow);
     document.body.append(composer);
     const editor = new Editor({
       element: { mount: input },
@@ -331,7 +341,10 @@ describe('ComposerSlashCommandController', () => {
   it('does not open for a composer without an Agent type', () => {
     const composer = document.createElement('div');
     const input = document.createElement('div');
-    composer.append(input);
+    const inputRow = document.createElement('div');
+  inputRow.className = 'agent-composer__input-row';
+  inputRow.append(input);
+  composer.append(inputRow);
     document.body.append(composer);
     const editor = new Editor({
       element: { mount: input },
@@ -364,7 +377,10 @@ describe('ComposerSlashCommandController', () => {
     // focused on the static-menu path.
     const nextComposer = document.createElement('div');
     const nextInput = document.createElement('div');
-    nextComposer.append(nextInput);
+    const nextRow = document.createElement('div');
+    nextRow.className = 'agent-composer__input-row';
+    nextRow.append(nextInput);
+    nextComposer.append(nextRow);
     document.body.append(nextComposer);
     const nextEditor = new Editor({
       element: { mount: nextInput },
@@ -377,7 +393,7 @@ describe('ComposerSlashCommandController', () => {
       input: nextInput,
       composer: nextComposer,
       editor: nextEditor,
-      agentType: 'deepseek-harness',
+      agentType: 'dsh',
       listDshSkills,
     });
     type(nextEditor, '/');
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.ts
index c08b6e26c..1068ff5bd 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-slash-command-controller.ts
@@ -11,8 +11,11 @@ import {
 import type { AgentTypeKey } from "@/types/agent";
 
 import { COMPOSER_SLASH_COMMANDS, type ComposerSlashCommand } from "./composer-commands";
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
 export { COMPOSER_SLASH_COMMANDS, type ComposerSlashCommand } from "./composer-commands";
 
+const MENU_SCROLLBAR_HIDE_DELAY_MS = 700;
+
 export interface ComposerSlashSkill {
   name: string;
   description: string;
@@ -51,6 +54,7 @@ export interface ComposerSlashCommandControllerOptions {
   composer: HTMLElement;
   commands?: readonly ComposerSlashCommand[];
   agentType?: AgentTypeKey;
+  getSkillsScopeId?: () => string | undefined;
   listDshSkills?: () => Promise<readonly ComposerSlashSkill[]>;
   listCodexSkills?: () => Promise<readonly ComposerSlashSkill[]>;
   listPiSkills?: () => Promise<readonly ComposerSlashSkill[]>;
@@ -75,6 +79,7 @@ export class ComposerSlashCommandController {
   private readonly composer: HTMLElement;
   private readonly commands: readonly ComposerSlashCommand[];
   private readonly agentType: AgentTypeKey | undefined;
+  private readonly getSkillsScopeId: (() => string | undefined) | undefined;
   private readonly listDshSkills: (() => Promise<readonly ComposerSlashSkill[]>) | undefined;
   private readonly listCodexSkills: (() => Promise<readonly ComposerSlashSkill[]>) | undefined;
   private readonly listPiSkills: (() => Promise<readonly ComposerSlashSkill[]>) | undefined;
@@ -95,6 +100,7 @@ export class ComposerSlashCommandController {
   private dismissedValue: string | null = null;
   private slashActive = false;
   private disposed = false;
+  private menuScrollbarHideTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(options: ComposerSlashCommandControllerOptions) {
     this.editor = options.editor;
@@ -102,6 +108,7 @@ export class ComposerSlashCommandController {
     this.composer = options.composer;
     this.commands = options.commands ?? COMPOSER_SLASH_COMMANDS;
     this.agentType = options.agentType;
+    this.getSkillsScopeId = options.getSkillsScopeId;
     this.listDshSkills = options.listDshSkills;
     this.listCodexSkills = options.listCodexSkills;
     this.listPiSkills = options.listPiSkills;
@@ -115,10 +122,11 @@ export class ComposerSlashCommandController {
       this.editor.view.focus();
     });
 
-    this.inputRow = document.createElement("div");
-    this.inputRow.className = "agent-thread-card__composer-input-row";
-    this.input.before(this.inputRow);
-    this.inputRow.append(this.input);
+    const inputRow = this.input.parentElement;
+    if (!inputRow?.classList.contains("agent-composer__input-row")) {
+      throw new Error("Composer DOM must provide its input row before initialization");
+    }
+    this.inputRow = inputRow as HTMLDivElement;
 
     this.input.addEventListener("keydown", this.handleKeydown, true);
     // The row is the actual expanded/fullscreen grid item. It has clickable
@@ -151,10 +159,7 @@ export class ComposerSlashCommandController {
     window.removeEventListener("scroll", this.updateMenuPosition, true);
     this.closeMenu();
     removeComposerSlashToken(this.editor);
-    if (this.inputRow.isConnected) {
-      this.inputRow.before(this.input);
-      this.inputRow.remove();
-    }
+
   }
 
   refresh(): void {
@@ -183,7 +188,7 @@ export class ComposerSlashCommandController {
 
     // Refresh once per slash entry, including after a transient failure.
     // Filtering an open slash must not start another catalog request.
-    if ((this.agentType === "deepseek-harness" || this.agentType === "pi") && !this.slashActive &&
+    if ((this.agentType === "dsh" || this.agentType === "pi") && !this.slashActive &&
       (this.skillsStatus === "ready" || this.skillsStatus === "error")) {
       this.skillsStatus = "idle";
     }
@@ -324,12 +329,27 @@ export class ComposerSlashCommandController {
       this.menu.className = "agent-composer-slash-menu";
       this.menu.setAttribute("role", "listbox");
       this.menu.setAttribute("aria-label", "Slash commands");
+      this.menu.setAttribute("data-flowix-surface", "popover");
+      this.menu.addEventListener("scroll", this.handleMenuScroll, { passive: true });
       document.body.append(this.menu);
     }
     this.renderMenuItems();
     this.updateMenuPosition();
   }
 
+  private readonly handleMenuScroll = (): void => {
+    const menu = this.menu;
+    if (!menu) return;
+    menu.dataset.scrolling = "true";
+    if (this.menuScrollbarHideTimer !== null) {
+      clearTimeout(this.menuScrollbarHideTimer);
+    }
+    this.menuScrollbarHideTimer = setTimeout(() => {
+      if (this.menu === menu) delete menu.dataset.scrolling;
+      this.menuScrollbarHideTimer = null;
+    }, MENU_SCROLLBAR_HIDE_DELAY_MS);
+  };
+
   private renderMenuItems(): void {
     const menu = this.menu;
     if (!menu) return;
@@ -476,17 +496,25 @@ export class ComposerSlashCommandController {
       this.skillsStatus = "ready";
       return;
     }
-    this.skillsStatus = "loading";
+    const scopeId = this.getSkillsScopeId?.()?.trim() || "global";
+    const cached = useAgentDataStore.getState().agents[this.agentType].catalog.skillsByNotebookId[scopeId];
+    if (cached) this.skills = cached.items;
+    this.skillsStatus = cached ? "ready" : "loading";
     this.renderMenuItems();
-    this.skillsPromise = Promise.resolve().then(() => listSkills());
+    this.skillsPromise = useAgentDataStore.getState().loadSkillCatalog(
+      this.agentType,
+      scopeId,
+      async () => [...await listSkills()],
+    );
     try {
       const skills = await this.skillsPromise;
-      if (this.disposed) return;
+      const currentScopeId = this.getSkillsScopeId?.()?.trim() || "global";
+      if (this.disposed || currentScopeId !== scopeId) return;
       this.skills = skills;
       this.skillsStatus = "ready";
     } catch (error) {
       if (this.disposed) return;
-      this.skillsStatus = "error";
+      this.skillsStatus = this.skills.length ? "ready" : "error";
       console.warn(`Failed to load ${this.agentType} skills`, error);
     }
     this.activeIndex = Math.min(this.activeIndex, Math.max(0, this.filtered.length - 1));
@@ -498,9 +526,9 @@ export class ComposerSlashCommandController {
     if (this.agentType === "codex") {
       insertComposerSkillToken(this.editor, skill.name, skill.displayName);
     } else if (this.agentType === "pi") {
-      insertComposerSlashToken(this.editor, `skill:${skill.name}`, "pi");
+      insertComposerSlashToken(this.editor, `skill:${skill.name}`, "pi", skill.displayName);
     } else {
-      insertComposerSlashToken(this.editor, skill.name, "deepseek-harness");
+      insertComposerSlashToken(this.editor, skill.name, "dsh");
     }
     this.onCommandChange();
   }
@@ -513,6 +541,10 @@ export class ComposerSlashCommandController {
   }
 
   private closeMenu(): void {
+    if (this.menuScrollbarHideTimer !== null) {
+      clearTimeout(this.menuScrollbarHideTimer);
+      this.menuScrollbarHideTimer = null;
+    }
     this.menu?.remove();
     this.menu = null;
   }
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-slash-token.ts b/app/flowix-web/features/agent/thread-card/composer/composer-slash-token.ts
index bf1a0390f..f85760e7b 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-slash-token.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-slash-token.ts
@@ -1,7 +1,19 @@
 import { Node, type Editor, type JSONContent, type MarkdownToken } from "@tiptap/core";
 import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
-import { NodeSelection, Plugin, type EditorState } from "@tiptap/pm/state";
+import { Plugin, type EditorState } from "@tiptap/pm/state";
+import skillLibraryIconSvg from "@/assets/skill-library.svg?raw";
 import type { AgentTypeKey } from "@/types/agent";
+import { loadLanguage, translate } from "@/lib/i18n";
+import {
+  getCurrentAppLanguage,
+  subscribeAppLanguage,
+} from "@features/preferences/public/runtime-api";
+import {
+  createInlineAtomCloseIcon,
+  createInlineAtomNodeView,
+  deleteInlineAtomNode,
+  deleteAdjacentInlineAtom,
+} from "@features/editor/extensions/shared/inline-atom-nodeview";
 import { createTerminalInlineAtomCaretDecorations } from "@features/editor/extensions/shared/terminal-inline-atom-caret";
 
 export interface ComposerSlashTokenOptions {
@@ -13,8 +25,8 @@ export interface ComposerSlashTokenValue {
   agentType?: AgentTypeKey;
 }
 
-const SLASH_TOKEN_RE = /^\[\/([a-z0-9._:-]+)\]\(flowix:\/\/slash\/(?:(deepseek-harness|codex|pi)\/)?([a-z0-9._:-]+)\)/i;
-const SLASH_TOKEN_GLOBAL_RE = /\[\/([a-z0-9._:-]+)\]\(flowix:\/\/slash\/(?:(deepseek-harness|codex|pi)\/)?([a-z0-9._:-]+)\)/gi;
+const SLASH_TOKEN_RE = /^\[((?:\\.|[^\]\n])*)\]\(flowix:\/\/slash\/(?:(deepseek-harness|codex|pi)\/)?([a-z0-9._:-]+)\)/i;
+const SLASH_TOKEN_GLOBAL_RE = /\[((?:\\.|[^\]\n])*)\]\(flowix:\/\/slash\/(?:(deepseek-harness|codex|pi)\/)?([a-z0-9._:-]+)\)/gi;
 const LEGACY_DSH_COMMANDS = new Set([
   "compact",
   "skill",
@@ -30,12 +42,58 @@ function isControlCommand(command: string): boolean {
   return CONTROL_COMMANDS.has(command.trim().toLowerCase());
 }
 
+function isPiSkillCommand(command: string, agentType: string): boolean {
+  return agentType === "pi" && command.toLowerCase().startsWith("skill:");
+}
+
+function piSkillName(command: string): string {
+  return command.slice("skill:".length);
+}
+
+function escapeSlashTokenLabel(label: string): string {
+  return label.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+}
+
+function unescapeSlashTokenLabel(label: string): string {
+  return label.replace(/\\([\\[\]])/g, "$1");
+}
+
+function findSlashTokenStart(src: string, hrefIndex: number): number {
+  let start = src.lastIndexOf("[", hrefIndex);
+  while (start >= 0) {
+    let escapeCount = 0;
+    for (let index = start - 1; index >= 0 && src[index] === "\\"; index -= 1) {
+      escapeCount += 1;
+    }
+    if (escapeCount % 2 === 0) return start;
+    start = src.lastIndexOf("[", start - 1);
+  }
+  return -1;
+}
+
 function slashTokenClass(command: string): string {
   return isControlCommand(command)
     ? "agent-thread-card__slash-token agent-thread-card__slash-token--control"
     : "agent-thread-card__slash-token";
 }
 
+function slashTokenLabel(command: string): string {
+  const normalized = command.trim().toLowerCase();
+  if (normalized === "plan") {
+    return translate(getCurrentAppLanguage(), "editor.threadCard.composer.planMode");
+  }
+  if (normalized === "goal") {
+    return translate(getCurrentAppLanguage(), "editor.threadCard.composer.longTask");
+  }
+  return `/${command}`;
+}
+
+function createSkillLibraryIcon(): SVGSVGElement {
+  const template = document.createElement("template");
+  template.innerHTML = skillLibraryIconSvg;
+  return template.content.firstElementChild as SVGSVGElement;
+}
+
 export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
   name: "composerSlashToken",
   priority: 1000,
@@ -49,6 +107,7 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
     return {
       command: { default: "" },
       agentType: { default: null },
+      displayName: { default: null },
     };
   },
 
@@ -56,6 +115,7 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
     return [{ tag: "span[data-composer-slash]", getAttrs: (dom) => ({
       command: (dom as HTMLElement).getAttribute("data-composer-slash") ?? "",
       agentType: (dom as HTMLElement).getAttribute("data-composer-slash-agent") || null,
+      displayName: (dom as HTMLElement).getAttribute("data-composer-slash-display-name") || null,
     }) }];
   },
 
@@ -65,6 +125,9 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
     return ["span", {
       "data-composer-slash": command,
       ...(agentType ? { "data-composer-slash-agent": agentType } : {}),
+      ...(node.attrs?.displayName
+        ? { "data-composer-slash-display-name": String(node.attrs.displayName) }
+        : {}),
       class: "agent-thread-card__slash-token-wrapper",
     }, ["button", {
       class: slashTokenClass(command),
@@ -76,8 +139,8 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
     name: "composerSlashToken",
     level: "inline" as const,
     start(src: string) {
-      const index = src.indexOf("flowix://slash/");
-      return index >= 0 ? index : -1;
+      const hrefIndex = src.indexOf("flowix://slash/");
+      return hrefIndex >= 0 ? findSlashTokenStart(src, hrefIndex) : -1;
     },
     tokenize(src: string) {
       const match = SLASH_TOKEN_RE.exec(src);
@@ -85,7 +148,7 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
         type: "composerSlashToken",
         raw: match[0],
         href: `flowix://slash/${match[2] ? `${match[2]}/` : ""}${match[3]}`,
-        text: `/${match[1]}`,
+        text: match[1],
       } : undefined;
     },
   },
@@ -94,60 +157,82 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
     const href = String(token.href ?? "");
     const path = href.replace(/^flowix:\/\/slash\//i, "");
     const parts = path.split("/");
-    const agentType = parts[0] === "deepseek-harness" || parts[0] === "codex" || parts[0] === "pi"
+    const agentType = parts[0] === "dsh" || parts[0] === "codex" || parts[0] === "pi"
       ? parts[0]
       : undefined;
     const command = (agentType ? parts[1] : parts[0]) ||
       String(token.text ?? "").replace(/^\//, "");
-    return { type: "composerSlashToken", attrs: { command, agentType } };
+    const label = unescapeSlashTokenLabel(String(token.text ?? "").trim());
+    const isPiSkill = agentType === "pi" && command.toLowerCase().startsWith("skill:");
+    const displayName = isPiSkill && label !== `/${command}` ? label || null : null;
+    return { type: "composerSlashToken", attrs: { command, agentType, displayName } };
   },
 
   renderMarkdown(node: JSONContent) {
     const command = String(node.attrs?.command ?? "");
     const agentType = String(node.attrs?.agentType ?? "");
-    return `[/${command}](flowix://slash/${agentType ? `${agentType}/` : ""}${command})`;
+    const displayName = String(node.attrs?.displayName ?? "").trim();
+    const label = isPiSkillCommand(command, agentType)
+      ? displayName || piSkillName(command)
+      : `/${command}`;
+    return `[${escapeSlashTokenLabel(label)}](flowix://slash/${agentType ? `${agentType}/` : ""}${command})`;
   },
 
   addNodeView() {
     return ({ node, view, getPos }) => {
-      // Keep the atom's visual card separate from its terminal caret landing
-      // point. The trailing text node is deliberately real: a span boundary
-      // is not a reliable caret anchor in Chromium/WebKit. There is no
-      // leading spacer because it makes the native caret render inside the
-      // chip, unlike the other composer reference cards.
-      const wrapper = document.createElement("span");
-      wrapper.className = "agent-thread-card__slash-token-wrapper";
-      wrapper.contentEditable = "false";
-      wrapper.setAttribute("data-composer-slash", String(node.attrs.command ?? ""));
-      const agentType = String(node.attrs.agentType ?? "");
-      if (agentType) wrapper.setAttribute("data-composer-slash-agent", agentType);
-
-      const button = document.createElement("button");
       const command = String(node.attrs.command ?? "");
-      button.type = "button";
-      button.className = slashTokenClass(command);
-      button.textContent = `/${command}`;
-      button.title = "点击移除命令";
-      button.setAttribute("aria-label", `移除 /${command} 命令`);
-      button.addEventListener("mousedown", (event) => event.preventDefault());
-      button.addEventListener("click", (event) => {
-        event.preventDefault();
-        event.stopPropagation();
-        const pos = typeof getPos === "function" ? getPos() : undefined;
-        if (pos === undefined) return;
-        view.dispatch(view.state.tr.delete(pos, pos + node.nodeSize));
-        view.focus();
+      const agentType = String(node.attrs.agentType ?? "");
+      const displayName = String(node.attrs.displayName ?? "").trim();
+      const piSkill = isPiSkillCommand(command, agentType);
+      const skillLabel = displayName || piSkillName(command);
+      const nodeView = createInlineAtomNodeView({
+        caretGeometry: 'single-line',
+        wrapperClassName: "agent-composer__inline-atom-wrapper agent-thread-card__slash-token-wrapper",
+        cardClassName: piSkill
+          ? "agent-composer__skill-token"
+          : slashTokenClass(command),
+        ...(piSkill
+          ? {
+            leadingIcon: createSkillLibraryIcon(),
+            labelClassName: "agent-composer__skill-token-label",
+          }
+          : {}),
+        label: piSkill ? skillLabel : slashTokenLabel(command),
+        title: `/${command}`,
+        ariaLabel: piSkill ? `Skill ${skillLabel}` : `/${command} 命令`,
+        hoverActions: [{
+          ariaLabel: piSkill ? `移除 Skill ${skillLabel}` : `移除 /${command} 命令`,
+          icon: createInlineAtomCloseIcon(),
+          onClick: () => deleteInlineAtomNode(
+            view,
+            node,
+            () => typeof getPos === "function" ? getPos() : undefined,
+          ),
+        }],
+        stopEvent: (event) => !event.type.startsWith("composition"),
       });
-
-      wrapper.append(button, document.createTextNode("\u200B"));
+      const wrapper = nodeView.dom;
+      const button = wrapper.querySelector<HTMLButtonElement>(".agent-thread-card__slash-token");
+      const updateLocalizedLabel = () => {
+        if (button) button.textContent = slashTokenLabel(command);
+      };
+      const refreshLabelForCurrentLanguage = () => {
+        void loadLanguage(getCurrentAppLanguage()).then(updateLocalizedLabel, updateLocalizedLabel);
+      };
+      const unsubscribeLanguage = piSkill
+        ? () => undefined
+        : (() => {
+          refreshLabelForCurrentLanguage();
+          return subscribeAppLanguage(refreshLabelForCurrentLanguage);
+        })();
+      wrapper.setAttribute("data-composer-slash", String(node.attrs.command ?? ""));
+      if (agentType) wrapper.setAttribute("data-composer-slash-agent", agentType);
+      if (displayName) wrapper.setAttribute("data-composer-slash-display-name", displayName);
 
       return {
-        dom: wrapper,
+        ...nodeView,
         contentDOM: null,
-        selectNode: () => wrapper.classList.add("is-selected"),
-        deselectNode: () => wrapper.classList.remove("is-selected"),
-        stopEvent: (event: Event) => !event.type.startsWith("composition"),
-        ignoreMutation: () => true,
+        destroy: unsubscribeLanguage,
       };
     };
   },
@@ -176,8 +261,8 @@ export const ComposerSlashToken = Node.create<ComposerSlashTokenOptions>({
 
   addKeyboardShortcuts() {
     return {
-      Backspace: () => deleteAdjacentComposerSlashToken(this.editor, "before"),
-      Delete: () => deleteAdjacentComposerSlashToken(this.editor, "after"),
+      Backspace: () => deleteAdjacentInlineAtom(this.editor, "composerSlashToken", "before"),
+      Delete: () => deleteAdjacentInlineAtom(this.editor, "composerSlashToken", "after"),
     };
   },
 });
@@ -215,25 +300,6 @@ function removeHardBreaksAroundComposerSlashTokens(state: EditorState) {
   return tr;
 }
 
-function deleteAdjacentComposerSlashToken(
-  editor: Editor,
-  direction: "before" | "after",
-): boolean {
-  const { selection } = editor.state;
-  if (selection instanceof NodeSelection && selection.node.type.name === "composerSlashToken") {
-    editor.commands.deleteSelection();
-    return true;
-  }
-
-  const { $from } = selection;
-  const node = direction === "before" ? $from.nodeBefore : $from.nodeAfter;
-  if (!node || node.type.name !== "composerSlashToken") return false;
-
-  const from = direction === "before" ? $from.pos - node.nodeSize : $from.pos;
-  editor.commands.deleteRange({ from, to: from + node.nodeSize });
-  return true;
-}
-
 export function getComposerSlashToken(editor: Editor): ComposerSlashTokenValue | null {
   let value: ComposerSlashTokenValue | null = null;
   editor.state.doc.descendants((node) => {
@@ -254,13 +320,14 @@ export function insertComposerSlashToken(
   editor: Editor,
   command: string,
   agentType?: AgentTypeKey,
+  displayName?: string,
 ): void {
   const { selection } = editor.state;
   editor.chain().focus().deleteRange({ from: 1, to: selection.to })
     .insertContent([
       {
         type: "composerSlashToken",
-        attrs: { command, agentType: agentType ?? null },
+        attrs: { command, agentType: agentType ?? null, displayName: displayName ?? null },
       },
       { type: "text", text: " " },
     ]).run();
@@ -270,12 +337,12 @@ export function insertComposerSlashToken(
 export function composerSlashMarkdownToPrompt(markdown: string): string {
   return markdown.replace(
     SLASH_TOKEN_GLOBAL_RE,
-    (match, command: string, scopedAgent: string | undefined, _encoded: string, offset: number, source: string) => {
+    (match, _label: string, scopedAgent: string | undefined, command: string, offset: number, source: string) => {
       // Unscoped chips are legacy data. Preserve old DSH drafts while keeping
       // the product-only permission chips UI-only as before.
       if (
         scopedAgent &&
-        scopedAgent.toLowerCase() !== "deepseek-harness" &&
+        scopedAgent.toLowerCase() !== "dsh" &&
         scopedAgent.toLowerCase() !== "codex" &&
         scopedAgent.toLowerCase() !== "pi" ||
         (!scopedAgent && !LEGACY_DSH_COMMANDS.has(command.toLowerCase()))
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.test.ts
index cb8b8bfb6..2d34475cd 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.test.ts
@@ -25,8 +25,8 @@ function setup() {
     resetHistoryNavigation: vi.fn(), updateMultiLineState: vi.fn(),
   };
   const images = {
-    hasImages: true, hasPending: false,
-    readyImages: [{ path: "/tmp/file.png", mimeType: "image/png", name: "file.png" }],
+    hasAttachments: true, hasPending: false,
+    readyAttachments: [{ path: "/tmp/file.png", mimeType: "image/png", name: "file.png" }],
     setLocked: vi.fn(), clearAfterSubmit: vi.fn(),
   };
   const phases: string[] = [];
@@ -126,8 +126,9 @@ describe("composer submission transaction", () => {
     gate.resolve();
     await first;
     expect(composer.getDraftMarkdown()).toBe("a new follow-up");
-    expect(composer.clear).not.toHaveBeenCalled();
-    expect(options.clearPersistedDraft).not.toHaveBeenCalled();
+    // The submitted draft clears at dispatch; acceptance must not clear the new draft again.
+    expect(composer.clear).toHaveBeenCalledOnce();
+    expect(options.clearPersistedDraft).toHaveBeenCalledOnce();
   });
 
   it("rechecks a command/stop that appeared during binding", async () => {
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.ts b/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.ts
index 79203efc6..2af5a80ca 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-submission-controller.ts
@@ -1,5 +1,6 @@
 import type { ComposerController } from "./composer-controller";
-import type { ComposerImageController, AgentThreadCardInputImage } from "./composer-image-controller";
+import type { ComposerAttachmentController } from "./composer-attachment-controller";
+import type { AgentThreadCardInputAttachment } from "./composer-attachment-types";
 import {
   selectComposerSubmissionState,
   type ComposerRuntimeState,
@@ -17,7 +18,7 @@ export type ComposerSubmissionPhase =
 export interface ComposerSubmissionSnapshot {
   markdown: string;
   prompt: string;
-  images: AgentThreadCardInputImage[];
+  attachments: AgentThreadCardInputAttachment[];
 }
 
 type SubmissionComposer = Pick<
@@ -60,8 +61,8 @@ export class ComposerSubmissionController {
   async submit<T>(options: {
     composer: SubmissionComposer;
     images: Pick<
-      ComposerImageController,
-      "hasImages" | "hasPending" | "readyImages" | "setLocked" | "clearAfterSubmit"
+      ComposerAttachmentController,
+      "hasAttachments" | "hasPending" | "readyAttachments" | "setLocked" | "clearAfterSubmit"
     >;
     getRuntime: () => ComposerRuntimeState;
     isDisposed: () => boolean;
@@ -80,7 +81,7 @@ export class ComposerSubmissionController {
       ...options.getRuntime(),
       isSubmitting: this.isSubmitting,
       prompt: composer.getPrompt(),
-      hasAttachments: images.hasImages,
+      hasAttachments: images.hasAttachments,
       hasPendingAttachments: images.hasPending,
     });
     if (options.isDisposed() || !state.canSubmit) return;
@@ -88,7 +89,7 @@ export class ComposerSubmissionController {
     const snapshot: ComposerSubmissionSnapshot = {
       markdown: composer.getDraftMarkdown(),
       prompt: composer.getPrompt().trim() || "Analyze the attached image(s).",
-      images: images.readyImages.map((image) => ({ ...image })),
+      attachments: images.readyAttachments.map((attachment) => ({ ...attachment })),
     };
     this.snapshot = snapshot;
     const transition = (phase: ComposerSubmissionPhase): void => {
@@ -128,7 +129,7 @@ export class ComposerSubmissionController {
         ...options.getRuntime(),
         isSubmitting: false,
         prompt: snapshot.prompt,
-        hasAttachments: snapshot.images.length > 0,
+        hasAttachments: snapshot.attachments.length > 0,
         hasPendingAttachments: false,
         kind: state.kind,
       }).canSubmit) {
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.test.ts b/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.test.ts
index e9392274f..887946de2 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.test.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.test.ts
@@ -9,11 +9,11 @@ const idle = {
 
 describe("composer submission policy", () => {
   it("uses one command catalog for typed prompts and menu commands", () => {
-    expect(getComposerSubmissionKind("deepseek-harness", "/export")).toBe("command");
-    expect(getComposerSubmissionKind("deepseek-harness", "/compact")).toBe("command");
+    expect(getComposerSubmissionKind("dsh", "/export")).toBe("command");
+    expect(getComposerSubmissionKind("dsh", "/compact")).toBe("command");
     expect(getComposerSubmissionKind("codex", "/goal set ship it")).toBe("command");
     expect(getComposerSubmissionKind("codex", "/goalkeeper")).toBe("message");
-    expect(getComposerSubmissionKind("claude", "/goal")).toBe("message");
+    expect(getComposerSubmissionKind("claudecode", "/goal")).toBe("message");
     expect(getComposerSubmissionKind("codex", "$browser:review")).toBe("message");
   });
 
@@ -37,13 +37,13 @@ describe("composer submission policy", () => {
       .toMatchObject({ action, disabled, canSubmit });
   });
 
-  it.each(["codex", "deepseek-harness", "pi"] as const)("allows %s messages to queue, but not native commands", (agentType) => {
+  it.each(["codex", "dsh", "pi"] as const)("allows %s messages to queue, but not native commands", (agentType) => {
     expect(selectComposerSubmissionState({ ...idle, agentType, isModelRunning: true }).canSubmit).toBe(true);
     expect(selectComposerSubmissionState({ ...idle, agentType, isModelRunning: true, kind: "command" }).canSubmit).toBe(false);
   });
 
   it("keeps Stop available for agents that cannot queue without permitting Enter to send", () => {
-    expect(selectComposerSubmissionState({ ...idle, agentType: "claude", isModelRunning: true }))
+    expect(selectComposerSubmissionState({ ...idle, agentType: "claudecode", isModelRunning: true }))
       .toMatchObject({ action: "stop", disabled: false, canSubmit: false });
   });
 });
diff --git a/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.ts b/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.ts
index 55d42e82a..b30bada14 100644
--- a/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/composer-submission-state.ts
@@ -40,7 +40,7 @@ export function selectComposerSubmissionState(input: ComposerRuntimeState & {
 }): ComposerSubmissionState {
   const kind = input.kind ?? getComposerSubmissionKind(input.agentType, input.prompt);
   const hasInput = !!input.prompt.trim() || input.hasAttachments;
-  const supportsQueue = ["codex", "deepseek-harness", "pi"].includes(input.agentType);
+  const supportsQueue = ["codex", "dsh", "pi"].includes(input.agentType);
   // Codex's native command endpoint has no attachment payload.
   const supportsAttachments = kind !== "command" || input.agentType !== "codex" || !input.hasAttachments;
   const canSubmit = input.isAvailable && hasInput &&
diff --git a/app/flowix-web/features/agent/thread-card/composer/index.ts b/app/flowix-web/features/agent/thread-card/composer/index.ts
index 6788c3f37..374109ae7 100644
--- a/app/flowix-web/features/agent/thread-card/composer/index.ts
+++ b/app/flowix-web/features/agent/thread-card/composer/index.ts
@@ -9,10 +9,16 @@ export {
 } from "./composer-draft-controller";
 export { getPersistableInputDraft } from "./composer-draft";
 export {
-  ComposerImageController,
-  type AgentThreadCardInputImage,
-  type ComposerImageControllerOptions,
-} from "./composer-image-controller";
+  ComposerAttachmentController,
+  type AgentThreadCardInputAttachment,
+  type ComposerAttachmentControllerOptions,
+} from "./composer-attachment-controller";
+export {
+  ComposerAttachmentToken,
+  composerAttachmentMarkdownToPrompt,
+} from "./composer-attachment-token";
+export { ComposerAttachmentDocument, type ComposerAttachmentDocumentPort } from "./composer-attachment-document";
+export { insertComposerAttachmentToken } from "./composer-attachment-document";
 export {
   ComposerAddMenuController,
   type ComposerAddMenuControllerOptions,
diff --git a/app/flowix-web/features/agent/thread-card/composer/send-button-renderer.tsx b/app/flowix-web/features/agent/thread-card/composer/send-button-renderer.tsx
index 4431c68b0..6b9dfd68e 100644
--- a/app/flowix-web/features/agent/thread-card/composer/send-button-renderer.tsx
+++ b/app/flowix-web/features/agent/thread-card/composer/send-button-renderer.tsx
@@ -21,9 +21,9 @@ export function renderAgentThreadCardSendButton(
   // "flushSync was called from inside a lifecycle method" 报错。root.render
   // 只负责调度更新, DOM 提交可能发生在随后的事件循环。
   const className = [
-    "agent-thread-card__send",
-    options.wantStop && "agent-thread-card__send--stop",
-    options.isRunning && "agent-thread-card__send--running",
+    "agent-composer__send",
+    options.wantStop && "agent-composer__send--stop",
+    options.isRunning && "agent-composer__send--running",
   ].filter(Boolean).join(" ");
 
   options.root.render(
@@ -43,7 +43,7 @@ export function renderAgentThreadCardSendButton(
         }}
       >
         {options.isRunning ? (
-          <span className="agent-thread-card__send-spinner" aria-hidden="true" />
+          <span className="agent-composer__send-spinner flowix-spin" aria-hidden="true" />
         ) : options.wantStop ? (
           <StopIcon />
         ) : (
@@ -59,7 +59,7 @@ function StopIcon(): ReactElement {
     <svg
       aria-hidden="true"
       focusable="false"
-      className="agent-thread-card__send-icon"
+      className="agent-composer__send-icon"
       viewBox="0 0 256 256"
     >
       <path d={ICON_STOP_PATH} fill="currentColor" />
@@ -72,7 +72,7 @@ function SendIcon(): ReactElement {
     <svg
       aria-hidden="true"
       focusable="false"
-      className="agent-thread-card__send-icon"
+      className="agent-composer__send-icon"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
diff --git a/app/flowix-web/features/agent/thread-card/link-navigation.test.ts b/app/flowix-web/features/agent/thread-card/link-navigation.test.ts
index 90af12bde..84d3607f8 100644
--- a/app/flowix-web/features/agent/thread-card/link-navigation.test.ts
+++ b/app/flowix-web/features/agent/thread-card/link-navigation.test.ts
@@ -9,14 +9,17 @@ import {
 import { parseAgentLink } from './agent-link-parser';
 
 const navigation = vi.hoisted(() => ({
-  fileBrowser: vi.fn(async () => ({ host: 'browser-column' as const, tabId: 'files', alreadyOpen: false })),
-  text: vi.fn(async () => ({ host: 'browser-column' as const, tabId: 'text', alreadyOpen: false })),
-  web: vi.fn(async () => ({ host: 'browser-column' as const, tabId: 'web', alreadyOpen: false })),
+  openSurface: vi.fn(async () => ({ status: 'opened' as const, host: 'browser-column' as const, location: { host: 'browser-column' as const, tabId: 'text' } })),
 }));
-vi.mock('@features/workspace/use-cases/browser-column-navigation', () => ({
-  openBrowserColumnFileBrowser: navigation.fileBrowser,
-  openBrowserColumnText: navigation.text,
-  openBrowserColumnWebpage: navigation.web,
+vi.mock('@features/workspace/public/browser-column-api', () => ({
+  createFileBrowserTarget: (path: string, scopePath: string) => ({
+    kind: 'file-browser', activeFilePath: path, folderPath: scopePath, scopePath,
+    notebookId: null, restoreNotebookContext: true, fileTreeVisible: true, fileTreeWidth: 220,
+  }),
+}));
+vi.mock('@features/workspace/public/open-surface-api', () => ({ openWorkspaceSurface: navigation.openSurface }));
+vi.mock('@features/memo/public/note-navigation-api', () => ({
+  openNoteByDeepLink: vi.fn(async () => undefined),
 }));
 
 function target(href: string, context: Parameters<typeof parseAgentLink>[1] = {}) {
@@ -132,7 +135,7 @@ describe("localFilePathFromAgentHref", () => {
 
 describe('shared Agent link click dispatcher', () => {
   it('intercepts a raw DOM href and sends the same local-file target to navigation', async () => {
-    navigation.text.mockClear();
+    navigation.openSurface.mockClear();
     const root = document.createElement('div');
     root.innerHTML = '<a href="/Users/u/a%20b.md">source</a>';
     let handled = false;
@@ -144,30 +147,47 @@ describe('shared Agent link click dispatcher', () => {
     await Promise.resolve();
     expect(handled).toBe(true);
     expect(event.defaultPrevented).toBe(true);
-    expect(navigation.text).toHaveBeenCalledWith('/Users/u/a b.md', null);
+    expect(navigation.openSurface).toHaveBeenCalledWith({
+      host: 'browser-column',
+      target: { kind: 'external', path: '/Users/u/a b.md', scopePath: null, transitionId: null },
+    });
   });
 
   it('keeps the location from the latest click when an earlier open resolves later', async () => {
     const { peekAgentLocationRequest, consumeAgentLocationRequest } = await import(
       '@features/document/use-cases/agent-location-navigation',
     );
-    let resolveFirst!: (value: { host: 'browser-column'; tabId: string; alreadyOpen: false }) => void;
-    let resolveSecond!: (value: { host: 'browser-column'; tabId: string; alreadyOpen: false }) => void;
-    navigation.text
+    type OpenResult = { status: 'opened'; host: 'browser-column'; location: { host: 'browser-column'; tabId: string } };
+    let resolveFirst!: (value: OpenResult) => void;
+    let resolveSecond!: (value: OpenResult) => void;
+    navigation.openSurface
       .mockImplementationOnce(() => new Promise((resolve) => { resolveFirst = resolve; }))
       .mockImplementationOnce(() => new Promise((resolve) => { resolveSecond = resolve; }));
 
     const first = openAgentLink('/Users/u/a.md:10', null);
     const second = openAgentLink('/Users/u/a.md:144', null);
-    resolveSecond({ host: 'browser-column', tabId: 'a', alreadyOpen: false });
+    resolveSecond({ status: 'opened', host: 'browser-column', location: { host: 'browser-column', tabId: 'a' } });
     await second;
-    resolveFirst({ host: 'browser-column', tabId: 'a', alreadyOpen: false });
+    resolveFirst({ status: 'opened', host: 'browser-column', location: { host: 'browser-column', tabId: 'a' } });
     await first;
 
     const request = peekAgentLocationRequest('/Users/u/a.md');
     expect(request?.location).toEqual({ line: 144 });
     if (request) consumeAgentLocationRequest(request.path, request.id);
   });
+
+  it('routes flowix note links through the browser column', async () => {
+    const { openNoteByDeepLink } = await import('@features/memo/public/note-navigation-api');
+    vi.mocked(openNoteByDeepLink).mockClear();
+
+    await openAgentLink('flowix://open?b=Notes&f=Projects%2FPlan.md', null);
+
+    expect(openNoteByDeepLink).toHaveBeenCalledWith(
+      'flowix://open?b=Notes&f=Projects%2FPlan.md',
+      null,
+      { destination: 'browser-column' },
+    );
+  });
 });
 
 describe("agentFileScopePath", () => {
diff --git a/app/flowix-web/features/agent/thread-card/link-navigation.ts b/app/flowix-web/features/agent/thread-card/link-navigation.ts
index 98e93e4db..e7411959e 100644
--- a/app/flowix-web/features/agent/thread-card/link-navigation.ts
+++ b/app/flowix-web/features/agent/thread-card/link-navigation.ts
@@ -5,18 +5,15 @@ import { toast } from '@/lib/toast';
 import { translate } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 import { externalFileViewKind } from '@features/editor/code-file';
-import { openNoteByDeepLink } from '@features/memo/use-cases/open-by-target';
-import {
-  openBrowserColumnFileBrowser,
-  openBrowserColumnText,
-  openBrowserColumnWebpage,
-  type BrowserColumnOpenResult,
-} from '@features/workspace/use-cases/browser-column-navigation';
+import { openNoteByDeepLink } from '@features/memo/public/note-navigation-api';
+import { createFileBrowserTarget } from '@features/workspace/public/browser-column-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import type { WorkspaceSurfaceOpenResult } from '@features/workspace/public/open-surface-api';
 import {
   cancelAgentLocationRequest,
   publishAgentLocationRequest,
 } from '@features/document/use-cases/agent-location-navigation';
-import { locationViewId } from '@features/document/use-cases/heading-anchor-publish';
+import { locationViewId } from '@features/document/public/heading-navigation-api';
 import {
   parseAgentLink,
   type AgentLinkParseResult,
@@ -126,10 +123,13 @@ export async function openAgentLink(
     case 'anchor':
       return;
     case 'flowix':
-      await openNoteByDeepLink(target.url);
+      // Notes and code share the same right-column destination. Opening a note
+      // deep link must not replace the conversation already shown by the work
+      // column (that is what the note card's “打开笔记” action does too).
+      await openNoteByDeepLink(target.url, null, { destination: 'browser-column' });
       return;
     case 'web':
-      await openBrowserColumnWebpage(target.url);
+      await openWorkspaceSurface({ host: 'browser-column', target: { kind: 'web', url: target.url } });
       return;
     case 'external':
       await openUrl(target.url);
@@ -146,11 +146,17 @@ export async function openAgentLink(
       latestLocalNavigationByPath.set(pathKey, navigationId);
       cancelAgentLocationRequest(target.path);
       const scopePath = agentFileScopePathForRuntime(target.path, runtimeConfig);
-      let opened: BrowserColumnOpenResult | null;
+      let opened: WorkspaceSurfaceOpenResult;
       try {
         opened = scopePath
-          ? await openBrowserColumnFileBrowser(scopePath, target.path)
-          : await openBrowserColumnText(target.path, null);
+          ? await openWorkspaceSurface({
+            host: 'browser-column',
+            target: createFileBrowserTarget(target.path, scopePath, scopePath),
+          })
+          : await openWorkspaceSurface({
+            host: 'browser-column',
+            target: { kind: 'external', path: target.path, scopePath: null, transitionId: null },
+          });
       } catch (error) {
         if (latestLocalNavigationByPath.get(pathKey) === navigationId) {
           latestLocalNavigationByPath.delete(pathKey);
@@ -159,7 +165,7 @@ export async function openAgentLink(
       }
       if (latestLocalNavigationByPath.get(pathKey) !== navigationId) return;
       latestLocalNavigationByPath.delete(pathKey);
-      if (!opened || (!target.location && !target.anchor)) return;
+      if (opened.status === 'cancelled' || (!target.location && !target.anchor)) return;
       const viewKind = externalFileViewKind(target.path);
       if (viewKind !== 'markdown' && viewKind !== 'code') {
         toast.info(translate(getCurrentAppLanguage(), 'document.file.locationUnsupported'));
@@ -169,8 +175,8 @@ export async function openAgentLink(
         path: target.path,
         ...(target.location ? { location: target.location } : {}),
         ...(target.anchor ? { anchor: target.anchor } : {}),
-        host: opened.host,
-        viewId: locationViewId(opened),
+        host: opened.location.host,
+        viewId: locationViewId(opened.location),
       });
       return;
     }
diff --git a/app/flowix-web/features/agent/thread-card/messages/image-preview.ts b/app/flowix-web/features/agent/thread-card/messages/image-preview.ts
index 52898a56b..838af11bc 100644
--- a/app/flowix-web/features/agent/thread-card/messages/image-preview.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/image-preview.ts
@@ -39,7 +39,7 @@ function showImagePreview(image: HTMLImageElement, language: AppLanguage): void
   loading.setAttribute("role", "status");
   loading.setAttribute("aria-live", "polite");
   const spinner = document.createElement("span");
-  spinner.className = "agent-thread-card__image-preview-spinner";
+  spinner.className = "agent-thread-card__image-preview-spinner flowix-spin";
   spinner.setAttribute("aria-hidden", "true");
   const loadingText = document.createElement("span");
   loadingText.textContent = language === "zh-CN" ? "图片加载中…" : "Loading image…";
diff --git a/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.test.ts b/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.test.ts
index 5661cd639..92ee070b0 100644
--- a/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.test.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.test.ts
@@ -196,7 +196,7 @@ describe("agent user and assistant Markdown rendering", () => {
     document.body.append(host);
 
     const editorPreSelector =
-      ".markdown-editor .tiptap:not(.agent-thread-card__composer-editor) " +
+      ".markdown-editor .tiptap:not(.agent-composer__input-content) " +
       "pre:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):not(.agent-thread-card__message-code-block)";
 
     expect(message.querySelector("pre")?.matches(editorPreSelector)).toBe(false);
@@ -216,7 +216,7 @@ describe("agent user and assistant Markdown rendering", () => {
     document.body.append(host);
 
     const firstBlockSelector =
-      ".markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) " +
+      ".markdown-editor .ProseMirror:not(.agent-composer__input-content) " +
       "> *:not(.agent-thread-card, .frontmatter-property-node):first-of-type";
 
     expect(card.matches(firstBlockSelector)).toBe(false);
@@ -310,7 +310,13 @@ describe("DSH command input rendering", () => {
     ]);
     expect(elements.map((element) => element.querySelector(
       ".agent-thread-card__message-dsh-badge",
-    )?.textContent)).toEqual(["DSH", "DSH", "DSH"]);
+    )?.textContent ?? null)).toEqual(["DSH", null, null]);
+    expect(elements.map((element) => element.querySelector(
+      ".agent-thread-card__message-mode-tag",
+    )?.textContent ?? null)).toEqual([null, "Goal 模式", "Plan 模式"]);
+    expect(elements[1].querySelector(".agent-thread-card__message-user-bubble")?.contains(
+      elements[1].querySelector(".agent-thread-card__message-mode-tag"),
+    )).toBe(false);
     expect(elements.map((element) => element.textContent?.includes("/"))).toEqual([
       true,
       true,
@@ -376,7 +382,10 @@ describe("Codex command rendering", () => {
     ]);
     expect(elements.map((element) => element.querySelector(
       ".agent-thread-card__message-codex-badge",
-    )?.textContent)).toEqual(["Codex", "Codex"]);
+    )?.textContent ?? null)).toEqual(["Codex", null]);
+    expect(elements.map((element) => element.querySelector(
+      ".agent-thread-card__message-mode-tag",
+    )?.textContent ?? null)).toEqual([null, "Goal 模式"]);
     expect(elements.map((element) => element.textContent?.includes("/"))).toEqual([
       true,
       true,
diff --git a/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.ts b/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.ts
index e9a42243e..214f70b64 100644
--- a/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/message-item-renderer.ts
@@ -1,7 +1,13 @@
 import { messageRenderKey } from "@features/agent/message/render-identity";
 import { createElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { Check, Copy, GitBranch, Image as ImageIcon } from "lucide-react";
+import {
+  Check,
+  Copy,
+  GitBranch,
+  Image as ImageIcon,
+  LoaderCircle,
+} from "lucide-react";
 import { translate, type AppLanguage } from "@/lib/i18n";
 import { createLogger } from "@/lib/logger";
 import { agent } from "@platform/tauri/client";
@@ -83,6 +89,28 @@ function getMessageDurationText(
   return `Duration ${minutes}m${seconds}s`;
 }
 
+function getCommandModeLabel(message: AgentMessage, language: AppLanguage): string | null {
+  if (
+    message.messageType !== "dsh-command" &&
+    message.messageType !== "dsh-command-prompt" &&
+    message.messageType !== "codex-command"
+  ) {
+    return null;
+  }
+
+  const command = message.content.trim();
+  if (
+    message.messageType === "dsh-command-prompt" ||
+    /^\/plan(?:\s|$)/iu.test(command)
+  ) {
+    return translate(language, "editor.threadCard.commandMode.plan");
+  }
+  if (/^\/goal(?:\s|$)/iu.test(command)) {
+    return translate(language, "editor.threadCard.commandMode.goal");
+  }
+  return null;
+}
+
 function createUserMessageAttachments(
   message: AgentMessage,
   language: AppLanguage,
@@ -111,21 +139,25 @@ function createUserMessageAttachments(
     const icon = document.createElement("span");
     icon.className = "agent-thread-card__message-attachment-icon";
     icon.append(createLucideIcon(ImageIcon));
-    card.append(icon);
+    const label = document.createElement("span");
+    label.className = "agent-thread-card__message-attachment-label";
+    label.textContent = attachment.name;
+    label.title = attachment.name;
+    card.append(icon, label);
     container.append(card);
 
     if (
       attachment.type === "input_image" ||
       attachment.mimeType.toLowerCase().startsWith("image/")
     ) {
-      void agent.readCachedImage(attachment.path).then((previewUrl) => {
+      void agent.readCachedAttachment(attachment.path).then((previewUrl) => {
         if (!previewUrl) return;
         const preview = document.createElement("img");
         preview.className = "agent-thread-card__message-attachment-preview";
         preview.src = previewUrl;
         preview.alt = attachment.name;
         preview.draggable = false;
-        card.replaceChildren(preview);
+        icon.replaceChildren(preview);
       }).catch(() => {
         // Keep the image icon when the cached file is no longer available.
       });
@@ -190,7 +222,9 @@ export function attachMessageActions(
     forkButton.setAttribute("aria-label", forkButton.title);
     forkButton.append(createLucideIcon(GitBranch));
     let activeConfirmation: HTMLSpanElement | null = null;
+    let isForking = false;
     function handleOutsidePointerDown(event: PointerEvent): void {
+      if (isForking) return;
       if (!actions.isConnected) {
         closeConfirmation();
         return;
@@ -206,11 +240,14 @@ export function attachMessageActions(
       document.removeEventListener("pointerdown", handleOutsidePointerDown, true);
     };
     disposeForkConfirmation = () => {
+      isForking = false;
+      item.classList.remove("agent-thread-card__message--forking");
       closeConfirmation();
     };
     forkButton.addEventListener("mousedown", (event) => event.stopPropagation());
     forkButton.addEventListener("click", (event) => {
       event.stopPropagation();
+      if (isForking) return;
       if (activeConfirmation) {
         closeConfirmation();
         return;
@@ -237,18 +274,32 @@ export function attachMessageActions(
         // the only visible state made a successful click look like a no-op.
         confirmButton.disabled = true;
         cancelButton.disabled = true;
-        confirmButton.textContent = language === "zh-CN" ? "分叉中…" : "Forking…";
+        isForking = true;
+        item.classList.add("agent-thread-card__message--forking");
+        const loadingIcon = createLucideIcon(LoaderCircle);
+        loadingIcon.classList.add(
+          "agent-thread-card__message-fork-loading-icon",
+          "flowix-spin",
+        );
+        const loadingLabel = document.createElement("span");
+        loadingLabel.textContent = language === "zh-CN" ? "分叉中…" : "Forking…";
+        confirmButton.replaceChildren(loadingIcon, loadingLabel);
         let result: void | Promise<void>;
+        const finishFork = () => {
+          isForking = false;
+          item.classList.remove("agent-thread-card__message--forking");
+          closeConfirmation();
+        };
         try {
           result = onFork?.(message);
         } catch (error) {
-          closeConfirmation();
+          finishFork();
           throw error;
         }
         if (result && typeof result.then === "function") {
-          void result.then(closeConfirmation, closeConfirmation);
+          void result.then(finishFork, finishFork);
         } else {
-          closeConfirmation();
+          finishFork();
         }
       });
 
@@ -634,6 +685,14 @@ export function createAgentThreadCardMessageElement(options: {
       const content = document.createElement("div");
       content.className =
         "agent-thread-card__message-content agent-thread-card__message-content--user-preview";
+      const commandModeLabel = getCommandModeLabel(message, language);
+      if (commandModeLabel) {
+        const modeTag = document.createElement("span");
+        modeTag.className =
+          "agent-thread-card__message-attachment agent-thread-card__message-mode-tag";
+        modeTag.textContent = commandModeLabel;
+        item.append(modeTag);
+      }
       if (skillMarkup.names.length > 0) {
         const skillTags = document.createElement("div");
         skillTags.className = "agent-thread-card__message-pi-skill-tags";
@@ -646,19 +705,21 @@ export function createAgentThreadCardMessageElement(options: {
         });
         bubble.append(skillTags);
       }
-      if (
-        message.messageType === "dsh-command" ||
-        message.messageType === "dsh-command-prompt"
-      ) {
-        const badge = document.createElement("span");
-        badge.className = "agent-thread-card__message-dsh-badge";
-        badge.textContent = message.messageType === "dsh-command-prompt" ? "DSH /plan" : "DSH";
-        bubble.append(badge);
-      } else if (message.messageType === "codex-command") {
-        const badge = document.createElement("span");
-        badge.className = "agent-thread-card__message-codex-badge";
-        badge.textContent = "Codex";
-        bubble.append(badge);
+      if (!commandModeLabel) {
+        if (
+          message.messageType === "dsh-command" ||
+          message.messageType === "dsh-command-prompt"
+        ) {
+          const badge = document.createElement("span");
+          badge.className = "agent-thread-card__message-dsh-badge";
+          badge.textContent = message.messageType === "dsh-command-prompt" ? "DSH /plan" : "DSH";
+          bubble.append(badge);
+        } else if (message.messageType === "codex-command") {
+          const badge = document.createElement("span");
+          badge.className = "agent-thread-card__message-codex-badge";
+          badge.textContent = "Codex";
+          bubble.append(badge);
+        }
       }
       bubble.append(content);
       item.append(bubble);
@@ -672,7 +733,7 @@ export function createAgentThreadCardMessageElement(options: {
         isStreaming: options.isStreaming,
       });
       const attachments = createUserMessageAttachments(message, language);
-      if (attachments) item.append(attachments);
+      if (attachments) bubble.append(attachments);
     } else if (message.role === "reasoning") {
       const header = document.createElement("button");
       header.type = "button";
diff --git a/app/flowix-web/features/agent/thread-card/messages/message-list-renderer.ts b/app/flowix-web/features/agent/thread-card/messages/message-list-renderer.ts
index 837bddcb9..1780129ca 100644
--- a/app/flowix-web/features/agent/thread-card/messages/message-list-renderer.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/message-list-renderer.ts
@@ -323,13 +323,15 @@ export function patchLastRenderedAgentMessage(
     const content = item.querySelector<HTMLElement>(
       ".agent-thread-card__message-content",
     );
-    if (!content) return null;
+    if (!content?.parentElement) return null;
     renderAgentThreadCardBudgetedMarkdown({
       message,
       role: message.role,
       visibleContent: messageView.visibleContent,
       content,
-      toggleParent: item,
+      // The toggle is a sibling of the content for both user bubbles and
+      // assistant messages.
+      toggleParent: content.parentElement,
       context,
       isStreaming: context.isStreaming(message),
     });
diff --git a/app/flowix-web/features/agent/thread-card/messages/thread-message-render-controller.test.ts b/app/flowix-web/features/agent/thread-card/messages/thread-message-render-controller.test.ts
index 0ded5afd8..383c18721 100644
--- a/app/flowix-web/features/agent/thread-card/messages/thread-message-render-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/thread-message-render-controller.test.ts
@@ -109,7 +109,7 @@ describe("ThreadMessageRenderController empty settings", () => {
       return frames.length;
     });
     vi.stubGlobal("cancelAnimationFrame", () => undefined);
-    const { body, controller } = createController("claude");
+    const { body, controller } = createController("claudecode");
     try {
       const first = {
         id: "code-reply", role: "assistant" as const,
@@ -174,7 +174,7 @@ describe("ThreadMessageRenderController empty settings", () => {
     });
     vi.stubGlobal("cancelAnimationFrame", () => undefined);
     try {
-      const { body, controller } = createController("claude");
+      const { body, controller } = createController("claudecode");
       const messages = Array.from({ length: 31 }, (_, index) => ({
         id: `end-${index}`,
         role: "end" as const,
@@ -251,7 +251,7 @@ describe("ThreadMessageRenderController empty settings", () => {
   });
 
   it("defers completed reasoning Markdown until the collapsed row is expanded", () => {
-    const { body, controller } = createController("claude");
+    const { body, controller } = createController("claudecode");
 
     controller.render({
       messages: [{
@@ -325,7 +325,7 @@ describe("ThreadMessageRenderController empty settings", () => {
 
   it("DeepSeek Harness empty card renders runtime settings", () => {
     const { body, controller, createExternalAgentEmptySettings } =
-      createController("deepseek-harness");
+      createController("dsh");
 
     controller.render({
       messages: [],
@@ -432,7 +432,7 @@ describe("ThreadMessageRenderController empty settings", () => {
 
   it("does not render runtime settings while thread cache is loading", () => {
     const { body, controller, createExternalAgentEmptySettings } =
-      createController("deepseek-harness");
+      createController("dsh");
 
     controller.render({
       messages: [],
@@ -455,7 +455,7 @@ describe("ThreadMessageRenderController run-end re-parse", () => {
     });
     vi.stubGlobal("cancelAnimationFrame", () => undefined);
     try {
-      const { body, controller } = createController("deepseek-harness");
+      const { body, controller } = createController("dsh");
       const history = [
         {
           id: "u1",
@@ -535,7 +535,7 @@ describe("ThreadMessageRenderController run-end re-parse", () => {
     });
     vi.stubGlobal("cancelAnimationFrame", () => undefined);
     try {
-      const { body, controller } = createController("deepseek-harness");
+      const { body, controller } = createController("dsh");
       const streaming = {
         id: "a1",
         role: "assistant" as const,
diff --git a/app/flowix-web/features/agent/thread-card/messages/tool-group-renderer.ts b/app/flowix-web/features/agent/thread-card/messages/tool-group-renderer.ts
index bbcda1408..29e1ab990 100644
--- a/app/flowix-web/features/agent/thread-card/messages/tool-group-renderer.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/tool-group-renderer.ts
@@ -137,7 +137,7 @@ function getToolGroupLabel(group: ToolGroup, language: AppLanguage): string {
         ? "agent.tools.runningSteps"
         : "agent.tools.processing"
       : group.status === "failed"
-        ? "agent.tools.failedSteps"
+        ? "agent.tools.finishedSteps"
         : "agent.tools.completedSteps";
   return translate(language, key, {
     count: group.status === "failed" ? group.totalCount : completedCount,
@@ -227,10 +227,8 @@ export function createToolGroupElement(options: {
   };
 
   const syncCompletedTools = () => {
-    const visibleTools = (expanded
-      ? currentGroup.completedTools
-      : currentGroup.completedTools.filter(isFailedToolMessage)
-    ).filter((tool) => !runningToolRows.has(tool.id));
+    const visibleTools = (expanded ? currentGroup.completedTools : [])
+      .filter((tool) => !runningToolRows.has(tool.id));
     if (visibleTools.length === 0) {
       replaceChildrenWithCleanup(completedTools);
       return;
@@ -354,14 +352,14 @@ export function createToolGroupElement(options: {
   headerLoadingIcon.setAttribute("aria-hidden", "true");
 
   const syncLabel = () => {
-    const baseLabel = getToolGroupLabel(currentGroup, currentContext.language);
+    label.textContent = getToolGroupLabel(currentGroup, currentContext.language);
     const duration = getToolGroupDurationMs(currentGroup);
     const formattedDuration = duration === null
       ? null
       : formatToolGroupDuration(duration);
-    label.textContent = formattedDuration === null
-      ? baseLabel
-      : `${baseLabel} · ${formattedDuration}`;
+    if (formattedDuration !== null) {
+      label.append(document.createTextNode(` · ${formattedDuration}`));
+    }
   };
 
   const syncDurationTimer = () => {
diff --git a/app/flowix-web/features/agent/thread-card/messages/tool-grouping.ts b/app/flowix-web/features/agent/thread-card/messages/tool-grouping.ts
index 5fa0eef23..b28e3e42c 100644
--- a/app/flowix-web/features/agent/thread-card/messages/tool-grouping.ts
+++ b/app/flowix-web/features/agent/thread-card/messages/tool-grouping.ts
@@ -71,6 +71,24 @@ function hasAssistantContent(message: ChatMessage): boolean {
   );
 }
 
+function isCodemodeChildTool(message: ChatMessage, messages: ChatMessage[]): boolean {
+  if (message.role !== "tool") return false;
+  const callId = message.toolCallId ?? message.id;
+  if (!callId) return false;
+
+  // Pi's RPC records codemode subcalls under the codemode result, with child
+  // ids prefixed by the parent call id (for example, `<call-id>/1`). Some
+  // live projections also expose those calls as tool rows; keep them hidden
+  // from the ordinary tool group while retaining the codemode parent row.
+  return messages.some((candidate) => {
+    if (candidate.role !== "tool" || candidate.toolName?.toLowerCase() !== "codemode") {
+      return false;
+    }
+    const parentCallId = candidate.toolCallId ?? candidate.id;
+    return callId.startsWith(`${parentCallId}/`);
+  });
+}
+
 /**
  * Converts the raw message sequence into render units. A non-tool row always
  * flushes the current run, including rows that the message renderer later
@@ -131,6 +149,7 @@ export function groupAgentMessages(
   for (let index = 0; index < messages.length; index += 1) {
     const message = messages[index];
     if (message.role === "tool") {
+      if (isCodemodeChildTool(message, messages)) continue;
       toolRun.push(message);
       lastToolIndex = index;
       continue;
diff --git a/app/flowix-web/features/agent/thread-card/note/note-picker-controller.test.ts b/app/flowix-web/features/agent/thread-card/note/note-picker-controller.test.ts
index fb7c43ce8..c4b0d25ad 100644
--- a/app/flowix-web/features/agent/thread-card/note/note-picker-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/note/note-picker-controller.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { NotePickerController } from './note-picker-controller';
 import { ComposerAddMenuController } from '../composer/composer-add-menu-controller';
-import type { ComposerImageController } from '../composer/composer-image-controller';
+import type { ComposerAttachmentController } from '../composer/composer-attachment-controller';
 
 const mocks = vi.hoisted(() => ({
   searchPathNotes: vi.fn(),
@@ -45,7 +45,7 @@ describe('NotePickerController', () => {
       popover: addPopover,
       notePopover: popover,
       notePicker: picker,
-      images: { addFiles: vi.fn() } as unknown as ComposerImageController,
+      attachments: { addFiles: vi.fn() } as unknown as ComposerAttachmentController,
       t: (key) => key,
       isDestroyed: () => false,
       openNotebookAgentSettings: vi.fn(),
@@ -59,7 +59,7 @@ describe('NotePickerController', () => {
     expect(mocks.searchPathNotes).toHaveBeenCalledWith('notebook-1', '', 10);
     expect(popover.textContent).toContain('Plan');
     expect(popover.textContent).not.toContain('selectRole');
-    popover.querySelector<HTMLButtonElement>('.agent-thread-card__composer-note-item')?.click();
+    popover.querySelector<HTMLButtonElement>('.agent-composer__note-item')?.click();
     expect(injectMemoReference).toHaveBeenCalledWith(expect.objectContaining({
       notebookId: 'notebook-1',
       relativePath: 'Projects/Plan.md',
diff --git a/app/flowix-web/features/agent/thread-card/note/note-picker-controller.ts b/app/flowix-web/features/agent/thread-card/note/note-picker-controller.ts
index a0925a8f3..d33f1f74d 100644
--- a/app/flowix-web/features/agent/thread-card/note/note-picker-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/note/note-picker-controller.ts
@@ -140,11 +140,11 @@ export class NotePickerController {
 
   private render(): void {
     const list = document.createElement('div');
-    list.className = 'agent-thread-card__composer-note-search-list';
+    list.className = 'agent-composer__note-search-list';
     list.dataset.noteResults = '';
     const search = document.createElement('input');
     search.type = 'text';
-    search.className = 'agent-thread-card__composer-note-search';
+    search.className = 'agent-composer__note-search';
     search.placeholder = this.options.t('editor.threadCard.noteSearch.searchPlaceholder');
     search.setAttribute('aria-label', this.options.t('editor.threadCard.noteSearch.sectionTitle'));
     search.value = this.query;
@@ -186,9 +186,9 @@ export class NotePickerController {
     if (!list) return;
     list.replaceChildren();
     const header = document.createElement('div');
-    header.className = 'agent-thread-card__composer-note-popover-header';
+    header.className = 'agent-composer__note-popover-header';
     const title = document.createElement('div');
-    title.className = 'agent-thread-card__composer-note-popover-title';
+    title.className = 'agent-composer__note-popover-title';
     title.textContent = this.options.t('editor.threadCard.noteSearch.sectionTitle');
     header.append(title);
     list.append(header);
@@ -197,7 +197,7 @@ export class NotePickerController {
     for (const note of hits) {
       const item = document.createElement('button');
       item.type = 'button';
-      item.className = 'agent-thread-card__composer-note-result agent-thread-card__composer-note-item';
+      item.className = 'agent-composer__note-result agent-composer__note-item';
       item.title = `${note.title} · ${note.notebookName}`;
       item.textContent = note.title || note.filename;
       item.addEventListener('click', (event) => {
@@ -210,7 +210,7 @@ export class NotePickerController {
     }
     if (!hits.length) {
       const empty = document.createElement('div');
-      empty.className = 'agent-thread-card__composer-note-empty';
+      empty.className = 'agent-composer__note-empty';
       empty.textContent = this.loading
         ? this.options.t('editor.threadCard.noteSearch.searching')
         : this.options.t(filter ? 'editor.threadCard.noteSearch.emptyNoMatch' : 'editor.threadCard.noteSearch.emptyHint');
diff --git a/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.test.ts b/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.test.ts
index 29cb804a0..35acfd78e 100644
--- a/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.test.ts
+++ b/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.test.ts
@@ -29,7 +29,7 @@ describe("createRuntimeInfoRequester", () => {
   });
 
   it("returns undefined for agent types without a runtime provider", () => {
-    expect(createRuntimeInfoRequester("claude", () => "thread-1")).toBeUndefined();
+    expect(createRuntimeInfoRequester("claudecode", () => "thread-1")).toBeUndefined();
   });
 
   it("loads persisted Pi session metadata after the conversation is restored", async () => {
@@ -81,7 +81,7 @@ describe("createRuntimeInfoRequester", () => {
   });
 
   it("resolves null without invoking when the thread id is missing for thread-scoped runtimes", async () => {
-    for (const typeKey of ["deepseek-harness", "opencode"] as const) {
+    for (const typeKey of ["dsh", "opencode"] as const) {
       const request = createRuntimeInfoRequester(typeKey, () => null);
       await expect(request?.()).resolves.toBeNull();
     }
@@ -106,7 +106,7 @@ describe("createRuntimeInfoRequester", () => {
 
   it("reads the thread id at call time instead of creation time", async () => {
     let threadId: string | null = null;
-    const request = createRuntimeInfoRequester("deepseek-harness", () => threadId);
+    const request = createRuntimeInfoRequester("dsh", () => threadId);
     await expect(request?.()).resolves.toBeNull();
     threadId = "thread-2";
     mocks.sessionUsage.mockResolvedValue({
diff --git a/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.ts b/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.ts
index bd5ac0a49..849be0b26 100644
--- a/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.ts
+++ b/app/flowix-web/features/agent/thread-card/runtime/runtime-info-requester.ts
@@ -63,7 +63,7 @@ export function createRuntimeInfoRequester(
           },
         };
       };
-    case "deepseek-harness":
+    case "dsh":
       return async () => {
         const threadId = getThreadId();
         if (!threadId) return null;
diff --git a/app/flowix-web/features/agent/thread-card/runtime/thread-card-subscriptions-controller.ts b/app/flowix-web/features/agent/thread-card/runtime/thread-card-subscriptions-controller.ts
index 0b36e4cbd..c302f39bb 100644
--- a/app/flowix-web/features/agent/thread-card/runtime/thread-card-subscriptions-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/runtime/thread-card-subscriptions-controller.ts
@@ -1,7 +1,8 @@
 import type { AgentTypeKey } from "@/types/agent";
 import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
 import { useAgentRuntimeStore } from "@features/agent/store/agent-runtime-store";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
 import type { ThreadProjection } from "@features/agent/store/session-reducer";
 import {
   isLocalExternalThreadId,
@@ -43,8 +44,8 @@ export class AgentThreadCardSubscriptionsController {
     this.unsubscribes = [
       this.subscribeThreadState(),
       this.subscribeTitle(),
-      this.subscribeSettings(),
-      this.subscribeAgentAccess(),
+      this.subscribeAgentData(),
+      this.subscribeWorkspace(),
       ...this.subscribeConversation(),
       this.subscribeRuntime(),
     ];
@@ -124,7 +125,7 @@ export class AgentThreadCardSubscriptionsController {
     const options = this.options;
     const typeKey = options.getTypeKey();
     if (
-      (typeKey === "codex" || typeKey === "claude") &&
+      (typeKey === "codex" || typeKey === "claudecode") &&
       next.localThreadId &&
       next.resolvedSessionId
     ) {
@@ -134,7 +135,7 @@ export class AgentThreadCardSubscriptionsController {
         typeKey,
       );
     } else if (
-      (typeKey === "codex" || typeKey === "claude") &&
+      (typeKey === "codex" || typeKey === "claudecode") &&
       next.threadId &&
       isLocalExternalThreadId(next.threadId, typeKey) &&
       next.projection &&
@@ -156,31 +157,6 @@ export class AgentThreadCardSubscriptionsController {
     }
   }
 
-  private subscribeSettings(): Unsubscribe {
-    const options = this.options;
-    // Phase 4 (2026-08-02): 真源切到 session-store.sessionMeta.settings.
-    return useAgentSessionStore.subscribe(
-      (state) => ({
-        agentPermissionMode: state.sessionMeta.settings.agentPermissionMode,
-        agentCodexModel: state.sessionMeta.settings.agentCodexModel,
-        agentCodexReasoningEffort:
-          state.sessionMeta.settings.agentCodexReasoningEffort,
-      }),
-      () => {
-        options.refreshExternalAgentEmptySettings();
-        if (options.isExternalSettingsOpen()) {
-          options.renderCodexSettingsPopover();
-        }
-      },
-      {
-        equalityFn: (a, b) =>
-          a.agentPermissionMode === b.agentPermissionMode &&
-          a.agentCodexModel === b.agentCodexModel &&
-          a.agentCodexReasoningEffort === b.agentCodexReasoningEffort,
-      },
-    );
-  }
-
   private subscribeConversation(): Unsubscribe[] {
     const options = this.options;
     // Phase 7 (2026-08-03): 改直读 session-store 真源. 之前用 conv-store
@@ -227,20 +203,35 @@ export class AgentThreadCardSubscriptionsController {
     });
   }
 
-  private subscribeAgentAccess(): Unsubscribe {
-    return useAgentAccessStore.subscribe((state, previous) => {
-      if (
-        state.config.defaults?.runtime?.pi?.piCodeMode ===
-        previous.config.defaults?.runtime?.pi?.piCodeMode
-      ) {
-        return;
-      }
-      if (this.options.getTypeKey() !== "pi") return;
-      this.options.refreshAttrs();
-      this.options.refreshExternalAgentEmptySettings();
-      if (this.options.isExternalSettingsOpen()) {
-        this.options.renderCodexSettingsPopover();
-      }
+  private subscribeAgentData(): Unsubscribe {
+    return useAgentDataStore.subscribe((state, previous) => {
+      const typeKey = this.options.getTypeKey();
+      const current = state.agents[typeKey];
+      const prior = previous.agents[typeKey];
+      const preferenceChanged = current.user.model !== prior.user.model
+        || current.user.permission !== prior.user.permission
+        || current.user.mode !== prior.user.mode
+        || current.user.reasoningEffort !== prior.user.reasoningEffort
+        || current.user.reasoningByModel !== prior.user.reasoningByModel
+        || current.user.serviceTier !== prior.user.serviceTier;
+      const modelCatalogChanged = current.catalog.models !== prior.catalog.models;
+      if (!preferenceChanged && !modelCatalogChanged) return;
+      this.refreshAgentSettings();
+    });
+  }
+
+  private subscribeWorkspace(): Unsubscribe {
+    return useAgentWorkspaceStore.subscribe((state, previous) => {
+      if (state.workspace === previous.workspace) return;
+      this.refreshAgentSettings();
     });
   }
+
+  private refreshAgentSettings(): void {
+    this.options.refreshAttrs();
+    this.options.refreshExternalAgentEmptySettings();
+    if (this.options.isExternalSettingsOpen()) {
+      this.options.renderCodexSettingsPopover();
+    }
+  }
 }
diff --git a/app/flowix-web/features/agent/thread-card/settings/agent-workspace-repositories.test.ts b/app/flowix-web/features/agent/thread-card/settings/agent-workspace-repositories.test.ts
index 0157bd007..8a95488ac 100644
--- a/app/flowix-web/features/agent/thread-card/settings/agent-workspace-repositories.test.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/agent-workspace-repositories.test.ts
@@ -1,17 +1,20 @@
 // @vitest-environment jsdom
 
-import type { AgentAccessConfig, AgentAccessEntry, NotebookAgentConfig } from "@/lib/types/agent-access";
+import type { AgentAccessConfig, AgentAccessEntry } from "@/lib/types/agent-workspace.test-support";
+import type { NotebookWorkspaceConfig } from "@/lib/types/agent-workspace";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const {
   addFolderFromPicker,
-  setDefaultFiles,
+  attachFolderToNotebook,
+  detachFolderFromNotebook,
   openBrowserColumnFileBrowser,
   accessState,
 } = vi.hoisted(() => ({
   addFolderFromPicker: vi.fn(),
-  setDefaultFiles: vi.fn(),
+  attachFolderToNotebook: vi.fn(async () => "saved" as const),
+  detachFolderFromNotebook: vi.fn(async () => "saved" as const),
   openBrowserColumnFileBrowser: vi.fn(),
   // 可变 store 快照 ── 增删用例需要"写盘后重新读到新列表"这条链路成立。
   accessState: {
@@ -19,7 +22,7 @@ const {
     notebookConfigs: {},
   } as {
     config: AgentAccessConfig;
-    notebookConfigs: Record<string, NotebookAgentConfig>;
+    notebookConfigs: Record<string, NotebookWorkspaceConfig>;
   },
 }));
 
@@ -44,28 +47,48 @@ vi.mock("@features/memo/store/note-store", () => ({
   },
 }));
 
-vi.mock("@features/memo/use-cases/open-by-target", () => ({
+vi.mock("@features/memo/public/note-navigation-api", () => ({
   openNoteByMemoId: vi.fn(),
 }));
 
 vi.mock("@features/workspace/use-cases/browser-column-navigation", () => ({
   openBrowserColumnFileBrowser,
+  openBrowserColumnNotebookNote: vi.fn(),
 }));
 
-vi.mock("@features/agent/store/agent-access-store", () => ({
-  useAgentAccessStore: {
-    getState: () => ({
-      config: accessState.config,
-      notebookConfigs: accessState.notebookConfigs,
-      addFolderFromPicker,
-      setDefaultFiles,
-    }),
-  },
-}));
+vi.mock("@features/agent/store/agent-workspace-store", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@features/agent/store/agent-workspace-store")>();
+  const getState = () => ({
+      ...actual.useAgentWorkspaceStore.getState(),
+      workspace: actual.projectAgentWorkspace({
+        notebooks: [{ id: "notebook-1", name: "项目", path: "/repo/project" }],
+        notebookConfigs: Object.fromEntries(Object.entries(accessState.notebookConfigs).map(([id, config]) => [id, {
+          ...config, addDirs: config.addDirs.map(directory => ({ ...directory, missing: accessState.config.entries.find(e => e.path === directory.path)?.missing ?? false })),
+        }])),
+      }),
+      workspaceActions: {
+        ...actual.useAgentWorkspaceStore.getState().workspaceActions,
+        addFolderFromPicker,
+        attachFolderToNotebook,
+        detachFolderFromNotebook,
+        getNotebookFiles: () => undefined,
+      },
+    });
+  return { ...actual, useAgentWorkspaceStore: Object.assign(
+    (selector: Parameters<typeof actual.useAgentWorkspaceStore>[0]) => selector ? selector(getState()) : getState(),
+    actual.useAgentWorkspaceStore,
+    { getState },
+  ) };
+});
 
 vi.mock("@features/agent/store/agent-session-store", () => ({
   useAgentSessionStore: {
-    getState: () => ({ getInstance: () => undefined, sessionMeta: { settings: {} } }),
+    subscribe: vi.fn(() => vi.fn()),
+    getState: () => ({
+      getInstance: (id: string) => id === "mode-conversation"
+        ? { runtimeConfig: { deepseekHarness: { mode: "standard" } } } : undefined,
+      sessionMeta: { settings: {} },
+    }),
   },
 }));
 
@@ -74,6 +97,9 @@ vi.mock("@features/agent/store/dsh-model-config-store", () => ({
 }));
 
 import { ExternalAgentSettingsController } from "./external-agent-settings-controller";
+import { AgentThreadCardSubscriptionsController } from "../runtime/thread-card-subscriptions-controller";
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
 
 function folderEntry(path: string, name: string, missing = false): AgentAccessEntry {
   return {
@@ -112,7 +138,8 @@ describe("agent workspace popover repositories page", () => {
   beforeEach(() => {
     document.body.replaceChildren();
     addFolderFromPicker.mockReset();
-    setDefaultFiles.mockReset().mockResolvedValue(true);
+    attachFolderToNotebook.mockReset().mockResolvedValue("saved");
+    detachFolderFromNotebook.mockReset().mockResolvedValue("saved");
     openBrowserColumnFileBrowser.mockReset();
     toast = vi.fn();
     setupAccess(
@@ -169,6 +196,64 @@ describe("agent workspace popover repositories page", () => {
     ).map((node) => node.textContent ?? "");
   }
 
+  it("keeps the DSH mode button and open picker subscribed to the user's choice", () => {
+    useAgentDataStore.getState().setUserPreference("dsh", { mode: "code" });
+    const modeController = new ExternalAgentSettingsController({
+      popover, getTypeKey: () => "dsh", getInstanceId: () => "mode-conversation",
+      getLanguage: () => "zh-CN", t: (key) => key, isDestroyed: () => false,
+    });
+    const button = modeController.createComposerModeButton()!;
+    document.body.append(button);
+    const subscriptions = new AgentThreadCardSubscriptionsController({
+      getRuntimeThreadId: () => null, getRenderThreadId: () => null, getStoredThreadId: () => null,
+      getTypeKey: () => "dsh", getInstanceId: () => "mode-conversation",
+      getResolvedSessionId: () => null, renderThreadState: vi.fn(), refreshAttrs: vi.fn(),
+      refreshExternalAgentEmptySettings: () => modeController.refreshEmptySettings(),
+      isExternalSettingsOpen: () => true,
+      renderCodexSettingsPopover: () => modeController.renderPopover(),
+      applyResolvedExternalSessionId: vi.fn(), syncRuntimeBadge: vi.fn(),
+    });
+    subscriptions.subscribe();
+    try {
+      expect(button.textContent).toContain("agent.mode.code");
+      button.click();
+      expect(popover.querySelector('[aria-checked="true"]')?.textContent).toContain("agent.mode.code");
+      useAgentDataStore.getState().setUserPreference("dsh", { mode: "minimal" });
+      expect(button.textContent).toContain("agent.mode.minimal");
+      expect(popover.querySelector('[aria-checked="true"]')?.textContent).toContain("agent.mode.minimal");
+    } finally {
+      subscriptions.dispose();
+      modeController.dispose();
+    }
+  });
+
+  it("refreshes Agent settings when the workspace snapshot changes", () => {
+    const refreshAttrs = vi.fn();
+    const refreshExternalAgentEmptySettings = vi.fn();
+    const subscriptions = new AgentThreadCardSubscriptionsController({
+      getRuntimeThreadId: () => null, getRenderThreadId: () => null, getStoredThreadId: () => null,
+      getTypeKey: () => "dsh", getInstanceId: () => null,
+      getResolvedSessionId: () => null, renderThreadState: vi.fn(), refreshAttrs,
+      refreshExternalAgentEmptySettings, isExternalSettingsOpen: () => false,
+      renderCodexSettingsPopover: vi.fn(), applyResolvedExternalSessionId: vi.fn(), syncRuntimeBadge: vi.fn(),
+    });
+    const previousWorkspace = useAgentWorkspaceStore.getState().workspace;
+    subscriptions.subscribe();
+    try {
+      useAgentWorkspaceStore.setState({ workspace: {
+        ...previousWorkspace,
+        resources: [...previousWorkspace.resources, {
+          id: "folder-1", path: "/folder-1", name: "folder-1", enabled: true, missing: false,
+        }],
+      } });
+      expect(refreshAttrs).toHaveBeenCalledOnce();
+      expect(refreshExternalAgentEmptySettings).toHaveBeenCalledOnce();
+    } finally {
+      subscriptions.dispose();
+      useAgentWorkspaceStore.setState({ workspace: previousWorkspace });
+    }
+  });
+
   it("首先渲染只读的「可访问」页, 不跳转文件浏览器", () => {
     openAccessPopover();
     expect(headings()).toContain("agent.workspace.access");
@@ -236,7 +321,7 @@ describe("agent workspace popover repositories page", () => {
     expect(pageTitles()).toContain("agent.workspace.manageRepositories");
   });
 
-  it("删除仓库会写回当前笔记本的 add-dir 列表", async () => {
+  it("删除仓库只从当前笔记本移除对应路径", async () => {
     openAccessPopover();
     (popover.querySelector(".agent-thread-card__codex-settings-settings") as HTMLButtonElement).click();
 
@@ -247,12 +332,9 @@ describe("agent workspace popover repositories page", () => {
     removeButtons[0].click();
 
     await vi.waitFor(() => {
-      expect(setDefaultFiles).toHaveBeenCalledTimes(1);
+      expect(detachFolderFromNotebook).toHaveBeenCalledTimes(1);
     });
-    expect(setDefaultFiles).toHaveBeenCalledWith(
-      "notebook-1",
-      expect.objectContaining({ folders: ["/repo/assets"] }),
-    );
+    expect(detachFolderFromNotebook).toHaveBeenCalledWith("notebook-1", "/repo/docs");
     expect(toast).toHaveBeenCalledWith(
       "success",
       expect.stringContaining("agent.access.folderDeleted"),
@@ -274,12 +356,9 @@ describe("agent workspace popover repositories page", () => {
     add.click();
 
     await vi.waitFor(() => {
-      expect(setDefaultFiles).toHaveBeenCalledTimes(1);
+      expect(addFolderFromPicker).toHaveBeenCalledWith("notebook-1");
     });
-    expect(setDefaultFiles).toHaveBeenCalledWith(
-      "notebook-1",
-      expect.objectContaining({ folders: ["/repo/docs", "/repo/assets", "/repo/new"] }),
-    );
+    expect(attachFolderToNotebook).not.toHaveBeenCalled();
   });
 
   it("关闭弹窗后重新打开会回到「可访问」页", () => {
diff --git a/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.test.ts b/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.test.ts
index ec01e181e..fb46f0abd 100644
--- a/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.test.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.test.ts
@@ -47,12 +47,13 @@ vi.mock("@features/memo/store/note-store", () => ({
   },
 }));
 
-vi.mock("@features/memo/use-cases/open-by-target", () => ({
+vi.mock("@features/memo/public/note-navigation-api", () => ({
   openNoteByMemoId: vi.fn(),
 }));
 
 vi.mock("@features/workspace/use-cases/browser-column-navigation", () => ({
   openBrowserColumnFileBrowser: vi.fn(),
+  openBrowserColumnNotebookNote: vi.fn(),
 }));
 
 import { ExternalAgentSettingsController } from "./external-agent-settings-controller";
@@ -62,7 +63,7 @@ let storedFilter = { key: "", operator: "", value: "" };
 
 function memo(id: string, properties: Record<string, unknown>): MemoItem {
   return {
-    id,
+    relativePath: `${id}.md`,
     filename: `${id}.md`,
     preview: `${id} description`,
     thumbnail: null,
@@ -147,7 +148,7 @@ describe("ExternalAgentSettingsController featured notes", () => {
 
     const children = Array.from(empty.children);
     const iconIndex = children.findIndex((node) => node.classList.contains("agent-thread-card__empty-agent-icon"));
-    const controlsIndex = children.findIndex((node) => node.classList.contains("agent-thread-card__empty-controls"));
+    const controlsIndex = children.findIndex((node) => node.classList.contains("agent-conversation__controls"));
     const notesIndex = children.findIndex((node) => node.classList.contains("agent-thread-card__featured-notes"));
     expect(iconIndex).toBeGreaterThanOrEqual(0);
     expect(controlsIndex).toBeGreaterThan(iconIndex);
diff --git a/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.ts b/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.ts
index c3e28fb27..223f4fd4e 100644
--- a/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/external-agent-settings-controller.ts
@@ -1,10 +1,10 @@
+import { resolveAgentPreferenceRuntimeConfig } from "@features/agent/store/agent-user-preferences";
 import cursorOutlineSvg from "@/assets/cursor-outline.svg?raw";
 import folderOutlineSvg from "@/assets/folder-outline.svg?raw";
 import shieldAlertOutlineSvg from "@/assets/shield-alert-outline.svg?raw";
 import shieldCheckOutlineSvg from "@/assets/shield-check-outline.svg?raw";
 import type { AppLanguage, I18nKey, I18nParams } from "@/lib/i18n";
 import { translate } from "@/lib/i18n";
-import { resolveNotebookAgentFiles } from "@/lib/agent-access-defaults";
 import { getWorkspaceAgentRepositories } from "@features/agent/public/workspace-api";
 import type {
   AgentCodexModel,
@@ -30,25 +30,26 @@ const PI_THINKING_OPTIONS = [
   { id: "max", label: "Max" },
 ] as const;
 import {
-  getAgentAccessOptions,
   supportsAgentRuntimeSetting,
   type AgentAccessOption,
   type AgentRuntimeSettingKind,
 } from "@features/agent/runtime/agent-runtime-spec";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
+import { modelPreferenceKey, useAgentDataStore, type AgentModelCatalog } from "@features/agent/store/agent-data-store";
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
+import { loadAgentModelCatalog } from "@features/agent/services/agent-catalog-service";
 import { useAgentRuntimeStore } from "@features/agent/store/agent-runtime-store";
 import { useAgentSessionStore } from "@features/agent/store/agent-session-store";
-import { loadDshModelConfigs } from "@features/agent/store/dsh-model-config-store";
 import { useNoteStore } from "@features/memo/store/note-store";
 import { FeaturedNotesController } from './featured-notes-controller';
 import { resolvePrimaryWorkspace } from "@features/agent/runtime/primary-workspace";
 import { normalizeWorkspacePath } from "@features/agent/runtime/workspace-path";
+import { normalizeAgentRuntimeStatus } from "@features/agent/runtime/agent-runtime-status";
 import {
   normalizeConversationWorkspaceState,
   selectDesiredWorkspace,
 } from "@features/agent/runtime/conversation-workspace";
 import { ensureConversationWorkspaceSnapshot } from "@features/agent/runtime/workspace-snapshot";
-import { agent, dshIntegration, piModels, windows } from "@platform/tauri/client";
+import { agent, windows } from "@platform/tauri/client";
 import { POPUP_SEPARATOR_CLASS } from "@shared/ui/popup-separator";
 import { subscribe, type UnlistenFn } from "@platform/tauri/event-bus";
 import {
@@ -69,11 +70,17 @@ import {
   createPlusIcon,
   createTrashIcon,
 } from "@features/agent/thread-card/agent-thread-card-icons";
+import {
+  createPiModelPicker,
+  isFlowixCloudModelOption,
+} from "@features/agent/thread-card/settings/model-picker/pi-model-picker";
+import type { AgentModelOption } from "@features/agent/thread-card/settings/model-picker/model-picker-types";
 
 const CODEX_SETTINGS_POPOVER_WIDTH_PX = 212;
 const CODEX_SETTINGS_POPOVER_MAX_HEIGHT_PX = 280;
 const CODEX_SETTINGS_POPOVER_OFFSET_PX = 6;
 const CODEX_SETTINGS_POPOVER_VIEWPORT_PADDING_PX = 8;
+type SettingsPopoverPlacement = "anchor" | "submenu";
 
 
 function createComposerWorkspaceIcon(): SVGSVGElement | null {
@@ -81,7 +88,7 @@ function createComposerWorkspaceIcon(): SVGSVGElement | null {
   template.innerHTML = folderOutlineSvg.trim();
   const icon = template.content.firstElementChild as SVGSVGElement | null;
   if (!icon) return null;
-  icon.classList.add("agent-thread-card__composer-workspace-icon");
+  icon.classList.add("agent-composer__workspace-icon");
   icon.setAttribute("aria-hidden", "true");
   icon.setAttribute("focusable", "false");
   return icon;
@@ -112,14 +119,24 @@ function createPermissionModeIcon(
   return icon;
 }
 
-type AgentModelOption = {
-  id: AgentCodexModel;
-  label: string;
-  reasoningEfforts?: AgentCodexReasoningEffort[];
-  /** DeepSeek Harness llm-pi-ai route; absent for legacy/Codex options. */
-  providerId?: string;
-  providerName?: string;
-};
+function modelProviderIcon(iconUrl?: string): HTMLImageElement | undefined {
+  if (!iconUrl) return undefined;
+  try {
+    if (new URL(iconUrl).protocol !== "https:") return undefined;
+  } catch {
+    return undefined;
+  }
+  const image = document.createElement("img");
+  image.className = "agent-thread-card__model-provider-icon";
+  image.src = iconUrl;
+  image.alt = "";
+  image.loading = "lazy";
+  image.referrerPolicy = "no-referrer";
+  image.onerror = () => image.remove();
+  return image;
+}
+
+export type AgentEmptyStatePresentation = "inline-card" | "expanded";
 
 const CLAUDE_MODEL_OPTIONS: AgentModelOption[] = [
   { id: "claude-opus-4-8", label: "claude-opus-4-8" },
@@ -127,33 +144,6 @@ const CLAUDE_MODEL_OPTIONS: AgentModelOption[] = [
   { id: "claude-haiku-4-5", label: "claude-haiku-4-5" },
 ];
 
-const DEEPSEEK_HARNESS_MODE_OPTIONS: readonly {
-  id: AgentHarnessPreset;
-  labelKey: I18nKey;
-  descriptionKey: I18nKey;
-}[] = [
-  {
-    id: "standard",
-    labelKey: "agent.mode.standard",
-    descriptionKey: "agent.mode.standard.description",
-  },
-  {
-    id: "code",
-    labelKey: "agent.mode.code",
-    descriptionKey: "agent.mode.code.description",
-  },
-  {
-    id: "minimal",
-    labelKey: "agent.mode.minimal",
-    descriptionKey: "agent.mode.minimal.description",
-  },
-  {
-    id: "cordis",
-    labelKey: "agent.mode.cordis",
-    descriptionKey: "agent.mode.cordis.description",
-  },
-];
-
 export interface ExternalAgentSettingsControllerOptions {
   popover: HTMLDivElement;
   getTypeKey: () => AgentTypeKey;
@@ -169,6 +159,10 @@ export interface ExternalAgentSettingsControllerOptions {
   isDestroyed: () => boolean;
   isRunning?: () => boolean;
   consumeOutsidePointer?: (event: PointerEvent) => void;
+  onPopoverStateChange?: (
+    open: boolean,
+    anchor: HTMLButtonElement | null,
+  ) => void;
   /**
    * 点击常用笔记卡片时的动作 ── 把该笔记作为行内引用注入 composer 输入框
    * (而不是打开笔记)。由宿主 (thread card view / 独立对话) 接到
@@ -190,6 +184,10 @@ export class ExternalAgentSettingsController {
   private readonly t: (key: I18nKey, params?: I18nParams) => string;
   private readonly isDestroyed: () => boolean;
   private readonly consumeOutsidePointer?: (event: PointerEvent) => void;
+  private readonly onPopoverStateChange?: (
+    open: boolean,
+    anchor: HTMLButtonElement | null,
+  ) => void;
   private readonly toast?: (
     kind: "success" | "error" | "info",
     message: string,
@@ -209,6 +207,7 @@ export class ExternalAgentSettingsController {
   private kind: AgentRuntimeSettingKind | null = null;
   private open = false;
   private workspacePopoverOpen = false;
+  private popoverPlacement: SettingsPopoverPlacement = "anchor";
   /**
    * 「可访问」弹窗的第二页 (仓库列表)。 弹窗只有一块 DOM, 翻页通过替换内容
    * 实现而不是叠一个新弹窗 ── 保持单一定位/外点关闭/焦点语义, 返回时也不
@@ -241,6 +240,7 @@ export class ExternalAgentSettingsController {
     this.t = options.t;
     this.isDestroyed = options.isDestroyed;
     this.consumeOutsidePointer = options.consumeOutsidePointer;
+    this.onPopoverStateChange = options.onPopoverStateChange;
     this.featuredNotes = new FeaturedNotesController({
       getNotebookId: () => this.getCurrentNotebookId(),
       t: options.t,
@@ -282,9 +282,9 @@ export class ExternalAgentSettingsController {
 
   /**
    * 读 model/permission/reasoning 控件的当前值 ── 优先 instance 快照；
-   * Pi Codemode 是全局偏好，始终读取共享默认值。
+   * 模式按钮始终显示当前 Agent 的 user.mode；执行时再解析会话覆盖。
    *  - instanceId 存在 + runtimeConfig 对应字段非空 → 用 instance 值
-   *  - 否则 → fallback 到全局 useAgentSessionStore 对应字段
+   *  - 否则 → 当前 Agent 的 user 偏好与内建默认值
    *
    * 注意：fallback 不写回 instance.runtimeConfig ── 仅"显示"，不修改快照。
    * 发消息时若 instance 没显式设置，也会走全局 fallback。
@@ -295,63 +295,21 @@ export class ExternalAgentSettingsController {
     kind: K,
   ): string | undefined {
     const instanceId = this.getInstanceId();
-    // Phase 4 (2026-08-02): 真源切到 session-store.sessionMeta.settings.
-    const settings = useAgentSessionStore.getState().sessionMeta.settings;
-    if (kind === "mode" && this.getTypeKey() === "pi") {
-      const sharedCodeMode = useAgentAccessStore.getState().config.defaults
-        ?.runtime?.pi?.piCodeMode;
-      return sharedCodeMode ? "code" : "writing";
-    }
-    if (instanceId) {
-      const runtimeConfig =
-        useAgentSessionStore.getState().getInstance(instanceId)
-          ?.runtimeConfig;
-      if (runtimeConfig) {
-        if (kind === "model" && runtimeConfig.model?.key) {
-          return runtimeConfig.model.key;
-        }
-        if (kind === "permission" && runtimeConfig.access?.sandbox) {
-          return runtimeConfig.access.sandbox;
-        }
-        if (kind === "reasoning" && runtimeConfig.reasoningEffort) {
-          return runtimeConfig.reasoningEffort;
-        }
-        if (kind === "mode" && runtimeConfig.deepseekHarness?.mode) {
-          return runtimeConfig.deepseekHarness.mode;
-        }
-      }
-    }
-    const typeDefault =
-      useAgentAccessStore.getState().config.defaults?.runtime?.[this.getTypeKey()];
-    if (typeDefault) {
-      if (kind === "model" && typeDefault.model?.key) return typeDefault.model.key;
-      if (kind === "permission" && typeDefault.access?.sandbox) {
-        return typeDefault.access.sandbox;
-      }
-      if (kind === "reasoning" && typeDefault.reasoningEffort) {
-        return typeDefault.reasoningEffort;
-      }
-      if (kind === "mode" && typeDefault.mode) return typeDefault.mode;
-      if (kind === "mode" && this.getTypeKey() === "pi") {
-        return typeDefault.piCodeMode ? "code" : "writing";
-      }
-    }
-    // DSH 不继承 Codex 系全局模型选择 (用户在 Codex 卡片选过的模型对 DSH
-    // 无意义) —— 无 instance / 类型默认时等待全局 dsh-settings 的真实默认值。
-    if (kind === "model") {
-      return this.getTypeKey() === "deepseek-harness"
-        ? undefined
-        : settings.agentCodexModel;
-    }
-    // 权限默认与所有 agent 统一 (danger-full-access / 完全访问), 无特殊分支。
-    if (kind === "permission") return settings.agentPermissionMode;
-    if (kind === "reasoning") return settings.agentCodexReasoningEffort;
-    return undefined;
+    const typeKey = this.getTypeKey();
+    const runtimeConfig = instanceId
+      ? useAgentSessionStore.getState().getInstance(instanceId)?.runtimeConfig
+      : undefined;
+    const resolved = resolveAgentPreferenceRuntimeConfig(typeKey, runtimeConfig ?? undefined);
+    if (kind === "model") return resolved.model?.key;
+    if (kind === "permission") return resolved.access?.sandbox ?? "danger-full-access";
+    if (kind === "reasoning") return resolved.reasoningEffort ?? "medium";
+    return useAgentDataStore.getState().agents[typeKey].user.mode
+      ?? (typeKey === "pi" ? "writing" : "standard");
   }
 
   /**
    * 写 model/permission/reasoning 控件 → 路由到 instance.runtimeConfig。
-   * instanceId 不存在（编辑器临时态）时退化为全局 setAgent*, 保持现有 fallback 行为。
+   * 无 instanceId 时直接更新当前 Agent 的 user 偏好。
    */
   private writeRuntimeSetting(
     kind: "model" | "permission" | "reasoning" | "mode",
@@ -363,20 +321,15 @@ export class ExternalAgentSettingsController {
     if (instanceId) {
       const instanceStore = useAgentSessionStore.getState();
       if (kind === "model") {
+        const selectedModel = { id: value, ...(providerId?.trim() ? { providerId: providerId.trim() } : {}) };
+        const userPreference = useAgentDataStore.getState().agents[typeKey].user;
+        const modelReasoning = userPreference.reasoningByModel?.[modelPreferenceKey(selectedModel)]
+          ?? (typeKey === "codex" ? this.defaultReasoningForModel(value) : undefined);
         instanceStore.setRuntimeConfig(instanceId, {
-          model: {
-            key: value,
-            ...(providerId?.trim() ? { providerId: providerId.trim() } : {}),
-          },
+          model: { key: value, ...(providerId?.trim() ? { providerId: providerId.trim() } : {}) },
+          reasoningEffort: modelReasoning,
         });
-        void useAgentAccessStore
-          .getState()
-          .setDefaultRuntime(typeKey, {
-            model: {
-              key: value,
-              ...(providerId?.trim() ? { providerId: providerId.trim() } : {}),
-            },
-          });
+        useAgentDataStore.getState().setUserPreference(typeKey, { model: selectedModel });
         this.syncCodexThreadSetting(instanceId, kind, value);
         return;
       }
@@ -384,88 +337,66 @@ export class ExternalAgentSettingsController {
         instanceStore.setRuntimeConfig(instanceId, {
           access: { sandbox: value as AgentPermissionMode },
         });
+        useAgentDataStore.getState().setUserPreference(typeKey, { permission: value as AgentPermissionMode });
         return;
       }
       if (kind === "mode") {
+        useAgentDataStore.getState().setUserPreference(typeKey, { mode: value });
         if (typeKey === "pi") {
-          void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-            piCodeMode: value === "code",
-          });
           return;
         }
         instanceStore.setRuntimeConfig(instanceId, {
           deepseekHarness: { mode: value as AgentHarnessPreset },
         });
-        void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-          mode: value as AgentHarnessPreset,
-        });
         return;
       }
       // reasoning effort 与 model / permission 同维度，锁定在 instance 快照上。
       instanceStore.setRuntimeConfig(instanceId, {
         reasoningEffort: value as AgentCodexReasoningEffort,
       });
-      void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-        reasoningEffort: value as AgentCodexReasoningEffort,
-      });
+      const instanceModel = instanceStore.getInstance(instanceId)?.runtimeConfig?.model;
+      const preferenceModel = useAgentDataStore.getState().agents[typeKey].user.model;
+      useAgentDataStore.getState().rememberModelReasoning(
+        typeKey,
+        instanceModel?.key
+          ? { id: instanceModel.key, providerId: instanceModel.providerId }
+          : preferenceModel,
+        value as AgentCodexReasoningEffort,
+      );
       this.syncCodexThreadSetting(instanceId, kind, value);
       return;
     }
-    // 无 instanceId (编辑器临时态) ── 退化到全局, 保留兼容。
-    // Update canonical global settings when no instance override exists.
+    // Without a conversation, update this Agent's global preference directly.
     if (kind === "model") {
-      useAgentSessionStore.getState().setSessionMeta((meta) => ({
-        ...meta,
-        settings: {
-          ...meta.settings,
-          agentCodexModel: value as AgentCodexModel,
-        },
-      }));
-      void useAgentAccessStore
-        .getState()
-        .setDefaultRuntime(typeKey, {
-          model: {
-            key: value,
-            ...(providerId?.trim() ? { providerId: providerId.trim() } : {}),
-          },
+      const selectedModel = { id: value, ...(providerId?.trim() ? { providerId: providerId.trim() } : {}) };
+      useAgentDataStore.getState().setUserPreference(typeKey, {
+        model: selectedModel,
+      });
+      if (typeKey === "codex") {
+        useAgentDataStore.getState().setUserPreference(typeKey, {
+          reasoningEffort: useAgentDataStore.getState().agents.codex.user.reasoningByModel?.[modelPreferenceKey(selectedModel)]
+            ?? this.defaultReasoningForModel(value),
         });
+      }
       return;
     }
     if (kind === "permission") {
-      useAgentSessionStore.getState().setSessionMeta((meta) => ({
-        ...meta,
-        settings: {
-          ...meta.settings,
-          agentPermissionMode: value as AgentPermissionMode,
-        },
-      }));
-      void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-        access: { sandbox: value as AgentPermissionMode },
-      });
+      useAgentDataStore.getState().setUserPreference(typeKey, { permission: value as AgentPermissionMode });
       return;
     }
     if (kind === "mode") {
+      useAgentDataStore.getState().setUserPreference(typeKey, { mode: value });
       if (typeKey === "pi") {
-        void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-          piCodeMode: value === "code",
-        });
         return;
       }
-      void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-        mode: value as AgentHarnessPreset,
-      });
       return;
     }
-    useAgentSessionStore.getState().setSessionMeta((meta) => ({
-      ...meta,
-      settings: {
-        ...meta.settings,
-        agentCodexReasoningEffort: value as AgentCodexReasoningEffort,
-      },
-    }));
-    void useAgentAccessStore.getState().setDefaultRuntime(typeKey, {
-      reasoningEffort: value as AgentCodexReasoningEffort,
-    });
+    const model = useAgentDataStore.getState().agents[typeKey].user.model;
+    useAgentDataStore.getState().rememberModelReasoning(
+      typeKey,
+      model,
+      value as AgentCodexReasoningEffort,
+    );
   }
 
   private syncCodexThreadSetting(
@@ -489,6 +420,14 @@ export class ExternalAgentSettingsController {
     });
   }
 
+  private defaultReasoningForModel(modelId: string): AgentCodexReasoningEffort {
+    const model = useAgentDataStore.getState().agents.codex.catalog.models.items
+      .find((option) => option.id === modelId);
+    return model?.reasoningEfforts?.includes("medium")
+      ? "medium"
+      : model?.reasoningEfforts?.[0] ?? "medium";
+  }
+
   get isOpen(): boolean {
     return this.open;
   }
@@ -501,186 +440,54 @@ export class ExternalAgentSettingsController {
     return this.anchor;
   }
 
-  loadDefaultModel(): void {
+  loadDefaultModel(force = false): void {
     const typeKey = this.getTypeKey();
-    if (typeKey === "pi") {
-      this.piModelsLoadFailed = false;
-      void Promise.all([piModels.list(), agent.listSupportedModels("pi")])
-        .then(([providers, models]) => {
-          if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
-          const configuredDefault = providers.find((provider) => provider.defaultModelId);
-          this.piDefaultModel = configuredDefault?.defaultModelId ?? "";
-          this.piDefaultProviderId = configuredDefault?.id;
-          const providerNames = new Map(providers.map((provider) => [provider.id, provider.displayName]));
-          const seen = new Set<string>();
-          this.localSupportedModelsTypeKey = typeKey;
-          this.localSupportedModels = models.flatMap((model) => {
-            const separator = model.indexOf("::");
-            if (separator < 1) return [];
-            const providerId = model.slice(0, separator);
-            const id = model.slice(separator + 2);
-            const key = `${providerId}\u0000${id}`;
-            if (!id || seen.has(key)) return [];
-            seen.add(key);
-            return [{
-              id,
-              label: formatModelDisplayLabel(id),
-              providerId,
-              providerName: providerNames.get(providerId) ?? providerId,
-            }];
-          });
-          this.refreshEmptySettings();
-          if (this.open && this.kind === "model") {
-            this.renderPopover();
-            this.schedulePosition();
-          }
-        })
-        .catch(() => {
-          if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
-          this.piModelsLoadFailed = true;
-          this.localSupportedModelsTypeKey = typeKey;
-          this.localSupportedModels = [];
-          this.refreshEmptySettings();
-          if (this.open && this.kind === "model") {
-            this.renderPopover();
-            this.schedulePosition();
-          }
-        });
-      return;
-    }
-    const isDeepseekHarness = typeKey === "deepseek-harness";
-    if (isDeepseekHarness) {
-      void loadDshModelConfigs()
-        .then((configs) => {
-          if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
-          const configuredDefault = useAgentAccessStore
-            .getState()
-            .config.defaults?.runtime?.['deepseek-harness']?.model;
-          const firstConfig = configs[0]?.model;
-          this.dshDefaultModel = configuredDefault?.key
-            && configuredDefault.key !== 'inherit'
-            ? configuredDefault.key.trim()
-            : firstConfig?.model.trim() ?? "";
-          this.dshDefaultProviderId = configuredDefault?.key
-            && configuredDefault.key !== 'inherit'
-            ? configuredDefault.providerId?.trim() || undefined
-            : firstConfig?.providerId?.trim() || undefined;
-
-          const seen = new Set<string>();
-          this.localSupportedModelsTypeKey = typeKey;
-          this.localSupportedModels = configs.flatMap((file) => {
-            const config = file.model;
-            const providerId = config.providerId?.trim() || undefined;
-            const providerName = config.displayName?.trim() || config.provider;
-            const models = config.models?.length
-              ? config.models
-              : config.model.trim()
-                ? [{ id: config.model, name: "" }]
-                : [];
-            return models
-              .map((model) => ({
-                id: model.id.trim(),
-                label: formatModelDisplayLabel(model.id),
-                providerId,
-                providerName,
-              }))
-              .filter((model) => model.id.length > 0)
-              .filter((model) => {
-                const key = `${model.providerId ?? model.providerName}\u0000${model.id}`;
-                if (seen.has(key)) return false;
-                seen.add(key);
-                return true;
-              });
-          });
-          this.refreshEmptySettings();
-          if (this.open && this.kind === "model") {
-            this.renderPopover();
-            this.schedulePosition();
-          }
-        })
-        .catch(() => {
-          if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
+    const cached = useAgentDataStore.getState().agents[typeKey].catalog.models;
+    if (cached.items.length) this.applyModelCatalog(typeKey, cached);
+
+    void loadAgentModelCatalog(typeKey, { force })
+      .then((catalog) => this.applyModelCatalog(typeKey, catalog))
+      .catch(() => {
+        if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
+        if (typeKey === "pi") this.piModelsLoadFailed = !cached.items.length;
+        if (!cached.items.length) {
           this.localSupportedModelsTypeKey = typeKey;
           this.localSupportedModels = [];
-        });
-      return;
-    }
-    void agent
-      .getCodexDefaultModel()
-      .then((model) => {
-        if (this.isDestroyed()) return;
-        this.codexDefaultModel = model.trim();
+        }
         this.refreshEmptySettings();
         if (this.open && this.kind === "model") {
           this.renderPopover();
           this.schedulePosition();
         }
-      })
-      .catch(() => {
-        // Keep the generic default label when Codex has no configured default.
       });
+  }
 
-    const listSupportedModels =
-      "listSupportedModels" in agent &&
-      typeof agent.listSupportedModels === "function"
-        ? agent.listSupportedModels.bind(agent)
-        : async () => [];
-
-    const applySupportedModels = (
-      models: string[],
-      effortsByModel = new Map<string, AgentCodexReasoningEffort[]>(),
-    ) => {
-      if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
-      const seen = new Set<string>();
-      this.localSupportedModelsTypeKey = typeKey;
-      this.localSupportedModels = models
-        .map((model) => model.trim())
-        .filter((model) => model.length > 0)
-        .filter((model) => {
-          if (seen.has(model)) return false;
-          seen.add(model);
-          return true;
-        })
-        .map((model) => ({
-          id: model,
-          label: formatModelDisplayLabel(model),
-          ...(effortsByModel.has(model)
-            ? { reasoningEfforts: effortsByModel.get(model) }
-            : {}),
-        }));
-      this.refreshEmptySettings();
-      if (this.open && this.kind === "model") {
-        this.renderPopover();
-        this.schedulePosition();
-      }
-    };
-
-    if (
-      typeKey === "codex"
-      && "listCodexModelCatalog" in agent
-      && typeof agent.listCodexModelCatalog === "function"
-    ) {
-      void agent.listCodexModelCatalog()
-        .then((catalog) => {
-          const effortsByModel = new Map<string, AgentCodexReasoningEffort[]>();
-          for (const model of catalog) {
-            const efforts = model.reasoningEfforts?.filter((effort): effort is AgentCodexReasoningEffort =>
-              ["low", "medium", "high", "xhigh", "max", "ultra"].includes(effort),
-            );
-            if (efforts?.length) effortsByModel.set(model.id, efforts);
-          }
-          applySupportedModels(catalog.map((model) => model.id), effortsByModel);
-        })
-        .catch(() => applySupportedModels([]));
-    } else {
-      void listSupportedModels(typeKey)
-        .then((models) => applySupportedModels(models))
-        .catch(() => applySupportedModels([]));
+  private applyModelCatalog(typeKey: AgentTypeKey, catalog: AgentModelCatalog): void {
+    if (this.isDestroyed() || this.getTypeKey() !== typeKey) return;
+    this.localSupportedModelsTypeKey = typeKey;
+    this.localSupportedModels = catalog.items as AgentModelOption[];
+    if (typeKey === "codex") this.codexDefaultModel = catalog.defaultModel ?? "";
+    if (typeKey === "pi") {
+      this.piDefaultModel = catalog.defaultModel ?? "";
+      this.piDefaultProviderId = catalog.defaultProviderId;
+      this.piModelsLoadFailed = false;
+    }
+    if (typeKey === "dsh") {
+      this.dshDefaultModel = catalog.defaultModel ?? "";
+      this.dshDefaultProviderId = catalog.defaultProviderId;
+    }
+    this.refreshEmptySettings();
+    if (this.open && this.kind === "model") {
+      this.renderPopover();
+      this.schedulePosition();
     }
   }
 
-  createEmptySettings(options: { showControls?: boolean } = {}): HTMLElement {
-    const showControls = options.showControls ?? true;
+  createEmptySettings(
+    options: { presentation?: AgentEmptyStatePresentation } = {},
+  ): HTMLElement {
+    const presentation = options.presentation ?? "inline-card";
+    const showControls = presentation === "inline-card";
     this.workspaceDisplay = null;
     this.modelButton = null;
     this.piModelNotice = null;
@@ -688,11 +495,13 @@ export class ExternalAgentSettingsController {
     this.modeButton = null;
     this.permissionButton = null;
     const empty = document.createElement("div");
-    empty.className =
-      "agent-thread-card__empty agent-thread-card__empty--codex-settings";
+    empty.className = [
+      "agent-thread-card__empty",
+      "agent-thread-card__empty--codex-settings",
+      `agent-thread-card__empty--${presentation}`,
+    ].join(" ");
 
-    // 控件组独立成行, 让独立对话 / 全屏能在其上方叠加 Agent 图标并整体居中；
-    // 非全屏 thread card 通过 CSS 让这层保持原有的单行 flex 表现。
+    // 两种展示模式共用 Agent 标识与精选笔记；卡片内模式额外显示设置控件。
     empty.append(createExternalAgentEmptyIcon(this.getTypeKey()));
     if (this.getTypeKey() === "pi") {
       const modelNotice = document.createElement("button");
@@ -728,106 +537,16 @@ export class ExternalAgentSettingsController {
         if (this.isDestroyed()) return;
         const status = useAgentRuntimeStore.getState().statusByType.pi;
         if (!status) return;
-        unavailableNotice.hidden = status.available;
-        if (!status.available && status.reason) {
-          unavailableNotice.title = status.reason;
-        }
-      });
-    }
-    if (this.getTypeKey() === "deepseek-harness") {
-      const updateNotice = document.createElement("button");
-      updateNotice.type = "button";
-      updateNotice.className = "agent-thread-card__dsh-update-notice";
-      updateNotice.hidden = true;
-      const updateLabel = document.createElement("span");
-      updateLabel.className = "agent-thread-card__dsh-update-label";
-      const updateProgress = document.createElement("span");
-      updateProgress.className = "agent-thread-card__dsh-update-progress";
-      updateProgress.setAttribute("aria-hidden", "true");
-      updateNotice.append(updateLabel, updateProgress);
-      let updating = false;
-      let unlistenProgress: UnlistenFn | null = null;
-      let completionTimer: number | null = null;
-      const showProgress = (progress: {
-        phase: string;
-        percent?: number | null;
-      }) => {
-        const active = ["checking", "downloading", "downloaded", "installing"].includes(progress.phase);
-        if (!active) {
-          unlistenProgress?.();
-          unlistenProgress = null;
-          if (this.isDestroyed()) return;
-          if (progress.phase === "installed" || progress.phase === "up-to-date") {
-            updating = false;
-            updateNotice.disabled = false;
-            updateNotice.classList.remove("is-updating", "is-indeterminate");
-            updateNotice.classList.add("is-complete");
-            updateLabel.textContent = this.t("agent.dsh.updateComplete");
-            if (completionTimer !== null) window.clearTimeout(completionTimer);
-            completionTimer = window.setTimeout(() => {
-              completionTimer = null;
-              if (!this.isDestroyed()) updateNotice.hidden = true;
-            }, 4000);
-          } else if (progress.phase === "failed" || progress.phase === "cancelled") {
-            updating = false;
-            updateNotice.disabled = false;
-            updateNotice.classList.remove("is-updating", "is-indeterminate");
-            updateNotice.classList.add("is-failed");
-            updateLabel.textContent = this.t("agent.dsh.updateFailed");
-          }
-          return;
-        }
-        if (this.isDestroyed()) return;
-        updateNotice.hidden = false;
-        updateNotice.disabled = true;
-        updateNotice.classList.add("is-updating");
-        updateNotice.classList.remove("is-complete", "is-failed");
-        const percent = progress.percent;
-        if (progress.phase === "downloading" && typeof percent === "number") {
-          updateNotice.classList.remove("is-indeterminate");
-          updateNotice.style.setProperty("--dsh-update-progress", `${Math.max(0, Math.min(100, percent))}%`);
-          updateLabel.textContent = this.t("agent.dsh.updateDownloading").replace("{percent}", String(percent));
-        } else {
-          updateNotice.classList.add("is-indeterminate");
-          updateLabel.textContent = progress.phase === "installing"
-            ? this.t("agent.dsh.updateInstalling")
-            : this.t("agent.dsh.updatePreparing");
-        }
-      };
-      updateNotice.addEventListener("click", (event) => {
-        event.stopPropagation();
-        if (updating) return;
-        if (completionTimer !== null) {
-          window.clearTimeout(completionTimer);
-          completionTimer = null;
+        const runtimeStatus = normalizeAgentRuntimeStatus(status);
+        unavailableNotice.hidden = runtimeStatus.state === "ready";
+        if (runtimeStatus.state !== "ready" && runtimeStatus.reason) {
+          unavailableNotice.title = runtimeStatus.reason;
         }
-        updating = true;
-        updateNotice.hidden = false;
-        updateNotice.disabled = true;
-        updateNotice.classList.remove("is-failed", "is-complete");
-        updateNotice.classList.add("is-updating", "is-indeterminate");
-        updateLabel.textContent = this.t("agent.dsh.updatePreparing");
-        unlistenProgress = subscribe("dsh-download-progress", showProgress);
-        void dshIntegration.updateRuntime().then(() => {
-          showProgress({ phase: "installed" });
-        }).catch(() => {
-          showProgress({ phase: "failed" });
-        });
-      });
-      updateNotice.addEventListener("mousedown", (event) => event.stopPropagation());
-      empty.append(updateNotice);
-      void dshIntegration.checkUpdate().then((check) => {
-        if (this.isDestroyed() || !check.updateAvailable || !check.latestVersion) return;
-        updateLabel.textContent = this.t("agent.dsh.updateAvailable")
-          .replace("{version}", check.latestVersion);
-        updateNotice.hidden = false;
-      }).catch(() => {
-        // Version checks are advisory and must never affect conversation setup.
       });
     }
     if (showControls) {
       const controls = document.createElement("div");
-      controls.className = "agent-thread-card__empty-controls";
+      controls.className = "agent-conversation__controls";
       empty.append(controls);
 
       this.workspaceDisplay = createExternalAgentWorkspaceDisplay(
@@ -894,16 +613,17 @@ export class ExternalAgentSettingsController {
       this.getComposerModelDisplayLabel(),
       (anchor) => this.toggleSettingsPopover("model", anchor),
     );
+    if (this.getTypeKey() === "pi") button.setAttribute("aria-haspopup", "dialog");
     button.classList.replace(
-      "agent-thread-card__composer-workspace",
-      "agent-thread-card__composer-model",
+      "agent-composer__workspace",
+      "agent-composer__model",
     );
     const value = button.querySelector<HTMLElement>(
-      ".agent-thread-card__composer-workspace-value",
+      ".agent-composer__workspace-value",
     );
     value?.classList.replace(
-      "agent-thread-card__composer-workspace-value",
-      "agent-thread-card__composer-model-value",
+      "agent-composer__workspace-value",
+      "agent-composer__model-value",
     );
     this.composerModelButton = button;
     this.refreshComposerModelButton();
@@ -928,7 +648,7 @@ export class ExternalAgentSettingsController {
       "",
       (anchor) => this.toggleWorkspacePopover(anchor),
     );
-    button.querySelector(".agent-thread-card__composer-workspace-value")?.remove();
+    button.querySelector(".agent-composer__workspace-value")?.remove();
     this.composerWorkspaceButton = button;
     this.refreshComposerWorkspaceButton();
     return button;
@@ -944,15 +664,15 @@ export class ExternalAgentSettingsController {
       (anchor) => this.toggleSettingsPopover("mode", anchor),
     );
     button.classList.replace(
-      "agent-thread-card__composer-workspace",
-      "agent-thread-card__composer-mode",
+      "agent-composer__workspace",
+      "agent-composer__mode",
     );
     const value = button.querySelector<HTMLElement>(
-      ".agent-thread-card__composer-workspace-value",
+      ".agent-composer__workspace-value",
     );
     value?.classList.replace(
-      "agent-thread-card__composer-workspace-value",
-      "agent-thread-card__composer-mode-value",
+      "agent-composer__workspace-value",
+      "agent-composer__mode-value",
     );
     this.composerModeButton = button;
     this.refreshComposerModeButton();
@@ -969,11 +689,11 @@ export class ExternalAgentSettingsController {
       (anchor) => this.toggleSettingsPopover("permission", anchor),
     );
     button.classList.replace(
-      "agent-thread-card__composer-workspace",
-      "agent-thread-card__composer-permission",
+      "agent-composer__workspace",
+      "agent-composer__permission",
     );
     const value = button.querySelector<HTMLElement>(
-      ".agent-thread-card__composer-workspace-value",
+      ".agent-composer__workspace-value",
     );
     value?.remove();
     this.composerPermissionButton = button;
@@ -985,7 +705,7 @@ export class ExternalAgentSettingsController {
     if (!this.composerModelButton) return;
     const label = this.getComposerModelDisplayLabel();
     const valueEl = this.composerModelButton.querySelector<HTMLElement>(
-      ".agent-thread-card__composer-model-value",
+      ".agent-composer__model-value",
     );
     if (valueEl) valueEl.textContent = label;
     this.composerModelButton.title = `${this.t("agent.model.title")}: ${label}`;
@@ -999,7 +719,7 @@ export class ExternalAgentSettingsController {
     if (!this.composerModeButton) return;
     const value = this.getCurrentModeLabel();
     const valueEl = this.composerModeButton.querySelector<HTMLElement>(
-      ".agent-thread-card__composer-mode-value",
+      ".agent-composer__mode-value",
     );
     if (valueEl) valueEl.textContent = value;
     const label = this.t("agent.mode.title");
@@ -1017,11 +737,11 @@ export class ExternalAgentSettingsController {
   private refreshComposerWorkspaceButton(): void {
     if (!this.composerWorkspaceButton) return;
     const currentIcon = this.composerWorkspaceButton.querySelector(
-      ".agent-thread-card__composer-workspace-icon",
+      ".agent-composer__workspace-icon",
     );
     const nextIcon = createComposerWorkspaceIcon();
     const chevron = this.composerWorkspaceButton.querySelector(
-      ".agent-thread-card__empty-control-chevron",
+      ".agent-conversation__control-chevron",
     );
     currentIcon?.remove();
     if (nextIcon && chevron) {
@@ -1049,7 +769,7 @@ export class ExternalAgentSettingsController {
     );
     const nextIcon = createPermissionModeIcon(mode);
     const chevron = this.composerPermissionButton.querySelector(
-      ".agent-thread-card__empty-control-chevron",
+      ".agent-conversation__control-chevron",
     );
     currentIcon?.remove();
     if (nextIcon && chevron) {
@@ -1082,7 +802,7 @@ export class ExternalAgentSettingsController {
     this.refreshComposerWorkspaceButton();
     if (this.workspaceDisplay) {
       const value = this.workspaceDisplay.querySelector<HTMLElement>(
-        ".agent-thread-card__empty-workspace-value",
+        ".agent-conversation__workspace-value",
       );
       const nextValue = this.getCurrentWorkspaceLabel();
       if (value) value.textContent = nextValue;
@@ -1122,13 +842,11 @@ export class ExternalAgentSettingsController {
     const path = this.getCurrentWorkspacePath();
     if (!path) return this.t("agent.workspace.unset");
 
-    const normalize = (value: string): string =>
-      value.replace(/[\\/]+$/, "").toLowerCase();
-    const entry = useAgentAccessStore
-      .getState()
-      .config.entries.find(
-        (item) => item.kind === "folder" && normalize(item.path) === normalize(path),
-      );
+    const normalize = (value: string): string => value.replace(/[\\/]+$/, "").toLowerCase();
+    const workspaceState = useAgentWorkspaceStore.getState().workspace;
+    const entry = workspaceState.resources.find(
+      (item) => normalize(item.path) === normalize(path),
+    );
     const instance = this.getInstanceId()
       ? useAgentSessionStore.getState().getInstance(this.getInstanceId()!)
       : undefined;
@@ -1138,6 +856,12 @@ export class ExternalAgentSettingsController {
         ? useNoteStore.getState().notebooks.find((item) => item.id === configuredNotebookId)
         : null) ?? useNoteStore.getState().selectedNotebook;
     if (entry?.name?.trim()) return entry.name.trim();
+    const notebookEntry = configuredNotebookId
+      ? workspaceState.byNotebookId[configuredNotebookId]?.notebook
+      : undefined;
+    if (notebookEntry && normalize(notebookEntry.path) === normalize(path) && notebookEntry.name.trim()) {
+      return notebookEntry.name.trim();
+    }
     if (notebook && normalize(notebook.path) === normalize(path) && notebook.name?.trim()) {
       return notebook.name.trim();
     }
@@ -1148,7 +872,7 @@ export class ExternalAgentSettingsController {
     const instance = this.getInstanceId()
       ? useAgentSessionStore.getState().getInstance(this.getInstanceId()!)
       : undefined;
-    const runtimeConfig = instance?.runtimeConfig;
+    const runtimeConfig = instance?.runtimeConfig ?? undefined;
     const snapshot = runtimeConfig?.workspaceSnapshot;
     const snapshotPath =
       snapshot && typeof snapshot === "object" && typeof snapshot.cwd === "string"
@@ -1161,13 +885,7 @@ export class ExternalAgentSettingsController {
         ? memoState.notebooks.find((item) => item.id === configuredNotebookId)
         : null) ?? memoState.selectedNotebook;
     const notebookPath = notebook?.path?.trim();
-    const accessState = useAgentAccessStore.getState();
-    const defaultFiles = resolveNotebookAgentFiles(
-      accessState.config,
-      accessState.notebookConfigs,
-      configuredNotebookId ?? notebook?.id,
-    );
-    const primary = resolvePrimaryWorkspace({ defaultFiles, notebookPath });
+    const primary = resolvePrimaryWorkspace({ notebookPath });
     const path = snapshotPath || (primary.kind === "empty" ? "" : primary.path);
     return path;
   }
@@ -1179,7 +897,7 @@ export class ExternalAgentSettingsController {
     const instance = this.getInstanceId()
       ? useAgentSessionStore.getState().getInstance(this.getInstanceId()!)
       : undefined;
-    const runtimeConfig = instance?.runtimeConfig;
+    const runtimeConfig = instance?.runtimeConfig ?? undefined;
     const state = normalizeConversationWorkspaceState(runtimeConfig);
     const snapshot = state?.desired ?? runtimeConfig?.workspaceSnapshot;
     const cwdPath = normalizeWorkspacePath(snapshot?.cwd ?? this.getCurrentWorkspacePath());
@@ -1189,25 +907,19 @@ export class ExternalAgentSettingsController {
       (configuredNotebookId
         ? memoState.notebooks.find((item) => item.id === configuredNotebookId)
         : null) ?? memoState.selectedNotebook;
-    const accessState = useAgentAccessStore.getState();
-    const fallbackFiles = resolveNotebookAgentFiles(
-      accessState.config,
-      accessState.notebookConfigs,
-      configuredNotebookId ?? notebook?.id,
-    );
+    const workspace = useAgentWorkspaceStore.getState().workspace.byNotebookId[configuredNotebookId ?? notebook?.id ?? ""];
+    const workspaceState = useAgentWorkspaceStore.getState().workspace;
     const addDirPaths = snapshot
       ? snapshot.workspacePaths
-      : (fallbackFiles?.folders ?? []);
-    const notebookAddDirs = configuredNotebookId
-      ? accessState.notebookConfigs[configuredNotebookId]?.addDirs ?? []
-      : [];
+      : (workspace?.addDirs.filter((directory) => directory.enabled && !directory.missing).map((directory) => directory.path) ?? []);
+    const notebookAddDirs = workspace?.addDirs ?? [];
     const notebookPath = normalizeWorkspacePath(notebook?.path ?? "").toLowerCase();
     const labelForPath = (path: string): string => {
       const key = normalizeWorkspacePath(path).toLowerCase();
       const local = notebookAddDirs.find(
         (item) => normalizeWorkspacePath(item.path).toLowerCase() === key,
       );
-      const entry = accessState.config.entries.find(
+      const entry = workspaceState.resources.find(
         (item) => normalizeWorkspacePath(item.path).toLowerCase() === key,
       );
       if (local?.label?.trim()) return local.label.trim();
@@ -1251,12 +963,42 @@ export class ExternalAgentSettingsController {
     this.setSettingsPopoverOpen(!sameMenuOpen, kind, anchor);
   }
 
+  /** Open a runtime settings picker as a right-side submenu from the add menu. */
+  openComposerSettingsPopover(
+    kind: AgentRuntimeSettingKind,
+    anchor: HTMLButtonElement,
+  ): void {
+    if (!this.supportsRuntimeSetting(kind)) return;
+    this.setSettingsPopoverOpen(true, kind, anchor, "submenu");
+  }
+
+  closeComposerSettingsPopover(anchor?: HTMLButtonElement): void {
+    if (this.popoverPlacement !== "submenu") return;
+    if (anchor && this.anchor !== anchor) return;
+    this.setSettingsPopoverOpen(false);
+  }
+
   private toggleWorkspacePopover(anchor: HTMLButtonElement): void {
     const sameMenuOpen = this.workspacePopoverOpen && this.anchor === anchor;
     if (sameMenuOpen) {
       this.setSettingsPopoverOpen(false);
       return;
     }
+    this.openWorkspacePopover(anchor, "anchor");
+  }
+
+  /** Open the read-only access page as a right-side submenu from the add menu. */
+  openComposerWorkspacePopover(anchor: HTMLButtonElement): void {
+    if (this.workspacePopoverOpen && this.anchor === anchor) return;
+    this.openWorkspacePopover(anchor, "submenu");
+  }
+
+  private openWorkspacePopover(
+    anchor: HTMLButtonElement,
+    placement: SettingsPopoverPlacement,
+  ): void {
+    this.popoverPlacement = placement;
+    this.workspacePage = "access";
     this.workspacePopoverOpen = true;
     this.open = true;
     this.kind = null;
@@ -1269,19 +1011,33 @@ export class ExternalAgentSettingsController {
     this.schedulePosition();
     this.startPositionTracking();
     document.addEventListener("pointerdown", this.handleOutsidePointer, true);
+    this.onPopoverStateChange?.(true, anchor);
   }
 
   setSettingsPopoverOpen(
     open: boolean,
     kind: AgentRuntimeSettingKind | null = null,
     anchor: HTMLButtonElement | null = null,
+    placement: SettingsPopoverPlacement = "anchor",
   ): void {
-    if (this.open === open && (!open || this.kind === kind) && !this.workspacePopoverOpen) return;
+    const nextPlacement = open ? placement : "anchor";
+    if (
+      this.open === open
+      && (!open || (
+        this.kind === kind
+        && this.anchor === anchor
+        && this.popoverPlacement === nextPlacement
+      ))
+      && !this.workspacePopoverOpen
+    ) return;
+    const previousAnchor = this.anchor;
+    this.popoverPlacement = nextPlacement;
     this.workspacePopoverOpen = false;
     this.workspacePage = "access";
     this.open = open;
     this.kind = open ? kind : null;
     this.anchor = open ? anchor : null;
+    this.onPopoverStateChange?.(open, open ? anchor : previousAnchor);
     this.popover.hidden = !open;
     this.popover.classList.toggle(
       "agent-thread-card__codex-settings-popover--mode",
@@ -1293,10 +1049,9 @@ export class ExternalAgentSettingsController {
     );
     this.syncControlOpenState(open, kind);
 
-    // Pi's model directory is edited from Preferences in another window. Refresh
-    // it whenever the composer picker opens so newly saved providers/models are
-    // immediately available without recreating the conversation card.
-    if (open && kind === "model" && this.getTypeKey() === "pi") {
+    // Recheck the shared catalog when a model picker opens. Fresh cached data
+    // renders immediately; expired or invalidated data refreshes in the background.
+    if (open && kind === "model") {
       this.loadDefaultModel();
     }
 
@@ -1343,6 +1098,17 @@ export class ExternalAgentSettingsController {
       "agent-thread-card__codex-settings-popover--model-picker",
       this.getTypeKey() === "codex" && kind === "model",
     );
+    const isPiModelPicker = this.getTypeKey() === "pi" && kind === "model";
+    this.popover.classList.toggle(
+      "agent-thread-card__codex-settings-popover--pi-model-picker",
+      isPiModelPicker,
+    );
+    this.popover.setAttribute("role", isPiModelPicker ? "dialog" : "menu");
+    if (isPiModelPicker) {
+      this.popover.setAttribute("aria-label", this.t("agent.model.title"));
+    } else {
+      this.popover.removeAttribute("aria-label");
+    }
     if (!kind || !this.supportsRuntimeSetting(kind)) return;
 
     if (kind !== "model") {
@@ -1377,6 +1143,11 @@ export class ExternalAgentSettingsController {
     this.popover.classList.remove(
       "agent-thread-card__codex-settings-popover--model-picker",
     );
+    this.popover.classList.remove(
+      "agent-thread-card__codex-settings-popover--pi-model-picker",
+    );
+    this.popover.setAttribute("role", "menu");
+    this.popover.removeAttribute("aria-label");
     this.popover.replaceChildren();
     if (this.workspacePage === "repositories") {
       this.renderRepositoryPage();
@@ -1456,7 +1227,7 @@ export class ExternalAgentSettingsController {
   }
 
   /**
-   * 第二页 ── 仓库列表, 可增删。 这里编辑的是当前笔记本 `.flowix/agent.json`
+   * 第二页 ── 仓库列表, 可增删。 这里编辑的是当前笔记本 `local.db`
    * 的 add-dirs (与笔记侧「资料文件夹」同一份数据), 所以增删后第一页的快照会
    * 在下次会话启动时同步反映出来。
    */
@@ -1504,6 +1275,7 @@ export class ExternalAgentSettingsController {
     // 「添加仓库」用第一页「管理仓库」同款的 settings 行契约, 加号放在文字左侧。
     const addButton = document.createElement("button");
     addButton.type = "button";
+    addButton.disabled = !this.getRepositoryScopeNotebookId();
     addButton.className =
       "agent-thread-card__codex-settings-item agent-thread-card__codex-settings-settings";
     addButton.setAttribute("role", "menuitem");
@@ -1527,7 +1299,7 @@ export class ExternalAgentSettingsController {
     const instance = this.getInstanceId()
       ? useAgentSessionStore.getState().getInstance(this.getInstanceId()!)
       : undefined;
-    const runtimeConfig = instance?.runtimeConfig;
+    const runtimeConfig = instance?.runtimeConfig ?? undefined;
     const memoState = useNoteStore.getState();
     const configuredNotebookId = runtimeConfig?.notebookId;
     const notebook =
@@ -1594,7 +1366,9 @@ export class ExternalAgentSettingsController {
   }
 
   private async addRepository(): Promise<void> {
-    const result = await useAgentAccessStore.getState().addFolderFromPicker();
+    const notebookId = this.getRepositoryScopeNotebookId();
+    if (!notebookId) return;
+    const result = await useAgentWorkspaceStore.getState().workspaceActions.addFolderFromPicker(notebookId);
     if (!result.ok) {
       if (result.code === "already-tracked") {
         this.toast?.("error", this.t("agent.access.alreadyTracked"));
@@ -1603,41 +1377,9 @@ export class ExternalAgentSettingsController {
       }
       return;
     }
-    const notebookId = this.getRepositoryScopeNotebookId();
-    if (!notebookId) {
-      // 没有笔记本作用域时, 全局授权条目仍然保留, 但没有 add-dir 列表可写。
-      this.rerenderRepositories();
-      return;
-    }
-    // picker 返回前已经 loadInitial 过一次, 所以要用最新 store 状态解析, 而不
-    // 是复用这次渲染的闭包快照。
-    const latest = useAgentAccessStore.getState();
-    const latestFiles = resolveNotebookAgentFiles(
-      latest.config,
-      latest.notebookConfigs,
-      notebookId,
-    );
-    const key = normalizeWorkspacePath(result.entry.path).toLowerCase();
-    if (
-      (latestFiles?.folders ?? []).some(
-        (path) => normalizeWorkspacePath(path).toLowerCase() === key,
-      )
-    ) {
-      this.toast?.("info", this.t("agent.access.folderExists"));
-      this.rerenderRepositories();
-      return;
-    }
-    const saved = await latest.setDefaultFiles(notebookId, {
-      folders: [...(latestFiles?.folders ?? []), result.entry.path],
-      notebooks: latestFiles?.notebooks ?? [],
-    });
-    if (!saved) {
-      this.toast?.("error", this.t("agent.access.saveFailed"));
-      return;
-    }
+    const latestFiles = useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles(notebookId);
     this.updateCurrentConversationWorkspaceFolders([
       ...(latestFiles?.folders ?? []),
-      result.entry.path,
     ]);
     this.rerenderRepositories();
   }
@@ -1645,17 +1387,18 @@ export class ExternalAgentSettingsController {
   private async removeRepository(path: string, name: string): Promise<void> {
     const notebookId = this.getRepositoryScopeNotebookId();
     if (!notebookId) return;
-    const state = useAgentAccessStore.getState();
-    const files = resolveNotebookAgentFiles(state.config, state.notebookConfigs, notebookId);
-    const nextFolders = (files?.folders ?? []).filter((item) => item !== path);
-    const saved = await state.setDefaultFiles(notebookId, {
-      folders: nextFolders,
-      notebooks: files?.notebooks ?? [],
-    });
-    if (!saved) {
+    const state = useAgentWorkspaceStore.getState().workspaceActions;
+    const saved = await state.detachFolderFromNotebook(notebookId, path);
+    if (saved === false) {
       this.toast?.("error", this.t("agent.access.saveFailed"));
       return;
     }
+    if (saved === "not-attached") {
+      this.rerenderRepositories();
+      return;
+    }
+    const files = useAgentWorkspaceStore.getState().workspaceActions.getNotebookFiles(notebookId);
+    const nextFolders = files?.folders ?? [];
     this.updateCurrentConversationWorkspaceFolders(nextFolders);
     this.toast?.("success", this.t("agent.access.folderDeleted", { name }));
     this.rerenderRepositories();
@@ -1691,7 +1434,7 @@ export class ExternalAgentSettingsController {
     const instance = this.getInstanceId()
       ? useAgentSessionStore.getState().getInstance(this.getInstanceId()!)
       : undefined;
-    const runtimeConfig = instance?.runtimeConfig;
+    const runtimeConfig = instance?.runtimeConfig ?? undefined;
     const state = normalizeConversationWorkspaceState(runtimeConfig);
     const snapshot = state?.desired ?? runtimeConfig?.workspaceSnapshot;
     const configuredNotebookId = runtimeConfig?.notebookId ?? snapshot?.notebookId;
@@ -1722,9 +1465,13 @@ export class ExternalAgentSettingsController {
     label: string,
     value: string,
   ): HTMLButtonElement {
-    return createExternalAgentEmptyControl(kind, label, value, (nextKind, button) => {
+    const button = createExternalAgentEmptyControl(kind, label, value, (nextKind, button) => {
       this.toggleSettingsPopover(nextKind, button);
     });
+    if (kind === "model" && this.getTypeKey() === "pi") {
+      button.setAttribute("aria-haspopup", "dialog");
+    }
+    return button;
   }
 
   private syncControlOpenState(
@@ -1749,7 +1496,7 @@ export class ExternalAgentSettingsController {
       open && kind === "reasoning" ? "true" : "false",
     );
     this.modelButton?.classList.toggle(
-      "agent-thread-card__empty-control--open",
+      "agent-conversation__control--open",
       modelExpanded,
     );
     this.composerModelButton?.setAttribute(
@@ -1757,7 +1504,7 @@ export class ExternalAgentSettingsController {
       modelExpanded ? "true" : "false",
     );
     this.composerModelButton?.classList.toggle(
-      "agent-thread-card__composer-model--open",
+      "agent-composer__model--open",
       modelExpanded,
     );
     this.composerPermissionButton?.setAttribute(
@@ -1765,7 +1512,7 @@ export class ExternalAgentSettingsController {
       open && kind === "permission" ? "true" : "false",
     );
     this.composerPermissionButton?.classList.toggle(
-      "agent-thread-card__composer-permission--open",
+      "agent-composer__permission--open",
       open && kind === "permission",
     );
     this.composerWorkspaceButton?.setAttribute(
@@ -1773,7 +1520,7 @@ export class ExternalAgentSettingsController {
       this.workspacePopoverOpen && open ? "true" : "false",
     );
     this.composerWorkspaceButton?.classList.toggle(
-      "agent-thread-card__composer-workspace--open",
+      "agent-composer__workspace--open",
       this.workspacePopoverOpen && open,
     );
     this.workspaceDisplay?.setAttribute(
@@ -1781,19 +1528,19 @@ export class ExternalAgentSettingsController {
       this.workspacePopoverOpen && open ? "true" : "false",
     );
     this.workspaceDisplay?.classList.toggle(
-      "agent-thread-card__empty-workspace--open",
+      "agent-conversation__workspace--open",
       this.workspacePopoverOpen && open,
     );
     this.permissionButton?.classList.toggle(
-      "agent-thread-card__empty-control--open",
+      "agent-conversation__control--open",
       open && kind === "permission",
     );
     this.modeButton?.classList.toggle(
-      "agent-thread-card__empty-control--open",
+      "agent-conversation__control--open",
       open && kind === "mode",
     );
     this.reasoningButton?.classList.toggle(
-      "agent-thread-card__empty-control--open",
+      "agent-conversation__control--open",
       open && kind === "reasoning",
     );
   }
@@ -1805,7 +1552,7 @@ export class ExternalAgentSettingsController {
   }
 
   private getAccessOptionsForType(): readonly AgentAccessOption[] {
-    return getAgentAccessOptions(this.getTypeKey());
+    return useAgentDataStore.getState().agents[this.getTypeKey()].catalog.capabilities.permissions;
   }
 
   private accessOptionLabel(option: AgentAccessOption): string {
@@ -1813,12 +1560,11 @@ export class ExternalAgentSettingsController {
   }
 
   private getExternalAgentModel(): AgentCodexModel {
-    // Claude 仍走 local state (per-controller); codex/claude-other
-    // 改为走 instance.runtimeConfig 优先, fallback 全局 agentCodexModel.
+    // Conversation overrides take precedence over this Agent's preferences.
     const fromThread = this.readRuntimeSetting("model");
     if (
       fromThread &&
-      !(this.getTypeKey() === "deepseek-harness" && fromThread === "inherit")
+      !(this.getTypeKey() === "dsh" && fromThread === "inherit")
     ) {
       return fromThread as AgentCodexModel;
     }
@@ -1827,11 +1573,10 @@ export class ExternalAgentSettingsController {
     }
     // DSH 不提供 inherit 选项，未单独设置时直接选中全局 dsh-settings
     // 中的真实默认模型。配置异步加载完成后 refreshEmptySettings 会更新选中项。
-    if (this.getTypeKey() === "deepseek-harness") {
+    if (this.getTypeKey() === "dsh") {
       return (this.dshDefaultModel || "inherit") as AgentCodexModel;
     }
-    // Phase 4 (2026-08-02): 真源切到 session-store.sessionMeta.settings.
-    return useAgentSessionStore.getState().sessionMeta.settings.agentCodexModel;
+    return "inherit";
   }
 
   private getExternalAgentModelProviderId(): string | undefined {
@@ -1843,12 +1588,9 @@ export class ExternalAgentSettingsController {
         ?.runtimeConfig?.model?.providerId;
       if (providerId?.trim()) return providerId.trim();
     }
-    const typeDefault = useAgentAccessStore
-      .getState()
-      .config.defaults?.runtime?.[this.getTypeKey()]
-      ?.model?.providerId;
-    if (typeDefault?.trim()) return typeDefault.trim();
-    if (this.getTypeKey() === "deepseek-harness") return this.dshDefaultProviderId;
+    const preferenceProvider = useAgentDataStore.getState().agents[this.getTypeKey()].user.model?.providerId;
+    if (preferenceProvider?.trim()) return preferenceProvider.trim();
+    if (this.getTypeKey() === "dsh") return this.dshDefaultProviderId;
     if (this.getTypeKey() === "pi") return this.piDefaultProviderId;
     return undefined;
   }
@@ -1870,7 +1612,7 @@ export class ExternalAgentSettingsController {
       }
       return formatModelDisplayLabel(model);
     }
-    if (this.getTypeKey() === "claude" || this.getTypeKey() === "opencode") {
+    if (this.getTypeKey() === "claudecode" || this.getTypeKey() === "opencode") {
       return this.t("agent.permission.default");
     }
     return this.codexDefaultModel
@@ -1891,15 +1633,17 @@ export class ExternalAgentSettingsController {
       }));
     // DSH 无硬编码 fallback —— 列表完全来自后端 (用户目录 / llm-pi-ai
     // catalog); 拉取失败时仅显示当前值, 不显示 Codex 的模型。
-    if (this.getTypeKey() === "deepseek-harness" || this.getTypeKey() === "opencode" || this.getTypeKey() === "pi") {
+    if (this.getTypeKey() === "dsh" || this.getTypeKey() === "opencode" || this.getTypeKey() === "pi") {
       return [];
     }
-    return this.getTypeKey() === "claude"
+    return this.getTypeKey() === "claudecode"
       ? mapLabel(CLAUDE_MODEL_OPTIONS)
       : mapLabel(CODEX_MODEL_OPTIONS);
   }
 
   private getLoadedModelOptions(): AgentModelOption[] {
+    const catalogOptions = useAgentDataStore.getState().agents[this.getTypeKey()].catalog.models.items;
+    if (catalogOptions.length > 0) return catalogOptions as AgentModelOption[];
     const localOptions =
       this.localSupportedModelsTypeKey === this.getTypeKey()
         ? this.localSupportedModels
@@ -1965,21 +1709,29 @@ export class ExternalAgentSettingsController {
     if (this.shouldShowPiModelEmptyState()) return [];
 
     const selection = this.resolveCurrentSelection();
-    const modelOptions = this.getLoadedModelOptions();
+    const loadedModelOptions = this.getLoadedModelOptions();
+    // Keep the Flowix Cloud provider at the top of Pi's composer picker when
+    // its catalog entry is present. Preserve the order within each provider.
+    const modelOptions = this.getTypeKey() === "pi"
+      ? [
+          ...loadedModelOptions.filter(isFlowixCloudModelOption),
+          ...loadedModelOptions.filter((option) => !isFlowixCloudModelOption(option)),
+        ]
+      : loadedModelOptions;
     const piDefaultProvider = this.getTypeKey() === "pi"
       ? modelOptions.find((option) => option.providerId === this.piDefaultProviderId)
       : undefined;
-    const inheritLabel = this.getTypeKey() === "deepseek-harness"
+    const inheritLabel = this.getTypeKey() === "dsh"
       ? ""
       : this.getExternalModelDefaultLabel();
     const showInheritOption =
-      this.getTypeKey() !== "deepseek-harness" && this.getTypeKey() !== "codex" && this.getTypeKey() !== "pi";
+      this.getTypeKey() !== "dsh" && this.getTypeKey() !== "codex" && this.getTypeKey() !== "pi";
     const options: AgentModelOption[] = [
       ...(showInheritOption && inheritLabel
         ? [{
             id: "inherit" as AgentCodexModel,
             label: inheritLabel,
-            providerId: this.getTypeKey() === "deepseek-harness"
+            providerId: this.getTypeKey() === "dsh"
               ? this.dshDefaultProviderId
               : this.getTypeKey() === "pi"
                 ? this.piDefaultProviderId
@@ -1991,12 +1743,17 @@ export class ExternalAgentSettingsController {
         : []),
       ...modelOptions,
     ];
+    const missingPiCloudModel = this.getTypeKey() === "pi"
+      && selection.providerId?.trim().toLocaleLowerCase().startsWith("flowix-cloud") === true;
     // Synthesize a tail row only when the current model is genuinely absent
     // from the directory. A model present under a different provider route is
     // reconciled above and rendered as its real option, never duplicated here.
+    // Flowix Cloud models are only valid while present in the active Cloud
+    // directory, so a stale selection must not survive logout as a synthetic row.
     if (
       selection.id !== "inherit" &&
       !(this.getTypeKey() === "pi" && !selection.id) &&
+      !missingPiCloudModel &&
       !options.some((option) =>
         option.id === selection.id
         && (option.providerId ?? "") === (selection.providerId ?? ""),
@@ -2032,7 +1789,7 @@ export class ExternalAgentSettingsController {
     );
     if (match) return match.label;
     // DSH 没有 Default 选项，等待默认模型异步加载期间不伪造一个选中值。
-    if (this.getTypeKey() === "deepseek-harness" && model === "inherit") {
+    if (this.getTypeKey() === "dsh" && model === "inherit") {
       return "";
     }
     // 未知模型仍然回退到列表中的第一个真实模型，避免控件显示空 label。
@@ -2066,7 +1823,7 @@ export class ExternalAgentSettingsController {
   private getCurrentCodexReasoningLabel(): string {
     const effort =
       this.readRuntimeSetting("reasoning") ??
-      useAgentSessionStore.getState().sessionMeta.settings.agentCodexReasoningEffort;
+      "medium";
     return (
       this.getCodexReasoningOptions().find((option) => option.id === effort)?.label ??
       "Medium"
@@ -2102,7 +1859,8 @@ export class ExternalAgentSettingsController {
 
   private getCurrentHarnessMode(): AgentHarnessPreset {
     const mode = this.readRuntimeSetting("mode");
-    return DEEPSEEK_HARNESS_MODE_OPTIONS.some((option) => option.id === mode)
+    const options = useAgentDataStore.getState().agents[this.getTypeKey()].catalog.capabilities.modes;
+    return options.some((option) => option.id === mode)
       ? (mode as AgentHarnessPreset)
       : "standard";
   }
@@ -2116,10 +1874,11 @@ export class ExternalAgentSettingsController {
       );
     }
     const mode = this.getCurrentHarnessMode();
+    const modeOption = useAgentDataStore.getState().agents[this.getTypeKey()].catalog.capabilities.modes
+      .find((option) => option.id === mode);
     return (
       this.t(
-        DEEPSEEK_HARNESS_MODE_OPTIONS.find((option) => option.id === mode)
-          ?.labelKey ?? "agent.mode.standard",
+        modeOption?.labelKey ?? "agent.mode.standard",
       )
     );
   }
@@ -2165,8 +1924,24 @@ export class ExternalAgentSettingsController {
       return;
     }
 
-    if (this.getTypeKey() === "deepseek-harness" || this.getTypeKey() === "pi") {
-      if (this.getTypeKey() === "pi" && this.shouldShowPiModelEmptyState()) {
+    if (this.getTypeKey() === "pi") {
+      const picker = createPiModelPicker({
+        models: options,
+        showMemberTab: this.getLoadedModelOptions().some(isFlowixCloudModelOption),
+        selectedModelId: current,
+        selectedProviderId: currentProviderId,
+        memberLabel: this.t("agent.pi.modelTab.member"),
+        mineLabel: this.t("agent.pi.modelTab.mine"),
+        modelLabel: this.t("agent.model.title"),
+        emptyLabel: this.t(
+          this.piModelsLoadFailed ? "agent.model.loadFailed" : "agent.model.noneFound",
+        ),
+        personalEmptyLabel: this.t("agent.pi.modelTab.mineEmpty"),
+        createModelItem: (option) => this.createModelSettingsItem(option, current, currentProviderId),
+      });
+      this.popover.append(picker);
+    } else if (this.getTypeKey() === "dsh") {
+      if (this.shouldShowPiModelEmptyState()) {
         const modelSection = document.createElement("div");
         modelSection.className = "agent-thread-card__codex-settings-section";
         modelSection.textContent = this.t("agent.model.title");
@@ -2238,9 +2013,18 @@ export class ExternalAgentSettingsController {
     const reasoningSection = document.createElement("div");
     reasoningSection.className = "agent-thread-card__codex-settings-section";
     reasoningSection.textContent = this.t("agent.reasoningDepth.title");
-    this.popover.append(reasoningSection);
-
-    this.renderReasoningOptions();
+    if (this.getTypeKey() === "pi") {
+      const reasoningGroup = document.createElement("div");
+      reasoningGroup.className = "pi-model-picker__reasoning";
+      reasoningGroup.setAttribute("role", "group");
+      reasoningGroup.setAttribute("aria-label", this.t("agent.reasoningDepth.title"));
+      reasoningGroup.append(reasoningSection);
+      this.popover.append(reasoningGroup);
+      this.renderReasoningOptions(reasoningGroup, true);
+    } else {
+      this.popover.append(reasoningSection);
+      this.renderReasoningOptions();
+    }
   }
 
   private createCodexReasoningSlider(): HTMLElement {
@@ -2249,7 +2033,7 @@ export class ExternalAgentSettingsController {
 
     const current =
       this.readRuntimeSetting("reasoning") ??
-      useAgentSessionStore.getState().sessionMeta.settings.agentCodexReasoningEffort;
+      "medium";
     const reasoningOptions = this.getCodexReasoningOptions().map((option) => ({
       ...option,
       label: this.t(`agent.reasoningDepth.${option.id}` as I18nKey),
@@ -2311,7 +2095,7 @@ export class ExternalAgentSettingsController {
       ? useAgentSessionStore.getState().getInstance(instanceId)?.runtimeConfig?.serviceTier
       : undefined;
     this.codexServiceTier = instanceServiceTier
-      ?? useAgentAccessStore.getState().config.defaults?.runtime?.codex?.serviceTier
+      ?? useAgentDataStore.getState().agents.codex.user.serviceTier
       ?? "auto";
 
     const icon = document.createElementNS("http://www.w3.org/2000/svg", "svg");
@@ -2346,7 +2130,7 @@ export class ExternalAgentSettingsController {
           serviceTier: this.codexServiceTier,
         });
       }
-      void useAgentAccessStore.getState().setDefaultRuntime("codex", {
+      useAgentDataStore.getState().setUserPreference("codex", {
         serviceTier: this.codexServiceTier,
       });
       updateValue();
@@ -2359,6 +2143,13 @@ export class ExternalAgentSettingsController {
     current: AgentCodexModel,
     currentProviderId: string | undefined,
   ): HTMLElement {
+    const isPiCloudModel = this.getTypeKey() === "pi" && isFlowixCloudModelOption(option);
+    const description = isPiCloudModel ? undefined : [
+      option.subtitle?.trim(),
+      option.creditMultiplier != null
+        ? translate(this.getLanguage(), "preferences.pi.creditMultiplier", { value: option.creditMultiplier.toFixed(2) })
+        : this.getTypeKey() === "pi" ? undefined : option.description,
+    ].filter(Boolean).join(" · ");
     return createCodexSettingsItem(
       option.label,
       option.id === current
@@ -2367,6 +2158,8 @@ export class ExternalAgentSettingsController {
         this.setExternalAgentModel(option);
         this.setSettingsPopoverOpen(false);
       },
+      description,
+      { icon: modelProviderIcon(option.iconUrl) },
     );
   }
 
@@ -2374,10 +2167,13 @@ export class ExternalAgentSettingsController {
     this.renderReasoningOptions();
   }
 
-  private renderReasoningOptions(): void {
+  private renderReasoningOptions(
+    target: HTMLElement = this.popover,
+    useButtonSelectionState = false,
+  ): void {
     const current =
       this.readRuntimeSetting("reasoning") ??
-      useAgentSessionStore.getState().sessionMeta.settings.agentCodexReasoningEffort;
+      "medium";
     const reasoningOptions = this.getTypeKey() === "pi"
       ? PI_THINKING_OPTIONS
       : this.getTypeKey() === "codex"
@@ -2389,27 +2185,28 @@ export class ExternalAgentSettingsController {
             ["low", "medium", "high", "xhigh"].includes(option.id),
           );
     reasoningOptions.forEach((option) => {
-      this.popover.append(
-        createCodexSettingsItem(option.label, option.id === current, () => {
-          this.writeRuntimeSetting("reasoning", option.id);
-          this.setSettingsPopoverOpen(false);
-        }),
-      );
+      const item = createCodexSettingsItem(option.label, option.id === current, () => {
+        this.writeRuntimeSetting("reasoning", option.id);
+        this.setSettingsPopoverOpen(false);
+      });
+      if (useButtonSelectionState) {
+        item.removeAttribute("role");
+        item.removeAttribute("aria-checked");
+        item.setAttribute("aria-pressed", option.id === current ? "true" : "false");
+      }
+      target.append(item);
     });
   }
 
   private renderModeSettings(): void {
+    const options = useAgentDataStore.getState().agents[this.getTypeKey()].catalog.capabilities.modes;
+    const current = this.readRuntimeSetting("mode")
+      ?? (this.getTypeKey() === "pi" ? "writing" : "standard");
     if (this.getTypeKey() === "pi") {
-      const current =
-        this.readRuntimeSetting("mode") === "code" ? "code" : "writing";
-      const options = [
-        { id: "writing", labelKey: "agent.mode.writing" as const },
-        { id: "code", labelKey: "agent.mode.piCode" as const },
-      ];
       options.forEach((option) => {
         this.popover.append(
           createCodexSettingsItem(
-            this.t(option.labelKey),
+            option.labelKey ? this.t(option.labelKey) : option.label,
             option.id === current,
             () => {
               this.writeRuntimeSetting("mode", option.id);
@@ -2420,20 +2217,19 @@ export class ExternalAgentSettingsController {
       });
       return;
     }
-    const current = this.getCurrentHarnessMode();
     // DSH 模式选择器使用田字格双列布局, 每个 cell 垂直堆叠标题+副标题。
     const grid = document.createElement("div");
     grid.className = "agent-thread-card__codex-settings-grid";
-    DEEPSEEK_HARNESS_MODE_OPTIONS.forEach((option) => {
+    options.forEach((option) => {
       grid.append(
         createCodexSettingsItem(
-          this.t(option.labelKey),
+          option.labelKey ? this.t(option.labelKey) : option.label,
           option.id === current,
           () => {
             this.writeRuntimeSetting("mode", option.id);
             this.setSettingsPopoverOpen(false);
           },
-          this.t(option.descriptionKey),
+          option.descriptionKey ? this.t(option.descriptionKey) : undefined,
           { layout: "grid" },
         ),
       );
@@ -2508,6 +2304,20 @@ export class ExternalAgentSettingsController {
       popoverRect.height || CODEX_SETTINGS_POPOVER_MAX_HEIGHT_PX,
       CODEX_SETTINGS_POPOVER_MAX_HEIGHT_PX,
     );
+    if (this.popoverPlacement === "submenu") {
+      const maxLeft = Math.max(padding, viewportWidth - padding - popoverWidth);
+      // A cascading settings panel touches the hovered row directly and uses
+      // that row's top edge, rather than the parent add-menu bounds, as anchor.
+      const rightPosition = anchorRect.right;
+      const preferredLeft = rightPosition + popoverWidth <= viewportWidth - padding
+        ? rightPosition
+        : anchorRect.left - popoverWidth;
+      const left = Math.min(Math.max(preferredLeft, padding), maxLeft);
+      const maxTop = Math.max(padding, viewportHeight - padding - popoverHeight);
+      const top = Math.min(Math.max(anchorRect.top, padding), maxTop);
+      applyPopoverPosition(this.popover, { left, top, placeAbove: false });
+      return;
+    }
     applyPopoverPosition(
       this.popover,
       calculateAnchoredPopoverPosition({
diff --git a/app/flowix-web/features/agent/thread-card/settings/external-agent-settings.ts b/app/flowix-web/features/agent/thread-card/settings/external-agent-settings.ts
index c235c9a7d..ef1934a03 100644
--- a/app/flowix-web/features/agent/thread-card/settings/external-agent-settings.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/external-agent-settings.ts
@@ -41,16 +41,16 @@ export function createExternalAgentWorkspaceDisplay(
 ): HTMLButtonElement {
   const display = document.createElement("button");
   display.type = "button";
-  display.className = "agent-thread-card__empty-workspace";
+  display.className = "agent-conversation__workspace";
   display.setAttribute("aria-haspopup", "menu");
   display.setAttribute("aria-expanded", "false");
   display.setAttribute("aria-label", `${label}: ${value}`);
 
   const labelEl = document.createElement("span");
-  labelEl.className = "agent-thread-card__empty-workspace-label";
+  labelEl.className = "agent-conversation__workspace-label";
   labelEl.textContent = label;
   const valueEl = document.createElement("span");
-  valueEl.className = "agent-thread-card__empty-workspace-value";
+  valueEl.className = "agent-conversation__workspace-value";
   valueEl.textContent = value;
   display.append(labelEl, valueEl, createDropdownChevron());
   display.title = `${label}: ${value}`;
@@ -70,12 +70,12 @@ export function createExternalAgentWorkspaceControl(
 ): HTMLButtonElement {
   const button = document.createElement("button");
   button.type = "button";
-  button.className = "agent-thread-card__composer-workspace";
+  button.className = "agent-composer__workspace";
   button.setAttribute("aria-haspopup", "menu");
   button.setAttribute("aria-expanded", "false");
   button.setAttribute("aria-label", `${label}: ${value}`);
   const valueEl = document.createElement("span");
-  valueEl.className = "agent-thread-card__composer-workspace-value";
+  valueEl.className = "agent-composer__workspace-value";
   valueEl.textContent = value;
   button.append(valueEl, createDropdownChevron());
   button.title = `${label}: ${value}`;
@@ -95,7 +95,7 @@ export function createDropdownChevron(): SVGSVGElement {
   svg.setAttribute("stroke-width", "2");
   svg.setAttribute("stroke-linecap", "round");
   svg.setAttribute("stroke-linejoin", "round");
-  svg.classList.add("agent-thread-card__empty-control-chevron");
+  svg.classList.add("agent-conversation__control-chevron");
   const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
   path.setAttribute("d", "m6 9 6 6 6-6");
   svg.append(path);
@@ -110,17 +110,17 @@ export function createExternalAgentEmptyControl(
 ): HTMLButtonElement {
   const button = document.createElement("button");
   button.type = "button";
-  button.className = "agent-thread-card__empty-control";
+  button.className = "agent-conversation__control";
   button.dataset.kind = kind;
   button.setAttribute("aria-haspopup", "menu");
   button.setAttribute("aria-expanded", "false");
   button.setAttribute("aria-label", label);
 
   const labelEl = document.createElement("span");
-  labelEl.className = "agent-thread-card__empty-control-label";
+  labelEl.className = "agent-conversation__control-label";
   labelEl.textContent = label;
   const valueEl = document.createElement("span");
-  valueEl.className = "agent-thread-card__empty-control-value";
+  valueEl.className = "agent-conversation__control-value";
   valueEl.textContent = value;
   button.append(labelEl, valueEl, createDropdownChevron());
 
@@ -137,7 +137,7 @@ export function updateExternalAgentEmptyControl(
   value: string,
 ): void {
   const valueEl = button?.querySelector<HTMLElement>(
-    ".agent-thread-card__empty-control-value",
+    ".agent-conversation__control-value",
   );
   if (valueEl) valueEl.textContent = value;
 }
@@ -149,7 +149,7 @@ export interface CodexSettingsItemOptions {
   readOnly?: boolean;
   selectedLabel?: string;
   notebookLabel?: boolean;
-  icon?: SVGSVGElement | null;
+  icon?: Node | null;
 }
 
 export function createCodexSettingsItem(
diff --git a/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.test.ts b/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.test.ts
index 00550ed58..a44dcb307 100644
--- a/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.test.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.test.ts
@@ -29,10 +29,7 @@ import {
 
 function memo(overrides: Partial<MemoItem>): MemoItem {
   return {
-    id: "memo-1",
-    // Path-keyed identity: card ids derive from relativePath, so keep it in
-    // sync with the fixture id to preserve the existing assertions.
-    relativePath: overrides.relativePath ?? overrides.id ?? "memo-1",
+    relativePath: overrides.relativePath ?? "memo-1.md",
     filename: "Getting started.md",
     preview: "Fallback preview",
     thumbnail: null,
@@ -59,14 +56,14 @@ describe("featured note cards", () => {
   it("uses type=skill by default and supports a custom property filter", () => {
     const memos = [
       memo({ properties: { type: "skill", name: "Writing", desc: "Draft clearly", icon: "🖋️" } }),
-      memo({ id: "memo-2", filename: "Pinned.md", properties: { pin: true } }),
-      memo({ id: "memo-3", filename: "Hidden.md", properties: { type: "reference" } }),
+      memo({ relativePath: "memo-2.md", filename: "Pinned.md", properties: { pin: true } }),
+      memo({ relativePath: "memo-3.md", filename: "Hidden.md", properties: { type: "reference" } }),
     ];
     const cards = getFeaturedNoteCards(memos);
 
     expect(cards).toEqual([
       {
-        id: "memo-1",
+        id: "memo-1.md",
         icon: "🖋️",
         name: "Writing",
         title: "Getting started",
@@ -77,17 +74,17 @@ describe("featured note cards", () => {
       memos,
       { conditions: [{ key: "pin", operator: "equals", value: "true" }] },
     ).map((card) => card.id))
-      .toEqual(["memo-2"]);
+      .toEqual(["memo-2.md"]);
     expect(getFeaturedNoteCards(
       memos,
       { conditions: [{ key: "type", operator: "contains", value: "feren" }] },
     ).map((card) => card.id))
-      .toEqual(["memo-3"]);
+      .toEqual(["memo-3.md"]);
     expect(getFeaturedNoteCards(
       memos,
       { conditions: [{ key: "type", operator: "excludes", value: "skill" }] },
     ).map((card) => card.id))
-      .toEqual(["memo-3"]);
+      .toEqual(["memo-3.md"]);
   });
 
   it("persists and restores the condition list through the notebook store", async () => {
@@ -154,9 +151,9 @@ describe("featured note cards", () => {
   it("unions multiple conditions instead of intersecting them", () => {
     // 并集语义: 命中任意一条即入选。若误写成交集, memo-1 / memo-2 会一起被排除。
     const memos = [
-      memo({ id: "memo-1", filename: "Skill.md", properties: { type: "skill" } }),
-      memo({ id: "memo-2", filename: "Pinned.md", properties: { pin: true } }),
-      memo({ id: "memo-3", filename: "Other.md", properties: { type: "reference" } }),
+      memo({ relativePath: "memo-1.md", filename: "Skill.md", properties: { type: "skill" } }),
+      memo({ relativePath: "memo-2.md", filename: "Pinned.md", properties: { pin: true } }),
+      memo({ relativePath: "memo-3.md", filename: "Other.md", properties: { type: "reference" } }),
     ];
     const cards = getFeaturedNoteCards(memos, {
       conditions: [
@@ -165,65 +162,65 @@ describe("featured note cards", () => {
       ],
     });
 
-    expect(cards.map((card) => card.id)).toEqual(["memo-1", "memo-2"]);
+    expect(cards.map((card) => card.id)).toEqual(["memo-1.md", "memo-2.md"]);
   });
 
   it("matches array-valued YAML keys element by element", () => {
     // YAML 里 tags 这类多值字段解析成数组 (见后端 frontmatter.rs: 统一成
     // Value::Array<String>)。逐元素比较才能用 equals / contains 命中。
     const memos = [
-      memo({ id: "ai", filename: "AI.md", properties: { tags: ["AI", "AI/flowix"] } }),
-      memo({ id: "cloud", filename: "Cloud.md", properties: { tags: ["云存储"] } }),
-      memo({ id: "none", filename: "None.md", properties: { tags: [] } }),
-      memo({ id: "scalar", filename: "Scalar.md", properties: { tags: "AI" } }),
+      memo({ relativePath: "ai.md", filename: "AI.md", properties: { tags: ["AI", "AI/flowix"] } }),
+      memo({ relativePath: "cloud.md", filename: "Cloud.md", properties: { tags: ["云存储"] } }),
+      memo({ relativePath: "none.md", filename: "None.md", properties: { tags: [] } }),
+      memo({ relativePath: "scalar.md", filename: "Scalar.md", properties: { tags: "AI" } }),
     ];
 
     // equals: 任一元素完全相等即命中。
     expect(getFeaturedNoteCards(memos, {
       conditions: [{ key: "tags", operator: "equals", value: "AI" }],
-    }).map((card) => card.id)).toEqual(["ai", "scalar"]);
+    }).map((card) => card.id)).toEqual(["ai.md", "scalar.md"]);
 
     // contains: 任一元素包含子串即命中 (含路径形式的标签)。
     expect(getFeaturedNoteCards(memos, {
       conditions: [{ key: "tags", operator: "contains", value: "flowix" }],
-    }).map((card) => card.id)).toEqual(["ai"]);
+    }).map((card) => card.id)).toEqual(["ai.md"]);
 
     // 空数组不命中任何条件。
     expect(getFeaturedNoteCards(memos, {
       conditions: [{ key: "tags", operator: "contains", value: "AI" }],
-    }).map((card) => card.id)).toEqual(["ai", "scalar"]);
+    }).map((card) => card.id)).toEqual(["ai.md", "scalar.md"]);
   });
 
   it("treats excludes on arrays as no element matching", () => {
     // excludes 的数组语义是「没有任何元素匹配」, 而不是「存在某个元素不匹配」——
     // 后者会让任何多值字段几乎永远满足 excludes。
     const memos = [
-      memo({ id: "ai", filename: "AI.md", properties: { tags: ["AI", "AI/flowix"] } }),
-      memo({ id: "cloud", filename: "Cloud.md", properties: { tags: ["云存储"] } }),
+      memo({ relativePath: "ai.md", filename: "AI.md", properties: { tags: ["AI", "AI/flowix"] } }),
+      memo({ relativePath: "cloud.md", filename: "Cloud.md", properties: { tags: ["云存储"] } }),
     ];
 
     expect(getFeaturedNoteCards(memos, {
       conditions: [{ key: "tags", operator: "excludes", value: "AI" }],
-    }).map((card) => card.id)).toEqual(["cloud"]);
+    }).map((card) => card.id)).toEqual(["cloud.md"]);
   });
 
   it("paginates after three cards and clamps invalid page indexes", () => {
     const notes = getFeaturedNoteCards([
-      memo({ id: "1", filename: "One.md", properties: { pin: true } }),
-      memo({ id: "2", filename: "Two.md", properties: { pin: true } }),
-      memo({ id: "3", filename: "Three.md", properties: { pin: true } }),
-      memo({ id: "4", filename: "Four.md", properties: { pin: true } }),
-      memo({ id: "5", filename: "Five.md", properties: { pin: true } }),
-      memo({ id: "6", filename: "Six.md", properties: { pin: true } }),
-      memo({ id: "7", filename: "Seven.md", properties: { pin: true } }),
+      memo({ relativePath: "1.md", filename: "One.md", properties: { pin: true } }),
+      memo({ relativePath: "2.md", filename: "Two.md", properties: { pin: true } }),
+      memo({ relativePath: "3.md", filename: "Three.md", properties: { pin: true } }),
+      memo({ relativePath: "4.md", filename: "Four.md", properties: { pin: true } }),
+      memo({ relativePath: "5.md", filename: "Five.md", properties: { pin: true } }),
+      memo({ relativePath: "6.md", filename: "Six.md", properties: { pin: true } }),
+      memo({ relativePath: "7.md", filename: "Seven.md", properties: { pin: true } }),
     ], { conditions: [{ key: "pin", operator: "equals", value: "true" }] });
 
     expect(getFeaturedNotePageCount(3)).toBe(1);
     expect(getFeaturedNotePageCount(4)).toBe(2);
     expect(getFeaturedNotePageCount(notes.length)).toBe(3);
-    expect(getFeaturedNotePage(notes, 0).map((item) => item.id)).toEqual(["1", "2", "3"]);
-    expect(getFeaturedNotePage(notes, 1).map((item) => item.id)).toEqual(["4", "5", "6"]);
-    expect(getFeaturedNotePage(notes, 99).map((item) => item.id)).toEqual(["7"]);
+    expect(getFeaturedNotePage(notes, 0).map((item) => item.id)).toEqual(["1.md", "2.md", "3.md"]);
+    expect(getFeaturedNotePage(notes, 1).map((item) => item.id)).toEqual(["4.md", "5.md", "6.md"]);
+    expect(getFeaturedNotePage(notes, 99).map((item) => item.id)).toEqual(["7.md"]);
   });
 
   it("keeps the narrow layout to three cards per page", () => {
@@ -243,12 +240,12 @@ describe("featured note cards", () => {
   it("loads and filters every memo page", async () => {
     const loadPage = vi.fn(async (cursor?: string) => cursor
       ? {
-          memos: [memo({ id: "skill-2", properties: { type: "skill" } })],
+          memos: [memo({ relativePath: "skill-2.md", properties: { type: "skill" } })],
           nextCursor: null,
           hasMore: false,
         }
       : {
-          memos: [memo({ id: "hidden", properties: {} }), memo({ id: "skill-1", properties: { type: "skill" } })],
+          memos: [memo({ relativePath: "hidden.md", properties: {} }), memo({ relativePath: "skill-1.md", properties: { type: "skill" } })],
           nextCursor: "page-2",
           hasMore: true,
         });
@@ -257,7 +254,7 @@ describe("featured note cards", () => {
 
     expect(loadPage).toHaveBeenNthCalledWith(1, undefined);
     expect(loadPage).toHaveBeenNthCalledWith(2, "page-2");
-    expect(cards.map((item) => item.id)).toEqual(["skill-1", "skill-2"]);
+    expect(cards.map((item) => item.id)).toEqual(["skill-1.md", "skill-2.md"]);
   });
 });
 
@@ -300,7 +297,7 @@ describe("featured note icon rendering", () => {
     // 默认图标是一个真实的图标 id (不再是被当文本显示的 "✦"), 因此会解析成
     // 内联 SVG; 解析失败时才会退化成字面量文本。
     const cards = getFeaturedNoteCards([
-      memo({ id: "plain", filename: "Plain.md", properties: { type: "skill" }, icon: null }),
+      memo({ relativePath: "plain.md", filename: "Plain.md", properties: { type: "skill" }, icon: null }),
     ]);
     expect(cards[0]?.icon).toBe(DEFAULT_FEATURED_NOTE_ICON);
 
diff --git a/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.ts b/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.ts
index 268317803..c11fccdcb 100644
--- a/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/featured-note-cards.ts
@@ -312,8 +312,8 @@ export function getFeaturedNoteCards(
 
     return [{
       // Test harness for the shared filter logic; production uses the path variant.
-      // Re-keyed off the path identity during the memo id decommission.
-      id: memo.relativePath || memo.filename,
+      // Use the notebook-relative path as the note key.
+      id: memo.relativePath,
       icon,
       name,
       title: noteTitle(memo.filename),
@@ -383,4 +383,3 @@ export function getFeaturedNotePage(
   const start = safePage * safePageSize;
   return notes.slice(start, start + safePageSize);
 }
-
diff --git a/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.focus.test.ts b/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.focus.test.ts
new file mode 100644
index 000000000..c3bfdd278
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.focus.test.ts
@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+vi.mock('@platform/tauri/client', () => ({
+  notes: {},
+  files: { listTableDocuments: vi.fn(async () => []) },
+  externalDocuments: {},
+}));
+vi.mock('@features/memo/public/note-navigation-api', () => ({ openNoteByNotebookPath: vi.fn() }));
+vi.mock('@features/memo/store/note-store', () => ({ useNoteStore: { getState: () => ({ notebooks: [{ id: 'book' }] }) } }));
+vi.mock('@features/multidimensional-table/parse-table-document', () => ({ parseTableDocumentAsync: vi.fn() }));
+vi.mock('./featured-note-cards', () => ({
+  FEATURED_NOTE_MOBILE_PAGE_SIZE: 2,
+  FEATURED_NOTE_PAGE_SIZE: 4,
+  appendFeaturedNoteIconContent: vi.fn(),
+  getFeaturedNotePage: () => [],
+  getFeaturedNotePageCountForSize: () => 1,
+  getFeaturedPathNoteCards: () => [],
+  readFeaturedNotesTableSelection: async () => null,
+  writeFeaturedNotesTableSelection: vi.fn(),
+}));
+import { FeaturedNotesController } from './featured-notes-controller';
+
+const controllers: FeaturedNotesController[] = [];
+
+beforeEach(() => {
+  vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false, addEventListener: vi.fn(), removeEventListener: vi.fn() })));
+});
+
+afterEach(() => {
+  controllers.forEach(controller => controller.dispose());
+  controllers.length = 0;
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+async function mount() {
+  const controller = new FeaturedNotesController({
+    getNotebookId: () => 'book',
+    t: key => key,
+    isDestroyed: () => false,
+  });
+  controllers.push(controller);
+  const card = document.createElement('div');
+  document.body.append(card);
+  await controller.appendFeaturedNotes(card);
+  const trigger = card.querySelector<HTMLButtonElement>('.agent-thread-card__featured-notes-settings-button')!;
+  const popover = [...document.body.querySelectorAll<HTMLDivElement>('.agent-thread-card__featured-notes-view-picker')].slice(-1)[0]!;
+  return { trigger, popover };
+}
+
+function pointer(target: HTMLElement) {
+  target.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+}
+
+function bodyEditor() {
+  const editor = document.createElement('div');
+  editor.tabIndex = 0;
+  document.body.append(editor);
+  editor.focus();
+  return editor;
+}
+
+it('does not move document focus to any closed card settings button on repeated outside pointers', async () => {
+  const first = await mount();
+  const second = await mount();
+  const editor = bodyEditor();
+  const focus = vi.spyOn(HTMLElement.prototype, 'focus');
+  pointer(editor);
+  pointer(editor);
+  expect(document.activeElement).toBe(editor);
+  expect(focus).not.toHaveBeenCalled();
+  expect(first.popover.hidden).toBe(true);
+  expect(second.popover.hidden).toBe(true);
+});
+
+it('closes an open popover on outside pointer without returning focus to its trigger', async () => {
+  const { trigger, popover } = await mount();
+  trigger.click();
+  const editor = bodyEditor();
+  const focus = vi.spyOn(trigger, 'focus');
+  pointer(editor);
+  expect(popover.hidden).toBe(true);
+  expect(document.activeElement).toBe(editor);
+  expect(focus).not.toHaveBeenCalled();
+});
+
+it('returns Escape focus without scrolling only while the popover owns focus', async () => {
+  const { trigger, popover } = await mount();
+  trigger.click();
+  expect(popover.contains(document.activeElement)).toBe(true);
+  const focus = vi.spyOn(trigger, 'focus');
+  document.activeElement!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }));
+  expect(popover.hidden).toBe(true);
+  expect(document.activeElement).toBe(trigger);
+  expect(focus).toHaveBeenCalledExactlyOnceWith({ preventScroll: true });
+  trigger.click();
+  const editor = bodyEditor();
+  focus.mockClear();
+  editor.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+  expect(focus).not.toHaveBeenCalled();
+  expect(document.activeElement).toBe(editor);
+});
+
+it('does not handle outside pointers after disposal', async () => {
+  const { trigger } = await mount();
+  controllers[0].dispose();
+  const editor = bodyEditor();
+  const focus = vi.spyOn(trigger, 'focus');
+  pointer(editor);
+  expect(focus).not.toHaveBeenCalled();
+  expect(document.activeElement).toBe(editor);
+});
diff --git a/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.ts b/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.ts
index 885f9d339..fcc0fcaa8 100644
--- a/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.ts
+++ b/app/flowix-web/features/agent/thread-card/settings/featured-notes-controller.ts
@@ -1,6 +1,6 @@
 import type { I18nKey, I18nParams } from '@/lib/i18n';
 import { notes as notesClient, files, externalDocuments } from '@platform/tauri/client';
-import { openNoteByNotebookPath } from '@features/memo/use-cases/open-by-target';
+import { openNoteByNotebookPath } from '@features/memo/public/note-navigation-api';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { joinNotebookMemoPath } from '@/lib/path';
 import { parseTableDocumentAsync } from '@features/multidimensional-table/parse-table-document';
@@ -133,9 +133,7 @@ export class FeaturedNotesController {
     settingsFooter.append(settingsButton, navigation);
 
     const settingsPopover = this.createTableSelectionPopover(notebookId, selection, onFilterChange, () => {
-      settingsPopover.hidden = true;
-      settingsButton.setAttribute("aria-expanded", "false");
-      settingsButton.focus();
+      setSettingsOpen(false);
     });
     document.body.append(settingsPopover);
     const positionSettingsPopover = (): void => {
@@ -154,15 +152,21 @@ export class FeaturedNotesController {
     };
     const popoverResizeObserver = new ResizeObserver(positionSettingsPopover);
     popoverResizeObserver.observe(settingsPopover);
-    const setSettingsOpen = (open: boolean): void => {
+    const setSettingsOpen = (open: boolean, restoreFocus = false): void => {
+      // Outside pointers must keep their own focus destination. Only an
+      // explicit keyboard dismissal may return focus from this popover.
+      if (open === !settingsPopover.hidden) return;
+      const returnFocus = !open && restoreFocus
+        && settingsPopover.contains(document.activeElement);
       settingsPopover.hidden = !open;
       settingsButton.setAttribute("aria-expanded", String(open));
       if (open) {
         positionSettingsPopover();
         (settingsPopover.querySelector<HTMLElement>(".agent-thread-card__featured-notes-view-option")
-          ?? settingsPopover.querySelector<HTMLElement>(".agent-thread-card__featured-notes-view-create"))?.focus();
+          ?? settingsPopover.querySelector<HTMLElement>(".agent-thread-card__featured-notes-view-create"))?.focus({ preventScroll: true });
+      } else if (returnFocus) {
+        settingsButton.focus({ preventScroll: true });
       }
-      else settingsButton.focus();
     };
     settingsButton.addEventListener("click", (event) => {
       event.stopPropagation();
@@ -204,6 +208,7 @@ export class FeaturedNotesController {
     const handleViewportChange = (): void => renderPage();
     const handleWindowResize = (): void => positionSettingsPopover();
     const handleOutsidePointer = (event: PointerEvent): void => {
+      if (settingsPopover.hidden) return;
       // 下拉层单独挂在 body, 点击内容区不关闭; 点击其他位置关闭。
       const target = event.target as Node;
       if (panel.contains(target) || settingsPopover.contains(target)) return;
@@ -213,7 +218,7 @@ export class FeaturedNotesController {
       if (settingsPopover.hidden) return;
       if (event.key !== "Escape") return;
       event.preventDefault();
-      setSettingsOpen(false);
+      setSettingsOpen(false, true);
     };
     mobileQuery.addEventListener("change", handleViewportChange);
     window.addEventListener("resize", handleWindowResize);
@@ -335,6 +340,7 @@ export class FeaturedNotesController {
     const create = document.createElement("button");
     create.type = "button";
     create.className = "flex h-8 w-full items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] text-sm text-[var(--foreground)] hover:bg-[var(--muted)] disabled:opacity-50";
+    create.classList.add("agent-thread-card__featured-notes-view-create");
     create.textContent = this.t("editor.threadCard.featuredNotes.createTable");
     create.addEventListener("click", async () => {
       onCreateTable();
diff --git a/app/flowix-web/features/agent/thread-card/settings/model-picker/model-picker-types.ts b/app/flowix-web/features/agent/thread-card/settings/model-picker/model-picker-types.ts
new file mode 100644
index 000000000..9c22c0615
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/settings/model-picker/model-picker-types.ts
@@ -0,0 +1,17 @@
+import type {
+  AgentCodexModel,
+  AgentCodexReasoningEffort,
+} from "@/types/agent";
+
+export type AgentModelOption = {
+  id: AgentCodexModel;
+  label: string;
+  description?: string;
+  subtitle?: string;
+  creditMultiplier?: number;
+  iconUrl?: string;
+  reasoningEfforts?: AgentCodexReasoningEffort[];
+  /** DeepSeek Harness llm-pi-ai route; absent for legacy/Codex options. */
+  providerId?: string;
+  providerName?: string;
+};
diff --git a/app/flowix-web/features/agent/thread-card/settings/model-picker/pi-model-picker.test.ts b/app/flowix-web/features/agent/thread-card/settings/model-picker/pi-model-picker.test.ts
new file mode 100644
index 000000000..d82030a68
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/settings/model-picker/pi-model-picker.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import type { AgentModelOption } from "./model-picker-types";
+import { createPiModelPicker } from "./pi-model-picker";
+
+function createModelItem(model: AgentModelOption): HTMLElement {
+  const item = document.createElement("button");
+  const icon = document.createElement("img");
+  icon.className = "agent-thread-card__model-provider-icon";
+  icon.src = model.iconUrl ?? "";
+  icon.alt = "";
+  const label = document.createElement("span");
+  label.className = "agent-thread-card__codex-settings-item-label";
+  label.textContent = model.label;
+  item.append(icon, label);
+  if (model.id === "deepseek-v3.2") {
+    const checkmark = document.createElement("span");
+    checkmark.className = "agent-thread-card__copy-icon";
+    item.append(checkmark);
+  }
+  return item;
+}
+
+describe("Pi model picker provider icons", () => {
+  it("uses the personal model item layout when member tabs are hidden", () => {
+    const picker = createPiModelPicker({
+      models: [
+        {
+          id: "custom-model",
+          label: "custom-model",
+          iconUrl: "https://example.com/provider-icons/custom.png",
+          providerId: "custom-provider",
+          providerName: "My provider",
+        },
+      ],
+      showMemberTab: false,
+      selectedModelId: "custom-model",
+      selectedProviderId: "custom-provider",
+      memberLabel: "会员",
+      mineLabel: "我的",
+      modelLabel: "模型",
+      emptyLabel: "没有模型",
+      personalEmptyLabel: "还没有自定义模型",
+      createModelItem,
+    });
+
+    const item = picker.querySelector<HTMLButtonElement>(".pi-model-picker__item");
+    const providerName = item?.querySelector(".pi-model-picker__provider-name");
+    expect(picker.querySelector(".pi-model-picker__tabs")).toBeNull();
+    expect(picker.querySelector(".pi-model-picker__panel > .pi-model-picker__models"))
+      .not.toBeNull();
+    expect(picker.querySelector(".pi-model-picker__provider-label")).toBeNull();
+    expect(item?.querySelector(".pi-model-picker__provider-icon")).not.toBeNull();
+    expect(providerName?.textContent).toBe("My provider");
+    const checkmarkPlaceholder = item?.querySelector(
+      ".pi-model-picker__checkmark-placeholder",
+    );
+    expect(checkmarkPlaceholder?.getAttribute("aria-hidden")).toBe("true");
+    expect(providerName?.nextElementSibling).toBe(checkmarkPlaceholder);
+  });
+
+  it("shows the provider icon before the model key in both member and personal tabs", () => {
+    const picker = createPiModelPicker({
+      models: [
+        {
+          id: "deepseek-v3.2",
+          label: "deepseek-v3.2",
+          subtitle: "稳定高速模型",
+          creditMultiplier: 1.25,
+          iconUrl: "https://staging-cloud.flowix.cc/provider-icons/deepseek.png",
+          providerId: "flowix-cloud-member",
+          providerName: "Flowix Cloud",
+        },
+        {
+          id: "custom-model",
+          label: "custom-model",
+          iconUrl: "https://example.com/provider-icons/custom.png",
+          providerId: "custom-provider",
+          providerName: "My provider",
+        },
+      ],
+      showMemberTab: true,
+      selectedModelId: "deepseek-v3.2",
+      selectedProviderId: "flowix-cloud-member",
+      memberLabel: "会员",
+      mineLabel: "我的",
+      modelLabel: "模型",
+      emptyLabel: "没有模型",
+      personalEmptyLabel: "还没有自定义模型",
+      createModelItem,
+    });
+
+    const memberItem = picker.querySelector<HTMLButtonElement>(".pi-model-picker__item");
+    expect(memberItem?.title).toBe("稳定高速模型");
+    const memberIcon = memberItem?.querySelector(".pi-model-picker__provider-icon");
+    expect(memberIcon).not.toBeNull();
+    expect(memberItem?.firstElementChild).toBe(memberIcon);
+    expect(memberItem?.querySelector(".agent-thread-card__codex-settings-item-label")?.textContent)
+      .toBe("deepseek-v3.2");
+    const multiplier = memberItem?.querySelector(".pi-model-picker__multiplier");
+    const checkmark = memberItem?.querySelector(".agent-thread-card__copy-icon");
+    expect(multiplier?.textContent).toBe("1.25x");
+    expect(multiplier?.nextElementSibling).toBe(checkmark);
+
+    picker.querySelector<HTMLButtonElement>(".pi-model-picker__tab:nth-child(2)")?.click();
+    const personalItem = picker.querySelector<HTMLButtonElement>(".pi-model-picker__item");
+    const personalIcon = personalItem?.querySelector(".pi-model-picker__provider-icon");
+    expect(personalIcon).not.toBeNull();
+    expect(personalItem?.firstElementChild).toBe(personalIcon);
+    expect(personalItem?.querySelector(".agent-thread-card__codex-settings-item-label")?.textContent)
+      .toBe("custom-model");
+    const providerName = personalItem?.querySelector(".pi-model-picker__provider-name");
+    expect(providerName?.textContent).toBe("My provider");
+    expect(providerName?.nextElementSibling?.classList.contains(
+      "pi-model-picker__checkmark-placeholder",
+    )).toBe(true);
+    expect(picker.querySelector(".pi-model-picker__provider-label")).toBeNull();
+  });
+});
diff --git a/app/flowix-web/features/agent/thread-card/settings/model-picker/pi-model-picker.ts b/app/flowix-web/features/agent/thread-card/settings/model-picker/pi-model-picker.ts
new file mode 100644
index 000000000..5c681aa44
--- /dev/null
+++ b/app/flowix-web/features/agent/thread-card/settings/model-picker/pi-model-picker.ts
@@ -0,0 +1,229 @@
+import type { AgentModelOption } from "./model-picker-types";
+
+type PiModelPickerProps = {
+  models: readonly AgentModelOption[];
+  showMemberTab: boolean;
+  selectedModelId: string;
+  selectedProviderId?: string;
+  memberLabel: string;
+  mineLabel: string;
+  modelLabel: string;
+  emptyLabel: string;
+  personalEmptyLabel: string;
+  createModelItem: (model: AgentModelOption) => HTMLElement;
+};
+
+type PiModelCategory = "member" | "mine";
+type ProviderLabelPlacement = "group" | "item" | "none";
+
+let nextTabSetId = 0;
+
+export function isFlowixCloudModelOption(model: AgentModelOption): boolean {
+  return model.providerName?.trim().toLocaleLowerCase() === "flowix cloud"
+    || model.providerId?.trim().toLocaleLowerCase().startsWith("flowix-cloud") === true;
+}
+
+function groupModels(models: readonly AgentModelOption[]) {
+  const groups = new Map<string, { label: string; models: AgentModelOption[] }>();
+  models.forEach((model) => {
+    const label = providerLabel(model);
+    const key = model.providerId?.trim() || label;
+    const group = groups.get(key);
+    if (group) {
+      group.models.push(model);
+    } else {
+      groups.set(key, { label, models: [model] });
+    }
+  });
+  return [...groups.values()];
+}
+
+function providerLabel(model: AgentModelOption): string {
+  return model.providerName?.trim() || model.providerId?.trim() || "Other";
+}
+
+function createModelGroups(
+  models: readonly AgentModelOption[],
+  props: PiModelPickerProps,
+  providerLabelPlacement: ProviderLabelPlacement,
+): HTMLElement {
+  const list = document.createElement("div");
+  list.className = "pi-model-picker__models";
+
+  groupModels(models).forEach((group) => {
+    const groupElement = document.createElement("section");
+    groupElement.className = "pi-model-picker__provider";
+    groupElement.setAttribute("role", "group");
+    groupElement.setAttribute("aria-label", group.label);
+
+    if (providerLabelPlacement === "group") {
+      const heading = document.createElement("div");
+      heading.className = "pi-model-picker__provider-label";
+      heading.textContent = group.label;
+      groupElement.append(heading);
+    }
+
+    group.models.forEach((model) => {
+      const item = props.createModelItem(model);
+      item.classList.add("pi-model-picker__item");
+      const subtitle = isFlowixCloudModelOption(model) ? model.subtitle?.trim() : undefined;
+      if (subtitle) item.title = subtitle;
+      const checkmark = item.querySelector(".agent-thread-card__copy-icon");
+      if (providerLabelPlacement === "item") {
+        const providerName = document.createElement("span");
+        providerName.className = "pi-model-picker__provider-name";
+        providerName.textContent = group.label;
+        providerName.title = group.label;
+        item.insertBefore(providerName, checkmark);
+      }
+      if (isFlowixCloudModelOption(model) && model.creditMultiplier != null) {
+        const multiplier = document.createElement("span");
+        multiplier.className = "pi-model-picker__multiplier";
+        multiplier.textContent = `${model.creditMultiplier.toFixed(2)}x`;
+        multiplier.setAttribute(
+          "aria-label",
+          `credit multiplier ${model.creditMultiplier.toFixed(2)}`,
+        );
+        item.insertBefore(multiplier, checkmark);
+      }
+      if (!checkmark) {
+        const checkmarkPlaceholder = document.createElement("span");
+        checkmarkPlaceholder.className = "pi-model-picker__checkmark-placeholder";
+        checkmarkPlaceholder.setAttribute("aria-hidden", "true");
+        item.append(checkmarkPlaceholder);
+      }
+      const providerIcon = item.querySelector(".agent-thread-card__model-provider-icon");
+      if (providerIcon) {
+        providerIcon.classList.add("pi-model-picker__provider-icon");
+        item.prepend(providerIcon);
+      }
+      item.removeAttribute("role");
+      item.removeAttribute("aria-checked");
+      item.setAttribute(
+        "aria-pressed",
+        model.id === props.selectedModelId
+          && (model.providerId ?? "") === (props.selectedProviderId ?? "")
+          ? "true"
+          : "false",
+      );
+      groupElement.append(item);
+    });
+    list.append(groupElement);
+  });
+  return list;
+}
+
+export function createPiModelPicker(props: PiModelPickerProps): HTMLElement {
+  const root = document.createElement("div");
+  root.className = "pi-model-picker";
+
+  if (props.models.length === 0) {
+    const empty = document.createElement("div");
+    empty.className = "pi-model-picker__empty";
+    empty.textContent = props.emptyLabel;
+    root.append(empty);
+    return root;
+  }
+
+  const memberModels = props.models.filter(isFlowixCloudModelOption);
+  const mineModels = props.models.filter((model) => !isFlowixCloudModelOption(model));
+  if (!props.showMemberTab || memberModels.length === 0) {
+    const panel = document.createElement("div");
+    panel.className = "pi-model-picker__panel";
+    panel.append(createModelGroups(props.models, props, "item"));
+    root.append(panel);
+    return root;
+  }
+
+  const tabSetId = `pi-model-picker-${++nextTabSetId}`;
+  const memberTabId = `${tabSetId}-member-tab`;
+  const mineTabId = `${tabSetId}-mine-tab`;
+  const panelId = `${tabSetId}-panel`;
+  const tabList = document.createElement("div");
+  tabList.className = "pi-model-picker__tabs";
+  tabList.setAttribute("role", "tablist");
+  tabList.setAttribute("aria-label", props.modelLabel);
+
+  const memberTab = document.createElement("button");
+  memberTab.type = "button";
+  memberTab.id = memberTabId;
+  memberTab.className = "pi-model-picker__tab";
+  memberTab.setAttribute("role", "tab");
+  memberTab.setAttribute("aria-controls", panelId);
+  memberTab.textContent = props.memberLabel;
+
+  const mineTab = document.createElement("button");
+  mineTab.type = "button";
+  mineTab.id = mineTabId;
+  mineTab.className = "pi-model-picker__tab";
+  mineTab.setAttribute("role", "tab");
+  mineTab.setAttribute("aria-controls", panelId);
+  mineTab.textContent = props.mineLabel;
+  tabList.append(memberTab, mineTab);
+
+  const panel = document.createElement("div");
+  panel.id = panelId;
+  panel.className = "pi-model-picker__panel";
+  panel.setAttribute("role", "tabpanel");
+
+  const selectedModel = props.models.find((model) =>
+    model.id === props.selectedModelId
+    && (model.providerId ?? "") === (props.selectedProviderId ?? ""),
+  );
+  const selectedModelIsCloud = selectedModel
+    ? isFlowixCloudModelOption(selectedModel)
+    : props.selectedProviderId?.trim().toLocaleLowerCase().startsWith("flowix-cloud") === true;
+  let activeCategory: PiModelCategory = selectedModelIsCloud ? "member" : "mine";
+
+  const selectCategory = (category: PiModelCategory, focusTab = false) => {
+    activeCategory = category;
+    const memberSelected = category === "member";
+    memberTab.setAttribute("aria-selected", String(memberSelected));
+    mineTab.setAttribute("aria-selected", String(!memberSelected));
+    memberTab.tabIndex = memberSelected ? 0 : -1;
+    mineTab.tabIndex = memberSelected ? -1 : 0;
+    memberTab.classList.toggle("pi-model-picker__tab--active", memberSelected);
+    mineTab.classList.toggle("pi-model-picker__tab--active", !memberSelected);
+    panel.setAttribute("aria-labelledby", memberSelected ? memberTabId : mineTabId);
+    panel.replaceChildren();
+
+    const categoryModels = memberSelected ? memberModels : mineModels;
+    if (categoryModels.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "pi-model-picker__empty";
+      empty.textContent = props.personalEmptyLabel;
+      panel.append(empty);
+    } else {
+      panel.append(createModelGroups(
+        categoryModels,
+        props,
+        memberSelected ? "none" : "item",
+      ));
+    }
+    if (focusTab) (memberSelected ? memberTab : mineTab).focus();
+  };
+
+  const handleTabKeyDown = (event: KeyboardEvent) => {
+    let next: PiModelCategory | undefined;
+    if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+      next = activeCategory === "member" ? "mine" : "member";
+    } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+      next = activeCategory === "member" ? "mine" : "member";
+    } else if (event.key === "Home") {
+      next = "member";
+    } else if (event.key === "End") {
+      next = "mine";
+    }
+    if (!next) return;
+    event.preventDefault();
+    selectCategory(next, true);
+  };
+
+  memberTab.addEventListener("click", () => selectCategory("member"));
+  mineTab.addEventListener("click", () => selectCategory("mine"));
+  memberTab.addEventListener("keydown", handleTabKeyDown);
+  mineTab.addEventListener("keydown", handleTabKeyDown);
+  root.append(tabList, panel);
+  selectCategory(activeCategory);
+  return root;
+}
diff --git a/app/flowix-web/features/agent/thread-card/settings/notebook-agent-settings-dialog.tsx b/app/flowix-web/features/agent/thread-card/settings/notebook-agent-settings-dialog.tsx
index 1442eb86e..69487e10c 100644
--- a/app/flowix-web/features/agent/thread-card/settings/notebook-agent-settings-dialog.tsx
+++ b/app/flowix-web/features/agent/thread-card/settings/notebook-agent-settings-dialog.tsx
@@ -23,17 +23,21 @@ import { agent, type NotebookAgentFile, type NotebookAgentWorkspace, type Notebo
 import { Button } from "@shared/ui/button";
 import { cn } from "@/lib/utils";
 import { displayNameForComposerSkill } from "@features/agent/thread-card/composer/composer-skill-token";
-import { parseCodexSkillCatalog, type CodexSkillCatalogItem } from "@features/agent/services/codex-slash-command-service";
+import type { CodexSkillCatalogItem } from "@features/agent/services/codex-slash-command-service";
+import { invalidateNotebookSkills, loadNotebookSkillCatalog } from "@features/agent/services/agent-catalog-service";
+import { useAgentDataStore } from "@features/agent/store/agent-data-store";
+import { useAgentWorkspaceStore } from "@features/agent/store/agent-workspace-store";
+import { useNoteStore } from "@features/memo/store/note-store";
 import { isValidPiSkillCommandName } from "@features/agent/services/pi-skill-name";
 
 type Tab = "mcp" | "skills" | "agents" | "plugins" | "other" | "memory";
 type FileKind = "skill" | "agent";
-type AgentResourceKey = "codex" | "deepseek-harness" | "general";
+type AgentResourceKey = "codex" | "dsh" | "general";
 type EditorState =
   | { kind: "mcp"; id: string | null }
   | { kind: "file"; fileKind: FileKind; id: string | null };
 
-const AGENT_RESOURCE_KEYS: readonly AgentResourceKey[] = ["codex", "deepseek-harness", "general"];
+const AGENT_RESOURCE_KEYS: readonly AgentResourceKey[] = ["codex", "dsh", "general"];
 const CODEX_RESOURCE_KEYS: readonly AgentResourceKey[] = ["codex"];
 
 const EMPTY_WORKSPACE: NotebookAgentWorkspace = {
@@ -239,7 +243,7 @@ function McpEditor({
         <Toggle checked={form.enabled} onChange={(enabled) => onChange({ enabled })} label="启用此服务" />
         <div className="flex items-center gap-2">
           <Button type="button" variant="ghost" onClick={onCancel}>取消</Button>
-          <Button type="button" disabled={saving} onClick={onSave}>{saving ? <Loader2 className="animate-spin" /> : <Save />}保存服务</Button>
+          <Button type="button" disabled={saving} onClick={onSave}>{saving ? <Loader2 className="flowix-spin" /> : <Save />}保存服务</Button>
         </div>
       </div>
       {error && <InlineError message={error} />}
@@ -417,7 +421,7 @@ function AgentTabs({ active, onChange, ariaLabel, keys = AGENT_RESOURCE_KEYS }:
                 : "text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]",
             )}
           >
-            <span className="whitespace-nowrap">{agentKey === "codex" ? "Codex" : agentKey === "deepseek-harness" ? "DeepSeek Harness" : "通用"}</span>
+            <span className="whitespace-nowrap">{agentKey === "codex" ? "Codex" : agentKey === "dsh" ? "DeepSeek Harness" : "通用"}</span>
           </button>
         );
       })}
@@ -575,40 +579,71 @@ function CodexSkillGroup({ title, items }: { title: string; items: readonly Code
   );
 }
 
+const EMPTY_CODEX_SKILLS: readonly CodexSkillCatalogItem[] = [];
+
+function normalizeNotebookPath(path: string): string {
+  return path.trim().replace(/[\\/]+$/, "").toLowerCase();
+}
+
+function getNotebookSkillScopeId(notebookPath: string): string {
+  const normalizedPath = normalizeNotebookPath(notebookPath);
+  const notebookId = useNoteStore.getState().notebooks.find(
+    (notebook) => normalizeNotebookPath(notebook.path) === normalizedPath,
+  )?.id;
+  const workspaceNotebookId = Object.values(useAgentWorkspaceStore.getState().workspace.byNotebookId).find(
+    (notebook) => normalizeNotebookPath(notebook.notebook.path) === normalizedPath,
+  )?.notebook.id;
+  return notebookId ?? workspaceNotebookId ?? normalizedPath;
+}
+
 function CodexSkillsList({ notebookPath }: { notebookPath: string }) {
+  const normalizedPath = normalizeNotebookPath(notebookPath);
+  const notebookId = useNoteStore((state) =>
+    state.notebooks.find((notebook) => normalizeNotebookPath(notebook.path) === normalizedPath)?.id ?? null,
+  );
+  const workspaceNotebookId = useAgentWorkspaceStore((state) =>
+    Object.values(state.workspace.byNotebookId).find(
+      (notebook) => normalizeNotebookPath(notebook.notebook.path) === normalizedPath,
+    )?.notebook.id ?? null,
+  );
+  const scopeId = notebookId ?? workspaceNotebookId ?? normalizedPath;
+  const catalog = useAgentDataStore((state) =>
+    scopeId ? state.agents.codex.catalog.skillsByNotebookId[scopeId] : undefined,
+  );
+  const skills = (catalog?.items ?? EMPTY_CODEX_SKILLS) as readonly CodexSkillCatalogItem[];
   const [status, setStatus] = useState<"loading" | "ready" | "error">("loading");
-  const [skills, setSkills] = useState<readonly CodexSkillCatalogItem[]>([]);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
     let active = true;
-    setStatus("loading");
-    setSkills([]);
+    const cached = useAgentDataStore.getState().agents.codex.catalog.skillsByNotebookId[scopeId];
+    setStatus(cached ? "ready" : "loading");
     setError(null);
 
-    void (async () => {
-      try {
-        const capabilities = await agent.getCodexProjectCapabilities(notebookPath);
-        if (!capabilities.skills.ok) {
-          throw new Error(capabilities.skills.error ?? "Codex Skill 加载失败");
-        }
+    void loadNotebookSkillCatalog("codex", scopeId, notebookPath)
+      .then(() => {
         if (!active) return;
-        setSkills(parseCodexSkillCatalog(capabilities.skills.value));
         setStatus("ready");
-      } catch (cause) {
+      })
+      .catch((cause) => {
         if (!active) return;
+        const latest = useAgentDataStore.getState().agents.codex.catalog.skillsByNotebookId[scopeId];
+        if (latest) {
+          setStatus("ready");
+          setError(cause instanceof Error ? cause.message : String(cause));
+          return;
+        }
         setError(cause instanceof Error ? cause.message : String(cause));
         setStatus("error");
-      }
-    })();
+      });
 
     return () => { active = false; };
-  }, [notebookPath]);
+  }, [notebookPath, scopeId]);
 
-  if (status === "loading") {
+  if (status === "loading" && !catalog) {
     return <div className="flex min-h-[280px] items-center justify-center text-sm text-[var(--muted-foreground)]" aria-live="polite">加载中…</div>;
   }
-  if (status === "error") {
+  if (status === "error" && !catalog) {
     return <div className="space-y-3"><InlineError message={error ?? "Codex Skill 加载失败"} /><div className="py-5 text-center text-sm text-[var(--muted-foreground)]">暂时无法读取 Codex Skill 列表</div></div>;
   }
   if (!skills.length) {
@@ -1077,6 +1112,15 @@ function NotebookAgentSettingsDialog({ notebookPath, onClose }: { notebookPath:
       setWorkspace(next);
       setOriginal(cloneWorkspace(next));
       closeEditor();
+      const skillScopeId = getNotebookSkillScopeId(notebookPath);
+      if (skillScopeId) {
+        for (const agentType of ["codex", "pi"] as const) {
+          invalidateNotebookSkills(agentType, skillScopeId);
+          void loadNotebookSkillCatalog(agentType, skillScopeId, notebookPath, { force: true }).catch((cause) => {
+            console.warn(`Failed to refresh ${agentType} skills after saving notebook Agent settings`, cause);
+          });
+        }
+      }
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : String(cause));
     } finally {
@@ -1145,7 +1189,7 @@ function NotebookAgentSettingsDialog({ notebookPath, onClose }: { notebookPath:
               {tab === "mcp" && <>
                 <SectionHeader title="MCP 服务" description="为这个笔记本里的 Agent 添加可调用的外部工具与数据源。" action={mcpAgent === "general" ? <Button variant="default" className="gap-[3px] px-3" onClick={() => openMcp(null)} disabled={!!editor}><Plus />添加</Button> : null} />
                 <AgentTabs active={mcpAgent} ariaLabel="MCP Agent" onChange={(agentKey) => { setMcpAgent(agentKey); closeEditor(); }} />
-                {mcpAgent === "codex" ? <CodexMcpList notebookPath={notebookPath} /> : mcpAgent === "deepseek-harness" ? <DeepSeekHarnessMcpList /> : <>
+                {mcpAgent === "codex" ? <CodexMcpList notebookPath={notebookPath} /> : mcpAgent === "dsh" ? <DeepSeekHarnessMcpList /> : <>
                   {editor?.kind === "mcp" && mcpForm && <McpEditor form={mcpForm} onChange={(patch) => setMcpForm((current) => current ? { ...current, ...patch } : current)} onCancel={closeEditor} onSave={saveMcpDraft} error={formError} saving={false} />}
                   <McpList workspace={workspace ?? EMPTY_WORKSPACE} onAdd={() => openMcp(null)} onEdit={openMcp} onDelete={deleteMcp} onToggle={toggleMcp} />
                 </>}
@@ -1153,7 +1197,7 @@ function NotebookAgentSettingsDialog({ notebookPath, onClose }: { notebookPath:
               {tab === "skills" && <>
                 <SectionHeader title="Skills" description="把可复用的工作流程保存为 Markdown Skill，之后可被不同 Agent 使用。" action={skillAgent === "general" ? <Button variant="default" className="gap-[3px] px-3" onClick={() => openFile("skill", null)} disabled={!!editor}><Plus />创建</Button> : null} />
                 <AgentTabs active={skillAgent} ariaLabel="Skill Agent" onChange={(agentKey) => { setSkillAgent(agentKey); closeEditor(); }} />
-                {skillAgent === "codex" ? <CodexSkillsList notebookPath={notebookPath} /> : skillAgent === "deepseek-harness" ? <DeepSeekHarnessSkillsList /> : <div className="space-y-3">
+                {skillAgent === "codex" ? <CodexSkillsList notebookPath={notebookPath} /> : skillAgent === "dsh" ? <DeepSeekHarnessSkillsList /> : <div className="space-y-3">
                   {editor?.kind === "file" && editor.fileKind === "skill" && fileForm && <FileEditor kind="skill" form={fileForm} onChange={(patch) => setFileForm((current) => current ? { ...current, ...patch } : current)} onCancel={closeEditor} onSave={saveFileDraft} error={formError} />}
                   <FileList kind="skill" items={(workspace ?? EMPTY_WORKSPACE).skills} onAdd={() => openFile("skill", null)} onEdit={(id) => openFile("skill", id)} onDelete={(id) => deleteFile("skill", id)} onToggle={(id, enabled) => toggleFile("skill", id, enabled)} />
                 </div>}
@@ -1161,7 +1205,7 @@ function NotebookAgentSettingsDialog({ notebookPath, onClose }: { notebookPath:
               {tab === "agents" && <>
                 <SectionHeader title="子 Agent" description="创建专门角色，让主 Agent 可以把任务交给更合适的处理者。" action={childAgent === "general" ? <Button variant="default" className="gap-[3px] px-3" onClick={() => openFile("agent", null)} disabled={!!editor}><Plus />创建</Button> : null} />
                 <AgentTabs active={childAgent} ariaLabel="子 Agent" onChange={(agentKey) => { setChildAgent(agentKey); closeEditor(); }} />
-                {childAgent === "codex" ? <CodexAgentsList notebookPath={notebookPath} /> : childAgent === "deepseek-harness" ? <DeepSeekHarnessAgentsList /> : <div className="space-y-3">
+                {childAgent === "codex" ? <CodexAgentsList notebookPath={notebookPath} /> : childAgent === "dsh" ? <DeepSeekHarnessAgentsList /> : <div className="space-y-3">
                   {editor?.kind === "file" && editor.fileKind === "agent" && fileForm && <FileEditor kind="agent" form={fileForm} onChange={(patch) => setFileForm((current) => current ? { ...current, ...patch } : current)} onCancel={closeEditor} onSave={saveFileDraft} error={formError} />}
                   <FileList kind="agent" items={(workspace ?? EMPTY_WORKSPACE).agents} onAdd={() => openFile("agent", null)} onEdit={(id) => openFile("agent", id)} onDelete={(id) => deleteFile("agent", id)} onToggle={(id, enabled) => toggleFile("agent", id, enabled)} />
                 </div>}
@@ -1187,7 +1231,7 @@ function NotebookAgentSettingsDialog({ notebookPath, onClose }: { notebookPath:
 
         <footer className="flex shrink-0 items-center justify-between gap-3 border-t border-[var(--divider)] bg-[color-mix(in_oklch,var(--background)_92%,var(--card))] px-5 py-3 sm:px-6">
           <div className="min-w-0 text-xs text-[var(--muted-foreground)]">{dirty ? <span className="text-[var(--primary)]">有未保存更改</span> : <span className="inline-flex items-center gap-1.5"><Check className="h-3.5 w-3.5 text-[var(--primary)]" /></span>}</div>
-          <div className="flex items-center gap-2"><Button type="button" variant="ghost" onClick={requestClose}>取消</Button><Button type="button" disabled={!dirty || saving} onClick={() => void saveWorkspace()}>{saving ? <Loader2 className="animate-spin" /> : null}保存</Button></div>
+          <div className="flex items-center gap-2"><Button type="button" variant="ghost" onClick={requestClose}>取消</Button><Button type="button" disabled={!dirty || saving} onClick={() => void saveWorkspace()}>{saving ? <Loader2 className="flowix-spin" /> : null}保存</Button></div>
         </footer>
       </div>
     </div>
diff --git a/app/flowix-web/features/agent/thread-card/view/agent-thread-card-dom-factory.ts b/app/flowix-web/features/agent/thread-card/view/agent-thread-card-dom-factory.ts
index 52a7afb1d..e3019a0ab 100644
--- a/app/flowix-web/features/agent/thread-card/view/agent-thread-card-dom-factory.ts
+++ b/app/flowix-web/features/agent/thread-card/view/agent-thread-card-dom-factory.ts
@@ -44,7 +44,7 @@ export interface AgentThreadCardDomParts {
   loadingIndicator: HTMLDivElement;
   queuedMessages: HTMLDivElement;
   composer: HTMLElement;
-  composerImages: HTMLDivElement;
+  inputRow: HTMLDivElement;
   composerActions: HTMLDivElement;
   composerRoleIcon: HTMLButtonElement;
   composerAddPopover: HTMLDivElement;
@@ -58,7 +58,7 @@ export function createAgentThreadCardDom(
   options: AgentThreadCardDomFactoryOptions,
 ): AgentThreadCardDomParts {
   const dom = document.createElement("section");
-  dom.className = "agent-thread-card";
+  dom.className = "agent-thread-card agent-conversation-surface";
   dom.contentEditable = "false";
   dom.tabIndex = -1;
   dom.dataset.agentThreadCard = "true";
@@ -166,7 +166,9 @@ export function createAgentThreadCardDom(
   body.dataset.noContextMenuScroll = "";
   body.addEventListener("click", options.onBodyClick);
   body.addEventListener("scroll", options.onBodyScroll, { passive: true });
-  body.addEventListener("wheel", options.onBodyWheel, { passive: true });
+  // Inline cards may route wheel input to the document until the message
+  // viewport is explicitly activated, so this listener must be cancellable.
+  body.addEventListener("wheel", options.onBodyWheel, { passive: false });
   const disposeBodyScrollbar = () => bodyScrollbar?.destroy();
 
   const loadingIndicator = document.createElement("div");
@@ -203,7 +205,7 @@ export function createAgentThreadCardDom(
   });
   const {
     composer,
-    composerImages,
+    inputRow,
     composerActions,
     composerRoleIcon,
     composerAddPopover,
@@ -263,7 +265,7 @@ export function createAgentThreadCardDom(
     loadingIndicator,
     queuedMessages,
     composer,
-    composerImages,
+    inputRow,
     composerActions,
     composerRoleIcon,
     composerAddPopover,
diff --git a/app/flowix-web/features/agent/tool-display.test.ts b/app/flowix-web/features/agent/tool-display.test.ts
index d5b2f67c4..b940fe674 100644
--- a/app/flowix-web/features/agent/tool-display.test.ts
+++ b/app/flowix-web/features/agent/tool-display.test.ts
@@ -157,7 +157,7 @@ describe("Codex protocol tool summaries", () => {
 
 describe("DeepSeek Harness (DSH) tool displays", () => {
   const dsh = (toolName: string, input: unknown) =>
-    createAgentToolDisplay({ agentType: "deepseek-harness", toolName, input });
+    createAgentToolDisplay({ agentType: "dsh", toolName, input });
 
   it.each([
     ["read", { file_path: "/tmp/a/main.rs" }, "main.rs", "file"],
@@ -407,7 +407,7 @@ describe("parseAgentCommandInput", () => {
   it("normalizes Flowix shell command tools to command display", () => {
     expect(
       createAgentToolDisplay({
-        agentType: "deepseek-harness",
+        agentType: "dsh",
         toolName: "shell",
         input: { command: "npm run build" },
       }),
@@ -420,7 +420,7 @@ describe("parseAgentCommandInput", () => {
   it("normalizes Claude Code Bash command tools to command display", () => {
     expect(
       createAgentToolDisplay({
-        agentType: "claude",
+        agentType: "claudecode",
         toolName: "Bash",
         input: { command: "npm test", description: "run tests" },
       }),
diff --git a/app/flowix-web/features/agent/use-cases/new-conversation.ts b/app/flowix-web/features/agent/use-cases/new-conversation.ts
new file mode 100644
index 000000000..19ef14503
--- /dev/null
+++ b/app/flowix-web/features/agent/use-cases/new-conversation.ts
@@ -0,0 +1,54 @@
+import { buildInitialInstanceRuntimeConfig } from '@features/agent/store/initial-runtime-config';
+import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
+import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { useNoteStore } from '@features/memo/store/note-store';
+import { isAgentTypeEnabled } from '@features/preferences/public/runtime-api';
+import {
+  getNewConversationAgentSelection,
+  type NewConversationAgentSelection,
+} from '@features/agent/runtime/new-conversation-agent-selection';
+import type { AgentTypeKey } from '@/types/agent';
+
+/** Refresh status in the background and decide from the latest known snapshot. */
+export function requestNewConversationAgentSelection(): NewConversationAgentSelection {
+  const runtime = useAgentRuntimeStore.getState();
+  void runtime.refreshIfStale();
+  return getNewConversationAgentSelection(
+    runtime.statusByType,
+    runtime.isChecking,
+    isAgentTypeEnabled,
+  );
+}
+
+function createAgentConversationInstance(typeKey: AgentTypeKey, notebookId: string | null) {
+  return useAgentSessionStore.getState().createInstance({
+    agentType: typeKey,
+    title: '',
+    threadId: null,
+    source: { kind: 'dedicated', notebookId, documentPath: null },
+    runtimeConfig: buildInitialInstanceRuntimeConfig(typeKey),
+  });
+}
+
+function openAgentConversation(instanceId: string): void {
+  void openWorkspaceSurface({
+    target: { kind: 'agent-conversation', instanceId, blankIfMissing: true },
+  });
+}
+
+/** Create a conversation instance for the browser column's host-specific navigation. */
+export function createBrowserColumnAgentConversation(typeKey: AgentTypeKey, notebookId: string): string {
+  return createAgentConversationInstance(typeKey, notebookId).instanceId;
+}
+
+/** Create and open a blank conversation scoped to a notebook. */
+export function createAndOpenAgentConversation(typeKey: AgentTypeKey, notebookId: string | null): void {
+  const instance = createAgentConversationInstance(typeKey, notebookId);
+  openAgentConversation(instance.instanceId);
+}
+
+export function createAndOpenPiConversation(): void {
+  const notebookId = useNoteStore.getState().selectedNotebook?.id ?? null;
+  createAndOpenAgentConversation('pi', notebookId);
+}
diff --git a/app/flowix-web/features/collection/dataset-filter-location.test.ts b/app/flowix-web/features/collection/dataset-filter-location.test.ts
new file mode 100644
index 000000000..00da8c121
--- /dev/null
+++ b/app/flowix-web/features/collection/dataset-filter-location.test.ts
@@ -0,0 +1,32 @@
+import { expect, it } from 'vitest';
+import { resolveDatasetFilterForLocation } from './dataset-filter-location';
+import { matchesMediaCollectionFilter, createMediaLibrary, mediaCollectionFilterForSave } from '../media-library/model';
+
+it('follows a moved folder index without changing conditions or the stored document', () => {
+  const filter = { path: 'Old', match: 'any', conditions: [{ field: 'file_name', op: 'contains', value: 'photo' }] };
+  const effective = resolveDatasetFilterForLocation(filter, 'folder', '/book/New/.index.yaml', '/book');
+  expect(matchesMediaCollectionFilter('New/photo.png', 'image', effective)).toBe(true);
+  expect(matchesMediaCollectionFilter('Old/photo.png', 'image', effective)).toBe(false);
+  expect(matchesMediaCollectionFilter('New/other.png', 'image', effective)).toBe(false);
+  expect(filter.path).toBe('Old');
+  expect(resolveDatasetFilterForLocation(filter, 'standalone', '/book/New/file.index.yaml', '/book')).toBe(filter);
+});
+
+it('resolves legacy path rules and notebook root locations', () => {
+  const filter = { all: [{ field: 'path', op: 'contains', value: 'Old' }], any: [] };
+  const effective = resolveDatasetFilterForLocation(filter, 'folder', '/book/New/.index.yaml', '/book');
+  expect(matchesMediaCollectionFilter('New/photo.png', 'image', effective)).toBe(true);
+  expect(resolveDatasetFilterForLocation({ path: 'Old', match: 'all', conditions: [] }, 'folder', '/book/.index.yaml', '/book')?.path).toBe('');
+});
+
+it('checks the latest media filter before replacing it and synchronizes folder paths on save', () => {
+  const document = createMediaLibrary('Media');
+  const before = document.dataset.filter;
+  expect(mediaCollectionFilterForSave(document, { file_name_contains: 'photo' }, '/book/media.index.yaml', '/book')).toMatchObject({ path: null });
+  document.dataset.filter = { all: [], any: [{ field: 'file_name', op: 'contains', value: 'external' }] };
+  expect(() => mediaCollectionFilterForSave(document, { file_name_contains: 'photo' }, '/book/media.index.yaml', '/book')).toThrow('已取消保存');
+  expect(document.dataset.filter.any).toHaveLength(1);
+  document.dataset.filter = before;
+  document.collection.placement = 'folder';
+  expect(mediaCollectionFilterForSave(document, {}, '/book/New/.index.yaml', '/book')).toEqual({ path: 'New', match: 'all', conditions: [] });
+});
diff --git a/app/flowix-web/features/collection/dataset-filter-location.ts b/app/flowix-web/features/collection/dataset-filter-location.ts
new file mode 100644
index 000000000..1a9be41f5
--- /dev/null
+++ b/app/flowix-web/features/collection/dataset-filter-location.ts
@@ -0,0 +1,24 @@
+import { notebookRelativeDirectoryPath, parentDirectoryPath } from '@/lib/path';
+import type { CollectionPlacement } from './model';
+
+/** Folder paths follow the current index location, including filesystem moves. */
+export function resolveDatasetFilterForLocation(
+  filter: Record<string, unknown> | null,
+  placement: CollectionPlacement,
+  filePath: string | null,
+  notebookPath: string | null,
+): Record<string, unknown> | null {
+  if (!filter || placement !== 'folder' || !filePath || !notebookPath) return filter;
+  const path = notebookRelativeDirectoryPath(notebookPath, parentDirectoryPath(filePath, notebookPath));
+  if (path === null) return filter;
+  if (Array.isArray(filter.conditions)) return { ...filter, path };
+  const relocate = (rule: Record<string, unknown>): Record<string, unknown> => {
+    if (rule.field === 'path') return { ...rule, value: path };
+    return {
+      ...rule,
+      ...(Array.isArray(rule.all) ? { all: rule.all.map(relocate) } : {}),
+      ...(Array.isArray(rule.any) ? { any: rule.any.map(relocate) } : {}),
+    };
+  };
+  return relocate(filter);
+}
diff --git a/app/flowix-web/features/collection/folder-collection.ts b/app/flowix-web/features/collection/folder-collection.ts
index 11c5a76bb..1959eb962 100644
--- a/app/flowix-web/features/collection/folder-collection.ts
+++ b/app/flowix-web/features/collection/folder-collection.ts
@@ -1,20 +1,25 @@
 import { createTableDocument, serializeTableDocument } from '@features/multidimensional-table/public/create-api';
 import { createMediaLibrary, serializeMediaLibrary } from '@features/media-library/model';
-import { parseCollectionDocumentV2, serializeCollectionDocumentV2, type CollectionType } from './model';
+import { collectionDisplayName, parseCollectionDocumentV2, serializeCollectionDocumentV2, type CollectionType } from './model';
 import { externalDocuments } from '@platform/tauri/client';
-import { canonicalPath } from '@/lib/path';
+import { canonicalPath, notebookRelativeDirectoryPath } from '@/lib/path';
 
-export function createFolderCollectionContent(kind: 'notes' | 'media', folderName: string): string {
+export function createFolderCollectionContent(kind: 'notes' | 'media', folderName: string, folderPath: string | null = null): string {
   if (kind === 'notes') {
     const document = createTableDocument('table', folderName, 'folder');
     document.dataset.source = { scope: 'containing_folder', depth: 'descendants' };
-    document.dataset.filter = { all: [{ field: 'kind', op: 'eq', value: 'note' }], any: [] };
+    document.dataset.filter = {
+      path: folderPath,
+      match: 'all',
+      conditions: [{ field: 'kind', op: 'eq', value: 'note' }],
+    };
     return serializeTableDocument(document);
   }
 
   const document = createMediaLibrary(folderName);
   document.collection.placement = 'folder';
   document.dataset.source = { scope: 'containing_folder', depth: 'descendants' };
+  document.dataset.filter = { path: folderPath, match: 'all', conditions: [] };
   return serializeMediaLibrary(document);
 }
 
@@ -25,11 +30,13 @@ export async function switchFolderCollectionType(filePath: string, notebookPath:
     throw new Error('仅文件夹集合支持切换视图类型');
   }
   if (current.collection.type === type) return current.collection.id;
-  const template = parseCollectionDocumentV2(createFolderCollectionContent(type === 'table' ? 'notes' : 'media', current.collection.name));
+  const folderPath = canonicalPath(filePath).replace(/[\\/][^\\/]*$/, '');
+  const relativeFolder = notebookRelativeDirectoryPath(notebookPath, folderPath) ?? '';
+  const folderName = collectionDisplayName(filePath, 'folder');
+  const template = parseCollectionDocumentV2(createFolderCollectionContent(type === 'table' ? 'notes' : 'media', folderName, relativeFolder));
   const next = {
     ...template.collection,
     id: current.collection.id,
-    name: current.collection.name,
     revision: current.collection.revision + 1,
     created_at: current.collection.created_at,
     updated_at: new Date().toISOString(),
diff --git a/app/flowix-web/features/collection/model.test.ts b/app/flowix-web/features/collection/model.test.ts
index 878c6cc7d..a47e4c922 100644
--- a/app/flowix-web/features/collection/model.test.ts
+++ b/app/flowix-web/features/collection/model.test.ts
@@ -14,7 +14,7 @@ describe('collection file identity and properties', () => {
     expect(tableFile.payload.dataset).not.toHaveProperty('id');
     expect(parseTableDocument(serializeTableDocument(table))).toEqual(table);
     const library = createMediaLibrary('照片');
-    library.dataset.records.include.push(createMediaLibraryRecord('attachments/photo.png'));
+    library.dataset.records.include.push(createMediaLibraryRecord('notebook-1', 'attachments/photo.png'));
     library.collection.properties = table.collection.properties;
     expect(parseMediaLibrary(serializeMediaLibrary(library))).toEqual(library);
     expect(library.collection.id).toMatch(/^col_[0-9a-f]{32}$/);
diff --git a/app/flowix-web/features/collection/model.ts b/app/flowix-web/features/collection/model.ts
index 614fd5b14..b733aaa83 100644
--- a/app/flowix-web/features/collection/model.ts
+++ b/app/flowix-web/features/collection/model.ts
@@ -19,7 +19,8 @@ export interface CollectionMetadata {
   id: string;
   type: CollectionType;
   placement: CollectionPlacement;
-  name: string;
+  /** Legacy name retained when reading old files; the path is authoritative. */
+  name?: string;
   revision: number;
   created_at: string;
   updated_at: string;
@@ -46,11 +47,16 @@ export function createUuidV7(): string {
 export const createCollectionId = () => `col_${createUuidV7()}`;
 export function createCollectionMetadata(
   type: CollectionType,
-  name: string,
+  _name: string,
   placement: CollectionPlacement = 'standalone',
 ): CollectionMetadata {
   const now = new Date().toISOString();
-  return { id: createCollectionId(), type, placement, name: name.trim(), revision: 0, created_at: now, updated_at: now, properties: {} };
+  return { id: createCollectionId(), type, placement, revision: 0, created_at: now, updated_at: now, properties: {} };
+}
+export function collectionDisplayName(filePath: string, placement: CollectionPlacement): string {
+  const parts = filePath.split(/[\\/]/).filter(Boolean);
+  if (placement === 'folder') return parts[parts.length - 2] ?? '';
+  return (parts[parts.length - 1] ?? '').replace(/\.(?:index\.ya?ml|(?:table|lib)\.ya?ml)$/i, '');
 }
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -91,6 +97,19 @@ function ruleFilterMatchesCollectionType(filter: unknown, type: CollectionType):
     return false;
   });
 }
+function datasetFilterMatchesCollectionType(filter: unknown, type: CollectionType): boolean {
+  if (!isRecord(filter) || !hasOnlyKeys(filter, ['path', 'match', 'conditions'])) {
+    return ruleFilterMatchesCollectionType(filter, type);
+  }
+  if (!(filter.path === null || filter.path === '' || isNotebookRelativePath(filter.path))
+    || (filter.match !== 'all' && filter.match !== 'any')
+    || !Array.isArray(filter.conditions)
+    || filter.conditions.some((condition) => !isRecord(condition) || 'all' in condition || 'any' in condition)) return false;
+  if (type === 'media_library' && filter.match !== 'all') return false;
+  const legacyShape = { all: filter.conditions, any: [] };
+  if (!filter.conditions.every((condition) => isRecord(condition) && condition.field !== 'path')) return false;
+  return ruleFilterMatchesCollectionType(legacyShape, type);
+}
 export function hasOnlyKeys(value: object, keys: readonly string[]): boolean {
   return Object.keys(value).every((key) => keys.includes(key));
 }
@@ -116,7 +135,7 @@ export function validateCollectionMetadata(value: unknown, type?: CollectionType
     || typeof value.id !== 'string' || !/^col_[0-9a-f]{32}$/.test(value.id)
     || !['table', 'media_library'].includes(String(normalizedType)) || (type && normalizedType !== type)
     || (value.placement !== undefined && !['standalone', 'folder'].includes(String(value.placement)))
-    || typeof value.name !== 'string' || !value.name.trim() || value.name !== value.name.trim()
+    || (value.name !== undefined && (typeof value.name !== 'string' || !value.name.trim() || value.name !== value.name.trim()))
     || !Number.isSafeInteger(value.revision) || Number(value.revision) < 0
     || typeof value.created_at !== 'string' || !Number.isFinite(Date.parse(value.created_at))
     || typeof value.updated_at !== 'string' || !Number.isFinite(Date.parse(value.updated_at))
@@ -186,7 +205,7 @@ function validateV2Envelope(value: Record<string, unknown>): { collection: Colle
       || (collection.type === 'media_library' && (sort.field !== 'created_at' || sort.direction !== 'desc')))))) throw new Error('集合视图筛选、排序或布局无效');
   // A deleted remembered table view is recoverable; the table model selects the first view.
   if (collection.type !== 'table' && !viewItems.some((view) => isRecord(view) && view.id === views.default_id)) throw new Error('默认集合视图不存在');
-  if (value.payload.dataset.filter !== null && value.payload.dataset.filter !== undefined && !ruleFilterMatchesCollectionType(value.payload.dataset.filter, collection.type)) {
+  if (value.payload.dataset.filter !== null && value.payload.dataset.filter !== undefined && !datasetFilterMatchesCollectionType(value.payload.dataset.filter, collection.type)) {
     throw new Error('集合规则筛选格式无效');
   }
 
@@ -357,7 +376,6 @@ export function serializeCollectionDocumentV2(document: CollectionDocumentV2): s
     id: checked.id,
     type: checked.type === 'table' ? 'notes' : 'media',
     placement: checked.placement,
-    name: checked.name,
     revision: checked.revision,
     created_at: checked.created_at,
     updated_at: checked.updated_at,
diff --git a/app/flowix-web/features/collection/recovery.test.ts b/app/flowix-web/features/collection/recovery.test.ts
new file mode 100644
index 000000000..8a3173ea3
--- /dev/null
+++ b/app/flowix-web/features/collection/recovery.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, expect, it, vi } from 'vitest';
+import YAML from 'yaml';
+import { externalDocuments } from '@platform/tauri/client';
+import { createTableDocument, parseTableDocument, serializeTableDocument } from '@features/multidimensional-table/model';
+import { createMediaLibrary, parseMediaLibrary, serializeMediaLibrary } from '@features/media-library/model';
+import { createFolderCollectionContent } from './folder-collection';
+import { repairCollectionFile } from './recovery';
+
+vi.mock('@platform/tauri/client', () => ({
+  externalDocuments: { read: vi.fn(), write: vi.fn() },
+  notebooks: { getAll: vi.fn().mockResolvedValue([{ id: 'book', path: '/book' }]) },
+}));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(externalDocuments.write).mockImplementation(async ({ filePath, content }) => ({ status: 'saved', path: filePath, content }));
+});
+
+it.each([
+  ['notes', 'standalone'], ['notes', 'folder'], ['media', 'standalone'], ['media', 'folder'],
+] as const)('recovers %s content with invalid placement at a %s location', async (type, placement) => {
+  const validSource = placement === 'folder' ? createFolderCollectionContent(type, '项目', '11测试')
+    : type === 'notes' ? serializeTableDocument(createTableDocument('calendar', '项目', 'standalone'))
+      : serializeMediaLibrary(createMediaLibrary('项目'));
+  const wire = YAML.parse(validSource);
+  const record = {
+    id: 'rec_01a12e0b2ab97d089eeff757ebd4e643', updated_at: '2026-10-12T02:57:27.436Z',
+    ...(type === 'notes' ? { note_path: 'Welcome111.md' } : { relative_path: 'photo.png', resource_id: 'image-1' }),
+  };
+  wire.payload.dataset.records.include.push(record);
+  wire.collection.placement = 'standalone1';
+  const damaged = YAML.stringify(wire);
+  vi.mocked(externalDocuments.read).mockResolvedValue(damaged);
+  const path = `/book/11测试/${placement === 'folder' ? '.index.yaml' : '新建多维日历.index.yaml'}`;
+  const result = await repairCollectionFile(path, '/book');
+  const write = vi.mocked(externalDocuments.write).mock.calls[0][0];
+  const repaired = type === 'notes' ? parseTableDocument(write.content) : parseMediaLibrary(write.content);
+  expect(write).toMatchObject({ filePath: path, scopePath: '/book', expectedContent: damaged });
+  expect(result.placement).toBe(placement);
+  expect(repaired.collection.id).toBe(wire.collection.id);
+  expect(repaired.dataset.records.include).toEqual([type === 'notes' ? record : { ...record, resource_id: 'book::photo.png' }]);
+  expect(repaired.views).toEqual(wire.payload.views);
+  if (placement === 'folder') expect(repaired.dataset.source).toEqual({ scope: 'containing_folder', depth: 'descendants' });
+});
+
+it('falls back to a valid table when the file has no recoverable YAML or collection type', async () => {
+  vi.mocked(externalDocuments.read).mockResolvedValue('collection: [\ninvalid: {');
+  const result = await repairCollectionFile('/book/11测试/broken.index.yaml', '/book');
+  expect(result).toMatchObject({ collectionType: 'table', placement: 'standalone' });
+  const write = vi.mocked(externalDocuments.write).mock.calls[0][0];
+  expect(() => parseTableDocument(write.content)).not.toThrow();
+});
diff --git a/app/flowix-web/features/collection/recovery.ts b/app/flowix-web/features/collection/recovery.ts
new file mode 100644
index 000000000..6ddb6792e
--- /dev/null
+++ b/app/flowix-web/features/collection/recovery.ts
@@ -0,0 +1,288 @@
+import YAML from 'yaml';
+import { externalDocuments, notebooks } from '@platform/tauri/client';
+import { canonicalDirectoryPath, canonicalPath, notebookRelativeDirectoryPath } from '@/lib/path';
+import { createFolderCollectionContent } from './folder-collection';
+import {
+  createCollectionId,
+  createUuidV7,
+  collectionDisplayName,
+  isRecord,
+  parseCollectionDocumentV2,
+  serializeCollectionDocumentV2,
+  validateCollectionProperty,
+  type CollectionDocumentV2,
+  type CollectionMetadata,
+  type CollectionPlacement,
+  type CollectionProperty,
+  type CollectionType,
+} from './model';
+import { createTableDocument, createTableView, parseTableDocument, serializeTableDocument, type MultidimensionalTableDocument } from '@features/multidimensional-table/model';
+import { createMediaLibrary, parseMediaLibrary, serializeMediaLibrary } from '@features/media-library/model';
+
+export interface CollectionRecoveryResult {
+  collectionId: string;
+  collectionType: CollectionType;
+  placement: CollectionPlacement;
+  name: string;
+}
+
+function parseLooseDocument(source: string): Record<string, unknown> | null {
+  try {
+    const value: unknown = YAML.parse(source);
+    return isRecord(value) ? value : null;
+  } catch {
+    // parseDocument can retain a useful partial YAML tree when a later block
+    // is malformed. Keep that partial tree for record-level salvage.
+    try {
+      const value: unknown = YAML.parseDocument(source, { prettyErrors: false }).toJS();
+      return isRecord(value) ? value : null;
+    } catch { return null; }
+  }
+}
+
+function collectionTypeFromWire(value: unknown): CollectionType | null {
+  if (value === 'notes' || value === 'table') return 'table';
+  if (value === 'media' || value === 'media_library') return 'media_library';
+  return null;
+}
+
+function detectCollectionType(source: string, loose: Record<string, unknown> | null): CollectionType {
+  const collection = loose && isRecord(loose.collection) ? loose.collection : null;
+  const parsed = collectionTypeFromWire(collection?.type);
+  if (parsed) return parsed;
+  // A syntax error elsewhere in the YAML should not hide a readable type.
+  const collectionBlock = source.match(/^collection:\s*\r?\n((?:^[ \t]+.*(?:\r?\n|$))*)/m)?.[1] ?? '';
+  const wireType = collectionBlock.match(/^[ \t]{2,}type:\s*(notes|media|table|media_library)\s*$/m)?.[1];
+  return collectionTypeFromWire(wireType) ?? 'table';
+}
+
+/** Identify the renderer without requiring the damaged document to validate. */
+export function inspectCollectionRecoveryType(source: string): CollectionType {
+  return detectCollectionType(source, parseLooseDocument(source));
+}
+
+function detectPlacement(filePath: string): CollectionPlacement {
+  // Placement is tied to the collection's location. A standalone collection
+  // cannot become a folder collection merely because its metadata is corrupt.
+  return canonicalPath(filePath).endsWith('/.index.yaml') ? 'folder' : 'standalone';
+}
+
+function validNotebookRelativePath(value: unknown): value is string {
+  return typeof value === 'string' && Boolean(value) && !value.startsWith('/') && !value.includes('\\')
+    && value.split('/').every((part) => part && part !== '.' && part !== '..');
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+
+function validRecordId(value: unknown): value is string {
+  return typeof value === 'string' && /^rec_[0-9a-f]{32}$/.test(value);
+}
+
+function sourceRecords(
+  loose: Record<string, unknown> | null,
+): { include: unknown[]; exclude: unknown[] } {
+  const payload = loose && isRecord(loose.payload) ? loose.payload : null;
+  const dataset = payload && isRecord(payload.dataset) ? payload.dataset : null;
+  const records = dataset && isRecord(dataset.records) ? dataset.records : null;
+  if (records) return {
+    include: Array.isArray(records.include) ? records.include : [],
+    exclude: Array.isArray(records.exclude) ? records.exclude : [],
+  };
+  // Read the common v1 shape as well as v2. Legacy data rows become explicit
+  // includes; malformed fields are stripped by the type-specific sanitizer.
+  const legacyRecords = payload && isRecord(payload.records) ? payload.records : null;
+  return { include: Array.isArray(legacyRecords?.data) ? legacyRecords.data : [], exclude: [] };
+}
+
+function sanitizeRecords(
+  loose: Record<string, unknown> | null,
+  type: CollectionType,
+  notebookId?: string,
+): { include: Record<string, unknown>[]; exclude: Record<string, unknown>[] } {
+  const records = sourceRecords(loose);
+  const sanitize = (values: unknown[]) => {
+    const seen = new Set<string>();
+    const seenIds = new Set<string>();
+    const output: Record<string, unknown>[] = [];
+    for (const raw of values) {
+      if (!isRecord(raw)) continue;
+      const path = type === 'table' ? raw.note_path : (raw.relative_path ?? raw.note_path);
+      if (!validNotebookRelativePath(path) || seen.has(path)) continue;
+      if (type === 'media_library' && !notebookId
+        && (typeof raw.resource_id !== 'string' || !raw.resource_id.trim())) continue;
+      seen.add(path);
+      const recordId = validRecordId(raw.id) && !seenIds.has(raw.id) ? raw.id : `rec_${createUuidV7()}`;
+      seenIds.add(recordId);
+      output.push({
+        id: recordId,
+        updated_at: validTimestamp(raw.updated_at) ? raw.updated_at : new Date().toISOString(),
+        ...(type === 'table' ? { note_path: path } : { resource_id: notebookId ? `${notebookId}::${path}` : (raw.resource_id as string).trim(), relative_path: path }),
+      });
+    }
+    return output;
+  };
+  return { include: sanitize(records.include), exclude: sanitize(records.exclude) };
+}
+
+function recoveredMetadata(
+  loose: Record<string, unknown> | null,
+  type: CollectionType,
+  placement: CollectionPlacement,
+  fallbackName: string,
+): CollectionMetadata {
+  const raw = loose && isRecord(loose.collection) ? loose.collection : {};
+  const now = new Date().toISOString();
+  const properties: Record<string, CollectionProperty> = {};
+  if (isRecord(raw.properties)) {
+    for (const [key, value] of Object.entries(raw.properties)) {
+      if (validateCollectionProperty(value)) properties[key] = value;
+    }
+  }
+  const rawName = typeof raw.name === 'string' ? raw.name.trim() : '';
+  return {
+    id: typeof raw.id === 'string' && /^col_[0-9a-f]{32}$/.test(raw.id) ? raw.id : createCollectionId(),
+    type,
+    placement,
+    name: rawName || fallbackName,
+    revision: Number.isSafeInteger(raw.revision) && Number(raw.revision) >= 0 ? Number(raw.revision) + 1 : 1,
+    created_at: validTimestamp(raw.created_at) ? raw.created_at : now,
+    updated_at: now,
+    properties,
+  };
+}
+
+function fallbackCollectionName(filePath: string, type: CollectionType): string {
+  const filename = filePath.split(/[\\/]/).filter(Boolean).pop() ?? '';
+  const withoutExtension = filename.replace(/(?:\.index\.ya?ml|\.(?:table|lib)\.ya?ml)$/i, '').trim();
+  return withoutExtension || (type === 'table' ? '多维表格' : '媒体库');
+}
+
+function createTemplate(
+  filePath: string,
+  notebookPath: string,
+  type: CollectionType,
+  placement: CollectionPlacement,
+  name: string,
+): CollectionDocumentV2 {
+  if (placement === 'folder') {
+    const directory = canonicalPath(filePath).replace(/[\\/][^\\/]*$/, '');
+    const relativeDirectory = notebookRelativeDirectoryPath(notebookPath, directory) ?? '';
+    return parseCollectionDocumentV2(createFolderCollectionContent(type === 'table' ? 'notes' : 'media', name, relativeDirectory));
+  }
+  if (type === 'table') return parseCollectionDocumentV2(serializeTableDocument(createTableDocument('table', name, 'standalone')));
+  const media = createMediaLibrary(name);
+  media.collection.placement = 'standalone';
+  // A damaged standalone media library with no readable filter should reopen
+  // with the notebook's discoverable media instead of an empty gallery.
+  media.dataset.filter = { all: [{ field: 'kind', op: 'in', value: ['image', 'video'] }], any: [] };
+  return parseCollectionDocumentV2(serializeMediaLibrary(media));
+}
+
+function tryCollection(candidate: CollectionDocumentV2): CollectionDocumentV2 | null {
+  try {
+    const source = serializeCollectionDocumentV2(candidate);
+    const parsed = parseCollectionDocumentV2(source);
+    if (parsed.collection.type === 'table') parseTableDocument(source);
+    else parseMediaLibrary(source);
+    return parsed;
+  }
+  catch { return null; }
+}
+
+function buildRecoveredDocument(
+  filePath: string,
+  notebookPath: string,
+  loose: Record<string, unknown> | null,
+  type: CollectionType,
+  placement: CollectionPlacement,
+  notebookId?: string,
+): CollectionDocumentV2 {
+  const name = fallbackCollectionName(filePath, type);
+  const template = createTemplate(filePath, notebookPath, type, placement, name);
+  const collection = recoveredMetadata(loose, type, placement, name);
+  const dataset = template.payload.dataset;
+  const incoming = loose && isRecord(loose.payload) && isRecord(loose.payload.dataset) ? loose.payload.dataset : null;
+  let candidate: CollectionDocumentV2 = {
+    ...template,
+    collection,
+    payload: { ...template.payload, dataset: { ...dataset, records: sanitizeRecords(loose, type, notebookId) } },
+  };
+
+  // Keep each optional dataset section only when it passes the full collection
+  // validator in combination with the repaired metadata and records.
+  if (incoming && isRecord(incoming.source) && placement === 'standalone') {
+    const next = { ...candidate, payload: { ...candidate.payload, dataset: { ...candidate.payload.dataset, source: incoming.source } } };
+    candidate = tryCollection(next) ?? candidate;
+  }
+  if (incoming && (incoming.filter === null || isRecord(incoming.filter))) {
+    const next = { ...candidate, payload: { ...candidate.payload, dataset: { ...candidate.payload.dataset, filter: incoming.filter as Record<string, unknown> | null } } };
+    candidate = tryCollection(next) ?? candidate;
+  }
+  if (incoming && isRecord(incoming.schema)) {
+    const datasetWithSchema = { ...candidate.payload.dataset, schema: incoming.schema };
+    let next: CollectionDocumentV2 = { ...candidate, payload: { ...candidate.payload, dataset: datasetWithSchema } };
+    if (type === 'table') {
+      try {
+        const tableDocument = {
+          collection,
+          dataset: datasetWithSchema,
+          views: { default_id: '', items: [] },
+        } as unknown as MultidimensionalTableDocument;
+        const defaultView = createTableView(tableDocument, 'table');
+        next = { ...next, payload: { ...next.payload, views: { default_id: defaultView.id, items: [defaultView] } } };
+      } catch { /* Invalid custom fields fall back to the known template below. */ }
+    }
+    candidate = tryCollection(next) ?? candidate;
+  }
+
+  // Retain custom views only as a valid set. A broken or stale view set falls
+  // back to the generated table/media view, which is always known to validate.
+  const incomingViews = loose && isRecord(loose.payload) && isRecord(loose.payload.views) ? loose.payload.views : null;
+  if (incomingViews && Array.isArray(incomingViews.items)) {
+    const requestedDefault = typeof incomingViews.default_id === 'string' ? incomingViews.default_id : '';
+    const validViews = incomingViews.items.filter(isRecord);
+    const defaultExists = validViews.some((view) => view.id === requestedDefault);
+    const nextViews = {
+      default_id: defaultExists ? requestedDefault : (typeof validViews[0]?.id === 'string' ? validViews[0].id : candidate.payload.views.default_id),
+      items: validViews,
+    };
+    const next = { ...candidate, payload: { ...candidate.payload, views: nextViews } };
+    candidate = tryCollection(next) ?? candidate;
+  }
+  return tryCollection(candidate) ?? template;
+}
+
+/** Repair a malformed collection in place while retaining every valid record/config section. */
+export async function repairCollectionFile(
+  filePath: string,
+  notebookPath: string,
+): Promise<CollectionRecoveryResult> {
+  const root = canonicalPath(notebookPath);
+  const path = canonicalPath(filePath);
+  const source = await externalDocuments.read(path, root);
+  const loose = parseLooseDocument(source);
+  const collectionType = detectCollectionType(source, loose);
+  const placement = detectPlacement(path);
+  const name = fallbackCollectionName(path, collectionType);
+  const notebookId = collectionType === 'media_library'
+    ? (await notebooks.getAll()).find((notebook) => canonicalDirectoryPath(notebook.path) === root)?.id
+    : undefined;
+  if (collectionType === 'media_library' && !notebookId) throw new Error('媒体库所属笔记本未注册');
+  const document = buildRecoveredDocument(path, root, loose, collectionType, placement, notebookId);
+  const content = serializeCollectionDocumentV2(document);
+  // Validate the exact bytes before touching disk; serialization must produce
+  // a complete document accepted by the normal reader.
+  const verified = parseCollectionDocumentV2(content);
+  const result = await externalDocuments.write({ filePath: path, scopePath: root, expectedContent: source, content });
+  if (result.status === 'conflict') throw new Error('集合文件已变化，请重新点击“重置当前视图”');
+  if (result.status === 'missing') throw new Error('集合文件已不存在');
+  if (result.status === 'error') throw new Error(result.message);
+  return {
+    collectionId: verified.collection.id,
+    collectionType: verified.collection.type,
+    placement: verified.collection.placement,
+    name: collectionDisplayName(path, placement) || name,
+  };
+}
diff --git a/app/flowix-web/features/collection/rule-filter.ts b/app/flowix-web/features/collection/rule-filter.ts
index 555d2100e..5282fb3ae 100644
--- a/app/flowix-web/features/collection/rule-filter.ts
+++ b/app/flowix-web/features/collection/rule-filter.ts
@@ -5,6 +5,15 @@ export interface CollectionRuleFilter {
 
 export type CollectionRuleEntry = CollectionRuleFilter | { field: string; op: string; value: unknown };
 
+export interface DatasetRuleFilter {
+  /** Mandatory notebook-relative directory prefix; null means no extra path restriction. */
+  path: string | null;
+  match: 'all' | 'any';
+  conditions: Array<{ field: string; op: string; value: unknown }>;
+}
+
+export type DatasetFilter = CollectionRuleFilter | DatasetRuleFilter;
+
 function isGroup(entry: CollectionRuleEntry): entry is CollectionRuleFilter {
   return 'all' in entry && 'any' in entry;
 }
@@ -20,17 +29,40 @@ export function matchesCollectionFilter(
   return filter.all.every(matches) && (filter.any.length === 0 || filter.any.some(matches));
 }
 
-export function collectionFilterUsesField(filter: CollectionRuleFilter | null, field: string): boolean {
+/** Dataset paths are mandatory; the remaining rules use one explicit match mode. */
+export function matchesDatasetFilter(
+  filter: DatasetFilter,
+  matchesRule: (rule: { field: string; op: string; value: unknown }) => boolean,
+): boolean {
+  if ('conditions' in filter && 'match' in filter) {
+    const pathMatches = filter.path === null
+      || matchesRule({ field: 'path', op: 'contains', value: filter.path });
+    if (!pathMatches) return false;
+    if (filter.conditions.length === 0) return true;
+    return filter.match === 'all'
+      ? filter.conditions.every(matchesRule)
+      : filter.conditions.some(matchesRule);
+  }
+  return matchesCollectionFilter(filter, matchesRule as (rule: Exclude<CollectionRuleEntry, CollectionRuleFilter>) => boolean);
+}
+
+export function collectionFilterUsesField(filter: DatasetFilter | null, field: string): boolean {
   if (!filter) return false;
+  if ('conditions' in filter && 'match' in filter) {
+    return filter.conditions.some((rule) => rule.field === field);
+  }
   const uses = (entry: CollectionRuleEntry): boolean => isGroup(entry)
     ? collectionFilterUsesField(entry, field)
     : entry.field === field;
   return [...filter.all, ...filter.any].some(uses);
 }
 
-export function renameCollectionFilterField(filter: CollectionRuleFilter, previous: string, next: string): CollectionRuleFilter {
+export function renameCollectionFilterField<T extends DatasetFilter>(filter: T, previous: string, next: string): T {
+  if ('conditions' in filter && 'match' in filter) {
+    return { ...filter, conditions: filter.conditions.map((rule) => rule.field === previous ? { ...rule, field: next } : rule) } as T;
+  }
   const rename = (entry: CollectionRuleEntry): CollectionRuleEntry => isGroup(entry)
     ? renameCollectionFilterField(entry, previous, next)
     : entry.field === previous ? { ...entry, field: next } : entry;
-  return { ...filter, all: filter.all.map(rename), any: filter.any.map(rename) };
+  return { ...filter, all: filter.all.map(rename), any: filter.any.map(rename) } as T;
 }
diff --git a/app/flowix-web/features/collection/use-collection-reference.ts b/app/flowix-web/features/collection/use-collection-reference.ts
index c35f18212..8323e53ee 100644
--- a/app/flowix-web/features/collection/use-collection-reference.ts
+++ b/app/flowix-web/features/collection/use-collection-reference.ts
@@ -1,11 +1,11 @@
 import { useEffect, useState } from 'react';
-import { collections, externalDocuments, type CollectionIndexItem } from '@platform/tauri/client';
+import { collections, externalDocuments, type CollectionChangedEvent, type CollectionIndexItem } from '@platform/tauri/client';
 import { subscribe } from '@platform/tauri/event-bus';
+import { subscribeNotebookChanges } from '@platform/tauri/notebook-change-events';
 import { bindCollectionDisplayPath, ensureCollectionDisplay, pinCollectionDisplay } from '@/lib/collection-display-registry';
 import type { FileDisplayIdentity } from '@/lib/file-display-registry';
 import { canonicalDirectoryPath } from '@/lib/path';
 import { parseCollectionDocumentV2, type CollectionType } from './model';
-import { subscribeLocalCollectionChanges } from './events';
 
 interface ReferenceState {
   key: string;
@@ -49,13 +49,17 @@ export function useCollectionReference(notebook: { id: string; path: string } |
     };
     void refresh();
     const matches = (event: { notebookId: string; collectionId?: string }) => event.notebookId === notebook.id && (!event.collectionId || event.collectionId === collectionId);
-    const stopCollection = subscribe<{ notebookId: string; collectionId: string }>('collection-changed', (event) => { if (matches(event)) void refresh(); });
-    const stopPath = subscribe<{ notebookId: string; relativePath?: string; directory?: boolean }>('flowix:path-note-changed', (event) => {
-      if (matches(event) && (event.directory || !event.relativePath || /(?:\.(table|lib)\.ya?ml|\.index\.yaml)$/i.test(event.relativePath))) void refresh();
+    const stopCollection = subscribe<CollectionChangedEvent>('collection-changed', (event) => {
+      if (matches(event) || (event.notebookId === notebook.id && Boolean(event.directoryMove))) void refresh();
     });
-    const stopCatalog = subscribe<{ notebookId: string }>('file-management-changed', (event) => { if (matches(event)) void refresh(); });
-    const stopLocal = subscribeLocalCollectionChanges((event) => { if (matches({ notebookId: event.notebookId, collectionId: event.item.collectionId ?? undefined })) void refresh(); });
-    return () => { active = false; stopCollection(); stopPath(); stopCatalog(); stopLocal(); release?.(); };
+    const stopPath = subscribeNotebookChanges((event) => {
+      const collectionMutation = event.changeId?.startsWith(`collection:${notebook.id}:`);
+      if (!collectionMutation && matches(event) && ((event.kind === 'path-moved' && event.directory) || !event.relativePath || /(?:\.(table|lib)\.ya?ml|\.index\.yaml)$/i.test(event.relativePath))) void refresh();
+    });
+    const stopCatalog = subscribe<{ notebookId: string; operationId?: string }>('file-management-changed', (event) => {
+      if (!event.operationId && matches(event)) void refresh();
+    });
+    return () => { active = false; stopCollection(); stopPath(); stopCatalog(); release?.(); };
   }, [enabled, notebook?.id, root, collectionId, type, viewId, key]);
   return state.key === key ? state : { key, item: null, content: null, fileIdentity: undefined, error: null };
 }
diff --git a/app/flowix-web/features/content/components/content-icon.tsx b/app/flowix-web/features/content/components/content-icon.tsx
new file mode 100644
index 000000000..8047fc14e
--- /dev/null
+++ b/app/flowix-web/features/content/components/content-icon.tsx
@@ -0,0 +1,186 @@
+import { forwardRef } from 'react';
+import type { Icon, IconProps } from '@phosphor-icons/react';
+import { Folder, Globe } from 'lucide-react';
+import {
+  FileCodeIcon,
+  FileDocIcon,
+  FileHtmlIcon,
+  FileImageIcon,
+  FileMdIcon,
+  FilePdfIcon,
+  FilePptIcon,
+  FileTextIcon,
+  FileVideoIcon,
+  FileXlsIcon,
+  FileZipIcon,
+} from '@phosphor-icons/react';
+import { classifyFileContent, type FileContentKind } from '@features/content/model/content-kind';
+import { NoteContentIcon } from './note-content-icon';
+
+export type ContentFileIconKind = FileContentKind | 'fallback';
+
+const PHOSPHOR_ICON_BY_KIND: Record<ContentFileIconKind, Icon> = {
+  note: FileMdIcon,
+  html: FileHtmlIcon,
+  document: FileDocIcon,
+  presentation: FilePptIcon,
+  spreadsheet: FileXlsIcon,
+  pdf: FilePdfIcon,
+  video: FileVideoIcon,
+  archive: FileZipIcon,
+  image: FileImageIcon,
+  code: FileCodeIcon,
+  fallback: FileTextIcon,
+  text: FileTextIcon,
+  unknown: FileTextIcon,
+};
+
+/** Flat icon categories; special resources sit beside file categories. */
+export type ContentKind = FileContentKind | 'folder' | 'web' | 'media-library' | 'multidimensional-table';
+
+export type ContentDescription =
+  | { kind: 'file'; path: string; mimeType?: string | null }
+  | { kind: ContentKind };
+
+/** One renderer for content icons; callers provide facts and layout only. */
+export function ContentIcon({ content, className }: { content: ContentDescription; className?: string }) {
+  const kind = content.kind === 'file'
+    ? getFileIconKind(content.path, content.mimeType)
+    : content.kind;
+  if (kind === 'folder') return <Folder aria-hidden="true" className={className} />;
+  if (kind === 'web') return <Globe aria-hidden="true" className={className} />;
+  if (kind === 'note') return <NoteContentIcon className={className} />;
+  if (kind === 'media-library') return <MediaLibraryIcon className={className} />;
+  if (kind === 'multidimensional-table') return <TableDocumentIcon className={className} />;
+  return <FileKindIcon kind={kind} className={className} />;
+}
+
+/** Resolve a file's semantic icon kind through the shared content classifier. */
+export function getFileIconKind(path: string, mimeType?: string | null): ContentFileIconKind {
+  return classifyFileContent(path, mimeType);
+}
+
+/** Resolve the legacy Phosphor component for callers that need it. */
+export function getFileIcon(path: string): Icon {
+  if (isTableDocumentPath(path)) return PHOSPHOR_ICON_BY_KIND.spreadsheet;
+  return PHOSPHOR_ICON_BY_KIND[getFileIconKind(path)];
+}
+
+export function FileTypeIcon({ path, className }: { path: string; className?: string }) {
+  if (isTableDocumentPath(path)) return <ContentIcon content={{ kind: 'multidimensional-table' }} className={className} />;
+  if (/\.lib\.ya?ml$/i.test(path)) return <ContentIcon content={{ kind: 'media-library' }} className={className} />;
+  return <ContentIcon content={{ kind: 'file', path }} className={className} />;
+}
+
+/** Resolve the custom icons used for non-note files in the notebook tree. */
+export function NotebookTreeResourceIcon({ path, className, collectionType }: { path: string; className?: string; collectionType?: 'table' | 'media_library' }) {
+  const legacyCollectionType = collectionType
+    ?? (isTableDocumentPath(path) ? 'table' : /\.lib\.ya?ml$/i.test(path) ? 'media_library' : undefined);
+  const content: ContentDescription = legacyCollectionType === 'table'
+    ? { kind: 'multidimensional-table' }
+    : legacyCollectionType === 'media_library'
+      ? { kind: 'media-library' }
+      : { kind: 'file', path };
+  return <ContentIcon content={content} className={className} />;
+}
+
+function FileKindIcon({ kind, className }: { kind: ContentFileIconKind; className?: string }) {
+  if (kind === 'image' || kind === 'video' || kind === 'code' || kind === 'unknown') {
+    return <CustomFileIcon kind={kind === 'unknown' ? 'fallback' : kind} className={className} />;
+  }
+  const IconComponent = PHOSPHOR_ICON_BY_KIND[kind];
+  return <IconComponent aria-hidden="true" className={className} />;
+}
+
+function isTableDocumentPath(path: string): boolean {
+  return /\.table\.ya?ml$/i.test(path);
+}
+
+/**
+ * 多维表格 (`.table.yaml`) 的统一图标 ── 与媒体库图标共用 viewBox、缩放、
+ * 描边和透明度，保持文件树内视觉尺寸一致。保留 Phosphor 兼容组件
+ * (forwardRef + IconProps), 以便直接作为 SlashMenuItem.icon 使用。
+ */
+export const TableDocumentIcon = forwardRef<SVGSVGElement, IconProps>(
+  function TableDocumentIcon({ className }, ref) {
+    return (
+      <svg ref={ref} xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
+        <g transform="translate(1.5 1.5) scale(0.625)" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+          <rect width="20" height="18" x="2" y="3" rx="2" />
+          <path d="M9 4v16M3 9h18" />
+        </g>
+      </svg>
+    );
+  },
+);
+
+export const MediaLibraryIcon = forwardRef<SVGSVGElement, IconProps>(
+  function MediaLibraryIcon({ className }, ref) {
+    return (
+      <svg ref={ref} xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
+        <g transform="translate(1.5 1.5) scale(0.625)" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+          <path d="M2 7v10" />
+          <path d="M6 5v14" />
+          <rect width="12" height="18" x="10" y="3" rx="2" />
+        </g>
+      </svg>
+    );
+  },
+);
+
+function CustomFileIcon({ kind, className }: { kind: ContentFileIconKind; className?: string }) {
+  if (kind === 'image') return <ImageFileIcon className={className} />;
+  if (kind === 'video') return <VideoFileIcon className={className} />;
+  if (kind === 'code') return <CodeFileIcon className={className} />;
+  return <FallbackFileIcon className={className} />;
+}
+
+export function CodeFileIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
+      <path d="M5.25 5.37L2.87 7.53C2.01 8.33 2.01 9.05 2.87 9.85L5.25 11.93" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M10.6 1.8L7.3 16.3" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M12.76 5.37L15.13 7.53C15.99 8.33 15.99 9.05 15.13 9.85L12.76 11.93" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+export function FallbackFileIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
+      <g transform="matrix(0.6923077 0 0 0.6923077 0.6923077 0.6923077)">
+        <path d="M 3.6667 19 V 5 c 0 -1.4733 1.1933 -2.6667 2.6667 -2.6667 h 7.448 c 0.3533 0 0.6933 0.14 0.9427 0.3907 l 5.2187 5.2187 c 0.2507 0.2507 0.3907 0.5893 0.3907 0.9427 v 10.1146 c 0 1.4733 -1.1933 2.6667 -2.6667 2.6667 H 6.3333 c -1.4733 0 -2.6667 -1.1933 -2.6667 -2.6667 Z" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
+        <path d="M 20.2133 8.3333 h -4.5467 c -0.736 0 -1.3333 -0.5973 -1.3333 -1.3333 V 2.4693" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
+      </g>
+    </svg>
+  );
+}
+
+export function VideoFileIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
+      <rect x="1.8" y="3.6" width="11.8" height="10.8" rx="1.8" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M13.6 7.08L16 5.16C16.6 4.68 17.3 5.16 17.3 6V12C17.3 12.84 16.6 13.32 16 12.84L13.6 10.92V7.08Z" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+export function ImageFileIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="64"
+      height="64"
+      viewBox="0 0 18 18"
+      fill="none"
+      opacity={0.6}
+      aria-hidden="true"
+      className={className}
+    >
+      <g transform="matrix(0.6666667 0 0 0.6666667 1 1)">
+        <path d="M21.6799 16.9599L18.5499 9.64988C17.4899 7.16988 15.5399 7.06988 14.2299 9.42988L12.3399 12.8399C11.3799 14.5699 9.58993 14.7199 8.34993 13.1699L8.12993 12.8899C6.83993 11.2699 5.01993 11.4699 4.08993 13.3199L2.36993 16.7699C1.15993 19.1699 2.90993 21.9999 5.58993 21.9999H18.3499C20.9499 21.9999 22.6999 19.3499 21.6799 16.9599Z" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+        <path d="M6.96997 8C8.62682 8 9.96997 6.65685 9.96997 5C9.96997 3.34315 8.62682 2 6.96997 2C5.31312 2 3.96997 3.34315 3.96997 5C3.96997 6.65685 5.31312 8 6.96997 8Z" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
+      </g>
+    </svg>
+  );
+}
diff --git a/app/flowix-web/features/content/components/note-content-icon.tsx b/app/flowix-web/features/content/components/note-content-icon.tsx
new file mode 100644
index 000000000..6dbab6e8a
--- /dev/null
+++ b/app/flowix-web/features/content/components/note-content-icon.tsx
@@ -0,0 +1,15 @@
+import type { SVGProps } from 'react';
+
+/** Default note glyph shared by ContentIcon and the legacy Memo icon export. */
+export function NoteContentIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" aria-hidden="true" {...props}>
+      <g transform="matrix(0.6923077 0 0 0.6923077 0.6923077 0.6923077)">
+        <line x1="7.6666" y1="11.36" x2="10.3333" y2="11.36" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
+        <line x1="7.6666" y1="15.18" x2="16.3333" y2="15.18" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
+        <path d="M3.6667 19V5c0-1.4733 1.1933-2.6667 2.6667-2.6667h7.448c.3533 0 .6933.14.9427.3907l5.2187 5.2187c.2507.2507.3907.5893.3907.9427v10.1146c0 1.4733-1.1933 2.6667-2.6667 2.6667H6.3333c-1.4733 0-2.6666-1.1934-2.6666-2.6667Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
+        <path d="M20.2133 8.3333h-4.5467c-.736 0-1.3333-.5973-1.3333-1.3333V2.4693" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
+      </g>
+    </svg>
+  );
+}
diff --git a/app/flowix-web/features/content/model/content-kind.ts b/app/flowix-web/features/content/model/content-kind.ts
new file mode 100644
index 000000000..9d0b35ec0
--- /dev/null
+++ b/app/flowix-web/features/content/model/content-kind.ts
@@ -0,0 +1,119 @@
+/** Factual content categories shared by surfaces that display resources. */
+export type FileContentKind =
+  | 'note'
+  | 'image'
+  | 'video'
+  | 'pdf'
+  | 'html'
+  | 'code'
+  | 'document'
+  | 'presentation'
+  | 'spreadsheet'
+  | 'archive'
+  | 'text'
+  | 'unknown';
+
+const MARKDOWN_EXTENSIONS = new Set(['md', 'markdown']);
+const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg', 'avif', 'ico', 'tif', 'tiff', 'heic', 'heif']);
+const VIDEO_EXTENSIONS = new Set(['3gp', 'avi', 'flv', 'm2ts', 'm4v', 'mkv', 'mov', 'mp4', 'mpeg', 'mpg', 'mts', 'webm', 'wmv']);
+const HTML_EXTENSIONS = new Set(['htm', 'html', 'xhtml']);
+const DOCUMENT_EXTENSIONS = new Set(['doc', 'docm', 'docx', 'dot', 'dotx', 'odt', 'rtf']);
+const PRESENTATION_EXTENSIONS = new Set(['key', 'odp', 'pot', 'potx', 'ppt', 'pptm', 'pptx']);
+const SPREADSHEET_EXTENSIONS = new Set(['csv', 'numbers', 'ods', 'tsv', 'xls', 'xlsb', 'xlsm', 'xlsx', 'xlt', 'xltx']);
+const ARCHIVE_EXTENSIONS = new Set(['7z', 'bz', 'bz2', 'cab', 'gz', 'iso', 'lz', 'lzma', 'rar', 'tar', 'tgz', 'xz', 'zip', 'zst']);
+
+// The desktop reader validates editability independently; these lists describe UI content categories.
+const CODE_EXTENSIONS = new Set([
+  'json', 'jsonc', 'json5', 'yaml', 'yml', 'toml', 'xml',
+  'html', 'htm', 'css', 'scss', 'sass', 'less', 'js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'mts', 'cts',
+  'vue', 'svelte', 'py', 'pyw', 'rs', 'go', 'java', 'kt', 'kts', 'c', 'cc', 'cpp', 'cxx', 'h', 'hh',
+  'hpp', 'hxx', 'cs', 'swift', 'php', 'rb', 'sh', 'bash', 'zsh', 'fish', 'sql', 'graphql', 'gql', 'lua',
+  'r', 'dart', 'scala', 'ex', 'exs', 'erl', 'hrl', 'fs', 'fsx', 'vb', 'pl', 'pm', 'proto', 'ini', 'conf',
+  'cfg', 'properties', 'gradle',
+]);
+const PLAIN_TEXT_EXTENSIONS = new Set(['txt', 'text', 'log']);
+const CODE_FILENAMES = new Set([
+  'dockerfile', 'containerfile', 'makefile', 'gnumakefile', 'procfile', 'justfile', 'rakefile',
+  '.gitattributes', '.gitignore', '.dockerignore', '.editorconfig', '.npmrc', '.nvmrc',
+  '.prettierrc', '.eslintrc',
+]);
+const TEXT_FILENAMES = new Set(['license', 'licence']);
+const CODE_FILENAME_PREFIXES = ['dockerfile.', 'containerfile.', 'makefile.'];
+
+const TEXT_APPLICATION_MIME_TYPES = new Set([
+  'application/json', 'application/ld+json', 'application/xml', 'application/javascript',
+  'application/x-javascript', 'application/x-yaml', 'application/toml', 'application/sql', 'application/graphql',
+]);
+
+export function fileExtension(path: string): string {
+  const filename = path.split(/[\\/]/).pop() ?? path;
+  const dot = filename.lastIndexOf('.');
+  if (dot <= 0 || dot === filename.length - 1) return '';
+  return filename.slice(dot + 1).toLowerCase();
+}
+
+export function normalizeMimeType(mimeType?: string | null): string {
+  return mimeType?.split(';', 1)[0]?.trim().toLowerCase() ?? '';
+}
+
+export function isTextMimeType(mimeType?: string | null): boolean {
+  const mime = normalizeMimeType(mimeType);
+  return !!mime && (mime.startsWith('text/') || TEXT_APPLICATION_MIME_TYPES.has(mime));
+}
+
+export function isMarkdownFilePath(path: string): boolean { return MARKDOWN_EXTENSIONS.has(fileExtension(path)); }
+export function isCodeTextFilePath(path: string): boolean {
+  return (isCodeFileName(path) || CODE_EXTENSIONS.has(fileExtension(path))) && !isMarkdownFilePath(path);
+}
+
+function isCodeFileName(path: string): boolean {
+  const filename = (path.split(/[\\/]/).pop() ?? path).toLowerCase();
+  return CODE_FILENAMES.has(filename) || CODE_FILENAME_PREFIXES.some((prefix) => filename.startsWith(prefix));
+}
+export function isImageFilePath(path: string): boolean { return IMAGE_EXTENSIONS.has(fileExtension(path)); }
+export function isVideoFilePath(path: string): boolean { return VIDEO_EXTENSIONS.has(fileExtension(path)); }
+// Preserve the renderer's established HTML extension set; XHTML still gets the factual HTML icon.
+export function isHtmlFilePath(path: string): boolean { return ['htm', 'html'].includes(fileExtension(path)); }
+
+export function classifyFileContent(path: string, mimeType?: string | null): FileContentKind {
+  const filename = (path.split(/[\\/]/).pop() ?? path).toLowerCase();
+  const extension = fileExtension(path);
+  const mime = normalizeMimeType(mimeType);
+  if (MARKDOWN_EXTENSIONS.has(extension) || mime === 'text/markdown' || mime === 'application/markdown' || mime === 'text/x-markdown') return 'note';
+  if (IMAGE_EXTENSIONS.has(extension) || mime.startsWith('image/')) return 'image';
+  if (VIDEO_EXTENSIONS.has(extension) || mime.startsWith('video/')) return 'video';
+  if (extension === 'pdf' || mime === 'application/pdf') return 'pdf';
+  if (HTML_EXTENSIONS.has(extension) || mime === 'text/html' || mime === 'application/xhtml+xml') return 'html';
+  if (DOCUMENT_EXTENSIONS.has(extension) || mime.includes('wordprocessingml') || mime === 'application/msword' || mime === 'application/rtf') return 'document';
+  if (PRESENTATION_EXTENSIONS.has(extension) || mime.includes('presentation') || mime === 'application/vnd.ms-powerpoint') return 'presentation';
+  if (SPREADSHEET_EXTENSIONS.has(extension) || mime.includes('spreadsheet') || mime === 'application/vnd.ms-excel') return 'spreadsheet';
+  if (ARCHIVE_EXTENSIONS.has(extension) || /(?:zip|compressed|x-7z|x-rar|x-tar)/.test(mime)) return 'archive';
+  if (TEXT_FILENAMES.has(filename) || PLAIN_TEXT_EXTENSIONS.has(extension)) return 'text';
+  if (isCodeFileName(path) || CODE_EXTENSIONS.has(extension) || TEXT_APPLICATION_MIME_TYPES.has(mime)) return 'code';
+  if (isTextMimeType(mimeType)) return 'text';
+  return 'unknown';
+}
+
+export function isEditableTextFilePath(path: string, mimeType?: string | null): boolean {
+  const filename = (path.split(/[\\/]/).pop() ?? path).toLowerCase();
+  return isMarkdownFilePath(path)
+    || isCodeTextFilePath(path)
+    || TEXT_FILENAMES.has(filename)
+    || PLAIN_TEXT_EXTENSIONS.has(fileExtension(path))
+    || isTextMimeType(mimeType);
+}
+
+export type ResourceKind = 'note' | 'image' | 'video' | 'other';
+
+/** Legacy workspace resource classification. MIME helps classify resources without a useful extension. */
+export function resourceKindFromPath(path: string, mimeType?: string | null): ResourceKind {
+  const kind = classifyFileContent(path, mimeType);
+  if (kind === 'note') return 'note';
+  if (kind === 'image' || kind === 'video') return kind;
+  return 'other';
+}
+
+export function isNotebookResourcePath(path: string): boolean {
+  const kind = resourceKindFromPath(path);
+  return kind === 'note' || kind === 'image' || kind === 'video';
+}
diff --git a/app/flowix-web/features/content/public/content-api.ts b/app/flowix-web/features/content/public/content-api.ts
new file mode 100644
index 000000000..8d7aa5c13
--- /dev/null
+++ b/app/flowix-web/features/content/public/content-api.ts
@@ -0,0 +1,17 @@
+export { ContentIcon, getFileIconKind } from '../components/content-icon';
+export type { ContentDescription, ContentKind, ContentFileIconKind } from '../components/content-icon';
+
+export {
+  classifyFileContent,
+  fileExtension,
+  isCodeTextFilePath,
+  isEditableTextFilePath,
+  isHtmlFilePath,
+  isImageFilePath,
+  isMarkdownFilePath,
+  isNotebookResourcePath,
+  isTextMimeType,
+  isVideoFilePath,
+  resourceKindFromPath,
+} from '../model/content-kind';
+export type { FileContentKind, ResourceKind } from '../model/content-kind';
diff --git a/app/flowix-web/features/document/components/csv-preview.test.tsx b/app/flowix-web/features/document/components/csv-preview.test.tsx
new file mode 100644
index 000000000..0a9ad6bd2
--- /dev/null
+++ b/app/flowix-web/features/document/components/csv-preview.test.tsx
@@ -0,0 +1,133 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SurfaceLifecycle } from '@features/workspace/public/surface-api';
+import type { SurfacePresentationUpdate } from '@features/workspace/public/surface-api';
+import { CsvPreview } from './csv-preview';
+import type { CellComponent, ColumnComponent, ColumnDefinition } from 'tabulator-tables';
+
+type TableOptions = { columns: ColumnDefinition[]; data: Record<string, unknown>[] };
+
+const mocks = vi.hoisted(() => ({ read: vi.fn(), write: vi.fn(), addColumn: vi.fn(), options: null as TableOptions | null }));
+vi.mock('@platform/tauri/client/memos', () => ({ externalDocuments: { read: mocks.read, write: mocks.write } }));
+vi.mock('@/lib/i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }));
+vi.mock('tabulator-tables', () => ({ TabulatorFull: class {
+  constructor(public element: HTMLElement, options: TableOptions) { mocks.options = options; }
+  on() {}
+  destroy() {}
+  addColumn() { return mocks.addColumn(); }
+} }));
+
+let root: Root;
+let host: HTMLDivElement;
+let lifecycle: SurfaceLifecycle | null;
+const register = (value: SurfaceLifecycle | null) => { lifecycle = value; };
+let nextPath = 0;
+let path: string;
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+function edit(value: string) {
+  mocks.options!.columns.find((column) => column.field === 'c0')!.cellEdited!({
+    getRow: () => ({ getData: () => ({ _rowId: 1 }) }),
+    getField: () => 'c0', getValue: () => value,
+  } as unknown as CellComponent);
+}
+async function mount(reportPresentation?: (update: SurfacePresentationUpdate) => void) {
+  await act(async () => root.render(<CsvPreview filePath={path} scopePath="/book" onSurfaceLifecycleReady={register} reportPresentation={reportPresentation} />));
+}
+
+beforeEach(async () => {
+  vi.clearAllMocks();
+  mocks.read.mockResolvedValue('header\noriginal');
+  vi.stubGlobal('Worker', class {
+    onmessage: ((event: unknown) => void) | null = null;
+    postMessage({ id }: { id: number }) {
+      this.onmessage?.({ data: { id, kind: 'parsed', data: { headers: ['header'], rows: [['original']], delimiter: ',' } } });
+    }
+    terminate() {}
+  });
+  path = `/book/lifecycle-${++nextPath}.csv`;
+  host = document.createElement('div');
+  root = createRoot(host);
+  lifecycle = null;
+  await mount();
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  vi.unstubAllGlobals();
+});
+
+describe('CSV surface save barrier', () => {
+  it('publishes load failure and retries through the shared surface action', async () => {
+    await act(async () => root.unmount());
+    root = createRoot(host);
+    mocks.read.mockReset().mockRejectedValue(new Error('file is unavailable'));
+    const updates: SurfacePresentationUpdate[] = [];
+    await mount((update) => updates.push(update));
+
+    const errors = updates.filter((update) => update.state?.status === 'error');
+    const error = errors[errors.length - 1];
+    expect(error?.title).toBe(path.split('/').pop());
+    expect(error?.state?.status).toBe('error');
+    if (error?.state?.status !== 'error') throw new Error('expected published CSV load error');
+    const retry = error.state.actions?.find((action) => action.id === 'retry');
+    expect(retry).toBeDefined();
+    await act(async () => retry?.run());
+    expect(mocks.read).toHaveBeenCalledTimes(2);
+    expect(updates.some((update) => update.state?.status === 'loading')).toBe(true);
+  });
+
+  it('waits for an asynchronous column edit before writing its new content', async () => {
+    const addColumn = deferred<void>();
+    mocks.addColumn.mockReturnValueOnce(addColumn.promise);
+    mocks.write.mockImplementation(async ({ content }: { content: string }) => ({ status: 'saved', content }));
+    act(() => mocks.options!.columns.find((column) => column.field === '_csvAction')!.headerClick!(
+      new MouseEvent('click'), {} as ColumnComponent,
+    ));
+    const flush = lifecycle!.flush!();
+    expect(mocks.write).not.toHaveBeenCalled();
+    await act(async () => addColumn.resolve());
+    await expect(flush).resolves.toBe(true);
+    expect(mocks.write).toHaveBeenCalledWith(expect.objectContaining({ content: 'header,\noriginal,' }));
+  });
+
+  it('waits for an ongoing write and revisions edited while that write is pending', async () => {
+    const first = deferred<{ status: 'saved'; content: string }>();
+    const second = deferred<{ status: 'saved'; content: string }>();
+    mocks.write.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise);
+    await act(async () => edit('first'));
+    const flush = lifecycle!.flush!();
+    let finished = false;
+    void flush.then(() => { finished = true; });
+    await act(async () => edit('second'));
+    expect(mocks.write).toHaveBeenCalledTimes(1);
+    expect(finished).toBe(false);
+    await act(async () => first.resolve({ status: 'saved', content: 'header\nfirst' }));
+    expect(mocks.write).toHaveBeenCalledTimes(2);
+    expect(mocks.write).toHaveBeenLastCalledWith(expect.objectContaining({
+      content: 'header\nsecond', expectedContent: 'header\nfirst',
+    }));
+    expect(finished).toBe(false);
+    await act(async () => second.resolve({ status: 'saved', content: 'header\nsecond' }));
+    await expect(flush).resolves.toBe(true);
+  });
+
+  it('rejects navigation on conflict and restores the unsaved draft on remount', async () => {
+    const write = deferred<{ status: 'conflict'; diskContent: string }>();
+    mocks.write.mockReturnValue(write.promise);
+    await act(async () => edit('draft'));
+    const flush = lifecycle!.flush!();
+    await act(async () => write.resolve({ status: 'conflict', diskContent: 'header\nother' }));
+    await expect(flush).resolves.toBe(false);
+    await act(async () => root.unmount());
+    expect(lifecycle).toBeNull();
+    root = createRoot(host);
+    await mount();
+    expect(mocks.read).toHaveBeenCalledTimes(1);
+    expect(mocks.options!.data[1].c0).toBe('draft');
+  });
+});
diff --git a/app/flowix-web/features/document/components/csv-preview.tsx b/app/flowix-web/features/document/components/csv-preview.tsx
index 175c24fbe..60060be2f 100644
--- a/app/flowix-web/features/document/components/csv-preview.tsx
+++ b/app/flowix-web/features/document/components/csv-preview.tsx
@@ -2,6 +2,7 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 import Papa from 'papaparse';
+import type { SurfaceLifecycle, SurfacePresentationUpdate, SurfaceState } from '@features/workspace/public/surface-api';
 import { TabulatorFull as Tabulator, type CellComponent, type ColumnDefinition } from 'tabulator-tables';
 import { externalDocuments } from '@platform/tauri/client/memos';
 import { clearActionableNotice, upsertActionableNotice } from '@features/notifications/actionable-notice-store';
@@ -181,7 +182,12 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePath: string | null }) {
+export function CsvPreview({ filePath, scopePath, onSurfaceLifecycleReady, reportPresentation }: {
+  filePath: string;
+  scopePath: string | null;
+  onSurfaceLifecycleReady?: (lifecycle: SurfaceLifecycle | null) => void;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
+}) {
   const { t } = useI18n();
   const hostRef = useRef<HTMLDivElement>(null);
   const workerRef = useRef<Worker | null>(null);
@@ -192,10 +198,19 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
   const finalNewlineRef = useRef(false);
   const bomRef = useRef(false);
   const revisionRef = useRef(0);
-  const savingRef = useRef<number | null>(null);
+  const savePromiseRef = useRef<{ requestId: number; promise: Promise<boolean> } | null>(null);
+  const mutationsRef = useRef(new Set<Promise<unknown>>());
+  const trackMutation = useCallback(<T,>(operation: () => Promise<T>): Promise<T> => {
+    const promise = operation();
+    mutationsRef.current.add(promise);
+    void promise.then(() => mutationsRef.current.delete(promise), () => mutationsRef.current.delete(promise));
+    return promise;
+  }, []);
   const visibleRowCountRef = useRef(MIN_VISIBLE_ROWS);
   const [state, setState] = useState<CsvLoadState>({ status: 'loading' });
   const [saveState, setSaveState] = useState<SaveState>({ status: 'idle' });
+  const [retryCount, setRetryCount] = useState(0);
+  const retryLoad = useCallback(() => setRetryCount((count) => count + 1), []);
 
   function retainDraft() {
     const doc = documentRef.current;
@@ -210,62 +225,102 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
     });
   }
 
-  const saveCurrentDocument = useCallback(async () => {
+  const saveCurrentDocument = useCallback((): Promise<boolean> => {
     const requestId = requestRef.current;
     const key = draftKey(filePath, scopePath);
-    if (savingRef.current === requestId) return;
-    savingRef.current = requestId;
-    try {
-      while (requestRef.current === requestId && documentRef.current && revisionRef.current > 0) {
-        const revision = revisionRef.current;
-        const doc = documentRef.current;
-        const serialized = Papa.unparse([doc.headers, ...doc.rows], {
-          delimiter: doc.delimiter,
-          newline: newlineRef.current,
-          header: false,
-          skipEmptyLines: false,
-        });
-        const content = `${bomRef.current ? '\uFEFF' : ''}${serialized}${finalNewlineRef.current ? newlineRef.current : ''}`;
-        if (utf8Encoder.encode(content).byteLength > MAX_CSV_BYTES) {
-          setSaveState({ status: 'error', message: '编辑后的 CSV 超过 20 MiB 上限，无法自动保存。' });
-          return;
+    if (savePromiseRef.current?.requestId === requestId) return savePromiseRef.current.promise;
+    const save = async (): Promise<boolean> => {
+      try {
+        while (requestRef.current === requestId && documentRef.current && revisionRef.current > 0) {
+          const revision = revisionRef.current;
+          const doc = documentRef.current;
+          const serialized = Papa.unparse([doc.headers, ...doc.rows], {
+            delimiter: doc.delimiter,
+            newline: newlineRef.current,
+            header: false,
+            skipEmptyLines: false,
+          });
+          const content = `${bomRef.current ? '\uFEFF' : ''}${serialized}${finalNewlineRef.current ? newlineRef.current : ''}`;
+          if (utf8Encoder.encode(content).byteLength > MAX_CSV_BYTES) {
+            setSaveState({ status: 'error', message: '编辑后的 CSV 超过 20 MiB 上限，无法自动保存。' });
+            return false;
+          }
+          const original = savedTextRef.current;
+          const draftVersion = pendingCsvDrafts.get(key)?.version;
+          setSaveState({ status: 'saving' });
+          let outcome: Awaited<ReturnType<typeof externalDocuments.write>>;
+          try {
+            outcome = await externalDocuments.write({ filePath, scopePath, content, expectedContent: original });
+          } catch (error) {
+            if (requestRef.current !== requestId) return false;
+            setSaveState({ status: 'error', message: `自动保存失败：${errorMessage(error)}`, retryable: true });
+            return false;
+          }
+          if (outcome.status !== 'saved') {
+            if (requestRef.current !== requestId) return false;
+            const message = outcome.status === 'conflict'
+              ? '文件已在其他位置修改。当前编辑未覆盖磁盘文件，请重新打开后处理冲突。'
+              : outcome.status === 'missing'
+                ? '文件已不存在，无法自动保存。'
+                : outcome.message;
+            setSaveState({ status: 'error', message, retryable: outcome.status === 'error' });
+            return false;
+          }
+          const draft = pendingCsvDrafts.get(key);
+          if (draft && draft.version === draftVersion) pendingCsvDrafts.delete(key);
+          else if (draft) draft.expectedContent = outcome.content;
+          if (requestRef.current !== requestId) return false;
+          savedTextRef.current = outcome.content;
+          if (revisionRef.current === revision) {
+            revisionRef.current = 0;
+            setSaveState({ status: 'saved' });
+          }
         }
-        const original = savedTextRef.current;
-        const draftVersion = pendingCsvDrafts.get(key)?.version;
-        setSaveState({ status: 'saving' });
-        let outcome: Awaited<ReturnType<typeof externalDocuments.write>>;
-        try {
-          outcome = await externalDocuments.write({ filePath, scopePath, content, expectedContent: original });
-        } catch (error) {
-          if (requestRef.current !== requestId) return;
+        return requestRef.current === requestId && revisionRef.current === 0;
+      } catch (error) {
+        if (requestRef.current === requestId) {
           setSaveState({ status: 'error', message: `自动保存失败：${errorMessage(error)}`, retryable: true });
-          return;
-        }
-        if (outcome.status !== 'saved') {
-          if (requestRef.current !== requestId) return;
-          const message = outcome.status === 'conflict'
-            ? '文件已在其他位置修改。当前编辑未覆盖磁盘文件，请重新打开后处理冲突。'
-            : outcome.status === 'missing'
-              ? '文件已不存在，无法自动保存。'
-              : outcome.message;
-          setSaveState({ status: 'error', message, retryable: outcome.status === 'error' });
-          return;
-        }
-        const draft = pendingCsvDrafts.get(key);
-        if (draft && draft.version === draftVersion) pendingCsvDrafts.delete(key);
-        else if (draft) draft.expectedContent = outcome.content;
-        if (requestRef.current !== requestId) return;
-        savedTextRef.current = outcome.content;
-        if (revisionRef.current === revision) {
-          revisionRef.current = 0;
-          setSaveState({ status: 'saved' });
         }
+        return false;
       }
-    } finally {
-      if (savingRef.current === requestId) savingRef.current = null;
-    }
+    };
+    const promise = save().finally(() => {
+      if (savePromiseRef.current?.promise === promise) savePromiseRef.current = null;
+    });
+    savePromiseRef.current = { requestId, promise };
+    return promise;
   }, [filePath, scopePath]);
 
+  useEffect(() => {
+    const title = filePath.split(/[\\/]/).filter(Boolean).pop() ?? filePath;
+    let surfaceState: SurfaceState;
+    if (state.status === 'loading') {
+      surfaceState = { status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: false };
+    } else if (state.status === 'error') {
+      surfaceState = {
+        status: 'error', message: { key: 'document.file.unavailable', fallbackText: state.message },
+        actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retryLoad }],
+      };
+    } else {
+      // Delimiter selection is an interactive CSV setup step, so the surface
+      // stays ready while its renderer presents that focused choice inline.
+      surfaceState = { status: 'ready' };
+    }
+    reportPresentation?.({ title, state: surfaceState });
+  }, [filePath, reportPresentation, retryLoad, state]);
+
+  useEffect(() => {
+    onSurfaceLifecycleReady?.({ status: 'ready', flush: async () => {
+      const requestId = requestRef.current;
+      while (mutationsRef.current.size) {
+        try { await Promise.all([...mutationsRef.current]); }
+        catch { return false; }
+      }
+      return requestRef.current === requestId && await saveCurrentDocument();
+    } });
+    return () => onSurfaceLifecycleReady?.(null);
+  }, [onSurfaceLifecycleReady, saveCurrentDocument]);
+
   useEffect(() => {
     const noticeId = `csv-save:${draftKey(filePath, scopePath)}`;
     if (saveState.status === 'error' && saveState.retryable) {
@@ -282,7 +337,7 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
           id: 'retry',
           label: t('document.save.retry'),
           variant: 'default',
-          run: saveCurrentDocument,
+          run: async () => { await saveCurrentDocument(); },
         }],
       });
     } else if (saveState.status === 'saving') {
@@ -303,7 +358,6 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
     let cancelled = false;
     documentRef.current = null;
     revisionRef.current = 0;
-    savingRef.current = null;
     setSaveState({ status: 'idle' });
     setState({ status: 'loading' });
     const draft = pendingCsvDrafts.get(draftKey(filePath, scopePath));
@@ -350,7 +404,7 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
       workerRef.current?.terminate();
       workerRef.current = null;
     };
-  }, [filePath, scopePath]);
+  }, [filePath, retryCount, scopePath]);
 
   useEffect(() => {
     if (state.status !== 'ready' || !hostRef.current) return;
@@ -447,7 +501,7 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
       resizable: false,
       hozAlign: 'center',
       headerHozAlign: 'center',
-      headerClick: () => { void addColumn(); },
+      headerClick: () => { void trackMutation(addColumn); },
       formatter: () => '',
     });
     const addVisibleRow = async () => {
@@ -595,7 +649,7 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
     const pasteIntoRange = (pastedRows: Array<Record<string, unknown>>) => {
       if (pasteInProgress) return [];
       pasteInProgress = true;
-      void applyPastedRows(pastedRows).catch((error: unknown) => {
+      void trackMutation(() => applyPastedRows(pastedRows)).catch((error: unknown) => {
         setSaveState({ status: 'error', message: `粘贴失败：${errorMessage(error)}` });
       }).finally(() => { pasteInProgress = false; });
       return [];
@@ -738,7 +792,8 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
         const doc = documentRef.current;
         const revision = revisionRef.current;
         event.preventDefault();
-        void navigator.clipboard.writeText(text).then(() => {
+        void trackMutation(async () => {
+          await navigator.clipboard.writeText(text);
           if (documentRef.current === doc && revisionRef.current === revision) clearSelectedCells(cells);
         }).catch((error: unknown) => {
           setSaveState({ status: 'error', message: `剪切失败：${errorMessage(error)}` });
@@ -746,7 +801,8 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
       } else if (key === 'v') {
         if (!navigator.clipboard?.readText) return;
         event.preventDefault();
-        void navigator.clipboard.readText().then((text) => {
+        void trackMutation(async () => {
+          const text = await navigator.clipboard.readText();
           const pastedRows = parseClipboardRows(text);
           if (pastedRows) pasteIntoRange(pastedRows);
           else setSaveState({ status: 'error', message: '无法将剪贴板内容粘贴到当前选区。' });
@@ -794,6 +850,8 @@ export function CsvPreview({ filePath, scopePath }: { filePath: string; scopePat
     }
   }
 
+  if (reportPresentation && state.status === 'loading') return null;
+  if (reportPresentation && state.status === 'error') return null;
   if (state.status === 'loading') return <div className="csv-preview__status">正在读取 CSV…</div>;
   if (state.status === 'error') {
     return <div className="csv-preview__status csv-preview__error" role="alert">无法显示 CSV：{state.message}</div>;
diff --git a/app/flowix-web/features/document/components/document-container.session.test.tsx b/app/flowix-web/features/document/components/document-container.session.test.tsx
index c3374fbd3..7b82f41f8 100644
--- a/app/flowix-web/features/document/components/document-container.session.test.tsx
+++ b/app/flowix-web/features/document/components/document-container.session.test.tsx
@@ -1,7 +1,7 @@
-import { act } from 'react';
+import { act, type ComponentProps } from 'react';
 import { invoke } from '@platform/tauri/core';
 import { createRoot, type Root } from 'react-dom/client';
-import type { Editor } from '@tiptap/core';
+import type { Editor, JSONContent } from '@tiptap/core';
 import { beforeEach, afterEach, describe, it, expect, vi } from 'vitest';
 import { DocumentContainer } from './document-container';
 import { DocumentSaveNotifications } from './document-save-status';
@@ -21,14 +21,27 @@ import { EditorView } from '@codemirror/view';
 import { publishAgentLocationRequest, peekAgentLocationRequest } from '../use-cases/agent-location-navigation';
 import * as attachmentIo from '@features/editor/extensions/attachment-link/upload/io';
 
-const mocks = vi.hoisted(() => ({ recoveryRead: vi.fn().mockResolvedValue(null), read: vi.fn(), write: vi.fn(), rename: vi.fn(), publish: vi.fn() }));
+const mocks = vi.hoisted(() => ({
+  recoveryRead: vi.fn().mockResolvedValue(null),
+  read: vi.fn(),
+  write: vi.fn(),
+  rename: vi.fn(),
+  publish: vi.fn(),
+  parseMarkdown: vi.fn<(markdown: string) => Promise<{
+    id: number;
+    ok: boolean;
+    document?: JSONContent;
+    workerMs?: number;
+    error?: string;
+  }>>(),
+}));
 vi.mock('@platform/tauri/core', () => ({ invoke: vi.fn(), convertFileSrc: (path: string) => `asset://localhost/${encodeURIComponent(path)}` }));
+vi.mock('@features/editor/markdown-parser', () => ({ parseMarkdownInWorker: mocks.parseMarkdown }));
 vi.mock('./lazy-document-editor', async () => ({
   LazyDocumentEditor: (await import('@features/editor/markdown-editor')).MarkdownEditor,
   preloadDocumentEditor: () => {},
 }));
-vi.mock('../use-cases/local-document-operations', async importOriginal => ({
-  ...await importOriginal<typeof import('../use-cases/local-document-operations')>(),
+vi.mock('../use-cases/local-document-operations', () => ({
   markdownFilenameForTitle: (path: string, title: string) => {
     const extension = path.match(/(\.markdown|\.md)$/i)?.[0] ?? '';
     const trimmed = title.trim();
@@ -67,7 +80,6 @@ vi.mock('@platform/tauri/window', () => ({ getCurrentWindow: () => ({ label: 'ma
 
 let root: Root; let container: HTMLDivElement; let sequence = 0;
 const environment = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
-
 function pasteScreenshot(editor: Editor): ClipboardEvent {
   const event = new Event('paste', { bubbles: true, cancelable: true }) as ClipboardEvent;
   Object.defineProperty(event, 'clipboardData', {
@@ -81,7 +93,7 @@ function pasteScreenshot(editor: Editor): ClipboardEvent {
   return event;
 }
 
-function setup(initialBoth = true) {
+function setup(initialBoth = true, callbacks: Pick<ComponentProps<typeof DocumentContainer>, 'onContentStateChange' | 'onSurfaceLifecycleReady'> = {}) {
   const identity = { kind: 'md' as const, ...ensureFileDisplayIdentity('/container-' + ++sequence + '/A.md') };
   reconcileFileDisplays([identity]);
   let path = identity.path; let both = initialBoth; let mounts = 0;
@@ -90,7 +102,7 @@ function setup(initialBoth = true) {
   const leftReady = ready('left'); const rightReady = ready('right');
   const render = () => root.render(<I18nProvider language="en-US"><ShortcutsProvider overrides={{}}>
     <Toaster /><DocumentSaveNotifications /><ActionableNoticeHost />
-    <DocumentContainer fileIdentity={{ ...identity, path }} isExternalDocument externalEditorMode="markdown" externalScopePath={path.replace(/\/[^/]+$/, '')} onEditorReady={leftReady} />
+    <DocumentContainer {...callbacks} fileIdentity={{ ...identity, path }} isExternalDocument externalEditorMode="markdown" externalScopePath={path.replace(/\/[^/]+$/, '')} onEditorReady={leftReady} />
     {both && <DocumentContainer fileIdentity={{ ...identity, path }}
       isExternalDocument externalEditorMode="markdown" externalScopePath={path.replace(/\/[^/]+$/, '')} documentSessionMode="isolated" onEditorReady={rightReady} />}
   </ShortcutsProvider></I18nProvider>);
@@ -108,6 +120,39 @@ function setup(initialBoth = true) {
 }
 
 describe('real document container session lifecycle', () => {
+  it('reports loading until the editor is mounted, then registers its ready lifecycle', async () => {
+    const onContentStateChange = vi.fn();
+    const onSurfaceLifecycleReady = vi.fn();
+    const doc = setup(false, { onContentStateChange, onSurfaceLifecycleReady });
+    let finishParse!: (reply: {
+      id: number;
+      ok: boolean;
+      document?: JSONContent;
+      workerMs?: number;
+      error?: string;
+    }) => void;
+    mocks.parseMarkdown.mockImplementationOnce(() => new Promise((resolve) => { finishParse = resolve; }));
+    await act(async () => { doc.render(); });
+    expect(mocks.read).toHaveBeenCalled();
+    expect(mocks.parseMarkdown).toHaveBeenCalledWith('Body');
+    expect(doc.editors.left).toBeUndefined();
+    expect(onContentStateChange).toHaveBeenLastCalledWith({ status: 'loading', retainContent: true });
+    expect(onSurfaceLifecycleReady).not.toHaveBeenCalled();
+    expect(container.querySelector('[role="status"]')).not.toBeNull();
+    await act(async () => {
+      finishParse({
+        id: 1,
+        ok: true,
+        document: { type: 'doc', content: [{ type: 'paragraph' }] },
+        workerMs: 1,
+      });
+    });
+    expect(doc.editors.left).toBeDefined();
+    expect(onContentStateChange).toHaveBeenLastCalledWith({ status: 'ready' });
+    expect(onSurfaceLifecycleReady).toHaveBeenLastCalledWith(expect.objectContaining({ status: 'ready' }));
+    expect(container.querySelector('[role="status"]')).toBeNull();
+  });
+
   it('switches a rich Markdown view to source and consumes a pending Agent location after load', async () => {
     const doc = setup(false);
     mocks.read.mockResolvedValue('first\nsecond\nthird');
@@ -181,8 +226,9 @@ describe('real document container session lifecycle', () => {
   });
   beforeEach(() => {
     vi.useFakeTimers(); environment.IS_REACT_ACT_ENVIRONMENT = true;
-    vi.mocked(invoke).mockReset();
+    vi.mocked(invoke).mockReset().mockResolvedValue(undefined);
     useNoteStore.setState({ notebooks: [], selectedNotebook: null });
+    mocks.parseMarkdown.mockReset().mockRejectedValue(new Error('Web Workers are unavailable'));
     mocks.read.mockReset().mockResolvedValue('Body');
     mocks.recoveryRead.mockReset().mockResolvedValue(null);
     mocks.write.mockReset().mockImplementation(async request => ({ status: 'saved', path: request.path, content: request.content }));
@@ -315,8 +361,8 @@ describe('real document container session lifecycle', () => {
     await act(async () => { doc.render(); });
     vi.mocked(invoke).mockClear();
     await act(async () => { doc.editors.left!.commands.openFileDialog(); });
+    // The watch lease is unrelated lifecycle noise; assert no asset was saved.
     expect(invoke).not.toHaveBeenCalledWith('save_notebook_asset', expect.anything());
-    expect(vi.mocked(invoke).mock.calls.map(([command]) => command)).toEqual(['select_files']);
     expect(doc.editors.left!.getMarkdown()).toBe('Body');
   });
   it('opening a second view preserves scheduled autosave', async () => {
@@ -369,11 +415,11 @@ describe('real document container session lifecycle', () => {
     await act(async () => { await vi.advanceTimersByTimeAsync(300); });
     expect(findFileDisplayPath(doc.identity.displayId)).toBe(doc.identity.path);
     expect(mocks.write).toHaveBeenLastCalledWith(expect.objectContaining({ path: doc.identity.path, content: expect.stringContaining('retained body') }));
-    expect((container.querySelector('textarea.memo-title-editor') as HTMLTextAreaElement).value).toBe('A');
-    expect(getDocumentSession(doc.identity).restoredTitle?.draft).toBe('Taken');
     // A rejected rename restores the confirmed title and keeps the attempted
     // title recoverable through an explicit action.
+    expect((container.querySelector('textarea.memo-title-editor') as HTMLTextAreaElement).value).toBe('A');
     expect(container.textContent).toContain('Recover unsaved title');
+    expect(getDocumentSession(doc.identity).restoredTitle?.draft).toBe('Taken');
     expect(doc.mounts()).toBe(2);
   });
   it('autosaves committed content without submitting or closing an active property draft', async () => {
diff --git a/app/flowix-web/features/document/components/document-container.tsx b/app/flowix-web/features/document/components/document-container.tsx
index 490b5c5a8..ac0e4846b 100644
--- a/app/flowix-web/features/document/components/document-container.tsx
+++ b/app/flowix-web/features/document/components/document-container.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import type { SurfacePresentationUpdate } from '@features/workspace/public/surface-api';
 import { getDocumentSession } from '../store/document-runtime-session';
 
 import { useEffect, useCallback, useRef, useMemo, useState } from 'react';
@@ -54,6 +55,7 @@ import { useI18n } from '@/lib/i18n';
 import { CenteredLoadingSpinner } from '@shared/ui/centered-loading-spinner';
 import { WorkspaceEmptyState } from '@shared/ui/workspace-empty-state';
 import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focus-store';
+import { focusWorkspaceHostFromEvent } from '@features/workspace/public/host-api';
 import { getBuffer, subscribeDocumentBufferChanges } from '@features/document/store/buffer-registry';
 import { documentIdentityKey } from '@features/document/store/document-identity';
 import {
@@ -61,7 +63,7 @@ import {
   isExternalDocumentRenameInProgress,
 } from '@features/document/store/external-document-operation';
 import { rebaseActiveDocumentPath } from '@features/document/store/document-session-service';
-import type { Editor } from '@tiptap/core';
+import type { Editor, JSONContent } from '@tiptap/core';
 import { replaceExternalDocumentPath } from '@features/workspace/use-cases/workspace-navigation';
 import { openDocumentLocalLink } from '@features/document/use-cases/open-document-local-link';
 import {
@@ -70,6 +72,15 @@ import {
   peekAgentLocationRequest,
   subscribeAgentLocationRequest,
 } from '@features/document/use-cases/agent-location-navigation';
+import { parseMarkdownInWorker } from '@features/editor/markdown-parser';
+import { markDocumentOpenTrace } from '@/lib/document-open-perf';
+
+type ParsedMarkdownDocument = {
+  key: string;
+  source: string;
+  /** `null` keeps the editor's compatibility fallback after Worker failure. */
+  document: JSONContent | null;
+};
 
 export function DocumentContainer({
   fileIdentity,
@@ -83,16 +94,19 @@ export function DocumentContainer({
   toolbarCollapsed = false,
   onToolbarCollapsedChange,
   documentSessionMode = 'main',
+  workspaceHost,
   navigationViewId,
   readOnly: forcedReadOnly = false,
   initialFocus,
   onEditorReady,
+  onSurfaceLifecycleReady,
+  onContentStateChange,
   onFlushReady,
 }: DocumentContainerProps) {
   const filePath = fileIdentity.path;
   const displayId = fileIdentity.displayId;
   const { t } = useI18n();
-  const hostId = documentSessionMode === 'isolated' ? 'browser-column' : 'main-third';
+  const hostId = workspaceHost ?? (documentSessionMode === 'isolated' ? 'browser-column' : 'main-third');
   const locationViewId = navigationViewId ?? hostId;
   const focusedHostId = useWorkspaceFocusStore((store) => store.focusedHostId);
   const readOnly = forcedReadOnly || focusedHostId !== hostId;
@@ -117,9 +131,15 @@ export function DocumentContainer({
   // 编辑器懒加载完成后递增，驱动待消费的定位请求在 handle 就绪后重试，
   // 避免用固定计时器猜测加载状态。
   const [editorReadyTick, setEditorReadyTick] = useState(0);
+  const [richEditorMount, setRichEditorMount] = useState<{ key: string; ready: boolean } | null>(null);
+  const [codeEditorReadyFor, setCodeEditorReadyFor] = useState<string | null>(null);
+  const richEditorMountReadyFor = richEditorMount?.key ?? null;
+  const richEditorReadyFor = richEditorMount?.ready ? richEditorMount.key : null;
+  const [parsedMarkdownDocument, setParsedMarkdownDocument] = useState<ParsedMarkdownDocument | null>(null);
   const titleEditorRef = useRef<MemoTitleEditorHandle | null>(null);
   const memoFilename = fileNameFromPath(filePath);
   const renameInProgressRef = useRef(false);
+  const previousFilePathRef = useRef(filePath);
   const getCurrentFilePath = useCallback(() => documentIdentity.path, [documentIdentity]);
   const getAttachmentNotebookId = useCallback(() => {
     return resolveNotebookIdForPath(documentIdentity.path, getWorkspaceMemoState().notebooks);
@@ -139,6 +159,92 @@ export function DocumentContainer({
     isolatedSession: documentSessionMode === 'isolated',
   });
 
+  const markdownParserKey = JSON.stringify([documentInstanceKey, filePath]);
+  const parsedMarkdownMatches = parsedMarkdownDocument?.key === markdownParserKey
+    && parsedMarkdownDocument.source === state.fullContent;
+  const shouldMountRichEditor = state.isLoaded && !state.isLoading && !state.error && !usesCodeEditor;
+  const needsWorkerMarkdownParse = richEditorMountReadyFor !== documentInstanceKey
+    && !parsedMarkdownMatches;
+  const canMountRichEditor = shouldMountRichEditor && !needsWorkerMarkdownParse;
+  const editorIsReady = state.isLoaded && !state.isLoading && !state.error
+    && (usesCodeEditor ? codeEditorReadyFor === documentInstanceKey : richEditorReadyFor === documentInstanceKey);
+
+  useEffect(() => {
+    if (!shouldMountRichEditor
+      || richEditorMountReadyFor === documentInstanceKey || parsedMarkdownMatches) return;
+
+    let cancelled = false;
+    const source = state.fullContent;
+    const startedAt = performance.now();
+    markDocumentOpenTrace(transitionId, 'editor:markdown-worker-start', {
+      contentChars: source.length,
+      path: filePath,
+    });
+    const finishWith = (document: JSONContent | null, error?: string, workerMs?: number) => {
+      if (cancelled) return;
+      const elapsedMs = Math.round((performance.now() - startedAt) * 10) / 10;
+      setParsedMarkdownDocument({ key: markdownParserKey, source, document });
+      console.info('[perf:open-doc]', 'MarkdownParser:worker', {
+        elapsedMs,
+        workerMs,
+        contentChars: source.length,
+        success: !error,
+        ...(error ? { error } : {}),
+      });
+      markDocumentOpenTrace(transitionId, error ? 'editor:markdown-worker-error' : 'editor:markdown-worker-ready', {
+        elapsedMs,
+        workerMs,
+        contentChars: source.length,
+        error,
+      });
+    };
+
+    void parseMarkdownInWorker(source).then((reply) => {
+      finishWith(reply.document ?? null, undefined, reply.workerMs);
+    }).catch((error) => {
+      finishWith(null, error instanceof Error ? error.message : String(error));
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    documentInstanceKey,
+    filePath,
+    markdownParserKey,
+    parsedMarkdownMatches,
+    richEditorMountReadyFor,
+    shouldMountRichEditor,
+    state.fullContent,
+    transitionId,
+  ]);
+
+  useEffect(() => {
+    if (!canMountRichEditor) {
+      setRichEditorMount(null);
+      return;
+    }
+    if (richEditorMountReadyFor === documentInstanceKey) return;
+    setRichEditorMount({ key: documentInstanceKey, ready: false });
+  }, [canMountRichEditor, documentInstanceKey, richEditorMountReadyFor]);
+
+  useEffect(() => {
+    if (!onContentStateChange) return;
+    if (state.error) {
+      const retry = () => reloadDocument(filePath, { showLoading: true });
+      if (isExternalDocument && /\.(?:md|markdown)$/i.test(filePath)
+        && state.errorKind === 'missing-note') {
+        onContentStateChange({ status: 'missing-note', path: filePath, retry });
+      } else {
+        onContentStateChange({ status: 'error', message: state.error, retry });
+      }
+    } else if (!editorIsReady) {
+      onContentStateChange({ status: 'loading', retainContent: true });
+    } else {
+      onContentStateChange({ status: 'ready' });
+    }
+  }, [editorIsReady, filePath, isExternalDocument, onContentStateChange, reloadDocument, state.error, state.errorKind]);
+
   useEffect(() => {
     if (!filePath) return;
     const revealPendingLocation = () => {
@@ -393,6 +499,33 @@ export function DocumentContainer({
     onFlushReady?.(flushDocument, discardDocument);
     return () => onFlushReady?.(null, null);
   }, [discardDocument, flushDocument, onFlushReady]);
+  useEffect(() => {
+    if (!editorIsReady) return;
+    let active = true;
+    onSurfaceLifecycleReady?.({
+      status: 'ready', flush: flushDocument, discard: discardDocument,
+      focus: (target = 'body') => {
+        if (!active || !containerRef.current?.getClientRects().length) return false;
+        const focus = target === 'title'
+          ? titleEditorRef.current?.focusEnd
+          : editorHandleRef.current?.focusStart;
+        if (!focus) return false;
+        useWorkspaceFocusStore.getState().focusHost(hostId);
+        requestAnimationFrame(() => {
+          if (active && containerRef.current?.isConnected
+            && useWorkspaceFocusStore.getState().focusedHostId === hostId) {
+            if (target === 'title') titleEditorRef.current?.focusEnd();
+            else editorHandleRef.current?.focusStart?.();
+          }
+        });
+        return true;
+      },
+    });
+    return () => {
+      active = false;
+      onSurfaceLifecycleReady?.(null);
+    };
+  }, [discardDocument, editorIsReady, flushDocument, hostId, onSurfaceLifecycleReady]);
   useEffect(() => {
     if (!filePath) {
       useDocumentMetricsStore.getState().clear(documentInstanceKey);
@@ -413,12 +546,24 @@ export function DocumentContainer({
 
     const loadedDocumentInstanceKey = loadedDocumentInstanceKeyRef.current;
     const instanceKeyChanged = loadedDocumentInstanceKey !== documentInstanceKey;
+    const pathChanged = previousFilePathRef.current !== filePath;
+    previousFilePathRef.current = filePath;
     loadedDocumentInstanceKeyRef.current = documentInstanceKey;
 
     // A path is an attribute of this session, never an editor lifecycle key.
     // Actual external content changes arrive through the content watchers.
     if (!instanceKeyChanged) {
       rebaseActiveDocumentPath(documentIdentity, filePath);
+      if (pathChanged) {
+        if (state.isLoading) return;
+        if (state.error || !state.isLoaded) {
+          reloadDocument(filePath, {
+            preservePending: hasDocumentUnsavedChanges(documentIdentity),
+            showLoading: true,
+          });
+          return;
+        }
+      }
       if (documentSessionMode !== 'isolated' && transitionId !== null) {
         useDocumentStore.getState().finishDocumentTransition(transitionId);
       }
@@ -496,15 +641,15 @@ export function DocumentContainer({
     <div
       ref={containerRef}
       data-document-session-mode={documentSessionMode}
-      onFocusCapture={() => useWorkspaceFocusStore.getState().focusHost(hostId)}
-      onPointerDownCapture={() => useWorkspaceFocusStore.getState().focusHost(hostId)}
+      onFocusCapture={(event) => focusWorkspaceHostFromEvent(event, hostId)}
+      onPointerDownCapture={(event) => focusWorkspaceHostFromEvent(event, hostId)}
       className="document-container h-full w-full min-w-0 flex flex-col bg-transparent relative overflow-hidden"
     >
-      <div className="flex-1 min-h-0 min-w-0 overflow-hidden">
-        {state.isLoading && (
-          <CenteredLoadingSpinner className="h-full w-full" />
+      <div className="relative flex-1 min-h-0 min-w-0 overflow-hidden">
+        {!state.error && !editorIsReady && (
+          <CenteredLoadingSpinner className="absolute inset-0 z-10 bg-[var(--document-bg)]" />
         )}
-        {!state.isLoading && usesCodeEditor && (
+        {state.isLoaded && !state.isLoading && usesCodeEditor && (
           <LazyCodeEditor
             ref={editorHandleRef}
             key={documentInstanceKey}
@@ -515,21 +660,28 @@ export function DocumentContainer({
             autoFocus={initialFocus === 'body'}
             onEditorScroll={handleEditorScroll}
             onEditingFinished={flushPendingEditorChanges}
+            onReadyChange={(ready) => {
+              setCodeEditorReadyFor((current) => ready
+                ? documentInstanceKey : current === documentInstanceKey ? null : current);
+            }}
             scrollHeader={documentHeader ?? undefined}
             searchPanelOpen={searchPanelOpen}
             onSearchPanelOpenChange={onSearchPanelOpenChange}
           />
         )}
-        {!state.isLoading && state.isLoaded && !usesCodeEditor && (
+        {canMountRichEditor && richEditorMountReadyFor === documentInstanceKey && (
           <LazyDocumentEditor
+            ownerPath={documentIdentity.path}
             getAttachmentOwnerPath={getAttachmentOwnerPath}
             getAttachmentNotebookId={getAttachmentNotebookId}
+            workspaceHost={hostId}
             propertyTargetId={propertyTargetId}
             onViewSourceMode={handleToggleEditorMode}
             transitionId={transitionId}
             ref={editorHandleRef}
             key={documentInstanceKey}
             content={state.fullContent}
+            initialParsedContent={parsedMarkdownMatches ? parsedMarkdownDocument?.document ?? undefined : undefined}
             header={documentHeader}
             editable={!readOnly}
             onDirty={handleDirty}
@@ -552,6 +704,11 @@ export function DocumentContainer({
             onSearchPanelOpenChange={onSearchPanelOpenChange}
             onBeforeCreate={(editor: Editor) => {
               onEditorReady?.(editor);
+              setRichEditorMount({ key: documentInstanceKey, ready: true });
+              // The editor has consumed the initial tree; release the duplicate.
+              setParsedMarkdownDocument((parsed) => (
+                parsed?.key === markdownParserKey ? null : parsed
+              ));
               setEditorReadyTick((tick) => tick + 1);
             }}
             linkContext={{
@@ -571,13 +728,31 @@ export function UnavailableFileView({
   filePath,
   openContainingFolder = false,
   scopePath,
+  reportPresentation,
 }: {
   filePath: string;
   openContainingFolder?: boolean;
   scopePath?: string | null;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
 }) {
   const { t } = useI18n();
   const filename = filePath.split(/[\\/]/).filter(Boolean).pop() ?? filePath;
+  const reveal = useCallback(async () => {
+    try { await product.revealInFileManager(filePath); }
+    catch { toast.error(t('memo.fileTree.openFailed')); }
+  }, [filePath, t]);
+  const openDefault = useCallback(async () => {
+    try { await externalDocuments.openWithDefaultApp(filePath, scopePath); }
+    catch { toast.error(t('memo.fileTree.openFailed')); }
+  }, [filePath, scopePath, t]);
+  useEffect(() => {
+    const actions = [{ id: 'reveal', label: { key: openContainingFolder ? 'document.file.openContainingFolder' : 'document.file.reveal' }, enabled: true, run: reveal }];
+    if (openContainingFolder) actions.push({ id: 'open-default', label: { key: 'document.file.openWithDefaultApp' }, enabled: true, run: openDefault });
+    reportPresentation?.({ title: filename, actions,
+      state: { status: 'unavailable', reason: 'unsupported', message: { key: 'document.file.unavailable', fallbackText: filename }, actions } });
+  }, [filename, openContainingFolder, openDefault, reportPresentation, reveal]);
+  if (reportPresentation) return null;
+
   return (
     <div className="flex h-full w-full flex-col items-center justify-center gap-3 px-6 text-sm text-[var(--muted-foreground)]">
       <span className="max-w-full truncate text-[var(--foreground)]" title={filename}>{filename}</span>
@@ -585,25 +760,16 @@ export function UnavailableFileView({
       <div className="flex items-center gap-2">
         <button
           type="button"
-          onClick={() => {
-            const action = product.revealInFileManager(filePath);
-            void action.catch(() => {
-              toast.error(t('memo.fileTree.openFailed'));
-            });
-          }}
-          className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)]"
+          onClick={() => { void reveal(); }}
+          className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]"
         >
           {t(openContainingFolder ? 'document.file.openContainingFolder' : 'document.file.reveal')}
         </button>
         {openContainingFolder && (
           <button
             type="button"
-            onClick={() => {
-              void externalDocuments.openWithDefaultApp(filePath, scopePath).catch(() => {
-                toast.error(t('memo.fileTree.openFailed'));
-              });
-            }}
-            className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)]"
+            onClick={() => { void openDefault(); }}
+            className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]"
           >
             {t('document.file.openWithDefaultApp')}
           </button>
diff --git a/app/flowix-web/features/document/components/document-titlebar-mac.tsx b/app/flowix-web/features/document/components/document-titlebar-mac.tsx
index c221c840f..a64dc44f9 100644
--- a/app/flowix-web/features/document/components/document-titlebar-mac.tsx
+++ b/app/flowix-web/features/document/components/document-titlebar-mac.tsx
@@ -11,8 +11,10 @@ import {
   MediaActions,
   DOCUMENT_TITLEBAR_ICON_BUTTON_MAC,
   AgentThreadCardFullscreenExitButton,
+  AgentThreadCardFullscreenMoreMenu,
   AgentThreadCardFullscreenIdentity,
   useAgentThreadCardFullscreenActive,
+  SurfaceHeaderIcon,
 } from '@features/document/components/document-titlebar-shared';
 import { useI18n } from '@/lib/i18n';
 import {
@@ -40,6 +42,7 @@ export function DocumentTitlebarMac({
     onNavigateForward,
     visible: showNavigationButtons = true,
     title: navigationTitle,
+    icon: navigationIcon,
   },
   contentCapabilities: {
     copyFullText: canCopyFullText,
@@ -117,12 +120,10 @@ export function DocumentTitlebarMac({
             </Tooltip>
           </>
         )}
-        {navigationTitle && (
-          <span
-            className="ml-2 min-w-0 max-w-[320px] truncate text-sm font-medium text-[var(--foreground)]"
-            title={navigationTitle}
-          >
-            {navigationTitle}
+        {(navigationTitle || navigationIcon) && (
+          <span className="ml-2 flex min-w-0 max-w-[320px] items-center gap-2 text-sm font-medium text-[var(--foreground)]" title={navigationTitle ?? undefined}>
+            <SurfaceHeaderIcon icon={navigationIcon} />
+            {navigationTitle && <span className="truncate">{navigationTitle}</span>}
           </span>
         )}
       </div>
@@ -156,8 +157,12 @@ export function DocumentTitlebarMac({
             canViewVersionHistory={canViewVersionHistory}
             folderCollectionViewType={folderCollectionViewType}
             showEditorFontSwitcher={showEditorFontSwitcher}
+            showMoreActions={!isAgentThreadCardFullscreen}
           />
         )}
+        {isAgentThreadCardFullscreen && (
+          <AgentThreadCardFullscreenMoreMenu iconButtonClass={ICON_BTN} />
+        )}
         {isMediaSurface && mediaActions && (
           <MediaActions
             iconButtonClass={ICON_BTN}
diff --git a/app/flowix-web/features/document/components/document-titlebar-shared.tsx b/app/flowix-web/features/document/components/document-titlebar-shared.tsx
index 5fa8ffb7e..6cdbd2fa2 100644
--- a/app/flowix-web/features/document/components/document-titlebar-shared.tsx
+++ b/app/flowix-web/features/document/components/document-titlebar-shared.tsx
@@ -10,6 +10,7 @@ import {
   FileDocIcon,
   FilePdfIcon,
   ClockIcon,
+  MapPinSimpleAreaIcon,
   TrashSimpleIcon,
   SwatchesIcon,
 } from '@phosphor-icons/react';
@@ -37,9 +38,10 @@ import { setDocumentProperties } from '@features/document/public/path-properties
 import { extractFrontmatter } from '@features/document/properties/frontmatter-model';
 import type { NoteColor } from '@/types/note-item';
 import { EditorFontSwitcher, useEditorFontSwitch } from '@features/document/components/editor-font-switcher';
+import { FontSizeSwitcher, type FontSizeMode } from '@shared/ui/font-size-switcher';
+import { useUserSettingsStore } from '@features/preferences/store/user-settings-store';
 import {
   applyLoadedDocumentContent,
-  flushDocumentPath,
   saveDocumentPath,
   getDocumentBuffer,
 } from '@features/document/store/document-session-service';
@@ -51,20 +53,16 @@ type VersionDisplay = PathVersionMeta;
 import { toast } from '@/lib/toast';
 import { FolderCollectionSwitchConfirmDialog } from '@features/collection/public/folder-api';
 import { notebookRelativeDirectoryPath, parentDirectoryPath } from '@/lib/path';
-import type { WorkspaceHostId } from '@features/workspace/store/workspace-focus-store';
+import type { WorkspaceHostId } from '@features/workspace/public/host-api';
 import { useI18n, translate, type AppLanguage, type I18nKey, type I18nParams } from '@/lib/i18n';
 import { createLogger } from '@/lib/logger';
-import { AgentIcon } from '@features/agent/components/agent-icon';
 import { normalizeAgentTypeKey } from '@/lib/agent-types';
 import type { AgentTypeKey } from '@/types/agent';
 import { ICON_FULLSCREEN_EXIT_PATH } from '@features/agent/thread-card/agent-thread-card-icons';
 import { useAgentSessionStore } from '@features/agent/store/agent-session-store';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
-import { BadgeHoverCard } from '@features/agent/thread-card/badge-hover-card';
-import { computeAgentThreadCardBadgeData } from '@features/agent/thread-card/runtime/run-status-presenter';
-import { createRuntimeInfoRequester } from '@features/agent/thread-card/runtime/runtime-info-requester';
-import { getResolvedExternalSessionId } from '@features/agent/services/external-agent-runtime-service';
-import { getAgentConversationRuntimeCwd } from '@features/agent/conversation-presentation';
+import type { AgentConversationInstance } from '@features/agent/store/agent-conversation-types';
+import { AgentConversationMoreMenu } from '@features/agent/components/agent-conversation-more-menu';
+import { AgentConversationIdentity } from '@features/agent/components/agent-conversation-identity';
 
 const logger = createLogger('document-titlebar');
 
@@ -95,6 +93,7 @@ export interface DocumentTitlebarProps {
     onNavigateForward: () => void;
     visible?: boolean;
     title?: string | null;
+    icon?: string | null;
   };
   contentCapabilities: {
     copyFullText: boolean;
@@ -120,11 +119,15 @@ export interface DocumentTitlebarProps {
   folderCollectionViewType?: {
     current: 'table' | 'media_library';
     onSelect: (type: 'table' | 'media_library') => void;
+    isDefaultFolder: boolean;
+    onToggleDefaultFolder: () => void;
   };
 }
 
 const AGENT_THREAD_CARD_FULLSCREEN_CHANGE_EVENT =
   'flowix:agent-thread-card-fullscreen-change';
+const AGENT_THREAD_CARD_FULLSCREEN_RENAME_EVENT =
+  'flowix:agent-thread-card-fullscreen-rename';
 const AGENT_THREAD_CARD_REQUEST_FULLSCREEN_EVENT =
   'flowix:agent-thread-card-request-fullscreen';
 
@@ -192,6 +195,7 @@ export function ExternalDocumentActions({
   canViewVersionHistory,
   folderCollectionViewType,
   showEditorFontSwitcher = false,
+  showMoreActions = true,
 }: {
   filePath: string;
   iconButtonClass: string;
@@ -209,6 +213,7 @@ export function ExternalDocumentActions({
   canViewVersionHistory: boolean;
   folderCollectionViewType?: DocumentTitlebarProps['folderCollectionViewType'];
   showEditorFontSwitcher?: boolean;
+  showMoreActions?: boolean;
 }) {
   const { t, language } = useI18n();
   const { session, currentNotebookPath, isOutsideCurrentNotebook } = useExternalDocumentLocation();
@@ -223,8 +228,23 @@ export function ExternalDocumentActions({
   const [restoringVersionId, setRestoringVersionId] = useState<string | null>(null);
   const [versionRefreshKey, setVersionRefreshKey] = useState(0);
   const fontSwitch = useEditorFontSwitch();
+  const fontSize = useUserSettingsStore((store) => store.settings.format.fontSize);
+  const updateSettings = useUserSettingsStore((store) => store.updateSettings);
   const itemClass = 'group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--hover-bg)] hover:text-[var(--foreground)]';
 
+  const selectedFontSizeMode: FontSizeMode | null = fontSize === 15
+    ? 'small'
+    : fontSize === 16
+      ? 'medium'
+      : fontSize === 17
+        ? 'large'
+        : null;
+
+  const setEditorFontSizeMode = (mode: FontSizeMode) => {
+    const nextFontSize = { small: 15, medium: 16, large: 17 }[mode];
+    void updateSettings({ format: { fontSize: nextFontSize } });
+  };
+
   const changePathColors = async (colors: NoteColor[]) => {
     try {
       if (!await setDocumentProperties(filePath, { flowix_colors: colors })) {
@@ -236,7 +256,6 @@ export function ExternalDocumentActions({
           && note.relativePath === session?.relativePath ? { ...note, colors } : note),
       }));
       setFileColors(colors);
-      useNoteStore.getState().triggerRefresh();
     } catch (error) {
       logger.error('save path note colors failed', { error, filePath });
       toast.error(t('media.properties.saveFailed'));
@@ -268,7 +287,7 @@ export function ExternalDocumentActions({
       const session = useDocumentStore.getState().activeExternalSession;
       if (!session?.notebookId || !session.relativePath || session.fileIdentity.path !== filePath) throw new Error('Document session changed');
       const identity = documentIdentityFromFile(session.fileIdentity);
-      if (!await flushDocumentPath(identity, filePath, session.scopePath)) {
+      if (!await saveDocumentPath(identity, filePath, session.scopePath)) {
         toast.error(t('document.version.saveCurrentFailed'));
         return;
       }
@@ -309,7 +328,7 @@ export function ExternalDocumentActions({
       <NoteColorPicker colors={fileColors} iconButtonClass={iconButtonClass}
         onChange={(colors) => { void changePathColors(colors); }} />
     )}
-    <DropdownMenu>
+    {showMoreActions && <DropdownMenu>
       <DropdownMenuTrigger asChild>
         <button
           type="button"
@@ -323,16 +342,31 @@ export function ExternalDocumentActions({
       <DropdownMenuContent align="end" className="w-[200px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
         {folderCollectionViewType ? (
           <>
-            <div className="shrink-0 px-2 py-1 text-xs font-normal uppercase tracking-wider text-[var(--muted-foreground)]">视图类型</div>
-            {([['table', '多维表格'], ['media_library', '媒体库']] as const).map(([type, label]) => (
+            <div className="flex shrink-0 items-center justify-between gap-2 px-2 py-1 text-xs font-normal uppercase tracking-wider text-[var(--muted-foreground)]">
+              <span>内容偏好</span>
+              <span className="inline-flex items-center gap-1 rounded bg-[var(--muted)] px-1.5 py-0.5 text-[10px] normal-case tracking-normal">
+                文件夹
+              </span>
+            </div>
+            {([['table', '展示笔记'], ['media_library', '展示图/视频']] as const).map(([type, label]) => (
               <DropdownMenuItem key={type} onClick={() => { if (type !== folderCollectionViewType.current) setPendingViewType(type); }} className={itemClass}>
+                <span className="inline-flex h-4 w-4 shrink-0 items-center justify-center" aria-hidden="true">
+                  {folderCollectionViewType.current === type && <Check className="h-4 w-4 text-[var(--brand)]" />}
+                </span>
                 <span className="flex-1">{label}</span>
-                {folderCollectionViewType.current === type && <Check className="h-4 w-4" aria-hidden="true" />}
               </DropdownMenuItem>
             ))}
             <div role="separator" aria-hidden="true" className={POPUP_SEPARATOR_CLASS} />
           </>
-        ) : showEditorFontSwitcher ? <EditorFontSwitcher fontMode={fontSwitch.fontMode} downloadingMode={fontSwitch.downloadingMode} percent={fontSwitch.percent} onSelect={fontSwitch.selectFontMode} /> : null}
+        ) : showEditorFontSwitcher ? <>
+          <EditorFontSwitcher
+            fontMode={fontSwitch.fontMode}
+            downloadingMode={fontSwitch.downloadingMode}
+            percent={fontSwitch.percent}
+            onSelect={fontSwitch.selectFontMode}
+          />
+          <FontSizeSwitcher sizeMode={selectedFontSizeMode} onSelect={setEditorFontSizeMode} />
+        </> : null}
         <DropdownMenuItem onClick={() => void handleCopyPath()} className={itemClass}>
           <LinkSimpleIcon className="h-4 w-4" /> {t('memo.fileTree.copyPath')}
         </DropdownMenuItem>
@@ -401,6 +435,15 @@ export function ExternalDocumentActions({
         >
           <TrashSimpleIcon className="h-4 w-4" /> {t(indexable ? 'memo.delete.confirm' : 'document.external.deleteFile')}
         </DropdownMenuItem>}
+        {folderCollectionViewType && (
+          <>
+            <div role="separator" aria-hidden="true" className={POPUP_SEPARATOR_CLASS} />
+            <DropdownMenuItem onClick={folderCollectionViewType.onToggleDefaultFolder} className={itemClass}>
+              <MapPinSimpleAreaIcon className="h-4 w-4" aria-hidden="true" />
+              {t(folderCollectionViewType.isDefaultFolder ? 'memo.fileTree.clearDefaultCreateFolder' : 'memo.fileTree.setDefaultCreateFolder')}
+            </DropdownMenuItem>
+          </>
+        )}
       </DropdownMenuContent>
       <FolderCollectionSwitchConfirmDialog
         open={pendingViewType !== null}
@@ -454,7 +497,7 @@ export function ExternalDocumentActions({
           </div>
         </DialogContent>
       </Dialog>
-    </DropdownMenu>
+    </DropdownMenu>}
     </>
   );
 }
@@ -488,13 +531,21 @@ export function ExternalPathDisplay({ path }: { path: string }) {
   );
 }
 
+export function SurfaceHeaderIcon({ icon }: { icon?: string | null }) {
+  if (!icon) return null;
+  if (icon.startsWith('http://') || icon.startsWith('https://')) {
+    return <img src={icon} alt="" className="h-4 w-4 shrink-0 rounded-sm object-contain" />;
+  }
+  return <span aria-hidden="true" className="shrink-0 text-sm leading-none">{icon}</span>;
+}
+
 // =====================================================================
 // Memo color picker — multi-select, dropdown of 7 swatches
 // 触发按钮:
 //   - 空数组 (无颜色) 时显示 `Palette` 图标
 //   - 至少 1 个颜色时显示叠加的小圆点 (右上偏移, 制造"多色"的视觉密度)
 // 7 个色块 + 1 个 "无" 按钮: 点色块 toggle, 点 "无" 清空全部。 每次切换
-// 把整组新颜色走 `onChange` 一次性写回后端, 由 memo-event 链路回灌 store。
+// 把整组新颜色走 `onChange` 一次性写回后端；行内状态即时更新，路径通知刷新查询投影。
 // =====================================================================
 
 const COLOR_LABEL_KEYS: Record<NoteColor, I18nKey> = {
@@ -730,7 +781,44 @@ export function AgentThreadCardFullscreenExitButton({
   );
 }
 
-/** Agent identity displayed in a column titlebar while a Thread Card is fullscreen. */
+/** Agent conversation menu rendered in the existing work-column titlebar slot. */
+export function AgentThreadCardFullscreenMoreMenu({
+  iconButtonClass,
+  host = 'main-third',
+}: {
+  iconButtonClass: string;
+  host?: AgentThreadCardFullscreenHost;
+}) {
+  const info = useFullscreenAgentThreadCardInfo(host);
+  const storedInstance = useAgentSessionStore((state) =>
+    info?.instanceId ? state.getInstance(info.instanceId) : null,
+  );
+  const instance: AgentConversationInstance | null = storedInstance ?? (
+    info?.instanceId ? {
+      instanceId: info.instanceId,
+      agentType: info.typeKey,
+      title: info.title,
+      threadId: info.threadId,
+      source: { kind: 'thread-card' },
+      createdAt: 0,
+      updatedAt: 0,
+    } : null
+  );
+
+  if (!info || !instance) return null;
+
+  return (
+    <AgentConversationMoreMenu
+      instance={instance}
+      iconButtonClass={iconButtonClass}
+      onRename={() => window.dispatchEvent(new CustomEvent(AGENT_THREAD_CARD_FULLSCREEN_RENAME_EVENT, {
+        detail: { host, instanceId: instance.instanceId },
+      }))}
+    />
+  );
+}
+
+/** Shared Agent identity displayed in a column titlebar while a conversation is fullscreen. */
 export function AgentThreadCardFullscreenIdentity({
   host = 'main-third',
 }: {
@@ -738,121 +826,36 @@ export function AgentThreadCardFullscreenIdentity({
 } = {}) {
   const { t } = useI18n();
   const info = useFullscreenAgentThreadCardInfo(host);
-  const [isEditingTitle, setIsEditingTitle] = useState(false);
-  const [titleDraft, setTitleDraft] = useState('');
-  // 用 selector 而不是 getState() ── session/runtime store 更新时让组件
-  // 重新 render, 否则外部 session id / cwd 注入后不会反映到 popup 内容。
+  const [renameRequest, setRenameRequest] = useState(0);
   const instance = useAgentSessionStore((state) =>
     info?.instanceId ? state.getInstance(info.instanceId) : null,
   );
-  const codexModel = useAgentSessionStore(
-    (state) => state.sessionMeta.settings.agentCodexModel,
-  );
-  const piCodeMode = useAgentAccessStore((state) =>
-    state.config.defaults?.runtime?.pi?.piCodeMode ?? false,
-  );
-  const projection = useAgentSessionStore((state) => {
-    const threadId = info?.threadId ?? (
-      info?.instanceId ? state.getInstance(info.instanceId)?.threadId : null
-    );
-    return threadId ? state.threadProjections[threadId] : undefined;
-  });
-
-  if (!info) return null;
 
-  const title = instance?.title?.trim() || info.title || t('common.untitled');
-  const commitTitle = () => {
-    const nextTitle = titleDraft.trim();
-    if (nextTitle && nextTitle !== title) {
-      void useAgentSessionStore.getState().renameAgentConversation({
-        instanceId: info.instanceId,
-        threadId: instance?.threadId ?? info.threadId,
-        title: nextTitle,
-        typeKey: info.typeKey,
-      });
-    }
-    setIsEditingTitle(false);
-  };
+  useEffect(() => {
+    const handleRename = (event: Event) => {
+      const detail = (event as CustomEvent<{
+        host?: AgentThreadCardFullscreenHost;
+        instanceId?: string;
+      }>).detail;
+      if (detail?.host !== host || detail.instanceId !== info?.instanceId) return;
+      setRenameRequest((request) => request + 1);
+    };
+    window.addEventListener(AGENT_THREAD_CARD_FULLSCREEN_RENAME_EVENT, handleRename);
+    return () => window.removeEventListener(AGENT_THREAD_CARD_FULLSCREEN_RENAME_EVENT, handleRename);
+  }, [host, info?.instanceId]);
 
-  // Document titlebar 自身在 data-tauri-drag-region 容器里, badge wrapper + trigger
-  // 都必须显式 [-webkit-app-region:no-drag], 否则 Radix HoverCard 的 hover 会被
-  // macOS 窗口拖拽吞掉。同步处理 ── 与第三列 AgentConversationHeader 行为对齐。
-  const productThreadId = instance?.threadId ?? info.threadId ?? '';
-  const providerSessionId = instance?.providerSessionId ?? (
-    productThreadId ? getResolvedExternalSessionId(productThreadId) : null
-  );
-  const { runId, model, usage } = computeAgentThreadCardBadgeData({
-    threadState: projection ? {
-      lastRun: projection.runs.lastRun,
-      activeRunId: projection.runs.activeRunId,
-      runs: projection.runs.runs,
-    } : undefined,
-    codexModel,
-    typeKey: info.typeKey,
-  });
-  const cwd = getAgentConversationRuntimeCwd(instance);
+  if (!info) return null;
 
   return (
-    <div
-      data-tauri-drag-region
-      className="ml-2 flex min-w-0 items-center gap-2"
-    >
-      <span className="agent-thread-card__badge-hover-wrapper shrink-0 [-webkit-app-region:no-drag]">
-        <BadgeHoverCard
-          threadId={productThreadId || undefined}
-          sessionId={providerSessionId ?? undefined}
-          runId={runId}
-          model={model}
-          usage={usage}
-          onRequestRuntimeInfo={createRuntimeInfoRequester(
-            info.typeKey,
-            () => productThreadId || null,
-            () => providerSessionId,
-          )}
-          agentType={info.typeKey}
-          piMode={info.typeKey === 'pi' ? (piCodeMode ? 'code' : 'writing') : undefined}
-          cwd={cwd}
-        />
-        <span className="agent-type-badge shrink-0" aria-hidden="true">
-          <AgentIcon typeKey={info.typeKey} alt="" className="agent-type-badge__icon" />
-        </span>
-      </span>
-      {isEditingTitle ? (
-        <div className="min-w-0 flex-[0_1_auto] truncate rounded px-0.5 py-1 text-sm font-semibold leading-none text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] focus-within:bg-[var(--muted)] [-webkit-app-region:no-drag]">
-          <input
-            autoFocus
-            value={titleDraft}
-            aria-label="重命名会话"
-            onChange={(event) => setTitleDraft(event.target.value)}
-            onBlur={commitTitle}
-            onKeyDown={(event) => {
-              if (event.key === 'Enter' && (event.nativeEvent.isComposing || event.keyCode === 229)) return;
-              if (event.key === 'Enter') {
-                event.preventDefault();
-                commitTitle();
-              } else if (event.key === 'Escape') {
-                event.preventDefault();
-                setIsEditingTitle(false);
-              }
-            }}
-            className="agent-thread-card__title-input h-auto max-w-full min-w-0 border-0 bg-transparent p-0 font-inherit leading-none text-[var(--foreground)] shadow-none outline-none ring-0 focus:border-0 focus:bg-transparent focus:outline-none focus:ring-0 [-webkit-app-region:no-drag]"
-          />
-        </div>
-      ) : (
-        <span
-          className="min-w-0 flex-[0_1_auto] truncate rounded px-0.5 py-1 text-sm font-semibold leading-none text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] [-webkit-app-region:no-drag]"
-          onPointerDown={(event) => event.stopPropagation()}
-          onMouseDown={(event) => event.stopPropagation()}
-          onClick={(event) => {
-            event.stopPropagation();
-            setTitleDraft(title);
-            setIsEditingTitle(true);
-          }}
-        >
-          {title}
-        </span>
-      )}
-    </div>
+    <AgentConversationIdentity
+      instanceId={info.instanceId}
+      title={instance?.title?.trim() || info.title || t('common.untitled')}
+      typeKey={instance?.agentType ?? info.typeKey}
+      threadId={instance?.threadId ?? info.threadId}
+      sessionId={instance?.providerSessionId}
+      renameRequest={renameRequest}
+      className="ml-2 min-w-0"
+    />
   );
 }
 
@@ -976,7 +979,7 @@ function VersionHistorySubmenu({
           <div className="max-h-[272px] overflow-y-auto px-1">
             {loading && (
               <div className="flex items-center gap-1 px-2 py-3 text-xs text-[var(--muted-foreground)]">
-                <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                <Loader2 className="h-3.5 w-3.5 flowix-spin" />
                 {t("document.version.loading")}
               </div>
             )}
@@ -1006,7 +1009,7 @@ function VersionHistorySubmenu({
                     {formatVersionTime(version.createdAt, language)}
                   </span>
                   {isRestoring && (
-                    <Loader2 className="h-3 w-3 animate-spin text-[var(--muted-foreground)] group-hover:text-[var(--foreground)]" />
+                    <Loader2 className="h-3 w-3 flowix-spin text-[var(--muted-foreground)] group-hover:text-[var(--foreground)]" />
                   )}
                   <span className="rounded bg-[var(--background)] px-1.5 py-0.5 text-[10px] text-[var(--muted-foreground)] group-hover:bg-[var(--card)] group-hover:text-[var(--foreground)]">
                     {translate(language, VERSION_SOURCE_LABEL_KEYS[version.source] ?? "") || version.source}
diff --git a/app/flowix-web/features/document/components/document-titlebar-win.tsx b/app/flowix-web/features/document/components/document-titlebar-win.tsx
index b370f0fe2..f236d4d9c 100644
--- a/app/flowix-web/features/document/components/document-titlebar-win.tsx
+++ b/app/flowix-web/features/document/components/document-titlebar-win.tsx
@@ -11,8 +11,10 @@ import {
   MediaActions,
   DOCUMENT_TITLEBAR_ICON_BUTTON_WIN,
   AgentThreadCardFullscreenExitButton,
+  AgentThreadCardFullscreenMoreMenu,
   AgentThreadCardFullscreenIdentity,
   useAgentThreadCardFullscreenActive,
+  SurfaceHeaderIcon,
 } from '@features/document/components/document-titlebar-shared';
 import { useI18n } from '@/lib/i18n';
 import {
@@ -37,6 +39,7 @@ export function DocumentTitlebarWin({
     onNavigateForward,
     visible: showNavigationButtons = true,
     title: navigationTitle,
+    icon: navigationIcon,
   },
   contentCapabilities: {
     copyFullText: canCopyFullText,
@@ -114,12 +117,10 @@ export function DocumentTitlebarWin({
             </Tooltip>
           </>
         )}
-        {navigationTitle && (
-          <span
-            className="ml-2 min-w-0 max-w-[320px] truncate text-sm font-medium text-[var(--foreground)]"
-            title={navigationTitle}
-          >
-            {navigationTitle}
+        {(navigationTitle || navigationIcon) && (
+          <span className="ml-2 flex min-w-0 max-w-[320px] items-center gap-2 text-sm font-medium text-[var(--foreground)]" title={navigationTitle ?? undefined}>
+            <SurfaceHeaderIcon icon={navigationIcon} />
+            {navigationTitle && <span className="truncate">{navigationTitle}</span>}
           </span>
         )}
       </div>
@@ -153,8 +154,12 @@ export function DocumentTitlebarWin({
             canViewVersionHistory={canViewVersionHistory}
             folderCollectionViewType={folderCollectionViewType}
             showEditorFontSwitcher={showEditorFontSwitcher}
+            showMoreActions={!isAgentThreadCardFullscreen}
           />
         )}
+        {isAgentThreadCardFullscreen && (
+          <AgentThreadCardFullscreenMoreMenu iconButtonClass={ICON_BTN} />
+        )}
         {isMediaSurface && mediaActions && (
           <MediaActions
             iconButtonClass={ICON_BTN}
diff --git a/app/flowix-web/features/document/components/docx-preview.tsx b/app/flowix-web/features/document/components/docx-preview.tsx
index 49f2a1b57..ed99ddad4 100644
--- a/app/flowix-web/features/document/components/docx-preview.tsx
+++ b/app/flowix-web/features/document/components/docx-preview.tsx
@@ -2,6 +2,8 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { AlertCircle, ArrowDownToLine, FolderOpen, LoaderCircle } from 'lucide-react';
+import type { SurfaceMessage, SurfaceNotice, SurfacePresentationUpdate, SurfaceState } from '@features/workspace/public/surface-api';
+import type { I18nKey } from '@/lib/i18n/locales';
 import { files, product } from '@platform/tauri/client';
 import { Button } from '@shared/ui/button';
 import { useI18n } from '@/lib/i18n';
@@ -36,32 +38,38 @@ function errorText(error: unknown): string {
   return String(error);
 }
 
-function userFacingError(
-  error: unknown,
-  fallback: string,
-  t: ReturnType<typeof useI18n>['t'],
-): string {
+function userFacingError(error: unknown, fallback: 'docx.previewFailed' | 'docx.conversionFailed'): SurfaceMessage {
   const message = errorText(error);
-  if (message.includes('DOCX_TOO_LARGE')) return t('docx.tooLarge');
-  if (message.includes('DOCX_IMAGE_TOO_LARGE')) return t('docx.imagesTooLarge');
-  if (message.includes('DOCX_IMAGE_UNSUPPORTED')) return t('docx.imageUnsupported');
-  if (message.includes('DOCX_FORBIDDEN')) return t('docx.forbidden');
-  if (message.includes('DOCX_NAME_CONFLICT')) return t('docx.nameConflict');
-  return `${fallback}: ${message.replace(/^DOCX_[A-Z_]+:\s*/, '')}`;
+  if (message.includes('DOCX_TOO_LARGE')) return { key: 'docx.tooLarge' };
+  if (message.includes('DOCX_IMAGE_TOO_LARGE')) return { key: 'docx.imagesTooLarge' };
+  if (message.includes('DOCX_IMAGE_UNSUPPORTED')) return { key: 'docx.imageUnsupported' };
+  if (message.includes('DOCX_FORBIDDEN')) return { key: 'docx.forbidden' };
+  if (message.includes('DOCX_NAME_CONFLICT')) return { key: 'docx.nameConflict' };
+  return { key: fallback, fallbackText: message.replace(/^DOCX_[A-Z_]+:\s*/, '') };
 }
 
-export function DocxPreview({ filePath, scopePath }: { filePath: string; scopePath: string | null }) {
+function translatedMessage(message: SurfaceMessage | null, t: ReturnType<typeof useI18n>['t']): string | null {
+  if (!message) return null;
+  const translated = t(message.key as I18nKey, message.params);
+  return message.fallbackText ? `${translated}: ${message.fallbackText}` : translated;
+}
+
+export function DocxPreview({ filePath, scopePath, reportPresentation }: {
+  filePath: string; scopePath: string | null; reportPresentation?: (update: SurfacePresentationUpdate) => void;
+}) {
   const { t } = useI18n();
   const bodyRef = useRef<HTMLDivElement>(null);
   const stylesRef = useRef<HTMLDivElement>(null);
   const requestRef = useRef(0);
   const bytesRef = useRef<Uint8Array | null>(null);
   const [previewState, setPreviewState] = useState<PreviewState>('loading');
-  const [previewError, setPreviewError] = useState<string | null>(null);
+  const [previewError, setPreviewError] = useState<SurfaceMessage | null>(null);
   const [conversionState, setConversionState] = useState<ConversionState>('idle');
-  const [conversionError, setConversionError] = useState<string | null>(null);
+  const [conversionError, setConversionError] = useState<SurfaceMessage | null>(null);
   const [warningCount, setWarningCount] = useState(0);
   const [generatedName, setGeneratedName] = useState<string | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+  const retry = useCallback(() => setRetryCount((count) => count + 1), []);
 
   useEffect(() => {
     const requestId = ++requestRef.current;
@@ -97,7 +105,7 @@ export function DocxPreview({ filePath, scopePath }: { filePath: string; scopePa
         setPreviewState('ready');
       } catch (error) {
         if (cancelled || requestRef.current !== requestId) return;
-        setPreviewError(userFacingError(error, t('docx.previewFailed'), t));
+        setPreviewError(userFacingError(error, 'docx.previewFailed'));
         setPreviewState('failed');
       }
     })();
@@ -109,7 +117,7 @@ export function DocxPreview({ filePath, scopePath }: { filePath: string; scopePa
       bodyRef.current?.replaceChildren();
       stylesRef.current?.replaceChildren();
     };
-  }, [filePath, scopePath, t]);
+  }, [filePath, retryCount, scopePath, t]);
 
   const convertToMarkdown = useCallback(async () => {
     const bytes = bytesRef.current;
@@ -159,12 +167,40 @@ export function DocxPreview({ filePath, scopePath }: { filePath: string; scopePa
       if (requestRef.current !== requestId) return;
       const message = errorText(error);
       setConversionError(message.includes('DOCX_EMPTY')
-        ? t('docx.emptyResult')
-        : userFacingError(error, t('docx.conversionFailed'), t));
+        ? { key: 'docx.emptyResult' }
+        : userFacingError(error, 'docx.conversionFailed'));
       setConversionState('failed');
     }
   }, [conversionState, filePath, scopePath, t]);
 
+  const revealContainingFolder = useCallback(async () => {
+    try { await product.revealInFileManager(filePath); }
+    catch { toast.error(t('memo.fileTree.openFailed')); }
+  }, [filePath, t]);
+
+  useEffect(() => {
+    const reveal = { id: 'reveal', label: { key: 'document.file.openContainingFolder' }, enabled: true, run: revealContainingFolder };
+    const convert = { id: 'convert', label: { key: 'docx.convert' },
+      enabled: previewState === 'ready' && conversionState !== 'converting' && Boolean(scopePath), run: convertToMarkdown };
+    const notices: SurfaceNotice[] = [];
+    if (conversionState === 'converting') notices.push({ id: 'conversion', severity: 'info', message: { key: 'docx.converting' } });
+    if (conversionState === 'failed' && conversionError) notices.push({
+      id: 'conversion', severity: 'error', message: conversionError, actions: [convert],
+    });
+    if (conversionState === 'success' && generatedName) {
+      notices.push({ id: 'conversion', severity: 'success', message: { key: 'docx.generated', params: { name: generatedName } } });
+      if (warningCount) notices.push({ id: 'conversion-warnings', severity: 'warning', message: { key: 'docx.warnings', params: { count: warningCount } } });
+    }
+    const state: SurfaceState = previewState === 'loading'
+      ? { status: 'loading', phase: 'content', message: { key: 'docx.loading' }, retainContent: false }
+      : previewState === 'failed'
+        ? { status: 'error', message: previewError ?? { key: 'docx.previewFailed' },
+            actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retry }, reveal] }
+        : { status: 'ready', notices };
+    reportPresentation?.({ title: fileName(filePath), actions: [reveal, convert], state });
+  }, [conversionError, conversionState, convertToMarkdown, filePath, generatedName, previewError,
+    previewState, reportPresentation, retry, revealContainingFolder, scopePath, warningCount]);
+
   return (
     <section className="flowix-docx-preview relative flex h-full min-h-0 flex-col">
       <header className="absolute left-0 right-0 top-0 z-20 flex h-10 items-center justify-between gap-3 border-b border-[color-mix(in_oklch,var(--border)_70%,transparent)] bg-[color-mix(in_oklch,var(--card)_78%,transparent)] px-3 backdrop-blur-md">
@@ -184,11 +220,7 @@ export function DocxPreview({ filePath, scopePath }: { filePath: string; scopePa
             className="h-7 w-7 rounded-lg p-0"
             aria-label={t('document.file.openContainingFolder')}
             title={t('document.file.openContainingFolder')}
-            onClick={() => {
-              void product.revealInFileManager(filePath).catch(() => {
-                toast.error(t('memo.fileTree.openFailed'));
-              });
-            }}
+            onClick={() => { void revealContainingFolder(); }}
           >
             <FolderOpen className="h-3.5 w-3.5" aria-hidden="true" />
           </Button>
@@ -201,36 +233,36 @@ export function DocxPreview({ filePath, scopePath }: { filePath: string; scopePa
             className="h-7 gap-1.5 rounded-lg px-2 text-xs"
           >
             {conversionState === 'converting'
-              ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" aria-hidden="true" />
+              ? <LoaderCircle className="h-3.5 w-3.5 flowix-spin" aria-hidden="true" />
               : <ArrowDownToLine className="h-3.5 w-3.5" aria-hidden="true" />}
             {conversionState === 'converting' ? t('docx.converting') : t('docx.convert')}
           </Button>
         </div>
       </header>
 
-      {previewState === 'loading' && (
+      {!reportPresentation && previewState === 'loading' && (
         <div className="flex min-h-0 flex-1 items-center justify-center gap-2 text-sm text-[var(--muted-foreground)]" role="status">
-          <LoaderCircle className="h-4 w-4 animate-spin" aria-hidden="true" />
+          <LoaderCircle className="h-4 w-4 flowix-spin" aria-hidden="true" />
           {t('docx.loading')}
         </div>
       )}
-      {previewState === 'failed' && (
+      {!reportPresentation && previewState === 'failed' && (
         <div className="flex min-h-0 flex-1 items-center justify-center p-6">
           <div className="max-w-lg text-center text-sm text-[var(--destructive)]" role="alert">
             <AlertCircle className="mx-auto mb-2 h-5 w-5" aria-hidden="true" />
-            {previewError}
+            {translatedMessage(previewError, t)}
           </div>
         </div>
       )}
-      {conversionState === 'success' && generatedName && (
+      {!reportPresentation && conversionState === 'success' && generatedName && (
         <p className="shrink-0 border-b border-[var(--border)] px-4 py-2 text-xs text-[var(--muted-foreground)]" role="status">
           {t('docx.generated', { name: generatedName })}
           {warningCount > 0 && ` · ${t('docx.warnings', { count: warningCount })}`}
         </p>
       )}
-      {conversionState === 'failed' && conversionError && (
+      {!reportPresentation && conversionState === 'failed' && conversionError && (
         <p className="shrink-0 border-b border-[var(--border)] px-4 py-2 text-xs text-[var(--destructive)]" role="alert">
-          {conversionError}
+          {translatedMessage(conversionError, t)}
         </p>
       )}
       <div className="flowix-docx-scroll min-h-0 flex-1" style={{ display: previewState === 'ready' ? undefined : 'none' }}>
diff --git a/app/flowix-web/features/document/components/editor-font-switcher.tsx b/app/flowix-web/features/document/components/editor-font-switcher.tsx
index c05d5b257..f11de34a0 100644
--- a/app/flowix-web/features/document/components/editor-font-switcher.tsx
+++ b/app/flowix-web/features/document/components/editor-font-switcher.tsx
@@ -1,10 +1,6 @@
 'use client';
 
 import { useEffect, useRef, useState } from 'react';
-import { Loader2 } from 'lucide-react';
-import standardIcon from '@/assets/editor-font-icons/standard.svg';
-import serifIcon from '@/assets/editor-font-icons/serif.svg';
-import wenkaiIcon from '@/assets/editor-font-icons/wenkai.svg';
 import {
   beginTypographyFontSelection,
   commitTypographyFontSelection,
@@ -15,19 +11,19 @@ import type { FontDownloadProgress } from '@platform/tauri/client/general';
 import { subscribe } from '@platform/tauri/event-bus';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
+import { TypographyFontSwitcher } from '@shared/ui/typography-font-switcher';
+import {
+  getTypographyFontId,
+  getTypographyFontMode,
+  type TypographyFontMode,
+} from '@/lib/typography-font-mode';
 
-const FONT_CHOICES = [
-  { mode: 'standard', icon: standardIcon },
-  { mode: 'serif', icon: serifIcon },
-  { mode: 'wenkai', icon: wenkaiIcon },
-] as const;
-
-type DocumentEditorFontMode = (typeof FONT_CHOICES)[number]['mode'];
+type DocumentEditorFontMode = TypographyFontMode;
 
 export function useEditorFontSwitch() {
   const { t } = useI18n();
   const fontId = useTypographyFontId();
-  const fontMode: DocumentEditorFontMode = fontId === 'noto-serif-sc' ? 'serif' : fontId === 'lxgw-wenkai' ? 'wenkai' : 'standard';
+  const fontMode = getTypographyFontMode(fontId);
   const [downloadingMode, setDownloadingMode] = useState<'serif' | 'wenkai' | null>(null);
   const [percent, setPercent] = useState<number | null>(null);
   const requestId = useRef(0);
@@ -44,22 +40,24 @@ export function useEditorFontSwitch() {
     downloadingFontId.current = null;
   }, []);
 
-  async function selectFontMode(mode: DocumentEditorFontMode) {
+  async function selectFontMode(mode: DocumentEditorFontMode): Promise<boolean> {
     const request = ++requestId.current;
-    const fontId = mode === 'standard' ? 'inter' : mode === 'serif' ? 'noto-serif-sc' : 'lxgw-wenkai';
+    const fontId = getTypographyFontId(mode);
     downloadingFontId.current = mode === 'standard' ? null : fontId;
     setDownloadingMode(mode === 'standard' ? null : mode);
     setPercent(null);
     try {
       const selectionId = await beginTypographyFontSelection();
-      if (requestId.current !== request) return;
+      if (requestId.current !== request) return false;
       if (mode !== 'standard') await ensureDownloadedFontRegistered(fontId);
-      if (requestId.current !== request) return;
+      if (requestId.current !== request) return false;
       await commitTypographyFontSelection(selectionId, fontId);
+      return true;
     } catch (error) {
-      if (requestId.current !== request) return;
+      if (requestId.current !== request) return false;
       const message = error instanceof Error ? error.message : String(error);
       toast.error(t('preferences.format.fontDownloadFailed', { message }));
+      return false;
     } finally {
       if (requestId.current === request) {
         downloadingFontId.current = null;
@@ -83,41 +81,5 @@ export function EditorFontSwitcher({
   percent: number | null;
   onSelect: (mode: DocumentEditorFontMode) => void;
 }) {
-  const { t } = useI18n();
-  const selectedMode = fontMode;
-
-  return (
-    <div className="mb-1">
-      <div className="flex justify-center gap-0.5" role="group" aria-label={t('document.font.label')}>
-        {FONT_CHOICES.map(({ mode, icon }) => {
-          const active = selectedMode === mode;
-          const isLoading = downloadingMode === mode;
-          return (
-            <button
-              key={mode}
-              type="button"
-              aria-pressed={active}
-              disabled={isLoading}
-              onClick={() => onSelect(mode)}
-              className={`group flex h-[58px] w-[58px] shrink-0 flex-col items-center justify-center gap-1 rounded-lg text-[11px] leading-tight transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)] ${active ? 'text-[var(--foreground)]' : 'text-[var(--muted-foreground)]'}`}
-            >
-              {isLoading
-                ? <Loader2 aria-hidden="true" className="h-4 w-4 animate-spin text-[var(--brand)]" />
-                : <img
-                    aria-hidden="true"
-                    src={icon}
-                    alt=""
-                    className="h-6 w-6 shrink-0 dark:invert"
-                  />}
-              <span className="max-w-full truncate tabular-nums">
-                {isLoading
-                  ? percent == null ? '…' : `${percent}%`
-                  : t(mode === 'standard' ? 'document.font.standard' : mode === 'serif' ? 'document.font.serif' : 'document.font.wenkai')}
-              </span>
-            </button>
-          );
-        })}
-      </div>
-    </div>
-  );
+  return <TypographyFontSwitcher fontMode={fontMode} downloadingMode={downloadingMode} percent={percent} onSelect={onSelect} />;
 }
diff --git a/app/flowix-web/features/document/components/memo-title-editor.tsx b/app/flowix-web/features/document/components/memo-title-editor.tsx
index 7590210e2..8c5db128d 100644
--- a/app/flowix-web/features/document/components/memo-title-editor.tsx
+++ b/app/flowix-web/features/document/components/memo-title-editor.tsx
@@ -224,7 +224,7 @@ export const MemoTitleEditor = forwardRef<MemoTitleEditorHandle, MemoTitleEditor
       if (occupiedPropertyKeys.has(key)
         || getPropertyPresets().some((field) => canonicalizePropertyKey(field.key).toLocaleLowerCase() === normalizedKey)
         || SYSTEM_FRONTMATTER_KEYS.has(normalizedKey)
-        || ['flowix_key', 'flowix_property_types', 'flowix_plugin'].includes(normalizedKey)) {
+        || ['flowix_property_types', 'flowix_plugin'].includes(normalizedKey)) {
         toast.error(t('document.properties.commonKey.alreadyExists'));
         return;
       }
diff --git a/app/flowix-web/features/document/components/note-properties/date-value-input.tsx b/app/flowix-web/features/document/components/note-properties/date-value-input.tsx
index a96da0241..bf06eb96b 100644
--- a/app/flowix-web/features/document/components/note-properties/date-value-input.tsx
+++ b/app/flowix-web/features/document/components/note-properties/date-value-input.tsx
@@ -143,7 +143,7 @@ export function DateValueInput({
       <PopoverContent
         align="start"
         sideOffset={6}
-        className={cn('frontmatter-property__date-picker-popover w-[272px] rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' ? 'p-1' : 'p-2')}
+        className={cn('frontmatter-property__date-picker-popover w-[272px] rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' ? '!z-[170] p-1' : 'p-2')}
       >
         <div className="rounded-lg bg-[var(--card)]">
           <div className="mb-2 flex items-center justify-between px-1">
diff --git a/app/flowix-web/features/document/components/property-preset-menu.tsx b/app/flowix-web/features/document/components/property-preset-menu.tsx
index f76a6f757..76b252c6d 100644
--- a/app/flowix-web/features/document/components/property-preset-menu.tsx
+++ b/app/flowix-web/features/document/components/property-preset-menu.tsx
@@ -6,6 +6,7 @@ import type { PropertyPreset } from '@features/document/properties/presets';
 import { Popover, PopoverContent, PopoverTrigger } from '@shared/ui/popover';
 import { POPUP_SEPARATOR_CLASS } from '@shared/ui/popup-separator';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 import type { I18nKey } from '@/lib/i18n';
 import { getPropertyTypeDefinition } from '@/lib/property-types';
 
@@ -87,7 +88,7 @@ export function PropertyPresetMenu({
         <span className="shrink-0 text-right text-xs text-[var(--muted-foreground)]">
           {t(getPropertyTypeDefinition(preset.kind).labelKey)}
         </span>
-        <input type="checkbox" checked={added} readOnly aria-hidden="true" tabIndex={-1} className="pointer-events-none h-4 w-4 shrink-0 accent-[var(--brand)]" />
+        <FlowixCheckbox checked={added} interactive={false} className="pointer-events-none shrink-0" />
       </button>;
     })}</section>;
 
@@ -117,7 +118,7 @@ export function PropertyPresetMenu({
         }}
         placeholder={t('document.properties.picker.search')}
         aria-label={t('document.properties.picker.search')}
-        className="agent-thread-card__composer-note-search multidimensional-table__preset-search shrink-0"
+        className="agent-composer__note-search multidimensional-table__preset-search shrink-0"
       />
       <div role="separator" aria-hidden="true" className={`${POPUP_SEPARATOR_CLASS} shrink-0`} />
       <OverlayScrollbar className="min-h-0 max-h-[calc(60vh-60px)] flex-1" scrollerClassName="min-h-0 max-h-[calc(60vh-60px)] overflow-y-auto overflow-x-hidden">
@@ -125,7 +126,7 @@ export function PropertyPresetMenu({
           {renderGroup(t('preferences.documentProperties.group.presets'), visibleSystemPresets)}
           {renderGroup(customGroupLabel ?? t('preferences.documentProperties.group.mine'), visibleCustomPresets)}
           {normalizedQuery && visibleSystemPresets.length === 0 && visibleCustomPresets.length === 0 && (
-            <div className="agent-thread-card__composer-note-empty">{t('document.properties.picker.empty')}</div>
+            <div className="agent-composer__note-empty">{t('document.properties.picker.empty')}</div>
           )}
           <button type="button" disabled={disabled} onClick={onManage} className="flex h-8 w-full items-center rounded-lg px-2 text-left text-sm text-[var(--foreground)] hover:bg-[var(--hover-bg)] disabled:opacity-50">
             预设属性管理
diff --git a/app/flowix-web/features/document/components/session/types.ts b/app/flowix-web/features/document/components/session/types.ts
index d51f91bbb..4fdd033e5 100644
--- a/app/flowix-web/features/document/components/session/types.ts
+++ b/app/flowix-web/features/document/components/session/types.ts
@@ -1,17 +1,25 @@
 import type { Editor } from '@tiptap/core';
 import type { FileDisplayIdentity } from '@/lib/file-display-registry';
+import type { SurfaceLifecycle, WorkspaceSurfaceHost } from '@features/workspace/public/surface-api';
 
 export interface LoadContentOptions {
   preservePending?: boolean;
   showLoading?: boolean;
 }
 
+export type DocumentContentStatus =
+  | { status: 'loading'; retainContent: boolean }
+  | { status: 'ready' }
+  | { status: 'missing-note'; path: string; retry: () => void | Promise<void> }
+  | { status: 'error'; message: string; retry: () => void | Promise<void> };
+
 export interface DocumentContainerState {
   // fullContent includes frontmatter + body markdown
   fullContent: string;
   isLoaded: boolean;
   isLoading: boolean;
   error: string | null;
+  errorKind: 'missing-note' | 'error' | null;
   isScrolled: boolean;
   isNewlyCreated: boolean;
   charCount: number;
@@ -53,6 +61,8 @@ export interface DocumentContainerProps {
   onToolbarCollapsedChange?: (collapsed: boolean) => void;
   /** Keep this editor out of the main workspace's singleton document session. */
   documentSessionMode?: 'main' | 'isolated';
+  /** Explicit host supplied by the workspace surface protocol. */
+  workspaceHost?: WorkspaceSurfaceHost;
   /** Runtime surface identity used to bind one-shot Agent navigation requests. */
   navigationViewId?: string;
   /** Render the document without edit or metadata mutation controls. */
@@ -61,6 +71,10 @@ export interface DocumentContainerProps {
   initialFocus?: 'title' | 'body';
   /** Expose the active rich-text editor to document-level exporters. */
   onEditorReady?: (editor: Editor | null) => void;
+  /** Publish the loaded view's lifecycle; null releases this editor's registration. */
+  onSurfaceLifecycleReady?: (lifecycle: SurfaceLifecycle | null) => void;
+  /** Publish the actual content read state to the owning surface adapter. */
+  onContentStateChange?: (state: DocumentContentStatus) => void;
   /** Register the active editor flush used by tabbed hosts before switching. */
   onFlushReady?: (
     flush: ((options?: { silent?: boolean }) => Promise<boolean>) | null,
@@ -73,6 +87,7 @@ export const initialDocumentContainerState: DocumentContainerState = {
   isLoaded: false,
   isLoading: false,
   error: null,
+  errorKind: null,
   isScrolled: false,
   isNewlyCreated: false,
   charCount: 0,
diff --git a/app/flowix-web/features/document/components/session/use-document-autosave.ts b/app/flowix-web/features/document/components/session/use-document-autosave.ts
index ddb64a04a..762e4890b 100644
--- a/app/flowix-web/features/document/components/session/use-document-autosave.ts
+++ b/app/flowix-web/features/document/components/session/use-document-autosave.ts
@@ -1,5 +1,4 @@
 import { useCallback, useEffect, useRef } from 'react';
-import { installDocumentShutdown } from '../../store/document-shutdown';
 import { getDocumentSession, listDocumentSessions } from '../../store/document-runtime-session';
 import { commitDocumentSession, scheduleDocumentSessionSave, recordDocumentEdit,
   registerDocumentCapture, registerDocumentPersistence, prepareDocumentLeave, discardDocumentDraft } from '../../store/document-session-service';
@@ -63,7 +62,7 @@ export function useDocumentAutosave(options: UseDocumentAutosaveOptions) {
 
   useEffect(() => {
     mounted.current = true;
-    installDocumentShutdown(); installVisibilityCapture();
+    installVisibilityCapture();
     const stopCapture = registerDocumentCapture(identity,
       () => live.current.flushPendingContent?.() ?? null,
       live.current.hostId, () => live.current.isActive?.() !== false);
diff --git a/app/flowix-web/features/document/components/session/use-document-content.ts b/app/flowix-web/features/document/components/session/use-document-content.ts
index c66a7f7f5..247b94aa1 100644
--- a/app/flowix-web/features/document/components/session/use-document-content.ts
+++ b/app/flowix-web/features/document/components/session/use-document-content.ts
@@ -1,6 +1,6 @@
 import { getBuffer } from '../../store/buffer-registry';
 import { getDocumentSession } from '../../store/document-runtime-session';
-import { restoreTitleDraft } from '@features/document/store/document-title-session';
+import { hasTitleDraft, restoreTitleDraft } from '@features/document/store/document-title-session';
 import { useCallback, useEffect, useRef, useState } from 'react';
 
 import { localDocumentOperations } from '@features/document/use-cases/local-document-operations';
@@ -13,11 +13,16 @@ import {
   protectDocumentDraft,
   saveDocumentContent,
 } from '@features/document/store/document-session-service';
-import { readRecoveryDraft, type RecoveryDraft } from '@features/document/store/recovery-draft-store';
+import {
+  clearRecoveryDraftThrough,
+  readRecoveryDraft,
+  type RecoveryDraft,
+} from '@features/document/store/recovery-draft-store';
 import { useDocumentStore } from '@features/document/store/document-store';
 import type { DocumentIdentity } from '@features/document/store/document-identity';
 import { translate } from '@/lib/i18n';
-import { isFileDisplayIdLive } from '@/lib/file-display-registry';
+import { findFileDisplayPath, isFileDisplayIdLive } from '@/lib/file-display-registry';
+import { canonicalPath } from '@/lib/path';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 import { markDocumentOpenTrace } from '@/lib/document-open-perf';
 import {
@@ -39,6 +44,27 @@ interface UseDocumentContentOptions {
   isolatedSession?: boolean;
 }
 
+const RECOVERY_DRAFT_READ_TIMEOUT_MS = 10_000;
+
+function readRecoveryDraftWithin(promise: Promise<RecoveryDraft | null>): Promise<RecoveryDraft | null> {
+  return new Promise((resolve, reject) => {
+    const timer = window.setTimeout(
+      () => reject(new Error('Recovery draft read timed out')),
+      RECOVERY_DRAFT_READ_TIMEOUT_MS,
+    );
+    void promise.then(
+      (draft) => {
+        window.clearTimeout(timer);
+        resolve(draft);
+      },
+      (error) => {
+        window.clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
 function logOpenDocPerf(label: string, startedAt: number, meta?: Record<string, unknown>) {
   console.info('[perf:open-doc]', label, {
     elapsedMs: Math.round((performance.now() - startedAt) * 10) / 10,
@@ -53,15 +79,25 @@ function logOpenDocPerf(label: string, startedAt: number, meta?: Record<string,
   }
 }
 
+function isMissingDocumentError(error: unknown): boolean {
+  const reason = error instanceof Error ? error.message : String(error);
+  const normalized = reason.toLowerCase();
+  return normalized.includes('external document is unavailable')
+    || normalized.includes('no such file')
+    || normalized.includes('not found')
+    || normalized.includes('failed to resolve');
+}
+
 function readFailureMessage(error: unknown, language: ReturnType<typeof getCurrentAppLanguage>): string {
   const reason = error instanceof Error ? error.message : String(error);
   const normalized = reason.toLowerCase();
+  if (normalized.includes('recovery draft read timed out')) {
+    return translate(language, 'document.load.recoveryTimeout');
+  }
   if (normalized.includes('outside its authorized scope') || normalized.includes('permission denied')) {
     return translate(language, 'document.load.accessDenied');
   }
-  if (normalized.includes('no such file') || normalized.includes('not found') || normalized.includes('failed to resolve')) {
-    return translate(language, 'document.load.fileNotFound');
-  }
+  if (isMissingDocumentError(error)) return translate(language, 'document.load.fileNotFound');
   if (normalized.includes('not a supported text file') || normalized.includes('is a directory')
     || normalized.includes('not a regular file') || normalized.includes('expected file')) {
     return translate(language, 'document.load.notTextFile');
@@ -84,15 +120,18 @@ export function useDocumentContent({
   // Monotonic counter for the latest reloadDocument call. Stale IPC
   // reads compare against this and abort.
   const counter = useRef(0);
+  const reloadDocumentRef = useRef<((path: string, options?: LoadContentOptions) => Promise<void>) | null>(null);
 
-  const readOpeningRecovery = useCallback(() => {
+  const readOpeningRecovery = useCallback((path: string) => {
     const session = getDocumentSession(identity);
-    if (session.openingRecovery) return session.openingRecovery;
-    const pending = readRecoveryDraft(identity).catch(() => null);
-    session.openingRecovery = pending;
-    void pending.finally(() => {
-      if (session.openingRecovery === pending) session.openingRecovery = undefined;
-    });
+    const recoveryPath = canonicalPath(path);
+    if (session.openingRecovery?.path === recoveryPath) return session.openingRecovery.promise;
+    const pending = readRecoveryDraft({ ...identity, path: recoveryPath });
+    session.openingRecovery = { path: recoveryPath, promise: pending };
+    const clearPending = () => {
+      if (session.openingRecovery?.promise === pending) session.openingRecovery = undefined;
+    };
+    void pending.then(clearPending, clearPending);
     return pending;
   }, [identity]);
 
@@ -118,26 +157,26 @@ export function useDocumentContent({
         setAsCurrent: !isolatedSession,
       });
       const recovery = options?.recovery ?? null;
-      if (recovery && recovery.originalPath === path) {
+      const recoveryMatchesPath = recovery?.originalPath === path;
+      const recoveryNeedsSave = Boolean(recoveryMatchesPath && recovery.content !== fullContent);
+      if (recoveryMatchesPath && recovery) {
         const session = getDocumentSession(identity);
         session.recoveryRevision = Math.max(session.recoveryRevision, recovery.revision);
       }
-      if (recovery?.title && recovery.originalPath === path) restoreTitleDraft(identity.displayId, recovery.title);
-      const recoveryNeedsMerge = Boolean(recovery
-        && recovery.originalPath === path
-        && recovery.content !== fullContent
-        && recovery.baseContent !== fullContent);
-      if (
-        recovery
-        && recovery.originalPath === path
-      ) {
+      if (recovery?.title && recoveryMatchesPath) restoreTitleDraft(identity.displayId, recovery.title);
+      if (recoveryNeedsSave && recovery) {
         applyRecoveryDraftContent(identity, recovery.content, recovery.bodyRevision ?? recovery.revision);
-        if (recoveryNeedsMerge) {
+        if (recovery.baseContent !== fullContent) {
           // The same conditional write used by live edits attempts a diffy
           // merge. An overlap will mark the buffer conflicted for review.
           buf.lastSavedContent = recovery.baseContent;
           buf.saveState = 'dirty';
         }
+      } else if (recoveryMatchesPath && recovery && !hasTitleDraft(identity.displayId)) {
+        // A completed body save can leave behind a checkpoint if clearing it
+        // raced with shutdown. The disk already has these bytes, so only clear
+        // the checkpoint after confirming there is no unsaved title input.
+        void clearRecoveryDraftThrough(identity, recovery.revision);
       }
       // A document heading does not imply that the file was just created.
       const initialContent = recovery
@@ -152,6 +191,7 @@ export function useDocumentContent({
         isLoaded: true,
         isLoading: false,
         error: null,
+        errorKind: null,
         isScrolled: false,
         isNewlyCreated: false,
         charCount: initialCharCount,
@@ -162,7 +202,7 @@ export function useDocumentContent({
         isFavorited: false,
         frontmatterMeta: {},
       });
-      if (recoveryNeedsMerge && recovery) {
+      if (recoveryNeedsSave && recovery) {
         void saveDocumentContent({
           identity, path, content: recovery.content,
           scopePath: externalScopePath, force: true,
@@ -180,19 +220,29 @@ export function useDocumentContent({
   const reloadDocument = useCallback(
     async (path: string, options?: LoadContentOptions) => {
       if (!path) return;
+      let readPath = findFileDisplayPath(identity.displayId) ?? path;
       const startedAt = performance.now();
       markDocumentOpenTrace(transitionId, 'content:load-start', {
-        path,
+        path: readPath,
         isolatedSession,
       });
 
       // Switch the active buffer up-front so any in-flight writes from
       // the previous document that resolve after this point still
       // target the right buffer.
-      if (!isolatedSession) setActiveDocumentPath(identity, path);
+      if (!isolatedSession) setActiveDocumentPath(identity, readPath);
       captureLatestDocumentContent(identity);
       const startRevision = getBuffer(identity)?.capturedRevision ?? 0;
       const currentLoadId = ++counter.current;
+      const restartAfterPathMove = () => {
+        const latestPath = findFileDisplayPath(identity.displayId);
+        if (!latestPath || canonicalPath(latestPath) === canonicalPath(readPath)) return false;
+        // The pathname is part of the durable address, while this editor and
+        // its buffer keep the same display identity across a rename. Restart
+        // against that address instead of applying an old-path read result.
+        void reloadDocumentRef.current?.(latestPath, options);
+        return true;
+      };
       if (skipContentLoad) {
         setState((prev) => ({
           ...prev,
@@ -200,6 +250,7 @@ export function useDocumentContent({
           isLoaded: false,
           isLoading: false,
           error: null,
+          errorKind: null,
           isScrolled: false,
           charCount: 0,
           tokenCount: 0,
@@ -211,20 +262,20 @@ export function useDocumentContent({
       }
       const session = getDocumentSession(identity);
       if ((options?.showLoading ?? true) && session.loaded && session.buffer) {
-        applyLoadedContent(identity.path, session.buffer.lastSavedContent, { preservePending: true });
+        applyLoadedContent(readPath, session.buffer.lastSavedContent, { preservePending: true });
         if (!isolatedSession && transitionId !== null) useDocumentStore.getState().finishDocumentTransition(transitionId);
         return;
       }
-      const stagedContent = consumeStagedDocumentSnapshot(identity, path);
+      const stagedContent = consumeStagedDocumentSnapshot(identity, readPath);
       if (stagedContent !== null) {
         // The just-committed create result is already authoritative. There
         // cannot be a recovery draft from this new note before its first edit.
         if (currentLoadId !== counter.current || !isFileDisplayIdLive(identity.displayId)) return;
         if (session.loaded && session.buffer) {
-          applyLoadedContent(session.identity.path, session.buffer.lastSavedContent, { preservePending: true });
+          applyLoadedContent(readPath, session.buffer.lastSavedContent, { preservePending: true });
           return;
         }
-        applyLoadedContent(path, stagedContent, { preservePending: true });
+        applyLoadedContent(readPath, stagedContent, { preservePending: true });
         logOpenDocPerf('reloadDocument:staged', startedAt, {
           transitionId,
           bytes: stagedContent.length,
@@ -240,6 +291,7 @@ export function useDocumentContent({
           isLoading: true,
           isLoaded: false,
           error: null,
+          errorKind: null,
           isScrolled: false,
           isNewlyCreated: false,
         }));
@@ -248,13 +300,12 @@ export function useDocumentContent({
       try {
         logOpenDocPerf('reloadDocument:start', startedAt, {
           transitionId,
-          path,
+          path: readPath,
         });
         const readStartedAt = performance.now();
         markDocumentOpenTrace(transitionId, 'ipc:read-start', {
-          path,
+          path: readPath,
         });
-        let readPath = path;
         const read = () => localDocumentOperations.read({ path: readPath, scopePath: externalScopePath });
         const opening = options?.showLoading ?? true;
         const operation = opening && session.openingRead?.path === readPath
@@ -274,28 +325,38 @@ export function useDocumentContent({
           bytes: fullContent?.length ?? 0,
         });
 
+        if (currentLoadId !== counter.current) return;
+        if (restartAfterPathMove()) return;
+        if (!isFileDisplayIdLive(identity.displayId)) return;
+
         if (fullContent === null || fullContent === undefined) {
-          if (currentLoadId !== counter.current) return;
+          session.loaded = false;
           const language = getCurrentAppLanguage();
-          setState((prev) => ({ ...prev, isLoading: false, error: translate(language, 'document.load.fileNotFound') }));
+          setState((prev) => ({
+            ...prev,
+            isLoading: false,
+            error: translate(language, 'document.load.fileNotFound'),
+            errorKind: 'missing-note',
+          }));
           if (!isolatedSession && transitionId !== null) {
-            useDocumentStore.getState().finishDocumentTransition(transitionId);
+            useDocumentStore.getState().finishDocumentTransition(transitionId, 'unavailable');
           }
           return;
         }
 
-        if (currentLoadId !== counter.current || !isFileDisplayIdLive(identity.displayId)) return;
         if ((options?.showLoading ?? true) && session.loaded && session.buffer) {
-          applyLoadedContent(session.identity.path, session.buffer.lastSavedContent, { preservePending: true });
+          applyLoadedContent(readPath, session.buffer.lastSavedContent, { preservePending: true });
           return;
         }
-        markDocumentOpenTrace(transitionId, 'recovery:read-start', { path });
+        markDocumentOpenTrace(transitionId, 'recovery:read-start', { path: readPath });
         const recovery = (options?.showLoading ?? true)
-          ? await readOpeningRecovery() : await readRecoveryDraft(identity).catch(() => null);
+          ? await readRecoveryDraftWithin(readOpeningRecovery(readPath))
+          : await readRecoveryDraftWithin(readRecoveryDraft({ ...identity, path: readPath }));
         markDocumentOpenTrace(transitionId, 'recovery:read-end', {
             found: recovery !== null,
         });
         if (currentLoadId !== counter.current || !isFileDisplayIdLive(identity.displayId)) return;
+        if (restartAfterPathMove()) return;
         captureLatestDocumentContent(identity);
         const liveBuffer = getBuffer(identity);
         if (options?.showLoading === false && liveBuffer
@@ -305,6 +366,7 @@ export function useDocumentContent({
             // through the same conditional merge used by normal saves.
             if (await protectDocumentDraft(identity, readPath, 'autosave')) {
               if (currentLoadId !== counter.current || !isFileDisplayIdLive(identity.displayId)) return;
+              if (restartAfterPathMove()) return;
               captureLatestDocumentContent(identity);
               void saveDocumentContent({
                 identity, path: readPath, content: getBuffer(identity)?.content ?? liveBuffer.content,
@@ -317,7 +379,7 @@ export function useDocumentContent({
         // Another view may have finished the same opening and accepted input
         // while this view was still reading recovery. Adopt that live buffer.
         if ((options?.showLoading ?? true) && session.loaded && session.buffer) {
-          applyLoadedContent(session.identity.path, session.buffer.lastSavedContent, { preservePending: true });
+          applyLoadedContent(readPath, session.buffer.lastSavedContent, { preservePending: true });
           return;
         }
         applyLoadedContent(readPath, fullContent, {
@@ -333,11 +395,21 @@ export function useDocumentContent({
         }
       } catch (err) {
         if (currentLoadId !== counter.current) return;
+        if (restartAfterPathMove()) return;
+        session.loaded = false;
         const language = getCurrentAppLanguage();
-        setState((prev) => ({ ...prev, isLoading: false, error: readFailureMessage(err, language) }));
+        setState((prev) => ({
+          ...prev,
+          isLoading: false,
+          error: readFailureMessage(err, language),
+          errorKind: isMissingDocumentError(err) ? 'missing-note' : 'error',
+        }));
         logOpenDocPerf('reloadDocument:error', startedAt, {
           transitionId,
         });
+        if (!isolatedSession && transitionId !== null) {
+          useDocumentStore.getState().finishDocumentTransition(transitionId, 'unavailable');
+        }
       } finally {
         if (currentLoadId === counter.current && !isolatedSession && transitionId !== null) {
           useDocumentStore.getState().finishDocumentTransition(transitionId);
@@ -346,6 +418,7 @@ export function useDocumentContent({
     },
     [applyLoadedContent, identity, isolatedSession, externalScopePath, readOpeningRecovery, skipContentLoad, transitionId],
   );
+  reloadDocumentRef.current = reloadDocument;
 
   return {
     state,
diff --git a/app/flowix-web/features/document/components/session/use-external-document-change-watch.ts b/app/flowix-web/features/document/components/session/use-external-document-change-watch.ts
index 20d0f245e..af0fc14f6 100644
--- a/app/flowix-web/features/document/components/session/use-external-document-change-watch.ts
+++ b/app/flowix-web/features/document/components/session/use-external-document-change-watch.ts
@@ -1,20 +1,19 @@
-import { captureLatestDocumentContent, reconcileUnsavedExternalDocumentChange } from '../../store/document-session-service';
+import {
+  captureLatestDocumentContent,
+  hasDocumentUnsavedChanges,
+  protectDocumentDraft,
+  reconcileUnsavedExternalDocumentChange,
+  scheduleDocumentSessionSave,
+} from '../../store/document-session-service';
 import { useEffect } from 'react';
-import { getCurrentWindow } from '@platform/tauri/window';
 
-import { hasDocumentUnsavedChanges } from '@features/document/store/document-session-service';
-import type { DocumentIdentity } from '@features/document/store/document-identity';
+import { documentIdentityKey, type DocumentIdentity } from '@features/document/store/document-identity';
 import { translate } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 import { toast } from '@/lib/toast';
 import { canonicalPath } from '@/lib/path';
-import { consumeExpectedExternalDocumentEvent } from '@features/document/store/external-document-operation';
-import { createLogger } from '@/lib/logger';
-import { onceUnlisten } from '@platform/tauri/event-bus';
-import {
-  windows,
-  type ExternalDocumentChangedEvent,
-} from '@platform/tauri/client';
+import { findFileDisplayPath } from '@/lib/file-display-registry';
+import { subscribeExternalDocumentChanges } from '@features/document/store/external-document-watch';
 
 interface UseExternalDocumentChangeWatchOptions {
   filePath: string;
@@ -24,8 +23,6 @@ interface UseExternalDocumentChangeWatchOptions {
   reloadDocument: (path: string, options?: { preservePending?: boolean; showLoading?: boolean }) => Promise<void>;
 }
 
-const logger = createLogger('external-document-watch');
-
 export function useExternalDocumentChangeWatch({
   filePath,
   identity,
@@ -37,69 +34,48 @@ export function useExternalDocumentChangeWatch({
     if (!filePath) return;
 
     let disposed = false;
-    let leaseId: string | null = null;
-    let unlisten: (() => void) | null = null;
     const currentPath = canonicalPath(filePath);
+    const stillWatchingCurrentPath = () => !disposed
+      && canonicalPath(findFileDisplayPath(identity.displayId) ?? filePath) === currentPath;
 
-    void (async () => {
-      logger.debug('registering', {
-        windowLabel: getCurrentWindow().label,
-      });
-      unlisten = onceUnlisten(await getCurrentWindow().listen<ExternalDocumentChangedEvent>(
-        'external-document-changed',
-        async ({ payload }) => {
-          logger.debug('change received', {
-            kind: payload.kind,
-            revision: payload.revision,
-            source: payload.source,
-            originWindowLabel: payload.originWindowLabel,
-            matchesCurrentDocument: canonicalPath(payload.path) === currentPath,
-          });
-          if (disposed || canonicalPath(payload.path) !== currentPath) return;
-          if (payload.source === 'user_edit' && payload.originWindowLabel === getCurrentWindow().label) return;
-          if (consumeExpectedExternalDocumentEvent(
-            payload.path,
-            payload.kind,
-            payload.revision,
-          )) return;
-          captureLatestDocumentContent(identity);
-          if (payload.kind === 'deleted') {
-            const language = getCurrentAppLanguage();
-            toast.warning(translate(language, 'document.external.changeWarning'), { duration: 5000 });
-            return;
-          }
-          if (hasDocumentUnsavedChanges(identity)) {
-            // The write boundary performs the shared diffy merge under the
-            // cross-process file lock. A real overlap surfaces the conflict UI.
-            await reconcileUnsavedExternalDocumentChange(identity, filePath, scopePath);
-            return;
-          }
-          clearSaveTimer();
-          await reloadDocument(filePath, { preservePending: false, showLoading: false });
-        },
-      ));
-      if (disposed) {
-        unlisten();
-        unlisten = null;
+    const identityKey = documentIdentityKey(identity);
+    const unsubscribe = subscribeExternalDocumentChanges(filePath, scopePath, async (payload, context) => {
+      if (disposed || !stillWatchingCurrentPath() || canonicalPath(payload.path) !== currentPath) return;
+      captureLatestDocumentContent(identity);
+      if (payload.kind === 'deleted') {
+        await context.runOnce('missing-warning', () => {
+          const language = getCurrentAppLanguage();
+          toast.warning(translate(language, 'document.external.changeWarning'), { duration: 5000 });
+        });
+        clearSaveTimer();
+        const protectedDraft = await context.runOnce(`protect-draft:${identityKey}`, () =>
+          protectDocumentDraft(identity, filePath, 'autosave').catch(() => false));
+        if (!protectedDraft) {
+          await context.runOnce(`schedule-save:${identityKey}`, () => scheduleDocumentSessionSave(identity));
+          return;
+        }
+        if (stillWatchingCurrentPath()) {
+          // Refresh the actual path state so the surface can offer retry
+          // and index cleanup. A missing file must not leave a stale editor
+          // looking ready after an external deletion.
+          await reloadDocument(filePath, { preservePending: true, showLoading: false });
+        }
         return;
       }
-      leaseId = await windows.watchExternalDocument(filePath, scopePath);
-      logger.debug('registered', {
-        leaseId,
-        windowLabel: getCurrentWindow().label,
-      });
-      if (disposed && leaseId) {
-        void windows.unwatchExternalDocument(leaseId);
-        leaseId = null;
+      if (hasDocumentUnsavedChanges(identity)) {
+        // The write boundary performs the shared diffy merge under the
+        // cross-process file lock. A real overlap surfaces the conflict UI.
+        await context.runOnce(`reconcile:${identityKey}`, () =>
+          reconcileUnsavedExternalDocumentChange(identity, filePath, scopePath));
+        return;
       }
-    })().catch((error) => {
-      if (!disposed) logger.warn('registration failed', { error });
+      clearSaveTimer();
+      await reloadDocument(filePath, { preservePending: false, showLoading: false });
     });
 
     return () => {
       disposed = true;
-      unlisten?.();
-      if (leaseId) void windows.unwatchExternalDocument(leaseId);
+      unsubscribe();
     };
   }, [filePath, identity, scopePath, clearSaveTimer, reloadDocument]);
 }
diff --git a/app/flowix-web/features/document/index.ts b/app/flowix-web/features/document/index.ts
index 7e8b47c32..ceb00bd8b 100644
--- a/app/flowix-web/features/document/index.ts
+++ b/app/flowix-web/features/document/index.ts
@@ -4,7 +4,7 @@ export { DocumentTitlebarWin } from '@features/document/components/document-titl
 export { LazyDocumentEditor } from '@features/document/components/lazy-document-editor';
 export { useDocumentCommands } from '@features/document/components/use-document-commands';
 export {
-  flushWorkspaceDocumentPath,
+  prepareWorkspaceDocumentLeave,
   getWorkspaceDocumentState,
   recordWorkspaceDocumentNavigation,
   type WorkspaceDocumentState,
diff --git a/app/flowix-web/features/document/properties/color-value-input.tsx b/app/flowix-web/features/document/properties/color-value-input.tsx
index c2715414a..b89376643 100644
--- a/app/flowix-web/features/document/properties/color-value-input.tsx
+++ b/app/flowix-web/features/document/properties/color-value-input.tsx
@@ -88,7 +88,7 @@ export function ColorValueInput({
       </DropdownMenuTrigger>
       <DropdownMenuContent
         align="start"
-        className={cn('min-w-[200px] rounded-xl border-[var(--border-popup)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' ? 'p-1' : 'p-2')}
+        className={cn('min-w-[200px] rounded-xl border-[var(--border-popup)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' ? '!z-[170] p-1' : 'p-2')}
       >
         <div className="mb-2 flex items-center justify-between gap-2">
           <span className="text-xs text-[var(--muted-foreground)]">{t('document.properties.type.color')}</span>
diff --git a/app/flowix-web/features/document/properties/frontmatter-model.ts b/app/flowix-web/features/document/properties/frontmatter-model.ts
index e825e1253..d53dfa8fb 100644
--- a/app/flowix-web/features/document/properties/frontmatter-model.ts
+++ b/app/flowix-web/features/document/properties/frontmatter-model.ts
@@ -8,7 +8,9 @@ import { isValidTagPath } from '@/lib/tag-path';
 import { NOTE_COLORS } from '@/types/note-item';
 
 export const FRONTMATTER_RE = /^\uFEFF?(?:[ \t]*\r?\n)*---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-export const SYSTEM_FRONTMATTER_KEYS = new Set(['flowix_key', 'key', PROPERTY_TYPES_KEY]);
+// Only editor metadata is hidden. Historical memo identity fields are ordinary
+// YAML properties and are no longer interpreted by note indexing.
+export const SYSTEM_FRONTMATTER_KEYS = new Set([PROPERTY_TYPES_KEY]);
 
 const FLOWIX_COLOR_SET = new Set<string>(NOTE_COLORS);
 
@@ -358,7 +360,7 @@ export function updateVisibleFrontmatterProperty(
   if (SYSTEM_FRONTMATTER_KEYS.has(nextKey)) {
     throw new FrontmatterPropertyError(
       'reserved-key',
-      'The system key property is managed by Flowix',
+      'This property is managed by the editor',
     );
   }
 
diff --git a/app/flowix-web/features/document/properties/icon-value-input.tsx b/app/flowix-web/features/document/properties/icon-value-input.tsx
index dccf58c28..45b190501 100644
--- a/app/flowix-web/features/document/properties/icon-value-input.tsx
+++ b/app/flowix-web/features/document/properties/icon-value-input.tsx
@@ -52,11 +52,14 @@ export function IconValueInput({
             <img
               src={selected.src}
               alt=""
-              className="h-5 w-5 shrink-0 object-contain"
+              className={cn('h-5 w-5 shrink-0 object-contain', variant === 'table' && 'multidimensional-table__icon-value')}
               draggable={false}
             />
           ) : (
-            <span className="h-5 w-5 shrink-0 rounded-md border border-dashed border-[var(--border)]" />
+            <span className={cn(
+              'h-5 w-5 shrink-0 rounded-md border border-dashed',
+              variant === 'table' ? 'multidimensional-table__icon-placeholder' : 'border-[var(--border)]',
+            )} />
           )}
           {selected && !disabled && (
             <span
@@ -74,7 +77,7 @@ export function IconValueInput({
       <PopoverContent
         align="start"
         sideOffset={6}
-        className={cn('z-[150] w-[280px] rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' ? 'p-1' : 'p-2')}
+        className={cn('z-[150] w-[280px] rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' ? '!z-[170] p-1' : 'p-2')}
       >
         <div className="max-h-[240px] overflow-y-auto [scrollbar-gutter:stable]">
           <div className="grid grid-cols-5 gap-1">
diff --git a/app/flowix-web/features/document/properties/multi-select-value-input.tsx b/app/flowix-web/features/document/properties/multi-select-value-input.tsx
index ee29f4b22..551ebb8d6 100644
--- a/app/flowix-web/features/document/properties/multi-select-value-input.tsx
+++ b/app/flowix-web/features/document/properties/multi-select-value-input.tsx
@@ -103,7 +103,7 @@ export function MultiSelectValueInput({
         </DropdownMenuTrigger>
         <DropdownMenuContent
           align="start"
-          className="min-w-[200px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]"
+          className={cn('min-w-[200px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' && '!z-[170]')}
         >
           {normalizedOptions.length === 0 ? (
             <div className="px-3 py-2 text-xs text-[var(--muted-foreground)]">
diff --git a/app/flowix-web/features/document/properties/property-type-metadata.ts b/app/flowix-web/features/document/properties/property-type-metadata.ts
index 82e257462..b3202cf79 100644
--- a/app/flowix-web/features/document/properties/property-type-metadata.ts
+++ b/app/flowix-web/features/document/properties/property-type-metadata.ts
@@ -23,7 +23,7 @@ export function patchPropertyTypes(map: YAMLMap, changes: Record<string, Propert
   const forced = new Set(forceNonPresetKeys.map(canonicalizePropertyKey));
   for (const [rawKey, kind] of Object.entries(changes)) {
     const key = canonicalizePropertyKey(rawKey);
-    if (kind === undefined || key === PROPERTY_TYPES_KEY || key === 'key' || key === 'flowix_key') continue;
+    if (kind === undefined || key === PROPERTY_TYPES_KEY) continue;
     // Text is the default fallback and Date is inferred from the value, so
     // neither is worth persisting. Declarations for them are removed even when
     // forced: the value alone recovers the same kind.
@@ -46,7 +46,7 @@ export function patchPropertyTypes(map: YAMLMap, changes: Record<string, Propert
 export function backfillPropertyTypes(map: YAMLMap, data: Record<string, unknown>, skipKeys: readonly string[] = [], forceNonPresetKeys: readonly string[] = []): void {
   const declared = readPropertyTypes(data[PROPERTY_TYPES_KEY]);
   const changes: Record<string, PropertyKind | null> = {};
-  const excluded = new Set(['flowix_key', 'key', 'flowix_plugin', PROPERTY_TYPES_KEY, ...skipKeys]);
+  const excluded = new Set(['flowix_plugin', PROPERTY_TYPES_KEY, ...skipKeys]);
   const existing = map.get(PROPERTY_TYPES_KEY, true);
   if (isMap(existing)) {
     for (const pair of existing.items) {
diff --git a/app/flowix-web/features/document/properties/select-value-input.tsx b/app/flowix-web/features/document/properties/select-value-input.tsx
index bdaffea07..893674536 100644
--- a/app/flowix-web/features/document/properties/select-value-input.tsx
+++ b/app/flowix-web/features/document/properties/select-value-input.tsx
@@ -63,7 +63,7 @@ export function SelectValueInput({
       </SelectTrigger>
       <SelectContent
         align="start"
-        className="min-w-[160px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]"
+        className={cn('min-w-[160px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]', variant === 'table' && '!z-[170]')}
       >
         {normalizedOptions.length === 0 ? (
           <div className="px-3 py-2 text-xs text-[var(--muted-foreground)]">
diff --git a/app/flowix-web/features/document/public/heading-navigation-api.ts b/app/flowix-web/features/document/public/heading-navigation-api.ts
new file mode 100644
index 000000000..aaeec5e68
--- /dev/null
+++ b/app/flowix-web/features/document/public/heading-navigation-api.ts
@@ -0,0 +1,5 @@
+/** Public heading navigation for callers opening a document in another surface. */
+export {
+  locationViewId,
+  publishHeadingAnchorRequest,
+} from '@features/document/use-cases/heading-anchor-publish';
diff --git a/app/flowix-web/features/document/public/path-properties.ts b/app/flowix-web/features/document/public/path-properties.ts
index 2cb0b3545..805187fe9 100644
--- a/app/flowix-web/features/document/public/path-properties.ts
+++ b/app/flowix-web/features/document/public/path-properties.ts
@@ -19,11 +19,11 @@ export function patchDocumentProperties(content: string, properties: Record<stri
   const previousData = document.toJS() ?? {};
   const previousTypes = readPropertyTypes(previousData[PROPERTY_TYPES_KEY]);
   for (const [key, value] of Object.entries(properties)) {
-    if (key === 'flowix_key' || key === 'key' || key === PROPERTY_TYPES_KEY) throw new Error('Identity properties cannot be generated');
+    if (key === PROPERTY_TYPES_KEY) throw new Error('Editor metadata cannot be generated');
     document.set(key, value);
   }
   for (const key of removedProperties) {
-    if (key === 'flowix_key' || key === 'key' || key === PROPERTY_TYPES_KEY) throw new Error('Identity properties cannot be removed');
+    if (key === PROPERTY_TYPES_KEY) throw new Error('Editor metadata cannot be removed');
     document.delete(key);
   }
   const typeChanges: Record<string, PropertyKind | null | undefined> = {
diff --git a/app/flowix-web/features/document/public/shutdown-api.ts b/app/flowix-web/features/document/public/shutdown-api.ts
new file mode 100644
index 000000000..b10aef49a
--- /dev/null
+++ b/app/flowix-web/features/document/public/shutdown-api.ts
@@ -0,0 +1,8 @@
+import { flushAllDocumentSessions } from '../store/document-session-service';
+import { listDocumentSessions } from '../store/document-runtime-session';
+import { documentCommitDiagnostics } from '../store/document-commit-queue';
+
+export const flushDocumentsForShutdown = flushAllDocumentSessions;
+export function documentShutdownDiagnostics() {
+  return { sessions: listDocumentSessions().length, ...documentCommitDiagnostics() };
+}
diff --git a/app/flowix-web/features/document/public/startup-api.ts b/app/flowix-web/features/document/public/startup-api.ts
index 3cc7e27f0..dfb579527 100644
--- a/app/flowix-web/features/document/public/startup-api.ts
+++ b/app/flowix-web/features/document/public/startup-api.ts
@@ -1,18 +1,17 @@
 import { useDocumentStore } from '@features/document/store/document-store';
 
 /** Wait for the restored document's content load to finish before disk maintenance starts. */
-export function waitForInitialDocumentLoad(timeoutMs = 60_000): Promise<'settled' | 'skipped' | 'superseded' | 'timeout'> {
+export function waitForInitialDocumentLoad(timeoutMs = 60_000): Promise<'settled' | 'unavailable' | 'skipped' | 'timeout'> {
   const initial = useDocumentStore.getState();
   if (!initial.isDocumentTransitioning) {
-    return Promise.resolve(initial.activeExternalSession ? 'settled' : 'skipped');
+    if (!initial.activeExternalSession) return Promise.resolve('skipped');
+    return Promise.resolve(initial.documentLoadOutcome === 'unavailable' ? 'unavailable' : 'settled');
   }
-  const transitionId = initial.documentTransitionId;
-
   return new Promise((resolve) => {
     let finished = false;
     let unsubscribe = () => {};
     let timer: ReturnType<typeof setTimeout>;
-    const finish = (result: 'settled' | 'superseded' | 'timeout') => {
+    const finish = (result: 'settled' | 'unavailable' | 'skipped' | 'timeout') => {
       if (finished) return;
       finished = true;
       clearTimeout(timer);
@@ -20,13 +19,19 @@ export function waitForInitialDocumentLoad(timeoutMs = 60_000): Promise<'settled
       resolve(result);
     };
     unsubscribe = useDocumentStore.subscribe((state) => {
-      if (state.documentTransitionId !== transitionId) finish('superseded');
-      else if (!state.isDocumentTransitioning) finish('settled');
+      // A user action can replace the restored target while it is loading.
+      // Wait for the latest transition to settle before releasing startup.
+      if (!state.isDocumentTransitioning) {
+        finish(!state.activeExternalSession ? 'skipped'
+          : state.documentLoadOutcome === 'unavailable' ? 'unavailable' : 'settled');
+      }
     });
     timer = setTimeout(() => finish('timeout'), timeoutMs);
     // The transition may finish between the first snapshot and subscribe().
     const current = useDocumentStore.getState();
-    if (current.documentTransitionId !== transitionId) finish('superseded');
-    else if (!current.isDocumentTransitioning) finish('settled');
+    if (!current.isDocumentTransitioning) {
+      finish(!current.activeExternalSession ? 'skipped'
+        : current.documentLoadOutcome === 'unavailable' ? 'unavailable' : 'settled');
+    }
   });
 }
diff --git a/app/flowix-web/features/document/public/workspace-api.ts b/app/flowix-web/features/document/public/workspace-api.ts
index 92c760e8e..2d2130091 100644
--- a/app/flowix-web/features/document/public/workspace-api.ts
+++ b/app/flowix-web/features/document/public/workspace-api.ts
@@ -7,15 +7,15 @@ import {
   type MediaHistoryEntry,
 } from '@features/document/store/document-history-store';
 import {
-  flushDocumentPath,
+  prepareDocumentLeave,
+  saveDocumentPath,
   rebaseActiveDocumentPath,
 } from '@features/document/store/document-session-service';
-import { findFileDisplayId, rebaseFileDisplayPath } from '@/lib/file-display-registry';
+import { findFileDisplayId, findFileDisplayPath, rebaseFileDisplayPath } from '@/lib/file-display-registry';
 import { canonicalPath } from '@/lib/path';
 import type { DocumentIdentity } from '@features/document/store/document-identity';
 import { rebaseRecoveryDraftPath } from '@features/document/store/recovery-draft-store';
-import { waitForSaveQueue } from '@features/document/store/save-queue';
-import { documentIdentityKey } from '@features/document/store/document-identity';
+export { rebaseStoredRecoveryDraftPaths } from '@features/document/store/recovery-draft-store';
 import { listDocumentSessions } from '@features/document/store/document-runtime-session';
 import { applyLoadedDocumentContent, captureLatestDocumentContent, hasDocumentUnsavedChanges } from '@features/document/store/document-session-service';
 import { subscribeDocumentBufferChanges } from '@features/document/store/buffer-registry';
@@ -53,11 +53,6 @@ export function subscribeWorkspaceDocumentSaves(listener: () => void): () => voi
   });
 }
 
-/** Navigation waits for document persistence without knowing queue keys. */
-export function waitForWorkspaceDocumentSaves(identity: DocumentIdentity): Promise<boolean> {
-  return waitForSaveQueue(documentIdentityKey(identity));
-}
-
 export function getWorkspaceDocumentPaths(): string[] {
   const state = useDocumentStore.getState();
   return [state.activeExternalSession?.fileIdentity.path]
@@ -103,13 +98,17 @@ export function recordWorkspaceDocumentNavigation(
 export function replaceWorkspaceDocumentPath(
   identity: DocumentIdentity,
   path: string,
-): void {
+): boolean {
   const previous = canonicalPath(identity.path);
   const next = canonicalPath(path);
-  if (!previous || !next || previous === next) return;
-  if (!rebaseWorkspaceDocumentPath(identity, next)) return;
+  if (!previous || !next) return false;
+  // A command response and its broadcast can confirm the same move. Allow
+  // callers to finish projections, but never rebase a display already at C.
+  if (findFileDisplayPath(identity.displayId) === next) return true;
+  if (!rebaseWorkspaceDocumentPath(identity, next)) return false;
   useDocumentStore.getState().replaceActiveExternalPath(identity.displayId, next);
   useDocumentHistoryStore.getState().replaceFilePath(previous, next);
+  return true;
 }
 
 /** Rebase the shared live document identity after either a Memo or file rename. */
@@ -129,12 +128,21 @@ export function rebaseWorkspaceDocumentPath(
   return true;
 }
 
-export async function flushWorkspaceDocumentPath(
+export async function prepareWorkspaceDocumentLeave(
+  identity: DocumentIdentity,
+  path: string,
+  scopePath?: string | null,
+): Promise<boolean> {
+  return prepareDocumentLeave(identity, path, scopePath);
+}
+
+/** Destructive writes must wait until the current editor body and title are durable. */
+export async function saveWorkspaceDocumentPath(
   identity: DocumentIdentity,
   path: string,
   scopePath?: string | null,
 ): Promise<boolean> {
-  return flushDocumentPath(identity, path, scopePath);
+  return saveDocumentPath(identity, path, scopePath);
 }
 
 export type {
@@ -147,6 +155,11 @@ export function getWorkspaceDocumentHistory(): DocumentHistoryEntry[] {
   const state = useDocumentHistoryStore.getState();
   return [...state.backStack, ...state.forwardStack];
 }
+
+/** History remains addressable even when no live display owns its old path. */
+export function replaceWorkspaceDocumentHistoryPath(previousPath: string, path: string): void {
+  useDocumentHistoryStore.getState().replaceFilePath(previousPath, path);
+}
 export function subscribeWorkspaceDocumentHistory(listener: () => void): () => void {
   return useDocumentHistoryStore.subscribe(listener);
 }
diff --git a/app/flowix-web/features/document/store/document-editor-view-store.ts b/app/flowix-web/features/document/store/document-editor-view-store.ts
index 247356f33..fca1a8082 100644
--- a/app/flowix-web/features/document/store/document-editor-view-store.ts
+++ b/app/flowix-web/features/document/store/document-editor-view-store.ts
@@ -1,6 +1,6 @@
 import { create } from 'zustand';
 
-import type { WorkspaceHostId } from '@features/workspace/store/workspace-focus-store';
+import type { WorkspaceHostId } from '@features/workspace/public/host-api';
 import { subscribeFileDisplayRelease } from '@/lib/file-display-registry';
 import {
   documentIdentityKey,
diff --git a/app/flowix-web/features/document/store/document-history-store.ts b/app/flowix-web/features/document/store/document-history-store.ts
index 9f278ea32..e0a0c78ee 100644
--- a/app/flowix-web/features/document/store/document-history-store.ts
+++ b/app/flowix-web/features/document/store/document-history-store.ts
@@ -4,7 +4,7 @@ import type { CollectionDisplayDescriptor } from '@/lib/collection-display-regis
 import { create } from 'zustand';
 import { canonicalPath, fileLocatorKey } from '@/lib/path';
 import { canonicalUrl } from '@/lib/url';
-import type { DocumentListFilters, DocumentListScope } from '@features/workspace/store/work-column-target';
+import type { LegacyFolderListTarget } from '@features/workspace/model/legacy-folder-list';
 
 type ExternalHistoryEntry = {
   kind: 'external';
@@ -13,13 +13,7 @@ type ExternalHistoryEntry = {
   openedAt: number;
 };
 
-export type DocumentListHistoryEntry = {
-  kind: 'document-list';
-  displayId: string;
-  scope: DocumentListScope;
-  filters: DocumentListFilters;
-  openedAt: number;
-};
+export type LegacyFolderListHistoryEntry = LegacyFolderListTarget & { openedAt: number };
 
 export type AgentConversationHistoryEntry = {
   kind: 'agent-conversation';
@@ -47,7 +41,7 @@ export type CollectionHistoryEntry = CollectionDisplayDescriptor & { kind: 'coll
 
 export type DocumentHistoryEntry =
   | CollectionHistoryEntry
-  | DocumentListHistoryEntry
+  | LegacyFolderListHistoryEntry
   | ExternalHistoryEntry
   | AgentConversationHistoryEntry
   | WebHistoryEntry
diff --git a/app/flowix-web/features/document/store/document-runtime-session.ts b/app/flowix-web/features/document/store/document-runtime-session.ts
index 9e7afc8f2..e4459089d 100644
--- a/app/flowix-web/features/document/store/document-runtime-session.ts
+++ b/app/flowix-web/features/document/store/document-runtime-session.ts
@@ -24,7 +24,7 @@ export interface DocumentRuntimeSession {
   capturing: boolean;
   recoveryRevision: number;
   openingRead?: { path: string; promise: Promise<string | null> };
-  openingRecovery?: Promise<RecoveryDraft | null>;
+  openingRecovery?: { path: string; promise: Promise<RecoveryDraft | null> };
   title?: MemoTitleSession;
   /** Recovery-only input; never the displayed title or an automatic rename intent. */
   restoredTitle?: { draft: string; filename: string };
diff --git a/app/flowix-web/features/document/store/document-session-service.ts b/app/flowix-web/features/document/store/document-session-service.ts
index 5073d0339..147b92d3e 100644
--- a/app/flowix-web/features/document/store/document-session-service.ts
+++ b/app/flowix-web/features/document/store/document-session-service.ts
@@ -120,14 +120,17 @@ export async function protectDocumentDraft(
   path: string,
   reason: 'autosave' | 'save-timeout' | 'save-error' | 'shutdown',
 ): Promise<boolean> {
+  // A filesystem rename keeps the runtime display identity and may happen
+  // while an external-change or shutdown callback is preparing this checkpoint.
+  const recoveryPath = findFileDisplayPath(identity.displayId) ?? path;
   const buffer = getOrCreateBuffer(identity);
   const title = getTitleDraft(identity.displayId);
   if (!hasUnsavedLocalChanges(identity) && !title) return true;
   const bodyRevision = buffer.capturedRevision;
   const revision = getDocumentSession(identity).recoveryRevision;
   const protectedByDraft = await waitWithTimeout(persistRecoveryDraft({
-    identity: { ...identity, path: canonicalPath(path) },
-    originalPath: canonicalPath(path),
+    identity: { ...identity, path: canonicalPath(recoveryPath) },
+    originalPath: canonicalPath(recoveryPath),
     revision,
     bodyRevision,
     title: title ?? undefined,
@@ -159,6 +162,11 @@ export async function reconcileUnsavedExternalDocumentChange(
   const protectedDraft = await protectDocumentDraft(identity, path, 'autosave').catch(() => false);
   captureLatestDocumentContent(identity);
   if (!hasUnsavedLocalChanges(identity)) return;
+  const latestPath = findFileDisplayPath(identity.displayId);
+  if (!latestPath || canonicalPath(latestPath) !== canonicalPath(path)) {
+    if (latestPath) scheduleDocumentSessionSave(identity);
+    return;
+  }
   if (!protectedDraft || buffer.capturedRevision !== revision) {
     scheduleDocumentSessionSave(identity);
     return;
@@ -316,14 +324,6 @@ export async function saveDocumentContent({
   return flushDocument(identity, path, { scopePath, force, ...callbacks });
 }
 
-export function flushDocumentPath(
-  identity: DocumentIdentity,
-  path: string,
-  scopePath: string | null = null,
-): Promise<boolean> {
-  return prepareDocumentLeave(identity, path, scopePath);
-}
-
 /** Wait until the current editor buffer is on disk before reading it for a snapshot or preview. */
 export async function saveDocumentPath(
   identity: DocumentIdentity,
@@ -431,32 +431,72 @@ subscribeDocumentBufferChanges((identity) => {
 
 /** Called by the desktop close/quit handshake, not fire-and-forget unload. */
 export async function flushAllDocumentSessions(): Promise<boolean> {
-  const registrations = listDocumentSessions().flatMap(session => {
-    const adapter = [...session.adapters].slice(-1)[0] ?? session.retainedAdapter;
-    return adapter ? [{ identity: session.identity, adapter }] : [];
-  });
-  const results = await Promise.all(registrations.map(async ({ identity, adapter }) => {
-    const key = documentIdentityKey(identity);
-    cancelDocumentCapture(key);
-    captureLatestDocumentContent(identity);
-    adapter.capture();
-    const titleSave = flushTitleDraft(identity.displayId);
-    const bodySave = flushDocument(identity, adapter.path(), { scopePath: adapter.scopePath });
-    const protectedDraft = protectDocumentDraft(identity, adapter.path(), 'shutdown');
-    const result = await waitWithTimeout(Promise.all([titleSave, bodySave, waitForDocumentCommits(key)])
-      .then(values => values.every(Boolean)), 5_000);
-    captureLatestDocumentContent(identity);
-    if (result === true && !hasUnsavedLocalChanges(identity) && !hasTitleDraft(identity.displayId)) return true;
-    // A timed-out mutation may have renamed the file. Do not close the process
-    // until its outcome is known, even when a recovery checkpoint exists.
-    if (hasDocumentCommit(key)) return false;
-    if (await waitWithTimeout(protectedDraft, 3_000) !== true) return false;
-    const protectedLatest = await waitWithTimeout(protectDocumentDraft(identity, adapter.path(), 'shutdown'), 3_000);
-    captureLatestDocumentContent(identity);
-    const buffer = getDocumentBuffer(identity);
-    return protectedLatest && buffer.durableRevision >= buffer.capturedRevision
-      && isTitleProtected(identity.displayId) && !hasDocumentCommit(key);
-  }));
-  const recoverySettled = await waitWithTimeout(flushRecoveryOperations(), 3_000);
-  return results.every(Boolean) && recoverySettled === true && documentCommitDiagnostics().active === 0;
+  // The user can still edit and open a document while a close handshake is
+  // waiting for I/O. Flush the current owners, then make one bounded pass for
+  // sessions or adapters that appeared during that wait. If the workspace is
+  // still changing after that, keep the window open and let the user retry.
+  for (let pass = 0; pass < 2; pass += 1) {
+    const sessionsAtStart = listDocumentSessions();
+    const ownersAtStart = new Map(sessionsAtStart.map(session => [session.identity.displayId, {
+      adapter: [...session.adapters].slice(-1)[0] ?? session.retainedAdapter,
+      captures: new Set(session.captures),
+    }] as const));
+    const registrations = sessionsAtStart.flatMap(session => {
+      const adapter = [...session.adapters].slice(-1)[0] ?? session.retainedAdapter;
+      return adapter ? [{ identity: session.identity, adapter }] : [];
+    });
+    const results = await Promise.all(registrations.map(async ({ identity, adapter }) => {
+      const key = documentIdentityKey(identity);
+      cancelDocumentCapture(key);
+      captureLatestDocumentContent(identity);
+      adapter.capture();
+      const titleSave = flushTitleDraft(identity.displayId);
+      const bodySave = flushDocument(identity, adapter.path(), { scopePath: adapter.scopePath });
+      const protectedDraft = protectDocumentDraft(identity, adapter.path(), 'shutdown');
+      const result = await waitWithTimeout(Promise.all([titleSave, bodySave, waitForDocumentCommits(key)])
+        .then(values => values.every(Boolean)), 5_000);
+      captureLatestDocumentContent(identity);
+      if (result === true && !hasUnsavedLocalChanges(identity) && !hasTitleDraft(identity.displayId)) return true;
+      // A timed-out mutation may have renamed the file. Do not close the process
+      // until its outcome is known, even when a recovery checkpoint exists.
+      if (hasDocumentCommit(key)) return false;
+      if (await waitWithTimeout(protectedDraft, 3_000) !== true) return false;
+      const protectedLatest = await waitWithTimeout(protectDocumentDraft(identity, adapter.path(), 'shutdown'), 3_000);
+      captureLatestDocumentContent(identity);
+      const buffer = getDocumentBuffer(identity);
+      return protectedLatest && buffer.durableRevision >= buffer.capturedRevision
+        && isTitleProtected(identity.displayId) && !hasDocumentCommit(key);
+    }));
+    if (!results.every(Boolean)) return false;
+
+    const recoverySettled = await waitWithTimeout(flushRecoveryOperations(), 3_000);
+    if (recoverySettled !== true) return false;
+
+    const sessionsNow = listDocumentSessions();
+    const newOwnerAppeared = sessionsNow.some(session => {
+      const adapter = [...session.adapters].slice(-1)[0] ?? session.retainedAdapter;
+      const initial = ownersAtStart.get(session.identity.displayId);
+      if (!initial) return Boolean(adapter || session.captures.size);
+      if (adapter && initial.adapter !== adapter) return true;
+      return [...session.captures].some(capture => !initial.captures.has(capture));
+    });
+    const hasUnretainedWork = sessionsNow.some(session => {
+      const buffer = getBuffer(session.identity);
+      const bodyNeedsProtection = Boolean(buffer
+        && hasUnsavedLocalChanges(session.identity)
+        && buffer.durableRevision < buffer.capturedRevision);
+      const titleNeedsProtection = hasTitleDraft(session.identity.displayId)
+        && !isTitleProtected(session.identity.displayId);
+      return bodyNeedsProtection || titleNeedsProtection;
+    });
+    const diagnostics = documentCommitDiagnostics();
+    const persistenceStillActive = diagnostics.active > 0 || diagnostics.pending > 0 || diagnostics.clocks > 0;
+    if (newOwnerAppeared || hasUnretainedWork || persistenceStillActive) {
+      if (pass === 0) continue;
+      return false;
+    }
+
+    return true;
+  }
+  return false;
 }
diff --git a/app/flowix-web/features/document/store/document-shutdown.test.ts b/app/flowix-web/features/document/store/document-shutdown.test.ts
deleted file mode 100644
index f94fc9944..000000000
--- a/app/flowix-web/features/document/store/document-shutdown.test.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-const mocks = vi.hoisted(() => ({ flush: vi.fn(), invoke: vi.fn(), destroy: vi.fn(), close: vi.fn(), subscribe: vi.fn(), error: vi.fn() }));
-vi.mock('@platform/tauri/core', () => ({ invoke: mocks.invoke }));
-vi.mock('@platform/tauri/window', () => ({ getCurrentWindow: () => ({ onCloseRequested: mocks.close, destroy: mocks.destroy }) }));
-vi.mock('@platform/tauri/event-bus', () => ({ subscribe: mocks.subscribe }));
-vi.mock('@platform/tauri/runtime', () => ({ isTauriDesktopRuntime: () => true }));
-vi.mock('@/lib/i18n', () => ({ translate: (_language: string, key: string) => key }));
-vi.mock('@features/preferences/public/runtime-api', () => ({ getCurrentAppLanguage: () => 'en-US' }));
-vi.mock('@/lib/toast', () => ({ toast: { error: mocks.error } }));
-vi.mock('./document-session-service', () => ({ flushAllDocumentSessions: mocks.flush }));
-async function tick() { for (let i = 0; i < 12; i++) await Promise.resolve(); }
-async function install() { const module = await import('./document-shutdown'); module.installDocumentShutdown(); await tick(); return module; }
-describe('desktop durability handshake', () => {
-  beforeEach(() => {
-    vi.resetModules(); Object.values(mocks).forEach(mock => mock.mockReset());
-    mocks.flush.mockResolvedValue(true); mocks.invoke.mockResolvedValue(true); mocks.destroy.mockResolvedValue(undefined);
-    mocks.close.mockResolvedValue(() => {}); document.body.inert = false;
-  });
-  it('installs once and awaits slow persistence while leaving the page interactive', async () => {
-    let finish!: (value: boolean) => void;
-    mocks.flush.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
-    const module = await install(); module.installDocumentShutdown();
-    const event = { preventDefault: vi.fn() }; const closing = mocks.close.mock.calls[0][0](event); await tick();
-    expect(event.preventDefault).toHaveBeenCalled(); expect(mocks.close).toHaveBeenCalledTimes(1);
-    expect(mocks.destroy).not.toHaveBeenCalled(); expect(document.body.inert).toBe(false);
-    finish(true); await closing;
-    expect(mocks.flush).toHaveBeenCalledTimes(2); expect(mocks.destroy).toHaveBeenCalledTimes(1);
-  });
-  it('keeps the window open when neither file nor recovery is durable', async () => {
-    mocks.flush.mockResolvedValue(false); await install();
-    await mocks.close.mock.calls[0][0]({ preventDefault: vi.fn() });
-    expect(mocks.destroy).not.toHaveBeenCalled(); expect(mocks.error).toHaveBeenCalled();
-    expect(document.body.inert).toBe(false);
-  });
-  it('restores interaction when another window cancels global exit', async () => {
-    await install();
-    const callback = (name: string) => mocks.subscribe.mock.calls.find(([event]) => event === name)![1];
-    callback('document:prepare-exit')(7); await tick();
-    expect(document.body.inert).toBe(true);
-    callback('document:exit-cancelled')(7);
-    expect(document.body.inert).toBe(false);
-    expect(mocks.invoke).toHaveBeenCalledWith('finish_document_shutdown', { request: 7, ready: true });
-  });
-  it('ignores a late completion after an exit request was cancelled', async () => {
-    let finish!: (value: boolean) => void;
-    mocks.flush.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
-    await install();
-    const callback = (name: string) => mocks.subscribe.mock.calls.find(([event]) => event === name)![1];
-    callback('document:prepare-exit')(8); callback('document:exit-cancelled')(8);
-    finish(true); await tick();
-    expect(document.body.inert).toBe(false);
-    expect(mocks.invoke.mock.calls.some(([command]) => command === 'finish_document_shutdown')).toBe(false);
-  });
-});
diff --git a/app/flowix-web/features/document/store/document-shutdown.ts b/app/flowix-web/features/document/store/document-shutdown.ts
deleted file mode 100644
index 1c0b5401c..000000000
--- a/app/flowix-web/features/document/store/document-shutdown.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import { createLogger } from '@/lib/logger';
-import { invoke } from '@platform/tauri/core';
-import { getCurrentWindow } from '@platform/tauri/window';
-import { subscribe } from '@platform/tauri/event-bus';
-import { isTauriDesktopRuntime } from '@platform/tauri/runtime';
-import { translate } from '@/lib/i18n';
-import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
-import { toast } from '@/lib/toast';
-import { flushAllDocumentSessions } from './document-session-service';
-
-let installed: Promise<void> | null = null;
-let preparing: Promise<boolean> | null = null;
-function prepare(): Promise<boolean> {
-  if (preparing) return preparing;
-  preparing = (async () => {
-    const ready = await flushAllDocumentSessions()
-      && await invoke<boolean>('flush_document_background')
-      && await flushAllDocumentSessions();
-    if (!ready) toast.error(translate(getCurrentAppLanguage(), 'document.save.closeFailed'));
-    return ready;
-  })().catch(() => {
-    toast.error(translate(getCurrentAppLanguage(), 'document.save.closeFailed'));
-    return false;
-  }).finally(() => { preparing = null; });
-  return preparing;
-}
-
-/** Install once for the lifetime of a desktop window, including detached tabs. */
-const persistenceLog = createLogger('document:shutdown');
-
-export function installDocumentShutdown(): void {
-  if (installed || !isTauriDesktopRuntime()) return;
-  installed = (async () => {
-    const window = getCurrentWindow();
-    let closing = false;
-    let exitRequest: number | null = null;
-    await window.onCloseRequested(async event => {
-      event.preventDefault();
-      if (closing) return;
-      closing = true;
-      try {
-        if (await prepare()) { document.body.inert = true; await window.destroy(); }
-      } catch { toast.error(translate(getCurrentAppLanguage(), 'document.save.closeFailed')); }
-      finally { closing = false; document.body.inert = false; }
-    });
-    subscribe<number>('document:exit-cancelled', request => {
-      if (exitRequest === request) { exitRequest = null; document.body.inert = false; }
-    });
-    subscribe<number>('document:prepare-exit', request => {
-      exitRequest = request;
-      void prepare().then(async ready => {
-        if (exitRequest !== request) return;
-        if (ready) document.body.inert = true;
-        try { await invoke('finish_document_shutdown', { request, ready }); }
-        catch { document.body.inert = false; }
-      });
-    }, { onListenerReady: () => { void invoke('register_document_window'); } });
-  })().catch(error => {
-    installed = null;
-    persistenceLog.error('listener installation failed', { errorType: error instanceof Error ? error.name : typeof error });
-  });
-}
diff --git a/app/flowix-web/features/document/store/document-store.navigation.test.ts b/app/flowix-web/features/document/store/document-store.navigation.test.ts
new file mode 100644
index 000000000..a72129b0a
--- /dev/null
+++ b/app/flowix-web/features/document/store/document-store.navigation.test.ts
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { prepareDocumentLeave } = vi.hoisted(() => ({ prepareDocumentLeave: vi.fn() }));
+vi.mock('./document-session-service', () => ({ prepareDocumentLeave }));
+vi.mock('@/lib/document-open-perf', () => ({
+  startDocumentOpenTrace: vi.fn(), markDocumentOpenTrace: vi.fn(),
+}));
+
+import { useDocumentStore } from './document-store';
+
+describe('document navigation supersession', () => {
+  beforeEach(() => {
+    useDocumentStore.setState(useDocumentStore.getInitialState(), true);
+    prepareDocumentLeave.mockReset().mockResolvedValue(true);
+  });
+
+  it('keeps A when the user returns to A while B is preparing to leave it', async () => {
+    await useDocumentStore.getState().openExternalDocument('/A.md');
+    useDocumentStore.getState().finishDocumentTransition(useDocumentStore.getState().documentTransitionId);
+    let finishLeave!: (saved: boolean) => void;
+    prepareDocumentLeave.mockImplementationOnce(() => new Promise((resolve) => { finishLeave = resolve; }));
+    const openingB = useDocumentStore.getState().openExternalDocument('/B.md');
+    await vi.waitFor(() => expect(prepareDocumentLeave).toHaveBeenCalledOnce());
+    const returningToA = useDocumentStore.getState().openExternalDocument('/A.md');
+    finishLeave(true);
+    await Promise.all([openingB, returningToA]);
+    expect(useDocumentStore.getState()).toMatchObject({
+      currentDocumentPath: '/A.md', isDocumentTransitioning: false,
+      activeExternalSession: { fileIdentity: { path: '/A.md' } },
+    });
+  });
+  it('lets C supersede a saving B and ignores B completion signals', async () => {
+    await useDocumentStore.getState().openExternalDocument('/A.md');
+    useDocumentStore.getState().finishDocumentTransition(useDocumentStore.getState().documentTransitionId);
+    let finishLeave!: (saved: boolean) => void;
+    prepareDocumentLeave.mockImplementationOnce(() => new Promise((resolve) => { finishLeave = resolve; }));
+    const openingB = useDocumentStore.getState().openExternalDocument('/B.md');
+    const transitionB = useDocumentStore.getState().documentTransitionId;
+    await vi.waitFor(() => expect(prepareDocumentLeave).toHaveBeenCalledOnce());
+    const openingC = useDocumentStore.getState().openExternalDocument('/C.md');
+    finishLeave(true);
+    await Promise.all([openingB, openingC]);
+    useDocumentStore.getState().finishDocumentTransition(transitionB);
+    expect(useDocumentStore.getState()).toMatchObject({
+      currentDocumentPath: '/C.md', isDocumentTransitioning: true, documentLoadOutcome: 'pending',
+    });
+    useDocumentStore.getState().finishDocumentTransition(useDocumentStore.getState().documentTransitionId);
+    expect(useDocumentStore.getState().isDocumentTransitioning).toBe(false);
+  });
+
+  it('ends loading on a refused leave, retains A, and allows retrying B', async () => {
+    await useDocumentStore.getState().openExternalDocument('/A.md');
+    useDocumentStore.getState().finishDocumentTransition(useDocumentStore.getState().documentTransitionId);
+    prepareDocumentLeave.mockResolvedValueOnce(false);
+    await expect(useDocumentStore.getState().openExternalDocument('/B.md')).rejects.toThrow('saving could not be retained');
+    expect(useDocumentStore.getState()).toMatchObject({
+      currentDocumentPath: '/A.md', isDocumentTransitioning: false,
+    });
+    await useDocumentStore.getState().openExternalDocument('/B.md');
+    expect(useDocumentStore.getState()).toMatchObject({
+      currentDocumentPath: '/B.md', isDocumentTransitioning: true, documentLoadOutcome: 'pending',
+    });
+  });
+
+});
diff --git a/app/flowix-web/features/document/store/document-store.ts b/app/flowix-web/features/document/store/document-store.ts
index d4bd13a9d..a3c5d0b48 100644
--- a/app/flowix-web/features/document/store/document-store.ts
+++ b/app/flowix-web/features/document/store/document-store.ts
@@ -1,5 +1,5 @@
 import { create } from 'zustand';
-import { flushDocumentPath } from '@features/document/store/document-session-service';
+import { prepareDocumentLeave } from '@features/document/store/document-session-service';
 import { canonicalPath } from '@/lib/path';
 import {
   markDocumentOpenTrace,
@@ -10,6 +10,7 @@ import { ensureFileDisplayIdentity, type FileDisplayIdentity } from '@/lib/file-
 
 
 export type DocumentSource = 'external';
+export type DocumentLoadOutcome = 'pending' | 'ready' | 'unavailable' | null;
 
 export interface ExternalDocumentSession {
   fileIdentity: FileDisplayIdentity;
@@ -43,7 +44,8 @@ interface DocumentStore {
   activeExternalSession: ExternalDocumentSession | null;
   isDocumentTransitioning: boolean;
   documentTransitionId: number;
-  finishDocumentTransition: (transitionId: number) => void;
+  documentLoadOutcome: DocumentLoadOutcome;
+  finishDocumentTransition: (transitionId: number, outcome?: 'ready' | 'unavailable') => void;
   replaceActiveExternalPath: (displayId: string, path: string) => void;
   openExternalDocument: (path: string | null, options?: {
     scopePath?: string | null;
@@ -63,15 +65,13 @@ interface DocumentStore {
 // ---------------------------------------------------------------------------
 //
 // A document session transition has two phases, both owned by this store:
-//   1. flush the outgoing document's pending edits to disk
-//      (calls document-session-service.flushDocumentPath for the previous path)
+//   1. retain the outgoing draft and start its save/checkpoint work
+//      (calls document-session-service.prepareDocumentLeave for the previous path)
 //   2. commit the new session state via set(...)
 //
-// The flush awaits the save queue's chain — see save-queue.ts — so by
-// the time set() runs, the outgoing document's last edit is on disk
-// (or a CAS refusal toast has been surfaced). React then re-renders
-// with the new session; useDocumentContent's reloadDocument effect
-// reads the new path and re-hydrates the buffer.
+// Navigation does not block on disk I/O. The outgoing runtime session stays
+// retained until its queued save or recovery checkpoint settles. Operations
+// that overwrite or delete the path use saveDocumentPath as a durability barrier.
 //
 // If there is no previous session (first open after launch), the flush
 // is a no-op.
@@ -84,6 +84,7 @@ function documentState(path: string | null, source: DocumentSource | null) {
     activeAgentConversationId: null,
     activeExternalSession: null,
     isDocumentTransitioning: false,
+    documentLoadOutcome: null,
   };
 }
 
@@ -120,10 +121,11 @@ export const useDocumentStore = create<DocumentStore>()(
     activeExternalSession: null,
     isDocumentTransitioning: false,
     documentTransitionId: 0,
-    finishDocumentTransition: (transitionId) => {
+    documentLoadOutcome: null,
+    finishDocumentTransition: (transitionId, outcome = 'ready') => {
       set((state) => {
-        if (state.documentTransitionId !== transitionId) return state;
-        return { isDocumentTransitioning: false };
+        if (state.documentTransitionId !== transitionId || !state.isDocumentTransitioning) return state;
+        return { isDocumentTransitioning: false, documentLoadOutcome: outcome };
       });
     },
     replaceActiveExternalPath: (displayId, path) => {
@@ -153,7 +155,8 @@ export const useDocumentStore = create<DocumentStore>()(
     } = {}) => {
       const canonicalNewPath = path ? canonicalPath(path) : null;
       const canonicalScopePath = scopePath ? canonicalPath(scopePath) : null;
-      if (isSameExternalTarget(get(), canonicalNewPath, canonicalScopePath)) {
+      // Returning to the visible document must supersede a queued switch too.
+      if (!get().isDocumentTransitioning && isSameExternalTarget(get(), canonicalNewPath, canonicalScopePath)) {
         return;
       }
 
@@ -166,9 +169,14 @@ export const useDocumentStore = create<DocumentStore>()(
       markDocumentOpenTrace(transitionId, 'navigation:external-start', {
         scopePath: canonicalScopePath,
       });
-      set({ isDocumentTransitioning: true, documentTransitionId: transitionId });
+      set({
+        isDocumentTransitioning: true,
+        documentTransitionId: transitionId,
+        documentLoadOutcome: 'pending',
+      });
       return enqueueTransition(async () => {
         try {
+          if (get().documentTransitionId !== transitionId) return;
           if (isSameExternalTarget(get(), canonicalNewPath, canonicalScopePath)) {
             get().finishDocumentTransition(transitionId);
             return;
@@ -176,13 +184,14 @@ export const useDocumentStore = create<DocumentStore>()(
 
           const prev = get().activeExternalSession;
           if (prev) {
-            const flushed = await flushDocumentPath(
+            const prepared = await prepareDocumentLeave(
               sessionIdentity(prev),
               sessionPath(prev),
               sessionScopePath(prev),
             );
-            if (!flushed) throw new Error('Document switch cancelled because saving did not complete');
+            if (!prepared) throw new Error('Document switch cancelled because saving could not be retained');
           }
+          if (get().documentTransitionId !== transitionId) return;
           set(() => {
             if (!canonicalNewPath) return documentState(null, null);
             const openedAt = Date.now();
@@ -202,6 +211,7 @@ export const useDocumentStore = create<DocumentStore>()(
                 transitionId,
               },
               isDocumentTransitioning: true,
+              documentLoadOutcome: 'pending',
             };
           });
         } catch (err) {
@@ -217,8 +227,8 @@ export const useDocumentStore = create<DocumentStore>()(
       return enqueueTransition(async () => {
         const prev = get().activeExternalSession;
         if (prev) {
-          const flushed = await flushDocumentPath(sessionIdentity(prev), sessionPath(prev), sessionScopePath(prev));
-          if (!flushed) throw new Error('Session switch cancelled because saving did not complete');
+          const prepared = await prepareDocumentLeave(sessionIdentity(prev), sessionPath(prev), sessionScopePath(prev));
+          if (!prepared) throw new Error('Session switch cancelled because saving could not be retained');
         }
         set({
           ...documentState(null, null),
@@ -234,8 +244,8 @@ export const useDocumentStore = create<DocumentStore>()(
       return enqueueTransition(async () => {
         const prev = get().activeExternalSession;
         if (prev) {
-          const flushed = await flushDocumentPath(sessionIdentity(prev), sessionPath(prev), sessionScopePath(prev));
-          if (!flushed) throw new Error('Document close cancelled because saving did not complete');
+          const prepared = await prepareDocumentLeave(sessionIdentity(prev), sessionPath(prev), sessionScopePath(prev));
+          if (!prepared) throw new Error('Document close cancelled because saving could not be retained');
         }
         set(documentState(null, null));
       });
diff --git a/app/flowix-web/features/document/store/external-document-watch.ts b/app/flowix-web/features/document/store/external-document-watch.ts
new file mode 100644
index 000000000..1885709ad
--- /dev/null
+++ b/app/flowix-web/features/document/store/external-document-watch.ts
@@ -0,0 +1,171 @@
+import { canonicalPath } from '@/lib/path';
+import { createLogger } from '@/lib/logger';
+import { getCurrentWindow } from '@platform/tauri/window';
+import { windows, type ExternalDocumentChangedEvent } from '@platform/tauri/client';
+import { subscribe, type UnlistenFn } from '@platform/tauri/event-bus';
+import { consumeExpectedExternalDocumentEvent } from './external-document-operation';
+
+export interface ExternalDocumentChangeContext {
+  runOnce<T>(key: string, operation: () => T | Promise<T>): Promise<T>;
+}
+
+type ExternalDocumentChangeHandler = (
+  event: ExternalDocumentChangedEvent,
+  context: ExternalDocumentChangeContext,
+) => void | Promise<void>;
+
+interface WatchGroup {
+  key: string;
+  path: string;
+  scopePath: string | null;
+  subscribers: Map<symbol, ExternalDocumentChangeHandler>;
+  active: boolean;
+  leaseId: string | null;
+}
+
+const logger = createLogger('external-document-watch');
+const watchGroups = new Map<string, WatchGroup>();
+const recentEvents = new Map<string, number>();
+const EVENT_DEDUP_WINDOW_MS = 2_000;
+const MAX_RECENT_EVENTS = 512;
+let eventUnlisten: UnlistenFn | null = null;
+
+function watchGroupKey(path: string, scopePath: string | null): string {
+  return JSON.stringify([path, scopePath]);
+}
+
+function eventKey(path: string, event: ExternalDocumentChangedEvent): string {
+  return JSON.stringify([
+    path,
+    event.kind,
+    event.revision,
+    event.source ?? null,
+    event.originWindowLabel ?? null,
+  ]);
+}
+
+function isDuplicateEvent(key: string): boolean {
+  const now = Date.now();
+  for (const [recentKey, receivedAt] of recentEvents) {
+    if (now - receivedAt > EVENT_DEDUP_WINDOW_MS) recentEvents.delete(recentKey);
+  }
+  const previous = recentEvents.get(key);
+  if (previous !== undefined && now - previous <= EVENT_DEDUP_WINDOW_MS) return true;
+
+  recentEvents.delete(key);
+  recentEvents.set(key, now);
+  while (recentEvents.size > MAX_RECENT_EVENTS) {
+    const oldest = recentEvents.keys().next().value;
+    if (oldest === undefined) break;
+    recentEvents.delete(oldest);
+  }
+  return false;
+}
+
+function dispatchExternalDocumentChange(event: ExternalDocumentChangedEvent): void {
+  const path = canonicalPath(event.path);
+  const groups = [...watchGroups.values()].filter((group) => group.path === path && group.active);
+  if (groups.length === 0 || isDuplicateEvent(eventKey(path, event))) return;
+
+  if (event.source === 'user_edit' && event.originWindowLabel === getCurrentWindow().label) return;
+  if (consumeExpectedExternalDocumentEvent(path, event.kind, event.revision)) return;
+
+  // Several path/scope leases can target the same file in one window. Route a
+  // matching revision once, while each mounted view updates its own local state.
+  const subscribers = groups.flatMap((group) => [...group.subscribers.values()]);
+  const sharedOperations = new Map<string, Promise<unknown>>();
+  const context: ExternalDocumentChangeContext = {
+    runOnce<T>(key: string, operation: () => T | Promise<T>): Promise<T> {
+      const existing = sharedOperations.get(key);
+      if (existing) return existing as Promise<T>;
+      const pending = Promise.resolve().then(operation);
+      sharedOperations.set(key, pending);
+      return pending;
+    },
+  };
+  for (const handler of subscribers) {
+    try {
+      const result = handler(event, context);
+      if (result && typeof result.then === 'function') {
+        void result.catch((error: unknown) => logger.warn('change handler failed', { error }));
+      }
+    } catch (error) {
+      logger.warn('change handler failed', { error });
+    }
+  }
+}
+
+function ensureEventSubscription(): void {
+  if (eventUnlisten) return;
+  eventUnlisten = subscribe<ExternalDocumentChangedEvent>(
+    'external-document-changed',
+    dispatchExternalDocumentChange,
+  );
+}
+
+function registerWatch(group: WatchGroup): void {
+  void windows.watchExternalDocument(group.path, group.scopePath).then((leaseId) => {
+    if (!group.active || watchGroups.get(group.key) !== group) {
+      void windows.unwatchExternalDocument(leaseId).catch((error: unknown) => {
+        logger.warn('stale watcher lease cleanup failed', { error });
+      });
+      return;
+    }
+    group.leaseId = leaseId;
+  }).catch((error: unknown) => {
+    if (group.active && watchGroups.get(group.key) === group) {
+      logger.warn('registration failed', { path: group.path, error });
+    }
+  });
+}
+
+function releaseWatchGroup(group: WatchGroup): void {
+  group.active = false;
+  watchGroups.delete(group.key);
+  if (group.leaseId) {
+    void windows.unwatchExternalDocument(group.leaseId).catch((error: unknown) => {
+      logger.warn('watcher lease cleanup failed', { path: group.path, error });
+    });
+  }
+  if (watchGroups.size !== 0) return;
+  eventUnlisten?.();
+  eventUnlisten = null;
+  recentEvents.clear();
+}
+
+/** Share native watch leases and event routing between views of the same file. */
+export function subscribeExternalDocumentChanges(
+  filePath: string,
+  scopePath: string | null,
+  handler: ExternalDocumentChangeHandler,
+): () => void {
+  const path = canonicalPath(filePath);
+  const normalizedScopePath = scopePath ? canonicalPath(scopePath) : null;
+  const key = watchGroupKey(path, normalizedScopePath);
+  let group = watchGroups.get(key);
+  if (!group) {
+    group = {
+      key,
+      path,
+      scopePath: normalizedScopePath,
+      subscribers: new Map(),
+      active: true,
+      leaseId: null,
+    };
+    watchGroups.set(key, group);
+    ensureEventSubscription();
+    registerWatch(group);
+  }
+
+  const subscriptionId = Symbol('external-document-change-subscriber');
+  group.subscribers.set(subscriptionId, handler);
+  let subscribed = true;
+  return () => {
+    if (!subscribed) return;
+    subscribed = false;
+    group?.subscribers.delete(subscriptionId);
+    if (group && group.subscribers.size === 0 && watchGroups.get(key) === group) {
+      releaseWatchGroup(group);
+    }
+  };
+}
diff --git a/app/flowix-web/features/document/store/index.ts b/app/flowix-web/features/document/store/index.ts
index 46f44b2c3..2cd3ce517 100644
--- a/app/flowix-web/features/document/store/index.ts
+++ b/app/flowix-web/features/document/store/index.ts
@@ -18,7 +18,6 @@ export {
   applyRecoveryDraftContent,
   prepareDocumentLeave,
   saveDocumentContent,
-  flushDocumentPath,
   getDocumentBuffer,
   hasDocumentUnsavedChanges,
   discardDocumentDraft,
diff --git a/app/flowix-web/features/document/store/recovery-draft-store.ts b/app/flowix-web/features/document/store/recovery-draft-store.ts
index 395776c28..a7269b406 100644
--- a/app/flowix-web/features/document/store/recovery-draft-store.ts
+++ b/app/flowix-web/features/document/store/recovery-draft-store.ts
@@ -11,7 +11,7 @@ import {
 
 const recoveryOperations = new Map<string, Promise<unknown>>();
 const createdAtByKey = new Map<string, number>();
-const RECOVERY_READ_TIMEOUT_MS = 2_000;
+const RECOVERY_LIST_TIMEOUT_MS = 2_000;
 
 function settleWithin<T>(promise: Promise<T>, timeoutMs: number, fallback: T): Promise<T> {
   return new Promise((resolve) => {
@@ -73,17 +73,10 @@ export interface RecoveryDraft {
 
 interface PreviousRecoveryDraft extends Omit<RecoveryDraft, 'schemaVersion' | 'identity'> {
   schemaVersion: 2 | 3;
-  identity: { kind: 'md'; memoId?: string | null; path: string };
+  identity: { kind: 'md'; path: string };
 }
 
-interface LegacyRecoveryDraft extends Omit<RecoveryDraft, 'schemaVersion' | 'identity'> {
-  schemaVersion: 1;
-  identity:
-    | { kind: 'memo'; id: string }
-    | { kind: 'external'; path: string };
-}
-
-type StoredRecoveryDraft = RecoveryDraft | PreviousRecoveryDraft | LegacyRecoveryDraft;
+type StoredRecoveryDraft = RecoveryDraft | PreviousRecoveryDraft;
 
 function normalizeRecoveryDraft(
   draft: StoredRecoveryDraft | null,
@@ -99,13 +92,7 @@ function normalizeRecoveryDraft(
       },
     };
   }
-  return {
-    ...draft,
-    schemaVersion: 4,
-    identity: draft.identity.kind === 'memo'
-      ? { kind: 'md', path: canonicalPath(draft.originalPath) }
-      : { kind: 'md', path: canonicalPath(draft.identity.path) },
-  };
+  return null;
 }
 
 function legacyExternalRecoveryKey(path: string): string {
@@ -123,15 +110,13 @@ async function readStoredDraftEntry(key: string): Promise<{
   const stored = await recoveryDrafts.read<StoredRecoveryDraft>(key);
   const draft = normalizeRecoveryDraft(stored);
   if (!stored || !draft) return null;
-  const hasLegacyMemoIdentity = stored.schemaVersion !== 1
-    && 'memoId' in stored.identity;
   return {
     draft,
-    needsMigration: stored.schemaVersion !== 4 || hasLegacyMemoIdentity,
+    needsMigration: stored.schemaVersion !== 4,
   };
 }
 
-function legacyRecoveryKeys(identity: DocumentIdentity): string[] {
+function legacyRecoveryKeys(identity: DocumentLocator): string[] {
   return [legacyExternalRecoveryKey(identity.path)];
 }
 
@@ -197,9 +182,10 @@ async function persistRecoverySnapshot(
   }).catch(() => false);
 }
 
+/** Opening callers must distinguish no checkpoint from a slow store read. */
 export function readRecoveryDraft(identity: DocumentIdentity): Promise<RecoveryDraft | null> {
   const recoveryIdentity = documentLocator(identity);
-  return settleWithin(enqueueRecoveryOperation(identity, async () => {
+  return enqueueRecoveryOperation(identity, async () => {
     const key = documentLocatorKey(recoveryIdentity);
     const stored = await readDraftForIdentity(identity);
     if (!stored) return null;
@@ -216,7 +202,7 @@ export function readRecoveryDraft(identity: DocumentIdentity): Promise<RecoveryD
     return {
       ...migratedDraft,
     };
-  }), RECOVERY_READ_TIMEOUT_MS, null);
+  });
 }
 
 export async function clearRecoveryDraftThrough(
@@ -236,14 +222,14 @@ export async function clearRecoveryDraftThrough(
 }
 
 /** Move a path-keyed draft with its live document during an in-place rename. */
-export function rebaseRecoveryDraftPath(identity: DocumentIdentity, nextPath: string): void {
-  const previous = documentLocator(identity);
+export function rebaseRecoveryDraftPath(identity: DocumentLocator, nextPath: string): Promise<void> {
+  const previous: DocumentLocator = { kind: 'md', path: canonicalPath(identity.path) };
   const next = { ...previous, path: canonicalPath(nextPath) };
-  if (!previous.path || !next.path || previous.path === next.path) return;
+  if (!previous.path || !next.path || previous.path === next.path) return Promise.resolve();
 
   const previousKey = documentLocatorKey(previous);
   const nextKey = documentLocatorKey(next);
-  void enqueueRecoveryOperationForKeys([previousKey, nextKey], async () => {
+  return enqueueRecoveryOperationForKeys([previousKey, nextKey], async () => {
     let sourceKey = previousKey;
     let source = await readStoredDraft(previousKey);
     if (!source) {
@@ -276,6 +262,21 @@ export function rebaseRecoveryDraftPath(identity: DocumentIdentity, nextPath: st
   }).catch(() => undefined);
 }
 
+/** Closed drafts have no runtime display to participate in a path move. */
+export async function rebaseStoredRecoveryDraftPaths(previous: string, next: string, directory: boolean): Promise<void> {
+  // Await migrations scheduled for live displays before listing closed drafts.
+  await Promise.all([...recoveryOperations.values()].map((operation) => operation.catch(() => undefined)));
+  const drafts = await recoveryDrafts.list<StoredRecoveryDraft>();
+  await Promise.all(drafts.map(async (stored) => {
+    const draft = normalizeRecoveryDraft(stored);
+    if (!draft) return;
+    const path = canonicalPath(draft.identity.path);
+    const replacement = path === previous ? next
+      : directory && path.startsWith(`${previous}/`) ? `${next}${path.slice(previous.length)}` : null;
+    if (replacement) await rebaseRecoveryDraftPath({ kind: 'md', path }, replacement);
+  }));
+}
+
 export function listRecoveryDrafts(): Promise<RecoveryDraft[]> {
   return settleWithin(
     recoveryDrafts.list<StoredRecoveryDraft>()
@@ -296,7 +297,7 @@ export function listRecoveryDrafts(): Promise<RecoveryDraft[]> {
         }
         return [...unique.values()];
       }),
-    RECOVERY_READ_TIMEOUT_MS,
+    RECOVERY_LIST_TIMEOUT_MS,
     [],
   );
 }
diff --git a/app/flowix-web/features/document/use-cases/delete-external-document.test.ts b/app/flowix-web/features/document/use-cases/delete-external-document.test.ts
index cf862270f..bb9563553 100644
--- a/app/flowix-web/features/document/use-cases/delete-external-document.test.ts
+++ b/app/flowix-web/features/document/use-cases/delete-external-document.test.ts
@@ -2,38 +2,36 @@ import { beforeEach, expect, it, vi } from 'vitest';
 import { deleteExternalDocument } from './delete-external-document';
 
 const mocks = vi.hoisted(() => ({
-  flush: vi.fn(), settled: vi.fn(), dirty: vi.fn(), remove: vi.fn(),
+  save: vi.fn(), dirty: vi.fn(), remove: vi.fn(),
   capture: vi.fn(), discard: vi.fn(), cancel: vi.fn(), expectDelete: vi.fn(),
 }));
 vi.mock('../store/document-session-service', () => ({
   captureLatestDocumentContent: mocks.capture, discardDocumentDraft: mocks.discard,
-  flushDocumentPath: mocks.flush, hasDocumentUnsavedChanges: mocks.dirty,
+  saveDocumentPath: mocks.save, hasDocumentUnsavedChanges: mocks.dirty,
 }));
-vi.mock('../store/save-queue', () => ({ waitForSaveQueue: mocks.settled }));
 vi.mock('../store/external-document-operation', () => ({ expectExternalDocumentDelete: mocks.expectDelete }));
 vi.mock('./local-document-operations', () => ({ localDocumentOperations: { delete: mocks.remove } }));
 const session = { fileIdentity: { path: '/notes/file.md', displayId: 'live-file' }, scopePath: '/notes', openedAt: 1, transitionId: 1 };
 
 beforeEach(() => {
   vi.resetAllMocks();
-  mocks.flush.mockResolvedValue(true);
-  mocks.settled.mockResolvedValue(true);
+  mocks.save.mockResolvedValue(true);
   mocks.dirty.mockReturnValue(false);
   mocks.expectDelete.mockReturnValue(mocks.cancel);
   mocks.remove.mockResolvedValue({ path: session.fileIdentity.path });
 });
 
-it.each(['flush', 'settled', 'dirty'] as const)('preserves the file when the %s persistence barrier rejects deletion', async barrier => {
+it.each(['save', 'dirty'] as const)('preserves the file when the %s persistence barrier rejects deletion', async barrier => {
   if (barrier === 'dirty') mocks.dirty.mockReturnValue(true);
-  else mocks[barrier].mockResolvedValue(false);
+  else mocks.save.mockResolvedValue(false);
   expect(await deleteExternalDocument(session)).toBe(false);
   expect(mocks.remove).not.toHaveBeenCalled();
   expect(mocks.discard).not.toHaveBeenCalled();
 });
 
-it('waits for queued writes, deletes inside the file scope and then releases the draft', async () => {
+it('waits for the save barrier, deletes inside the file scope and then releases the draft', async () => {
   let settle!: (value: boolean) => void;
-  mocks.settled.mockReturnValue(new Promise<boolean>(resolve => { settle = resolve; }));
+  mocks.save.mockReturnValue(new Promise<boolean>(resolve => { settle = resolve; }));
   const pending = deleteExternalDocument(session);
   await Promise.resolve();
   expect(mocks.remove).not.toHaveBeenCalled();
diff --git a/app/flowix-web/features/document/use-cases/delete-external-document.ts b/app/flowix-web/features/document/use-cases/delete-external-document.ts
index fb666c1cb..a871ab91d 100644
--- a/app/flowix-web/features/document/use-cases/delete-external-document.ts
+++ b/app/flowix-web/features/document/use-cases/delete-external-document.ts
@@ -1,7 +1,6 @@
 import type { ExternalDocumentSession } from '../store/document-store';
-import { documentIdentityFromFile, documentIdentityKey } from '../store/document-identity';
-import { captureLatestDocumentContent, discardDocumentDraft, flushDocumentPath, hasDocumentUnsavedChanges } from '../store/document-session-service';
-import { waitForSaveQueue } from '../store/save-queue';
+import { documentIdentityFromFile } from '../store/document-identity';
+import { captureLatestDocumentContent, discardDocumentDraft, saveDocumentPath, hasDocumentUnsavedChanges } from '../store/document-session-service';
 import { expectExternalDocumentDelete } from '../store/external-document-operation';
 import { localDocumentOperations } from './local-document-operations';
 
@@ -9,9 +8,8 @@ import { localDocumentOperations } from './local-document-operations';
 export async function deleteExternalDocument(session: ExternalDocumentSession): Promise<boolean> {
   const identity = documentIdentityFromFile(session.fileIdentity);
   captureLatestDocumentContent(identity);
-  const flushed = await flushDocumentPath(identity, identity.path, session.scopePath);
-  const settled = await waitForSaveQueue(documentIdentityKey(identity));
-  if (!flushed || !settled || hasDocumentUnsavedChanges(identity)) return false;
+  const saved = await saveDocumentPath(identity, identity.path, session.scopePath);
+  if (!saved || hasDocumentUnsavedChanges(identity)) return false;
 
   const cancelExpectedDelete = expectExternalDocumentDelete(identity.path);
   try {
diff --git a/app/flowix-web/features/document/use-cases/document-navigation.ts b/app/flowix-web/features/document/use-cases/document-navigation.ts
index c99faa3b6..0c6b70064 100644
--- a/app/flowix-web/features/document/use-cases/document-navigation.ts
+++ b/app/flowix-web/features/document/use-cases/document-navigation.ts
@@ -4,15 +4,11 @@ import {
   type DocumentHistoryEntry,
 } from '@features/document/store/document-history-store';
 import { useDocumentStore } from '@features/document/store/document-store';
-import { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
 import {
-  openExternalTarget,
-  openCollectionTarget,
-  openMediaTarget,
-  openWebTarget,
-  openDocumentListTarget,
   historyEntryFromWorkColumnTarget,
 } from '@features/workspace/use-cases/workspace-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { openFolderCollection } from '@features/workspace/public/main-window-api';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
 
 export type DocumentHistoryDirection = 'back' | 'forward';
@@ -43,45 +39,53 @@ function currentHistoryEntry(): DocumentHistoryEntry | null {
 
 async function openHistoryEntry(entry: DocumentHistoryEntry): Promise<DocumentHistoryEntry> {
   if (entry.kind === 'collection') {
-    await openCollectionTarget(entry, { history: 'skip', destination: 'main-third' });
+    await openWorkspaceSurface({
+      host: 'main-third',
+      target: { ...entry, kind: 'collection-reference' },
+      options: { history: 'skip' },
+    });
     return entry;
   }
   if (entry.kind === 'document-list') {
-    openDocumentListTarget({
-      kind: 'document-list',
-      displayId: entry.displayId,
-      scope: entry.scope,
-      filters: entry.filters,
-    }, { history: 'skip' });
-    return entry;
+    await openFolderCollection(entry.scope.notebookId ?? '', entry.scope.path, { history: 'skip' });
+    const openedEntry = historyEntryFromWorkColumnTarget(useWorkColumnStore.getState().navigation.target);
+    if (!openedEntry) throw new Error('无法恢复旧文件夹历史记录');
+    return openedEntry;
   }
   if (entry.kind === 'agent-conversation') {
-    await selectAndOpenAgentConversation(entry.instanceId, {
-      history: 'skip',
-      destination: 'main-third',
-      ...(entry.blankIfMissing ? { blankIfMissing: true as const } : {}),
+    await openWorkspaceSurface({
+      host: 'main-third',
+      target: {
+        kind: 'agent-conversation',
+        instanceId: entry.instanceId,
+        ...(entry.blankIfMissing ? { blankIfMissing: true as const } : {}),
+      },
+      options: { history: 'skip' },
     });
     return entry;
   }
   if (entry.kind === 'web') {
-    await openWebTarget(entry.url, { history: 'skip', destination: 'main-third' });
+    await openWorkspaceSurface({ host: 'main-third', target: { kind: 'web', url: entry.url }, options: { history: 'skip' } });
     return entry;
   }
   if (entry.kind === 'media') {
-    await openMediaTarget({
-      filePath: entry.filePath,
-      notebookId: entry.notebookId,
-      notebookPath: entry.notebookPath,
-      resourceKind: entry.resourceKind,
-      history: 'skip',
-      destination: 'main-third',
+    await openWorkspaceSurface({
+      host: 'main-third',
+      target: {
+        kind: 'media',
+        filePath: entry.filePath,
+        notebookId: entry.notebookId,
+        notebookPath: entry.notebookPath,
+        resourceKind: entry.resourceKind,
+      },
+      options: { history: 'skip' },
     });
     return entry;
   }
-  await openExternalTarget(entry.path, {
-    history: 'skip',
-    scopePath: entry.scopePath,
-    destination: 'main-third',
+  await openWorkspaceSurface({
+    host: 'main-third',
+    target: { kind: 'external', path: entry.path, scopePath: entry.scopePath, transitionId: null },
+    options: { history: 'skip' },
   });
   return entry;
 }
@@ -122,7 +126,7 @@ export async function navigateDocumentHistory(direction: DocumentHistoryDirectio
     ? useDocumentHistoryStore.getState().backStack
     : useDocumentHistoryStore.getState().forwardStack;
   if (documentHistoryEntryKey(currentStack[currentStack.length - discardCount] ?? null)
-    !== documentHistoryEntryKey(openedTarget)) return false;
+    !== documentHistoryEntryKey(target)) return false;
 
   if (direction === 'back') {
     useDocumentHistoryStore.getState().commitBackNavigation(current, discardCount);
diff --git a/app/flowix-web/features/document/use-cases/editable-document-operations.ts b/app/flowix-web/features/document/use-cases/editable-document-operations.ts
index 76441f53e..f7989364d 100644
--- a/app/flowix-web/features/document/use-cases/editable-document-operations.ts
+++ b/app/flowix-web/features/document/use-cases/editable-document-operations.ts
@@ -1,4 +1,4 @@
-import type { MemoContentCommit } from '@/types/memo';
+import type { NoteContentCommit } from '@/types/memo';
 
 /** File operations used by an open editable document surface. */
 export interface DocumentWriteRequest {
@@ -9,7 +9,7 @@ export interface DocumentWriteRequest {
 }
 
 export type DocumentWriteOutcome =
-  | ({ status: 'saved'; path: string; content: string; merged?: boolean } & MemoContentCommit)
+  | ({ status: 'saved'; path: string; content: string; merged?: boolean } & NoteContentCommit)
   | { status: 'conflict'; diskContent: string }
   | { status: 'refused' }
   | { status: 'missing' }
diff --git a/app/flowix-web/features/document/use-cases/heading-anchor-publish.ts b/app/flowix-web/features/document/use-cases/heading-anchor-publish.ts
index 40c88759c..7355cfbe3 100644
--- a/app/flowix-web/features/document/use-cases/heading-anchor-publish.ts
+++ b/app/flowix-web/features/document/use-cases/heading-anchor-publish.ts
@@ -1,11 +1,11 @@
 import GithubSlugger from 'github-slugger';
-import type { WorkspaceContentLocation } from '@features/workspace/use-cases/workspace-content-activation';
+import type { WorkspaceContentLocation } from '@features/workspace/public/note-navigation-api';
 import { publishAgentLocationRequest } from './agent-location-navigation';
 
 /** Stable view id for a content location: the tab itself, or the shared main view.
  *
- * Accepts any opened-location shape (WorkspaceContentLocation,
- * BrowserColumnOpenResult) — only `host` and an optional `tabId` are read.
+ * The public surface-open result is normalized to WorkspaceContentLocation
+ * before it reaches this helper.
  */
 export function locationViewId(opened: { host: string; tabId?: string }): string {
   return opened.host === 'browser-column' ? (opened.tabId ?? opened.host) : opened.host;
@@ -18,10 +18,8 @@ export function locationViewId(opened: { host: string; tabId?: string }): string
  * Single choke point for anchor publishing:
  * - the anchor is normalized to its GitHub slug once here — every consumer
  *   (rich text heading match, source view) compares against slugs;
- * - `openExternalTarget` does not report a location for the markdown
- *   main-document branch (returns null), so a null `opened` safely falls
- *   back to main-third — all anchor-carrying opens land there unless an
- *   existing browser-column view was activated (which returns its location).
+ * - A cancelled open passes null and does not publish a request. An actual
+ *   Work open always carries an explicit Work location.
  */
 export function publishHeadingAnchorRequest(
   path: string,
@@ -32,7 +30,8 @@ export function publishHeadingAnchorRequest(
   if (!raw) return;
   const slug = new GithubSlugger().slug(raw);
   if (!slug) return;
-  const location = opened ?? { host: 'main-third', state: 'active' };
+  if (!opened) return;
+  const location = opened;
   publishAgentLocationRequest({
     path,
     anchor: slug,
diff --git a/app/flowix-web/features/document/use-cases/local-document-operations.ts b/app/flowix-web/features/document/use-cases/local-document-operations.ts
index 08dd3978c..497f796cc 100644
--- a/app/flowix-web/features/document/use-cases/local-document-operations.ts
+++ b/app/flowix-web/features/document/use-cases/local-document-operations.ts
@@ -23,8 +23,8 @@ export const localDocumentOperations: EditableDocumentOperations = {
   },
   rename: async ({ path, name, scopePath, notebookId, collectionId }) => {
     if (!scopePath) throw new Error('A file scope is required to rename this document');
-    if (/\.(?:table|lib)\.ya?ml$/i.test(path)) {
-      const title = name.replace(/\.(?:table|lib)\.ya?ml$/i, '');
+    if (/\.(?:(?:table|lib)\.ya?ml|index\.yaml)$/i.test(path)) {
+      const title = name.replace(/\.(?:(?:table|lib)\.ya?ml|index\.yaml)$/i, '');
       const result = await renameCollectionAtPath(path, scopePath, title, notebookId, collectionId);
       if (result.errorCode) throw new Error(`集合已更新，但操作尚未完成：${result.errorCode}`);
       return { path: result.filePath };
diff --git a/app/flowix-web/features/document/use-cases/memo-document-operations.ts b/app/flowix-web/features/document/use-cases/memo-document-operations.ts
index 5a30a0dc5..60f3c206b 100644
--- a/app/flowix-web/features/document/use-cases/memo-document-operations.ts
+++ b/app/flowix-web/features/document/use-cases/memo-document-operations.ts
@@ -22,7 +22,8 @@ export const memoDocumentOperations = {
       expectedFilename: request.expectedFilename,
       expectedContent: request.expectedContent,
     });
-    if (result.path !== request.path) updateNoteLinksAfterMove(request.path, result.path);
+    // Modern results are applied by the shared notebook-change subscription.
+    if (!result.notebookChange && result.path !== request.path) updateNoteLinksAfterMove(request.path, result.path);
     return result;
   },
 } satisfies Pick<EditableDocumentOperations, 'read' | 'write'> & {
diff --git a/app/flowix-web/features/document/use-cases/open-document-local-link.test.ts b/app/flowix-web/features/document/use-cases/open-document-local-link.test.ts
index 919ba66d3..67fa45477 100644
--- a/app/flowix-web/features/document/use-cases/open-document-local-link.test.ts
+++ b/app/flowix-web/features/document/use-cases/open-document-local-link.test.ts
@@ -2,14 +2,17 @@ import { describe, expect, it, vi } from 'vitest';
 import { openDocumentLocalLink } from './open-document-local-link';
 import { peekAgentLocationRequest, cancelAgentLocationRequest } from './agent-location-navigation';
 
-const openExternalTarget = vi.hoisted(() => vi.fn());
-vi.mock('@features/workspace/use-cases/workspace-navigation', () => ({ openExternalTarget }));
+const openWorkspaceSurface = vi.hoisted(() => vi.fn());
+vi.mock('@features/workspace/public/open-surface-api', () => ({ openWorkspaceSurface }));
 
 describe('openDocumentLocalLink', () => {
   it('opens the target and publishes an anchor request for the opened host', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'main-third', state: 'active' });
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' } });
     await openDocumentLocalLink({ path: '/nb/课程/任务记录.md', anchor: '实验步骤' }, '/nb/课程');
-    expect(openExternalTarget).toHaveBeenCalledWith('/nb/课程/任务记录.md', { scopePath: '/nb/课程' });
+    expect(openWorkspaceSurface).toHaveBeenCalledWith({
+      host: 'main-third',
+      target: { kind: 'external', path: '/nb/课程/任务记录.md', scopePath: '/nb/课程', transitionId: null },
+    });
     const request = peekAgentLocationRequest('/nb/课程/任务记录.md');
     expect(request?.anchor).toBe('实验步骤');
     expect(request?.host).toBe('main-third');
@@ -17,29 +20,24 @@ describe('openDocumentLocalLink', () => {
     cancelAgentLocationRequest('/nb/课程/任务记录.md');
   });
 
-  it('targets the browser column tab when the host is a browser column', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'browser-column', tabId: 'tab-1' });
+  it('publishes the Work location for its explicit Work request', async () => {
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'activated', host: 'main-third', location: { host: 'main-third', state: 'active' } });
     await openDocumentLocalLink({ path: '/nb/课程/任务记录.md', anchor: '结论' }, null);
     const request = peekAgentLocationRequest('/nb/课程/任务记录.md');
-    expect(request?.host).toBe('browser-column');
-    expect(request?.viewId).toBe('tab-1');
+    expect(request?.host).toBe('main-third');
+    expect(request?.viewId).toBe('main-third');
     cancelAgentLocationRequest('/nb/课程/任务记录.md');
   });
 
   it('publishes nothing without an anchor', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'main-third', state: 'active' });
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' } });
     await openDocumentLocalLink({ path: '/nb/方案.md', anchor: null }, '/nb');
     expect(peekAgentLocationRequest('/nb/方案.md')).toBeNull();
   });
 
-  it('publishes nothing when nothing was opened', async () => {
-    openExternalTarget.mockResolvedValueOnce(null);
+  it('publishes nothing when navigation is cancelled', async () => {
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' });
     await openDocumentLocalLink({ path: '/nb/方案.md', anchor: '结论' }, '/nb');
-    // openExternalTarget 的 markdown 主区分支返回 null，但内容已落 main-third，
-    // 锚点请求按 main-third 回退发布。
-    const request = peekAgentLocationRequest('/nb/方案.md');
-    expect(request?.anchor).toBe('结论');
-    expect(request?.host).toBe('main-third');
-    cancelAgentLocationRequest('/nb/方案.md');
+    expect(peekAgentLocationRequest('/nb/方案.md')).toBeNull();
   });
 });
diff --git a/app/flowix-web/features/document/use-cases/open-document-local-link.ts b/app/flowix-web/features/document/use-cases/open-document-local-link.ts
index 097d4e967..adc88e5d6 100644
--- a/app/flowix-web/features/document/use-cases/open-document-local-link.ts
+++ b/app/flowix-web/features/document/use-cases/open-document-local-link.ts
@@ -1,4 +1,4 @@
-import { openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { publishHeadingAnchorRequest } from '@features/document/use-cases/heading-anchor-publish';
 import type { ResolvedEditorLocalLink } from '@features/editor/editor-link-resolution';
 
@@ -17,6 +17,9 @@ export async function openDocumentLocalLink(
   target: ResolvedEditorLocalLink,
   scopePath: string | null,
 ): Promise<void> {
-  const opened = await openExternalTarget(target.path, { scopePath });
-  publishHeadingAnchorRequest(target.path, opened, target.anchor);
+  const opened = await openWorkspaceSurface({
+    host: 'main-third',
+    target: { kind: 'external', path: target.path, scopePath, transitionId: null },
+  });
+  publishHeadingAnchorRequest(target.path, opened.status === 'cancelled' ? null : opened.location, target.anchor);
 }
diff --git a/app/flowix-web/features/editor/code-editor.tsx b/app/flowix-web/features/editor/code-editor.tsx
index ea837493b..2a8d8a978 100644
--- a/app/flowix-web/features/editor/code-editor.tsx
+++ b/app/flowix-web/features/editor/code-editor.tsx
@@ -71,6 +71,8 @@ interface CodeEditorProps {
   onSearchPanelOpenChange?: (open: boolean) => void;
   onEditorScroll?: (scrollTop: number) => void;
   onEditingFinished?: () => void;
+  /** Whether the CodeMirror view exists and can accept editor operations. */
+  onReadyChange?: (ready: boolean) => void;
   /** Optional control rendered in the source memo's title gutter. */
   onToggleEditorMode?: () => void;
   sourceModeToggleLabel?: string;
@@ -314,6 +316,7 @@ export const CodeEditor = forwardRef<CodeEditorHandle, CodeEditorProps>(function
   onSearchPanelOpenChange,
   onEditorScroll,
   onEditingFinished,
+  onReadyChange,
   onToggleEditorMode,
   sourceModeToggleLabel,
   scrollHeader,
@@ -326,6 +329,7 @@ export const CodeEditor = forwardRef<CodeEditorHandle, CodeEditorProps>(function
   const onSearchPanelOpenChangeRef = useRef(onSearchPanelOpenChange);
   const onEditorScrollRef = useRef(onEditorScroll);
   const onEditingFinishedRef = useRef(onEditingFinished);
+  const onReadyChangeRef = useRef(onReadyChange);
   const languageCompartment = useMemo(() => new Compartment(), []);
   const editableCompartment = useMemo(() => new Compartment(), []);
   const hasScrollHeader = Boolean(scrollHeader);
@@ -341,6 +345,7 @@ export const CodeEditor = forwardRef<CodeEditorHandle, CodeEditorProps>(function
   onSearchPanelOpenChangeRef.current = onSearchPanelOpenChange;
   onEditorScrollRef.current = onEditorScroll;
   onEditingFinishedRef.current = onEditingFinished;
+  onReadyChangeRef.current = onReadyChange;
 
   useShortcutScope('editor');
 
@@ -500,6 +505,7 @@ export const CodeEditor = forwardRef<CodeEditorHandle, CodeEditorProps>(function
     });
     const view = new EditorView({ state, parent: mount });
     viewRef.current = view;
+    onReadyChangeRef.current?.(true);
 
     const handleScroll = () => onEditorScrollRef.current?.(view.scrollDOM.scrollTop);
     const handleBlur = () => onEditingFinishedRef.current?.();
@@ -513,6 +519,7 @@ export const CodeEditor = forwardRef<CodeEditorHandle, CodeEditorProps>(function
       view.contentDOM.removeEventListener('blur', handleBlur);
       view.destroy();
       viewRef.current = null;
+      onReadyChangeRef.current?.(false);
       setScrollHeaderMount(null);
     };
   }, [autoFocus, editableCompartment, filePath, handleSourceHeaderMount, languageCompartment]);
diff --git a/app/flowix-web/features/editor/code-file.test.ts b/app/flowix-web/features/editor/code-file.test.ts
index 448dca107..377071e26 100644
--- a/app/flowix-web/features/editor/code-file.test.ts
+++ b/app/flowix-web/features/editor/code-file.test.ts
@@ -16,14 +16,17 @@ describe('code file classification', () => {
     expect(isMarkdownFilePath('/notes/README.MD')).toBe(true);
     expect(isCodeTextFilePath('/src/app.tsx')).toBe(true);
     expect(isCodeTextFilePath('/data/settings.JSON')).toBe(true);
-    expect(isCodeTextFilePath('/notes/plain.txt')).toBe(true);
+    expect(isCodeTextFilePath('/notes/plain.txt')).toBe(false);
+    expect(isEditableTextFilePath('/notes/plain.txt')).toBe(true);
     expect(isCodeTextFilePath('/notes/readme.md')).toBe(false);
   });
 
-  it('rejects unknown extensions until their MIME type is known to be text', () => {
+  it('recognizes known extensionless text files and waits to inspect unknown files', () => {
     expect(isEditableTextFilePath('/assets/logo.png')).toBe(false);
-    expect(isEditableTextFilePath('/src/Makefile')).toBe(false);
-    expect(isEditableTextFilePath('/src/LICENSE')).toBe(false);
+    expect(isEditableTextFilePath('/src/Makefile')).toBe(true);
+    expect(isEditableTextFilePath('/src/Dockerfile')).toBe(true);
+    expect(isEditableTextFilePath('/src/LICENSE')).toBe(true);
+    expect(externalFileViewKind('/src/LICENSE')).toBe('code');
     expect(isEditableTextFilePath('/src/data.custom', 'text/plain')).toBe(true);
     expect(isEditableTextFilePath('/src/archive.custom', 'application/octet-stream')).toBe(false);
     expect(isTextMimeType('text/csv; charset=utf-8')).toBe(true);
diff --git a/app/flowix-web/features/editor/code-file.ts b/app/flowix-web/features/editor/code-file.ts
index baf15cd64..275f3623a 100644
--- a/app/flowix-web/features/editor/code-file.ts
+++ b/app/flowix-web/features/editor/code-file.ts
@@ -1,105 +1,45 @@
-const MARKDOWN_EXTENSIONS = new Set(['md', 'markdown']);
+import {
+  fileExtension,
+  isMarkdownFilePath,
+  isEditableTextFilePath,
+  isImageFilePath,
+  isVideoFilePath,
+  isHtmlFilePath,
+  isTextMimeType,
+} from '@features/content/model/content-kind';
+
+export {
+  fileExtension,
+  isMarkdownFilePath,
+  isCodeTextFilePath,
+  isEditableTextFilePath,
+  isImageFilePath,
+  isVideoFilePath,
+  isHtmlFilePath,
+  isNotebookResourcePath,
+  resourceKindFromPath,
+} from '@features/content/model/content-kind';
+
+export type { ResourceKind } from '@features/content/model/content-kind';
 
-const IMAGE_EXTENSIONS = new Set([
-  'png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg', 'avif', 'ico', 'tif', 'tiff', 'heic', 'heif',
-]);
-
-const VIDEO_EXTENSIONS = new Set([
-  '3gp', 'avi', 'flv', 'm2ts', 'm4v', 'mkv', 'mov', 'mp4', 'mpeg', 'mpg', 'mts', 'webm', 'wmv',
-]);
-
-export type ResourceKind = 'note' | 'image' | 'video' | 'other';
 export type ExternalFileViewKind = 'code' | 'csv' | 'markdown' | 'image' | 'video' | 'html' | 'docx' | 'unavailable';
 
-// Keep this list aligned with the extension allowlist in
-// `supported_text_document_path` in the desktop external-document command.
-// All entries, including Markdown, are rendered as source text by CodeMirror
-// when opened from the file tree. Unlisted extensions are classified by the
-// desktop MIME database before they are sent to the text editor.
-const CODE_TEXT_EXTENSIONS = new Set([
-  'txt', 'text', 'log',
-  'json', 'jsonc', 'json5', 'yaml', 'yml', 'toml', 'xml',
-  'html', 'htm', 'css', 'scss', 'sass', 'less',
-  'js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'mts', 'cts',
-  'vue', 'svelte',
-  'py', 'pyw', 'rs', 'go', 'java', 'kt', 'kts',
-  'c', 'cc', 'cpp', 'cxx', 'h', 'hh', 'hpp', 'hxx',
-  'cs', 'swift', 'php', 'rb', 'sh', 'bash', 'zsh', 'fish',
-  'sql', 'graphql', 'gql', 'lua', 'r', 'dart', 'scala',
-  'ex', 'exs', 'erl', 'hrl', 'fs', 'fsx', 'vb', 'pl', 'pm',
-  'proto', 'ini', 'conf', 'cfg', 'properties', 'gradle',
-]);
-
-export function fileExtension(path: string): string {
-  const filename = path.split(/[\\/]/).pop() ?? path;
-  const dot = filename.lastIndexOf('.');
-  if (dot <= 0 || dot === filename.length - 1) return '';
-  return filename.slice(dot + 1).toLowerCase();
-}
-
-export function isMarkdownFilePath(path: string): boolean {
-  return MARKDOWN_EXTENSIONS.has(fileExtension(path));
-}
-
-export function isCodeTextFilePath(path: string): boolean {
+/** Renderer choice belongs to the opening Surface, separate from factual content classification. */
+export function externalFileViewKind(
+  path: string,
+  mimeType?: string | null,
+  detectedTextContent = false,
+): ExternalFileViewKind {
   const extension = fileExtension(path);
-  return CODE_TEXT_EXTENSIONS.has(extension);
-}
-
-const TEXT_APPLICATION_MIME_TYPES = new Set([
-  'application/json',
-  'application/ld+json',
-  'application/xml',
-  'application/javascript',
-  'application/x-javascript',
-  'application/x-yaml',
-  'application/toml',
-  'application/sql',
-  'application/graphql',
-]);
-
-export function isTextMimeType(mimeType: string | null | undefined): boolean {
-  const mime = mimeType?.split(';', 1)[0]?.trim().toLowerCase();
-  return !!mime && (mime.startsWith('text/') || TEXT_APPLICATION_MIME_TYPES.has(mime));
-}
-
-export function isEditableTextFilePath(path: string, mimeType?: string | null): boolean {
-  return isMarkdownFilePath(path) || isCodeTextFilePath(path) || isTextMimeType(mimeType);
-}
-
-export function isImageFilePath(path: string): boolean {
-  return IMAGE_EXTENSIONS.has(fileExtension(path));
-}
-
-export function isVideoFilePath(path: string): boolean {
-  return VIDEO_EXTENSIONS.has(fileExtension(path));
-}
-
-export function isHtmlFilePath(path: string): boolean {
-  return ['html', 'htm'].includes(fileExtension(path));
-}
-
-/** Pick the view for a file opened outside the notebook memo model. */
-export function externalFileViewKind(path: string, mimeType?: string | null): ExternalFileViewKind {
-  if (fileExtension(path) === 'docx') return 'docx';
-  if (fileExtension(path) === 'csv') return 'csv';
+  if (extension === 'docx') return 'docx';
+  if (extension === 'csv') return 'csv';
   if (isImageFilePath(path)) return 'image';
   if (isVideoFilePath(path)) return 'video';
   if (isHtmlFilePath(path)) return 'html';
   if (isMarkdownFilePath(path)) return 'markdown';
-  if (isEditableTextFilePath(path, mimeType)) return 'code';
+  if (isEditableTextFilePath(path, mimeType) || detectedTextContent) return 'code';
   return 'unavailable';
 }
 
-/** Classify files shown by the notebook tree and external document view. */
-export function resourceKindFromPath(path: string): ResourceKind {
-  if (isMarkdownFilePath(path)) return 'note';
-  if (isImageFilePath(path)) return 'image';
-  if (isVideoFilePath(path)) return 'video';
-  return 'other';
-}
-
-export function isNotebookResourcePath(path: string): boolean {
-  const kind = resourceKindFromPath(path);
-  return kind === 'note' || kind === 'image' || kind === 'video';
-}
+/** Kept for API compatibility; classifier text MIME behavior is centralized in content-kind. */
+export { isTextMimeType };
diff --git a/app/flowix-web/features/editor/components/drag-context-menu/block-info.test.ts b/app/flowix-web/features/editor/components/drag-context-menu/block-info.test.ts
index 4b8fcdba5..3dbc548e8 100644
--- a/app/flowix-web/features/editor/components/drag-context-menu/block-info.test.ts
+++ b/app/flowix-web/features/editor/components/drag-context-menu/block-info.test.ts
@@ -33,9 +33,9 @@ function createEditorFixture() {
   card.className = 'agent-thread-card'
   card.dataset.agentThreadCard = 'true'
   const composer = document.createElement('div')
-  composer.className = 'agent-thread-card__composer'
+  composer.className = 'agent-composer'
   const input = document.createElement('div')
-  input.className = 'agent-thread-card__composer-input'
+  input.className = 'agent-composer__input'
   input.contentEditable = 'true'
   input.tabIndex = 0
   composer.append(input)
diff --git a/app/flowix-web/features/editor/components/drag-context-menu/block-info.ts b/app/flowix-web/features/editor/components/drag-context-menu/block-info.ts
index fe2eaed51..e66ef72fb 100644
--- a/app/flowix-web/features/editor/components/drag-context-menu/block-info.ts
+++ b/app/flowix-web/features/editor/components/drag-context-menu/block-info.ts
@@ -96,7 +96,7 @@ export function getFocusedAgentThreadCardInfo(editor: Editor): CurrentBlockInfo
   const activeElement = view.dom.ownerDocument.activeElement
   if (!(activeElement instanceof HTMLElement)) return null
 
-  const composer = activeElement.closest<HTMLElement>('.agent-thread-card__composer')
+  const composer = activeElement.closest<HTMLElement>('.agent-composer')
   if (!composer || !view.dom.contains(composer)) return null
 
   const card = composer.closest<HTMLElement>('[data-agent-thread-card="true"]')
diff --git a/app/flowix-web/features/editor/components/drag-context-menu/style.ts b/app/flowix-web/features/editor/components/drag-context-menu/style.ts
index 87891db24..e86f71a63 100644
--- a/app/flowix-web/features/editor/components/drag-context-menu/style.ts
+++ b/app/flowix-web/features/editor/components/drag-context-menu/style.ts
@@ -3,7 +3,7 @@ import type { CurrentBlockInfo } from '@features/editor/components/drag-context-
 /**
  * Y offset from block top edge, in px. Computed dynamically from the user's
  * font size / line height settings so the handle stays aligned when those
- * change. At the default `fontSize=15, lineHeight=1.8`, body text blocks use
+ * change. At the default `fontSize=16, lineHeight=1.8`, body text blocks use
  * a 27px line box and a 4.5px centered offset; heading offsets remain 5/3/3/2px
  * and scale linearly with user settings otherwise.
  *
@@ -39,7 +39,7 @@ const HEADING_LINE_HEIGHT = 1.3
 
 /**
  * 标题字号 — 走 `calc(Nrem * var(--editor-scale))`, 而
- * `--editor-scale = var(--app-font-size, 15px) / 16px`, 两者相消后
+ * `--editor-scale = var(--editor-font-size, 16px) / 16px`, 两者相消后
  * 渲染字号 = `fontSize × N` px。h5/h6 没有显式声明, 走 fallback `1`
  * (即继承 body 字号), 在 getYOffset 里会落到 body 居中分支。
  */
diff --git a/app/flowix-web/features/editor/components/slash-menu-dropdown.tsx b/app/flowix-web/features/editor/components/slash-menu-dropdown.tsx
index 786a0f012..1a62badd7 100644
--- a/app/flowix-web/features/editor/components/slash-menu-dropdown.tsx
+++ b/app/flowix-web/features/editor/components/slash-menu-dropdown.tsx
@@ -57,9 +57,7 @@ export type SlashMenuItemId =
   | 'file'
   | 'agent-thread-codex'
   | 'agent-thread-claude'
-  | 'agent-thread-gemini'
   | 'agent-thread-hermes'
-  | 'agent-thread-openclaw'
   | 'agent-thread-opencode'
   | 'agent-thread-deepseek-harness'
   | 'agent-thread-pi'
@@ -88,8 +86,6 @@ export interface SlashMenuItem {
   sectionKey?: I18nKey;
   /** 快捷键 chord ── 使用与 drag context menu 相同的显示格式。 */
   shortcut?: string;
-  /** Keep bundled agent entries visible while their runtime status is settling. */
-  alwaysVisible?: boolean;
 }
 
 export interface SlashMenuProps {
@@ -129,18 +125,14 @@ export const SLASH_MENU_ITEMS: SlashMenuItem[] = [
     keywords: ['pi', 'coding agent', 'agent', 'code', 'bianma', '任务', 'renwu', 'task'],
     icon: getAgentType('pi').icon,
     sectionKey: 'editor.slash.section.agent',
-    alwaysVisible: true,
   },
   {
     id: 'agent-thread-deepseek-harness',
-    label: getAgentType('deepseek-harness').name,
+    label: getAgentType('dsh').name,
     description: 'AI Agent',
     keywords: ['dsh', 'deepseek', 'harness', 'agent', 'code', 'bianma', '任务', 'renwu', 'task'],
-    icon: getAgentType('deepseek-harness').icon,
+    icon: getAgentType('dsh').icon,
     sectionKey: 'editor.slash.section.agent',
-    // Keep DSH discoverable before the runtime and model are configured.
-    // Selection performs the availability check and routes setup to Preferences.
-    alwaysVisible: true,
   },
   {
     id: 'agent-thread-codex',
@@ -152,10 +144,10 @@ export const SLASH_MENU_ITEMS: SlashMenuItem[] = [
   },
   {
     id: 'agent-thread-claude',
-    label: getAgentType('claude').name,
+    label: getAgentType('claudecode').name,
     description: 'AI Agent',
     keywords: ['claude', 'anthropic', 'code', 'bianma', '任务', 'renwu', 'task'],
-    icon: getAgentType('claude').icon,
+    icon: getAgentType('claudecode').icon,
     sectionKey: 'editor.slash.section.agent',
   },
   {
@@ -166,14 +158,6 @@ export const SLASH_MENU_ITEMS: SlashMenuItem[] = [
     icon: getAgentType('opencode').icon,
     sectionKey: 'editor.slash.section.agent',
   },
-  {
-    id: 'agent-thread-gemini',
-    label: getAgentType('gemini').name,
-    description: 'AI Agent',
-    keywords: ['gemini', 'google', 'cli', 'code', 'bianma', '任务', 'renwu', 'task'],
-    icon: getAgentType('gemini').icon,
-    sectionKey: 'editor.slash.section.agent',
-  },
   {
     id: 'agent-thread-hermes',
     label: getAgentType('hermes').name,
@@ -182,14 +166,6 @@ export const SLASH_MENU_ITEMS: SlashMenuItem[] = [
     icon: getAgentType('hermes').icon,
     sectionKey: 'editor.slash.section.agent',
   },
-  {
-    id: 'agent-thread-openclaw',
-    label: getAgentType('openclaw').name,
-    description: 'AI Agent',
-    keywords: ['openclaw', 'claw', 'agent', 'code', 'bianma', '任务', 'renwu', 'task'],
-    icon: getAgentType('openclaw').icon,
-    sectionKey: 'editor.slash.section.agent',
-  },
   {
     id: 'heading-1',
     label: '#',
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/index.ts b/app/flowix-web/features/editor/extensions/attachment-link/index.ts
index 11c376337..3dd24882a 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/index.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/index.ts
@@ -46,7 +46,8 @@ export const AttachmentLink = Extension.create<AttachmentUploadOptions>({
         const opts = normalizeOptions(this.options);
         return [
             createFileUploadPlugin({
-                getOwnerPath: () => this.options.getOwnerPath ? this.options.getOwnerPath() : this.options.ownerPath,
+                ownerPath: this.options.ownerPath,
+                getOwnerPath: this.options.getOwnerPath,
                 ingest: {
                     drop: opts.ingest.drop,
                     paste: false,
@@ -62,8 +63,9 @@ export const AttachmentLink = Extension.create<AttachmentUploadOptions>({
 
     addCommands() {
         return createAttachmentCommands(
-            () => this.options.getOwnerPath ? this.options.getOwnerPath() : this.options.ownerPath,
+            this.options.ownerPath,
             this.options.getNotebookId,
+            this.options.getOwnerPath,
         );
     },
 });
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/markdown/asset-markdown.ts b/app/flowix-web/features/editor/extensions/attachment-link/markdown/asset-markdown.ts
new file mode 100644
index 000000000..00fcf7cc3
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/attachment-link/markdown/asset-markdown.ts
@@ -0,0 +1,24 @@
+export function decodeStorageKey(src: string): string | null {
+  if (!src.startsWith('asset://') && !src.startsWith('http://asset.localhost/') && !src.startsWith('https://asset.localhost/')) return null;
+  try {
+    const encoded = src
+      .replace('asset://localhost/', '')
+      .replace('http://asset.localhost/', '')
+      .replace('https://asset.localhost/', '');
+    return decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+}
+
+export function assetMarkdownUrl(storageKey: string | null | undefined): string {
+  if (!storageKey) return '';
+  const encoded = encodeURIComponent(storageKey)
+    .replace(/\(/g, '%28')
+    .replace(/\)/g, '%29');
+  return `asset://localhost/${encoded}`;
+}
+
+export function isVideoUrl(src: string | null | undefined): boolean {
+  return !!src && /\.(mp4|mov|webm)(\?|$)/i.test(src);
+}
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/markdown/extensions.ts b/app/flowix-web/features/editor/extensions/attachment-link/markdown/extensions.ts
new file mode 100644
index 000000000..2219fcaa4
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/attachment-link/markdown/extensions.ts
@@ -0,0 +1,10 @@
+import { FileAttachmentMarkdownExtension } from './file-markdown';
+import { ImageMarkdownExtension } from './image-markdown';
+import { VideoMarkdownExtension } from './video-markdown';
+
+/** Parser-only attachment extensions. They deliberately have no NodeViews, commands, or Tauri imports. */
+export const AttachmentMarkdownExtensions = [
+  ImageMarkdownExtension,
+  VideoMarkdownExtension,
+  FileAttachmentMarkdownExtension,
+];
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/markdown/file-markdown.ts b/app/flowix-web/features/editor/extensions/attachment-link/markdown/file-markdown.ts
index 8eccc12c1..af7a2f5e4 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/markdown/file-markdown.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/markdown/file-markdown.ts
@@ -1,5 +1,6 @@
-import { assetMarkdownUrl, decodeStorageKey } from '@features/editor/extensions/attachment-link/utils';
-import type { JSONContent, MarkdownToken } from '@tiptap/core';
+import { Extension, type JSONContent, type MarkdownToken } from '@tiptap/core';
+import { assetMarkdownUrl, decodeStorageKey } from './asset-markdown';
+import { readMarkdownLinkDestination } from '@features/editor/extensions/shared/markdown-link-destination';
 
 export function isAttachmentMarkdownUrl(url: string): boolean {
     return /^(asset:\/\/|https?:\/\/asset\.localhost\/)/i.test(url);
@@ -29,3 +30,32 @@ export function renderFileAttachmentMarkdown(node: JSONContent) {
         : url ?? '';
     return `[${name ?? ''}](${fileUrl})`;
 }
+
+export const fileAttachmentMarkdownSpec = {
+    markdownTokenizer: {
+        name: 'fileAttachment',
+        level: 'inline' as const,
+        start(src: string) {
+            const assetLink = /\[[^\]]*\]\((?:asset:\/\/|https?:\/\/asset\.localhost\/)/.exec(src);
+            return assetLink?.index ?? -1;
+        },
+        tokenize(src: string) {
+            const closeBracket = src.indexOf(']');
+            if (!src.startsWith('[') || closeBracket === -1 || src[closeBracket + 1] !== '(') return undefined;
+            const destination = readMarkdownLinkDestination(src, closeBracket + 1);
+            if (!destination || !isAttachmentMarkdownUrl(destination.url)) return undefined;
+            return {
+                type: 'fileAttachment',
+                raw: src.slice(0, destination.end + 1),
+                url: destination.url,
+                title: src.slice(1, closeBracket),
+            };
+        },
+    },
+    parseMarkdown: parseFileAttachmentMarkdown,
+};
+
+export const FileAttachmentMarkdownExtension = Extension.create({
+    name: 'fileAttachment',
+    ...fileAttachmentMarkdownSpec,
+});
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/markdown/image-markdown.ts b/app/flowix-web/features/editor/extensions/attachment-link/markdown/image-markdown.ts
new file mode 100644
index 000000000..6b468fa5a
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/attachment-link/markdown/image-markdown.ts
@@ -0,0 +1,99 @@
+import { Extension, type MarkdownParseHelpers, type MarkdownToken } from '@tiptap/core';
+import { decodeStorageKey } from './asset-markdown';
+import { parseFlowixMediaStyleComment, parseFlowixMediaStyleSuffix } from './media-style';
+
+const MARKDOWN_IMAGE_RE = /^!\[([^\]]*)\]\(([^)\n]+)\)/;
+const ASSET_IMAGE_RE = /^(asset:\/\/|https?:\/\/asset\.localhost\/)/i;
+export const DEFAULT_IMAGE_WIDTH_PERCENT = 100;
+const MIN_IMAGE_WIDTH_PERCENT = 20;
+export const MAX_IMAGE_WIDTH_PERCENT = 100;
+
+export type ImageAlignment = 'left' | 'center' | 'right';
+
+export function isAttachmentImageHref(href: string | null | undefined): boolean {
+  return !!href && ASSET_IMAGE_RE.test(href);
+}
+
+export function normalizeWidthPercent(value: unknown): number | null {
+  if (value === null || value === undefined || value === '') return null;
+  const numeric = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(numeric)) return null;
+  return Math.round(Math.min(MAX_IMAGE_WIDTH_PERCENT, Math.max(MIN_IMAGE_WIDTH_PERCENT, numeric)) * 10) / 10;
+}
+
+export function normalizeImageAlignment(value: unknown): ImageAlignment {
+  return value === 'left' || value === 'right' ? value : 'center';
+}
+
+function parseImageSuffix(value: string): { raw: string; widthPercent: number | null; align: ImageAlignment } {
+  const modern = parseFlowixMediaStyleSuffix(value);
+  if (modern) {
+    return {
+      raw: modern.raw,
+      widthPercent: normalizeWidthPercent(modern.style.widthPercent),
+      align: normalizeImageAlignment(modern.style.align),
+    };
+  }
+  const legacy = /^\{([^}\n]+)\}/.exec(value);
+  const attributes = Object.fromEntries(
+    [...(legacy?.[1] ?? '').matchAll(/(?:^|\s)(width|align)=([^\s}]+)/g)].map(([, key, item]) => [key, item]),
+  );
+  const hasLegacyStyle = Object.keys(attributes).length > 0;
+  return {
+    raw: hasLegacyStyle ? (legacy?.[0] ?? '') : '',
+    widthPercent: normalizeWidthPercent(attributes.width?.replace('%', '')),
+    align: normalizeImageAlignment(attributes.align),
+  };
+}
+
+export const imageMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'image',
+    level: 'block' as const,
+    start(src: string) {
+      const candidateIndex = src.search(/^<!--[ \t]*flowix:media[ \t]+\{/m);
+      const candidate = candidateIndex >= 0 ? parseFlowixMediaStyleComment(src.slice(candidateIndex)) : null;
+      const commentIndex = candidate && src.slice(candidateIndex + candidate.raw.length).startsWith('![') ? candidateIndex : -1;
+      const imageIndex = src.indexOf('![');
+      if (commentIndex < 0) return imageIndex;
+      if (imageIndex < 0) return commentIndex;
+      return Math.min(commentIndex, imageIndex);
+    },
+    tokenize(src: string) {
+      const metadata = parseFlowixMediaStyleComment(src);
+      const source = metadata ? src.slice(metadata.raw.length) : src;
+      const match = MARKDOWN_IMAGE_RE.exec(source);
+      if (!match) return undefined;
+      const suffix = parseImageSuffix(source.slice(match[0].length));
+      return {
+        type: 'image',
+        raw: (metadata?.raw ?? '') + match[0] + suffix.raw,
+        href: match[2],
+        text: match[1],
+        title: null,
+        widthPercent: metadata ? normalizeWidthPercent(metadata.style.widthPercent) : suffix.widthPercent,
+        align: metadata ? normalizeImageAlignment(metadata.style.align) : suffix.align,
+      };
+    },
+  },
+  parseMarkdown(token: MarkdownToken, helpers: MarkdownParseHelpers) {
+    if (!token.href) return { type: 'text', text: token.raw || '' };
+    const commonAttrs = {
+      src: token.href,
+      alt: token.text || null,
+      title: token.title || null,
+      widthPercent: token.widthPercent ?? null,
+      align: token.align ?? 'center',
+    };
+    if (!isAttachmentImageHref(token.href)) {
+      return helpers.createNode('image', { ...commonAttrs, storageMode: null, storageKey: null });
+    }
+    return helpers.createNode('image', {
+      ...commonAttrs,
+      storageMode: 'attachment',
+      storageKey: decodeStorageKey(token.href),
+    });
+  },
+};
+
+export const ImageMarkdownExtension = Extension.create({ name: 'image', ...imageMarkdownSpec });
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/markdown/video-markdown.ts b/app/flowix-web/features/editor/extensions/attachment-link/markdown/video-markdown.ts
new file mode 100644
index 000000000..e6418e1c3
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/attachment-link/markdown/video-markdown.ts
@@ -0,0 +1,107 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+import { decodeStorageKey, isVideoUrl } from './asset-markdown';
+import { parseFlowixMediaStyleComment, parseFlowixMediaStyleSuffix } from './media-style';
+
+export type VideoAlignment = 'left' | 'center' | 'right';
+
+export function normalizeVideoAlignment(value: unknown): VideoAlignment {
+  return value === 'left' || value === 'right' ? value : 'center';
+}
+
+function parseVideoSuffix(value: string): { raw: string; align: VideoAlignment } {
+  const modern = parseFlowixMediaStyleSuffix(value);
+  if (modern) return { raw: modern.raw, align: normalizeVideoAlignment(modern.style.align) };
+  const legacy = /^\{align=(left|center|right)\}/.exec(value);
+  return { raw: legacy?.[0] ?? '', align: normalizeVideoAlignment(legacy?.[1]) };
+}
+
+function findVideoLinkStart(src: string): number {
+  let pos = 0;
+  while (pos < src.length) {
+    const openBracket = src.indexOf('[', pos);
+    if (openBracket === -1) break;
+    const closeBracket = src.indexOf(']', openBracket);
+    const openParen = src.indexOf('(', openBracket);
+    if (closeBracket === -1 || openParen === -1 || closeBracket !== openParen - 1) {
+      pos = openBracket + 1;
+      continue;
+    }
+    if (src.startsWith('asset://', openParen + 1)) return openBracket;
+    pos = openBracket + 1;
+  }
+  return -1;
+}
+
+function findClosingParen(source: string, openParen: number): number {
+  for (let index = openParen + 1; index < source.length; index += 1) {
+    if (source[index] === '%' && index + 2 < source.length && source[index + 1] === '2' && source[index + 2] === '9') {
+      index += 2;
+      continue;
+    }
+    if (source[index] === ')' && !(index > 0 && source[index - 1] === '%')) return index;
+  }
+  return -1;
+}
+
+export const videoMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'videoAttachment',
+    level: 'block' as const,
+    start(src: string) {
+      const candidateIndex = src.search(/^<!--[ \t]*flowix:media[ \t]+\{/m);
+      const candidate = candidateIndex >= 0 ? parseFlowixMediaStyleComment(src.slice(candidateIndex)) : null;
+      const commentIndex = candidate && src.slice(candidateIndex + candidate.raw.length).startsWith('[') ? candidateIndex : -1;
+      const mediaIndex = findVideoLinkStart(src);
+      if (commentIndex < 0) return mediaIndex;
+      if (mediaIndex < 0) return commentIndex;
+      return Math.min(commentIndex, mediaIndex);
+    },
+    tokenize(src: string) {
+      const metadata = parseFlowixMediaStyleComment(src);
+      const source = metadata ? src.slice(metadata.raw.length) : src;
+      if (!source.startsWith('[')) return undefined;
+      const closeBracket = source.indexOf(']');
+      if (closeBracket === -1) return undefined;
+      const openParen = source.indexOf('(', closeBracket);
+      if (openParen !== closeBracket + 1) return undefined;
+      const closePos = findClosingParen(source, openParen);
+      if (closePos === -1) return undefined;
+      const url = source.slice(openParen + 1, closePos);
+      if (!isVideoUrl(url)) return undefined;
+      const suffix = parseVideoSuffix(source.slice(closePos + 1));
+      const align = metadata ? normalizeVideoAlignment(metadata.style.align) : suffix.align;
+      return {
+        type: 'videoAttachment',
+        raw: (metadata?.raw ?? '') + source.slice(0, closePos + 1) + suffix.raw,
+        align,
+      };
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    const raw = typeof token.raw === 'string' ? token.raw : '';
+    if (raw.startsWith('!')) return { type: 'text', text: raw };
+    const firstBracket = raw.indexOf('[');
+    if (firstBracket === -1) return { type: 'text', text: raw };
+    const closeBracket = raw.indexOf(']', firstBracket + 1);
+    const openParen = raw.indexOf('(', firstBracket);
+    if (closeBracket === -1 || openParen === -1 || closeBracket !== openParen - 1) return { type: 'text', text: raw };
+    const closePos = findClosingParen(raw, openParen);
+    if (closePos === -1) return { type: 'text', text: raw };
+    const src = raw.slice(openParen + 1, closePos);
+    if (!isVideoUrl(src)) return { type: 'text', text: raw };
+    const metadata = parseFlowixMediaStyleComment(raw);
+    const suffix = parseVideoSuffix(raw.slice(closePos + 1));
+    return {
+      type: 'videoAttachment',
+      attrs: {
+        src,
+        title: raw.slice(firstBracket + 1, closeBracket),
+        storageMode: 'attachment',
+        storageKey: decodeStorageKey(src),
+        align: metadata ? normalizeVideoAlignment(metadata.style.align) : suffix.align,
+      },
+    };
+  },
+};
+
+export const VideoMarkdownExtension = Extension.create({ name: 'videoAttachment', ...videoMarkdownSpec });
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-file.ts b/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-file.ts
index 6c0adc926..ff38d359f 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-file.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-file.ts
@@ -5,13 +5,11 @@ import type { ViewMutationRecord } from '@tiptap/pm/view';
 import { Node, mergeAttributes } from '@tiptap/core';
 import { NodeSelection, Plugin, PluginKey, type EditorState } from '@tiptap/pm/state';
 import { assetUrl } from '@features/editor/extensions/attachment-link/utils';
-import { readMarkdownLinkDestination } from '@features/editor/extensions/shared/markdown-link-destination';
 import { setInlineAtomTextSelectionFromMouse } from '@features/editor/extensions/shared/inline-atom-selection';
 import { createTerminalInlineAtomCaretDecorations } from '@features/editor/extensions/shared/terminal-inline-atom-caret';
 import { dialogs } from '@platform/tauri/client';
 import {
-    isAttachmentMarkdownUrl,
-    parseFileAttachmentMarkdown,
+    fileAttachmentMarkdownSpec,
     renderFileAttachmentMarkdown,
 } from '@features/editor/extensions/attachment-link/markdown/file-markdown';
 
@@ -402,32 +400,7 @@ export const FileAttachment = Node.create({
         };
     },
 
-    markdownTokenizer: {
-        name: 'fileAttachment',
-        level: 'inline' as const,
-        start(src: string) {
-            const assetLink = /\[[^\]]*\]\((?:asset:\/\/|https?:\/\/asset\.localhost\/)/.exec(src);
-            return assetLink?.index ?? -1;
-        },
-        tokenize(src: string) {
-            const closeBracket = src.indexOf(']');
-            if (!src.startsWith('[') || closeBracket === -1 || src[closeBracket + 1] !== '(') {
-                return undefined;
-            }
-
-            const destination = readMarkdownLinkDestination(src, closeBracket + 1);
-            if (!destination || !isAttachmentMarkdownUrl(destination.url)) return undefined;
-
-            return {
-                type: 'fileAttachment',
-                raw: src.slice(0, destination.end + 1),
-                url: destination.url,
-                title: src.slice(1, closeBracket),
-            };
-        },
-    },
-
-    parseMarkdown: parseFileAttachmentMarkdown,
+    ...fileAttachmentMarkdownSpec,
 
     renderMarkdown: renderFileAttachmentMarkdown,
 });
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-image.ts b/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-image.ts
index 9de69f67b..6b52cfa0b 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-image.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-image.ts
@@ -1,31 +1,23 @@
-import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { NodeView as ProseMirrorNodeView, EditorView, Decoration } from '@tiptap/pm/view';
 import {
     Node,
     InputRule,
     mergeAttributes,
     type JSONContent,
-    type MarkdownParseHelpers,
-    type MarkdownToken,
 } from '@tiptap/core';
 import { invoke } from '@platform/tauri/core';
 import { assetMarkdownUrl, assetUrl, decodeStorageKey } from '@features/editor/extensions/attachment-link/utils';
+import { renderFlowixMediaStyleComment } from '@features/editor/extensions/attachment-link/markdown/media-style';
 import {
-    parseFlowixMediaStyleComment,
-    parseFlowixMediaStyleSuffix,
-    renderFlowixMediaStyleComment,
-} from '@features/editor/extensions/attachment-link/markdown/media-style';
+    DEFAULT_IMAGE_WIDTH_PERCENT, MAX_IMAGE_WIDTH_PERCENT, imageMarkdownSpec,
+    normalizeImageAlignment, normalizeWidthPercent,
+} from '@features/editor/extensions/attachment-link/markdown/image-markdown';
 import { translate, type I18nKey } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 
 export { decodeStorageKey };
 
-const MARKDOWN_IMAGE_RE = /^!\[([^\]]*)\]\(([^)\n]+)\)/;
-const ASSET_IMAGE_RE = /^(asset:\/\/|https?:\/\/asset\.localhost\/)/i;
-const DEFAULT_IMAGE_WIDTH_PERCENT = 100;
-const MIN_IMAGE_WIDTH_PERCENT = 20;
-const MAX_IMAGE_WIDTH_PERCENT = 100;
-
 type ImageAttributes = Record<string, unknown> & {
     src?: unknown;
     alt?: unknown;
@@ -37,8 +29,6 @@ type ImageAttributes = Record<string, unknown> & {
     align?: unknown;
 };
 
-type ImageAlignment = 'left' | 'center' | 'right';
-
 function stringAttribute(value: unknown): string {
     return typeof value === 'string' ? value : '';
 }
@@ -48,10 +38,6 @@ function tKey(key: I18nKey, params?: Record<string, string | number>): string {
     return translate(getCurrentAppLanguage(), key, params);
 }
 
-function isAttachmentImageHref(href: string | null | undefined): boolean {
-    return !!href && ASSET_IMAGE_RE.test(href);
-}
-
 function whenIdle(cb: () => void, timeout = 200): number {
     if (typeof window !== 'undefined' && typeof window.requestIdleCallback === 'function') {
         return window.requestIdleCallback(cb, { timeout }) as unknown as number;
@@ -67,42 +53,6 @@ function cancelIdle(handle: number): void {
     }
 }
 
-function normalizeWidthPercent(value: unknown): number | null {
-    if (value === null || value === undefined || value === '') return null;
-    const numeric = typeof value === 'number' ? value : Number(value);
-    if (!Number.isFinite(numeric)) return null;
-    const clamped = Math.min(MAX_IMAGE_WIDTH_PERCENT, Math.max(MIN_IMAGE_WIDTH_PERCENT, numeric));
-    return Math.round(clamped * 10) / 10;
-}
-
-function normalizeImageAlignment(value: unknown): ImageAlignment {
-    return value === 'left' || value === 'right' ? value : 'center';
-}
-
-function parseImageSuffix(value: string): { raw: string; widthPercent: number | null; align: ImageAlignment } {
-    const modern = parseFlowixMediaStyleSuffix(value);
-    if (modern) {
-        return {
-            raw: modern.raw,
-            widthPercent: normalizeWidthPercent(modern.style.widthPercent),
-            align: normalizeImageAlignment(modern.style.align),
-        };
-    }
-
-    const legacy = /^\{([^}\n]+)\}/.exec(value);
-    const attributes = Object.fromEntries(
-        [...(legacy?.[1] ?? '').matchAll(/(?:^|\s)(width|align)=([^\s}]+)/g)].map(([, key, item]) => [key, item]),
-    );
-    const hasLegacyStyle = Object.keys(attributes).length > 0;
-    return {
-        raw: hasLegacyStyle ? (legacy?.[0] ?? '') : '',
-        widthPercent: normalizeWidthPercent(attributes.width?.replace('%', '')),
-        align: normalizeImageAlignment(attributes.align),
-    };
-}
-
-// 鈹€鈹€鈹€ ImageView 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
-
 class ImageView implements ProseMirrorNodeView {
     dom: HTMLElement;
     contentDOM: HTMLElement | null = null;
@@ -592,69 +542,7 @@ export const ImageAttachment = Node.create({
         );
     },
 
-    markdownTokenizer: {
-        name: 'image',
-        level: 'block' as const,
-        start(src: string) {
-            const candidateIndex = src.search(/^<!--[ \t]*flowix:media[ \t]+\{/m);
-            const candidate = candidateIndex >= 0 ? parseFlowixMediaStyleComment(src.slice(candidateIndex)) : null;
-            const commentIndex = candidate && src.slice(candidateIndex + candidate.raw.length).startsWith('![')
-                ? candidateIndex
-                : -1;
-            const imageIndex = src.indexOf('![');
-            if (commentIndex < 0) return imageIndex;
-            if (imageIndex < 0) return commentIndex;
-            return Math.min(commentIndex, imageIndex);
-        },
-        tokenize(src: string) {
-            const metadata = parseFlowixMediaStyleComment(src);
-            const source = metadata ? src.slice(metadata.raw.length) : src;
-            const match = MARKDOWN_IMAGE_RE.exec(source);
-            if (!match) return undefined;
-            const suffix = parseImageSuffix(source.slice(match[0].length));
-            const widthPercent = metadata
-                ? normalizeWidthPercent(metadata.style.widthPercent)
-                : suffix.widthPercent;
-            const align = metadata
-                ? normalizeImageAlignment(metadata.style.align)
-                : suffix.align;
-            return {
-                type: 'image',
-                raw: (metadata?.raw ?? '') + match[0] + suffix.raw,
-                href: match[2],
-                text: match[1],
-                title: null,
-                widthPercent,
-                align,
-            };
-        },
-    },
-
-    parseMarkdown(token: MarkdownToken, helpers: MarkdownParseHelpers) {
-        if (!token.href) {
-            return { type: 'text', text: token.raw || '' };
-        }
-        if (!isAttachmentImageHref(token.href)) {
-            return helpers.createNode('image', {
-                src: token.href,
-                alt: token.text || null,
-                title: token.title || null,
-                storageMode: null,
-                storageKey: null,
-                widthPercent: token.widthPercent ?? null,
-                align: token.align ?? 'center',
-            });
-        }
-        return helpers.createNode('image', {
-            src: token.href,
-            alt: token.text || null,
-            title: token.title || null,
-            storageMode: 'attachment',
-            storageKey: decodeStorageKey(token.href),
-            widthPercent: token.widthPercent ?? null,
-            align: token.align ?? 'center',
-        });
-    },
+    ...imageMarkdownSpec,
 
     renderMarkdown(node: JSONContent) {
         const { alt, title, fileName, storageMode, storageKey, src, widthPercent, align } = node.attrs || {};
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-video.ts b/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-video.ts
index 983991c13..efbd96b62 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-video.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/nodes/view-video.ts
@@ -2,13 +2,10 @@ import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { NodeView as ProseMirrorNodeView, EditorView, Decoration } from '@tiptap/pm/view';
 import type { ViewMutationRecord } from '@tiptap/pm/view';
 import { NodeSelection } from '@tiptap/pm/state';
-import { Node, InputRule, mergeAttributes, type JSONContent, type MarkdownToken } from '@tiptap/core';
+import { Node, InputRule, mergeAttributes, type JSONContent } from '@tiptap/core';
 import { assetMarkdownUrl, assetUrl, decodeStorageKey, isVideoUrl } from '@features/editor/extensions/attachment-link/utils';
-import {
-    parseFlowixMediaStyleComment,
-    parseFlowixMediaStyleSuffix,
-    renderFlowixMediaStyleComment,
-} from '@features/editor/extensions/attachment-link/markdown/media-style';
+import { renderFlowixMediaStyleComment } from '@features/editor/extensions/attachment-link/markdown/media-style';
+import { normalizeVideoAlignment, videoMarkdownSpec } from '@features/editor/extensions/attachment-link/markdown/video-markdown';
 
 type VideoAttributes = Record<string, unknown> & {
     src?: unknown;
@@ -18,28 +15,6 @@ type VideoAttributes = Record<string, unknown> & {
     align?: unknown;
 };
 
-type VideoAlignment = 'left' | 'center' | 'right';
-
-function normalizeVideoAlignment(value: unknown): VideoAlignment {
-    return value === 'left' || value === 'right' ? value : 'center';
-}
-
-function parseVideoSuffix(value: string): { raw: string; align: VideoAlignment } {
-    const modern = parseFlowixMediaStyleSuffix(value);
-    if (modern) {
-        return {
-            raw: modern.raw,
-            align: normalizeVideoAlignment(modern.style.align),
-        };
-    }
-
-    const legacy = /^\{align=(left|center|right)\}/.exec(value);
-    return {
-        raw: legacy?.[0] ?? '',
-        align: normalizeVideoAlignment(legacy?.[1]),
-    };
-}
-
 function stringAttribute(value: unknown): string {
     return typeof value === 'string' ? value : '';
 }
@@ -484,126 +459,7 @@ export const VideoAttachment = Node.create({
         );
     },
 
-    markdownTokenizer: {
-        name: 'videoAttachment',
-        level: 'block' as const,
-        start(src: string) {
-            const candidateIndex = src.search(/^<!--[ \t]*flowix:media[ \t]+\{/m);
-            const candidate = candidateIndex >= 0 ? parseFlowixMediaStyleComment(src.slice(candidateIndex)) : null;
-            const commentIndex = candidate && src.slice(candidateIndex + candidate.raw.length).startsWith('[')
-                ? candidateIndex
-                : -1;
-            let pos = 0;
-            let mediaIndex = -1;
-            while (pos < src.length) {
-                const openBracket = src.indexOf('[', pos);
-                if (openBracket === -1) break;
-
-                const closeBracket = src.indexOf(']', openBracket);
-                const openParen = src.indexOf('(', openBracket);
-
-                if (closeBracket === -1 || openParen === -1) {
-                    pos = openBracket + 1;
-                    continue;
-                }
-
-                // Must be adjacent: ](
-                if (closeBracket !== openParen - 1) {
-                    pos = openBracket + 1;
-                    continue;
-                }
-
-                // Check if it's an asset:// video link
-                if (src.startsWith('asset://', openParen + 1)) {
-                    mediaIndex = openBracket;
-                    break;
-                }
-
-                pos = openBracket + 1;
-            }
-            if (commentIndex < 0) return mediaIndex;
-            if (mediaIndex < 0) return commentIndex;
-            return Math.min(commentIndex, mediaIndex);
-        },
-        tokenize(src: string) {
-            const metadata = parseFlowixMediaStyleComment(src);
-            const source = metadata ? src.slice(metadata.raw.length) : src;
-            // source should start with '[' — if not, this isn't a video link
-            if (!source.startsWith('[')) return undefined;
-            const closeBracket = source.indexOf(']');
-            if (closeBracket === -1) return undefined;
-            const openParen = source.indexOf('(', closeBracket);
-            if (openParen !== closeBracket + 1) return undefined;
-            // Find matching ')' handling %29 escape
-            let closePos = -1;
-            for (let i = openParen + 1; i < source.length; i++) {
-                const ch = source[i];
-                if (ch === '%' && i + 2 < source.length && source[i + 1] === '2' && source[i + 2] === '9') {
-                    i += 2;
-                    continue;
-                }
-                if (ch === ')') {
-                    if (i > 0 && source[i - 1] === '%') continue;
-                    closePos = i;
-                    break;
-                }
-            }
-            if (closePos === -1) return undefined;
-            const url = source.slice(openParen + 1, closePos);
-            if (!isVideoUrl(url)) return undefined;
-            // raw is precisely [title](url), plus the optional style metadata.
-            const suffix = parseVideoSuffix(source.slice(closePos + 1));
-            const align = metadata
-                ? normalizeVideoAlignment(metadata.style.align)
-                : suffix.align;
-            const raw = (metadata?.raw ?? '') + source.slice(0, closePos + 1) + suffix.raw;
-            return { type: 'videoAttachment', raw, align };
-        },
-    },
-
-    parseMarkdown(token: MarkdownToken) {
-        const raw = typeof token.raw === 'string' ? token.raw : '';
-        if (raw.startsWith('!')) return { type: 'text', text: raw };
-        const firstBracket = raw.indexOf('[');
-        if (firstBracket === -1) return { type: 'text', text: raw };
-        const closeBracket = raw.indexOf(']', firstBracket + 1);
-        const openParen = raw.indexOf('(', firstBracket);
-        if (closeBracket === -1 || openParen === -1 || closeBracket !== openParen - 1) {
-            return { type: 'text', text: raw };
-        }
-        const title = raw.slice(firstBracket + 1, closeBracket);
-        let closePos = -1;
-        const remaining = raw.slice(openParen + 1);
-        for (let i = 0; i < remaining.length; i++) {
-            if (remaining[i] === '%' && i + 2 < remaining.length && remaining[i + 1] === '2' && remaining[i + 2] === '9') {
-                i += 2;
-                continue;
-            }
-            if (remaining[i] === ')') {
-                if (i > 0 && remaining[i - 1] === '%') continue;
-                closePos = openParen + 1 + i;
-                break;
-            }
-        }
-        if (closePos === -1) return { type: 'text', text: raw };
-        const src = raw.slice(openParen + 1, closePos);
-        if (!isVideoUrl(src)) return { type: 'text', text: raw };
-        const metadata = parseFlowixMediaStyleComment(raw);
-        const suffix = parseVideoSuffix(raw.slice(closePos + 1));
-        const align = metadata
-            ? normalizeVideoAlignment(metadata.style.align)
-            : suffix.align;
-        return {
-            type: 'videoAttachment',
-            attrs: {
-                src,
-                title,
-                storageMode: 'attachment',
-                storageKey: decodeStorageKey(src),
-            align,
-            },
-        };
-    },
+    ...videoMarkdownSpec,
 
     renderMarkdown(node: JSONContent) {
         const { title, storageMode, storageKey, src } = node.attrs || {};
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/upload/commands.ts b/app/flowix-web/features/editor/extensions/attachment-link/upload/commands.ts
index c24cfaf80..06ac15a28 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/upload/commands.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/upload/commands.ts
@@ -35,14 +35,17 @@ function pickBrowserFiles(params: OpenFileDialogParams | undefined, signal: Abor
     });
 }
 
-export function createAttachmentCommands(getOwnerPath?: () => string | undefined, getNotebookId?: () => string | undefined): Partial<RawCommands> {
+export function createAttachmentCommands(
+    ownerPath?: string,
+    getNotebookId?: () => string | undefined,
+    getOwnerPath?: () => string | undefined,
+): Partial<RawCommands> {
+    const resolveOwnerPath = () => getOwnerPath ? getOwnerPath() : ownerPath;
     return {
         openFileDialog:
             (params?: OpenFileDialogParams) =>
             ({ editor }: { editor: Editor }) => {
                 if (editor.isDestroyed || !editor.isEditable) return false;
-                const ownerPath = getOwnerPath?.();
-                const notebookId = getNotebookId?.();
                 void runTrackedUpload(editor.view, async (signal) => {
                     if (isTauriApp()) {
                         const paths = await invoke<string[] | null>('select_files', {
@@ -50,12 +53,17 @@ export function createAttachmentCommands(getOwnerPath?: () => string | undefined
                             multiple: params?.multiple ?? true,
                         });
                         if (!paths?.length || signal.aborted) return [];
-                        return (await createAttachmentUploadFromPaths(paths, { ownerPath, notebookId, signal, deduplicate: true })).assets;
+                        return (await createAttachmentUploadFromPaths(paths, {
+                            ownerPath: resolveOwnerPath(),
+                            notebookId: getNotebookId?.(),
+                            signal,
+                            deduplicate: true,
+                        })).assets;
                     }
                     const files = await pickBrowserFiles(params, signal);
                     if (signal.aborted) return [];
-                    return (await createAttachmentUpload(files, undefined, undefined, ownerPath, signal, true)).assets;
-                }, undefined, params?.replaceRange, ownerPath);
+                    return (await createAttachmentUpload(files, undefined, undefined, resolveOwnerPath(), signal, true)).assets;
+                }, undefined, params?.replaceRange);
                 return true;
             },
 
@@ -63,7 +71,7 @@ export function createAttachmentCommands(getOwnerPath?: () => string | undefined
             (params: { files: File[]; position?: number }) =>
             ({ editor }: { editor: Editor }) => {
                 if (editor.isDestroyed || !editor.isEditable) return false;
-                void handleFileUpload(editor.view, params.files, params.position, undefined, getOwnerPath?.());
+                void handleFileUpload(editor.view, params.files, params.position, undefined, resolveOwnerPath());
                 return true;
             },
     };
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.test.ts b/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.test.ts
index c0a723313..95dc19260 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.test.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.test.ts
@@ -35,7 +35,7 @@ describe('pending upload transactions', () => {
     it('maps the captured position through edits before upload completion', async () => {
         const view = fixture();
         let complete!: (assets: StoredAsset[]) => void;
-        const upload = runTrackedUpload(view, () => new Promise((resolve) => { complete = resolve; }), 3, undefined, 'memo');
+        const upload = runTrackedUpload(view, () => new Promise((resolve) => { complete = resolve; }), 3);
         view.dispatch(view.state.tr.insertText('xx', 1));
         complete([asset]);
         await upload;
@@ -50,13 +50,13 @@ describe('pending upload transactions', () => {
         const upload = runTrackedUpload(view, (value) => {
             signal = value;
             return new Promise((resolve) => { complete = resolve; });
-        }, 3, undefined, 'memo');
+        }, 3);
         view.dispatch(view.state.tr.delete(2, 5));
         expect(signal.aborted).toBe(true);
         complete([asset]);
         await upload;
         expect(insertUploadContent).not.toHaveBeenCalled();
-        expect(recordAttachmentRecovery).toHaveBeenCalledWith(['/file'], 'memo');
+        expect(recordAttachmentRecovery).toHaveBeenCalledWith(['/file']);
     });
 
     it('aborts work when the editor is destroyed', async () => {
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.ts b/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.ts
index 29b61a779..390033836 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/upload/pending.ts
@@ -49,7 +49,6 @@ export async function runTrackedUpload(
     load: (signal: AbortSignal) => Promise<StoredAsset[]>,
     position?: number,
     range?: { from: number; to: number },
-    ownerPath?: string,
 ): Promise<void> {
     if (view.isDestroyed || !view.editable || !fileUploadPluginKey.getState(view.state)) return;
     const requestedPosition = position ?? range?.from ?? view.state.selection.from;
@@ -75,7 +74,7 @@ export async function runTrackedUpload(
     } finally {
         const newlyCreatedAssets = assets.filter((asset) => asset.created !== false);
         if (!inserted && newlyCreatedAssets.length) {
-            recordAttachmentRecovery(newlyCreatedAssets.flatMap((asset) => asset.storageKey ? [asset.storageKey] : []), ownerPath);
+            recordAttachmentRecovery(newlyCreatedAssets.flatMap((asset) => asset.storageKey ? [asset.storageKey] : []));
             reportUninsertedAttachments();
         }
         if (!view.isDestroyed) view.dispatch(view.state.tr.setMeta(fileUploadPluginKey, { remove: id }).setMeta('addToHistory', false));
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/upload/plugin.ts b/app/flowix-web/features/editor/extensions/attachment-link/upload/plugin.ts
index d13ac2e64..5b2aeacac 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/upload/plugin.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/upload/plugin.ts
@@ -19,17 +19,19 @@ export async function handleFileUpload(
 
         await runTrackedUpload(view, async (signal) =>
             (await createAttachmentUpload(filteredFiles, undefined, undefined, ownerPath, signal, true)).assets,
-        position, replaceRange, ownerPath);
+        position, replaceRange);
     } catch (err) {
         console.error('[FileUpload] Upload failed:', err);
     }
 }
 
 export function createFileUploadPlugin(options: {
+    ownerPath?: string;
     getOwnerPath?: () => string | undefined;
     ingest: { drop: boolean; paste: boolean; allowedMimeTypes?: string[] };
 }) {
     const { ingest } = options;
+    const getOwnerPath = () => options.getOwnerPath ? options.getOwnerPath() : options.ownerPath;
 
     return new Plugin({
         key: fileUploadPluginKey,
@@ -48,7 +50,7 @@ export function createFileUploadPlugin(options: {
                 event.stopPropagation();
                 const coords = { left: event.clientX, top: event.clientY };
                 const pos = view.posAtCoords(coords)?.pos;
-                handleFileUpload(view, filteredFiles, pos, undefined, options.getOwnerPath?.());
+                handleFileUpload(view, filteredFiles, pos, undefined, getOwnerPath());
                 return true;
             },
             handlePaste(view, event) {
@@ -64,7 +66,7 @@ export function createFileUploadPlugin(options: {
                 event.preventDefault();
                 event.stopPropagation();
                 const pos = view.state.selection.from;
-                handleFileUpload(view, files, pos, undefined, options.getOwnerPath?.());
+                handleFileUpload(view, files, pos, undefined, getOwnerPath());
                 return true;
             },
         },
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.test.ts b/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.test.ts
index b67a5e840..7f7527e53 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.test.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.test.ts
@@ -5,20 +5,20 @@ describe('attachment recovery records', () => {
     beforeEach(() => localStorage.clear());
 
     it('deduplicates paths without deleting files', () => {
-        expect(recordAttachmentRecovery(['/one'], 'memo-a')).toBe(true);
-        recordAttachmentRecovery(['/one', '/two'], 'memo-a');
+        expect(recordAttachmentRecovery(['/one'])).toBe(true);
+        recordAttachmentRecovery(['/one', '/two']);
         expect(readAttachmentRecovery().map((entry) => entry.path)).toEqual(['/one', '/two']);
     });
 
     it('rejects malformed persisted state', () => {
         localStorage.setItem(ATTACHMENT_RECOVERY_KEY, '{');
         expect(readAttachmentRecovery()).toEqual([]);
-        localStorage.setItem(ATTACHMENT_RECOVERY_KEY, JSON.stringify([null, { path: 42 }, { path: '/ok', memoId: 'memo', savedAt: 1 }]));
-        expect(readAttachmentRecovery()).toEqual([{ path: '/ok', memoId: 'memo', savedAt: 1 }]);
+        localStorage.setItem(ATTACHMENT_RECOVERY_KEY, JSON.stringify([null, { path: 42 }, { path: '/ok', savedAt: 1 }]));
+        expect(readAttachmentRecovery()).toEqual([{ path: '/ok', savedAt: 1 }]);
     });
 
     it('bounds retained metadata', () => {
-        recordAttachmentRecovery(Array.from({ length: 205 }, (_, index) => `/file-${index}`), 'memo');
+        recordAttachmentRecovery(Array.from({ length: 205 }, (_, index) => `/file-${index}`));
         expect(readAttachmentRecovery()).toHaveLength(200);
     });
 });
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.ts b/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.ts
index b7446353f..e80ebada0 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/upload/recovery.ts
@@ -1,22 +1,22 @@
 export const ATTACHMENT_RECOVERY_KEY = 'flowix:attachment-upload-recovery:v1';
-export type AttachmentRecovery = { path: string; memoId: string; savedAt: number };
+export type AttachmentRecovery = { path: string; savedAt: number };
 
 export function readAttachmentRecovery(): AttachmentRecovery[] {
     try {
         const value: unknown = JSON.parse(localStorage.getItem(ATTACHMENT_RECOVERY_KEY) ?? '[]');
         if (!Array.isArray(value)) return [];
         return value.filter((entry): entry is AttachmentRecovery =>
-            !!entry && typeof entry.path === 'string' && typeof entry.memoId === 'string'
+            !!entry && typeof entry.path === 'string'
             && typeof entry.savedAt === 'number' && Number.isFinite(entry.savedAt));
     } catch {
         return [];
     }
 }
 
-export function recordAttachmentRecovery(paths: string[], memoId?: string): boolean {
+export function recordAttachmentRecovery(paths: string[]): boolean {
     try {
         const entries = new Map(readAttachmentRecovery().map((entry) => [entry.path, entry]));
-        for (const path of paths) entries.set(path, { path, memoId: memoId ?? '', savedAt: Date.now() });
+        for (const path of paths) entries.set(path, { path, savedAt: Date.now() });
         localStorage.setItem(ATTACHMENT_RECOVERY_KEY, JSON.stringify(Array.from(entries.values()).slice(-200)));
         return true;
     } catch {
diff --git a/app/flowix-web/features/editor/extensions/attachment-link/utils.ts b/app/flowix-web/features/editor/extensions/attachment-link/utils.ts
index 04fc1bc93..5d1e4e57d 100644
--- a/app/flowix-web/features/editor/extensions/attachment-link/utils.ts
+++ b/app/flowix-web/features/editor/extensions/attachment-link/utils.ts
@@ -1,52 +1,27 @@
-// ─── Storage Key Utilities ─────────────────────────────────────────────────────
 import { convertFileSrc } from '@platform/tauri/core';
+import { assetMarkdownUrl, decodeStorageKey, isVideoUrl } from './markdown/asset-markdown';
 
-function isNativeEditorWebView(): boolean {
-    if (typeof window === 'undefined') return false;
-    const candidate = window as Window & {
-        webkit?: { messageHandlers?: { flowixEditor?: { postMessage?: unknown } } };
-    };
-    return typeof candidate.webkit?.messageHandlers?.flowixEditor?.postMessage === 'function';
-}
+export { assetMarkdownUrl, decodeStorageKey, isVideoUrl };
 
-export function decodeStorageKey(src: string): string | null {
-    if (!src.startsWith('asset://') && !src.startsWith('http://asset.localhost/') && !src.startsWith('https://asset.localhost/')) return null;
-    try {
-        const encoded = src
-            .replace('asset://localhost/', '')
-            .replace('http://asset.localhost/', '')
-            .replace('https://asset.localhost/', '');
-        return decodeURIComponent(encoded);
-    } catch {
-        return null;
-    }
-}
-
-export function assetMarkdownUrl(storageKey: string | null | undefined): string {
-    if (!storageKey) return '';
-    const encoded = encodeURIComponent(storageKey)
-        .replace(/\(/g, '%28')
-        .replace(/\)/g, '%29');
-    return `asset://localhost/${encoded}`;
-}
-
-// Only match actual video file extensions - NOT all asset:// URLs
-export function isVideoUrl(src: string | null | undefined): boolean {
-    if (!src) return false;
-    return /\.(mp4|mov|webm)(\?|$)/i.test(src);
+function isNativeEditorWebView(): boolean {
+  if (typeof window === 'undefined') return false;
+  const candidate = window as Window & {
+    webkit?: { messageHandlers?: { flowixEditor?: { postMessage?: unknown } } };
+  };
+  return typeof candidate.webkit?.messageHandlers?.flowixEditor?.postMessage === 'function';
 }
 
 export function assetUrl(storageKey: string | null | undefined): string {
-    if (!storageKey) return '';
-    if (isNativeEditorWebView()) {
-        const encoded = encodeURIComponent(storageKey)
-            .replace(/\(/g, '%28')
-            .replace(/\)/g, '%29');
-        return `flowix-asset://localhost/${encoded}`;
-    }
-    return convertFileSrc(storageKey);
+  if (!storageKey) return '';
+  if (isNativeEditorWebView()) {
+    const encoded = encodeURIComponent(storageKey)
+      .replace(/\(/g, '%28')
+      .replace(/\)/g, '%29');
+    return `flowix-asset://localhost/${encoded}`;
+  }
+  return convertFileSrc(storageKey);
 }
 
 export function safeFileName(name: string): string {
-    return name.replace(/[\\/:*?"<>|]/g, '_');
+  return name.replace(/[\\/:*?"<>|]/g, '_');
 }
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki-base.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki-base.ts
new file mode 100644
index 000000000..934c23a2f
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki-base.ts
@@ -0,0 +1,50 @@
+import { CodeBlock } from '@tiptap/extension-code-block';
+
+export const SHIKI_DEFAULT_THEME = 'github-light';
+export const SHIKI_DEFAULT_LANGUAGE = 'plaintext';
+const languageClassPrefix = 'language-';
+
+export interface ShikiCodeBlockOptions {
+  defaultTheme: string;
+  traceId?: number | null;
+}
+
+function getLanguageFromElement(element: HTMLElement): string | null {
+  const codeElement = element.matches('code') ? element : element.querySelector('code');
+  const languageClass = Array.from(codeElement?.classList || [])
+    .find(className => className.startsWith(languageClassPrefix));
+
+  return languageClass?.replace(languageClassPrefix, '') || null;
+}
+
+/** Document-level code-block schema and attributes, with no editor UI imports. */
+export const CodeBlockShikiBase = CodeBlock.extend<ShikiCodeBlockOptions>({
+  addOptions() {
+    return {
+      ...this.parent?.(),
+      defaultLanguage: SHIKI_DEFAULT_LANGUAGE,
+      defaultTheme: SHIKI_DEFAULT_THEME,
+      traceId: null,
+    };
+  },
+
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      language: {
+        default: SHIKI_DEFAULT_LANGUAGE,
+        parseHTML: (element) => {
+          return element.getAttribute('data-language') || getLanguageFromElement(element) || null;
+        },
+        renderHTML: (attributes) => {
+          if (attributes.language === SHIKI_DEFAULT_LANGUAGE) return {};
+          return { 'data-language': attributes.language };
+        },
+      },
+      theme: {
+        default: SHIKI_DEFAULT_THEME,
+        parseHTML: element => element.getAttribute('data-theme'),
+      },
+    };
+  },
+});
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki.ts
index b33e640f2..fff1e5ff3 100644
--- a/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki.ts
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/codeblock-shiki.ts
@@ -1,63 +1,18 @@
-import { CodeBlock } from '@tiptap/extension-code-block';
 import { createCodeBlockShikiView } from '@features/editor/extensions/codeblock-shiki/codeblock-shiki-view';
 import { proseMirrorPluginShiki } from '@features/editor/extensions/codeblock-shiki/shiki/shiki-plugin';
 import { TextSelection } from '@tiptap/pm/state';
-
-const defaultTheme = 'github-light'
-const defaultLanguage = 'plaintext'
-const languageClassPrefix = 'language-'
-
-interface ShikiCodeBlockOptions {
-  defaultTheme: string;
-  traceId?: number | null;
-}
-
-/** Shiki 主题白名单 — 与 styles/theme/*.css 中 --shiki-theme 的取值一一对应
- *  (github-light 亮色 / github-dark 暗色)。这里预加载全部 2 个, 切换主题时
- *  getDecorations() 同步可用, 无 async lag / 无 flash。 */
-const PRELOADED_SHIKI_THEMES = [
-  'github-light',
-  'github-dark',
-] as const;
-
-function getLanguageFromElement(element: HTMLElement): string | null {
-  const codeElement = element.matches('code') ? element : element.querySelector('code');
-  const languageClass = Array.from(codeElement?.classList || [])
-    .find(className => className.startsWith(languageClassPrefix));
-
-  return languageClass?.replace(languageClassPrefix, '') || null;
-}
-
-export const CodeBlockShiki = CodeBlock.extend<ShikiCodeBlockOptions>({
-  addOptions() {
-    return {
-      ...this.parent?.(),
-      defaultLanguage,
-      defaultTheme,
-      traceId: null,
-    };
-  },
-
-  addAttributes() {
-    return {
-      ...this.parent?.(),
-      language: {
-        default: defaultLanguage,
-        parseHTML: (element) => {
-          return element.getAttribute('data-language') || getLanguageFromElement(element) || null;
-        },
-        renderHTML: (attributes) => {
-          if (attributes.language === defaultLanguage) return {};
-          return { 'data-language': attributes.language };
-        },
-      },
-      theme: {
-        default: defaultTheme,
-        parseHTML: element => element.getAttribute('data-theme'),
-      },
-    };
-  },
-
+import {
+  CodeBlockShikiBase,
+  SHIKI_DEFAULT_LANGUAGE,
+  SHIKI_DEFAULT_THEME,
+  type ShikiCodeBlockOptions,
+} from './codeblock-shiki-base';
+
+/** Shiki themes preloaded for synchronous theme changes after editor mount. */
+const PRELOADED_SHIKI_THEMES = ['github-light', 'github-dark'] as const;
+
+/** Browser editor behavior layered over the worker-safe document extension. */
+export const CodeBlockShiki = CodeBlockShikiBase.extend<ShikiCodeBlockOptions>({
   addNodeView() {
     return (...args) => createCodeBlockShikiView(...args);
   },
@@ -95,8 +50,8 @@ export const CodeBlockShiki = CodeBlock.extend<ShikiCodeBlockOptions>({
       ...plugins,
       proseMirrorPluginShiki({
         name: this.name,
-        defaultLanguage,
-        defaultTheme,
+        defaultLanguage: SHIKI_DEFAULT_LANGUAGE,
+        defaultTheme: SHIKI_DEFAULT_THEME,
         preloadThemes: [...PRELOADED_SHIKI_THEMES],
         traceId: this.options.traceId,
       }),
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.test.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.test.ts
index 99abbc609..1db5114d8 100644
--- a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.test.ts
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.test.ts
@@ -1,27 +1,7 @@
 import { Schema } from '@tiptap/pm/model'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 
-vi.mock(
-  '@features/editor/extensions/codeblock-shiki/shiki/shiki-highlighter',
-  () => ({
-    getShiki: () => ({
-      codeToTokensBase: (code: string) => (
-        code.split('\n').map((line) => (
-          line
-            ? [
-                { color: '#ffffff', content: '' },
-                { color: '#ffffff', content: line },
-              ]
-            : []
-        ))
-      ),
-      getLoadedLanguages: () => ['javascript', 'mermaid'],
-      getLoadedThemes: () => ['github-light'],
-    }),
-  }),
-)
-
-import { getDecorations } from './shiki-decorations'
+import { createShikiDecorationSet, getDecorations } from './shiki-decorations'
 
 const schema = new Schema({
   nodes: {
@@ -47,12 +27,30 @@ describe('Shiki code block decorations', () => {
     )
     const doc = schema.node('doc', null, [codeBlock])
 
-    const decorations = getDecorations({
+    const inputs = [{
+      from: 1,
+      text: 'alpha\nbeta\ngamma',
+      language: 'javascript',
+      theme: 'github-light',
+    }]
+    const decorations = createShikiDecorationSet(
       doc,
-      name: 'codeBlock',
-      defaultLanguage: 'plaintext',
-      defaultTheme: 'github-light',
-    }).find()
+      {
+        doc,
+        name: 'codeBlock',
+        defaultLanguage: 'plaintext',
+        defaultTheme: 'github-light',
+      },
+      inputs,
+      [{
+        from: 1,
+        lines: [
+          [{ content: 'alpha', color: '#ffffff' }],
+          [{ content: 'beta', color: '#ffffff' }],
+          [{ content: 'gamma', color: '#ffffff' }],
+        ],
+      }],
+    ).find()
 
     expect(decorations).toHaveLength(3)
     expect(decorations.every(({ from, to }) => from < to)).toBe(true)
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.ts
index 9539ddef6..0938d385f 100644
--- a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.ts
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-decorations.ts
@@ -4,7 +4,7 @@ import type { BundledLanguage, BundledTheme } from 'shiki'
 import { findChildren } from '@tiptap/core'
 import { Decoration, DecorationSet } from '@tiptap/pm/view'
 
-import { getShiki } from '@features/editor/extensions/codeblock-shiki/shiki/shiki-highlighter'
+import { getShikiLanguageDefinition } from '@features/editor/extensions/codeblock-shiki/shiki/shiki-languages'
 
 interface DecorationsOptions {
   doc: ProseMirrorNode
@@ -13,6 +13,24 @@ interface DecorationsOptions {
   defaultLanguage: BundledLanguage | 'plaintext' | null | undefined
 }
 
+export interface ShikiHighlightInput {
+  /** ProseMirror position immediately inside the codeBlock node. */
+  from: number
+  text: string
+  language: string
+  theme: string
+}
+
+export interface ShikiHighlightToken {
+  content: string
+  color: string
+}
+
+export interface ShikiHighlightBlockResult {
+  from: number
+  lines: ShikiHighlightToken[][]
+}
+
 // Shiki exposes VS Code TextMate's FontStyle as a bit mask:
 // italic = 1, bold = 2, underline = 4, strikethrough = 8.
 // Keep the conversion local so the editor only needs the token data and does
@@ -221,12 +239,9 @@ function getMermaidDecorations(
 // 长时间占用。缓存读取结果, 把读路径退化成一个普通变量访问, 消
 // 除 reflow。
 //
-// 失效时机 ── 由 shiki-plugin.ts 在 view() 挂载时挂 per-editor
-// 'app-theme-changed' 监听器, 切主题时同步 invalidate + dispatch
-// forceDecoration 触发 apply 重算。本模块自身不挂监听器 ── 缓存
-// 与失效职责分离: 本文件管「读 + 缓存 + 暴露失效接口」, plugin
-// 决定「何时失效」(只有 plugin 持有 editorView 引用, 才能在失
-// 效后强制刷新装饰)。
+// 失效时机 ── 由 shiki-plugin.ts 在 view() 挂载时监听
+// 'app-theme-changed'。切主题后由 plugin 安排 Worker 重算装饰。
+// 本模块只负责读取缓存并提供失效接口。
 let cachedCssTheme: string | null | undefined = undefined
 
 function readCssTheme(): string {
@@ -241,36 +256,43 @@ function readCssTheme(): string {
   return cachedCssTheme ?? ''
 }
 
-/** 失效缓存 ── 由 shiki-plugin 在收到 app-theme-changed 时调用,
- *  并伴随一次 shikiPluginForceDecoration dispatch 强制刷新装饰。
- *  Export 是因为 plugin 是同模块的兄弟文件, 需要 import 这个
- *  失效函数。 */
+/** Invalidate the cached CSS theme before the Worker recomputes decorations. */
 export function invalidateShikiThemeCache() {
   cachedCssTheme = undefined
 }
 
-export function getDecorations({
+export function collectShikiHighlightInputs({
   doc,
   name,
   defaultTheme,
-  defaultLanguage
-}: DecorationsOptions) {
-  const decorations: Decoration[] = []
-  const highlighter = getShiki()
+  defaultLanguage,
+}: DecorationsOptions): { codeBlockCount: number; blocks: ShikiHighlightInput[] } {
+  let codeBlockCount = 0
+  const blocks: ShikiHighlightInput[] = []
+  const cssTheme = readCssTheme()
+
+  findChildren(doc, node => node.type.name === name).forEach((block) => {
+    codeBlockCount += 1
+    const rawLanguage = String(block.node.attrs.language || defaultLanguage || 'plaintext')
+    if (rawLanguage.toLowerCase() === 'mermaid') return
+    const language = getShikiLanguageDefinition(rawLanguage)?.id ?? 'plaintext'
+    blocks.push({
+      from: block.pos + 1,
+      text: block.node.textContent,
+      language,
+      theme: cssTheme || block.node.attrs.theme || defaultTheme,
+    })
+  })
 
-  // During the synchronous editor mount Shiki has not loaded yet. Avoid
-  // traversing every code block just to return no decorations.
-  if (!highlighter) return DecorationSet.empty
+  return { codeBlockCount, blocks }
+}
 
+export function getDecorations({ doc, name, defaultTheme }: DecorationsOptions) {
+  const decorations: Decoration[] = []
   const codeBlocks = findChildren(doc, node => node.type.name === name)
 
   codeBlocks.forEach((block) => {
-    let language = block.node.attrs.language || defaultLanguage
-
-    if (!highlighter.getLoadedLanguages().includes(language)) {
-      language = 'plaintext'
-    }
-
+    if ((block.node.attrs.language || '').toLowerCase() !== 'mermaid') return
     let theme = block.node.attrs.theme || defaultTheme
     // Theme resolution: the --shiki-theme CSS var (app theme) is authoritative
     // whenever set — which is always, so node.attrs.theme / defaultTheme only act
@@ -279,41 +301,40 @@ export function getDecorations({
     // 读路径走 readCssTheme() 缓存, 避免每个 keystroke 触发 getComputedStyle 强制 reflow。
     const cssTheme = readCssTheme()
     if (cssTheme) theme = cssTheme as BundledTheme
-    const themeToApply = highlighter.getLoadedThemes().includes(theme)
-      ? theme
-      : highlighter.getLoadedThemes()[0]
+    decorations.push(...getMermaidDecorations(block, theme))
+  })
 
-    if ((block.node.attrs.language || '').toLowerCase() === 'mermaid') {
-      decorations.push(...getMermaidDecorations(block, themeToApply))
-      return
-    }
+  return DecorationSet.create(doc, decorations)
+}
 
-    const lines = highlighter.codeToTokensBase(block.node.textContent, {
-      lang: language,
-      theme: themeToApply
-    })
+export function createShikiDecorationSet(
+  doc: ProseMirrorNode,
+  options: DecorationsOptions,
+  inputs: readonly ShikiHighlightInput[],
+  results: readonly ShikiHighlightBlockResult[],
+): DecorationSet {
+  const decorations: Decoration[] = []
+  const resultsByPosition = new Map(results.map((result) => [result.from, result]))
 
-    let from = block.pos + 1
+  for (const input of inputs) {
+    const node = doc.nodeAt(input.from - 1)
+    if (!node || node.type.name !== options.name || node.textContent !== input.text) continue
+    const result = resultsByPosition.get(input.from)
+    if (!result) continue
 
-    lines.forEach((lineTokens, lineIndex) => {
+    let from = input.from
+    result.lines.forEach((lineTokens, lineIndex) => {
       for (const token of lineTokens) {
-        if (token.content.length === 0) continue
-
+        if (!token.content.length) continue
         const to = from + token.content.length
-
-        const decoration = Decoration.inline(from, to, {
-          style: `color: ${token.color}`
-        })
-
-        decorations.push(decoration)
+        decorations.push(Decoration.inline(from, to, {
+          style: `color: ${token.color}`,
+        }))
         from = to
       }
-
-      // ProseMirror text positions include the newline between Shiki lines.
-      // Do not advance past the end of the final line.
-      if (lineIndex < lines.length - 1) from += 1
+      if (lineIndex < result.lines.length - 1) from += 1
     })
-  })
+  }
 
-  return DecorationSet.create(doc, decorations)
+  return getDecorations(options).add(doc, decorations)
 }
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-plugin.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-plugin.ts
index 35ac79036..c9530eb7b 100644
--- a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-plugin.ts
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-plugin.ts
@@ -3,9 +3,14 @@ import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
 import type { EditorView } from '@tiptap/pm/view'
 
 import { Plugin, PluginKey } from '@tiptap/pm/state'
-
-import { getDecorations, invalidateShikiThemeCache } from '@features/editor/extensions/codeblock-shiki/shiki/shiki-decorations'
-import { getShiki, initHighlighter } from '@features/editor/extensions/codeblock-shiki/shiki/shiki-highlighter'
+import { DecorationSet } from '@tiptap/pm/view'
+
+import {
+  collectShikiHighlightInputs,
+  createShikiDecorationSet,
+  invalidateShikiThemeCache,
+} from '@features/editor/extensions/codeblock-shiki/shiki/shiki-decorations'
+import { tokenizeCodeBlocksInWorker } from './shiki-worker-client'
 import { transactionNeedsShikiLoad, transactionTouchesCodeBlock } from './shiki-transaction-scope'
 import { markDocumentOpenTrace } from '@/lib/document-open-perf'
 import { notifyCodeBlockThemeChange } from '../theme-coordinator'
@@ -18,24 +23,6 @@ export interface PluginShikiOptions {
   traceId?: number | null
 }
 
-// ── apply() 辅助 ────────────────────────────────────────────────────
-//
-// 旧实现 [findChildren(doc) × 2 + oldNodes.some(node => range ⊆ step)]
-// 每次 transaction 走两遍完整 doc tree, 大文档 (数千节点) 时不算
-// 便宜 ── 100 keystrokes/秒 × 2000 visits = 200K visits/秒, 长期
-// 跑能吃掉可观的主线程预算。
-//
-// 新实现换成范围受限的遍历:
-// 每个 StepMap 同时给出变更前、后的局部范围。分别检查 step 前后的
-// 文档即可覆盖代码块内部编辑、创建、删除和替换，不需要为每次普通
-// 输入统计新旧全文中的代码块数量。
-//
-// 顺带修正一个潜在正确性 bug: 旧检查 node.pos >= step.from &&
-// node.pos + nodeSize <= step.to 是「代码块 ⊆ step」语义 ── 只捕
-// 代码块删除; 代码块**内部编辑** (step 范围 < 代码块范围) 漏判,
-// 依赖 condition A (selection 在代码块内) 兜底。新检查是范围相交,
-// 两种语义同时覆盖, 即使将来有非交互式 transform 修改代码块内容
-// 也能正确触发 rAF。
 function countCodeBlocks(doc: ProseMirrorNode, typeName: string): number {
   let count = 0
   doc.descendants((node) => {
@@ -45,182 +32,156 @@ function countCodeBlocks(doc: ProseMirrorNode, typeName: string): number {
 }
 
 interface ShikiPluginState {
-  decorations: ReturnType<typeof getDecorations>
+  decorations: DecorationSet
   loadVersion: number
 }
 
-export function proseMirrorPluginShiki(options: PluginShikiOptions) {
-  const { name, defaultLanguage, defaultTheme, preloadThemes = [], traceId = null } = options
+const SHIKI_DECORATIONS_META = 'shikiPluginWorkerDecorations'
 
-  // ── rAF 批处理 ────────────────────────────────────────────────
-  //
-  // 代码块内容变化的 keystroke 路径上, apply() 把昂贵的 getDecorations()
-  // (全量 tokenize + 重建 DecorationSet) 改成「延迟到下一帧」: 同
-  // 一帧内多个 keystroke 共用一次 tokenize, apply() 同步路径只返
-  // 回 mapped set (positions 跟着 transaction.mapping 走, colors
-  // 暂时 stale), 视觉延迟 < 16ms 不可察觉, 但避免单帧多次 tokenize
-  // 串联阻断主线程 ── 1000 行代码块连续输入时从「每键 50–200ms」变
-  // 成「每帧 1 次」。
-  //
-  // state 闭包 ── 每个 proseMirrorPluginShiki() 实例持有自己的
-  // currentView / pendingRaf, 多编辑器场景不互相干扰。
+export function proseMirrorPluginShiki(options: PluginShikiOptions) {
+  const { name, defaultLanguage, defaultTheme, traceId = null } = options
   let currentView: EditorView | null = null
   let pendingRaf: number | null = null
-
-  const flushRecompute = () => {
-    // 先清 pendingRaf 再 dispatch ── 万一 dispatch 触发嵌套调用
-    // scheduleRecompute, 状态机不会卡死。
-    pendingRaf = null
-    if (!currentView || currentView.isDestroyed) return
-    currentView.dispatch(
-      currentView.state.tr.setMeta('shikiPluginForceDecoration', true)
-    )
-  }
-
-  const scheduleRecompute = () => {
-    if (pendingRaf !== null) return
-    pendingRaf = requestAnimationFrame(flushRecompute)
-  }
+  let requestWorkerRecompute: (() => void) | null = null
 
   const shikiPlugin: Plugin = new Plugin({
     key: new PluginKey('codeBlockShiki'),
 
     state: {
-      init: (_, { doc }) => {
-        return {
-          decorations: getDecorations({ doc, name, defaultLanguage, defaultTheme }),
-          loadVersion: 0,
-        } satisfies ShikiPluginState
-      },
+      // Parsing and initial editor mount should not traverse or tokenize the
+      // full document. The worker computes decorations after the view exists.
+      init: () => ({
+        decorations: DecorationSet.empty,
+        loadVersion: 0,
+      } satisfies ShikiPluginState),
 
       apply: (transaction, pluginState, oldState, newState) => {
+        const workerDecorations = transaction.getMeta(SHIKI_DECORATIONS_META) as DecorationSet | undefined
+        if (workerDecorations) {
+          return {
+            decorations: workerDecorations,
+            loadVersion: pluginState.loadVersion,
+          } satisfies ShikiPluginState
+        }
+
         const oldNodeName = oldState.selection.$head.parent.type.name
         const newNodeName = newState.selection.$head.parent.type.name
-
-        // didChangeSomeCodeBlock 两条短路 OR, 任一为真即触发重算:
-        //   A: selection 跨代码块 (光标进/出) ── 不需要扫 doc
-        //   B: step 前后任一局部变更范围相交代码块 ── 覆盖内容编辑、
-        //      创建、删除和替换，只遍历变更范围而非整篇 doc。
         let didChangeSomeCodeBlock = false
         let needsShikiLoad = false
         if (transaction.docChanged) {
-          if ([oldNodeName, newNodeName].includes(name)) {
-            didChangeSomeCodeBlock = true
-          } else {
-            didChangeSomeCodeBlock = transactionTouchesCodeBlock(transaction, name)
-          }
+          didChangeSomeCodeBlock = [oldNodeName, newNodeName].includes(name)
+            || transactionTouchesCodeBlock(transaction, name)
           needsShikiLoad = transactionNeedsShikiLoad(transaction, name)
         }
 
-        // 强制刷新路径 ── rAF 批处理触发 / highlighter 加载完成 /
-        // 外部显式调用 forceDecoration。同步执行, 不再 batched, 确
-        // 保调用方看到的 DecorationSet 立即反映 doc 状态。
-        if (transaction.getMeta('shikiPluginForceDecoration')) {
-          // 当前 transaction 已经把 doc 同步 tokenize 了一遍, 任何
-          // 之前因 keystroke 排上的 rAF 都已无意义 ── 取消掉, 避
-          // 免 rAF 触发后再跑一次相同输入的 getDecorations。
-          if (pendingRaf !== null) {
-            cancelAnimationFrame(pendingRaf)
+        if (didChangeSomeCodeBlock && pendingRaf === null) {
+          pendingRaf = requestAnimationFrame(() => {
             pendingRaf = null
-          }
-          return {
-            decorations: getDecorations({
-              doc: transaction.doc,
-              name,
-              defaultLanguage,
-              defaultTheme
-            }),
-            loadVersion: pluginState.loadVersion,
-          } satisfies ShikiPluginState
-        }
-
-        // 代码块内容变化 ── 排到下一帧统一重新计算, 当前 transaction
-        // 同步路径返回 mapped set 即可, 避免在 keystroke 回调栈里
-        // 跑全量 tokenize。
-        if (didChangeSomeCodeBlock) {
-          scheduleRecompute()
+            requestWorkerRecompute?.()
+          })
         }
 
         return {
           decorations: pluginState.decorations.map(transaction.mapping, transaction.doc),
           loadVersion: pluginState.loadVersion + (needsShikiLoad ? 1 : 0),
         } satisfies ShikiPluginState
-      }
+      },
     },
 
     props: {
       decorations(state) {
         return shikiPlugin.getState(state).decorations
-      }
+      },
     },
 
-    // Lazy Shiki bootstrap: editor mount stays synchronous. Only documents that
-    // actually contain code blocks import Shiki and load grammars/themes.
     view(editorView) {
       currentView = editorView
       let cancelled = false
-      let pending = false
+      let running = false
       let needsRerun = false
       let idleId: number | null = null
       let timeoutId: ReturnType<typeof setTimeout> | null = null
 
-      const forceDecorations = () => {
-        if (cancelled) return
-        editorView.dispatch(
-          editorView.state.tr.setMeta('shikiPluginForceDecoration', true)
-        )
-      }
-
-      // ── 主题切换响应 ──────────────────────────────────────────
-      // cssTheme 缓存 (shiki-decorations.ts) 把 getComputedStyle 从
-      // hot path 上拿掉, 但缓存只在下次 getDecorations 才会被消费,
-      // 而 getDecorations 只在 apply() 触发时跑 ── 用户切完主题
-      // 若不再输入, apply() 不跑, 装饰颜色就停留在旧值。
-      //
-      // 这里在 view() 挂 per-editor 监听器, 主题切换时:
-      //   1. invalidateShikiThemeCache() ── 清缓存, 下次 getDecorations
-      //      强制重新读 --shiki-theme (拿新主题)
-      //   2. forceDecorations() ── 派发 shikiPluginForceDecoration,
-      //      触发一次 apply() 同步重算, 把新主题应用到所有现有装饰
-      //
-      // destroy() 时同步 removeEventListener, 不留 zombie listener。
-      const handleThemeChange = () => {
+      const scheduleRecompute = () => {
         if (cancelled) return
-        invalidateShikiThemeCache()
-        notifyCodeBlockThemeChange(editorView)
-        forceDecorations()
+        if (running) {
+          needsRerun = true
+          return
+        }
+        void recomputeDecorations()
       }
-      window.addEventListener('app-theme-changed', handleThemeChange)
+      requestWorkerRecompute = scheduleRecompute
 
-      const loadForCurrentDoc = async () => {
-        if (cancelled || pending) return
-        pending = true
+      const recomputeDecorations = async () => {
+        if (cancelled || running || editorView.isDestroyed) return
+        running = true
         needsRerun = false
-        markDocumentOpenTrace(traceId, 'shiki:init-start', {
-          codeBlockCount: countCodeBlocks(editorView.state.doc, name),
+        const documentSnapshot = editorView.state.doc
+        const startedAt = performance.now()
+        const { codeBlockCount, blocks } = collectShikiHighlightInputs({
+          doc: documentSnapshot,
+          name,
+          defaultLanguage,
+          defaultTheme,
+        })
+        markDocumentOpenTrace(traceId, 'shiki:worker-start', {
+          codeBlockCount,
+          highlightedBlockCount: blocks.length,
+          contentChars: documentSnapshot.textContent.length,
         })
+
         try {
-          await initHighlighter({
-            doc: editorView.state.doc,
-            name,
-            language: defaultLanguage ?? null,
-            theme: defaultTheme,
-            themes: preloadThemes,
+          const reply = await tokenizeCodeBlocksInWorker(blocks)
+          if (cancelled || editorView.isDestroyed) return
+          if (editorView.state.doc !== documentSnapshot) {
+            needsRerun = true
+            return
+          }
+
+          const decorations = createShikiDecorationSet(
+            documentSnapshot,
+            { doc: documentSnapshot, name, defaultLanguage, defaultTheme },
+            blocks,
+            reply.blocks ?? [],
+          )
+          editorView.dispatch(editorView.state.tr.setMeta(SHIKI_DECORATIONS_META, decorations))
+          const elapsedMs = Math.round((performance.now() - startedAt) * 10) / 10
+          const tokenCount = (reply.blocks ?? []).reduce((count, block) => (
+            count + block.lines.reduce((lineCount, line) => lineCount + line.length, 0)
+          ), 0)
+          console.info('[perf:open-doc]', 'Shiki:worker-tokenize', {
+            elapsedMs,
+            workerMs: reply.workerMs,
+            codeBlockCount,
+            highlightedBlockCount: blocks.length,
+            tokenCount,
+            contentChars: documentSnapshot.textContent.length,
+          })
+          markDocumentOpenTrace(traceId, 'shiki:worker-ready', {
+            elapsedMs,
+            workerMs: reply.workerMs,
+            codeBlockCount,
+            highlightedBlockCount: blocks.length,
+            tokenCount,
           })
-          markDocumentOpenTrace(traceId, 'shiki:ready')
-          forceDecorations()
           markDocumentOpenTrace(traceId, 'shiki:first-decoration')
-        } catch (err) {
-          console.error('[CodeBlockShiki] failed to initialize highlighter:', err)
+        } catch (error) {
+          console.error('[CodeBlockShiki] worker tokenization failed:', error)
+          markDocumentOpenTrace(traceId, 'shiki:worker-error', {
+            error: error instanceof Error ? error.message : String(error),
+          })
         } finally {
-          pending = false
-          if (needsRerun) scheduleLoad()
+          running = false
+          if (needsRerun && !cancelled) {
+            needsRerun = false
+            scheduleRecompute()
+          }
         }
       }
 
       const scheduleLoad = () => {
         if (cancelled) return
-        if (pending) {
+        if (running) {
           needsRerun = true
           return
         }
@@ -229,27 +190,41 @@ export function proseMirrorPluginShiki(options: PluginShikiOptions) {
         if ('requestIdleCallback' in window) {
           idleId = window.requestIdleCallback(() => {
             idleId = null
-            void loadForCurrentDoc()
+            scheduleRecompute()
           }, { timeout: 1200 })
         } else {
           timeoutId = globalThis.setTimeout(() => {
             timeoutId = null
-            void loadForCurrentDoc()
+            scheduleRecompute()
           }, 300)
         }
       }
 
-      if (countCodeBlocks(editorView.state.doc, name) > 0) scheduleLoad()
+      const handleThemeChange = () => {
+        if (cancelled) return
+        invalidateShikiThemeCache()
+        notifyCodeBlockThemeChange(editorView)
+        scheduleRecompute()
+      }
+      window.addEventListener('app-theme-changed', handleThemeChange)
+
+      const initialCodeBlockCount = countCodeBlocks(editorView.state.doc, name)
+      if (initialCodeBlockCount > 0) {
+        markDocumentOpenTrace(traceId, 'shiki:init-start', { codeBlockCount: initialCodeBlockCount })
+        scheduleLoad()
+      }
 
       return {
-        update(view, prevState) {
-          const docChanged = prevState.doc !== view.state.doc
-          if (!docChanged && getShiki()) return
-          const previousPluginState = shikiPlugin.getState(prevState)
+        update(view, previousState) {
+          const docChanged = previousState.doc !== view.state.doc
+          if (running && docChanged) needsRerun = true
+
+          const previousPluginState = shikiPlugin.getState(previousState)
           const currentPluginState = shikiPlugin.getState(view.state)
           if (currentPluginState.loadVersion !== previousPluginState.loadVersion) {
             scheduleLoad()
           }
+
         },
         destroy() {
           cancelled = true
@@ -262,15 +237,15 @@ export function proseMirrorPluginShiki(options: PluginShikiOptions) {
             globalThis.clearTimeout(timeoutId)
             timeoutId = null
           }
-          // 编辑器销毁时取消未触发的 rAF, 防止回调里访问已销毁的 view。
           if (pendingRaf !== null) {
             cancelAnimationFrame(pendingRaf)
             pendingRaf = null
           }
           if (currentView === editorView) currentView = null
-        }
+          if (requestWorkerRecompute === scheduleRecompute) requestWorkerRecompute = null
+        },
       }
-    }
+    },
   })
 
   return shikiPlugin
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-tokenizer.worker.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-tokenizer.worker.ts
new file mode 100644
index 000000000..a5b82d48e
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-tokenizer.worker.ts
@@ -0,0 +1,104 @@
+import type { BundledLanguage, BundledTheme } from 'shiki'
+import type { LanguageRegistration } from '@shikijs/types'
+import { createHighlighterCore } from 'shiki/core'
+import { createOnigurumaEngine } from 'shiki/engine/oniguruma'
+
+import {
+  getShikiLanguageDefinition,
+  SHIKI_THEMES,
+} from './shiki-languages'
+import type {
+  ShikiHighlightBlockResult,
+  ShikiHighlightInput,
+  ShikiHighlightToken,
+} from './shiki-decorations'
+
+type WorkerHighlighter = Awaited<ReturnType<typeof createHighlighterCore>>
+
+interface WorkerRequest {
+  id: number
+  blocks: ShikiHighlightInput[]
+}
+
+let highlighter: WorkerHighlighter | undefined
+let highlighterPromise: Promise<WorkerHighlighter> | undefined
+const languagePromises = new Map<string, Promise<void>>()
+
+function getHighlighter(): Promise<WorkerHighlighter> {
+  if (highlighter) return Promise.resolve(highlighter)
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighterCore({
+      themes: SHIKI_THEMES,
+      langs: [],
+      engine: createOnigurumaEngine(import('shiki/wasm')),
+    }).then((created) => {
+      highlighter = created
+      return created
+    }).catch((error) => {
+      highlighterPromise = undefined
+      throw error
+    })
+  }
+  return highlighterPromise
+}
+
+async function ensureLanguage(
+  instance: WorkerHighlighter,
+  language: string,
+): Promise<void> {
+  const definition = getShikiLanguageDefinition(language)
+  if (!definition || instance.getLoadedLanguages().includes(definition.id)) return
+  let pending = languagePromises.get(definition.id)
+  if (!pending) {
+    pending = definition.load().then(async (registrations: LanguageRegistration[]) => {
+      await instance.loadLanguage(...registrations)
+    }).finally(() => {
+      languagePromises.delete(definition.id)
+    })
+    languagePromises.set(definition.id, pending)
+  }
+  await pending
+}
+
+async function tokenize(blocks: readonly ShikiHighlightInput[]): Promise<ShikiHighlightBlockResult[]> {
+  const instance = await getHighlighter()
+  await Promise.all([...new Set(blocks.map((block) => block.language))]
+    .map((language) => ensureLanguage(instance, language)))
+
+  return blocks.map((block) => {
+    const theme = instance.getLoadedThemes().includes(block.theme as BundledTheme)
+      ? block.theme as BundledTheme
+      : instance.getLoadedThemes()[0]
+    const language = instance.getLoadedLanguages().some((loadedLanguage) => loadedLanguage === block.language)
+      ? block.language
+      : 'plaintext'
+    const lines = instance.codeToTokensBase(block.text, {
+      lang: language as BundledLanguage,
+      theme,
+    })
+    const resultLines: ShikiHighlightToken[][] = lines.map((line) => line.map((token) => ({
+      content: token.content,
+      color: token.color ?? '',
+    })))
+    return { from: block.from, lines: resultLines }
+  })
+}
+
+self.addEventListener('message', (event: MessageEvent<WorkerRequest>) => {
+  const { id, blocks } = event.data
+  const startedAt = performance.now()
+  void tokenize(blocks).then((results) => {
+    self.postMessage({
+      id,
+      ok: true,
+      blocks: results,
+      workerMs: Math.round((performance.now() - startedAt) * 10) / 10,
+    })
+  }).catch((error) => {
+    self.postMessage({
+      id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  })
+})
diff --git a/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-worker-client.ts b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-worker-client.ts
new file mode 100644
index 000000000..83b82b292
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/codeblock-shiki/shiki/shiki-worker-client.ts
@@ -0,0 +1,65 @@
+import type {
+  ShikiHighlightBlockResult,
+  ShikiHighlightInput,
+} from './shiki-decorations'
+
+interface WorkerReply {
+  id: number
+  ok: boolean
+  blocks?: ShikiHighlightBlockResult[]
+  workerMs?: number
+  error?: string
+}
+
+let worker: Worker | null = null
+let nextRequestId = 0
+const pending = new Map<number, {
+  resolve: (reply: WorkerReply) => void
+  reject: (error: Error) => void
+}>()
+
+function failWorker(error: Error): void {
+  for (const request of pending.values()) request.reject(error)
+  pending.clear()
+  worker?.terminate()
+  worker = null
+}
+
+function getWorker(): Worker {
+  if (worker) return worker
+  worker = new Worker(new URL('./shiki-tokenizer.worker.ts', import.meta.url), { type: 'module' })
+  worker.addEventListener('message', (event: MessageEvent<WorkerReply>) => {
+    const request = pending.get(event.data.id)
+    if (!request) return
+    pending.delete(event.data.id)
+    if (event.data.ok) request.resolve(event.data)
+    else request.reject(new Error(event.data.error ?? 'Shiki worker failed'))
+  })
+  worker.addEventListener('error', (event) => {
+    failWorker(new Error(event.message || 'Shiki worker crashed'))
+  })
+  worker.addEventListener('messageerror', () => {
+    failWorker(new Error('Shiki worker returned an unreadable result'))
+  })
+  return worker
+}
+
+export function tokenizeCodeBlocksInWorker(
+  blocks: readonly ShikiHighlightInput[],
+): Promise<WorkerReply> {
+  if (blocks.length === 0) {
+    return Promise.resolve({ id: 0, ok: true, blocks: [], workerMs: 0 })
+  }
+  if (typeof Worker === 'undefined') return Promise.reject(new Error('Web Workers are unavailable'))
+
+  const id = ++nextRequestId
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject })
+    try {
+      getWorker().postMessage({ id, blocks })
+    } catch (error) {
+      pending.delete(id)
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
+  })
+}
diff --git a/app/flowix-web/features/editor/extensions/frontmatter-markdown.ts b/app/flowix-web/features/editor/extensions/frontmatter-markdown.ts
new file mode 100644
index 000000000..dc1ddfd5a
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/frontmatter-markdown.ts
@@ -0,0 +1,34 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+
+// Consume a BOM at the file boundary and the legacy displaced-BOM position.
+const FRONTMATTER_TOKEN_RE = /^\uFEFF?(?:[ \t]*\r?\n)*---\r?\n([\s\S]*?)\r?\n---(?:\r?\n\uFEFF?|$)/;
+
+export const frontmatterMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'frontmatter',
+    level: 'block' as const,
+    start(src: string) {
+      return /^\uFEFF?(?:[ \t]*\r?\n)*---/.test(src) ? 0 : -1;
+    },
+    tokenize(src: string, tokens?: unknown[]): { type: string; raw: string } | undefined {
+      if (tokens && tokens.length > 0) return undefined;
+      const match = FRONTMATTER_TOKEN_RE.exec(src);
+      return match ? { type: 'frontmatter', raw: match[0] } : undefined;
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    const raw = token.raw ?? '';
+    const match = FRONTMATTER_TOKEN_RE.exec(raw);
+    if (!match) return { type: 'text', text: raw };
+    return {
+      type: 'frontmatter',
+      attrs: { yamlContent: match[1].trim() },
+    };
+  },
+};
+
+export const FrontmatterMarkdownExtension = Extension.create({
+  name: 'frontmatter',
+  priority: 1000,
+  ...frontmatterMarkdownSpec,
+});
diff --git a/app/flowix-web/features/editor/extensions/frontmatter-node-view.ts b/app/flowix-web/features/editor/extensions/frontmatter-node-view.ts
index 74608ee67..6c5166d88 100644
--- a/app/flowix-web/features/editor/extensions/frontmatter-node-view.ts
+++ b/app/flowix-web/features/editor/extensions/frontmatter-node-view.ts
@@ -372,7 +372,7 @@ export class FrontmatterPropertyNodeView implements NodeView {
       case 'duplicate-key':
         return this.t('document.properties.duplicateKey');
       case 'reserved-key':
-        return this.t('document.properties.picker.reservedKeyError', { key: 'flowix_key' });
+        return this.t('document.properties.picker.reservedKeyError', { key: 'flowix_property_types' });
       case 'invalid-tag':
         return this.t('document.properties.invalidTag');
       case 'invalid-color':
@@ -1174,7 +1174,7 @@ export class FrontmatterPropertyNodeView implements NodeView {
     const createControl = (kind: PropertyEditKind, value: string): PropertyEditControl => {
       if (kind === 'Boolean') {
         const label = createElement('label', 'frontmatter-property__edit-checkbox-label');
-        const checkbox = createElement('input', 'frontmatter-property__edit-checkbox');
+        const checkbox = createElement('input', 'frontmatter-property__edit-checkbox flowix-hand-checkbox-input');
         checkbox.type = 'checkbox';
         checkbox.checked = value.trim() === 'true';
         checkbox.setAttribute('aria-label', property.key);
@@ -1495,7 +1495,7 @@ export class FrontmatterPropertyNodeView implements NodeView {
           return createSelectControl(value);
         }
         const label = createElement('label', 'frontmatter-property__edit-checkbox-label');
-        const checkbox = createElement('input', 'frontmatter-property__edit-checkbox');
+        const checkbox = createElement('input', 'frontmatter-property__edit-checkbox flowix-hand-checkbox-input');
         checkbox.type = 'checkbox';
         checkbox.checked = value.trim() === 'true';
         checkbox.setAttribute('aria-label', property.key);
@@ -2001,7 +2001,7 @@ export class FrontmatterPropertyNodeView implements NodeView {
     }
 
     if (kind === 'boolean') {
-      const checkbox = createElement('input', 'frontmatter-property__value-checkbox');
+      const checkbox = createElement('input', 'frontmatter-property__value-checkbox flowix-hand-checkbox-input');
       checkbox.type = 'checkbox';
       checkbox.checked = property.value === true;
       checkbox.disabled = !this.view.editable;
diff --git a/app/flowix-web/features/editor/extensions/frontmatter-property.test.ts b/app/flowix-web/features/editor/extensions/frontmatter-property.test.ts
index b453582be..5e17c61de 100644
--- a/app/flowix-web/features/editor/extensions/frontmatter-property.test.ts
+++ b/app/flowix-web/features/editor/extensions/frontmatter-property.test.ts
@@ -49,11 +49,11 @@ describe('frontmatter property helpers', () => {
     });
   });
 
-  it('reorders visible properties while keeping the system key in place', () => {
+  it('reorders ordinary YAML properties', () => {
     const yaml = 'flowix_key: ra61em97\nfirst: one\nsecond: two\nthird: three';
     const reordered = reorderVisibleFrontmatterProperty(yaml, 'first', 'third', 'after');
     expect([...parseVisibleFrontmatter(reordered).properties].map(({ key }) => key))
-      .toEqual(['second', 'third', 'first']);
+      .toEqual(['flowix_key', 'second', 'third', 'first']);
     expect(reordered.indexOf('flowix_key: ra61em97'))
       .toBeLessThan(reordered.indexOf('second: two'));
   });
@@ -77,7 +77,7 @@ describe('frontmatter property helpers', () => {
     const content = '\n  \n---\nflowix_key: abc12345\nstatus: draft\n---\n# Body';
     const extracted = extractFrontmatter(content);
     expect(extracted.hasFrontmatter).toBe(true);
-    expect(extracted.userData).toEqual({ status: 'draft' });
+    expect(extracted.userData).toEqual({ flowix_key: 'abc12345', status: 'draft' });
     expect(extracted.body).toBe('# Body');
 
     const editor = new Editor({
@@ -92,32 +92,38 @@ describe('frontmatter property helpers', () => {
     editor.destroy();
   });
 
-  it('skips the system key and returns every property from the first group', () => {
+  it('returns historical identity fields as ordinary YAML properties', () => {
     const result = parseVisibleFrontmatter('flowix_key: ra61em97\nstatus: in-progress\nkeywords: [推广, 归类]');
 
-    expect(result.firstProperty).toEqual({ key: 'status', value: 'in-progress' });
+    expect(result.firstProperty).toEqual({ key: 'flowix_key', value: 'ra61em97' });
     expect(result.properties).toEqual([
+      { key: 'flowix_key', value: 'ra61em97' },
       { key: 'status', value: 'in-progress' },
       { key: 'keywords', value: ['推广', '归类'] },
     ]);
     expect(result.userData).toEqual({
+      flowix_key: 'ra61em97',
       status: 'in-progress',
       keywords: ['推广', '归类'],
     });
   });
 
-  it('returns an empty visible property when frontmatter only has the system key', () => {
+  it('returns the historical identity field as a visible property', () => {
     const result = parseVisibleFrontmatter('flowix_key: ra61em97');
 
-    expect(result.firstProperty).toBeNull();
+    expect(result.firstProperty).toEqual({ key: 'flowix_key', value: 'ra61em97' });
+    expect(result.properties).toEqual([{ key: 'flowix_key', value: 'ra61em97' }]);
     expect(result.parseError).toBeNull();
   });
 
-  it('hides the deprecated legacy key from visible properties', () => {
+  it('returns the deprecated legacy key as an ordinary property', () => {
     const result = parseVisibleFrontmatter('key: legacy-id\nstatus: draft');
 
-    expect(result.properties).toEqual([{ key: 'status', value: 'draft' }]);
-    expect(result.userData).toEqual({ status: 'draft' });
+    expect(result.properties).toEqual([
+      { key: 'key', value: 'legacy-id' },
+      { key: 'status', value: 'draft' },
+    ]);
+    expect(result.userData).toEqual({ key: 'legacy-id', status: 'draft' });
   });
 
   it('suggests moving the malformed suffix into the document body', () => {
@@ -171,12 +177,13 @@ describe('frontmatter property helpers', () => {
     expect(result).toContain('stage: in-progress');
     expect(result).toContain('keywords: [ 推广, 归类 ]');
     expect(parseVisibleFrontmatter(result).userData).toEqual({
+      flowix_key: 'ra61em97',
       stage: 'in-progress',
       keywords: ['推广', '归类'],
     });
   });
 
-  it('adds a first user property after the system key', () => {
+  it('adds a property while preserving the historical identity field', () => {
     const result = updateVisibleFrontmatterProperty(
       'flowix_key: ra61em97',
       null,
@@ -185,16 +192,20 @@ describe('frontmatter property helpers', () => {
     );
 
     expect(result).toBe('flowix_key: ra61em97\nstatus: todo');
-    expect(parseVisibleFrontmatter(result).userData).toEqual({ status: 'todo' });
+    expect(parseVisibleFrontmatter(result).userData).toEqual({ flowix_key: 'ra61em97', status: 'todo' });
   });
 
-  it('rejects editing the system key', () => {
-    expect(() => updateVisibleFrontmatterProperty(
+  it('allows editing historical identity field names as ordinary properties', () => {
+    const result = updateVisibleFrontmatterProperty(
       'flowix_key: ra61em97',
       null,
       'key',
       'another-id',
-    )).toThrow(/managed by Flowix/);
+    );
+    expect(parseVisibleFrontmatter(result).userData).toEqual({
+      flowix_key: 'ra61em97',
+      key: 'another-id',
+    });
   });
 
   it('formats collections as a compact single line', () => {
@@ -1229,9 +1240,8 @@ describe('frontmatter property helpers', () => {
       detail: { propertyTargetId: 'file:display-frontmatter', keys },
     }));
 
-    // User properties are reported. `flowix_key` (the system key) is excluded
-    // by `parseVisibleFrontmatter`, matching the preset lists it feeds.
-    expect(new Set(keys)).toEqual(new Set(['status', 'tags']));
+    // Historical identity keys are ordinary frontmatter properties.
+    expect(new Set(keys)).toEqual(new Set(['flowix_key', 'status', 'tags']));
 
     // A query aimed at another target must not be answered by this view.
     const otherKeys: string[] = [];
diff --git a/app/flowix-web/features/editor/extensions/frontmatter.ts b/app/flowix-web/features/editor/extensions/frontmatter.ts
index d36d35c3f..5d292dfbb 100644
--- a/app/flowix-web/features/editor/extensions/frontmatter.ts
+++ b/app/flowix-web/features/editor/extensions/frontmatter.ts
@@ -7,11 +7,7 @@ import { FrontmatterPropertyNodeView } from '@features/editor/extensions/frontma
 import { updateVisibleFrontmatterProperty } from '@features/document/properties/frontmatter-model';
 import { resolvePropertyPreset } from '@features/document/properties/presets';
 import { getPropertyPresets } from '@features/properties/public-api';
-
-// Consume a BOM both at the true file boundary and immediately after the
-// frontmatter block. The latter repairs legacy imports where key injection
-// displaced the UTF-8 signature into the Markdown body.
-const FRONTMATTER_TOKEN_RE = /^\uFEFF?(?:[ \t]*\r?\n)*---\r?\n([\s\S]*?)\r?\n---(?:\r?\n\uFEFF?|$)/;
+import { frontmatterMarkdownSpec } from './frontmatter-markdown';
 
 const Frontmatter = Node.create({
   name: 'frontmatter',
@@ -123,28 +119,7 @@ const Frontmatter = Node.create({
     ];
   },
 
-  markdownTokenizer: {
-    name: 'frontmatter',
-    level: 'block',
-    start(src: string) {
-      return /^\uFEFF?(?:[ \t]*\r?\n)*---/.test(src) ? 0 : -1;
-    },
-    tokenize(src: string, tokens?: unknown[]): { type: string; raw: string } | undefined {
-      if (tokens && tokens.length > 0) return undefined;
-      const match = FRONTMATTER_TOKEN_RE.exec(src);
-      return match ? { type: 'frontmatter', raw: match[0] } : undefined;
-    },
-  },
-
-  parseMarkdown(token) {
-    const raw = token.raw ?? '';
-    const match = FRONTMATTER_TOKEN_RE.exec(raw);
-    if (!match) return { type: 'text', text: raw };
-    return {
-      type: 'frontmatter',
-      attrs: { yamlContent: match[1].trim() },
-    };
-  },
+  ...frontmatterMarkdownSpec,
 
   renderMarkdown(node) {
     return `---\n${String(node.attrs?.yamlContent ?? '')}\n---\n`;
diff --git a/app/flowix-web/features/editor/extensions/markdown-link-markdown.ts b/app/flowix-web/features/editor/extensions/markdown-link-markdown.ts
new file mode 100644
index 000000000..b230a1e46
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/markdown-link-markdown.ts
@@ -0,0 +1,117 @@
+import { Extension, type MarkdownParseHelpers, type MarkdownToken, type PasteRuleMatch, type InputRuleMatch } from '@tiptap/core';
+import { isVideoUrl } from '@features/editor/extensions/attachment-link/markdown/asset-markdown';
+import { sanitizeLinkHref } from '@/lib/safe-link';
+
+interface ParsedMarkdownLink {
+  raw: string;
+  text: string;
+  href: string;
+  title: string | null;
+}
+
+const ASSET_URL_RE = /^(asset:\/\/|https?:\/\/asset\.localhost\/)/i;
+const MARKDOWN_LINK_RE = /!?\[([^\]\n]+)\]\(([^)\n]+)\)/g;
+const FLOWIX_MEMO_URL_RE = /^flowix:\/\/memo\/.*$/i;
+
+export function normalizePlainLinkHref(url: string | null | undefined): string {
+  const safeHref = sanitizeLinkHref(url);
+  if (!safeHref) return '';
+  const trimmed = safeHref.trim();
+  if (!trimmed) return '';
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return trimmed;
+  if (trimmed.startsWith('//')) return `http:${trimmed}`;
+  if (trimmed.startsWith('#') || trimmed.startsWith('/') || trimmed.startsWith('?')) return trimmed;
+  return `http://${trimmed}`;
+}
+
+function stripAngleBracketDestination(destination: string): string {
+  return destination.startsWith('<') && destination.endsWith('>')
+    ? destination.slice(1, -1).trim()
+    : destination;
+}
+
+function normalizeMarkdownDestination(url: string | null | undefined): string {
+  const safeHref = sanitizeLinkHref(url);
+  if (!safeHref) return '';
+  const destination = stripAngleBracketDestination(safeHref);
+  if (!destination || /^[a-z][a-z0-9+.-]*:/i.test(destination) || destination.startsWith('//')) {
+    return normalizePlainLinkHref(destination);
+  }
+  return destination;
+}
+
+export function isPlainMarkdownLinkUrl(url: string | null | undefined): boolean {
+  if (!url || FLOWIX_MEMO_URL_RE.test(url) || ASSET_URL_RE.test(url) || isVideoUrl(url)) return false;
+  return true;
+}
+
+function stripOptionalTitle(destination: string): { href: string; title: string | null } {
+  const trimmed = destination.trim();
+  const bracketTitleMatch = /^<(.+)>\s+["']([^"']*)["']$/.exec(trimmed);
+  if (bracketTitleMatch) {
+    return { href: normalizeMarkdownDestination(bracketTitleMatch[1]), title: bracketTitleMatch[2] || null };
+  }
+  const titleMatch = /^(\S+)\s+["']([^"']*)["']$/.exec(trimmed);
+  if (!titleMatch) return { href: normalizeMarkdownDestination(trimmed), title: null };
+  return { href: normalizeMarkdownDestination(titleMatch[1]), title: titleMatch[2] || null };
+}
+
+function parseMarkdownLinkMatch(match: RegExpExecArray): ParsedMarkdownLink | null {
+  const raw = match[0];
+  if (raw.startsWith('!')) return null;
+  const text = match[1]?.trim();
+  const { href, title } = stripOptionalTitle(match[2] ?? '');
+  if (!text || !isPlainMarkdownLinkUrl(href)) return null;
+  return { raw, text, href, title };
+}
+
+export function findLastMarkdownLink(text: string): InputRuleMatch | null {
+  let found: InputRuleMatch | null = null;
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  for (const match of text.matchAll(MARKDOWN_LINK_RE)) {
+    if (match.index === undefined) continue;
+    const parsed = parseMarkdownLinkMatch(match);
+    if (!parsed || match.index + parsed.raw.length !== text.length) continue;
+    found = {
+      index: match.index,
+      text: parsed.raw,
+      replaceWith: parsed.text,
+      data: { href: parsed.href, title: parsed.title },
+    };
+  }
+  return found;
+}
+
+export function findMarkdownLinkPasteMatches(text: string): PasteRuleMatch[] {
+  const matches: PasteRuleMatch[] = [];
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  for (const match of text.matchAll(MARKDOWN_LINK_RE)) {
+    if (match.index === undefined) continue;
+    const parsed = parseMarkdownLinkMatch(match);
+    if (!parsed) continue;
+    matches.push({
+      index: match.index,
+      text: parsed.raw,
+      replaceWith: parsed.text,
+      data: { href: parsed.href, title: parsed.title },
+    });
+  }
+  return matches;
+}
+
+export const markdownLinkMarkdownSpec = {
+  parseMarkdown(token: MarkdownToken, helpers: MarkdownParseHelpers) {
+    if (!isPlainMarkdownLinkUrl(token.href)) return null;
+    return helpers.applyMark('link', helpers.parseInline(token.tokens || []), {
+      href: normalizeMarkdownDestination(token.href),
+      title: token.title || null,
+    });
+  },
+};
+
+// @ts-expect-error The Markdown runtime accepts null to let subsequent handlers process non-link tokens.
+export const MarkdownLinkParserExtension = Extension.create({
+  name: 'link',
+  priority: 50,
+  ...markdownLinkMarkdownSpec,
+});
diff --git a/app/flowix-web/features/editor/extensions/markdown-link.ts b/app/flowix-web/features/editor/extensions/markdown-link.ts
index c24102c2a..c98533f1c 100644
--- a/app/flowix-web/features/editor/extensions/markdown-link.ts
+++ b/app/flowix-web/features/editor/extensions/markdown-link.ts
@@ -1,173 +1,27 @@
 import Link from '@tiptap/extension-link';
-import { Extension, markInputRule, markPasteRule, type InputRuleMatch, type MarkdownParseHelpers, type MarkdownToken, type PasteRuleMatch } from '@tiptap/core';
+import { Extension, markInputRule, markPasteRule } from '@tiptap/core';
 import { Plugin, PluginKey } from '@tiptap/pm/state';
 import { Decoration, DecorationSet } from '@tiptap/pm/view';
-import { isVideoUrl } from '@features/editor/extensions/attachment-link/utils';
-import { sanitizeLinkHref } from '@/lib/safe-link';
-
-interface ParsedMarkdownLink {
-  raw: string;
-  text: string;
-  href: string;
-  title: string | null;
-}
-
-const ASSET_URL_RE = /^(asset:\/\/|https?:\/\/asset\.localhost\/)/i;
-const MARKDOWN_LINK_RE = /!?\[([^\]\n]+)\]\(([^)\n]+)\)/g;
-const FLOWIX_MEMO_URL_RE = /^flowix:\/\/memo\/.*$/i;
+import {
+  findLastMarkdownLink,
+  findMarkdownLinkPasteMatches,
+  markdownLinkMarkdownSpec,
+} from './markdown-link-markdown';
+export {
+  findMarkdownLinkPasteMatches,
+  isPlainMarkdownLinkUrl,
+  normalizePlainLinkHref,
+} from './markdown-link-markdown';
 
 export const linkSelectionHighlightPluginKey = new PluginKey<DecorationSet>('linkSelectionHighlight');
 
-export function normalizePlainLinkHref(url: string | null | undefined): string {
-  const safeHref = sanitizeLinkHref(url);
-  if (!safeHref) return '';
-  const trimmed = safeHref.trim();
-  if (!trimmed) return '';
-
-  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
-    return trimmed;
-  }
-
-  if (trimmed.startsWith('//')) {
-    return `http:${trimmed}`;
-  }
-
-  if (trimmed.startsWith('#') || trimmed.startsWith('/') || trimmed.startsWith('?')) {
-    return trimmed;
-  }
-
-  return `http://${trimmed}`;
-}
-
-function stripOptionalTitle(destination: string): { href: string; title: string | null } {
-  const trimmed = destination.trim();
-
-  // `<destination> "title"` form — the bracketed destination itself may
-  // contain spaces, so the plain `\S+` title regex would split it wrongly.
-  const bracketTitleMatch = /^<(.+)>\s+["']([^"']*)["']$/.exec(trimmed);
-  if (bracketTitleMatch) {
-    return {
-      href: normalizeMarkdownDestination(bracketTitleMatch[1]),
-      title: bracketTitleMatch[2] || null,
-    };
-  }
-
-  const titleMatch = /^(\S+)\s+["']([^"']*)["']$/.exec(trimmed);
-
-  if (!titleMatch) {
-    return { href: normalizeMarkdownDestination(trimmed), title: null };
-  }
-
-  return {
-    href: normalizeMarkdownDestination(titleMatch[1]),
-    title: titleMatch[2] || null,
-  };
-}
-
-/**
- * CommonMark strict destination: `<...>` guards spaces and parens. The
- * delimiters must not reach the stored href, otherwise strict links like
- * `[x](<../计划表.csv>)` would later be prefixed with `http://` as if they
- * were bare domains.
- */
-function stripAngleBracketDestination(destination: string): string {
-  return destination.startsWith('<') && destination.endsWith('>')
-    ? destination.slice(1, -1).trim()
-    : destination;
-}
-
-function normalizeMarkdownDestination(url: string | null | undefined): string {
-  const safeHref = sanitizeLinkHref(url);
-  if (!safeHref) return '';
-  const destination = stripAngleBracketDestination(safeHref);
-  if (!destination || /^[a-z][a-z0-9+.-]*:/i.test(destination) || destination.startsWith('//')) {
-    return normalizePlainLinkHref(destination);
-  }
-  return destination;
-}
-
-export function isPlainMarkdownLinkUrl(url: string | null | undefined): boolean {
-  if (!url) return false;
-  if (FLOWIX_MEMO_URL_RE.test(url)) return false;
-  if (ASSET_URL_RE.test(url)) return false;
-  if (isVideoUrl(url)) return false;
-  return true;
-}
-
-function parseMarkdownLinkMatch(match: RegExpExecArray): ParsedMarkdownLink | null {
-  const raw = match[0];
-  if (raw.startsWith('!')) return null;
-
-  const text = match[1]?.trim();
-  const { href, title } = stripOptionalTitle(match[2] ?? '');
-
-  if (!text || !isPlainMarkdownLinkUrl(href)) {
-    return null;
-  }
-
-  return { raw, text, href, title };
-}
-
-function findLastMarkdownLink(text: string): InputRuleMatch | null {
-  let found: InputRuleMatch | null = null;
-  MARKDOWN_LINK_RE.lastIndex = 0;
-
-  for (const match of text.matchAll(MARKDOWN_LINK_RE)) {
-    if (match.index === undefined) continue;
-    const parsed = parseMarkdownLinkMatch(match);
-    if (!parsed) continue;
-    if (match.index + parsed.raw.length !== text.length) continue;
-
-    found = {
-      index: match.index,
-      text: parsed.raw,
-      replaceWith: parsed.text,
-      data: { href: parsed.href, title: parsed.title },
-    };
-  }
-
-  return found;
-}
-
-export function findMarkdownLinkPasteMatches(text: string): PasteRuleMatch[] {
-  const matches: PasteRuleMatch[] = [];
-  MARKDOWN_LINK_RE.lastIndex = 0;
-
-  for (const match of text.matchAll(MARKDOWN_LINK_RE)) {
-    if (match.index === undefined) continue;
-    const parsed = parseMarkdownLinkMatch(match);
-    if (!parsed) continue;
-
-    matches.push({
-      index: match.index,
-      text: parsed.raw,
-      replaceWith: parsed.text,
-      data: { href: parsed.href, title: parsed.title },
-    });
-  }
-
-  return matches;
-}
-
+// @ts-expect-error The Markdown runtime accepts null to let subsequent handlers process non-link tokens.
 export const MarkdownLink = Link.extend({
   priority: 50,
-
-  // @ts-expect-error Tiptap's runtime explicitly accepts null to let the next
-  // registered token handler try, but MarkdownParseResult omits null.
-  parseMarkdown(token: MarkdownToken, helpers: MarkdownParseHelpers) {
-    if (!isPlainMarkdownLinkUrl(token.href)) {
-      return null;
-    }
-
-    return helpers.applyMark('link', helpers.parseInline(token.tokens || []), {
-      href: normalizeMarkdownDestination(token.href),
-      title: token.title || null,
-    });
-  },
+  ...markdownLinkMarkdownSpec,
 
   addInputRules() {
     const parentRules = this.parent?.() ?? [];
-
     return [
       markInputRule({
         find: findLastMarkdownLink,
@@ -183,7 +37,6 @@ export const MarkdownLink = Link.extend({
 
   addPasteRules() {
     const parentRules = this.parent?.() ?? [];
-
     return [
       markPasteRule({
         find: findMarkdownLinkPasteMatches,
diff --git a/app/flowix-web/features/editor/extensions/math-block-markdown.ts b/app/flowix-web/features/editor/extensions/math-block-markdown.ts
new file mode 100644
index 000000000..079ccedf9
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/math-block-markdown.ts
@@ -0,0 +1,48 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+
+const BLOCK_MATH_RE = /^\$\$\s*\n?([\s\S]*?)\n?\s*\$\$(?:\n|$)/;
+
+export function normalizeLatex(value: unknown): string {
+  if (typeof value !== 'string') return '';
+
+  let normalized = value.trim();
+  let unwrapped = true;
+  while (unwrapped) {
+    unwrapped = false;
+    const bracketed = /^\\\[\s*([\s\S]*?)\s*\\\]$/.exec(normalized);
+    if (bracketed) {
+      normalized = bracketed[1].trim();
+      unwrapped = true;
+      continue;
+    }
+    const dollarWrapped = /^\$\$\s*([\s\S]*?)\s*\$\$$/.exec(normalized);
+    if (dollarWrapped) {
+      normalized = dollarWrapped[1].trim();
+      unwrapped = true;
+    }
+  }
+  return normalized;
+}
+
+export const mathBlockMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'mathBlock',
+    level: 'block' as const,
+    start(src: string) {
+      return src.indexOf('$$');
+    },
+    tokenize(src: string) {
+      const match = BLOCK_MATH_RE.exec(src);
+      if (!match) return undefined;
+      return { type: 'mathBlock', raw: match[0], text: match[1] };
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    return { type: 'mathBlock', attrs: { latex: normalizeLatex(token.text) } };
+  },
+};
+
+export const MathBlockMarkdownExtension = Extension.create({
+  name: 'mathBlock',
+  ...mathBlockMarkdownSpec,
+});
diff --git a/app/flowix-web/features/editor/extensions/math-block.ts b/app/flowix-web/features/editor/extensions/math-block.ts
index bd78bcdde..ac16d081a 100644
--- a/app/flowix-web/features/editor/extensions/math-block.ts
+++ b/app/flowix-web/features/editor/extensions/math-block.ts
@@ -1,7 +1,10 @@
-import { Node as TiptapNode, mergeAttributes, type JSONContent, type MarkdownToken } from '@tiptap/core';
+import { Node as TiptapNode, mergeAttributes, type JSONContent } from '@tiptap/core';
+import { mathBlockMarkdownSpec, normalizeLatex } from './math-block-markdown';
 import { translate, type I18nKey } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 
+export { normalizeLatex };
+
 // katex + 其 CSS 动态 import (独立 chunk, 首个数学块渲染时加载)。
 // 参照 codeblock-shiki/mermaid-renderer.ts 的懒加载模式。
 type KatexModule = typeof import('katex');
@@ -32,42 +35,12 @@ declare module '@tiptap/core' {
 
 const DEFAULT_LATEX = '';
 const PLACEHOLDER_LATEX = '\\frac{a}{b}';
-const BLOCK_MATH_RE = /^\$\$\s*\n?([\s\S]*?)\n?\s*\$\$(?:\n|$)/;
 
 // NodeView 不在 React 树内, 不能用 useI18n, 走 user-settings-store 直读当前语言。
 function tKey(key: I18nKey, params?: Record<string, string | number>): string {
   return translate(getCurrentAppLanguage(), key, params);
 }
 
-export function normalizeLatex(value: unknown): string {
-  if (typeof value !== 'string') return '';
-
-  let normalized = value.trim();
-
-  // The math-block input stores the formula body, while users commonly paste
-  // a complete display-math snippet from Markdown/MathJax. Accept both forms
-  // at the boundary and keep the node attribute canonical.
-  let unwrapped = true;
-  while (unwrapped) {
-    unwrapped = false;
-
-    const bracketed = /^\\\[\s*([\s\S]*?)\s*\\\]$/.exec(normalized);
-    if (bracketed) {
-      normalized = bracketed[1].trim();
-      unwrapped = true;
-      continue;
-    }
-
-    const dollarWrapped = /^\$\$\s*([\s\S]*?)\s*\$\$$/.exec(normalized);
-    if (dollarWrapped) {
-      normalized = dollarWrapped[1].trim();
-      unwrapped = true;
-    }
-  }
-
-  return normalized;
-}
-
 function renderKatex(target: HTMLElement, latex: string) {
   const source = latex || PLACEHOLDER_LATEX;
 
@@ -244,31 +217,7 @@ export const MathBlock = TiptapNode.create({
     };
   },
 
-  markdownTokenizer: {
-    name: 'mathBlock',
-    level: 'block' as const,
-    start(src: string) {
-      return src.indexOf('$$');
-    },
-    tokenize(src: string) {
-      const match = BLOCK_MATH_RE.exec(src);
-      if (!match) return undefined;
-      return {
-        type: 'mathBlock',
-        raw: match[0],
-        text: match[1],
-      };
-    },
-  },
-
-  parseMarkdown(token: MarkdownToken) {
-    return {
-      type: 'mathBlock',
-      attrs: {
-        latex: normalizeLatex(token.text),
-      },
-    };
-  },
+  ...mathBlockMarkdownSpec,
 
   renderMarkdown(node: JSONContent) {
     const latex = normalizeLatex(node.attrs?.latex);
diff --git a/app/flowix-web/features/editor/extensions/note-link/index.ts b/app/flowix-web/features/editor/extensions/note-link/index.ts
index 2c4e2d0b5..30bc09473 100644
--- a/app/flowix-web/features/editor/extensions/note-link/index.ts
+++ b/app/flowix-web/features/editor/extensions/note-link/index.ts
@@ -1,7 +1,10 @@
-export { NoteReference } from '@features/editor/extensions/note-link/view-note';
+export {
+  ComposerNoteReference,
+  NoteReference,
+} from '@features/editor/extensions/note-link/view-note';
 export type { NoteReferenceAttrs } from '@features/editor/extensions/note-link/view-note';
 export {
   tryMatchPhysicalMemoPath,
   prewarmNotebookCache,
   invalidateNotebookCache,
-} from '@features/editor/extensions/note-link/memo-resolver';
\ No newline at end of file
+} from '@features/editor/extensions/note-link/memo-resolver';
diff --git a/app/flowix-web/features/editor/extensions/note-link/memo-resolver.ts b/app/flowix-web/features/editor/extensions/note-link/memo-resolver.ts
index 4762ebc41..d74fa1349 100644
--- a/app/flowix-web/features/editor/extensions/note-link/memo-resolver.ts
+++ b/app/flowix-web/features/editor/extensions/note-link/memo-resolver.ts
@@ -1,22 +1,11 @@
-export {
+export {
   openNotebookById,
   openNoteByPhysicalPath,
   openNoteByNotebookPath,
-} from '@features/memo/use-cases/open-by-target';
-
-// 鐗╃悊璺緞绮樿创 鈫?noteReference 鍗＄墖銆?//
-// 鐢ㄦ埛浠?Finder / 缁堢澶嶅埗涓€浠?`~/Documents/flowix/<notebook>/<title>.md`
-// 杩欑绗旇鏈唴鐨勭粷瀵硅矾寰勭矘璐村埌缂栬緫鍣? 杩欓噷璐熻矗:
-//   1. 瑙ｆ瀽璺緞鏂囦欢鍚?鈹€鈹€ v3 鍚?filename 宸茬粡鏄鐩樻枃浠跺悕 (鍚?.md),
-//      涓嶅啀甯?`#<id>` 鍚庣紑, 鎵€浠?memoId 蹇呴』浠?memo index 鍙嶆煡銆?//   2. 鎸?notebook.path 鍋氬墠缂€姣斿, 鍛戒腑鍚庣敤璇?notebook 涓?memo index
-//      `filename` 瀛楁鍖归厤 鈹€鈹€ 鍛戒腑鍚庣粰鍑?attrs 璁╀笂娓告瀯閫?noteReference 鑺傜偣
-//
-// 璁捐瑕佺偣:
-// - **涓嶅厑璁稿瓙鐩綍**: 鏂囦欢蹇呴』鐩存帴鍦?notebook 鏍圭洰褰曚笅 (`path === notebook.path + filename`),
-//   璺熷悗绔?`reconcile_with_disk` 鍙壂鏍圭洰褰曠殑琛屼负瀵归綈, 閬垮厤鍑虹幇鏍规湰涓嶄細琚储寮曠殑寮曠敤銆?// - **鍓嶇紑鎸夐暱搴﹀€掑簭姣?*: 闃叉 `/a/b/c-notebook/` 鎶婃洿鐭殑 `/a/b/` notebook 璇懡涓€?// - **notebook 鍒楄〃 + 姣忎釜 notebook 鐨?filename鈫抜d 鏄犲皠閮借蛋妯″潡绾х紦瀛?*:
-//   绮樿创灞炰簬楂橀閿洏浜嬩欢, 涓嶈兘姣忔璧?IPC銆侫pp.tsx 鍚姩鏃?//   `prewarmNotebookCache()`, notebook 鍙樻洿鏃?`invalidateNotebookCache()`銆?//   鍐峰惎鍔ㄦ湭鍒颁綅鏃惰繑鍥?null, 璧版櫘閫氭枃鏈矾寰?鈥?涓嶉樆濉炵矘璐淬€?//
-// v3 鏀归€? 涓嶅啀瑙ｆ瀽 filename 鏈熬鐨?`#<id>`, 鏀规垚 IPC 鎷?memo index
-// 鍚庢寜 filename 鍙嶆煡 memoId銆?
+} from '@features/memo/public/note-navigation-api';
+
+// Physical notebook paths pasted from Finder or a terminal become path-based
+// note references. Notebook paths are cached so paste handling stays synchronous.
 import { notebooks } from '@platform/tauri/client';
 import { buildNoteOpenLinkFromPath } from '@platform/open-target/path-link';
 
@@ -29,7 +18,6 @@ interface NotebookLite {
 }
 
 export interface NoteReferenceAttrs {
-  memoId: string | null;
   notebookId: string;
   notebookName: string;
   title: string;
@@ -87,7 +75,7 @@ export function prewarmNotebookCache(): Promise<void> {
 }
 
 /**
- * notebook 澧炲垹鏀?/ memo 澧炲垹鏀瑰悕鏃惰皟 鈥?鎶婄紦瀛樻竻鎺? 涓嬫绮樿创浼氳Е鍙? * 閲嶆柊鎷夊彇銆備笂娓稿彲鎸傚湪 `agent-access-changed` / `memo-event` 浜嬩欢
+ * notebook 澧炲垹鏀?/ memo 澧炲垹鏀瑰悕鏃惰皟 鈥?鎶婄紦瀛樻竻鎺? 涓嬫绮樿创浼氳Е鍙? * 閲嶆柊鎷夊彇銆備笂娓稿彲鎸傚湪 `agent-workspace-changed` / `memo-event` 浜嬩欢
  * (notebook CRUD 涓?memo CRUD 鏃朵細 emit)銆? */
 export function invalidateNotebookCache(): void {
   cached = null;
@@ -218,7 +206,6 @@ export function tryMatchPhysicalMemoPath(raw: string): NoteReferenceAttrs | null
     const title = filename.replace(/\.md$/i, '');
 
     return {
-      memoId: null,
       notebookId: nb.id,
       notebookName: nb.name,
       title,
diff --git a/app/flowix-web/features/editor/extensions/note-link/note-reference-markdown.ts b/app/flowix-web/features/editor/extensions/note-link/note-reference-markdown.ts
new file mode 100644
index 000000000..c05926eeb
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/note-link/note-reference-markdown.ts
@@ -0,0 +1,188 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+import { readMarkdownLinkDestination } from '@features/editor/extensions/shared/markdown-link-destination';
+import { parseBooleanAttr, pickAttr, splitDisplay, unescapeHtml } from './markdown';
+
+export interface NoteReferenceAttrs {
+  notebookId: string | null;
+  relativePath?: string | null;
+  notebookName: string;
+  title: string;
+  originalPath: string | null;
+  linkStyle: 'flowix' | 'wiki' | 'markdown';
+  linkTarget: string | null;
+  heading: string | null;
+  stale: boolean;
+}
+
+export interface ParsedMarkdownNoteLink {
+  raw: string;
+  text: string;
+  href: string;
+}
+
+export interface ParsedWikiNoteLink {
+  raw: string;
+  target: string;
+  heading: string | null;
+  title: string;
+}
+
+export const FLOWIX_NOTE_URL_RE = /^flowix:\/\/open\?/i;
+
+function decodeMarkdownHref(href: string): string {
+  try {
+    return decodeURIComponent(href);
+  } catch {
+    return href;
+  }
+}
+
+export function splitObsidianTarget(rawTarget: string): { target: string; heading: string | null } {
+  const hash = rawTarget.indexOf('#');
+  if (hash < 0) return { target: decodeMarkdownHref(rawTarget.trim()), heading: null };
+  const target = decodeMarkdownHref(rawTarget.slice(0, hash).trim());
+  const heading = decodeMarkdownHref(rawTarget.slice(hash).replace(/^#+\s*/, '').trim());
+  return { target, heading: heading || null };
+}
+
+export function parseWikiNoteLinkAtStart(src: string): ParsedWikiNoteLink | null {
+  if (!src.startsWith('[[')) return null;
+  const end = src.indexOf(']]', 2);
+  if (end < 0 || src.slice(2, end).includes('\n')) return null;
+  const body = src.slice(2, end);
+  const aliasAt = body.indexOf('|');
+  const rawTarget = aliasAt < 0 ? body : body.slice(0, aliasAt);
+  const { target, heading } = splitObsidianTarget(rawTarget);
+  if (!target) return null;
+  const fallbackTitle = target.split('/').pop()?.replace(/\.md$/i, '') || target;
+  return {
+    raw: src.slice(0, end + 2),
+    target,
+    heading,
+    title: (aliasAt < 0 ? fallbackTitle : body.slice(aliasAt + 1).trim()) || fallbackTitle,
+  };
+}
+
+export function isRelativeNoteDestination(href: string): boolean {
+  const value = href.trim();
+  if (!value || /^[a-z][a-z0-9+.-]*:/i.test(value)) return false;
+  if (value.startsWith('/') || value.startsWith('#') || value.startsWith('?') || value.startsWith('//')) return false;
+  return /\.md(?:#|$)/i.test(value) || /%20/i.test(value);
+}
+
+function findMarkdownLinkCloseBracket(src: string): number {
+  for (let i = 1; i < src.length; i += 1) {
+    const char = src[i];
+    if (char === '\\') {
+      i += 1;
+      continue;
+    }
+    if (char === '\n') return -1;
+    if (char === ']') return i;
+  }
+  return -1;
+}
+
+export function parseMarkdownNoteLinkAtStart(src: string): ParsedMarkdownNoteLink | null {
+  if (!src.startsWith('[')) return null;
+  const closeBracket = findMarkdownLinkCloseBracket(src);
+  if (closeBracket < 0 || src[closeBracket + 1] !== '(') return null;
+  const destination = readMarkdownLinkDestination(src, closeBracket + 1);
+  if (!destination || !FLOWIX_NOTE_URL_RE.test(destination.url)) return null;
+  return { raw: src.slice(0, destination.end + 1), text: src.slice(1, closeBracket), href: destination.url };
+}
+
+function unescapeMarkdownLinkText(text: string): string {
+  return text.replace(/\\([\\\[\]])/g, '$1');
+}
+
+export function escapeMarkdownLinkText(text: string): string {
+  return text
+    .replace(/\\/g, '\\\\')
+    .replace(/\[/g, '\\[')
+    .replace(/\]/g, '\\]');
+}
+
+export function attrsFromMarkdownNoteLink(titleText: string, href: string): NoteReferenceAttrs {
+  if (!FLOWIX_NOTE_URL_RE.test(href)) {
+    const { target, heading } = splitObsidianTarget(href);
+    return {
+      notebookId: null, notebookName: '', title: unescapeMarkdownLinkText(titleText).trim(),
+      originalPath: null, linkStyle: 'markdown', linkTarget: target, heading, stale: false,
+    };
+  }
+  let pathTarget: URL | null = null;
+  try { pathTarget = new URL(href); } catch { /* Keep malformed links unresolved. */ }
+  return {
+    notebookId: pathTarget?.searchParams.get('notebookId') ?? null,
+    relativePath: pathTarget?.searchParams.get('f') ?? pathTarget?.searchParams.get('file') ?? pathTarget?.searchParams.get('relativePath') ?? null,
+    notebookName: pathTarget?.searchParams.get('b') ?? pathTarget?.searchParams.get('book') ?? '',
+    title: unescapeMarkdownLinkText(titleText).trim(),
+    originalPath: null,
+    linkStyle: 'flowix',
+    linkTarget: href,
+    heading: pathTarget?.hash ? decodeMarkdownHref(pathTarget.hash.replace(/^#/, '').trim()) || null : null,
+    stale: !pathTarget,
+  };
+}
+
+export function attrsFromWikiNoteLink(parsed: ParsedWikiNoteLink): NoteReferenceAttrs {
+  return {
+    notebookId: null, notebookName: '', title: parsed.title,
+    originalPath: null, linkStyle: 'wiki', linkTarget: parsed.target, heading: parsed.heading, stale: false,
+  };
+}
+
+export const noteReferenceMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'noteReference',
+    level: 'inline' as const,
+    start(src: string) {
+      const noteIndex = src.indexOf('<note ');
+      const linkHrefIndex = src.indexOf('(flowix://open?');
+      const wikiIndex = src.indexOf('[[');
+      const indexes = [noteIndex, linkHrefIndex < 0 ? -1 : Math.max(0, src.lastIndexOf('[', linkHrefIndex)), wikiIndex]
+        .filter(index => index >= 0);
+      return indexes.length ? Math.min(...indexes) : -1;
+    },
+    tokenize(src: string) {
+      const wiki = parseWikiNoteLinkAtStart(src);
+      if (wiki) return { type: 'noteReference', raw: wiki.raw, wiki };
+      const link = parseMarkdownNoteLinkAtStart(src);
+      if (link) return { type: 'noteReference', raw: link.raw, href: link.href, text: link.text };
+      const note = /^<note\s+([^>]*)>([\s\S]*?)<\/note>/.exec(src);
+      if (!note) return undefined;
+      return { type: 'noteReference', raw: note[0], attrs: note[1], text: note[2] };
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    const wiki = token.wiki as ParsedWikiNoteLink | undefined;
+    if (wiki) return { type: 'noteReference', attrs: attrsFromWikiNoteLink(wiki) };
+    const href = String(token.href ?? '');
+    if (FLOWIX_NOTE_URL_RE.test(href)) {
+      return { type: 'noteReference', attrs: attrsFromMarkdownNoteLink(String(token.text ?? ''), href) };
+    }
+    const attrsStr = String(token.attrs ?? '');
+    const { notebookName, title } = splitDisplay(unescapeHtml(String(token.text ?? '')));
+    return {
+      type: 'noteReference',
+      attrs: {
+        notebookId: pickAttr(attrsStr, 'notebook'),
+        relativePath: pickAttr(attrsStr, 'relativePath'),
+        notebookName,
+        title,
+        originalPath: pickAttr(attrsStr, 'path'),
+        linkStyle: 'flowix',
+        linkTarget: null,
+        heading: null,
+        stale: parseBooleanAttr(pickAttr(attrsStr, 'stale')),
+      } satisfies NoteReferenceAttrs,
+    };
+  },
+};
+
+export const NoteReferenceMarkdownExtension = Extension.create({
+  name: 'noteReference',
+  priority: 1000,
+  ...noteReferenceMarkdownSpec,
+});
diff --git a/app/flowix-web/features/editor/extensions/note-link/note-reference-preview-controller.ts b/app/flowix-web/features/editor/extensions/note-link/note-reference-preview-controller.ts
new file mode 100644
index 000000000..a1484f0d1
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/note-link/note-reference-preview-controller.ts
@@ -0,0 +1,257 @@
+import type { I18nKey } from '@/lib/i18n';
+import { assetUrl, decodeStorageKey } from '@features/editor/extensions/attachment-link/utils';
+
+export interface NoteReferencePreviewData {
+  title: string;
+  preview: string;
+  thumbnail: string | null;
+  notebookId: string;
+  relativePath: string;
+  notebookPath: string;
+  filePath: string;
+}
+
+interface NoteReferencePreviewControllerOptions {
+  anchor: HTMLElement;
+  getLocatorKey: () => string;
+  getFallbackTitle: () => string;
+  loadData: () => Promise<NoteReferencePreviewData | null>;
+  openNote: (data: NoteReferencePreviewData) => Promise<void>;
+  t: (key: I18nKey) => string;
+  onError: (error: unknown) => void;
+}
+
+function noteReferenceThumbnailUrl(thumbnail: string | null): string | null {
+  if (!thumbnail) return null;
+  const storageKey = decodeStorageKey(thumbnail);
+  return storageKey ? assetUrl(storageKey) : thumbnail;
+}
+
+/** Owns the composer note-reference preview's DOM, async lifecycle, and placement. */
+export class NoteReferencePreviewController {
+  private popover: HTMLDivElement | null = null;
+  private title: HTMLElement | null = null;
+  private text: HTMLElement | null = null;
+  private image: HTMLImageElement | null = null;
+  private openButton: HTMLButtonElement | null = null;
+  private isOpen = false;
+  private isDisposed = false;
+  private requestId = 0;
+  private cache: { key: string; promise: Promise<NoteReferencePreviewData | null> } | null = null;
+
+  constructor(private readonly options: NoteReferencePreviewControllerOptions) {}
+
+  toggle(): void {
+    if (this.isDisposed) return;
+    if (this.isOpen) this.close();
+    else this.show();
+  }
+
+  invalidate(): void {
+    this.cache = null;
+    if (this.isOpen) this.loadAndRender();
+  }
+
+  /** Keep the replacement trigger in sync when its inline-atom DOM is rebuilt. */
+  syncAnchorState(): void {
+    this.options.anchor
+      .querySelector<HTMLElement>('[data-inline-atom-card]')
+      ?.setAttribute('aria-expanded', String(this.isOpen));
+  }
+
+  dispose(): void {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    this.close();
+    this.popover?.remove();
+    this.popover = null;
+  }
+
+  private ensurePopover(): void {
+    if (this.popover) return;
+
+    const popover = document.createElement('div');
+    popover.className = 'agent-composer__note-reference-preview';
+    popover.hidden = true;
+    popover.setAttribute('role', 'dialog');
+
+    const image = document.createElement('img');
+    image.className = 'agent-composer__note-reference-preview-image';
+    image.alt = '';
+    image.draggable = false;
+    image.hidden = true;
+    image.addEventListener('load', this.position);
+    image.addEventListener('error', () => {
+      image.hidden = true;
+      this.position();
+    });
+
+    const body = document.createElement('div');
+    body.className = 'agent-composer__note-reference-preview-body';
+    const titleRow = document.createElement('div');
+    titleRow.className = 'agent-composer__note-reference-preview-title-row';
+    const title = document.createElement('div');
+    title.className = 'agent-composer__note-reference-preview-title';
+    const text = document.createElement('div');
+    text.className = 'agent-composer__note-reference-preview-text';
+
+    const openButton = document.createElement('button');
+    openButton.type = 'button';
+    openButton.className = 'agent-composer__note-reference-preview-open';
+    openButton.textContent = this.options.t('editor.noteLink.openNote');
+    openButton.addEventListener('mousedown', (event) => event.preventDefault());
+    openButton.addEventListener('click', (event) => {
+      event.preventDefault();
+      event.stopPropagation();
+      void this.openReferencedNote();
+    });
+
+    titleRow.append(title, openButton);
+    body.append(titleRow, text);
+    popover.append(image, body);
+    document.body.append(popover);
+
+    this.popover = popover;
+    this.title = title;
+    this.text = text;
+    this.image = image;
+    this.openButton = openButton;
+  }
+
+  private show(): void {
+    this.ensurePopover();
+    if (!this.popover || this.isDisposed) return;
+
+    this.isOpen = true;
+    this.popover.hidden = false;
+    this.options.anchor
+      .querySelector<HTMLElement>('[data-inline-atom-card]')
+      ?.setAttribute('aria-expanded', 'true');
+    window.addEventListener('resize', this.position);
+    window.addEventListener('scroll', this.position, true);
+    document.addEventListener('pointerdown', this.handleOutsidePointer, true);
+    document.addEventListener('keydown', this.handleKeyDown, true);
+    this.position();
+    this.loadAndRender();
+  }
+
+  private close(): void {
+    this.isOpen = false;
+    this.requestId += 1;
+    if (this.popover) this.popover.hidden = true;
+    this.options.anchor
+      .querySelector<HTMLElement>('[data-inline-atom-card]')
+      ?.setAttribute('aria-expanded', 'false');
+    window.removeEventListener('resize', this.position);
+    window.removeEventListener('scroll', this.position, true);
+    document.removeEventListener('pointerdown', this.handleOutsidePointer, true);
+    document.removeEventListener('keydown', this.handleKeyDown, true);
+  }
+
+  private handleOutsidePointer = (event: PointerEvent): void => {
+    const target = event.target;
+    if (
+      target instanceof Node &&
+      (this.options.anchor.contains(target) || this.popover?.contains(target))
+    ) return;
+    this.close();
+  };
+
+  private handleKeyDown = (event: KeyboardEvent): void => {
+    if (event.key !== 'Escape' || !this.isOpen) return;
+    event.preventDefault();
+    event.stopPropagation();
+    this.close();
+  };
+
+  private loadCachedData(): Promise<NoteReferencePreviewData | null> {
+    const key = this.options.getLocatorKey();
+    if (this.cache?.key === key) return this.cache.promise;
+
+    const promise = this.options.loadData().catch((error: unknown) => {
+      if (this.cache?.key === key) this.cache = null;
+      throw error;
+    });
+    this.cache = { key, promise };
+    return promise;
+  }
+
+  private loadAndRender(): void {
+    if (!this.isOpen || !this.text || !this.openButton || !this.popover) return;
+    const requestId = ++this.requestId;
+    this.title!.textContent = this.options.getFallbackTitle();
+    this.popover.setAttribute('aria-label', this.title!.textContent ?? '');
+    this.text.textContent = this.options.t('editor.noteLink.previewLoading');
+    this.openButton.disabled = true;
+    if (this.image) this.image.hidden = true;
+    this.position();
+
+    void this.loadCachedData().then((data) => {
+      if (this.isDisposed || !this.isOpen || requestId !== this.requestId) return;
+      if (!data) {
+        this.text!.textContent = this.options.t('editor.noteLink.previewUnavailable');
+        this.openButton!.disabled = true;
+      } else {
+        this.title!.textContent = data.title;
+        this.popover!.setAttribute('aria-label', data.title);
+        this.text!.textContent = data.preview.trim()
+          || this.options.t('editor.noteLink.previewEmpty');
+        this.openButton!.disabled = false;
+        const thumbnailUrl = noteReferenceThumbnailUrl(data.thumbnail);
+        if (thumbnailUrl && this.image) {
+          this.image.hidden = false;
+          if (this.image.src !== thumbnailUrl) this.image.src = thumbnailUrl;
+        }
+      }
+      this.position();
+    }).catch(() => {
+      if (this.isDisposed || !this.isOpen || requestId !== this.requestId) return;
+      this.text!.textContent = this.options.t('editor.noteLink.previewUnavailable');
+      this.openButton!.disabled = true;
+      this.position();
+    });
+  }
+
+  private position = (): void => {
+    if (!this.isOpen || !this.popover?.isConnected || !this.options.anchor.isConnected) return;
+    const anchorRect = this.options.anchor.getBoundingClientRect();
+    const popoverRect = this.popover.getBoundingClientRect();
+    const width = popoverRect.width || 304;
+    const height = popoverRect.height || 156;
+    const padding = 8;
+    const left = Math.min(
+      Math.max(anchorRect.left + (anchorRect.width - width) / 2, padding),
+      Math.max(padding, window.innerWidth - width - padding),
+    );
+    const preferredTop = anchorRect.top - height - 8;
+    const top = preferredTop >= padding
+      ? preferredTop
+      : Math.min(anchorRect.bottom + 8, Math.max(padding, window.innerHeight - height - padding));
+    this.popover.style.left = `${left}px`;
+    this.popover.style.top = `${top}px`;
+  };
+
+  private async openReferencedNote(): Promise<void> {
+    const button = this.openButton;
+    if (!button || button.disabled || this.isDisposed) return;
+    const locatorKey = this.options.getLocatorKey();
+    button.disabled = true;
+    try {
+      const data = await this.loadCachedData();
+      // The inline atom may have been edited while the preview request was in
+      // flight. Never navigate using data for the previous target.
+      if (locatorKey !== this.options.getLocatorKey()) return;
+      if (!data) throw new Error(this.options.t('editor.noteLink.previewUnavailable'));
+      await this.options.openNote(data);
+      this.close();
+    } catch (error) {
+      this.options.onError(error);
+    } finally {
+      if (
+        !this.isDisposed
+        && button.isConnected
+        && locatorKey === this.options.getLocatorKey()
+      ) button.disabled = false;
+    }
+  }
+}
diff --git a/app/flowix-web/features/editor/extensions/note-link/note-reference-preview.test.ts b/app/flowix-web/features/editor/extensions/note-link/note-reference-preview.test.ts
new file mode 100644
index 000000000..057c40ce0
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/note-link/note-reference-preview.test.ts
@@ -0,0 +1,138 @@
+import { afterEach, expect, it, vi } from 'vitest';
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { notes } from '@platform/tauri/client';
+import { useNoteStore, type Notebook } from '@features/memo/store/note-store';
+import { useBrowserColumnStore } from '@features/workspace/store/browser-column-store';
+import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
+import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focus-store';
+import { resetBrowserColumnCoordinator } from '@features/workspace/use-cases/browser-column-coordinator';
+import { ComposerNoteReference } from './view-note';
+
+const initialNotes = useNoteStore.getState();
+const initialWorkColumn = useWorkColumnStore.getState();
+const initialBrowserColumn = useBrowserColumnStore.getState();
+const initialFocus = useWorkspaceFocusStore.getState();
+let editor: Editor | null = null;
+
+afterEach(() => {
+  editor?.destroy();
+  editor = null;
+  document.body.replaceChildren();
+  resetBrowserColumnCoordinator();
+  useNoteStore.setState(initialNotes);
+  useWorkColumnStore.setState(initialWorkColumn);
+  useBrowserColumnStore.setState(initialBrowserColumn);
+  useWorkspaceFocusStore.setState(initialFocus);
+  vi.restoreAllMocks();
+});
+
+it('opens the referenced note from its composer preview while a conversation is active', async () => {
+  const notebook: Notebook = {
+    id: 'work', name: 'Work', path: '/notes',
+    createdAt: 0, updatedAt: 0, isDefault: true,
+  };
+  useNoteStore.setState({ notebooks: [notebook], selectedNotebook: notebook, selectedNotebookId: notebook.id });
+  useBrowserColumnStore.getState().reset();
+  resetBrowserColumnCoordinator();
+  const conversation = { kind: 'agent-conversation' as const, instanceId: 'current-conversation' };
+  useWorkColumnStore.setState({
+    navigation: {
+      ...initialWorkColumn.navigation,
+      phase: 'committed', target: conversation,
+    },
+  });
+  vi.spyOn(notes, 'getIndexed').mockResolvedValue({
+    relativePath: 'Projects/Plan.md', title: 'Plan', preview: 'The referenced note', thumbnail: null,
+    tags: [], todos: [], agents: [], createdAt: 0, updatedAt: 0,
+    favorited: false, icon: null, colors: [], properties: {},
+  });
+
+  const element = document.createElement('div');
+  document.body.append(element);
+  editor = new Editor({
+    element,
+    extensions: [StarterKit, ComposerNoteReference],
+    content: {
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{
+        type: 'noteReference', attrs: { notebookId: 'work', relativePath: 'Projects/Plan.md' },
+      }] }],
+    },
+  });
+
+  const card = editor.view.dom.querySelector<HTMLElement>('.note-reference__card')!;
+  card.click();
+  const openButton = document.querySelector<HTMLButtonElement>('.agent-composer__note-reference-preview-open')!;
+  await vi.waitFor(() => expect(openButton.disabled).toBe(false));
+  expect(useBrowserColumnStore.getState().tabs).toHaveLength(0);
+
+  openButton.click();
+  await vi.waitFor(() => {
+    const browser = useBrowserColumnStore.getState();
+    expect(browser.tabs).toHaveLength(1);
+    expect(browser.tabs.find((tab) => tab.id === browser.activeTabId)?.target).toMatchObject({
+      kind: 'file-browser', activeFilePath: '/notes/Projects/Plan.md', scopePath: '/notes',
+    });
+  });
+  expect(useWorkColumnStore.getState().navigation.target).toEqual(conversation);
+  expect(document.querySelector<HTMLElement>('.agent-composer__note-reference-preview')?.hidden).toBe(true);
+
+  card.click();
+  await vi.waitFor(() => expect(openButton.disabled).toBe(false));
+  openButton.click();
+  await vi.waitFor(() => expect(document.querySelector<HTMLElement>('.agent-composer__note-reference-preview')?.hidden).toBe(true));
+  expect(useBrowserColumnStore.getState().tabs).toHaveLength(1);
+  expect(useWorkColumnStore.getState().navigation.target).toEqual(conversation);
+});
+
+it('keeps the current note (and its embedded conversation) in the work column', async () => {
+  const notebook: Notebook = {
+    id: 'work', name: 'Work', path: '/notes',
+    createdAt: 0, updatedAt: 0, isDefault: true,
+  };
+  useNoteStore.setState({ notebooks: [notebook], selectedNotebook: notebook, selectedNotebookId: notebook.id });
+  useBrowserColumnStore.getState().reset();
+  resetBrowserColumnCoordinator();
+  // The agent conversation lives in a thread card embedded in the current note,
+  // so the work column target is the note document, not an agent-conversation.
+  const currentNote = {
+    kind: 'external' as const, path: '/notes/Projects/Plan.md', scopePath: '/notes', transitionId: null,
+  };
+  useWorkColumnStore.setState({
+    navigation: {
+      ...initialWorkColumn.navigation,
+      phase: 'committed', target: currentNote,
+    },
+  });
+  vi.spyOn(notes, 'getIndexed').mockResolvedValue({
+    relativePath: 'Projects/Plan.md', title: 'Plan', preview: 'The referenced note', thumbnail: null,
+    tags: [], todos: [], agents: [], createdAt: 0, updatedAt: 0,
+    favorited: false, icon: null, colors: [], properties: {},
+  });
+
+  const element = document.createElement('div');
+  document.body.append(element);
+  editor = new Editor({
+    element,
+    extensions: [StarterKit, ComposerNoteReference],
+    content: {
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{
+        type: 'noteReference', attrs: { notebookId: 'work', relativePath: 'Projects/Plan.md' },
+      }] }],
+    },
+  });
+
+  const card = editor.view.dom.querySelector<HTMLElement>('.note-reference__card')!;
+  card.click();
+  const openButton = document.querySelector<HTMLButtonElement>('.agent-composer__note-reference-preview-open')!;
+  await vi.waitFor(() => expect(openButton.disabled).toBe(false));
+
+  openButton.click();
+  await vi.waitFor(() => {
+    expect(useBrowserColumnStore.getState().tabs).toHaveLength(1);
+  });
+  // The work column must not be emptied by opening the same note on the right.
+  expect(useWorkColumnStore.getState().navigation.target).toEqual(currentNote);
+});
diff --git a/app/flowix-web/features/editor/extensions/note-link/obsidian-link.test.ts b/app/flowix-web/features/editor/extensions/note-link/obsidian-link.test.ts
index 7ad554c23..69c4d9d98 100644
--- a/app/flowix-web/features/editor/extensions/note-link/obsidian-link.test.ts
+++ b/app/flowix-web/features/editor/extensions/note-link/obsidian-link.test.ts
@@ -20,11 +20,11 @@ describe('Obsidian note links', () => {
       type: 'noteReference',
       attrs: {
         notebookId: 'work', relativePath: 'Projects/Plan.md', notebookName: 'Work',
-        title: 'Plan', memoId: null, originalPath: null, linkStyle: 'flowix',
+        title: 'Plan', originalPath: null, linkStyle: 'flowix',
         linkTarget: null, heading: null, stale: false,
       },
     });
-    expect(editor.view.dom.querySelector('.editor-note-reference__card')?.getAttribute('data-stale')).toBe('false');
+    expect(editor.view.dom.querySelector('.note-reference__card')?.getAttribute('data-stale')).toBe('false');
     editor.destroy();
   });
   it('round trips a child note by notebook and relative path without a memo ID', () => {
@@ -35,7 +35,7 @@ describe('Obsidian note links', () => {
       contentType: 'markdown',
     });
     const node = editor.state.doc.firstChild?.firstChild;
-    expect(node?.attrs).toMatchObject({ notebookName: 'Work', relativePath: 'Projects/Plan.md', memoId: null });
+    expect(node?.attrs).toMatchObject({ notebookName: 'Work', relativePath: 'Projects/Plan.md' });
     expect(editor.getMarkdown()).toContain(link);
     editor.destroy();
   });
@@ -45,7 +45,7 @@ describe('Obsidian note links', () => {
       content: '[Custom label](flowix://open?b=Work&f=Projects%2FPlan.md)',
       contentType: 'markdown',
     });
-    expect(editor.view.dom.querySelector('.editor-note-reference__title')?.textContent).toBe('Plan');
+    expect(editor.view.dom.querySelector('.note-reference__title')?.textContent).toBe('Plan');
     expect(editor.getMarkdown()).toContain('[Plan](flowix://open?b=Work&f=Projects%2FPlan.md)');
     editor.destroy();
   });
@@ -69,7 +69,6 @@ describe('Obsidian note links', () => {
     const node = editor.state.doc.firstChild?.firstChild;
     expect(node?.type.name).toBe('noteReference');
     expect(node?.attrs.linkTarget).toBe(link);
-    expect(node?.attrs.memoId).toBeNull();
     editor.destroy();
   });
   it('normalizes an existing book/file link when saved', () => {
@@ -81,7 +80,7 @@ describe('Obsidian note links', () => {
     expect(editor.getMarkdown()).toContain('[Plan](flowix://open?b=MyVault&f=Projects%2FPlan.md)');
     editor.destroy();
   });
-  it('marks legacy memo ID links as stale and preserves them for repair', () => {
+  it('does not parse legacy memo ID links as note references', () => {
     const link = 'flowix://memo/abc12345';
     const editor = new Editor({
       extensions: [StarterKit, Markdown, NoteReference, MarkdownLink],
@@ -89,8 +88,7 @@ describe('Obsidian note links', () => {
       contentType: 'markdown',
     });
     const node = editor.state.doc.firstChild?.firstChild;
-    expect(node?.attrs).toMatchObject({ memoId: null, stale: true, linkTarget: link });
-    expect(editor.getMarkdown()).toContain(link);
+    expect(node?.type.name).not.toBe('noteReference');
     editor.destroy();
   });
   it('keeps ordinary relative Markdown links lightweight', () => {
diff --git a/app/flowix-web/features/editor/extensions/note-link/view-note.ts b/app/flowix-web/features/editor/extensions/note-link/view-note.ts
index 822b29038..20227e955 100644
--- a/app/flowix-web/features/editor/extensions/note-link/view-note.ts
+++ b/app/flowix-web/features/editor/extensions/note-link/view-note.ts
@@ -3,43 +3,46 @@
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { NodeView as ProseMirrorNodeView, EditorView } from '@tiptap/pm/view';
 import { DecorationSet } from '@tiptap/pm/view';
-import { Node, nodeInputRule, nodePasteRule, type InputRuleMatch, type JSONContent, type MarkdownToken, type PasteRuleMatch } from '@tiptap/core';
+import { Node, nodeInputRule, nodePasteRule, type InputRuleMatch, type JSONContent, type PasteRuleMatch } from '@tiptap/core';
 import { NodeSelection, Plugin, PluginKey, type EditorState } from '@tiptap/pm/state';
 
-import { readMarkdownLinkDestination } from '@features/editor/extensions/shared/markdown-link-destination';
-import { noteLinkForIndexedPath, openNoteByNotebookPath, openNoteByPhysicalPath } from '@features/editor/extensions/note-link/memo-resolver';
+import { noteLinkForIndexedPath } from '@features/editor/extensions/note-link/memo-resolver';
+import { openNoteByNotebookPath, openNoteByPhysicalPath } from '@features/memo/public/note-navigation-api';
 import { queryMentionNotes } from '@features/editor/extensions/note-mention/note-mention-data';
-import { parseBooleanAttr, pickAttr, splitDisplay, stripMdSuffix, unescapeHtml } from '@features/editor/extensions/note-link/markdown';
+import { parseBooleanAttr, splitDisplay, stripMdSuffix } from '@features/editor/extensions/note-link/markdown';
+import {
+  attrsFromMarkdownNoteLink, attrsFromWikiNoteLink, escapeMarkdownLinkText,
+  parseMarkdownNoteLinkAtStart, parseWikiNoteLinkAtStart, noteReferenceMarkdownSpec,
+  type NoteReferenceAttrs, type ParsedWikiNoteLink,
+} from './note-reference-markdown';
+export type { NoteReferenceAttrs } from './note-reference-markdown';
+export { isRelativeNoteDestination, parseWikiNoteLinkAtStart, splitObsidianTarget } from './note-reference-markdown';
 import { translate, type I18nKey } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 import { createTerminalInlineAtomCaretDecorations } from '@features/editor/extensions/shared/terminal-inline-atom-caret';
+import {
+  createInlineAtomCloseIcon,
+  createInlineAtomNodeView,
+  deleteInlineAtomNode,
+  deleteAdjacentInlineAtom,
+  setInlineAtomNodeViewSelected,
+} from '@features/editor/extensions/shared/inline-atom-nodeview';
 import { navigateToHeadingAnchor } from '@features/editor/components/heading-anchor-navigation';
-import { decodeEditorHref } from '@features/editor/editor-link-resolution';
 import GithubSlugger from 'github-slugger';
 import { notes as notesClient } from '@platform/tauri/client';
+import type { NoteEntry } from '@platform/tauri/client/notes';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { joinNotebookMemoPath } from '@/lib/path';
 import { buildNoteOpenLink } from '@platform/open-target/path-link';
 import { displayTitleFromFilename } from '@/lib/utils';
 import { toast } from '@/lib/toast';
+import {
+  NoteReferencePreviewController,
+  type NoteReferencePreviewData,
+} from '@features/editor/extensions/note-link/note-reference-preview-controller';
 
 // ─── Attrs ────────────────────────────────────────────────────────────────────
 
-export interface NoteReferenceAttrs {
-  memoId: string | null;
-  notebookId: string | null;
-  relativePath?: string | null;
-  notebookName: string;
-  title: string;
-  originalPath: string | null;
-  linkStyle: 'flowix' | 'wiki' | 'markdown';
-  linkTarget: string | null;
-  heading: string | null;
-  /** 渲染态: memoId 缺失 或 后端按 memoId/originalPath 都解析不到时为 true;
-   *  不写入 markdown */
-  stale: boolean;
-}
-
 function noteReferenceDisplayTitle(attrs: NoteReferenceAttrs): string {
   if (attrs.relativePath) return displayTitleFromFilename(attrs.relativePath);
   if (attrs.linkTarget?.startsWith('flowix://open?')) {
@@ -53,89 +56,10 @@ function noteReferenceDisplayTitle(attrs: NoteReferenceAttrs): string {
   return stripMdSuffix(attrs.title || '');
 }
 
-const FLOWIX_MEMO_URL_RE = /^flowix:\/\/(?:memo\/|open\?)/i;
-
-// NodeView 不在 React 树内, 不能用 useI18n, 走 user-settings-store 直读当前语言。
 function tKey(key: I18nKey, params?: Record<string, string | number>): string {
   return translate(getCurrentAppLanguage(), key, params);
 }
 
-type ParsedMarkdownNoteLink = {
-  raw: string;
-  text: string;
-  href: string;
-};
-
-type ParsedWikiNoteLink = {
-  raw: string;
-  target: string;
-  heading: string | null;
-  title: string;
-};
-
-export function splitObsidianTarget(rawTarget: string): { target: string; heading: string | null } {
-  const hash = rawTarget.indexOf('#');
-  if (hash < 0) return { target: decodeEditorHref(rawTarget.trim()), heading: null };
-  const target = decodeEditorHref(rawTarget.slice(0, hash).trim());
-  // Also accept the commonly typed `## Heading`, while Obsidian itself uses
-  // one `#` regardless of heading level.
-  const heading = decodeEditorHref(rawTarget.slice(hash).replace(/^#+\s*/, '').trim());
-  return { target, heading: heading || null };
-}
-
-export function parseWikiNoteLinkAtStart(src: string): ParsedWikiNoteLink | null {
-  if (!src.startsWith('[[')) return null;
-  const end = src.indexOf(']]', 2);
-  if (end < 0 || src.slice(2, end).includes('\n')) return null;
-  const body = src.slice(2, end);
-  const aliasAt = body.indexOf('|');
-  const rawTarget = aliasAt < 0 ? body : body.slice(0, aliasAt);
-  const { target, heading } = splitObsidianTarget(rawTarget);
-  if (!target) return null;
-  const fallbackTitle = target.split('/').pop()?.replace(/\.md$/i, '') || target;
-  return {
-    raw: src.slice(0, end + 2),
-    target,
-    heading,
-    title: (aliasAt < 0 ? fallbackTitle : body.slice(aliasAt + 1).trim()) || fallbackTitle,
-  };
-}
-
-export function isRelativeNoteDestination(href: string): boolean {
-  const value = href.trim();
-  if (!value || /^[a-z][a-z0-9+.-]*:/i.test(value)) return false;
-  if (value.startsWith('/') || value.startsWith('#') || value.startsWith('?') || value.startsWith('//')) return false;
-  return /\.md(?:#|$)/i.test(value) || /%20/i.test(value);
-}
-
-function findMarkdownLinkCloseBracket(src: string): number {
-  for (let i = 1; i < src.length; i += 1) {
-    const char = src[i];
-    if (char === '\\') {
-      i += 1;
-      continue;
-    }
-    if (char === '\n') return -1;
-    if (char === ']') return i;
-  }
-  return -1;
-}
-
-function parseMarkdownNoteLinkAtStart(src: string): ParsedMarkdownNoteLink | null {
-  if (!src.startsWith('[')) return null;
-  const closeBracket = findMarkdownLinkCloseBracket(src);
-  if (closeBracket < 0 || src[closeBracket + 1] !== '(') return null;
-
-  const destination = readMarkdownLinkDestination(src, closeBracket + 1);
-  if (!destination || !FLOWIX_MEMO_URL_RE.test(destination.url)) return null;
-
-  return {
-    raw: src.slice(0, destination.end + 1),
-    text: src.slice(1, closeBracket),
-    href: destination.url,
-  };
-}
-
 function findLastMarkdownNoteLink(text: string): InputRuleMatch | null {
   let found: InputRuleMatch | null = null;
 
@@ -188,72 +112,6 @@ function findWikiNotePasteMatches(text: string): PasteRuleMatch[] {
   return matches;
 }
 
-function parseFlowixMemoHrefForAttrs(href: string): { memoId: string | null; stale: boolean } {
-  if (/^flowix:\/\/open\?/i.test(href)) return { memoId: null, stale: false };
-  return { memoId: null, stale: true };
-}
-
-function escapeMarkdownLinkText(text: string): string {
-  return text
-    .replace(/\\/g, '\\\\')
-    .replace(/\[/g, '\\[')
-    .replace(/\]/g, '\\]');
-}
-
-function unescapeMarkdownLinkText(text: string): string {
-  return text.replace(/\\([\\\[\]])/g, '$1');
-}
-
-function attrsFromMarkdownNoteLink(titleText: string, href: string): NoteReferenceAttrs {
-  if (!FLOWIX_MEMO_URL_RE.test(href)) {
-    const { target, heading } = splitObsidianTarget(href);
-    return {
-      memoId: null,
-      notebookId: null,
-      notebookName: '',
-      title: unescapeMarkdownLinkText(titleText).trim(),
-      originalPath: null,
-      linkStyle: 'markdown',
-      linkTarget: target,
-      heading,
-      stale: false,
-    };
-  }
-  const parsed = parseFlowixMemoHrefForAttrs(href);
-  let pathTarget: URL | null = null;
-  if (/^flowix:\/\/open\?/i.test(href)) {
-    try { pathTarget = new URL(href); } catch { /* malformed link stays stale */ }
-  }
-  return {
-    memoId: parsed.memoId,
-    notebookId: pathTarget?.searchParams.get('notebookId') ?? null,
-    relativePath: pathTarget?.searchParams.get('f') ?? pathTarget?.searchParams.get('file') ?? pathTarget?.searchParams.get('relativePath') ?? null,
-    notebookName: pathTarget?.searchParams.get('b') ?? pathTarget?.searchParams.get('book') ?? '',
-    title: unescapeMarkdownLinkText(titleText).trim(),
-    originalPath: null,
-    linkStyle: 'flowix',
-    linkTarget: href,
-    // flowix://open 深链的 `#fragment` 是 GitHub-slug 标题锚点，与相对链接同语义。
-    heading: pathTarget?.hash ? decodeEditorHref(pathTarget.hash.replace(/^#/, '').trim()) || null : null,
-    stale: parsed.stale,
-  };
-}
-
-function attrsFromWikiNoteLink(parsed: ParsedWikiNoteLink): NoteReferenceAttrs {
-  return {
-    memoId: null,
-    notebookId: null,
-    notebookName: '',
-    title: parsed.title,
-    originalPath: null,
-    linkStyle: 'wiki',
-    linkTarget: parsed.target,
-    heading: parsed.heading,
-    stale: false,
-  };
-}
-
-
 // ─── HardBreak 清理 ───────────────────────────────────────────────────────────
 
 /**
@@ -306,8 +164,6 @@ function removeHardBreaksAroundNoteReferences(state: EditorState) {
   return tr;
 }
 
-const noteReferenceCaretPluginKey = new PluginKey<DecorationSet>('noteReferenceTerminalCaret');
-
 // ─── NodeView ─────────────────────────────────────────────────────────────────
 
 class NoteReferenceView implements ProseMirrorNodeView {
@@ -316,39 +172,49 @@ class NoteReferenceView implements ProseMirrorNodeView {
   private node: ProseMirrorNode;
   private view: EditorView;
   private getPos: (() => number | undefined) | undefined;
-  private clickHandler: (e: MouseEvent) => void;
   /** 节点已销毁标记. 异步 refresh 跑完后写回 doc 时如果发现 destroyed,
    * 立即放弃 dispatch, 避免 dispatch 到已死的 view 触发 PM 内部错误,
    * 或把 attrs 写到错的 noteReference 节点 (pos 处已被别的节点占据). */
   private destroyed = false;
+  private previewController: NoteReferencePreviewController | null = null;
 
-  constructor(node: ProseMirrorNode, view: EditorView, getPos: (() => number | undefined) | undefined) {
+  constructor(node: ProseMirrorNode, view: EditorView, getPos: (() => number | undefined) | undefined, private readonly presentation: 'document' | 'composer') {
     this.node = node;
     this.view = view;
     this.getPos = getPos;
     this.dom = this.createCard();
-    this.clickHandler = (e) => this.handleClick(e);
-    this.dom.addEventListener('click', this.clickHandler);
+    if (this.presentation === 'composer') {
+      this.previewController = new NoteReferencePreviewController({
+        anchor: this.dom,
+        getLocatorKey: () => this.previewLocatorKey(),
+        getFallbackTitle: () => noteReferenceDisplayTitle(this.node.attrs as NoteReferenceAttrs)
+          || tKey('editor.noteLink.untitled'),
+        loadData: () => this.loadNotePreviewData(),
+        openNote: async (data) => {
+          await openNoteByNotebookPath(
+            data.notebookId,
+            data.relativePath,
+            null,
+            { destination: 'browser-column' },
+          );
+        },
+        t: (key) => tKey(key),
+        onError: (error) => toast.error(error instanceof Error ? error.message : String(error)),
+      });
+    }
 
-    // mount 时异步校验: 用 memoId 反查最新 title / notebookName / 路径,
-    // 与 markdown 里缓存的旧值对比, 变化则写回 doc attrs;
-    // 解析失败 → 落 stale.
+    // mount 时按笔记本和相对路径校验目标是否仍存在.
   }
 
   private createCard(): HTMLElement {
     // notebookName 不再用于渲染 (见下方 nameSpan 注释), 仍在 attrs 里保留;
     // 这里只解构 UI 需要的字段.
-    const { notebookId, relativePath, notebookName, memoId, originalPath, linkTarget, stale } = this.node.attrs as NoteReferenceAttrs;
+    const { notebookId, relativePath, notebookName, originalPath, linkTarget, stale } = this.node.attrs as NoteReferenceAttrs;
 
     // 视觉 stale 判定:
     //   - 已 stale (applyAttrs 写入) → 视觉 stale
-    //   - memoId 缺失 + originalPath 缺失 (双向都没法定位 memo) → 视觉 stale
-    //   - 只有 memoId 缺失但 originalPath 在 (例如物理路径粘贴, paste 没
-    //     同步拿到 id) → **不**先 stale, mount 时 refreshMemoAttrs 会
-    //     用 originalPath 异步反查 memoId 并写回. 这样避免"刚粘贴的有效
-    //     链接一出生就是灰卡"的问题.
     const hasTarget = Boolean((notebookId || notebookName) && relativePath)
-      || Boolean(memoId || originalPath || linkTarget);
+      || Boolean(originalPath || linkTarget);
     const effectiveStale = stale || !hasTarget;
 
     // 外层 wrapper: 与 .editor-file-attachment 同结构 (display:inline),
@@ -359,26 +225,30 @@ class NoteReferenceView implements ProseMirrorNodeView {
     // 上鼠标按住拖动只会触发选区, 不会启动 DnD 流.
     const wrapper = document.createElement('span');
     wrapper.className = 'editor-note-reference';
-    // NoteReference remains the single source of truth for memo identity,
+    // NoteReference remains the single source of truth for note path,
     // path validation, and navigation. Only its composer surface gets a
     // presentation modifier, so Agent chips cannot leak into document links.
-    if (this.view.dom.closest('.agent-thread-card__composer')) {
-      wrapper.classList.add('editor-note-reference--composer');
+    if (this.presentation === 'composer') {
+      wrapper.classList.add('agent-composer__note-reference', 'agent-composer__inline-atom-wrapper');
     }
     wrapper.contentEditable = 'false';
     wrapper.draggable = true;
 
     const card = document.createElement('span');
-    card.className = 'editor-note-reference__card';
+    card.className = 'note-reference__card';
     card.setAttribute('data-stale', effectiveStale ? 'true' : 'false');
+    if (this.presentation === 'composer') {
+      card.setAttribute('aria-haspopup', 'dialog');
+      card.setAttribute('aria-expanded', 'false');
+    }
     if (originalPath) {
       card.setAttribute('title', effectiveStale ? tKey('editor.noteLink.stale', { path: originalPath }) : originalPath);
     }
 
-    // 笔记图标 (lucide file-text 同形, 内联 SVG 避免依赖 React)
+    // 使用侧边栏默认文档图标的 SVG 路径, 内联渲染以避免依赖 React。
     const icon = document.createElement('span');
-    icon.className = 'editor-note-reference__icon';
-    icon.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M10 9H8"/><path d="M16 13H8"/><path d="M16 17H8"/></svg>`;
+    icon.className = 'note-reference__icon';
+    icon.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 18 18" fill="none" aria-hidden="true"><g transform="matrix(0.6923077 0 0 0.6923077 0.6923077 0.6923077)"><line x1="7.6666" y1="11.36" x2="10.3333" y2="11.36" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.2" vector-effect="non-scaling-stroke"/><line x1="7.6666" y1="15.18" x2="16.3333" y2="15.18" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.2" vector-effect="non-scaling-stroke"/><path d="M 3.6667 19 V 5 c 0 -1.4733 1.1933 -2.6667 2.6667 -2.6667 h 7.448 c 0.3533 0 0.6933 0.14 0.9427 0.3907 l 5.2187 5.2187 c 0.2507 0.2507 0.3907 0.5893 0.3907 0.9427 v 10.1146 c 0 1.4733 -1.1933 2.6667 -2.6667 2.6667 H 6.3333 c -1.4733 0 -2.6667 -1.1933 -2.6667 -2.6667 Z" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.2" vector-effect="non-scaling-stroke"/><path d="M 20.2133 8.3333 h -4.5467 c -0.736 0 -1.3333 -0.5973 -1.3333 -1.3333 V 2.4693" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.2" vector-effect="non-scaling-stroke"/></g></svg>`;
 
     // 名称 = `title` 单段。
     //
@@ -393,62 +263,151 @@ class NoteReferenceView implements ProseMirrorNodeView {
     // 仍保留 notebookName 在 attrs 里 (markdown round-trip / 双击跳转跨笔记本
     // 都还要用), 只是 UI 层不再展示.
     const nameSpan = document.createElement('span');
-    nameSpan.className = 'editor-note-reference__name';
+    nameSpan.className = 'note-reference__name';
     const titleSpan = document.createElement('span');
-    titleSpan.className = 'editor-note-reference__title';
+    titleSpan.className = 'note-reference__title';
     titleSpan.textContent = noteReferenceDisplayTitle(this.node.attrs as NoteReferenceAttrs) || tKey('editor.noteLink.untitled');
     nameSpan.appendChild(titleSpan);
 
     card.appendChild(icon);
     card.appendChild(nameSpan);
 
-    // 失效标签: stale 视觉信号除了 opacity + 删除线, 再追加一段
+    // 失效标签: stale 视觉信号在降低 opacity 的同时追加一段
     // "（已失效）" 文字, 让用户在不 hover 的情况下也能直接读到链接状态.
     // 用独立 span 包起来, 避免继承 __name 的 font-weight/换行属性.
     if (effectiveStale) {
       const staleMark = document.createElement('span');
-      staleMark.className = 'editor-note-reference__stale-mark';
+      staleMark.className = 'note-reference__stale-mark';
       staleMark.textContent = tKey('editor.noteLink.staleMark');
       card.appendChild(staleMark);
     }
 
-    // 节点首/尾部 caret 占位:
-    //  inline atom node 位于段落行首/行尾时, 浏览器把 caret 贴到
-    //  NodeView 第一个/最后一个可定位点; 此前该点是 icon / 末尾文字,
-    //  caret 视觉上 "穿入图标" 或 "贴卡片右边缘". 改为在 wrapper 内、
-    //  card 前后各塞一个零宽空格文本节点, caret 自然落在文本节点上,
-    //  与卡片边缘不再重叠.
-    //  - 必须是 TextNode (createTextNode), <span> 不行——
-    //    span 的边缘问题与 icon 相同, caret 仍会贴其左/右边缘.
-    //  - 零宽空格 U+200B 不可见、不占字宽, 视觉上无副作用.
-    //  - wrapper 整体 contentEditable=false, 用户无法编辑节点内部 DOM.
-    //  - ignoreMutation 返回 true, PM 不会把这段 DOM 视为内容变更.
-    //  - 前后对称两个 spacer: 保证从左侧进卡片 (← / Home) 与从右侧
-    //    出卡片 (→ / End) 时 caret 着陆点一致.
-    const caretSpacerLeading = document.createTextNode('​');
-    const caretSpacerTrailing = document.createTextNode('​');
-    wrapper.appendChild(caretSpacerLeading);
-    wrapper.appendChild(card);
-    wrapper.appendChild(caretSpacerTrailing);
-
-    return wrapper;
+    const inlineAtomNodeView = createInlineAtomNodeView({
+      caretGeometry: wrapper.classList.contains('agent-composer__note-reference') ? 'single-line' : undefined,
+      wrapper,
+      wrapperClassName: wrapper.className,
+      content: card,
+      onClick: () => {
+        this.selectOnClick();
+        if (this.presentation === 'composer') this.previewController?.toggle();
+      },
+      onDoubleClick: () => { void this.handleDoubleClick(); },
+      ...(this.presentation === 'composer' ? {
+        hoverActions: [{
+          ariaLabel: `移除笔记引用 ${noteReferenceDisplayTitle(this.node.attrs as NoteReferenceAttrs)}`,
+          icon: createInlineAtomCloseIcon(),
+          onClick: () => deleteInlineAtomNode(this.view, this.node, this.getPos),
+        }],
+      } : {}),
+    });
+    wrapper.draggable = true;
+    return inlineAtomNodeView.dom;
+  }
+
+  private previewLocatorKey(): string {
+    const attrs = this.node.attrs as NoteReferenceAttrs;
+    return JSON.stringify([
+      attrs.notebookId ?? '',
+      attrs.notebookName ?? '',
+      attrs.relativePath ?? '',
+      attrs.originalPath ?? '',
+      attrs.linkTarget ?? '',
+    ]);
   }
 
-  private async handleClick(e: MouseEvent): Promise<void> {
-    e.preventDefault();
-    e.stopPropagation();
-
-    // 双击才触发跳转; 单击 / ⌘+click / Ctrl+click 都不打开。
-    if (e.detail < 2) {
-      // 键盘触发的 click 没有前置 mousedown, 仍保留节点选中语义。
-      const pos = this.getPos?.();
-      if (pos !== undefined) {
-        const sel = NodeSelection.create(this.view.state.doc, pos);
-        this.view.dispatch(this.view.state.tr.setSelection(sel));
+  private async loadNotePreviewData(): Promise<NoteReferencePreviewData | null> {
+    let attrs = this.node.attrs as NoteReferenceAttrs;
+    let notebookId = attrs.notebookId;
+    let relativePath = attrs.relativePath ?? null;
+    let notebookPath: string | null = null;
+    let location: Awaited<ReturnType<typeof notesClient.resolveLocation>> | null = null;
+    let physicalPath = attrs.originalPath;
+    let notebookName = attrs.notebookName;
+
+    if (attrs.linkTarget && /^flowix:\/\/open\?/i.test(attrs.linkTarget)) {
+      try {
+        const url = new URL(attrs.linkTarget);
+        notebookId ||= url.searchParams.get('notebookId');
+        relativePath ||= url.searchParams.get('f') ?? url.searchParams.get('file') ?? url.searchParams.get('relativePath');
+        notebookName ||= url.searchParams.get('b') ?? url.searchParams.get('book') ?? '';
+        physicalPath ||= url.searchParams.get('path');
+      } catch { /* Keep the authored attrs as fallback. */ }
+    } else if (!physicalPath && attrs.linkTarget && /^\//.test(attrs.linkTarget)) {
+      physicalPath = attrs.linkTarget;
+    }
+
+    if ((!notebookId || !relativePath) && physicalPath) {
+      try {
+        location = await notesClient.resolveLocation(physicalPath);
+        notebookId ||= location?.notebookId;
+        relativePath ||= location?.relativePath;
+        notebookPath = location?.notebookPath ?? null;
+      } catch { /* A missing note still gets a title-only preview. */ }
+    }
+
+    if (!notebookId || !relativePath) {
+      // Relative wiki links may be resolved lazily by the same note-reference
+      // resolver used when opening the chip. Re-read attrs after it completes.
+      if (attrs.linkStyle === 'wiki' && attrs.linkTarget) {
+        await this.refreshMemoAttrs();
+        attrs = this.node.attrs as NoteReferenceAttrs;
+        notebookId = attrs.notebookId;
+        relativePath = attrs.relativePath ?? null;
       }
-      return;
     }
 
+    if (!notebookId && relativePath && notebookName) {
+      let notebooks = useNoteStore.getState().notebooks;
+      if (!notebooks.length) {
+        await useNoteStore.getState().loadNotebooks();
+        notebooks = useNoteStore.getState().notebooks;
+      }
+      const matches = notebooks.filter((item) => item.name === notebookName);
+      if (matches.length === 1) notebookId = matches[0].id;
+    }
+
+    if (!notebookId || !relativePath) {
+      return null;
+    }
+
+    let notebook = useNoteStore.getState().notebooks.find((item) => item.id === notebookId);
+    if (!notebook) {
+      await useNoteStore.getState().loadNotebooks();
+      notebook = useNoteStore.getState().notebooks.find((item) => item.id === notebookId);
+    }
+    notebookPath ||= notebook?.path ?? null;
+    const filePath = notebookPath ? joinNotebookMemoPath(notebookPath, relativePath) : null;
+    if (!notebookPath || !filePath) {
+      return null;
+    }
+
+    let entry: NoteEntry | null = null;
+    try {
+      entry = await notesClient.getIndexed(notebookId, relativePath);
+    } catch { /* Render the saved reference title if the index is unavailable. */ }
+
+    const data: NoteReferencePreviewData = {
+      title: entry?.title || noteReferenceDisplayTitle(attrs) || tKey('editor.noteLink.untitled'),
+      preview: entry?.preview ?? '',
+      thumbnail: entry?.thumbnail ?? null,
+      notebookId,
+      relativePath,
+      notebookPath,
+      filePath,
+    };
+    return data;
+  }
+
+  private selectOnClick(): void {
+    // 键盘触发的 click 没有前置 mousedown, 仍保留节点选中语义。
+    const pos = this.getPos?.();
+    if (pos !== undefined) {
+      const sel = NodeSelection.create(this.view.state.doc, pos);
+      this.view.dispatch(this.view.state.tr.setSelection(sel));
+    }
+  }
+
+  private async handleDoubleClick(): Promise<void> {
     const attrs = this.node.attrs as NoteReferenceAttrs;
     if (attrs.linkTarget && /^flowix:\/\/memo\//i.test(attrs.linkTarget)) {
       this.applyAttrs({ stale: true });
@@ -494,10 +453,10 @@ class NoteReferenceView implements ProseMirrorNodeView {
   private refreshCard(): void {
     // 与 fileAttachment 保持同一策略: attrs 更新时只替换内部 card,
     // 保留外层 wrapper、caret spacer 和 ProseMirror 对 NodeView DOM 的引用。
-    const newCard = this.createCard().querySelector('.editor-note-reference__card') as HTMLElement | null;
+    const newCard = this.createCard().querySelector('.note-reference__card') as HTMLElement | null;
     if (!newCard) return;
 
-    const oldCard = this.dom.querySelector('.editor-note-reference__card');
+    const oldCard = this.dom.querySelector('.note-reference__card');
     if (oldCard) {
       this.dom.replaceChild(newCard, oldCard);
       return;
@@ -532,41 +491,31 @@ class NoteReferenceView implements ProseMirrorNodeView {
 
   update(node: ProseMirrorNode): boolean {
     if (node.type.name !== 'noteReference') return false;
+    const previousKey = this.previewLocatorKey();
     this.node = node;
     this.refreshCard();
+    this.previewController?.syncAnchorState();
+    if (previousKey !== this.previewLocatorKey()) {
+      this.previewController?.invalidate();
+    }
     // update 触发场景: 文档被外部修改 / 切换 memo / undo-redo,
     // 节点 attrs 可能刚被改过, 仍跑一次异步校验兜底.
     return true;
   }
 
-  /**
-   * 用 memoId 反查最新 memo 元数据, 与当前 attrs 比对:
-   *   - 解析失败 (memo 被删) → 落 stale.
-   *   - title / notebookName / originalPath / notebookId 任一变化 → 写回 doc.
-   *
-   * 通过 this.refreshPromise 跟踪 in-flight Promise, 短时间内多次触发
-   * (mount + 立刻 update) 时复用同一次请求, 避免后端被反复打.
-   */
+  /** Validate a note reference using its path target. */
   private refreshPromise: Promise<void> | null = null;
 
   refreshMemoAttrs(): Promise<void> {
     if (this.refreshPromise) return this.refreshPromise;
 
     const initialAttrs = this.node.attrs as NoteReferenceAttrs;
-    // 反查路径优先级:
-    //   1. memoId     — 稳定主键, 跨改名/跨笔记本移动不断链
-    //   2. originalPath — 物理路径粘贴场景下 memoId 缺失, 用来反查补 memoId
-    //   都没有 → 无可解析, 直接 return (createCard 已按 !memoId && !originalPath 落 stale)
-    if (!initialAttrs.memoId && !initialAttrs.originalPath && !initialAttrs.linkTarget) {
+    if (!initialAttrs.notebookId && !initialAttrs.notebookName && !initialAttrs.originalPath && !initialAttrs.linkTarget) {
       return Promise.resolve();
     }
 
     this.refreshPromise = (async () => {
       try {
-        if (initialAttrs.linkTarget && /^flowix:\/\/memo\//i.test(initialAttrs.linkTarget)) {
-          if (!(this.node.attrs as NoteReferenceAttrs).stale) this.applyAttrs({ stale: true });
-          return;
-        }
         if (initialAttrs.notebookName && initialAttrs.relativePath && !initialAttrs.notebookId) {
           let notebooks = useNoteStore.getState().notebooks;
           if (!notebooks.some((item) => item.name === initialAttrs.notebookName)) {
@@ -601,10 +550,6 @@ class NoteReferenceView implements ProseMirrorNodeView {
           if ((this.node.attrs as NoteReferenceAttrs).stale !== stale) this.applyAttrs({ stale });
           return;
         }
-        if (initialAttrs.memoId) {
-          if (!(this.node.attrs as NoteReferenceAttrs).stale) this.applyAttrs({ stale: true });
-          return;
-        }
         const target = initialAttrs.linkTarget!;
         let notebookId: string | null = null;
         let relativePath: string | null = null;
@@ -656,11 +601,11 @@ class NoteReferenceView implements ProseMirrorNodeView {
   }
 
   selectNode(): void {
-    this.dom.classList.add('is-selected');
+    setInlineAtomNodeViewSelected(this.dom, true);
   }
 
   deselectNode(): void {
-    this.dom.classList.remove('is-selected');
+    setInlineAtomNodeViewSelected(this.dom, false);
   }
 
   stopEvent(event: Event): boolean {
@@ -675,305 +620,217 @@ class NoteReferenceView implements ProseMirrorNodeView {
 
   destroy(): void {
     this.destroyed = true;
-    this.dom.removeEventListener('click', this.clickHandler);
+    this.previewController?.dispose();
+    this.previewController = null;
   }
 }
 
 // ─── Node definition ──────────────────────────────────────────────────────────
 
-export const NoteReference = Node.create({
-  name: 'noteReference',
-  group: 'inline',
-  inline: true,
-  atom: true,
-  selectable: true,
-  draggable: true,
-  // 抢在 Markdown 扩展之前注册 tokenizer
-  priority: 1000,
-
-  addAttributes() {
-    return {
-      memoId:        { default: null },
-      relativePath: { default: null },
-      notebookId:   { default: null },
-      notebookName: { default: '' },
-      title:        { default: '' },
-      originalPath: { default: null },
-      linkStyle:    { default: 'flowix' },
-      linkTarget:   { default: null },
-      heading:      { default: null },
-      stale:        { default: false },
-    };
-  },
-
-  parseHTML() {
-    return [
-      {
-        tag: 'note',
-        getAttrs: (el: HTMLElement) => {
-          const memoId        = el.getAttribute('id') || null;
-          const notebookId   = el.getAttribute('notebook') || null;
-          const originalPath = el.getAttribute('path') || null;
-          const relativePath = el.getAttribute('relativePath') || null;
-          const stale        = parseBooleanAttr(el.getAttribute('stale'));
-          const { notebookName, title } = splitDisplay(el.textContent ?? '');
-          return { memoId, notebookId, relativePath, notebookName, title, originalPath, linkStyle: 'flowix', linkTarget: null, heading: null, stale };
-        },
-      },
-    ];
-  },
-
-  renderHTML({ node }) {
-    const a = node.attrs as NoteReferenceAttrs;
-    return [
-      'note',
-      {
-        id: a.memoId ?? '',
-        notebook: a.notebookId ?? '',
-        relativePath: a.relativePath ?? '',
-        path: a.originalPath ?? '',
-        ...(a.stale ? { stale: 'true' } : {}),
-      },
-      // 序列化时 strip title 后缀, 跟 NodeView 渲染一致; 旧 markdown
-      // 历史里写 "foo.md" 也能正常 parse, 因为 splitDisplay 不剥后缀,
-      // 但下次落盘会被统一成无后缀形式.
-      `${a.notebookName || ''}${a.notebookName ? '/' : ''}${stripMdSuffix(a.title || '')}`,
-    ];
-  },
-
-  // ─── Markdown round-trip ──────────────────────────────────────────────────
-  // 新格式 `[title](flowix://memo/<id>)` 和旧格式 `<note ...>` 都转回
-  // noteReference 节点, 这样落盘格式可以迁移为标准 Markdown 链接,
-  // 渲染仍保持当前卡片 NodeView。
-
-  markdownTokenizer: {
+function createNoteReferenceExtension(presentation: 'document' | 'composer') {
+  const caretPluginKey = new PluginKey<DecorationSet>(`noteReferenceTerminalCaret:${presentation}`);
+  return Node.create({
     name: 'noteReference',
-    level: 'inline' as const,
-    start(src: string) {
-      const noteIndex = src.indexOf('<note ');
-      const linkHrefIndex = [src.indexOf('(flowix://memo/'), src.indexOf('(flowix://open?')]
-        .filter(index => index >= 0).sort((a, b) => a - b)[0] ?? -1;
-      const wikiIndex = src.indexOf('[[');
-      const indexes = [noteIndex, linkHrefIndex < 0 ? -1 : Math.max(0, src.lastIndexOf('[', linkHrefIndex)), wikiIndex]
-        .filter(index => index >= 0);
-      if (indexes.length === 0) return -1;
-      return Math.min(...indexes);
+    group: 'inline',
+    inline: true,
+    atom: true,
+    selectable: true,
+    draggable: true,
+    // 抢在 Markdown 扩展之前注册 tokenizer
+    priority: 1000,
+
+    addAttributes() {
+      return {
+        relativePath: { default: null },
+        notebookId:   { default: null },
+        notebookName: { default: '' },
+        title:        { default: '' },
+        originalPath: { default: null },
+        linkStyle:    { default: 'flowix' },
+        linkTarget:   { default: null },
+        heading:      { default: null },
+        stale:        { default: false },
+      };
     },
-    tokenize(src: string) {
-      const wiki = parseWikiNoteLinkAtStart(src);
-      if (wiki) {
-        return { type: 'noteReference', raw: wiki.raw, wiki };
-      }
-      const link = parseMarkdownNoteLinkAtStart(src);
-      if (link) {
-        return {
-          type: 'noteReference',
-          raw: link.raw,
-          href: link.href,
-          text: link.text,
-        };
-      }
 
-      const note = /^<note\s+([^>]*)>([\s\S]*?)<\/note>/.exec(src);
-      if (!note) return undefined;
-      return { type: 'noteReference', raw: note[0], attrs: note[1], text: note[2] };
+    parseHTML() {
+      return [
+        {
+          tag: 'note',
+          getAttrs: (el: HTMLElement) => {
+            const notebookId   = el.getAttribute('notebook') || null;
+            const originalPath = el.getAttribute('path') || null;
+            const relativePath = el.getAttribute('relativePath') || null;
+            const stale        = parseBooleanAttr(el.getAttribute('stale'));
+            const { notebookName, title } = splitDisplay(el.textContent ?? '');
+            return { notebookId, relativePath, notebookName, title, originalPath, linkStyle: 'flowix', linkTarget: null, heading: null, stale };
+          },
+        },
+      ];
     },
-  },
 
-  parseMarkdown(token: MarkdownToken) {
-    const wiki = token.wiki as ParsedWikiNoteLink | undefined;
-    if (wiki) {
-      return { type: 'noteReference', attrs: attrsFromWikiNoteLink(wiki) };
-    }
-    const href = String(token.href ?? '');
-    if (FLOWIX_MEMO_URL_RE.test(href)) {
-      return {
-        type: 'noteReference',
-        attrs: attrsFromMarkdownNoteLink(String(token.text ?? ''), href),
-      };
-    }
+    renderHTML({ node }) {
+      const a = node.attrs as NoteReferenceAttrs;
+      return [
+        'note',
+        {
+          notebook: a.notebookId ?? '',
+          relativePath: a.relativePath ?? '',
+          path: a.originalPath ?? '',
+          ...(a.stale ? { stale: 'true' } : {}),
+        },
+        // 序列化时 strip title 后缀, 跟 NodeView 渲染一致; 旧 markdown
+        // 历史里写 "foo.md" 也能正常 parse, 因为 splitDisplay 不剥后缀,
+        // 但下次落盘会被统一成无后缀形式.
+        `${a.notebookName || ''}${a.notebookName ? '/' : ''}${stripMdSuffix(a.title || '')}`,
+      ];
+    },
 
-    const attrsStr = String(token.attrs ?? '');
-    const text     = String(token.text ?? '');
-    const { notebookName, title } = splitDisplay(unescapeHtml(text));
-    // memoId 缺失 → null (而不是 ''), 与 addAttributes default null 一致;
-    // 配合 renderMarkdown 在缺失时不写 id="" 属性, 避免 "memoId='' → 落
-    // stale → save → 写 id='' → 重新 parse → 仍然 stale" 的死锁. mount
-    // 时 refreshMemoAttrs 会用 originalPath 反查补回 memoId.
-    const rawId = pickAttr(attrsStr, 'id');
-    return {
-      type: 'noteReference',
-      attrs: {
-        memoId:        rawId && rawId.length > 0 ? rawId : null,
-        notebookId:   pickAttr(attrsStr, 'notebook'),
-        relativePath: pickAttr(attrsStr, 'relativePath'),
-        notebookName,
-        title,
-        originalPath: pickAttr(attrsStr, 'path'),
-        linkStyle:    'flowix',
-        linkTarget:   null,
-        heading:      null,
-        stale:        parseBooleanAttr(pickAttr(attrsStr, 'stale')),
-      },
-    };
-  },
-
-  renderMarkdown(node: JSONContent) {
-    const a = (node?.attrs ?? {}) as NoteReferenceAttrs;
-    const displayTitle = escapeMarkdownLinkText(noteReferenceDisplayTitle(a));
-    if (a.linkStyle === 'wiki' && a.linkTarget) {
-      const target = `${a.linkTarget}${a.heading ? `#${a.heading}` : ''}`;
-      const naturalTitle = a.linkTarget.split('/').pop()?.replace(/\.md$/i, '') ?? a.linkTarget;
-      return `[[${target}${a.title && a.title !== naturalTitle ? `|${a.title}` : ''}]]`;
-    }
-    if (a.linkStyle === 'markdown' && a.linkTarget) {
-      const target = `${a.linkTarget}${a.heading ? `#${a.heading}` : ''}`.replace(/ /g, '%20');
-      return `[${escapeMarkdownLinkText(a.title || stripMdSuffix(a.linkTarget))}](${target})`;
-    }
-    if (a.linkTarget && /^flowix:\/\/memo\//i.test(a.linkTarget)) {
-      return `[${displayTitle}](${a.linkTarget})`;
-    }
-    if (a.relativePath) {
-      const notebook = a.notebookId
-        ? useNoteStore.getState().notebooks.find((item) => item.id === a.notebookId)
-        : null;
-      const book = notebook?.name ?? a.notebookName;
-      if (book) {
-        const target = buildNoteOpenLink(book, a.relativePath);
-        return `[${displayTitle}](${target})`;
+    // ─── Markdown round-trip ──────────────────────────────────────────────────
+    // Path based Flowix links and authored note tags render as note cards.
+
+    ...noteReferenceMarkdownSpec,
+
+    renderMarkdown(node: JSONContent) {
+      const a = (node?.attrs ?? {}) as NoteReferenceAttrs;
+      const displayTitle = escapeMarkdownLinkText(noteReferenceDisplayTitle(a));
+      if (a.linkStyle === 'wiki' && a.linkTarget) {
+        const target = `${a.linkTarget}${a.heading ? `#${a.heading}` : ''}`;
+        const naturalTitle = a.linkTarget.split('/').pop()?.replace(/\.md$/i, '') ?? a.linkTarget;
+        return `[[${target}${a.title && a.title !== naturalTitle ? `|${a.title}` : ''}]]`;
       }
-      if (a.linkTarget) {
+      if (a.linkStyle === 'markdown' && a.linkTarget) {
+        const target = `${a.linkTarget}${a.heading ? `#${a.heading}` : ''}`.replace(/ /g, '%20');
+        return `[${escapeMarkdownLinkText(a.title || stripMdSuffix(a.linkTarget))}](${target})`;
+      }
+      if (a.linkTarget && /^flowix:\/\/memo\//i.test(a.linkTarget)) {
         return `[${displayTitle}](${a.linkTarget})`;
       }
-      if (a.notebookId) {
-        const target = `flowix://open?notebookId=${encodeURIComponent(a.notebookId)}&relativePath=${encodeURIComponent(a.relativePath)}`;
-        return `[${displayTitle}](${target})`;
+      if (a.relativePath) {
+        const notebook = a.notebookId
+          ? useNoteStore.getState().notebooks.find((item) => item.id === a.notebookId)
+          : null;
+        const book = notebook?.name ?? a.notebookName;
+        if (book) {
+          const target = buildNoteOpenLink(book, a.relativePath);
+          return `[${displayTitle}](${target})`;
+        }
+        if (a.linkTarget) {
+          return `[${displayTitle}](${a.linkTarget})`;
+        }
+        if (a.notebookId) {
+          const target = `flowix://open?notebookId=${encodeURIComponent(a.notebookId)}&relativePath=${encodeURIComponent(a.relativePath)}`;
+          return `[${displayTitle}](${target})`;
+        }
       }
-    }
-    if (a.linkTarget?.startsWith('flowix://open?') && !a.originalPath) {
-      return `[${displayTitle}](${a.linkTarget})`;
-    }
-    const pathLink = a.originalPath ? noteLinkForIndexedPath(a.originalPath) : null;
-    if (pathLink) {
-      return `[${displayTitle}](${pathLink})`;
-    }
-    if (a.originalPath) {
-      const fallback = `flowix://open?path=${encodeURIComponent(a.originalPath)}`;
-      return `[${displayTitle}](${fallback})`;
-    }
-    return escapeMarkdownLinkText(stripMdSuffix(a.title || ''));
-  },
+      if (a.linkTarget?.startsWith('flowix://open?') && !a.originalPath) {
+        return `[${displayTitle}](${a.linkTarget})`;
+      }
+      const pathLink = a.originalPath ? noteLinkForIndexedPath(a.originalPath) : null;
+      if (pathLink) {
+        return `[${displayTitle}](${pathLink})`;
+      }
+      if (a.originalPath) {
+        const fallback = `flowix://open?path=${encodeURIComponent(a.originalPath)}`;
+        return `[${displayTitle}](${fallback})`;
+      }
+      return escapeMarkdownLinkText(stripMdSuffix(a.title || ''));
+    },
 
-  // ─── NodeView ─────────────────────────────────────────────────────────────
+    // ─── NodeView ─────────────────────────────────────────────────────────────
 
-  addNodeView() {
-    return ({ node, view, getPos }) => new NoteReferenceView(node, view, getPos as () => number | undefined);
-  },
+    addNodeView() {
+      return ({ node, view, getPos }) => new NoteReferenceView(node, view, getPos as () => number | undefined, presentation);
+    },
 
-  // ─── HardBreak 清理 ───────────────────────────────────────────────────────
-  // 与 fileAttachment 同源(`attachment-link/nodes/view-file.ts:onCreate / addProseMirrorPlugins`):
-  // 编辑器刚创建时扫一遍,后续每次文档变动也扫一遍,防止用户手动在卡片
-  // 前后插入换行(Shift+Enter)导致卡片头部或末尾出现同块空行。
+    // ─── HardBreak 清理 ───────────────────────────────────────────────────────
+    // 与 fileAttachment 同源(`attachment-link/nodes/view-file.ts:onCreate / addProseMirrorPlugins`):
+    // 编辑器刚创建时扫一遍,后续每次文档变动也扫一遍,防止用户手动在卡片
+    // 前后插入换行(Shift+Enter)导致卡片头部或末尾出现同块空行。
 
-  onCreate() {
-    const tr = removeHardBreaksAroundNoteReferences(this.editor.state);
-    if (tr?.docChanged) {
-      this.editor.view.dispatch(tr);
-    }
-  },
-
-  addProseMirrorPlugins() {
-    return [
-      new Plugin({
-        key: noteReferenceCaretPluginKey,
-        state: {
-          init: (_, state) => createTerminalInlineAtomCaretDecorations(state.doc, 'noteReference'),
-          apply: (transaction, value, _oldState, newState) => (
-            transaction.docChanged
-              ? createTerminalInlineAtomCaretDecorations(newState.doc, 'noteReference')
-              : value
+    onCreate() {
+      const tr = removeHardBreaksAroundNoteReferences(this.editor.state);
+      if (tr?.docChanged) {
+        this.editor.view.dispatch(tr);
+      }
+    },
+
+    addProseMirrorPlugins() {
+      return [
+        new Plugin({
+          key: caretPluginKey,
+          state: {
+            init: (_, state) => createTerminalInlineAtomCaretDecorations(state.doc, 'noteReference'),
+            apply: (transaction, value, _oldState, newState) => (
+              transaction.docChanged
+                ? createTerminalInlineAtomCaretDecorations(newState.doc, 'noteReference')
+                : value
+            ),
+          },
+          props: {
+            decorations: (state) => caretPluginKey.getState(state) ?? DecorationSet.empty,
+          },
+          appendTransaction: (transactions, _oldState, newState) => {
+            if (!transactions.some(transaction => transaction.docChanged)) return null;
+            return removeHardBreaksAroundNoteReferences(newState);
+          },
+        }),
+      ];
+    },
+
+    addInputRules() {
+      return [
+        nodeInputRule({
+          find: findLastWikiNoteLink,
+          type: this.type,
+          getAttributes: match => attrsFromWikiNoteLink(match.data as unknown as ParsedWikiNoteLink),
+        }),
+        nodeInputRule({
+          find: findLastMarkdownNoteLink,
+          type: this.type,
+          getAttributes: match => attrsFromMarkdownNoteLink(
+            String(match.data?.title ?? ''),
+            String(match.data?.href ?? '')
           ),
+        }),
+      ];
+    },
+
+    addPasteRules() {
+      return [
+        nodePasteRule({
+          find: findWikiNotePasteMatches,
+          type: this.type,
+          getAttributes: match => attrsFromWikiNoteLink(match.data as unknown as ParsedWikiNoteLink),
+        }),
+        nodePasteRule({
+          find: findMarkdownNotePasteMatches,
+          type: this.type,
+          getAttributes: match => attrsFromMarkdownNoteLink(
+            String(match.data?.title ?? ''),
+            String(match.data?.href ?? '')
+          ),
+        }),
+      ];
+    },
+
+    // ─── Keyboard ─────────────────────────────────────────────────────────────
+
+    addKeyboardShortcuts() {
+      return {
+        Backspace: () => {
+          return deleteAdjacentInlineAtom(this.editor, 'noteReference', 'before');
         },
-        props: {
-          decorations: (state) => noteReferenceCaretPluginKey.getState(state) ?? DecorationSet.empty,
-        },
-        appendTransaction: (transactions, _oldState, newState) => {
-          if (!transactions.some(transaction => transaction.docChanged)) return null;
-          return removeHardBreaksAroundNoteReferences(newState);
+        Delete: () => {
+          return deleteAdjacentInlineAtom(this.editor, 'noteReference', 'after');
         },
-      }),
-    ];
-  },
-
-  addInputRules() {
-    return [
-      nodeInputRule({
-        find: findLastWikiNoteLink,
-        type: this.type,
-        getAttributes: match => attrsFromWikiNoteLink(match.data as unknown as ParsedWikiNoteLink),
-      }),
-      nodeInputRule({
-        find: findLastMarkdownNoteLink,
-        type: this.type,
-        getAttributes: match => attrsFromMarkdownNoteLink(
-          String(match.data?.title ?? ''),
-          String(match.data?.href ?? '')
-        ),
-      }),
-    ];
-  },
-
-  addPasteRules() {
-    return [
-      nodePasteRule({
-        find: findWikiNotePasteMatches,
-        type: this.type,
-        getAttributes: match => attrsFromWikiNoteLink(match.data as unknown as ParsedWikiNoteLink),
-      }),
-      nodePasteRule({
-        find: findMarkdownNotePasteMatches,
-        type: this.type,
-        getAttributes: match => attrsFromMarkdownNoteLink(
-          String(match.data?.title ?? ''),
-          String(match.data?.href ?? '')
-        ),
-      }),
-    ];
-  },
-
-  // ─── Keyboard ─────────────────────────────────────────────────────────────
-
-  addKeyboardShortcuts() {
-    return {
-      Backspace: () => {
-        const { selection } = this.editor.state;
-        if (selection instanceof NodeSelection && selection.node.type.name === 'noteReference') {
-          this.editor.commands.deleteSelection();
-          return true;
-        }
-        const { $from } = selection;
-        const before = $from.nodeBefore;
-        if (before && before.type.name === 'noteReference') {
-          const from = $from.pos - before.nodeSize;
-          this.editor.commands.deleteRange({ from, to: $from.pos });
-          return true;
-        }
-        return false;
-      },
-      Delete: () => {
-        const { selection } = this.editor.state;
-        if (selection instanceof NodeSelection && selection.node.type.name === 'noteReference') {
-          this.editor.commands.deleteSelection();
-          return true;
-        }
-        const { $from } = selection;
-        const after = $from.nodeAfter;
-        if (after && after.type.name === 'noteReference') {
-          this.editor.commands.deleteRange({ from: $from.pos, to: $from.pos + after.nodeSize });
-          return true;
-        }
-        return false;
-      },
-    };
-  },
-});
+      };
+    },
+  });
+}
+
+/** Document-editor note references. */
+export const NoteReference = createNoteReferenceExtension('document');
+
+/** Composer note references use a separate extension and plugin key. */
+export const ComposerNoteReference = createNoteReferenceExtension('composer');
diff --git a/app/flowix-web/features/editor/extensions/note-mention/note-mention-data.ts b/app/flowix-web/features/editor/extensions/note-mention/note-mention-data.ts
index e942009ec..f95621dcc 100644
--- a/app/flowix-web/features/editor/extensions/note-mention/note-mention-data.ts
+++ b/app/flowix-web/features/editor/extensions/note-mention/note-mention-data.ts
@@ -67,7 +67,6 @@ export function queryMentionNotes(query: string): Promise<MentionNoteItem[]> {
 
 export function toNoteReferenceAttrs(item: MentionNoteItem): NoteReferenceAttrs {
   return {
-    memoId: null,
     notebookId: item.notebookId,
     relativePath: item.relativePath,
     notebookName: item.notebookName,
diff --git a/app/flowix-web/features/editor/extensions/note-mention/note-mention-dropdown.tsx b/app/flowix-web/features/editor/extensions/note-mention/note-mention-dropdown.tsx
index c4d3e5853..f3cbfef36 100644
--- a/app/flowix-web/features/editor/extensions/note-mention/note-mention-dropdown.tsx
+++ b/app/flowix-web/features/editor/extensions/note-mention/note-mention-dropdown.tsx
@@ -50,7 +50,7 @@ export function NoteMentionDropdown({
         <span>{t('editor.noteMention.header')}</span>
         {loading && (
           <LoaderCircle
-            className="mention-note-header-spinner"
+            className="mention-note-header-spinner flowix-spin"
             aria-hidden="true"
           />
         )}
diff --git a/app/flowix-web/features/editor/extensions/paste-rules/index.ts b/app/flowix-web/features/editor/extensions/paste-rules/index.ts
index 05299a58a..adf49ac9f 100644
--- a/app/flowix-web/features/editor/extensions/paste-rules/index.ts
+++ b/app/flowix-web/features/editor/extensions/paste-rules/index.ts
@@ -6,13 +6,17 @@ import { hasImportableHtml, isInternalEditorHtml, sanitizeExternalHtml } from '@
 import type { PasteContext } from '@features/editor/extensions/paste-rules/types';
 import type { Editor } from '@tiptap/core';
 
-export const ManagedPasteRules = Extension.create<{ ownerPath?: string; getOwnerPath?: () => string | undefined }>({
+export const ManagedPasteRules = Extension.create<{
+  ownerPath?: string;
+  getOwnerPath?: () => string | undefined;
+}>({
   name: 'managedPasteRules',
   priority: 1100,
 
   addOptions() {
     return {
       ownerPath: undefined,
+      getOwnerPath: undefined,
     };
   },
 
@@ -33,7 +37,9 @@ export const ManagedPasteRules = Extension.create<{ ownerPath?: string; getOwner
             const clipboardData = event.clipboardData;
             if (!clipboardData) return false;
             const snapshot = readClipboardSnapshot(clipboardData);
-            const ownerPath = this.options.getOwnerPath ? this.options.getOwnerPath() : this.options.ownerPath;
+            const ownerPath = this.options.getOwnerPath
+              ? this.options.getOwnerPath()
+              : this.options.ownerPath;
             if (snapshot.html && !hasImportableHtml(snapshot.html) && snapshot.text) {
               event.preventDefault();
               return pasteClipboardSnapshot(this.editor, { ...snapshot, html: '' }, ownerPath);
diff --git a/app/flowix-web/features/editor/extensions/shared/inline-atom-nodeview.ts b/app/flowix-web/features/editor/extensions/shared/inline-atom-nodeview.ts
new file mode 100644
index 000000000..233b97980
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/shared/inline-atom-nodeview.ts
@@ -0,0 +1,173 @@
+import type { Editor } from "@tiptap/core";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { NodeSelection } from "@tiptap/pm/state";
+import type { EditorView } from "@tiptap/pm/view";
+
+export interface InlineAtomHoverAction {
+  ariaLabel: string;
+  title?: string;
+  icon: Node;
+  onClick: (event: MouseEvent) => void;
+}
+
+export interface InlineAtomNodeViewOptions {
+  wrapperClassName?: string;
+  wrapper?: HTMLSpanElement;
+  /** Opt into border-based caret positioning for a single-line chip. */
+  caretGeometry?: 'single-line';
+  cardClassName?: string;
+  leadingIcon?: Node;
+  label?: string;
+  labelClassName?: string;
+  title?: string;
+  ariaLabel?: string;
+  content?: HTMLElement;
+  onClick?: (event: MouseEvent) => void;
+  onDoubleClick?: (event: MouseEvent) => void;
+  remove?: {
+    view: EditorView;
+    node: ProseMirrorNode;
+    getPos?: () => number | undefined;
+  };
+  hoverActions?: readonly InlineAtomHoverAction[];
+  stopEvent?: (event: Event) => boolean;
+}
+
+/** Small close affordance shared by removable composer chips. */
+export function createInlineAtomCloseIcon(): SVGSVGElement {
+  const icon = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  icon.setAttribute("viewBox", "0 0 16 16");
+  icon.setAttribute("fill", "none");
+  icon.setAttribute("stroke", "currentColor");
+  icon.setAttribute("stroke-width", "1.7");
+  icon.setAttribute("stroke-linecap", "round");
+  icon.setAttribute("aria-hidden", "true");
+  const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  path.setAttribute("d", "m4 4 8 8M12 4l-8 8");
+  icon.append(path);
+  return icon;
+}
+
+/** Delete an inline atom at its current document position. */
+export function deleteInlineAtomNode(
+  view: EditorView,
+  node: ProseMirrorNode,
+  getPos?: () => number | undefined,
+): void {
+  const pos = getPos?.();
+  if (pos === undefined) return;
+  view.dispatch(view.state.tr.delete(pos, pos + node.nodeSize));
+  view.focus();
+}
+
+/**
+ * Creates the shared shell and interaction surface for inline atom cards.
+ * Card contents and actions stay type-specific; focus, selection, hover-action
+ * plumbing, and caret landing points are handled consistently here.
+ */
+export function createInlineAtomNodeView(options: InlineAtomNodeViewOptions) {
+  const wrapper = options.wrapper ?? document.createElement("span");
+  if (options.wrapperClassName) wrapper.className = options.wrapperClassName;
+  wrapper.classList.add("editor-inline-atom");
+  wrapper.contentEditable = "false";
+  if (options.caretGeometry) wrapper.setAttribute('data-inline-atom-caret', options.caretGeometry);
+
+  const card = options.content ?? document.createElement("button");
+  card.setAttribute("data-inline-atom-card", "");
+  if (!options.content) {
+    const button = card as HTMLButtonElement;
+    button.type = "button";
+    if (options.cardClassName) button.className = options.cardClassName;
+    if (options.leadingIcon) {
+      button.append(options.leadingIcon);
+      const label = document.createElement("span");
+      if (options.labelClassName) label.className = options.labelClassName;
+      label.textContent = options.label ?? "";
+      button.append(label);
+    } else {
+      button.textContent = options.label ?? "";
+    }
+  }
+  if (wrapper.classList.contains("agent-composer__inline-atom-wrapper")) {
+    // Give composer atoms one styling hook regardless of their node type.
+    card.classList.add("agent-composer__inline-card");
+  }
+  if (options.title) card.title = options.title;
+  if (options.ariaLabel) card.setAttribute("aria-label", options.ariaLabel);
+  card.addEventListener("mousedown", (event) => event.preventDefault());
+
+  const actions = options.hoverActions ?? [];
+  const actionGroup = actions.length > 0 ? document.createElement("span") : null;
+  if (actionGroup) {
+    actionGroup.className = "agent-inline-atom__actions";
+    for (const action of actions) {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.className = "agent-inline-atom__action";
+      button.setAttribute("aria-label", action.ariaLabel);
+      button.title = action.title ?? action.ariaLabel;
+      button.append(action.icon);
+      button.addEventListener("mousedown", (event) => event.preventDefault());
+      button.addEventListener("click", (event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        action.onClick(event);
+      });
+      actionGroup.append(button);
+    }
+  }
+
+  // Real text nodes provide browser caret landing points on both sides of the
+  // non-editable atom; the trailing anchor stays after optional hover actions.
+  wrapper.append(document.createTextNode("\u200B"), card);
+  if (actionGroup) wrapper.append(actionGroup);
+  wrapper.append(document.createTextNode("\u200B"));
+
+  const remove = options.remove;
+  const onClick = options.onClick ?? (remove
+    ? () => deleteInlineAtomNode(remove.view, remove.node, remove.getPos)
+    : undefined);
+  if (onClick) {
+    wrapper.addEventListener("click", (event) => {
+      if ((event.target as Element | null)?.closest?.(".agent-inline-atom__actions")) return;
+      event.preventDefault();
+      event.stopPropagation();
+      onClick(event);
+    });
+  }
+  if (options.onDoubleClick) wrapper.addEventListener("dblclick", options.onDoubleClick);
+
+  return {
+    dom: wrapper,
+    selectNode: () => setInlineAtomNodeViewSelected(wrapper, true),
+    deselectNode: () => setInlineAtomNodeViewSelected(wrapper, false),
+    ...(options.stopEvent ? { stopEvent: options.stopEvent } : {}),
+    ignoreMutation: () => true,
+  };
+}
+
+export function setInlineAtomNodeViewSelected(wrapper: HTMLElement, selected: boolean): void {
+  wrapper.classList.toggle("is-selected", selected);
+}
+
+/** Delete an adjacent inline atom using the same Backspace/Delete behavior. */
+export function deleteAdjacentInlineAtom(
+  editor: Editor,
+  nodeName: string,
+  direction: "before" | "after",
+): boolean {
+  const { selection } = editor.state;
+  if (selection instanceof NodeSelection && selection.node.type.name === nodeName) {
+    editor.commands.deleteSelection();
+    return true;
+  }
+
+  if (!selection.empty) return false;
+  const { $from } = selection;
+  const node = direction === "before" ? $from.nodeBefore : $from.nodeAfter;
+  if (!node || node.type.name !== nodeName) return false;
+
+  const from = direction === "before" ? $from.pos - node.nodeSize : $from.pos;
+  editor.commands.deleteRange({ from, to: from + node.nodeSize });
+  return true;
+}
diff --git a/app/flowix-web/features/editor/extensions/shared/suggestion-menu.tsx b/app/flowix-web/features/editor/extensions/shared/suggestion-menu.tsx
index 9101f9701..644493e08 100644
--- a/app/flowix-web/features/editor/extensions/shared/suggestion-menu.tsx
+++ b/app/flowix-web/features/editor/extensions/shared/suggestion-menu.tsx
@@ -75,8 +75,8 @@ interface MenuInstance<TItem> {
 }
 
 // ─── 模块级单例: 同一时刻只允许一个 suggestion 弹窗 ──────────────────────
-// Mention 扩展共享同一容器 / 位置 / IME 状态,
-// 开新弹窗时主动 close 旧的, 避免两者并存。
+// Mention 扩展共享同一容器 / 位置 / IME 状态。
+// activeView 是弹窗 owner，其他编辑器的事件和销毁不能操作它。
 let menuState: MenuState | null = null;
 let menuInstance: MenuInstance<unknown> | null = null;
 let menuContainer: HTMLDivElement | null = null;
@@ -84,7 +84,7 @@ let menuRoot: Root | null = null;
 let activeEditor: Editor | null = null;
 let activeView: EditorView | null = null;
 let activeConfig: SuggestionMenuConfig<unknown> | null = null;
-let composing = false;
+let composingOwner: { view: EditorView; openId: number } | null = null;
 let menuPlacement: 'above' | 'below' | null = null;
 let positionFrame = 0;
 let menuOpenId = 0;
@@ -97,10 +97,15 @@ function disposeMenuRoot(root: Root, container: HTMLDivElement) {
 }
 
 function isComposing(view: EditorView): boolean {
-  return composing || Boolean((view as EditorView & { composing?: boolean }).composing);
+  return (
+    (composingOwner?.view === view && composingOwner.openId === menuOpenId)
+    || Boolean((view as EditorView & { composing?: boolean }).composing)
+  );
 }
 
-function closeMenu() {
+function closeMenu(ownerView?: EditorView) {
+  if (ownerView && activeView !== ownerView) return;
+
   menuOpenId += 1;
   document.removeEventListener('mousedown', handlePointerDownOutside, true);
   window.removeEventListener('resize', handleWindowResize);
@@ -120,7 +125,7 @@ function closeMenu() {
   activeEditor = null;
   activeView = null;
   activeConfig = null;
-  composing = false;
+  composingOwner = null;
   menuPlacement = null;
 
   if (root && container) {
@@ -153,10 +158,11 @@ function handleScrollOutside(event: Event) {
     return;
   }
 
+  const view = activeView;
   try {
-    refreshMenuFromEditor(activeView);
+    refreshMenuFromEditor(view);
   } catch {
-    closeMenu();
+    closeMenu(view);
   }
 }
 
@@ -221,16 +227,18 @@ function updatePosition(view: EditorView, width: number) {
   menuContainer.style.left = `${left}px`;
 }
 
-function scheduleUpdatePosition(view: EditorView, width: number) {
+function scheduleUpdatePosition(view: EditorView, width: number, openId: number) {
   if (positionFrame) window.cancelAnimationFrame(positionFrame);
   positionFrame = window.requestAnimationFrame(() => {
     positionFrame = 0;
+    if (!isCurrentMenuView(view, openId)) return;
     updatePosition(view, width);
   });
 }
 
 function renderMenu(view: EditorView) {
   if (!isCurrentMenuView(view)) return;
+  const openId = menuOpenId;
   const root = menuRoot;
   const instance = menuInstance;
   const config = activeConfig;
@@ -244,7 +252,7 @@ function renderMenu(view: EditorView) {
     hasMore: instance.visibleCount < instance.allItems.length,
     loading: instance.loading,
     onSelect: (item) => {
-      if (!activeEditor || !menuState || !activeConfig) return;
+      if (!isCurrentMenuView(view, openId) || !activeEditor || !menuState || !activeConfig) return;
       activeConfig.onSelect({
         editor: activeEditor,
         view,
@@ -255,12 +263,14 @@ function renderMenu(view: EditorView) {
       });
     },
     onHover: (index) => {
+      if (!isCurrentMenuView(view, openId)) return;
       if (!menuInstance) return;
       menuInstance.selectedIndex = index;
       menuInstance.scrollSelectedItem = false;
       renderMenu(view);
     },
     onLoadMore: () => {
+      if (!isCurrentMenuView(view, openId)) return;
       if (!menuInstance) return;
       menuInstance.visibleCount = Math.min(
         menuInstance.visibleCount + PAGE_SIZE,
@@ -270,7 +280,7 @@ function renderMenu(view: EditorView) {
     },
   }));
 
-  scheduleUpdatePosition(view, config.width);
+  scheduleUpdatePosition(view, config.width, openId);
 }
 
 function applyQueryItems(view: EditorView, items: unknown[], resetPage: boolean) {
@@ -388,7 +398,7 @@ function refreshMenuFromEditor(view: EditorView) {
 
   const query = config.parseQuery(view, state.triggerFrom, state.trigger);
   if (query === null) {
-    closeMenu();
+    closeMenu(view);
     return;
   }
 
@@ -425,19 +435,30 @@ export function createSuggestionExtension<TItem>(config: SuggestionMenuConfig<TI
           key: pluginKey,
 
           view(view) {
+            const handleBlur = (event: FocusEvent) => {
+              const nextTarget = event.relatedTarget;
+              if (nextTarget instanceof Node && menuContainer?.contains(nextTarget)) return;
+              closeMenu(view);
+            };
             const handleCompositionStart = () => {
-              if (menuState) composing = true;
+              if (activeView === view && menuState) {
+                composingOwner = { view, openId: menuOpenId };
+              }
             };
             const handleCompositionEnd = () => {
-              if (!composing) return;
-              composing = false;
+              const composition = composingOwner;
+              if (composition?.view !== view) return;
+              composingOwner = null;
               window.setTimeout(() => {
-                if (menuState) refreshMenuFromEditor(view);
+                if (isCurrentMenuView(view, composition.openId)) {
+                  refreshMenuFromEditor(view);
+                }
               }, 0);
             };
 
             view.dom.addEventListener('compositionstart', handleCompositionStart);
             view.dom.addEventListener('compositionend', handleCompositionEnd);
+            view.dom.addEventListener('blur', handleBlur);
 
             return {
               update(updatedView) {
@@ -451,8 +472,9 @@ export function createSuggestionExtension<TItem>(config: SuggestionMenuConfig<TI
                 if (!view.isDestroyed) {
                   view.dom.removeEventListener('compositionstart', handleCompositionStart);
                   view.dom.removeEventListener('compositionend', handleCompositionEnd);
+                  view.dom.removeEventListener('blur', handleBlur);
                 }
-                closeMenu();
+                closeMenu(view);
               },
             };
           },
@@ -469,7 +491,7 @@ export function createSuggestionExtension<TItem>(config: SuggestionMenuConfig<TI
                 from = prefixFrom;
               }
               if (!editor.isEditable || !view.state.selection.empty) {
-                closeMenu();
+                closeMenu(view);
                 return false;
               }
               if (isValidTriggerPosition && !isValidTriggerPosition(view, from)) {
@@ -481,7 +503,7 @@ export function createSuggestionExtension<TItem>(config: SuggestionMenuConfig<TI
             },
 
             handleKeyDown(view, event) {
-              if (!menuState || !menuInstance) return false;
+              if (!isCurrentMenuView(view) || !menuState || !menuInstance) return false;
               if (event.isComposing || isComposing(view)) return false;
 
               const visibleItems = menuInstance.allItems.slice(0, menuInstance.visibleCount);
@@ -519,7 +541,7 @@ export function createSuggestionExtension<TItem>(config: SuggestionMenuConfig<TI
 
               if (event.key === 'Escape') {
                 event.preventDefault();
-                closeMenu();
+                closeMenu(view);
                 return true;
               }
 
diff --git a/app/flowix-web/features/editor/extensions/slash-menu.tsx b/app/flowix-web/features/editor/extensions/slash-menu.tsx
index d2d80f128..64f2c3d21 100644
--- a/app/flowix-web/features/editor/extensions/slash-menu.tsx
+++ b/app/flowix-web/features/editor/extensions/slash-menu.tsx
@@ -16,12 +16,15 @@ import {
   isAgentTypeEnabled,
   subscribeEditorRuntimePreferences,
 } from '@features/preferences/public/runtime-api';
-import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
-import { normalizeAgentRuntimeStatus } from '@features/agent/public/runtime-status-api';
+import {
+  getAgentRuntimeStatusSnapshot,
+  getAvailableAgentTypes,
+  refreshAgentRuntimeStatusIfStale,
+  subscribeAgentRuntimeStatus,
+} from '@features/agent/public/runtime-status-api';
 import { windows } from '@platform/tauri/client';
 import { translate } from '@/lib/i18n';
 import type { AgentTypeKey } from '@/types/agent';
-import { isAgentTypeComingSoon } from '@/lib/agent-types';
 import { applyListType } from './list-transforms';
 import { openTableReferencePicker } from '@features/multidimensional-table/table-reference-picker';
 import { openMediaLibraryReferencePicker } from '@features/media-library/media-library-reference-picker';
@@ -65,12 +68,10 @@ function disposeMenuRoot(root: Root, container: HTMLDivElement) {
 const AGENT_THREAD_TYPE_BY_SLASH_ID: Record<AgentThreadSlashMenuItemId, AgentTypeKey> = {
   'agent-thread-pi': 'pi',
   'agent-thread-codex': 'codex',
-  'agent-thread-claude': 'claude',
-  'agent-thread-gemini': 'gemini',
+  'agent-thread-claude': 'claudecode',
   'agent-thread-hermes': 'hermes',
-  'agent-thread-openclaw': 'openclaw',
   'agent-thread-opencode': 'opencode',
-  'agent-thread-deepseek-harness': 'deepseek-harness',
+  'agent-thread-deepseek-harness': 'dsh',
 };
 
 const TABLE_VIEW_TYPE_BY_SLASH_ID: Partial<Record<SlashMenuItem['id'], TableViewType>> = {
@@ -84,23 +85,32 @@ function isAgentThreadSlashMenuItemId(id: SlashMenuItem['id']): id is AgentThrea
   return id in AGENT_THREAD_TYPE_BY_SLASH_ID;
 }
 
-function isAgentRuntimeAvailable(typeKey: AgentTypeKey): boolean {
-  if (isAgentTypeComingSoon(typeKey)) return false;
-  const runtime = useAgentRuntimeStore.getState();
-  return normalizeAgentRuntimeStatus(runtime.statusByType[typeKey], runtime.isChecking).state === 'ready';
-}
+function getAvailableSlashAgentTypes(): Set<AgentTypeKey> {
+  const runtime = getAgentRuntimeStatusSnapshot();
+  const availableAgents = getAvailableAgentTypes(
+    runtime.statusByType,
+    runtime.isChecking,
+    isAgentTypeEnabled,
+  );
 
-function isAgentSlashEnabled(typeKey: AgentTypeKey): boolean {
-  return isAgentTypeEnabled(typeKey);
+  if (availableAgents.length > 0) {
+    return new Set(availableAgents.map((type) => type.id));
+  }
+
+  // While no successful check exists or a refresh is in flight, keep Pi as
+  // the lightweight default until runtime availability is known.
+  if ((!runtime.hasChecked || runtime.isChecking) && isAgentTypeEnabled('pi')) {
+    return new Set(['pi']);
+  }
+  return new Set();
 }
 
 function getAvailableSlashMenuItems(): SlashMenuItem[] {
+  const availableAgentTypes = getAvailableSlashAgentTypes();
+
   return SLASH_MENU_ITEMS.filter((item) => {
     if (!isAgentThreadSlashMenuItemId(item.id)) return true;
-    if (item.id === 'agent-thread-deepseek-harness') return true;
-    const typeKey = AGENT_THREAD_TYPE_BY_SLASH_ID[item.id];
-    if (!isAgentSlashEnabled(typeKey)) return false;
-    return item.alwaysVisible || isAgentRuntimeAvailable(typeKey);
+    return availableAgentTypes.has(AGENT_THREAD_TYPE_BY_SLASH_ID[item.id]);
   });
 }
 
@@ -123,14 +133,16 @@ function filterItems(query: string, availableItems = getAvailableSlashMenuItems(
   });
 }
 
-function closeMenu() {
+function closeMenu(ownerView?: EditorView) {
+  if (ownerView && activeView !== ownerView) return;
+
   menuOpenId += 1;
   if (positionFrame !== null) {
     window.cancelAnimationFrame(positionFrame);
     positionFrame = null;
   }
   document.removeEventListener('mousedown', handlePointerDownOutside, true);
-  window.removeEventListener('resize', closeMenu);
+  window.removeEventListener('resize', handleWindowResize);
   window.removeEventListener('scroll', handleScrollOutside, true);
   unsubscribeRuntimeStatus?.();
   unsubscribeRuntimeStatus = null;
@@ -169,6 +181,10 @@ function handlePointerDownOutside(event: MouseEvent) {
   closeMenu();
 }
 
+function handleWindowResize() {
+  closeMenu();
+}
+
 // 滚动关闭 ── 与 mention (suggestion-menu.tsx) 同源: 只在滚动发生在
 // menuContainer 外时才关闭。弹窗自身 overflow-y:auto, 用户在弹窗内
 // 滚轮 / 触摸滚动时 scroll 事件会冒泡到 window (capture 阶段也会捕到),
@@ -176,20 +192,21 @@ function handlePointerDownOutside(event: MouseEvent) {
 function handleScrollOutside(event: Event) {
   const target = event.target;
   if (target instanceof Node && menuContainer?.contains(target)) return;
-  const view = activeEditor?.view;
+  const view = activeView;
   if (!view || view.isDestroyed) {
     closeMenu();
     return;
   }
 
   if (positionFrame !== null) return;
+  const openId = menuOpenId;
   positionFrame = window.requestAnimationFrame(() => {
     positionFrame = null;
-    if (!isCurrentMenuView(view)) return;
+    if (!isCurrentMenuView(view, openId)) return;
     try {
       updatePosition(view);
     } catch {
-      closeMenu();
+      closeMenu(view);
     }
   });
 }
@@ -375,6 +392,7 @@ function updatePosition(view: EditorView) {
 
 function renderMenu(view: EditorView, reposition = true) {
   if (!isCurrentMenuView(view)) return;
+  const openId = menuOpenId;
   const root = menuRoot;
   const instance = menuInstance;
   if (!root || !instance) return;
@@ -386,6 +404,7 @@ function renderMenu(view: EditorView, reposition = true) {
       selectedIndex={instance.selectedIndex}
       scrollSelectedItem={instance.scrollSelectedItem}
       onHover={(index) => {
+        if (!isCurrentMenuView(view, openId)) return;
         if (!menuInstance) return;
         if (menuInstance.selectedIndex === index && !menuInstance.scrollSelectedItem) return;
         menuInstance.hasNavigated = true;
@@ -394,10 +413,16 @@ function renderMenu(view: EditorView, reposition = true) {
         renderMenu(view, false);
       }}
       onScroll={() => {
-        if (menuInstance) menuInstance.hasNavigated = true;
+        if (isCurrentMenuView(view, openId) && menuInstance) {
+          menuInstance.hasNavigated = true;
+        }
+      }}
+      onSelect={(item) => {
+        if (isCurrentMenuView(view, openId)) handleSelect(item);
+      }}
+      onAddAgent={() => {
+        if (isCurrentMenuView(view, openId)) void handleAddAgentClick(view, openId);
       }}
-      onSelect={handleSelect}
-      onAddAgent={handleAddAgentClick}
     />
   );
 
@@ -405,8 +430,9 @@ function renderMenu(view: EditorView, reposition = true) {
   if (reposition) updatePosition(view);
 }
 
-async function handleAddAgentClick(): Promise<void> {
-  closeMenu();
+async function handleAddAgentClick(view: EditorView, openId: number): Promise<void> {
+  if (!isCurrentMenuView(view, openId)) return;
+  closeMenu(view);
   try {
     await windows.openPreferences('agents');
   } catch (err) {
@@ -439,17 +465,15 @@ function openMenu(view: EditorView, editor: Editor, triggerFrom: number, deleteF
   menuRoot = createRoot(menuContainer);
 
   document.addEventListener('mousedown', handlePointerDownOutside, true);
-  window.addEventListener('resize', closeMenu);
+  window.addEventListener('resize', handleWindowResize);
   window.addEventListener('scroll', handleScrollOutside, true);
 
   // Runtime detection may finish after the menu opens. Update the idle menu,
   // then freeze its row order once the user begins navigating it.
-  unsubscribeRuntimeStatus = useAgentRuntimeStore.subscribe((state, previous) => {
-    if (state.statusByType === previous.statusByType) return;
+  unsubscribeRuntimeStatus = subscribeAgentRuntimeStatus(() => {
     if (!isCurrentMenuView(view, openId) || activeEditor !== editor) return;
     if (!menuInstance || menuInstance.hasNavigated) return;
-    menuInstance.availableItems = getAvailableSlashMenuItems();
-    refreshMenuFromEditor(view, true);
+    refreshAvailableAgentItems(view);
   });
   unsubscribeUserSettings = subscribeEditorRuntimePreferences(() => {
     if (!isCurrentMenuView(view, openId) || activeEditor !== editor) return;
@@ -458,7 +482,7 @@ function openMenu(view: EditorView, editor: Editor, triggerFrom: number, deleteF
   });
 
   renderMenu(view);
-  void useAgentRuntimeStore.getState().refreshIfStale();
+  void refreshAgentRuntimeStatusIfStale();
 }
 
 function deleteTriggerText(editor: Editor): boolean {
@@ -500,7 +524,6 @@ async function createChildNoteReference(editor: Editor): Promise<void> {
       .insertContent({
         type: 'noteReference',
         attrs: {
-          memoId: null,
           notebookId: notebook.id,
           notebookName: notebook.name,
           title: memoTitleFromFilename(created.relativePath.split('/').pop() ?? created.relativePath),
@@ -598,26 +621,10 @@ function handleSelect(item: SlashMenuItem): void {
 
   if (isAgentThreadSlashMenuItemId(item.id)) {
     const agentThreadType = AGENT_THREAD_TYPE_BY_SLASH_ID[item.id];
-    const runtime = useAgentRuntimeStore.getState();
-    const runtimeState = normalizeAgentRuntimeStatus(
-      runtime.statusByType[agentThreadType],
-      runtime.isChecking,
-    ).state;
-    // DSH is always discoverable in the slash menu. Until availability is
-    // positively confirmed (including while status is still loading), guide
-    // the user to installation/model setup instead of inserting a dead card.
-    if (agentThreadType === 'deepseek-harness' && runtimeState !== 'ready') {
-      closeMenu();
-      void windows.openPreferences('dsh');
-      return;
-    }
-    if (agentThreadType === 'pi' && runtimeState !== 'ready') {
-      closeMenu();
-      void windows.openPreferences('pi');
-      return;
-    }
-    if (runtimeState === 'not-installed' || runtimeState === 'not-ready') {
-      closeMenu();
+    if (!getAvailableSlashAgentTypes().has(agentThreadType)) {
+      const view = activeView;
+      if (view && !view.isDestroyed) refreshAvailableAgentItems(view);
+      else closeMenu();
       return;
     }
     const replaceRange = isBlockStartTrigger(editor)
@@ -682,7 +689,7 @@ function refreshMenuFromEditor(view: EditorView, force = false) {
 
   const query = getQuery(view, state.triggerFrom);
   if (query === null) {
-    closeMenu();
+    closeMenu(view);
     return;
   }
 
@@ -707,6 +714,14 @@ function refreshMenuFromEditor(view: EditorView, force = false) {
   renderMenu(view);
 }
 
+function refreshAvailableAgentItems(view: EditorView) {
+  if (!isCurrentMenuView(view) || !menuInstance) return;
+  menuInstance.availableItems = getAvailableSlashMenuItems();
+  menuInstance.selectedIndex = 0;
+  menuInstance.hasNavigated = false;
+  refreshMenuFromEditor(view, true);
+}
+
 export const SlashMenu = Extension.create({
   name: 'slashMenu',
 
@@ -718,13 +733,21 @@ export const SlashMenu = Extension.create({
         key: slashMenuPluginKey,
 
         view(view) {
+          const handleBlur = (event: FocusEvent) => {
+            const nextTarget = event.relatedTarget;
+            if (nextTarget instanceof Node && menuContainer?.contains(nextTarget)) return;
+            closeMenu(view);
+          };
+          view.dom.addEventListener('blur', handleBlur);
+
           return {
             update(updatedView) {
               if (updatedView !== view || !menuState) return;
               refreshMenuFromEditor(updatedView);
             },
             destroy() {
-              closeMenu();
+              if (!view.isDestroyed) view.dom.removeEventListener('blur', handleBlur);
+              closeMenu(view);
             },
           };
         },
@@ -735,7 +758,7 @@ export const SlashMenu = Extension.create({
 
             const deleteFrom = getSlashTriggerDeleteFrom(view, from);
             if (!editor.isEditable || deleteFrom === null) {
-              closeMenu();
+              closeMenu(view);
               return false;
             }
 
@@ -744,7 +767,7 @@ export const SlashMenu = Extension.create({
           },
 
           handleKeyDown(view, event) {
-            if (!menuState || !menuInstance) return false;
+            if (!isCurrentMenuView(view) || !menuState || !menuInstance) return false;
 
             if (event.key === 'ArrowUp') {
               event.preventDefault();
@@ -770,7 +793,7 @@ export const SlashMenu = Extension.create({
 
             if (event.key === 'Escape') {
               event.preventDefault();
-              closeMenu();
+              closeMenu(view);
               return true;
             }
 
diff --git a/app/flowix-web/features/editor/extensions/stable-caret.test.ts b/app/flowix-web/features/editor/extensions/stable-caret.test.ts
index d99855df6..d4ee075ee 100644
--- a/app/flowix-web/features/editor/extensions/stable-caret.test.ts
+++ b/app/flowix-web/features/editor/extensions/stable-caret.test.ts
@@ -1,5 +1,19 @@
-import { describe, expect, it } from 'vitest';
-import { getTerminalInlineAtomCaretRect } from './stable-caret';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Editor, Node as TiptapNode } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { Schema } from '@tiptap/pm/model';
+import { EditorState, TextSelection } from '@tiptap/pm/state';
+import { ComposerStableCaret, StableCaret, getInlineAtomBoundaryCaretRect, getTerminalInlineAtomCaretRect } from './stable-caret';
+import { createInlineAtomNodeView } from './shared/inline-atom-nodeview';
+
+const chipSchema = new Schema({
+  nodes: {
+    doc: { content: 'paragraph+' },
+    paragraph: { content: 'inline*', group: 'block' },
+    text: { group: 'inline' },
+    chip: { inline: true, atom: true, group: 'inline' },
+  },
+});
 
 function setRect(element: HTMLElement, rect: Partial<DOMRect>): void {
   Object.defineProperty(element, 'getBoundingClientRect', {
@@ -23,7 +37,7 @@ describe('getTerminalInlineAtomCaretRect', () => {
     const card = document.createElement('span');
     const anchor = document.createElement('span');
 
-    card.className = 'editor-note-reference__card';
+    card.className = 'note-reference__card';
     anchor.className = 'terminal-inline-atom-caret-anchor';
     anchor.setAttribute('data-terminal-inline-atom-caret-position', '17');
     Object.defineProperty(card, 'getClientRects', {
@@ -51,7 +65,7 @@ describe('getTerminalInlineAtomCaretRect', () => {
     const card = document.createElement('span');
     const anchor = document.createElement('span');
 
-    card.className = 'editor-note-reference__card';
+    card.className = 'note-reference__card';
     anchor.className = 'terminal-inline-atom-caret-anchor';
     anchor.setAttribute('data-terminal-inline-atom-caret-position', '17');
     setRect(card, { left: 100, right: 240, top: 80, bottom: 106, width: 140, height: 26 });
@@ -70,7 +84,7 @@ describe('getTerminalInlineAtomCaretRect', () => {
     const card = document.createElement('span');
     const anchor = document.createElement('span');
 
-    card.className = 'editor-note-reference__card';
+    card.className = 'note-reference__card';
     anchor.className = 'terminal-inline-atom-caret-anchor';
     anchor.setAttribute('data-terminal-inline-atom-caret-position', '17');
     setRect(card, { left: 100, right: 240, top: 80, bottom: 106, width: 140, height: 26 });
@@ -81,3 +95,416 @@ describe('getTerminalInlineAtomCaretRect', () => {
     expect(getTerminalInlineAtomCaretRect({ dom: editor } as never, 17)).toBeNull();
   });
 });
+
+describe('composer inline atom caret boundaries', () => {
+  it.each(['slash-token', 'skill-token', 'folder-token', 'note-reference'])('%s keeps both caret edges clear of the border after deleting a separator', (kind) => {
+    const wrapper = document.createElement('span');
+    wrapper.className = `agent-composer__inline-atom-wrapper ${kind}`;
+    wrapper.setAttribute('data-inline-atom-caret', 'single-line');
+    const card = document.createElement('span');
+    card.setAttribute('data-inline-atom-card', '');
+    setRect(card, { left: 100, right: 240, top: 80, bottom: 106, width: 140, height: 26 });
+    wrapper.append(card);
+    const doc = chipSchema.node('doc', null, [chipSchema.node('paragraph', null, [
+      chipSchema.text(' '), chipSchema.node('chip'), chipSchema.text(' '),
+    ])]);
+    let state = EditorState.create({ doc, selection: TextSelection.create(doc, 2) });
+    state = state.apply(state.tr.delete(1, 2));
+    const view = { state, nodeDOM: (pos: number) => pos === 1 ? wrapper : null };
+    // Simulate the browser returning the next line / card border for native
+    // caret coordinates: the resolver uses the visible card for both sides.
+    expect(getInlineAtomBoundaryCaretRect(view as never, 1)).toEqual({ left: 97, top: 80, bottom: 106 });
+    state = state.apply(state.tr.delete(2, 3));
+    view.state = state;
+    expect(getInlineAtomBoundaryCaretRect(view as never, 2)).toEqual({ left: 241, top: 80, bottom: 106 });
+  });
+
+  it('leaves ordinary text positions to the native caret', () => {
+    const doc = chipSchema.node('doc', null, [chipSchema.node('paragraph', null, chipSchema.text('text'))]);
+    const view = { state: EditorState.create({ doc }), nodeDOM: () => null };
+    expect(getInlineAtomBoundaryCaretRect(view as never, 3)).toBeNull();
+  });
+
+  it('does not take over other editor atoms or unmounted cards', () => {
+    const doc = chipSchema.node('doc', null, [chipSchema.node('paragraph', null, chipSchema.node('chip'))]);
+    const wrapper = document.createElement('span');
+    const view = { state: EditorState.create({ doc }), nodeDOM: () => wrapper };
+    expect(getInlineAtomBoundaryCaretRect(view as never, 1)).toBeNull();
+    wrapper.className = 'agent-composer__inline-atom-wrapper';
+    wrapper.setAttribute('data-inline-atom-caret', 'single-line');
+    expect(getInlineAtomBoundaryCaretRect(view as never, 2)).toBeNull();
+  });
+
+  it('uses the configured caret width and gap for either direction', () => {
+    const doc = chipSchema.node('doc', null, [chipSchema.node('paragraph', null, chipSchema.node('chip'))]);
+    const wrapper = document.createElement('span');
+    wrapper.className = 'agent-composer__inline-atom-wrapper';
+    wrapper.setAttribute('data-inline-atom-caret', 'single-line');
+    wrapper.style.setProperty('--editor-caret-width', '3px');
+    wrapper.style.setProperty('--inline-atom-caret-gap', '2px');
+    const card = document.createElement('span');
+    card.setAttribute('data-inline-atom-card', '');
+    setRect(card, { left: 100, right: 240, top: 80, bottom: 106, width: 140, height: 26 });
+    wrapper.append(card);
+    document.body.append(wrapper);
+    const view = { state: EditorState.create({ doc }), nodeDOM: () => wrapper };
+    expect(getInlineAtomBoundaryCaretRect(view as never, 1)?.left).toBe(95);
+    expect(getInlineAtomBoundaryCaretRect(view as never, 2)?.left).toBe(242);
+    card.style.direction = 'rtl';
+    expect(getInlineAtomBoundaryCaretRect(view as never, 1)?.left).toBe(242);
+    expect(getInlineAtomBoundaryCaretRect(view as never, 2)?.left).toBe(95);
+    wrapper.remove();
+  });
+});
+
+describe('separate StableCaret instances in nested editors', () => {
+  const editors: Editor[] = [];
+  afterEach(() => {
+    editors.splice(0).reverse().forEach((editor) => editor.destroy());
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it('uses the same caret for text and both card edges, and restores native selection during composition', () => {
+    vi.spyOn(window, 'scrollBy').mockImplementation(() => {});
+    const frames = new Map<number, FrameRequestCallback>();
+    let nextId = 0;
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.set(++nextId, callback);
+      return nextId;
+    });
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => frames.delete(id));
+    const flush = () => {
+      const callbacks = [...frames.values()];
+      frames.clear();
+      callbacks.forEach((callback) => callback(0));
+    };
+    const Chip = TiptapNode.create({
+      name: 'chip', inline: true, atom: true, group: 'inline',
+      renderHTML: () => ['span'],
+      addNodeView: () => () => createInlineAtomNodeView({
+        caretGeometry: 'single-line',
+        wrapperClassName: 'agent-composer__inline-atom-wrapper', label: '计划模式',
+      }),
+    });
+    const mount = document.createElement('div');
+    mount.contentEditable = 'false';
+    mount.className = 'agent-composer__input-row';
+    const NestedComposer = TiptapNode.create({
+      name: 'nestedComposer', group: 'block', atom: true,
+      renderHTML: () => ['div'],
+      addNodeView: () => () => ({ dom: mount, ignoreMutation: () => true }),
+    });
+    const parentMount = document.createElement('div');
+    document.body.append(parentMount);
+    const parent = new Editor({
+      element: parentMount, extensions: [StarterKit, NestedComposer, StableCaret],
+      content: { type: 'doc', content: [
+        { type: 'paragraph', content: [{ type: 'text', text: '正文' }] },
+        { type: 'nestedComposer' },
+      ] },
+      editorProps: { attributes: { style: 'font-size: 16px' } },
+    });
+    editors.push(parent);
+    const parentCaret = document.body.querySelector<HTMLElement>('.stable-editor-caret--document')!;
+    setRect(parent.view.dom, { left: 0, right: 500, top: 0, bottom: 100, width: 500, height: 100 });
+    vi.spyOn(parent.view, 'coordsAtPos').mockReturnValue({ left: 20, right: 20, top: 20, bottom: 46 });
+    // EditorView can report focus in a nested editable as parent focus too.
+    vi.spyOn(parent.view, 'hasFocus').mockReturnValue(true);
+    const editor = new Editor({
+      element: mount,
+      extensions: [StarterKit, Chip, ComposerStableCaret],
+      editorProps: { attributes: { class: 'agent-composer__input-content', style: 'font-size: 16px' } },
+      content: { type: 'doc', content: [{ type: 'paragraph', content: [
+        { type: 'text', text: 'x' }, { type: 'chip' }, { type: 'text', text: 'yz' },
+      ] }] },
+    });
+    editors.push(editor);
+    setRect(editor.view.dom, { left: 0, right: 500, top: 0, bottom: 100, width: 500, height: 100 });
+    const card = editor.view.dom.querySelector<HTMLElement>('[data-inline-atom-card]')!;
+    setRect(card, { left: 100, right: 240, top: 20, bottom: 46, width: 140, height: 26 });
+    vi.spyOn(editor.view, 'coordsAtPos').mockReturnValue({ left: 20, right: 20, top: 20, bottom: 46 });
+    editor.view.dom.focus();
+    editor.commands.setTextSelection(2);
+    flush();
+    const caret = document.body.querySelector<HTMLElement>('.agent-composer__stable-caret')!;
+    expect(caret.hidden).toBe(false);
+    expect(caret.style.left).toBe('97px');
+    expect(caret.style.width).toBe('2px');
+    expect(editor.view.dom.classList.contains('has-composer-stable-caret')).toBe(true);
+    expect(parentCaret.hidden).toBe(true);
+    expect(parent.view.dom.classList.contains('has-document-stable-caret')).toBe(false);
+    editor.commands.setTextSelection(3);
+    flush();
+    expect(caret.style.left).toBe('241px');
+    editor.commands.setTextSelection(4);
+    flush();
+    expect(caret.style.left).toBe('20px');
+    expect(document.body.querySelectorAll('.stable-editor-caret--document:not([hidden])')).toHaveLength(0);
+    expect(document.body.querySelectorAll('.agent-composer__stable-caret:not([hidden])')).toHaveLength(1);
+    editor.commands.setTextSelection({ from: 1, to: 4 });
+    flush();
+    expect(caret.hidden).toBe(true);
+    editor.commands.setTextSelection(2);
+    flush();
+    vi.spyOn(editor.view, 'composing', 'get').mockReturnValue(true);
+    editor.view.dom.dispatchEvent(new Event('compositionstart'));
+    flush();
+    expect(caret.hidden).toBe(true);
+    expect(editor.view.dom.classList.contains('has-composer-stable-caret')).toBe(false);
+    parent.view.dom.focus();
+    parent.commands.setTextSelection(1);
+    flush();
+    expect(parentCaret.hidden).toBe(false);
+    expect(parentCaret.style.width).toBe(caret.style.width);
+    expect(parentCaret.style.height).toBe(caret.style.height);
+    expect(caret.hidden).toBe(true);
+    expect(frames.size).toBe(0);
+    editor.view.dom.focus();
+    flush();
+    expect(frames.size).toBe(0);
+    editor.view.dom.dispatchEvent(new Event('compositionend'));
+    expect(frames.size).toBeGreaterThan(0);
+    editor.destroy();
+    editors.splice(editors.indexOf(editor), 1);
+    expect(frames.size).toBe(0);
+  });
+});
+
+describe('composer local caret layer', () => {
+  let editor: Editor;
+  let layer: HTMLElement;
+  let caret: HTMLElement;
+  let frames: Map<number, FrameRequestCallback>;
+  let resize: (target: Element) => void;
+  let disconnect: ReturnType<typeof vi.fn>;
+
+  function flush() {
+    const callbacks = [...frames.values()];
+    frames.clear();
+    callbacks.forEach((callback) => callback(0));
+  }
+
+  function mount() {
+    frames = new Map();
+    let nextId = 0;
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.set(++nextId, callback);
+      return nextId;
+    });
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => frames.delete(id));
+    const targets = new Set<Element>();
+    disconnect = vi.fn(() => targets.clear());
+    vi.stubGlobal('ResizeObserver', class {
+      constructor(callback: ResizeObserverCallback) {
+        resize = (target) => {
+          if (targets.has(target)) callback([], this as unknown as ResizeObserver);
+        };
+      }
+      observe(target: Element) { targets.add(target); }
+      unobserve(target: Element) { targets.delete(target); }
+      disconnect = disconnect;
+    });
+    const host = document.createElement('div');
+    host.className = 'agent-composer__input-row';
+    host.contentEditable = 'false';
+    const input = document.createElement('div');
+    host.append(input);
+    document.body.append(host);
+    editor = new Editor({
+      element: { mount: input },
+      extensions: [StarterKit, ComposerStableCaret],
+      content: '<p>hello</p>',
+      editorProps: { attributes: {
+        class: 'agent-composer__input-content', style: 'font-size: 16px', tabindex: '0',
+      } },
+    });
+    layer = host.querySelector<HTMLElement>('.agent-composer__caret-layer')!;
+    caret = layer.querySelector<HTMLElement>('.agent-composer__stable-caret')!;
+    setRect(layer, { left: 40, right: 600, top: 30, bottom: 130, width: 560, height: 100 });
+    setRect(input, { left: 60, right: 560, top: 40, bottom: 120, width: 500, height: 80 });
+    const coords = vi.spyOn(editor.view, 'coordsAtPos')
+      .mockReturnValue({ left: 100, right: 100, top: 50, bottom: 76 });
+    input.focus();
+    editor.commands.setTextSelection(3);
+    flush();
+    return { input, coords };
+  }
+
+  afterEach(() => {
+    if (!editor.isDestroyed) editor.destroy();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it('uses local coordinates outside the editable DOM and stays idle when its row translates', async () => {
+    const { input, coords } = mount();
+    expect(layer.parentElement).toBe(input.parentElement);
+    expect(input.contains(caret)).toBe(false);
+    expect(layer.contentEditable).toBe('false');
+    expect(caret.hidden).toBe(false);
+    expect(caret.style.left).toBe('60px');
+    expect(Number.parseFloat(caret.style.top)).toBeCloseTo(23.8);
+    expect(layer.style.clipPath).toBe('inset(10px 40px 10px 20px)');
+    await Promise.resolve();
+    flush();
+    await Promise.resolve();
+    expect(frames.size).toBe(0);
+    coords.mockClear();
+    setRect(layer, { left: 140, right: 700, top: 80, bottom: 180, width: 560, height: 100 });
+    setRect(input, { left: 160, right: 660, top: 90, bottom: 170, width: 500, height: 80 });
+    coords.mockReturnValue({ left: 200, right: 200, top: 100, bottom: 126 });
+    flush();
+    expect(coords).not.toHaveBeenCalled();
+    expect(caret.style.left).toBe('60px');
+    resize(input);
+    flush();
+    expect(caret.style.left).toBe('60px');
+    expect(Number.parseFloat(caret.style.top)).toBeCloseTo(23.8);
+  });
+
+  it('coalesces viewport and internal token/paragraph resize notifications', () => {
+    const { input, coords } = mount();
+    coords.mockClear();
+    coords.mockReturnValue({ left: 120, right: 120, top: 80, bottom: 106 });
+    resize(input);
+    resize(input.querySelector('p')!);
+    resize(input);
+    expect(frames.size).toBe(1);
+    flush();
+    expect(coords).toHaveBeenCalledTimes(1);
+    expect(caret.style.left).toBe('80px');
+    expect(Number.parseFloat(caret.style.top)).toBeCloseTo(53.8);
+    expect(frames.size).toBe(0);
+  });
+
+  it('tracks new paragraphs and stops observing removed content', async () => {
+    const { input, coords } = mount();
+    editor.commands.setContent('<p>new</p><p>paragraph</p>');
+    await Promise.resolve();
+    flush();
+    const addedParagraph = input.querySelector('p:last-child')!;
+    coords.mockClear();
+    resize(addedParagraph);
+    flush();
+    expect(coords).toHaveBeenCalledTimes(1);
+    editor.commands.setContent('<p>remaining</p>');
+    await Promise.resolve();
+    flush();
+    expect(addedParagraph.isConnected).toBe(false);
+    coords.mockClear();
+    resize(addedParagraph);
+    flush();
+    expect(coords).not.toHaveBeenCalled();
+  });
+
+  it('hides outside the input viewport and restores on internal scroll', () => {
+    const { input, coords } = mount();
+    coords.mockReturnValue({ left: 100, right: 100, top: 130, bottom: 156 });
+    input.dispatchEvent(new Event('scroll'));
+    flush();
+    expect(caret.hidden).toBe(true);
+    coords.mockReturnValue({ left: 100, right: 100, top: 110, bottom: 136 });
+    input.dispatchEvent(new Event('scroll'));
+    flush();
+    expect(caret.hidden).toBe(false);
+    expect(layer.style.clipPath).toBe('inset(10px 40px 10px 20px)');
+  });
+
+  it('converts scaled viewport coordinates to CSS coordinates', () => {
+    const { input, coords } = mount();
+    Object.defineProperties(layer, {
+      offsetWidth: { configurable: true, value: 280 },
+      offsetHeight: { configurable: true, value: 50 },
+    });
+    coords.mockReturnValue({ left: 100, right: 100, top: 50, bottom: 102 });
+    resize(input);
+    flush();
+    expect(caret.style.left).toBe('30px');
+    expect(Number.parseFloat(caret.style.top)).toBeCloseTo(13.8);
+    expect(layer.style.clipPath).toBe('inset(5px 20px 5px 10px)');
+  });
+
+  it.each([2, 4])('keeps the full %ipx caret visible when text fills the input width', (width) => {
+    const { input, coords } = mount();
+    input.style.setProperty('--agent-composer-caret-width', `${width}px`);
+    // The layer has no spare space beyond the input, as in production.
+    setRect(layer, { left: 60, right: 560, top: 40, bottom: 120, width: 500, height: 80 });
+    coords.mockReturnValue({ left: 560, right: 560, top: 50, bottom: 76 });
+    resize(input);
+    flush();
+    expect(caret.hidden).toBe(false);
+    expect(caret.style.width).toBe(`${width}px`);
+    expect(Number.parseFloat(caret.style.left)).toBe(500 - width);
+    expect(layer.style.clipPath).toBe('inset(0px 0px 0px 0px)');
+    expect(input.classList.contains('has-composer-stable-caret')).toBe(true);
+  });
+
+  it('keeps the right-edge caret inside a scaled viewport without showing offscreen positions', () => {
+    const { input, coords } = mount();
+    Object.defineProperties(layer, {
+      offsetWidth: { configurable: true, value: 280 },
+      offsetHeight: { configurable: true, value: 50 },
+    });
+    coords.mockReturnValue({ left: 559, right: 559, top: 50, bottom: 76 });
+    resize(input);
+    flush();
+    expect(caret.hidden).toBe(false);
+    expect(Number.parseFloat(caret.style.left)).toBe(258);
+    coords.mockReturnValue({ left: 562, right: 562, top: 50, bottom: 76 });
+    resize(input);
+    flush();
+    expect(caret.hidden).toBe(true);
+  });
+
+  it('updates after internal style changes without observing its own render in a loop', async () => {
+    const { input, coords } = mount();
+    await Promise.resolve();
+    flush();
+    coords.mockClear();
+    coords.mockReturnValue({ left: 125, right: 125, top: 50, bottom: 76 });
+    input.style.fontSize = '20px';
+    await Promise.resolve();
+    expect(frames.size).toBe(1);
+    flush();
+    expect(coords).toHaveBeenCalledTimes(1);
+    expect(caret.style.left).toBe('85px');
+    await Promise.resolve();
+    expect(frames.size).toBe(0);
+  });
+
+  it('restores the native caret during composition and hides for a range selection', () => {
+    const { input } = mount();
+    const composing = vi.spyOn(editor.view, 'composing', 'get').mockReturnValue(true);
+    input.dispatchEvent(new Event('compositionstart'));
+    expect(caret.hidden).toBe(true);
+    expect(input.classList.contains('has-composer-stable-caret')).toBe(false);
+    composing.mockReturnValue(false);
+    input.dispatchEvent(new Event('compositionend'));
+    flush();
+    expect(caret.hidden).toBe(false);
+    editor.commands.setTextSelection({ from: 1, to: 3 });
+    flush();
+    expect(caret.hidden).toBe(true);
+    expect(frames.size).toBe(0);
+  });
+
+  it('releases observers, pending frames and the layer when destroyed', async () => {
+    const { input, coords } = mount();
+    resize(input);
+    expect(frames.size).toBe(1);
+    editor.destroy();
+    expect(disconnect).toHaveBeenCalledTimes(1);
+    expect(layer.isConnected).toBe(false);
+    expect(frames.size).toBe(0);
+    coords.mockClear();
+    input.style.fontSize = '20px';
+    input.dispatchEvent(new Event('load'));
+    resize(input);
+    await Promise.resolve();
+    flush();
+    expect(coords).not.toHaveBeenCalled();
+  });
+});
diff --git a/app/flowix-web/features/editor/extensions/stable-caret.ts b/app/flowix-web/features/editor/extensions/stable-caret.ts
index c1bac5624..3bd494cd9 100644
--- a/app/flowix-web/features/editor/extensions/stable-caret.ts
+++ b/app/flowix-web/features/editor/extensions/stable-caret.ts
@@ -2,8 +2,11 @@ import { Extension } from '@tiptap/core';
 import { Plugin, PluginKey, TextSelection } from '@tiptap/pm/state';
 import type { EditorView } from '@tiptap/pm/view';
 
-const stableCaretKey = new PluginKey('stableCaret');
-const ACTIVE_CLASS = 'has-stable-caret';
+type StableCaretScope = 'document' | 'composer';
+
+function activeClassFor(scope: StableCaretScope): string {
+  return scope === 'composer' ? 'has-composer-stable-caret' : 'has-document-stable-caret';
+}
 
 function elementAtPosition(view: EditorView, position: number): HTMLElement {
   const { node } = view.domAtPos(position, -1);
@@ -14,19 +17,67 @@ function elementAtPosition(view: EditorView, position: number): HTMLElement {
 function caretHeightAt(view: EditorView, position: number): number {
   const element = elementAtPosition(view, position);
   const fontSize = Number.parseFloat(getComputedStyle(element).fontSize);
-  const resolvedFontSize = Number.isFinite(fontSize) ? fontSize : 15;
+  const resolvedFontSize = Number.isFinite(fontSize) ? fontSize : 16;
 
   // Native carets expand to the line box in editable pre-wrap content. Keep
   // the visual caret tied to glyph size instead, independently of line-height.
   return Math.max(12, resolvedFontSize * 1.15);
 }
 
+function caretWidthAt(element: HTMLElement, scope: StableCaretScope = scopeAt(element)): number {
+  const property = scope === 'composer' ? '--agent-composer-caret-width' : '--editor-caret-width';
+  const width = Number.parseFloat(getComputedStyle(element).getPropertyValue(property));
+  return Number.isFinite(width) && width > 0 ? width : 2;
+}
+
+function scopeAt(element: HTMLElement): StableCaretScope {
+  return element.closest('.agent-composer__input-content') ? 'composer' : 'document';
+}
+
 interface CaretRect {
   left: number;
   top: number;
   bottom: number;
 }
 
+/** Resolve both sides from the logical selection and the visible chip, never
+ * from the browser's caret inside a non-editable NodeView. The shared caret
+ * is two pixels wide; its nearest edge stays one pixel away from the border. */
+export function getInlineAtomBoundaryCaretRect(
+  view: Pick<EditorView, 'state' | 'nodeDOM'>,
+  position: number,
+): CaretRect | null {
+  const $pos = view.state.doc.resolve(position);
+  const candidates = [
+    { node: $pos.nodeBefore, pos: position - ($pos.nodeBefore?.nodeSize ?? 0), side: 'after' },
+    { node: $pos.nodeAfter, pos: position, side: 'before' },
+  ] as const;
+  for (const { node, pos, side } of candidates) {
+    if (!node?.isInline || !node.isAtom || node.isText) continue;
+    const wrapper = view.nodeDOM(pos);
+    if (!(wrapper instanceof HTMLElement)
+      || wrapper.getAttribute('data-inline-atom-caret') !== 'single-line') continue;
+    const card = wrapper.querySelector<HTMLElement>('[data-inline-atom-card]');
+    if (!card) continue;
+    const rect = card.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) continue;
+    const scope = scopeAt(wrapper);
+    const gapProperty = scope === 'composer' ? '--agent-composer-caret-gap' : '--inline-atom-caret-gap';
+    const gapValue = Number.parseFloat(getComputedStyle(wrapper).getPropertyValue(gapProperty));
+    const gap = Number.isFinite(gapValue) && gapValue >= 0 ? gapValue : 1;
+    const width = caretWidthAt(wrapper, scope);
+    const rtl = getComputedStyle(card).direction === 'rtl';
+    const leftEdge = (side === 'before') !== rtl;
+    const result = {
+      left: leftEdge ? rect.left - width - gap : rect.right + gap,
+      top: rect.top,
+      bottom: rect.bottom,
+    };
+    if (isUsableCaretRect(result)) return result;
+  }
+  return null;
+}
+
 interface TerminalInlineAtomCaretResolution {
   found: boolean;
   rect: CaretRect | null;
@@ -109,7 +160,7 @@ function resolveTerminalInlineAtomCaret(
   // so its union bounding box is not a valid caret position.
   const atomWrapper = anchor.previousElementSibling as HTMLElement | null;
   const card = atomWrapper?.querySelector<HTMLElement>(
-    '.editor-note-reference__card, .editor-file-attachment__card',
+    '.note-reference__card, .editor-file-attachment__card',
   );
   if (card) {
     const cardRect = terminalInlineCaretRect(card);
@@ -150,12 +201,61 @@ export function getTerminalInlineAtomCaretRect(
 class StableCaretView {
   private readonly caret = document.createElement('span');
   private frame: number | null = null;
+  private readonly layer: HTMLSpanElement | null;
+  private resizeObserver: ResizeObserver | null = null;
+  private mutationObserver: MutationObserver | null = null;
+  private destroyed = false;
+  private readonly observedElements = new Set<Element>();
   private lastGeometry: { left: number; top: number; height: number } | null = null;
 
-  constructor(private readonly view: EditorView) {
-    this.caret.className = 'stable-editor-caret';
+  constructor(
+    private readonly view: EditorView,
+    private readonly scope: StableCaretScope,
+  ) {
+    this.caret.className = scope === 'composer'
+      ? 'agent-composer__stable-caret'
+      : 'stable-editor-caret--document';
     this.caret.setAttribute('aria-hidden', 'true');
-    document.body.appendChild(this.caret);
+    this.caret.hidden = true;
+    const host = scope === 'composer'
+      ? view.dom.closest<HTMLElement>('.agent-composer__input-row')
+      : null;
+    this.layer = host ? document.createElement('span') : null;
+    if (this.layer && host) {
+      this.layer.className = 'agent-composer__caret-layer';
+      this.layer.contentEditable = 'false';
+      this.layer.setAttribute('aria-hidden', 'true');
+      this.layer.appendChild(this.caret);
+      host.appendChild(this.layer);
+    } else {
+      // Document editors retain their existing viewport caret. A composer
+      // mounted without its production input row also uses this fallback.
+      document.body.appendChild(this.caret);
+      this.caret.style.position = 'fixed';
+    }
+    if (scope === 'composer') {
+      this.resizeObserver = new ResizeObserver(this.schedule);
+      this.observeLayout();
+      this.mutationObserver = new MutationObserver((records) => {
+        // Toggling our native-caret suppression class is a render result,
+        // not a layout change. Do not feed it back into another render.
+        const layoutChanged = records.some((record) => {
+          if (record.target !== view.dom || record.attributeName !== 'class') return true;
+          const withoutCaretClass = (value: string | null) => (value ?? '')
+            .split(/\s+/).filter((name) => name && name !== activeClassFor(scope)).sort().join(' ');
+          return withoutCaretClass(record.oldValue) !== withoutCaretClass(view.dom.className);
+        });
+        if (!layoutChanged) return;
+        if (records.some((record) => record.type === 'childList')) this.observeLayout();
+        this.schedule();
+      });
+      this.mutationObserver.observe(view.dom, {
+        subtree: true, childList: true, characterData: true,
+        attributes: true, attributeOldValue: true, attributeFilter: ['class', 'style', 'src'],
+      });
+      document.fonts?.addEventListener('loadingdone', this.schedule);
+      view.dom.addEventListener('load', this.schedule, true);
+    }
 
     view.dom.addEventListener('focus', this.schedule, true);
     view.dom.addEventListener('blur', this.schedule, true);
@@ -172,8 +272,16 @@ class StableCaretView {
   }
 
   destroy(): void {
+    this.destroyed = true;
+    this.resizeObserver?.disconnect();
+    this.observedElements.clear();
+    this.mutationObserver?.disconnect();
+    document.fonts?.removeEventListener('loadingdone', this.schedule);
+    this.view.dom.removeEventListener('load', this.schedule, true);
     if (this.frame !== null) cancelAnimationFrame(this.frame);
-    this.view.dom.classList.remove(ACTIVE_CLASS);
+    if (this.view.dom.classList.contains(activeClassFor(this.scope))) {
+      this.view.dom.classList.remove(activeClassFor(this.scope));
+    }
     this.view.dom.removeEventListener('focus', this.schedule, true);
     this.view.dom.removeEventListener('blur', this.schedule, true);
     this.view.dom.removeEventListener('compositionstart', this.handleCompositionStart);
@@ -182,14 +290,33 @@ class StableCaretView {
     window.removeEventListener('resize', this.schedule);
     window.removeEventListener('scroll', this.schedule, true);
     this.caret.remove();
+    this.layer?.remove();
   }
 
   private readonly handleCompositionStart = (): void => {
     this.hide();
   };
 
+  private observeLayout(): void {
+    // Inline tokens and paragraphs can reflow without changing the scroll
+    // viewport's dimensions (for example when it has reached max-height).
+    const elements = new Set<Element>([this.view.dom, ...this.view.dom.querySelectorAll('*')]);
+    for (const element of this.observedElements) {
+      if (!elements.has(element)) {
+        this.resizeObserver?.unobserve(element);
+        this.observedElements.delete(element);
+      }
+    }
+    for (const element of elements) {
+      if (!this.observedElements.has(element)) {
+        this.resizeObserver?.observe(element);
+        this.observedElements.add(element);
+      }
+    }
+  }
+
   private readonly schedule = (): void => {
-    if (this.frame !== null) cancelAnimationFrame(this.frame);
+    if (this.destroyed || this.frame !== null) return;
     this.frame = requestAnimationFrame(() => {
       this.frame = null;
       this.render();
@@ -201,7 +328,7 @@ class StableCaretView {
     // A thread-card composer is a nested contenteditable inside the document
     // editor. EditorView.hasFocus() treats focus in that subtree as focus in
     // the parent view, but the parent stable caret must not hide or compete
-    // with the composer's native caret.
+    // with the composer's own caret renderer.
     const activeElement = document.activeElement;
     const nestedEditableHasFocus = activeElement instanceof HTMLElement
       && activeElement !== this.view.dom
@@ -220,7 +347,10 @@ class StableCaretView {
     }
 
     try {
-      const terminalAtom = resolveTerminalInlineAtomCaret(this.view, selection.head);
+      const boundaryRect = getInlineAtomBoundaryCaretRect(this.view, selection.head);
+      const terminalAtom = boundaryRect
+        ? { found: false, rect: null }
+        : resolveTerminalInlineAtomCaret(this.view, selection.head);
       // Never fall back to coordsAtPos for a known terminal atom.  If the
       // NodeView is between mount and layout, showing the native caret is safer
       // than drawing a caret from the trailing-break line box.
@@ -228,8 +358,11 @@ class StableCaretView {
         this.hide();
         return;
       }
-      const rect = terminalAtom.rect ?? this.view.coordsAtPos(selection.head);
-      const scrollViewport = this.view.dom.closest('.editor-content');
+      const rect = boundaryRect ?? terminalAtom.rect ?? this.view.coordsAtPos(selection.head);
+      const clipsOwnContent = /^(auto|scroll|hidden|clip)$/.test(getComputedStyle(this.view.dom).overflowY);
+      const scrollViewport = this.layer || clipsOwnContent
+        ? this.view.dom
+        : this.view.dom.closest('.editor-content');
       const viewportRect = scrollViewport instanceof HTMLElement
         ? scrollViewport.getBoundingClientRect()
         : this.view.dom.getBoundingClientRect();
@@ -245,9 +378,40 @@ class StableCaretView {
       }
 
       const height = caretHeightAt(this.view, selection.head);
-      const lineHeight = Math.max(0, rect.bottom - rect.top);
-      const top = rect.top + Math.max(0, (lineHeight - height) / 2);
-      const geometry = { left: rect.left, top, height };
+      const width = caretWidthAt(this.view.dom, this.scope);
+      let left = rect.left;
+      let top = rect.top;
+      let lineHeight = Math.max(0, rect.bottom - rect.top);
+      if (this.layer) {
+        const layerRect = this.layer.getBoundingClientRect();
+        // Convert viewport measurements back to the layer's CSS coordinates,
+        // including any axis-aligned scale applied by an ancestor.
+        const scaleX = this.layer.offsetWidth > 0 && layerRect.width > 0
+          ? layerRect.width / this.layer.offsetWidth : 1;
+        const scaleY = this.layer.offsetHeight > 0 && layerRect.height > 0
+          ? layerRect.height / this.layer.offsetHeight : 1;
+        left = (left - layerRect.left) / scaleX;
+        top = (top - layerRect.top) / scaleY;
+        lineHeight /= scaleY;
+        // Clip the overlay to the editor viewport, including partial lines.
+        // Its sibling placement keeps it outside ProseMirror's editable DOM.
+        const inputRect = this.view.dom.getBoundingClientRect();
+        // A caret extends rightward from the insertion point. At a full line's
+        // right edge, keep its entire width inside the clipped viewport rather
+        // than suppressing the native caret and clipping away its replacement.
+        const inputLeft = (inputRect.left - layerRect.left) / scaleX;
+        const inputRight = (inputRect.right - layerRect.left) / scaleX;
+        left = Math.min(left, Math.max(inputLeft, inputRight - width));
+        const insets = [
+          (inputRect.top - layerRect.top) / scaleY,
+          (layerRect.right - inputRect.right) / scaleX,
+          (layerRect.bottom - inputRect.bottom) / scaleY,
+          (inputRect.left - layerRect.left) / scaleX,
+        ].map((value) => `${Math.max(0, value)}px`);
+        this.layer.style.clipPath = `inset(${insets.join(' ')})`;
+      }
+      top += Math.max(0, (lineHeight - height) / 2);
+      const geometry = { left, top, height };
       const geometryChanged = (
         this.lastGeometry === null
         || Math.abs(this.lastGeometry.left - geometry.left) > 0.1
@@ -255,11 +419,14 @@ class StableCaretView {
         || Math.abs(this.lastGeometry.height - geometry.height) > 0.1
       );
 
-      this.caret.style.left = `${rect.left}px`;
+      this.caret.style.left = `${left}px`;
+      this.caret.style.width = `${width}px`;
       this.caret.style.top = `${top}px`;
       this.caret.style.height = `${height}px`;
       this.caret.hidden = false;
-      this.view.dom.classList.add(ACTIVE_CLASS);
+      if (!this.view.dom.classList.contains(activeClassFor(this.scope))) {
+        this.view.dom.classList.add(activeClassFor(this.scope));
+      }
       this.lastGeometry = geometry;
 
       if (geometryChanged) {
@@ -275,19 +442,27 @@ class StableCaretView {
   private hide(): void {
     this.caret.hidden = true;
     this.lastGeometry = null;
-    this.view.dom.classList.remove(ACTIVE_CLASS);
+    if (this.view.dom.classList.contains(activeClassFor(this.scope))) {
+      this.view.dom.classList.remove(activeClassFor(this.scope));
+    }
   }
 }
 
-export const StableCaret = Extension.create({
-  name: 'stableCaret',
-
-  addProseMirrorPlugins() {
-    return [
-      new Plugin({
-        key: stableCaretKey,
-        view: (view) => new StableCaretView(view),
-      }),
-    ];
-  },
-});
+function createStableCaretExtension(scope: 'document' | 'composer') {
+  const key = new PluginKey(`stableCaret:${scope}`);
+  return Extension.create({
+    name: 'stableCaret',
+
+    addProseMirrorPlugins() {
+      return [
+        new Plugin({
+          key,
+          view: (view) => new StableCaretView(view, scope),
+        }),
+      ];
+    },
+  });
+}
+
+export const StableCaret = createStableCaretExtension('document');
+export const ComposerStableCaret = createStableCaretExtension('composer');
diff --git a/app/flowix-web/features/editor/extensions/tag-mention/tag-mention-dropdown.tsx b/app/flowix-web/features/editor/extensions/tag-mention/tag-mention-dropdown.tsx
index 12e031e8a..6316c7575 100644
--- a/app/flowix-web/features/editor/extensions/tag-mention/tag-mention-dropdown.tsx
+++ b/app/flowix-web/features/editor/extensions/tag-mention/tag-mention-dropdown.tsx
@@ -52,7 +52,7 @@ export function TagMentionDropdown({
         <span>{t('editor.tagMention.header')}</span>
         {loading && (
           <LoaderCircle
-            className="mention-note-header-spinner"
+            className="mention-note-header-spinner flowix-spin"
             aria-hidden="true"
           />
         )}
diff --git a/app/flowix-web/features/editor/extensions/web-card-markdown.ts b/app/flowix-web/features/editor/extensions/web-card-markdown.ts
new file mode 100644
index 000000000..004ae30fe
--- /dev/null
+++ b/app/flowix-web/features/editor/extensions/web-card-markdown.ts
@@ -0,0 +1,56 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+
+export type WebCardAttrs = {
+  url: string;
+  title: string;
+  description: string;
+  image: string;
+};
+
+export const DEFAULT_WEB_CARD_ATTRS: WebCardAttrs = {
+  url: '',
+  title: '',
+  description: '',
+  image: '',
+};
+
+const WEB_CARD_RE = /^::webcard\s*(\{[\s\S]*?\})(?:\n|$)/;
+
+function normalizeText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function normalizeWebCardAttrs(attrs: Partial<WebCardAttrs> | null | undefined): WebCardAttrs {
+  return {
+    url: normalizeText(attrs?.url),
+    title: normalizeText(attrs?.title),
+    description: normalizeText(attrs?.description),
+    image: normalizeText(attrs?.image),
+  };
+}
+
+export const webCardMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'webCard',
+    level: 'block' as const,
+    start(src: string) {
+      return src.indexOf('::webcard');
+    },
+    tokenize(src: string) {
+      const match = WEB_CARD_RE.exec(src);
+      return match ? { type: 'webCard', raw: match[0], text: match[1] } : undefined;
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    try {
+      return { type: 'webCard', attrs: normalizeWebCardAttrs(JSON.parse(token.text ?? '')) };
+    } catch {
+      return { type: 'webCard', attrs: DEFAULT_WEB_CARD_ATTRS };
+    }
+  },
+};
+
+export const WebCardMarkdownExtension = Extension.create({
+  name: 'webCard',
+  ...webCardMarkdownSpec,
+});
diff --git a/app/flowix-web/features/editor/extensions/web-card.ts b/app/flowix-web/features/editor/extensions/web-card.ts
index ddbad833f..358845949 100644
--- a/app/flowix-web/features/editor/extensions/web-card.ts
+++ b/app/flowix-web/features/editor/extensions/web-card.ts
@@ -1,9 +1,14 @@
-import { Node as TiptapNode, mergeAttributes, type JSONContent, type MarkdownToken } from '@tiptap/core';
+import { Node as TiptapNode, mergeAttributes, type JSONContent } from '@tiptap/core';
+import { DEFAULT_WEB_CARD_ATTRS as DEFAULT_ATTRS, normalizeWebCardAttrs as normalizeAttrs, type WebCardAttrs, webCardMarkdownSpec } from './web-card-markdown';
 import { openUrl } from '@platform/tauri/opener';
 import { web, type WebPageMetadata } from '@platform/tauri/client';
 import { translate, type I18nKey } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 
+function normalizeText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
 declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     webCard: {
@@ -12,35 +17,6 @@ declare module '@tiptap/core' {
   }
 }
 
-type WebCardAttrs = {
-  url: string;
-  title: string;
-  description: string;
-  image: string;
-};
-
-const DEFAULT_ATTRS: WebCardAttrs = {
-  url: '',
-  title: '',
-  description: '',
-  image: '',
-};
-
-const WEB_CARD_RE = /^::webcard\s*(\{[\s\S]*?\})(?:\n|$)/;
-
-function normalizeText(value: unknown): string {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function normalizeAttrs(attrs: Partial<WebCardAttrs> | null | undefined): WebCardAttrs {
-  return {
-    url: normalizeText(attrs?.url),
-    title: normalizeText(attrs?.title),
-    description: normalizeText(attrs?.description),
-    image: normalizeText(attrs?.image),
-  };
-}
-
 function normalizeUrlInput(value: string): string {
   const trimmed = value.trim();
   if (!trimmed) return '';
@@ -325,36 +301,7 @@ export const WebCard = TiptapNode.create({
     };
   },
 
-  markdownTokenizer: {
-    name: 'webCard',
-    level: 'block' as const,
-    start(src: string) {
-      return src.indexOf('::webcard');
-    },
-    tokenize(src: string) {
-      const match = WEB_CARD_RE.exec(src);
-      if (!match) return undefined;
-      return {
-        type: 'webCard',
-        raw: match[0],
-        text: match[1],
-      };
-    },
-  },
-
-  parseMarkdown(token: MarkdownToken) {
-    try {
-      return {
-        type: 'webCard',
-        attrs: normalizeAttrs(JSON.parse(token.text ?? '')),
-      };
-    } catch {
-      return {
-        type: 'webCard',
-        attrs: DEFAULT_ATTRS,
-      };
-    }
-  },
+  ...webCardMarkdownSpec,
 
   renderMarkdown(node: JSONContent) {
     const attrs = normalizeAttrs(node.attrs);
diff --git a/app/flowix-web/features/editor/markdown-editor-extensions.ts b/app/flowix-web/features/editor/markdown-editor-extensions.ts
new file mode 100644
index 000000000..9b26c1f97
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-editor-extensions.ts
@@ -0,0 +1,365 @@
+import { Editor, Extension, renderNestedMarkdownContent } from '@tiptap/core';
+import type { JSONContent } from '@tiptap/core';
+import { NodeSelection } from '@tiptap/pm/state';
+import StarterKit from '@tiptap/starter-kit';
+import { TaskList } from '@tiptap/extension-task-list';
+import { ListItem } from '@tiptap/extension-list';
+import { Markdown } from '@tiptap/markdown';
+import Placeholder from '@tiptap/extension-placeholder';
+import { AttachmentLink } from '@features/editor/extensions/attachment-link';
+import { FlowixHighlight } from '@features/editor/extensions/flowix-text-mark';
+import { Tag } from '@features/editor/extensions/tag';
+import MarkdownPaste from '@features/editor/extensions/markdown-paste';
+import ManagedPasteRules from '@features/editor/extensions/paste-rules';
+import { LinkSelectionHighlight, MarkdownLink } from '@features/editor/extensions/markdown-link';
+import { NoteReference } from '@features/editor/extensions/note-link';
+import { NoteMention, WikiNoteMention } from '@features/editor/extensions/note-mention';
+import { TagMention } from '@features/editor/extensions/tag-mention';
+import { CodeBlockShikiBase } from '@features/editor/extensions/codeblock-shiki/codeblock-shiki-base';
+import { MarkdownEscape, LegacyAdjacentStrongMarkdown } from './markdown-parser-core-extensions';
+import { MathBlock } from '@features/editor/extensions/math-block';
+import { WebCard } from '@features/editor/extensions/web-card';
+import { TableReference } from '@features/multidimensional-table/table-reference-node';
+import { MediaLibraryReference } from '@features/media-library/media-library-reference-node';
+import { SearchAndReplace } from '@features/editor/extensions/search-replace';
+import Frontmatter from '@features/editor/extensions/frontmatter';
+import { MenuPinExtension } from '@features/editor/extensions/menu-pin';
+import { BlockDragExtension } from '@features/editor/extensions/block-drag';
+import { ListTypeShortcuts } from '@features/editor/extensions/list-transforms';
+import { SlashMenu } from '@features/editor/extensions/slash-menu';
+import { AgentThreadCard } from '@features/agent/thread-card';
+import { TabAgentRun } from '@features/editor/extensions/tab-agent-run';
+import { TabCharacter } from '@features/editor/extensions/tab-character';
+import { TablePlugin } from '@features/editor/extensions/table/table-plugin';
+import { StableCaret } from '@features/editor/extensions/stable-caret';
+import { MarkdownParagraph, MarkdownTaskItem } from './markdown-parser-common-extensions';
+import type { WorkspaceHostId } from '@features/workspace/public/host-api';
+
+interface NestedListMarkdownContext {
+  parentType?: string;
+  index: number;
+  meta?: { parentAttrs?: { start?: number } };
+}
+
+type MarkdownRenderContext = {
+  parentType?: string | null;
+  index?: number;
+  meta?: {
+    parentAttrs?: {
+      start?: number;
+    };
+  };
+};
+
+type MarkdownNodeLike = {
+  type?: string;
+  text?: string;
+  content?: unknown;
+};
+
+const TABLE_CELL_PARENT_TYPES = new Set(['tableCell', 'tableHeader']);
+const LIST_ITEM_PARENT_TYPES = new Set(['listItem', 'taskItem']);
+const EMPTY_MARKDOWN_PLACEHOLDER_RE = /&(?:amp;)?nbsp;/gi;
+const EMPTY_PARAGRAPH_MARKDOWN = '&nbsp;';
+
+function stripEmptyMarkdownPlaceholders(value: string): string {
+  return value
+    .replace(/\u00a0/g, '')
+    .replace(EMPTY_MARKDOWN_PLACEHOLDER_RE, '')
+    .trim();
+}
+
+export function isEmptyMarkdownPlaceholderOnly(value: string): boolean {
+  return stripEmptyMarkdownPlaceholders(value) === '';
+}
+
+function getParentType(ctx: MarkdownRenderContext): string {
+  return ctx.parentType || '';
+}
+
+function isTableCellContext(ctx: MarkdownRenderContext): boolean {
+  return TABLE_CELL_PARENT_TYPES.has(getParentType(ctx));
+}
+
+function isListItemLeadingParagraphContext(ctx: MarkdownRenderContext): boolean {
+  return LIST_ITEM_PARENT_TYPES.has(getParentType(ctx)) && ctx.index === 0;
+}
+
+function shouldDropEmptyParagraph(ctx: MarkdownRenderContext): boolean {
+  return isTableCellContext(ctx) || isListItemLeadingParagraphContext(ctx);
+}
+
+function renderEmptyParagraphMarkdown(ctx: MarkdownRenderContext): string {
+  return shouldDropEmptyParagraph(ctx) ? '' : EMPTY_PARAGRAPH_MARKDOWN;
+}
+
+function isEmptyParagraphPlaceholderTextNode(node: unknown): boolean {
+  if (!node || typeof node !== 'object') return false;
+
+  const maybeNode = node as MarkdownNodeLike;
+  return maybeNode.type === 'text' &&
+    typeof maybeNode.text === 'string' &&
+    isEmptyMarkdownPlaceholderOnly(maybeNode.text);
+}
+
+function isEmptyParagraphForMarkdown(content: unknown[], ctx: MarkdownRenderContext): boolean {
+  if (content.length === 0) return true;
+  return shouldDropEmptyParagraph(ctx) && content.every(isEmptyParagraphPlaceholderTextNode);
+}
+
+const PreservedParagraph = MarkdownParagraph.extend({
+  renderMarkdown(node, h, ctx: MarkdownRenderContext) {
+    const content = Array.isArray(node.content) ? node.content : [];
+    if (isEmptyParagraphForMarkdown(content, ctx)) {
+      return renderEmptyParagraphMarkdown(ctx);
+    }
+
+    return h.renderChildren(content);
+  },
+});
+
+/** Mark name used only while serializing ambiguous bold boundaries. */
+const HTMLStrongFallback = Extension.create({
+  name: 'htmlStrongFallback',
+  renderMarkdown: (node, h) => `<strong>${h.renderChildren(node)}</strong>`,
+  markdownOptions: {
+    htmlReopen: {
+      open: '<strong>',
+      close: '</strong>',
+    },
+  },
+});
+
+function isUnicodeLetterOrNumber(value: string | undefined): boolean {
+  return !!value && /^[\p{L}\p{N}]$/u.test(value);
+}
+
+function isUnicodePunctuation(value: string | undefined): boolean {
+  // Marked's delimiter rules treat both Unicode punctuation and symbols as
+  // punctuation around a closing `**`. Symbols include currency signs,
+  // copyright marks, and emoji, all of which can trigger the same ambiguity.
+  return !!value && /^[\p{P}\p{S}]$/u.test(value);
+}
+
+function markIsBold(mark: { type?: string }): boolean {
+  return mark.type === 'bold' || mark.type === 'htmlStrongFallback';
+}
+
+/**
+ * CommonMark rejects `**text。**下一句` because the closing delimiter is
+ * followed immediately by a letter. Convert only those bold runs to inline
+ * HTML, which is standard Markdown and remains portable across parsers.
+ */
+function markAmbiguousBoldRunsAsHtml(node: JSONContent): JSONContent {
+  if (!Array.isArray(node.content)) return node;
+
+  const content = node.content.map(child => markAmbiguousBoldRunsAsHtml(child));
+  if (node.type !== 'paragraph' && node.type !== 'heading') {
+    return { ...node, content };
+  }
+
+  const nextContent = content.map(child => ({ ...child, marks: child.marks ? [...child.marks] : child.marks }));
+  let index = 0;
+  while (index < nextContent.length) {
+    const child = nextContent[index];
+    if (child.type !== 'text' || !child.marks?.some(markIsBold)) {
+      index += 1;
+      continue;
+    }
+
+    const runStart = index;
+    while (
+      index + 1 < nextContent.length
+      && nextContent[index + 1].type === 'text'
+      && nextContent[index + 1].marks?.some(markIsBold)
+    ) {
+      index += 1;
+    }
+
+    const lastText = nextContent[index].text ?? '';
+    const followingText = nextContent[index + 1]?.type === 'text'
+      ? nextContent[index + 1].text ?? ''
+      : '';
+    const lastCharacters = Array.from(lastText);
+    const lastCharacter = lastCharacters[lastCharacters.length - 1];
+    const followingCharacter = Array.from(followingText)[0];
+    const isAmbiguous = isUnicodePunctuation(lastCharacter)
+      && isUnicodeLetterOrNumber(followingCharacter);
+
+    if (isAmbiguous) {
+      for (let runIndex = runStart; runIndex <= index; runIndex += 1) {
+        const marks = nextContent[runIndex].marks ?? [];
+        nextContent[runIndex].marks = marks.map(mark => (
+          mark.type === 'bold' ? { ...mark, type: 'htmlStrongFallback' } : mark
+        ));
+      }
+    }
+
+    index += 1;
+  }
+
+  return { ...node, content: nextContent };
+}
+
+export function serializeEditorMarkdown(editor: Editor): string {
+  const json = markAmbiguousBoldRunsAsHtml(editor.getJSON());
+  return editor.markdown?.serialize(json) ?? editor.getMarkdown();
+}
+
+function isEmptyParagraphNode(node: unknown): boolean {
+  if (!node || typeof node !== 'object') return false;
+
+  const maybeNode = node as { type?: string; content?: unknown };
+  if (maybeNode.type !== 'paragraph') return false;
+  if (!Array.isArray(maybeNode.content) || maybeNode.content.length === 0) return true;
+  return maybeNode.content.every(isEmptyParagraphPlaceholderTextNode);
+}
+
+const PreservedListItem = ListItem.extend({
+  renderMarkdown(node, h, ctx) {
+    const content = Array.isArray(node.content) ? node.content : [];
+
+    if (content.length === 1 && isEmptyParagraphNode(content[0])) {
+      if (ctx?.parentType === 'orderedList') {
+        const start = ctx.meta?.parentAttrs?.start || 1;
+        return `${start + ctx.index}. ${EMPTY_PARAGRAPH_MARKDOWN}`;
+      }
+
+      return '-';
+    }
+
+    return renderNestedMarkdownContent(
+      node,
+      h,
+      (context: NestedListMarkdownContext) => {
+        if (context.parentType === 'bulletList') {
+          return '- ';
+        }
+        if (context.parentType === 'orderedList') {
+          const start = context.meta?.parentAttrs?.start || 1;
+          return `${start + context.index}. `;
+        }
+        return '- ';
+      },
+      ctx,
+    );
+  },
+});
+
+const PreservedTaskItem = MarkdownTaskItem.extend({
+  renderMarkdown(node, h) {
+    const checkedChar = node.attrs?.checked ? 'x' : ' ';
+    const prefix = `- [${checkedChar}] `;
+    const content = Array.isArray(node.content) ? node.content : [];
+
+    if (!isEmptyParagraphNode(content[0])) {
+      return renderNestedMarkdownContent(node, h, prefix);
+    }
+
+    const nestedContent = content.slice(1);
+    let output = nestedContent.length === 0 ? `${prefix}${EMPTY_PARAGRAPH_MARKDOWN}` : prefix;
+
+    nestedContent.forEach((child, index) => {
+      const childContent = h.renderChild?.(child, index + 1) ?? h.renderChildren([child]);
+      if (childContent === undefined || childContent === null) return;
+
+      const indentedChild = childContent
+        .split('\n')
+        .map(line => h.indent(line || ''))
+        .join('\n');
+
+      output += child.type === 'paragraph' ? `\n\n${indentedChild}` : `\n${indentedChild}`;
+    });
+
+    return output;
+  },
+});
+
+export interface MarkdownEditorExtensionContext {
+  ownerPath?: string;
+  getOwnerPath: () => string | undefined;
+  getAttachmentNotebookId: () => string | undefined;
+  propertyTargetId?: string;
+  onViewSourceMode?: () => void;
+  transitionId?: number | null;
+  workspaceHost: WorkspaceHostId;
+  getPlaceholder: () => string;
+}
+
+/** Full interactive editor registry; parser specs are shared through pure Markdown modules. */
+export function createMarkdownEditorExtensions({
+  ownerPath,
+  getOwnerPath,
+  getAttachmentNotebookId,
+  propertyTargetId,
+  onViewSourceMode,
+  transitionId,
+  workspaceHost,
+  getPlaceholder,
+}: MarkdownEditorExtensionContext, codeBlockExtension = CodeBlockShikiBase) {
+  return [
+    StarterKit.configure({
+      heading: { levels: [1, 2, 3, 4] },
+      dropcursor: false,
+      gapcursor: false,
+      link: false,
+      codeBlock: false,
+      paragraph: false,
+      listItem: false,
+    }),
+    PreservedParagraph,
+    PreservedListItem,
+    MarkdownEscape,
+    HTMLStrongFallback,
+    LegacyAdjacentStrongMarkdown,
+    AttachmentLink.configure({ ownerPath, getOwnerPath, getNotebookId: getAttachmentNotebookId }),
+    MarkdownLink,
+    LinkSelectionHighlight,
+    codeBlockExtension.configure({ traceId: transitionId }),
+    MathBlock,
+    WebCard,
+    TableReference,
+    MediaLibraryReference,
+    FlowixHighlight.configure({ multicolor: true }),
+    TablePlugin,
+    TaskList,
+    PreservedTaskItem.configure({ nested: true }),
+    Markdown.configure({ markedOptions: { gfm: true, breaks: true } }),
+    Placeholder.configure({
+      showOnlyCurrent: true,
+      // Node selections have no text caret, so suppress the placeholder on
+      // the empty paragraph immediately before a selected media node.
+      placeholder: ({ editor, node, pos }) => {
+        const selection = editor.state.selection;
+        if (
+          selection instanceof NodeSelection &&
+          selection.from === pos + node.nodeSize
+        ) {
+          return '';
+        }
+        return getPlaceholder();
+      },
+    }),
+    Tag,
+    ManagedPasteRules.configure({ ownerPath, getOwnerPath }),
+    MarkdownPaste,
+    Frontmatter.configure({
+      propertyTargetId,
+      onViewSourceMode,
+      getAttachmentNotebookId,
+    }),
+    NoteReference,
+    NoteMention,
+    WikiNoteMention,
+    TagMention,
+    StableCaret,
+    AgentThreadCard.configure({ workspaceHost }),
+    SlashMenu,
+    TabCharacter,
+    TabAgentRun,
+    SearchAndReplace,
+    MenuPinExtension,
+    BlockDragExtension,
+    ListTypeShortcuts,
+  ];
+}
diff --git a/app/flowix-web/features/editor/markdown-editor.tsx b/app/flowix-web/features/editor/markdown-editor.tsx
index d6576c7c5..b43ac3988 100644
--- a/app/flowix-web/features/editor/markdown-editor.tsx
+++ b/app/flowix-web/features/editor/markdown-editor.tsx
@@ -1,19 +1,10 @@
 import { createLogger } from '@/lib/logger';
-import { Editor, Extension, renderNestedMarkdownContent } from '@tiptap/core';
+import { Editor } from '@tiptap/core';
 import type { JSONContent } from '@tiptap/core';
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import { NodeSelection, TextSelection } from '@tiptap/pm/state';
-import StarterKit from '@tiptap/starter-kit';
-import { TaskList } from '@tiptap/extension-task-list';
-import { TaskItem } from '@tiptap/extension-task-item';
-import { ListItem } from '@tiptap/extension-list';
-import { Paragraph } from '@tiptap/extension-paragraph';
-import { Markdown } from '@tiptap/markdown';
-import Placeholder from '@tiptap/extension-placeholder';
 import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, useCallback, type MouseEvent as ReactMouseEvent, type ReactNode } from 'react';
 import { useShortcutScope, pushHandler } from '@features/shortcuts';
-import { AttachmentLink } from '@features/editor/extensions/attachment-link';
-import { FlowixHighlight } from '@features/editor/extensions/flowix-text-mark';
 import { TableBubbleMenu } from '@features/editor/extensions/table/table-bubble-menu';
 import { EditorToolbar } from '@features/editor/components/editor-toolbar';
 import { SelectionBubbleMenu } from '@features/editor/components/selection-bubble-menu';
@@ -22,39 +13,25 @@ import { DragContextMenu } from '@features/editor/components/drag-context-menu';
 import { attachLinkHoverTooltip } from '@features/editor/components/link-hover-tooltip';
 import { navigateToHeadingAnchor } from '@features/editor/components/heading-anchor-navigation';
 import type { EditorLinkContext } from '@features/editor/editor-link-resolution';
-import { Tag } from '@features/editor/extensions/tag';
-import MarkdownPaste from '@features/editor/extensions/markdown-paste';
-import ManagedPasteRules, { pasteClipboardSnapshot } from '@features/editor/extensions/paste-rules';
+import { pasteClipboardSnapshot } from '@features/editor/extensions/paste-rules';
 import type { ClipboardSnapshot } from '@features/editor/extensions/paste-rules/clipboard';
-import { LinkSelectionHighlight, MarkdownLink } from '@features/editor/extensions/markdown-link';
-import { NoteReference } from '@features/editor/extensions/note-link';
-import { NoteMention, WikiNoteMention } from '@features/editor/extensions/note-mention';
-import { TagMention } from '@features/editor/extensions/tag-mention';
-import { CodeBlockShiki } from '@features/editor/extensions/codeblock-shiki/codeblock-shiki';
-import { MathBlock } from '@features/editor/extensions/math-block';
-import { WebCard } from '@features/editor/extensions/web-card';
-import { TableReference } from '@features/multidimensional-table/table-reference-node';
-import { MediaLibraryReference } from '@features/media-library/media-library-reference-node';
-import { SearchAndReplace } from '@features/editor/extensions/search-replace';
 import { SearchReplacePanel } from '@features/editor/components/search-replace-panel';
-import Frontmatter, { selectEditableDocumentContent } from '@features/editor/extensions/frontmatter';
-import { MenuPinExtension } from '@features/editor/extensions/menu-pin';
-import { BlockDragExtension } from '@features/editor/extensions/block-drag';
-import { applyListType, ListTypeShortcuts } from '@features/editor/extensions/list-transforms';
-import { SlashMenu } from '@features/editor/extensions/slash-menu';
-import { AgentThreadCard } from '@features/agent/thread-card';
+import { selectEditableDocumentContent } from '@features/editor/extensions/frontmatter';
+import { applyListType } from '@features/editor/extensions/list-transforms';
 import { SKIP_AGENT_THREAD_CARD_CLEANUP_META } from '@features/agent/thread-card/agent-thread-card-extension';
-import { TabAgentRun } from '@features/editor/extensions/tab-agent-run';
-import { TabCharacter } from '@features/editor/extensions/tab-character';
-import { TablePlugin } from '@features/editor/extensions/table/table-plugin';
-import { StableCaret } from '@features/editor/extensions/stable-caret';
 import { useI18n } from '@/lib/i18n';
 import { markDocumentOpenTrace } from '@/lib/document-open-perf';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
+import type { WorkspaceHostId } from '@features/workspace/public/host-api';
+import { CodeBlockShiki } from '@features/editor/extensions/codeblock-shiki/codeblock-shiki';
+import { normalizeMarkdownTableEmptyCells } from './markdown-normalization';
+import { createMarkdownEditorExtensions, isEmptyMarkdownPlaceholderOnly, serializeEditorMarkdown } from './markdown-editor-extensions';
 
 interface MarkdownEditorProps {
   /** Absolute or notebook-relative path of the note owning editor uploads. */
   ownerPath?: string;
+  /** Workspace surface hosting this editor, passed to surface-aware NodeViews. */
+  workspaceHost?: WorkspaceHostId;
   /** Read the current path when an upload starts, including after a rename. */
   getAttachmentOwnerPath?: () => string | undefined;
   getAttachmentNotebookId?: () => string | undefined;
@@ -62,6 +39,8 @@ interface MarkdownEditorProps {
   onViewSourceMode?: () => void;
   transitionId?: number | null;
   content: string;
+  /** Pre-parsed Markdown JSON supplied by the large-document worker path. */
+  initialParsedContent?: JSONContent;
   editable?: boolean;
   placeholder?: string;
   onChange?: (markdown: string) => void;
@@ -96,6 +75,14 @@ interface MarkdownEditorProps {
 
 const persistenceLog = createLogger('document:editor');
 
+const SERIALIZE_DEBOUNCE_MS = 200;
+const SERIALIZE_IDLE_TIMEOUT_MS = 500;
+
+interface PendingExternalContent {
+  content: string;
+  localEditVersion: number;
+}
+
 export interface MarkdownEditorHandle {
   flushPendingChanges: () => string | null;
   commitPropertyDraft?: () => void;
@@ -109,316 +96,6 @@ export interface MarkdownEditorHandle {
   pasteToBody?: (snapshot: ClipboardSnapshot) => boolean;
 }
 
-interface NestedListMarkdownContext {
-  parentType?: string;
-  index: number;
-  meta?: { parentAttrs?: { start?: number } };
-}
-
-const SERIALIZE_DEBOUNCE_MS = 200;
-const SERIALIZE_IDLE_TIMEOUT_MS = 500;
-
-interface PendingExternalContent {
-  content: string;
-  localEditVersion: number;
-}
-
-type MarkdownRenderContext = {
-  parentType?: string | null;
-  index?: number;
-  meta?: {
-    parentAttrs?: {
-      start?: number;
-    };
-  };
-};
-
-type MarkdownNodeLike = {
-  type?: string;
-  text?: string;
-  content?: unknown;
-};
-
-const TABLE_CELL_PARENT_TYPES = new Set(['tableCell', 'tableHeader']);
-const LIST_ITEM_PARENT_TYPES = new Set(['listItem', 'taskItem']);
-const TABLE_SEPARATOR_CELL_RE = /^:?-{3,}:?$/;
-const EMPTY_MARKDOWN_PLACEHOLDER_RE = /&(?:amp;)?nbsp;/gi;
-const EMPTY_PARAGRAPH_MARKDOWN = '&nbsp;';
-
-function stripEmptyMarkdownPlaceholders(value: string): string {
-  return value
-    .replace(/\u00a0/g, '')
-    .replace(EMPTY_MARKDOWN_PLACEHOLDER_RE, '')
-    .trim();
-}
-
-function isEmptyMarkdownPlaceholderOnly(value: string): boolean {
-  return stripEmptyMarkdownPlaceholders(value) === '';
-}
-
-function getParentType(ctx: MarkdownRenderContext): string {
-  return ctx.parentType || '';
-}
-
-function isTableCellContext(ctx: MarkdownRenderContext): boolean {
-  return TABLE_CELL_PARENT_TYPES.has(getParentType(ctx));
-}
-
-function isListItemLeadingParagraphContext(ctx: MarkdownRenderContext): boolean {
-  return LIST_ITEM_PARENT_TYPES.has(getParentType(ctx)) && ctx.index === 0;
-}
-
-function shouldDropEmptyParagraph(ctx: MarkdownRenderContext): boolean {
-  return isTableCellContext(ctx) || isListItemLeadingParagraphContext(ctx);
-}
-
-function renderEmptyParagraphMarkdown(ctx: MarkdownRenderContext): string {
-  return shouldDropEmptyParagraph(ctx) ? '' : EMPTY_PARAGRAPH_MARKDOWN;
-}
-
-function isEmptyParagraphPlaceholderTextNode(node: unknown): boolean {
-  if (!node || typeof node !== 'object') return false;
-
-  const maybeNode = node as MarkdownNodeLike;
-  return maybeNode.type === 'text' &&
-    typeof maybeNode.text === 'string' &&
-    isEmptyMarkdownPlaceholderOnly(maybeNode.text);
-}
-
-function isEmptyParagraphForMarkdown(content: unknown[], ctx: MarkdownRenderContext): boolean {
-  if (content.length === 0) return true;
-  return shouldDropEmptyParagraph(ctx) && content.every(isEmptyParagraphPlaceholderTextNode);
-}
-
-function isMarkdownTableLine(line: string): boolean {
-  const trimmed = line.trim();
-  return trimmed.startsWith('|') && trimmed.endsWith('|') && trimmed.slice(1, -1).includes('|');
-}
-
-function isTableSeparatorCell(cell: string): boolean {
-  return TABLE_SEPARATOR_CELL_RE.test(cell.trim());
-}
-
-function normalizeMarkdownTableLine(line: string): string {
-  if (!isMarkdownTableLine(line)) return line;
-
-  const cells = line.split('|');
-  const innerCells = cells.slice(1, -1);
-  if (innerCells.every(isTableSeparatorCell)) return line;
-
-  const normalizedCells = innerCells.map((cell) => (
-    isEmptyMarkdownPlaceholderOnly(cell) ? '' : cell
-  ));
-  return `|${normalizedCells.join('|')}|`;
-}
-
-function normalizeMarkdownTableEmptyCells(markdown: string): string {
-  return markdown
-    .split('\n')
-    .map(normalizeMarkdownTableLine)
-    .join('\n');
-}
-
-const PreservedParagraph = Paragraph.extend({
-  renderMarkdown(node, h, ctx: MarkdownRenderContext) {
-    const content = Array.isArray(node.content) ? node.content : [];
-    if (isEmptyParagraphForMarkdown(content, ctx)) {
-      return renderEmptyParagraphMarkdown(ctx);
-    }
-
-    return h.renderChildren(content);
-  },
-});
-
-const MarkdownEscape = Extension.create({
-  name: 'markdownEscape',
-  markdownTokenName: 'escape',
-  parseMarkdown(token, h) {
-    return h.createTextNode(token.raw || token.text || '');
-  },
-});
-
-/** Mark name used only while serializing ambiguous bold boundaries. */
-const HTMLStrongFallback = Extension.create({
-  name: 'htmlStrongFallback',
-  renderMarkdown: (node, h) => `<strong>${h.renderChildren(node)}</strong>`,
-  markdownOptions: {
-    htmlReopen: {
-      open: '<strong>',
-      close: '</strong>',
-    },
-  },
-});
-
-/**
- * Read compatibility for notes written before the serializer fallback was
- * added. New notes never use this form; they serialize the ambiguous run as
- * standard inline HTML instead.
- */
-const LegacyAdjacentStrongMarkdown = Extension.create({
-  name: 'legacyAdjacentStrongMarkdown',
-  markdownTokenizer: {
-    name: 'strong',
-    level: 'inline',
-    start: '**',
-    tokenize(src, _tokens, lexer) {
-      const match = /^\*\*(?!\s)((?:(?!\*\*)[^\n])+?\S)\*\*(?=[\p{L}\p{N}])/u.exec(src);
-      if (!match) return undefined;
-
-      return {
-        type: 'strong',
-        raw: match[0],
-        text: match[1],
-        tokens: lexer.inlineTokens(match[1]),
-      };
-    },
-  },
-});
-
-function isUnicodeLetterOrNumber(value: string | undefined): boolean {
-  return !!value && /^[\p{L}\p{N}]$/u.test(value);
-}
-
-function isUnicodePunctuation(value: string | undefined): boolean {
-  // Marked's delimiter rules treat both Unicode punctuation and symbols as
-  // punctuation around a closing `**`. Symbols include currency signs,
-  // copyright marks, and emoji, all of which can trigger the same ambiguity.
-  return !!value && /^[\p{P}\p{S}]$/u.test(value);
-}
-
-function markIsBold(mark: { type?: string }): boolean {
-  return mark.type === 'bold' || mark.type === 'htmlStrongFallback';
-}
-
-/**
- * CommonMark rejects `**text。**下一句` because the closing delimiter is
- * followed immediately by a letter. Convert only those bold runs to inline
- * HTML, which is standard Markdown and remains portable across parsers.
- */
-function markAmbiguousBoldRunsAsHtml(node: JSONContent): JSONContent {
-  if (!Array.isArray(node.content)) return node;
-
-  const content = node.content.map(child => markAmbiguousBoldRunsAsHtml(child));
-  if (node.type !== 'paragraph' && node.type !== 'heading') {
-    return { ...node, content };
-  }
-
-  const nextContent = content.map(child => ({ ...child, marks: child.marks ? [...child.marks] : child.marks }));
-  let index = 0;
-  while (index < nextContent.length) {
-    const child = nextContent[index];
-    if (child.type !== 'text' || !child.marks?.some(markIsBold)) {
-      index += 1;
-      continue;
-    }
-
-    const runStart = index;
-    while (
-      index + 1 < nextContent.length
-      && nextContent[index + 1].type === 'text'
-      && nextContent[index + 1].marks?.some(markIsBold)
-    ) {
-      index += 1;
-    }
-
-    const lastText = nextContent[index].text ?? '';
-    const followingText = nextContent[index + 1]?.type === 'text'
-      ? nextContent[index + 1].text ?? ''
-      : '';
-    const lastCharacters = Array.from(lastText);
-    const lastCharacter = lastCharacters[lastCharacters.length - 1];
-    const followingCharacter = Array.from(followingText)[0];
-    const isAmbiguous = isUnicodePunctuation(lastCharacter)
-      && isUnicodeLetterOrNumber(followingCharacter);
-
-    if (isAmbiguous) {
-      for (let runIndex = runStart; runIndex <= index; runIndex += 1) {
-        const marks = nextContent[runIndex].marks ?? [];
-        nextContent[runIndex].marks = marks.map(mark => (
-          mark.type === 'bold' ? { ...mark, type: 'htmlStrongFallback' } : mark
-        ));
-      }
-    }
-
-    index += 1;
-  }
-
-  return { ...node, content: nextContent };
-}
-
-function serializeEditorMarkdown(editor: Editor): string {
-  const json = markAmbiguousBoldRunsAsHtml(editor.getJSON());
-  return editor.markdown?.serialize(json) ?? editor.getMarkdown();
-}
-
-function isEmptyParagraphNode(node: unknown): boolean {
-  if (!node || typeof node !== 'object') return false;
-
-  const maybeNode = node as { type?: string; content?: unknown };
-  if (maybeNode.type !== 'paragraph') return false;
-  if (!Array.isArray(maybeNode.content) || maybeNode.content.length === 0) return true;
-  return maybeNode.content.every(isEmptyParagraphPlaceholderTextNode);
-}
-
-const PreservedListItem = ListItem.extend({
-  renderMarkdown(node, h, ctx) {
-    const content = Array.isArray(node.content) ? node.content : [];
-
-    if (content.length === 1 && isEmptyParagraphNode(content[0])) {
-      if (ctx?.parentType === 'orderedList') {
-        const start = ctx.meta?.parentAttrs?.start || 1;
-        return `${start + ctx.index}. ${EMPTY_PARAGRAPH_MARKDOWN}`;
-      }
-
-      return '-';
-    }
-
-    return renderNestedMarkdownContent(
-      node,
-      h,
-      (context: NestedListMarkdownContext) => {
-        if (context.parentType === 'bulletList') {
-          return '- ';
-        }
-        if (context.parentType === 'orderedList') {
-          const start = context.meta?.parentAttrs?.start || 1;
-          return `${start + context.index}. `;
-        }
-        return '- ';
-      },
-      ctx,
-    );
-  },
-});
-
-const PreservedTaskItem = TaskItem.extend({
-  renderMarkdown(node, h) {
-    const checkedChar = node.attrs?.checked ? 'x' : ' ';
-    const prefix = `- [${checkedChar}] `;
-    const content = Array.isArray(node.content) ? node.content : [];
-
-    if (!isEmptyParagraphNode(content[0])) {
-      return renderNestedMarkdownContent(node, h, prefix);
-    }
-
-    const nestedContent = content.slice(1);
-    let output = nestedContent.length === 0 ? `${prefix}${EMPTY_PARAGRAPH_MARKDOWN}` : prefix;
-
-    nestedContent.forEach((child, index) => {
-      const childContent = h.renderChild?.(child, index + 1) ?? h.renderChildren([child]);
-      if (childContent === undefined || childContent === null) return;
-
-      const indentedChild = childContent
-        .split('\n')
-        .map(line => h.indent(line || ''))
-        .join('\n');
-
-      output += child.type === 'paragraph' ? `\n\n${indentedChild}` : `\n${indentedChild}`;
-    });
-
-    return output;
-  },
-});
 
 function normalizeTaskItemPlaceholders(editor: Editor): void {
   const { state, view } = editor;
@@ -560,12 +237,14 @@ function focusEmptyParagraphAfterMedia(
 
 export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorProps>(function MarkdownEditor({
   ownerPath,
+  workspaceHost = 'main-third',
   getAttachmentOwnerPath,
   getAttachmentNotebookId,
   propertyTargetId,
   onViewSourceMode,
   transitionId = null,
   content,
+  initialParsedContent,
   editable = true,
   placeholder,
   onChange,
@@ -604,6 +283,8 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
   const serializeIdleCallbackRef = useRef<number | null>(null);
   const onEditorScrollRef = useRef(onEditorScroll);
   const contentRef = useRef(normalizeMarkdownTableEmptyCells(content));
+  const initialParsedContentRef = useRef(initialParsedContent);
+  initialParsedContentRef.current = initialParsedContent;
   const isApplyingExternalContentRef = useRef(false);
   const isComposingRef = useRef(false);
   const pendingSerializeDirtyRef = useRef(false);
@@ -959,8 +640,10 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
     }
     const mountStartedAt = performance.now();
     const initialContent = normalizeMarkdownTableEmptyCells(content);
+    const parsedContent = initialParsedContentRef.current;
     contentRef.current = initialContent;
 
+    const constructorStartedAt = performance.now();
     const editor = new Editor({
       element: editorMountRef.current,
       // 修复跨多块复制时多余空行：ProseMirror 默认在块间插入 `\n\n`，
@@ -976,7 +659,10 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
           return content.content.textBetween(0, content.content.size, '\n', '\n');
         },
         handleDOMEvents: {
-          mousedown: (view, event) => focusEmptyParagraphAfterMedia(view, event),
+          mousedown: (view, event) => {
+            if (focusEmptyParagraphAfterMedia(view, event)) return true;
+            return false;
+          },
         },
         handleKeyDown: (_view, event) => {
           if (event.isComposing || event.altKey || event.ctrlKey || event.metaKey) {
@@ -1006,82 +692,18 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
           return false;
         },
       },
-      extensions: [
-        StarterKit.configure({
-          heading: {
-            levels: [1, 2, 3, 4],
-          },
-          dropcursor: false,
-          gapcursor: false,
-          link: false,
-          codeBlock: false,
-          paragraph: false,
-          listItem: false,
-        }),
-        PreservedParagraph,
-        PreservedListItem,
-        MarkdownEscape,
-        HTMLStrongFallback,
-        LegacyAdjacentStrongMarkdown,
-        AttachmentLink.configure({ getOwnerPath: getCurrentAttachmentOwnerPath, getNotebookId: getCurrentAttachmentNotebookId }),
-        MarkdownLink,
-        LinkSelectionHighlight,
-        CodeBlockShiki.configure({ traceId: transitionId }),
-        MathBlock,
-        WebCard,
-        TableReference,
-        MediaLibraryReference,
-        FlowixHighlight.configure({ multicolor: true }),
-        TablePlugin,
-        TaskList,
-        PreservedTaskItem.configure({
-          nested: true,
-        }),
-        Markdown.configure({
-          markedOptions: {
-            gfm: true,
-            breaks: true,
-          },
-        }),
-        Placeholder.configure({
-          showOnlyCurrent: true,
-          // `showOnlyCurrent` uses an inclusive range check. A block
-          // NodeSelection starts exactly at the end of the preceding block,
-          // so an empty paragraph immediately before a selected video/image
-          // would otherwise be treated as the current block and show its
-          // placeholder. Node selections have no text caret, so that boundary
-          // paragraph is not an editable current block.
-          placeholder: ({ editor, node, pos }) => {
-            const selection = editor.state.selection;
-            if (
-              selection instanceof NodeSelection &&
-              selection.from === pos + node.nodeSize
-            ) {
-              return '';
-            }
-            return resolvedPlaceholderRef.current;
-          },
-        }),
-        Tag,
-        ManagedPasteRules.configure({ getOwnerPath: getCurrentAttachmentOwnerPath }),
-        MarkdownPaste,
-        Frontmatter.configure({ propertyTargetId, onViewSourceMode, getAttachmentNotebookId }),
-        NoteReference,
-        NoteMention,
-        WikiNoteMention,
-        TagMention,
-        StableCaret,
-        AgentThreadCard,
-        SlashMenu,
-        TabCharacter,
-        TabAgentRun,
-        SearchAndReplace,
-        MenuPinExtension,
-        BlockDragExtension,
-        ListTypeShortcuts,
-      ],
-      content: initialContent,
-      contentType: 'markdown',
+      extensions: createMarkdownEditorExtensions({
+        ownerPath,
+        getOwnerPath: getCurrentAttachmentOwnerPath,
+        getAttachmentNotebookId: getCurrentAttachmentNotebookId,
+        propertyTargetId,
+        onViewSourceMode,
+        transitionId,
+        workspaceHost,
+        getPlaceholder: () => resolvedPlaceholderRef.current,
+      }, CodeBlockShiki),
+      content: parsedContent ?? initialContent,
+      contentType: parsedContent ? 'json' : 'markdown',
       editable,
       autofocus: autoFocus ? 'end' : false,
       onUpdate: ({ transaction }) => {
@@ -1099,15 +721,26 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
         onEditingFinishedRef.current?.();
       },
     });
+    logEditorPerf('MarkdownEditor:constructor', constructorStartedAt, {
+      initialChars: initialContent.length,
+    });
+    const placeholderNormalizationStartedAt = performance.now();
     normalizeTaskItemPlaceholders(editor);
+    logEditorPerf('MarkdownEditor:normalizeTaskPlaceholders', placeholderNormalizationStartedAt);
+    const documentScanStartedAt = performance.now();
     let codeBlockCount = 0;
     editor.state.doc.descendants((node) => {
       if (node.type.name === 'codeBlock') codeBlockCount += 1;
     });
+    logEditorPerf('MarkdownEditor:documentScan', documentScanStartedAt, {
+      docSize: editor.state.doc.content.size,
+      codeBlockCount,
+    });
     logEditorPerf('MarkdownEditor:create', mountStartedAt, {
       initialChars: initialContent.length,
       docSize: editor.state.doc.content.size,
       codeBlockCount,
+      initialContentType: parsedContent ? 'json' : 'markdown',
     });
 
     onBeforeCreate?.(editor);
diff --git a/app/flowix-web/features/editor/markdown-normalization.ts b/app/flowix-web/features/editor/markdown-normalization.ts
new file mode 100644
index 000000000..4e97d9503
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-normalization.ts
@@ -0,0 +1,33 @@
+const TABLE_SEPARATOR_CELL_RE = /^:?-{3,}:?$/;
+const EMPTY_MARKDOWN_PLACEHOLDER_RE = /&(?:amp;)?nbsp;/gi;
+
+function isEmptyMarkdownPlaceholderOnly(value: string): boolean {
+  return value
+    .replace(/\u00a0/g, '')
+    .replace(EMPTY_MARKDOWN_PLACEHOLDER_RE, '')
+    .trim() === '';
+}
+
+function normalizeMarkdownTableLine(line: string): string {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('|') || !trimmed.endsWith('|') || !trimmed.slice(1, -1).includes('|')) {
+    return line;
+  }
+
+  const cells = line.split('|');
+  const innerCells = cells.slice(1, -1);
+  if (innerCells.every((cell) => TABLE_SEPARATOR_CELL_RE.test(cell.trim()))) return line;
+
+  const normalizedCells = innerCells.map((cell) => (
+    isEmptyMarkdownPlaceholderOnly(cell) ? '' : cell
+  ));
+  return `|${normalizedCells.join('|')}|`;
+}
+
+/** Normalize the editor's empty-cell placeholders before parsing Markdown. */
+export function normalizeMarkdownTableEmptyCells(markdown: string): string {
+  return markdown
+    .split('\n')
+    .map(normalizeMarkdownTableLine)
+    .join('\n');
+}
diff --git a/app/flowix-web/features/editor/markdown-parser-common-extensions.ts b/app/flowix-web/features/editor/markdown-parser-common-extensions.ts
new file mode 100644
index 000000000..d407f6621
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-parser-common-extensions.ts
@@ -0,0 +1,68 @@
+import { Paragraph } from '@tiptap/extension-paragraph';
+import { TaskItem } from '@tiptap/extension-task-item';
+import type { JSONContent, MarkdownParseHelpers, MarkdownToken } from '@tiptap/core';
+
+const EMPTY_MARKDOWN_PLACEHOLDER_RE = /^(?:&(?:amp;)?nbsp;|\u00a0)$/i;
+
+function isEmptyMarkdownPlaceholderText(value: string | undefined): boolean {
+  return typeof value === 'string' && EMPTY_MARKDOWN_PLACEHOLDER_RE.test(value.trim());
+}
+
+function isEmptyMarkdownPlaceholder(
+  content: JSONContent[],
+  tokens: MarkdownToken[] = [],
+  fallbackText?: string,
+): boolean {
+  const sourceToken = tokens.length === 1 && tokens[0].type === 'text' ? tokens[0] : undefined;
+  const isReservedSource = sourceToken
+    ? isEmptyMarkdownPlaceholderText(sourceToken.raw) || isEmptyMarkdownPlaceholderText(sourceToken.text)
+    : isEmptyMarkdownPlaceholderText(fallbackText);
+
+  return content.length === 1
+    && content[0].type === 'text'
+    && (!content[0].marks || content[0].marks.length === 0)
+    && typeof content[0].text === 'string'
+    && isReservedSource
+    && isEmptyMarkdownPlaceholderText(content[0].text);
+}
+
+/** Shared Markdown parsing for paragraphs, including the saved empty-line marker. */
+export const MarkdownParagraph = Paragraph.extend({
+  parseMarkdown(token: MarkdownToken, helpers: MarkdownParseHelpers) {
+    const tokens = token.tokens ?? [];
+
+    // Markdown represents a standalone image as a block node in Flowix.
+    if (tokens.length === 1 && tokens[0].type === 'image') {
+      return helpers.parseChildren([tokens[0]]);
+    }
+
+    const content = helpers.parseInline(tokens);
+    return helpers.createNode(
+      'paragraph',
+      undefined,
+      isEmptyMarkdownPlaceholder(content, tokens) ? [] : content,
+    );
+  },
+});
+
+/** TaskItem parses its first paragraph directly, so it must share placeholder handling. */
+export const MarkdownTaskItem = TaskItem.extend({
+  parseMarkdown(token: MarkdownToken, helpers: MarkdownParseHelpers) {
+    const inlineContent = token.tokens?.length
+      ? helpers.parseInline(token.tokens)
+      : token.text
+        ? [helpers.createNode('text', { text: token.text })]
+        : [];
+    const content: JSONContent[] = [helpers.createNode(
+      'paragraph',
+      undefined,
+      isEmptyMarkdownPlaceholder(inlineContent, token.tokens ?? [], token.text) ? [] : inlineContent,
+    )];
+
+    if (token.nestedTokens?.length) {
+      content.push(...helpers.parseChildren(token.nestedTokens));
+    }
+
+    return helpers.createNode('taskItem', { checked: token.checked || false }, content);
+  },
+});
diff --git a/app/flowix-web/features/editor/markdown-parser-core-extensions.ts b/app/flowix-web/features/editor/markdown-parser-core-extensions.ts
new file mode 100644
index 000000000..3a5b1260d
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-parser-core-extensions.ts
@@ -0,0 +1,30 @@
+import { Extension } from '@tiptap/core';
+
+export const MarkdownEscape = Extension.create({
+  name: 'markdownEscape',
+  markdownTokenName: 'escape',
+  parseMarkdown(token, helpers) {
+    return helpers.createTextNode(token.raw || token.text || '');
+  },
+});
+
+/** Read compatibility for legacy adjacent bold runs in saved Markdown. */
+export const LegacyAdjacentStrongMarkdown = Extension.create({
+  name: 'legacyAdjacentStrongMarkdown',
+  markdownTokenizer: {
+    name: 'strong',
+    level: 'inline',
+    start: '**',
+    tokenize(src, _tokens, lexer) {
+      const match = /^\*\*(?!\s)((?:(?!\*\*)[^\n])+?\S)\*\*(?=[\p{L}\p{N}])/u.exec(src);
+      if (!match) return undefined;
+
+      return {
+        type: 'strong',
+        raw: match[0],
+        text: match[1],
+        tokens: lexer.inlineTokens(match[1]),
+      };
+    },
+  },
+});
diff --git a/app/flowix-web/features/editor/markdown-parser-extensions.ts b/app/flowix-web/features/editor/markdown-parser-extensions.ts
new file mode 100644
index 000000000..61752789f
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-parser-extensions.ts
@@ -0,0 +1,57 @@
+import { ListItem } from '@tiptap/extension-list';
+import { TaskList } from '@tiptap/extension-task-list';
+import StarterKit from '@tiptap/starter-kit';
+import { AttachmentMarkdownExtensions } from '@features/editor/extensions/attachment-link/markdown/extensions';
+import { CodeBlockShikiBase } from '@features/editor/extensions/codeblock-shiki/codeblock-shiki-base';
+import { FlowixHighlight } from '@features/editor/extensions/flowix-text-mark';
+import { MarkdownLinkParserExtension } from '@features/editor/extensions/markdown-link-markdown';
+import { NoteReferenceMarkdownExtension } from '@features/editor/extensions/note-link/note-reference-markdown';
+import { FlowixTable } from '@features/editor/extensions/table/flowix-table';
+import { FrontmatterMarkdownExtension } from '@features/editor/extensions/frontmatter-markdown';
+import { TableReferenceMarkdownExtension } from '@features/multidimensional-table/table-reference-markdown';
+import { MediaLibraryReferenceMarkdownExtension } from '@features/media-library/media-library-reference-markdown';
+import { MarkdownEscape, LegacyAdjacentStrongMarkdown } from './markdown-parser-core-extensions';
+import { MathBlockMarkdownExtension } from '@features/editor/extensions/math-block-markdown';
+import { WebCardMarkdownExtension } from '@features/editor/extensions/web-card-markdown';
+import { MarkdownParagraph, MarkdownTaskItem } from './markdown-parser-common-extensions';
+
+/**
+ * MarkdownManager only consumes Markdown tokenizers and parse handlers. Keep
+ * this registry separate from editor menus, NodeViews, and editing plugins.
+ */
+export function createMarkdownParserExtensions() {
+  return [
+    StarterKit.configure({
+      heading: { levels: [1, 2, 3, 4] },
+      dropcursor: false,
+      gapcursor: false,
+      link: false,
+      codeBlock: false,
+      paragraph: false,
+      listItem: false,
+    }),
+    MarkdownParagraph,
+    ListItem,
+    TaskList,
+    MarkdownTaskItem,
+    MarkdownEscape,
+    LegacyAdjacentStrongMarkdown,
+    ...AttachmentMarkdownExtensions,
+    MarkdownLinkParserExtension,
+    CodeBlockShikiBase,
+    MathBlockMarkdownExtension,
+    WebCardMarkdownExtension,
+    FlowixTable,
+    TableReferenceMarkdownExtension,
+    MediaLibraryReferenceMarkdownExtension,
+    FlowixHighlight.configure({ multicolor: true }),
+    FrontmatterMarkdownExtension,
+    NoteReferenceMarkdownExtension,
+  ];
+}
+
+export function hasUnsupportedWorkerMarkdown(markdown: string): boolean {
+  // The legacy Agent Thread Card form is plain text to Marked unless its UI
+  // extension is loaded. Route that legacy form through the browser parser.
+  return /^ {0,3}::agent-thread-card\{/m.test(markdown);
+}
diff --git a/app/flowix-web/features/editor/markdown-parser.ts b/app/flowix-web/features/editor/markdown-parser.ts
new file mode 100644
index 000000000..e325ebbe5
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-parser.ts
@@ -0,0 +1,58 @@
+import type { JSONContent } from '@tiptap/core'
+interface MarkdownParserReply {
+  id: number
+  ok: boolean
+  document?: JSONContent
+  workerMs?: number
+  error?: string
+}
+
+let worker: Worker | null = null
+let nextRequestId = 0
+const pending = new Map<number, {
+  resolve: (reply: MarkdownParserReply) => void
+  reject: (error: Error) => void
+}>()
+
+function failWorker(error: Error): void {
+  for (const request of pending.values()) request.reject(error)
+  pending.clear()
+  worker?.terminate()
+  worker = null
+}
+
+function getWorker(): Worker {
+  if (worker) return worker
+  worker = new Worker(new URL('./markdown-parser.worker.ts', import.meta.url), { type: 'module' })
+  worker.addEventListener('message', (event: MessageEvent<MarkdownParserReply>) => {
+    const request = pending.get(event.data.id)
+    if (!request) return
+    pending.delete(event.data.id)
+    if (event.data.ok && event.data.document) request.resolve(event.data)
+    else request.reject(new Error(event.data.error ?? 'Markdown worker failed'))
+  })
+  worker.addEventListener('error', (event) => {
+    failWorker(new Error(event.message || 'Markdown parser worker crashed'))
+  })
+  worker.addEventListener('messageerror', () => {
+    failWorker(new Error('Markdown parser worker returned an unreadable result'))
+  })
+  return worker
+}
+
+/** Parse Markdown away from the UI thread using the parser-only extension registry. */
+export function parseMarkdownInWorker(
+  markdown: string,
+): Promise<MarkdownParserReply> {
+  if (typeof Worker === 'undefined') return Promise.reject(new Error('Web Workers are unavailable'))
+  const id = ++nextRequestId
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject })
+    try {
+      getWorker().postMessage({ id, markdown })
+    } catch (error) {
+      pending.delete(id)
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
+  })
+}
diff --git a/app/flowix-web/features/editor/markdown-parser.worker.ts b/app/flowix-web/features/editor/markdown-parser.worker.ts
new file mode 100644
index 000000000..112543b33
--- /dev/null
+++ b/app/flowix-web/features/editor/markdown-parser.worker.ts
@@ -0,0 +1,60 @@
+import type { JSONContent } from '@tiptap/core'
+import { MarkdownManager } from '@tiptap/markdown'
+import { createMarkdownParserExtensions, hasUnsupportedWorkerMarkdown } from './markdown-parser-extensions'
+import { normalizeMarkdownTableEmptyCells } from './markdown-normalization'
+
+interface WorkerRequest {
+  id: number
+  markdown: string
+}
+
+let manager: MarkdownManager | null = null
+
+function containsRawHtmlToken(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(containsRawHtmlToken)
+  if (!value || typeof value !== 'object') return false
+  const token = value as Record<string, unknown>
+  if (token.type === 'html') return true
+  return Object.values(token).some(containsRawHtmlToken)
+}
+
+function createManager(): MarkdownManager {
+  const extensions = createMarkdownParserExtensions()
+  return new MarkdownManager({
+    extensions,
+    markedOptions: { gfm: true, breaks: true },
+  })
+}
+
+function getManager(): MarkdownManager {
+  if (!manager) manager = createManager()
+  return manager
+}
+
+self.addEventListener('message', (event: MessageEvent<WorkerRequest>) => {
+  const { id, markdown } = event.data
+  const startedAt = performance.now()
+  try {
+    const activeManager = getManager()
+    const normalizedMarkdown = normalizeMarkdownTableEmptyCells(markdown)
+    if (hasUnsupportedWorkerMarkdown(normalizedMarkdown)) {
+      throw new Error('Markdown uses a legacy Agent Thread Card form; preserve the main-thread parser')
+    }
+    if (containsRawHtmlToken(activeManager.instance.lexer(normalizedMarkdown))) {
+      throw new Error('Markdown contains raw HTML; preserve the main-thread HTML parser')
+    }
+    const document: JSONContent = activeManager.parse(normalizedMarkdown)
+    self.postMessage({
+      id,
+      ok: true,
+      document,
+      workerMs: Math.round((performance.now() - startedAt) * 10) / 10,
+    })
+  } catch (error) {
+    self.postMessage({
+      id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+})
diff --git a/app/flowix-web/features/editor/use-external-file-content-detection.ts b/app/flowix-web/features/editor/use-external-file-content-detection.ts
new file mode 100644
index 000000000..6c72621f6
--- /dev/null
+++ b/app/flowix-web/features/editor/use-external-file-content-detection.ts
@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+
+import { externalDocuments } from '@platform/tauri/client/memos';
+
+type ContentDetection = { filePath: string; scopePath: string | null; isTextContent: boolean };
+
+/** Inspect unknown local files to decide whether the text editor can open them. */
+export function useExternalFileContentDetection(filePath: string | null, scopePath: string | null, shouldResolve: boolean) {
+  const [detection, setDetection] = useState<ContentDetection | null>(null);
+
+  useEffect(() => {
+    if (!filePath || !shouldResolve) return;
+    let cancelled = false;
+    void externalDocuments.detectTextContent(filePath, scopePath).then((isTextContent) => {
+      if (!cancelled) setDetection({ filePath, scopePath, isTextContent });
+    }).catch(() => {
+      if (!cancelled) setDetection({ filePath, scopePath, isTextContent: false });
+    });
+    return () => { cancelled = true; };
+  }, [filePath, scopePath, shouldResolve]);
+
+  const current = detection?.filePath === filePath && detection.scopePath === scopePath ? detection : null;
+  return {
+    isTextContent: current?.isTextContent ?? false,
+    loading: Boolean(filePath && shouldResolve && !current),
+  };
+}
diff --git a/app/flowix-web/features/editor/use-external-file-mime.ts b/app/flowix-web/features/editor/use-external-file-mime.ts
deleted file mode 100644
index b36ae0d31..000000000
--- a/app/flowix-web/features/editor/use-external-file-mime.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { useEffect, useState } from 'react';
-
-import { externalDocuments } from '@platform/tauri/client/memos';
-
-type MimeResolution = { filePath: string; mimeType: string | null };
-
-/** Resolve an extension-derived MIME type only for otherwise unsupported paths. */
-export function useExternalFileMime(filePath: string | null, shouldResolve: boolean) {
-  const [resolution, setResolution] = useState<MimeResolution | null>(null);
-
-  useEffect(() => {
-    if (!filePath || !shouldResolve) return;
-    let cancelled = false;
-    void externalDocuments.mimeType(filePath).then((mimeType) => {
-      if (!cancelled) setResolution({ filePath, mimeType });
-    }).catch(() => {
-      if (!cancelled) setResolution({ filePath, mimeType: null });
-    });
-    return () => { cancelled = true; };
-  }, [filePath, shouldResolve]);
-
-  const current = resolution?.filePath === filePath ? resolution : null;
-  return {
-    mimeType: current?.mimeType ?? null,
-    loading: Boolean(filePath && shouldResolve && !current),
-  };
-}
diff --git a/app/flowix-web/features/media-library/media-import.test.ts b/app/flowix-web/features/media-library/media-import.test.ts
index 8fa90d41e..84bd435c9 100644
--- a/app/flowix-web/features/media-library/media-import.test.ts
+++ b/app/flowix-web/features/media-library/media-import.test.ts
@@ -109,7 +109,7 @@ describe('media import persistence and rollback', () => {
     const input = options();
     input.persist.mockResolvedValue(false);
     input.readLatest.mockResolvedValue({ ...input.document, dataset: { ...input.document.dataset,
-      records: { include: [createMediaLibraryRecord('attachments/photo.jpg')], exclude: [] },
+      records: { include: [createMediaLibraryRecord('notebook-1', 'attachments/photo.jpg')], exclude: [] },
     } });
     expect((await importMediaLibraryFiles(input)).completed).toEqual(['/notes/attachments/photo.jpg']);
     expect(mediaResources.delete).not.toHaveBeenCalled();
diff --git a/app/flowix-web/features/media-library/media-import.ts b/app/flowix-web/features/media-library/media-import.ts
index 8d7a81cdf..a832526fd 100644
--- a/app/flowix-web/features/media-library/media-import.ts
+++ b/app/flowix-web/features/media-library/media-import.ts
@@ -43,7 +43,7 @@ export async function importMediaLibraryFiles({ paths, notebookId, notebookPath,
       const previous = imported.get(key);
       imported.set(key, {
         path, created: saved.created || previous?.created === true,
-        record: previous?.record ?? createMediaLibraryRecord(path.slice(rootPrefix.length), resource?.resource.id),
+        record: previous?.record ?? createMediaLibraryRecord(notebookId, path.slice(rootPrefix.length), resource?.resource.id),
       });
     } catch (error) {
       console.error('[MediaLibrary] Failed to import media:', error);
diff --git a/app/flowix-web/features/media-library/media-library-filter-panel.tsx b/app/flowix-web/features/media-library/media-library-filter-panel.tsx
index d117500cd..709d88c3e 100644
--- a/app/flowix-web/features/media-library/media-library-filter-panel.tsx
+++ b/app/flowix-web/features/media-library/media-library-filter-panel.tsx
@@ -70,17 +70,17 @@ export function MediaLibraryFilterPanel({
     onFolderPickerOpenChange(false);
   };
   const folderPathLabel = fixedFolderPath !== undefined
-    ? '固定'
-    : (path || pathIsAll) ? (pathIsAll ? t('mediaLibrary.anyFolder') : path) : undefined;
+    ? fixedFolderPath || '笔记本根目录'
+    : (path || pathIsAll) ? (pathIsAll ? t('mediaLibrary.anyFolder') : path) : '空';
   const canClearFolderPath = fixedFolderPath === undefined && Boolean(path || pathIsAll);
 
   const locationMenu = <Popover open={folderPickerOpen} onOpenChange={onFolderPickerOpenChange}>
-        <div data-media-library-location-menu className={`flex min-w-0 items-center gap-0.5 rounded-lg transition-colors ${busy || !notebookAvailable || fixedFolderPath !== undefined ? '' : 'hover:bg-[var(--hover-bg)]'}`}>
+        <div data-media-library-location-menu className={`flex min-w-0 items-center gap-0.5 rounded-lg transition-colors ${busy || !notebookAvailable || fixedFolderPath !== undefined ? '' : folderPickerOpen ? 'bg-[var(--hover-bg)]' : 'hover:bg-[var(--hover-bg)]'}`}>
           <PopoverTrigger asChild>
             <button type="button" disabled={busy || !notebookAvailable || fixedFolderPath !== undefined} className="flex h-8 min-w-0 flex-1 items-center justify-between gap-2 rounded-lg pl-1.5 text-left text-sm disabled:opacity-50">
               <span className="min-w-0 truncate">浏览和保存</span>
               <span className="flex min-w-0 flex-1 items-center justify-end gap-1 text-[var(--muted-foreground)]">
-                {folderPathLabel && <span title={folderPathLabel} className="max-w-[150px] truncate text-right text-xs">{folderPathLabel}</span>}
+                {folderPathLabel && <span title={fixedFolderPath !== undefined ? `固定：${folderPathLabel}` : folderPathLabel} className="max-w-[150px] truncate text-right text-sm">{folderPathLabel}</span>}
               </span>
             </button>
           </PopoverTrigger>
@@ -158,8 +158,8 @@ export function MediaLibraryFilterPanel({
   return <>
     <div className="space-y-1">
       {showLocationMenu && locationMenu}
-      <p className="agent-thread-card__codex-settings-title px-2">{t('multidimensionalTable.autoCollect.file')}</p>
-      <label className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2 px-2">
+      <p className="agent-thread-card__codex-settings-title">{t('multidimensionalTable.autoCollect.file')}</p>
+      <label className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2">
         <span className="px-0.5 text-sm text-[var(--foreground)]">{t('mediaLibrary.filterFileName')}</span>
         <input
           autoFocus={autoFocus}
@@ -171,7 +171,7 @@ export function MediaLibraryFilterPanel({
           className="h-8 w-full rounded-lg border border-[var(--border)] bg-transparent px-3 text-sm outline-none focus:border-[var(--brand)] disabled:opacity-50"
         />
       </label>
-      <div className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2 px-2">
+      <div className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2">
         <span className="px-0.5 text-sm text-[var(--foreground)]">{t('mediaLibrary.filterType')}</span>
         <Select value={fileType} disabled={busy} onValueChange={(value) => onFileTypeChange(value as 'any' | MediaLibraryKind)}>
           <SelectTrigger className="h-8 min-w-0 w-full rounded-lg bg-transparent px-2 text-left text-sm">
@@ -185,9 +185,9 @@ export function MediaLibraryFilterPanel({
         </Select>
       </div>
     </div>
-    <div className="mx-2 mt-2 flex gap-2">
-      <button type="button" disabled={busy} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-transparent text-sm text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:opacity-50" onClick={onReset}>{t('mediaLibrary.reset')}</button>
-      <button type="button" disabled={busy} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] text-sm text-[var(--foreground)] hover:bg-[var(--muted)] disabled:opacity-50" onClick={onApply}>{applying ? t('mediaLibrary.saveProgress') : t('mediaLibrary.apply')}</button>
+    <div className="mt-2 flex gap-2">
+      <button type="button" disabled={busy} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--muted)] px-2 text-sm text-[var(--foreground)] hover:bg-[var(--hover-bg)] disabled:cursor-not-allowed disabled:opacity-50" onClick={onReset}>{t('mediaLibrary.reset')}</button>
+      <button type="button" disabled={busy} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--muted)] px-2 text-sm text-[var(--foreground)] hover:bg-[var(--hover-bg)] disabled:cursor-not-allowed disabled:opacity-50" onClick={onApply}>{applying ? t('mediaLibrary.saveProgress') : t('mediaLibrary.apply')}</button>
     </div>
   </>;
 }
diff --git a/app/flowix-web/features/media-library/media-library-photo-wall.tsx b/app/flowix-web/features/media-library/media-library-photo-wall.tsx
index b9859108a..a1976425e 100644
--- a/app/flowix-web/features/media-library/media-library-photo-wall.tsx
+++ b/app/flowix-web/features/media-library/media-library-photo-wall.tsx
@@ -4,7 +4,7 @@ import type { MediaResource } from '@platform/tauri/client';
 import { joinNotebookMemoPath } from '@/lib/path';
 import { toast } from '@/lib/toast';
 import { Button } from '@shared/ui/button';
-import { openMediaTarget } from '@features/workspace/use-cases/workspace-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { requestMediaPreview } from '@features/surface/media-preview-tasks';
 import imagePlaceholder from '@/assets/placeholder-image-card.jpg';
 import videoPlaceholder from '@/assets/placeholder-video-card.jpg';
@@ -38,7 +38,11 @@ function PhotoWallItem({ item, height, notebookId, notebookPath }: { item: Prepa
   const filePath = joinNotebookMemoPath(notebookPath, resource.relativePath);
   const title = resource.relativePath.split(/[\\/]/).pop() ?? resource.relativePath;
   return <button type="button" title={title} aria-label={`打开：${title}`} onClick={() => {
-    if (filePath) void openMediaTarget({ filePath, notebookId, notebookPath, resourceKind: resource.kind }).catch((reason) => toast.error(reason instanceof Error ? reason.message : '无法打开媒体资源'));
+    if (filePath) void openWorkspaceSurface({
+      host: 'browser-column',
+      target: { kind: 'media', filePath, notebookId, notebookPath, resourceKind: resource.kind },
+      options: { browserDisposition: 'focus-existing' },
+    }).catch((reason) => toast.error(reason instanceof Error ? reason.message : '无法打开媒体资源'));
   }} style={{ flexGrow: ratio, flexBasis: 0, height }} className="group relative min-w-0 overflow-hidden rounded-md bg-[var(--card)] text-left">
     <img src={!failed && preview ? preview : resource.kind === 'video' ? videoPlaceholder : imagePlaceholder} alt="" onError={() => setFailed(true)} className="absolute inset-0 h-full w-full object-contain" />
     {resource.kind === 'video' && <span className="pointer-events-none absolute inset-0 flex items-center justify-center"><span className="flex h-9 w-9 items-center justify-center rounded-full bg-black/40 text-white"><Play className="ml-0.5 h-4 w-4 fill-current" /></span></span>}
diff --git a/app/flowix-web/features/media-library/media-library-reference-markdown.ts b/app/flowix-web/features/media-library/media-library-reference-markdown.ts
new file mode 100644
index 000000000..f262343d9
--- /dev/null
+++ b/app/flowix-web/features/media-library/media-library-reference-markdown.ts
@@ -0,0 +1,64 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+
+export const MEDIA_LIBRARY_REFERENCE_MARKER = 'flowix:media-library-reference';
+export const MEDIA_LIBRARY_REFERENCE_VERSION = 1;
+
+export interface MediaLibraryReferenceAttrs {
+  notebookId: string | null;
+  relativePath: string | null;
+  collectionId: string | null;
+}
+
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+export function normalizeMediaLibraryReferenceAttrs(value: unknown): MediaLibraryReferenceAttrs {
+  const attrs = value && typeof value === 'object' ? value as Record<string, unknown> : {};
+  return {
+    notebookId: normalizeText(attrs.notebookId),
+    relativePath: normalizeText(attrs.relativePath)?.replace(/\\/g, '/').replace(/^\/+/, '') ?? null,
+    collectionId: normalizeText(attrs.collectionId),
+  };
+}
+
+export function mediaLibraryReferenceMetadataFromSource(source: string): Record<string, unknown> | null {
+  const match = new RegExp(`^<!--[ \\t]*${MEDIA_LIBRARY_REFERENCE_MARKER}[ \\t]+(\\{[^\\r\\n]*\\})[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
+  if (!match) return null;
+  try {
+    const parsed: unknown = JSON.parse(match[1]);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export const mediaLibraryReferenceMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'mediaLibraryReference',
+    level: 'block' as const,
+    start(source: string) {
+      return new RegExp(`^<!--[ \\t]*${MEDIA_LIBRARY_REFERENCE_MARKER}[ \\t]+\\{`, 'm').exec(source)?.index ?? -1;
+    },
+    tokenize(source: string) {
+      const metadata = mediaLibraryReferenceMetadataFromSource(source);
+      if (!metadata) return undefined;
+      const match = new RegExp(`^<!--[ \\t]*${MEDIA_LIBRARY_REFERENCE_MARKER}[ \\t]+\\{[^\\r\\n]*\\}[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
+      return match ? { type: 'mediaLibraryReference', raw: match[0], metadata } : undefined;
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    const metadata = token.metadata && typeof token.metadata === 'object'
+      ? token.metadata as Record<string, unknown>
+      : mediaLibraryReferenceMetadataFromSource(token.raw ?? '') ?? {};
+    const attrs = metadata.version === MEDIA_LIBRARY_REFERENCE_VERSION ? metadata : {};
+    return { type: 'mediaLibraryReference', attrs: normalizeMediaLibraryReferenceAttrs(attrs) };
+  },
+};
+
+export const MediaLibraryReferenceMarkdownExtension = Extension.create({
+  name: 'mediaLibraryReference',
+  ...mediaLibraryReferenceMarkdownSpec,
+});
diff --git a/app/flowix-web/features/media-library/media-library-reference-node.tsx b/app/flowix-web/features/media-library/media-library-reference-node.tsx
index fe2c0ab14..2c0944a41 100644
--- a/app/flowix-web/features/media-library/media-library-reference-node.tsx
+++ b/app/flowix-web/features/media-library/media-library-reference-node.tsx
@@ -1,6 +1,7 @@
+import { resolveDatasetFilterForLocation } from '@features/collection/dataset-filter-location';
 import { reuseCollectionValue } from '@features/collection/content-equality';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { Node as TiptapNode, mergeAttributes, type Editor, type MarkdownToken } from '@tiptap/core';
+import { Node as TiptapNode, mergeAttributes, type Editor } from '@tiptap/core';
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { EditorView, NodeView as ProseMirrorNodeView } from '@tiptap/pm/view';
 import { createRoot, type Root } from 'react-dom/client';
@@ -9,10 +10,11 @@ import { ArrowUpRightIcon, ArrowsLeftRightIcon, FunnelIcon, PlusIcon } from '@ph
 import { dialogs, externalDocuments, files, collections, mediaResources, type MediaResource, type NotebookFolderOption } from '@platform/tauri/client';
 import { resourceKindFromPath } from '@features/editor/public/code-file';
 import { useNoteStore } from '@features/memo/store/note-store';
-import { openCollectionTarget } from '@features/workspace/use-cases/workspace-navigation';
-import { canonicalDirectoryPath, canonicalPath, joinNotebookMemoPath } from '@/lib/path';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { canonicalDirectoryPath, canonicalPath, joinNotebookMemoPath, notebookRelativeDirectoryPath } from '@/lib/path';
 import { displayTitleFromFilename } from '@/lib/utils';
 import { useCollectionReference } from '@features/collection/use-collection-reference';
+import { collectionDisplayName } from '@features/collection/model';
 import { toast } from '@/lib/toast';
 import { Button } from '@shared/ui/button';
 import { useTitleEditCaret } from '@shared/hooks/use-title-edit-caret';
@@ -25,40 +27,17 @@ import { renameMediaLibrary } from './rename-media-library';
 import { MediaLibraryPhotoWall } from './media-library-photo-wall';
 import { PHOTO_WALL_CANDIDATE_LIMIT } from './photo-wall-layout';
 import { MediaLibraryFilterPanel } from './media-library-filter-panel';
-import { mediaCollectionFilterFromCondition, mediaLibraryFileCondition, matchesMediaCollectionFilter, normalizeMediaLibraryFileCondition, parseMediaLibrary, serializeMediaLibrary, type MediaLibraryDocument, type MediaLibraryKind, type MediaLibraryRecord } from './model';
+import {
+  MEDIA_LIBRARY_REFERENCE_MARKER,
+  MEDIA_LIBRARY_REFERENCE_VERSION,
+  mediaLibraryReferenceMarkdownSpec,
+  normalizeMediaLibraryReferenceAttrs,
+  type MediaLibraryReferenceAttrs,
+} from './media-library-reference-markdown';
+import { canEditMediaLibraryFilter, hasMediaDatasetFilter, mediaCollectionFilterForSave, mediaLibraryFileCondition, matchesMediaCollectionFilter, normalizeMediaLibraryFileCondition, parseMediaLibrary, serializeMediaLibrary, type MediaLibraryDocument, type MediaLibraryKind, type MediaLibraryRecord } from './model';
 
-const MEDIA_LIBRARY_REFERENCE_MARKER = 'flowix:media-library-reference';
-const MEDIA_LIBRARY_REFERENCE_VERSION = 1;
 const EMBED_RESOURCE_LIMIT = PHOTO_WALL_CANDIDATE_LIMIT;
 
-export interface MediaLibraryReferenceAttrs {
-  notebookId: string | null;
-  relativePath: string | null;
-  collectionId: string | null;
-}
-
-function normalizeText(value: unknown): string | null {
-  return typeof value === 'string' && value.trim() ? value.trim() : null;
-}
-
-function normalizeAttrs(value: unknown): MediaLibraryReferenceAttrs {
-  const attrs = value && typeof value === 'object' ? value as Record<string, unknown> : {};
-  return {
-    notebookId: normalizeText(attrs.notebookId),
-    relativePath: normalizeText(attrs.relativePath)?.replace(/\\/g, '/').replace(/^\/+/, '') ?? null,
-    collectionId: normalizeText(attrs.collectionId),
-  };
-}
-
-function metadataFromSource(source: string): Record<string, unknown> | null {
-  const match = new RegExp(`^<!--[ \\t]*${MEDIA_LIBRARY_REFERENCE_MARKER}[ \\t]+(\\{[^\\r\\n]*\\})[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
-  if (!match) return null;
-  try {
-    const parsed: unknown = JSON.parse(match[1]);
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
-  } catch { return null; }
-}
-
 class MediaLibraryReferenceNodeView implements ProseMirrorNodeView {
   readonly dom: HTMLElement;
   private readonly root: Root;
@@ -82,7 +61,7 @@ class MediaLibraryReferenceNodeView implements ProseMirrorNodeView {
     if (this.destroyed) return;
     this.root.render(<MediaLibraryReferenceSurface
       key={`${this.node.attrs.notebookId}:${this.node.attrs.collectionId}`}
-      attrs={normalizeAttrs(this.node.attrs)}
+      attrs={normalizeMediaLibraryReferenceAttrs(this.node.attrs)}
       editable={this.editor.isEditable}
       onRemove={() => this.removeNode()}
       onReplace={(anchor) => this.replaceNode(anchor)}
@@ -176,6 +155,9 @@ function MediaLibraryDatasetPopover({ document, notebook, filePath, editable, bu
   onOpenChange: (open: boolean) => void;
 }) {
   const condition = document ? mediaLibraryFileCondition(document) : {};
+  const fixedFolderPath = document?.collection.placement === 'folder' && notebook && filePath
+    ? notebookRelativeDirectoryPath(notebook.path, canonicalDirectoryPath(filePath.replace(/[\\/][^\\/]*$/, ''))) ?? ''
+    : undefined;
   const [filterMenuOpen, setFilterMenuOpen] = useState(false);
   const [folderPickerOpen, setFolderPickerOpen] = useState(false);
   const [fileName, setFileName] = useState('');
@@ -212,6 +194,10 @@ function MediaLibraryDatasetPopover({ document, notebook, filePath, editable, bu
 
   const save = useCallback(async (pathOverride?: string | null, closeOnSave = true): Promise<boolean> => {
     if (!document || !notebook || !filePath || saving) return false;
+    if (!canEditMediaLibraryFilter(document)) {
+      toast.error('当前媒体库包含编辑器不支持的筛选，未保存以保留原条件');
+      return false;
+    }
     const nextCondition = normalizeMediaLibraryFileCondition({
       file_name_contains: fileName.trim(),
       file_type: fileType === 'any' ? undefined : fileType,
@@ -224,12 +210,11 @@ function MediaLibraryDatasetPopover({ document, notebook, filePath, editable, bu
       for (let attempt = 0; attempt < 2; attempt += 1) {
         const current = parseMediaLibrary(source);
         if (current.collection.id !== document.collection.id) throw new Error('媒体库身份已变化，请重新插入引用');
+        if (!canEditMediaLibraryFilter(current)) throw new Error('当前媒体库包含编辑器不支持的筛选，已取消保存');
         const next: MediaLibraryDocument = {
           ...current,
           collection: { ...current.collection, revision: current.collection.revision + 1, updated_at: new Date().toISOString() },
-          dataset: { ...current.dataset, filter: Object.keys(nextCondition).length
-            ? mediaCollectionFilterFromCondition(nextCondition)
-            : null },
+          dataset: { ...current.dataset, filter: mediaCollectionFilterForSave(current, nextCondition, filePath, notebook.path) },
           views: { ...current.views, items: current.views.items.map((view) => view.id === current.views.default_id
             ? { ...view, filter: { all: [], any: [] } } : view) },
         };
@@ -268,67 +253,72 @@ function MediaLibraryDatasetPopover({ document, notebook, filePath, editable, bu
       </Button>
     </PopoverTrigger>
     <PopoverContent align="end" side="bottom" sideOffset={0} fitViewport style={{ zIndex: 150 }} ignorePopoverOutside={filterMenuOpen || folderPickerOpen} className="w-[220px] max-w-[calc(100vw-16px)] rounded-xl p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-      <MediaLibraryFilterPanel
-        fileName={fileName}
-        fileType={fileType}
-        path={path}
-        pathIsAll={pathIsAll}
-        folderPickerOpen={folderPickerOpen}
-        folderOptions={folderOptions}
-        folderOptionsLoading={loadingFolders}
-        notebookAvailable={Boolean(notebook)}
-        busy={saving || busy}
-        locationOnly
-        showLocationMenu={false}
-        onFileNameChange={setFileName}
-        onFileTypeChange={setFileType}
-        onPathChange={setPath}
-        onPathSelected={async (selectedPath) => {
-          const saved = await save(selectedPath, false);
-          if (saved) {
-            setPath(selectedPath ?? '');
-            setPathIsAll(selectedPath === null);
-          }
-          return saved;
-        }}
-        onFolderPickerOpenChange={setFolderPickerOpen}
-        onReset={() => {}}
-        onApply={() => {}}
-      />
-      <Popover open={filterMenuOpen} onOpenChange={setFilterMenuOpen}>
-        <PopoverTrigger asChild>
-          <button type="button" className="flex h-8 w-full items-center justify-between rounded-lg px-1.5 text-left text-sm hover:bg-[var(--hover-bg)] hover:text-[var(--foreground)] data-[state=open]:bg-[var(--hover-bg)] data-[state=open]:text-[var(--foreground)]">
-            <span>数据条件</span>
-            <span className="flex items-center gap-1 text-xs text-[var(--muted-foreground)]">
-              {fileName.trim() || fileType !== 'any' ? '已设置' : '未设置'}
-              <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
-            </span>
-          </button>
-        </PopoverTrigger>
-        <PopoverContent side="right" align="start" sideOffset={0} fitViewport style={{ zIndex: 160 }} ignorePopoverOutside={folderPickerOpen} className="max-h-[min(70vh,420px)] w-[320px] max-w-[calc(100vw-16px)] overflow-y-auto rounded-xl px-1 py-2 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-          <div className="space-y-1">
-            <MediaLibraryFilterPanel
-              fileName={fileName}
-              fileType={fileType}
-              path={path}
-              pathIsAll={pathIsAll}
-              folderPickerOpen={folderPickerOpen}
-              folderOptions={folderOptions}
-              folderOptionsLoading={loadingFolders}
-              notebookAvailable={Boolean(notebook)}
-              busy={saving || busy}
-              applying={saving}
-              showLocationMenu={false}
-              onFileNameChange={setFileName}
-              onFileTypeChange={setFileType}
-              onPathChange={setPath}
-              onFolderPickerOpenChange={setFolderPickerOpen}
-              onReset={() => { setFileName(''); setFileType('any'); }}
-              onApply={() => { void save(); }}
-            />
+      <div className="space-y-0.5">
+        <MediaLibraryFilterPanel
+          fileName={fileName}
+          fileType={fileType}
+          path={path}
+          pathIsAll={pathIsAll}
+          folderPickerOpen={folderPickerOpen}
+          folderOptions={folderOptions}
+          folderOptionsLoading={loadingFolders}
+          notebookAvailable={Boolean(notebook)}
+          busy={saving || busy}
+          fixedFolderPath={fixedFolderPath}
+          locationOnly
+          showLocationMenu={false}
+          onFileNameChange={setFileName}
+          onFileTypeChange={setFileType}
+          onPathChange={setPath}
+          onPathSelected={async (selectedPath) => {
+            const saved = await save(selectedPath, false);
+            if (saved) {
+              setPath(selectedPath ?? '');
+              setPathIsAll(selectedPath === null);
+            }
+            return saved;
+          }}
+          onFolderPickerOpenChange={setFolderPickerOpen}
+          onReset={() => {}}
+          onApply={() => {}}
+        />
+        <Popover open={filterMenuOpen} onOpenChange={setFilterMenuOpen}>
+          <div className={`rounded-lg transition-colors ${filterMenuOpen ? 'bg-[var(--hover-bg)]' : 'hover:bg-[var(--hover-bg)]'}`}>
+            <PopoverTrigger asChild>
+              <button type="button" className="flex h-8 w-full items-center justify-between rounded-lg px-1.5 text-left text-sm hover:text-[var(--foreground)] data-[state=open]:text-[var(--foreground)]">
+                <span>数据条件</span>
+                <span className="flex items-center gap-1 text-sm text-[var(--muted-foreground)]">
+                  {fileName.trim() || fileType !== 'any' ? '已设置' : '未设置'}
+                  <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
+                </span>
+              </button>
+            </PopoverTrigger>
           </div>
-        </PopoverContent>
-      </Popover>
+          <PopoverContent side="left" align="start" sideOffset={0} fitViewport style={{ zIndex: 160 }} ignorePopoverOutside={folderPickerOpen} className="max-h-[min(70vh,420px)] w-[320px] max-w-[calc(100vw-16px)] overflow-y-auto rounded-xl p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+            <div className="space-y-1">
+              <MediaLibraryFilterPanel
+                fileName={fileName}
+                fileType={fileType}
+                path={path}
+                pathIsAll={pathIsAll}
+                folderPickerOpen={folderPickerOpen}
+                folderOptions={folderOptions}
+                folderOptionsLoading={loadingFolders}
+                notebookAvailable={Boolean(notebook)}
+                busy={saving || busy}
+                applying={saving}
+                showLocationMenu={false}
+                onFileNameChange={setFileName}
+                onFileTypeChange={setFileType}
+                onPathChange={setPath}
+                onFolderPickerOpenChange={setFolderPickerOpen}
+                onReset={() => { setFileName(''); setFileType('any'); }}
+                onApply={() => { void save(); }}
+              />
+            </div>
+          </PopoverContent>
+        </Popover>
+      </div>
     </PopoverContent>
   </Popover>;
 }
@@ -386,7 +376,8 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
   const condition = document ? mediaLibraryFileCondition(document) : undefined;
   const [datasetMenuOpen, setDatasetMenuOpen] = useState(false);
   const fileType = condition?.file_type;
-  const hasDatasetCondition = Boolean(condition?.path_scope === 'all' || condition?.path_contains);
+  const hasDatasetCondition = Boolean(document && (hasMediaDatasetFilter(document.dataset.filter) || document.dataset.source.scope !== 'notebook')
+    || condition?.path_scope === 'all' || condition?.path_contains || condition?.file_name_contains || condition?.file_type);
   const hasDocument = document !== null;
   const mediaLibraryRecords = document?.dataset.records.include ?? [];
   useEffect(() => {
@@ -401,8 +392,27 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
     let active = true;
     setLoadingResources(true);
     void (async () => {
+      const inCollectionSource = (relativePath: string) => {
+        const source = document?.dataset.source;
+        if (!source || source.scope === 'notebook') return true;
+        let base = source.path ?? '';
+        if (source.scope === 'containing_folder') {
+          if (!filePath) return false;
+          const folder = canonicalDirectoryPath(filePath.replace(/[\\/][^\\/]*$/, ''));
+          const relativeFolder = notebookRelativeDirectoryPath(notebook.path, folder);
+          if (relativeFolder === null) return false;
+          base = relativeFolder;
+        }
+        const path = relativePath.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+        const prefix = base.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+        if (!prefix) return source.depth === 'descendants' || !path.includes('/');
+        if (!path.startsWith(`${prefix}/`)) return false;
+        return source.depth === 'descendants' || !path.slice(prefix.length + 1).includes('/');
+      };
+      const effectiveFilter = document ? resolveDatasetFilterForLocation(document.dataset.filter, document.collection.placement, filePath, notebook.path) : null;
+      const scopedRecords = mediaLibraryRecords.filter((record) => inCollectionSource(record.relative_path));
       const [linked, matches, hasMoreMatches] = await Promise.all([
-        loadLinkedMediaResources(mediaLibraryRecords, notebook.path, EMBED_RESOURCE_LIMIT, () => active),
+        loadLinkedMediaResources(scopedRecords, notebook.path, EMBED_RESOURCE_LIMIT, () => active),
         (async () => {
           if (!hasDatasetCondition) return [[], false] as const;
           const kinds: MediaLibraryKind[] = fileType ? [fileType] : ['image', 'video'];
@@ -411,7 +421,8 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
           let hasMoreResources = true;
           while (active && matching.length <= EMBED_RESOURCE_LIMIT && hasMoreResources) {
             const page = await mediaResources.listPage(notebook.path, kinds, cursor, 120);
-            matching.push(...page.resources.filter((resource) => matchesMediaCollectionFilter(resource.relativePath, resource.kind, document?.dataset.filter)));
+            matching.push(...page.resources.filter((resource) => inCollectionSource(resource.relativePath)
+              && matchesMediaCollectionFilter(resource.relativePath, resource.kind, effectiveFilter)));
             hasMoreResources = page.hasMore;
             cursor = page.nextCursor;
             if (hasMoreResources && !cursor) break;
@@ -433,14 +444,17 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
       if (active) setError(reason instanceof Error ? reason.message : String(reason));
     }).finally(() => { if (active) setLoadingResources(false); });
     return () => { active = false; };
-  }, [document?.dataset.filter, fileType, hasDatasetCondition, hasDocument, mediaLibraryRecords, nearViewport, notebook?.id, notebook?.path, resourceRevision]);
+  }, [document?.dataset.filter, document?.dataset.source.depth, document?.dataset.source.path, document?.dataset.source.scope, filePath, fileType, hasDatasetCondition, hasDocument, mediaLibraryRecords, nearViewport, notebook?.id, notebook?.path, resourceRevision]);
 
   const openLibrary = useCallback(async () => {
     if (!filePath || !notebook || !attrs.collectionId) return;
     try {
       const resolved = await resolveMediaLibraryPath(notebook, attrs.collectionId!);
       if (resolved.relativePath !== attrs.relativePath) onRelativePathChange(resolved.relativePath);
-      await openCollectionTarget({ notebookId: notebook.id, collectionId: attrs.collectionId });
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'collection-reference', notebookId: notebook.id, collectionId: attrs.collectionId, collectionKind: 'media_library' },
+      });
     } catch (reason) {
       toast.error(reason instanceof Error ? reason.message : '无法打开媒体库');
     }
@@ -517,12 +531,14 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
   }, [addingMedia, attrs.collectionId, attrs.relativePath, document, editable, editingName, filePath, notebook, onRelativePathChange, renaming, t]);
   const beginRename = useCallback(() => {
     if (!editable || renaming || addingMedia || !filePath) return;
-    setNameDraft(document?.collection.name ?? reference.item?.name ?? '');
+    setNameDraft(document ? collectionDisplayName(filePath, document.collection.placement) : reference.item?.name ?? '');
     setEditingName(true);
-  }, [addingMedia, document?.collection.name, reference.item?.name, editable, filePath, renaming]);
+  }, [addingMedia, document?.collection.placement, reference.item?.name, editable, filePath, renaming]);
   const renameLibrary = useCallback(async (rawTitle: string) => {
     const title = rawTitle.trim();
-    const currentTitle = document?.collection.name ?? reference.item?.name ?? '';
+    const currentTitle = document && filePath
+      ? collectionDisplayName(filePath, document.collection.placement)
+      : reference.item?.name ?? '';
     if (renaming) return;
     if (!editable || !notebook || !filePath || !title || title === currentTitle) {
       setEditingName(false);
@@ -556,8 +572,10 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
       setRenaming(false);
       setEditingName(false);
     }
-  }, [attrs.collectionId, document?.collection.name, reference.item?.name, editable, filePath, notebook, onRelativePathChange, renaming]);
-  const displayName = document?.collection.name ?? reference.item?.name ?? attrs.relativePath?.split('/').pop()?.replace(/\.lib\.ya?ml$/i, '') ?? '媒体库';
+  }, [attrs.collectionId, document?.collection.placement, reference.item?.name, editable, filePath, notebook, onRelativePathChange, renaming]);
+  const displayName = document && filePath
+    ? collectionDisplayName(filePath, document.collection.placement)
+    : reference.item?.name ?? attrs.relativePath?.split('/').pop()?.replace(/\.(?:index\.ya?ml|(?:table|lib)\.ya?ml)$/i, '') ?? '媒体库';
 
   return <section ref={sectionRef} className="my-3 overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--editor-block-bg)] px-3 pb-3 pt-1.5" contentEditable={false} aria-label={`媒体库：${displayName}`}>
     <div className="mb-1.5 flex items-center gap-2">
@@ -573,7 +591,7 @@ function MediaLibraryReferenceSurface({ attrs, editable, onRemove, onReplace, on
           onKeyDown={(event) => {
             if (event.key === 'Enter' && (event.nativeEvent.isComposing || event.keyCode === 229)) return;
             if (event.key === 'Enter') { event.preventDefault(); event.currentTarget.blur(); }
-            else if (event.key === 'Escape') { event.preventDefault(); setEditingName(false); setNameDraft(document?.collection.name ?? reference.item?.name ?? ''); }
+            else if (event.key === 'Escape') { event.preventDefault(); setEditingName(false); setNameDraft(document && filePath ? collectionDisplayName(filePath, document.collection.placement) : reference.item?.name ?? ''); }
           }}
           className="box-border h-[22px] min-w-[2em] max-w-full flex-[0_1_auto] rounded px-0.5 py-1 [field-sizing:content] border-0 bg-[var(--muted)] text-sm font-medium leading-none text-[var(--foreground)] outline-none"
         /> : <button
@@ -652,7 +670,7 @@ export const MediaLibraryReference = TiptapNode.create({
   parseHTML() { return [{ tag: 'div[data-flowix-media-library-reference]' }]; },
 
   renderHTML({ node, HTMLAttributes }) {
-    const attrs = normalizeAttrs(node.attrs);
+    const attrs = normalizeMediaLibraryReferenceAttrs(node.attrs);
     return ['div', mergeAttributes(HTMLAttributes, {
       'data-flowix-media-library-reference': 'true',
       'data-notebook-id': attrs.notebookId ?? '',
@@ -667,28 +685,9 @@ export const MediaLibraryReference = TiptapNode.create({
     return ({ node, editor, view, getPos }) => new MediaLibraryReferenceNodeView(node, editor, view, typeof getPos === 'function' ? getPos : () => undefined);
   },
 
-  markdownTokenizer: {
-    name: 'mediaLibraryReference',
-    level: 'block' as const,
-    start(source: string) {
-      const match = new RegExp(`^<!--[ \\t]*${MEDIA_LIBRARY_REFERENCE_MARKER}[ \\t]+\\{`, 'm').exec(source);
-      return match?.index ?? -1;
-    },
-    tokenize(source: string) {
-      const metadata = metadataFromSource(source);
-      if (!metadata) return undefined;
-      const match = new RegExp(`^<!--[ \\t]*${MEDIA_LIBRARY_REFERENCE_MARKER}[ \\t]+\\{[^\\r\\n]*\\}[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
-      return match ? { type: 'mediaLibraryReference', raw: match[0], metadata } : undefined;
-    },
-  },
-
-  parseMarkdown(token: MarkdownToken) {
-    const metadata = token.metadata && typeof token.metadata === 'object' ? token.metadata as Record<string, unknown> : metadataFromSource(token.raw ?? '') ?? {};
-    const attrs = metadata.version === MEDIA_LIBRARY_REFERENCE_VERSION ? metadata : {};
-    return { type: 'mediaLibraryReference', attrs: normalizeAttrs(attrs) };
-  },
+  ...mediaLibraryReferenceMarkdownSpec,
 
   renderMarkdown(node) {
-    return `<!-- ${MEDIA_LIBRARY_REFERENCE_MARKER} ${JSON.stringify({ version: MEDIA_LIBRARY_REFERENCE_VERSION, ...normalizeAttrs(node.attrs) })} -->\n`;
+    return `<!-- ${MEDIA_LIBRARY_REFERENCE_MARKER} ${JSON.stringify({ version: MEDIA_LIBRARY_REFERENCE_VERSION, ...normalizeMediaLibraryReferenceAttrs(node.attrs) })} -->\n`;
   },
 });
diff --git a/app/flowix-web/features/media-library/media-library-view.test.tsx b/app/flowix-web/features/media-library/media-library-view.test.tsx
new file mode 100644
index 000000000..0f2551f59
--- /dev/null
+++ b/app/flowix-web/features/media-library/media-library-view.test.tsx
@@ -0,0 +1,147 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SurfaceLifecycle } from '@features/workspace/public/surface-api';
+import { createMediaLibrary, serializeMediaLibrary } from './model';
+import { MediaLibraryView } from './media-library-view';
+
+type ListActions = {
+  onMediaLibraryFilterChange: (filter: { file_type: 'image' }) => Promise<boolean>;
+  onAddMedia: () => Promise<boolean>;
+};
+const mocks = vi.hoisted(() => ({
+  read: vi.fn(), write: vi.fn(), importFiles: vi.fn(),
+  actions: null as ListActions | null,
+  subscriptions: [] as Array<{ event: string; handler: (event: never) => void }>,
+}));
+vi.mock('@platform/tauri/client', () => ({
+  files: { read: mocks.read }, externalDocuments: { read: mocks.read, write: mocks.write },
+  dialogs: { selectFiles: async () => ['/source/image.png'] }, mediaResources: {}, notebookAssets: {},
+}));
+vi.mock('@platform/tauri/event-bus', () => ({
+  subscribe: (event: string, handler: (event: never) => void) => {
+    const subscription = { event, handler };
+    mocks.subscriptions.push(subscription);
+    return () => { mocks.subscriptions = mocks.subscriptions.filter((item) => item !== subscription); };
+  },
+}));
+vi.mock('@features/collection/public/folder-api', () => ({ FolderCollectionSwitchConfirmDialog: () => null }));
+vi.mock('@features/memo/store/note-store', () => ({
+  useNoteStore: (select: (state: { notebooks: unknown[] }) => unknown) => select({ notebooks: [] }),
+}));
+vi.mock('@features/surface/document-list-view', () => ({
+  DocumentListView: (props: ListActions) => { mocks.actions = props; return null; },
+}));
+vi.mock('./rename-media-library', () => ({ renameMediaLibrary: vi.fn() }));
+vi.mock('./media-import', () => ({ importMediaLibraryFiles: mocks.importFiles }));
+vi.mock('@/lib/i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }));
+vi.mock('@/lib/toast', () => ({ toast: { error: vi.fn(), success: vi.fn() } }));
+
+let root: Root;
+let container: HTMLDivElement;
+let lifecycle: SurfaceLifecycle | null;
+const register = (value: SurfaceLifecycle | null) => { lifecycle = value; };
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+beforeEach(async () => {
+  vi.clearAllMocks();
+  mocks.subscriptions = [];
+  mocks.read.mockResolvedValue(serializeMediaLibrary(createMediaLibrary('Library')));
+  mocks.write.mockImplementation(async ({ content }: { content: string }) => ({ status: 'saved', content }));
+  lifecycle = null;
+  container = document.createElement('div');
+  root = createRoot(container);
+  await act(async () => root.render(<MediaLibraryView filePath="/book/library.lib.yaml"
+    notebookPath="/book" notebookId="book" onSurfaceLifecycleReady={register} />));
+});
+afterEach(async () => { await act(async () => root.unmount()); });
+
+describe('media library surface save barrier', () => {
+  it('shows refresh failures, keeps the view mounted, and retries the latest path', async () => {
+    const failure = new Error('temporary disk read failure');
+    mocks.read.mockRejectedValueOnce(failure);
+    const collectionChanged = mocks.subscriptions.find((item) => item.event === 'collection-changed');
+    expect(collectionChanged).toBeDefined();
+
+    await act(async () => {
+      collectionChanged!.handler({ notebookId: 'book', relativePath: 'library.lib.yaml' } as never);
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(container.textContent).toContain('mediaLibrary.refreshFailed');
+    expect(container.textContent).toContain('temporary disk read failure');
+    expect(container.querySelector('[role="alert"]')).not.toBeNull();
+
+    const retry = [...container.querySelectorAll('button')].find((button) => button.textContent === 'error.retry');
+    expect(retry).toBeDefined();
+    await act(async () => {
+      retry!.click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(container.textContent).not.toContain('mediaLibrary.refreshFailed');
+    expect(mocks.read).toHaveBeenCalledWith('/book/library.lib.yaml', '/book');
+  });
+
+  it('ignores a refresh failure after the surface changes to another session', async () => {
+    let rejectRead!: (reason: Error) => void;
+    mocks.read.mockReturnValueOnce(new Promise<string>((_resolve, reject) => { rejectRead = reject; }));
+    const collectionChanged = mocks.subscriptions.find((item) => item.event === 'collection-changed');
+    expect(collectionChanged).toBeDefined();
+    act(() => {
+      collectionChanged!.handler({ notebookId: 'book', relativePath: 'library.lib.yaml' } as never);
+    });
+
+    await act(async () => root.render(<MediaLibraryView filePath="/book/next.lib.yaml"
+      notebookPath="/book" notebookId="book" onSurfaceLifecycleReady={register} />));
+    await act(async () => {
+      rejectRead(new Error('stale session failure'));
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(container.textContent).not.toContain('stale session failure');
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it('returns false for a failed config write and permits a successful retry', async () => {
+    const write = deferred<{ status: 'error'; message: string }>();
+    mocks.write.mockReturnValueOnce(write.promise);
+    let operation!: Promise<boolean>;
+    act(() => { operation = mocks.actions!.onMediaLibraryFilterChange({ file_type: 'image' }); });
+    const flush = lifecycle!.flush!();
+    let finished = false;
+    void flush.then(() => { finished = true; });
+    await Promise.resolve();
+    expect(finished).toBe(false);
+    await act(async () => { write.resolve({ status: 'error', message: 'write failed' }); await operation; });
+    await expect(flush).resolves.toBe(false);
+    await expect(lifecycle!.flush!()).resolves.toBe(false);
+    await act(async () => { expect(await mocks.actions!.onMediaLibraryFilterChange({ file_type: 'image' })).toBe(true); });
+    await expect(lifecycle!.flush!()).resolves.toBe(true);
+  });
+
+  it('waits for the import transaction after its nested configuration write completes', async () => {
+    const tail = deferred<void>();
+    mocks.importFiles.mockImplementation(async ({ persist }: { persist: (mutate: (value: ReturnType<typeof createMediaLibrary>) => ReturnType<typeof createMediaLibrary>) => Promise<boolean> }) => {
+      await persist((current) => current);
+      await tail.promise;
+      return { completed: ['image.png'], failed: 0, recordSaveFailed: false, cleanupFailed: 0 };
+    });
+    let operation!: Promise<boolean>;
+    await act(async () => { operation = mocks.actions!.onAddMedia(); });
+    expect(mocks.write).toHaveBeenCalledOnce();
+    const flush = lifecycle!.flush!();
+    let finished = false;
+    void flush.then(() => { finished = true; });
+    await Promise.resolve();
+    expect(finished).toBe(false);
+    await act(async () => { tail.resolve(); await operation; });
+    await expect(flush).resolves.toBe(true);
+  });
+});
diff --git a/app/flowix-web/features/media-library/media-library-view.tsx b/app/flowix-web/features/media-library/media-library-view.tsx
index 1907febc6..c43d9d27d 100644
--- a/app/flowix-web/features/media-library/media-library-view.tsx
+++ b/app/flowix-web/features/media-library/media-library-view.tsx
@@ -1,45 +1,85 @@
 'use client';
 
+import { createSaveBarrier } from '@/lib/save-barrier';
+import type { SurfaceLifecycle, SurfacePresentationUpdate } from '@features/workspace/public/surface-api';
+
+import { resolveDatasetFilterForLocation } from '@features/collection/dataset-filter-location';
 import { collectionSessionKey } from '@/lib/collection-session-key';
 import { reuseCollectionValue } from '@features/collection/content-equality';
 import { FolderCollectionSwitchConfirmDialog } from '@features/collection/public/folder-api';
-import { isLegacyCollectionSource } from '@features/collection/model';
+import { collectionDisplayName, isLegacyCollectionSource } from '@features/collection/model';
 import { collectionDisplayDescriptor } from '@/lib/collection-display-registry';
 import { subscribe } from '@platform/tauri/event-bus';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { externalDocuments, files } from '@platform/tauri/client';
+import { useCallback, useEffect, useMemo, useRef, useState, type SetStateAction } from 'react';
+import { externalDocuments, files, notebooks as notebookClient, type CollectionChangedEvent } from '@platform/tauri/client';
 import { canonicalDirectoryPath, canonicalPath } from '@/lib/path';
 import { useNoteStore } from '@features/memo/store/note-store';
+import { useNotebookMediaMaintenanceStore } from '@features/memo/store/notebook-media-maintenance-store';
 import { DocumentListView } from '@features/surface/document-list-view';
-import type { DocumentListSurface } from '@features/surface/types';
+import type { DocumentListViewContext } from '@features/surface/document-list-view-model';
 import { findFileDisplayPath, type FileDisplayIdentity } from '@/lib/file-display-registry';
 import { displayTitleFromFilename } from '@/lib/utils';
 import { toast } from '@/lib/toast';
 import { useI18n } from '@/lib/i18n';
-import { mediaCollectionFilterFromCondition, mediaLibraryDefaultView, mediaLibraryFileCondition, parseMediaLibrary, serializeMediaLibrary, type MediaLibraryDocument, type MediaLibraryFileCondition, type MediaLibraryKind } from './model';
+import { canEditMediaLibraryFilter, hasMediaDatasetFilter, mediaCollectionFilterForSave, mediaLibraryDefaultView, mediaLibraryFileCondition, parseMediaLibrary, serializeMediaLibrary, type MediaLibraryDocument, type MediaLibraryFileCondition, type MediaLibraryKind } from './model';
 import { renameMediaLibrary } from './rename-media-library';
 import { useMediaLibraryActions } from './use-media-library-actions';
+import { useMediaLibraryRefresh } from './use-media-library-refresh';
 
-export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNotebookPath, notebookId = null, expectedCollectionId }: { filePath: string; fileIdentity?: FileDisplayIdentity; notebookPath: string | null; notebookId?: string | null; expectedCollectionId?: string | null }) {
+export function MediaLibraryView({ onSurfaceLifecycleReady, reportPresentation, filePath, fileIdentity, notebookPath: rawNotebookPath, notebookId = null, expectedCollectionId, workspaceHost = 'main-third' }: { onSurfaceLifecycleReady?: (lifecycle: SurfaceLifecycle | null) => void; reportPresentation?: (update: SurfacePresentationUpdate) => void; filePath: string; fileIdentity?: FileDisplayIdentity; notebookPath: string | null; notebookId?: string | null; expectedCollectionId?: string | null; workspaceHost?: 'main-third' | 'browser-column' }) {
   const notebookPath = rawNotebookPath ? canonicalDirectoryPath(rawNotebookPath) : null;
+  const sessionKey = collectionSessionKey({ filePath, fileIdentity, notebookPath, notebookId, expectedCollectionId });
   const { t } = useI18n();
   const notebooks = useNoteStore((state) => state.notebooks);
   const notebook = notebooks.find((candidate) => canonicalDirectoryPath(candidate.path) === (notebookPath ?? ''));
+  const resolvedNotebookId = notebookId ?? notebook?.id ?? null;
+  const mediaMaintenance = useNotebookMediaMaintenanceStore((state) => resolvedNotebookId ? state.statuses[resolvedNotebookId] : undefined);
   const [renamedFilePath, setRenamedFilePath] = useState<string | null>(null);
   const [document, setDocument] = useState<MediaLibraryDocument | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
-  const [saving, setSaving] = useState(false);
+  const [loadAttempt, setLoadAttempt] = useState(0);
+  const [saving, setSavingState] = useState(false);
+  const [retryingMaintenance, setRetryingMaintenance] = useState(false);
+  const savingStateRef = useRef(false);
+  const saveBarrier = useMemo(createSaveBarrier, [sessionKey]);
+  const setSaving = useCallback((action: SetStateAction<boolean>) => {
+    const next = typeof action === 'function' ? action(savingStateRef.current) : action;
+    saveBarrier.setSaving(next);
+    savingStateRef.current = next;
+    setSavingState(next);
+  }, [saveBarrier]);
+  const retryMediaMaintenance = useCallback(async () => {
+    if (!resolvedNotebookId || retryingMaintenance) return;
+    setRetryingMaintenance(true);
+    try {
+      await notebookClient.retryMediaMaintenance(resolvedNotebookId);
+    } catch (reason) {
+      toast.error(reason instanceof Error ? reason.message : t('mediaLibrary.maintenanceRetryFailed'));
+    } finally {
+      setRetryingMaintenance(false);
+    }
+  }, [resolvedNotebookId, retryingMaintenance, t]);
+  const reportSaveFailure = useCallback(() => saveBarrier.fail(), [saveBarrier]);
   const [confirmFolderSwitch, setConfirmFolderSwitch] = useState(false);
   const sourceContentRef = useRef<string | null>(null);
   const saveInFlightRef = useRef(false);
   const displayId = fileIdentity?.displayId;
   const currentFilePath = (displayId ? findFileDisplayPath(displayId) : null) ?? renamedFilePath ?? filePath;
 
-  const sessionKey = collectionSessionKey({ filePath, fileIdentity, notebookPath, notebookId, expectedCollectionId });
   const currentSessionKeyRef = useRef(sessionKey);
   currentSessionKeyRef.current = sessionKey;
-  const pendingRefreshRef = useRef<{ key: string; path: string } | null>(null);
+  const retryLoad = useCallback(() => setLoadAttempt((attempt) => attempt + 1), []);
+  useEffect(() => {
+    onSurfaceLifecycleReady?.({ status: 'ready', flush: async () => {
+      const saved = await saveBarrier.flush();
+      return saved && currentSessionKeyRef.current === sessionKey;
+    } });
+    return () => {
+      onSurfaceLifecycleReady?.(null);
+    };
+  }, [onSurfaceLifecycleReady, saveBarrier, sessionKey]);
+  useEffect(() => () => saveBarrier.cancel(), [saveBarrier]);
   const acceptContent = useCallback((content: string) => {
     if (currentSessionKeyRef.current !== sessionKey) return false;
     const next = parseMediaLibrary(content);
@@ -54,22 +94,9 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
     } : next);
     return true;
   }, [displayId, expectedCollectionId, sessionKey]);
-  const refreshContent = useCallback((path: string) => {
-    void externalDocuments.read(path, notebookPath).then((content) => {
-      if (currentSessionKeyRef.current !== sessionKey) return;
-      if (saveInFlightRef.current) {
-        pendingRefreshRef.current ??= { key: sessionKey, path };
-        return;
-      }
-      acceptContent(content);
-    }).catch(() => undefined);
-  }, [acceptContent, notebookPath, sessionKey]);
-  useEffect(() => {
-    if (saving) return;
-    const pending = pendingRefreshRef.current;
-    pendingRefreshRef.current = null;
-    if (pending?.key === sessionKey) refreshContent(pending.path);
-  }, [refreshContent, saving, sessionKey]);
+  const { error: refreshError, refreshContent, retryRefresh } = useMediaLibraryRefresh({
+    sessionKey, notebookPath, currentFilePath, saving, saveInFlightRef, acceptContent,
+  });
 
   useEffect(() => setRenamedFilePath(null), [filePath]);
 
@@ -112,24 +139,36 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
       if (!cancelled) setLoading(false);
     });
     return () => { cancelled = true; };
-  }, [displayId ?? currentFilePath, notebookPath]);
+  }, [displayId ?? currentFilePath, expectedCollectionId, loadAttempt, notebookPath]);
 
   useEffect(() => {
-    const refresh = (event: { notebookId: string; collectionId?: string; relativePath?: string }) => {
+    const refresh = (event: Partial<CollectionChangedEvent> & Pick<CollectionChangedEvent, 'notebookId'>) => {
       const collectionId = document?.collection.id;
-      if (event.notebookId !== (notebookId ?? notebook?.id) || !collectionId
-        || (event.collectionId && event.collectionId !== collectionId) || !notebookPath) return;
-      const path = event.relativePath ? `${canonicalDirectoryPath(notebookPath)}/${event.relativePath}`
-        : (displayId ? findFileDisplayPath(displayId) : null) ?? currentFilePath;
-      if (saveInFlightRef.current) {
-        // A readiness event must not replace a confirmed destination with the old display path.
-        if (event.relativePath || !pendingRefreshRef.current) pendingRefreshRef.current = { key: sessionKey, path };
-        return;
+      if (event.notebookId !== (notebookId ?? notebook?.id) || !collectionId || !notebookPath) return;
+      const root = canonicalDirectoryPath(notebookPath);
+      let movedPath: string | null = null;
+      if (event.directoryMove) {
+        const previous = canonicalPath(`${root}/${event.directoryMove.previousRelativePath}`);
+        const next = canonicalPath(`${root}/${event.directoryMove.relativePath}`);
+        const current = canonicalPath(currentFilePath);
+        if (current === previous || current.startsWith(`${previous}/`)) {
+          movedPath = `${next}${current.slice(previous.length)}`;
+        } else if (current === next || current.startsWith(`${next}/`)) {
+          movedPath = current;
+        }
       }
-      refreshContent(path);
+      if (event.collectionId && event.collectionId !== collectionId && !movedPath) return;
+      const eventPath = event.relativePath
+        ? `${root}/${event.relativePath}`
+        : (displayId ? findFileDisplayPath(displayId) : null) ?? currentFilePath;
+      const path = movedPath ?? eventPath;
+      // Events with an authoritative path can replace a queued readiness refresh.
+      refreshContent(path, Boolean(event.relativePath));
     };
-    const stopCollection = subscribe<{ notebookId: string; collectionId: string; relativePath: string }>('collection-changed', refresh);
-    const stopCatalog = subscribe<{ notebookId: string }>('file-management-changed', refresh);
+    const stopCollection = subscribe<CollectionChangedEvent>('collection-changed', refresh);
+    const stopCatalog = subscribe<{ notebookId: string; operationId?: string }>('file-management-changed', (event) => {
+      if (!event.operationId) refresh(event);
+    });
     return () => { stopCollection(); stopCatalog(); };
   }, [currentFilePath, displayId, document?.collection.id, notebook?.id, notebookId, notebookPath, refreshContent, sessionKey]);
 
@@ -172,13 +211,16 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
             continue;
           }
           setDocument(latest);
+          reportSaveFailure();
           toast.error('媒体库配置再次发生变化，已载入最新版本，请重试');
           return false;
         }
         throw new Error(result.status === 'error' ? result.message : '媒体库文件已不存在');
       }
+      reportSaveFailure();
       return false;
     } catch (reason) {
+      reportSaveFailure();
       toast.error(reason instanceof Error ? reason.message : '保存媒体库配置失败');
       return false;
     } finally {
@@ -187,10 +229,14 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
         setSaving(false);
       }
     }
-  }, [currentFilePath, document, notebookPath]);
+  }, [currentFilePath, document, notebookPath, reportSaveFailure, setSaving]);
 
   const updateFilterCondition = useCallback(async (fileCondition: MediaLibraryFileCondition) => {
-    if (saving) return false;
+    if (saving || !notebookPath) return false;
+    if (document && !canEditMediaLibraryFilter(document)) {
+      toast.error('当前媒体库包含编辑器不支持的筛选，未保存以保留原条件');
+      return false;
+    }
     return persistMutation((current) => ({
       ...current,
       collection: {
@@ -198,13 +244,11 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
         revision: current.collection.revision + 1,
         updated_at: new Date().toISOString(),
       },
-      dataset: { ...current.dataset, filter: Object.keys(fileCondition).length > 0
-        ? mediaCollectionFilterFromCondition(fileCondition)
-        : null },
+      dataset: { ...current.dataset, filter: mediaCollectionFilterForSave(current, fileCondition, currentFilePath, notebookPath) },
       views: { ...current.views, items: current.views.items.map((view) => view.id === current.views.default_id
         ? { ...view, filter: { all: [], any: [] } } : view) },
     }));
-  }, [persistMutation, saving]);
+  }, [currentFilePath, document, notebookPath, persistMutation, saving]);
 
   const renameLibrary = useCallback(async (rawTitle: string) => {
     const title = rawTitle.trim();
@@ -225,28 +269,48 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
         notebookPath, notebookId: notebookId ?? notebook?.id,
         collectionId: document.collection.id, title,
       });
-      if (!acceptContent(result.content)) return;
+      if (!acceptContent(result.content)) { reportSaveFailure(); return; }
       setRenamedFilePath(result.filePath);
       if (result.errorCode) toast.error(`集合已更新，后续操作待恢复：${result.errorCode}`);
     } catch (reason) {
+      reportSaveFailure();
       toast.error(reason instanceof Error ? reason.message : '重命名媒体库失败');
     } finally {
       saveInFlightRef.current = false;
       setSaving(false);
     }
-  }, [acceptContent, currentFilePath, displayId, document, notebook?.id, notebookId, notebookPath, saving]);
+  }, [acceptContent, currentFilePath, displayId, document, notebook?.id, notebookId, notebookPath, reportSaveFailure, saving, setSaving]);
 
   const { addMedia, deleteMedia } = useMediaLibraryActions({
     document, setDocument, notebookPath, notebookId: notebookId ?? notebook?.id ?? null, currentFilePath, saving, setSaving,
-    sourceContentRef, saveInFlightRef, persistMutation, t,
+    sourceContentRef, saveInFlightRef, persistMutation, reportSaveFailure, t,
   });
 
   const selectedKind = document ? mediaLibraryFileCondition(document).file_type : undefined;
   const resourceKinds = useMemo<MediaLibraryKind[]>(() => selectedKind ? [selectedKind] : ['image', 'video'], [selectedKind]);
   const activeCollectionId = document?.collection.id;
-  const libraryDisplayName = document?.collection.placement === 'folder'
-    ? currentFilePath.replace(/[\\/]+$/, '').replace(/[\\/][^\\/]*$/, '').split(/[\\/]/).pop() || document.collection.name
-    : document?.collection.name ?? '媒体库';
+  const libraryDisplayName = document ? collectionDisplayName(currentFilePath, document.collection.placement) : '媒体库';
+  useEffect(() => {
+    if (!reportPresentation) return;
+    if (loading) {
+      reportPresentation({ title: libraryDisplayName, state: {
+        status: 'loading', phase: 'content', message: { key: 'mediaLibrary.opening' }, retainContent: false,
+      } });
+    } else if (error) {
+      reportPresentation({ title: libraryDisplayName, state: {
+        status: 'error',
+        message: { key: 'error.unexpected', fallbackText: error },
+        actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retryLoad }],
+      } });
+    } else if (document) {
+      reportPresentation({ title: libraryDisplayName, state: { status: 'ready' } });
+    } else {
+      reportPresentation({ title: libraryDisplayName, state: {
+        status: 'unavailable', reason: 'missing', message: { key: 'mediaLibrary.unavailable' },
+        actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retryLoad }],
+      } });
+    }
+  }, [document, error, libraryDisplayName, loading, reportPresentation, retryLoad]);
   const mediaScope = useMemo(() => {
     if (!document || !notebookPath) return undefined;
     const source = document.dataset.source;
@@ -272,34 +336,50 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
   const mediaLibraryExcludedPaths = useMemo(() => (document?.dataset.records.exclude ?? [])
     .map((record) => record.relative_path)
     .filter((path): path is string => typeof path === 'string'), [document?.dataset.records.exclude]);
-  const listSurface: DocumentListSurface | null = useMemo(() => {
+  const listContext: DocumentListViewContext | null = useMemo(() => {
     const resolvedNotebookId = notebookId ?? notebook?.id;
     if (!resolvedNotebookId || !notebookPath || !activeCollectionId) return null;
     const libraryIdentity = `media-library:${resolvedNotebookId}:${activeCollectionId}`;
     const browseCondition = mediaLibraryFileCondition(document);
     return {
-      kind: 'document-list',
-      instanceKey: libraryIdentity,
       displayId: displayId ?? libraryIdentity,
       folderPath: notebookPath,
       notebookPath,
       notebookId: resolvedNotebookId,
       filters: { resourceKinds },
       ...(mediaScope ? { mediaScope } : {}),
-      ...((mediaScope || browseCondition.path_scope === 'all' || browseCondition.path_contains)
+      ...((mediaScope || hasMediaDatasetFilter(document?.dataset.filter)
+        || browseCondition.path_scope === 'all' || browseCondition.path_contains
+        || browseCondition.file_name_contains || browseCondition.file_type)
         ? { mediaDatasetActive: true } : {}),
     };
   }, [activeCollectionId, displayId, document?.dataset.filter, mediaScope, notebook?.id, notebookId, notebookPath, resourceKinds]);
 
   if (loading) return <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">正在打开媒体库…</div>;
   if (error) return <div className="flex h-full items-center justify-center px-6 text-center text-sm text-[var(--destructive)]">{error}</div>;
-  if (!document || !listSurface) return <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">媒体库不可用</div>;
+  if (!document || !listContext) return <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">媒体库不可用</div>;
 
   return <div className="relative h-full min-h-0">
     {saving && <span className="pointer-events-none absolute right-5 top-4 z-10 text-[11px] text-[var(--muted-foreground)]">保存中…</span>}
+    {refreshError && <div role="alert" className="mx-4 mt-3 flex items-center justify-between gap-3 rounded-lg border border-[var(--destructive)]/30 bg-[var(--destructive)]/5 px-3 py-2 text-xs text-[var(--foreground)]">
+      <span className="min-w-0 truncate">{t('mediaLibrary.refreshFailed')}: {refreshError}</span>
+      <button type="button" onClick={retryRefresh} className="shrink-0 rounded-lg border border-[var(--border)] px-2.5 py-1 text-xs hover:bg-[var(--hover-bg)]">
+        {t('error.retry')}
+      </button>
+    </div>}
+    {mediaMaintenance?.state === 'failed' && <div role="alert" className="mx-4 mt-3 flex items-center justify-between gap-3 rounded-lg border border-[var(--destructive)]/30 bg-[var(--destructive)]/5 px-3 py-2 text-xs text-[var(--foreground)]">
+      <span className="min-w-0 truncate">{mediaMaintenance.message || t('mediaLibrary.maintenanceFailed')}</span>
+      <button type="button" disabled={retryingMaintenance} onClick={() => void retryMediaMaintenance()} className="shrink-0 rounded-lg border border-[var(--border)] px-2.5 py-1 text-xs hover:bg-[var(--hover-bg)] disabled:opacity-50">
+        {retryingMaintenance ? t('mediaLibrary.maintenanceRunning') : t('error.retry')}
+      </button>
+    </div>}
+    {(mediaMaintenance?.state === 'queued' || mediaMaintenance?.state === 'running') && <div role="status" className="mx-4 mt-3 rounded-lg bg-[var(--muted)] px-3 py-2 text-xs text-[var(--muted-foreground)]">
+      {mediaMaintenance.state === 'queued' ? t('mediaLibrary.maintenanceQueued') : t('mediaLibrary.maintenanceRunning')}
+    </div>}
     <DocumentListView
-      key={listSurface.displayId}
-      surface={listSurface}
+      key={listContext.displayId}
+      listContext={listContext}
+      workspaceHost={workspaceHost}
       mediaLibrary
       libraryName={libraryDisplayName}
       libraryFilePath={currentFilePath}
@@ -309,7 +389,7 @@ export function MediaLibraryView({ filePath, fileIdentity, notebookPath: rawNote
       mediaLibraryFilter={mediaLibraryFileCondition(document)}
       mediaLibraryRecords={mediaLibraryRecords}
       mediaLibraryExcludedPaths={mediaLibraryExcludedPaths}
-      mediaLibraryDatasetFilter={document.dataset.filter}
+      mediaLibraryDatasetFilter={resolveDatasetFilterForLocation(document.dataset.filter, document.collection.placement, currentFilePath, notebookPath)}
       mediaLibraryViewFilter={mediaLibraryDefaultView(document).filter}
       onAddMedia={addMedia}
       onDeleteMedia={deleteMedia}
diff --git a/app/flowix-web/features/media-library/model.ts b/app/flowix-web/features/media-library/model.ts
index 9185d5242..9d2dbe095 100644
--- a/app/flowix-web/features/media-library/model.ts
+++ b/app/flowix-web/features/media-library/model.ts
@@ -2,7 +2,8 @@ import { createCollectionMetadata, createUuidV7, parseCollectionDocumentV2, seri
 import { createUniqueNotebookFile } from '@features/collection/create-unique-notebook-file';
 export { createUuidV7 } from '@features/collection/model';
 import { sanitizeFileName } from '@/lib/export-utils';
-import { matchesCollectionFilter, type CollectionRuleFilter } from '@features/collection/rule-filter';
+import { matchesDatasetFilter, type DatasetFilter } from '@features/collection/rule-filter';
+import { resolveDatasetFilterForLocation } from '@features/collection/dataset-filter-location';
 
 export type MediaLibraryKind = 'image' | 'video';
 export interface MediaLibraryFileCondition {
@@ -20,6 +21,17 @@ export interface MediaLibraryRecord {
   relative_path: string;
 }
 
+/** Empty filter containers do not opt a standalone media library into notebook-wide browsing. */
+export function hasMediaDatasetFilter(filter: Record<string, unknown> | null | undefined): boolean {
+  if (!filter) return false;
+  if (Array.isArray(filter.conditions) && (filter.match === 'all' || filter.match === 'any')) {
+    return typeof filter.path === 'string' || filter.conditions.length > 0;
+  }
+  const all = Array.isArray(filter.all) ? filter.all : [];
+  const any = Array.isArray(filter.any) ? filter.any : [];
+  return all.length > 0 || any.length > 0;
+}
+
 export function normalizeMediaLibraryFileCondition(condition?: MediaLibraryFileCondition | null): MediaLibraryFileCondition {
   const normalized = {
     file_name_contains: condition?.file_name_contains?.trim() ?? '',
@@ -32,12 +44,14 @@ export function normalizeMediaLibraryFileCondition(condition?: MediaLibraryFileC
 
 export function mediaCollectionFilterFromCondition(condition?: MediaLibraryFileCondition | null): Record<string, unknown> {
   const normalized = normalizeMediaLibraryFileCondition(condition);
-  const all: Record<string, unknown>[] = [];
-  if (normalized.file_name_contains) all.push({ field: 'file_name', op: 'contains', value: normalized.file_name_contains });
-  if (normalized.path_scope === 'all') all.push({ field: 'path', op: 'contains', value: '' });
-  else if (normalized.path_contains) all.push({ field: 'path', op: 'contains', value: normalized.path_contains });
-  if (normalized.file_type) all.push({ field: 'kind', op: 'eq', value: normalized.file_type });
-  return { all, any: [] };
+  const conditions: Record<string, unknown>[] = [];
+  if (normalized.file_name_contains) conditions.push({ field: 'file_name', op: 'contains', value: normalized.file_name_contains });
+  if (normalized.file_type) conditions.push({ field: 'kind', op: 'eq', value: normalized.file_type });
+  return {
+    path: normalized.path_scope === 'all' ? '' : normalized.path_contains || null,
+    match: 'all',
+    conditions,
+  };
 }
 
 export function matchesMediaCollectionFilter(relativePath: string, kind: MediaLibraryKind, filter?: Record<string, unknown> | null): boolean {
@@ -45,7 +59,7 @@ export function matchesMediaCollectionFilter(relativePath: string, kind: MediaLi
   const path = relativePath.replace(/\\/g, '/');
   const name = path.split('/').pop() ?? path;
   const directory = path.split('/').slice(0, -1).join('/');
-  return matchesCollectionFilter(filter as unknown as CollectionRuleFilter, (rule) => {
+  return matchesDatasetFilter(filter as unknown as DatasetFilter, (rule) => {
     const actual = rule.field === 'file_name' ? name : rule.field === 'path' ? directory : rule.field === 'kind' ? kind : undefined;
     if (actual === undefined) return false;
     if (rule.op === 'in' && Array.isArray(rule.value)) return rule.value.some((value) => String(value).toLocaleLowerCase() === actual.toLocaleLowerCase());
@@ -85,23 +99,86 @@ export function mediaLibraryDefaultView(document: MediaLibraryDocument) {
 
 export function mediaLibraryFileCondition(document: MediaLibraryDocument): MediaLibraryFileCondition {
   const filter = document.dataset.filter;
-  if (!filter || !Array.isArray(filter.all) || (Array.isArray(filter.any) && filter.any.length)) return {};
+  if (!filter) return {};
   const condition: MediaLibraryFileCondition = {};
-  for (const entry of filter.all) {
+  let rules: unknown[];
+  if (Array.isArray(filter.conditions) && (filter.match === 'all' || filter.match === 'any')) {
+    rules = filter.conditions;
+    if (filter.path === '') condition.path_scope = 'all';
+    else if (typeof filter.path === 'string') condition.path_contains = filter.path;
+  } else if (Array.isArray(filter.all) && Array.isArray(filter.any)) {
+    const anyNonPath = filter.any.filter((entry) => !entry || typeof entry !== 'object' || Array.isArray(entry) || entry.field !== 'path');
+    if (anyNonPath.length) return {};
+    rules = [...filter.all, ...filter.any];
+  } else {
+    return {};
+  }
+  const pathRules = rules.filter((entry) => Boolean(entry && typeof entry === 'object' && !Array.isArray(entry)
+    && (entry as Record<string, unknown>).field === 'path')) as Record<string, unknown>[];
+  if (pathRules.length) {
+    const nonEmptyPaths = pathRules.map((rule) => typeof rule.value === 'string' ? rule.value.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') : '').filter(Boolean);
+    condition.path_scope = nonEmptyPaths.length ? undefined : 'all';
+    if (nonEmptyPaths.length) condition.path_contains = nonEmptyPaths.sort((left, right) => right.length - left.length)[0];
+  }
+  for (const entry of rules) {
     if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
-    if (entry.field === 'file_name' && entry.op === 'contains' && typeof entry.value === 'string') condition.file_name_contains = entry.value;
-    if (entry.field === 'path' && entry.op === 'contains' && typeof entry.value === 'string') {
-      if (entry.value === '') condition.path_scope = 'all';
-      else condition.path_contains = entry.value;
-    }
-    if (entry.field === 'kind' && entry.op === 'eq' && (entry.value === 'image' || entry.value === 'video')) condition.file_type = entry.value;
+    const rule = entry as Record<string, unknown>;
+    if (rule.field === 'file_name' && rule.op === 'contains' && typeof rule.value === 'string') condition.file_name_contains = rule.value;
+    if (rule.field === 'kind' && rule.op === 'eq' && (rule.value === 'image' || rule.value === 'video')) condition.file_type = rule.value;
   }
   return condition;
 }
 
-export function createMediaLibraryRecord(relativePath: string, resourceId?: string, now = new Date().toISOString()): MediaLibraryRecord {
+export function canEditMediaLibraryFilter(document: MediaLibraryDocument): boolean {
+  const filter = document.dataset.filter;
+  if (!filter) return true;
+  if (Array.isArray(filter.conditions) && filter.match === 'all') {
+    const conditions = filter.conditions as Record<string, unknown>[];
+    const fields = conditions.map((rule) => rule.field);
+    return new Set(fields).size === fields.length && conditions.every((rule) => (
+      (rule.field === 'file_name' && rule.op === 'contains' && typeof rule.value === 'string')
+      || (rule.field === 'kind' && rule.op === 'eq' && (rule.value === 'image' || rule.value === 'video'))
+      || (rule.field === 'kind' && rule.op === 'in' && Array.isArray(rule.value)
+        && rule.value.length === 2 && rule.value.includes('image') && rule.value.includes('video'))
+    ));
+  }
+  const all = Array.isArray(filter.all) ? filter.all as Record<string, unknown>[] : null;
+  const any = Array.isArray(filter.any) ? filter.any as Record<string, unknown>[] : null;
+  // The compact media editor represents conjunctions and one value per field.
+  // OR branches or duplicate scalar rules cannot be written back losslessly.
+  if (!all || !any || any.length > 0) return false;
+  const rules = all;
+  const pathRules = rules.filter((rule) => rule.field === 'path');
+  const scalarRules = rules.filter((rule) => rule.field !== 'path');
+  if (new Set(scalarRules.map((rule) => rule.field)).size !== scalarRules.length) return false;
+  const paths = [...new Set(pathRules.map((rule) => typeof rule.value === 'string'
+    ? rule.value.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') : null))];
+  if (pathRules.some((rule) => rule.op !== 'contains' || typeof rule.value !== 'string')
+    || paths.includes(null)) return false;
+  const nonEmptyPaths = paths.filter((path): path is string => Boolean(path));
+  if (nonEmptyPaths.some((path) => nonEmptyPaths.some((other) => path !== other
+    && !path.startsWith(`${other}/`) && !other.startsWith(`${path}/`)))) return false;
+  return rules.every((rule) => (
+    (rule.field === 'path' && rule.op === 'contains' && typeof rule.value === 'string')
+    || (rule.field === 'file_name' && rule.op === 'contains' && typeof rule.value === 'string')
+    || (rule.field === 'kind' && rule.op === 'eq' && (rule.value === 'image' || rule.value === 'video'))
+    || (rule.field === 'kind' && rule.op === 'in' && Array.isArray(rule.value)
+      && rule.value.length === 2 && rule.value.includes('image') && rule.value.includes('video'))
+  ));
+}
+
+export function createMediaLibraryRecord(notebookId: string, relativePath: string, resourceId?: string, now = new Date().toISOString()): MediaLibraryRecord {
   const path = relativePath.replace(/\\/g, '/');
-  return { id: `rec_${createUuidV7()}`, updated_at: now, resource_id: resourceId ?? `path:${path}`, relative_path: path };
+  return { id: `rec_${createUuidV7()}`, updated_at: now, resource_id: resourceId ?? `${notebookId}::${path}`, relative_path: path };
+}
+
+/** Called against each current document, including conflict retries. */
+export function mediaCollectionFilterForSave(document: MediaLibraryDocument, condition: MediaLibraryFileCondition, filePath: string, notebookPath: string): Record<string, unknown> | null {
+  if (!canEditMediaLibraryFilter(document)) throw new Error('当前媒体库包含编辑器不支持的筛选，已取消保存');
+  const normalized = normalizeMediaLibraryFileCondition(condition);
+  const filter = document.collection.placement === 'folder' || Object.keys(normalized).length
+    ? mediaCollectionFilterFromCondition(normalized) : null;
+  return resolveDatasetFilterForLocation(filter, document.collection.placement, filePath, notebookPath);
 }
 
 export function createMediaLibrary(name: string): MediaLibraryDocument {
diff --git a/app/flowix-web/features/media-library/use-media-library-actions.ts b/app/flowix-web/features/media-library/use-media-library-actions.ts
index 0fc36b947..9d8158fc2 100644
--- a/app/flowix-web/features/media-library/use-media-library-actions.ts
+++ b/app/flowix-web/features/media-library/use-media-library-actions.ts
@@ -25,12 +25,13 @@ interface MediaLibraryActionsOptions {
   sourceContentRef: MutableRefObject<string | null>;
   saveInFlightRef: MutableRefObject<boolean>;
   persistMutation: PersistMutation;
+  reportSaveFailure?: () => void;
   t: ReturnType<typeof useI18n>['t'];
 }
 
 export function useMediaLibraryActions({
   document, setDocument, notebookPath, notebookId, currentFilePath, saving, setSaving,
-  sourceContentRef, saveInFlightRef, persistMutation, t,
+  sourceContentRef, saveInFlightRef, persistMutation, reportSaveFailure, t,
 }: MediaLibraryActionsOptions) {
   const addMedia = useCallback(async (): Promise<boolean> => {
     if (!document || !notebookPath || !notebookId || saving || saveInFlightRef.current) return false;
@@ -66,13 +67,14 @@ export function useMediaLibraryActions({
       if (result.completed.length) toast.success(t('mediaLibrary.addMediaSuccess', { count: result.completed.length }));
       return result.completed.length > 0;
     } catch (reason) {
+      reportSaveFailure?.();
       toast.error(reason instanceof Error ? reason.message : t('mediaLibrary.addMediaFailed'));
       return false;
     } finally {
       saveInFlightRef.current = false;
       setSaving(false);
     }
-  }, [currentFilePath, document, notebookId, notebookPath, persistMutation, saving, t]);
+  }, [currentFilePath, document, notebookId, notebookPath, persistMutation, reportSaveFailure, saving, setSaving, t]);
 
   const deleteMedia = useCallback(async (item: DocumentPageItem): Promise<boolean> => {
     if (!document || !notebookPath || saving || saveInFlightRef.current) return false;
@@ -109,13 +111,14 @@ export function useMediaLibraryActions({
       toast.success(t('media.fileTree.deleted', { name: item.name }));
       return true;
     } catch (reason) {
+      reportSaveFailure?.();
       toast.error(reason instanceof Error ? reason.message : t('media.fileTree.deleteFailed'));
       return false;
     } finally {
       saveInFlightRef.current = false;
       setSaving(false);
     }
-  }, [currentFilePath, document, notebookPath, persistMutation, saving, t]);
+  }, [currentFilePath, document, notebookPath, persistMutation, reportSaveFailure, saving, setSaving, t]);
 
   return { addMedia, deleteMedia };
 }
diff --git a/app/flowix-web/features/media-library/use-media-library-refresh.ts b/app/flowix-web/features/media-library/use-media-library-refresh.ts
new file mode 100644
index 000000000..e60967e76
--- /dev/null
+++ b/app/flowix-web/features/media-library/use-media-library-refresh.ts
@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useRef, useState, type MutableRefObject } from 'react';
+import { externalDocuments } from '@platform/tauri/client';
+
+interface PendingRefresh {
+  sessionKey: string;
+  path: string;
+}
+
+export function useMediaLibraryRefresh({
+  sessionKey,
+  notebookPath,
+  currentFilePath,
+  saving,
+  saveInFlightRef,
+  acceptContent,
+}: {
+  sessionKey: string;
+  notebookPath: string | null;
+  currentFilePath: string;
+  saving: boolean;
+  saveInFlightRef: MutableRefObject<boolean>;
+  acceptContent: (content: string) => boolean;
+}) {
+  const [error, setError] = useState<string | null>(null);
+  const activeSessionKeyRef = useRef(sessionKey);
+  const requestIdRef = useRef(0);
+  const pendingRefreshRef = useRef<PendingRefresh | null>(null);
+  activeSessionKeyRef.current = sessionKey;
+
+  const refreshContent = useCallback((path: string, replacePending = true) => {
+    const requestId = ++requestIdRef.current;
+    if (saveInFlightRef.current) {
+      if (replacePending || pendingRefreshRef.current?.sessionKey !== sessionKey) {
+        pendingRefreshRef.current = { sessionKey, path };
+      }
+      return;
+    }
+
+    void externalDocuments.read(path, notebookPath).then((content) => {
+      if (activeSessionKeyRef.current !== sessionKey || requestIdRef.current !== requestId) return;
+      if (saveInFlightRef.current) {
+        if (replacePending || pendingRefreshRef.current?.sessionKey !== sessionKey) {
+          pendingRefreshRef.current = { sessionKey, path };
+        }
+        return;
+      }
+      if (!content) throw new Error('无法读取媒体库文件');
+      if (!acceptContent(content)) throw new Error('媒体库身份或版本已变化');
+      setError(null);
+    }).catch((reason: unknown) => {
+      if (activeSessionKeyRef.current !== sessionKey || requestIdRef.current !== requestId) return;
+      setError(reason instanceof Error ? reason.message : String(reason));
+    });
+  }, [acceptContent, notebookPath, saveInFlightRef, sessionKey]);
+
+  useEffect(() => {
+    setError(null);
+    requestIdRef.current += 1;
+    if (pendingRefreshRef.current?.sessionKey !== sessionKey) pendingRefreshRef.current = null;
+  }, [sessionKey]);
+  useEffect(() => () => { requestIdRef.current += 1; }, []);
+
+  useEffect(() => {
+    if (saving) return;
+    const pending = pendingRefreshRef.current;
+    pendingRefreshRef.current = null;
+    if (pending?.sessionKey === sessionKey) refreshContent(pending.path);
+  }, [refreshContent, saving, sessionKey]);
+
+  const retryRefresh = useCallback(() => refreshContent(currentFilePath), [currentFilePath, refreshContent]);
+  return { error, refreshContent, retryRefresh };
+}
diff --git a/app/flowix-web/features/memo/components/file-type-icon.tsx b/app/flowix-web/features/memo/components/file-type-icon.tsx
index 511dd977c..a53c48725 100644
--- a/app/flowix-web/features/memo/components/file-type-icon.tsx
+++ b/app/flowix-web/features/memo/components/file-type-icon.tsx
@@ -1,35 +1,19 @@
-import { forwardRef } from 'react';
-import type { Icon, IconProps } from '@phosphor-icons/react';
-import { GalleryHorizontalEnd } from 'lucide-react';
-import {
-  FileCodeIcon,
-  FileDocIcon,
-  FileHtmlIcon,
-  FileImageIcon,
-  FileMdIcon,
-  FilePdfIcon,
-  FilePptIcon,
-  FileTextIcon,
-  FileVideoIcon,
-  FileXlsIcon,
-  FileZipIcon,
-} from '@phosphor-icons/react';
-import {
-  fileExtension,
-  isCodeTextFilePath,
-  isImageFilePath,
-  isMarkdownFilePath,
-  isVideoFilePath,
-} from '@features/editor/code-file';
-
-const DOCUMENT_EXTENSIONS = new Set(['doc', 'docm', 'docx', 'dot', 'dotx', 'odt', 'rtf']);
-const HTML_EXTENSIONS = new Set(['htm', 'html', 'xhtml']);
-const PRESENTATION_EXTENSIONS = new Set(['key', 'odp', 'pot', 'potx', 'ppt', 'pptm', 'pptx']);
-const ARCHIVE_EXTENSIONS = new Set([
-  '7z', 'bz', 'bz2', 'cab', 'gz', 'iso', 'lz', 'lzma', 'rar', 'tar', 'tgz', 'xz', 'zip', 'zst',
-]);
-const SPREADSHEET_EXTENSIONS = new Set(['csv', 'numbers', 'ods', 'tsv', 'xls', 'xlsb', 'xlsm', 'xlsx', 'xlt', 'xltx']);
-
+/** @deprecated Import ContentIcon from features/content for new callers. */
+export {
+  FileTypeIcon,
+  NotebookTreeResourceIcon,
+  getFileIcon,
+  TableDocumentIcon,
+  MediaLibraryIcon,
+  CodeFileIcon,
+  FallbackFileIcon,
+  VideoFileIcon,
+  ImageFileIcon,
+} from '@features/content/components/content-icon';
+
+import { getFileIconKind as getContentFileIconKind } from '@features/content/components/content-icon';
+
+/** Legacy name retained for callers that expect Markdown-specific terminology. */
 export type FileIconKind =
   | 'markdown'
   | 'html'
@@ -43,158 +27,10 @@ export type FileIconKind =
   | 'code'
   | 'fallback';
 
-const PHOSPHOR_ICON_BY_KIND: Record<FileIconKind, Icon> = {
-  markdown: FileMdIcon,
-  html: FileHtmlIcon,
-  document: FileDocIcon,
-  presentation: FilePptIcon,
-  spreadsheet: FileXlsIcon,
-  pdf: FilePdfIcon,
-  video: FileVideoIcon,
-  archive: FileZipIcon,
-  image: FileImageIcon,
-  code: FileCodeIcon,
-  fallback: FileTextIcon,
-};
-
-/** Resolve a file's semantic icon kind once for every file-tree renderer. */
 export function getFileIconKind(path: string): FileIconKind {
-  if (isTableDocumentPath(path)) return 'spreadsheet';
-  const extension = fileExtension(path);
-
-  if (isMarkdownFilePath(path)) return 'markdown';
-  if (HTML_EXTENSIONS.has(extension)) return 'html';
-  if (DOCUMENT_EXTENSIONS.has(extension)) return 'document';
-  if (PRESENTATION_EXTENSIONS.has(extension)) return 'presentation';
-  if (SPREADSHEET_EXTENSIONS.has(extension)) return 'spreadsheet';
-  if (extension === 'pdf') return 'pdf';
-  if (isVideoFilePath(path)) return 'video';
-  if (ARCHIVE_EXTENSIONS.has(extension)) return 'archive';
-  if (isImageFilePath(path)) return 'image';
-  if (isCodeTextFilePath(path)) return 'code';
-
-  return 'fallback';
-}
-
-/** Resolve the legacy Phosphor component for callers that need it. */
-export function getFileIcon(path: string): Icon {
-  return PHOSPHOR_ICON_BY_KIND[getFileIconKind(path)];
-}
-
-export function FileTypeIcon({ path, className }: { path: string; className?: string }) {
-  if (/\.lib\.ya?ml$/i.test(path)) return <GalleryHorizontalEnd aria-hidden="true" className={className} />;
-  if (isTableDocumentPath(path)) {
-    return <TableDocumentIcon className={className} />;
-  }
-  const kind = getFileIconKind(path);
-  if (kind === 'image' || kind === 'video' || kind === 'code' || kind === 'fallback') {
-    return <CustomFileIcon kind={kind} className={className} />;
-  }
-
-  const IconComponent = PHOSPHOR_ICON_BY_KIND[kind];
-  return <IconComponent aria-hidden="true" className={className} />;
-}
-
-/** Resolve the custom icons used for non-note files in the notebook tree. */
-export function NotebookTreeResourceIcon({ path, className, collectionType }: { path: string; className?: string; collectionType?: 'table' | 'media_library' }) {
-  if (collectionType === 'media_library') return <MediaLibraryIcon className={className} />;
-  if (collectionType === 'table') return <TableDocumentIcon className={className} />;
-  if (/\.lib\.ya?ml$/i.test(path)) return <MediaLibraryIcon className={className} />;
-  if (isTableDocumentPath(path)) {
-    return <TableDocumentIcon className={className} />;
-  }
-  return <CustomFileIcon kind={getFileIconKind(path)} className={className} />;
-}
-
-function isTableDocumentPath(path: string): boolean {
-  return /\.table\.ya?ml$/i.test(path);
-}
-
-/**
- * 多维表格 (`.table.yaml`) 的统一图标 ── 与媒体库图标共用 viewBox、缩放、
- * 描边和透明度，保持文件树内视觉尺寸一致。保留 Phosphor 兼容组件
- * (forwardRef + IconProps), 以便直接作为 SlashMenuItem.icon 使用。
- */
-export const TableDocumentIcon = forwardRef<SVGSVGElement, IconProps>(
-  function TableDocumentIcon({ className }, ref) {
-    return (
-      <svg ref={ref} xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
-        <g transform="translate(1.5 1.5) scale(0.625)" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-          <rect width="20" height="18" x="2" y="3" rx="2" />
-          <path d="M9 4v16M3 9h18" />
-        </g>
-      </svg>
-    );
-  },
-);
-
-export const MediaLibraryIcon = forwardRef<SVGSVGElement, IconProps>(
-  function MediaLibraryIcon({ className }, ref) {
-    return (
-      <svg ref={ref} xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
-        <g transform="translate(1.5 1.5) scale(0.625)" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-          <path d="M2 7v10" />
-          <path d="M6 5v14" />
-          <rect width="12" height="18" x="10" y="3" rx="2" />
-        </g>
-      </svg>
-    );
-  },
-);
-
-function CustomFileIcon({ kind, className }: { kind: FileIconKind; className?: string }) {
-  if (kind === 'image') return <ImageFileIcon className={className} />;
-  if (kind === 'video') return <VideoFileIcon className={className} />;
-  if (kind === 'code') return <CodeFileIcon className={className} />;
-  return <FallbackFileIcon className={className} />;
-}
-
-export function CodeFileIcon({ className }: { className?: string }) {
-  return (
-    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
-      <path d="M5.25 5.37L2.87 7.53C2.01 8.33 2.01 9.05 2.87 9.85L5.25 11.93" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-      <path d="M10.6 1.8L7.3 16.3" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-      <path d="M12.76 5.37L15.13 7.53C15.99 8.33 15.99 9.05 15.13 9.85L12.76 11.93" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-  );
-}
-
-export function FallbackFileIcon({ className }: { className?: string }) {
-  return (
-    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
-      <g transform="matrix(0.6923077 0 0 0.6923077 0.6923077 0.6923077)">
-        <path d="M 3.6667 19 V 5 c 0 -1.4733 1.1933 -2.6667 2.6667 -2.6667 h 7.448 c 0.3533 0 0.6933 0.14 0.9427 0.3907 l 5.2187 5.2187 c 0.2507 0.2507 0.3907 0.5893 0.3907 0.9427 v 10.1146 c 0 1.4733 -1.1933 2.6667 -2.6667 2.6667 H 6.3333 c -1.4733 0 -2.6667 -1.1933 -2.6667 -2.6667 Z" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
-        <path d="M 20.2133 8.3333 h -4.5467 c -0.736 0 -1.3333 -0.5973 -1.3333 -1.3333 V 2.4693" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
-      </g>
-    </svg>
-  );
-}
-
-export function VideoFileIcon({ className }: { className?: string }) {
-  return (
-    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 18 18" fill="none" opacity={0.6} aria-hidden="true" className={className}>
-      <rect x="1.8" y="3.6" width="11.8" height="10.8" rx="1.8" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-      <path d="M13.6 7.08L16 5.16C16.6 4.68 17.3 5.16 17.3 6V12C17.3 12.84 16.6 13.32 16 12.84L13.6 10.92V7.08Z" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-  );
-}
-
-export function ImageFileIcon({ className }: { className?: string }) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="64"
-      height="64"
-      viewBox="0 0 18 18"
-      fill="none"
-      opacity={0.6}
-      aria-hidden="true"
-      className={className}
-    >
-      <g transform="matrix(0.6666667 0 0 0.6666667 1 1)">
-        <path d="M21.6799 16.9599L18.5499 9.64988C17.4899 7.16988 15.5399 7.06988 14.2299 9.42988L12.3399 12.8399C11.3799 14.5699 9.58993 14.7199 8.34993 13.1699L8.12993 12.8899C6.83993 11.2699 5.01993 11.4699 4.08993 13.3199L2.36993 16.7699C1.15993 19.1699 2.90993 21.9999 5.58993 21.9999H18.3499C20.9499 21.9999 22.6999 19.3499 21.6799 16.9599Z" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-        <path d="M6.96997 8C8.62682 8 9.96997 6.65685 9.96997 5C9.96997 3.34315 8.62682 2 6.96997 2C5.31312 2 3.96997 3.34315 3.96997 5C3.96997 6.65685 5.31312 8 6.96997 8Z" stroke="currentColor" strokeWidth="1.2" vectorEffect="non-scaling-stroke" strokeLinecap="round" strokeLinejoin="round" />
-      </g>
-    </svg>
-  );
+  if (/\.table\.ya?ml$/i.test(path)) return 'spreadsheet';
+  const kind = getContentFileIconKind(path);
+  if (kind === 'note') return 'markdown';
+  if (kind === 'text' || kind === 'unknown') return 'fallback';
+  return kind;
 }
diff --git a/app/flowix-web/features/memo/components/folder-file-tree.tsx b/app/flowix-web/features/memo/components/folder-file-tree.tsx
index 24a56c9c5..c57c6ce51 100644
--- a/app/flowix-web/features/memo/components/folder-file-tree.tsx
+++ b/app/flowix-web/features/memo/components/folder-file-tree.tsx
@@ -10,7 +10,6 @@ import { localDocumentOperations } from '@features/document/public/file-operatio
 import { openPath } from '@platform/tauri/opener';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
 import {
-  ListSurfaceInlineLoadingState,
   ListSurfaceLoadingState,
   ListSurfaceSpinner,
   ListSurfaceViewport,
@@ -30,7 +29,7 @@ import {
   type FolderTreeController,
   type VisibleTreeNode,
 } from '@features/memo/components/use-folder-tree';
-import { FileTypeIcon } from '@features/memo/components/file-type-icon';
+import { ContentIcon } from '@features/content/public/content-api';
 import { useI18n } from '@/lib/i18n';
 
 const TREE_EDGE_GUTTER = 6;
@@ -43,6 +42,9 @@ const FOLDER_MENU_ITEM_CLASS =
   'h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]';
 
 type FileTreeFileIcon = ComponentType<{ path: string; className?: string }>;
+function ContentFileIcon({ path, className }: { path: string; className?: string }) {
+  return <ContentIcon content={{ kind: 'file', path }} className={className} />;
+}
 type FileTreeFolderIcon = ComponentType<{
   expanded: boolean;
   hidden?: boolean;
@@ -84,7 +86,7 @@ export function FolderFileTree({
   onFileSelect,
   onFileOpenInNewTab,
   tree,
-  fileIcon: FileIcon = FileTypeIcon,
+  fileIcon: FileIcon = ContentFileIcon,
   folderIcon: FolderIcon,
 }: {
   folderPath: string;
@@ -561,10 +563,12 @@ export function FolderFileTree({
           onScroll={(event) => setShowScrollTopHint(event.currentTarget.scrollTop > 0)}
         >
           {tree.loading && visibleNodes.length > 0 && (
-            <ListSurfaceInlineLoadingState label={t('memo.fileTree.loading')} className="py-1" />
+            <div className="flex items-center justify-center px-2 py-1" role="status" aria-live="polite">
+              <ListSurfaceSpinner className="h-3.5 w-3.5" ariaLabel={t('memo.fileTree.loading')} />
+            </div>
           )}
           {tree.loading && visibleNodes.length === 0 && contentSized && (
-            <ListSurfaceLoadingState label={t('memo.fileTree.loading')} className="h-24" />
+            <ListSurfaceLoadingState ariaLabel={t('memo.fileTree.loading')} className="h-24" />
           )}
           {tree.error && (
             <div className="flex items-center justify-center gap-2 px-4 py-4 text-center text-xs text-[var(--muted-foreground)]" role="alert">
@@ -627,7 +631,7 @@ export function FolderFileTree({
         </OverlayScrollbar>
         {tree.loading && visibleNodes.length === 0 && !contentSized && (
           <ListSurfaceLoadingState
-            label={t('memo.fileTree.loading')}
+            ariaLabel={t('memo.fileTree.loading')}
             className="absolute inset-0 z-[2] bg-[var(--list-bg)]"
           />
         )}
diff --git a/app/flowix-web/features/memo/components/memo-card.tsx b/app/flowix-web/features/memo/components/memo-card.tsx
index 7994592bd..c4fa1e532 100644
--- a/app/flowix-web/features/memo/components/memo-card.tsx
+++ b/app/flowix-web/features/memo/components/memo-card.tsx
@@ -112,7 +112,7 @@ function AgentTodoIcons({
         // 仅在 AI 运行中展示 star-four 图标, 主色高亮。
         <span className="memo-card__running-agent-icon">
           <AgentIcon
-            typeKey={runningAgent.key}
+            typeKey={runningAgent.id}
             alt=""
             className="h-full w-full object-contain"
           />
@@ -203,7 +203,7 @@ function MemoCardShell({
     <div
       onClick={() => onSelect(memo)}
       className={cn(
-        'group memo-card relative min-w-0 w-full cursor-pointer rounded-lg px-2 transition-all',
+        'group memo-card relative min-w-0 w-full cursor-pointer rounded-lg px-2 transition-colors duration-150',
         'py-3',
         isSelected && ['bg-[var(--accent)]', 'memo-card--selected'],
       )}
diff --git a/app/flowix-web/features/memo/components/memo-create-view-options.ts b/app/flowix-web/features/memo/components/memo-create-view-options.ts
new file mode 100644
index 000000000..b08e63202
--- /dev/null
+++ b/app/flowix-web/features/memo/components/memo-create-view-options.ts
@@ -0,0 +1,9 @@
+import type { I18nKey } from '@/lib/i18n';
+import type { TableViewType } from '@features/multidimensional-table/public/create-api';
+
+export const MEMO_CREATE_VIEW_OPTIONS = [
+  { type: 'table', labelKey: 'memo.create.table' },
+  { type: 'gallery', labelKey: 'memo.create.newGallery' },
+  { type: 'kanban', labelKey: 'memo.create.newKanban' },
+  { type: 'calendar', labelKey: 'memo.create.newCalendar' },
+] as const satisfies ReadonlyArray<{ type: TableViewType; labelKey: I18nKey }>;
diff --git a/app/flowix-web/features/memo/components/memo-list-data-loader.test.tsx b/app/flowix-web/features/memo/components/memo-list-data-loader.test.tsx
index 22d518f87..dc6c21841 100644
--- a/app/flowix-web/features/memo/components/memo-list-data-loader.test.tsx
+++ b/app/flowix-web/features/memo/components/memo-list-data-loader.test.tsx
@@ -22,7 +22,7 @@ function renderLoader(overrides: Partial<ComponentProps<typeof MemoListDataLoade
     activeTagId: null,
     colorFilter: 'any',
     activePluginId: null,
-    refreshTrigger: 0,
+    memoListRefreshTrigger: 0,
     loadNotes: vi.fn().mockResolvedValue(true),
     setLoadedMemoListQueryKey: vi.fn(),
     setIsMemoListLoading: vi.fn(),
diff --git a/app/flowix-web/features/memo/components/memo-list-data-loader.tsx b/app/flowix-web/features/memo/components/memo-list-data-loader.tsx
index e17dc1419..80abf9817 100644
--- a/app/flowix-web/features/memo/components/memo-list-data-loader.tsx
+++ b/app/flowix-web/features/memo/components/memo-list-data-loader.tsx
@@ -20,7 +20,7 @@ export interface MemoListDataLoaderProps {
   colorFilter: ColorFilterValue;
   activePluginId: string | null;
   activeCustomFilterId?: string | null;
-  refreshTrigger: number;
+  memoListRefreshTrigger: number;
   loadNotes: NoteLibraryStore['loadNotes'];
   setLoadedMemoListQueryKey: (queryKey: string | null) => void;
   setIsMemoListLoading: (loading: boolean) => void;
@@ -46,7 +46,7 @@ export function MemoListDataLoader({
   colorFilter,
   activePluginId,
   activeCustomFilterId,
-  refreshTrigger,
+  memoListRefreshTrigger,
   loadNotes,
   setLoadedMemoListQueryKey,
   setIsMemoListLoading,
@@ -55,6 +55,11 @@ export function MemoListDataLoader({
   onLoadSuccess,
 }: MemoListDataLoaderProps) {
   const startupQuerySkippedRef = useRef<string | null>(null);
+  const inFlightRequestRef = useRef<{
+    fingerprint: string;
+    promise: Promise<boolean>;
+  } | null>(null);
+  const completedRequestFingerprintRef = useRef<string | null>(null);
 
   useEffect(() => {
     let cancelled = false;
@@ -89,34 +94,71 @@ export function MemoListDataLoader({
     );
     async function loadMemoListOnly() {
       onLoadStart?.(queryKey);
+      const fingerprint = JSON.stringify([queryKey, memoListRefreshTrigger]);
       // The startup orchestrator has already loaded this exact query. Mark it
       // as rendered locally without issuing a duplicate IPC request.
       if (
         initialMemoQueryKey === queryKey
         && memoListQueryKey === queryKey
-        && refreshTrigger === 0
+        && memoListRefreshTrigger === 0
         && startupQuerySkippedRef.current !== queryKey
       ) {
         startupQuerySkippedRef.current = queryKey;
+        completedRequestFingerprintRef.current = fingerprint;
         setLoadedMemoListQueryKey(queryKey);
         setIsMemoListLoading(false);
         onLoadSuccess?.(queryKey);
         return;
       }
+      // A completed list request updates memoListQueryKey, which is also an
+      // effect dependency. Remember that query revision so this state update
+      // cannot immediately issue the same request again.
+      if (completedRequestFingerprintRef.current === fingerprint) {
+        setLoadedMemoListQueryKey(queryKey);
+        setIsMemoListLoading(false);
+        return;
+      }
       setIsMemoListLoading(true);
+      let request = inFlightRequestRef.current;
+      // Effect re-entry for the exact same query revision shares its request;
+      // a newer invalidation has a different fingerprint and fetches again.
+      if (!request || request.fingerprint !== fingerprint) {
+        request = {
+          fingerprint,
+          promise: loadNotes({
+            notebookId: selectedNotebookId,
+            filter: activeFilter,
+            sort: activeSort,
+            tagId: activeTagId ?? undefined,
+            source: 'memo-list-loader',
+          }),
+        };
+        inFlightRequestRef.current = request;
+      }
       try {
-        const applied = await loadNotes({
-          notebookId: selectedNotebookId,
-          filter: activeFilter,
-          sort: activeSort,
-          tagId: activeTagId ?? undefined,
-        });
-        if (cancelled || !applied) return;
+        const applied = await request.promise;
+        if (cancelled) return;
+        if (!applied) {
+          // Another request may have loaded the same query while this one was
+          // superseded. Accept only that exact applied query; otherwise the
+          // rerendered current query owns the next readiness report.
+          if (memoListQueryKey === queryKey) {
+            completedRequestFingerprintRef.current = fingerprint;
+            setLoadedMemoListQueryKey(queryKey);
+          }
+          return;
+        }
+        completedRequestFingerprintRef.current = fingerprint;
         setLoadedMemoListQueryKey(queryKey);
         onLoadSuccess?.(queryKey);
       } catch (error) {
-        if (!cancelled) onLoadError(error);
+        if (!cancelled) {
+          onLoadError(error);
+        }
       } finally {
+        if (inFlightRequestRef.current === request) {
+          inFlightRequestRef.current = null;
+        }
         if (!cancelled) {
           setIsMemoListLoading(false);
         }
@@ -142,7 +184,7 @@ export function MemoListDataLoader({
     onLoadError,
     onLoadStart,
     onLoadSuccess,
-    refreshTrigger,
+    memoListRefreshTrigger,
     selectedNotebookId,
     setIsMemoListLoading,
     setLoadedMemoListQueryKey,
diff --git a/app/flowix-web/features/memo/components/memo-list-navigation-drawer.tsx b/app/flowix-web/features/memo/components/memo-list-navigation-drawer.tsx
index 669df8692..8d87ed5ab 100644
--- a/app/flowix-web/features/memo/components/memo-list-navigation-drawer.tsx
+++ b/app/flowix-web/features/memo/components/memo-list-navigation-drawer.tsx
@@ -90,7 +90,7 @@ export function MemoListNavigationDrawer({
       >
         <div className="relative z-[1] h-full min-h-0 flex-1 overflow-y-auto overscroll-contain px-2 pb-2">
           <div className="pt-3">
-            <div className="agent-thread-card__access-section-label">
+            <div className="agent-composer__access-section-label">
               {t('memo.navigation.notebookNavigation')}
             </div>
             <div className="space-y-0.5">
diff --git a/app/flowix-web/features/memo/components/memo-list-services-host.tsx b/app/flowix-web/features/memo/components/memo-list-services-host.tsx
index 8d5fe8d5a..533d9624a 100644
--- a/app/flowix-web/features/memo/components/memo-list-services-host.tsx
+++ b/app/flowix-web/features/memo/components/memo-list-services-host.tsx
@@ -7,14 +7,12 @@ import { useI18n, type I18nParams } from '@/lib/i18n';
 import { useShallow } from 'zustand/react/shallow';
 import {
   cloud,
-  files,
   listenToCloudStateChanges,
   mediaResources,
   notes,
   notebooks as notebooksClient,
   windows as tauriWindows,
   type CloudNotebook,
-  type NotebookSetupJob,
   type NotebookSetupReport,
 } from '@platform/tauri/client';
 import { useTauriRpc } from '@platform/tauri/use-tauri-rpc';
@@ -25,16 +23,15 @@ import {
 } from '@platform/tauri/errors';
 import { useCreateNotebookFlow } from '@features/memo/hooks/use-create-notebook-flow';
 import { useEmptyNotebookPrompt } from '@features/memo/hooks/use-empty-notebook-prompt';
-import { clearActionableNotice, upsertActionableNotice } from '@features/notifications/actionable-notice-store';
+import { clearActionableNotice, dismissActionableNotice, upsertActionableNotice } from '@features/notifications/actionable-notice-store';
 import { noteRepository, notebookRepository } from '@features/memo/services/note-repository';
 import { getVisibleCreateFilter, useNoteStore, useTagStore, type NoteListItem, type Notebook } from '@features/memo/store';
 import { noteListItemRelativePath } from '@/types/note-item';
+import { upsertNotebookSetupJob, useNotebookSetupJob } from '@features/memo/store/notebook-setup-store';
 import { getNotebookIconOption } from '@features/memo/components/notebook-icon';
 import { openNotebookNote } from '@features/memo/use-cases/open-notebook-note';
 import { clearWorkspaceDocument } from '@features/workspace/use-cases/workspace-navigation';
-import {
-  removeBrowserColumnTabsByPath,
-} from '@features/workspace/use-cases/browser-column-navigation';
+import { selectNotebook } from '@features/workspace/public/main-window-api';
 import { toast } from '@/lib/toast';
 import { cn } from '@/lib/utils';
 import { joinNotebookMemoPath } from '@/lib/path';
@@ -44,8 +41,8 @@ import { Select, SelectContent, SelectItem, SelectTrigger } from '@shared/ui/sel
 import { LazyGlobalSearchCommand } from '@features/memo/components/lazy-global-search-command';
 import { subscribe } from '@platform/tauri/event-bus';
 import { externalDocuments } from '@platform/tauri/client';
-import { openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
-import { documentIdentityFromFile, flushWorkspaceDocumentPath } from '@features/document/public/workspace-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { documentIdentityFromFile, saveWorkspaceDocumentPath } from '@features/document/public/workspace-api';
 import { ensureFileDisplayIdentity } from '@/lib/file-display-registry';
 import {
   FLOWIX_EXTERNAL_MARKDOWN_OPEN_EVENT,
@@ -62,11 +59,6 @@ function normalizeNotebookIconId(icon: string | null | undefined): string | null
   return getNotebookIconOption(icon) ? icon! : null;
 }
 
-const NOTEBOOK_DESCRIPTION_START = '<notebook-description>';
-const NOTEBOOK_DESCRIPTION_END = '</notebook-description>';
-const NOTEBOOK_DESCRIPTION_BLOCK = /<notebook-description>[\s\S]*?<\/notebook-description>/;
-const FLOWIX_MANAGED_BLOCK = /<!-- flowix:instructions:start -->[\s\S]*?<!-- flowix:instructions:end -->/;
-
 interface MediaDeleteRequest {
   filePath: string;
   notebookPath: string;
@@ -76,35 +68,6 @@ function filenameFromPath(filePath: string): string {
   return filePath.split(/[\\/]/).filter(Boolean).pop() ?? filePath;
 }
 
-function extractNotebookDescription(content: string): string {
-  const tagged = content.match(/<notebook-description>([\s\S]*?)<\/notebook-description>/);
-  if (tagged) return tagged[1].trim();
-
-  // Backward compatibility for descriptions written before the tagged block
-  // was introduced. Keep Flowix's generated instructions out of the editor.
-  return content.replace(FLOWIX_MANAGED_BLOCK, '').trim();
-}
-
-function notebookDescriptionBlock(description: string): string {
-  const normalized = description.trim();
-  return normalized
-    ? `${NOTEBOOK_DESCRIPTION_START}\n${normalized}\n${NOTEBOOK_DESCRIPTION_END}`
-    : `${NOTEBOOK_DESCRIPTION_START}\n${NOTEBOOK_DESCRIPTION_END}`;
-}
-
-function replaceNotebookDescription(existing: string, description: string): string {
-  const block = notebookDescriptionBlock(description);
-  if (NOTEBOOK_DESCRIPTION_BLOCK.test(existing)) {
-    return existing.replace(NOTEBOOK_DESCRIPTION_BLOCK, block);
-  }
-
-  // Migrate legacy untagged content into the new block. The managed Flowix
-  // section is retained outside it; all other old content was the former
-  // notebook-description field.
-  const managed = existing.match(FLOWIX_MANAGED_BLOCK)?.[0].trim() ?? '';
-  return managed ? `${managed}\n\n${block}\n` : `${block}\n`;
-}
-
 function DeleteDialogShortcuts({
   onCancel,
   onConfirm,
@@ -139,7 +102,7 @@ function BlockingOperationStatus({ text, stacked }: { text: string; stacked: boo
   return (
     <div className="pointer-events-auto fixed inset-0 z-[140] flex items-center justify-center bg-[color-mix(in_oklch,var(--card)_82%,transparent)] backdrop-blur-[1px]">
       <div className={cn('flex items-center gap-2 px-3 py-2 text-sm text-[var(--foreground)]', stacked && 'flex-col')} role="status" aria-live="polite">
-        <Loader2 className="h-4 w-4 animate-spin text-[var(--primary)]" />
+        <Loader2 className="h-4 w-4 flowix-spin text-[var(--primary)]" />
         <span>{text}</span>
       </div>
     </div>
@@ -193,8 +156,8 @@ function ExternalMarkdownOpenDialog() {
         const content = await externalDocuments.read(filePath, null);
         const created = await notes.importDocument(filePath, content, notebookId);
         imported.push(created.path);
+        useNoteStore.getState().upsertCreatedNote(created);
       }
-      await useNoteStore.getState().loadNotes({ notebookId });
       setRequest(null);
       const notebook = useNoteStore.getState().notebooks.find((item) => item.id === notebookId);
       if (notebook) await openNotebookNote(imported[imported.length - 1], notebook);
@@ -210,9 +173,9 @@ function ExternalMarkdownOpenDialog() {
     setOpening(true);
     try {
       for (const filePath of request.filePaths) {
-        await openExternalTarget(filePath, {
-          destination: 'main-third',
-          scopePath: selectedNotebook?.path ?? null,
+        await openWorkspaceSurface({
+          host: 'main-third',
+          target: { kind: 'external', path: filePath, scopePath: selectedNotebook?.path ?? null, transitionId: null },
         });
       }
       setRequest(null);
@@ -297,12 +260,14 @@ export function MemoListServicesHost({
     setNotebooks,
     setActiveFilter,
     triggerRefresh,
+    triggerMemoListRefresh,
   } = useNoteStore(
     useShallow((state) => ({
       setSelectedNotebook: state.setSelectedNotebook,
       setNotebooks: state.setNotebooks,
       setActiveFilter: state.setActiveFilter,
       triggerRefresh: state.triggerRefresh,
+      triggerMemoListRefresh: state.triggerMemoListRefresh,
     })),
   );
 
@@ -324,76 +289,54 @@ export function MemoListServicesHost({
   const [editOpen, setEditOpen] = useState(false);
   const [editName, setEditName] = useState('');
   const [editIcon, setEditIcon] = useState<string | null>(null);
-  const [editNotebookDescription, setEditNotebookDescription] = useState('');
-  const [editNotebookDescriptionDirty, setEditNotebookDescriptionDirty] = useState(false);
-  const [editNotebookDescriptionLoading, setEditNotebookDescriptionLoading] = useState(false);
   const [editCloudSync, setEditCloudSync] = useState(false);
   const [originalEditCloudSync, setOriginalEditCloudSync] = useState(false);
   const [editSaving, setEditSaving] = useState(false);
   const [cloudSyncAvailable, setCloudSyncAvailable] = useState(false);
-  const [notebookSetupJob, setNotebookSetupJob] = useState<NotebookSetupJob | null>(null);
+  const notebookSetupJob = useNotebookSetupJob(selectedNotebook?.id);
   const [notebookSetupNotice, setNotebookSetupNotice] = useState<NotebookSetupReport | null>(null);
   const [dismissedNotebookSetupKey, setDismissedNotebookSetupKey] = useState<string | null>(null);
-  const notebookSetupJobRef = useRef<NotebookSetupJob | null>(null);
+  const previousNotebookSetupJobRef = useRef(notebookSetupJob);
   const activeSetupNoticeIdRef = useRef<string | null>(null);
 
   const { creationState, createNotebook } = useCreateNotebookFlow({
     onMemoListReloadNeeded: onRefresh,
-    onMemoListQueryReset: () => undefined,
-    onMemoListLoadingChange: () => undefined,
   });
 
   useEffect(() => {
-    const notebookId = selectedNotebook?.id;
-    notebookSetupJobRef.current = null;
-    setNotebookSetupJob(null);
-    setNotebookSetupNotice(null);
     let dismissedSetupKey: string | null = null;
-    if (notebookId) {
+    if (selectedNotebook?.id) {
       try {
-        dismissedSetupKey = window.localStorage.getItem(`flowix:notebook-setup-dismissed:${notebookId}`);
+        dismissedSetupKey = window.localStorage.getItem(
+          `flowix:notebook-setup-dismissed:${selectedNotebook.id}`,
+        );
       } catch {
         // Dismissal still works for the current session without persistent storage.
       }
     }
     setDismissedNotebookSetupKey(dismissedSetupKey);
-    if (!notebookId) return;
-
-    let active = true;
-    const applyJob = (job: NotebookSetupJob) => {
-      if (!active || job.notebookId !== notebookId) return;
-      const previous = notebookSetupJobRef.current;
-      if (previous && previous.updatedAt > job.updatedAt) return;
-      if (previous?.status === 'completed' && job.status === 'running') return;
-      const justCompleted = previous?.status === 'running' && job.status === 'completed';
-      notebookSetupJobRef.current = job;
-      setNotebookSetupJob(job);
-      if (justCompleted && (job.report?.skippedExistingFiles ?? 0) > 0) {
-        setNotebookSetupNotice(job.report ?? null);
-      }
-    };
-    const unlisten = subscribe<NotebookSetupJob>('notebook-setup-status', applyJob);
+  }, [selectedNotebook?.id]);
 
-    void notebooksClient.startTemplateSetup(notebookId)
-      .then((job) => {
-        if (active && job) applyJob(job);
-      })
-      .catch((error) => {
-        if (active) console.warn('[MemoList] Failed to load notebook setup status:', error);
-      });
-
-    return () => {
-      active = false;
-      unlisten();
-    };
-  }, [onRefresh, selectedNotebook?.id]);
+  useEffect(() => {
+    const previous = previousNotebookSetupJobRef.current;
+    if (previous?.notebookId !== notebookSetupJob?.notebookId) setNotebookSetupNotice(null);
+    if (previous && notebookSetupJob
+      && previous.notebookId === notebookSetupJob.notebookId
+      && previous.jobId === notebookSetupJob.jobId
+      && previous.runId === notebookSetupJob.runId
+      && previous.status === 'running'
+      && notebookSetupJob.status === 'completed'
+      && (notebookSetupJob.report?.skippedExistingFiles ?? 0) > 0) {
+      setNotebookSetupNotice(notebookSetupJob.report);
+    }
+    previousNotebookSetupJobRef.current = notebookSetupJob;
+  }, [notebookSetupJob]);
 
   const retryNotebookSetup = useCallback(async (notebookId: string) => {
     try {
       const job = await notebooksClient.startTemplateSetup(notebookId, true);
       if (job && useNoteStore.getState().selectedNotebook?.id === notebookId) {
-        notebookSetupJobRef.current = job;
-        setNotebookSetupJob(job);
+        upsertNotebookSetupJob(job);
       }
     } catch (error) {
       throw new Error(notebookCreateErrorMessage(error, t));
@@ -401,7 +344,7 @@ export function MemoListServicesHost({
   }, [t]);
 
   const setupJobNoticeKey = notebookSetupJob
-    ? `${notebookSetupJob.notebookId}:${notebookSetupJob.updatedAt}:${notebookSetupJob.status}`
+    ? `${notebookSetupJob.jobId}:${notebookSetupJob.runId || notebookSetupJob.revision}:${notebookSetupJob.status}`
     : null;
   const notebookSetupNoticeDismissed = setupJobNoticeKey !== null
     && dismissedNotebookSetupKey === setupJobNoticeKey;
@@ -463,6 +406,30 @@ export function MemoListServicesHost({
     });
   }, [dismissNotebookSetupNotice, notebookSetupJob, notebookSetupNoticeDismissed, retryNotebookSetup, selectedNotebook?.name, t]);
 
+  useEffect(() => {
+    const job = notebookSetupJob;
+    if (!job || job.status !== 'completed' || !notebookSetupNotice
+      || notebookSetupNotice.skippedExistingFiles <= 0) return;
+    const noticeId = `notebook-setup-result:${job.notebookId}`;
+    upsertActionableNotice({
+      id: noticeId,
+      priority: 40,
+      tone: 'neutral',
+      title: t('notebook.setup.completedWithSkips', {
+        written: notebookSetupNotice.writtenFiles,
+        existing: notebookSetupNotice.skippedExistingFiles,
+      }),
+      revision: `${job.updatedAt}:${notebookSetupNotice.writtenFiles}:${notebookSetupNotice.skippedExistingFiles}`,
+      actions: [{
+        id: 'hide',
+        label: t('notebook.setup.hide'),
+        variant: 'outline',
+        run: () => dismissActionableNotice(noticeId),
+      }],
+    });
+    return () => clearActionableNotice(noticeId);
+  }, [notebookSetupJob, notebookSetupNotice, t]);
+
   useEffect(() => () => {
     if (activeSetupNoticeIdRef.current) clearActionableNotice(activeSetupNoticeIdRef.current);
   }, []);
@@ -544,44 +511,6 @@ export function MemoListServicesHost({
     };
   }, [editOpen, editingNotebook]);
 
-  useEffect(() => {
-    if (!editOpen || !editingNotebook) {
-      setEditNotebookDescription('');
-      setEditNotebookDescriptionDirty(false);
-      setEditNotebookDescriptionLoading(false);
-      return;
-    }
-
-    const agentsPath = joinNotebookMemoPath(editingNotebook.path, 'AGENTS.md');
-    if (!agentsPath) {
-      setEditNotebookDescription('');
-      setEditNotebookDescriptionDirty(false);
-      setEditNotebookDescriptionLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setEditNotebookDescriptionLoading(true);
-    void files.read(agentsPath, editingNotebook.path)
-      .then((content) => {
-        if (cancelled) return;
-        setEditNotebookDescription(extractNotebookDescription(content ?? ''));
-        setEditNotebookDescriptionDirty(false);
-      })
-      .catch(() => {
-        if (cancelled) return;
-        setEditNotebookDescription('');
-        setEditNotebookDescriptionDirty(false);
-      })
-      .finally(() => {
-        if (!cancelled) setEditNotebookDescriptionLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [editOpen, editingNotebook?.id, editingNotebook?.path]);
-
   useEffect(() => listenToCloudStateChanges((state) => {
     setCloudSyncAvailable(state.authenticated);
   }), []);
@@ -595,9 +524,6 @@ export function MemoListServicesHost({
       setEditingNotebook(notebook);
       setEditName(notebook.name);
       setEditIcon(normalizeNotebookIconId(notebook.icon));
-      setEditNotebookDescription('');
-      setEditNotebookDescriptionDirty(false);
-      setEditNotebookDescriptionLoading(true);
       setEditOpen(true);
     };
     const handleDeleteMemo = (event: Event) => {
@@ -650,21 +576,8 @@ export function MemoListServicesHost({
     if (shouldSelectNewMemo) {
       void openNotebookNote(created.path, selectedNotebook, { initialFocus: 'title' });
     }
-    void useNoteStore.getState().loadNotes({ notebookId: selectedNotebook.id, filter: createFilter })
-      .then((loaded) => {
-        if (!loaded) return;
-        const state = useNoteStore.getState();
-        if (state.selectedNotebook?.id !== selectedNotebook.id
-          || state.activeFilter !== createFilter
-          || (createFilter === 'tagged' && useTagStore.getState().selectedTagId !== tagId)) return;
-        if (!state.notes.some((note) => (
-          note.notebookId === created.notebookId && note.relativePath === created.relativePath
-        ))) state.upsertCreatedNote(created);
-      })
-      .catch((error) => {
-        console.warn('Failed to refresh note list after create', error);
-      });
-  }, [activeFilter, selectedNotebook, selectedTagId, setActiveFilter, setSelectedTagId]);
+    triggerMemoListRefresh();
+  }, [activeFilter, selectedNotebook, selectedTagId, setActiveFilter, setSelectedTagId, triggerMemoListRefresh]);
 
   useEffect(() => {
     const handleRequest = () => void handleCreateMemo();
@@ -683,12 +596,12 @@ export function MemoListServicesHost({
         ? joinNotebookMemoPath(targetNotebook.path, noteListItemRelativePath(memo))
         : null;
       if (!path) return;
-      const flushed = await flushWorkspaceDocumentPath(
+      const saved = await saveWorkspaceDocumentPath(
         documentIdentityFromFile(ensureFileDisplayIdentity(path)),
         path,
         targetNotebook?.path ?? null,
       );
-      if (flushed === false) {
+      if (!saved) {
         const status = await notes.pathStatus(path);
         if (status === 'present') {
           toast.error(t('document.save.failed', { message: '当前页签保存失败，未删除笔记' }));
@@ -696,13 +609,7 @@ export function MemoListServicesHost({
         }
       }
       const outcome = await noteRepository.delete(path);
-      removeBrowserColumnTabsByPath(path);
-      const selected = useNoteStore.getState().selectedNote;
-      if (selected?.notebookId === memo.notebookId && selected.relativePath === memo.relativePath) {
-        useNoteStore.getState().setSelectedNote(null);
-        await clearWorkspaceDocument();
-      }
-      triggerRefresh();
+      // MemoEvent or the path-deleted fallback owns list and workspace cleanup.
       if (outcome === 'missingCleaned') toast.success(t('memo.delete.missingCleaned'));
     })().catch((error) => {
       toast.error(error instanceof Error ? error.message : String(error));
@@ -775,6 +682,12 @@ export function MemoListServicesHost({
         }) ?? undefined;
       }
       if (!local) return;
+      if (useNoteStore.getState().selectedNotebook?.id !== local.id) {
+        await selectNotebook(local, { workColumnTarget: 'clear' });
+        if (useNoteStore.getState().selectedNotebook?.id !== local.id) {
+          throw new Error(t('memo.navigation.workspacePreparationFailed'));
+        }
+      }
       setCloudImporting(true);
       await cloud.linkNotebook(local.id, remote.id);
       await cloud.syncNow(local.id);
@@ -802,23 +715,19 @@ export function MemoListServicesHost({
     setEditingNotebook(null);
     setEditName('');
     setEditIcon(null);
-    setEditNotebookDescription('');
-    setEditNotebookDescriptionDirty(false);
-    setEditNotebookDescriptionLoading(false);
     setEditCloudSync(false);
     setOriginalEditCloudSync(false);
     setEditSaving(false);
   }, [editSaving]);
 
   const confirmEdit = useCallback(async () => {
-    if (!editingNotebook || editSaving || editNotebookDescriptionLoading) return;
+    if (!editingNotebook || editSaving) return;
     const name = editName.trim();
     const icon = editIcon || null;
     const iconChanged = (icon ?? '') !== (normalizeNotebookIconId(editingNotebook.icon) ?? '');
     const metadataChanged = name !== editingNotebook.name || iconChanged;
     const cloudChanged = editCloudSync !== originalEditCloudSync;
-    const descriptionChanged = editNotebookDescriptionDirty;
-    if (!name || (!metadataChanged && !cloudChanged && !descriptionChanged)) {
+    if (!name || (!metadataChanged && !cloudChanged)) {
       closeEdit();
       return;
     }
@@ -829,15 +738,6 @@ export function MemoListServicesHost({
         : editingNotebook;
       if (!updated) throw new Error(t('memo.list.updateFailed'));
       if (cloudChanged) await cloud.setNotebookEnabled(editingNotebook.id, editCloudSync);
-      if (descriptionChanged) {
-        const agentsPath = joinNotebookMemoPath(editingNotebook.path, 'AGENTS.md');
-        if (!agentsPath) throw new Error(t('notebook.edit.agents.saveFailed'));
-        const existing = (await files.read(agentsPath, editingNotebook.path)) ?? '';
-        const next = replaceNotebookDescription(existing, editNotebookDescription);
-        if (!await files.write(agentsPath, next, false, editingNotebook.path)) {
-          throw new Error(t('notebook.edit.agents.saveFailed'));
-        }
-      }
       setNotebooks(useNoteStore.getState().notebooks.map((item) => item.id === updated.id ? updated : item));
       if (useNoteStore.getState().selectedNotebook?.id === updated.id) setSelectedNotebook(updated);
       if (cloudChanged && editCloudSync) {
@@ -845,42 +745,16 @@ export function MemoListServicesHost({
           toast.error(cloudSyncErrorMessage(error, t));
         });
       }
-      toast.success(t(descriptionChanged ? 'notebook.edit.agents.saved' : 'memo.list.updated'));
+      toast.success(t('memo.list.updated'));
       closeEdit();
     } catch (error) {
       toast.error(cloudSyncErrorMessage(error, t));
       setEditSaving(false);
     }
-  }, [closeEdit, editCloudSync, editIcon, editName, editNotebookDescription, editNotebookDescriptionDirty, editNotebookDescriptionLoading, editSaving, editingNotebook, originalEditCloudSync, setNotebooks, setSelectedNotebook, t]);
+  }, [closeEdit, editCloudSync, editIcon, editName, editSaving, editingNotebook, originalEditCloudSync, setNotebooks, setSelectedNotebook, t]);
 
   return (
     <>
-      {notebookSetupJob?.status === 'running' && (
-        <div
-          className="fixed bottom-16 right-4 z-[180] flex max-w-sm items-center gap-2 rounded-xl border border-[var(--border)] bg-[var(--card)] px-4 py-3 text-sm text-[var(--foreground)] shadow-xl"
-          role="status"
-          aria-live="polite"
-        >
-          <Loader2 className="h-4 w-4 shrink-0 animate-spin text-[var(--primary)]" aria-hidden="true" />
-          <span>
-            {notebookSetupJob.stage === 'indexing'
-              ? t('notebook.setup.indexing')
-              : t('notebook.setup.applyingTemplate')}
-          </span>
-        </div>
-      )}
-      {notebookSetupNotice && (
-        <div
-          className="fixed bottom-16 right-4 z-[180] max-w-sm rounded-xl border border-[var(--border)] bg-[var(--card)] px-4 py-3 text-sm text-[var(--muted-foreground)] shadow-xl"
-          role="status"
-          aria-live="polite"
-        >
-          {t('notebook.setup.completedWithSkips', {
-            written: notebookSetupNotice.writtenFiles,
-            existing: notebookSetupNotice.skippedExistingFiles,
-          })}
-        </div>
-      )}
       <ExternalMarkdownOpenDialog />
 
       {cloudImporting && (
@@ -968,13 +842,6 @@ export function MemoListServicesHost({
             onEditNotebookNameChange={setEditName}
             editNotebookIcon={editIcon}
             onEditNotebookIconChange={setEditIcon}
-            editNotebookDescription={editNotebookDescription}
-            onEditNotebookDescriptionChange={(description) => {
-              setEditNotebookDescription(description);
-              setEditNotebookDescriptionDirty(true);
-            }}
-            editNotebookDescriptionLoading={editNotebookDescriptionLoading}
-            editNotebookDescriptionChanged={editNotebookDescriptionDirty}
             editNotebookCloudSync={editCloudSync}
             onEditNotebookCloudSyncChange={setEditCloudSync}
             onEditNotebookCloudSyncUnavailable={() => {
diff --git a/app/flowix-web/features/memo/components/memo-list.tsx b/app/flowix-web/features/memo/components/memo-list.tsx
index c0df9045e..e3821e5dd 100644
--- a/app/flowix-web/features/memo/components/memo-list.tsx
+++ b/app/flowix-web/features/memo/components/memo-list.tsx
@@ -1,7 +1,11 @@
-import { joinNotebookMemoPath } from '@/lib/path';
-import { subscribe } from '@platform/tauri/event-bus';
 'use client';
 
+import { useNotebookBackgroundStore } from '@features/memo/store/notebook-background-store';
+import { flushSync } from 'react-dom';
+import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
+import { samePath, joinNotebookMemoPath } from '@/lib/path';
+import { subscribe } from '@platform/tauri/event-bus';
+
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { useShallow } from 'zustand/react/shallow';
 import {
@@ -52,8 +56,8 @@ import {
 import { MemoListDataLoader } from '@features/memo/components/memo-list-data-loader';
 import { noteRepository } from '@features/memo/services/note-repository';
 import { initializeMainWindowStartup } from '@app/main-window-startup';
-import { clearWorkspaceDocument, openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
-import { openBrowserColumnText } from '@features/workspace/use-cases/browser-column-navigation';
+import { clearWorkspaceDocument } from '@features/workspace/use-cases/workspace-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { useI18n } from '@/lib/i18n';
 import {
   useMemoListViewPreference,
@@ -63,12 +67,13 @@ import { orderNoteTemplates } from '@/lib/note-template-order';
 import { useDocumentStore } from '@features/document/store';
 import { files as fileApi, notes as noteApi, type NoteTemplate } from '@platform/tauri/client';
 import { canonicalDirectoryPath } from '@/lib/path';
-import { AGENT_TYPES, isAgentTypeSelectable, isAlwaysVisibleNewConversationAgent } from '@/lib/agent-types';
 import type { AgentTypeKey } from '@/types/agent';
 import { AgentIcon } from '@features/agent/components/agent-icon';
 import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
-import { createAndOpenAgentConversation } from '@features/agent/public/shell-api';
-import { isAgentRuntimeInstalledState, normalizeAgentRuntimeStatus } from '@features/agent/runtime/agent-runtime-status';
+import { useNewConversationAgentSelection } from '@features/agent/hooks/use-new-conversation-agent-selection';
+import {
+  createAndOpenAgentConversation,
+} from '@features/agent/public/shell-api';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -86,24 +91,34 @@ import {
 } from './memo-list/color-filter-submenu';
 import { MemoNavigationDropdown, MemoNavigationSubmenu } from './memo-navigation-dropdown';
 import { MemoListNavigationDrawer } from './memo-list-navigation-drawer';
+import { MEMO_CREATE_VIEW_OPTIONS } from './memo-create-view-options';
 import { NotebookFolderView } from './notebook-folder-view';
 import type { NotebookNoteCreateRequest } from './notebook-file-tree';
 import { parentRelativePathForTreeCreate } from './memo-create-location';
 import { useMemoListPagination } from './memo-list/use-memo-list-pagination';
-import { useDynamicVirtualList } from '@features/memo/hooks/use-dynamic-virtual-list';
 import {
   findRunningAgentTypeForMemo,
   useRunningAgentTypeIndex,
 } from './memo-list/running-agent-index';
 const logger = createLogger('memo-list');
 
-// Keep small result sets in normal flow and virtualize larger lists.
-const MEMO_VIRTUALIZATION_THRESHOLD = 10;
-// Matches the scroller's py-2 top padding; virtual offsets include this space.
-const MEMO_LIST_TOP_PADDING_PX = 8;
-
-function EmptyState() {
+function EmptyState({ hasNotebooks }: { hasNotebooks: boolean }) {
   const { t } = useI18n();
+  if (!hasNotebooks) {
+    return (
+      <div className="flex h-full flex-col items-center justify-center gap-3 px-4 text-center text-[var(--muted-foreground)]">
+        <span className="text-sm">{t('memo.list.emptyNoNotebook')}</span>
+        <Button
+          variant="ghost"
+          size="sm"
+          className="rounded-lg border border-[var(--border)] text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+          onClick={() => window.dispatchEvent(new Event('flowix:open-create-notebook'))}
+        >
+          {t('memo.list.createNotebook')}
+        </Button>
+      </div>
+    );
+  }
   return (
     <div className="flex flex-col items-center justify-center h-full gap-2 text-[var(--muted-foreground)]">
       <span className="text-sm">{t("memo.list.emptyNotFound")}</span>
@@ -152,8 +167,8 @@ export function MemoList({
   const [showScrollTopHint, setShowScrollTopHint] = useState(false);
   const { registerCard, prepareForInsert, onListRendered } =
     useMemoInsertAnimation();
-  // 滚动容器由 OverlayScrollbar 提供。动态虚拟列表只负责在这个节点内
-  // 维护可见窗口，不接管 OverlayScrollbar 的滚动条和滚动事件。
+  // The list uses the OverlayScrollbar's native scrolling and renders its
+  // loaded rows in normal document flow.
   const listContainerRef = useRef<HTMLDivElement>(null);
   // 切片订阅: 替代原来的 `useNoteStore()` 全量订阅。每个 useStore 只取用到的字段,
   // 切到 selector 后, 列表里 5k 笔记的任何 set 都不会让本组件不必要地重渲 ──
@@ -161,6 +176,7 @@ export function MemoList({
   // store 里 setNotebooks 之类也会触发 memos selector 重跑。Zustand v5 默认
   // 用 Object.is 比对, 同一个 memos 引用相等就跳过, 不需要 useMemo。
   const notes = useNoteStore((s) => s.notes);
+  const notebooks = useNoteStore((s) => s.notebooks);
   const selectedNote = useNoteStore((s) => s.selectedNote);
   const memoListView = useMemoListViewPreference();
   const selectedNotebook = useNoteStore((s) => s.selectedNotebook);
@@ -177,8 +193,8 @@ export function MemoList({
   const [newLibraryName, setNewLibraryName] = useState('');
   const [isCreatingLibrary, setIsCreatingLibrary] = useState(false);
   const [createTemplates, setCreateTemplates] = useState<NoteTemplate[]>([]);
-  const agentRuntimeStatusByType = useAgentRuntimeStore((s) => s.statusByType);
-  const agentRuntimeIsChecking = useAgentRuntimeStore((s) => s.isChecking);
+  // A stale Zustand snapshot can survive a Vite HMR update with this field
+  // missing even though the current store initializer provides an empty map.
   const refreshAgentRuntimeIfStale = useAgentRuntimeStore((s) => s.refreshIfStale);
   const refreshTrigger = useNoteStore((s) => s.refreshTrigger);
   const activeFilter = useNoteStore((s) => s.activeFilter);
@@ -196,7 +212,12 @@ export function MemoList({
   const startupError = useNoteStore((s) => s.startupError);
   const initialMemoQueryKey = useNoteStore((s) => s.initialMemoQueryKey);
   const memoListQueryKey = useNoteStore((s) => s.memoListQueryKey);
+  const memoListRefreshTrigger = useNoteStore((s) => s.memoListRefreshTrigger);
   const selectedNotebookId = selectedNotebook?.id;
+  const handleCreateTypeMenuOpenChange = useCallback((open: boolean) => {
+    setCreateTypeMenuOpen(open);
+    if (!open) setCreateMoreMenuOpen(false);
+  }, []);
   useEffect(() => {
     const handleOpenCreateTableDialog = (event: Event) => {
       const requestEvent = event as CustomEvent<OpenCreateTableDialogRequest>;
@@ -212,14 +233,7 @@ export function MemoList({
     window.addEventListener('flowix:open-create-table-dialog', handleOpenCreateTableDialog);
     return () => window.removeEventListener('flowix:open-create-table-dialog', handleOpenCreateTableDialog);
   }, [t]);
-  const newConversationAgentTypes = AGENT_TYPES.filter((type) => {
-    if (!isAgentTypeSelectable(type.key)) return false;
-    if (isAlwaysVisibleNewConversationAgent(type.key)) return true;
-    return isAgentRuntimeInstalledState(normalizeAgentRuntimeStatus(
-      agentRuntimeStatusByType[type.key],
-      agentRuntimeIsChecking,
-    ));
-  });
+  const newConversationSelection = useNewConversationAgentSelection();
   useEffect(() => {
     if (createTypeMenuOpen && memoListView === 'folders') void refreshAgentRuntimeIfStale();
   }, [createTypeMenuOpen, memoListView, refreshAgentRuntimeIfStale]);
@@ -263,7 +277,7 @@ export function MemoList({
   const loadLibraryMetadata = useMemoLibraryMetadataStore((s) => s.loadMetadata);
   const {
     setSelectedNotebook,
-    triggerRefresh,
+    triggerMemoListRefresh,
     setActiveFilter,
     setActiveSort,
     setColorFilter,
@@ -274,7 +288,7 @@ export function MemoList({
   } = useNoteStore(
     useShallow((s) => ({
       setSelectedNotebook: s.setSelectedNotebook,
-      triggerRefresh: s.triggerRefresh,
+      triggerMemoListRefresh: s.triggerMemoListRefresh,
       setActiveFilter: s.setActiveFilter,
       setActiveSort: s.setActiveSort,
       setColorFilter: s.setColorFilter,
@@ -285,20 +299,6 @@ export function MemoList({
     })),
   );
   const listItems: NoteListItem[] = notes;
-  useEffect(() => subscribe<{ notebookId: string; relativePath: string }>(
-    'flowix:path-note-changed',
-    ({ notebookId }) => {
-      const state = useNoteStore.getState();
-      if (state.selectedNotebook?.id === notebookId) {
-        void state.loadNotes({ notebookId });
-      }
-    },
-  ), []);
-  useEffect(() => subscribe<{ notebookId: string }>('file-management-changed', ({ notebookId }) => {
-    if (useNoteStore.getState().selectedNotebook?.id === notebookId) {
-      useNoteStore.getState().triggerRefresh();
-    }
-  }), []);
   useEffect(() => subscribe<{ notebookPath: string; defaultCreateFolderChanged: boolean }>(
     'notebook-view-preferences-changed',
     ({ notebookPath, defaultCreateFolderChanged }) => {
@@ -317,9 +317,19 @@ export function MemoList({
       });
     },
   ), []);
-  const selectedListItemKey = selectedNote
-      ? `path:${selectedNote.notebookId}:${selectedNote.relativePath}`
-      : undefined;
+  const pendingDocumentPath = useWorkColumnStore((state) => {
+    const { phase, pendingTarget } = state.navigation;
+    return phase === 'loading' && pendingTarget?.kind === 'external' ? pendingTarget.path : null;
+  });
+  const pendingListItem = pendingDocumentPath && selectedNotebook?.path
+    ? notes.find((note) => samePath(
+        joinNotebookMemoPath(selectedNotebook.path, note.relativePath) ?? '',
+        pendingDocumentPath,
+      ))
+    : undefined;
+  const selectedListItemKey = pendingDocumentPath
+    ? pendingListItem ? noteListItemKey(pendingListItem) : undefined
+    : selectedNote ? `path:${selectedNote.notebookId}:${selectedNote.relativePath}` : undefined;
   const [notebookDropdownOpen, setNotebookDropdownOpen] = useState(false);
   const [isCreatingMemo, setIsCreatingMemo] = useState(false);
   const [localNavigationDrawerOpen, setLocalNavigationDrawerOpen] = useState(false);
@@ -397,6 +407,13 @@ export function MemoList({
   }, [t]);
 
   const handleMemoListLoadError = useCallback((error: unknown, requestedKind?: 'initial' | 'more') => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('NOTE_INDEX_PENDING')) {
+      const id = useNoteStore.getState().selectedNotebook?.id;
+      if (id) useNotebookBackgroundStore.getState().pending(id);
+      setMemoListError(null);
+      return;
+    }
     logger.warn('load memos failed', { error });
     const state = useNoteStore.getState();
     const queryKey = getMemoListQueryKey(
@@ -438,8 +455,8 @@ export function MemoList({
 
   const handleRetryMemoList = useCallback(() => {
     setMemoListError(null);
-    triggerRefresh();
-  }, [triggerRefresh]);
+    triggerMemoListRefresh();
+  }, [triggerMemoListRefresh]);
 
   const handleRetryMemoListMore = useCallback(() => {
     setMemoListError(null);
@@ -486,7 +503,7 @@ export function MemoList({
     void loadData().catch((error) => {
       if (!isActiveRef.current) return;
       logger.warn('load list metadata failed', { error });
-      toast.error(t('memo.list.loadFailed'));
+      if (!String(error).includes('NOTE_INDEX_PENDING')) toast.error(t('memo.list.loadFailed'));
     });
   }, [isActive, loadData, refreshTrigger, selectedNotebookId, t]);
 
@@ -504,7 +521,23 @@ export function MemoList({
     : null;
   const hasCurrentMemoListData = loadedMemoListQueryKey === currentMemoListQueryKey
     || memoListQueryKey === currentMemoListQueryKey;
-  const showMemoListLoading = startupPhase === 'loading' || shouldShowMemoListLoading({
+  const backgroundIndex = useNotebookBackgroundStore((state) => selectedNotebookId ? state.statuses[selectedNotebookId] : undefined);
+  const indexPreparing = backgroundIndex?.state === 'queued' || backgroundIndex?.state === 'running';
+  const indexFailed = backgroundIndex?.state === 'failed';
+  useEffect(() => {
+    if (backgroundIndex?.state === 'ready') setMemoListError(null);
+  }, [backgroundIndex?.state, backgroundIndex?.revision, selectedNotebookId]);
+  const retryIndexOrList = () => {
+    if (!selectedNotebookId || !indexFailed) { handleRetryMemoList(); return; }
+    const id = selectedNotebookId;
+    useNotebookBackgroundStore.getState().pending(id, true);
+    void import('@platform/tauri/client/memos').then(({ notebooks }) => notebooks.refreshIndex(id)).catch((error) => {
+      const current = useNotebookBackgroundStore.getState().statuses[id];
+      if (current) useNotebookBackgroundStore.getState().apply({ ...current, state: 'failed', message: String(error) });
+    });
+  };
+
+  const showMemoListLoading = indexPreparing || startupPhase === 'loading' || shouldShowMemoListLoading({
       selectedNotebookId,
       isMemoListLoading,
       currentMemoListQueryKey,
@@ -596,62 +629,20 @@ export function MemoList({
       toast.error(t('memo.fileTree.preferenceSaveFailed'));
     }
   }, [defaultCreateFolder, selectedNotebook, t]);
-  const memoVirtualizationEnabled =
-    filteredMemos.length > MEMO_VIRTUALIZATION_THRESHOLD;
-  // ResizeObserver is required for dynamic rows. Older/non-browser test
-  // environments gracefully keep the existing document-flow renderer.
-  const canVirtualizeMemos =
-    memoVirtualizationEnabled && typeof ResizeObserver !== 'undefined';
-  const getMemoKey = useCallback((memo: NoteListItem) => noteListItemKey(memo), []);
-  const estimateMemoSize = useCallback(
-    (memo: NoteListItem) => memo.thumbnail ? 208 : 136,
-    [],
-  );
-  const {
-    totalSize: virtualListTotalSize,
-    virtualItems,
-    getMeasureRef,
-    isVirtualizationReady,
-  } = useDynamicVirtualList({
-    items: filteredMemos,
-    getKey: getMemoKey,
-    estimateSize: estimateMemoSize,
-    scrollerRef: listContainerRef,
-    enabled: canVirtualizeMemos,
-    resetKey: currentMemoListQueryKey,
-    scrollMargin: MEMO_LIST_TOP_PADDING_PX,
-  });
-  // Selection lives in the store; virtualized rows do not need to stay mounted
-  // after scrolling out of view.
-  const shouldVirtualizeMemos = canVirtualizeMemos && isVirtualizationReady;
-
-  // Keep one stable row ref per key for both entry animation and measurement.
-  const rowRefCacheRef = useRef<
-    Map<string, (el: HTMLDivElement | null) => void>
-  >(new Map());
-  const registerCardRef = useRef(registerCard);
-  registerCardRef.current = registerCard;
-  const getMemoRowRef = (id: string) => {
-    const cached = rowRefCacheRef.current.get(id);
-    if (cached) return cached;
-    const measureRef = getMeasureRef(id);
-    const cb = (el: HTMLDivElement | null) => {
-      registerCardRef.current(id)(el);
-      measureRef(el);
-      if (!el) rowRefCacheRef.current.delete(id);
-    };
-    rowRefCacheRef.current.set(id, cb);
-    return cb;
-  };
   const handleSelectMemo = useCallback((memo: NoteListItem) => {
-    void openPathNoteSession(memo, useNoteStore.getState().selectedNotebook);
+    flushSync(() => {
+      void openPathNoteSession(memo, useNoteStore.getState().selectedNotebook);
+    });
   }, []);
 
   const handleOpenMemoWindow = useCallback((memo: NoteListItem) => {
     const notebook = useNoteStore.getState().selectedNotebook;
     if (!notebook?.path) return;
     const path = joinNotebookMemoPath(notebook.path, memo.relativePath) ?? memo.relativePath;
-    const open = openBrowserColumnText(path, notebook.path);
+    const open = openWorkspaceSurface({
+      host: 'browser-column',
+      target: { kind: 'external', path, scopePath: notebook.path, transitionId: null },
+    });
     void open
       .catch((error) => {
         logger.warn('open memo in browser column failed', {
@@ -684,7 +675,6 @@ export function MemoList({
           notes: state.notes.filter((item) =>
             item.notebookId !== memo.notebookId || item.relativePath !== memo.relativePath),
         }));
-        triggerRefresh();
         toast.success(t('memo.favorite.missingCleaned'));
         return;
       }
@@ -692,11 +682,10 @@ export function MemoList({
         ...memo,
         favorited: !memo.favorited,
       });
-      triggerRefresh();
     } catch (error) {
       toast.error(error instanceof Error ? error.message : String(error));
     }
-  }, [t, triggerRefresh]);
+  }, [t]);
 
   const handleColorsChange = useCallback(async (memo: NoteListItem, colors: NoteColor[]) => {
     const path = joinNotebookMemoPath(
@@ -705,34 +694,33 @@ export function MemoList({
     ) ?? '';
     const saved = await noteRepository.setColors(path, colors);
     if (!saved) {
-      triggerRefresh();
+      triggerMemoListRefresh();
       return;
     }
     useNoteStore.getState().updateMemoListItem({ ...memo, colors });
-    triggerRefresh();
-  }, [triggerRefresh]);
+  }, [triggerMemoListRefresh]);
 
-  // JSX keeps data-index in sync when keyed rows change position.
-  const renderMemoRow = (memo: NoteListItem, start?: number, index?: number) => {
+  const cardRefCacheRef = useRef(new Map<string, (element: HTMLDivElement | null) => void>());
+  const registerCardRef = useRef(registerCard);
+  registerCardRef.current = registerCard;
+  const getMemoCardRef = (key: string) => {
+    const cached = cardRefCacheRef.current.get(key);
+    if (cached) return cached;
+    const ref = (element: HTMLDivElement | null) => {
+      registerCardRef.current(key)(element);
+      if (!element) cardRefCacheRef.current.delete(key);
+    };
+    cardRefCacheRef.current.set(key, ref);
+    return ref;
+  };
+
+  const renderMemoRow = (memo: NoteListItem) => {
     const itemKey = noteListItemKey(memo);
-    const rowRef = getMemoRowRef(itemKey);
-    const isVirtualRow = start !== undefined;
     return (
       <div
         key={itemKey}
-        ref={rowRef}
-        data-index={index}
+        ref={getMemoCardRef(itemKey)}
         className="min-w-0 w-full"
-        style={
-          isVirtualRow
-            ? {
-                position: 'absolute',
-                top: start,
-                left: 0,
-                right: 0,
-              }
-            : undefined
-        }
       >
         <div data-insert-anim className="min-w-0 w-full">
           <MemoCard
@@ -752,9 +740,7 @@ export function MemoList({
     );
   };
 
-  const renderedMemoRows = shouldVirtualizeMemos
-    ? virtualItems.map(({ item, start, index }) => renderMemoRow(item, start, index))
-    : filteredMemos.map((memo, index) => renderMemoRow(memo, undefined, index));
+  const renderedMemoRows = filteredMemos.map(renderMemoRow);
 
   const handleFilterChange = (filter: typeof activeFilter) => {
     if (filter !== 'tagged') {
@@ -872,21 +858,8 @@ export function MemoList({
     const opening = shouldSelectNewMemo
       ? openNotebookNote(result.path, selectedNotebook, { initialFocus: 'title' })
       : null;
-    void loadNotes({ notebookId: selectedNotebook.id, filter: createFilter })
-      .then((loaded) => {
-        if (!loaded) return;
-        const state = useNoteStore.getState();
-        if (state.selectedNotebook?.id !== selectedNotebook.id
-          || state.activeFilter !== createFilter
-          || state.activeCustomFilterId !== activeCustomFilterId
-          || (createFilter === 'tagged' && useTagStore.getState().selectedTagId !== activeTagId)) return;
-        if (!state.notes.some((note) => (
-          note.notebookId === result.notebookId && note.relativePath === result.relativePath
-        ))) state.upsertCreatedNote(result);
-      })
-      .catch((error) => {
-        logger.warn('refresh note list after create failed', { error, notebookId: selectedNotebook.id });
-      });
+    // The document save emits a path invalidation after applying custom-view
+    // properties; the shared list query subscriber reloads this projection.
     if (opening) await opening;
     } finally { setIsCreatingMemo(false); }
   }, [
@@ -895,7 +868,6 @@ export function MemoList({
     activeCustomFilter,
     activeCustomFilterId,
     loadNotebookFilters,
-    loadNotes,
     prepareForInsert,
     memoListView,
     selectedNotebook,
@@ -948,16 +920,20 @@ export function MemoList({
       if (!view) throw new Error('新建多维表格没有可用视图');
       await onCreated?.({ relativePath: created.relativePath, collectionId: created.table.collection.id, viewId: view.id });
       setNewTableDialogOpen(false);
-      setCreateTypeMenuOpen(false);
+      handleCreateTypeMenuOpenChange(false);
       setCreateTableDialogNotebookId(null);
       createTableOnCreatedRef.current = null;
-      await openExternalTarget(created.filePath, { scopePath: targetNotebook.path, notebookId: targetNotebook.id, destination: 'main-third' });
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'external', path: created.filePath, scopePath: targetNotebook.path, transitionId: null },
+        options: { notebookId: targetNotebook.id },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : '创建多维表格失败');
     } finally {
       setIsCreatingTable(false);
     }
-  }, [createTableDialogNotebookId, defaultCreateFolder, defaultCreateFolderReady, isCreatingTable, newTableName, newTableViewType, selectedNotebook]);
+  }, [createTableDialogNotebookId, defaultCreateFolder, defaultCreateFolderReady, handleCreateTypeMenuOpenChange, isCreatingTable, newTableName, newTableViewType, selectedNotebook]);
 
   const handleCreateMediaLibrary = useCallback(async () => {
     if (!selectedNotebook || isCreatingLibrary) return;
@@ -968,14 +944,18 @@ export function MemoList({
         : (await fileApi.getNotebookViewPreferences(selectedNotebook.path)).defaultCreateFolder ?? undefined;
       const { filePath } = await createMediaLibraryFile(selectedNotebook.path, parentRelativePath, newLibraryName);
       setNewLibraryDialogOpen(false);
-      setCreateTypeMenuOpen(false);
-      await openExternalTarget(filePath, { scopePath: selectedNotebook.path, notebookId: selectedNotebook.id, destination: 'main-third' });
+      handleCreateTypeMenuOpenChange(false);
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'external', path: filePath, scopePath: selectedNotebook.path, transitionId: null },
+        options: { notebookId: selectedNotebook.id },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : '创建媒体库失败');
     } finally {
       setIsCreatingLibrary(false);
     }
-  }, [defaultCreateFolder, defaultCreateFolderReady, isCreatingLibrary, newLibraryName, selectedNotebook]);
+  }, [defaultCreateFolder, defaultCreateFolderReady, handleCreateTypeMenuOpenChange, isCreatingLibrary, newLibraryName, selectedNotebook]);
 
   const handleCreateAgentConversation = useCallback((typeKey: AgentTypeKey) => {
     if (!selectedNotebookId) return;
@@ -986,14 +966,14 @@ export function MemoList({
     if (!selectedNotebook) return;
     try {
       const created = await noteApi.createFromTemplate(templateId, selectedNotebook.id);
-      await useNoteStore.getState().loadNotes({ notebookId: selectedNotebook.id });
-      setCreateTypeMenuOpen(false);
+      useNoteStore.getState().upsertCreatedNote(created);
+      handleCreateTypeMenuOpenChange(false);
       await openNotebookNote(created.path, selectedNotebook);
     } catch (error) {
       logger.error('create note from template failed', { error, templateId, notebookId: selectedNotebook.id });
       toast.error(error instanceof Error ? error.message : t('memo.create.templateFailed'));
     }
-  }, [selectedNotebook, t]);
+  }, [handleCreateTypeMenuOpenChange, selectedNotebook, t]);
 
   const handleCreateFolder = useCallback(() => {
     if (!selectedNotebook) return;
@@ -1057,97 +1037,81 @@ export function MemoList({
           <span className="min-w-0 truncate">{template.name}</span>
         </DropdownMenuItem>
       ))}
-      <MemoNavigationSubmenu
-        label={t('memo.fileTree.viewsSectionTitle')}
-        icon={<MoreHorizontal className="h-4 w-4" aria-hidden="true" />}
-        open={createMoreMenuOpen}
-        onOpenChange={setCreateMoreMenuOpen}
-        emptyText=""
-        loadingText=""
-        hideHeader
-        onCloseMenu={() => setCreateTypeMenuOpen(false)}
-        submenuClassName="w-[176px]"
-        submenuContent={(
-          <div className="flex flex-col gap-0.5">
-            {([
-              { type: 'table' as const, label: t('memo.create.table') },
-              { type: 'gallery' as const, label: t('memo.create.newGallery') },
-              { type: 'kanban' as const, label: t('memo.create.newKanban') },
-              { type: 'calendar' as const, label: t('memo.create.newCalendar') },
-            ]).map(({ type, label }) => (
+      {memoListView === 'folders' && (
+        <MemoNavigationSubmenu
+          label={t('memo.create.newView')}
+          icon={<MoreHorizontal className="h-4 w-4" aria-hidden="true" />}
+          open={createMoreMenuOpen}
+          onOpenChange={setCreateMoreMenuOpen}
+          emptyText=""
+          loadingText=""
+          hideHeader
+          onCloseMenu={() => handleCreateTypeMenuOpenChange(false)}
+          submenuClassName="w-[176px]"
+          submenuContent={(
+            <div className="flex flex-col gap-0.5">
+              {MEMO_CREATE_VIEW_OPTIONS.map(({ type, labelKey }) => (
+                <button
+                  key={type}
+                  type="button"
+                  disabled={!selectedNotebook}
+                  className="memo-navigation-submenu-item mention-note-item !h-7 !min-h-7 !rounded-lg !py-0 !pl-[6px] !pr-2 hover:bg-[var(--brand)] focus-visible:bg-[var(--brand)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+                  onMouseDown={(event) => event.preventDefault()}
+                  onClick={() => {
+                    setNewTableViewType(type);
+                    setNewTableName(getTableDefaultName(type));
+                    setCreateTableDialogNotebookId(null);
+                    createTableOnCreatedRef.current = null;
+                    handleCreateTypeMenuOpenChange(false);
+                    setNewTableDialogOpen(true);
+                  }}
+                >
+                  <span className="flex min-w-0 items-center gap-2">
+                    {type === 'table' ? <Table2 className="h-4 w-4 shrink-0" aria-hidden="true" /> : <span className="h-4 w-4 shrink-0" aria-hidden="true" />}
+                    <span className="mention-note-title">{t(labelKey)}</span>
+                  </span>
+                  <span className="mention-note-notebook opacity-50">{t('memo.create.note')}</span>
+                </button>
+              ))}
               <button
-                key={type}
                 type="button"
-                disabled={!selectedNotebook}
+                disabled={!selectedNotebook || isCreatingLibrary}
                 className="memo-navigation-submenu-item mention-note-item !h-7 !min-h-7 !rounded-lg !py-0 !pl-[6px] !pr-2 hover:bg-[var(--brand)] focus-visible:bg-[var(--brand)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
                 onMouseDown={(event) => event.preventDefault()}
                 onClick={() => {
-                  setNewTableViewType(type);
-                  setNewTableName(getTableDefaultName(type));
-                  setCreateTableDialogNotebookId(null);
-                  createTableOnCreatedRef.current = null;
-                  setCreateMoreMenuOpen(false);
-                  setCreateTypeMenuOpen(false);
-                  setNewTableDialogOpen(true);
+                  setNewLibraryName(t('memo.create.mediaLibraryDefaultName'));
+                  handleCreateTypeMenuOpenChange(false);
+                  setNewLibraryDialogOpen(true);
                 }}
               >
                 <span className="flex min-w-0 items-center gap-2">
-                  {type === 'table' ? <Table2 className="h-4 w-4 shrink-0" aria-hidden="true" /> : <span className="h-4 w-4 shrink-0" aria-hidden="true" />}
-                  <span className="mention-note-title">{label}</span>
+                  <GalleryHorizontalEnd className="h-4 w-4 shrink-0" aria-hidden="true" />
+                  <span className="mention-note-title">{t('memo.create.mediaLibrary')}</span>
                 </span>
-                <span className="mention-note-notebook opacity-50">{t('memo.create.note')}</span>
+                <span className="mention-note-notebook opacity-50">{t('memo.create.mediaImageShort')}/{t('memo.create.mediaVideoShort')}</span>
               </button>
-            ))}
-            <button
-              type="button"
-              disabled={!selectedNotebook || isCreatingLibrary}
-              className="memo-navigation-submenu-item mention-note-item !h-7 !min-h-7 !rounded-lg !py-0 !pl-[6px] !pr-2 hover:bg-[var(--brand)] focus-visible:bg-[var(--brand)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
-              onMouseDown={(event) => event.preventDefault()}
-              onClick={() => {
-                setNewLibraryName(t('memo.create.mediaLibraryDefaultName'));
-                setCreateMoreMenuOpen(false);
-                setCreateTypeMenuOpen(false);
-                setNewLibraryDialogOpen(true);
-              }}
-            >
-              <span className="flex min-w-0 items-center gap-2">
-                <GalleryHorizontalEnd className="h-4 w-4 shrink-0" aria-hidden="true" />
-                <span className="mention-note-title">{t('memo.create.mediaLibrary')}</span>
-              </span>
-              <span className="mention-note-notebook opacity-50">{t('memo.create.mediaImageShort')}/{t('memo.create.mediaVideoShort')}</span>
-            </button>
-          </div>
-        )}
-      />
-      {memoListView === 'folders' && (
+            </div>
+          )}
+        />
+      )}
+      {memoListView === 'folders' && newConversationSelection.options.length > 0 && (
         <>
           <DropdownMenuLabel className="px-[0.375rem] pb-[0.35rem] pt-[0.35rem] text-xs font-normal leading-[1.2] text-[var(--muted-foreground)]">
             {t('memo.create.conversations')}
           </DropdownMenuLabel>
-          {newConversationAgentTypes.map((type) => {
-            const runtimeStatus = normalizeAgentRuntimeStatus(
-              agentRuntimeStatusByType[type.key],
-              agentRuntimeIsChecking,
-            );
-            const showNotInstalled = isAlwaysVisibleNewConversationAgent(type.key)
-              && runtimeStatus.state === 'not-installed';
+          {newConversationSelection.options.map((type) => {
             const name = type.nameKey
               ? t(type.nameKey as Parameters<typeof t>[0])
               : type.name;
             return (
               <DropdownMenuItem
-                key={type.key}
+                key={type.id}
                 disabled={!selectedNotebook}
-                onClick={() => handleCreateAgentConversation(type.key)}
+                onClick={() => handleCreateAgentConversation(type.id)}
                 className="agent-conversation-new-agent-item group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
               >
-                <AgentIcon typeKey={type.key} alt="" className="h-4 w-4 shrink-0 object-contain" />
+                <AgentIcon typeKey={type.id} alt="" className="h-4 w-4 shrink-0 object-contain" />
                 <span className="min-w-0 flex-1 truncate">{name}</span>
-                {showNotInstalled && (
-                  <span className="shrink-0 text-xs text-[var(--muted-foreground)] group-hover:text-[var(--primary-foreground)]">
-                    {t('agent.status.notInstalled')}
-                  </span>
-                )}
               </DropdownMenuItem>
             );
           })}
@@ -1169,7 +1133,7 @@ export function MemoList({
         colorFilter={colorFilter}
         activePluginId={activePluginId}
         activeCustomFilterId={activeCustomFilterId}
-        refreshTrigger={refreshTrigger}
+        memoListRefreshTrigger={memoListRefreshTrigger}
         loadNotes={loadNotes}
         setLoadedMemoListQueryKey={setLoadedMemoListQueryKey}
         setIsMemoListLoading={setIsMemoListLoading}
@@ -1344,11 +1308,11 @@ export function MemoList({
                   className="h-[30px] w-[25px] justify-start rounded-none border-0 bg-transparent pl-[7px] pr-[2px] text-[var(--primary-foreground)] hover:bg-white/10"
                 >
                   {isCreatingMemo || isCreatingTable
-                    ? <Loader2 className="h-4 w-4 animate-spin" aria-hidden="true" />
+                    ? <Loader2 className="h-4 w-4 flowix-spin" aria-hidden="true" />
                     : <SquarePen className="h-4 w-4" aria-hidden="true" />}
                 </Button>
               </Tooltip>
-              <DropdownMenu open={createTypeMenuOpen} onOpenChange={setCreateTypeMenuOpen}>
+              <DropdownMenu open={createTypeMenuOpen} onOpenChange={handleCreateTypeMenuOpenChange}>
                 <Tooltip content={t('memo.create.chooseType')}>
                   <DropdownMenuTrigger asChild>
                     <Button
@@ -1366,7 +1330,7 @@ export function MemoList({
               </DropdownMenu>
             </div>
           ) : (
-            <DropdownMenu open={createTypeMenuOpen} onOpenChange={setCreateTypeMenuOpen}>
+            <DropdownMenu open={createTypeMenuOpen} onOpenChange={handleCreateTypeMenuOpenChange}>
               <Tooltip content={t('memo.create.chooseType')} shortcut="memo.create">
                 <DropdownMenuTrigger asChild>
                   <Button
@@ -1377,7 +1341,7 @@ export function MemoList({
                     className="h-[30px] w-[30px] justify-center rounded-xl border border-transparent bg-[var(--primary)] p-0 text-[var(--primary-foreground)] hover:opacity-90"
                   >
                     {isCreatingMemo || isCreatingTable
-                      ? <Loader2 className="h-4 w-4 animate-spin" aria-hidden="true" />
+                      ? <Loader2 className="h-4 w-4 flowix-spin" aria-hidden="true" />
                       : <SquarePen className="h-4 w-4" aria-hidden="true" />}
                   </Button>
                 </DropdownMenuTrigger>
@@ -1465,7 +1429,7 @@ export function MemoList({
     )}
         {(startupPhase === 'idle' || startupPhase === 'loading') && (
           <ListSurfaceLoadingState
-            label={t('memo.list.loadingNotebook')}
+            ariaLabel={t('memo.list.loadingNotebook')}
             className="absolute inset-0 z-20 bg-[var(--card)]/80"
           />
         )}
@@ -1482,14 +1446,14 @@ export function MemoList({
               onCreateFolder={handleCreateFolder}
               defaultCreateFolder={defaultCreateFolder}
               onSetDefaultCreateFolder={(folderPath) => { void handleSetDefaultCreateFolder(folderPath); }}
-              isActive={isActive && dataLoadingEnabled && showFolderView}
+              isActive={isActive && dataLoadingEnabled && showFolderView && defaultCreateFolderReady}
               onCreateNote={handleCreateNoteInFolder}
             />
           </div>
         )}
         {foldersMounted && selectedNotebook && showFolderView && !defaultCreateFolderReady && (
           <ListSurfaceLoadingState
-            label={t('memo.list.loadingNotebook')}
+            ariaLabel={t('memo.list.loadingNotebook')}
             className="absolute inset-0 z-10 bg-[var(--card)]/80"
           />
         )}
@@ -1506,32 +1470,31 @@ export function MemoList({
               handleMemoListScroll(event);
             }}
           >
-            {currentMemoListError?.kind === 'initial' ? (
+            {currentMemoListError?.kind === 'initial' || (!hasCurrentMemoListData && indexFailed) ? (
               <div className="flex h-full min-h-0 w-full flex-col items-center justify-center gap-3 px-4 text-center" role="alert">
                 <span className="text-sm text-[var(--muted-foreground)]">{t('memo.list.loadFailed')}</span>
-                <Button size="sm" className="rounded-lg" onClick={handleRetryMemoList}>{t('error.retry')}</Button>
+                <Button size="sm" className="rounded-lg" onClick={retryIndexOrList}>{t('error.retry')}</Button>
               </div>
             ) : !hasCurrentMemoListData && showMemoListLoading ? (
-              <ListSurfaceLoadingState label={t('memo.list.loadingLibrary')} />
+              <ListSurfaceLoadingState ariaLabel={t('memo.list.loadingLibrary')} />
             ) : filteredMemos.length > 0 ? (
               <div
-                className={cn(
-                  'relative min-w-0 w-full',
-                  !shouldVirtualizeMemos && 'flex flex-col',
-                )}
-                style={
-                  shouldVirtualizeMemos
-                    ? {
-                        height: virtualListTotalSize,
-                        overflowAnchor: 'none',
-                      }
-                    : undefined
-                }
+                className="flex min-w-0 w-full flex-col"
               >
                 {renderedMemoRows}
               </div>
             ) : (
-              <EmptyState />
+              <EmptyState hasNotebooks={notebooks.length > 0} />
+            )}
+            {memoListLoadingMore && filteredMemos.length > 0 && (
+              <div
+                className="flex h-10 items-center justify-center gap-2 text-xs text-[var(--muted-foreground)]"
+                role="status"
+                aria-live="polite"
+              >
+                <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" />
+                <span>{t('memo.list.loadingMore')}</span>
+              </div>
             )}
             {currentMemoListError?.kind === 'more' && (
               <div className="flex items-center justify-center gap-2 px-4 py-3 text-center text-xs text-[var(--muted-foreground)]" role="alert">
@@ -1539,10 +1502,10 @@ export function MemoList({
                 <Button size="sm" className="rounded-lg" onClick={handleRetryMemoListMore}>{t('error.retry')}</Button>
               </div>
             )}
-            {currentMemoListError?.kind === 'refresh' && (
+            {(currentMemoListError?.kind === 'refresh' || (hasCurrentMemoListData && indexFailed)) && (
               <div className="flex items-center justify-center gap-2 px-4 py-3 text-center text-xs text-[var(--muted-foreground)]" role="alert">
                 <span>{t('memo.list.loadFailed')}</span>
-                <Button size="sm" className="rounded-lg" onClick={handleRetryMemoList}>{t('error.retry')}</Button>
+                <Button size="sm" className="rounded-lg" onClick={retryIndexOrList}>{t('error.retry')}</Button>
               </div>
             )}
           </OverlayScrollbar>
diff --git a/app/flowix-web/features/memo/components/memo-list/running-agent-index.test.ts b/app/flowix-web/features/memo/components/memo-list/running-agent-index.test.ts
index 11d0b843b..b976f8404 100644
--- a/app/flowix-web/features/memo/components/memo-list/running-agent-index.test.ts
+++ b/app/flowix-web/features/memo/components/memo-list/running-agent-index.test.ts
@@ -23,9 +23,8 @@ function instance(
   };
 }
 
-function memo(input: Partial<Pick<MemoItem, 'id' | 'agents'>> = {}): Pick<MemoItem, 'id' | 'agents'> {
+function memo(input: Partial<Pick<MemoItem, 'agents'>> = {}): Pick<MemoItem, 'agents'> {
   return {
-    id: 'memo-1',
     agents: [],
     ...input,
   };
@@ -41,7 +40,7 @@ describe('running agent index', () => {
 
     expect(findRunningAgentForMemo(index, memo())).toBeNull();
     expect(
-      findRunningAgentForMemo(index, memo({ id: 'memo-2', agents: [
+      findRunningAgentForMemo(index, memo({ agents: [
         { threadId: 'thread-1', title: 'Thread', agentType: 'codex' },
       ] })),
     ).toBe(byThread);
@@ -69,13 +68,13 @@ describe('running agent index', () => {
     const byThread = instance({
       instanceId: 'by-thread',
       threadId: 'thread-1',
-      agentType: 'deepseek-harness',
+      agentType: 'dsh',
     });
     const index = buildRunningAgentTypeIndex([byThread]);
 
     expect(findRunningAgentTypeForMemo(index, memo({
       agents: [{ threadId: 'thread-1', title: 'Thread', agentType: 'codex' }],
-    }))).toBe('deepseek-harness');
-    expect(findRunningAgentTypeForMemo(index, memo({ id: 'memo-2' }))).toBeNull();
+    }))).toBe('dsh');
+    expect(findRunningAgentTypeForMemo(index, memo())).toBeNull();
   });
 });
diff --git a/app/flowix-web/features/memo/components/memo-list/running-agent-index.ts b/app/flowix-web/features/memo/components/memo-list/running-agent-index.ts
index 641260758..ccafc3fbd 100644
--- a/app/flowix-web/features/memo/components/memo-list/running-agent-index.ts
+++ b/app/flowix-web/features/memo/components/memo-list/running-agent-index.ts
@@ -176,7 +176,7 @@ export function useRunningAgentTypeIndex(): RunningAgentTypeIndex {
 
 export function findRunningAgentForMemo(
   index: RunningAgentIndex,
-  memo: Pick<MemoItem, 'id' | 'agents'>,
+  memo: Pick<MemoItem, 'agents'>,
 ): AgentConversationInstance | null {
   let match: RankedAgent | undefined;
 
@@ -192,7 +192,7 @@ export function findRunningAgentForMemo(
 
 export function findRunningAgentTypeForMemo(
   index: RunningAgentTypeIndex,
-  memo: Pick<MemoItem, 'agents'> & { id?: string },
+  memo: Pick<MemoItem, 'agents'>,
 ): AgentConversationInstance['agentType'] | null {
   let match: RunningAgentTypeMatch | null = null;
 
diff --git a/app/flowix-web/features/memo/components/memo-list/use-memo-list-pagination.ts b/app/flowix-web/features/memo/components/memo-list/use-memo-list-pagination.ts
index 1d403aabc..5404cdff1 100644
--- a/app/flowix-web/features/memo/components/memo-list/use-memo-list-pagination.ts
+++ b/app/flowix-web/features/memo/components/memo-list/use-memo-list-pagination.ts
@@ -3,7 +3,8 @@ import { useCallback, useLayoutEffect, useMemo, type RefObject, type UIEvent } f
 import type { ColorFilterValue } from '@features/memo/store/note-store';
 import type { NoteListItem } from '@/types/note-item';
 
-const LOAD_MORE_THRESHOLD_PX = 720;
+const MIN_LOAD_MORE_THRESHOLD_PX = 720;
+const LOAD_MORE_VIEWPORT_MULTIPLIER = 2;
 
 interface MemoListPaginationOptions {
   memos: NoteListItem[];
@@ -39,7 +40,14 @@ export function useMemoListPagination({
   const loadWhenNearEnd = useCallback((scroller: HTMLDivElement | null) => {
     if (!isActive || loading || loadingMorePages || !hasMorePages || !scroller) return;
     const distanceToBottom = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight;
-    if (distanceToBottom <= LOAD_MORE_THRESHOLD_PX) loadMorePages();
+    // Start fetching well before the user reaches the current page boundary.
+    // Two viewports gives the backend time to respond during a fast fling,
+    // while the floor preserves the previous buffer for short list panes.
+    const threshold = Math.max(
+      MIN_LOAD_MORE_THRESHOLD_PX,
+      scroller.clientHeight * LOAD_MORE_VIEWPORT_MULTIPLIER,
+    );
+    if (distanceToBottom <= threshold) loadMorePages();
   }, [hasMorePages, isActive, loadMorePages, loading, loadingMorePages]);
 
   const onScroll = useCallback((event: UIEvent<HTMLDivElement>) => {
diff --git a/app/flowix-web/features/memo/components/notebook-access-files-list.test.ts b/app/flowix-web/features/memo/components/notebook-access-files-list.test.ts
index fc8e3da6a..0edd99d2a 100644
--- a/app/flowix-web/features/memo/components/notebook-access-files-list.test.ts
+++ b/app/flowix-web/features/memo/components/notebook-access-files-list.test.ts
@@ -1,10 +1,10 @@
 import { act, createElement, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { useAgentAccessStore } from "@features/agent/store/agent-access-store";
+import { useAgentWorkspaceStore, type AgentWorkspaceState } from "@features/agent/store/agent-workspace-store";
 import { NotebookAccessFilesList } from "@features/memo/components/notebook-access-files-list";
 import type { Notebook } from "@features/memo/store/note-store";
-import type { AgentAccessConfig, AgentAccessEntry } from "@/lib/types/agent-access";
+import type { AgentAccessEntry } from "@/lib/types/agent-workspace.test-support";
 
 const toastMock = vi.hoisted(() => ({ success: vi.fn(), error: vi.fn(), info: vi.fn() }));
 vi.mock("@/lib/toast", () => ({ toast: toastMock }));
@@ -20,23 +20,33 @@ vi.mock("@shared/ui/context-menu", () => ({
   ContextMenuItem: ({ children, onClick }: { children: ReactNode; onClick?: () => void }) => createElement("button", { type: "button", onClick, "data-testid": `menu-item:${String(children)}` }, children),
 }));
 const React = require("react");
-const setDefaultFilesMock = vi.fn(async () => true);
+const detachFolderMock = vi.fn(async () => "saved" as const);
 
 function makeFolderEntry(path: string): AgentAccessEntry { return { id: `fld_${path}`, kind: "folder", path, name: path.split(/[\\/]/).pop() ?? path, enabled: true, workspace: false, missing: false, addedAt: 0, updatedAt: 0 }; }
 function makeNotebook(overrides: Partial<Notebook> = {}): Notebook { return { id: "nb_1", name: "Notebook", icon: null, path: "/notes/notebook", createdAt: 0, updatedAt: 0, isDefault: false, ...overrides }; }
 interface MountHandle { root: Root; host: HTMLDivElement }
 function mount(notebook: Notebook | undefined, folders: string[]): MountHandle {
-  const entries = folders.map(makeFolderEntry);
-  useAgentAccessStore.setState((state) => ({ ...state, config: { version: 1, entries, defaults: {} }, notebookConfigs: notebook ? { [notebook.id]: { version: 1, revision: 1, addDirs: folders.map((path, i) => ({ id: `dir_${i}`, path, label: path, enabled: true })) } } : {}, setDefaultFiles: setDefaultFilesMock as unknown as typeof state.setDefaultFiles }));
+  const resources = folders.map(makeFolderEntry);
+  const byNotebookId = notebook ? { [notebook.id]: {
+    notebook: { id: notebook.id, name: notebook.name, path: notebook.path },
+    addDirs: folders.map((path, i) => ({ id: `dir_${i}`, path, label: path, enabled: true, authorized: true, missing: false })),
+  } } : {};
+  setWorkspace({ resources, byNotebookId });
   const host = document.createElement("div"); document.body.append(host); const root = createRoot(host); void act(() => root.render(createElement(NotebookAccessFilesList, { notebook }))); return { root, host };
 }
 function menuItems(host: HTMLElement): NodeListOf<HTMLElement> { return host.querySelectorAll('[data-testid="menu-item:Delete"]'); }
 
 describe("NotebookAccessFilesList — notebook-local add-dir list", () => {
   let active: MountHandle | null = null;
-  beforeEach(() => { useAgentAccessStore.setState({ config: { version: 1, entries: [], defaults: {} } as AgentAccessConfig, notebookConfigs: {}, isLoading: false }); setDefaultFilesMock.mockClear(); setDefaultFilesMock.mockResolvedValue(true); toastMock.success.mockClear(); toastMock.error.mockClear(); });
+  beforeEach(() => { setWorkspace({ resources: [], byNotebookId: {} }); useAgentWorkspaceStore.setState((state) => ({ workspaceActions: { ...state.workspaceActions, detachFolderFromNotebook: detachFolderMock } })); detachFolderMock.mockClear(); detachFolderMock.mockResolvedValue("saved"); toastMock.success.mockClear(); toastMock.error.mockClear(); });
   afterEach(() => { if (active) { void act(() => active!.root.unmount()); active.host.remove(); active = null; } });
-  it("renders add-dir rows without workspace controls or badges", () => { active = mount(makeNotebook(), ["/folder-a", "/folder-b"]); expect(active.host.textContent).toContain("folder-a"); expect(active.host.querySelectorAll(".agent-thread-card__access-workspace-star").length).toBe(0); expect(active.host.querySelectorAll('[data-testid="menu-item:Set as workspace"]').length).toBe(0); expect(menuItems(active.host).length).toBe(2); });
-  it("deleting an add-dir updates the notebook-local folders", async () => { const notebook = makeNotebook(); active = mount(notebook, ["/folder-a", "/folder-b"]); await act(async () => { (menuItems(active!.host)[0] as HTMLElement).click(); await Promise.resolve(); }); expect(setDefaultFilesMock).toHaveBeenCalledWith(notebook.id, expect.objectContaining({ folders: ["/folder-b"] })); expect(toastMock.success).toHaveBeenCalled(); });
+  it("renders add-dir rows without workspace controls or badges", () => { active = mount(makeNotebook(), ["/folder-a", "/folder-b"]); expect(active.host.textContent).toContain("folder-a"); expect(active.host.querySelectorAll(".agent-composer__access-workspace-star").length).toBe(0); expect(active.host.querySelectorAll('[data-testid="menu-item:Set as workspace"]').length).toBe(0); expect(menuItems(active.host).length).toBe(2); });
+  it("deleting an add-dir detaches only that notebook path", async () => { const notebook = makeNotebook(); active = mount(notebook, ["/folder-a", "/folder-b"]); await act(async () => { (menuItems(active!.host)[0] as HTMLElement).click(); await Promise.resolve(); }); expect(detachFolderMock).toHaveBeenCalledWith(notebook.id, "/folder-a"); expect(toastMock.success).toHaveBeenCalled(); });
   it("does not render rows without a selected notebook", () => { active = mount(undefined, ["/folder-a"]); expect(menuItems(active.host).length).toBe(0); });
 });
+
+function setWorkspace(update: Partial<AgentWorkspaceState> | ((state: AgentWorkspaceState) => Partial<AgentWorkspaceState>)) {
+  const store = useAgentWorkspaceStore.getState();
+  const patch = typeof update === "function" ? update(store.workspace) : update;
+  useAgentWorkspaceStore.setState({ workspace: { ...store.workspace, ...patch } });
+}
diff --git a/app/flowix-web/features/memo/components/notebook-access-files-list.tsx b/app/flowix-web/features/memo/components/notebook-access-files-list.tsx
index 7abb22717..6cb95bf60 100644
--- a/app/flowix-web/features/memo/components/notebook-access-files-list.tsx
+++ b/app/flowix-web/features/memo/components/notebook-access-files-list.tsx
@@ -4,21 +4,21 @@ import { useCallback } from 'react';
 import { Folder } from '@phosphor-icons/react';
 import { Plus } from 'lucide-react';
 import { toast } from '@/lib/toast';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
-import { resolveNotebookAgentFiles } from '@/lib/agent-access-defaults';
+import { useAgentWorkspaceStore } from '@features/agent/store/agent-workspace-store';
 import { useI18n } from '@/lib/i18n';
 import { cn } from '@/lib/utils';
 import { Tooltip } from '@shared/ui/tooltip';
 import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@shared/ui/context-menu';
 import { NotebookIcon } from '@features/memo/components/notebook-icon';
 import type { Notebook } from '@features/memo/store/note-store';
-import { openBrowserColumnFileBrowser } from '@features/workspace/use-cases/browser-column-navigation';
+import { createFileBrowserTarget } from '@features/workspace/public/browser-column-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { canUseNativeContextMenu, logNativeContextMenuError, popupNativeContextMenu } from '@platform/tauri/native-context-menu';
 import { loadNativeMenuIcons } from '@platform/tauri/native-menu-icons';
 
 /**
  * Shows add-dir entries for the selected notebook.  The notebook itself is
- * the workspace/cwd; this list only edits notebook-local `.flowix/agent.json`
+ * the workspace/cwd; this list edits that notebook’s mounts in `local.db`
  * and never selects a primary folder.
  */
 interface NotebookAccessFilesListProps {
@@ -32,11 +32,6 @@ interface ResolvedItem {
   missing: boolean;
 }
 
-// Agent-access paths can come from older config files or different platform
-// path spellings. Use the same comparison semantics as the access-defaults
-// resolver so the visual badge follows the persisted workspace value.
-const comparablePath = (path: string): string =>
-  path.trim().replace(/[\\/]+$/, '').toLowerCase();
 const ACCESS_MENU_CLASS =
   'w-[160px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]';
 const ACCESS_MENU_ITEM_CLASS =
@@ -49,38 +44,19 @@ export function NotebookAccessFilesList({
 }: NotebookAccessFilesListProps) {
   const { t } = useI18n();
   const notebookId = notebook?.id;
-  const config = useAgentAccessStore((s) => s.config);
-  const notebookConfigs = useAgentAccessStore((s) => s.notebookConfigs);
-  const addFolderFromPicker = useAgentAccessStore((s) => s.addFolderFromPicker);
-  const setDefaultFiles = useAgentAccessStore((s) => s.setDefaultFiles);
-
-  // Only the selected notebook's `.flowix/agent.json` add-dirs are shown;
-  // global entries merely authorize paths and are never displayed as defaults.
-  const defaultFiles = resolveNotebookAgentFiles(config, notebookConfigs, notebookId);
-  // Keep stale local paths visible (as missing) so users can remove them. The
-  // runtime resolver still intersects with the global authorization registry.
-  const folderPaths = notebookId && notebookConfigs?.[notebookId]
-    ? notebookConfigs[notebookId].addDirs
-        .filter((directory) => directory.enabled)
-        .map((directory) => directory.path)
-    : defaultFiles?.folders ?? [];
-  const entries = config.entries;
-  const resolveItem = (path: string): ResolvedItem => {
-    const found = entries.find(
-      (e) => e.kind === 'folder' && comparablePath(e.path) === comparablePath(path),
-    );
-    if (found) return { path, name: found.name, missing: found.missing };
-    // 默认里存了 path 但全局 entries 已没有 (folder 被删): 按缺失处理,
-    // name 用路径末段兜底, 让用户仍能认出是哪个目录。
-    const trimmed = path.replace(/[\\/]+$/, '');
-    const derived = trimmed.split(/[\\/]/).pop() || trimmed;
-    return { path, name: derived, missing: true };
-  };
+  const workspaceNotebook = useAgentWorkspaceStore((state) =>
+    notebookId ? state.workspace.byNotebookId[notebookId] : undefined,
+  );
+  const addFolderFromPicker = useAgentWorkspaceStore((s) => s.workspaceActions.addFolderFromPicker);
+  const detachFolderFromNotebook = useAgentWorkspaceStore((s) => s.workspaceActions.detachFolderFromNotebook);
 
-  const folderItems = folderPaths.map(resolveItem);
+  // Show the selected notebook's mounts, including missing paths for removal.
+  const folderItems: ResolvedItem[] = (workspaceNotebook?.addDirs ?? [])
+    .filter(directory => directory.enabled)
+    .map(directory => ({ path: directory.path, name: directory.label, missing: directory.missing }));
 
   const handleAddFolder = useCallback(async () => {
-    const result = await addFolderFromPicker();
+    const result = await addFolderFromPicker(notebookId);
     if (!result.ok) {
       if (result.code === 'already-tracked') {
         toast.error(t('agent.access.alreadyTracked'));
@@ -89,56 +65,29 @@ export function NotebookAccessFilesList({
       }
       return;
     }
-    // Attach the picked folder to this notebook's local add-dir list. Without
-    // a selected notebook, the global authorization entry is still retained.
-    if (!notebookId) return;
-    // The picker reloads the global config before returning. Resolve the
-    // latest notebook defaults instead of appending to a stale render closure.
-    const latestState = useAgentAccessStore.getState();
-    const latestFiles = resolveNotebookAgentFiles(
-      latestState.config,
-      latestState.notebookConfigs,
-      notebookId,
-    );
-    if (
-      (latestFiles?.folders ?? []).some(
-        (path) => comparablePath(path) === comparablePath(result.entry.path),
-      )
-    ) {
-      toast.info(t('agent.access.folderExists'));
-      return;
-    }
-    const nextFolders = Array.from(new Set([...(latestFiles?.folders ?? []), result.entry.path]));
-    const saved = await setDefaultFiles(notebookId, {
-      folders: nextFolders,
-      notebooks: latestFiles?.notebooks ?? [],
-    });
-    if (!saved) toast.error(t('agent.access.saveFailed'));
-  }, [addFolderFromPicker, setDefaultFiles, notebookId, t]);
 
-  // 删除资料文件夹只修改当前 notebook 的 add-dir 列表。
+  }, [addFolderFromPicker, notebookId, t]);
+
+  // Removing a folder deletes only this notebook’s mount.
   const handleRemoveFolder = useCallback(
     async (path: string) => {
       if (!notebookId) return;
-      const nextFolders = folderPaths.filter((p) => p !== path);
-      const saved = await setDefaultFiles(notebookId, {
-        folders: nextFolders,
-        notebooks: defaultFiles?.notebooks ?? [],
-      });
-      if (!saved) {
+      const saved = await detachFolderFromNotebook(notebookId, path);
+      if (saved === false) {
         toast.error(t('agent.access.saveFailed'));
         return;
       }
+      if (saved === 'not-attached') return;
       const item = folderItems.find((it) => it.path === path);
       toast.success(t('agent.access.folderDeleted', { name: item?.name ?? path }));
     },
-    [notebookId, folderPaths, defaultFiles, folderItems, setDefaultFiles, t],
+    [notebookId, folderItems, detachFolderFromNotebook, t],
   );
 
   // 资料组 ── 外侧容器, pt-1 提供组上方留白; pb-2 将滚动列表末尾底部留白缩小一半。
   return (
     <div className="pt-1 pb-2">
-      <div className="agent-thread-card__access-section-label">
+      <div className="agent-composer__access-section-label">
         {t('memo.navigation.files')}
       </div>
       <div className="space-y-0.5">
@@ -171,7 +120,10 @@ export function NotebookAccessFilesList({
                 onClick={
                   canBrowse
                     ? () => {
-                        void openBrowserColumnFileBrowser(item.path);
+                        void openWorkspaceSurface({
+                          host: 'browser-column',
+                          target: createFileBrowserTarget(null, item.path, item.path),
+                        });
                         onOpenFile?.(item.path);
                       }
                     : undefined
@@ -181,7 +133,10 @@ export function NotebookAccessFilesList({
                     ? (event) => {
                         if (event.key === 'Enter' || event.key === ' ') {
                           event.preventDefault();
-                          void openBrowserColumnFileBrowser(item.path);
+                          void openWorkspaceSurface({
+                            host: 'browser-column',
+                            target: createFileBrowserTarget(null, item.path, item.path),
+                          });
                           onOpenFile?.(item.path);
                         }
                       }
@@ -236,6 +191,7 @@ export function NotebookAccessFilesList({
           <button
             type="button"
             onClick={handleAddFolder}
+            disabled={!notebookId}
             className="group relative flex h-8 w-full cursor-pointer select-none items-center gap-0 rounded-md pr-2 text-left text-sm transition-colors text-[var(--muted-foreground)] hover:bg-[var(--muted)]"
             style={{ paddingLeft: 6 }}
           >
diff --git a/app/flowix-web/features/memo/components/notebook-create-context-menu.tsx b/app/flowix-web/features/memo/components/notebook-create-context-menu.tsx
index 0f05999ee..423c23ab3 100644
--- a/app/flowix-web/features/memo/components/notebook-create-context-menu.tsx
+++ b/app/flowix-web/features/memo/components/notebook-create-context-menu.tsx
@@ -3,6 +3,7 @@ import { GalleryHorizontalEnd, Table2 } from 'lucide-react';
 import { useI18n } from '@/lib/i18n';
 import { ContextMenuItem, ContextMenuSeparator, ContextMenuSubmenu } from '@shared/ui/context-menu';
 import type { TableViewType } from '@features/multidimensional-table/public/create-api';
+import { MEMO_CREATE_VIEW_OPTIONS } from './memo-create-view-options';
 
 const MENU_ITEM_CLASS =
   'group h-7 items-center justify-start rounded-lg px-2 py-0 text-left transition-colors hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]';
@@ -12,13 +13,15 @@ export function NotebookCreateContextMenuItems({
   onCreateFolder,
   onCreateTable,
   onCreateMediaLibrary,
-  onImport,
+  onImportFiles,
+  onImportFolder,
 }: {
   onCreateNote: () => void;
   onCreateFolder: () => void;
   onCreateTable: (viewType?: TableViewType) => void;
   onCreateMediaLibrary: () => void;
-  onImport?: () => void;
+  onImportFiles?: () => void;
+  onImportFolder?: () => void;
 }) {
   const { t } = useI18n();
 
@@ -33,19 +36,10 @@ export function NotebookCreateContextMenuItems({
         {t('memo.fileTree.newFolder')}
       </ContextMenuItem>
       <ContextMenuSubmenu label={t('memo.create.more')} icon={<PlusIcon className="h-4 w-4" aria-hidden="true" />}>
-        <ContextMenuItem onClick={() => onCreateTable()} className={MENU_ITEM_CLASS}>
-          <Table2 className="mr-2 h-4 w-4" aria-hidden="true" />
-          <span>{t('memo.create.table')}</span>
-          <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">{t('memo.create.note')}</span>
-        </ContextMenuItem>
-        {([
-          ['gallery', 'memo.create.newGallery'],
-          ['kanban', 'memo.create.newKanban'],
-          ['calendar', 'memo.create.newCalendar'],
-        ] as const).map(([viewType, label]) => (
-          <ContextMenuItem key={viewType} onClick={() => onCreateTable(viewType)} className={MENU_ITEM_CLASS}>
-            <span className="mr-2 h-4 w-4 shrink-0" aria-hidden="true" />
-            {t(label)}
+        {MEMO_CREATE_VIEW_OPTIONS.map(({ type, labelKey }) => (
+          <ContextMenuItem key={type} onClick={() => onCreateTable(type)} className={MENU_ITEM_CLASS}>
+            {type === 'table' ? <Table2 className="mr-2 h-4 w-4" aria-hidden="true" /> : <span className="mr-2 h-4 w-4 shrink-0" aria-hidden="true" />}
+            {t(labelKey)}
             <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">{t('memo.create.note')}</span>
           </ContextMenuItem>
         ))}
@@ -57,10 +51,10 @@ export function NotebookCreateContextMenuItems({
           </span>
         </ContextMenuItem>
       </ContextMenuSubmenu>
-      {onImport && <ContextMenuItem onClick={onImport} className={MENU_ITEM_CLASS}>
-        <DownloadSimpleIcon className="mr-2 h-4 w-4" aria-hidden="true" />
-        {t('memo.fileTree.import')}
-      </ContextMenuItem>}
+      {(onImportFiles || onImportFolder) && <ContextMenuSubmenu label={t('memo.fileTree.import')} icon={<DownloadSimpleIcon className="h-4 w-4" aria-hidden="true" />}>
+        {onImportFiles && <ContextMenuItem onClick={onImportFiles} className={MENU_ITEM_CLASS}>{t('memo.fileTree.importFiles')}</ContextMenuItem>}
+        {onImportFolder && <ContextMenuItem onClick={onImportFolder} className={MENU_ITEM_CLASS}>{t('memo.fileTree.importFolder')}</ContextMenuItem>}
+      </ContextMenuSubmenu>}
       <ContextMenuSeparator />
     </>
   );
diff --git a/app/flowix-web/features/memo/components/notebook-create-form.tsx b/app/flowix-web/features/memo/components/notebook-create-form.tsx
new file mode 100644
index 000000000..a6c8a90a1
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-create-form.tsx
@@ -0,0 +1,180 @@
+import { ChevronRight, LoaderCircle } from 'lucide-react';
+import { Button } from '@shared/ui/button';
+import { Input } from '@shared/ui/input';
+import { NotebookIconPopover } from '@features/memo/components/notebook-icon-popover';
+import { NotebookTemplateCardPreview, NotebookTemplateEmptyCard } from '@features/onboarding/notebook-template-picker';
+import type { NotebookTemplate } from '@features/onboarding/notebook-templates';
+
+export const NOTEBOOK_CREATE_PAGE_GUTTER_CLASS = 'px-[clamp(38px,6vw,96px)] max-[679px]:px-12';
+
+export interface NotebookCreateFormProps {
+  title: string;
+  formId: string;
+  name: string;
+  onNameChange: (name: string) => void;
+  nameLabel: string;
+  namePlaceholder?: string;
+  pathLabel: string;
+  path: string;
+  pathPlaceholder: string;
+  directoryButtonLabel: string;
+  onSelectDirectory: () => void;
+  icon: string | null;
+  onIconChange: (icon: string | null) => void;
+  templates: NotebookTemplate[];
+  selectedTemplateId: string | null;
+  onSelectTemplate: () => void;
+  disabled: boolean;
+  onSubmit: () => void;
+}
+
+export interface NotebookCreateFooterProps {
+  formId: string;
+  disabled: boolean;
+  isBusy: boolean;
+  submitLabel?: string;
+  busyLabel?: string;
+  cancelLabel?: string;
+  onCancel?: () => void;
+}
+
+export function NotebookCreateFooter({
+  formId,
+  disabled,
+  isBusy,
+  submitLabel = '创建并开始使用',
+  busyLabel = '正在进入',
+  cancelLabel,
+  onCancel,
+}: NotebookCreateFooterProps) {
+  return (
+    <div className="sticky bottom-0 z-[2] mx-auto flex min-h-[62px] w-[min(100%,680px)] flex-[0_0_auto] items-center justify-end gap-[18px] border-t border-[var(--onboarding-line)] bg-[var(--frame-bg)] pt-[18px] max-[760px]:min-h-[58px] max-[760px]:pt-[14px]">
+      {cancelLabel && onCancel && (
+        <button
+          type="button"
+          onClick={onCancel}
+          disabled={isBusy}
+          className="inline-flex h-8 min-h-8 items-center justify-center gap-2 rounded-lg border border-[var(--border)] bg-transparent px-[15px] text-xs font-medium text-[var(--onboarding-subtle)] hover:text-[var(--onboarding-ink)] disabled:opacity-50"
+        >
+          {cancelLabel}
+        </button>
+      )}
+      <button
+        type="submit"
+        form={formId}
+        className="inline-flex min-h-[38px] items-center justify-center gap-1 rounded-[9px] border border-[var(--brand)] bg-[var(--brand)] px-[15px] text-xs font-semibold text-[var(--primary-foreground)] shadow-[0_8px_18px_color-mix(in_oklch,var(--brand)_18%,transparent)] transition-transform hover:-translate-y-px disabled:cursor-not-allowed disabled:opacity-[0.46] max-[760px]:flex-1"
+        disabled={disabled || isBusy}
+        aria-busy={isBusy}
+      >
+        {isBusy
+          ? <><LoaderCircle size={17} className="flowix-spin" aria-hidden="true" /> {busyLabel}</>
+          : <>{submitLabel} <ChevronRight size={14} className="-ml-1" aria-hidden="true" /></>}
+      </button>
+    </div>
+  );
+}
+
+export function NotebookCreateForm({
+  title,
+  formId,
+  name,
+  onNameChange,
+  nameLabel,
+  namePlaceholder,
+  pathLabel,
+  path,
+  pathPlaceholder,
+  directoryButtonLabel,
+  onSelectDirectory,
+  icon,
+  onIconChange,
+  templates,
+  selectedTemplateId,
+  onSelectTemplate,
+  disabled,
+  onSubmit,
+}: NotebookCreateFormProps) {
+  const selectedTemplate = templates.find((template) => template.id === selectedTemplateId);
+
+  return (
+    <div className="w-full">
+      <h1 id={`${formId}-title`} className="mb-10 text-4xl font-light leading-tight tracking-[-0.04em] text-[var(--onboarding-ink)] max-[760px]:text-3xl">
+        {title}
+      </h1>
+      <form
+        id={formId}
+        className="mt-[22px] grid w-[min(100%,680px)] grid-cols-[minmax(0,1fr)_320px] items-start gap-x-[22px] gap-y-4 p-0 max-[760px]:grid-cols-1"
+        onSubmit={(event) => {
+          event.preventDefault();
+          onSubmit();
+        }}
+      >
+        <div className="grid min-w-0 content-start gap-4 pr-[38px] max-[760px]:pr-0">
+          <div className="grid min-w-0 gap-1">
+            <label className="text-sm font-semibold text-[var(--foreground)]" htmlFor={`${formId}-name`}>{nameLabel}</label>
+            <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-2">
+              <Input
+                id={`${formId}-name`}
+                placeholder={namePlaceholder}
+                value={name}
+                onChange={(event) => onNameChange(event.target.value)}
+                autoFocus
+                className="h-10 bg-[var(--card)]"
+                disabled={disabled}
+              />
+              <NotebookIconPopover
+                value={icon}
+                notebookName={name}
+                onChange={onIconChange}
+                disabled={disabled}
+              />
+            </div>
+          </div>
+          <div className="grid min-w-0 gap-1">
+            <label className="text-sm font-semibold text-[var(--foreground)]" htmlFor={`${formId}-path`}>{pathLabel}</label>
+            <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-2">
+              <Input
+                id={`${formId}-path`}
+                value={path}
+                placeholder={pathPlaceholder}
+                disabled
+                readOnly
+                className="h-10 min-w-0 bg-[var(--card)]"
+              />
+              <Button
+                type="button"
+                variant="outline"
+                className="h-10 shrink-0 bg-[var(--card)]"
+                onClick={onSelectDirectory}
+                disabled={disabled}
+              >
+                {directoryButtonLabel}
+              </Button>
+            </div>
+          </div>
+        </div>
+        <div className="grid min-w-0 content-start gap-1">
+          <button
+            type="button"
+            className="flex w-full items-center justify-start gap-0.5 p-0 text-left text-sm font-semibold text-[var(--foreground)] hover:text-[var(--brand)] disabled:cursor-not-allowed disabled:opacity-50"
+            aria-haspopup="dialog"
+            onClick={onSelectTemplate}
+            disabled={disabled}
+          >
+            <span>选择场景模板（可选）</span>
+            <ChevronRight size={16} aria-hidden="true" />
+          </button>
+          {selectedTemplate ? (
+            <NotebookTemplateCardPreview
+              template={selectedTemplate}
+              onSwitch={onSelectTemplate}
+              disabled={disabled}
+            />
+          ) : (
+            <NotebookTemplateEmptyCard onClick={onSelectTemplate} disabled={disabled} />
+          )}
+        </div>
+      </form>
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/memo/components/notebook-dialogs.tsx b/app/flowix-web/features/memo/components/notebook-dialogs.tsx
index ba5256f54..049396399 100644
--- a/app/flowix-web/features/memo/components/notebook-dialogs.tsx
+++ b/app/flowix-web/features/memo/components/notebook-dialogs.tsx
@@ -13,7 +13,11 @@ import {
   getNotebookIconOption,
   NotebookIcon,
 } from '@features/memo/components/notebook-icon';
-import { NotebookIconPopover } from '@features/memo/components/notebook-icon-popover';
+import {
+  NOTEBOOK_CREATE_PAGE_GUTTER_CLASS,
+  NotebookCreateFooter,
+  NotebookCreateForm,
+} from '@features/memo/components/notebook-create-form';
 import { NotebookIconPicker } from '@features/memo/components/notebook-icon-picker';
 import type { Notebook } from '@features/memo/store/note-store';
 import { cn } from '@/lib/utils';
@@ -22,17 +26,15 @@ import type { CloudNotebook } from '@platform/tauri/client';
 import {
   ArrowLeft,
   Check,
-  ChevronRight,
   CloudDownload,
   Loader2,
 } from 'lucide-react';
 import { useExperimentalMode } from '@platform/tauri/use-experimental-mode';
-import { Textarea } from '@shared/ui/textarea';
 import { WindowsTitlebarControls } from '@shared/window-titlebar-controls';
 import { isMac } from '@features/shortcuts';
 import { OnboardingTitlebarMac } from '@features/onboarding/onboarding-titlebar-mac';
 import { useNotebookTemplates } from '@features/onboarding/notebook-templates';
-import { NotebookTemplateCardPreview, NotebookTemplateEmptyCard, NotebookTemplatePicker } from '@features/onboarding/notebook-template-picker';
+import { NotebookTemplatePicker } from '@features/onboarding/notebook-template-picker';
 
 interface NotebookDialogsProps {
   createOpen: boolean;
@@ -64,10 +66,6 @@ interface NotebookDialogsProps {
   onEditNotebookNameChange: (name: string) => void;
   editNotebookIcon: string | null;
   onEditNotebookIconChange: (icon: string | null) => void;
-  editNotebookDescription: string;
-  onEditNotebookDescriptionChange: (description: string) => void;
-  editNotebookDescriptionLoading: boolean;
-  editNotebookDescriptionChanged: boolean;
   editNotebookCloudSync: boolean;
   onEditNotebookCloudSyncChange: (enabled: boolean) => void;
   onEditNotebookCloudSyncUnavailable: () => void;
@@ -169,10 +167,6 @@ export function NotebookDialogs({
   onEditNotebookNameChange,
   editNotebookIcon,
   onEditNotebookIconChange,
-  editNotebookDescription,
-  onEditNotebookDescriptionChange,
-  editNotebookDescriptionLoading,
-  editNotebookDescriptionChanged,
   editNotebookCloudSync,
   onEditNotebookCloudSyncChange,
   onEditNotebookCloudSyncUnavailable,
@@ -200,16 +194,25 @@ export function NotebookDialogs({
         <DialogContent
           showCloseButton={false}
           aria-busy={isCreatingNotebook}
-          className="!fixed !inset-0 !z-[130] !flex !h-dvh !max-h-none !w-full !max-w-none !flex-col !overflow-hidden !rounded-none !bg-[var(--frame-bg)] !p-0 !text-[var(--foreground)] !shadow-none [--onboarding-form-gap:22px] [--onboarding-ink:var(--foreground)] [--onboarding-subtle:var(--muted-foreground)] [--onboarding-panel:color-mix(in_oklch,var(--card)_96%,var(--background))] [--onboarding-line:color-mix(in_oklch,var(--border)_78%,transparent)] [&_button:focus-visible]:outline-2 [&_button:focus-visible]:outline-[var(--ring)] [&_button:focus-visible]:outline-offset-[3px]"
+          aria-labelledby={createMode === 'create' ? 'flowix-create-notebook-form-title' : undefined}
+          className="!fixed !inset-0 !z-[130] !flex !h-dvh !max-h-none !w-full !max-w-none !flex-col !overflow-hidden !rounded-none !bg-[var(--frame-bg)] !p-0 !text-[var(--foreground)] !shadow-none [--onboarding-ink:var(--foreground)] [--onboarding-subtle:var(--muted-foreground)] [--onboarding-panel:color-mix(in_oklch,var(--card)_96%,var(--background))] [--onboarding-line:color-mix(in_oklch,var(--border)_78%,transparent)] [&_button:focus-visible]:outline-2 [&_button:focus-visible]:outline-[var(--ring)] [&_button:focus-visible]:outline-offset-[3px]"
         >
           {isMac() && <OnboardingTitlebarMac />}
           <WindowsTitlebarControls reserveSpace />
-          <main className="relative z-[1] flex min-h-0 w-full flex-1 flex-col overflow-hidden p-0">
-            <div className="mx-auto flex min-h-0 w-full max-w-[780px] flex-1 flex-col overflow-y-auto overscroll-contain pb-[104px] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+          <main className={cn(
+            'relative z-[1] flex min-h-0 w-full flex-1 flex-col overflow-hidden',
+            createMode === 'create'
+              ? `${NOTEBOOK_CREATE_PAGE_GUTTER_CLASS} pb-[clamp(22px,3vw,44px)] max-[760px]:pb-[26px]`
+              : 'p-0',
+          )}>
+            <div className={cn(
+              'mx-auto flex min-h-0 w-full flex-1 flex-col overflow-y-auto overscroll-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden',
+              createMode === 'create' ? 'max-w-[680px]' : 'max-w-[780px] pb-[104px]',
+            )}>
               <section className={`w-full py-[clamp(11px,1.33vw,16px)] pb-4 ${createMode === 'create' ? 'flex min-h-full flex-col justify-center' : ''}`}>
-                <div className="max-w-full">
-                  {createMode === 'cloud' ? (
-                    <>
+                {createMode === 'cloud' ? (
+                  <>
+                    <div className="max-w-full">
                       <button
                         type="button"
                         onClick={onBackToCreate}
@@ -221,161 +224,105 @@ export function NotebookDialogs({
                         {t('notebook.cloudImport.back')}
                       </button>
                       <h1 className="text-[clamp(23px,3.33vw,44px)] font-light leading-[0.98] tracking-[-0.065em] text-[var(--onboarding-ink)]">{t('notebook.cloudImport.title')}</h1>
-                    </>
-                  ) : (
-                    <h1 className="text-[clamp(23px,3.33vw,44px)] font-light leading-[0.98] tracking-[-0.065em] text-[var(--onboarding-ink)]">{t("notebook.create.title")}</h1>
-                  )}
-                </div>
-          {createMode === 'cloud' ? (
-            <div className="mt-[22px] w-full max-w-[780px]">
-              {remoteNotebooksLoading ? (
-                <div className="flex min-h-[180px] items-center justify-center gap-2 text-sm text-[var(--muted-foreground)]">
-                  <Loader2 className="h-4 w-4 animate-spin" />
-                  {t('notebook.cloudImport.loading')}
-                </div>
-              ) : remoteNotebooks.length === 0 ? (
-                <div className="flex min-h-[180px] items-center justify-center text-sm text-[var(--muted-foreground)]">
-                  {t('notebook.cloudImport.empty')}
-                </div>
-              ) : (
-                <div className="max-h-[min(55vh,560px)] space-y-2 overflow-y-auto pr-1">
-                  {remoteNotebooks.map((notebook) => {
-                    const syncing = remoteNotebookSyncingId === notebook.id;
-                    return (
-                      <div
-                        key={notebook.id}
-                        className="flex w-full items-center gap-3 rounded-lg border border-[var(--border)] px-3 py-2.5"
-                      >
-                        <NotebookIcon
-                          name={notebook.name}
-                          icon={notebook.icon ?? undefined}
-                          className="h-8 w-8 shrink-0 rounded-md bg-[var(--muted)] text-xs font-semibold"
-                        />
-                        <span className="min-w-0 flex-1 truncate text-sm">{notebook.name}</span>
-                        {notebook.synced ? (
-                          <span className="flex shrink-0 items-center gap-1 text-xs text-[var(--muted-foreground)]">
-                            <Check className="h-3.5 w-3.5" />
-                            {t('notebook.cloudImport.synced')}
-                          </span>
-                        ) : (
-                          <button
-                            type="button"
-                            disabled={remoteNotebookSyncingId !== null}
-                            onClick={() => onSelectRemoteNotebook(notebook)}
-                            className="flex h-8 shrink-0 items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3 text-sm text-[var(--primary-foreground)] hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-60"
-                          >
-                            {syncing ? (
-                              <Loader2 className="h-4 w-4 animate-spin" />
-                            ) : (
-                              <CloudDownload className="h-4 w-4" />
-                            )}
-                            {t('notebook.cloudImport.sync')}
-                          </button>
-                        )}
-                      </div>
-                    );
-                  })}
-                </div>
-              )}
-            </div>
-          ) : (
-            <form
-              id="flowix-create-notebook-form"
-              className="mt-[60px] grid w-full max-w-[780px] grid-cols-[minmax(0,1fr)_320px] items-start gap-x-[22px] gap-y-4 p-0 max-[760px]:grid-cols-1"
-              onSubmit={(event) => { event.preventDefault(); onConfirmCreate(); }}
-            >
-              <div className="grid min-w-0 content-start gap-4 pr-[38px] max-[760px]:pr-0">
-                <div className="grid min-w-0 gap-1">
-                  <label className="text-sm font-semibold text-[var(--foreground)]" htmlFor="create-notebook-name">{t('notebook.create.namePlaceholder')}</label>
-                  <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-2">
-                    <Input
-                      id="create-notebook-name"
-                      placeholder={t("notebook.create.namePlaceholder")}
-                      value={newNotebookName}
-                      onChange={(event) => onNewNotebookNameChange(event.target.value)}
-                      autoFocus
-                      className="h-10 bg-[var(--card)]"
-                    />
-                    <NotebookIconPopover
-                      value={newNotebookIcon}
-                      notebookName={newNotebookName}
-                      onChange={onNewNotebookIconChange}
-                    />
-                  </div>
-                </div>
-                <div className="grid min-w-0 gap-1">
-                  <label className="text-sm font-semibold text-[var(--foreground)]" htmlFor="create-notebook-path">{t("notebook.create.pathLabel")}</label>
-                  <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-2">
-                    <Input
-                      id="create-notebook-path"
-                      placeholder={t("notebook.create.pathPlaceholder")}
-                      value={newNotebookPath || newNotebookDefaultPath}
-                      disabled
-                      className="h-10 min-w-0 bg-[var(--card)]"
-                      readOnly
-                    />
-                    <Button
-                      type="button"
-                      variant="outline"
-                      className="h-10 shrink-0 bg-[var(--card)]"
-                      onClick={() => void onSelectDirectory()}
-                    >
-                      {t("notebook.create.selectDirectory")}
-                    </Button>
-                  </div>
-                </div>
-              </div>
-              <div className="grid min-w-0 content-start gap-1">
-                <button
-                  type="button"
-                  className="flex w-full items-center justify-start gap-0.5 p-0 text-left text-sm font-semibold text-[var(--foreground)] hover:text-[var(--brand)]"
-                  aria-haspopup="dialog"
-                  onClick={() => setIsTemplatePickerOpen(true)}
-                >
-                  <span>选择场景模板（可选）</span>
-                  <ChevronRight size={16} aria-hidden="true" />
-                </button>
-                {notebookTemplates.find((template) => template.id === newNotebookTemplateId) && (
-                  <NotebookTemplateCardPreview
-                    template={notebookTemplates.find((template) => template.id === newNotebookTemplateId)!}
-                    onSwitch={() => setIsTemplatePickerOpen(true)}
+                    </div>
+                    <div className="mt-[22px] w-full max-w-[780px]">
+                      {remoteNotebooksLoading ? (
+                        <div className="flex min-h-[180px] items-center justify-center gap-2 text-sm text-[var(--muted-foreground)]">
+                          <Loader2 className="h-4 w-4 flowix-spin" />
+                          {t('notebook.cloudImport.loading')}
+                        </div>
+                      ) : remoteNotebooks.length === 0 ? (
+                        <div className="flex min-h-[180px] items-center justify-center text-sm text-[var(--muted-foreground)]">
+                          {t('notebook.cloudImport.empty')}
+                        </div>
+                      ) : (
+                        <div className="max-h-[min(55vh,560px)] space-y-2 overflow-y-auto pr-1">
+                          {remoteNotebooks.map((notebook) => {
+                            const syncing = remoteNotebookSyncingId === notebook.id;
+                            return (
+                              <div
+                                key={notebook.id}
+                                className="flex w-full items-center gap-3 rounded-lg border border-[var(--border)] px-3 py-2.5"
+                              >
+                                <NotebookIcon
+                                  name={notebook.name}
+                                  icon={notebook.icon ?? undefined}
+                                  className="h-8 w-8 shrink-0 rounded-md bg-[var(--muted)] text-xs font-semibold"
+                                />
+                                <span className="min-w-0 flex-1 truncate text-sm">{notebook.name}</span>
+                                {notebook.synced ? (
+                                  <span className="flex shrink-0 items-center gap-1 text-xs text-[var(--muted-foreground)]">
+                                    <Check className="h-3.5 w-3.5" />
+                                    {t('notebook.cloudImport.synced')}
+                                  </span>
+                                ) : (
+                                  <button
+                                    type="button"
+                                    disabled={remoteNotebookSyncingId !== null}
+                                    onClick={() => onSelectRemoteNotebook(notebook)}
+                                    className="flex h-8 shrink-0 items-center gap-1.5 rounded-lg bg-[var(--primary)] px-3 text-sm text-[var(--primary-foreground)] hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-60"
+                                  >
+                                    {syncing ? (
+                                      <Loader2 className="h-4 w-4 flowix-spin" />
+                                    ) : (
+                                      <CloudDownload className="h-4 w-4" />
+                                    )}
+                                    {t('notebook.cloudImport.sync')}
+                                  </button>
+                                )}
+                              </div>
+                            );
+                          })}
+                        </div>
+                      )}
+                    </div>
+                  </>
+                ) : (
+                  <NotebookCreateForm
+                    title="新建笔记本"
+                    formId="flowix-create-notebook-form"
+                    name={newNotebookName}
+                    onNameChange={onNewNotebookNameChange}
+                    nameLabel={t('notebook.create.namePlaceholder')}
+                    namePlaceholder={t('notebook.create.namePlaceholder')}
+                    pathLabel={t('notebook.create.pathLabel')}
+                    path={newNotebookPath || newNotebookDefaultPath}
+                    pathPlaceholder={t('notebook.create.pathPlaceholder')}
+                    directoryButtonLabel={t('notebook.create.selectDirectory')}
+                    onSelectDirectory={() => void onSelectDirectory()}
+                    icon={newNotebookIcon}
+                    onIconChange={onNewNotebookIconChange}
+                    templates={notebookTemplates}
+                    selectedTemplateId={newNotebookTemplateId}
+                    onSelectTemplate={() => setIsTemplatePickerOpen(true)}
+                    disabled={isCreatingNotebook}
+                    onSubmit={onConfirmCreate}
                   />
                 )}
-                {!newNotebookTemplateId && (
-                  <NotebookTemplateEmptyCard onClick={() => setIsTemplatePickerOpen(true)} />
-                )}
-              </div>
-            </form>
-          )}
               </section>
             </div>
-            <div className="absolute bottom-0 left-0 z-[4] m-0 flex min-h-20 w-full items-center justify-end border-t border-[var(--onboarding-line)] bg-[var(--frame-bg)] px-[clamp(28px,6vw,96px)] pb-[calc(16px+env(safe-area-inset-bottom))] pt-4 max-[600px]:flex-wrap max-[600px]:gap-2 max-[600px]:px-5 max-[600px]:pb-[calc(12px+env(safe-area-inset-bottom))] max-[600px]:pt-3">
-              <div className="mx-auto flex w-full max-w-[780px] items-center justify-end gap-2">
-                <button
-                  type="button"
-                  onClick={onCancelCreate}
-                  disabled={isCreatingNotebook}
-                  className="inline-flex h-8 min-h-8 items-center justify-center gap-2 rounded-lg border border-[var(--border)] bg-transparent px-[15px] text-xs font-medium text-[var(--onboarding-subtle)] hover:text-[var(--onboarding-ink)] disabled:opacity-50"
-                >
-                  {t("notebook.create.cancel")}
-                </button>
-                {createMode === 'create' && (
+            {createMode === 'create' ? (
+              <NotebookCreateFooter
+                formId="flowix-create-notebook-form"
+                disabled={!newNotebookName.trim()}
+                isBusy={isCreatingNotebook}
+                cancelLabel={t('notebook.create.cancel')}
+                onCancel={onCancelCreate}
+              />
+            ) : (
+              <div className="absolute bottom-0 left-0 z-[4] m-0 flex min-h-20 w-full items-center justify-end border-t border-[var(--onboarding-line)] bg-[var(--frame-bg)] px-[clamp(28px,6vw,96px)] pb-[calc(16px+env(safe-area-inset-bottom))] pt-4 max-[600px]:flex-wrap max-[600px]:gap-2 max-[600px]:px-5 max-[600px]:pb-[calc(12px+env(safe-area-inset-bottom))] max-[600px]:pt-3">
+                <div className="mx-auto flex w-full max-w-[780px] items-center justify-end gap-2">
                   <button
-                    type="submit"
-                    form="flowix-create-notebook-form"
-                    className="inline-flex h-8 min-h-8 items-center justify-center gap-0.5 rounded-lg border border-[var(--brand)] bg-[var(--brand)] px-2.5 text-xs font-semibold text-[var(--primary-foreground)] shadow-[0_8px_18px_color-mix(in_oklch,var(--brand)_18%,transparent)] disabled:cursor-not-allowed disabled:opacity-50 max-[600px]:flex-1"
-                    disabled={isCreatingNotebook || !newNotebookName.trim()}
-                    aria-busy={isCreatingNotebook}
+                    type="button"
+                    onClick={onCancelCreate}
+                    disabled={isCreatingNotebook}
+                    className="inline-flex h-8 min-h-8 items-center justify-center gap-2 rounded-lg border border-[var(--border)] bg-transparent px-[15px] text-xs font-medium text-[var(--onboarding-subtle)] hover:text-[var(--onboarding-ink)] disabled:opacity-50"
                   >
-                    {isCreatingNotebook ? (
-                      <><Loader2 size={17} className="animate-spin" aria-hidden="true" />{t("notebook.create.creating")}</>
-                    ) : (
-                      <>新建笔记本 <ChevronRight size={14} aria-hidden="true" /></>
-                    )}
+                    {t('notebook.create.cancel')}
                   </button>
-                )}
+                </div>
               </div>
-            </div>
+            )}
             {createMode === 'create' && isTemplatePickerOpen && (
               <NotebookTemplatePicker
                 templates={notebookTemplates}
@@ -393,11 +340,11 @@ export function NotebookDialogs({
         </DialogContent>
       </Dialog>
       <Dialog open={editOpen} onOpenChange={onEditOpenChange}>
-        <DialogContent className="w-[760px] !max-w-[calc(100vw-2rem)]" aria-busy={editSaving}>
+        <DialogContent className="w-[390px] !max-w-[calc(100vw-2rem)]" aria-busy={editSaving}>
           <DialogHeader>
             <DialogTitle>{t("notebook.edit.title")}</DialogTitle>
           </DialogHeader>
-          <div className="mt-2 grid grid-cols-1 gap-6 md:grid-cols-[2fr_3fr]">
+          <div className="mt-2">
             <div className="min-w-0 space-y-3">
               <Input
                 placeholder={t("notebook.edit.namePlaceholder")}
@@ -437,18 +384,6 @@ export function NotebookDialogs({
                 />
               )}
             </div>
-            <div className="min-w-0 flex h-full flex-col md:border-l md:border-[var(--border)] md:pl-6">
-              <div className="flex items-center gap-1.5 pb-[0.35rem] pt-[0.35rem] text-sm font-semibold leading-[1.2] text-[var(--foreground)]">
-                {t('notebook.edit.agents.title')}
-              </div>
-              <Textarea
-                value={editNotebookDescription}
-                disabled={editSaving || editNotebookDescriptionLoading}
-                onChange={(event) => onEditNotebookDescriptionChange(event.target.value)}
-                placeholder={t('notebook.edit.agents.placeholder')}
-                className="h-full min-h-0 flex-1 resize-none"
-              />
-            </div>
           </div>
           <div className="mt-4 flex items-center justify-between gap-2">
             {editingNotebook ? (
@@ -487,15 +422,13 @@ export function NotebookDialogs({
                 className="h-8 px-3 text-sm rounded-lg bg-[var(--primary)] text-[var(--primary-foreground)] hover:opacity-90 disabled:opacity-50"
                 disabled={
                   editSaving ||
-                  editNotebookDescriptionLoading ||
                   !editNotebookName.trim() ||
                   (editNotebookName.trim() === editingNotebook?.name &&
                     (editNotebookIcon ?? '') === (normalizeNotebookIconId(editingNotebook?.icon) ?? '') &&
-                    !editNotebookCloudSyncChanged &&
-                    !editNotebookDescriptionChanged)
+                    !editNotebookCloudSyncChanged)
                 }
               >
-                {editSaving && <Loader2 className="mr-1.5 inline-block h-3.5 w-3.5 animate-spin" />}
+                {editSaving && <Loader2 className="mr-1.5 inline-block h-3.5 w-3.5 flowix-spin" />}
                 {editSaving ? t("notebook.edit.saving") : t("notebook.edit.confirm")}
               </button>
             </div>
diff --git a/app/flowix-web/features/memo/components/notebook-file-tree-sections.tsx b/app/flowix-web/features/memo/components/notebook-file-tree-sections.tsx
new file mode 100644
index 000000000..e7ea21fd4
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-file-tree-sections.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { ChevronRight } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { useI18n } from '@/lib/i18n';
+import type { DocTreeItem, MediaLibraryListItem, TableDocumentListItem } from '@platform/tauri/client';
+import { TREE_EDGE_GUTTER } from './notebook-tree-layout';
+
+interface SectionFrameProps {
+  order: number;
+  collapsed: boolean;
+  onToggleCollapsed: () => void;
+  sectionActions?: ReactNode;
+}
+
+interface NotebookPinnedSectionProps extends SectionFrameProps {
+  items: DocTreeItem[];
+  renderItem: (item: DocTreeItem) => ReactNode;
+}
+
+export function NotebookPinnedSection({
+  order,
+  collapsed,
+  onToggleCollapsed,
+  sectionActions,
+  items,
+  renderItem,
+}: NotebookPinnedSectionProps) {
+  const { t } = useI18n();
+
+  return (
+    <section
+      className="pb-3"
+      aria-label={t('memo.fileTree.pinnedSectionTitle')}
+      data-notebook-pinned-section="true"
+      style={{ order }}
+    >
+      <div
+        className="notebook-file-tree__section-header group mb-0.5 flex h-7 items-center rounded-lg px-1.5 transition-colors hover:bg-[var(--muted)]"
+        style={{ marginLeft: TREE_EDGE_GUTTER, width: `calc(100% - ${TREE_EDGE_GUTTER * 2}px)` }}
+      >
+        <button
+          type="button"
+          className="flex h-full items-center gap-0.5 text-[0.82rem] font-medium text-[var(--muted-foreground)] opacity-90 hover:text-[var(--foreground)] focus-visible:outline-none"
+          aria-label={t(collapsed ? 'memo.fileTree.expandPinned' : 'memo.fileTree.collapsePinned')}
+          title={t(collapsed ? 'memo.fileTree.expandPinned' : 'memo.fileTree.collapsePinned')}
+          onClick={onToggleCollapsed}
+        >
+          <span>{t('memo.fileTree.pinnedSectionTitle')}</span>
+          <ChevronRight className={cn(
+            'h-3.5 w-3.5 opacity-0 transition-[opacity,transform] group-hover:opacity-100 group-focus-within:opacity-100',
+            collapsed && 'opacity-100',
+            !collapsed && 'rotate-90',
+          )} />
+        </button>
+        <div className="ml-auto flex items-center">{sectionActions}</div>
+      </div>
+      {!collapsed && <div className="flex flex-col gap-0.5">{items.map(renderItem)}</div>}
+    </section>
+  );
+}
+
+interface NotebookViewsSectionProps extends SectionFrameProps {
+  tables: TableDocumentListItem[];
+  mediaLibraries: MediaLibraryListItem[];
+  renderTable: (item: TableDocumentListItem) => ReactNode;
+  renderMediaLibrary: (item: MediaLibraryListItem) => ReactNode;
+}
+
+export function NotebookViewsSection({
+  order,
+  collapsed,
+  onToggleCollapsed,
+  sectionActions,
+  tables,
+  mediaLibraries,
+  renderTable,
+  renderMediaLibrary,
+}: NotebookViewsSectionProps) {
+  const { t } = useI18n();
+
+  return (
+    <section
+      className="pb-3"
+      aria-label={t('memo.fileTree.viewsSectionTitle')}
+      data-notebook-views-section="true"
+      style={{ order }}
+    >
+      <div
+        className="notebook-file-tree__section-header group mb-0.5 flex h-7 items-center rounded-lg px-1.5 transition-colors hover:bg-[var(--muted)]"
+        style={{ marginLeft: TREE_EDGE_GUTTER, width: `calc(100% - ${TREE_EDGE_GUTTER * 2}px)` }}
+      >
+        <button
+          type="button"
+          className="flex h-full items-center gap-0.5 text-[0.82rem] font-medium text-[var(--muted-foreground)] opacity-90 hover:text-[var(--foreground)] focus-visible:outline-none"
+          aria-label={t(collapsed ? 'memo.fileTree.expandViews' : 'memo.fileTree.collapseViews')}
+          title={t(collapsed ? 'memo.fileTree.expandViews' : 'memo.fileTree.collapseViews')}
+          onClick={onToggleCollapsed}
+        >
+          <span>{t('memo.fileTree.viewsSectionTitle')}</span>
+          <ChevronRight className={cn(
+            'h-3.5 w-3.5 opacity-0 transition-[opacity,transform] group-hover:opacity-100 group-focus-within:opacity-100',
+            collapsed && 'opacity-100',
+            !collapsed && 'rotate-90',
+          )} />
+        </button>
+        <div className="ml-auto flex items-center">{sectionActions}</div>
+      </div>
+      {!collapsed && <div className="space-y-0.5">
+        {tables.map(renderTable)}
+        {mediaLibraries.map(renderMediaLibrary)}
+      </div>}
+    </section>
+  );
+}
diff --git a/app/flowix-web/features/memo/components/notebook-file-tree.test.tsx b/app/flowix-web/features/memo/components/notebook-file-tree.test.tsx
index 230a54234..f7a5b0506 100644
--- a/app/flowix-web/features/memo/components/notebook-file-tree.test.tsx
+++ b/app/flowix-web/features/memo/components/notebook-file-tree.test.tsx
@@ -4,6 +4,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { files, notes, type DocTreeItem } from '@platform/tauri/client';
 import { toast } from '@/lib/toast';
+import { noteRepository } from '@features/memo/services/note-repository';
 import { EXTERNAL_FILE_DROP_EVENT } from '@features/document/components/use-external-file-drop';
 import type { FolderTreeController } from './use-folder-tree';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
@@ -14,12 +15,14 @@ import {
 } from './notebook-file-tree';
 
 const repositoryTreeTestState = vi.hoisted(() => ({ loadComplete: false }));
+const translationTestState = vi.hoisted(() => ({ t: (key: string) => key }));
 
 vi.mock('@/lib/i18n', async (importOriginal) => ({
   ...await importOriginal<typeof import('@/lib/i18n')>(),
-  useI18n: () => ({ t: (key: string) => key }),
+  useI18n: () => ({ t: translationTestState.t }),
 }));
-vi.mock('@/lib/toast', () => ({ toast: { error: vi.fn() } }));
+vi.mock('@/lib/toast', () => ({ toast: { error: vi.fn(), success: vi.fn() } }));
+vi.mock('@features/memo/services/note-link-rewriter', () => ({ updateNoteLinksAfterMove: vi.fn() }));
 vi.mock('@shared/ui/overlay-scrollbar', () => ({
   OverlayScrollbar: ({
     children,
@@ -46,7 +49,7 @@ vi.mock('@shared/ui/context-menu', () => ({
   ContextMenu: ({ children }: { children: React.ReactNode }) => <>{children}</>,
   ContextMenuTrigger: ({ children }: { children: React.ReactNode }) => <>{children}</>,
   ContextMenuContent: ({ children }: { children: React.ReactNode }) => <>{children}</>,
-  ContextMenuItem: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  ContextMenuItem: ({ children, onClick }: { children: React.ReactNode; onClick?: React.MouseEventHandler<HTMLDivElement> }) => <div onClick={onClick}>{children}</div>,
   ContextMenuSubmenu: ({ label, children }: { label: string; children: React.ReactNode }) => <div>{label}{children}</div>,
   ContextMenuSeparator: () => <hr />,
   useContextMenuContext: () => ({ openAt: vi.fn() }),
@@ -245,6 +248,78 @@ describe('NotebookFileTree pointer dragging', () => {
     return new MouseEvent('click', { bubbles: true, button: 0, ...modifiers });
   }
 
+  it('keeps the expanded folder visible while Enter saves its new name', async () => {
+    const { root, tree } = await mount(successfulMove);
+    const folder = tree.rootChildren[0];
+    const renameFolder = vi.fn<(path: string, name: string, scope: string) => Promise<string>>();
+    const base = { ...tree, renameFolder, loadingDirectories: new Set<string>(), directoryErrors: new Set<string>() };
+    const render = (current: FolderTreeController) => root.render(
+      <NotebookFileTree notebookPath="/notes" notebookName="Notes" tree={current}
+        onNoteSelect={vi.fn()} onCreateNote={vi.fn()} onMoveNote={successfulMove} />,
+    );
+    let finishRename!: (path: string) => void;
+    renameFolder.mockImplementationOnce(() => new Promise((resolve) => { finishRename = resolve; }));
+    try {
+      await act(async () => render(base));
+      const child = item(`${folder.fullPath}/child.md`, 'document');
+      const expanded = {
+        ...base,
+        expanded: new Set([folder.fullPath]),
+        nodes: new Map([[folder.fullPath, { ...folder, children: [child] }]]),
+      };
+      await act(async () => render(expanded));
+      const rename = Array.from(host.querySelectorAll('div')).find((element) => element.textContent === 'memo.fileTree.rename');
+      expect(rename).toBeDefined();
+      await act(async () => rename!.dispatchEvent(clickEvent()));
+      const input = host.querySelector<HTMLInputElement>('input');
+      expect(input).not.toBeNull();
+      await act(async () => {
+        Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(input, 'renamed');
+        input!.dispatchEvent(new Event('input', { bubbles: true }));
+      });
+      await act(async () => input!.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })));
+      expect(renameFolder).toHaveBeenCalledWith(folder.fullPath, 'renamed', '/notes');
+      expect(host.querySelector('[data-notebook-tree-path="/notes/projects/child.md"]')).not.toBeNull();
+      expect(host.querySelector('[aria-label="memo.fileTree.loading"]')).not.toBeNull();
+      await act(async () => finishRename('/notes/renamed'));
+      expect(base.toggle).not.toHaveBeenCalled();
+      expect(expanded.expanded.has(folder.fullPath)).toBe(true);
+    } finally {
+      await act(async () => root.unmount());
+    }
+  });
+
+  it('opens a pinned note using its complete nested notebook path', async () => {
+    const { root, tree } = await mount(successfulMove);
+    const onNoteSelect = vi.fn();
+    vi.mocked(noteRepository.listByPath).mockResolvedValueOnce({
+      notes: [{
+        relativePath: 'projects/nested/note.md', title: 'note', preview: '', thumbnail: null,
+        tags: [], todos: [], agents: [], createdAt: 1, updatedAt: 1,
+        favorited: true, icon: null, colors: [], properties: {},
+      }],
+      nextCursor: null, hasMore: false,
+    });
+    try {
+      await act(async () => root.render(
+        <NotebookFileTree notebookId="notebook-1" notebookPath="/notes" notebookName="Notes" tree={tree}
+          onNoteSelect={onNoteSelect} onCreateNote={vi.fn()} onMoveNote={successfulMove} />,
+      ));
+      const row = host.querySelector<HTMLElement>('[data-notebook-tree-path="/notes/projects/nested/note.md"]');
+      expect(row).not.toBeNull();
+      await act(async () => row!.dispatchEvent(clickEvent()));
+      expect(onNoteSelect.mock.calls[0]?.[0]).toBe('/notes/projects/nested/note.md');
+      await act(async () => root.render(
+        <NotebookFileTree notebookId="notebook-1" notebookPath="/notes" notebookName="Notes" tree={tree}
+          activeFilePath="/notes/projects/nested/note.md"
+          onNoteSelect={onNoteSelect} onCreateNote={vi.fn()} onMoveNote={successfulMove} />,
+      ));
+      expect(tree.expandTo).not.toHaveBeenCalled();
+    } finally {
+      await act(async () => root.unmount());
+    }
+  });
+
   it('selects a folder on single click and toggles it on double click', async () => {
     const onFolderSelect = vi.fn();
     const { root, tree } = await mount(successfulMove, undefined, onFolderSelect);
@@ -269,16 +344,18 @@ describe('NotebookFileTree pointer dragging', () => {
     await act(async () => root.unmount());
   });
 
-  it('highlights the folder owning the active collection with the file selection background', async () => {
+  it.each(['collection', 'table', 'media-library'] as const)('highlights the folder owning an active %s including damaged file surfaces', async (kind) => {
     const previousNavigation = useWorkColumnStore.getState().navigation;
     const { root } = await mount(successfulMove);
     try {
       await act(async () => useWorkColumnStore.setState({ navigation: {
         ...previousNavigation,
-        target: {
+        target: kind === 'collection' ? {
           kind: 'collection', displayId: 'collection:projects', notebookId: 'notes',
           collectionId: 'projects', viewId: null, collectionType: 'table',
           filePath: '/notes/projects/.index.yaml', notebookPath: '/notes', name: 'Projects',
+        } : {
+          kind, filePath: '/notes/projects/.index.yaml', notebookPath: '/notes', notebookId: 'notes', unavailableReason: '集合文件格式无效',
         },
       } }));
       const folderRow = host.querySelector<HTMLElement>('[data-notebook-tree-kind="folder"]')!;
@@ -413,7 +490,6 @@ describe('NotebookFileTree pointer dragging', () => {
     const note = {
       ...item('/notes/a.md', 'document'),
       memoMeta: {
-        id: 'memo-1',
         icon: 'flashlight',
         colors: ['blue'],
         favorited: false,
@@ -434,7 +510,6 @@ describe('NotebookFileTree pointer dragging', () => {
     const note = {
       ...item('/notes/a.md', 'document'),
       memoMeta: {
-        id: 'memo-1',
         icon: null,
         colors: [],
         favorited: false,
diff --git a/app/flowix-web/features/memo/components/notebook-file-tree.tsx b/app/flowix-web/features/memo/components/notebook-file-tree.tsx
index cde284483..4c7534e88 100644
--- a/app/flowix-web/features/memo/components/notebook-file-tree.tsx
+++ b/app/flowix-web/features/memo/components/notebook-file-tree.tsx
@@ -6,43 +6,26 @@ import { AgentTasksSection } from '@features/agent/public/shell-api';
 import {
   useCallback,
   useEffect,
-  useLayoutEffect,
   useMemo,
   useRef,
   useState,
   type CSSProperties,
-  type KeyboardEvent as ReactKeyboardEvent,
   type MouseEvent as ReactMouseEvent,
-  type PointerEvent as ReactPointerEvent,
 } from 'react';
 import {
-  Check,
+  ChevronLeft,
   ChevronRight,
-  ArrowDownUp,
-  MoreHorizontal,
   GripVertical,
-  Plus,
-  Table2,
-  GalleryHorizontalEnd,
   Loader2,
 } from 'lucide-react';
-import {
-  ArrowDownIcon,
-  ArrowUpIcon,
-  FileIcon,
-  FolderSimplePlusIcon,
-  SquaresFourIcon,
-  DownloadSimpleIcon,
-} from '@phosphor-icons/react';
+import { SquaresFourIcon } from '@phosphor-icons/react';
 
 import {
   canonicalDirectoryPath,
   canonicalPath,
   joinNotebookMemoPath,
   parentDirectoryPath,
-  pathInDirectory,
   samePath,
-  uniquePaths,
 } from '@/lib/path';
 import { createLogger } from '@/lib/logger';
 import { toast } from '@/lib/toast';
@@ -50,33 +33,24 @@ import { cn, displayTitleFromFilename, isMediaLibraryFilename, isTableDocumentFi
 import { useI18n } from '@/lib/i18n';
 import { useComposingValue } from '@shared/hooks/use-composing-value';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 import { ListSurfaceLoadingState, ListSurfaceViewport } from '@shared/ui/list-surface';
 import { Button } from '@shared/ui/button';
 import { Popover, PopoverContent } from '@shared/ui/popover';
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@shared/ui/dialog';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
-} from '@shared/ui/dropdown-menu';
 import { NotebookTreeFileIcon } from '@features/memo/components/notebook-tree-file-icon';
 import { NotebookCreateContextMenuItems } from '@features/memo/components/notebook-create-context-menu';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { useCustomFilterStore } from '@features/memo/store/custom-filter-store';
-import { noteRepository } from '@features/memo/services/note-repository';
+import { NotebookPinnedSection, NotebookViewsSection } from '@features/memo/components/notebook-file-tree-sections';
+import { useNotebookPinnedNotes } from '@features/memo/components/use-notebook-pinned-notes';
 import { createMediaLibraryFile } from '@features/media-library/model';
 import { updateNoteLinksAfterMove } from '@features/memo/services/note-link-rewriter';
-import { openExternalTarget, replaceExternalDocumentPath } from '@features/workspace/use-cases/workspace-navigation';
+import { replaceExternalDocumentPath } from '@features/workspace/use-cases/workspace-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { ensureFileDisplayIdentity } from '@/lib/file-display-registry';
-import {
-  EXTERNAL_FILE_DROP_EVENT,
-  type ExternalFileDropDetail,
-} from '@features/document/public/shell-api';
 import { localDocumentOperations, renameMarkdownTitle } from '@features/document/public/file-operations-api';
 import folderIcon from '@/assets/folder-outline.svg?raw';
-import { resolveNotebookAgentFiles } from '@/lib/agent-access-defaults';
 import {
   flattenLoadedTree,
   flattenVisibleTree,
@@ -85,14 +59,12 @@ import {
 } from '@features/memo/components/use-folder-tree';
 import { NotebookTreeRow } from '@features/memo/components/notebook-tree-row';
 import { getWorkspaceAgentRepositories, type WorkspaceAgentRepository } from '@features/agent/public/workspace-api';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
-import { normalizeWorkspacePath } from '@features/agent/runtime/workspace-path';
+import { useAgentWorkspaceStore } from '@features/agent/store/agent-workspace-store';
 import {
   files,
   dialogs,
   system,
   type DocTreeItem,
-  type DocTreeResourceKind,
   type MediaLibraryListItem,
   type TableDocumentListItem,
 } from '@platform/tauri/client';
@@ -100,7 +72,18 @@ import { resourceKindFromPath } from '@features/editor/code-file';
 import { useDynamicVirtualList } from '@features/memo/hooks/use-dynamic-virtual-list';
 import { useNotebookViewData } from './use-notebook-view-data';
 import { AgentRepositoriesSection } from './notebook-repositories-section';
-import { TREE_EDGE_GUTTER, INDENT_PER_LEVEL } from './notebook-tree-layout';
+import { TREE_EDGE_GUTTER, INDENT_PER_LEVEL, TREE_ROW_GAP, TREE_ROW_HEIGHT, TREE_ROW_SIZE } from './notebook-tree-layout';
+import { useNotebookTreeInteraction } from './use-notebook-tree-interaction';
+import { useNotebookTreeDragController } from './use-notebook-tree-drag-controller';
+import type { NotebookMoveResult, NotebookMoveSource } from './use-notebook-tree-drag-controller';
+export type { NotebookMoveResult, NotebookMoveSource } from './use-notebook-tree-drag-controller';
+import { getPopupOriginRect, NotebookTreeSectionMenu } from './notebook-tree-section-menu';
+import {
+  normalizeNotebookMoveFailure,
+  showNotebookMoveFailureToasts,
+  type NotebookMoveFailure,
+} from './notebook-move-failure-toast';
+import { getNotebookFolderImportErrorKey } from './notebook-folder-import';
 import { createTableDocumentFile, type TableViewType } from '@features/multidimensional-table/public/create-api';
 import {
   ContextMenu,
@@ -109,65 +92,12 @@ import {
   ContextMenuTrigger,
 } from '@shared/ui/context-menu';
 
-
-function getPopupOriginRect(target: HTMLElement): DOMRect {
-  const rect = (target.closest('[role="menu"]') ?? target).getBoundingClientRect();
-  return new DOMRect(rect.left, rect.top, 0, 0);
-}
-const TREE_ROW_HEIGHT = 32;
-const TREE_ROW_GAP = 2;
-const TREE_ROW_SIZE = TREE_ROW_HEIGHT + TREE_ROW_GAP;
 const TREE_HEADER_HEIGHT = 30;
 const TREE_VIRTUAL_OVERSCAN = 20;
-const TREE_DRAG_SCROLL_EDGE = 40;
-const TREE_DRAG_SCROLL_MAX_STEP = 18;
-const TREE_DRAG_EXPAND_DELAY_MS = 650;
-const TREE_EXTERNAL_DRAG_EXPAND_DELAY_MS = 1000;
 const logger = createLogger('notebook-file-tree');
 // Row gutter (6px) + inline padding (6px) + half of the 12px caret.
 const FOLDER_CARET_CENTER_OFFSET = 12;
 
-function useViewportSubmenuPosition(open: boolean) {
-  const triggerRef = useRef<HTMLButtonElement | null>(null);
-  const contentRef = useRef<HTMLDivElement | null>(null);
-  const [style, setStyle] = useState<CSSProperties>({ left: '100%', top: 0 });
-
-  useLayoutEffect(() => {
-    if (!open) return;
-    const updatePosition = () => {
-      const trigger = triggerRef.current;
-      const content = contentRef.current;
-      if (!trigger || !content) return;
-      const triggerRect = trigger.getBoundingClientRect();
-      const width = content.offsetWidth || 176;
-      const height = content.scrollHeight;
-      const opensLeft = window.innerWidth - triggerRect.right < width + 8;
-      const top = Math.max(4, Math.min(triggerRect.top, window.innerHeight - height - 4));
-      setStyle({
-        left: opensLeft ? undefined : '100%',
-        right: opensLeft ? '100%' : undefined,
-        top: top - triggerRect.top,
-      });
-    };
-    updatePosition();
-    const frame = window.requestAnimationFrame(updatePosition);
-    const observer = typeof ResizeObserver === 'undefined' || !contentRef.current
-      ? null
-      : new ResizeObserver(updatePosition);
-    if (observer && contentRef.current) observer.observe(contentRef.current);
-    window.addEventListener('resize', updatePosition);
-    window.addEventListener('scroll', updatePosition, true);
-    return () => {
-      window.cancelAnimationFrame(frame);
-      observer?.disconnect();
-      window.removeEventListener('resize', updatePosition);
-      window.removeEventListener('scroll', updatePosition, true);
-    };
-  }, [open]);
-
-  return { triggerRef, contentRef, style };
-}
-
 type NotebookTreeSection = 'agents' | 'pinned' | 'views' | 'files' | 'repositories';
 
 const DEFAULT_TREE_SECTION_ORDER: NotebookTreeSection[] = ['agents', 'pinned', 'views', 'files', 'repositories'];
@@ -229,194 +159,6 @@ function mediaLibraryTreeItem(library: MediaLibraryListItem, fullPath: string):
   };
 }
 
-function TreeSectionMoreMenu({
-  canMoveUp,
-  canMoveDown,
-  onMoveUp,
-  onMoveDown,
-  onCreateFolder,
-  onCreateNote,
-  onCreateTable,
-  onCreateMediaLibrary,
-  onImportFiles,
-  sort,
-  onSort,
-  onCustomizeDisplay,
-}: {
-  canMoveUp: boolean;
-  canMoveDown: boolean;
-  onMoveUp: () => void;
-  onMoveDown: () => void;
-  onCreateFolder?: () => void;
-  onCreateNote?: () => void;
-  onCreateTable?: (viewType?: TableViewType) => void;
-  onCreateMediaLibrary?: () => void;
-  onImportFiles?: () => void;
-  sort?: FolderTreeSort;
-  onSort?: (sort: FolderTreeSort) => void;
-  onCustomizeDisplay?: (anchorRect: DOMRect) => void;
-}) {
-  const { t } = useI18n();
-  const [sortSubmenuOpen, setSortSubmenuOpen] = useState(false);
-  const [createSubmenuOpen, setCreateSubmenuOpen] = useState(false);
-  const createSubmenuPosition = useViewportSubmenuPosition(createSubmenuOpen);
-  const sortSubmenuPosition = useViewportSubmenuPosition(sortSubmenuOpen);
-  const itemClassName = 'group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)] disabled:cursor-not-allowed disabled:opacity-40';
-  const hasActionsAfterMovement = Boolean(
-    onCreateNote || onCreateFolder || onCreateTable || onCreateMediaLibrary || onImportFiles || (sort && onSort),
-  );
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <button
-          type="button"
-          className="notebook-file-tree__section-more-trigger flex h-6 w-6 items-center justify-center rounded-md text-[var(--muted-foreground)] opacity-0 transition-[color,opacity] hover:text-[var(--foreground)] focus-visible:opacity-100 focus-visible:outline-none group-hover:opacity-100"
-          aria-label={t('memo.fileTree.moreSectionActions')}
-          title={t('memo.fileTree.moreSectionActions')}
-        >
-          <MoreHorizontal className="h-3.5 w-3.5" aria-hidden="true" />
-        </button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent align="end" className="w-[176px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-        <DropdownMenuItem disabled={!canMoveUp} onClick={onMoveUp} className={itemClassName}>
-          <ArrowUpIcon className="h-3.5 w-3.5" aria-hidden="true" />
-          {t('memo.fileTree.moveSectionUp')}
-        </DropdownMenuItem>
-        <DropdownMenuItem disabled={!canMoveDown} onClick={onMoveDown} className={itemClassName}>
-          <ArrowDownIcon className="h-3.5 w-3.5" aria-hidden="true" />
-          {t('memo.fileTree.moveSectionDown')}
-        </DropdownMenuItem>
-        {(hasActionsAfterMovement || onCustomizeDisplay) && <DropdownMenuSeparator />}
-        {onCreateNote && (
-          <DropdownMenuItem onClick={onCreateNote} className={itemClassName}>
-            <FileIcon className="h-3.5 w-3.5" aria-hidden="true" />
-            {t('memo.fileTree.newNote')}
-          </DropdownMenuItem>
-        )}
-        {onCreateFolder && (
-          <DropdownMenuItem onClick={onCreateFolder} className={itemClassName}>
-            <FolderSimplePlusIcon className="h-3.5 w-3.5" aria-hidden="true" />
-            {t('memo.fileTree.newFolder')}
-          </DropdownMenuItem>
-        )}
-        {(onCreateTable || onCreateMediaLibrary) && (
-          <div
-            className="relative"
-            onMouseEnter={() => setCreateSubmenuOpen(true)}
-            onMouseLeave={() => setCreateSubmenuOpen(false)}
-          >
-            <button
-              type="button"
-              ref={createSubmenuPosition.triggerRef}
-              className={cn(itemClassName, 'flex w-full items-center justify-between text-sm')}
-              onClick={() => setCreateSubmenuOpen((open) => !open)}
-              onMouseDown={(event) => event.preventDefault()}
-            >
-              <span className="flex items-center gap-2">
-                <Plus className="h-3.5 w-3.5" aria-hidden="true" />
-                {t('memo.create.more')}
-              </span>
-              <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
-            </button>
-            {createSubmenuOpen && (
-              <div ref={createSubmenuPosition.contentRef} style={{ ...createSubmenuPosition.style, maxWidth: 'calc(100vw - 8px)', maxHeight: 'calc(100vh - 8px)', overflowY: 'auto' }} className="absolute w-[176px] space-y-0.5 rounded-xl border border-[var(--border-popup)] bg-[var(--card)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-                {onCreateTable && (
-                  <DropdownMenuItem onClick={() => onCreateTable()} className={itemClassName}>
-                    <Table2 className="h-3.5 w-3.5" aria-hidden="true" />
-                    <span>{t('memo.create.table')}</span>
-                    <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">{t('memo.create.note')}</span>
-                  </DropdownMenuItem>
-                )}
-                {onCreateTable && ([
-                  ['gallery', 'memo.create.newGallery'],
-                  ['kanban', 'memo.create.newKanban'],
-                  ['calendar', 'memo.create.newCalendar'],
-                ] as const).map(([viewType, label]) => (
-                  <DropdownMenuItem key={viewType} onClick={() => onCreateTable(viewType)} className={itemClassName}>
-                    <span className="h-3.5 w-3.5 shrink-0" aria-hidden="true" />
-                    {t(label)}
-                    <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">{t('memo.create.note')}</span>
-                  </DropdownMenuItem>
-                ))}
-                {onCreateMediaLibrary && (
-                  <DropdownMenuItem onClick={onCreateMediaLibrary} className={itemClassName}>
-                    <GalleryHorizontalEnd className="h-3.5 w-3.5" aria-hidden="true" />
-                    <span>{t('memo.create.mediaLibrary')}</span>
-                    <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">
-                      {t('memo.create.mediaImageShort')}/{t('memo.create.mediaVideoShort')}
-                    </span>
-                  </DropdownMenuItem>
-                )}
-              </div>
-            )}
-          </div>
-        )}
-        {onImportFiles && (
-          <DropdownMenuItem onClick={onImportFiles} className={itemClassName}>
-            <DownloadSimpleIcon className="h-3.5 w-3.5" aria-hidden="true" />
-            {t('memo.fileTree.import')}
-          </DropdownMenuItem>
-        )}
-        {sort && onSort && (
-          <div
-            className="relative"
-            onMouseEnter={() => setSortSubmenuOpen(true)}
-            onMouseLeave={() => setSortSubmenuOpen(false)}
-          >
-            <button
-              type="button"
-              ref={sortSubmenuPosition.triggerRef}
-              className={cn(itemClassName, 'memo-navigation-submenu-trigger flex w-full items-center justify-between text-sm')}
-              onClick={() => setSortSubmenuOpen(true)}
-              onMouseDown={(event) => event.preventDefault()}
-            >
-              <span className="flex items-center gap-2">
-                <ArrowDownUp className="h-3.5 w-3.5" aria-hidden="true" />
-                {t('memo.list.sortLabel')}
-              </span>
-              <span className="flex items-center gap-1 text-xs text-[var(--muted-foreground)]">
-                {t(sort === 'createdAt' ? 'memo.list.sortCreated' : sort === 'updatedAt' ? 'memo.list.sortUpdated' : sort === 'filenameAsc' ? 'memo.list.sortFilenameAsc' : 'memo.list.sortFilenameDesc')}
-                <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
-              </span>
-            </button>
-            {sortSubmenuOpen && (
-              <div ref={sortSubmenuPosition.contentRef} style={{ ...sortSubmenuPosition.style, maxWidth: 'calc(100vw - 8px)', maxHeight: 'calc(100vh - 8px)', overflowY: 'auto' }} className="absolute w-[176px] space-y-0.5 rounded-xl border border-[var(--border-popup)] bg-[var(--card)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-                {([
-                  ['createdAt', 'memo.list.sortCreated'],
-                  ['updatedAt', 'memo.list.sortUpdated'],
-                  ['filenameAsc', 'memo.list.sortFilenameAsc'],
-                  ['filenameDesc', 'memo.list.sortFilenameDesc'],
-                ] as const).map(([value, label]) => (
-                  <DropdownMenuItem
-                    key={value}
-                    onClick={() => onSort(value)}
-                    className={cn(
-                      'memo-navigation-submenu-item mention-note-item cursor-pointer hover:bg-[var(--brand)] focus-visible:bg-[var(--brand)] focus-visible:outline-none',
-                      sort === value && 'is-selected',
-                    )}
-                  >
-                    <span>{t(label)}</span>
-                    {sort === value && <Check className="h-4 w-4 text-[var(--brand)]" aria-hidden="true" />}
-                  </DropdownMenuItem>
-                ))}
-              </div>
-            )}
-          </div>
-        )}
-        {hasActionsAfterMovement && onCustomizeDisplay && <DropdownMenuSeparator />}
-        {onCustomizeDisplay && (
-          <DropdownMenuItem onClick={(event) => {
-            const rect = getPopupOriginRect(event.currentTarget);
-            onCustomizeDisplay(rect);
-          }} className={itemClassName}>
-            <SquaresFourIcon className="h-3.5 w-3.5" aria-hidden="true" />
-            {t('memo.fileTree.customizeDisplay')}
-          </DropdownMenuItem>
-        )}
-      </DropdownMenuContent>
-    </DropdownMenu>
-  );
-}
 
 function relativeFolderPath(notebookPath: string, folderPath: string): string {
   const root = canonicalDirectoryPath(notebookPath);
@@ -425,26 +167,6 @@ function relativeFolderPath(notebookPath: string, folderPath: string): string {
   return folder.startsWith(`${root}/`) ? folder.slice(root.length + 1) : folder;
 }
 
-function resolveDropDirectory(
-  hit: Element | null,
-  treeRoot: HTMLElement,
-  notebookPath: string,
-): string | null {
-  if (!hit || !treeRoot.contains(hit)) return null;
-
-  // Rows are flat and may be virtualized. Resolve the destination from row
-  // metadata rather than from DOM ancestry: a folder targets itself, while a
-  // file targets its logical parent. The surrounding surface falls back to
-  // the notebook root.
-  const row = hit.closest<HTMLElement>('[data-notebook-tree-row="true"]');
-  if (row && treeRoot.contains(row)) {
-    return row.dataset.notebookDropPath
-      ?? row.dataset.notebookParentPath
-      ?? notebookPath;
-  }
-  return notebookPath;
-}
-
 export interface NotebookFolderCreateRequest {
   id: number;
   parentPath: string;
@@ -455,17 +177,6 @@ export interface NotebookNoteCreateRequest {
   parentPath: string;
 }
 
-export interface NotebookMoveResult {
-  movedPaths: string[];
-  failedPaths: string[];
-}
-
-export interface NotebookMoveSource {
-  path: string;
-  resourceKind?: DocTreeResourceKind | null;
-  isFolder?: boolean;
-}
-
 interface NotebookFileTreeProps {
   notebookId?: string;
   notebookPath: string;
@@ -490,21 +201,6 @@ interface NotebookFileTreeProps {
   onSetDefaultCreateFolder?: (folderPath: string) => void;
 }
 
-interface PointerNoteDrag {
-  sourceType: 'folder' | 'document';
-  sourcePath: string;
-  sourcePaths: string[];
-  sourceItems: NotebookMoveSource[];
-  preserveSelectionAfterMove: boolean;
-  sourceName: string;
-  pointerId: number;
-  captureElement: HTMLElement;
-  startX: number;
-  startY: number;
-  active: boolean;
-  targetDirectoryPath: string | null;
-}
-
 interface NotebookTreeDraftState {
   requestId: number;
   parentPath: string;
@@ -512,12 +208,6 @@ interface NotebookTreeDraftState {
   value: string;
 }
 
-interface NotebookMoveFeedback {
-  paths: string[];
-  targetDirectoryPath: string;
-  status: 'moving' | 'success';
-}
-
 interface NotebookTreeNodeRenderRow {
   kind: 'node';
   key: string;
@@ -647,9 +337,8 @@ export function NotebookFileTree({
   const { t } = useI18n();
   const selectedFolderPath = useWorkColumnStore((state) => {
     const target = state.navigation.target;
-    if (target.kind === 'document-list') return target.scope.path;
-    if (target.kind === 'collection' && canonicalPath(target.filePath).endsWith('/.index.yaml')) {
-      return parentDirectoryPath(target.filePath, target.notebookPath);
+    if ((target.kind === 'collection' || target.kind === 'table' || target.kind === 'media-library') && canonicalPath(target.filePath).endsWith('/.index.yaml')) {
+      return parentDirectoryPath(target.filePath, target.notebookPath ?? '');
     }
     return null;
   });
@@ -659,14 +348,20 @@ export function NotebookFileTree({
   ));
   const notebookId = notebookIdProp ?? notebookIdFromStore;
   const loadNotebookFilters = useCustomFilterStore((state) => state.loadNotebookFilters);
-  const agentAccessConfig = useAgentAccessStore((state) => state.config);
-  const agentNotebookConfigs = useAgentAccessStore((state) => state.notebookConfigs);
+  const agentWorkspaceNotebook = useAgentWorkspaceStore((state) =>
+    notebookId ? state.workspace.byNotebookId[notebookId] : undefined,
+  );
   const agentRepositories = useMemo(
     () => getWorkspaceAgentRepositories(notebookId),
-    [agentAccessConfig, agentNotebookConfigs, notebookId],
+    [agentWorkspaceNotebook, notebookId],
   );
   const [showScrollTopHint, setShowScrollTopHint] = useState(false);
-  const [pinnedItems, setPinnedItems] = useState<DocTreeItem[]>([]);
+  const { pinnedItems, removePinnedItem } = useNotebookPinnedNotes({
+    notebookId,
+    notebookPath,
+    isActive,
+    refreshTrigger,
+  });
   const {
     tableDocuments,
     mediaLibraries,
@@ -694,11 +389,6 @@ export function NotebookFileTree({
   const [isCreatingLibrary, setIsCreatingLibrary] = useState(false);
   const viewTableDocuments = useMemo(() => tableDocuments.filter((table) => table.inViews), [tableDocuments]);
   const viewMediaLibraries = useMemo(() => mediaLibraries.filter((library) => library.inViews), [mediaLibraries]);
-  const viewDocumentPaths = useMemo(() => new Set([
-    ...viewTableDocuments.map((table) => joinNotebookMemoPath(notebookPath, table.relativePath)),
-    ...viewMediaLibraries.map((library) => joinNotebookMemoPath(notebookPath, library.relativePath)),
-  ].flatMap((path) => path ? [canonicalPath(path)] : [])), [notebookPath, viewMediaLibraries, viewTableDocuments]);
-  const activeFileIsInViews = Boolean(activeFilePath && viewDocumentPaths.has(canonicalPath(activeFilePath)));
   const tableDocumentByPath = useMemo(() => {
     const byPath = new Map<string, TableDocumentListItem>();
     for (const table of tableDocuments) {
@@ -732,28 +422,35 @@ export function NotebookFileTree({
     setCustomizeHidden([...hiddenSections]);
     setCustomizeOpen(true);
   }, [hiddenSections, sectionOrder]);
+  const updateCustomizeSectionVisibility = useCallback((section: NotebookTreeSection, visible: boolean) => {
+    const nextHiddenSections = visible
+      ? customizeHidden.filter((item) => item !== section)
+      : [...customizeHidden, section];
+    setCustomizeHidden(nextHiddenSections);
+    setHiddenSections(nextHiddenSections);
+    if (notebookId) {
+      void system.setNotebookFileTreeSectionOrder(notebookId, sectionOrder, nextHiddenSections).catch((error) => {
+        logger.warn('failed to save notebook file tree section visibility', { error, notebookId, section });
+      });
+    }
+  }, [customizeHidden, notebookId, sectionOrder]);
+  const updateCustomizeSectionOrder = useCallback((nextOrder: NotebookTreeSection[]) => {
+    setCustomizeOrder(nextOrder);
+    setSectionOrder(nextOrder);
+    if (notebookId) {
+      void system.setNotebookFileTreeSectionOrder(notebookId, nextOrder, hiddenSections).catch((error) => {
+        logger.warn('failed to save notebook file tree section order', { error, notebookId });
+      });
+    }
+  }, [hiddenSections, notebookId]);
   const draggedSection = useRef<NotebookTreeSection | null>(null);
   const sectionDragPointerId = useRef<number | null>(null);
   const sectionDropTargetRef = useRef<{ section: NotebookTreeSection; after: boolean } | null>(null);
   const [sectionDropTarget, setSectionDropTarget] = useState<{ section: NotebookTreeSection; after: boolean } | null>(null);
   const [agentSectionHeight, setAgentSectionHeight] = useState(0);
   const [draft, setDraft] = useState<NotebookTreeDraftState | null>(null);
-  const [selectedFilePaths, setSelectedFilePaths] = useState<string[]>([]);
-  const [focusedTreePath, setFocusedTreePath] = useState<string | null>(null);
-  const selectedFilePathsRef = useRef<string[]>([]);
-  const selectionAnchorPathRef = useRef<string | null>(null);
-  const previousActiveFilePathRef = useRef(
-    activeFilePath ? canonicalPath(activeFilePath) : null,
-  );
-  const pointerDragRef = useRef<PointerNoteDrag | null>(null);
-  const dropPendingRef = useRef(false);
-  const externalDropTargetPathRef = useRef<string | null>(null);
   const treeScrollerRef = useRef<HTMLDivElement | null>(null);
-  const pendingActiveFileScrollPathRef = useRef<string | null>(
-    activeFilePath ? canonicalPath(activeFilePath) : null,
-  );
-  const activeFileIsInViewsRef = useRef(activeFileIsInViews);
-  activeFileIsInViewsRef.current = activeFileIsInViews;
+  const treeRootRef = useRef<HTMLDivElement | null>(null);
   const externalDropSurfaceRef = useRef<HTMLDivElement | null>(null);
 
   useEffect(() => {
@@ -799,90 +496,20 @@ export function NotebookFileTree({
       logger.warn('failed to save notebook file tree section order', { error, notebookId });
     });
   }, [notebookId, sectionOrder, visibleSectionOrder]);
+  const hideTreeSection = useCallback((section: NotebookTreeSection) => {
+    if (!notebookId || hiddenSections.includes(section)) return;
+    const nextHiddenSections = [...hiddenSections, section];
+    setHiddenSections(nextHiddenSections);
+    void system.setNotebookFileTreeSectionOrder(notebookId, sectionOrder, nextHiddenSections).catch((error) => {
+      logger.warn('failed to save hidden notebook file tree section', { error, notebookId, section });
+    });
+  }, [hiddenSections, notebookId, sectionOrder]);
   const treeHeaderRef = useRef<HTMLDivElement | null>(null);
-  const treeRootRef = useRef<HTMLDivElement | null>(null);
-  const dragPreviewRef = useRef<HTMLDivElement | null>(null);
-  const dragPreviewPositionRef = useRef({ x: 0, y: 0 });
-  const moveFeedbackTimerRef = useRef<number | null>(null);
-  const dragScrollFrameRef = useRef<number | null>(null);
-  const dragPointerPositionRef = useRef<{ x: number; y: number } | null>(null);
-  const dragExpandTimerRef = useRef<number | null>(null);
-  const dragExpandPathRef = useRef<string | null>(null);
-  const suppressOpenPathsRef = useRef<Set<string>>(new Set());
   const handledFolderRequestIdRef = useRef<number | null>(null);
   const handledNoteRequestIdRef = useRef<number | null>(null);
   const cancelledDraftRequestIdRef = useRef<number | null>(null);
   const submittingDraftRef = useRef(false);
-  const [dragOverFolderPath, setDragOverFolderPath] = useState<string | null>(null);
-  const [dragPreview, setDragPreview] = useState<{
-    name: string;
-    path: string;
-    count: number;
-  } | null>(null);
-  const [moveFeedback, setMoveFeedback] = useState<NotebookMoveFeedback | null>(null);
   const [keptAlivePaths, setKeptAlivePaths] = useState<Set<string>>(() => new Set());
-
-  useEffect(() => {
-    if (!isActive) return;
-    let cancelled = false;
-    setPinnedItems([]);
-    if (!notebookId) return () => { cancelled = true; };
-    void noteRepository.listByPath({
-      notebookId,
-      filter: 'favorited',
-      sort: 'updatedAt',
-      limit: 100,
-    }).then((page) => {
-      if (cancelled) return;
-      setPinnedItems(page.notes.map((note) => {
-        const relativePath = note.relativePath.replace(/\\/g, '/');
-        const fullPath = pathInDirectory(notebookPath, relativePath);
-        return {
-          id: `pinned:${relativePath}`,
-          fullPath,
-          name: relativePath.split('/').pop() || relativePath,
-          type: 'document' as const,
-          parentId: null,
-          children: null,
-          sizeBytes: null,
-          modifiedMs: note.updatedAt,
-          createdMs: note.createdAt,
-          memoCreatedMs: note.createdAt,
-          resourceKind: 'note' as const,
-          memoMeta: {
-            id: relativePath,
-            icon: note.icon,
-            colors: note.colors,
-            favorited: true,
-          },
-        };
-      }));
-    }).catch((error) => {
-      logger.warn('failed to load pinned notes', { error, notebookPath });
-      if (!cancelled) setPinnedItems([]);
-    });
-    return () => { cancelled = true; };
-  }, [isActive, notebookId, notebookPath, refreshTrigger]);
-
-  const clearMoveFeedbackTimer = useCallback(() => {
-    if (moveFeedbackTimerRef.current === null) return;
-    window.clearTimeout(moveFeedbackTimerRef.current);
-    moveFeedbackTimerRef.current = null;
-  }, []);
-
-  useEffect(() => clearMoveFeedbackTimer, [clearMoveFeedbackTimer]);
-
-  const updateDragPreviewPosition = useCallback((x: number, y: number) => {
-    dragPreviewPositionRef.current = { x, y };
-    dragPreviewRef.current?.style.setProperty(
-      'transform',
-      `translate3d(${x}px, ${y}px, 0)`,
-    );
-  }, []);
-  const selectedFilePathSet = useMemo(
-    () => new Set(selectedFilePaths.map((path) => canonicalPath(path))),
-    [selectedFilePaths],
-  );
   const loadedTreeItems = useMemo(() => flattenLoadedTree(tree), [tree]);
   const visibleTreeItems = useMemo(() => flattenVisibleTree(tree, fileTreeSort), [fileTreeSort, tree]);
   const renderRows = useMemo(
@@ -906,6 +533,9 @@ export function NotebookFileTree({
   const handleAgentSectionHeightChange = useCallback((height: number) => {
     setAgentSectionHeight((current) => current === height ? current : height);
   }, []);
+  const handleShowAllAgentConversations = useCallback(() => {
+    useNoteStore.getState().setMiddleColumnView('conversations');
+  }, []);
   const handleRepositorySectionHeightChange = useCallback((height: number) => {
     setRepositorySectionHeight((current) => current === height ? current : height);
   }, []);
@@ -916,12 +546,72 @@ export function NotebookFileTree({
     const repositoryTop = repositoryElement.getBoundingClientRect().top;
     scroller.scrollTop += repositoryTop - scrollerTop - 36;
   }, []);
+  const renderRowIndexByPath = useMemo(() => new Map(
+    renderRows.flatMap((row, index) => row.kind === 'node'
+      ? [[canonicalPath(row.item.fullPath), index] as const]
+      : []),
+  ), [renderRows]);
+  const treeItemByPath = useMemo(
+    () => new Map(loadedTreeItems.map((item) => [canonicalPath(item.fullPath), item] as const)),
+    [loadedTreeItems],
+  );
+  const treeItemPaths = useMemo(() => new Set(treeItemByPath.keys()), [treeItemByPath]);
+  const {
+    focusedTreePath,
+    setFocusedTreePath,
+    selectedFilePaths,
+    selectedFilePathSet,
+    updateSelection,
+    getSelectionAnchorPath,
+    setNavigationPolicy,
+    navigateToNote,
+    activeFileShouldReveal,
+    treeFocusPath,
+    handleTreeItemKeyDown,
+    selectNote,
+  } = useNotebookTreeInteraction({
+    activeFilePath,
+    visibleTreeItems,
+    treeItemPaths,
+    tree,
+    treeRootRef,
+    treeScrollerRef,
+    renderRowIndexByPath,
+    treeContentOffset,
+    onNoteSelect,
+  });
+  const {
+    dragOverFolderPath,
+    dragPreview,
+    dragPreviewRef,
+    dragPreviewPositionRef,
+    moveFeedback,
+    startItemDrag: handlePointerDownItem,
+    handlePointerMove: handleTreePointerMove,
+    handlePointerUp: handleTreePointerUp,
+    handlePointerCancel: handleTreePointerCancel,
+    shouldSuppressOpen: shouldSuppressOpenPath,
+  } = useNotebookTreeDragController({
+    notebookId,
+    notebookPath,
+    tree,
+    treeItemsByPath: treeItemByPath,
+    selectedFilePaths,
+    getSelectionAnchorPath,
+    updateSelection,
+    onMoveNote,
+    treeRootRef,
+    treeHeaderRef,
+    treeScrollerRef,
+    externalDropSurfaceRef,
+    t,
+  });
   const getRenderRowKey = useCallback((row: NotebookTreeRenderRow) => row.key, []);
   const estimateRenderRowSize = useCallback(() => TREE_ROW_SIZE, []);
   const keepAliveKeys = useMemo(() => {
-    const keys = [...keptAlivePaths].map((path) => `node:${canonicalPath(path)}`);
-    if (focusedTreePath) keys.push(`node:${canonicalPath(focusedTreePath)}`);
-    if (draft) keys.push(`draft:${draft.requestId}`);
+    const keys = [...keptAlivePaths].map((path) => 'node:' + canonicalPath(path));
+    if (focusedTreePath) keys.push('node:' + canonicalPath(focusedTreePath));
+    if (draft) keys.push('draft:' + draft.requestId);
     return keys;
   }, [draft, focusedTreePath, keptAlivePaths]);
   const {
@@ -938,14 +628,9 @@ export function NotebookFileTree({
     keepAliveKeys,
     scrollMargin: treeContentOffset,
   });
-  const renderRowIndexByPath = useMemo(() => new Map(
-    renderRows.flatMap((row, index) => row.kind === 'node'
-      ? [[canonicalPath(row.item.fullPath), index] as const]
-      : []),
-  ), [renderRows]);
   useEffect(() => {
     if (!draft) return;
-    const index = renderRows.findIndex((row) => row.key === `draft:${draft.requestId}`);
+    const index = renderRows.findIndex((row) => row.key === 'draft:' + draft.requestId);
     const scroller = treeScrollerRef.current;
     if (index < 0 || !scroller) return;
     const rowTop = treeContentOffset + index * TREE_ROW_SIZE;
@@ -955,50 +640,6 @@ export function NotebookFileTree({
       scroller.scrollTop = Math.max(0, rowBottom - scroller.clientHeight);
     }
   }, [draft, renderRows, treeContentOffset]);
-  useEffect(() => {
-    const activePath = activeFilePath ? canonicalPath(activeFilePath) : null;
-    pendingActiveFileScrollPathRef.current = activeFileIsInViewsRef.current ? null : activePath;
-  }, [activeFilePath]);
-  // Folder expansion changes the row index map; only honor a pending request
-  // from an active-file change, and keep it pending until that row is loaded.
-  useEffect(() => {
-    if (!activeFilePath || activeFileIsInViews) return;
-    const activePath = canonicalPath(activeFilePath);
-    if (pendingActiveFileScrollPathRef.current !== activePath) return;
-    const index = renderRowIndexByPath.get(activePath);
-    const scroller = treeScrollerRef.current;
-    if (index === undefined || !scroller) return;
-    const rowTop = treeContentOffset + index * TREE_ROW_SIZE;
-    const rowBottom = rowTop + TREE_ROW_HEIGHT;
-    if (rowTop < scroller.scrollTop) scroller.scrollTop = rowTop;
-    else if (rowBottom > scroller.scrollTop + scroller.clientHeight) {
-      scroller.scrollTop = Math.max(0, rowBottom - scroller.clientHeight);
-    }
-    pendingActiveFileScrollPathRef.current = null;
-  }, [activeFileIsInViews, activeFilePath, renderRowIndexByPath, treeContentOffset]);
-  const visibleDocumentPaths = useMemo(
-    () => visibleTreeItems
-      .filter(({ item }) => item.type === 'document')
-      .map(({ item }) => item.fullPath),
-    [visibleTreeItems],
-  );
-  const treeItemByPath = useMemo(() => {
-    return new Map(loadedTreeItems.map((item) => [canonicalPath(item.fullPath), item] as const));
-  }, [loadedTreeItems]);
-  const treeItemPaths = useMemo(() => new Set(treeItemByPath.keys()), [treeItemByPath]);
-  const updateSelection = useCallback((paths: string[], anchorPath: string | null) => {
-    const nextPaths = uniquePaths(paths);
-    selectedFilePathsRef.current = nextPaths;
-    selectionAnchorPathRef.current = anchorPath;
-    setSelectedFilePaths(nextPaths);
-  }, []);
-  useLayoutEffect(() => {
-    const nextActivePath = activeFilePath ? canonicalPath(activeFilePath) : null;
-    if (previousActiveFilePathRef.current === nextActivePath) return;
-    previousActiveFilePathRef.current = nextActivePath;
-    if (selectedFilePathsRef.current.length === 0 && selectionAnchorPathRef.current === null) return;
-    updateSelection([], null);
-  }, [activeFilePath, updateSelection]);
   const handleRowKeepAliveChange = useCallback((path: string, active: boolean) => {
     const key = canonicalPath(path);
     setKeptAlivePaths((previous) => {
@@ -1010,145 +651,16 @@ export function NotebookFileTree({
       return next;
     });
   }, []);
-  useEffect(() => {
-    const currentPaths = selectedFilePathsRef.current;
-    const nextPaths = currentPaths.filter((path) => treeItemPaths.has(canonicalPath(path)));
-    if (nextPaths.length === currentPaths.length) return;
-    const anchorPath = selectionAnchorPathRef.current;
-    updateSelection(
-      nextPaths,
-      anchorPath && nextPaths.some((path) => samePath(path, anchorPath))
-        ? anchorPath
-        : nextPaths[nextPaths.length - 1] ?? null,
-    );
-  }, [treeItemPaths, updateSelection]);
-  const focusTreeItem = useCallback((path: string) => {
-    setFocusedTreePath(path);
-    const focusMountedRow = () => {
-      const row = Array.from(
-        treeRootRef.current?.querySelectorAll<HTMLElement>('[role="treeitem"]') ?? [],
-      ).find((candidate) => samePath(candidate.dataset.notebookTreePath ?? '', path));
-      row?.focus();
-      return Boolean(row);
-    };
-    if (focusMountedRow()) return;
-
-    const index = renderRowIndexByPath.get(canonicalPath(path));
-    const scroller = treeScrollerRef.current;
-    if (index === undefined || !scroller) return;
-    const rowTop = treeContentOffset + index * TREE_ROW_SIZE;
-    const rowBottom = rowTop + TREE_ROW_HEIGHT;
-    if (rowTop < scroller.scrollTop) scroller.scrollTop = rowTop;
-    else if (rowBottom > scroller.scrollTop + scroller.clientHeight) {
-      scroller.scrollTop = Math.max(0, rowBottom - scroller.clientHeight);
-    }
-    window.requestAnimationFrame(() => { focusMountedRow(); });
-  }, [renderRowIndexByPath, treeContentOffset]);
-  const handleTreeItemKeyDown = useCallback((
-    path: string,
-    event: ReactKeyboardEvent<HTMLDivElement>,
-  ) => {
-    const currentIndex = visibleTreeItems.findIndex(({ item }) => samePath(item.fullPath, path));
-    if (currentIndex < 0) return;
-    const current = visibleTreeItems[currentIndex];
-    const nextVisibleItem = (step: number) => visibleTreeItems[currentIndex + step];
-
-    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-      const target = nextVisibleItem(event.key === 'ArrowDown' ? 1 : -1);
-      if (!target) return;
-      event.preventDefault();
-      focusTreeItem(target.item.fullPath);
-      return;
-    }
-    if (event.key === 'Home' || event.key === 'End') {
-      const target = event.key === 'Home'
-        ? visibleTreeItems[0]
-        : visibleTreeItems[visibleTreeItems.length - 1];
-      if (!target) return;
-      event.preventDefault();
-      focusTreeItem(target.item.fullPath);
-      return;
-    }
-
-    if (event.key === 'ArrowRight' && current.item.type === 'folder') {
-      const expanded = tree.expanded.has(canonicalPath(current.item.fullPath));
-      if (!expanded) {
-        event.preventDefault();
-        tree.toggle(current.item.fullPath);
-        return;
-      }
-      const child = nextVisibleItem(1);
-      if (child && child.depth > current.depth) {
-        event.preventDefault();
-        focusTreeItem(child.item.fullPath);
-      }
-      return;
-    }
-
-    if (event.key === 'ArrowLeft') {
-      if (current.item.type === 'folder'
-        && tree.expanded.has(canonicalPath(current.item.fullPath))) {
-        event.preventDefault();
-        tree.toggle(current.item.fullPath);
-        return;
-      }
-      const parent = visibleTreeItems
-        .slice(0, currentIndex)
-        .reverse()
-        .find(({ item, depth }) => item.type === 'folder' && depth < current.depth);
-      if (parent) {
-        event.preventDefault();
-        focusTreeItem(parent.item.fullPath);
-      }
-    }
-  }, [focusTreeItem, tree, visibleTreeItems]);
-  useEffect(() => {
-    const hasFocusedItem = focusedTreePath
-      && visibleTreeItems.some(({ item }) => samePath(item.fullPath, focusedTreePath));
-    if (hasFocusedItem) return;
-    const fallback = activeFilePath && visibleTreeItems.some(({ item }) => samePath(item.fullPath, activeFilePath))
-      ? activeFilePath
-      : visibleTreeItems[0]?.item.fullPath ?? null;
-    if (fallback !== focusedTreePath) setFocusedTreePath(fallback);
-  }, [activeFilePath, focusedTreePath, visibleTreeItems]);
-  const selectNote = useCallback((filePath: string, event?: ReactMouseEvent<HTMLDivElement>) => {
-    const currentPaths = selectedFilePathsRef.current;
-    const isToggle = Boolean(event?.ctrlKey || event?.metaKey);
-    const anchorPath = selectionAnchorPathRef.current;
-    const targetIndex = visibleDocumentPaths.findIndex((path) => samePath(path, filePath));
-    const anchorIndex = anchorPath
-      ? visibleDocumentPaths.findIndex((path) => samePath(path, anchorPath))
-      : -1;
-
-    if (event?.shiftKey && anchorIndex >= 0 && targetIndex >= 0) {
-      const start = Math.min(anchorIndex, targetIndex);
-      const end = Math.max(anchorIndex, targetIndex);
-      const range = visibleDocumentPaths.slice(start, end + 1);
-      updateSelection(isToggle ? [...currentPaths, ...range] : range, filePath);
-    } else if (isToggle) {
-      const nextPaths = currentPaths.some((path) => samePath(path, filePath))
-        ? currentPaths.filter((path) => !samePath(path, filePath))
-        : [...currentPaths, filePath];
-      updateSelection(nextPaths, filePath);
-    } else {
-      updateSelection([filePath], filePath);
-      onNoteSelect(filePath);
-    }
-  }, [onNoteSelect, updateSelection, visibleDocumentPaths]);
   const hasVisibleItems = tree.rootChildren.length > 0;
   const isRootDropTarget = dragOverFolderPath !== null
     && canonicalDirectoryPath(dragOverFolderPath) === canonicalDirectoryPath(notebookPath);
-  const treeFocusPath = focusedTreePath
-    ?? (activeFilePath && visibleTreeItems.some(({ item }) => samePath(item.fullPath, activeFilePath))
-      ? activeFilePath
-      : visibleTreeItems[0]?.item.fullPath ?? null);
   const expandToRef = useRef(tree.expandTo);
   expandToRef.current = tree.expandTo;
 
   useEffect(() => {
-    if (!isActive || !activeFilePath || activeFileIsInViews || tree.loading) return;
+    if (!isActive || !activeFilePath || !activeFileShouldReveal || tree.loading) return;
     void expandToRef.current(activeFilePath);
-  }, [activeFileIsInViews, activeFilePath, isActive, tree.loading]);
+  }, [activeFileShouldReveal, activeFilePath, isActive, tree.loading]);
 
   useEffect(() => {
     if (!createFolderRequest || handledFolderRequestIdRef.current === createFolderRequest.id) return;
@@ -1234,12 +746,19 @@ export function NotebookFileTree({
     const currentName = item.type === 'folder'
       ? item.name
       : isNote || isTableDocument || isMediaLibrary ? displayTitleFromFilename(item.name) : item.name;
-    if (!trimmed || trimmed === currentName) return;
+    if (!trimmed || trimmed === currentName) return true;
 
     try {
       if (item.type === 'folder') {
-        const renamedPath = await files.renameFolder(item.fullPath, trimmed, notebookPath);
+        const renamedPath = await tree.renameFolder(item.fullPath, trimmed, notebookPath);
+        const oldFolderPath = canonicalDirectoryPath(item.fullPath);
+        const newFolderPath = canonicalDirectoryPath(renamedPath);
+        const expandedPathsToRefresh = [...tree.expanded]
+          .filter((path) => (path === oldFolderPath || path.startsWith(`${oldFolderPath}/`))
+            && (tree.loadingDirectories.has(path) || !tree.nodes.get(path)?.children?.length))
+          .map((path) => `${newFolderPath}${path.slice(oldFolderPath.length)}`);
         updateNoteLinksAfterMove(item.fullPath, renamedPath, true);
+        await Promise.all(expandedPathsToRefresh.map((path) => tree.refresh(path)));
       } else {
         if (isNote) {
           const fileIdentity = ensureFileDisplayIdentity(item.fullPath);
@@ -1250,8 +769,8 @@ export function NotebookFileTree({
             displayId: fileIdentity.displayId,
             onPathChanged: (oldPath, newPath) => replaceExternalDocumentPath(fileIdentity.displayId, oldPath, newPath),
           });
-          if (!result) return;
-          if (!result.changed) return;
+          if (!result) return false;
+          if (!result.changed) return true;
         } else {
           const extension = isTableDocument
             ? tableDocumentExtension(item.name)
@@ -1269,19 +788,21 @@ export function NotebookFileTree({
 
       const normalizedPath = canonicalPath(item.fullPath);
       const parent = normalizedPath.slice(0, normalizedPath.lastIndexOf('/'));
-      if (!isTableDocument && !isMediaLibrary) await tree.refresh(parent || notebookPath);
+      if (item.type !== 'folder' && !isTableDocument && !isMediaLibrary) await tree.refresh(parent || notebookPath);
       toast.success(t('memo.fileTree.renamed', { name: trimmed }));
+      return true;
     } catch (error) {
       toast.error(t(String(error).includes('FILE_EXISTS')
         ? 'memo.fileTree.nameConflict'
         : 'memo.fileTree.renameFailed'));
+      return false;
     }
-  }, [notebookPath, notebookId, tableDocumentByPath, mediaLibraryByPath, t, tree.refresh]);
+  }, [notebookPath, notebookId, tableDocumentByPath, mediaLibraryByPath, t, tree]);
 
   const handleRenameTableDocument = useCallback(async (item: DocTreeItem, nextName: string) => {
     const trimmed = nextName.trim();
     const currentName = displayTitleFromFilename(item.name);
-    if (!trimmed || trimmed === currentName) return;
+    if (!trimmed || trimmed === currentName) return true;
     try {
       await localDocumentOperations.rename({
         path: item.fullPath,
@@ -1290,10 +811,12 @@ export function NotebookFileTree({
       });
       if (notebookId) await refreshTables();
       toast.success(t('memo.fileTree.renamed', { name: trimmed }));
+      return true;
     } catch (error) {
       toast.error(t(String(error).includes('FILE_EXISTS')
         ? 'memo.fileTree.nameConflict'
         : 'memo.fileTree.renameFailed'));
+      return false;
     }
   }, [notebookId, notebookPath, t, refreshTables]);
 
@@ -1333,15 +856,49 @@ export function NotebookFileTree({
   }, [notebookId, notebookPath, onDeleteFile, t, refreshMediaLibraries]);
 
   const handleTogglePath = useCallback((path: string) => {
-    if (suppressOpenPathsRef.current.has(canonicalPath(path))) return;
+    if (shouldSuppressOpenPath(path)) return;
     tree.toggle(path);
-  }, [tree.toggle]);
+  }, [shouldSuppressOpenPath, tree.toggle]);
+  const openMediaLibraryPath = useCallback((
+    path: string,
+    host: 'main-third' | 'browser-column',
+    navigationPolicy: 'reveal' | 'preserve' = 'reveal',
+  ) => {
+    const mediaLibrary = mediaLibraryByPath.get(canonicalPath(path));
+    if (!mediaLibrary || !notebookId) return false;
+    if (host === 'main-third') setNavigationPolicy(path, navigationPolicy);
+    void openWorkspaceSurface({
+      ...(host === 'browser-column'
+        ? { host, options: { browserDisposition: 'open-in-column' as const } }
+        : { host }),
+      target: {
+        kind: 'collection-reference',
+        notebookId,
+        collectionId: mediaLibrary.collectionId,
+        collectionKind: 'media_library',
+        relativePathHint: mediaLibrary.relativePath,
+      },
+    }).catch((error) => {
+      logger.warn('failed to open media library', { error, path, host });
+      toast.error(t('memo.fileTree.openFailed'));
+    });
+    return true;
+  }, [mediaLibraryByPath, notebookId, setNavigationPolicy, t]);
   const handleOpenPath = useCallback((path: string, event?: ReactMouseEvent<HTMLDivElement>) => {
-    if (suppressOpenPathsRef.current.has(canonicalPath(path))) return;
+    if (shouldSuppressOpenPath(path)) return;
+    if (openMediaLibraryPath(path, 'main-third', 'reveal')) return;
     selectNote(path, event);
-  }, [selectNote]);
+  }, [openMediaLibraryPath, selectNote, shouldSuppressOpenPath]);
+  const handleOpenPinnedPath = useCallback((path: string) => {
+    if (shouldSuppressOpenPath(path)) return;
+    updateSelection([], null);
+    navigateToNote(path, 'preserve');
+  }, [navigateToNote, shouldSuppressOpenPath, updateSelection]);
   const handleOpenRepositoryFile = useCallback((path: string, scopePath: string) => {
-    void openExternalTarget(path, { destination: 'main-third', scopePath }).catch((error) => {
+    void openWorkspaceSurface({
+      host: 'main-third',
+      target: { kind: 'external', path, scopePath, transitionId: null },
+    }).catch((error) => {
       logger.warn('failed to open repository file', { error, path });
       toast.error(t('memo.fileTree.openFailed'));
     });
@@ -1349,11 +906,20 @@ export function NotebookFileTree({
   const handleOpenTableDocument = useCallback((relativePath: string) => {
     const path = joinNotebookMemoPath(notebookPath, relativePath);
     if (!path) return;
-    void openExternalTarget(path, { destination: 'main-third', scopePath: notebookPath, notebookId }).catch((error) => {
+    setNavigationPolicy(path, 'preserve');
+    void openWorkspaceSurface({
+      host: 'main-third',
+      target: { kind: 'external', path, scopePath: notebookPath, transitionId: null },
+      options: { notebookId },
+    }).catch((error) => {
       logger.warn('failed to open table document', { error, path });
       toast.error(t('memo.fileTree.openFailed'));
     });
-  }, [notebookId, notebookPath, t]);
+  }, [notebookId, notebookPath, setNavigationPolicy, t]);
+  const handleOpenMediaLibraryFromViews = useCallback((path: string) => {
+    if (openMediaLibraryPath(path, 'main-third', 'preserve')) return;
+    selectNote(path);
+  }, [openMediaLibraryPath, selectNote]);
   const openNewTableDialog = useCallback((inViews = false, parentFolderPath?: string, viewType: TableViewType = 'table') => {
     setNewTableInViews(inViews);
     setNewTableParentFolder(parentFolderPath ?? null);
@@ -1469,7 +1035,11 @@ export function NotebookFileTree({
       setNewTableInViews(false);
       setNewTableParentFolder(null);
       await refreshTables();
-      await openExternalTarget(filePath, { destination: 'main-third', scopePath: notebookPath, notebookId });
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'external', path: filePath, scopePath: notebookPath, transitionId: null },
+        options: { notebookId },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : '创建多维表格失败');
     } finally {
@@ -1502,7 +1072,11 @@ export function NotebookFileTree({
       setNewLibraryInViews(false);
       setNewLibraryParentFolder(null);
       await refreshMediaLibraries();
-      await openExternalTarget(filePath, { destination: 'main-third', scopePath: notebookPath, notebookId });
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'external', path: filePath, scopePath: notebookPath, transitionId: null },
+        options: { notebookId },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : '创建媒体库失败');
     } finally {
@@ -1511,48 +1085,30 @@ export function NotebookFileTree({
   }, [defaultCreateFolder, isCreatingLibrary, newLibraryInViews, newLibraryName, newLibraryParentFolder, notebookId, notebookPath, refreshMediaLibraries]);
   const handleAddRepository = useCallback(async () => {
     if (!notebookId) return;
-    const result = await useAgentAccessStore.getState().addFolderFromPicker();
+    const result = await useAgentWorkspaceStore.getState().workspaceActions.addFolderFromPicker(notebookId);
     if (!result.ok) {
       if (result.code === 'already-tracked') toast.error(t('agent.access.alreadyTracked'));
       else if (result.code === 'save-failed') toast.error(t('agent.access.saveFailed'));
       return;
     }
 
-    const access = useAgentAccessStore.getState();
-    const notebookFiles = resolveNotebookAgentFiles(access.config, access.notebookConfigs, notebookId);
-    const folders = notebookFiles?.folders ?? [];
-    const addedPath = normalizeWorkspacePath(result.entry.path).toLowerCase();
-    if (folders.some((path) => normalizeWorkspacePath(path).toLowerCase() === addedPath)) {
-      toast.info(t('agent.access.folderExists'));
-      return;
-    }
-    const saved = await access.setDefaultFiles(notebookId, {
-      folders: [...folders, result.entry.path],
-      notebooks: notebookFiles?.notebooks ?? [],
-    });
-    if (!saved) toast.error(t('agent.access.saveFailed'));
+
   }, [notebookId, t]);
   const handleRemoveRepository = useCallback(async (repository: WorkspaceAgentRepository) => {
     if (!notebookId) return;
-    const access = useAgentAccessStore.getState();
-    const notebookFiles = resolveNotebookAgentFiles(access.config, access.notebookConfigs, notebookId);
-    const folders = notebookFiles?.folders ?? [];
-    const removedPath = normalizeWorkspacePath(repository.path).toLowerCase();
-    const nextFolders = folders.filter((path) => normalizeWorkspacePath(path).toLowerCase() !== removedPath);
-    if (nextFolders.length === folders.length) return;
-    const saved = await access.setDefaultFiles(notebookId, {
-      folders: nextFolders,
-      notebooks: notebookFiles?.notebooks ?? [],
-    });
-    if (!saved) {
+    const access = useAgentWorkspaceStore.getState().workspaceActions;
+    const saved = await access.detachFolderFromNotebook(notebookId, repository.path);
+    if (saved === false) {
       toast.error(t('agent.access.saveFailed'));
       return;
     }
+    if (saved === 'not-attached') return;
     toast.success(t('agent.access.folderDeleted', { name: repository.name }));
   }, [notebookId, t]);
   const handleOpenPathInNewTab = useCallback((path: string) => {
+    if (openMediaLibraryPath(path, 'browser-column')) return;
     onNoteOpenInNewTab?.(path);
-  }, [onNoteOpenInNewTab]);
+  }, [onNoteOpenInNewTab, openMediaLibraryPath]);
   const handleCreateNoteAtPath = useCallback((parentPath: string) => {
     requestCreateDraft(parentPath, 'note');
   }, [requestCreateDraft]);
@@ -1563,63 +1119,6 @@ export function NotebookFileTree({
   const handleDeleteFolderPath = useCallback(async (path: string) => {
     await onDeleteFolder?.(path);
   }, [onDeleteFolder]);
-  const handlePointerDownItem = useCallback((
-    item: DocTreeItem,
-    event: ReactPointerEvent<HTMLDivElement>,
-  ) => {
-    if (dropPendingRef.current || event.button !== 0) return;
-    if (item.type === 'folder') {
-      const captureElement = event.currentTarget;
-      captureElement.setPointerCapture(event.pointerId);
-      pointerDragRef.current = {
-        sourceType: 'folder',
-        sourcePath: item.fullPath,
-        sourcePaths: [item.fullPath],
-        sourceItems: [{ path: item.fullPath, isFolder: true }],
-        preserveSelectionAfterMove: false,
-        sourceName: item.name,
-        pointerId: event.pointerId,
-        captureElement,
-        startX: event.clientX,
-        startY: event.clientY,
-        active: false,
-        targetDirectoryPath: null,
-      };
-      return;
-    }
-    const currentPaths = selectedFilePathsRef.current;
-    const isSelected = currentPaths.some((path) => samePath(path, item.fullPath));
-    const sourcePaths = isSelected ? currentPaths : [item.fullPath];
-    const sourceItems = sourcePaths.map((path) => {
-      const sourceItem = path === item.fullPath ? item : treeItemByPath.get(canonicalPath(path));
-      const resourceMetadata = sourceItem?.resourceKind
-        ? { resourceKind: sourceItem.resourceKind }
-        : {};
-      return { path, ...resourceMetadata };
-    });
-    // Capture on the row that started the gesture. Capturing on the tree root
-    // retargets the browser's follow-up click to the root. Selection stays a
-    // click concern: starting a drag must not select an unselected document.
-    // Pointer events still bubble through the tree root while the row remains
-    // mounted, which keeps drag handling unchanged without swallowing clicks.
-    const captureElement = event.currentTarget;
-    captureElement.setPointerCapture(event.pointerId);
-    pointerDragRef.current = {
-      sourceType: 'document',
-      sourcePath: item.fullPath,
-      sourcePaths,
-      sourceItems,
-      preserveSelectionAfterMove: isSelected,
-      sourceName: displayTitleFromFilename(item.name),
-      pointerId: event.pointerId,
-      captureElement,
-      startX: event.clientX,
-      startY: event.clientY,
-      active: false,
-      targetDirectoryPath: null,
-    };
-  }, [treeItemByPath]);
-
   const renderDraft = (draftState: NotebookTreeDraftState, depth: number) => (
     <NotebookTreeDraft
       draft={draftState}
@@ -1634,20 +1133,51 @@ export function NotebookFileTree({
   const handleImportFiles = useCallback(async (targetDirectoryPath: string) => {
     const selectedPaths = await dialogs.selectFiles({ multiple: true });
     if (!selectedPaths?.length) return;
-    let failed = 0;
+    const failures: NotebookMoveFailure[] = [];
     for (const sourcePath of selectedPaths) {
       try {
         await files.importFile(sourcePath, targetDirectoryPath, notebookPath);
       } catch (error) {
         logger.warn('importing file into notebook tree failed', { error, sourcePath, targetDirectoryPath });
-        failed += 1;
+        failures.push(normalizeNotebookMoveFailure(error));
       }
     }
     await tree.refresh(targetDirectoryPath);
-    if (failed) toast.error(t('memo.fileTree.movePartialFailed', {
-      moved: selectedPaths.length - failed,
-      failed,
-    }));
+    if (failures.length > 0) {
+      showNotebookMoveFailureToasts(
+        t,
+        selectedPaths.length - failures.length,
+        failures.length,
+        failures,
+      );
+    }
+  }, [notebookPath, t, tree.refresh]);
+
+  const handleImportFolder = useCallback(async (targetDirectoryPath: string) => {
+    let sourceDirectoryPath: string | null | undefined;
+    let progressToastId: string | number | undefined;
+    try {
+      sourceDirectoryPath = await dialogs.selectImportDirectory();
+      if (!sourceDirectoryPath) return;
+      progressToastId = toast.info(t('memo.fileTree.importFolderInProgress'), { duration: Number.POSITIVE_INFINITY });
+      await files.importFolder(sourceDirectoryPath, targetDirectoryPath, notebookPath);
+      await tree.refresh(targetDirectoryPath);
+      toast.dismiss(progressToastId);
+      progressToastId = undefined;
+      toast.success(t('memo.fileTree.importFolderSuccess'));
+    } catch (error) {
+      logger.warn('importing folder into notebook tree failed', { error, sourceDirectoryPath, targetDirectoryPath });
+      if (sourceDirectoryPath) {
+        try {
+          await tree.refresh(targetDirectoryPath);
+        } catch (refreshError) {
+          logger.warn('refreshing notebook tree after folder import failed', { refreshError, targetDirectoryPath });
+        }
+      }
+      toast.error(t(getNotebookFolderImportErrorKey(error)));
+    } finally {
+      if (progressToastId !== undefined) toast.dismiss(progressToastId);
+    }
   }, [notebookPath, t, tree.refresh]);
 
   const renderTreeItem = (
@@ -1723,6 +1253,7 @@ export function NotebookFileTree({
           onCreateNote={handleCreateNoteAtPath}
           onCreateFolder={handleCreateFolderAtPath}
           onImportFiles={handleImportFiles}
+          onImportFolder={handleImportFolder}
           onCreateView={handleCreateViewAtPath}
           onCreateMediaLibrary={handleCreateMediaLibraryAtPath}
           tableViewVisibility={tableViewVisibility}
@@ -1750,287 +1281,6 @@ export function NotebookFileTree({
     ? renderDraft(row.draft, row.depth)
     : renderTreeItem(row.item, row.depth, row.parentPath, row.posInSet, row.setSize);
 
-  const handleDrop = useCallback(async (
-    targetDirectoryPath: string,
-    sourceItemsOverride?: NotebookMoveSource[],
-    preserveSelectionAfterMove = false,
-  ) => {
-    if (dropPendingRef.current) return;
-    const sourceItems = sourceItemsOverride ?? pointerDragRef.current?.sourceItems ?? [];
-    const sourcePaths = sourceItems.map((source) => source.path);
-    if (sourcePaths.length === 0) return;
-    const targetPath = canonicalDirectoryPath(targetDirectoryPath);
-    const movableSourceItems = sourceItems.filter(
-      (source) => parentDirectoryPath(source.path, notebookPath) !== targetPath,
-    );
-    const movableSourcePaths = movableSourceItems.map((source) => source.path);
-    pointerDragRef.current = null;
-    setDragOverFolderPath(null);
-    setDragPreview(null);
-    if (movableSourcePaths.length === 0) return;
-    dropPendingRef.current = true;
-    clearMoveFeedbackTimer();
-    setMoveFeedback({
-      paths: movableSourcePaths,
-      targetDirectoryPath: targetPath,
-      status: 'moving',
-    });
-    try {
-      const startedAt = performance.now();
-      const moveResult = await onMoveNote(movableSourceItems, targetDirectoryPath);
-      const moveFinishedAt = performance.now();
-      const rootPath = canonicalDirectoryPath(notebookPath);
-      const sourceParents = uniquePaths(
-        movableSourcePaths.map((sourcePath) => parentDirectoryPath(sourcePath, notebookPath)),
-      ).filter((path) => (
-        path === rootPath || path.startsWith(`${rootPath}/`)
-      ));
-      const refreshPaths = moveResult.movedPaths.length > 0
-        ? [...sourceParents, targetDirectoryPath]
-        : sourceParents;
-      await Promise.all(uniquePaths(refreshPaths).map((path) => tree.refresh(path)));
-      const refreshFinishedAt = performance.now();
-      logger.debug('notebook tree drop completed', {
-        requestedCount: movableSourcePaths.length,
-        movedCount: moveResult.movedPaths.length,
-        failedCount: moveResult.failedPaths.length,
-        moveDurationMs: Math.round(moveFinishedAt - startedAt),
-        refreshDurationMs: Math.round(refreshFinishedAt - moveFinishedAt),
-        totalDurationMs: Math.round(refreshFinishedAt - startedAt),
-      });
-
-      const unchangedSelection = sourcePaths.filter((sourcePath) => (
-        parentDirectoryPath(sourcePath, notebookPath) === targetPath
-      ));
-      const nextSelection = uniquePaths([
-        ...moveResult.movedPaths,
-        ...moveResult.failedPaths,
-        ...unchangedSelection,
-      ]);
-      const selectedAnchor = selectionAnchorPathRef.current;
-      const movedAnchor = selectedAnchor
-        ? moveResult.movedPaths.find((path) => (
-          samePath(path, pathInDirectory(targetPath, selectedAnchor))
-        ))
-        : null;
-      const nextAnchor = movedAnchor
-        ?? (selectedAnchor && moveResult.failedPaths.some((path) => samePath(path, selectedAnchor))
-          ? selectedAnchor
-          : selectedAnchor && unchangedSelection.some((path) => samePath(path, selectedAnchor))
-            ? selectedAnchor
-            : nextSelection[nextSelection.length - 1] ?? null);
-      if (preserveSelectionAfterMove) updateSelection(nextSelection, nextAnchor);
-      if (moveResult.movedPaths.length > 0) {
-        setMoveFeedback({
-          paths: moveResult.movedPaths,
-          targetDirectoryPath: targetPath,
-          status: 'success',
-        });
-        moveFeedbackTimerRef.current = window.setTimeout(() => {
-          moveFeedbackTimerRef.current = null;
-          setMoveFeedback(null);
-        }, 450);
-      } else {
-        setMoveFeedback(null);
-      }
-      if (moveResult.failedPaths.length > 0) {
-        toast.error(t('memo.fileTree.movePartialFailed', {
-          moved: moveResult.movedPaths.length,
-          failed: moveResult.failedPaths.length,
-        }));
-      }
-    } catch (error) {
-      clearMoveFeedbackTimer();
-      setMoveFeedback(null);
-      toast.error(t(String(error).includes('FILE_EXISTS')
-        ? 'memo.fileTree.nameConflict'
-        : 'memo.fileTree.moveFailed'));
-    } finally {
-      dropPendingRef.current = false;
-    }
-  }, [clearMoveFeedbackTimer, notebookPath, onMoveNote, t, tree.refresh, updateSelection]);
-
-  const clearDragExpandTimer = useCallback(() => {
-    dragExpandPathRef.current = null;
-    if (dragExpandTimerRef.current !== null) {
-      window.clearTimeout(dragExpandTimerRef.current);
-      dragExpandTimerRef.current = null;
-    }
-  }, []);
-
-  const scheduleFolderHoverExpand = useCallback((
-    path: string | null,
-    delayMs = TREE_DRAG_EXPAND_DELAY_MS,
-  ) => {
-    const key = path ? canonicalPath(path) : null;
-    if (key === dragExpandPathRef.current) return;
-    clearDragExpandTimer();
-    if (!key) return;
-    const item = treeItemByPath.get(key);
-    if (item?.type !== 'folder' || tree.expanded.has(key)) return;
-
-    dragExpandPathRef.current = key;
-    dragExpandTimerRef.current = window.setTimeout(() => {
-      dragExpandTimerRef.current = null;
-      dragExpandPathRef.current = null;
-      const pointerTarget = pointerDragRef.current?.targetDirectoryPath ?? null;
-      const externalTarget = externalDropTargetPathRef.current;
-      if (
-        (pointerTarget && samePath(pointerTarget, key))
-        || (externalTarget && samePath(externalTarget, key))
-      ) {
-        tree.toggle(item.fullPath);
-      }
-    }, delayMs);
-  }, [clearDragExpandTimer, tree.expanded, tree.toggle, treeItemByPath]);
-
-  const stopDragAutoScroll = useCallback(() => {
-    dragPointerPositionRef.current = null;
-    if (dragScrollFrameRef.current !== null) {
-      window.cancelAnimationFrame(dragScrollFrameRef.current);
-      dragScrollFrameRef.current = null;
-    }
-  }, []);
-
-  const updatePointerDropTarget = useCallback((clientX: number, clientY: number) => {
-    const drag = pointerDragRef.current;
-    const treeRoot = treeRootRef.current;
-    if (!drag?.active || !treeRoot) return;
-    const hit = document.elementFromPoint(clientX, clientY);
-    const hitTree = hit?.closest<HTMLElement>('[data-notebook-tree-root="true"]');
-    const isOverHeader = Boolean(hit && treeHeaderRef.current?.contains(hit));
-    const candidateDirectoryPath = hitTree === treeRoot
-      ? resolveDropDirectory(hit, treeRoot, notebookPath)
-      : isOverHeader
-        ? notebookPath
-        : null;
-    const targetDirectoryPath = candidateDirectoryPath
-      && drag.sourcePaths.some((sourcePath) => {
-        const target = canonicalDirectoryPath(candidateDirectoryPath);
-        if (drag.sourceType === 'folder') {
-          const source = canonicalDirectoryPath(sourcePath);
-          if (target === source || target.startsWith(`${source}/`)) return false;
-        }
-        return parentDirectoryPath(sourcePath, notebookPath) !== target;
-      })
-      ? candidateDirectoryPath
-      : null;
-    if (drag.targetDirectoryPath !== targetDirectoryPath) {
-      drag.targetDirectoryPath = targetDirectoryPath;
-      setDragOverFolderPath(targetDirectoryPath);
-      scheduleFolderHoverExpand(targetDirectoryPath);
-    }
-  }, [notebookPath, scheduleFolderHoverExpand]);
-
-  const scheduleDragAutoScroll = useCallback((clientX: number, clientY: number) => {
-    dragPointerPositionRef.current = { x: clientX, y: clientY };
-    if (dragScrollFrameRef.current !== null) return;
-
-    const tick = () => {
-      dragScrollFrameRef.current = null;
-      const drag = pointerDragRef.current;
-      const position = dragPointerPositionRef.current;
-      const scroller = treeScrollerRef.current;
-      if (!drag?.active || !position || !scroller) return;
-
-      const bounds = scroller.getBoundingClientRect();
-      const topDistance = position.y - bounds.top;
-      const bottomDistance = bounds.bottom - position.y;
-      let delta = 0;
-      if (topDistance >= 0 && topDistance < TREE_DRAG_SCROLL_EDGE) {
-        delta = -TREE_DRAG_SCROLL_MAX_STEP
-          * (1 - topDistance / TREE_DRAG_SCROLL_EDGE);
-      } else if (bottomDistance >= 0 && bottomDistance < TREE_DRAG_SCROLL_EDGE) {
-        delta = TREE_DRAG_SCROLL_MAX_STEP
-          * (1 - bottomDistance / TREE_DRAG_SCROLL_EDGE);
-      }
-
-      if (delta !== 0) {
-        const previousScrollTop = scroller.scrollTop;
-        scroller.scrollTop = Math.max(0, previousScrollTop + delta);
-        if (scroller.scrollTop !== previousScrollTop) {
-          scroller.dispatchEvent(new Event('scroll'));
-          updatePointerDropTarget(position.x, position.y);
-          dragScrollFrameRef.current = window.requestAnimationFrame(tick);
-        }
-      }
-    };
-
-    dragScrollFrameRef.current = window.requestAnimationFrame(tick);
-  }, [updatePointerDropTarget]);
-
-  useEffect(() => () => {
-    stopDragAutoScroll();
-    clearDragExpandTimer();
-  }, [clearDragExpandTimer, stopDragAutoScroll]);
-
-  useEffect(() => {
-    const dropSurface = externalDropSurfaceRef.current;
-    if (!dropSurface) return;
-
-    const updateExternalDropTarget = (detail: ExternalFileDropDetail, hit: Element | null) => {
-      if (dropPendingRef.current) {
-        externalDropTargetPathRef.current = null;
-        scheduleFolderHoverExpand(null);
-        setDragOverFolderPath(null);
-        return;
-      }
-      if (detail.type === 'leave' || detail.paths.length === 0) {
-        externalDropTargetPathRef.current = null;
-        scheduleFolderHoverExpand(null);
-        if (!pointerDragRef.current) setDragOverFolderPath(null);
-        return;
-      }
-
-      const targetDirectoryPath = hit
-        ? resolveDropDirectory(hit, dropSurface, notebookPath)
-        : null;
-      const targetPath = targetDirectoryPath
-        ? canonicalDirectoryPath(targetDirectoryPath)
-        : null;
-      const canDrop = targetPath !== null && detail.paths.some((path) => (
-        parentDirectoryPath(path, notebookPath) !== targetPath
-      ));
-      const nextTargetPath = canDrop ? targetPath : null;
-      const previousTargetPath = externalDropTargetPathRef.current;
-      externalDropTargetPathRef.current = nextTargetPath;
-      if (previousTargetPath !== nextTargetPath) {
-        setDragOverFolderPath(nextTargetPath);
-      }
-
-      if (detail.type === 'drop') {
-        scheduleFolderHoverExpand(null);
-        if (!nextTargetPath) return;
-        externalDropTargetPathRef.current = null;
-        void handleDrop(nextTargetPath, detail.paths.map((path) => ({
-          path,
-          resourceKind: resourceKindFromPath(path),
-        })));
-        return;
-      }
-
-      if (previousTargetPath !== nextTargetPath || !nextTargetPath) {
-        scheduleFolderHoverExpand(
-          nextTargetPath,
-          TREE_EXTERNAL_DRAG_EXPAND_DELAY_MS,
-        );
-      }
-    };
-
-    const onExternalFileDrop = (event: Event) => {
-      const detail = (event as CustomEvent<ExternalFileDropDetail>).detail;
-      if (!detail) return;
-      const hit = event.target instanceof Element ? event.target : null;
-      updateExternalDropTarget(detail, hit);
-    };
-
-    dropSurface.addEventListener(EXTERNAL_FILE_DROP_EVENT, onExternalFileDrop);
-    return () => {
-      dropSurface.removeEventListener(EXTERNAL_FILE_DROP_EVENT, onExternalFileDrop);
-      externalDropTargetPathRef.current = null;
-    };
-  }, [handleDrop, notebookPath, scheduleFolderHoverExpand]);
-
   const folderDropHighlight = useMemo(() => {
     if (!dragOverFolderPath || samePath(dragOverFolderPath, notebookPath)) return null;
     const targetIndex = renderRows.findIndex((row) => (
@@ -2078,8 +1328,10 @@ export function NotebookFileTree({
               edgeGutter={TREE_EDGE_GUTTER}
               order={sectionOrder.indexOf('agents') + 1}
               onHeightChange={handleAgentSectionHeightChange}
+              onShowAllConversations={handleShowAllAgentConversations}
               sectionActions={(
-                <TreeSectionMoreMenu
+                <NotebookTreeSectionMenu
+                  onHideSection={() => hideTreeSection('agents')}
                   canMoveUp={visibleSectionOrder.indexOf('agents') > 0}
                   canMoveDown={visibleSectionOrder.indexOf('agents') < visibleSectionOrder.length - 1}
                   onMoveUp={() => moveTreeSection('agents', -1)}
@@ -2089,40 +1341,23 @@ export function NotebookFileTree({
               )}
             />
           )}
-          {pinnedItems.length > 0 && !hiddenSections.includes('pinned') && <section
-            className="pb-3"
-            aria-label={t('memo.fileTree.pinnedSectionTitle')}
-            data-notebook-pinned-section="true"
-            style={{ order: sectionOrder.indexOf('pinned') + 1 }}
-          >
-              <div
-                className="notebook-file-tree__section-header group mb-0.5 flex h-7 items-center rounded-lg px-1.5 transition-colors hover:bg-[var(--muted)]"
-                style={{
-                  marginLeft: TREE_EDGE_GUTTER,
-                  width: `calc(100% - ${TREE_EDGE_GUTTER * 2}px)`,
-                }}
-              >
-                <button
-                  type="button"
-                  className="flex h-full items-center gap-0.5 text-[0.82rem] font-medium text-[var(--muted-foreground)] opacity-90 hover:text-[var(--foreground)] focus-visible:outline-none"
-                  aria-label={t(pinnedCollapsed ? 'memo.fileTree.expandPinned' : 'memo.fileTree.collapsePinned')}
-                  title={t(pinnedCollapsed ? 'memo.fileTree.expandPinned' : 'memo.fileTree.collapsePinned')}
-                  onClick={() => setPinnedCollapsed((collapsed) => !collapsed)}
-                >
-                  <span>{t('memo.fileTree.pinnedSectionTitle')}</span>
-                  <ChevronRight className={cn('h-3.5 w-3.5 opacity-0 transition-[opacity,transform] group-hover:opacity-100 group-focus-within:opacity-100', pinnedCollapsed && 'opacity-100', !pinnedCollapsed && 'rotate-90')} />
-                </button>
-                <div className="ml-auto flex items-center">
-                  <TreeSectionMoreMenu
-                    canMoveUp={visibleSectionOrder.indexOf('pinned') > 0}
-                    canMoveDown={visibleSectionOrder.indexOf('pinned') < visibleSectionOrder.length - 1}
-                    onMoveUp={() => moveTreeSection('pinned', -1)}
-                    onMoveDown={() => moveTreeSection('pinned', 1)}
-                    onCustomizeDisplay={openCustomizeDisplay}
-                  />
-                </div>
-              </div>
-              {!pinnedCollapsed && pinnedItems.map((item) => (
+          {pinnedItems.length > 0 && !hiddenSections.includes('pinned') && (
+            <NotebookPinnedSection
+              order={sectionOrder.indexOf('pinned') + 1}
+              items={pinnedItems}
+              collapsed={pinnedCollapsed}
+              onToggleCollapsed={() => setPinnedCollapsed((collapsed) => !collapsed)}
+              sectionActions={(
+                <NotebookTreeSectionMenu
+                  onHideSection={() => hideTreeSection('pinned')}
+                  canMoveUp={visibleSectionOrder.indexOf('pinned') > 0}
+                  canMoveDown={visibleSectionOrder.indexOf('pinned') < visibleSectionOrder.length - 1}
+                  onMoveUp={() => moveTreeSection('pinned', -1)}
+                  onMoveDown={() => moveTreeSection('pinned', 1)}
+                  onCustomizeDisplay={openCustomizeDisplay}
+                />
+              )}
+              renderItem={(item) => (
                 <NotebookTreeRow
                   key={item.fullPath}
                   item={item}
@@ -2133,138 +1368,121 @@ export function NotebookFileTree({
                   active={!selectedFolderPath && Boolean(activeFilePath) && samePath(item.fullPath, activeFilePath!)}
                   selected={selectedFilePathSet.has(canonicalPath(item.fullPath))}
                   onToggle={handleTogglePath}
-                  onOpen={handleOpenPath}
+                  onOpen={handleOpenPinnedPath}
                   onOpenInNewTab={onNoteOpenInNewTab ? handleOpenPathInNewTab : undefined}
                   onCreateNote={handleCreateNoteAtPath}
                   onCreateFolder={handleCreateFolderAtPath}
-          onImportFiles={(path) => { void handleImportFiles(path); }}
-                  onCreateView={(parentPath, viewType) => {
-                    openNewTableDialog(false, parentPath, viewType);
-                  }}
+                  onImportFiles={(path) => { void handleImportFiles(path); }}
+                  onImportFolder={(path) => { void handleImportFolder(path); }}
+                  onCreateView={(parentPath, viewType) => openNewTableDialog(false, parentPath, viewType)}
                   onCreateMediaLibrary={(parentPath) => openNewMediaLibraryDialog(false, parentPath)}
                   onRename={handleRename}
                   onDeleteFile={onDeleteFile}
                   onPointerDown={() => {}}
-                  onFocus={handleFocusPath}
                   onKeepAliveChange={handleRowKeepAliveChange}
-                  favoritePath={joinNotebookMemoPath(notebookPath, item.memoMeta?.id) ?? undefined}
+                  favoritePath={item.fullPath}
                   onFavoriteChanged={(itemId, favorited) => {
-                    if (!favorited) setPinnedItems((current) => current.filter((pinned) => pinned.id !== itemId));
+                    if (!favorited) removePinnedItem(itemId);
                   }}
                   tabIndex={0}
                 />
-              ))}
-          </section>}
-          {!hiddenSections.includes('views') && <section
-            className="pb-3"
-            aria-label={t('memo.fileTree.viewsSectionTitle')}
-            data-notebook-views-section="true"
-            style={{ order: sectionOrder.indexOf('views') + 1 }}
-          >
-            <div
-              className="notebook-file-tree__section-header group mb-0.5 flex h-7 items-center rounded-lg px-1.5 transition-colors hover:bg-[var(--muted)]"
-              style={{
-                marginLeft: TREE_EDGE_GUTTER,
-                width: `calc(100% - ${TREE_EDGE_GUTTER * 2}px)`,
-              }}
-            >
-              <button
-                type="button"
-                className="flex h-full items-center gap-0.5 text-[0.82rem] font-medium text-[var(--muted-foreground)] opacity-90 hover:text-[var(--foreground)] focus-visible:outline-none"
-                aria-label={t(viewsCollapsed ? 'memo.fileTree.expandViews' : 'memo.fileTree.collapseViews')}
-                title={t(viewsCollapsed ? 'memo.fileTree.expandViews' : 'memo.fileTree.collapseViews')}
-                onClick={() => setViewsCollapsed((collapsed) => !collapsed)}
-              >
-                <span>{t('memo.fileTree.viewsSectionTitle')}</span>
-                <ChevronRight className={cn('h-3.5 w-3.5 opacity-0 transition-[opacity,transform] group-hover:opacity-100 group-focus-within:opacity-100', viewsCollapsed && 'opacity-100', !viewsCollapsed && 'rotate-90')} />
-              </button>
-              <div className="ml-auto flex items-center">
-                <TreeSectionMoreMenu
+              )}
+            />
+          )}
+          {!hiddenSections.includes('views') && (
+            <NotebookViewsSection
+              order={sectionOrder.indexOf('views') + 1}
+              tables={viewTableDocuments}
+              mediaLibraries={viewMediaLibraries}
+              collapsed={viewsCollapsed}
+              onToggleCollapsed={() => setViewsCollapsed((collapsed) => !collapsed)}
+              sectionActions={(
+                <NotebookTreeSectionMenu
+                  onHideSection={() => hideTreeSection('views')}
                   canMoveUp={visibleSectionOrder.indexOf('views') > 0}
                   canMoveDown={visibleSectionOrder.indexOf('views') < visibleSectionOrder.length - 1}
                   onMoveUp={() => moveTreeSection('views', -1)}
                   onMoveDown={() => moveTreeSection('views', 1)}
                   onCreateTable={(viewType) => openNewTableDialog(true, undefined, viewType)}
                   onCreateMediaLibrary={() => openNewMediaLibraryDialog(true)}
+                  onCustomizeDisplay={openCustomizeDisplay}
                 />
-              </div>
-            </div>
-            {!viewsCollapsed && <div className="space-y-0.5">
-            {viewTableDocuments.map((table) => {
-              const tablePath = joinNotebookMemoPath(notebookPath, table.relativePath);
-              const active = Boolean(!selectedFolderPath && activeFilePath && tablePath && samePath(activeFilePath, tablePath));
-              if (!tablePath) return null;
-              const tableItem = tableDocumentTreeItem(table, tablePath);
-              const parentPath = parentDirectoryPath(tablePath, notebookPath);
-              return <NotebookTreeRow
-                key={table.relativePath}
-                item={tableItem}
-                notebookPath={notebookPath}
-                parentPath={parentPath}
-                depth={0}
-                expanded={false}
-                active={active}
-                selected={active}
-                onToggle={() => {}}
-                onOpen={() => handleOpenTableDocument(table.relativePath)}
-                onOpenInNewTab={onNoteOpenInNewTab ? handleOpenPathInNewTab : undefined}
-                onCreateNote={handleCreateNoteAtPath}
-                onCreateFolder={handleCreateFolderAtPath}
-                onCreateView={(parentPath, viewType) => {
-                  openNewTableDialog(true, parentPath, viewType);
-                }}
-                onCreateMediaLibrary={(parentPath) => openNewMediaLibraryDialog(true, parentPath)}
-                tableViewVisibility={{
-                  collectionId: table.collectionId,
-                  inViews: table.inViews,
-                  identityConflict: table.identityConflict ?? false,
-                  onChange: (inViews) => { void handleSetTableDocumentInViews(table.collectionId, inViews); },
-                  onMakeIdentityUnique: () => { void handleMakeTableIdentityUnique(table.relativePath); },
-                }}
-                onRename={handleRenameTableDocument}
-                onDeleteFile={handleDeleteTableDocument}
-                onPointerDown={() => {}}
-                onFocus={handleFocusPath}
-                tabIndex={0}
-              />;
-            })}
-            {viewMediaLibraries.map((library) => {
-              const libraryPath = joinNotebookMemoPath(notebookPath, library.relativePath);
-              if (!libraryPath) return null;
-              const active = Boolean(!selectedFolderPath && activeFilePath && samePath(activeFilePath, libraryPath));
-              const libraryItem = mediaLibraryTreeItem(library, libraryPath);
-              const parentPath = parentDirectoryPath(libraryPath, notebookPath);
-              return <NotebookTreeRow
-                key={library.relativePath}
-                item={libraryItem}
-                notebookPath={notebookPath}
-                parentPath={parentPath}
-                depth={0}
-                expanded={false}
-                active={active}
-                selected={active}
-                onToggle={() => {}}
-                onOpen={() => handleOpenPath(libraryPath)}
-                onOpenInNewTab={onNoteOpenInNewTab ? handleOpenPathInNewTab : undefined}
-                onCreateNote={handleCreateNoteAtPath}
-                onCreateFolder={handleCreateFolderAtPath}
-                onCreateView={(parentPath, viewType) => openNewTableDialog(true, parentPath, viewType)}
-                onCreateMediaLibrary={(parentPath) => openNewMediaLibraryDialog(true, parentPath)}
-                mediaLibraryViewVisibility={{
-                  inViews: library.inViews,
-                  identityConflict: library.identityConflict ?? false,
-                  onChange: (inViews) => { void handleSetMediaLibraryInViews(library.collectionId, inViews); },
-                  onMakeIdentityUnique: () => { void handleMakeMediaLibraryIdentityUnique(library.relativePath); },
-                }}
-                onRename={handleRename}
-                onDeleteFile={handleDeleteMediaLibrary}
-                onPointerDown={() => {}}
-                onFocus={handleFocusPath}
-                tabIndex={0}
-              />;
-            })}
-            </div>}
-          </section>}
+              )}
+              renderTable={(table) => {
+                const tablePath = joinNotebookMemoPath(notebookPath, table.relativePath);
+                if (!tablePath) return null;
+                const active = Boolean(!selectedFolderPath && activeFilePath && samePath(activeFilePath, tablePath));
+                const tableItem = tableDocumentTreeItem(table, tablePath);
+                return (
+                  <NotebookTreeRow
+                    key={table.relativePath}
+                    item={tableItem}
+                    notebookPath={notebookPath}
+                    parentPath={parentDirectoryPath(tablePath, notebookPath)}
+                    depth={0}
+                    expanded={false}
+                    active={active}
+                    selected={active}
+                    onToggle={() => {}}
+                    onOpen={() => handleOpenTableDocument(table.relativePath)}
+                    onOpenInNewTab={onNoteOpenInNewTab ? handleOpenPathInNewTab : undefined}
+                    onCreateNote={handleCreateNoteAtPath}
+                    onCreateFolder={handleCreateFolderAtPath}
+                    onCreateView={(parentPath, viewType) => openNewTableDialog(true, parentPath, viewType)}
+                    onCreateMediaLibrary={(parentPath) => openNewMediaLibraryDialog(true, parentPath)}
+                    tableViewVisibility={{
+                      collectionId: table.collectionId,
+                      inViews: table.inViews,
+                      identityConflict: table.identityConflict ?? false,
+                      onChange: (inViews) => { void handleSetTableDocumentInViews(table.collectionId, inViews); },
+                      onMakeIdentityUnique: () => { void handleMakeTableIdentityUnique(table.relativePath); },
+                    }}
+                    onRename={handleRenameTableDocument}
+                    onDeleteFile={handleDeleteTableDocument}
+                    onPointerDown={() => {}}
+                    onFocus={handleFocusPath}
+                    tabIndex={0}
+                  />
+                );
+              }}
+              renderMediaLibrary={(library) => {
+                const libraryPath = joinNotebookMemoPath(notebookPath, library.relativePath);
+                if (!libraryPath) return null;
+                const active = Boolean(!selectedFolderPath && activeFilePath && samePath(activeFilePath, libraryPath));
+                const libraryItem = mediaLibraryTreeItem(library, libraryPath);
+                return (
+                  <NotebookTreeRow
+                    key={library.relativePath}
+                    item={libraryItem}
+                    notebookPath={notebookPath}
+                    parentPath={parentDirectoryPath(libraryPath, notebookPath)}
+                    depth={0}
+                    expanded={false}
+                    active={active}
+                    selected={active}
+                    onToggle={() => {}}
+                    onOpen={() => handleOpenMediaLibraryFromViews(libraryPath)}
+                    onOpenInNewTab={onNoteOpenInNewTab ? handleOpenPathInNewTab : undefined}
+                    onCreateNote={handleCreateNoteAtPath}
+                    onCreateFolder={handleCreateFolderAtPath}
+                    onCreateView={(parentPath, viewType) => openNewTableDialog(true, parentPath, viewType)}
+                    onCreateMediaLibrary={(parentPath) => openNewMediaLibraryDialog(true, parentPath)}
+                    mediaLibraryViewVisibility={{
+                      inViews: library.inViews,
+                      identityConflict: library.identityConflict ?? false,
+                      onChange: (inViews) => { void handleSetMediaLibraryInViews(library.collectionId, inViews); },
+                      onMakeIdentityUnique: () => { void handleMakeMediaLibraryIdentityUnique(library.relativePath); },
+                    }}
+                    onRename={handleRename}
+                    onDeleteFile={handleDeleteMediaLibrary}
+                    onPointerDown={() => {}}
+                    onFocus={handleFocusPath}
+                    tabIndex={0}
+                  />
+                );
+              }}
+            />
+          )}
           {!hiddenSections.includes('files') && <section
             className="flex min-h-0 flex-col pb-3"
             aria-label={t('memo.fileTree.sectionTitle')}
@@ -2296,7 +1514,8 @@ export function NotebookFileTree({
               <ChevronRight className={cn('h-3.5 w-3.5 opacity-0 transition-[opacity,transform] group-hover:opacity-100 group-focus-within:opacity-100', filesCollapsed && 'opacity-100', !filesCollapsed && 'rotate-90')} />
             </button>
             <div className="ml-auto flex items-center">
-              <TreeSectionMoreMenu
+              <NotebookTreeSectionMenu
+                onHideSection={() => hideTreeSection('files')}
                 canMoveUp={visibleSectionOrder.indexOf('files') > 0}
                 canMoveDown={visibleSectionOrder.indexOf('files') < visibleSectionOrder.length - 1}
                 onMoveUp={() => moveTreeSection('files', -1)}
@@ -2306,6 +1525,7 @@ export function NotebookFileTree({
                 onCreateTable={(viewType) => openNewTableDialog(false, undefined, viewType)}
                 onCreateMediaLibrary={() => openNewMediaLibraryDialog()}
                 onImportFiles={() => { void handleImportFiles(notebookPath); }}
+                onImportFolder={() => { void handleImportFolder(notebookPath); }}
                 sort={fileTreeSort}
                 onSort={setFileTreeSort}
                 onCustomizeDisplay={openCustomizeDisplay}
@@ -2323,67 +1543,14 @@ export function NotebookFileTree({
               'relative min-h-0 flex-1 rounded-lg transition-colors duration-150',
               isRootDropTarget && 'bg-[color-mix(in_oklch,var(--brand)_10%,transparent)]',
             )}
-            onPointerMove={(event) => {
-              const drag = pointerDragRef.current;
-              if (!drag || event.pointerId !== drag.pointerId) return;
-              if (!drag.active) {
-                const distance = Math.hypot(event.clientX - drag.startX, event.clientY - drag.startY);
-                if (distance < 5) return;
-                drag.active = true;
-                setDragPreview({
-                  name: drag.sourceName,
-                  path: drag.sourcePath,
-                  count: drag.sourcePaths.length,
-                });
-              }
-              event.preventDefault();
-              updateDragPreviewPosition(event.clientX + 12, event.clientY + 12);
-              updatePointerDropTarget(event.clientX, event.clientY);
-              scheduleDragAutoScroll(event.clientX, event.clientY);
-            }}
-            onPointerUp={(event) => {
-              const drag = pointerDragRef.current;
-              if (!drag || event.pointerId !== drag.pointerId) return;
-              stopDragAutoScroll();
-              clearDragExpandTimer();
-              if (drag.captureElement.hasPointerCapture(drag.pointerId)) {
-                drag.captureElement.releasePointerCapture(drag.pointerId);
-              }
-              pointerDragRef.current = null;
-              setDragOverFolderPath(null);
-              setDragPreview(null);
-              if (!drag.active) return;
-              event.preventDefault();
-              const suppressedPaths = new Set(
-                drag.sourcePaths.map((sourcePath) => canonicalPath(sourcePath)),
-              );
-              suppressOpenPathsRef.current = suppressedPaths;
-              window.setTimeout(() => {
-                if (suppressOpenPathsRef.current === suppressedPaths) {
-                  suppressOpenPathsRef.current = new Set();
-                }
-              }, 0);
-              if (!drag.targetDirectoryPath) return;
-              void handleDrop(
-                drag.targetDirectoryPath,
-                drag.sourceItems,
-                drag.preserveSelectionAfterMove,
-              );
-            }}
-            onPointerCancel={(event) => {
-              const drag = pointerDragRef.current;
-              if (!drag || event.pointerId !== drag.pointerId) return;
-              stopDragAutoScroll();
-              clearDragExpandTimer();
-              pointerDragRef.current = null;
-              setDragOverFolderPath(null);
-              setDragPreview(null);
-            }}
+            onPointerMove={handleTreePointerMove}
+            onPointerUp={handleTreePointerUp}
+            onPointerCancel={handleTreePointerCancel}
           >
             {tree.error && (
               <div className="flex items-center justify-center gap-2 px-4 py-4 text-center text-xs text-[var(--muted-foreground)]" role="alert">
                 <span>{t('memo.fileTree.unreadableHint')}</span>
-                <Button type="button" size="xs" variant="ghost" onClick={() => void tree.reload()}>
+                <Button type="button" size="xs" variant="ghost" className="rounded-lg" onClick={() => void tree.reload()}>
                   {t('error.retry')}
                 </Button>
               </div>
@@ -2429,7 +1596,8 @@ export function NotebookFileTree({
               order={sectionOrder.indexOf('repositories') + 1}
               onHeightChange={handleRepositorySectionHeightChange}
               sectionActions={(
-                <TreeSectionMoreMenu
+                <NotebookTreeSectionMenu
+                  onHideSection={() => hideTreeSection('repositories')}
                   canMoveUp={visibleSectionOrder.indexOf('repositories') > 0}
                   canMoveDown={visibleSectionOrder.indexOf('repositories') < visibleSectionOrder.length - 1}
                   onMoveUp={() => moveTreeSection('repositories', -1)}
@@ -2453,15 +1621,11 @@ export function NotebookFileTree({
                 onCreateFolder={() => handleCreateFolderAtPath(notebookPath)}
                 onCreateTable={(viewType) => openNewTableDialog(false, notebookPath, viewType)}
                 onCreateMediaLibrary={() => openNewMediaLibraryDialog(false, notebookPath)}
-                onImport={() => { void handleImportFiles(notebookPath); }}
+                onImportFiles={() => { void handleImportFiles(notebookPath); }}
+                onImportFolder={() => { void handleImportFolder(notebookPath); }}
               />
-              <ContextMenuItem
-                onClick={(event) => {
-                  setCustomizeAnchorRect(getPopupOriginRect(event.currentTarget));
-                  setCustomizeOrder([...sectionOrder]);
-                  setCustomizeHidden([...hiddenSections]);
-                  setCustomizeOpen(true);
-                }}
+              <ContextMenuItem keepOpenOnClick
+                onClick={(event) => openCustomizeDisplay(getPopupOriginRect(event.currentTarget))}
                 className="h-7 items-center justify-start rounded-lg px-2 py-0 text-left transition-colors hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
               >
                 <SquaresFourIcon className="mr-2 h-4 w-4" aria-hidden="true" />
@@ -2472,7 +1636,7 @@ export function NotebookFileTree({
         </OverlayScrollbar>
         {!hasVisibleItems && tree.loading && (
           <ListSurfaceLoadingState
-            label={t('memo.fileTree.loading')}
+            ariaLabel={t('memo.fileTree.loading')}
             className="absolute inset-0 z-[2] bg-[var(--list-bg)]"
           />
         )}
@@ -2531,7 +1695,7 @@ export function NotebookFileTree({
             <div className="flex justify-end gap-2">
               <Button type="button" variant="outline" size="sm" className="h-8 rounded-lg text-sm" onClick={() => setNewTableDialogOpen(false)}>{t('dialog.cancel')}</Button>
               <Button type="submit" size="sm" className="h-8 rounded-lg text-sm" disabled={!newTableName.trim() || isCreatingTable}>
-                {isCreatingTable ? <Loader2 className="mr-1.5 h-4 w-4 animate-spin" aria-hidden="true" /> : null}
+                {isCreatingTable ? <Loader2 className="mr-1.5 h-4 w-4 flowix-spin" aria-hidden="true" /> : null}
                 {isCreatingTable ? t('memo.create.creating') : t('memo.create.confirm')}
               </Button>
             </div>
@@ -2549,7 +1713,7 @@ export function NotebookFileTree({
             <div className="flex justify-end gap-2">
               <Button type="button" variant="outline" size="sm" className="rounded-lg" onClick={() => setNewLibraryDialogOpen(false)}>{t('dialog.cancel')}</Button>
               <Button type="submit" size="sm" className="rounded-lg" disabled={!newLibraryName.trim() || isCreatingLibrary}>
-                {isCreatingLibrary ? <Loader2 className="mr-1.5 h-4 w-4 animate-spin" aria-hidden="true" /> : null}
+                {isCreatingLibrary ? <Loader2 className="mr-1.5 h-4 w-4 flowix-spin" aria-hidden="true" /> : null}
                 {isCreatingLibrary ? t('memo.create.creating') : t('memo.create.confirm')}
               </Button>
             </div>
@@ -2557,17 +1721,13 @@ export function NotebookFileTree({
         </DialogContent>
       </Dialog>
       <Popover open={customizeOpen} onOpenChange={setCustomizeOpen} anchorRect={customizeAnchorRect}>
-        <PopoverContent side="bottom" align="start" sideOffset={0} className="w-[190px] max-w-[calc(100vw-16px)] rounded-2xl p-[5px] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-          <DialogHeader className="mb-0 flex min-h-8 items-center justify-between px-1">
-            <DialogTitle className="text-sm">{t('memo.fileTree.customizeDisplay')}</DialogTitle>
-            <button type="button" className="rounded-md px-2 py-1 text-xs font-medium text-[var(--primary)] transition-colors hover:bg-[var(--muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]" onClick={() => {
-              setSectionOrder(customizeOrder);
-              setHiddenSections(customizeHidden);
-              if (notebookId) {
-                void system.setNotebookFileTreeSectionOrder(notebookId, customizeOrder, customizeHidden).catch((error) => logger.warn('failed to save notebook file tree preferences', { error, notebookId }));
-              }
-              setCustomizeOpen(false);
-            }}>完成</button>
+        <PopoverContent side="bottom" align="start" sideOffset={0} alignToAnchorOrigin keepParentMenuOpen className="w-[190px] max-w-[calc(100vw-16px)] rounded-2xl p-[5px] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+          <DialogHeader className="mb-0 flex min-h-8 flex-row items-center justify-between px-1">
+            <button type="button" aria-label="返回上一级菜单" title="返回上一级菜单" onClick={() => setCustomizeOpen(false)} className="inline-flex min-w-0 shrink-0 items-center gap-0.5 rounded px-0 text-xs leading-[1.2] text-[var(--muted-foreground)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]">
+              <ChevronLeft className="h-3.5 w-3.5" aria-hidden="true" />
+              <span className="min-w-0 truncate text-xs leading-[1.2]">{t('memo.fileTree.customizeDisplay')}</span>
+            </button>
+            <DialogTitle className="sr-only">{t('memo.fileTree.customizeDisplay')}</DialogTitle>
           </DialogHeader>
           <div className="space-y-0.5" aria-label="文件树分区展示与顺序">
             {customizeOrder.map((section) => {
@@ -2581,10 +1741,6 @@ export function NotebookFileTree({
               const selected = !customizeHidden.includes(section);
               return <div key={section} data-customize-section={section} className={cn('group relative flex h-8 items-center gap-2 rounded-lg px-2 transition-colors hover:bg-[var(--muted)]', draggedSection.current === section && 'opacity-50')}>
                 {sectionDropTarget?.section === section && draggedSection.current !== section && <span aria-hidden="true" className={cn('pointer-events-none absolute inset-x-1 z-10 h-0.5 rounded-full bg-[var(--primary)]', sectionDropTarget.after ? '-bottom-0.5' : '-top-0.5')} />}
-                <button type="button" role="checkbox" aria-checked={selected} aria-label={`展示${labels[section]}`} onClick={() => setCustomizeHidden((current) => selected ? [...current, section] : current.filter((item) => item !== section))} className={cn('notebook-file-tree__display-checkbox focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]', selected && 'notebook-file-tree__display-checkbox--checked')}>
-                  {selected && <span className="notebook-file-tree__display-checkbox-mark" aria-hidden="true" />}
-                </button>
-                <span className="min-w-0 flex-1 truncate text-xs font-medium text-[var(--foreground)]">{labels[section]}</span>
                 <button type="button" onPointerDown={(event) => {
                   if (event.button !== 0) return;
                   draggedSection.current = section;
@@ -2608,11 +1764,11 @@ export function NotebookFileTree({
                   if (sectionDragPointerId.current !== event.pointerId) return;
                   const source = draggedSection.current;
                   const target = sectionDropTargetRef.current;
-                  if (source && target) setCustomizeOrder((current) => {
-                    const next = current.filter((item) => item !== source);
+                  if (source && target) {
+                    const next = customizeOrder.filter((item) => item !== source);
                     next.splice(next.indexOf(target.section) + (target.after ? 1 : 0), 0, source);
-                    return next;
-                  });
+                    updateCustomizeSectionOrder(next);
+                  }
                   draggedSection.current = null;
                   sectionDragPointerId.current = null;
                   sectionDropTargetRef.current = null;
@@ -2626,17 +1782,21 @@ export function NotebookFileTree({
                   const direction = event.key === 'ArrowUp' ? -1 : event.key === 'ArrowDown' ? 1 : 0;
                   if (!direction) return;
                   event.preventDefault();
-                  setCustomizeOrder((current) => {
-                    const index = current.indexOf(section);
-                    const target = index + direction;
-                    if (target < 0 || target >= current.length) return current;
-                    const next = [...current];
-                    [next[index], next[target]] = [next[target], next[index]];
-                    return next;
-                  });
+                  const index = customizeOrder.indexOf(section);
+                  const target = index + direction;
+                  if (target < 0 || target >= customizeOrder.length) return;
+                  const next = [...customizeOrder];
+                  [next[index], next[target]] = [next[target], next[index]];
+                  updateCustomizeSectionOrder(next);
                 }} aria-label={`排序${labels[section]}，使用上下方向键调整`} className="flex h-7 w-7 shrink-0 cursor-grab touch-none items-center justify-center rounded-md text-[var(--muted-foreground)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)] active:cursor-grabbing">
                   <GripVertical className="h-4 w-4" aria-hidden="true" />
                 </button>
+                <span className="min-w-0 flex-1 truncate text-sm font-medium text-[var(--foreground)]">{labels[section]}</span>
+                <FlowixCheckbox
+                  checked={selected}
+                  aria-label={`展示${labels[section]}`}
+                  onCheckedChange={(checked) => updateCustomizeSectionVisibility(section, checked)}
+                />
               </div>;
             })}
           </div>
diff --git a/app/flowix-web/features/memo/components/notebook-folder-import.ts b/app/flowix-web/features/memo/components/notebook-folder-import.ts
new file mode 100644
index 000000000..1c0c8800d
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-folder-import.ts
@@ -0,0 +1,27 @@
+import type { I18nKey } from '@/lib/i18n';
+import { normalizeNotebookMoveFailure } from './notebook-move-failure-toast';
+
+/** Keep folder-import error handling consistent across notebook and repository trees. */
+export function getNotebookFolderImportErrorKey(error: unknown): I18nKey {
+  const { code } = normalizeNotebookMoveFailure(error);
+  switch (code) {
+    case 'IMPORT_FOLDER_TOO_MANY_FILES':
+      return 'memo.fileTree.importFolderTooManyFiles';
+    case 'IMPORT_FOLDER_TOO_MANY_ENTRIES':
+      return 'memo.fileTree.importFolderTooManyEntries';
+    case 'IMPORT_FOLDER_TOO_DEEP':
+      return 'memo.fileTree.importFolderTooDeep';
+    case 'IMPORT_FOLDER_TOO_LARGE':
+      return 'memo.fileTree.importFolderTooLarge';
+    case 'FILE_EXISTS':
+      return 'memo.fileTree.importFolderExists';
+    case 'FILE_PERMISSION_DENIED':
+      return 'memo.fileTree.movePermissionDenied';
+    case 'CLOUD_FILE_NOT_DOWNLOADED':
+      return 'memo.fileTree.moveCloudFileNotDownloaded';
+    case 'IMPORT_FOLDER_CLEANUP_FAILED':
+      return 'memo.fileTree.importFolderCleanupFailed';
+    default:
+      return 'memo.fileTree.importFolderFailed';
+  }
+}
diff --git a/app/flowix-web/features/memo/components/notebook-folder-view.test.ts b/app/flowix-web/features/memo/components/notebook-folder-view.test.ts
deleted file mode 100644
index 5e7b4cdd1..000000000
--- a/app/flowix-web/features/memo/components/notebook-folder-view.test.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import type { DocTreeItem } from '@platform/tauri/client';
-import { sortNotebookTreeItems } from './notebook-folder-view';
-
-function item(name: string, type: DocTreeItem['type']): DocTreeItem {
-  return {
-    id: name,
-    fullPath: `/notebook/${name}`,
-    name,
-    type,
-    parentId: null,
-    children: type === 'folder' ? [] : null,
-    sizeBytes: null,
-    modifiedMs: null,
-    createdMs: null,
-    memoCreatedMs: null,
-  };
-}
-
-describe('notebook folder sorting', () => {
-  it('keeps folders first and sorts notes by creation time descending', () => {
-    const folder = item('projects', 'folder');
-    const older = { ...item('older.md', 'document'), createdMs: 10, modifiedMs: 30 };
-    const newer = { ...item('newer.md', 'document'), createdMs: 20, modifiedMs: 15 };
-
-    expect(sortNotebookTreeItems([older, newer, folder]).map((entry) => entry.name))
-      .toEqual(['projects', 'newer.md', 'older.md']);
-  });
-
-  it('uses the indexed memo creation time when the file was atomically replaced', () => {
-    const replacedOlder = {
-      ...item('older.md', 'document'),
-      createdMs: 100,
-      memoCreatedMs: 10,
-    };
-    const genuinelyNewer = {
-      ...item('newer.md', 'document'),
-      createdMs: 20,
-      memoCreatedMs: 20,
-    };
-
-    expect(sortNotebookTreeItems([replacedOlder, genuinelyNewer]).map((entry) => entry.name))
-      .toEqual(['newer.md', 'older.md']);
-  });
-});
diff --git a/app/flowix-web/features/memo/components/notebook-folder-view.tsx b/app/flowix-web/features/memo/components/notebook-folder-view.tsx
index c118be445..a18f09b57 100644
--- a/app/flowix-web/features/memo/components/notebook-folder-view.tsx
+++ b/app/flowix-web/features/memo/components/notebook-folder-view.tsx
@@ -1,11 +1,12 @@
 'use client';
 
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 
 import { canonicalDirectoryPath, canonicalPath, parentDirectoryPath } from '@/lib/path';
 import { createLogger } from '@/lib/logger';
 import { toast } from '@/lib/toast';
 import { useI18n } from '@/lib/i18n';
+import { normalizeNotebookMoveFailure, type NotebookMoveFailure } from './notebook-move-failure-toast';
 import { resourceKindFromPath } from '@features/editor/public/code-file';
 import {
   NotebookFileTree,
@@ -17,18 +18,13 @@ import {
 import { useFolderTree } from '@features/memo/components/use-folder-tree';
 import { updateNoteLinksAfterMove } from '@features/memo/services/note-link-rewriter';
 import { openNotebookNote } from '@features/memo/use-cases/open-notebook-note';
-import {
-  openBrowserColumnFileBrowser,
-  openBrowserColumnMedia,
-  openBrowserColumnText,
-} from '@features/workspace/use-cases/browser-column-navigation';
-import {
-  openExternalTarget,
-  openMediaTarget,
-  openFolderCollectionOrList,
-} from '@features/workspace/use-cases/workspace-navigation';
+import { openFolderCollectionFromFolder } from '@features/workspace/public/main-window-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { createFileBrowserTarget } from '@features/workspace/public/browser-column-api';
+import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focus-store';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
-import { createDocumentListTarget, workColumnTargetFilePath } from '@features/workspace/store/work-column-target';
+import { clearWorkspaceTargetsForDeletedDirectory } from '@features/workspace/public/shell-api';
+import { workColumnTargetFilePath } from '@features/workspace/store/work-column-target';
 import {
   files,
   mediaResources,
@@ -42,15 +38,6 @@ import { type Notebook } from '@features/memo/store';
 const FILE_BROWSER_DIRECTORIES_CHANGED_EVENT = 'file-browser-directories-changed';
 const logger = createLogger('notebook-folder-view');
 
-export function sortNotebookTreeItems(items: DocTreeItem[]): DocTreeItem[] {
-  const timestamp = (item: DocTreeItem) => item.memoCreatedMs ?? item.createdMs ?? 0;
-  return [...items].sort((left, right) => {
-    if (left.type !== right.type) return left.type === 'folder' ? -1 : 1;
-    if (left.type === 'folder') return left.name.localeCompare(right.name);
-    return timestamp(right) - timestamp(left) || left.name.localeCompare(right.name);
-  });
-}
-
 export function NotebookFolderView({
   notebook,
   createFolderRequest,
@@ -74,45 +61,15 @@ export function NotebookFolderView({
   const tree = useFolderTree(notebook.path, {
     enabled: isActive,
   });
-  const noteTree = useMemo(() => {
-    if (!isActive) return tree;
-    return {
-      ...tree,
-      rootChildren: sortNotebookTreeItems(tree.rootChildren),
-      nodes: new Map([...tree.nodes].map(([path, item]) => [
-        path,
-        item.children
-          ? {
-              ...item,
-                children: sortNotebookTreeItems(item.children),
-            }
-          : item,
-      ])),
-    };
-  }, [
-    isActive,
-    notebook.path,
-    tree.rootChildren,
-    tree.nodes,
-    tree.expanded,
-    tree.loading,
-    tree.error,
-    tree.toggle,
-    tree.expandTo,
-    tree.collapseAll,
-    tree.refresh,
-    tree.refreshDirectories,
-    tree.reload,
-  ]);
   const activeFilePath = useWorkColumnStore((state) => (
     workColumnTargetFilePath(state.navigation.target)
   ));
   const refreshDirectoriesRef = useRef(tree.refreshDirectories);
   refreshDirectoriesRef.current = tree.refreshDirectories;
 
-  useEffect(() => subscribe<{ notebookId: string }>('file-management-changed', ({ notebookId }) => {
-    if (isActive && notebookId === notebook.id) void tree.reload();
-  }), [isActive, notebook.id, tree.reload]);
+  useEffect(() => subscribe<{ notebookId: string; operationId?: string }>('file-management-changed', ({ notebookId, operationId }) => {
+    if (isActive && notebookId === notebook.id && !operationId) void tree.refresh();
+  }), [isActive, notebook.id, tree.refresh]);
 
   useEffect(() => subscribe<{ notebookPath: string; treeVisibilityChanged: boolean }>(
     'notebook-view-preferences-changed',
@@ -163,16 +120,14 @@ export function NotebookFolderView({
       if (resourceKindFromPath(filePath) !== 'note') {
         const resourceKind = resourceKindFromPath(filePath);
         if (resourceKind === 'image' || resourceKind === 'video') {
-          await openMediaTarget({
-            filePath,
-            notebookId: notebook.id,
-            notebookPath: notebook.path,
-            resourceKind,
+          await openWorkspaceSurface({
+            host: 'main-third',
+            target: { kind: 'media', filePath, notebookId: notebook.id, notebookPath: notebook.path, resourceKind },
           });
         } else {
-          await openExternalTarget(filePath, {
-            scopePath: notebook.path,
-            destination: 'main-third',
+          await openWorkspaceSurface({
+            host: 'main-third',
+            target: { kind: 'external', path: filePath, scopePath: notebook.path, transitionId: null },
           });
         }
         return;
@@ -192,13 +147,22 @@ export function NotebookFolderView({
       if (resourceKindFromPath(filePath) !== 'note') {
         const resourceKind = resourceKindFromPath(filePath);
         if (resourceKind === 'image' || resourceKind === 'video') {
-          await openBrowserColumnMedia(filePath, notebook.id, notebook.path, resourceKind);
+          await openWorkspaceSurface({
+            host: 'browser-column',
+            target: { kind: 'media', filePath, notebookId: notebook.id, notebookPath: notebook.path, resourceKind },
+          });
         } else {
-          await openBrowserColumnFileBrowser(notebook.path, filePath);
+          await openWorkspaceSurface({
+            host: 'browser-column',
+            target: createFileBrowserTarget(filePath, notebook.path, notebook.path),
+          });
         }
         return;
       }
-      await openBrowserColumnText(filePath, notebook.path);
+      await openWorkspaceSurface({
+        host: 'browser-column',
+        target: { kind: 'external', path: filePath, scopePath: notebook.path, transitionId: null },
+      });
     } catch (error) {
       logger.warn('opening notebook tree file in new tab failed', { error, filePath });
       toast.error(t('memo.fileTree.openFailed'));
@@ -210,11 +174,16 @@ export function NotebookFolderView({
     const root = canonicalDirectoryPath(notebook.path);
     const target = canonicalDirectoryPath(targetDirectoryPath);
     if (target !== root && !target.startsWith(`${root}/`)) {
-      return { movedPaths: [], failedPaths: sourcePaths };
+      return {
+        movedPaths: [],
+        failedPaths: sourcePaths,
+        failures: sourcePaths.map(() => ({ code: 'FILE_PERMISSION_DENIED' })),
+      };
     }
     const parentRelativePath = target === root ? '' : target.slice(root.length + 1);
     const movedPaths: string[] = [];
     const failedPaths: string[] = [];
+    const failures: NotebookMoveFailure[] = [];
     for (const source of sources) {
       const sourcePath = source.path;
       try {
@@ -249,15 +218,22 @@ export function NotebookFolderView({
       } catch (error) {
         logger.warn('moving notebook tree item failed', { error, sourcePath, targetDirectoryPath });
         failedPaths.push(sourcePath);
+        failures.push(normalizeNotebookMoveFailure(error));
       }
     }
-    return { movedPaths, failedPaths };
+    return { movedPaths, failedPaths, failures };
   }, [notebook.id, notebook.path]);
 
   const deleteFolder = useCallback(async (folderPath: string) => {
     try {
       const ok = await files.deleteFolder(folderPath, notebook.path);
       if (!ok) throw new Error('delete failed');
+      try {
+        await clearWorkspaceTargetsForDeletedDirectory(folderPath);
+      } catch (cleanupError) {
+        logger.warn('folder deleted, but workspace targets could not be fully cleared', { cleanupError, folderPath });
+        toast.error(t('memo.fileTree.deleteFolderViewCleanupFailed'));
+      }
       const parent = folderPath.slice(0, folderPath.replace(/[\\/]+$/, '').lastIndexOf('/')) || notebook.path;
       await tree.refresh(parent);
       toast.success(t('memo.fileTree.deleted', { name: folderPath.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? folderPath }));
@@ -286,12 +262,13 @@ export function NotebookFolderView({
   }, [notebook.path, t, tree.refresh]);
 
   return (
+    <>
     <NotebookFileTree
       notebookId={notebook.id}
       notebookName={notebook.name}
       notebookPath={notebook.path}
       activeFilePath={activeFilePath}
-      tree={noteTree}
+      tree={tree}
       isActive={isActive}
       defaultCreateFolder={defaultCreateFolder}
       onSetDefaultCreateFolder={onSetDefaultCreateFolder}
@@ -300,13 +277,11 @@ export function NotebookFolderView({
       onCreateFolder={onCreateFolder}
       onNoteSelect={(filePath) => { void openFile(filePath); }}
       onFolderSelect={(folderPath) => {
-        const target = createDocumentListTarget(
-          { kind: 'folder', path: folderPath, notebookPath: notebook.path, notebookId: notebook.id },
-          {},
-        );
-        void openFolderCollectionOrList(target).catch((error) => {
+        const host = useWorkspaceFocusStore.getState().focusedHostId;
+        const opening = openFolderCollectionFromFolder(notebook.id, folderPath, host);
+        void opening.catch((error) => {
           logger.warn('opening folder collection failed', { folderPath, error });
-          toast.error(error instanceof Error ? error.message : typeof error === 'string' ? error : '无法打开文件夹集合');
+          toast.error(error instanceof Error ? error.message : '无法打开文件夹集合');
         });
       }}
       onNoteOpenInNewTab={(filePath) => { void openFileInNewTab(filePath); }}
@@ -315,5 +290,6 @@ export function NotebookFolderView({
       onDeleteFolder={deleteFolder}
       onDeleteFile={deleteFile}
     />
+  </>
   );
 }
diff --git a/app/flowix-web/features/memo/components/notebook-icon-menu.tsx b/app/flowix-web/features/memo/components/notebook-icon-menu.tsx
index 935584ab3..7ad7906c7 100644
--- a/app/flowix-web/features/memo/components/notebook-icon-menu.tsx
+++ b/app/flowix-web/features/memo/components/notebook-icon-menu.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState, type FormEvent } from 'react';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -13,7 +13,12 @@ import { PREFERENCE_TAB_GROUPS } from '@features/preferences/public/app-api';
 import { AgentIcon } from '@features/agent/components/agent-icon';
 import productLogo from '@/assets/productlogo.png';
 import { cn } from '@/lib/utils';
+import { toast } from '@/lib/toast';
 import { openUrl } from '@platform/tauri/opener';
+import { Check, ChevronDown, Plus, X } from 'lucide-react';
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@shared/ui/dialog';
+import { cloud, type CloudFeedbackAttachment } from '@platform/tauri/client/cloud';
+import { product } from '@platform/tauri/client/desktop';
 
 interface NotebookIconMenuProps {
   /** 打开偏好设置窗口; 可传入偏好 tab id (如 'theme' / 'dsh' / 'mcp' / 'aiAgent')。 */
@@ -45,15 +50,112 @@ export function NotebookIconMenu({
 }: NotebookIconMenuProps) {
   const { t } = useI18n();
   const [open, setOpen] = useState(false);
+  const [feedbackOpen, setFeedbackOpen] = useState(false);
+  const [feedbackType, setFeedbackType] = useState<'product_suggestion' | 'usage_issue'>('product_suggestion');
+  const [feedbackTypeTriggerWidth, setFeedbackTypeTriggerWidth] = useState<number | null>(null);
+  const [feedbackText, setFeedbackText] = useState('');
+  const [feedbackFiles, setFeedbackFiles] = useState<File[]>([]);
+  const [feedbackBusy, setFeedbackBusy] = useState(false);
+  const feedbackBusyRef = useRef(false);
+  const [feedbackPreviews, setFeedbackPreviews] = useState<Array<{ file: File; url: string }>>([]);
+  const feedbackFileInputRef = useRef<HTMLInputElement | null>(null);
   const openTimerRef = useRef<number | null>(null);
   const closeTimerRef = useRef<number | null>(null);
   const visiblePreferenceGroups = PREFERENCE_TAB_GROUPS.map((group) => ({
     ...group,
-    tabs: group.tabs.filter(
-      (tab) => !['cloudSync', 'connections', 'tools', 'history', 'dsh', 'aiAgent'].includes(tab.id),
-    ),
+    tabs: group.tabs.filter((tab) => !('visibleInProductMenu' in tab) || tab.visibleInProductMenu !== false),
   }));
 
+  const openFeedback = () => {
+    setOpen(false);
+    setFeedbackOpen(true);
+  };
+
+  const addFeedbackFiles = useCallback((incoming: File[]) => {
+    if (incoming.length === 0) return;
+    const next = [...feedbackFiles, ...incoming];
+    if (next.length > 3 || next.some((file) => !['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(file.type) || file.size > 5 * 1024 * 1024)) {
+      toast.error(t('memo.list.notebookMenu.feedback.imageLimit'));
+      return;
+    }
+    setFeedbackFiles(next);
+  }, [feedbackFiles, t]);
+
+  useEffect(() => {
+    const previews = feedbackFiles.map((file) => ({ file, url: URL.createObjectURL(file) }));
+    setFeedbackPreviews(previews);
+    return () => previews.forEach(({ url }) => URL.revokeObjectURL(url));
+  }, [feedbackFiles]);
+
+  useEffect(() => {
+    if (!feedbackOpen) return;
+    const handlePaste = (event: ClipboardEvent) => {
+      if (feedbackBusyRef.current) {
+        event.preventDefault();
+        return;
+      }
+      const clipboardItems = Array.from(event.clipboardData?.items ?? []);
+      const images = clipboardItems
+        .filter((item) => item.kind === 'file' && item.type.startsWith('image/'))
+        .map((item) => item.getAsFile())
+        .filter((file): file is File => file !== null);
+      if (images.length === 0) return;
+      event.preventDefault();
+      addFeedbackFiles(images);
+    };
+    window.addEventListener('paste', handlePaste);
+    return () => window.removeEventListener('paste', handlePaste);
+  }, [feedbackOpen, addFeedbackFiles]);
+
+  const getFeedbackDeviceId = () => {
+    const storageKey = 'flowix:feedback-device-id:v1';
+    try {
+      const existing = localStorage.getItem(storageKey);
+      if (existing && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(existing)) return existing;
+      const deviceId = crypto.randomUUID();
+      localStorage.setItem(storageKey, deviceId);
+      return deviceId;
+    } catch {
+      return crypto.randomUUID();
+    }
+  };
+
+  const readFeedbackImages = async (): Promise<CloudFeedbackAttachment[]> => Promise.all(feedbackFiles.map(async (file) => {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    let binary = '';
+    for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    return { filename: file.name, contentType: file.type, dataBase64: btoa(binary) };
+  }));
+
+  const submitFeedback = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (feedbackBusyRef.current || !feedbackText.trim()) return;
+    feedbackBusyRef.current = true;
+    setFeedbackBusy(true);
+    try {
+      const productInfo = await product.getInfo();
+      const architecture = productInfo.arch === 'aarch64' ? 'arm64' : productInfo.arch === 'x86_64' ? 'x64' : productInfo.arch;
+      const platform = `${productInfo.os}-${architecture}`;
+      await cloud.submitFeedback(
+        getFeedbackDeviceId(),
+        feedbackType,
+        feedbackText.trim(),
+        productInfo.version,
+        platform,
+        await readFeedbackImages(),
+      );
+      toast.success(t('memo.list.notebookMenu.feedback.submitSucceeded'));
+      setFeedbackOpen(false);
+      setFeedbackText('');
+      setFeedbackFiles([]);
+    } catch {
+      toast.error(t('memo.list.notebookMenu.feedback.submitFailed'));
+    } finally {
+      feedbackBusyRef.current = false;
+      setFeedbackBusy(false);
+    }
+  };
+
   const cancelOpen = useCallback(() => {
     if (openTimerRef.current !== null) {
       window.clearTimeout(openTimerRef.current);
@@ -150,7 +252,7 @@ export function NotebookIconMenu({
                 ) : (
                   tab.icon
                 )}
-                <span>{tab.id === 'mcp' ? 'MCP' : t(tab.labelKey)}</span>
+                <span>{t(tab.labelKey)}</span>
               </DropdownMenuItem>
             ))}
           </div>
@@ -163,14 +265,81 @@ export function NotebookIconMenu({
           className={NOTEBOOK_ICON_MENU_ITEM_CLASS}
         >
           <span>{t('memo.list.notebookMenu.officialWebsite')}</span>
+          <span className="ml-auto font-mono text-xs text-[var(--muted-foreground)]">Flowix.CC</span>
         </DropdownMenuItem>
         <DropdownMenuItem
           onClick={() => void openUrl(COMMUNITY_URL)}
           className={NOTEBOOK_ICON_MENU_ITEM_CLASS}
         >
           <span>{t('memo.list.notebookMenu.community')}</span>
+          <span className="ml-auto font-mono text-xs text-[var(--muted-foreground)]">GitHub</span>
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={openFeedback} className={NOTEBOOK_ICON_MENU_ITEM_CLASS}>
+          <span>{t('memo.list.notebookMenu.feedback')}</span>
         </DropdownMenuItem>
       </DropdownMenuContent>
+      <Dialog open={feedbackOpen} onOpenChange={(next) => { if (!feedbackBusy) setFeedbackOpen(next); }}>
+        <DialogContent className="max-w-lg rounded-xl border border-[var(--border-popup)] bg-[var(--background)]">
+          <DialogHeader>
+            <DialogTitle>{t('memo.list.notebookMenu.feedback.title')}</DialogTitle>
+            <DialogDescription>{t('memo.list.notebookMenu.feedback.description')}</DialogDescription>
+          </DialogHeader>
+          <form className="mt-4 space-y-4" onSubmit={(event) => void submitFeedback(event)}>
+            <div className="space-y-1.5 text-sm">
+              <span className="block">{t('memo.list.notebookMenu.feedback.type')}<span className="ml-1 rounded-md bg-[color-mix(in_oklch,var(--success)_15%,transparent)] px-1.5 py-0.5 text-xs text-[var(--success)]">{t('memo.list.notebookMenu.feedback.required')}</span></span>
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild onClick={(event) => setFeedbackTypeTriggerWidth(event.currentTarget.getBoundingClientRect().width)}>
+                  <button type="button" aria-required="true" disabled={feedbackBusy} className="flex h-9 w-1/2 items-center justify-between rounded-lg border border-[var(--border)] bg-[var(--card)] px-3 text-left text-sm hover:bg-[var(--hover-bg)] disabled:opacity-50">
+                    <span>{t(`memo.list.notebookMenu.feedback.${feedbackType === 'product_suggestion' ? 'suggestion' : 'issue'}`)}</span>
+                    <ChevronDown className="h-4 w-4 text-[var(--muted-foreground)]" />
+                  </button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="start" sideOffset={4} style={{ width: feedbackTypeTriggerWidth ?? undefined }} className="min-w-0 space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+                  <DropdownMenuItem onClick={() => setFeedbackType('product_suggestion')} className="flex h-8 items-center justify-between rounded-lg px-2 hover:bg-[var(--hover-bg)]">
+                    <span>{t('memo.list.notebookMenu.feedback.suggestion')}</span>
+                    {feedbackType === 'product_suggestion' && <Check className="h-4 w-4 text-[var(--brand)]" />}
+                  </DropdownMenuItem>
+                  <DropdownMenuItem onClick={() => setFeedbackType('usage_issue')} className="flex h-8 items-center justify-between rounded-lg px-2 hover:bg-[var(--hover-bg)]">
+                    <span>{t('memo.list.notebookMenu.feedback.issue')}</span>
+                    {feedbackType === 'usage_issue' && <Check className="h-4 w-4 text-[var(--brand)]" />}
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </div>
+            <label className="block space-y-1.5 text-sm">
+              <span>{t('memo.list.notebookMenu.feedback.content')}<span className="ml-1 rounded-md bg-[color-mix(in_oklch,var(--success)_15%,transparent)] px-1.5 py-0.5 text-xs text-[var(--success)]">{t('memo.list.notebookMenu.feedback.required')}</span></span>
+              <textarea required maxLength={2000} disabled={feedbackBusy} value={feedbackText} onChange={(event) => setFeedbackText(event.target.value)} rows={6} className="w-full resize-none rounded-lg border border-[var(--border)] bg-[var(--card)] px-3 py-2 text-sm outline-none focus:border-[var(--brand)] disabled:opacity-50" placeholder={t('memo.list.notebookMenu.feedback.placeholder')} />
+            </label>
+            <div className="block space-y-1.5 text-sm">
+              <div className="flex items-center gap-2">
+                <span>{t('memo.list.notebookMenu.feedback.attachments')}</span>
+                <span className="text-sm text-[var(--muted-foreground)]">{t('memo.list.notebookMenu.feedback.imageHint')}</span>
+              </div>
+              <input ref={feedbackFileInputRef} type="file" disabled={feedbackBusy} aria-label={t('memo.list.notebookMenu.feedback.attachments')} accept="image/png,image/jpeg,image/webp,image/gif" multiple className="sr-only" onChange={(event) => {
+                const files = Array.from(event.target.files ?? []);
+                addFeedbackFiles(files);
+                event.target.value = '';
+              }} />
+              <div className="flex flex-wrap gap-2 pt-1">
+                {feedbackPreviews.map(({ file, url }, index) => <div key={`${file.name}-${file.lastModified}-${index}`} className="relative h-[100px] w-[100px] shrink-0 overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--card)]">
+                  <img src={url} alt={file.name} className="h-full w-full object-cover" />
+                  <span className="absolute inset-x-0 bottom-0 truncate bg-black/55 px-1.5 py-1 text-[10px] text-white" title={file.name}>{file.name}</span>
+                  <button type="button" disabled={feedbackBusy} onClick={() => setFeedbackFiles((current) => current.filter((_, fileIndex) => fileIndex !== index))} aria-label={t('memo.list.notebookMenu.feedback.removeImage')} title={t('memo.list.notebookMenu.feedback.removeImage')} className="absolute right-1 top-1 flex h-6 w-6 items-center justify-center rounded-full bg-black/55 text-white hover:bg-black/75">
+                    <X className="h-3.5 w-3.5" />
+                  </button>
+                </div>)}
+                {feedbackFiles.length < 3 && <button type="button" disabled={feedbackBusy} onClick={() => feedbackFileInputRef.current?.click()} aria-label={t('memo.list.notebookMenu.feedback.addImage')} title={t('memo.list.notebookMenu.feedback.addImage')} className="flex h-[100px] w-[100px] shrink-0 items-center justify-center rounded-xl border border-dashed border-[var(--border)] bg-[var(--card)] text-[var(--muted-foreground)] transition-colors hover:border-[var(--brand)] hover:bg-[var(--hover-bg)] hover:text-[var(--foreground)] disabled:opacity-50">
+                  <Plus className="h-7 w-7" />
+                </button>}
+              </div>
+            </div>
+            <div className="flex justify-end gap-2">
+              <button type="button" disabled={feedbackBusy} onClick={() => setFeedbackOpen(false)} className="h-9 rounded-lg border border-[var(--border)] px-3 text-sm">{t('memo.list.notebookMenu.feedback.cancel')}</button>
+              <button type="submit" disabled={feedbackBusy || !feedbackText.trim()} className="h-9 rounded-lg bg-[var(--brand)] px-4 text-sm text-white disabled:opacity-50">{feedbackBusy ? t('memo.list.notebookMenu.feedback.submitting') : t('memo.list.notebookMenu.feedback.submit')}</button>
+            </div>
+          </form>
+        </DialogContent>
+      </Dialog>
     </DropdownMenu>
   );
 }
diff --git a/app/flowix-web/features/memo/components/notebook-icon-popover.tsx b/app/flowix-web/features/memo/components/notebook-icon-popover.tsx
index 00206eaeb..399bf5812 100644
--- a/app/flowix-web/features/memo/components/notebook-icon-popover.tsx
+++ b/app/flowix-web/features/memo/components/notebook-icon-popover.tsx
@@ -14,12 +14,14 @@ interface NotebookIconPopoverProps {
   value: string | null;
   notebookName: string;
   onChange: (icon: string | null) => void;
+  disabled?: boolean;
 }
 
 export function NotebookIconPopover({
   value,
   notebookName,
   onChange,
+  disabled = false,
 }: NotebookIconPopoverProps) {
   const [open, setOpen] = useState(false);
   const selected = getNotebookIconOption(value);
@@ -29,10 +31,11 @@ export function NotebookIconPopover({
       <PopoverTrigger asChild>
         <button
           type="button"
+          disabled={disabled}
           className={cn(
             'flex h-10 w-10 shrink-0 items-center justify-center rounded-lg border border-input bg-[var(--card)] transition-colors',
             'hover:bg-[var(--muted)]/40 focus-visible:border-[var(--primary)] focus-visible:outline-none',
-            'data-[state=open]:border-[var(--primary)]',
+            'data-[state=open]:border-[var(--primary)] disabled:cursor-not-allowed disabled:opacity-50',
           )}
           aria-label="设置笔记本图标"
           title={selected?.label ?? '设置笔记本图标'}
diff --git a/app/flowix-web/features/memo/components/notebook-move-failure-toast.ts b/app/flowix-web/features/memo/components/notebook-move-failure-toast.ts
new file mode 100644
index 000000000..70f8ef6e1
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-move-failure-toast.ts
@@ -0,0 +1,111 @@
+import { toast } from '@/lib/toast';
+import type { I18nKey, I18nParams } from '@/lib/i18n';
+
+export interface NotebookMoveFailure {
+  code: string;
+  message?: string;
+}
+
+type MoveFailureKind = 'cloud' | 'permission' | 'source' | 'target' | 'duplicate';
+type MoveTranslator = (key: I18nKey, params?: I18nParams) => string;
+
+const FAILURE_KIND_BY_CODE: Record<string, MoveFailureKind> = {
+  FILE_EXISTS: 'duplicate',
+  EEXIST: 'duplicate',
+  CLOUD_FILE_NOT_DOWNLOADED: 'cloud',
+  ICLOUD_FILE_NOT_DOWNLOADED: 'cloud',
+  FILE_PERMISSION_DENIED: 'permission',
+  FILE_NOT_FOUND: 'source',
+  SOURCE_NOT_REGULAR_FILE: 'source',
+  SOURCE_NOT_DIRECTORY: 'source',
+  TARGET_NOT_DIRECTORY: 'target',
+};
+
+const LEGACY_ERROR_CODES = new Set([
+  ...Object.keys(FAILURE_KIND_BY_CODE),
+  'IMPORT_FOLDER_TOO_MANY_FILES',
+  'IMPORT_FOLDER_TOO_MANY_ENTRIES',
+  'IMPORT_FOLDER_TOO_DEEP',
+  'IMPORT_FOLDER_TOO_LARGE',
+  'IMPORT_FOLDER_CLEANUP_FAILED',
+  'IMPORT_FOLDER_SCAN_FAILED',
+]);
+
+/** Normalize Tauri's structured errors and legacy string errors in one place. */
+export function normalizeNotebookMoveFailure(error: unknown): NotebookMoveFailure {
+  if (typeof error === 'object' && error !== null && 'code' in error) {
+    const value = error as { code?: unknown; message?: unknown };
+    if (typeof value.code === 'string') {
+      return {
+        code: value.code,
+        ...(typeof value.message === 'string' ? { message: value.message } : {}),
+      };
+    }
+  }
+
+  const raw = error instanceof Error
+    ? error.message
+    : typeof error === 'string'
+      ? error
+      : String(error);
+  const separator = raw.indexOf(': ');
+  const prefix = separator < 0 ? raw : raw.slice(0, separator);
+  const code = LEGACY_ERROR_CODES.has(prefix) ? prefix : 'UNKNOWN';
+  return {
+    code,
+    ...(separator >= 0 ? { message: raw.slice(separator + 2) } : { message: raw }),
+  };
+}
+
+function failureKind(failure: NotebookMoveFailure): MoveFailureKind | null {
+  return FAILURE_KIND_BY_CODE[failure.code] ?? null;
+}
+
+export function showNotebookMoveFailureToasts(
+  t: MoveTranslator,
+  moved: number,
+  failed: number,
+  failures: NotebookMoveFailure[],
+) {
+  const counts: Record<Exclude<MoveFailureKind, 'duplicate'>, number> = {
+    cloud: 0,
+    permission: 0,
+    source: 0,
+    target: 0,
+  };
+  let duplicateCount = 0;
+  const unknownFailures: NotebookMoveFailure[] = [];
+  for (const failure of failures) {
+    const kind = failureKind(failure);
+    if (!kind) {
+      unknownFailures.push(failure);
+    } else if (kind === 'duplicate') {
+      duplicateCount += 1;
+    } else {
+      counts[kind] += 1;
+    }
+  }
+
+  if (duplicateCount > 0) toast.error(t('memo.fileTree.moveDuplicate'));
+  const messageKeys: Record<Exclude<MoveFailureKind, 'duplicate'>, I18nKey> = {
+    cloud: 'memo.fileTree.moveCloudFileNotDownloaded',
+    permission: 'memo.fileTree.movePermissionDenied',
+    source: 'memo.fileTree.moveSourceUnavailable',
+    target: 'memo.fileTree.moveTargetUnavailable',
+  };
+  for (const kind of Object.keys(counts) as Array<keyof typeof counts>) {
+    if (counts[kind] > 0) {
+      toast.error(t(messageKeys[kind], { moved, failed: counts[kind] }));
+    }
+  }
+
+  const classifiedCount = duplicateCount + Object.values(counts).reduce((sum, count) => sum + count, 0);
+  const unknownCount = Math.max(0, failed - classifiedCount);
+  if (unknownCount === 0) return;
+  const reason = unknownFailures[0]?.message ?? unknownFailures[0]?.code;
+  if (import.meta.env.DEV && reason) {
+    toast.error(t('memo.fileTree.movePartialFailedWithReason', { moved, failed: unknownCount, reason }));
+  } else {
+    toast.error(t('memo.fileTree.movePartialFailed', { moved, failed: unknownCount }));
+  }
+}
diff --git a/app/flowix-web/features/memo/components/notebook-repositories-section.tsx b/app/flowix-web/features/memo/components/notebook-repositories-section.tsx
index 8282d5b0d..9460fd1b1 100644
--- a/app/flowix-web/features/memo/components/notebook-repositories-section.tsx
+++ b/app/flowix-web/features/memo/components/notebook-repositories-section.tsx
@@ -16,6 +16,13 @@ import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } f
 import { ListSurfaceSpinner } from '@shared/ui/list-surface';
 import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuSubmenu, ContextMenuTrigger } from '@shared/ui/context-menu';
 import { NotebookCopyContextMenu } from './notebook-copy-context-menu';
+import {
+  normalizeNotebookMoveFailure,
+  showNotebookMoveFailureToasts,
+  type NotebookMoveFailure,
+} from './notebook-move-failure-toast';
+import { getNotebookFolderImportErrorKey } from './notebook-folder-import';
+import { clearWorkspaceTargetsForDeletedDirectory } from '@features/workspace/public/shell-api';
 import { useFolderTree } from './use-folder-tree';
 import { TREE_EDGE_GUTTER, INDENT_PER_LEVEL } from './notebook-tree-layout';
 
@@ -63,12 +70,14 @@ function AgentRepositoryItem({
     const currentName = isTableDocument || isMediaLibrary ? displayTitleFromFilename(item.name) : item.name;
     if (!name || name === currentName) return;
     try {
-      if (item.type === 'folder') await files.renameFolder(item.fullPath, name, repository.path);
+      if (item.type === 'folder') {
+        await tree.renameFolder(item.fullPath, name, repository.path);
+      }
       else {
         const extension = isTableDocument ? tableDocumentExtension(item.name) : isMediaLibrary ? mediaLibraryExtension(item.name) : '';
         await localDocumentOperations.rename({ path: item.fullPath, name: `${name}${extension}`, scopePath: repository.path });
       }
-      await tree.refresh(parentDirectoryPath(item.fullPath, repository.path));
+      if (item.type !== 'folder') await tree.refresh(parentDirectoryPath(item.fullPath, repository.path));
       toast.success(t('memo.fileTree.renamed', { name }));
     } catch (error) {
       toast.error(t(String(error).includes('FILE_EXISTS') ? 'memo.fileTree.nameConflict' : 'memo.fileTree.renameFailed'));
@@ -81,6 +90,14 @@ function AgentRepositoryItem({
         ? await files.deleteFolder(deleting.fullPath, repository.path)
         : await files.delete(deleting.fullPath, repository.path);
       if (!ok) throw new Error('delete failed');
+      if (deleting.type === 'folder') {
+        try {
+          await clearWorkspaceTargetsForDeletedDirectory(deleting.fullPath);
+        } catch (cleanupError) {
+          logger.warn('folder deleted, but workspace targets could not be fully cleared', { cleanupError, folderPath: deleting.fullPath });
+          toast.error(t('memo.fileTree.deleteFolderViewCleanupFailed'));
+        }
+      }
       await tree.refresh(parentDirectoryPath(deleting.fullPath, repository.path));
       toast.success(t('memo.fileTree.deleted', { name: deleting.name }));
       setDeleting(null);
@@ -92,17 +109,50 @@ function AgentRepositoryItem({
   const importIntoRepository = async (targetDirectoryPath: string) => {
     const selectedPaths = await dialogs.selectFiles({ multiple: true });
     if (!selectedPaths?.length) return;
-    let failed = 0;
+    const failures: NotebookMoveFailure[] = [];
     for (const sourcePath of selectedPaths) {
       try {
         await files.importFile(sourcePath, targetDirectoryPath, repository.path);
       } catch (error) {
         logger.warn('importing file into access space failed', { error, sourcePath, targetDirectoryPath });
-        failed += 1;
+        failures.push(normalizeNotebookMoveFailure(error));
       }
     }
     await tree.refresh(targetDirectoryPath);
-    if (failed) toast.error(t('memo.fileTree.movePartialFailed', { moved: selectedPaths.length - failed, failed }));
+    if (failures.length > 0) {
+      showNotebookMoveFailureToasts(
+        t,
+        selectedPaths.length - failures.length,
+        failures.length,
+        failures,
+      );
+    }
+  };
+  const importFolderIntoRepository = async (targetDirectoryPath: string) => {
+    let sourceDirectoryPath: string | null | undefined;
+    let progressToastId: string | number | undefined;
+    try {
+      sourceDirectoryPath = await dialogs.selectImportDirectory();
+      if (!sourceDirectoryPath) return;
+      progressToastId = toast.info(t('memo.fileTree.importFolderInProgress'), { duration: Number.POSITIVE_INFINITY });
+      await files.importFolder(sourceDirectoryPath, targetDirectoryPath, repository.path);
+      await tree.refresh(targetDirectoryPath);
+      toast.dismiss(progressToastId);
+      progressToastId = undefined;
+      toast.success(t('memo.fileTree.importFolderSuccess'));
+    } catch (error) {
+      logger.warn('importing folder into access space failed', { error, sourceDirectoryPath, targetDirectoryPath });
+      if (sourceDirectoryPath) {
+        try {
+          await tree.refresh(targetDirectoryPath);
+        } catch (refreshError) {
+          logger.warn('refreshing access space after folder import failed', { refreshError, targetDirectoryPath });
+        }
+      }
+      toast.error(t(getNotebookFolderImportErrorKey(error)));
+    } finally {
+      if (progressToastId !== undefined) toast.dismiss(progressToastId);
+    }
   };
   const renderRepositoryItems = (items: DocTreeItem[], depth: number): ReactNode[] => items.map((item) => {
     const isFolder = item.type === 'folder';
@@ -205,9 +255,12 @@ function AgentRepositoryItem({
       </ContextMenuTrigger>
       <ContextMenuContent className="w-[180px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
         {!isFolder && onOpenInNewTab && <ContextMenuItem onClick={() => onOpenInNewTab(item.fullPath)} className="h-7 items-center justify-start rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"><SquareSplitHorizontalIcon className="mr-2 h-4 w-4" aria-hidden="true" />{t('memo.fileTree.openInRight')}</ContextMenuItem>}
-        <ContextMenuSubmenu label={t('memo.create.more')} icon={<Plus className="h-4 w-4" aria-hidden="true" />}>
+        <ContextMenuSubmenu label={t('memo.fileTree.import')} icon={<Plus className="h-4 w-4" aria-hidden="true" />}>
           <ContextMenuItem onClick={() => { void importIntoRepository(isFolder ? item.fullPath : parentDirectoryPath(item.fullPath, repository.path)); }} className="h-7 items-center justify-start rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]">
-            {t('memo.fileTree.import')}
+            {t('memo.fileTree.importFiles')}
+          </ContextMenuItem>
+          <ContextMenuItem onClick={() => { void importFolderIntoRepository(isFolder ? item.fullPath : parentDirectoryPath(item.fullPath, repository.path)); }} className="h-7 items-center justify-start rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]">
+            {t('memo.fileTree.importFolder')}
           </ContextMenuItem>
         </ContextMenuSubmenu>
         <ContextMenuItem onClick={() => setRenaming({ item, value: item.type === 'document' && (isTableDocumentFilename(item.name) || isMediaLibraryFilename(item.name)) ? displayTitleFromFilename(item.name) : item.name })} className="h-7 items-center justify-start rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"><PencilSimpleIcon className="mr-2 h-4 w-4" aria-hidden="true" />{t('memo.fileTree.rename')}</ContextMenuItem>
@@ -263,8 +316,8 @@ function AgentRepositoryItem({
       {expanded && (
         <div className="folder-file-tree__items">
           {tree.loading && tree.nodes.size === 0 && (
-            <div className="flex min-h-7 items-center px-2 text-xs text-[var(--muted-foreground)]" style={{ marginLeft: TREE_EDGE_GUTTER + 20 }}>
-              {t('memo.fileTree.loading')}
+            <div className="flex min-h-7 items-center px-2" style={{ marginLeft: TREE_EDGE_GUTTER + 20 }}>
+              <ListSurfaceSpinner className="h-3.5 w-3.5" ariaLabel={t('memo.fileTree.loading')} />
             </div>
           )}
           {tree.error && (
@@ -403,4 +456,3 @@ export function AgentRepositoriesSection({
     </section>
   );
 }
-
diff --git a/app/flowix-web/features/memo/components/notebook-setup-coordinator.tsx b/app/flowix-web/features/memo/components/notebook-setup-coordinator.tsx
new file mode 100644
index 000000000..799f64ebd
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-setup-coordinator.tsx
@@ -0,0 +1,104 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useWorkspaceStartupStore } from '@/lib/store/workspace-startup-store';
+import { notebooks, type NotebookSetupJob } from '@platform/tauri/client';
+import { subscribe } from '@platform/tauri/event-bus';
+import {
+  replaceNotebookSetupSnapshot,
+  upsertNotebookSetupJob,
+  useNotebookSetupJob,
+} from '@features/memo/store/notebook-setup-store';
+import { useNoteStore } from '@features/memo/store';
+import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
+
+export function NotebookSetupCoordinator() {
+  const workspaceReady = useWorkspaceStartupStore((state) =>
+    (state.status === 'ready' || state.status === 'degraded') && state.workbenchMounted,
+  );
+  const selectedNotebookId = useNoteStore((state) => state.selectedNotebook?.id ?? null);
+  const navigationReady = useWorkColumnStore((state) =>
+    state.navigation.phase !== 'loading' && state.notebookSwitchesInFlight === 0,
+  );
+  const activeSetupJob = useNotebookSetupJob(selectedNotebookId);
+  const activePendingJobKey = activeSetupJob?.status === 'pending'
+    ? `${activeSetupJob.jobId}:${activeSetupJob.revision}`
+    : null;
+
+  useEffect(() => {
+    let active = true;
+    let retryTimer: number | undefined;
+    let retryAttempt = 0;
+
+    const refreshSnapshot = async () => {
+      if (!active) return;
+      if (retryTimer !== undefined) {
+        window.clearTimeout(retryTimer);
+        retryTimer = undefined;
+      }
+      try {
+        const snapshot = await notebooks.getTemplateSetupSnapshot();
+        if (!active) return;
+        retryAttempt = 0;
+        replaceNotebookSetupSnapshot(snapshot);
+      } catch (error) {
+        if (!active) return;
+        console.warn('[NotebookSetupCoordinator] Failed to refresh setup jobs:', error);
+        const delay = Math.min(1_000 * (2 ** retryAttempt), 30_000);
+        retryAttempt += 1;
+        retryTimer = window.setTimeout(() => {
+          retryTimer = undefined;
+          void refreshSnapshot();
+        }, delay);
+      }
+    };
+
+    const unsubscribe = subscribe<NotebookSetupJob>(
+      'notebook-setup-status',
+      upsertNotebookSetupJob,
+      { onListenerReady: () => { void refreshSnapshot(); } },
+    );
+    const unsubscribeNotebookChanges = subscribe<unknown>(
+      'notebooks-changed',
+      () => { void refreshSnapshot(); },
+    );
+    return () => {
+      active = false;
+      if (retryTimer !== undefined) window.clearTimeout(retryTimer);
+      unsubscribe();
+      unsubscribeNotebookChanges();
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!workspaceReady || !navigationReady) return;
+    let active = true;
+    let retryTimer: number | undefined;
+    let retryAttempt = 0;
+
+    const startAndRecoverReadyJobs = async () => {
+      if (!active) return;
+      try {
+        await notebooks.startOrResumeReadyTemplateSetups(selectedNotebookId);
+        retryAttempt = 0;
+      } catch (error) {
+        if (!active) return;
+        console.warn('[NotebookSetupCoordinator] Failed to start or resume setup jobs:', error);
+        const delay = Math.min(1_000 * (2 ** retryAttempt), 30_000);
+        retryAttempt += 1;
+        retryTimer = window.setTimeout(() => {
+          retryTimer = undefined;
+          void startAndRecoverReadyJobs();
+        }, delay);
+      }
+    };
+
+    void startAndRecoverReadyJobs();
+    return () => {
+      active = false;
+      if (retryTimer !== undefined) window.clearTimeout(retryTimer);
+    };
+  }, [activePendingJobKey, navigationReady, selectedNotebookId, workspaceReady]);
+
+  return null;
+}
diff --git a/app/flowix-web/features/memo/components/notebook-setup-notice-host.tsx b/app/flowix-web/features/memo/components/notebook-setup-notice-host.tsx
new file mode 100644
index 000000000..f48f92852
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-setup-notice-host.tsx
@@ -0,0 +1,66 @@
+'use client';
+
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+import { useI18n } from '@/lib/i18n';
+import { subscribeNotebookSetupJobs, getNotebookSetupJobs } from '@features/memo/store/notebook-setup-store';
+import {
+  clearActionableNotice,
+  dismissActionableNotice,
+  upsertActionableNotice,
+} from '@features/notifications/actionable-notice-store';
+
+const EMPTY_JOBS: ReturnType<typeof getNotebookSetupJobs> = [];
+
+export function NotebookSetupNoticeHost() {
+  const { t } = useI18n();
+  const jobs = useSyncExternalStore(
+    subscribeNotebookSetupJobs,
+    getNotebookSetupJobs,
+    () => EMPTY_JOBS,
+  );
+  const activeNoticeIdsRef = useRef(new Set<string>());
+
+  useEffect(() => {
+    const activeJobs = jobs.filter((job) => job.status === 'running');
+    const nextIds = new Set(activeJobs.map((job) => `notebook-setup-running:${job.jobId}`));
+
+    for (const noticeId of activeNoticeIdsRef.current) {
+      if (!nextIds.has(noticeId)) clearActionableNotice(noticeId);
+    }
+
+    for (const job of activeJobs) {
+      const noticeId = `notebook-setup-running:${job.jobId}`;
+      const title = job.stage === 'preparing'
+        ? t('notebook.setup.preparingTemplate')
+        : job.stage === 'indexing'
+          ? t('notebook.setup.indexing')
+          : t('notebook.setup.applyingTemplate');
+
+      upsertActionableNotice({
+        id: noticeId,
+        priority: 80,
+        tone: 'neutral',
+        width: 'narrow',
+        title,
+        leadingIcon: 'loading',
+        revision: `${job.jobId}:${job.runId || `revision:${job.revision}`}`,
+        dismissible: true,
+        actions: [{
+          id: 'hide',
+          label: t('notebook.setup.hide'),
+          variant: 'outline',
+          run: () => dismissActionableNotice(noticeId),
+        }],
+      });
+    }
+
+    activeNoticeIdsRef.current = nextIds;
+  }, [jobs, t]);
+
+  useEffect(() => () => {
+    for (const noticeId of activeNoticeIdsRef.current) clearActionableNotice(noticeId);
+    activeNoticeIdsRef.current.clear();
+  }, []);
+
+  return null;
+}
diff --git a/app/flowix-web/features/memo/components/notebook-tree-file-icon.tsx b/app/flowix-web/features/memo/components/notebook-tree-file-icon.tsx
index 82340ba84..ea42ace75 100644
--- a/app/flowix-web/features/memo/components/notebook-tree-file-icon.tsx
+++ b/app/flowix-web/features/memo/components/notebook-tree-file-icon.tsx
@@ -1,39 +1,2 @@
-import type { SVGProps } from 'react';
-
-/** Shared default document icon for files and notes in the notebook tree. */
-export function NotebookTreeFileIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="64"
-      height="64"
-      viewBox="0 0 18 18"
-      fill="none"
-      aria-hidden="true"
-      {...props}
-    >
-      <g transform="matrix(0.6923077 0 0 0.6923077 0.6923077 0.6923077)">
-        <line x1="7.6666" y1="11.36" x2="10.3333" y2="11.36" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
-        <line x1="7.6666" y1="15.18" x2="16.3333" y2="15.18" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.2" vectorEffect="non-scaling-stroke" />
-        <path
-          d="M 3.6667 19 V 5 c 0 -1.4733 1.1933 -2.6667 2.6667 -2.6667 h 7.448 c 0.3533 0 0.6933 0.14 0.9427 0.3907 l 5.2187 5.2187 c 0.2507 0.2507 0.3907 0.5893 0.3907 0.9427 v 10.1146 c 0 1.4733 -1.1933 2.6667 -2.6667 2.6667 H 6.3333 c -1.4733 0 -2.6667 -1.1933 -2.6667 -2.6667 Z"
-          fill="none"
-          stroke="currentColor"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          strokeWidth="1.2"
-          vectorEffect="non-scaling-stroke"
-        />
-        <path
-          d="M 20.2133 8.3333 h -4.5467 c -0.736 0 -1.3333 -0.5973 -1.3333 -1.3333 V 2.4693"
-          fill="none"
-          stroke="currentColor"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          strokeWidth="1.2"
-          vectorEffect="non-scaling-stroke"
-        />
-      </g>
-    </svg>
-  );
-}
+/** @deprecated Use ContentIcon with kind="note". */
+export { NoteContentIcon as NotebookTreeFileIcon } from '@features/content/components/note-content-icon';
diff --git a/app/flowix-web/features/memo/components/notebook-tree-layout.ts b/app/flowix-web/features/memo/components/notebook-tree-layout.ts
index 6b4d5c195..884b11773 100644
--- a/app/flowix-web/features/memo/components/notebook-tree-layout.ts
+++ b/app/flowix-web/features/memo/components/notebook-tree-layout.ts
@@ -1,3 +1,10 @@
 // Shared spacing for notebook rows and access-space rows.
 export const TREE_EDGE_GUTTER = 6;
 export const INDENT_PER_LEVEL = 20;
+export const TREE_ROW_HEIGHT = 32;
+export const TREE_ROW_GAP = 2;
+export const TREE_ROW_SIZE = TREE_ROW_HEIGHT + TREE_ROW_GAP;
+export const TREE_DRAG_SCROLL_EDGE = 40;
+export const TREE_DRAG_SCROLL_MAX_STEP = 18;
+export const TREE_DRAG_EXPAND_DELAY_MS = 650;
+export const TREE_EXTERNAL_DRAG_EXPAND_DELAY_MS = 1000;
diff --git a/app/flowix-web/features/memo/components/notebook-tree-row.tsx b/app/flowix-web/features/memo/components/notebook-tree-row.tsx
index e6e1456e8..ebac7ddce 100644
--- a/app/flowix-web/features/memo/components/notebook-tree-row.tsx
+++ b/app/flowix-web/features/memo/components/notebook-tree-row.tsx
@@ -37,8 +37,7 @@ import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } f
 import folderIcon from '@/assets/folder-outline.svg?raw';
 import { getPropertyIconOption } from '@features/document/properties/property-icons';
 import { resourceKindFromPath } from '@features/editor/code-file';
-import { NotebookTreeFileIcon } from '@features/memo/components/notebook-tree-file-icon';
-import { NotebookTreeResourceIcon } from '@features/memo/components/file-type-icon';
+import { ContentIcon } from '@features/content/public/content-api';
 import { files, notes, product, type DocTreeItem } from '@platform/tauri/client';
 import { logNativeContextMenuError } from '@platform/tauri/native-context-menu';
 import type { TableViewType } from '@features/multidimensional-table/public/create-api';
@@ -96,6 +95,7 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
   onCreateView,
   onCreateMediaLibrary,
   onImportFiles,
+  onImportFolder,
   onRename,
   onDeleteFolder,
   onDeleteFile,
@@ -133,7 +133,8 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
   onCreateView: (parentPath: string, viewType?: TableViewType) => void;
   onCreateMediaLibrary: (parentPath: string) => void;
   onImportFiles?: (parentPath: string) => void;
-  onRename: (item: DocTreeItem, nextName: string) => Promise<void> | void;
+  onImportFolder?: (parentPath: string) => void;
+  onRename: (item: DocTreeItem, nextName: string) => Promise<boolean | void> | boolean | void;
   onPointerDown: (item: DocTreeItem, event: ReactPointerEvent<HTMLDivElement>) => void;
   onDeleteFolder?: (path: string) => Promise<void>;
   onDeleteFile?: (item: DocTreeItem) => Promise<void>;
@@ -224,12 +225,15 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
   const [renameValue, setRenameValue] = useState(
     isFolder || !isExtensionlessDocument ? item.name : displayTitleFromFilename(item.name),
   );
+  const [renameSaving, setRenameSaving] = useState(false);
+  const [optimisticName, setOptimisticName] = useState<string | null>(null);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [confirmFileDelete, setConfirmFileDelete] = useState(false);
   const [deleting, setDeleting] = useState(false);
 
   const keepsVirtualRowAlive = contextMenuOpen
     || renaming
+    || renameSaving
     || confirmDelete
     || confirmFileDelete
     || deleting;
@@ -341,11 +345,26 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
     }
   }, [deleting, item, onDeleteFile, t]);
 
-  const submitRename = useCallback(() => {
-    if (!renaming) return;
+  const submitRename = useCallback(async () => {
+    if (!renaming || renameSaving) return;
+    const nextName = renameValue.trim();
+    if (!nextName) {
+      setRenaming(false);
+      setRenameValue(isFolder || !isExtensionlessDocument ? item.name : displayTitleFromFilename(item.name));
+      return;
+    }
     setRenaming(false);
-    void onRename(item, renameValue);
-  }, [item, onRename, renameValue, renaming]);
+    setRenameSaving(true);
+    setOptimisticName(nextName);
+    try {
+      const saved = await onRename(item, nextName);
+      if (saved === false) setOptimisticName(null);
+    } catch {
+      setOptimisticName(null);
+    } finally {
+      setRenameSaving(false);
+    }
+  }, [isExtensionlessDocument, isFolder, item, onRename, renameSaving, renameValue, renaming]);
 
   const cancelRename = useCallback(() => {
     setRenaming(false);
@@ -360,6 +379,7 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
       }}>
       <ContextMenuTrigger asChild>
         <div
+          data-folder-selection={isFolder ? '' : undefined}
           role="treeitem"
           aria-expanded={isFolder ? expanded : undefined}
           aria-selected={active || selected}
@@ -425,9 +445,9 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
                 {isDefaultFolder && <DefaultFolderCheck />}
               </>
             ) : isNote ? (
-              <NotebookTreeFileIcon className="notebook-file-tree__default-file-icon h-[18px] w-[18px]" />
+              <ContentIcon content={{ kind: 'note' }} className="notebook-file-tree__default-file-icon h-[18px] w-[18px]" />
             ) : (
-              <NotebookTreeResourceIcon path={item.name} collectionType={isMediaLibrary ? 'media_library' : isTableDocument ? 'table' : undefined} className="h-[18px] w-[18px]" />
+              <ContentIcon content={isMediaLibrary ? { kind: 'media-library' } : isTableDocument ? { kind: 'multidimensional-table' } : { kind: 'file', path: item.name }} className="h-[18px] w-[18px]" />
             )}
           </span>
           <input
@@ -482,9 +502,9 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
                   draggable={false}
                 />
               ) : isNote ? (
-                <NotebookTreeFileIcon className="notebook-file-tree__default-file-icon h-[18px] w-[18px]" />
+                <ContentIcon content={{ kind: 'note' }} className="notebook-file-tree__default-file-icon h-[18px] w-[18px]" />
               ) : (
-                <NotebookTreeResourceIcon path={item.name} collectionType={isMediaLibrary ? 'media_library' : isTableDocument ? 'table' : undefined} className="h-[18px] w-[18px]" />
+                <ContentIcon content={isMediaLibrary ? { kind: 'media-library' } : isTableDocument ? { kind: 'multidimensional-table' } : { kind: 'file', path: item.name }} className="h-[18px] w-[18px]" />
               )}
             </span>
           )}
@@ -508,9 +528,9 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
             'ml-1.5',
             active || selected ? 'opacity-100' : 'opacity-[0.82]',
           )}>
-            {isFolder || !isExtensionlessDocument
+            {optimisticName ?? (isFolder || !isExtensionlessDocument
               ? item.name
-              : displayTitleFromFilename(item.name)}
+              : displayTitleFromFilename(item.name))}
           </span>
           {isFolder && isDefaultFolder && !renaming && (
             <span className="ml-2 shrink-0 text-xs text-[var(--muted-foreground)] opacity-50 transition-opacity duration-150 group-hover:opacity-0">
@@ -518,12 +538,15 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
             </span>
           )}
           {isFolder && isLoadingChildren && (
-            <Loader2 className="ml-1 h-3.5 w-3.5 shrink-0 animate-spin text-[var(--muted-foreground)]" aria-label={t('memo.fileTree.loading')} />
+            <Loader2 className="ml-1 h-3.5 w-3.5 shrink-0 flowix-spin text-[var(--muted-foreground)]" aria-label={t('memo.fileTree.loading')} />
+          )}
+          {renameSaving && (
+            <Loader2 className="ml-1 h-3.5 w-3.5 shrink-0 flowix-spin text-[var(--muted-foreground)]" aria-label={t('memo.fileTree.loading')} />
           )}
           {isFolder && expanded && childrenError && (
             <button
               type="button"
-              className="ml-1 shrink-0 rounded px-1.5 py-0.5 text-[11px] text-[var(--foreground)] hover:bg-[var(--muted)]"
+              className="ml-1 shrink-0 rounded-lg px-1.5 py-0.5 text-[11px] text-[var(--foreground)] hover:bg-[var(--muted)]"
               aria-label={t('memo.fileTree.unreadableHint')}
               title={t('memo.fileTree.unreadableHint')}
               onPointerDown={(event) => event.stopPropagation()}
@@ -543,7 +566,7 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
           className="ml-1 flex h-6 w-6 shrink-0 items-center justify-center text-[var(--brand)]"
         >
           {moveStatus === 'moving' ? (
-            <span aria-hidden="true" className="notebook-file-tree__moving-indicator" />
+            <span aria-hidden="true" className="notebook-file-tree__moving-indicator flowix-spin" />
           ) : (
             <span aria-hidden="true" className="text-xs font-semibold">✓</span>
           )}
@@ -569,11 +592,13 @@ export const NotebookTreeRow = memo(function NotebookTreeRow({
           onCreateFolder={() => onCreateFolder(actionParentPath)}
           onCreateTable={(viewType) => onCreateView(actionParentPath, viewType)}
           onCreateMediaLibrary={() => onCreateMediaLibrary(actionParentPath)}
-          onImport={onImportFiles ? () => onImportFiles(actionParentPath) : undefined}
+          onImportFiles={onImportFiles ? () => onImportFiles(actionParentPath) : undefined}
+          onImportFolder={onImportFolder ? () => onImportFolder(actionParentPath) : undefined}
         />
         <ContextMenuItem
           onClick={() => {
             setRenameValue(isFolder || !isExtensionlessDocument ? item.name : displayTitleFromFilename(item.name));
+            setOptimisticName(null);
             setRenaming(true);
           }}
           className={TREE_MENU_ITEM_CLASS}
@@ -755,7 +780,7 @@ function NotebookTreeMoreButton({ label, active }: { label: string; active: bool
       onClick={(event) => {
         event.stopPropagation();
         const rect = event.currentTarget.getBoundingClientRect();
-        openAt(rect.left, rect.bottom);
+        openAt(rect.left, rect.bottom, event.currentTarget);
       }}
       onKeyDown={(event) => event.stopPropagation()}
       className={cn(
diff --git a/app/flowix-web/features/memo/components/notebook-tree-section-menu.tsx b/app/flowix-web/features/memo/components/notebook-tree-section-menu.tsx
new file mode 100644
index 000000000..b42836278
--- /dev/null
+++ b/app/flowix-web/features/memo/components/notebook-tree-section-menu.tsx
@@ -0,0 +1,297 @@
+'use client';
+
+import { useLayoutEffect, useRef, useState, type CSSProperties } from 'react';
+import {
+  ArrowDownUp,
+  Check,
+  ChevronRight,
+  GalleryHorizontalEnd,
+  MoreHorizontal,
+  Plus,
+  Table2,
+} from 'lucide-react';
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  EyeSlashIcon,
+  DownloadSimpleIcon,
+  FileIcon,
+  FolderSimplePlusIcon,
+  SquaresFourIcon,
+} from '@phosphor-icons/react';
+
+import { cn } from '@/lib/utils';
+import { useI18n } from '@/lib/i18n';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@shared/ui/dropdown-menu';
+import type { FolderTreeSort } from './use-folder-tree';
+import type { TableViewType } from '@features/multidimensional-table/public/create-api';
+import { MEMO_CREATE_VIEW_OPTIONS } from './memo-create-view-options';
+
+export function getPopupOriginRect(target: HTMLElement): DOMRect {
+  const rect = (target.closest('[role="menu"]') ?? target).getBoundingClientRect();
+  return new DOMRect(rect.left, rect.top, 0, 0);
+}
+
+function useViewportSubmenuPosition(open: boolean) {
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const [style, setStyle] = useState<CSSProperties>({ left: '100%', top: 0 });
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const updatePosition = () => {
+      const trigger = triggerRef.current;
+      const content = contentRef.current;
+      if (!trigger || !content) return;
+      const triggerRect = trigger.getBoundingClientRect();
+      const width = content.offsetWidth || 176;
+      const height = content.scrollHeight;
+      const opensLeft = window.innerWidth - triggerRect.right < width + 8;
+      const top = Math.max(4, Math.min(triggerRect.top, window.innerHeight - height - 4));
+      setStyle({
+        left: opensLeft ? undefined : '100%',
+        right: opensLeft ? '100%' : undefined,
+        top: top - triggerRect.top,
+      });
+    };
+    updatePosition();
+    const frame = window.requestAnimationFrame(updatePosition);
+    const observer = typeof ResizeObserver === 'undefined' || !contentRef.current
+      ? null
+      : new ResizeObserver(updatePosition);
+    if (observer && contentRef.current) observer.observe(contentRef.current);
+    window.addEventListener('resize', updatePosition);
+    window.addEventListener('scroll', updatePosition, true);
+    return () => {
+      window.cancelAnimationFrame(frame);
+      observer?.disconnect();
+      window.removeEventListener('resize', updatePosition);
+      window.removeEventListener('scroll', updatePosition, true);
+    };
+  }, [open]);
+
+  return { triggerRef, contentRef, style };
+}
+
+interface NotebookTreeSectionMenuProps {
+  onHideSection?: () => void;
+  canMoveUp: boolean;
+  canMoveDown: boolean;
+  onMoveUp: () => void;
+  onMoveDown: () => void;
+  onCreateFolder?: () => void;
+  onCreateNote?: () => void;
+  onCreateTable?: (viewType?: TableViewType) => void;
+  onCreateMediaLibrary?: () => void;
+  onImportFiles?: () => void;
+  onImportFolder?: () => void;
+  sort?: FolderTreeSort;
+  onSort?: (sort: FolderTreeSort) => void;
+  onCustomizeDisplay?: (anchorRect: DOMRect) => void;
+}
+
+export function NotebookTreeSectionMenu({
+  onHideSection,
+  canMoveUp,
+  canMoveDown,
+  onMoveUp,
+  onMoveDown,
+  onCreateFolder,
+  onCreateNote,
+  onCreateTable,
+  onCreateMediaLibrary,
+  onImportFiles,
+  onImportFolder,
+  sort,
+  onSort,
+  onCustomizeDisplay,
+}: NotebookTreeSectionMenuProps) {
+  const { t } = useI18n();
+  const [sortSubmenuOpen, setSortSubmenuOpen] = useState(false);
+  const [createSubmenuOpen, setCreateSubmenuOpen] = useState(false);
+  const [importSubmenuOpen, setImportSubmenuOpen] = useState(false);
+  const createSubmenuPosition = useViewportSubmenuPosition(createSubmenuOpen);
+  const importSubmenuPosition = useViewportSubmenuPosition(importSubmenuOpen);
+  const sortSubmenuPosition = useViewportSubmenuPosition(sortSubmenuOpen);
+  const itemClassName = 'group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)] disabled:cursor-not-allowed disabled:opacity-40';
+  const hasActionsAfterMovement = Boolean(
+    onCreateNote || onCreateFolder || onCreateTable || onCreateMediaLibrary || onImportFiles || onImportFolder || (sort && onSort),
+  );
+
+  return (
+    <DropdownMenu onOpenChange={(open) => {
+      if (!open) {
+        setCreateSubmenuOpen(false);
+        setImportSubmenuOpen(false);
+        setSortSubmenuOpen(false);
+      }
+    }}>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          className="notebook-file-tree__section-more-trigger flex h-6 w-6 items-center justify-center rounded-md text-[var(--muted-foreground)] opacity-0 transition-[color,opacity] hover:text-[var(--foreground)] focus-visible:opacity-100 focus-visible:outline-none group-hover:opacity-100"
+          aria-label={t('memo.fileTree.moreSectionActions')}
+          title={t('memo.fileTree.moreSectionActions')}
+        >
+          <MoreHorizontal className="h-3.5 w-3.5" aria-hidden="true" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-[176px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+        <DropdownMenuItem disabled={!canMoveUp} onClick={onMoveUp} className={itemClassName}>
+          <ArrowUpIcon className="h-3.5 w-3.5" aria-hidden="true" />
+          {t('memo.fileTree.moveSectionUp')}
+        </DropdownMenuItem>
+        <DropdownMenuItem disabled={!canMoveDown} onClick={onMoveDown} className={itemClassName}>
+          <ArrowDownIcon className="h-3.5 w-3.5" aria-hidden="true" />
+          {t('memo.fileTree.moveSectionDown')}
+        </DropdownMenuItem>
+        {hasActionsAfterMovement && <DropdownMenuSeparator />}
+        {onCreateNote && (
+          <DropdownMenuItem onClick={onCreateNote} className={itemClassName}>
+            <FileIcon className="h-3.5 w-3.5" aria-hidden="true" />
+            {t('memo.fileTree.newNote')}
+          </DropdownMenuItem>
+        )}
+        {onCreateFolder && (
+          <DropdownMenuItem onClick={onCreateFolder} className={itemClassName}>
+            <FolderSimplePlusIcon className="h-3.5 w-3.5" aria-hidden="true" />
+            {t('memo.fileTree.newFolder')}
+          </DropdownMenuItem>
+        )}
+        {(onCreateTable || onCreateMediaLibrary) && (
+          <div
+            className="relative"
+            onMouseEnter={() => setCreateSubmenuOpen(true)}
+            onMouseLeave={() => setCreateSubmenuOpen(false)}
+          >
+            <button
+              type="button"
+              ref={createSubmenuPosition.triggerRef}
+              className={cn(itemClassName, 'flex w-full items-center justify-between text-sm')}
+              onClick={() => setCreateSubmenuOpen((open) => !open)}
+              onMouseDown={(event) => event.preventDefault()}
+            >
+              <span className="flex items-center gap-2">
+                <Plus className="h-3.5 w-3.5" aria-hidden="true" />
+                {t('memo.create.more')}
+              </span>
+              <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
+            </button>
+            {createSubmenuOpen && (
+              <div ref={createSubmenuPosition.contentRef} style={{ ...createSubmenuPosition.style, maxWidth: 'calc(100vw - 8px)', maxHeight: 'calc(100vh - 8px)', overflowY: 'auto' }} className="absolute w-[176px] space-y-0.5 rounded-xl border border-[var(--border-popup)] bg-[var(--card)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+                {onCreateTable && MEMO_CREATE_VIEW_OPTIONS.map(({ type, labelKey }) => (
+                  <DropdownMenuItem key={type} onClick={() => onCreateTable(type)} className={itemClassName}>
+                    {type === 'table' ? <Table2 className="h-3.5 w-3.5" aria-hidden="true" /> : <span className="h-3.5 w-3.5 shrink-0" aria-hidden="true" />}
+                    {t(labelKey)}
+                    <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">{t('memo.create.note')}</span>
+                  </DropdownMenuItem>
+                ))}
+                {onCreateMediaLibrary && (
+                  <DropdownMenuItem onClick={onCreateMediaLibrary} className={itemClassName}>
+                    <GalleryHorizontalEnd className="h-3.5 w-3.5" aria-hidden="true" />
+                    <span>{t('memo.create.mediaLibrary')}</span>
+                    <span className="ml-auto text-xs text-[var(--muted-foreground)] opacity-50 group-hover:text-[var(--primary-foreground)] group-focus-visible:text-[var(--primary-foreground)]">
+                      {t('memo.create.mediaImageShort')}/{t('memo.create.mediaVideoShort')}
+                    </span>
+                  </DropdownMenuItem>
+                )}
+              </div>
+            )}
+          </div>
+        )}
+        {(onImportFiles || onImportFolder) && (
+          <div className="relative" onMouseEnter={() => setImportSubmenuOpen(true)} onMouseLeave={() => setImportSubmenuOpen(false)}>
+            <button
+              type="button"
+              ref={importSubmenuPosition.triggerRef}
+              onClick={() => setImportSubmenuOpen((open) => !open)}
+              onMouseDown={(event) => event.preventDefault()}
+              className={cn(itemClassName, 'flex w-full items-center text-sm')}
+            >
+              <DownloadSimpleIcon className="h-3.5 w-3.5" aria-hidden="true" />
+              {t('memo.fileTree.import')}
+              <ChevronRight className="ml-auto h-3.5 w-3.5" aria-hidden="true" />
+            </button>
+            {importSubmenuOpen && (
+              <div
+                ref={importSubmenuPosition.contentRef}
+                style={importSubmenuPosition.style}
+                className="absolute z-50 w-[156px] space-y-0.5 rounded-xl border border-[var(--border-popup)] bg-[var(--card)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]"
+              >
+                {onImportFiles && <DropdownMenuItem onClick={onImportFiles} className={itemClassName}>{t('memo.fileTree.importFiles')}</DropdownMenuItem>}
+                {onImportFolder && <DropdownMenuItem onClick={onImportFolder} className={itemClassName}>{t('memo.fileTree.importFolder')}</DropdownMenuItem>}
+              </div>
+            )}
+          </div>
+        )}
+        {sort && onSort && (
+          <div
+            className="relative"
+            onMouseEnter={() => setSortSubmenuOpen(true)}
+            onMouseLeave={() => setSortSubmenuOpen(false)}
+          >
+            <button
+              type="button"
+              ref={sortSubmenuPosition.triggerRef}
+              className={cn(itemClassName, 'memo-navigation-submenu-trigger flex w-full items-center justify-between text-sm')}
+              onClick={() => setSortSubmenuOpen(true)}
+              onMouseDown={(event) => event.preventDefault()}
+            >
+              <span className="flex items-center gap-2">
+                <ArrowDownUp className="h-3.5 w-3.5" aria-hidden="true" />
+                {t('memo.list.sortLabel')}
+              </span>
+              <span className="flex items-center gap-1 text-xs text-[var(--muted-foreground)]">
+                {t(sort === 'createdAt' ? 'memo.list.sortCreated' : sort === 'updatedAt' ? 'memo.list.sortUpdated' : sort === 'filenameAsc' ? 'memo.list.sortFilenameAsc' : 'memo.list.sortFilenameDesc')}
+                <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
+              </span>
+            </button>
+            {sortSubmenuOpen && (
+              <div ref={sortSubmenuPosition.contentRef} style={{ ...sortSubmenuPosition.style, maxWidth: 'calc(100vw - 8px)', maxHeight: 'calc(100vh - 8px)', overflowY: 'auto' }} className="absolute w-[176px] space-y-0.5 rounded-xl border border-[var(--border-popup)] bg-[var(--card)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+                {([
+                  ['createdAt', 'memo.list.sortCreated'],
+                  ['updatedAt', 'memo.list.sortUpdated'],
+                  ['filenameAsc', 'memo.list.sortFilenameAsc'],
+                  ['filenameDesc', 'memo.list.sortFilenameDesc'],
+                ] as const).map(([value, label]) => (
+                  <DropdownMenuItem
+                    key={value}
+                    onClick={() => onSort(value)}
+                    className={cn(
+                      'memo-navigation-submenu-item mention-note-item cursor-pointer hover:bg-[var(--brand)] focus-visible:bg-[var(--brand)] focus-visible:outline-none',
+                      sort === value && 'is-selected',
+                    )}
+                  >
+                    <span>{t(label)}</span>
+                    {sort === value && <Check className="h-4 w-4 text-[var(--brand)]" aria-hidden="true" />}
+                  </DropdownMenuItem>
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+        {(hasActionsAfterMovement || onCustomizeDisplay || onHideSection) && <DropdownMenuSeparator />}
+        {onHideSection && (
+          <DropdownMenuItem onClick={onHideSection} className={itemClassName}>
+            <EyeSlashIcon className="h-3.5 w-3.5" aria-hidden="true" />
+            {t('memo.fileTree.hideSection')}
+          </DropdownMenuItem>
+        )}
+        {onCustomizeDisplay && (
+          <DropdownMenuItem keepOpenOnClick onClick={(event) => {
+            onCustomizeDisplay(getPopupOriginRect(event.currentTarget));
+          }} className={itemClassName}>
+            <SquaresFourIcon className="h-3.5 w-3.5" aria-hidden="true" />
+            {t('memo.fileTree.customizeDisplay')}
+          </DropdownMenuItem>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
diff --git a/app/flowix-web/features/memo/components/tag-tree.tsx b/app/flowix-web/features/memo/components/tag-tree.tsx
index ebd167537..a8dbe618c 100644
--- a/app/flowix-web/features/memo/components/tag-tree.tsx
+++ b/app/flowix-web/features/memo/components/tag-tree.tsx
@@ -1,3 +1,4 @@
+import { useNotebookBackgroundStore } from '@features/memo/store/notebook-background-store';
 'use client';
 
 import {
@@ -7,7 +8,6 @@ import {
   useRef,
   useState,
 } from 'react';
-import { PlusIcon } from '@phosphor-icons/react';
 import { SquareMinus } from 'lucide-react';
 
 import { cn } from '@/lib/utils';
@@ -17,8 +17,6 @@ import { createLogger } from '@/lib/logger';
 import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@shared/ui/context-menu';
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@shared/ui/dialog';
 import { Button } from '@shared/ui/button';
-import { Input } from '@shared/ui/input';
-import { Select, SelectContent, SelectItem, SelectTrigger } from '@shared/ui/select';
 import {
   useNoteStore,
 } from '@features/memo/store/note-store';
@@ -115,6 +113,8 @@ export function TagTree({
   const loadLibraryMetadata = useMemoLibraryMetadataStore((s) => s.loadMetadata);
   const clearLibraryMetadata = useMemoLibraryMetadataStore((s) => s.clearMetadata);
 
+  const backgroundIndex = useNotebookBackgroundStore((state) => selectedNotebook ? state.statuses[selectedNotebook.id] : undefined);
+  const [loadedTagNotebookId, setLoadedTagNotebookId] = useState<string | null>(null);
   const [tagOptions, setTagOptions] = useState<MemoTagTreeItem[]>([]);
   const [tagLayout, setTagLayout] = useState<MemoTagLayoutItem[]>([]);
   const [hiddenTagIds, setHiddenTagIds] = useState<string[]>([]);
@@ -127,11 +127,6 @@ export function TagTree({
   // 行内重命名编辑态: editingTagId 命中时标签名 span 替换为 input。
   const [editingTagId, setEditingTagId] = useState<string | null>(null);
   const [editingTagName, setEditingTagName] = useState('');
-  const [createDialogOpen, setCreateDialogOpen] = useState(false);
-  const [newTagParentPath, setNewTagParentPath] = useState('');
-  const [newTagName, setNewTagName] = useState('');
-  const [createTagError, setCreateTagError] = useState<string | null>(null);
-  const [isCreatingTag, setIsCreatingTag] = useState(false);
   // 删除确认弹窗: `deletingTag` 命中时, 弹 Dialog 提示子树影响范围 + 确认。
   const [deletingTag, setDeletingTag] = useState<MemoTagTreeItem | null>(null);
   // 批量管理模式: true 时标签末尾的数字变成删除按钮 (SquareMinus),
@@ -167,6 +162,7 @@ export function TagTree({
         );
         if (!metadata || cancelled) return;
         setTagOptions(metadata.tagOptions);
+        setLoadedTagNotebookId(notebook.id);
         setTagLayout(metadata.tagLayout);
         setHiddenTagIds(metadata.hiddenTagIds);
         setPinnedByParent(metadata.pinnedByParent);
@@ -190,6 +186,10 @@ export function TagTree({
         }
       } catch (error) {
         if (!cancelled) {
+          if (String(error).includes('NOTE_INDEX_PENDING')) {
+            useNotebookBackgroundStore.getState().pending(notebook.id);
+            return;
+          }
           logger.warn('failed to load tags', { error });
           setTagOptions([]);
           setTagLayout([]);
@@ -233,63 +233,6 @@ export function TagTree({
     ],
   );
 
-  const openCreateTagDialog = useCallback(() => {
-    setNewTagParentPath('');
-    setNewTagName('');
-    setCreateTagError(null);
-    setCreateDialogOpen(true);
-  }, []);
-
-  const submitCreateTag = useCallback(async () => {
-    if (!selectedNotebook || isCreatingTag) return;
-    const name = newTagName.trim();
-    if (!name) {
-      setCreateTagError(t('memo.tag.createEmpty'));
-      return;
-    }
-    if (name.startsWith('#')) {
-      setCreateTagError(t('memo.tag.createWithoutHash'));
-      return;
-    }
-    if (!isValidTagPath(name)) {
-      setCreateTagError(t('memo.tag.createInvalid'));
-      return;
-    }
-    const path = newTagParentPath ? `${newTagParentPath}/${name}` : name;
-
-    setIsCreatingTag(true);
-    setCreateTagError(null);
-    try {
-      const report = await useTagStore
-        .getState()
-        .createTag(selectedNotebook.id, path);
-      clearLibraryMetadata();
-      invalidateMentionTags();
-      setCreateDialogOpen(false);
-      setNewTagParentPath('');
-      setNewTagName('');
-      toast.success(
-        t('memo.tag.createdToast', { path: report.path } satisfies I18nParams),
-      );
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      toast.error(
-        message.includes('already exists')
-          ? t('memo.tag.createDuplicate')
-          : `${t('memo.tag.createFailed')}: ${message}`,
-      );
-    } finally {
-      setIsCreatingTag(false);
-    }
-  }, [
-    clearLibraryMetadata,
-    isCreatingTag,
-    newTagName,
-    newTagParentPath,
-    selectedNotebook,
-    t,
-  ]);
-
   const startRename = useCallback((tag: MemoTagTreeItem) => {
     setEditingTagId(tag.id);
     setEditingTagName(tag.name);
@@ -324,40 +267,35 @@ export function TagTree({
     [],
   );
 
-  /**
-   * 「置顶」菜单项: 把 tag 推到 parent 下兄弟组最前 (MRU 语义)。无提供取消
-   * 路径 ── pinned 只能通过 delete / rename / reparent 间接迁移或清空。
-   * 既有 pinned 重新置顶 = 把它从当前位置抽离并插到 head (让其他 pinned 后
-   * 退一格), 符合 "最近置顶排第一"。
-   */
-  const pinTag = useCallback(
+  /** 置顶或取消置顶标签；新置顶项放在同级置顶项的最前面。 */
+  const toggleTagPin = useCallback(
     async (tag: MemoTagTreeItem) => {
       const notebookId = useNoteStore.getState().selectedNotebook?.id;
       if (!notebookId) return;
       const parentKey = tag.parentId ?? '';
       const current = pinnedByParent[parentKey] ?? [];
-      const next: string[] = [
-        tag.fullPath,
-        ...current.filter((p) => p !== tag.fullPath),
-      ];
+      const isPinned = current.includes(tag.fullPath);
+      const next = isPinned
+        ? current.filter((path) => path !== tag.fullPath)
+        : [tag.fullPath, ...current];
       const prev = pinnedByParent;
-      const nextMap: Record<string, string[]> = {
-        ...pinnedByParent,
-        [parentKey]: next,
-      };
+      const nextMap = { ...pinnedByParent };
+      if (next.length > 0) nextMap[parentKey] = next;
+      else delete nextMap[parentKey];
+      const baseOptions = rebuildTagOptionsFromLayout(tagLayout, tagOptions);
       // 乐观更新
       setPinnedByParent(nextMap);
-      setTagOptions(applyPinOrdering(tagOptions, nextMap));
+      setTagOptions(applyPinOrdering(baseOptions, nextMap));
       try {
         await system.setTagPinned(notebookId, parentKey, next);
       } catch (err) {
         // 回滚
         setPinnedByParent(prev);
-        setTagOptions(applyPinOrdering(tagOptions, prev));
+        setTagOptions(applyPinOrdering(baseOptions, prev));
         toast.error(err instanceof Error ? err.message : String(err));
       }
     },
-    [pinnedByParent, tagOptions],
+    [pinnedByParent, tagLayout, tagOptions],
   );
 
   // 行内重命名提交: 复用 moveTag (重命名 = 同父级 move 末段)。segment 字符
@@ -648,6 +586,11 @@ export function TagTree({
 
   const draggingTagId = draggingId;
 
+  if (selectedNotebook && loadedTagNotebookId !== selectedNotebook.id
+    && (backgroundIndex?.state === 'queued' || backgroundIndex?.state === 'running')) {
+    return <div className="px-3 py-2 text-xs text-[var(--muted-foreground)]" role="status">{t('memo.navigation.loading')}</div>;
+  }
+
   return (
     <>
       {/* 标签组 ── 外侧容器, pt-1 提供组上方留白 (与资料组对称, 两侧均用 padding 而非 margin);
@@ -655,7 +598,7 @@ export function TagTree({
       <div className={cn('tag-tree-list', !hideSectionHeader && 'pt-1')}>
         {/* 标签分类标题 ── 过滤器 (全部/对话/待办) 在上, 真正的标签树在此标题之下。 */}
         {!hideSectionHeader && (
-          <div className="agent-thread-card__access-section-label flex items-center justify-between">
+          <div className="agent-composer__access-section-label flex items-center justify-between">
             <span>{t('memo.navigation.tags')}</span>
             {batchMode ? (
               <button
@@ -667,18 +610,7 @@ export function TagTree({
               >
                 <span>{t('memo.tag.batchDone')}</span>
               </button>
-            ) : (
-              <button
-                type="button"
-                onClick={openCreateTagDialog}
-                disabled={!selectedNotebook}
-                className="-my-1 flex h-5 w-5 translate-x-1 items-center justify-center rounded-md text-[var(--muted-foreground)] transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:pointer-events-none disabled:opacity-40"
-                aria-label={t('memo.tag.create')}
-                title={t('memo.tag.create')}
-              >
-                <PlusIcon className="h-3.5 w-3.5" weight="light" />
-              </button>
-            )}
+            ) : null}
           </div>
         )}
         {tagOptions.length > 0 && (
@@ -686,6 +618,7 @@ export function TagTree({
           {visibleTagOptions.map((tag) => {
             const isSelected = activeFilter === 'tagged' && selectedTagId === tag.id;
             const isHidden = hiddenTagIdSet.has(tag.id);
+            const isPinned = (pinnedByParent[tag.parentId ?? ''] ?? []).includes(tag.fullPath);
             const isDragging = draggingTagId === tag.id;
             const hasChildren = childTagIdSet.has(tag.id);
             const isDropBefore =
@@ -720,7 +653,11 @@ export function TagTree({
                   void loadNativeMenuIcons(TAG_NATIVE_ICON_NAMES)
                     .then((icons) => popupNativeContextMenu(event, [
                       { text: t('memo.tag.rename'), icon: icons.pencil!, action: () => startRename(tag) },
-                      { text: t('memo.tag.pin'), icon: icons.pin!, action: () => void pinTag(tag) },
+                      {
+                        text: t(isPinned ? 'memo.tag.unpin' : 'memo.tag.pin'),
+                        icon: icons.pin!,
+                        action: () => void toggleTagPin(tag),
+                      },
                       { text: t('memo.tag.batchManage'), icon: icons['list-checks']!, action: () => setBatchMode(true) },
                       { text: t('memo.tag.delete'), icon: icons.delete!, action: () => setDeletingTag(tag) },
                     ]))
@@ -876,10 +813,10 @@ export function TagTree({
                   {t('memo.tag.rename')}
                 </ContextMenuItem>
                 <ContextMenuItem
-                  onClick={() => void pinTag(tag)}
+                  onClick={() => void toggleTagPin(tag)}
                   className="h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
                 >
-                  {t('memo.tag.pin')}
+                  {t(isPinned ? 'memo.tag.unpin' : 'memo.tag.pin')}
                 </ContextMenuItem>
                 <ContextMenuItem
                   onClick={() => setBatchMode(true)}
@@ -905,107 +842,6 @@ export function TagTree({
       {/* Tag 删除确认弹窗 ── 右键菜单"删除" 触发。 子树命中时给出更
           严肃的提示文案, 明确告诉用户删除是整棵子树 + body 里所有
           #tag 都会被移除, 无法撤销。 */}
-      <Dialog
-        open={createDialogOpen}
-        onOpenChange={(open) => {
-          if (isCreatingTag) return;
-          setCreateDialogOpen(open);
-          if (!open) {
-            setNewTagParentPath('');
-            setNewTagName('');
-            setCreateTagError(null);
-          }
-        }}
-      >
-        <DialogContent className="w-[460px]">
-          <DialogHeader className="pr-7">
-            <DialogTitle>{t('memo.tag.createTitle')}</DialogTitle>
-          </DialogHeader>
-          <form
-            onSubmit={(event) => {
-              event.preventDefault();
-              void submitCreateTag();
-            }}
-          >
-            <div className="flex items-center gap-2">
-              <div className="w-1/3 shrink-0">
-                <Select
-                  value={newTagParentPath || '__root__'}
-                  disabled={isCreatingTag}
-                  onValueChange={(value) => {
-                    setNewTagParentPath(value === '__root__' ? '' : value);
-                    if (createTagError) setCreateTagError(null);
-                  }}
-                >
-                  <SelectTrigger className="bg-[var(--background)]">
-                    <span className="min-w-0 truncate text-left">
-                      {newTagParentPath
-                        ? `#${newTagParentPath}`
-                        : t('memo.tag.createParent')}
-                    </span>
-                  </SelectTrigger>
-                  <SelectContent align="start" className="max-h-64 w-[240px] overflow-y-auto">
-                    <SelectItem value="__root__">
-                      {t('memo.tag.createNoParent')}
-                    </SelectItem>
-                    {tagOptions.map((tag) => (
-                      <SelectItem key={tag.id} value={tag.fullPath}>
-                        <span
-                          className="block truncate"
-                          style={{ paddingLeft: `${tag.depth * 12}px` }}
-                        >
-                          #{tag.fullPath}
-                        </span>
-                      </SelectItem>
-                    ))}
-                  </SelectContent>
-                </Select>
-              </div>
-              <div className="flex min-w-0 flex-1 items-center rounded-lg border border-input bg-background focus-within:border-[var(--primary)]">
-                <span className="pl-3 text-sm text-[var(--muted-foreground)]">#</span>
-                <Input
-                  id="new-tag-name"
-                  autoFocus
-                  value={newTagName}
-                  disabled={isCreatingTag}
-                  placeholder={t('memo.tag.createPlaceholder')}
-                  aria-label={t('memo.tag.createName')}
-                  onChange={(event) => {
-                    setNewTagName(event.target.value);
-                    if (createTagError) setCreateTagError(null);
-                  }}
-                  className="border-0 pl-1 focus-visible:border-0"
-                  aria-invalid={Boolean(createTagError)}
-                />
-              </div>
-            </div>
-            {createTagError && (
-              <p className="mt-1.5 text-xs text-[var(--destructive)]">
-                {createTagError}
-              </p>
-            )}
-            <div className="mt-4 flex justify-end gap-2">
-              <Button
-                type="button"
-                variant="ghost"
-                disabled={isCreatingTag}
-                onClick={() => setCreateDialogOpen(false)}
-              >
-                {t('memo.tag.createCancel')}
-              </Button>
-              <Button
-                type="submit"
-                disabled={isCreatingTag || !newTagName.trim()}
-              >
-                {isCreatingTag
-                  ? t('memo.tag.creating')
-                  : t('memo.tag.createConfirm')}
-              </Button>
-            </div>
-          </form>
-        </DialogContent>
-      </Dialog>
-
       <Dialog
         open={deletingTag !== null}
         onOpenChange={(open) => {
diff --git a/app/flowix-web/features/memo/components/use-folder-tree.test.tsx b/app/flowix-web/features/memo/components/use-folder-tree.test.tsx
index 3cf5a0196..70b09b9aa 100644
--- a/app/flowix-web/features/memo/components/use-folder-tree.test.tsx
+++ b/app/flowix-web/features/memo/components/use-folder-tree.test.tsx
@@ -2,7 +2,7 @@ import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import type { DocTreeItem } from '@platform/tauri/client';
+import { files, type DocTreeItem } from '@platform/tauri/client';
 import {
   flattenLoadedTree,
   flattenVisibleTree,
@@ -94,6 +94,140 @@ describe('useFolderTree', () => {
     expect(getDirChildrenMock).toHaveBeenCalledTimes(1);
   });
 
+  it('重命名后丢弃旧父目录的迟到刷新结果', async () => {
+    const oldPath = '/root/old';
+    const newPath = '/root/new';
+    getTreeMock.mockResolvedValue([dir(oldPath, 'old')]);
+    getDirChildrenMock.mockResolvedValue([file(`${oldPath}/note.md`, 'note.md')]);
+    mount('/root');
+    await vi.waitFor(() => expect(lastState?.loading).toBe(false));
+    await act(async () => lastState?.toggle(oldPath));
+    let finishRefresh!: (items: DocTreeItem[]) => void;
+    getTreeMock.mockImplementationOnce(() => new Promise((resolve) => { finishRefresh = resolve; }));
+    let pending!: Promise<void>;
+    act(() => { pending = lastState!.refresh('/root'); });
+    act(() => lastState?.rebasePath(oldPath, newPath));
+    await act(async () => {
+      finishRefresh([dir(oldPath, 'old')]);
+      await pending;
+    });
+    expect(lastState?.expanded.has(newPath)).toBe(true);
+    expect(lastState?.rootChildren.map((item) => item.fullPath)).toEqual([newPath]);
+    expect(flattenVisibleTree(lastState!).map(({ item }) => item.fullPath)).toContain(`${newPath}/note.md`);
+  });
+
+  it.each(['/root', '/root/parent'])('保存期间监听刷新 %s 不展示折叠中间态', async (parent) => {
+    const oldPath = `${parent}/old`;
+    const nextPath = `${parent}/new`;
+    let renamed = false;
+    getTreeMock.mockImplementation(async () => parent === '/root'
+      ? [dir(renamed ? nextPath : oldPath, renamed ? 'new' : 'old')]
+      : [dir(parent, 'parent')]);
+    getDirChildrenMock.mockImplementation(async (path) => path === parent
+      ? [dir(renamed ? nextPath : oldPath, renamed ? 'new' : 'old')]
+      : [file(`${path}/note.md`, 'note.md')]);
+    mount('/root');
+    await vi.waitFor(() => expect(lastState?.loading).toBe(false));
+    if (parent !== '/root') await act(async () => lastState?.toggle(parent));
+    await act(async () => lastState?.toggle(oldPath));
+    let complete!: (path: string) => void;
+    let completeRead!: (items: DocTreeItem[]) => void;
+    const delayedRead = () => new Promise<DocTreeItem[]>((resolve) => { completeRead = resolve; });
+    if (parent === '/root') getTreeMock.mockImplementationOnce(delayedRead);
+    else getDirChildrenMock.mockImplementationOnce(delayedRead);
+    let pendingRead!: Promise<void>;
+    act(() => { pendingRead = lastState!.refresh(parent); });
+    const rename = vi.spyOn(files, 'renameFolder').mockImplementationOnce(() => new Promise((resolve) => { complete = resolve; }));
+    try {
+      let saving!: Promise<string>;
+      act(() => { saving = lastState!.renameFolder(oldPath, 'new', '/root'); });
+      renamed = true;
+      await act(async () => { completeRead([dir(nextPath, 'new')]); await pendingRead; });
+      await act(async () => { await lastState?.refresh(parent); });
+      expect(lastState?.expanded.has(oldPath)).toBe(true);
+      expect(flattenVisibleTree(lastState!).map(({ item }) => item.fullPath)).toContain(`${oldPath}/note.md`);
+      await act(async () => { complete(nextPath); await saving; });
+      expect(lastState?.expanded.has(nextPath)).toBe(true);
+      expect(flattenVisibleTree(lastState!).map(({ item }) => item.fullPath)).toContain(`${nextPath}/note.md`);
+    } finally {
+      rename.mockRestore();
+    }
+  });
+
+  it('文件夹重命名成功后不等待父目录刷新再结束保存态', async () => {
+    const oldPath = '/root/old';
+    const newPath = '/root/new';
+    getTreeMock.mockResolvedValue([dir(oldPath, 'old')]);
+    mount('/root');
+    await vi.waitFor(() => expect(lastState?.loading).toBe(false));
+
+    let finishRefresh!: (items: DocTreeItem[]) => void;
+    getTreeMock.mockImplementationOnce(() => new Promise((resolve) => { finishRefresh = resolve; }));
+    const rename = vi.spyOn(files, 'renameFolder').mockResolvedValueOnce(newPath);
+    try {
+      let saving!: Promise<string>;
+      act(() => { saving = lastState!.renameFolder(oldPath, 'new', '/root'); });
+      let timeout!: ReturnType<typeof setTimeout>;
+      let settled = false;
+      await act(async () => {
+        settled = await Promise.race([
+          saving.then(() => true),
+          new Promise<boolean>((resolve) => { timeout = setTimeout(() => resolve(false), 100); }),
+        ]);
+      });
+      clearTimeout(timeout);
+      expect(settled).toBe(true);
+      expect(lastState?.rootChildren.map((item) => item.fullPath)).toEqual([newPath]);
+      expect(getTreeMock).toHaveBeenCalledTimes(2);
+
+      await act(async () => { finishRefresh([dir(newPath, 'new')]); });
+    } finally {
+      rename.mockRestore();
+    }
+  });
+
+  it('重命名锁定期间到达的 watcher 刷新会在新路径补执行', async () => {
+    const oldPath = '/root/old';
+    const newPath = '/root/new';
+    let renamed = false;
+    getTreeMock.mockImplementation(async () => [dir(renamed ? newPath : oldPath, renamed ? 'new' : 'old')]);
+    getDirChildrenMock.mockImplementation(async (path) => [
+      file(`${path}/${path === newPath ? 'updated' : 'initial'}.md`, `${path === newPath ? 'updated' : 'initial'}.md`),
+    ]);
+    mount('/root');
+    await vi.waitFor(() => expect(lastState?.loading).toBe(false));
+    await act(async () => lastState?.toggle(oldPath));
+    // Let the tree's refresh deduplication window expire before delivering the watcher event.
+    await new Promise((resolve) => setTimeout(resolve, 400));
+
+    let completeRename!: (path: string) => void;
+    const rename = vi.spyOn(files, 'renameFolder').mockImplementationOnce(() => new Promise((resolve) => {
+      completeRename = resolve;
+    }));
+    try {
+      let saving!: Promise<string>;
+      act(() => {
+        saving = lastState!.renameFolder(oldPath, 'new', '/root');
+        lastState!.refreshDirectories([oldPath]);
+      });
+      renamed = true;
+      await act(async () => { await new Promise((resolve) => setTimeout(resolve, 300)); });
+      expect(getDirChildrenMock).toHaveBeenCalledTimes(1);
+
+      await act(async () => {
+        completeRename(newPath);
+        await saving;
+      });
+
+      await vi.waitFor(() => expect(getDirChildrenMock).toHaveBeenCalledWith(newPath));
+      await vi.waitFor(() => expect(lastState?.nodes.get(newPath)?.children?.map((item) => item.name)).toEqual(['updated.md']));
+      expect(lastState?.expanded.has(newPath)).toBe(true);
+      expect(lastState?.nodes.get(newPath)?.children?.map((item) => item.name)).toEqual(['updated.md']);
+    } finally {
+      rename.mockRestore();
+    }
+  });
+
   it('根目录不可读时置 error 且列表为空', async () => {
     getTreeMock.mockResolvedValue(null);
     mount('/root');
@@ -224,6 +358,40 @@ describe('flattenVisibleTree', () => {
     ]);
     expect(flattened[1].depth).toBe(1);
   });
+
+  it('按笔记索引时间与文件创建时间混排同级文档', () => {
+    const folder = { ...dir('/root/folder', 'folder'), createdMs: 999 };
+    const replacedOlderNote = {
+      ...file('/root/older-note.md', 'older-note.md'),
+      createdMs: 100,
+      memoCreatedMs: 10,
+    };
+    const newerFile = {
+      ...file('/root/image.png', 'image.png'),
+      createdMs: 20,
+    };
+    const newerNote = {
+      ...file('/root/newer-note.md', 'newer-note.md'),
+      createdMs: 30,
+      memoCreatedMs: 30,
+    };
+    const state: FolderTreeState = {
+      rootChildren: [replacedOlderNote, folder, newerFile, newerNote],
+      nodes: new Map(),
+      expanded: new Set(),
+      loading: false,
+      loadingDirectories: new Set(),
+      directoryErrors: new Set(),
+      error: null,
+    };
+
+    expect(flattenVisibleTree(state).map(({ item }) => item.name)).toEqual([
+      'folder',
+      'newer-note.md',
+      'image.png',
+      'older-note.md',
+    ]);
+  });
 });
 
 describe('flattenLoadedTree', () => {
diff --git a/app/flowix-web/features/memo/components/use-folder-tree.ts b/app/flowix-web/features/memo/components/use-folder-tree.ts
index 996288d72..aa79846d2 100644
--- a/app/flowix-web/features/memo/components/use-folder-tree.ts
+++ b/app/flowix-web/features/memo/components/use-folder-tree.ts
@@ -3,12 +3,13 @@
 import { subscribe } from '@platform/tauri/event-bus';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { files, type DocTreeItem } from '@platform/tauri/client';
+import { files, type CollectionChangedEvent, type DocTreeItem } from '@platform/tauri/client';
 import { canonicalDirectoryPath, canonicalPath } from '@/lib/path';
 import { createLogger } from '@/lib/logger';
 
 const logger = createLogger('folder-tree');
 const REFRESH_DEDUP_WINDOW_MS = 350;
+const WATCHER_REFRESH_DEBOUNCE_MS = 250;
 
 function deleteCachedSubtree(nodes: Map<string, DocTreeItem>, path: string): void {
   const key = canonicalPath(path);
@@ -21,6 +22,37 @@ function deleteCachedSubtree(nodes: Map<string, DocTreeItem>, path: string): voi
   nodes.delete(key);
 }
 
+function pruneExpandedSubtrees(expanded: Set<string>, removedFolderPaths: string[]): Set<string> {
+  if (removedFolderPaths.length === 0) return expanded;
+  const removedKeys = removedFolderPaths.map(canonicalDirectoryPath);
+  let changed = false;
+  const next = new Set<string>();
+  for (const path of expanded) {
+    const isRemoved = removedKeys.some((root) => path === root || path.startsWith(`${root}/`));
+    if (isRemoved) changed = true;
+    else next.add(path);
+  }
+  return changed ? next : expanded;
+}
+
+function isPathAtOrBelow(path: string, directoryPath: string): boolean {
+  return path === directoryPath || path.startsWith(`${directoryPath}/`);
+}
+
+function rebasePathSet(paths: Set<string>, previousPath: string, nextPath: string): Set<string> {
+  let changed = false;
+  const next = new Set<string>();
+  for (const path of paths) {
+    if (isPathAtOrBelow(path, previousPath)) {
+      next.add(`${nextPath}${path.slice(previousPath.length)}`);
+      changed = true;
+    } else {
+      next.add(path);
+    }
+  }
+  return changed ? next : paths;
+}
+
 function reconcileDirectoryChildren(
   previous: Map<string, DocTreeItem>,
   parentKey: string,
@@ -111,11 +143,13 @@ export interface FolderTreeOptions {
 
 export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
   const enabled = options?.enabled !== false;
+  const rootKey = canonicalDirectoryPath(folderPath);
   const [rootChildren, setRootChildren] = useState<DocTreeItem[]>([]);
   const [nodes, setNodes] = useState<Map<string, DocTreeItem>>(() => new Map());
   const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
   const [dirtyDirectories, setDirtyDirectories] = useState<Set<string>>(() => new Set());
   const [loading, setLoading] = useState(true);
+  const [loadedRootPath, setLoadedRootPath] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loadingDirectories, setLoadingDirectories] = useState<Set<string>>(() => new Set());
   const [directoryErrors, setDirectoryErrors] = useState<Set<string>>(() => new Set());
@@ -125,66 +159,195 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
   const directoryRefreshesRef = useRef(new Map<string, Promise<void>>());
   const directoryRefreshSequenceRef = useRef(new Map<string, number>());
   const lastRefreshAtRef = useRef(new Map<string, number>());
+  const pendingWatcherDirectoriesRef = useRef(new Set<string>());
+  const watcherRefreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const rootRefreshRef = useRef<Promise<void> | null>(null);
   const rootRefreshSequenceRef = useRef(0);
   const rootChildrenRef = useRef(rootChildren);
   rootChildrenRef.current = rootChildren;
   const nodesRef = useRef(nodes);
   nodesRef.current = nodes;
+  const expandedRef = useRef(expanded);
+  expandedRef.current = expanded;
+  const pendingRenamesRef = useRef(0);
+  const pendingRenameRefreshDirectoriesRef = useRef(new Set<string>());
+
+  /** Keep path-keyed tree data and UI state attached to a renamed/moved path. */
+  const rebasePath = useCallback((
+    previousPath: string,
+    nextPath: string,
+  ) => {
+    const previous = canonicalDirectoryPath(previousPath);
+    const nextPathKey = canonicalDirectoryPath(nextPath);
+    if (previous === nextPathKey || isPathAtOrBelow(nextPathKey, previous)) return;
+
+    const oldParent = canonicalDirectoryPath(previous.slice(0, previous.lastIndexOf('/')) || '/');
+    const newParent = canonicalDirectoryPath(nextPathKey.slice(0, nextPathKey.lastIndexOf('/')) || '/');
+    const nextName = nextPathKey.slice(nextPathKey.lastIndexOf('/') + 1);
+    const currentNodes = nodesRef.current;
+    // Discard reads started before the path changed, including parent reads.
+    rootRefreshSequenceRef.current += 1;
+    for (const parent of new Set([oldParent, newParent])) {
+      directoryRefreshSequenceRef.current.set(parent, (directoryRefreshSequenceRef.current.get(parent) ?? 0) + 1);
+    }
+    const source = currentNodes.get(previous)
+      ?? rootChildrenRef.current.find((item) => canonicalPath(item.fullPath) === previous);
+    const nextParentId = currentNodes.get(newParent)?.id ?? null;
+
+    const mapPath = (path: string) => {
+      const canonical = canonicalPath(path);
+      return isPathAtOrBelow(canonical, previous)
+        ? `${nextPathKey}${canonical.slice(previous.length)}`
+        : canonical;
+    };
+    const mapItem = (item: DocTreeItem): DocTreeItem => {
+      const canonical = canonicalPath(item.fullPath);
+      const isRoot = canonical === previous;
+      return {
+        ...item,
+        fullPath: mapPath(item.fullPath),
+        ...(isRoot ? { name: nextName, ...(oldParent !== newParent ? { parentId: nextParentId } : {}) } : {}),
+        ...(item.children ? { children: item.children.map(mapItem) } : {}),
+      };
+    };
+
+    const rebasedNodes = new Map<string, DocTreeItem>();
+    for (const [key, item] of currentNodes) {
+      const rebasedItem = mapItem(item);
+      rebasedNodes.set(mapPath(key), rebasedItem);
+    }
+
+    const rebasedSource = source ? mapItem(source) : undefined;
+    if (oldParent === newParent && rebasedSource) {
+      const parent = rebasedNodes.get(newParent);
+      if (parent?.children) {
+        rebasedNodes.set(newParent, {
+          ...parent,
+          children: [...parent.children.filter((child) => canonicalPath(child.fullPath) !== nextPathKey), rebasedSource],
+        });
+      }
+    }
+    if (oldParent !== newParent) {
+      const oldParentNode = rebasedNodes.get(oldParent);
+      if (oldParentNode?.children) {
+        rebasedNodes.set(oldParent, {
+          ...oldParentNode,
+          children: oldParentNode.children.filter((child) => canonicalPath(child.fullPath) !== nextPathKey),
+        });
+      }
+      const newParentNode = rebasedNodes.get(newParent);
+      if (newParentNode?.children && rebasedSource) {
+        rebasedNodes.set(newParent, {
+          ...newParentNode,
+          children: [
+            ...newParentNode.children.filter((child) => canonicalPath(child.fullPath) !== nextPathKey),
+            rebasedSource,
+          ],
+        });
+      }
+    }
+
+    nodesRef.current = rebasedNodes;
+    setNodes(rebasedNodes);
+    const rebasedRootChildren = rootChildrenRef.current.map(mapItem);
+    let nextRootChildren = rebasedRootChildren;
+    if (oldParent === newParent && newParent === rootKey && rebasedSource) {
+      nextRootChildren = [...nextRootChildren.filter((child) => canonicalPath(child.fullPath) !== nextPathKey), rebasedSource];
+    }
+    if (oldParent !== newParent) {
+      if (oldParent === rootKey) {
+        nextRootChildren = nextRootChildren.filter((child) => canonicalPath(child.fullPath) !== nextPathKey);
+      }
+      if (newParent === rootKey && rebasedSource) {
+        nextRootChildren = [
+          ...nextRootChildren.filter((child) => canonicalPath(child.fullPath) !== nextPathKey),
+          rebasedSource,
+        ];
+      }
+    }
+    rootChildrenRef.current = nextRootChildren;
+    setRootChildren(nextRootChildren);
+    const rebasedExpanded = rebasePathSet(expandedRef.current, previous, nextPathKey);
+    expandedRef.current = rebasedExpanded;
+    setExpanded(rebasedExpanded);
+    setDirtyDirectories((current) => rebasePathSet(current, previous, nextPathKey));
+    setDirectoryErrors((current) => rebasePathSet(current, previous, nextPathKey));
+    // Requests started under the old path must not repopulate stale cache entries.
+    for (const key of directoryRefreshSequenceRef.current.keys()) {
+      if (isPathAtOrBelow(key, previous)) {
+        directoryRefreshSequenceRef.current.set(key, (directoryRefreshSequenceRef.current.get(key) ?? 0) + 1);
+      }
+    }
+    setLoadingDirectories((current) => {
+      const next = new Set(current);
+      for (const key of current) {
+        if (isPathAtOrBelow(key, previous)) next.delete(key);
+      }
+      return next.size === current.size ? current : next;
+    });
+    for (const [key, value] of lastRefreshAtRef.current) {
+      if (!isPathAtOrBelow(key, previous)) continue;
+      lastRefreshAtRef.current.delete(key);
+      lastRefreshAtRef.current.set(`${nextPathKey}${key.slice(previous.length)}`, value);
+    }
+    pendingWatcherDirectoriesRef.current = rebasePathSet(
+      pendingWatcherDirectoriesRef.current,
+      previous,
+      nextPathKey,
+    );
+    pendingRenameRefreshDirectoriesRef.current = rebasePathSet(
+      pendingRenameRefreshDirectoriesRef.current,
+      previous,
+      nextPathKey,
+    );
+  }, [rootKey]);
 
   const mutationPathsRef = useRef(new Set<string>());
+  const mutationDirectoriesRef = useRef(new Set<string>());
   const ignoreCollectionPathEvents = useCallback((paths: readonly string[] | undefined) => {
     if (!paths?.length) return false;
     const known = mutationPathsRef.current;
-    if (!paths.every((path) => known.has(canonicalPath(path)) || /__collection_rename_/.test(path))) return false;
+    const knownDirectories = mutationDirectoriesRef.current;
+    if (!paths.every((path) => {
+      const canonical = canonicalPath(path);
+      return known.has(canonical)
+        || [...knownDirectories].some((directory) => isPathAtOrBelow(canonical, directory))
+        || /__collection_rename_/.test(path);
+    })) return false;
     return true;
   }, []);
   useEffect(() => {
     const root = canonicalPath(folderPath).replace(/\/$/, '');
     const applied = new Map<string, number>();
     mutationPathsRef.current.clear();
+    mutationDirectoriesRef.current.clear();
     const timers = new Set<ReturnType<typeof setTimeout>>();
-    const stop = subscribe<{ notebookPath: string; collectionId: string; previousRelativePath: string; relativePath: string; indexSequence: number }>('collection-changed', (event) => {
+    const stop = subscribe<CollectionChangedEvent>('collection-changed', (event) => {
       if (!event.notebookPath || !event.previousRelativePath || !event.relativePath) return;
       if (event.indexSequence < (applied.get(event.collectionId) ?? -1)) return;
       applied.set(event.collectionId, event.indexSequence);
-      const previous = canonicalPath(`${event.notebookPath}/${event.previousRelativePath}`);
-      const nextPath = canonicalPath(`${event.notebookPath}/${event.relativePath}`);
+      const previous = canonicalPath(`${event.notebookPath}/${event.directoryMove?.previousRelativePath ?? event.previousRelativePath}`);
+      const nextPath = canonicalPath(`${event.notebookPath}/${event.directoryMove?.relativePath ?? event.relativePath}`);
       if (!previous.startsWith(`${root}/`) || !nextPath.startsWith(`${root}/`)) return;
       const known = mutationPathsRef.current;
       known.add(previous); known.add(nextPath);
+      const previousDirectory = event.directoryMove ? previous : null;
+      const nextDirectory = event.directoryMove ? nextPath : null;
+      if (previousDirectory) mutationDirectoriesRef.current.add(previousDirectory);
+      if (nextDirectory) mutationDirectoriesRef.current.add(nextDirectory);
       // Bound suppression to the immediately following filesystem notifications.
-      const timer = setTimeout(() => { known.delete(previous); known.delete(nextPath); timers.delete(timer); }, 2000);
+      const timer = setTimeout(() => {
+        known.delete(previous); known.delete(nextPath);
+        if (previousDirectory) mutationDirectoriesRef.current.delete(previousDirectory);
+        if (nextDirectory) mutationDirectoriesRef.current.delete(nextDirectory);
+        timers.delete(timer);
+      }, 2000);
       timers.add(timer);
       if (previous === nextPath) return;
-      const oldParent = previous.slice(0, previous.lastIndexOf('/'));
-      const newParent = nextPath.slice(0, nextPath.lastIndexOf('/'));
-      const source = nodesRef.current.get(previous);
-      const name = nextPath.split('/').pop()!;
-      const rename = (item: DocTreeItem): DocTreeItem => canonicalPath(item.fullPath) === previous ? { ...item, fullPath: nextPath, name, parentId: nodesRef.current.get(newParent)?.id ?? null } : item;
-      setNodes((current) => {
-        const cached = current.get(previous);
-        if (!cached) return current;
-        const result = new Map(current);
-        result.delete(previous);
-        result.set(nextPath, rename(cached));
-        for (const [path, item] of current) {
-          if (!item.children) continue;
-          if (oldParent === newParent && path === oldParent) result.set(path, { ...item, children: item.children.map(rename) });
-          else if (path === oldParent) result.set(path, { ...item, children: item.children.filter((child) => canonicalPath(child.fullPath) !== previous) });
-          else if (path === newParent) result.set(path, { ...item, children: [...item.children.filter((child) => canonicalPath(child.fullPath) !== nextPath), rename(cached)] });
-        }
-        return result;
-      });
-      setRootChildren((items) => {
-        if (oldParent === root && newParent === root) return items.some((item) => canonicalPath(item.fullPath) === previous) ? items.map(rename) : items;
-        if (oldParent === root) return items.filter((item) => canonicalPath(item.fullPath) !== previous);
-        if (newParent === root && source) return [...items.filter((item) => canonicalPath(item.fullPath) !== nextPath), rename(source)];
-        return items;
-      });
+      rebasePath(previous, nextPath);
     });
     return () => { stop(); for (const timer of timers) clearTimeout(timer); };
-  }, [folderPath]);
+  }, [folderPath, rebasePath]);
   useEffect(() => {
     mountedRef.current = true;
     return () => {
@@ -192,8 +355,19 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
     };
   }, []);
 
+  useEffect(() => {
+    return () => {
+      if (watcherRefreshTimerRef.current) {
+        clearTimeout(watcherRefreshTimerRef.current);
+        watcherRefreshTimerRef.current = null;
+      }
+      pendingWatcherDirectoriesRef.current.clear();
+    };
+  }, [folderPath]);
+
   const loadRoot = useCallback(async () => {
     const generation = ++generationRef.current;
+    setLoadedRootPath(null);
     setLoading(true);
     setError(null);
     setLoadingDirectories(new Set());
@@ -223,11 +397,11 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
     } finally {
       if (mountedRef.current && generation === generationRef.current) {
         setLoading(false);
+        setLoadedRootPath(canonicalDirectoryPath(folderPath));
       }
     }
   }, [folderPath]);
 
-  const rootKey = canonicalDirectoryPath(folderPath);
   const autoLoadKey = rootKey;
   const lastAutoLoadKeyRef = useRef<string | null>(null);
 
@@ -239,6 +413,7 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
 
   /** Coalesce concurrent reads of the same directory (manual action + watcher). */
   const refreshDirectory = useCallback((dirPath: string, force = false) => {
+    if (pendingRenamesRef.current > 0) return Promise.resolve();
     const key = canonicalDirectoryPath(dirPath);
     const pending = directoryRefreshesRef.current.get(key);
     if (pending && !force) return pending;
@@ -258,9 +433,20 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
       .then((children) => {
         if (
           !mountedRef.current
+          || pendingRenamesRef.current > 0
           || generation !== generationRef.current
           || directoryRefreshSequenceRef.current.get(key) !== requestSequence
         ) return;
+        const previousChildren = nodesRef.current.get(key)?.children ?? [];
+        const nextChildKeys = new Set(children.map((child) => canonicalPath(child.fullPath)));
+        const removedFolders = previousChildren
+          .filter((child) => child.type === 'folder' && !nextChildKeys.has(canonicalPath(child.fullPath)))
+          .map((child) => child.fullPath);
+        if (removedFolders.length > 0) {
+          // Expansion state is path-based. Drop removed folder paths as well as
+          // cached nodes so a later same-name import starts collapsed.
+          setExpanded((previous) => pruneExpandedSubtrees(previous, removedFolders));
+        }
         // Preserve loaded descendants that still exist, but remove deleted or
         // moved-away children (and their cached subtrees) from the flat node
         // table. Without pruning, long-running watcher refreshes retain stale
@@ -282,7 +468,9 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
       })
       .catch((err) => {
         logger.warn('refresh directory failed', { dirPath, err });
-        if (!mountedRef.current || generation !== generationRef.current) return;
+        if (!mountedRef.current || generation !== generationRef.current
+          || pendingRenamesRef.current > 0
+          || directoryRefreshSequenceRef.current.get(key) !== requestSequence) return;
         setDirectoryErrors((previous) => new Set(previous).add(key));
       })
       .finally(() => {
@@ -375,6 +563,7 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
 
   /** Watcher-only root refresh; unlike the manual reload it preserves expansion. */
   const refreshRootPreservingExpansion = useCallback((force = false) => {
+    if (pendingRenamesRef.current > 0) return Promise.resolve();
     if (rootRefreshRef.current && !force) return rootRefreshRef.current;
     const requestSequence = rootRefreshSequenceRef.current + 1;
     rootRefreshSequenceRef.current = requestSequence;
@@ -383,6 +572,7 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
       .then((items) => {
         if (
           !mountedRef.current
+          || pendingRenamesRef.current > 0
           || generation !== generationRef.current
           || rootRefreshSequenceRef.current !== requestSequence
         ) return;
@@ -394,6 +584,13 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
           setError('unreadable');
           return;
         }
+        const nextChildKeys = new Set(items.map((item) => canonicalPath(item.fullPath)));
+        const removedFolders = rootChildrenRef.current
+          .filter((item) => item.type === 'folder' && !nextChildKeys.has(canonicalPath(item.fullPath)))
+          .map((item) => item.fullPath);
+        if (removedFolders.length > 0) {
+          setExpanded((previous) => pruneExpandedSubtrees(previous, removedFolders));
+        }
         setRootChildren(items);
         setNodes((prev) => reconcileRootChildren(prev, rootChildrenRef.current, items));
         setError(null);
@@ -422,6 +619,10 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
 
   /** 局部刷新某个目录的子级 (新建/删除/重命名后调用)。 */
   const refresh = useCallback(async (dirPath?: string) => {
+    if (pendingRenamesRef.current > 0) {
+      pendingRenameRefreshDirectoriesRef.current.add(canonicalDirectoryPath(dirPath ?? rootKey));
+      return;
+    }
     try {
       if (dirPath && canonicalDirectoryPath(dirPath) !== rootKey) {
         await refreshDirectory(dirPath, true);
@@ -438,14 +639,18 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
 
   /**
    * Reconcile native watcher notifications without throwing away expansion
-   * state. Expanded directories are refreshed immediately; collapsed ones are
-   * marked dirty and reread on their next expand.
+   * state. Expanded directories are refreshed; collapsed ones are marked dirty
+   * and reread on their next expand.
    */
-  const refreshDirectories = useCallback(async (dirPaths: string[]) => {
+  const refreshDirectoriesNow = useCallback(async (dirPaths: string[]) => {
     const keys = [...new Set(dirPaths.map((path) => canonicalDirectoryPath(path)))];
     if (keys.length === 0) return;
+    if (pendingRenamesRef.current > 0) {
+      for (const key of keys) pendingWatcherDirectoriesRef.current.add(key);
+      return;
+    }
 
-    const expandedSnapshot = expanded;
+    const expandedSnapshot = expandedRef.current;
     const now = Date.now();
     const refreshNow = keys.filter((key) => (
       (key === rootKey || expandedSnapshot.has(key))
@@ -469,7 +674,59 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
 
       await refreshDirectory(key);
     }));
-  }, [expanded, refresh, refreshRootPreservingExpansion, rootKey]);
+  }, [refreshRootPreservingExpansion, rootKey]);
+
+  /** Merge a burst of native watcher events and refresh after it settles. */
+  const refreshDirectories = useCallback((dirPaths: string[]) => {
+    for (const path of dirPaths) {
+      pendingWatcherDirectoriesRef.current.add(canonicalDirectoryPath(path));
+    }
+    if (watcherRefreshTimerRef.current) clearTimeout(watcherRefreshTimerRef.current);
+    watcherRefreshTimerRef.current = setTimeout(() => {
+      watcherRefreshTimerRef.current = null;
+      const pending = [...pendingWatcherDirectoriesRef.current];
+      pendingWatcherDirectoriesRef.current.clear();
+      void refreshDirectoriesNow(pending);
+    }, WATCHER_REFRESH_DEBOUNCE_MS);
+  }, [refreshDirectoriesNow]);
+
+  /** Keep watcher refreshes from publishing the gap between disk rename and index completion. */
+  const renameFolder = useCallback(async (path: string, name: string, scopePath: string) => {
+    pendingRenamesRef.current += 1;
+    const sourcePath = canonicalDirectoryPath(path);
+    let renamedPath: string | null = null;
+    try {
+      renamedPath = await files.renameFolder(path, name, scopePath);
+      rebasePath(path, renamedPath);
+      return renamedPath;
+    } finally {
+      const sourceParent = sourcePath.slice(0, sourcePath.lastIndexOf('/')) || '/';
+      pendingRenameRefreshDirectoriesRef.current.add(sourceParent);
+      if (renamedPath) {
+        const nextPath = canonicalDirectoryPath(renamedPath);
+        pendingRenameRefreshDirectoriesRef.current.add(nextPath.slice(0, nextPath.lastIndexOf('/')) || '/');
+      }
+      pendingRenamesRef.current -= 1;
+      if (pendingRenamesRef.current === 0) {
+        if (watcherRefreshTimerRef.current) {
+          clearTimeout(watcherRefreshTimerRef.current);
+          watcherRefreshTimerRef.current = null;
+        }
+        const parents = [...pendingRenameRefreshDirectoriesRef.current];
+        pendingRenameRefreshDirectoriesRef.current.clear();
+        const watcherDirectories = [...pendingWatcherDirectoriesRef.current];
+        pendingWatcherDirectoriesRef.current.clear();
+        void Promise.all(parents.map((parent) => refresh(parent)))
+          .then(() => {
+            const refreshedParents = new Set(parents);
+            return refreshDirectoriesNow(watcherDirectories.filter((directory) => !refreshedParents.has(directory)));
+          })
+          .catch((error) => {
+            logger.warn('refresh after folder rename failed', { path, error });
+          });
+      }
+    }
+  }, [rebasePath, refresh, refreshDirectoriesNow]);
 
   const state: FolderTreeState = useMemo(
     () => ({ rootChildren, nodes, expanded, loading, error, loadingDirectories, directoryErrors }),
@@ -478,6 +735,7 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
 
   return useMemo(() => ({
     ...state,
+    loadedRootPath,
     toggle,
     expandTo,
     collapseAll,
@@ -485,8 +743,10 @@ export function useFolderTree(folderPath: string, options?: FolderTreeOptions) {
     refreshDirectories,
     reload: loadRoot,
     retryDirectory,
+    rebasePath,
+    renameFolder,
     ignoreCollectionPathEvents,
-  }), [ignoreCollectionPathEvents, state, toggle, expandTo, collapseAll, refresh, refreshDirectories, loadRoot, retryDirectory]);
+  }), [ignoreCollectionPathEvents, loadedRootPath, state, toggle, expandTo, collapseAll, refresh, refreshDirectories, loadRoot, retryDirectory, rebasePath, renameFolder]);
 }
 
 export type FolderTreeController = ReturnType<typeof useFolderTree>;
@@ -537,8 +797,10 @@ function compareTreeItems(sort: FolderTreeSort, a: DocTreeItem, b: DocTreeItem):
     return sort === 'filenameDesc' ? -order : order;
   }
 
-  const aTime = sort === 'updatedAt' ? a.modifiedMs : a.createdMs;
-  const bTime = sort === 'updatedAt' ? b.modifiedMs : b.createdMs;
+  // Notebook notes have an indexed creation timestamp that survives atomic
+  // file replacement. Prefer it over filesystem birth time for created sorting.
+  const aTime = sort === 'updatedAt' ? a.modifiedMs : (a.memoCreatedMs ?? a.createdMs);
+  const bTime = sort === 'updatedAt' ? b.modifiedMs : (b.memoCreatedMs ?? b.createdMs);
   if (aTime === null && bTime !== null) return 1;
   if (aTime !== null && bTime === null) return -1;
   if (aTime !== null && bTime !== null && aTime !== bTime) return bTime - aTime;
diff --git a/app/flowix-web/features/memo/components/use-notebook-pinned-notes.ts b/app/flowix-web/features/memo/components/use-notebook-pinned-notes.ts
new file mode 100644
index 000000000..17003e917
--- /dev/null
+++ b/app/flowix-web/features/memo/components/use-notebook-pinned-notes.ts
@@ -0,0 +1,117 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { createLogger } from '@/lib/logger';
+import { joinNotebookMemoPath } from '@/lib/path';
+import { noteRepository } from '@features/memo/services/note-repository';
+import { registerMemoEventHandler } from '@/lib/memo-dispatcher';
+import type { DocTreeItem, NoteEntry } from '@platform/tauri/client';
+import { subscribeNotebookChanges } from '@platform/tauri/notebook-change-events';
+
+const logger = createLogger('notebook-pinned-notes');
+const PINNED_NOTES_PAGE_SIZE = 100;
+
+interface UseNotebookPinnedNotesOptions {
+  notebookId: string | null;
+  notebookPath: string;
+  isActive: boolean;
+  refreshTrigger: number;
+}
+
+export function useNotebookPinnedNotes({
+  notebookId,
+  notebookPath,
+  isActive,
+  refreshTrigger,
+}: UseNotebookPinnedNotesOptions) {
+  const [pinnedItems, setPinnedItems] = useState<DocTreeItem[]>([]);
+  const requestSequence = useRef(0);
+  const loadedScope = useRef<{ notebookId: string; notebookPath: string } | null>(null);
+  const [changeRevision, setChangeRevision] = useState(0);
+
+  useEffect(() => subscribeNotebookChanges((change) => {
+    if (change.notebookId === notebookId
+      && (change.kind !== 'resource-created' || change.source === 'external_tool')) {
+      setChangeRevision((revision) => revision + 1);
+    }
+  }), [notebookId]);
+
+  useEffect(() => registerMemoEventHandler((event) => {
+    if (event.notebookId !== notebookId || event.kind === 'tags_renamed' || event.kind === 'tags_deleted') return;
+    if (event.kind === 'deleted' || event.source === 'cloud_sync') {
+      setChangeRevision((revision) => revision + 1);
+    }
+  }), [notebookId]);
+
+  useEffect(() => {
+    if (!isActive) return;
+    if (!notebookId) {
+      loadedScope.current = null;
+      setPinnedItems([]);
+      return;
+    }
+    if (loadedScope.current?.notebookId !== notebookId || loadedScope.current.notebookPath !== notebookPath) {
+      setPinnedItems([]);
+    }
+    let cancelled = false;
+    const sequence = ++requestSequence.current;
+
+    void (async () => {
+      const notes: NoteEntry[] = [];
+      const seenCursors = new Set<string>();
+      let cursor: string | undefined;
+      while (!cancelled) {
+        const page = await noteRepository.listByPath({
+          notebookId,
+          filter: 'favorited',
+          sort: 'updatedAt',
+          cursor,
+          limit: PINNED_NOTES_PAGE_SIZE,
+        });
+        notes.push(...page.notes);
+        const nextCursor = page.nextCursor ?? undefined;
+        if (!page.hasMore || !nextCursor || seenCursors.has(nextCursor)) break;
+        seenCursors.add(nextCursor);
+        cursor = nextCursor;
+      }
+
+      if (cancelled || sequence !== requestSequence.current) return;
+      setPinnedItems(notes.flatMap((note) => {
+        const relativePath = note.relativePath.replace(/\\/g, '/');
+        const fullPath = joinNotebookMemoPath(notebookPath, relativePath);
+        if (!fullPath) return [];
+        return [{
+          id: `pinned:${relativePath}`,
+          fullPath,
+          name: relativePath.split('/').pop() || relativePath,
+          type: 'document' as const,
+          parentId: null,
+          children: null,
+          sizeBytes: note.sizeBytes ?? null,
+          modifiedMs: note.updatedAt,
+          createdMs: note.createdAt,
+          memoCreatedMs: note.createdAt,
+          resourceKind: 'note' as const,
+          memoMeta: {
+            icon: note.icon,
+            colors: note.colors,
+            favorited: true,
+          },
+        }];
+      }));
+      loadedScope.current = { notebookId, notebookPath };
+    })().catch((error) => {
+      if (!cancelled) logger.warn('failed to load pinned notes', { error, notebookPath });
+    });
+
+    return () => {
+      cancelled = true;
+      if (requestSequence.current === sequence) requestSequence.current += 1;
+    };
+  }, [isActive, notebookId, notebookPath, refreshTrigger, changeRevision]);
+
+  const removePinnedItem = useCallback((itemId: string) => {
+    setPinnedItems((items) => items.filter((item) => item.id !== itemId));
+  }, []);
+
+  return { pinnedItems, removePinnedItem };
+}
diff --git a/app/flowix-web/features/memo/components/use-notebook-tree-drag-controller.ts b/app/flowix-web/features/memo/components/use-notebook-tree-drag-controller.ts
new file mode 100644
index 000000000..b03668a49
--- /dev/null
+++ b/app/flowix-web/features/memo/components/use-notebook-tree-drag-controller.ts
@@ -0,0 +1,508 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState, type PointerEvent as ReactPointerEvent, type RefObject } from 'react';
+
+import { beginDragSession, cancelDragSession, endDragSession, moveDragSession } from '@shared/drag-drop/drag-drop-coordinator';
+import type { DragPayload } from '@shared/drag-drop/drag-drop-coordinator';
+import type { NotebookDragResource } from '@features/memo/public/drag-resource-api';
+import { canonicalDirectoryPath, canonicalPath, fileNameFromPath, notebookRelativeDirectoryPath, parentDirectoryPath, pathInDirectory, samePath, uniquePaths } from '@/lib/path';
+import { createLogger } from '@/lib/logger';
+import { displayTitleFromFilename } from '@/lib/utils';
+import { showNotebookMoveFailureToasts, normalizeNotebookMoveFailure, type NotebookMoveFailure } from './notebook-move-failure-toast';
+import { resourceKindFromPath } from '@features/editor/public/code-file';
+import { EXTERNAL_FILE_DROP_EVENT, type ExternalFileDropDetail } from '@features/document/public/shell-api';
+import type { DocTreeItem } from '@platform/tauri/client';
+import type { FolderTreeController } from './use-folder-tree';
+import { TREE_DRAG_EXPAND_DELAY_MS, TREE_DRAG_SCROLL_EDGE, TREE_DRAG_SCROLL_MAX_STEP, TREE_EXTERNAL_DRAG_EXPAND_DELAY_MS } from './notebook-tree-layout';
+
+const logger = createLogger('notebook-file-tree');
+
+export interface NotebookMoveResult {
+  movedPaths: string[];
+  failedPaths: string[];
+  failures?: NotebookMoveFailure[];
+}
+
+export interface NotebookMoveSource {
+  path: string;
+  resourceKind?: DocTreeItem['resourceKind'] | null;
+  isFolder?: boolean;
+}
+
+interface NotebookMoveFeedback {
+  paths: string[];
+  targetDirectoryPath: string;
+  status: 'moving' | 'success';
+}
+
+interface PointerNoteDrag {
+  sourceType: 'folder' | 'document';
+  sourcePath: string;
+  sourcePaths: string[];
+  sourceItems: NotebookMoveSource[];
+  dragPayload: DragPayload<NotebookDragResource>;
+  preserveSelectionAfterMove: boolean;
+  sourceName: string;
+  pointerId: number;
+  captureElement: HTMLElement;
+  startX: number;
+  startY: number;
+  active: boolean;
+  targetDirectoryPath: string | null;
+}
+
+interface NotebookTreeDragOperations {
+  expanded: Set<string>;
+  toggle: (path: string) => void;
+  refresh: FolderTreeController['refresh'];
+}
+
+interface UseNotebookTreeDragControllerOptions {
+  notebookId?: string | null;
+  notebookPath: string;
+  tree: NotebookTreeDragOperations;
+  treeItemsByPath: ReadonlyMap<string, DocTreeItem>;
+  selectedFilePaths: string[];
+  getSelectionAnchorPath: () => string | null;
+  updateSelection: (paths: string[], anchorPath: string | null) => void;
+  onMoveNote: (sources: NotebookMoveSource[], targetDirectoryPath: string) => Promise<NotebookMoveResult>;
+  treeRootRef: RefObject<HTMLDivElement | null>;
+  treeHeaderRef: RefObject<HTMLDivElement | null>;
+  treeScrollerRef: RefObject<HTMLDivElement | null>;
+  externalDropSurfaceRef: RefObject<HTMLDivElement | null>;
+  t: Parameters<typeof showNotebookMoveFailureToasts>[0];
+}
+
+function resolveDropDirectory(hit: Element | null, treeRoot: HTMLElement, notebookPath: string): string | null {
+  if (!hit || !treeRoot.contains(hit)) return null;
+  const row = hit.closest<HTMLElement>('[data-notebook-tree-row="true"]');
+  if (row && treeRoot.contains(row)) {
+    return row.dataset.notebookDropPath
+      ?? row.dataset.notebookParentPath
+      ?? notebookPath;
+  }
+  return notebookPath;
+}
+
+/** Owns pointer and external drag state, move execution, and post-move selection. */
+export function useNotebookTreeDragController({
+  notebookId,
+  notebookPath,
+  tree,
+  treeItemsByPath,
+  selectedFilePaths,
+  getSelectionAnchorPath,
+  updateSelection,
+  onMoveNote,
+  treeRootRef,
+  treeHeaderRef,
+  treeScrollerRef,
+  externalDropSurfaceRef,
+  t,
+}: UseNotebookTreeDragControllerOptions) {
+  const pointerDragRef = useRef<PointerNoteDrag | null>(null);
+  const dropPendingRef = useRef(false);
+  const externalDropTargetPathRef = useRef<string | null>(null);
+  const dragPreviewRef = useRef<HTMLDivElement | null>(null);
+  const dragPreviewPositionRef = useRef({ x: 0, y: 0 });
+  const moveFeedbackTimerRef = useRef<number | null>(null);
+  const dragScrollFrameRef = useRef<number | null>(null);
+  const dragPointerPositionRef = useRef<{ x: number; y: number } | null>(null);
+  const dragExpandTimerRef = useRef<number | null>(null);
+  const dragExpandPathRef = useRef<string | null>(null);
+  const suppressOpenPathsRef = useRef<Set<string>>(new Set());
+  const [dragOverFolderPath, setDragOverFolderPath] = useState<string | null>(null);
+  const [dragPreview, setDragPreview] = useState<{ name: string; path: string; count: number } | null>(null);
+  const [moveFeedback, setMoveFeedback] = useState<NotebookMoveFeedback | null>(null);
+
+  const clearMoveFeedbackTimer = useCallback(() => {
+    if (moveFeedbackTimerRef.current === null) return;
+    window.clearTimeout(moveFeedbackTimerRef.current);
+    moveFeedbackTimerRef.current = null;
+  }, []);
+  useEffect(() => clearMoveFeedbackTimer, [clearMoveFeedbackTimer]);
+
+  const updateDragPreviewPosition = useCallback((x: number, y: number) => {
+    dragPreviewPositionRef.current = { x, y };
+    dragPreviewRef.current?.style.setProperty('transform', `translate3d(${x}px, ${y}px, 0)`);
+  }, []);
+
+  const clearDragExpandTimer = useCallback(() => {
+    dragExpandPathRef.current = null;
+    if (dragExpandTimerRef.current !== null) {
+      window.clearTimeout(dragExpandTimerRef.current);
+      dragExpandTimerRef.current = null;
+    }
+  }, []);
+
+  const scheduleFolderHoverExpand = useCallback((path: string | null, delayMs = TREE_DRAG_EXPAND_DELAY_MS) => {
+    const key = path ? canonicalPath(path) : null;
+    if (key === dragExpandPathRef.current) return;
+    clearDragExpandTimer();
+    if (!key) return;
+    const item = treeItemsByPath.get(key);
+    if (item?.type !== 'folder' || tree.expanded.has(key)) return;
+
+    dragExpandPathRef.current = key;
+    dragExpandTimerRef.current = window.setTimeout(() => {
+      dragExpandTimerRef.current = null;
+      dragExpandPathRef.current = null;
+      const pointerTarget = pointerDragRef.current?.targetDirectoryPath ?? null;
+      const externalTarget = externalDropTargetPathRef.current;
+      if (
+        (pointerTarget && samePath(pointerTarget, key))
+        || (externalTarget && samePath(externalTarget, key))
+      ) {
+        tree.toggle(item.fullPath);
+      }
+    }, delayMs);
+  }, [clearDragExpandTimer, tree.expanded, tree.toggle, treeItemsByPath]);
+
+  const stopDragAutoScroll = useCallback(() => {
+    dragPointerPositionRef.current = null;
+    if (dragScrollFrameRef.current !== null) {
+      window.cancelAnimationFrame(dragScrollFrameRef.current);
+      dragScrollFrameRef.current = null;
+    }
+  }, []);
+
+  const handleDrop = useCallback(async (
+    targetDirectoryPath: string,
+    sourceItemsOverride?: NotebookMoveSource[],
+    preserveSelectionAfterMove = false,
+  ) => {
+    if (dropPendingRef.current) return;
+    const sourceItems = sourceItemsOverride ?? pointerDragRef.current?.sourceItems ?? [];
+    const sourcePaths = sourceItems.map((source) => source.path);
+    if (sourcePaths.length === 0) return;
+    const targetPath = canonicalDirectoryPath(targetDirectoryPath);
+    const movableSourceItems = sourceItems.filter(
+      (source) => parentDirectoryPath(source.path, notebookPath) !== targetPath,
+    );
+    const movableSourcePaths = movableSourceItems.map((source) => source.path);
+    pointerDragRef.current = null;
+    setDragOverFolderPath(null);
+    setDragPreview(null);
+    if (movableSourcePaths.length === 0) return;
+    dropPendingRef.current = true;
+    clearMoveFeedbackTimer();
+    setMoveFeedback({ paths: movableSourcePaths, targetDirectoryPath: targetPath, status: 'moving' });
+    try {
+      const startedAt = performance.now();
+      const moveResult = await onMoveNote(movableSourceItems, targetDirectoryPath);
+      const moveFinishedAt = performance.now();
+      const rootPath = canonicalDirectoryPath(notebookPath);
+      const sourceParents = uniquePaths(
+        movableSourcePaths.map((sourcePath) => parentDirectoryPath(sourcePath, notebookPath)),
+      ).filter((path) => path === rootPath || path.startsWith(`${rootPath}/`));
+      const refreshPaths = moveResult.movedPaths.length > 0
+        ? [...sourceParents, targetDirectoryPath]
+        : sourceParents;
+      await Promise.all(uniquePaths(refreshPaths).map((path) => tree.refresh(path)));
+      const refreshFinishedAt = performance.now();
+      logger.debug('notebook tree drop completed', {
+        requestedCount: movableSourcePaths.length,
+        movedCount: moveResult.movedPaths.length,
+        failedCount: moveResult.failedPaths.length,
+        moveDurationMs: Math.round(moveFinishedAt - startedAt),
+        refreshDurationMs: Math.round(refreshFinishedAt - moveFinishedAt),
+        totalDurationMs: Math.round(refreshFinishedAt - startedAt),
+      });
+
+      const unchangedSelection = sourcePaths.filter((sourcePath) => (
+        parentDirectoryPath(sourcePath, notebookPath) === targetPath
+      ));
+      const nextSelection = uniquePaths([
+        ...moveResult.movedPaths,
+        ...moveResult.failedPaths,
+        ...unchangedSelection,
+      ]);
+      const selectedAnchor = getSelectionAnchorPath();
+      const movedAnchor = selectedAnchor
+        ? moveResult.movedPaths.find((path) => samePath(path, pathInDirectory(targetPath, selectedAnchor)))
+        : null;
+      const nextAnchor = movedAnchor
+        ?? (selectedAnchor && moveResult.failedPaths.some((path) => samePath(path, selectedAnchor))
+          ? selectedAnchor
+          : selectedAnchor && unchangedSelection.some((path) => samePath(path, selectedAnchor))
+            ? selectedAnchor
+            : nextSelection[nextSelection.length - 1] ?? null);
+      if (preserveSelectionAfterMove) updateSelection(nextSelection, nextAnchor);
+      if (moveResult.movedPaths.length > 0) {
+        setMoveFeedback({ paths: moveResult.movedPaths, targetDirectoryPath: targetPath, status: 'success' });
+        moveFeedbackTimerRef.current = window.setTimeout(() => {
+          moveFeedbackTimerRef.current = null;
+          setMoveFeedback(null);
+        }, 450);
+      } else {
+        setMoveFeedback(null);
+      }
+      if (moveResult.failedPaths.length > 0) {
+        showNotebookMoveFailureToasts(t, moveResult.movedPaths.length, moveResult.failedPaths.length, moveResult.failures ?? []);
+      }
+    } catch (error) {
+      clearMoveFeedbackTimer();
+      setMoveFeedback(null);
+      showNotebookMoveFailureToasts(t, 0, 1, [normalizeNotebookMoveFailure(error)]);
+    } finally {
+      dropPendingRef.current = false;
+    }
+  }, [clearMoveFeedbackTimer, getSelectionAnchorPath, notebookPath, onMoveNote, t, tree.refresh, updateSelection]);
+
+  const updatePointerDropTarget = useCallback((clientX: number, clientY: number) => {
+    const drag = pointerDragRef.current;
+    const treeRoot = treeRootRef.current;
+    if (!drag?.active || !treeRoot) return;
+    const hit = document.elementFromPoint(clientX, clientY);
+    const hitTree = hit?.closest<HTMLElement>('[data-notebook-tree-root="true"]');
+    const isOverHeader = Boolean(hit && treeHeaderRef.current?.contains(hit));
+    const candidateDirectoryPath = hitTree === treeRoot
+      ? resolveDropDirectory(hit, treeRoot, notebookPath)
+      : isOverHeader
+        ? notebookPath
+        : null;
+    const targetDirectoryPath = candidateDirectoryPath && drag.sourcePaths.some((sourcePath) => {
+      const target = canonicalDirectoryPath(candidateDirectoryPath);
+      if (drag.sourceType === 'folder') {
+        const source = canonicalDirectoryPath(sourcePath);
+        if (target === source || target.startsWith(`${source}/`)) return false;
+      }
+      return parentDirectoryPath(sourcePath, notebookPath) !== target;
+    }) ? candidateDirectoryPath : null;
+    if (drag.targetDirectoryPath !== targetDirectoryPath) {
+      drag.targetDirectoryPath = targetDirectoryPath;
+      setDragOverFolderPath(targetDirectoryPath);
+      scheduleFolderHoverExpand(targetDirectoryPath);
+    }
+  }, [notebookPath, scheduleFolderHoverExpand, treeHeaderRef, treeRootRef]);
+
+  const scheduleDragAutoScroll = useCallback((clientX: number, clientY: number) => {
+    dragPointerPositionRef.current = { x: clientX, y: clientY };
+    if (dragScrollFrameRef.current !== null) return;
+    const tick = () => {
+      dragScrollFrameRef.current = null;
+      const drag = pointerDragRef.current;
+      const position = dragPointerPositionRef.current;
+      const scroller = treeScrollerRef.current;
+      if (!drag?.active || !position || !scroller) return;
+      const bounds = scroller.getBoundingClientRect();
+      const topDistance = position.y - bounds.top;
+      const bottomDistance = bounds.bottom - position.y;
+      let delta = 0;
+      if (topDistance >= 0 && topDistance < TREE_DRAG_SCROLL_EDGE) {
+        delta = -TREE_DRAG_SCROLL_MAX_STEP * (1 - topDistance / TREE_DRAG_SCROLL_EDGE);
+      } else if (bottomDistance >= 0 && bottomDistance < TREE_DRAG_SCROLL_EDGE) {
+        delta = TREE_DRAG_SCROLL_MAX_STEP * (1 - bottomDistance / TREE_DRAG_SCROLL_EDGE);
+      }
+      if (delta !== 0) {
+        const previousScrollTop = scroller.scrollTop;
+        scroller.scrollTop = Math.max(0, previousScrollTop + delta);
+        if (scroller.scrollTop !== previousScrollTop) {
+          scroller.dispatchEvent(new Event('scroll'));
+          updatePointerDropTarget(position.x, position.y);
+          dragScrollFrameRef.current = window.requestAnimationFrame(tick);
+        }
+      }
+    };
+    dragScrollFrameRef.current = window.requestAnimationFrame(tick);
+  }, [treeScrollerRef, updatePointerDropTarget]);
+
+  const startItemDrag = useCallback((item: DocTreeItem, event: ReactPointerEvent<HTMLDivElement>) => {
+    if (dropPendingRef.current || event.button !== 0) return;
+    if (item.type === 'folder') {
+      const captureElement = event.currentTarget;
+      captureElement.setPointerCapture(event.pointerId);
+      pointerDragRef.current = {
+        sourceType: 'folder',
+        sourcePath: item.fullPath,
+        sourcePaths: [item.fullPath],
+        sourceItems: [{ path: item.fullPath, isFolder: true }],
+        dragPayload: {
+          sessionId: crypto.randomUUID(),
+          sourceId: `notebook-file-tree:${notebookId ?? canonicalPath(notebookPath)}`,
+          items: [{ kind: 'folder', absolutePath: item.fullPath, name: item.name }],
+        },
+        preserveSelectionAfterMove: false,
+        sourceName: item.name,
+        pointerId: event.pointerId,
+        captureElement,
+        startX: event.clientX,
+        startY: event.clientY,
+        active: false,
+        targetDirectoryPath: null,
+      };
+      return;
+    }
+    const isSelected = selectedFilePaths.some((path) => samePath(path, item.fullPath));
+    const sourcePaths = isSelected ? selectedFilePaths : [item.fullPath];
+    const sourceItems = sourcePaths.map((path) => {
+      const sourceItem = samePath(path, item.fullPath) ? item : treeItemsByPath.get(canonicalPath(path));
+      const resourceMetadata = sourceItem?.resourceKind ? { resourceKind: sourceItem.resourceKind } : {};
+      return { path, ...resourceMetadata };
+    });
+    const resources = sourcePaths.map((path): NotebookDragResource => {
+      const sourceItem = samePath(path, item.fullPath) ? item : treeItemsByPath.get(canonicalPath(path));
+      const name = sourceItem?.name ?? fileNameFromPath(path);
+      const relativeParent = notebookRelativeDirectoryPath(notebookPath, parentDirectoryPath(path, notebookPath));
+      if (sourceItem?.type === 'document' && notebookId && relativeParent !== null && /\.(?:md|markdown)$/i.test(name)) {
+        return {
+          kind: 'note',
+          notebookId,
+          relativePath: [relativeParent, fileNameFromPath(path)].filter(Boolean).join('/'),
+          title: displayTitleFromFilename(name),
+        };
+      }
+      return { kind: 'file', absolutePath: path, name, resourceKind: sourceItem?.resourceKind };
+    });
+    const captureElement = event.currentTarget;
+    captureElement.setPointerCapture(event.pointerId);
+    pointerDragRef.current = {
+      sourceType: 'document',
+      sourcePath: item.fullPath,
+      sourcePaths,
+      sourceItems,
+      dragPayload: {
+        sessionId: crypto.randomUUID(),
+        sourceId: `notebook-file-tree:${notebookId ?? canonicalPath(notebookPath)}`,
+        items: resources,
+      },
+      preserveSelectionAfterMove: isSelected,
+      sourceName: displayTitleFromFilename(item.name),
+      pointerId: event.pointerId,
+      captureElement,
+      startX: event.clientX,
+      startY: event.clientY,
+      active: false,
+      targetDirectoryPath: null,
+    };
+  }, [notebookId, notebookPath, selectedFilePaths, treeItemsByPath]);
+
+  const handlePointerMove = useCallback((event: ReactPointerEvent<HTMLDivElement>) => {
+    const drag = pointerDragRef.current;
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    if (!drag.active) {
+      if (Math.hypot(event.clientX - drag.startX, event.clientY - drag.startY) < 5) return;
+      drag.active = true;
+      setDragPreview({ name: drag.sourceName, path: drag.sourcePath, count: drag.sourcePaths.length });
+      beginDragSession(drag.dragPayload, { x: event.clientX, y: event.clientY }, () => {
+        const active = pointerDragRef.current;
+        if (!active || active.pointerId !== drag.pointerId) return;
+        stopDragAutoScroll();
+        clearDragExpandTimer();
+        if (active.captureElement.hasPointerCapture(active.pointerId)) {
+          active.captureElement.releasePointerCapture(active.pointerId);
+        }
+        pointerDragRef.current = null;
+        setDragOverFolderPath(null);
+        setDragPreview(null);
+      });
+    }
+    event.preventDefault();
+    updateDragPreviewPosition(event.clientX + 12, event.clientY + 12);
+    updatePointerDropTarget(event.clientX, event.clientY);
+    moveDragSession(drag.dragPayload.sessionId, { x: event.clientX, y: event.clientY });
+    scheduleDragAutoScroll(event.clientX, event.clientY);
+  }, [clearDragExpandTimer, scheduleDragAutoScroll, stopDragAutoScroll, updateDragPreviewPosition, updatePointerDropTarget]);
+
+  const handlePointerUp = useCallback((event: ReactPointerEvent<HTMLDivElement>) => {
+    const drag = pointerDragRef.current;
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    stopDragAutoScroll();
+    clearDragExpandTimer();
+    if (drag.captureElement.hasPointerCapture(drag.pointerId)) drag.captureElement.releasePointerCapture(drag.pointerId);
+    pointerDragRef.current = null;
+    setDragOverFolderPath(null);
+    setDragPreview(null);
+    if (!drag.active) return;
+    event.preventDefault();
+    const suppressedPaths = new Set(drag.sourcePaths.map((sourcePath) => canonicalPath(sourcePath)));
+    suppressOpenPathsRef.current = suppressedPaths;
+    window.setTimeout(() => {
+      if (suppressOpenPathsRef.current === suppressedPaths) suppressOpenPathsRef.current = new Set();
+    }, 0);
+    const handledByDropTarget = endDragSession(drag.dragPayload.sessionId, { x: event.clientX, y: event.clientY });
+    if (handledByDropTarget || !drag.targetDirectoryPath) return;
+    void handleDrop(drag.targetDirectoryPath, drag.sourceItems, drag.preserveSelectionAfterMove);
+  }, [clearDragExpandTimer, handleDrop, stopDragAutoScroll]);
+
+  const handlePointerCancel = useCallback((event: ReactPointerEvent<HTMLDivElement>) => {
+    const drag = pointerDragRef.current;
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    cancelDragSession(drag.dragPayload.sessionId);
+    stopDragAutoScroll();
+    clearDragExpandTimer();
+    pointerDragRef.current = null;
+    setDragOverFolderPath(null);
+    setDragPreview(null);
+  }, [clearDragExpandTimer, stopDragAutoScroll]);
+
+  useEffect(() => () => {
+    const drag = pointerDragRef.current;
+    if (drag?.active) cancelDragSession(drag.dragPayload.sessionId);
+  }, []);
+  useEffect(() => () => {
+    stopDragAutoScroll();
+    clearDragExpandTimer();
+  }, [clearDragExpandTimer, stopDragAutoScroll]);
+
+  useEffect(() => {
+    const dropSurface = externalDropSurfaceRef.current;
+    if (!dropSurface) return;
+    const updateExternalDropTarget = (detail: ExternalFileDropDetail, hit: Element | null) => {
+      if (dropPendingRef.current) {
+        externalDropTargetPathRef.current = null;
+        scheduleFolderHoverExpand(null);
+        setDragOverFolderPath(null);
+        return;
+      }
+      if (detail.type === 'leave' || detail.paths.length === 0) {
+        externalDropTargetPathRef.current = null;
+        scheduleFolderHoverExpand(null);
+        if (!pointerDragRef.current) setDragOverFolderPath(null);
+        return;
+      }
+      const targetDirectoryPath = hit ? resolveDropDirectory(hit, dropSurface, notebookPath) : null;
+      const targetPath = targetDirectoryPath ? canonicalDirectoryPath(targetDirectoryPath) : null;
+      const canDrop = targetPath !== null && detail.paths.some((path) => parentDirectoryPath(path, notebookPath) !== targetPath);
+      const nextTargetPath = canDrop ? targetPath : null;
+      const previousTargetPath = externalDropTargetPathRef.current;
+      externalDropTargetPathRef.current = nextTargetPath;
+      if (previousTargetPath !== nextTargetPath) setDragOverFolderPath(nextTargetPath);
+      if (detail.type === 'drop') {
+        scheduleFolderHoverExpand(null);
+        if (!nextTargetPath) return;
+        externalDropTargetPathRef.current = null;
+        void handleDrop(nextTargetPath, detail.paths.map((path) => ({ path, resourceKind: resourceKindFromPath(path) })));
+        return;
+      }
+      if (previousTargetPath !== nextTargetPath || !nextTargetPath) {
+        scheduleFolderHoverExpand(nextTargetPath, TREE_EXTERNAL_DRAG_EXPAND_DELAY_MS);
+      }
+    };
+    const onExternalFileDrop = (event: Event) => {
+      const detail = (event as CustomEvent<ExternalFileDropDetail>).detail;
+      if (!detail) return;
+      updateExternalDropTarget(detail, event.target instanceof Element ? event.target : null);
+    };
+    dropSurface.addEventListener(EXTERNAL_FILE_DROP_EVENT, onExternalFileDrop);
+    return () => {
+      dropSurface.removeEventListener(EXTERNAL_FILE_DROP_EVENT, onExternalFileDrop);
+      externalDropTargetPathRef.current = null;
+    };
+  }, [externalDropSurfaceRef, handleDrop, notebookPath, scheduleFolderHoverExpand]);
+
+  const shouldSuppressOpen = useCallback((path: string) => suppressOpenPathsRef.current.has(canonicalPath(path)), []);
+
+  return {
+    dragOverFolderPath,
+    dragPreview,
+    dragPreviewRef,
+    dragPreviewPositionRef,
+    moveFeedback,
+    startItemDrag,
+    handlePointerMove,
+    handlePointerUp,
+    handlePointerCancel,
+    shouldSuppressOpen,
+  };
+}
diff --git a/app/flowix-web/features/memo/components/use-notebook-tree-interaction.ts b/app/flowix-web/features/memo/components/use-notebook-tree-interaction.ts
new file mode 100644
index 000000000..a89bdb69b
--- /dev/null
+++ b/app/flowix-web/features/memo/components/use-notebook-tree-interaction.ts
@@ -0,0 +1,286 @@
+'use client';
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type MouseEvent, type RefObject } from 'react';
+
+import { canonicalPath, samePath, uniquePaths } from '@/lib/path';
+import { TREE_ROW_HEIGHT, TREE_ROW_SIZE } from './notebook-tree-layout';
+import type { VisibleTreeNode } from './use-folder-tree';
+
+interface NotebookTreeController {
+  expanded: Set<string>;
+  toggle: (path: string) => void;
+}
+
+interface NotebookTreeNavigationPolicy {
+  path: string;
+  policy: 'reveal' | 'preserve';
+}
+
+interface NotebookTreeNavigationPolicies {
+  active: NotebookTreeNavigationPolicy | null;
+  pending: NotebookTreeNavigationPolicy | null;
+}
+
+function getNavigationPolicyForPath(
+  path: string | null,
+  policies: NotebookTreeNavigationPolicies,
+): NotebookTreeNavigationPolicy | null {
+  if (!path) return null;
+  if (policies.pending?.path === path) return policies.pending;
+  if (policies.active?.path === path) return policies.active;
+  return null;
+}
+
+interface UseNotebookTreeInteractionOptions {
+  activeFilePath: string | null;
+  visibleTreeItems: VisibleTreeNode[];
+  treeItemPaths: ReadonlySet<string>;
+  tree: NotebookTreeController;
+  treeRootRef: RefObject<HTMLDivElement | null>;
+  treeScrollerRef: RefObject<HTMLDivElement | null>;
+  renderRowIndexByPath: ReadonlyMap<string, number>;
+  treeContentOffset: number;
+  onNoteSelect: (path: string) => void;
+}
+
+/** Owns the file tree's selection, keyboard focus, and active-row navigation. */
+export function useNotebookTreeInteraction({
+  activeFilePath,
+  visibleTreeItems,
+  treeItemPaths,
+  tree,
+  treeRootRef,
+  treeScrollerRef,
+  renderRowIndexByPath,
+  treeContentOffset,
+  onNoteSelect,
+}: UseNotebookTreeInteractionOptions) {
+  const [selectedFilePaths, setSelectedFilePaths] = useState<string[]>([]);
+  const [focusedTreePath, setFocusedTreePath] = useState<string | null>(null);
+  const selectedFilePathsRef = useRef<string[]>([]);
+  const selectionAnchorPathRef = useRef<string | null>(null);
+  const previousActiveFilePathRef = useRef(activeFilePath ? canonicalPath(activeFilePath) : null);
+  const pendingActiveFileScrollPathRef = useRef(activeFilePath ? canonicalPath(activeFilePath) : null);
+  const [navigationPolicies, setNavigationPolicies] = useState<NotebookTreeNavigationPolicies>({
+    active: null,
+    pending: null,
+  });
+  const activePath = activeFilePath ? canonicalPath(activeFilePath) : null;
+  const navigationPolicyForActivePath = getNavigationPolicyForPath(activePath, navigationPolicies);
+  const activeFileShouldReveal = !activeFilePath
+    || navigationPolicyForActivePath?.policy !== 'preserve';
+
+  const selectedFilePathSet = useMemo(
+    () => new Set(selectedFilePaths.map((path) => canonicalPath(path))),
+    [selectedFilePaths],
+  );
+  const visibleDocumentPaths = useMemo(
+    () => visibleTreeItems
+      .filter(({ item }) => item.type === 'document')
+      .map(({ item }) => item.fullPath),
+    [visibleTreeItems],
+  );
+
+  const updateSelection = useCallback((paths: string[], anchorPath: string | null) => {
+    const nextPaths = uniquePaths(paths);
+    selectedFilePathsRef.current = nextPaths;
+    selectionAnchorPathRef.current = anchorPath;
+    setSelectedFilePaths(nextPaths);
+  }, []);
+  const getSelectionAnchorPath = useCallback(() => selectionAnchorPathRef.current, []);
+
+  const setNavigationPolicy = useCallback((path: string, policy: 'reveal' | 'preserve') => {
+    const intent = { path: canonicalPath(path), policy };
+    const currentActivePath = activeFilePath ? canonicalPath(activeFilePath) : null;
+    setNavigationPolicies((current) => intent.path === currentActivePath
+      ? { active: intent, pending: null }
+      // Keep the current file's policy until the requested path becomes active.
+      : { ...current, pending: intent });
+  }, [activeFilePath]);
+
+  const navigateToNote = useCallback((path: string, policy: 'reveal' | 'preserve') => {
+    setNavigationPolicy(path, policy);
+    onNoteSelect(path);
+  }, [onNoteSelect, setNavigationPolicy]);
+
+  useLayoutEffect(() => {
+    const nextActivePath = activeFilePath ? canonicalPath(activeFilePath) : null;
+    if (previousActiveFilePathRef.current === nextActivePath) return;
+    previousActiveFilePathRef.current = nextActivePath;
+    const requestedPolicy = nextActivePath
+      && navigationPolicies.pending?.path === nextActivePath
+      ? navigationPolicies.pending
+      : null;
+    setNavigationPolicies({ active: requestedPolicy, pending: null });
+    if (selectedFilePathsRef.current.length === 0 && selectionAnchorPathRef.current === null) return;
+    updateSelection([], null);
+  }, [activeFilePath, navigationPolicies.pending, updateSelection]);
+
+  useEffect(() => {
+    const currentPaths = selectedFilePathsRef.current;
+    const nextPaths = currentPaths.filter((path) => treeItemPaths.has(canonicalPath(path)));
+    if (nextPaths.length === currentPaths.length) return;
+    const anchorPath = selectionAnchorPathRef.current;
+    updateSelection(
+      nextPaths,
+      anchorPath && nextPaths.some((path) => samePath(path, anchorPath))
+        ? anchorPath
+        : nextPaths[nextPaths.length - 1] ?? null,
+    );
+  }, [treeItemPaths, updateSelection]);
+
+  const focusTreeItem = useCallback((path: string) => {
+    setFocusedTreePath(path);
+    const focusMountedRow = () => {
+      const row = Array.from(
+        treeRootRef.current?.querySelectorAll<HTMLElement>('[role="treeitem"]') ?? [],
+      ).find((candidate) => samePath(candidate.dataset.notebookTreePath ?? '', path));
+      row?.focus();
+      return Boolean(row);
+    };
+    if (focusMountedRow()) return;
+
+    const index = renderRowIndexByPath.get(canonicalPath(path));
+    const scroller = treeScrollerRef.current;
+    if (index === undefined || !scroller) return;
+    const rowTop = treeContentOffset + index * TREE_ROW_SIZE;
+    const rowBottom = rowTop + TREE_ROW_HEIGHT;
+    if (rowTop < scroller.scrollTop) scroller.scrollTop = rowTop;
+    else if (rowBottom > scroller.scrollTop + scroller.clientHeight) {
+      scroller.scrollTop = Math.max(0, rowBottom - scroller.clientHeight);
+    }
+    window.requestAnimationFrame(() => { focusMountedRow(); });
+  }, [renderRowIndexByPath, treeContentOffset, treeRootRef, treeScrollerRef]);
+
+  const handleTreeItemKeyDown = useCallback((path: string, event: KeyboardEvent<HTMLDivElement>) => {
+    const currentIndex = visibleTreeItems.findIndex(({ item }) => samePath(item.fullPath, path));
+    if (currentIndex < 0) return;
+    const current = visibleTreeItems[currentIndex];
+    const nextVisibleItem = (step: number) => visibleTreeItems[currentIndex + step];
+
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      const target = nextVisibleItem(event.key === 'ArrowDown' ? 1 : -1);
+      if (!target) return;
+      event.preventDefault();
+      focusTreeItem(target.item.fullPath);
+      return;
+    }
+    if (event.key === 'Home' || event.key === 'End') {
+      const target = event.key === 'Home'
+        ? visibleTreeItems[0]
+        : visibleTreeItems[visibleTreeItems.length - 1];
+      if (!target) return;
+      event.preventDefault();
+      focusTreeItem(target.item.fullPath);
+      return;
+    }
+
+    if (event.key === 'ArrowRight' && current.item.type === 'folder') {
+      const expanded = tree.expanded.has(canonicalPath(current.item.fullPath));
+      if (!expanded) {
+        event.preventDefault();
+        tree.toggle(current.item.fullPath);
+        return;
+      }
+      const child = nextVisibleItem(1);
+      if (child && child.depth > current.depth) {
+        event.preventDefault();
+        focusTreeItem(child.item.fullPath);
+      }
+      return;
+    }
+
+    if (event.key === 'ArrowLeft') {
+      if (current.item.type === 'folder'
+        && tree.expanded.has(canonicalPath(current.item.fullPath))) {
+        event.preventDefault();
+        tree.toggle(current.item.fullPath);
+        return;
+      }
+      const parent = visibleTreeItems
+        .slice(0, currentIndex)
+        .reverse()
+        .find(({ item, depth }) => item.type === 'folder' && depth < current.depth);
+      if (parent) {
+        event.preventDefault();
+        focusTreeItem(parent.item.fullPath);
+      }
+    }
+  }, [focusTreeItem, tree, visibleTreeItems]);
+
+  useEffect(() => {
+    const hasFocusedItem = focusedTreePath
+      && visibleTreeItems.some(({ item }) => samePath(item.fullPath, focusedTreePath));
+    if (hasFocusedItem) return;
+    const fallback = activeFileShouldReveal && activeFilePath && visibleTreeItems.some(({ item }) => samePath(item.fullPath, activeFilePath))
+      ? activeFilePath
+      : visibleTreeItems[0]?.item.fullPath ?? null;
+    if (fallback !== focusedTreePath) setFocusedTreePath(fallback);
+  }, [activeFileShouldReveal, activeFilePath, focusedTreePath, visibleTreeItems]);
+
+  useEffect(() => {
+    const activePath = activeFilePath ? canonicalPath(activeFilePath) : null;
+    pendingActiveFileScrollPathRef.current = activeFileShouldReveal ? activePath : null;
+  }, [activeFileShouldReveal, activeFilePath]);
+
+  useEffect(() => {
+    if (!activeFilePath || !activeFileShouldReveal) return;
+    const activePath = canonicalPath(activeFilePath);
+    if (pendingActiveFileScrollPathRef.current !== activePath) return;
+    const index = renderRowIndexByPath.get(activePath);
+    const scroller = treeScrollerRef.current;
+    if (index === undefined || !scroller) return;
+    const rowTop = treeContentOffset + index * TREE_ROW_SIZE;
+    const rowBottom = rowTop + TREE_ROW_HEIGHT;
+    if (rowTop < scroller.scrollTop) scroller.scrollTop = rowTop;
+    else if (rowBottom > scroller.scrollTop + scroller.clientHeight) {
+      scroller.scrollTop = Math.max(0, rowBottom - scroller.clientHeight);
+    }
+    pendingActiveFileScrollPathRef.current = null;
+  }, [activeFileShouldReveal, activeFilePath, renderRowIndexByPath, treeContentOffset, treeScrollerRef]);
+
+  const selectNote = useCallback((filePath: string, event?: MouseEvent<HTMLDivElement>) => {
+    const currentPaths = selectedFilePathsRef.current;
+    const isToggle = Boolean(event?.ctrlKey || event?.metaKey);
+    const anchorPath = selectionAnchorPathRef.current;
+    const targetIndex = visibleDocumentPaths.findIndex((path) => samePath(path, filePath));
+    const anchorIndex = anchorPath
+      ? visibleDocumentPaths.findIndex((path) => samePath(path, anchorPath))
+      : -1;
+
+    if (event?.shiftKey && anchorIndex >= 0 && targetIndex >= 0) {
+      const start = Math.min(anchorIndex, targetIndex);
+      const end = Math.max(anchorIndex, targetIndex);
+      const range = visibleDocumentPaths.slice(start, end + 1);
+      updateSelection(isToggle ? [...currentPaths, ...range] : range, filePath);
+    } else if (isToggle) {
+      const nextPaths = currentPaths.some((path) => samePath(path, filePath))
+        ? currentPaths.filter((path) => !samePath(path, filePath))
+        : [...currentPaths, filePath];
+      updateSelection(nextPaths, filePath);
+    } else {
+      updateSelection([filePath], filePath);
+      navigateToNote(filePath, 'reveal');
+    }
+  }, [navigateToNote, updateSelection, visibleDocumentPaths]);
+
+  const treeFocusPath = focusedTreePath
+    ?? (activeFileShouldReveal && activeFilePath && visibleTreeItems.some(({ item }) => samePath(item.fullPath, activeFilePath))
+      ? activeFilePath
+      : visibleTreeItems[0]?.item.fullPath ?? null);
+
+  return {
+    focusedTreePath,
+    setFocusedTreePath,
+    selectedFilePaths,
+    selectedFilePathSet,
+    updateSelection,
+    getSelectionAnchorPath,
+    setNavigationPolicy,
+    navigateToNote,
+    activeFileShouldReveal,
+    treeFocusPath,
+    handleTreeItemKeyDown,
+    selectNote,
+  };
+}
diff --git a/app/flowix-web/features/memo/components/use-notebook-view-data.ts b/app/flowix-web/features/memo/components/use-notebook-view-data.ts
index 499b62325..0888c8f61 100644
--- a/app/flowix-web/features/memo/components/use-notebook-view-data.ts
+++ b/app/flowix-web/features/memo/components/use-notebook-view-data.ts
@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useState } from 'react';
-import { files, type FileBrowserDirectoriesChangedEvent, type MediaLibraryListItem, type TableDocumentListItem } from '@platform/tauri/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { files, type CollectionChangedEvent, type FileBrowserDirectoriesChangedEvent, type MediaLibraryListItem, type TableDocumentListItem } from '@platform/tauri/client';
 import { subscribe } from '@platform/tauri/event-bus';
 import { canonicalPath } from '@/lib/path';
 import { createLogger } from '@/lib/logger';
@@ -24,65 +24,84 @@ export function useNotebookViewData({
 }: NotebookViewDataOptions) {
   const [tableDocuments, setTableDocuments] = useState<TableDocumentListItem[]>([]);
   const [mediaLibraries, setMediaLibraries] = useState<MediaLibraryListItem[]>([]);
+  const tableRequestSequence = useRef(0);
+  const mediaRequestSequence = useRef(0);
+  const scopeRef = useRef({ notebookId, isActive });
+  scopeRef.current = { notebookId, isActive };
 
   const refreshTables = useCallback(async () => {
-    if (notebookId) setTableDocuments(await files.listTableDocuments(notebookId));
-  }, [notebookId]);
+    if (!notebookId || !isActive) return;
+    const requestSequence = ++tableRequestSequence.current;
+    const documents = await files.listTableDocuments(notebookId);
+    if (
+      requestSequence === tableRequestSequence.current
+      && scopeRef.current.notebookId === notebookId
+      && scopeRef.current.isActive
+    ) setTableDocuments(documents);
+  }, [isActive, notebookId]);
   const refreshMediaLibraries = useCallback(async () => {
-    if (notebookId) setMediaLibraries(await files.listMediaLibraries(notebookId));
-  }, [notebookId]);
+    if (!notebookId || !isActive) return;
+    const requestSequence = ++mediaRequestSequence.current;
+    const libraries = await files.listMediaLibraries(notebookId);
+    if (
+      requestSequence === mediaRequestSequence.current
+      && scopeRef.current.notebookId === notebookId
+      && scopeRef.current.isActive
+    ) setMediaLibraries(libraries);
+  }, [isActive, notebookId]);
 
   useEffect(() => {
     if (!isActive || !notebookId) {
+      tableRequestSequence.current += 1;
       setTableDocuments([]);
       return;
     }
-    let cancelled = false;
-    void files.listTableDocuments(notebookId).then((documents) => {
-      if (!cancelled) setTableDocuments(documents);
-    }).catch((error) => {
+    void refreshTables().catch((error) => {
       logger.warn('failed to load table documents', { error, notebookId });
-      if (!cancelled) setTableDocuments([]);
     });
-    return () => { cancelled = true; };
-  }, [isActive, notebookId, refreshTrigger]);
+    return () => { tableRequestSequence.current += 1; };
+  }, [isActive, notebookId, refreshTrigger, refreshTables]);
   useEffect(() => {
     if (!isActive || !notebookId) {
+      mediaRequestSequence.current += 1;
       setMediaLibraries([]);
       return;
     }
-    let cancelled = false;
-    void files.listMediaLibraries(notebookId).then((libraries) => {
-      if (!cancelled) setMediaLibraries(libraries);
-    }).catch((error) => {
+    void refreshMediaLibraries().catch((error) => {
       logger.warn('failed to load media libraries', { error, notebookId });
-      if (!cancelled) setMediaLibraries([]);
     });
-    return () => { cancelled = true; };
-  }, [isActive, notebookId, refreshTrigger]);
+    return () => { mediaRequestSequence.current += 1; };
+  }, [isActive, notebookId, refreshMediaLibraries, refreshTrigger]);
   useEffect(() => {
     const applied = new Map<string, number>();
-    return subscribe<{ notebookId: string; collectionId: string; relativePath: string; name: string; revision: number; indexSequence: number }>('collection-changed', (event) => {
-      if (event.notebookId !== notebookId || event.indexSequence < (applied.get(event.collectionId) ?? -1)) return;
+    return subscribe<CollectionChangedEvent>('collection-changed', (event) => {
+      if (!isActive || event.notebookId !== notebookId || event.indexSequence < (applied.get(event.collectionId) ?? -1)) return;
       applied.set(event.collectionId, event.indexSequence);
+      if (event.directoryMove) {
+        void refreshTables().catch((error) => logger.warn('failed to refresh table documents after collection directory move', { error, notebookId }));
+        void refreshMediaLibraries().catch((error) => logger.warn('failed to refresh media libraries after collection directory move', { error, notebookId }));
+        return;
+      }
+      tableRequestSequence.current += 1;
+      mediaRequestSequence.current += 1;
       setTableDocuments((items) => items.map((item) => item.collectionId === event.collectionId ? { ...item, relativePath: event.relativePath, name: event.name, fileRevision: event.revision } : item));
       setMediaLibraries((items) => items.map((item) => item.collectionId === event.collectionId ? { ...item, relativePath: event.relativePath, name: event.name } : item));
     });
-  }, [notebookId]);
-  useEffect(() => subscribe<{ notebookId: string }>('file-management-changed', (event) => {
-    if (event.notebookId !== notebookId || !notebookId) return;
+  }, [isActive, notebookId, refreshTables, refreshMediaLibraries]);
+  useEffect(() => subscribe<{ notebookId: string; operationId?: string }>('file-management-changed', (event) => {
+    if (!isActive || event.notebookId !== notebookId || !notebookId || event.operationId) return;
     void refreshTables().catch((error) => {
       logger.warn('failed to refresh table documents', { error, notebookId });
     });
     void refreshMediaLibraries().catch((error) => {
       logger.warn('failed to refresh media libraries', { error, notebookId });
     });
-  }), [notebookId, refreshTables, refreshMediaLibraries]);
+  }), [isActive, notebookId, refreshTables, refreshMediaLibraries]);
 
   useEffect(() => subscribe<FileBrowserDirectoriesChangedEvent>(
     'file-browser-directories-changed',
     (event) => {
-      if (!notebookId || canonicalPath(event.rootPath) !== canonicalPath(notebookPath)) return;
+      if (!isActive || !notebookId || canonicalPath(event.rootPath) !== canonicalPath(notebookPath)) return;
       if (ignoreCollectionPathEvents(event.paths)) return;
       void refreshTables().catch((error) => {
         logger.warn('failed to refresh table documents after file change', { error, notebookId });
@@ -91,7 +110,7 @@ export function useNotebookViewData({
         logger.warn('failed to refresh media libraries after file change', { error, notebookId });
       });
     },
-  ), [notebookId, notebookPath, ignoreCollectionPathEvents, refreshTables, refreshMediaLibraries]);
+  ), [isActive, notebookId, notebookPath, ignoreCollectionPathEvents, refreshTables, refreshMediaLibraries]);
 
   const updateTableIdentity = useCallback((relativePath: string, collectionId: string) => {
     setTableDocuments((current) => current.map((table) => table.relativePath === relativePath
diff --git a/app/flowix-web/features/memo/hooks/create-notebook-flow-state.ts b/app/flowix-web/features/memo/hooks/create-notebook-flow-state.ts
index efe78d3a1..66b15e797 100644
--- a/app/flowix-web/features/memo/hooks/create-notebook-flow-state.ts
+++ b/app/flowix-web/features/memo/hooks/create-notebook-flow-state.ts
@@ -10,7 +10,6 @@ export type NotebookCreationState =
 export interface NotebookImportStatusEffect {
   creationState: NotebookCreationState;
   reloadMemoList: boolean;
-  stopMemoListLoading: boolean;
   errorMessage: string | null;
 }
 
@@ -26,7 +25,6 @@ export function resolveNotebookImportStatusEffect(
     return {
       creationState: { status: 'importing', notebookId },
       reloadMemoList: false,
-      stopMemoListLoading: false,
       errorMessage: null,
     };
   }
@@ -35,7 +33,6 @@ export function resolveNotebookImportStatusEffect(
     return {
       creationState: { status: 'ready', notebookId },
       reloadMemoList: true,
-      stopMemoListLoading: false,
       errorMessage: null,
     };
   }
@@ -45,7 +42,6 @@ export function resolveNotebookImportStatusEffect(
     return {
       creationState: { status: 'failed', message },
       reloadMemoList: false,
-      stopMemoListLoading: true,
       errorMessage: message,
     };
   }
@@ -53,7 +49,6 @@ export function resolveNotebookImportStatusEffect(
   return {
     creationState: { status: 'ready', notebookId },
     reloadMemoList: false,
-    stopMemoListLoading: true,
     errorMessage: null,
   };
 }
diff --git a/app/flowix-web/features/memo/hooks/index.ts b/app/flowix-web/features/memo/hooks/index.ts
index 77d8d1829..d98414045 100644
--- a/app/flowix-web/features/memo/hooks/index.ts
+++ b/app/flowix-web/features/memo/hooks/index.ts
@@ -1,3 +1,2 @@
-export { useMemoEvents } from '@features/memo/hooks/use-memo-events';
 export { useMemoInsertAnimation } from '@features/memo/hooks/use-memo-insert-animation';
 export { useCreateNotebookFlow } from '@features/memo/hooks/use-create-notebook-flow';
diff --git a/app/flowix-web/features/memo/hooks/use-create-notebook-flow.test.ts b/app/flowix-web/features/memo/hooks/use-create-notebook-flow.test.ts
index 90df40a85..1c9dca173 100644
--- a/app/flowix-web/features/memo/hooks/use-create-notebook-flow.test.ts
+++ b/app/flowix-web/features/memo/hooks/use-create-notebook-flow.test.ts
@@ -33,7 +33,6 @@ describe('resolveNotebookImportStatusEffect', () => {
     ).toEqual({
       creationState: { status: 'importing', notebookId: 'nb_current' },
       reloadMemoList: false,
-      stopMemoListLoading: false,
       errorMessage: null,
     });
   });
@@ -48,12 +47,11 @@ describe('resolveNotebookImportStatusEffect', () => {
     ).toEqual({
       creationState: { status: 'ready', notebookId: 'nb_current' },
       reloadMemoList: true,
-      stopMemoListLoading: false,
       errorMessage: null,
     });
   });
 
-  it('stops loading and surfaces backend failures', () => {
+  it('surfaces backend failures', () => {
     expect(
       resolveNotebookImportStatusEffect(
         'nb_current',
@@ -63,7 +61,6 @@ describe('resolveNotebookImportStatusEffect', () => {
     ).toEqual({
       creationState: { status: 'failed', message: 'import failed' },
       reloadMemoList: false,
-      stopMemoListLoading: true,
       errorMessage: 'import failed',
     });
   });
@@ -78,12 +75,11 @@ describe('resolveNotebookImportStatusEffect', () => {
     ).toEqual({
       creationState: { status: 'failed', message: 'Failed to create' },
       reloadMemoList: false,
-      stopMemoListLoading: true,
       errorMessage: 'Failed to create',
     });
   });
 
-  it('treats skipped imports as ready and stops memo-list loading', () => {
+  it('treats skipped imports as ready', () => {
     expect(
       resolveNotebookImportStatusEffect(
         'nb_current',
@@ -93,7 +89,6 @@ describe('resolveNotebookImportStatusEffect', () => {
     ).toEqual({
       creationState: { status: 'ready', notebookId: 'nb_current' },
       reloadMemoList: false,
-      stopMemoListLoading: true,
       errorMessage: null,
     });
   });
diff --git a/app/flowix-web/features/memo/hooks/use-create-notebook-flow.ts b/app/flowix-web/features/memo/hooks/use-create-notebook-flow.ts
index c0edcc724..b82945935 100644
--- a/app/flowix-web/features/memo/hooks/use-create-notebook-flow.ts
+++ b/app/flowix-web/features/memo/hooks/use-create-notebook-flow.ts
@@ -9,9 +9,8 @@ import {
   resolveNotebookImportStatusEffect,
   type NotebookCreationState,
 } from '@features/memo/hooks/create-notebook-flow-state';
-import { useNoteStore, useTagStore, type Notebook } from '@features/memo/store';
-import { clearWorkspaceDocument } from '@features/workspace/use-cases/workspace-navigation';
-import { setCurrentWorkspaceNotebook } from '@features/memo/public/workspace-api';
+import { useNoteStore, type Notebook } from '@features/memo/store';
+import { selectNotebook } from '@features/workspace/public/main-window-api';
 import { createNotebookRegistration } from '@features/memo/services/notebook-creation-service';
 
 const NOTEBOOK_IMPORT_POLL_INTERVAL_MS = 500;
@@ -27,20 +26,20 @@ interface CreateNotebookInput {
 
 interface UseCreateNotebookFlowOptions {
   onMemoListReloadNeeded: () => void;
-  onMemoListQueryReset: () => void;
-  onMemoListLoadingChange: (loading: boolean) => void;
 }
 
 export function useCreateNotebookFlow({
   onMemoListReloadNeeded,
-  onMemoListQueryReset,
-  onMemoListLoadingChange,
 }: UseCreateNotebookFlowOptions) {
   const { t } = useI18n();
   const [creationState, setCreationState] = useState<NotebookCreationState>({
     status: 'idle',
   });
   const createInFlightRef = useRef(false);
+  const registeredNotebookRef = useRef<{
+    key: string;
+    registration: Awaited<ReturnType<typeof createNotebookRegistration>>;
+  } | null>(null);
   const activeImportNotebookIdRef = useRef<string | null>(null);
   const importMonitorGenerationRef = useRef(0);
 
@@ -56,12 +55,12 @@ export function useCreateNotebookFlow({
       if (!effect) return;
 
       setCreationState(effect.creationState);
-      if (effect.reloadMemoList) {
+      if (
+        effect.reloadMemoList
+        && useNoteStore.getState().selectedNotebook?.id === trackedNotebookId
+      ) {
         onMemoListReloadNeeded();
       }
-      if (effect.stopMemoListLoading) {
-        onMemoListLoadingChange(false);
-      }
       if (effect.errorMessage) {
         toast.error(effect.errorMessage);
       }
@@ -69,7 +68,7 @@ export function useCreateNotebookFlow({
         activeImportNotebookIdRef.current = null;
       }
     },
-    [onMemoListLoadingChange, onMemoListReloadNeeded, t],
+    [onMemoListReloadNeeded, t],
   );
 
   useEffect(() => {
@@ -108,47 +107,63 @@ export function useCreateNotebookFlow({
       if (!notebookName || (cloudNotebookId && !notebookPath)) return null;
       if (createInFlightRef.current) return null;
       createInFlightRef.current = true;
+      const registrationKey = JSON.stringify({ notebookName, notebookPath, icon, cloudNotebookId, templateId });
 
       setCreationState({ status: 'creating' });
 
       try {
         let registration: Awaited<ReturnType<typeof createNotebookRegistration>>;
-        if (cloudNotebookId) {
-          registration = {
-            notebook: await notebookRepository.createFromCloud(cloudNotebookId, notebookName, notebookPath ?? '', icon),
-            created: true,
-            needsImport: false,
-            hasTemplateSetup: false,
-            setupJob: null,
-          };
+        if (registeredNotebookRef.current?.key === registrationKey) {
+          registration = registeredNotebookRef.current.registration;
         } else {
-          try {
-            registration = await createNotebookRegistration({
-              name: notebookName,
-              path: notebookPath,
-              icon,
-              templateId,
-            });
-          } catch (error) {
-            if (!templateId || !String(error).includes('NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED')) {
-              throw error;
-            }
-            if (!await notebookRepository.confirmPresetOverwrite(t('notebook.template.overwriteConfirm'))) {
-              setCreationState({ status: 'idle' });
-              return null;
+          registeredNotebookRef.current = null;
+          if (cloudNotebookId) {
+            registration = {
+              notebook: await notebookRepository.createFromCloud(
+                cloudNotebookId,
+                notebookName,
+                notebookPath ?? '',
+                icon,
+                false,
+              ),
+              created: true,
+              needsImport: false,
+              hasTemplateSetup: false,
+              setupJob: null,
+            };
+          } else {
+            try {
+              registration = await createNotebookRegistration({
+                name: notebookName,
+                path: notebookPath,
+                icon,
+                templateId,
+                reuseExisting: true,
+              });
+            } catch (error) {
+              if (!templateId || !String(error).includes('NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED')) {
+                throw error;
+              }
+              if (!await notebookRepository.confirmPresetOverwrite(t('notebook.template.overwriteConfirm'))) {
+                setCreationState({ status: 'idle' });
+                return null;
+              }
+              registration = await createNotebookRegistration({
+                name: notebookName,
+                path: notebookPath,
+                icon,
+                templateId,
+                overwriteExisting: true,
+                reuseExisting: true,
+              });
             }
-            registration = await createNotebookRegistration({
-              name: notebookName,
-              path: notebookPath,
-              icon,
-              templateId,
-              overwriteExisting: true,
-            });
           }
+          registeredNotebookRef.current = { key: registrationKey, registration };
         }
         const created = registration.notebook as Notebook | null;
 
         if (!created) {
+          registeredNotebookRef.current = null;
           toast.error(t('memo.list.createFailed'));
           setCreationState({ status: 'failed', message: t('memo.list.createFailed') });
           return null;
@@ -160,14 +175,9 @@ export function useCreateNotebookFlow({
           ? existingNotebooks.map((notebook) => notebook.id === created.id ? created : notebook)
           : [...existingNotebooks, created];
 
-        await clearWorkspaceDocument();
-        await setCurrentWorkspaceNotebook(created);
         memoStore.setNotebooks(nextNotebooks);
-        memoStore.setSelectedNotebook(created);
-        useTagStore.getState().setSelectedTagId(null);
-        onMemoListQueryReset();
-        onMemoListLoadingChange(true);
-        onMemoListReloadNeeded();
+        await selectNotebook(created, { workColumnTarget: 'clear' });
+        registeredNotebookRef.current = null;
 
         if (cloudNotebookId) {
           setCreationState({ status: 'idle' });
@@ -181,7 +191,6 @@ export function useCreateNotebookFlow({
           } catch (error) {
             const message = notebookCreateErrorMessage(error, t);
             activeImportNotebookIdRef.current = null;
-            onMemoListLoadingChange(false);
             setCreationState({ status: 'failed', message });
             toast.error(message);
           }
@@ -204,16 +213,12 @@ export function useCreateNotebookFlow({
         const message = notebookCreateErrorMessage(error, t);
         toast.error(message);
         setCreationState({ status: 'failed', message });
-        onMemoListLoadingChange(false);
         return null;
       } finally {
         createInFlightRef.current = false;
       }
     },
     [
-      onMemoListLoadingChange,
-      onMemoListQueryReset,
-      onMemoListReloadNeeded,
       t,
     ],
   );
diff --git a/app/flowix-web/features/memo/hooks/use-dynamic-virtual-list.ts b/app/flowix-web/features/memo/hooks/use-dynamic-virtual-list.ts
index 1333ff84c..7c7543cec 100644
--- a/app/flowix-web/features/memo/hooks/use-dynamic-virtual-list.ts
+++ b/app/flowix-web/features/memo/hooks/use-dynamic-virtual-list.ts
@@ -3,6 +3,7 @@ import {
   useLayoutEffect,
   useMemo,
   useRef,
+  useState,
   type RefObject,
 } from 'react';
 import {
@@ -31,6 +32,10 @@ interface DynamicVirtualListOptions<T> {
   estimateSize: (item: T, index: number) => number;
   scrollerRef: RefObject<HTMLDivElement | null>;
   enabled: boolean;
+  /** Track fresh, stable geometry across hidden-to-visible transitions. */
+  trackViewportReadiness?: boolean;
+  /** Whether the viewport is currently visible and can be measured. */
+  viewportActive?: boolean;
   /** Reset scroll position and measurements when the query changes. */
   resetKey?: string;
   overscan?: number;
@@ -41,26 +46,109 @@ interface DynamicVirtualListOptions<T> {
 
 function observeUsableRect(
   lastUsableRect: { current: Rect | null },
+  trackViewportReadiness: { current: boolean },
+  viewportActive: { current: boolean },
+  viewportReady: { current: boolean },
+  setViewportReady: (ready: boolean) => void,
 ) {
   return (
     instance: Virtualizer<HTMLDivElement, HTMLDivElement>,
     onChange: (rect: Rect) => void,
-  ) => observeElementRect(instance, (observedRect) => {
-    const element = instance.scrollElement;
-    const rect = {
-      width: observedRect.width || element?.clientWidth || 0,
-      height: observedRect.height || element?.clientHeight || 0,
+  ) => {
+    let frame: number | null = null;
+    let previousFrameRect: Rect | null = null;
+    let stableFrames = 0;
+
+    const updateViewportReady = (ready: boolean) => {
+      if (viewportReady.current === ready) return;
+      viewportReady.current = ready;
+      setViewportReady(ready);
+    };
+
+    const cancelPendingMeasure = () => {
+      if (frame === null) return;
+      cancelAnimationFrame(frame);
+      frame = null;
     };
-    if (rect.width > 0 && rect.height > 0) {
+
+    const checkViewportStability = () => {
+      frame = null;
+      if (!trackViewportReadiness.current || !viewportActive.current) {
+        updateViewportReady(false);
+        previousFrameRect = null;
+        stableFrames = 0;
+        return;
+      }
+
+      const element = instance.scrollElement;
+      const bounds = element?.getBoundingClientRect();
+      const rect = {
+        width: bounds?.width ?? 0,
+        height: bounds?.height ?? 0,
+      };
+      if (rect.width <= 0 || rect.height <= 0) {
+        updateViewportReady(false);
+        previousFrameRect = null;
+        stableFrames = 0;
+        return;
+      }
+
       lastUsableRect.current = rect;
       onChange(rect);
-      return;
-    }
+      if (previousFrameRect
+        && Math.abs(previousFrameRect.width - rect.width) < 0.5
+        && Math.abs(previousFrameRect.height - rect.height) < 0.5) {
+        stableFrames += 1;
+      } else {
+        stableFrames = 0;
+      }
+      previousFrameRect = rect;
 
-    // Hidden workspace columns temporarily report zero geometry. Keep the
-    // last usable viewport so the list stays virtualized while hidden.
-    if (!lastUsableRect.current) onChange(rect);
-  });
+      // After a hidden-to-visible transition, wait for the opening width
+      // animation to settle before exposing dynamically measured rows.
+      if (stableFrames >= 1) {
+        updateViewportReady(true);
+        return;
+      }
+      frame = requestAnimationFrame(checkViewportStability);
+    };
+
+    const scheduleStabilityCheck = () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(checkViewportStability);
+    };
+
+    const stopObserving = observeElementRect(instance, (observedRect) => {
+      const element = instance.scrollElement;
+      const rect = {
+        width: observedRect.width || element?.clientWidth || 0,
+        height: observedRect.height || element?.clientHeight || 0,
+      };
+      if (rect.width > 0 && rect.height > 0) {
+        lastUsableRect.current = rect;
+        onChange(rect);
+        if (trackViewportReadiness.current && viewportActive.current && !viewportReady.current) {
+          scheduleStabilityCheck();
+        }
+        return;
+      }
+
+      if (trackViewportReadiness.current) {
+        updateViewportReady(false);
+      }
+      previousFrameRect = null;
+      stableFrames = 0;
+      cancelPendingMeasure();
+      // Hidden workspace columns temporarily report zero geometry. Keep the
+      // last usable viewport so the list stays virtualized while hidden.
+      if (!lastUsableRect.current) onChange(rect);
+    });
+
+    return () => {
+      cancelPendingMeasure();
+      stopObserving?.();
+    };
+  };
 }
 
 /** Shared TanStack Virtual adapter for memo cards and notebook tree rows. */
@@ -70,12 +158,20 @@ export function useDynamicVirtualList<T>({
   estimateSize,
   scrollerRef,
   enabled,
+  trackViewportReadiness = false,
+  viewportActive = true,
   resetKey,
   overscan = DEFAULT_OVERSCAN,
   keepAliveKeys = [],
   scrollMargin = 0,
 }: DynamicVirtualListOptions<T>) {
   const lastUsableRectRef = useRef<Rect | null>(null);
+  const trackViewportReadinessRef = useRef(trackViewportReadiness);
+  trackViewportReadinessRef.current = trackViewportReadiness;
+  const viewportActiveRef = useRef(viewportActive);
+  viewportActiveRef.current = viewportActive;
+  const viewportReadyRef = useRef(false);
+  const [viewportReadyState, setViewportReadyState] = useState(false);
   const enabledRef = useRef(enabled);
   enabledRef.current = enabled;
   const itemIndexesRef = useRef(new Map<string, number>());
@@ -105,8 +201,14 @@ export function useDynamicVirtualList<T>({
     Math.ceil(element.getBoundingClientRect().height),
   ), []);
   const observeRect = useMemo(
-    () => observeUsableRect(lastUsableRectRef),
-    [],
+    () => observeUsableRect(
+      lastUsableRectRef,
+      trackViewportReadinessRef,
+      viewportActiveRef,
+      viewportReadyRef,
+      setViewportReadyState,
+    ),
+    [setViewportReadyState],
   );
   const virtualizer = useVirtualizer<HTMLDivElement, HTMLDivElement>({
     count: items.length,
@@ -125,6 +227,13 @@ export function useDynamicVirtualList<T>({
   virtualizerRef.current = virtualizer;
 
   const lastResetKeyRef = useRef(resetKey);
+  useLayoutEffect(() => {
+    if (trackViewportReadiness && !viewportActive) {
+      viewportReadyRef.current = false;
+      setViewportReadyState(false);
+    }
+  }, [setViewportReadyState, trackViewportReadiness, viewportActive]);
+
   useLayoutEffect(() => {
     if (lastResetKeyRef.current === resetKey) return;
     lastResetKeyRef.current = resetKey;
@@ -140,10 +249,10 @@ export function useDynamicVirtualList<T>({
     previousWidthRef.current = viewportWidth;
     if (previousWidth === 0 || previousWidth === viewportWidth) return;
 
-    // Width changes invalidate cached heights. Reset and synchronously
-    // remeasure only the mounted virtual window; TanStack keeps the scroll
-    // anchor stable as changed rows above the viewport are measured.
-    virtualizer.measure();
+    // Width changes can alter the height of mounted rows. Remeasure those
+    // rows synchronously, while retaining cached sizes for offscreen rows;
+    // clearing the whole cache on every drag frame replaces them with
+    // estimates and creates visible gaps between cards.
     scrollerRef.current?.querySelectorAll<HTMLDivElement>('[data-index]').forEach((element) => {
       virtualizer.measureElement(element);
     });
@@ -200,6 +309,10 @@ export function useDynamicVirtualList<T>({
     totalSize: enabled ? totalSize : 0,
     virtualItems,
     isVirtualizationReady: enabled && lastUsableRectRef.current !== null,
+    isViewportReady: trackViewportReadiness
+      && enabled
+      && viewportActive
+      && viewportReadyState,
     getMeasureRef,
   };
 }
diff --git a/app/flowix-web/features/memo/hooks/use-memo-events.ts b/app/flowix-web/features/memo/hooks/use-memo-events.ts
deleted file mode 100644
index 2c507e036..000000000
--- a/app/flowix-web/features/memo/hooks/use-memo-events.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import '@/lib/memo-dispatcher';
-
-/**
- * Legacy hook-shaped entrypoint for installing memo-event handling.
- *
- * The preferences window no longer mounts this. The main window installs the
- * dispatcher from app/main-window-effects.tsx so preferences startup stays
- * lightweight. Keep this hook for older feature code that still imports it as
- * the memo-event setup API.
- */
-export function useMemoEvents(): void {
-  /* Module import above performs the setup. */
-}
diff --git a/app/flowix-web/features/memo/public/app-api.ts b/app/flowix-web/features/memo/public/app-api.ts
index 1259d2cf2..c1f958940 100644
--- a/app/flowix-web/features/memo/public/app-api.ts
+++ b/app/flowix-web/features/memo/public/app-api.ts
@@ -2,6 +2,8 @@ import type { MemoEvent, MemoDerivedRefresh } from '@/types/memo';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { useTagStore } from '@features/memo/store/tag-store';
 import { useTodoCountStore } from '@features/memo/store/todo-count-store';
+export { mountNotebookBackgroundUpdates } from '@features/memo/services/notebook-background-service';
+export { mountMemoListRefreshService } from '@features/memo/services/memo-list-refresh-service';
 export { resumePendingNoteLinkUpdates } from '@features/memo/services/note-link-rewriter';
 export {
   mountOpenTargetListener,
@@ -45,7 +47,9 @@ export function applyAppMemoDeleted(): void {
 }
 
 export function refreshAppTodoCount(notebookId: string): void {
-  void useTodoCountStore.getState().loadTodoCount(notebookId);
+  void useTodoCountStore.getState().loadTodoCount(notebookId).catch((error) => {
+    if (!String(error).includes('NOTE_INDEX_PENDING')) console.warn('Todo count unavailable:', error);
+  });
 }
 
 /** Refresh derived data after a filesystem path changes without a memo ID event. */
diff --git a/app/flowix-web/features/memo/public/drag-resource-api.ts b/app/flowix-web/features/memo/public/drag-resource-api.ts
new file mode 100644
index 000000000..4f7381c5e
--- /dev/null
+++ b/app/flowix-web/features/memo/public/drag-resource-api.ts
@@ -0,0 +1,34 @@
+export interface NotebookNoteDragResource {
+  kind: 'note';
+  notebookId: string;
+  relativePath: string;
+  title: string;
+}
+
+export function isMarkdownNoteDragResource(item: unknown): item is NotebookNoteDragResource {
+  if (!item || typeof item !== 'object') return false;
+  const resource = item as Partial<NotebookNoteDragResource>;
+  return resource.kind === 'note'
+    && typeof resource.notebookId === 'string'
+    && typeof resource.relativePath === 'string'
+    && /\.(?:md|markdown)$/i.test(resource.relativePath)
+    && typeof resource.title === 'string';
+}
+
+export interface NotebookFileDragResource {
+  kind: 'file';
+  absolutePath: string;
+  name: string;
+  resourceKind?: string | null;
+}
+
+export interface NotebookFolderDragResource {
+  kind: 'folder';
+  absolutePath: string;
+  name: string;
+}
+
+export type NotebookDragResource =
+  | NotebookNoteDragResource
+  | NotebookFileDragResource
+  | NotebookFolderDragResource;
diff --git a/app/flowix-web/features/memo/public/file-icon-api.ts b/app/flowix-web/features/memo/public/file-icon-api.ts
new file mode 100644
index 000000000..2c88b1743
--- /dev/null
+++ b/app/flowix-web/features/memo/public/file-icon-api.ts
@@ -0,0 +1,2 @@
+/** @deprecated Import ContentIcon from features/content for new callers. */
+export { NotebookTreeResourceIcon } from '@features/content/components/content-icon';
diff --git a/app/flowix-web/features/memo/public/note-navigation-api.ts b/app/flowix-web/features/memo/public/note-navigation-api.ts
new file mode 100644
index 000000000..11b626829
--- /dev/null
+++ b/app/flowix-web/features/memo/public/note-navigation-api.ts
@@ -0,0 +1,8 @@
+/** Public note-opening commands for features that navigate to Memo content. */
+export {
+  openNotebookById,
+  openNoteByDeepLink,
+  openNoteByNotebookPath,
+  openNoteByPhysicalPath,
+} from '@features/memo/use-cases/open-by-target';
+export type { OpenNoteDestinationOptions } from '@features/memo/use-cases/open-by-target';
diff --git a/app/flowix-web/features/memo/public/shell-api.ts b/app/flowix-web/features/memo/public/shell-api.ts
index 7b3075c34..21022e013 100644
--- a/app/flowix-web/features/memo/public/shell-api.ts
+++ b/app/flowix-web/features/memo/public/shell-api.ts
@@ -1,8 +1,6 @@
-import { useEffect } from 'react';
 import { useShallow } from 'zustand/react/shallow';
-import { useCustomFilterStore } from '@features/memo/store/custom-filter-store';
 import { useNoteStore } from '@features/memo/store/note-store';
-import { noteRepository } from '@features/memo/services/note-repository';
+import { noteRepository, notebookRepository } from '@features/memo/services/note-repository';
 
 export { MemoList } from '@features/memo/components/memo-list';
 export { NotebookTreeFileIcon } from '@features/memo/components/notebook-tree-file-icon';
@@ -22,6 +20,19 @@ export {
 } from '@features/memo/store';
 export { startNotebookImportWithMonitoring } from '@features/memo/services/notebook-creation-service';
 
+/** Persist a notebook template task; the application coordinator starts it when the workspace is ready. */
+export async function ensureShellNotebookTemplateSetup(
+  notebookId: string,
+  templateId: string,
+  overwriteExisting = false,
+) {
+  return notebookRepository.ensureTemplateSetup(notebookId, templateId, overwriteExisting);
+}
+
+export function confirmShellNotebookTemplateOverwrite(message: string) {
+  return notebookRepository.confirmPresetOverwrite(message);
+}
+
 export function useShellSelectedNotebook() {
   return useNoteStore((state) => state.selectedNotebook);
 }
@@ -52,24 +63,4 @@ export function showAgentConversationsView(): void {
   useNoteStore.getState().setMiddleColumnView('conversations');
 }
 
-export function useShellDocumentListTitle(input: {
-  notebookId: string | null;
-  folderPath: string;
-  customFilterId: string | null;
-} | null): string | null {
-  const loadNotebookFilters = useCustomFilterStore((state) => state.loadNotebookFilters);
-  const customFilter = useCustomFilterStore((state) => (
-    input && input.notebookId && input.customFilterId
-      ? state.filtersByNotebook[input.notebookId]?.find((filter) => filter.id === input.customFilterId) ?? null
-      : null
-  ));
-
-  useEffect(() => {
-    if (input?.notebookId) void loadNotebookFilters(input.notebookId);
-  }, [input?.notebookId, loadNotebookFilters]);
-
-  if (!input) return null;
-  return customFilter?.name
-    || input.folderPath.replace(/[\\/]+$/, '').split(/[\\/]/).pop()
-    || input.folderPath;
-}
+/** The one list data source that must be ready before the workspace is shown. */
diff --git a/app/flowix-web/features/memo/public/workspace-api.ts b/app/flowix-web/features/memo/public/workspace-api.ts
index dee8ec0a3..1bdcd415b 100644
--- a/app/flowix-web/features/memo/public/workspace-api.ts
+++ b/app/flowix-web/features/memo/public/workspace-api.ts
@@ -29,6 +29,7 @@ export function getWorkspaceMemoState(): WorkspaceMemoState {
 /** Reactive workspace selectors for app-level notebook navigation. */
 export function useWorkspaceMemoViewModel() {
   return useNoteStore(useShallow((state) => ({
+    notebooks: state.notebooks,
     selectedNotebook: state.selectedNotebook,
     startupPhase: state.startupPhase,
     setActiveFilter: state.setActiveFilter,
diff --git a/app/flowix-web/features/memo/services/memo-list-metadata-service.ts b/app/flowix-web/features/memo/services/memo-list-metadata-service.ts
index e590438c4..f3e413f85 100644
--- a/app/flowix-web/features/memo/services/memo-list-metadata-service.ts
+++ b/app/flowix-web/features/memo/services/memo-list-metadata-service.ts
@@ -38,7 +38,7 @@ export interface MemoTagTreeItem extends MemoTagLayoutItem {
   fullPath: string;
   depth: number;
   /** prefix count: 挂了"以 fullPath 起始的 tag"的去重 memo 数 (后端
-   *  get_tag_prefix_counts 用 HashSet<memo_id> 去重, 同一 memo 多个子
+   *  get_tag_prefix_counts 按笔记去重，同一篇笔记多个子
    *  tag 在父 prefix 下只算 1)。 */
   count: number;
 }
@@ -135,8 +135,8 @@ export function buildTagTreeOptions({
 }): MemoTagTreeItem[] {
   // Step 3+: 每个 tag 路径 (e.g. `中国/湖南/长沙`) 拆成多个 segment 节点
   // (中国 / 湖南 / 长沙) ── 选中任一节点即按其 fullPath 做 prefix 过滤。
-  // 兄弟顺序由 layout 里的全路径条目首次出现位置决定 (savedOrder 仍是
-  // 真实 tag 全路径的列表, 这里展开时按出现顺序插入 segment)。
+  // 兄弟顺序由 layout (或旧数据的 order 回退值) 中全路径首次出现位置决定;
+  // 展开时按该顺序插入 segment。
   //
   // count 来源: 后端 `get_tag_prefix_counts` 已经是按 distinct memo
   // 算好的, 直接读 fullPath 即可。比起累加 tagCounts 的好处:
@@ -242,12 +242,18 @@ export async function loadMemoLibraryMetadata({
   ]);
 
   const tagMap: Record<string, string> = {};
-  const allTagDefinitions = tagsResult.tags ?? [];
-  for (const tag of allTagDefinitions) {
-    tagMap[tag.id] = tag.name;
+  // The notes index is the source of truth for tags used by notes. The tag
+  // catalog only contains explicitly-created notebook tags, so tags parsed
+  // from Markdown would otherwise be omitted from the sidebar.
+  const catalogById = new Map(
+    (tagsResult.tags ?? []).map((tag) => [tag.id, tag.name]),
+  );
+  const allTagIds = [...new Set(usedTagIdsResult.usedTagIds ?? [])];
+  for (const id of allTagIds) {
+    tagMap[id] = catalogById.get(id) ?? id;
   }
 
-  const allTagIds = allTagDefinitions.map((tag) => tag.id);
+  const allTagDefinitions = allTagIds.map((id) => ({ id, name: tagMap[id] }));
   const allTagIdSet = new Set(allTagIds);
 
   const savedOrder = normalizeSavedStringArray(tagSystemMetadata.order);
diff --git a/app/flowix-web/features/memo/services/memo-list-refresh-service.ts b/app/flowix-web/features/memo/services/memo-list-refresh-service.ts
new file mode 100644
index 000000000..efc6bce85
--- /dev/null
+++ b/app/flowix-web/features/memo/services/memo-list-refresh-service.ts
@@ -0,0 +1,69 @@
+import { getCurrentWindow } from '@tauri-apps/api/window';
+import { subscribe } from '@platform/tauri/event-bus';
+import { subscribeNotebookChanges } from '@platform/tauri/notebook-change-events';
+import { useNoteStore } from '@features/memo/store/note-store';
+
+const REFRESH_BATCH_WINDOW_MS = 24;
+
+/** Owns application-level invalidation for the selected notebook's note views. */
+export function mountMemoListRefreshService(): () => void {
+  const pending = new Map<string, 'list' | 'notebook-views'>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+  let currentWindowLabel: string | null = null;
+  try {
+    currentWindowLabel = getCurrentWindow().label;
+  } catch {
+    // Browser preview has no Tauri window label.
+  }
+
+  const flush = () => {
+    timer = null;
+    if (disposed) return;
+    const pendingNotebookIds = new Map(pending);
+    pending.clear();
+    const state = useNoteStore.getState();
+    const selectedNotebookId = state.selectedNotebook?.id;
+    if (!selectedNotebookId) return;
+    const scope = pendingNotebookIds.get(selectedNotebookId);
+    if (scope === 'notebook-views') state.triggerRefresh();
+    else if (scope === 'list') state.triggerMemoListRefresh();
+  };
+
+  const schedule = (notebookId: string, scope: 'list' | 'notebook-views') => {
+    if (disposed) return;
+    const current = pending.get(notebookId);
+    pending.set(notebookId, current === 'notebook-views' || scope === 'notebook-views'
+      ? 'notebook-views'
+      : 'list');
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, REFRESH_BATCH_WINDOW_MS);
+  };
+
+  const stopNotebookChanges = subscribeNotebookChanges((change) => {
+    // The initiating window applies command-created notes from the command
+    // result. Other windows refresh their own selected list projection.
+    if (change.kind === 'resource-created'
+      && currentWindowLabel
+      && change.originWindowLabel === currentWindowLabel) return;
+    schedule(change.notebookId, 'list');
+  });
+  const stopFileManagement = subscribe<{ notebookId: string; operationId?: string }>(
+    'file-management-changed',
+    ({ notebookId, operationId }) => {
+      // Collection operations also publish a structured path change, which is
+      // enough to refresh the list. Unscoped maintenance events affect all
+      // notebook views, matching the previous broad refresh behavior.
+      if (operationId) return;
+      schedule(notebookId, 'notebook-views');
+    },
+  );
+
+  return () => {
+    disposed = true;
+    if (timer) clearTimeout(timer);
+    pending.clear();
+    stopNotebookChanges();
+    stopFileManagement();
+  };
+}
diff --git a/app/flowix-web/features/memo/services/note-link-rename.integration.test.ts b/app/flowix-web/features/memo/services/note-link-rename.integration.test.ts
index 8f86f1640..10fb35659 100644
--- a/app/flowix-web/features/memo/services/note-link-rename.integration.test.ts
+++ b/app/flowix-web/features/memo/services/note-link-rename.integration.test.ts
@@ -91,7 +91,7 @@ describe('rename B updates the Markdown reference in A', () => {
     const reopened = editor();
     reopened.commands.setContent(getDocumentBuffer(identity).content, { contentType: 'markdown' });
     expect(reopened.state.doc.firstChild?.firstChild?.attrs.relativePath).toBe('教学方案/简介2.md');
-    expect(reopened.view.dom.querySelector('.editor-note-reference__title')?.textContent).toBe('简介2');
+    expect(reopened.view.dom.querySelector('.note-reference__title')?.textContent).toBe('简介2');
 
     // A persisted chain must reach the final filename in one pass.
     expect(await rewriteNoteLinkMoves([
diff --git a/app/flowix-web/features/memo/services/note-link-rewriter.ts b/app/flowix-web/features/memo/services/note-link-rewriter.ts
index 3c33aba65..329ec8edb 100644
--- a/app/flowix-web/features/memo/services/note-link-rewriter.ts
+++ b/app/flowix-web/features/memo/services/note-link-rewriter.ts
@@ -80,8 +80,19 @@ let retryCount = 0;
 let rerunRequested = false;
 
 export function updateNoteLinksAfterMove(oldPath: string, newPath: string, folder = false): void {
-  if (canonicalPath(oldPath) === canonicalPath(newPath)) return;
-  try { writeJobs([...readJobs(), { oldPath, newPath, folder }]); } catch { return; }
+  oldPath = canonicalPath(oldPath);
+  newPath = canonicalPath(newPath);
+  if (oldPath === newPath) return;
+  try {
+    const jobs = readJobs();
+    const last = jobs[jobs.length - 1];
+    // Only coalesce adjacent identical confirmations. A->B, B->A, A->B
+    // are distinct operations and must retain their order.
+    if (!last || canonicalPath(last.oldPath) !== oldPath
+      || canonicalPath(last.newPath) !== newPath || last.folder !== folder) {
+      writeJobs([...jobs, { oldPath, newPath, folder }]);
+    }
+  } catch { return; }
   resumePendingNoteLinkUpdates();
 }
 
diff --git a/app/flowix-web/features/memo/services/note-repository.ts b/app/flowix-web/features/memo/services/note-repository.ts
index 4b5ff7e51..a6869c40a 100644
--- a/app/flowix-web/features/memo/services/note-repository.ts
+++ b/app/flowix-web/features/memo/services/note-repository.ts
@@ -66,8 +66,8 @@ export const notebookRepository = {
     notebooks.getTemplateSetupStatus(notebookId),
   startTemplateSetup: (notebookId: string, retry = false) =>
     notebooks.startTemplateSetup(notebookId, retry),
-  createFromCloud: (id: string, name: string, path: string, icon?: string | null) =>
-    notebooks.createFromCloud(id, name, path, icon),
+  createFromCloud: (id: string, name: string, path: string, icon?: string | null, activate = true) =>
+    notebooks.createFromCloud(id, name, path, icon, activate),
   startImport: (notebookId: string) => notebooks.startImport(notebookId),
   getImportStatus: (notebookId: string) => notebooks.getImportStatus(notebookId),
   update: (id: string, name?: string, icon?: string | null) =>
diff --git a/app/flowix-web/features/memo/services/notebook-background-service.test.ts b/app/flowix-web/features/memo/services/notebook-background-service.test.ts
new file mode 100644
index 000000000..da03e0675
--- /dev/null
+++ b/app/flowix-web/features/memo/services/notebook-background-service.test.ts
@@ -0,0 +1,42 @@
+import { beforeEach, expect, it, vi } from 'vitest';
+import type { NotebookBackgroundStatus } from '@platform/tauri/client/memos';
+const mocks = vi.hoisted(() => ({ snapshot: vi.fn(), subscribe: vi.fn(), invalidate: vi.fn(), setNotes: vi.fn(), stop: vi.fn() }));
+vi.mock('@platform/tauri/client/memos', () => ({ notebooks: { getBackgroundStatus: mocks.snapshot } }));
+vi.mock('@platform/tauri/event-bus', () => ({ subscribe: mocks.subscribe }));
+vi.mock('@platform/tauri/notebook-change-events', () => ({ publishNotebookQueryInvalidated: mocks.invalidate }));
+vi.mock('../store/note-store', () => ({ useNoteStore: { setState: mocks.setNotes } }));
+import { useNotebookBackgroundStore } from '../store/notebook-background-store';
+import { mountNotebookBackgroundUpdates } from './notebook-background-service';
+beforeEach(() => {
+  vi.resetAllMocks(); mocks.snapshot.mockResolvedValue([]); mocks.subscribe.mockReturnValue(mocks.stop);
+  useNotebookBackgroundStore.setState({ statuses: {} });
+});
+it('does not let an old snapshot overwrite a newer completion event', async () => {
+  let finish!: (value: NotebookBackgroundStatus[]) => void;
+  mocks.snapshot.mockReturnValueOnce(new Promise((resolve) => { finish = resolve; }));
+  const stop = mountNotebookBackgroundUpdates();
+  const deliver = mocks.subscribe.mock.calls[0][1] as (status: NotebookBackgroundStatus) => void;
+  deliver({ notebookId: 'a', revision: 2, state: 'ready', memoCount: 4, message: null });
+  finish([{ notebookId: 'a', revision: 1, state: 'running', message: null }]);
+  await vi.waitFor(() => expect(useNotebookBackgroundStore.getState().statuses.a.memoCount).toBe(4));
+  expect(mocks.invalidate).toHaveBeenCalledExactlyOnceWith('a');
+  stop();
+});
+it('reconciles a missed completion when the event listener reconnects', async () => {
+  const stop = mountNotebookBackgroundUpdates();
+  await Promise.resolve();
+  mocks.snapshot.mockResolvedValueOnce([{ notebookId: 'a', revision: 3, state: 'ready', memoCount: 0, message: null }]);
+  mocks.subscribe.mock.calls[0][2].onListenerReady();
+  await vi.waitFor(() => expect(mocks.invalidate).toHaveBeenCalledExactlyOnceWith('a'));
+  expect(useNotebookBackgroundStore.getState().statuses.a.memoCount).toBe(0);
+  stop();
+});
+it('ignores a snapshot that arrives after the workbench unmounts', async () => {
+  let finish!: (value: NotebookBackgroundStatus[]) => void;
+  mocks.snapshot.mockReturnValueOnce(new Promise((resolve) => { finish = resolve; }));
+  const stop = mountNotebookBackgroundUpdates(); stop();
+  finish([{ notebookId: 'a', revision: 1, state: 'ready', memoCount: 2, message: null }]);
+  await Promise.resolve();
+  expect(mocks.setNotes).not.toHaveBeenCalled(); expect(mocks.invalidate).not.toHaveBeenCalled();
+  expect(mocks.stop).toHaveBeenCalledOnce();
+});
diff --git a/app/flowix-web/features/memo/services/notebook-background-service.ts b/app/flowix-web/features/memo/services/notebook-background-service.ts
new file mode 100644
index 000000000..ef0c5dcce
--- /dev/null
+++ b/app/flowix-web/features/memo/services/notebook-background-service.ts
@@ -0,0 +1,42 @@
+import { publishNotebookQueryInvalidated } from '@platform/tauri/notebook-change-events';
+import { notebooks, type NotebookBackgroundStatus, type NotebookMediaMaintenanceStatus } from '@platform/tauri/client/memos';
+import { subscribe } from '@platform/tauri/event-bus';
+import { useNotebookBackgroundStore } from '../store/notebook-background-store';
+import { useNotebookMediaMaintenanceStore } from '../store/notebook-media-maintenance-store';
+import { useNoteStore } from '../store/note-store';
+
+/** Subscribe before taking the snapshot; revisions reject late snapshot/event results. */
+export function mountNotebookBackgroundUpdates(): () => void {
+  let disposed = false;
+  const apply = (status: NotebookBackgroundStatus) => {
+    if (disposed || !useNotebookBackgroundStore.getState().apply(status)) return;
+    useNoteStore.setState((state) => {
+      const patch = { ...(status.memoCount === undefined ? {} : { memoCount: status.memoCount }),
+        ...(status.missing === undefined ? {} : { missing: status.missing }) };
+      return {
+        notebooks: state.notebooks.map((notebook) => notebook.id === status.notebookId ? { ...notebook, ...patch } : notebook),
+        selectedNotebook: state.selectedNotebook?.id === status.notebookId
+          ? { ...state.selectedNotebook, ...patch } : state.selectedNotebook,
+      };
+    });
+    if (status.state === 'ready') publishNotebookQueryInvalidated(status.notebookId);
+  };
+  const reconcile = () => {
+    void notebooks.getBackgroundStatus().then((statuses) => statuses.forEach(apply))
+      .catch((error) => console.warn('Notebook maintenance status unavailable:', error));
+  };
+  const stop = subscribe<NotebookBackgroundStatus>('flowix:notebook-maintenance', apply, { onListenerReady: reconcile });
+  reconcile();
+  const applyMedia = (status: NotebookMediaMaintenanceStatus) => {
+    if (!disposed) useNotebookMediaMaintenanceStore.getState().apply(status);
+  };
+  const reconcileMedia = () => {
+    void notebooks.getMediaMaintenanceStatus().then((statuses) => statuses.forEach(applyMedia))
+      .catch((error) => console.warn('Media maintenance status unavailable:', error));
+  };
+  const stopMedia = subscribe<NotebookMediaMaintenanceStatus>(
+    'flowix:media-maintenance', applyMedia, { onListenerReady: reconcileMedia },
+  );
+  reconcileMedia();
+  return () => { disposed = true; stop(); stopMedia(); };
+}
diff --git a/app/flowix-web/features/memo/store/custom-filter-store.test.ts b/app/flowix-web/features/memo/store/custom-filter-store.test.ts
index 35919b3f1..02e0e165c 100644
--- a/app/flowix-web/features/memo/store/custom-filter-store.test.ts
+++ b/app/flowix-web/features/memo/store/custom-filter-store.test.ts
@@ -4,7 +4,7 @@ import { memoMatchesCustomFilter, type CustomFilter } from './custom-filter-stor
 import type { MemoItem } from '@/types/memo-item';
 
 const memo: MemoItem = {
-  id: 'memo-1',
+  relativePath: 'note.md',
   filename: 'note.md',
   preview: '',
   tags: [],
diff --git a/app/flowix-web/features/memo/store/note-store.test.ts b/app/flowix-web/features/memo/store/note-store.test.ts
index ff6825dc4..820520d0a 100644
--- a/app/flowix-web/features/memo/store/note-store.test.ts
+++ b/app/flowix-web/features/memo/store/note-store.test.ts
@@ -40,6 +40,7 @@ vi.mock('@features/memo/store/custom-filter-store', () => ({
 }));
 
 import { useNoteStore } from '@features/memo/store/note-store';
+import { useNotebookBackgroundStore } from './notebook-background-store';
 
 describe('note store list loading', () => {
   beforeEach(() => {
@@ -62,6 +63,14 @@ describe('note store list loading', () => {
     });
   });
 
+  it('keeps a missing index as pending without treating it as an empty result', async () => {
+    useNotebookBackgroundStore.setState({ statuses: {} });
+    mocks.listByPath.mockRejectedValue(new Error('NOTE_INDEX_PENDING'));
+    await expect(useNoteStore.getState().loadNotes({ notebookId: 'notebook-1', filter: 'all' })).resolves.toBe(false);
+    expect(useNoteStore.getState().memoListQueryKey).toBeNull();
+    expect(useNotebookBackgroundStore.getState().statuses['notebook-1'].state).toBe('queued');
+  });
+
   it('updates a filtered list without clearing the document selection', async () => {
     const filteredNote = {
       relativePath: 'todo.md', title: 'todo', preview: '', thumbnail: null,
diff --git a/app/flowix-web/features/memo/store/note-store.ts b/app/flowix-web/features/memo/store/note-store.ts
index 8b82ef11f..7730ae7a0 100644
--- a/app/flowix-web/features/memo/store/note-store.ts
+++ b/app/flowix-web/features/memo/store/note-store.ts
@@ -1,8 +1,10 @@
+import { useNotebookBackgroundStore } from '@features/memo/store/notebook-background-store';
 import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
 import { noteRepository, notebookRepository, type FilterType, type SortType } from '@features/memo/services';
 import { getNoteQueryKey } from '@features/memo/services/note-query-key';
 import { STORAGE_KEYS } from '@/lib/constants';
+import { createLogger } from '@/lib/logger';
 import { useTagStore } from '@features/memo/store/tag-store';
 import {
   memoMatchesCustomFilter,
@@ -49,6 +51,34 @@ interface MemoListPageQuery {
 }
 
 const MEMO_LIST_PAGE_SIZE = 50;
+const memoListRequestLogger = createLogger('memo-list-query');
+const recentMemoListRequestCounts = new Map<string, { startedAt: number; count: number }>();
+
+/** Development-only visibility into repeated backend reads for one query burst. */
+function recordMemoListRequest(queryKey: string, requestSeq: number, source: string): void {
+  if (!import.meta.env.DEV) return;
+
+  const now = Date.now();
+  const previous = recentMemoListRequestCounts.get(queryKey);
+  const isSameBurst = previous != null && now - previous.startedAt <= 500;
+  const count = isSameBurst && previous ? previous.count + 1 : 1;
+  recentMemoListRequestCounts.delete(queryKey);
+  recentMemoListRequestCounts.set(queryKey, {
+    startedAt: isSameBurst && previous ? previous.startedAt : now,
+    count,
+  });
+  if (recentMemoListRequestCounts.size > 64) {
+    const oldestQueryKey = recentMemoListRequestCounts.keys().next().value;
+    if (oldestQueryKey) recentMemoListRequestCounts.delete(oldestQueryKey);
+  }
+
+  memoListRequestLogger.debug('list query request started', {
+    queryKey,
+    requestSeq,
+    source,
+    requestsInBurst: count,
+  });
+}
 
 export interface SelectedNoteIdentity {
   notebookId: string;
@@ -94,6 +124,8 @@ export interface Notebook {
   /** User-defined display order; smaller values appear first. Mirrors the
    * Rust `NotebookConfig.sort` field. */
   sort?: number;
+  /** Device-local pinned state from the notebook registry. */
+  pinned?: boolean;
   missing?: boolean;
 }
 
@@ -146,8 +178,10 @@ export interface NoteLibraryStore {
   // 'color' 二级弹窗用的具体颜色值。'any'/'none'/具体颜色 (NOTE_COLORS)。
   // 当 activeFilter !== 'color' 时此值仍然保留, 切回颜色筛选时恢复。
   colorFilter: ColorFilterValue;
-  // Reload trigger
+  /** Broad refresh for the list and notebook-scoped dependent surfaces. */
   refreshTrigger: number;
+  /** Query-only invalidation. Does not reload notebook metadata consumers. */
+  memoListRefreshTrigger: number;
   /** Cursor state for the currently loaded memo query. Not persisted. */
   memoListQueryKey: string | null;
   memoListQuery: MemoListPageQuery | null;
@@ -179,14 +213,16 @@ export interface NoteLibraryStore {
   setActiveSort: (sort: SortType) => void;
   setColorFilter: (color: ColorFilterValue) => void;
   triggerRefresh: () => void;
+  /** Invalidate only the currently selected memo-list query. */
+  triggerMemoListRefresh: () => void;
   // Data loading
-  loadNotes: (params?: { notebookId?: string; filter?: ExtendedFilterType; sort?: SortType; tagId?: string }) => Promise<boolean>;
+  loadNotes: (params?: { notebookId?: string; filter?: ExtendedFilterType; sort?: SortType; tagId?: string; source?: string }) => Promise<boolean>;
   upsertCreatedNote: (created: CreatedNoteDocument) => void;
   updateMemoListItem: (memo: NoteListItem) => void;
   loadMoreMemos: () => Promise<boolean>;
   loadNotebooks: () => Promise<void>;
   createNote: (tag: string | undefined, notebookId: string) => Promise<CreatedNoteDocument>;
-  /** Invalidate the Note list after a legacy Memo IPC event. */
+  /** Invalidate the Note list after a memo-shaped IPC event. */
   handleMemoEvent: () => void;
 }
 
@@ -278,6 +314,7 @@ export const useNoteStore = create<NoteLibraryStore>()(
       activeSort: 'createdAt',
       colorFilter: 'any',
       refreshTrigger: 0,
+      memoListRefreshTrigger: 0,
       memoListQueryKey: null,
       memoListQuery: null,
       memoListNextCursor: null,
@@ -395,7 +432,13 @@ export const useNoteStore = create<NoteLibraryStore>()(
       }),
       setActiveSort: (sort) => set({ activeSort: sort }),
       setColorFilter: (color) => set({ colorFilter: color }),
-      triggerRefresh: () => set((state) => ({ refreshTrigger: state.refreshTrigger + 1 })),
+      triggerRefresh: () => set((state) => ({
+        refreshTrigger: state.refreshTrigger + 1,
+        memoListRefreshTrigger: state.memoListRefreshTrigger + 1,
+      })),
+      triggerMemoListRefresh: () => set((state) => ({
+        memoListRefreshTrigger: state.memoListRefreshTrigger + 1,
+      })),
 
       loadNotes: async (params) => {
         const requestSeq = ++loadMemosRequestSeq;
@@ -432,6 +475,7 @@ export const useNoteStore = create<NoteLibraryStore>()(
         };
         try {
           if (query.pluginId) {
+            recordMemoListRequest(queryKey, requestSeq, params?.source ?? 'unspecified');
             const indexed = await noteRepository.listAllByPath(query.notebookId);
             if (requestSeq !== loadMemosRequestSeq) return false;
             set({
@@ -446,6 +490,7 @@ export const useNoteStore = create<NoteLibraryStore>()(
             return true;
           }
 
+          recordMemoListRequest(queryKey, requestSeq, params?.source ?? 'unspecified');
           const response = await noteRepository.listByPath({
             notebookId: query.notebookId,
             filter: toBackendFilter(query.filter),
@@ -465,6 +510,16 @@ export const useNoteStore = create<NoteLibraryStore>()(
             memoListHasMore: response.hasMore ?? Boolean(response.nextCursor),
           });
           return true;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.includes('NOTE_INDEX_PENDING')) {
+            useNotebookBackgroundStore.getState().pending(notebookId);
+            return false;
+          }
+          // Backend status supplies a local failure/retry surface. Do not let
+          // fire-and-forget refresh consumers reject during offline maintenance.
+          if (message.includes('NOTE_INDEX_UNAVAILABLE')) return false;
+          throw error;
         } finally {
           if (requestSeq === loadMemosRequestSeq) {
             set({ memoListLoadingMore: false });
@@ -596,13 +651,21 @@ export const useNoteStore = create<NoteLibraryStore>()(
        */
       reorderNotebooks: async (nextOrderIds: string[]) => {
         if (nextOrderIds.length === 0) return;
+        const previousById = new Map(get().notebooks.map((notebook) => [notebook.id, notebook] as const));
         const order = nextOrderIds.map((id, index) => ({
           id,
           sort: (index + 1) * 10,
         }));
         try {
           const updated = await notebookRepository.reorder(order);
-          set({ notebooks: updated as Notebook[] });
+          set({ notebooks: updated.map((notebook) => {
+            const previous = previousById.get(notebook.id);
+            return {
+              ...notebook,
+              memoCount: notebook.memoCount ?? previous?.memoCount,
+              pinned: notebook.pinned ?? previous?.pinned,
+            };
+          }) as Notebook[] });
         } catch (error) {
           // 失败时重新拉一次 list 跟服务端对齐 (notebook 列表较短, 直接重拉比
           // 维护本地乐观回滚更稳)。
@@ -625,11 +688,8 @@ export const useNoteStore = create<NoteLibraryStore>()(
         }
         const createTag = tag ?? (createFilter === 'tagged' ? selectedTagId ?? undefined : undefined);
         const result = await noteRepository.create(createTag, notebookId);
-        invalidatePendingMemoLoads();
-        await get().loadNotes({ notebookId, filter: createFilter });
-        // 新建 memo 可能引入新 tag (body 派生) ── 主动 bump metadata refresh,
-        // 让侧栏标签树立即出现新节点 / 更新计数。后端 SelfWriteSuppressor 会
-        // 掐掉 desktop 自写的 memo-event, 不会自动触发 refresh, 必须手动调。
+        get().upsertCreatedNote(result);
+        // The shared path-created event refreshes notebook queries in every window.
         useTagStore.getState().triggerMetadataRefresh();
         return result;
       },
diff --git a/app/flowix-web/features/memo/store/notebook-background-store.test.ts b/app/flowix-web/features/memo/store/notebook-background-store.test.ts
new file mode 100644
index 000000000..b05b951e6
--- /dev/null
+++ b/app/flowix-web/features/memo/store/notebook-background-store.test.ts
@@ -0,0 +1,29 @@
+import { beforeEach, expect, it } from 'vitest';
+import { useNotebookBackgroundStore as store } from './notebook-background-store';
+beforeEach(() => store.setState({ statuses: {} }));
+it('rejects late snapshots and completed results from an older refresh', () => {
+  store.getState().apply({ notebookId: 'a', state: 'running', revision: 2, message: null });
+  expect(store.getState().apply({ notebookId: 'a', state: 'ready', revision: 1, memoCount: 0, message: null })).toBe(false);
+  expect(store.getState().statuses.a.state).toBe('running');
+});
+it('does not regress from completion to a late running event', () => {
+  store.getState().apply({ notebookId: 'a', state: 'ready', revision: 1, memoCount: 3, message: null });
+  expect(store.getState().apply({ notebookId: 'a', state: 'running', revision: 1, message: null })).toBe(false);
+  expect(store.getState().statuses.a.memoCount).toBe(3);
+});
+it('keeps failed and unknown counts distinct from a known empty notebook', () => {
+  store.getState().apply({ notebookId: 'a', state: 'failed', revision: 1, message: 'offline' });
+  store.getState().apply({ notebookId: 'b', state: 'ready', revision: 2, memoCount: 0, message: null });
+  expect(store.getState().statuses.a.memoCount).toBeUndefined();
+  expect(store.getState().statuses.b.memoCount).toBe(0);
+});
+
+it('keeps a failure when an earlier pending query arrives late, and admits explicit retry', () => {
+  store.getState().apply({ notebookId: 'a', state: 'failed', revision: 4, message: 'offline' });
+  store.getState().pending('a');
+  expect(store.getState().statuses.a).toMatchObject({ state: 'failed', revision: 4, message: 'offline' });
+  store.getState().pending('a', true);
+  expect(store.getState().statuses.a.state).toBe('queued');
+  store.getState().apply({ notebookId: 'a', state: 'running', revision: 5, message: null });
+  expect(store.getState().statuses.a.state).toBe('running');
+});
diff --git a/app/flowix-web/features/memo/store/notebook-background-store.ts b/app/flowix-web/features/memo/store/notebook-background-store.ts
new file mode 100644
index 000000000..01ebcae44
--- /dev/null
+++ b/app/flowix-web/features/memo/store/notebook-background-store.ts
@@ -0,0 +1,25 @@
+import { create } from 'zustand';
+import type { NotebookBackgroundStatus } from '@platform/tauri/client/memos';
+
+const rank = { queued: 0, running: 1, ready: 2, failed: 2 };
+export const useNotebookBackgroundStore = create<{
+  statuses: Record<string, NotebookBackgroundStatus>;
+  apply: (status: NotebookBackgroundStatus) => boolean;
+  pending: (notebookId: string, force?: boolean) => void;
+}>()((set, get) => ({
+  statuses: {},
+  apply: (status) => {
+    const previous = get().statuses[status.notebookId];
+    if (previous && (previous.revision > status.revision
+      || (previous.revision === status.revision && rank[previous.state] >= rank[status.state]))) return false;
+    set((state) => ({ statuses: { ...state.statuses, [status.notebookId]: status } }));
+    return true;
+  },
+  pending: (notebookId, force = false) => {
+    const previous = get().statuses[notebookId]?.state;
+    if (!force && (previous === 'running' || previous === 'ready' || previous === 'failed')) return;
+    set((state) => ({ statuses: { ...state.statuses, [notebookId]: {
+      notebookId, state: 'queued', revision: state.statuses[notebookId]?.revision ?? 0, message: null,
+    } } }));
+  },
+}));
diff --git a/app/flowix-web/features/memo/store/notebook-media-maintenance-store.ts b/app/flowix-web/features/memo/store/notebook-media-maintenance-store.ts
new file mode 100644
index 000000000..1e7efd9b0
--- /dev/null
+++ b/app/flowix-web/features/memo/store/notebook-media-maintenance-store.ts
@@ -0,0 +1,18 @@
+import { create } from 'zustand';
+import type { NotebookMediaMaintenanceStatus } from '@platform/tauri/client/memos';
+
+const rank = { queued: 0, running: 1, ready: 2, failed: 2 };
+
+export const useNotebookMediaMaintenanceStore = create<{
+  statuses: Record<string, NotebookMediaMaintenanceStatus>;
+  apply: (status: NotebookMediaMaintenanceStatus) => boolean;
+}>()((set, get) => ({
+  statuses: {},
+  apply: (status) => {
+    const previous = get().statuses[status.notebookId];
+    if (previous && (previous.revision > status.revision
+      || (previous.revision === status.revision && rank[previous.state] >= rank[status.state]))) return false;
+    set((state) => ({ statuses: { ...state.statuses, [status.notebookId]: status } }));
+    return true;
+  },
+}));
diff --git a/app/flowix-web/features/memo/store/notebook-setup-store.ts b/app/flowix-web/features/memo/store/notebook-setup-store.ts
new file mode 100644
index 000000000..79a1b3bb5
--- /dev/null
+++ b/app/flowix-web/features/memo/store/notebook-setup-store.ts
@@ -0,0 +1,58 @@
+import { useSyncExternalStore } from 'react';
+import type { NotebookSetupJob, NotebookSetupSnapshot } from '@platform/tauri/client';
+
+const jobsByNotebook = new Map<string, NotebookSetupJob>();
+const listeners = new Set<() => void>();
+let snapshot: readonly NotebookSetupJob[] = [];
+let latestSnapshotRevision = -1;
+
+function publish() {
+  snapshot = [...jobsByNotebook.values()];
+  for (const listener of [...listeners]) listener();
+}
+
+export function subscribeNotebookSetupJobs(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function getNotebookSetupJobs(): readonly NotebookSetupJob[] {
+  return snapshot;
+}
+
+export function getNotebookSetupJob(notebookId: string | null | undefined): NotebookSetupJob | null {
+  return notebookId ? jobsByNotebook.get(notebookId) ?? null : null;
+}
+
+export function upsertNotebookSetupJob(job: NotebookSetupJob) {
+  // The snapshot is authoritative for every revision it covers. An event that
+  // arrives later with an older revision must not resurrect a removed job.
+  if (job.revision <= latestSnapshotRevision) return;
+  const previous = jobsByNotebook.get(job.notebookId);
+  if (previous && job.revision < previous.revision) return;
+  if (previous && job.revision === previous.revision
+    && job.jobId === previous.jobId && job.runId === previous.runId) return;
+  jobsByNotebook.set(job.notebookId, job);
+  publish();
+}
+
+/** Replace persisted state while preserving events committed after the snapshot began. */
+export function replaceNotebookSetupSnapshot(value: NotebookSetupSnapshot) {
+  if (value.revision < latestSnapshotRevision) return;
+  const next = new Map(value.jobs.map((job) => [job.notebookId, job]));
+  for (const [notebookId, eventJob] of jobsByNotebook) {
+    if (eventJob.revision > value.revision) next.set(notebookId, eventJob);
+  }
+  jobsByNotebook.clear();
+  for (const [notebookId, job] of next) jobsByNotebook.set(notebookId, job);
+  latestSnapshotRevision = value.revision;
+  publish();
+}
+
+export function useNotebookSetupJob(notebookId: string | null | undefined): NotebookSetupJob | null {
+  return useSyncExternalStore(
+    subscribeNotebookSetupJobs,
+    () => getNotebookSetupJob(notebookId),
+    () => null,
+  );
+}
diff --git a/app/flowix-web/features/memo/store/tag-store.ts b/app/flowix-web/features/memo/store/tag-store.ts
index 11a1cd6d0..39be7ec87 100644
--- a/app/flowix-web/features/memo/store/tag-store.ts
+++ b/app/flowix-web/features/memo/store/tag-store.ts
@@ -25,7 +25,6 @@ interface TagStore {
   setSelectedTagId: (id: string | null) => void;
   triggerMetadataRefresh: () => void;
   loadTags: (notebookId?: string) => Promise<void>;
-  createTag: (notebookId: string, path: string) => Promise<{ path: string }>;
   /**
    * 移动 subtag: 把 `oldPath` 整棵子树重命名为 `newPath` (含 prefix
    * 替换), 批量改写所有受影响 memo 的 YAML `tags` + 同步 memo index。
@@ -67,14 +66,14 @@ export const useTagStore = create<TagStore>()(
       })),
 
       loadTags: async (notebookId?: string) => {
-        const response = await tags.getAll(notebookId);
-        set({ tags: response.tags });
-      },
-
-      createTag: async (notebookId: string, path: string) => {
-        const report = await tags.create(notebookId, path);
-        get().triggerMetadataRefresh();
-        return report;
+        try {
+          const response = await tags.getAll(notebookId);
+          set({ tags: response.tags });
+        } catch (error) {
+          // Existing tag projections remain usable; the maintenance completion
+          // event retries this read. Fire-and-forget consumers must not reject.
+          if (!String(error).includes('NOTE_INDEX_PENDING')) console.warn('Tag metadata unavailable:', error);
+        }
       },
 
       moveTag: async (
diff --git a/app/flowix-web/features/memo/use-cases/open-by-target.test.ts b/app/flowix-web/features/memo/use-cases/open-by-target.test.ts
index 2b5b2bc68..00c6f0a0f 100644
--- a/app/flowix-web/features/memo/use-cases/open-by-target.test.ts
+++ b/app/flowix-web/features/memo/use-cases/open-by-target.test.ts
@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-const { openExternalTarget, store } = vi.hoisted(() => ({
-  openExternalTarget: vi.fn(),
+const { openWorkspaceSurface, store } = vi.hoisted(() => ({
+  openWorkspaceSurface: vi.fn(),
   store: {
     notebooks: [{ id: 'work-id', name: 'My Vault', path: 'C:/Notes' }],
     loadNotebooks: vi.fn(),
@@ -9,9 +9,9 @@ const { openExternalTarget, store } = vi.hoisted(() => ({
 }));
 
 vi.mock('@features/memo/store/note-store', () => ({ useNoteStore: { getState: () => store } }));
-vi.mock('@features/workspace/use-cases/workspace-navigation', () => ({
+vi.mock('@features/workspace/public/note-navigation-api', () => ({
   clearWorkspaceDocument: vi.fn(),
-  openExternalTarget,
+  openWorkspaceSurface,
 }));
 vi.mock('@features/memo/public/workspace-api', () => ({ setCurrentWorkspaceNotebook: vi.fn() }));
 vi.mock('@platform/tauri/client', () => ({ notes: {
@@ -23,35 +23,40 @@ import { openNoteByDeepLink } from './open-by-target';
 import { peekAgentLocationRequest, cancelAgentLocationRequest } from '../../document/use-cases/agent-location-navigation';
 
 describe('note deep links', () => {
-  beforeEach(() => openExternalTarget.mockClear());
+  beforeEach(() => {
+    openWorkspaceSurface.mockClear();
+    openWorkspaceSurface.mockResolvedValue({
+      status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' },
+    });
+  });
 
   it('opens a note by notebook name and relative file', async () => {
     await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md');
-    expect(openExternalTarget).toHaveBeenCalledWith('C:/Notes/Projects/Plan.md', {
-      scopePath: 'C:/Notes',
-      destination: 'main-third',
+    expect(openWorkspaceSurface).toHaveBeenCalledWith({
+      host: 'main-third',
+      target: { kind: 'external', path: 'C:/Notes/Projects/Plan.md', scopePath: 'C:/Notes', transitionId: null },
     });
   });
 
   it('still opens existing book/file links', async () => {
     await openNoteByDeepLink('flowix://open?book=My+Vault&file=Projects%2FPlan.md');
-    expect(openExternalTarget).toHaveBeenCalledWith('C:/Notes/Projects/Plan.md', {
-      scopePath: 'C:/Notes',
-      destination: 'main-third',
+    expect(openWorkspaceSurface).toHaveBeenCalledWith({
+      host: 'main-third',
+      target: { kind: 'external', path: 'C:/Notes/Projects/Plan.md', scopePath: 'C:/Notes', transitionId: null },
     });
   });
 
   it('rejects legacy memo ID links', async () => {
     await expect(openNoteByDeepLink('flowix://memo/abc12345')).rejects.toThrow('Expired note link');
-    expect(openExternalTarget).not.toHaveBeenCalled();
+    expect(openWorkspaceSurface).not.toHaveBeenCalled();
   });
 
   it('publishes a heading anchor request for hash deep links', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'main-third', state: 'active' });
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' } });
     await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md#%E7%9B%AE%E6%A0%87%E4%B8%8E%E8%8C%83%E5%9B%B4');
-    expect(openExternalTarget).toHaveBeenCalledWith('C:/Notes/Projects/Plan.md', {
-      scopePath: 'C:/Notes',
-      destination: 'main-third',
+    expect(openWorkspaceSurface).toHaveBeenCalledWith({
+      host: 'main-third',
+      target: { kind: 'external', path: 'C:/Notes/Projects/Plan.md', scopePath: 'C:/Notes', transitionId: null },
     });
     const request = peekAgentLocationRequest('C:/Notes/Projects/Plan.md');
     expect(request?.anchor).toBe('目标与范围');
@@ -60,7 +65,7 @@ describe('note deep links', () => {
   });
 
   it('accepts the legacy heading parameter and normalizes it to a slug', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'main-third', state: 'active' });
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' } });
     await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md&heading=Step%201%3A%20Setup');
     const request = peekAgentLocationRequest('C:/Notes/Projects/Plan.md');
     expect(request?.anchor).toBe('step-1-setup');
@@ -68,13 +73,13 @@ describe('note deep links', () => {
   });
 
   it('does not treat an empty heading parameter as an anchor', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'main-third', state: 'active' });
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' } });
     await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md&heading=');
     expect(peekAgentLocationRequest('C:/Notes/Projects/Plan.md')).toBeNull();
   });
 
   it('routes anchor requests to the browser column tab when content lands there', async () => {
-    openExternalTarget.mockResolvedValueOnce({ host: 'browser-column', tabId: 'tab-7' });
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'opened', host: 'browser-column', location: { host: 'browser-column', tabId: 'tab-7' } });
     await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md#%E7%BB%93%E8%AE%BA');
     const request = peekAgentLocationRequest('C:/Notes/Projects/Plan.md');
     expect(request?.host).toBe('browser-column');
@@ -82,14 +87,36 @@ describe('note deep links', () => {
     cancelAgentLocationRequest('C:/Notes/Projects/Plan.md');
   });
 
-  it('falls back to main-third when the open result does not report a location', async () => {
-    // openExternalTarget 的 markdown 主区分支返回 null，但内容实际落在 main-third。
-    openExternalTarget.mockResolvedValueOnce(undefined);
+  it('does not publish an anchor when the open was cancelled', async () => {
+    openWorkspaceSurface.mockResolvedValueOnce({ status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' });
     await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md#%E7%9B%AE%E6%A0%87');
+    expect(peekAgentLocationRequest('C:/Notes/Projects/Plan.md')).toBeNull();
+  });
+
+  it('opens a note in the browser column without touching the work column', async () => {
+    openWorkspaceSurface.mockResolvedValueOnce({
+      status: 'opened', host: 'browser-column', location: { host: 'browser-column', tabId: 'file:C:/Notes/Projects/Plan.md' },
+    });
+    await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md', null, {
+      destination: 'browser-column',
+    });
+    expect(openWorkspaceSurface).toHaveBeenCalledWith({
+      host: 'browser-column',
+      target: { kind: 'external', path: 'C:/Notes/Projects/Plan.md', scopePath: 'C:/Notes', transitionId: null },
+      options: { notebookId: 'work-id' },
+    });
+  });
+
+  it('publishes the anchor against the browser column tab', async () => {
+    openWorkspaceSurface.mockResolvedValueOnce({
+      status: 'opened', host: 'browser-column', location: { host: 'browser-column', tabId: 'tab-note' },
+    });
+    await openNoteByDeepLink('flowix://open?b=My+Vault&f=Projects%2FPlan.md#%E7%BB%93%E8%AE%BA', null, {
+      destination: 'browser-column',
+    });
     const request = peekAgentLocationRequest('C:/Notes/Projects/Plan.md');
-    expect(request?.anchor).toBe('目标');
-    expect(request?.host).toBe('main-third');
-    expect(request?.viewId).toBe('main-third');
+    expect(request?.host).toBe('browser-column');
+    expect(request?.viewId).toBe('tab-note');
     cancelAgentLocationRequest('C:/Notes/Projects/Plan.md');
   });
 });
diff --git a/app/flowix-web/features/memo/use-cases/open-by-target.ts b/app/flowix-web/features/memo/use-cases/open-by-target.ts
index 508a66032..e38d3b3ff 100644
--- a/app/flowix-web/features/memo/use-cases/open-by-target.ts
+++ b/app/flowix-web/features/memo/use-cases/open-by-target.ts
@@ -4,12 +4,32 @@ import { notes as notesClient } from '@platform/tauri/client';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { setCurrentWorkspaceNotebook } from '@features/memo/public/workspace-api';
 import { canonicalDirectoryPath, canonicalPath, joinNotebookMemoPath } from '@/lib/path';
-import { clearWorkspaceDocument, openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
-import type { WorkspaceContentLocation } from '@features/workspace/use-cases/workspace-content-activation';
-import { publishHeadingAnchorRequest } from '@features/document/use-cases/heading-anchor-publish';
+import {
+  clearWorkspaceDocument,
+  openWorkspaceSurface,
+} from '@features/workspace/public/note-navigation-api';
+import type { WorkspaceContentLocation } from '@features/workspace/public/note-navigation-api';
+import type { WorkspaceSurfaceOpenResult } from '@features/workspace/public/open-surface-api';
+import { publishHeadingAnchorRequest } from '@features/document/public/heading-navigation-api';
 import { translate } from '@/lib/i18n';
 import { getCurrentAppLanguage } from '@features/preferences/public/runtime-api';
 
+/**
+ * Where a note should be surfaced. `browser-column` mirrors the Agent message
+ * link target: notes open in the right column instead of replacing whatever
+ * the work column already shows.
+ */
+export interface OpenNoteDestinationOptions {
+  destination?: 'main-third' | 'browser-column';
+}
+
+/** Cancelled opens have no view location to publish anchors against. */
+function locationFromOpenResult(
+  opened: WorkspaceSurfaceOpenResult,
+): WorkspaceContentLocation | null {
+  return opened.status === 'cancelled' ? null : opened.location;
+}
+
 /** Extract the heading anchor from a flowix://open deep link.
  *
  * Two accepted forms: the standard `#fragment` (GitHub slug), and the
@@ -68,7 +88,11 @@ function hiddenNotebookForPhysicalTarget(rawPath: string): { path: string; noteb
 }
 
 /** Resolve a path link through the notebook path index and open the document. */
-export async function openNoteByDeepLink(url: string, anchorOverride: string | null = null): Promise<void> {
+export async function openNoteByDeepLink(
+  url: string,
+  anchorOverride: string | null = null,
+  options?: OpenNoteDestinationOptions,
+): Promise<void> {
   const anchor = anchorOverride ?? anchorFromDeepLinkUrl(url);
   if (/^flowix:\/\/open\?/i.test(url.trim())) {
     const target = new URL(url.trim().replace(/&amp;/gi, '&'));
@@ -82,13 +106,13 @@ export async function openNoteByDeepLink(url: string, anchorOverride: string | n
       }
       const matches = notebooks.filter((item) => item.name === book);
       if (matches.length !== 1) throw new Error(`Notebook link is unavailable or ambiguous: ${book}`);
-      await openNoteByNotebookPath(matches[0].id, file, anchor);
+      await openNoteByNotebookPath(matches[0].id, file, anchor, options);
       return;
     }
     const notebookId = target.searchParams.get('notebookId');
     const relativePath = target.searchParams.get('relativePath');
     if (notebookId && relativePath) {
-      await openNoteByNotebookPath(notebookId, relativePath, anchor);
+      await openNoteByNotebookPath(notebookId, relativePath, anchor, options);
       return;
     }
     if (!target.searchParams.get('path')) throw new Error(`Invalid note link: ${url}`);
@@ -105,16 +129,17 @@ export async function openNoteByDeepLink(url: string, anchorOverride: string | n
   if (/\.(?:md|markdown)$/i.test(physicalPath)) {
     const location = await notesClient.resolveLocation(physicalPath).catch(() => null);
     if (location?.indexable && location.notebookId && location.relativePath) {
-      await openNoteByNotebookPath(location.notebookId, location.relativePath, anchor);
+      await openNoteByNotebookPath(location.notebookId, location.relativePath, anchor, options);
       return;
     }
   }
   const hiddenTarget = hiddenNotebookForPhysicalTarget(url);
   if (hiddenTarget) {
-    const opened = await openExternalTarget(hiddenTarget.path, {
-      destination: 'main-third',
-      scopePath: hiddenTarget.notebookPath,
-    });
+    const opened = await openNoteDestination(
+      hiddenTarget.path,
+      hiddenTarget.notebookPath,
+      options,
+    );
     if (anchor) publishHeadingAnchorRequest(hiddenTarget.path, opened, anchor);
     return;
   }
@@ -125,15 +150,37 @@ export async function openNoteByDeepLink(url: string, anchorOverride: string | n
   if (!/\.(?:md|markdown)$/i.test(physicalPath)) {
     throw new Error(`Unsupported note target: ${url}`);
   }
-  const opened = await openExternalTarget(physicalPath, { scopePath: null, destination: 'main-third' });
+  const opened = await openNoteDestination(physicalPath, null, options);
   if (anchor) publishHeadingAnchorRequest(physicalPath, opened, anchor);
 }
 
+/** Route a resolved physical note into the requested workspace host. */
+async function openNoteDestination(
+  path: string,
+  scopePath: string | null,
+  options?: OpenNoteDestinationOptions,
+): Promise<WorkspaceContentLocation | null> {
+  if (options?.destination === 'browser-column') {
+    const opened = await openWorkspaceSurface({
+      host: 'browser-column',
+      target: { kind: 'external', path, scopePath, transitionId: null },
+      options: { notebookId: useNoteStore.getState().notebooks.find((notebook) => canonicalPath(notebook.path) === canonicalPath(scopePath ?? ''))?.id },
+    });
+    return locationFromOpenResult(opened);
+  }
+  const opened = await openWorkspaceSurface({
+    host: 'main-third',
+    target: { kind: 'external', path, scopePath, transitionId: null },
+  });
+  return locationFromOpenResult(opened);
+}
+
 /** Open a note by notebook ID + relative path; returns where the content landed. */
 export async function openNoteByNotebookPath(
   notebookId: string,
   relativePath: string,
   anchor: string | null = null,
+  options?: OpenNoteDestinationOptions,
 ): Promise<WorkspaceContentLocation | null> {
   const normalized = relativePath.replace(/\\/g, '/');
   if (!normalized || normalized.startsWith('/') || normalized.split('/').some((part) => !part || part === '.' || part === '..')) {
@@ -152,14 +199,33 @@ export async function openNoteByNotebookPath(
       path: `${notebook.name}/${normalized}`,
     }));
   }
-  const opened = await openExternalTarget(path, { scopePath: notebook.path, destination: 'main-third' });
-  if (anchor) publishHeadingAnchorRequest(path, opened, anchor);
-  return opened;
+  if (options?.destination === 'browser-column') {
+    const opened = locationFromOpenResult(
+      await openWorkspaceSurface({
+        host: 'browser-column',
+        target: { kind: 'external', path, scopePath: notebook.path, transitionId: null },
+        options: { notebookId },
+      }),
+    );
+    if (anchor) publishHeadingAnchorRequest(path, opened, anchor);
+    return opened;
+  }
+  const opened = await openWorkspaceSurface({
+    host: 'main-third',
+    target: { kind: 'external', path, scopePath: notebook.path, transitionId: null },
+  });
+  const location = locationFromOpenResult(opened);
+  if (anchor) publishHeadingAnchorRequest(path, location, anchor);
+  return location;
 }
 
 /** Open a Markdown file by absolute path or file URL, with an optional heading anchor. */
-export async function openNoteByPhysicalPath(rawPath: string, anchor: string | null = null): Promise<void> {
-  await openNoteByDeepLink(rawPath, anchor);
+export async function openNoteByPhysicalPath(
+  rawPath: string,
+  anchor: string | null = null,
+  options?: OpenNoteDestinationOptions,
+): Promise<void> {
+  await openNoteByDeepLink(rawPath, anchor, options);
 }
 
 /** Open a notebook by its explicit notebook link. */
diff --git a/app/flowix-web/features/memo/use-cases/open-memo-session.ts b/app/flowix-web/features/memo/use-cases/open-memo-session.ts
index 411ad8844..13aaebac1 100644
--- a/app/flowix-web/features/memo/use-cases/open-memo-session.ts
+++ b/app/flowix-web/features/memo/use-cases/open-memo-session.ts
@@ -8,8 +8,7 @@ import { normalizePluginId } from '@features/plugin/plugin-note';
 
 const logger = createLogger('memo-session');
 
-/** Open a main-list note by its notebook-relative path, without resolving a
- * memo ID or creating an ID-backed workspace target. */
+/** Open a main-list note by its notebook-relative path. */
 export async function openPathNoteSession(
   note: NoteListItem,
   notebook: Notebook | null,
diff --git a/app/flowix-web/features/memo/use-cases/open-notebook-note.test.ts b/app/flowix-web/features/memo/use-cases/open-notebook-note.test.ts
index b2d325dc2..c4092caba 100644
--- a/app/flowix-web/features/memo/use-cases/open-notebook-note.test.ts
+++ b/app/flowix-web/features/memo/use-cases/open-notebook-note.test.ts
@@ -2,11 +2,11 @@ import { describe, expect, it, vi } from 'vitest';
 import type { Notebook } from '@features/memo/store/note-store';
 
 const mocks = vi.hoisted(() => ({
-  openExternalTarget: vi.fn(),
+  openWorkspaceSurface: vi.fn(),
 }));
 
-vi.mock('@features/workspace/use-cases/workspace-navigation', () => ({
-  openExternalTarget: mocks.openExternalTarget,
+vi.mock('@features/workspace/public/open-surface-api', () => ({
+  openWorkspaceSurface: mocks.openWorkspaceSurface,
 }));
 
 import { openNotebookNote } from './open-notebook-note';
@@ -15,16 +15,21 @@ const notebook = { id: 'book-1', path: '/notes' } as Notebook;
 
 describe('openNotebookNote', () => {
   it('opens ordinary Markdown by path without requiring a memo ID', async () => {
-    mocks.openExternalTarget.mockClear();
+    mocks.openWorkspaceSurface.mockClear();
     await openNotebookNote('/notes/a.md', notebook);
-    expect(mocks.openExternalTarget).toHaveBeenCalledWith('/notes/a.md', {
-      scopePath: '/notes', destination: undefined, history: undefined, initialFocus: undefined,
+    expect(mocks.openWorkspaceSurface).toHaveBeenCalledWith({
+      host: 'main-third',
+      target: { kind: 'external', path: '/notes/a.md', scopePath: '/notes', transitionId: null },
+      options: { history: undefined, initialFocus: undefined },
     });
   });
 
   it('opens plugin Markdown through the path document surface', async () => {
-    mocks.openExternalTarget.mockClear();
+    mocks.openWorkspaceSurface.mockClear();
     await openNotebookNote('/notes/map.md', notebook);
-    expect(mocks.openExternalTarget).toHaveBeenCalledWith('/notes/map.md', expect.objectContaining({ scopePath: '/notes' }));
+    expect(mocks.openWorkspaceSurface).toHaveBeenCalledWith(expect.objectContaining({
+      host: 'main-third',
+      target: { kind: 'external', path: '/notes/map.md', scopePath: '/notes', transitionId: null },
+    }));
   });
 });
diff --git a/app/flowix-web/features/memo/use-cases/open-notebook-note.ts b/app/flowix-web/features/memo/use-cases/open-notebook-note.ts
index a251e6f1c..7981f851d 100644
--- a/app/flowix-web/features/memo/use-cases/open-notebook-note.ts
+++ b/app/flowix-web/features/memo/use-cases/open-notebook-note.ts
@@ -1,5 +1,5 @@
-import { openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
-import type { WorkspaceContentLocation } from '@features/workspace/use-cases/workspace-content-activation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import type { WorkspaceContentLocation } from '@features/workspace/public/note-navigation-api';
 import type { Notebook } from '@features/memo/store/note-store';
 
 /** Open notebook Markdown through the shared path document surface. */
@@ -8,10 +8,10 @@ export async function openNotebookNote(
   notebook: Notebook,
   options: { destination?: 'main-third'; history?: 'push' | 'skip'; initialFocus?: 'title' | 'body'; mayBePlugin?: boolean } = {},
 ): Promise<WorkspaceContentLocation | null> {
-  return openExternalTarget(path, {
-    scopePath: notebook.path,
-    destination: options.destination,
-    history: options.history,
-    initialFocus: options.initialFocus,
+  const result = await openWorkspaceSurface({
+    host: options.destination ?? 'main-third',
+    target: { kind: 'external', path, scopePath: notebook.path, transitionId: null },
+    options: { history: options.history, initialFocus: options.initialFocus },
   });
+  return result.status === 'cancelled' ? null : result.location;
 }
diff --git a/app/flowix-web/features/multidimensional-table/model.test.ts b/app/flowix-web/features/multidimensional-table/model.test.ts
index 5d03b8ef9..68ece7a98 100644
--- a/app/flowix-web/features/multidimensional-table/model.test.ts
+++ b/app/flowix-web/features/multidimensional-table/model.test.ts
@@ -141,3 +141,23 @@ it('reuses existing date fields and rejects conflicting types across calendar cr
   const second = addCalendarDateView(first.document);
   expect(second.document.dataset.schema.preset_fields.filter((id) => id === NOTE_CALENDAR_DATE_FIELD_ID)).toHaveLength(1);
 });
+
+
+describe('dataset editor preservation', () => {
+  it.each(['all', 'any'])('rejects duplicate legacy file conditions in %s', (match) => {
+    const document = createTableDocument();
+    document.dataset.filter = { all: [], any: [], [match]: [
+      { field: 'file_name', op: 'contains', value: 'release' },
+      { field: 'file_name', op: 'contains', value: 'draft' },
+    ] };
+    expect(canEditTableAutoCollectFilter(parseTableDocument(serializeTableDocument(document)))).toBe(false);
+  });
+  it('accepts condition reordering but still rejects lost duplicate rules', () => {
+    const document = createTableDocument();
+    const file = { field: 'file_name', op: 'contains', value: 'draft' };
+    document.dataset.filter = { path: null, match: 'any', conditions: [file, { field: 'status', op: 'eq', value: 'ready' }] };
+    expect(canEditTableAutoCollectFilter(document)).toBe(true);
+    document.dataset.filter.conditions = [file, file];
+    expect(canEditTableAutoCollectFilter(document)).toBe(false);
+  });
+});
diff --git a/app/flowix-web/features/multidimensional-table/model.ts b/app/flowix-web/features/multidimensional-table/model.ts
index 5146314ca..d1099dd3b 100644
--- a/app/flowix-web/features/multidimensional-table/model.ts
+++ b/app/flowix-web/features/multidimensional-table/model.ts
@@ -1,5 +1,5 @@
 import type { PropertyFieldConfig } from '@/lib/constants';
-import { createCollectionMetadata, createCollectionId, createUuidV7, parseCollectionDocumentV2, serializeCollectionDocumentV2, validateCollectionMetadata, reviseCollection, hasOnlyKeys, type CollectionMetadata, type CollectionSource } from '@features/collection/model';
+import { createCollectionMetadata, createCollectionId, createUuidV7, parseCollectionDocumentV2, serializeCollectionDocumentV2, validateCollectionMetadata, reviseCollection, hasOnlyKeys, isRecord, type CollectionMetadata, type CollectionSource } from '@features/collection/model';
 export { createUuidV7 } from '@features/collection/model';
 import { isTablePropertyKind, type TablePropertyKind } from '@/lib/property-types';
 import { TAG_COLUMN_MIN_WIDTH, TAG_COLUMN_MAX_WIDTH } from './tag-column-width';
@@ -15,7 +15,11 @@ export interface TableFieldOption {
 }
 
 export interface TableAutoCollectCondition {
+  match?: 'all' | 'any';
+  /** `null` means no path rule; an empty string explicitly selects all folders. */
+  path?: string | null;
   property_conditions?: TableAutoCollectPropertyCondition[];
+  /** Kept for reading older runtime drafts. */
   property_match?: 'union' | 'intersection';
   file_condition?: TableAutoCollectFileCondition;
 }
@@ -94,63 +98,123 @@ export interface MultidimensionalTableDocument {
 export function tableAutoCollectConfig(document: MultidimensionalTableDocument): TableAutoCollectConfig | null {
   const filter = document.dataset.filter;
   if (!filter) return null;
+  if (Array.isArray(filter.conditions) && (filter.match === 'all' || filter.match === 'any')) {
+    const path = typeof filter.path === 'string' ? filter.path : null;
+    return { condition: tableConditionFromRules(filter.conditions as Record<string, unknown>[], filter.match, path) };
+  }
   const all = Array.isArray(filter.all) ? filter.all as Record<string, unknown>[] : [];
   const any = Array.isArray(filter.any) ? filter.any as Record<string, unknown>[] : [];
-  const grouped = any.find((rule) => Array.isArray(rule.all));
-  const isFileRule = (rule: Record<string, unknown>) => ['kind', 'file_name', 'path'].includes(String(rule.field));
-  const allPropertyRules = all.filter((rule) => !isFileRule(rule));
-  const propertyRules = grouped ? grouped.all as Record<string, unknown>[] : allPropertyRules.length ? allPropertyRules : any.filter((rule) => !isFileRule(rule));
-  const property_conditions = propertyRules.flatMap((rule) => {
-    if (typeof rule.field !== 'string' || ['kind', 'file_name', 'path'].includes(rule.field) || typeof rule.value !== 'string') return [];
+  const allPaths = all.filter((rule) => rule.field === 'path');
+  const anyPaths = any.filter((rule) => rule.field === 'path');
+  const path = pathFromLegacyRules([...allPaths, ...anyPaths]) ?? null;
+  const nonPathAll = all.filter((rule) => rule.field !== 'path');
+  const nonPathAny = any.filter((rule) => rule.field !== 'path');
+  const grouped = nonPathAny.find((rule) => Array.isArray(rule.all));
+  const chosenRules = nonPathAny.length
+    ? grouped && nonPathAny.length === 1 ? grouped.all as Record<string, unknown>[] : nonPathAny
+    : nonPathAll;
+  const match = nonPathAny.length && !grouped ? 'any' : 'all';
+  return { condition: tableConditionFromRules(chosenRules, match, path) };
+}
+
+function tableConditionFromRules(rules: Record<string, unknown>[], match: 'all' | 'any', path: string | null): TableAutoCollectCondition {
+  const property_conditions = rules.flatMap((rule) => {
+    if (typeof rule.field !== 'string' || ['kind', 'file_name', 'path'].includes(rule.field) || typeof rule.value !== 'string'
+      || !['eq', 'equals', 'contains'].includes(String(rule.op))) return [];
     return [{ field_id: rule.field, operator: rule.op === 'contains' ? 'contains' as const : 'equals' as const, value: rule.value }];
   });
-  const fileRules = [...all, ...any].filter((rule) => typeof rule.field === 'string');
   const file_condition: TableAutoCollectFileCondition = {};
-  for (const rule of fileRules) {
+  for (const rule of rules) {
     if (rule.field === 'file_name' && rule.op === 'contains' && typeof rule.value === 'string') file_condition.file_name_contains = rule.value;
-    if (rule.field === 'path' && rule.op === 'contains' && typeof rule.value === 'string') {
-      if (rule.value === '') file_condition.path_scope = 'all';
-      else file_condition.path_contains = rule.value;
-    }
     if (rule.field === 'kind' && rule.op === 'eq' && rule.value === 'note') file_condition.file_type = 'markdown';
   }
-  const condition: TableAutoCollectCondition = {
-    ...(property_conditions.length ? { property_conditions, property_match: grouped || allPropertyRules.length ? 'intersection' as const : 'union' as const } : {}),
+  return {
+    match,
+    path,
+    ...(property_conditions.length ? { property_conditions } : {}),
     ...(Object.keys(file_condition).length ? { file_condition } : {}),
   };
-  return { condition };
 }
 
 export function withTableAutoCollect(document: MultidimensionalTableDocument, config: TableAutoCollectConfig | null): MultidimensionalTableDocument {
   if (!config) return { ...document, dataset: { ...document.dataset, filter: null } };
   const properties = (config.condition.property_conditions ?? []).map((item) => ({ field: item.field_id.trim(), op: item.operator === 'contains' ? 'contains' : 'eq', value: item.value.trim() }));
   const file = config.condition.file_condition;
-  const pathRules: Record<string, unknown>[] = file?.path_scope === 'all'
-    ? [{ field: 'path', op: 'contains', value: '' }]
-    : file?.path_contains ? [{ field: 'path', op: 'contains', value: file.path_contains }] : [];
   const files: Record<string, unknown>[] = [];
-  if (file?.file_name_contains) files.push({ field: 'file_name', op: 'contains', value: file.file_name_contains });
+  if (file?.file_name_contains?.trim()) files.push({ field: 'file_name', op: 'contains', value: file.file_name_contains.trim() });
   if (file?.file_type === 'markdown') files.push({ field: 'kind', op: 'eq', value: 'note' });
-  const filter = properties.length && config.condition.property_match === 'intersection'
-    ? files.length ? { all: pathRules, any: [{ all: properties, any: [] }, ...files] } : { all: [...pathRules, ...properties], any: [] }
-    : { all: pathRules, any: [...properties, ...files] };
+  const legacyPath = file?.path_scope === 'all' ? '' : file?.path_contains?.trim() || null;
+  const rawPath = config.condition.path !== undefined ? config.condition.path : legacyPath;
+  const path = typeof rawPath === 'string' ? rawPath.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') : null;
+  const filter = {
+    path,
+    match: config.condition.match ?? (config.condition.property_match === 'intersection' ? 'all' : 'any'),
+    conditions: [...properties, ...files],
+  };
   return { ...document, dataset: { ...document.dataset, filter } };
 }
 
 function stableValue(value: unknown): unknown {
   if (Array.isArray(value)) return value.map(stableValue);
   if (!value || typeof value !== 'object') return value;
-  const entries = Object.entries(value).map(([key, entry]) => [key, key === 'op' && entry === 'equals' ? 'eq' : stableValue(entry)] as const);
+  const entries = Object.entries(value).map(([key, entry]) => {
+    const normalized = key === 'op' && entry === 'equals' ? 'eq' : stableValue(entry);
+    // Sorting preserves duplicate counts while ignoring conjunction/disjunction order.
+    if (key === 'conditions' && Array.isArray(normalized)) {
+      normalized.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    }
+    return [key, normalized] as const;
+  });
   return Object.fromEntries(entries.sort(([left], [right]) => left.localeCompare(right)));
 }
 
 /** The compact auto-collect form can edit only filters it can round-trip exactly. */
 export function canEditTableAutoCollectFilter(document: MultidimensionalTableDocument): boolean {
   if (document.dataset.filter == null) return true;
+  const filter = document.dataset.filter;
+  if (!Array.isArray(filter.conditions)) return isEditableLegacyTableFilter(filter);
+  const supported = (filter.conditions as Record<string, unknown>[]).every((rule) => (
+    typeof rule.field === 'string' && typeof rule.value === 'string'
+      && ((rule.field === 'kind' && rule.op === 'eq' && rule.value === 'note')
+        || (rule.field === 'file_name' && rule.op === 'contains')
+        || (!['path', 'kind', 'file_name'].includes(rule.field) && ['eq', 'equals', 'contains'].includes(String(rule.op))))
+  ));
+  if (!supported) return false;
   const roundTripped = withTableAutoCollect(document, tableAutoCollectConfig(document)).dataset.filter;
   return JSON.stringify(stableValue(document.dataset.filter)) === JSON.stringify(stableValue(roundTripped));
 }
 
+function isEditableLegacyTableFilter(filter: Record<string, unknown>): boolean {
+  const all = Array.isArray(filter.all) ? filter.all as Record<string, unknown>[] : [];
+  const any = Array.isArray(filter.any) ? filter.any as Record<string, unknown>[] : [];
+  const allPaths = all.filter((rule) => rule.field === 'path');
+  const anyPaths = any.filter((rule) => rule.field === 'path');
+  // Path rules inside an OR branch cannot generally become the mandatory path.
+  if (anyPaths.length || pathFromLegacyRules(allPaths) === undefined) return false;
+  const allRules = all.filter((rule) => rule.field !== 'path');
+  const anyRules = any.filter((rule) => rule.field !== 'path');
+  const isLeaf = (rule: Record<string, unknown>) => typeof rule.field === 'string' && typeof rule.value === 'string'
+    && ((rule.field === 'kind' && rule.op === 'eq' && rule.value === 'note')
+      || (rule.field === 'file_name' && rule.op === 'contains')
+      || (!['path', 'kind', 'file_name'].includes(rule.field) && ['eq', 'equals', 'contains'].includes(String(rule.op))));
+  if (allRules.length && anyRules.length) return false;
+  const hasDuplicateFileRules = (rules: Record<string, unknown>[]) => ['file_name', 'kind'].some((field) => rules.filter((rule) => rule.field === field).length > 1);
+  if (anyRules.length === 1 && Array.isArray(anyRules[0].all)) {
+    const group = anyRules[0];
+    return Array.isArray(group.any) && group.any.length === 0 && !hasDuplicateFileRules(group.all as Record<string, unknown>[]) && (group.all as unknown[]).every((rule) => isRecord(rule) && isLeaf(rule as Record<string, unknown>));
+  }
+  return !hasDuplicateFileRules([...allRules, ...anyRules]) && [...allRules, ...anyRules].every(isLeaf);
+}
+
+function pathFromLegacyRules(rules: Record<string, unknown>[]): string | null | undefined {
+  if (rules.some((rule) => rule.op !== 'contains' || typeof rule.value !== 'string')) return rules.length ? undefined : null;
+  const paths = [...new Set(rules.map((rule) => String(rule.value).trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '')))];
+  const nonEmpty = paths.filter(Boolean);
+  if (nonEmpty.some((path) => nonEmpty.some((other) => path !== other
+    && !path.startsWith(`${other}/`) && !other.startsWith(`${path}/`)))) return undefined;
+  return nonEmpty.sort((left, right) => right.length - left.length)[0] ?? (rules.length ? '' : null);
+}
+
 export const createTableId = createCollectionId;
 
 function completeFieldOrder(
diff --git a/app/flowix-web/features/multidimensional-table/note-create-picker.tsx b/app/flowix-web/features/multidimensional-table/note-create-picker.tsx
index 735c16807..616251b5b 100644
--- a/app/flowix-web/features/multidimensional-table/note-create-picker.tsx
+++ b/app/flowix-web/features/multidimensional-table/note-create-picker.tsx
@@ -2,19 +2,25 @@ import { useLayoutEffect, useRef, useState, type ReactNode } from 'react';
 import { FileText, Plus } from 'lucide-react';
 import type { NoteEntry } from '@platform/tauri/client';
 import { useComposingValue } from '@shared/hooks/use-composing-value';
+import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
 
 /** Shared interaction for creating a note or linking an existing one. Persistence stays in the caller. */
-export function NoteCreatePicker({ value, onChange, notes, allowSelect = true, disabled = false, error, onCreate, onSelect, onCancel, actions }: {
+export function NoteCreatePicker({ value, onChange, notes = [], allowSelect = true, disabled = false, error, onCreate, onSelect, onCancel, actions, actionsLayout = 'row', scrollTitleWithActions = false, footer, showCreateButton = true, mode = 'create' }: {
   value: string;
   onChange: (value: string) => void;
-  notes: readonly NoteEntry[];
+  notes?: readonly NoteEntry[];
   allowSelect?: boolean;
   disabled?: boolean;
   error?: string | null;
   onCreate: () => unknown;
-  onSelect: (note: NoteEntry) => unknown;
+  onSelect?: (note: NoteEntry) => unknown;
   onCancel: () => void;
   actions?: ReactNode;
+  actionsLayout?: 'row' | 'column';
+  scrollTitleWithActions?: boolean;
+  footer?: ReactNode;
+  showCreateButton?: boolean;
+  mode?: 'create' | 'edit';
 }) {
   const input = useComposingValue(value, onChange);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -22,7 +28,7 @@ export function NoteCreatePicker({ value, onChange, notes, allowSelect = true, d
   const [activePath, setActivePath] = useState<string | null>(null);
   const [keyboardNavigation, setKeyboardNavigation] = useState(false);
   const query = input.value.trim().toLocaleLowerCase();
-  const filtered = allowSelect ? notes.filter((note) => !query || `${note.title ?? ''} ${note.relativePath}`.toLocaleLowerCase().includes(query)) : [];
+  const filtered = allowSelect && onSelect ? notes.filter((note) => !query || `${note.title ?? ''} ${note.relativePath}`.toLocaleLowerCase().includes(query)) : [];
   const activeIndex = filtered.findIndex((note) => note.relativePath === activePath);
 
   useLayoutEffect(() => { textareaRef.current?.focus({ preventScroll: true }); }, []);
@@ -30,9 +36,9 @@ export function NoteCreatePicker({ value, onChange, notes, allowSelect = true, d
     const textarea = textareaRef.current;
     if (!textarea) return;
     textarea.style.height = '0px';
-    textarea.style.height = `${Math.min(textarea.scrollHeight + 2, window.innerHeight * 0.5)}px`;
+    const contentHeight = textarea.scrollHeight + 2;
+    textarea.style.height = `${scrollTitleWithActions ? contentHeight : Math.min(contentHeight, window.innerHeight * 0.5)}px`;
   }, [input.value]);
-
   const navigate = (direction: number, fromIndex = activeIndex, moveFocus = false) => {
     if (!filtered.length) return;
     const next = fromIndex < 0 ? (direction > 0 ? 0 : filtered.length - 1) : (fromIndex + direction + filtered.length) % filtered.length;
@@ -41,63 +47,72 @@ export function NoteCreatePicker({ value, onChange, notes, allowSelect = true, d
     if (moveFocus) optionRefs.current[next]?.focus({ preventScroll: true });
     optionRefs.current[next]?.scrollIntoView({ block: 'nearest' });
   };
-
-  return <div className={`multidimensional-table__primary-editor${keyboardNavigation ? ' is-keyboard-navigation' : ''}`}>
-    <div className="flex shrink-0 items-start gap-1">
-      <textarea ref={textareaRef} rows={1} aria-label="新建或选择笔记" placeholder="输入名称搜索 或 新建"
-        value={input.value} disabled={disabled}
-        className="multidimensional-table__primary-title-input min-w-0 flex-1 !py-2"
-        onChange={(event) => { input.onChange(event); setActivePath(null); }}
-        onCompositionStart={input.onCompositionStart} onCompositionEnd={input.onCompositionEnd}
-        onKeyDown={(event) => {
-          if (input.isComposingKeyboardEvent(event.nativeEvent)) { event.stopPropagation(); return; }
-          if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); onCancel(); }
-          else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-            if (!filtered.length) return;
-            event.preventDefault(); event.stopPropagation(); navigate(event.key === 'ArrowDown' ? 1 : -1);
-          } else if (event.key === 'Enter' && !event.shiftKey) {
-            event.preventDefault(); event.stopPropagation();
-            if (activeIndex >= 0) void onSelect(filtered[activeIndex]);
-            else if (value.trim()) void onCreate();
-          }
-        }} />
-      {value.trim() && <button type="button" aria-label="创建并关联笔记" title="创建并关联笔记" disabled={disabled}
-        onMouseDown={(event) => event.preventDefault()} onClick={() => void onCreate()}
-        className="flex h-8 w-10 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--hover-bg)] disabled:opacity-50">
-        <Plus size={14} aria-hidden="true" />
-      </button>}
-    </div>
-    {actions && <div className="multidimensional-table__primary-editor-actions">{actions}</div>}
-    {allowSelect && <div className="min-w-0">
-      <div className="-mx-1 max-h-48 overflow-y-auto">
-        <div className="slash-menu-header !px-1.5" role="presentation"><span>搜索并添加笔记</span></div>
-        <div role="listbox" aria-label="已创建笔记">
-          {filtered.map((note, index) => <button key={note.relativePath} ref={(element) => { optionRefs.current[index] = element; }}
-            type="button" role="option" aria-selected={index === activeIndex} disabled={disabled}
-            onFocus={() => { setActivePath(note.relativePath); setKeyboardNavigation(true); }}
-            onKeyDown={(event) => {
-              if (input.isComposingKeyboardEvent(event.nativeEvent)) return;
-              if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-                event.preventDefault(); event.stopPropagation();
-                navigate(event.key === 'ArrowDown' ? 1 : -1, index, true);
-              } else if (event.key === 'Enter') {
-                event.preventDefault(); event.stopPropagation(); void onSelect(note);
-              } else if (event.key === 'Escape') {
-                event.preventDefault(); event.stopPropagation(); onCancel();
-              }
-            }}
-            onMouseMove={(event) => {
-              if (!event.movementX && !event.movementY) return;
-              setActivePath(note.relativePath); setKeyboardNavigation(false);
-            }}
-            onMouseDown={(event) => event.preventDefault()} onClick={() => void onSelect(note)}
-            className={`multidimensional-table__note-picker-option${index === activeIndex ? ' is-selected' : ''}`} title={note.relativePath}>
-            <FileText className="h-3.5 w-3.5 shrink-0 text-[var(--muted-foreground)]" aria-hidden="true" />
-            <span className="truncate">{note.title || note.relativePath}</span>
-          </button>)}
-        </div>
-        {(error || filtered.length === 0) && <p className="px-1 py-2 text-center text-sm text-[var(--muted-foreground)]">{error || (notes.length ? '没有匹配的笔记' : '没有可选择的笔记')}</p>}
+  const titleInput = <div className={`flex shrink-0 items-start gap-1${scrollTitleWithActions ? ' pb-2' : ''}`}>
+    <textarea ref={textareaRef} rows={1} aria-label={mode === 'edit' || !allowSelect ? '笔记名称' : '新建或选择笔记'} placeholder={mode === 'edit' || !allowSelect ? '笔记名称' : '输入名称搜索 或 新建'}
+      value={input.value} disabled={disabled}
+      className="multidimensional-table__primary-title-input min-w-0 flex-1 !py-2"
+      onChange={(event) => { input.onChange(event); setActivePath(null); }}
+      onCompositionStart={input.onCompositionStart} onCompositionEnd={input.onCompositionEnd}
+      onKeyDown={(event) => {
+        if (input.isComposingKeyboardEvent(event.nativeEvent)) { event.stopPropagation(); return; }
+        if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); onCancel(); }
+        else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+          if (!filtered.length) return;
+          event.preventDefault(); event.stopPropagation(); navigate(event.key === 'ArrowDown' ? 1 : -1);
+        } else if (event.key === 'Enter' && !event.shiftKey) {
+          event.preventDefault(); event.stopPropagation();
+          if (activeIndex >= 0 && onSelect) void onSelect(filtered[activeIndex]);
+          else if (value.trim()) void onCreate();
+        }
+      }} />
+    {showCreateButton && value.trim() && <button type="button" aria-label="创建并关联笔记" title="创建并关联笔记" disabled={disabled}
+      onMouseDown={(event) => event.preventDefault()} onClick={() => void onCreate()}
+      className="flex h-8 w-10 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--hover-bg)] disabled:opacity-50">
+      <Plus size={14} aria-hidden="true" />
+    </button>}
+  </div>;
+  const actionContent = actions && <div className={actionsLayout === 'column' ? 'flex w-full min-w-0 flex-col items-stretch' : 'multidimensional-table__primary-editor-actions'}>{actions}</div>;
+  const noteList = mode === 'create' && allowSelect && onSelect && <div className="min-w-0">
+    <div className="-mx-1 max-h-48 overflow-y-auto">
+      <div className="slash-menu-header !px-1.5" role="presentation"><span>搜索并添加笔记</span></div>
+      <div role="listbox" aria-label="已创建笔记">
+        {filtered.map((note, index) => <button key={note.relativePath} ref={(element) => { optionRefs.current[index] = element; }}
+          type="button" role="option" aria-selected={index === activeIndex} disabled={disabled}
+          onFocus={() => { setActivePath(note.relativePath); setKeyboardNavigation(true); }}
+          onKeyDown={(event) => {
+            if (input.isComposingKeyboardEvent(event.nativeEvent)) return;
+            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+              event.preventDefault(); event.stopPropagation();
+              navigate(event.key === 'ArrowDown' ? 1 : -1, index, true);
+            } else if (event.key === 'Enter') {
+              event.preventDefault(); event.stopPropagation(); void onSelect?.(note);
+            } else if (event.key === 'Escape') {
+              event.preventDefault(); event.stopPropagation(); onCancel();
+            }
+          }}
+          onMouseMove={(event) => {
+            if (!event.movementX && !event.movementY) return;
+            setActivePath(note.relativePath); setKeyboardNavigation(false);
+          }}
+          onMouseDown={(event) => event.preventDefault()} onClick={() => void onSelect?.(note)}
+          className={`multidimensional-table__note-picker-option${index === activeIndex ? ' is-selected' : ''}`} title={note.relativePath}>
+          <FileText className="h-3.5 w-3.5 shrink-0 text-[var(--muted-foreground)]" aria-hidden="true" />
+          <span className="truncate">{note.title || note.relativePath}</span>
+        </button>)}
       </div>
-    </div>}
+      {(error || filtered.length === 0) && <p className="px-1 py-2 text-center text-sm text-[var(--muted-foreground)]">{error || (notes.length ? '没有匹配的笔记' : '没有可选择的笔记')}</p>}
+    </div>
+  </div>;
+
+  return <div className={`multidimensional-table__primary-editor${keyboardNavigation ? ' is-keyboard-navigation' : ''}${scrollTitleWithActions ? ' flex min-h-0 flex-1 flex-col' : ''}`}>
+    {scrollTitleWithActions
+      ? <>
+        <OverlayScrollbar
+          className="-mr-1 -mt-2 h-auto min-h-[120px] max-h-[min(360px,calc(100vh-112px))] flex-none"
+          scrollerClassName="h-auto min-h-[120px] max-h-[min(360px,calc(100vh-112px))] overflow-y-auto overscroll-contain pl-1 pr-1 pt-2"
+        >{titleInput}{actionContent}{noteList}</OverlayScrollbar>
+        {footer}
+      </>
+      : <>{titleInput}{actionContent}{noteList}{footer}</>}
   </div>;
 }
diff --git a/app/flowix-web/features/multidimensional-table/record-filter.ts b/app/flowix-web/features/multidimensional-table/record-filter.ts
index 1e9bd3ba3..7cc7ad65c 100644
--- a/app/flowix-web/features/multidimensional-table/record-filter.ts
+++ b/app/flowix-web/features/multidimensional-table/record-filter.ts
@@ -1,6 +1,6 @@
 import type { NoteEntry } from '@platform/tauri/client';
 import type { TableField } from './model';
-import { matchesCollectionFilter, type CollectionRuleFilter } from '@features/collection/rule-filter';
+import { matchesDatasetFilter, type DatasetFilter } from '@features/collection/rule-filter';
 
 export function noteMatchesCollectionFilter(
   note: NoteEntry,
@@ -11,9 +11,9 @@ export function noteMatchesCollectionFilter(
   const path = note.relativePath.replace(/\\/g, '/');
   const filename = path.split('/').pop() ?? path;
   const directory = path.split('/').slice(0, -1).join('/');
-  const ruleMatches = (rule: Record<string, unknown>): boolean => {
-    const field = String(rule.field ?? '');
-    const operator = String(rule.op ?? '');
+  const ruleMatches = (rule: { field: string; op: string; value: unknown }): boolean => {
+    const field = rule.field;
+    const operator = rule.op;
     const expected = rule.value;
     let actual: unknown;
     if (field === 'kind') actual = 'note';
@@ -49,5 +49,5 @@ export function noteMatchesCollectionFilter(
       return normalized.includes(expected);
     });
   };
-  return matchesCollectionFilter(filter as unknown as CollectionRuleFilter, ruleMatches);
+  return matchesDatasetFilter(filter as unknown as DatasetFilter, ruleMatches);
 }
diff --git a/app/flowix-web/features/multidimensional-table/table-commands.ts b/app/flowix-web/features/multidimensional-table/table-commands.ts
index a62be751c..ce467d384 100644
--- a/app/flowix-web/features/multidimensional-table/table-commands.ts
+++ b/app/flowix-web/features/multidimensional-table/table-commands.ts
@@ -4,7 +4,7 @@ import { reviseCollection } from '@features/collection/model';
 import { canonicalizePropertyKey } from '@features/properties/property-key';
 import type { PropertyPreset } from '@features/document/properties/presets';
 import { type MultidimensionalTableDocument, type TableField, type TableFieldType, type TableView } from './model';
-import { collectionFilterUsesField, type CollectionRuleFilter } from '@features/collection/rule-filter';
+import { collectionFilterUsesField, type DatasetFilter } from '@features/collection/rule-filter';
 import { BUILTIN_TABLE_FIELDS, builtinPresetTableField } from './builtin-fields';
 
 export function viewsRequiringField(document: MultidimensionalTableDocument, fieldId: string): TableView[] {
@@ -51,7 +51,7 @@ export function removeField(document: MultidimensionalTableDocument, fieldId: st
   const field = document.dataset.schema.fields.find((item) => item.id === fieldId);
   if (!field || field.type === 'primary') throw new Error('不能移除主字段');
   if (viewsRequiringField(document, fieldId).length) throw new Error('请先调整依赖此属性的视图');
-  if (collectionFilterUsesField(document.dataset.filter as unknown as CollectionRuleFilter | null, fieldId)) {
+  if (collectionFilterUsesField(document.dataset.filter as unknown as DatasetFilter | null, fieldId)) {
     throw new Error('请先调整引用此属性的笔记条件匹配');
   }
   const views = document.views.items.map((view) => {
@@ -93,7 +93,7 @@ export function addTableField(document: MultidimensionalTableDocument, field: Ta
     const key = builtinPresetTableField(item.id)?.property_key;
     return key !== undefined && canonicalizePropertyKey(key).toLocaleLowerCase() === propertyKey;
   });
-  if (!propertyKey || builtinKey || ['flowix_key', 'key'].includes(propertyKey)
+  if (!propertyKey || builtinKey
     || document.dataset.schema.fields.some((item) => item.property_key
     && canonicalizePropertyKey(item.property_key).toLocaleLowerCase() === propertyKey)) {
     throw new Error('属性键已存在或属于保留名称');
diff --git a/app/flowix-web/features/multidimensional-table/table-dataset-menu.tsx b/app/flowix-web/features/multidimensional-table/table-dataset-menu.tsx
index ef1183a71..50546aab4 100644
--- a/app/flowix-web/features/multidimensional-table/table-dataset-menu.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-dataset-menu.tsx
@@ -21,7 +21,8 @@ function readAutoCollectCondition(defaultFieldId: string, fields: AutoCollectFie
   const condition = config?.condition ?? {};
   return {
     ...condition,
-    property_match: condition.property_match ?? 'union',
+    match: condition.match ?? (condition.property_match === 'intersection' ? 'all' : condition.property_match === 'union' ? 'any' : 'all'),
+    path: condition.path ?? null,
     property_conditions: (condition.property_conditions ?? [{ field_id: defaultFieldId, operator: 'contains' as const, value: '' }]).map((item) => ({
       ...item,
       field_id: fields.find((fieldOption) => fieldOption.id === item.field_id)?.label ?? item.field_id,
@@ -82,12 +83,12 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
   const baseline = useRef(JSON.stringify(autoCollectDraft));
   const draftOpen = filterOnly ? autoCollectMenuOpen : open;
   const folderPathLabel = fixedFolderPath !== undefined
-    ? '固定'
-    : autoCollectDraft.file_condition?.path_scope === 'all'
+    ? fixedFolderPath || '笔记本根目录'
+    : autoCollectDraft.path === ''
       ? t('multidimensionalTable.autoCollect.anyFolder')
-      : autoCollectDraft.file_condition?.path_contains;
+      : autoCollectDraft.path ?? '空';
   const canClearFolderPath = fixedFolderPath === undefined
-    && (autoCollectDraft.file_condition?.path_scope === 'all' || Boolean(autoCollectDraft.file_condition?.path_contains));
+    && autoCollectDraft.path !== null && autoCollectDraft.path !== undefined;
   useEffect(() => {
     if (fixedFolderPath !== undefined) setFolderPickerOpen(false);
   }, [fixedFolderPath]);
@@ -103,11 +104,7 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
   const savePathImmediately = async (path: string | null) => {
     const withPath = (condition: TableAutoCollectCondition): TableAutoCollectCondition => ({
       ...condition,
-      file_condition: {
-        ...Object.fromEntries(Object.entries(condition.file_condition ?? {})
-          .filter(([key]) => key !== 'path_contains' && key !== 'path_scope')),
-        ...(path === null ? { path_scope: 'all' as const } : path ? { path_contains: path } : {}),
-      },
+      path: path === null ? '' : path.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') || null,
     });
     const nextDraft = withPath(autoCollectDraft);
     if (onSavePath && !(await onSavePath(path))) return false;
@@ -153,12 +150,12 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
   }, [folderPickerOpen, folderOptions]);
 
   const folderPathRow = <Popover open={folderPickerOpen} onOpenChange={setFolderPickerOpen}>
-    <div data-table-dataset-location-menu className={`flex min-w-0 items-center gap-0.5 rounded-lg transition-colors ${saving || !notebookPath || fixedFolderPath !== undefined ? '' : 'hover:bg-[var(--hover-bg)]'}`}>
+    <div data-table-dataset-location-menu data-state={folderPickerOpen ? 'open' : 'closed'} className={`flex min-w-0 items-center gap-0.5 rounded-lg transition-colors ${saving || !notebookPath || fixedFolderPath !== undefined ? '' : 'hover:bg-[var(--hover-bg)] data-[state=open]:bg-[var(--hover-bg)]'}`}>
       <PopoverTrigger asChild>
         <button type="button" disabled={saving || !notebookPath || fixedFolderPath !== undefined} className="flex h-8 min-w-0 flex-1 items-center justify-between gap-2 rounded-lg pl-1.5 text-left text-sm disabled:opacity-50">
           <span className="min-w-0 truncate">浏览和保存</span>
           <span className="flex min-w-0 flex-1 items-center justify-end gap-1 text-[var(--muted-foreground)]">
-            {folderPathLabel && <span title={folderPathLabel} className="max-w-[150px] truncate text-right text-xs">{folderPathLabel}</span>}
+            {folderPathLabel && <span title={fixedFolderPath !== undefined ? `固定：${folderPathLabel}` : folderPathLabel} className="max-w-[150px] truncate text-right text-sm">{folderPathLabel}</span>}
           </span>
         </button>
       </PopoverTrigger>
@@ -184,11 +181,11 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
           : <div className="space-y-0.5">
             <button
               type="button"
-              aria-pressed={autoCollectDraft.file_condition?.path_scope === 'all'}
+              aria-pressed={autoCollectDraft.path === ''}
               onClick={async () => {
                 if (await savePathImmediately(null)) setFolderPickerOpen(false);
               }}
-              className={`flex h-8 w-full items-center gap-2 rounded-lg pr-2 text-left text-sm hover:bg-[var(--muted)] ${autoCollectDraft.file_condition?.path_scope === 'all' ? 'bg-[var(--muted)]' : ''}`}
+              className={`flex h-8 w-full items-center gap-2 rounded-lg pr-2 text-left text-sm hover:bg-[var(--muted)] ${autoCollectDraft.path === '' ? 'bg-[var(--muted)]' : ''}`}
             >
               <span className="flex min-w-0 flex-1 items-center gap-2 pl-2">
                 <ResourceFolderIcon expanded={false} className="h-[18px] w-[18px] shrink-0" />
@@ -201,7 +198,7 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
             }).map((option) => {
               const segments = option.relativePath.split('/');
               const folderName = segments[segments.length - 1] ?? option.relativePath;
-              const selected = autoCollectDraft.file_condition?.path_contains === option.relativePath;
+              const selected = autoCollectDraft.path === option.relativePath;
               const hasChildren = folderOptions.some((candidate) => candidate.relativePath.startsWith(`${option.relativePath}/`));
               const collapsed = collapsedFolders.has(option.relativePath);
               return <div key={option.relativePath} className="flex h-8 min-w-0 items-center rounded-lg pr-2 text-sm hover:bg-[var(--muted)]" style={{ paddingLeft: `${8 + option.depth * 12}px` }}>
@@ -249,11 +246,7 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
     const reset = readAutoCollectCondition(defaultFieldId, autoCollectFields, null);
     return {
       ...reset,
-      file_condition: {
-        ...reset.file_condition,
-        ...(current.file_condition?.path_scope === 'all' ? { path_scope: 'all' as const } : {}),
-        path_contains: current.file_condition?.path_contains ?? '',
-      },
+      path: current.path,
     };
   });
   const filterMenu = <>
@@ -261,33 +254,33 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
           <PopoverTrigger asChild>
             <button type="button" disabled={saving} className="flex h-8 w-full items-center justify-between rounded-lg px-1.5 text-left text-sm hover:bg-[var(--hover-bg)] hover:text-[var(--foreground)] data-[state=open]:bg-[var(--hover-bg)] data-[state=open]:text-[var(--foreground)] disabled:opacity-50">
               <span>数据条件</span>
-              <span className="flex items-center gap-1 text-xs text-[var(--muted-foreground)]">
+              <span className="flex items-center gap-1 text-sm text-[var(--muted-foreground)]">
                 {dataSelectionConfigured ? '已设置' : '未设置'}
                 <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
               </span>
             </button>
           </PopoverTrigger>
-          <PopoverContent side="right" align="start" sideOffset={0} ignorePopoverOutside={folderPickerOpen} fitViewport style={{ zIndex: 160 }} className="w-[320px] max-w-[calc(100vw-16px)] rounded-xl px-1 py-2 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+          <PopoverContent side="right" align="start" sideOffset={0} ignorePopoverOutside={folderPickerOpen} fitViewport style={{ zIndex: 160 }} className="w-[320px] max-w-[calc(100vw-16px)] rounded-xl p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
             <div className="space-y-2">
             <div className="space-y-1">
                 <div className="min-w-0 space-y-1">
-                  <div role="group" aria-label="属性匹配方式" className="multidimensional-table__condition-tabs mx-2">
+                  <div role="group" aria-label="属性匹配方式" className="multidimensional-table__condition-tabs">
                     <button
                       type="button"
-                      aria-pressed={(autoCollectDraft.property_match ?? 'union') === 'union'}
-                      onClick={() => setAutoCollectDraft((current) => ({ ...current, property_match: 'union' }))}
+                      aria-pressed={(autoCollectDraft.match ?? 'all') === 'any'}
+                      onClick={() => setAutoCollectDraft((current) => ({ ...current, match: 'any' }))}
                       className="multidimensional-table__condition-tab"
                     >并集</button>
                     <button
                       type="button"
-                      aria-pressed={autoCollectDraft.property_match === 'intersection'}
-                      onClick={() => setAutoCollectDraft((current) => ({ ...current, property_match: 'intersection' }))}
+                      aria-pressed={(autoCollectDraft.match ?? 'all') === 'all'}
+                      onClick={() => setAutoCollectDraft((current) => ({ ...current, match: 'all' }))}
                       className="multidimensional-table__condition-tab"
                     >交集</button>
                   </div>
-                  <p className="agent-thread-card__codex-settings-title px-2">{t('multidimensionalTable.autoCollect.properties')}</p>
+                  <p className="agent-thread-card__codex-settings-title">{t('multidimensionalTable.autoCollect.properties')}</p>
                 </div>
-                {(autoCollectDraft.property_conditions ?? []).map((condition, index) => <div key={index} className="flex min-w-0 items-center gap-1 px-2">
+                {(autoCollectDraft.property_conditions ?? []).map((condition, index) => <div key={index} className="flex min-w-0 items-center gap-1">
                   <input
                     value={condition.field_id === '名称' ? '' : condition.field_id}
                     disabled={saving}
@@ -342,9 +335,9 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
                   }))}
                   className="flex h-7 items-center gap-1 rounded-lg px-1.5 text-left text-xs text-[var(--muted-foreground)] hover:bg-[var(--hover-bg)] hover:text-[var(--foreground)] disabled:opacity-50"
                 ><Plus className="h-3.5 w-3.5" aria-hidden="true" />添加条件</button>
-                <p className="agent-thread-card__codex-settings-title px-2">{t('multidimensionalTable.autoCollect.file')}</p>
+                <p className="agent-thread-card__codex-settings-title">{t('multidimensionalTable.autoCollect.file')}</p>
                 <div className="space-y-1">
-                  <label className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2 px-2">
+                  <label className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2">
                     <span className="px-0.5 text-sm text-[var(--foreground)]">{t('multidimensionalTable.autoCollect.fileName')}</span>
                     <input
                       value={autoCollectDraft.file_condition?.file_name_contains ?? ''}
@@ -355,32 +348,25 @@ export function TableDatasetMenu({ defaultFieldId, fields: autoCollectFields, co
                       className="h-8 w-full rounded-lg border border-[var(--border)] bg-transparent px-3 text-sm outline-none disabled:opacity-50"
                     />
                   </label>
-                  <div className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2 px-2">
+                  <div className="grid min-w-0 grid-cols-[64px_minmax(0,1fr)] items-center gap-2">
                     <span className="px-0.5 text-sm text-[var(--foreground)]">{t('multidimensionalTable.autoCollect.fileType')}</span>
                     <Select
-                      value={autoCollectDraft.file_condition?.file_type || 'any'}
-                      disabled={saving}
-                      onValueChange={(type) => setAutoCollectDraft((current) => ({
-                        ...current,
-                        file_condition: { ...current.file_condition, file_type: type === 'any' ? '' : type as TableAutoCollectFileType },
-                      }))}
+                      value="markdown"
+                      disabled
                     >
                       <SelectTrigger className="h-8 min-w-0 w-full rounded-lg bg-transparent px-2 text-left">
-                        <SelectValue>{autoCollectDraft.file_condition?.file_type
-                          ? t(`multidimensionalTable.autoCollect.type.${autoCollectDraft.file_condition.file_type}` as I18nKey)
-                          : t('multidimensionalTable.autoCollect.anyFileType')}</SelectValue>
+                        <SelectValue>{t('multidimensionalTable.autoCollect.type.markdown')}</SelectValue>
                       </SelectTrigger>
                       <SelectContent align="start" fitViewport style={{ zIndex: 170 }} className="flowix-preferences-select-content">
-                        <SelectItem value="any">{t('multidimensionalTable.autoCollect.anyFileType')}</SelectItem>
                         <SelectItem value="markdown">{t('multidimensionalTable.autoCollect.type.markdown')}</SelectItem>
                       </SelectContent>
                     </Select>
                   </div>
                 </div>
             </div>
-            <div className="mx-2 flex gap-2">
-              <button type="button" disabled={saving} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-transparent text-sm text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:opacity-50" onClick={resetDataSelection}>{t('multidimensionalTable.autoCollect.reset')}</button>
-              <button type="button" disabled={saving} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] text-sm text-[var(--foreground)] hover:bg-[var(--muted)] disabled:opacity-50" onClick={async () => {
+            <div className="flex gap-2">
+              <button type="button" disabled={saving} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--muted)] px-2 text-sm text-[var(--foreground)] hover:bg-[var(--hover-bg)] disabled:cursor-not-allowed disabled:opacity-50" onClick={resetDataSelection}>{t('multidimensionalTable.autoCollect.reset')}</button>
+              <button type="button" disabled={saving} className="flex h-8 flex-1 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--muted)] px-2 text-sm text-[var(--foreground)] hover:bg-[var(--hover-bg)] disabled:cursor-not-allowed disabled:opacity-50" onClick={async () => {
                 if (await onSave(resolveAutoCollectCondition(autoCollectDraft, autoCollectFields))) closeMenu();
               }}>应用</button>
             </div>
diff --git a/app/flowix-web/features/multidimensional-table/table-document-view.tsx b/app/flowix-web/features/multidimensional-table/table-document-view.tsx
index 7339fa8bd..15d0eea84 100644
--- a/app/flowix-web/features/multidimensional-table/table-document-view.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-document-view.tsx
@@ -1,4 +1,10 @@
-import { propertyImagePaths as imagePaths, selectPropertyImage } from '@features/document/properties/image-value-input';
+import { resolveDatasetFilterForLocation } from '@features/collection/dataset-filter-location';
+import { NotePropertyImageValue, propertyImagePaths as imagePaths, selectPropertyImage } from '@features/document/properties/image-value-input';
+import { DateValueInput } from '@features/document/components/note-properties/date-value-input';
+import { ColorValueInput } from '@features/document/properties/color-value-input';
+import { IconValueInput } from '@features/document/properties/icon-value-input';
+import { MultiSelectValueInput } from '@features/document/properties/multi-select-value-input';
+import { SelectValueInput } from '@features/document/properties/select-value-input';
 import { countPresetTableReferences, deletePresetEverywhere, ensureTableFieldPreset, migrateNotePropertyKey, updatePresetFromTable } from '@features/properties/property-preset-service';
 import { usePropertyPresetStore } from '@features/properties/property-preset-store';
 import { DeletePresetDialog } from '@features/properties/delete-preset-dialog';
@@ -7,15 +13,18 @@ import { NoteCreatePicker } from './note-create-picker';
 import { collectionSessionKey } from '@/lib/collection-session-key';
 'use client';
 
+import type { SurfaceLifecycle, SurfacePresentationUpdate } from '@features/workspace/public/surface-api';
+
 import { mutateCollectionFile } from '@features/collection/mutations';
 import { FolderCollectionSwitchConfirmDialog } from '@features/collection/public/folder-api';
 import { reviseCollection, type CollectionSource } from '@features/collection/model';
 import { resolveCollectionSaveDirectory } from '@features/collection/save-location';
-import { collectionFilterUsesField, type CollectionRuleFilter } from '@features/collection/rule-filter';
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { collectionFilterUsesField, type DatasetFilter } from '@features/collection/rule-filter';
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { ChevronLeft, ChevronRight, LoaderCircle, Plus, MousePointerClick, Table2 } from 'lucide-react';
 import { DotsThreeIcon, EyeIcon, EyeSlashIcon, PencilSimpleIcon, TrashIcon } from '@phosphor-icons/react';
 import { collections, notes as notesClient, windows, type NoteEntry } from '@platform/tauri/client';
+import { NOTE_COLOR_HEX } from '@features/memo/store';
 import { canonicalDirectoryPath, canonicalPath, joinNotebookMemoPath, notebookRelativeDirectoryPath, parentDirectoryPath } from '@/lib/path';
 import { toast } from '@/lib/toast';
 import { canonicalizePropertyKey, isSystemPropertyKey } from '@features/properties/property-key';
@@ -25,13 +34,16 @@ import { PROPERTY_URL_RE } from '@features/document/properties/property-type';
 import { assetUrl, decodeStorageKey } from '@features/editor/extensions/attachment-link/utils';
 import { getAllPresets, resolvePropertyPreset, resolvePropertyDisplayName, type PropertyPreset } from '@features/document/properties/presets';
 import { usePropertyPresets } from '@features/properties/public-api';
-import { createFileBrowserTarget, openBrowserColumnTarget } from '@features/workspace/use-cases/browser-column-navigation';
+import { createFileBrowserTarget } from '@features/workspace/public/browser-column-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { replaceExternalDocumentPath } from '@features/workspace/use-cases/workspace-navigation';
 import { NotebookTreeResourceIcon } from '@features/memo/components/file-type-icon';
 import { renameMarkdownTitle } from '@features/document/use-cases/local-document-operations';
 import { ensureFileDisplayIdentity, type FileDisplayIdentity } from '@/lib/file-display-registry';
 import { displayTitleFromFilename } from '@/lib/utils';
+import { collectionDisplayName } from '@features/collection/model';
 import { Button } from '@shared/ui/button';
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@shared/ui/dialog';
 import { CenteredLoadingSpinner } from '@shared/ui/centered-loading-spinner';
 import { useTitleEditCaret } from '@shared/hooks/use-title-edit-caret';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
@@ -59,6 +71,8 @@ import {
 } from './model';
 import {
   BUILTIN_TABLE_FIELDS,
+  NOTE_CREATED_AT_FIELD_ID,
+  NOTE_UPDATED_AT_FIELD_ID,
   NOTE_CALENDAR_DATE_FIELD_ID,
   builtinPresetValue,
   builtinPresetTableField,
@@ -69,15 +83,20 @@ import {
 import { groupRecordsByValue, KANBAN_UNASSIGNED_GROUP_ID } from './view-index';
 import { noteMatchesCollectionFilter } from './record-filter';
 import { applyTableView } from './view-records';
+import { planTableNoteDrop, type TableNoteDropPreview, type TableNoteDropRejection } from './table-note-drop';
 import { useTableImages } from './use-table-images';
 import { useTableScrollLoading } from './use-table-scroll-loading';
 import { TableCalendarView, TableGalleryView, TableKanbanView } from './table-secondary-views';
+import { TableNoteDropOverlay } from './table-note-drop-overlay';
+import { useTableNoteDropTarget, type TableNoteDropTargetRejection } from './use-table-note-drop-target';
 import { TableSortButton, cycleTableSort, tableSortDirection } from './table-sort-button';
 import { TableDatasetMenu } from './table-dataset-menu';
 import { sortFields } from './field-order';
 import { useAutoContentColumnWidths, type AutoColumnContent } from './use-auto-content-column-widths';
 import { TableFieldList } from './table-field-list';
-import { TableRecordRow } from './table-record-row';
+import { TableBooleanInput, TableNumberInput, TableRecordRow } from './table-record-row';
+import { TableTagValueInput } from './table-tag-value-input';
+import { TableTextValueInput } from './table-text-value-input';
 import { applyFieldMigrations, migratedOptionValue, planFieldMigrations, type FieldValueMigration } from './table-field-migration';
 import { bindTableField, presetFromTableField, retireTablePreset, tableFieldFromPreset } from './table-preset-bindings';
 import { NOTE_CALENDAR_DATE_FIELDS, useCalendarController } from './use-calendar-controller';
@@ -87,9 +106,15 @@ import { useTableSession } from './use-table-session';
 import { useTableCellWriter, type TableCellSaveStatus } from './use-table-cell-writer';
 import { useTableViewSelection } from './use-table-view-selection';
 import { removeTableView, resolveTableView } from './view-selection';
+import { isMarkdownNoteDragResource, type NotebookNoteDragResource } from '@features/memo/public/drag-resource-api';
 import { addPresetField, addTableField, toggleDatasetTableFieldVisibility, changeFieldType as changeFieldTypeInDocument, removeBuiltinField as removeBuiltinTableField, removeField, removePresetField, viewsRequiringField } from './table-commands';
 
+const TABLE_TITLE_VISIBILITY_STORAGE_KEY = 'flowix:multidimensional-table:title-visible';
+const TABLE_TITLE_VISIBILITY_EVENT = 'flowix:multidimensional-table:title-visibility-changed';
+
 export interface TableDocumentViewProps {
+  onSurfaceLifecycleReady?: (lifecycle: SurfaceLifecycle | null) => void;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
   filePath: string;
   /** Stable runtime identity for the table file; survives a rename. */
   fileIdentity?: FileDisplayIdentity;
@@ -310,6 +335,37 @@ function notePropertyEditorValue(note: NoteEntry | undefined, field: TableField)
   return value;
 }
 
+function calendarCreatePropertyValue(field: TableField, value: unknown): { include: boolean; value: unknown } {
+  if (field.type === 'Boolean') return { include: true, value: Boolean(value) };
+  if (field.type === 'Number') {
+    const number = typeof value === 'number' ? value : Number(String(value ?? '').trim());
+    return { include: Number.isFinite(number) && String(value ?? '').trim() !== '', value: number };
+  }
+  if (field.type === 'Select') {
+    const option = field.options?.find((item) => item.id === value);
+    return { include: Boolean(option), value: option?.label ?? null };
+  }
+  if (field.type === 'MultiSelect') {
+    const ids = Array.isArray(value) ? value.map(String) : [];
+    const labels = ids.map((id) => field.options?.find((item) => item.id === id)?.label ?? id);
+    return { include: labels.length > 0, value: labels };
+  }
+  if (field.type === 'Tag' || field.type === 'Color' || (field.type === 'Image' && field.multiple)) {
+    const values = Array.isArray(value) ? value.map(String) : String(value ?? '').split(',');
+    const normalized = values.map((item) => item.trim()).filter(Boolean);
+    return { include: normalized.length > 0, value: normalized };
+  }
+  const normalized = String(value ?? '').trim();
+  return { include: Boolean(normalized), value: normalized || null };
+}
+
+function isCalendarCreateWritableField(field: TableField): boolean {
+  return field.type !== 'primary'
+    && Boolean(field.property_key)
+    && field.id !== NOTE_CREATED_AT_FIELD_ID
+    && field.id !== NOTE_UPDATED_AT_FIELD_ID;
+}
+
 const EMPTY_CELL_STATUSES: ReadonlyMap<string, TableCellSaveStatus> = new Map();
 
 export function TableDocumentView(props: TableDocumentViewProps) {
@@ -317,7 +373,7 @@ export function TableDocumentView(props: TableDocumentViewProps) {
   return <TableDocumentViewSession key={sessionKey} {...props} />;
 }
 
-function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebookId, expectedCollectionId, initialViewId, onActiveViewChange, editable = true, canCreateFields = true, canCreateRecords = true, showAssociateNoteAction = canCreateRecords, canDeleteViews = true, embeddedInEditor = false, onRemoveReference, trailingActions, onFilePathChange }: TableDocumentViewProps) {
+function TableDocumentViewSession({ onSurfaceLifecycleReady, reportPresentation, filePath, fileIdentity, notebookPath, notebookId, expectedCollectionId, initialViewId, onActiveViewChange, editable = true, canCreateFields = true, canCreateRecords = true, showAssociateNoteAction = canCreateRecords, canDeleteViews = true, embeddedInEditor = false, onRemoveReference, trailingActions, onFilePathChange }: TableDocumentViewProps) {
   const tablePageSize = embeddedInEditor ? EMBEDDED_TABLE_PAGE_SIZE : SCROLL_PAGE_SIZE;
   const galleryPageSize = embeddedInEditor ? EMBEDDED_GALLERY_PAGE_SIZE : SCROLL_PAGE_SIZE;
   const [currentFilePath, setCurrentFilePath] = useState(filePath);
@@ -333,7 +389,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   }, [propertyFields, t]);
   const {
     document, loadError, saving, saveFailed, setSaving, reportSaveFailure, notes, setNotes, resolvedNotebookId,
-    notesLoadError, load, acceptContent, save: saveSession, loadSequenceRef, loadGeneration, isCurrentSession, pendingNotePropertiesRef,
+    notesLoadError, load, acceptContent, save: saveSession, flush: flushSession, loadSequenceRef, loadGeneration, isCurrentSession, pendingNotePropertiesRef,
   } = useTableSession({ filePath: currentFilePath, fileIdentity, notebookPath, notebookId, expectedCollectionId });
   const latestDocumentRef = useRef(document);
   latestDocumentRef.current = document;
@@ -366,7 +422,39 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   const [editingViewWidth, setEditingViewWidth] = useState(48);
   const [managingViewId, setManagingViewId] = useState<string | null>(null);
   const [managingViewName, setManagingViewName] = useState('');
+  const [viewPendingDelete, setViewPendingDelete] = useState<TableView | null>(null);
+  const [showTableTitle, setShowTableTitle] = useState(true);
   const manageRenameCancelledRef = useRef(false);
+  const deletingViewRef = useRef(false);
+  useEffect(() => {
+    const readVisibility = () => {
+      try {
+        setShowTableTitle(window.localStorage.getItem(TABLE_TITLE_VISIBILITY_STORAGE_KEY) !== 'false');
+      } catch {
+        setShowTableTitle(true);
+      }
+    };
+    const handleStorage = (event: StorageEvent) => {
+      if (event.key === TABLE_TITLE_VISIBILITY_STORAGE_KEY || event.key === null) readVisibility();
+    };
+    readVisibility();
+    window.addEventListener('storage', handleStorage);
+    window.addEventListener(TABLE_TITLE_VISIBILITY_EVENT, readVisibility);
+    return () => {
+      window.removeEventListener('storage', handleStorage);
+      window.removeEventListener(TABLE_TITLE_VISIBILITY_EVENT, readVisibility);
+    };
+  }, []);
+  const toggleTableTitleVisibility = useCallback(() => {
+    const next = !showTableTitle;
+    setShowTableTitle(next);
+    try {
+      window.localStorage.setItem(TABLE_TITLE_VISIBILITY_STORAGE_KEY, String(next));
+      window.dispatchEvent(new Event(TABLE_TITLE_VISIBILITY_EVENT));
+    } catch {
+      // Keep the visibility toggle usable when local storage is unavailable.
+    }
+  }, [showTableTitle]);
   const [editingTableName, setEditingTableName] = useState(false);
   const [tableNameDraft, setTableNameDraft] = useState('');
   const [renamingTable, setRenamingTable] = useState(false);
@@ -374,9 +462,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   const commitTableTitle = useCallback(async (rawTitle: string) => {
     setEditingTableName(false);
     const title = rawTitle.trim();
-    const currentTitle = document?.collection.placement === 'folder'
-      ? currentFilePath.replace(/[\\/]+$/, '').replace(/[\\/][^\\/]*$/, '').split(/[\\/]/).pop() ?? document.collection.name
-      : document?.collection.name ?? displayTitleFromFilename(currentFilePath);
+    const currentTitle = document ? collectionDisplayName(currentFilePath, document.collection.placement) : displayTitleFromFilename(currentFilePath);
     if (!editable || saving || renamingTable || !notebookPath || !title || title === currentTitle) return;
     if (/[\\/]/.test(title)) {
       toast.error('文件名不能包含路径分隔符');
@@ -449,12 +535,18 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   const [configuringViewId, setConfiguringViewId] = useState<string | null>(null);
   const [viewFieldPickerAnchorRect, setViewFieldPickerAnchorRect] = useState<DOMRect | null>(null);
   const [calendarCursor, setCalendarCursor] = useState(() => new Date());
+  const [calendarCreatePropertyValues, setCalendarCreatePropertyValues] = useState<Record<string, unknown>>({});
+  const [calendarEditingRecord, setCalendarEditingRecord] = useState<TableRecord | null>(null);
+  const calendarPendingCreatedNoteRef = useRef<{ title: string; entry: NoteEntry } | null>(null);
   const [tablePage, setTablePage] = useState(0);
   const [galleryPage, setGalleryPage] = useState(0);
   const recordsScrollerRef = useRef<HTMLDivElement | null>(null);
+  const tableDropAreaRef = useRef<HTMLDivElement | null>(null);
+  const tableDropTargetId = useId();
+  const [tableDropPreview, setTableDropPreview] = useState<TableNoteDropPreview | null>(null);
   const loadMoreRecordsRef = useRef<HTMLDivElement | null>(null);
   const [pendingTablePageRecordId, setPendingTablePageRecordId] = useState<string | null>(null);
-  const { cellStatusesByRecord, updateCell } = useTableCellWriter({
+  const { cellStatusesByRecord, updateCell, flush: flushCells } = useTableCellWriter({
     enabled: Boolean(document) && !saving && editable,
     loadGeneration,
     notebookPath,
@@ -462,6 +554,53 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     setNotes,
     pendingNotePropertiesRef,
   });
+  useEffect(() => {
+    onSurfaceLifecycleReady?.({ status: 'ready', flush: async () => {
+      const [sessionSaved, cellsSaved] = await Promise.all([flushSession(), flushCells()]);
+      return sessionSaved && cellsSaved;
+    } });
+    return () => onSurfaceLifecycleReady?.(null);
+  }, [flushCells, flushSession, onSurfaceLifecycleReady]);
+  const onRemoveReferenceRef = useRef(onRemoveReference);
+  onRemoveReferenceRef.current = onRemoveReference;
+  const removeReferenceForPresentation = useCallback(() => { onRemoveReferenceRef.current?.(); }, []);
+  const hasRemoveReference = Boolean(onRemoveReference);
+  useEffect(() => {
+    if (!reportPresentation) return;
+    const title = document ? collectionDisplayName(currentFilePath, document.collection.placement) : displayTitleFromFilename(currentFilePath);
+    if (loadError) {
+      const actions = [
+        { id: 'retry', label: { key: 'error.retry' }, enabled: true, run: () => load() },
+        ...(embeddedInEditor && hasRemoveReference ? [{
+          id: 'remove-reference', label: { key: 'multidimensionalTable.removeReference' }, enabled: editable,
+          run: removeReferenceForPresentation,
+        }] : !embeddedInEditor && document?.collection.placement !== 'folder' ? [{
+          id: 'delete-table', label: { key: 'multidimensionalTable.deleteTableFile' }, enabled: editable,
+          run: () => { window.dispatchEvent(new CustomEvent('flowix:request-delete-external-file', { detail: { filePath: currentFilePath, notebookPath } })); },
+        }] : []),
+      ];
+      reportPresentation({ title, state: {
+        status: 'error',
+        message: { key: 'error.unexpected', fallbackText: loadError },
+        actions,
+      } });
+    } else if (!document) {
+      reportPresentation({ title, state: {
+        status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: false,
+      } });
+    } else if (expectedCollectionId && document.collection.id !== expectedCollectionId) {
+      reportPresentation({ title, state: {
+        status: 'unavailable', reason: 'stale-context',
+        message: { key: 'multidimensionalTable.referenceIdentityChanged' },
+        actions: embeddedInEditor && hasRemoveReference ? [{
+          id: 'remove-reference', label: { key: 'multidimensionalTable.removeReference' }, enabled: editable,
+          run: removeReferenceForPresentation,
+        }] : [],
+      } });
+    } else {
+      reportPresentation({ title, state: { status: 'ready' } });
+    }
+  }, [currentFilePath, document, editable, embeddedInEditor, expectedCollectionId, hasRemoveReference, load, loadError, notebookPath, removeReferenceForPresentation, reportPresentation]);
   const [newFieldOpen, setNewFieldOpen] = useState(false);
   const [newFieldAnchor, setNewFieldAnchor] = useState<{ rect: DOMRect; align: 'start' | 'end' } | null>(null);
   const [newFieldPropertyKey, setNewFieldPropertyKey] = useState('');
@@ -514,12 +653,36 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     updateWeekStart: updateCalendarWeekStart,
     updateDateField: updateCalendarDateField,
     addDialog: calendarAddDialog,
-    openAddDialog: openCalendarNotePopover,
+    openAddDialog: openCalendarAddDialog,
     closeAddDialog: closeCalendarAddPopover,
     setAddDialogOpen: setCalendarAddOpen,
     setTitle: setCalendarAddTitle,
   } = calendarController;
+  const calendarField = calendarDateFieldId && !calendarDateMetadata
+    ? document?.dataset.schema.fields.find((field) => field.id === calendarDateFieldId) ?? builtinPresetTableField(calendarDateFieldId) ?? undefined
+    : undefined;
   const { open: calendarAddOpen, anchorRect: calendarAddAnchorRect, date: calendarAddDate, title: calendarAddTitle } = calendarAddDialog;
+  const calendarCreateFields = useMemo(() => {
+    if (!document) return [];
+    const schemaFields = [...document.dataset.schema.fields];
+    for (const fieldId of document.dataset.schema.preset_fields) {
+      const presetField = builtinPresetTableField(fieldId);
+      if (presetField && !schemaFields.some((field) => field.id === presetField.id)) schemaFields.push(presetField);
+    }
+    return sortFields(schemaFields.filter(isCalendarCreateWritableField), (field) => field.id, document.dataset.schema.field_order);
+  }, [document]);
+  const openCalendarNotePopover = useCallback((date: string, anchorRect: DOMRect, fieldId: string) => {
+    calendarPendingCreatedNoteRef.current = null;
+    setCalendarEditingRecord(null);
+    setCalendarCreatePropertyValues(Object.fromEntries(calendarCreateFields.map((field) => [
+      field.id,
+      field.type === 'Date' && field.id === fieldId ? date
+        : field.type === 'Boolean' ? false
+          : field.type === 'MultiSelect' || field.type === 'Tag' || field.type === 'Color' || (field.type === 'Image' && field.multiple) ? []
+            : '',
+    ])));
+    openCalendarAddDialog(date, anchorRect, fieldId);
+  }, [calendarCreateFields, openCalendarAddDialog]);
   const calendarDays = useMemo(() => {
     const year = calendarCursor.getFullYear();
     const month = calendarCursor.getMonth();
@@ -538,6 +701,11 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     const key = noteKeyForRecord(record);
     return key ? noteByKey.get(key.replace(/\\/g, '/')) : undefined;
   }, [noteByKey]);
+  const calendarNoteColorForRecord = useCallback((record: TableRecord) => {
+    const color = noteForRecord(record)?.colors[0];
+    return color ? NOTE_COLOR_HEX[color] : undefined;
+  }, [noteForRecord]);
+  const noteIconForRecord = useCallback((record: TableRecord) => noteForRecord(record)?.icon ?? null, [noteForRecord]);
   const noteStatusForRecord = useCallback((record: TableRecord) => {
     const noteKey = noteKeyForRecord(record);
     const note = noteKey ? noteByKey.get(noteKey.replace(/\\/g, '/')) : undefined;
@@ -545,7 +713,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   }, [noteByKey, notesLoadError]);
   const conditionRecords = useMemo(() => {
     if (!document || !noteField) return [];
-    const datasetFilter = document.dataset.filter;
+    const datasetFilter = resolveDatasetFilterForLocation(document.dataset.filter, document.collection.placement, currentFilePath, notebookPath);
     if (datasetFilter == null) return [];
 
     const linkedPaths = new Set(document.dataset.records.include.map((record) => record.note_path.replace(/\\/g, '/')).filter(Boolean));
@@ -712,6 +880,8 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   const visibleTableRecords = useMemo(() => visibleRecords.slice(
     embeddedInEditor ? currentPage * tablePageSize : 0, (currentPage + 1) * tablePageSize,
   ), [visibleRecords, embeddedInEditor, currentPage, tablePageSize]);
+  const nextTableRecordId = visibleRecords[(embeddedInEditor ? currentPage * tablePageSize : 0) + visibleTableRecords.length]?.id ?? null;
+  const renderedTableRecords = tableDropPreview?.records ?? visibleTableRecords;
   const visibleGalleryRecords = useMemo(() => secondaryViewRecords.slice(
     embeddedInEditor ? galleryCurrentPage * galleryPageSize : 0, (galleryCurrentPage + 1) * galleryPageSize,
   ), [secondaryViewRecords, embeddedInEditor, galleryCurrentPage, galleryPageSize]);
@@ -767,19 +937,18 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     const fileCondition = Object.fromEntries(Object.entries({
       file_name_contains: condition.file_condition?.file_name_contains?.trim() ?? '',
       file_type: condition.file_condition?.file_type?.trim().replace(/^\./, '') ?? '',
-      path_contains: condition.file_condition?.path_contains?.trim() ?? '',
-      path_scope: condition.file_condition?.path_scope === 'all' ? 'all' : '',
     }).filter(([, value]) => value)) as TableAutoCollectCondition['file_condition'];
     const hasPropertyCriteria = propertyConditions.length > 0;
     const hasFileCriteria = Object.keys(fileCondition ?? {}).length > 0;
+    const rawPath = condition.path === undefined ? previous?.condition.path ?? null : condition.path;
+    const path = typeof rawPath === 'string' ? rawPath.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') : null;
     const nextCondition: TableAutoCollectCondition = {
-      ...(hasPropertyCriteria ? {
-        property_conditions: propertyConditions,
-        property_match: condition.property_match ?? 'union',
-      } : {}),
+      match: condition.match ?? (condition.property_match === 'intersection' ? 'all' : condition.property_match === 'union' ? 'any' : previous?.condition.match ?? 'all'),
+      path,
+      ...(hasPropertyCriteria ? { property_conditions: propertyConditions } : {}),
       ...(hasFileCriteria ? { file_condition: fileCondition } : {}),
     };
-    const hasActiveCriteria = hasFileCriteria || hasPropertyCriteria;
+    const hasActiveCriteria = hasFileCriteria || hasPropertyCriteria || path !== null;
     if (previous && hasActiveCriteria && JSON.stringify(previous.condition) === JSON.stringify(nextCondition)) return true;
     if (!previous && !hasActiveCriteria && document.dataset.filter == null) return true;
     const nextAutoCollect: TableAutoCollectConfig | null = hasActiveCriteria
@@ -793,30 +962,24 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
 
   const saveAutoCollectPath = useCallback(async (path: string | null): Promise<boolean> => {
     if (!document || saving) return false;
-    const removePathRules = (value: unknown): unknown => {
-      if (Array.isArray(value)) return value.flatMap((item) => {
-        const next = removePathRules(item);
-        return next === null ? [] : [next];
-      });
-      if (!value || typeof value !== 'object') return value;
-      const rule = value as Record<string, unknown>;
-      if (typeof rule.field === 'string') return rule.field === 'path' ? null : rule;
-      return Object.fromEntries(Object.entries(rule).map(([key, item]) => [key, removePathRules(item)]));
+    if (document.collection.placement === 'folder') return false;
+    if (!canEditTableAutoCollectFilter(document)) {
+      toast.error('当前数据集包含编辑器不支持的规则，未保存以保留原筛选');
+      return false;
+    }
+    const previous = tableAutoCollectConfig(document);
+    const nextPath = path === null ? '' : path.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') || null;
+    if ((previous?.condition.path ?? null) === nextPath) return true;
+    const condition: TableAutoCollectCondition = {
+      ...(previous?.condition ?? {}),
+      match: previous?.condition.match ?? 'all',
+      path: nextPath,
     };
-    const stripped = document.dataset.filter
-      ? removePathRules(document.dataset.filter) as Record<string, unknown>
-      : { all: [], any: [] };
-    const all = Array.isArray(stripped.all) ? [...stripped.all] : [];
-    const any = Array.isArray(stripped.any) ? [...stripped.any] : [];
-    const normalizedPath = path?.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') ?? '';
-    if (path === null) all.push({ field: 'path', op: 'contains', value: '' });
-    else if (normalizedPath) all.push({ field: 'path', op: 'contains', value: normalizedPath });
-    const filter = all.length || any.length ? { ...stripped, all, any } : null;
-    return save({
-      ...document,
-      collection: reviseCollection(document.collection),
-      dataset: { ...document.dataset, filter },
-    });
+    const hasConditions = Boolean(condition.property_conditions?.length
+      || condition.file_condition?.file_name_contains?.trim()
+      || condition.file_condition?.file_type);
+    const next = withTableAutoCollect(document, nextPath !== null || hasConditions ? { condition } : null);
+    return save({ ...next, collection: reviseCollection(document.collection) });
   }, [document, save, saving]);
 
   const retryNoteLookup = useCallback(() => { void load(); }, [load]);
@@ -893,7 +1056,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     const directory = resolveCollectionSaveDirectory({
       filePath: currentFilePath, notebookPath, placement: document.collection.placement,
       source: document.dataset.source,
-      configuredFolder: tableAutoCollectConfig(document)?.condition.file_condition?.path_contains,
+      configuredFolder: tableAutoCollectConfig(document)?.condition.path || undefined,
       defaultDirectory: parentDirectoryPath(currentFilePath, notebookPath),
     });
     const parentRelativePath = notebookRelativeDirectoryPath(notebookPath, directory) ?? undefined;
@@ -1092,16 +1255,32 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   }, [renameView]);
 
   const deleteView = useCallback(async (view: TableView) => {
-    if (!editable || !canDeleteViews || !document || saving || document.views.items.length <= 1) return;
-    if (!window.confirm(t('multidimensionalTable.view.deleteConfirm', { name: view.name }))) return;
-    const sequence = loadSequenceRef.current;
-    const next = removeTableView(document, view.id);
-    if (next === document) return;
-    if (await save(next, false, sequence) && isCurrentSession(sequence) && activeViewId === view.id) {
-      const fallback = resolveTableView(next);
-      if (fallback) activateView(fallback.id);
+    if (!editable || !canDeleteViews || !document || saving || document.views.items.length <= 1 || deletingViewRef.current) return;
+    deletingViewRef.current = true;
+    try {
+      const sequence = loadSequenceRef.current;
+      const next = removeTableView(document, view.id);
+      if (next === document) return;
+      if (await save(next, false, sequence) && isCurrentSession(sequence) && activeViewId === view.id) {
+        const fallback = resolveTableView(next);
+        if (fallback) activateView(fallback.id);
+      }
+    } finally {
+      deletingViewRef.current = false;
     }
-  }, [activeViewId, activateView, canDeleteViews, document, editable, isCurrentSession, loadSequenceRef, save, saving, t]);
+  }, [activeViewId, activateView, canDeleteViews, document, editable, isCurrentSession, loadSequenceRef, save, saving]);
+
+  const requestDeleteView = useCallback((view: TableView) => {
+    if (!editable || !canDeleteViews || !document || saving || document.views.items.length <= 1 || deletingViewRef.current) return;
+    setViewPendingDelete(view);
+  }, [canDeleteViews, document, editable, saving]);
+
+  const confirmDeleteView = useCallback(() => {
+    if (!viewPendingDelete || deletingViewRef.current) return;
+    const view = viewPendingDelete;
+    setViewPendingDelete(null);
+    void deleteView(view);
+  }, [deleteView, viewPendingDelete]);
 
   const linkSelectedNote = useCallback(async (selectedNoteKey: string) => {
     if (!editable || !document || document.collection.placement === 'folder' || !noteField || !selectedNoteKey || saving) return;
@@ -1211,7 +1390,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     }
   }, [activeView?.layout, applyCalendarDateToNote, createNoteInNotebook, document, editable, isCurrentSession, loadSequenceRef, newNoteTitle, noteField, notePickerCalendarDate, notePickerRecordId, resolvedNotebookId, save, saving, visibleRecords, reportSaveFailure, setSaving]);
 
-  const persistCalendarNote = useCallback(async (note: NoteEntry, calendarDate: { fieldId: string; date: string }, sequence: number) => {
+  const persistCalendarNote = useCallback(async (note: NoteEntry, calendarDate: { fieldId: string; date: string } | null, sequence: number) => {
     if (!editable || !document || !noteField || !isCurrentSession(sequence)) return false;
     const datedNote = await applyCalendarDateToNote(note, calendarDate);
     if (!isCurrentSession(sequence)) return false;
@@ -1227,36 +1406,280 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     return saved;
   }, [applyCalendarDateToNote, closeCalendarAddPopover, document, editable, isCurrentSession, noteField, save, setNotes]);
 
-  const createCalendarNote = useCallback(async () => {
-    const title = calendarAddTitle.trim();
-    if (!editable || !document || !noteField || !resolvedNotebookId || !calendarAddDate || !title || saving) return;
+  const planExternalNoteDrop = useCallback((
+    draggedNotes: NotebookNoteDragResource[], beforeRecordId: string | null,
+  ) => {
+    if (!document || (activeView?.layout !== 'gallery' && activeView?.layout !== 'table') || !notebookPath || !resolvedNotebookId) {
+      return { reason: 'unavailable' as const };
+    }
+    const uniqueNotes = [...new Map(draggedNotes.map((note) => [canonicalPath(note.relativePath), note])).values()];
+    const resolved: NoteEntry[] = [];
+    for (const draggedNote of uniqueNotes) {
+      if (!isMarkdownNoteDragResource(draggedNote) || draggedNote.notebookId !== resolvedNotebookId) {
+        return { reason: 'unavailable' as const };
+      }
+      const relativePath = canonicalPath(draggedNote.relativePath).replace(/^\/+/, '');
+      const note = notes.find((item) => item.relativePath.replace(/\\/g, '/') === relativePath);
+      if (!note || !noteInCollectionSource(relativePath, document.dataset.source, currentFilePath, notebookPath)) {
+        return { reason: 'unavailable' as const };
+      }
+      resolved.push(note);
+    }
+    return planTableNoteDrop({
+      explicitRecords: document.dataset.records.include,
+      automaticRecords: conditionRecords,
+      draggedNotes: resolved,
+      beforeRecordId,
+      view: activeView,
+      fields: document.dataset.schema.fields,
+      primaryFieldId: document.dataset.schema.primary_field_id,
+      noteForRecord,
+      isInSource: (path) => noteInCollectionSource(path, document.dataset.source, currentFilePath, notebookPath),
+    });
+  }, [activeView, conditionRecords, currentFilePath, document, noteForRecord, notes, notebookPath, resolvedNotebookId]);
+
+  const previewExternalGalleryDrop = useCallback((
+    draggedNotes: NotebookNoteDragResource[], beforeRecordId: string | null,
+  ): TableNoteDropPreview | TableNoteDropRejection => {
+    const plan = planExternalNoteDrop(draggedNotes, beforeRecordId);
+    if ('reason' in plan) return plan;
+    const index = plan.records.findIndex((record) => plan.draggedPaths.includes(record.note_path.replace(/\\/g, '/')));
+    const page = embeddedInEditor
+      ? Math.floor(index / galleryPageSize)
+      : Math.max(galleryCurrentPage, Math.floor(index / galleryPageSize));
+    return {
+      records: plan.records.slice(embeddedInEditor ? page * galleryPageSize : 0, (page + 1) * galleryPageSize),
+      draggedPaths: plan.draggedPaths,
+    };
+  }, [embeddedInEditor, galleryCurrentPage, galleryPageSize, planExternalNoteDrop]);
+
+  const persistExternalNotesToTableView = useCallback(async (
+    draggedNotes: NotebookNoteDragResource[],
+    beforeRecordId: string | null,
+    layout: 'table' | 'gallery',
+  ) => {
+    if (!editable || !document || !noteField || saving || activeView?.layout !== layout) return;
+    const plan = planExternalNoteDrop(draggedNotes, beforeRecordId);
+    const filteredMessage = layout === 'gallery'
+      ? 'multidimensionalTable.galleryDropFiltered' : 'multidimensionalTable.tableDropFiltered';
+    const unsupportedMessage = layout === 'gallery'
+      ? 'memo.fileTree.galleryDropUnsupported' : 'memo.fileTree.tableDropUnsupported';
+    const failedMessage = layout === 'gallery'
+      ? 'multidimensionalTable.galleryDropFailed' : 'multidimensionalTable.tableDropFailed';
+    if ('reason' in plan) {
+      toast.warning(t(plan.reason === 'filtered' ? filteredMessage : unsupportedMessage));
+      return;
+    }
     const sequence = loadSequenceRef.current;
+    if (!isCurrentSession(sequence)) return;
     setSaving(true);
     try {
-      const created = await createNoteInNotebook(title);
+      const records = plan.includedRecords.map((record) => record.id.startsWith('drop-note:')
+        ? { ...record, id: `rec_${createUuidV7()}` } : record);
+      const next: MultidimensionalTableDocument = {
+        ...document,
+        collection: reviseCollection(document.collection),
+        dataset: { ...document.dataset, records: {
+          ...document.dataset.records,
+          include: records,
+          exclude: document.dataset.records.exclude.filter((record) => !plan.draggedPaths.includes(record.note_path.replace(/\\/g, '/'))),
+        } },
+      };
+      if (!await save(next, true, sequence)) {
+        if (isCurrentSession(sequence)) toast.error(t(failedMessage));
+        return;
+      }
       if (!isCurrentSession(sequence)) return;
-      await persistCalendarNote(created.entry, calendarAddDate, sequence);
+      const index = plan.records.findIndex((record) => plan.draggedPaths.includes(record.note_path.replace(/\\/g, '/')));
+      const pageSize = layout === 'gallery' ? galleryPageSize : tablePageSize;
+      const setPage = layout === 'gallery' ? setGalleryPage : setTablePage;
+      setPage((page) => embeddedInEditor
+        ? Math.floor(index / pageSize)
+        : Math.max(page, Math.floor(index / pageSize)));
     } catch (error) {
-      reportSaveFailure(sequence);
-      toast.error(error instanceof Error ? error.message : '新建并关联笔记失败');
+      if (isCurrentSession(sequence)) toast.error(error instanceof Error ? error.message : t(failedMessage));
     } finally {
       if (isCurrentSession(sequence)) setSaving(false);
     }
-  }, [calendarAddDate, calendarAddTitle, createNoteInNotebook, document, editable, isCurrentSession, loadSequenceRef, noteField, persistCalendarNote, resolvedNotebookId, saving, setSaving, reportSaveFailure]);
+  }, [activeView?.layout, document, editable, embeddedInEditor, galleryPageSize, isCurrentSession, loadSequenceRef, noteField, planExternalNoteDrop, save, saving, setSaving, t, tablePageSize]);
+
+  const addExternalNotesToGallery = useCallback((draggedNotes: NotebookNoteDragResource[], beforeRecordId: string | null) => (
+    persistExternalNotesToTableView(draggedNotes, beforeRecordId, 'gallery')
+  ), [persistExternalNotesToTableView]);
+
+  const previewExternalTableDrop = useCallback((
+    draggedNotes: NotebookNoteDragResource[], beforeRecordId: string | null,
+  ): TableNoteDropPreview | TableNoteDropRejection => {
+    const plan = planExternalNoteDrop(draggedNotes, beforeRecordId);
+    if ('reason' in plan) return plan;
+    const index = plan.records.findIndex((record) => plan.draggedPaths.includes(record.note_path.replace(/\\/g, '/')));
+    const page = embeddedInEditor
+      ? Math.floor(index / tablePageSize)
+      : Math.max(currentPage, Math.floor(index / tablePageSize));
+    return {
+      records: plan.records.slice(embeddedInEditor ? page * tablePageSize : 0, (page + 1) * tablePageSize),
+      draggedPaths: plan.draggedPaths,
+    };
+  }, [currentPage, embeddedInEditor, planExternalNoteDrop, tablePageSize]);
+
+  const addExternalNotesToTable = useCallback((draggedNotes: NotebookNoteDragResource[], beforeRecordId: string | null) => (
+    persistExternalNotesToTableView(draggedNotes, beforeRecordId, 'table')
+  ), [persistExternalNotesToTableView]);
+
+  const previewTableDrop = useCallback((draggedNotes: NotebookNoteDragResource[], location: { beforeRecordId: string | null }) => (
+    previewExternalTableDrop(draggedNotes, location.beforeRecordId)
+  ), [previewExternalTableDrop]);
+  const onTableDropPreview = useCallback((preview: TableNoteDropPreview | null) => {
+    setTableDropPreview((current) => current && preview
+      && current.records.length === preview.records.length
+      && current.records.every((record, index) => record.id === preview.records[index].id)
+      && current.draggedPaths.join('\0') === preview.draggedPaths.join('\0') ? current : preview);
+  }, []);
+  const onTableDropReject = useCallback((reason: TableNoteDropTargetRejection) => {
+    if (reason === 'unsupported-resource' || reason === 'wrong-notebook' || reason === 'unavailable') {
+      toast.warning(t('memo.fileTree.tableDropUnsupported'));
+    } else if (reason === 'read-only') {
+      toast.warning(t('multidimensionalTable.tableDropReadOnly'));
+    } else if (reason === 'filtered') {
+      toast.warning(t('multidimensionalTable.tableDropFiltered'));
+    }
+  }, [t]);
+  useTableNoteDropTarget({
+    id: `table:${tableDropTargetId}`,
+    active: activeView?.layout === 'table',
+    notebookId: resolvedNotebookId,
+    canDrop: editable && !saving,
+    canHandleDrop: true,
+    hitTest: ({ x, y }) => {
+      const area = recordsScrollerRef.current;
+      if (!area) return null;
+      const bounds = area.getBoundingClientRect();
+      if (x < bounds.left || x > bounds.right || y < bounds.top || y > bounds.bottom) return null;
+      const rows = [...(tableDropAreaRef.current?.querySelectorAll<HTMLElement>('tbody tr[data-table-record]') ?? [])]
+        .filter((candidate) => {
+          const rowBounds = candidate.getBoundingClientRect();
+          return rowBounds.bottom > bounds.top && rowBounds.top < bounds.bottom;
+        });
+      if (!rows.length) return { beforeRecordId: null };
+      const row = rows.reduce((nearest, candidate) => {
+        const rowBounds = candidate.getBoundingClientRect();
+        const nearestBounds = nearest.getBoundingClientRect();
+        return Math.abs(y - (rowBounds.top + rowBounds.height / 2))
+          < Math.abs(y - (nearestBounds.top + nearestBounds.height / 2)) ? candidate : nearest;
+      });
+      const index = rows.indexOf(row);
+      const rowBounds = row.getBoundingClientRect();
+      const insertAfter = y >= rowBounds.top + rowBounds.height / 2;
+      return {
+        beforeRecordId: rows[index + (insertAfter ? 1 : 0)]?.dataset.tableRecord
+          ?? (insertAfter ? nextTableRecordId : null),
+      };
+    },
+    locationKey: ({ beforeRecordId }) => beforeRecordId ?? 'end',
+    preview: previewTableDrop,
+    onPreview: onTableDropPreview,
+    onDrop: (notes, location) => addExternalNotesToTable(notes, location.beforeRecordId),
+    onReject: onTableDropReject,
+    onError: (error) => toast.error(error instanceof Error ? error.message : t('multidimensionalTable.tableDropFailed')),
+  });
 
-  const linkCalendarNote = useCallback(async (note: NoteEntry) => {
-    if (!editable || !document || !noteField || !calendarAddDate || saving) return;
+  const addExternalNotesToCalendar = useCallback(async (
+    draggedNotes: NotebookNoteDragResource[],
+    date: string,
+  ) => {
+    if (!editable || !document || !noteField || !notebookPath || !calendarDateFieldId
+      || !calendarField || calendarField.type !== 'Date' || saving) return;
     const sequence = loadSequenceRef.current;
+    const uniqueNotes = [...new Map(draggedNotes.map((note) => [canonicalPath(note.relativePath), note])).values()];
+    const resolved = uniqueNotes.map((draggedNote) => {
+      if (!isMarkdownNoteDragResource(draggedNote) || draggedNote.notebookId !== resolvedNotebookId) return null;
+      const relativePath = canonicalPath(draggedNote.relativePath).replace(/^\/+/, '');
+      const note = notes.find((item) => item.relativePath.replace(/\\/g, '/') === relativePath);
+      if (!note || !noteInCollectionSource(relativePath, document.dataset.source, currentFilePath, notebookPath)) return null;
+      return { note, relativePath };
+    });
+    if (!resolved.length || resolved.some((item) => !item)) {
+      toast.warning(t('memo.fileTree.calendarDropUnsupported'));
+      return;
+    }
+    if (!isCurrentSession(sequence)) return;
     setSaving(true);
     try {
-      await persistCalendarNote(note, calendarAddDate, sequence);
+      for (const item of resolved) {
+        if (!item || !isCurrentSession(sequence)) return;
+        const datedNote = await applyCalendarDateToNote(item.note, { fieldId: calendarDateFieldId, date });
+        if (!isCurrentSession(sequence)) return;
+        setNotes((current) => current.map((note) => (
+          note.relativePath.replace(/\\/g, '/') === item.relativePath ? datedNote : note
+        )));
+      }
+
+      let records = [...document.dataset.records.include];
+      const now = new Date().toISOString();
+      for (const item of resolved) {
+        if (!item) continue;
+        const existing = datasetRecords.find((record) => record.note_path.replace(/\\/g, '/') === item.relativePath);
+        const linkedRecord = existing
+          ? { ...existing, updated_at: now, note_path: item.relativePath }
+          : { id: `rec_${createUuidV7()}`, updated_at: now, note_path: item.relativePath };
+        records = upsertTableRecord(records, linkedRecord);
+      }
+      const next: MultidimensionalTableDocument = {
+        ...document,
+        collection: reviseCollection(document.collection),
+        dataset: { ...document.dataset, records: { ...document.dataset.records, include: records } },
+      };
+      if (!await save(next, true, sequence) || !isCurrentSession(sequence)) {
+        toast.error('日历关联未保存，请重试');
+        return;
+      }
+    } catch (error) {
+      if (isCurrentSession(sequence)) toast.error(error instanceof Error ? error.message : '加入日历失败');
+    } finally {
+      if (isCurrentSession(sequence)) setSaving(false);
+    }
+  }, [applyCalendarDateToNote, calendarDateFieldId, calendarField, currentFilePath, datasetRecords, document, editable, isCurrentSession, loadSequenceRef, noteField, notes, notebookPath, resolvedNotebookId, save, saving, setNotes, setSaving, t]);
+
+  const createCalendarNote = useCallback(async () => {
+    const title = calendarAddTitle.trim();
+    if (!editable || !document || !noteField || !resolvedNotebookId || !calendarAddDate || !title || saving) return;
+    const sequence = loadSequenceRef.current;
+    setSaving(true);
+    try {
+      let pending = calendarPendingCreatedNoteRef.current;
+      if (!pending || pending.title !== title) {
+        const created = await createNoteInNotebook(title);
+        if (!isCurrentSession(sequence)) return;
+        pending = { title, entry: created.entry };
+        calendarPendingCreatedNoteRef.current = pending;
+      }
+      let note = await applyCalendarDateToNote(pending.entry, calendarAddDate);
+      if (!isCurrentSession(sequence)) return;
+      const properties: Record<string, unknown> = {};
+      const types: Record<string, PropertyKind | null | undefined> = {};
+      for (const field of calendarCreateFields) {
+        if (field.type === 'primary' || !field.property_key) continue;
+        const property = calendarCreatePropertyValue(field, calendarCreatePropertyValues[field.id]);
+        if (!property.include) continue;
+        properties[field.property_key] = property.value;
+        types[field.property_key] = field.type;
+      }
+      if (Object.keys(properties).length) {
+        const path = notebookPath ? joinNotebookMemoPath(notebookPath, note.relativePath) : null;
+        if (!path || !await setDocumentProperties(path, properties, types)) throw new Error('笔记属性未能保存');
+        note = { ...note, updatedAt: Date.now(), properties: { ...note.properties, ...properties } };
+      }
+      const saved = await persistCalendarNote(note, null, sequence);
+      if (saved && calendarPendingCreatedNoteRef.current?.entry.relativePath === pending.entry.relativePath) {
+        calendarPendingCreatedNoteRef.current = null;
+      }
     } catch (error) {
       reportSaveFailure(sequence);
-      toast.error(error instanceof Error ? error.message : '关联笔记失败');
+      toast.error(error instanceof Error ? error.message : '新建并关联笔记失败');
     } finally {
       if (isCurrentSession(sequence)) setSaving(false);
     }
-  }, [calendarAddDate, document, editable, isCurrentSession, loadSequenceRef, noteField, persistCalendarNote, saving, setSaving, reportSaveFailure]);
+  }, [applyCalendarDateToNote, calendarAddDate, calendarAddTitle, calendarCreateFields, calendarCreatePropertyValues, createNoteInNotebook, document, editable, isCurrentSession, loadSequenceRef, noteField, notebookPath, persistCalendarNote, resolvedNotebookId, saving, setSaving, reportSaveFailure]);
 
   const addField = useCallback(async (preset?: PropertyPreset) => {
     if (!document || saving) return;
@@ -1344,7 +1767,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     if (keyChanged) {
       const normalized = canonicalizePropertyKey(name).toLowerCase();
       if (isSystemPropertyKey(propertyKey) || isSystemPropertyKey(name)
-        || !name || ['flowix_key', 'key', 'flowix_property_types', 'flowix_plugin'].includes(normalized)) {
+        || !name || ['flowix_property_types', 'flowix_plugin'].includes(normalized)) {
         toast.error('系统预设或保留名称不能修改属性名称');
         return false;
       }
@@ -1532,7 +1955,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
       || isSystemPropertyKey(field.property_key ?? '')) return false;
     const propertyKey = preset.key.trim();
     const normalizedKey = canonicalizePropertyKey(propertyKey).toLocaleLowerCase();
-    if (!propertyKey || normalizedKey === 'flowix_key' || normalizedKey === 'key' || normalizedKey === 'flowix_property_types'
+    if (!propertyKey || normalizedKey === 'flowix_property_types'
       || document.dataset.schema.fields.some((item) => item.id !== field.id && item.property_key
         && canonicalizePropertyKey(item.property_key).toLocaleLowerCase() === normalizedKey)) {
       toast.error('属性键已存在或属于保留名称');
@@ -1566,7 +1989,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     const preset = registry.fields.find((item) => item.id === field.id);
     if (!preset) {
       const dependentViews = viewsRequiringField(document, field.id);
-      if (dependentViews.length || collectionFilterUsesField(document.dataset.filter as unknown as CollectionRuleFilter | null, field.id)) {
+      if (dependentViews.length || collectionFilterUsesField(document.dataset.filter as unknown as DatasetFilter | null, field.id)) {
         toast.error('请先调整依赖此属性的视图或笔记数据集');
         return false;
       }
@@ -1602,7 +2025,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     const record = visibleRecords.find((item) => item.id === recordId);
     if (!record) return;
     const primaryField = document.dataset.schema.fields[0];
-    const datasetFilter = document.dataset.filter;
+    const datasetFilter = resolveDatasetFilterForLocation(document.dataset.filter, document.collection.placement, currentFilePath, notebookPath);
     let nextDocument = document;
     const note = record ? noteForRecord(record) : undefined;
     const ruleMatch = primaryField && record && note
@@ -1624,7 +2047,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
       dataset: { ...nextDocument.dataset, records: { ...nextDocument.dataset.records, include: document.dataset.records.include.filter((item) => item.id !== recordId) } },
     };
     void save(next);
-  }, [document, noteForRecord, save, saving, visibleRecords]);
+  }, [currentFilePath, document, notebookPath, noteForRecord, save, saving, visibleRecords]);
 
   const updateRecordField = useCallback((recordId: string, fieldId: string, value: unknown) => {
     if (!document) return;
@@ -1687,6 +2110,90 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     }
   }, [editable, isCurrentSession, loadSequenceRef, notebookPath, saving, setNotes, reportSaveFailure, setSaving]);
 
+  const closeCalendarNoteDialog = useCallback(() => {
+    calendarPendingCreatedNoteRef.current = null;
+    setCalendarEditingRecord(null);
+    closeCalendarAddPopover();
+  }, [closeCalendarAddPopover]);
+
+  const openCalendarEditPopover = useCallback((recordId: string, anchorRect: DOMRect) => {
+    const record = visibleRecords.find((item) => item.id === recordId);
+    const note = record ? noteForRecord(record) : undefined;
+    if (!record || !note) {
+      toast.warning('无法找到这篇笔记');
+      return;
+    }
+    if (!editable) {
+      toast.warning('当前多维表格为只读状态');
+      return;
+    }
+    const dateValue = calendarDateMetadata
+      ? calendarDateTimeForTimestamp(note[calendarDateMetadata.timestamp])
+      : calendarField ? notePropertyEditorValue(note, calendarField) : null;
+    const date = calendarDateKey(dateValue) ?? isoDate(new Date());
+    setCalendarEditingRecord(record);
+    setCalendarCreatePropertyValues(Object.fromEntries(calendarCreateFields.map((field) => {
+      const value = notePropertyEditorValue(note, field);
+      return [field.id, value ?? (field.type === 'Boolean' ? false : field.type === 'MultiSelect' || field.type === 'Tag' || field.type === 'Color' || (field.type === 'Image' && field.multiple) ? [] : '')];
+    })));
+    openCalendarAddDialog(date, anchorRect, calendarDateFieldId ?? '');
+    setCalendarAddTitle(note.title);
+  }, [calendarCreateFields, calendarDateFieldId, calendarDateMetadata, calendarField, editable, noteForRecord, openCalendarAddDialog, setCalendarAddTitle, visibleRecords]);
+
+  const saveCalendarNoteEdit = useCallback(async () => {
+    const record = calendarEditingRecord;
+    const initialNote = record ? noteForRecord(record) : undefined;
+    const title = calendarAddTitle.trim();
+    if (!record || !initialNote || !editable || !document || !title || saving) return;
+    const sequence = loadSequenceRef.current;
+    try {
+      const note = title === initialNote.title ? initialNote : await renameLinkedNote(record.id, initialNote, title);
+      if (!note || !isCurrentSession(sequence)) return;
+      if (note.relativePath.replace(/\\/g, '/') !== record.note_path.replace(/\\/g, '/')) {
+        setCalendarEditingRecord((current) => current?.id === record.id
+          ? { ...current, note_path: note.relativePath.replace(/\\/g, '/') }
+          : current);
+      }
+      if (!notebookPath) throw new Error('无法确定笔记路径');
+      const path = joinNotebookMemoPath(notebookPath, note.relativePath);
+      if (!path) throw new Error('无法确定笔记路径');
+      const expected: Record<string, { exists: boolean; value?: unknown }> = {};
+      const next: Record<string, { exists: boolean; value?: unknown }> = {};
+      const types: Record<string, PropertyKind> = {};
+      for (const field of calendarCreateFields) {
+        if (!field.property_key) continue;
+        const key = field.property_key;
+        const property = calendarCreatePropertyValue(field, calendarCreatePropertyValues[field.id]);
+        expected[key] = {
+          exists: Object.prototype.hasOwnProperty.call(note.properties, key),
+          value: note.properties[key],
+        };
+        next[key] = property.include ? { exists: true, value: property.value } : { exists: false };
+        types[key] = field.type as PropertyKind;
+      }
+      setSaving(true);
+      const saved = Object.keys(next).length
+        ? await compareAndPatchDocumentProperties(path, expected, next, types)
+        : true;
+      if (!saved) throw new Error('笔记属性未能保存');
+      if (!isCurrentSession(sequence)) return;
+      const properties = { ...note.properties };
+      for (const [key, state] of Object.entries(next)) {
+        if (state.exists) properties[key] = state.value;
+        else delete properties[key];
+      }
+      setNotes((current) => current.map((item) => item.relativePath.replace(/\\/g, '/') === note.relativePath.replace(/\\/g, '/')
+        ? { ...note, updatedAt: Date.now(), properties }
+        : item));
+      closeCalendarNoteDialog();
+    } catch (error) {
+      reportSaveFailure(sequence);
+      toast.error(error instanceof Error ? error.message : '编辑笔记失败');
+    } finally {
+      if (isCurrentSession(sequence)) setSaving(false);
+    }
+  }, [calendarAddTitle, calendarCreateFields, calendarCreatePropertyValues, calendarEditingRecord, closeCalendarNoteDialog, document, editable, isCurrentSession, loadSequenceRef, noteForRecord, notebookPath, renameLinkedNote, reportSaveFailure, saving, setCalendarEditingRecord, setNotes, setSaving]);
+
   const renameKanbanRecord = useCallback(async (recordId: string, title: string) => {
     const record = visibleRecords.find((item) => item.id === recordId);
     const note = record ? noteForRecord(record) : undefined;
@@ -1698,10 +2205,11 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   const openLinkedNote = useCallback((note: NoteEntry) => {
     if (!notebookPath) return;
     const path = joinNotebookMemoPath(notebookPath, note.relativePath);
-    if (path) void openBrowserColumnTarget({
-      ...createFileBrowserTarget(path, notebookPath),
-      notebookId: resolvedNotebookId,
-    }, 'open-in-column');
+    if (path) void openWorkspaceSurface({
+      host: 'browser-column',
+      target: { ...createFileBrowserTarget(path, notebookPath), notebookId: resolvedNotebookId },
+      options: { browserDisposition: 'open-in-column' },
+    });
   }, [notebookPath, notebookId, resolvedNotebookId]);
   const openLinkedRecord = useCallback((recordId: string) => {
     const record = visibleRecords.find((item) => item.id === recordId);
@@ -1778,9 +2286,6 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
 
   const groupFieldId = activeView?.layout === 'kanban' && typeof activeView.config.group_by === 'string' ? activeView.config.group_by : null;
   const groupField = groupFieldId ? document?.dataset.schema.fields.find((field) => field.id === groupFieldId) : undefined;
-  const calendarField = calendarDateFieldId && !calendarDateMetadata
-    ? document?.dataset.schema.fields.find((field) => field.id === calendarDateFieldId) ?? builtinPresetTableField(calendarDateFieldId) ?? undefined
-    : undefined;
   const calendarDateFieldOptions = [
     ...NOTE_CALENDAR_DATE_FIELDS.map(({ id, label }) => ({ id, label, readOnly: true })),
     ...(document?.dataset.schema.preset_fields.includes(NOTE_CALENDAR_DATE_FIELD_ID) ? [{ id: NOTE_CALENDAR_DATE_FIELD_ID, label: '日期' }] : []),
@@ -1870,6 +2375,103 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
       if (isCurrentSession(sequence)) setSaving(false);
     }
   }, [createNoteInNotebook, datasetRecords, document, editable, groupField, isCurrentSession, loadSequenceRef, noteField, noteForRecord, notebookPath, reportSaveFailure, resolvedNotebookId, save, saving, setNotes, setSaving]);
+  const addExternalNotesToKanban = useCallback(async (
+    draggedNotes: NotebookNoteDragResource[],
+    targetGroupId: string,
+    beforeRecordId: string | null,
+  ) => {
+    if (!editable || !document || !noteField || !notebookPath || !resolvedNotebookId
+      || groupField?.type !== 'Select' || saving) return;
+    const targetIsUnassigned = targetGroupId === KANBAN_UNASSIGNED_GROUP_ID;
+    const targetOption = groupField.options?.find((option) => option.id === targetGroupId);
+    if (!targetIsUnassigned && !targetOption) return;
+    if (!targetIsUnassigned && !groupField.property_key) {
+      toast.error('状态字段未配置属性键，无法加入任务');
+      return;
+    }
+    const uniqueNotes = [...new Map(draggedNotes.map((note) => [canonicalPath(note.relativePath), note])).values()];
+    const resolved = uniqueNotes.map((draggedNote) => {
+      if (!isMarkdownNoteDragResource(draggedNote) || draggedNote.notebookId !== resolvedNotebookId) return null;
+      const relativePath = canonicalPath(draggedNote.relativePath).replace(/^\/+/, '');
+      const note = notes.find((item) => item.relativePath.replace(/\\/g, '/') === relativePath);
+      if (!note || !noteInCollectionSource(relativePath, document.dataset.source, currentFilePath, notebookPath)) return null;
+      return { note, relativePath };
+    });
+    if (!resolved.length || resolved.some((item) => !item)) {
+      toast.warning(t('memo.fileTree.kanbanDropUnsupported'));
+      return;
+    }
+    const sequence = loadSequenceRef.current;
+    if (!isCurrentSession(sequence)) return;
+    setSaving(true);
+    try {
+      for (const item of resolved) {
+        if (!item || !isCurrentSession(sequence)) return;
+        const path = joinNotebookMemoPath(notebookPath, item.relativePath);
+        if (!path) throw new Error('无法确定笔记路径');
+        if (groupField.property_key) {
+          const saved = targetOption
+            ? await setDocumentProperties(path, { [groupField.property_key]: targetOption.label }, { [groupField.property_key]: 'Select' })
+            : !Object.prototype.hasOwnProperty.call(item.note.properties, groupField.property_key)
+              || await removeDocumentProperty(path, groupField.property_key);
+          if (!saved) throw new Error('笔记的分组属性未能保存');
+        }
+        if (!isCurrentSession(sequence)) return;
+        setNotes((current) => current.map((note) => {
+          if (note.relativePath.replace(/\\/g, '/') !== item.relativePath) return note;
+          const properties = { ...note.properties };
+          if (groupField.property_key) {
+            if (targetOption) properties[groupField.property_key] = targetOption.label;
+            else delete properties[groupField.property_key];
+          }
+          return { ...note, properties };
+        }));
+      }
+
+      const linkedRecords: TableRecord[] = [];
+      const now = new Date().toISOString();
+      for (const item of resolved) {
+        if (!item) continue;
+        const existing = datasetRecords.find((record) => record.note_path.replace(/\\/g, '/') === item.relativePath);
+        const linkedRecord = existing
+          ? { ...existing, updated_at: now, note_path: item.relativePath }
+          : { id: `rec_${createUuidV7()}`, updated_at: now, note_path: item.relativePath };
+        linkedRecords.push(linkedRecord);
+      }
+      const linkedIds = new Set(linkedRecords.map((record) => record.id));
+      const recordsWithoutDropped = document.dataset.records.include.filter((record) => !linkedIds.has(record.id));
+      let insertAt = beforeRecordId
+        ? recordsWithoutDropped.findIndex((record) => record.id === beforeRecordId)
+        : -1;
+      if (insertAt < 0) {
+        const targetRecords = (targetGroupId === KANBAN_UNASSIGNED_GROUP_ID
+          ? kanbanUnassignedRecords
+          : kanbanGroups.get(targetGroupId) ?? []).filter((record) => !linkedIds.has(record.id));
+        const lastTargetRecord = targetRecords[targetRecords.length - 1];
+        const lastTargetIndex = lastTargetRecord
+          ? recordsWithoutDropped.findIndex((record) => record.id === lastTargetRecord.id)
+          : -1;
+        insertAt = lastTargetIndex >= 0 ? lastTargetIndex + 1 : recordsWithoutDropped.length;
+      }
+      const records = [
+        ...recordsWithoutDropped.slice(0, insertAt),
+        ...linkedRecords,
+        ...recordsWithoutDropped.slice(insertAt),
+      ];
+      const next: MultidimensionalTableDocument = {
+        ...document,
+        collection: reviseCollection(document.collection),
+        dataset: { ...document.dataset, records: { ...document.dataset.records, include: records } },
+      };
+      if (!await save(next, true, sequence) || !isCurrentSession(sequence)) {
+        toast.error(t('multidimensionalTable.kanbanDropFailed'));
+      }
+    } catch (error) {
+      if (isCurrentSession(sequence)) toast.error(error instanceof Error ? error.message : t('multidimensionalTable.kanbanDropFailed'));
+    } finally {
+      if (isCurrentSession(sequence)) setSaving(false);
+    }
+  }, [currentFilePath, datasetRecords, document, editable, groupField, isCurrentSession, kanbanGroups, kanbanUnassignedRecords, loadSequenceRef, noteField, notes, notebookPath, resolvedNotebookId, save, saving, setNotes, setSaving, t]);
   const dropKanbanRecord = useCallback(async (recordId: string, targetGroupId: string, beforeRecordId: string | null) => {
     if (!editable || !document || groupField?.type !== 'Select' || saving) return;
     const record = visibleRecords.find((item) => item.id === recordId);
@@ -2015,9 +2617,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
       ]
       : [];
   const showAssociateNoteButton = canCreateRecords || showAssociateNoteAction;
-  const tableDisplayName = document.collection.placement === 'folder'
-    ? currentFilePath.replace(/[\\/]+$/, '').replace(/[\\/][^\\/]*$/, '').split(/[\\/]/).pop() || document.collection.name
-    : document.collection.name;
+  const tableDisplayName = collectionDisplayName(currentFilePath, document.collection.placement);
   const cellSaveStatuses = [...cellStatusesByRecord.values()].flatMap((statuses) => [...statuses.values()]);
   const isSaving = saving || renamingTable || cellSaveStatuses.some((status) => status.saving);
   const saveStatusText = saveFailed || cellSaveStatuses.some((status) => status.error) ? '未保存' : '已保存';
@@ -2051,14 +2651,18 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
     return Boolean(builtin && document.dataset.schema.preset_fields.includes(builtin.id));
   };
   const isSystemPresetField = (field: TableField) => tablePresets.system.some((preset) => preset.id === field.id);
+  const fixedFolderPath = document.collection.placement === 'folder'
+    ? resolveTableNoteParentRelativePath(currentFilePath, notebookPath) ?? ''
+    : undefined;
+  const storedAutoCollectConfig = tableAutoCollectConfig(document);
   const datasetMenuProps = {
     defaultFieldId: document.dataset.schema.primary_field_id,
     fields: document.dataset.schema.fields.map((item) => ({ id: item.id, label: fieldLabel(item, propertyFields, t) })),
-    config: tableAutoCollectConfig(document),
+    config: fixedFolderPath !== undefined
+      ? { condition: { ...(storedAutoCollectConfig?.condition ?? {}), match: storedAutoCollectConfig?.condition.match ?? 'all', path: fixedFolderPath } }
+      : storedAutoCollectConfig,
     notebookPath,
-    fixedFolderPath: document.collection.placement === 'folder'
-      ? resolveTableNoteParentRelativePath(currentFilePath, notebookPath) ?? ''
-      : undefined,
+    fixedFolderPath,
     saving: saving || !editable,
     t,
     onSave: (condition: TableAutoCollectCondition) => saveAutoCollectCondition(document.dataset.schema.fields[0], condition),
@@ -2110,7 +2714,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
   };
   const datasetAction = <div className="flex shrink-0 items-center gap-2">
     <span role="status" aria-label={isSaving ? '保存中' : saveStatusText} className="inline-flex items-center whitespace-nowrap text-xs text-[var(--muted-foreground)]">
-      {isSaving ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" aria-hidden="true" /> : saveStatusText}
+      {isSaving ? <LoaderCircle className="h-3.5 w-3.5 flowix-spin" aria-hidden="true" /> : saveStatusText}
     </span>
     <TableDatasetMenu
       {...datasetMenuProps}
@@ -2254,7 +2858,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
       onConfirm={() => { void confirmDeleteField(); }}
     />
     <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
-      <nav className="multidimensional-table__view-nav sticky top-0 z-10 flex min-w-0 shrink-0 items-center gap-1 px-4 py-1" aria-label="表格视图">
+      <nav data-title-visible={showTableTitle} className="multidimensional-table__view-nav sticky top-0 z-10 flex min-w-0 shrink-0 items-center gap-1 px-4 py-1" aria-label="表格视图">
         <div
           className="multidimensional-table__view-title flex min-w-0 max-w-[40%] shrink-0 -translate-x-[2px] items-center gap-1.5"
           title={tableDisplayName}
@@ -2295,7 +2899,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
               {tableDisplayName}
             </button>}
             {renamingTable && <span role="status" aria-label={t('memo.fileTree.renaming')} className="inline-flex shrink-0 items-center text-[var(--muted-foreground)]">
-              <LoaderCircle className="h-3.5 w-3.5 animate-spin" aria-hidden="true" />
+              <LoaderCircle className="h-3.5 w-3.5 flowix-spin" aria-hidden="true" />
             </span>}
         </div>
         <span role="separator" aria-orientation="vertical" className="multidimensional-table__view-nav-separator" />
@@ -2339,7 +2943,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
               )}
               <ContextMenuContent className="w-[160px] space-y-0.5 rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
                 <ContextMenuItem disabled={!editable || saving} onSelect={() => beginRenameView(view)}>{t('multidimensionalTable.view.rename')}</ContextMenuItem>
-                <ContextMenuItem disabled={!editable || !canDeleteViews || saving || document.views.items.length <= 1} className="text-[var(--destructive)]" onSelect={() => void deleteView(view)}>{t('multidimensionalTable.view.delete')}</ContextMenuItem>
+                <ContextMenuItem disabled={!editable || !canDeleteViews || saving || document.views.items.length <= 1} className="text-[var(--destructive)]" onSelect={() => requestDeleteView(view)}>{t('multidimensionalTable.view.delete')}</ContextMenuItem>
               </ContextMenuContent>
             </ContextMenu>
           ))}
@@ -2369,7 +2973,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
                   <DotsThreeIcon size={16} weight="bold" aria-hidden="true" />
                 </button>
               </PopoverTrigger>
-              <PopoverContent key={viewAddStep} align="start" side="bottom" sideOffset={5} fitViewport className={`${viewAddStep === 'manage' ? 'w-[220px]' : 'w-[160px]'} rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]`}>
+              <PopoverContent key={viewAddStep} align="start" side="bottom" sideOffset={5} fitViewport className={`${viewAddStep === 'manage' ? 'w-[220px]' : 'w-[190px]'} rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]`}>
                 {viewAddStep === 'kind' ? <div className="space-y-0.5">
                   <div className="px-2 py-1 text-xs text-[var(--muted-foreground)]">添加笔记视图</div>
                   <button type="button" disabled={saving} onClick={() => void createDataTableView()} className="flex h-8 w-full items-center rounded-lg px-2 text-left text-sm hover:bg-[var(--hover-bg)] disabled:opacity-50">表格</button>
@@ -2383,22 +2987,34 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
                     画廊
                   </button>
                   {document.collection.placement === 'folder' && <>
-                    <div className="px-2 py-1 text-xs text-[var(--muted-foreground)]">添加图/视频视图</div>
                     <button type="button" disabled={saving || !notebookPath || !notebookId} onClick={() => {
                       setViewAddOpen(false);
                       setFolderMediaSwitchConfirmOpen(true);
-                    }} className="flex h-8 w-full items-center rounded-lg px-2 text-left text-sm hover:bg-[var(--hover-bg)] disabled:opacity-50">
-                      媒体库
+                    }} className="flex h-8 w-full items-center justify-between rounded-lg px-2 text-left text-sm hover:bg-[var(--hover-bg)] disabled:opacity-50">
+                      <span>媒体库</span>
+                      <span className="text-xs text-[var(--muted-foreground)]">图/视频</span>
                     </button>
                   </>}
                   <div role="separator" aria-hidden="true" className="mx-2 my-1 h-px bg-[var(--border)]" />
-                  <button type="button" disabled={saving} onClick={() => setViewAddStep('manage')} className="flex h-8 w-full items-center rounded-lg px-2 text-left text-sm hover:bg-[var(--hover-bg)] disabled:opacity-50">
-                    管理视图
+                  <button type="button" disabled={saving} onClick={() => setViewAddStep('manage')} className="flex h-8 w-full items-center justify-between rounded-lg px-2 text-left text-sm hover:bg-[var(--hover-bg)] disabled:opacity-50">
+                    <span>管理视图</span>
+                    <ChevronRight className="h-3.5 w-3.5 text-[var(--muted-foreground)]" aria-hidden="true" />
+                  </button>
+                  <button type="button" aria-label={showTableTitle ? '隐藏标题' : '显示标题'} aria-pressed={showTableTitle} onClick={toggleTableTitleVisibility} className="flex h-8 w-full items-center justify-between rounded-lg px-2 text-left text-sm hover:bg-[var(--hover-bg)]">
+                    <span>显示标题</span>
+                    {showTableTitle
+                      ? <EyeIcon size={16} weight="bold" className="text-[var(--brand)]" aria-hidden="true" />
+                      : <EyeSlashIcon size={16} weight="bold" className="text-[var(--muted-foreground)]" aria-hidden="true" />}
                   </button>
                 </div> : viewAddStep === 'manage' ? <div className="space-y-0.5">
-                  <div className="px-2 py-1 text-xs text-[var(--muted-foreground)]">管理视图</div>
+                  <div className="flex min-w-0 items-center gap-0.5 px-1.5 py-[0.35rem]">
+                    <button type="button" aria-label="返回视图类型" className="inline-flex min-h-4 shrink-0 items-center gap-0.5 rounded px-0 text-xs leading-[1.2] text-[var(--muted-foreground)] hover:text-[var(--foreground)] focus-visible:outline-none" onClick={() => setViewAddStep('kind')}>
+                      <ChevronLeft className="h-3.5 w-3.5" aria-hidden="true" />
+                      <span className="min-w-0 truncate text-xs leading-[1.2] text-[var(--muted-foreground)]">管理视图</span>
+                    </button>
+                  </div>
                   <div className="max-h-[min(60vh,420px)] space-y-0.5 overflow-y-auto">
-                    {document.views.items.map((view) => <div key={view.id} className="flex h-8 min-w-0 items-center gap-1 rounded-lg px-1 hover:bg-[var(--hover-bg)]">
+                    {document.views.items.map((view) => <div key={view.id} className="flex h-8 w-full min-w-0 items-center gap-1 rounded-lg px-1">
                       {managingViewId === view.id ? <input
                         ref={manageViewRenameInputRef}
                         aria-label={`重命名视图：${view.name}`}
@@ -2424,12 +3040,18 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
                         }}
                         className="h-7 min-w-0 flex-1 rounded-md border border-[var(--primary)] bg-[var(--background)] px-2 text-sm text-[var(--foreground)] outline-none"
                       /> : <span className="min-w-0 flex-1 truncate px-1.5 text-sm text-[var(--foreground)]">{view.name}</span>}
-                      <button type="button" aria-label={`重命名视图：${view.name}`} title="重命名" disabled={!editable || saving || managingViewId !== null} onClick={() => beginManageViewRename(view)} className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:opacity-40">
+                      {managingViewId === view.id ? <button
+                        type="button"
+                        disabled={!editable || saving}
+                        onMouseDown={(event) => event.preventDefault()}
+                        onClick={() => finishManageViewRename(view, managingViewName)}
+                        className="inline-flex h-7 w-11 shrink-0 items-center justify-center rounded-md border border-[var(--border)] bg-[var(--background)] text-xs text-[var(--primary)] hover:bg-[var(--muted)] disabled:opacity-40"
+                      >保存</button> : <button type="button" aria-label={`重命名视图：${view.name}`} title="重命名" disabled={!editable || saving || managingViewId !== null} onClick={() => beginManageViewRename(view)} className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:opacity-40">
                         <PencilSimpleIcon size={15} aria-hidden="true" />
-                      </button>
-                      <button type="button" aria-label={`删除视图：${view.name}`} title={canDeleteViews ? '删除' : '此处不可删除视图'} disabled={!editable || !canDeleteViews || saving || document.views.items.length <= 1 || managingViewId !== null} onClick={() => void deleteView(view)} className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--destructive)] disabled:opacity-40">
+                      </button>}
+                      {managingViewId !== view.id && <button type="button" aria-label={`删除视图：${view.name}`} title={canDeleteViews ? '删除' : '此处不可删除视图'} disabled={!editable || !canDeleteViews || saving || document.views.items.length <= 1 || managingViewId !== null} onClick={() => requestDeleteView(view)} className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--destructive)] disabled:opacity-40">
                         <TrashIcon size={15} aria-hidden="true" />
-                      </button>
+                      </button>}
                     </div>)}
                   </div>
                 </div> : <div className="space-y-0.5">
@@ -2476,7 +3098,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         {!embeddedInEditor && datasetAction}
         {trailingActions ? trailingActions(datasetAction) : embeddedInEditor ? datasetAction : null}
       </nav>
-      <OverlayScrollbar scrollerRef={recordsScrollerRef} horizontalScrollbar={activeView?.layout === 'table' || activeView?.layout === 'kanban'} className={`multidimensional-table__scrollbar--bottom-clearance min-h-0 ${activeView?.layout === 'table' && !embeddedInEditor ? 'flex flex-col flex-[0_1_auto]' : 'flex-1'}`} scrollerClassName={`min-h-0 flex flex-col ${activeView?.layout === 'table' && !embeddedInEditor ? 'flex-[0_1_auto]' : 'h-full'}`} onScroll={() => {
+      <OverlayScrollbar scrollerRef={recordsScrollerRef} horizontalScrollbar={activeView?.layout === 'table' || activeView?.layout === 'kanban'} className="multidimensional-table__scrollbar--bottom-clearance min-h-0 flex-1" scrollerClassName="min-h-0 flex h-full flex-col" onScroll={() => {
         window.dispatchEvent(new Event('flowix:multidimensional-table-scroll'));
         setHeaderMenuFieldId(null);
         setNewFieldOpen(false);
@@ -2490,7 +3112,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         setNotePickerCalendarDate(null);
         closeCalendarAddPopover();
       }}>
-      {activeView?.layout === 'table' && <div className={`min-w-0 w-full ${embeddedInEditor ? 'flex-1' : 'shrink-0'} pr-4 ${embeddedInEditor ? '' : 'pl-4'}`}>
+      {activeView?.layout === 'table' && <div ref={tableDropAreaRef} className={`relative min-w-0 w-full ${embeddedInEditor ? 'flex-1' : 'shrink-0'} pr-4 ${embeddedInEditor ? '' : 'pl-4'}`}>
         <table ref={tableElementRef} className="multidimensional-table table-fixed border-collapse text-sm" style={{ width: '100%', minWidth: tableMinWidth }}>
           <colgroup>
             {orderedTableWidths.map(({ fieldId, width }) => <col key={fieldId} style={{ width }} />)}
@@ -2577,13 +3199,15 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
               ><Plus className="h-4 w-4" aria-hidden="true" /></button>}
             </th></tr>
           </thead>
-          <tbody>{visibleTableRecords.map((record) => {
+          <tbody>{renderedTableRecords.map((record) => {
             const noteKey = noteKeyForRecord(record);
             const note = noteKey ? noteByKey.get(noteKey) : undefined;
             const noteStatus = !noteKey ? 'draft' : note ? 'linked' : notesLoadError ? 'unknown' : 'missing';
+            const isDropPreview = tableDropPreview?.draggedPaths.includes(record.note_path.replace(/\\/g, '/')) ?? false;
             return <TableRecordRow
               key={record.id}
               record={record}
+              isDropPreview={isDropPreview}
               showBottomBorder
               imagePaths={imagePaths}
               notePropertyEditorValue={notePropertyEditorValue}
@@ -2616,7 +3240,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
               onRowActionOpenChange={handleRowActionOpenChange}
             />;
           })}
-          {visibleRecords.length === 0 && (
+          {renderedTableRecords.length === 0 && (
             <tr>
               <td colSpan={tableColumnCount} className="border-b border-[var(--border)] px-4 py-3 text-center text-sm text-[var(--muted-foreground)]">
                 添加数据后查看
@@ -2626,6 +3250,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
           </tbody>
         </table>
       </div>}
+      {activeView?.layout === 'table' && <TableNoteDropOverlay active={Boolean(tableDropPreview)} dropAreaRef={recordsScrollerRef} />}
       {activeView?.layout === 'kanban' && groupField?.type === 'Select' && <TableKanbanView
         embeddedInEditor={embeddedInEditor}
         groupField={groupField}
@@ -2634,7 +3259,11 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         groups={kanbanGroups}
         renderValue={displayFieldValue}
         recordStatus={noteStatusForRecord}
+        noteIconForRecord={noteIconForRecord}
         onDropRecord={dropKanbanRecord}
+        dropNotebookId={resolvedNotebookId}
+        canDropExternal={editable && !saving && Boolean(document && noteField && notebookPath && resolvedNotebookId)}
+        onExternalNoteDrop={addExternalNotesToKanban}
         onReorderLane={reorderKanbanLane}
         onAddLane={editable ? addKanbanLane : undefined}
         onAddTask={addKanbanTask}
@@ -2675,6 +3304,8 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         onCustomDateField={calendarController.canChangeDateField ? () => setMatchingOpen(true) : undefined}
         titleField={document.dataset.schema.fields.find((field) => field.id === calendarTitleFieldId) ?? noteField ?? document.dataset.schema.fields[0]}
         renderValue={displayFieldValue}
+        noteColorForRecord={calendarNoteColorForRecord}
+        noteIconForRecord={noteIconForRecord}
         dateValueForRecord={(record) => calendarDateMetadata
           ? calendarDateTimeForTimestamp(noteForRecord(record)?.[calendarDateMetadata.timestamp])
           : calendarField ? notePropertyEditorValue(noteForRecord(record), calendarField) : null}
@@ -2684,7 +3315,10 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         weekStart={calendarWeekStart}
         onWeekStartChange={calendarController.canChangeDateField ? updateCalendarWeekStart : undefined}
         onMoveRecord={updateRecordField}
+        dropNotebookId={resolvedNotebookId}
+        onExternalNoteDrop={addExternalNotesToCalendar}
         onOpenRecord={openLinkedRecord}
+        onEditRecord={openCalendarEditPopover}
         addingNoteDate={calendarAddOpen ? calendarAddDate?.date : null}
         onDoubleClickDate={(date, anchorRect) => {
           if (!editable) {
@@ -2717,7 +3351,9 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
           : t('multidimensionalTable.view.calendarMissingField')}
       />}
       {activeView?.layout === 'gallery' && <TableGalleryView
+        dropAreaRef={recordsScrollerRef}
         records={visibleGalleryRecords}
+        nextRecordId={secondaryViewRecords[(embeddedInEditor ? galleryCurrentPage * galleryPageSize : 0) + visibleGalleryRecords.length]?.id ?? null}
         titleField={titleField ?? document.dataset.schema.fields[0]}
         fields={galleryFields}
         renderValue={displayFieldValue}
@@ -2737,6 +3373,10 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         recordStatus={noteStatusForRecord}
         noteIcon={(record) => noteForRecord(record)?.icon ?? null}
         canAddData={editable && Boolean(noteField && resolvedNotebookId) && !saving}
+        dropNotebookId={resolvedNotebookId}
+        canDropExternal={editable && Boolean(noteField && notebookPath && resolvedNotebookId) && !saving}
+        previewExternalNoteDrop={previewExternalGalleryDrop}
+        onExternalNoteDrop={addExternalNotesToGallery}
       />}
       {embeddedInEditor && activeView?.layout === 'gallery' && galleryPageCount > 1 && <footer className="flex flex-wrap items-center justify-end gap-3 px-5 py-1.5 text-xs text-[var(--muted-foreground)]" aria-label="画廊分页">
         <span>{secondaryViewRecords.length} 条</span>
@@ -2775,7 +3415,7 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
             添加笔记
           </button>
         )}
-        <footer className="flex flex-wrap items-center gap-3 text-xs text-[var(--muted-foreground)]" aria-label={embeddedInEditor && pageCount > 1 ? '表格分页' : '记录统计'}>
+        <footer className="flex flex-wrap items-center gap-3 text-sm text-[var(--muted-foreground)]" aria-label={embeddedInEditor && pageCount > 1 ? '表格分页' : '记录统计'}>
           <span>{visibleRecords.length} 条</span>
           {embeddedInEditor && pageCount > 1 && <>
             <button
@@ -2865,13 +3505,68 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         />
       </PopoverContent>
     </Popover>
-    <Popover open={calendarAddOpen} onOpenChange={setCalendarAddOpen} anchorRect={calendarAddAnchorRect}>
-      <PopoverContent side="bottom" align="start" sideOffset={6} fitViewport className="w-[240px] max-w-[calc(100vw-16px)] rounded-xl px-2 py-2 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+    <Popover open={calendarAddOpen} onOpenChange={(open) => {
+      setCalendarAddOpen(open);
+      if (!open) {
+        calendarPendingCreatedNoteRef.current = null;
+        setCalendarEditingRecord(null);
+      }
+    }} anchorRect={calendarAddAnchorRect}>
+      <PopoverContent side="right" align="start" sideOffset={8} fitViewport ignorePopoverOutside style={{ zIndex: 160 }} className="calendar-note-create-popover flex max-h-[min(424px,100vh)] w-[320px] max-w-[calc(100vw-16px)] flex-col overflow-hidden rounded-xl px-2 py-2 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
         <NoteCreatePicker
           value={calendarAddTitle} onChange={setCalendarAddTitle}
-          notes={availableNotes} allowSelect={!calendarDateMetadata && document.collection.placement !== 'folder'}
-          disabled={saving || !editable || !resolvedNotebookId} error={notesLoadError}
-          onCreate={createCalendarNote} onSelect={linkCalendarNote} onCancel={closeCalendarAddPopover}
+          mode={calendarEditingRecord ? 'edit' : 'create'} allowSelect={false}
+          disabled={saving || !editable || (!calendarEditingRecord && !resolvedNotebookId)}
+          onCreate={calendarEditingRecord ? saveCalendarNoteEdit : createCalendarNote} onCancel={closeCalendarNoteDialog}
+          showCreateButton={false}
+          actionsLayout="column"
+          scrollTitleWithActions
+          actions={calendarCreateFields.length > 0 ? <div className="calendar-note-create-fields border-t border-[var(--border)]">
+            {calendarCreateFields.map((field) => {
+              const value = calendarCreatePropertyValues[field.id];
+              const inputClass = 'h-8 w-full rounded-md border-0 bg-transparent px-0 text-sm outline-none placeholder:text-[var(--muted-foreground)] placeholder:opacity-80 focus:border-0 focus:bg-transparent focus:ring-0 disabled:cursor-not-allowed disabled:opacity-50';
+              const setValue = (nextValue: unknown) => setCalendarCreatePropertyValues((current) => ({ ...current, [field.id]: nextValue }));
+              const options = field.options?.map((option) => ({ value: option.id, label: option.label })) ?? [];
+              const control = field.type === 'Boolean'
+                ? <TableBooleanInput value={value} disabled={saving} ariaLabel={fieldLabel(field, propertyFields, t)} onChange={setValue} />
+                : field.type === 'Select'
+                  ? <SelectValueInput value={String(value ?? '')} options={options} disabled={saving} variant="table" onChange={setValue} />
+                  : field.type === 'MultiSelect'
+                    ? <MultiSelectValueInput value={Array.isArray(value) ? value.map(String).join(', ') : ''} options={options} disabled={saving} variant="table" onChange={(next) => setValue(next.split(',').map((item) => item.trim()).filter(Boolean))} />
+                    : field.type === 'Date'
+                      ? <DateValueInput value={String(value ?? '')} disabled={saving} variant="table" onChange={setValue} />
+                      : field.type === 'Color'
+                        ? <ColorValueInput value={Array.isArray(value) ? value.map(String).join(', ') : ''} disabled={saving} variant="table" onChange={(next) => setValue(next ? next.split(',').map((item) => item.trim()).filter(Boolean) : [])} />
+                        : field.type === 'Icon'
+                          ? <IconValueInput value={String(value ?? '')} disabled={saving} variant="table" onChange={setValue} />
+                          : field.type === 'Tag'
+                            ? <TableTagValueInput value={Array.isArray(value) ? value.map(String) : []} disabled={saving} isNoteTags={canonicalizePropertyKey(field.property_key ?? '') === 'tags'} onChange={setValue} />
+                            : field.type === 'Text'
+                              ? <TableTextValueInput value={String(value ?? '')} disabled={saving} onChange={(next) => setValue(next ?? '')} />
+                              : field.type === 'Number'
+                                ? <TableNumberInput value={value} disabled={saving} placeholder="" className={inputClass} onChange={setValue} />
+                                : field.type === 'Image'
+                                  ? <NotePropertyImageValue
+                                    value={value}
+                                    notebook={resolvedNotebookId && notebookPath ? { id: resolvedNotebookId, path: notebookPath } : undefined}
+                                    disabled={saving}
+                                    onChange={(path) => setValue(field.multiple ? [...(Array.isArray(value) ? value.map(String) : []), path] : path)}
+                                  />
+                                  : <input type="url" value={String(value ?? '')} disabled={saving} onChange={(event) => setValue(event.currentTarget.value)} className={inputClass} />;
+              return <div key={field.id} className="flex min-w-0 items-center gap-2 border-b border-[var(--border)] last:border-b-0">
+                <div className="w-fit min-w-[24%] max-w-[36%] shrink-0 truncate text-sm" title={fieldLabel(field, propertyFields, t)}>{fieldLabel(field, propertyFields, t)}</div>
+                <div className="multidimensional-table__cell-content calendar-note-create-field-input min-w-0 flex-1 px-1.5">{control}</div>
+              </div>;
+            })}
+          </div> : undefined}
+          footer={<div className="flex w-full shrink-0 gap-2 pt-2">
+            {!calendarEditingRecord && <Button type="button" variant="outline" size="lg" className="!h-8 flex-1 rounded-lg text-sm" disabled={saving} onClick={closeCalendarNoteDialog}>取消</Button>}
+            <Button type="button" size="lg" className="!h-8 flex-1 rounded-lg text-sm" disabled={saving || !editable || (!calendarEditingRecord && !resolvedNotebookId) || !calendarAddTitle.trim()} onClick={() => void (calendarEditingRecord ? saveCalendarNoteEdit() : createCalendarNote())}>
+              {saving && <LoaderCircle className="mr-1 h-3.5 w-3.5 flowix-spin" aria-hidden="true" />}
+              保存
+            </Button>
+            {calendarEditingRecord && <Button type="button" variant="outline" size="lg" className="!h-8 flex-1 rounded-lg text-sm" disabled={!noteForRecord(calendarEditingRecord)} onClick={() => openLinkedRecord(calendarEditingRecord.id)}>打开</Button>}
+          </div>}
         />
       </PopoverContent>
     </Popover>
@@ -2893,6 +3588,20 @@ function TableDocumentViewSession({ filePath, fileIdentity, notebookPath, notebo
         />
       </PopoverContent>
     </Popover>
+    <Dialog open={viewPendingDelete !== null} onOpenChange={(open) => { if (!open) setViewPendingDelete(null); }}>
+      <DialogContent className="rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+        <DialogHeader>
+          <DialogTitle>{t('multidimensionalTable.view.delete')}</DialogTitle>
+          <DialogDescription>
+            {viewPendingDelete ? t('multidimensionalTable.view.deleteConfirm', { name: viewPendingDelete.name }) : ''}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="mt-4 flex justify-end gap-2">
+          <Button type="button" variant="ghost" onClick={() => setViewPendingDelete(null)}>{t('dialog.cancel')}</Button>
+          <Button type="button" variant="destructive" onClick={confirmDeleteView}>{t('dialog.delete')}</Button>
+        </div>
+      </DialogContent>
+    </Dialog>
     <FolderCollectionSwitchConfirmDialog
       open={folderMediaSwitchConfirmOpen}
       onOpenChange={setFolderMediaSwitchConfirmOpen}
diff --git a/app/flowix-web/features/multidimensional-table/table-gallery-drop.test.tsx b/app/flowix-web/features/multidimensional-table/table-gallery-drop.test.tsx
new file mode 100644
index 000000000..2e75beb92
--- /dev/null
+++ b/app/flowix-web/features/multidimensional-table/table-gallery-drop.test.tsx
@@ -0,0 +1,63 @@
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { expect, it, vi } from 'vitest';
+import type { NoteEntry } from '@platform/tauri/client';
+import { beginDragSession, cancelDragSession, endDragSession } from '@shared/drag-drop/drag-drop-coordinator';
+import { createTableDocument, type TableRecord } from './model';
+import { planTableNoteDrop } from './table-note-drop';
+import { TableGalleryView } from './table-secondary-views';
+
+it('shows a same-size translucent card at the sorted destination even when the pointer is over another position', async () => {
+  const documentModel = createTableDocument('gallery');
+  const incoming: NoteEntry = {
+    relativePath: 'incoming.md', title: 'incoming.md', preview: '', thumbnail: null,
+    tags: [], todos: [], agents: [], createdAt: 0, updatedAt: 20,
+    favorited: false, icon: null, colors: [], properties: {},
+  };
+  const records: TableRecord[] = [
+    { id: 'automatic', note_path: 'automatic.md', updated_at: '' },
+    { id: 'old', note_path: 'old.md', updated_at: '' },
+  ];
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  const onDrop = vi.fn();
+  try {
+    act(() => root.render(<TableGalleryView
+      records={records}
+      titleField={documentModel.dataset.schema.fields[0]}
+      fields={documentModel.dataset.schema.fields}
+      renderValue={(record) => record.note_path}
+      imageUrl={() => null}
+      onOpenRecord={vi.fn()}
+      dropNotebookId="book"
+      canDropExternal
+      previewExternalNoteDrop={(_notes, beforeRecordId) => planTableNoteDrop({
+        explicitRecords: [records[1]], automaticRecords: [records[0]], draggedNotes: [incoming],
+        beforeRecordId, view: documentModel.views.items[0], fields: documentModel.dataset.schema.fields,
+        primaryFieldId: documentModel.dataset.schema.primary_field_id,
+        noteForRecord: (record) => ({ ...incoming, relativePath: record.note_path, updatedAt: record.id === 'automatic' ? 30 : 10 }),
+        isInSource: () => true,
+      })}
+      onExternalNoteDrop={onDrop}
+    />));
+    const firstCard = container.querySelector<HTMLElement>('[data-gallery-record="automatic"]')!;
+    Object.defineProperty(document, 'elementFromPoint', { configurable: true, value: () => firstCard });
+    Object.defineProperty(firstCard, 'getBoundingClientRect', { configurable: true, value: () => ({ left: 0, top: 0, width: 160, height: 210 }) });
+    act(() => beginDragSession({
+      sourceId: 'sidebar', sessionId: 'gallery-sorted-drop',
+      items: [{ kind: 'note', notebookId: 'book', relativePath: 'incoming.md', title: 'incoming.md' }],
+    }, { x: 5, y: 5 }));
+    const cards = [...container.querySelectorAll<HTMLElement>('[data-gallery-record], [data-gallery-preview]')];
+    expect(cards.map((card) => card.textContent?.split('更新')[0])).toEqual(['automatic.md', 'incoming.md', 'old.md']);
+    expect(cards[1].classList.contains('opacity-50')).toBe(true);
+    expect(cards.every((card) => card.classList.contains('h-[210px]'))).toBe(true);
+    await act(async () => { endDragSession('gallery-sorted-drop', { x: 5, y: 5 }); });
+    expect(onDrop).toHaveBeenCalledOnce();
+    expect(container.querySelector('[data-gallery-preview]')).toBeNull();
+  } finally {
+    act(() => { cancelDragSession(); root.unmount(); });
+    container.remove();
+    Reflect.deleteProperty(document, 'elementFromPoint');
+  }
+});
diff --git a/app/flowix-web/features/multidimensional-table/table-note-drop-overlay.tsx b/app/flowix-web/features/multidimensional-table/table-note-drop-overlay.tsx
new file mode 100644
index 000000000..5da423bdc
--- /dev/null
+++ b/app/flowix-web/features/multidimensional-table/table-note-drop-overlay.tsx
@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useI18n } from '@/lib/i18n';
+
+export function TableNoteDropOverlay({ active, dropAreaRef }: {
+  active: boolean;
+  dropAreaRef: { current: HTMLElement | null };
+}) {
+  const { t } = useI18n();
+  const [bounds, setBounds] = useState<{ top: number; left: number; width: number; height: number } | null>(null);
+
+  useEffect(() => {
+    if (!active) {
+      setBounds(null);
+      return;
+    }
+    const updateBounds = () => {
+      const area = dropAreaRef.current;
+      if (!area) {
+        setBounds(null);
+        return;
+      }
+      const rect = area.getBoundingClientRect();
+      setBounds({ top: rect.top, left: rect.left, width: rect.width, height: rect.height });
+    };
+    updateBounds();
+    window.addEventListener('resize', updateBounds);
+    window.addEventListener('scroll', updateBounds, true);
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(updateBounds);
+    if (dropAreaRef.current) observer?.observe(dropAreaRef.current);
+    return () => {
+      window.removeEventListener('resize', updateBounds);
+      window.removeEventListener('scroll', updateBounds, true);
+      observer?.disconnect();
+    };
+  }, [active, dropAreaRef]);
+
+  if (!active || !bounds || bounds.width <= 0 || bounds.height <= 0) return null;
+  return createPortal(<div
+    aria-live="polite"
+    className="pointer-events-none z-[80] flex items-center justify-center bg-[color-mix(in_oklch,var(--document-bg)_58%,transparent)] backdrop-blur-[1px]"
+    style={{ position: 'fixed', top: bounds.top, left: bounds.left, width: bounds.width, height: bounds.height }}
+  >
+    <span className="text-sm font-medium text-[var(--foreground)]">{t('multidimensionalTable.dropOverlayHint')}</span>
+  </div>, document.body);
+}
diff --git a/app/flowix-web/features/multidimensional-table/table-note-drop.test.ts b/app/flowix-web/features/multidimensional-table/table-note-drop.test.ts
new file mode 100644
index 000000000..cefe1a927
--- /dev/null
+++ b/app/flowix-web/features/multidimensional-table/table-note-drop.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import type { NoteEntry } from '@platform/tauri/client';
+import { createTableDocument, type TableRecord } from './model';
+import { planTableNoteDrop } from './table-note-drop';
+import { applyTableView } from './view-records';
+
+const record = (path: string): TableRecord => ({ id: `existing:${path}`, note_path: path, updated_at: '' });
+const note = (path: string, updatedAt: number, workflow = 'keep'): NoteEntry => ({
+  relativePath: path, title: path, preview: '', thumbnail: null, tags: [], todos: [], agents: [],
+  createdAt: 0, updatedAt, favorited: false, icon: null, colors: [], properties: { workflow },
+});
+
+function fixture() {
+  const document = createTableDocument('gallery');
+  const old = note('old.md', 10);
+  const automatic = note('automatic.md', 30);
+  const incoming = note('incoming.md', 20);
+  const notes = new Map([old, automatic, incoming].map((entry) => [entry.relativePath, entry]));
+  return {
+    explicitRecords: [record(old.relativePath)], automaticRecords: [record(automatic.relativePath)],
+    draggedNotes: [incoming], beforeRecordId: 'existing:old.md', view: document.views.items[0],
+    fields: document.dataset.schema.fields, primaryFieldId: document.dataset.schema.primary_field_id,
+    noteForRecord: (entry: TableRecord) => notes.get(entry.note_path), isInSource: () => true,
+  };
+}
+
+describe('table note drop planning', () => {
+  it('previews the existing sort order and reproduces it after save/reload without new ordering fields', () => {
+    const args = fixture();
+    const plan = planTableNoteDrop(args);
+    if ('reason' in plan) throw new Error(plan.reason);
+    expect(plan.records.map((entry) => entry.note_path)).toEqual(['automatic.md', 'incoming.md', 'old.md']);
+    expect(plan.includedRecords.map((entry) => entry.note_path)).toEqual(['old.md', 'incoming.md']);
+    const persisted = JSON.parse(JSON.stringify(plan.includedRecords)) as TableRecord[];
+    persisted[1].id = 'rec_00000000000000000000000000000001';
+    const reloaded = applyTableView([...persisted, ...args.automaticRecords], args.view, args.fields,
+      args.primaryFieldId, (entry) => args.draggedNotes.find((note) => note.relativePath === entry.note_path) ?? args.noteForRecord(entry));
+    expect(reloaded.map((entry) => entry.note_path)).toEqual(plan.records.map((entry) => entry.note_path));
+    expect(args.view.sort).toEqual([{ field: 'modified_at', direction: 'desc' }]);
+    expect(args.view.config).not.toHaveProperty('record_order');
+  });
+
+  it('accepts matching notes under active filters and rejects only notes that would be hidden', () => {
+    const args = fixture();
+    args.view.filter = { all: [{ field: 'workflow', op: 'contains', value: 'keep' }], any: [] };
+    expect(planTableNoteDrop(args)).not.toHaveProperty('reason');
+    expect(planTableNoteDrop({ ...args, draggedNotes: [note('skip.md', 20, 'skip')] }))
+      .toEqual({ reason: 'filtered' });
+  });
+
+  it('does not duplicate an automatically collected note or convert unrelated automatic records to explicit records', () => {
+    const args = fixture();
+    args.automaticRecords.push(record('other.md'));
+    const plan = planTableNoteDrop({ ...args, draggedNotes: [note('automatic.md', 30)] });
+    if ('reason' in plan) throw new Error(plan.reason);
+    expect(plan.records.filter((entry) => entry.note_path === 'automatic.md')).toHaveLength(1);
+    expect(plan.includedRecords.map((entry) => entry.note_path)).toEqual(['old.md', 'automatic.md']);
+    expect(plan.records.some((entry) => entry.note_path === 'other.md')).toBe(true);
+    expect(args.automaticRecords).toHaveLength(2);
+  });
+
+  it('inserts at the requested list position when no automatic sort is configured', () => {
+    const args = fixture();
+    args.view.sort = [];
+    args.explicitRecords.push(record('last.md'));
+    const plan = planTableNoteDrop({ ...args, beforeRecordId: 'existing:last.md' });
+    if ('reason' in plan) throw new Error(plan.reason);
+    expect(plan.includedRecords.map((entry) => entry.note_path)).toEqual(['old.md', 'incoming.md', 'last.md']);
+    expect(args.explicitRecords).toHaveLength(2);
+  });
+
+  it('places multiple dragged notes independently according to the existing sort', () => {
+    const args = fixture();
+    const plan = planTableNoteDrop({ ...args, draggedNotes: [note('newest.md', 40), note('middle.md', 20)] });
+    if ('reason' in plan) throw new Error(plan.reason);
+    expect(plan.records.map((entry) => entry.note_path)).toEqual(['newest.md', 'automatic.md', 'middle.md', 'old.md']);
+  });
+});
diff --git a/app/flowix-web/features/multidimensional-table/table-note-drop.ts b/app/flowix-web/features/multidimensional-table/table-note-drop.ts
new file mode 100644
index 000000000..099b2b7da
--- /dev/null
+++ b/app/flowix-web/features/multidimensional-table/table-note-drop.ts
@@ -0,0 +1,54 @@
+import type { NoteEntry } from '@platform/tauri/client';
+import type { TableField, TableRecord, TableView } from './model';
+import { applyTableView } from './view-records';
+
+export interface TableNoteDropPreview {
+  records: TableRecord[];
+  draggedPaths: string[];
+}
+
+export type TableNoteDropRejection = { reason: 'filtered' | 'unavailable' };
+
+/** Preview and save use the same prospective dataset and the existing view rules. */
+export function planTableNoteDrop({
+  explicitRecords, automaticRecords, draggedNotes, beforeRecordId, view, fields,
+  primaryFieldId, noteForRecord, isInSource,
+}: {
+  explicitRecords: TableRecord[];
+  automaticRecords: TableRecord[];
+  draggedNotes: NoteEntry[];
+  beforeRecordId: string | null;
+  view: TableView;
+  fields: TableField[];
+  primaryFieldId: string;
+  noteForRecord: (record: TableRecord) => NoteEntry | undefined;
+  isInSource: (path: string) => boolean;
+}): (TableNoteDropPreview & { includedRecords: TableRecord[] }) | TableNoteDropRejection {
+  const pathKey = (path: string) => path.replace(/\\/g, '/');
+  const notesByPath = new Map(draggedNotes.map((note) => [pathKey(note.relativePath), note]));
+  if (!notesByPath.size) return { reason: 'unavailable' };
+  const existingByPath = new Map([...automaticRecords, ...explicitRecords].map((record) => [pathKey(record.note_path), record]));
+  const linkedRecords = [...notesByPath].map(([path, note]): TableRecord => existingByPath.get(path) ?? {
+    id: `drop-note:${path}`,
+    note_path: path,
+    updated_at: new Date(note.updatedAt).toISOString(),
+  });
+  const remaining = explicitRecords.filter((record) => !notesByPath.has(pathKey(record.note_path)));
+  const requestedIndex = view.sort.length ? -1 : explicitRecords.findIndex((record) => record.id === beforeRecordId);
+  const anchor = requestedIndex >= 0
+    ? explicitRecords.slice(requestedIndex).find((record) => !notesByPath.has(pathKey(record.note_path)))
+    : undefined;
+  const insertAt = anchor ? remaining.findIndex((record) => record.id === anchor.id) : remaining.length;
+  const includedRecords = [...remaining.slice(0, insertAt), ...linkedRecords, ...remaining.slice(insertAt)];
+  const includedPaths = new Set(includedRecords.map((record) => pathKey(record.note_path)));
+  const dataset = [
+    ...includedRecords.filter((record) => isInSource(record.note_path)),
+    ...automaticRecords.filter((record) => !includedPaths.has(pathKey(record.note_path))),
+  ];
+  const records = applyTableView(dataset, view, fields, primaryFieldId,
+    (record) => notesByPath.get(pathKey(record.note_path)) ?? noteForRecord(record))
+    .filter((record) => record.note_path.trim().length > 0);
+  const visiblePaths = new Set(records.map((record) => pathKey(record.note_path)));
+  if ([...notesByPath.keys()].some((path) => !visiblePaths.has(path))) return { reason: 'filtered' };
+  return { includedRecords, records, draggedPaths: [...notesByPath.keys()] };
+}
diff --git a/app/flowix-web/features/multidimensional-table/table-record-row.test.tsx b/app/flowix-web/features/multidimensional-table/table-record-row.test.tsx
index fd8fdaabf..bb5121d60 100644
--- a/app/flowix-web/features/multidimensional-table/table-record-row.test.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-record-row.test.tsx
@@ -85,7 +85,7 @@ describe('TableRecordRow note fallback', () => {
     const view = renderRow('unknown');
     const retry = [...view.container.querySelectorAll('button')].find((button) => button.textContent?.includes('无法确认关联状态'));
     expect(retry).toBeTruthy();
-    expect(view.container.querySelector<HTMLInputElement>('input[type="checkbox"]')?.disabled).toBe(true);
+    expect(view.container.querySelector<HTMLButtonElement>('[role="checkbox"]')?.disabled).toBe(true);
 
     act(() => retry?.click());
     expect(view.retryNoteLookup).toHaveBeenCalledOnce();
@@ -96,19 +96,19 @@ describe('TableRecordRow note fallback', () => {
     const view = renderRow('missing');
     const replace = [...view.container.querySelectorAll('button')].find((button) => button.textContent?.includes('未找到笔记'));
     expect(replace).toBeTruthy();
-    expect(view.container.querySelector<HTMLInputElement>('input[type="checkbox"]')?.disabled).toBe(true);
+    expect(view.container.querySelector<HTMLButtonElement>('[role="checkbox"]')?.disabled).toBe(true);
 
     expect(view.container.querySelector('textarea')?.getAttribute('placeholder')).toBe('输入名称搜索 或 新建');
   });
 
   it('keeps property editing enabled for a resolved note', () => {
     const view = renderRow('linked', linkedNote);
-    expect(view.container.querySelector<HTMLInputElement>('input[type="checkbox"]')?.disabled).toBe(false);
+    expect(view.container.querySelector<HTMLButtonElement>('[role="checkbox"]')?.disabled).toBe(false);
   });
 
   it('disables property editing in an unlinked draft row', () => {
     const view = renderRow('draft');
-    expect(view.container.querySelector<HTMLInputElement>('input[type="checkbox"]')?.disabled).toBe(true);
+    expect(view.container.querySelector<HTMLButtonElement>('[role="checkbox"]')?.disabled).toBe(true);
   });
 });
 
@@ -132,8 +132,8 @@ describe('TableRecordRow builtin metadata', () => {
     vi.useFakeTimers();
     const view = renderRow('linked', { ...linkedNote, favorited: true }, true);
     const index = BUILTIN_TABLE_FIELDS.findIndex((field) => field.label === '置顶');
-    const checkbox = view.container.querySelectorAll('td')[index + 2].querySelector<HTMLInputElement>('input');
-    expect(checkbox?.checked).toBe(true);
+    const checkbox = view.container.querySelectorAll('td')[index + 2].querySelector<HTMLButtonElement>('[role="checkbox"]');
+    expect(checkbox?.getAttribute('aria-checked')).toBe('true');
     await act(async () => { checkbox?.click(); vi.advanceTimersByTime(1000); });
     expect(view.updateCell).toHaveBeenCalledWith(expect.anything(), expect.anything(),
       expect.objectContaining({ id: '__note_pinned__', property_key: 'flowix_favorited', type: 'Boolean' }), false);
diff --git a/app/flowix-web/features/multidimensional-table/table-record-row.tsx b/app/flowix-web/features/multidimensional-table/table-record-row.tsx
index e5893f488..71faa0153 100644
--- a/app/flowix-web/features/multidimensional-table/table-record-row.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-record-row.tsx
@@ -9,6 +9,7 @@ import { displayTitleFromFilename } from '@/lib/utils';
 import { canonicalizePropertyKey } from '@features/properties/property-key';
 import { useComposingValue } from '@shared/hooks/use-composing-value';
 import { Popover, PopoverContent, PopoverTrigger } from '@shared/ui/popover';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 import { DateValueInput } from '@features/document/components/note-properties/date-value-input';
 import { ColorValueInput } from '@features/document/properties/color-value-input';
 import { ImageValueInput } from '@features/document/properties/image-value-input';
@@ -23,9 +24,10 @@ import type { TableCellSaveStatus } from './use-table-cell-writer';
 
 const EMPTY_AVAILABLE_NOTES: NoteEntry[] = [];
 
-function TableBooleanInput({ value, disabled, onChange }: {
+export function TableBooleanInput({ value, disabled, ariaLabel, onChange }: {
   value: unknown;
   disabled: boolean;
+  ariaLabel: string;
   onChange: (value: boolean) => void;
 }) {
   const [checked, setChecked] = useState(Boolean(value));
@@ -60,13 +62,11 @@ function TableBooleanInput({ value, disabled, onChange }: {
     if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
   }, []);
 
-  return <input
-    type="checkbox"
-    className="h-4 w-4 accent-[var(--brand)]"
+  return <FlowixCheckbox
+    aria-label={ariaLabel}
     checked={checked}
     disabled={disabled}
-    onChange={(event) => {
-      const nextValue = event.target.checked;
+    onCheckedChange={(nextValue) => {
       pendingValueRef.current = nextValue;
       setChecked(nextValue);
       if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
@@ -78,7 +78,7 @@ function TableBooleanInput({ value, disabled, onChange }: {
   />;
 }
 
-function TableNumberInput({
+export function TableNumberInput({
   value: initialValue,
   disabled,
   placeholder,
@@ -146,6 +146,7 @@ function TableNumberInput({
 
 interface TableRecordRowProps {
   record: TableRecord;
+  isDropPreview?: boolean;
   showBottomBorder?: boolean;
   imagePaths: (value: unknown) => string[];
   notePropertyEditorValue: (note: NoteEntry | undefined, field: TableField) => unknown;
@@ -180,6 +181,7 @@ interface TableRecordRowProps {
 
 export const TableRecordRow = memo(function TableRecordRow({
   record,
+  isDropPreview = false,
   showBottomBorder = true,
   imagePaths,
   notePropertyEditorValue,
@@ -309,7 +311,12 @@ export const TableRecordRow = memo(function TableRecordRow({
     }
   };
 
-  return <tr className="hover:bg-[var(--muted)]/25">
+  return <tr
+    data-table-record={isDropPreview ? undefined : record.id}
+    aria-hidden={isDropPreview || undefined}
+    inert={isDropPreview || undefined}
+    className={`hover:bg-[var(--muted)]/25 ${isDropPreview ? 'pointer-events-none opacity-50' : ''}`}
+  >
     {sortFields([...[...fields, ...builtinFields.flatMap((field) => {
       const preset = builtinPresetTableField(field.id);
       return preset ? [preset] : [];
@@ -500,7 +507,7 @@ export const TableRecordRow = memo(function TableRecordRow({
                   variant="table"
                   onChange={(next) => onUpdateCell(record, note, field, next || null)}
                 />
-                  : field.type === 'Boolean' ? <TableBooleanInput value={value} disabled={cellDisabled} onChange={(nextValue) => onUpdateCell(record, note, field, nextValue)} />
+                  : field.type === 'Boolean' ? <TableBooleanInput value={value} disabled={cellDisabled} ariaLabel={field.name || field.property_key || field.id} onChange={(nextValue) => onUpdateCell(record, note, field, nextValue)} />
                     : field.type === 'MultiSelect' ? <MultiSelectValueInput
                       value={Array.isArray(value) ? value.map(String).join(', ') : typeof value === 'string' ? value : ''}
                       options={field.options?.map((option) => ({ value: option.id, label: option.label })) ?? []}
diff --git a/app/flowix-web/features/multidimensional-table/table-reference-markdown.ts b/app/flowix-web/features/multidimensional-table/table-reference-markdown.ts
new file mode 100644
index 000000000..4ad7c8bdb
--- /dev/null
+++ b/app/flowix-web/features/multidimensional-table/table-reference-markdown.ts
@@ -0,0 +1,66 @@
+import { Extension, type MarkdownToken } from '@tiptap/core';
+
+export const TABLE_REFERENCE_MARKER = 'flowix:table-reference';
+export const TABLE_REFERENCE_VERSION = 1;
+
+export interface TableReferenceAttrs {
+  notebookId: string | null;
+  relativePath: string | null;
+  collectionId: string | null;
+  viewId: string | null;
+}
+
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+export function normalizeTableReferenceAttrs(value: unknown): TableReferenceAttrs {
+  const attrs = value && typeof value === 'object' ? value as Record<string, unknown> : {};
+  return {
+    notebookId: normalizeText(attrs.notebookId),
+    relativePath: normalizeText(attrs.relativePath)?.replace(/\\/g, '/').replace(/^\/+/, '') ?? null,
+    collectionId: normalizeText(attrs.collectionId),
+    viewId: normalizeText(attrs.viewId),
+  };
+}
+
+export function tableReferenceMetadataFromSource(source: string): Record<string, unknown> | null {
+  const match = new RegExp(`^<!--[ \\t]*${TABLE_REFERENCE_MARKER}[ \\t]+(\\{[^\\r\\n]*\\})[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
+  if (!match) return null;
+  try {
+    const parsed: unknown = JSON.parse(match[1]);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export const tableReferenceMarkdownSpec = {
+  markdownTokenizer: {
+    name: 'tableReference',
+    level: 'block' as const,
+    start(source: string) {
+      return new RegExp(`^<!--[ \\t]*${TABLE_REFERENCE_MARKER}[ \\t]+\\{`, 'm').exec(source)?.index ?? -1;
+    },
+    tokenize(source: string) {
+      const metadata = tableReferenceMetadataFromSource(source);
+      if (!metadata) return undefined;
+      const match = new RegExp(`^<!--[ \\t]*${TABLE_REFERENCE_MARKER}[ \\t]+\\{[^\\r\\n]*\\}[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
+      return match ? { type: 'tableReference', raw: match[0], metadata } : undefined;
+    },
+  },
+  parseMarkdown(token: MarkdownToken) {
+    const metadata = token.metadata && typeof token.metadata === 'object'
+      ? token.metadata as Record<string, unknown>
+      : tableReferenceMetadataFromSource(token.raw ?? '') ?? {};
+    const data = metadata.version === TABLE_REFERENCE_VERSION ? metadata : {};
+    return { type: 'tableReference', attrs: normalizeTableReferenceAttrs(data) };
+  },
+};
+
+export const TableReferenceMarkdownExtension = Extension.create({
+  name: 'tableReference',
+  ...tableReferenceMarkdownSpec,
+});
diff --git a/app/flowix-web/features/multidimensional-table/table-reference-node.tsx b/app/flowix-web/features/multidimensional-table/table-reference-node.tsx
index cf0711c89..ab74cb265 100644
--- a/app/flowix-web/features/multidimensional-table/table-reference-node.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-reference-node.tsx
@@ -1,11 +1,11 @@
 import { useCallback } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
-import { Node as TiptapNode, mergeAttributes, type Editor, type MarkdownToken } from '@tiptap/core';
+import { Node as TiptapNode, mergeAttributes, type Editor } from '@tiptap/core';
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { EditorView, NodeView as ProseMirrorNodeView } from '@tiptap/pm/view';
 import { X } from 'lucide-react';
 import { ArrowUpRightIcon, ArrowsLeftRightIcon } from '@phosphor-icons/react';
-import { openCollectionTarget } from '@features/workspace/use-cases/workspace-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { useAppLanguage } from '@features/preferences/public/runtime-api';
 import { I18nProvider } from '@/lib/i18n/provider';
@@ -15,45 +15,16 @@ import { toast } from '@/lib/toast';
 import { Button } from '@shared/ui/button';
 import { TableDocumentView } from './table-document-view';
 import { openTableReferencePicker } from './table-reference-picker';
+import {
+  TABLE_REFERENCE_MARKER,
+  TABLE_REFERENCE_VERSION,
+  normalizeTableReferenceAttrs,
+  tableReferenceMarkdownSpec,
+  type TableReferenceAttrs,
+} from './table-reference-markdown';
 
-const TABLE_REFERENCE_MARKER = 'flowix:table-reference';
-const TABLE_REFERENCE_VERSION = 1;
 const EDITOR_EDITABILITY_CHANGE_EVENT = 'flowix:editor-editability-change';
 
-export interface TableReferenceAttrs {
-  notebookId: string | null;
-  relativePath: string | null;
-  collectionId: string | null;
-  viewId: string | null;
-}
-
-function normalizeText(value: unknown): string | null {
-  return typeof value === 'string' && value.trim() ? value.trim() : null;
-}
-
-function normalizeAttrs(value: unknown): TableReferenceAttrs {
-  const attrs = value && typeof value === 'object' ? value as Record<string, unknown> : {};
-  return {
-    notebookId: normalizeText(attrs.notebookId),
-    relativePath: normalizeText(attrs.relativePath)?.replace(/\\/g, '/').replace(/^\/+/, '') ?? null,
-    collectionId: normalizeText(attrs.collectionId),
-    viewId: normalizeText(attrs.viewId),
-  };
-}
-
-function metadataFromSource(source: string): Record<string, unknown> | null {
-  const match = new RegExp(`^<!--[ \\t]*${TABLE_REFERENCE_MARKER}[ \\t]+(\\{[^\\r\\n]*\\})[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
-  if (!match) return null;
-  try {
-    const parsed: unknown = JSON.parse(match[1]);
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? parsed as Record<string, unknown>
-      : null;
-  } catch {
-    return null;
-  }
-}
-
 class TableReferenceNodeView implements ProseMirrorNodeView {
   readonly dom: HTMLElement;
   private readonly root: Root;
@@ -79,7 +50,7 @@ class TableReferenceNodeView implements ProseMirrorNodeView {
 
   private render() {
     if (this.destroyed) return;
-    const attrs = normalizeAttrs(this.node.attrs);
+    const attrs = normalizeTableReferenceAttrs(this.node.attrs);
     this.root.render(<TableReferenceSurface
       attrs={attrs}
       editable={this.editor.isEditable}
@@ -168,7 +139,10 @@ function TableReferenceSurface({ attrs, editable, onViewChange, onRelativePathCh
   const openOriginal = useCallback(async () => {
     if (!notebook || !attrs.collectionId) return;
     try {
-      await openCollectionTarget({ notebookId: notebook.id, collectionId: attrs.collectionId, viewId: attrs.viewId });
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'collection-reference', notebookId: notebook.id, collectionId: attrs.collectionId, viewId: attrs.viewId, collectionKind: 'table' },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : '无法打开多维表格');
     }
@@ -257,7 +231,7 @@ export const TableReference = TiptapNode.create({
   },
 
   renderHTML({ node, HTMLAttributes }) {
-    const attrs = normalizeAttrs(node.attrs);
+    const attrs = normalizeTableReferenceAttrs(node.attrs);
     return ['div', mergeAttributes(HTMLAttributes, {
       'data-flowix-table-reference': 'true',
       'data-notebook-id': attrs.notebookId ?? '',
@@ -278,32 +252,10 @@ export const TableReference = TiptapNode.create({
     );
   },
 
-  markdownTokenizer: {
-    name: 'tableReference',
-    level: 'block' as const,
-    start(source: string) {
-      const match = new RegExp(`^<!--[ \\t]*${TABLE_REFERENCE_MARKER}[ \\t]+\\{`, 'm').exec(source);
-      return match?.index ?? -1;
-    },
-    tokenize(source: string) {
-      const metadata = metadataFromSource(source);
-      if (!metadata) return undefined;
-      const match = new RegExp(`^<!--[ \\t]*${TABLE_REFERENCE_MARKER}[ \\t]+\\{[^\\r\\n]*\\}[ \\t]*-->(?:\\r?\\n|$)`).exec(source);
-      if (!match) return undefined;
-      return { type: 'tableReference', raw: match[0], metadata };
-    },
-  },
-
-  parseMarkdown(token: MarkdownToken) {
-    const metadata = token.metadata && typeof token.metadata === 'object'
-      ? token.metadata as Record<string, unknown>
-      : metadataFromSource(token.raw ?? '') ?? {};
-    const data = metadata.version === TABLE_REFERENCE_VERSION ? metadata : {};
-    return { type: 'tableReference', attrs: normalizeAttrs(data) };
-  },
+  ...tableReferenceMarkdownSpec,
 
   renderMarkdown(node) {
-    const attrs = normalizeAttrs(node.attrs);
+    const attrs = normalizeTableReferenceAttrs(node.attrs);
     return `<!-- ${TABLE_REFERENCE_MARKER} ${JSON.stringify({ version: TABLE_REFERENCE_VERSION, ...attrs })} -->\n`;
   },
 });
diff --git a/app/flowix-web/features/multidimensional-table/table-secondary-views.test.tsx b/app/flowix-web/features/multidimensional-table/table-secondary-views.test.tsx
index 044fca2bf..001520784 100644
--- a/app/flowix-web/features/multidimensional-table/table-secondary-views.test.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-secondary-views.test.tsx
@@ -3,6 +3,7 @@ import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { TableField, TableRecord } from './model';
 import { TableKanbanView } from './table-secondary-views';
+import { endDragSession, registerDropTarget } from '@shared/drag-drop/drag-drop-coordinator';
 
 const groupField: TableField = {
   id: 'status',
@@ -36,6 +37,42 @@ afterEach(() => {
 });
 
 describe('TableKanbanView pointer movement', () => {
+  it('cancels its drag session and clears another target preview when unmounted', () => {
+    container = document.createElement('div');
+    root = createRoot(container);
+    const onPreview = vi.fn();
+    const unregister = registerDropTarget({
+      id: 'unmount-probe',
+      priority: 200,
+      hitTest: () => 'probe',
+      locationKey: (location: string) => location,
+      evaluate: () => ({ accepted: true as const }),
+      onPreview,
+      onDrop: vi.fn(),
+      onError: vi.fn(),
+    });
+    try {
+      act(() => root?.render(<TableKanbanView
+        groupField={groupField}
+        titleField={titleField}
+        groups={new Map([['todo', [first]]])}
+        renderValue={(record) => record.note_path}
+        onDropRecord={vi.fn()}
+        onReorderLane={vi.fn()}
+      />));
+      const card = container.querySelector<HTMLElement>('[data-kanban-record="first"]')!;
+      pointer(card, 'pointerdown', 10, 10);
+      pointer(card, 'pointermove', 30, 30);
+      const sessionId = onPreview.mock.calls[0][0].payload.sessionId;
+      act(() => root?.unmount());
+      root = null;
+      expect(onPreview).toHaveBeenLastCalledWith(null);
+      expect(endDragSession(sessionId, { x: 30, y: 30 })).toBe(false);
+    } finally {
+      unregister();
+    }
+  });
+
   it('opens a linked note when a card is clicked without dragging', () => {
     container = document.createElement('div');
     root = createRoot(container);
diff --git a/app/flowix-web/features/multidimensional-table/table-secondary-views.tsx b/app/flowix-web/features/multidimensional-table/table-secondary-views.tsx
index cd4d797ca..828584354 100644
--- a/app/flowix-web/features/multidimensional-table/table-secondary-views.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-secondary-views.tsx
@@ -1,4 +1,4 @@
-import { Fragment, useMemo, useRef, useState, type MouseEvent, type PointerEvent } from 'react';
+import { Fragment, useCallback, useEffect, useId, useMemo, useRef, useState, type CSSProperties, type MouseEvent, type PointerEvent } from 'react';
 import { createPortal } from 'react-dom';
 import { Check, ChevronDown, ChevronLeft, ChevronRight, Link2, LoaderCircle, Plus } from 'lucide-react';
 import { ArrowSquareOutIcon, DotsThreeVerticalIcon, PencilSimpleIcon, TrashIcon } from '@phosphor-icons/react';
@@ -10,20 +10,36 @@ import documentCardPlaceholder from '@/assets/placeholder-document-card.jpg';
 import { getPropertyIconOption } from '@features/document/properties/property-icons';
 import { NotebookTreeFileIcon } from '@features/memo/components/notebook-tree-file-icon';
 import type { TableField, TableRecord } from './model';
+import type { TableNoteDropPreview, TableNoteDropRejection } from './table-note-drop';
+import { TableNoteDropOverlay } from './table-note-drop-overlay';
+import { useTableNoteDropTarget, type TableNoteDropTargetRejection } from './use-table-note-drop-target';
 import { KANBAN_UNASSIGNED_GROUP_ID } from './view-index';
+import { toast } from '@/lib/toast';
+import { useI18n } from '@/lib/i18n';
+import { beginDragSession, cancelDragSession, endDragSession, moveDragSession, registerDropTarget, suppressTextSelectionForDrag } from '@shared/drag-drop/drag-drop-coordinator';
+import type { DragPayload, DropPreview } from '@shared/drag-drop/drag-drop-coordinator';
+import { isMarkdownNoteDragResource, type NotebookNoteDragResource } from '@features/memo/public/drag-resource-api';
 
 type ValueRenderer = (record: TableRecord, field: TableField) => string;
 type MoveRecord = (recordId: string, fieldId: string, value: string) => void;
 type DropKanbanRecord = (recordId: string, groupId: string, beforeRecordId: string | null) => void | Promise<void>;
+interface KanbanRecordDragResource { kind: 'kanban-record'; recordId: string }
+type KanbanDragItem = NotebookNoteDragResource | KanbanRecordDragResource;
+interface KanbanDropLocation { groupId: string; beforeRecordId: string | null }
+interface GalleryDropLocation { beforeRecordId: string | null }
 
-function formatCalendarTime(value: unknown): string | null {
-  if (typeof value !== 'string') return null;
-  const match = /^\d{4}-\d{2}-\d{2}[T ](\d{2}):(\d{2})/.exec(value);
-  if (!match) return null;
-  const hours = Number(match[1]);
-  const minutes = Number(match[2]);
-  if (hours > 23 || minutes > 59) return null;
-  return new Date(2000, 0, 1, hours, minutes).toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+function isKanbanRecordDragResource(item: unknown): item is KanbanRecordDragResource {
+  if (!item || typeof item !== 'object') return false;
+  const resource = item as Partial<KanbanRecordDragResource>;
+  return resource.kind === 'kanban-record' && typeof resource.recordId === 'string';
+}
+
+function calendarCardColorStyle(color?: string): CSSProperties | undefined {
+  if (!color) return undefined;
+  return {
+    '--multidimensional-table-calendar-card-background': `color-mix(in oklch, ${color} 20%, transparent)`,
+    '--multidimensional-table-calendar-card-hover-background': `color-mix(in oklch, ${color} 30%, transparent)`,
+  } as CSSProperties;
 }
 
 function formatGalleryUpdatedAt(timestamp: string): string {
@@ -42,7 +58,7 @@ function formatGalleryUpdatedAt(timestamp: string): string {
   return `更新 ${Math.floor(elapsedMonths / 12)}年前`;
 }
 
-export function TableGalleryView({ records, titleField, fields, renderValue, imageUrl, noteThumbnail, onOpenRecord, onCreateBlankNote, onChooseData, recordStatus, noteIcon, canAddData = true }: {
+export function TableGalleryView({ records, titleField, fields, renderValue, imageUrl, noteThumbnail, onOpenRecord, onCreateBlankNote, onChooseData, recordStatus, noteIcon, canAddData = true, dropNotebookId, canDropExternal = false, previewExternalNoteDrop, nextRecordId, dropAreaRef, onExternalNoteDrop }: {
   records: TableRecord[];
   titleField: TableField;
   fields: TableField[];
@@ -55,12 +71,95 @@ export function TableGalleryView({ records, titleField, fields, renderValue, ima
   recordStatus?: (record: TableRecord) => 'draft' | 'linked' | 'unknown' | 'missing';
   noteIcon?: (record: TableRecord) => string | null;
   canAddData?: boolean;
+  dropNotebookId?: string | null;
+  canDropExternal?: boolean;
+  previewExternalNoteDrop?: (notes: NotebookNoteDragResource[], beforeRecordId: string | null) => TableNoteDropPreview | TableNoteDropRejection;
+  nextRecordId?: string | null;
+  dropAreaRef?: { current: HTMLElement | null };
+  onExternalNoteDrop?: (notes: NotebookNoteDragResource[], beforeRecordId: string | null) => void | Promise<void>;
 }) {
+  const { t } = useI18n();
+  const galleryId = useId();
+  const galleryRef = useRef<HTMLDivElement | null>(null);
+  const [dropPreview, setDropPreview] = useState<TableNoteDropPreview | null>(null);
   const imageField = fields.find((field) => field.type === 'Image');
 
-  return <div className="multidimensional-table__gallery flex-1 px-5">
-    <div className="multidimensional-table__gallery-grid grid w-full grid-cols-[repeat(auto-fill,minmax(min(100%,200px),1fr))] items-stretch gap-3.5 pt-3">
-      {records.length === 0 && (onCreateBlankNote || onChooseData) ? <div className="col-span-full flex min-h-10 items-center justify-start gap-2 text-sm text-[var(--muted-foreground)]">
+  useEffect(() => {
+    if (!dropPreview) return;
+    galleryRef.current?.querySelector<HTMLElement>('[data-gallery-preview]')?.scrollIntoView?.({ block: 'nearest' });
+  }, [dropPreview]);
+
+  const dropPositionAt = useCallback((x: number, y: number): GalleryDropLocation | null => {
+    const root = galleryRef.current;
+    if (!root) return null;
+    const dropArea = dropAreaRef?.current ?? root;
+    const rootBounds = dropArea.getBoundingClientRect();
+    if (x < rootBounds.left || x > rootBounds.right || y < rootBounds.top || y > rootBounds.bottom) return null;
+    const cards = [...root.querySelectorAll<HTMLElement>('[data-gallery-record]')]
+      .filter((candidate) => {
+        const bounds = candidate.getBoundingClientRect();
+        return bounds.bottom > rootBounds.top && bounds.top < rootBounds.bottom
+          && bounds.right > rootBounds.left && bounds.left < rootBounds.right;
+      });
+    if (!cards.length) return { beforeRecordId: nextRecordId ?? null };
+
+    // DOM hit testing can land on a transparent overlay in embedded workspaces.
+    // Use the gallery/card rectangles so drop detection is independent of the
+    // element under the pointer and still works in the gaps between cards.
+    const card = cards.reduce((nearest, candidate) => {
+      const bounds = candidate.getBoundingClientRect();
+      const nearestBounds = nearest.getBoundingClientRect();
+      const distance = Math.hypot(x - (bounds.left + bounds.width / 2), y - (bounds.top + bounds.height / 2));
+      const nearestDistance = Math.hypot(x - (nearestBounds.left + nearestBounds.width / 2), y - (nearestBounds.top + nearestBounds.height / 2));
+      return distance < nearestDistance ? candidate : nearest;
+    });
+    const index = cards.indexOf(card);
+    const bounds = card.getBoundingClientRect();
+    const insertAfter = x >= bounds.left + bounds.width / 2;
+    const neighboringId = cards[index + (insertAfter ? 1 : 0)]?.dataset.galleryRecord;
+    if (neighboringId) return { beforeRecordId: neighboringId };
+    const recordIndex = records.findIndex((record) => record.id === card.dataset.galleryRecord);
+    return { beforeRecordId: (insertAfter ? records[recordIndex + 1]?.id : undefined) ?? nextRecordId ?? null };
+  }, [dropAreaRef, nextRecordId, records]);
+
+  const previewGalleryDrop = useCallback((notes: NotebookNoteDragResource[], location: GalleryDropLocation) => (
+    previewExternalNoteDrop?.(notes, location.beforeRecordId) ?? { reason: 'unavailable' as const }
+  ), [previewExternalNoteDrop]);
+  const onGalleryDropPreview = useCallback((preview: TableNoteDropPreview | null) => {
+    setDropPreview((current) => preview && current
+      && current.records.length === preview.records.length
+      && current.records.every((record, index) => record.id === preview.records[index].id)
+      && current.draggedPaths.join('\0') === preview.draggedPaths.join('\0') ? current : preview);
+  }, []);
+  const onGalleryDropReject = useCallback((reason: TableNoteDropTargetRejection) => {
+    if (reason === 'unsupported-resource' || reason === 'wrong-notebook' || reason === 'unavailable') {
+      toast.warning(t('memo.fileTree.galleryDropUnsupported'));
+    } else if (reason === 'read-only') {
+      toast.warning(t('multidimensionalTable.galleryDropReadOnly'));
+    } else if (reason === 'filtered') {
+      toast.warning(t('multidimensionalTable.galleryDropFiltered'));
+    }
+  }, [t]);
+  useTableNoteDropTarget({
+    id: `gallery:${galleryId}`,
+    active: true,
+    notebookId: dropNotebookId ?? null,
+    canDrop: canDropExternal,
+    canHandleDrop: Boolean(previewExternalNoteDrop && onExternalNoteDrop),
+    hitTest: ({ x, y }) => dropPositionAt(x, y),
+    locationKey: ({ beforeRecordId }) => beforeRecordId ?? 'end',
+    preview: previewGalleryDrop,
+    onPreview: onGalleryDropPreview,
+    onDrop: (notes, location) => onExternalNoteDrop?.(notes, location.beforeRecordId),
+    onReject: onGalleryDropReject,
+    onError: (error) => toast.error(error instanceof Error ? error.message : t('multidimensionalTable.galleryDropFailed')),
+  });
+
+  const renderedRecords = dropPreview?.records ?? records;
+
+  return <div ref={galleryRef} className="multidimensional-table__gallery relative flex-1 px-5">
+    <div className="multidimensional-table__gallery-grid grid w-full grid-cols-[repeat(auto-fill,minmax(min(100%,160px),1fr))] items-stretch gap-3.5 pt-3">
+      {renderedRecords.length === 0 && (onCreateBlankNote || onChooseData) ? <div className="col-span-full flex min-h-10 items-center justify-start gap-2 text-sm text-[var(--muted-foreground)]">
         {onCreateBlankNote && <button
           type="button"
           disabled={!canAddData}
@@ -100,14 +199,15 @@ export function TableGalleryView({ records, titleField, fields, renderValue, ima
           <span>选择数据</span>
         </button>}
       </div>}
-      {records.map((record) => {
+      {renderedRecords.map((record) => {
         const cover = imageField ? imageUrl(record, imageField) : null;
         const notePreview = noteThumbnail?.(record) ?? null;
         const imageSources = [...new Set([notePreview, cover, documentCardPlaceholder].filter((source): source is string => Boolean(source)))];
         const missing = recordStatus?.(record) === 'missing';
         const iconValue = noteIcon?.(record);
         const icon = iconValue ? getPropertyIconOption(iconValue) : null;
-        return <button key={record.id} type="button" onClick={(event) => onOpenRecord(record, event.currentTarget.getBoundingClientRect())} className="group flex h-[210px] min-w-0 flex-col overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--card)] text-left transition-[background-color,border-color] hover:border-[color-mix(in_oklch,var(--border)_94%,var(--foreground)_6%)] hover:bg-[color-mix(in_oklch,var(--card)_98%,var(--foreground)_2%)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]">
+        const isPreview = dropPreview?.draggedPaths.includes(record.note_path.replace(/\\/g, '/')) ?? false;
+        return <button key={record.id} data-gallery-record={isPreview ? undefined : record.id} data-gallery-preview={isPreview ? 'true' : undefined} aria-hidden={isPreview || undefined} tabIndex={isPreview ? -1 : undefined} type="button" onClick={(event) => { if (!isPreview) onOpenRecord(record, event.currentTarget.getBoundingClientRect()); }} className={`group flex h-[210px] min-w-0 flex-col overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--card)] text-left transition-[background-color,border-color] hover:border-[color-mix(in_oklch,var(--border)_94%,var(--foreground)_6%)] hover:bg-[color-mix(in_oklch,var(--card)_98%,var(--foreground)_2%)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] ${isPreview ? 'pointer-events-none opacity-50' : ''}`}>
           <span className="flex h-[148px] w-full shrink-0 items-center justify-center overflow-hidden border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--card)_97%,var(--foreground)_3%)]">
             <img
               src={imageSources[0]}
@@ -126,13 +226,15 @@ export function TableGalleryView({ records, titleField, fields, renderValue, ima
               }}
             />
           </span>
-          <span className="flex h-[61px] min-w-0 items-start gap-1 px-3 py-2.5">
-            {icon
-              ? <img src={icon.src} alt="" aria-hidden="true" draggable={false} className="mt-0.5 h-4 w-4 shrink-0 object-contain" />
-              : <NotebookTreeFileIcon className='mt-0.5 h-4 w-4 shrink-0 text-[color-mix(in_oklch,var(--foreground)_70%,black_30%)] [[data-theme="dark"]_&]:text-[var(--foreground)]' />}
+          <span className="flex h-[61px] min-w-0 px-2 py-2.5">
             <span className="min-w-0 flex-1">
-              <span className={`block truncate text-[13px] font-medium leading-5 ${missing ? 'text-[var(--muted-foreground)]' : 'text-[var(--foreground)]'}`}>{renderValue(record, titleField)}</span>
-              <span className="mt-0.5 block truncate text-[11px] leading-4 text-[var(--muted-foreground)]">
+              <span className="flex min-w-0 items-center gap-1">
+                {icon
+                  ? <img src={icon.src} alt="" aria-hidden="true" draggable={false} className="h-4 w-4 shrink-0 object-contain" />
+                  : <NotebookTreeFileIcon className='h-4 w-4 shrink-0 text-[color-mix(in_oklch,var(--foreground)_70%,black_30%)] [[data-theme="dark"]_&]:text-[var(--foreground)]' />}
+                <span className={`block min-w-0 truncate text-sm font-medium leading-5 ${missing ? 'text-[var(--muted-foreground)]' : 'text-[var(--foreground)]'}`}>{renderValue(record, titleField)}</span>
+              </span>
+              <span className="mt-0.5 block truncate text-xs leading-4 text-[var(--muted-foreground)]">
                 {formatGalleryUpdatedAt(record.updated_at)}
               </span>
             </span>
@@ -140,17 +242,22 @@ export function TableGalleryView({ records, titleField, fields, renderValue, ima
         </button>;
       })}
     </div>
+    <TableNoteDropOverlay active={Boolean(dropPreview)} dropAreaRef={dropAreaRef ?? galleryRef} />
   </div>;
 }
 
-export function TableKanbanView({ groupField, titleField, records, groups, renderValue, recordStatus, onDropRecord, onReorderLane, onAddTask, onAddLane, onOpenRecord, onRenameRecord, onDeleteRecord, canAddTask = true, canAddLane = true, embeddedInEditor = false }: {
+export function TableKanbanView({ groupField, titleField, records, groups, renderValue, recordStatus, noteIconForRecord, onDropRecord, onExternalNoteDrop, dropNotebookId, canDropExternal = false, onReorderLane, onAddTask, onAddLane, onOpenRecord, onRenameRecord, onDeleteRecord, canAddTask = true, canAddLane = true, embeddedInEditor = false }: {
   groupField: TableField;
   titleField: TableField;
   records?: TableRecord[];
   groups: ReadonlyMap<string, TableRecord[]>;
   renderValue: ValueRenderer;
   recordStatus?: (record: TableRecord) => 'draft' | 'linked' | 'unknown' | 'missing';
+  noteIconForRecord?: (record: TableRecord) => string | null | undefined;
   onDropRecord: DropKanbanRecord;
+  onExternalNoteDrop?: (notes: NotebookNoteDragResource[], groupId: string, beforeRecordId: string | null) => void | Promise<void>;
+  dropNotebookId?: string | null;
+  canDropExternal?: boolean;
   onReorderLane: (sourceOptionId: string, targetOptionId: string, insertAfter: boolean) => void;
   onAddTask?: (groupId: string) => void;
   onAddLane?: () => void;
@@ -161,6 +268,7 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
   canAddLane?: boolean;
   embeddedInEditor?: boolean;
 }) {
+  const { t } = useI18n();
   const [draggingRecordId, setDraggingRecordId] = useState<string | null>(null);
   const [editingRecord, setEditingRecord] = useState<TableRecord | null>(null);
   const [editingTitle, setEditingTitle] = useState('');
@@ -169,11 +277,22 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
   const [draggingLaneId, setDraggingLaneId] = useState<string | null>(null);
   const [laneDropTarget, setLaneDropTarget] = useState<{ optionId: string; insertAfter: boolean } | null>(null);
   const [unassignedCollapsed, setUnassignedCollapsed] = useState(false);
+  const [externalDropPreview, setExternalDropPreview] = useState<{ groupId: string; beforeRecordId: string | null; label: string } | null>(null);
   const kanbanBoardRef = useRef<HTMLDivElement | null>(null);
   const lanePointerDragRef = useRef<{ pointerId: number; optionId: string; startX: number; startY: number; active: boolean } | null>(null);
-  const pointerDragRef = useRef<{ pointerId: number; recordId: string; startX: number; startY: number; active: boolean } | null>(null);
+  const laneSelectionReleaseRef = useRef<(() => void) | null>(null);
+  const pointerDragRef = useRef<{ pointerId: number; recordId: string; sessionId: string; startX: number; startY: number; active: boolean } | null>(null);
+  useEffect(() => () => {
+    const drag = pointerDragRef.current;
+    if (drag?.active) cancelDragSession(drag.sessionId);
+    laneSelectionReleaseRef.current?.();
+    laneSelectionReleaseRef.current = null;
+  }, []);
   const pointerPositionRef = useRef({ x: 0, y: 0 });
   const floatingCardRef = useRef<HTMLElement | null>(null);
+  const kanbanTargetId = useId();
+  const externalDropConfigRef = useRef({ groupField, dropNotebookId, canDropExternal, onExternalNoteDrop, onDropRecord });
+  externalDropConfigRef.current = { groupField, dropNotebookId, canDropExternal, onExternalNoteDrop, onDropRecord };
   const laneOptions = groupField.options ?? [];
   const allRecords = useMemo(() => records ?? [...new Map([...groups.values()].flat().map((record) => [record.id, record])).values()], [groups, records]);
   const assignedRecordIds = new Set(laneOptions.flatMap((option) => groups.get(option.id) ?? []).map((record) => record.id));
@@ -188,14 +307,15 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
   const renderRecordCard = (record: TableRecord) => {
     const status = recordStatus?.(record);
     const title = renderValue(record, titleField);
+    const displayTitle = status === 'missing' ? title.replace(/^未找到笔记\s*/, '') : title;
     return <article key={record.id} data-kanban-record={record.id} onPointerDown={(event) => {
       if ((event.target as HTMLElement).closest('button')) return;
       onCardPointerDown(event, record.id);
     }} className={`multidimensional-table__kanban-card relative cursor-default select-none touch-none rounded-lg border border-[var(--border)] px-2 py-2 active:cursor-grabbing ${draggingRecordId === record.id ? 'opacity-50' : ''}`}>
       <div className="flex min-w-0 items-center gap-2">
-        <div className={`min-w-0 flex-1 break-words text-sm font-medium leading-5 ${(onRenameRecord || onDeleteRecord) ? 'pr-7' : ''} ${status === 'missing' ? 'text-[var(--muted-foreground)]' : 'text-[var(--foreground)]'}`}>
+        <div className={`min-w-0 flex-1 text-sm font-medium leading-5 ${(onRenameRecord || onDeleteRecord) ? 'pr-7' : ''} ${status === 'missing' ? 'text-[var(--muted-foreground)]' : 'text-[var(--foreground)]'}`}>
           {status === 'missing' && <span className="mr-1">未找到</span>}
-          {status === 'missing' ? title.replace(/^未找到笔记\s*/, '') : title}
+          <TableRecordTitle record={record} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} label={displayTitle} titleClassName="min-w-0 break-words" />
         </div>
         {(onOpenRecord || onRenameRecord || onDeleteRecord) && <DropdownMenu>
           <DropdownMenuTrigger asChild>
@@ -234,11 +354,106 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
     const element = document.elementFromPoint(x, y) as HTMLElement | null;
     const lane = element?.closest<HTMLElement>('[data-kanban-lane]');
     const targetOptionId = lane?.dataset.kanbanLane;
-    if (!lane || !targetOptionId || targetOptionId === sourceOptionId) return null;
+    if (!lane || !kanbanBoardRef.current?.contains(lane) || !targetOptionId || targetOptionId === sourceOptionId) return null;
     const bounds = lane.getBoundingClientRect();
     return { optionId: targetOptionId, insertAfter: x >= bounds.left + bounds.width / 2 };
   };
 
+  const dropLocationAt = useCallback((x: number, y: number): KanbanDropLocation | null => {
+    const element = document.elementFromPoint(x, y) as HTMLElement | null;
+    const draggedRecordId = pointerDragRef.current?.active ? pointerDragRef.current.recordId : null;
+    if (draggedRecordId && element?.closest<HTMLElement>('[data-kanban-record]')?.dataset.kanbanRecord === draggedRecordId) return null;
+    const lane = element?.closest<HTMLElement>('[data-kanban-lane], [data-kanban-unassigned="true"]');
+    const groupId = lane?.dataset.kanbanLane
+      ?? (lane?.dataset.kanbanUnassigned === 'true' ? KANBAN_UNASSIGNED_GROUP_ID : null);
+    if (!lane || !kanbanBoardRef.current?.contains(lane) || !groupId) return null;
+    const beforeCard = [...lane.querySelectorAll<HTMLElement>('[data-kanban-record]')]
+      .filter((card) => card.dataset.kanbanRecord !== draggedRecordId)
+      .find((card) => {
+        const bounds = card.getBoundingClientRect();
+        return y < bounds.top + bounds.height / 2;
+      });
+    return { groupId, beforeRecordId: beforeCard?.dataset.kanbanRecord ?? null };
+  }, []);
+
+  useEffect(() => registerDropTarget<KanbanDragItem, KanbanDropLocation>({
+    id: `kanban:${kanbanTargetId}`,
+    priority: 100,
+    hitTest: ({ x, y }) => dropLocationAt(x, y),
+    locationKey: ({ groupId, beforeRecordId }) => `${groupId}:${beforeRecordId ?? ''}`,
+    evaluate: (payload, location) => {
+      const config = externalDropConfigRef.current;
+      const records = payload.items.filter(isKanbanRecordDragResource);
+      if (records.length === payload.items.length) {
+        if (records.length !== 1) return { accepted: false, reason: 'unsupported-resource' };
+        if (!config.canDropExternal) return { accepted: false, reason: 'read-only' };
+        if (location.groupId !== KANBAN_UNASSIGNED_GROUP_ID
+          && (!config.groupField.options?.some((option) => option.id === location.groupId) || !config.groupField.property_key)) {
+          return { accepted: false, reason: 'unavailable' };
+        }
+        return { accepted: true };
+      }
+      const notes = payload.items.filter(isMarkdownNoteDragResource);
+      if (notes.length === 0 || notes.length !== payload.items.length) {
+        return { accepted: false, reason: 'unsupported-resource' };
+      }
+      if (!config.dropNotebookId || notes.some((note) => note.notebookId !== config.dropNotebookId)) {
+        return { accepted: false, reason: 'wrong-notebook' };
+      }
+      if (!config.canDropExternal) return { accepted: false, reason: 'read-only' };
+      if (location.groupId !== KANBAN_UNASSIGNED_GROUP_ID
+        && (!config.groupField.options?.some((option) => option.id === location.groupId) || !config.groupField.property_key)) {
+        return { accepted: false, reason: 'unavailable' };
+      }
+      if (!config.onExternalNoteDrop) return { accepted: false, reason: 'unavailable' };
+      return { accepted: true };
+    },
+    onPreview: (preview: DropPreview<KanbanDragItem, KanbanDropLocation> | null) => {
+      if (!preview?.decision.accepted) {
+        setExternalDropPreview(null);
+        setDropTarget(null);
+        if (!pointerDragRef.current?.active) setDraggingRecordId(null);
+        return;
+      }
+      const records = preview.payload.items.filter(isKanbanRecordDragResource);
+      if (records.length === 1 && records.length === preview.payload.items.length) {
+        setExternalDropPreview(null);
+        setDraggingRecordId(records[0].recordId);
+        setDropTarget(preview.location);
+        return;
+      }
+      const notes = preview.payload.items.filter(isMarkdownNoteDragResource);
+      const next = {
+        groupId: preview.location.groupId,
+        beforeRecordId: preview.location.beforeRecordId,
+        label: notes.length === 1 ? notes[0].title : `${notes.length} 篇笔记`,
+      };
+      setDraggingRecordId(null);
+      setDropTarget(null);
+      setExternalDropPreview((current) => current?.groupId === next.groupId
+        && current?.beforeRecordId === next.beforeRecordId && current?.label === next.label ? current : next);
+    },
+    onDrop: (payload, location) => {
+      const records = payload.items.filter(isKanbanRecordDragResource);
+      if (records.length === 1 && records.length === payload.items.length) {
+        return externalDropConfigRef.current.onDropRecord?.(records[0].recordId, location.groupId, location.beforeRecordId);
+      }
+      return externalDropConfigRef.current.onExternalNoteDrop?.(
+        payload.items.filter(isMarkdownNoteDragResource), location.groupId, location.beforeRecordId,
+      );
+    },
+    onReject: (_payload, _groupId, reason) => {
+      if (reason === 'unsupported-resource' || reason === 'wrong-notebook') {
+        toast.warning(t('memo.fileTree.kanbanDropUnsupported'));
+      } else if (reason === 'read-only') {
+        toast.warning(t('multidimensionalTable.kanbanDropReadOnly'));
+      } else if (reason === 'unavailable') {
+        toast.warning(t('multidimensionalTable.kanbanDropUnavailable'));
+      }
+    },
+    onError: (error) => toast.error(error instanceof Error ? error.message : t('multidimensionalTable.kanbanDropFailed')),
+  }), [dropLocationAt, kanbanTargetId, t]);
+
   const onLanePointerDown = (event: PointerEvent<HTMLElement>, optionId: string) => {
     if (event.button !== 0) return;
     event.preventDefault();
@@ -252,6 +467,7 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
     if (!drag.active) {
       if (Math.hypot(event.clientX - drag.startX, event.clientY - drag.startY) < 6) return;
       drag.active = true;
+      laneSelectionReleaseRef.current = suppressTextSelectionForDrag();
       setDraggingLaneId(drag.optionId);
     }
     const target = laneTargetAt(event.clientX, event.clientY, drag.optionId);
@@ -262,8 +478,11 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
     const drag = lanePointerDragRef.current;
     if (!drag || drag.pointerId !== event.pointerId) return;
     if (drag.active) {
-      const hoveredLaneId = (document.elementFromPoint(event.clientX, event.clientY) as HTMLElement | null)
-        ?.closest<HTMLElement>('[data-kanban-lane]')?.dataset.kanbanLane;
+      const hoveredLane = (document.elementFromPoint(event.clientX, event.clientY) as HTMLElement | null)
+        ?.closest<HTMLElement>('[data-kanban-lane]');
+      const hoveredLaneId = hoveredLane && kanbanBoardRef.current?.contains(hoveredLane)
+        ? hoveredLane.dataset.kanbanLane
+        : undefined;
       const target = laneTargetAt(event.clientX, event.clientY, drag.optionId)
         ?? (hoveredLaneId === drag.optionId ? laneDropTarget : null);
       if (target) onReorderLane(drag.optionId, target.optionId, target.insertAfter);
@@ -271,29 +490,16 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
     lanePointerDragRef.current = null;
     setDraggingLaneId(null);
     setLaneDropTarget(null);
+    laneSelectionReleaseRef.current?.();
+    laneSelectionReleaseRef.current = null;
   };
 
   const onLanePointerCancel = () => {
     lanePointerDragRef.current = null;
     setDraggingLaneId(null);
     setLaneDropTarget(null);
-  };
-
-  const targetAt = (x: number, y: number, draggedId: string) => {
-    const element = document.elementFromPoint(x, y) as HTMLElement | null;
-    // Dropping onto the dragged card itself is a no-op: keep its origin slot and
-    // suppress the insertion ghost.
-    if (element?.closest<HTMLElement>('[data-kanban-record]')?.dataset.kanbanRecord === draggedId) return null;
-    const lane = element?.closest<HTMLElement>('[data-kanban-lane], [data-kanban-unassigned="true"]');
-    const groupId = lane?.dataset.kanbanLane ?? (lane?.dataset.kanbanUnassigned === 'true' ? KANBAN_UNASSIGNED_GROUP_ID : undefined);
-    if (!lane || !groupId) return null;
-    const beforeCard = [...lane.querySelectorAll<HTMLElement>('[data-kanban-record]')]
-      .filter((card) => card.dataset.kanbanRecord !== draggedId)
-      .find((card) => {
-        const bounds = card.getBoundingClientRect();
-        return y < bounds.top + bounds.height / 2;
-      });
-    return { groupId, beforeRecordId: beforeCard?.dataset.kanbanRecord ?? null };
+    laneSelectionReleaseRef.current?.();
+    laneSelectionReleaseRef.current = null;
   };
 
   const resetDrag = () => {
@@ -302,10 +508,16 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
     setDropTarget(null);
   };
 
+  const cancelKanbanDrag = () => {
+    const drag = pointerDragRef.current;
+    if (drag?.active) cancelDragSession(drag.sessionId);
+    else resetDrag();
+  };
+
   const onCardPointerDown = (event: PointerEvent<HTMLElement>, recordId: string) => {
     if (event.button !== 0) return;
     event.preventDefault();
-    pointerDragRef.current = { pointerId: event.pointerId, recordId, startX: event.clientX, startY: event.clientY, active: false };
+    pointerDragRef.current = { pointerId: event.pointerId, recordId, sessionId: crypto.randomUUID(), startX: event.clientX, startY: event.clientY, active: false };
     kanbanBoardRef.current?.setPointerCapture?.(event.pointerId);
   };
 
@@ -321,33 +533,29 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
       if (Math.hypot(event.clientX - drag.startX, event.clientY - drag.startY) < 6) return;
       drag.active = true;
       setDraggingRecordId(drag.recordId);
+      beginDragSession({
+        sessionId: drag.sessionId,
+        sourceId: `kanban:${kanbanTargetId}`,
+        items: [{ kind: 'kanban-record', recordId: drag.recordId }],
+      }, { x: event.clientX, y: event.clientY }, resetDrag);
     }
-    setDropTarget(targetAt(event.clientX, event.clientY, drag.recordId));
+    moveDragSession(drag.sessionId, { x: event.clientX, y: event.clientY });
   };
 
   const onCardPointerUp = (event: PointerEvent<HTMLElement>) => {
     const drag = pointerDragRef.current;
     if (!drag || drag.pointerId !== event.pointerId) return;
     if (drag.active) {
-      const target = targetAt(event.clientX, event.clientY, drag.recordId);
-      if (target) {
-        // Drop synchronously, then clear the drag UI right away so the floating
-        // preview disappears with the pointerup, even if the write is async.
-        let result: unknown;
-        try { result = onDropRecord(drag.recordId, target.groupId, target.beforeRecordId); }
-        catch { result = null; }
-        resetDrag();
-        void Promise.resolve(result).catch(() => {});
-        return;
-      }
-    } else {
-      const record = allRecords.find((item) => item.id === drag.recordId);
-      if (record && recordStatus?.(record) === 'linked') onOpenRecord?.(drag.recordId);
+      endDragSession(drag.sessionId, { x: event.clientX, y: event.clientY });
+      resetDrag();
+      return;
     }
+    const record = allRecords.find((item) => item.id === drag.recordId);
     resetDrag();
+    if (record && recordStatus?.(record) === 'linked') onOpenRecord?.(drag.recordId);
   };
 
-  return <div ref={kanbanBoardRef} onPointerMove={onCardPointerMove} onPointerUp={onCardPointerUp} onPointerCancel={resetDrag} className="flex min-h-0 flex-1 flex-col">
+  return <div ref={kanbanBoardRef} onPointerMove={onCardPointerMove} onPointerUp={onCardPointerUp} onPointerCancel={cancelKanbanDrag} className="flex min-h-0 flex-1 flex-col">
     <div className={`multidimensional-table__kanban-lanes flex w-max items-stretch gap-3 ${embeddedInEditor ? 'px-5 py-3' : 'px-4 py-1'}`}>
       <section data-kanban-unassigned="true" className={`multidimensional-table__kanban-lane flex shrink-0 flex-col rounded-xl border border-[var(--border)] ${unassignedCollapsed ? 'w-10 min-w-10 max-w-10' : 'w-64'}`}>
         <header className={`flex min-h-10 items-center gap-3 ${unassignedCollapsed ? 'w-full min-w-0 flex-col px-1.5 pt-3 pb-1.5' : 'justify-between px-3.5 pt-3.5 pb-1.5'}`}>
@@ -364,8 +572,16 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
           </>}
         </header>
         {!unassignedCollapsed && <div className="multidimensional-table__kanban-lane-content min-h-0 overflow-y-auto flex flex-col gap-2 px-2.5 pt-[5px] pb-4">
-          {visibleUnassignedRecords.map(renderRecordCard)}
-          {unassignedRecords.length === 0 && <div className="multidimensional-table__kanban-empty pointer-events-none flex min-h-24 select-none items-center justify-center rounded-lg border border-dashed border-[var(--border)] px-4 text-center text-xs text-[var(--muted-foreground)]">无未分配数据</div>}
+          {visibleUnassignedRecords.map((record) => <Fragment key={record.id}>
+            {externalDropPreview?.groupId === KANBAN_UNASSIGNED_GROUP_ID && externalDropPreview.beforeRecordId === record.id && <article aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none rounded-lg border border-[var(--border)] px-2 py-2 opacity-50">
+              <div className="min-w-0 break-words text-sm font-medium leading-5 text-[var(--foreground)]">{externalDropPreview.label}</div>
+            </article>}
+            {renderRecordCard(record)}
+          </Fragment>)}
+          {externalDropPreview?.groupId === KANBAN_UNASSIGNED_GROUP_ID && externalDropPreview.beforeRecordId === null && <article aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none rounded-lg border border-[var(--border)] px-2 py-2 opacity-50">
+            <div className="min-w-0 break-words text-sm font-medium leading-5 text-[var(--foreground)]">{externalDropPreview.label}</div>
+          </article>}
+          {unassignedRecords.length === 0 && externalDropPreview?.groupId !== KANBAN_UNASSIGNED_GROUP_ID && <div className="multidimensional-table__kanban-empty pointer-events-none flex min-h-24 select-none items-center justify-center rounded-lg border border-dashed border-[var(--border)] px-4 text-center text-xs text-[var(--muted-foreground)]">无未分配数据</div>}
         </div>}
       </section>
       {previewLaneOptions.map((option) => {
@@ -382,15 +598,21 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
           </header>
           <div className="multidimensional-table__kanban-lane-content min-h-0 overflow-y-auto flex flex-col gap-2 px-2.5 pt-[5px] pb-4">
             {visibleGroup.map((record) => <Fragment key={record.id}>
+                {externalDropPreview?.groupId === option.id && externalDropPreview.beforeRecordId === record.id && <article aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none rounded-lg border border-[var(--border)] px-2 py-2 opacity-50">
+                  <div className="min-w-0 break-words text-sm font-medium leading-5 text-[var(--foreground)]">{externalDropPreview.label}</div>
+                </article>}
                 {showInsertionPreview && draggedRecord && dropTarget?.groupId === option.id && dropTarget.beforeRecordId === record.id && <article aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none rounded-lg border border-[var(--border)] px-2 py-2 opacity-50">
-                  <div className="break-words text-sm font-medium leading-5 text-[var(--foreground)]">{renderValue(draggedRecord, titleField)}</div>
+                  <TableRecordTitle record={draggedRecord} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} titleClassName="min-w-0 break-words" className="text-sm font-medium leading-5 text-[var(--foreground)]" />
                 </article>}
                 {renderRecordCard(record)}
               </Fragment>)}
             {showEndPreview && draggedRecord && <article aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none rounded-lg border border-[var(--border)] px-2 py-2 opacity-50">
-              <div className="break-words text-sm font-medium leading-5 text-[var(--foreground)]">{renderValue(draggedRecord, titleField)}</div>
+              <TableRecordTitle record={draggedRecord} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} titleClassName="min-w-0 break-words" className="text-sm font-medium leading-5 text-[var(--foreground)]" />
+            </article>}
+            {externalDropPreview?.groupId === option.id && externalDropPreview.beforeRecordId === null && <article aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none rounded-lg border border-[var(--border)] px-2 py-2 opacity-50">
+              <div className="min-w-0 break-words text-sm font-medium leading-5 text-[var(--foreground)]">{externalDropPreview.label}</div>
             </article>}
-            {visibleGroup.length === 0 && !showEndPreview && <div className="multidimensional-table__kanban-empty pointer-events-none flex min-h-24 select-none items-center justify-center rounded-lg border border-dashed border-[var(--border)] px-4 text-center text-xs text-[var(--muted-foreground)]">拖动记录到此处</div>}
+            {visibleGroup.length === 0 && !showEndPreview && externalDropPreview?.groupId !== option.id && <div className="multidimensional-table__kanban-empty pointer-events-none flex min-h-24 select-none items-center justify-center rounded-lg border border-dashed border-[var(--border)] px-4 text-center text-xs text-[var(--muted-foreground)]">拖动记录到此处</div>}
           </div>
         </section>;
       })}
@@ -407,7 +629,7 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
     </div>
     {draggedRecord && typeof document !== 'undefined' && createPortal(
       <article ref={floatingCardRef} data-kanban-floating-preview aria-hidden="true" className="multidimensional-table__kanban-card pointer-events-none fixed z-[1000] w-[252px] select-none rounded-lg border border-[var(--border)] px-2 py-2 shadow-lg" style={{ left: pointerPositionRef.current.x + 14, top: pointerPositionRef.current.y + 14 }}>
-        <div className="break-words text-sm font-medium leading-5 text-[var(--foreground)]">{renderValue(draggedRecord, titleField)}</div>
+        <TableRecordTitle record={draggedRecord} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} titleClassName="min-w-0 break-words" className="text-sm font-medium leading-5 text-[var(--foreground)]" />
       </article>, document.body)}
     <Dialog open={Boolean(editingRecord)} onOpenChange={(open) => { if (!open && !savingEdit) setEditingRecord(null); }}>
       <DialogContent className="rounded-xl border border-[var(--border-popup)] bg-[var(--card)] shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
@@ -428,7 +650,7 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
           <div className="mt-4 flex justify-end gap-2">
             <Button type="button" variant="outline" disabled={savingEdit} onClick={() => setEditingRecord(null)}>取消</Button>
             <Button type="submit" disabled={!editingTitle.trim() || savingEdit}>
-              {savingEdit && <LoaderCircle className="mr-1.5 h-4 w-4 animate-spin" aria-hidden="true" />}
+              {savingEdit && <LoaderCircle className="mr-1.5 h-4 w-4 flowix-spin" aria-hidden="true" />}
               {savingEdit ? '保存中…' : '保存'}
             </Button>
           </div>
@@ -438,7 +660,24 @@ export function TableKanbanView({ groupField, titleField, records, groups, rende
   </div>;
 }
 
-export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFieldId, dateFieldLabel = '', dateFieldOptions = [], onDateFieldChange, onCustomDateField, titleField, renderValue, dateValueForRecord, weekStart = 0, onWeekStartChange, onMoveRecord, onOpenRecord, canMoveRecords = true, dateFieldReadOnly = !canMoveRecords, dateFieldReadOnlyReason = '当前日期字段为只读状态', onDoubleClickDate, addingNoteDate, embeddedInEditor = false }: {
+function TableRecordTitle({ record, titleField, renderValue, noteIconForRecord, className = '', titleClassName = 'min-w-0 truncate', label }: {
+  record: TableRecord;
+  titleField: TableField;
+  renderValue: ValueRenderer;
+  noteIconForRecord?: (record: TableRecord) => string | null | undefined;
+  className?: string;
+  titleClassName?: string;
+  label?: string;
+}) {
+  const iconValue = noteIconForRecord?.(record);
+  const icon = iconValue ? getPropertyIconOption(iconValue) : null;
+  return <span className={`flex min-w-0 items-center gap-1 ${className}`}>
+    {icon && <img src={icon.src} alt="" aria-hidden="true" draggable={false} className="h-4 w-4 shrink-0 object-contain" />}
+    <span className={titleClassName}>{label ?? renderValue(record, titleField)}</span>
+  </span>;
+}
+
+export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFieldId, dateFieldLabel = '', dateFieldOptions = [], embeddedInEditor = false, onDateFieldChange, onCustomDateField, titleField, renderValue, dateValueForRecord, noteColorForRecord, noteIconForRecord, weekStart = 0, onWeekStartChange, onMoveRecord, onOpenRecord, onEditRecord, canMoveRecords = true, dateFieldReadOnly = !canMoveRecords, dateFieldReadOnlyReason = '当前日期字段为只读状态', onDoubleClickDate, addingNoteDate, dropNotebookId, onExternalNoteDrop }: {
   cursor: Date;
   onCursorChange: (date: Date) => void;
   days: Array<{ date: Date; iso: string; inMonth: boolean }>;
@@ -452,16 +691,22 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
   titleField: TableField;
   renderValue: ValueRenderer;
   dateValueForRecord?: (record: TableRecord) => unknown;
+  noteColorForRecord?: (record: TableRecord) => string | undefined;
+  noteIconForRecord?: (record: TableRecord) => string | null | undefined;
   weekStart?: 0 | 1;
   onWeekStartChange?: (weekStart: 0 | 1) => void | Promise<void>;
   onMoveRecord: MoveRecord;
   onOpenRecord?: (recordId: string) => void;
+  onEditRecord?: (recordId: string, anchorRect: DOMRect) => void;
   canMoveRecords?: boolean;
   dateFieldReadOnly?: boolean;
   dateFieldReadOnlyReason?: string;
   onDoubleClickDate?: (date: string, anchorRect: DOMRect) => void;
   addingNoteDate?: string | null;
+  dropNotebookId?: string | null;
+  onExternalNoteDrop?: (notes: NotebookNoteDragResource[], date: string) => void | Promise<void>;
 }) {
+  const { t } = useI18n();
   const [weekStartMenuOpen, setWeekStartMenuOpen] = useState(false);
   const weekdayLabels = weekStart === 1
     ? ['星期一', '星期二', '星期三', '星期四', '星期五', '星期六', '星期日']
@@ -471,10 +716,19 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
   const previewLimit = days.length >= 42 ? 1 : days.length >= 35 ? 2 : 3;
   const [draggingRecord, setDraggingRecord] = useState<TableRecord | null>(null);
   const [dropDate, setDropDate] = useState<string | null>(null);
+  const [externalDropPreview, setExternalDropPreview] = useState<{ date: string; label: string } | null>(null);
+  const calendarTargetId = useId();
+  const externalDropConfigRef = useRef({ dropNotebookId, canMoveRecords, onExternalNoteDrop, dateFieldReadOnlyReason });
+  externalDropConfigRef.current = { dropNotebookId, canMoveRecords, onExternalNoteDrop, dateFieldReadOnlyReason };
   const calendarRef = useRef<HTMLDivElement | null>(null);
   const floatingCardRef = useRef<HTMLDivElement | null>(null);
   const pointerPositionRef = useRef({ x: 0, y: 0 });
+  const selectionReleaseRef = useRef<(() => void) | null>(null);
   const pointerDragRef = useRef<{ pointerId: number; record: TableRecord; sourceDate: string; startX: number; startY: number; active: boolean } | null>(null);
+  useEffect(() => () => {
+    selectionReleaseRef.current?.();
+    selectionReleaseRef.current = null;
+  }, []);
 
   const onCellDoubleClick = (event: MouseEvent<HTMLDivElement>, date: string) => {
     const interactiveTarget = (event.target as HTMLElement).closest('[data-calendar-record], button, a, input, textarea, [contenteditable="true"]');
@@ -484,15 +738,64 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
     onDoubleClickDate?.(date, event.currentTarget.getBoundingClientRect());
   };
 
-  const dateAt = (x: number, y: number): string | null => {
+  const dateAt = useCallback((x: number, y: number): string | null => {
     const cell = (document.elementFromPoint(x, y) as HTMLElement | null)?.closest<HTMLElement>('[data-calendar-date]');
     return cell && calendarRef.current?.contains(cell) ? cell.dataset.calendarDate ?? null : null;
-  };
+  }, []);
+
+  useEffect(() => {
+    const noteResources = (payload: DragPayload<unknown>) => payload.items.filter(isMarkdownNoteDragResource);
+    return registerDropTarget<unknown, string>({
+      id: `calendar:${calendarTargetId}`,
+      priority: 100,
+      hitTest: (point) => dateAt(point.x, point.y),
+      locationKey: (date) => date,
+      evaluate: (payload) => {
+        const config = externalDropConfigRef.current;
+        const notes = noteResources(payload);
+        if (notes.length !== payload.items.length || notes.length === 0) {
+          return { accepted: false, reason: 'unsupported-resource' };
+        }
+        if (!config.dropNotebookId || notes.some((note) => note.notebookId !== config.dropNotebookId)) {
+          return { accepted: false, reason: 'wrong-notebook' };
+        }
+        if (!config.canMoveRecords) return { accepted: false, reason: 'read-only' };
+        if (!config.onExternalNoteDrop) return { accepted: false, reason: 'unavailable' };
+        return { accepted: true };
+      },
+      onPreview: (preview) => {
+        if (!preview?.decision.accepted) {
+          setExternalDropPreview(null);
+          return;
+        }
+        const notes = noteResources(preview.payload);
+        const next = {
+          date: preview.location,
+          label: notes.length === 1 ? notes[0].title : `${notes.length} 篇笔记`,
+        };
+        setExternalDropPreview((current) => current?.date === next.date && current?.label === next.label ? current : next);
+      },
+      onDrop: (payload, date) => externalDropConfigRef.current.onExternalNoteDrop?.(noteResources(payload), date),
+      onReject: (_payload, _date, reason) => {
+        const config = externalDropConfigRef.current;
+        if (reason === 'unsupported-resource' || reason === 'wrong-notebook') {
+          toast.warning(t('memo.fileTree.calendarDropUnsupported'));
+        } else if (reason === 'read-only') {
+          toast.warning(config.dateFieldReadOnlyReason || '当前日期字段只读，无法加入日历');
+        } else if (reason === 'unavailable') {
+          toast.warning(t('memo.fileTree.calendarDropUnsupported'));
+        }
+      },
+      onError: (error) => toast.error(error instanceof Error ? error.message : '加入日历失败'),
+    });
+  }, [calendarTargetId, dateAt, t]);
 
   const resetDrag = () => {
     pointerDragRef.current = null;
     setDraggingRecord(null);
     setDropDate(null);
+    selectionReleaseRef.current?.();
+    selectionReleaseRef.current = null;
   };
 
   const onCardPointerDown = (event: PointerEvent<HTMLElement>, record: TableRecord, sourceDate: string) => {
@@ -513,6 +816,7 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
     if (!drag.active) {
       if (Math.hypot(event.clientX - drag.startX, event.clientY - drag.startY) < 6) return;
       drag.active = true;
+      selectionReleaseRef.current = suppressTextSelectionForDrag();
       setDraggingRecord(drag.record);
     }
     const target = dateAt(event.clientX, event.clientY);
@@ -530,13 +834,14 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
         onMoveRecord(drag.record.id, dateFieldId, `${target}${time}`);
       }
     } else {
-      onOpenRecord?.(drag.record.id);
+      if (onEditRecord) onEditRecord(drag.record.id, event.currentTarget.getBoundingClientRect());
+      else onOpenRecord?.(drag.record.id);
     }
     resetDrag();
   };
 
-  return <div ref={calendarRef} className={`multidimensional-table__calendar mx-0 flex min-h-0 flex-1 flex-col pt-0 ${embeddedInEditor ? '' : 'px-4 pb-4'}`}>
-    <header className="flex shrink-0 items-center justify-between pb-1">
+  return <div ref={calendarRef} className="multidimensional-table__calendar mx-0 flex min-h-0 flex-1 flex-col pt-0">
+    <header className={`flex shrink-0 items-center justify-between pb-1 ${embeddedInEditor ? '' : 'px-4'}`}>
       <div className="flex min-w-0 items-center gap-2">
           <DropdownMenu onOpenChange={(open) => { if (!open) setWeekStartMenuOpen(false); }}>
             <DropdownMenuTrigger asChild>
@@ -586,12 +891,13 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
           <button type="button" aria-label="上个月" onClick={() => onCursorChange(new Date(cursor.getFullYear(), cursor.getMonth() - 1, 1))} className="flex h-7 w-7 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]">
             <ChevronLeft className="h-4 w-4" aria-hidden="true" />
           </button>
+          <button type="button" onClick={() => onCursorChange(new Date())} className="h-7 px-2 text-sm text-[var(--muted-foreground)] hover:text-[var(--foreground)]">今天</button>
           <button type="button" aria-label="下个月" onClick={() => onCursorChange(new Date(cursor.getFullYear(), cursor.getMonth() + 1, 1))} className="flex h-7 w-7 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]">
             <ChevronRight className="h-4 w-4" aria-hidden="true" />
           </button>
         </div>
     </header>
-    <div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-[var(--border)] shadow-none">
+    <div className="flex min-h-0 flex-1 flex-col overflow-hidden border-y border-[var(--border)] shadow-none">
       <div className="grid grid-cols-7 border-b border-[var(--border)] text-center text-sm text-[var(--muted-foreground)]">{weekdayLabels.map((day, index) => <div key={`${day}-${index}`} className="border-r border-[var(--border)] py-2 last:border-r-0">{day}</div>)}</div>
       <div className="grid min-h-0 flex-1 grid-cols-7" style={{ gridTemplateRows: `repeat(${days.length / 7}, minmax(var(--multidimensional-table-calendar-day-row-min-height, 0px), 1fr))` }}>
         {days.map(({ date, iso, inMonth }, index) => {
@@ -603,31 +909,30 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
           const records = groups.get(iso) ?? [];
           const hasHiddenRecords = records.length > previewLimit;
           return <Popover key={iso} cellPopup>
-            <div data-flowix-cell-anchor data-calendar-date={iso} data-calendar-drop-target={dropDate === iso ? 'true' : undefined} onDoubleClick={(event) => onCellDoubleClick(event, iso)} style={addingNoteDate === iso ? { backgroundColor: 'var(--multidimensional-table-calendar-active-bg)' } : isToday ? { backgroundColor: 'var(--multidimensional-table-calendar-today-bg)' } : isWeekend ? { backgroundColor: 'var(--multidimensional-table-calendar-weekend-bg)' } : undefined} className={`relative flex h-full min-h-0 w-full flex-col overflow-hidden p-1.5 text-left ${cellBorders} ${inMonth ? '' : 'text-[var(--muted-foreground)]'} ${dropDate === iso ? 'multidimensional-table__calendar-drop-target' : ''}`}>
+            <div data-flowix-cell-anchor data-calendar-date={iso} data-calendar-drop-target={dropDate === iso || externalDropPreview?.date === iso ? 'true' : undefined} onDoubleClick={(event) => onCellDoubleClick(event, iso)} style={dropDate === iso || externalDropPreview?.date === iso ? { backgroundColor: 'var(--multidimensional-table-calendar-drop-bg)' } : addingNoteDate === iso ? { backgroundColor: 'var(--multidimensional-table-calendar-active-bg)' } : isToday ? { backgroundColor: 'var(--multidimensional-table-calendar-today-bg)' } : isWeekend ? { backgroundColor: 'var(--multidimensional-table-calendar-weekend-bg)' } : undefined} className={`relative flex h-full min-h-0 w-full flex-col overflow-hidden p-1.5 text-left ${cellBorders} ${inMonth ? '' : 'text-[var(--muted-foreground)]'} ${dropDate === iso || externalDropPreview?.date === iso ? 'multidimensional-table__calendar-drop-target' : ''}`}>
                 <div className={`absolute left-1.5 top-1.5 text-sm ${inMonth ? '' : 'opacity-50'}`}>{date.getDate()}</div>
                 <div className="mt-6 flex min-h-0 flex-col gap-1 overflow-hidden">
-              {dropDate === iso && draggingRecord && <div aria-hidden="true" className="multidimensional-table__calendar-card pointer-events-none flex items-center overflow-hidden rounded-md border border-[color-mix(in_oklch,var(--brand)_25%,var(--border))] bg-[color-mix(in_oklch,var(--brand)_4%,var(--background))] px-1 py-1 opacity-50">
-                <span className="min-w-0 truncate text-xs text-[var(--foreground)]">{renderValue(draggingRecord, titleField)}</span>
+              {externalDropPreview?.date === iso && <div aria-hidden="true" className="multidimensional-table__calendar-card pointer-events-none flex h-6 items-center overflow-hidden rounded-md border-0 px-1 py-0 opacity-70">
+                <span className="min-w-0 truncate text-xs text-[var(--foreground)]">{externalDropPreview.label}</span>
+              </div>}
+              {dropDate === iso && draggingRecord && <div aria-hidden="true" style={calendarCardColorStyle(noteColorForRecord?.(draggingRecord))} className="multidimensional-table__calendar-card pointer-events-none flex h-6 items-center overflow-hidden rounded-md border-0 px-1 py-0 opacity-50">
+                <TableRecordTitle record={draggingRecord} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} className="text-xs text-[var(--foreground)]" />
               </div>}
               {records.slice(0, previewLimit).map((record) => {
-                const time = formatCalendarTime(dateValueForRecord?.(record));
-                return <div key={record.id} data-calendar-record={record.id} onPointerDown={(event) => onCardPointerDown(event, record, iso)} onPointerMove={onCardPointerMove} onPointerUp={onCardPointerUp} onPointerCancel={resetDrag} onClick={(event) => { if (canMoveRecords) return; event.stopPropagation(); onOpenRecord?.(record.id); }} className={`multidimensional-table__calendar-card flex cursor-default items-center justify-between gap-2 overflow-hidden rounded-md border border-[color-mix(in_oklch,var(--brand)_25%,var(--border))] bg-[color-mix(in_oklch,var(--brand)_4%,var(--background))] px-1 py-1 text-[var(--brand)] ${canMoveRecords ? 'touch-none active:cursor-grabbing' : ''} ${draggingRecord?.id === record.id ? 'opacity-50' : ''}`} title={canMoveRecords ? renderValue(record, titleField) : '创建时间和更新时间不能通过拖动修改'}>
-                  <span className="min-w-0 truncate text-xs font-normal text-[var(--foreground)]">{renderValue(record, titleField)}</span>
-                  {time && <span className="shrink-0 text-[11px] tabular-nums text-[var(--muted-foreground)]">{time}</span>}
+                return <div key={record.id} data-calendar-record={record.id} onPointerDown={(event) => onCardPointerDown(event, record, iso)} onPointerMove={onCardPointerMove} onPointerUp={onCardPointerUp} onPointerCancel={resetDrag} onClick={(event) => { if (canMoveRecords) return; event.stopPropagation(); if (onEditRecord) onEditRecord(record.id, event.currentTarget.getBoundingClientRect()); else onOpenRecord?.(record.id); }} style={calendarCardColorStyle(noteColorForRecord?.(record))} className={`multidimensional-table__calendar-card flex h-6 cursor-pointer items-center justify-between gap-2 overflow-hidden rounded-md border-0 px-1 py-0 text-[var(--brand)] ${canMoveRecords ? 'touch-none active:cursor-grabbing' : ''} ${draggingRecord?.id === record.id ? 'opacity-50' : ''}`} title={canMoveRecords ? renderValue(record, titleField) : '创建时间和更新时间不能通过拖动修改'}>
+                  <TableRecordTitle record={record} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} className="text-xs font-normal text-[var(--foreground)]" />
                 </div>;
               })}
               {hasHiddenRecords && <PopoverTrigger asChild anchorToCell>
-                <button type="button" aria-label={`${date.toLocaleDateString()}，查看全部 ${records.length} 条笔记`} className="h-5 shrink-0 truncate rounded bg-transparent px-1 text-left text-xs leading-5 text-[var(--muted-foreground)] hover:bg-transparent hover:text-[var(--foreground)] active:bg-transparent data-[state=open]:bg-transparent">更多 +{records.length - previewLimit}</button>
+                <button type="button" aria-label={`${date.toLocaleDateString()}，查看全部 ${records.length} 条笔记`} className="h-5 w-full shrink-0 truncate rounded bg-transparent px-1 text-right text-xs leading-5 text-[var(--muted-foreground)] hover:bg-transparent hover:text-[var(--foreground)] active:bg-transparent data-[state=open]:bg-transparent">+ {records.length - previewLimit}</button>
               </PopoverTrigger>}
                 </div>
             </div>
-            <PopoverContent align="start" side="bottom" sideOffset={0} matchAnchorWidth matchAnchorHeight className={`max-h-[min(60vh,360px)] overflow-y-auto rounded-xl p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)] ${draggingRecord ? 'pointer-events-none' : ''}`}>
+            <PopoverContent align="start" side="bottom" sideOffset={0} matchAnchorWidth={1.6} matchAnchorHeight className={`max-h-[min(60vh,360px)] max-w-[calc(100vw-16px)] overflow-y-auto p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)] ${draggingRecord ? 'pointer-events-none' : ''}`}>
               <div className="space-y-1">
                 {records.length ? records.map((record) => {
-                  const time = formatCalendarTime(dateValueForRecord?.(record));
-                  return <div key={record.id} data-calendar-record={record.id} onPointerDown={(event) => onCardPointerDown(event, record, iso)} onPointerMove={onCardPointerMove} onPointerUp={onCardPointerUp} onPointerCancel={resetDrag} onClick={(event) => { if (canMoveRecords) return; event.stopPropagation(); onOpenRecord?.(record.id); }} className={`multidimensional-table__calendar-card flex min-w-0 cursor-default items-center justify-between gap-1 rounded-md border border-[color-mix(in_oklch,var(--brand)_25%,var(--border))] bg-[color-mix(in_oklch,var(--brand)_4%,var(--background))] px-1 py-1 text-[var(--brand)] ${canMoveRecords ? 'touch-none active:cursor-grabbing' : ''} ${draggingRecord?.id === record.id ? 'opacity-50' : ''}`} title={canMoveRecords ? renderValue(record, titleField) : '创建时间和更新时间不能通过拖动修改'}>
-                    <span className="min-w-0 truncate text-xs font-normal text-[var(--foreground)]">{renderValue(record, titleField)}</span>
-                    {time && <span className="shrink-0 text-[10px] tabular-nums text-[var(--muted-foreground)]">{time}</span>}
+                  return <div key={record.id} data-calendar-record={record.id} onPointerDown={(event) => onCardPointerDown(event, record, iso)} onPointerMove={onCardPointerMove} onPointerUp={onCardPointerUp} onPointerCancel={resetDrag} onClick={(event) => { if (canMoveRecords) return; event.stopPropagation(); if (onEditRecord) onEditRecord(record.id, event.currentTarget.getBoundingClientRect()); else onOpenRecord?.(record.id); }} style={calendarCardColorStyle(noteColorForRecord?.(record))} className={`multidimensional-table__calendar-card flex h-6 min-w-0 cursor-pointer items-center justify-between gap-1 overflow-hidden rounded-md border-0 px-1 py-0 text-[var(--brand)] ${canMoveRecords ? 'touch-none active:cursor-grabbing' : ''} ${draggingRecord?.id === record.id ? 'opacity-50' : ''}`} title={canMoveRecords ? renderValue(record, titleField) : '创建时间和更新时间不能通过拖动修改'}>
+                    <TableRecordTitle record={record} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} className="text-xs font-normal text-[var(--foreground)]" />
                   </div>;
                 }) : <p className="px-0.5 py-1 text-xs text-[var(--muted-foreground)]">当天没有笔记</p>}
               </div>
@@ -637,9 +942,8 @@ export function TableCalendarView({ cursor, onCursorChange, days, groups, dateFi
       </div>
     </div>
     {draggingRecord && typeof document !== 'undefined' && createPortal(
-      <div ref={floatingCardRef} data-calendar-floating-preview aria-hidden="true" className="multidimensional-table__calendar-card pointer-events-none fixed z-[1000] flex w-[220px] items-center justify-between gap-2 overflow-hidden rounded-md border border-[color-mix(in_oklch,var(--brand)_25%,var(--border))] bg-[var(--card)] px-1 py-1 shadow-lg" style={{ left: pointerPositionRef.current.x + 14, top: pointerPositionRef.current.y + 14 }}>
-        <span className="min-w-0 truncate text-xs text-[var(--foreground)]">{renderValue(draggingRecord, titleField)}</span>
-        {formatCalendarTime(dateValueForRecord?.(draggingRecord)) && <span className="shrink-0 text-[11px] tabular-nums text-[var(--muted-foreground)]">{formatCalendarTime(dateValueForRecord?.(draggingRecord))}</span>}
+      <div ref={floatingCardRef} data-calendar-floating-preview aria-hidden="true" className="multidimensional-table__calendar-card pointer-events-none fixed z-[1000] flex h-6 w-[220px] items-center justify-between gap-2 overflow-hidden rounded-md border-0 px-1 py-0 shadow-lg" style={{ ...calendarCardColorStyle(noteColorForRecord?.(draggingRecord)), left: pointerPositionRef.current.x + 14, top: pointerPositionRef.current.y + 14 }}>
+        <TableRecordTitle record={draggingRecord} titleField={titleField} renderValue={renderValue} noteIconForRecord={noteIconForRecord} className="text-xs text-[var(--foreground)]" />
       </div>, document.body)}
   </div>;
 }
diff --git a/app/flowix-web/features/multidimensional-table/table-tag-value-input.tsx b/app/flowix-web/features/multidimensional-table/table-tag-value-input.tsx
index f53ab0a19..b8353e9bb 100644
--- a/app/flowix-web/features/multidimensional-table/table-tag-value-input.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-tag-value-input.tsx
@@ -211,7 +211,7 @@ export function TableTagValueInput({
     <PopoverContent
       align="start"
       sideOffset={4}
-      className="frontmatter-property__edit-popover rounded-xl p-1"
+      className="frontmatter-property__edit-popover !z-[170] rounded-xl p-1"
       matchAnchorWidth={1.2}
       style={{ maxWidth: 'calc(100vw - 8px)', maxHeight: '280px', overflowY: 'auto' }}
     >
diff --git a/app/flowix-web/features/multidimensional-table/table-text-value-input.tsx b/app/flowix-web/features/multidimensional-table/table-text-value-input.tsx
index 65c1b899e..8bf21875b 100644
--- a/app/flowix-web/features/multidimensional-table/table-text-value-input.tsx
+++ b/app/flowix-web/features/multidimensional-table/table-text-value-input.tsx
@@ -55,7 +55,7 @@ export function TableTextValueInput({ value, disabled = false, placeholder, onCh
       align="start"
       side="bottom"
       sideOffset={4}
-      className="rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]"
+      className="!z-[170] rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]"
       matchAnchorWidth={1.2}
       style={{ maxWidth: 'calc(100vw - 8px)', maxHeight: '280px', overflowY: 'auto' }}
     >
diff --git a/app/flowix-web/features/multidimensional-table/use-table-cell-writer.test.tsx b/app/flowix-web/features/multidimensional-table/use-table-cell-writer.test.tsx
index d1de568be..f05b53ad9 100644
--- a/app/flowix-web/features/multidimensional-table/use-table-cell-writer.test.tsx
+++ b/app/flowix-web/features/multidimensional-table/use-table-cell-writer.test.tsx
@@ -73,6 +73,9 @@ describe('useTableCellWriter', () => {
     await act(async () => root?.render(<Probe generation={2} />));
     await act(async () => { latestWriter?.updateCell(record, note, field, 'second'); });
     expect(container.textContent).toBe('second');
+    const flush = latestWriter!.flush();
+    let completed = false;
+    void flush.then(() => { completed = true; });
 
     await act(async () => {
       firstWrite.resolve(true);
@@ -80,6 +83,7 @@ describe('useTableCellWriter', () => {
       await Promise.resolve();
     });
     expect(mocks.writeProperty).toHaveBeenCalledTimes(2);
+    expect(completed).toBe(false);
 
     await act(async () => {
       secondWrite.reject(new Error('write failed'));
@@ -88,6 +92,7 @@ describe('useTableCellWriter', () => {
     });
 
     expect(container.textContent).toBe('first');
+    await expect(flush).resolves.toBe(false);
   });
 });
 
diff --git a/app/flowix-web/features/multidimensional-table/use-table-cell-writer.ts b/app/flowix-web/features/multidimensional-table/use-table-cell-writer.ts
index 889412fb2..9775ea9a6 100644
--- a/app/flowix-web/features/multidimensional-table/use-table-cell-writer.ts
+++ b/app/flowix-web/features/multidimensional-table/use-table-cell-writer.ts
@@ -37,13 +37,27 @@ interface TableCellWriterOptions {
 
 export function useTableCellWriter({ enabled, loadGeneration, notebookPath, loadSequenceRef, setNotes, pendingNotePropertiesRef }: TableCellWriterOptions) {
   const [cellStatusesByRecord, setCellStatusesByRecord] = useState<Map<string, ReadonlyMap<string, TableCellSaveStatus>>>(() => new Map());
+  const writesRef = useRef(new Set<Promise<void>>());
+  const errorsRef = useRef(new Set<string>());
+  const flush = useCallback(async () => {
+    const sequence = loadSequenceRef.current;
+    while (writesRef.current.size) {
+      try { await Promise.all([...writesRef.current]); }
+      catch { return false; }
+    }
+    return sequence === loadSequenceRef.current && errorsRef.current.size === 0;
+  }, [loadSequenceRef]);
   const cellWriteQueuesRef = useRef(new Map<string, TableCellWriteQueue>());
 
   useEffect(() => {
+    errorsRef.current.clear();
     setCellStatusesByRecord(new Map());
   }, [loadGeneration]);
 
   const updateCellStatus = useCallback((recordId: string, fieldId: string, status: TableCellSaveStatus | null) => {
+    const key = `${recordId}\u0000${fieldId}`;
+    if (status?.error) errorsRef.current.add(key);
+    else errorsRef.current.delete(key);
     setCellStatusesByRecord((current) => {
       const rowStatuses = new Map(current.get(recordId) ?? []);
       if (status) rowStatuses.set(fieldId, status);
@@ -103,7 +117,7 @@ export function useTableCellWriter({ enabled, loadGeneration, notebookPath, load
       : item));
 
     if (!isNewQueue) return;
-    void (async () => {
+    const write = (async () => {
       let failure: string | null = null;
       while (queue.pending) {
         const request = queue.pending;
@@ -142,7 +156,9 @@ export function useTableCellWriter({ enabled, loadGeneration, notebookPath, load
         if (pendingProperties?.size === 0) pendingNotePropertiesRef?.current.delete(notePathKey);
       }
     })();
+    writesRef.current.add(write);
+    void write.then(() => writesRef.current.delete(write), () => writesRef.current.delete(write));
   }, [enabled, loadSequenceRef, notebookPath, pendingNotePropertiesRef, setNotes, updateCellStatus]);
 
-  return { cellStatusesByRecord, updateCell };
+  return { cellStatusesByRecord, updateCell, flush };
 }
diff --git a/app/flowix-web/features/multidimensional-table/use-table-note-drop-target.ts b/app/flowix-web/features/multidimensional-table/use-table-note-drop-target.ts
new file mode 100644
index 000000000..8758c3874
--- /dev/null
+++ b/app/flowix-web/features/multidimensional-table/use-table-note-drop-target.ts
@@ -0,0 +1,94 @@
+import { useEffect, useRef } from 'react';
+import { isMarkdownNoteDragResource, type NotebookNoteDragResource } from '@features/memo/public/drag-resource-api';
+import { registerDropTarget, type DropPreview } from '@shared/drag-drop/drag-drop-coordinator';
+import type { TableNoteDropPreview, TableNoteDropRejection } from './table-note-drop';
+
+export type TableNoteDropTargetRejection =
+  | TableNoteDropRejection['reason']
+  | 'unsupported-resource'
+  | 'wrong-notebook'
+  | 'read-only';
+
+interface TableNoteDropTargetOptions<Location> {
+  id: string;
+  active: boolean;
+  notebookId: string | null;
+  canDrop: boolean;
+  canHandleDrop: boolean;
+  hitTest: (point: { x: number; y: number }) => Location | null;
+  locationKey: (location: Location) => string;
+  preview: (notes: NotebookNoteDragResource[], location: Location) => TableNoteDropPreview | TableNoteDropRejection;
+  onPreview: (preview: TableNoteDropPreview | null) => void;
+  onDrop: (notes: NotebookNoteDragResource[], location: Location) => void | Promise<void>;
+  onReject: (reason: TableNoteDropTargetRejection) => void;
+  onError: (error: unknown) => void;
+}
+
+/** Shares note eligibility, preview caching and target lifecycle across table and gallery drops. */
+export function useTableNoteDropTarget<Location>(options: TableNoteDropTargetOptions<Location>): void {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const previewCacheRef = useRef<{
+    sessionId: string;
+    items: readonly unknown[];
+    locationKey: string;
+    planner: TableNoteDropTargetOptions<Location>['preview'];
+    result: TableNoteDropPreview | TableNoteDropRejection;
+  } | null>(null);
+
+  useEffect(() => {
+    if (!options.active) {
+      optionsRef.current.onPreview(null);
+      return;
+    }
+    const resolvePreview = (items: readonly unknown[], sessionId: string, location: Location) => {
+      const current = optionsRef.current;
+      const key = current.locationKey(location);
+      const cached = previewCacheRef.current;
+      if (cached && cached.sessionId === sessionId && cached.items === items
+        && cached.locationKey === key && cached.planner === current.preview) return cached.result;
+      const notes = items.filter(isMarkdownNoteDragResource);
+      const result = current.preview(notes, location);
+      previewCacheRef.current = { sessionId, items, locationKey: key, planner: current.preview, result };
+      return result;
+    };
+    return registerDropTarget<unknown, Location>({
+      id: options.id,
+      priority: 100,
+      hitTest: (point) => optionsRef.current.hitTest(point),
+      locationKey: (location) => optionsRef.current.locationKey(location),
+      evaluate: (payload, location) => {
+        const current = optionsRef.current;
+        const notes = payload.items.filter(isMarkdownNoteDragResource);
+        if (!notes.length || notes.length !== payload.items.length) return { accepted: false, reason: 'unsupported-resource' };
+        if (!current.notebookId || notes.some((note) => note.notebookId !== current.notebookId)) {
+          return { accepted: false, reason: 'wrong-notebook' };
+        }
+        if (!current.canDrop) return { accepted: false, reason: 'read-only' };
+        if (!current.canHandleDrop) return { accepted: false, reason: 'unavailable' };
+        const plan = resolvePreview(payload.items, payload.sessionId, location);
+        return 'reason' in plan ? { accepted: false, reason: plan.reason } : { accepted: true };
+      },
+      onPreview: (preview: DropPreview<unknown, Location> | null) => {
+        if (!preview?.decision.accepted) {
+          optionsRef.current.onPreview(null);
+          return;
+        }
+        const next = resolvePreview(preview.payload.items, preview.payload.sessionId, preview.location);
+        optionsRef.current.onPreview('reason' in next ? null : next);
+      },
+      onDrop: (payload, location) => optionsRef.current.onDrop(
+        payload.items.filter(isMarkdownNoteDragResource), location,
+      ),
+      onReject: (_payload, _location, reason) => {
+        optionsRef.current.onReject(isTableNoteDropTargetRejection(reason) ? reason : 'unavailable');
+      },
+      onError: (error) => optionsRef.current.onError(error),
+    });
+  }, [options.active, options.id]);
+}
+
+function isTableNoteDropTargetRejection(reason: string | undefined): reason is TableNoteDropTargetRejection {
+  return reason === 'filtered' || reason === 'unavailable' || reason === 'unsupported-resource'
+    || reason === 'wrong-notebook' || reason === 'read-only';
+}
diff --git a/app/flowix-web/features/multidimensional-table/use-table-session.test.tsx b/app/flowix-web/features/multidimensional-table/use-table-session.test.tsx
index 0b23d6343..d3ae1a278 100644
--- a/app/flowix-web/features/multidimensional-table/use-table-session.test.tsx
+++ b/app/flowix-web/features/multidimensional-table/use-table-session.test.tsx
@@ -33,10 +33,19 @@ it('reports external write failures, clears them for retry, and ignores stale se
     expect(session.document).toBeTruthy();
     const sequence = session.loadSequenceRef.current;
     act(() => session.setSaving(true));
+    const failedFlush = session.flush();
+    let completed = false;
+    void failedFlush.then(() => { completed = true; });
+    await Promise.resolve();
+    expect(completed).toBe(false);
     act(() => session.reportSaveFailure(sequence));
+    act(() => session.setSaving(true));
+    expect(session.saveFailed).toBe(true);
     act(() => session.setSaving(false));
     expect(session.saveFailed).toBe(true);
     expect(session.saving).toBe(false);
+    await expect(failedFlush).resolves.toBe(false);
+    await expect(session.flush()).resolves.toBe(false);
 
     act(() => session.setSaving(true));
     expect(session.saveFailed).toBe(false);
@@ -45,6 +54,7 @@ it('reports external write failures, clears them for retry, and ignores stale se
     await act(async () => { expect(await session.save(session.document!)).toBe(true); });
     expect(session.saveFailed).toBe(false);
     expect(session.saving).toBe(false);
+    await expect(session.flush()).resolves.toBe(true);
 
     await act(async () => session.load());
     act(() => session.reportSaveFailure(sequence));
@@ -75,9 +85,12 @@ it('retains data and pending writes across views, but reloads for another collec
     expect(mocks.read).toHaveBeenCalledTimes(1);
     act(() => session.reportSaveFailure(generation));
     expect(session.saveFailed).toBe(true);
+    const previousFlush = session.flush();
     await act(async () => root.render(<Probe displayId="other-view" collectionId="collection-b" />));
     expect(mocks.read).toHaveBeenCalledTimes(2);
     expect(session.loadSequenceRef.current).toBeGreaterThan(generation);
     expect(session.saveFailed).toBe(false);
+    await expect(previousFlush).resolves.toBe(false);
+    await expect(session.flush()).resolves.toBe(true);
   } finally { act(() => root.unmount()); }
 });
diff --git a/app/flowix-web/features/multidimensional-table/use-table-session.ts b/app/flowix-web/features/multidimensional-table/use-table-session.ts
index 5f0fe5032..5b7028c84 100644
--- a/app/flowix-web/features/multidimensional-table/use-table-session.ts
+++ b/app/flowix-web/features/multidimensional-table/use-table-session.ts
@@ -1,11 +1,13 @@
+import { createSaveBarrier } from '@/lib/save-barrier';
 import { hydrateTablePresets } from './table-preset-bindings';
 import { subscribePropertyPresets } from '@features/properties/public-api';
 import { collectionSessionKey } from '@/lib/collection-session-key';
 import { canonicalDirectoryPath } from '@/lib/path';
 import { reuseCollectionValue } from '@features/collection/content-equality';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { externalDocuments, notes as notesClient, type NoteEntry } from '@platform/tauri/client';
 import { subscribe } from '@platform/tauri/event-bus';
+import { subscribeNotebookChanges, type NotebookChange } from '@platform/tauri/notebook-change-events';
 import { toast } from '@/lib/toast';
 import { findFileDisplayPath, type FileDisplayIdentity } from '@/lib/file-display-registry';
 import { parseTableDocumentAsync } from './parse-table-document';
@@ -21,14 +23,6 @@ interface TableSessionOptions {
   notebookId: string | null;
 }
 
-interface NoteChangeEvent {
-  notebookId: string;
-  relativePath?: string;
-  previousRelativePath?: string;
-  kind?: string;
-  deleted?: boolean;
-}
-
 /** Apply the same path/default normalization to loads, rename replies and events. */
 function normalizeTableSessionDocument(document: MultidimensionalTableDocument): MultidimensionalTableDocument {
   return {
@@ -55,13 +49,26 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
   const [document, setDocument] = useState<MultidimensionalTableDocument | null>(null);
   const [loadError, setLoadError] = useState<string | null>(null);
   const [saving, setSavingState] = useState(false);
-  const [saveFailed, setSaveFailed] = useState(false);
+  const [saveFailed, setSaveFailedState] = useState(false);
+  const saveBarrier = useMemo(createSaveBarrier, [sessionKey]);
+  const setSaveFailed = useCallback((failed: boolean) => {
+    if (failed) saveBarrier.fail();
+    else saveBarrier.resetFailure();
+    setSaveFailedState(failed);
+  }, [saveBarrier]);
+  useEffect(() => () => saveBarrier.cancel(), [saveBarrier]);
+  const flush = useCallback(async () => {
+    const sequence = loadSequenceRef.current;
+    const saved = await saveBarrier.flush();
+    return saved && sequence === loadSequenceRef.current && currentSessionKeyRef.current === sessionKey;
+  }, [saveBarrier, sessionKey]);
   const savingRef = useRef(false);
   const setSaving = useCallback((next: boolean) => {
     if (next && !savingRef.current) setSaveFailed(false);
     savingRef.current = next;
+    saveBarrier.setSaving(next);
     setSavingState(next);
-  }, []);
+  }, [saveBarrier, setSaveFailed]);
   const [notes, setNotes] = useState<NoteEntry[]>([]);
   useEffect(() => subscribePropertyPresets(() => {
     setDocument((current) => current ? hydrateTablePresets(current) : current);
@@ -91,7 +98,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
       setSaveFailed(true);
       pendingTableSyncRef.current = true;
     }
-  }, [isCurrentSession, sessionKey]);
+  }, [isCurrentSession, sessionKey, setSaveFailed]);
 
   const load = useCallback(async () => {
     syncSequenceRef.current += 1;
@@ -172,7 +179,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
     } catch (error) {
       if (isCurrentSession(sequence, key)) setLoadError(error instanceof Error ? error.message : String(error));
     }
-  }, [getCurrentFilePath, isCurrentSession, notebookId, notebookPath, sessionKey]);
+  }, [getCurrentFilePath, isCurrentSession, notebookId, notebookPath, sessionKey, setSaveFailed, setSaving]);
 
   // A rename changes the path prop, not the live table session. Read the latest
   // loader when the file identity or notebook scope changes, while keeping the
@@ -191,7 +198,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
     };
   }, [sessionKey]);
 
-  const syncNotes = useCallback(async (event: NoteChangeEvent) => {
+  const syncNotes = useCallback(async (event: NotebookChange) => {
     const notebook = resolvedNotebookId;
     if (!notebook || event.notebookId !== notebook) return;
     const key = sessionKey;
@@ -204,7 +211,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
     const generation = loadSequenceRef.current;
     const syncSequence = ++syncSequenceRef.current;
     const isCurrent = () => isCurrentSession(generation, key) && syncSequence === syncSequenceRef.current;
-    if (event.kind === 'path' || event.deleted || !event.relativePath) pendingTableSyncRef.current = true;
+    if (event.kind !== 'query-invalidated' || !event.relativePath) pendingTableSyncRef.current = true;
     let needsTableSync = pendingTableSyncRef.current;
     try {
       const singlePath = !needsTableSync && event.relativePath?.replace(/\\/g, '/');
@@ -273,7 +280,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
       }
       if (sourceContentRef.current?.content !== baselineAtStart) {
         pendingTableSyncRef.current = true;
-        void syncNotes({ notebookId: notebook, kind: 'path' });
+        void syncNotes({ notebookId: notebook, kind: 'query-invalidated', relativePath: null });
         return;
       }
       const sourceChanged = sourceContentRef.current?.content !== baseline;
@@ -292,12 +299,11 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
 
   useEffect(() => {
     if (!saving && !savingRef.current && pendingTableSyncRef.current && resolvedNotebookId) {
-      void syncNotes({ notebookId: resolvedNotebookId, kind: 'path' });
+      void syncNotes({ notebookId: resolvedNotebookId, kind: 'query-invalidated', relativePath: null });
     }
   }, [resolvedNotebookId, saving, syncNotes]);
 
-  useEffect(() => subscribe<NoteChangeEvent>(
-    'flowix:path-note-changed',
+  useEffect(() => subscribeNotebookChanges(
     (event) => {
       if (event.relativePath && /\.(table|lib)\.ya?ml$/i.test(event.relativePath)) return;
       if (event.notebookId === resolvedNotebookId) void syncNotes(event);
@@ -324,8 +330,6 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
     }
 
     writeLocksRef.current.add(lockKey);
-    savingRef.current = true;
-    setSaveFailed(false);
     setSaving(true);
     try {
       validateTableDocument(next);
@@ -362,7 +366,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
       writeLocksRef.current.delete(lockKey);
       if (!keepSaving && isCurrentSession(sequence, key)) setSaving(false);
     }
-  }, [getCurrentFilePath, isCurrentSession, load, notebookPath, resolvedNotebookId, sessionKey, syncNotes]);
+  }, [getCurrentFilePath, isCurrentSession, load, notebookPath, resolvedNotebookId, sessionKey, setSaveFailed, setSaving, syncNotes]);
 
   const acceptContent = useCallback((content: string) => {
     if (currentSessionKeyRef.current !== sessionKey) return false;
@@ -425,6 +429,7 @@ export function useTableSession({ filePath, fileIdentity, notebookPath: rawNoteb
     notesLoadError: stateIsCurrent ? notesLoadError : null,
     load,
     save,
+    flush,
     acceptContent,
     isCurrentSession: isCurrentSessionForKey,
     loadSequenceRef,
diff --git a/app/flowix-web/features/notifications/actionable-notice-host.tsx b/app/flowix-web/features/notifications/actionable-notice-host.tsx
index 83c031a87..aa12c3cdc 100644
--- a/app/flowix-web/features/notifications/actionable-notice-host.tsx
+++ b/app/flowix-web/features/notifications/actionable-notice-host.tsx
@@ -30,7 +30,7 @@ export function ActionableNoticeHost() {
     //   - pb-8 (32px) 底部再多给一些, 因为投影向下偏移最明显;
     //   - top-4 + pt-4 = 32px, 让卡片视觉顶边仍停在原来的 top-8 位置。
     <div
-      className="pointer-events-none fixed left-1/2 top-4 z-[2147483647] flex max-h-[calc(100vh-4rem)] w-[min(36rem,calc(100vw-2rem))] -translate-x-1/2 flex-col gap-2 overflow-y-auto p-4 pb-8"
+      className="pointer-events-none fixed left-1/2 top-4 z-[2147483647] flex max-h-[calc(100vh-4rem)] w-[min(44rem,calc(100vw-2rem))] -translate-x-1/2 flex-col items-center gap-2 overflow-y-auto p-4 pb-8"
       data-actionable-notice-host
       role="region"
       aria-label={t('notifications.actionable.region')}
@@ -43,12 +43,14 @@ export function ActionableNoticeHost() {
             key={notice.id}
             role={notice.tone === 'neutral' ? 'status' : 'alert'}
             aria-live={index === 0 && notice.tone !== 'neutral' ? 'assertive' : 'polite'}
-            className={`pointer-events-auto animate-in slide-in-from-top-2 fade-in duration-200 rounded-xl border bg-[var(--card)] px-4 py-3 text-sm text-[var(--foreground)] shadow-xl ${notice.tone === 'error' ? 'border-destructive/30' : notice.tone === 'warning' ? 'border-[color-mix(in_oklch,var(--warning)_30%,transparent)]' : 'border-[var(--border)]'}`}
+            className={`pointer-events-auto w-full ${notice.width === 'wide' ? '' : notice.width === 'narrow' ? 'max-w-[24rem]' : 'max-w-[36rem]'} animate-in slide-in-from-top-2 fade-in duration-200 rounded-xl border bg-[var(--card)] px-4 py-3 text-sm text-[var(--foreground)] shadow-xl ${notice.tone === 'error' ? 'border-destructive/30' : notice.tone === 'warning' ? 'border-[color-mix(in_oklch,var(--warning)_30%,transparent)]' : 'border-[var(--border)]'}`}
           >
-            <div className="flex items-start gap-3">
-              {working
-                ? <Loader2 className="mt-0.5 h-4 w-4 shrink-0 animate-spin text-[var(--primary)]" aria-hidden="true" />
-                : <Icon className={`mt-0.5 h-4 w-4 shrink-0 ${notice.tone === 'error' ? 'text-destructive' : notice.tone === 'warning' ? 'text-[var(--warning)]' : 'text-[var(--muted-foreground)]'}`} aria-hidden="true" />}
+            <div className="flex items-center gap-3">
+              {notice.leadingIcon === 'loading'
+                ? <Loader2 className="h-4 w-4 shrink-0 flowix-spin text-[var(--primary)]" aria-hidden="true" />
+                : working
+                  ? <Loader2 className="h-4 w-4 shrink-0 flowix-spin text-[var(--primary)]" aria-hidden="true" />
+                  : <Icon className={`h-4 w-4 shrink-0 ${notice.tone === 'error' ? 'text-destructive' : notice.tone === 'warning' ? 'text-[var(--warning)]' : 'text-[var(--muted-foreground)]'}`} aria-hidden="true" />}
               <div className="min-w-0 flex-1">
                 <strong className="block font-semibold">{notice.title}</strong>
                 {/* 副文案最多 1 行, 超出省略。 */}
@@ -75,7 +77,7 @@ export function ActionableNoticeHost() {
                   ))}
                 </div>
               )}
-              {notice.dismissible && (
+              {notice.dismissible && !notice.actions.some((action) => action.id === 'hide') && (
                 <button
                   type="button"
                   className="-mr-1 grid h-7 w-7 shrink-0 place-items-center self-center rounded-lg text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] disabled:opacity-50"
diff --git a/app/flowix-web/features/notifications/actionable-notice-store.ts b/app/flowix-web/features/notifications/actionable-notice-store.ts
index 8fa61f816..e3d2b5edf 100644
--- a/app/flowix-web/features/notifications/actionable-notice-store.ts
+++ b/app/flowix-web/features/notifications/actionable-notice-store.ts
@@ -1,5 +1,6 @@
 export type ActionableNoticeTone = 'neutral' | 'error' | 'warning';
 export type ActionableNoticeActionVariant = 'default' | 'outline' | 'destructive';
+export type ActionableNoticeLeadingIcon = 'loading';
 
 export interface ActionableNoticeAction {
   id: string;
@@ -14,6 +15,8 @@ export interface ActionableNotice {
   tone: ActionableNoticeTone;
   title: string;
   message?: string;
+  leadingIcon?: ActionableNoticeLeadingIcon;
+  width?: 'default' | 'wide' | 'narrow';
   actions: ActionableNoticeAction[];
   dismissible?: boolean;
   onDismiss?: () => void;
diff --git a/app/flowix-web/features/onboarding/notebook-template-picker.tsx b/app/flowix-web/features/onboarding/notebook-template-picker.tsx
index 040a0ab2a..24f0c8507 100644
--- a/app/flowix-web/features/onboarding/notebook-template-picker.tsx
+++ b/app/flowix-web/features/onboarding/notebook-template-picker.tsx
@@ -1,5 +1,5 @@
 import { useMemo, useState } from 'react';
-import { Check, CircleAlert, Plus, X } from 'lucide-react';
+import { Check, CircleAlert, LoaderCircle, Plus, X } from 'lucide-react';
 import { ArrowsLeftRightIcon } from '@phosphor-icons/react';
 import { Button } from '@shared/ui/button';
 import { cn } from '@/lib/utils';
@@ -12,9 +12,11 @@ import { NotebookTemplateCover } from './notebook-template-icon';
 function NotebookTemplateCardContent({
   template,
   onSwitch,
+  disabled = false,
 }: {
   template: NotebookTemplate;
   onSwitch?: () => void;
+  disabled?: boolean;
 }) {
   return (
     <>
@@ -24,6 +26,7 @@ function NotebookTemplateCardContent({
           <span className="pointer-events-none absolute inset-0 grid place-items-center rounded-lg bg-[color-mix(in_oklch,var(--background)_68%,transparent)] opacity-0 transition-opacity group-hover/cover:pointer-events-auto group-hover/cover:opacity-100 group-focus-within/cover:pointer-events-auto group-focus-within/cover:opacity-100">
             <button
               type="button"
+              disabled={disabled}
               aria-label="切换场景模板"
               title="切换场景模板"
               className="inline-flex h-7 w-7 items-center justify-center text-[var(--brand)]"
@@ -45,22 +48,25 @@ function NotebookTemplateCardContent({
 export function NotebookTemplateCardPreview({
   template,
   onSwitch,
+  disabled = false,
 }: {
   template: NotebookTemplate;
   onSwitch: () => void;
+  disabled?: boolean;
 }) {
   return (
     <div className="grid min-h-0 w-[min(280px,100%)] grid-rows-[auto_auto] gap-2 rounded-[11px] border border-[var(--onboarding-line)] bg-[var(--card)] p-[10px] text-left text-[var(--onboarding-subtle)]">
-      <NotebookTemplateCardContent template={template} onSwitch={onSwitch} />
+      <NotebookTemplateCardContent template={template} onSwitch={onSwitch} disabled={disabled} />
     </div>
   );
 }
 
-export function NotebookTemplateEmptyCard({ onClick }: { onClick: () => void }) {
+export function NotebookTemplateEmptyCard({ onClick, disabled = false }: { onClick: () => void; disabled?: boolean }) {
   return (
     <button
       type="button"
-      className="flex h-[240px] w-[320px] max-w-full flex-col items-center justify-center gap-1.5 rounded-2xl border-2 border-dashed border-[color-mix(in_oklch,var(--onboarding-line)_90%,var(--onboarding-ink))] bg-transparent text-sm text-[var(--onboarding-subtle)]"
+      disabled={disabled}
+      className="flex h-[240px] w-[320px] max-w-full flex-col items-center justify-center gap-1.5 rounded-2xl border-2 border-dashed border-[color-mix(in_oklch,var(--onboarding-line)_90%,var(--onboarding-ink))] bg-transparent text-sm text-[var(--onboarding-subtle)] disabled:cursor-not-allowed disabled:opacity-50"
       aria-haspopup="dialog"
       onClick={onClick}
     >
@@ -93,35 +99,53 @@ export function NotebookTemplatePicker({
       ? templates.filter((template) => template.category === selectedCategory)
       : templates
   ), [selectedCategory, templates]);
+  const hasCategories = templates.some((template) => Boolean(template.category));
 
   return (
     <div className="absolute inset-0 z-[5] grid grid-rows-[minmax(0,1fr)_auto] bg-[var(--frame-bg)] text-[var(--onboarding-ink)] [--onboarding-ink:var(--foreground)] [--onboarding-subtle:var(--muted-foreground)] [--onboarding-panel:color-mix(in_oklch,var(--card)_96%,var(--background))] [--onboarding-line:color-mix(in_oklch,var(--border)_78%,transparent)]" role="dialog" aria-modal="true" aria-label="选择场景模板">
-      <main className="overflow-auto px-[clamp(20px,5vw,64px)] pb-7 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
-        <div className="sticky top-0 z-[3] flex items-center gap-3 bg-[var(--frame-bg)] pb-2 shadow-[0_1px_0_var(--onboarding-line)]">
-          <NotebookTemplateCategories
-            templates={templates}
-            value={selectedCategory}
-            onChange={setSelectedCategory}
-          />
-          <button
-            type="button"
-            className="inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] p-0 text-[var(--muted-foreground)] shadow-sm transition-colors hover:border-[color-mix(in_oklch,var(--border)_65%,var(--muted-foreground))] hover:text-[var(--foreground)]"
-            aria-label="关闭场景选择"
-            onClick={onCancel}
-          >
-            <X size={19} aria-hidden="true" />
-          </button>
-        </div>
-        {status === 'loading' && (
-          <p className="mt-4 text-sm text-muted-foreground" aria-live="polite">
-            {t('notebook.template.loading')}
-          </p>
+      <main className={cn(
+        'min-h-0 overflow-auto px-[clamp(20px,5vw,64px)] pb-7 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden',
+        status === 'loading' && 'relative grid place-items-center',
+      )}>
+        {status === 'loading' ? (
+          <>
+            <button
+              type="button"
+              className="absolute right-[clamp(20px,5vw,64px)] top-3 z-[3] inline-flex h-8 w-8 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] p-0 text-[var(--muted-foreground)] shadow-sm transition-colors hover:border-[color-mix(in_oklch,var(--border)_65%,var(--muted-foreground))] hover:text-[var(--foreground)]"
+              aria-label="关闭场景选择"
+              onClick={onCancel}
+            >
+              <X size={19} aria-hidden="true" />
+            </button>
+            <div className="flex items-center justify-center gap-2 text-sm text-muted-foreground" role="status" aria-live="polite">
+              <LoaderCircle size={16} className="flowix-spin" aria-hidden="true" />
+              <span>{t('notebook.template.loading')}</span>
+            </div>
+          </>
+        ) : (
+          <div className="sticky top-0 z-[3] flex items-center gap-3 bg-[var(--frame-bg)] pb-2 shadow-[0_1px_0_var(--onboarding-line)]">
+            {hasCategories && (
+              <NotebookTemplateCategories
+                templates={templates}
+                value={selectedCategory}
+                onChange={setSelectedCategory}
+              />
+            )}
+            <button
+              type="button"
+              className="inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] p-0 text-[var(--muted-foreground)] shadow-sm transition-colors hover:border-[color-mix(in_oklch,var(--border)_65%,var(--muted-foreground))] hover:text-[var(--foreground)]"
+              aria-label="关闭场景选择"
+              onClick={onCancel}
+            >
+              <X size={19} aria-hidden="true" />
+            </button>
+          </div>
         )}
         {status === 'error' && (
           <div className="mt-4 flex items-start gap-2 text-xs leading-5 text-[var(--destructive)]" role="alert">
             <CircleAlert size={15} aria-hidden="true" />
             <span>{t('notebook.template.loadFailed')}</span>
-            <Button type="button" variant="outline" size="sm" className="h-7" onClick={retry}>
+            <Button type="button" variant="outline" size="sm" className="h-7 rounded-lg" onClick={retry}>
               {t('error.retry')}
             </Button>
           </div>
@@ -129,33 +153,35 @@ export function NotebookTemplatePicker({
         {status === 'ready' && templates.length === 0 && (
           <p className="mt-4 text-sm text-muted-foreground">{t('notebook.template.empty')}</p>
         )}
-        <div className="mt-[18px] grid grid-cols-[repeat(auto-fill,minmax(min(100%,220px),1fr))] gap-3 max-[600px]:grid-cols-2 max-[600px]:gap-2" role="group" aria-label="场景模板">
-          {visibleTemplates.map((template) => {
-            const selected = template.id === selectedTemplateId;
-            return (
-              <button
-                key={template.id}
-                type="button"
-                aria-pressed={selected}
-                className={cn(
-                  'relative grid min-h-0 min-w-0 content-start grid-rows-[auto_auto] gap-2 rounded-[11px] border border-[var(--onboarding-line)] bg-[color-mix(in_oklch,var(--onboarding-panel)_74%,transparent)] p-[11px] text-left text-[var(--onboarding-subtle)] transition-colors hover:border-[color-mix(in_oklch,var(--brand)_45%,var(--onboarding-line))] max-[600px]:p-2',
-                  selected && 'border-[color-mix(in_oklch,var(--brand)_55%,var(--border))] bg-[var(--card)]',
-                )}
-                onClick={() => setSelectedTemplateId((current) => current === template.id ? null : template.id)}
-              >
-                <NotebookTemplateCardContent template={template} />
-                {selected && (
-                  <span
-                    className="pointer-events-none absolute inset-0 z-[1] grid place-items-center rounded-[inherit] bg-[color-mix(in_oklch,var(--background)_68%,transparent)]"
-                    aria-hidden="true"
-                  >
-                    <Check size={32} className="text-[var(--brand)]" strokeWidth={3} />
-                  </span>
-                )}
-              </button>
-            );
-          })}
-        </div>
+        {status === 'ready' && (
+          <div className="mt-[18px] grid grid-cols-[repeat(auto-fill,minmax(min(100%,220px),1fr))] gap-3 max-[600px]:grid-cols-2 max-[600px]:gap-2" role="group" aria-label="场景模板">
+            {visibleTemplates.map((template) => {
+              const selected = template.id === selectedTemplateId;
+              return (
+                <button
+                  key={template.id}
+                  type="button"
+                  aria-pressed={selected}
+                  className={cn(
+                    'relative grid min-h-0 min-w-0 content-start grid-rows-[auto_auto] gap-2 rounded-[11px] border border-[var(--onboarding-line)] bg-[color-mix(in_oklch,var(--onboarding-panel)_74%,transparent)] p-[11px] text-left text-[var(--onboarding-subtle)] transition-colors hover:border-[color-mix(in_oklch,var(--brand)_45%,var(--onboarding-line))] max-[600px]:p-2',
+                    selected && 'border-[color-mix(in_oklch,var(--brand)_55%,var(--border))] bg-[var(--card)]',
+                  )}
+                  onClick={() => setSelectedTemplateId((current) => current === template.id ? null : template.id)}
+                >
+                  <NotebookTemplateCardContent template={template} />
+                  {selected && (
+                    <span
+                      className="pointer-events-none absolute inset-0 z-[1] grid place-items-center rounded-[inherit] bg-[color-mix(in_oklch,var(--background)_68%,transparent)]"
+                      aria-hidden="true"
+                    >
+                      <Check size={32} className="text-[var(--brand)]" strokeWidth={3} />
+                    </span>
+                  )}
+                </button>
+              );
+            })}
+          </div>
+        )}
       </main>
 
       <footer className="flex justify-end gap-2 border-t border-[var(--onboarding-line)] bg-[var(--frame-bg)] px-[clamp(20px,5vw,64px)] pb-[calc(14px+env(safe-area-inset-bottom))] pt-[14px]">
diff --git a/app/flowix-web/features/onboarding/notebook-templates.ts b/app/flowix-web/features/onboarding/notebook-templates.ts
index 17669dd6b..9ededef41 100644
--- a/app/flowix-web/features/onboarding/notebook-templates.ts
+++ b/app/flowix-web/features/onboarding/notebook-templates.ts
@@ -10,7 +10,10 @@ export function useNotebookTemplates(enabled = true) {
   const [status, setStatus] = useState<NotebookTemplateLoadStatus>('idle');
   const [retryCount, setRetryCount] = useState(0);
 
-  const retry = useCallback(() => setRetryCount((count) => count + 1), []);
+  const retry = useCallback(() => {
+    setStatus('loading');
+    setRetryCount((count) => count + 1);
+  }, []);
 
   useEffect(() => {
     if (!enabled) {
@@ -38,7 +41,9 @@ export function useNotebookTemplates(enabled = true) {
 
   return {
     templates,
-    status,
+    // Show the loading state in the same render that opens the picker; the
+    // effect below starts the request immediately after that commit.
+    status: enabled && status === 'idle' ? 'loading' : status,
     retry,
   } as const;
 }
diff --git a/app/flowix-web/features/onboarding/onboarding-flow.test.tsx b/app/flowix-web/features/onboarding/onboarding-flow.test.tsx
index 398581d21..8ccf1f274 100644
--- a/app/flowix-web/features/onboarding/onboarding-flow.test.tsx
+++ b/app/flowix-web/features/onboarding/onboarding-flow.test.tsx
@@ -1,13 +1,11 @@
 import { act, useCallback, useState } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { BootFeatures, NotebookImportStatus, NotebookRecord } from '@platform/tauri/client';
+import type { NotebookImportStatus, NotebookRecord } from '@platform/tauri/client';
 
-// Only desktop IPC and unrelated window chrome are replaced. The wizard, registration,
-// boot controller, empty-notebook policy, import monitoring and retry UI run together.
+// Only unrelated desktop IPC and window chrome are replaced. The wizard,
+// notebook policy, import monitoring and retry UI run together.
 const mocks = vi.hoisted(() => ({
-  getFeatures: vi.fn(),
-  setOnboardingCompleted: vi.fn(),
   create: vi.fn(),
   list: vi.fn(),
   getDefaultPath: vi.fn(),
@@ -21,11 +19,7 @@ const mocks = vi.hoisted(() => ({
 }));
 
 vi.mock('@platform/tauri/client', () => ({
-  boot: {
-    getFeatures: mocks.getFeatures,
-    setOnboardingCompleted: mocks.setOnboardingCompleted,
-    setIntroDisplayed: vi.fn(),
-  },
+  boot: {},
   consumeAppUpdateResult: async () => null,
   dshIntegration: { downloadStatus: async () => null },
   notebooks: {
@@ -57,24 +51,30 @@ vi.mock('@features/memo/public/shell-api', async () => ({
 }));
 vi.mock('@features/memo/store/note-store', async () => {
   const { create } = await import('zustand');
-  return { useNoteStore: create(() => ({
+  type MockNoteStore = {
+    selectedNotebook: NotebookRecord | null;
+    notebooks: NotebookRecord[];
+    startupPhase: 'ready';
+    setNotebooks(notebooks: NotebookRecord[]): void;
+  };
+  return { useNoteStore: create<MockNoteStore>()((set) => ({
     selectedNotebook: null as NotebookRecord | null,
-    setNotebooks: () => {},
+    notebooks: [] as NotebookRecord[],
+    startupPhase: 'ready' as const,
+    setNotebooks: (notebooks: NotebookRecord[]) => set({ notebooks }),
   })) };
 });
 vi.mock('@features/workspace/public/shell-api', () => ({ selectNotebook: mocks.selectNotebook }));
 vi.mock('@features/preferences/public/app-api', () => ({
   useAppUpdatePreferences: () => ({ loading: false, enabled: false }),
 }));
-vi.mock('@features/preferences/public/system-api', () => ({
-  useDshRuntimeInstaller: () => ({ busy: false, status: null }),
-}));
 vi.mock('@features/shell/public/system-api', () => ({ useAppUpdater: () => ({}) }));
 vi.mock('@shared/window-titlebar-controls', () => ({ WindowsTitlebarControls: () => null }));
 vi.mock('@features/shortcuts', () => ({ isMac: () => false }));
 vi.mock('@features/memo/components/notebook-icon-popover', () => ({ NotebookIconPopover: () => null }));
 
 import { I18nProvider } from '@/lib/i18n';
+import { admitStartupStage3 } from '@/lib/startup-stage3';
 import { useMainWindowSystemController } from '@app/main-window/use-main-window-system-controller';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { useEmptyNotebookPrompt } from '@features/memo/hooks/use-empty-notebook-prompt';
@@ -87,7 +87,6 @@ const notebook: NotebookRecord = {
   id: 'first-book', name: 'My Notebook', path: '/notes/My Notebook',
   createdAt: 1, updatedAt: 1, isDefault: false,
 };
-let savedBoot: BootFeatures;
 let host: HTMLDivElement;
 let root: Root;
 
@@ -105,7 +104,6 @@ function FirstRunHarness() {
   });
   return <>
     {ordinaryCreateOpen && <div data-ordinary-create>普通新建笔记本</div>}
-    {system.dshInstallPromptOpen && <div data-agent-intro>Agent 安装引导</div>}
     {selectedNotebook && <div data-workspace>{selectedNotebook.name}</div>}
     {introOpen && <div data-product-intro>产品介绍</div>}
     {system.onboardingOpen && <OnboardingScreen onFinish={async (book, options) => {
@@ -120,7 +118,10 @@ function FirstRunHarness() {
 }
 
 async function mount() {
-  await act(async () => root.render(<I18nProvider language="zh-CN"><FirstRunHarness /></I18nProvider>));
+  await act(async () => {
+    admitStartupStage3();
+    root.render(<I18nProvider language="zh-CN"><FirstRunHarness /></I18nProvider>);
+  });
 }
 
 function button(text: string): HTMLButtonElement {
@@ -151,9 +152,6 @@ beforeEach(() => {
   vi.resetAllMocks();
   mocks.listeners.clear();
   for (const notice of getActionableNotices()) clearActionableNotice(notice.id);
-  savedBoot = { experimental: false, isIntroductDisplayed: false, isOnboardingCompleted: false };
-  mocks.getFeatures.mockImplementation(async () => ({ ...savedBoot }));
-  mocks.setOnboardingCompleted.mockImplementation(async () => { savedBoot.isOnboardingCompleted = true; });
   mocks.create.mockResolvedValue(notebook);
   mocks.list.mockResolvedValue([notebook]);
   mocks.getDefaultPath.mockResolvedValue(notebook.path);
@@ -163,7 +161,7 @@ beforeEach(() => {
   mocks.selectNotebook.mockImplementation(async (book: NotebookRecord) => {
     useNoteStore.setState({ selectedNotebook: book });
   });
-  useNoteStore.setState({ selectedNotebook: null });
+  useNoteStore.setState({ selectedNotebook: null, notebooks: [], startupPhase: 'ready' });
   host = document.createElement('div');
   document.body.appendChild(host);
   root = createRoot(host);
@@ -177,19 +175,14 @@ afterEach(async () => {
 });
 
 describe('first-run notebook setup', () => {
-  it('suppresses the ordinary create screen while boot is pending and enters the workspace with one create', async () => {
-    let resolveBoot!: (features: BootFeatures) => void;
-    mocks.getFeatures.mockReturnValueOnce(new Promise<BootFeatures>((resolve) => { resolveBoot = resolve; }));
+  it('suppresses the ordinary create screen while notebook context is ready and enters the workspace with one create', async () => {
     await mount();
-    expect(host.querySelector('[data-ordinary-create]')).toBeNull();
-    await act(async () => resolveBoot(savedBoot));
     expect(host.querySelector('#flowix-onboarding-notebook-form')).not.toBeNull();
     expect(host.textContent).not.toContain('接入 Agent');
 
     await click('创建并开始使用');
     expect(mocks.create).toHaveBeenCalledTimes(1);
     expect(mocks.startImport).toHaveBeenCalledWith(notebook.id);
-    expect(savedBoot.isOnboardingCompleted).toBe(true);
     expect(host.querySelector('#flowix-onboarding-notebook-form')).toBeNull();
     expect(host.querySelector('[data-ordinary-create]')).toBeNull();
     expect(host.querySelector('[data-workspace]')).not.toBeNull();
@@ -199,30 +192,26 @@ describe('first-run notebook setup', () => {
     expect(mocks.listeners.size).toBe(0);
   });
 
-  it('does not bring Agent onboarding back on the next launch even if the legacy intro flag is false', async () => {
+  it('closes notebook onboarding after successful setup', async () => {
     await mount();
     await click('创建并开始使用');
     await emitImport('completed');
     await act(async () => root.unmount());
     root = createRoot(host);
     await mount();
-    expect(savedBoot.isIntroductDisplayed).toBe(false);
     expect(host.querySelector('#flowix-onboarding-notebook-form')).toBeNull();
     expect(host.querySelector('[data-ordinary-create]')).toBeNull();
-    expect(host.querySelector('[data-agent-intro]')).toBeNull();
     expect(mocks.create).toHaveBeenCalledTimes(1);
   });
 
-  it('keeps creation failures retryable without recording completion', async () => {
+  it('keeps creation failures retryable', async () => {
     mocks.create.mockRejectedValueOnce(new Error('PATH_CREATE_FAILED'));
     await mount();
     await click('创建并开始使用');
     expect(host.querySelector('[role="alert"]')?.textContent).toContain('PATH_CREATE_FAILED');
-    expect(mocks.setOnboardingCompleted).not.toHaveBeenCalled();
     expect(mocks.startImport).not.toHaveBeenCalled();
     await click('创建并开始使用');
     expect(mocks.create).toHaveBeenCalledTimes(2);
-    expect(savedBoot.isOnboardingCompleted).toBe(true);
   });
 
   it('retries workspace selection with the registered notebook instead of creating a second one', async () => {
@@ -230,7 +219,6 @@ describe('first-run notebook setup', () => {
     await mount();
     await click('创建并开始使用');
     expect(host.querySelector('[role="alert"]')?.textContent).toContain('NOTEBOOK_UNAVAILABLE');
-    expect(mocks.setOnboardingCompleted).not.toHaveBeenCalled();
     expect(mocks.startImport).not.toHaveBeenCalled();
     await click('重试');
     expect(mocks.create).toHaveBeenCalledTimes(1);
@@ -244,25 +232,19 @@ describe('first-run notebook setup', () => {
     await mount();
     await click('创建并开始使用');
     expect(host.querySelector('[role="alert"]')?.textContent).toContain('IMPORT_START_FAILED');
-    expect(mocks.setOnboardingCompleted).not.toHaveBeenCalled();
     expect(mocks.listeners.size).toBe(0);
     await click('重试');
     expect(mocks.create).toHaveBeenCalledTimes(1);
     expect(mocks.startImport).toHaveBeenCalledTimes(2);
-    expect(savedBoot.isOnboardingCompleted).toBe(true);
   });
 
-  it('does not dismiss setup when completion persistence fails', async () => {
+  it('dismisses setup after import completion without a completion-state write', async () => {
     mocks.getImportStatus.mockResolvedValue({ notebookId: notebook.id, status: 'completed' });
-    mocks.setOnboardingCompleted.mockRejectedValueOnce(new Error('BOOT_WRITE_FAILED'));
     await mount();
     await click('创建并开始使用');
-    expect(host.querySelector('[role="alert"]')?.textContent).toContain('BOOT_WRITE_FAILED');
-    expect(savedBoot.isOnboardingCompleted).toBe(false);
-    expect(host.querySelector('[data-product-intro]')).toBeNull();
-    await click('重试');
     expect(mocks.create).toHaveBeenCalledTimes(1);
-    expect(savedBoot.isOnboardingCompleted).toBe(true);
+    expect(host.querySelector('#flowix-onboarding-notebook-form')).toBeNull();
+    expect(host.querySelector('[data-product-intro]')).not.toBeNull();
   });
 
   it('passes scene templates to deferred setup without starting the ordinary importer', async () => {
@@ -271,7 +253,6 @@ describe('first-run notebook setup', () => {
     await click('创建并开始使用');
     expect(mocks.create).toHaveBeenCalledWith('My Notebook', undefined, null, false, 'project', false);
     expect(mocks.startImport).not.toHaveBeenCalled();
-    expect(savedBoot.isOnboardingCompleted).toBe(true);
     expect(host.querySelector('[data-ordinary-create]')).toBeNull();
   });
 
@@ -282,7 +263,6 @@ describe('first-run notebook setup', () => {
     await selectTemplate();
     await click('创建并开始使用');
     expect(mocks.create).toHaveBeenCalledTimes(1);
-    expect(mocks.setOnboardingCompleted).not.toHaveBeenCalled();
     expect(host.querySelector('#flowix-onboarding-notebook-form')).not.toBeNull();
     expect(button('创建并开始使用').disabled).toBe(false);
   });
@@ -295,7 +275,6 @@ describe('first-run notebook setup', () => {
     expect(mocks.selectNotebook).toHaveBeenCalledWith(notebook);
     expect(mocks.create).toHaveBeenCalledTimes(1);
     expect(mocks.startImport).not.toHaveBeenCalled();
-    expect(savedBoot.isOnboardingCompleted).toBe(true);
   });
 
   it('offers a real retry button after background import failure and retries the original notebook', async () => {
@@ -350,19 +329,9 @@ describe('first-run notebook setup', () => {
     expect(mocks.listeners.size).toBe(0);
   });
 
-  it('still offers ordinary notebook creation when setup is completed but no notebook remains', async () => {
-    savedBoot.isOnboardingCompleted = true;
+  it('opens onboarding when no notebook exists', async () => {
     await mount();
-    expect(host.querySelector('[data-ordinary-create]')).not.toBeNull();
-    expect(host.querySelector('#flowix-onboarding-notebook-form')).toBeNull();
+    expect(host.querySelector('#flowix-onboarding-notebook-form')).not.toBeNull();
     expect(host.querySelector('[data-agent-intro]')).toBeNull();
   });
-
-  it('releases the empty-notebook fallback when the boot lookup fails', async () => {
-    mocks.getFeatures.mockRejectedValueOnce(new Error('BOOT_UNAVAILABLE'));
-    await mount();
-    expect(host.querySelector('[data-ordinary-create]')).not.toBeNull();
-    expect(host.querySelector('#flowix-onboarding-notebook-form')).toBeNull();
-    expect(mocks.setOnboardingCompleted).not.toHaveBeenCalled();
-  });
 });
diff --git a/app/flowix-web/features/onboarding/onboarding-screen.tsx b/app/flowix-web/features/onboarding/onboarding-screen.tsx
index f08a9ef56..a46574982 100644
--- a/app/flowix-web/features/onboarding/onboarding-screen.tsx
+++ b/app/flowix-web/features/onboarding/onboarding-screen.tsx
@@ -1,10 +1,12 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { ChevronRight, CircleAlert, LoaderCircle } from 'lucide-react';
-import { Button } from '@shared/ui/button';
-import { Input } from '@shared/ui/input';
-import { NotebookIconPopover } from '@features/memo/components/notebook-icon-popover';
+import { CircleAlert } from 'lucide-react';
+import {
+  NOTEBOOK_CREATE_PAGE_GUTTER_CLASS,
+  NotebookCreateFooter,
+  NotebookCreateForm,
+} from '@features/memo/components/notebook-create-form';
 import { dialogs, notebooks, type NotebookRecord } from '@platform/tauri/client';
 import { createNotebookRegistration, notebookRepository } from '@features/memo/services';
 import { useNoteStore } from '@features/memo/store/note-store';
@@ -12,7 +14,7 @@ import { useI18n } from '@/lib/i18n';
 import { WindowsTitlebarControls } from '@shared/window-titlebar-controls';
 import { isMac } from '@features/shortcuts';
 import { useNotebookTemplates } from './notebook-templates';
-import { NotebookTemplateCardPreview, NotebookTemplateEmptyCard, NotebookTemplatePicker } from './notebook-template-picker';
+import { NotebookTemplatePicker } from './notebook-template-picker';
 import { OnboardingTitlebarMac } from './onboarding-titlebar-mac';
 
 const DEFAULT_BOOK_FOLDER = 'My Notebook';
@@ -24,23 +26,24 @@ function defaultFolderNameForNotebook(name: string): string {
 }
 
 interface OnboardingScreenProps {
-  onFinish(notebook: NotebookRecord, options: { startImport: boolean }): Promise<void>;
+  onFinish(notebook: NotebookRecord, options: { startImport: boolean; templateId?: string | null }): Promise<void>;
 }
 
 export function OnboardingScreen({ onFinish }: OnboardingScreenProps) {
   const { t } = useI18n();
+  const [isTemplatePickerOpen, setIsTemplatePickerOpen] = useState(false);
   const {
     templates: notebookTemplates,
     status: notebookTemplateStatus,
     retry: retryNotebookTemplates,
-  } = useNotebookTemplates();
-  const [isTemplatePickerOpen, setIsTemplatePickerOpen] = useState(false);
+  } = useNotebookTemplates(isTemplatePickerOpen);
   const [defaultPath, setDefaultPath] = useState<string | null>(null);
   const [notebookName, setNotebookName] = useState(DEFAULT_NOTEBOOK_NAME);
   const [notebookPath, setNotebookPath] = useState<string | null>(null);
   const [notebookIcon, setNotebookIcon] = useState<string | null>(null);
   const [selectedTemplateId, setSelectedTemplateId] = useState<string | null>(null);
   const [createdNotebook, setCreatedNotebook] = useState<NotebookRecord | null>(null);
+  const [createdTemplateId, setCreatedTemplateId] = useState<string | null>(null);
   const [shouldStartImport, setShouldStartImport] = useState(false);
   const [isCreatingNotebook, setIsCreatingNotebook] = useState(false);
   const [isFinishing, setIsFinishing] = useState(false);
@@ -56,11 +59,15 @@ export function OnboardingScreen({ onFinish }: OnboardingScreenProps) {
       });
   }, [notebookName, notebookPath]);
 
-  const finishNotebook = async (notebook: NotebookRecord, startImport: boolean) => {
+  const finishNotebook = async (
+    notebook: NotebookRecord,
+    startImport: boolean,
+    templateId: string | null = selectedTemplateId,
+  ) => {
     setIsFinishing(true);
     setError(null);
     try {
-      await onFinish(notebook, { startImport });
+      await onFinish(notebook, { startImport, templateId });
     } catch (value) {
       setError(value instanceof Error ? value.message : String(value));
       setIsFinishing(false);
@@ -69,7 +76,7 @@ export function OnboardingScreen({ onFinish }: OnboardingScreenProps) {
 
   const createNotebook = async () => {
     if (createdNotebook) {
-      await finishNotebook(createdNotebook, shouldStartImport);
+      await finishNotebook(createdNotebook, shouldStartImport, createdTemplateId);
       return;
     }
 
@@ -78,41 +85,58 @@ export function OnboardingScreen({ onFinish }: OnboardingScreenProps) {
     setIsCreatingNotebook(true);
     setError(null);
     try {
+      let templateId = selectedTemplateId;
       let registration: Awaited<ReturnType<typeof createNotebookRegistration>>;
       try {
         registration = await createNotebookRegistration({
           name,
           path: notebookPath ?? undefined,
           icon: notebookIcon,
-          templateId: selectedTemplateId,
+          templateId,
           reuseExisting: true,
         });
       } catch (value) {
-        if (
-          !selectedTemplateId
-          || !String(value).includes('NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED')
-        ) {
+        if (!templateId || !String(value).includes('NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED')) {
           throw value;
         }
-        if (!await notebookRepository.confirmPresetOverwrite(t('notebook.template.overwriteConfirm'))) return;
-        registration = await createNotebookRegistration({
-          name,
-          path: notebookPath ?? undefined,
-          icon: notebookIcon,
-          templateId: selectedTemplateId,
-          overwriteExisting: true,
-          reuseExisting: true,
-        });
+        const confirmed = await notebooks.confirmPresetOverwrite(t('notebook.template.overwriteConfirm'));
+        if (confirmed) {
+          registration = await createNotebookRegistration({
+            name,
+            path: notebookPath ?? undefined,
+            icon: notebookIcon,
+            templateId,
+            overwriteExisting: true,
+            reuseExisting: true,
+          });
+        } else {
+          // Keep the notebook creation flow available when the user declines
+          // template replacement; ordinary import will index existing files.
+          templateId = null;
+          setSelectedTemplateId(null);
+          registration = await createNotebookRegistration({
+            name,
+            path: notebookPath ?? undefined,
+            icon: notebookIcon,
+            reuseExisting: true,
+          });
+        }
       }
 
       const notebook = registration.notebook;
       setDefaultPath(notebook.path);
-      const latest = await notebookRepository.list();
-      useNoteStore.getState().setNotebooks(latest);
-      const startImport = registration.needsImport && !registration.hasTemplateSetup;
+      const store = useNoteStore.getState();
+      store.setNotebooks(store.notebooks.some((item) => item.id === notebook.id)
+        ? store.notebooks.map((item) => item.id === notebook.id ? notebook : item)
+        : [...store.notebooks, notebook]);
+      const startImport = registration.needsImport && !templateId && !registration.hasTemplateSetup;
       setCreatedNotebook(notebook);
+      setCreatedTemplateId(templateId);
       setShouldStartImport(startImport);
-      await finishNotebook(notebook, startImport);
+      await finishNotebook(notebook, startImport, templateId);
+      void notebookRepository.list()
+        .then((latest) => useNoteStore.getState().setNotebooks(latest))
+        .catch((value) => console.warn('[Onboarding] Failed to refresh notebook list:', value));
     } catch (value) {
       setError(value instanceof Error ? value.message : String(value));
     } finally {
@@ -130,92 +154,35 @@ export function OnboardingScreen({ onFinish }: OnboardingScreenProps) {
 
   return (
     <div
-      className="fixed inset-0 z-[220] flex flex-col overflow-hidden bg-[var(--frame-bg)] text-[var(--foreground)] [--onboarding-form-gap:22px] [--onboarding-ink:var(--foreground)] [--onboarding-subtle:var(--muted-foreground)] [--onboarding-panel:color-mix(in_oklch,var(--card)_96%,var(--background))] [--onboarding-line:color-mix(in_oklch,var(--border)_78%,transparent)] animate-[flowix-onboarding-in_520ms_cubic-bezier(0.16,1,0.3,1)_both] motion-reduce:animate-none max-[760px]:overflow-y-auto [&_button:focus-visible]:outline-2 [&_button:focus-visible]:outline-[var(--ring)] [&_button:focus-visible]:outline-offset-[3px]"
+      className="fixed inset-0 z-[220] flex flex-col overflow-hidden bg-[var(--frame-bg)] text-[var(--foreground)] [--onboarding-ink:var(--foreground)] [--onboarding-subtle:var(--muted-foreground)] [--onboarding-panel:color-mix(in_oklch,var(--card)_96%,var(--background))] [--onboarding-line:color-mix(in_oklch,var(--border)_78%,transparent)] animate-[flowix-onboarding-in_520ms_cubic-bezier(0.16,1,0.3,1)_both] motion-reduce:animate-none max-[760px]:overflow-y-auto [&_button:focus-visible]:outline-2 [&_button:focus-visible]:outline-[var(--ring)] [&_button:focus-visible]:outline-offset-[3px]"
       role="dialog"
       aria-modal="true"
-      aria-labelledby="flowix-onboarding-notebook-title"
+      aria-labelledby="flowix-onboarding-notebook-form-title"
     >
       {isMac() && <OnboardingTitlebarMac />}
       <WindowsTitlebarControls reserveSpace />
-      <main className="relative z-[1] flex min-h-0 w-full flex-1 flex-col px-[clamp(28px,6vw,96px)] pb-[clamp(22px,3vw,44px)] max-[760px]:px-5 max-[760px]:pb-[26px]">
-        <div className="mx-auto flex min-h-0 w-[min(100%,780px)] flex-1 flex-col items-start justify-center overflow-y-auto overscroll-contain">
-          <section className="w-full animate-[flowix-onboarding-section-in_500ms_ease-out_both] motion-reduce:animate-none py-[clamp(11px,1.33vw,16px)] pb-4" aria-labelledby="flowix-onboarding-notebook-title">
-            <div className="max-w-full">
-              <h1 className="text-[clamp(23px,3.33vw,44px)] font-light leading-[0.98] tracking-[-0.065em] text-[var(--onboarding-ink)]" id="flowix-onboarding-notebook-title">创建你的第一个笔记本</h1>
-              <p className="mt-6 max-w-full text-sm leading-[1.72] text-[var(--onboarding-subtle)]">填写笔记本名称和存储位置，也可以选择一个场景模板开始使用。</p>
-            </div>
-            <form
-              id="flowix-onboarding-notebook-form"
-              className="mt-[22px] grid w-[min(100%,780px)] grid-cols-[minmax(0,1fr)_320px] items-start gap-x-[22px] gap-y-4 p-0 max-[760px]:grid-cols-1"
-              onSubmit={(event) => {
-                event.preventDefault();
-                void createNotebook();
-              }}
-            >
-              <div className="grid min-w-0 content-start gap-4 pr-[38px] max-[760px]:pr-0">
-                <div className="grid min-w-0 gap-1">
-                  <label className="text-sm font-semibold text-[var(--foreground)]" htmlFor="flowix-onboarding-notebook-name">笔记本名称</label>
-                  <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-2">
-                    <Input
-                      id="flowix-onboarding-notebook-name"
-                      value={notebookName}
-                      onChange={(event) => setNotebookName(event.target.value)}
-                      autoFocus
-                      className="h-10 bg-[var(--card)]"
-                      disabled={Boolean(createdNotebook) || isCreatingNotebook || isFinishing}
-                    />
-                    <NotebookIconPopover
-                      value={notebookIcon}
-                      notebookName={notebookName}
-                      onChange={setNotebookIcon}
-                    />
-                  </div>
-                </div>
-                <div className="grid min-w-0 gap-1">
-                  <label className="text-sm font-semibold text-[var(--foreground)]" htmlFor="flowix-onboarding-notebook-path">存储位置</label>
-                  <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-2">
-                    <Input
-                      id="flowix-onboarding-notebook-path"
-                      value={notebookPath ?? defaultPath ?? ''}
-                      placeholder="文档 / flowix / My Notebook"
-                      disabled
-                      readOnly
-                      className="h-10 min-w-0 bg-[var(--card)]"
-                    />
-                    <Button
-                      type="button"
-                      variant="outline"
-                      className="h-10 shrink-0 bg-[var(--card)]"
-                      onClick={() => void selectNotebookDirectory()}
-                      disabled={Boolean(createdNotebook) || isCreatingNotebook || isFinishing}
-                    >
-                      选择目录
-                    </Button>
-                  </div>
-                </div>
-              </div>
-              <div className="grid min-w-0 content-start gap-1">
-                <button
-                  type="button"
-                  className="flex w-full items-center justify-start gap-0.5 p-0 text-left text-sm font-semibold text-[var(--foreground)] hover:text-[var(--brand)]"
-                  aria-haspopup="dialog"
-                  onClick={() => setIsTemplatePickerOpen(true)}
-                  disabled={Boolean(createdNotebook) || isCreatingNotebook || isFinishing}
-                >
-                  <span>选择场景模板（可选）</span>
-                  <ChevronRight size={16} aria-hidden="true" />
-                </button>
-                {notebookTemplates.find((template) => template.id === selectedTemplateId) && (
-                  <NotebookTemplateCardPreview
-                    template={notebookTemplates.find((template) => template.id === selectedTemplateId)!}
-                    onSwitch={() => setIsTemplatePickerOpen(true)}
-                  />
-                )}
-                {!selectedTemplateId && (
-                  <NotebookTemplateEmptyCard onClick={() => setIsTemplatePickerOpen(true)} />
-                )}
-              </div>
-            </form>
+      <main className={`relative z-[1] flex min-h-0 w-full flex-1 flex-col ${NOTEBOOK_CREATE_PAGE_GUTTER_CLASS} pb-[clamp(22px,3vw,44px)] max-[760px]:pb-[26px]`}>
+        <div className="mx-auto flex min-h-0 w-[min(100%,680px)] flex-1 flex-col items-start justify-center overflow-y-auto overscroll-contain">
+          <section className="w-full animate-[flowix-onboarding-section-in_500ms_ease-out_both] motion-reduce:animate-none py-[clamp(11px,1.33vw,16px)] pb-4" aria-labelledby="flowix-onboarding-notebook-form-title">
+            <NotebookCreateForm
+              title="创建第一个笔记本"
+              formId="flowix-onboarding-notebook-form"
+              name={notebookName}
+              onNameChange={setNotebookName}
+              nameLabel="笔记本名称"
+              pathLabel="存储位置"
+              path={notebookPath ?? defaultPath ?? ''}
+              pathPlaceholder="默认文稿位置"
+              directoryButtonLabel="选择目录"
+              onSelectDirectory={() => void selectNotebookDirectory()}
+              icon={notebookIcon}
+              onIconChange={setNotebookIcon}
+              templates={notebookTemplates}
+              selectedTemplateId={selectedTemplateId}
+              onSelectTemplate={() => setIsTemplatePickerOpen(true)}
+              disabled={Boolean(createdNotebook) || isCreatingNotebook || isFinishing}
+              onSubmit={() => void createNotebook()}
+            />
           </section>
 
           {error && (
@@ -223,18 +190,12 @@ export function OnboardingScreen({ onFinish }: OnboardingScreenProps) {
           )}
         </div>
 
-        <div className="sticky bottom-0 z-[2] mx-auto flex min-h-[62px] w-[min(100%,780px)] flex-[0_0_auto] items-center justify-end gap-[18px] border-t border-[var(--onboarding-line)] bg-[var(--frame-bg)] pt-[18px] max-[760px]:min-h-[58px] max-[760px]:pt-[14px]">
-          <button
-            type="submit"
-            form="flowix-onboarding-notebook-form"
-            className="inline-flex min-h-[38px] items-center justify-center gap-1 rounded-[9px] border border-[var(--brand)] bg-[var(--brand)] px-[15px] text-xs font-semibold text-[var(--primary-foreground)] shadow-[0_8px_18px_color-mix(in_oklch,var(--brand)_18%,transparent)] transition-transform hover:-translate-y-px disabled:cursor-not-allowed disabled:opacity-[0.46] max-[760px]:flex-1"
-            disabled={isCreatingNotebook || isFinishing || !notebookName.trim() || (!createdNotebook && !notebookPath && !defaultPath)}
-          >
-            {isCreatingNotebook || isFinishing
-              ? <><LoaderCircle size={17} className="animate-spin" aria-hidden="true" /> 正在进入</>
-              : <>{createdNotebook ? t('error.retry') : '创建并开始使用'} <ChevronRight size={14} className="-ml-1" aria-hidden="true" /></>}
-          </button>
-        </div>
+        <NotebookCreateFooter
+          formId="flowix-onboarding-notebook-form"
+          disabled={!notebookName.trim() || (!createdNotebook && !notebookPath && !defaultPath)}
+          isBusy={isCreatingNotebook || isFinishing}
+          submitLabel={createdNotebook ? t('error.retry') : '创建并开始使用'}
+        />
         {isTemplatePickerOpen && (
           <NotebookTemplatePicker
             templates={notebookTemplates}
diff --git a/app/flowix-web/features/plugin/plugin-agent-workbench.tsx b/app/flowix-web/features/plugin/plugin-agent-workbench.tsx
index f887e55c6..93f46e562 100644
--- a/app/flowix-web/features/plugin/plugin-agent-workbench.tsx
+++ b/app/flowix-web/features/plugin/plugin-agent-workbench.tsx
@@ -18,9 +18,8 @@ import {
   type PluginDescriptor,
   type PluginField,
 } from '@platform/tauri/client';
-import {
-  openBrowserColumnMarkdown,
-} from '@features/workspace/use-cases/browser-column-navigation';
+import type { SurfaceNotice, SurfacePresentationUpdate } from '@features/workspace/public/surface-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
 import { runPlugin } from './plugin-runner';
 import {
@@ -54,11 +53,13 @@ export function AgentPluginWorkbench({
   notebookPath,
   currentNotePath,
   currentNoteContent,
+  reportPresentation,
 }: {
   plugin: PluginDescriptor;
   notebookPath: string | undefined;
   currentNotePath: string | null;
   currentNoteContent: string;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
 }) {
   const [values, setValues] = useState<Record<string, PluginFieldValue>>({ prompt: '' });
   const [agentType, setAgentType] = useState<AgentTypeKey>(DEFAULT_AGENT_TYPE_KEY);
@@ -81,7 +82,7 @@ export function AgentPluginWorkbench({
   const runStatus = run?.status ?? null;
   const hasCanvasControls = artifact?.renderer === 'markmap';
   const agentOptions = useMemo(
-    () => AGENT_TYPES.filter((item) => isAgentTypeSelectable(item.key)),
+    () => AGENT_TYPES.filter((item) => isAgentTypeSelectable(item.id)),
     [],
   );
   const fields = useMemo(() => fieldList(plugin), [plugin]);
@@ -100,13 +101,23 @@ export function AgentPluginWorkbench({
 
   const handleOpenArtifact = useCallback(() => {
     if (!artifact) return;
-    const opening = openBrowserColumnMarkdown(artifact.path);
+    const opening = openWorkspaceSurface({
+      host: 'browser-column',
+      target: { kind: 'external', path: artifact.path, scopePath: null, transitionId: null },
+    });
     void opening.catch((error) => {
       console.error('[AgentPluginWorkbench] Failed to open artifact', error);
     });
   }, [artifact]);
 
   useEffect(() => { ensurePluginRunStoreSubscription(); }, [plugin.manifest.id]);
+  useEffect(() => {
+    const notices: SurfaceNotice[] = [];
+    if (running) notices.push({ id: 'plugin-generation', severity: 'info', message: { key: 'plugin.workbench.generating' } });
+    if (error) notices.push({ id: 'plugin-generation-error', severity: 'error',
+      message: { key: 'error.unexpected', fallbackText: error } });
+    reportPresentation?.({ state: { status: 'ready', notices } });
+  }, [error, reportPresentation, running]);
   useEffect(() => {
     const handleFullscreenChange = () => setIsFullscreen(document.fullscreenElement === canvasRef.current);
     document.addEventListener('fullscreenchange', handleFullscreenChange);
@@ -223,11 +234,11 @@ export function AgentPluginWorkbench({
             );
           })}
           <button disabled={!canGenerate} onClick={() => void handleGenerate()} className="inline-flex items-center justify-center gap-2 rounded-lg bg-[var(--brand)] px-3 py-2 text-sm font-medium text-[var(--primary-foreground)] disabled:cursor-not-allowed disabled:opacity-50">
-            {running ? <SpinnerIcon size={16} weight="bold" className="animate-spin" /> : <MagicWandIcon size={16} weight="bold" />}
+            {running ? <SpinnerIcon size={16} weight="bold" className="flowix-spin" /> : <MagicWandIcon size={16} weight="bold" />}
             {running ? '生成中…' : runStatus === 'completed' ? '重新生成' : '生成插件产物'}
           </button>
           {missingRequiredField && <p className="text-xs text-[var(--muted-foreground)]">请填写必填项：{pluginFieldLabel(missingRequiredField)}</p>}
-          {error && <p className="rounded-lg bg-[color-mix(in_oklch,var(--destructive)_10%,transparent)] p-3 text-xs text-[var(--destructive)]">{error}</p>}
+          {error && !reportPresentation && <p className="rounded-lg bg-[color-mix(in_oklch,var(--destructive)_10%,transparent)] p-3 text-xs text-[var(--destructive)]">{error}</p>}
         </div>
       )}
       <div className="min-h-0 flex-1 overflow-hidden">
diff --git a/app/flowix-web/features/plugin/plugin-document-view.tsx b/app/flowix-web/features/plugin/plugin-document-view.tsx
index bef5351f1..a1fc831d4 100644
--- a/app/flowix-web/features/plugin/plugin-document-view.tsx
+++ b/app/flowix-web/features/plugin/plugin-document-view.tsx
@@ -10,39 +10,78 @@ import { artifacts, type ArtifactSession } from '@platform/tauri/client';
 import { useDocumentStore } from '@features/document/store/document-store';
 import { PluginArtifactRenderer, type PluginArtifactRendererHandle } from './plugin-artifact-renderer';
 import { PluginMarkmapControls } from './plugin-markmap-controls';
+import type { SurfacePresentationUpdate } from '@features/workspace/public/surface-api';
 
 export function PluginDocumentView({
   notePath,
   transitionId,
+  reportPresentation,
 }: {
   notePath: string;
   transitionId?: number;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
 }) {
   const [artifact, setArtifact] = useState<ArtifactSession | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [fullscreen, setFullscreen] = useState(false);
   const canvasRef = useRef<HTMLDivElement>(null);
   const rendererRef = useRef<PluginArtifactRendererHandle>(null);
+  const requestSequenceRef = useRef(0);
+  const currentNotePathRef = useRef(notePath);
+  currentNotePathRef.current = notePath;
+  const retryPresentation = useCallback(() => {
+    // Re-mount the renderer; its effect starts a fresh artifact resolution.
+    reportPresentation?.({ state: { status: 'ready' } });
+  }, [reportPresentation]);
 
   const load = useCallback(async () => {
+    const requestSequence = ++requestSequenceRef.current;
+    const isCurrentRequest = () => requestSequence === requestSequenceRef.current
+      && currentNotePathRef.current === notePath;
     setError(null);
+    reportPresentation?.({
+      state: { status: 'loading', phase: 'content', message: { key: 'memo.navigation.loading' }, retainContent: true },
+    });
     try {
-      setArtifact(await artifacts.resolve(notePath));
+      const resolved = await artifacts.resolve(notePath);
+      if (!isCurrentRequest()) return;
+      setArtifact(resolved);
+      reportPresentation?.({
+        title: resolved.name,
+        state: resolved.content?.length
+          ? { status: 'ready' }
+          : {
+              status: 'unavailable', reason: 'unsupported',
+              message: { key: 'error.unexpected', fallbackText: resolved.error ?? '插件产物内容不可读' },
+              actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retryPresentation }],
+            },
+      });
     } catch (loadError) {
+      if (!isCurrentRequest()) return;
       setArtifact(null);
       setError(loadError instanceof Error ? loadError.message : String(loadError));
+      reportPresentation?.({
+        state: {
+          status: 'error',
+          message: { key: 'error.unexpected', fallbackText: loadError instanceof Error ? loadError.message : String(loadError) },
+          actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retryPresentation }],
+        },
+      });
     } finally {
       // Plugin pointer notes bypass DocumentContainer, which normally owns
       // the document transition completion callback. Complete the same
       // transition after the pointer/artifact has been resolved, otherwise
       // MainLayout's document loading overlay remains visible forever.
-      if (transitionId !== undefined) {
+      if (isCurrentRequest() && transitionId !== undefined) {
         useDocumentStore.getState().finishDocumentTransition(transitionId);
       }
     }
-  }, [notePath, transitionId]);
+  }, [notePath, reportPresentation, retryPresentation, transitionId]);
 
-  useEffect(() => { void load(); }, [load]);
+  useEffect(() => {
+    void load();
+    return () => { requestSequenceRef.current += 1; };
+  }, [load]);
   useEffect(() => {
     const onFullscreenChange = () => setFullscreen(document.fullscreenElement === canvasRef.current);
     document.addEventListener('fullscreenchange', onFullscreenChange);
diff --git a/app/flowix-web/features/plugin/plugin-field-control.tsx b/app/flowix-web/features/plugin/plugin-field-control.tsx
index 6004d0a7a..0eb3dfaa0 100644
--- a/app/flowix-web/features/plugin/plugin-field-control.tsx
+++ b/app/flowix-web/features/plugin/plugin-field-control.tsx
@@ -3,6 +3,7 @@
 import type { AgentTypeKey } from '@/types/agent';
 import { AGENT_TYPES } from '@/lib/agent-types';
 import type { PluginField } from '@platform/tauri/client';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 
 export type PluginFieldValue = string | boolean;
 
@@ -37,7 +38,7 @@ export function PluginFieldControl({
   const className = 'rounded-lg border border-[var(--border)] bg-[var(--background)] p-2 text-sm outline-none focus:border-[var(--brand)]';
   const options = field.options?.length
     ? field.options
-    : agentOptions.map((item) => ({ value: item.key, label: item.name }));
+    : agentOptions.map((item) => ({ value: item.id, label: item.name }));
 
   if (field.type === 'agent-select' || field.id === 'agentType') {
     return (
@@ -70,16 +71,14 @@ export function PluginFieldControl({
 
   if (field.type === 'checkbox') {
     return (
-      <label className="flex items-center gap-2 text-sm text-[var(--foreground)]" htmlFor={id}>
-        <input
-          id={id}
-          type="checkbox"
+      <div className="flex items-center gap-2 text-sm text-[var(--foreground)]">
+        <FlowixCheckbox
           checked={value === true}
-          onChange={(event) => onChange(event.target.checked)}
-          className="h-4 w-4 accent-[var(--brand)]"
+          aria-label={field.placeholder || pluginFieldLabel(field)}
+          onCheckedChange={onChange}
         />
-        <span>{field.placeholder || pluginFieldLabel(field)}</span>
-      </label>
+        <span className="cursor-pointer" onClick={() => onChange(value !== true)}>{field.placeholder || pluginFieldLabel(field)}</span>
+      </div>
     );
   }
 
diff --git a/app/flowix-web/features/plugin/plugin-note.test.ts b/app/flowix-web/features/plugin/plugin-note.test.ts
index cbdf520db..6d167eaec 100644
--- a/app/flowix-web/features/plugin/plugin-note.test.ts
+++ b/app/flowix-web/features/plugin/plugin-note.test.ts
@@ -4,7 +4,7 @@ import { getPluginNoteInfo } from './plugin-note';
 
 function memo(properties: Record<string, unknown>): MemoItem {
   return {
-    id: 'memo-1',
+    relativePath: 'memo-1.md',
     filename: 'note.md',
     preview: '',
     tags: [],
diff --git a/app/flowix-web/features/plugin/plugin-workbench.tsx b/app/flowix-web/features/plugin/plugin-workbench.tsx
index b6249b5d2..ca7dcf476 100644
--- a/app/flowix-web/features/plugin/plugin-workbench.tsx
+++ b/app/flowix-web/features/plugin/plugin-workbench.tsx
@@ -10,7 +10,8 @@ import {
 import { joinNotebookMemoPath } from '@/lib/path';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { notes, type PluginDescriptor } from '@platform/tauri/client';
-import { openBrowserColumnMarkdown } from '@features/workspace/use-cases/browser-column-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import type { SurfacePresentationUpdate, SurfaceNotice } from '@features/workspace/public/surface-api';
 import { AgentPluginWorkbench } from './plugin-agent-workbench';
 import { normalizePluginId } from './plugin-note';
 
@@ -19,6 +20,7 @@ interface PluginWorkbenchProps {
   notebookPath: string | undefined;
   currentNotePath: string | null;
   currentNoteContent: string;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
 }
 
 export function PluginWorkbench(props: PluginWorkbenchProps) {
@@ -35,6 +37,7 @@ export function PluginWorkbench(props: PluginWorkbenchProps) {
 function ArtifactToolWorkbench({
   plugin,
   notebookPath,
+  reportPresentation,
 }: PluginWorkbenchProps) {
   const selectedNotebook = useNoteStore((state) => state.selectedNotebook);
   const [documents, setDocuments] = useState<{ relativePath: string; title: string }[]>([]);
@@ -63,6 +66,15 @@ function ArtifactToolWorkbench({
     void load();
   }, [load]);
 
+  useEffect(() => {
+    const notices: SurfaceNotice[] = error ? [{
+      id: 'artifact-list', severity: 'error',
+      message: { key: 'error.unexpected', fallbackText: error },
+      actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: load }],
+    }] : [];
+    reportPresentation?.({ state: { status: 'ready', notices } });
+  }, [error, load, reportPresentation]);
+
   if (!notebookPath || !selectedNotebook) {
     return <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">请先选择一个笔记本</div>;
   }
@@ -86,7 +98,7 @@ function ArtifactToolWorkbench({
           title="刷新"
           aria-label={`刷新${plugin.manifest.name}列表`}
         >
-          <ArrowClockwiseIcon size={16} weight="bold" className={loading ? 'animate-spin' : undefined} />
+          <ArrowClockwiseIcon size={16} weight="bold" className={loading ? 'flowix-spin' : undefined} />
         </button>
       </div>
 
@@ -107,7 +119,7 @@ function ArtifactToolWorkbench({
             </div>
           </div>
 
-          {error && <p className="rounded-lg bg-[color-mix(in_oklch,var(--destructive)_10%,transparent)] p-3 text-sm text-[var(--destructive)]">{error}</p>}
+          {error && !reportPresentation && <p className="rounded-lg bg-[color-mix(in_oklch,var(--destructive)_10%,transparent)] p-3 text-sm text-[var(--destructive)]">{error}</p>}
 
           <section>
             <div className="mb-2 flex items-center justify-between">
@@ -120,7 +132,10 @@ function ArtifactToolWorkbench({
                   className="flex w-full items-center gap-3 border-b border-[var(--divider)] px-4 py-3 text-left last:border-b-0 hover:bg-[var(--muted)]"
                   onClick={() => {
                     const path = joinNotebookMemoPath(selectedNotebook.path, note.relativePath);
-                    if (path) void openBrowserColumnMarkdown(path);
+                    if (path) void openWorkspaceSurface({
+                      host: 'browser-column',
+                      target: { kind: 'external', path, scopePath: null, transitionId: null },
+                    });
                   }}>
                   <TreeStructureIcon size={16} weight="bold" className="shrink-0 text-[var(--muted-foreground)]" />
                   <span className="min-w-0 flex-1 truncate text-sm text-[var(--foreground)]">{note.title}</span>
diff --git a/app/flowix-web/features/preferences/components/dsh-install-prompt.tsx b/app/flowix-web/features/preferences/components/dsh-install-prompt.tsx
deleted file mode 100644
index b4f830fa8..000000000
--- a/app/flowix-web/features/preferences/components/dsh-install-prompt.tsx
+++ /dev/null
@@ -1,275 +0,0 @@
-import { useEffect, useRef, useState } from 'react';
-import { EjectIcon } from '@phosphor-icons/react';
-import { Check, Loader2 } from 'lucide-react';
-import { useI18n } from '@/lib/i18n';
-import { toast } from '@/lib/toast';
-import iconCodex from '@/assets/codex.svg';
-import iconClaudeCode from '@/assets/icon-claude-code.svg';
-import iconFlowixAgent from '@/assets/flowix-agent.svg';
-import iconOpenCode from '@/assets/icon-opencode.svg';
-import { Button } from '@shared/ui/button';
-import { DialogDescription, DialogHeader, DialogTitle } from '@shared/ui/dialog';
-import { UpdateProgress } from '@shared/ui/update-progress';
-import { FloatingPrompt } from '@features/shell/components/floating-prompt';
-import {
-  AgentIcon,
-  getLocalAgentRuntimeStatus,
-} from '@features/agent/public/dsh-onboarding-api';
-import { useCliLinkStatusStore } from '@features/preferences/store';
-import type { DshRuntimeInstallerState } from '@features/preferences/public/system-api';
-
-const LOCAL_AGENT_INTRO_OPTIONS = [
-  { key: 'codex', nameKey: 'agent.types.codex.name', icon: iconCodex },
-  { key: 'claude', nameKey: 'agent.types.claude.name', icon: iconClaudeCode },
-  { key: 'opencode', nameKey: 'agent.types.opencode.name', icon: iconOpenCode },
-] as const;
-type LocalAgentIntroOption = (typeof LOCAL_AGENT_INTRO_OPTIONS)[number];
-
-export function DshInstallPrompt({
-  open,
-  installer,
-  onClose,
-  onIntroDisplayed,
-  onInstalled,
-}: {
-  open: boolean;
-  installer: DshRuntimeInstallerState;
-  onClose: () => void;
-  onIntroDisplayed: () => void;
-  onInstalled: () => void;
-}) {
-  const { t } = useI18n();
-  const { busy, error, progress, install, cancel } = installer;
-  const canCancel = busy && progress?.phase !== 'downloaded' && progress?.phase !== 'installing';
-  const [slide, setSlide] = useState<'mcp' | 'intro' | 'download'>('mcp');
-  const [mcpCopied, setMcpCopied] = useState(false);
-  const [checkingLocalAgents, setCheckingLocalAgents] = useState(false);
-  const [localAgent, setLocalAgent] = useState<LocalAgentIntroOption | null>(null);
-  const lastToastedInstallErrorRef = useRef<string | null>(null);
-  const cliStatus = useCliLinkStatusStore((state) => state.status);
-  const refreshCliStatus = useCliLinkStatusStore((state) => state.refreshIfStale);
-
-  useEffect(() => {
-    if (!open) return;
-    void refreshCliStatus();
-  }, [open, refreshCliStatus]);
-
-  useEffect(() => {
-    if (!open || !error) {
-      lastToastedInstallErrorRef.current = null;
-      return;
-    }
-    if (error && error !== lastToastedInstallErrorRef.current) {
-      lastToastedInstallErrorRef.current = error;
-      toast.error(`${t('preferences.dsh.setup.error')}: ${error}`);
-    }
-  }, [error, open, t]);
-
-  useEffect(() => {
-    if (!open) return;
-    let cancelled = false;
-    setCheckingLocalAgents(true);
-    setLocalAgent(null);
-    void getLocalAgentRuntimeStatus()
-      .then((status) => {
-        if (cancelled) return;
-        const detected = LOCAL_AGENT_INTRO_OPTIONS.find(({ key }) => status[key]?.available);
-        setLocalAgent(detected ?? null);
-      })
-      .catch(() => {
-        if (!cancelled) setLocalAgent(null);
-      })
-      .finally(() => {
-        if (!cancelled) setCheckingLocalAgents(false);
-      });
-    return () => { cancelled = true; };
-  }, [open]);
-
-  const handleInstall = async () => {
-    onIntroDisplayed();
-    const status = await install();
-    if (status) {
-      toast.success(t('preferences.dsh.setup.installSuccess'));
-      onInstalled();
-    }
-  };
-
-  const handleCancel = async () => {
-    if (await cancel()) toast.info(t('preferences.dsh.setup.cancelled'));
-  };
-
-  const handleCopyMcp = async () => {
-    try {
-      await navigator.clipboard.writeText(t('preferences.dsh.setup.mcp.copyContent', {
-        command: cliStatus?.commandPath || 'flowix',
-      }));
-      setMcpCopied(true);
-      toast.success(t('preferences.mcp.copied'));
-      window.setTimeout(() => setMcpCopied(false), 1600);
-    } catch {
-      toast.error(t('preferences.mcp.copyFailed'));
-    }
-  };
-
-  return (
-    <FloatingPrompt open={open} onClose={onClose} className="max-h-[calc(100vh-2rem)] p-0">
-        <div className="px-5 py-5 text-left">
-          <div
-            className="mb-5 flex items-center gap-1.5"
-            role="tablist"
-            aria-label={t('preferences.dsh.setup.carousel')}
-          >
-            <button
-              type="button"
-              role="tab"
-              aria-selected={slide === 'mcp'}
-              aria-label={t('preferences.dsh.setup.mcp.slide')}
-              onClick={() => setSlide('mcp')}
-              className={`h-1.5 rounded-full transition-[width,background-color] ${slide === 'mcp' ? 'w-7 bg-[var(--primary)]' : 'w-3 bg-[var(--muted)]'}`}
-            />
-            <button
-              type="button"
-              role="tab"
-              aria-selected={slide === 'intro'}
-              aria-label={t('preferences.dsh.setup.intro.slide')}
-              onClick={() => setSlide('intro')}
-              className={`h-1.5 rounded-full transition-[width,background-color] ${slide === 'intro' ? 'w-7 bg-[var(--primary)]' : 'w-3 bg-[var(--muted)]'}`}
-            />
-            <button
-              type="button"
-              role="tab"
-              aria-selected={slide === 'download'}
-              aria-label={t('preferences.dsh.setup.download.slide')}
-              onClick={() => setSlide('download')}
-              className={`h-1.5 rounded-full transition-[width,background-color] ${slide === 'download' ? 'w-7 bg-[var(--primary)]' : 'w-3 bg-[var(--muted)]'}`}
-            />
-          </div>
-
-          <div
-            className="relative overflow-hidden"
-            aria-live="polite"
-          >
-            <div
-              className="flex w-[300%] items-start transition-transform duration-300 ease-out will-change-transform"
-              style={{
-                transform: slide === 'mcp'
-                  ? 'translateX(0)'
-                  : slide === 'intro'
-                    ? 'translateX(-33.333333%)'
-                    : 'translateX(-66.666667%)',
-              }}
-            >
-              <section className="w-1/3 shrink-0" aria-hidden={slide !== 'mcp'}>
-                <DialogHeader className="mb-0">
-                  <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-[color-mix(in_oklch,var(--primary)_12%,transparent)] text-[var(--primary)]">
-                    <EjectIcon className="h-7 w-7" weight="regular" aria-hidden="true" />
-                  </div>
-                  <DialogTitle className="mt-3 text-base">
-                    {t('preferences.dsh.setup.mcp.title')}
-                  </DialogTitle>
-                  <DialogDescription className="mt-1 whitespace-pre-line text-xs leading-5">
-                    {t('preferences.dsh.setup.mcp.description')}
-                  </DialogDescription>
-                </DialogHeader>
-              </section>
-
-              <section className="w-1/3 shrink-0" aria-hidden={slide !== 'intro'}>
-                <DialogHeader className="mb-0">
-                  <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-[color-mix(in_oklch,var(--primary)_12%,transparent)]">
-                    <img
-                      src={checkingLocalAgents ? iconFlowixAgent : localAgent?.icon ?? iconFlowixAgent}
-                      alt=""
-                      className="h-7 w-7 object-contain"
-                    />
-                  </div>
-                  <DialogTitle className="mt-3 text-base">
-                    {checkingLocalAgents
-                      ? t('preferences.dsh.setup.intro.checking')
-                      : localAgent
-                        ? t('preferences.dsh.setup.intro.detected', { agent: t(localAgent.nameKey) })
-                        : t('preferences.dsh.setup.intro.none')}
-                  </DialogTitle>
-                  {!checkingLocalAgents && (
-                    <DialogDescription className="mt-1 whitespace-pre-line text-xs leading-5">
-                      {t(
-                        localAgent
-                          ? 'preferences.dsh.setup.intro.description'
-                          : 'preferences.dsh.setup.intro.noAgentDescription',
-                      )}
-                    </DialogDescription>
-                  )}
-                </DialogHeader>
-              </section>
-
-              <section className="w-1/3 shrink-0" aria-hidden={slide !== 'download'}>
-                <DialogHeader className="mb-0">
-                  <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-[color-mix(in_oklch,var(--primary)_12%,transparent)]">
-                    <AgentIcon typeKey="deepseek-harness" alt="" className="h-7 w-7" />
-                  </div>
-                  <DialogTitle className="mt-3 text-base">
-                    {t('preferences.dsh.setup.promptTitle')}
-                  </DialogTitle>
-                  <DialogDescription className="mt-1 whitespace-pre-line text-xs leading-5">
-                    {t('preferences.dsh.setup.promptDescription')}
-                  </DialogDescription>
-                </DialogHeader>
-
-                {busy && progress && (
-                  <UpdateProgress
-                    className="mt-5 text-left"
-                    value={progress}
-                    label={t(progress.phase === 'installing' ? 'preferences.dsh.setup.installing' : 'preferences.dsh.setup.downloading')}
-                    resumedLabel={t('preferences.dsh.setup.resumed')}
-                  />
-                )}
-
-              </section>
-            </div>
-          </div>
-
-          <div className="relative mt-6 min-h-8">
-            <div
-              className={`absolute inset-y-0 right-0 flex items-center gap-2 transition-opacity duration-200 ${slide === 'mcp' ? 'opacity-100' : 'pointer-events-none opacity-0'}`}
-              aria-hidden={slide !== 'mcp'}
-            >
-              <Button type="button" variant="outline" onClick={() => void handleCopyMcp()}>
-                {mcpCopied && <Check className="h-4 w-4" />}
-                {mcpCopied ? t('preferences.mcp.copied') : t('preferences.mcp.copy')}
-              </Button>
-              <Button type="button" onClick={() => setSlide('intro')}>
-                {t('preferences.dsh.setup.next')}
-              </Button>
-            </div>
-            <div
-              className={`absolute inset-y-0 right-0 flex items-center gap-2 transition-opacity duration-200 ${slide === 'intro' ? 'opacity-100' : 'pointer-events-none opacity-0'}`}
-              aria-hidden={slide !== 'intro'}
-            >
-              <Button type="button" variant="outline" onClick={() => setSlide('mcp')}>
-                {t('preferences.dsh.setup.previous')}
-              </Button>
-              <Button type="button" onClick={() => setSlide('download')}>
-                {t('preferences.dsh.setup.next')}
-              </Button>
-            </div>
-            <div
-              className={`absolute inset-y-0 right-0 flex items-center gap-2 transition-opacity duration-200 ${slide === 'download' ? 'opacity-100' : 'pointer-events-none opacity-0'}`}
-              aria-hidden={slide !== 'download'}
-            >
-              <Button type="button" variant="outline" onClick={() => setSlide('intro')}>
-                {t('preferences.dsh.setup.previous')}
-              </Button>
-              <Button type="button" onClick={() => void handleInstall()} disabled={busy}>
-                {busy && <Loader2 className="h-4 w-4 animate-spin" />}
-                {busy ? t(progress?.phase === 'installing' ? 'preferences.dsh.setup.installing' : 'preferences.dsh.setup.downloading') : t('preferences.dsh.setup.install')}
-              </Button>
-              {canCancel && (
-                <Button type="button" variant="outline" onClick={() => void handleCancel()}>
-                  {t('preferences.dsh.setup.cancel')}
-                </Button>
-              )}
-            </div>
-          </div>
-        </div>
-    </FloatingPrompt>
-  );
-}
diff --git a/app/flowix-web/features/preferences/components/settings-tab-group.tsx b/app/flowix-web/features/preferences/components/settings-tab-group.tsx
new file mode 100644
index 000000000..02a4feb51
--- /dev/null
+++ b/app/flowix-web/features/preferences/components/settings-tab-group.tsx
@@ -0,0 +1,103 @@
+'use client';
+
+import { useId, useRef, type KeyboardEvent, type ReactNode } from 'react';
+import { cn } from '@/lib/utils';
+
+export interface SettingsTabItem {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+}
+
+interface SettingsTabGroupProps {
+  tabs: readonly SettingsTabItem[];
+  activeTab: string;
+  onActiveTabChange: (tab: string) => void;
+  ariaLabel: string;
+  orientation?: 'horizontal' | 'vertical';
+  listClassName?: string;
+  tabClassName?: string;
+  activeTabClassName?: string;
+  inactiveTabClassName?: string;
+  children: ReactNode;
+}
+
+/** Accessible single-select tabs with automatic activation and arrow-key navigation. */
+export function SettingsTabGroup({
+  tabs,
+  activeTab,
+  onActiveTabChange,
+  ariaLabel,
+  orientation = 'horizontal',
+  listClassName,
+  tabClassName,
+  activeTabClassName,
+  inactiveTabClassName,
+  children,
+}: SettingsTabGroupProps) {
+  const generatedId = useId().replace(/:/g, '');
+  const tabRefs = useRef<Record<string, HTMLButtonElement | null>>({});
+  const selectedIndex = Math.max(0, tabs.findIndex((tab) => tab.id === activeTab));
+  const selected = tabs[selectedIndex];
+  if (!selected) return null;
+
+  const tabElementId = (id: string) => `${generatedId}-tab-${id}`;
+  const panelId = `${generatedId}-panel`;
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    let nextIndex: number | null = null;
+    if (event.key === 'Home') nextIndex = 0;
+    if (event.key === 'End') nextIndex = tabs.length - 1;
+    if (orientation === 'horizontal' && event.key === 'ArrowRight') nextIndex = (index + 1) % tabs.length;
+    if (orientation === 'horizontal' && event.key === 'ArrowLeft') nextIndex = (index - 1 + tabs.length) % tabs.length;
+    if (orientation === 'vertical' && event.key === 'ArrowDown') nextIndex = (index + 1) % tabs.length;
+    if (orientation === 'vertical' && event.key === 'ArrowUp') nextIndex = (index - 1 + tabs.length) % tabs.length;
+    if (nextIndex === null) return;
+    event.preventDefault();
+    const next = tabs[nextIndex];
+    onActiveTabChange(next.id);
+    tabRefs.current[next.id]?.focus();
+  };
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div
+        role="tablist"
+        aria-label={ariaLabel}
+        aria-orientation={orientation}
+        className={listClassName}
+      >
+        {tabs.map((tab, index) => {
+          const isSelected = tab.id === selected.id;
+          return (
+            <button
+              key={tab.id}
+              ref={(element) => { tabRefs.current[tab.id] = element; }}
+              id={tabElementId(tab.id)}
+              type="button"
+              role="tab"
+              aria-selected={isSelected}
+              aria-controls={panelId}
+              tabIndex={isSelected ? 0 : -1}
+              className={cn(tabClassName, isSelected ? activeTabClassName : inactiveTabClassName)}
+              onClick={() => onActiveTabChange(tab.id)}
+              onKeyDown={(event) => onKeyDown(event, index)}
+            >
+              {tab.icon}
+              {tab.label}
+            </button>
+          );
+        })}
+      </div>
+      <div
+        id={panelId}
+        role="tabpanel"
+        aria-labelledby={tabElementId(selected.id)}
+        tabIndex={0}
+        className="flex min-h-0 flex-1 flex-col"
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/preferences/hooks/use-apply-font-settings.ts b/app/flowix-web/features/preferences/hooks/use-apply-font-settings.ts
index 2bab63f34..e25685098 100644
--- a/app/flowix-web/features/preferences/hooks/use-apply-font-settings.ts
+++ b/app/flowix-web/features/preferences/hooks/use-apply-font-settings.ts
@@ -19,10 +19,10 @@ import {
  * 不会泄漏到 MemoList、shadcn 按钮等其它 UI 文本。
  *
  * 与之配套的变量定义在 css/index.css :
- *   --app-font-family
- *   --app-font-size
- *   --app-line-height
- *   --app-document-width
+ *   --editor-font-family
+ *   --editor-font-size
+ *   --editor-line-height
+ *   --editor-document-width
  *
  * 调用方: app.tsx (主窗口 + 偏好设置窗口都会挂载, 因此跨窗口都会立即响应)。
  */
@@ -43,17 +43,17 @@ export function useApplyFontSettings(format: FormatConfig | undefined) {
       // Emoji must be considered before platform emoji fonts even when a user
       // selects a custom document font. This face only covers emoji codepoints,
       // so placing it first leaves ordinary text to the selected font stack.
-      root.style.setProperty('--app-font-family', `'Flowix Small Emoji', ${format.fontFamily}`);
+      root.style.setProperty('--editor-font-family', `'Flowix Small Emoji', ${format.fontFamily}`);
     }
     if (typeof format.fontSize === 'number' && !Number.isNaN(format.fontSize)) {
-      root.style.setProperty('--app-font-size', `${format.fontSize}px`);
+      root.style.setProperty('--editor-font-size', `${format.fontSize}px`);
     }
     if (typeof format.lineHeight === 'number' && !Number.isNaN(format.lineHeight)) {
-      root.style.setProperty('--app-line-height', String(format.lineHeight));
+      root.style.setProperty('--editor-line-height', String(format.lineHeight));
     }
     if (typeof format.documentWidth === 'number' && !Number.isNaN(format.documentWidth)) {
       root.style.setProperty(
-        '--app-document-width',
+        '--editor-document-width',
         format.documentWidth > DOCUMENT_WIDTH_FULL_THRESHOLD ? 'none' : `${format.documentWidth}px`,
       );
     }
diff --git a/app/flowix-web/features/preferences/hooks/use-cloud-account-state.test.tsx b/app/flowix-web/features/preferences/hooks/use-cloud-account-state.test.tsx
index 056fb86dc..6383b8e21 100644
--- a/app/flowix-web/features/preferences/hooks/use-cloud-account-state.test.tsx
+++ b/app/flowix-web/features/preferences/hooks/use-cloud-account-state.test.tsx
@@ -102,7 +102,9 @@ it('shows membership failures and allows a successful retry', async () => {
   await act(async () => root.render(<Harness />));
   expect(current.membershipError).toBe('offline');
   expect(current.membershipLoading).toBe(false);
-  await act(async () => current.refreshMembership());
+  let result: string | undefined;
+  await act(async () => { result = await current.refreshMembership(); });
+  expect(result).toBe('refreshed');
   expect(current.membershipError).toBeNull();
   expect(mocks.refreshMembership).toHaveBeenCalledTimes(2);
 });
@@ -143,3 +145,35 @@ it('clears the focus throttle after logout so the next session reloads membershi
   await act(async () => mocks.receive!({ ...snapshot(3), authenticated: true, authStatus: 'authenticated', account: { user: { id: 'user-1' } } } as CloudState));
   expect(mocks.refreshMembership).toHaveBeenCalledTimes(2);
 });
+
+it('returns failure to callers and success after retry without an unhandled rejection', async () => {
+  mocks.getState.mockResolvedValue({ ...snapshot(1), authenticated: true, authStatus: 'authenticated' });
+  await act(async () => root.render(<Harness />));
+  mocks.refreshMembership.mockRejectedValueOnce(new Error('offline'));
+  let result: string | undefined;
+  await act(async () => { result = await current.refreshMembership(); });
+  expect(result).toBe('failed');
+  expect(current.membershipError).toBe('offline');
+  await act(async () => { result = await current.refreshMembership(); });
+  expect(result).toBe('refreshed');
+  expect(current.membershipError).toBeNull();
+});
+
+it('returns stale to all coalesced callers after the session changes', async () => {
+  mocks.getState.mockResolvedValue({ ...snapshot(1), authenticated: true, authStatus: 'authenticated' });
+  await act(async () => root.render(<Harness />));
+  let finish!: () => void;
+  mocks.refreshMembership.mockReturnValueOnce(new Promise<void>((resolve) => { finish = resolve; }));
+  let first!: ReturnType<typeof current.refreshMembership>;
+  let second!: ReturnType<typeof current.refreshMembership>;
+  await act(async () => {
+    first = current.refreshMembership();
+    second = current.refreshMembership();
+  });
+  await act(async () => mocks.receive!(snapshot(2)));
+  await act(async () => finish());
+  await expect(first).resolves.toBe('stale');
+  await expect(second).resolves.toBe('stale');
+  expect(current.membershipError).toBeNull();
+  expect(current.membershipLoading).toBe(false);
+});
diff --git a/app/flowix-web/features/preferences/hooks/use-cloud-account-state.ts b/app/flowix-web/features/preferences/hooks/use-cloud-account-state.ts
index 9a1da0416..aedd79492 100644
--- a/app/flowix-web/features/preferences/hooks/use-cloud-account-state.ts
+++ b/app/flowix-web/features/preferences/hooks/use-cloud-account-state.ts
@@ -6,12 +6,14 @@ import { cloud, listenToCloudStateChanges, type CloudState } from '@platform/tau
 
 const MEMBERSHIP_FOCUS_REFRESH_INTERVAL_MS = 30_000;
 
+type MembershipRefreshResult = 'refreshed' | 'failed' | 'stale' | 'skipped';
+
 export function useCloudAccountState() {
   const [state, setState] = useState<CloudState | null>(null);
   const [membershipLoading, setMembershipLoading] = useState(false);
   const [membershipError, setMembershipError] = useState<string | null>(null);
   const membershipRequest = useRef(0);
-  const membershipInFlight = useRef<{ userId: string; promise: Promise<void> } | null>(null);
+  const membershipInFlight = useRef<{ userId: string; promise: Promise<MembershipRefreshResult> } | null>(null);
   const lastMembershipRefresh = useRef<{ userId: string; at: number } | null>(null);
   const [loadError, setLoadError] = useState<string | null>(null);
 
@@ -41,28 +43,31 @@ export function useCloudAccountState() {
     return () => { active = false; unlisten(); };
   }, [applyState]);
 
-  const refreshMembership = useCallback(async (force = true) => {
-    if (!state?.authenticated) return;
+  const refreshMembership = useCallback(async (force = true): Promise<MembershipRefreshResult> => {
+    if (!state?.authenticated) return 'skipped';
     const userId = state.account?.user.id ?? '';
     if (membershipInFlight.current?.userId === userId) return membershipInFlight.current.promise;
     const now = Date.now();
     if (!force && lastMembershipRefresh.current?.userId === userId &&
-      now - lastMembershipRefresh.current.at < MEMBERSHIP_FOCUS_REFRESH_INTERVAL_MS) return;
+      now - lastMembershipRefresh.current.at < MEMBERSHIP_FOCUS_REFRESH_INTERVAL_MS) return 'skipped';
     lastMembershipRefresh.current = { userId, at: now };
     const request = ++membershipRequest.current;
     setMembershipLoading(true);
     setMembershipError(null);
-    const promise = (async () => {
+    const promise = (async (): Promise<MembershipRefreshResult> => {
       try {
         await cloud.refreshMembership();
+        return request === membershipRequest.current ? 'refreshed' : 'stale';
       } catch (error) {
-        if (request === membershipRequest.current) setMembershipError(errorMessage(error));
+        if (request !== membershipRequest.current) return 'stale';
+        setMembershipError(errorMessage(error));
+        return 'failed';
       } finally {
         if (request === membershipRequest.current) setMembershipLoading(false);
       }
     })();
     membershipInFlight.current = { userId, promise };
-    try { await promise; }
+    try { return await promise; }
     finally {
       if (membershipInFlight.current?.promise === promise) membershipInFlight.current = null;
     }
diff --git a/app/flowix-web/features/preferences/hooks/use-dsh-runtime-installer.ts b/app/flowix-web/features/preferences/hooks/use-dsh-runtime-installer.ts
deleted file mode 100644
index 907f49e55..000000000
--- a/app/flowix-web/features/preferences/hooks/use-dsh-runtime-installer.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { subscribe } from '@platform/tauri/event-bus';
-import {
-  dshIntegration,
-  type DshDownloadProgress,
-  type DshIntegrationStatus,
-} from '@platform/tauri/client';
-
-const DSH_DOWNLOAD_PROGRESS_EVENT = 'dsh-download-progress';
-
-function isActiveDownload(progress: DshDownloadProgress | null): boolean {
-  return progress?.phase === 'checking'
-    || progress?.phase === 'downloading'
-    || progress?.phase === 'downloaded'
-    || progress?.phase === 'installing';
-}
-
-/** Shared installation state for the DSH setup and Runtime settings views. */
-export function useDshRuntimeInstaller(initialStatus?: DshIntegrationStatus | null) {
-  const [status, setStatus] = useState<DshIntegrationStatus | null>(initialStatus ?? null);
-  const [busy, setBusy] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [progress, setProgress] = useState<DshDownloadProgress | null>(null);
-  const cancelRequestedRef = useRef(false);
-
-  const handleProgress = useCallback((next: DshDownloadProgress) => {
-    setProgress(isActiveDownload(next) ? next : null);
-    setBusy(isActiveDownload(next));
-  }, []);
-
-  const refresh = useCallback(async () => {
-    try {
-      const next = await dshIntegration.status();
-      setStatus(next);
-      setError(null);
-      return next;
-    } catch (value) {
-      const message = value instanceof Error ? value.message : String(value);
-      setError(message);
-      throw value;
-    }
-  }, []);
-
-  useEffect(() => {
-    const unsubscribe = subscribe<DshDownloadProgress>(DSH_DOWNLOAD_PROGRESS_EVENT, handleProgress);
-    void refresh().catch(() => {
-      // The hook exposes the error to the view; no unhandled promise is needed.
-    });
-    void dshIntegration.downloadStatus()
-      .then((next) => {
-        if (next) handleProgress(next);
-      })
-      .catch(() => {
-        // The active download remains observable through native events.
-      });
-    return unsubscribe;
-  }, [handleProgress, refresh]);
-
-  const install = useCallback(async () => {
-    cancelRequestedRef.current = false;
-    setBusy(true);
-    setError(null);
-    setProgress({
-      phase: 'checking',
-      downloadedBytes: 0,
-      totalBytes: null,
-      percent: null,
-      resumed: false,
-    });
-    try {
-      const next = await dshIntegration.ensureRuntime();
-      setStatus(next);
-      return next;
-    } catch (value) {
-      const message = value instanceof Error ? value.message : String(value);
-      setError(cancelRequestedRef.current ? null : message);
-      return null;
-    } finally {
-      setBusy(false);
-      setProgress(null);
-    }
-  }, []);
-
-  const cancel = useCallback(async () => {
-    cancelRequestedRef.current = true;
-    try {
-      await dshIntegration.cancelUpdate();
-      return true;
-    } catch (value) {
-      cancelRequestedRef.current = false;
-      setError(value instanceof Error ? value.message : String(value));
-      return false;
-    }
-  }, []);
-
-  /** Remove the managed runtime tree. Returns the post-uninstall status
-   * (installed: false), or null when the backend rejected the uninstall. */
-  const uninstall = useCallback(async () => {
-    setBusy(true);
-    setError(null);
-    try {
-      const next = await dshIntegration.uninstallRuntime();
-      setStatus(next);
-      return next;
-    } catch (value) {
-      setError(value instanceof Error ? value.message : String(value));
-      return null;
-    } finally {
-      setBusy(false);
-    }
-  }, []);
-
-  return { status, busy, error, progress, refresh, install, cancel, uninstall };
-}
diff --git a/app/flowix-web/features/preferences/index.ts b/app/flowix-web/features/preferences/index.ts
index f7b677443..9dc0011d7 100644
--- a/app/flowix-web/features/preferences/index.ts
+++ b/app/flowix-web/features/preferences/index.ts
@@ -4,5 +4,3 @@ export { PreferencesTitlebarWin } from '@features/preferences/preferences-titleb
 export * from '@features/preferences/sections';
 export * from '@features/preferences/hooks';
 export * from '@features/preferences/store';
-export * from '@features/preferences/public/system-api';
-export * from '@features/preferences/public/dsh-install-prompt';
diff --git a/app/flowix-web/features/preferences/preferences-tab-config.tsx b/app/flowix-web/features/preferences/preferences-tab-config.tsx
index 415ebc6a7..3b848958c 100644
--- a/app/flowix-web/features/preferences/preferences-tab-config.tsx
+++ b/app/flowix-web/features/preferences/preferences-tab-config.tsx
@@ -1,4 +1,6 @@
+import { lazy, type ComponentType, type LazyExoticComponent, type ReactNode } from 'react';
 import {
+  CloudIcon,
   FadersHorizontalIcon,
   KeyboardIcon,
   RulerIcon,
@@ -8,41 +10,97 @@ import {
 } from '@phosphor-icons/react';
 import type { I18nKey } from '@/lib/i18n';
 import mcpPluginIcon from '@/assets/mcp-plugin-settings.svg';
-import type { SettingsTab } from '@features/preferences/sections';
 import { AgentIcon } from '@features/agent/components/agent-icon';
 
-export type PreferencesTabItem = {
-  id: SettingsTab;
+export interface PreferenceTabProps {
+  productInfo?: import('@platform/tauri/client').ProductInfo | null;
+}
+
+export type PreferenceTabComponent = LazyExoticComponent<ComponentType<PreferenceTabProps>>;
+type PreferenceTabLoader = () => Promise<{ default: unknown }>;
+
+function lazyPreferenceTab(load: PreferenceTabLoader) {
+  const createComponent = () => lazy(async () => {
+    const module = await load();
+    return { default: module.default as ComponentType<PreferenceTabProps> };
+  });
+  return { createComponent };
+}
+
+export type PreferencesTabItem<Id extends string = string> = {
+  id: Id;
   labelKey: I18nKey;
-  icon: React.ReactNode;
+  icon: ReactNode;
+  createComponent: () => PreferenceTabComponent;
+  contentWidth: 'normal' | 'wide';
+  experimentalOnly?: boolean;
+  visibleInProductMenu?: boolean;
 };
 
-export type PreferencesTabGroup = {
+export type PreferencesTabGroup<Id extends string = string> = {
   labelKey: I18nKey;
-  tabs: readonly PreferencesTabItem[];
+  tabs: readonly PreferencesTabItem<Id>[];
 };
 
-/** Shared order and icons for the Preferences sidebar and product menu. */
-export const PREFERENCE_TAB_GROUPS: readonly PreferencesTabGroup[] = [
+/**
+ * The preference sidebar, product menu, route normalization and page loader
+ * all derive from these definitions. Dynamic imports keep inactive sections
+ * out of the initial preference-window chunk.
+ */
+export const PREFERENCE_TAB_GROUPS = [
   {
     labelKey: 'preferences.groups.features',
     tabs: [
-      { id: 'general', labelKey: 'preferences.tabs.general', icon: <FadersHorizontalIcon className="w-4 h-4" /> },
-      { id: 'format', labelKey: 'preferences.tabs.format', icon: <TextAUnderlineIcon className="w-4 h-4" /> },
-      { id: 'noteSettings', labelKey: 'preferences.tabs.noteSettings', icon: <RulerIcon className="w-4 h-4" /> },
-      { id: 'shortcuts', labelKey: 'preferences.tabs.shortcuts', icon: <KeyboardIcon className="w-4 h-4" /> },
-      { id: 'cloudSync', labelKey: 'preferences.tabs.cloudSync', icon: <UserIcon className="w-4 h-4" /> },
+      {
+        id: 'general', labelKey: 'preferences.tabs.general',
+        icon: <FadersHorizontalIcon className="w-4 h-4" />, contentWidth: 'normal',
+        ...lazyPreferenceTab(() => import('@features/preferences/tab-pages/general').then((module) => ({ default: module.GeneralPreferencesTab }))),
+      },
+      {
+        id: 'format', labelKey: 'preferences.tabs.format',
+        icon: <TextAUnderlineIcon className="w-4 h-4" />, contentWidth: 'normal',
+        ...lazyPreferenceTab(() => import('@features/preferences/tab-pages/format').then((module) => ({ default: module.FormatPreferencesTab }))),
+      },
+      {
+        id: 'noteSettings', labelKey: 'preferences.tabs.noteSettings',
+        icon: <RulerIcon className="w-4 h-4" />, contentWidth: 'normal',
+        ...lazyPreferenceTab(() => import('@features/preferences/sections/note-settings').then((module) => ({ default: module.NoteSettingsSection }))),
+      },
+      {
+        id: 'shortcuts', labelKey: 'preferences.tabs.shortcuts',
+        icon: <KeyboardIcon className="w-4 h-4" />, contentWidth: 'normal',
+        ...lazyPreferenceTab(() => import('@features/preferences/sections/shortcuts').then((module) => ({ default: module.ShortcutsSection }))),
+      },
+      {
+        id: 'cloudSync', labelKey: 'preferences.tabs.cloudSync',
+        icon: <UserIcon className="w-4 h-4" />, contentWidth: 'normal',
+        experimentalOnly: true, visibleInProductMenu: false,
+        ...lazyPreferenceTab(() => import('@features/preferences/sections/cloud-sync').then((module) => ({ default: module.CloudSyncSection }))),
+      },
     ],
   },
   {
     labelKey: 'preferences.groups.ai',
     tabs: [
-      { id: 'pi', labelKey: 'preferences.tabs.pi', icon: <AgentIcon typeKey="pi" alt="" className="w-4 h-4 object-contain" /> },
-      { id: 'dsh', labelKey: 'preferences.tabs.dsh', icon: <AgentIcon typeKey="deepseek-harness" alt="" className="w-4 h-4 object-contain" /> },
-      { id: 'aiAgent', labelKey: 'preferences.tabs.aiAgent', icon: <StarFourIcon className="w-4 h-4" weight="regular" /> },
       {
-        id: 'mcp',
-        labelKey: 'preferences.tabs.mcp',
+        id: 'pi', labelKey: 'preferences.tabs.pi',
+        icon: <AgentIcon typeKey="pi" alt="" className="w-4 h-4 object-contain" />, contentWidth: 'wide',
+        ...lazyPreferenceTab(() => import('@features/preferences/sections/pi').then((module) => ({ default: module.PiSettingsSection }))),
+      },
+      {
+        id: 'dsh', labelKey: 'preferences.tabs.dsh',
+        icon: <AgentIcon typeKey="dsh" alt="" className="w-4 h-4 object-contain" />, contentWidth: 'wide',
+        visibleInProductMenu: false,
+        ...lazyPreferenceTab(() => import('@features/preferences/sections/dsh').then((module) => ({ default: module.DshSettingsSection }))),
+      },
+      {
+        id: 'aiAgent', labelKey: 'preferences.tabs.aiAgent',
+        icon: <StarFourIcon className="w-4 h-4" weight="regular" />, contentWidth: 'normal',
+        visibleInProductMenu: false,
+        ...lazyPreferenceTab(() => import('@features/preferences/sections/agents').then((module) => ({ default: module.AgentsSection }))),
+      },
+      {
+        id: 'mcp', labelKey: 'preferences.tabs.mcp',
         icon: (
           <span
             aria-hidden="true"
@@ -53,11 +111,41 @@ export const PREFERENCE_TAB_GROUPS: readonly PreferencesTabGroup[] = [
             }}
           />
         ),
+        contentWidth: 'normal',
+        ...lazyPreferenceTab(() => import('@features/preferences/tab-pages/mcp').then((module) => ({ default: module.McpPreferencesTab }))),
       },
     ],
   },
+] as const satisfies readonly PreferencesTabGroup[];
+
+/** Visible only in the dedicated Preferences sidebar for development builds. */
+export const DEVELOPMENT_PREFERENCE_TAB_GROUP = {
+  labelKey: 'preferences.groups.development',
+  tabs: [
+    {
+      id: 'environmentConfig',
+      labelKey: 'preferences.tabs.environmentConfig',
+      icon: <CloudIcon className="w-4 h-4" />,
+      contentWidth: 'normal',
+      visibleInProductMenu: false,
+      ...lazyPreferenceTab(() => import('@features/preferences/tab-pages/environment-config').then((module) => ({ default: module.EnvironmentConfigPreferencesTab }))),
+    },
+  ],
+} as const satisfies PreferencesTabGroup;
+
+export type ActiveSettingsTab =
+  | (typeof PREFERENCE_TAB_GROUPS)[number]['tabs'][number]['id']
+  | (typeof DEVELOPMENT_PREFERENCE_TAB_GROUP.tabs)[number]['id'];
+
+export const PREFERENCE_TABS = PREFERENCE_TAB_GROUPS.flatMap(
+  (group) => [...group.tabs],
+);
+
+export const ALL_PREFERENCE_TABS = [
+  ...PREFERENCE_TABS,
+  ...DEVELOPMENT_PREFERENCE_TAB_GROUP.tabs,
 ];
 
-export const PREFERENCE_TABS: readonly PreferencesTabItem[] = PREFERENCE_TAB_GROUPS.flatMap(
-  (group) => group.tabs,
+export const PREFERENCE_TAB_BY_ID: ReadonlyMap<ActiveSettingsTab, PreferencesTabItem<ActiveSettingsTab>> = new Map(
+  ALL_PREFERENCE_TABS.map((tab) => [tab.id, tab] as const),
 );
diff --git a/app/flowix-web/features/preferences/preferences-view.tsx b/app/flowix-web/features/preferences/preferences-view.tsx
index de6864f87..2a75cdf32 100644
--- a/app/flowix-web/features/preferences/preferences-view.tsx
+++ b/app/flowix-web/features/preferences/preferences-view.tsx
@@ -1,100 +1,57 @@
 'use client';
 
-import { lazy, Suspense, useState, useEffect, useMemo } from 'react';
+import { Suspense, useState, useEffect, useMemo } from 'react';
 import { Loader2 } from 'lucide-react';
 import {
-	useUserSettings,
-	useUserSettingsActions,
-} from '@features/preferences/hooks/use-user-settings';
-import {
-	GeneralSection,
-	ThemeSection,
-	NoteSettingsSection,
-	AgentsSection,
-	DshSettingsSection,
-	PiSettingsSection,
-	ShortcutsSection,
-	CliSection,
-	McpSection,
-	ConnectionsSection,
-	CloudSyncSection,
-	HistorySection,
-	PluginsSection,
-	SectionHeader,
-	type SettingsTab,
-} from '@features/preferences/sections';
-import { PREFERENCE_TAB_GROUPS, PREFERENCE_TABS } from '@features/preferences/preferences-tab-config';
+	DEVELOPMENT_PREFERENCE_TAB_GROUP,
+	PREFERENCE_TAB_BY_ID,
+	PREFERENCE_TAB_GROUPS,
+	type ActiveSettingsTab,
+	type PreferencesTabGroup,
+} from '@features/preferences/preferences-tab-config';
 import { cn } from '@/lib/utils';
 import { Button } from '@shared/ui/button';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
+import { ErrorBoundary } from '@shared/error-boundary';
 import { WindowsTitlebarControls } from '@shared/window-titlebar-controls';
 import { PreferencesTitlebarMac } from '@features/preferences/preferences-titlebar-mac';
 import { PreferencesTitlebarWin } from '@features/preferences/preferences-titlebar-win';
 import { useI18n } from '@/lib/i18n';
 import { getCurrentWindow } from '@platform/tauri/window';
 import { useExperimentalMode } from '@platform/tauri/use-experimental-mode';
-import { useAgentRuntimeStore } from '@features/agent/store/agent-runtime-store';
+import { product, type ProductInfo } from '@platform/tauri/client';
 
 function isWindowsPlatform(): boolean {
 	return /Windows/i.test(navigator.userAgent) || /Win/i.test(navigator.platform);
 }
 
-const TABS = PREFERENCE_TABS;
-const FormatSection = lazy(() =>
-	import('@features/preferences/sections/format').then((module) => ({ default: module.FormatSection })),
-);
-
-function normalizeInitialTab(tab: string): SettingsTab | null {
-	if (tab === 'templates' || tab === 'documentProperties' || tab === 'fileDisplayRules') return 'noteSettings';
-	if (tab === 'theme') return 'general';
-	if (tab === 'cli') return 'mcp';
-	// 老 URL: `agent` / `modelConfig` 都是模型配置, 落到合并后的 `aiAgent`。
-	if (tab === 'agent' || tab === 'modelConfig' || tab === 'agents') return 'aiAgent';
-	// 老 URL: 图片 / 视频生成合并到 `tools`。
-	if (tab === 'imageGeneration' || tab === 'videoGeneration') return 'tools';
-	return TABS.some(item => item.id === tab) ? tab as SettingsTab : null;
-}
-
-function PlaceholderSection({ title, emptyText }: { title: string; emptyText: string }) {
-	return (
-		<div className="space-y-6">
-			<SectionHeader title={title} />
-			<p className="text-sm text-[var(--muted-foreground)]">{emptyText}</p>
-		</div>
-	);
-}
-
-function GeneralSettingsSection() {
-	const language = useUserSettings((settings) => settings.language);
-	const { updateSettings } = useUserSettingsActions();
-	return <GeneralSection language={language} updateSettings={updateSettings} afterGeneral={<ThemeSettingsSection />} />;
-}
-
-function FormatSettingsSection() {
-	const { t } = useI18n();
-	const format = useUserSettings((settings) => settings.format);
-	const { updateSettings } = useUserSettingsActions();
-	return (
-		<Suspense
-			fallback={(
-				<div className="space-y-6" aria-busy="true">
-					<SectionHeader title={t('preferences.format.title')} />
-					<div className="flex h-48 items-center justify-center" role="status" aria-label={t('preferences.general.loading')}>
-						<Loader2 className="size-6 animate-spin text-[var(--muted-foreground)]" />
-						<span className="sr-only">{t('preferences.general.loading')}</span>
-					</div>
-				</div>
-			)}
-		>
-			<FormatSection settings={format} updateSettings={updateSettings} />
-		</Suspense>
-	);
+const LEGACY_TAB_REDIRECTS: Readonly<Record<string, ActiveSettingsTab>> = {
+	templates: 'noteSettings',
+	documentProperties: 'noteSettings',
+	fileDisplayRules: 'noteSettings',
+	theme: 'general',
+	cli: 'mcp',
+	agent: 'aiAgent',
+	modelConfig: 'aiAgent',
+	agents: 'aiAgent',
+};
+
+function normalizeInitialTab(tab: string): ActiveSettingsTab | null {
+	const redirected = LEGACY_TAB_REDIRECTS[tab];
+	if (redirected) return redirected;
+	return PREFERENCE_TAB_BY_ID.has(tab as ActiveSettingsTab) ? tab as ActiveSettingsTab : null;
 }
 
-function ThemeSettingsSection() {
-	const theme = useUserSettings((settings) => settings.theme);
-	const { updateSettings } = useUserSettingsActions();
-	return <ThemeSection settings={{ theme }} updateSettings={updateSettings} />;
+function getVisibleTabGroups({ isDevBuild, experimental }: { isDevBuild: boolean; experimental: boolean }) {
+	const groups: readonly PreferencesTabGroup<ActiveSettingsTab>[] = isDevBuild
+		? [...PREFERENCE_TAB_GROUPS, DEVELOPMENT_PREFERENCE_TAB_GROUP]
+		: PREFERENCE_TAB_GROUPS;
+	return groups
+		.map((group) => ({
+			...group,
+			tabs: group.tabs.filter((tab) => experimental || !tab.experimentalOnly),
+		}))
+		.filter((group) => group.tabs.length > 0);
 }
 
 interface PreferencesViewProps {
@@ -104,41 +61,44 @@ interface PreferencesViewProps {
 export function PreferencesView({ initialTab }: PreferencesViewProps) {
 	const { t } = useI18n();
 	const experimental = useExperimentalMode();
-	const refreshRuntimeStatus = useAgentRuntimeStore((state) => state.refreshIfStale);
-	const [activeTab, setActiveTab] = useState<SettingsTab>('general');
+	const [activeTab, setActiveTab] = useState<ActiveSettingsTab>('general');
+	const [tabRetryVersion, setTabRetryVersion] = useState(0);
+	const [productInfo, setProductInfo] = useState<ProductInfo | null>(null);
 	const title = t('preferences.title');
 	const initialTabName = initialTab?.split('?')[0];
-	const autoUpdateDsh = initialTab?.includes('autoUpdate=1') ?? false;
 
 	useEffect(() => {
-		void refreshRuntimeStatus();
-	}, [refreshRuntimeStatus]);
+		product.getInfo().then(setProductInfo).catch(() => setProductInfo(null));
+	}, []);
 
 	const visibleTabGroups = useMemo(
-		() => PREFERENCE_TAB_GROUPS.map((group) => ({
-			...group,
-			tabs: experimental
-				? group.tabs
-				: group.tabs.filter((tab) => !['cloudSync', 'connections', 'tools', 'history'].includes(tab.id)),
-		})),
-		[experimental],
+		() => getVisibleTabGroups({ isDevBuild: productInfo?.isDevBuild ?? false, experimental }),
+		[experimental, productInfo?.isDevBuild],
+	);
+	const visibleTabIds = useMemo(
+		() => new Set(visibleTabGroups.flatMap((group) => group.tabs.map((tab) => tab.id))),
+		[visibleTabGroups],
+	);
+	const activeTabDefinition = PREFERENCE_TAB_BY_ID.get(activeTab);
+	const ActiveTabComponent = useMemo(
+		() => activeTabDefinition?.createComponent() ?? null,
+		[activeTabDefinition, tabRetryVersion],
 	);
-	const tabsWithRuntimeAvailability = visibleTabGroups;
 
 	useEffect(() => {
 		if (initialTab) {
 			const normalizedTab = normalizeInitialTab(initialTabName ?? initialTab);
-			if (normalizedTab && (normalizedTab !== 'cloudSync' || experimental)) {
+				if (normalizedTab && visibleTabIds.has(normalizedTab)) {
 				setActiveTab(normalizedTab);
 			}
 		}
-	}, [experimental, initialTab]);
+	}, [experimental, initialTab, initialTabName, visibleTabIds]);
 
 	useEffect(() => {
-		if (!experimental && ['cloudSync', 'connections', 'tools', 'history'].includes(activeTab)) {
+		if (!visibleTabIds.has(activeTab)) {
 			setActiveTab('general');
 		}
-	}, [activeTab, experimental]);
+	}, [activeTab, visibleTabIds]);
 
 	useEffect(() => {
 		document.title = title;
@@ -157,8 +117,8 @@ export function PreferencesView({ initialTab }: PreferencesViewProps) {
 					className="flex h-full w-[204px] min-h-0 shrink-0 border-r border-solid border-[var(--divider)] bg-[var(--card)]"
 					scrollerClassName="h-full min-h-0 px-2 pt-5 pb-2"
 				>
-					<div className="flex min-h-full flex-col gap-4">
-						{tabsWithRuntimeAvailability.map((group) => (
+					<nav aria-label={title} className="flex min-h-full flex-col gap-4">
+						{visibleTabGroups.map((group) => (
 							<div key={group.labelKey} className="space-y-1">
 								<div className="px-2 pb-1 text-xs font-medium text-[var(--muted-foreground)]">
 									{t(group.labelKey)}
@@ -171,12 +131,13 @@ export function PreferencesView({ initialTab }: PreferencesViewProps) {
 											// 同色, 在 light/dark 主题下都保持视觉一致。
 											variant="ghost"
 											size="sm"
+											aria-current={activeTab === tab.id ? 'page' : undefined}
 											className={cn(
 												'w-full justify-start gap-1.5 py-4 rounded-lg',
 												activeTab === tab.id &&
 													'bg-muted hover:bg-muted dark:bg-[color-mix(in_oklch,var(--muted)_50%,transparent)] dark:hover:bg-[color-mix(in_oklch,var(--muted)_50%,transparent)]'
 											)}
-											onClick={() => setActiveTab(tab.id)}
+												onClick={() => setActiveTab(tab.id)}
 										>
 											{tab.icon}
 											<span className="text-sm font-normal">{t(tab.labelKey)}</span>
@@ -185,51 +146,45 @@ export function PreferencesView({ initialTab }: PreferencesViewProps) {
 								</div>
 							</div>
 						))}
-					</div>
+					</nav>
 				</OverlayScrollbar>
 				{/* Right content */}
-				<div className="h-full min-w-0 min-h-0 flex-1">
-					<OverlayScrollbar className="h-full w-full min-h-0" scrollerClassName="h-full min-h-0">
-						<div className="min-h-full">
-							<div className="flex justify-center p-6 pb-0">
-								{/* DSH 页信息密度更高(模型/插件/预设卡片), 放宽到 760px, 其余 tab 保持 500px。 */}
-								<div className={cn('w-full', ['dsh', 'codex', 'pi'].includes(activeTab) ? 'max-w-[760px]' : 'max-w-[500px]')}>
-									{activeTab === 'general' && <GeneralSettingsSection />}
-									{activeTab === 'format' && <FormatSettingsSection />}
-									{activeTab === 'noteSettings' && <NoteSettingsSection />}
-									{activeTab === 'aiAgent' && <AgentsSection />}
-									{activeTab === 'dsh' && <DshSettingsSection autoUpdate={autoUpdateDsh} />}
-									{activeTab === 'pi' && <PiSettingsSection />}
-									{activeTab === 'shortcuts' && <ShortcutsSection />}
-									{activeTab === 'mcp' && (
-										<div className="space-y-8">
-											<McpSection />
-											<CliSection />
-										</div>
-									)}
-									{activeTab === 'connections' && <ConnectionsSection />}
-									{experimental && activeTab === 'cloudSync' && <CloudSyncSection />}
-									{activeTab === 'tools' && (
-										<div className="space-y-8">
-											<PlaceholderSection
-												title={t('preferences.imageGeneration.title')}
-												emptyText={t('preferences.emptySettings')}
-											/>
-											<PlaceholderSection
-												title={t('preferences.videoGeneration.title')}
-												emptyText={t('preferences.emptySettings')}
-											/>
-										</div>
+				<main aria-label={title} className="h-full min-w-0 min-h-0 flex-1">
+					<OverlayScrollbar className="h-full w-full min-h-0" scrollerClassName="flex h-full min-h-0 flex-col">
+						<div className="flex min-h-full flex-1 flex-col">
+							<div className="flex flex-1 justify-center p-6 pb-0">
+								<div className={cn('flex w-full flex-1 flex-col', activeTabDefinition?.contentWidth === 'wide' ? 'max-w-[760px]' : 'max-w-[500px]')}>
+									{activeTabDefinition && (
+										<ErrorBoundary
+											key={`${activeTab}:${tabRetryVersion}`}
+											fallback={(
+												<div className="flex flex-wrap items-center justify-between gap-3 rounded-md bg-[color-mix(in_oklch,var(--destructive)_10%,transparent)] p-3" role="alert">
+													<p className="text-sm text-[var(--destructive)]">{t('preferences.sectionLoadFailed')}</p>
+									<Button type="button" size="sm" variant="outline" className="rounded-lg" onClick={() => setTabRetryVersion((version) => version + 1)}>
+														{t('error.retry')}
+													</Button>
+												</div>
+											)}
+										>
+											<Suspense fallback={(
+												<div className="flex flex-1 items-center justify-center" role="status" aria-label={t('preferences.general.loading')}>
+													<Loader2 className="size-6 flowix-spin text-[var(--muted-foreground)]" />
+													<span className="sr-only">{t('preferences.general.loading')}</span>
+												</div>
+											)}>
+												{ActiveTabComponent && <ActiveTabComponent
+													productInfo={productInfo}
+												/>}
+											</Suspense>
+										</ErrorBoundary>
 									)}
-									{activeTab === 'history' && <HistorySection />}
-									{activeTab === 'plugins' && <PluginsSection />}
-								</div>
+									</div>
 							</div>
+							{/* 独立尾部块确保 WebKit 将留白计入 scrollHeight。 */}
+							<div aria-hidden="true" className="h-10 shrink-0" />
 						</div>
-						{/* 独立尾部块确保 WebKit 将留白计入 scrollHeight。 */}
-						<div aria-hidden="true" style={{ height: '2.5rem' }} />
 					</OverlayScrollbar>
-				</div>
+				</main>
 			</div>
 		</div>
 	);
diff --git a/app/flowix-web/features/preferences/public/dsh-install-prompt.ts b/app/flowix-web/features/preferences/public/dsh-install-prompt.ts
deleted file mode 100644
index daa75209c..000000000
--- a/app/flowix-web/features/preferences/public/dsh-install-prompt.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { DshInstallPrompt } from '@features/preferences/components/dsh-install-prompt';
-
diff --git a/app/flowix-web/features/preferences/public/runtime-api.ts b/app/flowix-web/features/preferences/public/runtime-api.ts
index a11b9ec9b..916813b5a 100644
--- a/app/flowix-web/features/preferences/public/runtime-api.ts
+++ b/app/flowix-web/features/preferences/public/runtime-api.ts
@@ -39,6 +39,10 @@ export function useMemoListViewPreference() {
   return useUserSettingsStore((state) => state.settings.memoListView);
 }
 
+export function getMemoListViewPreference() {
+  return useUserSettingsStore.getState().settings.memoListView;
+}
+
 export function setMemoListViewPreference(
   view: UserSettings['memoListView'],
 ): Promise<void> {
diff --git a/app/flowix-web/features/preferences/public/shutdown-api.ts b/app/flowix-web/features/preferences/public/shutdown-api.ts
new file mode 100644
index 000000000..f45d9bd50
--- /dev/null
+++ b/app/flowix-web/features/preferences/public/shutdown-api.ts
@@ -0,0 +1,5 @@
+import { useUserSettingsStore } from '../store/user-settings-store';
+
+export function flushPreferencesForShutdown(): Promise<void> {
+  return useUserSettingsStore.getState().flushPending();
+}
diff --git a/app/flowix-web/features/preferences/public/system-api.ts b/app/flowix-web/features/preferences/public/system-api.ts
deleted file mode 100644
index 46dd88cd7..000000000
--- a/app/flowix-web/features/preferences/public/system-api.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export { useDshRuntimeInstaller } from '@features/preferences/hooks/use-dsh-runtime-installer';
-export type DshRuntimeInstallerState = ReturnType<
-  typeof import('@features/preferences/hooks/use-dsh-runtime-installer').useDshRuntimeInstaller
->;
-
diff --git a/app/flowix-web/features/preferences/sections/agent.tsx b/app/flowix-web/features/preferences/sections/agent.tsx
index a9dda821a..468174ff7 100644
--- a/app/flowix-web/features/preferences/sections/agent.tsx
+++ b/app/flowix-web/features/preferences/sections/agent.tsx
@@ -24,7 +24,7 @@ import { Loader2, Plus, Trash2, Pencil } from 'lucide-react';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
 import { cn } from '@/lib/utils';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
+import { useAgentDataStore } from '@features/agent/store/agent-data-store';
 import { catalogProviderForConfiguredModel } from './model-provider';
 import { useRegionStore } from '@/lib/i18n';
 import iconMinimax from '@/assets/icon-minimax.svg';
@@ -347,7 +347,7 @@ const PROVIDER_ICONS: Record<string, ProviderIconSpec> = {
   Anthropic: { icon: iconClaude },
   Gemini: { icon: iconGemini },
   Ollama: { icon: iconOllama },
-  DeepSeek: { icon: iconDeepseek, agentTypeKey: 'deepseek-harness' },
+  DeepSeek: { icon: iconDeepseek, agentTypeKey: 'dsh' },
   OpenRouter: { icon: iconOpenrouter },
   Kimi: { icon: iconKimi },
   Moonshot: { icon: iconKimi },
@@ -430,8 +430,8 @@ export function AgentSection({
 	// Legacy single-route settings keep their regional provider visibility;
 	// DeepSeek Harness's catalog does not apply a regional filter.
 	const isMainland = useRegionStore((s) => s.region === 'mainland');
-  const dshDefaultModel = useAgentAccessStore(
-    (state) => state.config.defaults?.runtime?.['deepseek-harness']?.model,
+  const dshDefaultModel = useAgentDataStore(
+    (state) => state.agents.dsh.user.model,
   );
   /** 编辑中的草稿 — 所有 onChange 只更新这里, 不会写盘。 */
   const [localConfig, setLocalConfig] = useState<AgentConfig | null>(null);
@@ -1431,10 +1431,10 @@ export function AgentSection({
         });
       })
     : [];
-  const activeModelId = dshDefaultModel?.key && dshDefaultModel.key !== 'inherit'
-    ? dshDefaultModel.key
+  const activeModelId = dshDefaultModel?.id && dshDefaultModel.id !== 'inherit'
+    ? dshDefaultModel.id
     : modelListConfig.model;
-  const activeProviderId = dshDefaultModel?.key && dshDefaultModel.key !== 'inherit'
+  const activeProviderId = dshDefaultModel?.id && dshDefaultModel.id !== 'inherit'
     ? dshDefaultModel.providerId
     : modelListConfig.providerId;
   // DeepSeek Harness model management is card-driven: the form is opened by
@@ -1457,7 +1457,7 @@ export function AgentSection({
         </Button>
       )}
       <Button type="button" onClick={() => void handleSave()} disabled={isBusy}>
-        {isSaving ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : t('preferences.agent.save')}
+        {isSaving ? <Loader2 className="h-3.5 w-3.5 flowix-spin" /> : t('preferences.agent.save')}
       </Button>
       <Button
         type="button"
@@ -1465,7 +1465,7 @@ export function AgentSection({
         onClick={() => void handleTest()}
         disabled={isBusy}
       >
-        {isTesting ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : t('preferences.agent.test')}
+        {isTesting ? <Loader2 className="h-3.5 w-3.5 flowix-spin" /> : t('preferences.agent.test')}
       </Button>
       <div className="flex items-center gap-1 text-xs" aria-live="polite">
         {isTesting && <span className="text-[var(--muted-foreground)]">{t('preferences.agent.testing')}</span>}
@@ -1477,12 +1477,12 @@ export function AgentSection({
 
   const renderModelConfiguration = () => (
     <div className="space-y-4">
-      {(showCustomProviderForm || showGenericModelConfiguration) && <Field title={t('preferences.agent.provider.title')} className={modelFieldClass}>
+      {(showCustomProviderForm || showGenericModelConfiguration) && <Field title={t('preferences.agent.provider.title')} controlId="ai-provider" className={modelFieldClass}>
         <Select
           value={showCustomProviderForm ? CUSTOM_PROVIDER_VALUE : localConfig.provider}
           onValueChange={updateProvider}
         >
-          <SelectTrigger className={modelFormOnly ? 'h-10 w-full' : 'w-[16rem]'}>
+          <SelectTrigger id="ai-provider" className={modelFormOnly ? 'h-10 w-full' : 'w-[16rem]'}>
             {showCustomProviderForm ? (
               <span className="truncate">{t('preferences.agent.provider.custom')}</span>
             ) : localConfig.provider.trim() ? (
@@ -1530,7 +1530,7 @@ export function AgentSection({
         />
       ) : showGenericModelConfiguration ? (
         <>
-          <Field title={t('preferences.agent.modelId.title')} className={modelFieldClass}>
+          <Field title={t('preferences.agent.modelId.title')} controlId="ai-model-id" className={modelFieldClass}>
             {modelOptions || dynamicModelOptions ? (
               <Select
                 value={localConfig.model}
@@ -1539,6 +1539,7 @@ export function AgentSection({
                 <SelectTrigger asChild>
                   <div className="relative">
                     <Input
+                      id="ai-model-id"
                       value={localConfig.model}
                       onChange={(e) => updateField('model', e.target.value)}
                       placeholder={modelPlaceholder}
@@ -1559,6 +1560,7 @@ export function AgentSection({
               </Select>
             ) : (
               <Input
+                id="ai-model-id"
                 value={localConfig.model}
                 onChange={(e) => updateField('model', e.target.value)}
                 placeholder={modelPlaceholder}
@@ -1580,7 +1582,7 @@ export function AgentSection({
                   onClick={() => void discoverModels()}
                   disabled={modelDiscoveryBusy}
                 >
-                  {modelDiscoveryBusy ? <Loader2 className="mr-1 h-3 w-3 animate-spin" /> : null}
+                  {modelDiscoveryBusy ? <Loader2 className="mr-1 h-3 w-3 flowix-spin" /> : null}
                   {t('preferences.agent.modelId.discover')}
                 </Button>
               )}
@@ -1593,8 +1595,9 @@ export function AgentSection({
           </Field>
 
           {!hideBaseUrlField && (
-            <Field title={t('preferences.agent.baseUrl.title')} className={modelFieldClass}>
+            <Field title={t('preferences.agent.baseUrl.title')} controlId="ai-base-url" className={modelFieldClass}>
               <Input
+                id="ai-base-url"
                 value={localConfig.apiUrl}
                 onChange={(e) => updateField('apiUrl', e.target.value)}
                 placeholder={baseUrlPlaceholder}
@@ -1605,8 +1608,9 @@ export function AgentSection({
             </Field>
           )}
 
-          <Field title={t('preferences.agent.apiKey.title')} description={apiKeyDescription} className={modelFieldClass}>
+          <Field title={t('preferences.agent.apiKey.title')} controlId="ai-api-key" description={apiKeyDescription} className={modelFieldClass}>
             <Input
+              id="ai-api-key"
               type="password"
               value={localConfig.apiKeys[apiKeyBucket] ?? ''}
               onChange={(e) => updateApiKey(e.target.value)}
@@ -1657,12 +1661,12 @@ export function AgentSection({
         )}
 
         {/* 1. 供应商 */}
-        {!modelDirectory && (showCustomProviderForm || showGenericModelConfiguration) && <Field title={t('preferences.agent.provider.title')}>
+        {!modelDirectory && (showCustomProviderForm || showGenericModelConfiguration) && <Field title={t('preferences.agent.provider.title')} controlId="ai-provider">
           <Select
             value={showCustomProviderForm ? CUSTOM_PROVIDER_VALUE : localConfig.provider}
             onValueChange={updateProvider}
           >
-            <SelectTrigger className="w-[16rem]">
+            <SelectTrigger id="ai-provider" className="w-[16rem]">
               {showCustomProviderForm ? (
                 <span className="truncate">{t('preferences.agent.provider.custom')}</span>
               ) : localConfig.provider.trim() ? (
@@ -1710,7 +1714,7 @@ export function AgentSection({
 
         {/* 2. 模型 ID(原"模型"字段,语义改为 API 调用时的模型标识符)
               有目录时支持自由输入，并提供当前供应商的模型列表提示。 */}
-        <Field title={t('preferences.agent.modelId.title')}>
+        <Field title={t('preferences.agent.modelId.title')} controlId="ai-model-id">
           {modelOptions || dynamicModelOptions ? (
             <Select
               value={localConfig.model}
@@ -1719,6 +1723,7 @@ export function AgentSection({
               <SelectTrigger asChild>
                 <div className="relative">
                   <Input
+                    id="ai-model-id"
                     value={localConfig.model}
                     onChange={(e) => updateField('model', e.target.value)}
                     placeholder={modelPlaceholder}
@@ -1736,6 +1741,7 @@ export function AgentSection({
             </Select>
           ) : (
             <Input
+              id="ai-model-id"
               value={localConfig.model}
               onChange={(e) => updateField('model', e.target.value)}
               placeholder={modelPlaceholder}
@@ -1757,7 +1763,7 @@ export function AgentSection({
                 onClick={() => void discoverModels()}
                 disabled={modelDiscoveryBusy}
               >
-                {modelDiscoveryBusy ? <Loader2 className="mr-1 h-3 w-3 animate-spin" /> : null}
+                {modelDiscoveryBusy ? <Loader2 className="mr-1 h-3 w-3 flowix-spin" /> : null}
                 {t('preferences.agent.modelId.discover')}
               </Button>
             )}
@@ -1777,8 +1783,9 @@ export function AgentSection({
             `optionalDescription` 暗示"留空走默认", 但 DeepSeek 等
             locked 供应商不允许留空; 与其显示容易误解的提示, 不如不显示。 */}
         {hideBaseUrlField ? null : (
-          <Field title={t('preferences.agent.baseUrl.title')}>
+          <Field title={t('preferences.agent.baseUrl.title')} controlId="ai-base-url">
             <Input
+              id="ai-base-url"
               value={localConfig.apiUrl}
               onChange={(e) => updateField('apiUrl', e.target.value)}
               placeholder={baseUrlPlaceholder}
@@ -1790,8 +1797,9 @@ export function AgentSection({
         )}
 
         {/* 4. 模型密钥(原"API 密钥") */}
-        <Field title={t('preferences.agent.apiKey.title')} description={apiKeyDescription}>
+        <Field title={t('preferences.agent.apiKey.title')} controlId="ai-api-key" description={apiKeyDescription}>
           <Input
+            id="ai-api-key"
             type="password"
             value={localConfig.apiKeys[apiKeyBucket] ?? ''}
             onChange={(e) => updateApiKey(e.target.value)}
@@ -1986,23 +1994,26 @@ function CustomProviderInlineForm({
         <div className="space-y-4">
           <Field
             title={t('preferences.agent.provider.customId')}
+            controlId="custom-provider-id"
           >
             <Input
+              id="custom-provider-id"
               value={draft.id}
               onChange={(event) => onDraftChange({ ...draft, id: event.target.value })}
               placeholder="acme-gateway"
               className={FIELD_INPUT_CLASS}
             />
           </Field>
-          <Field title={t('preferences.agent.provider.customDisplayName')}>
+          <Field title={t('preferences.agent.provider.customDisplayName')} controlId="custom-provider-display-name">
             <Input
+              id="custom-provider-display-name"
               value={draft.displayName}
               onChange={(event) => onDraftChange({ ...draft, displayName: event.target.value })}
               placeholder={t('preferences.agent.provider.customDisplayName')}
               className={FIELD_INPUT_CLASS}
             />
           </Field>
-          <Field title={t('preferences.agent.provider.customProtocol')}>
+          <Field title={t('preferences.agent.provider.customProtocol')} controlId="custom-provider-protocol">
             <Select
               value={draft.apiProtocol}
               onValueChange={(apiProtocol) => onDraftChange({
@@ -2010,7 +2021,7 @@ function CustomProviderInlineForm({
                 apiProtocol: apiProtocol as CustomProviderDraft['apiProtocol'],
               })}
             >
-              <SelectTrigger className="w-full" />
+              <SelectTrigger id="custom-provider-protocol" className="w-full" />
               <SelectContent align="start" fitViewport className="flowix-preferences-select-content">
                 {CUSTOM_PROVIDER_PROTOCOLS.map((protocol) => (
                   <SelectItem key={protocol} value={protocol}>{protocol}</SelectItem>
@@ -2018,16 +2029,18 @@ function CustomProviderInlineForm({
               </SelectContent>
             </Select>
           </Field>
-          <Field title={t('preferences.agent.baseUrl.title')}>
+          <Field title={t('preferences.agent.baseUrl.title')} controlId="custom-provider-base-url">
             <Input
+              id="custom-provider-base-url"
               value={draft.apiUrl}
               onChange={(event) => onDraftChange({ ...draft, apiUrl: event.target.value })}
               placeholder="https://gateway.example/v1"
               className={FIELD_INPUT_CLASS}
             />
           </Field>
-          <Field title={t('preferences.agent.apiKey.title')}>
+          <Field title={t('preferences.agent.apiKey.title')} controlId="custom-provider-api-key">
             <Input
+              id="custom-provider-api-key"
               type="password"
               value={draft.apiKey}
               onChange={(event) => onDraftChange({ ...draft, apiKey: event.target.value })}
@@ -2092,7 +2105,7 @@ function CustomProviderInlineForm({
               {t('common.cancel')}
             </Button>
             <Button type="button" onClick={() => void submit()} disabled={submitting}>
-              {submitting && <Loader2 className="mr-1.5 h-4 w-4 animate-spin" />}
+              {submitting && <Loader2 className="mr-1.5 h-4 w-4 flowix-spin" />}
               {t(isEditing
                 ? 'preferences.agent.provider.customSave'
                 : 'preferences.agent.provider.customCreate')}
diff --git a/app/flowix-web/features/preferences/sections/agents.tsx b/app/flowix-web/features/preferences/sections/agents.tsx
index cd879c21b..c9aed1379 100644
--- a/app/flowix-web/features/preferences/sections/agents.tsx
+++ b/app/flowix-web/features/preferences/sections/agents.tsx
@@ -18,28 +18,26 @@ import { AGENT_TYPES } from '@/lib/agent-types';
 import type { AgentTypeKey } from '@/types/agent';
 import { cn } from '@/lib/utils';
 import { toast } from '@/lib/toast';
+import { useAgentDataStore } from '@features/agent/store/agent-data-store';
 
 type CollapsibleAgentKey =
   | 'codex'
-  | 'claude'
-  | 'gemini'
+  | 'claudecode'
   | 'hermes'
-  | 'openclaw'
   | 'opencode';
 
 /// "使用自定义模型" 文档链接, codex/claude 的"查看"按钮跳转此处。
 const CUSTOM_MODEL_DOCS_URL = 'https://flowix-memo.com/docs/ai-access/';
 
-/// 偏好设置 AI Agents 列表里要隐藏的 agent; 其它入口仍可独立使用。
+/// 偏好设置不展示内置 Agent 的路径配置卡片。
 const HIDDEN_PREFERENCE_AGENT_KEYS: ReadonlySet<AgentTypeKey> = new Set([
   'pi',
-  'openclaw',
-  'gemini',
-  'deepseek-harness',
+  'dsh',
 ]);
 
 export function AgentsSection() {
   const { t } = useI18n();
+  const persistenceError = useAgentDataStore((state) => state.persistenceError);
   const statusByType = useAgentRuntimeStore((s) => s.statusByType);
   const isChecking = useAgentRuntimeStore((s) => s.isChecking);
   const refreshIfStale = useAgentRuntimeStore((s) => s.refreshIfStale);
@@ -60,8 +58,7 @@ export function AgentsSection() {
     } catch (err) {
       console.warn('[agents] failed to load external config:', err);
     }
-    void refreshStatus({ force: true });
-  }, [refreshStatus]);
+  }, []);
 
   useEffect(() => {
     void refreshIfStale();
@@ -84,10 +81,8 @@ export function AgentsSection() {
   const renderHeaderAction = (typeKey: string) => {
     const isCollapsible =
       typeKey === 'codex' ||
-      typeKey === 'claude' ||
-      typeKey === 'gemini' ||
+      typeKey === 'claudecode' ||
       typeKey === 'hermes' ||
-      typeKey === 'openclaw' ||
       typeKey === 'opencode';
     if (!isCollapsible) {
       return null;
@@ -132,6 +127,14 @@ export function AgentsSection() {
         title={t('preferences.agents.title')}
         description={t('preferences.agents.subtitle')}
       />
+      {persistenceError && (
+        <div
+          role="alert"
+          className="rounded-md border border-[var(--destructive)]/35 bg-[var(--destructive)]/5 px-3 py-2 text-sm text-[var(--destructive)]"
+        >
+          {t('preferences.agents.cacheWriteFailed')}
+        </div>
+      )}
       <AgentRuntimeStatusList
         statusByType={statusByType}
         isChecking={isChecking}
@@ -148,7 +151,7 @@ export function AgentsSection() {
         onCardClick={(key) => toggleExpanded(key as CollapsibleAgentKey)}
         renderAfterRow={(typeKey) => {
           const renderExternalPath = () => {
-            const def = AGENT_TYPES.find((a) => a.key === typeKey);
+            const def = AGENT_TYPES.find((a) => a.id === typeKey);
             const displayName = def?.name ?? typeKey;
             // codex 走终端 npm install; 其余走 openAgentSetup 引导页。
             const onInstall =
@@ -161,13 +164,16 @@ export function AgentsSection() {
                 displayName={displayName}
                 entry={externalConfig?.[typeKey]}
                 onInstall={onInstall}
-                onChanged={() => void refreshExternal()}
+                onChanged={() => {
+                  void refreshExternal();
+                  void refreshStatus({ force: true });
+                }}
               />
             );
           };
-          if (typeKey === 'claude') {
+          if (typeKey === 'claudecode') {
             return renderCollapsible(
-              'claude',
+              'claudecode',
               <>
                 {renderExternalPath()}
                 <FieldRow
@@ -205,11 +211,9 @@ export function AgentsSection() {
               </>,
             );
           }
-          // gemini / hermes / openclaw / opencode: 只展示状态 + 执行路径。
+          // Hermes / OpenCode: 只展示状态 + 执行路径。
           if (
-            typeKey === 'gemini' ||
             typeKey === 'hermes' ||
-            typeKey === 'openclaw' ||
             typeKey === 'opencode'
           ) {
             return renderCollapsible(typeKey as CollapsibleAgentKey, renderExternalPath());
diff --git a/app/flowix-web/features/preferences/sections/cli.tsx b/app/flowix-web/features/preferences/sections/cli.tsx
index 533c796f5..8fa99eb1b 100644
--- a/app/flowix-web/features/preferences/sections/cli.tsx
+++ b/app/flowix-web/features/preferences/sections/cli.tsx
@@ -112,7 +112,7 @@ export function CliSection() {
                 disabled={installing}
               >
                 {installing ? (
-                  <Loader2 data-icon="inline-start" className="animate-spin" />
+                  <Loader2 data-icon="inline-start" className="flowix-spin" />
                 ) : (
                   <Download data-icon="inline-start" />
                 )}
diff --git a/app/flowix-web/features/preferences/sections/cloud-sync.orders.test.tsx b/app/flowix-web/features/preferences/sections/cloud-sync.orders.test.tsx
new file mode 100644
index 000000000..cc151c989
--- /dev/null
+++ b/app/flowix-web/features/preferences/sections/cloud-sync.orders.test.tsx
@@ -0,0 +1,144 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { CloudSyncSection } from './cloud-sync';
+
+const mocks = vi.hoisted(() => ({
+  listBillingOrders: vi.fn(), checkBillingOrder: vi.fn(), listProducts: vi.fn(),
+  refreshMembership: vi.fn(), success: vi.fn(), info: vi.fn(), error: vi.fn(),
+  cloudState: { authenticated: true, account: { user: { id: 'usr_1', displayName: 'User' } } },
+}));
+vi.mock('@platform/tauri/client', () => ({ cloud: {
+  listBillingOrders: mocks.listBillingOrders,
+  checkBillingOrder: mocks.checkBillingOrder,
+  listProducts: mocks.listProducts,
+} }));
+vi.mock('@features/preferences/sections/pi-cloud-models-section', () => ({
+  PiCloudModelsSection: () => 'PI_MEMBER_MODELS_SECTION',
+}));
+vi.mock('@features/preferences/hooks/use-cloud-account-state', () => ({
+  useCloudAccountState: () => ({
+    state: mocks.cloudState,
+    refreshMembership: mocks.refreshMembership,
+  }),
+}));
+vi.mock('@/lib/i18n', async (importOriginal) => ({
+  ...await importOriginal<typeof import('@/lib/i18n')>(),
+  useI18n: () => ({ t: (key: string) => key }),
+}));
+vi.mock('@/lib/toast', () => ({ toast: { success: mocks.success, info: mocks.info, error: mocks.error } }));
+vi.mock('@platform/tauri/event-bus', () => ({ subscribe: () => () => {} }));
+vi.mock('@platform/tauri/opener', () => ({ openUrl: vi.fn() }));
+
+let container: HTMLDivElement;
+let root: Root;
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.cloudState.authenticated = true;
+  mocks.listProducts.mockResolvedValue([]);
+  mocks.listBillingOrders.mockResolvedValue([{
+    id: 'ord_1', productName: 'Plan', amount: 390, currency: 'CNY', status: 'pending', createdAt: 0,
+  }]);
+  mocks.refreshMembership.mockResolvedValue('refreshed');
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+});
+
+async function clickCheck() {
+  await act(async () => root.render(<CloudSyncSection />));
+  const button = Array.from(container.querySelectorAll('button')).find(
+    (item) => item.textContent === 'preferences.cloud.order.check',
+  );
+  expect(button).toBeDefined();
+  await act(async () => button!.click());
+}
+
+it('hides Pi Cloud models while signed out', async () => {
+  mocks.cloudState.authenticated = false;
+  await act(async () => root.render(<CloudSyncSection />));
+  expect(container.textContent).not.toContain('PI_MEMBER_MODELS_SECTION');
+});
+
+it('shows Pi Cloud models while signed in', async () => {
+  await act(async () => root.render(<CloudSyncSection />));
+  expect(container.textContent).toContain('PI_MEMBER_MODELS_SECTION');
+});
+
+it.each([
+  ['unsupported', 'error', 'needsReview'],
+  ['dead_letter', 'error', 'needsReview'],
+  ['failed', 'error', 'syncFailed'],
+  ['processing', 'info', 'processing'],
+  ['pending', 'info', 'notConfirmed'],
+  ['unavailable', 'error', 'unavailable'],
+  ['refunded', 'info', 'refunded'],
+  ['future_status', 'error', 'unknownResult'],
+] as const)('presents %s accurately without reporting successful membership recovery', async (checkStatus, kind, message) => {
+  mocks.checkBillingOrder.mockResolvedValue({ status: 'pending', confirmed: false, checkStatus });
+  await clickCheck();
+  expect(mocks[kind]).toHaveBeenCalledWith(`preferences.cloud.order.${message}`);
+  expect(mocks.success).not.toHaveBeenCalled();
+  expect(mocks.refreshMembership).not.toHaveBeenCalled();
+  if (checkStatus === 'failed') {
+    expect(container.textContent).toContain('preferences.cloud.retry');
+  }
+});
+
+it('refreshes membership after a confirmed payment', async () => {
+  mocks.checkBillingOrder.mockResolvedValue({ status: 'paid', confirmed: true, checkStatus: 'processed' });
+  await clickCheck();
+  expect(mocks.refreshMembership).toHaveBeenCalledOnce();
+  expect(mocks.success).toHaveBeenCalledWith('preferences.cloud.order.confirmed');
+  expect(mocks.listBillingOrders).toHaveBeenCalledTimes(2);
+});
+
+it('shows the localized rate limit message and keeps retry available', async () => {
+  mocks.checkBillingOrder.mockRejectedValue('cloud API error 429 BILLING_RATE_LIMITED: too many checks');
+  await clickCheck();
+  expect(mocks.error).toHaveBeenCalledWith('preferences.cloud.order.rateLimited');
+  expect(container.textContent).toContain('preferences.cloud.retry');
+});
+
+it('reports a confirmed payment with a failed local refresh without showing success', async () => {
+  mocks.checkBillingOrder.mockResolvedValue({ status: 'paid', confirmed: true, checkStatus: 'processed' });
+  mocks.refreshMembership.mockResolvedValue('failed');
+  await clickCheck();
+  expect(mocks.error).toHaveBeenCalledWith('preferences.cloud.order.refreshFailed');
+  expect(mocks.success).not.toHaveBeenCalled();
+});
+
+it.each(['stale', 'skipped'])('does not show recovery feedback for a %s membership refresh', async (result) => {
+  mocks.checkBillingOrder.mockResolvedValue({ status: 'paid', confirmed: true, checkStatus: 'processed' });
+  mocks.refreshMembership.mockResolvedValue(result);
+  await clickCheck();
+  expect(mocks.success).not.toHaveBeenCalled();
+  expect(mocks.error).not.toHaveBeenCalled();
+});
+
+
+it('blocks purchases while an order is pending and enables them after payment confirmation', async () => {
+  mocks.listProducts.mockResolvedValue([{
+    id: 'product_1', name: 'Flowix Go', description: '',
+    price: { amount: 390, currency: 'CNY' },
+    entitlement: { storageBytes: 200 * 1024 * 1024, duration: { unit: 'month', count: 1 }, features: {} },
+  }]);
+  await act(async () => root.render(<CloudSyncSection />));
+  const purchaseButton = () => Array.from(container.querySelectorAll('button')).find(
+    (button) => button.textContent === 'preferences.cloud.plan.go.get',
+  )!;
+  expect(purchaseButton().disabled).toBe(true);
+  expect(container.textContent).toContain('preferences.cloud.order.pendingCheckout');
+
+  mocks.listBillingOrders.mockResolvedValue([{
+    id: 'ord_1', productName: 'Plan', amount: 390, currency: 'CNY', status: 'paid', createdAt: 0,
+  }]);
+  mocks.checkBillingOrder.mockResolvedValue({ status: 'paid', confirmed: true, checkStatus: 'processed' });
+  await clickCheck();
+  expect(purchaseButton().disabled).toBe(false);
+  expect(container.textContent).not.toContain('preferences.cloud.order.pendingCheckout');
+});
diff --git a/app/flowix-web/features/preferences/sections/cloud-sync.tsx b/app/flowix-web/features/preferences/sections/cloud-sync.tsx
index 89b4251ef..e5e2a2c62 100644
--- a/app/flowix-web/features/preferences/sections/cloud-sync.tsx
+++ b/app/flowix-web/features/preferences/sections/cloud-sync.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { Check, Cloud, Info } from 'lucide-react';
+import { Check, Cloud, Info, Loader2 } from 'lucide-react';
 
 import googleLogo from '@/assets/google.svg';
 import { errorMessage } from '@/lib/error-message';
@@ -13,20 +13,17 @@ import { subscribe } from '@platform/tauri/event-bus';
 import {
   cloud,
   type CloudProduct,
+  type CloudOrder,
   type CloudState,
 } from '@platform/tauri/client';
 import { Button } from '@shared/ui/button';
+import { Tooltip } from '@shared/ui/tooltip';
 import { Input } from '@shared/ui/input';
 import { Popover, PopoverContent, PopoverTrigger } from '@shared/ui/popover';
 import { SectionHeader } from '@features/preferences/sections/primitives';
 import { cn } from '@/lib/utils';
 import { useCloudAccountState } from '@features/preferences/hooks/use-cloud-account-state';
-
-function formatBytes(value: number): string {
-  if (value < 1024) return `${value} B`;
-  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`;
-  return `${(value / (1024 * 1024)).toFixed(1)} MB`;
-}
+import { PiCloudModelsSection } from '@features/preferences/sections/pi-cloud-models-section';
 
 function formatStorageCapacity(value: number): string {
   const units = ['B', 'KB', 'MB', 'GB', 'TB'];
@@ -40,6 +37,18 @@ function formatStorageCapacity(value: number): string {
   return `${formatted} ${units[unitIndex]}`;
 }
 
+function formatMembershipBytes(value: number): string {
+  return value === 0 ? '0 MB' : formatStorageCapacity(value);
+}
+
+function formatMembershipDate(value: number): string {
+  const date = new Date(value);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
 function productPlan(product: CloudProduct): 'go' | 'pro' | null {
   const capacity = formatStorageCapacity(product.entitlement.storageBytes);
   const productText = `${product.name} ${product.description}`.toLowerCase();
@@ -80,16 +89,100 @@ export function CloudSyncSection() {
   const [password, setPassword] = useState('');
   const [busy, setBusy] = useState(false);
   const [productsLoadError, setProductsLoadError] = useState<string | null>(null);
+  const [productsLoading, setProductsLoading] = useState(true);
+  const [orders, setOrders] = useState<CloudOrder[]>([]);
+  const [ordersLoading, setOrdersLoading] = useState(false);
+  const [ordersLoadError, setOrdersLoadError] = useState<string | null>(null);
+  const [checkingOrderId, setCheckingOrderId] = useState<string | null>(null);
+  const [orderCheckFailedId, setOrderCheckFailedId] = useState<string | null>(null);
+
+  const hasPendingOrder = orders.some((order) => order.status === 'pending');
+
+  const loadOrders = async () => {
+    if (!state?.authenticated) {
+      setOrders([]);
+      setOrdersLoadError(null);
+      return;
+    }
+    setOrdersLoading(true);
+    setOrdersLoadError(null);
+    try {
+      setOrders(await cloud.listBillingOrders());
+    } catch (error) {
+      setOrdersLoadError(errorMessage(error));
+    } finally {
+      setOrdersLoading(false);
+    }
+  };
+
   useEffect(() => {
     let active = true;
     void cloud.listProducts().then((next) => {
       if (active) setProducts(next);
     }).catch((error) => {
       if (active) setProductsLoadError(errorMessage(error));
+    }).finally(() => {
+      if (active) setProductsLoading(false);
     });
     return () => { active = false; };
   }, []);
 
+  useEffect(() => {
+    let active = true;
+    if (!state?.authenticated) {
+      setOrders([]);
+      setOrdersLoadError(null);
+      return () => { active = false; };
+    }
+    setOrdersLoading(true);
+    setOrdersLoadError(null);
+    void cloud.listBillingOrders().then((next) => {
+      if (active) setOrders(next);
+    }).catch((error) => {
+      if (active) setOrdersLoadError(errorMessage(error));
+    }).finally(() => {
+      if (active) setOrdersLoading(false);
+    });
+    return () => { active = false; };
+  }, [state?.authenticated, state?.account?.user.id]);
+
+  const checkOrder = async (orderId: string) => {
+    setCheckingOrderId(orderId);
+    setOrderCheckFailedId(null);
+    try {
+      const result = await cloud.checkBillingOrder(orderId);
+      await loadOrders();
+      if (result.confirmed) {
+        const refreshResult = await refreshMembership();
+        if (refreshResult === 'refreshed') {
+          toast.success(t('preferences.cloud.order.confirmed'));
+        } else if (refreshResult === 'failed') {
+          toast.error(t('preferences.cloud.order.refreshFailed'));
+        }
+      } else if (result.checkStatus === 'pending') {
+        toast.info(t('preferences.cloud.order.notConfirmed'));
+      } else if (result.checkStatus === 'processing') {
+        toast.info(t('preferences.cloud.order.processing'));
+      } else if (result.checkStatus === 'failed') {
+        setOrderCheckFailedId(orderId);
+        toast.error(t('preferences.cloud.order.syncFailed'));
+      } else if (['unsupported', 'dead_letter'].includes(result.checkStatus)) {
+        toast.error(t('preferences.cloud.order.needsReview'));
+      } else if (result.checkStatus === 'unavailable') {
+        toast.error(t('preferences.cloud.order.unavailable'));
+      } else if (result.checkStatus === 'refunded') {
+        toast.info(t('preferences.cloud.order.refunded'));
+      } else {
+        toast.error(t('preferences.cloud.order.unknownResult'));
+      }
+    } catch (error) {
+      setOrderCheckFailedId(orderId);
+      toast.error(cloudSyncErrorMessage(error, t));
+    } finally {
+      setCheckingOrderId(null);
+    }
+  };
+
   const run = async (task: () => Promise<CloudState>) => {
     setBusy(true);
     try {
@@ -191,18 +284,26 @@ export function CloudSyncSection() {
                 <Cloud className="h-5 w-5" />
               </div>
               <div className="min-w-0 flex-1">
-                <div className="truncate text-sm font-medium">
-                  {state.account?.user.displayName}
+                <div className="flex min-w-0 items-center gap-2">
+                  <div className="truncate text-sm font-medium">
+                    {state.account?.user.displayName}
+                  </div>
+                  {membershipLoading && (
+                    <span className="flex shrink-0 items-center gap-1 whitespace-nowrap text-sm text-[var(--muted-foreground)]">
+                      <Loader2 className="h-3.5 w-3.5 flowix-spin" aria-hidden="true" />
+                      {t('preferences.cloud.membershipLoading')}
+                    </span>
+                  )}
                 </div>
-                <div className="truncate text-xs text-[var(--muted-foreground)]">
+                <div className="truncate text-sm text-[var(--muted-foreground)]">
                   {state.account?.user.email}
                 </div>
               </div>
-              <div className="flex items-center gap-2">
+              <div className="flex shrink-0 items-center gap-2">
                 <Button
                   variant="outline"
                   size="sm"
-                  className="rounded-xl"
+                  className="rounded-xl text-sm"
                   disabled={busy}
                   onClick={() => void run(() => cloud.logout())}
                 >
@@ -212,10 +313,10 @@ export function CloudSyncSection() {
             </div>
 
             <div className="space-y-3 border-t border-[var(--border)] pt-4">
-              <div className="flex items-center gap-2">
+              <div className="flex flex-wrap items-center gap-x-1 gap-y-1">
                 <div className="text-sm font-medium">{t('preferences.cloud.membership')}</div>
                 {state.membership && <span className={cn(
-                  'rounded-full px-2 py-0.5 text-xs',
+                  'rounded-md px-1.5 py-0.5 text-xs',
                   state.membership?.active
                     ? 'bg-[color-mix(in_oklch,var(--success)_15%,transparent)] text-[var(--success)]'
                     : 'bg-[color-mix(in_oklch,var(--warning)_15%,transparent)] text-[var(--warning)]',
@@ -224,164 +325,270 @@ export function CloudSyncSection() {
                     ? t('preferences.cloud.active')
                     : t('preferences.cloud.inactive')}
                 </span>}
+                {state.membership && (
+                  <div className="ml-auto flex flex-wrap items-center gap-x-2 text-sm text-[var(--muted-foreground)]">
+                    <span>
+                      {t('preferences.cloud.usage')} {formatMembershipBytes(state.membership.usedBytes)} / {formatMembershipBytes(state.membership.quotaBytes)}
+                    </span>
+                    {state.membership.expiresAt != null && (
+                      <>
+                        <span aria-hidden="true">｜</span>
+                        <span>
+                          {t('preferences.cloud.expires')}{' '}
+                          {formatMembershipDate(state.membership.expiresAt)}
+                        </span>
+                      </>
+                    )}
+                  </div>
+                )}
               </div>
-              {membershipLoading && <p className="text-xs text-[var(--muted-foreground)]">{t('preferences.cloud.membershipLoading')}</p>}
               {membershipError && <div className="space-y-2">
-                <p className="text-xs text-[var(--destructive)]">{t('preferences.cloud.membershipFailed')}: {membershipError}</p>
+                <p className="text-sm text-[var(--destructive)]">{t('preferences.cloud.membershipFailed')}: {membershipError}</p>
                 <Button variant="outline" className="px-3" disabled={membershipLoading} onClick={() => void refreshMembership()}>
                   {t('preferences.cloud.retry')}
                 </Button>
               </div>}
-              {state.membership && <div className="text-sm text-[var(--muted-foreground)]">
-                {t('preferences.cloud.usage')}: {formatBytes(state.membership?.usedBytes ?? 0)}
-                {' / '}
-                {formatBytes(state.membership?.quotaBytes ?? 0)}
-              </div>}
-              {state.membership?.expiresAt && (
-                <div className="text-xs text-[var(--muted-foreground)]">
-                  {t('preferences.cloud.expires')}:{' '}
-                  {new Date(state.membership.expiresAt).toLocaleDateString()}
-                </div>
-              )}
             </div>
           </div>
 
+          <PiCloudModelsSection authenticated />
 
-          <div className="space-y-3">
-            <div className="text-sm font-medium">{t('preferences.cloud.plans')}</div>
-            <div
-              role="tablist"
-              aria-label={t('preferences.cloud.plans')}
-              className="relative inline-flex h-9 shrink-0 items-center gap-0.5 rounded-xl border border-[var(--border)] bg-[color-mix(in_oklch,var(--foreground)_5%,transparent)] px-0.5 py-0"
-            >
-              {(['monthly', 'yearly'] as const).map((period) => (
-                <button
-                  key={period}
-                  type="button"
-                  role="tab"
-                  aria-selected={billingPeriod === period}
-                  tabIndex={billingPeriod === period ? 0 : -1}
-                  className={cn(
-                    'relative flex h-[30px] items-center justify-center rounded-lg px-1.5 text-sm transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]',
-                    billingPeriod === period
-                      ? 'border border-[var(--border)] bg-[var(--card)] text-[var(--primary)]'
-                      : 'border border-transparent text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]',
+          {(ordersLoading || ordersLoadError || orders.length > 0) && (
+            <div className="space-y-3">
+              {ordersLoading ? (
+                <div aria-hidden="true" className="h-5 w-24 animate-pulse rounded bg-[var(--muted)]" />
+              ) : (
+                <div className="text-sm font-medium">{t('preferences.cloud.order.title')}</div>
+              )}
+              {ordersLoading ? (
+                <div aria-hidden="true" className="h-20 animate-pulse rounded-xl bg-[var(--muted)]" />
+              ) : (
+                <div className="space-y-3 rounded-xl border border-[var(--border)] bg-[var(--card)] p-4">
+                  {ordersLoadError ? (
+                    <div className="space-y-2">
+                      <p className="break-words text-sm text-[var(--destructive)]">{ordersLoadError}</p>
+                      <Button
+                        variant="outline"
+                        size="sm"
+                        className="rounded-lg"
+                        disabled={ordersLoading}
+                        onClick={() => void loadOrders()}
+                      >
+                        {t('preferences.cloud.retry')}
+                      </Button>
+                    </div>
+                  ) : (
+                    <ul className="divide-y divide-[var(--border)]">
+                      {orders.map((order) => {
+                        const checkable = ['pending', 'paid'].includes(order.status);
+                        const statusLabel = order.status === 'pending'
+                          ? t('preferences.cloud.order.status.pending')
+                          : order.status === 'paid'
+                          ? t('preferences.cloud.order.status.paid')
+                          : order.status === 'expired'
+                          ? t('preferences.cloud.order.status.expired')
+                          : order.status === 'refunded'
+                          ? t('preferences.cloud.order.status.refunded')
+                          : t('preferences.cloud.order.status.unknown');
+
+                        return (
+                          <li key={order.id} className="flex flex-wrap items-center gap-x-4 gap-y-2 py-3 first:pt-0 last:pb-0">
+                            <div className="min-w-0 flex-1">
+                              <div className="truncate text-sm font-medium text-[var(--foreground)]">{order.productName}</div>
+                              <div className="mt-1 text-sm text-[var(--muted-foreground)]">
+                                {new Date(order.createdAt).toLocaleString()} · {new Intl.NumberFormat(undefined, {
+                                  style: 'currency', currency: order.currency.toUpperCase(),
+                                }).format(order.amount / 100)}
+                              </div>
+                            </div>
+                            {checkable && (
+                              <Tooltip content={t('preferences.cloud.order.checkTooltip')}>
+                                <Button
+                                  type="button"
+                                  variant="outline"
+                                  size="sm"
+                                  className="rounded-lg"
+                                  disabled={checkingOrderId !== null}
+                                  onClick={() => void checkOrder(order.id)}
+                                >
+                                  {checkingOrderId === order.id
+                                    ? t('preferences.cloud.order.checking')
+                                    : orderCheckFailedId === order.id
+                                    ? t('preferences.cloud.retry')
+                                    : t('preferences.cloud.order.check')}
+                                </Button>
+                              </Tooltip>
+                            )}
+                            <span className={cn(
+                              'rounded-md px-1.5 py-0.5 text-xs',
+                              order.status === 'paid'
+                                ? 'bg-[color-mix(in_oklch,var(--success)_15%,transparent)] text-[var(--success)]'
+                                : 'bg-[color-mix(in_oklch,var(--warning)_15%,transparent)] text-[var(--warning)]',
+                            )}>{statusLabel}</span>
+                          </li>
+                        );
+                      })}
+                    </ul>
                   )}
-                  onClick={() => setBillingPeriod(period)}
-                >
-                  {t(`preferences.cloud.${period}`)}
-                </button>
-              ))}
+                </div>
+              )}
             </div>
-            {productsLoadError && (
-              <p className="break-words text-sm text-[var(--destructive)]">
-                {productsLoadError}
-              </p>
-            )}
-            <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
-              {products.filter((product) => productBillingPeriod(product) === billingPeriod).map((product) => {
-                const plan = productPlan(product);
-                const storageCapacity = formatStorageCapacity(product.entitlement.storageBytes);
-                const [storagePrefix, storageSuffix] = t('preferences.cloud.totalStorage', { capacity: storageCapacity }).split(storageCapacity);
+          )}
 
-                return (
-                  <div
-                    key={product.id}
-                    className="flex h-full min-h-[520px] flex-col rounded-xl border border-[var(--border)] bg-[var(--card)] p-2.5 pt-4 transition-colors hover:border-[var(--primary)]/40 sm:p-3 sm:pt-[18px]"
-                  >
-                    <div className="min-h-14 min-w-0">
-                      <div className="text-[22px] font-semibold leading-7 tracking-tight text-[var(--foreground)]">
-                        {plan
-                          ? t(`preferences.cloud.plan.${plan}.name`)
-                          : product.name}
-                      </div>
-                      {plan && (
-                        <div className="mt-1.5 text-[13px] leading-5 text-[var(--muted-foreground)]">
-                          {t(`preferences.cloud.plan.${plan}.subtitle`)}
-                        </div>
+          {!state.membership?.active && (
+            <div className="space-y-3">
+              {productsLoading ? (
+                <div aria-hidden="true" className="h-5 w-28 animate-pulse rounded bg-[var(--muted)]" />
+              ) : (
+                <div className="text-sm font-medium">{t('preferences.cloud.plans')}</div>
+              )}
+              {hasPendingOrder && !productsLoading && (
+                <p role="status" className="text-sm text-[var(--muted-foreground)]">
+                  {t('preferences.cloud.order.pendingCheckout')}
+                </p>
+              )}
+              {productsLoading ? (
+                <div aria-hidden="true" className="h-9 w-28 animate-pulse rounded-xl bg-[var(--muted)]" />
+              ) : (
+                <div
+                  role="group"
+                  aria-label={t('preferences.cloud.plans')}
+                  className="relative inline-flex h-9 shrink-0 items-center gap-0.5 rounded-xl border border-[var(--border)] bg-[color-mix(in_oklch,var(--foreground)_5%,transparent)] px-0.5 py-0"
+                >
+                  {(['monthly', 'yearly'] as const).map((period) => (
+                    <button
+                      key={period}
+                      type="button"
+                      aria-pressed={billingPeriod === period}
+                      className={cn(
+                        'relative flex h-[30px] items-center justify-center rounded-lg px-1.5 text-sm transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]',
+                        billingPeriod === period
+                          ? 'border border-[var(--border)] bg-[var(--card)] text-[var(--primary)]'
+                          : 'border border-transparent text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]',
                       )}
-                    </div>
-                    <div className="mt-1 flex flex-wrap items-baseline gap-x-1.5 gap-y-1 text-[var(--foreground)]" style={{ fontFamily: 'var(--code-text-font-family)' }}>
-                      <span className="text-[32px] font-semibold leading-10 tracking-tight tabular-nums">
-                        ${(product.price.amount / 100).toFixed(2)}
-                      </span>
-                      <span className="text-[13px] leading-5 text-[var(--muted-foreground)]">
-                        {t(`preferences.cloud.pricePeriod.${billingPeriod}`)}
-                      </span>
-                    </div>
-                    <div className="my-5 border-t border-[var(--border)]" />
-                    <div className="mb-3 text-[13px] font-medium leading-5 text-[var(--foreground)]">
-                      {t('preferences.cloud.plan.includes')}
-                    </div>
-                    <ul className="space-y-2.5 text-[13px] leading-5 text-[var(--muted-foreground)]">
-                      <li className="flex items-start gap-1.5">
-                        <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
-                      <span>
-                        {storagePrefix}<span className="font-medium text-[var(--brand)]">{storageCapacity}</span>{storageSuffix}
-                      </span>
-                      </li>
-                      <li className="flex items-start gap-1.5">
-                        <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
-                        <span>{t('preferences.cloud.unlimitedSyncedNotebooks')}</span>
-                      </li>
-                      <li className="flex items-start gap-1.5">
-                        <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
-                        <span>{t('preferences.cloud.maximumFileSize', { size: '5 MB' })}</span>
-                      </li>
-                      {([
-                        'piByok',
-                        'localAgents',
-                        'mcpCli',
-                        'earlyAccess',
-                      ] as const).map((benefit) => (
-                        <li key={benefit} className="flex items-start gap-1.5">
+                      onClick={() => setBillingPeriod(period)}
+                    >
+                      {t(`preferences.cloud.${period}`)}
+                    </button>
+                  ))}
+                </div>
+              )}
+              {productsLoadError && (
+                <p className="break-words text-sm text-[var(--destructive)]">
+                  {productsLoadError}
+                </p>
+              )}
+              <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+                {productsLoading ? (
+                  <div aria-hidden="true" className="col-span-full h-48 animate-pulse rounded-xl bg-[var(--muted)]" />
+                ) : products.filter((product) => productBillingPeriod(product) === billingPeriod).map((product) => {
+                  const plan = productPlan(product);
+                  const storageCapacity = formatStorageCapacity(product.entitlement.storageBytes);
+                  const [storagePrefix, storageSuffix] = t('preferences.cloud.totalStorage', { capacity: storageCapacity }).split(storageCapacity);
+
+                  return (
+                    <div
+                      key={product.id}
+                      className="flex h-full min-h-[480px] flex-col rounded-xl border border-[var(--border)] bg-[var(--card)] p-2.5 pt-4 transition-colors hover:border-[var(--primary)]/40 sm:p-3 sm:pt-[18px]"
+                    >
+                      <div className="min-h-14 min-w-0">
+                        <div className="text-[22px] font-semibold leading-7 tracking-tight text-[var(--foreground)]">
+                          {plan
+                            ? t(`preferences.cloud.plan.${plan}.name`)
+                            : product.name}
+                        </div>
+                        {plan && (
+                          <div className="mt-1.5 text-sm leading-5 text-[var(--muted-foreground)]">
+                            {t(`preferences.cloud.plan.${plan}.subtitle`)}
+                          </div>
+                        )}
+                      </div>
+                      <div className="mt-1 flex flex-wrap items-baseline gap-x-1.5 gap-y-1 text-[var(--foreground)]" style={{ fontFamily: 'ui-monospace' }}>
+                        <span className="text-[32px] font-normal leading-10 tracking-tight tabular-nums">
+                          ${(product.price.amount / 100).toFixed(2)}
+                        </span>
+                        <span className="text-sm leading-5 text-[var(--muted-foreground)]">
+                          {t(`preferences.cloud.pricePeriod.${billingPeriod}`)}
+                        </span>
+                      </div>
+                      <div className="my-5 border-t border-[var(--border)]" />
+                      <div className="mb-3 text-sm font-medium leading-5 text-[var(--foreground)]">
+                        {t('preferences.cloud.plan.includes')}
+                      </div>
+                      <ul className="space-y-2.5 text-sm leading-5 text-[var(--muted-foreground)]">
+                        <li className="flex items-start gap-1.5">
                           <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
-                          <span>{t(`preferences.cloud.plan.benefit.${benefit}`)}</span>
-                          {benefit === 'localAgents' && (
-                            <div className="-ml-1.5">
-                              <Popover>
-                                <PopoverTrigger asChild>
-                                  <button
-                                    type="button"
-                                    aria-label={t('preferences.cloud.plan.benefit.localAgentsInfo')}
-                                    className="flex h-5 w-5 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
-                                  >
-                                    <Info className="h-3 w-3" aria-hidden="true" />
-                                  </button>
-                                </PopoverTrigger>
-                                <PopoverContent side="top" align="center" className="max-w-[240px] px-3 py-2 text-xs leading-5">
-                                  {t('preferences.cloud.plan.benefit.localAgentsInfo')}
-                                </PopoverContent>
-                              </Popover>
-                            </div>
-                          )}
+                        <span>
+                          {storagePrefix}<span className="font-medium text-[var(--brand)]">{storageCapacity}</span>{storageSuffix}
+                        </span>
                         </li>
-                      ))}
-                    </ul>
-                    <div className="mt-auto pt-6">
-                      <Button
-                        size="lg"
-                        className="h-10 w-full rounded-xl bg-[var(--brand)] text-[13px] font-medium text-[var(--primary-foreground)] hover:bg-[color-mix(in_oklch,var(--brand)_90%,black)]"
-                        disabled={busy}
-                        onClick={() => {
-                          setBusy(true);
-                          void cloud.createCheckout(product.id)
-                            .then((checkout) => openUrl(checkout.checkoutUrl))
-                            .catch((error) => toast.error(errorMessage(error)))
-                            .finally(() => setBusy(false));
-                        }}
-                      >
-                      {plan ? t(`preferences.cloud.plan.${plan}.get`) : t('preferences.cloud.buy')}
-                      </Button>
+                        <li className="flex items-start gap-1.5">
+                          <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
+                          <span>{t('preferences.cloud.unlimitedSyncedNotebooks')}</span>
+                        </li>
+                        <li className="flex items-start gap-1.5">
+                          <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
+                          <span>{t('preferences.cloud.maximumFileSize', { size: '5 MB' })}</span>
+                        </li>
+                        {([
+                          'piByok',
+                          'localAgents',
+                          'mcpCli',
+                          'earlyAccess',
+                        ] as const).map((benefit) => (
+                          <li key={benefit} className="flex items-start gap-1.5">
+                            <Check className="mt-1 h-3 w-3 shrink-0" aria-hidden="true" />
+                            <span>{t(`preferences.cloud.plan.benefit.${benefit}`)}</span>
+                            {benefit === 'localAgents' && (
+                              <div className="-ml-1.5">
+                                <Popover>
+                                  <PopoverTrigger asChild>
+                                    <button
+                                      type="button"
+                                      aria-label={t('preferences.cloud.plan.benefit.localAgentsInfo')}
+                                      className="flex h-5 w-5 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+                                    >
+                                      <Info className="h-3 w-3" aria-hidden="true" />
+                                    </button>
+                                  </PopoverTrigger>
+                                  <PopoverContent side="top" align="center" className="max-w-[240px] px-3 py-2 text-sm leading-5">
+                                    {t('preferences.cloud.plan.benefit.localAgentsInfo')}
+                                  </PopoverContent>
+                                </Popover>
+                              </div>
+                            )}
+                          </li>
+                        ))}
+                      </ul>
+                      <div className="mt-auto">
+                        <Button
+                          size="lg"
+                          className="h-10 w-full rounded-xl bg-[var(--brand)] text-base font-medium text-[var(--primary-foreground)] hover:bg-[color-mix(in_oklch,var(--brand)_90%,black)]"
+                          disabled={busy || ordersLoading || ordersLoadError !== null || hasPendingOrder}
+                          onClick={() => {
+                            if (busy || ordersLoading || ordersLoadError !== null || hasPendingOrder) return;
+                            setBusy(true);
+                            void cloud.createCheckout(product.id)
+                              .then((checkout) => openUrl(checkout.checkoutUrl))
+                              .catch((error) => toast.error(cloudSyncErrorMessage(error, t)))
+                              .finally(async () => {
+                                await loadOrders();
+                                setBusy(false);
+                              });
+                          }}
+                        >
+                        {plan ? t(`preferences.cloud.plan.${plan}.get`) : t('preferences.cloud.buy')}
+                        </Button>
+                      </div>
                     </div>
-                  </div>
-                );
-              })}
+                  );
+                })}
+              </div>
+              {!productsLoadError && products.length > 0 && !products.some((product) => productBillingPeriod(product) === billingPeriod) && (
+                <p className="text-sm text-[var(--muted-foreground)]">{t('preferences.cloud.noPlansForPeriod')}</p>
+              )}
             </div>
-            {!productsLoadError && products.length > 0 && !products.some((product) => productBillingPeriod(product) === billingPeriod) && (
-              <p className="text-sm text-[var(--muted-foreground)]">{t('preferences.cloud.noPlansForPeriod')}</p>
-            )}
-          </div>
+          )}
         </>
       )}
     </div>
diff --git a/app/flowix-web/features/preferences/sections/dsh.tsx b/app/flowix-web/features/preferences/sections/dsh.tsx
index 2b1d1b3f7..97349c815 100644
--- a/app/flowix-web/features/preferences/sections/dsh.tsx
+++ b/app/flowix-web/features/preferences/sections/dsh.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { lazy, Suspense, useCallback, useEffect, useState } from 'react';
 import {
   Check,
   Database,
@@ -14,22 +14,27 @@ import {
 import type { LucideIcon } from 'lucide-react';
 import { Input } from '@shared/ui/input';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@shared/ui/select';
-import { AgentSection } from '@features/preferences/sections/agent';
 import { SectionHeader } from '@features/preferences/sections/primitives';
 import { useI18n, type I18nKey } from '@/lib/i18n';
 import { errorMessage } from '@/lib/error-message';
 import { toast } from '@/lib/toast';
 import { cn } from '@/lib/utils';
 import { AgentIcon } from '@features/agent/components/agent-icon';
+import { DEEPSEEK_HARNESS_MODE_OPTIONS } from '@features/agent/runtime/agent-runtime-spec';
 import { deepseekHarness } from '@platform/tauri/client';
 import type { DeepSeekHarnessPlugin, DeepSeekHarnessPluginCatalog } from '@platform/tauri/client';
 import { dshIntegration, type DshIntegrationStatus } from '@platform/tauri/client';
 import { subscribe } from '@platform/tauri/event-bus';
 import { Button } from '@shared/ui/button';
-import { useDshRuntimeInstaller } from '@features/preferences/hooks/use-dsh-runtime-installer';
+import { SettingsTabGroup } from '@features/preferences/components/settings-tab-group';
+import { openUrl } from '@platform/tauri/opener';
 
 type DshTab = 'models' | 'general' | 'plugins' | 'presets';
 
+const AgentSection = lazy(() =>
+  import('@features/preferences/sections/agent').then((module) => ({ default: module.AgentSection })),
+);
+
 const DSH_TABS: readonly {
   id: DshTab;
   labelKey: I18nKey;
@@ -41,32 +46,11 @@ const DSH_TABS: readonly {
   { id: 'presets', labelKey: 'preferences.dsh.tabs.presets', icon: PanelsTopLeft },
 ];
 
-const DSH_PRESETS: readonly {
-  id: 'standard' | 'code' | 'minimal' | 'cordis';
-  titleKey: I18nKey;
-  descriptionKey: I18nKey;
-}[] = [
-  {
-    id: 'standard',
-    titleKey: 'agent.mode.standard',
-    descriptionKey: 'agent.mode.standard.description',
-  },
-  {
-    id: 'code',
-    titleKey: 'agent.mode.code',
-    descriptionKey: 'agent.mode.code.description',
-  },
-  {
-    id: 'minimal',
-    titleKey: 'agent.mode.minimal',
-    descriptionKey: 'agent.mode.minimal.description',
-  },
-  {
-    id: 'cordis',
-    titleKey: 'agent.mode.cordis',
-    descriptionKey: 'agent.mode.cordis.description',
-  },
-];
+const DSH_PRESETS = DEEPSEEK_HARNESS_MODE_OPTIONS.map(({ id, labelKey, descriptionKey }) => ({
+  id,
+  titleKey: labelKey,
+  descriptionKey,
+}));
 
 const PRESET_TITLE_KEYS: Record<string, I18nKey> = {
   standard: 'preferences.dsh.plugins.presetStandard',
@@ -75,13 +59,11 @@ const PRESET_TITLE_KEYS: Record<string, I18nKey> = {
   cordis: 'preferences.dsh.plugins.presetCreative',
 };
 
-export function DshSettingsSection({ autoUpdate = false }: { autoUpdate?: boolean }) {
+export function DshSettingsSection() {
   const { t } = useI18n();
   const [activeTab, setActiveTab] = useState<DshTab>('general');
-  const [useLocalDevRuntime, setUseLocalDevRuntime] = useState(false);
   const [status, setStatus] = useState<DshIntegrationStatus | null>(null);
   const [statusError, setStatusError] = useState<string | null>(null);
-  const activeTabLabelKey = DSH_TABS.find((tab) => tab.id === activeTab)?.labelKey ?? DSH_TABS[0].labelKey;
 
   const refreshStatus = useCallback(async () => {
     setStatusError(null);
@@ -99,14 +81,9 @@ export function DshSettingsSection({ autoUpdate = false }: { autoUpdate?: boolea
     });
   }, [refreshStatus]);
 
-  const handleUninstalled = (next: DshIntegrationStatus) => {
-    setStatus(next);
-    setActiveTab('general');
-  };
-
   if (status === null) {
     return (
-      <div className="flex min-h-[min(560px,calc(100vh-220px))] flex-col">
+      <div className="flex min-h-0 flex-1 flex-col">
         <SectionHeader
           title={t('preferences.dsh.title')}
           description={t('preferences.dsh.description')}
@@ -114,7 +91,7 @@ export function DshSettingsSection({ autoUpdate = false }: { autoUpdate?: boolea
         <div className="flex flex-1 items-center justify-center px-8 py-12 text-center">
           <div className="space-y-3">
             {!statusError && (
-              <Loader2 className="mx-auto h-7 w-7 animate-spin text-[var(--primary)]" />
+              <Loader2 className="mx-auto h-7 w-7 flowix-spin text-[var(--primary)]" />
             )}
             <p className="text-sm text-[var(--muted-foreground)]">
               {statusError ?? t('preferences.dsh.setup.loading')}
@@ -130,224 +107,212 @@ export function DshSettingsSection({ autoUpdate = false }: { autoUpdate?: boolea
     );
   }
 
-  if (!status.installed && !(import.meta.env.DEV && useLocalDevRuntime)) {
-    if (import.meta.env.DEV) {
-      return (
-        <div className="flex min-h-[min(560px,calc(100vh-220px))] flex-col">
-          <DshDevRuntimeNotice onContinue={() => setUseLocalDevRuntime(true)} />
-        </div>
-      );
-    }
+  if (!status.installed || !status.appServerProfileInstalled) {
     return (
       <div className="flex min-h-[min(560px,calc(100vh-220px))] flex-col">
-        <DshInstallPage initialStatus={status} onInstalled={setStatus} />
+        <DshSetupPage status={status} onStatusChanged={setStatus} />
       </div>
     );
   }
 
-  const displayedStatus = import.meta.env.DEV && useLocalDevRuntime
-    ? { ...status, installed: true }
-    : status;
-
   return (
-    <div className="space-y-5">
+    <div className="flex min-h-0 flex-1 flex-col space-y-5">
       <SectionHeader
         title={t('preferences.dsh.title')}
         description={t('preferences.dsh.description')}
       />
 
-      <div
-        className="grid grid-cols-4 gap-1 rounded-lg border border-[var(--divider)] bg-[var(--muted)]/40 p-1"
-        role="tablist"
-        aria-label={t('preferences.dsh.title')}
+      <SettingsTabGroup
+        tabs={DSH_TABS.map(({ id, labelKey, icon: Icon }) => ({
+          id,
+          label: t(labelKey),
+          icon: <Icon className="h-3.5 w-3.5 shrink-0" />,
+        }))}
+        activeTab={activeTab}
+        onActiveTabChange={(id) => setActiveTab(id as DshTab)}
+        ariaLabel={t('preferences.dsh.title')}
+        listClassName="grid grid-cols-4 gap-1 rounded-lg border border-[var(--divider)] bg-[var(--muted)]/40 p-1"
+        tabClassName="flex min-w-0 items-center justify-center gap-1.5 rounded-md px-2 py-2 text-xs transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]"
+        activeTabClassName="bg-[var(--card)] font-medium text-[var(--primary)] shadow-sm"
+        inactiveTabClassName="text-[var(--muted-foreground)] hover:bg-[var(--card)]/70 hover:text-[var(--foreground)]"
       >
-        {DSH_TABS.map(({ id, labelKey, icon: Icon }) => {
-          const selected = activeTab === id;
-          return (
-            <button
-              key={id}
-              type="button"
-              role="tab"
-              aria-selected={selected}
-              className={cn(
-                'flex min-w-0 items-center justify-center gap-1.5 rounded-md px-2 py-2 text-xs transition-colors',
-                selected
-                  ? 'bg-[var(--card)] font-medium text-[var(--primary)] shadow-sm'
-                  : 'text-[var(--muted-foreground)] hover:bg-[var(--card)]/70 hover:text-[var(--foreground)]',
-              )}
-              onClick={() => setActiveTab(id)}
-            >
-              <Icon className="h-3.5 w-3.5 shrink-0" />
-              <span className="truncate">{t(labelKey)}</span>
-            </button>
-          );
-        })}
-      </div>
-
-      <div role="tabpanel" aria-label={t(activeTabLabelKey)}>
         {activeTab === 'models' && (
-          <AgentSection
-            configStore={deepseekHarness}
-            configChangeKind="dsh_config"
-            testConnection={deepseekHarness.testConnection}
-            modelDirectory={deepseekHarness}
-            hideSectionDivider
-          />
+          <Suspense fallback={(
+            <div className="flex flex-1 items-center justify-center" role="status" aria-busy="true">
+              <Loader2 className="size-6 flowix-spin text-[var(--muted-foreground)]" />
+              <span className="sr-only">{t('preferences.general.loading')}</span>
+            </div>
+          )}>
+            <AgentSection
+              configStore={deepseekHarness}
+              configChangeKind="dsh_config"
+              testConnection={deepseekHarness.testConnection}
+              modelDirectory={deepseekHarness}
+              hideSectionDivider
+            />
+          </Suspense>
         )}
-        {activeTab === 'general' && <GeneralTab initialStatus={displayedStatus} onUninstalled={handleUninstalled} autoUpdate={autoUpdate} />}
+        {activeTab === 'general' && <GeneralTab status={status} />}
         {activeTab === 'plugins' && <PluginsTab />}
         {activeTab === 'presets' && <PresetsTab />}
-      </div>
-    </div>
-  );
-}
-
-function DshDevRuntimeNotice({ onContinue }: { onContinue: () => void }) {
-  return (
-    <div className="flex flex-1 items-start justify-center px-1 py-2">
-      <div className="flex h-[420px] w-full max-w-xl flex-col rounded-2xl border border-[var(--divider)] bg-[var(--card)] p-8 text-center shadow-sm">
-        <div className="mx-auto flex h-16 w-16 items-center justify-center rounded-2xl bg-[color-mix(in_oklch,var(--primary)_12%,transparent)] text-[var(--primary)]">
-          <AgentIcon typeKey="deepseek-harness" alt="" className="h-8 w-8" />
-        </div>
-        <h3 className="mt-5 text-lg font-semibold text-[var(--foreground)]">Dev 本地 DSH</h3>
-        <p className="mt-2 text-sm text-[var(--muted-foreground)]">
-          开发版本使用本地 dsh-host 和 runtime，不下载或安装远程 DSH。
-        </p>
-        <div className="mt-auto pt-8">
-          <Button type="button" onClick={onContinue}>
-            继续使用本地 DSH
-          </Button>
-        </div>
-      </div>
+      </SettingsTabGroup>
     </div>
   );
 }
 
-function DshInstallPage({
-  initialStatus,
-  onInstalled,
+function DshSetupPage({
+  status,
+  onStatusChanged,
 }: {
-  initialStatus: DshIntegrationStatus;
-  onInstalled: (status: DshIntegrationStatus) => void;
+  status: DshIntegrationStatus;
+  onStatusChanged: (status: DshIntegrationStatus) => void;
 }) {
   const { t } = useI18n();
-  const { busy, error, progress, install, cancel } = useDshRuntimeInstaller(initialStatus);
-  const [archiveSize, setArchiveSize] = useState<number | null>(initialStatus.archiveSize ?? null);
-  const canCancel = busy && progress?.phase !== 'downloaded' && progress?.phase !== 'installing';
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [selectingPath, setSelectingPath] = useState(false);
+  const [checkingPath, setCheckingPath] = useState(false);
+
+  const installAppServer = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      onStatusChanged(await dshIntegration.installAppServerProfile());
+      toast.success(t('preferences.dsh.appServer.installSuccess'));
+    } catch (value) {
+      setError(errorMessage(value));
+    } finally {
+      setBusy(false);
+    }
+  };
 
-  useEffect(() => {
-    if (initialStatus.installed) return;
-    void dshIntegration.archiveSize().then((size) => setArchiveSize(size));
-  }, [initialStatus.installed]);
+  const openOfficialInstall = async () => {
+    setError(null);
+    try {
+      await openUrl('https://github.com/deepseek-ai/deepseek-harness');
+    } catch (value) {
+      setError(errorMessage(value));
+    }
+  };
 
-  const startInstall = async () => {
+  const selectCliPath = async () => {
+    setSelectingPath(true);
+    setError(null);
     try {
-      const status = await install();
-      if (status) {
-        onInstalled(status);
-        toast.success(t('preferences.dsh.setup.installSuccess'));
-      }
-    } catch {
-      // The hook owns and exposes the rendered error state.
+      const path = await dshIntegration.selectCliPath();
+      if (!path) return;
+      onStatusChanged(await dshIntegration.setCliPath(path));
+      toast.success(t('preferences.agents.external.pathSaved'));
+    } catch (value) {
+      setError(errorMessage(value));
+    } finally {
+      setSelectingPath(false);
     }
   };
 
-  const cancelInstall = async () => {
-    if (await cancel()) toast.info(t('preferences.dsh.setup.cancelled'));
+  const checkCliPath = async () => {
+    setCheckingPath(true);
+    setError(null);
+    try {
+      const next = await dshIntegration.status();
+      onStatusChanged(next);
+      if (next.installed && next.executablePath) {
+        toast.success(t('preferences.agents.external.checkSuccess'));
+      } else {
+        toast.error(t('preferences.agents.external.checkNotFound'));
+      }
+    } catch (value) {
+      setError(errorMessage(value));
+    } finally {
+      setCheckingPath(false);
+    }
   };
 
   return (
     <div className="flex flex-1 items-start justify-center px-1 py-2">
-      <div className="flex h-[420px] w-full max-w-xl flex-col rounded-2xl border border-[var(--divider)] bg-[var(--card)] p-8 text-center shadow-sm">
+      <div className="flex min-h-[360px] w-full max-w-xl flex-col p-8 text-center">
         <div className="mx-auto flex h-16 w-16 items-center justify-center rounded-2xl bg-[color-mix(in_oklch,var(--primary)_12%,transparent)] text-[var(--primary)]">
-          <AgentIcon typeKey="deepseek-harness" alt="" className="h-8 w-8" />
+          <AgentIcon typeKey="dsh" alt="" className="h-8 w-8" />
         </div>
         <h3 className="mt-5 text-lg font-semibold text-[var(--foreground)]">
           {t('preferences.dsh.setup.title')}
         </h3>
         <p className="mt-2 text-sm text-[var(--muted-foreground)]">
-          {t('preferences.dsh.setup.description')}
+          {status.installed
+            ? status.appServerProfileUpdateAvailable
+              ? t('preferences.dsh.appServer.updateDescription')
+              : status.appServerProfileInstalled
+                ? t('preferences.dsh.appServer.missingDescription')
+                : status.source === 'local-cli'
+                  ? t('preferences.dsh.appServer.localDetected', { version: status.version ?? '—' })
+                  : t('preferences.dsh.appServer.managedRuntime', { version: status.harnessVersion ?? status.version ?? '—' })
+            : t('preferences.dsh.appServer.runtimeMissingDescription')}
         </p>
-        {archiveSize != null && (
-          <p className="mt-3 text-xs text-[var(--muted-foreground)]">
-            {t('preferences.dsh.runtime.packageSize')}: {formatDshArchiveSize(archiveSize)}
-          </p>
-        )}
-
-        <div className="mt-auto flex justify-center gap-2 pt-8">
-          <Button type="button" onClick={() => void startInstall()} disabled={busy}>
-            {busy && <Loader2 className="h-4 w-4 animate-spin" />}
-            {busy ? t(progress?.phase === 'installing' ? 'preferences.dsh.setup.installing' : 'preferences.dsh.setup.downloading') : t('preferences.dsh.setup.install')}
-          </Button>
-          {canCancel && (
-            <Button type="button" variant="outline" onClick={() => void cancelInstall()}>
-              {t('preferences.dsh.setup.cancel')}
+        <div className="mt-4 w-full space-y-2 text-left">
+          <div className="flex min-w-0 items-center gap-2">
+            <Input
+              value={status.executablePath ?? ''}
+              placeholder={t('preferences.agents.external.notConfigured')}
+              spellCheck={false}
+              readOnly
+              disabled
+              title={status.executablePath ?? ''}
+              className="min-w-0 flex-1 text-ellipsis"
+            />
+            <Button
+              type="button"
+              variant="outline"
+              title={t('preferences.agents.external.selectHint')}
+              disabled={selectingPath}
+              onClick={() => void selectCliPath()}
+            >
+              {selectingPath ? <Loader2 className="h-4 w-4 flowix-spin" /> : t('preferences.agents.external.select')}
             </Button>
-          )}
+            <Button
+              type="button"
+              variant="outline"
+              disabled={checkingPath}
+              onClick={() => void checkCliPath()}
+            >
+              {checkingPath ? <Loader2 className="h-4 w-4 flowix-spin" /> : t('preferences.agents.external.check')}
+            </Button>
+          </div>
         </div>
-
-        {busy && progress && (
-          <div className="mx-auto mt-6 max-w-md space-y-2 text-left">
-            <div className="flex justify-between text-xs text-[var(--muted-foreground)]">
-              <span>{t(progress.phase === 'installing' ? 'preferences.dsh.setup.installing' : 'preferences.dsh.setup.downloading')}</span>
-              <span>{progress.percent == null ? '…' : `${progress.percent}%`}</span>
-            </div>
-            <div className="h-2 overflow-hidden rounded-full bg-[var(--muted)]">
-              <div
-                className="h-full rounded-full bg-[var(--primary)] transition-[width]"
-                style={{ width: `${progress.percent ?? 0}%` }}
-              />
-            </div>
-            {progress.resumed && (
+        <div className="mt-auto flex flex-wrap justify-center gap-2 pt-8">
+          {!status.installed ? (
+            <Button type="button" onClick={() => void openOfficialInstall()}>
+              {t('preferences.dsh.appServer.openOfficialInstall')}
+            </Button>
+          ) : (
+            <div className="flex flex-col items-center gap-2">
+              <Button type="button" onClick={() => void installAppServer()} disabled={busy}>
+                {busy && <Loader2 className="h-4 w-4 flowix-spin" />}
+                {busy
+                  ? t('preferences.dsh.appServer.installing')
+                  : status.appServerProfileUpdateAvailable
+                    ? t('preferences.dsh.appServer.update')
+                    : t('preferences.dsh.appServer.install')}
+              </Button>
               <p className="text-xs text-[var(--muted-foreground)]">
-                {t('preferences.dsh.setup.resumed')}
+                {t('preferences.dsh.appServer.installNote')}
               </p>
-            )}
-          </div>
-        )}
-
-        {error && (
-          <div className="mx-auto mt-5 max-w-md space-y-2 rounded-lg border border-[var(--destructive)]/30 bg-[var(--destructive)]/5 px-3 py-2 text-left">
-            <p className="text-xs text-[var(--destructive)]">
-              {t('preferences.dsh.setup.error')}: {error}
-            </p>
-            {!busy && (
-              <Button type="button" variant="outline" className="px-3" onClick={() => void startInstall()}>
-                {t('preferences.dsh.setup.retry')}
-              </Button>
-            )}
-          </div>
-        )}
-
+            </div>
+          )}
+        </div>
+        {error && <p className="mt-4 text-xs text-[var(--destructive)]">{error}</p>}
       </div>
     </div>
   );
 }
 
-function GeneralTab({
-  initialStatus,
-  onUninstalled,
-  autoUpdate = false,
-}: {
-  initialStatus: DshIntegrationStatus;
-  onUninstalled: (status: DshIntegrationStatus) => void;
-  autoUpdate?: boolean;
-}) {
+
+function GeneralTab({ status }: { status: DshIntegrationStatus }) {
   const { t } = useI18n();
-  const { status, busy, error, progress, install, uninstall } =
-    useDshRuntimeInstaller(initialStatus);
-  const autoUpdateStarted = useRef(false);
-  const [uninstalling, setUninstalling] = useState(false);
-  const checkingUpdate = busy && progress?.phase === 'checking';
-  const showingUpdateProgress = busy
-    && (progress?.phase === 'downloading'
-      || progress?.phase === 'downloaded'
-      || progress?.phase === 'installing');
   const rows = [
     {
       icon: Tag,
       title: t('preferences.dsh.general.harnessVersion'),
-      value: status?.harnessVersion ?? 'unknown',
+      value: status.harnessVersion ?? status.version ?? 'unknown',
     },
     {
       icon: Database,
@@ -366,42 +331,6 @@ function GeneralTab({
     },
   ] as const;
 
-  const startUninstall = async () => {
-    if (!window.confirm(t('preferences.dsh.runtime.uninstallConfirm'))) return;
-    setUninstalling(true);
-    try {
-      const next = await uninstall();
-      if (next) {
-        onUninstalled(next);
-        toast.success(t('preferences.dsh.runtime.uninstallSuccess'));
-      } else {
-        toast.error(t('preferences.dsh.runtime.uninstallFailed'));
-      }
-    } finally {
-      setUninstalling(false);
-    }
-  };
-
-  const checkForUpdates = async () => {
-    const previousVersion = status?.version;
-    const next = await install();
-    if (!next) {
-      toast.error(t('preferences.dsh.runtime.updateFailed'));
-      return;
-    }
-    toast.success(
-      next.version && next.version !== previousVersion
-        ? t('preferences.dsh.runtime.updateSuccess')
-        : t('preferences.dsh.runtime.upToDate'),
-    );
-  };
-
-  useEffect(() => {
-    if (!autoUpdate || autoUpdateStarted.current || !status?.installed) return;
-    autoUpdateStarted.current = true;
-    void install();
-  }, [autoUpdate, install, status?.installed]);
-
   return (
     <div className="space-y-2 pb-[30px]">
       <SectionHeader
@@ -421,63 +350,18 @@ function GeneralTab({
         <div className="flex items-center gap-3">
           <div className="min-w-0 flex-1">
             <p className="text-sm text-[var(--foreground)]">{t('preferences.dsh.runtime.version')}</p>
-          </div>
-          <Button
-            variant="outline"
-            className="px-3"
-            disabled={busy || !status?.installed}
-            onClick={() => void checkForUpdates()}
-          >
-            {checkingUpdate && <Loader2 className="h-4 w-4 animate-spin" />}
-            {checkingUpdate
-              ? t('preferences.dsh.runtime.checking')
-              : busy
-                ? t(progress?.phase === 'installing' ? 'preferences.dsh.runtime.installing' : 'preferences.dsh.runtime.downloading')
-                : t('preferences.dsh.runtime.check')}
-          </Button>
-          <Button
-            variant="outline"
-            className="px-3 text-[var(--muted-foreground)] hover:bg-transparent hover:text-[var(--destructive)]"
-            title={t('preferences.dsh.runtime.uninstall')}
-            disabled={busy || !status?.installed}
-            onClick={() => void startUninstall()}
-          >
-            {uninstalling && <Loader2 className="h-4 w-4 animate-spin" />}
-            {uninstalling
-              ? t('preferences.dsh.runtime.uninstalling')
-              : t('preferences.dsh.runtime.uninstallButton')}
-          </Button>
-        </div>
-        {showingUpdateProgress && progress && (
-          <div className="space-y-1.5">
-            <div className="flex justify-between text-xs text-[var(--muted-foreground)]">
-              <span>{t(progress.phase === 'installing' ? 'preferences.dsh.runtime.installing' : 'preferences.dsh.runtime.downloading')}</span>
-              <span>{progress.percent == null ? '…' : `${progress.percent}%`}</span>
-            </div>
-            <div className="h-1.5 overflow-hidden rounded-full bg-[var(--muted)]">
-              <div
-                className="h-full rounded-full bg-[var(--primary)] transition-[width]"
-                style={{ width: `${progress.percent ?? 0}%` }}
-              />
-            </div>
-            {progress.resumed && (
-              <p className="text-xs text-[var(--muted-foreground)]">
-                {t('preferences.dsh.runtime.resumed')}
+            {status.source === 'local-cli' && (
+              <p className="mt-1 truncate text-sm text-[var(--muted-foreground)]">
+                {t('preferences.dsh.appServer.localRuntime', { path: status.executablePath ?? '' })}
               </p>
             )}
           </div>
-        )}
-        {error && <p className="text-xs text-[var(--destructive)]">{error}</p>}
+        </div>
       </div>
     </div>
   );
 }
 
-function formatDshArchiveSize(bytes: number | null | undefined): string {
-  if (!Number.isFinite(bytes) || bytes == null || bytes <= 0) return '—';
-  const megabytes = bytes / (1024 * 1024);
-  return `${megabytes.toFixed(megabytes >= 10 ? 0 : 1)} MB`;
-}
 
 function PluginsTab() {
   const { t } = useI18n();
diff --git a/app/flowix-web/features/preferences/sections/environment-config.tsx b/app/flowix-web/features/preferences/sections/environment-config.tsx
new file mode 100644
index 000000000..38e02e16b
--- /dev/null
+++ b/app/flowix-web/features/preferences/sections/environment-config.tsx
@@ -0,0 +1,195 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { boot, product, relaunch, type CloudEnvironment, type ProductInfo } from '@platform/tauri/client';
+import { Button } from '@shared/ui/button';
+import { Select, SelectContent, SelectItem, SelectTrigger } from '@shared/ui/select';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@shared/ui/dialog';
+import { Tooltip } from '@shared/ui/tooltip';
+import { toast } from '@/lib/toast';
+import { useI18n } from '@/lib/i18n';
+import { FieldRow, SectionHeader } from '@features/preferences/sections/primitives';
+
+interface EnvironmentConfigSectionProps {
+  productInfo: ProductInfo | null;
+}
+
+export function EnvironmentConfigSection({ productInfo }: EnvironmentConfigSectionProps) {
+  const { t } = useI18n();
+  const [switchingCloudEnvironment, setSwitchingCloudEnvironment] = useState(false);
+  const [confirmingProdSwitch, setConfirmingProdSwitch] = useState(false);
+  const [versionInitializationCompleted, setVersionInitializationCompleted] = useState<boolean | null>(null);
+  const [savingVersionInitialization, setSavingVersionInitialization] = useState(false);
+  const cloudEnvironmentLabel = productInfo?.cloudEnvironment === 'prod'
+    ? t('preferences.environmentConfig.cloudEnvironment.prod')
+    : t('preferences.environmentConfig.cloudEnvironment.staging');
+
+  useEffect(() => {
+    let active = true;
+    if (!productInfo?.isDevBuild) {
+      setVersionInitializationCompleted(null);
+      return () => { active = false; };
+    }
+    void boot.getVersionInitializationCompleted().then((completed) => {
+      if (active) setVersionInitializationCompleted(completed);
+    }).catch(() => {
+      if (active) toast.error(t('preferences.environmentConfig.versionInitialization.loadFailed'));
+    });
+    return () => { active = false; };
+  }, [productInfo?.isDevBuild, t]);
+
+  const handleVersionInitializationChange = async () => {
+    if (versionInitializationCompleted === null || savingVersionInitialization) return;
+    const completed = !versionInitializationCompleted;
+    setSavingVersionInitialization(true);
+    try {
+      await boot.setVersionInitializationCompleted(completed);
+      setVersionInitializationCompleted(completed);
+      toast.success(t(completed
+        ? 'preferences.environmentConfig.versionInitialization.markedComplete'
+        : 'preferences.environmentConfig.versionInitialization.rerunNextLaunch'));
+    } catch {
+      toast.error(t('preferences.environmentConfig.versionInitialization.saveFailed'));
+    } finally {
+      setSavingVersionInitialization(false);
+    }
+  };
+
+  const applyCloudEnvironment = async (environment: CloudEnvironment) => {
+    if (!productInfo?.isDevBuild) return;
+    setSwitchingCloudEnvironment(true);
+    let preferenceSaved = false;
+    try {
+      await product.setCloudEnvironment(environment);
+      preferenceSaved = true;
+      await relaunch();
+    } catch {
+      setSwitchingCloudEnvironment(false);
+      setConfirmingProdSwitch(false);
+      toast.error(t(preferenceSaved
+        ? 'preferences.environmentConfig.cloudEnvironment.restartFailed'
+        : 'preferences.environmentConfig.cloudEnvironment.failed'));
+    }
+  };
+
+  const handleCloudEnvironmentChange = (value: string) => {
+    if (!productInfo?.isDevBuild) return;
+    const environment = value === 'staging' || value === 'prod' ? value : null;
+    if (!environment || environment === productInfo.cloudEnvironment) return;
+    if (environment === 'prod') {
+      setConfirmingProdSwitch(true);
+      return;
+    }
+    void applyCloudEnvironment(environment);
+  };
+
+  const handleOpenLogDir = async () => {
+    try {
+      await product.openLogDir();
+    } catch {
+      toast.error(t('preferences.environmentConfig.runtimeLogs.openFailed'));
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      <SectionHeader title={t('preferences.environmentConfig.title')} />
+
+      {productInfo?.isDevBuild && (
+        <FieldRow
+          title={t('preferences.environmentConfig.cloudEnvironment.title')}
+          description={t('preferences.environmentConfig.cloudEnvironment.description')}
+          controlId="preferences-cloud-environment"
+        >
+          <Select
+            value={productInfo.cloudEnvironment}
+            disabled={switchingCloudEnvironment}
+            onValueChange={handleCloudEnvironmentChange}
+          >
+            <SelectTrigger id="preferences-cloud-environment" className="w-64">
+              <span>{cloudEnvironmentLabel}</span>
+            </SelectTrigger>
+            <SelectContent className="flowix-preferences-select-content">
+              <SelectItem value="staging">
+                {t('preferences.environmentConfig.cloudEnvironment.staging')}
+              </SelectItem>
+              <SelectItem value="prod">
+                {t('preferences.environmentConfig.cloudEnvironment.prod')}
+              </SelectItem>
+            </SelectContent>
+          </Select>
+        </FieldRow>
+      )}
+
+      {productInfo?.isDevBuild && (
+        <FieldRow
+          title={t('preferences.environmentConfig.versionInitialization.title')}
+          description={t('preferences.environmentConfig.versionInitialization.description')}
+        >
+          <button
+            type="button"
+            role="switch"
+            aria-checked={versionInitializationCompleted === true}
+            aria-label={t('preferences.environmentConfig.versionInitialization.title')}
+            disabled={versionInitializationCompleted === null || savingVersionInitialization}
+            onClick={() => void handleVersionInitializationChange()}
+            className={`relative h-5 w-9 shrink-0 rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-45 ${
+              versionInitializationCompleted ? 'bg-[var(--primary)]' : 'bg-[var(--muted)]'
+            }`}
+          >
+            <span
+              className={`absolute left-0.5 top-0.5 h-4 w-4 rounded-full bg-[var(--card)] shadow-sm transition-transform ${
+                versionInitializationCompleted ? 'translate-x-4' : 'translate-x-0'
+              }`}
+            />
+          </button>
+        </FieldRow>
+      )}
+
+      <FieldRow
+        title={t('preferences.environmentConfig.runtimeLogs.title')}
+        description={productInfo?.logDir ?? t('preferences.environmentConfig.runtimeLogs.description')}
+      >
+        <Tooltip content={t('preferences.environmentConfig.runtimeLogs.openFolder')}>
+          <Button variant="outline" className="px-3" onClick={() => void handleOpenLogDir()}>
+            {t('preferences.environmentConfig.runtimeLogs.open')}
+          </Button>
+        </Tooltip>
+      </FieldRow>
+
+      <Dialog open={confirmingProdSwitch} onOpenChange={(open) => {
+        if (!switchingCloudEnvironment) setConfirmingProdSwitch(open);
+      }}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{t('preferences.environmentConfig.cloudEnvironment.prodConfirm.title')}</DialogTitle>
+            <DialogDescription>
+              {t('preferences.environmentConfig.cloudEnvironment.prodConfirm.description')}
+            </DialogDescription>
+          </DialogHeader>
+          <div className="mt-4 flex justify-end gap-2">
+            <Button
+              variant="ghost"
+              disabled={switchingCloudEnvironment}
+              onClick={() => setConfirmingProdSwitch(false)}
+            >
+              {t('dialog.cancel')}
+            </Button>
+            <Button
+              disabled={switchingCloudEnvironment}
+              onClick={() => void applyCloudEnvironment('prod')}
+            >
+              {t('preferences.environmentConfig.cloudEnvironment.prodConfirm.confirm')}
+            </Button>
+          </div>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/preferences/sections/external-path-row.tsx b/app/flowix-web/features/preferences/sections/external-path-row.tsx
index 2f3e05d2b..04897b417 100644
--- a/app/flowix-web/features/preferences/sections/external-path-row.tsx
+++ b/app/flowix-web/features/preferences/sections/external-path-row.tsx
@@ -126,7 +126,7 @@ export function ExternalPathRow({
             onClick={() => void switchPath()}
           >
             {switching ? (
-              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+              <Loader2 className="h-3.5 w-3.5 flowix-spin" />
             ) : (
               t('preferences.agents.external.select')
             )}
@@ -138,7 +138,7 @@ export function ExternalPathRow({
             onClick={() => void check()}
           >
             {detecting ? (
-              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+              <Loader2 className="h-3.5 w-3.5 flowix-spin" />
             ) : (
               t('preferences.agents.external.check')
             )}
diff --git a/app/flowix-web/features/preferences/sections/file-management.tsx b/app/flowix-web/features/preferences/sections/file-management.tsx
index 41ca880f7..f0f411f81 100644
--- a/app/flowix-web/features/preferences/sections/file-management.tsx
+++ b/app/flowix-web/features/preferences/sections/file-management.tsx
@@ -9,6 +9,7 @@ import { NotebookTreeResourceIcon } from '@features/memo/components/file-type-ic
 import { ResourceFolderIcon } from '@features/surface/resource-file-icon';
 import { useNoteStore } from '@features/memo/store/note-store';
 import { FIELD_TITLE_CLASS, SectionHeader } from '@features/preferences/sections/primitives';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 
 type NotebookOption = Awaited<ReturnType<typeof notebooks.getAll>>[number];
 type NotebookSettingsTreeEntry = Awaited<ReturnType<typeof files.getNotebookSettingsTree>>[number];
@@ -357,13 +358,13 @@ export function FileManagementSection({ hideSectionHeader = false }: { hideSecti
                   </div>
                   <span className="w-16 truncate text-center text-xs text-[var(--muted-foreground)]">{t(typeLabel)}</span>
                   <div className="flex w-20 justify-center">
-                    {entry.isDirectory && !entry.hidden && !entry.defaultHidden && !entry.locked && <input type="checkbox" aria-label={`${t('preferences.fileManagement.noteLocationTitle')}: ${entry.relativePath || notebookDirectoryName}`} className="h-4 w-4 accent-[var(--brand)]" checked={isDefaultLocation} disabled={!preferences || locationDisabled || savingFolderSettings} onChange={() => updateNotebookPreferences({ defaultCreateFolder: isDefaultLocation ? null : entry.relativePath || null })} />}
+                    {entry.isDirectory && !entry.hidden && !entry.defaultHidden && !entry.locked && <FlowixCheckbox aria-label={`${t('preferences.fileManagement.noteLocationTitle')}: ${entry.relativePath || notebookDirectoryName}`} checked={isDefaultLocation} disabled={!preferences || locationDisabled || savingFolderSettings} onCheckedChange={(checked) => updateNotebookPreferences({ defaultCreateFolder: checked ? entry.relativePath || null : null })} />}
                   </div>
                   <div className="flex w-16 justify-center">
-                    {!isFlowixDirectory && (isRootAgents || (!entry.defaultHidden && entry.isDirectory)) && <input type="checkbox" aria-label={`${t('preferences.fileManagement.noteIndexTitle')}: ${entry.relativePath || notebookDirectoryName}`} className="h-4 w-4 accent-[var(--brand)]" checked={!excluded} disabled={!preferences || entry.locked || savingFolderSettings || (entry.relativePath !== '' && parentExcluded)} onChange={(event) => updateIndexExclusion(entry.relativePath, !event.currentTarget.checked)} />}
+                    {!isFlowixDirectory && (isRootAgents || (!entry.defaultHidden && entry.isDirectory)) && <FlowixCheckbox aria-label={`${t('preferences.fileManagement.noteIndexTitle')}: ${entry.relativePath || notebookDirectoryName}`} checked={!excluded} disabled={!preferences || entry.locked || savingFolderSettings || (entry.relativePath !== '' && parentExcluded)} onCheckedChange={(checked) => updateIndexExclusion(entry.relativePath, !checked)} />}
                   </div>
                   <div className="flex w-16 justify-center">
-                    {!isFlowixDirectory && <input type="checkbox" aria-label={`${t('preferences.fileManagement.hiddenColumn')}: ${entry.relativePath || notebookDirectoryName}`} className="h-4 w-4 accent-[var(--brand)]" checked={!entry.hidden} disabled={!preferences || entry.locked || !entry.relativePath || pendingPaths.includes(entry.relativePath)} onChange={() => toggleTreeDisplay(entry)} />}
+                    {!isFlowixDirectory && <FlowixCheckbox aria-label={`${t('preferences.fileManagement.hiddenColumn')}: ${entry.relativePath || notebookDirectoryName}`} checked={!entry.hidden} disabled={!preferences || entry.locked || !entry.relativePath || pendingPaths.includes(entry.relativePath)} onCheckedChange={() => toggleTreeDisplay(entry)} />}
                   </div>
                 </div>;
               })}
diff --git a/app/flowix-web/features/preferences/sections/format.tsx b/app/flowix-web/features/preferences/sections/format.tsx
index 28d5d3d67..8094ae551 100644
--- a/app/flowix-web/features/preferences/sections/format.tsx
+++ b/app/flowix-web/features/preferences/sections/format.tsx
@@ -69,6 +69,7 @@ interface FormatSectionProps {
  * so the slider doesn't stretch across the full preferences content area.
  */
 function SliderRow({
+  id,
   value,
   min,
   max,
@@ -76,6 +77,7 @@ function SliderRow({
   onChange,
   formatValue,
 }: {
+  id: string;
   value: number;
   min: number;
   max: number;
@@ -89,6 +91,7 @@ function SliderRow({
   return (
     <div className="flex w-64 items-center gap-3">
       <input
+        id={id}
         type="range"
         min={min}
         max={max}
@@ -214,12 +217,13 @@ export function FormatSection({ settings, updateSettings }: FormatSectionProps)
       <FieldRow
         title={t('preferences.format.font.title')}
         description={t('preferences.format.font.description')}
+        controlId="preferences-format-font"
       >
         <Select
           value={selectValue}
           onValueChange={(value) => { void handleFontChange(value); }}
         >
-          <SelectTrigger className="w-72">
+          <SelectTrigger id="preferences-format-font" className="w-72">
             <span
               className="flex min-w-0 flex-1 items-center gap-2 text-left"
               style={{ fontFamily: settings.fontFamily }}
@@ -230,7 +234,7 @@ export function FormatSection({ settings, updateSettings }: FormatSectionProps)
                   : fontLabel}
               </span>
               {loadingFontId && (
-                <Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin text-[var(--primary)]" aria-hidden="true" />
+                <Loader2 className="h-3.5 w-3.5 shrink-0 flowix-spin text-[var(--primary)]" aria-hidden="true" />
               )}
             </span>
           </SelectTrigger>
@@ -247,7 +251,7 @@ export function FormatSection({ settings, updateSettings }: FormatSectionProps)
                           ? `${t('preferences.format.fontStatus.downloading')}${activeProgressLabel}`
                           : t('preferences.format.fontStatus.needsDownload')}
                         {isLoading && (
-                          <Loader2 className="h-3 w-3 animate-spin text-[var(--primary)]" aria-hidden="true" />
+                          <Loader2 className="h-3 w-3 flowix-spin text-[var(--primary)]" aria-hidden="true" />
                         )}
                       </span>
                     )}
@@ -263,8 +267,10 @@ export function FormatSection({ settings, updateSettings }: FormatSectionProps)
       <FieldRow
         title={t('preferences.format.documentWidth.title')}
         description={t('preferences.format.documentWidth.description')}
+        controlId="preferences-format-document-width"
       >
         <SliderRow
+          id="preferences-format-document-width"
           value={settings.documentWidth}
           min={DOCUMENT_WIDTH_MIN}
           max={DOCUMENT_WIDTH_MAX}
@@ -282,8 +288,10 @@ export function FormatSection({ settings, updateSettings }: FormatSectionProps)
       <FieldRow
         title={t('preferences.format.fontSize.title')}
         description={t('preferences.format.fontSize.description')}
+        controlId="preferences-format-font-size"
       >
         <SliderRow
+          id="preferences-format-font-size"
           value={settings.fontSize}
           min={FONT_SIZE_MIN}
           max={FONT_SIZE_MAX}
@@ -297,8 +305,10 @@ export function FormatSection({ settings, updateSettings }: FormatSectionProps)
       <FieldRow
         title={t('preferences.format.lineHeight.title')}
         description={t('preferences.format.lineHeight.description')}
+        controlId="preferences-format-line-height"
       >
         <SliderRow
+          id="preferences-format-line-height"
           value={settings.lineHeight}
           min={LINE_HEIGHT_MIN}
           max={LINE_HEIGHT_MAX}
diff --git a/app/flowix-web/features/preferences/sections/general.tsx b/app/flowix-web/features/preferences/sections/general.tsx
index d4fc1b56b..c3f2d4cc6 100644
--- a/app/flowix-web/features/preferences/sections/general.tsx
+++ b/app/flowix-web/features/preferences/sections/general.tsx
@@ -1,18 +1,12 @@
 'use client';
 
-import { useEffect, useState, type ReactNode } from 'react';
+import { useState, type ReactNode } from 'react';
 import { Check, Copy } from 'lucide-react';
 import { useAppUpdater } from '@features/shell/hooks/use-app-updater';
-import {
-  Select,
-  SelectTrigger,
-  SelectContent,
-  SelectItem,
-} from '@shared/ui/select';
+import { Select, SelectTrigger, SelectContent, SelectItem } from '@shared/ui/select';
 import { Button } from '@shared/ui/button';
 import { UpdateProgress } from '@shared/ui/update-progress';
-import { Tooltip } from '@shared/ui/tooltip';
-import { product, type ProductInfo } from '@platform/tauri/client';
+import type { ProductInfo } from '@platform/tauri/client';
 import { toast } from '@/lib/toast';
 import {
   FieldRow,
@@ -23,6 +17,7 @@ import { LANGUAGE_OPTIONS, useI18n, type AppLanguage } from '@/lib/i18n';
 
 interface GeneralSectionProps {
   language: AppLanguage;
+  productInfo: ProductInfo | null;
   afterGeneral?: ReactNode;
   updateSettings: (updates: {
     language?: AppLanguage;
@@ -30,28 +25,13 @@ interface GeneralSectionProps {
   }) => Promise<void>;
 }
 
-export function GeneralSection({ language, afterGeneral, updateSettings }: GeneralSectionProps) {
+export function GeneralSection({ language, productInfo, afterGeneral, updateSettings }: GeneralSectionProps) {
   const { t } = useI18n();
-  const [productInfo, setProductInfo] = useState<ProductInfo | null>(null);
   const [versionCopied, setVersionCopied] = useState(false);
   const updater = useAppUpdater();
   const currentLanguageLabel =
     LANGUAGE_OPTIONS.find((option) => option.value === language)?.label ?? language;
 
-  useEffect(() => {
-    product.getInfo()
-      .then(setProductInfo)
-      .catch(() => setProductInfo(null));
-  }, []);
-
-  const handleOpenLogDir = async () => {
-    try {
-      await product.openLogDir();
-    } catch {
-      toast.error(t('preferences.general.runtimeLogs.openFailed'));
-    }
-  };
-
   const handleCheckProductUpdates = async () => {
     try {
       const update = await updater.checkNow();
@@ -104,12 +84,13 @@ export function GeneralSection({ language, afterGeneral, updateSettings }: Gener
 
       <FieldRow
         title={t('preferences.general.language.title')}
+        controlId="preferences-language"
       >
         <Select
           value={language}
           onValueChange={(value) => updateSettings({ language: value as AppLanguage })}
         >
-          <SelectTrigger className="w-40">
+          <SelectTrigger id="preferences-language" className="w-40">
             <span>{currentLanguageLabel}</span>
           </SelectTrigger>
           <SelectContent className="flowix-preferences-select-content">
@@ -196,22 +177,6 @@ export function GeneralSection({ language, afterGeneral, updateSettings }: Gener
         </div>
       )}
 
-      {import.meta.env.DEV && (
-        <FieldRow
-          title={t('preferences.general.runtimeLogs.title')}
-          description={productInfo?.logDir ?? t('preferences.general.runtimeLogs.description')}
-        >
-          <Tooltip content={t('preferences.general.runtimeLogs.openFolder')}>
-            <Button
-              variant="outline"
-              className="px-3"
-              onClick={handleOpenLogDir}
-            >
-              {t('preferences.general.runtimeLogs.open')}
-            </Button>
-          </Tooltip>
-        </FieldRow>
-      )}
     </div>
   );
 }
diff --git a/app/flowix-web/features/preferences/sections/history.tsx b/app/flowix-web/features/preferences/sections/history.tsx
index 333402311..f8251e157 100644
--- a/app/flowix-web/features/preferences/sections/history.tsx
+++ b/app/flowix-web/features/preferences/sections/history.tsx
@@ -9,7 +9,7 @@ import { notes, type PathArchiveSummary, type PathVersionMeta } from '@platform/
 import { Button } from '@shared/ui/button';
 import { useDocumentStore } from '@features/document/store/document-store';
 import { documentIdentityFromFile } from '@features/document/store/document-identity';
-import { applyLoadedDocumentContent, flushDocumentPath } from '@features/document/store/document-session-service';
+import { applyLoadedDocumentContent, saveDocumentPath } from '@features/document/store/document-session-service';
 
 export function HistorySection() {
   const { t } = useI18n();
@@ -47,7 +47,7 @@ export function HistorySection() {
         && session.relativePath === archive.relativePath ? session : null;
       if (active) {
         const identity = documentIdentityFromFile(active.fileIdentity);
-        if (!await flushDocumentPath(identity, active.fileIdentity.path, active.scopePath)) {
+        if (!await saveDocumentPath(identity, active.fileIdentity.path, active.scopePath)) {
           toast.error(t('document.version.saveCurrentFailed'));
           return;
         }
diff --git a/app/flowix-web/features/preferences/sections/index.ts b/app/flowix-web/features/preferences/sections/index.ts
index 9c9ab8af6..14c5ca2cc 100644
--- a/app/flowix-web/features/preferences/sections/index.ts
+++ b/app/flowix-web/features/preferences/sections/index.ts
@@ -1,8 +1,8 @@
-// Sections barrel — re-exports every settings tab plus shared types & primitives.
-// Both the main-window command palette (`windows/main/menu-board.tsx`) and the
-// dedicated Preferences window (`windows/preferences/preferences-view.tsx`)
-// import from here so there's a single source of truth for the tab content.
+// Sections barrel for direct consumers that need specific settings sections.
+// The Preferences window uses the lazy tab registry instead, so importing the
+// barrel here would pull every section into the preference-window entry chunk.
 export { GeneralSection } from '@features/preferences/sections/general';
+export { EnvironmentConfigSection } from '@features/preferences/sections/environment-config';
 export { FileDisplayRulesSection } from '@features/preferences/sections/file-display-rules';
 export { FormatSection } from '@features/preferences/sections/format';
 export { ThemeSection } from '@features/preferences/sections/theme';
diff --git a/app/flowix-web/features/preferences/sections/note-settings.tsx b/app/flowix-web/features/preferences/sections/note-settings.tsx
index c2adb7595..6dea9ae76 100644
--- a/app/flowix-web/features/preferences/sections/note-settings.tsx
+++ b/app/flowix-web/features/preferences/sections/note-settings.tsx
@@ -3,7 +3,7 @@
 import { Component, lazy, Suspense, useState, type ReactNode } from 'react';
 import { Loader2 } from 'lucide-react';
 import { useI18n } from '@/lib/i18n';
-import { cn } from '@/lib/utils';
+import { SettingsTabGroup } from '@features/preferences/components/settings-tab-group';
 
 type NoteSettingsTab = 'templates' | 'properties' | 'documentManagement';
 
@@ -65,62 +65,40 @@ export function NoteSettingsSection() {
   ];
 
   return (
-    <div className="space-y-6">
-      <div
-        className="flex gap-6 border-b border-[var(--divider)]"
-        role="tablist"
-        aria-label={t('preferences.tabs.noteSettings')}
+    <div className="flex min-h-0 flex-1 flex-col space-y-6">
+      <SettingsTabGroup
+        tabs={tabs}
+        activeTab={activeTab}
+        onActiveTabChange={(id) => setActiveTab(id as NoteSettingsTab)}
+        ariaLabel={t('preferences.tabs.noteSettings')}
+        listClassName="flex gap-6 border-b border-[var(--divider)]"
+        tabClassName="relative -mb-px min-w-0 border-b-2 px-0.5 py-2.5 text-base font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]"
+        activeTabClassName="border-[var(--primary)] text-[var(--primary)]"
+        inactiveTabClassName="border-transparent text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
       >
-        {tabs.map(({ id, label }) => {
-          const selected = activeTab === id;
-          return (
-            <button
-              key={id}
-              id={`note-settings-tab-${id}`}
-              type="button"
-              role="tab"
-              aria-selected={selected}
-              aria-controls={`note-settings-panel-${id}`}
-              className={cn(
-                'relative -mb-px min-w-0 border-b-2 px-0.5 py-2.5 text-base font-medium transition-colors',
-                selected
-                  ? 'border-[var(--primary)] text-[var(--primary)]'
-                  : 'border-transparent text-[var(--muted-foreground)] hover:text-[var(--foreground)]',
+        <div className={activeTab === 'properties' ? undefined : 'pt-2'}>
+          <SectionErrorBoundary
+            key={activeTab}
+            errorText={t('preferences.noteSettings.loadFailed')}
+            retryText={t('preferences.noteSettings.retry')}
+          >
+            <Suspense
+              fallback={(
+                <div className="flex min-h-0 flex-1 flex-col space-y-6" aria-busy="true">
+                  <div className="flex flex-1 items-center justify-center" role="status" aria-label={t('preferences.general.loading')}>
+                    <Loader2 className="size-6 flowix-spin text-[var(--muted-foreground)]" />
+                    <span className="sr-only">{t('preferences.general.loading')}</span>
+                  </div>
+                </div>
               )}
-              onClick={() => setActiveTab(id)}
             >
-              <span className="block truncate">{label}</span>
-            </button>
-          );
-        })}
-      </div>
-
-      <div
-        id={`note-settings-panel-${activeTab}`}
-        role="tabpanel"
-        aria-labelledby={`note-settings-tab-${activeTab}`}
-      >
-        <SectionErrorBoundary
-          key={activeTab}
-          errorText={t('preferences.noteSettings.loadFailed')}
-          retryText={t('preferences.noteSettings.retry')}
-        >
-          <Suspense
-            fallback={(
-              <div className="space-y-6" aria-busy="true">
-                <div className="flex h-48 items-center justify-center" role="status" aria-label={t('preferences.general.loading')}>
-                  <Loader2 className="size-6 animate-spin text-[var(--muted-foreground)]" />
-                  <span className="sr-only">{t('preferences.general.loading')}</span>
-                </div>
-              </div>
-            )}
-          >
-            {activeTab === 'templates' && <TemplatesSection hideSectionHeader />}
-            {activeTab === 'properties' && <DocumentPropertiesSection hideSectionHeader />}
-            {activeTab === 'documentManagement' && <FileDisplayRulesSection hideSectionHeader />}
-          </Suspense>
-        </SectionErrorBoundary>
-      </div>
+              {activeTab === 'templates' && <TemplatesSection hideSectionHeader />}
+              {activeTab === 'properties' && <DocumentPropertiesSection hideSectionHeader />}
+              {activeTab === 'documentManagement' && <FileDisplayRulesSection hideSectionHeader />}
+            </Suspense>
+          </SectionErrorBoundary>
+        </div>
+      </SettingsTabGroup>
     </div>
   );
 }
diff --git a/app/flowix-web/features/preferences/sections/pi-cloud-models-section.test.tsx b/app/flowix-web/features/preferences/sections/pi-cloud-models-section.test.tsx
new file mode 100644
index 000000000..9271224cf
--- /dev/null
+++ b/app/flowix-web/features/preferences/sections/pi-cloud-models-section.test.tsx
@@ -0,0 +1,66 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { PiCloudModelsSection } from './pi-cloud-models-section';
+
+const mocks = vi.hoisted(() => ({
+  getAiCreditBalance: vi.fn(),
+  refreshPiModelProvider: vi.fn(),
+  connectPiModelProvider: vi.fn(),
+  listPiModels: vi.fn(),
+  refreshAgentModelCatalog: vi.fn(),
+  toastError: vi.fn(),
+  toastSuccess: vi.fn(),
+}));
+
+vi.mock('@platform/tauri/client', () => ({
+  cloud: {
+    getAiCreditBalance: mocks.getAiCreditBalance,
+    refreshPiModelProvider: mocks.refreshPiModelProvider,
+    connectPiModelProvider: mocks.connectPiModelProvider,
+  },
+  piModels: { list: mocks.listPiModels },
+}));
+vi.mock('@features/agent/services/agent-catalog-service', () => ({
+  refreshAgentModelCatalog: mocks.refreshAgentModelCatalog,
+}));
+vi.mock('@/lib/i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }));
+vi.mock('@/lib/toast', () => ({
+  toast: { error: mocks.toastError, success: mocks.toastSuccess },
+}));
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.getAiCreditBalance.mockResolvedValue({ balanceMicrocredits: 1_000_000 });
+  mocks.refreshPiModelProvider.mockResolvedValue(true);
+  mocks.connectPiModelProvider.mockResolvedValue(undefined);
+  mocks.listPiModels.mockResolvedValue([]);
+  mocks.refreshAgentModelCatalog.mockResolvedValue({ items: [] });
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+});
+
+it('refreshes the Cloud model catalog before reloading the local Pi catalog', async () => {
+  await act(async () => root.render(<PiCloudModelsSection authenticated />));
+  const refreshButton = Array.from(container.querySelectorAll('button')).find(
+    (button) => button.textContent?.includes('preferences.pi.cloudCreditsRefresh'),
+  );
+  expect(refreshButton).toBeDefined();
+
+  await act(async () => refreshButton!.click());
+
+  expect(mocks.refreshPiModelProvider).toHaveBeenCalledOnce();
+  expect(mocks.refreshAgentModelCatalog).toHaveBeenCalledWith('pi');
+  expect(mocks.refreshPiModelProvider.mock.invocationCallOrder[0])
+    .toBeLessThan(mocks.refreshAgentModelCatalog.mock.invocationCallOrder[0]);
+  expect(mocks.getAiCreditBalance).toHaveBeenCalledTimes(2);
+});
diff --git a/app/flowix-web/features/preferences/sections/pi-cloud-models-section.tsx b/app/flowix-web/features/preferences/sections/pi-cloud-models-section.tsx
new file mode 100644
index 000000000..d51aa44d1
--- /dev/null
+++ b/app/flowix-web/features/preferences/sections/pi-cloud-models-section.tsx
@@ -0,0 +1,136 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Loader2 } from 'lucide-react';
+import {
+  cloud,
+  piModels,
+  type PiProviderConfig,
+} from '@platform/tauri/client';
+import { cloudModelAccessErrorMessage } from '@platform/tauri/errors';
+import { errorMessage } from '@/lib/error-message';
+import { useI18n } from '@/lib/i18n';
+import { toast } from '@/lib/toast';
+import { refreshAgentModelCatalog } from '@features/agent/services/agent-catalog-service';
+import { Button } from '@shared/ui/button';
+
+const FLOWIX_CLOUD_SOURCE = 'flowix-cloud';
+
+export function PiCloudModelsSection({ authenticated }: { authenticated: boolean }) {
+  const { t } = useI18n();
+  const [providers, setProviders] = useState<PiProviderConfig[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [balance, setBalance] = useState<number | null>(null);
+  const [balanceError, setBalanceError] = useState<string | null>(null);
+  const [balanceLoading, setBalanceLoading] = useState(false);
+  const [modelCatalogLoading, setModelCatalogLoading] = useState(false);
+  const balanceRequest = useRef(0);
+
+  const reload = useCallback(async () => {
+    setError(null);
+    try {
+      setProviders(await piModels.list());
+    } catch (value) {
+      setError(errorMessage(value));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => { void reload(); }, [reload]);
+
+  const refreshBalance = useCallback(async (notifyError = false) => {
+    const request = ++balanceRequest.current;
+    if (!authenticated) {
+      setBalance(null);
+      setBalanceError(null);
+      setBalanceLoading(false);
+      return;
+    }
+    setBalanceLoading(true);
+    try {
+      const result = await cloud.getAiCreditBalance();
+      if (request !== balanceRequest.current) return;
+      setBalance(Math.ceil(result.balanceMicrocredits / 1_000_000));
+      setBalanceError(null);
+    } catch (value) {
+      if (request !== balanceRequest.current) return;
+      const message = errorMessage(value);
+      setBalanceError(message);
+      if (notifyError) toast.error(message);
+    } finally {
+      if (request === balanceRequest.current) setBalanceLoading(false);
+    }
+  }, [authenticated]);
+
+  useEffect(() => {
+    void refreshBalance();
+    return () => { balanceRequest.current += 1; };
+  }, [refreshBalance]);
+
+  const refreshBalanceAndModels = useCallback(async () => {
+    setModelCatalogLoading(true);
+    try {
+      const refreshModels = async () => {
+        await cloud.refreshPiModelProvider();
+        await refreshAgentModelCatalog('pi');
+      };
+      const [, modelCatalogResult] = await Promise.allSettled([
+        refreshBalance(true),
+        refreshModels(),
+      ]);
+      if (modelCatalogResult.status === 'rejected') {
+        toast.error(errorMessage(modelCatalogResult.reason));
+      }
+    } finally {
+      setModelCatalogLoading(false);
+    }
+  }, [refreshBalance]);
+
+  const provider = providers.find((item) => item.source === FLOWIX_CLOUD_SOURCE);
+  const connect = async () => {
+    setBusy(true);
+    try {
+      await cloud.connectPiModelProvider();
+      await reload();
+      await refreshAgentModelCatalog('pi');
+      toast.success(t('preferences.pi.cloudConnected'));
+    } catch (value) {
+      toast.error(cloudModelAccessErrorMessage(value, t));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div className="space-y-3">
+      <div className="text-sm font-medium text-[var(--foreground)]">{t('preferences.pi.cloudTitle')}</div>
+      <section className="space-y-3 rounded-xl border border-[var(--border)] bg-[var(--card)] p-4">
+        {!provider && <div className="flex justify-end">
+          <Button type="button" variant="outline" className="h-8" disabled={!authenticated || loading || busy} onClick={() => void connect()}>
+            {(loading || busy) && <Loader2 className="mr-2 size-3.5 flowix-spin" />}
+            {t('preferences.pi.cloudConnect')}
+          </Button>
+        </div>}
+
+        {error && <p className="text-xs text-[var(--destructive)]">{error}</p>}
+
+        {authenticated && <div className="flex flex-wrap items-center justify-between gap-2">
+          <div className="text-sm text-[var(--foreground)]" title={balanceError ?? undefined}>
+            {t('preferences.pi.cloudCreditsBalance')}: <span className="font-semibold">
+              {balance === null
+                ? balanceLoading ? t('preferences.pi.cloudCreditsLoading') : t('preferences.pi.cloudCreditsUnavailable')
+                : `${balance.toLocaleString('zh-CN', { maximumFractionDigits: 0 })} ${t('preferences.pi.cloudCreditsUnit')}`}
+            </span>
+          </div>
+          <Button type="button" variant="ghost" className="h-8" disabled={balanceLoading || modelCatalogLoading} onClick={() => void refreshBalanceAndModels()}>
+            {(balanceLoading || modelCatalogLoading) && <Loader2 className="mr-2 size-3.5 flowix-spin" />}
+            {t('preferences.pi.cloudCreditsRefresh')}
+          </Button>
+        </div>}
+      </section>
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/preferences/sections/pi-mcp-settings.tsx b/app/flowix-web/features/preferences/sections/pi-mcp-settings.tsx
index 620ad91c4..c95cd1875 100644
--- a/app/flowix-web/features/preferences/sections/pi-mcp-settings.tsx
+++ b/app/flowix-web/features/preferences/sections/pi-mcp-settings.tsx
@@ -10,6 +10,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@
 import { Field, FIELD_INPUT_CLASS, SectionHeader } from '@features/preferences/sections/primitives';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 
 type Transport = 'stdio' | 'http';
 type Draft = {
@@ -118,37 +119,37 @@ export function PiMcpSettings() {
   const form = draft && (
     <fieldset disabled={busy} className="m-0 min-w-0 space-y-3 rounded-xl border border-[var(--divider)] bg-[var(--card)] p-3">
       <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
-        <Field title={t('preferences.pi.mcp.name')}>
-          <Input className={fieldClass} value={draft.name} disabled={Boolean(draft.original.command || draft.original.url)} onChange={(event) => setDraft({ ...draft, name: event.target.value })} placeholder="filesystem" />
+        <Field title={t('preferences.pi.mcp.name')} controlId="pi-mcp-name">
+          <Input id="pi-mcp-name" className={fieldClass} value={draft.name} disabled={Boolean(draft.original.command || draft.original.url)} onChange={(event) => setDraft({ ...draft, name: event.target.value })} placeholder="filesystem" />
         </Field>
-        <Field title={t('preferences.pi.mcp.transport')}>
+        <Field title={t('preferences.pi.mcp.transport')} controlId="pi-mcp-transport">
           <Select value={draft.transport} onValueChange={(transport) => setDraft({ ...draft, transport: transport as Transport })}>
-            <SelectTrigger className={fieldClass}><SelectValue /></SelectTrigger>
+            <SelectTrigger id="pi-mcp-transport" className={fieldClass}><SelectValue /></SelectTrigger>
             <SelectContent><SelectItem value="stdio">stdio</SelectItem><SelectItem value="http">Streamable HTTP</SelectItem></SelectContent>
           </Select>
         </Field>
       </div>
       {draft.transport === 'stdio' ? <>
-        <Field title={t('preferences.pi.mcp.command')}><Input className={fieldClass} value={draft.command} onChange={(event) => setDraft({ ...draft, command: event.target.value })} placeholder="npx" /></Field>
-        <Field title={t('preferences.pi.mcp.args')} description={t('preferences.pi.mcp.argsHint')}><textarea className={`${fieldClass} min-h-20 w-full resize-y rounded-md p-2 font-mono text-xs`} value={draft.args} onChange={(event) => setDraft({ ...draft, args: event.target.value })} placeholder={'-y\n@modelcontextprotocol/server-filesystem\n.'} /></Field>
+        <Field title={t('preferences.pi.mcp.command')} controlId="pi-mcp-command"><Input id="pi-mcp-command" className={fieldClass} value={draft.command} onChange={(event) => setDraft({ ...draft, command: event.target.value })} placeholder="npx" /></Field>
+        <Field title={t('preferences.pi.mcp.args')} controlId="pi-mcp-args" description={t('preferences.pi.mcp.argsHint')}><textarea id="pi-mcp-args" className={`${fieldClass} min-h-20 w-full resize-y rounded-md p-2 font-mono text-xs`} value={draft.args} onChange={(event) => setDraft({ ...draft, args: event.target.value })} placeholder={'-y\n@modelcontextprotocol/server-filesystem\n.'} /></Field>
         <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
-          <Field title={t('preferences.pi.mcp.env')}><textarea className={`${fieldClass} min-h-20 w-full resize-y rounded-md p-2 font-mono text-xs`} value={draft.env} onChange={(event) => setDraft({ ...draft, env: event.target.value })} placeholder={t('preferences.pi.mcp.envHint')} /></Field>
-          <Field title={t('preferences.pi.mcp.cwd')}><Input className={fieldClass} value={draft.cwd} onChange={(event) => setDraft({ ...draft, cwd: event.target.value })} placeholder="/path/to/project" /></Field>
+          <Field title={t('preferences.pi.mcp.env')} controlId="pi-mcp-env"><textarea id="pi-mcp-env" className={`${fieldClass} min-h-20 w-full resize-y rounded-md p-2 font-mono text-xs`} value={draft.env} onChange={(event) => setDraft({ ...draft, env: event.target.value })} placeholder={t('preferences.pi.mcp.envHint')} /></Field>
+          <Field title={t('preferences.pi.mcp.cwd')} controlId="pi-mcp-cwd"><Input id="pi-mcp-cwd" className={fieldClass} value={draft.cwd} onChange={(event) => setDraft({ ...draft, cwd: event.target.value })} placeholder="/path/to/project" /></Field>
         </div>
       </> : <>
-        <Field title={t('preferences.pi.mcp.url')}><Input className={fieldClass} value={draft.url} onChange={(event) => setDraft({ ...draft, url: event.target.value })} placeholder="https://example.com/mcp" /></Field>
-        <Field title={t('preferences.pi.mcp.headers')} description={t('preferences.pi.mcp.headersHint')}><textarea className={`${fieldClass} min-h-20 w-full resize-y rounded-md p-2 font-mono text-xs`} value={draft.headers} onChange={(event) => setDraft({ ...draft, headers: event.target.value })} /></Field>
+        <Field title={t('preferences.pi.mcp.url')} controlId="pi-mcp-url"><Input id="pi-mcp-url" className={fieldClass} value={draft.url} onChange={(event) => setDraft({ ...draft, url: event.target.value })} placeholder="https://example.com/mcp" /></Field>
+        <Field title={t('preferences.pi.mcp.headers')} controlId="pi-mcp-headers" description={t('preferences.pi.mcp.headersHint')}><textarea id="pi-mcp-headers" className={`${fieldClass} min-h-20 w-full resize-y rounded-md p-2 font-mono text-xs`} value={draft.headers} onChange={(event) => setDraft({ ...draft, headers: event.target.value })} /></Field>
       </>}
       <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
-        <Field title={t('preferences.pi.mcp.exposure')}>
+        <Field title={t('preferences.pi.mcp.exposure')} controlId="pi-mcp-exposure">
           <Select value={draft.exposure} onValueChange={(exposure) => setDraft({ ...draft, exposure })}>
-            <SelectTrigger className={fieldClass}><SelectValue /></SelectTrigger>
+            <SelectTrigger id="pi-mcp-exposure" className={fieldClass}><SelectValue /></SelectTrigger>
             <SelectContent><SelectItem value="codemode">codemode</SelectItem><SelectItem value="deferred">deferred</SelectItem><SelectItem value="direct">direct</SelectItem><SelectItem value="hidden">hidden</SelectItem></SelectContent>
           </Select>
         </Field>
-        <Field title={t('preferences.pi.mcp.serverDescription')}><Input className={fieldClass} value={draft.description} onChange={(event) => setDraft({ ...draft, description: event.target.value })} /></Field>
+        <Field title={t('preferences.pi.mcp.serverDescription')} controlId="pi-mcp-server-description"><Input id="pi-mcp-server-description" className={fieldClass} value={draft.description} onChange={(event) => setDraft({ ...draft, description: event.target.value })} /></Field>
       </div>
-      <label className="flex items-center gap-2 text-sm text-[var(--foreground)]"><input type="checkbox" checked={draft.enabled} onChange={(event) => setDraft({ ...draft, enabled: event.target.checked })} />{t('preferences.pi.mcp.enabled')}</label>
+      <div className="flex items-center gap-2 text-sm text-[var(--foreground)]"><FlowixCheckbox checked={draft.enabled} disabled={busy} aria-label={t('preferences.pi.mcp.enabled')} onCheckedChange={(enabled) => setDraft({ ...draft, enabled })} /><span className={busy ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'} onClick={() => { if (!busy) setDraft({ ...draft, enabled: !draft.enabled }); }}>{t('preferences.pi.mcp.enabled')}</span></div>
       <div className="flex justify-end gap-2"><Button type="button" variant="outline" className="h-8" onClick={() => setDraft(null)}>{t('preferences.pi.cancel')}</Button><Button type="button" className="h-8" disabled={busy} onClick={() => void save()}>{t('preferences.pi.save')}</Button></div>
     </fieldset>
   );
@@ -160,7 +161,7 @@ export function PiMcpSettings() {
         <Button type="button" variant="outline" className="h-8 shrink-0 gap-1" disabled={busy || Boolean(draft)} onClick={() => setDraft(draftFrom())}><Plus className="size-3.5" />{t('preferences.pi.mcp.add')}</Button>
       </div>
       {error && <p role="alert" className="text-sm text-[var(--destructive)]">{error}</p>}
-      {loading && <div className="flex justify-center py-5"><Loader2 className="size-5 animate-spin" /></div>}
+      {loading && <div className="flex justify-center py-5"><Loader2 className="size-5 flowix-spin" /></div>}
       {!loading && !error && servers.length === 0 && !draft && <div className="rounded-lg border border-dashed border-[var(--divider)] px-4 py-5 text-center text-sm text-[var(--muted-foreground)]">{t('preferences.pi.mcp.empty')}</div>}
       <div className="space-y-2">
         {servers.map((server) => <article key={server.name} className="flex items-center gap-2 rounded-xl border border-[var(--divider)] bg-[var(--card)] p-3">
diff --git a/app/flowix-web/features/preferences/sections/pi.tsx b/app/flowix-web/features/preferences/sections/pi.tsx
index b98dad228..23dc5232e 100644
--- a/app/flowix-web/features/preferences/sections/pi.tsx
+++ b/app/flowix-web/features/preferences/sections/pi.tsx
@@ -15,11 +15,13 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@
 import { Field, SectionHeader, FIELD_INPUT_CLASS } from '@features/preferences/sections/primitives';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
+import { useAgentDataStore } from '@features/agent/store/agent-data-store';
 import { PiMcpSettings } from '@features/preferences/sections/pi-mcp-settings';
+import { useCloudAccountState } from '@features/preferences/hooks/use-cloud-account-state';
 
 type Draft = Omit<PiProviderConfig, 'credentialConfigured'>;
 const CUSTOM_PROVIDER = '__pi_custom_provider__';
+const FLOWIX_CLOUD_SOURCE = 'flowix-cloud';
 const FALLBACK_APIS = ['openai-completions', 'openai-responses', 'anthropic-messages'];
 const API_LABELS: Record<string, string> = {
   'openai-completions': 'OpenAI Chat Completions',
@@ -33,6 +35,7 @@ const API_LABELS: Record<string, string> = {
   'mistral-conversations': 'Mistral Conversations',
   'pi-messages': 'Pi Messages',
 };
+
 const PREFERENCES_SELECT_CONTENT_CLASS = 'flowix-preferences-select-content';
 const PROVIDER_FORM_FIELD_CLASS = 'space-y-[3px]';
 const PROVIDER_FORM_CONTROL_CLASS = `${FIELD_INPUT_CLASS} !bg-[color-mix(in_srgb,var(--muted)_50%,var(--card))]`;
@@ -76,6 +79,8 @@ function modelsFromDraft(value: string, existing: PiModelEntryConfig[]): PiModel
 
 export function PiSettingsSection() {
   const { t } = useI18n();
+  const { state: cloudState } = useCloudAccountState();
+  const cloudAuthenticated = Boolean(cloudState?.authenticated);
   const [providers, setProviders] = useState<PiProviderConfig[]>([]);
   const [draft, setDraft] = useState<Draft | null>(null);
   const [providerTemplateId, setProviderTemplateId] = useState(CUSTOM_PROVIDER);
@@ -90,13 +95,11 @@ export function PiSettingsSection() {
   const [error, setError] = useState<string | null>(null);
   const [providerCatalog, setProviderCatalog] = useState<PiModelCatalog | null>(null);
   const [providerCatalogError, setProviderCatalogError] = useState<string | null>(null);
-  const [features, setFeatures] = useState({ codeMode: false, toolSearch: false });
-  const codeMode = useAgentAccessStore((state) =>
-    state.config.defaults?.runtime?.pi?.piCodeMode ?? false,
-  );
-  const agentAccessLoaded = useAgentAccessStore((state) => state.hasLoaded);
-  const agentAccessError = useAgentAccessStore((state) => state.loadError);
-  const reloadAgentAccess = useAgentAccessStore((state) => state.loadInitial);
+  const [features, setFeatures] = useState({ toolSearch: false });
+  const codeMode = useAgentDataStore((state) => state.agents.pi.user.mode === 'code');
+  const modeLoad = useAgentDataStore((state) => state.loadState.piMode);
+  const modeLoaded = modeLoad.status === 'ready';
+  const initializePiMode = useAgentDataStore((state) => state.initializePiMode);
   const [featuresLoading, setFeaturesLoading] = useState(true);
   const [featuresSaving, setFeaturesSaving] = useState(false);
   const [featuresError, setFeaturesError] = useState<string | null>(null);
@@ -105,7 +108,7 @@ export function PiSettingsSection() {
     void piModels.getFeatures()
       .then((value) => {
         if (cancelled) return;
-        setFeatures(value);
+        setFeatures({ toolSearch: value.toolSearch });
       })
       .catch((error) => {
         if (!cancelled) setFeaturesError(error instanceof Error ? error.message : String(error));
@@ -114,27 +117,18 @@ export function PiSettingsSection() {
     return () => { cancelled = true; };
   }, []);
   useEffect(() => {
-    if (!agentAccessLoaded || featuresLoading || !features.codeMode) return;
-    const savedMode = useAgentAccessStore.getState().config.defaults
-      ?.runtime?.pi?.piCodeMode;
-    // Migrate the old Pi-only preference only after agent-access hydration;
-    // otherwise its late initial read could overwrite a user's new selection.
-    if (savedMode === undefined) {
-      void useAgentAccessStore.getState().setDefaultRuntime('pi', {
-        piCodeMode: true,
-      });
-    }
-  }, [agentAccessLoaded, featuresLoading, features.codeMode]);
+    void initializePiMode().catch(() => undefined);
+  }, [initializePiMode]);
   const setFeature = async (key: 'codeMode' | 'toolSearch', value: boolean) => {
     if (key === 'codeMode') {
-      if (!agentAccessLoaded) return;
-      await useAgentAccessStore.getState().setDefaultRuntime('pi', { piCodeMode: value });
+      if (!modeLoaded) return;
+      useAgentDataStore.getState().setUserPreference('pi', { mode: value ? 'code' : 'writing' });
       return;
     }
     const next = { ...features, [key]: value };
     setFeatures(next);
     setFeaturesSaving(true);
-    try { await piModels.saveFeatures({ ...next, codeMode }); }
+    try { await piModels.saveFeatures(next); }
     catch (error) {
       setFeatures(features);
       toast.error(error instanceof Error ? error.message : String(error));
@@ -148,7 +142,7 @@ export function PiSettingsSection() {
     finally { setLoading(false); }
   }, []);
 
-  useEffect(() => { void reload(); }, [reload]);
+  useEffect(() => { void reload(); }, [reload, cloudAuthenticated]);
 
   useEffect(() => {
     let cancelled = false;
@@ -168,6 +162,7 @@ export function PiSettingsSection() {
   const catalogProviders = useMemo(() => providerCatalog?.providers ?? [], [providerCatalog]);
   const compatibleProviders = catalogProviders;
   const selectedCatalogProvider = catalogProviders.find((provider) => provider.id === draft?.id);
+  const byokProviders = providers.filter((provider) => provider.source !== FLOWIX_CLOUD_SOURCE);
 
   const beginEdit = (provider?: PiProviderConfig) => {
     setEditingId(provider?.id ?? null);
@@ -313,16 +308,6 @@ export function PiSettingsSection() {
     } finally { setBusy(false); }
   };
 
-  const setDefaultModel = async (provider: PiProviderConfig, modelId: string) => {
-    setBusy(true);
-    try {
-      await piModels.save({ ...provider, apiKey: '', defaultModelId: modelId === '__none__' ? undefined : modelId });
-      await reload();
-    } catch (value) {
-      toast.error(value instanceof Error ? value.message : String(value));
-    } finally { setBusy(false); }
-  };
-
   const cancelDraft = () => {
     setDraft(null);
     setEditingId(null);
@@ -335,12 +320,12 @@ export function PiSettingsSection() {
       <div className={embedded ? 'space-y-2 rounded-xl bg-[var(--card)] p-2.5' : 'space-y-2 rounded-lg border border-[var(--divider)] bg-[var(--card)] p-2.5'}>
         <div className="flex items-center justify-between"><h3 className="text-base font-semibold text-[var(--foreground)]">{t(editingId !== null ? 'preferences.pi.edit' : 'preferences.pi.add')}</h3><Button type="button" variant="ghost" className="h-7 px-2 text-sm" onClick={cancelDraft}>{t('preferences.pi.cancel')}</Button></div>
         <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
-          <Field title={t('preferences.pi.providerCatalog')} className={PROVIDER_FORM_FIELD_CLASS}>
+          <Field title={t('preferences.pi.providerCatalog')} controlId="pi-provider-catalog" className={PROVIDER_FORM_FIELD_CLASS}>
             <Select
               value={providerTemplateId}
               onValueChange={(value) => selectCatalogProvider(value)}
             >
-              <SelectTrigger className="w-full !border-[var(--primary)]">
+              <SelectTrigger id="pi-provider-catalog" className="w-full !border-[var(--primary)]">
                 <SelectValue>
                   {providerTemplateId === CUSTOM_PROVIDER
                     ? t('preferences.pi.customProvider')
@@ -360,9 +345,9 @@ export function PiSettingsSection() {
               </p>
             )}
           </Field>
-          <Field title={t('preferences.pi.api')} className={PROVIDER_FORM_FIELD_CLASS}>
+          <Field title={t('preferences.pi.api')} controlId="pi-provider-api" className={PROVIDER_FORM_FIELD_CLASS}>
             <Select value={draft.api} onValueChange={selectApi}>
-              <SelectTrigger className="w-full !bg-[color-mix(in_srgb,var(--muted)_50%,var(--card))]"><SelectValue /></SelectTrigger>
+              <SelectTrigger id="pi-provider-api" className="w-full !bg-[color-mix(in_srgb,var(--muted)_50%,var(--card))]"><SelectValue /></SelectTrigger>
               <SelectContent align="start" fitViewport maxHeight={240} className={PREFERENCES_SELECT_CONTENT_CLASS}>
                 {(providerCatalog?.apis.length ? providerCatalog.apis : FALLBACK_APIS).map((api) => (
                   <SelectItem key={api} value={api}>{API_LABELS[api] ?? api}</SelectItem>
@@ -372,10 +357,10 @@ export function PiSettingsSection() {
           </Field>
         </div>
         <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
-          <Field title={t('preferences.pi.providerName')} className={PROVIDER_FORM_FIELD_CLASS}><Input className={PROVIDER_FORM_CONTROL_CLASS} value={draft.displayName} onChange={(event) => setDraft({ ...draft, displayName: event.target.value })} /></Field>
-          <Field title={t('preferences.pi.defaultModel')} className={PROVIDER_FORM_FIELD_CLASS}>
+          <Field title={t('preferences.pi.providerName')} controlId="pi-provider-name" className={PROVIDER_FORM_FIELD_CLASS}><Input id="pi-provider-name" className={PROVIDER_FORM_CONTROL_CLASS} value={draft.displayName} onChange={(event) => setDraft({ ...draft, displayName: event.target.value })} /></Field>
+          <Field title={t('preferences.pi.defaultModel')} controlId="pi-default-model" className={PROVIDER_FORM_FIELD_CLASS}>
             <Select value={draft.defaultModelId ?? '__none__'} onValueChange={(defaultModelId) => setDraft({ ...draft, defaultModelId: defaultModelId === '__none__' ? undefined : defaultModelId })}>
-              <SelectTrigger className="w-full !bg-[color-mix(in_srgb,var(--muted)_50%,var(--card))]"><SelectValue>{draft.defaultModelId ? parseModels(modelText).find((model) => model.id === draft.defaultModelId)?.name || draft.defaultModelId : t('preferences.pi.noDefault')}</SelectValue></SelectTrigger>
+              <SelectTrigger id="pi-default-model" className="w-full !bg-[color-mix(in_srgb,var(--muted)_50%,var(--card))]"><SelectValue>{draft.defaultModelId ? parseModels(modelText).find((model) => model.id === draft.defaultModelId)?.name || draft.defaultModelId : t('preferences.pi.noDefault')}</SelectValue></SelectTrigger>
               <SelectContent align="start" fitViewport maxHeight={240} className={PREFERENCES_SELECT_CONTENT_CLASS}>
                 {parseModels(modelText).length === 0 && <SelectItem value="__none__">{t('preferences.pi.noDefault')}</SelectItem>}
                 {parseModels(modelText).map((model) => <SelectItem key={model.id} value={model.id}>{model.name || model.id}</SelectItem>)}
@@ -383,13 +368,14 @@ export function PiSettingsSection() {
             </Select>
           </Field>
         </div>
-        <Field title={t('preferences.pi.baseUrl')} className={PROVIDER_FORM_FIELD_CLASS}><Input className={`${PROVIDER_FORM_CONTROL_CLASS} w-full sm:w-3/5`} value={draft.baseUrl} onChange={(event) => setDraft({ ...draft, baseUrl: event.target.value })} placeholder="https://api.example.com/v1" /></Field>
+        <Field title={t('preferences.pi.baseUrl')} controlId="pi-provider-base-url" className={PROVIDER_FORM_FIELD_CLASS}><Input id="pi-provider-base-url" className={`${PROVIDER_FORM_CONTROL_CLASS} w-full sm:w-3/5`} value={draft.baseUrl} onChange={(event) => setDraft({ ...draft, baseUrl: event.target.value })} placeholder="https://api.example.com/v1" /></Field>
         <Field
           title={t('preferences.pi.apiKey')}
+          controlId="pi-provider-api-key"
           description={selectedCatalogProvider?.takesApiKey === false ? t('preferences.pi.apiKeyOptional') : undefined}
           className={PROVIDER_FORM_FIELD_CLASS}
         >
-          <Input className={PROVIDER_FORM_SECRET_CLASS} type="password" autoComplete="new-password" value={draft.apiKey ?? ''} onChange={(event) => setDraft({ ...draft, apiKey: event.target.value })} placeholder={t('preferences.pi.keyPlaceholder')} />
+          <Input id="pi-provider-api-key" className={PROVIDER_FORM_SECRET_CLASS} type="password" autoComplete="new-password" value={draft.apiKey ?? ''} onChange={(event) => setDraft({ ...draft, apiKey: event.target.value })} placeholder={t('preferences.pi.keyPlaceholder')} />
         </Field>
         <div>
             <Button type="button" variant="ghost" className="h-8 w-fit justify-start gap-1 rounded-none px-0 text-sm font-medium text-[var(--foreground)] hover:bg-transparent dark:hover:!bg-transparent aria-expanded:bg-transparent aria-expanded:text-[var(--foreground)]" aria-label={`${t(modelListExpanded ? 'preferences.pi.collapseModels' : 'preferences.pi.expandModels')} ${t('preferences.pi.modelIds')}`} aria-expanded={modelListExpanded} onClick={() => setModelListExpanded((expanded) => !expanded)}>
@@ -402,7 +388,7 @@ export function PiSettingsSection() {
                   <Input className={FIELD_INPUT_CLASS} value={newModelId} onChange={(event) => setNewModelId(event.target.value)} onKeyDown={(event) => { if (event.key === 'Enter') { event.preventDefault(); addModel(); } }} placeholder={t('preferences.pi.newModelPlaceholder')} />
                   <Button type="button" size="sm" variant="outline" className="h-8 shrink-0 gap-0.5 rounded-lg" disabled={!newModelId.trim()} onClick={addModel}><Plus className="size-3.5" />{t('preferences.pi.addModel')}</Button>
                   <div className="flex shrink-0 items-center border-l border-[var(--divider)] pl-2">
-                    <Button type="button" size="sm" variant="outline" className="h-8 rounded-lg" disabled={discovering || !draft.baseUrl.trim()} onClick={() => void discoverModels()}>{discovering && <Loader2 className="mr-2 size-3.5 animate-spin" />}{t('preferences.pi.discover')}</Button>
+                    <Button type="button" size="sm" variant="outline" className="h-8 rounded-lg" disabled={discovering || !draft.baseUrl.trim()} onClick={() => void discoverModels()}>{discovering && <Loader2 className="mr-2 size-3.5 flowix-spin" />}{t('preferences.pi.discover')}</Button>
                   </div>
                 </div>
                 <div className="divide-y divide-[var(--divider)] px-1">
@@ -422,23 +408,23 @@ export function PiSettingsSection() {
               </div>
             )}
         </div>
-        <div className="flex flex-wrap items-center gap-2 pt-3"><Button type="button" variant="outline" className="h-8" onClick={cancelDraft}>{t('preferences.pi.cancel')}</Button><Button type="button" variant="outline" className="h-8" disabled={testing || modelText.trim().length === 0} onClick={() => void testConnection()}>{testing && <Loader2 className="mr-2 size-3.5 animate-spin" />}{t('preferences.pi.test')}</Button><Button type="button" className="ml-auto h-8" disabled={busy} onClick={() => void save()}>{busy && <Loader2 className="mr-2 size-3.5 animate-spin" />}{t('preferences.pi.save')}</Button></div>
+        <div className="flex flex-wrap items-center gap-2 pt-3"><Button type="button" variant="outline" className="h-8" onClick={cancelDraft}>{t('preferences.pi.cancel')}</Button><Button type="button" variant="outline" className="h-8" disabled={testing || modelText.trim().length === 0} onClick={() => void testConnection()}>{testing && <Loader2 className="mr-2 size-3.5 flowix-spin" />}{t('preferences.pi.test')}</Button><Button type="button" className="ml-auto h-8" disabled={busy} onClick={() => void save()}>{busy && <Loader2 className="mr-2 size-3.5 flowix-spin" />}{t('preferences.pi.save')}</Button></div>
       </div>
     );
   };
 
   return (
     <div className="space-y-5">
-      <SectionHeader title={t('preferences.pi.title')} description={t('preferences.pi.description')} />
-      <div className="space-y-3">
-        {loading && <div className="flex justify-center py-8"><Loader2 className="size-5 animate-spin" /></div>}
+      <section className="space-y-3">
+        <SectionHeader title={t('preferences.pi.byokTitle')} />
+        {loading && <div className="flex justify-center py-8"><Loader2 className="size-5 flowix-spin" /></div>}
         {error && <p className="text-sm text-[var(--destructive)]">{error}</p>}
-        {!loading && !error && providers.length === 0 && !draft && (
-          <div className="rounded-lg border border-dashed border-[var(--divider)] px-4 py-8 text-center text-sm text-[var(--muted-foreground)]">
-            {t('preferences.pi.empty')}
+        {!loading && !error && byokProviders.length === 0 && !draft && (
+          <div className="rounded-lg border border-dashed border-[var(--divider)] px-4 py-6 text-center text-sm text-[var(--muted-foreground)]">
+            {t('preferences.pi.byokEmpty')}
           </div>
         )}
-        {providers.map((provider) => (
+        {byokProviders.map((provider) => (
           <article key={provider.id} className={`rounded-xl border border-[var(--divider)] ${draft && editingId === provider.id ? '' : 'bg-[var(--card)] p-2.5'}`}>
             {draft && editingId === provider.id ? renderProviderForm(true) : (
               <>
@@ -451,24 +437,33 @@ export function PiSettingsSection() {
                     <Button type="button" variant="ghost" size="icon" className="size-7 hover:text-[var(--destructive)]" aria-label={t('preferences.pi.delete')} title={t('preferences.pi.delete')} disabled={busy || Boolean(draft)} onClick={() => void remove(provider.id)}><TrashSimpleIcon className="h-4 w-4" aria-hidden="true" /></Button>
                   </div>
                 </div>
-                <div className="flex items-center justify-start gap-2">
-                  <span className="shrink-0 text-sm text-[var(--foreground)]">{t('preferences.pi.defaultModel')}</span>
-                  <Select value={provider.defaultModelId ?? '__none__'} disabled={busy || Boolean(draft)} onValueChange={(modelId) => void setDefaultModel(provider, modelId)}>
-                    <SelectTrigger className="w-[16rem]"><SelectValue>{provider.defaultModelId ? provider.models.find((model) => model.id === provider.defaultModelId)?.name || provider.defaultModelId : t('preferences.pi.noDefault')}</SelectValue></SelectTrigger>
-                    <SelectContent align="start" fitViewport maxHeight={240} className={PREFERENCES_SELECT_CONTENT_CLASS}>
-                      {provider.models.length === 0 && <SelectItem value="__none__">{t('preferences.pi.noDefault')}</SelectItem>}
-                      {provider.models.map((model) => <SelectItem key={model.id} value={model.id}>{model.name || model.id}</SelectItem>)}
-                    </SelectContent>
-                  </Select>
+                <div className="mt-2">
+                  {provider.models.length > 0 ? (
+                    <div className="flex flex-wrap gap-1.5" aria-label={t('preferences.pi.modelIds')}>
+                      {provider.models.map((model) => (
+                        <span
+                          key={model.id}
+                          className="rounded-md border border-[var(--border)] bg-[var(--background)] px-2 py-1 text-xs text-[var(--foreground)]"
+                          title={model.name && model.name !== model.id ? model.id : undefined}
+                        >
+                          {model.id === provider.defaultModelId
+                            ? t('preferences.pi.defaultModelTag', { name: model.name || model.id })
+                            : model.name || model.id}
+                        </span>
+                      ))}
+                    </div>
+                  ) : (
+                    <p className="text-xs text-[var(--muted-foreground)]">{t('preferences.pi.noModels')}</p>
+                  )}
                 </div>
               </>
             )}
           </article>
         ))}
-      </div>
 
       {draft && editingId === null && renderProviderForm()}
-      <Button type="button" variant="outline" className="h-8 gap-0.5" style={{ marginTop: '10px' }} onClick={() => beginEdit()} disabled={busy || Boolean(draft)}><Plus className="size-3.5" />{t('preferences.pi.add')}</Button>
+      <Button type="button" variant="outline" className="h-8 gap-0.5" style={{ marginTop: '10px' }} onClick={() => beginEdit()} disabled={busy || Boolean(draft)}><Plus className="size-3.5" />{t('preferences.pi.byokAdd')}</Button>
+      </section>
       <div className="space-y-5" style={{ marginTop: '36px' }}>
         <SectionHeader title={t('preferences.pi.featuresTitle')} />
         <div className="space-y-2">
@@ -479,13 +474,13 @@ export function PiSettingsSection() {
           ] as const).map(([key, label]) => (
             <div key={key} className="flex items-center justify-between gap-3 rounded-xl border border-[var(--divider)] bg-[var(--card)] p-3 text-sm">
               <span>{label}</span>
-              {key === 'codeMode' && !agentAccessLoaded ? (
-                agentAccessError ? (
+              {key === 'codeMode' && !modeLoaded ? (
+                modeLoad.error ? (
                   <div className="flex items-center gap-2">
                     <span role="alert" className="text-xs text-[var(--destructive)]">{t('preferences.agent.loadFailed')}</span>
-                    <Button type="button" variant="outline" className="h-7" onClick={() => void reloadAgentAccess()}>{t('error.retry')}</Button>
+                    <Button type="button" variant="outline" className="h-7 rounded-lg" onClick={() => void initializePiMode().catch(() => undefined)}>{t('error.retry')}</Button>
                   </div>
-                ) : <Loader2 className="size-4 animate-spin text-[var(--muted-foreground)]" />
+                ) : <Loader2 className="size-4 flowix-spin text-[var(--muted-foreground)]" />
               ) : <button
                 type="button"
                 role="switch"
diff --git a/app/flowix-web/features/preferences/sections/plugins.tsx b/app/flowix-web/features/preferences/sections/plugins.tsx
index 42861d2f5..33b210756 100644
--- a/app/flowix-web/features/preferences/sections/plugins.tsx
+++ b/app/flowix-web/features/preferences/sections/plugins.tsx
@@ -5,14 +5,18 @@ import { AlertTriangle, FolderOpen, Power, RefreshCw, ShieldCheck, ShieldQuestio
 import { dialogs, plugins, type PluginDescriptor, type PluginDiagnostic } from '@platform/tauri/client';
 import { Button } from '@shared/ui/button';
 import { SectionHeader } from './primitives';
+import { useI18n } from '@/lib/i18n';
 
 export function PluginsSection() {
+  const { t } = useI18n();
   const [items, setItems] = useState<PluginDescriptor[]>([]);
   const [diagnostics, setDiagnostics] = useState<PluginDiagnostic[]>([]);
+  const [loading, setLoading] = useState(true);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   const load = useCallback(async () => {
+    setLoading(true);
     try {
       const snapshot = await plugins.catalog();
       setItems(snapshot.plugins);
@@ -20,6 +24,8 @@ export function PluginsSection() {
       setError(null);
     } catch (loadError) {
       setError(loadError instanceof Error ? loadError.message : String(loadError));
+    } finally {
+      setLoading(false);
     }
   }, []);
 
@@ -33,9 +39,12 @@ export function PluginsSection() {
     try {
       const candidate = await plugins.validate(source);
       const capabilitySummary = candidate.permissions.length > 0
-        ? `\n\n宿主能力：${candidate.permissions.join('、')}`
+        ? t('preferences.plugins.capabilities', { capabilities: candidate.permissions.join('、') })
         : '';
-      if (!window.confirm(`安装或升级插件“${candidate.manifest.name}”吗？${capabilitySummary}`)) return;
+      if (!window.confirm(t('preferences.plugins.installConfirm', {
+        name: candidate.manifest.name,
+        capabilities: capabilitySummary,
+      }))) return;
       await plugins.install(source);
       await load();
     } catch (installError) {
@@ -59,7 +68,7 @@ export function PluginsSection() {
   };
 
   const uninstall = async (plugin: PluginDescriptor) => {
-    if (plugin.isSystem || !window.confirm(`确定卸载插件“${plugin.manifest.name}”吗？`)) return;
+    if (plugin.isSystem || !window.confirm(t('preferences.plugins.uninstallConfirm', { name: plugin.manifest.name }))) return;
     setBusy(true);
     setError(null);
     try {
@@ -75,45 +84,53 @@ export function PluginsSection() {
   return (
     <div className="space-y-6">
       <SectionHeader
-        title="插件"
-        description="插件安装在 ~/.flowix/plugin/，安装后对全部笔记本可用。"
+        title={t('preferences.plugins.title')}
+        description={t('preferences.plugins.description')}
       />
       <div className="flex gap-2">
         <Button variant="outline" size="sm" disabled={busy} onClick={() => void install()}>
-          <FolderOpen className="mr-1.5 h-4 w-4" />安装或升级插件
+          <FolderOpen className="mr-1.5 h-4 w-4" />{t('preferences.plugins.install')}
         </Button>
         <Button variant="ghost" size="sm" disabled={busy} onClick={() => void load()}>
-          <RefreshCw className="mr-1.5 h-4 w-4" />刷新
+          <RefreshCw className="mr-1.5 h-4 w-4" />{t('preferences.plugins.refresh')}
         </Button>
       </div>
       {error && <p className="rounded-md bg-[color-mix(in_oklch,var(--destructive)_10%,transparent)] p-3 text-xs text-[var(--destructive)]">{error}</p>}
-      <div className="space-y-2">
+      {loading && items.length === 0 && !error && (
+        <p className="flex h-24 items-center justify-center text-sm text-[var(--muted-foreground)]" role="status" aria-busy="true">
+          {t('preferences.plugins.loading')}
+        </p>
+      )}
+      {!loading && items.length === 0 && !error && (
+        <p className="text-sm text-[var(--muted-foreground)]">{t('preferences.plugins.empty')}</p>
+      )}
+      <div className="space-y-2" aria-busy={loading}>
         {items.map((plugin) => (
           <div key={plugin.manifest.id} className="flex items-center justify-between rounded-lg border border-[var(--divider)] bg-[var(--card)] p-3">
             <div className="min-w-0">
               <div className="flex items-center gap-2 text-sm font-medium text-[var(--foreground)]">
                 <span className="truncate">{plugin.manifest.name}</span>
-                {plugin.isSystem && <span className="rounded bg-[var(--muted)] px-1.5 py-0.5 text-[10px] text-[var(--muted-foreground)]">内置</span>}
-                {!plugin.enabled && <span className="rounded bg-[color-mix(in_oklch,var(--warning)_10%,transparent)] px-1.5 py-0.5 text-[10px] text-[var(--warning)]">已停用</span>}
+                {plugin.isSystem && <span className="rounded bg-[var(--muted)] px-1.5 py-0.5 text-[10px] text-[var(--muted-foreground)]">{t('preferences.plugins.builtIn')}</span>}
+                {!plugin.enabled && <span className="rounded bg-[color-mix(in_oklch,var(--warning)_10%,transparent)] px-1.5 py-0.5 text-[10px] text-[var(--warning)]">{t('preferences.plugins.disabled')}</span>}
                 {plugin.integrityStatus === 'verified'
-                  ? <span className="flex items-center gap-1 rounded bg-[color-mix(in_oklch,var(--success)_10%,transparent)] px-1.5 py-0.5 text-[10px] text-[var(--success)]" title="安装包文件与插件声明的 SHA-256 完整性清单一致"><ShieldCheck className="h-3 w-3" />完整性通过</span>
-                  : <span className="flex items-center gap-1 rounded bg-[var(--muted)] px-1.5 py-0.5 text-[10px] text-[var(--muted-foreground)]" title="插件未提供完整性清单"><ShieldQuestion className="h-3 w-3" />未校验</span>}
+                  ? <span className="flex items-center gap-1 rounded bg-[color-mix(in_oklch,var(--success)_10%,transparent)] px-1.5 py-0.5 text-[10px] text-[var(--success)]" title={t('preferences.plugins.integrityVerifiedHint')}><ShieldCheck className="h-3 w-3" />{t('preferences.plugins.integrityVerified')}</span>
+                  : <span className="flex items-center gap-1 rounded bg-[var(--muted)] px-1.5 py-0.5 text-[10px] text-[var(--muted-foreground)]" title={t('preferences.plugins.integrityMissingHint')}><ShieldQuestion className="h-3 w-3" />{t('preferences.plugins.integrityMissing')}</span>}
               </div>
               <p className="mt-1 truncate text-xs text-[var(--muted-foreground)]">{plugin.manifest.id} · v{plugin.manifest.version}</p>
-              <p className="mt-1 truncate text-[10px] text-[var(--muted-foreground)]">能力：{plugin.permissions.join('、')}</p>
+              <p className="mt-1 truncate text-[10px] text-[var(--muted-foreground)]">{t('preferences.plugins.capabilityLabel', { capabilities: plugin.permissions.join('、') })}</p>
             </div>
             <div className="flex items-center gap-1">
-              <Button variant="ghost" size="icon" disabled={busy || (plugin.isSystem && plugin.enabled)} onClick={() => void setEnabled(plugin)} title={plugin.enabled ? '停用插件' : '启用插件'}>
+              <Button variant="ghost" size="icon" disabled={busy || (plugin.isSystem && plugin.enabled)} onClick={() => void setEnabled(plugin)} aria-label={plugin.enabled ? t('preferences.plugins.disable') : t('preferences.plugins.enable')} title={plugin.enabled ? t('preferences.plugins.disable') : t('preferences.plugins.enable')}>
                 <Power className={`h-4 w-4 ${plugin.enabled ? 'text-[var(--success)]' : 'text-[var(--muted-foreground)]'}`} />
               </Button>
-              {!plugin.isSystem && <Button variant="ghost" size="icon" disabled={busy} onClick={() => void uninstall(plugin)} title="卸载插件" className="text-[var(--muted-foreground)] hover:bg-transparent hover:text-[var(--destructive)]"><Trash2 className="h-4 w-4" /></Button>}
+              {!plugin.isSystem && <Button variant="ghost" size="icon" disabled={busy} onClick={() => void uninstall(plugin)} aria-label={t('preferences.plugins.uninstall')} title={t('preferences.plugins.uninstall')} className="text-[var(--muted-foreground)] hover:bg-transparent hover:text-[var(--destructive)]"><Trash2 className="h-4 w-4" /></Button>}
             </div>
           </div>
         ))}
       </div>
       {diagnostics.some((item) => item.status === 'invalid') && (
         <div className="space-y-2">
-          <h3 className="flex items-center gap-2 text-sm font-medium text-[var(--warning)]"><AlertTriangle className="h-4 w-4" />加载失败</h3>
+          <h3 className="flex items-center gap-2 text-sm font-medium text-[var(--warning)]"><AlertTriangle className="h-4 w-4" />{t('preferences.plugins.invalidTitle')}</h3>
           {diagnostics.filter((item) => item.status === 'invalid').map((item) => (
             <div key={item.path} className="rounded-lg border border-[color-mix(in_oklch,var(--warning)_30%,transparent)] bg-[color-mix(in_oklch,var(--warning)_10%,transparent)] p-3">
               <p className="truncate text-xs text-[var(--foreground)]">{item.path}</p>
diff --git a/app/flowix-web/features/preferences/sections/primitives.tsx b/app/flowix-web/features/preferences/sections/primitives.tsx
index 062a9f619..040dc7528 100644
--- a/app/flowix-web/features/preferences/sections/primitives.tsx
+++ b/app/flowix-web/features/preferences/sections/primitives.tsx
@@ -59,19 +59,24 @@ export function Field({
   title,
   description,
   hint,
+  controlId,
   children,
   className,
 }: {
   title: string;
   description?: string;
   hint?: string;
+  /** Connects the visible field title to its input, select, or custom control. */
+  controlId?: string;
   children: ReactNode;
   className?: string;
 }) {
   return (
     <div className={cn('space-y-1.5', className)}>
       <div className="space-y-0.5">
-        <label className={FIELD_TITLE_CLASS}>{title}</label>
+        {controlId
+          ? <label htmlFor={controlId} className={FIELD_TITLE_CLASS}>{title}</label>
+          : <span className={FIELD_TITLE_CLASS}>{title}</span>}
         {description && <p className={FIELD_DESC_CLASS}>{description}</p>}
       </div>
       {children}
@@ -84,18 +89,23 @@ export function Field({
 export function FieldRow({
   title,
   description,
+  controlId,
   children,
   className,
 }: {
   title: string;
   description?: string;
+  /** Connects the visible row title to its input, select, or custom control. */
+  controlId?: string;
   children: ReactNode;
   className?: string;
 }) {
   return (
     <div className={cn('flex items-center justify-between gap-4', className)}>
       <div className="space-y-0.5 min-w-0">
-        <label className={FIELD_TITLE_CLASS}>{title}</label>
+        {controlId
+          ? <label htmlFor={controlId} className={FIELD_TITLE_CLASS}>{title}</label>
+          : <span className={FIELD_TITLE_CLASS}>{title}</span>}
         {description && <p className={FIELD_DESC_CLASS}>{description}</p>}
       </div>
       <div className="shrink-0">{children}</div>
diff --git a/app/flowix-web/features/preferences/sections/shortcuts.tsx b/app/flowix-web/features/preferences/sections/shortcuts.tsx
index 4aef0c610..a4774beca 100644
--- a/app/flowix-web/features/preferences/sections/shortcuts.tsx
+++ b/app/flowix-web/features/preferences/sections/shortcuts.tsx
@@ -217,7 +217,7 @@ function ShortcutRow({
           )}
         </div>
         {actionDescription && (
-          <p className="truncate text-xs text-[var(--muted-foreground)]">
+          <p className="truncate text-sm text-[var(--muted-foreground)]">
             {actionDescription}
           </p>
         )}
@@ -231,7 +231,7 @@ function ShortcutRow({
 
       <div className="flex shrink-0 items-center gap-2">
         {chordString ? (
-          <KbdChord chord={chordString} />
+          <KbdChord chord={chordString} className="!text-sm" />
         ) : (
           <span className="text-xs text-[var(--muted-foreground)]">{t('preferences.shortcuts.unbound')}</span>
         )}
@@ -240,7 +240,7 @@ function ShortcutRow({
           variant="ghost"
           size="sm"
           onClick={onEdit}
-          className="h-7 rounded-lg px-2 text-xs"
+          className="h-7 rounded-lg px-2 text-sm"
           aria-label={`${t('preferences.shortcuts.edit')} — ${actionTitle}`}
           title={t('preferences.shortcuts.edit')}
         >
diff --git a/app/flowix-web/features/preferences/sections/types.ts b/app/flowix-web/features/preferences/sections/types.ts
index c7befde81..810209667 100644
--- a/app/flowix-web/features/preferences/sections/types.ts
+++ b/app/flowix-web/features/preferences/sections/types.ts
@@ -1,33 +1,25 @@
+import type { ActiveSettingsTab as RegistryActiveSettingsTab } from '@features/preferences/preferences-tab-config';
+
 /**
- * Identifier for each settings section.
- *
- * 模型配置 (供应商 / 模型 / API Key) 现在塞在 `aiAgent` 的 Flowix 卡片
- * 里, 不再是独立 tab。 图片生成 + 视频生成合并到 `tools`。
- *
- * `imageGeneration` / `videoGeneration` / `agent` / `modelConfig` /
- * `agents` 都是旧 tab id, 现在仅作 normalizeInitialTab 的 URL 兜底。
+ * Active tab IDs come from the preferences tab registry. This file only adds
+ * the legacy identifiers that remain accepted at the route boundary.
  */
-export type SettingsTab =
-  | 'general'
+export type ActiveSettingsTab = RegistryActiveSettingsTab;
+
+/** Legacy URL identifiers accepted by PreferencesView's compatibility map. */
+export type LegacySettingsTab =
   | 'fileDisplayRules'
-  | 'format'
   | 'theme'
-  | 'noteSettings'
-  | 'shortcuts'
   | 'cli'
-  | 'mcp'
   | 'connections'
-  | 'cloudSync'
   | 'tools'
   | 'history'
-  | 'dsh'
-  | 'pi'
   | 'codex'
-  | 'aiAgent'
   | 'plugins'
-  // 旧 id, 仍在 normalizeInitialTab 里重定向使用。
   | 'agent'
   | 'agents'
   | 'modelConfig'
   | 'imageGeneration'
   | 'videoGeneration';
+
+export type SettingsTab = ActiveSettingsTab | LegacySettingsTab;
diff --git a/app/flowix-web/features/preferences/store/user-settings-store.test.ts b/app/flowix-web/features/preferences/store/user-settings-store.test.ts
index e50ccb101..edf98f41e 100644
--- a/app/flowix-web/features/preferences/store/user-settings-store.test.ts
+++ b/app/flowix-web/features/preferences/store/user-settings-store.test.ts
@@ -136,3 +136,24 @@ describe('user-settings-store · property preset sanitization', () => {
     expect(sanitized.every((field) => /^fld_[0-9a-f]{32}$/.test(field.id ?? ''))).toBe(true);
   });
 });
+
+describe('shutdown preference flush', () => {
+  it('awaits writes already dispatched by the debounce timer', async () => {
+    await useUserSettingsStore.getState().flushPending();
+    vi.useFakeTimers();
+    let finish!: () => void;
+    mockedPreferences.patch.mockImplementationOnce(() => new Promise(resolve => {
+      finish = () => resolve();
+    }));
+    try {
+      await useUserSettingsStore.getState().updateSettings({ memoListView: 'folders' });
+      await vi.advanceTimersByTimeAsync(200);
+      let settled = false;
+      const flushing = useUserSettingsStore.getState().flushPending().then(() => { settled = true; });
+      await Promise.resolve();
+      expect(settled).toBe(false);
+      finish(); await flushing;
+      expect(settled).toBe(true);
+    } finally { vi.useRealTimers(); }
+  });
+});
diff --git a/app/flowix-web/features/preferences/store/user-settings-store.ts b/app/flowix-web/features/preferences/store/user-settings-store.ts
index 96710ea86..2f0f760a2 100644
--- a/app/flowix-web/features/preferences/store/user-settings-store.ts
+++ b/app/flowix-web/features/preferences/store/user-settings-store.ts
@@ -305,12 +305,14 @@ function mergePreferencePatches(current: PreferencePatch | null, incoming: Prefe
   return merged;
 }
 
-async function writeToBackend(patch: PreferencePatch): Promise<void> {
-  try {
-    await tauriPreferences.patch(patch);
-  } catch (error) {
+const writesInFlight = new Set<Promise<void>>();
+function writeToBackend(patch: PreferencePatch): Promise<void> {
+  const write = tauriPreferences.patch(patch).then(() => undefined).catch(error => {
     logger.error('persist failed', { error });
-  }
+  });
+  writesInFlight.add(write);
+  void write.finally(() => writesInFlight.delete(write));
+  return write;
 }
 
 /** debounced flush — 拖动滑块 / 连续敲键盘时合并多次写盘 */
@@ -431,7 +433,8 @@ export const useUserSettingsStore = create<UserSettingsState>((set, get) => ({
     if (pendingPatch) {
       const toWrite = pendingPatch;
       pendingPatch = null;
-      await writeToBackend(toWrite);
+      void writeToBackend(toWrite);
     }
+    await Promise.all([...writesInFlight]);
   },
 }));
diff --git a/app/flowix-web/features/preferences/tab-pages/environment-config.tsx b/app/flowix-web/features/preferences/tab-pages/environment-config.tsx
new file mode 100644
index 000000000..f4476cffa
--- /dev/null
+++ b/app/flowix-web/features/preferences/tab-pages/environment-config.tsx
@@ -0,0 +1,8 @@
+'use client';
+
+import type { ProductInfo } from '@platform/tauri/client';
+import { EnvironmentConfigSection } from '@features/preferences/sections/environment-config';
+
+export function EnvironmentConfigPreferencesTab({ productInfo = null }: { productInfo?: ProductInfo | null }) {
+  return <EnvironmentConfigSection productInfo={productInfo} />;
+}
diff --git a/app/flowix-web/features/preferences/tab-pages/format.tsx b/app/flowix-web/features/preferences/tab-pages/format.tsx
new file mode 100644
index 000000000..323656bcd
--- /dev/null
+++ b/app/flowix-web/features/preferences/tab-pages/format.tsx
@@ -0,0 +1,31 @@
+'use client';
+
+import { lazy, Suspense } from 'react';
+import { Loader2 } from 'lucide-react';
+import { useUserSettings, useUserSettingsActions } from '@features/preferences/hooks/use-user-settings';
+import { SectionHeader } from '@features/preferences/sections/primitives';
+import { useI18n } from '@/lib/i18n';
+
+const FormatSection = lazy(() =>
+  import('@features/preferences/sections/format').then((module) => ({ default: module.FormatSection })),
+);
+
+export function FormatPreferencesTab() {
+  const { t } = useI18n();
+  const format = useUserSettings((settings) => settings.format);
+  const { updateSettings } = useUserSettingsActions();
+
+  return (
+    <Suspense fallback={(
+      <div className="flex min-h-0 flex-1 flex-col space-y-6" aria-busy="true">
+        <SectionHeader title={t('preferences.format.title')} />
+        <div className="flex flex-1 items-center justify-center" role="status" aria-label={t('preferences.general.loading')}>
+          <Loader2 className="size-6 flowix-spin text-[var(--muted-foreground)]" />
+          <span className="sr-only">{t('preferences.general.loading')}</span>
+        </div>
+      </div>
+    )}>
+      <FormatSection settings={format} updateSettings={updateSettings} />
+    </Suspense>
+  );
+}
diff --git a/app/flowix-web/features/preferences/tab-pages/general.tsx b/app/flowix-web/features/preferences/tab-pages/general.tsx
new file mode 100644
index 000000000..d3947b35e
--- /dev/null
+++ b/app/flowix-web/features/preferences/tab-pages/general.tsx
@@ -0,0 +1,21 @@
+'use client';
+
+import type { ProductInfo } from '@platform/tauri/client';
+import { GeneralSection } from '@features/preferences/sections/general';
+import { ThemeSection } from '@features/preferences/sections/theme';
+import { useUserSettings, useUserSettingsActions } from '@features/preferences/hooks/use-user-settings';
+
+export function GeneralPreferencesTab({ productInfo = null }: { productInfo?: ProductInfo | null }) {
+  const language = useUserSettings((settings) => settings.language);
+  const theme = useUserSettings((settings) => settings.theme);
+  const { updateSettings } = useUserSettingsActions();
+
+  return (
+    <GeneralSection
+      language={language}
+      productInfo={productInfo}
+      updateSettings={updateSettings}
+      afterGeneral={<ThemeSection settings={{ theme }} updateSettings={updateSettings} />}
+    />
+  );
+}
diff --git a/app/flowix-web/features/preferences/tab-pages/mcp.tsx b/app/flowix-web/features/preferences/tab-pages/mcp.tsx
new file mode 100644
index 000000000..5a78a8bf7
--- /dev/null
+++ b/app/flowix-web/features/preferences/tab-pages/mcp.tsx
@@ -0,0 +1,13 @@
+'use client';
+
+import { CliSection } from '@features/preferences/sections/cli';
+import { McpSection } from '@features/preferences/sections/mcp';
+
+export function McpPreferencesTab() {
+  return (
+    <div className="space-y-8">
+      <McpSection />
+      <CliSection />
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/shell/components/browser-column-header.test.tsx b/app/flowix-web/features/shell/components/browser-column-header.test.tsx
index 5e6eddcad..fb96bd84b 100644
--- a/app/flowix-web/features/shell/components/browser-column-header.test.tsx
+++ b/app/flowix-web/features/shell/components/browser-column-header.test.tsx
@@ -77,6 +77,7 @@ async function withHeader(
     tabs?: BrowserColumnTab[];
     onToggleMemoEditorMode?: import('./browser-column-header').BrowserColumnHeaderProps['onToggleMemoEditorMode'];
     onCloseColumn?: import('./browser-column-header').BrowserColumnHeaderProps['onCloseColumn'];
+    onOpenTabInWorkColumn?: import('./browser-column-header').BrowserColumnHeaderProps['onOpenTabInWorkColumn'];
   } = {},
 ) {
   const environment = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
@@ -93,7 +94,7 @@ async function withHeader(
   try {
     await act(async () => root.render(<BrowserColumnHeader tabs={tabs} activeTabId="one" activeSurfaceChrome="document" onSelectTab={onSelectTab}
       onCloseTab={vi.fn()} onCloseOtherTabs={vi.fn()} onCloseTabsToRight={vi.fn()}
-      onCloseAllTabs={vi.fn()} onToggleMemoEditorMode={options.onToggleMemoEditorMode ?? vi.fn()} onOpenTabInWorkColumn={vi.fn()} onReorderTab={vi.fn()}
+      onCloseAllTabs={vi.fn()} onToggleMemoEditorMode={options.onToggleMemoEditorMode ?? vi.fn()} onOpenTabInWorkColumn={options.onOpenTabInWorkColumn ?? vi.fn()} onReorderTab={vi.fn()}
       isTabMenuOpen={false} onTabMenuOpenChange={vi.fn()} onCloseColumn={options.onCloseColumn} onContextMenuOpenChange={vi.fn()}
       canCreate={false} onCreateNote={vi.fn()} onCreateAgentConversation={vi.fn()}
       isFocused={false} />));
@@ -222,13 +223,27 @@ it('ignores a stale failure after a newer keyboard selection', async () => {
   });
 });
 
-it('shows the reason why a webpage cannot be moved in its context menu', async () => {
+it('allows opening a webpage in Work from its context menu', async () => {
+  const onOpen = vi.fn();
+  await withHeader(vi.fn(), async (buttons) => {
+    await act(async () => { buttons[0].dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, clientX: 20, clientY: 20 })); });
+    const item = [...document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')]
+      .find((element) => element.textContent === 'tabWindow.context.openInWorkColumn')!;
+    expect(item.disabled).toBe(false);
+    expect(item.getAttribute('aria-describedby')).toBeNull();
+    await act(async () => item.click());
+    expect(onOpen).toHaveBeenCalledWith('one');
+  }, { onOpenTabInWorkColumn: onOpen });
+});
+
+it('keeps an unselected folder tab unavailable for Work', async () => {
   await withHeader(vi.fn(), async (buttons) => {
     await act(async () => { buttons[0].dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, clientX: 20, clientY: 20 })); });
     const explanation = document.getElementById('move-unavailable-one');
-    expect(explanation?.textContent).toBe('tabWindow.context.moveWebUnavailable');
+    expect(explanation?.textContent).toBe('tabWindow.context.moveFolderUnavailable');
     expect(document.querySelector<HTMLButtonElement>('[aria-describedby="move-unavailable-one"]')?.disabled).toBe(true);
-  });
+  }, { tabs: [{ id: 'one', title: 'folder', icon: null, target: { kind: 'file-browser', folderPath: '/book', activeFilePath: null,
+    notebookId: null, scopePath: '/book', fileTreeVisible: true, fileTreeWidth: 220 } }] });
 });
 
 it('shows the editor mode entry for Markdown file tabs and toggles its label', async () => {
diff --git a/app/flowix-web/features/shell/components/browser-column-header.tsx b/app/flowix-web/features/shell/components/browser-column-header.tsx
index 23a5c7384..3bd6de020 100644
--- a/app/flowix-web/features/shell/components/browser-column-header.tsx
+++ b/app/flowix-web/features/shell/components/browser-column-header.tsx
@@ -1,9 +1,9 @@
-import { useEffect, useMemo, useRef, useState, type DragEvent, type KeyboardEvent, type MouseEvent } from 'react';
+import { useEffect, useRef, useState, type DragEvent, type KeyboardEvent, type MouseEvent } from 'react';
 import { flushSync } from 'react-dom';
-import { Check, ChevronDown, ChevronRight, Code2, FileText, FilePlus2, Folder, Globe, MessageCirclePlus, X } from 'lucide-react';
-import { NotebookTreeFileIcon } from '@features/memo/public/shell-api';
+import { Check, ChevronDown, ChevronRight, Code2, FilePlus2, Globe, MessageCirclePlus, X } from 'lucide-react';
+import { ContentIcon, classifyFileContent } from '@features/content/public/content-api';
 import {
-  canMoveBrowserColumnTargetToWorkColumn,
+  canOpenBrowserColumnTargetInWorkColumn,
   type BrowserColumnTab,
 } from '@features/workspace/public/browser-column-api';
 import {
@@ -11,12 +11,16 @@ import {
   useDocumentEditorMode,
   useFullscreenAgentThreadCardInfo,
 } from '@features/document/public/shell-api';
-import { AgentIcon, isAgentRuntimeInstalledState, normalizeAgentRuntimeStatus, useBrowserColumnAgentHeaderModel } from '@features/agent/public/shell-api';
+import {
+  AgentIcon,
+  requestNewConversationAgentSelection,
+  useBrowserColumnAgentHeaderModel,
+} from '@features/agent/public/shell-api';
+import { useNewConversationAgentSelection } from '@features/agent/hooks/use-new-conversation-agent-selection';
 import type { BrowserColumnSurfaceChrome } from '@features/surface/public/shell-api';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
 import { cn } from '@/lib/utils';
-import { DEFAULT_AGENT_TYPE_KEY } from '@/lib/agent-types';
 import { WORK_COLUMN_TITLEBAR_GRADIENT } from './work-column-titlebar-shell';
 import {
   ContextMenu,
@@ -34,7 +38,6 @@ import {
 } from '@shared/ui/dropdown-menu';
 import { documentIdentityFromFile } from '@features/document/public/shell-api';
 import { requireFileDisplayIdentity } from '@/lib/file-display-registry';
-import { AGENT_TYPES, isAgentTypeSelectable, isAlwaysVisibleNewConversationAgent } from '@/lib/agent-types';
 import type { AgentTypeKey } from '@/types/agent';
 
 function isWindowsPlatform(): boolean {
@@ -42,29 +45,53 @@ function isWindowsPlatform(): boolean {
     && (/Windows/i.test(navigator.userAgent) || /Win/i.test(navigator.platform));
 }
 
-function tabIcon(tab: BrowserColumnTab, agentTypeKey = DEFAULT_AGENT_TYPE_KEY) {
-  if (tab.icon?.startsWith('http://') || tab.icon?.startsWith('https://')) {
-    return (
+const MAX_INLINE_TAB_ICON_LENGTH = 64 * 1024;
+
+function tabIconImageSource(icon: string | null): string | null {
+  if (!icon) return null;
+  if (/^https?:\/\//i.test(icon)) return icon;
+  if (icon.length <= MAX_INLINE_TAB_ICON_LENGTH
+    && /^data:image\/(?:svg\+xml|png|jpe?g|gif|webp|avif)(?:;[^,]*)?,/i.test(icon)) return icon;
+  return null;
+}
+
+function tabIcon(tab: BrowserColumnTab, agentTypeKey?: AgentTypeKey) {
+  if (tab.target.kind === 'agent_conversation') {
+    return agentTypeKey ? <AgentIcon typeKey={agentTypeKey} alt="" className="h-3.5 w-3.5" /> : null;
+  }
+  if (tab.target.kind === 'web') {
+    const imageSource = tabIconImageSource(tab.icon);
+    return imageSource ? (
       <span className="relative flex h-4 w-4 items-center justify-center">
         <Globe className="h-3.5 w-3.5" />
         <img
-          src={tab.icon}
+          src={imageSource}
           alt=""
           className="absolute h-3.5 w-3.5 rounded-sm"
           onError={(event) => { event.currentTarget.style.display = 'none'; }}
         />
       </span>
-    );
+    ) : <Globe className="h-3.5 w-3.5" />;
   }
-  if (tab.icon) return <span className="text-sm leading-none">{tab.icon}</span>;
-  if (tab.target.kind === 'file-browser' && !tab.target.activeFilePath) return <Folder className="h-3.5 w-3.5" />;
-  if (tab.target.kind === 'agent_conversation') {
-    return <AgentIcon typeKey={agentTypeKey} alt="" className="h-3.5 w-3.5" />;
+  if (tab.target.kind === 'media') {
+    return <ContentIcon content={{ kind: 'file', path: tab.target.filePath }} className="h-3.5 w-3.5 opacity-100" />;
+  }
+  if (tab.target.kind === 'folder-collection') {
+    return <ContentIcon content={{ kind: 'folder' }} className="h-3.5 w-3.5 opacity-100" />;
+  }
+  if (tab.target.kind === 'file-browser') {
+    if (tab.target.collectionType === 'table') {
+      return <ContentIcon content={{ kind: 'multidimensional-table' }} className="h-3.5 w-3.5 opacity-100" />;
+    }
+    if (tab.target.collectionType === 'media_library') {
+      return <ContentIcon content={{ kind: 'media-library' }} className="h-3.5 w-3.5 opacity-100" />;
+    }
+    const path = tab.target.activeFilePath;
+    if (!path) return <ContentIcon content={{ kind: 'folder' }} className="h-3.5 w-3.5 opacity-100" />;
+    if (classifyFileContent(path) === 'note') return <ContentIcon content={{ kind: 'note' }} className="h-3.5 w-3.5 opacity-100" />;
+    return <ContentIcon content={{ kind: 'file', path }} className="h-3.5 w-3.5 opacity-100" />;
   }
-  if (tab.target.kind === 'web') return <Globe className="h-3.5 w-3.5" />;
-  if (tab.target.kind === 'file-browser' && tab.target.activeFilePath?.toLowerCase().endsWith('.md'))
-    return <NotebookTreeFileIcon className="h-4 w-4" />;
-  return <FileText className="h-3.5 w-3.5" />;
+  return <ContentIcon content={{ kind: 'web' }} className="h-3.5 w-3.5 opacity-100" />;
 }
 
 function MemoEditorModeContextMenuItem({
@@ -140,20 +167,8 @@ export function BrowserColumnHeader({
 }: BrowserColumnHeaderProps) {
   const { t } = useI18n();
   const [agentTypeMenuAnchor, setAgentTypeMenuAnchor] = useState<{ left: number; top: number } | null>(null);
-  const {
-    statusByType: agentRuntimeStatusByType,
-    isChecking: agentRuntimeIsChecking,
-    conversationInstances,
-    refreshIfStale: refreshAgentRuntimeIfStale,
-  } = useBrowserColumnAgentHeaderModel();
-  const newConversationAgentTypes = useMemo(() => AGENT_TYPES.filter((type) => {
-    if (!isAgentTypeSelectable(type.key)) return false;
-    if (isAlwaysVisibleNewConversationAgent(type.key)) return true;
-    return isAgentRuntimeInstalledState(normalizeAgentRuntimeStatus(
-      agentRuntimeStatusByType[type.key],
-      agentRuntimeIsChecking,
-    ));
-  }), [agentRuntimeIsChecking, agentRuntimeStatusByType]);
+  const { conversationInstances } = useBrowserColumnAgentHeaderModel();
+  const newConversationSelection = useNewConversationAgentSelection();
   const tabButtons = useRef(new Map<string, HTMLButtonElement>());
   const selectionRequest = useRef(0);
   const activeTabIdRef = useRef(activeTabId);
@@ -206,8 +221,8 @@ export function BrowserColumnHeader({
     return title || tab.title;
   };
   const tabAgentTypeKey = (tab: BrowserColumnTab) => tab.target.kind === 'agent_conversation'
-    ? conversationInstances[tab.target.instanceId]?.agentType ?? DEFAULT_AGENT_TYPE_KEY
-    : DEFAULT_AGENT_TYPE_KEY;
+    ? conversationInstances[tab.target.instanceId]?.agentType
+    : undefined;
 
   useEffect(() => {
     if (displayedActiveTabId) {
@@ -215,15 +230,24 @@ export function BrowserColumnHeader({
     }
   }, [displayedActiveTabId]);
 
-  useEffect(() => {
-    if (agentTypeMenuAnchor) void refreshAgentRuntimeIfStale();
-  }, [agentTypeMenuAnchor, refreshAgentRuntimeIfStale]);
-
   const openAgentTypeMenu = (event: MouseEvent<HTMLButtonElement>) => {
+    const selection = requestNewConversationAgentSelection();
+    if (selection.kind === 'create') {
+      setAgentTypeMenuAnchor(null);
+      onCreateAgentConversation(selection.agentType);
+      return;
+    }
+    if (selection.kind === 'none') return;
     const rect = event.currentTarget.getBoundingClientRect();
     setAgentTypeMenuAnchor({ left: rect.right + 2, top: rect.top });
   };
 
+  useEffect(() => {
+    if (agentTypeMenuAnchor && newConversationSelection.kind !== 'choose') {
+      setAgentTypeMenuAnchor(null);
+    }
+  }, [agentTypeMenuAnchor, newConversationSelection]);
+
   const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
     let nextIndex = index;
     if (event.key === 'ArrowRight') nextIndex = Math.min(index + 1, tabs.length - 1);
@@ -273,9 +297,7 @@ export function BrowserColumnHeader({
       >
         {tabs.map((tab, index) => {
           const selected = tab.id === displayedActiveTabId;
-          const moveUnavailableReason = tab.target.kind === 'web'
-            ? t('tabWindow.context.moveWebUnavailable')
-            : tab.target.kind === 'file-browser' && !tab.target.activeFilePath
+          const workOpenUnavailableReason = tab.target.kind === 'file-browser' && !tab.target.activeFilePath
               ? t('tabWindow.context.moveFolderUnavailable')
               : null;
           // 仅激活 tab 会挂载内容，全屏卡片必然在其中 ── 全屏期间激活
@@ -351,14 +373,14 @@ export function BrowserColumnHeader({
                       alt=""
                       className="h-3.5 w-3.5 shrink-0"
                     />
-                    <span className="min-w-0 truncate">{tabFullscreen.title}</span>
+                    <span className="ml-0.5 min-w-0 truncate">{tabFullscreen.title}</span>
                   </span>
                 ) : (
                   <span className="flex min-w-0 items-center">
                     <span aria-hidden="true" className="flex h-4 w-4 shrink-0 items-center justify-center">
                       {tabIcon(tab, tabAgentTypeKey(tab))}
                     </span>
-                    <span className="min-w-0 truncate">{tabLabel(tab)}</span>
+                    <span className="ml-0.5 min-w-0 truncate">{tabLabel(tab)}</span>
                   </span>
                 )}
               </button>
@@ -419,16 +441,16 @@ export function BrowserColumnHeader({
                   className={POPUP_SEPARATOR_CLASS}
                 />
                 <ContextMenuItem
-                  aria-describedby={moveUnavailableReason ? `move-unavailable-${tab.id}` : undefined}
-                  disabled={!canMoveBrowserColumnTargetToWorkColumn(tab.target)}
+                  aria-describedby={workOpenUnavailableReason ? `move-unavailable-${tab.id}` : undefined}
+                  disabled={!canOpenBrowserColumnTargetInWorkColumn(tab.target)}
                   onClick={() => onOpenTabInWorkColumn(tab.id)}
                   className="h-7 items-center justify-start gap-0 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
                 >
                   <span className="leading-5">{t('tabWindow.context.openInWorkColumn')}</span>
                 </ContextMenuItem>
-                {moveUnavailableReason && (
+                {workOpenUnavailableReason && (
                   <p id={`move-unavailable-${tab.id}`} className="px-2 py-1 text-xs leading-5 text-[var(--muted-foreground)]">
-                    {moveUnavailableReason}
+                    {workOpenUnavailableReason}
                   </p>
                 )}
               </ContextMenuContent>
@@ -445,7 +467,7 @@ export function BrowserColumnHeader({
           </ContextMenuTrigger>
           <ContextMenuContent className="w-[180px] space-y-0.5 rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
             <ContextMenuItem
-              disabled={!canCreate}
+              disabled={!canCreate || newConversationSelection.kind === 'none'}
               onClick={onCreateNote}
               className="h-7 items-center justify-start gap-0 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
             >
@@ -486,32 +508,21 @@ export function BrowserColumnHeader({
           <DropdownMenuLabel className="flex items-center gap-1.5 px-[0.375rem] pb-[0.35rem] pt-[0.35rem] text-xs font-normal leading-[1.2] text-[var(--muted-foreground)]">
             {t('tabWindow.context.newConversation')}
           </DropdownMenuLabel>
-          {newConversationAgentTypes.map((type) => {
-            const status = normalizeAgentRuntimeStatus(
-              agentRuntimeStatusByType[type.key],
-              agentRuntimeIsChecking,
-            );
-            const showNotInstalled = isAlwaysVisibleNewConversationAgent(type.key)
-              && status.state === 'not-installed';
+          {newConversationSelection.options.map((type) => {
             const name = type.nameKey
               ? t(type.nameKey as Parameters<typeof t>[0])
               : type.name;
             return (
               <DropdownMenuItem
-                key={type.key}
+                key={type.id}
                 onClick={() => {
                   setAgentTypeMenuAnchor(null);
-                  onCreateAgentConversation(type.key);
+                  onCreateAgentConversation(type.id);
                 }}
                 className="agent-conversation-new-agent-item group h-7 items-center justify-start gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
               >
-                <AgentIcon typeKey={type.key} alt="" className="h-4 w-4 shrink-0 object-contain" />
+                <AgentIcon typeKey={type.id} alt="" className="h-4 w-4 shrink-0 object-contain" />
                 <span className="min-w-0 flex-1 truncate">{name}</span>
-                {showNotInstalled && (
-                  <span className="shrink-0 text-xs text-[var(--muted-foreground)] group-hover:text-[var(--primary-foreground)]">
-                    {t('agent.status.notInstalled')}
-                  </span>
-                )}
               </DropdownMenuItem>
             );
           })}
diff --git a/app/flowix-web/features/shell/components/browser-column.tsx b/app/flowix-web/features/shell/components/browser-column.tsx
index bf80fc425..dddde17b5 100644
--- a/app/flowix-web/features/shell/components/browser-column.tsx
+++ b/app/flowix-web/features/shell/components/browser-column.tsx
@@ -1,4 +1,5 @@
 import { ColumnResizeHandle } from './column-resize-handle';
+import { focusWorkspaceHostFromEvent } from '@features/workspace/public/host-api';
 import { useCallback, useEffect, useState } from 'react';
 import {
   closeAllBrowserColumnTabs,
@@ -6,21 +7,21 @@ import {
   closeBrowserColumnTabsToRight,
   closeOtherBrowserColumnTabs,
   hideBrowserColumn,
-  openBrowserColumnAgentConversation,
-  openBrowserColumnNotebookNote,
-  openBrowserColumnTabInMainWorkColumn,
+  openBrowserColumnTabInWorkColumn,
   registerBrowserColumnFlush,
   reorderBrowserColumnTab,
   selectBrowserColumnTab,
   useBrowserColumnFocusViewModel,
   useBrowserColumnViewModel,
 } from '@features/workspace/public/browser-column-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { BrowserColumnHeader } from './browser-column-header';
 import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
 import { createShellNote, useShellSelectedNotebook } from '@features/memo/public/shell-api';
 import { createBrowserColumnAgentConversation } from '@features/agent/public/shell-api';
 import type { AgentTypeKey } from '@/types/agent';
+import { workspaceSurfaceAppearance } from '@features/workspace/public/surface-api';
 import {
   captureLatestDocumentContent,
   getDocumentEditorMode,
@@ -31,8 +32,10 @@ import { requireFileDisplayIdentity } from '@/lib/file-display-registry';
 import {
   BrowserColumnSurfaceHost,
   getBrowserColumnSurfaceDefinition,
+  useWorkspaceSurfacePresentation,
   type BrowserColumnFlushRegistration,
   resolveBrowserColumnSurface,
+  WorkspaceSurfaceStateView,
 } from '@features/surface/public/shell-api';
 
 export interface BrowserColumnProps {
@@ -85,13 +88,17 @@ export function BrowserColumn({
     activeWebRuntime,
     activePathHasDuplicateTab,
   } = useBrowserColumnViewModel();
-  const { isFocused, focusBrowserColumn } = useBrowserColumnFocusViewModel();
+  const { isFocused } = useBrowserColumnFocusViewModel();
   const selectedNotebook = useShellSelectedNotebook();
   const handleCreateNote = useCallback(async () => {
     if (!selectedNotebook) return;
     try {
       const created = await createShellNote(selectedNotebook.id);
-      await openBrowserColumnNotebookNote(created.path, selectedNotebook.id, selectedNotebook.path);
+      await openWorkspaceSurface({
+        host: 'browser-column',
+        target: { kind: 'external', path: created.path, scopePath: selectedNotebook.path, transitionId: null },
+        options: { notebookId: selectedNotebook.id },
+      });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : t('tabWindow.createNote.failed'));
     }
@@ -100,7 +107,7 @@ export function BrowserColumn({
     if (!selectedNotebook) return;
     const instanceId = createBrowserColumnAgentConversation(typeKey, selectedNotebook.id);
     try {
-      await openBrowserColumnAgentConversation(instanceId);
+      await openWorkspaceSurface({ host: 'browser-column', target: { kind: 'agent-conversation', instanceId } });
     } catch (error) {
       toast.error(error instanceof Error ? error.message : t('tabWindow.createConversation.failed'));
     }
@@ -181,16 +188,16 @@ export function BrowserColumn({
         onToolbarCollapsedChange,
       )
     : null;
-  const activeSurfaceChrome = activeSurface
-    ? getBrowserColumnSurfaceDefinition(activeSurface).chrome
-    : 'document';
+  const activeSurfaceRuntime = useWorkspaceSurfacePresentation(activeSurface?.tabId ?? '');
+  const activeSurfaceChrome = activeSurfaceRuntime.appearance?.headerStyle
+    ?? (activeSurface ? getBrowserColumnSurfaceDefinition(activeSurface).chrome : 'document');
   return (
     <section
       data-workspace-host="browser-column"
       data-workspace-focused={isFocused ? '' : undefined}
       aria-label="浏览器列辅助工作区"
-      onPointerDown={focusBrowserColumn}
-      onFocusCapture={focusBrowserColumn}
+      onPointerDown={(event) => focusWorkspaceHostFromEvent(event, 'browser-column')}
+      onFocusCapture={(event) => focusWorkspaceHostFromEvent(event, 'browser-column')}
       className={'relative flex h-full min-w-0 shrink-0 flex-col border-l border-[var(--divider)] bg-[var(--document-bg)]'}
       style={{ width }}
     >
@@ -205,7 +212,7 @@ export function BrowserColumn({
         onCloseTabsToRight={handleCloseTabsToRight}
         onCloseAllTabs={handleCloseAllTabs}
         onToggleMemoEditorMode={handleToggleMemoEditorMode}
-        onOpenTabInWorkColumn={(tabId) => { void openBrowserColumnTabInMainWorkColumn(tabId); }}
+        onOpenTabInWorkColumn={(tabId) => { void openBrowserColumnTabInWorkColumn(tabId); }}
         onReorderTab={reorderBrowserColumnTab}
         isTabMenuOpen={isTabMenuOpen}
         onTabMenuOpenChange={setIsTabMenuOpen}
@@ -221,11 +228,14 @@ export function BrowserColumn({
           <BrowserColumnSurfaceHost
             key={activeSurface.instanceKey}
             surface={activeSurface}
+            focused={isFocused}
           />
         ) : (
-          <div className="flex h-full items-center justify-center px-8 text-center text-sm text-[var(--muted-foreground)]">
-            选择一个 tab 打开内容
-          </div>
+          <WorkspaceSurfaceStateView
+            appearance={{ ...workspaceSurfaceAppearance('file-markdown'), emptyDecoration: 'none' }}
+            state={{ status: 'empty', reason: 'no-target', message: { key: 'document.file.loading' } }}
+            messageOverride="选择一个 tab 打开内容"
+          />
         )}
       </div>
     </section>
diff --git a/app/flowix-web/features/shell/components/drag-overlay/external-file-drop-overlay.tsx b/app/flowix-web/features/shell/components/drag-overlay/external-file-drop-overlay.tsx
index 3def32869..dac105e23 100644
--- a/app/flowix-web/features/shell/components/drag-overlay/external-file-drop-overlay.tsx
+++ b/app/flowix-web/features/shell/components/drag-overlay/external-file-drop-overlay.tsx
@@ -7,8 +7,7 @@ import { errorMessage } from '@/lib/error-message';
 import { createLogger } from '@/lib/logger';
 import { useShellSelectedNotebook } from '@features/memo/public/shell-api';
 import {
-  openBrowserColumnDroppedFile,
-  openExternalTarget,
+  openWorkspaceSurface,
 } from '@features/workspace/public/shell-api';
 import { FullscreenDragOverlay } from './fullscreen-drag-overlay';
 
@@ -24,11 +23,15 @@ export function ExternalFileDropOverlay() {
     if (paths.length === 0) return;
     for (const path of paths) {
       if (destination === 'browser-column') {
-        await openBrowserColumnDroppedFile(path);
+        await openWorkspaceSurface({
+          host: 'browser-column',
+          target: { kind: 'external', path, scopePath: selectedNotebook?.path ?? null, transitionId: null },
+          options: { browserDisposition: 'open-in-column' },
+        });
       } else {
-        await openExternalTarget(path, {
-          destination: 'main-third',
-          scopePath: selectedNotebook?.path ?? null,
+        await openWorkspaceSurface({
+          host: 'main-third',
+          target: { kind: 'external', path, scopePath: selectedNotebook?.path ?? null, transitionId: null },
         });
       }
     }
diff --git a/app/flowix-web/features/shell/components/floating-prompt.tsx b/app/flowix-web/features/shell/components/floating-prompt.tsx
deleted file mode 100644
index 23944c71e..000000000
--- a/app/flowix-web/features/shell/components/floating-prompt.tsx
+++ /dev/null
@@ -1,51 +0,0 @@
-'use client';
-
-import { createPortal } from 'react-dom';
-import { X } from 'lucide-react';
-import type { ReactNode } from 'react';
-import { cn } from '@/lib/utils';
-
-/** Shared bottom-left host for non-blocking onboarding and update prompts. */
-export function FloatingPromptStack({ children }: { children: ReactNode }) {
-  return createPortal(
-    <div className="pointer-events-none fixed bottom-4 left-4 z-[130] flex max-h-[calc(100vh-2rem)] w-[calc(100vw-2rem)] max-w-[340px] flex-col gap-3">
-      {children}
-    </div>,
-    document.body,
-  );
-}
-
-export function FloatingPrompt({
-  open,
-  onClose,
-  children,
-  className,
-}: {
-  open: boolean;
-  onClose: () => void;
-  children: ReactNode;
-  className?: string;
-}) {
-  if (!open) return null;
-
-  return (
-    <section
-      role="dialog"
-      aria-modal="false"
-      className={cn(
-        'pointer-events-auto relative max-h-[calc(100vh-2rem)] w-full overflow-y-auto rounded-2xl border border-[var(--divider)] bg-[var(--card)] shadow-xl flowix-dialog-enter',
-        className,
-      )}
-    >
-      <button
-        type="button"
-        aria-label="Close"
-        onClick={onClose}
-        className="absolute right-4 top-4 z-10 rounded-md p-1 hover:bg-[var(--muted)]"
-      >
-        <X className="h-4 w-4" />
-      </button>
-      {children}
-    </section>
-  );
-}
diff --git a/app/flowix-web/features/shell/components/global-search-command.tsx b/app/flowix-web/features/shell/components/global-search-command.tsx
index d53c29307..6c9d17dd3 100644
--- a/app/flowix-web/features/shell/components/global-search-command.tsx
+++ b/app/flowix-web/features/shell/components/global-search-command.tsx
@@ -33,11 +33,10 @@ import {
   useGlobalSearchMemoViewModel,
   type Notebook,
 } from '@features/memo/public/global-search-api';
+import { useNoteStore } from '@features/memo/store';
 import { joinNotebookMemoPath } from '@/lib/path';
-import {
-  selectAndOpenAgentConversation,
-  selectNotebook,
-} from '@features/workspace/public/search-navigation-api';
+import { selectNotebook } from '@features/workspace/public/search-navigation-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import {
   AgentIcon,
   getConversationRunSummary,
@@ -359,7 +358,7 @@ function RunningAgentConversationsGroup({ onClose }: RunningAgentConversationsGr
 
   const openRunningInstance = async (instance: AgentConversationInstance) => {
     prepareAgentConversationSelection(instance);
-    await selectAndOpenAgentConversation(instance.instanceId);
+    await openWorkspaceSurface({ target: { kind: 'agent-conversation', instanceId: instance.instanceId } });
     onClose();
   };
 
@@ -380,7 +379,7 @@ function RunningAgentConversationsGroup({ onClose }: RunningAgentConversationsGr
           >
             <span className="flex h-5 w-5 shrink-0 items-center justify-center rounded-full border border-[var(--border)] p-0.5 agent-runtime-list__icon--running">
               <AgentIcon
-                typeKey={agent.key}
+                typeKey={agent.id}
                 alt=""
                 className="h-full w-full object-contain"
               />
@@ -504,7 +503,6 @@ function StaticGroups({ onClose }: StaticGroupsProps) {
     activeFilter,
     setActiveFilter,
     createNote,
-    loadNotes,
     setSelectedTagId,
   } = useGlobalSearchMemoViewModel();
 
@@ -581,7 +579,7 @@ function StaticGroups({ onClose }: StaticGroupsProps) {
     if (!selectedNotebook) return;
     try {
       const created = await notes.createFromTemplate(template.id, selectedNotebook.id);
-      await loadNotes({ notebookId: selectedNotebook.id });
+      useNoteStore.getState().upsertCreatedNote(created);
       void openNotebookNote(created.path, selectedNotebook);
     } catch (err) {
       logger.error('create from template failed', { error: err });
diff --git a/app/flowix-web/features/shell/components/list-column-content.tsx b/app/flowix-web/features/shell/components/list-column-content.tsx
index 563228374..aecc04dbc 100644
--- a/app/flowix-web/features/shell/components/list-column-content.tsx
+++ b/app/flowix-web/features/shell/components/list-column-content.tsx
@@ -3,15 +3,13 @@
 import type { ReactNode } from 'react';
 
 import { MemoListViewTabs, type MemoListViewTab } from '@features/memo/components/memo-list-view-tabs';
-import { useI18n } from '@/lib/i18n';
-import { ListSurfaceLoadingState } from '@shared/ui/list-surface';
+import { ListColumnGuideCard } from '@features/shell/components/list-column-guide-card';
 
 interface ListColumnContentProps {
   activeView: MemoListViewTab;
   onViewChange: (view: MemoListViewTab) => void;
   navigationDrawerOpen: boolean;
   onToggleNavigationDrawer: () => void;
-  conversationLoading: boolean;
   children: ReactNode;
 }
 
@@ -21,11 +19,8 @@ export function ListColumnContent({
   onViewChange,
   navigationDrawerOpen,
   onToggleNavigationDrawer,
-  conversationLoading,
   children,
 }: ListColumnContentProps) {
-  const { t } = useI18n();
-
   return (
     <div className="relative h-full min-h-0 bg-[var(--list-bg)]">
       <div className="absolute left-3 top-0 z-30">
@@ -38,12 +33,7 @@ export function ListColumnContent({
         />
       </div>
       <div className="absolute inset-0">{children}</div>
-      {conversationLoading && (
-        <ListSurfaceLoadingState
-          label={t('status.agent.loadingConversations')}
-          className="pointer-events-none absolute inset-0 z-20"
-        />
-      )}
+      <ListColumnGuideCard activeView={activeView} onViewChange={onViewChange} />
     </div>
   );
 }
diff --git a/app/flowix-web/features/shell/components/list-column-guide-card.tsx b/app/flowix-web/features/shell/components/list-column-guide-card.tsx
new file mode 100644
index 000000000..43683305c
--- /dev/null
+++ b/app/flowix-web/features/shell/components/list-column-guide-card.tsx
@@ -0,0 +1,168 @@
+'use client';
+
+import {
+  useState,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+} from 'react';
+import { ChevronLeft, ChevronRight, X } from 'lucide-react';
+
+import { useI18n, type I18nKey } from '@/lib/i18n';
+import type { MemoListViewTab } from '@features/memo/components/memo-list-view-tabs';
+
+const DISMISSED_KEY = 'flowix:list-column-guide:dismissed:v1';
+
+const PAGES = [
+  {
+    view: 'folders',
+    title: 'memo.guide.fileTree.title',
+    description: 'memo.guide.fileTree.description',
+  },
+  {
+    view: 'cards',
+    title: 'memo.guide.notes.title',
+    description: 'memo.guide.notes.description',
+  },
+  {
+    view: 'conversations',
+    title: 'memo.guide.conversations.title',
+    description: 'memo.guide.conversations.description',
+  },
+] satisfies ReadonlyArray<{
+  view: MemoListViewTab;
+  title: I18nKey;
+  description: I18nKey;
+}>;
+
+function actionButtonHandlers(action: () => void) {
+  return {
+    onPointerDown: (event: ReactPointerEvent<HTMLButtonElement>) => {
+      if (event.isPrimary === false || event.button !== 0) return;
+      action();
+    },
+    onClick: (event: ReactMouseEvent<HTMLButtonElement>) => {
+      if (event.detail === 0) action();
+    },
+  };
+}
+
+function wasDismissed() {
+  if (typeof window === 'undefined') return false;
+  try {
+    return window.localStorage.getItem(DISMISSED_KEY) === 'true';
+  } catch {
+    return false;
+  }
+}
+
+function rememberDismissed() {
+  try {
+    window.localStorage.setItem(DISMISSED_KEY, 'true');
+  } catch {
+    // Keep the guide dismissible when storage is unavailable.
+  }
+}
+
+export function ListColumnGuideCard({
+  activeView,
+  onViewChange,
+}: {
+  activeView: MemoListViewTab;
+  onViewChange: (view: MemoListViewTab) => void;
+}) {
+  const { t } = useI18n();
+  const [dismissed, setDismissed] = useState(wasDismissed);
+  const pageIndex = PAGES.findIndex(({ view }) => view === activeView);
+  const page = PAGES[pageIndex];
+
+  const dismiss = () => {
+    rememberDismissed();
+    setDismissed(true);
+  };
+
+  const selectPage = (index: number) => {
+    onViewChange(PAGES[index].view);
+  };
+
+  const goToNextPage = () => {
+    if (pageIndex === PAGES.length - 1) {
+      dismiss();
+      return;
+    }
+    selectPage(pageIndex + 1);
+  };
+
+  if (dismissed) return null;
+
+  return (
+    <div className="pointer-events-none absolute inset-x-0 bottom-3 z-40 flex justify-center px-3">
+      <section
+        aria-label={t('memo.guide.ariaLabel')}
+        className="pointer-events-auto w-full max-w-[360px] rounded-2xl border border-[var(--border-popup)] bg-[color-mix(in_oklch,var(--card)_96%,transparent)] p-3.5 backdrop-blur-xl"
+      >
+        <div className="mb-2 flex items-center justify-between gap-3">
+          <h2 className="min-w-0 text-[15px] font-semibold leading-5 tracking-[-0.02em] text-[var(--foreground)]">
+            {t(page.title)}
+          </h2>
+          <button
+            type="button"
+            aria-label={t('memo.guide.close')}
+            title={t('memo.guide.close')}
+            {...actionButtonHandlers(dismiss)}
+            className="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] transition-colors hover:bg-[color-mix(in_oklch,var(--foreground)_7%,transparent)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+          >
+            <X className="h-3.5 w-3.5" />
+          </button>
+        </div>
+
+        <div aria-live="polite" aria-atomic="true" className="min-h-[36px]">
+          <p className="text-sm leading-5 text-[var(--foreground)]">
+            {t(page.description)}
+          </p>
+        </div>
+
+        <div className="mt-2 flex items-center justify-between">
+          <div
+            role="group"
+            aria-label={t('memo.guide.pageStatus', { current: pageIndex + 1, total: PAGES.length })}
+            className="flex items-center gap-1.5"
+          >
+            {PAGES.map((entry, index) => (
+              <button
+                key={entry.title}
+                type="button"
+                aria-label={t('memo.guide.goToPage', { page: index + 1 })}
+                aria-current={index === pageIndex ? 'step' : undefined}
+                {...actionButtonHandlers(() => selectPage(index))}
+                className="group inline-flex h-5 items-center justify-center focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+              >
+                <span className={`h-1.5 rounded-full transition-all ${index === pageIndex ? 'w-4 bg-[var(--primary)]' : 'w-1.5 bg-[color-mix(in_oklch,var(--foreground)_20%,transparent)] group-hover:bg-[var(--primary)]'}`} />
+              </button>
+            ))}
+          </div>
+
+          <div className="flex items-center gap-1.5">
+            {pageIndex > 0 && (
+              <button
+                type="button"
+                {...actionButtonHandlers(() => selectPage(pageIndex - 1))}
+                className="inline-flex h-8 items-center gap-1 rounded-lg px-2 text-xs font-medium text-[var(--muted-foreground)] transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+              >
+                <ChevronLeft className="h-3.5 w-3.5" />
+                {t('memo.guide.previous')}
+              </button>
+            )}
+            <button
+              type="button"
+              {...actionButtonHandlers(goToNextPage)}
+              className="inline-flex h-8 items-center rounded-lg bg-[var(--primary)] px-3 text-xs font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--card)]"
+            >
+              {t(pageIndex === PAGES.length - 1 ? 'memo.guide.done' : 'memo.guide.next')}
+              {pageIndex < PAGES.length - 1 && <ChevronRight className="h-3.5 w-3.5" />}
+            </button>
+          </div>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/shell/components/list-column.tsx b/app/flowix-web/features/shell/components/list-column.tsx
index 6d0ff25a2..30afdae66 100644
--- a/app/flowix-web/features/shell/components/list-column.tsx
+++ b/app/flowix-web/features/shell/components/list-column.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useRef, type ReactNode } from 'react';
+import { useEffect, useRef, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react';
 
 import type { Notebook } from '@features/memo/store/note-store';
 import { MemoListTitlebarMac } from '@features/memo/components/memo-list-titlebar-mac';
@@ -23,7 +23,7 @@ interface ListColumnProps {
   onOpenPreferences: (tab?: string) => void;
   onPreviewEnter: () => void;
   onPreviewLeave: () => void;
-  onPointerDown: () => void;
+  onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
   children: ReactNode;
 }
 
diff --git a/app/flowix-web/features/shell/components/main-prompt-host.tsx b/app/flowix-web/features/shell/components/main-prompt-host.tsx
deleted file mode 100644
index 5d4cf21b7..000000000
--- a/app/flowix-web/features/shell/components/main-prompt-host.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-import type { DshRuntimeInstallerState } from '@features/preferences/public/system-api';
-import type { AppUpdaterState } from '@features/shell/public/system-api';
-import { DshInstallPrompt } from '@features/preferences/public/dsh-install-prompt';
-import { FloatingPromptStack } from '@features/shell/components/floating-prompt';
-import { AppUpdatePrompt } from '@features/shell/components/prompts/app-update-prompt';
-import { NavigationFailurePrompt } from '@features/shell/components/prompts/navigation-failure-prompt';
-
-export interface MainPromptHostProps {
-  updater: AppUpdaterState;
-  dshInstallPromptOpen: boolean;
-  dshInstaller: DshRuntimeInstallerState;
-  onCloseDshInstallPrompt(): void;
-  onDshIntroDisplayed(): void;
-  onDshInstalled(): void;
-}
-
-export function MainPromptHost({
-  updater,
-  dshInstallPromptOpen,
-  dshInstaller,
-  onCloseDshInstallPrompt,
-  onDshIntroDisplayed,
-  onDshInstalled,
-}: MainPromptHostProps) {
-  return (
-    <FloatingPromptStack>
-      <NavigationFailurePrompt />
-      <AppUpdatePrompt updater={updater} />
-      <DshInstallPrompt
-        open={dshInstallPromptOpen}
-        installer={dshInstaller}
-        onClose={onCloseDshInstallPrompt}
-        onIntroDisplayed={onDshIntroDisplayed}
-        onInstalled={onDshInstalled}
-      />
-    </FloatingPromptStack>
-  );
-}
-
diff --git a/app/flowix-web/features/shell/components/main-status-bar-host.tsx b/app/flowix-web/features/shell/components/main-status-bar-host.tsx
index 167fae2cd..d8a3af512 100644
--- a/app/flowix-web/features/shell/components/main-status-bar-host.tsx
+++ b/app/flowix-web/features/shell/components/main-status-bar-host.tsx
@@ -1,4 +1,3 @@
-import type { DshDownloadProgress } from '@platform/tauri/client';
 import { windows } from '@platform/tauri/client';
 import type { Notebook } from '@features/memo/public/shell-api';
 import type { AppUpdaterState } from '@features/shell/public/system-api';
@@ -13,7 +12,6 @@ export interface MainStatusBarHostProps {
   onOpenTagPanel(): void;
   productIntroOpen: boolean;
   onProductIntroOpenChange(open: boolean): void;
-  dshDownload: DshDownloadProgress | null;
   updater: AppUpdaterState;
 }
 
@@ -22,7 +20,6 @@ export function MainStatusBarHost(props: MainStatusBarHostProps) {
     <StatusBar
       {...props}
       onOpenMcpPreferences={() => windows.openPreferences('mcp')}
-      onOpenDshPreferences={() => windows.openPreferences('dsh')}
     />
   );
 }
diff --git a/app/flowix-web/features/shell/components/notebook-delete-dialog.tsx b/app/flowix-web/features/shell/components/notebook-delete-dialog.tsx
index 41e76495e..c9ab9c036 100644
--- a/app/flowix-web/features/shell/components/notebook-delete-dialog.tsx
+++ b/app/flowix-web/features/shell/components/notebook-delete-dialog.tsx
@@ -9,6 +9,7 @@ import {
 } from '@shared/ui/dialog';
 import { useI18n } from '@/lib/i18n';
 import { useState } from 'react';
+import { FlowixCheckbox } from '@shared/ui/flowix-checkbox';
 
 interface NotebookDeleteDialogProps {
   /** When non-null, the dialog is open and confirming will delete this notebook. */
@@ -38,15 +39,14 @@ export function NotebookDeleteDialog({ target, onCancel, onConfirm }: NotebookDe
           <DialogDescription>{t('notebook.delete.description')}</DialogDescription>
         </DialogHeader>
         <div className="mt-4 flex items-center justify-between gap-3">
-          <label className="flex cursor-pointer items-center gap-2 text-sm text-[var(--foreground)]">
-            <input
-              type="checkbox"
+          <div className="flex items-center gap-2 text-sm text-[var(--foreground)]">
+            <FlowixCheckbox
               checked={deleteLocalFiles}
-              onChange={(event) => setDeleteLocalFiles(event.currentTarget.checked)}
-              className="h-4 w-4 accent-[var(--brand)]"
+              aria-label={t('notebook.delete.deleteLocalFiles')}
+              onCheckedChange={setDeleteLocalFiles}
             />
-            {t('notebook.delete.deleteLocalFiles')}
-          </label>
+            <span className="cursor-pointer" onClick={() => setDeleteLocalFiles((checked) => !checked)}>{t('notebook.delete.deleteLocalFiles')}</span>
+          </div>
           <div className="flex shrink-0 justify-end gap-2">
             <button
               type="button"
diff --git a/app/flowix-web/features/shell/components/prompts/app-update-prompt.tsx b/app/flowix-web/features/shell/components/prompts/app-update-prompt.tsx
deleted file mode 100644
index dca42fe16..000000000
--- a/app/flowix-web/features/shell/components/prompts/app-update-prompt.tsx
+++ /dev/null
@@ -1,102 +0,0 @@
-import { useEffect, useState } from 'react';
-import { ArrowUp, Loader2 } from 'lucide-react';
-import ReactMarkdown from 'react-markdown';
-import remarkGfm from 'remark-gfm';
-import { useI18n } from '@/lib/i18n';
-import { Button } from '@shared/ui/button';
-import { DialogHeader, DialogTitle } from '@shared/ui/dialog';
-import { UpdateProgress } from '@shared/ui/update-progress';
-import { FloatingPrompt } from '@features/shell/components/floating-prompt';
-import type { AppUpdaterState } from '@features/shell/public/system-api';
-
-export function AppUpdatePrompt({ updater }: { updater: AppUpdaterState }) {
-  const { t } = useI18n();
-  const [dismissedVersion, setDismissedVersion] = useState<string | null>(null);
-  const [installError, setInstallError] = useState(false);
-  const [isCancelling, setIsCancelling] = useState(false);
-  const update = updater.update;
-  const isDownloading = updater.status === 'downloading';
-  const isInstalling = updater.status === 'installing';
-  const isUpdating = isDownloading || isInstalling;
-
-  useEffect(() => {
-    if (update?.version && update.version !== dismissedVersion) setInstallError(false);
-  }, [dismissedVersion, update?.version]);
-
-  if (!update || !update.notify || (updater.status !== 'available' && !isUpdating) || update.version === dismissedVersion) {
-    return null;
-  }
-
-  const handleInstall = async () => {
-    setInstallError(false);
-    try {
-      await updater.installNow();
-    } catch {
-      setInstallError(true);
-    }
-  };
-
-  const handleCancel = async () => {
-    if (isCancelling) return;
-    setIsCancelling(true);
-    try {
-      if (isUpdating) await updater.cancelNow();
-      setDismissedVersion(update.version);
-    } finally {
-      setIsCancelling(false);
-    }
-  };
-
-  const downloadPercent = updater.progress?.phase === 'progress' && updater.progress.contentLength
-    ? Math.min(100, Math.round((updater.progress.downloadedBytes / updater.progress.contentLength) * 100))
-    : null;
-
-  return (
-    <FloatingPrompt open onClose={() => void handleCancel()} className="p-0">
-      <div className="px-5 py-5 text-left">
-        <DialogHeader className="mb-0">
-          <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-[color-mix(in_oklch,var(--primary)_12%,transparent)] text-[var(--primary)]">
-            <ArrowUp className="h-7 w-7" aria-hidden="true" />
-          </div>
-          <DialogTitle className="mt-3 text-base">
-            {t('appUpdates.available')} v{update.version.replace(/^v/i, '')}
-          </DialogTitle>
-        </DialogHeader>
-        <div className="mt-1 max-h-48 overflow-y-auto text-xs leading-5 text-[var(--muted-foreground)]">
-          <ReactMarkdown
-            remarkPlugins={[remarkGfm]}
-            components={{
-              p: ({ children }) => <p className="mb-1 last:mb-0">{children}</p>,
-              ul: ({ children }) => <ul className="my-1 list-disc space-y-0.5 pl-5">{children}</ul>,
-              ol: ({ children }) => <ol className="my-1 list-decimal space-y-0.5 pl-5">{children}</ol>,
-              li: ({ children }) => <li className="pl-0.5">{children}</li>,
-            }}
-          >
-            {update.body || t('appUpdates.description')}
-          </ReactMarkdown>
-        </div>
-        {isUpdating && updater.progress && (
-          <UpdateProgress
-            className="mt-5"
-            value={{
-              percent: downloadPercent,
-              downloadedBytes: updater.progress.phase === 'progress' ? updater.progress.downloadedBytes : undefined,
-              totalBytes: updater.progress.phase === 'progress' ? updater.progress.contentLength : undefined,
-            }}
-            label={t(isDownloading ? 'appUpdates.downloading' : 'appUpdates.installing')}
-          />
-        )}
-        {installError && <p className="mt-3 text-xs text-[var(--destructive)]">{t('appUpdates.installFailed')}</p>}
-        <div className="mt-6 flex justify-end gap-2">
-          <Button type="button" variant="outline" onClick={() => void handleCancel()} disabled={isCancelling}>
-            {t('dialog.cancel')}
-          </Button>
-          <Button type="button" onClick={() => void handleInstall()} disabled={isUpdating}>
-            {isUpdating && <Loader2 className="h-4 w-4 animate-spin" />}
-            {isDownloading ? t('appUpdates.downloading') : isInstalling ? t('appUpdates.installing') : t('appUpdates.install')}
-          </Button>
-        </div>
-      </div>
-    </FloatingPrompt>
-  );
-}
diff --git a/app/flowix-web/features/shell/components/prompts/navigation-failure-prompt.tsx b/app/flowix-web/features/shell/components/prompts/navigation-failure-prompt.tsx
deleted file mode 100644
index d4558a421..000000000
--- a/app/flowix-web/features/shell/components/prompts/navigation-failure-prompt.tsx
+++ /dev/null
@@ -1,55 +0,0 @@
-import { useEffect, useState } from 'react';
-import { Loader2 } from 'lucide-react';
-import { useI18n } from '@/lib/i18n';
-import { Button } from '@shared/ui/button';
-import { FloatingPrompt } from '@features/shell/components/floating-prompt';
-import {
-  dismissNavigationFailure,
-  retryLastNavigation,
-  useWorkspaceNavigationFailure,
-} from '@features/workspace/public/main-window-api';
-
-export function NavigationFailurePrompt() {
-  const { t } = useI18n();
-  const failure = useWorkspaceNavigationFailure();
-  const [retrying, setRetrying] = useState(false);
-
-  useEffect(() => {
-    setRetrying(false);
-  }, [failure?.requestId]);
-
-  const handleRetry = async () => {
-    if (!failure || retrying) return;
-    setRetrying(true);
-    try {
-      await retryLastNavigation();
-    } catch {
-      // The coordinator publishes the new failure; keep this prompt open.
-    } finally {
-      setRetrying(false);
-    }
-  };
-
-  return (
-    <FloatingPrompt
-      open={failure !== null}
-      onClose={dismissNavigationFailure}
-      className="p-4 pr-12"
-    >
-      <div className="space-y-3">
-        <div>
-          <div className="text-sm font-semibold text-[var(--foreground)]">
-            {t('shell.navigation.failed')}
-          </div>
-          <div className="mt-1 break-words text-xs text-[var(--muted-foreground)]">
-            {failure?.message}
-          </div>
-        </div>
-        <Button type="button" size="sm" disabled={retrying} onClick={() => void handleRetry()}>
-          {retrying ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : null}
-          {t('error.retry')}
-        </Button>
-      </div>
-    </FloatingPrompt>
-  );
-}
diff --git a/app/flowix-web/features/shell/components/status-bar/notebook-selector-popup.tsx b/app/flowix-web/features/shell/components/status-bar/notebook-selector-popup.tsx
index c2ac9e376..6a5580232 100644
--- a/app/flowix-web/features/shell/components/status-bar/notebook-selector-popup.tsx
+++ b/app/flowix-web/features/shell/components/status-bar/notebook-selector-popup.tsx
@@ -2,23 +2,17 @@
 
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { ChevronsUpDown, MoreVertical, Pencil, Plus, Trash2, X } from 'lucide-react';
+import { ChevronsUpDown, Plus } from 'lucide-react';
+import { PencilSimpleIcon, StarIcon, TrashSimpleIcon } from '@phosphor-icons/react';
 import { Popover, PopoverContent, PopoverTrigger } from '@shared/ui/popover';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@shared/ui/dropdown-menu';
 import { notebooks as notebooksClient } from '@platform/tauri/client';
 import { NotebookIcon } from '@features/memo/components/notebook-icon';
+import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
+import { Button } from '@shared/ui/button';
 import { useNoteStore, type Notebook } from '@features/memo/store/note-store';
 import { cn } from '@/lib/utils';
 import { toast } from '@/lib/toast';
 import { useI18n } from '@/lib/i18n';
-import { WindowsTitlebarControls } from '@shared/window-titlebar-controls';
-import { isMac } from '@features/shortcuts';
-import { OnboardingTitlebarMac } from '@features/onboarding/onboarding-titlebar-mac';
 
 export interface NotebookSelectorPopupProps {
   open: boolean;
@@ -57,12 +51,12 @@ interface PointerState {
 }
 
 interface DragGeometry {
-  cardRects: Map<string, DOMRect>;
+  itemRects: Map<string, DOMRect>;
   viewportRect: DOMRect | null;
 }
 
 const DRAG_THRESHOLD_PX = 4;
-const NOTEBOOK_CARD_SIZE_CLASS = 'h-[165px] w-[144px] shrink-0';
+const NOTEBOOK_ITEM_CLASS = 'w-full shrink-0';
 
 function reorderNotebookIds(
   notebooks: Notebook[],
@@ -108,62 +102,76 @@ export function NotebookSelectorPopup({
 }: NotebookSelectorPopupProps) {
   const { t } = useI18n();
   const reorderNotebooks = useNoteStore((state) => state.reorderNotebooks);
-  const cardRefs = useRef(new Map<string, HTMLDivElement>());
-  const listViewportRef = useRef<HTMLElement>(null);
-  const previousCardRectsRef = useRef(new Map<string, DOMRect>());
-  const cardAnimationsRef = useRef(new Map<string, Animation>());
+  const itemRefs = useRef(new Map<string, HTMLDivElement>());
+  const listViewportRef = useRef<HTMLDivElement>(null);
+  const previousItemRectsRef = useRef(new Map<string, DOMRect>());
+  const itemAnimationsRef = useRef(new Map<string, Animation>());
   const pointerRef = useRef<PointerState | null>(null);
   const dragGeometryRef = useRef<DragGeometry | null>(null);
   const refreshRequestRef = useRef(0);
   const pendingAfterCloseRef = useRef<(() => void) | null>(null);
+  const searchComposingRef = useRef(false);
   const [draggingId, setDraggingId] = useState<string | null>(null);
   const [dropTarget, setDropTarget] = useState<DropTarget | null>(null);
   const [ghost, setGhost] = useState<PointerState | null>(null);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [filterQuery, setFilterQuery] = useState('');
+  const normalizedSearchQuery = filterQuery.trim().toLocaleLowerCase();
   const notebooksById = useMemo(
     () => new Map(notebooks.map((notebook) => [notebook.id, notebook] as const)),
     [notebooks],
   );
   const previewNotebookIds = useMemo(
-    () => draggingId
-      ? reorderNotebookIds(notebooks, draggingId, dropTarget)
-      : notebooks.map((notebook) => notebook.id),
-    [draggingId, dropTarget, notebooks],
+    () => {
+      if (normalizedSearchQuery) {
+        return notebooks
+          .filter((notebook) => (
+            notebook.name.toLocaleLowerCase().includes(normalizedSearchQuery) ||
+            notebook.path.toLocaleLowerCase().includes(normalizedSearchQuery)
+          ))
+          .map((notebook) => notebook.id);
+      }
+      return draggingId
+        ? reorderNotebookIds(notebooks, draggingId, dropTarget)
+        : notebooks.map((notebook) => notebook.id);
+    },
+    [draggingId, dropTarget, notebooks, normalizedSearchQuery],
   );
 
   useLayoutEffect(() => {
     const nextRects = new Map<string, DOMRect>();
-    for (const [id, card] of cardRefs.current) {
-      const activeAnimation = cardAnimationsRef.current.get(id);
-      const visualRect = activeAnimation ? card.getBoundingClientRect() : null;
+    for (const [id, item] of itemRefs.current) {
+      const activeAnimation = itemAnimationsRef.current.get(id);
+      const visualRect = activeAnimation ? item.getBoundingClientRect() : null;
       activeAnimation?.cancel();
-      cardAnimationsRef.current.delete(id);
-      const nextRect = card.getBoundingClientRect();
+      itemAnimationsRef.current.delete(id);
+      const nextRect = item.getBoundingClientRect();
       nextRects.set(id, nextRect);
-      const previousRect = visualRect ?? previousCardRectsRef.current.get(id);
-      if (!previousRect || typeof card.animate !== 'function') continue;
+      const previousRect = visualRect ?? previousItemRectsRef.current.get(id);
+      if (!previousRect || typeof item.animate !== 'function') continue;
       const deltaX = previousRect.left - nextRect.left;
       const deltaY = previousRect.top - nextRect.top;
       if (Math.abs(deltaX) < 1 && Math.abs(deltaY) < 1) continue;
-      const animation = card.animate(
+      const animation = item.animate(
         [
           { transform: `translate3d(${deltaX}px, ${deltaY}px, 0)` },
           { transform: 'translate3d(0, 0, 0)' },
         ],
         { duration: 180, easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)' },
       );
-      cardAnimationsRef.current.set(id, animation);
+      itemAnimationsRef.current.set(id, animation);
       animation.addEventListener('finish', () => {
-        if (cardAnimationsRef.current.get(id) === animation) {
-          cardAnimationsRef.current.delete(id);
+        if (itemAnimationsRef.current.get(id) === animation) {
+          itemAnimationsRef.current.delete(id);
         }
       }, { once: true });
     }
-    previousCardRectsRef.current = nextRects;
+    previousItemRectsRef.current = nextRects;
   }, [previewNotebookIds]);
 
   useEffect(() => () => {
-    for (const animation of cardAnimationsRef.current.values()) animation.cancel();
-    cardAnimationsRef.current.clear();
+    for (const animation of itemAnimationsRef.current.values()) animation.cancel();
+    itemAnimationsRef.current.clear();
   }, []);
 
   const refreshNotebooks = useCallback(async () => {
@@ -177,6 +185,17 @@ export function NotebookSelectorPopup({
     }
   }, [onRefresh]);
 
+  const toggleNotebookPinned = useCallback(async (notebook: Notebook) => {
+    const pinned = !notebook.pinned;
+    try {
+      const updated = await notebooksClient.setPinned(notebook.id, pinned);
+      if (!updated) throw new Error('Notebook pin state was not updated');
+      await refreshNotebooks();
+    } catch {
+      toast.error(t('memo.list.notebookMenu.pinFailed'));
+    }
+  }, [refreshNotebooks, t]);
+
   useEffect(() => () => {
     refreshRequestRef.current += 1;
   }, []);
@@ -185,6 +204,14 @@ export function NotebookSelectorPopup({
     if (open) pendingAfterCloseRef.current = null;
   }, [open]);
 
+  useEffect(() => {
+    if (!open) {
+      searchComposingRef.current = false;
+      setSearchQuery('');
+      setFilterQuery('');
+    }
+  }, [open]);
+
   const closeThen = useCallback((afterClose: () => void) => {
     pendingAfterCloseRef.current = afterClose;
     onOpenChange(false);
@@ -217,7 +244,7 @@ export function NotebookSelectorPopup({
       ) {
         return null;
       }
-      const sourceRect = geometry.cardRects.get(sourceId);
+      const sourceRect = geometry.itemRects.get(sourceId);
       if (
         sourceRect &&
         x >= sourceRect.left && x <= sourceRect.right &&
@@ -230,7 +257,7 @@ export function NotebookSelectorPopup({
 
       for (const notebook of notebooks) {
         if (notebook.id === sourceId) continue;
-        const rect = geometry.cardRects.get(notebook.id);
+        const rect = geometry.itemRects.get(notebook.id);
         if (!rect) continue;
         if (
           rect.right < viewportRect.left || rect.left > viewportRect.right ||
@@ -240,7 +267,7 @@ export function NotebookSelectorPopup({
         const centerX = rect.left + rect.width / 2;
         const centerY = rect.top + rect.height / 2;
         const distance = Math.hypot(x - centerX, y - centerY);
-        const position: DropPosition = x < centerX ? 'before' : 'after';
+        const position: DropPosition = y < centerY ? 'before' : 'after';
 
         if (inside) return { id: notebook.id, position };
         if (!nearest || distance < nearest.distance) {
@@ -256,6 +283,7 @@ export function NotebookSelectorPopup({
       if (!pointer || pointer.pointerId !== event.pointerId) return;
 
       if (!pointer.dragging) {
+        if (normalizedSearchQuery) return;
         const dx = Math.abs(event.clientX - pointer.startX);
         const dy = Math.abs(event.clientY - pointer.startY);
         if (Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
@@ -316,17 +344,17 @@ export function NotebookSelectorPopup({
       window.removeEventListener('pointerup', handleUp);
       window.removeEventListener('pointercancel', handleUp);
     };
-  }, [closeThen, notebooks, onSelect, reorderNotebooks, t]);
+  }, [closeThen, notebooks, normalizedSearchQuery, onSelect, reorderNotebooks, t]);
 
   const handleCardPointerDown = (notebook: Notebook, event: React.PointerEvent<HTMLDivElement>) => {
     if (event.button !== 0 || pointerRef.current) return;
     event.preventDefault();
-    const cardRects = new Map<string, DOMRect>();
-    for (const [id, card] of cardRefs.current) {
-      cardRects.set(id, card.getBoundingClientRect());
+    const itemRects = new Map<string, DOMRect>();
+    for (const [id, item] of itemRefs.current) {
+      itemRects.set(id, item.getBoundingClientRect());
     }
     dragGeometryRef.current = {
-      cardRects,
+      itemRects,
       viewportRect: listViewportRef.current?.getBoundingClientRect() ?? null,
     };
     pointerRef.current = {
@@ -384,218 +412,220 @@ export function NotebookSelectorPopup({
         side={side}
         sideOffset={sideOffset}
         onExitComplete={handleExitComplete}
+        aria-label={t('status.notebookList')}
         className={cn(
-          'flowix-notebook-selector-popup flowix-notebook-list-screen !fixed !inset-0 !left-0 !top-0 !z-[130] !h-dvh !max-h-none !w-full !max-w-none !translate-x-0 !translate-y-0 !flex !flex-col !overflow-hidden !rounded-none !border-0 !bg-[var(--frame-bg)] !p-0 !text-[var(--foreground)] !shadow-none [--onboarding-ink:var(--foreground)] [--onboarding-subtle:var(--muted-foreground)] [--onboarding-panel:color-mix(in_oklch,var(--card)_96%,var(--background))] [--onboarding-line:color-mix(in_oklch,var(--border)_78%,transparent)]',
+          'flowix-notebook-selector-popup !z-[150] !w-[max(25vw,320px)] !max-w-[calc(100vw-1rem)] !h-[72vh] !max-h-[72vh] !flex !flex-col !overflow-hidden !rounded-xl !border-[var(--border-popup)] !bg-[var(--popover)] !p-0 !text-[var(--foreground)] !shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]',
+          side === 'bottom' && 'flowix-notebook-selector-popup--bottom',
         )}
       >
-        {isMac() && <OnboardingTitlebarMac />}
-        <WindowsTitlebarControls reserveSpace />
-        <main ref={listViewportRef} className="relative z-[1] flex min-h-0 flex-1 overflow-x-hidden overflow-y-auto overscroll-contain px-[clamp(28px,6vw,96px)] pb-[clamp(22px,3vw,44px)]">
-          <div className="mx-auto flex min-h-full w-[min(100%,914px)] flex-[1_0_auto] flex-col items-stretch overflow-visible">
-            <section className="flex min-h-full w-full flex-[1_0_auto] flex-col py-[clamp(11px,1.33vw,16px)] pb-4">
-              <div className="relative mb-4 max-w-full pr-[58px]">
-                <h1 className="text-4xl font-light leading-[0.98] tracking-[-0.065em] text-[var(--onboarding-ink)]">{t('status.notebookList')}</h1>
-                <button
-                  type="button"
-                  onClick={() => onOpenChange(false)}
-                  className="fixed right-[clamp(20px,3vw,48px)] top-[58px] z-20 inline-flex h-8 w-8 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--card)] p-0 text-[var(--muted-foreground)] shadow-sm transition-colors duration-150 hover:border-[color-mix(in_oklch,var(--border)_65%,var(--muted-foreground))] hover:text-[color-mix(in_oklch,var(--muted-foreground)_75%,var(--foreground))]"
-                  aria-label={t('common.close')}
-                  title={t('common.close')}
-                >
-                  <X className="h-4 w-4" />
-                </button>
+        <div className="shrink-0 px-2">
+          <input
+            type="search"
+            value={searchQuery}
+            onChange={(event) => {
+              const value = event.target.value;
+              setSearchQuery(value);
+              if (!searchComposingRef.current && !(event.nativeEvent as InputEvent).isComposing) {
+                setFilterQuery(value);
+              }
+            }}
+            onCompositionStart={() => { searchComposingRef.current = true; }}
+            onCompositionEnd={(event) => {
+              searchComposingRef.current = false;
+              const value = event.currentTarget.value;
+              setSearchQuery(value);
+              setFilterQuery(value);
+            }}
+            placeholder={t('status.searchNotebookPlaceholder')}
+            aria-label={t('status.searchNotebookPlaceholder')}
+            className="agent-composer__note-search flowix-notebook-selector-search !mt-0 !h-[48px] !text-[var(--foreground)]"
+          />
+        </div>
+        <OverlayScrollbar
+          className="flowix-notebook-selector-scrollbar min-h-0 flex-1"
+          scrollerRef={listViewportRef}
+          scrollerClassName="h-full min-h-0 overflow-x-hidden overflow-y-auto overscroll-contain px-2 pt-1 pb-1"
+        >
+          <div className="flex flex-col space-y-0.5">
+            {notebooks.length === 0 && (
+              <div className="px-3 py-4 text-center text-sm text-[var(--muted-foreground)]">
+                {t('status.noNotebooks')}
               </div>
-              {notebooks.length === 0 && (
-                <div className="px-3 py-8 text-center text-sm text-[var(--muted-foreground)]">
-                  {t('status.noNotebooks')}
-                </div>
-              )}
-              <div className="grid w-full grid-cols-[repeat(auto-fit,144px)] justify-center gap-[10px]">
-                <button
-                  type="button"
-                  onClick={() => closeThen(onCreateNotebook)}
+            )}
+            {notebooks.length > 0 && normalizedSearchQuery && previewNotebookIds.length === 0 && (
+              <div className="px-3 py-4 text-center text-sm text-[var(--muted-foreground)]">
+                {t('status.noMatchingNotebooks')}
+              </div>
+            )}
+            {previewNotebookIds.map((notebookId) => {
+              if (notebookId === draggingId) {
+                return (
+                  <div
+                    key={`placeholder-${notebookId}`}
+                    aria-hidden="true"
+                    className={cn(
+                      NOTEBOOK_ITEM_CLASS,
+                      'min-h-9',
+                      'flowix-notebook-drop-placeholder rounded-lg border-2 border-dashed border-[color-mix(in_oklch,var(--primary)_62%,var(--border))] bg-[color-mix(in_oklch,var(--primary)_5%,transparent)]',
+                    )}
+                  />
+                );
+              }
+
+              const notebook = notebooksById.get(notebookId);
+              if (!notebook) return null;
+              const isActive = selectedNotebook?.id === notebook.id;
+              const isMissing = Boolean(notebook.missing);
+
+              return (
+                <div
+                  key={notebook.id}
+                  ref={(element) => {
+                    if (element) itemRefs.current.set(notebook.id, element);
+                    else itemRefs.current.delete(notebook.id);
+                  }}
+                  role="button"
+                  tabIndex={0}
+                  aria-pressed={isActive}
+                  onPointerDown={(event) => handleCardPointerDown(notebook, event)}
+                  onKeyDown={(event) => handleCardKeyDown(notebook, event)}
                   className={cn(
-                    NOTEBOOK_CARD_SIZE_CLASS,
-                    'group relative flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed border-[var(--border)] bg-[var(--card)] text-[var(--muted-foreground)] transition-colors hover:border-solid hover:text-[var(--primary)]',
+                    NOTEBOOK_ITEM_CLASS,
+                    'group relative flex cursor-pointer select-none items-center gap-3 rounded-lg px-1.5 py-1 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]',
+                    isActive
+                      ? 'bg-[color-mix(in_oklch,var(--primary)_9%,var(--popover))]'
+                      : 'bg-transparent hover:bg-[var(--muted)]',
+                    isMissing && 'opacity-70',
                   )}
-                  aria-label={t('status.newNotebook')}
-                  title={t('status.newNotebook')}
+                  style={{ touchAction: 'none' }}
                 >
-                  <Plus className="h-7 w-7" />
-                  <span className="text-sm">{t('status.newNotebook')}</span>
-                </button>
-                {previewNotebookIds.map((notebookId) => {
-                  if (notebookId === draggingId) {
-                    return (
-                      <div
-                        key={`placeholder-${notebookId}`}
-                        aria-hidden="true"
-                        className={cn(
-                          NOTEBOOK_CARD_SIZE_CLASS,
-                          'flowix-notebook-drop-placeholder rounded-lg border-2 border-dashed border-[color-mix(in_oklch,var(--primary)_62%,var(--border))] bg-[color-mix(in_oklch,var(--primary)_5%,transparent)]',
-                        )}
-                      />
-                    );
-                  }
-
-                  const notebook = notebooksById.get(notebookId);
-                  if (!notebook) return null;
-                  const isActive = selectedNotebook?.id === notebook.id;
-                  const isMissing = Boolean(notebook.missing);
-
-                  return (
-                    <div
-                      key={notebook.id}
-                      ref={(element) => {
-                        if (element) cardRefs.current.set(notebook.id, element);
-                        else cardRefs.current.delete(notebook.id);
-                      }}
-                      role="button"
-                      tabIndex={0}
-                      aria-pressed={isActive}
-                      onPointerDown={(event) => handleCardPointerDown(notebook, event)}
-                      onKeyDown={(event) => handleCardKeyDown(notebook, event)}
+                  <NotebookIcon
+                    icon={notebook.icon}
+                    name={notebook.name}
+                    className={cn(
+                      'h-7 w-7 shrink-0 rounded-md text-[15px] font-semibold transition-colors duration-150',
+                      isActive
+                        ? 'bg-[color-mix(in_oklch,var(--primary)_16%,var(--muted))] !text-[var(--primary)]'
+                        : 'bg-[var(--muted)] !text-[var(--foreground)]',
+                    )}
+                    imageClassName="h-[72%] w-[72%]"
+                  />
+                  <div className="flex min-w-0 flex-1 items-center gap-2">
+                    <span
                       className={cn(
-                        NOTEBOOK_CARD_SIZE_CLASS,
-                        'group relative flex cursor-pointer select-none flex-col items-start gap-2 rounded-lg border px-3 py-3 text-left transition-[border-color,background-color,box-shadow]',
-                        isActive
-                          ? 'border-[var(--primary)]/50 bg-[color-mix(in_oklch,var(--primary)_10%,transparent)]'
-                          : 'border-[var(--border)] bg-[var(--card)] hover:border-[var(--primary)]/50 hover:bg-[var(--card)]',
-                        isMissing && 'opacity-70',
+                        'block min-w-0 flex-1 truncate text-sm',
+                        isMissing ? 'text-[var(--muted-foreground)]' : 'text-[var(--foreground)]',
                       )}
-                      style={{
-                        touchAction: 'none',
-                        ...(isActive
-                          ? {
-                              backgroundColor: 'var(--popover)',
-                              backgroundImage:
-                                'radial-gradient(ellipse 90% 145% at 100% 0%, var(--brand) 0%, color-mix(in oklch, var(--brand) 80%, transparent) 100%)',
-                            }
-                          : {}),
-                      }}
+                      title={notebook.name}
                     >
-                      <div className="flex w-full items-center justify-between">
-                        <NotebookIcon
-                          icon={notebook.icon}
-                          name={notebook.name}
-                          className={cn(
-                            'h-8 w-8 shrink-0 rounded-md text-[15px] font-semibold transition-[color,background-color,opacity,filter] duration-150',
-                            isActive
-                              ? 'bg-[color-mix(in_oklch,var(--inverse-foreground)_10%,transparent)] !text-white opacity-100'
-                              : 'bg-[var(--muted)] !text-[var(--foreground)]',
-                          )}
-                          imageClassName="h-[72%] w-[72%]"
-                        />
-                        <DropdownMenu className="shrink-0">
-                          <DropdownMenuTrigger
-                            asChild
-                            onClick={(event) => event.stopPropagation()}
-                          >
-                            <button
-                              type="button"
-                              onPointerDown={(event) => event.stopPropagation()}
-                              className={cn(
-                                'flex h-6 w-6 items-center justify-center rounded-md hover:bg-transparent',
-                                isActive
-                                  ? 'text-[var(--inverse-foreground)] hover:text-[var(--inverse-foreground)]'
-                                  : 'text-[var(--muted-foreground)] hover:text-[var(--foreground)]',
-                              )}
-                              aria-label={t('document.agent.moreActions')}
-                              title={t('document.agent.moreActions')}
-                            >
-                              <MoreVertical className="h-4 w-4 translate-x-1" />
-                            </button>
-                          </DropdownMenuTrigger>
-                          <DropdownMenuContent
-                            align="end"
-                            className="w-[132px] space-y-0.5 rounded-xl border-[var(--border-popup)] p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]"
-                          >
-                            <DropdownMenuItem
-                              onClick={() => closeThen(() => onEdit(notebook))}
-                              className="group h-7 items-center gap-2 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
-                            >
-                              <Pencil className="h-3.5 w-3.5 shrink-0" />
-                              <span>{t('common.edit')}</span>
-                            </DropdownMenuItem>
-                            <DropdownMenuItem
-                              onClick={() => closeThen(() => onDelete(notebook))}
-                              className="group h-7 items-center gap-2 rounded-lg px-2 py-0 text-left hover:bg-transparent hover:text-[var(--destructive)]"
-                            >
-                              <Trash2 className="h-3.5 w-3.5 shrink-0" />
-                              <span>{t('dialog.delete')}</span>
-                            </DropdownMenuItem>
-                          </DropdownMenuContent>
-                        </DropdownMenu>
-                      </div>
-                      <div className="mt-auto w-full space-y-1">
-                        <span
-                          className={cn(
-                            'block min-h-5 w-full min-w-0 truncate text-left text-sm font-medium',
-                            isMissing
-                              ? 'text-[var(--muted-foreground)]'
-                              : isActive
-                                ? 'text-[var(--inverse-foreground)]'
-                                : 'text-[var(--foreground)]',
-                          )}
-                          title={notebook.name}
-                        >
-                          {notebook.name}
-                          {isMissing && ` ${t('status.invalid')}`}
+                      {notebook.name}
+                      {isMissing && ` ${t('status.invalid')}`}
+                    </span>
+                    <span className="flex shrink-0 items-center gap-1 text-xs text-[var(--muted-foreground)] group-hover:hidden group-focus-within:hidden">
+                      {notebook.pinned && (
+                        <span title={t('memo.list.notebookMenu.pin')}>
+                          <StarIcon
+                            className="h-4 w-4 text-[var(--primary)]"
+                            aria-label={t('memo.list.notebookMenu.pin')}
+                            weight="fill"
+                          />
                         </span>
-                        <span
-                          className={cn(
-                            'flex items-center gap-0 text-left text-xs',
-                            isActive
-                              ? 'text-[var(--inverse-foreground)]'
-                              : 'text-[var(--muted-foreground)]',
-                          )}
-                        >
-                          {cloudSyncedNotebookIds?.has(notebook.id) && (
-                            <span className="flex h-4 w-3 shrink-0 items-center justify-center" aria-hidden="true">
-                              <span
-                                className={cn(
-                                  'h-2 w-2 rounded-full',
-                                  cloudSyncAvailable
-                                    ? 'bg-[var(--success)]'
-                                    : 'bg-[var(--muted-foreground)]',
-                                )}
-                                aria-hidden="true"
-                              />
-                            </span>
-                          )}
-                          {t('status.notebookMemoCount', { count: notebook.memoCount ?? 0 })}
+                      )}
+                      {cloudSyncedNotebookIds?.has(notebook.id) && (
+                        <span className="flex h-4 w-3 shrink-0 items-center justify-center" aria-hidden="true">
+                          <span
+                            className={cn(
+                              'h-2 w-2 rounded-full',
+                              cloudSyncAvailable ? 'bg-[var(--success)]' : 'bg-[var(--muted-foreground)]',
+                            )}
+                            aria-hidden="true"
+                          />
                         </span>
-                      </div>
-                    </div>
-                  );
-                })}
-              </div>
-            </section>
+                      )}
+                      <span className="text-sm">
+                        {notebook.memoCount === undefined ? '—' : t('status.notebookMemoCount', { count: notebook.memoCount })}
+                      </span>
+                    </span>
+                  </div>
+                  <div className="flex w-0 shrink-0 items-center justify-end gap-0.5 overflow-hidden opacity-0 transition-[width,opacity] duration-[37.5ms] group-hover:w-[76px] group-hover:opacity-100 group-focus-within:w-[76px] group-focus-within:opacity-100">
+                    <button
+                      type="button"
+                      aria-label={t(notebook.pinned ? 'memo.list.notebookMenu.unpin' : 'memo.list.notebookMenu.pin')}
+                      title={t(notebook.pinned ? 'memo.list.notebookMenu.unpin' : 'memo.list.notebookMenu.pin')}
+                      onPointerDown={(event) => event.stopPropagation()}
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        void toggleNotebookPinned(notebook);
+                      }}
+                      className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--primary)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+                    >
+                      <StarIcon className="h-4 w-4" weight={notebook.pinned ? 'fill' : 'regular'} aria-hidden="true" />
+                    </button>
+                    <button
+                      type="button"
+                      aria-label={t('common.edit')}
+                      title={t('common.edit')}
+                      onPointerDown={(event) => event.stopPropagation()}
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        closeThen(() => onEdit(notebook));
+                      }}
+                      className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+                    >
+                      <PencilSimpleIcon className="h-4 w-4" aria-hidden="true" />
+                    </button>
+                    <button
+                      type="button"
+                      aria-label={t('dialog.delete')}
+                      title={t('dialog.delete')}
+                      onPointerDown={(event) => event.stopPropagation()}
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        closeThen(() => onDelete(notebook));
+                      }}
+                      className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--destructive)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)]"
+                    >
+                      <TrashSimpleIcon className="h-4 w-4" aria-hidden="true" />
+                    </button>
+                  </div>
+                </div>
+              );
+            })}
           </div>
-        </main>
+        </OverlayScrollbar>
+        <div className="shrink-0 p-2">
+          <Button
+            type="button"
+            className="h-9 w-full border border-[var(--border)] bg-[var(--card)] text-[var(--foreground)] hover:bg-[var(--hover-bg)]"
+            onClick={() => closeThen(onCreateNotebook)}
+          >
+            <Plus />
+            {t('status.newNotebook')}
+          </Button>
+        </div>
 
         {ghost && sourceNotebook && typeof document !== 'undefined' && createPortal(
           <div
-            className="pointer-events-none fixed z-[160] flex origin-top-left flex-col items-start gap-2 rounded-lg border border-[color-mix(in_oklch,var(--primary)_70%,var(--border))] bg-[var(--popover)] px-3 py-3 opacity-95 shadow-[0_16px_40px_color-mix(in_oklch,var(--foreground)_18%,transparent)]"
+            className="pointer-events-none fixed z-[160] flex origin-top-left items-center gap-3 rounded-lg border border-[color-mix(in_oklch,var(--primary)_70%,var(--border))] bg-[var(--popover)] px-1.5 py-1 opacity-95 shadow-[0_16px_40px_color-mix(in_oklch,var(--foreground)_18%,transparent)]"
             style={{
               left: ghost.pointerX + 10,
               top: ghost.pointerY + 10,
               width: ghost.ghostRect.width,
               height: ghost.ghostRect.height,
-              transform: 'rotate(1.5deg) scale(1.02)',
+              transform: 'rotate(0.5deg) scale(1.01)',
             }}
           >
             <NotebookIcon
               icon={sourceNotebook.icon}
               name={sourceNotebook.name}
-              className="h-8 w-8 shrink-0 rounded-md bg-[color-mix(in_oklch,var(--primary)_14%,var(--muted))] text-[15px] font-semibold !text-[var(--primary)]"
+              className="h-7 w-7 shrink-0 rounded-md bg-[color-mix(in_oklch,var(--primary)_14%,var(--muted))] text-[15px] font-semibold !text-[var(--primary)]"
             />
-            <div className="mt-auto w-full space-y-1">
-              <span className="block truncate text-sm font-medium text-[var(--foreground)]">
+            <div className="min-w-0 flex-1 space-y-0.5">
+              <span className="block truncate text-sm text-[var(--foreground)]">
                 {sourceNotebook.name}
               </span>
               <span className="block text-xs text-[var(--muted-foreground)]">
-                {t('status.notebookMemoCount', { count: sourceNotebook.memoCount ?? 0 })}
+                {sourceNotebook.memoCount === undefined ? '—' : t('status.notebookMemoCount', { count: sourceNotebook.memoCount })}
               </span>
             </div>
           </div>,
diff --git a/app/flowix-web/features/shell/components/status-bar/product-update-pill.tsx b/app/flowix-web/features/shell/components/status-bar/product-update-pill.tsx
index dcb829228..2d0b92137 100644
--- a/app/flowix-web/features/shell/components/status-bar/product-update-pill.tsx
+++ b/app/flowix-web/features/shell/components/status-bar/product-update-pill.tsx
@@ -1,97 +1,73 @@
 'use client';
 
+import { ArrowCircleUpIcon } from '@phosphor-icons/react';
 import type { AppUpdaterState } from '@features/shell/hooks/use-app-updater';
 import { useI18n } from '@/lib/i18n';
-import { cn } from '@/lib/utils';
 import { toast } from '@/lib/toast';
 
-/** Compact signed-app-update CTA for the desktop status bar. */
+/** Status-bar action that installs the prepared app update. */
 export function ProductUpdatePill({ updater }: { updater: AppUpdaterState }) {
   const { t } = useI18n();
-  const { status, update, installNow } = updater;
-
-  async function handleClick() {
-    if (!update || status === 'downloading' || status === 'installing') return;
-    try {
-      await installNow();
-    } catch {
-      toast.error(t('appUpdates.installFailed'));
-    }
-  }
+  const { status, update } = updater;
 
   if (!update || !update.notify || status === 'error' || status === 'none' || status === 'idle' || status === 'checking') {
     return null;
   }
 
-  const downloading = status === 'downloading';
-  const installing = status === 'installing';
-  const contentLength = updater.progress && 'contentLength' in updater.progress
-    ? updater.progress.contentLength
-    : undefined;
-  const downloadedBytes = updater.progress && 'downloadedBytes' in updater.progress
-    ? updater.progress.downloadedBytes
-    : undefined;
-  const percent = downloading && contentLength && contentLength > 0 && downloadedBytes != null
-    ? Math.min(100, Math.max(0, Math.round((downloadedBytes / contentLength) * 100)))
-    : null;
-  const label = downloading
-    ? percent == null
-      ? t('appUpdates.statusDownloading')
-      : t('appUpdates.statusDownloadingProgress').replace('{percent}', String(percent))
-    : installing
-      ? t('appUpdates.statusInstalling')
-      : t('appUpdates.install');
+  const versionLabel = t('appUpdates.statusBarVersion', {
+    version: update.version.replace(/^v/i, ''),
+  });
+  const isUpdating = status === 'downloading' || status === 'installing';
 
   return (
     <button
       type="button"
-      onClick={handleClick}
-      disabled={downloading || installing}
-      title={`${t('appUpdates.available')}: ${update.version}`}
-      className={cn(
-        'inline-flex h-[22px] items-center gap-0.5 rounded-md px-2',
-        'text-xs leading-none text-[var(--primary)] hover:bg-[var(--muted)]',
-        'disabled:cursor-wait',
-      )}
-      aria-label={label}
+      onClick={() => {
+        void updater.installNow().catch(() => {
+          toast.error(t('appUpdates.installFailed'));
+        });
+      }}
+      disabled={isUpdating}
+      title={versionLabel}
+      className="inline-flex h-[22px] items-center justify-center gap-1 rounded-md px-2 text-xs leading-none text-[var(--primary)] hover:bg-[var(--muted)]"
+      aria-label={versionLabel}
     >
-      <UpdateProgressIcon percent={percent ?? (installing ? 100 : 0)} spinning={downloading && percent == null} />
-      <span>{label}</span>
+      {isUpdating
+        ? <DownloadProgressIcon progress={updater.progress} />
+        : <ArrowCircleUpIcon className="h-[18px] w-[18px]" weight="fill" aria-hidden="true" />}
+      <span>{versionLabel}</span>
     </button>
   );
 }
 
-function UpdateProgressIcon({ percent, spinning }: { percent: number; spinning: boolean }) {
-  const radius = 5;
+function DownloadProgressIcon({ progress }: { progress: AppUpdaterState['progress'] }) {
+  let hasProgress = false;
+  let percent = 0;
+  if (progress?.phase === 'progress' && progress.contentLength && progress.contentLength > 0) {
+    hasProgress = true;
+    percent = Math.min(1, Math.max(0, progress.downloadedBytes / progress.contentLength));
+  }
+  const radius = 9;
   const circumference = 2 * Math.PI * radius;
-  const progress = Math.min(100, Math.max(0, percent)) / 100;
 
   return (
     <svg
       aria-hidden="true"
-      className={`h-3.5 w-3.5 shrink-0${spinning ? ' animate-spin' : ''}`}
-      viewBox="0 0 12 12"
+      className={`h-[18px] w-[18px] shrink-0${hasProgress ? '' : ' flowix-spin'}`}
+      viewBox="0 0 24 24"
     >
+      <circle cx="12" cy="12" r={radius} fill="none" stroke="currentColor" strokeOpacity="0.24" strokeWidth="3" />
       <circle
-        cx="6"
-        cy="6"
-        r={radius}
-        fill="none"
-        stroke="currentColor"
-        strokeOpacity="0.25"
-        strokeWidth="1.5"
-      />
-      <circle
-        cx="6"
-        cy="6"
+        cx="12"
+        cy="12"
         r={radius}
         fill="none"
         stroke="currentColor"
         strokeLinecap="round"
-        strokeWidth="1.5"
-        strokeDasharray={circumference}
-        strokeDashoffset={circumference * (1 - progress)}
-        transform="rotate(-90 6 6)"
+        strokeWidth="3"
+        strokeDasharray={hasProgress ? circumference : `${circumference * 0.28} ${circumference * 0.72}`}
+        strokeDashoffset={hasProgress ? circumference * (1 - percent) : 0}
+        transform="rotate(-90 12 12)"
       />
     </svg>
   );
diff --git a/app/flowix-web/features/shell/components/status-bar/status-bar.tsx b/app/flowix-web/features/shell/components/status-bar/status-bar.tsx
index ddfc7572b..c0743083a 100644
--- a/app/flowix-web/features/shell/components/status-bar/status-bar.tsx
+++ b/app/flowix-web/features/shell/components/status-bar/status-bar.tsx
@@ -26,7 +26,6 @@ import {
   listenToCloudStateChanges,
   listenToCloudSyncStatusChanges,
   type CloudSyncStatus,
-  type DshDownloadProgress,
 } from '@platform/tauri/client';
 import type { AppUpdaterState } from '@features/shell/hooks/use-app-updater';
 
@@ -40,56 +39,13 @@ interface StatusBarProps {
   productIntroOpen: boolean;
   onProductIntroOpenChange: (open: boolean) => void;
   onOpenMcpPreferences: () => void;
-  onOpenDshPreferences: () => void;
-  dshDownload: DshDownloadProgress | null;
   updater: AppUpdaterState;
 }
 
-function DshDownloadProgressIcon({ percent }: { percent: number | null | undefined }) {
-  const radius = 5;
-  const circumference = 2 * Math.PI * radius;
-  const progress = percent == null ? 0.25 : Math.min(100, Math.max(0, percent)) / 100;
-
-  return (
-    <svg
-      aria-hidden="true"
-      className={`h-3.5 w-3.5 shrink-0${percent == null ? ' animate-spin' : ''}`}
-      viewBox="0 0 12 12"
-    >
-      <circle
-        cx="6"
-        cy="6"
-        r={radius}
-        fill="none"
-        stroke="currentColor"
-        strokeOpacity="0.25"
-        strokeWidth="1.5"
-      />
-      <circle
-        cx="6"
-        cy="6"
-        r={radius}
-        fill="none"
-        stroke="currentColor"
-        strokeLinecap="round"
-        strokeWidth="1.5"
-        strokeDasharray={circumference}
-        strokeDashoffset={circumference * (1 - progress)}
-        transform="rotate(-90 6 6)"
-      />
-    </svg>
-  );
-}
-
 function PiRuntimeStatusIndicator() {
   const { t } = useI18n();
   const piStatus = useAgentRuntimeStore((state) => state.statusByType.pi);
   const isChecking = useAgentRuntimeStore((state) => state.isChecking);
-  const refreshIfStale = useAgentRuntimeStore((state) => state.refreshIfStale);
-
-  useEffect(() => {
-    void refreshIfStale();
-  }, [refreshIfStale]);
 
   const runtimeStatus = normalizeAgentRuntimeStatus(piStatus, isChecking);
   const statusText = runtimeStatus.state === 'ready'
@@ -140,8 +96,6 @@ export function StatusBar({
   productIntroOpen,
   onProductIntroOpenChange,
   onOpenMcpPreferences,
-  onOpenDshPreferences,
-  dshDownload,
   updater,
 }: StatusBarProps) {
   const { t } = useI18n();
@@ -283,17 +237,6 @@ export function StatusBar({
         </button>
         <AgentConversationStatusBar />
         <div className="flex-1" />
-        {dshDownload && (
-          <button
-            type="button"
-            onClick={onOpenDshPreferences}
-            className="inline-flex h-[22px] items-center gap-0.5 rounded-md px-2 text-xs leading-none text-[var(--primary)] hover:bg-[var(--muted)]"
-            title={t('preferences.dsh.runtime.downloadProgress')}
-          >
-            <DshDownloadProgressIcon percent={dshDownload.percent} />
-            <span>{t('preferences.dsh.runtime.downloading')}</span>
-          </button>
-        )}
         <ProductUpdatePill updater={updater} />
         {cloudSyncInProgress && (
           <div
diff --git a/app/flowix-web/features/shell/components/work-column-titlebar-shell.tsx b/app/flowix-web/features/shell/components/work-column-titlebar-shell.tsx
index c0f22a7fa..55c1078cf 100644
--- a/app/flowix-web/features/shell/components/work-column-titlebar-shell.tsx
+++ b/app/flowix-web/features/shell/components/work-column-titlebar-shell.tsx
@@ -1,12 +1,11 @@
 'use client';
 
-import type { CSSProperties, MouseEvent, ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 import { isMac } from '@features/shortcuts';
 import { useI18n } from '@/lib/i18n';
 import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@shared/ui/context-menu';
 import { useWorkColumnTransferViewModel } from '@features/workspace/public/shell-api';
-import { canUseNativeContextMenu, logNativeContextMenuError, popupNativeContextMenu } from '@platform/tauri/native-context-menu';
-import { buildWorkColumnContextMenuItems } from '@features/shell/menus/work-column-context-menu';
+import { hideBrowserColumn } from '@features/workspace/public/browser-column-api';
 
 /** Shared titlebar fade used by the work column and browser-column tabs. */
 export const WORK_COLUMN_TITLEBAR_GRADIENT =
@@ -32,30 +31,12 @@ export function WorkColumnTitlebarShell({
 }: WorkColumnTitlebarShellProps) {
   const { t } = useI18n();
   const { canOpenInBrowserColumn, openInBrowserColumn } = useWorkColumnTransferViewModel();
-  const useNativeMenu = canUseNativeContextMenu();
-
-  const showNativeContextMenu = async (event: MouseEvent<HTMLDivElement>) => {
-    if (!canUseNativeContextMenu()) return;
-    try {
-      await popupNativeContextMenu(event, buildWorkColumnContextMenuItems({
-        label: t('workColumn.context.openInBrowserColumn'),
-        enabled: canOpenInBrowserColumn,
-        openInBrowserColumn: () => void openInBrowserColumn(),
-      }));
-    } catch (error) {
-      logNativeContextMenuError('work-column titlebar', error);
-    }
-  };
 
   return (
     <ContextMenu>
       <ContextMenuTrigger asChild>
         <div
           data-tauri-drag-region
-          // On Windows the shared ContextMenuTrigger must receive the event
-          // directly so it can open the web menu. Installing a no-op native
-          // handler here can prevent that fallback in the drag-region titlebar.
-          onContextMenu={useNativeMenu ? (event) => void showNativeContextMenu(event) : undefined}
           className={`z-[50] flex shrink-0 select-none items-center pl-2 ${
             isWindows
               ? `h-9 ${reserveWindowsControls ? 'pr-[126px]' : 'pr-0'}`
@@ -69,7 +50,7 @@ export function WorkColumnTitlebarShell({
           {children}
         </div>
       </ContextMenuTrigger>
-      <ContextMenuContent className="w-[180px] space-y-0.5 rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+      <ContextMenuContent className="w-[176px] space-y-0.5 rounded-xl p-1 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
         <ContextMenuItem
           disabled={!canOpenInBrowserColumn}
           onClick={() => {
@@ -79,7 +60,13 @@ export function WorkColumnTitlebarShell({
           }}
           className="h-7 items-center justify-start gap-0 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
         >
-          <span className="leading-5">{t('workColumn.context.openInBrowserColumn')}</span>
+          <span className="leading-5">{t('workColumn.context.alsoOpenInBrowserColumn')}</span>
+        </ContextMenuItem>
+        <ContextMenuItem
+          onClick={hideBrowserColumn}
+          className="h-7 items-center justify-start gap-0 rounded-lg px-2 py-0 text-left hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
+        >
+          <span className="leading-5">{t('tabWindow.closeColumn')}</span>
         </ContextMenuItem>
       </ContextMenuContent>
     </ContextMenu>
diff --git a/app/flowix-web/features/shell/hooks/use-app-updater.ts b/app/flowix-web/features/shell/hooks/use-app-updater.ts
index 15052103d..f62fa3d05 100644
--- a/app/flowix-web/features/shell/hooks/use-app-updater.ts
+++ b/app/flowix-web/features/shell/hooks/use-app-updater.ts
@@ -6,6 +6,7 @@ import {
   type AppUpdate,
   type AppUpdateDownloadProgress,
 } from '@platform/tauri/client/updater';
+import { runStartupStage3Task, waitForStartupStage3 } from '@/lib/startup-stage3';
 
 export type AppUpdaterStatus = 'idle' | 'checking' | 'none' | 'available' | 'downloading' | 'installing' | 'error';
 
@@ -35,9 +36,11 @@ export function useAppUpdater({
   const [progress, setProgress] = useState<AppUpdateDownloadProgress | null>(null);
   const [error, setError] = useState<unknown>(null);
   const updateRef = useRef<AppUpdate | null>(null);
+  const checkStartedRef = useRef(false);
   updateRef.current = update;
 
   const checkNow = useCallback(async () => {
+    checkStartedRef.current = true;
     setStatus('checking');
     setError(null);
     setProgress(null);
@@ -62,7 +65,7 @@ export function useAppUpdater({
     setError(null);
     setProgress(null);
     try {
-      await installAppUpdate((next) => {
+      await installAppUpdate(current.version, (next) => {
         setProgress(next);
         setStatus(next.phase === 'installing' ? 'installing' : 'downloading');
       });
@@ -81,13 +84,28 @@ export function useAppUpdater({
 
   useEffect(() => {
     if (!autoCheck || !enabled) return;
-    const timer = window.setTimeout(() => {
-      void checkNow().catch(() => {
-        // Automatic checks are intentionally silent. The preferences view
-        // exposes the error through its explicit check action.
-      });
-    }, delayMs);
-    return () => window.clearTimeout(timer);
+    let cancelled = false;
+    let timer: number | undefined;
+    void waitForStartupStage3().then(() => {
+      if (cancelled) return;
+      timer = window.setTimeout(() => {
+        if (cancelled) return;
+        void runStartupStage3Task('app-update-auto-check', async () => {
+          if (cancelled || checkStartedRef.current) return;
+          checkStartedRef.current = true;
+          try {
+            await checkNow();
+          } catch {
+            // Automatic checks are intentionally silent. The preferences view
+            // exposes the error through its explicit check action.
+          }
+        });
+      }, delayMs);
+    });
+    return () => {
+      cancelled = true;
+      if (timer !== undefined) window.clearTimeout(timer);
+    };
   }, [autoCheck, enabled, delayMs, checkNow]);
 
   return { status, update, progress, error, checkNow, installNow, cancelNow };
diff --git a/app/flowix-web/features/shell/hooks/use-main-middle-column-controller.tsx b/app/flowix-web/features/shell/hooks/use-main-middle-column-controller.tsx
index 47bd6446c..d63673d12 100644
--- a/app/flowix-web/features/shell/hooks/use-main-middle-column-controller.tsx
+++ b/app/flowix-web/features/shell/hooks/use-main-middle-column-controller.tsx
@@ -1,9 +1,7 @@
 import {
   lazy,
   Suspense,
-  useCallback,
   useEffect,
-  useLayoutEffect,
   useState,
   type ReactNode,
 } from 'react';
@@ -12,6 +10,8 @@ import {
   type NoteNavigationDrawerPhase,
 } from '@features/memo/public/shell-api';
 import { createLogger } from '@/lib/logger';
+import { useI18n } from '@/lib/i18n';
+import { ListSurfaceLoadingState } from '@shared/ui/list-surface';
 
 const logger = createLogger('main-middle-column-controller');
 
@@ -30,19 +30,12 @@ function loadAgentConversationList() {
 
 const AgentConversationList = lazy(loadAgentConversationList);
 
-function AgentConversationListReadySignal({
-  onReady,
-  isActive,
-}: {
-  onReady(): void;
-  isActive: boolean;
-}) {
-  useLayoutEffect(() => onReady(), [onReady]);
-  return <AgentConversationList isActive={isActive} />;
+function AgentConversationListLoadingFallback() {
+  const { t } = useI18n();
+  return <ListSurfaceLoadingState ariaLabel={t('status.agent.loadingConversations')} />;
 }
 
 export interface MainMiddleColumnController {
-  agentConversationListReady: boolean;
   shouldRenderAgentConversationList: boolean;
   showMemoListSurface: boolean;
   showAgentConversationSurface: boolean;
@@ -69,10 +62,6 @@ export function useMainMiddleColumnController({
   const [agentConversationListMounted, setAgentConversationListMounted] = useState(
     () => isAgentConversationView,
   );
-  const [agentConversationListReady, setAgentConversationListReady] = useState(false);
-  const handleAgentConversationListReady = useCallback(() => {
-    setAgentConversationListReady(true);
-  }, []);
 
   useEffect(() => {
     if (isAgentConversationView) setAgentConversationListMounted(true);
@@ -97,11 +86,9 @@ export function useMainMiddleColumnController({
   const shouldRenderAgentConversationList = agentConversationListMounted || isAgentConversationView;
 
   return {
-    agentConversationListReady,
     shouldRenderAgentConversationList,
-    // The selected surface must follow the store immediately.  Readiness is
-    // only a loading concern for the lazy conversation chunk; it must not keep
-    // the previous notes surface visible after the user has switched views.
+    // The selected surface follows the store immediately; a lazy chunk uses
+    // its own Suspense fallback instead of keeping the previous notes visible.
     showMemoListSurface: !isAgentConversationView,
     showAgentConversationSurface: isAgentConversationView,
     memoListPreviewVisible,
@@ -113,11 +100,8 @@ export function useMainMiddleColumnController({
     handleMemoListPreviewCompanionEnter: preview.handleCompanionSurfaceEnter,
     handleMemoListPreviewCompanionLeave: preview.handleCompanionSurfaceLeave,
     agentConversationListNode: (
-      <Suspense fallback={null}>
-        <AgentConversationListReadySignal
-          onReady={handleAgentConversationListReady}
-          isActive={agentConversationListActive}
-        />
+      <Suspense fallback={<AgentConversationListLoadingFallback />}>
+        <AgentConversationList isActive={agentConversationListActive} />
       </Suspense>
     ),
   };
diff --git a/app/flowix-web/features/shell/main-layout.tsx b/app/flowix-web/features/shell/main-layout.tsx
index 6fce7edc1..31b0a2878 100644
--- a/app/flowix-web/features/shell/main-layout.tsx
+++ b/app/flowix-web/features/shell/main-layout.tsx
@@ -1,9 +1,10 @@
 'use client';
 
 import { ColumnResizeHandle } from './components/column-resize-handle';
+import { focusWorkspaceHostFromEvent } from '@features/workspace/public/host-api';
 
 import { createLogger } from '@/lib/logger';
-import { canonicalPath } from '@/lib/path';
+import { canonicalPath, canonicalDirectoryPath, notebookRelativeDirectoryPath, parentDirectoryPath } from '@/lib/path';
 import {
   setMemoListViewPreference,
   useMemoListViewPreference,
@@ -28,20 +29,19 @@ import {
   MemoListServicesHost,
   NoteNavigationDrawer,
   useShellMemoViewModel,
-  useShellDocumentListTitle,
   type Notebook,
 } from '@features/memo/public/shell-api';
 import { AgentConversationTitlebar } from '@features/agent/public/shell-api';
 import { useSettingsStore } from '@/lib/store/settings-store';
+import { useWorkspaceStartupStore } from '@/lib/store/workspace-startup-store';
 import { useShallow } from 'zustand/react/shallow';
 import {
   product,
   windows,
   boot,
-  type StartupStatus,
-  type DshDownloadProgress,
 } from '@platform/tauri/client';
 import { files } from '@platform/tauri/client/desktop';
+import { subscribe } from '@platform/tauri/event-bus';
 import { WindowsTitlebarControls } from '@shared/window-titlebar-controls';
 import { NotebookDeleteDialog } from '@features/shell/components/notebook-delete-dialog';
 import { ExternalFileDropOverlay } from '@features/shell/components/drag-overlay/external-file-drop-overlay';
@@ -53,11 +53,11 @@ import { useI18n } from '@/lib/i18n';
 import { toast } from '@/lib/toast';
 import { openPath } from '@platform/tauri/opener';
 import { Button } from '@shared/ui/button';
-import type { DshRuntimeInstallerState } from '@features/preferences/public/system-api';
 import type { AppUpdaterState } from '@features/shell/hooks/use-app-updater';
 import {
   WorkColumnContentHost,
   resolveWorkColumnPresentation,
+  useWorkspaceSurfacePresentation,
   type DocumentSurfaceContext,
 } from '@features/surface/public/shell-api';
 import type { PluginDescriptor } from '@platform/tauri/client';
@@ -69,7 +69,6 @@ import {
 } from '@features/workspace/public/shell-api';
 import { MainStatusBarHost } from '@features/shell/components/main-status-bar-host';
 import { CenteredLoadingSpinner } from '@shared/ui/centered-loading-spinner';
-import { MainPromptHost } from '@features/shell/components/main-prompt-host';
 import type { Editor } from '@tiptap/core';
 import { OnboardingScreen } from '@features/onboarding';
 import { finishOnboardingNotebook } from '@features/shell/use-cases/finish-onboarding';
@@ -90,10 +89,6 @@ function isWindowsPlatform(): boolean {
   return /Windows/i.test(navigator.userAgent) || /Win/i.test(navigator.platform);
 }
 
-function isTauriRuntime(): boolean {
-  return typeof window !== 'undefined'
-    && ('__TAURI_INTERNALS__' in window || '__TAURI__' in window);
-}
 
 function isDifferentHistoryTarget(
   entry: DocumentHistoryEntry,
@@ -121,15 +116,11 @@ export interface MainLayoutBusinessController {
 }
 
 export interface MainLayoutSystemController {
-  dshDownload: DshDownloadProgress | null;
-  dshInstallPromptOpen: boolean;
   onboardingOpen: boolean;
   onboardingLoading: boolean;
   updater: AppUpdaterState;
-  dshInstaller: DshRuntimeInstallerState;
-  closeDshInstallPrompt(): void;
-  markDshIntroDisplayed(): void;
-  completeDshInstallPrompt(): void;
+  hasPendingAppUpdateResult: boolean;
+  presentPendingAppUpdateResult(): void;
   completeOnboarding(): Promise<void>;
 }
 
@@ -157,15 +148,11 @@ export function MainLayout({
     selectNotebook: handleSelectNotebook,
   } = business;
   const {
-    dshDownload,
-    dshInstallPromptOpen,
     onboardingOpen,
     onboardingLoading,
     updater,
-    dshInstaller,
-    closeDshInstallPrompt: handleDshPromptClose,
-    markDshIntroDisplayed: handleDshIntroDisplayed,
-    completeDshInstallPrompt: handleDshInstalled,
+    hasPendingAppUpdateResult,
+    presentPendingAppUpdateResult,
     completeOnboarding,
   } = system;
   const showProductIntroAfterOnboarding = useCallback(() => {
@@ -181,6 +168,21 @@ export function MainLayout({
 
     setProductIntroOpen(true);
   }, []);
+
+  useEffect(() => {
+    if (!hasPendingAppUpdateResult
+      || onboardingLoading
+      || onboardingOpen
+      || productIntroOpen) return;
+    const frame = window.requestAnimationFrame(() => presentPendingAppUpdateResult());
+    return () => window.cancelAnimationFrame(frame);
+  }, [
+    hasPendingAppUpdateResult,
+    onboardingLoading,
+    onboardingOpen,
+    productIntroOpen,
+    presentPendingAppUpdateResult,
+  ]);
   // 切片订阅：每个 useStore 只取真正用到的字段，setter 走 useShallow 聚合。
   // 替代原来的 `useNoteStore()` / `useDocumentStore()` / `useSettingsStore()`
   // 全量订阅 —— 任何 set 都会让 MainLayout 整树重渲，跨菜单栏 / 状态栏 /
@@ -198,6 +200,48 @@ export function MainLayout({
     loadNotes,
     triggerRefresh,
   } = useShellMemoViewModel();
+  const [defaultCreateFolderState, setDefaultCreateFolderState] = useState<{
+    notebookId: string;
+    path: string | null;
+  } | null>(null);
+  const defaultCreateFolder = defaultCreateFolderState !== null
+    && selectedNotebook != null
+    && defaultCreateFolderState.notebookId === selectedNotebook.id
+    ? defaultCreateFolderState.path
+    : null;
+  useEffect(() => {
+    let current = true;
+    const refreshDefaultFolder = () => {
+      if (!selectedNotebook) return;
+      void files.getNotebookViewPreferences(selectedNotebook.path).then((preferences) => {
+        if (current) setDefaultCreateFolderState({
+          notebookId: selectedNotebook.id,
+          path: preferences.defaultCreateFolder ?? null,
+        });
+      }).catch((error) => {
+        logger.warn('load notebook default create folder for titlebar failed', { error, notebookId: selectedNotebook.id });
+        if (current) setDefaultCreateFolderState({ notebookId: selectedNotebook.id, path: null });
+      });
+    };
+    if (!selectedNotebook) {
+      setDefaultCreateFolderState(null);
+      return () => { current = false; };
+    }
+    refreshDefaultFolder();
+    const unsubscribe = subscribe<{ notebookPath: string; defaultCreateFolderChanged: boolean }>(
+      'notebook-view-preferences-changed',
+      ({ notebookPath, defaultCreateFolderChanged }) => {
+        if (defaultCreateFolderChanged
+          && canonicalDirectoryPath(notebookPath) === canonicalDirectoryPath(selectedNotebook.path)) {
+          refreshDefaultFolder();
+        }
+      },
+    );
+    return () => {
+      current = false;
+      unsubscribe();
+    };
+  }, [selectedNotebook?.id, selectedNotebook?.path]);
   const memoListView = useMemoListViewPreference();
   const isAgentConversationView = middleColumnView === 'conversations';
   const {
@@ -228,48 +272,18 @@ export function MainLayout({
     browserColumnVisible,
     browserColumnSplitRatio,
     setBrowserColumnSplitRatio,
-    focusWorkspaceHost,
     focusedHostId,
     notebookSwitching,
   } = useShellWorkspaceViewModel();
-  const [startupStatus, setStartupStatus] = useState<StartupStatus>({
-    phase: 'pending',
-    step: 'initializing',
-    error: null,
-  });
-  useEffect(() => {
-    if (!isTauriRuntime()) {
-      setStartupStatus({ phase: 'ready', step: 'ready', error: null });
-      return;
-    }
-
-    let active = true;
-    let timer: number | undefined;
-    const refresh = async () => {
-      try {
-        const next = await boot.getStartupStatus();
-        if (!active) return;
-        setStartupStatus(next);
-        if (next.phase === 'ready' || next.phase === 'failed') {
-          if (timer !== undefined) window.clearInterval(timer);
-          timer = undefined;
-        }
-      } catch {
-        // Browser preview and older native shells have no startup coordinator;
-        // they should retain the existing interactive behavior.
-        if (active) setStartupStatus({ phase: 'ready', step: 'ready', error: null });
-        if (timer !== undefined) window.clearInterval(timer);
-        timer = undefined;
-      }
-    };
-
-    void refresh();
-    timer = window.setInterval(() => void refresh(), 250);
-    return () => {
-      active = false;
-      if (timer !== undefined) window.clearInterval(timer);
-    };
-  }, []);
+  const nativeStartup = useWorkspaceStartupStore(useShallow((state) => ({
+    phase: state.nativePhase,
+    stage: state.nativeStage,
+    step: state.nativeStep,
+    error: state.nativeError,
+  })));
+  const workspaceStartup = useWorkspaceStartupStore();
+  // Native error UI remains in the layout; the root overlay owns all loading visuals.
+  const startupStatus = nativeStartup;
   const documentHistory = useShellDocumentHistory();
   const canNavigateBack = documentHistory.backStack.some((entry) => (
     isDifferentHistoryTarget(
@@ -322,7 +336,6 @@ export function MainLayout({
     openNoteNavigation();
   }, [openNoteNavigation, setMiddleColumnView]);
   const {
-    agentConversationListReady,
     shouldRenderAgentConversationList,
     showMemoListSurface,
     showAgentConversationSurface,
@@ -564,15 +577,12 @@ export function MainLayout({
       : null,
     emptyMessage: t('shell.emptyDocument'),
   });
-  const documentListTitle = useShellDocumentListTitle(
-    navigationState.target.kind === 'document-list'
-      ? {
-          notebookId: navigationState.target.scope.notebookId,
-          folderPath: navigationState.target.scope.path,
-          customFilterId: navigationState.target.filters.customFilterId ?? null,
-        }
-      : null,
-  );
+  const workSurfaceViewId = workColumnPresentation.content.status === 'surface'
+    ? workColumnPresentation.content.surface.instanceKey
+    : '';
+  const workRuntimePresentation = useWorkspaceSurfacePresentation(workSurfaceViewId);
+  const workCapabilities = workRuntimePresentation.capabilities ?? workColumnPresentation.capabilities;
+  const workHeaderStyle = workRuntimePresentation.appearance?.headerStyle ?? workColumnPresentation.chrome;
   const isAgentConversationDetail = workColumnPresentation.header.kind === 'agent';
   const workColumnLoadingTone = navigationState.phase === 'loading'
     ? navigationState.pendingTarget?.kind === 'agent-conversation'
@@ -581,10 +591,36 @@ export function MainLayout({
         ? 'media'
         : 'document'
     : workColumnPresentation.chrome;
+  const handleToggleDefaultFolder = useCallback(async (target: {
+    filePath: string;
+    notebookPath: string;
+    notebookId: string;
+  }) => {
+    const folderPath = parentDirectoryPath(target.filePath, target.notebookPath);
+    const relativeFolder = notebookRelativeDirectoryPath(target.notebookPath, folderPath);
+    if (relativeFolder === null) return;
+    try {
+      const preferences = await files.getNotebookViewPreferences(target.notebookPath);
+      const isDefaultFolder = (preferences.defaultCreateFolder ?? null) === relativeFolder;
+      const nextDefaultFolder = isDefaultFolder ? null : relativeFolder;
+      await files.setNotebookViewPreferences(target.notebookPath, {
+        ...preferences,
+        defaultCreateFolder: nextDefaultFolder,
+      });
+      setDefaultCreateFolderState({ notebookId: target.notebookId, path: nextDefaultFolder });
+      toast.success(t(isDefaultFolder
+        ? 'memo.fileTree.defaultCreateFolderCleared'
+        : 'memo.fileTree.defaultCreateFolderSet'));
+    } catch (error) {
+      logger.warn('set default create folder from collection titlebar failed', { error, folderPath });
+      toast.error(t('memo.fileTree.preferenceSaveFailed'));
+    }
+  }, [t]);
   const documentTitlebarProps = {
     reserveWindowsControls: !browserColumnVisible,
-    surfaceChrome: workColumnPresentation.chrome === 'media' ? 'media' as const : 'document' as const,
+    surfaceChrome: workHeaderStyle === 'media' ? 'media' as const : 'document' as const,
     showEditorFontSwitcher: workColumnPresentation.content.status === 'surface'
+      && workCapabilities.includes('edit')
       && workColumnPresentation.content.surface.kind === 'md',
     document: {
       // An artifact is allowed to sit above an existing editable session.
@@ -604,14 +640,15 @@ export function MainLayout({
       canNavigateForward,
       onNavigateBack: handleNavigateBack,
       onNavigateForward: handleNavigateForward,
-      title: documentListTitle,
+      title: workRuntimePresentation.title,
+      icon: workRuntimePresentation.icon,
     },
     contentCapabilities: {
-      copyFullText: workColumnPresentation.capabilities.includes('copy-content'),
-      memoColors: workColumnPresentation.capabilities.includes('memo-colors'),
-      exportContent: workColumnPresentation.capabilities.includes('export-content'),
-      saveAsTemplate: workColumnPresentation.capabilities.includes('save-template'),
-      versionHistory: workColumnPresentation.capabilities.includes('version-history'),
+      copyFullText: workCapabilities.includes('copy-content'),
+      memoColors: workCapabilities.includes('memo-colors'),
+      exportContent: workCapabilities.includes('export-content'),
+      saveAsTemplate: workCapabilities.includes('save-template'),
+      versionHistory: workCapabilities.includes('version-history'),
     },
     actions: {
       onCopyLink: handleCopyLink,
@@ -637,6 +674,19 @@ export function MainLayout({
       && navigationState.target.notebookId
       ? {
           current: navigationState.target.collectionType,
+          isDefaultFolder: defaultCreateFolderState?.notebookId === navigationState.target.notebookId
+            && notebookRelativeDirectoryPath(
+              navigationState.target.notebookPath,
+              parentDirectoryPath(navigationState.target.filePath, navigationState.target.notebookPath),
+            ) === defaultCreateFolder,
+          onToggleDefaultFolder: () => {
+            const target = navigationState.target;
+            if (target.kind === 'collection') void handleToggleDefaultFolder({
+              filePath: target.filePath,
+              notebookPath: target.notebookPath,
+              notebookId: target.notebookId,
+            });
+          },
           onSelect: (type: 'table' | 'media_library') => {
             const target = navigationState.target;
             if (target.kind !== 'collection' || target.collectionType === type) return;
@@ -687,7 +737,12 @@ export function MainLayout({
             onOpenPreferences={(tab) => void windows.openPreferences(tab)}
             onPreviewEnter={handleMemoListPreviewEnter}
             onPreviewLeave={handleMemoListPreviewLeave}
-            onPointerDown={() => focusWorkspaceHost('main-third')}
+            onPointerDown={(event) => {
+              if (event.button !== 0) return;
+              const target = event.target;
+              if (target instanceof Element && target.closest('[data-folder-selection]')) return;
+              focusWorkspaceHostFromEvent(event, 'main-third');
+            }}
           >
             <ListColumnContent
               activeView={middleColumnView === 'conversations'
@@ -703,7 +758,6 @@ export function MainLayout({
               }}
               navigationDrawerOpen={noteNavigationPhase !== 'closed'}
               onToggleNavigationDrawer={handleToggleNoteNavigation}
-              conversationLoading={isAgentConversationView && !agentConversationListReady}
             >
                 <div
                   className={`absolute inset-0 ${
@@ -756,8 +810,8 @@ export function MainLayout({
                 : { minWidth: DOCUMENT_PANEL_MIN_WIDTH, flex: 1 }}
               data-workspace-host="main-third"
               data-workspace-focused={focusedHostId === 'main-third' ? '' : undefined}
-              onPointerDown={() => focusWorkspaceHost('main-third')}
-              onFocusCapture={() => focusWorkspaceHost('main-third')}
+              onPointerDown={(event) => focusWorkspaceHostFromEvent(event, 'main-third')}
+              onFocusCapture={(event) => focusWorkspaceHostFromEvent(event, 'main-third')}
             >
             {isMemoListHidden && (
               <button
@@ -842,7 +896,11 @@ export function MainLayout({
                   </Button>
                 </div>
               )}
-              <WorkColumnContentHost content={workColumnPresentation.content} />
+              <WorkColumnContentHost
+                content={workColumnPresentation.content}
+                focused={focusedHostId === 'main-third'}
+                startupIdentity={JSON.stringify(navigationState.target)}
+              />
               {(isDocumentTransitioning
                 || (navigationState.phase === 'loading' && navigationState.showWorkColumnLoading)) && (
                 <CenteredLoadingSpinner
@@ -877,7 +935,6 @@ export function MainLayout({
             onOpenTagPanel={handleOpenTagPanel}
             productIntroOpen={productIntroOpen}
             onProductIntroOpenChange={setProductIntroOpen}
-            dshDownload={dshDownload}
             updater={updater}
           />
         </div>
@@ -896,42 +953,42 @@ export function MainLayout({
         suppressEmptyNotebookPrompt={onboardingLoading || onboardingOpen}
       />
 
-      <MainPromptHost
-        updater={updater}
-        dshInstallPromptOpen={dshInstallPromptOpen}
-        dshInstaller={dshInstaller}
-        onCloseDshInstallPrompt={handleDshPromptClose}
-        onDshIntroDisplayed={handleDshIntroDisplayed}
-        onDshInstalled={handleDshInstalled}
-      />
-
-      {(startupStatus.phase !== 'ready'
-        || memoStartupPhase === 'idle'
-        || memoStartupPhase === 'loading'
+      {(startupStatus.phase === 'failed'
+        || workspaceStartup.status === 'failed'
         || (memoStartupPhase === 'error' && (!showMemoListSurface || isMemoListHidden))) && (
         <div className="absolute inset-0 z-[100] flex items-center justify-center bg-[var(--frame-bg)]">
           {startupStatus.phase === 'failed' ? (
-            <div className="max-w-md px-6 text-center text-sm text-[var(--muted-foreground)]" role="alert">
-              {t('memo.navigation.startupMigrationFailed')}
+            <div className="flex max-w-md flex-col items-center gap-3 px-6 text-center text-sm text-[var(--muted-foreground)]" role="alert">
+              {t(startupStatus.stage === 'workspacePreparation'
+                ? 'memo.navigation.workspacePreparationFailed'
+                : 'memo.navigation.startupMigrationFailed')}
+              {startupStatus.error && <span className="max-h-40 overflow-auto break-words">{startupStatus.error}</span>}
+              <Button size="sm" className="rounded-lg" onClick={() => {
+                void boot.retryStartup().then(() => window.location.reload()).catch((error) => {
+                  useWorkspaceStartupStore.setState({ nativeError: String(error) });
+                });
+              }}>{t('error.retry')}</Button>
             </div>
-          ) : memoStartupPhase === 'error' ? (
+          ) : (
             <div className="flex max-w-md flex-col items-center gap-3 px-6 text-center" role="alert">
-              <span className="text-sm text-[var(--muted-foreground)]">{t('memo.list.loadFailed')}</span>
-              <Button size="sm" onClick={() => window.location.reload()}>{t('error.retry')}</Button>
+              <span className="text-sm text-[var(--muted-foreground)]">{t(workspaceStartup.status === 'failed'
+                ? 'memo.navigation.workspacePreparationFailed'
+                : 'memo.list.loadFailed')}</span>
+              {workspaceStartup.error && <span className="max-h-40 overflow-auto break-words text-sm text-[var(--muted-foreground)]">{workspaceStartup.error}</span>}
+              <Button size="sm" className="rounded-lg" onClick={() => window.location.reload()}>{t('error.retry')}</Button>
             </div>
-          ) : (
-            <CenteredLoadingSpinner label={t('memo.navigation.preparingWorkspace')} />
           )}
         </div>
       )}
 
       {onboardingOpen && (
         <OnboardingScreen
-          onFinish={async (notebook, { startImport }) => {
-            await finishOnboardingNotebook(notebook, { startImport }, {
+          onFinish={async (notebook, { startImport, templateId }) => {
+            await finishOnboardingNotebook(notebook, { startImport, templateId }, {
               completeOnboarding,
               failureTitle: t('notebook.setup.failed'),
               retryLabel: t('error.retry'),
+              overwriteConfirmMessage: t('notebook.template.overwriteConfirm'),
             });
             showProductIntroAfterOnboarding();
           }}
diff --git a/app/flowix-web/features/shell/use-cases/finish-onboarding.ts b/app/flowix-web/features/shell/use-cases/finish-onboarding.ts
index 375696eb4..24028dc71 100644
--- a/app/flowix-web/features/shell/use-cases/finish-onboarding.ts
+++ b/app/flowix-web/features/shell/use-cases/finish-onboarding.ts
@@ -1,22 +1,47 @@
-import { startNotebookImportWithMonitoring, type Notebook } from '@features/memo/public/shell-api';
+import {
+  confirmShellNotebookTemplateOverwrite,
+  ensureShellNotebookTemplateSetup,
+  startNotebookImportWithMonitoring,
+  type Notebook,
+} from '@features/memo/public/shell-api';
 import { selectNotebook } from '@features/workspace/public/shell-api';
 import { clearActionableNotice, upsertActionableNotice } from '@features/notifications/actionable-notice-store';
 
 export async function finishOnboardingNotebook(
   notebook: Notebook,
-  { startImport }: { startImport: boolean },
+  { startImport, templateId }: { startImport: boolean; templateId?: string | null },
   {
     completeOnboarding,
     failureTitle,
     retryLabel,
+    overwriteConfirmMessage,
   }: {
     completeOnboarding: () => Promise<void>;
     failureTitle: string;
     retryLabel: string;
+    overwriteConfirmMessage?: string;
   },
 ): Promise<void> {
   await selectNotebook(notebook);
-  if (startImport) {
+  // Template setup performs its own import after the template files are written.
+  // Avoid starting a competing import alongside that background job.
+  let shouldStartImport = startImport && !templateId;
+  if (templateId) {
+    try {
+      await ensureShellNotebookTemplateSetup(notebook.id, templateId);
+    } catch (error) {
+      if (!String(error).includes('NOTEBOOK_PRESET_OVERWRITE_CONFIRM_REQUIRED')) throw error;
+      const confirmed = await confirmShellNotebookTemplateOverwrite(
+        overwriteConfirmMessage ?? '所选文件夹中已有文件或笔记。继续将用场景内容覆盖同路径文件，是否继续？',
+      );
+      if (confirmed) {
+        await ensureShellNotebookTemplateSetup(notebook.id, templateId, true);
+      } else {
+        shouldStartImport = true;
+      }
+    }
+  }
+  if (shouldStartImport) {
     const noticeId = `notebook-import:${notebook.id}`;
     let attempt = 0;
     let importing = false;
diff --git a/app/flowix-web/features/surface/browser-column-registry.test.ts b/app/flowix-web/features/surface/browser-column-registry.test.ts
index b9892a432..c2075b611 100644
--- a/app/flowix-web/features/surface/browser-column-registry.test.ts
+++ b/app/flowix-web/features/surface/browser-column-registry.test.ts
@@ -1,11 +1,33 @@
 import { describe, expect, it } from 'vitest';
-import { browserColumnSurfaceRegistry } from './browser-column-registry';
+import { getBrowserColumnSurfaceDefinition, browserColumnSurfaceSupports, type BrowserColumnSurface } from './browser-column-registry';
+import { workspaceSurfaceRendererRegistry } from './workspace-surface-renderer-registry';
 
-describe('browserColumnSurfaceRegistry', () => {
-  it('assigns semantic chrome to conversation and media surfaces', () => {
-    expect(browserColumnSurfaceRegistry['agent-conversation'].chrome).toBe('agent');
-    expect(browserColumnSurfaceRegistry.media.chrome).toBe('media');
-    expect(browserColumnSurfaceRegistry['file-browser'].chrome).toBe('document');
-    expect(browserColumnSurfaceRegistry.web.chrome).toBe('document');
+const base = { tabId: 'tab-1', instanceKey: 'tab:tab-1' };
+
+describe('Browser surface adapter', () => {
+  it('uses common appearance and capabilities for conversation, media and web', () => {
+    const surfaces: BrowserColumnSurface[] = [
+      { ...base, kind: 'agent-conversation', instanceId: 'agent-1' },
+      { ...base, kind: 'media', fileIdentity: { path: '/book/a.png', displayId: 'a' }, notebookId: 'book', notebookPath: '/book', resourceKind: 'image' },
+      { ...base, kind: 'web', url: 'https://example.com', title: 'example', runtime: null },
+    ];
+    for (const surface of surfaces) {
+      const definition = getBrowserColumnSurfaceDefinition(surface);
+      expect(definition.appearance).toBe(workspaceSurfaceRendererRegistry[surface.kind].appearance);
+      expect(definition.capabilities).toBe(workspaceSurfaceRendererRegistry[surface.kind].capabilities);
+    }
+  });
+
+  it.each([
+    ['/book/a.md', 'edit', true], ['/book/a.png', 'zoom', true], ['/book/a.png', 'edit', false],
+    ['/book/a.docx', 'edit', false],
+  ] as const)('derives %s capabilities from its active content', (path, capability, enabled) => {
+    const surface: BrowserColumnSurface = {
+      ...base, kind: 'file-browser', activeFilePath: path, fileIdentity: { path, displayId: path },
+      scopePath: '/book', notebookId: 'book', folderPath: null, fileTreeVisible: false, fileTreeWidth: 220,
+      documentProps: { isExternalDocument: true }, onSelectFile: () => {}, onOpenFileInNewTab: () => {},
+      onContextChange: () => {}, onTreeVisibleChange: () => {}, onTreeWidthChange: () => {},
+    };
+    expect(browserColumnSurfaceSupports(surface, capability)).toBe(enabled);
   });
 });
diff --git a/app/flowix-web/features/surface/browser-column-registry.tsx b/app/flowix-web/features/surface/browser-column-registry.tsx
index e6a309e7d..8097a5909 100644
--- a/app/flowix-web/features/surface/browser-column-registry.tsx
+++ b/app/flowix-web/features/surface/browser-column-registry.tsx
@@ -1,51 +1,23 @@
-import { setCollectionActiveView } from '@features/workspace/use-cases/collection-view-state';
-import { collectionDisplayDescriptor, findCollectionDisplayPath, type CollectionDisplayDescriptor } from '@/lib/collection-display-registry';
 'use client';
 
-import { FileBrowserView, type FileBrowserViewSurface } from './file-browser-view';
-import { openBrowserColumnTarget, selectBrowserColumnFile } from '@features/workspace/use-cases/browser-column-navigation';
-
-import {
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
-  type ComponentType,
-  type ComponentProps,
-  type FormEvent,
-  type ReactNode,
-} from 'react';
-import { ChevronLeft, ChevronRight, Globe, RotateCw, X } from 'lucide-react';
-import { LazyAgentConversationDetail } from '@features/agent/components/lazy-agent-conversation-detail';
-import { DocumentContainer, UnavailableFileView } from '@features/document/components/document-container';
-import { DocxPreview } from '@features/document/components/docx-preview';
-import { CsvPreview } from '@features/document/components/csv-preview';
-import { MediaResourceView } from './media-resource-view';
-import { SurfaceSuspenseHost } from '@shared/ui/surface-suspense-host';
-import { externalFileViewKind } from '@features/editor/public/code-file';
-import { HtmlResourceView } from './html-resource-view';
-import {
-  useBrowserColumnStore,
-  type BrowserColumnTab,
-  type BrowserColumnWebRuntime,
-} from '@features/workspace/store/browser-column-store';
-import { canonicalUrl } from '@features/workspace/store/workspace-content-identity';
+import { useCallback, useLayoutEffect, useMemo, type ReactNode } from 'react';
+import { type CollectionDisplayDescriptor } from '@/lib/collection-display-registry';
 import { requireFileDisplayIdentity, type FileDisplayIdentity } from '@/lib/file-display-registry';
-import { openUrl } from '@platform/tauri/opener';
-import { styleAccessibleIframeScrollbar } from '@shared/ui/iframe-scrollbar';
-import { TableDocumentView } from '@features/multidimensional-table/public/surface-api';
-import { MediaLibraryView } from '@features/media-library/media-library-view';
-import { useExternalFileMime } from '@features/editor/use-external-file-mime';
-import { useI18n } from '@/lib/i18n';
+import { selectBrowserColumnFile } from '@features/workspace/public/browser-column-api';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import { setCollectionActiveView } from '@features/workspace/use-cases/collection-view-state';
+import { useBrowserColumnStore, type BrowserColumnTab, type BrowserColumnWebRuntime } from '@features/workspace/store/browser-column-store';
+import { canonicalUrl } from '@features/workspace/store/workspace-content-identity';
+import type { WorkspaceSurfaceCapability, SurfaceAppearance, SurfaceHeaderStyle } from '@features/workspace/public/surface-api';
+import type { FileBrowserViewSurface } from './file-browser-view';
+import { getWorkspaceSurfaceRendererDefinition, WorkspaceSurfaceRendererView } from './workspace-surface-renderer-registry';
+import type { ExternalDocumentProps, WorkspaceSurfaceRendererData, WorkspaceWebNavigationPort } from './workspace-surface-renderer-contract';
+import { registerWorkspaceSurfacePresentationOwner, reportWorkspaceSurfacePresentation } from './workspace-surface-runtime';
+import type { SurfacePresentationUpdate } from '@features/workspace/model/surface-contract';
+import type { SurfaceLifecycle } from '@features/workspace/model/surface-contract';
+import { registerWorkspaceSurfaceLifecycle, registerWorkspaceSurfaceHostView } from '@features/workspace/public/surface-lifecycle-api';
 
-export type BrowserColumnSurfaceCapability =
-  | 'edit'
-  | 'search'
-  | 'web-navigation'
-  | 'stream-conversation'
-  | 'fullscreen'
-  | 'fit'
-  | 'zoom';
+export type BrowserColumnSurfaceCapability = WorkspaceSurfaceCapability;
 
 interface SurfaceBase {
   instanceKey: string;
@@ -63,9 +35,17 @@ export interface BrowserMediaSurface extends FileSurfaceBase {
   resourceKind: 'image' | 'video';
 }
 
+export interface BrowserFolderCollectionSurface extends SurfaceBase {
+  kind: 'collection';
+  notebookId: string;
+  notebookPath: string;
+  folderPath: string;
+  folderName: string;
+}
+
 export type BrowserFileBrowserSurface = SurfaceBase
   & FileBrowserViewSurface
-  & { collectionType?: 'table' | 'media_library'; collectionUnavailableReason?: string; collectionDisplay?: CollectionDisplayDescriptor; documentProps: Omit<ComponentProps<typeof DocumentContainer>, 'fileIdentity'> }
+  & { collectionType?: 'table' | 'media_library'; collectionUnavailableReason?: string; collectionDisplay?: CollectionDisplayDescriptor; documentProps: ExternalDocumentProps }
   & (
     | { activeFilePath: string; fileIdentity: FileDisplayIdentity }
     | { activeFilePath: null; fileIdentity?: never }
@@ -84,6 +64,7 @@ export interface BrowserAgentConversationSurface extends SurfaceBase {
 }
 
 export type BrowserColumnSurface =
+  | BrowserFolderCollectionSurface
   | BrowserMediaSurface
   | BrowserFileBrowserSurface
   | BrowserWebSurface
@@ -92,12 +73,13 @@ export type BrowserColumnSurface =
 export type BrowserColumnSurfaceKind = BrowserColumnSurface['kind'];
 
 /** Titlebar skin owned by the surface currently mounted in Browser Column. */
-export type BrowserColumnSurfaceChrome = 'document' | 'agent' | 'media';
+export type BrowserColumnSurfaceChrome = SurfaceHeaderStyle;
 
 export interface BrowserColumnSurfaceDefinition {
+  appearance: Readonly<SurfaceAppearance>;
   chrome: BrowserColumnSurfaceChrome;
   capabilities: readonly BrowserColumnSurfaceCapability[];
-  render: (surface: BrowserColumnSurface) => ReactNode;
+  render: () => ReactNode;
 }
 
 export type BrowserColumnDocumentFlush = (
@@ -108,374 +90,6 @@ export type BrowserColumnFlushRegistration = (
   discard?: (() => void) | null,
 ) => void;
 
-function browserTitleForUrl(url: string): string {
-  try {
-    return new URL(url).hostname || url;
-  } catch {
-    return url;
-  }
-}
-
-function browserFaviconForUrl(url: string): string | null {
-  try {
-    const parsed = new URL(url);
-    return `${parsed.origin}/favicon.ico`;
-  } catch {
-    return null;
-  }
-}
-
-function BrowserWebSurfaceView({ surface }: { surface: BrowserWebSurface }) {
-  const iframeRef = useRef<HTMLIFrameElement>(null);
-  const embedTimeoutRef = useRef<number | null>(null);
-  const runtime = surface.runtime;
-  const currentUrl = runtime?.currentUrl ?? surface.url;
-  const reloadToken = runtime?.reloadToken ?? 0;
-  const [address, setAddress] = useState(currentUrl);
-  const [addressError, setAddressError] = useState<string | null>(null);
-  const [showEmbedTimeout, setShowEmbedTimeout] = useState(false);
-  const setWebRuntime = useBrowserColumnStore((state) => state.setWebRuntime);
-  const navigateWebTab = useBrowserColumnStore((state) => state.navigateWebTab);
-  const goBackWebTab = useBrowserColumnStore((state) => state.goBackWebTab);
-  const goForwardWebTab = useBrowserColumnStore((state) => state.goForwardWebTab);
-  const reloadWebTab = useBrowserColumnStore((state) => state.reloadWebTab);
-  const updateTabMetadata = useBrowserColumnStore((state) => state.updateTabMetadata);
-
-  useEffect(() => {
-    setAddress(currentUrl);
-  }, [currentUrl]);
-
-  useEffect(() => {
-    if (runtime) return;
-    setWebRuntime(surface.tabId, {
-      currentUrl: surface.url,
-      history: [surface.url],
-      historyIndex: 0,
-      reloadToken: 0,
-      isLoading: false,
-      error: null,
-    });
-  }, [runtime, setWebRuntime, surface.tabId, surface.url]);
-
-  const reportRuntime = useCallback((patch: Partial<BrowserColumnWebRuntime>) => {
-    const current = useBrowserColumnStore.getState().webRuntimes[surface.tabId] ?? {
-      currentUrl,
-      history: [currentUrl],
-      historyIndex: 0,
-      reloadToken,
-      isLoading: false,
-      error: null,
-    };
-    setWebRuntime(surface.tabId, { ...current, ...patch });
-  }, [currentUrl, reloadToken, setWebRuntime, surface.tabId]);
-
-  useEffect(() => {
-    setShowEmbedTimeout(false);
-    embedTimeoutRef.current = window.setTimeout(() => setShowEmbedTimeout(true), 6_000);
-    return () => {
-      if (embedTimeoutRef.current !== null) window.clearTimeout(embedTimeoutRef.current);
-      embedTimeoutRef.current = null;
-    };
-  }, [currentUrl, reloadToken]);
-
-  const handleNavigate = useCallback((event: FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    const normalized = canonicalUrl(address);
-    if (!normalized) {
-      setAddressError('请输入 http:// 或 https:// 地址');
-      return;
-    }
-    setAddressError(null);
-    setAddress(normalized);
-    navigateWebTab(surface.tabId, normalized);
-    updateTabMetadata(surface.tabId, {
-      icon: browserFaviconForUrl(normalized),
-      title: browserTitleForUrl(normalized),
-    });
-  }, [address, navigateWebTab, surface.tabId, updateTabMetadata]);
-
-  const handleIframeLoad = useCallback(() => {
-    const iframe = iframeRef.current;
-    styleAccessibleIframeScrollbar(iframe);
-    let loadedUrl = currentUrl;
-    let pageTitle = '';
-    try {
-      const href = iframe?.contentWindow?.location.href;
-      loadedUrl = canonicalUrl(href ?? '') ?? currentUrl;
-      pageTitle = iframe?.contentDocument?.title?.trim() ?? '';
-      if (embedTimeoutRef.current !== null) window.clearTimeout(embedTimeoutRef.current);
-      embedTimeoutRef.current = null;
-      setShowEmbedTimeout(false);
-    } catch {
-      // Cross-origin pages intentionally do not expose their URL/title to the
-      // host document. Keep the address bar and tab title at their last known
-      // values in that case.
-    }
-
-    const runtimeNow = useBrowserColumnStore.getState().webRuntimes[surface.tabId];
-    if (runtimeNow && loadedUrl !== runtimeNow.currentUrl) {
-      const history = runtimeNow.history.slice(0, runtimeNow.historyIndex + 1);
-      if (history[history.length - 1] !== loadedUrl) history.push(loadedUrl);
-      reportRuntime({
-        currentUrl: loadedUrl,
-        history,
-        historyIndex: history.length - 1,
-        isLoading: false,
-        error: null,
-      });
-    } else {
-      reportRuntime({ isLoading: false, error: null });
-    }
-    updateTabMetadata(surface.tabId, {
-      title: pageTitle || browserTitleForUrl(loadedUrl),
-      icon: browserFaviconForUrl(loadedUrl),
-    });
-  }, [currentUrl, reportRuntime, surface.tabId, updateTabMetadata]);
-
-  const handleOpenInSystemBrowser = useCallback(() => {
-    void openUrl(currentUrl).catch(() => {
-      reportRuntime({ error: '无法在系统浏览器中打开' });
-    });
-  }, [currentUrl, reportRuntime]);
-
-  return (
-    <div className="flex h-full min-h-0 w-full flex-col bg-[var(--background)]">
-      <form
-        onSubmit={handleNavigate}
-        className="flex shrink-0 items-center gap-1 border-b border-[var(--divider)] bg-[var(--bg-titlebar)] px-2 py-1.5"
-      >
-        <button
-          type="button"
-          aria-label="后退"
-          title="后退"
-          disabled={!runtime || runtime.historyIndex <= 0}
-          onClick={() => goBackWebTab(surface.tabId)}
-          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] disabled:opacity-35"
-        >
-          <ChevronLeft className="h-3.5 w-3.5" />
-        </button>
-        <button
-          type="button"
-          aria-label="前进"
-          title="前进"
-          disabled={!runtime || runtime.historyIndex >= runtime.history.length - 1}
-          onClick={() => goForwardWebTab(surface.tabId)}
-          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] disabled:opacity-35"
-        >
-          <ChevronRight className="h-3.5 w-3.5" />
-        </button>
-        <button
-          type="button"
-          aria-label="重新加载"
-          title="重新加载"
-          onClick={() => reloadWebTab(surface.tabId)}
-          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)]"
-        >
-          <RotateCw className="h-3.5 w-3.5" />
-        </button>
-        <div className="flex min-w-0 flex-1 items-center rounded-md border border-[var(--border)] bg-[var(--background)] px-2">
-          <Globe className="mr-1.5 h-3.5 w-3.5 shrink-0 text-[var(--muted-foreground)]" />
-          <input
-            aria-label="网页地址"
-            value={address}
-            onChange={(event) => {
-              setAddress(event.target.value);
-              setAddressError(null);
-            }}
-            className="h-7 min-w-0 flex-1 bg-transparent text-xs text-[var(--foreground)] outline-none"
-            spellCheck={false}
-          />
-        </div>
-        {runtime?.isLoading && (
-          <span
-            role="status"
-            aria-label="加载中"
-            className="mx-1 h-4 w-4 shrink-0 animate-spin rounded-full border-2 border-[color-mix(in_oklch,var(--muted-foreground)_26%,transparent)] border-t-[var(--brand)]"
-          />
-        )}
-        {runtime?.error && <span className="shrink-0 text-[10px] text-[var(--destructive)]">{runtime.error}</span>}
-      </form>
-      {addressError && <div className="shrink-0 px-3 py-1 text-[10px] text-[var(--destructive)]">{addressError}</div>}
-      <div className="relative min-h-0 min-w-0 flex-1 bg-white">
-        <iframe
-          key={`${surface.tabId}:${currentUrl}:${reloadToken}`}
-          ref={iframeRef}
-          title={surface.title}
-          src={currentUrl}
-          onLoad={handleIframeLoad}
-          onError={() => {
-            reportRuntime({ isLoading: false, error: '网页加载失败' });
-            setShowEmbedTimeout(true);
-          }}
-          className="h-full w-full border-0"
-          referrerPolicy="no-referrer"
-        />
-        {showEmbedTimeout && (
-          <div className="absolute inset-0 flex items-center justify-center bg-white/90 px-6 backdrop-blur-sm">
-            <div className="relative flex max-w-sm flex-col items-center gap-4 rounded-xl border border-[var(--border)] bg-[var(--background)] px-8 py-7 text-center shadow-lg">
-              <button
-                type="button"
-                aria-label="关闭提示"
-                title="关闭提示"
-                onClick={() => setShowEmbedTimeout(false)}
-                className="absolute right-2 top-2 flex h-7 w-7 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)]"
-              >
-                <X className="h-4 w-4" />
-              </button>
-              <p className="text-sm text-[var(--muted-foreground)]">网页可能禁止嵌入或加载超时</p>
-              <button
-                type="button"
-                onClick={handleOpenInSystemBrowser}
-                className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)]"
-              >
-                在系统浏览器中打开
-              </button>
-            </div>
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-function BrowserMediaSurfaceView({ surface }: { surface: BrowserMediaSurface }) {
-  return (
-    <MediaResourceView
-      filePath={surface.fileIdentity.path}
-      notebookPath={surface.notebookPath}
-      resourceKind={surface.resourceKind}
-    />
-  );
-}
-
-function BrowserFileBrowserSurfaceView({ surface }: { surface: BrowserFileBrowserSurface }) {
-  const { t } = useI18n();
-  const baseFileKind = surface.activeFilePath
-    ? externalFileViewKind(surface.activeFilePath)
-    : null;
-  const { mimeType, loading: mimeLoading } = useExternalFileMime(
-    surface.activeFilePath,
-    baseFileKind === 'unavailable',
-  );
-  if (!surface.activeFilePath) {
-    return <FileBrowserView surface={{ ...surface, sourceMenuEnabled: false }} />;
-  }
-
-  if (surface.collectionUnavailableReason) return <div className="p-4 text-sm">{surface.collectionUnavailableReason}</div>;
-  if (surface.fileIdentity && collectionDisplayDescriptor(surface.fileIdentity.displayId) && !findCollectionDisplayPath(surface.fileIdentity.displayId)) return <div className="p-4 text-sm">正在解析集合位置…</div>;
-  if (mimeLoading) {
-    return (
-      <div className="flex h-full w-full items-center justify-center text-sm text-[var(--muted-foreground)]">
-        {t('document.file.loading')}
-      </div>
-    );
-  }
-  const fileKind = externalFileViewKind(surface.activeFilePath, mimeType);
-  if (surface.collectionType === 'media_library' || (!surface.collectionType && /\.lib\.ya?ml$/i.test(surface.activeFilePath))) {
-    return <MediaLibraryView filePath={surface.activeFilePath} fileIdentity={surface.fileIdentity} expectedCollectionId={collectionDisplayDescriptor(surface.fileIdentity.displayId)?.collectionId} notebookPath={surface.scopePath} notebookId={surface.notebookId ?? null} />;
-  }
-  if (surface.collectionType === 'table' || (!surface.collectionType && /\.table\.ya?ml$/i.test(surface.activeFilePath))) {
-    return <TableDocumentView initialViewId={surface.collectionDisplay?.viewId} onActiveViewChange={(viewId) => {
-      const tab = useBrowserColumnStore.getState().tabs.find((candidate) => candidate.id === surface.tabId);
-      if (tab?.target.kind !== 'file-browser' || !tab.target.collectionDisplay) return;
-      const { notebookId, collectionId } = tab.target.collectionDisplay;
-      setCollectionActiveView({ host: 'browser-column', tabId: surface.tabId }, { notebookId, collectionId }, viewId);
-    }} filePath={surface.activeFilePath} fileIdentity={surface.fileIdentity} expectedCollectionId={collectionDisplayDescriptor(surface.fileIdentity.displayId)?.collectionId} notebookPath={surface.scopePath} notebookId={surface.notebookId ?? null} />;
-  }
-  switch (fileKind) {
-    case 'csv':
-      return <CsvPreview filePath={surface.activeFilePath} scopePath={surface.scopePath} />;
-    case 'docx':
-      return <FileBrowserView surface={{
-        ...surface,
-        fileTreeEnabled: false,
-        sourceMenuEnabled: false,
-        content: <DocxPreview filePath={surface.activeFilePath} scopePath={surface.scopePath} />,
-      }} />;
-    case 'markdown':
-      return <DocumentContainer {...surface.documentProps} fileIdentity={surface.fileIdentity} navigationViewId={surface.tabId} externalEditorMode="markdown" />;
-    case 'code':
-      return <FileBrowserView surface={{
-        ...surface,
-        fileTreeEnabled: false,
-        sourceMenuEnabled: false,
-        content: <DocumentContainer
-          {...surface.documentProps}
-          fileIdentity={surface.fileIdentity}
-          navigationViewId={surface.tabId}
-          externalScopePath={surface.scopePath}
-        />,
-      }} />;
-    case 'image':
-    case 'video':
-      return <MediaResourceView
-        filePath={surface.activeFilePath}
-        notebookPath={surface.scopePath}
-        resourceKind={fileKind}
-      />;
-    case 'html':
-      return <HtmlResourceView
-        filePath={surface.activeFilePath}
-        scopePath={surface.scopePath}
-        documentProps={{ ...surface.documentProps, fileIdentity: surface.fileIdentity }}
-      />;
-    case 'unavailable':
-      return <UnavailableFileView filePath={surface.activeFilePath} openContainingFolder scopePath={surface.scopePath} />;
-  }
-
-  return <UnavailableFileView filePath={surface.activeFilePath} openContainingFolder scopePath={surface.scopePath} />;
-}
-
-function BrowserAgentConversationSurfaceView({ surface }: { surface: BrowserAgentConversationSurface }) {
-  return <LazyAgentConversationDetail instanceId={surface.instanceId} />;
-}
-
-type SurfaceOfKind<K extends BrowserColumnSurfaceKind> = Extract<BrowserColumnSurface, { kind: K }>;
-
-function defineSurface<K extends BrowserColumnSurfaceKind>(
-  kind: K,
-  options: {
-    chrome: BrowserColumnSurfaceChrome;
-    capabilities?: readonly BrowserColumnSurfaceCapability[];
-    component: ComponentType<{ surface: SurfaceOfKind<K> }>;
-  },
-): BrowserColumnSurfaceDefinition {
-  const Component = options.component;
-  return Object.freeze({
-    chrome: options.chrome,
-    capabilities: Object.freeze([...(options.capabilities ?? [])]),
-    render(surface: BrowserColumnSurface) {
-      if (surface.kind !== kind) {
-        throw new Error(`BrowserColumn surface registry mismatch: expected '${kind}', received '${surface.kind}'`);
-      }
-      return <Component surface={surface as SurfaceOfKind<K>} />;
-    },
-  });
-}
-
-export const browserColumnSurfaceRegistry = Object.freeze({
-  media: defineSurface('media', {
-    chrome: 'media',
-    capabilities: ['fullscreen'],
-    component: BrowserMediaSurfaceView,
-  }),
-  'file-browser': defineSurface('file-browser', {
-    chrome: 'document',
-    capabilities: ['edit', 'search'],
-    component: BrowserFileBrowserSurfaceView,
-  }),
-  web: defineSurface('web', {
-    chrome: 'document',
-    capabilities: ['web-navigation'],
-    component: BrowserWebSurfaceView,
-  }),
-  'agent-conversation': defineSurface('agent-conversation', {
-    chrome: 'agent',
-    capabilities: ['stream-conversation'],
-    component: BrowserAgentConversationSurfaceView,
-  }),
-} satisfies Record<BrowserColumnSurfaceKind, BrowserColumnSurfaceDefinition>);
-
 export function resolveBrowserColumnSurface(
   tab: BrowserColumnTab,
   readOnly: boolean,
@@ -489,6 +103,9 @@ export function resolveBrowserColumnSurface(
     tabId: tab.id,
   };
   switch (tab.target.kind) {
+    case 'folder-collection':
+      return { ...base, kind: 'collection', notebookId: tab.target.notebookId,
+        notebookPath: tab.target.notebookPath, folderPath: tab.target.folderPath, folderName: tab.target.folderName };
     case 'media':
       return {
         ...base,
@@ -507,10 +124,15 @@ export function resolveBrowserColumnSurface(
           isExternalDocument: true,
           externalScopePath: target.scopePath,
           documentSessionMode: 'isolated',
+          workspaceHost: 'browser-column',
           readOnly, onFlushReady, toolbarCollapsed, onToolbarCollapsedChange,
         },
         onSelectFile: (path) => { void selectBrowserColumnFile(tab.id, path); },
-        onOpenFileInNewTab: (path) => { void openBrowserColumnTarget({ ...target, activeFilePath: path, collectionDisplay: undefined, folderPath: null }, 'open-in-column'); },
+        onOpenFileInNewTab: (path) => { void openWorkspaceSurface({
+          host: 'browser-column',
+          target: { ...target, activeFilePath: path, collectionDisplay: undefined, folderPath: null },
+          options: { browserDisposition: 'open-in-column' },
+        }); },
         onContextChange: (patch) => useBrowserColumnStore.getState().updateFileBrowserContext(tab.id, patch),
         onSelectFolder: (path) => { void selectBrowserColumnFile(tab.id, null, path); },
         onTreeVisibleChange: (visible) => useBrowserColumnStore.getState().setFileBrowserTreeVisible(tab.id, visible),
@@ -539,32 +161,86 @@ export function resolveBrowserColumnSurface(
   }
 }
 
-export function getBrowserColumnSurfaceDefinition(
-  surface: BrowserColumnSurface,
-): BrowserColumnSurfaceDefinition {
-  return browserColumnSurfaceRegistry[surface.kind];
+function browserSurfaceData(surface: BrowserColumnSurface): WorkspaceSurfaceRendererData {
+  switch (surface.kind) {
+    case 'collection': return { kind: 'collection', notebookId: surface.notebookId,
+      notebookPath: surface.notebookPath, folderPath: surface.folderPath, folderName: surface.folderName };
+    case 'media': return { kind: 'media', fileIdentity: surface.fileIdentity, notebookPath: surface.notebookPath,
+      notebookId: surface.notebookId, resourceKind: surface.resourceKind };
+    case 'agent-conversation': return { kind: 'agent-conversation', instanceId: surface.instanceId };
+    case 'web': return { kind: 'web', url: surface.url, title: surface.title, runtime: surface.runtime };
+    case 'file-browser': return { kind: 'file-browser', props: surface };
+  }
 }
 
-export function browserColumnSurfaceSupports(
-  surface: BrowserColumnSurface,
-  capability: BrowserColumnSurfaceCapability,
-): boolean {
-  return getBrowserColumnSurfaceDefinition(surface).capabilities.includes(capability);
+function createBrowserWebNavigationPort(tabId: string): WorkspaceWebNavigationPort {
+  return {
+    getRuntime: () => useBrowserColumnStore.getState().webRuntimes[tabId] ?? null,
+    setRuntime: (runtime) => useBrowserColumnStore.getState().setWebRuntime(tabId, runtime),
+    navigate: (url) => { useBrowserColumnStore.getState().navigateWebTab(tabId, url); },
+    back: () => { useBrowserColumnStore.getState().goBackWebTab(tabId); },
+    forward: () => { useBrowserColumnStore.getState().goForwardWebTab(tabId); },
+    reload: () => { useBrowserColumnStore.getState().reloadWebTab(tabId); },
+    updateMetadata: (metadata) => useBrowserColumnStore.getState().updateTabMetadata(tabId, metadata),
+  };
 }
 
-export function BrowserColumnSurfaceHost({ surface }: { surface: BrowserColumnSurface }) {
-  const instanceKey = `${surface.kind}:${surface.instanceKey}`;
-  const definition = getBrowserColumnSurfaceDefinition(surface);
-  return (
-    <SurfaceSuspenseHost
-      instanceKey={instanceKey}
-      loadingTone={definition.chrome}
-    >
-      <BrowserColumnSurfaceMount surface={surface} />
-    </SurfaceSuspenseHost>
-  );
+function BrowserRegisteredSurfaceView({ surface, focused }: { surface: BrowserColumnSurface; focused: boolean }) {
+  const presentationIdentity = surface.kind === 'collection'
+    ? `${surface.notebookId}:${surface.folderPath}`
+    : surface.kind === 'file-browser'
+    ? `${surface.fileIdentity?.displayId ?? ''}:${surface.activeFilePath ?? surface.folderPath ?? 'folder'}:${surface.collectionType ?? ''}`
+    : surface.kind === 'media'
+      ? surface.fileIdentity.displayId
+      : surface.kind === 'web'
+        ? canonicalUrl(surface.url) ?? surface.url
+      : surface.instanceId;
+  const presentationOwner = useMemo(() => ({}), [surface.tabId, presentationIdentity]);
+  const webNavigation = useMemo(() => surface.kind === 'web' ? createBrowserWebNavigationPort(surface.tabId) : undefined,
+    [surface.kind, surface.tabId]);
+  const onCollectionActiveViewChange = useCallback((viewId: string) => {
+    const tab = useBrowserColumnStore.getState().tabs.find((candidate) => candidate.id === surface.tabId);
+    if (tab?.target.kind !== 'file-browser' || !tab.target.collectionDisplay) return;
+    const { notebookId, collectionId } = tab.target.collectionDisplay;
+    setCollectionActiveView({ host: 'browser-column', tabId: surface.tabId }, { notebookId, collectionId }, viewId);
+  }, [surface.tabId]);
+  const reportPresentation = useCallback((update: SurfacePresentationUpdate) => {
+    const accepted = reportWorkspaceSurfacePresentation(surface.tabId, update, presentationOwner);
+    if (!accepted) return;
+    if (update.title !== undefined || update.icon !== undefined) {
+      const metadata: { title?: string; icon?: string | null } = {};
+      if (update.title !== undefined) metadata.title = update.title;
+      if (update.icon !== undefined) metadata.icon = update.icon;
+      useBrowserColumnStore.getState().updateTabMetadata(surface.tabId, metadata);
+    }
+  }, [presentationOwner, surface.tabId]);
+  const registerLifecycle = useCallback((lifecycle: SurfaceLifecycle | null, owner?: object) => {
+    registerWorkspaceSurfaceLifecycle(surface.tabId, lifecycle, owner);
+  }, [surface.tabId]);
+  useLayoutEffect(() => registerWorkspaceSurfaceHostView('browser-column', surface.tabId), [surface.tabId]);
+  useLayoutEffect(() => registerWorkspaceSurfacePresentationOwner(surface.tabId, presentationOwner),
+    [presentationOwner, surface.tabId]);
+  return <WorkspaceSurfaceRendererView
+    surface={browserSurfaceData(surface)}
+    context={{ host: 'browser-column', viewId: surface.tabId, focused,
+      initialFocus: surface.kind === 'file-browser' ? surface.documentProps.initialFocus : undefined,
+      webNavigation, onCollectionActiveViewChange,
+      readOnly: surface.kind === 'file-browser' && Boolean(surface.documentProps.readOnly),
+      reportPresentation, registerLifecycle }}
+  />;
+}
+
+/** Browser provides view data and navigation ports; all kinds use the common registry. */
+export function getBrowserColumnSurfaceDefinition(surface: BrowserColumnSurface): BrowserColumnSurfaceDefinition {
+  const definition = getWorkspaceSurfaceRendererDefinition(browserSurfaceData(surface));
+  return { appearance: definition.appearance, chrome: definition.appearance.headerStyle,
+    capabilities: definition.capabilities, render: () => <BrowserRegisteredSurfaceView surface={surface} focused={false} /> };
+}
+
+export function browserColumnSurfaceSupports(surface: BrowserColumnSurface, capability: BrowserColumnSurfaceCapability): boolean {
+  return getBrowserColumnSurfaceDefinition(surface).capabilities.includes(capability);
 }
 
-function BrowserColumnSurfaceMount({ surface }: { surface: BrowserColumnSurface }) {
-  return getBrowserColumnSurfaceDefinition(surface).render(surface);
+export function BrowserColumnSurfaceHost({ surface, focused = false }: { surface: BrowserColumnSurface; focused?: boolean }) {
+  return <BrowserRegisteredSurfaceView key={`${surface.kind}:${surface.instanceKey}`} surface={surface} focused={focused} />;
 }
diff --git a/app/flowix-web/features/surface/document-list-view-model.ts b/app/flowix-web/features/surface/document-list-view-model.ts
new file mode 100644
index 000000000..50886c006
--- /dev/null
+++ b/app/flowix-web/features/surface/document-list-view-model.ts
@@ -0,0 +1,10 @@
+/** Internal inputs for document list UI; not a registered workspace surface. */
+export interface DocumentListViewContext {
+  displayId: string;
+  folderPath: string;
+  notebookPath: string;
+  notebookId: string | null;
+  filters: { resourceKinds?: string[]; tags?: string[]; customFilterId?: string };
+  mediaScope?: { relativePath: string; depth: 'direct_children' | 'descendants' };
+  mediaDatasetActive?: boolean;
+}
diff --git a/app/flowix-web/features/surface/document-list-view.test.tsx b/app/flowix-web/features/surface/document-list-view.test.tsx
index f6e7edc84..d96fd92d5 100644
--- a/app/flowix-web/features/surface/document-list-view.test.tsx
+++ b/app/flowix-web/features/surface/document-list-view.test.tsx
@@ -3,7 +3,7 @@ import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { DocumentPage, MediaResourcePage } from '@platform/tauri/client';
 import { DocumentListView } from './document-list-view';
-import type { DocumentListSurface } from './types';
+import type { DocumentListViewContext } from './document-list-view-model';
 
 const probe = vi.hoisted(() => ({
   read: vi.fn<(request: unknown) => Promise<DocumentPage>>(),
@@ -27,8 +27,8 @@ class RequestLoopBoundary extends Component<{ children: ReactNode }, { failed: b
   render() { return this.state.failed ? <div>Directory request loop</div> : this.props.children; }
 }
 
-const surface: DocumentListSurface = {
-  kind: 'document-list', instanceKey: 'folder', displayId: 'folder',
+const listContext: DocumentListViewContext = {
+  displayId: 'folder',
   folderPath: '/notes/empty', notebookPath: '/notes', notebookId: 'notes', filters: {},
 };
 const emptyPage: DocumentPage = { folders: [], items: [], nextCursor: null, hasMore: false };
@@ -72,9 +72,9 @@ describe('DocumentListView folder loading', () => {
     });
   }
 
-  async function render(nextSurface = surface) {
+  async function render(nextSurface = listContext) {
     await act(async () => root.render(
-      <RequestLoopBoundary><DocumentListView surface={nextSurface} /></RequestLoopBoundary>,
+      <RequestLoopBoundary><DocumentListView listContext={nextSurface} /></RequestLoopBoundary>,
     ));
   }
 
@@ -105,7 +105,7 @@ describe('DocumentListView folder loading', () => {
     expect(host.textContent).not.toContain('正在整理文件列表');
 
     respondWith(Promise.resolve(emptyPage));
-    await render({ ...surface, displayId: 'other', folderPath: '/notes/other' });
+    await render({ ...listContext, displayId: 'other', folderPath: '/notes/other' });
     expect(probe.read).toHaveBeenCalledTimes(2);
     expect(probe.read).toHaveBeenLastCalledWith(expect.objectContaining({ folderPath: '/notes/other' }));
     expect(host.textContent).toContain('列表内容为空');
@@ -114,12 +114,12 @@ describe('DocumentListView folder loading', () => {
 
   it('keeps folder media visible through a rename and coalesces a large event burst', async () => {
     probe.mediaRead.mockResolvedValueOnce(mediaPage('before'));
-    const mediaSurface = (folder: string): DocumentListSurface => ({
-      ...surface, displayId: 'folder-library', filters: { resourceKinds: ['image'] },
+    const mediaSurface = (folder: string): DocumentListViewContext => ({
+      ...listContext, displayId: 'folder-library', filters: { resourceKinds: ['image'] },
       mediaScope: { relativePath: folder, depth: 'descendants' },
     });
     const renderLibrary = async (folder: string, paused = false) => {
-      await act(async () => root.render(<DocumentListView surface={mediaSurface(folder)} mediaLibrary libraryActionsDisabled={paused} refreshPaused={paused} />));
+      await act(async () => root.render(<DocumentListView listContext={mediaSurface(folder)} mediaLibrary libraryActionsDisabled={paused} refreshPaused={paused} />));
     };
     await renderLibrary('before');
     // A containing-folder source must work without explicit records or a path filter.
@@ -158,11 +158,11 @@ describe('DocumentListView folder loading', () => {
 
   it('recovers an early empty query when media index reconciliation completes without changing filters', async () => {
     probe.mediaRead.mockResolvedValueOnce({ resources: [], nextCursor: null, hasMore: false });
-    const scopedSurface: DocumentListSurface = {
-      ...surface, displayId: 'reconciled-library', filters: { resourceKinds: ['image'] },
+    const scopedSurface: DocumentListViewContext = {
+      ...listContext, displayId: 'reconciled-library', filters: { resourceKinds: ['image'] },
       mediaScope: { relativePath: 'renamed', depth: 'descendants' },
     };
-    await act(async () => root.render(<DocumentListView surface={scopedSurface} mediaLibrary />));
+    await act(async () => root.render(<DocumentListView listContext={scopedSurface} mediaLibrary />));
     expect(probe.mediaRead).toHaveBeenCalledTimes(1);
     expect(host.textContent).toContain('列表内容为空');
     expect(host.textContent).not.toContain('未设置数据集合');
@@ -177,11 +177,11 @@ describe('DocumentListView folder loading', () => {
 
   it('loads a readable library when its actions are disabled', async () => {
     probe.mediaRead.mockResolvedValue(mediaPage('readonly'));
-    const scopedSurface: DocumentListSurface = {
-      ...surface, displayId: 'readonly-library', filters: { resourceKinds: ['image'] },
+    const scopedSurface: DocumentListViewContext = {
+      ...listContext, displayId: 'readonly-library', filters: { resourceKinds: ['image'] },
       mediaScope: { relativePath: 'readonly', depth: 'descendants' },
     };
-    await act(async () => root.render(<DocumentListView surface={scopedSurface} mediaLibrary libraryActionsDisabled />));
+    await act(async () => root.render(<DocumentListView listContext={scopedSurface} mediaLibrary libraryActionsDisabled />));
     expect(probe.mediaRead).toHaveBeenCalledTimes(1);
     expect(host.querySelector('[title="photo.png"]')).not.toBeNull();
   });
diff --git a/app/flowix-web/features/surface/document-list-view.tsx b/app/flowix-web/features/surface/document-list-view.tsx
index 55845ce6d..17190c202 100644
--- a/app/flowix-web/features/surface/document-list-view.tsx
+++ b/app/flowix-web/features/surface/document-list-view.tsx
@@ -13,7 +13,7 @@ import { useI18n } from '@/lib/i18n';
 import { matchesMediaCollectionFilter, normalizeMediaLibraryFileCondition, type MediaLibraryFileCondition, type MediaLibraryRecord } from '@features/media-library/model';
 import { NotebookTreeFileIcon } from '@features/memo/components/notebook-tree-file-icon';
 import { NotebookTreeResourceIcon } from '@features/memo/components/file-type-icon';
-import type { DocumentListSurface } from './types';
+import type { DocumentListViewContext } from './document-list-view-model';
 import { useDocumentListData } from './use-document-list-data';
 import { OverlayScrollbar } from '@shared/ui/overlay-scrollbar';
 import { requestMediaPreview } from './media-preview-tasks';
@@ -30,6 +30,8 @@ import folderCardPlaceholder from '@/assets/placeholder-folder-card.png';
 
 // Keep the loading effect stable when ordinary folders omit media records.
 const EMPTY_MEDIA_LIBRARY_RECORDS: MediaLibraryRecord[] = [];
+const MEDIA_CARD_MIN_WIDTH = 160;
+const MEDIA_COLUMN_GAP = 2;
 
 function cardPlaceholder(item: DocumentPageItem): string {
   if (item.resourceKind === 'folder') return folderCardPlaceholder;
@@ -195,8 +197,8 @@ const DocumentCard = memo(function DocumentCard({ item, notebookPath, openItem,
   </button>;
 });
 
-export function DocumentListView({ surface, mediaLibrary = false, libraryName = '媒体库', libraryFilePath, mediaLibraryFolderPath, mediaLibraryFilter = {}, mediaLibraryRecords = EMPTY_MEDIA_LIBRARY_RECORDS, mediaLibraryExcludedPaths = [], mediaLibraryDatasetFilter, mediaLibraryViewFilter, onMediaLibraryFilterChange, onRenameLibrary, onAddMedia, onDeleteMedia, onSwitchToTable, libraryActionsDisabled = false, refreshPaused = false }: {
-  surface: DocumentListSurface;
+export function DocumentListView({ listContext, mediaLibrary = false, libraryName = '媒体库', libraryFilePath, mediaLibraryFolderPath, mediaLibraryFilter = {}, mediaLibraryRecords = EMPTY_MEDIA_LIBRARY_RECORDS, mediaLibraryExcludedPaths = [], mediaLibraryDatasetFilter, mediaLibraryViewFilter, onMediaLibraryFilterChange, onRenameLibrary, onAddMedia, onDeleteMedia, onSwitchToTable, libraryActionsDisabled = false, refreshPaused = false, workspaceHost = 'main-third' }: {
+  listContext: DocumentListViewContext;
   mediaLibrary?: boolean;
   libraryName?: string;
   libraryFilePath?: string;
@@ -213,13 +215,14 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
   onSwitchToTable?: () => void;
   libraryActionsDisabled?: boolean;
   refreshPaused?: boolean;
+  workspaceHost?: 'main-third' | 'browser-column';
 }) {
   const { t } = useI18n();
-  const resourceKindsKey = (surface.filters.resourceKinds ?? []).join('\u0000');
+  const resourceKindsKey = (listContext.filters.resourceKinds ?? []).join('\u0000');
   const {
     items, linkedItems, folders, hasMediaDataset, hasLinkedMedia, loading, loadingLinkedItems,
     moreError, hasMore, error, loadMore, refresh,
-  } = useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords, refreshPaused });
+  } = useDocumentListData({ listContext, mediaLibrary, mediaLibraryRecords, refreshPaused });
   const [addingMedia, setAddingMedia] = useState(false);
   const [mediaToDelete, setMediaToDelete] = useState<DocumentPageItem | null>(null);
   const [deletingMedia, setDeletingMedia] = useState(false);
@@ -318,16 +321,16 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
   }, [mediaLibrary]);
   useEffect(() => {
     scrollRef.current?.scrollTo(0, 0);
-  }, [surface.displayId]);
+  }, [listContext.displayId]);
   useEffect(() => {
     if (!mediaLibrary) return;
     scrollRef.current?.scrollTo(0, 0);
   }, [mediaLibrary, mediaLibraryFilter.file_name_contains, mediaLibraryFilter.file_type, mediaLibraryFilter.path_contains, resourceKindsKey]);
   useEffect(() => {
-    if (!folderPickerOpen || !surface.notebookPath) return;
+    if (!folderPickerOpen || !listContext.notebookPath) return;
     let active = true;
     setFolderOptionsLoading(true);
-    void files.getNotebookFolderOptions(surface.notebookPath).then((options) => {
+    void files.getNotebookFolderOptions(listContext.notebookPath).then((options) => {
       if (active) setFolderOptions(options);
     }).catch(() => {
       if (active) setFolderOptions([]);
@@ -335,7 +338,7 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
       if (active) setFolderOptionsLoading(false);
     });
     return () => { active = false; };
-  }, [folderPickerOpen, surface.notebookPath]);
+  }, [folderPickerOpen, listContext.notebookPath]);
   const [createOpen, setCreateOpen] = useState(false);
   const [newTitle, setNewTitle] = useState('');
   const [creating, setCreating] = useState(false);
@@ -359,13 +362,13 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
   const excludedMediaPathSet = new Set(mediaLibraryExcludedPaths.map((path) => path.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '').toLocaleLowerCase()));
   const visibleItems = mediaLibrary
     ? [...new Map([
-      ...linkedItems.filter((item) => !excludedMediaPathSet.has(mediaItemRelativePath(item.fullPath, surface.notebookPath).toLocaleLowerCase())
-        && matchesMediaRuleFilter(item, surface.notebookPath, mediaLibraryViewFilter)),
+      ...linkedItems.filter((item) => !excludedMediaPathSet.has(mediaItemRelativePath(item.fullPath, listContext.notebookPath).toLocaleLowerCase())
+        && matchesMediaRuleFilter(item, listContext.notebookPath, mediaLibraryViewFilter)),
       ...(hasMediaDataset ? items.filter((item) => (
         (item.resourceKind === 'image' || item.resourceKind === 'video')
-        && !excludedMediaPathSet.has(mediaItemRelativePath(item.fullPath, surface.notebookPath).toLocaleLowerCase())
-        && matchesMediaRuleFilter(item, surface.notebookPath, mediaLibraryDatasetFilter)
-        && matchesMediaRuleFilter(item, surface.notebookPath, mediaLibraryViewFilter)
+        && !excludedMediaPathSet.has(mediaItemRelativePath(item.fullPath, listContext.notebookPath).toLocaleLowerCase())
+        && matchesMediaRuleFilter(item, listContext.notebookPath, mediaLibraryDatasetFilter)
+        && matchesMediaRuleFilter(item, listContext.notebookPath, mediaLibraryViewFilter)
       )) : []),
     ].map((item) => [canonicalPath(item.fullPath), item])).values()]
     : [...folders, ...items];
@@ -409,7 +412,7 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
       folderPickerOpen={folderPickerOpen}
       folderOptions={folderOptions}
       folderOptionsLoading={folderOptionsLoading}
-      notebookAvailable={Boolean(surface.notebookPath)}
+      notebookAvailable={Boolean(listContext.notebookPath)}
       autoFocus={!locationOnly}
       locationOnly={locationOnly}
       showLocationMenu={false}
@@ -444,58 +447,70 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
     }
   }, [deletingMedia, mediaToDelete, onDeleteMedia, t]);
   const columnCount = Math.max(1, Math.floor((viewport.width + 14) / 214));
+  const mediaColumnCount = Math.min(
+    Math.max(1, Math.floor((viewport.width + MEDIA_COLUMN_GAP) / (MEDIA_CARD_MIN_WIDTH + MEDIA_COLUMN_GAP))),
+    Math.max(1, visibleItems.length),
+  );
+  const mediaColumns: DocumentPageItem[][] = Array.from({ length: mediaColumnCount }, () => []);
+  // Appending a page keeps existing cards in their columns while the column count is unchanged.
+  visibleItems.forEach((item, index) => mediaColumns[index % mediaColumnCount].push(item));
   const rowHeight = 224;
   const rowCount = Math.ceil(visibleItems.length / columnCount);
   const firstRow = Math.min(Math.max(0, rowCount - 1), Math.max(0, Math.floor(viewport.top / rowHeight) - 2));
   const lastRow = Math.min(rowCount, Math.ceil((viewport.top + viewport.height) / rowHeight) + 2);
   const visibleCards = visibleItems.slice(firstRow * columnCount, lastRow * columnCount);
-  const folderTitle = surface.folderPath.replace(/[\\/]+$/, '').split(/[\\/]/).pop() || surface.folderPath;
+  const folderTitle = listContext.folderPath.replace(/[\\/]+$/, '').split(/[\\/]/).pop() || listContext.folderPath;
   const createNote = useCallback(async () => {
     const title = newTitle.trim();
-    if (!title || creating || !surface.notebookId) return;
+    if (!title || creating || !listContext.notebookId) return;
     setCreating(true);
     try {
       let path: string;
       const { noteRepository } = await import('@features/memo/services/note-repository');
-      const root = canonicalPath(surface.notebookPath).replace(/\/$/, '');
-      const folder = canonicalPath(surface.folderPath).replace(/\/$/, '');
+      const root = canonicalPath(listContext.notebookPath).replace(/\/$/, '');
+      const folder = canonicalPath(listContext.folderPath).replace(/\/$/, '');
       const relative = folder === root ? '' : folder.slice(root.length + 1);
-      const created = await noteRepository.create(undefined, surface.notebookId, relative, title);
+      const created = await noteRepository.create(undefined, listContext.notebookId, relative, title);
       path = created.path;
       setCreateOpen(false);
       setNewTitle('');
       refresh();
-      const { openExternalTarget } = await import('@features/workspace/use-cases/workspace-navigation');
-      await openExternalTarget(path, { destination: 'main-third', scopePath: surface.notebookPath });
+      const { openWorkspaceSurface } = await import('@features/workspace/public/open-surface-api');
+      await openWorkspaceSurface({
+        host: 'main-third',
+        target: { kind: 'external', path, scopePath: listContext.notebookPath, transitionId: null },
+      });
     } catch {
       toast.error('新建笔记失败');
     } finally {
       setCreating(false);
     }
-  }, [creating, newTitle, surface.folderPath, surface.notebookId, surface.notebookPath]);
+  }, [creating, newTitle, listContext.folderPath, listContext.notebookId, listContext.notebookPath]);
   const openItem = useCallback(async (item: DocumentPageItem) => {
     try {
       if (item.resourceKind === 'folder') {
-        const [{ openDocumentListTarget }, { createDocumentListTarget }] = await Promise.all([
-          import('@features/workspace/use-cases/workspace-navigation'),
-          import('@features/workspace/store/work-column-target'),
-        ]);
-        openDocumentListTarget(createDocumentListTarget({
-          kind: 'folder', path: item.fullPath, notebookPath: surface.notebookPath, notebookId: surface.notebookId,
-        }, {}));
+        if (!listContext.notebookId) throw new Error('无法确定文件夹所属笔记本');
+        const { openFolderCollectionFromFolder } = await import('@features/workspace/public/main-window-api');
+        await openFolderCollectionFromFolder(listContext.notebookId, item.fullPath, workspaceHost);
         return;
       }
-      const { openExternalTarget, openMediaTarget } = await import('@features/workspace/use-cases/workspace-navigation');
+      const { openWorkspaceSurface } = await import('@features/workspace/public/open-surface-api');
       const kind = item.resourceKind ?? resourceKindFromPath(item.fullPath);
       if (kind === 'image' || kind === 'video') {
-        await openMediaTarget({ filePath: item.fullPath, notebookId: surface.notebookId, notebookPath: surface.notebookPath, resourceKind: kind });
+        await openWorkspaceSurface({ host: 'browser-column', target: {
+          kind: 'media', filePath: item.fullPath, notebookId: listContext.notebookId,
+          notebookPath: listContext.notebookPath, resourceKind: kind,
+        }, options: { browserDisposition: 'focus-existing' } });
       } else {
-        await openExternalTarget(item.fullPath, { destination: 'main-third', scopePath: surface.notebookPath });
+        await openWorkspaceSurface({
+          host: 'main-third',
+          target: { kind: 'external', path: item.fullPath, scopePath: listContext.notebookPath, transitionId: null },
+        });
       }
     } catch {
       toast.error('打开文件失败');
     }
-  }, [surface.notebookId, surface.notebookPath]);
+  }, [listContext.notebookId, listContext.notebookPath, workspaceHost]);
   return <section className="flex h-full min-h-0 flex-col bg-transparent text-[var(--foreground)]">
     <OverlayScrollbar
       className="flex h-full min-h-0 min-w-0 flex-1"
@@ -540,7 +555,7 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
               className="inline-flex min-w-[2em] flex-[0_1_auto] items-center truncate rounded border-0 bg-transparent px-0.5 py-1 text-left text-sm font-medium leading-none text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] disabled:opacity-100"
             >{libraryName}</button>}
             {renamingLibraryTitle && <span role="status" aria-label={t('memo.fileTree.renaming')} className="inline-flex shrink-0 items-center text-[var(--muted-foreground)]">
-              <LoaderCircle className="h-3.5 w-3.5 animate-spin" aria-hidden="true" />
+              <LoaderCircle className="h-3.5 w-3.5 flowix-spin" aria-hidden="true" />
             </span>}
           </div>
           {onSwitchToTable && <>
@@ -586,21 +601,25 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
                 ><FunnelIcon size={14} weight="bold" aria-hidden="true" /></Button>
               </PopoverTrigger>
               <PopoverContent align="end" side="bottom" sideOffset={0} fitViewport style={{ zIndex: 150 }} ignorePopoverOutside={folderPickerOpen || mediaDataFiltersOpen} className="w-[220px] max-w-[calc(100vw-16px)] rounded-xl p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-                {renderMediaFilterPanel(true)}
-                <Popover open={mediaDataFiltersOpen} onOpenChange={setMediaDataFiltersOpen}>
-                  <PopoverTrigger asChild>
-                    <button type="button" className="flex h-8 w-full items-center justify-between rounded-lg px-1.5 text-left text-sm hover:bg-[var(--hover-bg)]">
-                      <span>数据条件</span>
-                      <span className="flex items-center gap-1 text-xs text-[var(--muted-foreground)]">
-                        {mediaNameQuery.trim() || mediaTypeQuery !== 'any' ? '已设置' : '未设置'}
-                        <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
-                      </span>
-                    </button>
-                  </PopoverTrigger>
-                  <PopoverContent side="right" align="start" sideOffset={0} fitViewport style={{ zIndex: 160 }} ignorePopoverOutside={folderPickerOpen} className="max-h-[min(70vh,420px)] w-[320px] max-w-[calc(100vw-16px)] overflow-y-auto rounded-xl px-1 py-2 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
-                    {renderMediaFilterPanel(false)}
-                  </PopoverContent>
-                </Popover>
+                <div className="space-y-0.5">
+                  {renderMediaFilterPanel(true)}
+                  <Popover open={mediaDataFiltersOpen} onOpenChange={setMediaDataFiltersOpen}>
+                    <div className={`rounded-lg transition-colors ${mediaDataFiltersOpen ? 'bg-[var(--hover-bg)]' : 'hover:bg-[var(--hover-bg)]'}`}>
+                      <PopoverTrigger asChild>
+                        <button type="button" className="flex h-8 w-full items-center justify-between rounded-lg px-1.5 text-left text-sm">
+                          <span>数据条件</span>
+                          <span className="flex items-center gap-1 text-sm text-[var(--muted-foreground)]">
+                            {mediaNameQuery.trim() || mediaTypeQuery !== 'any' ? '已设置' : '未设置'}
+                            <ChevronRight className="h-3.5 w-3.5" aria-hidden="true" />
+                          </span>
+                        </button>
+                      </PopoverTrigger>
+                    </div>
+                    <PopoverContent side="left" align="start" sideOffset={0} fitViewport style={{ zIndex: 160 }} ignorePopoverOutside={folderPickerOpen} className="max-h-[min(70vh,420px)] w-[320px] max-w-[calc(100vw-16px)] overflow-y-auto rounded-xl p-1.5 shadow-[0_4px_24px_-3px_rgb(0_0_0_/_0.24)]">
+                      {renderMediaFilterPanel(false)}
+                    </PopoverContent>
+                  </Popover>
+                </div>
               </PopoverContent>
             </Popover>
             {onAddMedia && <Button
@@ -624,7 +643,7 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
         ><Folder className="h-3.5 w-3.5" aria-hidden="true" /><span className="max-w-[500px] truncate">{folderTitle}</span></button>
       </div>
       <div className="flex items-center gap-2">
-        <Button type="button" className="px-3" onClick={() => setCreateOpen(true)} disabled={!surface.notebookId}>{t('memo.documentList.new')}</Button>
+        <Button type="button" className="px-3" onClick={() => setCreateOpen(true)} disabled={!listContext.notebookId}>{t('memo.documentList.new')}</Button>
       </div>
       </>}
     </div>
@@ -654,10 +673,25 @@ export function DocumentListView({ surface, mediaLibrary = false, libraryName =
           : mediaLibrary && visibleItems.length === 0 && hasMore
             ? <div className="flex h-full min-h-[160px] items-center justify-center text-sm text-[var(--muted-foreground)]">{t('mediaLibrary.searchingMore')}</div>
           : mediaLibrary
-            ? <div className="gap-0.5 pt-0" style={{ columns: '220px', columnGap: '2px', contentVisibility: 'auto', containIntrinsicSize: '1px 1000px' }}>{visibleItems.map((item) => {
-              return <div key={item.fullPath} className="break-inside-avoid py-px"><DocumentCard item={item} notebookPath={surface.notebookPath} openItem={openItem} mediaLibrary observeMediaCard={observeMediaCard} onRequestDelete={onDeleteMedia ? setMediaToDelete : undefined} deleteLabel={t('media.fileTree.delete')} deleteDisabled={libraryActionsDisabled || deletingMedia} /></div>;
-            })}</div>
-            : <div style={{ paddingTop: firstRow * rowHeight, paddingBottom: Math.max(0, rowCount - lastRow) * rowHeight }}><div className="grid w-full grid-cols-[repeat(auto-fill,minmax(min(100%,200px),1fr))] items-stretch gap-3.5 pt-3">{visibleCards.map((item) => <DocumentCard key={item.fullPath} item={item} notebookPath={surface.notebookPath} openItem={openItem} />)}</div></div>}
+            ? <div className="flex w-full items-start pt-0" style={{ gap: MEDIA_COLUMN_GAP }}>{mediaColumns.map((column, columnIndex) => (
+              <div key={columnIndex} className="flex min-w-0 flex-1 flex-col" style={{ gap: MEDIA_COLUMN_GAP }}>
+                {column.map((item) => (
+                  <div key={item.fullPath} className="min-w-0 py-px">
+                    <DocumentCard
+                      item={item}
+                      notebookPath={listContext.notebookPath}
+                      openItem={openItem}
+                      mediaLibrary
+                      observeMediaCard={observeMediaCard}
+                      onRequestDelete={onDeleteMedia ? setMediaToDelete : undefined}
+                      deleteLabel={t('media.fileTree.delete')}
+                      deleteDisabled={libraryActionsDisabled || deletingMedia}
+                    />
+                  </div>
+                ))}
+              </div>
+            ))}</div>
+            : <div style={{ paddingTop: firstRow * rowHeight, paddingBottom: Math.max(0, rowCount - lastRow) * rowHeight }}><div className="grid w-full grid-cols-[repeat(auto-fill,minmax(min(100%,200px),1fr))] items-stretch gap-3.5 pt-3">{visibleCards.map((item) => <DocumentCard key={item.fullPath} item={item} notebookPath={listContext.notebookPath} openItem={openItem} />)}</div></div>}
       {moreError && <button type="button" className="mt-4 rounded-lg px-2 py-1 text-sm text-[var(--brand)] hover:bg-[var(--muted)]" onClick={loadMore}>加载失败，点击重试</button>}
       {hasMore && !moreError && <div ref={endRef} className="h-1" aria-hidden="true" />}
     </OverlayScrollbar>
diff --git a/app/flowix-web/features/surface/file-browser-view.test.tsx b/app/flowix-web/features/surface/file-browser-view.test.tsx
index 9d5cfc3e1..f2509f607 100644
--- a/app/flowix-web/features/surface/file-browser-view.test.tsx
+++ b/app/flowix-web/features/surface/file-browser-view.test.tsx
@@ -2,7 +2,7 @@ import { act, useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
 import { expect, it, vi } from 'vitest';
 import { FileBrowserView, type FileBrowserViewSurface } from './file-browser-view';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
+import { useAgentWorkspaceStore, type AgentWorkspaceState } from '@features/agent/store/agent-workspace-store';
 import { useNoteStore } from '@features/memo/store';
 import { DocumentContainer } from '@features/document/components/document-container';
 
@@ -33,9 +33,9 @@ vi.mock('@platform/tauri/event-bus', () => ({ subscribe: () => () => {} }));
 it('derives the tree from the owning notebook without remounting or changing file access scope', async () => {
   const environment = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
   environment.IS_REACT_ACT_ENVIRONMENT = true;
-  const previousConfig = useAgentAccessStore.getState().config;
+  const previousWorkspace = useAgentWorkspaceStore.getState().workspace;
   const previousNotebookId = useNoteStore.getState().selectedNotebookId;
-  useAgentAccessStore.setState({ config: { version: 1, entries: [], defaults: {} }, notebookConfigs: {} });
+  setWorkspace({ byNotebookId: {} });
   probe.mounts = 0;
   const element = document.createElement('div');
   const root = createRoot(element);
@@ -58,13 +58,11 @@ it('derives the tree from the owning notebook without remounting or changing fil
     expect(editor).not.toBeNull();
     expect(element.querySelector('[data-tree-root]')).toBeNull();
     expect(flushReady).toHaveBeenCalledWith(probe.flush);
-    await act(async () => useAgentAccessStore.setState({
-      config: { version: 1, entries: [
-        { id: 'src', kind: 'folder', path: '/workspace/src', name: 'src', enabled: true, workspace: false, missing: false, addedAt: 0, updatedAt: 0 },
-      ], defaults: {} },
-      notebookConfigs: { owner: { version: 1, revision: 1, addDirs: [
-        { id: 'src', path: '/workspace/src', label: 'src', enabled: true },
-      ] } },
+    await act(async () => setWorkspace({
+      byNotebookId: { owner: {
+        notebook: { id: 'owner', name: 'Owner', path: '/notes/owner' },
+        addDirs: [{ id: 'src', path: '/workspace/src', label: 'src', enabled: true, missing: false }],
+      } },
     }));
     expect(element.querySelector('[data-tree-root]')?.getAttribute('data-tree-root')).toBe('/workspace/src');
     await act(async () => useNoteStore.setState({ selectedNotebookId: 'unrelated' }));
@@ -75,7 +73,7 @@ it('derives the tree from the owning notebook without remounting or changing fil
     await act(async () => root.render(<FileBrowserView surface={{ ...surface, fileTreeVisible: false }} />));
     expect(element.querySelector('[data-tree-root]')).toBeNull();
     expect(element.querySelector('[title="展开文件树"]')).not.toBeNull();
-    await act(async () => useAgentAccessStore.setState({ config: { version: 1, entries: [], defaults: {} }, notebookConfigs: {} }));
+    await act(async () => setWorkspace({ byNotebookId: {} }));
     expect(element.querySelector('[title="展开文件树"]')).toBeNull();
     expect(element.querySelector('textarea')).toBe(editor);
     expect(editor?.value).toBe('unsaved draft');
@@ -83,8 +81,14 @@ it('derives the tree from the owning notebook without remounting or changing fil
     expect(probe.scope).toBe('/granted-scope');
   } finally {
     await act(async () => root.unmount());
-    useAgentAccessStore.setState({ config: previousConfig });
+    setWorkspace(previousWorkspace);
     useNoteStore.setState({ selectedNotebookId: previousNotebookId });
     environment.IS_REACT_ACT_ENVIRONMENT = false;
   }
 });
+
+function setWorkspace(update: Partial<AgentWorkspaceState> | ((state: AgentWorkspaceState) => Partial<AgentWorkspaceState>)) {
+  const store = useAgentWorkspaceStore.getState();
+  const patch = typeof update === "function" ? update(store.workspace) : update;
+  useAgentWorkspaceStore.setState({ workspace: { ...store.workspace, ...patch } });
+}
diff --git a/app/flowix-web/features/surface/file-browser-view.tsx b/app/flowix-web/features/surface/file-browser-view.tsx
index 4ebfdf6f7..58f3fb225 100644
--- a/app/flowix-web/features/surface/file-browser-view.tsx
+++ b/app/flowix-web/features/surface/file-browser-view.tsx
@@ -5,8 +5,7 @@ import { FolderFileTree } from '@features/memo/components/folder-file-tree';
 import { useFolderTree } from '@features/memo/components/use-folder-tree';
 import { useNoteStore } from '@features/memo/store';
 import type { FileBrowserContext } from '@features/workspace/store/file-browser-target';
-import { useAgentAccessStore } from '@features/agent/store/agent-access-store';
-import { resolveNotebookAgentFiles } from '@/lib/agent-access-defaults';
+import { useAgentWorkspaceStore } from '@features/agent/store/agent-workspace-store';
 import { toast } from '@/lib/toast';
 import { useI18n } from '@/lib/i18n';
 import { openPath } from '@platform/tauri/opener';
@@ -322,67 +321,57 @@ function BrowserBreadcrumbs({
 
 export function FileBrowserView({ surface: input }: { surface: FileBrowserViewSurface }) {
   const { t } = useI18n();
-  const config = useAgentAccessStore((state) => state.config);
-  const notebookConfigs = useAgentAccessStore((state) => state.notebookConfigs);
-  const addFolderFromPicker = useAgentAccessStore((state) => state.addFolderFromPicker);
-  const setDefaultFiles = useAgentAccessStore((state) => state.setDefaultFiles);
+  const addFolderFromPicker = useAgentWorkspaceStore((state) => state.workspaceActions.addFolderFromPicker);
+  const detachFolderFromNotebook = useAgentWorkspaceStore((state) => state.workspaceActions.detachFolderFromNotebook);
   const selectedNotebookId = useNoteStore((state) => state.selectedNotebookId ?? state.selectedNotebook?.id ?? null);
   const legacyNotebookRef = useRef<string | null>(null);
   if (input.restoreNotebookContext && !legacyNotebookRef.current && selectedNotebookId) {
     legacyNotebookRef.current = selectedNotebookId;
   }
   const notebookId = input.restoreNotebookContext ? legacyNotebookRef.current : input.notebookId;
+  const workspaceNotebook = useAgentWorkspaceStore((state) =>
+    notebookId ? state.workspace.byNotebookId[notebookId] : undefined,
+  );
   useEffect(() => {
     if (input.restoreNotebookContext && notebookId) {
       input.onContextChange({ notebookId, restoreNotebookContext: false });
     }
   }, [input.restoreNotebookContext, input.onContextChange, notebookId]);
-  const defaultFiles = resolveNotebookAgentFiles(config, notebookConfigs, notebookId);
+  const availableFolders = workspaceNotebook?.addDirs
+    .filter((directory) => directory.enabled && !directory.missing)
+    .map((directory) => directory.path) ?? [];
   const root = input.activeFilePath
-    ? resolveFileBrowserRoot(input.activeFilePath, defaultFiles?.folders ?? [])
+    ? resolveFileBrowserRoot(input.activeFilePath, availableFolders)
     : input.folderPath;
   const surface = { ...input, folderPath: root ?? '' };
   const breadcrumbs = root ? resolveFileBrowserBreadcrumbItems(root, input.activeFilePath) : [];
   const currentPath = input.activeFilePath ?? input.folderPath ?? '';
-  const folderItems = (defaultFiles?.folders ?? []).map((path) => {
-    const entry = config.entries.find(
-      (candidate) => candidate.kind === 'folder'
-        && candidate.path.trim().replace(/[\\/]+$/, '').toLowerCase()
-          === path.trim().replace(/[\\/]+$/, '').toLowerCase(),
-    );
-    const trimmed = path.replace(/[\\/]+$/, '');
-    return {
-      path,
-      name: entry?.name ?? trimmed.split(/[\\/]/).pop() ?? trimmed,
-      missing: entry?.missing ?? true,
-    };
-  });
+  const folderItems = (workspaceNotebook?.addDirs ?? [])
+    .filter((directory) => directory.enabled && !directory.missing)
+    .map((directory) => {
+      const path = directory.path;
+      return {
+        path,
+        name: directory.label,
+        missing: directory.missing,
+      };
+    });
 
   const handleRemoveFolder = useCallback(async (path: string) => {
     if (!notebookId) return;
-    const latestConfig = useAgentAccessStore.getState().config;
-    const latestFiles = resolveNotebookAgentFiles(
-      latestConfig,
-      useAgentAccessStore.getState().notebookConfigs,
-      notebookId,
-    );
-    const latestFolders = latestFiles?.folders ?? [];
-    const comparable = (value: string) => value.trim().replace(/[\\/]+$/, '').toLowerCase();
-    const nextFolders = latestFolders.filter((candidate) => comparable(candidate) !== comparable(path));
-    const saved = await setDefaultFiles(notebookId, {
-      folders: nextFolders,
-      notebooks: latestFiles?.notebooks ?? [],
-    });
-    if (!saved) {
+    const saved = await detachFolderFromNotebook(notebookId, path);
+    if (saved === false) {
       toast.error(t('agent.access.saveFailed'));
       return;
     }
+    if (saved === 'not-attached') return;
+    const comparable = (value: string) => value.trim().replace(/[\\/]+$/, '').toLowerCase();
     const item = folderItems.find((candidate) => comparable(candidate.path) === comparable(path));
     toast.success(t('agent.access.folderDeleted', { name: item?.name ?? path }));
-  }, [folderItems, notebookId, setDefaultFiles, t]);
+  }, [detachFolderFromNotebook, folderItems, notebookId, t]);
 
   const handleAddFolder = useCallback(async () => {
-    const result = await addFolderFromPicker();
+    const result = await addFolderFromPicker(notebookId);
     if (!result.ok) {
       if (result.code === 'already-tracked') {
         toast.error(t('agent.access.alreadyTracked'));
@@ -391,30 +380,8 @@ export function FileBrowserView({ surface: input }: { surface: FileBrowserViewSu
       }
       return;
     }
-    if (!notebookId) return;
 
-    const latestConfig = useAgentAccessStore.getState().config;
-    const latestFiles = resolveNotebookAgentFiles(
-      latestConfig,
-      useAgentAccessStore.getState().notebookConfigs,
-      notebookId,
-    );
-    if (
-      (latestFiles?.folders ?? []).some(
-        (path) => path.trim().replace(/[\\/]+$/, '').toLowerCase()
-          === result.entry.path.trim().replace(/[\\/]+$/, '').toLowerCase(),
-      )
-    ) {
-      toast.info(t('agent.access.folderExists'));
-      return;
-    }
-    const nextFolders = Array.from(new Set([...(latestFiles?.folders ?? []), result.entry.path]));
-    const saved = await setDefaultFiles(notebookId, {
-      folders: nextFolders,
-      notebooks: latestFiles?.notebooks ?? [],
-    });
-    if (!saved) toast.error(t('agent.access.saveFailed'));
-  }, [addFolderFromPicker, notebookId, setDefaultFiles, t]);
+  }, [addFolderFromPicker, notebookId, t]);
 
   const handleCopyPath = useCallback(async () => {
     try {
@@ -479,6 +446,7 @@ export function FileBrowserView({ surface: input }: { surface: FileBrowserViewSu
             {folderItems.length > 0 && <DropdownMenuSeparator />}
             <DropdownMenuItem
               onClick={() => void handleAddFolder()}
+              disabled={!notebookId}
               className="h-7 gap-2 rounded-lg px-2 py-0 text-left text-sm text-[var(--muted-foreground)] hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)]"
             >
               <PlusIcon size={15} weight="regular" aria-hidden="true" />
diff --git a/app/flowix-web/features/surface/html-resource-view.tsx b/app/flowix-web/features/surface/html-resource-view.tsx
index 1d5da9d82..5487dfeef 100644
--- a/app/flowix-web/features/surface/html-resource-view.tsx
+++ b/app/flowix-web/features/surface/html-resource-view.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useMemo, useRef, useState, type ComponentProps, type CSSProperties } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, type ComponentProps, type CSSProperties } from 'react';
 import { CaretDownIcon, CaretUpIcon, CodeIcon, EyeIcon } from '@phosphor-icons/react';
 
 import { useI18n } from '@/lib/i18n';
@@ -8,6 +8,8 @@ import { files } from '@platform/tauri/client';
 import { DocumentContainer } from '@features/document/components/document-container';
 import { connectLocalHtmlScrollbar } from '@shared/ui/local-html-scrollbar';
 import { Tooltip } from '@shared/ui/tooltip';
+import type { SurfacePresentationUpdate } from '@features/workspace/model/surface-contract';
+import type { DocumentContentStatus } from '@features/document/components/session/types';
 
 type DocumentProps = ComponentProps<typeof DocumentContainer>;
 
@@ -23,10 +25,12 @@ export function HtmlResourceView({
   filePath,
   scopePath,
   documentProps,
+  reportPresentation,
 }: {
   filePath: string;
   scopePath: string | null;
   documentProps: DocumentProps;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
 }) {
   const { t } = useI18n();
   const [mode, setMode] = useState<'preview' | 'source'>('preview');
@@ -37,12 +41,61 @@ export function HtmlResourceView({
   const setToolbarCollapsed = documentProps.onToolbarCollapsedChange ?? setLocalToolbarCollapsed;
   const src = useMemo(() => files.toAssetUrl(filePath), [filePath]);
   const previewRef = useRef<HTMLIFrameElement>(null);
+  const [previewState, setPreviewState] = useState<'loading' | 'ready' | 'error'>('loading');
+  const [previewRetry, setPreviewRetry] = useState(0);
+  const retryPreview = useCallback(() => {
+    setPreviewState('loading');
+    setPreviewRetry((current) => current + 1);
+  }, []);
+  const onContentStateChange = useCallback((state: DocumentContentStatus) => {
+    if (mode !== 'source') return;
+    if (state.status === 'loading') {
+      reportPresentation?.({ state: {
+        status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: state.retainContent,
+      } });
+    } else if (state.status === 'missing-note') {
+      reportPresentation?.({ state: {
+        status: 'error', message: { key: 'document.load.missingNoteTitle' }, detailText: state.path,
+        actions: [
+          { id: 'retry', label: { key: 'error.retry' }, enabled: true, run: state.retry },
+          { id: 'preview', label: { key: 'htmlResource.preview' }, enabled: true, run: () => setMode('preview') },
+        ],
+      } });
+    } else if (state.status === 'error') {
+      reportPresentation?.({ state: {
+        status: 'error', message: { key: 'error.unexpected', fallbackText: state.message },
+        actions: [
+          { id: 'retry', label: { key: 'error.retry' }, enabled: true, run: state.retry },
+          { id: 'preview', label: { key: 'htmlResource.preview' }, enabled: true, run: () => setMode('preview') },
+        ],
+      } });
+    } else {
+      reportPresentation?.({ state: { status: 'ready' } });
+    }
+  }, [mode, reportPresentation, setMode]);
+
+  useEffect(() => {
+    if (mode !== 'preview') return;
+    reportPresentation?.({ state: previewState === 'loading'
+      ? { status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: false }
+      : previewState === 'error'
+        ? { status: 'error', message: { key: 'document.file.unavailable' },
+            actions: [
+              { id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retryPreview },
+              { id: 'source', label: { key: 'htmlResource.source' }, enabled: true, run: () => setMode('source') },
+            ] }
+        : { status: 'ready' } });
+  }, [mode, previewState, reportPresentation, retryPreview, setMode]);
 
   useEffect(() => {
     const iframe = previewRef.current;
     if (iframe) return connectLocalHtmlScrollbar(iframe);
   }, [src, mode]);
 
+  useEffect(() => {
+    if (mode === 'preview') setPreviewState('loading');
+  }, [mode, src]);
+
   return (
     <div className="relative h-full min-h-0 min-w-0">
       <div className="editor-toolbar">
@@ -68,7 +121,7 @@ export function HtmlResourceView({
                 aria-pressed={mode === 'preview'}
                 aria-label={t('htmlResource.preview')}
                 onMouseDown={(event) => event.preventDefault()}
-                onClick={() => setMode('preview')}
+                onClick={() => { setPreviewState('loading'); setMode('preview'); }}
                 className={`toolbar-button ${mode === 'preview' ? 'active' : ''}`}
                 style={iconButtonStyle}
               >
@@ -112,6 +165,7 @@ export function HtmlResourceView({
         >
           <DocumentContainer
             {...documentProps}
+            onContentStateChange={onContentStateChange}
             isExternalDocument
             externalScopePath={scopePath}
             readOnly
@@ -119,10 +173,12 @@ export function HtmlResourceView({
         </div>
         {mode === 'preview' && (
           <iframe
-            key={src}
+            key={`${src}:${previewRetry}`}
             ref={previewRef}
             title={filePath.split(/[\\/]/).filter(Boolean).pop() ?? filePath}
             src={src}
+            onLoad={() => setPreviewState('ready')}
+            onError={() => setPreviewState('error')}
             sandbox="allow-scripts"
             referrerPolicy="no-referrer"
             className="absolute inset-0 h-full w-full border-0 bg-white"
diff --git a/app/flowix-web/features/surface/index.ts b/app/flowix-web/features/surface/index.ts
index ccb93909e..b9d01ac14 100644
--- a/app/flowix-web/features/surface/index.ts
+++ b/app/flowix-web/features/surface/index.ts
@@ -36,11 +36,22 @@ export type {
 
 export {
   BrowserColumnSurfaceHost,
-  browserColumnSurfaceRegistry,
   browserColumnSurfaceSupports,
   getBrowserColumnSurfaceDefinition,
   resolveBrowserColumnSurface,
 } from './browser-column-registry';
+export {
+  WorkspaceSurfaceRendererView,
+  getWorkspaceSurfaceRendererDefinition,
+  workspaceSurfaceRendererRegistry,
+  workspaceSurfaceRendererSupportsHost,
+} from './workspace-surface-renderer-registry';
+export type {
+  WorkspaceSurfaceRendererData,
+  WorkspaceSurfaceRendererDefinition,
+  WorkspaceSurfaceRenderContext,
+} from './workspace-surface-renderer-registry';
+export { WorkspaceSurfaceStateView } from './workspace-surface-state-view';
 export type {
   BrowserColumnSurface,
   BrowserColumnSurfaceCapability,
diff --git a/app/flowix-web/features/surface/markdown-document-surface.test.tsx b/app/flowix-web/features/surface/markdown-document-surface.test.tsx
new file mode 100644
index 000000000..1e2d4a5b3
--- /dev/null
+++ b/app/flowix-web/features/surface/markdown-document-surface.test.tsx
@@ -0,0 +1,64 @@
+import { act, useEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MarkdownDocumentSurface } from './markdown-document-surface';
+
+const mocks = vi.hoisted(() => ({ read: vi.fn(), flush: vi.fn(), discard: vi.fn() }));
+vi.mock('@platform/tauri/client', () => ({ notes: { readDocument: mocks.read } }));
+vi.mock('@features/document/components/document-container', () => ({ DocumentContainer: ({ onFlushReady }: {
+  onFlushReady: (flush: (() => Promise<boolean>) | null, discard: (() => void) | null) => void;
+}) => {
+  useEffect(() => { onFlushReady(mocks.flush, mocks.discard); return () => onFlushReady(null, null); }, [onFlushReady]);
+  return <div>editor</div>;
+} }));
+vi.mock('@features/plugin/plugin-artifact-renderer', () => ({ PluginArtifactRenderer: ({ content }: { content: string }) => <div data-preview>{content}</div> }));
+
+const content = (body: string) => `---
+flowix_plugin:
+  id: html
+  renderer: html
+---
+${body}`;
+let root: Root;
+let host: HTMLDivElement;
+const observer = vi.fn();
+const reportPresentation = vi.fn();
+beforeEach(async () => {
+  vi.clearAllMocks();
+  mocks.read.mockResolvedValue(content('before'));
+  mocks.flush.mockResolvedValue(true);
+  host = document.createElement('div');
+  root = createRoot(host);
+  await act(async () => root.render(<MarkdownDocumentSurface fileIdentity={{ path: '/book/plugin.md', displayId: 'plugin' }}
+    navigationViewId="browser-view" reportPresentation={reportPresentation}
+    documentProps={{ isExternalDocument: true, documentSessionMode: 'isolated', onFlushReady: observer }} />));
+});
+afterEach(async () => { await act(async () => root.unmount()); });
+
+describe('shared Markdown plugin preview session', () => {
+  it('flushes the registered view and refreshes non-mindmap plugin previews', async () => {
+    expect(observer).toHaveBeenCalledWith(mocks.flush, mocks.discard);
+    expect(host.querySelector('[data-preview]')!.textContent).toBe('before');
+    expect(reportPresentation).toHaveBeenCalledWith(expect.objectContaining({
+      capabilities: expect.arrayContaining(['fullscreen']),
+      appearance: expect.objectContaining({ headerStyle: 'document' }),
+    }));
+    await act(async () => host.querySelector('button')!.click());
+    mocks.read.mockResolvedValue(content('after'));
+    await act(async () => host.querySelector('button')!.click());
+    expect(mocks.flush).toHaveBeenCalledOnce();
+    expect(mocks.read).toHaveBeenLastCalledWith('/book/plugin.md');
+    expect(host.querySelector('[data-preview]')!.textContent).toBe('after');
+    expect(reportPresentation).toHaveBeenLastCalledWith(expect.objectContaining({
+      capabilities: ['fullscreen'],
+      state: { status: 'ready' },
+    }));
+  });
+  it('stays in the editor if that view cannot flush', async () => {
+    await act(async () => host.querySelector('button')!.click());
+    mocks.flush.mockResolvedValue(false);
+    await act(async () => host.querySelector('button')!.click());
+    expect(mocks.read).toHaveBeenCalledOnce();
+    expect(host.querySelector('[data-preview]')).toBeNull();
+  });
+});
diff --git a/app/flowix-web/features/surface/markdown-document-surface.tsx b/app/flowix-web/features/surface/markdown-document-surface.tsx
new file mode 100644
index 000000000..b7dbc9f84
--- /dev/null
+++ b/app/flowix-web/features/surface/markdown-document-surface.tsx
@@ -0,0 +1,108 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState, type ComponentProps } from 'react';
+import { notes } from '@platform/tauri/client';
+import { DocumentContainer } from '@features/document/components/document-container';
+import { PluginArtifactRenderer } from '@features/plugin/plugin-artifact-renderer';
+import { normalizePluginArtifactRenderer, type PluginArtifactRendererId } from '@features/plugin/plugin-note';
+import { extractFrontmatter } from '@features/document/properties/frontmatter-model';
+import { workspaceSurfaceAppearance, workspaceSurfaceCapabilities } from '@features/workspace/public/surface-api';
+import type { FileDisplayIdentity } from '@/lib/file-display-registry';
+import type { SurfacePresentationUpdate } from '@features/workspace/model/surface-contract';
+import type { SurfaceLifecycle } from '@features/workspace/model/surface-contract';
+import { useWorkspaceSurfaceLifecycleBridge } from './workspace-surface-lifecycle-bridge';
+
+type DocumentProps = Omit<ComponentProps<typeof DocumentContainer>, 'fileIdentity' | 'externalEditorMode' | 'navigationViewId'>;
+
+function pluginPreview(content: string | null) {
+  if (!content) return null;
+  const frontmatter = extractFrontmatter(content);
+  const pluginValue = frontmatter.data.flowix_plugin;
+  const metadata = pluginValue && typeof pluginValue === 'object' && !Array.isArray(pluginValue)
+    ? pluginValue as Record<string, unknown> : null;
+  const pluginId = typeof metadata?.id === 'string' ? metadata.id : null;
+  const renderer = normalizePluginArtifactRenderer(typeof metadata?.renderer === 'string'
+    ? metadata.renderer : pluginId === 'mindmap' ? 'markmap' : null);
+  return frontmatter.hasFrontmatter && !frontmatter.parseError && pluginId && renderer
+    ? { renderer, content: frontmatter.body.trimStart() } : null;
+}
+
+export function MarkdownDocumentSurface({
+  fileIdentity,
+  documentProps,
+  navigationViewId,
+  reportPresentation,
+  registerLifecycle,
+}: {
+  fileIdentity: FileDisplayIdentity;
+  documentProps: DocumentProps;
+  navigationViewId?: string;
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
+  registerLifecycle?: (lifecycle: SurfaceLifecycle | null, owner?: object) => void;
+}) {
+  const [previewContent, setPreviewContent] = useState<string | null>(null);
+  const [pluginRenderer, setPluginRenderer] = useState<PluginArtifactRendererId | null>(null);
+  const [preview, setPreview] = useState(false);
+  const flushRef = useRef<Parameters<NonNullable<DocumentProps['onFlushReady']>>[0]>(null);
+  const currentPath = useRef(fileIdentity.path);
+  currentPath.current = fileIdentity.path;
+  const onFlushReady = useCallback<NonNullable<DocumentProps['onFlushReady']>>((flush, discard) => {
+    flushRef.current = flush;
+    documentProps.onFlushReady?.(flush, discard);
+  }, [documentProps.onFlushReady]);
+  const lifecycleDocumentProps = useWorkspaceSurfaceLifecycleBridge(documentProps, registerLifecycle);
+
+  useEffect(() => {
+    let cancelled = false;
+    setPreviewContent(null);
+    setPluginRenderer(null);
+    setPreview(false);
+    void notes.readDocument(fileIdentity.path).then((content) => {
+      if (cancelled || !content) return;
+      const value = pluginPreview(content);
+      if (value) {
+        setPluginRenderer(value.renderer);
+        setPreviewContent(value.content);
+        setPreview(true);
+      }
+    }).catch(() => undefined);
+    return () => { cancelled = true; };
+  }, [fileIdentity.path]);
+
+  useEffect(() => {
+    const previewKind = preview && pluginRenderer === 'markmap' ? 'mindmap' : preview ? 'plugin-artifact' : 'file-markdown';
+    reportPresentation?.({
+      appearance: workspaceSurfaceAppearance(previewKind),
+      capabilities: workspaceSurfaceCapabilities(previewKind),
+    });
+  }, [pluginRenderer, preview, reportPresentation]);
+
+  return <div className="relative flex h-full min-h-0 flex-col">
+    <div className="min-h-0 flex-1" style={{ display: preview ? 'none' : undefined }}>
+      <DocumentContainer {...lifecycleDocumentProps} fileIdentity={fileIdentity} navigationViewId={navigationViewId} onFlushReady={onFlushReady} externalEditorMode="markdown" />
+    </div>
+    {preview && previewContent !== null && pluginRenderer && <div className="min-h-0 flex-1"><PluginArtifactRenderer renderer={pluginRenderer} content={previewContent} /></div>}
+    {previewContent !== null && pluginRenderer && <button type="button" className="mindmap-markdown-toggle"
+        onClick={() => {
+          if (!preview) {
+            const path = fileIdentity.path;
+            // Flush this view's editor (including Browser's isolated session).
+            // No global Work session is consulted when entering plugin preview.
+            if (!flushRef.current) return;
+            void flushRef.current()
+              .then((saved) => saved ? notes.readDocument(path) : null)
+              .then((content) => {
+                if (currentPath.current !== path) return;
+                const value = pluginPreview(content);
+                if (value) {
+                  setPluginRenderer(value.renderer);
+                  setPreviewContent(value.content);
+                  setPreview(true);
+                }
+              }).catch(() => undefined);
+          } else {
+            setPreview(false);
+          }
+        }}>{preview ? '编辑 Markdown' : pluginRenderer === 'markmap' ? '预览思维导图' : '预览产物'}</button>}
+  </div>;
+}
diff --git a/app/flowix-web/features/surface/media-resource-view.test.tsx b/app/flowix-web/features/surface/media-resource-view.test.tsx
new file mode 100644
index 000000000..f4fa47c2e
--- /dev/null
+++ b/app/flowix-web/features/surface/media-resource-view.test.tsx
@@ -0,0 +1,84 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SurfacePresentationUpdate } from '@features/workspace/model/surface-contract';
+import { MediaResourceView } from './media-resource-view';
+
+const mocks = vi.hoisted(() => ({ readImage: vi.fn(), toAssetUrl: vi.fn(), mediaGet: vi.fn(), cancelThumbnail: vi.fn() }));
+vi.mock('@platform/tauri/client', () => ({
+  files: { readImage: mocks.readImage, toAssetUrl: mocks.toAssetUrl },
+  mediaResources: { get: mocks.mediaGet, cancelThumbnail: mocks.cancelThumbnail },
+}));
+vi.mock('./video-preview-cache', () => ({ getNotebookVideoPreview: vi.fn() }));
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((done, fail) => { resolve = done; reject = fail; });
+  return { promise, resolve, reject };
+}
+
+let host: HTMLDivElement;
+let root: Root;
+let updates: SurfacePresentationUpdate[];
+const reportPresentation = (update: SurfacePresentationUpdate) => updates.push(update);
+
+function latestState() {
+  const stateUpdates = updates.filter((update) => update.state);
+  return stateUpdates[stateUpdates.length - 1]?.state;
+}
+
+async function render(filePath: string) {
+  await act(async () => root.render(<MediaResourceView filePath={filePath} notebookPath="/book" resourceKind="image" reportPresentation={reportPresentation} />));
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  host = document.createElement('div');
+  root = createRoot(host);
+  updates = [];
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+});
+
+describe('media resource presentation', () => {
+  it('publishes loading, error, retry and ready after the image is loaded', async () => {
+    const first = deferred<string | null>();
+    const second = deferred<string | null>();
+    mocks.readImage.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise);
+    await render('/book/photo.png');
+    expect(latestState()?.status).toBe('loading');
+
+    await act(async () => first.reject(new Error('read failed')));
+    expect(latestState()?.status).toBe('error');
+    const errorState = latestState();
+    const retry = errorState && (errorState.status === 'error' || errorState.status === 'unavailable')
+      ? errorState.actions?.find((action) => action.id === 'retry')
+      : undefined;
+    expect(retry).toBeDefined();
+    await act(async () => retry?.run());
+    await act(async () => second.resolve('data:image/png;base64,abc'));
+
+    const image = host.querySelector('img');
+    expect(image).not.toBeNull();
+    await act(async () => image!.dispatchEvent(new Event('load')));
+    expect(latestState()?.status).toBe('ready');
+    expect(mocks.readImage).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores an image read that finishes after switching to another file', async () => {
+    const stale = deferred<string | null>();
+    const current = deferred<string | null>();
+    mocks.readImage.mockReturnValueOnce(stale.promise).mockReturnValueOnce(current.promise);
+    await render('/book/old.png');
+    await render('/book/new.png');
+
+    await act(async () => stale.resolve('data:image/png;base64,old'));
+    expect(host.querySelector('img')).toBeNull();
+    await act(async () => current.resolve('data:image/png;base64,new'));
+    expect(host.querySelector('img')?.alt).toBe('new.png');
+    expect(updates.some((update) => update.title === 'old.png' && update.state?.status === 'ready')).toBe(false);
+  });
+});
diff --git a/app/flowix-web/features/surface/media-resource-view.tsx b/app/flowix-web/features/surface/media-resource-view.tsx
index 976c3cb11..d2cf898ac 100644
--- a/app/flowix-web/features/surface/media-resource-view.tsx
+++ b/app/flowix-web/features/surface/media-resource-view.tsx
@@ -1,148 +1,124 @@
 'use client';
 
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
 
-import { useI18n } from '@/lib/i18n';
 import { files, mediaResources } from '@platform/tauri/client';
+import type { SurfacePresentationUpdate, SurfaceState } from '@features/workspace/model/surface-contract';
+import { workspaceSurfaceAppearance } from '@features/workspace/public/surface-api';
 import videoCardPlaceholder from '@/assets/placeholder-video-card.jpg';
 import { getNotebookVideoPreview } from './video-preview-cache';
+import { WorkspaceSurfaceStateView } from './workspace-surface-state-view';
 
 type MediaKind = 'image' | 'video';
+type ReportPresentation = (update: SurfacePresentationUpdate) => void;
+type PreviewProps = {
+  filePath: string;
+  notebookPath: string;
+  retry: () => void;
+  reportPresentation?: ReportPresentation;
+};
+const LOADING: SurfaceState = {
+  status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: false,
+};
 
 function filenameFromPath(filePath: string): string {
   return filePath.split(/[\\/]/).filter(Boolean).pop() ?? filePath;
 }
 
-function MediaUnavailable({ filePath }: { filePath: string }) {
-  const { t } = useI18n();
-  return (
-    <div className="flex h-full flex-col items-center justify-center gap-2 px-8 text-center text-sm text-[var(--muted-foreground)]">
-      <span>{t('document.file.unavailable')}</span>
-      <span className="max-w-full truncate text-xs" title={filePath}>{filenameFromPath(filePath)}</span>
-    </div>
-  );
+function mediaError(filePath: string, retry: () => void, error?: unknown): SurfaceState {
+  return {
+    status: 'error',
+    message: { key: 'document.file.unavailable', fallbackText: error instanceof Error ? error.message : filenameFromPath(filePath) },
+    actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retry }],
+  };
 }
 
-function ImageResourcePreview({ filePath, notebookPath }: { filePath: string; notebookPath: string }) {
-  const { t } = useI18n();
-  const [src, setSrc] = useState<string | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [failed, setFailed] = useState(false);
+/** Standalone previews use the same state UI; workspace hosts own its presentation. */
+function MediaPreviewState({ filePath, state, reportPresentation, children }: {
+  filePath: string; state: SurfaceState; reportPresentation?: ReportPresentation; children?: ReactNode;
+}) {
+  useEffect(() => {
+    reportPresentation?.({ title: filenameFromPath(filePath), state });
+  }, [filePath, reportPresentation, state]);
+  return reportPresentation ? children : <WorkspaceSurfaceStateView
+    state={state} appearance={workspaceSurfaceAppearance('media')} keepContentMounted>
+    {children}
+  </WorkspaceSurfaceStateView>;
+}
 
+function ImageResourcePreview({ filePath, notebookPath, retry, reportPresentation }: PreviewProps) {
+  const [src, setSrc] = useState<string | null>(null);
+  const [state, setState] = useState<SurfaceState>(LOADING);
   useEffect(() => {
     let cancelled = false;
-    setLoading(true);
-    setFailed(false);
-    setSrc(null);
     void files.readImage(filePath, notebookPath).then((dataUrl) => {
       if (cancelled) return;
-      setSrc(dataUrl);
-      setFailed(!dataUrl);
-      setLoading(false);
-    }).catch(() => {
-      if (cancelled) return;
-      setFailed(true);
-      setLoading(false);
+      if (dataUrl) setSrc(dataUrl);
+      else setState(mediaError(filePath, retry));
+    }).catch((error: unknown) => {
+      if (!cancelled) setState(mediaError(filePath, retry, error));
     });
-    return () => {
-      cancelled = true;
-    };
-  }, [filePath, notebookPath]);
-
-  if (loading) {
-    return <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">{t('document.file.loading')}</div>;
-  }
-  if (failed || !src) return <MediaUnavailable filePath={filePath} />;
+    return () => { cancelled = true; };
+  }, [filePath, notebookPath, retry]);
 
-  return (
-    <div className="flex h-full w-full items-center justify-center overflow-auto bg-[var(--agent-bg,var(--document-bg))] p-6">
-      <img
-        src={src}
-        alt={filenameFromPath(filePath)}
-        className="block max-h-full max-w-full rounded-lg object-contain"
-        onError={() => setFailed(true)}
-      />
-    </div>
-  );
+  return <MediaPreviewState filePath={filePath} state={state} reportPresentation={reportPresentation}>
+    {src && <div className="flex h-full w-full items-center justify-center overflow-auto p-6">
+      <img src={src} alt={filenameFromPath(filePath)} className="block max-h-full max-w-full rounded-lg object-contain"
+        onLoad={() => setState({ status: 'ready' })} onError={() => setState(mediaError(filePath, retry))} />
+    </div>}
+  </MediaPreviewState>;
 }
 
-function VideoResourcePreview({ filePath, notebookPath }: { filePath: string; notebookPath: string }) {
-  const { t } = useI18n();
-  const [failed, setFailed] = useState(false);
+function VideoResourcePreview({ filePath, notebookPath, retry, reportPresentation }: PreviewProps) {
+  const [state, setState] = useState<SurfaceState>(LOADING);
   const [authorized, setAuthorized] = useState(false);
   const [poster, setPoster] = useState(videoCardPlaceholder);
   const src = useMemo(() => files.toAssetUrl(filePath), [filePath]);
 
-  // The media command establishes the notebook-scoped security access before
-  // the native asset URL is mounted. It does not create a document session.
+  // Establish notebook access before mounting the native asset URL.
   useEffect(() => {
     let cancelled = false;
     const requestId = crypto.randomUUID();
-    setAuthorized(false);
-    setFailed(false);
-    setPoster(videoCardPlaceholder);
     void mediaResources.get(filePath, notebookPath).then(() => {
       if (cancelled) return;
       setAuthorized(true);
-      void getNotebookVideoPreview(
-        filePath,
-        notebookPath,
-        requestId,
-      ).then((preview) => {
+      void getNotebookVideoPreview(filePath, notebookPath, requestId).then((preview) => {
         if (!cancelled && preview) setPoster(preview);
-      });
-    }).catch(() => {
-      if (!cancelled) setFailed(true);
+      }).catch(() => undefined);
+    }).catch((error: unknown) => {
+      if (!cancelled) setState(mediaError(filePath, retry, error));
     });
     return () => {
       cancelled = true;
       void mediaResources.cancelThumbnail(requestId).catch(() => undefined);
     };
-  }, [filePath, notebookPath, src]);
+  }, [filePath, notebookPath, retry]);
 
-  if (failed) return <MediaUnavailable filePath={filePath} />;
-  if (!authorized) {
-    return <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">{t('document.file.loading')}</div>;
-  }
-
-  return (
-    <div className="flex h-full w-full items-center justify-center overflow-auto bg-[var(--agent-bg,var(--document-bg))] p-6">
-      <video
-        src={src}
-        poster={poster}
-        controls
-        preload="metadata"
-        playsInline
+  return <MediaPreviewState filePath={filePath} state={state} reportPresentation={reportPresentation}>
+    {authorized && <div className="flex h-full w-full items-center justify-center overflow-auto p-6">
+      <video src={src} poster={poster} controls preload="metadata" playsInline
         className="media-resource-video block h-auto max-h-full max-w-full rounded-lg object-contain"
-        aria-label={filenameFromPath(filePath)}
-        onError={() => setFailed(true)}
-      />
-    </div>
-  );
+        aria-label={filenameFromPath(filePath)} onLoadedMetadata={() => setState({ status: 'ready' })}
+        onError={() => setState(mediaError(filePath, retry))} />
+    </div>}
+  </MediaPreviewState>;
 }
 
-export function MediaResourceView({
-  filePath,
-  notebookPath,
-  resourceKind,
-}: {
-  filePath: string;
-  notebookPath: string | null;
-  resourceKind: MediaKind;
+export function MediaResourceView({ filePath, notebookPath, resourceKind, reportPresentation }: {
+  filePath: string; notebookPath: string | null; resourceKind: MediaKind; reportPresentation?: ReportPresentation;
 }) {
-  const preview = notebookPath ? (
-    resourceKind === 'image'
-      ? <ImageResourcePreview filePath={filePath} notebookPath={notebookPath} />
-      : <VideoResourcePreview filePath={filePath} notebookPath={notebookPath} />
-  ) : (
-    <MediaUnavailable filePath={filePath} />
-  );
-
-  return (
-    <div className="flex h-full min-w-0 flex-col bg-[var(--agent-bg,var(--document-bg))]">
-      <div className="relative flex min-h-0 flex-1">
-        <div className="min-w-0 flex-1">{preview}</div>
-      </div>
-    </div>
-  );
+  const [retryCount, setRetryCount] = useState(0);
+  const retry = useCallback(() => setRetryCount((count) => count + 1), []);
+  const unavailableState = useMemo<SurfaceState>(() => ({
+    status: 'unavailable', reason: 'unsupported',
+    message: { key: 'document.file.unavailable', fallbackText: filenameFromPath(filePath) },
+  }), [filePath]);
+  const props = { filePath, notebookPath: notebookPath ?? '', retry, reportPresentation };
+  const key = `${filePath}:${notebookPath}:${resourceKind}:${retryCount}`;
+  return <div className="flex h-full min-w-0 flex-col bg-[var(--agent-bg,var(--document-bg))]">
+    <div className="relative flex min-h-0 flex-1"><div className="min-w-0 flex-1">
+      {!notebookPath ? <MediaPreviewState filePath={filePath} state={unavailableState} reportPresentation={reportPresentation} />
+        : resourceKind === 'image' ? <ImageResourcePreview key={key} {...props} /> : <VideoResourcePreview key={key} {...props} />}
+    </div></div>
+  </div>;
 }
diff --git a/app/flowix-web/features/surface/public/shell-api.ts b/app/flowix-web/features/surface/public/shell-api.ts
index e9aacb505..6593d5a6e 100644
--- a/app/flowix-web/features/surface/public/shell-api.ts
+++ b/app/flowix-web/features/surface/public/shell-api.ts
@@ -31,3 +31,20 @@ export {
   type BrowserColumnSurfaceChrome,
 } from '@features/surface/browser-column-registry';
 export { resolveBrowserColumnSurface } from '@features/surface/browser-column-registry';
+export {
+  WorkspaceSurfaceRendererView,
+  getWorkspaceSurfaceRendererDefinition,
+  workspaceSurfaceRendererRegistry,
+  workspaceSurfaceRendererSupportsHost,
+} from '@features/surface/workspace-surface-renderer-registry';
+export type {
+  WorkspaceSurfaceRendererData,
+  WorkspaceSurfaceRendererDefinition,
+  WorkspaceSurfaceRenderContext,
+} from '@features/surface/workspace-surface-renderer-registry';
+export { WorkspaceSurfaceStateView } from '@features/surface/workspace-surface-state-view';
+export {
+  beginWorkspaceSurfaceStartup,
+  waitForWorkspaceSurfaceStartup,
+  useWorkspaceSurfacePresentation,
+} from '@features/surface/workspace-surface-runtime';
diff --git a/app/flowix-web/features/surface/registry-transitions.test.tsx b/app/flowix-web/features/surface/registry-transitions.test.tsx
index 2789ca3a8..1b10fec0c 100644
--- a/app/flowix-web/features/surface/registry-transitions.test.tsx
+++ b/app/flowix-web/features/surface/registry-transitions.test.tsx
@@ -1,4 +1,4 @@
-import { act, type ReactNode } from 'react';
+import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
@@ -13,14 +13,11 @@ vi.mock('@features/document/components/document-container', () => ({
     openContainingFolder?: boolean;
   }) => <div data-file-path={filePath} data-open-folder={String(Boolean(openContainingFolder))}>unavailable</div>,
 }));
-vi.mock('@features/editor/use-external-file-mime', () => ({
-  useExternalFileMime: () => ({ mimeType: 'application/octet-stream', loading: false }),
+vi.mock('@features/editor/use-external-file-content-detection', () => ({
+  useExternalFileContentDetection: () => ({ isTextContent: false, loading: false }),
 }));
 vi.mock('./media-resource-view', () => ({ MediaResourceView: () => <div>media loading</div> }));
 vi.mock('./html-resource-view', () => ({ HtmlResourceView: () => <div>html reader</div> }));
-vi.mock('@shared/ui/surface-suspense-host', () => ({
-  SurfaceSuspenseHost: ({ children }: { children: ReactNode }) => children,
-}));
 
 const initialDocumentState = useDocumentStore.getState();
 
@@ -81,7 +78,10 @@ describe('work column external-file transition completion', () => {
         await act(async () => root.render(<WorkColumnSurfaceHost surface={externalSurface(kind, 12)} />));
         expect(useDocumentStore.getState().isDocumentTransitioning).toBe(false);
         if (kind === 'unavailable-file') {
-          expect(element.querySelector('[data-file-path]')?.getAttribute('data-file-path')).toBe('/notebook/report.pdf');
+          await vi.waitFor(async () => {
+            await act(async () => {});
+            expect(element.querySelector('[data-file-path]')?.getAttribute('data-file-path')).toBe('/notebook/report.pdf');
+          });
           expect(element.querySelector('[data-open-folder]')?.getAttribute('data-open-folder')).toBe('true');
         }
       } finally {
diff --git a/app/flowix-web/features/surface/registry.test.ts b/app/flowix-web/features/surface/registry.test.ts
index 7cacc843e..066129a79 100644
--- a/app/flowix-web/features/surface/registry.test.ts
+++ b/app/flowix-web/features/surface/registry.test.ts
@@ -2,9 +2,10 @@ import { describe, expect, it } from 'vitest';
 import {
   getWorkColumnSurfaceDefinition,
   surfaceSupports,
-  workColumnSurfaceRegistry,
 } from './registry';
 import type { WorkColumnSurface, WorkColumnSurfaceKind } from './types';
+import { workspaceSurfaceRendererRegistry } from './workspace-surface-renderer-registry';
+import { workspaceSurfaceRegistry } from '@features/workspace/public/surface-api';
 
 function fileIdentity(path: string) {
   return { path, displayId: `display:${path}` };
@@ -12,8 +13,8 @@ function fileIdentity(path: string) {
 
 function surface(kind: WorkColumnSurfaceKind): WorkColumnSurface {
   switch (kind) {
-    case 'document-list':
-      return { kind, displayId: 'document-list:/notebook', instanceKey: 'document-list:/notebook', folderPath: '/notebook', notebookPath: '/notebook', notebookId: 'notebook-1', filters: {} };
+    case 'folder-collection':
+      return { kind, instanceKey: 'folder-collection:1', notebookId: 'notebook-1', notebookPath: '/notebook', folderPath: '/notebook/folder', folderName: 'folder' };
     case 'md':
       return { kind, instanceKey: 'md:1', fileIdentity: fileIdentity('/workspace/readme.md'), props: { isExternalDocument: true } };
     case 'code':
@@ -103,29 +104,9 @@ function surface(kind: WorkColumnSurfaceKind): WorkColumnSurface {
   }
 }
 
-describe('workColumnSurfaceRegistry', () => {
-  it('registers every supported product-level surface kind', () => {
-    expect(Object.keys(workColumnSurfaceRegistry).sort()).toEqual([
-      'agent-conversation',
-      'code',
-      'csv-file',
-      'document-list',
-      'html',
-      'html-file',
-      'image-file',
-      'json',
-      'md',
-      'media',
-      'media-library-file',
-      'mindmap',
-      'plugin-artifact',
-      'plugin-workbench',
-      'table-file',
-      'text',
-      'unavailable-file',
-      'video-file',
-      'web',
-    ]);
+describe('Work surface adapter', () => {
+  it('provides one renderer registration for every canonical surface kind', () => {
+    expect(Object.keys(workspaceSurfaceRendererRegistry).sort()).toEqual(Object.keys(workspaceSurfaceRegistry).sort());
   });
 
   it('exposes Markdown editing actions on the path surface', () => {
diff --git a/app/flowix-web/features/surface/registry.tsx b/app/flowix-web/features/surface/registry.tsx
index b872d2ec0..68ba275a9 100644
--- a/app/flowix-web/features/surface/registry.tsx
+++ b/app/flowix-web/features/surface/registry.tsx
@@ -1,351 +1,67 @@
-import { setCollectionActiveView } from '@features/workspace/use-cases/collection-view-state';
 'use client';
 
-import { CodeSurfaceFileBrowser } from './work-file-browser-view';
-import { DocumentListView } from './document-list-view';
 import {
-  type ComponentType,
   type ReactNode,
+  useCallback,
   useLayoutEffect,
-  useEffect,
-  useState,
+  useMemo,
 } from 'react';
-import { notes } from '@platform/tauri/client';
-import { PluginArtifactRenderer } from '@features/plugin/plugin-artifact-renderer';
-import { normalizePluginArtifactRenderer, type PluginArtifactRendererId } from '@features/plugin/plugin-note';
-import { extractFrontmatter } from '@features/document/properties/frontmatter-model';
-import { DocumentContainer, UnavailableFileView } from '@features/document/components/document-container';
-import { DocxPreview } from '@features/document/components/docx-preview';
-import { CsvPreview } from '@features/document/components/csv-preview';
 import { useDocumentStore } from '@features/document/store/document-store';
-import { documentIdentityFromFile } from '@features/document/store/document-identity';
-import { saveDocumentPath } from '@features/document/store/document-session-service';
-import { MediaResourceView } from './media-resource-view';
-import { LazyAgentConversationDetail } from '@features/agent/components/lazy-agent-conversation-detail';
-import {
-  LazyPluginDocumentView,
-  LazyPluginWorkbench,
-} from '@features/plugin/public/surface-api';
-import { SurfaceSuspenseHost } from '@shared/ui/surface-suspense-host';
-import { WorkspaceEmptyState } from '@shared/ui/workspace-empty-state';
-import { HtmlResourceView } from './html-resource-view';
 import type {
-  AgentConversationSurface,
-  CodeSurface,
-  HtmlFileSurface,
-  ImageFileSurface,
-  MDSurface,
-  MediaResourceSurface,
-  UnavailableFileSurface,
-  VideoFileSurface,
-  PluginArtifactSurfaceBase,
-  PluginWorkbenchSurface,
-  WorkColumnContentPresentation,
-  WorkColumnSurface,
-  WorkColumnSurfaceCapability,
-  WorkColumnSurfaceChrome,
-  WorkColumnSurfaceKind,
-  WebSurface,
+  WorkColumnContentPresentation, WorkColumnSurface,
+  WorkColumnSurfaceCapability, WorkColumnSurfaceChrome,
 } from './types';
-import { TableDocumentView } from '@features/multidimensional-table/public/surface-api';
-import { MediaLibraryView } from '@features/media-library/media-library-view';
-import { externalFileViewKind } from '@features/editor/code-file';
-import { useExternalFileMime } from '@features/editor/use-external-file-mime';
-import { useI18n } from '@/lib/i18n';
-import type { MediaLibraryFileSurface, TableFileSurface } from './types';
+import { workspaceSurfaceAppearance } from '@features/workspace/public/surface-api';
+import type { SurfaceAppearance } from '@features/workspace/public/surface-api';
+import {
+  getWorkspaceSurfaceRendererDefinition,
+  WorkspaceSurfaceRendererView,
+} from './workspace-surface-renderer-registry';
+import { WorkspaceSurfaceStateView } from './workspace-surface-state-view';
 
-type SurfaceOfKind<K extends WorkColumnSurfaceKind> = Extract<WorkColumnSurface, { kind: K }>;
+import { workspaceSurfaceRendererDataFromWorkSurface } from './work-column-surface-adapter';
+import { registerStartupSurfaceHostView, registerWorkspaceSurfacePresentationOwner, reportEmptyWorkspaceSurfaceForIdentity, reportWorkspaceSurfacePresentation } from './workspace-surface-runtime';
+import type { SurfacePresentationUpdate } from '@features/workspace/model/surface-contract';
+import type { SurfaceLifecycle } from '@features/workspace/model/surface-contract';
+import { registerWorkspaceSurfaceLifecycle } from '@features/workspace/public/surface-lifecycle-api';
 
 export interface WorkColumnSurfaceDefinition {
+  appearance: Readonly<SurfaceAppearance>;
   chrome: WorkColumnSurfaceChrome;
   capabilities: readonly WorkColumnSurfaceCapability[];
-  render: (surface: WorkColumnSurface) => ReactNode;
-}
-
-function defineSurface<K extends WorkColumnSurfaceKind>(
-  kind: K,
-  options: {
-    chrome: WorkColumnSurfaceChrome;
-    capabilities?: readonly WorkColumnSurfaceCapability[];
-    component: ComponentType<{ surface: SurfaceOfKind<K> }>;
-  },
-): WorkColumnSurfaceDefinition {
-  const Component = options.component;
-  return Object.freeze({
-    chrome: options.chrome,
-    capabilities: Object.freeze([...(options.capabilities ?? [])]),
-    render(surface: WorkColumnSurface) {
-      if (surface.kind !== kind) {
-        throw new Error(`Surface registry mismatch: expected '${kind}', received '${surface.kind}'`);
-      }
-      // TypeScript cannot correlate a generic discriminant with Extract after
-      // the runtime guard. Keep the assertion inside this constructor so all
-      // registry consumers remain exhaustively typed.
-      return <Component surface={surface as SurfaceOfKind<K>} />;
-    },
-  });
-}
-
-function MDSurfaceView({ surface }: { surface: MDSurface }) {
-  const [mindmapContent, setMindmapContent] = useState<string | null>(null);
-  const [pluginRenderer, setPluginRenderer] = useState<PluginArtifactRendererId | null>(null);
-  const [preview, setPreview] = useState(false);
-  useEffect(() => {
-    let cancelled = false;
-    setMindmapContent(null);
-    setPluginRenderer(null);
-    setPreview(false);
-    void notes.readDocument(surface.fileIdentity.path).then((content) => {
-      if (cancelled || !content) return;
-      const frontmatter = extractFrontmatter(content);
-      const pluginValue = frontmatter.data.flowix_plugin;
-      const pluginMetadata = pluginValue && typeof pluginValue === 'object' && !Array.isArray(pluginValue)
-        ? pluginValue as Record<string, unknown> : null;
-      const pluginId = typeof pluginMetadata?.id === 'string' ? pluginMetadata.id : null;
-      const rendererValue = typeof pluginMetadata?.renderer === 'string' ? pluginMetadata.renderer
-        : pluginId === 'mindmap' ? 'markmap' : null;
-      const renderer = normalizePluginArtifactRenderer(rendererValue);
-      if (frontmatter.hasFrontmatter && !frontmatter.parseError && pluginId && renderer) {
-        setPluginRenderer(renderer);
-        setMindmapContent(frontmatter.body.trimStart());
-        setPreview(true);
-      }
-    }).catch(() => undefined);
-    return () => { cancelled = true; };
-  }, [surface.fileIdentity.path]);
-  return <div className="relative flex h-full min-h-0 flex-col">
-    <div className="min-h-0 flex-1" style={{ display: preview ? 'none' : undefined }}>
-      <DocumentContainer {...surface.props} fileIdentity={surface.fileIdentity} externalEditorMode="markdown" />
-    </div>
-    {preview && mindmapContent !== null && pluginRenderer && <div className="min-h-0 flex-1"><PluginArtifactRenderer renderer={pluginRenderer} content={mindmapContent} /></div>}
-    {mindmapContent !== null && pluginRenderer && <button type="button" className="mindmap-markdown-toggle"
-        onClick={() => {
-          if (!preview) {
-            const session = useDocumentStore.getState().activeExternalSession;
-            const scopePath = session?.fileIdentity.path === surface.fileIdentity.path ? session.scopePath : null;
-            void saveDocumentPath(documentIdentityFromFile(surface.fileIdentity), surface.fileIdentity.path, scopePath)
-              .then((saved) => saved ? notes.readDocument(surface.fileIdentity.path) : null)
-              .then((content) => {
-              const frontmatter = content ? extractFrontmatter(content) : null;
-              const pluginValue = frontmatter?.data.flowix_plugin;
-              const pluginId = pluginValue && typeof pluginValue === 'object' && !Array.isArray(pluginValue)
-                ? (pluginValue as Record<string, unknown>).id : null;
-              if (frontmatter?.hasFrontmatter && !frontmatter.parseError && pluginId === 'mindmap') {
-                setMindmapContent(frontmatter.body.trimStart());
-                setPreview(true);
-              }
-            }).catch(() => undefined);
-          } else {
-            setPreview(false);
-          }
-        }}>{preview ? '编辑 Markdown' : '预览思维导图'}</button>}
-  </div>;
-}
-
-function CodeSurfaceView({ surface }: { surface: CodeSurface }) {
-  return <CodeSurfaceFileBrowser surface={surface} />;
-}
-
-function ImageFileSurfaceView({ surface }: { surface: ImageFileSurface }) {
-  return <MediaResourceView
-    filePath={surface.fileIdentity.path}
-    notebookPath={surface.scopePath}
-    resourceKind="image"
-  />;
+  render: () => ReactNode;
 }
 
-function VideoFileSurfaceView({ surface }: { surface: VideoFileSurface }) {
-  return <MediaResourceView
-    filePath={surface.fileIdentity.path}
-    notebookPath={surface.scopePath}
-    resourceKind="video"
-  />;
-}
-
-function CsvFileSurfaceView({ surface }: { surface: Extract<WorkColumnSurface, { kind: 'csv-file' }> }) {
-  return <CsvPreview filePath={surface.fileIdentity.path} scopePath={surface.scopePath} />;
-}
-
-function TableFileSurfaceView({ surface }: { surface: TableFileSurface }) {
-  return <TableDocumentView {...surface.props} fileIdentity={surface.fileIdentity}
-    onActiveViewChange={surface.props.expectedCollectionId && surface.props.notebookId ? (viewId) => {
-      setCollectionActiveView({ host: 'main-third' }, { notebookId: surface.props.notebookId!, collectionId: surface.props.expectedCollectionId! }, viewId);
-    } : surface.props.onActiveViewChange} />;
-}
-
-function MediaLibraryFileSurfaceView({ surface }: { surface: MediaLibraryFileSurface }) {
-  return <MediaLibraryView filePath={surface.fileIdentity.path} fileIdentity={surface.fileIdentity} notebookPath={surface.notebookPath} notebookId={surface.notebookId} />;
-}
-
-function HtmlFileSurfaceView({ surface }: { surface: HtmlFileSurface }) {
-  return <HtmlResourceView
-    filePath={surface.fileIdentity.path}
-    scopePath={surface.scopePath}
-    documentProps={{ ...surface.props, fileIdentity: surface.fileIdentity }}
-  />;
-}
-
-function UnavailableFileSurfaceView({ surface }: { surface: UnavailableFileSurface }) {
-  const { t } = useI18n();
-  const filePath = surface.fileIdentity.path;
-  const baseFileKind = externalFileViewKind(filePath);
-  const { mimeType, loading: mimeLoading } = useExternalFileMime(
-    filePath,
-    baseFileKind === 'unavailable',
-  );
-  if (baseFileKind === 'docx') {
-    return <DocxPreview filePath={filePath} scopePath={surface.scopePath} />;
-  }
-  if (baseFileKind === 'csv') {
-    return <CsvPreview filePath={filePath} scopePath={surface.scopePath} />;
-  }
-  if (mimeLoading) {
-    return (
-      <div className="flex h-full w-full items-center justify-center text-sm text-[var(--muted-foreground)]">
-        {t('document.file.loading')}
-      </div>
-    );
-  }
-  if (externalFileViewKind(filePath, mimeType) === 'code') {
-    return <DocumentContainer
-      {...surface.props}
-      fileIdentity={surface.fileIdentity}
-      externalScopePath={surface.scopePath}
-    />;
-  }
-  return <UnavailableFileView
-    filePath={filePath}
-    openContainingFolder
-    scopePath={surface.scopePath}
-  />;
-}
-
-function MediaResourceSurfaceView({ surface }: { surface: MediaResourceSurface }) {
-  return <MediaResourceView
-    filePath={surface.fileIdentity.path}
-    notebookPath={surface.notebookPath}
-    resourceKind={surface.resourceKind}
-  />;
-}
-
-function PluginArtifactSurfaceView({ surface }: { surface: PluginArtifactSurfaceBase }) {
-  return <LazyPluginDocumentView {...surface.props} />;
-}
-
-function AgentConversationSurfaceView({ surface }: { surface: AgentConversationSurface }) {
-  return <LazyAgentConversationDetail instanceId={surface.instanceId} />;
-}
-
-function PluginWorkbenchSurfaceView({ surface }: { surface: PluginWorkbenchSurface }) {
-  return <LazyPluginWorkbench {...surface.props} />;
-}
-
-function WebSurfaceView({ surface }: { surface: WebSurface }) {
-  return (
-    <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">
-      {surface.url}
-    </div>
-  );
-}
-
-const artifactBaseCapabilities = ['fullscreen'] as const;
-
-export const workColumnSurfaceRegistry = Object.freeze({
-  md: defineSurface('md', {
-    chrome: 'document',
-    capabilities: ['edit', 'search', 'copy-content', 'export-content', 'save-template'],
-    component: MDSurfaceView,
-  }),
-  code: defineSurface('code', {
-    chrome: 'document',
-    capabilities: ['edit', 'search', 'copy-content'],
-    component: CodeSurfaceView,
-  }),
-  'csv-file': defineSurface('csv-file', {
-    chrome: 'document',
-    capabilities: [],
-    component: CsvFileSurfaceView,
-  }),
-  'image-file': defineSurface('image-file', {
-    chrome: 'document',
-    component: ImageFileSurfaceView,
-  }),
-  'video-file': defineSurface('video-file', {
-    chrome: 'document',
-    component: VideoFileSurfaceView,
-  }),
-  'table-file': defineSurface('table-file', {
-    chrome: 'document',
-    capabilities: [],
-    component: TableFileSurfaceView,
-  }),
-  'media-library-file': defineSurface('media-library-file', {
-    chrome: 'document',
-    capabilities: [],
-    component: MediaLibraryFileSurfaceView,
-  }),
-  'html-file': defineSurface('html-file', {
-    chrome: 'document',
-    component: HtmlFileSurfaceView,
-  }),
-  'unavailable-file': defineSurface('unavailable-file', {
-    chrome: 'document',
-    component: UnavailableFileSurfaceView,
-  }),
-  media: defineSurface('media', {
-    chrome: 'media',
-    capabilities: ['fullscreen'],
-    component: MediaResourceSurfaceView,
-  }),
-  mindmap: defineSurface('mindmap', {
-    chrome: 'document',
-    capabilities: [...artifactBaseCapabilities, 'fit', 'zoom'],
-    component: PluginArtifactSurfaceView,
-  }),
-  html: defineSurface('html', {
-    chrome: 'document',
-    capabilities: artifactBaseCapabilities,
-    component: PluginArtifactSurfaceView,
-  }),
-  json: defineSurface('json', {
-    chrome: 'document',
-    capabilities: artifactBaseCapabilities,
-    component: PluginArtifactSurfaceView,
-  }),
-  text: defineSurface('text', {
-    chrome: 'document',
-    capabilities: artifactBaseCapabilities,
-    component: PluginArtifactSurfaceView,
-  }),
-  'plugin-artifact': defineSurface('plugin-artifact', {
-    chrome: 'document',
-    capabilities: artifactBaseCapabilities,
-    component: PluginArtifactSurfaceView,
-  }),
-  'agent-conversation': defineSurface('agent-conversation', {
-    chrome: 'agent',
-    capabilities: ['stream-conversation'],
-    component: AgentConversationSurfaceView,
-  }),
-  'plugin-workbench': defineSurface('plugin-workbench', {
-    chrome: 'document',
-    capabilities: ['run-agent', 'fullscreen'],
-    component: PluginWorkbenchSurfaceView,
-  }),
-  web: defineSurface('web', {
-    chrome: 'document',
-    component: WebSurfaceView,
-  }),
-  'document-list': defineSurface('document-list', {
-    chrome: 'document',
-    component: DocumentListView,
-  }),
-} satisfies Record<WorkColumnSurfaceKind, WorkColumnSurfaceDefinition>);
-
+/** Work adapts navigation data; renderer registration belongs to the common registry. */
 export function getWorkColumnSurfaceDefinition(
   surface: WorkColumnSurface,
+  reportPresentation?: (update: SurfacePresentationUpdate) => void,
+  registerLifecycle?: (lifecycle: SurfaceLifecycle | null, owner?: object) => void,
+  focused = false,
 ): WorkColumnSurfaceDefinition {
-  return workColumnSurfaceRegistry[surface.kind];
+  const data = workspaceSurfaceRendererDataFromWorkSurface(surface);
+  const definition = getWorkspaceSurfaceRendererDefinition(data);
+  return {
+    appearance: definition.appearance,
+    chrome: definition.appearance.headerStyle,
+    capabilities: definition.capabilities,
+    render: () => <WorkspaceSurfaceRendererView
+      surface={data}
+      context={{
+        host: 'main-third', viewId: surface.instanceKey, focused,
+        initialFocus: initialFocusForSurface(surface),
+        readOnly: 'props' in surface && 'readOnly' in surface.props ? Boolean(surface.props.readOnly) : false,
+        reportPresentation: reportPresentation ?? ((update) => reportWorkspaceSurfacePresentation(surface.instanceKey, update)),
+        registerLifecycle,
+      }}
+    />,
+  };
+}
+
+function initialFocusForSurface(surface: WorkColumnSurface): 'title' | 'body' | undefined {
+  if (!('props' in surface) || !surface.props || !('initialFocus' in surface.props)) return undefined;
+  const value = surface.props.initialFocus;
+  return value === 'title' || value === 'body' ? value : undefined;
 }
 
 export function surfaceSupports(
@@ -368,8 +84,18 @@ function transitionFinishedOnMount(surface: WorkColumnSurface): number | null {
   }
 }
 
-function WorkColumnSurfaceMount({ surface }: { surface: WorkColumnSurface }) {
+function WorkColumnSurfaceMount({ surface, focused }: { surface: WorkColumnSurface; focused: boolean }) {
   const immediateTransitionId = transitionFinishedOnMount(surface);
+  const presentationScope = `${surface.kind}:${surface.instanceKey}:${'fileIdentity' in surface ? surface.fileIdentity.path : ''}`;
+  const presentationOwner = useMemo(() => ({}), [presentationScope]);
+  const reportPresentation = useCallback((update: SurfacePresentationUpdate) => {
+    reportWorkspaceSurfacePresentation(surface.instanceKey, update, presentationOwner);
+  }, [presentationOwner, surface.instanceKey]);
+  const registerLifecycle = useCallback((lifecycle: SurfaceLifecycle | null, owner?: object) => {
+    registerWorkspaceSurfaceLifecycle(surface.instanceKey, lifecycle, owner);
+  }, [surface.instanceKey]);
+
+  useLayoutEffect(() => registerStartupSurfaceHostView('main-third', surface.instanceKey), [surface.instanceKey]);
 
   useLayoutEffect(() => {
     // These views have no DocumentContainer to finish the transition after
@@ -379,26 +105,29 @@ function WorkColumnSurfaceMount({ surface }: { surface: WorkColumnSurface }) {
     }
   }, [immediateTransitionId]);
 
-  return getWorkColumnSurfaceDefinition(surface).render(surface);
+  useLayoutEffect(() => registerWorkspaceSurfacePresentationOwner(surface.instanceKey, presentationOwner),
+    [presentationOwner, surface.instanceKey]);
+
+  return getWorkColumnSurfaceDefinition(surface, reportPresentation, registerLifecycle, focused).render();
 }
 
-export function WorkColumnSurfaceHost({ surface }: { surface: WorkColumnSurface }) {
+export function WorkColumnSurfaceHost({ surface, focused = false }: { surface: WorkColumnSurface; focused?: boolean }) {
   const instanceKey = `${surface.kind}:${surface.instanceKey}`;
-  const definition = getWorkColumnSurfaceDefinition(surface);
-  return (
-    <SurfaceSuspenseHost
-      instanceKey={instanceKey}
-      loadingTone={definition.chrome}
-    >
-      <WorkColumnSurfaceMount surface={surface} />
-    </SurfaceSuspenseHost>
-  );
+  return <WorkColumnSurfaceMount key={instanceKey} surface={surface} focused={focused} />;
 }
 
-export function WorkColumnContentHost({ content }: { content: WorkColumnContentPresentation }) {
+export function WorkColumnContentHost({ content, focused = false, startupIdentity = '' }: { content: WorkColumnContentPresentation; focused?: boolean; startupIdentity?: string }) {
   if (content.status === 'empty') {
-    return <WorkspaceEmptyState tone={content.tone} message={content.message} />;
+    reportEmptyWorkspaceSurfaceForIdentity('main-third', startupIdentity);
+    const baseAppearance = content.tone === 'agent' ? workspaceSurfaceAppearance('agent-conversation')
+      : workspaceSurfaceAppearance('file-markdown');
+    const appearance = content.actions?.length ? { ...baseAppearance, emptyDecoration: 'none' as const } : baseAppearance;
+    return <WorkspaceSurfaceStateView
+      appearance={appearance}
+      state={{ status: 'empty', reason: content.reason, message: { key: 'document.file.loading' }, actions: content.actions }}
+      messageOverride={content.message}
+    />;
   }
 
-  return <WorkColumnSurfaceHost surface={content.surface} />;
+  return <WorkColumnSurfaceHost surface={content.surface} focused={focused} />;
 }
diff --git a/app/flowix-web/features/surface/resolver.test.ts b/app/flowix-web/features/surface/resolver.test.ts
index a5ca9b540..60f60e858 100644
--- a/app/flowix-web/features/surface/resolver.test.ts
+++ b/app/flowix-web/features/surface/resolver.test.ts
@@ -13,7 +13,6 @@ import { ensureFileDisplayIdentity } from '@/lib/file-display-registry';
 
 function markdownSurface(options: {
   filePath?: string;
-  memoId?: string | null;
   transitionId?: number | null;
   notebookId?: string | null;
   notebookPath?: string | null;
@@ -21,7 +20,7 @@ function markdownSurface(options: {
 } = {}): MDSurface {
   return {
     kind: 'md',
-    instanceKey: options.memoId ? `memo:${options.memoId}` : `path:${options.filePath ?? '/notebook/note.md'}`,
+    instanceKey: `path:${options.filePath ?? '/notebook/note.md'}`,
     fileIdentity: {
       path: options.filePath ?? '/notebook/note.md',
       displayId: `display:${options.filePath ?? '/notebook/note.md'}`,
diff --git a/app/flowix-web/features/surface/resolver.ts b/app/flowix-web/features/surface/resolver.ts
index d70d8154d..a35bebc3a 100644
--- a/app/flowix-web/features/surface/resolver.ts
+++ b/app/flowix-web/features/surface/resolver.ts
@@ -1,6 +1,9 @@
 import { collectionSessionKey } from '@/lib/collection-session-key';
 import { canonicalPath } from '@/lib/path';
-import { externalFileViewKind } from '@features/editor/public/code-file';
+import {
+  resolveWorkspaceFileSurfaceKind,
+  workspaceFileSurfaceSupportsHost,
+} from '@features/workspace/public/surface-api';
 import type {
   DocumentSurfaceContext,
   PluginWorkbenchContext,
@@ -12,6 +15,8 @@ import type {
 } from './types';
 import type { WorkColumnTarget } from '@features/workspace/store/work-column-target';
 import { requireFileDisplayIdentity } from '@/lib/file-display-registry';
+import { resetCurrentCollectionView } from '@features/workspace/use-cases/workspace-navigation';
+import { toast } from '@/lib/toast';
 
 function assertNever(value: never): never {
   throw new Error(`Unsupported plugin artifact renderer: ${String(value)}`);
@@ -21,7 +26,7 @@ function emptyContent(
   message: string,
   reason: WorkColumnEmptyReason,
   tone: WorkColumnEmptyStateTone = 'document',
-): WorkColumnContentPresentation {
+): Extract<WorkColumnContentPresentation, { status: 'empty' }> {
   return { status: 'empty', message, reason, tone };
 }
 
@@ -36,21 +41,12 @@ function resolveExternalDocumentSurface(
   const { fileIdentity } = document.identity;
   const filePath = fileIdentity.path;
   const scopePath = document.identity.scopePath;
-
-  if (/\.lib\.ya?ml$/i.test(filePath)) {
-    return { kind: 'media-library-file', instanceKey, fileIdentity, notebookPath: scopePath, notebookId: null };
-  }
-
-  if (/\.table\.ya?ml$/i.test(filePath)) {
-    return {
-      kind: 'table-file',
-      instanceKey,
-      fileIdentity,
-      props: { filePath, fileIdentity, notebookPath: scopePath, notebookId: null },
-    };
+  const fileSurfaceKind = resolveWorkspaceFileSurfaceKind(filePath);
+  if (!workspaceFileSurfaceSupportsHost(fileSurfaceKind, 'main-third')) {
+    throw new Error(`Work column does not support file surface '${fileSurfaceKind}'`);
   }
 
-  switch (externalFileViewKind(filePath)) {
+  switch (fileSurfaceKind) {
     case 'markdown':
       return { kind: 'md', instanceKey, fileIdentity, props: document.documentProps };
     case 'html':
@@ -67,6 +63,15 @@ function resolveExternalDocumentSurface(
       return { kind: 'unavailable-file', instanceKey, fileIdentity, scopePath, props: document.documentProps };
     case 'unavailable':
       return { kind: 'unavailable-file', instanceKey, fileIdentity, scopePath, props: document.documentProps };
+    case 'table':
+      return {
+        kind: 'table-file',
+        instanceKey,
+        fileIdentity,
+        props: { filePath, fileIdentity, notebookPath: scopePath, notebookId: null },
+      };
+    case 'media-library':
+      return { kind: 'media-library-file', instanceKey, fileIdentity, notebookPath: scopePath, notebookId: null };
   }
 }
 
@@ -123,11 +128,26 @@ function resolveWorkColumnTarget(
   target: WorkColumnTarget,
   input: Pick<ResolveWorkColumnContentInput, 'document' | 'pluginWorkbench' | 'emptyMessage'>,
 ): WorkColumnContentPresentation {
+  if ((target.kind === 'collection' || target.kind === 'table' || target.kind === 'media-library') && target.unavailableReason) {
+    return {
+      ...emptyContent(target.unavailableReason, 'invalid-target'),
+      actions: [{
+        id: 'reset-current-collection-view',
+        label: { key: 'collection.resetCurrentView' },
+        enabled: Boolean(target.filePath),
+        run: async () => {
+          try { await resetCurrentCollectionView(target.filePath, target.notebookPath, target.notebookId); }
+          catch (error) { toast.error(error instanceof Error ? error.message : '重置当前视图失败'); }
+        },
+      }],
+    };
+  }
   switch (target.kind) {
+    case 'folder-collection':
+      return surfaceContent({ kind: 'folder-collection', instanceKey: `${target.notebookId}:${target.folderPath}`,
+        notebookId: target.notebookId, notebookPath: target.notebookPath, folderPath: target.folderPath, folderName: target.folderName });
     case 'empty':
       return emptyContent(input.emptyMessage, 'no-target');
-    case 'document-list':
-      return surfaceContent({ kind: 'document-list', displayId: target.displayId, instanceKey: target.displayId, folderPath: target.scope.path, notebookPath: target.scope.notebookPath, notebookId: target.scope.notebookId, filters: target.filters });
     case 'web':
       return surfaceContent({ kind: 'web', instanceKey: target.url, url: target.url });
     case 'agent-conversation':
@@ -148,7 +168,6 @@ function resolveWorkColumnTarget(
     case 'media':
       return resolveMediaTargetContent(target);
     case 'collection': {
-      if (target.unavailableReason) return emptyContent(target.unavailableReason, 'invalid-target');
       const fileIdentity = { path: target.filePath, displayId: target.displayId };
       if (target.collectionType === 'media_library') {
         return surfaceContent({ kind: 'media-library-file', instanceKey: target.displayId, fileIdentity, notebookId: target.notebookId, notebookPath: target.notebookPath });
diff --git a/app/flowix-web/features/surface/resource-file-icon.tsx b/app/flowix-web/features/surface/resource-file-icon.tsx
index c2558a9c6..74ef08206 100644
--- a/app/flowix-web/features/surface/resource-file-icon.tsx
+++ b/app/flowix-web/features/surface/resource-file-icon.tsx
@@ -192,3 +192,19 @@ export function ResourceFolderIcon({ className, hidden = false }: {
     </span>
   );
 }
+
+/** DOM adapter for non-React editor NodeViews, sharing file-tree glyphs and themes. */
+export function createResourceFileIcon(path: string, className = '', size = 14) {
+  const dom = document.createElement('span');
+  dom.className = className;
+  dom.setAttribute('aria-hidden', 'true');
+  const render = () => {
+    const icon = getResourceSetiIcon(path, getSetiThemeVariant());
+    dom.dataset.setiIcon = icon.definitionKey;
+    dom.textContent = icon.glyph;
+    Object.assign(dom.style, setiIconStyle(icon.color, size));
+  };
+  render();
+  const destroy = subscribeToSetiTheme(render);
+  return { dom, destroy };
+}
diff --git a/app/flowix-web/features/surface/types.ts b/app/flowix-web/features/surface/types.ts
index 7226f7eb3..34f5a4de3 100644
--- a/app/flowix-web/features/surface/types.ts
+++ b/app/flowix-web/features/surface/types.ts
@@ -1,6 +1,5 @@
 import type { ComponentProps } from 'react';
 import type { AgentConversationDetail } from '@features/agent/components/agent-conversation-detail';
-import type { DocumentContainer } from '@features/document/components/document-container';
 import type {
   PluginDocumentViewProps,
   PluginWorkbenchProps,
@@ -10,31 +9,16 @@ import type { PluginDescriptor } from '@platform/tauri/client';
 import type { WorkColumnNavigationState } from '@features/workspace/store/work-column-target';
 import type { FileDisplayIdentity } from '@/lib/file-display-registry';
 import type { TableDocumentViewProps } from '@features/multidimensional-table/public/surface-api';
+import type { WorkspaceSurfaceCapability, SurfaceHeaderStyle, SurfaceEmptyReason } from '@features/workspace/public/surface-api';
 
-export type WorkColumnSurfaceCapability =
-  | 'edit'
-  | 'search'
-  | 'memo-colors'
-  | 'properties'
-  | 'copy-content'
-  | 'export-content'
-  | 'save-template'
-  | 'version-history'
-  | 'fit'
-  | 'zoom'
-  | 'fullscreen'
-  | 'open-source'
-  | 'run-agent'
-  | 'stream-conversation';
+import type { ExternalDocumentProps } from './workspace-surface-renderer-contract';
+
+export type WorkColumnSurfaceCapability = WorkspaceSurfaceCapability;
 
 /** Visual chrome owned by the currently mounted surface. */
-export type WorkColumnSurfaceChrome = 'document' | 'agent' | 'media';
+export type WorkColumnSurfaceChrome = SurfaceHeaderStyle;
 
-export type WorkColumnEmptyReason =
-  | 'no-target'
-  | 'stale-context'
-  | 'invalid-target'
-  | 'invalid-artifact';
+export type WorkColumnEmptyReason = Exclude<SurfaceEmptyReason, 'no-content'>;
 
 export type WorkColumnEmptyStateTone = 'document' | 'agent';
 
@@ -47,9 +31,7 @@ interface FileSurfaceBase extends SurfaceBase {
   fileIdentity: FileDisplayIdentity;
 }
 
-export type ExternalDocumentProps = Omit<ComponentProps<typeof DocumentContainer>, 'isExternalDocument' | 'fileIdentity'> & {
-  isExternalDocument: true;
-};
+export type { ExternalDocumentProps } from './workspace-surface-renderer-contract';
 
 /** Markdown documents opened through their file path, including notebook notes. */
 export interface MDSurface extends FileSurfaceBase {
@@ -92,6 +74,14 @@ export interface MediaLibraryFileSurface extends FileSurfaceBase {
   notebookId: string | null;
 }
 
+export interface FolderCollectionSurface extends SurfaceBase {
+  kind: 'folder-collection';
+  notebookId: string;
+  notebookPath: string;
+  folderPath: string;
+  folderName: string;
+}
+
 export interface HtmlFileSurface extends FileSurfaceBase {
   kind: 'html-file';
   scopePath: string | null;
@@ -155,17 +145,6 @@ export interface WebSurface extends SurfaceBase {
   url: string;
 }
 
-export interface DocumentListSurface extends SurfaceBase {
-  kind: 'document-list';
-  displayId: string;
-  folderPath: string;
-  notebookPath: string;
-  notebookId: string | null;
-  filters: { resourceKinds?: string[]; tags?: string[]; customFilterId?: string };
-  mediaScope?: { relativePath: string; depth: 'direct_children' | 'descendants' };
-  mediaDatasetActive?: boolean;
-}
-
 export type WorkColumnSurface =
   | MDSurface
   | CodeSurface
@@ -174,6 +153,7 @@ export type WorkColumnSurface =
   | VideoFileSurface
   | TableFileSurface
   | MediaLibraryFileSurface
+  | FolderCollectionSurface
   | HtmlFileSurface
   | UnavailableFileSurface
   | MediaResourceSurface
@@ -184,7 +164,6 @@ export type WorkColumnSurface =
   | PluginArtifactSurface
   | AgentConversationSurface
   | PluginWorkbenchSurface
-  | DocumentListSurface
   | WebSurface;
 
 export type WorkColumnSurfaceKind = WorkColumnSurface['kind'];
@@ -199,6 +178,7 @@ export type WorkColumnContentPresentation =
       reason: WorkColumnEmptyReason;
       tone: WorkColumnEmptyStateTone;
       message: string;
+      actions?: readonly import('@features/workspace/model/surface-contract').SurfaceAction[];
     };
 
 export type DocumentSurfaceIdentity =
diff --git a/app/flowix-web/features/surface/use-document-list-data.ts b/app/flowix-web/features/surface/use-document-list-data.ts
index fc8903da7..adc2345df 100644
--- a/app/flowix-web/features/surface/use-document-list-data.ts
+++ b/app/flowix-web/features/surface/use-document-list-data.ts
@@ -4,7 +4,7 @@ import { subscribe } from '@platform/tauri/event-bus';
 import { canonicalPath, joinNotebookMemoPath } from '@/lib/path';
 import { createLogger } from '@/lib/logger';
 import type { MediaLibraryRecord } from '@features/media-library/model';
-import type { DocumentListSurface } from './types';
+import type { DocumentListViewContext } from './document-list-view-model';
 
 const logger = createLogger('document-list-data');
 const MEDIA_LIBRARY_PAGE_SIZE = 30;
@@ -47,14 +47,14 @@ function mediaResourceListItem(resource: { relativePath: string; kind: 'image' |
 }
 
 /** Owns paging, cancellation and coalesced refreshes; UI action permissions are separate. */
-export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords, refreshPaused }: {
-  surface: DocumentListSurface;
+export function useDocumentListData({ listContext, mediaLibrary, mediaLibraryRecords, refreshPaused }: {
+  listContext: DocumentListViewContext;
   mediaLibrary: boolean;
   mediaLibraryRecords: MediaLibraryRecord[];
   refreshPaused: boolean;
 }) {
-  const resourceKindsKey = (surface.filters.resourceKinds ?? []).join('\u0000');
-  const hasMediaDataset = Boolean(surface.mediaScope || surface.mediaDatasetActive);
+  const resourceKindsKey = (listContext.filters.resourceKinds ?? []).join('\u0000');
+  const hasMediaDataset = Boolean(listContext.mediaScope || listContext.mediaDatasetActive);
   const hasLinkedMedia = mediaLibraryRecords.length > 0;
   const [items, setItems] = useState<DocumentPageItem[]>([]);
   const [linkedItems, setLinkedItems] = useState<DocumentPageItem[]>([]);
@@ -81,19 +81,19 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
     setRevision((value) => value + 1);
   }, []);
   useEffect(() => subscribe<{ notebookId: string }>('file-management-changed', ({ notebookId }) => {
-    if (notebookId === surface.notebookId) requestRefresh();
-  }), [requestRefresh, surface.notebookId]);
+    if (notebookId === listContext.notebookId) requestRefresh();
+  }), [requestRefresh, listContext.notebookId]);
   useEffect(() => subscribe<{ notebookId: string }>('media-properties-changed', ({ notebookId }) => {
-    if (notebookId === surface.notebookId) requestRefresh();
-  }), [requestRefresh, surface.notebookId]);
+    if (notebookId === listContext.notebookId) requestRefresh();
+  }), [requestRefresh, listContext.notebookId]);
   useEffect(() => subscribe<FileBrowserDirectoriesChangedEvent>(
     'file-browser-directories-changed',
     (event) => {
-      if (canonicalPath(event.rootPath) !== canonicalPath(surface.notebookPath)) return;
+      if (canonicalPath(event.rootPath) !== canonicalPath(listContext.notebookPath)) return;
       const changedPaths = event.paths ?? [];
       // Library-config mutations update the catalog separately, but do not change the media rows shown here.
       if (mediaLibrary && changedPaths.length > 0 && changedPaths.every((path) => /\.lib\.ya?ml$/i.test(path))) return;
-      const root = canonicalPath(surface.notebookPath).replace(/\/$/, '');
+      const root = canonicalPath(listContext.notebookPath).replace(/\/$/, '');
       const directories = event.directories.filter((directory) => {
         const path = canonicalPath(directory);
         if (path === root) return true;
@@ -102,7 +102,7 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
       if (directories.length === 0) return;
       requestRefresh();
     },
-  ), [mediaLibrary, requestRefresh, surface.notebookPath]);
+  ), [mediaLibrary, requestRefresh, listContext.notebookPath]);
   useEffect(() => {
     if (refreshPaused) {
       loadingRef.current = false;
@@ -112,7 +112,7 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
     pendingRefreshRef.current = false;
     const generation = ++requestGenerationRef.current;
     let cancelled = false;
-    if (!surface.notebookId) {
+    if (!listContext.notebookId) {
       loadingRef.current = false;
       setItems([]);
       setError(true);
@@ -140,7 +140,7 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
     setLoadingMore(false);
     setMoreError(false);
     setError(false);
-    const listIdentity = JSON.stringify([surface.displayId, surface.notebookPath, mediaLibrary]);
+    const listIdentity = JSON.stringify([listContext.displayId, listContext.notebookPath, mediaLibrary]);
     if (loadedListIdentityRef.current !== listIdentity) {
       setItems([]);
       setLinkedItems([]);
@@ -151,12 +151,12 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
     setNextCursor(null);
     const pageRequest = mediaLibrary
       ? hasMediaDataset
-        ? mediaResources.listPage(surface.notebookPath, (surface.filters.resourceKinds ?? ['image', 'video']).filter((kind): kind is 'image' | 'video' => kind === 'image' || kind === 'video'), null, MEDIA_LIBRARY_PAGE_SIZE, surface.mediaScope?.relativePath ?? null, surface.mediaScope?.depth)
+        ? mediaResources.listPage(listContext.notebookPath, (listContext.filters.resourceKinds ?? ['image', 'video']).filter((kind): kind is 'image' | 'video' => kind === 'image' || kind === 'video'), null, MEDIA_LIBRARY_PAGE_SIZE, listContext.mediaScope?.relativePath ?? null, listContext.mediaScope?.depth)
         : Promise.resolve({ resources: [], nextCursor: null, hasMore: false } satisfies MediaResourcePage)
-      : files.listDocumentPage({ notebookId: surface.notebookId, folderPath: surface.folderPath, resourceKinds: surface.filters.resourceKinds });
+      : files.listDocumentPage({ notebookId: listContext.notebookId, folderPath: listContext.folderPath, resourceKinds: listContext.filters.resourceKinds });
     const nextLinkedItems: DocumentPageItem[] = [];
     const linkedRequest = mediaLibrary
-      ? loadLinkedMediaItems(mediaLibraryRecords, surface.notebookPath, (batch) => {
+      ? loadLinkedMediaItems(mediaLibraryRecords, listContext.notebookPath, (batch) => {
         if (cancelled || generation !== requestGenerationRef.current) return;
         nextLinkedItems.push(...batch);
         setLinkedItems([...nextLinkedItems]);
@@ -169,7 +169,7 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
       if (cancelled || generation !== requestGenerationRef.current) return;
       if (mediaLibrary) {
         const mediaPage = page as MediaResourcePage;
-        setItems(mediaPage.resources.map((resource) => mediaResourceListItem(resource, surface.notebookPath)).filter((item): item is DocumentPageItem => item !== null));
+        setItems(mediaPage.resources.map((resource) => mediaResourceListItem(resource, listContext.notebookPath)).filter((item): item is DocumentPageItem => item !== null));
         setFolders([]);
         setNextCursor(mediaPage.nextCursor);
         setHasMore(mediaPage.hasMore);
@@ -208,19 +208,19 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
       }
     });
     return () => { cancelled = true; requestGenerationRef.current += 1; };
-  }, [hasMediaDataset, hasLinkedMedia, refreshPaused, mediaLibrary, mediaLibraryRecords, revision, surface.displayId, surface.folderPath, surface.mediaScope?.relativePath, surface.mediaScope?.depth, surface.mediaDatasetActive, surface.notebookId, surface.notebookPath, resourceKindsKey]);
+  }, [hasMediaDataset, hasLinkedMedia, refreshPaused, mediaLibrary, mediaLibraryRecords, revision, listContext.displayId, listContext.folderPath, listContext.mediaScope?.relativePath, listContext.mediaScope?.depth, listContext.mediaDatasetActive, listContext.notebookId, listContext.notebookPath, resourceKindsKey]);
   const loadMore = useCallback(() => {
-    if (!surface.notebookId || refreshPausedRef.current || (mediaLibrary && !hasMediaDataset) || !nextCursor || loading || loadingMore || !hasMore) return;
+    if (!listContext.notebookId || refreshPausedRef.current || (mediaLibrary && !hasMediaDataset) || !nextCursor || loading || loadingMore || !hasMore) return;
     const generation = requestGenerationRef.current;
     setLoadingMore(true);
     setMoreError(false);
     const pageRequest = mediaLibrary
-      ? mediaResources.listPage(surface.notebookPath, (surface.filters.resourceKinds ?? ['image', 'video']).filter((kind): kind is 'image' | 'video' => kind === 'image' || kind === 'video'), nextCursor, MEDIA_LIBRARY_PAGE_SIZE, surface.mediaScope?.relativePath ?? null, surface.mediaScope?.depth)
-      : files.listDocumentPage({ notebookId: surface.notebookId, folderPath: surface.folderPath, resourceKinds: surface.filters.resourceKinds, cursor: nextCursor });
+      ? mediaResources.listPage(listContext.notebookPath, (listContext.filters.resourceKinds ?? ['image', 'video']).filter((kind): kind is 'image' | 'video' => kind === 'image' || kind === 'video'), nextCursor, MEDIA_LIBRARY_PAGE_SIZE, listContext.mediaScope?.relativePath ?? null, listContext.mediaScope?.depth)
+      : files.listDocumentPage({ notebookId: listContext.notebookId, folderPath: listContext.folderPath, resourceKinds: listContext.filters.resourceKinds, cursor: nextCursor });
     void pageRequest.then((page) => {
       if (generation !== requestGenerationRef.current) return;
       const nextItems = mediaLibrary
-        ? (page as MediaResourcePage).resources.map((resource) => mediaResourceListItem(resource, surface.notebookPath)).filter((item): item is DocumentPageItem => item !== null)
+        ? (page as MediaResourcePage).resources.map((resource) => mediaResourceListItem(resource, listContext.notebookPath)).filter((item): item is DocumentPageItem => item !== null)
         : (page as DocumentPage).items;
       setItems((current) => [...current, ...nextItems]);
       setNextCursor(page.nextCursor);
@@ -231,7 +231,7 @@ export function useDocumentListData({ surface, mediaLibrary, mediaLibraryRecords
     }).finally(() => {
       if (generation === requestGenerationRef.current) setLoadingMore(false);
     });
-  }, [hasMediaDataset, hasMore, loading, loadingMore, mediaLibrary, nextCursor, resourceKindsKey, surface.filters.resourceKinds, surface.folderPath, surface.mediaScope?.relativePath, surface.mediaScope?.depth, surface.mediaDatasetActive, surface.notebookId, surface.notebookPath]);
+  }, [hasMediaDataset, hasMore, loading, loadingMore, mediaLibrary, nextCursor, resourceKindsKey, listContext.filters.resourceKinds, listContext.folderPath, listContext.mediaScope?.relativePath, listContext.mediaScope?.depth, listContext.mediaDatasetActive, listContext.notebookId, listContext.notebookPath]);
   return { items, linkedItems, folders, loading, loadingLinkedItems, loadingMore, moreError, hasMore,
     hasMediaDataset, hasLinkedMedia, error, loadMore, refresh: requestRefresh };
 }
diff --git a/app/flowix-web/features/surface/work-column-surface-adapter.ts b/app/flowix-web/features/surface/work-column-surface-adapter.ts
new file mode 100644
index 000000000..dac3b7b3c
--- /dev/null
+++ b/app/flowix-web/features/surface/work-column-surface-adapter.ts
@@ -0,0 +1,41 @@
+import { setCollectionActiveView } from '@features/workspace/use-cases/collection-view-state';
+import { externalFileViewKind } from '@features/editor/public/code-file';
+import type { WorkColumnSurface } from './types';
+import type { WorkspaceSurfaceRendererData } from './workspace-surface-renderer-contract';
+
+/** Convert Work's navigation discriminants to the canonical renderer input. */
+export function workspaceSurfaceRendererDataFromWorkSurface(surface: WorkColumnSurface): WorkspaceSurfaceRendererData {
+  switch (surface.kind) {
+    case 'folder-collection': return { kind: 'collection', notebookId: surface.notebookId,
+      notebookPath: surface.notebookPath, folderPath: surface.folderPath, folderName: surface.folderName };
+    case 'media': return { kind: 'media', fileIdentity: surface.fileIdentity, notebookPath: surface.notebookPath, notebookId: surface.notebookId, resourceKind: surface.resourceKind };
+    case 'agent-conversation': return { kind: 'agent-conversation', instanceId: surface.instanceId };
+    case 'mindmap': return { kind: 'mindmap', props: surface.props };
+    case 'html':
+    case 'json':
+    case 'text':
+    case 'plugin-artifact': return { kind: 'plugin-artifact', props: surface.props };
+    case 'plugin-workbench': return { kind: 'plugin-workbench', props: surface.props };
+    case 'md': return { kind: 'file-markdown', fileIdentity: surface.fileIdentity, scopePath: surface.props.externalScopePath ?? null, documentProps: surface.props };
+    case 'code': return { kind: 'file-code', fileIdentity: surface.fileIdentity, scopePath: surface.props.externalScopePath ?? null, documentProps: surface.props, instanceKey: surface.instanceKey };
+    case 'csv-file': return { kind: 'file-csv', fileIdentity: surface.fileIdentity, scopePath: surface.scopePath };
+    case 'image-file': return { kind: 'file-image', fileIdentity: surface.fileIdentity, scopePath: surface.scopePath };
+    case 'video-file': return { kind: 'file-video', fileIdentity: surface.fileIdentity, scopePath: surface.scopePath };
+    case 'table-file': {
+      const { notebookId, expectedCollectionId } = surface.props;
+      return { kind: 'file-table', fileIdentity: surface.fileIdentity, props: {
+        ...surface.props,
+        onActiveViewChange: notebookId && expectedCollectionId
+          ? (viewId) => setCollectionActiveView({ host: 'main-third' }, { notebookId, collectionId: expectedCollectionId }, viewId)
+          : surface.props.onActiveViewChange,
+      } };
+    }
+    case 'media-library-file': return { kind: 'file-media-library', fileIdentity: surface.fileIdentity, notebookPath: surface.notebookPath, notebookId: surface.notebookId };
+    case 'html-file': return { kind: 'file-html', fileIdentity: surface.fileIdentity, scopePath: surface.scopePath, documentProps: surface.props };
+    case 'unavailable-file':
+      return externalFileViewKind(surface.fileIdentity.path) === 'docx'
+        ? { kind: 'file-docx', fileIdentity: surface.fileIdentity, scopePath: surface.scopePath }
+        : { kind: 'file-unavailable', fileIdentity: surface.fileIdentity, scopePath: surface.scopePath, documentProps: surface.props };
+    case 'web': return { kind: 'web', url: surface.url };
+  }
+}
diff --git a/app/flowix-web/features/surface/work-file-browser-view.test.tsx b/app/flowix-web/features/surface/work-file-browser-view.test.tsx
new file mode 100644
index 000000000..0c6ca71bd
--- /dev/null
+++ b/app/flowix-web/features/surface/work-file-browser-view.test.tsx
@@ -0,0 +1,45 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { CodeSurfaceFileBrowser } from './work-file-browser-view';
+import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
+import type { CodeSurfaceFileTree } from './code-surface-view';
+
+vi.mock('@features/workspace/public/open-surface-api', () => ({ openWorkspaceSurface: vi.fn().mockResolvedValue(null) }));
+vi.mock('./code-surface-view', () => ({ CodeSurfaceView: ({ fileTree }: { fileTree: CodeSurfaceFileTree }) => <>
+  <button onClick={() => fileTree.onSelectFile('/book/report.docx')}>docx</button>
+  <button onClick={() => fileTree.onSelectFile('/book/archive.bin')}>unsupported</button>
+  <button onClick={() => fileTree.onOpenFileInNewTab('/book/report.docx')}>browser</button>
+</> }));
+
+const initial = useWorkColumnStore.getState();
+let root: Root;
+let host: HTMLDivElement;
+beforeEach(async () => {
+  vi.clearAllMocks();
+  useWorkColumnStore.setState({ navigation: { ...initial.navigation, phase: 'committed', target: {
+    kind: 'external', path: '/book/main.ts', scopePath: '/book', transitionId: null,
+  } } });
+  host = document.createElement('div');
+  root = createRoot(host);
+  await act(async () => root.render(<CodeSurfaceFileBrowser surface={{ kind: 'code', instanceKey: 'code-main',
+    fileIdentity: { path: '/book/main.ts', displayId: 'main' }, props: { isExternalDocument: true } }} />));
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  useWorkColumnStore.setState(initial, true);
+});
+
+describe('Work file tree open destination', () => {
+  it.each(['docx', 'unsupported'])('keeps %s selection in Work', async (label) => {
+    const button = [...host.querySelectorAll('button')].find((item) => item.textContent === label)!;
+    await act(async () => button.click());
+    expect(openWorkspaceSurface).toHaveBeenCalledWith(expect.objectContaining({ host: 'main-third', target: expect.objectContaining({ kind: 'external' }) }));
+  });
+  it('opens Browser when explicitly requested', async () => {
+    const button = [...host.querySelectorAll('button')].find((item) => item.textContent === 'browser')!;
+    await act(async () => button.click());
+    expect(openWorkspaceSurface).toHaveBeenCalledWith(expect.objectContaining({ host: 'browser-column', options: { browserDisposition: 'open-in-column' } }));
+  });
+});
diff --git a/app/flowix-web/features/surface/work-file-browser-view.tsx b/app/flowix-web/features/surface/work-file-browser-view.tsx
index 6674f8f70..ce71e24d2 100644
--- a/app/flowix-web/features/surface/work-file-browser-view.tsx
+++ b/app/flowix-web/features/surface/work-file-browser-view.tsx
@@ -1,8 +1,6 @@
 import { useCallback, useRef } from 'react';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
-import { openExternalTarget } from '@features/workspace/use-cases/workspace-navigation';
-import { openMediaTarget } from '@features/workspace/use-cases/workspace-navigation';
-import { openBrowserColumnTarget } from '@features/workspace/use-cases/browser-column-navigation';
+import { openWorkspaceSurface } from '@features/workspace/public/open-surface-api';
 import { CodeSurfaceView } from './code-surface-view';
 import type { FileBrowserContext } from '@features/workspace/store/file-browser-target';
 import { toast } from '@/lib/toast';
@@ -41,24 +39,16 @@ export function CodeSurfaceFileBrowser({ surface }: { surface: CodeSurface }) {
       const current = useWorkColumnStore.getState().navigation;
       if (current.phase === 'loading' || current.target.kind !== 'external' || current.target.path !== target.path) return;
       const fileKind = externalFileViewKind(path);
-      if (fileKind === 'unavailable' || fileKind === 'docx') {
-        await openBrowserColumnTarget({
-          ...context,
-          kind: 'file-browser',
-          activeFilePath: path,
-          folderPath: null,
-        });
-        return;
-      }
       if ((fileKind === 'image' || fileKind === 'video') && context.scopePath) {
-        await openMediaTarget({
-          filePath: path,
-          notebookId: context.notebookId,
-          notebookPath: context.scopePath,
-          resourceKind: fileKind,
+        await openWorkspaceSurface({
+          host: 'main-third',
+          target: { kind: 'media', filePath: path, notebookId: context.notebookId, notebookPath: context.scopePath, resourceKind: fileKind },
         });
       } else {
-        await openExternalTarget(path, { destination: 'main-third', scopePath: context.scopePath, fileBrowser: context });
+        await openWorkspaceSurface({
+          host: 'main-third',
+          target: { kind: 'external', path, scopePath: context.scopePath, transitionId: null, fileBrowser: context },
+        });
       }
     } catch {
       toast.error(t('tabWindow.switchFailed'));
@@ -75,7 +65,11 @@ export function CodeSurfaceFileBrowser({ surface }: { surface: CodeSurface }) {
       ...context, kind: 'file-browser', activeFilePath: target.path,
       onSelectFile: (path) => { void selectFile(path); },
       onOpenFileInNewTab: (path) => {
-        void openBrowserColumnTarget({ ...context, kind: 'file-browser', activeFilePath: path, folderPath: null }, 'open-in-column');
+        void openWorkspaceSurface({
+          host: 'browser-column',
+          target: { ...context, kind: 'file-browser', activeFilePath: path, folderPath: null },
+          options: { browserDisposition: 'open-in-column' },
+        });
       },
       onContextChange: updateView,
       onTreeVisibleChange: (fileTreeVisible) => updateView({ fileTreeVisible }),
diff --git a/app/flowix-web/features/surface/workspace-file-browser-surface-renderer.tsx b/app/flowix-web/features/surface/workspace-file-browser-surface-renderer.tsx
new file mode 100644
index 000000000..9e9438a5d
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-file-browser-surface-renderer.tsx
@@ -0,0 +1,147 @@
+'use client';
+
+import { collectionDisplayDescriptor, findCollectionDisplayPath } from '@/lib/collection-display-registry';
+import { useExternalFileContentDetection } from '@features/editor/use-external-file-content-detection';
+import { resolveWorkspaceFileSurfaceKind, workspaceSurfaceAppearance } from '@features/workspace/public/surface-api';
+import { FileBrowserView } from './file-browser-view';
+import { useLayoutEffect } from 'react';
+import { getWorkspaceSurfaceRendererDefinition } from './workspace-surface-renderer-registry';
+import type { WorkspaceSurfaceRendererData, WorkspaceSurfaceRenderContext } from './workspace-surface-renderer-contract';
+import { WorkspaceSurfaceStateView } from './workspace-surface-state-view';
+import { resetCurrentCollectionView } from '@features/workspace/use-cases/workspace-navigation';
+import { toast } from '@/lib/toast';
+import { workspaceSurfaceCapabilities } from '@features/workspace/public/surface-api';
+
+export function FileBrowserRenderer({ surface: data, context }: {
+  surface: Extract<WorkspaceSurfaceRendererData, { kind: 'file-browser' }>;
+  context: WorkspaceSurfaceRenderContext;
+}) {
+  const surface = data.props;
+  const fileSurfaceKind = surface.activeFilePath
+    ? resolveWorkspaceFileSurfaceKind(surface.activeFilePath)
+    : null;
+  const { isTextContent, loading: contentDetectionLoading } = useExternalFileContentDetection(
+    surface.activeFilePath,
+    surface.scopePath,
+    fileSurfaceKind === 'unavailable',
+  );
+  const fileKind = surface.collectionType === 'media_library'
+    ? 'media-library'
+    : surface.collectionType === 'table'
+      ? 'table'
+      : resolveWorkspaceFileSurfaceKind(surface.activeFilePath ?? '', null, isTextContent);
+  const dynamicKind = `file-${fileKind}` as const;
+  const collectionLocationLoading = Boolean(surface.fileIdentity
+    && collectionDisplayDescriptor(surface.fileIdentity.displayId)
+    && !findCollectionDisplayPath(surface.fileIdentity.displayId));
+  // Publish the resolver baseline before content renderers publish their state.
+  useLayoutEffect(() => {
+    if (!surface.activeFilePath) {
+      context.reportPresentation?.({
+        appearance: workspaceSurfaceAppearance('file-browser'),
+        capabilities: workspaceSurfaceCapabilities('file-browser'),
+        state: { status: 'ready' },
+      });
+      return;
+    }
+    const state = contentDetectionLoading
+          ? { status: 'loading' as const, phase: 'content' as const, message: { key: 'document.file.loading' }, retainContent: true }
+        : surface.collectionUnavailableReason
+          ? { status: 'unavailable' as const, reason: 'unsupported' as const, message: { key: 'document.file.unavailable', fallbackText: surface.collectionUnavailableReason } }
+          : collectionLocationLoading
+            ? { status: 'loading' as const, phase: 'navigation' as const, message: { key: 'document.file.loading' }, retainContent: true }
+          : { status: 'loading' as const, phase: 'renderer' as const, message: { key: 'document.file.loading' }, retainContent: true };
+    context.reportPresentation?.({
+      appearance: workspaceSurfaceAppearance(dynamicKind),
+      capabilities: workspaceSurfaceCapabilities(dynamicKind),
+      state,
+    });
+  }, [collectionLocationLoading, context.reportPresentation, dynamicKind, contentDetectionLoading, surface.activeFilePath, surface.collectionUnavailableReason]);
+  if (!surface.activeFilePath) {
+    return <FileBrowserView surface={{ ...surface, sourceMenuEnabled: false }} />;
+  }
+
+  const stateAppearance = workspaceSurfaceAppearance(`file-${fileSurfaceKind ?? 'unavailable'}`);
+  if (surface.collectionUnavailableReason) return <WorkspaceSurfaceStateView
+    appearance={stateAppearance}
+    state={{
+      status: 'unavailable', reason: 'unsupported', message: { key: 'document.file.loading' },
+      actions: [{
+        id: 'reset-current-collection-view', label: { key: 'collection.resetCurrentView' }, enabled: true,
+        run: async () => {
+          try { await resetCurrentCollectionView(surface.activeFilePath!, surface.scopePath, surface.notebookId, { host: 'browser-column', tabId: context.viewId }); }
+          catch (error) { toast.error(error instanceof Error ? error.message : '重置当前视图失败'); }
+        },
+      }],
+    }}
+    messageOverride={surface.collectionUnavailableReason}
+  />;
+  if (surface.fileIdentity && collectionDisplayDescriptor(surface.fileIdentity.displayId) && !findCollectionDisplayPath(surface.fileIdentity.displayId)) return <WorkspaceSurfaceStateView
+    appearance={stateAppearance}
+    state={{ status: 'loading', phase: 'navigation', message: { key: 'document.file.loading' }, retainContent: false }}
+    messageOverride="正在解析集合位置…"
+  />;
+  if (contentDetectionLoading) return null;
+  const filePath = surface.activeFilePath;
+  const fileIdentity = surface.fileIdentity;
+  if (!filePath || !fileIdentity) return <FileBrowserView surface={{ ...surface, sourceMenuEnabled: false }} />;
+
+  const expectedCollectionId = collectionDisplayDescriptor(fileIdentity.displayId)?.collectionId ?? null;
+  let fileSurface: WorkspaceSurfaceRendererData;
+  switch (fileKind) {
+    case 'markdown':
+      fileSurface = { kind: 'file-markdown', fileIdentity, scopePath: surface.scopePath, documentProps: surface.documentProps };
+      break;
+    case 'code':
+      fileSurface = { kind: 'file-code', fileIdentity, scopePath: surface.scopePath, documentProps: surface.documentProps, instanceKey: context.viewId };
+      break;
+    case 'csv':
+      fileSurface = { kind: 'file-csv', fileIdentity, scopePath: surface.scopePath };
+      break;
+    case 'image':
+      fileSurface = { kind: 'file-image', fileIdentity, scopePath: surface.scopePath };
+      break;
+    case 'video':
+      fileSurface = { kind: 'file-video', fileIdentity, scopePath: surface.scopePath };
+      break;
+    case 'table':
+      fileSurface = {
+        kind: 'file-table', fileIdentity,
+        props: {
+          filePath, fileIdentity, notebookPath: surface.scopePath, notebookId: surface.notebookId ?? null,
+          expectedCollectionId, initialViewId: surface.collectionDisplay?.viewId,
+          onActiveViewChange: context.onCollectionActiveViewChange,
+        },
+      };
+      break;
+    case 'media-library':
+      fileSurface = {
+        kind: 'file-media-library', fileIdentity, notebookPath: surface.scopePath,
+        notebookId: surface.notebookId ?? null, expectedCollectionId,
+      };
+      break;
+    case 'html':
+      fileSurface = { kind: 'file-html', fileIdentity, scopePath: surface.scopePath, documentProps: surface.documentProps };
+      break;
+    case 'docx':
+      fileSurface = { kind: 'file-docx', fileIdentity, scopePath: surface.scopePath };
+      break;
+    case 'unavailable':
+      fileSurface = { kind: 'file-unavailable', fileIdentity, scopePath: surface.scopePath, documentProps: surface.documentProps };
+      break;
+  }
+
+  // The outer workspace view owns presentation and Suspense/error boundaries.
+  // Rendering content directly avoids applying the same state/notices twice.
+  return getWorkspaceSurfaceRendererDefinition(fileSurface).render(fileSurface, {
+      ...context,
+      viewId: context.viewId,
+      readOnly: Boolean(surface.documentProps.readOnly),
+      wrapInFileBrowser: (content) => <FileBrowserView surface={{
+        ...surface,
+        fileTreeEnabled: false,
+        sourceMenuEnabled: false,
+        content,
+      }} />,
+    });
+}
diff --git a/app/flowix-web/features/surface/workspace-surface-lifecycle-bridge.ts b/app/flowix-web/features/surface/workspace-surface-lifecycle-bridge.ts
new file mode 100644
index 000000000..e0d9bb4af
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-lifecycle-bridge.ts
@@ -0,0 +1,19 @@
+import { useCallback, useRef } from 'react';
+import type { SurfaceLifecycle } from '@features/workspace/model/surface-contract';
+
+type SurfaceLifecycleProps = {
+  onSurfaceLifecycleReady?: (lifecycle: SurfaceLifecycle | null) => void;
+};
+
+/** Each renderer owns its registration, including after another renderer replaces it. */
+export function useWorkspaceSurfaceLifecycleBridge<T extends object>(
+  props: T & SurfaceLifecycleProps,
+  registerLifecycle?: (lifecycle: SurfaceLifecycle | null, owner?: object) => void,
+): T & SurfaceLifecycleProps {
+  const owner = useRef({});
+  const onSurfaceLifecycleReady = useCallback((lifecycle: SurfaceLifecycle | null) => {
+    registerLifecycle?.(lifecycle, owner.current);
+    props.onSurfaceLifecycleReady?.(lifecycle);
+  }, [props.onSurfaceLifecycleReady, registerLifecycle]);
+  return { ...props, onSurfaceLifecycleReady };
+}
diff --git a/app/flowix-web/features/surface/workspace-surface-renderer-contract.ts b/app/flowix-web/features/surface/workspace-surface-renderer-contract.ts
new file mode 100644
index 000000000..ab6fb2b80
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-renderer-contract.ts
@@ -0,0 +1,56 @@
+import type { ComponentProps, ReactNode } from 'react';
+import type { DocumentContainer } from '@features/document/components/document-container';
+import type { FileDisplayIdentity } from '@/lib/file-display-registry';
+import type { CollectionDisplayDescriptor } from '@/lib/collection-display-registry';
+import type { TableDocumentViewProps } from '@features/multidimensional-table/public/surface-api';
+import type { PluginDocumentViewProps, PluginWorkbenchProps } from '@features/plugin/public/surface-api';
+import type { SurfaceLifecycle, SurfacePresentationUpdate, SurfaceViewContext, WorkspaceWebRuntime } from '@features/workspace/model/surface-contract';
+import type { FileBrowserViewSurface } from './file-browser-view';
+
+export interface WorkspaceWebNavigationPort {
+  getRuntime: () => WorkspaceWebRuntime | null;
+  setRuntime: (runtime: WorkspaceWebRuntime) => void;
+  navigate: (url: string) => void;
+  back: () => void;
+  forward: () => void;
+  reload: () => void;
+  updateMetadata: (metadata: { title: string; icon: string | null }) => void;
+}
+
+export type WorkspaceFileBrowserSurfaceProps = FileBrowserViewSurface & {
+  fileIdentity?: FileDisplayIdentity;
+  collectionDisplay?: CollectionDisplayDescriptor;
+  documentProps: ExternalDocumentProps;
+};
+
+export type ExternalDocumentProps = Omit<ComponentProps<typeof DocumentContainer>, 'isExternalDocument' | 'fileIdentity'> & { isExternalDocument: true };
+
+export type WorkspaceSurfaceRendererData =
+  | { kind: 'file-markdown'; fileIdentity: FileDisplayIdentity; scopePath: string | null; documentProps: ExternalDocumentProps }
+  | { kind: 'file-code'; fileIdentity: FileDisplayIdentity; scopePath: string | null; documentProps: ExternalDocumentProps; instanceKey: string }
+  | { kind: 'file-csv'; fileIdentity: FileDisplayIdentity; scopePath: string | null }
+  | { kind: 'file-image'; fileIdentity: FileDisplayIdentity; scopePath: string | null }
+  | { kind: 'file-video'; fileIdentity: FileDisplayIdentity; scopePath: string | null }
+  | { kind: 'file-table'; fileIdentity: FileDisplayIdentity; props: TableDocumentViewProps }
+  | { kind: 'file-media-library'; fileIdentity: FileDisplayIdentity; notebookPath: string | null; notebookId: string | null; expectedCollectionId?: string | null }
+  | { kind: 'file-html'; fileIdentity: FileDisplayIdentity; scopePath: string | null; documentProps: ExternalDocumentProps }
+  | { kind: 'file-docx'; fileIdentity: FileDisplayIdentity; scopePath: string | null }
+  | { kind: 'file-unavailable'; fileIdentity: FileDisplayIdentity; scopePath: string | null; documentProps?: ExternalDocumentProps }
+  | { kind: 'media'; fileIdentity: FileDisplayIdentity; notebookPath: string | null; notebookId: string | null; resourceKind: 'image' | 'video' }
+  | { kind: 'agent-conversation'; instanceId: string }
+  | { kind: 'web'; url: string; title?: string; runtime?: WorkspaceWebRuntime | null }
+  | { kind: 'file-browser'; props: WorkspaceFileBrowserSurfaceProps }
+  | { kind: 'collection'; notebookId: string; notebookPath: string; folderPath: string; folderName: string }
+  | { kind: 'mindmap'; props: PluginDocumentViewProps }
+  | { kind: 'plugin-artifact'; props: PluginDocumentViewProps }
+  | { kind: 'plugin-workbench'; props: PluginWorkbenchProps };
+
+export interface WorkspaceSurfaceRenderContext extends Pick<SurfaceViewContext,
+  'host' | 'viewId' | 'focused' | 'readOnly' | 'initialFocus'> {
+  reportPresentation?: (update: SurfacePresentationUpdate) => void;
+  registerLifecycle?: (lifecycle: SurfaceLifecycle | null, owner?: object) => void;
+  webNavigation?: WorkspaceWebNavigationPort;
+  onCollectionActiveViewChange?: (viewId: string) => void;
+  /** Browser's file tree/source shell for the file kinds that use it. */
+  wrapInFileBrowser?: (content: ReactNode) => ReactNode;
+}
diff --git a/app/flowix-web/features/surface/workspace-surface-renderer-registry.tsx b/app/flowix-web/features/surface/workspace-surface-renderer-registry.tsx
new file mode 100644
index 000000000..704fd8d8a
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-renderer-registry.tsx
@@ -0,0 +1,173 @@
+'use client';
+
+import { Suspense, useEffect, type ComponentType, type ReactNode } from 'react';
+import {
+  workspaceSurfaceAppearance,
+  workspaceSurfaceCapabilities,
+  workspaceSurfaceRegistry,
+  resolveWorkspaceFileSurfaceKind,
+} from '@features/workspace/public/surface-api';
+import type {
+  SurfaceAppearance,
+  SurfaceState,
+  WorkspaceSurfaceCapability,
+  WorkspaceSurfaceHost,
+  WorkspaceSurfaceKind,
+} from '@features/workspace/public/surface-api';
+import { useWorkspaceSurfaceRendererLazy, WorkspaceSurfaceErrorBoundary, WorkspaceSurfaceStateView } from './workspace-surface-state-view';
+import { registerStartupSurfaceHostView, useWorkspaceSurfacePresentation } from './workspace-surface-runtime';
+
+export type { WorkspaceSurfaceRendererData, WorkspaceSurfaceRenderContext } from './workspace-surface-renderer-contract';
+import type { WorkspaceSurfaceRendererData, WorkspaceSurfaceRenderContext } from './workspace-surface-renderer-contract';
+type EnsureSurfaceData<K extends WorkspaceSurfaceRendererData['kind']> = K;
+// Adding a public surface kind requires a typed renderer data variant.
+type WorkspaceSurfaceRendererKind = EnsureSurfaceData<WorkspaceSurfaceKind>;
+type RendererId = typeof workspaceSurfaceRegistry[WorkspaceSurfaceKind]['rendererId'];
+type SurfaceKindsForRenderer<R extends RendererId> = {
+  [K in WorkspaceSurfaceKind]: typeof workspaceSurfaceRegistry[K]['rendererId'] extends R ? K : never
+}[WorkspaceSurfaceKind];
+type RendererProps<R extends RendererId> = {
+  surface: Extract<WorkspaceSurfaceRendererData, { kind: SurfaceKindsForRenderer<R> }>;
+  context: WorkspaceSurfaceRenderContext;
+};
+type RendererLoader<R extends RendererId> = () => Promise<{ default: ComponentType<RendererProps<R>> }>;
+
+interface RendererImplementation {
+  render: (surface: WorkspaceSurfaceRendererData, context: WorkspaceSurfaceRenderContext) => ReactNode;
+}
+
+export interface WorkspaceSurfaceRendererDefinition extends RendererImplementation {
+  kind: WorkspaceSurfaceRendererKind;
+  hosts: readonly WorkspaceSurfaceHost[];
+  appearance: Readonly<SurfaceAppearance>;
+  capabilities: readonly WorkspaceSurfaceCapability[];
+}
+
+function RetryableRenderer<R extends RendererId>({
+  loader,
+  surface,
+  context,
+}: {
+  loader: RendererLoader<R>;
+  surface: RendererProps<R>['surface'];
+  context: WorkspaceSurfaceRenderContext;
+}) {
+  const Renderer = useWorkspaceSurfaceRendererLazy(loader);
+  return <Renderer surface={surface} context={context} />;
+}
+
+function implementRenderer<R extends RendererId>(
+  rendererId: R,
+  loader: RendererLoader<R>,
+): RendererImplementation {
+  return {
+    render(surface, context) {
+      if (workspaceSurfaceRegistry[surface.kind].rendererId !== rendererId) {
+        throw new Error(`Surface '${surface.kind}' does not use renderer '${rendererId}'`);
+      }
+      // The public renderer ID check above correlates the data variant with the
+      // component. Keep the generic assertion at this single implementation boundary.
+      return <RetryableRenderer<R>
+        loader={loader}
+        surface={surface as RendererProps<R>['surface']}
+        context={context}
+      />;
+    },
+  };
+}
+
+/** Implementations have no host registration or independent support declarations. */
+const rendererImplementations = {
+  'file-markdown': implementRenderer('file-markdown', () => import('./workspace-surface-renderers').then((module) => ({ default: module.MarkdownRenderer }))),
+  'file-code': implementRenderer('file-code', () => import('./workspace-surface-renderers').then((module) => ({ default: module.CodeRenderer }))),
+  'file-csv': implementRenderer('file-csv', () => import('./workspace-surface-renderers').then((module) => ({ default: module.CsvRenderer }))),
+  'file-image': implementRenderer('file-image', () => import('./workspace-surface-renderers').then((module) => ({ default: module.ImageRenderer }))),
+  'file-video': implementRenderer('file-video', () => import('./workspace-surface-renderers').then((module) => ({ default: module.VideoRenderer }))),
+  'file-table': implementRenderer('file-table', () => import('./workspace-surface-renderers').then((module) => ({ default: module.TableRenderer }))),
+  'file-media-library': implementRenderer('file-media-library', () => import('./workspace-surface-renderers').then((module) => ({ default: module.MediaLibraryRenderer }))),
+  'file-html': implementRenderer('file-html', () => import('./workspace-surface-renderers').then((module) => ({ default: module.HtmlRenderer }))),
+  'file-docx': implementRenderer('file-docx', () => import('./workspace-surface-renderers').then((module) => ({ default: module.DocxRenderer }))),
+  'file-unavailable': implementRenderer('file-unavailable', () => import('./workspace-surface-renderers').then((module) => ({ default: module.UnavailableRenderer }))),
+  media: implementRenderer('media', () => import('./workspace-surface-renderers').then((module) => ({ default: module.MediaResourceRenderer }))),
+  'agent-conversation': implementRenderer('agent-conversation', () => import('./workspace-surface-renderers').then((module) => ({ default: module.AgentConversationRenderer }))),
+  'plugin-document': implementRenderer('plugin-document', () => import('./workspace-surface-renderers').then((module) => ({ default: module.PluginDocumentRenderer }))),
+  'plugin-workbench': implementRenderer('plugin-workbench', () => import('./workspace-surface-renderers').then((module) => ({ default: module.PluginWorkbenchRenderer }))),
+  collection: implementRenderer('collection', () => import('./workspace-surface-renderers').then((module) => ({ default: module.CollectionRenderer }))),
+  web: implementRenderer('web', () => import('./workspace-web-surface-renderer').then((module) => ({ default: module.WebRenderer }))),
+  'file-browser': implementRenderer('file-browser', () => import('./workspace-file-browser-surface-renderer').then((module) => ({ default: module.FileBrowserRenderer }))),
+} satisfies Record<RendererId, RendererImplementation>;
+
+function buildWorkspaceSurfaceRendererRegistry() {
+  // Every entry is populated from the exhaustive public registry below.
+  const definitions = {} as Record<WorkspaceSurfaceKind, WorkspaceSurfaceRendererDefinition>;
+  for (const kind of Object.keys(workspaceSurfaceRegistry) as WorkspaceSurfaceKind[]) {
+    const registration = workspaceSurfaceRegistry[kind];
+    definitions[kind] = Object.freeze({
+      kind,
+      hosts: registration.hosts,
+      appearance: registration.appearance,
+      capabilities: registration.capabilities,
+      render(surface: WorkspaceSurfaceRendererData, context: WorkspaceSurfaceRenderContext) {
+        if (surface.kind !== kind) throw new Error(`Expected surface '${kind}', received '${surface.kind}'`);
+        return rendererImplementations[registration.rendererId].render(surface, context);
+      },
+    });
+  }
+  return Object.freeze(definitions);
+}
+
+/** Derived from the public registration: hosts never maintain renderer maps. */
+export const workspaceSurfaceRendererRegistry = buildWorkspaceSurfaceRendererRegistry();
+
+export function workspaceSurfaceRendererSupportsHost(kind: WorkspaceSurfaceRendererData['kind'], host: WorkspaceSurfaceHost): boolean {
+  return workspaceSurfaceRendererRegistry[kind].hosts.includes(host);
+}
+
+/** File-browser is a shell; its current content determines chrome and capabilities. */
+export function getWorkspaceSurfaceRendererDefinition(surface: WorkspaceSurfaceRendererData): WorkspaceSurfaceRendererDefinition {
+  const definition = workspaceSurfaceRendererRegistry[surface.kind];
+  if (surface.kind !== 'file-browser' || !surface.props.activeFilePath) return definition;
+  const props = surface.props;
+  const fileKind = props.collectionType === 'table' ? 'table'
+    : props.collectionType === 'media_library' ? 'media-library'
+    : resolveWorkspaceFileSurfaceKind(props.activeFilePath!);
+  const contentKind = `file-${fileKind}` as const;
+  return { ...definition, appearance: workspaceSurfaceAppearance(contentKind), capabilities: workspaceSurfaceCapabilities(contentKind) };
+}
+
+export function WorkspaceSurfaceRendererView({
+  surface,
+  context,
+  state = { status: 'ready' },
+}: {
+  surface: WorkspaceSurfaceRendererData;
+  context: WorkspaceSurfaceRenderContext;
+  state?: SurfaceState;
+}) {
+  const definition = getWorkspaceSurfaceRendererDefinition(surface);
+  const runtime = useWorkspaceSurfacePresentation(context.viewId);
+  useEffect(() => registerStartupSurfaceHostView(context.host, context.viewId), [context.host, context.viewId]);
+  const appearance = runtime.appearance ?? definition.appearance;
+  const resolvedState = runtime.state ?? state;
+  const contentIdentity = surface.kind === 'file-browser'
+    ? surface.props.fileIdentity?.displayId ?? surface.props.activeFilePath ?? 'folder'
+    : 'fileIdentity' in surface ? surface.fileIdentity.displayId : '';
+  if (!definition.hosts.includes(context.host)) {
+    throw new Error(`Workspace host '${context.host}' does not support '${surface.kind}'`);
+  }
+  const backgroundClass = appearance.contentBackground === 'document'
+    ? 'bg-[var(--document-bg)]'
+    : 'bg-[var(--agent-bg,var(--document-bg))]';
+  return <div data-workspace-surface={surface.kind} data-surface-capabilities={(runtime.capabilities ?? definition.capabilities).join(' ')} className={`flex h-full min-h-0 w-full flex-col ${backgroundClass}`}>
+    <WorkspaceSurfaceErrorBoundary key={`${context.viewId}:${surface.kind}:${contentIdentity}`} appearance={appearance}>
+      <WorkspaceSurfaceStateView state={resolvedState} appearance={appearance} keepContentMounted>
+        <Suspense fallback={<WorkspaceSurfaceStateView
+          appearance={appearance}
+          state={{ status: 'loading', phase: 'renderer', message: { key: 'memo.navigation.loading' }, retainContent: false }}
+        />}>
+          <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden">{definition.render(surface, context)}</div>
+        </Suspense>
+      </WorkspaceSurfaceStateView>
+    </WorkspaceSurfaceErrorBoundary>
+  </div>;
+}
diff --git a/app/flowix-web/features/surface/workspace-surface-renderers.tsx b/app/flowix-web/features/surface/workspace-surface-renderers.tsx
new file mode 100644
index 000000000..64667b67d
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-renderers.tsx
@@ -0,0 +1,286 @@
+'use client';
+
+import { lazy, useCallback, useEffect } from 'react';
+
+import { useExternalFileContentDetection } from '@features/editor/use-external-file-content-detection';
+import { externalFileViewKind } from '@features/editor/public/code-file';
+import { workspaceSurfaceAppearance, workspaceSurfaceCapabilities } from '@features/workspace/public/surface-api';
+
+import { LazyAgentConversationDetail } from '@features/agent/components/lazy-agent-conversation-detail';
+import { LazyPluginDocumentView, LazyPluginWorkbench } from '@features/plugin/public/surface-api';
+
+import type { WorkspaceSurfaceRendererData, WorkspaceSurfaceRenderContext } from './workspace-surface-renderer-registry';
+import { WorkspaceSurfaceStateView } from './workspace-surface-state-view';
+import { useWorkspaceSurfaceLifecycleBridge } from './workspace-surface-lifecycle-bridge';
+import type { DocumentContentStatus } from '@features/document/components/session/types';
+import { openFolderCollection } from '@features/workspace/public/main-window-api';
+import { notes } from '@platform/tauri/client';
+import { toast } from '@/lib/toast';
+
+const NO_SURFACE_ACTIONS: readonly [] = [];
+
+function publishDocumentContentState(
+  reportPresentation: WorkspaceSurfaceRenderContext['reportPresentation'],
+  contentState: DocumentContentStatus,
+) {
+  if (!reportPresentation) return;
+  switch (contentState.status) {
+    case 'loading':
+      reportPresentation({ state: {
+        status: 'loading', phase: 'content', message: { key: 'document.file.loading' },
+        retainContent: contentState.retainContent,
+      } });
+      break;
+    case 'error':
+      reportPresentation({ state: {
+        status: 'error', message: { key: 'error.unexpected', fallbackText: contentState.message },
+        actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: contentState.retry }],
+      } });
+      break;
+    case 'missing-note':
+      reportPresentation({ state: {
+        status: 'error', message: { key: 'document.load.missingNoteTitle' }, detailText: contentState.path,
+        actions: [
+          { id: 'retry', label: { key: 'error.retry' }, enabled: true, run: contentState.retry },
+          { id: 'delete', label: { key: 'document.action.delete' }, enabled: true, run: async () => {
+            try {
+              const outcome = await notes.pruneMissing(contentState.path);
+              if (outcome === 'present') {
+                await contentState.retry();
+                return;
+              }
+              // The confirmed resource-deleted event owns list, tab and work
+              // target cleanup in every window.
+            } catch (error) {
+              toast.error(error instanceof Error ? error.message : String(error));
+            }
+          } },
+        ],
+      } });
+      break;
+    case 'ready':
+      reportPresentation({ state: { status: 'ready' } });
+      break;
+  }
+}
+
+// Keep the wrapper module lightweight: each content view loads only when selected.
+const DocumentContainer = lazy(() => import('@features/document/components/document-container').then((module) => ({ default: module.DocumentContainer })));
+const UnavailableFileView = lazy(() => import('@features/document/components/document-container').then((module) => ({ default: module.UnavailableFileView })));
+const DocxPreview = lazy(() => import('@features/document/components/docx-preview').then((module) => ({ default: module.DocxPreview })));
+const CsvPreview = lazy(() => import('@features/document/components/csv-preview').then((module) => ({ default: module.CsvPreview })));
+const TableDocumentView = lazy(() => import('@features/multidimensional-table/public/surface-api').then((module) => ({ default: module.TableDocumentView })));
+const MediaLibraryView = lazy(() => import('@features/media-library/media-library-view').then((module) => ({ default: module.MediaLibraryView })));
+const MediaResourceView = lazy(() => import('./media-resource-view').then((module) => ({ default: module.MediaResourceView })));
+const MarkdownDocumentSurface = lazy(() => import('./markdown-document-surface').then((module) => ({ default: module.MarkdownDocumentSurface })));
+const HtmlResourceView = lazy(() => import('./html-resource-view').then((module) => ({ default: module.HtmlResourceView })));
+const CodeSurfaceFileBrowser = lazy(() => import('./work-file-browser-view').then((module) => ({ default: module.CodeSurfaceFileBrowser })));
+
+type SurfaceOfKind<K extends WorkspaceSurfaceRendererData['kind']> = Extract<WorkspaceSurfaceRendererData, { kind: K }>;
+type RendererProps<K extends WorkspaceSurfaceRendererData['kind']> = {
+  surface: SurfaceOfKind<K>;
+  context: WorkspaceSurfaceRenderContext;
+};
+
+export function MarkdownRenderer({ surface, context }: RendererProps<'file-markdown'>) {
+  const onContentStateChange = useCallback((state: DocumentContentStatus) => {
+    publishDocumentContentState(context.reportPresentation, state);
+  }, [context.reportPresentation]);
+  return <MarkdownDocumentSurface
+    fileIdentity={surface.fileIdentity}
+    documentProps={{ ...surface.documentProps, workspaceHost: context.host,
+      initialFocus: context.initialFocus ?? surface.documentProps.initialFocus, onContentStateChange }}
+    navigationViewId={context.host === 'browser-column' ? context.viewId : undefined}
+    reportPresentation={context.reportPresentation}
+    registerLifecycle={context.registerLifecycle}
+  />;
+}
+
+export function CodeRenderer({ surface, context }: RendererProps<'file-code'>) {
+  const onContentStateChange = useCallback((state: DocumentContentStatus) => {
+    publishDocumentContentState(context.reportPresentation, state);
+  }, [context.reportPresentation]);
+  const documentProps = useWorkspaceSurfaceLifecycleBridge({
+    ...surface.documentProps,
+    workspaceHost: context.host,
+    initialFocus: context.initialFocus ?? surface.documentProps.initialFocus,
+    onContentStateChange,
+  }, context.registerLifecycle);
+  if (context.host === 'main-third') {
+    const workSurface = {
+      kind: 'code' as const,
+      instanceKey: surface.instanceKey,
+      fileIdentity: surface.fileIdentity,
+      props: documentProps,
+    };
+    return <CodeSurfaceFileBrowser surface={workSurface} />;
+  }
+  const content = <DocumentContainer
+    {...documentProps}
+    fileIdentity={surface.fileIdentity}
+    navigationViewId={context.viewId}
+    externalScopePath={surface.scopePath}
+  />;
+  return context.wrapInFileBrowser?.(content) ?? content;
+}
+
+export function CsvRenderer({ surface, context }: RendererProps<'file-csv'>) {
+  const props = useWorkspaceSurfaceLifecycleBridge({
+    filePath: surface.fileIdentity.path, scopePath: surface.scopePath,
+  }, context.registerLifecycle);
+  return <CsvPreview {...props} reportPresentation={context.reportPresentation} />;
+}
+
+export function ImageRenderer({ surface, context }: RendererProps<'file-image'>) {
+  return <MediaResourceView filePath={surface.fileIdentity.path} notebookPath={surface.scopePath} resourceKind="image"
+    reportPresentation={context.reportPresentation} />;
+}
+
+export function VideoRenderer({ surface, context }: RendererProps<'file-video'>) {
+  return <MediaResourceView filePath={surface.fileIdentity.path} notebookPath={surface.scopePath} resourceKind="video"
+    reportPresentation={context.reportPresentation} />;
+}
+
+export function TableRenderer({ surface, context }: RendererProps<'file-table'>) {
+  const props = useWorkspaceSurfaceLifecycleBridge(surface.props, context.registerLifecycle);
+  return <TableDocumentView {...props} fileIdentity={surface.fileIdentity} reportPresentation={context.reportPresentation} />;
+}
+
+export function MediaLibraryRenderer({ surface, context }: RendererProps<'file-media-library'>) {
+  const lifecycleProps = useWorkspaceSurfaceLifecycleBridge({}, context.registerLifecycle);
+  return <MediaLibraryView
+    {...lifecycleProps}
+    filePath={surface.fileIdentity.path}
+    fileIdentity={surface.fileIdentity}
+    expectedCollectionId={surface.expectedCollectionId}
+    notebookPath={surface.notebookPath}
+    notebookId={surface.notebookId}
+    workspaceHost={context.host}
+    reportPresentation={context.reportPresentation}
+  />;
+}
+
+export function HtmlRenderer({ surface, context }: RendererProps<'file-html'>) {
+  const documentProps = useWorkspaceSurfaceLifecycleBridge({
+    ...surface.documentProps,
+    fileIdentity: surface.fileIdentity,
+    workspaceHost: context.host,
+    initialFocus: context.initialFocus ?? surface.documentProps.initialFocus,
+  }, context.registerLifecycle);
+  return <HtmlResourceView
+    filePath={surface.fileIdentity.path}
+    scopePath={surface.scopePath}
+    documentProps={documentProps}
+    reportPresentation={context.reportPresentation}
+  />;
+}
+
+export function DocxRenderer({ surface, context }: RendererProps<'file-docx'>) {
+  const preview = <DocxPreview filePath={surface.fileIdentity.path} scopePath={surface.scopePath} reportPresentation={context.reportPresentation} />;
+  return context.host === 'browser-column' ? context.wrapInFileBrowser?.(preview) ?? preview : preview;
+}
+
+export function UnavailableRenderer({ surface, context }: RendererProps<'file-unavailable'>) {
+  const onContentStateChange = useCallback((state: DocumentContentStatus) => {
+    publishDocumentContentState(context.reportPresentation, state);
+  }, [context.reportPresentation]);
+  const filePath = surface.fileIdentity.path;
+  const documentProps = useWorkspaceSurfaceLifecycleBridge({
+    ...surface.documentProps,
+    workspaceHost: context.host,
+    initialFocus: context.initialFocus ?? surface.documentProps?.initialFocus,
+    onContentStateChange,
+  }, context.registerLifecycle);
+  const baseFileKind = externalFileViewKind(filePath);
+  const { isTextContent, loading: contentDetectionLoading } = useExternalFileContentDetection(filePath, surface.scopePath, baseFileKind === 'unavailable');
+  const resolvedFileKind = externalFileViewKind(filePath, null, isTextContent);
+  const hasDocumentProps = Boolean(surface.documentProps);
+  useEffect(() => {
+    if (baseFileKind === 'docx' || baseFileKind === 'csv') return;
+    if (contentDetectionLoading) {
+      context.reportPresentation?.({ state: {
+        status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: false,
+      } });
+    } else if (resolvedFileKind === 'code' && hasDocumentProps) {
+      context.reportPresentation?.({ appearance: workspaceSurfaceAppearance('file-code'),
+        capabilities: workspaceSurfaceCapabilities('file-code'), actions: NO_SURFACE_ACTIONS });
+    }
+  }, [baseFileKind, context.reportPresentation, hasDocumentProps, contentDetectionLoading, resolvedFileKind]);
+  if (baseFileKind === 'docx') {
+    const preview = <DocxPreview filePath={filePath} scopePath={surface.scopePath} reportPresentation={context.reportPresentation} />;
+    return context.host === 'browser-column' ? context.wrapInFileBrowser?.(preview) ?? preview : preview;
+  }
+  if (baseFileKind === 'csv') return <CsvPreview filePath={filePath} scopePath={surface.scopePath}
+    onSurfaceLifecycleReady={documentProps.onSurfaceLifecycleReady} reportPresentation={context.reportPresentation} />;
+  if (contentDetectionLoading) return context.reportPresentation ? null : <WorkspaceSurfaceStateView
+    appearance={workspaceSurfaceAppearance('file-unavailable')}
+    state={{ status: 'loading', phase: 'content', message: { key: 'document.file.loading' }, retainContent: false }}
+  />;
+  if (resolvedFileKind === 'code' && surface.documentProps) {
+    const content = <DocumentContainer
+      {...documentProps}
+      initialFocus={context.initialFocus ?? surface.documentProps.initialFocus}
+      fileIdentity={surface.fileIdentity}
+      navigationViewId={context.host === 'browser-column' ? context.viewId : undefined}
+      externalScopePath={surface.scopePath}
+    />;
+    return context.host === 'browser-column' ? context.wrapInFileBrowser?.(content) ?? content : content;
+  }
+  return <UnavailableFileView filePath={filePath} openContainingFolder scopePath={surface.scopePath} reportPresentation={context.reportPresentation} />;
+}
+
+export function MediaResourceRenderer({ surface, context }: RendererProps<'media'>) {
+  return <MediaResourceView
+    filePath={surface.fileIdentity.path}
+    notebookPath={surface.notebookPath}
+    resourceKind={surface.resourceKind}
+    reportPresentation={context.reportPresentation}
+  />;
+}
+
+export function AgentConversationRenderer({ surface, context }: RendererProps<'agent-conversation'>) {
+  return <LazyAgentConversationDetail instanceId={surface.instanceId} reportPresentation={context.reportPresentation} />;
+}
+
+export function PluginDocumentRenderer({ surface, context }: RendererProps<'mindmap' | 'plugin-artifact'>) {
+  return <LazyPluginDocumentView {...surface.props} reportPresentation={context.reportPresentation} />;
+}
+
+export function PluginWorkbenchRenderer({ surface, context }: RendererProps<'plugin-workbench'>) {
+  return <LazyPluginWorkbench {...surface.props} reportPresentation={context.reportPresentation} />;
+}
+
+export function CollectionRenderer({ surface, context }: RendererProps<'collection'>) {
+  useEffect(() => {
+    context.reportPresentation?.({ state: { status: 'ready' } });
+  }, [context.reportPresentation]);
+
+  const choose = async (initialType: 'notes' | 'media') => {
+    try {
+      await openFolderCollection(surface.notebookId, surface.folderPath, {
+        initialType,
+        destination: context.host,
+      });
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '无法打开文件夹集合');
+    }
+  };
+
+  return <div className="flex min-h-0 flex-1 items-center justify-center overflow-auto p-6">
+    <section className="w-full max-w-xl">
+      <h1 className="mb-5 text-xl font-semibold text-[var(--foreground)]">如何显示当前文件夹？</h1>
+      <div className="mb-2 grid grid-cols-1 gap-3">
+        <button type="button" onClick={() => { void choose('notes'); }}
+          className="flex flex-col items-start justify-center gap-1 rounded-xl border border-[var(--border)] bg-[var(--card)] px-4 py-3 text-left transition-colors hover:bg-[var(--muted)]">
+          <span className="text-sm font-medium">显示笔记</span>
+          <span className="text-sm text-[var(--muted-foreground)]">支持表格 / 日历 / 看板 / 画廊</span>
+        </button>
+        <button type="button" onClick={() => { void choose('media'); }}
+          className="flex flex-col items-start justify-center gap-1 rounded-xl border border-[var(--border)] bg-[var(--card)] px-4 py-3 text-left transition-colors hover:bg-[var(--muted)]">
+          <span className="text-sm font-medium">显示图/视频</span>
+          <span className="text-sm text-[var(--muted-foreground)]">支持图片墙 / 瀑布流</span>
+        </button>
+      </div>
+    </section>
+  </div>;
+}
diff --git a/app/flowix-web/features/surface/workspace-surface-runtime.ts b/app/flowix-web/features/surface/workspace-surface-runtime.ts
new file mode 100644
index 000000000..a2fd51221
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-runtime.ts
@@ -0,0 +1,169 @@
+import { useSyncExternalStore } from 'react';
+import type { SurfacePresentationUpdate, SurfaceState, WorkspaceSurfaceHost } from '@features/workspace/model/surface-contract';
+
+const snapshots = new Map<string, Readonly<SurfacePresentationUpdate>>();
+const listeners = new Map<string, Set<() => void>>();
+const owners = new Map<string, object>();
+const pendingUpdates = new Map<string, { owner: object; update: Readonly<SurfacePresentationUpdate> }>();
+const hostViews = new Map<WorkspaceSurfaceHost, string>();
+const startupListeners = new Set<() => void>();
+let startupHosts: readonly WorkspaceSurfaceHost[] = [];
+const startupOutcomes = new Map<string, 'ready' | 'failed'>();
+const emptySurfaceIdentityByHost = new Map<WorkspaceSurfaceHost, string>();
+let startupIdentities: Partial<Record<WorkspaceSurfaceHost, string>> = {};
+
+function emit(viewId: string) {
+  listeners.get(viewId)?.forEach((listener) => listener());
+}
+
+function emitStartup() {
+  startupListeners.forEach((listener) => listener());
+}
+
+/** Freeze the visible surface set for this startup attempt before waiting. */
+export function beginWorkspaceSurfaceStartup(
+  hosts: readonly WorkspaceSurfaceHost[],
+  identities: Partial<Record<WorkspaceSurfaceHost, string>> = {},
+): void {
+  startupHosts = hosts;
+  startupIdentities = identities;
+  startupOutcomes.clear();
+  for (const host of hosts) {
+    if (emptySurfaceIdentityByHost.get(host) === identities[host]) {
+      startupOutcomes.set(host, 'ready');
+      continue;
+    }
+    const viewId = hostViews.get(host);
+    const state = viewId ? snapshots.get(viewId)?.state : undefined;
+    if (state) updateStartupSurfaceState(viewId!, state);
+  }
+  emitStartup();
+}
+
+export function registerStartupSurfaceHostView(host: WorkspaceSurfaceHost, viewId: string): () => void {
+  emptySurfaceIdentityByHost.delete(host);
+  hostViews.set(host, viewId);
+  startupOutcomes.delete(host);
+  const state = snapshots.get(viewId)?.state;
+  if (state) updateStartupSurfaceState(viewId, state);
+  emitStartup();
+  return () => {
+    if (hostViews.get(host) !== viewId) return;
+    hostViews.delete(host);
+    startupOutcomes.delete(host);
+    emitStartup();
+  };
+}
+
+export function reportEmptyWorkspaceSurfaceForIdentity(host: WorkspaceSurfaceHost, identity: string): void {
+  emptySurfaceIdentityByHost.set(host, identity);
+  if (!startupHosts.includes(host)) return;
+  if (startupIdentities[host] !== identity) return;
+  startupOutcomes.set(host, 'ready');
+  emitStartup();
+}
+
+export function waitForWorkspaceSurfaceStartup(timeoutMs = 60_000): Promise<'ready' | 'timeout' | 'failed'> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result: 'ready' | 'timeout' | 'failed') => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      startupListeners.delete(check);
+      resolve(result);
+    };
+    const check = () => {
+      if (startupHosts.some((host) => !hostViews.has(host) && !startupOutcomes.has(host))) return;
+      if (startupHosts.some((host) => startupOutcomes.get(host) === 'failed')) finish('failed');
+      else if (startupHosts.every((host) => startupOutcomes.get(host) === 'ready')) finish('ready');
+    };
+    const timeout = setTimeout(() => finish('timeout'), timeoutMs);
+    startupListeners.add(check);
+    check();
+  });
+}
+
+function updateStartupSurfaceState(viewId: string, state: SurfaceState): void {
+  const host = [...hostViews.entries()].find(([, currentViewId]) => currentViewId === viewId)?.[0];
+  if (!host || !startupHosts.includes(host)) return;
+  if (state.status === 'loading') startupOutcomes.delete(host);
+  else if (state.status === 'error' || state.status === 'unavailable') startupOutcomes.set(host, 'failed');
+  else startupOutcomes.set(host, 'ready');
+  emitStartup();
+}
+
+export function registerWorkspaceSurfacePresentationOwner(viewId: string, owner: object): () => void {
+  owners.set(viewId, owner);
+  clearSnapshot(viewId);
+  const pending = pendingUpdates.get(viewId);
+  if (pending?.owner === owner) {
+    pendingUpdates.delete(viewId);
+    snapshots.set(viewId, pending.update);
+    emit(viewId);
+  } else if (pending) {
+    pendingUpdates.delete(viewId);
+  }
+  return () => {
+    if (owners.get(viewId) !== owner) return;
+    owners.delete(viewId);
+    if (pendingUpdates.get(viewId)?.owner === owner) pendingUpdates.delete(viewId);
+    clearSnapshot(viewId);
+  };
+}
+
+function clearSnapshot(viewId: string) {
+  if (!snapshots.delete(viewId)) return;
+  emit(viewId);
+}
+
+export function reportWorkspaceSurfacePresentation(
+  viewId: string,
+  update: SurfacePresentationUpdate,
+  owner?: object,
+): boolean {
+  const currentOwner = owners.get(viewId);
+  if (currentOwner && owner !== currentOwner) return false;
+  if (!currentOwner && owner) {
+    const previousPending = pendingUpdates.get(viewId);
+    const previous = previousPending?.owner === owner ? previousPending.update : {};
+    pendingUpdates.set(viewId, { owner, update: { ...previous, ...update } });
+    return true;
+  }
+  if (!currentOwner && !owner && pendingUpdates.has(viewId)) return false;
+  const previous = snapshots.get(viewId) ?? {};
+  const next = { ...previous, ...update };
+  if (Object.keys(update).every((key) => Object.is(previous[key as keyof SurfacePresentationUpdate], update[key as keyof SurfacePresentationUpdate]))) return true;
+  snapshots.set(viewId, next);
+  if (update.state) updateStartupSurfaceState(viewId, update.state);
+  emit(viewId);
+  return true;
+}
+
+export function clearWorkspaceSurfacePresentation(viewId: string, owner?: object) {
+  const currentOwner = owners.get(viewId);
+  if (currentOwner && owner !== currentOwner) return;
+  clearSnapshot(viewId);
+}
+
+export function getWorkspaceSurfacePresentation(viewId: string): Readonly<SurfacePresentationUpdate> {
+  return snapshots.get(viewId) ?? EMPTY_PRESENTATION;
+}
+
+const EMPTY_PRESENTATION: Readonly<SurfacePresentationUpdate> = Object.freeze({});
+
+export function useWorkspaceSurfacePresentation(viewId: string): Readonly<SurfacePresentationUpdate> {
+  return useSyncExternalStore(
+    (listener) => {
+      const viewListeners = listeners.get(viewId) ?? new Set<() => void>();
+      viewListeners.add(listener);
+      listeners.set(viewId, viewListeners);
+      return () => {
+        viewListeners.delete(listener);
+        if (viewListeners.size === 0) listeners.delete(viewId);
+      };
+    },
+    () => getWorkspaceSurfacePresentation(viewId),
+    () => EMPTY_PRESENTATION,
+  );
+}
diff --git a/app/flowix-web/features/surface/workspace-surface-state-view.test.tsx b/app/flowix-web/features/surface/workspace-surface-state-view.test.tsx
new file mode 100644
index 000000000..ee80e5958
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-state-view.test.tsx
@@ -0,0 +1,126 @@
+import { act, Suspense, useEffect, type ComponentType } from 'react';
+import type { SurfaceState } from '@features/workspace/model/surface-contract';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useWorkspaceSurfaceRendererLazy, WorkspaceSurfaceErrorBoundary, WorkspaceSurfaceStateView } from './workspace-surface-state-view';
+
+vi.mock('@shared/ui/centered-loading-spinner', () => ({
+  CenteredLoadingSpinner: () => <div data-testid="surface-spinner" />,
+}));
+vi.mock('@/lib/i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }));
+
+const appearance = {
+  headerStyle: 'document' as const,
+  contentBackground: 'document' as const,
+  stateBackground: 'document' as const,
+  emptyDecoration: 'none' as const,
+};
+let host: HTMLDivElement;
+let root: Root;
+
+afterEach(async () => {
+  if (root) await act(async () => root.unmount());
+});
+
+describe('WorkspaceSurfaceStateView', () => {
+  it('preserves renderer identity and its effects through loading, failure and retry', async () => {
+    host = document.createElement('div');
+    root = createRoot(host);
+    const mount = vi.fn();
+    const dispose = vi.fn();
+    function Content() {
+      useEffect(() => { mount(); return dispose; }, []);
+      return <input defaultValue="draft" />;
+    }
+    const render = async (state: SurfaceState) => {
+      await act(async () => root.render(<WorkspaceSurfaceStateView appearance={appearance} state={state} keepContentMounted>
+        <Content />
+      </WorkspaceSurfaceStateView>));
+    };
+    await render({ status: 'ready' });
+    const input = host.querySelector('input');
+    await render({ status: 'loading', phase: 'content', retainContent: false });
+    expect(host.querySelector('input')).toBe(input);
+    expect(input!.closest('[inert]')).not.toBeNull();
+    await render({ status: 'error', message: { key: 'error.unexpected' } });
+    await render({ status: 'loading', phase: 'content', retainContent: true });
+    await render({ status: 'ready' });
+    expect(host.querySelector('input')).toBe(input);
+    expect(input!.closest('[inert]')).toBeNull();
+    expect(mount).toHaveBeenCalledOnce();
+    expect(dispose).not.toHaveBeenCalled();
+  });
+  it('keeps async content mounted beneath a retained loading state', async () => {
+    host = document.createElement('div');
+    root = createRoot(host);
+    await act(async () => root.render(<WorkspaceSurfaceStateView
+      appearance={appearance}
+      state={{ status: 'loading', phase: 'content', message: { key: 'loading' }, retainContent: true }}>
+      <div data-testid="async-content">mounted</div>
+    </WorkspaceSurfaceStateView>));
+
+    expect(host.querySelector('[data-testid="async-content"]')?.textContent).toBe('mounted');
+    expect(host.querySelector('[data-testid="surface-spinner"]')).not.toBeNull();
+  });
+
+  it('shows domain error detail and its retry action in the shared state view', async () => {
+    host = document.createElement('div');
+    root = createRoot(host);
+    const retry = vi.fn();
+    await act(async () => root.render(<WorkspaceSurfaceStateView
+      appearance={appearance}
+      state={{ status: 'error', message: { key: 'error.unexpected', fallbackText: 'artifact missing' },
+        actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: retry }] }} />));
+
+    expect(host.textContent).toContain('artifact missing');
+    await act(async () => host.querySelector('button')?.click());
+    expect(retry).toHaveBeenCalledOnce();
+  });
+
+  it('settles initial loading when Suspense wraps the lazy-renderer hook', async () => {
+    host = document.createElement('div');
+    root = createRoot(host);
+    let resolve!: (value: { default: ComponentType }) => void;
+    const load = vi.fn(() => new Promise<{ default: ComponentType }>((done) => { resolve = done; }));
+    function LazyRenderer() {
+      const Renderer = useWorkspaceSurfaceRendererLazy(load);
+      return <Renderer />;
+    }
+    await act(async () => root.render(<WorkspaceSurfaceErrorBoundary appearance={appearance}>
+      <Suspense fallback={<div>loading</div>}><LazyRenderer /></Suspense>
+    </WorkspaceSurfaceErrorBoundary>));
+    expect(host.textContent).toBe('loading');
+    await act(async () => resolve({ default: () => <div>content ready</div> }));
+    expect(host.textContent).toBe('content ready');
+    expect(load).toHaveBeenCalledOnce();
+  });
+
+  it('retries a rejected lazy renderer with a fresh React lazy wrapper', async () => {
+    host = document.createElement('div');
+    root = createRoot(host);
+    const load = vi.fn(async (): Promise<{ default: ComponentType }> => {
+      if (load.mock.calls.length === 1) throw new Error('temporary chunk failure');
+      return { default: () => <div>renderer recovered</div> };
+    });
+    function LazyRenderer() {
+      const Renderer = useWorkspaceSurfaceRendererLazy(load);
+      return <Suspense fallback={<div>loading</div>}><Renderer /></Suspense>;
+    }
+    const logError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await act(async () => root.render(<WorkspaceSurfaceErrorBoundary appearance={appearance}>
+      <LazyRenderer />
+    </WorkspaceSurfaceErrorBoundary>));
+    expect(host.textContent).toContain('error.unexpected');
+
+    await act(async () => {
+      host.querySelector('button')?.click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(host.textContent).toContain('renderer recovered');
+    expect(load).toHaveBeenCalledTimes(2);
+    logError.mockRestore();
+  });
+});
diff --git a/app/flowix-web/features/surface/workspace-surface-state-view.tsx b/app/flowix-web/features/surface/workspace-surface-state-view.tsx
new file mode 100644
index 000000000..34783070e
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-surface-state-view.tsx
@@ -0,0 +1,182 @@
+'use client';
+
+import { Component, createContext, Fragment, lazy, useContext, type ComponentType, type ErrorInfo, type LazyExoticComponent, type ReactNode } from 'react';
+import { CenteredLoadingSpinner } from '@shared/ui/centered-loading-spinner';
+import { WorkspaceEmptyState } from '@shared/ui/workspace-empty-state';
+import { useI18n } from '@/lib/i18n';
+import type { I18nKey } from '@/lib/i18n/locales';
+import type { SurfaceAppearance, SurfaceMessage, SurfaceState } from '@features/workspace/public/surface-api';
+
+const WorkspaceSurfaceRendererRetryContext = createContext<object>({});
+const rendererCache = new WeakMap<object, WeakMap<object, unknown>>();
+
+/** Recreate a lazy component when the shared renderer boundary retries. */
+export function useWorkspaceSurfaceRendererLazy<P extends object>(
+  load: () => Promise<{ default: ComponentType<P> }>,
+): LazyExoticComponent<ComponentType<P>> {
+  const retryScope = useContext(WorkspaceSurfaceRendererRetryContext);
+  // Initial suspension discards hook state, including useMemo. Cache outside
+  // the suspending component so retries reuse the same resolved lazy wrapper.
+  let scopes = rendererCache.get(load);
+  if (!scopes) {
+    scopes = new WeakMap();
+    rendererCache.set(load, scopes);
+  }
+  let renderer = scopes.get(retryScope) as LazyExoticComponent<ComponentType<P>> | undefined;
+  if (!renderer) {
+    renderer = lazy(load);
+    scopes.set(retryScope, renderer);
+  }
+  return renderer;
+}
+
+function messageText(message: SurfaceMessage, t: (key: I18nKey, params?: Record<string, string | number>) => string): string {
+  const translated = t(message.key as I18nKey, message.params);
+  return message.fallbackText ? `${translated}: ${message.fallbackText}` : translated;
+}
+
+function backgroundClass(appearance: SurfaceAppearance): string {
+  return appearance.stateBackground === 'document'
+    ? 'bg-[var(--document-bg)]'
+    : 'bg-[var(--agent-bg,var(--document-bg))]';
+}
+
+export function WorkspaceSurfaceStateView({
+  state,
+  appearance,
+  children,
+  messageOverride,
+  keepContentMounted = false,
+}: {
+  state: SurfaceState;
+  appearance: Readonly<SurfaceAppearance>;
+  children?: ReactNode;
+  /** Adapter for callers that still hold an already-translated legacy message. */
+  messageOverride?: string;
+  /** Renderer-owned async state must not unmount the renderer publishing it. */
+  keepContentMounted?: boolean;
+}) {
+  const { t } = useI18n();
+  const message = 'message' in state && state.message
+    ? messageOverride ?? messageText(state.message, t)
+    : null;
+  const detailText = state.status === 'error' ? state.detailText : undefined;
+
+  if (keepContentMounted) {
+    const contentVisible = state.status === 'ready' || state.status === 'loading' && state.retainContent;
+    return <div className="relative flex h-full min-h-0 w-full flex-col">
+      {state.status === 'ready' && <WorkspaceSurfaceStateView key="notices" state={state} appearance={appearance} />}
+      {/* Keep a bounded flex viewport through this slot; renderers own scrolling. */}
+      <div key="content" className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden" style={{ visibility: contentVisible ? undefined : 'hidden' }}
+        aria-hidden={contentVisible ? undefined : true} inert={!contentVisible}>
+        {children}
+      </div>
+      {state.status !== 'ready' && <div key="state" className={`absolute inset-0 z-10 ${state.status === 'loading' && state.retainContent ? 'opacity-90' : ''}`}>
+        <WorkspaceSurfaceStateView state={state} appearance={appearance} messageOverride={messageOverride} />
+      </div>}
+    </div>;
+  }
+
+  if (state.status === 'ready') {
+    return <>
+      {state.notices?.map((notice) => (
+        <div key={notice.id} role={notice.severity === 'error' ? 'alert' : 'status'}
+          className={`flex items-center justify-between gap-3 border-b px-3 py-2 text-xs ${backgroundClass(appearance)}`}>
+          <span>{messageText(notice.message, t)}</span>
+          {notice.actions?.length ? <div className="flex shrink-0 gap-2">
+            {notice.actions.map((action) => <button key={action.id} type="button" disabled={!action.enabled}
+              onClick={() => { void action.run(); }}
+              className="rounded-lg border border-[var(--border)] px-2 py-1 transition-colors hover:bg-[var(--muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] disabled:opacity-50">
+              {messageText(action.label, t)}
+            </button>)}
+          </div> : null}
+        </div>
+      ))}
+      {children}
+    </>;
+  }
+
+  if (state.status === 'loading') {
+    if (state.retainContent && children) {
+      return <div className={`relative h-full min-h-0 w-full ${backgroundClass(appearance)}`}>
+        <div className="h-full min-h-0 w-full">{children}</div>
+        <div className={`absolute inset-0 z-10 flex min-h-0 flex-col ${backgroundClass(appearance)} opacity-90`}>
+          <CenteredLoadingSpinner className="min-h-0 flex-1" />
+        </div>
+      </div>;
+    }
+    return <div className={`flex h-full min-h-0 w-full flex-col ${backgroundClass(appearance)}`}>
+      <CenteredLoadingSpinner className="min-h-0 flex-1" />
+    </div>;
+  }
+
+  if (state.status === 'empty' && appearance.emptyDecoration === 'document-artwork') {
+    return <WorkspaceEmptyState
+      tone={appearance.stateBackground === 'agent' ? 'agent' : 'document'}
+      message={message}
+    />;
+  }
+
+  return <div className={`flex h-full min-h-0 w-full flex-col items-center justify-center gap-3 px-6 text-center ${backgroundClass(appearance)}`}
+    role={state.status === 'error' || state.status === 'unavailable' ? 'alert' : 'status'}>
+    <p className={detailText ? 'text-sm font-medium text-[var(--foreground)]' : 'text-sm text-[var(--muted-foreground)]'}>{message}</p>
+    {detailText ? <p className="max-w-full break-all text-xs text-[var(--muted-foreground)]">{detailText}</p> : null}
+    {'actions' in state && state.actions?.length ? <div className="flex flex-wrap justify-center gap-2">
+      {state.actions.map((action) => <button key={action.id} type="button" disabled={!action.enabled}
+        onClick={() => { void action.run(); }}
+        className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] disabled:opacity-50">
+        {messageText(action.label, t)}
+      </button>)}
+    </div> : null}
+  </div>;
+}
+
+interface WorkspaceSurfaceErrorBoundaryProps {
+  appearance: Readonly<SurfaceAppearance>;
+  children: ReactNode;
+}
+
+interface WorkspaceSurfaceErrorBoundaryState {
+  error: Error | null;
+  retryKey: number;
+}
+
+/** Gives every registry renderer the same error state and retry behavior. */
+export class WorkspaceSurfaceErrorBoundary extends Component<
+  WorkspaceSurfaceErrorBoundaryProps,
+  WorkspaceSurfaceErrorBoundaryState
+> {
+  constructor(props: WorkspaceSurfaceErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null, retryKey: 0 };
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<WorkspaceSurfaceErrorBoundaryState> {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error('[WorkspaceSurface] Renderer failed:', error, info);
+  }
+
+  private retry = () => {
+    this.setState(({ retryKey }) => ({ error: null, retryKey: retryKey + 1 }));
+  };
+
+  render() {
+    if (this.state.error) {
+      return <WorkspaceSurfaceStateView
+        appearance={this.props.appearance}
+        state={{
+          status: 'error',
+          message: { key: 'error.unexpected' },
+          actions: [{ id: 'retry', label: { key: 'error.retry' }, enabled: true, run: this.retry }],
+        }}
+      />;
+    }
+
+    return <WorkspaceSurfaceRendererRetryContext.Provider value={this.state}>
+      <Fragment key={this.state.retryKey}>{this.props.children}</Fragment>
+    </WorkspaceSurfaceRendererRetryContext.Provider>;
+  }
+}
diff --git a/app/flowix-web/features/surface/workspace-web-surface-renderer.test.tsx b/app/flowix-web/features/surface/workspace-web-surface-renderer.test.tsx
new file mode 100644
index 000000000..43d145c41
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-web-surface-renderer.test.tsx
@@ -0,0 +1,77 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { WebRenderer } from './workspace-web-surface-renderer';
+import { createWorkspaceWebRuntime } from '@features/workspace/model/web-navigation';
+import type { WorkspaceWebNavigationPort } from './workspace-surface-renderer-contract';
+
+vi.mock('@platform/tauri/opener', () => ({ openUrl: vi.fn().mockResolvedValue(undefined) }));
+vi.mock('@shared/ui/iframe-scrollbar', () => ({ styleAccessibleIframeScrollbar: vi.fn() }));
+
+let root: Root;
+let host: HTMLDivElement;
+const url = 'https://example.com/';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  host = document.createElement('div');
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+  vi.useRealTimers();
+});
+
+async function navigate(address: string) {
+  const input = host.querySelector('input')!;
+  await act(async () => {
+    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(input, address);
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+  });
+  await act(async () => { host.querySelector('form')!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })); });
+}
+
+async function click(label: string) {
+  await act(async () => { host.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`)!.click(); });
+}
+
+describe('shared web renderer', () => {
+  it('provides navigation, history and reload in Work without Browser state', async () => {
+    await act(async () => root.render(<WebRenderer surface={{ kind: 'web', url }} context={{ host: 'main-third', viewId: 'work-web', focused: true, readOnly: false }} />));
+    await navigate('https://example.org/next');
+    expect(host.querySelector('iframe')!.src).toBe('https://example.org/next');
+    await click('后退');
+    expect(host.querySelector('iframe')!.src).toBe(url);
+    await click('前进');
+    expect(host.querySelector('iframe')!.src).toBe('https://example.org/next');
+    const frame = host.querySelector('iframe');
+    await click('重新加载');
+    expect(host.querySelector('iframe')).not.toBe(frame);
+  });
+
+  it('delegates Browser navigation to the injected tab port', async () => {
+    const runtime = { ...createWorkspaceWebRuntime(url), history: ['https://before.com/', url, 'https://after.com/'], historyIndex: 1 };
+    const port: WorkspaceWebNavigationPort = {
+      getRuntime: vi.fn(() => runtime), setRuntime: vi.fn(), navigate: vi.fn(), back: vi.fn(),
+      forward: vi.fn(), reload: vi.fn(), updateMetadata: vi.fn(),
+    };
+    await act(async () => root.render(<WebRenderer surface={{ kind: 'web', url, runtime }} context={{ host: 'browser-column', viewId: 'tab-web', focused: true, readOnly: false, webNavigation: port }} />));
+    await click('后退'); await click('前进'); await click('重新加载');
+    await navigate('https://example.org/');
+    expect(port.back).toHaveBeenCalledOnce();
+    expect(port.forward).toHaveBeenCalledOnce();
+    expect(port.reload).toHaveBeenCalledOnce();
+    expect(port.navigate).toHaveBeenCalledWith('https://example.org/');
+    expect(port.updateMetadata).toHaveBeenCalledWith(expect.objectContaining({ title: 'example.org' }));
+  });
+
+  it('clears the timeout after a cross-origin iframe load', async () => {
+    await act(async () => root.render(<WebRenderer surface={{ kind: 'web', url }} context={{ host: 'main-third', viewId: 'work-web', focused: true, readOnly: false }} />));
+    const frame = host.querySelector('iframe')!;
+    Object.defineProperty(frame, 'contentWindow', { get: () => { throw new DOMException('Cross origin', 'SecurityError'); } });
+    await act(async () => { frame.dispatchEvent(new Event('load')); vi.advanceTimersByTime(6000); });
+    expect(host.textContent).not.toContain('网页可能禁止嵌入或加载超时');
+  });
+});
diff --git a/app/flowix-web/features/surface/workspace-web-surface-renderer.tsx b/app/flowix-web/features/surface/workspace-web-surface-renderer.tsx
new file mode 100644
index 000000000..e1ad79a7a
--- /dev/null
+++ b/app/flowix-web/features/surface/workspace-web-surface-renderer.tsx
@@ -0,0 +1,290 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState, type FormEvent } from 'react';
+import { ArrowUpRight, ChevronLeft, ChevronRight, Globe, RotateCw, X } from 'lucide-react';
+import { canonicalUrl } from '@features/workspace/model/surface-identity';
+import type { WorkspaceWebRuntime } from '@features/workspace/model/surface-contract';
+import { createWorkspaceWebRuntime, navigateWorkspaceWebRuntime, moveWorkspaceWebHistory, reloadWorkspaceWebRuntime } from '@features/workspace/model/web-navigation';
+import { openUrl } from '@platform/tauri/opener';
+import { styleAccessibleIframeScrollbar } from '@shared/ui/iframe-scrollbar';
+import type { WorkspaceSurfaceRendererData, WorkspaceSurfaceRenderContext, WorkspaceWebNavigationPort } from './workspace-surface-renderer-contract';
+
+/** Work owns a view-local web session; Browser injects its tab runtime port. */
+function useLocalWebNavigation(url: string) {
+  const [runtime, setRuntime] = useState(() => createWorkspaceWebRuntime(url));
+  const current = useRef(runtime);
+  const port = useMemo<WorkspaceWebNavigationPort>(() => {
+    const commit = (next: WorkspaceWebRuntime | null) => {
+      if (!next) return;
+      current.current = next;
+      setRuntime(next);
+    };
+    return {
+      getRuntime: () => current.current,
+      setRuntime: commit,
+      navigate: (address) => commit(navigateWorkspaceWebRuntime(current.current, address)),
+      back: () => commit(moveWorkspaceWebHistory(current.current, -1)),
+      forward: () => commit(moveWorkspaceWebHistory(current.current, 1)),
+      reload: () => commit(reloadWorkspaceWebRuntime(current.current)),
+      updateMetadata: () => {},
+    };
+  }, []);
+  return { runtime, port };
+}
+
+function browserTitleForUrl(url: string): string {
+  try {
+    return new URL(url).hostname || url;
+  } catch {
+    return url;
+  }
+}
+
+function browserFaviconForUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}/favicon.ico`;
+  } catch {
+    return null;
+  }
+}
+
+export function WebRenderer({ surface, context }: {
+  surface: Extract<WorkspaceSurfaceRendererData, { kind: 'web' }>;
+  context: WorkspaceSurfaceRenderContext;
+}) {
+  const local = useLocalWebNavigation(surface.url);
+  const port = context.webNavigation ?? local.port;
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const embedTimeoutRef = useRef<number | null>(null);
+  const runtime = context.webNavigation ? surface.runtime ?? port.getRuntime() : local.runtime;
+  const currentUrl = runtime?.currentUrl ?? surface.url;
+  const reloadToken = runtime?.reloadToken ?? 0;
+  const [address, setAddress] = useState(currentUrl);
+  const [pageTitle, setPageTitle] = useState(() => browserTitleForUrl(currentUrl));
+  const [addressError, setAddressError] = useState<string | null>(null);
+  const [showEmbedTimeout, setShowEmbedTimeout] = useState(false);
+
+  useEffect(() => {
+    setAddress(currentUrl);
+    setPageTitle(browserTitleForUrl(currentUrl));
+  }, [currentUrl]);
+
+  useEffect(() => {
+    if (runtime) return;
+    port.setRuntime({
+      currentUrl: surface.url,
+      history: [surface.url],
+      historyIndex: 0,
+      reloadToken: 0,
+      isLoading: true,
+      error: null,
+    });
+  }, [runtime, port, surface.url]);
+
+  const reportRuntime = useCallback((patch: Partial<WorkspaceWebRuntime>) => {
+    const current = port.getRuntime() ?? {
+      currentUrl,
+      history: [currentUrl],
+      historyIndex: 0,
+      reloadToken,
+      isLoading: true,
+      error: null,
+    };
+    port.setRuntime({ ...current, ...patch });
+  }, [currentUrl, reloadToken, port]);
+
+  useEffect(() => {
+    setShowEmbedTimeout(false);
+    embedTimeoutRef.current = window.setTimeout(() => {
+      setShowEmbedTimeout(true);
+      reportRuntime({ isLoading: false, error: '网页可能禁止嵌入或加载超时' });
+    }, 6_000);
+    return () => {
+      if (embedTimeoutRef.current !== null) window.clearTimeout(embedTimeoutRef.current);
+      embedTimeoutRef.current = null;
+    };
+  }, [currentUrl, reloadToken, reportRuntime]);
+
+  const handleNavigate = useCallback((event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const normalized = canonicalUrl(address);
+    if (!normalized) {
+      setAddressError('请输入 http:// 或 https:// 地址');
+      return;
+    }
+    setAddressError(null);
+    setAddress(normalized);
+    port.navigate(normalized);
+    port.updateMetadata({
+      icon: browserFaviconForUrl(normalized),
+      title: browserTitleForUrl(normalized),
+    });
+  }, [address, port]);
+
+  const handleIframeLoad = useCallback(() => {
+    const iframe = iframeRef.current;
+    styleAccessibleIframeScrollbar(iframe);
+    if (embedTimeoutRef.current !== null) window.clearTimeout(embedTimeoutRef.current);
+    embedTimeoutRef.current = null;
+    setShowEmbedTimeout(false);
+    let loadedUrl = currentUrl;
+    let pageTitle = '';
+    try {
+      const href = iframe?.contentWindow?.location.href;
+      loadedUrl = canonicalUrl(href ?? '') ?? currentUrl;
+      pageTitle = iframe?.contentDocument?.title?.trim() ?? '';
+    } catch {
+      // Cross-origin pages intentionally do not expose their URL/title to the
+      // host document. Keep the address bar and tab title at their last known
+      // values in that case.
+    }
+
+    const runtimeNow = port.getRuntime();
+    if (runtimeNow && loadedUrl !== runtimeNow.currentUrl) {
+      const history = runtimeNow.history.slice(0, runtimeNow.historyIndex + 1);
+      if (history[history.length - 1] !== loadedUrl) history.push(loadedUrl);
+      reportRuntime({
+        currentUrl: loadedUrl,
+        history,
+        historyIndex: history.length - 1,
+        isLoading: false,
+        error: null,
+      });
+    } else {
+      reportRuntime({ isLoading: false, error: null });
+    }
+    port.updateMetadata({
+      title: pageTitle || browserTitleForUrl(loadedUrl),
+      icon: browserFaviconForUrl(loadedUrl),
+    });
+    setPageTitle(pageTitle || browserTitleForUrl(loadedUrl));
+  }, [currentUrl, pageTitle, reportRuntime, port]);
+
+  useEffect(() => {
+    const error = runtime?.error;
+    context.reportPresentation?.({
+      title: pageTitle,
+      icon: browserFaviconForUrl(currentUrl) ?? undefined,
+      state: error
+        ? {
+            status: 'error',
+            message: { key: 'error.unexpected', fallbackText: error },
+            actions: [{ id: 'reload', label: { key: 'error.retry' }, enabled: true, run: port.reload }],
+          }
+        : runtime?.isLoading
+          ? { status: 'loading', phase: 'content', message: { key: 'memo.navigation.loading' }, retainContent: true }
+          : { status: 'ready' },
+    });
+  }, [context.reportPresentation, currentUrl, pageTitle, port.reload, runtime?.error, runtime?.isLoading]);
+
+  const handleOpenInSystemBrowser = useCallback(() => {
+    void openUrl(currentUrl).catch(() => {
+      reportRuntime({ error: '无法在系统浏览器中打开' });
+    });
+  }, [currentUrl, reportRuntime]);
+
+  return (
+    <div className="flex h-full min-h-0 w-full flex-col bg-[var(--background)]">
+      <form
+        onSubmit={handleNavigate}
+        className="flex shrink-0 items-center gap-1 border-b border-[var(--divider)] bg-[var(--bg-titlebar)] px-2 py-1.5"
+      >
+        <button
+          type="button"
+          aria-label="后退"
+          title="后退"
+          disabled={!runtime || runtime.historyIndex <= 0}
+          onClick={() => port.back()}
+          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] disabled:opacity-35"
+        >
+          <ChevronLeft className="h-3.5 w-3.5" />
+        </button>
+        <button
+          type="button"
+          aria-label="前进"
+          title="前进"
+          disabled={!runtime || runtime.historyIndex >= runtime.history.length - 1}
+          onClick={() => port.forward()}
+          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)] disabled:opacity-35"
+        >
+          <ChevronRight className="h-3.5 w-3.5" />
+        </button>
+        <button
+          type="button"
+          aria-label="重新加载"
+          title="重新加载"
+          onClick={() => port.reload()}
+          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)]"
+        >
+          <RotateCw className="h-3.5 w-3.5" />
+        </button>
+        <div className="flex min-w-0 flex-1 items-center rounded-md border border-[var(--border)] bg-[var(--background)] px-2">
+          <Globe className="mr-1.5 h-3.5 w-3.5 shrink-0 text-[var(--muted-foreground)]" />
+          <input
+            aria-label="网页地址"
+            value={address}
+            onChange={(event) => {
+              setAddress(event.target.value);
+              setAddressError(null);
+            }}
+            className="h-7 min-w-0 flex-1 bg-transparent text-xs text-[var(--foreground)] outline-none"
+            spellCheck={false}
+          />
+        </div>
+        <button type="button" aria-label="在系统浏览器中打开" title="在系统浏览器中打开"
+          onClick={handleOpenInSystemBrowser}
+          className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)]">
+          <ArrowUpRight className="h-3.5 w-3.5" />
+        </button>
+        {runtime?.isLoading && (
+          <span
+            role="status"
+            aria-label="加载中"
+            className="mx-1 h-4 w-4 shrink-0 flowix-spin rounded-full border-2 border-[color-mix(in_oklch,var(--muted-foreground)_26%,transparent)] border-t-[var(--brand)]"
+          />
+        )}
+        {runtime?.error && <span className="shrink-0 text-[10px] text-[var(--destructive)]">{runtime.error}</span>}
+      </form>
+      {addressError && <div className="shrink-0 px-3 py-1 text-[10px] text-[var(--destructive)]">{addressError}</div>}
+      <div className="relative min-h-0 min-w-0 flex-1 bg-white">
+        <iframe
+          key={`${context.viewId}:${currentUrl}:${reloadToken}`}
+          ref={iframeRef}
+          title={surface.title ?? browserTitleForUrl(currentUrl)}
+          src={currentUrl}
+          onLoad={handleIframeLoad}
+          onError={() => {
+            reportRuntime({ isLoading: false, error: '网页加载失败' });
+            setShowEmbedTimeout(true);
+          }}
+          className="h-full w-full border-0"
+          referrerPolicy="no-referrer"
+        />
+        {showEmbedTimeout && (
+          <div className="absolute inset-0 flex items-center justify-center bg-white/90 px-6 backdrop-blur-sm">
+            <div className="relative flex max-w-sm flex-col items-center gap-4 rounded-xl border border-[var(--border)] bg-[var(--background)] px-8 py-7 text-center shadow-lg">
+              <button
+                type="button"
+                aria-label="关闭提示"
+                title="关闭提示"
+                onClick={() => setShowEmbedTimeout(false)}
+                className="absolute right-2 top-2 flex h-7 w-7 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--muted)]"
+              >
+                <X className="h-4 w-4" />
+              </button>
+              <p className="text-sm text-[var(--muted-foreground)]">网页可能禁止嵌入或加载超时</p>
+              <button
+                type="button"
+                onClick={handleOpenInSystemBrowser}
+                className="inline-flex h-8 items-center rounded-lg border border-[var(--border)] px-3 text-xs text-[var(--foreground)] transition-colors hover:bg-[var(--muted)]"
+              >
+                在系统浏览器中打开
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/app/flowix-web/features/workspace/model/legacy-folder-list.ts b/app/flowix-web/features/workspace/model/legacy-folder-list.ts
new file mode 100644
index 000000000..5d35b0e24
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/legacy-folder-list.ts
@@ -0,0 +1,21 @@
+/** Shape persisted by the removed standalone folder-list workspace surface. */
+export type LegacyFolderListScope = {
+  kind: 'folder';
+  path: string;
+  notebookPath: string;
+  notebookId: string | null;
+};
+
+export type LegacyFolderListFilters = {
+  resourceKinds?: string[];
+  tags?: string[];
+  customFilterId?: string;
+};
+
+/** Read only at persistence and history boundaries; never a renderable target. */
+export type LegacyFolderListTarget = {
+  kind: 'document-list';
+  displayId: string;
+  scope: LegacyFolderListScope;
+  filters: LegacyFolderListFilters;
+};
diff --git a/app/flowix-web/features/workspace/model/path-move.ts b/app/flowix-web/features/workspace/model/path-move.ts
new file mode 100644
index 000000000..3b899f282
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/path-move.ts
@@ -0,0 +1,48 @@
+import { canonicalPath } from '@/lib/path';
+import type { WorkspaceContentTarget } from './surface-target';
+import type { BrowserColumnTarget } from '../store/browser-column-store';
+import type { LegacyFolderListTarget } from './legacy-folder-list';
+
+export function movedFilePath(path: string, previous: string, next: string, directory: boolean): string {
+  const normalized = canonicalPath(path);
+  if (normalized === previous) return next;
+  return directory && normalized.startsWith(`${previous}/`)
+    ? `${next}${normalized.slice(previous.length)}` : path;
+}
+
+/** Rebase address hints, preserving display identity, view selection and host state. */
+export function rebaseWorkspaceTargetPath<T extends WorkspaceContentTarget | BrowserColumnTarget | LegacyFolderListTarget>(
+  target: T, previous: string, next: string, directory: boolean,
+): T {
+  const move = (path: string) => movedFilePath(path, previous, next, directory);
+  switch (target.kind) {
+    case 'external': {
+      const path = move(target.path);
+      const folderPath = target.fileBrowser?.folderPath;
+      const movedFolder = folderPath ? move(folderPath) : folderPath;
+      if (path === target.path && movedFolder === folderPath) return target;
+      return { ...target, path, fileBrowser: target.fileBrowser
+        ? { ...target.fileBrowser, folderPath: movedFolder ?? null } : undefined };
+    }
+    case 'file-browser': {
+      const activeFilePath = target.activeFilePath ? move(target.activeFilePath) : null;
+      const folderPath = target.folderPath ? move(target.folderPath) : null;
+      return activeFilePath === target.activeFilePath && folderPath === target.folderPath
+        ? target : { ...target, activeFilePath, folderPath };
+    }
+    case 'folder-collection': {
+      const folderPath = move(target.folderPath);
+      return folderPath === target.folderPath ? target : {
+        ...target, folderPath, folderName: folderPath.split('/').pop() ?? target.folderName,
+      };
+    }
+    case 'collection':
+    case 'table':
+    case 'media-library':
+    case 'media': {
+      const filePath = move(target.filePath);
+      return filePath === target.filePath ? target : { ...target, filePath };
+    }
+    default: return target;
+  }
+}
diff --git a/app/flowix-web/features/workspace/model/surface-contract.ts b/app/flowix-web/features/workspace/model/surface-contract.ts
new file mode 100644
index 000000000..461be8397
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/surface-contract.ts
@@ -0,0 +1,98 @@
+import type { WorkspaceSurfaceIdentity } from './surface-identity';
+
+export type WorkspaceSurfaceHost = 'main-third' | 'browser-column';
+
+export type WorkspaceSurfaceCapability =
+  | 'edit' | 'search' | 'memo-colors' | 'properties' | 'copy-content'
+  | 'export-content' | 'save-template' | 'version-history' | 'fit' | 'zoom'
+  | 'fullscreen' | 'open-source' | 'run-agent' | 'stream-conversation'
+  | 'web-navigation';
+
+export type WorkspaceFileSurfaceKind =
+  | 'markdown' | 'code' | 'csv' | 'image' | 'video' | 'table'
+  | 'media-library' | 'html' | 'docx' | 'unavailable';
+
+/** Canonical surface kinds shared by the Work and Browser hosts. */
+export type WorkspaceSurfaceKind =
+  | `file-${WorkspaceFileSurfaceKind}`
+  | 'file-browser' | 'media' | 'mindmap' | 'plugin-artifact' | 'agent-conversation' | 'web'
+  | 'plugin-workbench' | 'collection';
+
+
+/** Appearance dimensions are independent: header styling never determines loading styling. */
+export type SurfaceHeaderStyle = 'document' | 'agent' | 'media';
+export type SurfaceBackground = 'document' | 'agent' | 'media';
+export interface SurfaceAppearance {
+  headerStyle: SurfaceHeaderStyle;
+  contentBackground: SurfaceBackground;
+  stateBackground: SurfaceBackground;
+  emptyDecoration: 'document-artwork' | 'none';
+}
+
+export interface SurfaceMessage {
+  key: string;
+  params?: Record<string, string | number>;
+  /** Optional domain detail shown alongside the translated message key. */
+  fallbackText?: string;
+}
+export interface SurfaceAction {
+  id: string;
+  label: SurfaceMessage;
+  enabled: boolean;
+  run: () => void | Promise<void>;
+}
+export interface SurfaceNotice {
+  id: string;
+  severity: 'info' | 'success' | 'warning' | 'error';
+  message: SurfaceMessage;
+  actions?: readonly SurfaceAction[];
+}
+export type SurfaceEmptyReason = 'no-target' | 'stale-context' | 'invalid-target' | 'invalid-artifact' | 'no-content';
+export type SurfaceState =
+  | { status: 'loading'; phase: 'navigation' | 'renderer' | 'content'; message?: SurfaceMessage; retainContent: boolean }
+  | { status: 'empty'; reason: SurfaceEmptyReason; message: SurfaceMessage; actions?: readonly SurfaceAction[] }
+  | { status: 'ready'; notices?: readonly SurfaceNotice[] }
+  | { status: 'unavailable'; reason: 'missing' | 'forbidden' | 'unsupported' | 'stale-context'; message: SurfaceMessage; actions?: readonly SurfaceAction[] }
+  | { status: 'error'; message: SurfaceMessage; detailText?: string; actions?: readonly SurfaceAction[] };
+
+/** A content identity may have independent Work and Browser view instances. */
+export interface SurfaceViewContext {
+  host: WorkspaceSurfaceHost;
+  viewId: string;
+  focused: boolean;
+  readOnly: boolean;
+  initialFocus?: 'title' | 'body';
+}
+export interface SurfaceLifecycle {
+  status: 'ready';
+  flush?: (options?: { silent?: boolean }) => Promise<boolean>;
+  discard?: () => void;
+  focus?: (target?: 'title' | 'body') => boolean | void;
+  dispose?: () => void;
+}
+export interface SurfacePresentation {
+  title: string;
+  icon?: string;
+  appearance: SurfaceAppearance;
+  capabilities: readonly WorkspaceSurfaceCapability[];
+  actions: readonly SurfaceAction[];
+  state: SurfaceState;
+}
+/** Runtime values a renderer may publish after async resolution or mode changes. */
+export type SurfacePresentationUpdate = Partial<Pick<SurfacePresentation,
+  'title' | 'icon' | 'appearance' | 'capabilities' | 'actions' | 'state'>>;
+export interface ResolvedSurface<K extends WorkspaceSurfaceKind, D> {
+  kind: K;
+  identity: WorkspaceSurfaceIdentity;
+  data: D;
+}
+
+/** Per-view web navigation state; it is never part of content identity. */
+export interface WorkspaceWebRuntime {
+  currentUrl: string;
+  history: string[];
+  historyIndex: number;
+  reloadToken: number;
+  isLoading: boolean;
+  error: string | null;
+}
diff --git a/app/flowix-web/features/workspace/model/surface-identity.ts b/app/flowix-web/features/workspace/model/surface-identity.ts
new file mode 100644
index 000000000..e665668cb
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/surface-identity.ts
@@ -0,0 +1,63 @@
+import { canonicalPath, fileLocatorKey } from '@/lib/path';
+import { canonicalUrl } from '@/lib/url';
+
+export { canonicalUrl } from '@/lib/url';
+
+/**
+ * Stable identity for content that can be opened by either workspace host.
+ *
+ * Paths and URLs deliberately have different normalizers. `canonicalPath`
+ * collapses repeated slashes, which is correct for filesystem paths but would
+ * corrupt the `//` in an URL scheme.
+ */
+export type ContentIdentity =
+  | { kind: 'collection'; notebookId: string; collectionId: string; viewId: string | null }
+  | { kind: 'media'; path: string }
+  | { kind: 'external'; path: string }
+  | { kind: 'file-browser'; folderPath: string }
+  | { kind: 'folder-collection'; notebookId: string; folderPath: string }
+  | { kind: 'web'; url: string }
+  | { kind: 'agent-conversation'; instanceId: string };
+
+export function contentIdentityKey(
+  identity: ContentIdentity,
+): string | null {
+  switch (identity.kind) {
+    case 'collection': return `collection:${JSON.stringify([identity.notebookId, identity.collectionId])}`;
+    case 'media': {
+      const path = identity.path;
+      return path.trim() ? fileLocatorKey(path) : null;
+    }
+    case 'external': {
+      const path = identity.path;
+      return path.trim() ? fileLocatorKey(path) : null;
+    }
+    case 'file-browser': {
+      const folderPath = identity.folderPath.trim();
+      return folderPath ? `file-browser:${canonicalPath(folderPath)}` : null;
+    }
+    case 'folder-collection': {
+      const folderPath = identity.folderPath.trim();
+      return folderPath ? `folder-collection:${JSON.stringify([identity.notebookId, canonicalPath(folderPath)])}` : null;
+    }
+    case 'web': {
+      const url = canonicalUrl(identity.url);
+      return url ? `web:${url}` : null;
+    }
+    case 'agent-conversation': {
+      const instanceId = identity.instanceId.trim();
+      return instanceId ? `agent:${instanceId}` : null;
+    }
+  }
+}
+
+/** Every registered surface has an identity, including non-file workspace views. */
+export type WorkspaceSurfaceIdentity = ContentIdentity
+  | { kind: 'plugin-workbench'; pluginId: string };
+
+export function workspaceSurfaceIdentityKey(identity: WorkspaceSurfaceIdentity): string | null {
+  switch (identity.kind) {
+    case 'plugin-workbench': return identity.pluginId.trim() ? `plugin:${JSON.stringify(identity.pluginId)}` : null;
+    default: return contentIdentityKey(identity);
+  }
+}
diff --git a/app/flowix-web/features/workspace/model/surface-opening.ts b/app/flowix-web/features/workspace/model/surface-opening.ts
new file mode 100644
index 000000000..61f3f3b2d
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/surface-opening.ts
@@ -0,0 +1,47 @@
+import type { MarkdownLocation } from '@platform/tauri/client';
+import type { WorkWorkspaceSurfaceTarget, BrowserWorkspaceSurfaceTarget } from './surface-target';
+
+export type BrowserSurfaceOpenDisposition = 'focus-existing' | 'replace-active' | 'open-in-column';
+export type WorkspaceContentLocation =
+  | { host: 'main-third'; state: 'active' | 'pending' }
+  | { host: 'browser-column'; tabId: string };
+
+export interface WorkspaceOpenNavigationOptions {
+  history?: 'push' | 'skip';
+  /** Re-resolve and commit an already-open collection after its backing file changes. */
+  refresh?: boolean;
+}
+export interface WorkWorkspaceSurfaceOptions extends WorkspaceOpenNavigationOptions {
+  notebookId?: string | null;
+  markdownLocation?: MarkdownLocation | null;
+  initialFocus?: 'title' | 'body';
+}
+export interface BrowserWorkspaceSurfaceOptions {
+  notebookId?: string | null;
+  browserDisposition?: BrowserSurfaceOpenDisposition;
+}
+export interface WorkWorkspaceSurfaceRequest {
+  /** Missing host means Work. */
+  host?: 'main-third';
+  target: WorkWorkspaceSurfaceTarget;
+  options?: WorkWorkspaceSurfaceOptions;
+}
+export interface BrowserWorkspaceSurfaceRequest {
+  host: 'browser-column';
+  target: BrowserWorkspaceSurfaceTarget;
+  options?: BrowserWorkspaceSurfaceOptions;
+}
+export type OpenWorkspaceSurfaceRequest = WorkWorkspaceSurfaceRequest | BrowserWorkspaceSurfaceRequest;
+export type WorkWorkspaceOpenResult =
+  | { status: 'opened' | 'activated'; host: 'main-third'; location: Extract<WorkspaceContentLocation, { host: 'main-third' }> }
+  | { status: 'cancelled'; host: 'main-third'; reason: 'navigation-cancelled' };
+export type BrowserWorkspaceOpenResult =
+  | { status: 'opened' | 'activated'; host: 'browser-column'; location: Extract<WorkspaceContentLocation, { host: 'browser-column' }> }
+  | { status: 'cancelled'; host: 'browser-column'; reason: 'navigation-cancelled' };
+export type WorkspaceSurfaceOpenResult = WorkWorkspaceOpenResult | BrowserWorkspaceOpenResult;
+/** Internal Browser adapter detail, normalized by openWorkspaceSurface. */
+export type BrowserColumnNavigationResult = {
+  host: 'browser-column';
+  tabId: string;
+  alreadyOpen: boolean;
+} | null;
diff --git a/app/flowix-web/features/workspace/model/surface-target.ts b/app/flowix-web/features/workspace/model/surface-target.ts
new file mode 100644
index 000000000..e2f9f1cc9
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/surface-target.ts
@@ -0,0 +1,94 @@
+import type { PluginDescriptor } from '@platform/tauri/client';
+import type { CollectionDisplayDescriptor } from '@/lib/collection-display-registry';
+
+/** Public content targets have no dependency on a host store or React view. */
+export interface FileBrowserContext {
+  /** Only legacy tabs lack a notebook binding; bind them once when restored. */
+  restoreNotebookContext?: boolean;
+  folderPath: string | null;
+  notebookId: string | null;
+  scopePath: string | null;
+  fileTreeVisible: boolean;
+  fileTreeWidth: number;
+}
+
+export interface FileBrowserTarget extends FileBrowserContext {
+  kind: 'file-browser';
+  activeFilePath: string | null;
+  collectionDisplay?: CollectionDisplayDescriptor;
+  collectionType?: 'table' | 'media_library';
+  collectionUnavailableReason?: string;
+}
+
+export interface CollectionSurfaceTarget {
+  kind: 'collection';
+  displayId: string;
+  notebookId: string;
+  collectionId: string;
+  viewId: string | null;
+  collectionType: 'table' | 'media_library';
+  filePath: string;
+  notebookPath: string;
+  name: string;
+  unavailableReason?: string;
+}
+
+/** Folder-scoped Collection surface before the folder's collection type is selected. */
+export interface FolderCollectionSurfaceTarget {
+  kind: 'folder-collection';
+  folderPath: string;
+  notebookId: string;
+  notebookPath: string;
+  folderName: string;
+}
+
+export type WorkspaceContentTarget =
+  | { kind: 'empty' }
+  | CollectionSurfaceTarget
+  | FolderCollectionSurfaceTarget
+  | {
+      kind: 'external';
+      fileBrowser?: FileBrowserContext;
+      path: string;
+      scopePath: string | null;
+      /** Compatibility input; navigation adapters own transition IDs. */
+      transitionId?: number | null;
+    }
+  | { kind: 'table'; filePath: string; notebookPath: string | null; notebookId: string | null; unavailableReason?: string }
+  | {
+      kind: 'media';
+      filePath: string;
+      notebookId: string | null;
+      notebookPath: string | null;
+      resourceKind: 'image' | 'video';
+    }
+  | { kind: 'media-library'; filePath: string; notebookPath: string | null; notebookId: string | null; unavailableReason?: string }
+  | {
+      kind: 'agent-conversation';
+      instanceId: string;
+      /** A temporary empty draft should restore as an empty work column if it has vanished. */
+      blankIfMissing?: true;
+    }
+  /** View identity only. Plugin run state and artifacts live in host stores. */
+  | { kind: 'plugin-workbench'; plugin: PluginDescriptor }
+  | { kind: 'web'; url: string };
+
+
+export interface CollectionReferenceSurfaceTarget {
+  kind: 'collection-reference';
+  notebookId: string;
+  collectionId: string;
+  collectionKind?: 'table' | 'media_library';
+  viewId?: string | null;
+  displayId?: string;
+  relativePathHint?: string;
+  filePath?: string;
+}
+
+export type WorkspaceSurfaceOpenTarget = WorkspaceContentTarget | FileBrowserTarget | CollectionReferenceSurfaceTarget;
+/** Empty is a host state, not an open request. */
+export type WorkWorkspaceSurfaceTarget = Exclude<WorkspaceContentTarget, { kind: 'empty' }> | CollectionReferenceSurfaceTarget;
+export type BrowserWorkspaceSurfaceTarget = Exclude<
+  WorkspaceContentTarget,
+  { kind: 'empty' | 'plugin-workbench' }
+> | FileBrowserTarget | CollectionReferenceSurfaceTarget;
diff --git a/app/flowix-web/features/workspace/model/web-navigation.ts b/app/flowix-web/features/workspace/model/web-navigation.ts
new file mode 100644
index 000000000..40c0dad0c
--- /dev/null
+++ b/app/flowix-web/features/workspace/model/web-navigation.ts
@@ -0,0 +1,24 @@
+import type { WorkspaceWebRuntime } from './surface-contract';
+
+export function createWorkspaceWebRuntime(url: string): WorkspaceWebRuntime {
+  return { currentUrl: url, history: [url], historyIndex: 0, reloadToken: 0, isLoading: true, error: null };
+}
+
+/** Address is already normalized by the navigation caller. */
+export function navigateWorkspaceWebRuntime(current: WorkspaceWebRuntime, url: string): WorkspaceWebRuntime {
+  const history = current.history.slice(0, current.historyIndex + 1);
+  if (history[history.length - 1] !== url) history.push(url);
+  return { ...current, currentUrl: url, history, historyIndex: history.length - 1,
+    reloadToken: current.reloadToken + 1, isLoading: true, error: null };
+}
+
+export function moveWorkspaceWebHistory(current: WorkspaceWebRuntime, direction: -1 | 1): WorkspaceWebRuntime | null {
+  const historyIndex = current.historyIndex + direction;
+  if (historyIndex < 0 || historyIndex >= current.history.length) return null;
+  return { ...current, currentUrl: current.history[historyIndex], historyIndex,
+    reloadToken: current.reloadToken + 1, isLoading: true, error: null };
+}
+
+export function reloadWorkspaceWebRuntime(current: WorkspaceWebRuntime): WorkspaceWebRuntime {
+  return { ...current, reloadToken: current.reloadToken + 1, isLoading: true, error: null };
+}
diff --git a/app/flowix-web/features/workspace/public/app-api.ts b/app/flowix-web/features/workspace/public/app-api.ts
index 55abf3047..9fd4359e9 100644
--- a/app/flowix-web/features/workspace/public/app-api.ts
+++ b/app/flowix-web/features/workspace/public/app-api.ts
@@ -2,8 +2,7 @@ import { useWorkspaceRestoreStore } from '@features/workspace/store/workspace-re
 export { ensureFileDisplayTrackingStarted } from '@features/workspace/use-cases/file-display-tracking';
 export {
   removeBrowserColumnTabsByPath,
-  openBrowserColumnNotebookNote,
-} from '@features/workspace/use-cases/browser-column-navigation';
+} from '@features/workspace/public/browser-column-api';
 export { applyNotebookPathMove } from '@features/workspace/use-cases/notebook-path-move';
 
 export function syncAppAgentConversationRestore(instanceId: string | null): void {
diff --git a/app/flowix-web/features/workspace/public/browser-column-api.ts b/app/flowix-web/features/workspace/public/browser-column-api.ts
index 2e488b87d..719e0a1f5 100644
--- a/app/flowix-web/features/workspace/public/browser-column-api.ts
+++ b/app/flowix-web/features/workspace/public/browser-column-api.ts
@@ -1,7 +1,7 @@
 import { useCallback } from 'react';
 import { useShallow } from 'zustand/react/shallow';
 import {
-  canMoveBrowserColumnTargetToWorkColumn,
+  canOpenBrowserColumnTargetInWorkColumn,
   useBrowserColumnStore,
   type BrowserColumnTab,
 } from '@features/workspace/store/browser-column-store';
@@ -13,18 +13,27 @@ import {
   registerBrowserColumnDocumentFlush,
 } from '@features/workspace/use-cases/browser-column-coordinator';
 import {
-  openBrowserColumnMarkdown,
-  openBrowserColumnAgentConversation,
-  openBrowserColumnNotebookNote,
-  openBrowserColumnTabInWorkColumn,
+  createFileBrowserTarget,
+  removeBrowserColumnTabsByPath,
+  selectBrowserColumnFile,
 } from '@features/workspace/use-cases/browser-column-navigation';
+import { openBrowserColumnTabInWorkColumn } from '@features/workspace/use-cases/surface-opening';
 
-export { openBrowserColumnAgentConversation, openBrowserColumnNotebookNote };
+export { openWorkspaceSurface } from './open-surface-api';
+export type { OpenWorkspaceSurfaceRequest, BrowserWorkspaceSurfaceRequest } from './open-surface-api';
 
 export {
-  canMoveBrowserColumnTargetToWorkColumn,
+  createFileBrowserTarget,
+  removeBrowserColumnTabsByPath,
+  selectBrowserColumnFile,
+};
+export { openBrowserColumnTabInWorkColumn };
+
+export {
+  canOpenBrowserColumnTargetInWorkColumn,
   type BrowserColumnTab,
 };
+export type { BrowserColumnTarget } from '@features/workspace/store/browser-column-store';
 
 export function useBrowserColumnViewModel() {
   return useBrowserColumnStore(useShallow((state) => {
@@ -56,8 +65,6 @@ export function useBrowserColumnFocusViewModel() {
 
 export const selectBrowserColumnTab = activateBrowserColumnTab;
 export const registerBrowserColumnFlush = registerBrowserColumnDocumentFlush;
-export const openBrowserColumnTabInMainWorkColumn = openBrowserColumnTabInWorkColumn;
-export const openMarkdownInBrowserColumn = openBrowserColumnMarkdown;
 
 export function hideBrowserColumn(): void {
   useBrowserColumnStore.getState().setVisible(false);
@@ -76,12 +83,12 @@ export function closeBrowserColumnTab(
   options?: { discardChanges?: boolean },
 ): Promise<boolean | null> {
   const closesActiveTab = useBrowserColumnStore.getState().activeTabId === tabId;
-  if (options?.discardChanges && closesActiveTab) discardActiveBrowserColumnDocument();
+  const discarded = Boolean(options?.discardChanges && closesActiveTab && discardActiveBrowserColumnDocument());
   return enqueueBrowserColumnNavigation(() => {
     if (browserColumnTabExists(tabId)) useBrowserColumnStore.getState().closeTab(tabId);
     return true;
   }, {
-    flush: closesActiveTab && !options?.discardChanges,
+    flush: closesActiveTab && !discarded,
     silentFlush: true,
   });
 }
@@ -91,12 +98,12 @@ export function closeOtherBrowserColumnTabs(
   options?: { discardChanges?: boolean },
 ): Promise<boolean | null> {
   const closesActiveTab = useBrowserColumnStore.getState().activeTabId !== tabId;
-  if (options?.discardChanges && closesActiveTab) discardActiveBrowserColumnDocument();
+  const discarded = Boolean(options?.discardChanges && closesActiveTab && discardActiveBrowserColumnDocument());
   return enqueueBrowserColumnNavigation(() => {
     if (browserColumnTabExists(tabId)) useBrowserColumnStore.getState().closeOtherTabs(tabId);
     return true;
   }, {
-    flush: closesActiveTab && !options?.discardChanges,
+    flush: closesActiveTab && !discarded,
     silentFlush: true,
   });
 }
@@ -109,12 +116,12 @@ export function closeBrowserColumnTabsToRight(
   const targetIndex = state.tabs.findIndex((tab) => tab.id === tabId);
   const activeIndex = state.tabs.findIndex((tab) => tab.id === state.activeTabId);
   const closesActiveTab = targetIndex >= 0 && activeIndex > targetIndex;
-  if (options?.discardChanges && closesActiveTab) discardActiveBrowserColumnDocument();
+  const discarded = Boolean(options?.discardChanges && closesActiveTab && discardActiveBrowserColumnDocument());
   return enqueueBrowserColumnNavigation(() => {
     if (browserColumnTabExists(tabId)) useBrowserColumnStore.getState().closeTabsToRight(tabId);
     return true;
   }, {
-    flush: closesActiveTab && !options?.discardChanges,
+    flush: closesActiveTab && !discarded,
     silentFlush: true,
   });
 }
@@ -122,9 +129,9 @@ export function closeBrowserColumnTabsToRight(
 export function closeAllBrowserColumnTabs(
   options?: { discardChanges?: boolean },
 ): Promise<boolean | null> {
-  if (options?.discardChanges) discardActiveBrowserColumnDocument();
+  const discarded = Boolean(options?.discardChanges && discardActiveBrowserColumnDocument());
   return enqueueBrowserColumnNavigation(() => {
     useBrowserColumnStore.getState().closeAllTabs();
     return true;
-  }, { flush: !options?.discardChanges, silentFlush: true });
+  }, { flush: !discarded, silentFlush: true });
 }
diff --git a/app/flowix-web/features/workspace/public/host-api.ts b/app/flowix-web/features/workspace/public/host-api.ts
new file mode 100644
index 000000000..ce5d98b5c
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/host-api.ts
@@ -0,0 +1,3 @@
+/** Host identity is part of the common surface contract. */
+export type { WorkspaceSurfaceHost as WorkspaceHostId } from '../model/surface-contract';
+export { focusWorkspaceHostFromEvent } from '../use-cases/workspace-host-focus';
diff --git a/app/flowix-web/features/workspace/public/main-window-api.ts b/app/flowix-web/features/workspace/public/main-window-api.ts
index 529ae2d58..81c6bf41b 100644
--- a/app/flowix-web/features/workspace/public/main-window-api.ts
+++ b/app/flowix-web/features/workspace/public/main-window-api.ts
@@ -3,9 +3,9 @@ import { useWorkColumnStore } from '@features/workspace/store/work-column-store'
 export {
   clearPluginWorkbenchTarget,
   dismissNavigationFailure,
-  flushWorkspaceDocument,
-  openCollectionTarget,
-  openPluginWorkbench,
+  prepareActiveWorkColumnDocumentLeave,
+  openFolderCollection,
+  openFolderCollectionFromFolder,
   reconcileDeletedNotebook,
   retryLastNavigation,
   selectNotebook,
diff --git a/app/flowix-web/features/workspace/public/note-navigation-api.ts b/app/flowix-web/features/workspace/public/note-navigation-api.ts
new file mode 100644
index 000000000..85f7b2144
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/note-navigation-api.ts
@@ -0,0 +1,7 @@
+/** Stable navigation commands consumed by note-oriented features. */
+export {
+  clearWorkspaceDocument,
+} from '@features/workspace/use-cases/workspace-navigation';
+export { openWorkspaceSurface } from './open-surface-api';
+export type { OpenWorkspaceSurfaceRequest } from './open-surface-api';
+export type { WorkspaceContentLocation } from '@features/workspace/use-cases/workspace-content-activation';
diff --git a/app/flowix-web/features/workspace/public/open-surface-api.ts b/app/flowix-web/features/workspace/public/open-surface-api.ts
new file mode 100644
index 000000000..4a786323e
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/open-surface-api.ts
@@ -0,0 +1,7 @@
+/** Canonical host-aware surface opening API. */
+export { openWorkspaceSurface } from '../use-cases/surface-opening';
+export type * from '../model/surface-opening';
+export type {
+  WorkspaceSurfaceOpenTarget, WorkWorkspaceSurfaceTarget, BrowserWorkspaceSurfaceTarget,
+  CollectionReferenceSurfaceTarget,
+} from '../model/surface-target';
diff --git a/app/flowix-web/features/workspace/public/search-navigation-api.ts b/app/flowix-web/features/workspace/public/search-navigation-api.ts
index e6ff3d2ee..76cf94824 100644
--- a/app/flowix-web/features/workspace/public/search-navigation-api.ts
+++ b/app/flowix-web/features/workspace/public/search-navigation-api.ts
@@ -1,2 +1 @@
-export { selectAndOpenAgentConversation } from '@features/workspace/use-cases/agent-conversation-navigation';
 export { selectNotebook } from '@features/workspace/use-cases/workspace-navigation';
diff --git a/app/flowix-web/features/workspace/public/shell-api.ts b/app/flowix-web/features/workspace/public/shell-api.ts
index 619533731..5b0157d06 100644
--- a/app/flowix-web/features/workspace/public/shell-api.ts
+++ b/app/flowix-web/features/workspace/public/shell-api.ts
@@ -4,16 +4,16 @@ import { useShallow } from 'zustand/react/shallow';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
 import { useBrowserColumnStore } from '@features/workspace/store/browser-column-store';
 import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focus-store';
-import { openWorkColumnTargetInBrowserColumn } from '@features/workspace/use-cases/browser-column-navigation';
+import { openWorkspaceSurface } from './open-surface-api';
 
 export { selectNotebook } from '@features/workspace/use-cases/workspace-navigation';
 export {
   clearWorkspaceTargetForDeletedFile,
+  clearWorkspaceTargetsForDeletedDirectory,
   historyEntryFromWorkColumnTarget,
-  openDocumentListTarget,
-  openExternalTarget,
 } from '@features/workspace/use-cases/workspace-navigation';
-export { openBrowserColumnDroppedFile } from '@features/workspace/use-cases/browser-column-navigation';
+export { openWorkspaceSurface } from './open-surface-api';
+export type { OpenWorkspaceSurfaceRequest } from './open-surface-api';
 export { deleteMainExternalDocument } from '@features/workspace/use-cases/delete-main-external-document';
 
 export function clearBrowserColumnExternalPath(path: string): void {
@@ -26,6 +26,23 @@ export {
 } from '@features/workspace/store/browser-column-store';
 export type { WorkColumnTarget } from '@features/workspace/store/work-column-target';
 
+/** Hosts with content visible in the current workspace layout. */
+export function getVisibleWorkspaceSurfaceHosts(): ('main-third' | 'browser-column')[] {
+  const hosts: ('main-third' | 'browser-column')[] = ['main-third'];
+  const browser = useBrowserColumnStore.getState();
+  if (browser.visible && browser.activeTabId
+    && browser.tabs.some((tab) => tab.id === browser.activeTabId)) hosts.push('browser-column');
+  return hosts;
+}
+
+export function getWorkspaceNavigationRevision(): number {
+  return useWorkColumnStore.getState().navigation.requestId;
+}
+
+export function getWorkColumnStartupIdentity(): string {
+  return JSON.stringify(useWorkColumnStore.getState().navigation.target);
+}
+
 export function useShellWorkspaceViewModel() {
   const { navigation, notebookSwitchesInFlight } = useWorkColumnStore(useShallow((state) => ({
     navigation: state.navigation,
@@ -53,11 +70,13 @@ export function useWorkColumnTransferViewModel() {
   const canOpenInBrowserColumn = target.kind !== 'empty'
     && target.kind !== 'plugin-workbench';
   const openInBrowserColumn = useCallback(() => {
-    if (!canOpenInBrowserColumn) return Promise.resolve(null);
-    return openWorkColumnTargetInBrowserColumn(target).catch((error: unknown) => {
+    if (target.kind === 'empty' || target.kind === 'plugin-workbench') {
+      return Promise.resolve(null);
+    }
+    return openWorkspaceSurface({ host: 'browser-column', target }).catch((error: unknown) => {
       toast.error('无法在右栏打开', { description: error instanceof Error ? error.message : String(error) });
       return null;
     });
-  }, [canOpenInBrowserColumn, target]);
+  }, [target]);
   return { canOpenInBrowserColumn, openInBrowserColumn };
 }
diff --git a/app/flowix-web/features/workspace/public/shutdown-api.test.ts b/app/flowix-web/features/workspace/public/shutdown-api.test.ts
new file mode 100644
index 000000000..1fba696f6
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/shutdown-api.test.ts
@@ -0,0 +1,24 @@
+import { expect, it, vi } from 'vitest';
+import { registerWorkspaceSurfaceLifecycle } from '../store/surface-lifecycle-store';
+import { flushWorkspaceSurfacesForShutdown } from './shutdown-api';
+
+it('starts all surface barriers together and reports a failure without skipping other views', async () => {
+  let finish!: (value: boolean) => void;
+  const table = vi.fn(() => new Promise<boolean>(resolve => { finish = resolve; }));
+  const media = vi.fn().mockRejectedValue(new Error('write failed'));
+  registerWorkspaceSurfaceLifecycle('shutdown-table', { status: 'ready', flush: table });
+  registerWorkspaceSurfaceLifecycle('shutdown-media', { status: 'ready', flush: media });
+  try {
+    let settled = false;
+    const saving = flushWorkspaceSurfacesForShutdown().then(result => { settled = true; return result; });
+    await Promise.resolve(); await Promise.resolve();
+    expect(table).toHaveBeenCalledWith({ silent: true });
+    expect(media).toHaveBeenCalledWith({ silent: true });
+    expect(settled).toBe(false);
+    finish(true);
+    expect(await saving).toBe(false);
+  } finally {
+    registerWorkspaceSurfaceLifecycle('shutdown-table', null);
+    registerWorkspaceSurfaceLifecycle('shutdown-media', null);
+  }
+});
diff --git a/app/flowix-web/features/workspace/public/shutdown-api.ts b/app/flowix-web/features/workspace/public/shutdown-api.ts
new file mode 100644
index 000000000..954d07b51
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/shutdown-api.ts
@@ -0,0 +1,9 @@
+import { listWorkspaceSurfaceLifecycles } from '../store/surface-lifecycle-store';
+
+/** Reuse each surface's save barrier (tables, media libraries, CSV, etc.). */
+export async function flushWorkspaceSurfacesForShutdown(): Promise<boolean> {
+  const results = await Promise.allSettled(listWorkspaceSurfaceLifecycles().map(surface =>
+    Promise.resolve().then(() => surface.flush?.({ silent: true })),
+  ));
+  return results.every(result => result.status === 'fulfilled' && result.value !== false);
+}
diff --git a/app/flowix-web/features/workspace/public/startup-api.ts b/app/flowix-web/features/workspace/public/startup-api.ts
index fdcd63c9f..abbf99983 100644
--- a/app/flowix-web/features/workspace/public/startup-api.ts
+++ b/app/flowix-web/features/workspace/public/startup-api.ts
@@ -2,11 +2,12 @@ import { restoreAgentConversationWorkspace as restore } from '@features/workspac
 import { useWorkspaceRestoreStore } from '@features/workspace/store/workspace-restore-store';
 export {
   captureWorkspaceRestoreTarget,
-  restoreDocumentListWorkspace,
+  restoreLegacyFolderListWorkspace,
   restoreExternalDocumentWorkspace,
   restoreMediaWorkspace,
   restoreTableWorkspace,
   restoreCollectionWorkspace,
+  restoreFolderCollectionWorkspace,
 } from '@features/workspace/use-cases/workspace-navigation';
 export type { PersistedWorkspaceTarget } from '@features/workspace/store/workspace-restore-store';
 
@@ -15,6 +16,6 @@ export function setWorkspaceRestoreStatus(status: 'restoring' | 'restored' | 'un
 }
 
 /** Application bootstrap contract; keeps startup imports isolated from the use-case module graph. */
-export async function restoreAgentConversationWorkspace(): Promise<void> {
-  await restore();
+export async function restoreAgentConversationWorkspace(restoreRequestId?: number): Promise<void> {
+  await restore(restoreRequestId);
 }
diff --git a/app/flowix-web/features/workspace/public/surface-api.ts b/app/flowix-web/features/workspace/public/surface-api.ts
new file mode 100644
index 000000000..3282950fd
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/surface-api.ts
@@ -0,0 +1,21 @@
+/** Shared surface support and routing metadata for Work and Browser hosts. */
+export {
+  resolveWorkspaceFileSurfaceKind,
+  workspaceFileSurfaceKind,
+  workspaceFileSurfaceSupportsHost,
+  workspaceSurfaceCapabilities,
+  workspaceSurfaceAppearance,
+  workspaceSurfaceRegistry,
+  workspaceSurfaceSupportsHost,
+} from '../surface-registry';
+export type {
+  WorkspaceFileSurfaceKind,
+  WorkspaceSurfaceCapability,
+  WorkspaceSurfaceHost,
+  WorkspaceSurfaceKind,
+} from '../surface-registry';
+
+export type * from '../model/surface-contract';
+export type * from '../model/surface-target';
+export type { ContentIdentity, WorkspaceSurfaceIdentity } from '../model/surface-identity';
+export { contentIdentityKey, workspaceSurfaceIdentityKey } from '../model/surface-identity';
diff --git a/app/flowix-web/features/workspace/public/surface-lifecycle-api.ts b/app/flowix-web/features/workspace/public/surface-lifecycle-api.ts
new file mode 100644
index 000000000..1382419df
--- /dev/null
+++ b/app/flowix-web/features/workspace/public/surface-lifecycle-api.ts
@@ -0,0 +1,8 @@
+export {
+  getWorkspaceSurfaceLifecycle,
+  getWorkspaceHostSurfaceLifecycle,
+  registerWorkspaceSurfaceHostView,
+  registerWorkspaceSurfaceLifecycle,
+  subscribeWorkspaceSurfaceLifecycle,
+} from '../store/surface-lifecycle-store';
+export type { SurfaceLifecycle } from '../model/surface-contract';
diff --git a/app/flowix-web/features/workspace/store/browser-column-store.test.ts b/app/flowix-web/features/workspace/store/browser-column-store.test.ts
index ceaab3b5a..d4165110e 100644
--- a/app/flowix-web/features/workspace/store/browser-column-store.test.ts
+++ b/app/flowix-web/features/workspace/store/browser-column-store.test.ts
@@ -6,7 +6,7 @@ import {
 } from './browser-column-store';
 import { useWorkspaceFocusStore } from './workspace-focus-store';
 
-function tab(id: string, memoId = id) {
+function tab(id: string, fileStem = id) {
   return {
     id,
     title: `${id}.md`,
@@ -18,7 +18,7 @@ function tab(id: string, memoId = id) {
       scopePath: '/notes',
       fileTreeVisible: true,
       fileTreeWidth: 220,
-      activeFilePath: `/notes/${memoId}.md`,
+      activeFilePath: `/notes/${fileStem}.md`,
     },
   };
 }
@@ -49,12 +49,12 @@ describe('browser column store', () => {
 
   it('focuses an existing target instead of duplicating it by default', () => {
     const store = useBrowserColumnStore.getState();
-    store.openTab(tab('memo:a', 'a'));
-    store.openTab(tab('memo:a:second', 'a'));
+    store.openTab(tab('note:a', 'a'));
+    store.openTab(tab('note:a:second', 'a'));
 
     expect(useBrowserColumnStore.getState()).toMatchObject({
-      tabs: [{ ...tab('memo:a', 'a'), title: 'memo:a:second.md' }],
-      activeTabId: 'memo:a',
+      tabs: [{ ...tab('note:a', 'a'), title: 'note:a:second.md' }],
+      activeTabId: 'note:a',
       visible: true,
     });
     expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
@@ -84,10 +84,10 @@ describe('browser column store', () => {
 
   it('reuses an existing target when replace-active would otherwise duplicate it', () => {
     const store = useBrowserColumnStore.getState();
-    store.openTab(tab('memo:a', 'a'));
-    store.openTab(tab('memo:b', 'b'));
+    store.openTab(tab('note:a', 'a'));
+    store.openTab(tab('note:b', 'b'));
 
-    store.openTab(tab('memo:a:replacement', 'a'), 'replace-active');
+    store.openTab(tab('note:a:replacement', 'a'), 'replace-active');
 
     expect(useBrowserColumnStore.getState().tabs.map((item) => item.id)).toEqual(['memo:a']);
     expect(useBrowserColumnStore.getState().activeTabId).toBe('memo:a');
@@ -240,8 +240,8 @@ describe('browser column store', () => {
 
   it('removes a file tab by path when the note is deleted', () => {
     const store = useBrowserColumnStore.getState();
-    store.openTab(tab('memo:a', 'a'));
-    store.openTab(tab('memo:b', 'b'));
+    store.openTab(tab('note:a', 'a'));
+    store.openTab(tab('note:b', 'b'));
 
     expect(store.removeTabsByFilePath('/notes/a.md')).toEqual(['memo:a']);
     expect(useBrowserColumnStore.getState().tabs.map((item) => item.id)).toEqual(['memo:b']);
diff --git a/app/flowix-web/features/workspace/store/browser-column-store.ts b/app/flowix-web/features/workspace/store/browser-column-store.ts
index 45a62bdd8..0be8f642f 100644
--- a/app/flowix-web/features/workspace/store/browser-column-store.ts
+++ b/app/flowix-web/features/workspace/store/browser-column-store.ts
@@ -1,8 +1,10 @@
+import { resolveWorkspaceFileSurfaceKind, workspaceSurfaceSupportsHost } from '../surface-registry';
+import { createWorkspaceWebRuntime, navigateWorkspaceWebRuntime, moveWorkspaceWebHistory, reloadWorkspaceWebRuntime } from '../model/web-navigation';
 import type { FileBrowserContext, FileBrowserTarget } from './file-browser-target';
 import { create } from 'zustand';
 import { createJSONStorage, persist } from 'zustand/middleware';
 import { STORAGE_KEYS } from '@/lib/constants';
-import { canonicalPath } from '@/lib/path';
+import { canonicalPath, canonicalDirectoryPath, isPathInDirectory, parentDirectoryPath } from '@/lib/path';
 import { displayTitleFromFilename } from '@/lib/utils';
 import {
   canonicalUrl,
@@ -12,6 +14,13 @@ import {
 import { useWorkspaceFocusStore } from './workspace-focus-store';
 
 export type BrowserColumnTarget =
+  | {
+      kind: 'folder-collection';
+      folderPath: string;
+      notebookId: string;
+      notebookPath: string;
+      folderName: string;
+    }
   | {
       kind: 'media';
       filePath: string;
@@ -29,12 +38,22 @@ export type BrowserColumnTarget =
       instanceId: string;
     };
 
-/** Only targets with a usable work-column surface can be moved there. */
-export function canMoveBrowserColumnTargetToWorkColumn(target: BrowserColumnTarget): boolean {
-  return target.kind !== 'web'
-    && (target.kind !== 'file-browser' || Boolean(target.activeFilePath));
+/** Opening in Work uses the same public support declaration as normal navigation. */
+export function canOpenBrowserColumnTargetInWorkColumn(target: BrowserColumnTarget): boolean {
+  if (target.kind === 'file-browser') {
+    if (!target.activeFilePath) return false;
+    const fileKind = target.collectionType === 'table' ? 'table'
+      : target.collectionType === 'media_library' ? 'media-library'
+      : resolveWorkspaceFileSurfaceKind(target.activeFilePath);
+    return workspaceSurfaceSupportsHost(`file-${fileKind}`, 'main-third');
+  }
+  return workspaceSurfaceSupportsHost(target.kind === 'agent_conversation' ? 'agent-conversation'
+    : target.kind === 'folder-collection' ? 'collection' : target.kind, 'main-third');
 }
 
+/** Compatibility name for callers from before dual-host views were supported. */
+export const canMoveBrowserColumnTargetToWorkColumn = canOpenBrowserColumnTargetInWorkColumn;
+
 export interface BrowserColumnTab {
   id: string;
   title: string;
@@ -43,18 +62,13 @@ export interface BrowserColumnTab {
 }
 
 /** Runtime-only state for a web tab. It is intentionally not persisted with tabs. */
-export interface BrowserColumnWebRuntime {
-  currentUrl: string;
-  history: string[];
-  historyIndex: number;
-  reloadToken: number;
-  isLoading: boolean;
-  error: string | null;
-}
+export type { WorkspaceWebRuntime as BrowserColumnWebRuntime } from '../model/surface-contract';
+import type { WorkspaceWebRuntime as BrowserColumnWebRuntime } from '../model/surface-contract';
 
 export type BrowserColumnWebNavigationPhase = 'navigating' | 'started' | 'finished';
 
-export type BrowserColumnOpenDisposition = 'focus-existing' | 'replace-active' | 'open-in-column';
+import type { BrowserSurfaceOpenDisposition } from '../model/surface-opening';
+export type BrowserColumnOpenDisposition = BrowserSurfaceOpenDisposition;
 
 interface BrowserColumnState {
   visible: boolean;
@@ -65,7 +79,7 @@ interface BrowserColumnState {
   setVisible: (visible: boolean) => void;
   setSplitRatio: (ratio: number) => void;
   updateFileBrowserContext: (tabId: string, patch: Partial<FileBrowserContext>) => void;
-  selectFileBrowserFile: (tabId: string, filePath: string | null, collectionDisplay?: FileBrowserTarget['collectionDisplay'], collectionType?: FileBrowserTarget['collectionType']) => void;
+  selectFileBrowserFile: (tabId: string, filePath: string | null, collectionDisplay?: FileBrowserTarget['collectionDisplay'], collectionType?: FileBrowserTarget['collectionType'], collectionUnavailableReason?: string) => void;
   switchFileBrowserFolder: (tabId: string, folderPath: string) => void;
   setFileBrowserTreeVisible: (tabId: string, visible: boolean) => void;
   setFileBrowserTreeWidth: (tabId: string, width: number) => void;
@@ -77,6 +91,7 @@ interface BrowserColumnState {
   closeAllTabs: () => void;
   replaceExternalPath: (previousPath: string, path: string) => void;
   clearExternalPath: (path: string) => void;
+  clearTargetsUnderDirectory: (directoryPath: string) => void;
   removeTabsByFilePath: (path: string) => string[];
   reorderTab: (tabId: string, beforeTabId: string | null) => void;
   updateTabMetadata: (tabId: string, metadata: Partial<Pick<BrowserColumnTab, 'title' | 'icon'>>) => void;
@@ -102,6 +117,7 @@ export const BROWSER_COLUMN_FILE_TREE_MAX_WIDTH = 420;
 
 export function browserColumnTargetIdentity(target: BrowserColumnTarget): ContentIdentity {
   switch (target.kind) {
+    case 'folder-collection': return { kind: 'folder-collection', notebookId: target.notebookId, folderPath: target.folderPath };
     case 'media': return { kind: 'media', path: target.filePath };
     case 'file-browser': return target.collectionDisplay ? { kind: 'collection', ...target.collectionDisplay } : target.activeFilePath
       ? { kind: 'external', path: target.activeFilePath }
@@ -140,17 +156,6 @@ function clampFileTreeWidth(width: number): number {
     : BROWSER_COLUMN_FILE_TREE_DEFAULT_WIDTH;
 }
 
-function initialWebRuntime(url: string): BrowserColumnWebRuntime {
-  return {
-    currentUrl: url,
-    history: [url],
-    historyIndex: 0,
-    reloadToken: 0,
-    isLoading: false,
-    error: null,
-  };
-}
-
 function isWebTab(tab: BrowserColumnTab | undefined): tab is BrowserColumnTab & {
   target: Extract<BrowserColumnTarget, { kind: 'web' }>;
 } {
@@ -162,7 +167,7 @@ function withWebRuntime(
   tab: BrowserColumnTab | undefined,
 ): BrowserColumnWebRuntime | null {
   if (!isWebTab(tab)) return null;
-  return runtimes[tab.id] ?? initialWebRuntime(tab.target.url);
+  return runtimes[tab.id] ?? createWorkspaceWebRuntime(tab.target.url);
 }
 
 function updateWebTabTarget(
@@ -181,9 +186,10 @@ function updateFileBrowserTabTarget(
   filePath: string | null,
   collectionDisplay?: FileBrowserTarget['collectionDisplay'],
   collectionType?: FileBrowserTarget['collectionType'],
+  collectionUnavailableReason?: string,
 ): BrowserColumnTab[] {
   return tabs.map((tab) => tab.id === tabId && tab.target.kind === 'file-browser'
-    ? { ...tab, title: filePath ? displayTitleFromFilename(filePath.split(/[\\/]/).pop() ?? filePath) : tab.title, target: { ...tab.target, activeFilePath: filePath, collectionDisplay, collectionType, collectionUnavailableReason: undefined } }
+    ? { ...tab, title: filePath ? displayTitleFromFilename(filePath.split(/[\\/]/).pop() ?? filePath) : tab.title, target: { ...tab.target, activeFilePath: filePath, collectionDisplay, collectionType, collectionUnavailableReason } }
     : tab);
 }
 
@@ -232,6 +238,12 @@ function parseBrowserColumnTarget(value: unknown): BrowserColumnTarget | null {
   if (!isRecord(value) || typeof value.kind !== 'string') return null;
 
   switch (value.kind) {
+    case 'folder-collection':
+      return nonEmptyString(value.folderPath) && nonEmptyString(value.notebookId)
+        && nonEmptyString(value.notebookPath) && typeof value.folderName === 'string'
+        ? { kind: 'folder-collection', folderPath: value.folderPath, notebookId: value.notebookId,
+            notebookPath: value.notebookPath, folderName: value.folderName }
+        : null;
     case 'media':
       return nonEmptyString(value.filePath)
         && typeof value.notebookId === 'string'
@@ -432,10 +444,10 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
       updateFileBrowserContext: (tabId, patch) => {
         set({ tabs: updateFileBrowserTabTree(get().tabs, tabId, patch) });
       },
-      selectFileBrowserFile: (tabId, filePath, collectionDisplay, collectionType) => {
+      selectFileBrowserFile: (tabId, filePath, collectionDisplay, collectionType, collectionUnavailableReason) => {
         const tab = get().tabs.find((candidate) => candidate.id === tabId);
         if (!tab || tab.target.kind !== 'file-browser') return;
-        set({ tabs: updateFileBrowserTabTarget(get().tabs, tabId, filePath, collectionDisplay, collectionType) });
+        set({ tabs: updateFileBrowserTabTarget(get().tabs, tabId, filePath, collectionDisplay, collectionType, collectionUnavailableReason) });
       },
       switchFileBrowserFolder: (tabId, folderPath) => {
         if (!folderPath.trim()) return;
@@ -466,7 +478,7 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
             : updatedTabs;
           const webRuntimes = { ...state.webRuntimes };
           if (isWebTab(existing)) {
-            webRuntimes[existing.id] ??= initialWebRuntime(existing.target.url);
+            webRuntimes[existing.id] ??= createWorkspaceWebRuntime(existing.target.url);
           } else {
             delete webRuntimes[existing.id];
           }
@@ -489,7 +501,7 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
           delete webRuntimes[state.activeTabId];
         }
         if (isWebTab(tab)) {
-          webRuntimes[id] = initialWebRuntime(tab.target.url);
+          webRuntimes[id] = createWorkspaceWebRuntime(tab.target.url);
         }
         useWorkspaceFocusStore.getState().focusHost('browser-column');
         set({
@@ -607,6 +619,70 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
             : tab),
         }));
       },
+      clearTargetsUnderDirectory: (directoryPath) => {
+        const directory = canonicalDirectoryPath(directoryPath);
+        const state = get();
+        const removedIds = new Set<string>();
+        let changed = false;
+        const tabs = state.tabs.flatMap((tab) => {
+          const target = tab.target;
+          if (target.kind === 'media' && isPathInDirectory(target.filePath, directory)) {
+            changed = true;
+            removedIds.add(tab.id);
+            return [];
+          }
+          if (target.kind === 'folder-collection' && isPathInDirectory(target.folderPath, directory)) {
+            changed = true;
+            removedIds.add(tab.id);
+            return [];
+          }
+          if (target.kind !== 'file-browser') return [tab];
+
+          const activeFileRemoved = Boolean(
+            target.activeFilePath && isPathInDirectory(target.activeFilePath, directory),
+          );
+          const folderRemoved = Boolean(
+            target.folderPath && isPathInDirectory(target.folderPath, directory),
+          );
+          if (!activeFileRemoved && !folderRemoved) return [tab];
+
+          changed = true;
+          const folderPath = folderRemoved
+            ? parentDirectoryPath(directory, directory)
+            : target.folderPath;
+          const folderName = folderPath?.split(/[\\/]/).filter(Boolean).pop() ?? '';
+          return [{
+            ...tab,
+            title: displayTitleFromFilename(folderName),
+            target: {
+              ...target,
+              folderPath,
+              activeFilePath: activeFileRemoved ? null : target.activeFilePath,
+              collectionDisplay: activeFileRemoved ? undefined : target.collectionDisplay,
+              collectionType: activeFileRemoved ? undefined : target.collectionType,
+              collectionUnavailableReason: activeFileRemoved ? undefined : target.collectionUnavailableReason,
+            },
+          }];
+        });
+        if (!changed) return;
+
+        const activeWasRemoved = state.activeTabId !== null && removedIds.has(state.activeTabId);
+        const activeIndex = state.tabs.findIndex((tab) => tab.id === state.activeTabId);
+        const activeTabId = activeWasRemoved
+          ? tabs[activeIndex - 1]?.id ?? tabs[activeIndex]?.id ?? null
+          : state.activeTabId;
+        const webRuntimes = Object.fromEntries(
+          tabs
+            .filter((tab) => state.webRuntimes[tab.id])
+            .map((tab) => [tab.id, state.webRuntimes[tab.id]]),
+        );
+        if (activeWasRemoved) {
+          useWorkspaceFocusStore.getState().focusHost(
+            tabs.length > 0 ? 'browser-column' : 'main-third',
+          );
+        }
+        set({ tabs, activeTabId, visible: tabs.length > 0 && state.visible, webRuntimes });
+      },
       removeTabsByFilePath: (path) => {
         const targetPath = canonicalPath(path);
         if (!targetPath) return [];
@@ -711,22 +787,10 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
         const tab = state.tabs.find((candidate) => candidate.id === tabId);
         const current = withWebRuntime(state.webRuntimes, tab);
         if (!current || !isWebTab(tab)) return false;
-        const history = current.history.slice(0, current.historyIndex + 1);
-        if (history[history.length - 1] !== normalized) history.push(normalized);
+        const runtime = navigateWorkspaceWebRuntime(current, normalized);
         set({
-          tabs: updateWebTabTarget(state.tabs, tabId, normalized),
-          webRuntimes: {
-            ...state.webRuntimes,
-            [tabId]: {
-              ...current,
-              currentUrl: normalized,
-              history,
-              historyIndex: history.length - 1,
-              reloadToken: current.reloadToken + 1,
-              isLoading: true,
-              error: null,
-            },
-          },
+          tabs: updateWebTabTarget(state.tabs, tabId, runtime.currentUrl),
+          webRuntimes: { ...state.webRuntimes, [tabId]: runtime },
         });
         return true;
       },
@@ -734,21 +798,11 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
         const state = get();
         const tab = state.tabs.find((candidate) => candidate.id === tabId);
         const current = withWebRuntime(state.webRuntimes, tab);
-        if (!current || current.historyIndex <= 0) return false;
-        const historyIndex = current.historyIndex - 1;
+        const runtime = current ? moveWorkspaceWebHistory(current, -1) : null;
+        if (!runtime) return false;
         set({
-          tabs: updateWebTabTarget(state.tabs, tabId, current.history[historyIndex]),
-          webRuntimes: {
-            ...state.webRuntimes,
-            [tabId]: {
-              ...current,
-              currentUrl: current.history[historyIndex],
-              historyIndex,
-              reloadToken: current.reloadToken + 1,
-              isLoading: true,
-              error: null,
-            },
-          },
+          tabs: updateWebTabTarget(state.tabs, tabId, runtime.currentUrl),
+          webRuntimes: { ...state.webRuntimes, [tabId]: runtime },
         });
         return true;
       },
@@ -756,21 +810,11 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
         const state = get();
         const tab = state.tabs.find((candidate) => candidate.id === tabId);
         const current = withWebRuntime(state.webRuntimes, tab);
-        if (!current || current.historyIndex >= current.history.length - 1) return false;
-        const historyIndex = current.historyIndex + 1;
+        const runtime = current ? moveWorkspaceWebHistory(current, 1) : null;
+        if (!runtime) return false;
         set({
-          tabs: updateWebTabTarget(state.tabs, tabId, current.history[historyIndex]),
-          webRuntimes: {
-            ...state.webRuntimes,
-            [tabId]: {
-              ...current,
-              currentUrl: current.history[historyIndex],
-              historyIndex,
-              reloadToken: current.reloadToken + 1,
-              isLoading: true,
-              error: null,
-            },
-          },
+          tabs: updateWebTabTarget(state.tabs, tabId, runtime.currentUrl),
+          webRuntimes: { ...state.webRuntimes, [tabId]: runtime },
         });
         return true;
       },
@@ -779,17 +823,7 @@ export const useBrowserColumnStore = create<BrowserColumnState>()(
         const tab = state.tabs.find((candidate) => candidate.id === tabId);
         const current = withWebRuntime(state.webRuntimes, tab);
         if (!current) return false;
-        set({
-          webRuntimes: {
-            ...state.webRuntimes,
-            [tabId]: {
-              ...current,
-              reloadToken: current.reloadToken + 1,
-              isLoading: true,
-              error: null,
-            },
-          },
-        });
+        set({ webRuntimes: { ...state.webRuntimes, [tabId]: reloadWorkspaceWebRuntime(current) } });
         return true;
       },
       reset: () => {
diff --git a/app/flowix-web/features/workspace/store/file-browser-target.ts b/app/flowix-web/features/workspace/store/file-browser-target.ts
index d704d2bb3..377855757 100644
--- a/app/flowix-web/features/workspace/store/file-browser-target.ts
+++ b/app/flowix-web/features/workspace/store/file-browser-target.ts
@@ -1,23 +1,5 @@
-import type { CollectionDisplayDescriptor } from '@/lib/collection-display-registry';
 import { canonicalPath } from '@/lib/path';
-
-export interface FileBrowserContext {
-  /** Only legacy tabs lack a notebook binding; bind them once when restored. */
-  restoreNotebookContext?: boolean;
-  folderPath: string | null;
-  notebookId: string | null;
-  scopePath: string | null;
-  fileTreeVisible: boolean;
-  fileTreeWidth: number;
-}
-
-export interface FileBrowserTarget extends FileBrowserContext {
-  kind: 'file-browser';
-  activeFilePath: string | null;
-  collectionDisplay?: CollectionDisplayDescriptor;
-  collectionType?: 'table' | 'media_library';
-  collectionUnavailableReason?: string;
-}
+export type { FileBrowserContext, FileBrowserTarget } from '../model/surface-target';
 
 /** Longest directory-boundary match; preserve filesystem case semantics. */
 export function resolveFileBrowserRoot(path: string | null, folders: readonly string[]): string | null {
diff --git a/app/flowix-web/features/workspace/store/surface-lifecycle-store.test.ts b/app/flowix-web/features/workspace/store/surface-lifecycle-store.test.ts
new file mode 100644
index 000000000..ad7eb8fca
--- /dev/null
+++ b/app/flowix-web/features/workspace/store/surface-lifecycle-store.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getWorkspaceSurfaceLifecycle, registerWorkspaceSurfaceLifecycle, registerWorkspaceSurfaceHostView, getWorkspaceHostSurfaceLifecycle } from './surface-lifecycle-store';
+
+describe('surface lifecycle ownership', () => {
+  it('keeps the replacement editor when an old editor releases its registration', () => {
+    const oldOwner = {};
+    const newOwner = {};
+    const disposeOld = vi.fn();
+    const replacement = { status: 'ready' as const, flush: vi.fn().mockResolvedValue(true) };
+    registerWorkspaceSurfaceLifecycle('replacement-view', { status: 'ready', dispose: disposeOld }, oldOwner);
+    registerWorkspaceSurfaceLifecycle('replacement-view', replacement, newOwner);
+    registerWorkspaceSurfaceLifecycle('replacement-view', null, oldOwner);
+    expect(getWorkspaceSurfaceLifecycle('replacement-view')).toBe(replacement);
+    expect(disposeOld).toHaveBeenCalledOnce();
+    registerWorkspaceSurfaceLifecycle('replacement-view', null, newOwner);
+    expect(getWorkspaceSurfaceLifecycle('replacement-view')).toBeNull();
+  });
+
+  it('keeps independent Work and Browser lifecycles for the same content', () => {
+    const owner = {};
+    const work = { status: 'ready' as const, flush: vi.fn().mockResolvedValue(true) };
+    const browser = { status: 'ready' as const, flush: vi.fn().mockResolvedValue(false) };
+    registerWorkspaceSurfaceLifecycle('work:content', work, owner);
+    registerWorkspaceSurfaceLifecycle('browser:content', browser, owner);
+    registerWorkspaceSurfaceLifecycle('work:content', null, owner);
+    expect(getWorkspaceSurfaceLifecycle('browser:content')).toBe(browser);
+    registerWorkspaceSurfaceLifecycle('browser:content', null, owner);
+  });
+});
+
+it('keeps the mounted host view when the old view cleans up after a replacement', () => {
+  const old = registerWorkspaceSurfaceHostView('main-third', 'old-view');
+  const current = registerWorkspaceSurfaceHostView('main-third', 'current-view');
+  const lifecycle = { status: 'ready' as const, flush: vi.fn().mockResolvedValue(true) };
+  registerWorkspaceSurfaceLifecycle('current-view', lifecycle);
+  old();
+  expect(getWorkspaceHostSurfaceLifecycle('main-third')).toBe(lifecycle);
+  current();
+  expect(getWorkspaceHostSurfaceLifecycle('main-third')).toBeNull();
+  registerWorkspaceSurfaceLifecycle('current-view', null);
+});
diff --git a/app/flowix-web/features/workspace/store/surface-lifecycle-store.ts b/app/flowix-web/features/workspace/store/surface-lifecycle-store.ts
new file mode 100644
index 000000000..3a9ad7778
--- /dev/null
+++ b/app/flowix-web/features/workspace/store/surface-lifecycle-store.ts
@@ -0,0 +1,60 @@
+import type { SurfaceLifecycle, WorkspaceSurfaceHost } from '../model/surface-contract';
+
+const defaultOwner = {};
+const lifecycles = new Map<string, { owner: object; lifecycle: SurfaceLifecycle }>();
+const subscribers = new Map<string, Set<() => void>>();
+const hostViews = new Map<WorkspaceSurfaceHost, { viewId: string }>();
+
+/** Hosts identify the mounted view; navigation need not reconstruct renderer IDs. */
+export function registerWorkspaceSurfaceHostView(host: WorkspaceSurfaceHost, viewId: string): () => void {
+  const registration = { viewId };
+  hostViews.set(host, registration);
+  return () => {
+    if (hostViews.get(host) === registration) hostViews.delete(host);
+  };
+}
+
+export function getWorkspaceHostSurfaceLifecycle(host: WorkspaceSurfaceHost): SurfaceLifecycle | null {
+  const view = hostViews.get(host);
+  return view ? getWorkspaceSurfaceLifecycle(view.viewId) : null;
+}
+
+function emit(viewId: string) {
+  subscribers.get(viewId)?.forEach((listener) => listener());
+}
+
+/** Register or remove the live lifecycle handlers owned by one surface view. */
+export function registerWorkspaceSurfaceLifecycle(viewId: string, lifecycle: SurfaceLifecycle | null, owner: object = defaultOwner): void {
+  const previous = lifecycles.get(viewId);
+  if (lifecycle === null) {
+    if (!previous || previous.owner !== owner) return;
+    lifecycles.delete(viewId);
+    try { previous.lifecycle.dispose?.(); }
+    finally { emit(viewId); }
+    return;
+  }
+  if (previous?.lifecycle === lifecycle && previous.owner === owner) return;
+  lifecycles.set(viewId, { owner, lifecycle });
+  try {
+    if (previous && previous.owner !== owner) previous.lifecycle.dispose?.();
+  } finally { emit(viewId); }
+}
+
+export function getWorkspaceSurfaceLifecycle(viewId: string): SurfaceLifecycle | null {
+  return lifecycles.get(viewId)?.lifecycle ?? null;
+}
+
+export function subscribeWorkspaceSurfaceLifecycle(viewId: string, listener: () => void): () => void {
+  const viewSubscribers = subscribers.get(viewId) ?? new Set<() => void>();
+  viewSubscribers.add(listener);
+  subscribers.set(viewId, viewSubscribers);
+  return () => {
+    viewSubscribers.delete(listener);
+    if (viewSubscribers.size === 0) subscribers.delete(viewId);
+  };
+}
+
+/** Snapshot all mounted surfaces, including background/browser-column views. */
+export function listWorkspaceSurfaceLifecycles(): SurfaceLifecycle[] {
+  return [...new Set([...lifecycles.values()].map(entry => entry.lifecycle))];
+}
diff --git a/app/flowix-web/features/workspace/store/work-column-target.ts b/app/flowix-web/features/workspace/store/work-column-target.ts
index 19dcd5433..d7497dfce 100644
--- a/app/flowix-web/features/workspace/store/work-column-target.ts
+++ b/app/flowix-web/features/workspace/store/work-column-target.ts
@@ -1,99 +1,11 @@
-import type { FileBrowserContext } from './file-browser-target';
-import type { PluginDescriptor } from '@platform/tauri/client';
-import { canonicalPath } from '@/lib/path';
-
-export type DocumentListScope = {
-  kind: 'folder';
-  path: string;
-  notebookPath: string;
-  notebookId: string | null;
-};
-
-export type DocumentListFilters = {
-  resourceKinds?: string[];
-  tags?: string[];
-  customFilterId?: string;
-};
-
-export type DocumentListTarget = {
-  kind: 'document-list';
-  displayId: string;
-  scope: DocumentListScope;
-  filters: DocumentListFilters;
-};
-
-/** Stable identity for a folder list and its active filter set. */
-export function createDocumentListTarget(
-  scope: DocumentListScope,
-  filters: DocumentListFilters,
-): DocumentListTarget {
-  const normalizedScope = {
-    ...scope,
-    path: canonicalPath(scope.path),
-    notebookPath: canonicalPath(scope.notebookPath),
-  };
-  const normalizedFilters: DocumentListFilters = {
-    ...(filters.resourceKinds ? { resourceKinds: [...new Set(filters.resourceKinds)].sort() } : {}),
-    ...(filters.tags ? { tags: [...new Set(filters.tags)].sort() } : {}),
-    ...(filters.customFilterId ? { customFilterId: filters.customFilterId } : {}),
-  };
-  const displayId = `document-list:${JSON.stringify([
-    normalizedScope.path,
-    normalizedScope.notebookPath,
-    normalizedScope.notebookId,
-    normalizedFilters,
-  ])}`;
-  return { kind: 'document-list', displayId, scope: normalizedScope, filters: normalizedFilters };
-}
-
-/**
- * The stable target currently owned by the workColumn.
- *
- * The selected notebook remains in NoteLibraryStore; folder-list destinations are
- * explicit targets so they can be restored independently of that selection.
- */
-export interface CollectionWorkspaceTarget {
-  kind: 'collection';
-  displayId: string;
-  notebookId: string;
-  collectionId: string;
-  viewId: string | null;
-  collectionType: 'table' | 'media_library';
-  filePath: string;
-  notebookPath: string;
-  name: string;
-  unavailableReason?: string;
-}
-
-export type WorkColumnTarget =
-  | { kind: 'empty' }
-  | CollectionWorkspaceTarget
-  | DocumentListTarget
-  | {
-      kind: 'external';
-      fileBrowser?: FileBrowserContext;
-      path: string;
-      scopePath: string | null;
-      transitionId: number | null;
-    }
-  | { kind: 'table'; filePath: string; notebookPath: string | null; notebookId: string | null }
-  | {
-      kind: 'media';
-      filePath: string;
-      notebookId: string | null;
-      notebookPath: string | null;
-      resourceKind: 'image' | 'video';
-    }
-  | { kind: 'media-library'; filePath: string; notebookPath: string | null; notebookId: string | null }
-  | {
-      kind: 'agent-conversation';
-      instanceId: string;
-      /** A temporary empty draft should restore as an empty work column if it has vanished. */
-      blankIfMissing?: true;
-    }
-  /** View identity only. Plugin run state and artifacts live in host stores. */
-  | { kind: 'plugin-workbench'; plugin: PluginDescriptor }
-  | { kind: 'web'; url: string };
+import type {
+  CollectionSurfaceTarget, WorkspaceContentTarget,
+} from '../model/surface-target';
+export type CollectionWorkspaceTarget = CollectionSurfaceTarget;
+
+/** Stored Work targets require the transaction ID which is optional at the public boundary. */
+export type WorkColumnTarget = Exclude<WorkspaceContentTarget, { kind: 'external' }>
+  | (Extract<WorkspaceContentTarget, { kind: 'external' }> & { transitionId: number | null });
 
 /** Local file path for the last successfully committed workColumn target. */
 export function workColumnTargetFilePath(target: WorkColumnTarget): string | null {
diff --git a/app/flowix-web/features/workspace/store/workspace-content-identity.ts b/app/flowix-web/features/workspace/store/workspace-content-identity.ts
index e92e006fd..43e2ab047 100644
--- a/app/flowix-web/features/workspace/store/workspace-content-identity.ts
+++ b/app/flowix-web/features/workspace/store/workspace-content-identity.ts
@@ -1,47 +1,3 @@
-import { canonicalPath, fileLocatorKey } from '@/lib/path';
-import { canonicalUrl } from '@/lib/url';
-
-export { canonicalUrl } from '@/lib/url';
-
-/**
- * Stable identity for content that can be opened by either workspace host.
- *
- * Paths and URLs deliberately have different normalizers. `canonicalPath`
- * collapses repeated slashes, which is correct for filesystem paths but would
- * corrupt the `//` in an URL scheme.
- */
-export type ContentIdentity =
-  | { kind: 'collection'; notebookId: string; collectionId: string; viewId: string | null }
-  | { kind: 'media'; path: string }
-  | { kind: 'external'; path: string }
-  | { kind: 'file-browser'; folderPath: string }
-  | { kind: 'web'; url: string }
-  | { kind: 'agent-conversation'; instanceId: string };
-
-export function contentIdentityKey(
-  identity: ContentIdentity,
-): string | null {
-  switch (identity.kind) {
-    case 'collection': return `collection:${JSON.stringify([identity.notebookId, identity.collectionId])}`;
-    case 'media': {
-      const path = identity.path;
-      return path.trim() ? fileLocatorKey(path) : null;
-    }
-    case 'external': {
-      const path = identity.path;
-      return path.trim() ? fileLocatorKey(path) : null;
-    }
-    case 'file-browser': {
-      const folderPath = identity.folderPath.trim();
-      return folderPath ? `file-browser:${canonicalPath(folderPath)}` : null;
-    }
-    case 'web': {
-      const url = canonicalUrl(identity.url);
-      return url ? `web:${url}` : null;
-    }
-    case 'agent-conversation': {
-      const instanceId = identity.instanceId.trim();
-      return instanceId ? `agent:${instanceId}` : null;
-    }
-  }
-}
+/** Compatibility seam: content identity belongs to the shared surface model. */
+export { canonicalUrl, contentIdentityKey } from '../model/surface-identity';
+export type { ContentIdentity } from '../model/surface-identity';
diff --git a/app/flowix-web/features/workspace/store/workspace-focus-store.ts b/app/flowix-web/features/workspace/store/workspace-focus-store.ts
index a3c33b5bb..8e6673ace 100644
--- a/app/flowix-web/features/workspace/store/workspace-focus-store.ts
+++ b/app/flowix-web/features/workspace/store/workspace-focus-store.ts
@@ -1,6 +1,7 @@
 import { create } from 'zustand';
+import type { WorkspaceHostId } from '@features/workspace/public/host-api';
 
-export type WorkspaceHostId = 'main-third' | 'browser-column';
+export type { WorkspaceHostId } from '@features/workspace/public/host-api';
 
 interface WorkspaceFocusState {
   focusedHostId: WorkspaceHostId;
@@ -10,6 +11,8 @@ interface WorkspaceFocusState {
 
 export const useWorkspaceFocusStore = create<WorkspaceFocusState>((set) => ({
   focusedHostId: 'main-third',
-  focusHost: (focusedHostId) => set({ focusedHostId }),
+  focusHost: (focusedHostId) => set((state) => (
+    state.focusedHostId === focusedHostId ? state : { focusedHostId }
+  )),
   reset: () => set({ focusedHostId: 'main-third' }),
 }));
diff --git a/app/flowix-web/features/workspace/store/workspace-restore-store.ts b/app/flowix-web/features/workspace/store/workspace-restore-store.ts
index c9457cd0a..099f799d5 100644
--- a/app/flowix-web/features/workspace/store/workspace-restore-store.ts
+++ b/app/flowix-web/features/workspace/store/workspace-restore-store.ts
@@ -2,7 +2,9 @@ import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
 
 import { STORAGE_KEYS } from '@/lib/constants';
-import type { CollectionWorkspaceTarget, DocumentListTarget } from './work-column-target';
+import type { CollectionWorkspaceTarget } from './work-column-target';
+import type { FolderCollectionSurfaceTarget } from '../model/surface-target';
+import type { LegacyFolderListTarget } from '../model/legacy-folder-list';
 
 interface AgentConversationRestoreState {
   selectedInstanceId: string | null;
@@ -11,7 +13,8 @@ interface AgentConversationRestoreState {
 
 export type PersistedWorkspaceTarget =
   | CollectionWorkspaceTarget
-  | DocumentListTarget
+  | FolderCollectionSurfaceTarget
+  | LegacyFolderListTarget
   | { kind: 'external'; path: string; scopePath: string | null }
   | { kind: 'table'; filePath: string; notebookPath: string | null; notebookId: string | null }
   | {
diff --git a/app/flowix-web/features/workspace/surface-registry.ts b/app/flowix-web/features/workspace/surface-registry.ts
new file mode 100644
index 000000000..ac28f6db4
--- /dev/null
+++ b/app/flowix-web/features/workspace/surface-registry.ts
@@ -0,0 +1,107 @@
+import { externalFileViewKind } from '@features/editor/public/code-file';
+
+import type {
+  WorkspaceSurfaceHost, WorkspaceSurfaceCapability, WorkspaceFileSurfaceKind, WorkspaceSurfaceKind,
+  SurfaceAppearance,
+} from './model/surface-contract';
+export type {
+  WorkspaceSurfaceHost, WorkspaceSurfaceCapability, WorkspaceFileSurfaceKind, WorkspaceSurfaceKind,
+} from './model/surface-contract';
+
+type SurfaceRegistration = {
+  /** Stable implementation ID; the UI layer supplies its lazy component. */
+  rendererId: string;
+  hosts: readonly WorkspaceSurfaceHost[];
+  capabilities: readonly WorkspaceSurfaceCapability[];
+  appearance: SurfaceAppearance;
+};
+
+const DOCUMENT_APPEARANCE = Object.freeze({
+  headerStyle: 'document', contentBackground: 'document', stateBackground: 'document',
+  emptyDecoration: 'document-artwork',
+} as const satisfies SurfaceAppearance);
+const AGENT_APPEARANCE = Object.freeze({
+  headerStyle: 'agent', contentBackground: 'agent', stateBackground: 'agent',
+  emptyDecoration: 'document-artwork',
+} as const satisfies SurfaceAppearance);
+const MEDIA_APPEARANCE = Object.freeze({
+  headerStyle: 'media', contentBackground: 'media', stateBackground: 'media',
+  emptyDecoration: 'none',
+} as const satisfies SurfaceAppearance);
+const FILE_MEDIA_APPEARANCE = Object.freeze({
+  ...MEDIA_APPEARANCE, headerStyle: 'document',
+} as const satisfies SurfaceAppearance);
+
+/**
+ * The single support declaration for surfaces rendered in workspace hosts.
+ * Both hosts consume common renderer registrations. The React-free metadata
+ * is also used by navigation to reject unsupported hosts before mounting UI.
+ */
+export const workspaceSurfaceRegistry = Object.freeze({
+  'file-markdown': { rendererId: 'file-markdown', hosts: ['main-third', 'browser-column'], capabilities: ['edit', 'search', 'copy-content', 'export-content', 'save-template'], appearance: DOCUMENT_APPEARANCE },
+  'file-code': { rendererId: 'file-code', hosts: ['main-third', 'browser-column'], capabilities: ['edit', 'search', 'copy-content'], appearance: DOCUMENT_APPEARANCE },
+  'file-csv': { rendererId: 'file-csv', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  'file-image': { rendererId: 'file-image', hosts: ['main-third', 'browser-column'], capabilities: ['fullscreen', 'zoom'], appearance: FILE_MEDIA_APPEARANCE },
+  'file-video': { rendererId: 'file-video', hosts: ['main-third', 'browser-column'], capabilities: ['fullscreen'], appearance: FILE_MEDIA_APPEARANCE },
+  'file-table': { rendererId: 'file-table', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  'file-media-library': { rendererId: 'file-media-library', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  'file-html': { rendererId: 'file-html', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  'file-docx': { rendererId: 'file-docx', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  'file-unavailable': { rendererId: 'file-unavailable', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  'file-browser': { rendererId: 'file-browser', hosts: ['browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  collection: { rendererId: 'collection', hosts: ['main-third', 'browser-column'], capabilities: [], appearance: DOCUMENT_APPEARANCE },
+  media: { rendererId: 'media', hosts: ['main-third', 'browser-column'], capabilities: ['fullscreen'], appearance: MEDIA_APPEARANCE },
+  mindmap: { rendererId: 'plugin-document', hosts: ['main-third'], capabilities: ['fullscreen', 'fit', 'zoom'], appearance: DOCUMENT_APPEARANCE },
+  'plugin-artifact': { rendererId: 'plugin-document', hosts: ['main-third'], capabilities: ['fullscreen'], appearance: DOCUMENT_APPEARANCE },
+  'agent-conversation': { rendererId: 'agent-conversation', hosts: ['main-third', 'browser-column'], capabilities: ['stream-conversation'], appearance: AGENT_APPEARANCE },
+  web: { rendererId: 'web', hosts: ['main-third', 'browser-column'], capabilities: ['web-navigation'], appearance: DOCUMENT_APPEARANCE },
+  'plugin-workbench': { rendererId: 'plugin-workbench', hosts: ['main-third'], capabilities: ['run-agent', 'fullscreen'], appearance: DOCUMENT_APPEARANCE },
+} as const satisfies Record<WorkspaceSurfaceKind, SurfaceRegistration>);
+
+export function workspaceSurfaceSupportsHost(
+  kind: WorkspaceSurfaceKind,
+  host: WorkspaceSurfaceHost,
+): boolean {
+  const hosts: readonly WorkspaceSurfaceHost[] = workspaceSurfaceRegistry[kind].hosts;
+  return hosts.includes(host);
+}
+
+export function workspaceSurfaceCapabilities(kind: WorkspaceSurfaceKind): readonly WorkspaceSurfaceCapability[] {
+  return workspaceSurfaceRegistry[kind].capabilities;
+}
+
+export function workspaceFileSurfaceKind(kind: WorkspaceFileSurfaceKind): `file-${WorkspaceFileSurfaceKind}` {
+  return `file-${kind}`;
+}
+
+export function workspaceFileSurfaceSupportsHost(
+  kind: WorkspaceFileSurfaceKind,
+  host: WorkspaceSurfaceHost,
+): boolean {
+  return workspaceSurfaceSupportsHost(workspaceFileSurfaceKind(kind), host);
+}
+
+/** Resolve a local file to the same canonical surface kind for either host. */
+export function resolveWorkspaceFileSurfaceKind(
+  path: string,
+  mimeType?: string | null,
+  detectedTextContent = false,
+): WorkspaceFileSurfaceKind {
+  if (/\.lib\.ya?ml$/i.test(path)) return 'media-library';
+  if (/\.table\.ya?ml$/i.test(path)) return 'table';
+  switch (externalFileViewKind(path, mimeType, detectedTextContent)) {
+    case 'markdown': return 'markdown';
+    case 'code': return 'code';
+    case 'csv': return 'csv';
+    case 'image': return 'image';
+    case 'video': return 'video';
+    case 'html': return 'html';
+    case 'docx': return 'docx';
+    case 'unavailable': return 'unavailable';
+  }
+}
+
+/** Shared defaults; dynamic view modes may refine them in the surface presentation. */
+export function workspaceSurfaceAppearance(kind: WorkspaceSurfaceKind): Readonly<SurfaceAppearance> {
+  return workspaceSurfaceRegistry[kind].appearance;
+}
diff --git a/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.test.ts b/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.test.ts
index ff7601081..ecbf3200b 100644
--- a/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.test.ts
+++ b/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.test.ts
@@ -8,9 +8,12 @@ const mocks = vi.hoisted(() => ({
   isCurrentNavigation: vi.fn().mockReturnValue(true),
   activeAgentConversationId: 'conversation-a',
   activeFilter: 'all',
+  navigationRevision: 1,
   hydrateInstance: vi.fn(),
   selectAgentConversation: vi.fn(),
   setDesiredTarget: vi.fn(),
+  clearAgentConversation: vi.fn(),
+  clearDocument: vi.fn(),
   agentRestore: {
     selectedInstanceId: 'conversation-a' as string | null,
     detailOpen: true,
@@ -28,6 +31,7 @@ vi.mock('@features/document/store/document-store', () => ({
   useDocumentStore: {
     getState: () => ({
       openAgentConversation: mocks.openAgentConversation,
+      clearDocument: mocks.clearDocument,
       activeAgentConversationId: mocks.activeAgentConversationId,
     }),
   },
@@ -51,6 +55,7 @@ vi.mock('@features/workspace/store/workspace-restore-store', () => ({
         : null,
       selectAgentConversation: mocks.selectAgentConversation,
       setDesiredTarget: mocks.setDesiredTarget,
+      clearAgentConversation: mocks.clearAgentConversation,
     }),
   },
 }));
@@ -58,7 +63,7 @@ vi.mock('@features/workspace/store/workspace-restore-store', () => ({
 vi.mock('@features/workspace/store/work-column-store', () => ({
   useWorkColumnStore: {
     getState: () => ({
-      navigation: { phase: 'committed', showWorkColumnLoading: false, requestId: 1, target: { kind: 'plugin-workbench', plugin: { manifest: { id: 'plugin-a' } } }, pendingTarget: null, previousTarget: null, failure: null, retryToken: null },
+      navigation: { phase: 'committed', showWorkColumnLoading: false, requestId: mocks.navigationRevision, target: { kind: 'plugin-workbench', plugin: { manifest: { id: 'plugin-a' } } }, pendingTarget: null, previousTarget: null, failure: null, retryToken: null },
       beginNavigation: mocks.beginNavigation,
       commitNavigation: mocks.commitNavigation,
       failNavigation: mocks.failNavigation,
@@ -75,6 +80,9 @@ describe('agent conversation navigation', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mocks.activeFilter = 'all';
+    mocks.navigationRevision = 1;
+    mocks.activeAgentConversationId = 'conversation-a';
+    mocks.clearDocument.mockImplementation(async () => { mocks.activeAgentConversationId = ''; });
     mocks.hydrateInstance.mockResolvedValue({ instanceId: 'conversation-a' });
     mocks.agentRestore = {
       selectedInstanceId: 'conversation-a',
@@ -95,7 +103,7 @@ describe('agent conversation navigation', () => {
     expect(mocks.selectAgentConversation).toHaveBeenCalledWith('conversation-a', true);
   });
 
-  it('activates an existing browser-column conversation without reopening it in the third column', async () => {
+  it('opens an existing browser-column conversation in Work for a default Work request', async () => {
     useBrowserColumnStore.getState().openTab({
       id: 'agent:conversation-a',
       title: 'Conversation A',
@@ -106,13 +114,35 @@ describe('agent conversation navigation', () => {
 
     await selectAndOpenAgentConversation('conversation-a');
 
-    expect(mocks.openAgentConversation).not.toHaveBeenCalled();
+    expect(mocks.openAgentConversation).toHaveBeenCalledWith('conversation-a');
     expect(useBrowserColumnStore.getState()).toMatchObject({
       visible: true,
       activeTabId: 'agent:conversation-a',
     });
-    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
-    expect(mocks.selectAgentConversation).toHaveBeenCalledWith('conversation-a', false);
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('main-third');
+    expect(mocks.selectAgentConversation).toHaveBeenCalledWith('conversation-a', true);
+  });
+
+  it('clears an absent persisted conversation after session database rebuild', async () => {
+    mocks.hydrateInstance.mockResolvedValue(null);
+    const { restoreAgentConversationWorkspace } = await import('./agent-conversation-navigation');
+    await restoreAgentConversationWorkspace();
+    expect(mocks.clearDocument).toHaveBeenCalledOnce();
+    expect(mocks.clearAgentConversation).toHaveBeenCalledOnce();
+    expect(mocks.openAgentConversation).not.toHaveBeenCalled();
+  });
+
+  it.each([null, { instanceId: 'conversation-a' }])('does not replace later navigation after delayed hydration (%j)', async (result) => {
+    let finish!: (value: typeof result) => void;
+    mocks.hydrateInstance.mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
+    const { restoreAgentConversationWorkspace } = await import('./agent-conversation-navigation');
+    const restoring = restoreAgentConversationWorkspace();
+    mocks.navigationRevision = 2;
+    finish(result);
+    await restoring;
+    expect(mocks.openAgentConversation).not.toHaveBeenCalled();
+    expect(mocks.clearDocument).not.toHaveBeenCalled();
+    expect(mocks.clearAgentConversation).not.toHaveBeenCalled();
   });
 
   it('restores the work-column conversation even when the middle column is on notes', async () => {
diff --git a/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.ts b/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.ts
index 20323b5c4..66df69fb9 100644
--- a/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.ts
+++ b/app/flowix-web/features/workspace/use-cases/agent-conversation-navigation.ts
@@ -8,29 +8,38 @@ import { clearWorkspaceDocument, closeAgentTarget, openAgentTarget } from './wor
 
 export async function selectAndOpenAgentConversation(
   instanceId: string,
-  options?: { history?: 'push' | 'skip'; destination?: 'main-third'; blankIfMissing?: true },
+  options?: { history?: 'push' | 'skip'; destination?: 'main-third'; blankIfMissing?: true; restoreRequestId?: number },
 ): Promise<void> {
   const normalized = instanceId.trim();
-  if (!normalized) return;
+  if (!normalized || !isRestoreRequestCurrent(options?.restoreRequestId)) return;
 
   if (options?.blankIfMissing && !hasWorkspaceAgentConversation(normalized)) {
     const requestId = useWorkColumnStore.getState().navigation.requestId;
     try {
       const restored = await hydrateWorkspaceAgentConversation(normalized);
-      if (useWorkColumnStore.getState().navigation.requestId !== requestId) return;
+      if (useWorkColumnStore.getState().navigation.requestId !== requestId
+        || !isRestoreRequestCurrent(options?.restoreRequestId)) return;
       if (!restored) {
         await clearWorkspaceDocument();
         useWorkspaceRestoreStore.getState().clearAgentConversation(normalized);
         return;
       }
     } catch {
-      if (useWorkColumnStore.getState().navigation.requestId !== requestId) return;
+      if (useWorkColumnStore.getState().navigation.requestId !== requestId
+        || !isRestoreRequestCurrent(options?.restoreRequestId)) return;
       // A backend error is not proof that an empty draft has vanished. Keep
       // the target so the detail can show its normal loading error and retry.
     }
   }
 
-  const host = await openAgentTarget(normalized, options);
+  // A list click targets Work. Browser placement is a separate explicit
+  // openWorkspaceSurface request.
+  const host = await openAgentTarget(normalized, {
+    ...options,
+    destination: options?.destination ?? 'main-third',
+  });
+  const activeTarget = useWorkColumnStore.getState().navigation.target;
+  if (activeTarget.kind !== 'agent-conversation' || activeTarget.instanceId !== normalized) return;
   useWorkspaceRestoreStore.getState().selectAgentConversation(
     normalized,
     host === 'main-third',
@@ -46,7 +55,10 @@ export function clearRestoredAgentConversation(instanceId: string): void {
   useWorkspaceRestoreStore.getState().clearAgentConversation(instanceId);
 }
 
-export async function restoreAgentConversationWorkspace(): Promise<void> {
+export async function restoreAgentConversationWorkspace(
+  restoreRequestId = useWorkColumnStore.getState().navigation.requestId,
+): Promise<void> {
+  if (!isRestoreRequestCurrent(restoreRequestId)) return;
   const store = useWorkspaceRestoreStore.getState();
   const desiredTarget = store.desiredTarget;
   const instanceId = desiredTarget?.kind === 'agent-conversation'
@@ -56,6 +68,7 @@ export async function restoreAgentConversationWorkspace(): Promise<void> {
 
   const blankIfMissing = desiredTarget?.kind === 'agent-conversation'
     && desiredTarget.blankIfMissing === true;
+  const navigationRevision = restoreRequestId;
   let restored: Awaited<ReturnType<typeof hydrateWorkspaceAgentConversation>> = null;
   let restoreFailed = false;
 
@@ -68,17 +81,21 @@ export async function restoreAgentConversationWorkspace(): Promise<void> {
 
   const currentTarget = useWorkspaceRestoreStore.getState().desiredTarget;
   if (
-    currentTarget?.kind !== 'agent-conversation'
+    useWorkColumnStore.getState().navigation.requestId !== navigationRevision
+    || !isRestoreRequestCurrent(restoreRequestId)
+    || currentTarget?.kind !== 'agent-conversation'
     || currentTarget.instanceId.trim() !== instanceId
     || useWorkColumnStore.getState().navigation.phase === 'loading'
   ) return;
 
-  if (blankIfMissing && !restoreFailed && restored === null) {
-    // Empty drafts are intentionally memory-only. Their stale restore target
-    // should become the ordinary empty work column, not a missing-session page.
+  if (!restoreFailed && restored === null) {
+    // A rebuilt session store also invalidates formerly persisted selections.
+    // Confirmed absence returns to the ordinary empty work column.
     try {
       await clearWorkspaceDocument();
-      useWorkspaceRestoreStore.getState().clearAgentConversation(instanceId);
+      const latest = useWorkspaceRestoreStore.getState().desiredTarget;
+      if (latest?.kind !== 'agent-conversation' || latest.instanceId.trim() !== instanceId) return;
+      useWorkspaceRestoreStore.getState().clearAgentConversation();
       return;
     } catch (error) {
       console.error('Failed to clear missing empty conversation target:', error);
@@ -96,6 +113,11 @@ export async function restoreAgentConversationWorkspace(): Promise<void> {
   // target visible even when this eager lookup did not return an instance.
   await selectAndOpenAgentConversation(instanceId, {
     history: 'skip',
+    restoreRequestId,
     ...(blankIfMissing && restoreFailed ? { blankIfMissing: true as const } : {}),
   });
 }
+
+function isRestoreRequestCurrent(requestId: number | undefined): boolean {
+  return requestId === undefined || useWorkColumnStore.getState().navigation.requestId === requestId;
+}
diff --git a/app/flowix-web/features/workspace/use-cases/browser-column-collections.test.ts b/app/flowix-web/features/workspace/use-cases/browser-column-collections.test.ts
index e82893dab..5c7fed3aa 100644
--- a/app/flowix-web/features/workspace/use-cases/browser-column-collections.test.ts
+++ b/app/flowix-web/features/workspace/use-cases/browser-column-collections.test.ts
@@ -21,7 +21,7 @@ function fixture(type: 'table' | 'media_library', filename: string) {
     : serializeMediaLibrary(document as ReturnType<typeof createMediaLibrary>);
   const item: CollectionIndexItem = {
     collectionId: document.collection.id, collectionType: type, relativePath: filename,
-    indexSequence: 1, name: document.collection.name, schemaVersion: 2, payloadSchemaVersion: 2,
+    indexSequence: 1, name: filename.replace(/\.(?:index\.ya?ml|(?:table|lib)\.ya?ml)$/i, ''), schemaVersion: 2, payloadSchemaVersion: 2,
     revision: 0, properties: {}, createdAt: null, updatedAt: null, modifiedMs: 0,
     sizeBytes: content.length, contentHash: null, parseState: 'valid', errorCode: null,
     inViews: true, identityConflict: false,
@@ -54,7 +54,7 @@ describe('browser column collection navigation', () => {
     });
   });
 
-  it('moves a collection with its selected view and resolves its current path', async () => {
+  it('opens a second collection view at the current path and retains Work', async () => {
     const item = fixture('table', '移动后.index.yaml');
     const display = ensureCollectionDisplay({ notebookId: 'notes', collectionId: item.collectionId!, viewId: 'selected-view' });
     const target: WorkColumnTarget = { kind: 'collection', ...display, collectionType: 'table', filePath: '/notes/旧.index.yaml', notebookPath: '/notes', name: '项目' };
@@ -63,13 +63,13 @@ describe('browser column collection navigation', () => {
     expect(useBrowserColumnStore.getState().tabs[0].target).toMatchObject({
       activeFilePath: '/notes/移动后.index.yaml', collectionType: 'table', collectionDisplay: display,
     });
-    expect(useWorkColumnStore.getState().navigation.target).toEqual({ kind: 'empty' });
+    expect(useWorkColumnStore.getState().navigation.target).toEqual(target);
   });
 
   it.each([
     ['table', 'table', '旧.table.yaml'],
     ['media-library', 'media_library', '旧.lib.yml'],
-  ] as const)('moves the legacy %s target', async (kind, type, filename) => {
+  ] as const)('opens a second view for the legacy %s target', async (kind, type, filename) => {
     fixture(type, filename);
     activate({ kind, filePath: `/notes/${filename}`, notebookPath: '/notes', notebookId: 'notes' });
     await openWorkColumnTargetInBrowserColumn(useWorkColumnStore.getState().navigation.target);
@@ -85,4 +85,25 @@ describe('browser column collection navigation', () => {
     expect(useBrowserColumnStore.getState().tabs).toEqual([]);
     expect(useWorkColumnStore.getState().navigation.target).toEqual(target);
   });
+
+  it.each(['table', 'media_library'] as const)('keeps an invalid %s selected when opening and switching files', async (type) => {
+    fixture(type, 'broken.index.yaml');
+    const document = type === 'table' ? createTableDocument() : createMediaLibrary('照片');
+    const valid = type === 'table'
+      ? serializeTableDocument(document as ReturnType<typeof createTableDocument>)
+      : serializeMediaLibrary(document as ReturnType<typeof createMediaLibrary>);
+    vi.mocked(externalDocuments.read).mockResolvedValue(valid.replace(/placement: \w+/, 'placement: standalone1'));
+    const opened = await openBrowserColumnText('/notes/broken.index.yaml', '/notes');
+    expect(opened).not.toBeNull();
+    const tab = useBrowserColumnStore.getState().tabs[0];
+    expect(tab.target).toMatchObject({
+      activeFilePath: '/notes/broken.index.yaml', collectionType: type, collectionUnavailableReason: '集合文件格式无效',
+    });
+    await selectBrowserColumnFile(tab.id, '/notes/plan.md');
+    expect(useBrowserColumnStore.getState().tabs[0].target).toMatchObject({ activeFilePath: '/notes/plan.md', collectionUnavailableReason: undefined });
+    await selectBrowserColumnFile(tab.id, '/notes/broken.index.yaml');
+    expect(useBrowserColumnStore.getState().tabs[0].target).toMatchObject({
+      activeFilePath: '/notes/broken.index.yaml', collectionType: type, collectionUnavailableReason: '集合文件格式无效',
+    });
+  });
 });
diff --git a/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.test.ts b/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.test.ts
new file mode 100644
index 000000000..c57cfc1bd
--- /dev/null
+++ b/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useBrowserColumnStore } from '../store/browser-column-store';
+import { registerWorkspaceSurfaceLifecycle } from '../store/surface-lifecycle-store';
+import { closeBrowserColumnTab } from '../public/browser-column-api';
+import {
+  discardActiveBrowserColumnDocument,
+  flushActiveBrowserColumnDocument,
+  registerBrowserColumnDocumentFlush,
+  resetBrowserColumnCoordinator,
+} from './browser-column-coordinator';
+
+afterEach(() => {
+  resetBrowserColumnCoordinator();
+  useBrowserColumnStore.getState().reset();
+});
+
+describe('Browser Column surface lifecycle', () => {
+  it('keeps a failed surface open when discard was requested but is unsupported', async () => {
+    const tabId = useBrowserColumnStore.getState().openTab({
+      id: 'tab:csv', title: 'CSV', icon: null, target: { kind: 'web', url: 'https://example.com' },
+    });
+    const flush = vi.fn().mockResolvedValue(false);
+    registerWorkspaceSurfaceLifecycle(tabId, { status: 'ready', flush });
+    try {
+      expect(discardActiveBrowserColumnDocument()).toBe(false);
+      await expect(closeBrowserColumnTab(tabId, { discardChanges: true })).resolves.toBeNull();
+      expect(flush).toHaveBeenCalledOnce();
+      expect(useBrowserColumnStore.getState().tabs).toHaveLength(1);
+    } finally {
+      registerWorkspaceSurfaceLifecycle(tabId, null);
+    }
+  });
+  it('uses the common view lifecycle for flush and discard', async () => {
+    const lifecycleFlush = vi.fn().mockResolvedValue(false);
+    const fallbackFlush = vi.fn().mockResolvedValue(true);
+    const lifecycleDiscard = vi.fn();
+    const lifecycleDispose = vi.fn();
+    const fallbackDiscard = vi.fn();
+    useBrowserColumnStore.setState({ activeTabId: 'tab:one' });
+    registerWorkspaceSurfaceLifecycle('tab:one', {
+      status: 'ready', flush: lifecycleFlush, discard: lifecycleDiscard,
+      dispose: lifecycleDispose,
+    });
+    registerBrowserColumnDocumentFlush('tab:one', fallbackFlush, fallbackDiscard);
+
+    await expect(flushActiveBrowserColumnDocument({ silent: true })).resolves.toBe(false);
+    expect(lifecycleFlush).toHaveBeenCalledWith({ silent: true });
+    expect(fallbackFlush).not.toHaveBeenCalled();
+
+    discardActiveBrowserColumnDocument();
+    expect(lifecycleDiscard).toHaveBeenCalledOnce();
+    expect(fallbackDiscard).not.toHaveBeenCalled();
+
+    registerWorkspaceSurfaceLifecycle('tab:one', null);
+    expect(lifecycleDispose).toHaveBeenCalledOnce();
+  });
+});
diff --git a/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.ts b/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.ts
index 7ce47286a..83801bf5f 100644
--- a/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.ts
+++ b/app/flowix-web/features/workspace/use-cases/browser-column-coordinator.ts
@@ -1,4 +1,5 @@
 import { useBrowserColumnStore } from '@features/workspace/store/browser-column-store';
+import { getWorkspaceSurfaceLifecycle } from '@features/workspace/public/surface-lifecycle-api';
 
 export type BrowserColumnDocumentFlush = (
   options?: { silent?: boolean },
@@ -38,6 +39,15 @@ export async function flushActiveBrowserColumnDocument(
   options?: { silent?: boolean },
 ): Promise<boolean> {
   const activeTabId = useBrowserColumnStore.getState().activeTabId;
+  const lifecycle = activeTabId ? getWorkspaceSurfaceLifecycle(activeTabId) : null;
+  if (lifecycle?.status === 'ready' && lifecycle.flush) {
+    try {
+      return await lifecycle.flush(options);
+    } catch (error) {
+      console.error('[BrowserColumn] Failed to flush active surface lifecycle', error);
+      return false;
+    }
+  }
   const registration = activeFlushRegistration;
   if (!activeTabId || !registration || registration.tabId !== activeTabId) return true;
 
@@ -49,8 +59,21 @@ export async function flushActiveBrowserColumnDocument(
   }
 }
 
-export function discardActiveBrowserColumnDocument(): void {
-  activeFlushRegistration?.discard?.();
+/** False means this editor cannot discard and must still cross its flush barrier. */
+export function discardActiveBrowserColumnDocument(): boolean {
+  const activeTabId = useBrowserColumnStore.getState().activeTabId;
+  const lifecycle = activeTabId ? getWorkspaceSurfaceLifecycle(activeTabId) : null;
+  if (lifecycle?.status === 'ready' && lifecycle.discard) {
+    lifecycle.discard();
+    return true;
+  }
+  if (lifecycle?.flush) return false;
+  const registration = activeFlushRegistration;
+  if (activeTabId && registration?.tabId === activeTabId) {
+    if (!registration.discard) return false;
+    registration.discard();
+  }
+  return true;
 }
 
 /**
diff --git a/app/flowix-web/features/workspace/use-cases/browser-column-navigation.test.ts b/app/flowix-web/features/workspace/use-cases/browser-column-navigation.test.ts
index 745ca519a..5c2bfc03a 100644
--- a/app/flowix-web/features/workspace/use-cases/browser-column-navigation.test.ts
+++ b/app/flowix-web/features/workspace/use-cases/browser-column-navigation.test.ts
@@ -5,11 +5,11 @@ import {
   openBrowserColumnFileBrowser,
   openBrowserColumnMarkdown,
   openBrowserColumnNotebookNote,
-  openBrowserColumnTabInWorkColumn,
   openBrowserColumnTarget,
   openBrowserColumnWebpage,
   openWorkColumnTargetInBrowserColumn,
 } from './browser-column-navigation';
+import { openBrowserColumnTabInWorkColumn } from './surface-opening';
 import { useBrowserColumnStore } from '@features/workspace/store/browser-column-store';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
 import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focus-store';
@@ -140,23 +140,25 @@ describe('browser column navigation', () => {
     });
   });
 
-  it('preserves webpage tabs instead of moving them to an unsupported surface', async () => {
+  it('opens a webpage in Work while retaining Browser tabs', async () => {
     await openBrowserColumnWebpage('https://example.com/docs');
     await openBrowserColumnWebpage('https://flowix.dev/');
     const before = useBrowserColumnStore.getState();
-    const focus = useWorkspaceFocusStore.getState().focusedHostId;
-
-    expect(await openBrowserColumnTabInWorkColumn('web:https://example.com/docs')).toBe(false);
+    expect(await openBrowserColumnTabInWorkColumn('web:https://example.com/docs')).toMatchObject({
+      status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' },
+    });
     expect(useBrowserColumnStore.getState().tabs).toEqual(before.tabs);
     expect(useBrowserColumnStore.getState().activeTabId).toBe(before.activeTabId);
-    expect(useWorkColumnStore.getState().navigation.target).toEqual({ kind: 'empty' });
-    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe(focus);
+    expect(useWorkColumnStore.getState().navigation.target).toEqual({ kind: 'web', url: 'https://example.com/docs' });
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('main-third');
   });
 
   it('preserves a folder tab without a selected file when asked to move it', async () => {
     await openBrowserColumnFileBrowser('/workspace');
     const before = useBrowserColumnStore.getState();
-    expect(await openBrowserColumnTabInWorkColumn(before.tabs[0].id)).toBe(false);
+    expect(await openBrowserColumnTabInWorkColumn(before.tabs[0].id)).toEqual({
+      status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled',
+    });
     expect(useBrowserColumnStore.getState().tabs).toEqual(before.tabs);
     expect(useBrowserColumnStore.getState().visible).toBe(true);
     expect(useWorkColumnStore.getState().navigation.target).toEqual({ kind: 'empty' });
@@ -171,14 +173,14 @@ describe('browser column navigation', () => {
 
     const moved = await openBrowserColumnTabInWorkColumn('file:/notes/plan.md');
 
-    expect(moved).toBeNull();
+    expect(moved).toEqual({ status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' });
     expect(useBrowserColumnStore.getState().tabs[0]).toMatchObject({
       id: 'file:/notes/plan.md',
       target: { kind: 'file-browser', folderPath: null, notebookId: null, fileTreeVisible: true, fileTreeWidth: 220, activeFilePath: '/notes/plan.md' },
     });
   });
 
-  it('deduplicates the same document path across work and browser columns', async () => {
+  it('keeps one Browser tab for repeated opens while preserving the Work view', async () => {
     const target = { kind: 'external' as const, path: '/notes/shared.md', scopePath: '/notes', transitionId: 1 };
     const work = useWorkColumnStore.getState();
     const requestId = work.beginNavigation(target, null);
@@ -186,11 +188,12 @@ describe('browser column navigation', () => {
     const first = await openBrowserColumnNotebookNote(target.path, 'notes', '/notes');
     await openBrowserColumnWebpage('https://example.com');
     const second = await openBrowserColumnNotebookNote(target.path, 'notes', '/notes');
-    expect(first?.alreadyOpen).toBe(true);
+    expect(first?.alreadyOpen).toBe(false);
     expect(second?.alreadyOpen).toBe(true);
-    expect(useBrowserColumnStore.getState().tabs).toHaveLength(1);
+    expect(second).toMatchObject({ host: 'browser-column', tabId: first?.host === 'browser-column' ? first.tabId : undefined });
+    expect(useBrowserColumnStore.getState().tabs).toHaveLength(2);
     expect(useWorkColumnStore.getState().navigation.target).toEqual(target);
-    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('main-third');
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
   });
 
   it('supports replacing the active tab', async () => {
@@ -201,7 +204,7 @@ describe('browser column navigation', () => {
     expect(useBrowserColumnStore.getState().activeTabId).toBe('agent:agent-2');
   });
 
-  it('focuses an existing work-column document instead of opening a duplicate tab', async () => {
+  it('opens explicitly in Browser even when the content already exists in Work', async () => {
     const workColumn = useWorkColumnStore.getState();
     const requestId = workColumn.beginNavigation({
       kind: 'external',
@@ -219,11 +222,11 @@ describe('browser column navigation', () => {
     const result = await openBrowserColumnMarkdown('/notes/plan.md');
 
     expect(useBrowserColumnStore.getState()).toMatchObject({
-      tabs: [],
-      visible: false,
+      visible: true,
     });
-    expect(result).toEqual({ host: 'main-third', alreadyOpen: true });
-    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('main-third');
+    expect(useBrowserColumnStore.getState().tabs).toHaveLength(1);
+    expect(result).toEqual({ host: 'browser-column', tabId: 'file:/notes/plan.md', alreadyOpen: false });
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
   });
 
   it('opens a dropped file in the browser column even when it is open in the work column', async () => {
@@ -308,7 +311,7 @@ describe('browser column navigation', () => {
   });
 });
 
-it('moves a folder selection to the main column even when a separate file tab already exists', async () => {
+it('opens a folder selection in Work without closing Browser tabs or deadlocking', async () => {
   const location = vi.spyOn(notes, 'resolveLocation').mockResolvedValue({
     path: '/workspace/readme.md', notebookId: null, notebookPath: null,
     relativePath: null, indexable: false,
@@ -332,11 +335,11 @@ it('moves a folder selection to the main column even when a separate file tab al
       moving,
       new Promise<string>((resolve) => setTimeout(() => resolve('navigation queue deadlocked'), 100)),
     ]);
-    expect(result).toBe(true);
+    expect(result).toMatchObject({ status: 'opened', host: 'main-third' });
     expect(useWorkColumnStore.getState().navigation.target).toMatchObject({ kind: 'external', path: '/workspace/readme.md' });
-    expect(useBrowserColumnStore.getState().tabs.map((tab) => tab.id)).toEqual(['file:/workspace/readme.md']);
-    await openBrowserColumnWebpage('https://example.com/after-move');
-    expect(useBrowserColumnStore.getState().tabs).toHaveLength(2);
+    expect(useBrowserColumnStore.getState().tabs.map((tab) => tab.id)).toEqual(['file:/workspace/readme.md', 'file-browser:/workspace']);
+    await openBrowserColumnWebpage('https://example.com/after-open');
+    expect(useBrowserColumnStore.getState().tabs).toHaveLength(3);
   } finally {
     location.mockRestore();
     resetBrowserColumnCoordinator();
diff --git a/app/flowix-web/features/workspace/use-cases/browser-column-navigation.ts b/app/flowix-web/features/workspace/use-cases/browser-column-navigation.ts
index 532f60e80..542409b6c 100644
--- a/app/flowix-web/features/workspace/use-cases/browser-column-navigation.ts
+++ b/app/flowix-web/features/workspace/use-cases/browser-column-navigation.ts
@@ -1,6 +1,8 @@
+import type { BrowserColumnNavigationResult } from '../model/surface-opening';
 import { collections, externalDocuments, notebooks } from '@platform/tauri/client';
 import { collectionNotebookId } from '@features/collection/mutations';
 import { parseCollectionDocumentV2 } from '@features/collection/model';
+import { inspectCollectionRecoveryType } from '@features/collection/recovery';
 import { ensureCollectionDisplay, bindCollectionDisplayPath } from '@/lib/collection-display-registry';
 import { captureFileBrowserContext } from './file-browser-context';
 import type { FileBrowserTarget } from '../store/file-browser-target';
@@ -8,17 +10,15 @@ import { canonicalDirectoryPath, canonicalPath, fileLocatorKey } from '@/lib/pat
 import { displayTitleFromFilename } from '@/lib/utils';
 import { canonicalUrl, contentIdentityKey } from '@features/workspace/store/workspace-content-identity';
 import {
-  canMoveBrowserColumnTargetToWorkColumn,
   useBrowserColumnStore,
   type BrowserColumnOpenDisposition,
-  type BrowserColumnTab,
   type BrowserColumnTarget,
 } from '@features/workspace/store/browser-column-store';
 import type { WorkColumnTarget } from '@features/workspace/store/work-column-target';
 import {
   activateExistingWorkspaceContent,
   activateExistingWorkspaceContentAsync,
-  findExistingWorkspaceContent,
+  findWorkspaceContentLocations,
   browserColumnTargetIdentity,
   workColumnTargetIdentity,
 } from './workspace-content-activation';
@@ -26,36 +26,20 @@ import {
   enqueueBrowserColumnNavigation,
 } from './browser-column-coordinator';
 import {
-  openCollectionTarget,
-  openAgentTarget,
-  openExternalTarget,
-  openMediaTarget,
-  openWebTarget,
-  closeAgentTarget,
-  clearWorkspaceDocument,
-  flushWorkspaceDocument,
+  prepareActiveWorkColumnDocumentLeave,
 } from './workspace-navigation';
-import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focus-store';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
 import type { ContentIdentity } from '@features/workspace/store/workspace-content-identity';
 
-export type BrowserColumnOpenResult =
-  | { host: 'main-third'; alreadyOpen: true }
-  | { host: 'browser-column'; tabId: string; alreadyOpen: boolean };
-
-function openResult(
-  location: ReturnType<typeof activateExistingWorkspaceContent>,
-): BrowserColumnOpenResult | null {
-  if (!location) return null;
-  return location.host === 'main-third'
-    ? { host: 'main-third', alreadyOpen: true }
-    : { host: 'browser-column', tabId: location.tabId, alreadyOpen: true };
-}
+export type BrowserColumnOpenResult = NonNullable<BrowserColumnNavigationResult>;
+export type BrowserTargetOpenResult = BrowserColumnOpenResult;
 
 function targetTabTitle(target: BrowserColumnTarget): string {
   const filenameFromPath = (path: string) => path.split(/[\\/]/).pop() ?? path;
 
   switch (target.kind) {
+    case 'folder-collection':
+      return target.folderName || target.folderPath.split(/[\\/]/).filter(Boolean).pop() || '文件夹集合';
     case 'media':
       return filenameFromPath(target.filePath);
     case 'file-browser':
@@ -81,86 +65,56 @@ function targetTabIcon(target: BrowserColumnTarget): string | null {
   }
 }
 
+function targetTabId(target: BrowserColumnTarget): string {
+  if (target.kind === 'folder-collection') return `folder-collection:${target.notebookId}:${canonicalPath(target.folderPath)}`;
+  if (target.kind === 'agent_conversation') return `agent:${target.instanceId}`;
+  if (target.kind === 'web') return `web:${canonicalUrl(target.url) ?? target.url}`;
+  if (target.kind === 'file-browser') {
+    return target.collectionDisplay
+      ? target.collectionDisplay.displayId
+      : target.activeFilePath
+        ? fileLocatorKey(target.activeFilePath)
+        : `file-browser:${target.folderPath}`;
+  }
+  if (target.kind === 'media') return fileLocatorKey(target.filePath);
+  return 'empty';
+}
+
 export function openBrowserColumnTarget(
   target: BrowserColumnTarget,
   disposition: BrowserColumnOpenDisposition = 'focus-existing',
-): Promise<BrowserColumnOpenResult | null> {
-  let id = target.kind === 'agent_conversation'
-      ? `agent:${target.instanceId}`
-      : target.kind === 'web'
-        ? `web:${canonicalUrl(target.url) ?? target.url}`
-    : target.kind === 'file-browser'
-          ? target.activeFilePath ? fileLocatorKey(target.activeFilePath) : `file-browser:${target.folderPath}`
-        : target.kind === 'media'
-            ? fileLocatorKey(target.filePath)
-          : 'empty';
-
+): Promise<BrowserColumnNavigationResult> {
   return enqueueBrowserColumnNavigation(async () => {
     target = await prepareCollectionBrowserTarget(target);
-    if (target.kind === 'file-browser' && target.collectionDisplay) id = target.collectionDisplay.displayId;
-    let moveWorkColumnTarget = false;
-    if (disposition === 'focus-existing') {
-      const existing = findExistingWorkspaceContent(browserColumnTargetIdentity(target));
-      if (existing?.host === 'main-third') {
-        const workTarget = useWorkColumnStore.getState().navigation.target;
-        const workIdentity = workColumnTargetIdentity(workTarget);
-        const requestedIdentity = browserColumnTargetIdentity(target);
-        moveWorkColumnTarget = !!workIdentity
-          && contentIdentityKey(workIdentity) === contentIdentityKey(requestedIdentity);
-        if (!moveWorkColumnTarget) {
-          activateExistingWorkspaceContent(browserColumnTargetIdentity(target));
-          return openResult(existing);
-        }
-        // List-column "open in right" is a move when the same content is
-        // already in the work column. Save before mounting the right-side copy.
-        if (target.kind !== 'agent_conversation') await flushWorkspaceDocument();
-        if (moveWorkColumnTarget) {
-          const currentIdentity = workColumnTargetIdentity(useWorkColumnStore.getState().navigation.target);
-          if (!currentIdentity || contentIdentityKey(currentIdentity) !== contentIdentityKey(requestedIdentity)) {
-            return null;
-          }
-        }
-      }
-      if (existing?.host === 'browser-column') {
+    // Browser opens are scoped to Browser: a matching Work target may
+    // coexist, while a matching Browser tab is always reused.
+    if (disposition !== 'replace-active') {
+      const existingTab = findWorkspaceContentLocations(
+        browserColumnTargetIdentity(target),
+      ).browserColumn;
+      if (existingTab) {
         const store = useBrowserColumnStore.getState();
-        const existingTab = store.tabs.find((candidate) => candidate.id === existing.tabId);
         if (target.kind === 'file-browser') {
-          if (existingTab?.target.kind === 'file-browser') {
+          const existingTarget = store.tabs.find((tab) => tab.id === existingTab.tabId)?.target;
+          if (existingTarget?.kind === 'file-browser') {
             // Upgrade a standalone file tab to a file-browser tab in place.
             // The tab identity stays stable while the resource context and
             // tree preferences are added.
-            store.updateFileBrowserContext(existing.tabId, {
+            store.updateFileBrowserContext(existingTab.tabId, {
               folderPath: target.folderPath,
               notebookId: target.notebookId,
               scopePath: target.scopePath,
             });
             if (target.activeFilePath) {
-              store.selectFileBrowserFile(existing.tabId, target.activeFilePath, target.collectionDisplay, target.collectionType);
+              store.selectFileBrowserFile(existingTab.tabId, target.activeFilePath, target.collectionDisplay, target.collectionType, target.collectionUnavailableReason);
             }
           }
         }
-        store.commitTab(existing.tabId);
-        if (moveWorkColumnTarget) {
-          if (target.kind === 'agent_conversation') closeAgentTarget();
-          else await clearWorkspaceDocument();
-        }
-        return { host: 'browser-column', tabId: existing.tabId, alreadyOpen: true };
+        store.commitTab(existingTab.tabId);
+        return { host: 'browser-column', tabId: existingTab.tabId, alreadyOpen: true };
       }
     }
 
-    if (disposition === 'open-in-column') {
-      const store = useBrowserColumnStore.getState();
-      const key = contentIdentityKey(browserColumnTargetIdentity(target));
-      const existing = store.tabs.find((tab) => contentIdentityKey(browserColumnTargetIdentity(tab.target)) === key);
-      if (existing) {
-        store.commitTab(existing.id);
-        if (moveWorkColumnTarget) {
-          if (target.kind === 'agent_conversation') closeAgentTarget();
-          else await clearWorkspaceDocument();
-        }
-        return { host: 'browser-column', tabId: existing.id, alreadyOpen: true };
-      }
-    }
     // Directory opens reuse their browsing tab after file-identity lookup.
     // Independent file opens keep their own stable tabs.
     if (target.kind === 'file-browser' && target.folderPath && disposition !== 'replace-active') {
@@ -170,24 +124,18 @@ export function openBrowserColumnTarget(
         && tab.target.folderPath && canonicalPath(tab.target.folderPath) === canonicalPath(folderTarget.folderPath!)
         && tab.target.notebookId === folderTarget.notebookId);
       if (folderTab) {
-        if (target.activeFilePath) store.selectFileBrowserFile(folderTab.id, target.activeFilePath, target.collectionDisplay, target.collectionType);
+        if (target.activeFilePath) store.selectFileBrowserFile(folderTab.id, target.activeFilePath, target.collectionDisplay, target.collectionType, target.collectionUnavailableReason);
         store.commitTab(folderTab.id);
-        if (moveWorkColumnTarget) {
-          await clearWorkspaceDocument();
-        }
         return { host: 'browser-column', tabId: folderTab.id, alreadyOpen: true };
       }
     }
+    const id = targetTabId(target);
     const tabId = useBrowserColumnStore.getState().openTab({
       id,
       title: targetTabTitle(target),
       icon: targetTabIcon(target),
       target,
     }, disposition);
-    if (moveWorkColumnTarget) {
-      if (target.kind === 'agent_conversation') closeAgentTarget();
-      else await clearWorkspaceDocument();
-    }
     return { host: 'browser-column', tabId, alreadyOpen: false };
   });
 }
@@ -208,19 +156,24 @@ export function selectBrowserColumnFile(tabId: string, filePath: string | null,
     if (existing) { state.commitTab(existing.id); return true; }
     if (folderPath !== undefined) state.switchFileBrowserFolder(tabId, folderPath);
     const prepared = await prepareCollectionBrowserTarget({ ...tab.target, activeFilePath: filePath, collectionDisplay: undefined, collectionType: undefined });
-    const location = findExistingWorkspaceContent(browserColumnTargetIdentity(prepared));
-    if (location && !(location.host === 'browser-column' && location.tabId === tabId)) { activateExistingWorkspaceContent(browserColumnTargetIdentity(prepared)); return true; }
-    state.selectFileBrowserFile(tabId, prepared.kind === 'file-browser' ? prepared.activeFilePath : filePath, prepared.kind === 'file-browser' ? prepared.collectionDisplay : undefined, prepared.kind === 'file-browser' ? prepared.collectionType : undefined);
+    const existingBrowser = findWorkspaceContentLocations(
+      browserColumnTargetIdentity(prepared),
+    ).browserColumn;
+    if (existingBrowser && existingBrowser.tabId !== tabId) {
+      activateExistingWorkspaceContent(browserColumnTargetIdentity(prepared), 'browser-column');
+      return true;
+    }
+    if (prepared.kind === 'file-browser') state.selectFileBrowserFile(tabId, prepared.activeFilePath, prepared.collectionDisplay, prepared.collectionType, prepared.collectionUnavailableReason);
     return true;
   });
   if (!filePath) return select();
 
   const documentIdentity: ContentIdentity = { kind: 'external', path: filePath };
-  const existing = findExistingWorkspaceContent(documentIdentity);
-  if (!existing || (existing.host === 'browser-column' && existing.tabId === tabId)) {
+  const existingBrowser = findWorkspaceContentLocations(documentIdentity).browserColumn;
+  if (!existingBrowser || existingBrowser.tabId === tabId) {
     return select();
   }
-  return activateExistingWorkspaceContentAsync(documentIdentity)
+  return activateExistingWorkspaceContentAsync(documentIdentity, 'browser-column')
     .then((location) => location ? true : select());
 }
 
@@ -237,15 +190,20 @@ export function openBrowserColumnNotebookNote(
   filePath: string,
   notebookId: string,
   notebookPath: string,
+  disposition: BrowserColumnOpenDisposition = 'focus-existing',
 ): Promise<BrowserColumnOpenResult | null> {
   return openBrowserColumnTarget({
     ...createFileBrowserTarget(filePath, notebookPath),
     notebookId,
-  });
+  }, disposition);
 }
 
-export function openBrowserColumnText(filePath: string, scopePath: string | null): Promise<BrowserColumnOpenResult | null> {
-  return openBrowserColumnTarget(createFileBrowserTarget(filePath, scopePath));
+export function openBrowserColumnText(
+  filePath: string,
+  scopePath: string | null,
+  disposition: BrowserColumnOpenDisposition = 'focus-existing',
+): Promise<BrowserColumnOpenResult | null> {
+  return openBrowserColumnTarget(createFileBrowserTarget(filePath, scopePath), disposition);
 }
 
 export function openBrowserColumnMedia(
@@ -280,12 +238,14 @@ export function openBrowserColumnAgentConversation(instanceId: string): Promise<
   return openBrowserColumnTarget({ kind: 'agent_conversation', instanceId });
 }
 
-/** Move the currently displayed work-column target into the right browser column. */
+/** Open the currently displayed work-column target in the right browser column. */
 export function openWorkColumnTargetInBrowserColumn(
   target: WorkColumnTarget,
 ): Promise<BrowserColumnOpenResult | null> {
   const browserTarget: BrowserColumnTarget | null = (() => {
-    switch (target.kind) {
+  switch (target.kind) {
+    case 'folder-collection': return { kind: 'folder-collection', notebookId: target.notebookId,
+      notebookPath: target.notebookPath, folderPath: target.folderPath, folderName: target.folderName };
       case 'media':
         return {
           kind: 'media',
@@ -323,108 +283,24 @@ export function openWorkColumnTargetInBrowserColumn(
       return null;
     }
 
-    // Flush the work-column editor before the BrowserColumn mounts its own
-    // document surface. This action moves the document; it must not leave two
-    // independently editable copies open in separate columns.
-    if (target.kind !== 'agent-conversation') await flushWorkspaceDocument();
+    // This legacy transfer opens the current Work content as a second view.
+    if (target.kind !== 'agent-conversation') await prepareActiveWorkColumnDocumentLeave();
     if (!isStillCurrentTarget()) return null;
 
     const preparedTarget = await prepareCollectionBrowserTarget(browserTarget);
     if (!isStillCurrentTarget()) return null;
 
-    const id = preparedTarget.kind === 'agent_conversation'
-        ? `agent:${preparedTarget.instanceId}`
-        : preparedTarget.kind === 'web'
-          ? `web:${canonicalUrl(preparedTarget.url) ?? preparedTarget.url}`
-          : preparedTarget.kind === 'file-browser' ? preparedTarget.collectionDisplay ? preparedTarget.collectionDisplay.displayId : preparedTarget.activeFilePath ? fileLocatorKey(preparedTarget.activeFilePath) : `file-browser:${preparedTarget.folderPath}` : 'empty';
+    const id = targetTabId(preparedTarget);
+    const existingTab = findWorkspaceContentLocations(
+      browserColumnTargetIdentity(preparedTarget),
+    ).browserColumn;
     const tabId = useBrowserColumnStore.getState().openTab({
       id,
       title: targetTabTitle(preparedTarget),
       icon: targetTabIcon(preparedTarget),
       target: preparedTarget,
     });
-    if (target.kind === 'agent-conversation') {
-      closeAgentTarget();
-    } else {
-      await clearWorkspaceDocument();
-    }
-    return { host: 'browser-column', tabId, alreadyOpen: false };
-  });
-}
-
-function restoreBrowserColumnTab(
-  tab: BrowserColumnTab,
-  originalIndex: number,
-  originalActiveTabId: string | null,
-): void {
-  const store = useBrowserColumnStore.getState();
-  if (!store.tabs.some((candidate) => candidate.id === tab.id)) {
-    store.openTab(tab);
-  }
-
-  const restored = useBrowserColumnStore.getState();
-  const currentIndex = restored.tabs.findIndex((candidate) => candidate.id === tab.id);
-  if (currentIndex >= 0 && currentIndex !== originalIndex) {
-    const beforeTabId = restored.tabs[originalIndex]?.id ?? null;
-    restored.reorderTab(tab.id, beforeTabId === tab.id ? null : beforeTabId);
-  }
-
-  const activeTabStillExists = originalActiveTabId !== null
-    && useBrowserColumnStore.getState().tabs.some((candidate) => candidate.id === originalActiveTabId);
-  if (activeTabStillExists) {
-    useBrowserColumnStore.getState().commitTab(originalActiveTabId);
-  }
-}
-
-/** Move a BrowserColumn tab to the left work column. */
-export function openBrowserColumnTabInWorkColumn(tabId: string): Promise<boolean | null> {
-  return enqueueBrowserColumnNavigation(async () => {
-    const before = useBrowserColumnStore.getState();
-    const originalIndex = before.tabs.findIndex((tab) => tab.id === tabId);
-    if (originalIndex < 0) return false;
-    const tab = before.tabs[originalIndex];
-    if (!canMoveBrowserColumnTargetToWorkColumn(tab.target)) return false;
-    const originalActiveTabId = before.activeTabId;
-
-    // Remove the tab before invoking the normal work-column navigation
-    // facade. Its duplicate detection must see the target as no longer owned
-    // by the BrowserColumn, otherwise it would simply reactivate this tab.
-    useBrowserColumnStore.getState().closeTab(tabId);
-
-    try {
-      switch (tab.target.kind) {
-        case 'file-browser':
-          if (tab.target.collectionDisplay) {
-            await openCollectionTarget(tab.target.collectionDisplay);
-          } else if (tab.target.activeFilePath) {
-            await openExternalTarget(tab.target.activeFilePath, {
-              destination: 'main-third',
-              scopePath: tab.target.scopePath,
-              fileBrowser: tab.target,
-            });
-          }
-          break;
-        case 'media':
-          await openMediaTarget({
-            filePath: tab.target.filePath,
-            notebookId: tab.target.notebookId,
-            notebookPath: tab.target.notebookPath,
-            resourceKind: tab.target.resourceKind,
-          });
-          break;
-        case 'web':
-          await openWebTarget(tab.target.url);
-          break;
-        case 'agent_conversation':
-          await openAgentTarget(tab.target.instanceId);
-          break;
-      }
-      useWorkspaceFocusStore.getState().focusHost('main-third');
-      return true;
-    } catch (error) {
-      restoreBrowserColumnTab(tab, originalIndex, originalActiveTabId);
-      throw error;
-    }
+    return { host: 'browser-column', tabId, alreadyOpen: !!existingTab };
   });
 }
 
@@ -442,15 +318,27 @@ export function removeBrowserColumnTabsByPath(path: string): string[] {
 
 /** Resolve identity before a browser surface can mount. */
 async function prepareCollectionBrowserTarget(target: BrowserColumnTarget): Promise<BrowserColumnTarget> {
-  if (target.kind !== 'file-browser' || !target.activeFilePath || (!target.collectionDisplay && !/(?:\.(table|lib)\.ya?ml|\.index\.yaml)$/i.test(target.activeFilePath))) return target.kind === 'file-browser' ? { ...target, collectionType: undefined } : target;
+  if (target.kind !== 'file-browser' || !target.activeFilePath || (!target.collectionDisplay && !/(?:\.(table|lib)\.ya?ml|\.index\.yaml)$/i.test(target.activeFilePath))) return target.kind === 'file-browser' ? { ...target, collectionType: undefined, collectionUnavailableReason: undefined } : target;
   const registered = (await notebooks.getAll()).find((notebook) => target.notebookId ? notebook.id === target.notebookId : canonicalPath(target.activeFilePath!).startsWith(`${canonicalDirectoryPath(notebook.path)}/`));
   const root = registered ? canonicalDirectoryPath(registered.path) : null;
   if (!root) throw new Error('集合需要笔记本上下文');
   const notebookId = await collectionNotebookId(root, target.notebookId);
-  const envelope = target.collectionDisplay ? null : parseCollectionDocumentV2(await externalDocuments.read(target.activeFilePath, root));
+  let envelope: ReturnType<typeof parseCollectionDocumentV2> | null = null;
+  if (!target.collectionDisplay) {
+    const source = await externalDocuments.read(target.activeFilePath, root);
+    try { envelope = parseCollectionDocumentV2(source); }
+    catch {
+      return { ...target, notebookId, scopePath: root, collectionType: inspectCollectionRecoveryType(source), collectionUnavailableReason: '集合文件格式无效' };
+    }
+  }
   const collectionId = target.collectionDisplay?.collectionId ?? envelope!.collection.id;
-  const item = await collections.resolve(notebookId, collectionId);
-  if (item.identityConflict || item.parseState !== 'valid') throw new Error('集合身份冲突或格式暂不可用');
+  let item: Awaited<ReturnType<typeof collections.resolve>>;
+  try { item = await collections.resolve(notebookId, collectionId); }
+  catch {
+    return { ...target, notebookId, scopePath: root, collectionType: target.collectionType ?? envelope?.collection.type ?? 'table', collectionUnavailableReason: '集合不存在或暂时无法读取' };
+  }
+  if (item.identityConflict) throw new Error('集合身份冲突或格式暂不可用');
+  if (item.parseState !== 'valid') return { ...target, notebookId, scopePath: root, collectionType: item.collectionType, collectionUnavailableReason: '集合文件格式无效' };
   const display = ensureCollectionDisplay({ notebookId, collectionId, viewId: target.collectionDisplay?.viewId ?? null }, target.collectionDisplay?.displayId);
   const path = `${root.replace(/\/$/, '')}/${item.relativePath}`;
   bindCollectionDisplayPath(display.displayId, path, item.indexSequence);
diff --git a/app/flowix-web/features/workspace/use-cases/collection-display-tracking.ts b/app/flowix-web/features/workspace/use-cases/collection-display-tracking.ts
index ed420ac95..98fb7b9f7 100644
--- a/app/flowix-web/features/workspace/use-cases/collection-display-tracking.ts
+++ b/app/flowix-web/features/workspace/use-cases/collection-display-tracking.ts
@@ -1,6 +1,7 @@
 import { parseCollectionDocumentV2 } from '@features/collection/model';
-import { collections, externalDocuments, notebooks, type CollectionIndexItem } from '@platform/tauri/client';
+import { collections, externalDocuments, notebooks, type CollectionChangedEvent, type CollectionIndexItem } from '@platform/tauri/client';
 import { subscribe } from '@platform/tauri/event-bus';
+import { subscribeNotebookChanges } from '@platform/tauri/notebook-change-events';
 import { canonicalDirectoryPath } from '@/lib/path';
 import { bindCollectionDisplayPath, collectionDisplays, findCollectionDisplayPath } from '@/lib/collection-display-registry';
 import { useWorkColumnStore } from '../store/work-column-store';
@@ -12,14 +13,14 @@ import { findFileDisplayId } from '@/lib/file-display-registry';
 import { replaceWorkspaceDocumentPath } from '@features/document/public/workspace-api';
 import { useBrowserColumnStore } from '../store/browser-column-store';
 
-interface CollectionChange { notebookId: string; collectionId?: string; indexSequence?: number; relativePath?: string; kind?: string }
+interface CollectionChange extends Partial<CollectionChangedEvent> { notebookId: string; kind?: string; changeId?: string }
 const appliedSequences = new Map<string, number>();
 const sequences = new Map<string, number>();
 let started = false;
 
 function replaceLiveFilePath(previousPath: string, path: string): void {
   const displayId = findFileDisplayId(previousPath);
-  if (displayId) replaceWorkspaceDocumentPath({ kind: 'md', path: previousPath, displayId }, path);
+  if (displayId && !replaceWorkspaceDocumentPath({ kind: 'md', path: previousPath, displayId }, path)) return;
   useWorkColumnStore.getState().replaceExternalPath(previousPath, path);
   useBrowserColumnStore.getState().replaceExternalPath(previousPath, path);
 }
@@ -147,9 +148,16 @@ export function ensureCollectionDisplayTrackingStarted(): void {
       void refreshCollectionDisplays({ notebookId: display.notebookId, collectionId: display.collectionId });
     }
   }
-  subscribe<CollectionChange>('collection-changed', (event) => { void refreshCollectionDisplays(event); });
-  subscribe<CollectionChange>('flowix:path-note-changed', (event) => {
-    if (event.notebookId && (!event.relativePath || /(?:\.(table|lib)\.ya?ml|\.index\.yaml)$/i.test(event.relativePath))) void refreshCollectionDisplays(event);
+  subscribe<CollectionChangedEvent>('collection-changed', (event) => {
+    void refreshCollectionDisplays(event.directoryMove ? { notebookId: event.notebookId } : event);
+  });
+  subscribeNotebookChanges((event) => {
+    const collectionMutation = event.changeId?.startsWith(`collection:${event.notebookId}:`);
+    if (!collectionMutation && (!event.relativePath || (event.kind === 'path-moved' && event.directory) || /(?:\.(table|lib)\.ya?ml|\.index\.yaml)$/i.test(event.relativePath))) {
+      void refreshCollectionDisplays({ notebookId: event.notebookId });
+    }
+  });
+  subscribe<CollectionChange>('file-management-changed', (event) => {
+    if (event.notebookId && !event.operationId) void refreshCollectionDisplays(event);
   });
-  subscribe<CollectionChange>('file-management-changed', (event) => { if (event.notebookId) void refreshCollectionDisplays(event); });
 }
diff --git a/app/flowix-web/features/workspace/use-cases/collection-navigation.test.ts b/app/flowix-web/features/workspace/use-cases/collection-navigation.test.ts
index 372eb3a42..36a087424 100644
--- a/app/flowix-web/features/workspace/use-cases/collection-navigation.test.ts
+++ b/app/flowix-web/features/workspace/use-cases/collection-navigation.test.ts
@@ -1,24 +1,27 @@
 import { afterEach, beforeEach, expect, it, vi } from 'vitest';
-import { createTableDocument, serializeTableDocument } from '@features/multidimensional-table/model';
+import { createTableDocument, parseTableDocument, serializeTableDocument } from '@features/multidimensional-table/model';
 import { createMediaLibrary, serializeMediaLibrary } from '@features/media-library/model';
 import { ensureCollectionDisplay, reconcileCollectionDisplays } from '@/lib/collection-display-registry';
+import { workColumnTargetFilePath } from '../store/work-column-target';
+import { resolveWorkColumnContent } from '@features/surface/resolver';
 import { useWorkColumnStore } from '../store/work-column-store';
 import { useBrowserColumnStore } from '../store/browser-column-store';
 
-const mocks = vi.hoisted(() => ({ resolve: vi.fn(), read: vi.fn(), clear: vi.fn(async () => {}) }));
+const mocks = vi.hoisted(() => ({ resolve: vi.fn(), read: vi.fn(), write: vi.fn(), getAll: vi.fn(), clear: vi.fn(async () => {}) }));
 vi.mock('@platform/tauri/client', async (importOriginal) => ({
   ...await importOriginal<typeof import('@platform/tauri/client')>(),
-  collections: { resolve: mocks.resolve }, externalDocuments: { read: mocks.read },
+  collections: { resolve: mocks.resolve }, externalDocuments: { read: mocks.read, write: mocks.write }, notebooks: { getAll: mocks.getAll },
 }));
 vi.mock('@features/memo/public/workspace-api', () => ({ getWorkspaceMemoState: () => ({ notebooks: [{ id: 'book', path: '/book' }] }) }));
 vi.mock('@features/document/public/workspace-api', () => ({
   getWorkspaceDocumentState: () => ({ activeExternalSession: null, activeAgentConversationId: null, clearDocument: mocks.clear }),
   recordWorkspaceDocumentNavigation: vi.fn(),
 }));
-import { openCollectionTarget } from './workspace-navigation';
+import { openCollectionTarget, openTableTarget, openFolderCollection, resetCurrentCollectionView } from './workspace-navigation';
 
 beforeEach(() => {
   vi.clearAllMocks();
+  mocks.getAll.mockResolvedValue([{ id: 'book', path: '/book' }]);
   useBrowserColumnStore.getState().reset();
   const store = useWorkColumnStore.getState();
   store.commitNavigation(store.beginNavigation({ kind: 'empty' }, null), { kind: 'empty' });
@@ -78,3 +81,54 @@ it('revalidates an unavailable collection without clearing an identity conflict'
   expect(mocks.read).not.toHaveBeenCalled();
   expect(useWorkColumnStore.getState().navigation.target).toMatchObject({ unavailableReason: '集合身份冲突，请先为副本生成新 ID' });
 });
+
+it('retains the selected file when a previously resolved collection disappears from the index', async () => {
+  const document = createTableDocument();
+  mocks.resolve.mockResolvedValueOnce({ relativePath: '11测试/新建多维日历.index.yaml', parseState: 'valid', collectionType: 'table', name: '日历', indexSequence: 1 })
+    .mockRejectedValue(new Error('COLLECTION_NOT_FOUND'));
+  const reference = { notebookId: 'book', collectionId: document.collection.id };
+  await openCollectionTarget(reference);
+  await openCollectionTarget(reference, { refresh: true });
+  expect(useWorkColumnStore.getState().navigation.target).toMatchObject({
+    filePath: '/book/11测试/新建多维日历.index.yaml', unavailableReason: '集合不存在或暂时无法读取',
+  });
+});
+
+it('opens a malformed calendar without withdrawing selection, then repairs it even while the index is unavailable', async () => {
+  const document = createTableDocument('calendar', '新建多维日历', 'standalone');
+  const damaged = serializeTableDocument(document).replace('placement: standalone', 'placement: standalone1');
+  const path = '/book/11测试/新建多维日历.index.yaml';
+  mocks.read.mockResolvedValue(damaged);
+  mocks.resolve.mockRejectedValue(new Error('COLLECTION_NOT_FOUND'));
+  mocks.write.mockResolvedValue({ status: 'saved' });
+  await openTableTarget(path, '/book/11测试', null);
+  const navigation = useWorkColumnStore.getState().navigation;
+  expect(navigation.phase).toBe('committed');
+  expect(workColumnTargetFilePath(navigation.target)).toBe(path);
+  expect(navigation.target).toMatchObject({ kind: 'table', notebookPath: '/book', notebookId: 'book', unavailableReason: '集合文件格式无效' });
+  const presentation = resolveWorkColumnContent({ navigation, document: null, pluginWorkbench: null, emptyMessage: '' });
+  expect(presentation).toMatchObject({ status: 'empty', actions: [{ id: 'reset-current-collection-view', enabled: true }] });
+
+  await resetCurrentCollectionView(path, '/book/11测试', null);
+  const write = mocks.write.mock.calls[0][0];
+  expect(write).toMatchObject({ filePath: path, scopePath: '/book', expectedContent: damaged });
+  const repaired = parseTableDocument(write.content);
+  expect(repaired.collection).toMatchObject({ id: document.collection.id, name: '新建多维日历', placement: 'standalone' });
+  expect(repaired.views.items).toEqual(document.views.items);
+  expect(useWorkColumnStore.getState().navigation.target).toMatchObject({ kind: 'table', filePath: path });
+  expect(useWorkColumnStore.getState().navigation.target).not.toHaveProperty('unavailableReason');
+});
+
+it('keeps a malformed folder collection selected and recoverable', async () => {
+  const document = createTableDocument('table', '项目', 'folder');
+  document.dataset.source = { scope: 'containing_folder', depth: 'descendants' };
+  mocks.read.mockResolvedValue(serializeTableDocument(document).replace('placement: folder', 'placement: broken'));
+  const { files } = await import('@platform/tauri/client');
+  const read = vi.spyOn(files, 'read').mockResolvedValue(await mocks.read());
+  try {
+    await openFolderCollection('book', '/book/项目');
+    expect(useWorkColumnStore.getState().navigation.target).toMatchObject({
+      kind: 'table', filePath: '/book/项目/.index.yaml', unavailableReason: '集合文件格式无效',
+    });
+  } finally { read.mockRestore(); }
+});
diff --git a/app/flowix-web/features/workspace/use-cases/notebook-path-move.ts b/app/flowix-web/features/workspace/use-cases/notebook-path-move.ts
index 9cf25ddad..be8496ec7 100644
--- a/app/flowix-web/features/workspace/use-cases/notebook-path-move.ts
+++ b/app/flowix-web/features/workspace/use-cases/notebook-path-move.ts
@@ -1,11 +1,12 @@
 import { canonicalPath } from '@/lib/path';
-import { findFileDisplayId } from '@/lib/file-display-registry';
-import { getWorkspaceDocumentState } from '@features/document/public/workspace-api';
+import { findFileDisplayId, listFileDisplayIdentities, suspendFileDisplayReconciliation } from '@/lib/file-display-registry';
+import { getWorkspaceDocumentState, getWorkspaceDocumentHistory, replaceWorkspaceDocumentHistoryPath } from '@features/document/public/workspace-api';
 import { getWorkspaceMemoState, updateNoteLinksAfterMove } from '@features/memo/public/workspace-api';
 import { useBrowserColumnStore } from '../store/browser-column-store';
 import { useWorkColumnStore } from '../store/work-column-store';
 import { useWorkspaceRestoreStore } from '../store/workspace-restore-store';
 import { replaceExternalDocumentPath } from './workspace-navigation';
+import { rebaseWorkspaceTargetPath } from '../model/path-move';
 
 /** Apply only a confirmed filesystem rename pair, never a guessed path match. */
 export function applyNotebookPathMove(input: {
@@ -22,7 +23,9 @@ export function applyNotebookPathMove(input: {
     || previousRelative.split('/').includes('..') || nextRelative.split('/').includes('..')) return;
   const previous = `${root}/${previousRelative}`;
   const next = `${root}/${nextRelative}`;
-  updateNoteLinksAfterMove(previous, next, input.directory);
+  if (input.directory || /\.(?:md|markdown)$/i.test(previous)) {
+    updateNoteLinksAfterMove(previous, next, input.directory);
+  }
   const movedPath = (candidate: string): string | null => {
     const path = canonicalPath(candidate);
     if (path === previous) return next;
@@ -33,18 +36,48 @@ export function applyNotebookPathMove(input: {
   const document = getWorkspaceDocumentState().activeExternalSession;
   const navigation = useWorkColumnStore.getState().navigation;
   const desired = useWorkspaceRestoreStore.getState().desiredTarget;
-  const candidates = [document?.fileIdentity.path];
+  const candidates = [document?.fileIdentity.path, ...listFileDisplayIdentities().map((identity) => identity.path)];
+  for (const entry of getWorkspaceDocumentHistory()) {
+    if (entry.kind === 'external') candidates.push(entry.path);
+    if (entry.kind === 'media') candidates.push(entry.filePath);
+  }
   for (const target of [navigation.target, navigation.pendingTarget, navigation.previousTarget, desired]) {
     if (target?.kind === 'external') candidates.push(target.path);
   }
   for (const tab of useBrowserColumnStore.getState().tabs) {
     if (tab.target.kind === 'file-browser') candidates.push(tab.target.activeFilePath ?? undefined);
   }
-  for (const path of new Set(candidates.filter((value): value is string => Boolean(value)))) {
-    const replacement = movedPath(path);
-    const displayId = findFileDisplayId(path);
-    if (replacement && displayId) replaceExternalDocumentPath(displayId, path, replacement);
-  }
+  const resume = suspendFileDisplayReconciliation();
+  try {
+    for (const path of new Set(candidates.filter((value): value is string => Boolean(value)))) {
+      const replacement = movedPath(path);
+      if (!replacement) continue;
+      const displayId = findFileDisplayId(path);
+      if (displayId) replaceExternalDocumentPath(displayId, path, replacement);
+      replaceWorkspaceDocumentHistoryPath(path, replacement);
+    }
+    const workspace = useWorkColumnStore.getState();
+    const navigation = workspace.navigation;
+    const rebase = <T extends Parameters<typeof rebaseWorkspaceTargetPath>[0]>(target: T) =>
+      rebaseWorkspaceTargetPath(target, previous, next, input.directory);
+    const target = rebase(navigation.target);
+    const pendingTarget = navigation.pendingTarget ? rebase(navigation.pendingTarget) : null;
+    const previousTarget = navigation.previousTarget ? rebase(navigation.previousTarget) : null;
+    if (target !== navigation.target || pendingTarget !== navigation.pendingTarget || previousTarget !== navigation.previousTarget) {
+      useWorkColumnStore.setState({ navigation: { ...navigation, target, pendingTarget, previousTarget } });
+    }
+    const browser = useBrowserColumnStore.getState();
+    const tabs = browser.tabs.map((tab) => {
+      const target = rebase(tab.target);
+      return target === tab.target ? tab : { ...tab, target };
+    });
+    if (tabs.some((tab, index) => tab !== browser.tabs[index])) useBrowserColumnStore.setState({ tabs });
+    const desired = useWorkspaceRestoreStore.getState().desiredTarget;
+    if (desired) {
+      const updated = rebase(desired);
+      if (updated !== desired) useWorkspaceRestoreStore.getState().setDesiredTarget(updated);
+    }
+  } finally { resume(); }
 
   const memo = getWorkspaceMemoState();
   const selected = memo.selectedNote;
diff --git a/app/flowix-web/features/workspace/use-cases/prepare-browser-document-for-work.ts b/app/flowix-web/features/workspace/use-cases/prepare-browser-document-for-work.ts
new file mode 100644
index 000000000..bc8d860c1
--- /dev/null
+++ b/app/flowix-web/features/workspace/use-cases/prepare-browser-document-for-work.ts
@@ -0,0 +1,21 @@
+import type { ContentIdentity } from '../model/surface-identity';
+import { useBrowserColumnStore } from '../store/browser-column-store';
+import { getWorkspaceSurfaceLifecycle } from '../store/surface-lifecycle-store';
+import { findWorkspaceContentLocations } from './workspace-content-activation';
+import { flushActiveBrowserColumnDocument } from './browser-column-coordinator';
+
+export async function flushBrowserViewBeforeOpeningWork(identity: ContentIdentity): Promise<boolean> {
+  const browserLocation = findWorkspaceContentLocations(identity).browserColumn;
+  if (!browserLocation) return true;
+  const lifecycle = getWorkspaceSurfaceLifecycle(browserLocation.tabId);
+  if (lifecycle?.status === 'ready' && lifecycle.flush) {
+    try { return await lifecycle.flush(); }
+    catch { return false; }
+  }
+  if (useBrowserColumnStore.getState().activeTabId === browserLocation.tabId) {
+    return flushActiveBrowserColumnDocument();
+  }
+  // Inactive tabs have already crossed the coordinator's flush barrier when
+  // they were hidden; their renderer is not mounted and cannot hold a live edit.
+  return true;
+}
diff --git a/app/flowix-web/features/workspace/use-cases/surface-opening.test.ts b/app/flowix-web/features/workspace/use-cases/surface-opening.test.ts
new file mode 100644
index 000000000..2cc075834
--- /dev/null
+++ b/app/flowix-web/features/workspace/use-cases/surface-opening.test.ts
@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  openWork: vi.fn(), openBrowser: vi.fn(),
+  prepareDocumentLeave: vi.fn(),
+  workIdentity: null as { kind: 'external'; path: string } | null,
+}));
+vi.mock('./workspace-navigation', () => ({
+  openExternalTarget: mocks.openWork,
+  prepareActiveWorkColumnDocumentLeave: mocks.prepareDocumentLeave,
+  openCollectionTarget: vi.fn(),
+  openMediaLibraryTarget: vi.fn(), openMediaTarget: vi.fn(),
+  openPluginWorkbench: vi.fn(), openTableTarget: vi.fn(), openWebTarget: vi.fn(),
+}));
+vi.mock('./browser-column-navigation', () => ({
+  openBrowserColumnTarget: mocks.openBrowser,
+  createFileBrowserTarget: (path: string, scopePath: string | null) => ({
+    kind: 'file-browser', activeFilePath: path, scopePath, folderPath: null,
+    notebookId: null, fileTreeVisible: true, fileTreeWidth: 220,
+  }),
+}));
+vi.mock('./agent-conversation-navigation', () => ({ selectAndOpenAgentConversation: vi.fn() }));
+vi.mock('../store/work-column-store', () => ({
+  useWorkColumnStore: { getState: () => ({ navigation: { target: { kind: 'empty' } } }) },
+}));
+vi.mock('./workspace-content-activation', () => ({
+  workColumnTargetIdentity: () => mocks.workIdentity,
+  findWorkspaceContentLocations: () => ({ browserColumn: null }),
+  findWorkspaceContentForNavigation: (identity: { kind: 'external'; path: string }) =>
+    mocks.workIdentity?.path === identity.path ? { host: 'main-third', state: 'active' } : null,
+  browserColumnTargetIdentity: (target: { activeFilePath: string }) => ({ kind: 'external', path: target.activeFilePath }),
+}));
+vi.mock('@platform/tauri/client', () => ({ collections: {}, notebooks: {} }));
+
+import { openWorkspaceSurface } from './surface-opening';
+
+describe('public surface opening host contract', () => {
+  const target = { kind: 'external' as const, path: '/notes/a.md', scopePath: '/notes' };
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.prepareDocumentLeave.mockResolvedValue(undefined);
+    mocks.workIdentity = null;
+    mocks.openWork.mockImplementation(async (path: string) => { mocks.workIdentity = { kind: 'external', path }; });
+    mocks.openBrowser.mockResolvedValue({ host: 'browser-column', tabId: 'a', alreadyOpen: true });
+  });
+
+  it('defaults to Work without requiring a store transaction ID', async () => {
+    await expect(openWorkspaceSurface({ target })).resolves.toEqual({
+      status: 'opened', host: 'main-third', location: { host: 'main-third', state: 'active' },
+    });
+    expect(mocks.openWork).toHaveBeenCalledWith(target.path, expect.objectContaining({ destination: 'main-third' }));
+    expect(mocks.openBrowser).not.toHaveBeenCalled();
+  });
+
+  it('keeps explicit Browser opens in Browser and forwards notebook context', async () => {
+    await expect(openWorkspaceSurface({ host: 'browser-column', target, options: { notebookId: 'book' } }))
+      .resolves.toEqual({ status: 'activated', host: 'browser-column', location: { host: 'browser-column', tabId: 'a' } });
+    expect(mocks.openBrowser).toHaveBeenCalledWith(expect.objectContaining({ notebookId: 'book', activeFilePath: target.path }), undefined);
+    expect(mocks.openWork).not.toHaveBeenCalled();
+  });
+
+  it('publishes Work changes before opening a second view of the same content', async () => {
+    mocks.workIdentity = { kind: 'external', path: target.path };
+    await openWorkspaceSurface({ host: 'browser-column', target });
+    expect(mocks.prepareDocumentLeave).toHaveBeenCalledOnce();
+    expect(mocks.prepareDocumentLeave.mock.invocationCallOrder[0]).toBeLessThan(mocks.openBrowser.mock.invocationCallOrder[0]);
+  });
+
+  it('preserves a cancelled Browser navigation result', async () => {
+    mocks.openBrowser.mockResolvedValue(null);
+    await expect(openWorkspaceSurface({ host: 'browser-column', target })).resolves.toEqual({
+      status: 'cancelled', host: 'browser-column', reason: 'navigation-cancelled',
+    });
+    expect(mocks.openWork).not.toHaveBeenCalled();
+  });
+
+  it('reports a Work navigation superseded before its target becomes active as cancelled', async () => {
+    mocks.openWork.mockImplementation(async () => undefined);
+    await expect(openWorkspaceSurface({ target })).resolves.toEqual({
+      status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled',
+    });
+  });
+});
diff --git a/app/flowix-web/features/workspace/use-cases/surface-opening.ts b/app/flowix-web/features/workspace/use-cases/surface-opening.ts
new file mode 100644
index 000000000..755862edd
--- /dev/null
+++ b/app/flowix-web/features/workspace/use-cases/surface-opening.ts
@@ -0,0 +1,326 @@
+import { canOpenBrowserColumnTargetInWorkColumn, useBrowserColumnStore, type BrowserColumnTarget } from '../store/browser-column-store';
+import type { BrowserSurfaceOpenDisposition } from '../model/surface-opening';
+import type {
+  OpenWorkspaceSurfaceRequest, WorkWorkspaceSurfaceRequest, BrowserWorkspaceSurfaceRequest,
+  WorkWorkspaceOpenResult, BrowserWorkspaceOpenResult, WorkspaceContentLocation, WorkspaceSurfaceOpenResult,
+} from '../model/surface-opening';
+import type { WorkWorkspaceSurfaceTarget, BrowserWorkspaceSurfaceTarget, CollectionReferenceSurfaceTarget } from '../model/surface-target';
+export type * from '../model/surface-opening';
+export type { WorkspaceSurfaceOpenTarget, BrowserWorkspaceSurfaceTarget, CollectionReferenceSurfaceTarget } from '../model/surface-target';
+import { contentIdentityKey } from '../model/surface-identity';
+import type { ContentIdentity } from '../model/surface-identity';
+import { useWorkColumnStore } from '../store/work-column-store';
+import type { WorkspaceSurfaceHost, WorkspaceSurfaceKind } from '../surface-registry';
+import { collections, notebooks } from '@platform/tauri/client';
+import { ensureCollectionDisplay, findCollectionDisplayPath } from '@/lib/collection-display-registry';
+import {
+  resolveWorkspaceFileSurfaceKind,
+  workspaceFileSurfaceKind,
+  workspaceSurfaceSupportsHost,
+} from '../surface-registry';
+import {
+  createFileBrowserTarget,
+  openBrowserColumnTarget,
+} from './browser-column-navigation';
+import {
+  openCollectionTarget,
+  openFolderCollectionChooserTarget,
+  openExternalTarget,
+  openMediaLibraryTarget,
+  openMediaTarget,
+  openPluginWorkbench,
+  openTableTarget,
+  openWebTarget,
+  prepareActiveWorkColumnDocumentLeave,
+} from './workspace-navigation';
+import { selectAndOpenAgentConversation } from './agent-conversation-navigation';
+import { browserColumnTargetIdentity, workColumnTargetIdentity, findWorkspaceContentForNavigation } from './workspace-content-activation';
+import { flushBrowserViewBeforeOpeningWork } from './prepare-browser-document-for-work';
+
+function fileKind(path: string): WorkspaceSurfaceKind {
+  return workspaceFileSurfaceKind(resolveWorkspaceFileSurfaceKind(path));
+}
+
+function workTargetSurfaceKind(target: WorkWorkspaceSurfaceTarget): WorkspaceSurfaceKind {
+  switch (target.kind) {
+    case 'folder-collection': return 'collection';
+    case 'external': return fileKind(target.path);
+    case 'table': return 'file-table';
+    case 'media-library': return 'file-media-library';
+    case 'collection': return target.collectionType === 'table' ? 'file-table' : 'file-media-library';
+    case 'collection-reference': return target.collectionKind === 'media_library' ? 'file-media-library' : 'file-table';
+    case 'media': return 'media';
+    case 'agent-conversation': return 'agent-conversation';
+    case 'web': return 'web';
+    case 'plugin-workbench': return 'plugin-workbench';
+  }
+}
+
+function workTargetIdentity(target: WorkWorkspaceSurfaceTarget): ContentIdentity | null {
+  switch (target.kind) {
+    case 'folder-collection': return { kind: 'folder-collection', notebookId: target.notebookId, folderPath: target.folderPath };
+    case 'external': return { kind: 'external', path: target.path };
+    case 'table': case 'media-library': return { kind: 'external', path: target.filePath };
+    case 'collection': return { kind: 'collection', notebookId: target.notebookId, collectionId: target.collectionId, viewId: target.viewId };
+    case 'collection-reference': return { kind: 'collection', notebookId: target.notebookId, collectionId: target.collectionId, viewId: target.viewId ?? null };
+    case 'media': return { kind: 'media', path: target.filePath };
+    case 'agent-conversation': return { kind: 'agent-conversation', instanceId: target.instanceId };
+    case 'web': return { kind: 'web', url: target.url };
+    case 'plugin-workbench': return null;
+  }
+}
+
+function browserTargetSurfaceKind(target: BrowserColumnTarget): WorkspaceSurfaceKind {
+  switch (target.kind) {
+    case 'folder-collection': return 'collection';
+    case 'media': return 'media';
+    case 'web': return 'web';
+    case 'agent_conversation': return 'agent-conversation';
+    case 'file-browser':
+      if (!target.activeFilePath) return 'file-browser';
+      if (target.collectionType === 'table' || /\.table\.ya?ml$/i.test(target.activeFilePath)) return 'file-table';
+      if (target.collectionType === 'media_library' || /\.lib\.ya?ml$/i.test(target.activeFilePath)) return 'file-media-library';
+      if (/\.index\.yaml$/i.test(target.activeFilePath)) return 'file-browser';
+      return fileKind(target.activeFilePath);
+  }
+}
+
+function browserTargetFromOpenTarget(
+  target: Exclude<BrowserWorkspaceSurfaceTarget, CollectionReferenceSurfaceTarget>,
+  notebookId?: string | null,
+): BrowserColumnTarget {
+  switch (target.kind) {
+    case 'folder-collection':
+      return target;
+    case 'file-browser':
+      return target;
+    case 'external':
+      return {
+        ...createFileBrowserTarget(target.path, target.scopePath),
+        ...target.fileBrowser,
+        ...(notebookId !== undefined ? { notebookId } : {}),
+      };
+    case 'table':
+      return { ...createFileBrowserTarget(target.filePath, target.notebookPath), notebookId: target.notebookId };
+    case 'media-library':
+      return {
+        ...createFileBrowserTarget(target.filePath, target.notebookPath),
+        notebookId: target.notebookId,
+        collectionType: 'media_library',
+      };
+    case 'collection':
+      return {
+        ...createFileBrowserTarget(target.filePath, target.notebookPath),
+        notebookId: target.notebookId,
+        collectionDisplay: target,
+        collectionType: target.collectionType,
+      };
+    case 'media':
+      if (!target.notebookPath?.trim()) throw new Error('Browser media target requires a notebook path');
+      if (!target.notebookId?.trim()) throw new Error('Browser media target requires a notebook ID');
+      return {
+        kind: 'media',
+        filePath: target.filePath,
+        notebookId: target.notebookId,
+        notebookPath: target.notebookPath,
+        resourceKind: target.resourceKind,
+      };
+    case 'agent-conversation':
+      return { kind: 'agent_conversation', instanceId: target.instanceId };
+    case 'web':
+      return { kind: 'web', url: target.url };
+  }
+}
+
+async function openCollectionReferenceInBrowser(
+  target: CollectionReferenceSurfaceTarget,
+  disposition?: BrowserSurfaceOpenDisposition,
+): Promise<BrowserWorkspaceOpenResult> {
+  const notebook = (await notebooks.getAll()).find((candidate) => candidate.id === target.notebookId);
+  if (!notebook) throw new Error('集合所属笔记本不存在');
+  const descriptor = ensureCollectionDisplay({
+    notebookId: target.notebookId,
+    collectionId: target.collectionId,
+    viewId: target.viewId ?? null,
+  }, target.displayId);
+  const root = notebook.path.replace(/[\\/]+$/, '');
+  let path = target.filePath || (target.relativePathHint ? `${root}/${target.relativePathHint}` : null)
+    || findCollectionDisplayPath(descriptor.displayId);
+  let collectionType = target.collectionKind;
+  try {
+    const collection = await collections.resolve(target.notebookId, target.collectionId);
+    path = `${root}/${collection.relativePath}`;
+    collectionType = collection.collectionType;
+  } catch (error) {
+    if (!path) throw error;
+  }
+  if (!path) throw new Error('集合文件路径已丢失，请从文件树重新打开此文件');
+  return openBrowserTarget({
+    ...createFileBrowserTarget(path, notebook.path, notebook.path),
+    notebookId: target.notebookId,
+    collectionDisplay: descriptor,
+    collectionType,
+  }, disposition);
+}
+
+function activeWorkLocation(): Extract<WorkspaceContentLocation, { host: 'main-third' }> {
+  return { host: 'main-third', state: 'active' };
+}
+
+function assertHostSupport(kind: WorkspaceSurfaceKind, host: WorkspaceSurfaceHost): void {
+  if (!workspaceSurfaceSupportsHost(kind, host)) {
+    throw new Error(`Surface '${kind}' is not supported in '${host}'`);
+  }
+}
+
+async function openBrowserTarget(
+  target: BrowserColumnTarget,
+  disposition?: BrowserSurfaceOpenDisposition,
+): Promise<BrowserWorkspaceOpenResult> {
+  assertHostSupport(browserTargetSurfaceKind(target), 'browser-column');
+  if (target.kind !== 'agent_conversation') {
+    const requestedIdentity = browserColumnTargetIdentity(target);
+    const activeWorkIdentity = workColumnTargetIdentity(useWorkColumnStore.getState().navigation.target);
+    if (activeWorkIdentity && contentIdentityKey(activeWorkIdentity) === contentIdentityKey(requestedIdentity)) {
+      await prepareActiveWorkColumnDocumentLeave();
+    }
+  }
+  const result = await openBrowserColumnTarget(target, disposition);
+  return result
+    ? { status: result.alreadyOpen ? 'activated' : 'opened', host: 'browser-column', location: { host: 'browser-column', tabId: result.tabId } }
+    : { status: 'cancelled', host: 'browser-column', reason: 'navigation-cancelled' };
+}
+
+export function openWorkspaceSurface(request: BrowserWorkspaceSurfaceRequest): Promise<BrowserWorkspaceOpenResult>;
+export function openWorkspaceSurface(request: WorkWorkspaceSurfaceRequest): Promise<WorkWorkspaceOpenResult>;
+export function openWorkspaceSurface(request: OpenWorkspaceSurfaceRequest): Promise<BrowserWorkspaceOpenResult | WorkWorkspaceOpenResult>;
+/** Route a shared surface target through the selected host adapter. */
+export async function openWorkspaceSurface(
+  request: OpenWorkspaceSurfaceRequest,
+): Promise<BrowserWorkspaceOpenResult | WorkWorkspaceOpenResult> {
+  if (request.host === 'browser-column') {
+    const target = request.target;
+    if (target.kind === 'collection-reference') {
+      assertHostSupport(target.collectionKind === 'media_library' ? 'file-media-library' : 'file-table', 'browser-column');
+      return openCollectionReferenceInBrowser(target, request.options?.browserDisposition);
+    }
+    const resolvedTarget = browserTargetFromOpenTarget(target, request.options?.notebookId);
+    return openBrowserTarget(resolvedTarget, request.options?.browserDisposition);
+  }
+
+  const target = request.target;
+  const kind = workTargetSurfaceKind(target);
+  assertHostSupport(kind, 'main-third');
+  const options = request.options;
+  const identity = workTargetIdentity(target);
+  const previousLocation = identity ? findWorkspaceContentForNavigation(identity, 'main-third') : null;
+  if (target.kind !== 'external' && !(previousLocation?.host === 'main-third' && previousLocation.state === 'active') && identity
+    && identity.kind !== 'media' && identity.kind !== 'web' && identity.kind !== 'agent-conversation') {
+    if (!await flushBrowserViewBeforeOpeningWork(identity)) {
+      return { status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' };
+    }
+  }
+  const previousWorkTarget = useWorkColumnStore.getState().navigation.target;
+  const pluginWasOpen = target.kind === 'plugin-workbench'
+    && previousWorkTarget.kind === 'plugin-workbench'
+    && previousWorkTarget.plugin.manifest.id === target.plugin.manifest.id;
+  const finishWorkOpen = (): WorkWorkspaceOpenResult => {
+    const navigationTarget = useWorkColumnStore.getState().navigation.target;
+    const pluginMatches = target.kind === 'plugin-workbench'
+      && navigationTarget.kind === 'plugin-workbench'
+      && navigationTarget.plugin.manifest.id === target.plugin.manifest.id;
+    const location = identity
+      ? findWorkspaceContentForNavigation(identity, 'main-third')
+      : pluginMatches ? activeWorkLocation() : null;
+    if (!location || location.host !== 'main-third' || location.state === 'pending') {
+      return { status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' };
+    }
+    return { status: previousLocation || pluginWasOpen ? 'activated' : 'opened', host: 'main-third', location };
+  };
+  switch (target.kind) {
+    case 'folder-collection':
+      await openFolderCollectionChooserTarget(target);
+      return finishWorkOpen();
+    case 'external': {
+      await openExternalTarget(target.path, {
+        scopePath: target.scopePath,
+        fileBrowser: target.fileBrowser,
+        history: options?.history,
+        notebookId: options?.notebookId,
+        markdownLocation: options?.markdownLocation,
+        initialFocus: options?.initialFocus,
+        destination: 'main-third',
+      });
+      return finishWorkOpen();
+    }
+    case 'table':
+      await openTableTarget(target.filePath, target.notebookPath, target.notebookId, { history: options?.history, destination: 'main-third' });
+      return finishWorkOpen();
+    case 'media-library':
+      await openMediaLibraryTarget(target.filePath, target.notebookPath, target.notebookId, { history: options?.history, destination: 'main-third' });
+      return finishWorkOpen();
+    case 'collection':
+      await openCollectionTarget(target, { history: options?.history, destination: 'main-third', refresh: options?.refresh });
+      return finishWorkOpen();
+    case 'collection-reference':
+      await openCollectionTarget(target, { history: options?.history, destination: 'main-third', refresh: options?.refresh });
+      return finishWorkOpen();
+    case 'media':
+      await openMediaTarget({ ...target, history: options?.history, destination: 'main-third' });
+      return finishWorkOpen();
+    case 'agent-conversation': {
+      await selectAndOpenAgentConversation(target.instanceId, {
+        history: options?.history,
+        destination: 'main-third',
+        ...(target.blankIfMissing ? { blankIfMissing: true as const } : {}),
+      });
+      return finishWorkOpen();
+    }
+    case 'web':
+      await openWebTarget(target.url, { history: options?.history, destination: 'main-third' });
+      return finishWorkOpen();
+    case 'plugin-workbench':
+      await openPluginWorkbench(target.plugin);
+      return finishWorkOpen();
+  }
+}
+
+/** Open a Browser tab as an additional Work view through the shared protocol. */
+export async function openBrowserColumnTabInWorkColumn(
+  tabId: string,
+): Promise<WorkspaceSurfaceOpenResult> {
+  const tab = useBrowserColumnStore.getState().tabs.find((candidate) => candidate.id === tabId);
+  if (!tab || !canOpenBrowserColumnTargetInWorkColumn(tab.target)) {
+    return { status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' };
+  }
+  const target: WorkWorkspaceSurfaceTarget | null = (() => {
+    switch (tab.target.kind) {
+      case 'folder-collection': return tab.target;
+      case 'file-browser':
+        if (tab.target.collectionDisplay) return {
+          kind: 'collection-reference',
+          notebookId: tab.target.collectionDisplay.notebookId,
+          collectionId: tab.target.collectionDisplay.collectionId,
+          viewId: tab.target.collectionDisplay.viewId,
+          displayId: tab.target.collectionDisplay.displayId,
+          filePath: tab.target.activeFilePath ?? undefined,
+        };
+        if (!tab.target.activeFilePath) return null;
+        return {
+          kind: 'external', path: tab.target.activeFilePath,
+          scopePath: tab.target.scopePath, fileBrowser: tab.target,
+        };
+      case 'media':
+        return {
+          kind: 'media', filePath: tab.target.filePath, notebookId: tab.target.notebookId,
+          notebookPath: tab.target.notebookPath, resourceKind: tab.target.resourceKind,
+        };
+      case 'web': return { kind: 'web', url: tab.target.url };
+      case 'agent_conversation': return { kind: 'agent-conversation', instanceId: tab.target.instanceId };
+    }
+  })();
+  if (!target) return { status: 'cancelled', host: 'main-third', reason: 'navigation-cancelled' };
+  return openWorkspaceSurface({ host: 'main-third', target });
+}
+
+export type { WorkspaceSurfaceHost };
diff --git a/app/flowix-web/features/workspace/use-cases/workspace-content-activation.ts b/app/flowix-web/features/workspace/use-cases/workspace-content-activation.ts
index 04706af71..9b0978292 100644
--- a/app/flowix-web/features/workspace/use-cases/workspace-content-activation.ts
+++ b/app/flowix-web/features/workspace/use-cases/workspace-content-activation.ts
@@ -12,12 +12,18 @@ import { useWorkspaceFocusStore } from '@features/workspace/store/workspace-focu
 import { getWorkColumnContentState } from '@features/workspace/store/work-column-content-state';
 import { activateBrowserColumnTab } from './browser-column-coordinator';
 
-export type WorkspaceContentLocation =
-  | { host: 'main-third'; state: 'active' | 'pending' }
-  | { host: 'browser-column'; tabId: string };
+import type { WorkspaceContentLocation } from '../model/surface-opening';
+export type { WorkspaceContentLocation } from '../model/surface-opening';
+
+export interface WorkspaceContentLocations {
+  workColumn: Extract<WorkspaceContentLocation, { host: 'main-third' }> | null;
+  browserColumn: Extract<WorkspaceContentLocation, { host: 'browser-column' }> | null;
+}
 
 export function workColumnTargetIdentity(target: WorkColumnTarget): ContentIdentity | null {
   switch (target.kind) {
+    case 'folder-collection':
+      return { kind: 'folder-collection', notebookId: target.notebookId, folderPath: target.folderPath };
     case 'media':
       return { kind: 'media', path: target.filePath };
     case 'external':
@@ -50,14 +56,20 @@ function currentCollectionView(location: WorkspaceContentLocation): string | nul
 }
 
 /**
- * Focus an already-open workspace target without opening a second surface.
- * The third column wins when legacy state already contains the target in both
- * columns; normal opens prevent that ambiguous state from being created.
+ * Focus a target in the requested host. Without a host preference, Work is
+ * preferred for legacy callers; callers that care about placement should pass
+ * the host explicitly because the same content may exist in both columns.
  */
 export function activateExistingWorkspaceContent(
   identity: ContentIdentity,
+  host?: WorkspaceContentLocation['host'],
 ): WorkspaceContentLocation | null {
-  const location = findExistingWorkspaceContent(identity);
+  const locations = findWorkspaceContentLocations(identity);
+  const location = host === 'main-third'
+    ? locations.workColumn
+    : host === 'browser-column'
+      ? locations.browserColumn
+      : locations.workColumn ?? locations.browserColumn;
   if (!location) return null;
 
   if (identity.kind === 'collection') {
@@ -79,8 +91,14 @@ export function activateExistingWorkspaceContent(
  */
 export async function activateExistingWorkspaceContentAsync(
   identity: ContentIdentity,
+  host?: WorkspaceContentLocation['host'],
 ): Promise<WorkspaceContentLocation | null> {
-  const location = findExistingWorkspaceContent(identity);
+  const locations = findWorkspaceContentLocations(identity);
+  const location = host === 'main-third'
+    ? locations.workColumn
+    : host === 'browser-column'
+      ? locations.browserColumn
+      : locations.workColumn ?? locations.browserColumn;
   if (!location) return null;
 
   if (location.host === 'main-third') {
@@ -101,20 +119,18 @@ export async function activateExistingWorkspaceContentAsync(
   return activated ? location : null;
 }
 
-/** Read the existing location without changing focus or active tab. */
-export function findExistingWorkspaceContent(
+/** Find matching content independently in each workspace host. */
+export function findWorkspaceContentLocations(
   identity: ContentIdentity,
-): WorkspaceContentLocation | null {
+): WorkspaceContentLocations {
   const key = contentIdentityKey(identity);
-  if (!key) return null;
+  if (!key) return { workColumn: null, browserColumn: null };
 
   const workColumn = getWorkColumnContentState();
   const pendingIdentity = workColumn.status === 'transitioning'
     ? workColumnTargetIdentity(workColumn.to)
     : null;
-  if (pendingIdentity && contentIdentityKey(pendingIdentity) === key) {
-    return { host: 'main-third', state: 'pending' };
-  }
+  const pendingMatch = pendingIdentity && contentIdentityKey(pendingIdentity) === key;
 
   const workTarget = workColumn.status === 'empty'
     ? null
@@ -122,9 +138,7 @@ export function findExistingWorkspaceContent(
       ? workColumn.from
       : workColumn.target;
   const workIdentity = workTarget ? workColumnTargetIdentity(workTarget) : null;
-  if (workIdentity && contentIdentityKey(workIdentity) === key) {
-    return { host: 'main-third', state: 'active' };
-  }
+  const activeMatch = workIdentity && contentIdentityKey(workIdentity) === key;
 
   const browserColumn = useBrowserColumnStore.getState();
   const matchingTabs = browserColumn.tabs.filter(
@@ -132,6 +146,29 @@ export function findExistingWorkspaceContent(
   );
   const tab = matchingTabs.find((candidate) => candidate.id === browserColumn.activeTabId)
     ?? matchingTabs[0];
-  if (!tab) return null;
-  return { host: 'browser-column', tabId: tab.id };
+  return {
+    workColumn: pendingMatch
+      ? { host: 'main-third', state: 'pending' }
+      : activeMatch ? { host: 'main-third', state: 'active' } : null,
+    browserColumn: tab ? { host: 'browser-column', tabId: tab.id } : null,
+  };
+}
+
+/** Legacy single-location lookup. Prefer host-specific location queries. */
+export function findExistingWorkspaceContent(
+  identity: ContentIdentity,
+): WorkspaceContentLocation | null {
+  const locations = findWorkspaceContentLocations(identity);
+  return locations.workColumn ?? locations.browserColumn;
+}
+
+/** Resolve an existing location in the requested host; unspecified opens target Work. */
+export function findWorkspaceContentForNavigation(
+  identity: ContentIdentity,
+  destination?: WorkspaceContentLocation['host'],
+): WorkspaceContentLocation | null {
+  const locations = findWorkspaceContentLocations(identity);
+  if (destination === 'main-third') return locations.workColumn;
+  if (destination === 'browser-column') return locations.browserColumn;
+  return locations.workColumn;
 }
diff --git a/app/flowix-web/features/workspace/use-cases/workspace-host-focus.test.tsx b/app/flowix-web/features/workspace/use-cases/workspace-host-focus.test.tsx
new file mode 100644
index 000000000..01ec610ca
--- /dev/null
+++ b/app/flowix-web/features/workspace/use-cases/workspace-host-focus.test.tsx
@@ -0,0 +1,55 @@
+import { act } from 'react';
+import { createPortal } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { afterEach, expect, it, vi } from 'vitest';
+import { focusWorkspaceHostFromEvent } from './workspace-host-focus';
+import { useWorkspaceFocusStore } from '../store/workspace-focus-store';
+import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@shared/ui/context-menu';
+
+afterEach(() => useWorkspaceFocusStore.getState().reset());
+
+it('does not notify subscribers for repeated activation of the current host', () => {
+  const onChange = vi.fn();
+  const unsubscribe = useWorkspaceFocusStore.subscribe(onChange);
+  try {
+    useWorkspaceFocusStore.getState().focusHost('main-third');
+    expect(onChange).not.toHaveBeenCalled();
+    useWorkspaceFocusStore.getState().focusHost('browser-column');
+    useWorkspaceFocusStore.getState().focusHost('browser-column');
+    expect(onChange).toHaveBeenCalledTimes(1);
+  } finally { unsubscribe(); }
+});
+
+it('ignores real portal focus/pointer capture while allowing host DOM interaction', async () => {
+  const container = document.createElement('div');
+  const portal = document.createElement('div');
+  document.body.append(container, portal);
+  const root = createRoot(container);
+  const activate = (event: { currentTarget: HTMLElement; target: EventTarget | null }) => focusWorkspaceHostFromEvent(event, 'main-third');
+  try {
+    await act(async () => root.render(<div onFocusCapture={activate} onPointerDownCapture={activate}>
+      <input data-testid="inside" />
+      {createPortal(<input data-testid="portal" />, portal)}
+      <ContextMenu><ContextMenuTrigger asChild><div data-testid="card">Card</div></ContextMenuTrigger>
+        <ContextMenuContent><ContextMenuItem>Copy</ContextMenuItem></ContextMenuContent>
+      </ContextMenu>
+    </div>));
+    useWorkspaceFocusStore.getState().focusHost('browser-column');
+    const popupInput = portal.querySelector<HTMLInputElement>('input')!;
+    await act(async () => {
+      popupInput.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+      popupInput.focus();
+    });
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
+    await act(async () => container.querySelector('[data-testid="card"]')!.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true })));
+    expect(document.activeElement?.getAttribute('role')).toBe('menu');
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
+    await act(async () => document.querySelector('[role="menuitem"]')!.dispatchEvent(new Event('pointerdown', { bubbles: true })));
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('browser-column');
+    await act(async () => container.querySelector<HTMLInputElement>('[data-testid="inside"]')!.focus());
+    expect(useWorkspaceFocusStore.getState().focusedHostId).toBe('main-third');
+  } finally {
+    await act(async () => root.unmount());
+    container.remove(); portal.remove();
+  }
+});
diff --git a/app/flowix-web/features/workspace/use-cases/workspace-host-focus.ts b/app/flowix-web/features/workspace/use-cases/workspace-host-focus.ts
new file mode 100644
index 000000000..a17b2edb8
--- /dev/null
+++ b/app/flowix-web/features/workspace/use-cases/workspace-host-focus.ts
@@ -0,0 +1,11 @@
+import { useWorkspaceFocusStore } from '../store/workspace-focus-store';
+import type { WorkspaceSurfaceHost } from '../model/surface-contract';
+
+/** React portals share ancestors in React, but do not interact with the host DOM. */
+export function focusWorkspaceHostFromEvent(
+  event: { currentTarget: HTMLElement; target: EventTarget | null },
+  host: WorkspaceSurfaceHost,
+): void {
+  if (!(event.target instanceof Node) || !event.currentTarget.contains(event.target)) return;
+  useWorkspaceFocusStore.getState().focusHost(host);
+}
diff --git a/app/flowix-web/features/workspace/use-cases/workspace-navigation.test.ts b/app/flowix-web/features/workspace/use-cases/workspace-navigation.test.ts
index c96a69407..6e79579f5 100644
--- a/app/flowix-web/features/workspace/use-cases/workspace-navigation.test.ts
+++ b/app/flowix-web/features/workspace/use-cases/workspace-navigation.test.ts
@@ -16,12 +16,13 @@ const mocks = vi.hoisted(() => ({
   replaceActiveMemoPath: vi.fn(),
   discardMemoDocument: vi.fn(),
   closeAgentConversation: vi.fn(),
-  flushDocumentPath: vi.fn(),
+  prepareDocumentLeave: vi.fn(),
   setCurrentNotebook: vi.fn(),
   beginNavigation: vi.fn().mockReturnValue(1),
   commitNavigation: vi.fn().mockReturnValue(true),
   failNavigation: vi.fn().mockReturnValue(true),
   isCurrentNavigation: vi.fn().mockReturnValue(true),
+  navigationRevision: 1,
   navigationTarget: pluginWorkbenchTarget('plugin-a') as WorkColumnTarget,
   memoState: {
     selectedNotebook: null as { id: string; path: string } | null,
@@ -60,7 +61,7 @@ vi.mock('@features/document/store/document-store', () => ({
 }));
 
 vi.mock('@features/document/store/document-session-service', () => ({
-  flushDocumentPath: mocks.flushDocumentPath,
+  prepareDocumentLeave: mocks.prepareDocumentLeave,
 }));
 
 vi.mock('@platform/tauri/client', () => ({
@@ -72,7 +73,7 @@ vi.mock('@platform/tauri/client', () => ({
 vi.mock('@features/workspace/store/work-column-store', () => ({
   useWorkColumnStore: {
     getState: () => ({
-      navigation: { phase: 'committed', showWorkColumnLoading: false, requestId: 1, target: mocks.navigationTarget, pendingTarget: null, previousTarget: null, failure: null, retryToken: null },
+      navigation: { phase: 'committed', showWorkColumnLoading: false, requestId: mocks.navigationRevision, target: mocks.navigationTarget, pendingTarget: null, previousTarget: null, failure: null, retryToken: null },
       beginNavigation: mocks.beginNavigation,
       commitNavigation: mocks.commitNavigation,
       failNavigation: mocks.failNavigation,
@@ -88,20 +89,103 @@ vi.mock('@features/memo/store/note-store', () => ({
 }));
 
 import {
+  captureWorkspaceRestoreTarget,
   closePluginWorkbench,
   openPluginWorkbench,
 } from './workspace-navigation';
 
 describe('workspace navigation', () => {
+  it('does not replace user navigation after a delayed Markdown restore lookup', async () => {
+    const { notes } = await import('@platform/tauri/client');
+    const { restoreExternalDocumentWorkspace } = await import('./workspace-navigation');
+    let finish!: (value: Awaited<ReturnType<typeof notes.resolveLocation>>) => void;
+    vi.mocked(notes.resolveLocation).mockImplementationOnce(() => new Promise((resolve) => { finish = resolve; }));
+    const restored = restoreExternalDocumentWorkspace({ kind: 'external', path: '/old.md', scopePath: null });
+    mocks.navigationRevision = 2;
+    finish({ path: '/old.md', notebookId: null, relativePath: null, notebookPath: null, indexable: false });
+    await restored;
+    expect(mocks.beginNavigation).not.toHaveBeenCalled();
+    expect(mocks.openExternalDocument).not.toHaveBeenCalled();
+  });
+
+  it('publishes loading before metadata work and skips a superseded request after yielding', async () => {
+    const { notes } = await import('@platform/tauri/client');
+    const { openExternalTarget } = await import('./workspace-navigation');
+    const opening = openExternalTarget('/new.md', { destination: 'main-third' });
+    expect(mocks.beginNavigation).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: 'external', path: '/new.md' }), expect.any(String), false, true,
+    );
+    expect(notes.resolveLocation).not.toHaveBeenCalled();
+    mocks.isCurrentNavigation.mockReturnValueOnce(false);
+    await opening;
+    expect(notes.resolveLocation).not.toHaveBeenCalled();
+    expect(mocks.openExternalDocument).not.toHaveBeenCalled();
+  });
+
+  it('keeps A selected when B metadata resolves after the user clicks back to A', async () => {
+    const { notes } = await import('@platform/tauri/client');
+    const { openExternalTarget } = await import('./workspace-navigation');
+    const { useWorkColumnStore: mockedStore } = await import('../store/work-column-store');
+    const { useWorkColumnStore: realStore } = await vi.importActual<typeof import('../store/work-column-store')>(
+      '../store/work-column-store',
+    );
+    const previousState = realStore.getState();
+    const getState = vi.spyOn(mockedStore, 'getState').mockImplementation(realStore.getState);
+    realStore.setState({ navigation: {
+      phase: 'committed', showWorkColumnLoading: false, requestId: 10,
+      target: { kind: 'external', path: '/A.md', scopePath: null, transitionId: null },
+      pendingTarget: null, previousTarget: null, failure: null, retryToken: null,
+    } });
+    mocks.documentState.activeExternalSession = {
+      fileIdentity: { displayId: 'test-A', path: '/A.md' }, scopePath: null, transitionId: 1,
+    };
+    let finishB!: () => void;
+    const previousResolveLocation = vi.mocked(notes.resolveLocation).getMockImplementation();
+    vi.mocked(notes.resolveLocation).mockImplementation((path) => {
+      const location = { path, notebookId: null, relativePath: null, notebookPath: null, indexable: false };
+      return path === '/B.md'
+        ? new Promise((resolve) => { finishB = () => resolve(location); })
+        : Promise.resolve(location);
+    });
+    const openingB = openExternalTarget('/B.md', { destination: 'main-third' }).catch(() => undefined);
+    try {
+      await vi.waitFor(() => expect(notes.resolveLocation).toHaveBeenCalledWith('/B.md'));
+      await openExternalTarget('/A.md', { destination: 'main-third' });
+      finishB();
+      await openingB;
+      expect(mocks.openExternalDocument.mock.calls.some(([path]) => path === '/B.md')).toBe(false);
+      expect(realStore.getState().navigation).toMatchObject({
+        phase: 'committed', target: { kind: 'external', path: '/A.md' }, pendingTarget: null,
+      });
+    } finally {
+      finishB?.();
+      await openingB;
+      getState.mockRestore();
+      realStore.setState(previousState, true);
+      if (previousResolveLocation) vi.mocked(notes.resolveLocation).mockImplementation(previousResolveLocation);
+    }
+  });
+
+  it('clears a restored notebook target after registry rebuild', async () => {
+    const { useWorkspaceRestoreStore } = await import('../store/workspace-restore-store');
+    useWorkspaceRestoreStore.getState().setDesiredTarget({
+      kind: 'table', notebookId: 'removed-notebook', notebookPath: '/old', filePath: '/old/table.csv',
+    });
+    mocks.memoState.notebooks = [];
+    expect(captureWorkspaceRestoreTarget()).toBeNull();
+    expect(useWorkspaceRestoreStore.getState().desiredTarget).toBeNull();
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
     mocks.clearDocument.mockResolvedValue(undefined);
     mocks.openExternalDocument.mockResolvedValue(undefined);
     mocks.openAgentConversation.mockResolvedValue(undefined);
     mocks.discardMemoDocument.mockResolvedValue(undefined);
-    mocks.flushDocumentPath.mockResolvedValue(true);
+    mocks.prepareDocumentLeave.mockResolvedValue(true);
     mocks.setCurrentNotebook.mockResolvedValue(undefined);
     mocks.navigationTarget = pluginWorkbenchTarget('plugin-a');
+    mocks.navigationRevision = 1;
     mocks.documentState.activeExternalSession = null;
     mocks.documentState.activeAgentConversationId = null;
     mocks.memoState.selectedNotebook = null;
diff --git a/app/flowix-web/features/workspace/use-cases/workspace-navigation.ts b/app/flowix-web/features/workspace/use-cases/workspace-navigation.ts
index e04565d43..6a4379e51 100644
--- a/app/flowix-web/features/workspace/use-cases/workspace-navigation.ts
+++ b/app/flowix-web/features/workspace/use-cases/workspace-navigation.ts
@@ -1,15 +1,17 @@
-import { ensureCollectionDisplay, bindCollectionDisplayPath } from '@/lib/collection-display-registry';
-import { collections, externalDocuments, files } from '@platform/tauri/client';
-import { parseCollectionDocumentV2 } from '@features/collection/model';
+import { flushBrowserViewBeforeOpeningWork } from './prepare-browser-document-for-work';
+import { ensureCollectionDisplay, bindCollectionDisplayPath, findCollectionDisplayPath } from '@/lib/collection-display-registry';
+import { collections, externalDocuments, files, notebooks } from '@platform/tauri/client';
+import { collectionDisplayName, parseCollectionDocumentV2 } from '@features/collection/model';
 import { createFolderCollectionContent } from '@features/collection/folder-collection';
-import { toast } from '@/lib/toast';
+import { repairCollectionFile, inspectCollectionRecoveryType } from '@features/collection/recovery';
 import { captureFileBrowserContext } from './file-browser-context';
 import { notes as notesClient, type PluginDescriptor, type MarkdownLocation } from '@platform/tauri/client';
-import { canonicalDirectoryPath, canonicalPath, samePath } from '@/lib/path';
+import { canonicalDirectoryPath, canonicalPath, isPathInDirectory, joinNotebookMemoPath, notebookRelativeDirectoryPath, samePath } from '@/lib/path';
 import { resourceKindFromPath } from '@features/editor/public/code-file';
 import { canonicalUrl } from '@features/workspace/store/workspace-content-identity';
 import {
-  flushWorkspaceDocumentPath,
+  documentIdentityFromFile,
+  prepareWorkspaceDocumentLeave,
   getWorkspaceDocumentState,
   recordWorkspaceDocumentNavigation,
   replaceWorkspaceDocumentPath,
@@ -18,7 +20,6 @@ import {
 import {
   useBrowserColumnStore,
 } from '@features/workspace/store/browser-column-store';
-import { documentIdentityFromFile } from '@features/document/public/workspace-api';
 import {
   suspendFileDisplayReconciliation,
 } from '@/lib/file-display-registry';
@@ -29,7 +30,9 @@ import {
 } from '@features/memo/public/workspace-api';
 import { useWorkColumnStore } from '@features/workspace/store/work-column-store';
 import { EMPTY_WORK_COLUMN_TARGET, workColumnTargetFilePath } from '@features/workspace/store/work-column-target';
-import type { DocumentListTarget, WorkColumnTarget } from '@features/workspace/store/work-column-target';
+import type { WorkColumnTarget } from '@features/workspace/store/work-column-target';
+import type { FolderCollectionSurfaceTarget } from '../model/surface-target';
+import type { LegacyFolderListTarget } from '../model/legacy-folder-list';
 import {
   useWorkspaceFocusStore,
   type WorkspaceHostId,
@@ -37,7 +40,7 @@ import {
 import {
   activateExistingWorkspaceContent,
   activateExistingWorkspaceContentAsync,
-  findExistingWorkspaceContent,
+  findWorkspaceContentForNavigation,
   type WorkspaceContentLocation,
 } from './workspace-content-activation';
 import type { ContentIdentity } from '@features/workspace/store/workspace-content-identity';
@@ -47,6 +50,8 @@ import {
 } from '@features/workspace/store/workspace-restore-store';
 
 export interface OpenExternalTargetOptions {
+  /** Delayed startup resolution must not replace newer user navigation. */
+  restoreRequestId?: number;
   fileBrowser?: import('../store/file-browser-target').FileBrowserContext;
   /** Explicit cross-column moves must not reactivate a BrowserColumn tab. */
   destination?: 'main-third';
@@ -64,6 +69,8 @@ export interface OpenMediaTargetParams {
   resourceKind?: 'image' | 'video';
   history?: 'push' | 'skip';
   destination?: 'main-third';
+  /** Startup restoration lease, checked before navigation side effects begin. */
+  restoreRequestId?: number;
 }
 
 type RetryAction = () => Promise<void>;
@@ -88,14 +95,20 @@ let retrySequence = 0;
  */
 function activateExistingContentForNavigation(
   identity: ContentIdentity,
+  destination?: WorkspaceContentLocation['host'],
 ): WorkspaceContentLocation | null | Promise<WorkspaceContentLocation | null> {
-  const existing = findExistingWorkspaceContent(identity);
+  const existing = findWorkspaceContentForNavigation(identity, destination);
   if (!existing) return null;
   if (existing.host === 'main-third') {
-    activateExistingWorkspaceContent(identity);
+    // The visible target is not the latest intent while another target loads.
+    // Clicking it must start a new transaction so the pending request is stale.
+    if (existing.state === 'active' && useWorkColumnStore.getState().navigation.phase === 'loading') {
+      return null;
+    }
+    activateExistingWorkspaceContent(identity, existing.host);
     return existing;
   }
-  return activateExistingWorkspaceContentAsync(identity);
+  return activateExistingWorkspaceContentAsync(identity, existing.host);
 }
 
 function pendingExternalTarget(
@@ -161,9 +174,9 @@ function commitNavigation(
         historyEntryFromWorkColumnTarget(target),
       );
     }
-    const desiredTarget: PersistedWorkspaceTarget | null = target.kind === 'collection'
+    const desiredTarget: PersistedWorkspaceTarget | null = target.kind === 'folder-collection'
       ? target
-      : target.kind === 'document-list'
+      : target.kind === 'collection'
       ? target
       : target.kind === 'table'
         ? { kind: 'table', filePath: canonicalPath(target.filePath), notebookPath: target.notebookPath ? canonicalPath(target.notebookPath) : null, notebookId: target.notebookId }
@@ -191,23 +204,32 @@ function commitNavigation(
   return committed;
 }
 
-/** Open a folder/filter list as a first-class work-column history destination. */
-export function openDocumentListTarget(
-  target: DocumentListTarget,
-  options?: { history?: 'push' | 'skip' },
-): void {
-  const requestId = beginNavigation(target, null, false, false);
-  commitNavigation(requestId, target, options?.history ?? 'push');
-}
-
 export function captureWorkspaceRestoreTarget(): PersistedWorkspaceTarget | null {
-  return useWorkspaceRestoreStore.getState().desiredTarget;
+  const target = useWorkspaceRestoreStore.getState().desiredTarget;
+  // Notebook context has loaded before startup captures this target. A rebuilt
+  // registry must not restore a view owned by a notebook that no longer exists.
+  if (target && 'notebookId' in target && target.notebookId
+    && !getWorkspaceMemoState().notebooks.some((notebook) => notebook.id === target.notebookId)) {
+    useWorkspaceRestoreStore.getState().setDesiredTarget(null);
+    return null;
+  }
+  return target;
 }
 
 export async function restoreExternalDocumentWorkspace(
   restored: Extract<PersistedWorkspaceTarget, { kind: 'external' }>,
+  restoreRequestId = useWorkColumnStore.getState().navigation.requestId,
 ): Promise<void> {
+  if (!isRestoreRequestCurrent(restoreRequestId)) return;
+  // Startup restoration must validate its captured revision before beginning a
+  // navigation; an explicit user click can supersede this metadata lookup.
+  const markdownLocation = /\.(md|markdown)$/i.test(restored.path)
+    ? await notesClient.resolveLocation(restored.path)
+    : null;
+  if (!isRestoreRequestCurrent(restoreRequestId)) return;
   await openExternalTarget(restored.path, {
+    restoreRequestId,
+    markdownLocation,
     scopePath: restored.scopePath,
     history: 'skip',
     destination: 'main-third',
@@ -216,45 +238,57 @@ export async function restoreExternalDocumentWorkspace(
 
 export function restoreTableWorkspace(
   restored: Extract<PersistedWorkspaceTarget, { kind: 'table' }>,
+  restoreRequestId = useWorkColumnStore.getState().navigation.requestId,
 ): Promise<void> {
-  return openTableTarget(restored.filePath, restored.notebookPath, restored.notebookId, { history: 'skip' });
+  return openTableTarget(restored.filePath, restored.notebookPath, restored.notebookId, { history: 'skip', restoreRequestId });
 }
 
 export async function openCollectionTarget(
-  reference: { notebookId: string; collectionId: string; viewId?: string | null; displayId?: string; relativePathHint?: string },
-  options?: { history?: 'push' | 'skip'; destination?: 'main-third' },
+  reference: { notebookId: string; collectionId: string; viewId?: string | null; displayId?: string; relativePathHint?: string; filePath?: string },
+  options?: { history?: 'push' | 'skip'; destination?: 'main-third'; refresh?: boolean; restoreRequestId?: number },
 ): Promise<void> {
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
   const { notebookId, collectionId } = reference;
   const identity: ContentIdentity = { kind: 'collection', notebookId, collectionId, viewId: reference.viewId ?? null };
-  if (options?.destination !== 'main-third') {
-    const existing = await activateExistingWorkspaceContentAsync(identity);
+  const navigation = useWorkColumnStore.getState().navigation;
+  const liveTarget = [navigation.pendingTarget, navigation.target].find((target) => target?.kind === 'collection'
+    && target.notebookId === notebookId && target.collectionId === collectionId);
+  const needsResolution = options?.refresh || options?.destination === 'main-third'
+    || (liveTarget?.kind === 'collection' && (liveTarget.unavailableReason || liveTarget.viewId !== identity.viewId));
+  if (!needsResolution) {
+    const existing = await activateExistingContentForNavigation(identity, options?.destination);
+    if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
     if (existing) return;
   }
   const notebook = getWorkspaceMemoState().notebooks.find((item) => item.id === notebookId)
-    ?? (getWorkspaceMemoState().selectedNotebook?.id === notebookId ? getWorkspaceMemoState().selectedNotebook : null);
+    ?? (getWorkspaceMemoState().selectedNotebook?.id === notebookId ? getWorkspaceMemoState().selectedNotebook : null)
+    ?? (await notebooks.getAll()).find((item) => item.id === notebookId);
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
   if (!notebook) throw new Error('集合所属笔记本不存在');
   const descriptor = ensureCollectionDisplay({ notebookId, collectionId, viewId: reference.viewId ?? null }, reference.displayId);
+  const previousTarget = useWorkColumnStore.getState().navigation.target;
+  const knownPath = reference.filePath || (reference.relativePathHint
+    ? `${canonicalDirectoryPath(notebook.path)}/${reference.relativePathHint}` : null)
+    || findCollectionDisplayPath(descriptor.displayId)
+    || (previousTarget.kind === 'collection' && previousTarget.notebookId === notebookId && previousTarget.collectionId === collectionId
+      ? previousTarget.filePath : '');
   const placeholder: Extract<WorkColumnTarget, { kind: 'collection' }> = {
-    kind: 'collection', ...descriptor, filePath: '', notebookPath: canonicalDirectoryPath(notebook.path), collectionType: 'table', name: '正在打开集合',
+    kind: 'collection', ...descriptor, filePath: knownPath, notebookPath: canonicalDirectoryPath(notebook.path), collectionType: 'table', name: '正在打开集合',
   };
   const requestId = beginNavigation(placeholder, null, false, false);
-  try {
-    await flushWorkspaceDocument();
-  } catch (error) {
-    if (isCurrentNavigation(requestId)) useWorkColumnStore.getState().failNavigation(requestId, error);
-    throw error;
-  }
   if (!isCurrentNavigation(requestId)) return;
   let item: Awaited<ReturnType<typeof collections.resolve>> | null = null;
   let unavailableReason: string | undefined;
   try { item = await collections.resolve(notebookId, collectionId); }
   catch (error) { unavailableReason = String(error).includes('IDENTITY_CONFLICT') ? '集合身份冲突，请先为副本生成新 ID' : '集合不存在或暂时无法读取'; }
-  const filePath = item ? `${canonicalDirectoryPath(notebook.path)}/${item.relativePath}` : reference.relativePathHint ? `${canonicalDirectoryPath(notebook.path)}/${reference.relativePathHint}` : '';
+  if (!isCurrentNavigation(requestId)) return;
+  const filePath = item ? `${canonicalDirectoryPath(notebook.path)}/${item.relativePath}` : knownPath;
   if (item?.identityConflict) unavailableReason = '集合身份冲突，请先为副本生成新 ID';
   if (item && item.parseState !== 'valid') unavailableReason = item.parseState === 'unsupported' ? '此集合版本暂不支持' : '集合文件格式无效';
   if (item && !unavailableReason && descriptor.viewId) {
     try {
       const envelope = parseCollectionDocumentV2(await externalDocuments.read(filePath, notebook.path));
+      if (!isCurrentNavigation(requestId)) return;
       const payload = envelope.payload;
       const views = payload.views.items as Array<{ id: string }>;
       // Tables resolve stale embedded/history view IDs against the file's
@@ -264,7 +298,13 @@ export async function openCollectionTarget(
   }
   if (useWorkColumnStore.getState().navigation.requestId !== requestId) return;
   if (filePath && !bindCollectionDisplayPath(descriptor.displayId, filePath, item?.indexSequence)) {
-    return openCollectionTarget(reference, options);
+    // The first attempt already advanced the navigation revision. Carry that
+    // revision into the retry so the startup restore lease does not reject its
+    // own retry as stale; a later user navigation will still supersede it.
+    return openCollectionTarget(reference, {
+      ...options,
+      restoreRequestId: requestId,
+    });
   }
   const target: Extract<WorkColumnTarget, { kind: 'collection' }> = {
     kind: 'collection', ...descriptor, filePath, notebookPath: canonicalDirectoryPath(notebook.path),
@@ -282,77 +322,273 @@ export async function openCollectionTarget(
   useWorkspaceFocusStore.getState().focusHost('main-third');
 }
 
-async function openCollectionFile(filePath: string, notebookPath: string | null, notebookId: string | null, options?: { history?: 'push' | 'skip'; destination?: 'main-third' }): Promise<void> {
-  const root = canonicalPath(notebookPath ?? '');
+async function resolveCollectionFileNotebook(
+  filePath: string,
+  notebookPath: string | null,
+  notebookId: string | null,
+): Promise<Notebook> {
+  if (!filePath.trim()) throw new Error('集合文件路径已丢失，请从文件树重新打开此文件');
   const workspace = getWorkspaceMemoState();
-  const resolvedId = notebookId ?? workspace.notebooks.find((item) => canonicalPath(item.path) === root)?.id
-    ?? (workspace.selectedNotebook && canonicalPath(workspace.selectedNotebook.path) === root ? workspace.selectedNotebook.id : null);
-  if (!resolvedId || !root) throw new Error('无法确定集合所属笔记本');
-  const envelope = parseCollectionDocumentV2(await externalDocuments.read(filePath, root));
-  await openCollectionTarget({ notebookId: resolvedId, collectionId: envelope.collection.id }, options);
+  const fileDirectory = canonicalDirectoryPath(canonicalPath(filePath).replace(/[\\/][^\\/]*$/, ''));
+  const containsFile = (item: Notebook) => notebookRelativeDirectoryPath(item.path, fileDirectory) !== null;
+  // File browser surfaces can be restored before the memo library has loaded
+  // its notebook list. Refresh it here so nested notebooks and stale cached
+  // paths resolve to the actual owner of this collection file.
+  let candidates: Notebook[];
+  try { candidates = (await notebooks.getAll()).filter(containsFile); }
+  catch { candidates = [...workspace.notebooks, ...(workspace.selectedNotebook ? [workspace.selectedNotebook] : [])].filter(containsFile); }
+  const requestedNotebook = notebookId
+    ? candidates.find((item) => item.id === notebookId)
+    : null;
+  const hintedPathNotebook = notebookPath
+    ? candidates.find((item) => canonicalPath(item.path) === canonicalPath(notebookPath))
+    : null;
+  const notebook = requestedNotebook ?? hintedPathNotebook
+    ?? candidates.sort((left, right) => canonicalPath(right.path).length - canonicalPath(left.path).length)[0];
+  if (!notebook) throw new Error('无法确定集合所属笔记本');
+  return notebook;
+}
+
+/** Reopen a collection from its file and return to its configured default view. */
+export async function resetCurrentCollectionView(
+  filePath: string,
+  notebookPath: string | null,
+  notebookId: string | null,
+  location: { host: 'main-third' } | { host: 'browser-column'; tabId: string } = { host: 'main-third' },
+): Promise<void> {
+  const notebook = await resolveCollectionFileNotebook(filePath, notebookPath, notebookId);
+  const root = canonicalDirectoryPath(notebook.path);
+  const resolvedId = notebook.id;
+  const repaired = await repairCollectionFile(filePath, root);
+  if (location.host === 'browser-column') {
+    let display: ReturnType<typeof ensureCollectionDisplay> | undefined;
+    try {
+      const item = await collections.resolve(resolvedId, repaired.collectionId);
+      if (!item.identityConflict && item.parseState === 'valid' && item.collectionType === repaired.collectionType) {
+        const descriptor = ensureCollectionDisplay({ notebookId: resolvedId, collectionId: repaired.collectionId, viewId: null });
+        if (bindCollectionDisplayPath(descriptor.displayId, filePath, item.indexSequence)) display = descriptor;
+      }
+    } catch { /* The direct file view below does not depend on catalog readiness. */ }
+    useBrowserColumnStore.getState().selectFileBrowserFile(
+      location.tabId, filePath, display, repaired.collectionType,
+    );
+    return;
+  }
+
+  try {
+    await openCollectionTarget({ notebookId: resolvedId, collectionId: repaired.collectionId, filePath }, { refresh: true });
+  } catch {
+    await openCollectionFileDirectly(filePath, root, resolvedId, repaired.collectionType);
+    return;
+  }
+  const active = useWorkColumnStore.getState().navigation.target;
+  if (active.kind !== 'collection' || active.collectionId !== repaired.collectionId || active.unavailableReason) {
+    await openCollectionFileDirectly(filePath, root, resolvedId, repaired.collectionType);
+  }
 }
-export async function openFolderCollectionOrList(target: DocumentListTarget): Promise<void> {
-  const notebookId = target.scope.notebookId;
-  const notebook = notebookId ? getWorkspaceMemoState().notebooks.find((item) => item.id === notebookId) : null;
-  if (!notebook || !notebookId) {
-    await openDocumentListTarget(target);
+
+async function openCollectionFileDirectly(
+  filePath: string,
+  notebookPath: string,
+  notebookId: string,
+  type: 'table' | 'media_library',
+  unavailableReason?: string,
+  history: 'push' | 'skip' = 'skip',
+): Promise<void> {
+  const target: WorkColumnTarget = type === 'table'
+    ? { kind: 'table', filePath, notebookPath, notebookId, ...(unavailableReason ? { unavailableReason } : {}) }
+    : { kind: 'media-library', filePath, notebookPath, notebookId, ...(unavailableReason ? { unavailableReason } : {}) };
+  await runNavigation(target, async (requestId) => {
+    await getWorkspaceDocumentState().clearDocument();
+    if (!isCurrentNavigation(requestId)) return;
+    commitNavigation(requestId, target, history);
+    useWorkspaceFocusStore.getState().focusHost('main-third');
+  }, async () => { await openCollectionFileDirectly(filePath, notebookPath, notebookId, type, unavailableReason, history); });
+}
+
+async function openCollectionFile(filePath: string, notebookPath: string | null, notebookId: string | null, options?: { history?: 'push' | 'skip'; destination?: 'main-third'; restoreRequestId?: number }): Promise<void> {
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+  const notebook = await resolveCollectionFileNotebook(filePath, notebookPath, notebookId);
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+  const root = canonicalDirectoryPath(notebook.path);
+  const source = await externalDocuments.read(filePath, root);
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+  let envelope: ReturnType<typeof parseCollectionDocumentV2>;
+  try { envelope = parseCollectionDocumentV2(source); }
+  catch {
+    // Invalid content still owns a selectable file surface with a recovery
+    // action. Never roll the navigation back merely because parsing failed.
+    await openCollectionFileDirectly(filePath, root, notebook.id, inspectCollectionRecoveryType(source), '集合文件格式无效', options?.history ?? 'push');
     return;
   }
-  const folderPath = canonicalDirectoryPath(target.scope.path);
+  await openCollectionTarget({ notebookId: notebook.id, collectionId: envelope.collection.id, filePath }, options);
+}
+export async function openFolderCollection(
+  notebookId: string,
+  path: string,
+  options?: { history?: 'push' | 'skip'; initialType?: 'notes' | 'media'; destination?: 'main-third' | 'browser-column'; browserDisposition?: 'focus-existing' | 'replace-active' | 'open-in-column'; restoreRequestId?: number },
+): Promise<void> {
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+  const workspace = getWorkspaceMemoState();
+  const folderPath = canonicalDirectoryPath(path);
+  const notebook = notebookId
+    ? workspace.notebooks.find((item) => item.id === notebookId)
+    : workspace.notebooks.find((item) => notebookRelativeDirectoryPath(item.path, folderPath) !== null);
+  if (!notebook) {
+    throw new Error('无法确定文件夹所属笔记本');
+  }
+  const relativeFolder = notebookRelativeDirectoryPath(notebook.path, folderPath);
+  if (relativeFolder === null) throw new Error('文件夹不属于当前笔记本');
   const indexPath = `${folderPath}/.index.yaml`;
   let source = await files.read(indexPath, notebook.path);
-  let loadingToastId: string | number | undefined;
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+  if (source === null) {
+    const folderName = folderPath.split('/').filter(Boolean).pop() ?? notebook.name;
+    const content = createFolderCollectionContent(options?.initialType ?? 'notes', folderName, relativeFolder);
+    try {
+      if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+      await files.create(indexPath, content, notebook.path);
+      source = content;
+    } catch (error) {
+      // Another click may have created the same index while this one was waiting.
+      source = await files.read(indexPath, notebook.path);
+      if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+      if (source === null) throw error;
+    }
+  }
+  let envelope: ReturnType<typeof parseCollectionDocumentV2>;
+  try { envelope = parseCollectionDocumentV2(source); }
+  catch {
+    await openCollectionFileDirectly(indexPath, notebook.path, notebook.id, inspectCollectionRecoveryType(source), '集合文件格式无效', options?.history ?? 'push');
+    return;
+  }
+  if (envelope.collection.placement !== 'folder') throw new Error('文件夹 .index.yaml 必须声明 placement: folder');
+  if (options?.destination === 'browser-column') {
+    const viewId = (envelope.payload.views as { default_id?: string }).default_id ?? null;
+    const descriptor = ensureCollectionDisplay({ notebookId: notebook.id, collectionId: envelope.collection.id, viewId });
+    bindCollectionDisplayPath(descriptor.displayId, indexPath);
+    const { openWorkspaceSurface } = await import('@features/workspace/public/open-surface-api');
+    if (!isRestoreRequestCurrent(options?.restoreRequestId)) return;
+    await openWorkspaceSurface({
+      host: 'browser-column',
+      target: {
+        kind: 'collection',
+        ...descriptor,
+        filePath: indexPath,
+        notebookPath: canonicalDirectoryPath(notebook.path),
+        collectionType: envelope.collection.type,
+        name: collectionDisplayName(indexPath, envelope.collection.placement),
+      },
+      options: { browserDisposition: options?.browserDisposition ?? 'replace-active' },
+    });
+    return;
+  }
+  await openCollectionTarget({
+    notebookId: notebook.id,
+    collectionId: envelope.collection.id,
+    viewId: (envelope.payload.views as { default_id?: string }).default_id,
+    filePath: indexPath,
+  }, { history: options?.history, restoreRequestId: options?.restoreRequestId });
+}
+
+export async function openFolderCollectionChooserTarget(target: FolderCollectionSurfaceTarget, restoreRequestId?: number): Promise<void> {
+  if (!isRestoreRequestCurrent(restoreRequestId)) return;
+  const notebook = getWorkspaceMemoState().notebooks.find((item) => item.id === target.notebookId);
+  if (!notebook || notebookRelativeDirectoryPath(notebook.path, target.folderPath) === null) {
+    throw new Error('文件夹不属于当前笔记本');
+  }
+  const requestId = beginNavigation(target, null, false, false);
   try {
-    if (source === null) {
-      loadingToastId = toast.info('正在创建并打开笔记集合…', { duration: 60_000 });
-      const folderName = folderPath.split('/').filter(Boolean).pop() ?? notebook.name;
-      const content = createFolderCollectionContent('notes', folderName);
-      try {
-        await files.create(indexPath, content, notebook.path);
-        source = content;
-      } catch (error) {
-        // Another click may have created the same index while this one was waiting.
-        source = await files.read(indexPath, notebook.path);
-        if (source === null) throw error;
-      }
+    await prepareActiveWorkColumnDocumentLeave();
+  } catch (error) {
+    if (isCurrentNavigation(requestId)) useWorkColumnStore.getState().failNavigation(requestId, error);
+    throw error;
+  }
+  if (isCurrentNavigation(requestId)) commitNavigation(requestId, target, 'skip');
+}
+
+export async function openFolderCollectionFromFolder(
+  notebookId: string,
+  path: string,
+  host: WorkspaceHostId = 'main-third',
+): Promise<void> {
+  const folderPath = canonicalDirectoryPath(path);
+  const notebook = getWorkspaceMemoState().notebooks.find((item) => item.id === notebookId);
+  if (!notebook) throw new Error('无法确定文件夹所属笔记本');
+  const indexPath = `${folderPath}/.index.yaml`;
+  const source = await files.read(indexPath, notebook.path);
+  let hasReadableFolderCollection = false;
+  if (source !== null) {
+    try {
+      const envelope = parseCollectionDocumentV2(source);
+      hasReadableFolderCollection = envelope.collection.placement === 'folder';
+    } catch {
+      // Unreadable or malformed folder metadata falls through to the chooser.
     }
-    const envelope = parseCollectionDocumentV2(source);
-    if (envelope.collection.placement !== 'folder') throw new Error('文件夹 .index.yaml 必须声明 placement: folder');
-    await openCollectionTarget({
-      notebookId,
-      collectionId: envelope.collection.id,
-      viewId: (envelope.payload.views as { default_id?: string }).default_id,
+  }
+  if (hasReadableFolderCollection) {
+    await openFolderCollection(notebookId, folderPath, {
+      destination: host,
+      ...(host === 'browser-column' ? { browserDisposition: 'replace-active' as const } : {}),
     });
-  } finally {
-    if (loadingToastId !== undefined) toast.dismiss(loadingToastId);
+    return;
+  }
+  const folderName = folderPath.split(/[\\/]/).filter(Boolean).pop() ?? notebook.name;
+  const target: FolderCollectionSurfaceTarget = {
+    kind: 'folder-collection', folderPath, notebookId, notebookPath: notebook.path, folderName,
+  };
+  if (host === 'browser-column') {
+    const { openWorkspaceSurface } = await import('@features/workspace/public/open-surface-api');
+    await openWorkspaceSurface({ host, target, options: { browserDisposition: 'replace-active' } });
+  } else {
+    await openFolderCollectionChooserTarget(target);
   }
 }
-export function openTableTarget(filePath: string, notebookPath: string | null, notebookId: string | null, options?: { history?: 'push' | 'skip'; destination?: 'main-third' }): Promise<void> {
+
+export function openTableTarget(filePath: string, notebookPath: string | null, notebookId: string | null, options?: { history?: 'push' | 'skip'; destination?: 'main-third'; restoreRequestId?: number }): Promise<void> {
   return openCollectionFile(filePath, notebookPath, notebookId, options);
 }
-export function openMediaLibraryTarget(filePath: string, notebookPath: string | null, notebookId: string | null, options?: { history?: 'push' | 'skip'; destination?: 'main-third' }): Promise<void> {
+export function openMediaLibraryTarget(filePath: string, notebookPath: string | null, notebookId: string | null, options?: { history?: 'push' | 'skip'; destination?: 'main-third'; restoreRequestId?: number }): Promise<void> {
   return openCollectionFile(filePath, notebookPath, notebookId, options);
 }
-export function restoreCollectionWorkspace(restored: Extract<PersistedWorkspaceTarget, { kind: 'collection' }>): Promise<void> {
-  return openCollectionTarget(restored, { history: 'skip' });
+export function restoreCollectionWorkspace(restored: Extract<PersistedWorkspaceTarget, { kind: 'collection' }>, restoreRequestId = useWorkColumnStore.getState().navigation.requestId): Promise<void> {
+  return openCollectionTarget(restored, { history: 'skip', restoreRequestId });
+}
+export function restoreFolderCollectionWorkspace(restored: FolderCollectionSurfaceTarget, restoreRequestId = useWorkColumnStore.getState().navigation.requestId): Promise<void> {
+  return openFolderCollectionChooserTarget(restored, restoreRequestId);
 }
 
 export async function restoreMediaWorkspace(
   restored: Extract<PersistedWorkspaceTarget, { kind: 'media' }>,
+  restoreRequestId = useWorkColumnStore.getState().navigation.requestId,
 ): Promise<void> {
+  if (!isRestoreRequestCurrent(restoreRequestId)) return;
   await openMediaTarget({
     filePath: restored.filePath,
     notebookId: restored.notebookId,
     notebookPath: restored.notebookPath,
     resourceKind: restored.resourceKind,
     history: 'skip',
+    restoreRequestId,
   });
 }
 
-export function restoreDocumentListWorkspace(
-  restored: DocumentListTarget,
-): void {
-  openDocumentListTarget(restored, { history: 'skip' });
+export async function restoreLegacyFolderListWorkspace(
+  restored: LegacyFolderListTarget,
+  restoreRequestId = useWorkColumnStore.getState().navigation.requestId,
+): Promise<void> {
+  await openFolderCollection(restored.scope.notebookId ?? '', restored.scope.path, { history: 'skip', restoreRequestId });
+}
+
+function isRestoreRequestCurrent(requestId: number | undefined): boolean {
+  return requestId === undefined || useWorkColumnStore.getState().navigation.requestId === requestId;
+}
+
+function stripRestoreRequestId<T extends { restoreRequestId?: number }>(options: T | undefined): Omit<T, 'restoreRequestId'> | undefined {
+  if (!options) return undefined;
+  const copy = { ...options };
+  delete copy.restoreRequestId;
+  return copy;
 }
 
 function isCurrentNavigation(requestId: number): boolean {
@@ -391,12 +627,10 @@ async function runNavigation(
   showWorkColumnLoading = true,
 ): Promise<void> {
   const requestId = beginNavigation(
-    pendingTarget,
-    retry,
-    preservePreviousTarget,
-    showWorkColumnLoading,
+    pendingTarget, retry, preservePreviousTarget, showWorkColumnLoading,
   );
   try {
+    if (!isCurrentNavigation(requestId)) return;
     await operation(requestId);
   } catch (error) {
     const workspace = useWorkColumnStore.getState();
@@ -426,14 +660,6 @@ export function historyEntryFromWorkColumnTarget(
   switch (target.kind) {
     case 'collection':
       return { kind: 'collection', displayId: target.displayId, notebookId: target.notebookId, collectionId: target.collectionId, viewId: target.viewId, relativePathHint: target.filePath.startsWith(`${target.notebookPath}/`) ? target.filePath.slice(target.notebookPath.length + 1) : undefined, openedAt: Date.now() };
-    case 'document-list':
-      return {
-        kind: 'document-list',
-        displayId: target.displayId,
-        scope: target.scope,
-        filters: target.filters,
-        openedAt: Date.now(),
-      };
     case 'external': {
       if (!target.path) return null;
       return {
@@ -523,7 +749,11 @@ export function dismissNavigationFailure(): void {
 }
 
 /** Switch the main workspace notebook as one navigation transaction. */
-export async function selectNotebook(notebook: Notebook): Promise<void> {
+export async function selectNotebook(
+  notebook: Notebook,
+  options: { workColumnTarget?: 'preserve' | 'clear' } = {},
+): Promise<void> {
+  const shouldClearTarget = options.workColumnTarget === 'clear';
   const previousNotebook = getWorkspaceMemoState().selectedNotebook;
   const previousDocument = captureDocumentSnapshot();
   const previousWorkColumnTarget = targetToPreserveOnNotebookSwitch(
@@ -532,7 +762,7 @@ export async function selectNotebook(notebook: Notebook): Promise<void> {
   );
   const clearPreviousTarget = previousWorkColumnTarget.kind === 'media'
     && previousWorkColumnTarget.notebookId !== notebook.id;
-  const nextWorkColumnTarget = clearPreviousTarget
+  const nextWorkColumnTarget = shouldClearTarget || clearPreviousTarget
     ? EMPTY_WORK_COLUMN_TARGET
     : previousWorkColumnTarget;
   let switchedNotebook = false;
@@ -542,38 +772,31 @@ export async function selectNotebook(notebook: Notebook): Promise<void> {
     await runNavigation(
       nextWorkColumnTarget,
       async (requestId) => {
-        // Flush first. Changing the backend notebook before this point could
-        // make a pending save observe the wrong notebook context. Keep the
-        // document session alive so the workColumn remains visible while the
-        // notebook and middle-column list change.
-        await flushWorkspaceDocument();
-        if (!useWorkColumnStore.getState().isCurrentNavigation(requestId)) return;
-
+        // A preserved document remains active with its captured scope. If the
+        // switch clears the target, clearDocument prepares its session once.
         await setCurrentWorkspaceNotebook(notebook);
         switchedNotebook = true;
         if (!useWorkColumnStore.getState().isCurrentNavigation(requestId)) return;
 
         getWorkspaceMemoState().setSelectedNotebook(notebook);
-        await getWorkspaceMemoState().loadNotes({ notebookId: notebook.id });
-        if (!useWorkColumnStore.getState().isCurrentNavigation(requestId)) return;
-        if (clearPreviousTarget) {
+        if (shouldClearTarget || clearPreviousTarget) {
           await getWorkspaceDocumentState().clearDocument();
           if (!useWorkColumnStore.getState().isCurrentNavigation(requestId)) return;
         }
         commitNavigation(requestId, nextWorkColumnTarget);
       },
-      () => selectNotebook(notebook),
+      () => selectNotebook(notebook, options),
       async (requestId) => {
         if (!useWorkColumnStore.getState().isCurrentNavigation(requestId)) return;
-        if (switchedNotebook && previousNotebook?.id) {
-          await setCurrentWorkspaceNotebook(previousNotebook);
+        if (switchedNotebook) {
+          await setCurrentWorkspaceNotebook(previousNotebook?.id ?? null);
         }
         if (!useWorkColumnStore.getState().isCurrentNavigation(requestId)) return;
         getWorkspaceMemoState().setSelectedNotebook(previousNotebook);
         await restoreDocumentSnapshot(previousDocument);
       },
       true,
-      clearPreviousTarget,
+      shouldClearTarget || clearPreviousTarget,
     );
   } finally {
     useWorkColumnStore.getState().endNotebookSwitch?.();
@@ -609,6 +832,7 @@ export async function openExternalTarget(
   path: string | null,
   options?: OpenExternalTargetOptions,
 ): Promise<WorkspaceContentLocation | null> {
+  if (!isRestoreRequestCurrent(options?.restoreRequestId)) return null;
   if (path && /\.index\.yaml$/i.test(path)) {
     const capturedFileBrowser = options?.fileBrowser ?? captureFileBrowserContext(path, options?.scopePath);
     const scopePath = options?.scopePath ?? capturedFileBrowser.scopePath;
@@ -617,7 +841,7 @@ export async function openExternalTarget(
       ?? getWorkspaceMemoState().notebooks.find((notebook) => scopePath && canonicalPath(notebook.path) === canonicalPath(scopePath))?.id
       ?? capturedFileBrowser.notebookId
       ?? null;
-    await openCollectionFile(path, scopePath, notebookId, { history: options?.history, destination: options?.destination });
+    await openCollectionFile(path, scopePath, notebookId, { history: options?.history, destination: options?.destination, restoreRequestId: options?.restoreRequestId });
     return null;
   }
   if (path && /\.lib\.ya?ml$/i.test(path)) {
@@ -628,7 +852,7 @@ export async function openExternalTarget(
       ?? getWorkspaceMemoState().notebooks.find((notebook) => scopePath && canonicalPath(notebook.path) === canonicalPath(scopePath))?.id
       ?? capturedFileBrowser.notebookId
       ?? null;
-    await openMediaLibraryTarget(path, scopePath, notebookId, { history: options?.history, destination: options?.destination });
+    await openMediaLibraryTarget(path, scopePath, notebookId, { history: options?.history, destination: options?.destination, restoreRequestId: options?.restoreRequestId });
     return null;
   }
   if (path && /\.table\.ya?ml$/i.test(path)) {
@@ -639,29 +863,21 @@ export async function openExternalTarget(
       ?? getWorkspaceMemoState().notebooks.find((notebook) => scopePath && canonicalPath(notebook.path) === canonicalPath(scopePath))?.id
       ?? capturedFileBrowser.notebookId
       ?? null;
-    await openTableTarget(path, scopePath, notebookId, { history: options?.history, destination: options?.destination });
+    await openTableTarget(path, scopePath, notebookId, { history: options?.history, destination: options?.destination, restoreRequestId: options?.restoreRequestId });
     return null;
   }
-  const markdownLocation = path && /\.(md|markdown)$/i.test(path)
-    ? options?.markdownLocation ?? await notesClient.resolveLocation(path)
-    : null;
-  const capturedFileBrowser = options?.fileBrowser ?? captureFileBrowserContext(path, options?.scopePath);
-  const fileBrowser = markdownLocation?.notebookId
-    ? { ...capturedFileBrowser, notebookId: markdownLocation.notebookId }
-    : capturedFileBrowser;
-  options = {
-    ...options,
-    fileBrowser,
-    markdownLocation,
-    scopePath: options?.scopePath ?? markdownLocation?.notebookPath ?? fileBrowser.scopePath,
-  };
-  const existing = path && options?.destination !== 'main-third'
-    ? activateExistingContentForNavigation({ kind: 'external', path })
+  const existing = path
+    ? activateExistingContentForNavigation(
+        { kind: 'external', path },
+        options?.destination ?? undefined,
+      )
     : null;
   if (existing instanceof Promise) {
     const activated = await existing;
+    if (!isRestoreRequestCurrent(options?.restoreRequestId)) return null;
     if (activated) return activated;
   } else if (existing) {
+    if (!isRestoreRequestCurrent(options?.restoreRequestId)) return null;
     return existing;
   }
 
@@ -669,9 +885,29 @@ export async function openExternalTarget(
   const previousPathNote = getWorkspaceMemoState().selectedNote;
   let switchedNotebook = false;
   const previousDocument = captureDocumentSnapshot();
+  const retryOptions = stripRestoreRequestId(options);
   await runNavigation(
     pendingExternalTarget(path, options),
     async (requestId) => {
+      if (path && !await flushBrowserViewBeforeOpeningWork({ kind: 'external', path })) {
+        throw new Error('Document switch cancelled because the Browser document could not be saved');
+      }
+      if (!isCurrentNavigation(requestId)) return;
+      const markdownLocation = path && /\.(md|markdown)$/i.test(path)
+        ? options?.markdownLocation ?? await notesClient.resolveLocation(path)
+        : null;
+      if (!isCurrentNavigation(requestId)) return;
+      const capturedFileBrowser = options?.fileBrowser ?? captureFileBrowserContext(path, options?.scopePath);
+      const fileBrowser = markdownLocation?.notebookId
+        ? { ...capturedFileBrowser, notebookId: markdownLocation.notebookId }
+        : capturedFileBrowser;
+      options = {
+        ...options,
+        fileBrowser,
+        markdownLocation,
+        scopePath: options?.scopePath ?? markdownLocation?.notebookPath ?? fileBrowser.scopePath,
+      };
+
       if (markdownLocation?.notebookId && markdownLocation.notebookId !== (
         getWorkspaceMemoState().selectedNotebookId ?? getWorkspaceMemoState().selectedNotebook?.id
       )) {
@@ -720,7 +956,7 @@ export async function openExternalTarget(
       }
     },
     async () => {
-      await openExternalTarget(path, options);
+      await openExternalTarget(path, retryOptions);
     },
     async (requestId) => {
       if (!isCurrentNavigation(requestId)) return;
@@ -740,31 +976,34 @@ export async function openExternalTarget(
 export async function openMediaTarget(
   params: OpenMediaTargetParams,
 ): Promise<WorkspaceContentLocation | null> {
+  if (!isRestoreRequestCurrent(params.restoreRequestId)) return null;
   const filePath = params.filePath.trim();
   if (!filePath || !params.notebookPath?.trim()) return null;
   const target = pendingMediaTarget({ ...params, filePath });
-  const existing = params.destination === 'main-third'
-    ? null
-    : activateExistingContentForNavigation({ kind: 'media', path: filePath });
+  const existing = activateExistingContentForNavigation(
+    { kind: 'media', path: filePath },
+    params.destination,
+  );
   if (existing instanceof Promise) {
     const activated = await existing;
+    if (!isRestoreRequestCurrent(params.restoreRequestId)) return null;
     if (activated) return activated;
   } else if (existing) {
+    if (!isRestoreRequestCurrent(params.restoreRequestId)) return null;
     return existing;
   }
 
   const previousDocument = captureDocumentSnapshot();
+  const retryParams = stripRestoreRequestId(params)!;
   await runNavigation(
     target,
     async (requestId) => {
-      await flushWorkspaceDocument();
-      if (!isCurrentNavigation(requestId)) return;
       await getWorkspaceDocumentState().clearDocument();
       if (!isCurrentNavigation(requestId)) return;
       if (!commitNavigation(requestId, target, params.history ?? 'push')) return;
       useWorkspaceFocusStore.getState().focusHost('main-third');
     },
-    async () => { await openMediaTarget(params); },
+    async () => { await openMediaTarget(retryParams); },
     async (requestId) => {
       if (!isCurrentNavigation(requestId)) return;
       await restoreDocumentSnapshot(previousDocument);
@@ -782,9 +1021,10 @@ export async function openWebTarget(
   const normalized = canonicalUrl(url);
   if (!normalized) throw new Error(`Unsupported webpage URL: ${url}`);
 
-  const existing = options?.destination === 'main-third'
-    ? null
-    : activateExistingContentForNavigation({ kind: 'web', url: normalized });
+  const existing = activateExistingContentForNavigation(
+    { kind: 'web', url: normalized },
+    options?.destination,
+  );
   if (existing instanceof Promise) {
     const activated = await existing;
     if (activated) return activated;
@@ -796,7 +1036,7 @@ export async function openWebTarget(
   await runNavigation(
     target,
     async (requestId) => {
-      await flushWorkspaceDocument();
+      await prepareActiveWorkColumnDocumentLeave();
       if (!isCurrentNavigation(requestId)) return;
       commitNavigation(requestId, target, options?.history ?? 'push');
       useWorkspaceFocusStore.getState().focusHost('main-third');
@@ -806,47 +1046,46 @@ export async function openWebTarget(
   return null;
 }
 
-/** Flush the active editable document without clearing its session or target. */
-export async function flushWorkspaceDocument(): Promise<void> {
-  const document = getWorkspaceDocumentState();
-  let flushed = true;
-
-  if (document.activeExternalSession) {
-    flushed = await flushWorkspaceDocumentPath(
-      documentIdentityFromFile(document.activeExternalSession.fileIdentity),
-      document.activeExternalSession.fileIdentity.path,
-      document.activeExternalSession.scopePath,
-    );
-  }
-
-  if (!flushed) {
-    throw new Error('Document flush did not complete');
-  }
+/** Capture and retain the document before replacing its visible work surface. */
+export async function prepareActiveWorkColumnDocumentLeave(): Promise<void> {
+  const active = getWorkspaceDocumentState().activeExternalSession;
+  if (!active) return;
+  const prepared = await prepareWorkspaceDocumentLeave(
+    documentIdentityFromFile(active.fileIdentity),
+    active.fileIdentity.path,
+    active.scopePath,
+  );
+  if (!prepared) throw new Error('Document draft could not be retained');
 }
 
 export async function openAgentTarget(
   instanceId: string,
-  options?: { history?: 'push' | 'skip'; destination?: 'main-third'; blankIfMissing?: true },
+  options?: { history?: 'push' | 'skip'; destination?: 'main-third'; blankIfMissing?: true; restoreRequestId?: number },
 ): Promise<WorkspaceHostId | WorkspaceContentLocation> {
   const normalized = instanceId.trim();
-  if (!normalized) return 'main-third';
-  const existing = options?.destination === 'main-third'
-    ? null
-    : activateExistingContentForNavigation({
-        kind: 'agent-conversation',
-        instanceId: normalized,
-      });
+  if (!normalized || !isRestoreRequestCurrent(options?.restoreRequestId)) return 'main-third';
+  const navigationOptions = options ? {
+    ...(options.history ? { history: options.history } : {}),
+    ...(options.destination ? { destination: options.destination } : {}),
+    ...(options.blankIfMissing ? { blankIfMissing: true as const } : {}),
+  } : undefined;
+  const existing = activateExistingContentForNavigation(
+    { kind: 'agent-conversation', instanceId: normalized },
+    options?.destination ?? undefined,
+  );
   if (existing instanceof Promise) {
     const activated = await existing;
+    if (!isRestoreRequestCurrent(options?.restoreRequestId)) return 'main-third';
     if (activated) return activated;
   } else if (existing) {
+    if (!isRestoreRequestCurrent(options?.restoreRequestId)) return 'main-third';
     return existing;
   }
   await runNavigation(
     {
       kind: 'agent-conversation',
       instanceId: normalized,
-      ...(options?.blankIfMissing ? { blankIfMissing: true as const } : {}),
+      ...(navigationOptions?.blankIfMissing ? { blankIfMissing: true as const } : {}),
     },
     async (requestId) => {
       await getWorkspaceDocumentState().openAgentConversation(
@@ -858,18 +1097,19 @@ export async function openAgentTarget(
       }
       getWorkspaceMemoState().setActivePluginId(null);
       if (!isCurrentNavigation(requestId)) return;
-      commitNavigation(
+      const committed = commitNavigation(
         requestId,
         {
           kind: 'agent-conversation',
           instanceId: normalized,
-          ...(options?.blankIfMissing ? { blankIfMissing: true as const } : {}),
+          ...(navigationOptions?.blankIfMissing ? { blankIfMissing: true as const } : {}),
         },
-        options?.history ?? 'push',
+        navigationOptions?.history ?? 'push',
       );
+      if (committed) useWorkspaceFocusStore.getState().focusHost('main-third');
     },
     async () => {
-      await openAgentTarget(normalized, options);
+      await openAgentTarget(normalized, navigationOptions);
     },
   );
   return 'main-third';
@@ -891,12 +1131,92 @@ export async function clearWorkspaceDocument(): Promise<void> {
   );
 }
 
+function clearSelectedWorkspaceNoteIf(matchesPath: (path: string) => boolean): void {
+  const memoState = getWorkspaceMemoState();
+  const selectedNote = memoState.selectedNote;
+  if (!selectedNote) return;
+  const notebook = memoState.notebooks.find((item) => item.id === selectedNote.notebookId)
+    ?? (memoState.selectedNotebook?.id === selectedNote.notebookId ? memoState.selectedNotebook : null);
+  const selectedPath = notebook && joinNotebookMemoPath(notebook.path, selectedNote.relativePath);
+  if (selectedPath && matchesPath(selectedPath)) memoState.setSelectedNote(null);
+}
+
 /** Clear the active work-column view when its backing file has been deleted. */
 export async function clearWorkspaceTargetForDeletedFile(filePath: string): Promise<boolean> {
-  const targetPath = workColumnTargetFilePath(useWorkColumnStore.getState().navigation.target);
-  if (!targetPath || !samePath(targetPath, filePath)) return false;
-  await clearWorkspaceDocument();
-  return true;
+  clearSelectedWorkspaceNoteIf((selectedPath) => samePath(selectedPath, filePath));
+
+  const matchesPath = (target: WorkColumnTarget | null | undefined) => {
+    const path = target ? workColumnTargetFilePath(target) : null;
+    return Boolean(path && samePath(path, filePath));
+  };
+  const restoreStore = useWorkspaceRestoreStore.getState();
+  const desired = restoreStore.desiredTarget;
+  const desiredPath = desired?.kind === 'external'
+    ? desired.path
+    : desired && 'filePath' in desired ? desired.filePath : null;
+  if (desiredPath && samePath(desiredPath, filePath)) restoreStore.setDesiredTarget(null);
+
+  const navigation = useWorkColumnStore.getState().navigation;
+  const targetMatches = matchesPath(navigation.target);
+  const pendingMatches = matchesPath(navigation.pendingTarget);
+  const previousMatches = matchesPath(navigation.previousTarget);
+  if (!targetMatches && !pendingMatches && !previousMatches) return false;
+
+  if (targetMatches || pendingMatches) await clearWorkspaceDocument();
+
+  // Committing an empty target intentionally preserves navigation history for
+  // ordinary closes. A deleted file must not remain as a rollback target.
+  const latestNavigation = useWorkColumnStore.getState().navigation;
+  if (matchesPath(latestNavigation.previousTarget)) {
+    useWorkColumnStore.setState({
+      navigation: { ...latestNavigation, previousTarget: null },
+    });
+  }
+  return targetMatches || pendingMatches;
+}
+
+/** Clear work and browser targets that would become valid again after a same-path folder import. */
+export async function clearWorkspaceTargetsForDeletedDirectory(directoryPath: string): Promise<void> {
+  const isInsideDeletedDirectory = (path: string | null | undefined) => (
+    Boolean(path && isPathInDirectory(path, directoryPath))
+  );
+  const navigation = useWorkColumnStore.getState().navigation;
+  clearSelectedWorkspaceNoteIf(isInsideDeletedDirectory);
+
+  const workTargetIsInside = (target: WorkColumnTarget | null) => {
+    if (!target) return false;
+    if (target.kind === 'folder-collection') return isInsideDeletedDirectory(target.folderPath);
+    return isInsideDeletedDirectory(workColumnTargetFilePath(target));
+  };
+  const targetIsInside = workTargetIsInside(navigation.target);
+  const pendingTargetIsInside = workTargetIsInside(navigation.pendingTarget);
+  const clearWorkTarget = targetIsInside || pendingTargetIsInside;
+
+  useBrowserColumnStore.getState().clearTargetsUnderDirectory(directoryPath);
+
+  const restoreStore = useWorkspaceRestoreStore.getState();
+  const desiredTarget = restoreStore.desiredTarget;
+  const desiredPath = desiredTarget
+    ? desiredTarget.kind === 'external'
+      ? desiredTarget.path
+      : desiredTarget.kind === 'agent-conversation'
+        ? null
+        : 'filePath' in desiredTarget
+          ? desiredTarget.filePath
+          : 'folderPath' in desiredTarget
+            ? typeof desiredTarget.folderPath === 'string' ? desiredTarget.folderPath : null
+            : null
+    : null;
+  if (isInsideDeletedDirectory(desiredPath)) restoreStore.setDesiredTarget(null);
+
+  if (clearWorkTarget) await clearWorkspaceDocument();
+
+  const latestNavigation = useWorkColumnStore.getState().navigation;
+  if (workTargetIsInside(latestNavigation.previousTarget)) {
+    useWorkColumnStore.setState({
+      navigation: { ...latestNavigation, previousTarget: null },
+    });
+  }
 }
 
 /** Update every live reference to an external file after an in-place rename. */
@@ -912,11 +1232,12 @@ export function replaceExternalDocumentPath(
 
   const resumeDisplayIdReconciliation = suspendFileDisplayReconciliation();
   try {
-    replaceWorkspaceDocumentPath({
+    const applied = replaceWorkspaceDocumentPath({
       kind: 'md',
       path: previous,
       displayId,
     }, next);
+    if (!applied) return;
     if (activeExternal?.indexable && selectedNote
       && selectedNote.notebookId === activeExternal.notebookId
       && selectedNote.relativePath === activeExternal.relativePath) {
diff --git a/app/flowix-web/index.html b/app/flowix-web/index.html
index 888690ff3..20c187305 100644
--- a/app/flowix-web/index.html
+++ b/app/flowix-web/index.html
@@ -20,29 +20,9 @@
         background: var(--background, #f5f5f4);
         pointer-events: none;
       }
-      #app-loading::before {
-        width: 24px;
-        height: 24px;
-        box-sizing: border-box;
-        border: 2px solid color-mix(in srgb, var(--foreground, #78716c) 28%, transparent);
-        border-top-color: var(--foreground, #78716c);
-        border-radius: 50%;
-        content: "";
-        animation: app-loading-spin 0.72s linear infinite;
-      }
       html[data-theme="dark"] #app-loading {
         background: var(--background, #171717);
       }
-      html[data-theme="dark"] #app-loading::before {
-        border-color: color-mix(in srgb, var(--foreground, #d6d3d1) 24%, transparent);
-        border-top-color: var(--foreground, #d6d3d1);
-      }
-      @keyframes app-loading-spin {
-        to { transform: rotate(360deg); }
-      }
-      @media (prefers-reduced-motion: reduce) {
-        #app-loading::before { animation-duration: 1.4s; }
-      }
     </style>
     <!--
       首屏 boot: 在 CSS paint 之前把 data-theme 写到 <html>。
diff --git a/app/flowix-web/lib/agent-access-defaults.test.ts b/app/flowix-web/lib/agent-access-defaults.test.ts
deleted file mode 100644
index 86ace1549..000000000
--- a/app/flowix-web/lib/agent-access-defaults.test.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { resolveAuthorizedDefaultFiles } from '@/lib/agent-access-defaults';
-import type { AgentAccessConfig, AgentAccessEntry } from '@/lib/types/agent-access';
-
-function folder(path: string, overrides: Partial<AgentAccessEntry> = {}): AgentAccessEntry {
-  return {
-    id: `folder-${path}`,
-    kind: 'folder',
-    path,
-    name: path,
-    enabled: true,
-    workspace: false,
-    addedAt: 1,
-    updatedAt: 1,
-    missing: false,
-    ...overrides,
-  };
-}
-
-describe('resolveAuthorizedDefaultFiles', () => {
-  it('filters missing, disabled, and unregistered default folders', () => {
-    const config: AgentAccessConfig = {
-      version: 1,
-      entries: [
-        folder('/资料/active'),
-        folder('/资料/missing', { missing: true }),
-        folder('/资料/disabled', { enabled: false }),
-      ],
-      defaults: {
-        files: {
-          notebook: {
-            workspace: '/资料/missing',
-            folders: ['/资料/active', '/资料/missing', '/资料/disabled', '/资料/stale'],
-            notebooks: [],
-          },
-        },
-      },
-    };
-
-    expect(resolveAuthorizedDefaultFiles(config, 'notebook')).toEqual({
-      workspace: undefined,
-      folders: ['/资料/active'],
-      notebooks: [],
-    });
-  });
-});
diff --git a/app/flowix-web/lib/agent-access-defaults.ts b/app/flowix-web/lib/agent-access-defaults.ts
deleted file mode 100644
index 81a3e0488..000000000
--- a/app/flowix-web/lib/agent-access-defaults.ts
+++ /dev/null
@@ -1,131 +0,0 @@
-/**
- * Agent access defaults 的纯函数工具 ── 与 store 解耦, 便于在
- * `buildInitialInstanceRuntimeConfig` 等处直接引用而不被 store mock 影响。
- *
- * Legacy `defaults.files` 按 notebook 维度索引: key 为 notebook.id,
- * `DEFAULT_FILES_GLOBAL_KEY` ("_global") 为兜底 (老版单对象迁移落点 /
- * 历史 instance 无 `runtimeConfig.notebookId` 时的回写目标)。 老版本是单个
- * `FilesConfig` 对象, 读取时由 `normalizeFilesDefaults` 归一化到
- * `{ _global: <old> }`, 无须显式数据迁移。
- */
-import { DEFAULT_FILES_GLOBAL_KEY } from "@/lib/types/agent-access";
-import type { AgentAccessConfig, NotebookAgentConfig } from "@/lib/types/agent-access";
-import type { FilesConfig } from "@/types/agent";
-
-/**
- * 判断 `defaults.files` 是老版单对象 `FilesConfig` 还是新索引对象。
- * `FilesConfig` 必有 `folders` 数组; 索引对象的顶层 key 是 notebookId,
- * 值才是 `FilesConfig`。 notebookId 形如 `nb_<ts>` / `_global`, 不会是
- * `folders`, 故无歧义。
- */
-function isPlainFilesConfig(value: unknown): value is FilesConfig {
-  return (
-    !!value &&
-    typeof value === "object" &&
-    Array.isArray((value as { folders?: unknown }).folders)
-  );
-}
-
-/**
- * 把任意形状的 `defaults.files` 归一化成索引对象:
- *   - 老版单对象 `FilesConfig` -> `{ _global: <old> }` (迁移)
- *   - 已是索引对象 -> 原样返回
- *   - 缺失 / 非对象 -> `{}`
- *
- * 读取与写入都先过这一层, 让老数据无须显式迁移即可在新 schema 下工作。
- */
-export function normalizeFilesDefaults(
-  raw: unknown,
-): Record<string, FilesConfig> {
-  if (!raw || typeof raw !== "object") return {};
-  if (isPlainFilesConfig(raw)) {
-    return { [DEFAULT_FILES_GLOBAL_KEY]: raw };
-  }
-  return raw as Record<string, FilesConfig>;
-}
-
-/**
- * 按 notebookId 取该 notebook 的默认 files, 缺失时 fallback 到 `_global`。
- * 新卡片取种子 (`buildInitialInstanceRuntimeConfig`) 用它读"本笔记本的默认"。
- */
-export function resolveDefaultFiles(
-  config: AgentAccessConfig | undefined | null,
-  notebookId: string | null | undefined,
-): FilesConfig | undefined {
-  const indexed = normalizeFilesDefaults(config?.defaults?.files);
-  if (notebookId && indexed[notebookId]) return indexed[notebookId];
-  return indexed[DEFAULT_FILES_GLOBAL_KEY];
-}
-
-/**
- * Resolve one notebook's files and keep only folders that still have an
- * enabled, present entry in the backend-owned global registry. This prevents
- * stale defaults from silently widening a run after an entry disappears.
- */
-export function resolveAuthorizedDefaultFiles(
-  config: AgentAccessConfig | undefined | null,
-  notebookId: string | null | undefined,
-): FilesConfig | undefined {
-  const files = resolveDefaultFiles(config, notebookId);
-  if (!files) return undefined;
-
-  const comparable = (path: string): string =>
-    path.trim().replace(/[\\/]+$/, '').toLowerCase();
-  const allowed = new Set(
-    (config?.entries ?? [])
-      .filter((entry) => entry.kind === 'folder' && entry.enabled && !entry.missing)
-      .map((entry) => comparable(entry.path)),
-  );
-  const folders = files.folders.filter((path) => allowed.has(comparable(path)));
-  // `null` 是显式取消主空间, 需保留 (UI 把 null 视作 fallback 到 notebook.path);
-  // `string` 必须仍命中合法 folders 才保留, 否则清掉让 UI 重新选。
-  const rawWorkspace = files.workspace;
-  let workspace: string | null | undefined;
-  if (rawWorkspace === null) {
-    // `null` 是显式取消主空间, 需保留 (UI 把 null 视作 fallback 到
-    // notebook.path)。
-    workspace = null;
-  } else if (typeof rawWorkspace === "string") {
-    // `string` 必须仍命中合法 folders 才保留, 否则清掉让 UI 重新选。
-    workspace = folders.some(
-      (path) => comparable(path) === comparable(rawWorkspace),
-    )
-      ? rawWorkspace
-      : undefined;
-  } else {
-    workspace = undefined;
-  }
-
-  return { workspace, folders, notebooks: [...files.notebooks] };
-}
-
-/** Resolve add-dirs from notebook/.flowix/agent.json, intersected with the
- * device-owned authorization registry. */
-export function resolveNotebookAgentFiles(
-  config: AgentAccessConfig | undefined | null,
-  notebookConfigs: Record<string, NotebookAgentConfig> | undefined,
-  notebookId: string | null | undefined,
-): FilesConfig | undefined {
-  if (!notebookId) return undefined;
-  // An explicitly supplied notebook-config map is authoritative.  Do not
-  // fall back to legacy global defaults when loading it failed or the
-  // notebook has no local config: that could silently widen add-dir access.
-  if (notebookConfigs !== undefined && !notebookConfigs[notebookId]) {
-    return undefined;
-  }
-  const local = notebookConfigs?.[notebookId];
-  if (!local) return resolveAuthorizedDefaultFiles(config, notebookId);
-  const comparable = (path: string) => path.trim().replace(/[\\/]+$/, '').toLowerCase();
-  const allowed = new Set(
-    (config?.entries ?? [])
-      .filter((entry) => entry.kind === 'folder' && entry.enabled && !entry.missing)
-      .map((entry) => comparable(entry.path)),
-  );
-  return {
-    workspace: null,
-    folders: local.addDirs
-      .filter((directory) => directory.enabled && allowed.has(comparable(directory.path)))
-      .map((directory) => directory.path),
-    notebooks: [],
-  };
-}
diff --git a/app/flowix-web/lib/agent-types.test.ts b/app/flowix-web/lib/agent-types.test.ts
index a844b3604..fac6e8ce0 100644
--- a/app/flowix-web/lib/agent-types.test.ts
+++ b/app/flowix-web/lib/agent-types.test.ts
@@ -1,32 +1,29 @@
 import { describe, expect, it } from 'vitest';
 
-import {
-  isAlwaysVisibleNewConversationAgent,
-  pickFirstAvailableAgent,
-} from './agent-types';
+import { pickFirstAvailableAgent } from './agent-types';
 
 describe('pickFirstAvailableAgent', () => {
   it('uses the requested priority when several runtimes are available', () => {
     expect(pickFirstAvailableAgent({
-      'deepseek-harness': { available: true },
+      'dsh': { available: true },
       opencode: { available: true },
-      claude: { available: true },
+      claudecode: { available: true },
       codex: { available: true },
-    })).toBe('deepseek-harness');
+    })).toBe('dsh');
   });
 
   it('falls through unavailable runtimes in priority order', () => {
     expect(pickFirstAvailableAgent({
-      claude: { available: true },
+      claudecode: { available: true },
       opencode: { available: true },
-      'deepseek-harness': { available: false },
-    })).toBe('claude');
+      'dsh': { available: false },
+    })).toBe('claudecode');
   });
 
   it('returns DeepSeek Harness when it is the only preferred runtime', () => {
     expect(pickFirstAvailableAgent({
-      'deepseek-harness': { available: true },
-    })).toBe('deepseek-harness');
+      'dsh': { available: true },
+    })).toBe('dsh');
   });
 
   it('returns null when no runtime is available', () => {
@@ -36,12 +33,3 @@ describe('pickFirstAvailableAgent', () => {
     })).toBeNull();
   });
 });
-
-describe('new conversation agent menu visibility', () => {
-  it.each(['deepseek-harness', 'codex', 'claude'] as const)(
-    'always shows %s even when its runtime is unavailable or unchecked',
-    (typeKey) => {
-      expect(isAlwaysVisibleNewConversationAgent(typeKey)).toBe(true);
-    },
-  );
-});
diff --git a/app/flowix-web/lib/agent-types.ts b/app/flowix-web/lib/agent-types.ts
index 4e9c65995..c1fa6ae03 100644
--- a/app/flowix-web/lib/agent-types.ts
+++ b/app/flowix-web/lib/agent-types.ts
@@ -9,9 +9,7 @@ export type { AgentTypeKey };
 //   - icon-claude-code.svg    Claude Code 品牌图标
 import iconCodex from '@/assets/codex.svg';
 import iconClaudeCode from '@/assets/icon-claude-code.svg';
-import iconGeminiCli from '@/assets/icon-gemini-cli.svg';
 import iconHermesAgent from '@/assets/icon-hermes-agent.svg';
-import iconOpenClaw from '@/assets/icon-openclaw.svg';
 import iconOpenCode from '@/assets/icon-opencode.svg';
 import iconDeepSeek from '@/assets/icon-deepseek.svg';
 import iconPi from '@/assets/icon-pi.svg';
@@ -21,12 +19,28 @@ import iconPi from '@/assets/icon-pi.svg';
 // DSH-backed cards implicitly; persisted/card-level choices still win.
 export const DEFAULT_AGENT_TYPE_KEY: AgentTypeKey = 'codex';
 
+/** One-time storage/API boundary normalization for IDs written by older builds. */
+export function normalizeAgentId(value: string | null | undefined): AgentTypeKey | null {
+  switch (value) {
+    case 'claude': return 'claudecode';
+    case 'deepseek-harness':
+    case 'deepseek_harness': return 'dsh';
+    case 'codex':
+    case 'claudecode':
+    case 'hermes':
+    case 'opencode':
+    case 'pi':
+    case 'dsh': return value;
+    default: return null;
+  }
+}
+
 /**
  * Agent icons that are rendered with the current theme color instead of
  * preserving their original brand colors.
  */
 export const THEME_ADAPTIVE_AGENT_ICON_KEYS = new Set<AgentTypeKey>([
-  'deepseek-harness',
+  'dsh',
   'opencode',
   'hermes',
 ]);
@@ -42,28 +56,12 @@ export function isThemeAdaptiveAgentIcon(typeKey: AgentTypeKey): boolean {
  * preference order.
  */
 export const LOCAL_AGENT_DISPLAY_PRIORITY = [
-  'deepseek-harness',
+  'dsh',
   'codex',
-  'claude',
+  'claudecode',
   'opencode',
 ] as const satisfies readonly AgentTypeKey[];
 
-/**
- * Product entry points that must remain discoverable even before their local
- * runtime has been installed. Other agents only appear in the new-conversation
- * menu after runtime detection confirms that they are installed.
- */
-export const ALWAYS_VISIBLE_NEW_CONVERSATION_AGENT_KEYS = new Set<AgentTypeKey>([
-  'deepseek-harness',
-  'codex',
-  'claude',
-  'pi',
-]);
-
-export function isAlwaysVisibleNewConversationAgent(typeKey: AgentTypeKey): boolean {
-  return ALWAYS_VISIBLE_NEW_CONVERSATION_AGENT_KEYS.has(typeKey);
-}
-
 export function pickFirstAvailableAgent(
   statusByType: Partial<Record<AgentTypeKey, { available: boolean }>>,
 ): AgentTypeKey | null {
@@ -86,31 +84,18 @@ const STREAMING_EXTERNAL_CLI_CAPABILITIES: AgentRuntimeCapabilities = {
   externalSessionBacked: true,
 };
 
-const SIMPLE_CLI_CAPABILITIES: AgentRuntimeCapabilities = {
-  supportsTextStreaming: false,
-  supportsToolEvents: false,
-  externalSessionBacked: false,
-};
-
 export const AGENT_TYPES: AgentType[] = [
   {
-    key: 'pi',
+    id: 'pi',
+    runtimeKind: 'builtin',
     icon: iconPi,
     name: 'Pi',
     desc: 'Use Pi coding agent',
     capabilities: STREAMING_EXTERNAL_CLI_CAPABILITIES,
   },
   {
-    key: 'deepseek-harness',
-    icon: iconDeepSeek,
-    name: 'DeepSeek Harness',
-    desc: 'Use the bundled DeepSeek Harness',
-    nameKey: 'agent.types.deepseekHarness.name',
-    descKey: 'agent.types.deepseekHarness.desc',
-    capabilities: { ...STREAMING_EXTERNAL_CLI_CAPABILITIES, supportsThreadArchive: true },
-  },
-  {
-    key: 'codex',
+    id: 'codex',
+    runtimeKind: 'external-cli',
     icon: iconCodex,
     name: 'Codex',
     desc: 'Use Codex coding agent',
@@ -119,7 +104,8 @@ export const AGENT_TYPES: AgentType[] = [
     capabilities: { ...EXTERNAL_CLI_CAPABILITIES, supportsThreadArchive: true },
   },
   {
-    key: 'claude',
+    id: 'claudecode',
+    runtimeKind: 'external-cli',
     icon: iconClaudeCode,
     name: 'Claude Code',
     desc: 'Use Claude Code agent',
@@ -128,7 +114,8 @@ export const AGENT_TYPES: AgentType[] = [
     capabilities: STREAMING_EXTERNAL_CLI_CAPABILITIES,
   },
   {
-    key: 'opencode',
+    id: 'opencode',
+    runtimeKind: 'external-cli',
     icon: iconOpenCode,
     name: 'OpenCode',
     desc: 'Use OpenCode through Agent Client Protocol',
@@ -137,7 +124,8 @@ export const AGENT_TYPES: AgentType[] = [
     capabilities: { ...STREAMING_EXTERNAL_CLI_CAPABILITIES, supportsThreadArchive: true },
   },
   {
-    key: 'hermes',
+    id: 'hermes',
+    runtimeKind: 'external-cli',
     icon: iconHermesAgent,
     name: 'Hermes',
     desc: 'Use Hermes',
@@ -146,37 +134,28 @@ export const AGENT_TYPES: AgentType[] = [
     capabilities: { ...EXTERNAL_CLI_CAPABILITIES, supportsThreadArchive: true },
   },
   {
-    key: 'gemini',
-    icon: iconGeminiCli,
-    name: 'Gemini CLI',
-    desc: 'Use Gemini CLI agent',
-    nameKey: 'agent.types.gemini.name',
-    descKey: 'agent.types.gemini.desc',
-    releaseStatus: 'coming-soon',
-    capabilities: SIMPLE_CLI_CAPABILITIES,
-  },
-  {
-    key: 'openclaw',
-    icon: iconOpenClaw,
-    name: 'OpenClaw',
-    desc: 'Use OpenClaw agent',
-    nameKey: 'agent.types.openclaw.name',
-    descKey: 'agent.types.openclaw.desc',
-    releaseStatus: 'coming-soon',
-    capabilities: SIMPLE_CLI_CAPABILITIES,
+    id: 'dsh',
+    runtimeKind: 'builtin',
+    icon: iconDeepSeek,
+    name: 'DeepSeek Harness',
+    desc: 'Use the bundled DeepSeek Harness',
+    nameKey: 'agent.types.deepseekHarness.name',
+    descKey: 'agent.types.deepseekHarness.desc',
+    capabilities: { ...STREAMING_EXTERNAL_CLI_CAPABILITIES, supportsThreadArchive: true },
   },
 ];
 
 export function getAgentType(typeKey: string | null | undefined): AgentType {
+  const id = normalizeAgentId(typeKey);
   return (
-    AGENT_TYPES.find((t) => t.key === typeKey) ??
-    AGENT_TYPES.find((t) => t.key === DEFAULT_AGENT_TYPE_KEY) ??
+    AGENT_TYPES.find((t) => t.id === id) ??
+    AGENT_TYPES.find((t) => t.id === DEFAULT_AGENT_TYPE_KEY) ??
     AGENT_TYPES[0]
   );
 }
 
 export function normalizeAgentTypeKey(typeKey: string | null | undefined): AgentTypeKey {
-  return getAgentType(typeKey).key;
+  return normalizeAgentId(typeKey) ?? DEFAULT_AGENT_TYPE_KEY;
 }
 
 export function supportsTextStreaming(typeKey: string | null | undefined): boolean {
diff --git a/app/flowix-web/lib/constants.ts b/app/flowix-web/lib/constants.ts
index 50146b50b..7e81c6388 100644
--- a/app/flowix-web/lib/constants.ts
+++ b/app/flowix-web/lib/constants.ts
@@ -30,7 +30,9 @@ export function isTextFile(fileName: string): boolean {
 export const STORAGE_KEYS = {
   CHAT: 'flowix-chat-storage',
   AGENT_SESSION: 'flowix-agent-session-storage',
+  AGENT_DATA: 'flowix-agent-data-storage',
   AGENT_CONVERSATIONS: 'flowix-agent-conversations',
+  AGENT_MESSAGE_FONT: 'flowix-agent-message-font',
   SETTINGS: 'flowix-settings',
   TAG: 'flowix-tag',
   NOTE: 'flowix-note-storage',
@@ -220,7 +222,7 @@ export const DEFAULT_USER_SETTINGS: UserSettings = {
   format: {
     fontFamily: FONT_FAMILY_OPTIONS[0].value,
     fontId: FONT_FAMILY_OPTIONS[0].id,
-    fontSize: 15,
+    fontSize: 16,
     lineHeight: 1.8,
     documentWidth: DOCUMENT_WIDTH_DEFAULT,
   },
diff --git a/app/flowix-web/lib/event-dispatcher.ts b/app/flowix-web/lib/event-dispatcher.ts
index 51fc71e68..7e3a21fba 100644
--- a/app/flowix-web/lib/event-dispatcher.ts
+++ b/app/flowix-web/lib/event-dispatcher.ts
@@ -1,47 +1,7 @@
 /**
- * 通用事件分发器 — 给应用层事件 (如 `MemoEvent`) 一个中央路由。
- *
- * 背景: 项目里 `useMemoEvents.ts` 早期是 "hook 集中分发 (kind switch)"
- * 形态 — 单订阅点, 内部 switch 派发到 note-store 的 handleMemo* action,
- * 已经有中央化的雏形。但有 3 个缺陷:
- *
- * 1. 双订阅绕过中央路由 — `useExternalDocumentChangeWatch` 直接 subscribe
- *    Tauri 'memo-event', 跟 useMemoEvents 并列, 不走中央 switch。未来
- *    第 3 个订阅者会继续散开。
- * 2. 同 id 快速连续事件不合并 — N 次 set() 触发 N 次 rerender。 这是
- *    后端 fs_watcher FSEvents 双触发 / 编辑器 debounce save 期间的常态。
- * 3. source 字段闲置 — 6 种 source 前端仅用 `user_edit` 做一次排除,
- *    handler 想拿上下文得自己实现。
- *
- * 本模块提供 (Phase 1 启用, Phase 2 增强):
- *
- * - `subscribe(handler, filter?)` — 每个 handler 就近声明自己关心的
- *   kind / source / path, filter 在 dispatcher 内统一执行, 跨订阅者
- *   一致。
- * - `dispatch(event)` — 同步派发到所有匹配 filter 的 handler, handler
- *   抛错被捕获不影响其他。
- * - `use(middleware)` — koa-style middleware 链, 可包装 dispatch 实现
- *   dedup / coalesce / log。当前 (Phase 2) 上一个 dedup middleware。
- *
- * 不替代 `lib/tauri/event-bus.ts`: 那个是 Tauri `listen` 适配层
- * (多 handler 共享 1 个 Tauri listener), 这个是应用层语义层 (filter +
- * middleware + 分发策略)。两者职责正交, 一般用法是
- * event-bus.subscribe(tauri event) → dispatcher.dispatch(payload)。
- *
- * 使用范式 (MemoEvent 场景):
- *
- *   // lib/memo-dispatcher.ts (side-effect module)
- *   import { memoDispatcher } from '@/lib/event-dispatcher';
- *   subscribe<MemoEvent>('memo-event', (e) => memoDispatcher.dispatch(e));
- *
- *   memoDispatcher.subscribe(
- *     (e) => useNoteStore.getState().handleMemoUpdated(e.memo),
- *     (e) => e.kind === 'updated',
- *   );
- *
- * 注意: dispatcher 是模块级单例, 多个 webview (主窗口 / 偏好窗口) 各持
- * 一份独立实例, 互不影响。 这是预期行为 — 偏好窗口没有 document-pane,
- * 它的 reload handler 就根本不订阅, 不需要跨 webview 协调 dispatcher。
+ * Application-level event routing with optional filters and middleware.
+ * Tauri transport subscriptions live in `platform/tauri/event-bus`; this class
+ * handles typed events after they enter the application layer.
  */
 
 export type DispatcherMiddleware<T> = (next: DispatchFn<T>) => DispatchFn<T>;
diff --git a/app/flowix-web/lib/file-display-registry.ts b/app/flowix-web/lib/file-display-registry.ts
index 8dd6c1891..5c1fbbc8d 100644
--- a/app/flowix-web/lib/file-display-registry.ts
+++ b/app/flowix-web/lib/file-display-registry.ts
@@ -59,6 +59,11 @@ export function findFileDisplayId(path: string): string | null {
   return displayIdsByFile.get(fileLocatorKey(path)) ?? null;
 }
 
+/** Snapshot before a directory move; includes pinned, temporarily hidden sessions. */
+export function listFileDisplayIdentities(): FileDisplayIdentity[] {
+  return [...pathsByDisplay].map(([displayId, path]) => ({ displayId, path }));
+}
+
 /** Resolve the latest path at the instant a queued write executes. */
 export function findFileDisplayPath(displayId: string): string | null {
   return findCollectionDisplayPath(displayId) ?? pathsByDisplay.get(displayId) ?? null;
diff --git a/app/flowix-web/lib/i18n/messages.en-US.ts b/app/flowix-web/lib/i18n/messages.en-US.ts
index b32f1d31f..4f3060062 100644
--- a/app/flowix-web/lib/i18n/messages.en-US.ts
+++ b/app/flowix-web/lib/i18n/messages.en-US.ts
@@ -5,7 +5,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "editor.attachment.uploadTooLarge": "Attachment content exceeds 64 MiB. Import it using the native file picker.",
     "editor.attachment.uploadBusy": "Other attachments are being processed. Please retry shortly.",
     "editor.attachment.uploadOwnerRequired": "The attachment has no note owner. Reopen the note and retry.",
-    "editor.attachment.uploadFailed": "Attachment could not be saved. Check file permissions and available space.",
+    "editor.attachment.uploadFailed": "Attachment could not be saved. Check file permissions and available space",
     "editor.attachment.uploadUninserted": "The attachment was saved but its insertion location or editor is no longer available. The file remains in the notebook attachments folder.",
     "language.zhCN": "Simplified Chinese",
     "language.enUS": "English",
@@ -16,7 +16,29 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.title": "Preferences",
     "preferences.groups.features": "Features",
     "preferences.groups.ai": "AI",
+    "preferences.plugins.title": "Plugins",
+    "preferences.plugins.description": "Plugins are installed in ~/.flowix/plugin/ and are available in all notebooks.",
+    "preferences.plugins.install": "Install or upgrade plugin",
+    "preferences.plugins.installConfirm": "Install or upgrade “{name}”?{capabilities}",
+    "preferences.plugins.capabilities": "\n\nHost capabilities: {capabilities}",
+    "preferences.plugins.uninstallConfirm": "Uninstall “{name}”?",
+    "preferences.plugins.refresh": "Refresh",
+    "preferences.plugins.builtIn": "Built in",
+    "preferences.plugins.disabled": "Disabled",
+    "preferences.plugins.integrityVerified": "Integrity verified",
+    "preferences.plugins.integrityMissing": "Not verified",
+    "preferences.plugins.integrityVerifiedHint": "The package files match the plugin's declared SHA-256 integrity manifest",
+    "preferences.plugins.integrityMissingHint": "The plugin does not provide an integrity manifest",
+    "preferences.plugins.capabilityLabel": "Capabilities: {capabilities}",
+    "preferences.plugins.enable": "Enable plugin",
+    "preferences.plugins.disable": "Disable plugin",
+    "preferences.plugins.uninstall": "Uninstall plugin",
+    "preferences.plugins.invalidTitle": "Failed to load",
+    "preferences.plugins.loading": "Loading plugins…",
+    "preferences.plugins.empty": "No plugins installed",
+    "preferences.groups.development": "Development",
     "preferences.emptySettings": "No settings available",
+    "preferences.sectionLoadFailed": "This settings page could not be loaded. You can still open another tab.",
     "preferences.error.pathAlreadyRegistered":
       "This folder is already added as a notebook",
     "preferences.error.pathNotEmpty": "Choose an empty folder when restoring from Cloud",
@@ -31,6 +53,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
       "Couldn’t update the notebook index",
     "preferences.error.deleteFailed": "Failed to delete",
     "preferences.tabs.general": "General",
+    "preferences.tabs.environmentConfig": "Environment configuration",
     "preferences.tabs.fileDisplayRules": "Access space visibility",
     "preferences.tabs.format": "Editor layout",
     "preferences.tabs.theme": "Theme",
@@ -71,7 +94,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.tabs.agent": "Model settings",
     "preferences.tabs.shortcuts": "Shortcuts",
     "preferences.tabs.cli": "CLI",
-    "preferences.tabs.mcp": "Connections · MCP · CLI",
+    "preferences.tabs.mcp": "Connections",
     "preferences.tabs.connections": "Integrations",
     "preferences.tabs.cloudSync": "Account",
     "preferences.tabs.imageGeneration": "Image Generation",
@@ -103,10 +126,34 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.cloud.logout": "Log out",
     "preferences.cloud.sessionExpired": "Your cloud session has expired. Please log in again.",
     "preferences.cloud.membership": "Membership and storage",
+    "preferences.cloud.order.title": "Order history",
+    "preferences.cloud.order.description": "View in-app purchases on this account. If payment has not taken effect, check the order with Creem and sync the membership.",
+    "preferences.cloud.order.loading": "Loading orders…",
+    "preferences.cloud.order.empty": "No in-app purchases yet.",
+    "preferences.cloud.order.check": "Check order",
+    "preferences.cloud.order.checkTooltip": "If your benefits have not taken effect, check the order to sync them",
+    "preferences.cloud.order.checking": "Checking…",
+    "preferences.cloud.order.confirmed": "Creem confirmed the payment and membership benefits were synced.",
+    "preferences.cloud.order.notConfirmed": "Creem has not confirmed payment. Check your payment status before checking again.",
+    "preferences.cloud.order.refreshFailed": "Payment is confirmed, but refreshing the account status failed. Please retry the membership refresh.",
+    "preferences.cloud.order.processing": "The order is being checked or its benefits are being synced. Check again shortly.",
+    "preferences.cloud.order.syncFailed": "Creem confirmed payment, but benefit syncing failed. Retry shortly, or contact support if this continues.",
+    "preferences.cloud.order.needsReview": "Creem confirmed payment, but this order needs manual review. Please contact support.",
+    "preferences.cloud.order.unavailable": "This order is missing payment details needed for verification. Please contact support.",
+    "preferences.cloud.order.refunded": "This order has been refunded. Membership benefits will not be restored.",
+    "preferences.cloud.order.unknownResult": "The order check result could not be determined. Try again later, or contact support if this continues.",
+    "preferences.cloud.order.rateLimited": "Too many order checks. Please try again in a minute.",
+    "preferences.cloud.order.pendingCheckout": "An order is already in progress. Please do not purchase again.",
+    "preferences.cloud.order.checkUnavailable": "Order checking is temporarily unavailable. Please try again later.",
+    "preferences.cloud.order.status.pending": "Pending",
+    "preferences.cloud.order.status.paid": "Paid",
+    "preferences.cloud.order.status.expired": "Expired",
+    "preferences.cloud.order.status.refunded": "Refunded",
+    "preferences.cloud.order.status.unknown": "Processing",
     "preferences.cloud.active": "Active",
     "preferences.cloud.inactive": "Not active",
-    "preferences.cloud.usage": "Storage used",
-    "preferences.cloud.expires": "Expires",
+    "preferences.cloud.usage": "Available",
+    "preferences.cloud.expires": "Expiration date",
     "preferences.cloud.syncNow": "Sync now",
     "preferences.cloud.syncComplete": "Sync complete",
     "preferences.cloud.recoveryTitle": "History and conflicts",
@@ -169,6 +216,8 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "notebook.template.loadFailed": "Failed to load notebook templates",
     "notebook.template.empty": "No notebook templates available",
     "notebook.setup.applyingTemplate": "Adding template content…",
+    "notebook.setup.preparingTemplate": "Preparing template files…",
+    "notebook.setup.hide": "Hide",
     "notebook.setup.indexing": "Indexing notebook content…",
     "notebook.setup.failed": "Notebook setup failed",
     "notebook.setup.partial": "Template was applied partially",
@@ -190,11 +239,27 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.general.versionCopied": "Version information copied",
     "preferences.general.versionCopyFailed": "Failed to copy version information",
     "preferences.general.loading": "Loading",
-    "preferences.general.runtimeLogs.title": "Runtime logs",
-    "preferences.general.runtimeLogs.description": "Local folder for app logs",
-    "preferences.general.runtimeLogs.open": "Open",
-    "preferences.general.runtimeLogs.openFolder": "Open log folder",
-    "preferences.general.runtimeLogs.openFailed": "Failed to open log folder",
+    "preferences.environmentConfig.title": "Environment configuration",
+    "preferences.environmentConfig.cloudEnvironment.title": "Cloud environment",
+    "preferences.environmentConfig.cloudEnvironment.description": "The first launch defaults to Prod. Flowix restarts after switching, and a saved selection takes precedence over the startup default.",
+    "preferences.environmentConfig.cloudEnvironment.staging": "Staging Cloud",
+    "preferences.environmentConfig.cloudEnvironment.prod": "Prod",
+    "preferences.environmentConfig.cloudEnvironment.failed": "Failed to switch Cloud environment",
+    "preferences.environmentConfig.cloudEnvironment.restartFailed": "The environment was saved, but Flowix could not restart. Restart the app to apply it.",
+    "preferences.environmentConfig.cloudEnvironment.prodConfirm.title": "Switch to production Cloud?",
+    "preferences.environmentConfig.cloudEnvironment.prodConfirm.description": "Cloud sign-in, sync, and payment requests will use the production environment. Paid actions may create real transactions.",
+    "preferences.environmentConfig.cloudEnvironment.prodConfirm.confirm": "Switch to Prod",
+    "preferences.environmentConfig.versionInitialization.title": "Current version initialization complete",
+    "preferences.environmentConfig.versionInitialization.description": "Turn this off to rerun initialization for the current version on the next launch.",
+    "preferences.environmentConfig.versionInitialization.rerunNextLaunch": "Current version will initialize again on next launch",
+    "preferences.environmentConfig.versionInitialization.markedComplete": "Current version marked as initialized",
+    "preferences.environmentConfig.versionInitialization.loadFailed": "Failed to load version initialization status",
+    "preferences.environmentConfig.versionInitialization.saveFailed": "Failed to save version initialization status",
+    "preferences.environmentConfig.runtimeLogs.title": "Runtime logs",
+    "preferences.environmentConfig.runtimeLogs.description": "Local folder for app logs",
+    "preferences.environmentConfig.runtimeLogs.open": "Open",
+    "preferences.environmentConfig.runtimeLogs.openFolder": "Open log folder",
+    "preferences.environmentConfig.runtimeLogs.openFailed": "Failed to open log folder",
     "preferences.general.productUpdates.title": "Product updates",
     "preferences.general.productUpdates.check": "Check updates",
     "preferences.general.productUpdates.checking": "Checking...",
@@ -204,14 +269,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "productUpdates.version": "Version {version}",
     "productUpdates.openFailed": "Failed to open update link",
     "appUpdates.available": "New version found",
-    "appUpdates.description": "Ready to install. Finish active tool tasks first. This will disconnect Flowix MCP and stop running Flowix CLI processes. The app will restart after installation; reconnect Flowix in your MCP client if its tools are unavailable.",
+    "appUpdates.statusBarVersion": "New version {version}",
     "appUpdates.install": "Install update",
     "appUpdates.downloading": "Downloading…",
     "appUpdates.installing": "Installing…",
-    "appUpdates.statusDownloading": "Downloading",
-    "appUpdates.statusDownloadingProgress": "Downloading {percent}%",
-    "appUpdates.statusInstalling": "Installing",
-    "appUpdates.progress": "Download progress: {percent}%",
     "appUpdates.installFailed": "Failed to install update",
     "appUpdates.installSucceeded": "Flowix was updated and restarted",
     "appUpdates.previousInstallFailed": "The previous update failed",
@@ -368,10 +429,11 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.agent.testError.other": "Test failed",
     "preferences.agents.title": "AI Agent configuration",
     "preferences.agents.subtitle":
-      "Configure the Agent types below for use in document input / activation",
+      "Enable configured Agents to use them in the slash menu and new conversations",
+    "preferences.agents.enableAgent": "Enable {name}",
+    "preferences.agents.cacheWriteFailed": "Agent preferences still work in this window, but could not be saved locally. They may be lost when the app restarts.",
     "preferences.dsh.title": "DeepSeek Harness (Beta)",
     "preferences.pi.title": "Models",
-    "preferences.pi.description": "Manage Pi providers and model lists. Switch models below the conversation input.",
     "preferences.pi.mcp.title": "MCP servers",
     "preferences.pi.mcp.description": "Manage Pi's global MCP configuration. Pi reads changes the next time it starts. Use ${NAME} to reference environment variables instead of storing secrets here.",
     "preferences.pi.mcp.empty": "No MCP servers configured.",
@@ -435,6 +497,19 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.pi.deleted": "Pi provider deleted",
     "preferences.pi.oldProviderCleanupFailed": "The new provider was saved, but the old provider configuration could not be removed",
     "preferences.pi.validation": "Enter provider details and at least one model ID",
+    "preferences.pi.cloudTitle": "Member models",
+    "preferences.pi.creditMultiplier": "Credit consumption multiplier: {value}×",
+    "preferences.pi.cloudCreditsBalance": "Credits balance",
+    "preferences.pi.cloudCreditsUnit": "credits",
+    "preferences.pi.cloudCreditsRefresh": "Refresh balance",
+    "preferences.pi.cloudCreditsLoading": "Loading…",
+    "preferences.pi.cloudCreditsUnavailable": "Unavailable",
+    "preferences.pi.cloudConnect": "Connect Cloud models",
+    "preferences.pi.cloudConnected": "Flowix Cloud models were added to Pi",
+    "preferences.pi.byokTitle": "My Models",
+    "preferences.pi.defaultModelTag": "Default · {name}",
+    "preferences.pi.byokEmpty": "No BYOK providers yet. Cloud models and BYOK providers can be used side by side.",
+    "preferences.pi.byokAdd": "Add BYOK provider",
     "preferences.dsh.description": "A high-performance AI Agent for office work and coding",
     "preferences.dsh.tabs.models": "Models",
     "preferences.dsh.tabs.general": "General",
@@ -474,76 +549,24 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.dsh.plugins.skills": "Load and use reusable skill instructions.",
     "preferences.dsh.plugins.subagents": "Create subagents to collaborate on tasks.",
     "preferences.dsh.plugins.workflows": "Compose multi-step tasks and run workflows.",
-    "preferences.dsh.runtime.title": "DeepSeek Harness Runtime",
-    "preferences.dsh.runtime.officialProfile": "Flowix uses an independent headless DSH Runtime, installed under the Flowix data directory:",
-    "preferences.dsh.runtime.officialHint": "The Runtime updates independently from Flowix; packages are checked with the SHA-256 declared by latest.json.",
-    "preferences.dsh.runtime.officialCommands": "Flowix starts DSH automatically when you first use a DSH Agent.",
-    "preferences.dsh.runtime.install": "Install DSH Runtime",
-    "preferences.dsh.runtime.installing": "Installing…",
-    "preferences.dsh.runtime.updating": "Updating…",
-    "preferences.dsh.runtime.update": "Update DSH Runtime",
-    "preferences.dsh.runtime.check": "Check for updates",
-    "preferences.dsh.runtime.checking": "Checking…",
-    "preferences.dsh.runtime.updateSuccess": "DSH Runtime updated successfully",
-    "preferences.dsh.runtime.upToDate": "DSH Runtime is already up to date",
-    "preferences.dsh.runtime.updateFailed": "Failed to check or update DSH Runtime",
-    "agent.dsh.updateAvailable": "New version {version} found — click to update",
-    "agent.dsh.updatePreparing": "Preparing update…",
-    "agent.dsh.updateDownloading": "Downloading update {percent}%",
-    "agent.dsh.updateInstalling": "Installing update…",
-    "agent.dsh.updateComplete": "DSH Runtime updated",
-    "agent.dsh.updateFailed": "Update failed — click to retry",
     "agent.pi.unavailable": "No available PI service found",
-    "preferences.dsh.runtime.cancel": "Cancel",
-    "preferences.dsh.runtime.downloadProgress": "Download progress",
-    "preferences.dsh.runtime.downloading": "dsh downloading",
-    "preferences.dsh.runtime.resumed": "Resumed from the previous partial download",
-    "preferences.dsh.runtime.installed": "Installed",
-    "preferences.dsh.runtime.detected": "DSH Runtime installed",
-    "preferences.dsh.runtime.packageSize": "Size",
-    "preferences.dsh.runtime.notDetected": "DSH Runtime is not installed yet.",
-    "preferences.dsh.runtime.uninstall": "Uninstall DeepSeek Harness",
     "preferences.dsh.runtime.version": "Version",
-    "preferences.dsh.runtime.uninstallButton": "Uninstall",
-    "preferences.dsh.runtime.uninstallHint": "Only the DSH package is removed; configured models and session data are not affected.",
-    "preferences.dsh.runtime.uninstalling": "Uninstalling…",
-    "preferences.dsh.runtime.uninstallSuccess": "DeepSeek Harness uninstalled successfully",
-    "preferences.dsh.runtime.uninstallFailed": "Failed to uninstall DeepSeek Harness",
-    "preferences.dsh.runtime.uninstallConfirm": "Uninstall the DeepSeek Harness Runtime? Running DeepSeek Harness tasks will be rejected first; model settings and session history (~/.dsh) are kept.",
-    "preferences.dsh.install.prompt": "Download and start DeepSeek Harness? It is an optional local Agent runtime for Flowix.",
-    "preferences.dsh.install.complete": "DeepSeek Harness is installed and will start automatically when you first use a DSH Agent.",
-    "preferences.dsh.install.failed": "DeepSeek Harness installation failed",
     "preferences.dsh.setup.loading": "Checking DeepSeek Harness status…",
     "preferences.dsh.setup.title": "Deepseek Harness",
-    "preferences.dsh.setup.promptTitle": "Download DeepSeek Harness",
-    "preferences.dsh.setup.description": "Harness keeps your Agent working in real-world scenarios",
-    "preferences.dsh.setup.promptDescription": "DeepSeek Harness (dsh) is DeepSeek's open-source AI Agent runtime framework—everything is a plugin. After installation, it can be uninstalled separately from Preferences.",
-    "preferences.dsh.setup.carousel": "DeepSeek Harness setup",
-    "preferences.dsh.setup.mcp.slide": "Flowix MCP",
-    "preferences.dsh.setup.mcp.title": "Flowix MCP",
-    "preferences.dsh.setup.mcp.description": "Open another AI client, copy the setup instructions, and send them to connect Flowix MCP. The AI client may need file access while updating its configuration.",
-    "preferences.dsh.setup.mcp.copyContent": "Please install Flowix MCP in the current AI client.\n\nTransport: stdio\ncommand: {command}\nargs: [\"mcp\"]\n\nAdd it to this client's MCP configuration. Before making changes, tell me which configuration file you will edit and the exact changes. Do not modify other MCP entries.",
-    "preferences.dsh.setup.intro.slide": "Local Agent check",
-    "preferences.dsh.setup.download.slide": "DeepSeek Harness download",
-    "preferences.dsh.setup.intro.checking": "Checking for local AI Agents…",
-    "preferences.dsh.setup.intro.detected": "Detected {agent}",
-    "preferences.dsh.setup.intro.none": "No local AI Agent found",
-    "preferences.dsh.setup.intro.description": "Use the / command in a note to insert a session with an AI Agent. Multiple sessions in the document share its content.",
-    "preferences.dsh.setup.intro.noAgentDescription": "Flowix can directly call Codex, Claude Code, or OpenCode installed locally.",
-    "preferences.dsh.setup.next": "Next",
-    "preferences.dsh.setup.previous": "Back",
-    "preferences.dsh.setup.install": "Install DeepSeek Harness",
-    "preferences.dsh.setup.installing": "Installing…",
-    "preferences.dsh.setup.downloading": "Downloading…",
-    "preferences.dsh.setup.cancel": "Cancel",
-    "preferences.dsh.setup.installSuccess": "DSH Runtime downloaded and installed successfully",
-    "preferences.dsh.setup.installFailed": "Failed to download or install DSH Runtime",
-    "preferences.dsh.setup.cancelled": "DSH Runtime download cancelled",
     "preferences.dsh.setup.retry": "Retry",
-    "preferences.dsh.setup.error": "Installation failed",
-    "preferences.dsh.setup.downloadProgress": "Downloading DSH Runtime",
-    "preferences.dsh.setup.resumed": "Resumed from the previous partial download",
-    "preferences.dsh.setup.security": "Packages are verified with the SHA-256 declared by latest.json. After installation, this page will show the DSH Models, General, Runtime, and Presets settings.",
+    "preferences.dsh.appServer.missingDescription": "DSH is installed. Install the Flowix App Server plugin to use the DSH Agent in Flowix.",
+    "preferences.dsh.appServer.localDetected": "Local check found DSH {version} installed",
+    "preferences.dsh.appServer.updateDescription": "The Flowix App Server plugin is out of date. Update the profile to keep using the DSH Agent.",
+    "preferences.dsh.appServer.runtimeMissingDescription": "Local DSH was not found. Or select a local DSH path below to add it.",
+    "preferences.dsh.appServer.localRuntime": "Local DSH detected: {path}",
+    "preferences.dsh.appServer.installationPath": "DSH installation path",
+    "preferences.dsh.appServer.managedRuntime": "Flowix DSH Runtime detected: {version}",
+    "preferences.dsh.appServer.openOfficialInstall": "Open official DSH install page",
+    "preferences.dsh.appServer.install": "Install the Flowix plugin for DSH",
+    "preferences.dsh.appServer.installNote": "For communication and conversation management",
+    "preferences.dsh.appServer.update": "Update DSH App Server plugin",
+    "preferences.dsh.appServer.installing": "Installing plugin…",
+    "preferences.dsh.appServer.installSuccess": "DSH App Server plugin installed and connection verified",
     "preferences.dsh.presets.title": "Agent presets",
     "preferences.dsh.presets.hint": "Choose a preset per session from the mode settings in DeepSeek Harness.",
     "preferences.agents.codex.downloadPrompt": "Download Codex CLI?",
@@ -595,10 +618,6 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "agent.types.claude.desc": "Architecture analysis, complex refactors, plan synthesis",
     "agent.types.hermes.name": "Hermes",
     "agent.types.hermes.desc": "Use a locally installed Hermes",
-    "agent.types.gemini.name": "Gemini CLI",
-    "agent.types.gemini.desc": "Use a locally installed Gemini CLI",
-    "agent.types.openclaw.name": "OpenClaw",
-    "agent.types.openclaw.desc": "Use a locally installed OpenClaw",
     "agent.types.opencode.name": "OpenCode",
     "agent.types.opencode.desc": "Use OpenCode through Agent Client Protocol",
     "agent.types.pi.name": "Pi",
@@ -619,7 +638,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.shortcuts.resetOneAria": "Reset {title} to default",
     "preferences.shortcuts.group.editor": "Editor",
     "preferences.shortcuts.action.editor.selectAll.title": "Select all",
-    "preferences.shortcuts.action.editor.selectAll.description": "Select all content in the current editor.",
+    "preferences.shortcuts.action.editor.selectAll.description": "Select all content in the current editor",
     "preferences.shortcuts.group.navigation": "Navigation",
     "preferences.shortcuts.group.view": "View",
     "preferences.shortcuts.group.system": "System",
@@ -636,79 +655,79 @@ const enUS: Record<keyof typeof zhCN, string> = {
       "Esc to cancel · Enter to confirm · Backspace to record again",
     "preferences.shortcuts.action.editor.find.title": "Find in editor",
     "preferences.shortcuts.action.editor.find.description":
-      "Open or close search and replace for the current editor.",
+      "Open or close search and replace for the current editor",
     "preferences.shortcuts.action.editor.undo.title": "Undo",
     "preferences.shortcuts.action.editor.undo.description":
-      "Undo the last edit.",
+      "Undo the last edit",
     "preferences.shortcuts.action.editor.redo.title": "Redo",
     "preferences.shortcuts.action.editor.redo.description":
-      "Redo the last undone edit.",
+      "Redo the last undone edit",
     "preferences.shortcuts.action.editor.setHeading1.title": "Heading 1",
     "preferences.shortcuts.action.editor.setHeading1.description":
-      "Set the current block to H1.",
+      "Set the current block to H1",
     "preferences.shortcuts.action.editor.setHeading2.title": "Heading 2",
     "preferences.shortcuts.action.editor.setHeading2.description":
-      "Set the current block to H2.",
+      "Set the current block to H2",
     "preferences.shortcuts.action.editor.setHeading3.title": "Heading 3",
     "preferences.shortcuts.action.editor.setHeading3.description":
-      "Set the current block to H3.",
+      "Set the current block to H3",
     "preferences.shortcuts.action.editor.setHeading4.title": "Heading 4",
     "preferences.shortcuts.action.editor.setHeading4.description":
-      "Set the current block to H4.",
+      "Set the current block to H4",
     "preferences.shortcuts.action.editor.setParagraph.title": "Paragraph",
     "preferences.shortcuts.action.editor.setParagraph.description":
-      "Convert the current block to paragraph text.",
+      "Convert the current block to paragraph text",
     "preferences.shortcuts.action.editor.toggleBulletList.title":
       "Bulleted list",
     "preferences.shortcuts.action.editor.toggleBulletList.description":
-      "Turn the current block into a bulleted list.",
+      "Turn the current block into a bulleted list",
     "preferences.shortcuts.action.editor.toggleOrderedList.title":
       "Numbered list",
     "preferences.shortcuts.action.editor.toggleOrderedList.description":
-      "Turn the current block into a numbered list.",
+      "Turn the current block into a numbered list",
     "preferences.shortcuts.action.editor.toggleTaskList.title": "Task list",
     "preferences.shortcuts.action.editor.toggleTaskList.description":
-      "Turn the current block into a task list.",
+      "Turn the current block into a task list",
     "preferences.shortcuts.action.palette.search.title":
       "Toggle command palette",
     "preferences.shortcuts.action.palette.search.description":
-      "Open or close global search and command palette.",
+      "Open or close global search and command palette",
     "preferences.shortcuts.action.menu.open.title": "Open preferences",
     "preferences.shortcuts.action.menu.open.description":
-      "Open the Preferences window.",
+      "Open the Preferences window",
     "preferences.shortcuts.action.history.back.title": "Back",
     "preferences.shortcuts.action.history.back.description":
-      "Go back to the previous note.",
+      "Go back to the previous note",
     "preferences.shortcuts.action.history.forward.title": "Forward",
     "preferences.shortcuts.action.history.forward.description":
-      "Go forward to the next note.",
+      "Go forward to the next note",
     "preferences.shortcuts.action.memo.create.title": "New note",
     "preferences.shortcuts.action.memo.create.description":
-      "Create a new note in the selected notebook.",
+      "Create a new note in the selected notebook",
     "preferences.shortcuts.action.notebook.create.title": "New notebook",
     "preferences.shortcuts.action.notebook.create.description":
-      "Open the new notebook dialog.",
+      "Open the new notebook dialog",
     "preferences.shortcuts.action.notebook.switcher.toggle.title":
       "Toggle notebook switcher",
     "preferences.shortcuts.action.notebook.switcher.toggle.description":
-      "Open or close the notebook switcher in the status bar.",
+      "Open or close the notebook switcher in the status bar",
     "preferences.shortcuts.action.theme.toggle.title": "Toggle theme",
     "preferences.shortcuts.action.theme.toggle.description":
-      "Cycle through available themes.",
+      "Cycle through available themes",
     "preferences.shortcuts.action.panel.memoList.toggle.title":
       "Show/hide note list",
     "preferences.shortcuts.action.panel.memoList.toggle.description":
-      "Toggle the left note list panel.",
+      "Toggle the left note list panel",
     "preferences.shortcuts.action.panel.noteNavigation.toggle.title":
       "Show/hide note navigation sidebar",
     "preferences.shortcuts.action.panel.noteNavigation.toggle.description":
-      "Toggle the leftmost note navigation (tags / notebooks) sidebar.",
+      "Toggle the leftmost note navigation (tags / notebooks) sidebar",
     "preferences.shortcuts.action.dialog.cancel.title": "Close dialog",
     "preferences.shortcuts.action.dialog.cancel.description":
-      "Close the current modal dialog.",
+      "Close the current modal dialog",
     "preferences.shortcuts.action.dialog.confirm.title": "Confirm dialog",
     "preferences.shortcuts.action.dialog.confirm.description":
-      "Confirm the default action in the current modal dialog.",
+      "Confirm the default action in the current modal dialog",
 
     "preferences.connections.title": "Integrations",
     "preferences.connections.connect": "暂未开放",
@@ -745,6 +764,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
       "Search across notes, with optional notebook and result limits.",
     "preferences.cli.commands.completion": "Print shell completion scripts.",
     "preferences.cli.commands.pluginCreate": "Create a plugin artifact and its Flowix document from standard input.",
+    "plugin.workbench.generating": "Generating plugin artifact…",
 
     "preferences.mcp.title": "MCP Server",
     "preferences.mcp.generic": "Standard MCP configuration",
@@ -770,6 +790,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "window.minimize": "Minimize",
     "window.maximize": "Maximize",
     "window.close": "Close",
+    "window.closeNativeUnavailable": "Native close protection is unavailable. The button can still close a responsive window; use Task Manager if Flowix stops responding.",
+    "window.closeNativeRestored": "Native close protection is available again.",
+    "window.closeRequestFailed": "The close request could not be confirmed. Click Close again if Flowix remains open; use Task Manager if it stops responding.",
+    "notebook.delete.saveCurrentDocumentFailed": "Could not save the current document. Retry saving it before deleting the notebook.",
     "tabWindow.all": "All",
     "tabWindow.showAll": "All",
     "tabWindow.openContent": "Open content in browser column",
@@ -783,12 +807,12 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "tabWindow.createNote.failed": "Could not create the note",
     "tabWindow.context.newConversation": "New conversation",
     "tabWindow.createConversation.failed": "Could not create the conversation",
-    "tabWindow.context.moveWebUnavailable": "Webpages can currently only be viewed in the auxiliary workspace.",
-    "tabWindow.context.moveFolderUnavailable": "Select a file in this folder before moving it to the main workspace.",
+    "tabWindow.context.moveFolderUnavailable": "Select a file in this folder before opening it in the main workspace.",
     "tabWindow.switchFailed": "Could not switch tabs. Your current content remains open. Check that saving succeeds, then try again.",
     "tabWindow.confirmDiscardChanges": "This document could not be saved. Discard unsaved local content and close it?",
-    "tabWindow.context.openInWorkColumn": "Move to main workspace",
+    "tabWindow.context.openInWorkColumn": "Open in main workspace",
     "workColumn.context.openInBrowserColumn": "Open in auxiliary workspace",
+    "workColumn.context.alsoOpenInBrowserColumn": "Also open in right column",
     "workspace.alreadyOpen": "Document is already open",
     "error.title": "Something went wrong",
     "error.unexpected": "An unexpected error occurred",
@@ -805,7 +829,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "status.agent.loadingMoreConversations": "Loading…",
     "status.agent.noConversations": "No sessions",
     "status.agent.loadConversationsFailed": "Could not load sessions",
-    "status.agent.loadHistoryFailed": "Could not load conversation history",
+    "status.agent.loadHistoryFailed": "Could not load conversation",
+    "status.agent.historySessionNotFound": "This conversation could not be found. It may have been deleted.",
+    "status.agent.historyRefreshFailed": "Refresh failed. The conversation may not be up to date.",
+    "status.agent.newConversation": "New conversation",
     "status.agent.openRun": "Open document",
     "status.agent.openConversation": "Open session",
     "status.agent.originUnavailable": "Document unavailable",
@@ -816,6 +843,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "status.agent.deleteSuccess": "Session deleted",
     "document.agent.viewInNote": "View in note",
     "document.agent.moreActions": "More actions",
+    "agent.chat.messageFontSize": "Message size",
+    "agent.chat.messageFontSize.small": "Small",
+    "agent.chat.messageFontSize.medium": "Medium",
+    "agent.chat.messageFontSize.large": "Large",
     "document.agent.archiveConversation": "Archive session",
     "document.agent.deleteConversation": "Delete session",
     "document.agent.deleteConfirm": "This permanently deletes the session history on the agent side and cannot be undone. Delete it?",
@@ -825,6 +856,8 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "status.notebook": "Notebook",
     "status.switchNotebook": "Switch notebook",
     "status.notebookList": "Notebook list",
+    "status.searchNotebookPlaceholder": "Search notebooks",
+    "status.noMatchingNotebooks": "No matching notebooks",
     "status.previousNotebookPage": "Previous notebook page",
     "status.nextNotebookPage": "Next notebook page",
     "status.notebookMemoCount": "{count} notes",
@@ -881,6 +914,9 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "agent.model.menu": "Model",
     "agent.model.title": "Model",
     "agent.speed.title": "Speed",
+    "agent.pi.modelTab.member": "Membership",
+    "agent.pi.modelTab.mine": "My models",
+    "agent.pi.modelTab.mineEmpty": "No personal models configured",
     "agent.model.noneFound": "No models found",
     "agent.model.configure": "Configure models",
     "agent.model.loadFailed": "Failed to load models",
@@ -942,7 +978,12 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "agent.deepseekHarness.reconnectFailed": "DeepSeek Harness reconnect failed",
     "agent.deepseekHarness.failureReason": "Failure reason: {reason}",
     "agent.error.diagnostic.requestId": "Request ID: {value}",
+    "agent.error.diagnostic.reference": "If you contact support, provide reference: {value}",
     "agent.error.diagnostic.retryAfter": "Retry after: {value}",
+    "agent.error.membershipRequired": "This model requires an active Flowix Cloud membership. Check your status in Settings > Membership and storage. If your membership is active, sign in again and retry.",
+    "agent.error.insufficientCredits": "There are not enough Flowix credits to reserve this request. Reduce the output length or contact an administrator to add credits, then retry.",
+    "agent.error.cloudModelUnavailable": "This Flowix Cloud model is currently unavailable. Refresh the Cloud catalog in Settings > Pi and select an available model.",
+    "agent.error.cloudPricingUnavailable": "Flowix Cloud has no models with active credit pricing. Contact an administrator.",
     "agent.error.guidance.authentication": "Check this agent's sign-in state or API key configuration.",
     "agent.error.guidance.rate_limited": "The request was rate limited. Retry after the quota recovers.",
     "agent.error.guidance.network": "The network connection failed. Check your connection and retry.",
@@ -956,8 +997,6 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "agent.opencodeSession.title": "OpenCode session",
     "agent.piSession.title": "Pi session",
     "agent.hermesSession.title": "Hermes session",
-    "agent.geminiSession.title": "Gemini CLI session",
-    "agent.openclawSession.title": "OpenClaw session",
     "agent.time.justNow": "Just now",
     "agent.time.seconds": "{s}s",
     "agent.time.minutes": "{m}m",
@@ -1036,7 +1075,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "agent.tools.completedSteps": "Completed {count} steps",
     "agent.tools.processing": "Processing",
     "agent.tools.runningSteps": "Processing, {count} steps completed",
-    "agent.tools.failedSteps": "{count} steps incomplete",
+    "agent.tools.finishedSteps": "Finished {count} steps",
     "agent.tools.noInput": "No input information",
     "agent.tools.input": "Input",
     "agent.tools.output": "Output",
@@ -1122,13 +1161,38 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.list.notebookMenu.appearanceTheme": "Appearance theme",
     "memo.list.notebookMenu.preferences": "Preferences",
     "memo.list.notebookMenu.about": "About",
+    "memo.list.notebookMenu.pin": "Pin notebook",
+    "memo.list.notebookMenu.unpin": "Unpin notebook",
+    "memo.list.notebookMenu.pinFailed": "Failed to update pinned state",
     "memo.list.notebookMenu.officialWebsite": "Website",
     "memo.list.notebookMenu.community": "Community",
+    "memo.list.notebookMenu.feedback": "Feedback",
+    "memo.list.notebookMenu.feedback.title": "Send feedback",
+    "memo.list.notebookMenu.feedback.description": "Your suggestions or problems you encountered while using Flowix",
+    "memo.list.notebookMenu.feedback.type": "Type",
+    "memo.list.notebookMenu.feedback.required": "Required",
+    "memo.list.notebookMenu.feedback.suggestion": "Product suggestion",
+    "memo.list.notebookMenu.feedback.issue": "Usage problem",
+    "memo.list.notebookMenu.feedback.content": "Message",
+    "memo.list.notebookMenu.feedback.placeholder": "Describe your suggestion or the problem you encountered",
+    "memo.list.notebookMenu.feedback.attachments": "Attachments",
+    "memo.list.notebookMenu.feedback.addImage": "Add image",
+    "memo.list.notebookMenu.feedback.removeImage": "Remove image",
+    "memo.list.notebookMenu.feedback.imageHint": "Upload or paste images, up to 3",
+    "memo.list.notebookMenu.feedback.imageLimit": "Add up to 3 PNG, JPG, WebP, or GIF images, each no larger than 5 MB.",
+    "memo.list.notebookMenu.feedback.cancel": "Cancel",
+    "memo.list.notebookMenu.feedback.submit": "Submit",
+    "memo.list.notebookMenu.feedback.submitting": "Submitting…",
+    "memo.list.notebookMenu.feedback.submitSucceeded": "Submitted successfully",
+    "memo.list.notebookMenu.feedback.submitFailed": "Submission failed. Please try again",
     "memo.list.preferences": "Preferences",
     "memo.list.preferencesTooltip": "Preferences",
     "memo.list.emptyNotFound": "No notes found",
+    "memo.list.emptyNoNotebook": "No notebooks yet",
+    "memo.list.createNotebook": "Create notebook",
     "memo.list.loadingNotebook": "Loading…",
     "memo.list.loadingLibrary": "Indexing notes...",
+    "memo.list.loadingMore": "Loading more notes...",
     "memo.list.loadFailed": "Failed to load notes",
     "memo.tag.expand": "Expand tag",
     "memo.tag.collapse": "Collapse tag",
@@ -1149,6 +1213,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.tag.createdToast": "Added tag #{{path}}",
     "memo.tag.rename": "Rename",
     "memo.tag.pin": "Pin to top",
+    "memo.tag.unpin": "Unpin",
     "memo.tag.batchManage": "Batch manage",
     "memo.tag.batchDone": "Done",
     "memo.tag.batchDelete": "Delete tag #{{path}}",
@@ -1223,13 +1288,25 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.list.searchTooltip": "Full-text search",
     "memo.list.newMemoTooltip": "New note",
     "memo.create.chooseType": "Create new",
-    "memo.create.documents": "New documents",
+    "memo.create.documents": "New notes",
     "memo.create.conversations": "New conversations",
     "memo.create.templateFailed": "Failed to create document from template",
     "memo.create.note": "Note",
     "memo.create.table": "Multidimensional table",
     "memo.create.more": "Create…",
+    "memo.create.newView": "New view",
     "memo.fileTree.import": "Import",
+    "memo.fileTree.importFiles": "Import files…",
+    "memo.fileTree.importFolder": "Import folder…",
+    "memo.fileTree.importFolderSuccess": "Folder imported",
+    "memo.fileTree.importFolderInProgress": "Importing folder…",
+    "memo.fileTree.importFolderFailed": "Failed to import folder",
+    "memo.fileTree.importFolderCleanupFailed": "Import failed and some files may remain at the destination. Please check and remove them if needed.",
+    "memo.fileTree.importFolderExists": "A folder with that name already exists at the destination. Rename it or choose another location.",
+    "memo.fileTree.importFolderTooManyFiles": "The folder contains more than 2,000 files. Import it in smaller batches.",
+    "memo.fileTree.importFolderTooManyEntries": "The folder tree contains more than 5,000 files and folders. Choose a smaller folder.",
+    "memo.fileTree.importFolderTooDeep": "The folder is nested more than 32 levels. Choose a smaller folder.",
+    "memo.fileTree.importFolderTooLarge": "The folder is larger than 5 GiB. Import it in smaller batches.",
     "memo.create.tableDialogTitle": "New table",
     "memo.create.galleryDialogTitle": "New gallery",
     "memo.create.kanbanDialogTitle": "New kanban",
@@ -1278,6 +1355,11 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "mediaLibrary.videos": "Videos",
     "mediaLibrary.itemCount": "{count}{more} items",
     "mediaLibrary.opening": "Opening media library…",
+    "mediaLibrary.refreshFailed": "Could not refresh the media library",
+    "mediaLibrary.maintenanceQueued": "Waiting to refresh the media index",
+    "mediaLibrary.maintenanceRunning": "Refreshing the media index…",
+    "mediaLibrary.maintenanceFailed": "Media index maintenance failed",
+    "mediaLibrary.maintenanceRetryFailed": "Could not retry media index maintenance",
     "mediaLibrary.unavailable": "Media library unavailable",
     "mediaLibrary.saveProgress": "Saving…",
     "mediaLibrary.empty": "No images or videos yet",
@@ -1345,15 +1427,43 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.navigation.all": "All",
     "memo.navigation.allNotes": "Notes",
     "memo.navigation.conversations": "Sessions",
+    "memo.guide.ariaLabel": "List view introduction",
+    "memo.guide.pageStatus": "Page {current} of {total}",
+    "memo.guide.goToPage": "Go to page {page}",
+    "memo.guide.close": "Close introduction",
+    "memo.guide.previous": "Back",
+    "memo.guide.next": "Next",
+    "memo.guide.done": "Get started",
+    "memo.guide.fileTree.title": "Browse the file tree",
+    "memo.guide.fileTree.description": "Browse notes, images, videos, and other files in a familiar folder tree.",
+    "memo.guide.notes.title": "Explore your notes",
+    "memo.guide.notes.description": "See all Markdown documents in one place, ready for focused writing.",
+    "memo.guide.conversations.title": "Work with AI conversations",
+    "memo.guide.conversations.description": "Manage local conversations and let AI read your notebook workspace.",
     "memo.navigation.collapseNotebookList": "Collapse notebook list",
     "memo.navigation.expandNotebookList": "Expand notebook list",
     "memo.navigation.notebooks": "Notebooks",
     "memo.navigation.tags": "Tags",
     "memo.navigation.referenceMaterials": "Source",
     "memo.navigation.loading": "Loading…",
+    "memo.navigation.preparingVersion": "Initializing version…",
     "memo.navigation.preparingNotebook": "Preparing notebook…",
-    "memo.navigation.preparingWorkspace": "Preparing workspace…",
-    "memo.navigation.startupMigrationFailed": "Workspace migration failed. Restart the app and try again.",
+    "memo.navigation.workspacePreparationFailed": "Workspace preparation failed. Please retry.",
+    "startup.progress.prepareDatabasePaths": "Migrating database files",
+    "startup.progress.prepareThreadDatabase": "Preparing conversation database",
+    "startup.progress.prepareSyncDatabase": "Preparing sync database",
+    "startup.progress.prepareNotebookRegistry": "Preparing notebook registry",
+    "startup.progress.runMigrations": "Applying migrations",
+    "startup.progress.migrateAgentLayout": "Migrating Agent settings",
+    "startup.progress.migrateLocalConfiguration": "Migrating local settings",
+    "startup.progress.migrateWatcherSettings": "Updating file watcher settings",
+    "startup.progress.prepareTemplates": "Preparing templates",
+    "startup.progress.migrateNotebookStorage": "Updating notebook storage",
+    "startup.progress.deferredNotebookJobs": "Waiting for notebook availability",
+    "startup.progress.prepareRuntimeStorage": "Preparing runtime storage",
+    "startup.progress.activateRuntime": "Activating runtime configuration",
+    "startup.progress.completeInitialization": "Finishing version initialization",
+    "memo.navigation.startupMigrationFailed": "Initialization failed. Please retry.",
     "memo.navigation.emptyTags": "No tags",
     "memo.navigation.emptyReferences": "No reference materials",
     "memo.navigation.files": "Source",
@@ -1364,6 +1474,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.fileTree.agentsSectionTitle": "Sessions",
     "memo.fileTree.agentsEmpty": "List is empty",
     "memo.fileTree.moreAgents": "More",
+    "memo.fileTree.openAllConversations": "Open all conversations",
     "memo.fileTree.collapseAgents": "Collapse conversations",
     "memo.fileTree.expandAgents": "Expand conversations",
     "memo.fileTree.pinnedSectionTitle": "Pinned",
@@ -1399,6 +1510,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.fileTree.newDocument": "New document",
     "memo.fileTree.newFolder": "New folder",
     "memo.fileTree.customizeDisplay": "Customize display",
+    "memo.fileTree.hideSection": "Hide",
     "memo.fileTree.rename": "Rename",
     "memo.fileTree.renaming": "Renaming…",
     "memo.fileTree.moreActions": "More actions",
@@ -1413,6 +1525,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.fileTree.deleted": "Deleted {name}",
     "memo.fileTree.deleteFailed": "Delete failed",
     "memo.fileTree.deletePartialFailed": "The folder was only partly deleted. Refresh and check the remaining files.",
+    "memo.fileTree.deleteFolderViewCleanupFailed": "The folder was deleted, but its open content could not be cleared.",
     "memo.fileTree.createFailed": "Create failed",
     "memo.fileTree.nameConflict": "A file with this name already exists. Choose another name.",
     "memo.fileTree.openInNewTab": "Open in new tab",
@@ -1429,9 +1542,19 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "memo.fileTree.openFailed": "Open failed",
     "memo.fileTree.moveFailed": "Move failed",
     "memo.fileTree.movePartialFailed": "Move failed: {moved} succeeded, {failed} failed",
+    "memo.fileTree.movePartialFailedWithReason": "Move failed: {moved} succeeded, {failed} failed ({reason})",
+    "memo.fileTree.moveDuplicate": "A document with this name already exists",
+    "memo.fileTree.moveCloudFileNotDownloaded": "This file is still in the cloud. Download it and try again.",
+    "memo.fileTree.movePermissionDenied": "The file or destination folder cannot be accessed",
+    "memo.fileTree.moveSourceUnavailable": "The source file no longer exists or is not a regular file",
+    "memo.fileTree.moveTargetUnavailable": "The destination folder is unavailable",
     "memo.fileTree.moving": "Moving",
     "memo.fileTree.moved": "Moved",
     "memo.fileTree.draggingNotes": "Dragging {count} notes",
+    "memo.fileTree.calendarDropUnsupported": "This document cannot be added to the calendar",
+    "memo.fileTree.kanbanDropUnsupported": "Only Markdown notes from this notebook can be added to the kanban board",
+    "memo.fileTree.galleryDropUnsupported": "Only Markdown notes from this notebook can be added to the gallery",
+    "memo.fileTree.tableDropUnsupported": "Only Markdown notes from this notebook can be added to the table",
     "memo.fileTree.dropToMove": "Release to move here",
     "memo.fileTree.dropToRoot": "Release to move to notebook root",
     "memo.fileTree.loading": "Loading…",
@@ -1442,13 +1565,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "notebook.iconLabel": "ICON",
     "notebook.create.title": "New notebook",
     "notebook.create.namePlaceholder": "Notebook name",
-    "notebook.create.pathPlaceholder": "Choose where to store notes",
+    "notebook.create.pathPlaceholder": "Default document location",
     "notebook.create.pathLabel": "Storage location",
     "notebook.create.selectDirectory": "Choose directory",
-    "notebook.create.customPath": "Customize storage path",
     "notebook.create.cancel": "Close",
-    "notebook.create.confirm": "New notebook",
-    "notebook.create.creating": "Creating…",
     "notebook.edit.title": "Edit notebook",
     "notebook.edit.namePlaceholder": "Notebook name",
     "notebook.edit.pathLabel": "Storage path",
@@ -1456,10 +1576,6 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "notebook.edit.confirm": "Save",
     "notebook.edit.saving": "Saving...",
     "notebook.edit.remove": "Remove",
-    "notebook.edit.agents.title": "Notebook description",
-    "notebook.edit.agents.placeholder": "Add prompts to help AI understand the content\nThe input will be added to AGENTS.md",
-    "notebook.edit.agents.saved": "Notebook and AGENTS.md saved",
-    "notebook.edit.agents.saveFailed": "Failed to save the notebook description",
 
     // document
     "document.file.unavailable": "This file cannot be viewed",
@@ -1467,6 +1583,7 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "document.file.openContainingFolder": "Open Containing Folder",
     "document.file.openWithDefaultApp": "Open with Default App",
     "document.file.reveal": "Show in Finder",
+    "collection.resetCurrentView": "Reset Current View",
     "document.file.locationClamped": "The file opened, but the requested position was past its current content. The cursor moved to the end.",
     "document.file.anchorNotFound": "The file opened, but the referenced heading could not be found.",
     "document.file.locationUnsupported": "The file opened, but this view cannot navigate to a line or heading.",
@@ -1581,7 +1698,6 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "document.save.useDisk": "Use the file version",
     "document.save.retry": "Retry saving",
     "document.save.missing": "The file is unavailable",
-    "document.save.closeFailed": "Some changes are still being saved. The window will stay open.",
     "document.save.titleFailed": "The title could not be saved. Edit it to try again.",
     "document.save.titleEmpty": "Enter a file name.",
     "document.save.recoverTitle": "Recover unsaved title",
@@ -1589,8 +1705,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "document.save.externalChanged": "This note was changed outside Flowix",
     "document.save.sourceMissingDiscarded": "The source file no longer exists. Unsaved local content was discarded and the tab was closed.",
     "document.load.failed": "Failed to read",
+    "document.load.missingNoteTitle": "Something went wrong. The following note could not be found.",
     "document.load.accessDenied": "This file is outside the authorized scope or cannot be accessed by the current user.",
     "document.load.fileNotFound": "The file does not exist or its actual path could not be resolved.",
+    "document.load.recoveryTimeout": "Reading the recovery draft timed out. Try again.",
     "document.load.notTextFile": "The target is not a supported text file.",
     "document.properties.title": "Properties",
     "document.properties.noteTitle": "Properties",
@@ -1812,6 +1930,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "editor.noteLink.stale": "Note not found · {path}",
     "editor.noteLink.untitled": "Untitled",
     "editor.noteLink.staleMark": "(not found)",
+    "editor.noteLink.previewLoading": "Loading note preview…",
+    "editor.noteLink.previewUnavailable": "Note preview is unavailable",
+    "editor.noteLink.previewEmpty": "No preview available",
+    "editor.noteLink.openNote": "Open note",
     "editor.noteMention.header": "Notes",
     "editor.noteMention.loading": "Loading",
     "editor.noteMention.empty": "No matching notes",
@@ -1835,6 +1957,10 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "editor.threadCard.copyLatex": "Copy LaTeX",
     "editor.threadCard.model": "Model",
     "editor.threadCard.mode": "Mode",
+    "editor.threadCard.composer.planMode": "Plan mode",
+    "editor.threadCard.commandMode.plan": "Plan mode",
+    "editor.threadCard.commandMode.goal": "Goal mode",
+    "editor.threadCard.composer.longTask": "Long task",
     "editor.threadCard.piCodeMode": "Code",
     "editor.threadCard.piWritingMode": "Writing",
     "editor.threadCard.inputTokens": "Input",
@@ -1973,6 +2099,9 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "preferences.format.fontStatus.downloading": "Downloading",
     "preferences.format.fontStatus.needsDownload": "Download required",
     "multidimensionalTable.view.rename": "Rename",
+    "multidimensionalTable.referenceIdentityChanged": "The referenced table identity changed. The table at this path no longer matches the saved table.id; select a table again.",
+    "multidimensionalTable.removeReference": "Remove table reference",
+    "multidimensionalTable.deleteTableFile": "Delete table file",
     "multidimensionalTable.view.name": "View name",
     "multidimensionalTable.view.delete": "Delete",
     "multidimensionalTable.view.deleteConfirm": "Delete the view “{name}”?",
@@ -1983,6 +2112,16 @@ const enUS: Record<keyof typeof zhCN, string> = {
     "multidimensionalTable.view.kanbanMissingField": "The single-select field used to group this kanban was deleted. Choose another grouping field.",
     "multidimensionalTable.view.calendarMissingField": "The date field used by this calendar was deleted. Choose another calendar date field.",
     "multidimensionalTable.view.kanbanFieldTypeMismatch": "Kanban requires a single-select grouping field (“{field}”), but its current type is “{type}”. Change the property back to single select or choose another grouping field.",
+    "multidimensionalTable.kanbanDropReadOnly": "This kanban board is read-only; notes cannot be added",
+    "multidimensionalTable.kanbanDropUnavailable": "Cannot add notes to this group. Check the kanban grouping field.",
+    "multidimensionalTable.kanbanDropFailed": "Failed to add notes to the kanban board",
+    "multidimensionalTable.galleryDropReadOnly": "This gallery is read-only; notes cannot be added",
+    "multidimensionalTable.dropOverlayHint": "Release to add to the list",
+    "multidimensionalTable.galleryDropFailed": "Failed to add notes to the gallery",
+    "multidimensionalTable.galleryDropFiltered": "The dragged notes do not match the current gallery filter",
+    "multidimensionalTable.tableDropReadOnly": "This table is read-only; notes cannot be added",
+    "multidimensionalTable.tableDropFailed": "Failed to add notes to the table",
+    "multidimensionalTable.tableDropFiltered": "The dragged notes do not match the current table filter",
     "multidimensionalTable.view.calendarFieldTypeMismatch": "Calendar requires a date field (“{field}”), but its current type is “{type}”. Change the property back to Date or choose another calendar field.",
     "multidimensionalTable.viewMembership.add": "Add to Views",
     "multidimensionalTable.viewMembership.hide": "Hide from Views",
diff --git a/app/flowix-web/lib/i18n/messages.zh-CN.ts b/app/flowix-web/lib/i18n/messages.zh-CN.ts
index 098efa7f6..6906f2ad1 100644
--- a/app/flowix-web/lib/i18n/messages.zh-CN.ts
+++ b/app/flowix-web/lib/i18n/messages.zh-CN.ts
@@ -3,7 +3,7 @@ const zhCN = {
     "editor.attachment.uploadTooLarge": "附件内容超过 64 MiB，请使用原生文件选择导入。",
     "editor.attachment.uploadBusy": "正在处理其他附件，请稍后重试。",
     "editor.attachment.uploadOwnerRequired": "无法确定附件所属笔记，请重新打开笔记后重试。",
-    "editor.attachment.uploadFailed": "附件保存失败，请检查文件权限或剩余空间后重试。",
+    "editor.attachment.uploadFailed": "附件保存失败，请检查文件权限或剩余空间后重试",
     "editor.attachment.uploadUninserted": "附件已保存，但原插入位置已失效或编辑器已关闭。文件仍保留在笔记本的 attachments 目录中。",
     "language.zhCN": "简体中文",
     "language.enUS": "English",
@@ -14,7 +14,29 @@ const zhCN = {
     "preferences.title": "偏好设置",
     "preferences.groups.features": "功能",
     "preferences.groups.ai": "AI",
+    "preferences.plugins.title": "插件",
+    "preferences.plugins.description": "插件安装在 ~/.flowix/plugin/，安装后对全部笔记本可用。",
+    "preferences.plugins.install": "安装或升级插件",
+    "preferences.plugins.installConfirm": "安装或升级插件“{name}”吗？{capabilities}",
+    "preferences.plugins.capabilities": "\n\n宿主能力：{capabilities}",
+    "preferences.plugins.uninstallConfirm": "确定卸载插件“{name}”吗？",
+    "preferences.plugins.refresh": "刷新",
+    "preferences.plugins.builtIn": "内置",
+    "preferences.plugins.disabled": "已停用",
+    "preferences.plugins.integrityVerified": "完整性通过",
+    "preferences.plugins.integrityMissing": "未校验",
+    "preferences.plugins.integrityVerifiedHint": "安装包文件与插件声明的 SHA-256 完整性清单一致",
+    "preferences.plugins.integrityMissingHint": "插件未提供完整性清单",
+    "preferences.plugins.capabilityLabel": "能力：{capabilities}",
+    "preferences.plugins.enable": "启用插件",
+    "preferences.plugins.disable": "停用插件",
+    "preferences.plugins.uninstall": "卸载插件",
+    "preferences.plugins.invalidTitle": "加载失败",
+    "preferences.plugins.loading": "正在加载插件…",
+    "preferences.plugins.empty": "尚未安装插件",
+    "preferences.groups.development": "开发",
     "preferences.emptySettings": "暂无配置项",
+    "preferences.sectionLoadFailed": "此设置页面加载失败，你仍可切换到其他页面。",
     "preferences.error.pathAlreadyRegistered": "该文件夹已作为笔记本添加",
     "preferences.error.pathNotEmpty": "从云端恢复时请选择空文件夹",
     "preferences.error.pathMissing": "文件夹不存在",
@@ -26,6 +48,7 @@ const zhCN = {
     "preferences.error.indexWriteFailedDelete": "删除失败，索引写入失败",
     "preferences.error.deleteFailed": "删除失败",
     "preferences.tabs.general": "通用",
+    "preferences.tabs.environmentConfig": "环境配置",
     "preferences.tabs.fileDisplayRules": "访问空间 屏蔽显示",
     "preferences.tabs.format": "编辑器排版",
     "preferences.tabs.theme": "主题",
@@ -66,7 +89,7 @@ const zhCN = {
     "preferences.tabs.agent": "模型配置",
     "preferences.tabs.shortcuts": "快捷键",
     "preferences.tabs.cli": "CLI",
-    "preferences.tabs.mcp": "连接 · MCP · CLI",
+    "preferences.tabs.mcp": "连接",
     "preferences.tabs.connections": "集成",
     "preferences.tabs.cloudSync": "账号",
     "preferences.tabs.imageGeneration": "图片生成",
@@ -98,10 +121,34 @@ const zhCN = {
     "preferences.cloud.logout": "退出登录",
     "preferences.cloud.sessionExpired": "云端登录已失效，请重新登录。",
     "preferences.cloud.membership": "会员与存储",
+    "preferences.cloud.order.title": "订单记录",
+    "preferences.cloud.order.description": "查看账号下的产品内购订单；付款未生效时可向 Creem 查询并同步权益。",
+    "preferences.cloud.order.loading": "正在加载订单…",
+    "preferences.cloud.order.empty": "暂无内购订单。",
+    "preferences.cloud.order.check": "检查订单",
+    "preferences.cloud.order.checkTooltip": "权益尚未生效时，检查订单并同步权益",
+    "preferences.cloud.order.checking": "正在检查…",
+    "preferences.cloud.order.confirmed": "Creem 已确认付款，会员权益已同步。",
+    "preferences.cloud.order.notConfirmed": "Creem 尚未确认付款，请确认支付状态后再检查。",
+    "preferences.cloud.order.refreshFailed": "付款已确认，但账号状态刷新失败，请重试刷新会员状态。",
+    "preferences.cloud.order.processing": "订单正在核验或同步权益，请稍后再次检查。",
+    "preferences.cloud.order.syncFailed": "Creem 已确认付款，但权益同步失败，请稍后重试；持续失败时请联系客服。",
+    "preferences.cloud.order.needsReview": "Creem 已确认付款，但订单处理遇到需要人工核查的问题，请联系客服。",
+    "preferences.cloud.order.unavailable": "此订单缺少可核验的支付信息，请联系客服。",
+    "preferences.cloud.order.refunded": "此订单已退款，不会恢复会员权益。",
+    "preferences.cloud.order.unknownResult": "无法确定订单核验结果，请稍后重试；持续出现时请联系客服。",
+    "preferences.cloud.order.rateLimited": "订单检查过于频繁，请一分钟后重试。",
+    "preferences.cloud.order.pendingCheckout": "存在进行中订单，请勿重复购买。",
+    "preferences.cloud.order.checkUnavailable": "订单检查暂时不可用，请稍后重试。",
+    "preferences.cloud.order.status.pending": "待确认",
+    "preferences.cloud.order.status.paid": "已支付",
+    "preferences.cloud.order.status.expired": "已过期",
+    "preferences.cloud.order.status.refunded": "已退款",
+    "preferences.cloud.order.status.unknown": "处理中",
     "preferences.cloud.active": "有效",
     "preferences.cloud.inactive": "未开通",
-    "preferences.cloud.usage": "已用空间",
-    "preferences.cloud.expires": "到期时间",
+    "preferences.cloud.usage": "可用",
+    "preferences.cloud.expires": "到期日期",
     "preferences.cloud.syncNow": "立即同步",
     "preferences.cloud.syncComplete": "同步完成",
     "preferences.cloud.recoveryTitle": "版本历史与冲突",
@@ -164,6 +211,8 @@ const zhCN = {
     "notebook.template.loadFailed": "加载笔记本模板失败",
     "notebook.template.empty": "暂无可用的笔记本模板",
     "notebook.setup.applyingTemplate": "正在写入笔记本模板内容…",
+    "notebook.setup.preparingTemplate": "正在准备模板文件…",
+    "notebook.setup.hide": "隐藏",
     "notebook.setup.indexing": "正在建立笔记本索引…",
     "notebook.setup.failed": "笔记本初始化失败",
     "notebook.setup.partial": "模板已部分写入",
@@ -185,11 +234,27 @@ const zhCN = {
     "preferences.general.versionCopied": "版本信息已复制",
     "preferences.general.versionCopyFailed": "复制版本信息失败",
     "preferences.general.loading": "加载中",
-    "preferences.general.runtimeLogs.title": "运行日志",
-    "preferences.general.runtimeLogs.description": "本地日志文件夹",
-    "preferences.general.runtimeLogs.open": "打开",
-    "preferences.general.runtimeLogs.openFolder": "打开日志文件夹",
-    "preferences.general.runtimeLogs.openFailed": "打开日志文件夹失败",
+    "preferences.environmentConfig.title": "环境配置",
+    "preferences.environmentConfig.cloudEnvironment.title": "Cloud 环境",
+    "preferences.environmentConfig.cloudEnvironment.description": "首次启动默认使用 Prod；切换后应用会重启，已保存的选择优先于启动参数默认值。",
+    "preferences.environmentConfig.cloudEnvironment.staging": "Staging Cloud",
+    "preferences.environmentConfig.cloudEnvironment.prod": "Prod",
+    "preferences.environmentConfig.cloudEnvironment.failed": "切换 Cloud 环境失败",
+    "preferences.environmentConfig.cloudEnvironment.restartFailed": "环境已保存，但应用未能重启；请手动重启以应用切换",
+    "preferences.environmentConfig.cloudEnvironment.prodConfirm.title": "切换到正式 Cloud？",
+    "preferences.environmentConfig.cloudEnvironment.prodConfirm.description": "切换后，Cloud 登录、同步和支付请求会发送到正式环境。付费操作可能产生真实交易。",
+    "preferences.environmentConfig.cloudEnvironment.prodConfirm.confirm": "切换到 Prod",
+    "preferences.environmentConfig.versionInitialization.title": "当前版本初始化已完成",
+    "preferences.environmentConfig.versionInitialization.description": "关闭后，下次启动会重新执行当前版本初始化。",
+    "preferences.environmentConfig.versionInitialization.rerunNextLaunch": "下次启动将重新初始化当前版本",
+    "preferences.environmentConfig.versionInitialization.markedComplete": "当前版本已标记为初始化完成",
+    "preferences.environmentConfig.versionInitialization.loadFailed": "读取版本初始化状态失败",
+    "preferences.environmentConfig.versionInitialization.saveFailed": "保存版本初始化状态失败",
+    "preferences.environmentConfig.runtimeLogs.title": "运行日志",
+    "preferences.environmentConfig.runtimeLogs.description": "本地日志文件夹",
+    "preferences.environmentConfig.runtimeLogs.open": "打开",
+    "preferences.environmentConfig.runtimeLogs.openFolder": "打开日志文件夹",
+    "preferences.environmentConfig.runtimeLogs.openFailed": "打开日志文件夹失败",
     "preferences.general.productUpdates.title": "产品更新",
     "preferences.general.productUpdates.check": "检查更新",
     "preferences.general.productUpdates.checking": "检查中...",
@@ -199,14 +264,10 @@ const zhCN = {
     "productUpdates.version": "版本 {version}",
     "productUpdates.openFailed": "打开更新链接失败",
     "appUpdates.available": "发现新版本",
-    "appUpdates.description": "已准备好安装。请先结束正在执行的工具任务。安装会断开 Flowix MCP 连接并关闭正在运行的 Flowix CLI；应用安装完成后会自动重启。如 MCP 工具不可用，请在客户端重新连接。",
+    "appUpdates.statusBarVersion": "新版本 {version}",
     "appUpdates.install": "安装更新",
     "appUpdates.downloading": "下载中…",
     "appUpdates.installing": "正在安装…",
-    "appUpdates.statusDownloading": "下载中",
-    "appUpdates.statusDownloadingProgress": "下载中 {percent}%",
-    "appUpdates.statusInstalling": "安装中",
-    "appUpdates.progress": "下载进度：{percent}%",
     "appUpdates.installFailed": "安装更新失败",
     "appUpdates.installSucceeded": "应用已更新并重启",
     "appUpdates.previousInstallFailed": "上次更新失败",
@@ -354,10 +415,11 @@ const zhCN = {
     "preferences.agent.testError.other": "测试失败",
     "preferences.agents.title": "AI Agent 配置",
     "preferences.agents.subtitle":
-      "支持配置以下 Agent 类型，在文档输入 / 激活使用",
+      "启用已配置的 Agent 后，可在斜线菜单和新建对话中使用",
+    "preferences.agents.enableAgent": "启用 {name}",
+    "preferences.agents.cacheWriteFailed": "Agent 偏好仍可在当前窗口使用，但无法保存到本地缓存；重启应用后这些偏好可能丢失。",
     "preferences.dsh.title": "DeepSeek Harness（Beta版）",
     "preferences.pi.title": "模型",
-    "preferences.pi.description": "管理 Pi 使用的服务商和模型列表，可在对话输入框下方切换。",
     "preferences.pi.mcp.title": "MCP 服务器",
     "preferences.pi.mcp.description": "管理 Pi 全局 MCP 配置；保存后，Pi 下次启动时读取。使用 ${变量名} 引用环境变量，避免把密钥直接写入配置。",
     "preferences.pi.mcp.empty": "尚未配置 MCP 服务器",
@@ -421,6 +483,19 @@ const zhCN = {
     "preferences.pi.deleted": "Pi 服务商已删除",
     "preferences.pi.oldProviderCleanupFailed": "新服务商已保存，但旧服务商配置清理失败",
     "preferences.pi.validation": "请填写服务商信息和至少一个模型 ID",
+    "preferences.pi.cloudTitle": "会员模型",
+    "preferences.pi.creditMultiplier": "点数消耗倍率：{value}×",
+    "preferences.pi.cloudCreditsBalance": "点数余额",
+    "preferences.pi.cloudCreditsUnit": "点",
+    "preferences.pi.cloudCreditsRefresh": "刷新余额",
+    "preferences.pi.cloudCreditsLoading": "读取中…",
+    "preferences.pi.cloudCreditsUnavailable": "暂不可用",
+    "preferences.pi.cloudConnect": "连接 Cloud 模型",
+    "preferences.pi.cloudConnected": "Flowix Cloud 模型已添加到 Pi",
+    "preferences.pi.byokTitle": "我的模型",
+    "preferences.pi.defaultModelTag": "默认 · {name}",
+    "preferences.pi.byokEmpty": "尚未添加 BYOK 服务商。Cloud 模型和 BYOK 可以同时使用。",
+    "preferences.pi.byokAdd": "添加 BYOK 服务商",
     "preferences.dsh.description": "办公、Coding的高性能AI Agent",
     "preferences.dsh.tabs.models": "模型",
     "preferences.dsh.tabs.general": "通用",
@@ -460,76 +535,24 @@ const zhCN = {
     "preferences.dsh.plugins.skills": "加载和使用可复用的技能指令。",
     "preferences.dsh.plugins.subagents": "创建子 Agent 协作处理任务。",
     "preferences.dsh.plugins.workflows": "组合多步任务并运行工作流。",
-    "preferences.dsh.runtime.title": "DeepSeek Harness Runtime",
-    "preferences.dsh.runtime.officialProfile": "Flowix 使用独立的无 UI DSH Runtime，安装在 Flowix 数据目录：",
-    "preferences.dsh.runtime.officialHint": "Runtime 与 Flowix 客户端独立更新；下载包会校验 latest.json 中声明的 SHA-256。",
-    "preferences.dsh.runtime.officialCommands": "DSH 会在首次使用 DSH Agent 时由 Flowix 自动启动。",
-    "preferences.dsh.runtime.install": "安装 DSH Runtime",
-    "preferences.dsh.runtime.installing": "安装中…",
-    "preferences.dsh.runtime.updating": "更新中…",
-    "preferences.dsh.runtime.update": "更新 DSH Runtime",
-    "preferences.dsh.runtime.check": "检查更新",
-    "preferences.dsh.runtime.checking": "正在检查…",
-    "preferences.dsh.runtime.updateSuccess": "DSH Runtime 更新成功",
-    "preferences.dsh.runtime.upToDate": "DSH Runtime 已是最新版本",
-    "preferences.dsh.runtime.updateFailed": "DSH Runtime 检查或更新失败",
-    "agent.dsh.updateAvailable": "检查到新版本{version}，点击更新",
-    "agent.dsh.updatePreparing": "正在准备更新…",
-    "agent.dsh.updateDownloading": "正在下载更新 {percent}%",
-    "agent.dsh.updateInstalling": "正在安装更新…",
-    "agent.dsh.updateComplete": "DSH Runtime 更新完成",
-    "agent.dsh.updateFailed": "更新失败，点击重试",
     "agent.pi.unavailable": "未找到可用 PI 服务",
-    "preferences.dsh.runtime.cancel": "取消",
-    "preferences.dsh.runtime.downloadProgress": "下载进度",
-    "preferences.dsh.runtime.downloading": "dsh 下载中",
-    "preferences.dsh.runtime.resumed": "已从上次中断位置继续下载",
-    "preferences.dsh.runtime.installed": "已安装",
-    "preferences.dsh.runtime.detected": "已安装 DSH Runtime",
-    "preferences.dsh.runtime.packageSize": "大小",
-    "preferences.dsh.runtime.notDetected": "尚未安装 DSH Runtime。",
-    "preferences.dsh.runtime.uninstall": "卸载 DeepSeek Harness",
     "preferences.dsh.runtime.version": "版本",
-    "preferences.dsh.runtime.uninstallButton": "卸载",
-    "preferences.dsh.runtime.uninstallHint": "仅移除 dsh 安装包，已配置模型、会话数据不受影响。",
-    "preferences.dsh.runtime.uninstalling": "卸载中…",
-    "preferences.dsh.runtime.uninstallSuccess": "DeepSeek Harness 卸载成功",
-    "preferences.dsh.runtime.uninstallFailed": "DeepSeek Harness 卸载失败",
-    "preferences.dsh.runtime.uninstallConfirm": "确定卸载 DeepSeek Harness Runtime 吗？正在运行的 DeepSeek Harness 任务会被拒绝，模型配置与会话历史（~/.dsh）会保留。",
-    "preferences.dsh.install.prompt": "是否下载并启动 DeepSeek Harness？它是 Flowix 的可选本地 Agent 运行时。",
-    "preferences.dsh.install.complete": "DeepSeek Harness 已安装，首次使用 DSH Agent 时会自动启动。",
-    "preferences.dsh.install.failed": "DeepSeek Harness 安装失败",
     "preferences.dsh.setup.loading": "正在检查 DeepSeek Harness 状态…",
     "preferences.dsh.setup.title": "Deepseek Harness",
-    "preferences.dsh.setup.promptTitle": "Deepseek Harness 下载",
-    "preferences.dsh.setup.description": "DeepSeek Harness（dsh）是 DeepSeek 开源的 AI Agent 运行框架：把模型、工具、技能、会话、沙箱、存储、调度与 UI 全部做成可自由替换、组合和扩展的插件。",
-    "preferences.dsh.setup.promptDescription": "一切皆插件，可按需组装适用工具、工作流。适用于办公、编程场景。 安装后，可在偏好设置中，独立卸载。",
-    "preferences.dsh.setup.carousel": "DeepSeek Harness 安装引导",
-    "preferences.dsh.setup.mcp.slide": "Flowix MCP",
-    "preferences.dsh.setup.mcp.title": "Flowix MCP",
-    "preferences.dsh.setup.mcp.description": "打开其他 AI 客户端，复制下面的安装说明并发送，即可接入 Flowix MCP。安装过程中，AI 客户端可能需要文件访问权限。",
-    "preferences.dsh.setup.mcp.copyContent": "请为当前 AI 客户端安装 Flowix MCP。\n\n连接方式：stdio\ncommand：{command}\nargs：[\"mcp\"]\n\n请将它写入当前客户端的 MCP 配置，并在修改前告诉我配置文件位置和具体改动。不要修改其他 MCP 配置。",
-    "preferences.dsh.setup.intro.slide": "本地 Agent 检查",
-    "preferences.dsh.setup.download.slide": "DeepSeek Harness 下载",
-    "preferences.dsh.setup.intro.checking": "正在检查本地 AI Agent…",
-    "preferences.dsh.setup.intro.detected": "已检查到 {agent}",
-    "preferences.dsh.setup.intro.none": "未找到本地可用 AI Agent",
-    "preferences.dsh.setup.intro.description": "可在笔记内通过 / 命令，插入会话使用 AI Agent。文档的多个会话，共享文档内容。",
-    "preferences.dsh.setup.intro.noAgentDescription": "Flowix 可直接调用本地已安装的 Codex / Claude Code / OpenCode。",
-    "preferences.dsh.setup.next": "下一步",
-    "preferences.dsh.setup.previous": "上一步",
-    "preferences.dsh.setup.install": "安装 DeepSeek Harness",
-    "preferences.dsh.setup.installing": "安装中…",
-    "preferences.dsh.setup.downloading": "下载中…",
-    "preferences.dsh.setup.cancel": "取消下载",
-    "preferences.dsh.setup.installSuccess": "DSH Runtime 下载并安装成功",
-    "preferences.dsh.setup.installFailed": "DSH Runtime 下载或安装失败",
-    "preferences.dsh.setup.cancelled": "DSH Runtime 下载已取消",
     "preferences.dsh.setup.retry": "重试",
-    "preferences.dsh.setup.error": "安装失败",
-    "preferences.dsh.setup.downloadProgress": "正在下载 DSH Runtime",
-    "preferences.dsh.setup.resumed": "已从上次中断位置继续下载",
-    "preferences.dsh.setup.security": "下载包会校验 latest.json 中声明的 SHA-256。安装完成后，这里会显示 DSH 的模型、通用、运行时和预设设置。",
+    "preferences.dsh.appServer.missingDescription": "DSH 已安装。安装 Flowix App Server 插件后，即可在 Flowix 中使用 DSH Agent。",
+    "preferences.dsh.appServer.localDetected": "本地检查已安装 DSH {version}",
+    "preferences.dsh.appServer.updateDescription": "Flowix App Server 插件版本已过期。更新 profile 后可继续使用 DSH Agent。",
+    "preferences.dsh.appServer.runtimeMissingDescription": "未找到本地 DSH，或在下方选择本地 DSH 路径添加",
+    "preferences.dsh.appServer.localRuntime": "检测到本地 DSH：{path}",
+    "preferences.dsh.appServer.installationPath": "DSH 安装路径",
+    "preferences.dsh.appServer.managedRuntime": "检测到 Flowix DSH Runtime：{version}",
+    "preferences.dsh.appServer.openOfficialInstall": "打开 DSH 官方安装页",
+    "preferences.dsh.appServer.install": "为 DSH 安装 Flowix 插件",
+    "preferences.dsh.appServer.installNote": "用于通信/对话管理",
+    "preferences.dsh.appServer.update": "更新 DSH App Server 插件",
+    "preferences.dsh.appServer.installing": "正在安装插件…",
+    "preferences.dsh.appServer.installSuccess": "DSH App Server 插件已安装并通过连接检查",
     "preferences.dsh.presets.title": "Agent 预设",
     "preferences.dsh.presets.hint": "预设可在 DeepSeek Harness 会话的模式设置中按会话选择。",
     "preferences.agents.codex.downloadPrompt": "下载 Codex CLI?",
@@ -581,10 +604,6 @@ const zhCN = {
     "agent.types.claude.desc": "架构分析、复杂重构、方案整理",
     "agent.types.hermes.name": "Hermes",
     "agent.types.hermes.desc": "使用本地安装的 Hermes",
-    "agent.types.gemini.name": "Gemini CLI",
-    "agent.types.gemini.desc": "使用本地安装的 Gemini CLI",
-    "agent.types.openclaw.name": "OpenClaw",
-    "agent.types.openclaw.desc": "使用本地安装的 OpenClaw",
     "agent.types.opencode.name": "OpenCode",
     "agent.types.opencode.desc": "轻量快速、开源、模型自由",
     "agent.types.pi.name": "Pi",
@@ -604,7 +623,7 @@ const zhCN = {
     "preferences.shortcuts.resetOneAria": "重置 {title} 为默认",
     "preferences.shortcuts.group.editor": "编辑",
     "preferences.shortcuts.action.editor.selectAll.title": "全选",
-    "preferences.shortcuts.action.editor.selectAll.description": "全选当前编辑器中的内容。",
+    "preferences.shortcuts.action.editor.selectAll.description": "全选当前编辑器中的内容",
     "preferences.shortcuts.group.navigation": "导航",
     "preferences.shortcuts.group.view": "视图",
     "preferences.shortcuts.group.system": "系统",
@@ -620,75 +639,75 @@ const zhCN = {
       "Esc 取消 · Enter 确认 · Backspace 重录",
     "preferences.shortcuts.action.editor.find.title": "编辑器内查找",
     "preferences.shortcuts.action.editor.find.description":
-      "打开 / 关闭当前编辑器的搜索替换面板。",
+      "打开 / 关闭当前编辑器的搜索替换面板",
     "preferences.shortcuts.action.editor.undo.title": "撤销",
     "preferences.shortcuts.action.editor.undo.description":
-      "撤销上一步编辑操作。",
+      "撤销上一步编辑操作",
     "preferences.shortcuts.action.editor.redo.title": "重做",
     "preferences.shortcuts.action.editor.redo.description":
-      "重做上一步被撤销的操作。",
+      "重做上一步被撤销的操作",
     "preferences.shortcuts.action.editor.setHeading1.title": "标题 1",
     "preferences.shortcuts.action.editor.setHeading1.description":
-      "将当前块元素设置为 H1。",
+      "将当前块元素设置为 H1",
     "preferences.shortcuts.action.editor.setHeading2.title": "标题 2",
     "preferences.shortcuts.action.editor.setHeading2.description":
-      "将当前块元素设置为 H2。",
+      "将当前块元素设置为 H2",
     "preferences.shortcuts.action.editor.setHeading3.title": "标题 3",
     "preferences.shortcuts.action.editor.setHeading3.description":
-      "将当前块元素设置为 H3。",
+      "将当前块元素设置为 H3",
     "preferences.shortcuts.action.editor.setHeading4.title": "标题 4",
     "preferences.shortcuts.action.editor.setHeading4.description":
-      "将当前块元素设置为 H4。",
+      "将当前块元素设置为 H4",
     "preferences.shortcuts.action.editor.setParagraph.title": "正文",
     "preferences.shortcuts.action.editor.setParagraph.description":
-      "将当前块元素转换为正文。",
+      "将当前块元素转换为正文",
     "preferences.shortcuts.action.editor.toggleBulletList.title": "无序列表",
     "preferences.shortcuts.action.editor.toggleBulletList.description":
-      "将当前块元素切换为无序列表。",
+      "将当前块元素切换为无序列表",
     "preferences.shortcuts.action.editor.toggleOrderedList.title": "有序列表",
     "preferences.shortcuts.action.editor.toggleOrderedList.description":
-      "将当前块元素切换为有序列表。",
+      "将当前块元素切换为有序列表",
     "preferences.shortcuts.action.editor.toggleTaskList.title": "待办列表",
     "preferences.shortcuts.action.editor.toggleTaskList.description":
-      "将当前块元素切换为待办列表。",
+      "将当前块元素切换为待办列表",
     "preferences.shortcuts.action.palette.search.title": "切换命令面板",
     "preferences.shortcuts.action.palette.search.description":
-      "打开或关闭全局搜索 / 命令面板。",
+      "打开或关闭全局搜索 / 命令面板",
     "preferences.shortcuts.action.menu.open.title": "打开偏好设置",
-    "preferences.shortcuts.action.menu.open.description": "打开偏好设置窗口。",
+    "preferences.shortcuts.action.menu.open.description": "打开偏好设置窗口",
     "preferences.shortcuts.action.history.back.title": "后退",
     "preferences.shortcuts.action.history.back.description":
-      "返回上一个阅读的文档。",
+      "返回上一个阅读的文档",
     "preferences.shortcuts.action.history.forward.title": "前进",
     "preferences.shortcuts.action.history.forward.description":
-      "前进到下一个阅读的文档。",
+      "前进到下一个阅读的文档",
     "preferences.shortcuts.action.memo.create.title": "新建 Memo",
     "preferences.shortcuts.action.memo.create.description":
-      "在当前选中的笔记本下创建一条新 Memo。",
+      "在当前选中的笔记本下创建一条新 Memo",
     "preferences.shortcuts.action.notebook.create.title": "新建笔记本",
     "preferences.shortcuts.action.notebook.create.description":
-      "打开新建笔记本弹窗。",
+      "打开新建笔记本弹窗",
     "preferences.shortcuts.action.notebook.switcher.toggle.title":
       "切换笔记本面板",
     "preferences.shortcuts.action.notebook.switcher.toggle.description":
-      "打开或关闭底部状态栏的笔记本下拉面板。",
+      "打开或关闭底部状态栏的笔记本下拉面板",
     "preferences.shortcuts.action.theme.toggle.title": "切换主题",
     "preferences.shortcuts.action.theme.toggle.description":
-      "在 跟随系统 / 浅色 / 深色 / 岩灰 / 余烬 之间循环切换。",
+      "在 跟随系统 / 浅色 / 深色 / 岩灰 / 余烬 之间循环切换",
     "preferences.shortcuts.action.panel.memoList.toggle.title":
       "显示/隐藏 memo 列表",
     "preferences.shortcuts.action.panel.memoList.toggle.description":
-      "切换左栏 memo 列表的显示与隐藏。",
+      "切换左栏 memo 列表的显示与隐藏",
     "preferences.shortcuts.action.panel.noteNavigation.toggle.title":
       "显示/隐藏笔记导航侧边栏",
     "preferences.shortcuts.action.panel.noteNavigation.toggle.description":
-      "切换最左栏笔记导航 (标签 / 笔记本) 的显示与隐藏。",
+      "切换最左栏笔记导航 (标签 / 笔记本) 的显示与隐藏",
     "preferences.shortcuts.action.dialog.cancel.title": "关闭弹窗",
     "preferences.shortcuts.action.dialog.cancel.description":
-      "关闭当前打开的模态弹窗。",
+      "关闭当前打开的模态弹窗",
     "preferences.shortcuts.action.dialog.confirm.title": "确认弹窗",
     "preferences.shortcuts.action.dialog.confirm.description":
-      "确认当前模态弹窗的默认动作。",
+      "确认当前模态弹窗的默认动作",
 
     "preferences.connections.title": "集成",
     "preferences.connections.connect": "暂未开放",
@@ -724,6 +743,7 @@ const zhCN = {
       "跨笔记全文搜索，可限制笔记本和结果数量。",
     "preferences.cli.commands.completion": "输出 shell 补全脚本。",
     "preferences.cli.commands.pluginCreate": "从标准输入创建插件产物和对应的 Flowix 文档。",
+    "plugin.workbench.generating": "正在生成插件产物…",
 
     "preferences.mcp.title": "MCP Server",
     "preferences.mcp.generic": "标准 MCP 配置",
@@ -749,6 +769,10 @@ const zhCN = {
     "window.minimize": "最小化",
     "window.maximize": "最大化",
     "window.close": "关闭",
+    "window.closeNativeUnavailable": "原生关闭保护暂不可用。窗口响应时按钮仍可正常关闭；若 Flowix 无响应，请在任务管理器中结束进程。",
+    "window.closeNativeRestored": "原生关闭保护已恢复。",
+    "window.closeRequestFailed": "无法确认关闭请求已送达。若 Flowix 仍打开，请再次点击关闭；若应用无响应，请在任务管理器中结束进程。",
+    "notebook.delete.saveCurrentDocumentFailed": "当前文档未能保存，请重试保存后再删除笔记本。",
     "tabWindow.all": "全部",
     "tabWindow.showAll": "全部",
     "tabWindow.openContent": "浏览器列打开的内容",
@@ -762,12 +786,12 @@ const zhCN = {
     "tabWindow.createNote.failed": "新建笔记失败",
     "tabWindow.context.newConversation": "新建对话",
     "tabWindow.createConversation.failed": "新建对话失败",
-    "tabWindow.context.moveWebUnavailable": "网页暂时只能在辅助工作区浏览。",
-    "tabWindow.context.moveFolderUnavailable": "请先在目录中选择文件，再移到主工作区。",
+    "tabWindow.context.moveFolderUnavailable": "请先在目录中选择文件，再在主工作区打开。",
     "tabWindow.switchFailed": "未能切换标签，当前内容已保留。请确认保存成功后重试。",
     "tabWindow.confirmDiscardChanges": "当前文档无法保存。是否放弃未保存的本地内容并关闭？",
     "tabWindow.context.openInWorkColumn": "在左栏打开",
     "workColumn.context.openInBrowserColumn": "在右栏打开",
+    "workColumn.context.alsoOpenInBrowserColumn": "同时在右栏打开",
     "workspace.alreadyOpen": "文档已打开",
     "error.title": "出错了",
     "error.unexpected": "发生了意外错误",
@@ -784,7 +808,10 @@ const zhCN = {
     "status.agent.loadingMoreConversations": "加载中…",
     "status.agent.noConversations": "暂无会话",
     "status.agent.loadConversationsFailed": "会话加载失败",
-    "status.agent.loadHistoryFailed": "历史记录加载失败",
+    "status.agent.loadHistoryFailed": "对话读取失败",
+    "status.agent.historySessionNotFound": "找不到这段对话，可能已被删除。",
+    "status.agent.historyRefreshFailed": "刷新失败，当前内容可能不是最新。",
+    "status.agent.newConversation": "新建对话",
     "status.agent.openRun": "打开所在文档",
     "status.agent.openConversation": "打开会话",
     "status.agent.originUnavailable": "无法定位文档",
@@ -795,6 +822,10 @@ const zhCN = {
     "status.agent.deleteSuccess": "删除会话成功",
     "document.agent.viewInNote": "查看笔记",
     "document.agent.moreActions": "更多操作",
+    "agent.chat.messageFontSize": "字号",
+    "agent.chat.messageFontSize.small": "小",
+    "agent.chat.messageFontSize.medium": "中",
+    "agent.chat.messageFontSize.large": "大",
     "document.agent.archiveConversation": "归档会话",
     "document.agent.deleteConversation": "删除会话",
     "document.agent.deleteConfirm": "删除后该会话在 Agent 侧的历史记录将被彻底删除，且无法恢复。确定删除吗？",
@@ -804,6 +835,8 @@ const zhCN = {
     "status.notebook": "笔记本",
     "status.switchNotebook": "切换笔记本",
     "status.notebookList": "笔记本列表",
+    "status.searchNotebookPlaceholder": "搜索笔记本",
+    "status.noMatchingNotebooks": "没有匹配的笔记本",
     "status.previousNotebookPage": "上一页笔记本",
     "status.nextNotebookPage": "下一页笔记本",
     "status.notebookMemoCount": "{count} 篇",
@@ -860,6 +893,9 @@ const zhCN = {
     "agent.model.menu": "模型",
     "agent.model.title": "模型",
     "agent.speed.title": "速度",
+    "agent.pi.modelTab.member": "会员",
+    "agent.pi.modelTab.mine": "我的",
+    "agent.pi.modelTab.mineEmpty": "暂无已配置的个人模型",
     "agent.model.noneFound": "未找到模型",
     "agent.model.configure": "开始配置模型",
     "agent.model.loadFailed": "模型加载失败",
@@ -902,8 +938,8 @@ const zhCN = {
     "agent.chat.historyLabel": "{role} 历史",
     "agent.chat.conversationsLabel": "会话",
     "agent.chat.emptyHistory": "暂无历史会话",
-    "agent.chat.newThread": "新建会话",
-    "agent.chat.newConversation": "新会话",
+    "agent.chat.newThread": "新建对话",
+    "agent.chat.newConversation": "新建对话",
     "agent.chat.conversation.more": "更多操作",
     "agent.chat.conversation.favorites": "收藏",
     "agent.chat.conversation.favorite": "收藏",
@@ -921,7 +957,12 @@ const zhCN = {
     "agent.deepseekHarness.reconnectFailed": "DeepSeek Harness 重连失败",
     "agent.deepseekHarness.failureReason": "失败原因：{reason}",
     "agent.error.diagnostic.requestId": "请求 ID：{value}",
+    "agent.error.diagnostic.reference": "联系客服时请提供排查编号：{value}",
     "agent.error.diagnostic.retryAfter": "建议等待：{value}",
+    "agent.error.membershipRequired": "此模型需要有效的 Flowix Cloud 会员。请到「设置 > 会员与存储」确认当前账号的会员状态；如果已是会员，请重新登录后重试。",
+    "agent.error.insufficientCredits": "Flowix 点数不足以预留本次请求额度。请减少输出长度，或联系管理员补充点数后重试。",
+    "agent.error.cloudModelUnavailable": "此 Cloud 模型当前不可用。请到「设置 > Pi」刷新 Cloud 凭据目录，再选择一个可用模型。",
+    "agent.error.cloudPricingUnavailable": "Flowix Cloud 当前没有启用点数计价的模型，请联系管理员处理。",
     "agent.error.guidance.authentication": "请检查该 Agent 的登录状态或 API 密钥配置。",
     "agent.error.guidance.rate_limited": "请求受到限流，请等待配额恢复后重试。",
     "agent.error.guidance.network": "网络连接失败，请检查网络后重试。",
@@ -935,8 +976,6 @@ const zhCN = {
     "agent.opencodeSession.title": "OpenCode 会话",
     "agent.piSession.title": "Pi 会话",
     "agent.hermesSession.title": "Hermes 会话",
-    "agent.geminiSession.title": "Gemini CLI 会话",
-    "agent.openclawSession.title": "OpenClaw 会话",
     "agent.time.justNow": "刚刚",
     "agent.time.seconds": "{s}s",
     "agent.time.minutes": "{m}m",
@@ -1015,7 +1054,7 @@ const zhCN = {
     "agent.tools.completedSteps": "已完成 {count} 个步骤",
     "agent.tools.processing": "运行中",
     "agent.tools.runningSteps": "运行中，已完成 {count} 步",
-    "agent.tools.failedSteps": "{count} 个步骤未完成",
+    "agent.tools.finishedSteps": "已完成 {count} 个步骤",
     "agent.tools.noInput": "无输入信息",
     "agent.tools.input": "输入",
     "agent.tools.output": "输出",
@@ -1099,13 +1138,38 @@ const zhCN = {
     "memo.list.notebookMenu.appearanceTheme": "外观主题",
     "memo.list.notebookMenu.preferences": "偏好",
     "memo.list.notebookMenu.about": "关于",
+    "memo.list.notebookMenu.pin": "置顶笔记本",
+    "memo.list.notebookMenu.unpin": "取消置顶",
+    "memo.list.notebookMenu.pinFailed": "更新置顶状态失败",
     "memo.list.notebookMenu.officialWebsite": "官网",
     "memo.list.notebookMenu.community": "社区",
+    "memo.list.notebookMenu.feedback": "反馈",
+    "memo.list.notebookMenu.feedback.title": "提交反馈",
+    "memo.list.notebookMenu.feedback.description": "你的建议或使用中遇到的问题",
+    "memo.list.notebookMenu.feedback.type": "类型",
+    "memo.list.notebookMenu.feedback.required": "必填",
+    "memo.list.notebookMenu.feedback.suggestion": "产品建议",
+    "memo.list.notebookMenu.feedback.issue": "使用问题",
+    "memo.list.notebookMenu.feedback.content": "内容",
+    "memo.list.notebookMenu.feedback.placeholder": "请描述你的建议或遇到的问题",
+    "memo.list.notebookMenu.feedback.attachments": "附件",
+    "memo.list.notebookMenu.feedback.addImage": "添加图片",
+    "memo.list.notebookMenu.feedback.removeImage": "移除图片",
+    "memo.list.notebookMenu.feedback.imageHint": "上传 或 粘贴图片，3 张以内",
+    "memo.list.notebookMenu.feedback.imageLimit": "最多添加 3 张图片，格式限 PNG、JPG、WebP、GIF，且每张不超过 5 MB。",
+    "memo.list.notebookMenu.feedback.cancel": "取消",
+    "memo.list.notebookMenu.feedback.submit": "提交",
+    "memo.list.notebookMenu.feedback.submitting": "提交中…",
+    "memo.list.notebookMenu.feedback.submitSucceeded": "提交成功",
+    "memo.list.notebookMenu.feedback.submitFailed": "提交失败，请稍后重试",
     "memo.list.preferences": "偏好设置",
     "memo.list.preferencesTooltip": "偏好设置",
     "memo.list.emptyNotFound": "未找到笔记",
+    "memo.list.emptyNoNotebook": "还没有笔记本",
+    "memo.list.createNotebook": "新建笔记本",
     "memo.list.loadingNotebook": "加载中…",
     "memo.list.loadingLibrary": "正在解析文档库",
+    "memo.list.loadingMore": "正在加载更多笔记…",
     "memo.list.loadFailed": "加载笔记列表失败",
     "memo.tag.expand": "展开标签",
     "memo.tag.collapse": "折叠标签",
@@ -1126,6 +1190,7 @@ const zhCN = {
     "memo.tag.createdToast": "已创建标签 #{{path}}",
     "memo.tag.rename": "重命名",
     "memo.tag.pin": "置顶",
+    "memo.tag.unpin": "取消置顶",
     "memo.tag.batchManage": "批量管理",
     "memo.tag.batchDone": "完成",
     "memo.tag.batchDelete": "删除标签 #{{path}}",
@@ -1200,13 +1265,25 @@ const zhCN = {
     "memo.list.searchTooltip": "全文搜索",
     "memo.list.newMemoTooltip": "新建笔记",
     "memo.create.chooseType": "新建",
-    "memo.create.documents": "新建文档",
+    "memo.create.documents": "新建笔记",
     "memo.create.conversations": "新建对话",
     "memo.create.templateFailed": "从模板创建文档失败",
     "memo.create.note": "笔记",
     "memo.create.table": "多维表格",
     "memo.create.more": "新建…",
+    "memo.create.newView": "新建视图",
     "memo.fileTree.import": "导入",
+    "memo.fileTree.importFiles": "导入文件…",
+    "memo.fileTree.importFolder": "导入文件夹…",
+    "memo.fileTree.importFolderSuccess": "文件夹导入完成",
+    "memo.fileTree.importFolderInProgress": "正在导入文件夹…",
+    "memo.fileTree.importFolderFailed": "文件夹导入失败",
+    "memo.fileTree.importFolderCleanupFailed": "导入失败，部分文件可能仍留在目标位置，请检查后清理",
+    "memo.fileTree.importFolderExists": "目标位置已存在同名文件夹，请先重命名或选择其他位置",
+    "memo.fileTree.importFolderTooManyFiles": "文件夹包含超过 2,000 个文件，请分批导入",
+    "memo.fileTree.importFolderTooManyEntries": "文件夹树包含超过 5,000 个文件和文件夹，请缩小导入范围",
+    "memo.fileTree.importFolderTooDeep": "文件夹嵌套超过 32 层，请缩小导入范围",
+    "memo.fileTree.importFolderTooLarge": "文件夹总大小超过 5 GiB，请分批导入",
     "memo.create.tableDialogTitle": "新建表格",
     "memo.create.galleryDialogTitle": "新建画廊",
     "memo.create.kanbanDialogTitle": "新建看板",
@@ -1255,6 +1332,11 @@ const zhCN = {
     "mediaLibrary.videos": "视频",
     "mediaLibrary.itemCount": "{count}{more} 项",
     "mediaLibrary.opening": "正在打开媒体库…",
+    "mediaLibrary.refreshFailed": "媒体库刷新失败",
+    "mediaLibrary.maintenanceQueued": "正在等待媒体索引维护",
+    "mediaLibrary.maintenanceRunning": "正在维护媒体索引…",
+    "mediaLibrary.maintenanceFailed": "媒体索引维护失败",
+    "mediaLibrary.maintenanceRetryFailed": "无法重试媒体索引维护",
     "mediaLibrary.unavailable": "媒体库不可用",
     "mediaLibrary.saveProgress": "保存中…",
     "mediaLibrary.empty": "暂无图片或视频",
@@ -1322,15 +1404,43 @@ const zhCN = {
     "memo.navigation.all": "全部",
     "memo.navigation.allNotes": "笔记",
     "memo.navigation.conversations": "对话",
+    "memo.guide.ariaLabel": "列表视图介绍",
+    "memo.guide.pageStatus": "第 {current} 页，共 {total} 页",
+    "memo.guide.goToPage": "前往第 {page} 页",
+    "memo.guide.close": "关闭介绍",
+    "memo.guide.previous": "上一步",
+    "memo.guide.next": "下一步",
+    "memo.guide.done": "开始使用",
+    "memo.guide.fileTree.title": "文件树展示",
+    "memo.guide.fileTree.description": "树形呈现笔记、图片 / 视频和其他文件，适合阅读本地文件夹。",
+    "memo.guide.notes.title": "笔记展示",
+    "memo.guide.notes.description": "呈现全部 Markdown 文档，适合记录与专注写作。",
+    "memo.guide.conversations.title": "AI 对话展示",
+    "memo.guide.conversations.description": "管理本地对话，可读取笔记本空间，适合 AI 协同辅助。",
     "memo.navigation.collapseNotebookList": "折叠笔记本列表",
     "memo.navigation.expandNotebookList": "展开笔记本列表",
     "memo.navigation.notebooks": "笔记本",
     "memo.navigation.tags": "标签",
     "memo.navigation.referenceMaterials": "参考资料",
     "memo.navigation.loading": "加载中…",
+    "memo.navigation.preparingVersion": "版本初始化中…",
     "memo.navigation.preparingNotebook": "正在准备笔记本…",
-    "memo.navigation.preparingWorkspace": "正在准备数据",
-    "memo.navigation.startupMigrationFailed": "工作区迁移失败，请重新启动应用后重试。",
+    "memo.navigation.workspacePreparationFailed": "工作区准备失败，请重试。",
+    "startup.progress.prepareDatabasePaths": "迁移数据库位置",
+    "startup.progress.prepareThreadDatabase": "准备对话数据库",
+    "startup.progress.prepareSyncDatabase": "准备同步数据库",
+    "startup.progress.prepareNotebookRegistry": "准备笔记本注册表",
+    "startup.progress.runMigrations": "执行迁移",
+    "startup.progress.migrateAgentLayout": "迁移 Agent 配置",
+    "startup.progress.migrateLocalConfiguration": "迁移本地配置",
+    "startup.progress.migrateWatcherSettings": "更新文件监控设置",
+    "startup.progress.prepareTemplates": "准备模板",
+    "startup.progress.migrateNotebookStorage": "升级笔记本存储",
+    "startup.progress.deferredNotebookJobs": "等待笔记本就绪",
+    "startup.progress.prepareRuntimeStorage": "准备运行时数据",
+    "startup.progress.activateRuntime": "启用运行时配置",
+    "startup.progress.completeInitialization": "完成版本初始化",
+    "memo.navigation.startupMigrationFailed": "初始化失败，请重试。",
     "memo.navigation.emptyTags": "暂无标签",
     "memo.navigation.emptyReferences": "暂无参考资料",
     "memo.navigation.files": "仓库",
@@ -1341,6 +1451,7 @@ const zhCN = {
     "memo.fileTree.agentsSectionTitle": "对话",
     "memo.fileTree.agentsEmpty": "列表为空",
     "memo.fileTree.moreAgents": "更多",
+    "memo.fileTree.openAllConversations": "打开全部对话",
     "memo.fileTree.collapseAgents": "折叠对话",
     "memo.fileTree.expandAgents": "展开对话",
     "memo.fileTree.pinnedSectionTitle": "置顶",
@@ -1376,6 +1487,7 @@ const zhCN = {
     "memo.fileTree.newDocument": "新建文档",
     "memo.fileTree.newFolder": "新建文件夹",
     "memo.fileTree.customizeDisplay": "自定义展示",
+    "memo.fileTree.hideSection": "隐藏",
     "memo.fileTree.rename": "重命名",
     "memo.fileTree.renaming": "重命名中…",
     "memo.fileTree.moreActions": "更多操作",
@@ -1390,6 +1502,7 @@ const zhCN = {
     "memo.fileTree.deleted": "已删除 {name}",
     "memo.fileTree.deleteFailed": "删除失败",
     "memo.fileTree.deletePartialFailed": "文件夹只删除了部分内容，请刷新后检查剩余文件",
+    "memo.fileTree.deleteFolderViewCleanupFailed": "文件夹已删除，但无法清除其中打开的内容",
     "memo.fileTree.createFailed": "创建失败",
     "memo.fileTree.nameConflict": "同名文件已存在，请使用其他名称",
     "memo.fileTree.openInNewTab": "在新标签打开",
@@ -1406,9 +1519,19 @@ const zhCN = {
     "memo.fileTree.openFailed": "打开失败",
     "memo.fileTree.moveFailed": "移动失败",
     "memo.fileTree.movePartialFailed": "移动失败：{moved} 个成功，{failed} 个失败",
+    "memo.fileTree.movePartialFailedWithReason": "移动失败：{moved} 个成功，{failed} 个失败（{reason}）",
+    "memo.fileTree.moveDuplicate": "已存在重复文档",
+    "memo.fileTree.moveCloudFileNotDownloaded": "文件仍在云端，请下载后重试",
+    "memo.fileTree.movePermissionDenied": "文件或目标目录无访问权限",
+    "memo.fileTree.moveSourceUnavailable": "源文件已不存在或不是普通文件",
+    "memo.fileTree.moveTargetUnavailable": "目标目录已不可用",
     "memo.fileTree.moving": "正在移动",
     "memo.fileTree.moved": "已移动",
     "memo.fileTree.draggingNotes": "拖动 {count} 篇笔记",
+    "memo.fileTree.calendarDropUnsupported": "文档不支持加入日历",
+    "memo.fileTree.kanbanDropUnsupported": "仅支持将当前笔记本中的 Markdown 笔记加入看板",
+    "memo.fileTree.galleryDropUnsupported": "仅支持将当前笔记本中的 Markdown 笔记加入画廊",
+    "memo.fileTree.tableDropUnsupported": "仅支持将当前笔记本中的 Markdown 笔记加入表格",
     "memo.fileTree.dropToMove": "松开以移入",
     "memo.fileTree.dropToRoot": "松开以移到笔记本根目录",
     "memo.fileTree.loading": "加载中…",
@@ -1419,13 +1542,10 @@ const zhCN = {
     "notebook.iconLabel": "图标",
     "notebook.create.title": "新建笔记本",
     "notebook.create.namePlaceholder": "笔记本名称",
-    "notebook.create.pathPlaceholder": "选择笔记存储文件夹",
+    "notebook.create.pathPlaceholder": "默认文稿位置",
     "notebook.create.pathLabel": "存储位置",
     "notebook.create.selectDirectory": "选择目录",
-    "notebook.create.customPath": "自定义存储路径",
     "notebook.create.cancel": "关闭",
-    "notebook.create.confirm": "新建笔记本",
-    "notebook.create.creating": "正在创建中",
     "notebook.edit.title": "编辑笔记本",
     "notebook.edit.namePlaceholder": "笔记本名称",
     "notebook.edit.pathLabel": "保存至",
@@ -1433,17 +1553,14 @@ const zhCN = {
     "notebook.edit.confirm": "保存",
     "notebook.edit.saving": "保存中...",
     "notebook.edit.remove": "移除",
-    "notebook.edit.agents.title": "笔记本介绍",
-    "notebook.edit.agents.placeholder": "追加提示词，引导 AI 理解内容\n输入内容将添加到 AGENTS.md 文档中",
-    "notebook.edit.agents.saved": "笔记本和 AGENTS.md 已保存",
-    "notebook.edit.agents.saveFailed": "保存笔记本介绍失败",
 
     // document
     "document.file.unavailable": "文件无法查看",
     "document.file.loading": "正在加载文件…",
-    "document.file.openContainingFolder": "在文件夹中打开",
+    "document.file.openContainingFolder": "在文件夹中显示",
     "document.file.openWithDefaultApp": "默认应用打开",
     "document.file.reveal": "在文件夹中显示",
+    "collection.resetCurrentView": "重置当前视图",
     "document.file.locationClamped": "文件已打开，但引用位置超出当前内容范围，已定位到末尾。",
     "document.file.anchorNotFound": "文件已打开，但找不到引用的标题。",
     "document.file.locationUnsupported": "文件已打开，但当前视图不支持行号或标题定位。",
@@ -1556,7 +1673,6 @@ const zhCN = {
     "document.save.useDisk": "使用磁盘版本",
     "document.save.retry": "重试保存",
     "document.save.missing": "文件暂时不可用",
-    "document.save.closeFailed": "部分修改尚未保存完成，窗口将保持打开。",
     "document.save.titleFailed": "标题未能保存，修改后可重试。",
     "document.save.titleEmpty": "请输入文件名。",
     "document.save.recoverTitle": "恢复未提交的标题",
@@ -1564,8 +1680,10 @@ const zhCN = {
     "document.save.externalChanged": "文档已被外部修改",
     "document.save.sourceMissingDiscarded": "源文件已不存在，未保存的本地内容已丢弃并关闭标签",
     "document.load.failed": "读取失败",
+    "document.load.missingNoteTitle": "糟糕，笔记未找到",
     "document.load.accessDenied": "文件不在当前授权范围内，或当前用户无权访问。",
     "document.load.fileNotFound": "文件不存在或无法解析其真实路径。",
+    "document.load.recoveryTimeout": "恢复草稿读取超时，请重试。",
     "document.load.notTextFile": "目标不是受支持的文本文件。",
     "document.properties.title": "属性",
     "document.properties.noteTitle": "属性",
@@ -1784,6 +1902,10 @@ const zhCN = {
     "editor.noteLink.stale": "链接已失效 · {path}",
     "editor.noteLink.untitled": "未命名",
     "editor.noteLink.staleMark": "（已失效）",
+    "editor.noteLink.previewLoading": "正在加载笔记预览…",
+    "editor.noteLink.previewUnavailable": "暂时无法加载笔记预览",
+    "editor.noteLink.previewEmpty": "暂无预览内容",
+    "editor.noteLink.openNote": "打开笔记",
     "editor.noteMention.header": "笔记",
     "editor.noteMention.loading": "加载中",
     "editor.noteMention.empty": "无匹配笔记",
@@ -1807,6 +1929,10 @@ const zhCN = {
     "editor.threadCard.copyLatex": "复制 LaTeX",
     "editor.threadCard.model": "模型",
     "editor.threadCard.mode": "模式",
+    "editor.threadCard.composer.planMode": "计划模式",
+    "editor.threadCard.commandMode.plan": "Plan 模式",
+    "editor.threadCard.commandMode.goal": "Goal 模式",
+    "editor.threadCard.composer.longTask": "长任务",
     "editor.threadCard.piCodeMode": "代码",
     "editor.threadCard.piWritingMode": "写作",
     "editor.threadCard.inputTokens": "输入",
@@ -1944,6 +2070,9 @@ const zhCN = {
     "preferences.format.fontStatus.downloading": "下载中",
     "preferences.format.fontStatus.needsDownload": "待下载",
     "multidimensionalTable.view.rename": "重命名",
+    "multidimensionalTable.referenceIdentityChanged": "引用的表格身份已变化。当前路径对应的表格与引用保存的 table.id 不一致，请重新选择表格。",
+    "multidimensionalTable.removeReference": "移除此表格引用",
+    "multidimensionalTable.deleteTableFile": "删除多维表格",
     "multidimensionalTable.view.name": "视图名称",
     "multidimensionalTable.view.delete": "删除",
     "multidimensionalTable.view.deleteConfirm": "确定删除视图“{name}”吗？",
@@ -1954,6 +2083,16 @@ const zhCN = {
     "multidimensionalTable.view.kanbanMissingField": "看板依赖的单选分组字段，已被删除。请更换看板分组字段。",
     "multidimensionalTable.view.calendarMissingField": "日历依赖的日期类型字段，已被删除。请更换日历日期字段。",
     "multidimensionalTable.view.kanbanFieldTypeMismatch": "看板需要单选类型的分组字段“{field}”，当前字段类型为“{type}”。请将属性改回单选，或更换看板分组字段。",
+    "multidimensionalTable.kanbanDropReadOnly": "当前看板不可编辑，无法加入笔记",
+    "multidimensionalTable.kanbanDropUnavailable": "无法加入此分组，请检查看板分组设置",
+    "multidimensionalTable.kanbanDropFailed": "加入看板失败",
+    "multidimensionalTable.galleryDropReadOnly": "当前画廊不可编辑，无法加入笔记",
+    "multidimensionalTable.dropOverlayHint": "松开以添加到列表",
+    "multidimensionalTable.galleryDropFailed": "加入画廊失败",
+    "multidimensionalTable.galleryDropFiltered": "拖入的笔记不符合当前画廊的筛选条件",
+    "multidimensionalTable.tableDropReadOnly": "当前表格不可编辑，无法加入笔记",
+    "multidimensionalTable.tableDropFailed": "加入表格失败",
+    "multidimensionalTable.tableDropFiltered": "拖入的笔记不符合当前表格的筛选条件",
     "multidimensionalTable.view.calendarFieldTypeMismatch": "日历需要日期类型的日期字段“{field}”，当前字段类型为“{type}”。请将属性改回日期，或更换日历日期字段。",
     "multidimensionalTable.viewMembership.add": "添加到视图",
     "multidimensionalTable.viewMembership.hide": "从视图隐藏",
diff --git a/app/flowix-web/lib/i18n/provider.tsx b/app/flowix-web/lib/i18n/provider.tsx
index f1f3a5298..f4db03c92 100644
--- a/app/flowix-web/lib/i18n/provider.tsx
+++ b/app/flowix-web/lib/i18n/provider.tsx
@@ -28,7 +28,7 @@ interface I18nContextValue {
 
 const I18nContext = createContext<I18nContextValue>({
   language: DEFAULT_APP_LANGUAGE,
-  t: (key) => getMessages(DEFAULT_APP_LANGUAGE)[key],
+  t: (key, params) => interpolate(getMessages(DEFAULT_APP_LANGUAGE)[key], params),
 });
 
 export function I18nProvider({
diff --git a/app/flowix-web/lib/memo-dispatcher-dedup.test.ts b/app/flowix-web/lib/memo-dispatcher-dedup.test.ts
index c878f78e3..b62855765 100644
--- a/app/flowix-web/lib/memo-dispatcher-dedup.test.ts
+++ b/app/flowix-web/lib/memo-dispatcher-dedup.test.ts
@@ -4,11 +4,11 @@ import { createMemoDedupMiddleware } from './memo-dispatcher-dedup';
 
 function updated(revision: number, notebookId = 'notebook'): Extract<MemoEvent, { kind: 'updated' }> {
   return {
-    kind: 'updated', id: 'memo', path: '/note.md', notebookId, revision,
+    kind: 'updated', path: '/note.md', notebookId, revision,
     changeId: `change-${revision}`, source: 'user_edit',
     derivedChanged: { tags: false, todos: false, agents: false },
     memo: {
-      id: 'memo', filename: 'note.md', relativePath: 'note.md', preview: '', tags: [], todos: [], agents: [],
+      filename: 'note.md', relativePath: 'note.md', preview: '', tags: [], todos: [], agents: [],
       createdAt: 1, updatedAt: 1, favorited: false, icon: null, colors: [], properties: {},
     },
   };
diff --git a/app/flowix-web/lib/memo-dispatcher-dedup.ts b/app/flowix-web/lib/memo-dispatcher-dedup.ts
index 8e302925b..2e6164a73 100644
--- a/app/flowix-web/lib/memo-dispatcher-dedup.ts
+++ b/app/flowix-web/lib/memo-dispatcher-dedup.ts
@@ -1,5 +1,5 @@
 /**
- * `memoDispatcher` dedup middleware — 同 id 短窗口内合并, last-write-wins。
+ * `memoDispatcher` dedup middleware — 同笔记路径短窗口内合并, last-write-wins。
  *
  * 背景:
  * - 后端 fs_watcher 在 FSEvents 双触发 / 编辑器 debounce save 期间
@@ -12,8 +12,7 @@
  *   N 次 IPC + N 次 `applyLoadedContent`。
  *
  * 设计:
- * - 按 `getKey(event)` 拿到同一 memo 的 key (MemoEvent 统一走 `id` 或
- *   新建 memo 的 `memo.id`)。
+ * - 按 `getKey(event)` 拿到同一笔记的 key (`notebookId + relativePath`)。
  * - 同 key 在 `delay` 窗口内有新事件 → 清掉旧 timer, 用新事件覆盖
  *   pending, 重启 timer。
  * - timer 到期 → 把最后一次事件 `next()` 给下游, 清掉 pending entry。
@@ -39,25 +38,24 @@ import type { DispatcherMiddleware } from '@/lib/event-dispatcher';
 import type { MemoEvent, MemoDerivedRefresh } from '@/types/memo';
 
 /**
- * 取 MemoEvent 的 dedup key。 三种 kind 都能拿到 memo id:
- * - created → e.memo.id
- * - updated → e.id
- * - deleted → e.id
+ * 取 MemoEvent 的 dedup key。三种 kind 都按笔记相对路径定位:
+ * - created → e.memo.relativePath
+ * - updated → e.memo.relativePath
+ * - deleted → e.relativePath
  * - tags_renamed → 返回 `undefined` (立即派发, 不 dedup) ── 它不是
- *   单条 memo 事件, 没有 memo id 维度; 短时间内多次 rename 也应该
+ *   单条笔记事件, 没有笔记路径维度; 短时间内多次 rename 也应该
  *   各自生效, 不能合并。
  *
  * 返回 `undefined` 表示此事件不参与 dedup (立即 next)。
  */
 function memoEventKey(event: MemoEvent): string | undefined {
-  // Path-keyed dedup: (notebookId, relativePath) is the identity that
-  // survives the legacy memo id decommission.
+  // Path-keyed dedup: (notebookId, relativePath) identifies a note.
   if (event.kind === 'created')
-    return JSON.stringify([event.notebookId, event.memo.relativePath ?? event.memo.filename]);
+    return JSON.stringify([event.notebookId, event.memo.relativePath]);
   if (event.kind === 'updated')
-    return JSON.stringify([event.notebookId, event.memo.relativePath ?? event.path]);
+    return JSON.stringify([event.notebookId, event.memo.relativePath]);
   if (event.kind === 'deleted') return JSON.stringify([event.notebookId, event.relativePath]);
-  // tags_renamed 没有 memo id 维度, 返回 undefined 让 caller 走 "立即 next" 分支
+  // tags_renamed 没有单笔记路径维度，立即派发。
   return undefined;
 }
 
@@ -75,7 +73,7 @@ export interface CreateMemoDedupMiddlewareOptions {
   onDiscardedDerivedChange?: (event: MemoDerivedRefresh) => void;
   /** 合并窗口, 默认 50ms。 */
   delay?: number;
-  /** 自定义 key 提取, 默认按 MemoEvent 的 memo id。 */
+  /** 自定义 key 提取, 默认按笔记路径。 */
   getKey?: (event: MemoEvent) => string | undefined;
 }
 
diff --git a/app/flowix-web/lib/memo-dispatcher.ts b/app/flowix-web/lib/memo-dispatcher.ts
index 7a685b2ac..2a9eac433 100644
--- a/app/flowix-web/lib/memo-dispatcher.ts
+++ b/app/flowix-web/lib/memo-dispatcher.ts
@@ -111,21 +111,7 @@ function installMemoDedup(): void {
 }
 installMemoDedup();
 
-// ---- 跨订阅者注册接口 -------------------------------------------------------
-//
-// 给 `useExternalDocumentChangeWatch` 等需要"按 kind + source + path
-// 自定义"的 hook 用: 它们走 `memoDispatcher.subscribe(...)` 注册自己
-// 的 handler, 不再直接监听 Tauri 通道，并共享同一份 dedup / filter / log
-// 中间件。
-//
-// 这正是 Phase 1 的核心收益: 把双订阅从"event-bus 层并列"统一到
-// "memoDispatcher 层声明式 filter"。
-
-/**
- * 给 `useExternalDocumentChangeWatch` 等外部组件使用的注册接口。
- * 等价于 `memoDispatcher.subscribe` 但带命名空间前缀, 阅读时一眼看出
- * "这是 reload 类 handler, 不是 note-store 类"。
- */
+/** Register an application-level MemoEvent consumer with an optional filter. */
 export function registerMemoEventHandler(
   handler: (event: MemoEvent) => void,
   filter?: (event: MemoEvent) => boolean,
diff --git a/app/flowix-web/lib/path.ts b/app/flowix-web/lib/path.ts
index 874ca50ba..c356c99fe 100644
--- a/app/flowix-web/lib/path.ts
+++ b/app/flowix-web/lib/path.ts
@@ -2,9 +2,8 @@
  * Cross-platform path utilities for joining notebook and memo paths.
  * On Mac/Linux, uses forward slashes; on Windows, handles both \\ and /.
  *
- * v3 改造: filename 改成磁盘文件名 (含 .md, 不再带 #memoid 后缀),
- * 因此 extractMemoIdFromPath / generateMemoFilename / MEMO_ID_FILENAME_PATTERN
- * 全部移除。memo id 由后端 memo index 持有, 前端从 memo 结构读。
+ * Notes use their notebook-relative path as the stable address. Filenames
+ * are the physical disk names, including `.md`; no memo ID is encoded there.
  */
 
 export function joinNotebookMemoPath(notebookPath: string, memoPath: string | null | undefined): string | null {
@@ -68,6 +67,14 @@ export function samePath(left: string, right: string): boolean {
   return canonicalPath(left) === canonicalPath(right);
 }
 
+/** Whether a path is the directory itself or one of its descendants. */
+export function isPathInDirectory(path: string, directoryPath: string): boolean {
+  const candidate = canonicalDirectoryPath(path);
+  const directory = canonicalDirectoryPath(directoryPath);
+  return candidate === directory
+    || candidate.startsWith(directory === '/' ? '/' : `${directory}/`);
+}
+
 export function uniquePaths(paths: string[]): string[] {
   const seen = new Set<string>();
   return paths.filter((path) => {
@@ -83,6 +90,7 @@ export function fileNameFromPath(filePath: string): string {
   return canonicalFilePath.slice(canonicalFilePath.lastIndexOf('/') + 1);
 }
 
+/** Destination when moving a file into a directory; discards its original parent directories. */
 export function pathInDirectory(directoryPath: string, filePath: string): string {
   const directory = canonicalDirectoryPath(directoryPath);
   const name = fileNameFromPath(filePath);
diff --git a/app/flowix-web/lib/save-barrier.ts b/app/flowix-web/lib/save-barrier.ts
new file mode 100644
index 000000000..67474a11d
--- /dev/null
+++ b/app/flowix-web/lib/save-barrier.ts
@@ -0,0 +1,33 @@
+/** Wait for the full save transaction, including work performed after its write. */
+export function createSaveBarrier() {
+  let failed = false;
+  let pending: { promise: Promise<boolean>; resolve: (saved: boolean) => void } | null = null;
+  return {
+    setSaving(saving: boolean) {
+      if (saving) {
+        if (pending) return;
+        failed = false;
+        let resolve!: (saved: boolean) => void;
+        const promise = new Promise<boolean>((done) => { resolve = done; });
+        pending = { promise, resolve };
+      } else {
+        const completed = pending;
+        pending = null;
+        completed?.resolve(!failed);
+      }
+    },
+    fail() { failed = true; },
+    resetFailure() { failed = false; },
+    cancel() {
+      const cancelled = pending;
+      pending = null;
+      cancelled?.resolve(false);
+    },
+    async flush(): Promise<boolean> {
+      while (pending) {
+        if (!await pending.promise) return false;
+      }
+      return !failed;
+    },
+  };
+}
diff --git a/app/flowix-web/lib/startup-stage3.ts b/app/flowix-web/lib/startup-stage3.ts
new file mode 100644
index 000000000..dfd48e75e
--- /dev/null
+++ b/app/flowix-web/lib/startup-stage3.ts
@@ -0,0 +1,36 @@
+type StartupStage3Task = () => void | Promise<void>;
+
+let admitted = false;
+let resolveAdmission!: () => void;
+const admission = new Promise<void>((resolve) => {
+  resolveAdmission = resolve;
+});
+const tasks = new Map<string, Promise<void>>();
+
+/** Release non-blocking startup work after the first workbench paint. */
+export function admitStartupStage3(): void {
+  if (admitted) return;
+  admitted = true;
+  resolveAdmission();
+}
+
+export function waitForStartupStage3(): Promise<void> {
+  return admission;
+}
+
+/** Run an admitted startup task once per WebView, even if its effect remounts. */
+export function runStartupStage3Task(
+  taskId: string,
+  task: StartupStage3Task,
+): Promise<void> {
+  const existing = tasks.get(taskId);
+  if (existing) return existing;
+
+  const pending = admission
+    .then(task)
+    .catch((error) => {
+      console.warn(`[startup:stage3] ${taskId} failed`, error);
+    });
+  tasks.set(taskId, pending);
+  return pending;
+}
diff --git a/app/flowix-web/lib/store/workspace-startup-store.test.ts b/app/flowix-web/lib/store/workspace-startup-store.test.ts
new file mode 100644
index 000000000..b47336f58
--- /dev/null
+++ b/app/flowix-web/lib/store/workspace-startup-store.test.ts
@@ -0,0 +1,21 @@
+import { beforeEach, expect, it } from 'vitest';
+import { applyNativeStartupStatus as apply, useWorkspaceStartupStore as store } from './workspace-startup-store';
+beforeEach(() => store.setState({ nativePhase: 'pending', nativeStage: 'initialization', nativeStep: 'initialization', nativeProgress: null, nativeError: null }));
+it('rejects a late initialization response after workspace preparation starts', () => {
+  apply({ phase: 'running', stage: 'workspacePreparation', step: 'preparingData', error: null });
+  apply({ phase: 'running', stage: 'initialization', step: 'versionInitialization', error: null,
+    progress: { percent: 30, completed: 0, total: 2, task: 'runMigrations' } });
+  expect(store.getState().nativeStage).toBe('workspacePreparation');
+  expect(store.getState().nativeProgress).toBeNull();
+});
+it('keeps the shell ready when an earlier polling response arrives late', () => {
+  store.setState({ nativePhase: 'ready', nativeStage: 'workspacePreparation' });
+  apply({ phase: 'running', stage: 'workspacePreparation', step: 'preparingData', error: null });
+  expect(store.getState().nativePhase).toBe('ready');
+});
+it('allows retry within the failed stage', () => {
+  apply({ phase: 'failed', stage: 'workspacePreparation', step: 'preparingData', error: 'unavailable' });
+  apply({ phase: 'pending', stage: 'workspacePreparation', step: 'preparingData', error: null });
+  expect(store.getState().nativePhase).toBe('pending');
+  expect(store.getState().nativeStage).toBe('workspacePreparation');
+});
diff --git a/app/flowix-web/lib/store/workspace-startup-store.ts b/app/flowix-web/lib/store/workspace-startup-store.ts
new file mode 100644
index 000000000..b3d8f4b6d
--- /dev/null
+++ b/app/flowix-web/lib/store/workspace-startup-store.ts
@@ -0,0 +1,46 @@
+import type { StartupStatus } from '@platform/tauri/client/general';
+import { create } from 'zustand';
+
+export type WorkspaceStartupStatus = 'idle' | 'running' | 'ready' | 'degraded' | 'failed';
+export type NativeStartupPhase = 'pending' | 'running' | 'ready' | 'failed';
+
+/** Process-local foreground startup state. Never persist it across launches. */
+export const useWorkspaceStartupStore = create<{
+  nativePhase: NativeStartupPhase;
+  nativeStage: 'initialization' | 'workspacePreparation';
+  nativeStep: string;
+  nativeError: string | null;
+  nativeProgress: { percent: number; completed: number; total: number; task: string } | null;
+  status: WorkspaceStartupStatus;
+  workbenchMounted: boolean;
+  task: string | null;
+  error: string | null;
+}>()(() => ({
+  nativePhase: 'pending',
+  nativeStage: 'initialization',
+  nativeStep: 'initialization',
+  nativeError: null,
+  nativeProgress: null,
+  status: 'idle',
+  workbenchMounted: false,
+  task: null,
+  error: null,
+}));
+
+/** Native responses and the foreground readiness promise can settle out of order. */
+export function applyNativeStartupStatus(status: StartupStatus): void {
+  const stage = status.stage ?? (status.step === 'versionInitialization' || status.step === 'initialization'
+    ? 'initialization' : 'workspacePreparation');
+  useWorkspaceStartupStore.setState((state) => {
+    if (state.nativePhase === 'ready' && status.phase !== 'ready') return state;
+    if (state.nativeStage === 'workspacePreparation' && stage === 'initialization') return state;
+    if (state.nativePhase === status.phase && state.nativeStage === stage
+      && state.nativeStep === status.step && state.nativeError === status.error
+      && state.nativeProgress?.percent === status.progress?.percent
+      && state.nativeProgress?.task === status.progress?.task
+      && state.nativeProgress?.completed === status.progress?.completed
+      && state.nativeProgress?.total === status.progress?.total) return state;
+    return { ...state, nativePhase: status.phase, nativeStage: stage,
+      nativeStep: status.step, nativeError: status.error, nativeProgress: status.progress ?? null };
+  });
+}
diff --git a/app/flowix-web/lib/types/agent-access.ts b/app/flowix-web/lib/types/agent-access.ts
deleted file mode 100644
index 516e88329..000000000
--- a/app/flowix-web/lib/types/agent-access.ts
+++ /dev/null
@@ -1,95 +0,0 @@
-/**
- * Agent 访问目录 (可访问文件夹) — 镜像后端 `app/flowix-desktop/src/agent_access.rs`
- * 的 `AgentAccessConfig` / `AgentAccessEntry` / `AgentAccessKind`。
- *
- * 真源在 `~/.flowix/agent-access.json` (后端 `agent_access::AgentAccessStore`),
- * 前端走 `lib/tauri/client.ts::agentAccess` IPC 读写。 整份 set 走乐观更新,
- * 跨窗口同步靠后端 emit 的 `agent-access-changed` 事件。
- */
-
-import type {
-  AgentCodexReasoningEffort,
-  AgentHarnessPreset,
-  AgentPermissionMode,
-  AgentTypeKey,
-  FilesConfig,
-} from "@/types/agent";
-
-/**
- * Responsibility split for `~/.flowix/agent-access.json`:
- *
- * - `defaults`: default runtime values copied into a newly created
- *   agent-thread-card instance; file defaults are legacy read-only data.
- * - `entries`: global access registry used to authorize notebook add-dirs.
- * - actual per-run file permission: instance `runtimeConfig.files`, sent as
- *   IPC `runtimeConfig.{agent}.workspacePaths`.
- */
-
-export type AgentAccessKind = "notebook" | "folder";
-
-export interface AgentAccessEntry {
-  id: string;
-  kind: AgentAccessKind;
-  path: string;
-  name: string;
-  enabled: boolean;
-  /** @deprecated Workspace selection is notebook-owned; retained for v1 JSON. */
-  workspace?: boolean;
-  addedAt: number;
-  updatedAt: number;
-  /** 运行时由后端重算: 该 path 在磁盘上是否还存在。 失联目录保留在列表,
-   *  UI 据此灰显 + 强制禁用勾选框。 */
-  missing: boolean;
-}
-
-export interface AgentAccessDefaultRuntime {
-  model?: { key: string; providerId?: string };
-  access?: { sandbox: AgentPermissionMode };
-  reasoningEffort?: AgentCodexReasoningEffort;
-  serviceTier?: "auto" | "priority";
-  /** DeepSeek Harness tool presentation mode. */
-  mode?: AgentHarnessPreset;
-  /** Default Pi codemode setting for newly created conversations. */
-  piCodeMode?: boolean;
-}
-
-/**
- * Legacy `defaults.files` global key retained for read-only migration of old
- * installations. New writes always target notebook `.flowix/agent.json`.
- */
-export const DEFAULT_FILES_GLOBAL_KEY = "_global";
-
-/**
- * Legacy notebook-indexed files defaults. This type is retained so old config
- * files can be read and migrated; it is no longer the write target.
- *
- * 老版本 `defaults.files` 是单个 `FilesConfig` 对象, 读取时由
- * `normalizeFilesDefaults` 归一化到 `{ _global: <old> }`, 写入时始终落索引。
- */
-export type AgentAccessFilesDefaults = Record<string, FilesConfig>;
-
-export interface AgentAccessDefaults {
-  runtime?: Partial<Record<AgentTypeKey, AgentAccessDefaultRuntime>>;
-  files?: AgentAccessFilesDefaults;
-}
-
-export interface AgentAccessConfig {
-  version: number; // 当前 = 1
-  entries: AgentAccessEntry[];
-  defaults?: AgentAccessDefaults;
-}
-
-/** Notebook-local `.flowix/agent.json`. The notebook itself is always cwd;
- * `addDirs` contains only additional runtime roots. */
-export interface NotebookAddDir {
-  id: string;
-  path: string;
-  label: string;
-  enabled: boolean;
-}
-
-export interface NotebookAgentConfig {
-  version: 1;
-  revision: number;
-  addDirs: NotebookAddDir[];
-}
diff --git a/app/flowix-web/lib/types/agent-workspace.test-support.ts b/app/flowix-web/lib/types/agent-workspace.test-support.ts
new file mode 100644
index 000000000..1c760d9ef
--- /dev/null
+++ b/app/flowix-web/lib/types/agent-workspace.test-support.ts
@@ -0,0 +1,39 @@
+/** Historical config fixtures retained for legacy-session regression tests. */
+import type { AgentTypeKey, FilesConfig } from '@/types/agent';
+import type { LegacyAgentRuntimePreference } from './agent-workspace';
+
+export type AgentAccessKind = "notebook" | "folder";
+
+export interface AgentAccessEntry {
+  id: string;
+  kind: AgentAccessKind;
+  path: string;
+  name: string;
+  enabled: boolean;
+  /** @deprecated Workspace selection is notebook-owned; retained for v1 JSON. */
+  workspace?: boolean;
+  addedAt: number;
+  updatedAt: number;
+  /** 运行时由后端重算: 该 path 在磁盘上是否还存在。 失联目录保留在列表,
+   *  UI 据此灰显 + 强制禁用勾选框。 */
+  missing: boolean;
+}
+
+/**
+ * Legacy notebook-indexed files defaults. This type is retained so old config
+ * files can be read and migrated; it is no longer the write target.
+ *
+ * The backend migrates old shapes into notebook-local add-dir configs.
+ */
+export type AgentAccessFilesDefaults = Record<string, FilesConfig>;
+
+export interface AgentAccessDefaults {
+  runtime?: Partial<Record<AgentTypeKey, LegacyAgentRuntimePreference>>;
+  files?: AgentAccessFilesDefaults;
+}
+
+export interface AgentAccessConfig {
+  version: number; // 当前 = 1
+  entries: AgentAccessEntry[];
+  defaults?: AgentAccessDefaults;
+}
diff --git a/app/flowix-web/lib/types/agent-workspace.ts b/app/flowix-web/lib/types/agent-workspace.ts
new file mode 100644
index 000000000..e3003847e
--- /dev/null
+++ b/app/flowix-web/lib/types/agent-workspace.ts
@@ -0,0 +1,52 @@
+/** Device-local workspace DTOs; runtime preference types support upgrades. */
+
+import type {
+  AgentCodexReasoningEffort,
+  AgentHarnessPreset,
+  AgentPermissionMode,
+} from "@/types/agent";
+
+export interface LegacyAgentRuntimePreference {
+  model?: { key: string; providerId?: string };
+  access?: { sandbox: AgentPermissionMode };
+  reasoningEffort?: AgentCodexReasoningEffort;
+  serviceTier?: "auto" | "priority";
+  /** DeepSeek Harness tool presentation mode. */
+  mode?: AgentHarnessPreset;
+  /** Default Pi codemode setting for newly created conversations. */
+  piCodeMode?: boolean;
+}
+
+/** Legacy preference payload is a string-keyed map because its keys migrate. */
+export type LegacyAgentRuntimePreferences = Record<string, LegacyAgentRuntimePreference>;
+
+/** Notebook-local mount data read from local.db. The notebook itself is cwd;
+ * `addDirs` contains only additional runtime roots. */
+export interface NotebookAddDir {
+  id: string;
+  path: string;
+  label: string;
+  enabled: boolean;
+  missing?: boolean;
+}
+
+export interface NotebookWorkspaceConfig {
+  version: 1;
+  revision: number;
+  addDirs: NotebookAddDir[];
+}
+
+/** Authoritative device-local workspace read from local.db. */
+export interface AgentWorkspaceSnapshot {
+  notebooks: Array<{ id: string; name: string; path: string }>;
+  notebookConfigs: Record<string, NotebookWorkspaceConfig>;
+}
+
+/** Derived resource metadata; these rows are never persisted independently. */
+export interface AgentWorkspaceResource {
+  id: string;
+  path: string;
+  name: string;
+  enabled: boolean;
+  missing: boolean;
+}
diff --git a/app/flowix-web/lib/typography-font-mode.ts b/app/flowix-web/lib/typography-font-mode.ts
new file mode 100644
index 000000000..a05d2662d
--- /dev/null
+++ b/app/flowix-web/lib/typography-font-mode.ts
@@ -0,0 +1,26 @@
+import { FONT_FAMILY_OPTIONS } from '@/lib/constants';
+
+export const TYPOGRAPHY_FONT_MODES = ['standard', 'serif', 'wenkai'] as const;
+export type TypographyFontMode = (typeof TYPOGRAPHY_FONT_MODES)[number];
+
+const FONT_ID_BY_MODE: Record<TypographyFontMode, string> = {
+  standard: 'inter',
+  serif: 'noto-serif-sc',
+  wenkai: 'lxgw-wenkai',
+};
+
+export function getTypographyFontId(mode: TypographyFontMode): string {
+  return FONT_ID_BY_MODE[mode];
+}
+
+export function getTypographyFontMode(fontId: string | undefined): TypographyFontMode {
+  if (fontId === FONT_ID_BY_MODE.serif) return 'serif';
+  if (fontId === FONT_ID_BY_MODE.wenkai) return 'wenkai';
+  return 'standard';
+}
+
+export function getTypographyFontFamily(mode: TypographyFontMode): string {
+  const fontId = getTypographyFontId(mode);
+  return FONT_FAMILY_OPTIONS.find((font) => font.id === fontId)?.value
+    ?? FONT_FAMILY_OPTIONS[0].value;
+}
diff --git a/app/flowix-web/lib/workbench-mount.ts b/app/flowix-web/lib/workbench-mount.ts
new file mode 100644
index 000000000..338fae300
--- /dev/null
+++ b/app/flowix-web/lib/workbench-mount.ts
@@ -0,0 +1,21 @@
+import { useWorkspaceStartupStore } from './store/workspace-startup-store';
+
+let mounted = false;
+let resolveMounted!: () => void;
+
+const workbenchMounted = new Promise<void>((resolve) => {
+  resolveMounted = resolve;
+});
+
+/** Signal that the main workbench subtree has committed inside its Suspense boundary. */
+export function notifyWorkbenchMounted(): void {
+  if (mounted) return;
+  mounted = true;
+  useWorkspaceStartupStore.setState({ workbenchMounted: true });
+  resolveMounted();
+}
+
+/** Wait for the workbench subtree before declaring the first interactive paint. */
+export function waitForWorkbenchMounted(): Promise<void> {
+  return workbenchMounted;
+}
diff --git a/app/flowix-web/platform/tauri/client/agent.ts b/app/flowix-web/platform/tauri/client/agent.ts
index bcd9a98d0..45f1c2f7f 100644
--- a/app/flowix-web/platform/tauri/client/agent.ts
+++ b/app/flowix-web/platform/tauri/client/agent.ts
@@ -7,6 +7,7 @@ import type {
   AgentCodexReasoningEffort,
   AgentPermissionMode,
   AgentRuntimeConfig,
+  AgentRuntimeStatusById,
   AgentTypeKey,
   ChatMessage,
   RunInfo,
@@ -90,7 +91,7 @@ export interface AgentConversationCursor {
 }
 
 export interface AgentConversationListQuery {
-  notebookId: string | null;
+  notebookId: string;
   agentType: AgentTypeKey | null;
   cursor: AgentConversationCursor | null;
 }
@@ -217,23 +218,9 @@ export type AgentConversationInstanceUpsert = Omit<AgentConversationInstance, 't
   runtimeConfig?: string | null;
 };
 
-export interface AgentRuntimeAvailability {
-  available: boolean;
-  /** Executable/runtime presence, independent from model or dependency setup. */
-  installed?: boolean;
-  reasonCode?: string | null;
-  reason?: string | null;
-}
-
+/** Complete six-agent runtime snapshot returned by the desktop host. */
 export interface AgentRuntimeStatus {
-  codex: AgentRuntimeAvailability;
-  claude: AgentRuntimeAvailability;
-  gemini: AgentRuntimeAvailability;
-  hermes: AgentRuntimeAvailability;
-  openclaw: AgentRuntimeAvailability;
-  opencode: AgentRuntimeAvailability;
-  pi: AgentRuntimeAvailability;
-  'deepseek-harness': AgentRuntimeAvailability;
+  agents: AgentRuntimeStatusById;
 }
 
 export interface CodexRateLimitWindow {
@@ -287,6 +274,13 @@ export interface AgentExternalEntry {
   available: boolean;
 }
 
+const cacheAgentAttachment = (content: string, mimeType: string) =>
+  invoke<CachedAgentAttachment>('cache_agent_image', { content, mimeType });
+const deleteCachedAgentAttachment = (path: string) =>
+  invoke<boolean>('delete_cached_agent_image', { path });
+const readCachedAgentAttachment = (path: string) =>
+  invoke<string | null>('read_cached_agent_image', { path });
+
 export const agent = {
   runtimeStatus: () =>
     invoke<AgentRuntimeStatus>('agent_runtime_status'),
@@ -304,12 +298,17 @@ export const agent = {
     invoke<AgentExternalEntry>('redetect_agent_external', { agentType }),
   selectExternalCliPath: () =>
     invoke<string | null>('select_external_cli_path'),
-  cacheImage: (content: string, mimeType: string) =>
-    invoke<CachedAgentImage>('cache_agent_image', { content, mimeType }),
-  deleteCachedImage: (path: string) =>
-    invoke<boolean>('delete_cached_agent_image', { path }),
-  readCachedImage: (path: string) =>
-    invoke<string | null>('read_cached_agent_image', { path }),
+  // Frontend uses attachment terminology; the IPC names stay stable for older
+  // desktop builds and persisted agent data.
+  cacheAttachment: cacheAgentAttachment,
+  deleteCachedAttachment: deleteCachedAgentAttachment,
+  readCachedAttachment: readCachedAgentAttachment,
+  /** @deprecated Use cacheAttachment. */
+  cacheImage: cacheAgentAttachment,
+  /** @deprecated Use deleteCachedAttachment. */
+  deleteCachedImage: deleteCachedAgentAttachment,
+  /** @deprecated Use readCachedAttachment. */
+  readCachedImage: readCachedAgentAttachment,
   chatStream: (threadId: string, message: AgentUserMessage) =>
     invoke<ChatResponse>('chat_with_agent_stream', { threadId, message }),
   steerChat: (threadId: string, message: AgentUserMessage, clientUserMessageId: string, deliveryMode: 'steer' | 'follow_up' = 'steer') =>
@@ -403,9 +402,9 @@ export const agent = {
     invoke<AgentConversationInstance[]>('agent_conversation_list'),
   listConversationInstancesPage: (query: AgentConversationListQuery, limit: number) =>
     invoke<AgentConversationListPage>('agent_conversation_list_page', { ...query, limit }),
-  countConversationInstancesByNotebook: (notebookId: string | null) =>
+  countConversationInstancesByNotebook: (notebookId: string) =>
     invoke<number>('agent_conversation_count_by_notebook', { notebookId }),
-  listConversationTypeCountsByNotebook: (notebookId: string | null) =>
+  listConversationTypeCountsByNotebook: (notebookId: string) =>
     invoke<AgentConversationTypeCount[]>('agent_conversation_type_counts_by_notebook', { notebookId }),
   getConversationInstance: (instanceId: string) =>
     invoke<AgentConversationInstance | null>('agent_conversation_get', {
@@ -625,12 +624,15 @@ export const agent = {
   codexApprovalPending: () => invoke<CodexApprovalRequest[]>('codex_approval_pending'),
 };
 
-export interface CachedAgentImage {
+export interface CachedAgentAttachment {
   path: string;
   mimeType: string;
   name: string;
 }
 
+/** @deprecated Legacy payload name retained for existing integrations. */
+export type CachedAgentImage = CachedAgentAttachment;
+
 // Stream event handling
 //
 // Module-level singleton listener — only ONE registration is allowed. The
@@ -704,16 +706,16 @@ export function stopListeningToUserConfigChanges(): void {
   // subscribe 杩斿洖鐨?unlisten 璧?useEffect cleanup, 涓嶈鎵嬪伐璋?stopXxx銆?
 }
 
-// Agent 鍙闂洰褰曞彉鏇翠簨浠?鈹€鈹€ 鍚庣 set_agent_access / notebook CRUD
+// Agent 鍙闂洰褰曞彉鏇翠簨浠?鈹€鈹€ 鍚庣 notebook workspace / notebook CRUD
 // 閽╁瓙浠讳竴鎴愬姛閮?emit, payload 鏄?`()` (鏃?payload), 鐩戝惉鑰呯洿鎺?
 // `loadInitial()` 鎷夋暣浠?config銆?涓?`user-config-changed` 鍚屽舰銆?
 type AgentAccessChangeHandler = () => void;
 
-export function listenToAgentAccessChanges(
+export function listenToAgentWorkspaceChanges(
   handler: AgentAccessChangeHandler,
   options?: SubscribeOptions,
 ): UnlistenFn {
-  return subscribe<unknown>('agent-access-changed', () => handler(), options);
+  return subscribe<unknown>('agent-workspace-changed', () => handler(), options);
 }
 
 export function listenToNotebookImportComplete(
diff --git a/app/flowix-web/platform/tauri/client/cloud.ts b/app/flowix-web/platform/tauri/client/cloud.ts
index 52052d1c1..b33b0c9c6 100644
--- a/app/flowix-web/platform/tauri/client/cloud.ts
+++ b/app/flowix-web/platform/tauri/client/cloud.ts
@@ -6,7 +6,6 @@ export interface CloudUser {
   id: string;
   email: string;
   displayName: string;
-  systemRole: string;
 }
 
 export interface CloudMembership {
@@ -20,6 +19,10 @@ export interface CloudMembership {
   readOnly: boolean;
 }
 
+export interface CloudAiCreditBalance {
+  balanceMicrocredits: number;
+}
+
 export interface CloudState {
   revision: number;
   authenticated: boolean;
@@ -100,6 +103,29 @@ export interface CloudCheckout {
   expiresAt?: number | null;
 }
 
+export interface CloudOrder {
+  id: string;
+  productId: string;
+  productName: string;
+  amount: number;
+  currency: string;
+  status: string;
+  createdAt: number;
+  paidAt?: number | null;
+}
+
+export interface CloudOrderCheck {
+  status: string;
+  confirmed: boolean;
+  checkStatus: string;
+}
+
+export interface CloudFeedbackAttachment {
+  filename: string;
+  contentType: string;
+  dataBase64: string;
+}
+
 export interface CloudNoteHistory {
   noteId: string;
   notebookId: string;
@@ -138,9 +164,26 @@ export const cloud = {
     invoke<CloudNotebookSyncState>('cloud_set_notebook_enabled', { notebookId, enabled }),
   refreshMembership: () =>
     invoke<CloudMembership>('cloud_refresh_membership'),
+  getAiCreditBalance: () =>
+    invoke<CloudAiCreditBalance>('cloud_ai_credit_balance'),
+  connectPiModelProvider: () => invoke<void>('cloud_connect_pi_model_provider'),
+  refreshPiModelProvider: () => invoke<boolean>('cloud_refresh_pi_model_provider'),
+  refreshPiModelProviderAtStartup: () =>
+    invoke<boolean>('cloud_refresh_pi_model_provider_at_startup'),
   listProducts: () => invoke<CloudProduct[]>('cloud_list_products'),
+  listBillingOrders: () => invoke<CloudOrder[]>('cloud_list_billing_orders'),
+  checkBillingOrder: (orderId: string) =>
+    invoke<CloudOrderCheck>('cloud_check_billing_order', { orderId }),
   createCheckout: (productId: string) =>
     invoke<CloudCheckout>('cloud_create_checkout', { productId }),
+  submitFeedback: (
+    deviceId: string,
+    kind: 'product_suggestion' | 'usage_issue',
+    content: string,
+    appVersion: string,
+    platform: string,
+    attachments: CloudFeedbackAttachment[],
+  ) => invoke<void>('cloud_submit_feedback', { deviceId, kind, content, appVersion, platform, attachments }),
   syncNow: (notebookId?: string) =>
     invoke<CloudSyncResult>('cloud_sync_now', { notebookId }),
   noteHistory: (notebookId: string, relativePath: string) =>
diff --git a/app/flowix-web/platform/tauri/client/desktop.ts b/app/flowix-web/platform/tauri/client/desktop.ts
index 382e49ed1..9807b251c 100644
--- a/app/flowix-web/platform/tauri/client/desktop.ts
+++ b/app/flowix-web/platform/tauri/client/desktop.ts
@@ -1,10 +1,10 @@
+import { acceptPathMutationResult, publishNotebookPathMove, type PathMutationResult } from '../notebook-change-events';
 import { invokeDocumentMutation } from './document-mutation';
 import { convertFileSrc, invoke } from '@platform/tauri/core';
 import type { ThemeId } from '@/lib/theme';
 import type { NoteColor } from '@/types/note-item';
 
 export interface DocTreeMemoMeta {
-  id: string;
   icon: string | null;
   colors: NoteColor[];
   favorited: boolean;
@@ -149,13 +149,37 @@ export interface CollectionMutationResult {
   notebookPath: string;
   directoryMove: { previousRelativePath: string; relativePath: string } | null;
 }
+export interface CollectionChangedEvent {
+  notebookId: string;
+  collectionId: string;
+  operationId: string;
+  indexSequence: number;
+  relativePath: string;
+  previousRelativePath: string;
+  notebookPath: string;
+  name: string;
+  revision: number;
+  directoryMove?: CollectionMutationResult['directoryMove'];
+}
 export const collections = {
   list: (notebookId: string, collectionType?: CollectionIndexItem['collectionType']) =>
     invoke<CollectionIndexItem[]>('list_collections', { notebookId, collectionType }),
   resolve: (notebookId: string, collectionId: string) =>
     invoke<CollectionIndexItem>('resolve_collection', { notebookId, collectionId }),
   mutate: (request: CollectionMutationRequest) =>
-    invokeDocumentMutation<CollectionMutationResult>('mutate_collection', { request }),
+    invokeDocumentMutation<CollectionMutationResult>('mutate_collection', { request }).then((result) => {
+      const moved = result.directoryMove;
+      if (moved || result.previousRelativePath !== result.actualRelativePath) {
+        publishNotebookPathMove({
+          changeId: `collection:${request.notebookId}:${result.operationId}`,
+          notebookId: request.notebookId,
+          previousRelativePath: moved?.previousRelativePath ?? result.previousRelativePath,
+          relativePath: moved?.relativePath ?? result.actualRelativePath,
+          directory: Boolean(moved),
+        });
+      }
+      return result;
+    }),
   setInViews: (notebookId: string, collectionId: string, inViews: boolean) =>
     invoke<void>('set_collection_display_state', { notebookId, collectionId, inViews }),
   makeIdentityUnique: (notebookId: string, relativePath: string) =>
@@ -229,15 +253,17 @@ export const files = {
   deleteFolder: (folderPath: string, spacePath: string) =>
     invoke<boolean>('delete_folder', { folderPath, spacePath }),
   rename: (filePath: string, name: string, spacePath: string) =>
-    invokeDocumentMutation<string>('rename_file', { filePath, name, spacePath }),
+    invokeDocumentMutation<PathMutationResult>('rename_file', { filePath, name, spacePath }).then(acceptPathMutationResult),
   move: (filePath: string, targetDirectoryPath: string, spacePath: string) =>
-    invoke<string>('move_file', { filePath, targetDirectoryPath, spacePath }),
+    invoke<PathMutationResult>('move_file', { filePath, targetDirectoryPath, spacePath }).then(acceptPathMutationResult),
   moveFolder: (folderPath: string, targetDirectoryPath: string, spacePath: string) =>
-    invoke<string>('move_folder', { folderPath, targetDirectoryPath, spacePath }),
+    invoke<PathMutationResult>('move_folder', { folderPath, targetDirectoryPath, spacePath }).then(acceptPathMutationResult),
   importFile: (filePath: string, targetDirectoryPath: string, spacePath: string) =>
     invoke<string>('import_file', { filePath, targetDirectoryPath, spacePath }),
+  importFolder: (sourceDirectoryPath: string, targetDirectoryPath: string, spacePath: string) =>
+    invoke<string>('import_folder', { sourceDirectoryPath, targetDirectoryPath, spacePath }),
   renameFolder: (folderPath: string, name: string, spacePath: string) =>
-    invokeDocumentMutation<string>('rename_folder', { folderPath, name, spacePath }),
+    invokeDocumentMutation<PathMutationResult>('rename_folder', { folderPath, name, spacePath }).then(acceptPathMutationResult),
   createFolder: (spacePath: string, name: string, parentId?: string) =>
     invoke<DocTreeItem | null>('create_folder', { spacePath, name, parentId }),
   createDocument: (spacePath: string, name: string, parentId?: string) =>
@@ -282,6 +308,7 @@ export interface SaveFileFilter {
 
 export const dialogs = {
   selectDirectory: () => invoke<string | null>('select_directory'),
+  selectImportDirectory: () => invoke<string | null>('select_import_directory'),
   selectFiles: (options?: { accept?: string; multiple?: boolean }) => invoke<string[] | null>('select_files', {
     accept: options?.accept ?? null,
     multiple: options?.multiple ?? true,
@@ -352,6 +379,8 @@ export const windows = {
     invoke<void>('unwatch_external_document', { leaseId }),
 };
 
+export type CloudEnvironment = 'staging' | 'prod';
+
 export interface ProductInfo {
   productName: string;
   version: string;
@@ -360,10 +389,14 @@ export interface ProductInfo {
   logDir: string;
   os: string;
   arch: string;
+  isDevBuild: boolean;
+  cloudEnvironment: CloudEnvironment;
 }
 
 export const product = {
   getInfo: () => invoke<ProductInfo>('get_product_info'),
+  setCloudEnvironment: (environment: CloudEnvironment) =>
+    invoke<void>('set_cloud_environment', { environment }),
   openLogDir: () => invoke<void>('open_log_dir'),
   revealInFileManager: (filePath: string) => invoke<void>('reveal_in_file_manager', { filePath }),
 };
@@ -507,8 +540,6 @@ export const plugins = {
     sourceNote?: string;
   }) => invoke<PluginRunStarted>('plugin_run', params),
   runStop: (runId: string) => invoke<boolean>('plugin_run_stop', { runId }),
-  resolveNote: (memoId: string) =>
-    invoke<PluginArtifact>('plugin_resolve_note', { memoId }),
 };
 
 export const artifacts = {
diff --git a/app/flowix-web/platform/tauri/client/general.ts b/app/flowix-web/platform/tauri/client/general.ts
index 20406f0d1..cd6028283 100644
--- a/app/flowix-web/platform/tauri/client/general.ts
+++ b/app/flowix-web/platform/tauri/client/general.ts
@@ -1,6 +1,6 @@
 import { invoke } from '@tauri-apps/api/core';
 import type { UserSettings } from '@/lib/constants';
-import type { AgentAccessConfig, AgentAccessEntry } from '@/lib/types/agent-access';
+import type { AgentWorkspaceSnapshot } from '@/lib/types/agent-workspace';
 import type { UsageInfo } from '@/types/agent';
 import type { AgentConfig, TestConnectionResult } from './agent';
 
@@ -13,13 +13,14 @@ export const preferences = {
 export interface BootFeatures {
   experimental: boolean;
   isIntroductDisplayed: boolean;
-  isOnboardingCompleted: boolean;
 }
 
 export const boot = {
   getFeatures: () => invoke<BootFeatures>('get_boot_features'),
-  setIntroDisplayed: () => invoke<void>('set_boot_intro_displayed'),
-  setOnboardingCompleted: () => invoke<void>('set_boot_onboarding_completed'),
+  getVersionInitializationCompleted: () => invoke<boolean>('get_version_initialization_completed'),
+  setVersionInitializationCompleted: (completed: boolean) =>
+    invoke<void>('set_version_initialization_completed', { completed }),
+  retryStartup: () => invoke<void>('retry_startup'),
   getStartupStatus: () => invoke<StartupStatus>('get_startup_status'),
   getStartupNotebookId: () => invoke<string | null>('get_startup_notebook_id'),
   notifyStartupInteractive: () => invoke<void>('notify_startup_interactive'),
@@ -32,8 +33,11 @@ export type StartupPhase = 'pending' | 'running' | 'ready' | 'failed';
 
 export interface StartupStatus {
   phase: StartupPhase;
+  /** Optional only for compatibility with older native shells. */
+  stage?: 'initialization' | 'workspacePreparation';
   step: string;
   error: string | null;
+  progress?: { percent: number; completed: number; total: number; task: string } | null;
 }
 
 export interface FontCacheStatus {
@@ -125,6 +129,9 @@ export const deepseekHarness = {
 export interface PiModelEntryConfig {
   id: string;
   name: string;
+  subtitle?: string;
+  creditMultiplier?: number;
+  providerIconUrl?: string;
   api?: string;
   reasoning: boolean;
   vision: boolean;
@@ -135,8 +142,11 @@ export interface PiModelEntryConfig {
 export interface PiProviderConfig {
   id: string;
   displayName: string;
+  iconUrl?: string;
   api: string;
   baseUrl: string;
+  /** Set for providers managed by Flowix Cloud. */
+  source?: string;
   /** Write-only. Empty preserves the credential already saved for this provider. */
   apiKey?: string;
   credentialConfigured: boolean;
@@ -144,7 +154,7 @@ export interface PiProviderConfig {
   models: PiModelEntryConfig[];
 }
 
-export interface PiFeatures { codeMode: boolean; toolSearch: boolean }
+export interface PiFeatures { toolSearch: boolean; legacyCodeMode?: boolean }
 
 export interface PiMcpServerConfig {
   name: string;
@@ -169,7 +179,8 @@ export interface PiModelCatalog {
 
 export const piModels = {
   getFeatures: () => invoke<PiFeatures>('get_pi_features'),
-  saveFeatures: (features: PiFeatures) => invoke<void>('save_pi_features', { features }),
+  saveFeatures: (features: Pick<PiFeatures, 'toolSearch'>) => invoke<void>('save_pi_features', { features }),
+  clearLegacyCodeMode: () => invoke<void>('clear_pi_legacy_code_mode'),
   list: () => invoke<PiProviderConfig[]>('get_pi_model_configs'),
   catalog: () => invoke<PiModelCatalog>('get_pi_model_catalog'),
   save: (config: PiProviderConfig) => invoke<void>('save_pi_model_config', { config }),
@@ -187,6 +198,10 @@ export const piMcp = {
 
 export interface DshIntegrationStatus {
   installed: boolean;
+  localInstalled: boolean;
+  managedInstalled: boolean;
+  appServerProfileInstalled: boolean;
+  appServerProfileUpdateAvailable: boolean;
   executablePath?: string | null;
   version?: string | null;
   harnessVersion?: string | null;
@@ -196,30 +211,12 @@ export interface DshIntegrationStatus {
   archiveSize?: number | null;
 }
 
-export interface DshDownloadProgress {
-  phase: 'checking' | 'downloading' | 'downloaded' | 'installing' | 'installed' | 'up-to-date' | 'cancelled' | 'failed';
-  downloadedBytes: number;
-  totalBytes?: number | null;
-  percent?: number | null;
-  resumed: boolean;
-}
-
-export interface DshUpdateCheck {
-  currentVersion?: string | null;
-  latestVersion?: string | null;
-  updateAvailable: boolean;
-}
-
 export const dshIntegration = {
   status: () => invoke<DshIntegrationStatus>('dsh_status'),
-  checkUpdate: () => invoke<DshUpdateCheck>('dsh_check_update'),
-  archiveSize: () => invoke<number | null>('dsh_archive_size'),
-  downloadStatus: () => invoke<DshDownloadProgress | null>('dsh_download_status'),
-  installRuntime: () => invoke<DshIntegrationStatus>('dsh_install_runtime'),
-  updateRuntime: () => invoke<DshIntegrationStatus>('dsh_update'),
-  ensureRuntime: () => invoke<DshIntegrationStatus>('dsh_ensure_runtime'),
-  cancelUpdate: () => invoke<boolean>('dsh_cancel_update'),
-  uninstallRuntime: () => invoke<DshIntegrationStatus>('dsh_uninstall'),
+  selectCliPath: () => invoke<string | null>('dsh_select_cli_path'),
+  setCliPath: (path: string) => invoke<DshIntegrationStatus>('dsh_set_cli_path', { path }),
+  installAppServerProfile: () =>
+    invoke<DshIntegrationStatus>('dsh_install_appserver_profile'),
 };
 
 function snapshotFromHarnessUsage(
@@ -303,27 +300,13 @@ export interface DeepSeekHarnessPluginCatalog {
   profile: DeepSeekHarnessPlugin[];
 }
 
-// Agent access roots (backend ~/.flowix/agent-access.json).
-// Source of truth is `agent_access::AgentAccessStore`; it mirrors notebooks and user-added folders.
-// 鏁翠唤 set 鏇夸唬閫愭潯 patch, 閬垮厤鍓嶇瀵瑰崟鏉?entry 绠?diff; 鍐欐椂璧颁箰瑙傛洿鏂?
-// (鏈湴鍏堟敼, 澶辫触 `loadInitial` 鍥炴粴)銆?
-export const agentAccess = {
-  get: () => invoke<AgentAccessConfig>('get_agent_access'),
-  set: (config: AgentAccessConfig) => invoke<void>('set_agent_access', { config }),
-  addFolderFromPicker: () =>
-    invoke<AgentAccessEntry | null>('add_agent_access_folder_from_picker'),
-  getNotebookConfigs: () =>
-    invoke<Record<string, import('@/lib/types/agent-access').NotebookAgentConfig>>(
-      'get_notebook_agent_configs',
-    ),
-  setNotebookConfig: (
-    notebookId: string,
-    expectedRevision: number,
-    config: import('@/lib/types/agent-access').NotebookAgentConfig,
-  ) => invoke<import('@/lib/types/agent-access').NotebookAgentConfig>(
-    'set_notebook_agent_config',
-    { notebookId, expectedRevision, config },
-  ),
+// Device-local notebook workspaces. Mutations change one attachment atomically.
+export const agentWorkspace = {
+  get: () => invoke<AgentWorkspaceSnapshot>('get_agent_workspace'),
+  getLegacyPreferences: () => invoke<import('@/lib/types/agent-workspace').LegacyAgentRuntimePreferences | null>('get_legacy_agent_preferences'),
+  pickDirectory: (notebookId: string) => invoke<AgentWorkspaceSnapshot | null>('pick_notebook_directory', { notebookId }),
+  attachDirectory: (notebookId: string, path: string) => invoke<AgentWorkspaceSnapshot>('attach_notebook_directory', { notebookId, path }),
+  detachDirectory: (notebookId: string, path: string) => invoke<AgentWorkspaceSnapshot>('detach_notebook_directory', { notebookId, path }),
 };
 
 export interface SystemTagLayoutItem {
diff --git a/app/flowix-web/platform/tauri/client/memos.ts b/app/flowix-web/platform/tauri/client/memos.ts
index e6a71c6a1..e6fef5457 100644
--- a/app/flowix-web/platform/tauri/client/memos.ts
+++ b/app/flowix-web/platform/tauri/client/memos.ts
@@ -12,7 +12,7 @@ export interface NotebookTemplateRecord {
   coverUrl?: string;
 }
 
-/** Memo-ID tag summary and compatibility IPC. Path-based note operations live in `notes`. */
+/** Tag summary and memo events. Path-based note operations live in `notes`. */
 export const memos = {
   getUsedTagIds: (notebookId?: string) =>
     invoke<{
@@ -32,8 +32,8 @@ export type ExternalDocumentWriteOutcome =
   | { status: 'error'; message: string };
 
 export const externalDocuments = {
-  mimeType: (filePath: string) =>
-    invoke<string>('get_external_document_mime_type', { filePath }),
+  detectTextContent: (filePath: string, scopePath?: string | null) =>
+    invoke<boolean>('detect_external_document_text', { filePath, scopePath: scopePath ?? null }),
   openWithDefaultApp: (filePath: string, scopePath?: string | null) =>
     invoke<void>('open_file_with_default_app', { filePath, scopePath: scopePath ?? null }),
   read: (filePath: string, scopePath?: string | null, maxBytes?: number) =>
@@ -55,8 +55,6 @@ export const externalDocuments = {
 export const tags = {
   getAll: (notebookId?: string) =>
     invoke<{ tags: { id: string; name: string }[] }>('get_all_tags', { notebookId }),
-  create: (notebookId: string, path: string) =>
-    invoke<{ path: string }>('create_notebook_tag', { notebookId, path }),
   /**
    * 移动 subtag: 把 `oldPath` 整棵子树重命名 (含 prefix 替换), 批量
    * 改写所有受影响 memo 的 YAML `tags` + 同步 memo index。
@@ -94,6 +92,22 @@ export interface NotebookSortEntry {
   sort: number;
 }
 
+export interface NotebookBackgroundStatus {
+  notebookId: string;
+  state: 'queued' | 'running' | 'ready' | 'failed';
+  revision: number;
+  memoCount?: number;
+  missing?: boolean;
+  message: string | null;
+}
+
+export interface NotebookMediaMaintenanceStatus {
+  notebookId: string;
+  state: 'queued' | 'running' | 'ready' | 'failed';
+  revision: number;
+  message: string | null;
+}
+
 export interface NotebookRecord {
   id: string;
   name: string;
@@ -105,10 +119,12 @@ export interface NotebookRecord {
   updatedAt: number;
   isDefault: boolean;
   sort?: number;
+  pinned?: boolean;
   missing?: boolean;
 }
 
 export type NotebookSetupJobStatus = 'pending' | 'running' | 'completed' | 'partial' | 'failed';
+export type NotebookSetupStage = 'preparing' | 'writing' | 'indexing' | 'completed';
 
 export interface NotebookSetupReport {
   totalFiles: number;
@@ -121,19 +137,32 @@ export interface NotebookSetupReport {
 
 export interface NotebookSetupJob {
   notebookId: string;
+  jobId: string;
   templateId: string | null;
   overwriteExisting: boolean;
   status: NotebookSetupJobStatus;
-  stage: string;
-  completedFiles: number;
-  totalFiles: number;
+  stage: NotebookSetupStage;
+  revision: number;
+  runId: string;
   message: string | null;
   report: NotebookSetupReport | null;
   updatedAt: number;
+  executionRequested: boolean;
+}
+
+export interface NotebookSetupSnapshot {
+  revision: number;
+  jobs: NotebookSetupJob[];
 }
 
 export const notebooks = {
   getAll: () => invoke<NotebookRecord[]>('get_notebooks'),
+  setPinned: (notebookId: string, pinned: boolean) =>
+    invoke<boolean>('set_notebook_pinned', { notebookId, pinned }),
+  getBackgroundStatus: () => invoke<NotebookBackgroundStatus[]>('get_notebook_background_status'),
+  refreshIndex: (notebookId: string) => invoke<void>('request_notebook_refresh', { notebookId }),
+  getMediaMaintenanceStatus: () => invoke<NotebookMediaMaintenanceStatus[]>('get_notebook_media_maintenance_status'),
+  retryMediaMaintenance: (notebookId: string) => invoke<void>('request_notebook_media_maintenance', { notebookId }),
   listTemplates: () => invoke<NotebookTemplateRecord[]>('list_notebook_templates'),
   getDefaultPath: (name: string) =>
     invoke<string>('get_default_notebook_path', { name }),
@@ -166,8 +195,12 @@ export const notebooks = {
     invoke<NotebookSetupJob | null>('get_notebook_template_setup_status', { notebookId }),
   startTemplateSetup: (notebookId: string, retry = false) =>
     invoke<NotebookSetupJob | null>('start_notebook_template_setup', { notebookId, retry }),
-  createFromCloud: (id: string, name: string, path: string, icon?: string | null) =>
-    invoke<NotebookRecord>('create_notebook_from_cloud', { id, name, path, icon }),
+  startOrResumeReadyTemplateSetups: (activeNotebookId: string | null) =>
+    invoke<void>('start_or_resume_ready_notebook_template_setups', { activeNotebookId }),
+  getTemplateSetupSnapshot: () =>
+    invoke<NotebookSetupSnapshot>('get_notebook_template_setup_snapshot'),
+  createFromCloud: (id: string, name: string, path: string, icon?: string | null, activate = true) =>
+    invoke<NotebookRecord>('create_notebook_from_cloud', { id, name, path, icon, activate }),
   startImport: (notebookId: string) =>
     invoke<void>('start_notebook_import', { notebookId }),
   getImportStatus: (notebookId: string) =>
diff --git a/app/flowix-web/platform/tauri/client/notes.ts b/app/flowix-web/platform/tauri/client/notes.ts
index 6baf90b75..d80cb11a2 100644
--- a/app/flowix-web/platform/tauri/client/notes.ts
+++ b/app/flowix-web/platform/tauri/client/notes.ts
@@ -1,7 +1,8 @@
+import { publishNotebookPathCreated, publishNotebookPathMove, type NotebookPathCreated, type NotebookPathMove } from '../notebook-change-events';
 import { invokeDocumentMutation } from './document-mutation';
 import { invoke } from '@tauri-apps/api/core';
 import type { NoteColor } from '@/types/note-item';
-import type { MemoContentCommit } from '@/types/memo';
+import type { NoteContentCommit } from '@/types/memo';
 
 export type FilterType = 'all' | 'todos' | 'agents' | 'favorited' | 'tagged' | 'thisWeek' | 'thisMonth';
 export type SortType = 'createdAt' | 'updatedAt' | 'filenameAsc' | 'filenameDesc';
@@ -36,6 +37,17 @@ export interface CreatedNoteDocument {
   path: string;
   initialContent: string;
   entry: NoteEntry;
+  notebookChange?: NotebookPathCreated;
+}
+
+function publishCreatedNote(result: CreatedNoteDocument): CreatedNoteDocument {
+  // Older desktop processes return the path result without a change receipt.
+  // The command result still confirms creation, so refresh this window locally.
+  publishNotebookPathCreated(result.notebookChange ?? {
+    notebookId: result.notebookId,
+    relativePath: result.relativePath,
+  });
+  return result;
 }
 
 export interface MarkdownLocation {
@@ -87,21 +99,21 @@ export const notes = {
     invoke<MarkdownLocation>('resolve_markdown_location', { filePath }),
   readDocument: (filePath: string) => invoke<string | null>('read_document', { filePath }),
   writeDocument: (params: { filePath: string; content: string; expectedContent?: string }) =>
-    invokeDocumentMutation<({ path: string; content: string } & MemoContentCommit) | null>('write_document', {
+    invokeDocumentMutation<({ path: string; content: string } & NoteContentCommit) | null>('write_document', {
       filePath: params.filePath,
       content: params.content,
       expectedContent: params.expectedContent,
     }),
   modifiedAt: (filePath: string) => invoke<number | null>('get_document_modified_at', { filePath }),
   renameTitle: (params: { filePath: string; title: string; expectedFilename?: string; expectedContent: string }) =>
-    invokeDocumentMutation<{ path: string; filename: string }>('rename_memo_title', {
+    invokeDocumentMutation<{ path: string; filename: string; notebookChange: NotebookPathMove }>('rename_memo_title', {
       filePath: params.filePath,
       title: params.title,
       expectedFilename: params.expectedFilename,
       expectedContent: params.expectedContent,
-    }),
+    }).then((result) => { publishNotebookPathMove(result.notebookChange); return result; }),
   moveToDirectory: (filePath: string, notebookId: string, parentRelativePath: string) =>
-    invoke<{ path: string }>('move_memo_to_directory', { filePath, notebookId, parentRelativePath }),
+    invoke<{ path: string; notebookChange: NotebookPathMove }>('move_memo_to_directory', { filePath, notebookId, parentRelativePath }).then((result) => { publishNotebookPathMove(result.notebookChange); return result; }),
   list: (notebookId: string) => invoke<NoteEntry[]>('list_notes_by_path', { notebookId }),
   getIndexed: (notebookId: string, relativePath: string) =>
     invoke<NoteEntry | null>('get_indexed_note_by_path', { notebookId, relativePath }),
@@ -129,14 +141,17 @@ export const notes = {
   pruneMissing: (filePath: string) => invoke<PruneMissingNoteOutcome>('prune_missing_memo', { filePath }),
   /** Omitted parent uses the notebook's default create folder; '' explicitly targets the notebook root. */
   create: (notebookId: string, tag?: string, parentRelativePath?: string, title?: string) =>
-    invoke<CreatedNoteDocument>('add_path_document', { tag, notebookId, parentRelativePath, title }),
+    invoke<CreatedNoteDocument>('add_path_document', { tag, notebookId, parentRelativePath, title })
+      .then(publishCreatedNote),
   createFromTemplate: (templateId: string, notebookId: string) =>
-    invoke<CreatedNoteDocument>('create_path_from_template', { templateId, notebookId }),
+    invoke<CreatedNoteDocument>('create_path_from_template', { templateId, notebookId })
+      .then(publishCreatedNote),
   listTemplates: () => invoke<NoteTemplate[]>('list_memo_templates'),
   saveTemplate: (title: string, content: string) => invoke<NoteTemplate>('save_memo_template', { title, content }),
   deleteTemplate: (templateId: string) => invoke<boolean>('delete_memo_template', { templateId }),
   importDocument: (filePath: string, content: string, notebookId: string) =>
-    invoke<CreatedNoteDocument>('import_external_document_by_path', { filePath, content, notebookId }),
+    invoke<CreatedNoteDocument>('import_external_document_by_path', { filePath, content, notebookId })
+      .then(publishCreatedNote),
   listVersions: (notebookId: string, relativePath: string) =>
     invoke<PathVersionMeta[]>('list_path_versions', { notebookId, relativePath }),
   listArchives: () => invoke<PathArchiveSummary[]>('list_local_path_archives'),
diff --git a/app/flowix-web/platform/tauri/client/updater.ts b/app/flowix-web/platform/tauri/client/updater.ts
index 73996ad74..141801eaf 100644
--- a/app/flowix-web/platform/tauri/client/updater.ts
+++ b/app/flowix-web/platform/tauri/client/updater.ts
@@ -65,6 +65,7 @@ export async function consumeAppUpdateResult(): Promise<AppUpdateInstallResult |
 }
 
 export async function installAppUpdate(
+  version: string,
   onProgress?: (progress: AppUpdateDownloadProgress) => void,
 ): Promise<void> {
   if (installPromise) return installPromise;
@@ -75,7 +76,7 @@ export async function installAppUpdate(
       onProgress?.(event.payload);
     });
     try {
-      await invoke('install_app_update');
+      await invoke('install_app_update', { version });
       await relaunch();
     } finally {
       await unlisten();
@@ -92,3 +93,5 @@ export async function installAppUpdate(
 export async function cancelAppUpdate(): Promise<boolean> {
   return await invoke<boolean>('cancel_app_update');
 }
+
+export { relaunch };
diff --git a/app/flowix-web/platform/tauri/errors.ts b/app/flowix-web/platform/tauri/errors.ts
index 493497e42..ea566adf6 100644
--- a/app/flowix-web/platform/tauri/errors.ts
+++ b/app/flowix-web/platform/tauri/errors.ts
@@ -1,5 +1,9 @@
 import type { I18nKey, I18nParams } from '@/lib/i18n';
 
+const FLOWIX_MEMBERSHIP_ERROR =
+  /^\s*(?:Error:\s*)?cloud API error\s+403\s+MEMBERSHIP_REQUIRED\b/i;
+const FLOWIX_REQUEST_ID = /\(request id:\s*([a-z\d_-]+)\s*\)/i;
+
 /**
  * Tauri IPC 错误格式化。
  *
@@ -74,6 +78,15 @@ function cloudErrorDetails(message: string): Record<string, unknown> {
 
 export function cloudSyncErrorMessage(error: unknown, t: Translate): string {
   const message = tauriErrorMessage(error);
+  if (['CHECKOUT_IN_PROGRESS', 'CHECKOUT_CREATION_IN_PROGRESS', 'CHECKOUT_PAYMENT_PROCESSING'].some((code) => hasTauriErrorCode(error, code))) {
+    return t('preferences.cloud.order.pendingCheckout');
+  }
+  if (hasTauriErrorCode(error, 'BILLING_RATE_LIMITED')) {
+    return t('preferences.cloud.order.rateLimited');
+  }
+  if (hasTauriErrorCode(error, 'BILLING_RATE_LIMIT_NOT_CONFIGURED')) {
+    return t('preferences.cloud.order.checkUnavailable');
+  }
   if (message.includes('MEMBERSHIP_REQUIRED')) {
     return t('preferences.cloud.membershipRequired');
   }
@@ -88,6 +101,23 @@ export function cloudSyncErrorMessage(error: unknown, t: Translate): string {
   return message;
 }
 
+export function cloudModelAccessErrorMessage(error: unknown, t: Translate): string {
+  const message = tauriErrorMessage(error);
+  if (message.includes('INSUFFICIENT_CREDITS')) return t('agent.error.insufficientCredits');
+  if (message.includes('MODEL_NOT_FOUND')) return t('agent.error.cloudModelUnavailable');
+  if (message.includes('MODEL_PRICING_NOT_CONFIGURED')) return t('agent.error.cloudPricingUnavailable');
+  if (!FLOWIX_MEMBERSHIP_ERROR.test(message)) return message;
+
+  const userMessage = t('agent.error.membershipRequired');
+  const requestId = message.match(FLOWIX_REQUEST_ID)?.[1];
+  if (!requestId) return userMessage;
+
+  return [
+    userMessage,
+    t('agent.error.diagnostic.reference', { value: requestId }),
+  ].join('\n\n');
+}
+
 export function notebookCreateErrorMessage(error: unknown, t: Translate): string {
   const templateFailure = notebookTemplateFileFailure(error);
   if (templateFailure) {
diff --git a/app/flowix-web/platform/tauri/event-bus.ts b/app/flowix-web/platform/tauri/event-bus.ts
index 0a0e06fef..c313c9c86 100644
--- a/app/flowix-web/platform/tauri/event-bus.ts
+++ b/app/flowix-web/platform/tauri/event-bus.ts
@@ -1,12 +1,8 @@
 /**
  * 前端事件总线 — 统一收口 `@tauri-apps/api/event` 的 `listen<T>(name, cb)`。
  *
- * 背景: 项目里后端发了多 channel 事件 (memo-event / agent-chunk /
- * user-config-changed / agent-access-changed / flowix:open-target), 此前
- * 每个 channel 自己写 "模块级 unlisten 单例 + 重复挂载短路" 样板
- * (client.ts 的 `streamUnlisten` / `userConfigUnlisten` / `agentAccessUnlisten`、
- * openByTarget/listener.ts 的 `unlisten`、useMemoEvents 的 `disposed` 互斥)。
- * 同形逻辑散在 4 处, 改一处就得手工同步 4 处。
+ * 后端事件经此适配层共享 Tauri listener。业务层可独立订阅同名事件，
+ * 底层仅保留一个 listener，并在最后一个订阅者离开时释放。
  *
  * 设计:
  * - `subscribe<T>(event, handler): UnlistenFn` — 同名事件只挂 1 个 Tauri
@@ -23,11 +19,9 @@
  * - 单例状态模块级, 跨 hook 共享 (跟原 client.ts 设计一致)。 进程退出
  *   Tauri 自动清理, 这里不提供 `shutdown`。
  *
- * 迁移: client.ts 的 `listenToAgentStream` / `listenToUserConfigChanges` /
- * `listenToAgentAccessChanges` / `stopListeningTo*` 内部都改走本模块。
- * openByTarget/listener.ts 的 `mountOpenTargetListener` / `unmount` 也走
- * 同一接口。 useMemoEvents 用 `subscribe` 替换内联 `listen` + `disposed`
- * 样板, useEffect cleanup 直接调 unsubscribe。
+ * 应用层的 memo-event 桥接、open-target 监听和客户端事件适配都通过
+ * `subscribe` 管理生命周期；外部文档 watcher 还会在领域层合并文件 lease，
+ * 再把事件分发到该文件的各个视图。
  *
  * 类型安全: handler 入参是 `event.payload` (T), 生命周期通知通过类型化的
  * SubscribeOptions 暴露。
diff --git a/app/flowix-web/platform/tauri/notebook-change-events.ts b/app/flowix-web/platform/tauri/notebook-change-events.ts
new file mode 100644
index 000000000..151994c4c
--- /dev/null
+++ b/app/flowix-web/platform/tauri/notebook-change-events.ts
@@ -0,0 +1,122 @@
+import { subscribe, type SubscribeOptions, type UnlistenFn } from './event-bus';
+import { createLogger } from '@/lib/logger';
+
+/** Compatibility payload. Only this boundary interprets the legacy optional fields. */
+interface PathNoteChangedPayload {
+  changeId?: string;
+  notebookId: string;
+  relativePath?: string;
+  previousRelativePath?: string;
+  created?: boolean;
+  directory?: boolean;
+  deleted?: boolean;
+  source?: 'external_tool';
+  originWindowLabel?: string;
+}
+
+export type NotebookPathMove = {
+  changeId: string;
+  notebookId: string;
+  previousRelativePath: string;
+  relativePath: string;
+  directory: boolean;
+};
+
+export type NotebookPathCreated = {
+  changeId?: string;
+  notebookId: string;
+  relativePath: string;
+  source?: 'external_tool';
+  originWindowLabel?: string;
+};
+
+export interface PathMutationResult {
+  path: string;
+  notebookChange?: NotebookPathMove | null;
+}
+
+export type NotebookChange = (
+  | { kind: 'path-moved'; notebookId: string; relativePath: string; previousRelativePath: string; directory: boolean }
+  | { kind: 'resource-created'; notebookId: string; relativePath: string; source?: 'external_tool'; originWindowLabel?: string }
+  | { kind: 'resource-deleted'; notebookId: string; relativePath: string }
+  | { kind: 'query-invalidated'; notebookId: string; relativePath: string | null }
+) & { changeId?: string };
+
+const localHandlers = new Set<(change: NotebookChange) => void>();
+const logger = createLogger('notebook-change');
+
+/** Command receipts use the same subscription and dedup boundary as broadcasts. */
+export function publishNotebookQueryInvalidated(notebookId: string): void {
+  for (const handler of [...localHandlers]) {
+    try { handler({ kind: 'query-invalidated', notebookId, relativePath: null }); }
+    catch (error) { logger.warn('apply notebook refresh failed', { error, notebookId }); }
+  }
+}
+
+export function publishNotebookPathMove(change: NotebookPathMove | null | undefined): void {
+  if (!change) return;
+  for (const handler of [...localHandlers]) {
+    try { handler({ ...change, kind: 'path-moved' }); }
+    catch (error) { logger.warn('apply command path move failed', { error, changeId: change.changeId }); }
+  }
+}
+
+export function publishNotebookPathCreated(change: NotebookPathCreated | null | undefined): void {
+  if (!change) return;
+  for (const handler of [...localHandlers]) {
+    try { handler({ ...change, kind: 'resource-created' }); }
+    catch (error) { logger.warn('apply command path create failed', { error, changeId: change.changeId }); }
+  }
+}
+
+export function acceptPathMutationResult(result: string | PathMutationResult): string {
+  // Frontend HMR can precede the Rust process restart during development.
+  if (typeof result === 'string') return result;
+  if (result.notebookChange) publishNotebookPathMove(result.notebookChange);
+  return result.path;
+}
+
+/** A path notification without a confirmed move/delete is only an invalidation,
+ * not evidence that document content changed. Empty paths invalidate the notebook.
+ */
+export function normalizeNotebookChange(payload: PathNoteChangedPayload): NotebookChange {
+  const { notebookId, relativePath, previousRelativePath } = payload;
+  if (relativePath && payload.created) {
+    return {
+      kind: 'resource-created', notebookId, relativePath, source: payload.source,
+      originWindowLabel: payload.originWindowLabel, changeId: payload.changeId,
+    };
+  }
+  if (relativePath && payload.deleted) {
+    return { kind: 'resource-deleted', notebookId, relativePath, changeId: payload.changeId };
+  }
+  if (relativePath && previousRelativePath && relativePath !== previousRelativePath) {
+    return {
+      kind: 'path-moved', notebookId, relativePath, previousRelativePath, changeId: payload.changeId,
+      directory: payload.directory === true,
+    };
+  }
+  return { kind: 'query-invalidated', notebookId, relativePath: relativePath || null };
+}
+
+export function subscribeNotebookChanges(
+  handler: (change: NotebookChange) => void,
+  options?: SubscribeOptions,
+): UnlistenFn {
+  // Per-consumer tracking: one consumer must not suppress delivery to another.
+  // Bound memory; path application must remain safe even after an ID is evicted.
+  const seen = new Set<string>();
+  const deliver = (change: NotebookChange) => {
+    if (change.changeId && seen.has(change.changeId)) return;
+    handler(change);
+    if (change.changeId) {
+      seen.add(change.changeId);
+      if (seen.size > 512) seen.delete(seen.values().next().value!);
+    }
+  };
+  localHandlers.add(deliver);
+  const stop = subscribe<PathNoteChangedPayload>('flowix:path-note-changed', (payload) => {
+    deliver(normalizeNotebookChange(payload));
+  }, options);
+  return () => { localHandlers.delete(deliver); stop(); };
+}
diff --git a/app/flowix-web/platform/tauri/window-close-region.test.ts b/app/flowix-web/platform/tauri/window-close-region.test.ts
new file mode 100644
index 000000000..13e0cec6d
--- /dev/null
+++ b/app/flowix-web/platform/tauri/window-close-region.test.ts
@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+const invoke = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+vi.mock('./core', () => ({ invoke }));
+import { registerWindowCloseRegion, subscribeNativeCloseRouting } from './window-close-region';
+let cleanups: Array<() => void> = [];
+beforeEach(() => {
+  invoke.mockClear();
+  vi.stubGlobal('ResizeObserver', class {
+    observe() {} disconnect() {}
+  });
+});
+afterEach(() => {
+  cleanups.forEach(cleanup => cleanup()); cleanups = [];
+  document.body.innerHTML = '';
+  vi.unstubAllGlobals();
+});
+function button() {
+  const element = document.createElement('button');
+  document.body.append(element);
+  element.getClientRects = () => ({ length: 1 }) as DOMRectList;
+  element.getBoundingClientRect = () => ({ right: window.innerWidth, top: 0, width: 42, height: 36 }) as DOMRect;
+  return element;
+}
+it('publishes the actual close-button rectangle in physical pixels', () => {
+  vi.stubGlobal('devicePixelRatio', 2);
+  cleanups.push(registerWindowCloseRegion(button()));
+  expect(invoke).toHaveBeenLastCalledWith('set_window_close_region', {
+    revision: expect.any(Number), region: { rightInset: 0, top: 0, width: 84, height: 72 },
+  });
+});
+it('keeps another mounted control active when an overlapping host unmounts', () => {
+  const disposeFirst = registerWindowCloseRegion(button());
+  const disposeSecond = registerWindowCloseRegion(button());
+  disposeSecond();
+  expect(invoke.mock.lastCall?.[1].region).not.toBeNull();
+  disposeFirst();
+  expect(invoke.mock.lastCall?.[1].region).toBeNull();
+  const revisions = invoke.mock.calls.map(([, args]) => args.revision);
+  expect(revisions).toEqual([...revisions].sort((a, b) => a - b));
+});
+it('reports native routing failure and recovery from the live health command', async () => {
+  vi.useFakeTimers();
+  invoke.mockImplementation((command: string) => Promise.resolve(
+    command === 'native_close_routing_ready' ? false : undefined,
+  ));
+  cleanups.push(registerWindowCloseRegion(button()));
+  const listener = vi.fn();
+  cleanups.push(subscribeNativeCloseRouting(listener));
+
+  await vi.advanceTimersByTimeAsync(2_000);
+  expect(listener).toHaveBeenLastCalledWith(false);
+
+  invoke.mockImplementation((command: string) => Promise.resolve(
+    command === 'native_close_routing_ready' ? true : undefined,
+  ));
+  await vi.advanceTimersByTimeAsync(2_000);
+  expect(listener).toHaveBeenLastCalledWith(true);
+});
diff --git a/app/flowix-web/platform/tauri/window-close-region.ts b/app/flowix-web/platform/tauri/window-close-region.ts
new file mode 100644
index 000000000..a74cd5779
--- /dev/null
+++ b/app/flowix-web/platform/tauri/window-close-region.ts
@@ -0,0 +1,93 @@
+/** Publishes the close-button region and reports native input-routing health. */
+import { invoke } from './core';
+import { createLogger } from '@/lib/logger';
+
+const buttons = new Set<HTMLElement>();
+let revision = 0;
+const log = createLogger('window:close-region');
+type RoutingListener = (ready: boolean) => void;
+const routingListeners = new Set<RoutingListener>();
+let routingTimer: ReturnType<typeof setTimeout> | undefined;
+let routingCheckInFlight = false;
+let nativeInputReady: boolean | undefined;
+let latestRegionPublished: boolean | undefined;
+let lastReportedAvailability: boolean | undefined;
+
+function reportAvailability() {
+  if (nativeInputReady === undefined) return;
+  const ready = nativeInputReady && latestRegionPublished === true;
+  if (ready === lastReportedAvailability) return;
+  lastReportedAvailability = ready;
+  routingListeners.forEach(listener => listener(ready));
+}
+
+function scheduleRoutingCheck(delay = 2_000) {
+  if (routingTimer !== undefined || routingListeners.size === 0) return;
+  routingTimer = setTimeout(() => {
+    routingTimer = undefined;
+    if (routingCheckInFlight || routingListeners.size === 0) return;
+    routingCheckInFlight = true;
+    void invoke<boolean>('native_close_routing_ready')
+      .then(ready => { nativeInputReady = ready; })
+      .catch(() => { nativeInputReady = false; })
+      .finally(() => {
+        routingCheckInFlight = false;
+        reportAvailability();
+        scheduleRoutingCheck();
+      });
+  }, delay);
+}
+
+function publish() {
+  const button = [...buttons].reverse().find(button => button.isConnected && button.getClientRects().length > 0);
+  const bounds = button?.getBoundingClientRect();
+  const scale = window.devicePixelRatio || 1;
+  const region = bounds ? {
+    rightInset: Math.max(0, window.innerWidth - bounds.right) * scale,
+    top: bounds.top * scale,
+    width: bounds.width * scale,
+    height: bounds.height * scale,
+  } : null;
+  const publishedRevision = ++revision;
+  void invoke('set_window_close_region', { revision: publishedRevision, region })
+    .then(() => {
+      if (publishedRevision === revision) {
+        latestRegionPublished = true;
+        reportAvailability();
+      }
+    })
+    .catch(() => {
+      if (publishedRevision === revision) {
+        latestRegionPublished = false;
+        reportAvailability();
+      }
+      log.error('native close region registration failed');
+    });
+}
+
+export function subscribeNativeCloseRouting(listener: RoutingListener): () => void {
+  routingListeners.add(listener);
+  if (lastReportedAvailability !== undefined) listener(lastReportedAvailability);
+  scheduleRoutingCheck();
+  return () => {
+    routingListeners.delete(listener);
+    if (routingListeners.size === 0 && routingTimer !== undefined) {
+      clearTimeout(routingTimer);
+      routingTimer = undefined;
+    }
+  };
+}
+
+export function registerWindowCloseRegion(button: HTMLElement): () => void {
+  buttons.add(button);
+  const observer = new ResizeObserver(publish);
+  observer.observe(button);
+  window.addEventListener('resize', publish);
+  publish();
+  return () => {
+    observer.disconnect();
+    window.removeEventListener('resize', publish);
+    buttons.delete(button);
+    publish();
+  };
+}
diff --git a/app/flowix-web/shared/drag-drop/drag-drop-coordinator.ts b/app/flowix-web/shared/drag-drop/drag-drop-coordinator.ts
new file mode 100644
index 000000000..0083171b9
--- /dev/null
+++ b/app/flowix-web/shared/drag-drop/drag-drop-coordinator.ts
@@ -0,0 +1,191 @@
+export interface DragPoint {
+  x: number;
+  y: number;
+}
+
+export interface DragPayload<Item = unknown> {
+  sessionId: string;
+  sourceId: string;
+  items: readonly Item[];
+}
+
+export type DropDecision =
+  | { accepted: true }
+  | { accepted: false; reason?: string };
+
+export interface DropPreview<Item, Location> {
+  payload: DragPayload<Item>;
+  location: Location;
+  decision: DropDecision;
+  point: DragPoint;
+}
+
+export interface DropTarget<Item, Location> {
+  /** Must be unique while this target is registered. */
+  id: string;
+  /** Higher priority wins when targets overlap. A rejected target still blocks lower-priority targets. */
+  priority?: number;
+  hitTest: (point: DragPoint) => Location | null;
+  locationKey: (location: Location) => string;
+  evaluate: (payload: DragPayload<Item>, location: Location) => DropDecision;
+  onPreview: (preview: DropPreview<Item, Location> | null) => void;
+  onDrop: (payload: DragPayload<Item>, location: Location) => void | Promise<void>;
+  onReject?: (payload: DragPayload<Item>, location: Location, reason?: string) => void;
+  onError: (error: unknown) => void;
+}
+
+interface ActiveDropTarget {
+  id: string;
+  key: string;
+  preview: DropPreview<unknown, unknown>;
+  target: DropTarget<unknown, unknown>;
+}
+
+interface ActiveDrag {
+  payload: DragPayload<unknown>;
+  point: DragPoint;
+  target: ActiveDropTarget | null;
+  onCancel?: () => void;
+  releaseTextSelection: () => void;
+}
+
+const targets = new Map<string, DropTarget<unknown, unknown>>();
+let activeDrag: ActiveDrag | null = null;
+let registrationOrder = 0;
+const targetOrder = new Map<string, number>();
+const DRAG_SELECTION_CLASS = 'flowix-drag-drop-active';
+let textSelectionSuppressionCount = 0;
+
+export function suppressTextSelectionForDrag(): () => void {
+  if (textSelectionSuppressionCount++ === 0 && typeof document !== 'undefined') {
+    document.documentElement.classList.add(DRAG_SELECTION_CLASS);
+    window.getSelection()?.removeAllRanges();
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    textSelectionSuppressionCount = Math.max(0, textSelectionSuppressionCount - 1);
+    if (textSelectionSuppressionCount === 0 && typeof document !== 'undefined') {
+      document.documentElement.classList.remove(DRAG_SELECTION_CLASS);
+    }
+  };
+}
+
+function findTarget(point: DragPoint, payload: DragPayload<unknown>): ActiveDropTarget | null {
+  const ordered = [...targets.values()].sort((left, right) => {
+    const priorityDifference = (right.priority ?? 0) - (left.priority ?? 0);
+    return priorityDifference || (targetOrder.get(right.id) ?? 0) - (targetOrder.get(left.id) ?? 0);
+  });
+  for (const target of ordered) {
+    const location = target.hitTest(point);
+    if (location === null) continue;
+    return {
+      id: target.id,
+      key: target.locationKey(location),
+      target,
+      preview: {
+        payload,
+        location,
+        decision: target.evaluate(payload, location),
+        point,
+      },
+    };
+  }
+  return null;
+}
+
+function clearTargetPreview(target: ActiveDropTarget | null): void {
+  target?.target.onPreview(null);
+}
+
+function updateTarget(drag: ActiveDrag): void {
+  const next = findTarget(drag.point, drag.payload);
+  const current = drag.target;
+  if (current && next && current.id === next.id && current.key === next.key
+    && current.preview.decision.accepted === next.preview.decision.accepted
+    && (current.preview.decision.accepted || (!next.preview.decision.accepted
+      && current.preview.decision.reason === next.preview.decision.reason))) {
+    return;
+  }
+  if (!current || !next || current.id !== next.id || current.key !== next.key) clearTargetPreview(current);
+  drag.target = next;
+  next?.target.onPreview(next.preview);
+}
+
+function clearActiveDrag(): ActiveDrag | null {
+  const previous = activeDrag;
+  activeDrag = null;
+  previous?.releaseTextSelection();
+  clearTargetPreview(previous?.target ?? null);
+  return previous;
+}
+
+function cancelOnEscape(event: KeyboardEvent): void {
+  if (event.key === 'Escape') cancelDragSession();
+}
+
+function cancelOnBlur(): void {
+  cancelDragSession();
+}
+
+export function registerDropTarget<Item, Location>(target: DropTarget<Item, Location>): () => void {
+  targets.set(target.id, target as unknown as DropTarget<unknown, unknown>);
+  targetOrder.set(target.id, ++registrationOrder);
+  if (activeDrag) updateTarget(activeDrag);
+  return () => {
+    if (targets.get(target.id) !== target) return;
+    targets.delete(target.id);
+    targetOrder.delete(target.id);
+    if (activeDrag?.target?.id === target.id) {
+      clearTargetPreview(activeDrag.target);
+      activeDrag.target = null;
+      updateTarget(activeDrag);
+    }
+  };
+}
+
+export function beginDragSession(
+  payload: DragPayload<unknown>,
+  point: DragPoint,
+  onCancel?: () => void,
+): void {
+  cancelDragSession();
+  activeDrag = { payload, point, target: null, onCancel, releaseTextSelection: suppressTextSelectionForDrag() };
+  window.addEventListener('keydown', cancelOnEscape);
+  window.addEventListener('blur', cancelOnBlur);
+  updateTarget(activeDrag);
+}
+
+export function moveDragSession(sessionId: string, point: DragPoint): void {
+  if (!activeDrag || activeDrag.payload.sessionId !== sessionId) return;
+  activeDrag.point = point;
+  updateTarget(activeDrag);
+}
+
+export function endDragSession(sessionId: string, point: DragPoint): boolean {
+  if (!activeDrag || activeDrag.payload.sessionId !== sessionId) return false;
+  activeDrag.point = point;
+  updateTarget(activeDrag);
+  const completed = clearActiveDrag();
+  window.removeEventListener('keydown', cancelOnEscape);
+  window.removeEventListener('blur', cancelOnBlur);
+  const target = completed?.target;
+  if (!target) return false;
+  if (!target.preview.decision.accepted) {
+    target.target.onReject?.(target.preview.payload, target.preview.location, target.preview.decision.reason);
+    return true;
+  }
+  void Promise.resolve()
+    .then(() => target.target.onDrop(target.preview.payload, target.preview.location))
+    .catch((error) => target.target.onError(error));
+  return true;
+}
+
+export function cancelDragSession(sessionId?: string): void {
+  if (!activeDrag || (sessionId !== undefined && activeDrag.payload.sessionId !== sessionId)) return;
+  const cancelled = clearActiveDrag();
+  window.removeEventListener('keydown', cancelOnEscape);
+  window.removeEventListener('blur', cancelOnBlur);
+  cancelled?.onCancel?.();
+}
diff --git a/app/flowix-web/shared/error-boundary.tsx b/app/flowix-web/shared/error-boundary.tsx
index cf448db4f..45ada90d8 100644
--- a/app/flowix-web/shared/error-boundary.tsx
+++ b/app/flowix-web/shared/error-boundary.tsx
@@ -42,6 +42,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 	componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
 		document.getElementById("app-loading")?.remove();
 		console.error("[ErrorBoundary] Caught error:", error, errorInfo);
+		console.error("[ErrorBoundary] Error stack:", error.stack ?? "<no stack>");
 		this.props.onError?.(error, errorInfo);
 	}
 
diff --git a/app/flowix-web/shared/ui/centered-loading-spinner.tsx b/app/flowix-web/shared/ui/centered-loading-spinner.tsx
index b713adc64..d57359295 100644
--- a/app/flowix-web/shared/ui/centered-loading-spinner.tsx
+++ b/app/flowix-web/shared/ui/centered-loading-spinner.tsx
@@ -20,7 +20,7 @@ export function CenteredLoadingSpinner({
     >
       <div className="flex flex-col items-center gap-3 text-sm text-[var(--muted-foreground)]">
         <div
-          className="h-5 w-5 animate-spin rounded-full border-2 border-[color-mix(in_oklch,var(--muted-foreground)_26%,transparent)] border-t-[var(--brand)]"
+          className="h-5 w-5 flowix-spin rounded-full border-2 border-[color-mix(in_oklch,var(--muted-foreground)_26%,transparent)] border-t-[var(--brand)]"
           aria-hidden="true"
         />
         {label && <span>{label}</span>}
diff --git a/app/flowix-web/shared/ui/context-menu.focus.test.tsx b/app/flowix-web/shared/ui/context-menu.focus.test.tsx
new file mode 100644
index 000000000..73cb93cca
--- /dev/null
+++ b/app/flowix-web/shared/ui/context-menu.focus.test.tsx
@@ -0,0 +1,183 @@
+import { act, useState, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
+import {
+  ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSubmenu, ContextMenuTrigger,
+} from './context-menu';
+
+let container: HTMLDivElement;
+let root: Root;
+let action: Mock<() => void>;
+
+async function render(items?: ReactNode) {
+  await act(async () => root.render(<>
+    <div data-testid="list"><ContextMenu>
+      <ContextMenuTrigger asChild><div data-testid="card">Note card</div></ContextMenuTrigger>
+      <ContextMenuContent>{items ?? <ContextMenuItem onClick={action}>Copy link</ContextMenuItem>}</ContextMenuContent>
+    </ContextMenu></div>
+    <div data-testid="editor" contentEditable suppressContentEditableWarning>Body text</div>
+    <input data-testid="outside" />
+  </>));
+}
+
+function element(selector: string) { return document.querySelector<HTMLElement>(selector)!; }
+function menu() { return element('[data-flowix-surface="context-menu"]'); }
+async function open() {
+  await act(async () => element('[data-testid="card"]').dispatchEvent(new MouseEvent('contextmenu', {
+    bubbles: true, cancelable: true, clientX: 10, clientY: 20,
+  })));
+}
+async function key(target: HTMLElement, value: string) {
+  await act(async () => target.dispatchEvent(new KeyboardEvent('keydown', { key: value, bubbles: true, cancelable: true })));
+}
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+  action = vi.fn();
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+  vi.restoreAllMocks();
+});
+
+describe('context menu focus and scroll ownership', () => {
+  it('takes DOM focus without scrolling and returns Escape focus to the card, not the editor', async () => {
+    await render();
+    const editor = element('[data-testid="editor"]');
+    editor.focus();
+    const editorFocus = vi.spyOn(editor, 'focus');
+    const card = element('[data-testid="card"]');
+    const cardFocus = vi.spyOn(card, 'focus');
+    const focus = vi.spyOn(HTMLElement.prototype, 'focus');
+    await open();
+    expect(document.activeElement).toBe(menu());
+    expect(focus).toHaveBeenCalledWith({ preventScroll: true });
+    await key(menu(), 'Escape');
+    expect(menu()).toBeNull();
+    expect(document.activeElement).toBe(card);
+    expect(cardFocus).toHaveBeenCalledWith({ preventScroll: true });
+    expect(editorFocus).not.toHaveBeenCalled();
+  });
+
+  it('executes the first action once despite sibling editor scroll between mousedown and click', async () => {
+    await render();
+    await open();
+    const item = menu().querySelector<HTMLButtonElement>('button')!;
+    await act(async () => {
+      item.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true, button: 0 }));
+      element('[data-testid="editor"]').dispatchEvent(new Event('scroll'));
+    });
+    expect(item.isConnected).toBe(true);
+    await act(async () => item.click());
+    expect(action).toHaveBeenCalledTimes(1);
+    expect(menu()).toBeNull();
+  });
+
+  it('does not dismiss when the menu itself scrolls', async () => {
+    await render();
+    await open();
+    await act(async () => menu().dispatchEvent(new Event('scroll')));
+    expect(menu()).not.toBeNull();
+  });
+
+  it.each(['[data-testid="list"]', 'document'])('dismisses when the trigger moves with %s scrolling', async (target) => {
+    await render();
+    await open();
+    await act(async () => (target === 'document' ? document : element(target)).dispatchEvent(new Event('scroll')));
+    expect(menu()).toBeNull();
+    expect(action).not.toHaveBeenCalled();
+  });
+
+  it('lets outside pointer targets take focus without restoring the editor or card', async () => {
+    await render();
+    await open();
+    const cardFocus = vi.spyOn(element('[data-testid="card"]'), 'focus');
+    const outside = element('[data-testid="outside"]');
+    await act(async () => {
+      outside.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+      outside.focus();
+    });
+    expect(menu()).toBeNull();
+    expect(document.activeElement).toBe(outside);
+    expect(cardFocus).not.toHaveBeenCalled();
+  });
+
+  it('preserves focus explicitly handed to a command destination', async () => {
+    await render(<ContextMenuItem onClick={() => element('[data-testid="outside"]').focus()}>Rename</ContextMenuItem>);
+    await open();
+    const cardFocus = vi.spyOn(element('[data-testid="card"]'), 'focus');
+    await act(async () => menu().querySelector<HTMLButtonElement>('button')!.click());
+    expect(document.activeElement).toBe(element('[data-testid="outside"]'));
+    expect(cardFocus).not.toHaveBeenCalled();
+  });
+
+  it('hands focus to a rename dialog mounted by the same action that closes the menu', async () => {
+    // Keep the dialog owner mounted outside ContextMenuContent's conditional DOM.
+    function RenameHarness() {
+      const [renaming, setRenaming] = useState(false);
+      return <><ContextMenu><ContextMenuTrigger asChild><div data-testid="card">Card</div></ContextMenuTrigger>
+        <ContextMenuContent><ContextMenuItem onClick={() => setRenaming(true)}>Rename</ContextMenuItem></ContextMenuContent>
+      </ContextMenu>{renaming && createPortal(<input autoFocus data-testid="rename" />, document.body)}</>;
+    }
+    await act(async () => root.render(<RenameHarness />));
+    await open();
+    await act(async () => menu().querySelector<HTMLButtonElement>('button')!.click());
+    expect(menu()).toBeNull();
+    expect(document.activeElement).toBe(element('[data-testid="rename"]'));
+  });
+
+  it('navigates enabled items and submenus without scrolling or closing the parent', async () => {
+    await render(<>
+      <ContextMenuItem disabled>Disabled</ContextMenuItem>
+      <ContextMenuItem onClick={action}>Copy</ContextMenuItem>
+      <ContextMenuSubmenu label="More"><ContextMenuItem onClick={action}>Nested copy</ContextMenuItem></ContextMenuSubmenu>
+    </>);
+    await open();
+    await key(menu(), 'ArrowDown');
+    expect(document.activeElement?.textContent).toBe('Copy');
+    await key(menu(), 'End');
+    const trigger = document.activeElement as HTMLElement;
+    expect(trigger.textContent).toBe('More');
+    await key(trigger, 'ArrowRight');
+    const submenu = element('[data-context-menu-submenu]');
+    expect(submenu.contains(document.activeElement)).toBe(true);
+    expect(document.activeElement?.textContent).toBe('Nested copy');
+    await act(async () => submenu.dispatchEvent(new Event('scroll')));
+    expect(menu()).not.toBeNull();
+    await key(document.activeElement as HTMLElement, 'Escape');
+    expect(element('[data-context-menu-submenu]')).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+    expect(menu()).not.toBeNull();
+    await key(trigger, 'Escape');
+    expect(menu()).toBeNull();
+  });
+
+  it('keeps the menu open for explicit keepOpenOnClick actions', async () => {
+    await render(<ContextMenuItem onClick={action} keepOpenOnClick>Toggle</ContextMenuItem>);
+    await open();
+    await act(async () => menu().querySelector<HTMLButtonElement>('button')!.click());
+    expect(action).toHaveBeenCalledTimes(1);
+    expect(menu()).not.toBeNull();
+  });
+
+  it('executes the first nested copy action once while the sibling editor scrolls', async () => {
+    await render(<ContextMenuSubmenu label="Copy"><ContextMenuItem onClick={action}>Copy link</ContextMenuItem></ContextMenuSubmenu>);
+    await open();
+    await key(menu(), 'ArrowDown');
+    await key(document.activeElement as HTMLElement, 'ArrowRight');
+    const item = element('[data-context-menu-submenu] [role="menuitem"]');
+    await act(async () => {
+      item.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true }));
+      element('[data-testid="editor"]').dispatchEvent(new Event('scroll'));
+    });
+    expect(item.isConnected).toBe(true);
+    await act(async () => item.click());
+    expect(action).toHaveBeenCalledOnce();
+    expect(menu()).toBeNull();
+    expect(document.activeElement).toBe(element('[data-testid="card"]'));
+  });
+});
diff --git a/app/flowix-web/shared/ui/context-menu.tsx b/app/flowix-web/shared/ui/context-menu.tsx
index 4320e5cfb..703fc6e79 100644
--- a/app/flowix-web/shared/ui/context-menu.tsx
+++ b/app/flowix-web/shared/ui/context-menu.tsx
@@ -6,13 +6,18 @@ import { POPUP_SEPARATOR_CLASS } from "@shared/ui/popup-separator";
 
 interface ContextMenuTriggerChildProps extends React.HTMLAttributes<HTMLElement> {}
 
+type ContextMenuCloseReason = 'select' | 'escape' | 'outside' | 'scroll' | 'resize' | 'replace' | 'tab';
+
 // Context for managing context-menu state. Position is captured at the moment
 // of the right-click, so the menu opens exactly at the cursor.
 interface ContextMenuContextValue {
 	open: boolean;
 	position: { x: number; y: number } | null;
 	setOpen: (open: boolean) => void;
-	openAt: (x: number, y: number) => void;
+	openAt: (x: number, y: number, trigger?: HTMLElement) => void;
+	triggerRef: React.RefObject<HTMLElement | null>;
+	menuId: string;
+	close: (reason: ContextMenuCloseReason) => void;
 }
 
 const ContextMenuContext = React.createContext<ContextMenuContextValue | null>(null);
@@ -35,10 +40,27 @@ function ContextMenu({ children, onOpenChange }: ContextMenuProps) {
 	const [open, setOpen] = React.useState(false);
 	const [position, setPosition] = React.useState<{ x: number; y: number } | null>(null);
 	const ownerRef = React.useRef({});
+	const triggerRef = React.useRef<HTMLElement | null>(null);
+	const menuId = React.useId();
 	const updateOpen = React.useCallback((nextOpen: boolean) => {
 		setOpen(nextOpen);
 		onOpenChange?.(nextOpen);
 	}, [onOpenChange]);
+	const close = React.useCallback((reason: ContextMenuCloseReason) => {
+		const active = document.activeElement;
+		const ownsFocus = active instanceof Element
+			&& active.closest('[data-context-menu-owner]')?.getAttribute('data-context-menu-owner') === menuId;
+		const trigger = triggerRef.current;
+		if (ownsFocus && trigger?.isConnected && (reason === 'escape' || reason === 'select' || reason === 'tab')) {
+			// Non-tabbable cards can receive programmatic return focus. Never
+			// restore the editor that happened to be active before right-click.
+			const temporaryTabIndex = trigger.tabIndex < 0 && !trigger.hasAttribute('tabindex');
+			if (temporaryTabIndex) trigger.setAttribute('tabindex', '-1');
+			trigger.focus({ preventScroll: true });
+			if (temporaryTabIndex) trigger.removeAttribute('tabindex');
+		}
+		updateOpen(false);
+	}, [menuId, updateOpen]);
 
 	// Context menus are rendered independently (for example, one per file-tree
 	// row), so coordinate them through a document-level event. Opening one menu
@@ -46,29 +68,27 @@ function ContextMenu({ children, onOpenChange }: ContextMenuProps) {
 	React.useEffect(() => {
 		const handleAnotherMenuOpen = (event: Event) => {
 			const owner = (event as CustomEvent<object>).detail;
-			if (owner !== ownerRef.current) updateOpen(false);
+			if (owner !== ownerRef.current) close('replace');
 		};
 		document.addEventListener(CONTEXT_MENU_OPEN_EVENT, handleAnotherMenuOpen);
 		return () => document.removeEventListener(CONTEXT_MENU_OPEN_EVENT, handleAnotherMenuOpen);
-	}, [updateOpen]);
+	}, [close]);
 
-	const openAt = React.useCallback((x: number, y: number) => {
+	const openAt = React.useCallback((x: number, y: number, trigger?: HTMLElement) => {
 		document.dispatchEvent(new CustomEvent(CONTEXT_MENU_OPEN_EVENT, {
 			detail: ownerRef.current,
 		}));
+		triggerRef.current = trigger ?? null;
 		setPosition({ x, y });
 		updateOpen(true);
 	}, [updateOpen]);
 
-	const close = React.useCallback(() => {
-		updateOpen(false);
-		// Keep the last position until the menu finishes its close animation; the
-		// content is unmounted when open is false so position becomes invisible
-		// to the user either way.
-	}, [updateOpen]);
+	const setMenuOpen = React.useCallback((nextOpen: boolean) => {
+		if (!nextOpen) close('select');
+	}, [close]);
 
 	return (
-		<ContextMenuContext.Provider value={{ open, position, setOpen: close, openAt }}>
+		<ContextMenuContext.Provider value={{ open, position, setOpen: setMenuOpen, openAt, triggerRef, menuId, close }}>
 			{children}
 		</ContextMenuContext.Provider>
 	);
@@ -90,7 +110,7 @@ function ContextMenuTrigger({ children, className, onContextMenu, asChild, ...pr
 		if (e.defaultPrevented) return;
 		e.preventDefault();
 		e.stopPropagation();
-		openAt(e.clientX, e.clientY);
+		openAt(e.clientX, e.clientY, e.currentTarget);
 	};
 
 	if (asChild && React.Children.count(children) === 1) {
@@ -118,9 +138,34 @@ interface ContextMenuContentProps {
 	style?: React.CSSProperties;
 }
 
+function menuItems(menu: HTMLElement): HTMLElement[] {
+	return Array.from(menu.querySelectorAll<HTMLElement>('[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]'))
+		.filter((item) => item.closest('[role="menu"]') === menu
+			&& !item.hasAttribute('disabled') && item.getAttribute('aria-disabled') !== 'true');
+}
+
+function navigateMenu(event: React.KeyboardEvent<HTMLDivElement>) {
+	if (event.defaultPrevented || !(event.target instanceof Element)
+		|| event.target.closest('[role="menu"]') !== event.currentTarget) return;
+	if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
+	event.preventDefault();
+	event.stopPropagation();
+	const items = menuItems(event.currentTarget);
+	if (!items.length) return;
+	const current = items.indexOf(document.activeElement as HTMLElement);
+	const index = event.key === 'Home' ? 0
+		: event.key === 'End' ? items.length - 1
+			: event.key === 'ArrowDown' ? (current + 1) % items.length
+				: current < 0 ? items.length - 1 : (current - 1 + items.length) % items.length;
+	items[index].focus({ preventScroll: true });
+}
+
 function ContextMenuContent({ children, className, style }: ContextMenuContentProps) {
-	const { open, position, setOpen } = useContextMenuContext();
+	const { open, position, triggerRef, menuId, close } = useContextMenuContext();
 	const contentRef = React.useRef<HTMLDivElement>(null);
+	React.useLayoutEffect(() => {
+		if (open) contentRef.current?.focus({ preventScroll: true });
+	}, [open, position]);
 
 	// Clamp the position so the menu never spills off-screen. The content can
 	// change size after opening (for example, a tree menu first renders a
@@ -172,32 +217,37 @@ function ContextMenuContent({ children, className, style }: ContextMenuContentPr
 		const handlePointerDown = (e: PointerEvent) => {
 			const target = e.target as Node;
 			if (contentRef.current?.contains(target)) return;
+			if (target instanceof Element && target.closest("[data-flowix-menu-child]")) return;
 			if (target instanceof Element && target.closest("[data-context-menu-submenu]")) return;
-			setOpen(false);
+			close('outside');
 		};
 
-		document.addEventListener("pointerdown", handlePointerDown);
-		return () => document.removeEventListener("pointerdown", handlePointerDown);
-	}, [open, setOpen]);
+		document.addEventListener("pointerdown", handlePointerDown, true);
+		return () => document.removeEventListener("pointerdown", handlePointerDown, true);
+	}, [open, close]);
 
 	// Close on Escape, scroll, or resize.
 	React.useEffect(() => {
 		if (!open) return;
 
 		const handleKeyDown = (e: KeyboardEvent) => {
-			if (e.key === "Escape") setOpen(false);
+			if (e.defaultPrevented) return;
+			if (e.key === 'Escape') {
+				e.preventDefault();
+				close('escape');
+			} else if (e.key === 'Tab') close('tab');
 		};
-		// scroll 触发场景里, 部分容器是"自身内容增长驱动的滚动" (例如 agent
-		// thread card 在 streaming 期间每帧 `body.scrollTop = scrollHeight`) ──
-		// 滚动事件是组件自身的内部行为, 不应牵连到全局右键菜单. 业务侧声明豁免
-		// 容器: 在元素上加 `data-no-context-menu-scroll`, 这里的 closest 命中即
-		// 跳过 setOpen(false)。`shared/ui/` 不依赖任何业务类名。
+		// A viewport-anchored menu only becomes stale when its trigger moves.
+		// Sibling editor scrolling and scrolling inside the menu cannot dismiss
+		// an in-flight pointer gesture before the menu item's click runs.
 		const handleScroll = (e: Event) => {
-			const target = e.target as Element | null;
-			if (target?.closest?.("[data-no-context-menu-scroll]")) return;
-			setOpen(false);
+			const target = e.target;
+			const trigger = triggerRef.current;
+			if (target instanceof Element && target.closest('[data-no-context-menu-scroll]')) return;
+			if (target === document || target === window
+				|| (target instanceof Element && trigger && target.contains(trigger))) close('scroll');
 		};
-		const handleResize = () => setOpen(false);
+		const handleResize = () => close('resize');
 
 		document.addEventListener("keydown", handleKeyDown);
 		window.addEventListener("scroll", handleScroll, true);
@@ -207,7 +257,7 @@ function ContextMenuContent({ children, className, style }: ContextMenuContentPr
 			window.removeEventListener("scroll", handleScroll, true);
 			window.removeEventListener("resize", handleResize);
 		};
-	}, [open, setOpen]);
+	}, [open, close, triggerRef]);
 
 	if (!open) return null;
 	if (typeof document === "undefined") return null;
@@ -216,7 +266,14 @@ function ContextMenuContent({ children, className, style }: ContextMenuContentPr
 		<div
 			ref={contentRef}
 			role="menu"
+			tabIndex={-1}
+			data-context-menu-owner={menuId}
 			data-flowix-surface="context-menu"
+			onKeyDown={navigateMenu}
+			onPointerDown={(event) => event.stopPropagation()}
+			onMouseDown={(event) => event.stopPropagation()}
+			onClick={(event) => event.stopPropagation()}
+			onFocus={(event) => event.stopPropagation()}
 			// Start at the cursor position; the layout effect above clamps
 			// these values once the element's true size is known.
 			style={{ left: position?.x ?? 0, top: position?.y ?? 0, ...style }}
@@ -239,6 +296,7 @@ interface ContextMenuItemProps {
 	onSelect?: () => void;
 	disabled?: boolean;
 	inset?: boolean;
+	keepOpenOnClick?: boolean;
 }
 
 function ContextMenuItem({
@@ -249,6 +307,7 @@ function ContextMenuItem({
 	onSelect,
 	disabled,
 	inset,
+	keepOpenOnClick = false,
 }: ContextMenuItemProps) {
 	const { setOpen } = useContextMenuContext();
 
@@ -257,18 +316,18 @@ function ContextMenuItem({
 		if (disabled) return;
 		onClick?.(e);
 		onSelect?.();
-		setOpen(false);
+		if (!keepOpenOnClick) setOpen(false);
 	};
 
 	return (
 		<button
 			type="button"
 			role="menuitem"
+			tabIndex={-1}
 			aria-describedby={ariaDescribedBy}
 			disabled={disabled}
 			onClick={handleClick}
 			onMouseDown={(e) => {
-				e.preventDefault();
 				e.stopPropagation();
 			}}
 			className={cn(
@@ -292,11 +351,13 @@ function ContextMenuSubmenu({
 	icon?: React.ReactNode;
 	children: React.ReactNode;
 }) {
+	const { menuId } = useContextMenuContext();
 	const [open, setOpen] = React.useState(false);
 	const [position, setPosition] = React.useState<{ left: number; top: number } | null>(null);
 	const triggerRef = React.useRef<HTMLButtonElement | null>(null);
 	const submenuRef = React.useRef<HTMLDivElement | null>(null);
 	const skipFocusOpenRef = React.useRef(false);
+	const focusFirstOnOpenRef = React.useRef(false);
 	const closeTimerRef = React.useRef<number | null>(null);
 
 	const cancelClose = () => {
@@ -312,6 +373,11 @@ function ContextMenuSubmenu({
 		}, 160);
 	};
 	React.useEffect(() => () => cancelClose(), []);
+	React.useLayoutEffect(() => {
+		if (!open || !focusFirstOnOpenRef.current || !submenuRef.current) return;
+		focusFirstOnOpenRef.current = false;
+		menuItems(submenuRef.current)[0]?.focus({ preventScroll: true });
+	}, [open]);
 
 	const alignToTrigger = React.useCallback((trigger: HTMLButtonElement) => {
 		const rect = trigger.getBoundingClientRect();
@@ -357,6 +423,7 @@ function ContextMenuSubmenu({
 			<button
 				type="button"
 				role="menuitem"
+				tabIndex={-1}
 				aria-haspopup="menu"
 				aria-expanded={open}
 				onMouseEnter={(event) => show(event.currentTarget)}
@@ -367,16 +434,20 @@ function ContextMenuSubmenu({
 					}
 					show(event.currentTarget);
 				}}
-				onClick={(event) => show(event.currentTarget)}
+				onClick={(event) => { event.stopPropagation(); show(event.currentTarget); }}
 				onKeyDown={(event) => {
 					if (event.key === "ArrowRight") {
 						event.preventDefault();
+						event.stopPropagation();
+						focusFirstOnOpenRef.current = true;
 						show(event.currentTarget);
-						window.requestAnimationFrame(() => submenuRef.current?.querySelector<HTMLElement>('[role="menuitem"]')?.focus());
+						if (submenuRef.current) {
+							focusFirstOnOpenRef.current = false;
+							menuItems(submenuRef.current)[0]?.focus({ preventScroll: true });
+						}
 					}
-					if (event.key === "Escape") setOpen(false);
 				}}
-				onMouseDown={(event) => { event.preventDefault(); event.stopPropagation(); }}
+				onMouseDown={(event) => event.stopPropagation()}
 				className="flex h-7 w-full items-center justify-between rounded-lg px-2 text-left text-sm text-[var(--foreground)] outline-none hover:bg-[var(--brand)] hover:text-[var(--primary-foreground)] focus-visible:bg-[var(--brand)] focus-visible:text-[var(--primary-foreground)]"
 			>
 				<span className="flex min-w-0 items-center gap-2">{icon}{label}</span>
@@ -386,13 +457,22 @@ function ContextMenuSubmenu({
 				<div
 					ref={submenuRef}
 					data-context-menu-submenu="true"
+					data-context-menu-owner={menuId}
 					role="menu"
+					onPointerDown={(event) => event.stopPropagation()}
+					onMouseDown={(event) => event.stopPropagation()}
+					onClick={(event) => event.stopPropagation()}
+					onFocus={(event) => event.stopPropagation()}
 					onKeyDown={(event) => {
-						if (event.key !== "ArrowLeft") return;
+						if (event.key !== 'ArrowLeft' && event.key !== 'Escape') {
+							navigateMenu(event);
+							return;
+						}
 						event.preventDefault();
+						event.stopPropagation();
 						setOpen(false);
 						skipFocusOpenRef.current = true;
-						triggerRef.current?.focus();
+						triggerRef.current?.focus({ preventScroll: true });
 					}}
 					onMouseEnter={cancelClose}
 					onMouseLeave={scheduleClose}
diff --git a/app/flowix-web/shared/ui/dropdown-menu.tsx b/app/flowix-web/shared/ui/dropdown-menu.tsx
index 723f0a1e3..6860af3c6 100644
--- a/app/flowix-web/shared/ui/dropdown-menu.tsx
+++ b/app/flowix-web/shared/ui/dropdown-menu.tsx
@@ -262,7 +262,8 @@ function DropdownMenuContent({
 			const target = e.target as Node;
 			if (
 				contentRef.current?.contains(target) ||
-				triggerRef.current?.contains(target)
+				triggerRef.current?.contains(target) ||
+				(target instanceof Element && target.closest("[data-flowix-menu-child]"))
 			) {
 				return;
 			}
@@ -331,6 +332,7 @@ function DropdownMenuItem({
 	trailingActionLabel,
 	inset,
 	title,
+	keepOpenOnClick = false,
 }: {
 	children: React.ReactNode;
 	className?: string;
@@ -342,6 +344,7 @@ function DropdownMenuItem({
 	trailingActionLabel?: string;
 	inset?: boolean;
 	title?: string;
+	keepOpenOnClick?: boolean;
 }) {
 	const { setOpen } = useDropdownContext();
 
@@ -349,7 +352,7 @@ function DropdownMenuItem({
 		e.stopPropagation();
 		if (disabled) return;
 		onClick?.(e);
-		setOpen(false);
+	if (!keepOpenOnClick) setOpen(false);
 	};
 
 	const handleMouseDown = (e: React.MouseEvent<HTMLButtonElement>) => {
diff --git a/app/flowix-web/shared/ui/flowix-checkbox.tsx b/app/flowix-web/shared/ui/flowix-checkbox.tsx
new file mode 100644
index 000000000..e8e668977
--- /dev/null
+++ b/app/flowix-web/shared/ui/flowix-checkbox.tsx
@@ -0,0 +1,61 @@
+import type { FocusEventHandler } from 'react';
+import { cn } from '@/lib/utils';
+
+interface FlowixCheckboxBaseProps {
+  checked: boolean;
+  className?: string;
+  disabled?: boolean;
+}
+
+export type FlowixCheckboxProps = FlowixCheckboxBaseProps & (
+  | {
+      interactive?: true;
+      onCheckedChange: (checked: boolean) => void;
+      'aria-label': string;
+      onBlur?: FocusEventHandler<HTMLButtonElement>;
+    }
+  | {
+      interactive: false;
+      onCheckedChange?: never;
+      'aria-label'?: never;
+      onBlur?: never;
+    }
+);
+
+export function FlowixCheckbox({
+  checked,
+  onCheckedChange,
+  'aria-label': ariaLabel,
+  interactive = true,
+  className,
+  disabled = false,
+  onBlur,
+}: FlowixCheckboxProps) {
+  const checkboxClassName = cn(
+    'flowix-hand-checkbox',
+    interactive && 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]',
+    checked && 'flowix-hand-checkbox--checked',
+    disabled && 'disabled:cursor-not-allowed disabled:opacity-50',
+    className,
+  );
+  const mark = checked && <span className="flowix-hand-checkbox__mark" aria-hidden="true" />;
+
+  if (!interactive) {
+    return <span aria-hidden="true" className={checkboxClassName}>{mark}</span>;
+  }
+
+  return (
+    <button
+      type="button"
+      role="checkbox"
+      aria-checked={checked}
+      aria-label={ariaLabel}
+      disabled={disabled}
+      onClick={() => onCheckedChange?.(!checked)}
+      onBlur={onBlur}
+      className={checkboxClassName}
+    >
+      {mark}
+    </button>
+  );
+}
diff --git a/app/flowix-web/shared/ui/font-size-switcher.tsx b/app/flowix-web/shared/ui/font-size-switcher.tsx
new file mode 100644
index 000000000..36be040a1
--- /dev/null
+++ b/app/flowix-web/shared/ui/font-size-switcher.tsx
@@ -0,0 +1,39 @@
+'use client';
+
+import { TextTIcon } from '@phosphor-icons/react';
+import { useI18n } from '@/lib/i18n';
+
+export const FONT_SIZE_MODES = ['small', 'medium', 'large'] as const;
+export type FontSizeMode = (typeof FONT_SIZE_MODES)[number];
+
+export function FontSizeSwitcher({
+  sizeMode,
+  onSelect,
+}: {
+  sizeMode: FontSizeMode | null;
+  onSelect: (mode: FontSizeMode) => void;
+}) {
+  const { t } = useI18n();
+  return (
+    <div className="group flex h-7 w-full items-center gap-2 rounded-lg px-2 text-sm text-[var(--foreground)]">
+      <TextTIcon aria-hidden="true" className="h-4 w-4 shrink-0" />
+      <div className="min-w-0 flex-1">{t('agent.chat.messageFontSize')}</div>
+      <div className="flex shrink-0 gap-0.5" role="group" aria-label={t('agent.chat.messageFontSize')}>
+        {FONT_SIZE_MODES.map((mode) => (
+          <button
+            key={mode}
+            type="button"
+            aria-pressed={sizeMode === mode}
+            onClick={(event) => {
+              event.stopPropagation();
+              onSelect(mode);
+            }}
+            className={`h-6 min-w-7 rounded-md px-1 text-xs transition-colors ${sizeMode === mode ? 'font-semibold text-[var(--foreground)]' : 'text-[var(--muted-foreground)]'}`}
+          >
+            {t(`agent.chat.messageFontSize.${mode}`)}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/app/flowix-web/shared/ui/list-surface.tsx b/app/flowix-web/shared/ui/list-surface.tsx
index f6083649a..c9c9cd134 100644
--- a/app/flowix-web/shared/ui/list-surface.tsx
+++ b/app/flowix-web/shared/ui/list-surface.tsx
@@ -22,15 +22,17 @@ export function ListSurfaceViewport({
 /** Initial-load state shared by notes, trees, and conversation lists. */
 export function ListSurfaceLoadingState({
   label,
+  ariaLabel,
   className,
 }: {
-  label: string;
+  label?: string;
+  ariaLabel?: string;
   className?: string;
 }) {
   return (
     <CenteredLoadingSpinner
       className={cn('h-full w-full', className)}
-      ariaLabel={label}
+      ariaLabel={ariaLabel ?? label}
       label={label}
     />
   );
@@ -47,7 +49,7 @@ export function ListSurfaceSpinner({
   return (
     <span
       className={cn(
-        'shrink-0 animate-spin rounded-full border-2 border-[color-mix(in_oklch,var(--muted-foreground)_26%,transparent)] border-t-[var(--brand)]',
+        'shrink-0 flowix-spin rounded-full border-2 border-[color-mix(in_oklch,var(--muted-foreground)_26%,transparent)] border-t-[var(--brand)]',
         className,
       )}
       role={ariaLabel ? 'status' : undefined}
diff --git a/app/flowix-web/shared/ui/popover.tsx b/app/flowix-web/shared/ui/popover.tsx
index 8b423741a..711f6f1df 100644
--- a/app/flowix-web/shared/ui/popover.tsx
+++ b/app/flowix-web/shared/ui/popover.tsx
@@ -138,6 +138,7 @@ interface PopoverContentProps {
 	sideOffset?: number;
 	offsetY?: number;
 	className?: string;
+	"aria-label"?: string;
 	style?: React.CSSProperties;
 	matchAnchorWidth?: boolean | number;
 	matchAnchorHeight?: boolean;
@@ -145,6 +146,8 @@ interface PopoverContentProps {
 	ignoreSelectOutside?: boolean;
 	ignorePopoverOutside?: boolean;
 	fitViewport?: boolean;
+	alignToAnchorOrigin?: boolean;
+	keepParentMenuOpen?: boolean;
 }
 
 type PopoverMotionState = "starting" | "open" | "closing";
@@ -159,6 +162,7 @@ function PopoverContent({
 	sideOffset = 4,
 	offsetY = 0,
 	className,
+	"aria-label": ariaLabel,
 	style,
 	matchAnchorWidth = false,
 	matchAnchorHeight = false,
@@ -166,6 +170,8 @@ function PopoverContent({
 	ignoreSelectOutside = true,
 	ignorePopoverOutside = false,
 	fitViewport = false,
+	alignToAnchorOrigin = false,
+	keepParentMenuOpen = false,
 }: PopoverContentProps) {
 	const { open, setOpen, triggerRef, anchorRect, cellAnchorRect, cellPopup } = usePopoverContext();
 	const contentRef = React.useRef<HTMLDivElement>(null);
@@ -215,15 +221,19 @@ function PopoverContent({
 
 		const updatePosition = () => {
 			const content = contentRef.current;
-			if (fitViewport && content) {
-				content.style.maxWidth = `${Math.max(0, window.innerWidth - 16)}px`;
-				content.style.maxHeight = `${Math.max(0, window.innerHeight - 8)}px`;
-				content.style.overflowY = 'auto';
-			}
 			const trigger = triggerRef.current;
 			const anchor = anchorSelector ? trigger?.closest<HTMLElement>(anchorSelector) : null;
 			const rect = anchor?.getBoundingClientRect() ?? cellAnchorRect ?? anchorRect ?? trigger?.getBoundingClientRect();
 			if (!rect) return;
+			if (content && alignToAnchorOrigin) {
+				content.style.maxWidth = `${Math.max(0, window.innerWidth - rect.left - 4)}px`;
+				content.style.maxHeight = `${Math.max(0, window.innerHeight - rect.top - 4)}px`;
+				content.style.overflowY = 'auto';
+			} else if (fitViewport && content) {
+				content.style.maxWidth = `${Math.max(0, window.innerWidth - 16)}px`;
+				content.style.maxHeight = `${Math.max(0, window.innerHeight - 8)}px`;
+				content.style.overflowY = 'auto';
+			}
 			const width = contentRef.current?.offsetWidth ?? 200;
 			const height = contentRef.current?.offsetHeight ?? 200;
 
@@ -237,7 +247,10 @@ function PopoverContent({
 				resolvedSide = 'right';
 			}
 
-			if (cellAnchorRect) {
+			if (alignToAnchorOrigin) {
+				leftPos = rect.left;
+				topPos = rect.top;
+			} else if (cellAnchorRect) {
 				leftPos = rect.left;
 				topPos = rect.top;
 			} else if (resolvedSide === "right" || resolvedSide === "left") {
@@ -257,10 +270,12 @@ function PopoverContent({
 			}
 
 			topPos += offsetY;
-			const nextPosition = {
-				top: Math.max(4, Math.min(topPos, window.innerHeight - height - 4)),
-				left: Math.max(4, Math.min(leftPos, window.innerWidth - width - 4)),
-			};
+			const nextPosition = alignToAnchorOrigin
+				? { top: topPos, left: leftPos }
+				: {
+					top: Math.max(4, Math.min(topPos, window.innerHeight - height - 4)),
+					left: Math.max(4, Math.min(leftPos, window.innerWidth - width - 4)),
+				};
 			setPosition((current) =>
 				current.top === nextPosition.top && current.left === nextPosition.left
 					? current
@@ -271,6 +286,10 @@ function PopoverContent({
 		updatePosition();
 		rafId = requestAnimationFrame(() => setMotionState("open"));
 		settleTimerId = window.setTimeout(updatePosition, 50);
+		const resizeObserver = fitViewport && typeof ResizeObserver !== 'undefined' && contentRef.current
+			? new ResizeObserver(updatePosition)
+			: null;
+		if (contentRef.current) resizeObserver?.observe(contentRef.current);
 
 		window.addEventListener('scroll', updatePosition, true);
 		window.addEventListener('resize', updatePosition);
@@ -278,10 +297,11 @@ function PopoverContent({
 		return () => {
 			cancelAnimationFrame(rafId);
 			window.clearTimeout(settleTimerId);
+			resizeObserver?.disconnect();
 			window.removeEventListener('scroll', updatePosition, true);
 			window.removeEventListener('resize', updatePosition);
 		};
-	}, [open, present, side, sideOffset, offsetY, align, anchorRect, cellAnchorRect, anchorSelector, fitViewport]);
+	}, [open, present, side, sideOffset, offsetY, align, anchorRect, cellAnchorRect, anchorSelector, fitViewport, alignToAnchorOrigin]);
 
 	React.useEffect(() => {
 		if (!open || !cellAnchorRect) return;
@@ -348,9 +368,12 @@ function PopoverContent({
 				shadowClass,
 				className
 			)}
-				data-motion-state={motionState}
+			data-motion-state={motionState}
 			data-side={side}
 				data-flowix-surface="popover"
+			data-flowix-menu-child={keepParentMenuOpen ? "" : undefined}
+			role={ariaLabel ? "dialog" : undefined}
+			aria-label={ariaLabel}
 			style={{
 				...style,
 				...(matchAnchorWidth && cellAnchorRect
diff --git a/app/flowix-web/shared/ui/select.tsx b/app/flowix-web/shared/ui/select.tsx
index 90e594f05..8a102eb43 100644
--- a/app/flowix-web/shared/ui/select.tsx
+++ b/app/flowix-web/shared/ui/select.tsx
@@ -23,6 +23,7 @@ interface SelectContextValue {
 }
 
 const SelectContext = React.createContext<SelectContextValue | null>(null);
+const selectDisabledClassName = "disabled:cursor-not-allowed disabled:opacity-50";
 
 function useSelectContext() {
 	const context = React.useContext(SelectContext);
@@ -84,9 +85,13 @@ interface SelectTriggerProps {
 	children?: React.ReactNode;
 	className?: string;
 	asChild?: boolean;
+	id?: string;
+	'aria-label'?: string;
+	'aria-labelledby'?: string;
+	'aria-describedby'?: string;
 }
 
-function SelectTrigger({ children, className, asChild }: SelectTriggerProps) {
+function SelectTrigger({ children, className, asChild, id, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy }: SelectTriggerProps) {
 	const { value, open, disabled, setOpen, triggerRef, setAnchorRect, anchorToCell } = useSelectContext();
 	const { t } = useI18n();
 
@@ -105,10 +110,15 @@ function SelectTrigger({ children, className, asChild }: SelectTriggerProps) {
 			<button
 				type="button"
 				ref={triggerRef as React.Ref<HTMLButtonElement>}
+				id={id}
+				aria-label={ariaLabel}
+				aria-labelledby={ariaLabelledBy}
+				aria-describedby={ariaDescribedBy}
 				disabled={disabled}
 				onClick={handleClick}
 				className={cn(
 					"flex items-center justify-between w-full h-8 px-3 rounded-lg bg-[var(--card)] border border-[var(--border)] text-sm text-[var(--foreground)] focus:outline-none focus:border-[var(--primary)]",
+					selectDisabledClassName,
 					className
 				)}
 				data-state={open ? "open" : "closed"}
@@ -127,6 +137,11 @@ function SelectTrigger({ children, className, asChild }: SelectTriggerProps) {
 		const childOnClick = child.props.onClick;
 		return React.cloneElement(child, {
 			ref: triggerRef,
+			id: id ?? child.props.id,
+			'aria-label': ariaLabel ?? child.props['aria-label'],
+			'aria-labelledby': ariaLabelledBy ?? child.props['aria-labelledby'],
+			'aria-describedby': ariaDescribedBy ?? child.props['aria-describedby'],
+			className: cn(child.props.className, className, selectDisabledClassName),
 			onClick: (event: React.MouseEvent<HTMLElement>) => {
 				if (disabled) return;
 				childOnClick?.(event);
@@ -142,10 +157,15 @@ function SelectTrigger({ children, className, asChild }: SelectTriggerProps) {
 		<button
 			type="button"
 			ref={triggerRef as React.Ref<HTMLButtonElement>}
+			id={id}
+			aria-label={ariaLabel}
+			aria-labelledby={ariaLabelledBy}
+			aria-describedby={ariaDescribedBy}
 			disabled={disabled}
 			onClick={handleClick}
 			className={cn(
 				"flex items-center justify-between w-full h-8 px-3 rounded-lg bg-[var(--card)] border border-[var(--border)] text-sm text-[var(--foreground)] focus:outline-none focus:border-[var(--primary)]",
+				selectDisabledClassName,
 				className
 			)}
 			data-state={open ? "open" : "closed"}
diff --git a/app/flowix-web/shared/ui/typography-font-switcher.tsx b/app/flowix-web/shared/ui/typography-font-switcher.tsx
new file mode 100644
index 000000000..206834785
--- /dev/null
+++ b/app/flowix-web/shared/ui/typography-font-switcher.tsx
@@ -0,0 +1,58 @@
+'use client';
+
+import { Loader2 } from 'lucide-react';
+import standardIcon from '@/assets/editor-font-icons/standard.svg';
+import serifIcon from '@/assets/editor-font-icons/serif.svg';
+import wenkaiIcon from '@/assets/editor-font-icons/wenkai.svg';
+import { useI18n } from '@/lib/i18n';
+import { TYPOGRAPHY_FONT_MODES, type TypographyFontMode } from '@/lib/typography-font-mode';
+
+const FONT_MODE_ICONS: Record<TypographyFontMode, string> = {
+  standard: standardIcon,
+  serif: serifIcon,
+  wenkai: wenkaiIcon,
+};
+
+export function TypographyFontSwitcher({
+  fontMode,
+  downloadingMode,
+  percent,
+  onSelect,
+}: {
+  fontMode: TypographyFontMode;
+  downloadingMode: Exclude<TypographyFontMode, 'standard'> | null;
+  percent: number | null;
+  onSelect: (mode: TypographyFontMode) => void;
+}) {
+  const { t } = useI18n();
+
+  return (
+    <div className="mb-1">
+      <div className="flex justify-center gap-0.5" role="group" aria-label={t('document.font.label')}>
+        {TYPOGRAPHY_FONT_MODES.map((mode) => {
+          const active = fontMode === mode;
+          const isLoading = downloadingMode === mode;
+          return (
+            <button
+              key={mode}
+              type="button"
+              aria-pressed={active}
+              disabled={isLoading}
+              onClick={() => onSelect(mode)}
+              className={`group flex h-[58px] w-[58px] shrink-0 flex-col items-center justify-center gap-1 rounded-lg text-[11px] leading-tight transition-colors hover:bg-[var(--muted)] hover:text-[var(--foreground)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--ring)] ${active ? 'text-[var(--foreground)]' : 'text-[var(--muted-foreground)]'}`}
+            >
+              {isLoading
+                ? <Loader2 aria-hidden="true" className="h-4 w-4 flowix-spin text-[var(--brand)]" />
+                : <img aria-hidden="true" src={FONT_MODE_ICONS[mode]} alt="" className="h-6 w-6 shrink-0 dark:invert" />}
+              <span className="max-w-full truncate tabular-nums">
+                {isLoading
+                  ? percent == null ? '…' : `${percent}%`
+                  : t(mode === 'standard' ? 'document.font.standard' : mode === 'serif' ? 'document.font.serif' : 'document.font.wenkai')}
+              </span>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/app/flowix-web/shared/window-titlebar-controls.tsx b/app/flowix-web/shared/window-titlebar-controls.tsx
index 5deaabae0..59be85106 100644
--- a/app/flowix-web/shared/window-titlebar-controls.tsx
+++ b/app/flowix-web/shared/window-titlebar-controls.tsx
@@ -1,8 +1,14 @@
+import { useEffect, useRef } from 'react';
+import { registerWindowCloseRegion, subscribeNativeCloseRouting } from '@platform/tauri/window-close-region';
+import { createLogger } from '@/lib/logger';
+import { toast } from '@/lib/toast';
 import { Minus, Square, X } from "lucide-react";
 import { getCurrentWindow } from "@platform/tauri/window";
 import { Tooltip } from "@shared/ui/tooltip";
 import { useI18n } from "@/lib/i18n";
 
+let lastAnnouncedRoutingStatus: boolean | undefined;
+
 function isWindowsPlatform(): boolean {
   return /Windows/i.test(navigator.userAgent) || /Win/i.test(navigator.platform);
 }
@@ -21,6 +27,28 @@ export function WindowsTitlebarControls({
   reserveSpace = false,
 }: WindowsTitlebarControlsProps) {
   const { t } = useI18n();
+  const closeButton = useRef<HTMLButtonElement>(null);
+  const translate = useRef(t);
+  translate.current = t;
+  useEffect(() => {
+    if (isWindowsPlatform() && isTauriApp() && closeButton.current) {
+      const unregisterRegion = registerWindowCloseRegion(closeButton.current);
+      const unsubscribeHealth = subscribeNativeCloseRouting(ready => {
+        if (lastAnnouncedRoutingStatus === ready) return;
+        const wasKnown = lastAnnouncedRoutingStatus !== undefined;
+        lastAnnouncedRoutingStatus = ready;
+        if (!ready) {
+          toast.warning(translate.current('window.closeNativeUnavailable'));
+        } else if (wasKnown) {
+          toast.success(translate.current('window.closeNativeRestored'));
+        }
+      });
+      return () => {
+        unregisterRegion();
+        unsubscribeHealth();
+      };
+    }
+  }, []);
   if (!isWindowsPlatform() || !isTauriApp()) return null;
 
   return (
@@ -51,7 +79,13 @@ export function WindowsTitlebarControls({
           <button
             type="button"
             aria-label={t('window.close')}
-            onClick={() => getCurrentWindow().close()}
+            ref={closeButton}
+            onClick={() => {
+              void getCurrentWindow().close().catch(() => {
+                createLogger('window:controls').error('close request failed');
+                toast.error(t('window.closeRequestFailed'));
+              });
+            }}
             className="flex h-9 w-[42px] items-center justify-center text-[var(--muted-foreground)] transition-colors hover:bg-[var(--destructive)] hover:text-[var(--floating-foreground)] [-webkit-app-region:no-drag]"
           >
             <X className="h-3.5 w-3.5" strokeWidth={1.8} />
diff --git a/app/flowix-web/styles/agent-conversation/composer.css b/app/flowix-web/styles/agent-conversation/composer.css
new file mode 100644
index 000000000..35b1bcba4
--- /dev/null
+++ b/app/flowix-web/styles/agent-conversation/composer.css
@@ -0,0 +1,1723 @@
+/* Shared Agent conversation composer. Compact and expanded surfaces use the
+ * same component; state-specific sizing lives in --agent-composer-input-min-height.
+ * Rounded capsule container uses content-driven grid rows.
+ * 子元素隐藏时自动收缩，折叠态不会留下空白区域。
+ * 外层 max-height: 15rem; 输入区内容超出时在输入区内部滚动,
+ * composer 容器不被撑破。
+ *
+ * 背景使用 var(--input-bg) ── 输入面与文档背景解耦, 浅色模式统一为白色;
+ * 1px border 保留, 仍能围出胶囊形状; 输入内容透明, 直接
+ * 透出 composer 背景。多行状态由 .--multi-line 修饰类切到 flex-end。 */
+.agent-conversation-surface .agent-composer {
+  --agent-composer-input-min-height: 1.6em;
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  align-self: end;
+  width: calc(100% - 24px);
+  /* Allow the composer to shrink within its grid track, even when the input
+   * contains a long unbroken string. */
+  min-width: 0;
+  max-width: calc(100% - 24px);
+  margin: 0 0.8rem 0.6rem;
+  padding: 0 0.4rem 0 0.8rem;
+  border: 1px solid var(--border);
+  border-radius: 1rem;
+  background: var(--input-bg, var(--document-bg));
+  /* Keep the composer lighter than the Slash menu while
+   * keeping a shorter offset for the composer sitting against the canvas edge. */
+  box-shadow: 0 2px 24px -3px rgb(0 0 0 / 3%);
+  box-sizing: border-box;
+  max-height: 15rem;
+  user-select: none;
+  /* Empty composer space also focuses the input, so show a text cursor.
+   *
+   * 用 :where() 选非交互后代让优先级保持在 0, 不压过下面的 button /
+   * image-remove 等子选择器 ── 按钮仍是 pointer 光标。 */
+  cursor: text;
+}
+
+/* Compact composer keeps its existing single-line outer height. */
+.agent-conversation-surface .agent-composer:not(.agent-composer--expanded) {
+  min-height: 42px;
+  padding-top: 6px;
+  padding-bottom: 6px;
+}
+
+.agent-conversation-surface .agent-composer :where(
+  button,
+  a,
+  [role='button'],
+  .agent-composer__add-button,
+  .agent-composer__model,
+  .agent-composer__mode,
+  .agent-composer__permission,
+  .agent-composer__workspace
+) {
+  cursor: pointer;
+}
+
+.agent-conversation-surface .agent-composer--expanded {
+  width: calc(100% - 3rem);
+  max-width: 780px;
+  margin: 0 auto 0.6rem;
+  /* 全屏态: 宽度 / margin 与基线不同; 背景由基线 var(--document-bg) 提供,
+   * 不再覆盖, 全屏 / 非全屏视觉一致。 */
+}
+
+.agent-conversation-surface .agent-composer--multi-line {
+  align-items: flex-end;
+}
+
+/* As compact input grows, keep side actions vertically centered.
+ * 仍应相对整个 composer 上下居中；底部对齐只保留给 expanded composer
+ * 的独立操作行布局。 */
+.agent-conversation-surface
+  .agent-composer:not(.agent-composer--expanded)
+  .agent-composer--multi-line {
+  align-items: center;
+}
+
+/* 非全屏态的 actions 也要建立自己的 flex 行。
+ * 如果保持默认 block 行盒，Add 按钮会按文字基线布局，视觉上贴在
+ * actions 的上沿；显式居中后，按钮始终在 actions 的内容高度内垂直居中。 */
+.agent-conversation-surface
+  .agent-composer:not(.agent-composer--expanded)
+  .agent-composer__actions {
+  display: flex;
+  align-items: center;
+  flex: 0 0 auto;
+  gap: 0.1rem;
+}
+
+.agent-conversation-surface .agent-composer__model {
+  display: none;
+}
+
+.agent-conversation-surface .agent-composer__mode {
+  display: none;
+}
+
+.agent-conversation-surface .agent-composer__workspace {
+  display: none;
+}
+
+.agent-conversation-surface .agent-composer__permission {
+  display: none;
+}
+
+.agent-conversation-surface .agent-composer__workspace:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+  pointer-events: auto;
+}
+
+.agent-conversation-surface .agent-composer__permission:disabled,
+.agent-conversation-surface .agent-composer__mode:disabled,
+.agent-conversation-surface .agent-conversation__control[data-kind='permission']:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+  pointer-events: auto;
+}
+
+.agent-conversation-surface .agent-composer__workspace:disabled:hover {
+  background: transparent;
+}
+
+.agent-conversation-surface .agent-composer__permission:disabled:hover,
+.agent-conversation-surface .agent-composer__mode:disabled:hover,
+.agent-conversation-surface .agent-conversation__control[data-kind='permission']:disabled:hover {
+  background: transparent;
+}
+
+/* Setup controls share one neutral conversation-control style wherever the
+ * conversation starts without messages. */
+.agent-conversation-surface .agent-conversation__controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+}
+
+.agent-conversation-surface .agent-conversation__control {
+  display: inline-flex;
+  align-items: center;
+  max-width: 190px;
+  min-width: 0;
+  height: 28px;
+  gap: 5px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+.agent-conversation-surface .agent-conversation__control[data-kind='model'] {
+  max-width: 240px;
+}
+
+.agent-conversation-surface .agent-conversation__workspace {
+  display: inline-flex;
+  align-items: center;
+  max-width: 190px;
+  min-width: 0;
+  height: 28px;
+  gap: 5px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+  font-family: inherit;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+.agent-conversation-surface .agent-conversation__workspace-value,
+.agent-conversation-surface .agent-conversation__control-value {
+  min-width: 0;
+  overflow: hidden;
+  color: var(--foreground);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  line-height: 1.6;
+}
+
+.agent-conversation-surface .agent-conversation__control-label {
+  flex: 0 0 auto;
+}
+
+.agent-conversation-surface
+  :is(.agent-conversation__control, .agent-conversation__workspace):is(
+    :hover,
+    :focus-visible,
+    .agent-conversation__control--open,
+    .agent-conversation__workspace--open
+  ) {
+  background: var(--muted);
+  color: var(--foreground);
+  outline: none;
+}
+
+  /* Expanded conversation composer: the input occupies the upper row and the
+ * role/add + send controls share a dedicated bottom row. Both fullscreen
+ * surfaces opt in through .agent-composer--expanded. */
+.agent-conversation-surface .agent-composer--expanded {
+  --agent-composer-input-min-height: 2.6rem;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: end;
+  row-gap: 0.35rem;
+  /* Keep the top breathing room inside the scrollable input area. */
+  padding: 0.55rem 0.6rem 0.55rem 0.8rem;
+  grid-template-areas:
+    "input input"
+    "actions send";
+  grid-template-rows: minmax(var(--agent-composer-input-min-height), auto) auto;
+  max-height: none;
+}
+
+.agent-conversation-surface .agent-composer--expanded .agent-composer__actions {
+  grid-area: actions;
+  display: flex;
+  align-items: center;
+  gap: 0.1rem;
+  align-self: end;
+}
+
+.agent-conversation-surface
+  .agent-composer--expanded
+  :is(.agent-composer__model, .agent-composer__mode) {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.2rem;
+  min-width: 0;
+  max-width: 12rem;
+  height: 24px;
+  flex: 0 1 auto;
+  padding: 0 0.45rem;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+  transition:
+    background-color 150ms ease,
+    color 150ms ease;
+}
+
+.agent-conversation-surface
+  .agent-composer--expanded
+  .agent-composer__model {
+  max-width: 240px;
+}
+
+/* hover / open 态背景与 add (+) 按钮的默认背景 (var(--muted)) 对齐,
+ * 同空状态 __empty-control 的 hover 规格, 不再单独加深。 */
+.agent-conversation-surface
+  .agent-composer--expanded
+  :is(.agent-composer__model:hover, .agent-composer__model--open) {
+  background: var(--muted);
+  color: var(--foreground);
+  outline: none;
+}
+
+.agent-conversation-surface
+  .agent-composer--expanded
+  :is(
+    .agent-composer__mode,
+    .agent-composer__permission,
+    .agent-composer__workspace
+  ) {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.2rem;
+  min-width: 0;
+  max-width: 12rem;
+  height: 24px;
+  flex: 0 1 auto;
+  padding: 0 0.45rem;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  /* 与空状态的空间信息保持同一套文字规格（text-xs / muted）。 */
+  color: var(--muted-foreground);
+  cursor: pointer;
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+  transition:
+    background-color 150ms ease,
+    color 150ms ease;
+}
+
+.agent-conversation-surface
+  .agent-composer--expanded
+  :is(
+    .agent-composer__mode:hover,
+    .agent-composer__mode--open,
+    .agent-composer__permission:hover,
+    .agent-composer__permission--open,
+    .agent-composer__workspace:hover,
+    .agent-composer__workspace--open
+  ) {
+  background: var(--muted);
+  color: var(--foreground);
+  outline: none;
+}
+
+.agent-conversation-surface .agent-composer__workspace-value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  line-height: 1.6;
+}
+
+.agent-conversation-surface .agent-composer__model-value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  line-height: 1.6;
+}
+
+.agent-conversation-surface .agent-composer__mode-value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  line-height: 1.6;
+}
+
+.agent-conversation-surface .agent-composer__workspace .agent-conversation__control-chevron {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+  opacity: 0.72;
+}
+
+.agent-conversation-surface .agent-composer__workspace-icon {
+  width: 15px;
+  height: 15px;
+  flex: 0 0 auto;
+  color: var(--muted-foreground);
+}
+
+.agent-conversation-surface .agent-composer__permission .agent-conversation__control-chevron {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+  opacity: 0.72;
+}
+
+.agent-conversation-surface .agent-composer__model .agent-conversation__control-chevron {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+  opacity: 0.72;
+}
+
+.agent-conversation-surface .agent-composer__mode .agent-conversation__control-chevron {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+  opacity: 0.72;
+}
+
+.agent-conversation-surface .agent-composer--expanded .agent-composer__send-tooltip {
+  grid-area: send;
+  align-self: end;
+  justify-self: end;
+}
+
+.agent-conversation-surface .agent-composer__add-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  flex: 0 0 auto;
+  align-self: center;
+  /* Add 略小于发送按钮, 但仍通过 align-self: center 保持上下居中。
+   * 额外呼吸位叠加在 __composer-actions 行 gap 之上。 */
+  margin-right: 0.2rem;
+  overflow: hidden;
+  border: 0;
+  padding: 0;
+  border-radius: 6px;
+  background: var(--muted);
+  color: var(--secondary-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  font-weight: 600;
+  text-transform: uppercase;
+  cursor: pointer;
+  transition:
+    background-color 150ms ease,
+    color 150ms ease;
+}
+
+/* 之前 `hidden` 时 display: none ── 现在 composerRoleIcon 永远是 button,
+ * 不再设 hidden 属性, 这条规则保留作兜底, 防止后续调用方误设 hidden 时
+ * 留下按钮空白 (auto 行高 collapse 已处理, 但显式更稳)。 */
+.agent-conversation-surface .agent-composer__add-button[hidden] {
+  display: none;
+}
+
+.agent-conversation-surface .agent-composer__add-button img,
+.agent-conversation-surface .agent-composer__add-button svg {
+  display: block;
+  width: 20px;
+  height: 20px;
+  object-fit: contain;
+  /* 子元素 SVG / img 不接收 pointer events ── 点击落到底层 button,
+   * 走统一的 click handler。 否则某些浏览器 (尤其带 ::after 高亮的
+   * svg) 会把事件吞掉, 让 button 的 onclick 不触发。 */
+  pointer-events: none;
+}
+
+/* 空态 Plus 图标 ── 14×14, 复用 access popover 新增资料夹按钮
+ * (`.agent-composer__access-add-icon`) 的尺寸。 20×20 对 Plus
+ * filled cross 来说偏大, 与按钮 24×24 容器几乎填满, 视觉上比 memo
+ * 文档图标更"重", 与"未设置"的轻量占位语义不符。 缩到 14×14 后,
+ * 与 access popover 新增资料夹视觉同源, "次级 indicator" 这一类
+ * UI 元素有统一节奏。 */
+.agent-conversation-surface
+  .agent-composer__add-button
+  svg.agent-composer__add-button-empty {
+  width: 14px;
+  height: 14px;
+}
+
+/* hover / open 态 ── 与文件内 __icon-btn 的 hover 风格同源, 用 var(--muted)
+ * 与 var(--foreground) 混合色 + transition 150ms。 popover 打开时挂
+ * --open 修饰类, 视觉上"按钮被按下"。 */
+.agent-conversation-surface .agent-composer__add-button:hover,
+.agent-conversation-surface .agent-composer__add-button--open,
+.agent-conversation-surface .agent-composer__add-button:focus-visible {
+  background: color-mix(in oklch, var(--muted) 80%, var(--foreground) 12%);
+  color: var(--foreground);
+  outline: none;
+}
+
+.agent-composer-slash-menu {
+  position: fixed;
+  z-index: 1000;
+  max-height: min(22rem, 48vh);
+  overflow-y: auto;
+  padding: 0.25rem;
+  border: 1px solid var(--border-popup);
+  border-radius: 0.75rem;
+  background: var(--card);
+  color: var(--agent-foreground);
+  /* Slash menu shadow is intentionally 1/4 of the standard popover weight. */
+  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 6%);
+  box-sizing: border-box;
+}
+
+.agent-composer-slash-menu--folder {
+  max-height: min(16.5rem, 36vh);
+}
+
+.agent-composer-slash-menu__item {
+  display: flex;
+  width: 100%;
+  min-width: 0;
+  align-items: center;
+  gap: 0.75rem;
+  min-height: 1.75rem;
+  padding: 0.125rem 0.5rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: var(--foreground);
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1.25;
+  text-align: left;
+  cursor: pointer;
+}
+
+.agent-composer-slash-menu__section {
+  margin: 0.25rem 0.5rem 0.125rem;
+  padding: 0.35rem 0 0.125rem;
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.75);
+  line-height: 1.2;
+}
+
+.agent-composer-slash-menu__item--back {
+  margin-bottom: 0.2rem;
+  border-radius: 0;
+  color: var(--muted-foreground);
+}
+
+.agent-composer-slash-menu__empty {
+  padding: 0.5rem;
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.85);
+  text-align: center;
+}
+
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover,
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible,
+.agent-composer-slash-menu__item--active {
+  background: var(--hover-bg);
+  color: var(--foreground);
+}
+
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover
+  .agent-composer-slash-menu__name,
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover
+  .agent-composer-slash-menu__description,
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover
+  .agent-composer-slash-menu__scope,
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible
+  .agent-composer-slash-menu__name,
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible
+  .agent-composer-slash-menu__description,
+.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible
+  .agent-composer-slash-menu__scope,
+.agent-composer-slash-menu__item--active
+  .agent-composer-slash-menu__name,
+.agent-composer-slash-menu__item--active
+  .agent-composer-slash-menu__description,
+.agent-composer-slash-menu__item--active
+  .agent-composer-slash-menu__scope {
+  color: var(--foreground);
+}
+
+/* The skill picker has a navigation row, not a selectable command. Keep
+ * hovering/focusing that row to a text-color change, without the command
+ * highlight background. */
+.agent-composer-slash-menu:not(.is-keyboard-navigation)
+  .agent-composer-slash-menu__item--back:hover,
+.agent-composer-slash-menu:not(.is-keyboard-navigation)
+  .agent-composer-slash-menu__item--back:focus-visible {
+  background: transparent;
+  color: var(--foreground);
+}
+
+.agent-composer-slash-menu__name {
+  flex: 0 0 6.6rem;
+  color: var(--foreground);
+  font-weight: 400;
+}
+
+.agent-composer-slash-menu__item--skill .agent-composer-slash-menu__name {
+  flex: 0 1 auto;
+  min-width: 10em;
+  max-width: 34%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-composer-slash-menu__item--skill .agent-composer-slash-menu__description {
+  flex: 1 1 auto;
+}
+
+.agent-composer-slash-menu__scope {
+  flex: 0 0 auto;
+  padding: 0.1rem 0.4rem;
+  border-radius: 999px;
+  background: color-mix(in oklch, var(--foreground) 6%, transparent);
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.72);
+  line-height: 1.3;
+  white-space: nowrap;
+}
+
+.agent-composer-slash-menu__item--folder .agent-composer-slash-menu__name {
+  flex: 0 1 auto;
+  min-width: 0;
+  max-width: 40%;
+  overflow: hidden;
+  color: var(--foreground);
+  text-overflow: ellipsis;
+  font-weight: 400;
+  white-space: nowrap;
+}
+
+.agent-composer-slash-menu__item--folder .agent-composer-slash-menu__description {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--muted-foreground);
+  font-size: inherit;
+  text-overflow: ellipsis;
+  text-align: right;
+  white-space: nowrap;
+}
+
+.agent-composer-slash-menu__item--folder:hover .agent-composer-slash-menu__name,
+.agent-composer-slash-menu__item--folder:hover .agent-composer-slash-menu__description,
+.agent-composer-slash-menu__item--folder:focus-visible .agent-composer-slash-menu__name,
+.agent-composer-slash-menu__item--folder:focus-visible .agent-composer-slash-menu__description {
+  color: var(--foreground);
+}
+
+.agent-composer-slash-menu__item--folder.agent-composer-slash-menu__item--active
+  .agent-composer-slash-menu__name {
+  color: var(--foreground);
+}
+
+.agent-composer-slash-menu__item--note .agent-composer-slash-menu__name {
+  flex: 0 1 auto;
+  min-width: 0;
+  max-width: 62%;
+  overflow: hidden;
+  color: var(--foreground);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-composer-slash-menu__item--note .agent-composer-slash-menu__description {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--muted-foreground);
+  font-size: inherit;
+  text-align: right;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-composer-slash-menu__item--note:hover .agent-composer-slash-menu__name,
+.agent-composer-slash-menu__item--note:hover .agent-composer-slash-menu__description,
+.agent-composer-slash-menu__item--note:focus-visible .agent-composer-slash-menu__name,
+.agent-composer-slash-menu__item--note:focus-visible .agent-composer-slash-menu__description,
+.agent-composer-slash-menu__item--note.agent-composer-slash-menu__item--active
+  .agent-composer-slash-menu__name,
+.agent-composer-slash-menu__item--note.agent-composer-slash-menu__item--active
+  .agent-composer-slash-menu__description {
+  color: var(--foreground);
+}
+
+.agent-composer-slash-menu__description {
+  min-width: 0;
+  overflow: hidden;
+  color: var(--muted-foreground);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* 发送按钮 ── 28×28 圆形, 内嵌 16×16 Phosphor 图标。
+ * 尺寸取自 --atc-send-size, 与输入区 min-height 公式联动。 */
+.agent-composer__access-trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--atc-send-size);
+  flex: 0 0 auto;
+  border: 0;
+  border-radius: 9999px;
+  background: transparent;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  padding: 0 0.5rem;
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9); /* text-xs */
+  line-height: 1;
+  white-space: nowrap;
+}
+
+.agent-composer__access-trigger:hover,
+.agent-composer__access-trigger--open {
+  color: var(--foreground);
+}
+/* Shared input, inline token and caret rules for Agent conversation composer. */
+
+/* The surface sets `cursor: default` on descendants. Keep the input surface
+ * text-like; buttons and other controls restore their own pointer cursor. */
+.agent-conversation-surface .agent-composer__input,
+.agent-conversation-surface .agent-composer__input :where(*) {
+  cursor: text;
+}
+
+.agent-conversation-surface .agent-composer__input {
+  display: block;
+  width: 0;
+  min-width: 0;
+  max-width: 100%;
+  min-height: var(--agent-composer-input-min-height, 1.6em);
+  max-height: calc(var(--atc-composer-max-h) - 8px - var(--atc-bottom-pad));
+  height: auto;
+  flex: 1 1 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  outline: none;
+  background: transparent;
+  color: var(--foreground);
+  caret-color: var(--brand);
+  font: inherit;
+  font-size: var(--font-size, 15px);
+  line-height: 1.6;
+  user-select: text;
+  white-space: pre-wrap;
+}
+
+.agent-conversation-surface .agent-composer__input-content {
+  background: transparent;
+  font-family: var(--font-sans);
+}
+
+.agent-conversation-surface .agent-composer__input:focus {
+  box-shadow: none;
+}
+
+.agent-conversation-surface .agent-composer__input-row {
+  position: relative;
+  display: flex;
+  min-width: 0;
+  flex: 1 1 0;
+  align-items: center;
+  gap: 0.35rem;
+  cursor: text;
+  user-select: text;
+}
+
+.agent-conversation-surface .agent-composer--expanded .agent-composer__input-row {
+  grid-area: input;
+  align-self: stretch;
+}
+
+.agent-conversation-surface
+  .agent-composer--expanded
+  .agent-composer__input-row
+  .agent-composer__input {
+  box-sizing: border-box;
+  width: 100%;
+  height: auto;
+  max-height: calc(10 * 1.35em);
+  flex: 1 1 auto;
+  align-self: stretch;
+  padding-top: 0;
+  text-align: left;
+}
+
+.agent-conversation-surface
+  .agent-composer--expanded
+  .agent-composer__input-row
+  .agent-composer__input
+  > p:first-of-type {
+  padding-top: 0.25rem;
+}
+
+.agent-conversation-surface .agent-composer__input > p {
+  min-height: 1rem;
+  margin-top: 0 !important;
+  margin-bottom: 0 !important;
+  white-space: pre-wrap;
+}
+
+.agent-conversation-surface .agent-composer__input > p:empty::before,
+.agent-conversation-surface
+  .agent-composer__input
+  > p:has(> br.ProseMirror-trailingBreak:only-child)::before {
+  content: "\00a0";
+}
+
+/* Composer-specific appearance for inline cards and input tokens. */
+
+.agent-conversation-surface .agent-composer {
+  --agent-composer-inline-card-max-width: 16rem;
+  --agent-composer-card-border: var(--border);
+  --agent-composer-caret-width: 2px;
+  --agent-composer-caret-gap: 1px;
+  --agent-composer-action-inset: calc(var(--agent-composer-caret-width) + var(--agent-composer-caret-gap) + 0.18rem);
+}
+
+/* ── Composer caret ─────────────────────────────────────────────────────── */
+
+.agent-conversation-surface .agent-composer__input-content.has-composer-stable-caret,
+.agent-conversation-surface .agent-composer__input-content.has-composer-stable-caret :where(*) {
+  caret-color: transparent !important;
+}
+
+.agent-composer__caret-layer {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  pointer-events: none;
+  user-select: none;
+  z-index: 1;
+}
+
+.agent-composer__stable-caret {
+  position: absolute;
+  width: var(--agent-composer-caret-width, 2px);
+  border-radius: 999px;
+  background: var(--brand);
+  pointer-events: none;
+  animation: agent-composer-caret-blink 1.05s steps(1, end) infinite;
+}
+
+.agent-composer__stable-caret[hidden] {
+  display: none;
+}
+
+@keyframes agent-composer-caret-blink {
+  0%, 52% { opacity: 1; }
+  53%, 100% { opacity: 0; }
+}
+
+/* ── Shared composer card surface ───────────────────────────────────────── */
+
+.agent-conversation-surface .agent-composer .agent-composer__inline-card {
+  display: inline-flex;
+  box-sizing: border-box;
+  height: 1.6em;
+  max-width: var(--agent-composer-inline-card-max-width);
+  min-width: 0;
+  align-items: center;
+  padding: 0 0.25rem;
+  border: 1px solid var(--agent-composer-card-border);
+  border-radius: 0.35rem;
+  background: transparent;
+  color: var(--foreground);
+  font: inherit;
+  font-size: 92%;
+  font-weight: 400;
+  line-height: inherit;
+  vertical-align: top;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  cursor: pointer;
+  transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__inline-card:focus-visible {
+  border-color: color-mix(in oklch, var(--border) 95%, var(--foreground) 5%);
+  background: transparent;
+  color: var(--foreground);
+  outline: none;
+}
+
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__inline-atom-wrapper.is-selected
+  > .agent-composer__inline-card,
+.agent-conversation-surface .agent-composer .agent-composer__inline-card.ProseMirror-selectednode {
+  background-color: color-mix(in oklch, var(--foreground) 8%, transparent);
+}
+
+.agent-conversation-surface
+  .agent-composer.agent-composer--pointer-hover-ready
+  .agent-composer__inline-atom-wrapper:hover
+  > .agent-composer__inline-card {
+  border-color: var(--agent-composer-card-border);
+  background-color: var(--hover-bg);
+}
+
+/* ── Shared atom shell and remove action ─────────────────────────────────── */
+
+.agent-conversation-surface .agent-composer .agent-composer__inline-atom-wrapper {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  max-width: var(--agent-composer-inline-card-max-width);
+  box-sizing: border-box;
+  padding-inline: calc(var(--agent-composer-caret-width) + var(--agent-composer-caret-gap));
+  white-space: nowrap;
+  vertical-align: top;
+}
+
+.agent-conversation-surface .agent-composer .agent-inline-atom__actions {
+  position: absolute;
+  z-index: 1;
+  top: 50%;
+  inset-inline-end: var(--agent-composer-action-inset);
+  display: inline-flex;
+  align-items: center;
+  transform: translateY(-50%);
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.12s ease, visibility 0.12s ease;
+}
+
+.agent-conversation-surface
+  .agent-composer.agent-composer--pointer-hover-ready
+  .agent-composer__inline-atom-wrapper:hover
+  .agent-inline-atom__actions,
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__inline-atom-wrapper:focus-within
+  .agent-inline-atom__actions,
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__inline-atom-wrapper.is-selected
+  .agent-inline-atom__actions {
+  opacity: 1;
+  visibility: visible;
+}
+
+.agent-conversation-surface .agent-composer .agent-inline-atom__action {
+  display: inline-flex;
+  width: 1.1rem;
+  height: 1.1rem;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: var(--hover-bg);
+  color: var(--muted-foreground);
+  cursor: pointer;
+}
+
+.agent-conversation-surface
+  .agent-composer.agent-composer--pointer-hover-ready
+  .agent-inline-atom__action:hover,
+.agent-conversation-surface .agent-composer .agent-inline-atom__action:focus-visible {
+  color: var(--foreground);
+  outline: none;
+}
+
+.agent-conversation-surface .agent-composer .agent-inline-atom__action > svg {
+  width: 0.8rem;
+  height: 0.8rem;
+}
+
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__input
+  .agent-composer__inline-atom-wrapper,
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__input
+  .agent-composer__inline-atom-wrapper
+  * {
+  cursor: pointer;
+}
+
+/* ── Attachment, skill and slash token details ───────────────────────────── */
+
+.agent-conversation-surface .agent-composer .agent-composer__attachment-token {
+  gap: 0.3rem;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__attachment-token-preview,
+.agent-conversation-surface .agent-composer .agent-composer__attachment-token-icon {
+  display: inline-flex;
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__attachment-token-preview {
+  object-fit: cover;
+  border-radius: 0.16rem;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__attachment-token-label,
+.agent-conversation-surface .agent-composer .agent-composer__folder-token-label,
+.agent-conversation-surface .agent-composer .agent-composer__skill-token-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__skill-token {
+  gap: 0.08rem;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__folder-token {
+  gap: 0.25rem;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__folder-token-icon {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  color: var(--muted-foreground);
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__skill-token-icon {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  color: var(--muted-foreground);
+}
+
+/* ── Note-reference token details ───────────────────────────────────────── */
+
+.agent-conversation-surface .agent-composer .agent-composer__note-reference {
+  max-width: 100%;
+}
+
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__note-reference
+  .note-reference__icon {
+  display: inline-flex;
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  align-items: center;
+  margin: 0 0.06rem 0 0;
+  color: var(--muted-foreground);
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__note-reference :is(
+    .note-reference__name,
+    .note-reference__title
+  ) {
+  min-width: 0;
+  max-width: 100%;
+  overflow: hidden;
+  color: var(--foreground);
+  font-weight: 400;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-conversation-surface
+  .agent-composer.agent-composer--pointer-hover-ready
+  .agent-composer__note-reference
+  .note-reference__card:hover
+  :is(.note-reference__name, .note-reference__title) {
+  color: var(--foreground);
+}
+
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__note-reference
+  .note-reference__stale-mark {
+  margin-left: 4px;
+  color: var(--muted-foreground);
+  font-weight: 400;
+  white-space: nowrap;
+}
+
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__note-reference
+  .note-reference__card[data-stale="true"] {
+  opacity: 0.5;
+}
+
+.agent-conversation-surface .agent-composer .agent-composer__note-reference,
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__note-reference
+  .note-reference__card,
+.agent-conversation-surface
+  .agent-composer
+  .agent-composer__note-reference
+  .note-reference__card
+  * {
+  -webkit-user-drag: none;
+  -moz-user-drag: none;
+  -ms-user-drag: none;
+  user-drag: none;
+}
+
+/* 整体外框 ── position: fixed, 不写 max-height 也不写 overflow。
+ *
+ * 关键设计 ── overflow: visible (默认) ── 让内嵌子节点越界时不被裁
+ * 剪 (例如 future inline submenu)。 max-height 不写 ── 由 JS 写到内层
+ * .access-popover-scroll 上, 控制整个滚动区高度。
+ *
+ * 副作用 ── overflow visible 配合 box-shadow: shadow 仍按 outer 矩形
+ * 渲染, 不会因 visible 失效; border-radius 8px 配合 children 圆角 ──
+ * children 在 rounded 边缘内时被裁, 在外时不被裁。 */
+.agent-composer__access-popover {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 105;
+  width: 208px;
+  border: 1px solid var(--border-popup);
+  border-radius: 0.75rem;
+  background: var(--card);
+  color: var(--agent-foreground);
+  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
+  padding: 0.25rem;
+}
+
+/* 滚动容器 ── 装整个可滚动内容: notebook section、folder section、
+ * 末尾的"添加文件夹"按钮。 max-height 由 JS 动态计算 (= 可用空间)。
+ * 内容超出时整体滚动, 不再有 sticky footer ── 按钮作为列表最后一项
+ * 跟随内容滚动, 长列表下滚到底才能看到, 避免按钮在视觉上"凭空"出现
+ * 在分隔很远的列表底部, 维持"按钮属于 folder 区域"的归属感。 */
+.agent-composer__access-popover-scroll {
+  overflow-y: auto;
+  margin-right: -0.25rem;
+  padding-right: 0.25rem;
+}
+
+/* "添加文件夹"按钮容器 ── 挂在 folder 列表末尾 (folderEntries 非空
+ * 时), 或作为空态时唯一的引导 (folderEntries 空时)。 视觉上是 folder
+ * section 的自然延伸, 不是独立的全局操作 ── 用户打开弹窗扫到 folder
+ * 列表就能立刻看到"加一个"。
+ *
+ * 仅 margin-top: 4px 给一个柔和的呼吸空间, 不加 border-top 或 padding-
+ * top, 让按钮与 folder row 视觉连续。 长列表下跟随内容滚动, 不再被钉
+ * 在弹窗底部固定可见 ── 配合自定义 overlay scrollbar, Windows 下滚
+ * 动条体验与 mention 下拉同源。
+ *
+ * 演变: 顶部 actions → 底部 sticky footer → folder 区域末尾
+ *   - 顶部 actions: 用户先看到按钮再看列表, 视觉重音错位。
+ *   - 底部 sticky footer: 列表滚动时按钮被钉在弹窗底部固定可见, 长列
+ *     表下按钮与列表末尾分隔很远, 与 folder 语义割裂。
+ *   - 现在: 紧贴 folder 列表末尾, notebook section 之前, 按钮与 folder
+ *     section 视觉归属一致 ── 用户读完 folder 列表, 续上"加一个"再
+ *     去翻 notebook, 路径自然。 */
+.agent-composer__access-popover-footer {
+  margin-top: 4px;
+}
+
+.agent-composer__access-popover[hidden] {
+  display: none;
+}
+
+/* ── 笔记搜索下拉弹窗 ────────────────────────
+ * 独立挂在 document.body, 通过 JS 算 position: fixed 坐标 (top/left)
+ * 锚定到 composerRoleIcon button 上方/下方。 视觉与文档标题栏 "…more"
+ * 下拉菜单 (DropdownMenuContent) 同源 ── border / radius / box-shadow /
+ * padding / animation 全部对齐, 让"产品图标点击的下拉"在不同入口呈现
+ * 同一套容器视觉。
+ *
+ * 容器自身不写 max-height / overflow ── 由内层
+ * `.agent-composer__doc-search-list` 承担滚动, 让外层
+ * 跟随内容自然高, 弹窗 pop-in 动画 (fade + zoom-in) 不被裁切。
+ *
+ * composer add popover 是一级菜单；悬停「添加笔记」后，
+ * 笔记搜索弹窗在其右侧作为二级菜单。 */
+.agent-composer__note-popover {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 105;
+  width: 280px;
+  padding: 0.25rem;
+  border: 1px solid var(--border-popup);
+  border-radius: 0.75rem;
+  background: var(--card);
+  color: var(--agent-foreground);
+  /* 与消息输入框的模型 / 权限 / 空间设置弹窗使用同一套容器投影。 */
+  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
+  /* 弹窗入场动画 ── 与 DropdownMenuContent 的 animate-in fade-in-0
+   * zoom-in-95 同源: opacity 0→1 + scale 0.95→1, transform-origin
+   * top left (从 trigger 右上角弹出)。 */
+  opacity: 0;
+  transform: scale(0.95);
+  transform-origin: top left;
+  transition:
+    opacity 120ms ease,
+    transform 120ms ease;
+}
+
+.agent-composer__add-popover {
+  position: fixed;
+  /* Keep nested settings popovers above their parent add menu. */
+  z-index: 104;
+  width: 168px;
+  max-height: min(320px, calc(100vh - 16px));
+  overflow-y: auto;
+  padding: 0.25rem;
+  border: 1px solid var(--border-popup);
+  border-radius: 0.75rem;
+  background: var(--card);
+  color: var(--agent-foreground);
+  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
+}
+
+.agent-composer__add-popover[hidden] { display: none; }
+
+.agent-composer__add-item {
+  /* Layout, type, color and states come from the settings item above. */
+  gap: 8px;
+}
+
+.agent-composer__add-separator {
+  height: 1px;
+  margin: 0.25rem 0.375rem;
+  background: var(--border);
+  opacity: 0.7;
+}
+
+.agent-composer__add-chevron {
+  width: 15px;
+  height: 15px;
+  flex: 0 0 auto;
+  color: var(--muted-foreground);
+}
+
+.agent-composer__note-popover:not([hidden]) {
+  opacity: 1;
+  transform: scale(1);
+}
+
+.agent-composer__note-popover[hidden] {
+  display: none;
+}
+
+.agent-composer__note-popover-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  /* 对齐笔记列表下拉窗里 DropdownMenuLabel 的 padding
+   * (`memo-list.tsx` 里 sortLabel / filterLabel 的
+   * `px-[0.375rem] pb-[0.35rem] pt-[0.15rem]`) ── 让两个下拉窗
+   * 的 group label 视觉间距一致。 */
+  padding: 0.35rem 0.375rem 0.35rem;
+}
+
+.agent-composer__note-popover-title {
+  color: var(--muted-foreground);
+  /* 对齐 memo-list 的 sort label: text-xs font-normal leading-[1.2]
+   * ── 让笔记搜索弹窗的 group label 跟其它下拉窗
+   * 的 label 视觉密度一致。 */
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.2;
+}
+
+.agent-composer__note-popover-meta {
+  color: var(--muted-foreground);
+  font-size: 0.7rem;
+  line-height: 1.2;
+  font-variant-numeric: tabular-nums;
+  opacity: 0.75;
+}
+
+.agent-composer__access-empty {
+  padding: 12px 8px;
+  text-align: center;
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9); /* text-xs */
+}
+
+.agent-composer__access-section-label {
+  padding: 0.35rem 0.375rem 0.35rem;
+  color: var(--muted-foreground);
+  font-size: 0.75rem;
+  line-height: 1.2;
+  letter-spacing: 0;
+}
+
+.agent-composer__access-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 36px;
+  border-radius: 6px;
+  padding: 6px 8px;
+  transition: background-color 120ms ease;
+}
+
+/* row 整体不再 clickable ── 改用 cursor: default 让用户视觉上知道这块不是
+ * 按钮。 真正的交互入口只有 checkbox / star / remove, 鼠标移上去会自然
+ * 触发对应 button 的 hover 高亮 (CSS 已经处理)。 这里不再让整行 hover
+ * 也染色, 避免"整行像 button 但点了没反应"的误判。 */
+.agent-composer__access-row:hover {
+  background: transparent;
+}
+
+.agent-composer__access-row--disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+.agent-composer__access-row--disabled:hover {
+  background: transparent;
+}
+
+.agent-composer__access-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  flex: 0 0 auto;
+  border-radius: 8px;
+  background: var(--muted);
+  color: var(--secondary-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  font-weight: 600;
+}
+
+.agent-composer__access-avatar--icon {
+  background: var(--muted);
+  color: var(--secondary-foreground);
+}
+
+.agent-composer__access-avatar--icon svg {
+  display: block;
+  width: 72%;
+  height: 72%;
+  opacity: 0.9;
+}
+
+.agent-composer__access-row-icon {
+  width: 14px;
+  height: 14px;
+  color: var(--muted-foreground);
+}
+
+.agent-composer__access-name-wrap {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.agent-composer__access-name {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+}
+
+.agent-composer__access-alert-icon {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+  color: var(--warning);
+}
+
+.agent-composer__access-default-badge {
+  display: inline-flex;
+  align-items: center;
+  height: 20px;
+  flex: 0 0 auto;
+  border-radius: 8px;
+  background: var(--accent);
+  color: var(--primary);
+  padding: 0 6px;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+}
+
+.agent-composer__access-remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  flex: 0 0 auto;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  opacity: 0;
+  padding: 0;
+}
+
+.agent-composer__access-row:hover .agent-composer__access-remove,
+.agent-composer__access-remove:focus {
+  opacity: 1;
+}
+
+.agent-composer__access-remove:hover {
+  color: var(--destructive);
+}
+
+.agent-composer__access-remove .agent-icon__trash {
+  width: 14px;
+  height: 14px;
+}
+
+/* Workspace row 视觉 ── workspace entry (folder 或 notebook) 的 avatar 渲染
+ * 原图标 + 左侧竖长条标记 (.access-workspace-mark) 作为 "主空间" 标记
+ * (workspace 全局唯一), 不可点击。 非 workspace + 非 missing 的 entry
+ * (folder 或 notebook) 整个 avatar 就是一个 button, 点击直接 setWorkspace ──
+ * 不再 hover 出 star 按钮覆盖, 交互入口即图标本身。 */
+
+/* workspace avatar 不做特殊背景/颜色覆盖 ── 直接走基类 `.agent-composer__access-avatar`
+ * (背景 `var(--muted)` + 颜色 `var(--secondary-foreground)`); folder 图标走
+ * `.access-row-icon` 的 `var(--muted-foreground)`, notebook 图标走
+ * `.access-avatar--icon` ── 与同 kind 的普通 entry 视觉重量完全一致, "workspace"
+ * 这个角色标记只靠左侧竖长条体现, 不靠图标形状或颜色暗示。 avatar 设
+ * position/overflow, 让长条能贴左边缘定位; 长条自带全圆角呈胶囊形。 (不再用
+ * `--workspace svg` 统一 14px ── 那会误把 notebook 的 20px 图标也缩小;
+ * folder 图标尺寸由 `.access-row-icon` 自带, notebook 由 `--icon svg` 自带。) */
+
+.agent-composer__access-avatar--workspace {
+  position: relative;
+  overflow: hidden;
+  /* 已是主空间的 avatar 虽不可点击 (没有 set-workspace 入口), 也用 hand cursor ──
+   * 与同列其它 avatar 视觉一致, 避免 "选中后变箭头" 的突兀感。 */
+  cursor: pointer;
+}
+
+/* workspace 侧边标记 ── 贴 avatar 左边缘的竖长条, 用 var(--primary) 实色
+ * 填充, 作为 "主空间" 的标记。 3px 宽 × 12px 高, 上下居中 (top:50% +
+ * translateY(-50%)); 仅右侧上下圆角 (border-radius:0 9999px 9999px 0, 受
+ * 3px 宽限制实际半径 1.5px 呈右半圆), 左侧贴 avatar 边缘保持直角, 既能
+ * 一眼识别又不喧宾夺主。 pointer-events:none 让标记不挡 avatar 上的点击。 */
+.agent-composer__access-workspace-mark {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  width: 3px;
+  height: 12px;
+  transform: translateY(-50%);
+  background: var(--primary);
+  border-radius: 0 9999px 9999px 0;
+  pointer-events: none;
+}
+
+/* The notebook sidebar uses a right-aligned star, which is a different
+ * affordance from the legacy avatar-side workspace mark above. Keep it in the
+ * row's flex flow so it stays at the far right after the flexible name cell. */
+.agent-composer__access-workspace-star {
+  position: static;
+  flex: 0 0 auto;
+  color: var(--primary);
+}
+
+/* 可点击 avatar ── 非 workspace + 非 missing 的 entry (folder 或 notebook)
+ * avatar 本身是 <button>, 点击 setWorkspace。 不再有 star 按钮覆盖层: hover
+ * 只给一层 primary 薄底提示 "这个图标可点", 视觉重量与普通 avatar 一致。
+ * button 重置 (border/padding) 走这里; 背景/颜色/尺寸/圆角都复用基类
+ * `.agent-composer__access-avatar`。 */
+.agent-composer__access-avatar--set-workspace {
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+  transition: background-color 120ms ease;
+}
+
+.agent-composer__access-avatar--set-workspace:hover {
+  background: color-mix(in oklch, var(--primary) 14%, var(--muted));
+}
+
+.agent-composer__access-checkbox {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  flex: 0 0 auto;
+  border: 1px solid var(--muted-foreground);
+  border-radius: 4px;
+  background: transparent;
+  color: var(--primary-foreground);
+  cursor: pointer;
+  padding: 0;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+}
+
+.agent-composer__access-checkbox--checked {
+  border-color: var(--primary);
+  background: var(--primary);
+}
+
+.agent-composer__access-checkbox-mark {
+  width: 11px;
+  height: 9px;
+  color: var(--primary-foreground);
+}
+
+.agent-composer__access-checkbox:disabled {
+  cursor: not-allowed;
+}
+
+.agent-composer__access-add {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  min-width: 0;
+  margin: 0;
+  min-height: 28px;
+  padding: 2px 8px;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1;
+  text-align: left;
+  box-sizing: border-box;
+  user-select: none;
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+.agent-composer__access-add:hover {
+  background: var(--brand);
+  color: var(--primary-foreground);
+}
+
+.agent-composer__access-add-icon-wrap {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  flex: 0 0 auto;
+  border-radius: 6px;
+  background: var(--muted);
+  color: var(--secondary-foreground);
+}
+
+.agent-composer__access-add-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-composer__access-add-icon {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  color: currentColor;
+}
+/* Note search menu and shared composer badge styles. */
+
+.agent-composer__note-result {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-width: 0;
+  min-height: 28px;
+  padding: 2px 8px;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--agent-foreground);
+  cursor: pointer;
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1.2;
+  text-align: left;
+  box-sizing: border-box;
+  user-select: none;
+  transition: background-color 120ms ease;
+}
+
+.agent-composer__note-result
+  + .agent-composer__note-result {
+  margin-top: 2px;
+}
+
+.agent-composer__note-result:hover {
+  background: var(--brand);
+  color: var(--primary-foreground);
+}
+
+.agent-composer__note-empty {
+  padding: 6px 8px;
+  color: var(--muted-foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9);
+}
+
+/* Search field for indexed notebook notes. */
+.agent-composer__note-search {
+  display: block;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 6px 8px 8px;
+  margin: 4px 0 0;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  color: var(--agent-foreground);
+  font: inherit;
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  line-height: 1.2;
+  outline: none;
+}
+
+.agent-composer__note-search::placeholder {
+  color: var(--muted-foreground);
+  opacity: 0.85;
+}
+.agent-composer__note-search:focus::placeholder {
+  opacity: 0.6;
+}
+.flowix-notebook-selector-search:focus::placeholder {
+  opacity: 0.85;
+}
+
+/* 列表容器 — 仅承担垂直 padding, 不画外框; 水平方向不加 padding,
+ * 让 item 自身的 6px 8px padding 与菜单项对齐。容器自身
+ * 设置 max-height + overflow-y, 当 hits 数量过多时弹窗内部可滚动,
+ * 而外层容器 pop-in 动画 (fade + zoom-in) 不被裁切。
+ *
+ * 不再保留底部 4px padding ── 跟弹窗自身的 padding-bottom (4px) 重复,
+ * 视觉上等于"列表底部"出现了 8px 空档, 与 DropdownMenuContent
+ * (`py-1` = 4px 上下) 的紧凑节奏不一致。 改为 padding-top: 2px 即可,
+ * 顶部留 2px 让第一项与上方分隔线之间有呼吸感。 */
+.agent-composer__note-search-list {
+  display: block;
+  max-height: 320px;
+  overflow-y: auto;
+  margin-right: -0.25rem;
+  padding: 2px 0.25rem 0 0;
+}
+/* 容器内第一组 header 紧贴其上方分隔线, 但标签自身上下 padding 保持对称。 */
+.agent-composer__note-search-list
+  > .agent-composer__note-popover-header {
+  padding-top: 0.35rem;
+  margin-top: 4px;
+}
+.agent-composer__note-search-list
+  > .agent-composer__note-popover-header:first-child {
+  padding-top: 0.35rem;
+  margin-top: 0;
+}
+
+.agent-conversation-surface .agent-composer__send {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--atc-send-size);
+  height: var(--atc-send-size);
+  flex: 0 0 auto;
+  border: 0;
+  border-radius: 9999px;
+  background: var(--primary);
+  color: var(--primary-foreground);
+  cursor: pointer;
+}
+
+.agent-conversation-surface .agent-composer__send:hover:not(:disabled) {
+  background: color-mix(in oklch, var(--primary) 88%, var(--foreground) 12%);
+}
+
+.agent-conversation-surface .agent-composer__send-tooltip {
+  display: inline-flex;
+  flex: 0 0 auto;
+  line-height: 0;
+}
+
+.agent-conversation-surface .agent-composer__send:disabled {
+  cursor: not-allowed;
+}
+
+/* 未输入内容时: 跟 inputbox 同步, 走 muted 色变, 不再依赖 opacity 半透明。
+ * --stop 变体由 :not() 排除, 保持 warning 全亮 ── 停止按钮在 loading 期间
+ * 仍需"亮"以传达"这是可点击的停止动作", 与 inputbox 中 isLoading 时强制
+ * canSend=false 但视觉走 dim 的逻辑不同, 这里停止按钮是 dim→亮态的逆例。
+ *
+ * 图标色用 muted-foreground ── 与 muted 背景同色系, 形成'暗底 + 灰图标'
+ * 的纯灰 dim 关系, 不再保留 primary 色相。 */
+.agent-conversation-surface
+  .agent-composer__send:disabled:not(.agent-composer__send--stop) {
+  background: var(--muted);
+  color: var(--muted-foreground);
+}
+
+/* Send icon stays legible inside the compact composer action button. */
+.agent-conversation-surface .agent-composer__send-icon {
+  display: block;
+  width: 15px;
+  height: 15px;
+  flex: 0 0 auto;
+  color: currentColor;
+}
+
+.agent-conversation-surface .agent-composer__send--stop {
+  background: var(--warning);
+  color: var(--floating-foreground);
+}
+
+.agent-conversation-surface .agent-composer__send--running {
+  background: var(--muted);
+  color: var(--muted-foreground);
+  cursor: wait;
+}
+
+.agent-conversation-surface .agent-composer__send--running.agent-composer__send--stop {
+  background: var(--warning);
+  color: var(--floating-foreground);
+  cursor: pointer;
+}
+
+.agent-conversation-surface .agent-composer__send-spinner {
+  display: block;
+  width: 13px;
+  height: 13px;
+  border: 2px solid color-mix(in srgb, currentColor 28%, transparent);
+  border-top-color: currentColor;
+  border-radius: 50%;
+  --flowix-spin-duration: 0.8s;
+}
+
+.agent-conversation-surface
+  .agent-composer__send.agent-composer__send--stop:hover:not(:disabled) {
+  background: var(--warning);
+  filter: brightness(1.08);
+}
diff --git a/app/flowix-web/styles/agent-conversation/titlebar.css b/app/flowix-web/styles/agent-conversation/titlebar.css
new file mode 100644
index 000000000..fb08e4a41
--- /dev/null
+++ b/app/flowix-web/styles/agent-conversation/titlebar.css
@@ -0,0 +1,138 @@
+/* Shared conversation identity used by standalone and fullscreen surfaces. */
+.agent-type-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  box-sizing: border-box;
+  flex: 0 0 auto;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 9999px;
+  background: transparent;
+  cursor: default;
+  user-select: none;
+  transition: border-color 180ms ease;
+}
+
+.agent-type-badge--unavailable {
+  border-color: color-mix(in oklch, var(--border) 70%, transparent);
+  color: var(--muted-foreground);
+  opacity: 0.6;
+}
+
+.agent-type-badge__icon {
+  display: block;
+  width: 0.875rem;
+  height: 0.875rem;
+  flex: 0 0 auto;
+  object-fit: contain;
+  object-position: center;
+  border: 0 !important;
+  border-radius: 0 !important;
+  margin-bottom: 0 !important;
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: contain;
+}
+
+.agent-type-badge__icon--image {
+  background-image: var(--agent-icon-src);
+}
+
+.agent-type-badge__icon--unavailable {
+  filter: grayscale(1);
+}
+
+.agent-type-badge__name[hidden] {
+  display: none;
+}
+
+.agent-type-badge__name {
+  display: inline-block;
+  color: var(--foreground);
+  font-size: calc(var(--font-size, 16px) * 0.9);
+  font-weight: 400;
+  line-height: 1;
+  letter-spacing: 0;
+  white-space: nowrap;
+}
+
+.agent-type-badge--unavailable .agent-type-badge__name {
+  color: var(--muted-foreground);
+}
+
+.agent-conversation-identity {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 8px;
+}
+
+.agent-conversation-identity__badge-anchor {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+  -webkit-app-region: no-drag;
+}
+
+.agent-conversation-identity__badge-trigger {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: block;
+  border-radius: inherit;
+  background: transparent;
+  cursor: pointer;
+  -webkit-app-region: no-drag;
+}
+
+.agent-conversation-identity__title,
+.agent-conversation-identity__title-wrap {
+  min-width: 0;
+  flex: 0 1 auto;
+  overflow: hidden;
+  border-radius: 4px;
+  padding: 4px 2px;
+  color: var(--foreground);
+  font-size: 0.875rem;
+  font-weight: 600;
+  line-height: 1;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  -webkit-app-region: no-drag;
+}
+
+.agent-conversation-identity__title {
+  cursor: default;
+  transition: background-color 120ms ease;
+}
+
+.agent-conversation-identity__title:hover,
+.agent-conversation-identity__title-wrap:hover,
+.agent-conversation-identity__title-wrap:focus-within {
+  background: var(--muted);
+}
+
+.agent-conversation-identity__title-input {
+  width: auto;
+  max-width: 100%;
+  min-width: 0;
+  height: 14px;
+  border: 0;
+  border-radius: 0;
+  padding: 0;
+  background: transparent;
+  color: inherit;
+  cursor: text;
+  font: inherit;
+  line-height: 1;
+  outline: none;
+  field-sizing: content;
+}
+
+.agent-conversation-identity__badge-trigger:hover ~ .agent-type-badge .agent-type-badge__name,
+.agent-conversation-identity__badge-trigger[data-state="open"] ~ .agent-type-badge .agent-type-badge__name {
+  color: var(--foreground);
+}
diff --git a/app/flowix-web/styles/agent-thread-card/background-terminals.css b/app/flowix-web/styles/agent-thread-card/background-terminals.css
new file mode 100644
index 000000000..a8cfe7f11
--- /dev/null
+++ b/app/flowix-web/styles/agent-thread-card/background-terminals.css
@@ -0,0 +1,182 @@
+/* Codex background terminals sit in the small layer immediately above the
+ * composer.  Keep the collapsed row monospace and single-line so it reads as
+ * process status rather than another chat message. */
+.agent-conversation-surface .agent-background-terminals {
+  --background-terminal-overlap: 1.15rem;
+  /* Status surface: one restrained step darker than the paper composer.
+   * Keep this in OKLCH so the same perceived contrast survives theme changes. */
+  --agent-status-bg: var(--agent-status-surface, color-mix(in oklch, var(--document-bg) 94%, var(--foreground) 6%));
+  position: relative;
+  z-index: 0;
+  align-self: end;
+  width: calc(100% - 3rem);
+  max-width: 780px;
+  /* The terminal strip is a back plate for the composer. Its padded lower
+   * edge slides underneath the composer so the two controls read as one
+   * connected surface, matching the reference layout. */
+  margin: 0 auto calc(-1 * var(--background-terminal-overlap));
+  padding-bottom: var(--background-terminal-overlap);
+  overflow: hidden;
+  border: 1px solid var(--border);
+  border-radius: 1rem 1rem 0.75rem 0.75rem;
+  background: var(--agent-status-bg);
+  color: var(--muted-foreground);
+  font-family: var(--code-font-family);
+  font-size: 0.75rem;
+  box-sizing: border-box;
+}
+
+.agent-conversation-detail__composer-stack > div:last-child {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  width: 100%;
+}
+
+.agent-background-terminals__summary {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  min-width: 0;
+  height: 2rem;
+  gap: 0.5rem;
+  padding: 0 0.75rem;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.agent-background-terminals__summary:hover { background: color-mix(in oklch, var(--accent) 54%, transparent); }
+.agent-background-terminals__summary:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: -2px;
+}
+.agent-background-terminals__dot,
+.agent-background-terminals__status { width: 0.4rem; height: 0.4rem; flex: 0 0 auto; border-radius: 999px; background: var(--success); }
+.agent-background-terminals__label { flex: 0 0 auto; color: var(--foreground); }
+.agent-background-terminals__command { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; opacity: 0.72; }
+.agent-background-terminals__chevron { width: 1rem; height: 1rem; flex: 0 0 auto; margin-left: auto; transition: transform 160ms ease; }
+.agent-background-terminals[data-expanded='true'] .agent-background-terminals__chevron { transform: rotate(180deg); }
+.agent-background-terminals__details {
+  border-top: 0;
+  padding: 0 0.75rem;
+  background: transparent;
+}
+.agent-background-terminals__row {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  gap: 0.5rem;
+  height: 2rem;
+  line-height: 1.25;
+}
+.agent-background-terminals__row code {
+  overflow: hidden;
+  color: var(--foreground);
+  opacity: 0.72;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.agent-background-terminals__cwd { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; opacity: 0.55; }
+.agent-background-terminals__state { margin-left: auto; opacity: 0.65; }
+.agent-background-terminals__queue {
+  display: grid;
+  gap: 0;
+  padding: 0 0.75rem;
+  background: transparent;
+}
+.agent-background-terminals__queue-row {
+  display: flex;
+  min-width: 0;
+  gap: 0.38rem;
+  align-items: center;
+  height: 2rem;
+  padding: 0;
+  line-height: 1.25;
+}
+.agent-background-terminals__queue-text {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--foreground);
+  opacity: 1;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.agent-background-terminals__queue-mark {
+  display: inline-flex;
+  flex: 0 0 auto;
+  color: var(--primary);
+}
+.agent-background-terminals__queue-mark svg {
+  display: block;
+  width: 0.75rem;
+  height: 0.75rem;
+}
+.agent-background-terminals__queue-actions {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 0.2rem;
+  margin-left: auto;
+}
+.agent-background-terminals__queue-steer,
+.agent-background-terminals__queue-delete {
+  box-sizing: border-box;
+  flex: 0 0 auto;
+  height: 1.32rem;
+  border-radius: 0.55rem;
+  padding: 0 0.4rem;
+  font-size: 0.7rem;
+  line-height: 1;
+  color: var(--primary);
+  background: transparent;
+}
+.agent-background-terminals__queue-steer:not(:disabled):hover,
+.agent-background-terminals__queue-delete:not(:disabled):hover {
+  background: color-mix(in srgb, var(--primary) 18%, transparent);
+}
+.agent-background-terminals__queue-steer:focus-visible,
+.agent-background-terminals__queue-delete:focus-visible {
+  outline: 2px solid var(--primary);
+  outline-offset: 2px;
+}
+.agent-background-terminals__queue-delete {
+  display: inline-flex;
+  width: auto;
+  align-items: center;
+  justify-content: center;
+}
+.agent-background-terminals__queue-soon {
+  flex: 0 0 auto;
+  color: var(--primary);
+  font-size: 0.7rem;
+}
+.agent-thread-card__queued-messages { margin: 0 0 -1.15rem; }
+
+/* Approval uses the same process strip and the same composer stack slot. The
+ * approval modifier intentionally adds no outer-surface styles: border,
+ * radius, background, width, overlap and stacking all come from the process
+ * strip above. */
+.agent-background-terminals__approval { display: flex; align-items: center; min-width: 0; gap: 0.6rem; padding: 0.6rem 0.75rem; }
+.agent-background-terminals__approval-dot { width: 0.45rem; height: 0.45rem; flex: 0 0 auto; border-radius: 999px; background: var(--primary); box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary) 14%, transparent); }
+.agent-background-terminals__approval-copy { display: flex; min-width: 0; flex: 1; align-items: baseline; gap: 0.55rem; overflow: hidden; font-size: 0.72rem; }
+.agent-background-terminals__approval-copy strong { flex: 0 0 auto; color: var(--foreground); font-size: 0.78rem; }
+.agent-background-terminals__approval-copy span { flex: 0 0 auto; color: var(--muted-foreground); }
+.agent-background-terminals__approval-copy code { min-width: 0; overflow: hidden; color: var(--foreground); text-overflow: ellipsis; white-space: nowrap; opacity: 0.78; }
+.agent-background-terminals__approval-error { flex-basis: 100%; color: var(--destructive); font-size: 0.68rem; }
+.agent-background-terminals__approval-actions { display: flex; flex: 0 0 auto; gap: 0.35rem; }
+.agent-background-terminals__approval-actions button { min-height: 1.27rem; border: 1px solid var(--border); border-radius: 0.6rem; padding: 0.15rem 0.2rem; background: transparent; color: var(--muted-foreground); font-size: 0.72rem; font-weight: 600; cursor: pointer; }
+.agent-background-terminals__approval-actions button:hover { background: var(--muted); color: var(--foreground); }
+.agent-background-terminals__approval-actions button:last-child { border-color: var(--primary); background: var(--primary); color: var(--primary-foreground); }
+.agent-background-terminals__approval-actions button:last-child:hover { opacity: 0.88; }
+
+@media (max-width: 560px) {
+  .agent-background-terminals__approval { align-items: flex-start; flex-wrap: wrap; }
+  .agent-background-terminals__approval-copy { flex-basis: calc(100% - 1.2rem); flex-wrap: wrap; gap: 0.2rem 0.45rem; }
+  .agent-background-terminals__approval-copy code { flex-basis: 100%; }
+  .agent-background-terminals__approval-actions { width: 100%; margin-left: 1.05rem; }
+  .agent-background-terminals__approval-actions button { flex: 1; }
+}
diff --git a/app/flowix-web/styles/agent-thread-card/chrome.css b/app/flowix-web/styles/agent-thread-card/chrome.css
index 80fb22242..bc334ef7c 100644
--- a/app/flowix-web/styles/agent-thread-card/chrome.css
+++ b/app/flowix-web/styles/agent-thread-card/chrome.css
@@ -7,75 +7,6 @@
   --atc-header-h: 40px;
 }
 
-.agent-type-badge {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 1.25rem; /* h-5 w-5 = 20px ── 跟按钮 28px / chevron 14px 视觉节奏
-                   * 匹配; header 总高 40px, 20px 方形 icon 居中后上下
-                   * 各留 10px 呼吸, 不顶到 header 边缘。 */
-  height: 1.25rem;
-  padding: 0;
-  box-sizing: border-box;
-  border: 1px solid var(--border);
-  border-radius: 9999px;
-  background: transparent;
-  flex: 0 0 auto;
-  user-select: none;
-  cursor: default;
-  transition: border-color 180ms ease;
-}
-
-.agent-type-badge--unavailable {
-  border-color: color-mix(in oklch, var(--border) 70%, transparent);
-  color: var(--muted-foreground);
-  opacity: 0.6;
-}
-
-.agent-type-badge__icon {
-  display: block;
-  width: 0.875rem; /* 14px ── 20px 方块留 3px 内边距, 视觉重量跟
-                    * 28px 按钮 + 14px icon 节奏一致。 */
-  height: 0.875rem;
-  flex: 0 0 auto;
-  object-fit: contain;
-  object-position: center;
-  border: 0 !important;
-  border-radius: 0 !important;
-  margin-bottom: 0 !important;
-  background-position: center;
-  background-repeat: no-repeat;
-  background-size: contain;
-}
-
-.agent-type-badge__icon--image {
-  background-image: var(--agent-icon-src);
-}
-
-.agent-type-badge__icon--unavailable {
-  filter: grayscale(1);
-}
-
-/* __name 元素在 header 中 hidden (badge 改为纯 icon), 样式只留
- * 兜底: 任何意外显示的实例也不会撑破 badge 容器。 */
-.agent-type-badge__name[hidden] {
-  display: none;
-}
-
-.agent-type-badge__name {
-  display: inline-block;
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
-  line-height: 1;
-  font-weight: 400; /* 明确非加粗 ── 不被父级 600 继承 */
-  color: var(--foreground);
-  white-space: nowrap;
-  letter-spacing: 0;
-}
-
-.agent-type-badge--unavailable .agent-type-badge__name {
-  color: var(--muted-foreground);
-}
-
 .markdown-editor
   .agent-thread-card--running
   .agent-type-badge:not(.agent-type-badge--unavailable) {
@@ -101,14 +32,14 @@
 }
 
 .markdown-editor .agent-thread-card {
-  margin: 0 0 calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.32);
+  margin: 0 0 calc(var(--font-size, 16px) * var(--font-line-height, 1.8) * 0.32);
   background: transparent;
   /* Messages and card chrome use the product font even though this NodeView
    * is nested inside a user-configurable Tiptap document. The nested composer
-   * is itself a Tiptap editor and opts into --app-font-family separately. */
+   * is itself a Tiptap editor and opts into --editor-font-family separately. */
   font-family: var(--font-sans);
-  font-size: var(--app-font-size, 15px);
-  line-height: var(--app-line-height, 1.6);
+  font-size: var(--font-size, 16px);
+  line-height: var(--font-line-height, 1.6);
   color: var(--foreground);
   tab-size: 5;
   cursor: default;
@@ -259,7 +190,7 @@
  *   (现代浏览器 outline 已支持 border-radius, 但显式写更稳)
  * - 选择器特异性: .agent-thread-card.ProseMirror-selectednode = (0,2,0)
  *   高于全局 .ProseMirror-selectednode = (0,1,0), 本规则胜出 */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .agent-thread-card.ProseMirror-selectednode {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .agent-thread-card.ProseMirror-selectednode {
   outline: 1px solid var(--brand);
   outline-offset: -1px;
   border-radius: 8px;
@@ -319,7 +250,7 @@
 
 /* 左侧: agent-type-badge (icon + role 名) + 对话标题 单行排版, 整体
  * flex 1 让 meta 推到右边。role 名称已迁出到 badge 内, 这里只剩 title。
- * badge 样式见本文件顶部的 .agent-type-badge 块, 这里只负责外层布局。 */
+ * badge 样式由共享 agent-conversation/titlebar.css 提供, 这里只负责外层布局。 */
 .markdown-editor .agent-thread-card__agent {
   display: flex;
   align-items: center;
@@ -350,7 +281,7 @@
   overflow: hidden;
   color: var(--foreground);
   cursor: grab;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(var(--font-size, 16px) * 0.9);
   font-weight: 600;
   line-height: 1;
   text-overflow: ellipsis;
@@ -395,7 +326,7 @@
   flex: 0 0 auto;
   gap: 6px;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
+  font-size: calc(var(--font-size, 16px) * 0.9); /* text-xs */
   line-height: 1;
   white-space: nowrap;
 }
@@ -409,7 +340,7 @@
   padding: 0;
   background: transparent;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
+  font-size: calc(var(--font-size, 16px) * 0.9); /* text-xs */
   font-weight: 500;
   line-height: 1;
   letter-spacing: 0;
diff --git a/app/flowix-web/styles/agent-thread-card/composer.css b/app/flowix-web/styles/agent-thread-card/composer.css
deleted file mode 100644
index 501d14ffb..000000000
--- a/app/flowix-web/styles/agent-thread-card/composer.css
+++ /dev/null
@@ -1,1207 +0,0 @@
-/* composer 圆角胶囊容器 ── grid auto 行, 高度由内容决定 (auto 行
- * 在子元素 display: none 时收缩到 0, 这是折叠态没有空白区块的关键)。
- * 外层 max-height: --atc-composer-max-h (200px) 兜底封顶; 内部
- * contenteditable 编辑器在自身 max-height (= 外层 max-height - padding-y)
- * 下, 内容超出时走 overflow-y 内部滚动,
- * composer 容器不被撑破。
- *
- * 背景使用 var(--input-bg) ── 输入面与文档背景解耦, 浅色模式统一为白色;
- * 1px border 保留, 仍能围出胶囊形状; 编辑器自身 transparent, 直接
- * 透出 composer 背景。多行状态由 .--multi-line 修饰类切到 flex-end
- * (按钮贴底, 始终维持 --atc-bottom-pad 距离)。 类切换由 agent-thread-card.tsx
- * 的 input 事件控制。 */
-.markdown-editor .agent-thread-card__composer {
-  position: relative;
-  display: flex;
-  align-items: center;
-  gap: 5px;
-  align-self: end;
-  width: calc(100% - 24px);
-  /* 这是 container 的 grid item; min-width:auto 会把编辑器的
-   * content-sized min-content 宽度带回 grid，长连续字符串因此可能把
-   * composer 撑出卡片。明确允许它在 grid track 内收缩。 */
-  min-width: 0;
-  max-width: calc(100% - 24px);
-  margin: 0 0.8rem 0.6rem;
-  padding: 0 0.4rem 0 0.8rem;
-  border: 1px solid var(--border);
-  border-radius: 1rem;
-  background: var(--input-bg, var(--document-bg));
-  /* Keep the composer lighter than the Slash menu while
-   * keeping a shorter offset for the composer sitting against the canvas edge. */
-  box-shadow: 0 2px 24px -3px rgb(0 0 0 / 3%);
-  box-sizing: border-box;
-  max-height: 15rem;
-  user-select: none;
-  /* ── 空区域点击聚焦的视觉暗示 ──
-   * composer 容器大部分位置都是编辑器之外的"占位", 用户不知道点
-   * 这里能把键盘焦点抢回输入框; 默认 cursor: auto / default 看起来
-   * 像死区。 给容器本体的"非交互元素"位置统一标 text 光标, 配合
-   * composer-dom-factory.ts 里的 pointerdown 委托, 形成"整片都是
-   * 输入区"的体感。
-   *
-   * 用 :where() 选非交互后代让优先级保持在 0, 不压过下面的 button /
-   * image-remove 等子选择器 ── 按钮仍是 pointer 光标。 */
-  cursor: text;
-}
-
-/* The card sets `cursor: default` on every descendant. Keep the editable
- * ProseMirror surface text-like as well; the interactive controls below
- * restore their pointer cursor later in this stylesheet. */
-.markdown-editor .agent-thread-card__composer-input,
-.markdown-editor .agent-thread-card__composer-input :where(*) {
-  cursor: text;
-}
-
-/* 非全屏单行 composer 的外层高度基线。仅约束输入框容器，不改变
- * Tiptap 编辑器自身的内容高度；左右操作按钮以该容器为基准垂直居中。 */
-.markdown-editor
-.agent-thread-card:not(.agent-thread-card--fullscreen)
-  .agent-thread-card__composer {
-  min-height: 42px;
-  padding-top: 6px;
-  padding-bottom: 6px;
-}
-
-/* Codex background terminals sit in the small layer immediately above the
- * composer.  Keep the collapsed row monospace and single-line so it reads as
- * process status rather than another chat message. */
-.markdown-editor .agent-background-terminals {
-  --background-terminal-overlap: 1.15rem;
-  /* Status surface: one restrained step darker than the paper composer.
-   * Keep this in OKLCH so the same perceived contrast survives theme changes. */
-  --agent-status-bg: var(--agent-status-surface, color-mix(in oklch, var(--document-bg) 94%, var(--foreground) 6%));
-  position: relative;
-  z-index: 0;
-  align-self: end;
-  width: calc(100% - 3rem);
-  max-width: 780px;
-  /* The terminal strip is a back plate for the composer. Its padded lower
-   * edge slides underneath the composer so the two controls read as one
-   * connected surface, matching the reference layout. */
-  margin: 0 auto calc(-1 * var(--background-terminal-overlap));
-  padding-bottom: var(--background-terminal-overlap);
-  overflow: hidden;
-  border: 1px solid var(--border);
-  border-radius: 1rem 1rem 0.75rem 0.75rem;
-  background: var(--agent-status-bg);
-  color: var(--muted-foreground);
-  font-family: var(--code-font-family);
-  font-size: 0.75rem;
-  box-sizing: border-box;
-}
-
-.agent-conversation-detail__composer-stack > div:last-child {
-  position: relative;
-  z-index: 1;
-  display: flex;
-  width: 100%;
-}
-
-.agent-background-terminals__summary {
-  display: flex;
-  align-items: center;
-  width: 100%;
-  min-width: 0;
-  height: 2rem;
-  gap: 0.5rem;
-  padding: 0 0.75rem;
-  border: 0;
-  background: transparent;
-  color: inherit;
-  text-align: left;
-  cursor: pointer;
-}
-
-.agent-background-terminals__summary:hover { background: color-mix(in oklch, var(--accent) 54%, transparent); }
-.agent-background-terminals__summary:focus-visible {
-  outline: 2px solid var(--ring);
-  outline-offset: -2px;
-}
-.agent-background-terminals__dot,
-.agent-background-terminals__status { width: 0.4rem; height: 0.4rem; flex: 0 0 auto; border-radius: 999px; background: var(--success); }
-.agent-background-terminals__label { flex: 0 0 auto; color: var(--foreground); }
-.agent-background-terminals__command { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; opacity: 0.72; }
-.agent-background-terminals__chevron { width: 1rem; height: 1rem; flex: 0 0 auto; margin-left: auto; transition: transform 160ms ease; }
-.agent-background-terminals[data-expanded='true'] .agent-background-terminals__chevron { transform: rotate(180deg); }
-.agent-background-terminals__details {
-  border-top: 0;
-  padding: 0 0.75rem;
-  background: transparent;
-}
-.agent-background-terminals__row {
-  display: flex;
-  align-items: center;
-  min-width: 0;
-  gap: 0.5rem;
-  height: 2rem;
-  line-height: 1.25;
-}
-.agent-background-terminals__row code {
-  overflow: hidden;
-  color: var(--foreground);
-  opacity: 0.72;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-.agent-background-terminals__cwd { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; opacity: 0.55; }
-.agent-background-terminals__state { margin-left: auto; opacity: 0.65; }
-.agent-background-terminals__queue {
-  display: grid;
-  gap: 0;
-  padding: 0 0.75rem;
-  background: transparent;
-}
-.agent-background-terminals__queue-row {
-  display: flex;
-  min-width: 0;
-  gap: 0.38rem;
-  align-items: center;
-  height: 2rem;
-  padding: 0;
-  line-height: 1.25;
-}
-.agent-background-terminals__queue-text {
-  flex: 1 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  color: var(--foreground);
-  opacity: 1;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-.agent-background-terminals__queue-mark {
-  display: inline-flex;
-  flex: 0 0 auto;
-  color: var(--primary);
-}
-.agent-background-terminals__queue-mark svg {
-  display: block;
-  width: 0.75rem;
-  height: 0.75rem;
-}
-.agent-background-terminals__queue-actions {
-  display: inline-flex;
-  flex: 0 0 auto;
-  align-items: center;
-  gap: 0.2rem;
-  margin-left: auto;
-}
-.agent-background-terminals__queue-steer,
-.agent-background-terminals__queue-delete {
-  box-sizing: border-box;
-  flex: 0 0 auto;
-  height: 1.32rem;
-  border-radius: 0.55rem;
-  padding: 0 0.4rem;
-  font-size: 0.7rem;
-  line-height: 1;
-  color: var(--primary);
-  background: transparent;
-}
-.agent-background-terminals__queue-steer:not(:disabled):hover,
-.agent-background-terminals__queue-delete:not(:disabled):hover {
-  background: color-mix(in srgb, var(--primary) 18%, transparent);
-}
-.agent-background-terminals__queue-steer:focus-visible,
-.agent-background-terminals__queue-delete:focus-visible {
-  outline: 2px solid var(--primary);
-  outline-offset: 2px;
-}
-.agent-background-terminals__queue-delete {
-  display: inline-flex;
-  width: 1.32rem;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-}
-.agent-background-terminals__queue-delete svg {
-  display: block;
-  width: 0.875rem;
-  height: 0.875rem;
-}
-.agent-background-terminals__queue-soon {
-  flex: 0 0 auto;
-  color: var(--primary);
-  font-size: 0.7rem;
-}
-.agent-thread-card__queued-messages { margin: 0 0 -1.15rem; }
-
-/* Approval uses the same process strip and the same composer stack slot. The
- * approval modifier intentionally adds no outer-surface styles: border,
- * radius, background, width, overlap and stacking all come from the process
- * strip above. */
-.agent-background-terminals__approval { display: flex; align-items: center; min-width: 0; gap: 0.6rem; padding: 0.6rem 0.75rem; }
-.agent-background-terminals__approval-dot { width: 0.45rem; height: 0.45rem; flex: 0 0 auto; border-radius: 999px; background: var(--primary); box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary) 14%, transparent); }
-.agent-background-terminals__approval-copy { display: flex; min-width: 0; flex: 1; align-items: baseline; gap: 0.55rem; overflow: hidden; font-size: 0.72rem; }
-.agent-background-terminals__approval-copy strong { flex: 0 0 auto; color: var(--foreground); font-size: 0.78rem; }
-.agent-background-terminals__approval-copy span { flex: 0 0 auto; color: var(--muted-foreground); }
-.agent-background-terminals__approval-copy code { min-width: 0; overflow: hidden; color: var(--foreground); text-overflow: ellipsis; white-space: nowrap; opacity: 0.78; }
-.agent-background-terminals__approval-error { flex-basis: 100%; color: var(--destructive); font-size: 0.68rem; }
-.agent-background-terminals__approval-actions { display: flex; flex: 0 0 auto; gap: 0.35rem; }
-.agent-background-terminals__approval-actions button { min-height: 1.27rem; border: 1px solid var(--border); border-radius: 0.6rem; padding: 0.15rem 0.2rem; background: transparent; color: var(--muted-foreground); font-size: 0.72rem; font-weight: 600; cursor: pointer; }
-.agent-background-terminals__approval-actions button:hover { background: var(--muted); color: var(--foreground); }
-.agent-background-terminals__approval-actions button:last-child { border-color: var(--primary); background: var(--primary); color: var(--primary-foreground); }
-.agent-background-terminals__approval-actions button:last-child:hover { opacity: 0.88; }
-
-@media (max-width: 560px) {
-  .agent-background-terminals__approval { align-items: flex-start; flex-wrap: wrap; }
-  .agent-background-terminals__approval-copy { flex-basis: calc(100% - 1.2rem); flex-wrap: wrap; gap: 0.2rem 0.45rem; }
-  .agent-background-terminals__approval-copy code { flex-basis: 100%; }
-  .agent-background-terminals__approval-actions { width: 100%; margin-left: 1.05rem; }
-  .agent-background-terminals__approval-actions button { flex: 1; }
-}
-
-.markdown-editor .agent-thread-card__composer :where(
-  button,
-  a,
-  [role='button'],
-  .agent-thread-card__composer-image-remove,
-  .agent-thread-card__composer-add-button,
-  .agent-thread-card__composer-model,
-  .agent-thread-card__composer-mode,
-  .agent-thread-card__composer-permission,
-  .agent-thread-card__composer-workspace
-) {
-  cursor: pointer;
-}
-
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__composer {
-  width: calc(100% - 3rem);
-  max-width: 780px;
-  margin: 0 auto 0.6rem;
-  /* 全屏态: 宽度 / margin 与基线不同; 背景由基线 var(--document-bg) 提供,
-   * 不再覆盖, 全屏 / 非全屏视觉一致。 */
-}
-
-.markdown-editor .agent-thread-card__composer--multi-line {
-  align-items: flex-end;
-}
-
-/* 非全屏输入内容变多时，输入编辑器可以继续增高，但两侧操作按钮
- * 仍应相对整个 composer 上下居中；底部对齐只保留给 expanded composer
- * 的独立操作行布局。 */
-.markdown-editor
-  .agent-thread-card__composer:not(.agent-composer--expanded)
-  .agent-thread-card__composer--multi-line {
-  align-items: center;
-}
-
-.markdown-editor .agent-thread-card__composer--has-images {
-  flex-wrap: wrap;
-  border-radius: 0.85rem;
-}
-
-/* 非全屏态的 actions 也要建立自己的 flex 行。
- * 如果保持默认 block 行盒，Add 按钮会按文字基线布局，视觉上贴在
- * actions 的上沿；显式居中后，按钮始终在 actions 的内容高度内垂直居中。 */
-.markdown-editor
-  .agent-thread-card__composer:not(.agent-composer--expanded)
-  .agent-thread-card__composer-actions {
-  display: flex;
-  align-items: center;
-  flex: 0 0 auto;
-  gap: 0.1rem;
-}
-
-.markdown-editor .agent-thread-card__composer-model {
-  display: none;
-}
-
-.markdown-editor .agent-thread-card__composer-mode {
-  display: none;
-}
-
-.markdown-editor .agent-thread-card__composer-workspace {
-  display: none;
-}
-
-.markdown-editor .agent-thread-card__composer-permission {
-  display: none;
-}
-
-.markdown-editor .agent-thread-card__composer-workspace:disabled {
-  opacity: 0.45;
-  cursor: not-allowed;
-  pointer-events: auto;
-}
-
-.markdown-editor .agent-thread-card__composer-permission:disabled,
-.markdown-editor .agent-thread-card__composer-mode:disabled,
-.markdown-editor .agent-thread-card__empty-control[data-kind='permission']:disabled {
-  opacity: 0.45;
-  cursor: not-allowed;
-  pointer-events: auto;
-}
-
-.markdown-editor .agent-thread-card__composer-workspace:disabled:hover {
-  background: transparent;
-}
-
-.markdown-editor .agent-thread-card__composer-permission:disabled:hover,
-.markdown-editor .agent-thread-card__composer-mode:disabled:hover,
-.markdown-editor .agent-thread-card__empty-control[data-kind='permission']:disabled:hover {
-  background: transparent;
-}
-
-/* Expanded conversation composer: the editor occupies two lines and the
- * role/add + send controls share a dedicated bottom row. Both fullscreen
- * surfaces opt in through .agent-composer--expanded. */
-.markdown-editor .agent-composer--expanded {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) auto;
-  align-items: end;
-  row-gap: 0.35rem;
-  /* 上方留白移入编辑器，避免滚动文案时占据不可滚动的固定区域。 */
-  padding: 0.55rem 0.6rem 0.55rem 0.8rem;
-}
-
-.markdown-editor .agent-composer--expanded .agent-thread-card__composer-images {
-  grid-column: 1 / -1;
-  grid-row: 1;
-}
-
-.markdown-editor .agent-composer--expanded .agent-thread-card__composer-input {
-  grid-column: 1 / -1;
-  grid-row: 2;
-  align-self: stretch;
-  width: auto;
-  flex: none;
-}
-
-.markdown-editor .agent-composer--expanded .agent-thread-card__composer-actions {
-  grid-column: 1;
-  grid-row: 3;
-  display: flex;
-  align-items: center;
-  gap: 0.1rem;
-  align-self: end;
-}
-
-.markdown-editor
-  .agent-composer--expanded
-  :is(.agent-thread-card__composer-model, .agent-thread-card__composer-mode) {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.2rem;
-  min-width: 0;
-  max-width: 12rem;
-  height: 24px;
-  flex: 0 1 auto;
-  padding: 0 0.45rem;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  color: var(--muted-foreground);
-  cursor: pointer;
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1;
-  transition:
-    background-color 150ms ease,
-    color 150ms ease;
-}
-
-.markdown-editor
-  .agent-composer--expanded
-  .agent-thread-card__composer-model {
-  max-width: 240px;
-}
-
-/* hover / open 态背景与 add (+) 按钮的默认背景 (var(--muted)) 对齐,
- * 同空状态 __empty-control 的 hover 规格, 不再单独加深。 */
-.markdown-editor
-  .agent-composer--expanded
-  :is(.agent-thread-card__composer-model:hover, .agent-thread-card__composer-model--open) {
-  background: var(--muted);
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor
-  .agent-composer--expanded
-  :is(
-    .agent-thread-card__composer-mode,
-    .agent-thread-card__composer-permission,
-    .agent-thread-card__composer-workspace
-  ) {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.2rem;
-  min-width: 0;
-  max-width: 12rem;
-  height: 24px;
-  flex: 0 1 auto;
-  padding: 0 0.45rem;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  /* 与空状态的空间信息保持同一套文字规格（text-xs / muted）。 */
-  color: var(--muted-foreground);
-  cursor: pointer;
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1;
-  transition:
-    background-color 150ms ease,
-    color 150ms ease;
-}
-
-.markdown-editor
-  .agent-composer--expanded
-  :is(
-    .agent-thread-card__composer-mode:hover,
-    .agent-thread-card__composer-mode--open,
-    .agent-thread-card__composer-permission:hover,
-    .agent-thread-card__composer-permission--open,
-    .agent-thread-card__composer-workspace:hover,
-    .agent-thread-card__composer-workspace--open
-  ) {
-  background: var(--muted);
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__composer-workspace-value {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  line-height: 1.6;
-}
-
-.markdown-editor .agent-thread-card__composer-model-value {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  line-height: 1.6;
-}
-
-.markdown-editor .agent-thread-card__composer-mode-value {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  line-height: 1.6;
-}
-
-.markdown-editor .agent-thread-card__composer-workspace .agent-thread-card__empty-control-chevron {
-  width: 12px;
-  height: 12px;
-  flex: 0 0 auto;
-  opacity: 0.72;
-}
-
-.markdown-editor .agent-thread-card__composer-workspace-icon {
-  width: 15px;
-  height: 15px;
-  flex: 0 0 auto;
-  color: var(--muted-foreground);
-}
-
-.markdown-editor .agent-thread-card__composer-permission .agent-thread-card__empty-control-chevron {
-  width: 12px;
-  height: 12px;
-  flex: 0 0 auto;
-  opacity: 0.72;
-}
-
-.markdown-editor .agent-thread-card__composer-model .agent-thread-card__empty-control-chevron {
-  width: 12px;
-  height: 12px;
-  flex: 0 0 auto;
-  opacity: 0.72;
-}
-
-.markdown-editor .agent-thread-card__composer-mode .agent-thread-card__empty-control-chevron {
-  width: 12px;
-  height: 12px;
-  flex: 0 0 auto;
-  opacity: 0.72;
-}
-
-.markdown-editor .agent-composer--expanded .agent-thread-card__send-tooltip {
-  grid-column: 2;
-  grid-row: 3;
-  align-self: end;
-  justify-self: end;
-}
-
-.markdown-editor .agent-thread-card__composer-images {
-  display: flex;
-  width: 100%;
-  gap: 0.5rem;
-  padding: 0.15rem 0 0.25rem;
-  overflow-x: auto;
-}
-
-.markdown-editor .agent-thread-card__composer-images[hidden] {
-  display: none;
-}
-
-.markdown-editor .agent-thread-card__composer-image {
-  position: relative;
-  display: block;
-  width: 52px;
-  height: 52px;
-  flex: 0 0 52px;
-  overflow: hidden;
-  border: 1px solid var(--border);
-  border-radius: 0.55rem;
-  background: var(--muted);
-}
-
-.markdown-editor .agent-thread-card__composer-image img {
-  display: block;
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-}
-
-.markdown-editor .agent-thread-card__composer-attachment-name {
-  display: block;
-  max-width: 112px;
-  overflow: hidden;
-  padding: 8px 6px;
-  color: var(--muted-foreground);
-  font-size: 11px;
-  line-height: 1.25;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.markdown-editor .agent-thread-card__composer-image-remove {
-  position: absolute;
-  inset: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  border: 0;
-  background: rgb(0 0 0 / 55%);
-  color: white;
-  font: inherit;
-  font-size: 1.35rem;
-  cursor: pointer;
-  opacity: 0;
-  transition: opacity 120ms ease;
-}
-
-.markdown-editor .agent-thread-card__composer-image:hover .agent-thread-card__composer-image-remove,
-.markdown-editor .agent-thread-card__composer-image-remove:focus-visible {
-  opacity: 1;
-}
-
-.markdown-editor .agent-thread-card__composer-add-button {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 26px;
-  height: 26px;
-  flex: 0 0 auto;
-  align-self: center;
-  /* Add 略小于发送按钮, 但仍通过 align-self: center 保持上下居中。
-   * 额外呼吸位叠加在 __composer-actions 行 gap 之上。 */
-  margin-right: 0.2rem;
-  overflow: hidden;
-  border: 0;
-  padding: 0;
-  border-radius: 6px;
-  background: var(--muted);
-  color: var(--secondary-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  font-weight: 600;
-  text-transform: uppercase;
-  cursor: pointer;
-  transition:
-    background-color 150ms ease,
-    color 150ms ease;
-}
-
-/* 之前 `hidden` 时 display: none ── 现在 composerRoleIcon 永远是 button,
- * 不再设 hidden 属性, 这条规则保留作兜底, 防止后续调用方误设 hidden 时
- * 留下按钮空白 (auto 行高 collapse 已处理, 但显式更稳)。 */
-.markdown-editor .agent-thread-card__composer-add-button[hidden] {
-  display: none;
-}
-
-.markdown-editor .agent-thread-card__composer-add-button img,
-.markdown-editor .agent-thread-card__composer-add-button svg {
-  display: block;
-  width: 20px;
-  height: 20px;
-  object-fit: contain;
-  /* 子元素 SVG / img 不接收 pointer events ── 点击落到底层 button,
-   * 走统一的 click handler。 否则某些浏览器 (尤其带 ::after 高亮的
-   * svg) 会把事件吞掉, 让 button 的 onclick 不触发。 */
-  pointer-events: none;
-}
-
-/* 空态 Plus 图标 ── 14×14, 复用 access popover 新增资料夹按钮
- * (`.agent-thread-card__access-add-icon`) 的尺寸。 20×20 对 Plus
- * filled cross 来说偏大, 与按钮 24×24 容器几乎填满, 视觉上比 memo
- * 文档图标更"重", 与"未设置"的轻量占位语义不符。 缩到 14×14 后,
- * 与 access popover 新增资料夹视觉同源, "次级 indicator" 这一类
- * UI 元素有统一节奏。 */
-.markdown-editor
-  .agent-thread-card__composer-add-button
-  svg.agent-thread-card__composer-add-button-empty {
-  width: 14px;
-  height: 14px;
-}
-
-/* hover / open 态 ── 与文件内 __icon-btn 的 hover 风格同源, 用 var(--muted)
- * 与 var(--foreground) 混合色 + transition 150ms。 popover 打开时挂
- * --open 修饰类, 视觉上"按钮被按下"。 */
-.markdown-editor .agent-thread-card__composer-add-button:hover,
-.markdown-editor .agent-thread-card__composer-add-button--open,
-.markdown-editor .agent-thread-card__composer-add-button:focus-visible {
-  background: color-mix(in oklch, var(--muted) 80%, var(--foreground) 12%);
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__composer-input {
-  display: block;
-  flex: 1 1 0;
-  /* width:0 让 flex 从可收缩的基准宽度开始分配空间，避免内容的固有
-   * 宽度参与横向布局。编辑器自身通过 max-height + overflow-y 增长。 */
-  width: 0;
-  min-width: 0;
-  max-width: 100%;
-  min-height: 1rem;
-  max-height: calc(var(--atc-composer-max-h) - 8px - var(--atc-bottom-pad));
-  height: auto;
-  overflow-x: hidden;
-  overflow-y: auto;
-  overflow-wrap: anywhere;
-  word-break: break-word;
-  border: 0;
-  border-radius: 0;
-  background: transparent;
-  color: var(--foreground);
-  caret-color: var(--brand);
-  padding: 0;
-  font: inherit;
-  font-size: var(--app-font-size, 15px);
-  line-height: 1.6;
-  cursor: text;
-  outline: none;
-  user-select: text;
-  white-space: pre-wrap;
-}
-
-/* composer 编辑器挂载节点同时带有 Tiptap/ProseMirror class；强制透明，
- * 避免全局编辑器背景覆盖输入框外层的统一底色。 */
-.markdown-editor .agent-thread-card__composer-editor {
-  background: transparent !important;
-  /* The composer is part of the agent UI, so it follows the product font
-   * even when its surrounding note uses a custom editor font. */
-  font-family: var(--font-sans);
-}
-
-.markdown-editor .agent-thread-card__composer-input > p {
-  min-height: 1rem;
-  margin-top: 0 !important;
-  margin-bottom: 0 !important;
-  white-space: pre-wrap;
-}
-
-/* WebKit 在拉伸后的全屏空 composer 段落中有时不会绘制原生 caret。
- * 生成一个不可见占位字符，为空段落提供稳定的 inline caret 锚点；
- * 输入真实文字后该伪元素自动消失，不会进入 ProseMirror 文档。 */
-.markdown-editor .agent-thread-card__composer-input > p:empty::before,
-.markdown-editor
-  .agent-thread-card__composer-input
-  > p:has(> br.ProseMirror-trailingBreak:only-child)::before {
-  content: "\00a0";
-}
-
-/* 全局编辑器会给首个 ProseMirror block 增加 margin-top；composer 内的
- * 段落必须贴合输入区域顶部，不保留这段文档编辑器间距。 */
-.markdown-editor
-.agent-thread-card__composer-input
-  > p:first-of-type {
-  margin-top: 0 !important;
-}
-
-.markdown-editor .agent-thread-card__composer-input-row {
-  display: flex;
-  align-items: center;
-  min-width: 0;
-  flex: 1 1 0;
-  gap: 0.35rem;
-  cursor: text;
-  user-select: text;
-}
-
-.markdown-editor .agent-thread-card__composer-input-row .agent-thread-card__composer-input {
-  flex: 1 1 0;
-}
-
-.markdown-editor .agent-thread-card__slash-token {
-  display: inline-block;
-  vertical-align: middle;
-  padding: 0 0.42rem;
-  border: 0;
-  border-radius: 0;
-  background: transparent;
-  color: var(--brand);
-  font: inherit;
-  font-size: inherit;
-  line-height: inherit;
-  cursor: pointer;
-}
-
-/* The slash command is an inline atom, not editable button content. Keep the
- * wrapper as one inline unit and leave its trailing zero-width text node as
- * the caret landing point at the end of a composer paragraph. */
-.markdown-editor .agent-thread-card__slash-token-wrapper {
-  display: inline-flex;
-  align-items: center;
-  white-space: nowrap;
-  vertical-align: top;
-}
-
-.markdown-editor .agent-thread-card__slash-token:hover {
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__slash-token:focus-visible {
-  color: color-mix(in oklch, var(--brand) 82%, var(--foreground));
-  outline: none;
-}
-
-/* Goal and plan are persistent composer controls. Give them the same compact
- * chip treatment as Skill cards so the selected action is visible at a glance
- * and feels like one removable input unit. */
-.markdown-editor :is(
-  .agent-thread-card__slash-token--control,
-  .agent-thread-card__folder-token
-) {
-  display: inline-flex;
-  height: 1.6em;
-  max-width: 100%;
-  align-items: center;
-  padding: 0 0.45rem;
-  border: 1px solid color-mix(in oklch, var(--border) 75%, var(--input-bg, var(--document-bg)) 25%);
-  border-radius: 0.35rem;
-  background: transparent;
-  color: var(--foreground);
-  font-size: inherit;
-  line-height: inherit;
-  transition: border-color 0.15s ease, background-color 0.15s ease;
-  vertical-align: top;
-}
-
-.markdown-editor .agent-thread-card__slash-token--control:hover,
-.markdown-editor .agent-thread-card__folder-token:hover {
-  color: var(--foreground);
-}
-
-.markdown-editor :is(
-  .agent-thread-card__slash-token--control,
-  .agent-thread-card__folder-token
-):focus-visible {
-  border-color: color-mix(in oklch, var(--border) 68%, var(--foreground) 32%);
-  background: transparent;
-  color: var(--foreground);
-}
-
-.markdown-editor .agent-thread-card__slash-token-wrapper.is-selected > .agent-thread-card__slash-token--control {
-  background-color: color-mix(in oklch, var(--foreground) 8%, transparent);
-}
-
-.markdown-editor .agent-thread-card__skill-token {
-  display: inline-flex;
-  height: 1.6em;
-  max-width: 100%;
-  align-items: center;
-  padding: 0 0.45rem;
-  border: 1px solid color-mix(in oklch, var(--border) 75%, var(--input-bg, var(--document-bg)) 25%);
-  border-radius: 0.35rem;
-  background: transparent;
-  color: var(--foreground);
-  font: inherit;
-  font-size: inherit;
-  line-height: inherit;
-  transition: border-color 0.15s ease, background-color 0.15s ease;
-  white-space: nowrap;
-  vertical-align: top;
-  cursor: pointer;
-}
-
-.markdown-editor .agent-thread-card__skill-token:hover {
-  background: transparent;
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__skill-token:focus-visible {
-  border-color: color-mix(in oklch, var(--border) 68%, var(--foreground) 32%);
-  background: transparent;
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__skill-token.ProseMirror-selectednode {
-  background-color: color-mix(in oklch, var(--foreground) 8%, transparent);
-}
-
-/* Notebook add-dir mention. Keep the chip geometry aligned with Skill cards;
- * the @ prefix makes a selected data folder recognizable at a glance. */
-/* Notes selected through the @ picker keep the canonical NoteReference node
- * (memo id/path validation and double-click navigation), but use the same
- * compact chip treatment as Skill and folder references inside the composer.
- * This override is composer-scoped so normal document note links keep their
- * own presentation. */
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer {
-  display: inline-block;
-  max-width: 100%;
-  vertical-align: top;
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__card,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__card {
-  display: inline-flex;
-  box-sizing: border-box;
-  height: 1.6em;
-  max-width: 100%;
-  align-items: center;
-  padding: 0 0.45rem;
-  border: 1px solid color-mix(in oklch, var(--border) 75%, var(--input-bg, var(--document-bg)) 25%);
-  border-radius: 0.35rem;
-  background: transparent;
-  color: var(--foreground);
-  font: inherit;
-  font-size: inherit;
-  line-height: inherit;
-  vertical-align: top;
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__card:hover :is(
-  .editor-note-reference__name,
-  .editor-note-reference__title,
-  .editor-note-reference__notebook,
-  .editor-note-reference__chevron
-) {
-  color: var(--foreground);
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__card:focus-visible,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__card:focus-visible {
-  border-color: color-mix(in oklch, var(--border) 68%, var(--foreground) 32%);
-  background: transparent;
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__icon,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__icon {
-  display: inline-flex;
-  width: 14px;
-  height: 14px;
-  align-items: center;
-  margin: 0 0.25rem 0 0;
-  color: var(--muted-foreground);
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__name,
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__title,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__name,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__title {
-  max-width: 100%;
-  overflow: hidden;
-  color: var(--foreground);
-  font-weight: 400;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__stale-mark,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer .editor-note-reference__stale-mark {
-  color: var(--muted-foreground);
-  font-weight: 400;
-}
-
-.markdown-editor .agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer.is-selected .editor-note-reference__card,
-.agent-thread-card__composer .agent-thread-card__composer-input .editor-note-reference--composer.is-selected .editor-note-reference__card {
-  background-color: color-mix(in oklch, var(--foreground) 8%, transparent);
-}
-
-.agent-composer-slash-menu {
-  position: fixed;
-  z-index: 1000;
-  max-height: min(22rem, 48vh);
-  overflow-y: auto;
-  padding: 0.25rem;
-  border: 1px solid var(--border-popup);
-  border-radius: 0.75rem;
-  background: var(--card);
-  color: var(--agent-foreground);
-  /* Slash menu shadow is intentionally 1/4 of the standard popover weight. */
-  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 6%);
-  box-sizing: border-box;
-}
-
-.agent-composer-slash-menu--folder {
-  max-height: min(16.5rem, 36vh);
-}
-
-.agent-composer-slash-menu__item {
-  display: flex;
-  width: 100%;
-  min-width: 0;
-  align-items: center;
-  gap: 0.75rem;
-  min-height: 1.75rem;
-  padding: 0.125rem 0.5rem;
-  border: 0;
-  border-radius: 0.5rem;
-  background: transparent;
-  color: var(--foreground);
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1.25;
-  text-align: left;
-  cursor: pointer;
-}
-
-.agent-composer-slash-menu__section {
-  margin: 0.25rem 0.5rem 0.125rem;
-  padding: 0.35rem 0 0.125rem;
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.75);
-  line-height: 1.2;
-}
-
-.agent-composer-slash-menu__item--back {
-  margin-bottom: 0.2rem;
-  border-radius: 0;
-  color: var(--muted-foreground);
-}
-
-.agent-composer-slash-menu__empty {
-  padding: 0.5rem;
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.85);
-  text-align: center;
-}
-
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover,
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible,
-.agent-composer-slash-menu__item--active {
-  background: var(--hover-bg);
-  color: var(--foreground);
-}
-
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover
-  .agent-composer-slash-menu__name,
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover
-  .agent-composer-slash-menu__description,
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:hover
-  .agent-composer-slash-menu__scope,
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible
-  .agent-composer-slash-menu__name,
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible
-  .agent-composer-slash-menu__description,
-.agent-composer-slash-menu:not(.is-keyboard-navigation) .agent-composer-slash-menu__item:focus-visible
-  .agent-composer-slash-menu__scope,
-.agent-composer-slash-menu__item--active
-  .agent-composer-slash-menu__name,
-.agent-composer-slash-menu__item--active
-  .agent-composer-slash-menu__description,
-.agent-composer-slash-menu__item--active
-  .agent-composer-slash-menu__scope {
-  color: var(--foreground);
-}
-
-/* The skill picker has a navigation row, not a selectable command. Keep
- * hovering/focusing that row to a text-color change, without the command
- * highlight background. */
-.agent-composer-slash-menu:not(.is-keyboard-navigation)
-  .agent-composer-slash-menu__item--back:hover,
-.agent-composer-slash-menu:not(.is-keyboard-navigation)
-  .agent-composer-slash-menu__item--back:focus-visible {
-  background: transparent;
-  color: var(--foreground);
-}
-
-.agent-composer-slash-menu__name {
-  flex: 0 0 6.6rem;
-  color: var(--foreground);
-  font-weight: 400;
-}
-
-.agent-composer-slash-menu__item--skill .agent-composer-slash-menu__name {
-  flex: 0 1 auto;
-  min-width: 10em;
-  max-width: 34%;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.agent-composer-slash-menu__item--skill .agent-composer-slash-menu__description {
-  flex: 1 1 auto;
-}
-
-.agent-composer-slash-menu__scope {
-  flex: 0 0 auto;
-  padding: 0.1rem 0.4rem;
-  border-radius: 999px;
-  background: color-mix(in oklch, var(--foreground) 6%, transparent);
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.72);
-  line-height: 1.3;
-  white-space: nowrap;
-}
-
-.agent-composer-slash-menu__item--folder .agent-composer-slash-menu__name {
-  flex: 0 1 auto;
-  min-width: 0;
-  max-width: 40%;
-  overflow: hidden;
-  color: var(--foreground);
-  text-overflow: ellipsis;
-  font-weight: 400;
-  white-space: nowrap;
-}
-
-.agent-composer-slash-menu__item--folder .agent-composer-slash-menu__description {
-  flex: 1 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  color: var(--muted-foreground);
-  font-size: inherit;
-  text-overflow: ellipsis;
-  text-align: right;
-  white-space: nowrap;
-}
-
-.agent-composer-slash-menu__item--folder:hover .agent-composer-slash-menu__name,
-.agent-composer-slash-menu__item--folder:hover .agent-composer-slash-menu__description,
-.agent-composer-slash-menu__item--folder:focus-visible .agent-composer-slash-menu__name,
-.agent-composer-slash-menu__item--folder:focus-visible .agent-composer-slash-menu__description {
-  color: var(--foreground);
-}
-
-.agent-composer-slash-menu__item--folder.agent-composer-slash-menu__item--active
-  .agent-composer-slash-menu__name {
-  color: var(--foreground);
-}
-
-.agent-composer-slash-menu__item--note .agent-composer-slash-menu__name {
-  flex: 0 1 auto;
-  min-width: 0;
-  max-width: 62%;
-  overflow: hidden;
-  color: var(--foreground);
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.agent-composer-slash-menu__item--note .agent-composer-slash-menu__description {
-  flex: 1 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  color: var(--muted-foreground);
-  font-size: inherit;
-  text-align: right;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.agent-composer-slash-menu__item--note:hover .agent-composer-slash-menu__name,
-.agent-composer-slash-menu__item--note:hover .agent-composer-slash-menu__description,
-.agent-composer-slash-menu__item--note:focus-visible .agent-composer-slash-menu__name,
-.agent-composer-slash-menu__item--note:focus-visible .agent-composer-slash-menu__description,
-.agent-composer-slash-menu__item--note.agent-composer-slash-menu__item--active
-  .agent-composer-slash-menu__name,
-.agent-composer-slash-menu__item--note.agent-composer-slash-menu__item--active
-  .agent-composer-slash-menu__description {
-  color: var(--foreground);
-}
-
-.agent-composer-slash-menu__description {
-  min-width: 0;
-  overflow: hidden;
-  color: var(--muted-foreground);
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.markdown-editor .agent-thread-card__composer-input:focus {
-  /* base 已 border: 0, 这里只压掉默认 focus ring 的 box-shadow */
-  box-shadow: none;
-}
-
-/* 发送按钮 ── 28×28 圆形, 内嵌 16×16 Phosphor 图标。
- * 尺寸取自 --atc-send-size, 与输入区 min-height 公式联动。 */
-.agent-thread-card__access-trigger {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  height: var(--atc-send-size);
-  flex: 0 0 auto;
-  border: 0;
-  border-radius: 9999px;
-  background: transparent;
-  color: var(--muted-foreground);
-  cursor: pointer;
-  padding: 0 0.5rem;
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
-  line-height: 1;
-  white-space: nowrap;
-}
-
-.agent-thread-card__access-trigger:hover,
-.agent-thread-card__access-trigger--open {
-  color: var(--foreground);
-}
-
-.markdown-editor .agent-composer--expanded .agent-thread-card__composer-input-row {
-  grid-column: 1 / -1;
-  grid-row: 2;
-  align-self: stretch;
-}
-
-.markdown-editor
-  .agent-composer--expanded
-  .agent-thread-card__composer-input-row
-  .agent-thread-card__composer-input {
-  width: 100%;
-  min-width: 0;
-  height: 100%;
-  flex: 1 1 auto;
-  align-self: stretch;
-  padding-top: 0;
-  text-align: left;
-}
-
-.markdown-editor .agent-composer--expanded .agent-thread-card__composer-input {
-  width: 100%;
-  height: 100%;
-  flex: none;
-  align-self: stretch;
-  padding-top: 0;
-  text-align: left;
-}
-
-/* 展开态尺寸集中定义在这里，并放在基础输入规则之后，避免依赖多处
- * 覆盖关系；普通非全屏单行 composer 不带这个 modifier，因此保持原有尺寸。 */
-.markdown-editor .agent-composer--expanded {
-  grid-template-rows: auto minmax(2rem, auto) auto;
-  max-height: none;
-}
-
-.markdown-editor
-  .agent-composer--expanded
-  .agent-thread-card__composer-input-row
-  .agent-thread-card__composer-input {
-  min-height: 2rem;
-  max-height: calc(10 * 1.35em);
-}
diff --git a/app/flowix-web/styles/agent-thread-card/controls.css b/app/flowix-web/styles/agent-thread-card/controls.css
index d79efa530..974656016 100644
--- a/app/flowix-web/styles/agent-thread-card/controls.css
+++ b/app/flowix-web/styles/agent-thread-card/controls.css
@@ -118,7 +118,7 @@
 /* 复用 __copy-icon 口径 ── 14×14, color 继承按钮文字色, 不缩小。
  * 之所以独立类不复用, 是因为以后可能给删除按钮单独调 hover 色或加危险态, 独立类
  * 给未来留扩展空间。 */
-.markdown-editor .agent-thread-card__trash-icon {
+.markdown-editor .agent-icon__trash {
   display: block;
   width: 14px;
   height: 14px;
@@ -140,7 +140,7 @@
 }
 
 /* 查看笔记按钮 ── 在右侧列对话 (AgentConversationDetail) header 的
- * actions 区出现, 视觉同 __icon-btn 基类。 仅在 source.memoId /
+ * actions 区出现, 视觉同 __icon-btn 基类。 仅在 source.relativePath /
  * source.documentPath 存在时启用; dedicated 对话没有来源笔记, 整段
  * "[icon] | …" 操作组被隐藏, 只剩 "…" 入口供删除。
  *
@@ -277,6 +277,18 @@
     opacity 120ms ease;
 }
 
+/* A click transfers wheel ownership to the embedded message viewport. Keep a
+ * quiet top/bottom inset cue on the whole card until the user clicks elsewhere. */
+.markdown-editor
+  .agent-thread-card.agent-thread-card--message-scroll-active
+  > .agent-thread-card__container {
+  box-shadow:
+    inset 0 5px 14px -8px color-mix(in oklch, var(--brand) 18%, transparent),
+    inset 0 -5px 14px -8px color-mix(in oklch, var(--brand) 18%, transparent),
+    inset 5px 0 14px -8px color-mix(in oklch, var(--brand) 18%, transparent),
+    inset -5px 0 14px -8px color-mix(in oklch, var(--brand) 18%, transparent);
+}
+
 html[data-platform="mac"] .markdown-editor .agent-thread-card__body-frame {
   min-height: 0;
   height: 100%;
@@ -481,6 +493,13 @@ html[data-platform="mac"] .agent-conversation-detail .agent-thread-card__body {
   align-items: stretch;
 }
 
+/* Keep the running indicator on the same message-column track in every
+ * Thread Card mode. Expanded surfaces below narrow this shared track. */
+.markdown-editor .agent-thread-card__messages,
+.markdown-editor .agent-thread-card__body > .agent-thread-card__loading-indicator {
+  width: 100%;
+}
+
 /* 独立对话的消息区不允许长 URL / token / 代码行把整个 surface 撑出
  * 横向滚动。仅限第三列 AgentConversationDetail, 不影响文档内嵌卡片及其
  * fullscreen 模式。 */
@@ -506,13 +525,14 @@ html[data-platform="mac"] .agent-conversation-detail .agent-thread-card__body {
 }
 
 .markdown-editor.agent-conversation-detail .agent-thread-card__messages,
-.markdown-editor.agent-conversation-detail .agent-thread-card__skeleton {
+.markdown-editor.agent-conversation-detail .agent-thread-card__skeleton,
+.markdown-editor.agent-conversation-detail .agent-thread-card__loading-indicator {
   width: calc(100% - 3rem);
   max-width: 780px;
   margin-inline: auto;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__composer {
+.markdown-editor.agent-conversation-detail .agent-composer {
   align-self: center;
   width: calc(100% - 3rem);
   max-width: 780px;
@@ -547,7 +567,7 @@ html[data-platform="mac"] .markdown-editor .agent-thread-card--collapsed .agent-
   display: none;
 }
 
-.markdown-editor .agent-thread-card--collapsed .agent-thread-card__composer {
+.markdown-editor .agent-thread-card--collapsed .agent-composer {
   display: none;
 }
 
@@ -637,7 +657,10 @@ html[data-platform="mac"] .markdown-editor .agent-thread-card--collapsed .agent-
   width: calc(100% - 3rem);
 }
 
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__messages {
+.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__messages,
+.markdown-editor
+  .agent-thread-card--fullscreen
+  .agent-thread-card__loading-indicator {
   width: calc(100% - 3rem);
   max-width: 780px;
   margin-inline: auto;
diff --git a/app/flowix-web/styles/agent-thread-card/markdown.css b/app/flowix-web/styles/agent-thread-card/markdown.css
index 150f521ef..33c9e77f3 100644
--- a/app/flowix-web/styles/agent-thread-card/markdown.css
+++ b/app/flowix-web/styles/agent-thread-card/markdown.css
@@ -2,194 +2,188 @@
  * 面板 message-end = `text-xs text-[var(--muted-foreground)]
  * text-center`, 内容或时间戳。卡片里 mt-2 让 end 消息与前一条
  * 有视觉间距, 不与下一条 user/assistant "贴" 一起。 */
-.markdown-editor .agent-thread-card__message--end {
+.agent-conversation-surface .agent-thread-card__message--end {
   display: block;
   margin: 4px 0;
   text-align: center;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message--end
   .agent-thread-card__message-content {
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   text-align: center;
 }
 
 /* 消息正文容器 ── 现在内容是 marked 输出的 HTML 树, 不能再用
  * white-space: pre-wrap (会把 <p> 节点当文本节点, 不再分段)。改成
  * 默认 block 流式 + overflow-wrap: anywhere (替代 word-break:
- * break-word, 语义更准), 正文字号为 0.94 倍 app 字号。 */
-.markdown-editor .agent-thread-card__message-content {
+ * break-word, 语义更准), 字号跟随 agent 字号档位。 */
+.agent-conversation-surface .agent-thread-card__message-content {
   color: var(--foreground);
   cursor: text;
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-family: var(--agent-message-font-family, var(--font-sans));
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   line-height: 1.7;
   overflow-wrap: anywhere;
   word-break: break-word;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   :where(:not(a):not(button):not([role="button"])) {
   cursor: text;
 }
 
-/* reasoning 的正文为 0.94 倍 app 字号, 使用 muted-foreground。 */
-.markdown-editor
+/* reasoning 正文跟随 agent 字号档位, 使用 muted-foreground。 */
+.agent-conversation-surface
   .agent-thread-card__message--reasoning
   .agent-thread-card__message-content {
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
 }
 
 /* end 角色的 content: 居中灰字 (保留在 .--end 修饰里)。 */
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message--end
   .agent-thread-card__message-content {
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   text-align: center;
 }
 
 /* ── markdown 元素排版 ── 对齐面板 markdown-renderer WRAPPER_CLASS
  * 子选择器 (面板走 Tailwind arbitrary variant, 卡片走原生 CSS 子选择器,
- * 效果相同)。标题尺寸为 H1–H3 1.2 倍 app 字号、H4–H6 0.94 倍；
- * 正文为 0.94 倍 app 字号。 */
-.markdown-editor .agent-thread-card__message-content > *:first-child {
+ * 效果相同)。标题尺寸为 H1–H3 1.2 倍 agent 字号、H4–H6 继承 agent 字号；
+ * 正文跟随 agent 字号档位。 */
+.agent-conversation-surface .agent-thread-card__message-content > *:first-child {
   margin-top: 0;
 }
-.markdown-editor .agent-thread-card__message-content > *:last-child {
+.agent-conversation-surface .agent-thread-card__message-content > *:last-child {
   margin-bottom: 0;
 }
-.markdown-editor .agent-thread-card__message-content > p:last-child {
+
+.agent-conversation-surface .agent-thread-card__message-content > p:last-child {
   padding-bottom: 0;
 }
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   > :is(ul, ol, blockquote):last-child {
   padding-bottom: 0;
 }
 
-.markdown-editor .agent-thread-card__message-content p {
+.agent-conversation-surface .agent-thread-card__message-content p {
   margin: 0;
   padding: 0 0 8px;
 }
 
-.markdown-editor .agent-thread-card__message-display-toggle {
+.agent-conversation-surface .agent-thread-card__message-display-toggle {
   justify-self: flex-start;
   width: fit-content;
   border: 0;
   padding: 2px 0;
-  background: color-mix(in srgb, var(--primary) 7%, transparent);
+  background: transparent;
   color: var(--muted-foreground);
   cursor: pointer;
-  font-size: calc(var(--app-font-size, 15px) * 0.82);
+  font-size: calc(var(--agent-message-base-font-size, 15px) * 0.82);
   line-height: 1.4;
-  text-decoration: underline;
-  text-underline-offset: 3px;
 }
 
-.markdown-editor .agent-thread-card__message-display-toggle:hover {
+.agent-conversation-surface .agent-thread-card__message-display-toggle:hover {
   color: var(--foreground);
 }
 
-.markdown-editor
-  .agent-thread-card__message--user
-  .agent-thread-card__message-display-toggle {
-  margin-left: auto;
-}
-
-.markdown-editor .agent-thread-card__message-content h1,
-.markdown-editor .agent-thread-card__message-content h2,
-.markdown-editor .agent-thread-card__message-content h3,
-.markdown-editor .agent-thread-card__message-content h4,
-.markdown-editor .agent-thread-card__message-content h5,
-.markdown-editor .agent-thread-card__message-content h6 {
+.agent-conversation-surface .agent-thread-card__message-content h1,
+.agent-conversation-surface .agent-thread-card__message-content h2,
+.agent-conversation-surface .agent-thread-card__message-content h3,
+.agent-conversation-surface .agent-thread-card__message-content h4,
+.agent-conversation-surface .agent-thread-card__message-content h5,
+.agent-conversation-surface .agent-thread-card__message-content h6 {
   margin: 0;
   padding: 8px 0;
   color: var(--foreground);
   font-weight: 600;
   line-height: 1.3;
 }
-.markdown-editor .agent-thread-card__message-content h4,
-.markdown-editor .agent-thread-card__message-content h5,
-.markdown-editor .agent-thread-card__message-content h6 {
+.agent-conversation-surface .agent-thread-card__message-content h4,
+.agent-conversation-surface .agent-thread-card__message-content h5,
+.agent-conversation-surface .agent-thread-card__message-content h6 {
   padding-top: 0;
 }
-.markdown-editor .agent-thread-card__message-content h1 {
-  font-size: calc(var(--app-font-size, 15px) * 1.2);
+.agent-conversation-surface .agent-thread-card__message-content h1 {
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 1.2);
 }
-.markdown-editor .agent-thread-card__message-content h2 {
-  font-size: calc(var(--app-font-size, 15px) * 1.2);
+.agent-conversation-surface .agent-thread-card__message-content h2 {
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 1.2);
 }
-.markdown-editor .agent-thread-card__message-content h3 {
-  font-size: calc(var(--app-font-size, 15px) * 1.2);
+.agent-conversation-surface .agent-thread-card__message-content h3 {
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 1.2);
 }
-.markdown-editor .agent-thread-card__message-content h4 {
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+.agent-conversation-surface .agent-thread-card__message-content h4 {
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   font-weight: 500;
 }
-.markdown-editor .agent-thread-card__message-content h5,
-.markdown-editor .agent-thread-card__message-content h6 {
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+.agent-conversation-surface .agent-thread-card__message-content h5,
+.agent-conversation-surface .agent-thread-card__message-content h6 {
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   font-weight: 500;
 }
 
-.markdown-editor .agent-thread-card__message-content ul,
-.markdown-editor .agent-thread-card__message-content ol {
+.agent-conversation-surface .agent-thread-card__message-content ul,
+.agent-conversation-surface .agent-thread-card__message-content ol {
   margin: 0;
   padding-top: 0;
   padding-bottom: 8px;
   padding-left: 22px;
 }
-.markdown-editor .agent-thread-card__message-content ul {
+.agent-conversation-surface .agent-thread-card__message-content ul {
   list-style: disc;
 }
-.markdown-editor .agent-thread-card__message-content ol {
+.agent-conversation-surface .agent-thread-card__message-content ol {
   list-style: decimal;
 }
-.markdown-editor .agent-thread-card__message-content li {
+.agent-conversation-surface .agent-thread-card__message-content li {
   margin: 0;
   line-height: 1.7;
 }
-.markdown-editor .agent-thread-card__message-content li > p {
+.agent-conversation-surface .agent-thread-card__message-content li > p {
   margin: 0;
 }
 
-.markdown-editor .agent-thread-card__message-content strong {
+.agent-conversation-surface .agent-thread-card__message-content strong {
   font-weight: 600;
 }
-.markdown-editor .agent-thread-card__message-content em {
+.agent-conversation-surface .agent-thread-card__message-content em {
   font-style: italic;
 }
-.markdown-editor .agent-thread-card__message-content del {
+.agent-conversation-surface .agent-thread-card__message-content del {
   color: var(--muted-foreground);
 }
 
 /* 链接 ── 面板走 text-primary + hover:underline; 卡片用 var(--brand)
  * + hover:underline。target=_blank / rel=noopener 在 marked 输出
  * 不会自动加, 后续如需可注入属性 (此处保留基础样式)。 */
-.markdown-editor .agent-thread-card__message-content a {
+.agent-conversation-surface .agent-thread-card__message-content a {
   color: var(--brand);
   cursor: pointer;
   text-decoration: none;
   border-bottom: 1px solid color-mix(in oklch, var(--brand) 35%, transparent);
 }
 
-.markdown-editor .agent-thread-card__message-content a *,
-.markdown-editor .agent-thread-card__message-content button *,
-.markdown-editor .agent-thread-card__message-content [role="button"] * {
+.agent-conversation-surface .agent-thread-card__message-content a *,
+.agent-conversation-surface .agent-thread-card__message-content button *,
+.agent-conversation-surface .agent-thread-card__message-content [role="button"] * {
   cursor: inherit;
 }
-.markdown-editor .agent-thread-card__message-content a:hover {
+.agent-conversation-surface .agent-thread-card__message-content a:hover {
   border-bottom-color: var(--brand);
 }
 
 /* Markdown images are regular <img> elements rather than editor attachment
  * NodeViews. Keep them inside the message column after editor image rules
  * are intentionally excluded. */
-.markdown-editor .agent-thread-card__message-content img {
+.agent-conversation-surface .agent-thread-card__message-content img {
   box-sizing: border-box;
   display: block;
   max-width: min(120px, 100%);
@@ -200,12 +194,12 @@
   cursor: zoom-in;
 }
 
-.markdown-editor .agent-thread-card__message-content img[data-agent-image-preview]:focus-visible {
+.agent-conversation-surface .agent-thread-card__message-content img[data-agent-image-preview]:focus-visible {
   outline: 2px solid var(--brand);
   outline-offset: 2px;
 }
 
-.markdown-editor .agent-thread-card__generated-image-strip {
+.agent-conversation-surface .agent-thread-card__generated-image-strip {
   display: flex;
   gap: 8px;
   width: 100%;
@@ -218,7 +212,7 @@
   scrollbar-width: thin;
 }
 
-.markdown-editor .agent-thread-card__generated-image-frame {
+.agent-conversation-surface .agent-thread-card__generated-image-frame {
   display: flex;
   flex: 0 0 auto;
   align-items: center;
@@ -226,7 +220,7 @@
   max-width: 120px;
 }
 
-.markdown-editor .agent-thread-card__generated-image {
+.agent-conversation-surface .agent-thread-card__generated-image {
   display: block;
   width: auto;
   height: auto;
@@ -236,23 +230,23 @@
   cursor: zoom-in;
 }
 
-.markdown-editor .agent-thread-card__generated-image:focus-visible {
+.agent-conversation-surface .agent-thread-card__generated-image:focus-visible {
   outline: 2px solid var(--brand);
   outline-offset: 2px;
 }
 
 /* 独立对话中的工具命令收起态是 nowrap 单行摘要；完整参数只在展开态
  * 进入详情列表。所有尺寸约束都落在工具自己的内容轨道内。 */
-.markdown-editor.agent-conversation-detail .agent-thread-card__message--tool,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-tool-content,
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-line,
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-list,
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-item {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message--tool,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-tool-content,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-line,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-list,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-item {
   min-width: 0;
   max-width: 100%;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-line {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-line {
   display: flex;
   flex-wrap: nowrap;
   width: 100%;
@@ -262,16 +256,16 @@
   white-space: nowrap;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-name,
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-args-inline,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-tool-summary {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-name,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-args-inline,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-tool-summary {
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.markdown-editor.agent-conversation-detail
+.agent-conversation-surface.agent-conversation-detail
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__message-tool-summary {
   overflow: visible;
@@ -282,7 +276,7 @@
 
 /* 收起态命令名也必须保持单行；否则该高 specificity 规则会覆盖
  * messages.css 的 nowrap，导致 run/bash 等命令参数出现多行布局。 */
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-name {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-name {
   flex: 0 1 auto;
   width: fit-content;
   min-width: 0;
@@ -292,7 +286,7 @@
   white-space: nowrap;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-tool-name {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-tool-name {
   /* 工具名是参数摘要左侧的稳定锚点，不参与 sibling 的负空间分配。
    * 否则长参数会把它压到接近 0px，overflow:hidden 最终只露出半个字；
    * 参数摘要自身已设置 min-width:0 + ellipsis，应由它承担收缩。 */
@@ -307,7 +301,7 @@
   text-align: left;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-args-inline {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-args-inline {
   flex: 1 1 auto;
   width: auto;
   max-width: none;
@@ -315,13 +309,13 @@
   word-break: normal;
 }
 
-.markdown-editor.agent-conversation-detail
+.agent-conversation-surface.agent-conversation-detail
   .agent-thread-card__message-tool-content--expanded {
   display: block;
   overflow: visible;
 }
 
-.markdown-editor.agent-conversation-detail
+.agent-conversation-surface.agent-conversation-detail
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-line {
   width: 100%;
@@ -329,10 +323,10 @@
   white-space: normal;
 }
 
-.markdown-editor.agent-conversation-detail
+.agent-conversation-surface.agent-conversation-detail
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-name,
-.markdown-editor.agent-conversation-detail
+.agent-conversation-surface.agent-conversation-detail
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-args-inline {
   overflow: visible;
@@ -341,8 +335,8 @@
   overflow-wrap: anywhere;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__command-args-inline,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-tool-summary {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__command-args-inline,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-tool-summary {
   display: block;
   min-width: 0;
   max-width: 100%;
@@ -353,26 +347,26 @@
 
 /* 第三列中的历史正文必须在自己的内容轨道内收缩。尤其是列表、引用、
  * 链接和媒体，它们不能因为某个不可断开的 token 把 body 撑出横向滚动。 */
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content > *,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content li,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content blockquote,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content a,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content img,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content video,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content iframe {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content > *,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content li,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content blockquote,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content a,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content img,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content video,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content iframe {
   box-sizing: border-box;
   max-width: 100%;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content img,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content video,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content iframe {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content img,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content video,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content iframe {
   height: auto;
 }
 
 /* Keep the conversation-detail media guard from overriding the compact
  * dimensions of Markdown images in Agent replies. */
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content img {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content img {
   max-width: min(120px, 100%);
   width: auto;
   height: auto;
@@ -448,17 +442,7 @@
   border: 2px solid rgb(255 255 255 / 35%);
   border-top-color: white;
   border-radius: 50%;
-  animation: agent-thread-card-image-preview-spin 0.8s linear infinite;
-}
-
-@keyframes agent-thread-card-image-preview-spin {
-  to { transform: rotate(360deg); }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .agent-thread-card__image-preview-spinner {
-    animation: none;
-  }
+  --flowix-spin-duration: 0.8s;
 }
 
 .agent-thread-card__image-preview-close {
@@ -489,12 +473,12 @@
   outline-offset: 2px;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content table {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content table {
   table-layout: fixed;
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content th,
-.markdown-editor.agent-conversation-detail .agent-thread-card__message-content td {
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content th,
+.agent-conversation-surface.agent-conversation-detail .agent-thread-card__message-content td {
   overflow-wrap: anywhere;
   word-break: break-word;
 }
@@ -504,7 +488,7 @@
  * (与右栏面板 markdown-renderer 同源, 不写死颜色)。卡片
  * 映射到 3px 左边框 + 12px 左 padding, italic + muted-foreground
  * 跟编辑器一致。 */
-.markdown-editor .agent-thread-card__message-content blockquote {
+.agent-conversation-surface .agent-thread-card__message-content blockquote {
   margin: 6px 0;
   padding: 2px 0 2px 12px;
   border-left: 3px solid var(--border);
@@ -513,14 +497,14 @@
 }
 
 /* 分隔线 ── 面板 border-t 10% 透明; 卡片走 1px 透明分割。 */
-.markdown-editor .agent-thread-card__message-content hr {
+.agent-conversation-surface .agent-thread-card__message-content hr {
   margin: 10px 0;
   border: 0;
   border-top: 1px solid
     color-mix(in oklch, var(--muted-foreground) 12%, transparent);
 }
 
-/* 内联 code ── 严格对齐 .markdown-editor .tiptap:not(.agent-thread-card__composer-editor) p code 的视觉口径:
+/* 内联 code ── 严格对齐 .agent-conversation-surface .tiptap:not(.agent-composer__input-content) p code 的视觉口径:
  *   border: 1px solid color-mix(in oklch, var(--border) 90%, transparent)
  *   border-radius: 0.4rem
  *   padding: 0 0.3rem
@@ -537,8 +521,8 @@
  *  - <pre><code>foo</code></pre>          不命中 (pre 是 pre)
  * 编辑器正文也不带背景色 ── 仅靠 1px 边框 + 品牌色文字做区分。
  * 卡片跨三处 (Tiptap 正文 / 卡片 / 右栏面板) 走同一套 token。 */
-.markdown-editor .agent-thread-card__message-content .agent-thread-card__math,
-.markdown-editor
+.agent-conversation-surface .agent-thread-card__message-content .agent-thread-card__math,
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math
   * {
@@ -547,7 +531,7 @@
   word-break: normal;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math--inline {
   display: inline;
@@ -559,7 +543,7 @@
   transition: background-color 120ms ease;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math--block {
   display: block;
@@ -578,7 +562,7 @@
 }
 
 /* Keep display math naturally sized while allowing long formulas to scroll. */
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math-scroller {
   display: block;
@@ -590,46 +574,48 @@
   box-sizing: border-box;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math:hover {
   background: color-mix(in oklch, var(--primary) 10%, transparent);
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math:focus-visible {
   outline: 2px solid color-mix(in oklch, var(--primary) 65%, transparent);
   outline-offset: 2px;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math--copied {
   background: color-mix(in oklch, var(--primary) 16%, transparent);
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   .agent-thread-card__math--block.agent-thread-card__math--copied {
   border-color: color-mix(in oklch, var(--primary) 35%, var(--border));
 }
 
-.markdown-editor .agent-thread-card__message-content .katex-display {
+.agent-conversation-surface .agent-thread-card__message-content .katex-display {
   margin: 0;
 }
 
-.markdown-editor .agent-thread-card__message-content :not(pre) > code {
+.agent-conversation-surface .agent-thread-card__message-content :not(pre) > code {
   padding: 0 0.3rem;
   border: 1px solid color-mix(in oklch, var(--border) 90%, transparent);
   border-radius: 0.4rem;
   color: var(--text-hint);
   font-family: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* was 0.84rem ≈ 13.44px */
+  font-size: calc(
+    var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1)
+  );
   font-weight: 400;
 }
 
-/* fenced code 块 ── 严格对齐 .markdown-editor .tiptap:not(.agent-thread-card__composer-editor) pre / pre code
+/* fenced code 块 ── 严格对齐 .agent-conversation-surface .tiptap:not(.agent-composer__input-content) pre / pre code
  * 的视觉口径: 把"边框 / 底色 / 圆角 / padding / 字号 / 行高"全部
  * 挂在 pre 上 (跟编辑器一致), pre code 只还原 padding 与透明背景
  * (让内层 code 不再叠加边框/底色 ── 避免双层视觉)。
@@ -640,7 +626,7 @@
  *            padding     0.5rem 0.8rem 8px
  *            margin      0 0 6px
  *            font-size   inherit (from message-content)
- *            line-height 1.5
+ *            line-height var(--code-line-height, 1.8)
  *            language   small label in the top-right corner
  *            white-space pre-wrap (跟编辑器一致, 长代码在卡片宽度下自动换行)
  *   pre code: padding 0 / background transparent (还原内层, 让 pre
@@ -649,7 +635,7 @@
  * 卡片之前把样式挂在 pre code 上 ── 与编辑器结构相反, 这里收口到
  * pre。pre-wrap + 卡片宽度窄, 代码块天然按卡片宽换行, 不需要
  * overflow-x: auto (编辑器是 overflow-x: visible, 同源)。 */
-.markdown-editor .agent-thread-card__message-content pre {
+.agent-conversation-surface .agent-thread-card__message-content pre {
   position: relative;
   margin: 0 0 6px;
   padding: 0.5rem 0.8rem 8px;
@@ -658,12 +644,12 @@
   background: var(--editor-block-bg);
   font-family: var(--code-font-family);
   font-size: inherit;
-  line-height: 1.5;
+  line-height: var(--code-line-height, 1.8);
   white-space: pre-wrap;
   word-break: break-word;
   tab-size: 5;
 }
-.markdown-editor .agent-thread-card__message-content pre::before {
+.agent-conversation-surface .agent-thread-card__message-content pre::before {
   position: absolute;
   top: 0.5rem;
   right: 0.8rem;
@@ -676,7 +662,7 @@
   user-select: none;
   white-space: nowrap;
 }
-.markdown-editor .agent-thread-card__message-content pre code {
+.agent-conversation-surface .agent-thread-card__message-content pre code {
   /* 还原: 1) 上方 :not(pre) > code 已经让 inline code 规则不命中
    * pre code ── 但浏览器 UA stylesheet 默认给 code 元素
    * font-family: monospace, 会盖过 pre 的 font-family: inherit,
@@ -697,50 +683,52 @@
 /* 表格 ── 沿用编辑器 .tiptap table 的视觉规格 (separate + 单边 border)
  * table 统一负责整体 8px 圆角与 overflow 裁剪; border-collapse: separate
  * + border-spacing: 0 保证 cell 边框按整体形状自然收口。 */
-.markdown-editor .agent-thread-card__message-content table {
+.agent-conversation-surface .agent-thread-card__message-content table {
   width: 100%;
   margin: 8px 0;
   border-collapse: separate;
   border-spacing: 0;
   border-radius: 8px;
   overflow: hidden;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(
+    var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1)
+  );
 }
-.markdown-editor .agent-thread-card__message-content thead {
+.agent-conversation-surface .agent-thread-card__message-content thead {
   background: transparent;
 }
 /* table 是外层圆角容器, tbody 保留圆角作为内部边界兜底; overflow: hidden
  * 把 thead / tbody 的 cell 边框按表格整体形状裁剪成圆角视觉。 */
-.markdown-editor .agent-thread-card__message-content tbody {
+.agent-conversation-surface .agent-thread-card__message-content tbody {
   border-radius: 8px;
   overflow: hidden;
 }
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   tbody
   tr:last-child
   td:first-child,
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   tbody
   tr:last-child
   th:first-child {
   border-bottom-left-radius: 8px;
 }
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   tbody
   tr:last-child
   td:last-child,
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-content
   tbody
   tr:last-child
   th:last-child {
   border-bottom-right-radius: 8px;
 }
-.markdown-editor .agent-thread-card__message-content th,
-.markdown-editor .agent-thread-card__message-content td {
+.agent-conversation-surface .agent-thread-card__message-content th,
+.agent-conversation-surface .agent-thread-card__message-content td {
   padding: 6px 10px;
   border: 1px solid var(--border);
   color: var(--foreground);
@@ -750,47 +738,47 @@
 }
 /* 头行底色对齐编辑器 (--muted); thead transparent 让 th 的底色
  * 直接透出, 不与 table 自身重叠。 */
-.markdown-editor .agent-thread-card__message-content th {
+.agent-conversation-surface .agent-thread-card__message-content th {
   background: color-mix(in srgb, var(--muted) 50%, var(--background));
   font-weight: 600;
 }
 /* 相邻 cell 共用一条边 ── 把每条边归属到"左/上"侧, 让行内/列内交界
  * 不出现双倍 1px 视觉。 */
-.markdown-editor .agent-thread-card__message-content th + th,
-.markdown-editor .agent-thread-card__message-content td + td,
-.markdown-editor .agent-thread-card__message-content th + td,
-.markdown-editor .agent-thread-card__message-content td + th {
+.agent-conversation-surface .agent-thread-card__message-content th + th,
+.agent-conversation-surface .agent-thread-card__message-content td + td,
+.agent-conversation-surface .agent-thread-card__message-content th + td,
+.agent-conversation-surface .agent-thread-card__message-content td + th {
   border-left: 0;
 }
-.markdown-editor .agent-thread-card__message-content tr + tr th,
-.markdown-editor .agent-thread-card__message-content tr + tr td {
+.agent-conversation-surface .agent-thread-card__message-content tr + tr th,
+.agent-conversation-surface .agent-thread-card__message-content tr + tr td {
   border-top: 0;
 }
 /* thead ↔ tbody 接缝去重 ── 默认两段 cell 各画一条边会在接缝处叠
  * 成 2px, 这里压掉 tbody 首行 cell 的 border-top, 让 thead 末行 cell
  * 的 border-bottom 独自承担"分隔线"职责, 视觉上仍是 1px。 */
-.markdown-editor .agent-thread-card__message-content
+.agent-conversation-surface .agent-thread-card__message-content
   tbody
   tr:first-child
   th,
-.markdown-editor .agent-thread-card__message-content
+.agent-conversation-surface .agent-thread-card__message-content
   tbody
   tr:first-child
   td {
   border-top: 0;
 }
 
-.markdown-editor .agent-thread-card__empty {
+.agent-conversation-surface .agent-thread-card__empty {
   display: flex;
   align-items: center;
   justify-content: center;
   gap: 8px;
   min-height: 38px;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(var(--font-size, 16px) * 0.9);
 }
 
-.markdown-editor .agent-thread-card__empty--codex-settings {
+.agent-conversation-surface .agent-thread-card__empty--codex-settings {
   flex-direction: column;
   flex-wrap: nowrap;
   align-items: center;
@@ -800,17 +788,7 @@
   padding: 4px 10px;
 }
 
-/* 非全屏 thread card 保持原有单行表现: 控件组不产生额外盒子, Agent 图标
- * 不参与布局。居中 + 图标只在独立对话 / 全屏两种大画布下开启。 */
-.markdown-editor .agent-thread-card__empty-controls {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: 6px;
-}
-
-.markdown-editor .agent-thread-card__empty-agent-icon {
+.agent-conversation-surface .agent-thread-card__empty-agent-icon {
   display: block;
   width: 5rem;
   height: 5rem;
@@ -821,21 +799,21 @@
 /* Keep every empty Thread Card centered, including the embedded card surface.
  * The composer remains the independent bottom row; only the empty-state
  * content (Agent setup plus featured notes) participates in this centering. */
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__body:has(> .agent-thread-card__empty--codex-settings) {
   display: flex;
   flex-direction: column;
   justify-content: center;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__body:has(> .agent-thread-card__empty--codex-settings)
   > .agent-thread-card__loading-indicator {
   height: 0;
   overflow: hidden;
 }
 
-.markdown-editor .agent-thread-card__dsh-update-notice {
+.agent-conversation-surface .agent-thread-card__dsh-update-notice {
   position: relative;
   overflow: hidden;
   display: none;
@@ -850,12 +828,12 @@
   cursor: pointer;
 }
 
-.markdown-editor .agent-thread-card__dsh-update-label {
+.agent-conversation-surface .agent-thread-card__dsh-update-label {
   position: relative;
   z-index: 1;
 }
 
-.markdown-editor .agent-thread-card__dsh-update-progress {
+.agent-conversation-surface .agent-thread-card__dsh-update-progress {
   position: absolute;
   right: 0;
   bottom: 0;
@@ -867,7 +845,7 @@
   transition: transform 180ms ease;
 }
 
-.markdown-editor .agent-thread-card__dsh-update-notice.is-updating .agent-thread-card__dsh-update-progress {
+.agent-conversation-surface .agent-thread-card__dsh-update-notice.is-updating .agent-thread-card__dsh-update-progress {
   transform: scaleX(1);
   background: linear-gradient(
     to right,
@@ -876,13 +854,13 @@
   );
 }
 
-.markdown-editor .agent-thread-card__dsh-update-notice.is-updating.is-indeterminate .agent-thread-card__dsh-update-progress {
+.agent-conversation-surface .agent-thread-card__dsh-update-notice.is-updating.is-indeterminate .agent-thread-card__dsh-update-progress {
   background: var(--primary);
   animation: dsh-update-progress-indeterminate 1.2s ease-in-out infinite;
   transform-origin: center;
 }
 
-.markdown-editor .agent-thread-card__dsh-update-notice:disabled {
+.agent-conversation-surface .agent-thread-card__dsh-update-notice:disabled {
   cursor: default;
 }
 
@@ -891,143 +869,45 @@
   to { transform: translateX(100%) scaleX(0.35); }
 }
 
-.markdown-editor.agent-conversation-detail .agent-thread-card__dsh-update-notice,
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__dsh-update-notice {
+.agent-conversation-surface
+  .agent-thread-card__empty--expanded
+  .agent-thread-card__dsh-update-notice {
   display: inline-flex;
 }
 
-.markdown-editor .agent-thread-card__dsh-update-notice[hidden] {
+.agent-conversation-surface .agent-thread-card__dsh-update-notice[hidden] {
   display: none;
 }
 
-.markdown-editor .agent-thread-card__pi-unavailable-notice:not([hidden]) {
+.agent-conversation-surface .agent-thread-card__pi-unavailable-notice:not([hidden]) {
   display: inline-flex;
   cursor: default;
 }
 
-.markdown-editor .agent-thread-card__pi-model-notice:not([hidden]) {
+.agent-conversation-surface .agent-thread-card__pi-model-notice:not([hidden]) {
   display: inline-flex;
   gap: 3px;
   cursor: pointer;
 }
 
-.markdown-editor .agent-thread-card__pi-model-notice:hover {
+.agent-conversation-surface .agent-thread-card__pi-model-notice:hover {
   background: color-mix(in srgb, var(--primary) 12%, transparent);
 }
 
-.markdown-editor .agent-thread-card__pi-model-notice:focus-visible {
+.agent-conversation-surface .agent-thread-card__pi-model-notice:focus-visible {
   outline: 2px solid color-mix(in srgb, var(--primary) 55%, transparent);
   outline-offset: 2px;
 }
 
-.markdown-editor.agent-conversation-detail
-  .agent-thread-card__empty--codex-settings,
-.markdown-editor
-  .agent-thread-card--fullscreen
-  .agent-thread-card__empty--codex-settings {
+.agent-conversation-surface .agent-thread-card__empty--expanded {
   /* 居中由 body 负责, 这里让空状态自身在纵向不被拉伸。 */
   flex: 0 0 auto;
 }
 
-.markdown-editor .agent-thread-card__empty-control {
-  display: inline-flex;
-  align-items: center;
-  max-width: 190px;
-  min-width: 0;
-  height: 28px;
-  gap: 5px;
-  padding: 0 8px;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
-  line-height: 1;
-  cursor: pointer;
-  user-select: none;
-  transition:
-    background-color 120ms ease,
-    color 120ms ease;
-}
-
-/* 模型名现在会带上思考深度 (例如 "GPT-5.5 · medium"), 给模型控件
- * 单独留出更多空间，避免比全屏输入框更早截断。 */
-.markdown-editor .agent-thread-card__empty-control[data-kind='model'] {
-  max-width: 240px;
-}
-
-.markdown-editor .agent-thread-card__empty-workspace {
-  display: inline-flex;
-  align-items: center;
-  max-width: 190px;
-  min-width: 0;
-  height: 28px;
-  gap: 5px;
-  padding: 0 8px;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1;
-  font-family: inherit;
-  cursor: pointer;
-  user-select: none;
-  transition:
-    background-color 120ms ease,
-    color 120ms ease;
-}
-
-.markdown-editor .agent-thread-card__empty-workspace-value {
-  min-width: 0;
-  overflow: hidden;
-  /* 与模型控件的 value 保持一致：名称使用前景色，label 仍使用次级色。 */
-  color: var(--foreground);
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  line-height: 1.6;
-}
-
-.markdown-editor .agent-thread-card__empty-workspace:hover,
-.markdown-editor .agent-thread-card__empty-workspace:focus-visible,
-.markdown-editor .agent-thread-card__empty-workspace--open {
-  background: var(--muted);
-  color: var(--foreground);
-  outline: none;
-}
-
-.markdown-editor .agent-thread-card__empty-control:hover,
-.markdown-editor .agent-thread-card__empty-control--open,
-.markdown-editor .agent-thread-card__empty-control:focus-visible {
-  background: var(--muted);
-  color: var(--foreground);
-}
-
-.markdown-editor .agent-thread-card__empty-control-label {
-  flex: 0 0 auto;
-}
-
-.markdown-editor .agent-thread-card__empty-control-value {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  color: var(--foreground);
-  line-height: 1.6;
-}
-
-.markdown-editor .agent-thread-card__empty-control-chevron {
-  width: 12px;
-  height: 12px;
-  flex: 0 0 auto;
-  color: currentColor;
-  opacity: 0.72;
-}
-
 /* Featured note shortcuts keep the empty state useful without turning it
  * into a dense launcher. A page stays to one row and preserves the generous
  * whitespace around the empty-state controls. */
-.markdown-editor .agent-thread-card__featured-notes {
+.agent-conversation-surface .agent-thread-card__featured-notes {
   position: relative;
   width: min(100%, 740px);
   flex: 0 0 auto;
@@ -1036,17 +916,14 @@
   color: var(--foreground);
 }
 
-/* Keep embedded cards compact while preserving shortcuts in standalone chats,
- * which share the agent-thread-card class without using fullscreen mode. */
-.markdown-editor
-  .agent-thread-card:not(.agent-thread-card--fullscreen):not(
-    .agent-conversation-detail__card
-  )
+/* Inline cards stay compact; expanded surfaces keep the shared shortcuts. */
+.agent-conversation-surface
+  .agent-thread-card__empty--inline-card
   .agent-thread-card__featured-notes {
   display: none;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-header {
+.agent-conversation-surface .agent-thread-card__featured-notes-header {
   display: flex;
   align-items: center;
   justify-content: flex-start;
@@ -1055,25 +932,25 @@
   padding: 0 4px 5px;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-header[hidden],
-.markdown-editor .agent-thread-card__featured-notes-navigation[hidden],
-.markdown-editor .agent-thread-card__featured-notes-nav[hidden] {
+.agent-conversation-surface .agent-thread-card__featured-notes-header[hidden],
+.agent-conversation-surface .agent-thread-card__featured-notes-navigation[hidden],
+.agent-conversation-surface .agent-thread-card__featured-notes-nav[hidden] {
   display: none;
 }
 
-/* 弹层与运算符菜单已挂到 document.body, 不再是 .markdown-editor 的后代,
+/* 弹层与运算符菜单已挂到 document.body, 不再是 .agent-conversation-surface 的后代,
  * 必须单独列出, 否则 [hidden] 不生效、关闭后仍会显示。 */
 .agent-thread-card__featured-notes-settings[hidden],
 .agent-thread-card__featured-notes-operator-menu[hidden] {
   display: none;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-navigation {
+.agent-conversation-surface .agent-thread-card__featured-notes-navigation {
   display: inline-flex;
   gap: 2px;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-nav {
+.agent-conversation-surface .agent-thread-card__featured-notes-nav {
   display: inline-grid;
   width: 22px;
   height: 22px;
@@ -1089,19 +966,19 @@
   transition: background-color 120ms ease, color 120ms ease;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-nav:hover:not(:disabled),
-.markdown-editor .agent-thread-card__featured-notes-nav:focus-visible {
+.agent-conversation-surface .agent-thread-card__featured-notes-nav:hover:not(:disabled),
+.agent-conversation-surface .agent-thread-card__featured-notes-nav:focus-visible {
   background: var(--muted);
   color: var(--foreground);
   outline: none;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-nav:disabled {
+.agent-conversation-surface .agent-thread-card__featured-notes-nav:disabled {
   color: color-mix(in srgb, var(--muted-foreground) 35%, transparent);
   cursor: default;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-settings-footer {
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-footer {
   position: relative;
   display: flex;
   align-items: center;
@@ -1111,19 +988,19 @@
 }
 
 /* 添加常用笔记按钮相对整行居中, 不受右侧翻页控件宽度影响。 */
-.markdown-editor .agent-thread-card__featured-notes-settings-button {
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-button {
   position: absolute;
   left: 50%;
   transform: translateX(-50%);
 }
 
 /* 翻页控件贴齐内容区域右侧。 */
-.markdown-editor .agent-thread-card__featured-notes-settings-footer
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-footer
   .agent-thread-card__featured-notes-navigation {
   margin-left: auto;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-settings-button {
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-button {
   min-height: 26px;
   padding: 0 10px;
   border: 1px solid color-mix(in srgb, var(--border) 82%, transparent);
@@ -1135,12 +1012,12 @@
   cursor: pointer;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-settings-button:hover,
-.markdown-editor .agent-thread-card__featured-notes-settings-button:focus-visible {
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-button:hover,
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-button:focus-visible {
   color: var(--foreground);
 }
 
-.markdown-editor .agent-thread-card__featured-notes-settings-button:focus-visible {
+.agent-conversation-surface .agent-thread-card__featured-notes-settings-button:focus-visible {
   outline: 2px solid color-mix(in srgb, var(--primary) 42%, var(--border));
   outline-offset: 2px;
 }
@@ -1151,7 +1028,7 @@
  * 视口坐标定位 (见 popover-position.ts)。这样弹层不受任何祖先的 overflow 裁剪,
  * 也不受祖先层叠上下文限制, 空状态下不会再有"被下面输入框遮住"的问题。
  *
- * 注意: 因为不在 .markdown-editor 子树内, 这一组选择器都不带该前缀。 */
+ * 注意: 因为不在 .agent-conversation-surface 子树内, 这一组选择器都不带该前缀。 */
 .agent-thread-card__featured-notes-settings {
   position: fixed;
   /* top/left 由 JS 计算写入, 这里给初值避免首帧跳动。 */
@@ -1446,23 +1323,23 @@
   height: 14px;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-list {
+.agent-conversation-surface .agent-thread-card__featured-notes-list {
   display: grid;
   grid-template-columns: repeat(3, minmax(0, 1fr));
   gap: 10px;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-list[data-card-count="1"] {
+.agent-conversation-surface .agent-thread-card__featured-notes-list[data-card-count="1"] {
   grid-template-columns: minmax(0, 240px);
   justify-content: center;
 }
 
-.markdown-editor .agent-thread-card__featured-notes-list[data-card-count="2"] {
+.agent-conversation-surface .agent-thread-card__featured-notes-list[data-card-count="2"] {
   grid-template-columns: repeat(2, minmax(0, 240px));
   justify-content: center;
 }
 
-.markdown-editor .agent-thread-card__featured-note {
+.agent-conversation-surface .agent-thread-card__featured-note {
   display: flex;
   width: 100%;
   min-height: 128px;
@@ -1479,21 +1356,21 @@
   transition: color 140ms ease;
 }
 
-.markdown-editor .agent-thread-card__featured-note:hover {
+.agent-conversation-surface .agent-thread-card__featured-note:hover {
   color: var(--primary);
 }
 
-.markdown-editor .agent-thread-card__featured-note:hover
+.agent-conversation-surface .agent-thread-card__featured-note:hover
   .agent-thread-card__featured-note-description {
   color: var(--primary);
 }
 
-.markdown-editor .agent-thread-card__featured-note:focus-visible {
+.agent-conversation-surface .agent-thread-card__featured-note:focus-visible {
   outline: 2px solid color-mix(in srgb, var(--primary) 42%, var(--border));
   outline-offset: 2px;
 }
 
-.markdown-editor .agent-thread-card__featured-note-icon {
+.agent-conversation-surface .agent-thread-card__featured-note-icon {
   display: grid;
   width: 18px;
   height: 18px;
@@ -1513,33 +1390,33 @@
 /* 图标值解析后可能是 <img> (属性图标)、<svg> (笔记本图标) 或纯文本 (emoji /
  * 单字)。图形子元素铺满 18px 容器; object-fit 给内联 SVG 兜底, 避免按原始
  * viewBox 撑破容器。 */
-.markdown-editor .agent-thread-card__featured-note-icon > img,
-.markdown-editor .agent-thread-card__featured-note-icon > svg {
+.agent-conversation-surface .agent-thread-card__featured-note-icon > img,
+.agent-conversation-surface .agent-thread-card__featured-note-icon > svg {
   display: block;
   width: 100%;
   height: 100%;
   object-fit: contain;
 }
 
-.markdown-editor .agent-thread-card__featured-note-content {
+.agent-conversation-surface .agent-thread-card__featured-note-content {
   display: grid;
   min-width: 0;
   gap: 5px;
 }
 
-.markdown-editor .agent-thread-card__featured-note-title {
+.agent-conversation-surface .agent-thread-card__featured-note-title {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.markdown-editor .agent-thread-card__featured-note-title {
+.agent-conversation-surface .agent-thread-card__featured-note-title {
   font-size: 13px;
   font-weight: 550;
   line-height: 1.35;
 }
 
-.markdown-editor .agent-thread-card__featured-note-description {
+.agent-conversation-surface .agent-thread-card__featured-note-description {
   display: -webkit-box;
   overflow: hidden;
   -webkit-box-orient: vertical;
@@ -1550,11 +1427,11 @@
 }
 
 @media (max-width: 767px) {
-  .markdown-editor .agent-thread-card__featured-notes {
+  .agent-conversation-surface .agent-thread-card__featured-notes {
     width: min(100%, calc(100vw - 24px));
   }
 
-  .markdown-editor .agent-thread-card__featured-notes-list {
+  .agent-conversation-surface .agent-thread-card__featured-notes-list {
     grid-template-columns: repeat(2, minmax(0, 1fr));
     gap: 8px;
   }
@@ -1775,7 +1652,7 @@
   border-radius: 8px;
   background: transparent;
   color: var(--foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(var(--font-size, 16px) * 0.9);
   line-height: 1.2;
   text-align: left;
   cursor: pointer;
@@ -1904,7 +1781,7 @@
 .agent-thread-card__codex-settings-empty {
   padding: 12px 8px;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(var(--font-size, 16px) * 0.9);
   line-height: 1.4;
   text-align: center;
 }
@@ -1933,7 +1810,7 @@
   border-radius: 8px;
   background: transparent;
   color: var(--foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(var(--font-size, 16px) * 0.9);
   line-height: 1.2;
   text-align: left;
   cursor: default;
@@ -1990,7 +1867,7 @@
 }
 
 .agent-thread-card__codex-settings-repository-remove
-  .agent-thread-card__trash-icon {
+  .agent-icon__trash {
   width: 14px;
   height: 14px;
 }
@@ -2027,6 +1904,14 @@
   color: var(--muted-foreground);
 }
 
+.agent-thread-card__model-provider-icon {
+  width: 20px;
+  height: 20px;
+  flex: 0 0 auto;
+  border-radius: 5px;
+  object-fit: contain;
+}
+
 .agent-thread-card__permission-mode-icon--warning {
   color: var(--destructive);
 }
@@ -2095,7 +1980,7 @@
   overflow: hidden;
 }
 
-.markdown-editor .agent-thread-card__loading-indicator {
+.agent-conversation-surface .agent-thread-card__loading-indicator {
   display: flex;
   align-items: center;
   gap: 0.3rem;
@@ -2104,32 +1989,16 @@
   height: 38px;
   padding: 0rem;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* was 0.78rem ≈ 12.48px */
+  font-size: calc(var(--font-size, 16px) * 0.9); /* was 0.78rem ≈ 12.48px */
   font-weight: 500;
   line-height: 1;
 }
 
-.markdown-editor .agent-thread-card__loading-indicator[role="status"] {
+.agent-conversation-surface .agent-thread-card__loading-indicator[role="status"] {
   min-width: 0;
 }
 
-.markdown-editor
-  .agent-thread-card--fullscreen
-  .agent-thread-card__loading-indicator {
-  width: calc(100% - 3rem);
-  max-width: 780px;
-  margin-inline: auto;
-}
-
-/* The standalone detail is not CSS-fullscreen, but its message column uses
- * the same centered width as the fullscreen Thread Card. */
-.markdown-editor.agent-conversation-detail .agent-thread-card__loading-indicator {
-  width: calc(100% - 3rem);
-  max-width: 780px;
-  margin-inline: auto;
-}
-
-.markdown-editor .agent-thread-card__loading-cells {
+.agent-conversation-surface .agent-thread-card__loading-cells {
   display: inline-grid;
   grid-template-columns: repeat(2, 4px);
   grid-template-rows: repeat(2, 4px);
@@ -2138,7 +2007,7 @@
   line-height: 0;
 }
 
-.markdown-editor .agent-thread-card__loading-cell {
+.agent-conversation-surface .agent-thread-card__loading-cell {
   display: inline-block;
   width: 4px;
   height: 4px;
@@ -2173,7 +2042,7 @@
   animation-delay: calc(var(--cell-step, 0) * 0.6s - 0.36s);
 }
 
-.markdown-editor .agent-thread-card__loading-text {
+.agent-conversation-surface .agent-thread-card__loading-text {
   line-height: 1.5;
   /* 文本不再做扫光 ── 动效交给 2×2 格顺序点亮; 文字本身保持纯前景色,
    * 视觉负担小, 也避免 WebKit 在 background-clip:text + background:
@@ -2181,8 +2050,8 @@
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__loading-cells[hidden],
-.markdown-editor .agent-thread-card__loading-text[hidden] {
+.agent-conversation-surface .agent-thread-card__loading-cells[hidden],
+.agent-conversation-surface .agent-thread-card__loading-text[hidden] {
   display: none;
 }
 
@@ -2227,14 +2096,14 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .markdown-editor .agent-thread-card__loading-cell {
+  .agent-conversation-surface .agent-thread-card__loading-cell {
     animation: none;
     background-color: var(--muted-foreground);
   }
 }
 
 /* 折叠态 ── 与 body 一起消失, 不留孤立的 24px 空白带。 */
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card--collapsed
   .agent-thread-card__loading-indicator {
   display: none;
diff --git a/app/flowix-web/styles/agent-thread-card/messages.css b/app/flowix-web/styles/agent-thread-card/messages.css
index 03e13748c..a353de321 100644
--- a/app/flowix-web/styles/agent-thread-card/messages.css
+++ b/app/flowix-web/styles/agent-thread-card/messages.css
@@ -11,12 +11,13 @@
  *
  * 卡片 base 默认 "无背景无圆角", 5 个 role 修饰类各自按面板
  * 对应风格覆盖 ── 不再是"一统气泡"模式。 */
-.markdown-editor .agent-thread-card__message {
+.agent-conversation-surface .agent-thread-card__message {
   display: grid;
   gap: 4px;
   padding: 0;
   border-radius: 0;
   background: transparent;
+  font-family: var(--agent-message-font-family, var(--font-sans));
   -webkit-user-select: none;
   user-select: none;
 }
@@ -28,7 +29,7 @@
  * 面板 user 圆角: 8px 16px 8px 8px (右上 2xl 最圆, 其它 lg)。
  * margin-left: auto 在 flex column 容器里把 user 推右 (CSS 端
  * 替代 row-reverse, 不破坏 assistant 左对齐)。 */
-.markdown-editor .agent-thread-card__message--user {
+.agent-conversation-surface .agent-thread-card__message--user {
   width: 100%;
   margin-top: 0;
   max-width: 100%;
@@ -36,7 +37,7 @@
   justify-items: end;
 }
 
-.markdown-editor .agent-thread-card__message-user-bubble {
+.agent-conversation-surface .agent-thread-card__message-user-bubble {
   width: fit-content;
   max-width: 100%;
   padding: 8px 12px;
@@ -44,14 +45,78 @@
   background: var(--muted);
 }
 
-.markdown-editor .agent-thread-card__message-pi-skill-tags {
+/* The user bubble adds its own 8px/12px inset around Markdown. Let fenced
+ * blocks use the same outer spacing as assistant pre blocks while retaining
+ * the bubble inset for surrounding prose. */
+.agent-conversation-surface
+  .agent-thread-card__message-user-bubble
+  .agent-thread-card__message-content
+  > pre {
+  margin-right: -12px;
+  margin-left: -12px;
+}
+
+.agent-conversation-surface
+  .agent-thread-card__message-user-bubble
+  .agent-thread-card__message-content
+  > pre:first-child {
+  margin-top: -8px;
+}
+
+.agent-conversation-surface
+  .agent-thread-card__message-user-bubble
+  .agent-thread-card__message-content
+  > pre:last-child {
+  margin-bottom: -8px;
+}
+
+.agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  pre,
+.agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  pre
+  *,
+.agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  code,
+.agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  code
+  * {
+  background: transparent !important;
+}
+
+html:not([data-theme="dark"])
+  .agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  pre,
+html:not([data-theme="dark"])
+  .agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  th,
+html:not([data-theme="dark"])
+  .agent-conversation-surface
+  .agent-thread-card__message--user
+  .agent-thread-card__message-content
+  td {
+  border-color: color-mix(in oklch, var(--border) 95%, var(--foreground) 5%);
+}
+
+.agent-conversation-surface .agent-thread-card__message-pi-skill-tags {
   display: flex;
   flex-wrap: wrap;
   gap: 4px;
   margin-bottom: 4px;
 }
 
-.markdown-editor .agent-thread-card__message-pi-skill-tag {
+.agent-conversation-surface .agent-thread-card__message-pi-skill-tag {
   display: inline-flex;
   align-items: center;
   width: fit-content;
@@ -66,83 +131,104 @@
   overflow-wrap: anywhere;
 }
 
-.markdown-editor .agent-thread-card__message-attachments {
+.agent-conversation-surface .agent-thread-card__message-attachments {
   display: flex;
+  flex-wrap: wrap;
   justify-content: flex-end;
-  gap: 8px;
+  gap: 4px;
   max-width: 100%;
-  margin-top: 0;
-  overflow-x: auto;
+  margin-top: 6px;
 }
 
-.markdown-editor .agent-thread-card__message-attachment {
-  position: relative;
-  display: block;
+.agent-conversation-surface .agent-thread-card__message-attachment {
+  display: inline-flex;
+  box-sizing: border-box;
+  min-width: 0;
+  max-width: min(16rem, 100%);
+  height: 1.6em;
   align-items: center;
-  width: 52px;
-  height: 52px;
-  min-width: 52px;
-  max-width: 52px;
-  min-height: 52px;
-  max-height: 52px;
-  padding: 2px;
-  border: 1px solid var(--border);
-  border-radius: 0.55rem;
-  background: var(--muted);
+  gap: 0.3rem;
+  padding: 0 0.45rem;
+  border: 1px solid color-mix(in oklch, var(--border) 95%, var(--muted) 5%);
+  border-radius: 0.35rem;
+  background: transparent;
   color: var(--foreground);
   cursor: default;
+  overflow: hidden;
+  white-space: nowrap;
 }
 
-.markdown-editor .agent-thread-card__message-attachment-icon {
-  display: flex;
+.agent-conversation-surface .agent-thread-card__message-attachment-icon {
+  display: inline-flex;
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
   align-items: center;
   justify-content: center;
-  width: 100%;
-  height: 100%;
-  border-radius: 0.4rem;
-  background: transparent;
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__message-attachment-icon svg {
-  width: 18px;
-  height: 18px;
+.agent-conversation-surface .agent-thread-card__message-attachment-icon svg {
+  width: 14px;
+  height: 14px;
 }
 
-.markdown-editor .agent-thread-card__message-attachment-preview {
+.agent-conversation-surface .agent-thread-card__message-attachment-preview {
   display: block;
-  width: 100%;
-  height: 100%;
-  border-radius: 0.4rem;
+  width: 14px;
+  height: 14px;
+  border-radius: 0.16rem;
   object-fit: cover;
 }
 
+.agent-conversation-surface .agent-thread-card__message-attachment-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-conversation-surface .agent-thread-card__message-mode-tag {
+  display: flex;
+  width: fit-content;
+  height: auto;
+  margin: 0 0 5px auto;
+  padding: 4px 8px;
+  border-color: var(--border);
+  border-radius: 7px;
+  background: var(--background);
+  font-size: var(--agent-message-base-font-size, 15px);
+  line-height: 1.2;
+}
+
 /* ── assistant: 纯文本, 无气泡, 顶部 mt-1 留白 ────────────────
  * 面板 assistant = `text-sm mt-1`, 无背景无圆角, 占满左侧。 */
-.markdown-editor .agent-thread-card__message--assistant {
+.agent-conversation-surface .agent-thread-card__message--assistant {
   padding: 4px 0 0;
   color: var(--foreground);
 }
 
-[data-theme="dark"] .markdown-editor .agent-thread-card__message--assistant,
-[data-theme="dark"] .markdown-editor .agent-thread-card__message--assistant .agent-thread-card__message-content {
+[data-theme="dark"] .agent-conversation-surface .agent-thread-card__message--assistant,
+[data-theme="dark"] .agent-conversation-surface .agent-thread-card__message--assistant .agent-thread-card__message-content {
   color: var(--foreground);
 }
 
-.markdown-editor .agent-thread-card__message--system {
+.agent-conversation-surface .agent-thread-card__message--system {
   padding: 2px 0;
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__message-context-compaction {
+.agent-conversation-surface .agent-thread-card__message-context-compaction {
   align-self: flex-start;
   padding-top: 8px;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+  font-size: calc(
+    var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 0.9
+  );
   line-height: 1.4;
   font-style: italic;
 }
 
-.markdown-editor .agent-thread-card__message-context-compaction-summary {
+.agent-conversation-surface .agent-thread-card__message-context-compaction-summary {
   margin-top: 4px;
   font-style: normal;
 }
@@ -150,23 +236,25 @@
 /* DSH goal prompts are internal model-control messages. They remain visible
  * as a small timeline status row, while their long instructions are removed
  * by the DSH history projection before this renderer is reached. */
-.markdown-editor .agent-thread-card__message--goal-control {
+.agent-conversation-surface .agent-thread-card__message--goal-control {
   align-self: flex-start;
   padding: 2px 0;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.86);
+  font-size: calc(
+    var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 0.86
+  );
   line-height: 1.35;
 }
 
-.markdown-editor .agent-thread-card__message-goal-control {
+.agent-conversation-surface .agent-thread-card__message-goal-control {
   font-style: italic;
 }
 
-.markdown-editor .agent-thread-card__message--goal-complete {
+.agent-conversation-surface .agent-thread-card__message--goal-complete {
   color: var(--foreground);
 }
 
-.markdown-editor .agent-thread-card__message--goal-blocked {
+.agent-conversation-surface .agent-thread-card__message--goal-blocked {
   color: var(--destructive);
 }
 
@@ -174,34 +262,38 @@
  * ordinary model messages. Keep the visual treatment compact while retaining
  * the source marker so commands from other agents cannot be confused with
  * this provider's controls. */
-.markdown-editor .agent-thread-card__message--dsh-command {
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+.agent-conversation-surface .agent-thread-card__message--dsh-command {
+  font-size: calc(
+    var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 0.9
+  );
 }
 
-.markdown-editor .agent-thread-card__message--dsh-command-loading {
+.agent-conversation-surface .agent-thread-card__message--dsh-command-loading {
   opacity: 0.72;
 }
 
-.markdown-editor .agent-thread-card__message--dsh-command-result {
+.agent-conversation-surface .agent-thread-card__message--dsh-command-result {
   align-self: flex-start;
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__message--dsh-command-prompt {
+.agent-conversation-surface .agent-thread-card__message--dsh-command-prompt {
   border: 1px solid color-mix(in srgb, var(--brand) 28%, transparent);
 }
 
 /* Codex-native slash commands are product-owned user rows. They use the same
  * compact treatment as DSH command rows, but keep a distinct provider badge. */
-.markdown-editor .agent-thread-card__message--codex-command {
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
+.agent-conversation-surface .agent-thread-card__message--codex-command {
+  font-size: calc(
+    var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1) * 0.9
+  );
 }
 
-.markdown-editor .agent-thread-card__message--codex-command-loading {
+.agent-conversation-surface .agent-thread-card__message--codex-command-loading {
   opacity: 0.72;
 }
 
-.markdown-editor .agent-thread-card__message-dsh-badge {
+.agent-conversation-surface .agent-thread-card__message-dsh-badge {
   display: inline-flex;
   align-items: center;
   width: fit-content;
@@ -213,7 +305,7 @@
   line-height: 1.2;
 }
 
-.markdown-editor .agent-thread-card__message-codex-badge {
+.agent-conversation-surface .agent-thread-card__message-codex-badge {
   display: inline-flex;
   align-items: center;
   width: fit-content;
@@ -225,13 +317,13 @@
   line-height: 1.2;
 }
 
-.markdown-editor .agent-thread-card__message-dsh-result {
+.agent-conversation-surface .agent-thread-card__message-dsh-result {
   display: inline-flex;
   align-items: baseline;
   gap: 6px;
 }
 
-.markdown-editor .agent-thread-card__message-actions {
+.agent-conversation-surface .agent-thread-card__message-actions {
   display: flex;
   position: relative;
   align-items: center;
@@ -247,7 +339,7 @@
     visibility 0s linear 150ms;
 }
 
-.markdown-editor .agent-thread-card__message-fork-confirm {
+.agent-conversation-surface .agent-thread-card__message-fork-confirm {
   display: flex;
   position: absolute;
   bottom: calc(100% + 4px);
@@ -267,8 +359,8 @@
   animation: agent-thread-card-fork-confirm-in 120ms cubic-bezier(0.16, 1, 0.3, 1) both;
 }
 
-.markdown-editor .agent-thread-card__message-fork-confirm-button,
-.markdown-editor .agent-thread-card__message-fork-cancel-button {
+.agent-conversation-surface .agent-thread-card__message-fork-confirm-button,
+.agent-conversation-surface .agent-thread-card__message-fork-cancel-button {
   display: flex;
   align-items: center;
   justify-content: flex-start;
@@ -290,10 +382,21 @@
     color 120ms ease;
 }
 
-.markdown-editor .agent-thread-card__message-fork-confirm-button:hover,
-.markdown-editor .agent-thread-card__message-fork-confirm-button:focus-visible,
-.markdown-editor .agent-thread-card__message-fork-cancel-button:hover,
-.markdown-editor .agent-thread-card__message-fork-cancel-button:focus-visible {
+.agent-conversation-surface .agent-thread-card__message-fork-loading-icon {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  --flowix-spin-duration: 0.8s;
+}
+
+.agent-conversation-surface .agent-thread-card__message-fork-confirm-button {
+  gap: 6px;
+}
+
+.agent-conversation-surface .agent-thread-card__message-fork-confirm-button:hover,
+.agent-conversation-surface .agent-thread-card__message-fork-confirm-button:focus-visible,
+.agent-conversation-surface .agent-thread-card__message-fork-cancel-button:hover,
+.agent-conversation-surface .agent-thread-card__message-fork-cancel-button:focus-visible {
   background: var(--brand);
   color: var(--primary-foreground);
 }
@@ -310,20 +413,21 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .markdown-editor .agent-thread-card__message-fork-confirm {
+  .agent-conversation-surface .agent-thread-card__message-fork-confirm {
     animation: none;
   }
 }
 
-.markdown-editor .agent-thread-card__message:hover .agent-thread-card__message-actions,
-.markdown-editor .agent-thread-card__message:focus-within .agent-thread-card__message-actions {
+.agent-conversation-surface .agent-thread-card__message:hover .agent-thread-card__message-actions,
+.agent-conversation-surface .agent-thread-card__message:focus-within .agent-thread-card__message-actions,
+.agent-conversation-surface .agent-thread-card__message--forking .agent-thread-card__message-actions {
   opacity: 1;
   visibility: visible;
   pointer-events: auto;
   transition-delay: 0s;
 }
 
-.markdown-editor .agent-thread-card__message-action {
+.agent-conversation-surface .agent-thread-card__message-action {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -342,18 +446,18 @@
     border-color 120ms ease;
 }
 
-.markdown-editor .agent-thread-card__message-action:hover {
+.agent-conversation-surface .agent-thread-card__message-action:hover {
   color: var(--foreground);
   background: var(--muted);
 }
 
-.markdown-editor .agent-thread-card__message-action svg {
+.agent-conversation-surface .agent-thread-card__message-action svg {
   width: 12px;
   height: 12px;
 }
 
-.markdown-editor .agent-thread-card__message-time,
-.markdown-editor .agent-thread-card__message-duration {
+.agent-conversation-surface .agent-thread-card__message-time,
+.agent-conversation-surface .agent-thread-card__message-duration {
   color: var(--muted-foreground);
   font-size: 12px;
   line-height: 22px;
@@ -361,21 +465,29 @@
   white-space: nowrap;
 }
 
-.markdown-editor
-  .agent-thread-card:not(.agent-thread-card--fullscreen)
+:is(
+    .agent-conversation-surface.agent-thread-card:not(.agent-thread-card--fullscreen),
+    .agent-conversation-surface .agent-thread-card:not(.agent-thread-card--fullscreen)
+  )
   .agent-thread-card__message--user
   .agent-thread-card__message-content,
-.markdown-editor
-  .agent-thread-card:not(.agent-thread-card--fullscreen)
+:is(
+    .agent-conversation-surface.agent-thread-card:not(.agent-thread-card--fullscreen),
+    .agent-conversation-surface .agent-thread-card:not(.agent-thread-card--fullscreen)
+  )
   .agent-thread-card__message--user
   .agent-thread-card__message-content
   *,
-.markdown-editor
-  .agent-thread-card:not(.agent-thread-card--fullscreen)
+:is(
+    .agent-conversation-surface.agent-thread-card:not(.agent-thread-card--fullscreen),
+    .agent-conversation-surface .agent-thread-card:not(.agent-thread-card--fullscreen)
+  )
   .agent-thread-card__message--assistant
   .agent-thread-card__message-content,
-.markdown-editor
-  .agent-thread-card:not(.agent-thread-card--fullscreen)
+:is(
+    .agent-conversation-surface.agent-thread-card:not(.agent-thread-card--fullscreen),
+    .agent-conversation-surface .agent-thread-card:not(.agent-thread-card--fullscreen)
+  )
   .agent-thread-card__message--assistant
   .agent-thread-card__message-content
   * {
@@ -400,14 +512,14 @@
  *     .__message--reasoning-collapsed .__message-reasoning-body { display: none }
  * 数值: pl-4 = 12px (这里 12px 与 6px ml-1.5 视觉接近, 同时让缩进在
  * 卡片宽度下不至于挤掉内容), border-l = 2px (卡片小尺寸下更可见)。 */
-.markdown-editor .agent-thread-card__message--reasoning {
+.agent-conversation-surface .agent-thread-card__message--reasoning {
   display: flex;
   flex-direction: column;
   gap: 4px;
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__message-reasoning-header {
+.agent-conversation-surface .agent-thread-card__message-reasoning-header {
   display: inline-flex;
   align-items: center;
   align-self: flex-start;
@@ -418,7 +530,7 @@
   border-radius: 4px;
   background: transparent;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
+  font-size: calc(var(--agent-message-base-font-size, 15px) * 0.9); /* text-xs */
   font-weight: 500;
   line-height: 1.1;
   cursor: pointer;
@@ -430,11 +542,11 @@
   transition: color 150ms ease;
 }
 
-.markdown-editor .agent-thread-card__message-reasoning-header:hover {
+.agent-conversation-surface .agent-thread-card__message-reasoning-header:hover {
   color: var(--foreground);
 }
 
-.markdown-editor .agent-thread-card__message-reasoning-header svg {
+.agent-conversation-surface .agent-thread-card__message-reasoning-header svg {
   display: block;
   width: 12px;
   height: 12px;
@@ -443,13 +555,13 @@
   transition: transform 150ms ease;
 }
 
-.markdown-editor .agent-thread-card__message-reasoning-body {
+.agent-conversation-surface .agent-thread-card__message-reasoning-body {
   padding: 2px 0 4px 12px;
   margin-left: 5px;
   border-left: 1px solid var(--border);
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message--reasoning-collapsed
   .agent-thread-card__message-reasoning-body {
   display: none;
@@ -467,7 +579,7 @@
  * 走 features/agent/message/tools 单源 registry (getToolIconPath),
  * 与面板 (inline SVG 同样 path) 共用 TOOL_ICON_PATHS regular weight 数据,
  * 视觉完全一致 (同样 14×14 渲染, 同样 muted-foreground 颜色)。未命中 → terminal。 */
-.markdown-editor .agent-thread-card__message--tool {
+.agent-conversation-surface .agent-thread-card__message--tool {
   display: flex;
   flex-wrap: nowrap;
   /* 图标容器固定为 18px，工具名/摘要首行也固定为 18px；
@@ -478,17 +590,18 @@
   padding: 4px 0;
   background: transparent;
   color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   line-height: 18px;
 }
 
 /* ── 连续工具组: 独立的两级折叠容器 ─────────────────────────────
  * header 是一级折叠; 已完成工具区域在展开时显示, 每个 tool row 仍保留
  * 自己的输入展开按钮; 进行中工具区域始终位于组尾并保持单行。 */
-.markdown-editor .agent-thread-card__tool-group {
+.agent-conversation-surface .agent-thread-card__tool-group {
   display: flex;
   flex-direction: column;
   min-width: 0;
+  font-family: var(--agent-message-font-family, var(--font-sans));
   padding-top: 6px;
   padding-bottom: 6px;
   padding-left: 4px;
@@ -499,7 +612,7 @@
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__tool-group-header {
+.agent-conversation-surface .agent-thread-card__tool-group-header {
   display: flex;
   align-items: center;
   align-self: stretch;
@@ -511,23 +624,24 @@
   border-radius: 4px;
   background: transparent;
   color: var(--foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-family: inherit;
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   line-height: 18px;
   cursor: pointer;
   transition: color 150ms ease;
 }
 
-.markdown-editor .agent-thread-card__tool-group-header:hover {
+.agent-conversation-surface .agent-thread-card__tool-group-header:hover {
   color: var(--brand);
 }
 
-.markdown-editor .agent-thread-card__tool-group--expanded
+.agent-conversation-surface .agent-thread-card__tool-group--expanded
   .agent-thread-card__tool-group-header {
   color: var(--brand);
 }
 
-.markdown-editor .agent-thread-card__tool-group-toggle,
-.markdown-editor .agent-thread-card__message-tool-toggle {
+.agent-conversation-surface .agent-thread-card__tool-group-toggle,
+.agent-conversation-surface .agent-thread-card__message-tool-toggle {
   display: inline-grid;
   flex: 0 0 auto;
   place-items: center;
@@ -539,30 +653,29 @@
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__tool-group-toggle {
+.agent-conversation-surface .agent-thread-card__tool-group-toggle {
   color: currentColor;
 }
 
-.markdown-editor .agent-thread-card__tool-group-toggle svg,
-.markdown-editor .agent-thread-card__message-tool-toggle svg {
+.agent-conversation-surface .agent-thread-card__tool-group-toggle svg,
+.agent-conversation-surface .agent-thread-card__message-tool-toggle svg {
   width: 13px;
   height: 13px;
   flex: 0 0 auto;
   transition: transform 150ms ease;
 }
 
-.markdown-editor .agent-thread-card__tool-group-running-loading-icon {
+.agent-conversation-surface .agent-thread-card__tool-group-running-loading-icon {
   width: 12px;
   height: 12px;
   flex: 0 0 auto;
   color: var(--muted-foreground);
-  animation: agent-thread-card-tool-group-running-loading 1s linear infinite;
 }
 
 /* The spinner is 12px visually, but its flex item must use the same 18px
  * first-line track as the tool icon and label. Without this wrapper the
  * spinner is aligned by its own box and appears a few pixels too high. */
-.markdown-editor .agent-thread-card__tool-group-running-loading-wrap {
+.agent-conversation-surface .agent-thread-card__tool-group-running-loading-wrap {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -572,82 +685,63 @@
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__tool-group-header-loading-icon {
+.agent-conversation-surface .agent-thread-card__tool-group-header-loading-icon {
   margin-left: auto;
 }
 
-.markdown-editor .agent-thread-card__tool-group-label {
+.agent-conversation-surface .agent-thread-card__tool-group-label {
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-@keyframes agent-thread-card-tool-group-running-loading {
-  to {
-    transform: rotate(360deg);
-  }
-}
-
-.markdown-editor .agent-thread-card__tool-group-header:focus-visible {
+.agent-conversation-surface .agent-thread-card__tool-group-header:focus-visible {
   outline: 2px solid color-mix(in srgb, var(--foreground) 45%, transparent);
   outline-offset: 1px;
 }
 
-.markdown-editor .agent-thread-card__tool-group--failed
-  .agent-thread-card__tool-group-header {
-  color: var(--destructive, var(--muted-foreground));
-}
-
-.markdown-editor .agent-thread-card__tool-group-completed-tools {
+.agent-conversation-surface .agent-thread-card__tool-group-completed-tools {
   display: none;
   min-width: 0;
   padding-top: 6px;
   padding-left: 24px;
 }
 
-.markdown-editor .agent-thread-card__tool-group--expanded
-  .agent-thread-card__tool-group-completed-tools {
-  display: flex;
-  flex-direction: column;
-}
-
-/* A failed tool keeps its fallback row visible while the group is collapsed,
- * so provider/rendering errors are not silently hidden behind the summary. */
-.markdown-editor .agent-thread-card__tool-group--failed
+.agent-conversation-surface .agent-thread-card__tool-group--expanded
   .agent-thread-card__tool-group-completed-tools {
   display: flex;
   flex-direction: column;
 }
 
-.markdown-editor .agent-thread-card__tool-group-running-tools {
+.agent-conversation-surface .agent-thread-card__tool-group-running-tools {
   display: flex;
   flex-direction: column;
   min-width: 0;
   padding-left: 24px;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__tool-group-running-tool
   .agent-thread-card__message-tool-icon-wrap {
   /* 与结束态工具行保持一致：工具 icon 顶部对齐。 */
   align-self: flex-start;
 }
 
-.markdown-editor .agent-thread-card__tool-group-running-tool {
+.agent-conversation-surface .agent-thread-card__tool-group-running-tool {
   display: flex;
   align-items: flex-start;
   padding: 6px 0;
 }
 
-.markdown-editor .agent-thread-card__tool-group--expanded
+.agent-conversation-surface .agent-thread-card__tool-group--expanded
   .agent-thread-card__tool-group-completed-tools
   .agent-thread-card__message {
   padding-top: 6px;
   padding-bottom: 6px;
 }
 
-.markdown-editor .agent-thread-card__message-tool-content {
+.agent-conversation-surface .agent-thread-card__message-tool-content {
   display: flex;
   position: relative;
   flex: 1 1 auto;
@@ -660,7 +754,7 @@
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__message-tool-row {
+.agent-conversation-surface .agent-thread-card__message-tool-row {
   display: flex;
   align-items: center;
   width: 100%;
@@ -671,37 +765,37 @@
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__message-tool-toggle {
+.agent-conversation-surface .agent-thread-card__message-tool-toggle {
   margin-left: auto;
   background: transparent;
   color: var(--muted-foreground);
   cursor: pointer;
 }
 
-.markdown-editor .agent-thread-card__message-tool-toggle:hover {
+.agent-conversation-surface .agent-thread-card__message-tool-toggle:hover {
   background: color-mix(in srgb, var(--muted-foreground) 10%, transparent);
   color: var(--foreground);
 }
 
-.markdown-editor .agent-thread-card__message-tool-toggle .agent-thread-card__chevron-icon {
+.agent-conversation-surface .agent-thread-card__message-tool-toggle .agent-thread-card__chevron-icon {
   width: 13px;
   height: 13px;
   transition: transform 150ms ease;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__message-tool-toggle
   .agent-thread-card__chevron-icon {
   transform: rotate(180deg);
 }
 
-.markdown-editor .agent-thread-card__message-tool-toggle:focus-visible {
+.agent-conversation-surface .agent-thread-card__message-tool-toggle:focus-visible {
   outline: 2px solid color-mix(in srgb, var(--foreground) 45%, transparent);
   outline-offset: 1px;
 }
 
-.markdown-editor .agent-thread-card__message-tool-icon {
+.agent-conversation-surface .agent-thread-card__message-tool-icon {
   display: block;
   width: 14px;
   height: 14px;
@@ -711,7 +805,7 @@
 
 /* 工具图标占用与首行一致的 18px 轨道。外层固定高度并自行居中，
  * 避免直接放置 14px SVG 时受多行参数/基线布局影响而上下偏移。 */
-.markdown-editor .agent-thread-card__message-tool-icon-wrap {
+.agent-conversation-surface .agent-thread-card__message-tool-icon-wrap {
   display: inline-flex;
   align-self: flex-start;
   align-items: center;
@@ -724,16 +818,16 @@
 /* 工具名视觉规格: __message-tool-name + __command-name 共享 ──
  * 颜色 (前景) + 字重 (500) + 横向布局 (auto) 同步,
  * command-name 额外保留 45% 宽度上限 + ellipsis 截断。 */
-.markdown-editor .agent-thread-card__message-tool-name,
-.markdown-editor .agent-thread-card__message-tool-concrete-name,
-.markdown-editor .agent-thread-card__command-name {
+.agent-conversation-surface .agent-thread-card__message-tool-name,
+.agent-conversation-surface .agent-thread-card__message-tool-concrete-name,
+.agent-conversation-surface .agent-thread-card__command-name {
   flex: 0 0 auto;
   color: var(--foreground);
   font-weight: 500;
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__message-tool-concrete-name {
+.agent-conversation-surface .agent-thread-card__message-tool-concrete-name {
   min-width: 0;
   max-width: 40%;
   overflow: hidden;
@@ -743,43 +837,43 @@
 
 /* tool-name 不需要水平截断, command-name 需要 ——
  * flex/color/weight 已在上一规则声明, 此处仅追加独有的截断属性 */
-.markdown-editor .agent-thread-card__command-name {
+.agent-conversation-surface .agent-thread-card__command-name {
   max-width: 45%;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.markdown-editor .agent-thread-card__command-operator {
+.agent-conversation-surface .agent-thread-card__command-operator {
   flex: 0 0 auto;
   margin-right: 4px;
   color: var(--muted-foreground);
 }
 
-.markdown-editor .agent-thread-card__message-tool-summary {
+.agent-conversation-surface .agent-thread-card__message-tool-summary {
   flex: 1 1 auto;
   min-width: 0;
   overflow: hidden;
   color: var(--muted-foreground);
-  font-family: var(--font-sans);
-  font-size: calc(var(--app-font-size, 15px) * 0.94);
+  font-family: var(--agent-message-font-family, var(--font-sans));
+  font-size: calc(var(--agent-message-base-font-size, 15px) * var(--agent-message-size-scale, 1));
   line-height: 18px;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.markdown-editor .agent-thread-card__message-tool-summary--link {
+.agent-conversation-surface .agent-thread-card__message-tool-summary--link {
   cursor: pointer;
   text-decoration: none;
 }
 
-.markdown-editor .agent-thread-card__message-tool-summary--link:hover {
+.agent-conversation-surface .agent-thread-card__message-tool-summary--link:hover {
   color: var(--foreground);
   text-decoration: underline;
   text-underline-offset: 2px;
 }
 
-.markdown-editor .agent-thread-card__message-tool-input {
+.agent-conversation-surface .agent-thread-card__message-tool-input {
   display: none;
   min-width: 0;
   max-width: 100%;
@@ -794,13 +888,13 @@
   overflow-wrap: anywhere;
 }
 
-.markdown-editor .agent-thread-card__message-tool-payload {
+.agent-conversation-surface .agent-thread-card__message-tool-payload {
   display: none;
   min-width: 0;
   max-width: 100%;
 }
 
-.markdown-editor .agent-thread-card__message-tool-payload-label {
+.agent-conversation-surface .agent-thread-card__message-tool-payload-label {
   display: block;
   padding-top: 4px;
   color: var(--muted-foreground);
@@ -808,19 +902,19 @@
   line-height: 16px;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__message-tool-payload {
   display: block;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__message-tool-input {
   display: block;
 }
 
-.markdown-editor .agent-thread-card__command-list {
+.agent-conversation-surface .agent-thread-card__command-list {
   flex: 0 0 auto;
   min-width: 0;
   max-width: 100%;
@@ -831,7 +925,7 @@
   /* 字体: 与工具描述信息统一为 sans (默认), 删除原先的 mono, 让命令列表跟其它工具描述在视觉上无法区分 */
 }
 
-.markdown-editor .agent-thread-card__command-preview {
+.agent-conversation-surface .agent-thread-card__command-preview {
   flex: 1 1 auto;
   min-width: 0;
   overflow: hidden;
@@ -840,18 +934,18 @@
   white-space: nowrap;
 }
 
-.markdown-editor .agent-thread-card__command-list--details {
+.agent-conversation-surface .agent-thread-card__command-list--details {
   display: none;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-list--details {
   width: 100%;
   display: block;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded {
   display: flex;
   flex-direction: column;
@@ -859,7 +953,7 @@
   overflow: visible;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-line {
   width: 100%;
@@ -867,10 +961,10 @@
   white-space: normal;
 }
 
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-name,
-.markdown-editor
+.agent-conversation-surface
   .agent-thread-card__message-tool-content--expanded
   .agent-thread-card__command-args-inline {
   overflow: visible;
@@ -879,14 +973,14 @@
   overflow-wrap: anywhere;
 }
 
-.markdown-editor .agent-thread-card__command-list--nested {
+.agent-conversation-surface .agent-thread-card__command-list--nested {
   max-width: calc(100% - 10px);
   margin-left: 10px;
   padding-left: 10px;
   border-left: 1px solid var(--border);
 }
 
-.markdown-editor .agent-thread-card__command-item {
+.agent-conversation-surface .agent-thread-card__command-item {
   min-width: 0;
   max-width: 100%;
   overflow: hidden;
@@ -895,7 +989,7 @@
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__command-line {
+.agent-conversation-surface .agent-thread-card__command-line {
   display: flex;
   align-items: baseline;
   flex: 1 1 auto;
@@ -908,14 +1002,14 @@
 
 /* command 输入信息视觉对齐工具描述 (tool-name / tool-summary), 字体一律 inherit (sans) */
 
-.markdown-editor .agent-thread-card__command-args-inline,
-.markdown-editor .agent-thread-card__command-env,
-.markdown-editor .agent-thread-card__command-more {
+.agent-conversation-surface .agent-thread-card__command-args-inline,
+.agent-conversation-surface .agent-thread-card__command-env,
+.agent-conversation-surface .agent-thread-card__command-more {
   color: var(--muted-foreground);
   line-height: 18px;
 }
 
-.markdown-editor .agent-thread-card__command-args-inline {
+.agent-conversation-surface .agent-thread-card__command-args-inline {
   flex: 1 1 auto;
   min-width: 0;
   margin-left: 4px;
@@ -924,11 +1018,11 @@
   white-space: nowrap;
 }
 
-.markdown-editor .agent-thread-card__command-env,
-.markdown-editor .agent-thread-card__command-more {
+.agent-conversation-surface .agent-thread-card__command-env,
+.agent-conversation-surface .agent-thread-card__command-more {
   flex: 0 0 auto;
 }
 
-.markdown-editor .agent-thread-card__command-env {
+.agent-conversation-surface .agent-thread-card__command-env {
   margin-right: 4px;
 }
diff --git a/app/flowix-web/styles/agent-thread-card/note-picker.css b/app/flowix-web/styles/agent-thread-card/note-picker.css
index aa94e3244..fca0d7043 100644
--- a/app/flowix-web/styles/agent-thread-card/note-picker.css
+++ b/app/flowix-web/styles/agent-thread-card/note-picker.css
@@ -1,194 +1,10 @@
-/* Note search menu and shared composer badge styles. */
-
-.agent-thread-card__composer-note-result {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  width: 100%;
-  min-width: 0;
-  min-height: 28px;
-  padding: 2px 8px;
-  border: 0;
-  border-radius: 8px;
-  background: transparent;
-  color: var(--agent-foreground);
-  cursor: pointer;
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1.2;
-  text-align: left;
-  box-sizing: border-box;
-  user-select: none;
-  transition: background-color 120ms ease;
-}
-
-.agent-thread-card__composer-note-result
-  + .agent-thread-card__composer-note-result {
-  margin-top: 2px;
-}
-
-.agent-thread-card__composer-note-result:hover {
-  background: var(--brand);
-  color: var(--primary-foreground);
-}
-
-.agent-thread-card__composer-note-empty {
-  padding: 6px 8px;
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-}
-
-/* Search field for indexed notebook notes. */
-.agent-thread-card__composer-note-search {
-  display: block;
-  width: 100%;
-  box-sizing: border-box;
-  padding: 6px 8px 8px;
-  margin: 4px 0 0;
-  border: 0;
-  border-radius: 0;
-  background: transparent;
-  color: var(--agent-foreground);
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1.2;
-  outline: none;
-}
-
-.agent-thread-card__composer-note-search::placeholder {
-  color: var(--muted-foreground);
-  opacity: 0.85;
-}
-.agent-thread-card__composer-note-search:focus::placeholder {
-  opacity: 0.6;
-}
-
-/* 列表容器 — 仅承担垂直 padding, 不画外框; 水平方向不加 padding,
- * 让 item 自身的 6px 8px padding 与菜单项对齐。容器自身
- * 设置 max-height + overflow-y, 当 hits 数量过多时弹窗内部可滚动,
- * 而外层容器 pop-in 动画 (fade + zoom-in) 不被裁切。
- *
- * 不再保留底部 4px padding ── 跟弹窗自身的 padding-bottom (4px) 重复,
- * 视觉上等于"列表底部"出现了 8px 空档, 与 DropdownMenuContent
- * (`py-1` = 4px 上下) 的紧凑节奏不一致。 改为 padding-top: 2px 即可,
- * 顶部留 2px 让第一项与上方分隔线之间有呼吸感。 */
-.agent-thread-card__composer-note-search-list {
-  display: block;
-  max-height: 320px;
-  overflow-y: auto;
-  margin-right: -0.25rem;
-  padding: 2px 0.25rem 0 0;
-}
-/* 容器内第一组 header 紧贴其上方分隔线, 但标签自身上下 padding 保持对称。 */
-.agent-thread-card__composer-note-search-list
-  > .agent-thread-card__composer-note-popover-header {
-  padding-top: 0.35rem;
-  margin-top: 4px;
-}
-.agent-thread-card__composer-note-search-list
-  > .agent-thread-card__composer-note-popover-header:first-child {
-  padding-top: 0.35rem;
-  margin-top: 0;
-}
-
-.markdown-editor .agent-thread-card__send {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: var(--atc-send-size);
-  height: var(--atc-send-size);
-  flex: 0 0 auto;
-  border: 0;
-  border-radius: 9999px;
-  background: var(--primary);
-  color: var(--primary-foreground);
-  cursor: pointer;
-}
-
-.markdown-editor .agent-thread-card__send:hover:not(:disabled) {
-  background: color-mix(in oklch, var(--primary) 88%, var(--foreground) 12%);
-}
-
-.markdown-editor .agent-thread-card__send-tooltip {
-  display: inline-flex;
-  flex: 0 0 auto;
-  line-height: 0;
-}
-
-.markdown-editor .agent-thread-card__send:disabled {
-  cursor: not-allowed;
-}
-
-/* 未输入内容时: 跟 inputbox 同步, 走 muted 色变, 不再依赖 opacity 半透明。
- * --stop 变体由 :not() 排除, 保持 warning 全亮 ── 停止按钮在 loading 期间
- * 仍需"亮"以传达"这是可点击的停止动作", 与 inputbox 中 isLoading 时强制
- * canSend=false 但视觉走 dim 的逻辑不同, 这里停止按钮是 dim→亮态的逆例。
- *
- * 图标色用 muted-foreground ── 与 muted 背景同色系, 形成'暗底 + 灰图标'
- * 的纯灰 dim 关系, 不再保留 primary 色相。 */
-.markdown-editor
-  .agent-thread-card__send:disabled:not(.agent-thread-card__send--stop) {
-  background: var(--muted);
-  color: var(--muted-foreground);
-}
-
-/* send 图标: 15×15 ── 跟主面板 inputbox 不必对齐, 卡片按钮更小一档
- * (--atc-send-size 28×28 vs 主面板 h-8 w-8 = 32×32), 图标按比例缩小
- * 维持视觉密度。stop 图标 (Phosphor 矩形 fill 满框) 在 15×15 下比例
- * 仍满, 不需要单独 size 分支。 */
-.markdown-editor .agent-thread-card__send-icon {
-  display: block;
-  width: 15px;
-  height: 15px;
-  flex: 0 0 auto;
-  color: currentColor;
-}
-
-.markdown-editor .agent-thread-card__send--stop {
-  background: var(--warning);
-  color: var(--floating-foreground);
-}
-
-.markdown-editor .agent-thread-card__send--running {
-  background: var(--muted);
-  color: var(--muted-foreground);
-  cursor: wait;
-}
-
-.markdown-editor .agent-thread-card__send--running.agent-thread-card__send--stop {
-  background: var(--warning);
-  color: var(--floating-foreground);
-  cursor: pointer;
-}
-
-.markdown-editor .agent-thread-card__send-spinner {
-  display: block;
-  width: 13px;
-  height: 13px;
-  border: 2px solid color-mix(in srgb, currentColor 28%, transparent);
-  border-top-color: currentColor;
-  border-radius: 50%;
-  animation: agent-thread-card-send-spinner 0.8s linear infinite;
-}
-
-@keyframes agent-thread-card-send-spinner {
-  to { transform: rotate(360deg); }
-}
-
-.markdown-editor
-  .agent-thread-card__send.agent-thread-card__send--stop:hover:not(:disabled) {
-  background: var(--warning);
-  filter: brightness(1.08);
-}
-
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__body,
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__body *,
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__message,
-.markdown-editor .agent-thread-card--fullscreen .agent-thread-card__message *,
-.markdown-editor
-  .agent-thread-card--fullscreen
-  .agent-thread-card__composer
-  .agent-thread-card__composer-input {
+.agent-conversation-surface.agent-thread-card--fullscreen .agent-thread-card__body,
+.agent-conversation-surface.agent-thread-card--fullscreen .agent-thread-card__body *,
+.agent-conversation-surface.agent-thread-card--fullscreen .agent-thread-card__message,
+.agent-conversation-surface.agent-thread-card--fullscreen .agent-thread-card__message *,
+.agent-conversation-surface.agent-thread-card--fullscreen
+  .agent-composer
+  .agent-composer__input {
   -webkit-user-select: text;
   user-select: text;
 }
@@ -206,19 +22,6 @@
   -webkit-app-region: no-drag;
 }
 
-/* Standalone conversation details use the same badge hover card as the
- * fullscreen Thread Card. Unlike the editor NodeView it does not need a
- * separately-positioned mount; this local wrapper is the anchor. */
-.agent-thread-card__badge-hover-wrapper {
-  position: relative;
-  display: inline-flex;
-  flex: 0 0 auto;
-  /* 与 mount 同源 ── drag region 内 wrapper 必须显式置 no-drag,否则 trigger
-   * 的 hover/click 全被 macOS 窗口拖拽吞掉。编辑器内嵌 NodeView 不在 drag
-   * region 里,这里是冗余但无副作用。 */
-  -webkit-app-region: no-drag;
-}
-
 /* 空间名称始终单行右对齐展示,超出时从右侧省略。 */
 .agent-thread-card__cwd-value {
   display: block;
@@ -301,23 +104,3 @@
     opacity: 0.7;
   }
 }
-
-.agent-thread-card__badge-hover-trigger {
-  position: absolute;
-  inset: 0;
-  z-index: 1;
-  display: block;
-  cursor: pointer;
-  background: transparent;
-  border-radius: inherit;
-  /* 与 wrapper 同源 ── drag region 内 trigger 必须显式置 no-drag 才能响应
-   * pointer 事件 (Radix HoverCard 的 onPointerEnter 才能 fire)。 */
-  -webkit-app-region: no-drag;
-}
-
-/* open 状态不加重背景 (避免与按钮灰色 hover 视觉冲突) ──
- * 仅在 trigger:hover / open 时让下层 badge 文字提亮。 */
-.agent-thread-card__badge-hover-trigger:hover ~ .agent-type-badge .agent-type-badge__name,
-.agent-thread-card__badge-hover-trigger[data-state="open"] ~ .agent-type-badge .agent-type-badge__name {
-  color: var(--foreground);
-}
diff --git a/app/flowix-web/styles/agent-thread-card/pi-model-picker.css b/app/flowix-web/styles/agent-thread-card/pi-model-picker.css
new file mode 100644
index 000000000..ab2333733
--- /dev/null
+++ b/app/flowix-web/styles/agent-thread-card/pi-model-picker.css
@@ -0,0 +1,125 @@
+.agent-thread-card__codex-settings-popover--pi-model-picker {
+  display: flex;
+  width: min(258px, calc(100vw - 16px));
+  max-height: min(360px, calc(100vh - 16px));
+  flex-direction: column;
+  overflow: hidden;
+  padding: 4px;
+}
+
+.pi-model-picker {
+  display: flex;
+  min-height: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+}
+
+.pi-model-picker__tabs {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 0;
+  padding: 4px 4px 0;
+}
+
+.pi-model-picker__tab {
+  min-width: 0;
+  flex: 0 0 auto;
+  padding: 6px 10px;
+  border: 0;
+  border-radius: 7px;
+  background: transparent;
+  color: var(--muted-foreground);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.25;
+  cursor: pointer;
+  transition: color 120ms ease;
+}
+
+.pi-model-picker__tab:hover,
+.pi-model-picker__tab:focus-visible {
+  color: var(--foreground);
+  outline: none;
+}
+
+.pi-model-picker__tab--active {
+  color: var(--foreground);
+  font-weight: 600;
+}
+
+.pi-model-picker__panel,
+.pi-model-picker__models {
+  min-height: 0;
+  flex: 1 1 auto;
+  overflow-y: auto;
+}
+
+.pi-model-picker__panel {
+  padding: 2px 0 0;
+}
+
+.pi-model-picker__models {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.pi-model-picker__provider {
+  min-width: 0;
+}
+
+.pi-model-picker__item {
+  min-height: 32px;
+  padding-inline: 10px;
+}
+
+.pi-model-picker__checkmark-placeholder {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  visibility: hidden;
+}
+
+.pi-model-picker__provider-icon {
+  width: 16px;
+  height: 16px;
+  flex: 0 0 auto;
+  border-radius: 4px;
+  object-fit: contain;
+}
+
+.pi-model-picker__multiplier,
+.pi-model-picker__provider-name {
+  flex: 0 0 auto;
+  color: var(--muted-foreground);
+  font-size: 12px;
+  line-height: 1.2;
+}
+
+.pi-model-picker__provider-name {
+  max-width: 96px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.pi-model-picker__provider-label {
+  padding: 7px 8px 4px;
+  color: var(--muted-foreground);
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.pi-model-picker__empty {
+  padding: 18px 12px;
+  color: var(--muted-foreground);
+  font-size: 13px;
+  line-height: 1.45;
+  text-align: center;
+}
+
+.pi-model-picker__reasoning {
+  flex: 0 0 auto;
+  padding: 0 4px 4px;
+}
diff --git a/app/flowix-web/styles/agent-thread-card/popovers.css b/app/flowix-web/styles/agent-thread-card/popovers.css
deleted file mode 100644
index ae11005b9..000000000
--- a/app/flowix-web/styles/agent-thread-card/popovers.css
+++ /dev/null
@@ -1,454 +0,0 @@
-
-/* 整体外框 ── position: fixed, 不写 max-height 也不写 overflow。
- *
- * 关键设计 ── overflow: visible (默认) ── 让内嵌子节点越界时不被裁
- * 剪 (例如 future inline submenu)。 max-height 不写 ── 由 JS 写到内层
- * .access-popover-scroll 上, 控制整个滚动区高度。
- *
- * 副作用 ── overflow visible 配合 box-shadow: shadow 仍按 outer 矩形
- * 渲染, 不会因 visible 失效; border-radius 8px 配合 children 圆角 ──
- * children 在 rounded 边缘内时被裁, 在外时不被裁。 */
-.agent-thread-card__access-popover {
-  position: fixed;
-  top: 0;
-  left: 0;
-  z-index: 105;
-  width: 208px;
-  border: 1px solid var(--border-popup);
-  border-radius: 0.75rem;
-  background: var(--card);
-  color: var(--agent-foreground);
-  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
-  padding: 0.25rem;
-}
-
-/* 滚动容器 ── 装整个可滚动内容: notebook section、folder section、
- * 末尾的"添加文件夹"按钮。 max-height 由 JS 动态计算 (= 可用空间)。
- * 内容超出时整体滚动, 不再有 sticky footer ── 按钮作为列表最后一项
- * 跟随内容滚动, 长列表下滚到底才能看到, 避免按钮在视觉上"凭空"出现
- * 在分隔很远的列表底部, 维持"按钮属于 folder 区域"的归属感。 */
-.agent-thread-card__access-popover-scroll {
-  overflow-y: auto;
-  margin-right: -0.25rem;
-  padding-right: 0.25rem;
-}
-
-/* "添加文件夹"按钮容器 ── 挂在 folder 列表末尾 (folderEntries 非空
- * 时), 或作为空态时唯一的引导 (folderEntries 空时)。 视觉上是 folder
- * section 的自然延伸, 不是独立的全局操作 ── 用户打开弹窗扫到 folder
- * 列表就能立刻看到"加一个"。
- *
- * 仅 margin-top: 4px 给一个柔和的呼吸空间, 不加 border-top 或 padding-
- * top, 让按钮与 folder row 视觉连续。 长列表下跟随内容滚动, 不再被钉
- * 在弹窗底部固定可见 ── 配合自定义 overlay scrollbar, Windows 下滚
- * 动条体验与 mention 下拉同源。
- *
- * 演变: 顶部 actions → 底部 sticky footer → folder 区域末尾
- *   - 顶部 actions: 用户先看到按钮再看列表, 视觉重音错位。
- *   - 底部 sticky footer: 列表滚动时按钮被钉在弹窗底部固定可见, 长列
- *     表下按钮与列表末尾分隔很远, 与 folder 语义割裂。
- *   - 现在: 紧贴 folder 列表末尾, notebook section 之前, 按钮与 folder
- *     section 视觉归属一致 ── 用户读完 folder 列表, 续上"加一个"再
- *     去翻 notebook, 路径自然。 */
-.agent-thread-card__access-popover-footer {
-  margin-top: 4px;
-}
-
-.agent-thread-card__access-popover[hidden] {
-  display: none;
-}
-
-/* ── 笔记搜索下拉弹窗 ────────────────────────
- * 独立挂在 document.body, 通过 JS 算 position: fixed 坐标 (top/left)
- * 锚定到 composerRoleIcon button 上方/下方。 视觉与文档标题栏 "…more"
- * 下拉菜单 (DropdownMenuContent) 同源 ── border / radius / box-shadow /
- * padding / animation 全部对齐, 让"产品图标点击的下拉"在不同入口呈现
- * 同一套容器视觉。
- *
- * 容器自身不写 max-height / overflow ── 由内层
- * `.agent-thread-card__composer-doc-search-list` 承担滚动, 让外层
- * 跟随内容自然高, 弹窗 pop-in 动画 (fade + zoom-in) 不被裁切。
- *
- * composer add popover 是一级菜单；悬停「添加笔记」后，
- * 笔记搜索弹窗在其右侧作为二级菜单。 */
-.agent-thread-card__composer-note-popover {
-  position: fixed;
-  top: 0;
-  left: 0;
-  z-index: 105;
-  width: 280px;
-  padding: 0.25rem;
-  border: 1px solid var(--border-popup);
-  border-radius: 0.75rem;
-  background: var(--card);
-  color: var(--agent-foreground);
-  /* 与消息输入框的模型 / 权限 / 空间设置弹窗使用同一套容器投影。 */
-  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
-  /* 弹窗入场动画 ── 与 DropdownMenuContent 的 animate-in fade-in-0
-   * zoom-in-95 同源: opacity 0→1 + scale 0.95→1, transform-origin
-   * top left (从 trigger 右上角弹出)。 */
-  opacity: 0;
-  transform: scale(0.95);
-  transform-origin: top left;
-  transition:
-    opacity 120ms ease,
-    transform 120ms ease;
-}
-
-.agent-thread-card__composer-add-popover {
-  position: fixed;
-  z-index: 105;
-  width: 168px;
-  padding: 0.25rem;
-  border: 1px solid var(--border-popup);
-  border-radius: 0.75rem;
-  background: var(--card);
-  color: var(--agent-foreground);
-  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
-}
-
-.agent-thread-card__composer-add-popover[hidden] { display: none; }
-
-.agent-thread-card__composer-add-item {
-  /* Layout, type, color and states come from the settings item above. */
-  gap: 8px;
-}
-
-.agent-thread-card__composer-add-chevron {
-  width: 15px;
-  height: 15px;
-  flex: 0 0 auto;
-  color: var(--muted-foreground);
-}
-
-.agent-thread-card__composer-note-popover:not([hidden]) {
-  opacity: 1;
-  transform: scale(1);
-}
-
-.agent-thread-card__composer-note-popover[hidden] {
-  display: none;
-}
-
-.agent-thread-card__composer-note-popover-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  /* 对齐笔记列表下拉窗里 DropdownMenuLabel 的 padding
-   * (`memo-list.tsx` 里 sortLabel / filterLabel 的
-   * `px-[0.375rem] pb-[0.35rem] pt-[0.15rem]`) ── 让两个下拉窗
-   * 的 group label 视觉间距一致。 */
-  padding: 0.35rem 0.375rem 0.35rem;
-}
-
-.agent-thread-card__composer-note-popover-title {
-  color: var(--muted-foreground);
-  /* 对齐 memo-list 的 sort label: text-xs font-normal leading-[1.2]
-   * ── 让笔记搜索弹窗的 group label 跟其它下拉窗
-   * 的 label 视觉密度一致。 */
-  font-size: 0.75rem;
-  font-weight: 400;
-  line-height: 1.2;
-}
-
-.agent-thread-card__composer-note-popover-meta {
-  color: var(--muted-foreground);
-  font-size: 0.7rem;
-  line-height: 1.2;
-  font-variant-numeric: tabular-nums;
-  opacity: 0.75;
-}
-
-.agent-thread-card__access-empty {
-  padding: 12px 8px;
-  text-align: center;
-  color: var(--muted-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9); /* text-xs */
-}
-
-.agent-thread-card__access-section-label {
-  padding: 0.35rem 0.375rem 0.35rem;
-  color: var(--muted-foreground);
-  font-size: 0.75rem;
-  line-height: 1.2;
-  letter-spacing: 0;
-}
-
-.agent-thread-card__access-row {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  min-height: 36px;
-  border-radius: 6px;
-  padding: 6px 8px;
-  transition: background-color 120ms ease;
-}
-
-/* row 整体不再 clickable ── 改用 cursor: default 让用户视觉上知道这块不是
- * 按钮。 真正的交互入口只有 checkbox / star / remove, 鼠标移上去会自然
- * 触发对应 button 的 hover 高亮 (CSS 已经处理)。 这里不再让整行 hover
- * 也染色, 避免"整行像 button 但点了没反应"的误判。 */
-.agent-thread-card__access-row:hover {
-  background: transparent;
-}
-
-.agent-thread-card__access-row--disabled {
-  cursor: default;
-  opacity: 0.6;
-}
-
-.agent-thread-card__access-row--disabled:hover {
-  background: transparent;
-}
-
-.agent-thread-card__access-avatar {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 24px;
-  height: 24px;
-  flex: 0 0 auto;
-  border-radius: 8px;
-  background: var(--muted);
-  color: var(--secondary-foreground);
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  font-weight: 600;
-}
-
-.agent-thread-card__access-avatar--icon {
-  background: var(--muted);
-  color: var(--secondary-foreground);
-}
-
-.agent-thread-card__access-avatar--icon svg {
-  display: block;
-  width: 72%;
-  height: 72%;
-  opacity: 0.9;
-}
-
-.agent-thread-card__access-row-icon {
-  width: 14px;
-  height: 14px;
-  color: var(--muted-foreground);
-}
-
-.agent-thread-card__access-name-wrap {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  min-width: 0;
-  flex: 1 1 auto;
-}
-
-.agent-thread-card__access-name {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-}
-
-.agent-thread-card__access-alert-icon {
-  width: 12px;
-  height: 12px;
-  flex: 0 0 auto;
-  color: var(--warning);
-}
-
-.agent-thread-card__access-default-badge {
-  display: inline-flex;
-  align-items: center;
-  height: 20px;
-  flex: 0 0 auto;
-  border-radius: 8px;
-  background: var(--accent);
-  color: var(--primary);
-  padding: 0 6px;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1;
-}
-
-.agent-thread-card__access-remove {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 22px;
-  height: 22px;
-  flex: 0 0 auto;
-  border: 0;
-  border-radius: 6px;
-  background: transparent;
-  color: var(--muted-foreground);
-  cursor: pointer;
-  opacity: 0;
-  padding: 0;
-}
-
-.agent-thread-card__access-row:hover .agent-thread-card__access-remove,
-.agent-thread-card__access-remove:focus {
-  opacity: 1;
-}
-
-.agent-thread-card__access-remove:hover {
-  color: var(--destructive);
-}
-
-.agent-thread-card__access-remove .agent-thread-card__trash-icon {
-  width: 14px;
-  height: 14px;
-}
-
-/* Workspace row 视觉 ── workspace entry (folder 或 notebook) 的 avatar 渲染
- * 原图标 + 左侧竖长条标记 (.access-workspace-mark) 作为 "主空间" 标记
- * (workspace 全局唯一), 不可点击。 非 workspace + 非 missing 的 entry
- * (folder 或 notebook) 整个 avatar 就是一个 button, 点击直接 setWorkspace ──
- * 不再 hover 出 star 按钮覆盖, 交互入口即图标本身。 */
-
-/* workspace avatar 不做特殊背景/颜色覆盖 ── 直接走基类 `.agent-thread-card__access-avatar`
- * (背景 `var(--muted)` + 颜色 `var(--secondary-foreground)`); folder 图标走
- * `.access-row-icon` 的 `var(--muted-foreground)`, notebook 图标走
- * `.access-avatar--icon` ── 与同 kind 的普通 entry 视觉重量完全一致, "workspace"
- * 这个角色标记只靠左侧竖长条体现, 不靠图标形状或颜色暗示。 avatar 设
- * position/overflow, 让长条能贴左边缘定位; 长条自带全圆角呈胶囊形。 (不再用
- * `--workspace svg` 统一 14px ── 那会误把 notebook 的 20px 图标也缩小;
- * folder 图标尺寸由 `.access-row-icon` 自带, notebook 由 `--icon svg` 自带。) */
-
-.agent-thread-card__access-avatar--workspace {
-  position: relative;
-  overflow: hidden;
-  /* 已是主空间的 avatar 虽不可点击 (没有 set-workspace 入口), 也用 hand cursor ──
-   * 与同列其它 avatar 视觉一致, 避免 "选中后变箭头" 的突兀感。 */
-  cursor: pointer;
-}
-
-/* workspace 侧边标记 ── 贴 avatar 左边缘的竖长条, 用 var(--primary) 实色
- * 填充, 作为 "主空间" 的标记。 3px 宽 × 12px 高, 上下居中 (top:50% +
- * translateY(-50%)); 仅右侧上下圆角 (border-radius:0 9999px 9999px 0, 受
- * 3px 宽限制实际半径 1.5px 呈右半圆), 左侧贴 avatar 边缘保持直角, 既能
- * 一眼识别又不喧宾夺主。 pointer-events:none 让标记不挡 avatar 上的点击。 */
-.agent-thread-card__access-workspace-mark {
-  position: absolute;
-  top: 50%;
-  left: 0;
-  width: 3px;
-  height: 12px;
-  transform: translateY(-50%);
-  background: var(--primary);
-  border-radius: 0 9999px 9999px 0;
-  pointer-events: none;
-}
-
-/* The notebook sidebar uses a right-aligned star, which is a different
- * affordance from the legacy avatar-side workspace mark above. Keep it in the
- * row's flex flow so it stays at the far right after the flexible name cell. */
-.agent-thread-card__access-workspace-star {
-  position: static;
-  flex: 0 0 auto;
-  color: var(--primary);
-}
-
-/* 可点击 avatar ── 非 workspace + 非 missing 的 entry (folder 或 notebook)
- * avatar 本身是 <button>, 点击 setWorkspace。 不再有 star 按钮覆盖层: hover
- * 只给一层 primary 薄底提示 "这个图标可点", 视觉重量与普通 avatar 一致。
- * button 重置 (border/padding) 走这里; 背景/颜色/尺寸/圆角都复用基类
- * `.agent-thread-card__access-avatar`。 */
-.agent-thread-card__access-avatar--set-workspace {
-  border: 0;
-  padding: 0;
-  cursor: pointer;
-  transition: background-color 120ms ease;
-}
-
-.agent-thread-card__access-avatar--set-workspace:hover {
-  background: color-mix(in oklch, var(--primary) 14%, var(--muted));
-}
-
-.agent-thread-card__access-checkbox {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 16px;
-  height: 16px;
-  flex: 0 0 auto;
-  border: 1px solid var(--muted-foreground);
-  border-radius: 4px;
-  background: transparent;
-  color: var(--primary-foreground);
-  cursor: pointer;
-  padding: 0;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1;
-}
-
-.agent-thread-card__access-checkbox--checked {
-  border-color: var(--primary);
-  background: var(--primary);
-}
-
-.agent-thread-card__access-checkbox-mark {
-  width: 11px;
-  height: 9px;
-  color: var(--primary-foreground);
-}
-
-.agent-thread-card__access-checkbox:disabled {
-  cursor: not-allowed;
-}
-
-.agent-thread-card__access-add {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  width: 100%;
-  min-width: 0;
-  margin: 0;
-  min-height: 28px;
-  padding: 2px 8px;
-  border: 0;
-  border-radius: 8px;
-  background: transparent;
-  color: var(--muted-foreground);
-  cursor: pointer;
-  font: inherit;
-  font-size: calc(var(--app-font-size, 15px) * 0.9);
-  line-height: 1;
-  text-align: left;
-  box-sizing: border-box;
-  user-select: none;
-  transition:
-    background-color 120ms ease,
-    color 120ms ease;
-}
-
-.agent-thread-card__access-add:hover {
-  background: var(--brand);
-  color: var(--primary-foreground);
-}
-
-.agent-thread-card__access-add-icon-wrap {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 24px;
-  height: 24px;
-  flex: 0 0 auto;
-  border-radius: 6px;
-  background: var(--muted);
-  color: var(--secondary-foreground);
-}
-
-.agent-thread-card__access-add-label {
-  flex: 1 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.agent-thread-card__access-add-icon {
-  width: 14px;
-  height: 14px;
-  flex: 0 0 auto;
-  color: currentColor;
-}
diff --git a/app/flowix-web/styles/checkbox.css b/app/flowix-web/styles/checkbox.css
new file mode 100644
index 000000000..7853240f2
--- /dev/null
+++ b/app/flowix-web/styles/checkbox.css
@@ -0,0 +1,71 @@
+/* Shared checkbox treatment for compact React controls and editor properties. */
+.flowix-hand-checkbox {
+  position: relative;
+  display: inline-flex;
+  width: 16px;
+  height: 16px;
+  flex: 0 0 16px;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--brand);
+  border-radius: 6px;
+  background: transparent;
+  cursor: pointer;
+  padding: 0;
+}
+
+.flowix-hand-checkbox-input {
+  position: relative;
+  display: inline-block;
+  width: 16px;
+  height: 16px;
+  flex: 0 0 16px;
+  appearance: none;
+  border: 1px solid var(--brand);
+  border-radius: 6px;
+  background: transparent;
+  cursor: pointer;
+  margin: 0;
+  padding: 0;
+}
+
+.flowix-hand-checkbox--checked,
+.flowix-hand-checkbox-input:checked {
+  border-color: var(--brand);
+  background: var(--brand);
+}
+
+:root[data-window-focused="false"] :is(.flowix-hand-checkbox, .flowix-hand-checkbox-input) {
+  border-color: color-mix(in srgb, var(--muted-foreground) 60%, transparent);
+}
+
+:root[data-window-focused="false"] :is(.flowix-hand-checkbox--checked, .flowix-hand-checkbox-input:checked) {
+  background: color-mix(in srgb, var(--muted-foreground) 60%, transparent);
+}
+
+.flowix-hand-checkbox__mark,
+.flowix-hand-checkbox-input:checked::after {
+  content: '';
+  display: block;
+  width: 11px;
+  height: 9px;
+  background: var(--primary-foreground);
+  mask: var(--flowix-hand-check-mask) center / contain no-repeat;
+}
+
+.flowix-hand-checkbox-input:checked::after {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+}
+
+.flowix-hand-checkbox-input:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+.flowix-hand-checkbox-input:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
diff --git a/app/flowix-web/styles/code-editor.css b/app/flowix-web/styles/code-editor.css
index 7414c5851..4ed5217e8 100644
--- a/app/flowix-web/styles/code-editor.css
+++ b/app/flowix-web/styles/code-editor.css
@@ -84,7 +84,7 @@
 
 .code-editor .source-document-date-row {
 	width: 100%;
-	max-width: var(--app-document-width, 680px);
+	max-width: var(--editor-document-width, 680px);
 	box-sizing: border-box;
 	margin: 0 auto;
 	padding: 0;
@@ -102,7 +102,7 @@
 .code-editor .source-document-title-row .memo-document-header {
 	/* Keep a centered content column while the outer CodeMirror header stays
 	 * full-width for its active surface. */
-	max-width: var(--app-document-width, 680px);
+	max-width: var(--editor-document-width, 680px);
 	padding: 0;
 }
 
@@ -118,7 +118,7 @@
 	user-select: text;
 	-webkit-user-select: text;
 	font-family: inherit;
-	font-size: calc(1.9rem * (var(--app-font-size, 15px) / 16px));
+	font-size: calc(1.9rem * (var(--editor-font-size, 16px) / 16px));
 	font-weight: 600;
 	line-height: 1.32;
 	white-space: pre-wrap;
diff --git a/app/flowix-web/styles/editor-agent-thread-card.css b/app/flowix-web/styles/editor-agent-thread-card.css
index cf20a1c14..57179903e 100644
--- a/app/flowix-web/styles/editor-agent-thread-card.css
+++ b/app/flowix-web/styles/editor-agent-thread-card.css
@@ -2,6 +2,6 @@
 @import './agent-thread-card/controls.css';
 @import './agent-thread-card/messages.css';
 @import './agent-thread-card/markdown.css';
-@import './agent-thread-card/composer.css';
-@import './agent-thread-card/popovers.css';
+@import './agent-thread-card/pi-model-picker.css';
+@import './agent-thread-card/background-terminals.css';
 @import './agent-thread-card/note-picker.css';
diff --git a/app/flowix-web/styles/editor-attachment-link.css b/app/flowix-web/styles/editor-attachment-link.css
index a5ed163b5..42c36bc9a 100644
--- a/app/flowix-web/styles/editor-attachment-link.css
+++ b/app/flowix-web/styles/editor-attachment-link.css
@@ -8,14 +8,14 @@
  */
 
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment {
   display: block;
   position: relative;
   width: 100%;
   aspect-ratio: 16 / 9;
   border-radius: 8px;
   border: 1px solid var(--border);
-  margin-bottom: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.32);
+  margin-bottom: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.32);
   overflow: hidden;
   background:
     linear-gradient(
@@ -25,22 +25,22 @@
     );
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment[data-video-align="left"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment[data-video-align="left"] {
   margin-left: 0;
   margin-right: auto;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment[data-video-align="right"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment[data-video-align="right"] {
   margin-left: auto;
   margin-right: 0;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment.is-selected {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment.is-selected {
   outline: 1px solid var(--brand);
   outline-offset: 0px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment video {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment video {
   display: block;
   width: 100%;
   height: 100%;
@@ -50,27 +50,27 @@
   transition: opacity 0.16s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment video.is-loaded {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment video.is-loaded {
   opacity: 1;
 }
 
 /* 原生 WebKit 视频控件自带的灰色面板降低不透明度，保留播放/音量控件
  * 的可读性，同时让底层视频画面更明显。不同 WebView 版本可能把背景
  * 绘制在 controls、enclosure 或 panel 层，因此一并覆盖。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment video::-webkit-media-controls,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment video::-webkit-media-controls-enclosure,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-video-attachment video::-webkit-media-controls-panel {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment video::-webkit-media-controls,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment video::-webkit-media-controls-enclosure,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-video-attachment video::-webkit-media-controls-panel {
   background-color: rgb(96 96 96 / 8%) !important;
   background-image: none !important;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment {
   display: inline;
   /* caret 视觉位置由 NodeView 内部的零宽空格 spacer 接管,
    * 见 nodes/file-attachment.ts createCard(). CSS 不再需要 margin-left. */
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card {
   /* inline 而非 inline-flex: 行盒允许在子节点之间换行,
    * 长文件名换行后,图标不会被孤立——它属于第一段文字所在行.
    * 注意: inline 不支持 gap, icon 与文件名的间距改由 icon 的 margin-right 提供. */
@@ -84,39 +84,32 @@
   vertical-align: baseline;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card:hover {
-  border-color: transparent;
-  background: transparent;
-  box-shadow: none;
-}
-
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card:hover,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card:hover * {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card:hover,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card:hover * {
   cursor: pointer;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card:hover .editor-file-attachment__name {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card:hover .editor-file-attachment__name {
   /* 与正文链接 hover 走同一条派生公式 (color-mix --document-link × white 20%),
    * 保证附件卡片的 "可点击" 视觉权重和正文 a:hover 完全一致. */
   color: color-mix(in oklch, var(--document-link), white 20%);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card:hover .editor-file-attachment__icon {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card:hover .editor-file-attachment__icon {
   color: color-mix(in oklch, var(--document-link), white 20%);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__icon {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__icon {
   display: inline-flex;
   align-items: center;
   vertical-align: middle;
-  margin-bottom: 3px;
   color: var(--document-link);
   flex-shrink: 0;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__card * {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__card * {
   -webkit-user-select: none;
   -moz-user-select: none;
   -ms-user-select: none;
@@ -125,7 +118,7 @@
   user-drag: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment__name {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment__name {
   /* 附件名称文字颜色统一到 --document-link token, 与正文 <a> 同源:
    * - 基色一致 → "这是链接" 的视觉信号强度统一
    * - hover 派生公式一致 → 鼠标悬停时和正文链接同步提亮
@@ -146,17 +139,17 @@
  * 走 color-mix(--document-link × transparent) 派生公式, 跨主题自动适配.
  * 浓度 10% 与 .editor-note-reference.is-selected 对齐, inline 卡片在文本
  * 行内不应铺大色块喧宾夺主, 视觉权重对齐 hover 反馈。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-file-attachment.is-selected .editor-file-attachment__card {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-file-attachment.is-selected .editor-file-attachment__card {
   background-color: color-mix(in oklch, var(--document-link) 10%, transparent);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment {
   display: block;
   position: relative;
   width: 100%;
   max-width: 100%;
   aspect-ratio: 16 / 9;
-  margin: 0 auto calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.32);
+  margin: 0 auto calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.32);
   overflow: hidden;
   border: 1px solid var(--border);
   border-radius: 8px;
@@ -170,12 +163,12 @@
   transition: border-color 0.12s ease, box-shadow 0.12s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment[data-image-align="left"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment[data-image-align="left"] {
   margin-left: 0;
   margin-right: auto;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment[data-image-align="right"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment[data-image-align="right"] {
   margin-left: auto;
   margin-right: 0;
 }
@@ -183,23 +176,23 @@
 /* macOS WebKit 的 Live Text 会在可选中的图片上识别并高亮图片内文字。
  * 图片仍由 ProseMirror 通过 click 进入 NodeSelection, 因此这里禁用的是
  * 原生文本选择, 不会影响点击选中、外框描边或 drag handle。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__image {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__image {
   -webkit-user-select: none;
   user-select: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-loaded {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-loaded {
   aspect-ratio: auto;
   background: transparent;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-error {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-error {
   border-style: dashed;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-selected,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.ProseMirror-selectednode {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-selected,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.ProseMirror-selectednode {
   outline: 1px solid var(--brand);
   outline-offset: 0;
 }
@@ -207,21 +200,21 @@
 /* 图片是 NodeSelection 时, ProseMirror 会同步一个原生 DOM 选区。
  * 编辑器统一的 ::selection 规则会因此在图片块上铺一层文字选区背景;
  * 图片只保留上面的 outline 作为选中反馈, 不改变普通文本的选区颜色。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-selected::selection,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-selected *::selection,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.ProseMirror-selectednode::selection,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.ProseMirror-selectednode *::selection {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-selected::selection,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-selected *::selection,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.ProseMirror-selectednode::selection,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.ProseMirror-selectednode *::selection {
   background: transparent !important;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-selected::-moz-selection,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-selected *::-moz-selection,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.ProseMirror-selectednode::-moz-selection,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.ProseMirror-selectednode *::-moz-selection {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-selected::-moz-selection,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-selected *::-moz-selection,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.ProseMirror-selectednode::-moz-selection,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.ProseMirror-selectednode *::-moz-selection {
   background: transparent !important;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__image {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__image {
   display: block;
   width: 100%;
   height: 100%;
@@ -233,17 +226,17 @@
   transition: opacity 0.16s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__image.is-loaded {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__image.is-loaded {
   height: auto;
   object-fit: contain;
   opacity: 1;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-error .editor-image-attachment__image {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-error .editor-image-attachment__image {
   opacity: 0;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__fallback {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__fallback {
   position: absolute;
   inset: 0;
   display: flex;
@@ -257,11 +250,11 @@
   pointer-events: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__fallback[hidden] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__fallback[hidden] {
   display: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__resize-handle {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__resize-handle {
   position: absolute;
   top: 50%;
   z-index: 2;
@@ -277,7 +270,7 @@
   transition: opacity 0.12s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__resize-handle::before {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__resize-handle::before {
   content: "";
   position: absolute;
   top: 9px;
@@ -289,20 +282,20 @@
   transform: translateX(-50%);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__resize-handle--left {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__resize-handle--left {
   left: 4px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__resize-handle--right {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__resize-handle--right {
   right: 4px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment:hover .editor-image-attachment__resize-handle,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment.is-resizing .editor-image-attachment__resize-handle {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment:hover .editor-image-attachment__resize-handle,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment.is-resizing .editor-image-attachment__resize-handle {
   opacity: 1;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-image-attachment__resize-handle:focus-visible {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-image-attachment__resize-handle:focus-visible {
   outline: none;
 }
 
@@ -311,7 +304,7 @@ body.is-image-resizing {
   user-select: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) a:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) a:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   /* 链接文字: 改用 --document-link token 化, 颜色随主题切换:
    * - light: 紫 (273) → 与品牌同色相
    * - dark:  亮紫 → 高对比可读
@@ -323,7 +316,7 @@ body.is-image-resizing {
   transition: color 0.12s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) a:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):hover {
+.markdown-editor .tiptap:not(.agent-composer__input-content) a:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):hover {
   /* hover 状态不单独维护 token, 直接基于 --document-link 与白色 20% 混色提亮:
    * - 单一来源: --document-link 决定基色, hover 由派生公式统一管理
    * - 跨主题一致: 各主题共享同一公式, 不会有"某主题的 hover 没设计"的问题 */
diff --git a/app/flowix-web/styles/editor-bubble-menus.css b/app/flowix-web/styles/editor-bubble-menus.css
index 8250a9566..9565dec7e 100644
--- a/app/flowix-web/styles/editor-bubble-menus.css
+++ b/app/flowix-web/styles/editor-bubble-menus.css
@@ -413,13 +413,6 @@
   height: 16px;
   flex: 0 0 auto;
   color: var(--primary);
-  animation: mention-note-header-spinner 1s linear infinite;
-}
-
-@keyframes mention-note-header-spinner {
-  to {
-    transform: rotate(360deg);
-  }
 }
 
 .mention-note-items-frame {
@@ -513,6 +506,10 @@
   font-weight: 500;
 }
 
+.mention-note-dropdown:not(.tag-mention-dropdown) .mention-note-title {
+  font-weight: 400;
+}
+
 /* Middle-column navigation submenus (tags / filter / sort / view) use the
  * shared mention label class, but their item text should remain regular. */
 .memo-navigation-submenu-item .mention-note-title {
diff --git a/app/flowix-web/styles/editor-code-block.css b/app/flowix-web/styles/editor-code-block.css
index 851dc57ff..108a98e7d 100644
--- a/app/flowix-web/styles/editor-code-block.css
+++ b/app/flowix-web/styles/editor-code-block.css
@@ -3,7 +3,7 @@
   z-index: 1;
   display: flex;
   flex-direction: column;
-  margin: 0 0 calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.32);
+  margin: 0 0 calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.32);
   padding: 0.4rem 0.8rem 1.2rem;
   padding-top: 0.4rem;
   padding-bottom: 0.5rem;
@@ -22,7 +22,7 @@
  * subtree as a plain pre > code so browser selections cannot terminate on
  * toolbar or preview DOM and be mapped to the end of the code block.
  */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .code-block-wrapper > .code-block-editor {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .code-block-wrapper > .code-block-editor {
   order: 2;
   z-index: 1;
   margin: 0;
@@ -39,14 +39,14 @@
   word-break: break-word;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .code-block-wrapper > .code-block-editor > .code-block-content {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .code-block-wrapper > .code-block-editor > .code-block-content {
   display: block;
   min-height: 1lh;
   white-space: inherit;
   word-break: inherit;
 }
 
-[data-theme="dark"] .markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .code-block-wrapper > .code-block-editor > .code-block-content,
+[data-theme="dark"] .markdown-editor .tiptap:not(.agent-composer__input-content) .code-block-wrapper > .code-block-editor > .code-block-content,
 [data-theme="dark"] .code-editor .cm-line {
   opacity: 0.68;
 }
@@ -84,7 +84,7 @@
 .code-block-language-search,
 .code-block-language-status,
 .code-block-language-dropdown-item {
-  font-family: var(--app-font-family, var(--font-sans));
+  font-family: var(--editor-font-family, var(--font-sans));
   font-feature-settings: normal;
   font-variant-numeric: normal;
 }
diff --git a/app/flowix-web/styles/editor-frontmatter.css b/app/flowix-web/styles/editor-frontmatter.css
index 9e60c9f34..cef690d86 100644
--- a/app/flowix-web/styles/editor-frontmatter.css
+++ b/app/flowix-web/styles/editor-frontmatter.css
@@ -40,7 +40,7 @@
   position: relative;
   width: 100%;
   color: var(--muted-foreground);
-  font-size: var(--app-font-size, 15px);
+  font-size: var(--editor-font-size, 16px);
   line-height: 1.25rem;
 }
 
@@ -138,7 +138,7 @@
   align-items: center;
   padding: 0.2rem 0 0.55rem;
   color: var(--foreground);
-  font-size: var(--app-font-size, 15px);
+  font-size: var(--editor-font-size, 16px);
   font-weight: 600;
   line-height: 1.4;
 }
@@ -327,8 +327,8 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
   background: var(--card);
   box-shadow: 0 8px 28px -6px rgb(0 0 0 / 24%);
   font-family: var(--font-sans);
-  font-size: var(--app-font-size, 15px);
-  line-height: var(--app-line-height, 1.8);
+  font-size: var(--editor-font-size, 16px);
+  line-height: var(--editor-line-height, 1.8);
   padding: 0.5rem 0.6rem;
 }
 
@@ -346,8 +346,8 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
   background: var(--card);
   box-shadow: 0 0 24px -3px rgb(0 0 0 / 24%);
   font-family: var(--font-sans);
-  font-size: var(--app-font-size, 15px);
-  line-height: var(--app-line-height, 1.8);
+  font-size: var(--editor-font-size, 16px);
+  line-height: var(--editor-line-height, 1.8);
   padding: 4px;
 }
 
@@ -404,7 +404,7 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
   color: var(--foreground);
   caret-color: var(--brand);
   font: inherit;
-  font-size: var(--app-font-size, 15px);
+  font-size: var(--editor-font-size, 16px);
   line-height: 1.5;
   padding: 0;
 }
@@ -585,7 +585,7 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
   color: var(--document-foreground);
   padding: 0.25rem 0.4rem;
   font: inherit;
-  font-size: var(--app-font-size, 15px);
+  font-size: var(--editor-font-size, 16px);
   line-height: 1.25;
   text-align: left;
   white-space: nowrap;
@@ -714,7 +714,7 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
 .markdown-editor .frontmatter-property__value-chip.tag-node .tag-node-prefix {
   /* Property chips wrap the prefix in a 92% outer chip, so restore the
    * editor's surrounding text size for the # glyph itself. */
-  font-size: var(--app-font-size, 15px);
+  font-size: var(--editor-font-size, 16px);
 }
 
 .frontmatter-property__edit-tags-input {
@@ -912,14 +912,6 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
   align-items: center;
 }
 
-.frontmatter-property__edit-checkbox {
-  width: 1rem;
-  height: 1rem;
-  margin: 0;
-  accent-color: var(--brand);
-  cursor: pointer;
-}
-
 .frontmatter-property__edit-type-row {
   position: relative;
   display: flex;
@@ -1123,19 +1115,6 @@ html.frontmatter-property--dragging .markdown-editor .frontmatter-property__disp
   align-items: baseline;
 }
 
-.markdown-editor .frontmatter-property__value-checkbox {
-  width: 14px;
-  height: 14px;
-  margin: 0;
-  accent-color: var(--brand);
-  cursor: pointer;
-}
-
-.markdown-editor .frontmatter-property__value-checkbox:disabled {
-  cursor: default;
-  opacity: 0.6;
-}
-
 .markdown-editor .frontmatter-property__key {
   min-width: 3.2rem;
   max-width: 9rem;
diff --git a/app/flowix-web/styles/editor-mermaid.css b/app/flowix-web/styles/editor-mermaid.css
index 7483480b2..17b0f7f38 100644
--- a/app/flowix-web/styles/editor-mermaid.css
+++ b/app/flowix-web/styles/editor-mermaid.css
@@ -41,14 +41,14 @@
   display: block;
   margin: 0 auto;
   color: var(--foreground);
-  font-family: var(--app-font-family), var(--font-sans), sans-serif !important;
+  font-family: var(--editor-font-family), var(--font-sans), sans-serif !important;
 }
 
 /* SVG 全部后代字体统一 ── mermaid 默认走 SF / Helvetica, 这里
  * 强制走应用字体, 让图表文字与编辑器正文视觉一致。 */
 .mermaid-surface svg,
 .mermaid-surface svg * {
-  font-family: var(--app-font-family), var(--font-sans), sans-serif !important;
+  font-family: var(--editor-font-family), var(--font-sans), sans-serif !important;
 }
 
 /* ── 文字 / label 字号 ─────────────────────────────────────────
diff --git a/app/flowix-web/styles/editor-note-reference.css b/app/flowix-web/styles/editor-note-reference.css
index b4a7237ef..33c9d1fb3 100644
--- a/app/flowix-web/styles/editor-note-reference.css
+++ b/app/flowix-web/styles/editor-note-reference.css
@@ -1,27 +1,27 @@
-/* Note Reference — 行内笔记卡片
+/* Note Reference — 行内笔记引用
  *
- * 形态: [📄 notebookName/title]  (单行, inline-flex, baseline 对齐周围文本)
+ * 形态: [📄 title] (inline 卡片, 长标题可换行)
  * 状态: 正常 / hover / 选中 / stale (链接失效)
  *
  * 完全对照 .editor-file-attachment 的结构 / 配色 token:
  *   - 透明底 (无边框/无阴影) — 跟文件附件卡片视觉权重一致
  *   - 颜色统一到 --document-link, 跨各主题自动适配
  *   - 选中态背景走 color-mix(--document-link 10%, transparent) 派生公式
- *   - hover 时 name 颜色与正文 a:hover 同步提亮
+ *   - hover 时标题和图标与正文 a:hover 同步提亮
  *
- * 与 file attachment 的差异: 名称用 `notebookName/title` 拼接, stale 状态
- * 整卡片降饱和 + 删除线 (链接失效语义)。
+ * 与 file attachment 的差异: 标题放在独立的 __title 中; stale 状态降低
+ * 整卡片透明度并追加状态文字。
  *
- * NoteReference 同时被文档编辑器和 Agent composer 使用。composer 被文档
- * 通用排版选择器排除，但仍需要这组组件专属的行内布局样式。 */
+ * 本样式表只服务正文编辑器。Agent composer 使用独立的扩展注册和
+ * Agent Conversation composer 样式，不依赖这里的笔记链接展示规则。 */
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-note-reference {
   display: inline;
 }
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card {
   /* inline 而非 inline-flex: 行盒允许在子节点之间换行,
-   * 长 notebook/title 换行后, 图标不会孤立. icon 与 __name 之间的
+   * 长标题换行后, 图标不会孤立. icon 与 __name 之间的
    * 间距由 __icon 的 margin-right 替代原 gap: 4px. */
   display: inline;
   padding: 2px;
@@ -34,55 +34,41 @@
   transition: background-color 0.15s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-note-reference__card:hover {
-  border-color: transparent;
-}
-
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover {
-  background: transparent;
-  box-shadow: none;
-}
-
 /* hover 时整组切到手型 cursor, 跟 __card 自身的 cursor: pointer 一致。
  * 默认态 __name 仍是 default (避免光标在文字上从箭头变 I 形后再变 pointer 的
  * 三态闪烁), 仅在用户主动 hover 卡片时统一发出"可点"的视觉信号。 */
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover,
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover * {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card:hover,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card:hover * {
   cursor: pointer;
 }
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover .editor-note-reference__name {
-  color: color-mix(in oklch, var(--document-link), white 20%);
-}
-
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__icon {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__icon {
   display: inline-flex;
   align-items: center;
   vertical-align: middle;
   margin-right: 1px;
-  margin-bottom: 3px;
   color: var(--document-link);
   flex-shrink: 0;
   transition: color 0.15s ease;
 }
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference,
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card,
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card * {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-note-reference,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card * {
   -webkit-user-drag: none;
   -moz-user-drag: none;
   -ms-user-drag: none;
   user-drag: none;
 }
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__name {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__name {
   /* 名称文字颜色与 file-attachment 同源: --document-link token
    * hover 派生公式一致 → 鼠标悬停时和文件附件卡片同步提亮
-   * 内部 __notebook / __title 由各自 className 覆写, 这里给兜底色 */
+   * 内部 __title 由自己的 className 覆写, 这里给兜底色 */
   color: var(--document-link);
   font-weight: 500;
   cursor: default;
-  /* 允许长 notebook/title 在任意字符处断行, 避免超出编辑器宽度;
+  /* 允许长标题在任意字符处断行, 避免超出编辑器宽度;
    * overflow-wrap 优先在词边界换行, 单"词"超长时强制断字. */
   white-space: normal;
   overflow-wrap: anywhere;
@@ -90,41 +76,16 @@
   transition: color 0.15s ease;
 }
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__notebook {
-  /* notebook 名 + chevron 跟笔记标题同色同源: --document-link
-   * 整条引用视为"一个语义单元", 视觉权重统一, 不再让前缀/分隔抢焦点
-   * font-weight 跟 __title 保持 500, 让用户一眼把整段当链接看 */
-  color: var(--document-link);
-  font-weight: 500;
-  transition: color 0.15s ease;
-}
-
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__chevron {
-  /* chevron 跟 notebook/title 完全同色, opacity 微微弱化仅做"路径层级"提示,
-   * 不再降色 — 颜色信号统一, 视觉上"notebook > title"是一条连贯的链接 */
-  display: inline-flex;
-  align-items: center;
-  color: var(--document-link);
-  opacity: 0.65;
-  vertical-align: -0.05em;
-  margin: 0 2px;
-  flex-shrink: 0;
-  transition: color 0.15s ease, opacity 0.15s ease;
-}
-
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__title {
-  /* 笔记标题: 跟原 file-attachment 的 __name 一致 — --document-link 强权重
-   * 让用户一眼锁定"这是哪个笔记", notebook 名只是定位上下文 */
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__title {
+  /* 笔记标题沿用 file-attachment 的 __name 配色 */
   color: var(--document-link);
   font-weight: 500;
 }
 
-/* hover 时整组同步提亮: notebook / chevron / title / icon 一并走
+/* hover 时标题和图标同步提亮
  * color-mix(--document-link, white 20%) 与 file-attachment 同源 */
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover .editor-note-reference__title,
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover .editor-note-reference__notebook,
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover .editor-note-reference__chevron,
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card:hover .editor-note-reference__icon {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card:hover .note-reference__title,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card:hover .note-reference__icon {
   color: color-mix(in oklch, var(--document-link), white 20%);
 }
 
@@ -132,7 +93,7 @@
  * 走 color-mix(--document-link × transparent) 派生公式, 跨主题自动适配。
  * 浓度 10% 与 .editor-file-attachment.is-selected 对齐, 选中态统一为"轻量"——
  * inline 卡片在文本行内不应铺大色块喧宾夺主, 视觉权重对齐 hover 反馈。 */
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference.is-selected .editor-note-reference__card {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-note-reference.is-selected .note-reference__card {
   background-color: color-mix(in oklch, var(--document-link) 10%, transparent);
 }
 
@@ -141,17 +102,16 @@
  * 视觉上: 整卡片 50% 透明度 + 末尾 "（已失效）" 标签, 跨主题一致.
  * 失效只表达视觉状态, 交互与正常卡片保持一致。 */
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__card[data-stale="true"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__card[data-stale="true"] {
   /* 整卡片半透明形成"明显已失效但仍占位"的视觉信号;
    * 透明度而非 color-mix 灰化是为了保留 --document-link 颜色信号,
    * 跨主题行为一致. */
   opacity: 0.5;
 }
 
-.markdown-editor :is(.tiptap:not(.agent-thread-card__composer-editor), .agent-thread-card__composer-input) .editor-note-reference__stale-mark {
-  /* 失效标签: 跟 __name 同色同源 (--document-link), 不加粗不加删除线
-   * (删除线仅作用于名字段, 失效标签本身是"状态注解"而非内容);
-   * 跟名字段间距与 chevron 风格保持一致, 视觉上是同一组里的尾巴. */
+.markdown-editor .tiptap:not(.agent-composer__input-content) .note-reference__stale-mark {
+  /* 失效标签: 跟 __name 同色同源 (--document-link), 不加粗;
+   * 跟名称字段保持间距, 作为状态注解显示. */
   color: var(--document-link);
   font-weight: 400;
   margin-left: 4px;
diff --git a/app/flowix-web/styles/editor.css b/app/flowix-web/styles/editor.css
index 0006a029c..4ea6b63d3 100644
--- a/app/flowix-web/styles/editor.css
+++ b/app/flowix-web/styles/editor.css
@@ -195,7 +195,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 
 .heading-outline-navigation__popover-item[data-level='1'] {
   padding-left: 0.5em;
-  font-size: var(--app-font-size, 15px);
+  font-size: var(--editor-font-size, 16px);
   font-weight: 600;
 }
 
@@ -278,7 +278,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 
 .memo-document-header {
   width: 100%;
-  max-width: var(--app-document-width, 680px);
+  max-width: var(--editor-document-width, 680px);
   margin: 0 auto;
   box-sizing: border-box;
   padding: 0 2.5rem;
@@ -289,7 +289,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   box-sizing: border-box;
   padding: 4px 0;
   color: var(--muted-foreground);
-  font-family: var(--app-font-family, var(--font-sans));
+  font-family: var(--editor-font-family, var(--font-sans));
   font-size: 0.75rem;
   line-height: 1.4;
   text-align: center;
@@ -368,8 +368,8 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   color: var(--document-foreground);
   caret-color: var(--brand);
   cursor: text;
-  font-family: var(--app-font-family, var(--font-sans));
-  font-size: calc(1.9rem * (var(--app-font-size, 15px) / 16px));
+  font-family: var(--editor-font-family, var(--font-sans));
+  font-size: calc(1.9rem * (var(--editor-font-size, 16px) / 16px));
   font-weight: 600;
   /* Match StableCaret's glyph-relative height in the body editor. */
   line-height: 1.15;
@@ -385,18 +385,18 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   pointer-events: none;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) {
   display: block;
   width: 100%;
   min-height: 100%;
-  max-width: var(--app-document-width, 680px);
+  max-width: var(--editor-document-width, 680px);
   margin: 0 auto;
   box-sizing: border-box;
   padding: 0 2.5rem 10rem 2.5rem;
   outline: none;
-  font-family: var(--app-font-family, var(--font-sans));
-  font-size: var(--app-font-size, 15px);
-  line-height: var(--app-line-height, 1.8);
+  font-family: var(--editor-font-family, var(--font-sans));
+  font-size: var(--editor-font-size, 16px);
+  line-height: var(--editor-line-height, 1.8);
   color: var(--document-foreground);
   background: transparent !important;
   caret-color: var(--brand);
@@ -404,68 +404,68 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   tab-size: 5;
 
   /* 让标题 rem 值跟随用户设定的基准字号 */
-  --editor-scale: calc(var(--app-font-size, 15px) / 16px);
+  --editor-scale: calc(var(--editor-font-size, 16px) / 16px);
 }
 
 /* Browser-column memo surfaces can be read-only while remaining selectable.
  * Make that contract explicit because contenteditable=false alone removes
  * keyboard focus behavior in WebKit. */
-.markdown-editor .ProseMirror[aria-readonly="true"] {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content)[aria-readonly="true"] {
   user-select: text;
   -webkit-user-select: text;
 }
 
-.markdown-editor:focus .ProseMirror {
+.markdown-editor:focus .ProseMirror:not(.agent-composer__input-content) {
   outline: none;
 }
 
 /* Native contenteditable carets use the full line box, so their height grows
  * with the user's line-spacing preference. StableCaret draws a glyph-height
  * caret instead; keep the native caret available during IME composition. */
-.markdown-editor .ProseMirror.has-stable-caret,
-.markdown-editor .ProseMirror.has-stable-caret :where(
-  *:not(.agent-thread-card__composer-editor):not(.agent-thread-card__composer-editor *)
+.markdown-editor .ProseMirror.has-document-stable-caret,
+.markdown-editor .ProseMirror.has-document-stable-caret :where(
+  *:not(.agent-composer__input-content):not(.agent-composer__input-content *)
 ) {
   caret-color: transparent !important;
 }
 
-.stable-editor-caret {
+.stable-editor-caret--document {
   position: fixed;
   z-index: 1000;
-  width: 2px;
+  width: var(--editor-caret-width, 2px);
   border-radius: 999px;
   background: var(--brand);
   pointer-events: none;
-  animation: stable-editor-caret-blink 1.05s steps(1, end) infinite;
+  animation: document-stable-editor-caret-blink 1.05s steps(1, end) infinite;
 }
 
-.stable-editor-caret[hidden] {
+.stable-editor-caret--document[hidden] {
   display: none;
 }
 
-@keyframes stable-editor-caret-blink {
+@keyframes document-stable-editor-caret-blink {
   0%, 52% { opacity: 1; }
   53%, 100% { opacity: 0; }
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) > :nth-child(1 of :not(.agent-thread-card, .frontmatter-property-node)):is(h1, h2, h3, h4, h5, h6, p) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) > :nth-child(1 of :not(.agent-thread-card, .frontmatter-property-node)):is(h1, h2, h3, h4, h5, h6, p) {
   padding-top: 0.8rem !important;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) > :nth-child(1 of :not(.agent-thread-card, .frontmatter-property-node)):not(h1, h2, h3, h4, h5, h6, p) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) > :nth-child(1 of :not(.agent-thread-card, .frontmatter-property-node)):not(h1, h2, h3, h4, h5, h6, p) {
   margin-top: 0.8rem !important;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) > .agent-thread-card:first-child:not(.agent-thread-card--fullscreen) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) > .agent-thread-card:first-child:not(.agent-thread-card--fullscreen) {
   margin-top: 0.8rem !important;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h1:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h2:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h3:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h4:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h5:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h6:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) h1:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h2:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h3:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h4:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h5:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h6:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
   margin: 0;
   padding-top: 1.5rem;
   padding-bottom: 0.5rem;
@@ -474,56 +474,56 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   white-space: pre-wrap;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h1:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) h1:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
   font-size: calc(1.9rem * var(--editor-scale));
   padding-top: 1rem;
   padding-bottom: calc(0.3rem * var(--editor-scale));
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h2:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) h2:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
   font-size: calc(1.5rem * var(--editor-scale));
   padding-top: 0.6rem;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h3:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) h3:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
   font-size: calc(1.2rem * var(--editor-scale));
   padding-top: 0.4rem;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h4:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) h4:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
   font-size: calc(1.05rem * var(--editor-scale));
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h4:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h5:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) h6:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) h4:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h5:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) h6:where(:not(.agent-thread-card__message, .agent-thread-card__message *, .table-reference-node, .table-reference-node *)) {
   padding-top: 0.3rem;
 }
 
-/* 行高相关公式统一走 var(--app-font-size) × var(--app-line-height):
- *  - 用 1rem 是错的 — 那是根 html 字号 (16px), 跟 --app-font-size (15px) 脱节,
+/* 行高相关公式统一走 var(--editor-font-size) × var(--editor-line-height):
+ *  - 用 1rem 是错的 — 那是根 html 字号 (16px), 跟 --editor-font-size (16px) 脱节,
  *    用户在 Preferences 改字号时 p 的下填充 / 空 p 的 min-height 不会跟着缩放。
  *  - 空 p / 非空 p 共享同一行高基线 (27px),
  *    段落下填充为行高的 0.25 倍 (6.75px)。 */
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   /* 0.25 行 box, 作为块间节奏 */
   margin: 0;
-  padding-bottom: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.25);
+  padding-bottom: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.25);
   white-space: pre-wrap;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):empty,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):has(> br.ProseMirror-trailingBreak:only-child) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):empty,
+.markdown-editor .tiptap:not(.agent-composer__input-content) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):has(> br.ProseMirror-trailingBreak:only-child) {
   /* 1 行 box, 与非空 <p> 等高 */
-  min-height: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8));
+  min-height: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8));
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):empty::before {
+.markdown-editor .tiptap:not(.agent-composer__input-content) > p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):empty::before {
   content: "\00a0";
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .terminal-inline-atom-caret-anchor {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .terminal-inline-atom-caret-anchor {
   display: inline;
 }
 
@@ -531,32 +531,32 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  * after contenteditable=false inline atoms in Safari/Chrome. The caret anchor
  * already provides the terminal landing point, so both DOM shapes should keep
  * the hack br visually hidden. */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .terminal-inline-atom-caret-anchor + br.ProseMirror-trailingBreak,
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .terminal-inline-atom-caret-anchor + img.ProseMirror-separator + br.ProseMirror-trailingBreak {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .terminal-inline-atom-caret-anchor + br.ProseMirror-trailingBreak,
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .terminal-inline-atom-caret-anchor + img.ProseMirror-separator + br.ProseMirror-trailingBreak {
   display: none;
 }
 
 /* Composer slash atoms use the same terminal caret decoration as note and
  * file-reference atoms. The composer is excluded from the document-editor
  * rule above, so keep the anchor visible here as an inline landing point. */
-.markdown-editor .agent-thread-card__composer-editor .terminal-inline-atom-caret-anchor {
+.markdown-editor .agent-composer__input-content .terminal-inline-atom-caret-anchor {
   display: inline;
 }
 
-.markdown-editor .agent-thread-card__composer-editor .terminal-inline-atom-caret-anchor + br.ProseMirror-trailingBreak,
-.markdown-editor .agent-thread-card__composer-editor .terminal-inline-atom-caret-anchor + img.ProseMirror-separator + br.ProseMirror-trailingBreak {
+.markdown-editor .agent-composer__input-content .terminal-inline-atom-caret-anchor + br.ProseMirror-trailingBreak,
+.markdown-editor .agent-composer__input-content .terminal-inline-atom-caret-anchor + img.ProseMirror-separator + br.ProseMirror-trailingBreak {
   display: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) strong:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) strong:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   font-weight: 700;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) em:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) em:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   font-style: italic;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) code {
+.markdown-editor .tiptap:not(.agent-composer__input-content) p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) code {
   border: 1px solid var(--border);
   border-radius: 0.4rem;
   padding: 0rem 0.3rem;
@@ -569,24 +569,24 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  * blocks own their styling and must not inherit these editor rules. The
  * boundary is message-level so the nested composer remains an editor. */
 .markdown-editor
-  .tiptap:not(.agent-thread-card__composer-editor)
+  .tiptap:not(.agent-composer__input-content)
   pre:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):not(.agent-thread-card__message-code-block) {
   background: var(--editor-block-bg);
   border: 1px solid var(--border);
   border-radius: 0.5rem;
   padding: 0.4rem 0.8rem 1.2rem;
   padding-top: 0;
-  margin: 0 0 calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.25);
+  margin: 0 0 calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.25);
   font-family: inherit;
   font-size: inherit;
   white-space: pre-wrap;
   word-break: break-word;
   overflow-x: visible;
-  line-height: var(--app-line-height, 1.8);
+  line-height: var(--editor-line-height, 1.8);
 }
 
 .markdown-editor
-  .tiptap:not(.agent-thread-card__composer-editor)
+  .tiptap:not(.agent-composer__input-content)
   pre:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):not(.agent-thread-card__message-code-block)
   code {
   padding: 0;
@@ -594,57 +594,57 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 }
 
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) blockquote:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) blockquote:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border-left: 0.1875rem solid var(--border);
-  margin: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.2) 0
-    calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.52);
+  margin: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.2) 0
+    calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.52);
   padding: 0 0 0 1rem;
   color: var(--document-foreground);
   font-style: normal;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ol:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) ol:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   margin: 0;
   padding-top: 0;
   padding-right: 0;
   padding-left: 1.5rem;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   margin: 0;
   padding: 0;
-  line-height: var(--app-line-height, 1.8);
+  line-height: var(--editor-line-height, 1.8);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul:where(:not([data-type="taskList"], .agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul:where(:not([data-type="taskList"], .agent-thread-card__message, .agent-thread-card__message *)) {
   padding-left: calc(1.5rem - 2px);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul:where(:not([data-type="taskList"], .agent-thread-card__message, .agent-thread-card__message *)) > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul:where(:not([data-type="taskList"], .agent-thread-card__message, .agent-thread-card__message *)) > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   padding-left: 2px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) td p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) th p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) td p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) th p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   margin-bottom: 0;
   padding-bottom: 0;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) li p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) li p:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   margin: 0;
-  padding-bottom: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.25);
+  padding-bottom: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.25);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   list-style-type: disc;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul ul:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul ul:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   list-style-type: circle;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) mark:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   background-color: var(--flowix-mark-bg, var(--flowix-default-mark-bg));
   color: var(--flowix-mark-fg, inherit);
   /* 文字色继承 document-foreground, 不另设 token */
@@ -652,83 +652,83 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   padding: 0.1rem 0.2rem;
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="red"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="red"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-red) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg]:not([data-flowix-bg]) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg]:not([data-flowix-bg]) {
   --flowix-mark-bg: transparent;
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="orange"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="orange"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-orange) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="yellow"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="yellow"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-yellow) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="green"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="green"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-green) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="cyan"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="cyan"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-cyan) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="blue"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="blue"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-blue) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="purple"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="purple"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-purple) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="pink"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="pink"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-pink) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-bg="gray"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-bg="gray"] {
   --flowix-mark-bg: color-mix(in oklch, var(--flowix-text-gray) 20%, transparent);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="red"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="red"] {
   --flowix-mark-fg: var(--flowix-text-red);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="orange"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="orange"] {
   --flowix-mark-fg: var(--flowix-text-orange);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="yellow"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="yellow"] {
   --flowix-mark-fg: var(--flowix-text-yellow);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="green"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="green"] {
   --flowix-mark-fg: var(--flowix-text-green);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="cyan"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="cyan"] {
   --flowix-mark-fg: var(--flowix-text-cyan);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="blue"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="blue"] {
   --flowix-mark-fg: var(--flowix-text-blue);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="purple"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="purple"] {
   --flowix-mark-fg: var(--flowix-text-purple);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="pink"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="pink"] {
   --flowix-mark-fg: var(--flowix-text-pink);
 }
 
-.markdown-editor .tiptap mark[data-flowix-fg="gray"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) mark[data-flowix-fg="gray"] {
   --flowix-mark-fg: var(--flowix-text-gray);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table):where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table):where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border-collapse: separate;
   border-spacing: 0;
   table-layout: fixed;
@@ -738,8 +738,8 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   border-radius: 8px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border: 1px solid var(--border);
   border-top: none;
   border-left: none;
@@ -750,60 +750,60 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   vertical-align: top;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   background: var(--table-header-fill);
   font-weight: 600;
   text-align: left;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child,
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child {
   border-left: 1px solid var(--border);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:first-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:first-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:first-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:first-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border-top: 1px solid var(--border);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:first-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:first-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:first-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child,
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:first-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child {
   border-top-left-radius: 8px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:first-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:first-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:first-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child,
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:first-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child {
   border-top-right-radius: 8px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:last-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:last-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:last-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child,
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:last-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):first-child {
   border-bottom-left-radius: 8px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:last-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table:not(.multidimensional-table) tr:last-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:last-child td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child,
+.markdown-editor .tiptap:not(.agent-composer__input-content) table:not(.multidimensional-table) tr:last-child th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)):last-child {
   border-bottom-right-radius: 8px;
 }
 
 /* ProseMirror adds .ProseMirror-hideselection for invisible selections such as
  * NodeSelection. Keep this override important because the editor-wide ::selection
  * rule below is also important and otherwise paints the browser range again. */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor).ProseMirror-hideselection :where(:not(.agent-thread-card__message, .agent-thread-card__message *))::selection {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content).ProseMirror-hideselection :where(:not(.agent-thread-card__message, .agent-thread-card__message *))::selection {
   background: transparent !important;
   color: inherit !important;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor).ProseMirror-hideselection :where(:not(.agent-thread-card__message, .agent-thread-card__message *))::-moz-selection {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content).ProseMirror-hideselection :where(:not(.agent-thread-card__message, .agent-thread-card__message *))::-moz-selection {
   background: transparent !important;
   color: inherit !important;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor).ProseMirror-hideselection {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content).ProseMirror-hideselection {
   caret-color: transparent;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .selectedCell::after {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .selectedCell::after {
   content: "";
   position: absolute;
   z-index: 2;
@@ -823,7 +823,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  *    取代原硬编码 #5262DC (hue 240 indigo) 在不同主题下脱节的问题.
  *  - hover: color-mix × white 25% 提亮派生, 与 .tiptap a:hover (white 20%)
  *    同公式一族, 各主题共享同一提亮曲线, 不会有"某主题的 hover 没设计". */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .column-resize-handle {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .column-resize-handle {
   position: absolute;
   right: -3px;
   top: 0;
@@ -835,12 +835,12 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   pointer-events: none;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table tr > td:last-child .column-resize-handle,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table tr > th:last-child .column-resize-handle {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table tr > td:last-child .column-resize-handle,
+.markdown-editor .tiptap:not(.agent-composer__input-content) table tr > th:last-child .column-resize-handle {
   right: 0;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .column-resize-handle::before {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .column-resize-handle::before {
   content: "";
   position: absolute;
   top: 0;
@@ -853,7 +853,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   transition: background-color 0.12s ease, opacity 0.12s ease;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .column-resize-handle:hover::before {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .column-resize-handle:hover::before {
   background: color-mix(in oklch, var(--brand), white 25%);
   opacity: 1;
 }
@@ -861,15 +861,15 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 /* prosemirror-tables 在鼠标进入列边检测区时给 editor 根节点加 `resize-cursor`。
  * 默认 cursor 规则来自 prosemirror-tables/style/tables.css, 但本项目未引入,
  * 故在此声明, 让整个编辑器区域(而非仅 2px handle)在靠近列边时都显示调整光标。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor).resize-cursor,
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor).ProseMirror.resize-cursor {
+.markdown-editor .tiptap:not(.agent-composer__input-content).resize-cursor,
+.markdown-editor .tiptap:not(.agent-composer__input-content).ProseMirror.resize-cursor {
   cursor: col-resize;
 }
 
 /* prosemirror-tables 在拖拽期间会给 cell 加 `column-resize-dragging` 装饰类;
  * 故意不样式化 — 列边高亮由 .column-resize-handle widget 自身形成连续线。 */
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .tableWrapper {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .tableWrapper {
   overflow-x: auto;
   overflow-y: visible;
   max-width: 100%;
@@ -880,8 +880,8 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 }
 
 /* relative 定位: 作为 column-resize-handle 的定位上下文 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) table th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) table td:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) table th:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   position: relative;
 }
 
@@ -937,22 +937,22 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   color: var(--foreground, #111827);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::marker {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::marker {
   color: var(--brand);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"]:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"]:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   list-style: none;
   padding-left: 0;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   display: flex;
   align-items: flex-start;
   gap: 8px;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label {
   flex-shrink: 0;
   /* margin-top: 3px 之前用来把 checkbox 视觉下移对齐文字 baseline,
    * 但在 flex 容器里 margin 会进 outer size, 给 <li> 多撑 3px。
@@ -960,7 +960,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
    * 但 transform 不参与 box model, 不会撑高 <li>。 */
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"] {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"] {
   width: 16px;
   height: 16px;
   cursor: pointer;
@@ -972,12 +972,12 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   transform: translateY(3px);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"]:checked {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"]:checked {
   background-color: transparent;
   border-color: var(--muted-foreground);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"]:checked::after {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"]:checked::after {
   content: '✓';
   position: absolute;
   top: 50%;
@@ -988,7 +988,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   font-weight: bold;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"]:checked::after {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > label input[type="checkbox"]:checked::after {
   content: '';
   width: 11px;
   height: 9px;
@@ -1000,13 +1000,13 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   mask: var(--flowix-hand-check-mask) center / contain no-repeat;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > div {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) > div {
   flex: 1;
 }
 
 /* text-decoration 是可继承属性，原本写在 > div 上会经由继承作用到嵌套的
  * 子 todo，所以选择器要限定到本级文本所在的 <p>，避免子级被划线。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))[data-checked="true"] > div > p {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))[data-checked="true"] > div > p {
   text-decoration: line-through;
   color: var(--muted-foreground);
 }
@@ -1014,38 +1014,38 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 /* todo 切到已完成态时, 标签底色跟着文本一起走灰, 视觉上"这条 todo 已经
  * 收尾, 标签也一并沉寂"。复用与文本同色的 muted-foreground, 保持和上方 li > p 的
  * color 一致 — 改 li 文字色时这里要同步。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))[data-checked="true"] > div > p .tag-node {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ul[data-type="taskList"] > li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))[data-checked="true"] > div > p .tag-node {
   background: var(--muted-foreground);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ol:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ol:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   list-style-type: decimal;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) ol li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::marker {
+.markdown-editor .tiptap:not(.agent-composer__input-content) ol li:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::marker {
   color: var(--brand);
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > p > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) li > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) li > p > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) > p > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) li > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) li > p > img:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border-radius: 8px;
   border: 1px solid var(--border);
   margin-bottom: 0;
   padding-bottom: 1rem;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) > p > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) li > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) li > p > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) > p > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) li > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .tiptap:not(.agent-composer__input-content) li > p > img.error:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border: 1px dashed var(--muted-foreground);
   border-radius: 8px;
   opacity: 1 !important;
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) .editor-link-selection-highlight:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-link-selection-highlight:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   /* 链接选区高亮: 与 .is-block-selected 同思路, 用 --brand 派生透明底,
    * 在各主题下都能融入品牌色相, 避免硬编码 indigo. */
   background: color-mix(in oklch, var(--brand) 18%, transparent);
@@ -1053,7 +1053,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 }
 
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) hr:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .tiptap:not(.agent-composer__input-content) hr:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border: none;
   border-top: 0.0625rem solid var(--border);
   margin: 0.4rem 0 0.8rem 0;
@@ -1073,8 +1073,8 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  *     不再加 outline / box-shadow 等外框 — hr 自身就是 1px 边, 高亮
  *     只在线本身, 视觉更克制。
  * 选择器特异性 (0,3,1) 高于全局 .ProseMirror-selectednode (0,1,0)。 */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) hr.is-block-selected:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) hr.ProseMirror-selectednode:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) hr.is-block-selected:where(:not(.agent-thread-card__message, .agent-thread-card__message *)),
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) hr.ProseMirror-selectednode:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   border-top-color: var(--brand);
 }
 
@@ -1102,7 +1102,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
    * character to the property tag icon while keeping it in the native text
    * run, so the caret is painted above the glyph instead of behind a layer. */
   display: inline;
-  font-family: var(--document-tag-icon-font-family, 'Flowix Tag Icon'), var(--app-font-family, var(--font-sans));
+  font-family: var(--document-tag-icon-font-family, 'Flowix Tag Icon'), var(--editor-font-family, var(--font-sans));
   font-size: inherit;
   line-height: var(--document-tag-prefix-line-height);
   font-weight: 400;
@@ -1371,7 +1371,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   color: color-mix(in oklch, var(--brand) 70%, var(--foreground));
 }
 
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor) p.is-empty:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::before {
+.markdown-editor .tiptap:not(.agent-composer__input-content) p.is-empty:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::before {
   content: attr(data-placeholder);
   color: var(--muted-foreground);
   opacity: 0.6;
@@ -1386,7 +1386,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  * 它仍被加上 is-empty + data-placeholder, 原规则会一直显示。
  * ProseMirror 在 view.dom 上自动维护 ProseMirror-focused 类, 这里未聚焦
  * 时直接把 ::before 的 content 置 none 即可, 不影响聚焦态。 */
-.markdown-editor .tiptap:not(.agent-thread-card__composer-editor):not(.ProseMirror-focused) p.is-empty:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::before {
+.markdown-editor .tiptap:not(.agent-composer__input-content):not(.ProseMirror-focused) p.is-empty:where(:not(.agent-thread-card__message, .agent-thread-card__message *))::before {
   content: none;
 }
 
@@ -1394,7 +1394,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  * 浮动菜单的 transform / delete 操作作用于哪一段。柔背景 + 圆角 + 左侧
  * 强调色, 视觉上读作"行指示", 不抢文本。
  * transition 只动画会被改动的属性, 避免影响光标闪烁等 ProseMirror 内部更新。 */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .is-block-selected {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .is-block-selected {
   position: relative;
   background-color: color-mix(in oklch, var(--brand) 6%, transparent);
   border-radius: 6px;
@@ -1402,11 +1402,11 @@ html[data-platform="mac"] .markdown-editor .editor-content {
     background-color 120ms ease-out;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .is-block-selected:hover {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .is-block-selected:hover {
   background-color: color-mix(in oklch, var(--brand) 10%, transparent);
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .flowix-block-drop-indicator {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .flowix-block-drop-indicator {
   display: block;
   height: 1px;
   margin: 0;
@@ -1415,7 +1415,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
   pointer-events: none;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .flowix-block-drag-source {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .flowix-block-drag-source {
   opacity: 0.3;
 }
 
@@ -1452,7 +1452,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
  * atom 节点被 NodeSelection 选中时): 用品牌色 outline 替代 Tiptap 默认
  * 的浅蓝 #8cf, 与 .is-block-selected 左侧描边、::selection 文字底色共
  * 同收口到 var(--brand), 各主题下视觉一致。 */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .ProseMirror-selectednode {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .ProseMirror-selectednode {
   /* outline: 2px solid var(--brand);
   outline-offset: 2px; */
   border-radius: 6px;
@@ -1464,7 +1464,7 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 /* 编辑器内文本选区: 比全局 ::selection 更显眼, 配合块高亮读作"这段
  * 文字被选中了"。限定在 .markdown-editor 内, 避免影响侧栏 / 输入
  * 框等非编辑区域的选区色。 */
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) :where(:not(.agent-thread-card__message, .agent-thread-card__message *))::selection {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) :where(:not(.agent-thread-card__message, .agent-thread-card__message *))::selection {
   background: color-mix(in oklch, var(--brand) 26%, transparent) !important;
   color: inherit !important;
 }
@@ -1675,13 +1675,13 @@ html[data-platform="mac"] .markdown-editor .editor-content {
 
 
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .search-result:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .search-result:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   background-color: rgba(255, 213, 79, 0.4);
   border-radius: 2px;
   padding: 0 1px;
 }
 
-.markdown-editor .ProseMirror:not(.agent-thread-card__composer-editor) .search-result-current:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
+.markdown-editor .ProseMirror:not(.agent-composer__input-content) .search-result-current:where(:not(.agent-thread-card__message, .agent-thread-card__message *)) {
   background-color: rgba(255, 193, 7, 0.6);
   outline: 1px solid rgba(255, 152, 0, 0.8);
 }
@@ -1691,3 +1691,183 @@ html.flowix-block-dragging * {
   user-select: none !important;
   -webkit-user-select: none !important;
 }
+
+/* Document-editor inline-atom hover actions. Composer actions use the shared
+ * Agent Conversation stylesheet and intentionally do not use these rules. */
+.markdown-editor .tiptap:not(.agent-composer__input-content) .agent-inline-atom__actions {
+  position: absolute;
+  z-index: 1;
+  top: 50%;
+  inset-inline-end: -0.3rem;
+  display: inline-flex;
+  align-items: center;
+  transform: translate(50%, -50%);
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.12s ease, visibility 0.12s ease;
+}
+
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-inline-atom:hover .agent-inline-atom__actions,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-inline-atom:focus-within .agent-inline-atom__actions,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .editor-inline-atom.is-selected .agent-inline-atom__actions {
+  opacity: 1;
+  visibility: visible;
+}
+
+.markdown-editor .tiptap:not(.agent-composer__input-content) .agent-inline-atom__action {
+  display: inline-flex;
+  width: 1.35rem;
+  height: 1.35rem;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--input-bg, var(--document-bg));
+  color: var(--muted-foreground);
+  cursor: pointer;
+}
+
+.markdown-editor .tiptap:not(.agent-composer__input-content) .agent-inline-atom__action:hover,
+.markdown-editor .tiptap:not(.agent-composer__input-content) .agent-inline-atom__action:focus-visible {
+  color: var(--foreground);
+  outline: none;
+}
+
+.markdown-editor .tiptap:not(.agent-composer__input-content) .agent-inline-atom__action > svg {
+  width: 0.8rem;
+  height: 0.8rem;
+}
+
+/* Image previews are portaled to body so the composer scroll region cannot clip them. */
+.agent-composer__image-preview-popover {
+  position: fixed;
+  z-index: 1000;
+  display: flex;
+  max-width: calc(100vw - 1rem);
+  max-height: calc(100vh - 1rem);
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  padding: 0.5rem;
+  border: 1px solid var(--border-popup, var(--border, #444));
+  border-radius: 0.75rem;
+  background: var(--input-bg, var(--document-bg, #1c1c1c));
+  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
+  pointer-events: auto;
+}
+
+.agent-composer__image-preview-popover[hidden] {
+  display: none;
+}
+
+.agent-composer__image-preview-popover > img {
+  display: block;
+  width: auto;
+  height: auto;
+  max-width: min(18rem, calc(100vw - 1.7rem));
+  max-height: min(14rem, calc(100vh - 1.7rem));
+  border-radius: 0.4rem;
+  object-fit: contain;
+}
+
+.agent-composer__note-reference-preview {
+  position: fixed;
+  z-index: 1000;
+  display: flex;
+  width: min(18rem, calc(100vw - 1rem));
+  max-height: calc(100vh - 1rem);
+  flex-direction: column;
+  gap: 0.65rem;
+  overflow: hidden;
+  padding: 0.5rem;
+  border: 1px solid var(--border-popup, var(--border, #444));
+  border-radius: 0.75rem;
+  background: var(--input-bg, var(--document-bg, #1c1c1c));
+  box-shadow: 0 4px 24px -3px rgb(0 0 0 / 24%);
+  color: var(--foreground);
+  pointer-events: auto;
+}
+
+.agent-composer__note-reference-preview[hidden],
+.agent-composer__note-reference-preview-image[hidden] {
+  display: none;
+}
+
+.agent-composer__note-reference-preview-image {
+  display: block;
+  width: 100%;
+  max-height: min(10rem, 32vh);
+  border-radius: 0.45rem;
+  object-fit: cover;
+}
+
+.agent-composer__note-reference-preview-body {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.agent-composer__note-reference-preview-title-row {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.agent-composer__note-reference-preview-title {
+  display: -webkit-box;
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--foreground);
+  font-size: 0.875rem;
+  font-weight: 600;
+  line-height: 1.3;
+  overflow-wrap: anywhere;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.agent-composer__note-reference-preview-text {
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--muted-foreground);
+  font-size: 0.78rem;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 4;
+}
+
+.agent-composer__note-reference-preview-open {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  border-radius: 0.2rem;
+  background: transparent;
+  color: var(--brand);
+  font: inherit;
+  font-size: 0.8rem;
+  cursor: pointer;
+}
+
+.agent-composer__note-reference-preview-open:hover:not(:disabled) {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.agent-composer__note-reference-preview-open:focus-visible {
+  outline: 2px solid var(--brand);
+  outline-offset: 2px;
+}
+
+.agent-composer__note-reference-preview-open:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
diff --git a/app/flowix-web/styles/fonts.css b/app/flowix-web/styles/fonts.css
index 74dea331b..46d6a8949 100644
--- a/app/flowix-web/styles/fonts.css
+++ b/app/flowix-web/styles/fonts.css
@@ -41,7 +41,7 @@
 
 .flowix-tag-icon {
 	display: inline-block;
-	font-family: 'Flowix Tag Icon', var(--app-font-family, var(--font-sans));
+	font-family: 'Flowix Tag Icon', var(--editor-font-family, var(--font-sans));
 	font-size: 1em;
 	font-style: normal;
 	font-weight: 400;
diff --git a/app/flowix-web/styles/index.css b/app/flowix-web/styles/index.css
index f0ed42e82..5c6b035b7 100644
--- a/app/flowix-web/styles/index.css
+++ b/app/flowix-web/styles/index.css
@@ -1,4 +1,5 @@
 @import './fonts.css';
+@import './checkbox.css';
 
 /* Tiptap 编辑器相关样式集中收口:
  *   - editor.css            容器/排版基础 (ProseMirror 排版 / 基础 markdown 节点)
@@ -15,6 +16,9 @@
 @import './editor-frontmatter.css';
 @import './multidimensional-table.css';
 @import './editor-agent-thread-card.css';
+/* Shared composer styles used by standalone and embedded Agent conversations. */
+@import './agent-conversation/titlebar.css';
+@import './agent-conversation/composer.css';
 @import './editor-note-reference.css';
 @import './editor-code-block.css';
 @import './editor-mermaid.css';
@@ -50,6 +54,13 @@
 
 @import "shadcn/tailwind.css";
 
+/* Keep drag gestures from selecting page text while a shared drop session is active. */
+html.flowix-drag-drop-active,
+html.flowix-drag-drop-active * {
+	-webkit-user-select: none !important;
+	user-select: none !important;
+}
+
 /* shadcn/ui variable convention: --[role]-[property]
  * Roles: background, foreground, primary, secondary, muted, accent, border, ring */
 
@@ -57,6 +68,24 @@
 @tailwind components;
 @tailwind utilities;
 
+/* Shared rotation for loading indicators. Keep dimensions and colors local to
+ * each spinner; callers may override the duration with --flowix-spin-duration. */
+.flowix-spin {
+	animation: flowix-spin var(--flowix-spin-duration, 1s) linear infinite;
+}
+
+@keyframes flowix-spin {
+	to {
+		transform: rotate(360deg);
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.flowix-spin {
+		animation: none;
+	}
+}
+
 /* Browser column 的激活 tab 顶部指示线从中心向两侧展开，避免切换时
  * 线条瞬间出现。 */
 .browser-column-active-tab-indicator {
@@ -391,13 +420,7 @@
 	border: 1.5px solid color-mix(in srgb, var(--brand) 34%, transparent);
 	border-top-color: var(--brand);
 	border-radius: 999px;
-	animation: notebook-file-tree-move-spin 700ms linear infinite;
-}
-
-@keyframes notebook-file-tree-move-spin {
-	to {
-		transform: rotate(360deg);
-	}
+	--flowix-spin-duration: 700ms;
 }
 
 @keyframes notebook-file-tree-move-success {
@@ -510,9 +533,9 @@
 	mask: var(--flowix-hand-check-mask) center / contain no-repeat;
 }
 
-@layer base {
+	@layer base {
 	/* 颜色 token 全部由 css/theme/*.css 提供, 这里只放不参与主题的非颜色 token
-	 * (radius / font-* / app-font-*)。
+	 * (radius / font-* / editor-font-*)。
 	 *
 	 * 注意: 绝不能在这里定义 --destructive / --warning 等会被 [data-theme="..."]
 	 * 覆盖的色 token —— 因为 Vite/esbuild 的 CSS 压缩会剥掉 @layer 包装,
@@ -524,18 +547,14 @@
 		--font-heading: var(--font-sans);
 		--font-sans: 'Flowix Small Emoji', 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif;
 		--font-nav: 'SF Mono';
+		--font-size: 15px;
+		--font-line-height: 1.8;
 
-		/* User-configurable typography (Preferences → Format).
-		 * Tiptap 正文及其嵌入内容消费 --app-font-family;
-		 * Agent 对话和产品 UI 继续使用 --font-sans。字号/行高也被部分
-		 * 编辑器和 Thread Card 尺寸规则消费。
-		 * 不再写到 body / html, 避免影响 MemoList、Agent 面板等其它
-		 * UI 文本。默认值需与 constants.ts 的 DEFAULT_USER_SETTINGS
-		 * 保持同步。由 useApplyFontSettings 运行时覆盖。 */
-		--app-font-family: var(--font-sans);
-		--app-font-size: 15px;
-		--app-line-height: 1.8;
-		--app-document-width: 700px;
+		/* Preferences → Format controls editor content only. */
+		--editor-font-family: var(--font-sans);
+		--editor-font-size: 16px;
+		--editor-line-height: 1.8;
+		--editor-document-width: 700px;
 
 		/* Shared code typography for rendered code blocks and CodeMirror. */
 		--code-text-font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'DengXian', '等线', 'Microsoft YaHei', '微软雅黑', monospace;
@@ -552,6 +571,10 @@
 		--agent-font: 'Flowix Small Emoji', 'Anonymous Pro', 'PingFang SC', 'Microsoft YaHei', 'Inter', -apple-system, monospace;
 	}
 
+	html {
+		font-size: 16px;
+	}
+
 	/* Markdown viewer & Tiptap 编辑器: 跟随主题背景色,
 	 * 否则 dark/rock 下会出现白底与背景不同步。 */
 	.markdown-body {
@@ -560,7 +583,7 @@
 		--bgColor-muted: var(--muted);
 	}
 
-	.tiptap {
+	.tiptap:not(.agent-composer__input-content) {
 		background: var(--background) !important;
 		overflow: hidden;
 	}
@@ -747,22 +770,14 @@
 
 	.flowix-notebook-selector-popup {
 		--flowix-popover-enter-y: 4px;
-		--flowix-popover-enter-scale: 0.84;
+		--flowix-popover-enter-scale: 1;
 		--flowix-popover-enter-duration: 180ms;
 		--flowix-popover-exit-y: 4px;
-		--flowix-popover-exit-scale: 0.96;
+		--flowix-popover-exit-scale: 1;
 		--flowix-popover-exit-duration: 140ms;
 		transform-origin: bottom left !important;
 	}
 
-	.flowix-notebook-selector-popup.flowix-notebook-list-screen {
-		--flowix-popover-enter-y: 0px;
-		--flowix-popover-enter-scale: 1;
-		--flowix-popover-exit-y: 0px;
-		--flowix-popover-exit-scale: 1;
-		transform-origin: center center !important;
-	}
-
 	/* 左侧当前笔记本卡片的弹窗向下展开；状态栏入口仍保留向上弹出的动效。 */
 	.flowix-notebook-selector-popup--bottom {
 		--flowix-popover-enter-y: -4px;
@@ -1116,29 +1131,3 @@
     border-color: color-mix(in oklch, var(--brand) 50%, transparent);
   }
 }
-/* Match the editor task checkbox in the file tree display popover. */
-.notebook-file-tree__display-checkbox {
-  position: relative;
-  display: inline-flex;
-  width: 16px;
-  height: 16px;
-  flex: 0 0 16px;
-  align-items: center;
-  justify-content: center;
-  border: 1px solid var(--brand);
-  border-radius: 6px;
-  background: transparent;
-  cursor: pointer;
-  padding: 0;
-}
-
-.notebook-file-tree__display-checkbox--checked {
-  border-color: var(--muted-foreground);
-}
-
-.notebook-file-tree__display-checkbox-mark {
-  width: 11px;
-  height: 9px;
-  background: var(--muted-foreground);
-  mask: var(--flowix-hand-check-mask) center / contain no-repeat;
-}
diff --git a/app/flowix-web/styles/multidimensional-table.css b/app/flowix-web/styles/multidimensional-table.css
index eaf5f921e..035223e58 100644
--- a/app/flowix-web/styles/multidimensional-table.css
+++ b/app/flowix-web/styles/multidimensional-table.css
@@ -7,12 +7,17 @@
   container-type: inline-size;
 }
 
-.agent-thread-card__composer-note-search.multidimensional-table__preset-search {
+.agent-composer__note-search.multidimensional-table__preset-search {
   padding-top: 3px;
   padding-bottom: 4px;
   margin-top: 2px;
 }
 
+.multidimensional-table__view-nav[data-title-visible="false"] .multidimensional-table__view-title,
+.multidimensional-table__view-nav[data-title-visible="false"] .multidimensional-table__view-nav-separator {
+  display: none;
+}
+
 @container multidimensional-table (max-width: 499px) {
   .multidimensional-table__view-nav .multidimensional-table__view-title,
   .multidimensional-table__view-nav-separator {
@@ -204,21 +209,42 @@ html[data-platform="mac"] .multidimensional-table__scrollbar--bottom-clearance.o
   background-color: color-mix(in srgb, var(--card) 50%, var(--hover-bg) 50%);
 }
 
+.multidimensional-table__kanban-drop-target {
+  background-color: color-mix(in srgb, var(--brand) 8%, var(--background));
+  transition: background-color 120ms ease;
+}
+
+.multidimensional-table__kanban-lane[data-kanban-unassigned='true'].multidimensional-table__kanban-drop-target {
+  background-color: color-mix(in srgb, var(--brand) 8%, var(--background));
+}
+
 .multidimensional-table__calendar-card,
 .multidimensional-table__calendar-card * {
   -webkit-user-select: none;
   user-select: none;
 }
 
+.multidimensional-table__calendar-card {
+  cursor: pointer;
+  background-color: var(--multidimensional-table-calendar-card-background, color-mix(in oklch, var(--brand) 10%, var(--background)));
+  transition: background-color 120ms ease;
+}
+
+.multidimensional-table__calendar-card:hover {
+  background-color: var(--multidimensional-table-calendar-card-hover-background, color-mix(in oklch, var(--brand) 28%, color-mix(in oklch, var(--foreground) 16%, var(--background))));
+}
+
 .multidimensional-table__calendar {
   --multidimensional-table-calendar-weekend-bg: color-mix(in srgb, var(--foreground) 1.6%, var(--background));
   --multidimensional-table-calendar-today-bg: color-mix(in srgb, var(--brand) 8%, var(--background));
+  --multidimensional-table-calendar-drop-bg: color-mix(in srgb, var(--brand) 16%, var(--background));
   --multidimensional-table-calendar-active-bg: color-mix(in srgb, var(--foreground) 3.2%, var(--background));
   box-sizing: border-box;
 }
 
 .multidimensional-table__calendar-drop-target {
-  box-shadow: inset 0 0 0 2px var(--brand);
+  background-color: var(--multidimensional-table-calendar-drop-bg);
+  transition: background-color 120ms ease;
 }
 
 .multidimensional-table__cell-content {
@@ -322,12 +348,51 @@ button.multidimensional-table__primary-title--placeholder {
   outline: none;
 }
 
+.calendar-note-create-popover .multidimensional-table__primary-title-input {
+  max-height: none;
+  font-size: var(--font-size, 16px);
+  line-height: var(--font-line-height, 1.8);
+}
+
+.calendar-note-create-fields {
+  font-size: var(--font-size, 16px);
+  line-height: var(--font-line-height, 1.8);
+}
+
+.calendar-note-create-fields :is(input, textarea, button, [role='combobox']) {
+  color: var(--foreground);
+  font-size: inherit;
+  line-height: inherit;
+}
+
+.calendar-note-create-fields .text-sm {
+  font-size: inherit;
+  line-height: inherit;
+}
+
+.calendar-note-create-field-input {
+  border-radius: 0.5rem;
+  transition: background-color 150ms ease;
+}
+
+.calendar-note-create-field-input:hover {
+  background-color: var(--hover-bg);
+}
+
 .multidimensional-table__primary-editor-actions {
   display: flex;
   justify-content: flex-end;
   gap: 0.5rem;
 }
 
+.multidimensional-table__icon-value {
+  filter: brightness(0.88) saturate(1.08);
+}
+
+.multidimensional-table__icon-placeholder {
+  border-color: color-mix(in oklch, var(--border) 80%, var(--foreground));
+}
+
 .multidimensional-table__note-picker-option {
   display: flex;
   width: 100%;
diff --git a/app/flowix-web/styles/overlay-scrollbar.css b/app/flowix-web/styles/overlay-scrollbar.css
index 6672e58de..5f95faefd 100644
--- a/app/flowix-web/styles/overlay-scrollbar.css
+++ b/app/flowix-web/styles/overlay-scrollbar.css
@@ -64,28 +64,37 @@ html[data-platform="mac"] *::-webkit-scrollbar-thumb:active {
 	background: var(--muted-foreground);
 }
 
-/* Select popups keep their scrollbar track space, but only paint the thumb
- * while the list is actively scrolling. */
-[data-flowix-surface="select"]:not([data-scrolling="true"]) {
+/* Select and composer popups keep their scrollbar track space, but only paint
+ * the thumb while the list is actively scrolling. */
+[data-flowix-surface="select"]:not([data-scrolling="true"]),
+.agent-composer-slash-menu:not([data-scrolling="true"]) {
 	scrollbar-color: transparent transparent;
 }
 
-[data-flowix-surface="select"][data-scrolling="true"] {
+[data-flowix-surface="select"][data-scrolling="true"],
+.agent-composer-slash-menu[data-scrolling="true"] {
 	scrollbar-color: color-mix(in oklch, var(--muted-foreground) 30%, transparent) transparent;
 }
 
-[data-flowix-surface="select"]:not([data-scrolling="true"])::-webkit-scrollbar-thumb {
+[data-flowix-surface="select"]:not([data-scrolling="true"])::-webkit-scrollbar-thumb,
+.agent-composer-slash-menu:not([data-scrolling="true"])::-webkit-scrollbar-thumb {
 	background: transparent;
 }
 
-[data-flowix-surface="select"][data-scrolling="true"]::-webkit-scrollbar-thumb {
+[data-flowix-surface="select"][data-scrolling="true"]::-webkit-scrollbar-thumb,
+.agent-composer-slash-menu[data-scrolling="true"]::-webkit-scrollbar-thumb {
 	background: color-mix(in oklch, var(--muted-foreground) 25%, transparent);
 }
 
-html[data-platform="mac"] [data-flowix-surface="select"][data-scrolling="true"]::-webkit-scrollbar-thumb {
+html[data-platform="mac"] [data-flowix-surface="select"][data-scrolling="true"]::-webkit-scrollbar-thumb,
+html[data-platform="mac"] .agent-composer-slash-menu[data-scrolling="true"]::-webkit-scrollbar-thumb {
 	background: color-mix(in oklch, var(--muted-foreground) 78%, transparent);
 }
 
+html[data-platform="mac"] .agent-composer-slash-menu:not([data-scrolling="true"])::-webkit-scrollbar-thumb {
+	background: transparent;
+}
+
 html[data-platform="non-mac"] .overlay-scrollbar,
 html[data-platform="mac"] .overlay-scrollbar-frame--custom-mac .overlay-scrollbar {
 	overflow: auto;
@@ -155,6 +164,16 @@ html[data-platform="mac"] .overlay-scrollbar-frame--custom-mac .overlay-scrollba
 	width: 6px;
 }
 
+/* Keep the notebook selector's overlay thumb clear of the popup's rounded corners. */
+.flowix-notebook-selector-scrollbar > .overlay-scrollbar-track--vertical {
+	top: 8px !important;
+	bottom: 8px !important;
+}
+
+.flowix-notebook-selector-scrollbar > .overlay-scrollbar-thumb--vertical {
+	top: 8px !important;
+}
+
 /* Horizontal counterpart of the product scrollbar: matching capsule thumb,
  * track hit area, fade behavior, and drag support. */
 html[data-platform="non-mac"] .overlay-scrollbar-track--horizontal,
diff --git a/app/flowix-web/styles/pdf-print.css b/app/flowix-web/styles/pdf-print.css
index 429534e13..005c2c559 100644
--- a/app/flowix-web/styles/pdf-print.css
+++ b/app/flowix-web/styles/pdf-print.css
@@ -85,7 +85,8 @@
     caret-color: transparent !important;
   }
 
-  html.flowix-pdf-printing .stable-editor-caret,
+  html.flowix-pdf-printing .stable-editor-caret--document,
+  html.flowix-pdf-printing .agent-composer__stable-caret,
   html.flowix-pdf-printing .ProseMirror-cursor,
   html.flowix-pdf-printing .cm-cursor,
   html.flowix-pdf-printing .cm-dropCursor,
@@ -149,14 +150,14 @@
     margin: 0 !important;
     padding: 0 !important;
     overflow: visible !important;
-    font-family: var(--app-font-family, var(--font-sans));
-    font-size: var(--app-font-size, 15px);
-    line-height: var(--app-line-height, 1.8);
+    font-family: var(--editor-font-family, var(--font-sans));
+    font-size: var(--editor-font-size, 16px);
+    line-height: var(--editor-line-height, 1.8);
     color: var(--document-foreground);
     background: transparent !important;
     overflow-wrap: anywhere;
     word-break: break-word;
-    --editor-scale: calc(var(--app-font-size, 15px) / 16px);
+    --editor-scale: calc(var(--editor-font-size, 16px) / 16px);
   }
 
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror > :first-child {
@@ -210,7 +211,7 @@
   /* Paragraphs: keep the editor's padding-based block rhythm. */
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror > p {
     margin: 0;
-    padding-bottom: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.25);
+    padding-bottom: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.25);
     white-space: pre-wrap;
     orphans: 3;
     widows: 3;
@@ -218,7 +219,7 @@
 
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror > p:empty,
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror > p:has(> br.ProseMirror-trailingBreak:only-child) {
-    min-height: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8));
+    min-height: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8));
   }
 
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror strong {
@@ -252,13 +253,13 @@
     border-radius: 0.5rem;
     padding: 0.4rem 0.8rem 1.2rem;
     padding-top: 0;
-    margin: 0 0 calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.25);
+    margin: 0 0 calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.25);
     font-family: inherit;
     font-size: inherit;
     white-space: pre-wrap;
     word-break: break-word;
     overflow: visible !important;
-    line-height: var(--app-line-height, 1.8);
+    line-height: var(--editor-line-height, 1.8);
     break-inside: avoid;
     page-break-inside: avoid;
   }
@@ -278,7 +279,7 @@
     width: calc(100% - 1px) !important;
     max-width: calc(100% - 1px) !important;
     min-width: 0 !important;
-    margin: 0 0 calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.32);
+    margin: 0 0 calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.32);
     padding: 0.4rem 0.8rem 1.2rem;
     padding-top: 0.4rem;
     padding-bottom: 0.5rem;
@@ -326,8 +327,8 @@
   /* Quote: copied from editor.css; its vertical padding is already zero. */
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror blockquote {
     border-left: 0.1875rem solid var(--border);
-    margin: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.2) 0
-      calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.52);
+    margin: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.2) 0
+      calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.52);
     padding: 0 0 0 1rem;
     color: var(--document-foreground);
     font-style: normal;
@@ -347,7 +348,7 @@
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror li {
     margin: 0;
     padding: 0;
-    line-height: var(--app-line-height, 1.8);
+    line-height: var(--editor-line-height, 1.8);
   }
 
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror ul:not([data-type="taskList"]) {
@@ -360,7 +361,7 @@
 
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror li > p {
     margin: 0;
-    padding-bottom: calc(var(--app-font-size, 15px) * var(--app-line-height, 1.8) * 0.25);
+    padding-bottom: calc(var(--editor-font-size, 16px) * var(--editor-line-height, 1.8) * 0.25);
   }
 
   html.flowix-pdf-printing .flowix-pdf-print-scope .markdown-editor .ProseMirror ul {
diff --git a/app/flowix-web/styles/plugin-markmap.css b/app/flowix-web/styles/plugin-markmap.css
index a5a319e6e..47838e1bf 100644
--- a/app/flowix-web/styles/plugin-markmap.css
+++ b/app/flowix-web/styles/plugin-markmap.css
@@ -20,7 +20,7 @@
   display: block;
   width: 100%;
   height: 100%;
-  --markmap-font: 400 var(--app-font-size, 15px)/1.45 var(--font-sans);
+  --markmap-font: 400 var(--editor-font-size, 16px)/1.45 var(--font-sans);
   --markmap-text-color: var(--foreground);
   --markmap-a-color: var(--brand);
   --markmap-a-hover-color: color-mix(in oklch, var(--brand) 78%, var(--foreground));
diff --git a/app/flowix-web/types/agent.ts b/app/flowix-web/types/agent.ts
index fc50246a4..633445880 100644
--- a/app/flowix-web/types/agent.ts
+++ b/app/flowix-web/types/agent.ts
@@ -11,18 +11,50 @@ export interface ThreadListItem {
 }
 
 // Core message type used throughout the app
-export type AgentTypeKey =
-  | "codex"
-  | "claude"
-  | "gemini"
-  | "hermes"
-  | "openclaw"
-  | "opencode"
-  | "pi"
-  | "deepseek-harness";
+/** Stable identity values used by frontend state and the backend protocol. */
+export type AgentId = "pi" | "codex" | "claudecode" | "opencode" | "hermes" | "dsh";
+
+export type ActiveAgentTypeKey = AgentId;
+export type AgentTypeKey = AgentId;
+
+export type AgentRuntimeKind = "builtin" | "external-cli";
+
+/** `missing` means detection completed and found no executable/runtime. */
+export type AgentInstallationState = "unknown" | "installed" | "missing";
+
+/** Readiness describes whether a known installed runtime can be started. */
+export type AgentReadinessState = "unknown" | "ready" | "blocked";
+
+export type AgentRuntimeReasonCode =
+  | "path-not-detected"
+  | "runtime-not-installed"
+  | "configured-path-missing"
+  | "version-too-low"
+  | "preflight-failed"
+  | "no-model-configured"
+  | "no-usable-model"
+  | "status-check-failed";
+
+interface AgentRuntimeSnapshotDetail {
+  /** Machine-readable cause for a blocked or unknown result. */
+  reasonCode?: AgentRuntimeReasonCode | null;
+  /** Human-readable detail for tooltip/setup UI. */
+  reason?: string | null;
+}
+
+/** Runtime presence is separate from whether the runtime can currently start. */
+export type AgentRuntimeSnapshot = AgentRuntimeSnapshotDetail & (
+  | { installation: "unknown"; readiness: "unknown" }
+  | { installation: "missing"; readiness: "unknown" }
+  | { installation: "installed"; readiness: AgentReadinessState }
+);
+
+export type AgentRuntimeStatusById = Record<AgentId, AgentRuntimeSnapshot>;
 
 export interface AgentType {
-  key: AgentTypeKey;
+  /** Stable runtime protocol identity. */
+  id: AgentId;
+  runtimeKind: AgentRuntimeKind;
   /** 图标资源路径 (Vite 静态资源 import 解析后的 URL)。所有 agent 图标统一在 agent-types.ts 集中管理。 */
   icon: string;
   name: string;
@@ -115,18 +147,15 @@ export interface ClaudeRuntimeConfig extends AgentRuntimeConfigBase {
   permissionMode?: AgentPermissionMode;
 }
 
-export interface SimpleCliRuntimeConfig extends AgentRuntimeConfigBase {}
-
 export interface HermesRuntimeConfig extends AgentRuntimeConfigBase {
   permissionMode?: AgentPermissionMode;
 }
 
 export interface AgentRuntimeConfig {
+  notebookId?: string;
   codex?: CodexRuntimeConfig;
   claude?: ClaudeRuntimeConfig;
-  gemini?: SimpleCliRuntimeConfig;
   hermes?: HermesRuntimeConfig;
-  openclaw?: SimpleCliRuntimeConfig;
   opencode?: CodexRuntimeConfig;
   pi?: PiRuntimeConfig;
   deepseekHarness?: DeepSeekHarnessRuntimeConfig;
@@ -156,7 +185,7 @@ export interface FilesConfig {
   workspace?: string | null;
   /** 启用目录列表 (path 数组) */
   folders: string[];
-  /** 笔记本路径列表 (path 数组, 与 agent-access-store 同语义) */
+  /** 笔记本路径列表 (path 数组, 由 Agent Store 的 workspace 解析) */
   notebooks: string[];
   /**
    * 旧冻结模型的兼容字段。新数据使用 `RuntimeConfig.workspaceSnapshot`。
@@ -206,7 +235,7 @@ export interface RuntimeConfig {
   serviceTier?: AgentCodexServiceTier;
   /** DeepSeek Harness Agent preset, locked per thread card. */
   deepseekHarness?: Pick<DeepSeekHarnessRuntimeConfig, "mode">;
-  /** Pi coding-agent presentation mode, locked per thread card. */
+  /** Legacy Pi snapshot, read only for compatibility. New conversations omit it. */
   pi?: Pick<PiRuntimeConfig, "codeMode">;
   /** 预留：工具白名单 */
   tools?: string[];
@@ -216,16 +245,8 @@ export interface RuntimeConfig {
   workspaceSnapshot?: WorkspaceSnapshot;
   /** Canonical conversation workspace state. Legacy snapshots are read-only migration input. */
   workspaceState?: ConversationWorkspaceState;
-  /**
-   * 创建该 instance 时所属 notebook 的 id 快照 (如 `nb_<ts>` / `nb_default`)。
-   *
-   * 非运行时配置 ── 它不发给 LLM, 仅用于把卡片关联到所属 notebook 的
-   * `.flowix/agent.json` add-dir 配置。借 `runtimeConfig` 的
-   * JSON 透传通道一起落 SQLite (后端 `runtime_config` 是裸 TEXT, 不解析内部),
-   * 与 `_frozen` 同构 ── 无需 backend schema 升级。
-   *
-   * 缺失时仅保留历史会话兼容，不再写入全局资料默认。
-   */
+  /** Owning notebook identity. Persisted with the conversation and forwarded
+   * as backend workspace-validation metadata; local.db owns its mounts. */
   notebookId?: string;
 }
 
@@ -503,7 +524,7 @@ export interface AgentChunkStreamStart {
   run_id?: string;
   /**
    * 通用 metadata 协议字段 —— 该 run 锁定的 LLM model id. 后端在 spawn 时确定 (从用户配置 / CLI override 解析), 对 OpenAI /
-   * Codex / Claude / Gemini 等所有 provider 一致, 字段不识别时为 undefined. 前端读 `run.model ?? threadStates[tid].runs[activeRunId].model` 取值.
+   * Codex / Claude 等所有 provider 一致, 字段不识别时为 undefined. 前端读 `run.model ?? threadStates[tid].runs[activeRunId].model` 取值.
    */
   model?: string;
   /**
@@ -657,7 +678,7 @@ interface AgentEventBase {
 export type AgentEvent =
   | (AgentEventBase & {
       kind: "stream_start";
-      /** 通用 metadata 协议字段 —— 该 run 锁定的 LLM model id。后端在 spawn 时确定 (从用户配置 / CLI override 解析), 对 OpenAI / Codex / Claude / Gemini 等所有 provider 一致, 字段不识别时为 undefined。前端读 `run.model ?? threadStates[tid].runs[activeRunId].model` 取值。 */
+      /** 通用 metadata 协议字段 —— 该 run 锁定的 LLM model id。后端在 spawn 时确定 (从用户配置 / CLI override 解析), 对 OpenAI / Codex / Claude 等所有 provider 一致, 字段不识别时为 undefined。前端读 `run.model ?? threadStates[tid].runs[activeRunId].model` 取值。 */
       model?: string;
       /** 通用 metadata 协议 —— reasoning effort ("low"/"medium"/"high"/"xhigh")。Provider 不支持时为 undefined。 */
       reasoning_effort?: string;
@@ -740,7 +761,7 @@ export interface RunInfo {
  * 通用 metadata 协议 —— session 的最近一次 run 展示快照。写在
  * `ThreadState.lastRun` 中, run 从 `runs` map 清理后仍作为常驻展示信息保留；
  * 迟到的 usage 事件也会继续合并到这个快照。Provider-agnostic: 对 Codex /
- * Claude / Gemini / Hermes / OpenClaw / DeepSeek Harness 全部适用, 字段不识别时为 undefined。
+ * Claude / Hermes / DeepSeek Harness 全部适用, 字段不识别时为 undefined。
  */
 
 export interface LastRunSnapshot {
diff --git a/app/flowix-web/types/memo-item.ts b/app/flowix-web/types/memo-item.ts
index 0e53d3cd0..bd5fddbc5 100644
--- a/app/flowix-web/types/memo-item.ts
+++ b/app/flowix-web/types/memo-item.ts
@@ -1,4 +1,4 @@
-/** Memo-ID compatibility payload mirrored from the legacy Core Memo DTO. */
+/** Path-keyed memo event projection mirrored from the Core note DTO. */
 import {
   noteListItemKey,
   noteListItemRelativePath,
@@ -16,12 +16,11 @@ export {
   noteListItemTitle,
 } from './note-item';
 
-/** @deprecated Use NoteColor for path-identified Notes. */
+/** @deprecated Use NoteListItem for path-identified Notes. */
 export interface MemoItem {
-  id: string;
   filename: string;
   /** Path relative to the notebook root, using `/` separators. */
-  relativePath?: string;
+  relativePath: string;
   preview: string;
   thumbnail?: string | null;
   tags: string[];
diff --git a/app/flowix-web/types/memo.ts b/app/flowix-web/types/memo.ts
index 9c719f18e..3d7ae1dfc 100644
--- a/app/flowix-web/types/memo.ts
+++ b/app/flowix-web/types/memo.ts
@@ -19,7 +19,7 @@ export type MemoChangeSource =
   | 'user_delete'
   | 'cloud_sync';
 
-export type MemoContentCommit = {
+export type NoteContentCommit = {
   derivedOnly?: boolean;
   /** SHA-256 of the exact committed markdown bytes. */
   contentHash?: string;
@@ -49,27 +49,23 @@ export type MemoEvent =
       notebookId: string;
       derivedChanged: MemoDerivedChanged;
       source: MemoChangeSource;
-    } & MemoContentCommit)
+    } & NoteContentCommit)
   | ({
       kind: 'updated';
-      /** @deprecated Legacy memo cache id. Dedup/patch keys use relativePath. */
-      id?: string;
       path: string;
       memo: MemoItem;
       notebookId: string;
       derivedChanged: MemoDerivedChanged;
       source: MemoChangeSource;
-    } & MemoContentCommit)
+    } & NoteContentCommit)
   | ({
       kind: 'deleted';
-      /** @deprecated Legacy memo cache id. Dedup keys use relativePath. */
-      id?: string;
       path: string;
       relativePath: string;
       notebookId: string;
       derivedChanged: MemoDerivedChanged;
       source: MemoChangeSource;
-    } & MemoContentCommit)
+    } & NoteContentCommit)
   | {
       kind: 'tags_renamed';
       notebookId: string;
diff --git a/docs/AGENT-DATA.md b/docs/AGENT-DATA.md
new file mode 100644
index 000000000..fe438d1ee
--- /dev/null
+++ b/docs/AGENT-DATA.md
@@ -0,0 +1,25 @@
+# Agent data ownership
+
+Device-local notebook registration and repository mounts are stored in `~/.flowix/db/local.db`.
+
+- `notebooks` owns notebook identity, display metadata, local root paths and order.
+- `notebook_add_dirs` owns notebook-scoped repository mounts. The same directory may be mounted by multiple notebooks. A notebook deletion cascades to its mounts.
+- `notebook_workspace_state` records migration completion and mount revisions.
+- `app_state` stores selected notebook state; `notebook_setup_jobs` preserves first-open setup jobs.
+
+The frontend Agent Store projects workspace data from IPC into memory. Its `workspace.resources` is derived from notebook mounts. Workspace data is neither persisted in localStorage nor merged from old browser caches. Agent model/skill catalogs and user preferences retain their existing browser persistence.
+
+Repository selection commits a mount to a specific notebook. There is no independent global folder pool. Removing a mount does not affect another notebook's mount of the same path. Missing mounts remain visible and removable.
+
+Flowix file IPC authorizes registered notebook roots and enabled mounted directories, together with existing explicit document grants. Agent submissions wait for initial workspace hydration; each conversation captures its own workspace snapshot. Backend chat and DSH command dispatch validate snapshot paths against current mounts, using notebook scope when present. Native Agent sandbox settings remain separate from these Flowix checks.
+
+## Upgrade imports
+
+- `index.db` is retired and is no longer opened or imported. After successful version initialization, copies in `~/.flowix/` and `~/.flowix/db/`, including SQLite companions, are moved to each directory's `rebuild-backups/<UUID>/` for manual recovery. Installations with only an old index must re-register their notebook folders.
+- Each notebook's `.flowix/agent.json` is imported once. Older `agent-access.json.defaults.files` is a fallback for notebooks registered before the upgrade. Unattached global folder entries never create mounts.
+- Missing notebook roots defer the mount import. Malformed legacy files fail without marking import complete, allowing a later retry. Successfully imported sources are not reread after mounts change.
+- Old runtime defaults are exposed through a migration-only IPC and imported into the browser-owned user preference Store.
+
+Legacy files are retained on disk for recovery, but normal workspace writes use only `local.db`.
+
+On macOS, `~/.flowix/boot/bookmark.json` is the only bookmark store. Directory selections and successful access to registered notebook directories persist directory bookmarks; single-file selections persist file bookmarks without granting their parent directory. Saved scopes are restored at startup and held for the process lifetime. Stale bookmarks are regenerated from the resolved URL and their stored paths are updated. Denied directory access is not recorded. macOS privacy controls still apply; Flowix cannot observe the system Allow button directly. Old bookmark locations are no longer read or migrated.
diff --git a/docs/COLLECTION-INDEX.md b/docs/COLLECTION-INDEX.md
index d9c49152b..97d560ed0 100644
--- a/docs/COLLECTION-INDEX.md
+++ b/docs/COLLECTION-INDEX.md
@@ -9,6 +9,7 @@
 - 文件夹专用的 `.index.yaml` 始终不在笔记本文件树、访问空间文件树和目录文件列表中展示，也不能通过文件可见性设置显示；点击文件夹时仍会读取它并加载集合。
 - 文件夹的 `.index.yaml` 通过 `collection.placement: folder` 标明用途；独立文件通过 `placement: standalone` 标明用途。文件名不决定集合类型，`collection.type` 决定是 `notes` 还是 `media`。
 - `.table.yaml`、`.table.yml`、`.lib.yaml`、`.lib.yml` 继续作为旧文件名读取。新建及重命名后的独立集合使用 `.index.yaml`。
+- 集合展示名称直接从路径推导：独立集合取文件名去掉扩展名；文件夹集合取 `.index.yaml` 的父目录名。新文件不写 `collection.name`；读取旧文件时忽略该兼容字段。
 - 集合 ID 为创建时生成的 `col_` + 32 位 UUIDv7 十六进制字符串。名称、文件名和相对路径均不构成集合身份。
 
 ## 数据结构
@@ -24,7 +25,6 @@ collection:
   id: col_01900000000070008000000000000000
   type: notes                 # notes | media
   placement: folder           # standalone | folder
-  name: 开发任务管理
   revision: 0
   created_at: "2026-10-11T00:00:00.000Z"
   updated_at: "2026-10-11T00:00:00.000Z"
@@ -49,9 +49,10 @@ payload:
       include: []
       exclude: []
     filter:
-      all:
+      path: null
+      match: all
+      conditions:
         - { field: kind, op: eq, value: note }
-      any: []
   views:
     default_id: view_01900000000070008000000000000001
     items:
@@ -71,7 +72,11 @@ payload:
 
 `dataset.schema` 描述笔记属性字段；笔记属性值仍保存在各笔记 frontmatter。`records.include` 和 `records.exclude` 保存显式记录引用；笔记记录使用 `note_path`，媒体记录使用 `resource_id` 和 `relative_path`。尚未关联笔记的表格草稿行允许 `include.note_path: ""`。`dataset.filter` 保存规则取数条件。媒体集合当前不开放自定义字段，`schema.fields` 应为空；图片和视频身份仍由 `media_resources` 管理。
 
-`dataset.filter: null` 表示不按规则自动收集，仅展示显式记录。启用规则取数后，`{ all: [], any: [] }` 表示对来源范围不增加条件。媒体筛选面板修改 `dataset.filter`；`views.items[].filter` 仅用于视图级筛选，不再重复执行旧版 `file_condition`。
+`dataset.filter: null` 表示不按规则自动收集，仅展示显式记录。数据集筛选使用 `{ path, match, conditions }`：`path` 是必须满足的笔记本相对目录前缀，`null` 表示不追加路径限制，空字符串表示显式选择全部目录；`match: all` 要求 `conditions` 全部满足，`match: any` 要求至少一项满足。整体逻辑固定为 `source 范围 AND path 匹配 AND 条件组匹配`。路径规则不放入条件数组，因此不会随交集 / 并集切换而失效。`path: null` 且空条件数组表示对来源范围自动收集全部记录。
+
+文件夹集合的固定目录由 `.index.yaml` 所在文件夹决定，使用 `source.scope: containing_folder`，并将该目录相对笔记本根目录的路径写入 `dataset.filter.path`；路径选择在文件夹集合中禁用。这样表格、媒体库主视图和媒体库引用都按同一个固定目录筛选，移动 `.index.yaml` 时该路径随集合位置重定位；读取执行时也按当前位置解析有效路径，因此通过系统文件管理器移动后不会继续受旧路径限制，下一次保存会同步更新路径。独立集合的“浏览和保存”目录也写入 `dataset.filter.path`，同时用于保存新建笔记或媒体的目标目录。独立集合若另有 `source.scope: folder`，其来源边界仍由 `source.path` 定义。
+
+读取时兼容旧版数据集规则筛选。可无损转换的简单旧规则会在用户下次保存时写成新结构；混有非空 `all` 和 `any`、或含嵌套分组的旧规则无法由单一 `match` 表达，编辑器会保留原规则并阻止覆盖。旧的路径规则会提升为独立的必需路径。`views.items[].filter` 仍使用视图筛选的 `all` / `any` 格式。
 
 筛选器使用 `all`（全部满足）与 `any`（至少满足一项）；规则项允许再包含一层 `all`/`any` 分组。旧表格中“多个属性同时满足，或命中文件条件”转换为 `any: [{ all: [属性规则…], any: [] }, 文件规则…]`，保留原有匹配结果。
 
@@ -98,9 +103,9 @@ payload:
           relative_path: 图片/参考.png
       exclude: []
     filter:
-      all:
-        - { field: kind, op: in, value: [image, video] }
-      any: []
+      path: null
+      match: all
+      conditions: []
   views:
     default_id: view_01900000000070008000000000000004
     items:
diff --git a/docs/DOCUMENT-MODULE-REFACTOR.md b/docs/DOCUMENT-MODULE-REFACTOR.md
new file mode 100644
index 000000000..fe3c2c5a7
--- /dev/null
+++ b/docs/DOCUMENT-MODULE-REFACTOR.md
@@ -0,0 +1,208 @@
+# 文档模块整理
+
+## 约束
+
+- 笔记继续按路径寻址，运行中的编辑会话使用 displayId。
+- 集合使用 collectionId；所选 viewId 属于展示实例。
+- 保留保存队列、CAS、操作回执、恢复草稿和各领域状态。
+- 每迁移一种行为即删除对应旧协调逻辑，不建立万能资源服务。
+
+## 职责
+
+| 位置 | 负责 | 不应承担 |
+| --- | --- | --- |
+| 后端领域操作 | 持久化、索引、持久引用、失败恢复 | 依赖前端事件补齐持久一致性 |
+| 文档会话 | 编辑缓冲、保存基线、冲突、草稿 | 文件树查询 |
+| 集合领域 | 配置、dataset、views、结构校验 | Markdown 缓冲 |
+| 工作区 | 展示、导航、恢复位置 | 文件持久化 |
+| 查询消费者 | 按影响范围刷新结果 | 自行协调跨领域路径迁移 |
+| 传输适配 | 解释旧消息、提供类型化契约 | 从 fs modify 推断正文已经变化 |
+
+## 已开始的迁移
+
+`platform/tauri/notebook-change-events.ts` 是旧 `flowix:path-note-changed`
+通道的类型化边界，不增加第二条广播通道。
+
+- `path-moved`：带确认的旧／新相对路径和 directory。
+- `resource-deleted`：带删除路径。
+- `query-invalidated`：指定路径或整个笔记本需要重新查询，不代表内容提交。
+
+全部现有前端路径通道消费者改用此入口。内容提交仍由 memo-event 和
+文档监听现有机制处理，集合配置仍保留 collection-changed。
+笔记移动和标题重命名现在也发送完整移动信息。
+
+## 第二阶段实现
+
+- 后端 `commands/path_change.rs` 定义确认移动事实；文件／目录命令响应中的
+  `notebookChange` 与广播携带相同 `changeId`。集合用 notebookId 和已存在
+  的 operationId 构造相同标识，不引入第二条广播通道。
+- 前端 IPC 适配器将命令结果交给 `subscribeNotebookChanges` 的同一消费者。
+  每个消费者维护有界的去重集合，避免一个消费者抑制其他消费者。
+- 对外的 files.rename/move/renameFolder/moveFolder 仍返回路径字符串。
+  兼容前端 HMR 已更新而旧后端尚未重启时的旧字符串响应。
+- 文档层拒绝过期迁移时，工作区停止对应导航迁移；重复确认同一目标地址
+  不重复更新文档历史。
+- 路径移动遍历全部运行身份，而非只看激活文档；批量期间暂停身份回收。
+  工作区更新打开位置、目录上下文、媒体、集合、恢复目标和文档历史，保留
+  展示身份、视图选择、焦点及其他宿主状态。
+- 恢复草稿按持久地址迁移，覆盖无运行身份的关闭草稿；与路径通知队列串行，
+  避免下一次移动在上一次草稿迁移结束前开始处理。
+- 主窗口移动与删除共用顺序队列。笔记专用移动／重命名也接入 watcher
+  move guard 和 lease rebase，失败退出释放 guard。
+- 置顶读取 notes 中的 favorited 投影，新增直接消费笔记本变更的刷新入口，
+  旧请求结果由 requestSequence 隔离，不先清空已有组。
+- 移除笔记专用操作的重复链接任务提交；其余相邻相同任务在队列合并。
+
+### 持久一致性边界
+
+目录移动沿用 core `rename_indexed_path`：notes、派生索引、内容版本地址与
+媒体地址在 notebook DB 事务中迁移，失败执行文件和索引回滚。
+置顶是 notes 的属性，不是前端缓存或独立的置顶列表表。
+笔记专用移动沿用 NoteService：磁盘为事实，索引失败写 pending-refresh
+标记并保留原有修复机制。集合引用更新保持 CAS，发生并发编辑时不覆盖。
+这些机制不等于跨文件系统与多个配置文件的全局事务。
+
+### 当前限制
+
+changeId 解决同一确认事实的重复投递，不是版本号；本地队列保留接收次序，
+不会为任意乱序、缺失的外部事件推测资源身份。原始 watcher 的无标识通知
+仍需按路径安全应用；外部变化全面核对与恢复属于第四阶段。
+非笔记本访问目录继续保留原有命令调用方的路径处理。
+
+
+## 后续交付顺序
+
+### 第三阶段进度
+
+- `prune_missing_memo` 清理失效路径索引和表格引用后，即使没有旧 memo
+  compatibility row，也会发出带 changeId 的路径删除事实。有 memo row 时仍走
+  MemoEvent，避免同一删除广播两类删除事件。
+- 删除事实由各查询消费者按范围处理：笔记列表合并 24ms 后重查，置顶区跳过普通
+  新建事件并消费用户删除及云同步 MemoEvent；主窗口另行刷新标签与待办派生元数据。路径删除路由
+  清理浏览器标签，以及工作区当前、pending、previous、选中笔记和持久恢复目标中
+  命中的文件路径。若 previous 是唯一命中项，只移除回滚地址，保留当前有效视图。
+- 缺失笔记提示和列表删除入口不再重复本地刷新／关闭；由 MemoEvent 或路径删除
+  事件统一更新所有窗口。删除前的保存检查和成功提示仍由调用处负责。
+- 普通创建、模板创建和导入都返回并广播同一个 `NotebookPathCreated` 回执。
+  前端命令回执和广播进入同一订阅边界，以 changeId 去重；旧桌面进程缺少回执时，
+  前端用已确认的创建结果刷新当前窗口。
+- 普通新建与模板创建结果就地 upsert。模板创建和批量导入不再额外发起重复列表
+  查询。创建回执携带发起窗口标识；发起窗口由命令结果 upsert，其他窗口重查，
+  批量导入在本地逐项 upsert。
+- 笔记属性继续使用文档保存队列；保存回执由文档会话消费，路径失效通知刷新列表。
+  颜色、置顶和自定义筛选的调用处保留即时行内 patch，不再额外触发整表查询。
+- 集合引用的内容刷新由 `collection-changed` 或外部路径变化负责；本地集合回执只
+  更新路径跟踪，不再触发同一个引用重复读取。目录集合移动会在集合变更通知中携带
+  移动范围，驱动嵌套集合引用和目录清单刷新；文件树按目录范围迁移缓存，并抑制随后
+  到达的重复文件系统通知。
+
+本阶段已收口删除／失效清理、创建，以及保存／属性的查询刷新入口；集合配置消费
+已按 `operationId` 区分集合变更和随后的目录清单通知。代码级外部写入盘点已完成，
+并补上云端删除缺少兼容 Memo 行时的路径清理／通知，以及云端属性变更对置顶投影的
+刷新。复核发现并修复了置顶区未消费 `UserDelete` MemoEvent、以及命令创建事件让
+发起窗口重复查询的问题。用户已确认之前的第三阶段运行时验收完成；上述复核修复尚未
+再次运行时验收，本轮也未运行自动测试。
+
+已定位的入口：前端笔记操作在 `memo-document-operations.ts`，普通文件
+在 `local-document-operations.ts`，集合在 `collection/mutations.ts`；
+桌面命令分别进入 `commands/memo`、`commands/file.rs` 和
+`commands/collection.rs`。入口核对如下：
+
+| 写入来源 | 持久化和索引 | 前端通知／会话 | 失败边界 |
+| --- | --- | --- | --- |
+| 界面笔记创建、保存、删除 | 路径型 `NoteService` 更新 Markdown 和 notebook 的 SQLite `notes` 投影；路径命令不要求兼容 Memo 行 | 创建回执和 `flowix:path-note-changed` 由同一适配边界消费；路径编辑会话使用保存队列及提交回执。仍走旧 Memo 模型的操作继续发 `memo-event` | 磁盘是笔记正文事实；路径索引可重建，Memo 兼容清理不应阻止已确认的路径删除通知 |
+| Agent 的 Flowix CLI/MCP | `flowix-cli/src/path_store.rs` 通过 core `NoteService` 创建、CAS 保存、删除；不经过前端服务，直接更新路径索引 | 桌面文件监听刷新查询；外部创建发 `resource-created/source=external_tool`，可按既有偏好自动打开；活跃文档由外部文档监听器通知 | CLI 与桌面端不共享命令回执；关闭应用期间的变更由下次索引 reconcile 收敛 |
+| Agent shell、外部编辑器和其他进程 | 直接写 notebook 文件时，桌面文件监听器按路径刷新可重建索引，并记录本地云同步变化 | 文件监听发移动、删除或查询失效；当前打开的路径另由 `ExternalDocumentWatchState` 的原生监听和 750ms 修订轮询通知，未保存缓冲走外部变更合并 | 外部内容事件发送失败会保留修订供轮询重试；主文件监听不可用或索引刷新失败时依赖 watcher 重绑／启动 reconcile |
+| Flowix Cloud V2 拉取、冲突解决和历史恢复 | 写盘后重建路径与兼容 Memo 投影；写入冲突副本时单独注册副本 | `MemoEvent` 标记 `cloud_sync`；置顶区现在消费此来源；磁盘监听由 self-write revision 抑制，避免把云端回写误判为外部编辑 | 内容 hash、pending dirty 和安全替换保护本地编辑；远端删除改为按路径工作，即使兼容 Memo 行缺失也清理路径投影并发路径删除事实；集合表格引用在 notebook 写锁释放后清理 |
+
+Agent 的 Flowix CLI/MCP 与 Agent shell 是两种写入路径：前者经过 `NoteService`，后者
+由文件系统监听发现。路径型笔记不创建兼容 Memo 行，因此外部写入不会伪造
+`MemoEvent::Created/Updated`；`MemoChangeSource::ExternalTool` 保留给仍以 Memo 为事实的
+调用方。外部创建使用路径事件表达来源，并由工作区按既有偏好决定是否打开。
+
+失败边界仍需注意：进程级文件监听不是持久消息队列；应用关闭期间没有 UI 实时通知，
+恢复依靠启动 reconcile。索引数据库持续不可写时，磁盘操作与查询投影可能暂时分离，
+当前仍依赖后续 watcher 重试或 reconcile 修复。
+
+1. 入口矩阵已覆盖界面 notes/files/collections、Agent、CLI、云同步，并记录
+   持久化、索引、引用、回执及通知负责人。
+2. 移动闭环的命令回执、重复投递和路径消费者已迁移；运行时验收已完成。
+3. 删除／失效清理、创建、保存／属性刷新及集合配置通知消费已迁移；外部写入入口
+   矩阵已完成；运行时验收已完成。
+   失效清理必须与物理删除、取消置顶、关闭展示分别表达。
+4. 收口打开、关闭、恢复、外部变更核对，保留领域独立会话实现。
+5. 移除旧适配和重复订阅，完成整个模块验收。
+
+### 第四阶段进度
+
+- 将导航离开从 `flushDocumentPath` / `flushWorkspaceDocumentPath` 改名为
+  `prepareDocumentLeave` / `prepareWorkspaceDocumentLeave`。它只保留会话并启动
+  保存与恢复草稿，不再让调用名暗示磁盘写入已完成；文档切换仍不等待文件 I/O。
+- 版本恢复、版本归档、路径笔记删除使用 `saveDocumentPath`，先捕获编辑器最终
+  内容并等待标题和正文保存队列完成，再做覆盖或删除。路径删除不再额外拼接
+  一个调用方级 save-queue 等待。
+- `DocumentStore` 的生命周期注释同步说明了导航准备与破坏性写入的不同保证。
+
+第四阶段本轮又复核了外部变化与路径迁移交错时的恢复草稿地址，以及退出超时后重试
+与动态编辑捕获器的收尾行为。也静态复核了打开与导航补偿入口：会清理文档会话的操作
+由 `clearDocument` 统一准备一次，保留会话的目标走显式准备；没有发现同一导航事务重复
+协调的调用链。第四阶段没有运行自动测试或完整运行时验收。
+
+本轮第四阶段继续处理了打开、恢复和外部变化的交界：
+
+- 文档加载和恢复草稿读取都按当前路径核对。加载期间发生路径移动时，旧路径的
+  读取结果不会落进新路径会话，而是针对移动后的路径重新读取；恢复读取的去重键
+  也包含路径，避免复用旧地址的草稿请求。
+- 打开时发现恢复草稿与磁盘相同，不再把它重新挂成未保存缓冲，并在没有待恢复标题
+  时清除已完成保存遗留的草稿；草稿与基线相同但内容较新时，也会进入普通条件保存，
+  不会只显示在内存里而不触发写回。
+- 恢复存储读取超过 10 秒会显示可重试的读取错误，不再被当作“没有草稿”继续打开；
+  这避免慢 IPC 时新编辑覆盖尚未读出的旧恢复草稿。
+- 文档加载结束会把 `ready` 或 `unavailable` 结果写入文档转换状态。启动等待会等
+  当前转换结束；被新导航替换时继续等待新目标，加载失败会让首屏进入 degraded，
+  保留本地错误／重试入口。
+- 活跃文档收到外部删除时取消尚未开始的保存计时，先保护未保存内容，再读取路径
+  实际状态以展示缺失笔记入口。读失败会使会话缓存标记为未加载，重试会重新读盘。
+  外部不可用错误也映射为缺失笔记状态。
+- 退出准备设有 16 秒前端截止时间，为桌面端 20 秒多窗口握手预留应答时间。单窗口
+  的 flush 会在首次保存后检查是否出现新文档会话／持久化适配器，并最多补做一轮；
+  工作区持续变化或超时会拒绝本次关闭，让用户仍可重试。
+- 关闭握手开始后暂时冻结窗口输入；两轮 flush 结束前再次检查新编辑捕获器、未保护的
+  正文／标题草稿及待执行保存计时。超时后仍在运行的会话 flush 由单飞协调复用，避免
+  用户重试时并发启动第二个 flush。
+- 全局退出等待期间新挂载的文档窗口会加入当前参与集合并收到同一退出请求，避免
+  退出快照之后打开的窗口没有保存确认机会。
+- 异步保护草稿时按运行时 display identity 解析最新路径，避免目录重命名与外部变化或
+  退出保存交错时，把恢复草稿写到已过期的旧路径。
+- 工作区切换到会清理文档会话的媒体／集合目标时，不再在调用方和 `clearDocument`
+  各准备一次同一文档。仍保留文档会话的网页和文件夹选择器走明确命名的
+  `prepareActiveWorkColumnDocumentLeave`。
+- 删除当前笔记本前改用 `saveWorkspaceDocumentPath` 等待标题与正文保存完成；一般
+  工作区离开继续走后台准备。`flushWorkspaceDocument` 的兼容适配已在第五阶段移除。
+
+本轮代码级修复与静态复核已完成；第四阶段仍待用户后续统一运行时验收。自动测试未运行。
+
+### 第五阶段进度
+
+- 删除 `flushWorkspaceDocument` 兼容适配和没有调用方的
+  `waitForWorkspaceDocumentSaves`，工作区导航统一使用显式的离开准备或持久保存入口。
+- 外部文档监听集中到文档专用协调器。同一路径和授权范围共享一条 Tauri 事件订阅与
+  watcher lease；多个授权范围产生相同路径修订事件时只处理一次。
+- 预期事件在路径级分发之前消费一次，避免第一个视图消费后，同一事件被其他视图误判为
+  外部编辑。多视图仍分别刷新各自的加载／缺失状态；提示、恢复草稿保护和冲突合并按事件
+  共享一次。
+- 删除无调用方的 `useMemoEvents` hook 适配，并修正文档事件总线和分发器中与当前实现不符
+  的说明。保留 `onFlushReady`：文件树切换文件时仍用它等待当前文件保存，职责不同于通用
+  surface 生命周期注册。
+
+第五阶段代码清理与静态审阅已完成，`git diff --check` 通过。本轮未运行自动测试；完整模块运行时验收留待用户统一进行。
+
+## 验收清单
+
+各阶段验证覆盖未保存内容、保存中、多窗口、外部变更、重复／乱序／遗漏
+通知、命令超时回执、失败恢复、重启和资源缺失。重点确认路径移动不会
+触发内容冲突，持久索引及置顶不会依赖界面刷新才能正确。
+
+既有记录：Rust 桌面库 cargo check --no-default-features 通过；全仓 TypeScript 检查
+曾受其他模块错误阻挡。第三阶段由用户确认运行时验收完成；自动测试未运行。第四阶段
+的实现和完整模块验收仍在进行。
diff --git a/docs/FRONTEND-MODULE-BOUNDARIES.md b/docs/FRONTEND-MODULE-BOUNDARIES.md
index a21bb1b63..a08dbee5f 100644
--- a/docs/FRONTEND-MODULE-BOUNDARIES.md
+++ b/docs/FRONTEND-MODULE-BOUNDARIES.md
@@ -56,6 +56,16 @@ contract and should shrink as higher-level commands are introduced.
 Same-feature code may use its own internal paths. Tests may import internals
 when they are explicitly testing an internal unit.
 
+## Markdown parsing worker
+
+`features/editor/markdown-parser-extensions.ts` is the parser-only registry used
+for every Markdown document. Its extensions must come from pure Markdown
+modules; they must not import editor NodeViews, React, Tauri clients, or feature
+stores. Editor extensions reuse the same tokenizer and parse specs so parsing
+behavior stays aligned between the Worker and the interactive editor. Raw HTML
+and other unsupported forms return an explicit Worker error and use the
+existing main-thread parser fallback.
+
 ## Navigation transaction
 
 Workspace owns the order of a navigation change:
@@ -96,15 +106,14 @@ The `app/main-window` composition code also consumes Workspace through
 aware of feature capabilities without binding it to Workspace's Zustand state
 shape or use-case file layout.
 
-Application update lifecycle, DSH download observation, and DSH onboarding
+Application update lifecycle, DSH download observation, and notebook onboarding
 persistence are owned by `app/main-window/use-main-window-system-controller`.
 Shell receives their current presentation state through
 `MainLayoutSystemController`; it no longer starts those subscriptions or writes
 the onboarding flag itself.
 
-The DSH onboarding and installation prompt is owned by Preferences and exposed
-through `features/preferences/public/dsh-install-prompt`. Shell only places the
-prompt in its overlay stack and supplies controller state from `app/main-window`.
+DSH runtime installation is managed in Preferences. Shell only exposes active
+download progress in the status bar; startup has no DSH installation prompt.
 
 `features/shell/main-layout` now consumes Document, Memo, Agent, Surface, and
 Workspace through their `public/shell-api` entrypoints. These entrypoints are
@@ -114,10 +123,9 @@ stores. The public hooks retain narrow selectors and shallow equality inside
 the owning module, preserving render-subscription behavior while hiding store
 shape and implementation paths from Shell.
 
-MainLayout delegates bottom-bar composition to `MainStatusBarHost` and overlay
-composition to `MainPromptHost`. These hosts group cohesive presentation props
-and keep platform navigation and prompt ordering outside the central layout
-tree. Their cross-feature imports are protected by the public-entrypoint rule.
+MainLayout delegates bottom-bar composition to `MainStatusBarHost`. Navigation
+failures use the shared actionable-notice host and Workspace's public API;
+Shell does not own a floating prompt stack.
 
 Middle-column switching is coordinated by
 `useMainMiddleColumnController`. It owns the Agent conversation list's lazy
@@ -192,7 +200,5 @@ selection. The first two files are fully protected from cross-feature deep
 imports; global search is ratcheted on its migrated Workspace seam while its
 legacy Memo and Agent dependencies are handled separately.
 
-Navigation failure and application update prompts are isolated presentation
-components under `features/shell/components/prompts`. The navigation prompt
-uses Workspace's public API, and boundary checks protect prompt components from
-reaching into another feature's private implementation.
+Navigation failure recovery is published through the shared actionable-notice
+host and Workspace's public API. It no longer has a Shell prompt component.
diff --git a/docs/NOTEBOOK-STORAGE.md b/docs/NOTEBOOK-STORAGE.md
index ea2268f8f..cea3df52e 100644
--- a/docs/NOTEBOOK-STORAGE.md
+++ b/docs/NOTEBOOK-STORAGE.md
@@ -9,7 +9,7 @@ Flowix-owned metadata.
 
 ```text
 ~/.flowix/
-  index.db                         Device-local notebook registry
+  db/local.db                      Device-local notebook registry
 
 <notebook>/
   *.md                             Note content; source of truth
@@ -30,8 +30,8 @@ migration still moves plugin output from `.plugin-output/` into that directory.
 
 | Store | Ownership | Contents | Rebuild policy |
 | --- | --- | --- | --- |
-| `~/.flowix/index.db` | Device | Notebook registry and legacy source rows for import | Preserve; it is not a notebook cache |
-| `<notebook>/.flowix/notebook.db` | Notebook | Path-keyed note and full-text projections, the multidimensional-table listing catalog, legacy memo-ID compatibility records, media identities and properties | Rebuild note, search, and table-listing projections selectively; preserve user-owned media properties and compatibility data |
+| `~/.flowix/db/local.db` | Device | Notebook registry, workspace mounts and setup state | Preserve; it is not a notebook cache |
+| `<notebook>/.flowix/notebook.db` | Notebook | Path-keyed note and full-text projections, the multidimensional-table listing catalog, media identities and properties | Rebuild note, search, and table-listing projections selectively; preserve user-owned media properties |
 
 The notebook database deliberately remains one file. Its tables have different
 lifecycles, so maintenance code must target the relevant tables and must not
@@ -41,6 +41,22 @@ Media bytes remain in notebook files. The `media_resources` table stores a
 notebook-relative path, resource identity, file fingerprint, and user
 properties. Those properties cannot be reconstructed from the media file.
 
+## Notebook template setup lifecycle
+
+The device-local registry stores notebook template setup jobs. A stable
+`job_id` identifies the selected template task across retries; each execution
+gets a new `run_id`; a registry-wide revision orders events across task
+deletion and recreation. Registration leaves a task pending until the selected
+notebook's workspace is ready. The application coordinator requests its pending
+job after the active workspace switch settles; requested pending jobs and
+interrupted running jobs resume after workspace preparation.
+
+The worker persists the `indexing` stage and its aggregate write report before
+removing the initialization marker. Indexing retries therefore continue from
+that checkpoint without reapplying template files. Terminal state remains
+owned by the worker until it is durably stored. The frontend combines status
+events with a complete registry snapshot; taking a snapshot never starts work.
+
 The multidimensional-table listing is a rebuildable file catalog. Its
 view-group membership preference is stored separately by stable `table_id`,
 so a catalog refresh or file rename does not reset the user's choice.
@@ -54,16 +70,18 @@ different visibility semantics and should remain separate.
 - **Note** is a Markdown document identified by `(notebook_id, relative_path)`.
   Moving or renaming it changes that identity. The file remains the content
   source of truth.
-- **Memo ID** is an opaque compatibility identity. It is not the identity of a
-  path-based Note and must not be generated for new Note writes.
+- Note identity is `(notebook_id, relative_path)` across storage and APIs.
 - **Media resource** is a separate image or video identity with notebook-owned
-  properties. Its ID is independent from both Note paths and Memo IDs.
+  properties. Its ID is independent from Note paths.
+- Frontmatter properties, including `flowix_key`, are user data. The application
+  does not generate, interpret, or use `flowix_key` as a document identity.
 - **File entry** is any filesystem file or directory shown by the browser; it
   has a path but does not automatically need a database identity.
 - Use `registry_db_path()` and `notebook_db_path(id)` when opening a database.
-- `MemoFile` remains a compatibility storage façade. `NotebookRegistry` owns
-  the device-local registry path, connection setup and config cache; Note,
-  media, revision and Memo-ID implementations live in their own modules.
+- `MemoFile` remains the storage façade used by existing core operations;
+  document identity is path-based. `NotebookRegistry` owns the device-local
+  registry path, connection setup and config cache; Note, media and revision
+  implementations live in their own modules.
 - Note projection tables use `note_*` names. Existing `v2_*` projection tables
   are discarded transactionally on first open. The current projection is kept
   when both sets exist; when only V2 exists, Markdown files rebuild the new
@@ -71,48 +89,27 @@ different visibility semantics and should remain separate.
 - Keep generic file-tree enumeration on the filesystem. Do not add database
   rows for ordinary files unless a feature needs durable metadata for them.
 
-### Memo ID compatibility boundary
-
-Memo ID is still a real compatibility identity in several persisted and public
-surfaces. Keep those uses explicit; do not treat every remaining `Memo` string
-as a naming cleanup that can be mechanically replaced.
-
-| Surface | Current Memo-ID dependency | Direction |
-| --- | --- | --- |
-| Notebook database | `memos.id` and `memo_lifecycles.memo_id` retain old identity and lifecycle state. `memo_tags`, `memo_colors`, `memo_todos`, and `memo_agents` attach persisted associations to that identity. | Preserve until each association has a path-keyed migration and a rollback/read-compatibility policy. These rows are not part of the rebuildable Note projection. |
-| Revisions | Legacy memo versions and content-revision records are addressed by Memo ID; existing version archives may be stored under that ID. | Keep old-version reads and writes behind compatibility operations. Path-based Note revision history is separate and should not need an ID. |
-| IPC and links | Existing `get_memos`-style commands, Memo-shaped payloads, ID lookup, plugin artifact references, and older deep links can carry a Memo ID. | Keep command strings and ID resolvers as adapters while callers migrate. New Note operations should pass `(notebookId, relativePath)`. |
-| Web state | `notes` is the path-keyed source for the main Note list. Legacy Memo IPC events still carry IDs, but the Web store now treats them as invalidation signals instead of retaining a Memo-ID list cache. | Keep ID-shaped event payloads in the IPC adapter. New view state should use Note paths. |
-| CLI and integrations | Older CLI/MCP requests and external callers can address notes by Memo ID. | Preserve the old address form as an adapter; new address forms use notebook ID plus relative path. |
-
-Path-based Note list, search, create, edit, move, delete, and Note-version
-operations should use Note types and APIs. Keep compatibility adapters at the
-service/IPC boundary; do not copy Memo IDs into Markdown or make them a second
-Note key. Migrating any persisted association requires its own data migration
-and compatibility plan.
-
-The Rust path API exposes `NoteEntry`, `NoteDocument`, `NotePage`, and
-`NoteService`; `MemoService` handles the remaining Memo-ID use cases. The old
-`v2_*` SQLite projection tables are discarded on first use.
-On the Web side, path-identified operations use the `notes` Tauri client,
-`noteRepository`, and `useNoteStore` / `NoteLibraryStore`. The `memos` Tauri
-client retains commands that still operate on Memo IDs. Existing Tauri command
-strings stay stable while Rust and Web callers migrate.
-
-The Web store's Note list is keyed by `(notebookId, relativePath)`. Legacy Memo
-events invalidate that list; the Web store no longer retains a parallel list
-keyed by Memo ID. Remaining Memo-ID consumers are confined to compatibility
-commands and integration surfaces that still explicitly request Memo data.
-
-The persisted filenames `index.db` and `notebook.db` are retained for backward
-compatibility. Their meanings are made explicit by the APIs above; changing
-those filenames requires a separate, downgrade-aware migration.
+The Rust service boundary exposes path-keyed `NoteService` operations. The
+`MemoService` facade and `resolve_memo` service lookup have been removed. The
+Web Note list is keyed by `(notebookId, relativePath)`, and path-identified
+operations use the `notes` Tauri client. On notebook initialization, legacy
+Memo properties are copied into Markdown before the old Memo tables are
+dropped; tags, todos, and agents are rebuilt from Markdown into the `notes`
+row. The old `v2_*` SQLite projection tables are discarded on first use.
+
+The persisted filename `notebook.db` is retained for backward
+compatibility. Its meaning is made explicit by the APIs above; changing
+that filename requires a separate, downgrade-aware migration.
 
 ## Index update model
 
 - Note writes and Markdown watcher events refresh one path. Startup and
   directory-level recovery reconcile the notebook tree against the note
   projection.
+- The `notes.tags`, `notes.todos`, and `notes.agents` columns are the query
+  source for tag navigation and note task/agent summaries. Tags are derived
+  from Markdown; notebooks do not store standalone empty tags or a separate
+  tag catalog.
 - The `note_search_fts` FTS5 table caches note titles, tags and body text. A
   path refresh updates it in the same transaction as the note projection.
   Existing notebooks backfill it once on the first path-based search, using
@@ -130,5 +127,7 @@ those filenames requires a separate, downgrade-aware migration.
 - The file tree and folder document list read the current directory directly;
   folder document lists do not keep a separate file-entry catalog. The notebook
   watcher writes the media catalog.
-- The legacy memo-ID search remains an in-memory projection. Search caches may
-  be rebuilt; user properties and media metadata must be preserved.
+- Note storage and queries use notebook-relative paths. Markdown remains the
+  source for rebuildable note metadata; the note index has no document ID key.
+
+The global `index.db` is retired. Version initialization no longer copies or imports it. After current stores initialize successfully, both old locations and their SQLite companions are archived under `rebuild-backups/<UUID>/` before initialization is marked complete. Cleanup failures are logged and skipped independently for each location; they do not block initialization or schedule a retry on normal startup. Old-only installations must re-register their notebook folders; Markdown files are unchanged.
diff --git a/docs/PI-INTEGRATION.md b/docs/PI-INTEGRATION.md
index cd7f355f6..54b7aa980 100644
--- a/docs/PI-INTEGRATION.md
+++ b/docs/PI-INTEGRATION.md
@@ -21,25 +21,25 @@ Pi session with the persisted Pi session ID and the updated runtime settings.
 
 ## Build variants
 
-- `npm run tauri:dev:pi` downloads the matching Pi v1.1.0 archive into
-  `.build/pi-runtime`, verifies its pinned SHA-256 digest, and points the dev
-  app at that executable. No system-wide Pi installation is required.
-- `npm run tauri:dev` reuses Pi from an installed Flowix app when it finds one
-  in the standard app location for the current platform. Set `PI_CLI_PATH` to
-  override the executable path, or `FLOWIX_PROD_APP_PATH` when the app is in a
-  non-standard location. This avoids downloading or staging another Pi build.
-- `npm run tauri:build:prod` builds Flowix without Pi. The user must have `pi`
-  on `PATH` or set `PI_CLI_PATH` to a Pi v1.1.0 executable.
-- `npm run tauri:build:prod:pi` downloads the matching Pi v1.1.0 release
-  archive, verifies its pinned SHA-256 digest, and puts the matching runtime
-  in the app resources. The universal macOS build stages arm64 and x64
-  archives separately and includes only the matching runtime in each app.
+- Pi is an application resource in every desktop build. Runtime availability
+  checks and Pi process startup resolve the same bundled executable; neither
+  `PATH` nor `PI_CLI_PATH` selects an external Pi installation.
+- `npm run tauri:dev` reuses the matching architecture already staged in
+  `.build/pi-runtime`; if it is missing, the command downloads Pi v1.1.0,
+  verifies its pinned SHA-256 digest, and stages it. No system-wide Pi
+  installation is required. `npm run tauri:dev:pi` remains available to force
+  staging again.
+- `npm run tauri:build:prod` stages Pi v1.1.0 and includes it in the package.
+  The legacy `npm run tauri:build:prod:pi` command remains an alias. A universal
+  macOS build stages arm64 and x64 archives and packages only the matching
+  runtime in each app. Release CI prepares the runtime for each target before
+  generating its Tauri resource configuration.
 
-Pi-enabled artifacts use the Pi updater endpoint family. Release infrastructure
-must publish manifests under `/updater/pi/{macos,windows,linux}/latest.json` or
-set `FLOWIX_UPDATER_ENDPOINT_PI_MACOS`, `FLOWIX_UPDATER_ENDPOINT_PI_WINDOWS`,
-and `FLOWIX_UPDATER_ENDPOINT_PI_LINUX` as appropriate. This keeps Pi-enabled
-and base installations on separate update channels.
+Production packages always include Pi. Their updater endpoint remains the
+regular platform endpoint unless `FLOWIX_UPDATER_ENDPOINT_PI_MACOS`,
+`FLOWIX_UPDATER_ENDPOINT_PI_WINDOWS`, or `FLOWIX_UPDATER_ENDPOINT_PI_LINUX` is
+configured. Set those variables only when release infrastructure publishes a
+separate Pi manifest, such as `/updater/pi/{macos,windows,linux}/latest.json`.
 
 ## Models and permissions
 
@@ -79,6 +79,15 @@ Pi history adapter maps native user, assistant, reasoning, tool, bash, custom,
 and compaction messages into Flowix rows and pages the full RPC transcript by
 conversation turns. Pi's session remains the history source of truth; Flowix's
 external-event journal is not used to reconstruct Pi conversations.
+History RPC responses are routed by request ID, so snapshots can be read while
+a prompt is streaming. Flowix checks the native append cursor and active leaf
+around the message read; an unfinished tail without a native entry ID remains
+owned by the live stream projection. Pi does not persist a partial assistant
+message, so a refresh restores committed history and the submitted user message
+but cannot restore assistant text streamed before the refresh. If a new turn is
+still starting its Pi process, history reads wait for that active run to bind
+its session before reading, so reopening the conversation does not mistake
+session startup for an empty history.
 
 Pi thinking blocks are not forwarded to Flowix by default. Set
 `FLOWIX_PI_FORWARD_THINKING=1` (also accepts `true`, `yes`, or `on`) in the
diff --git a/docs/STARTUP-LIFECYCLE.md b/docs/STARTUP-LIFECYCLE.md
new file mode 100644
index 000000000..473cc7aef
--- /dev/null
+++ b/docs/STARTUP-LIFECYCLE.md
@@ -0,0 +1,253 @@
+# Desktop startup lifecycle
+
+Stage 1 is controlled solely by the durable completion record for the current
+application version. Missing indexes, offline notebooks, old watcher preferences
+and background failures never reopen this stage.
+
+Stage 2 prepares current local stores, selects the notebook from registry metadata,
+and renders the workbench shell. It does not enumerate notebook files, query counts
+across notebooks, probe every external directory, load Cloud credentials, or await
+restored document/panel contents. A metadata failure exposes a retry screen rather
+than pretending that the notebook list is empty. `notifyStartupInteractive` means
+the shell or retry screen has painted, not that all its content has loaded.
+
+Stage 3 has independent execution paths:
+
+- Visible document, collection, media and Agent content loads through its normal
+  view lifecycle. User navigation supersedes delayed restoration.
+- The frontend admits non-essential startup checks only after the workbench has
+  painted; Tauri sends the native interactive signal first. Admission is
+  idempotent per WebView; named startup tasks run once and report failures
+  without changing stage-2 readiness. This is a gate and deduplication point,
+  not a shared task queue.
+- Agent event subscriptions remain early so live session events are not missed.
+  Agent run/history reconciliation waits for admission and the selected
+  workspace target to settle (up to two seconds); stage-3 admission already
+  follows the shell paint, so reconciliation needs no second paint wait. It
+  refreshes currently interested conversations first, then catches up hidden
+  sessions two at a time. Visible conversation hydration remains owned by its
+  view. The one-time Agent runtime refresh waits for native startup CLI
+  discovery to finish before reading paths. The backend runtime-status command
+  owns this dependency for every caller. Its wait is race-safe and bounded to
+  30 seconds; a timeout logs and returns the best available status so the Agent
+  surface remains usable.
+  Agent workspace and Pi mode snapshots load after main-window stage-3 admission;
+  the separate preferences window loads them when that window is opened. Model
+  and notebook skill catalogs load on demand instead of being prefetched for
+  every launch. Note-link cache warming and interrupted repair resume run after
+  admission.
+- Automatic app-update checks retain their 3.6-second delay, but the timer starts
+  only after admission and the named task is deduplicated. Explicit update
+  checks remain immediate. DSH download progress subscription and its active
+  download snapshot remain early; the main window skips a second DSH runtime
+  status query because Agent runtime status already reads it. DSH preferences
+  still load their own status when opened. The advisory DSH version check stays
+  with the Agent card that displays it, waits for admission and shares one result
+  across cards. Clicking the runtime update action still starts immediately.
+- Onboarding state and the previous app-update result are read early. Onboarding
+  is shown after admission. A previous update-result toast waits until onboarding,
+  the product intro and other prompts are closed, so startup messages do not
+  compete for the same attention.
+- The stage-3 gate makes one attempt per named task and does not provide a shared
+  retry policy. Note-link repair owns up to three delayed retries; Agent runtime
+  refresh makes one startup request and can refresh again when an Agent surface
+  requests stale status; Agent session
+  reconciliation runs again after listener recovery or window focus; automatic
+  app-update failure remains silent and the explicit check is the retry path.
+  Agent workspace snapshots reload after listener recovery or workspace changes;
+  Pi mode initialization retries when a Pi operation requests it. Other advisory
+  checks stay feature-owned and can run again when requested.
+- `NotebookBackground` admits passive note/media maintenance after shell paint.
+  One worker coalesces requests, prioritizes the current notebook, yields between
+  batches and cooperatively cancels work for shutdown/update or higher-priority
+  work. Directory watcher events and watcher rebinds use the same note queue;
+  media maintenance has its own status revisions and explicit retry command, so
+  a media failure cannot change the note-index readiness state.
+- The filesystem watcher binds all currently available notebook roots in one
+  pass. A separate 15-second retry loop attaches roots that were offline or
+  unavailable at startup, then requests one reconciliation for changes made
+  while the root was detached. Watcher retries stop after accepted application
+  exit. Split rename tracking is seeded when each root attaches.
+
+Cloud initialization/credential recovery, CLI discovery and housekeeping also
+start after shell paint. Cloud schema initialization retries with bounded
+exponential backoff up to 60 seconds; Cloud store APIs initialize their schema
+on first use if an explicit request arrives before the background service.
+Credential reads hold no auth lock; a later login/logout supersedes startup
+restoration. A 120-second wait without an interactive signal is recorded as
+`interactive-timeout-degraded-release`: it releases independent services for
+liveness and does not assert that the shell painted.
+
+## Data and concurrency contracts
+
+Note-list, count and tag queries do not reconcile files. Notebook list responses contain only registry metadata
+and available background statistics. An omitted count is unknown; a completed
+empty projection reports zero. Index-dependent queries return `NOTE_INDEX_PENDING`
+or a scope-local unavailable state. Completion invalidates that notebook once.
+
+A scan uses a separate `MemoFile` facade instead of holding AppState's global lock.
+Note scanning retains per-file SQLite transactions and notebook OS locks across
+GUI, CLI and Cloud operations. Media maintenance retains its SQLite consistency
+checks, rechecks stale paths before cleanup, and guards against intervening catalog
+renames/restoration. Filesystem traversal is never an atomic snapshot. Explicit accurate snapshots/imports/mutations
+retain their blocking consistency requirements; they are not silently replaced by
+cached results. Scanner cancellation is checked between files; an operating-system
+filesystem call already blocked on an external device cannot be forcibly aborted.
+
+Cancelled cold builds remain incomplete. Warm refreshes keep the preceding
+projection readable. Incomplete/unavailable directory walks are not evidence of
+resource deletion. Projection schema preparation preserves the shared notebook
+DB and media properties. Higher-version session databases are rejected without
+being classified as corruption or replaced by an empty store.
+
+## Status delivery and lifecycle
+
+`flowix:notebook-maintenance` publishes notebook ID, state, revision, optional
+count/path availability and failure text. `get_notebook_background_status` is the
+snapshot counterpart. The frontend reconciles on listener readiness/recovery and
+rejects older revisions and regressing same-revision events. List/panel loading
+and retry remain independent of global startup state.
+
+Media cleanup uses `flowix:media-maintenance` and
+`get_notebook_media_maintenance_status`; the media library exposes a retry action
+for failed maintenance. Its revisions and state do not affect note-index status.
+
+Queue failures do not stop other notebooks. Repeated passive failures have a short
+admission backoff; explicit retry is immediate. Accepted application exit stops
+admission and cooperatively cancels the current scan. Windows updater preparation
+pauses maintenance; a failed update resumes it through the update guard.
+
+## Implementation review
+
+Review covered the version gate, stage-2 dependencies, stage-3 admission and
+shutdown, separate facades, stale event/snapshot delivery, offline notebooks,
+cold projections, shared media data, and delayed workspace navigation.
+
+Issues found and fixed during review:
+
+- A late pending-query response could overwrite a failed maintenance task and
+  leave a list waiting indefinitely. Passive pending responses preserve terminal
+  states; explicit retry can enqueue a new attempt.
+- A maintenance-lock conflict could be reported as a successful background scan
+  using an older warm count. Background scans now report busy explicitly; the
+  older passive API retains its documented skip behavior.
+- An older DB without projection tables could turn an unknown count into an SQL
+  error. Cached counts now inspect table presence without creating a projection.
+- Admission could race with accepted shutdown between its initial stop check
+  and queue insertion. Both operations now serialize on the queue lock.
+- Pausing the worker could race with its condition-variable wait and lose the
+  resume notification. Pause/resume now update their predicate under the same
+  queue lock used by the waiter.
+- When the current notebook root was offline, the previous startup bind omitted
+  every other root too. Startup now binds all available roots, and a stoppable
+  retry loop attaches offline roots independently and reconciles their changes.
+- Dynamically attached roots now seed the split-rename identity tracker, keeping
+  rename pairing reliable after a volume becomes available.
+- Restored workspace content could finish a slower table, collection, folder,
+  media or Agent lookup after a newer user navigation. The startup navigation
+  revision is now passed through each restore path and checked before navigation
+  or filesystem side effects.
+- Interrupted note-link repair no longer starts on component mount. Startup
+  admits it after the shell paint signal; explicit file moves and document saves
+  still resume it immediately.
+- Cloud schema failures previously left credential recovery and polling
+  disabled until restart. Initialization now retries with bounded backoff while
+  the existing auth generation guard protects explicit login/logout.
+- Media maintenance failures previously had only a log entry. They now publish
+  a separate versioned status and can be retried from the media library.
+- Startup metrics now say `background-services-admitted`; they no longer imply
+  that background work itself has completed.
+- A media file could reappear after traversal, or its row could be renamed or
+  restored before stale cleanup. Cleanup rechecks the path and uses conditional
+  updates/deletes against the captured path and missing/deleted state.
+- Deferred credential results could share a revision with the initial Restoring
+  snapshot. Changed results now advance the revision, so stale snapshots lose.
+- A collection path-conflict retry kept the pre-navigation restore revision and
+  could reject its own retry. The retry now carries the current navigation
+  revision while remaining supersedable by later user navigation.
+- A stale in-flight completion flag could disagree with a successful record for
+  the same app version. The successful-version record now acts as a skip fallback;
+  the explicit development rerun control clears that fallback for the current
+  version.
+- Agent runtime refresh could race native CLI discovery and cache an unknown path.
+  The runtime-status command now waits on a completion condition backed by
+  latched in-process state plus a notification, so every caller observes the
+  dependency and late subscribers cannot miss completion.
+- Agent model and notebook-skill catalog requests were being launched globally
+  from the root effect. They now load only when their feature needs them; the
+  initial runtime refresh remains ordered after CLI discovery.
+- Main-window update and DSH checks previously started outside a shared
+  first-paint admission point. Automatic update checking now runs as a named,
+  deduplicated stage-3 task; the main window relies on the runtime snapshot for
+  DSH status and retains only progress recovery at startup.
+- Onboarding and the prior-install result toast could become visible during the
+  same startup transition. Onboarding is now decided at the stage-2 notebook
+  context boundary, and opens when no notebook is available; it does not wait
+  for a boot-feature read or stage-3 admission. The toast still waits until
+  startup prompts are closed.
+- Agent history catch-up could race workspace restoration and fan out all
+  conversations together. It now yields briefly to the restored view, starts
+  interested histories first, and limits background catch-up to two requests at
+  a time; listener recovery received during this window is replayed afterward.
+- A follow-up runtime refresh after 1.5 seconds repeated the same startup check.
+  Stage 3 now makes one request; Agent surfaces can refresh stale status when
+  needed.
+- Agent workspace and Pi mode reads were starting before the main shell painted.
+  The main window now loads them through one named stage-3 task, while the
+  separate preferences window loads them when opened. Workspace change
+  subscriptions remain early and buffer reloads until the initial snapshot ends.
+- DSH settings read runtime status in both the parent and its installer child.
+  The parent owns the snapshot; child installer hooks now only subscribe to
+  progress and perform install actions.
+- Stage-3 tasks intentionally remain one-shot and own their retry policy. The
+  lifecycle notes now document the existing retry paths and explicit checks.
+
+Validation before the follow-up lifecycle hardening on the current macOS host:
+55 frontend tests, 36 desktop startup tests,
+15 core note-index tests, 18 media tests, 59 sync tests, and one test each for
+notebook-list serialization, higher-version session preservation, and runtime
+configuration across process restarts passed. The runtime registry regression also
+passed (187 tests in total). Desktop library compilation
+and `git diff --check` passed. A stale desktop test reference to a removed runtime
+method was corrected to the existing `id()` API and canonical runtime IDs, so
+these tests compile and execute normally.
+
+The follow-up hardening changes above were reviewed statically but were not
+revalidated after editing. The full TypeScript check remains blocked by 246 existing errors, principally the
+AgentId migration; no errors were reported in the startup/maintenance files or
+navigation files changed for this work. Two previously reproduced baseline core
+index failures were excluded from the focused index run:
+`mixed_v2_and_note_tables_keep_current_note_rows` and
+`note_projection_coexists_with_legacy_rows_in_the_same_notebook_db`.
+
+No packaged-app timing measurements or Windows/Linux runtime validation were
+performed. No claim is made that an in-flight OS filesystem call can be cancelled.
+The frontend stage-3 admission, deferred Agent recovery, DSH startup query split,
+and native CLI-detection completion wait added in this implementation were
+reviewed statically; no tests or builds were run for these changes.
+The additional Agent-history priority, Agent-context admission, and DSH status
+deduplication edits in this review were also checked statically; no tests or
+builds were run for them.
+
+## Watcher binding lock contract
+
+Binding paths serialize a fresh registry read with watcher changes, using
+`watcher::runtime::read_registered_notebooks` and a short-lived independent
+MemoFile facade. They must not acquire AppState's global MemoFile lock while
+holding the watcher lock: document writes hold a global MemoFile read guard
+while registering watcher self-write marks, and a pending global writer can
+turn a nested watcher-to-MemoFile read into a lock cycle. Current-notebook
+identity for startup queue priority is read before taking the watcher lock.
+A registry read failure preserves bindings; retrying an uninitialized watcher
+must queue reconciliation for every successfully attached root after binding,
+not merely initialize the OS watcher and skip the next retry.
+
+Validation of the watcher lock/recovery follow-up: all 36 `app::` tests and
+33 of 36 `watcher::` tests passed, including four new registry/recovery tests.
+The registry test reads while the global MemoFile write lock is held; it
+verifies removal of that dependency rather than relying on platform-specific
+RwLock writer-priority behavior to reproduce a deadlock. Recovery queue tests
+use real notify root attachments and exclude offline/suspended roots.
+The three remaining watcher failures are unchanged whitelist assertions that
+expect hidden files/default file exclusions which the current defaults no
+longer apply. No packaged-app or cross-platform deadlock timing was exercised.
diff --git a/docs/STARTUP.md b/docs/STARTUP.md
new file mode 100644
index 000000000..6e94654ea
--- /dev/null
+++ b/docs/STARTUP.md
@@ -0,0 +1,63 @@
+# 启动阶段与任务接入
+
+桌面端启动分为三个阶段。阶段 1 是当前应用版本的一次性初始化；阶段 2 在每次启动运行，负责让当前笔记本和工作台 shell 可用；阶段 3 在工作台首次绘制后放行内容恢复和非阻塞服务。阶段 3 不延长阶段 2，也不增加第二层全屏 loading。
+
+| 阶段 | 目标 | 主要工作 | 就绪边界 |
+| --- | --- | --- | --- |
+| 1. 版本初始化 `initialization` | 升级当前版本所需的数据 | 数据库路径兼容、数据库准备、结构与持久化格式迁移、一次性修复、运行时准备 | 当前版本的持久化完成记录写入成功。正常启动跳过已完成的版本初始化 |
+| 2. 工作区准备 `workspacePreparation` | 展示可交互的工作台 | 准备当前本地存储、读取笔记本注册元数据、选定当前笔记本、初始化前端笔记本上下文 | 原生依赖 ready，笔记本身份与上下文可用，前端 shell 已绘制 |
+| 3. 绘制后工作 `stage 3` | 恢复内容并启动独立服务 | 恢复保存的工作区目标、可见视图加载内容、Agent 恢复、Cloud 初始化、CLI 探测、更新检查、笔记和媒体维护等 | 各任务按所属功能完成或报告自身失败；不改变阶段 2 的就绪结果 |
+
+原生 `StartupStatus.stage` 只表示阶段 1 和阶段 2，`phase` 表示 `pending/running/ready/failed`，`step` 标记当前任务。前端 `useWorkspaceStartupStore` 跟踪原生状态及工作台前台状态。阶段 3 是工作台绘制后的准入点，不是第三个全屏启动屏障。
+
+## 阶段 1：版本初始化
+
+初始化进度包含数据库路径处理、数据库准备、迁移 job 和运行时准备。笔记本文件扫描和工作区内容恢复不属于阶段 1。阶段 1 仅在当前应用版本尚未完成初始化时运行。
+
+迁移通过 `storage_initialization.rs` 的 `initialize_legacy_storage_with_progress` 接入，并使用稳定且唯一的任务 ID，例如 `feature_schema_v2`。迁移内容变化时使用新 ID，不复用已完成 ID。新增全局 job 时同步加入 `GlobalInitializationJob::ALL`，使任务计数和执行定义保持一致。
+
+迁移必须能够安全重试，因为操作成功后、完成记录写入前仍可能中断。必需迁移失败会阻止阶段 2 并保留失败状态；可选迁移失败不写完成记录，但不因此在同一版本的每次启动重新打开阶段 1。不能移除版本完成判断，也不能为发现新增任务而每次启动重跑阶段 1。
+
+## 阶段 2：工作区准备
+
+原生必需准备由 `spawn_workbench_startup` 调用 `prepare_startup_storage` 和 `prepare_notebook_selection`，使用 `StartupStage::WorkspacePreparation`；任务成功前原生状态保持未就绪。当前笔记本选择从本地注册元数据解析，不探测所有外部目录或磁盘。
+
+前端 `performMainWindowStartup` 按依赖顺序等待原生 ready、笔记本身份和笔记本上下文。随后释放 shell，等待 `MainLayout` 在 Suspense 边界内挂载，再给浏览器绘制机会，最后发送 `notifyStartupInteractive`。这个信号表示工作台或重试界面已挂载并有机会绘制，允许后台服务开始；它不表示恢复的文档或全部首屏数据已经加载。
+
+笔记本注册元数据读取失败时显示失败和重试界面，不将错误伪装成空笔记本列表。并发挂载共用一次启动 Promise，避免重复初始化。前端必需元数据任务加入 `performMainWindowStartup` 并等待其结果；不要把文档读取、列表加载或面板水合重新加入阶段 2 的等待链。
+
+## 阶段 3：工作台绘制后
+
+前端通过 `admitStartupStage3` 在 `MainLayout` 挂载并经过绘制机会后放行非必需任务。`runStartupStage3Task` 按 WebView 内的任务名去重；它提供准入和去重，不是共享队列，也不提供统一重试策略。每个任务保留自己的失败处理和重试入口。
+
+- 保存的工作区目标开始异步恢复；用户在绘制期间导航时，较新的导航目标优先。文档、表格、集合、媒体和 Agent 内容由各自的视图或导航路径管理加载状态。
+- Agent 事件订阅保持较早注册，避免漏掉实时事件。运行状态、历史补齐和 workspace 快照在准入后加载，并遵循当前工作区目标；隐藏会话的补齐限流执行。
+- Cloud 初始化与凭据恢复、CLI 路径探测和后台维护在 shell 绘制后启动。设备登记是独立的 fire-and-forget 任务，不参与前台就绪。Cloud schema 初始化使用有界退避；显式登录或退出优先于启动恢复。
+- 自动更新检查保留绘制后的延迟并按任务名去重；用户显式检查仍立即执行。Onboarding 和上次更新结果提示延后展示，避免多个提示同时出现。
+- 笔记索引、媒体维护和文件监视器属于后台服务，不阻塞阶段 2。离线笔记本根目录由独立重试流程绑定；维护失败通过各自的状态和重试入口处理。
+
+阶段 3 任务各自决定重试方式。例如，笔记链接修复有有限次延迟重试；Agent 状态可由 Agent 界面请求刷新；Agent 会话可在监听器恢复或窗口重新聚焦时再次对账；媒体维护有显式重试入口。不要把这些策略集中到阶段 3 准入器。
+
+## 失败与重试
+
+- 阶段 1 或阶段 2 的必需任务失败时保留失败阶段和具体任务，展示重试入口。原生失败先请求现有工作线程重试；前端重新加载以重跑前端准备。
+- 阶段 2 失败的重试界面绘制后也可以发送交互完成信号，以释放不依赖工作区的服务；原生初始化失败时不发送该信号。
+- 阶段 2 成功后，内容恢复错误由视图或导航本地展示，不回退工作台启动状态。
+- 原生在 120 秒内没有收到交互完成信号时，会用 `interactive-timeout-degraded-release` 释放独立服务以保证活性；该超时不能证明 shell 已绘制。
+
+## 代码入口
+
+- 阶段状态与协调：`app/flowix-desktop/src/app/startup.rs`
+- 原生准备与绘制后服务：`app/flowix-desktop/src/app/bootstrap.rs`
+- 前端工作台启动与目标恢复：`app/flowix-web/app/main-window-startup.ts`
+- 阶段 3 准入和按名去重：`app/flowix-web/lib/startup-stage3.ts`
+- 详细并发、维护和状态交付约定：[`STARTUP-LIFECYCLE.md`](./STARTUP-LIFECYCLE.md)
+
+新增阶段 1 任务应检查成功记录、完成后跳过和失败重试。新增阶段 2 任务应检查依赖顺序、失败重试和重复挂载去重。新增阶段 3 任务应检查准入前不会执行、同名任务不会重复启动，并验证该功能自己的失败和重试策略。
+
+## 启动并发补充
+
+- 遗留 Agent loading 标记必须在原生 ready 发布前清理，避免误清除本次启动中新建的消息状态。
+- Agent 一次性 workspace 快照与 effect 的订阅生命周期分开。重挂载可复用初始化 Promise，但每个订阅必须独立恢复变化队列和监听重连补齐；异步重载失败需要被观察。
+- 首屏后的 watcher 绑定、全量重绑和离线根重试，在 watcher 锁内通过 `watcher::runtime::read_registered_notebooks` 读取最新注册表。该入口使用独立 MemoFile facade，不获取 AppState 的全局 MemoFile 锁，避免与文档自写标记形成反向锁依赖。读取失败保留现有绑定，不将错误解释成空注册表。恢复全量绑定后，为实际绑定成功的根目录补排 reconciliation，覆盖监听空窗期；离线和暂停的根目录不在该分支误报为已恢复。
+- 原生日志接受 `stage3-admitted`、`workspace-restore-settled` 和 `workspace-restore-superseded`，用于区分准入、恢复完成和用户导航替代恢复。
diff --git a/docs/UPDATER-RELEASE.md b/docs/UPDATER-RELEASE.md
index b651da6f6..edaeefc9c 100644
--- a/docs/UPDATER-RELEASE.md
+++ b/docs/UPDATER-RELEASE.md
@@ -21,8 +21,8 @@ either client into a self-install loop.
 
 Manifests include `notify: true` by default. Set `FLOWIX_UPDATE_NOTIFY=false`
 when publishing a release that should remain available to manual checks but must
-not show the automatic update prompt or status-bar update button. The release is
-still detected by the updater and can be installed from Preferences.
+not show the automatic status-bar update button. The release is still detected
+by the updater and can be installed from Preferences.
 
 ## Manifest layout
 
diff --git a/docs/WINDOW-SHUTDOWN.md b/docs/WINDOW-SHUTDOWN.md
new file mode 100644
index 000000000..da4a0e03e
--- /dev/null
+++ b/docs/WINDOW-SHUTDOWN.md
@@ -0,0 +1,91 @@
+# Window close and application exit
+
+A user close/quit request has a **one second total deadline**, measured from
+native receipt (the mouse-up message timestamp for Windows custom controls).
+This is not a one-second delay: successful saves trigger destruction immediately.
+After one second, outstanding work is abandoned and the process is terminated.
+Already issued disk writes cannot necessarily be rolled back.
+
+## Responsibilities
+
+- Windows retains `decorations: false` and its existing React-drawn controls.
+  React publishes only the close button's physical rectangle and a revision.
+  A dedicated native message pump uses Windows Raw Input in background mode to
+  observe mouse input without JS. It does not suppress or capture clicks, checks
+  the owning process, and keeps the region anchored during resize/DPI changes.
+  Raw mouse input has one registration per process, so this module owns the
+  application's sole mouse registration. Failed initialization and stopped
+  pumps retry; a heartbeat reports whether the registered input pump is live.
+  The UI reports loss and recovery. The custom control remains clickable through
+  JS while the renderer responds.
+- The native pump only enqueues close intent. Separate workers arm deadlines before
+  framework/coordinator locks; a blocked UI dispatch cannot delay another click.
+  Geometry remains registered until the host unmounts or native `Destroyed`.
+- macOS keeps native traffic lights and native `CloseRequested` handling.
+- `app/desktop-shutdown.ts` installs at window startup, not editor mount. It
+  concurrently flushes document sessions, all mounted workspace surface barriers
+  (tables/media/CSV/etc.), and preferences including already dispatched writes.
+  Every close attempt captures fresh feature state, including after an updater
+  cancellation. Each feature exposes a narrow public shutdown API. No JS close
+  interceptor is installed. Frontend completion is a report, never permission to
+  close; Rust owns the only timeout so app exit and updater deadlines cannot race
+  a second frontend timer.
+- `commands/window_shutdown.rs` coordinates saving, window destruction and
+  updater preparation. Save acknowledgements and waiters use native window
+  instance identity rather than its reusable label. Only native `Destroyed`
+  confirms a window closed. Repeated clicks reuse the original request and do
+  not create extra deadline workers; repeated app-quit events remain deferred
+  behind the original save request.
+- `commands/shutdown_watchdog.rs` enforces an absolute `Instant` deadline on an
+  independent OS thread. A destroyed window's shared atomic liveness state
+  makes its callback a no-op. It bypasses UI/Tokio, logger locks, destructors
+  and atexit handlers when forcing process termination.
+- App cleanup runs once off the UI thread. It shares the original close/quit
+  deadline; it gets no extra saving or cleanup allowance.
+
+## Forced termination scope
+
+A hung native UI thread cannot reliably destroy only one window of a shared
+process. Under the strict one-second policy, a window still not destroyed at its
+deadline triggers **whole-application termination**, including other windows.
+A normally closed auxiliary window marks its watchdog target destroyed and
+leaves other windows open.
+Explicit app quit / closing the last window additionally keeps the app watchdog
+armed until the process exits. There is no confirmation that can extend the
+strict deadline. Unsaved changes may be lost as specified by this policy.
+
+A completely unresponsive native UI on macOS may not deliver a traffic-light
+click at all; OS Force Quit remains the external fallback. The application can
+only enforce its deadline once it receives a close intent. OS scheduling can
+also delay execution; the deadline is an enforcement target, not a real-time OS
+scheduling guarantee.
+
+## Installer separation
+
+Windows updater preparation still requires durable documents; a failed save or
+an unacknowledged window destruction cancels installation rather than discarding
+edits. Its native missing-response timeout is separate (8 seconds), and must
+never arm a user-exit watchdog. User close/quit supersedes update preparation.
+IPC names retaining `document` are kept for compatibility, while the coordinator
+owns the complete window lifecycle.
+
+## Verification and release checks
+
+Automated tests cover immediate completion, failed/stalled saves, concurrent
+surface/preferences flushing, preference writes already in flight, repeated
+quit requests, instance-scoped acknowledgements, stale request generations,
+native region hit boundaries/DPI and a real subprocess deadlocked on a mutex
+that must be terminated after the product's one-second budget. The Windows
+routing module is separately cross-type-checked.
+
+Before release, test on Windows and macOS:
+
+1. Close clean/dirty/conflicted documents and tables with inaccessible storage.
+2. Hang the Windows renderer after close-region registration. Click custom X;
+   verify native intent and termination without a renderer acknowledgement.
+3. Hang cleanup/storage; verify termination at the original total deadline.
+4. Close an auxiliary window normally; other windows must remain open. Stall
+   that close beyond the deadline; strict-policy whole-app termination must occur.
+5. Overlap close/quit/updater preparation; stale timers must not affect new requests.
+6. Verify custom control hit regions across scale, zoom, theme, fullscreen,
+   onboarding, preferences, overlapping hosts and input over other applications.
diff --git a/docs/WORKSPACE-DRAG-DROP.md b/docs/WORKSPACE-DRAG-DROP.md
new file mode 100644
index 000000000..57d44ea3b
--- /dev/null
+++ b/docs/WORKSPACE-DRAG-DROP.md
@@ -0,0 +1,35 @@
+# Workspace drag and drop
+
+Cross-surface drag sessions use the foundation coordinator in
+`app/flowix-web/shared/drag-drop/drag-drop-coordinator.ts`. It owns one active
+session per WebView, registered drop targets, target priority, preview cleanup,
+Escape/window-blur cancellation, and a fresh target lookup on release. It has no
+feature imports and treats dragged items as opaque data.
+
+Sources create a `DragPayload<Item>` and call `beginDragSession`,
+`moveDragSession`, `endDragSession`, and `cancelDragSession`. Session IDs are
+independent of the input device so Pointer Events, editor drag events, and
+native file-drop adapters can use the same target contract.
+
+Targets register `hitTest`, `evaluate`, `onPreview`, `onDrop`, and `onError`
+handlers. `hitTest` returns a target-specific location, such as a calendar date
+or an editor insertion position. A higher-priority target wins when targets
+overlap; a rejected higher-priority target blocks lower-priority targets. The
+target owns resource validation and the business operation after release.
+
+Memo publishes file, folder, and note drag resource types from
+`features/memo/public/drag-resource-api.ts`. The file tree adapts its existing
+pointer gesture into a generic drag session. The calendar registers a target,
+accepts notes from its notebook when its date field is writable, previews the
+target date, and delegates persistence to the multidimensional-table feature.
+
+Future editor and table drop zones should register targets with this
+coordinator. Their source adapters can use the same session ID contract; the
+coordinator does not assume Pointer Events. Native file dragging still uses the
+existing Tauri external-file-drop router and can be migrated as a separate
+source adapter.
+
+Kanban card moves and notebook-note drops use the same Kanban target and resolve
+the lane plus insertion position through the coordinator. Reordering the lane
+headers remains its own gesture because it changes lane order rather than moving
+records between lanes.
diff --git a/docs/WORKSPACE-PREPARATION-DESIGN.md b/docs/WORKSPACE-PREPARATION-DESIGN.md
new file mode 100644
index 000000000..84c389b38
--- /dev/null
+++ b/docs/WORKSPACE-PREPARATION-DESIGN.md
@@ -0,0 +1,44 @@
+# 工作区准备与笔记本进入
+
+状态：首期调整已实施。保留现有启动屏障和导航事务；暂不抽取独立的通用准备模块。
+
+## 目标与边界
+
+启动继续分为两个阶段：阶段 1 保留版本首次执行一次的初始化门槛；阶段 2 每次启动准备当前工作区。普通笔记本切换和新建后进入继续使用自己的局部导航事务，不重新打开启动全屏 loading。
+
+当前阶段优先消除已经确认的重复请求与无效等待，并复用成熟的 `selectNotebook` 事务处理新建后的进入。卡片、文件夹和会话列表仍由各自 loader 加载。后台导入、模板设置和云同步继续使用各自的进度与错误状态。
+
+只有当首期实现后仍出现多处重复的准备规则，才考虑抽取共享模块。启动专属屏障、列表数据和导航事务仍各自保留在原有状态归属中。
+
+## 已实施
+
+- `getStartupListTask` 在没有选中笔记本或列表列隐藏时不注册列表等待；会话视图只在列表实际可见时等待。
+- `waitForStartupTask(null)` 立即结算为 ready；其余阶段 2 任务仍等待当前可见列表、初始文档和工作区表面。
+- 笔记本切换不再从导航事务直接调用 `loadNotes`。选择变化后由 `MemoListDataLoader` 或文件夹／会话 loader 负责唯一的数据请求；文件夹模式不额外加载卡片列表。
+- `selectNotebook` 接受显式的 `workColumnTarget` 策略。普通切换默认保留工作区目标，新建进入传 `clear`，在同一事务中保存旧文档、切换上下文、清空目标并提交。
+- 新建注册结果暂存于 hook 中。进入失败后使用相同输入重试会复用已注册的笔记本，避免重复创建。
+- 云端恢复可先注册而不切换原生上下文，再由同一个 `selectNotebook` 事务完成保存旧文档、激活和清空目标。命令默认仍激活，保持既有调用兼容。
+- 新建进入回滚时，前一个原生笔记本为空也会恢复为 null。
+
+## 入口规则
+
+| 入口 | 进入行为 | 后台工作 |
+| --- | --- | --- |
+| 启动 | 原生 ready、笔记本上下文、工作区恢复；等待当前可见首屏数据 | 版本首次初始化只由既有门槛控制 |
+| A→B | `selectNotebook(B)` 默认保留工作区目标；数据 loader 独立加载 B | 导入和同步不重新打开启动 loading |
+| 普通新建 | 注册后调用 `selectNotebook(created, { workColumnTarget: 'clear' })` | 普通导入／模板设置维持原有状态和重试 |
+| 首次创建 | onboarding 继续调用普通 `selectNotebook`，保留引导完成及导入启动顺序 | 导入完成不作为关闭引导的前置条件 |
+| 云端恢复 | 注册时不激活，再通过 `selectNotebook` 进入并清空旧目标 | 云同步独立运行，不启动普通导入或引导填充 |
+
+## 暂不做的扩展
+
+- 不把启动屏障改造成可供所有导航复用的任务框架，也不新增通用任务注册、取消和轮次系统。
+- 笔记本切换提交后，列表由现有 loader 展示其局部 loading 与错误；切换事务不等待列表完整首屏。若后续产品要求切换期间也等待完整首屏，再基于具体体验需求设计局部屏障。
+- 本轮不改造 onboarding 的事务和后台任务生命周期；它已复用 `selectNotebook`，其创建结果与引导持久化重试保持原样。
+
+## 关注点
+
+- 空列表是合法 ready；列表读取错误仍由列表自身呈现和重试。
+- 连续切换依赖现有导航 requestId 和原生笔记本转换锁。过期导航不得覆盖当前前端提交。
+- 如果新增首屏必需数据，应先确认它当前可见，再加入启动等待；隐藏列表、隐藏标签页、后续分页和后台内容生产不应阻塞阶段 2。
+- 如果普通新建进入失败，保留注册结果只用于同一组输入的重试；不同输入开始新建时丢弃旧缓存。
diff --git a/docs/WORKSPACE-SURFACE-ARCHITECTURE.md b/docs/WORKSPACE-SURFACE-ARCHITECTURE.md
new file mode 100644
index 000000000..b0c67db51
--- /dev/null
+++ b/docs/WORKSPACE-SURFACE-ARCHITECTURE.md
@@ -0,0 +1,120 @@
+# Workspace Surface 架构与打开协议
+
+## 目标与边界
+
+Work 与 Browser 是 workspace host：负责导航、布局、实例和焦点。它们把目标数据及视图上下文交给公共 surface 系统，不各自登记 renderer。`workspaceSurfaceRegistry` 是唯一 surface 能力与宿主支持声明；公共 renderer 表只按 `rendererId` 装载实现。具体 renderer 通过 render context 获取 host 差异。
+
+## 公共注册及宿主支持范围
+
+宿主范围来自 `features/workspace/surface-registry.ts`：
+
+| Surface | Work | Browser |
+| --- | --- | --- |
+| Markdown、代码、CSV、图片、视频、表格、媒体库、HTML、DOCX、不可预览文件 | ✓ | ✓ |
+| 媒体资源、Agent 对话、网页 | ✓ | ✓ |
+| 文件浏览器 | — | ✓ |
+| 思维导图、插件产物、插件工作台 | ✓ | — |
+
+表格和媒体库集合分别归入 `file-table`、`file-media-library`。打开文件夹时使用集合 surface；旧 `document-list` 已不再是 workspace surface。媒体库内部的照片列表是 renderer 内部视图，不另占 workspace surface。
+
+## 打开入口审计
+
+产品入口按来源分组如下。目标路由最终都应经过 `openWorkspaceSurface`；host adapter 再调用既有导航 use-case。下列组件和 use-case 当前已使用公共入口：
+
+| 来源 | 主要入口 |
+| --- | --- |
+| 笔记列表、搜索/最近内容、笔记链接与提及 | `memo-list.tsx`、`open-by-target.ts`、`open-notebook-note.ts`、编辑器 note-link / note-mention 扩展 |
+| 笔记本文件树、文件夹集合、访问文件 | `notebook-file-tree.tsx`、`notebook-folder-view.tsx`、`notebook-access-files-list.tsx`、`work-file-browser-view.tsx` |
+| 表格/媒体库引用和媒体墙 | `table-reference-node.tsx`、`media-library-reference-node.tsx`、`media-library-photo-wall.tsx` |
+| Agent 对话和消息内链接/附件 | 对话列表、任务区、搜索、状态栏、新建、fork、消息内链接/附件均通过 `openWorkspaceSurface`；Browser 仅由显式请求指定 |
+| 浏览器 tab 操作、网页和文件 | `browser-column.tsx`、`browser-column-registry.tsx`、Browser 文件 renderer |
+| 拖放、插件工作台及产物 | `external-file-drop-overlay.tsx`、`plugin-workbench.tsx`、`plugin-agent-workbench.tsx` |
+| 历史、恢复和应用级请求 | `document-navigation.ts`、启动恢复、main-window effects / business controller |
+
+导航 use-case 内部直接调用 `openBrowserColumnTarget`、`openExternalTarget`、`openCollectionTarget` 等属于 host adapter / 事务实现。Agent 产品入口统一调用 `openWorkspaceSurface`；协议内部保留 Agent hydration、恢复、选择状态和空草稿处理。恢复流程仍可在恢复边界调用 Agent 导航 helper。公共 Browser API 已移除按 surface 类型拆分的打开方法；`createFileBrowserTarget` 只负责构造目标数据。Browser tab 的“在 Work 打开”操作也已改为提交 Work surface 请求。未来新增产品入口应依赖 `open-surface-api.ts`，而不是依赖具体 host 导航函数。
+
+## 公共打开协议
+
+`openWorkspaceSurface(request)` 是 host-aware 的唯一通用打开入口：
+
+- 省略 `host` 或指定 `main-third` 时打开 Work；明确指定 `browser-column` 才打开 Browser。
+- 同一内容可分别拥有一个 Work view 和一个 Browser tab。Browser 内按内容身份复用 tab 并激活，不重复创建同内容 tab。
+- Work target 不接受 `empty`。清空是 workspace 状态变更，不是打开 surface。
+- 成功返回 `{ status: 'opened' | 'activated', host, location }`。
+- 被新导航取代或 Browser 保存屏障阻止时返回 `{ status: 'cancelled', host, reason: 'navigation-cancelled' }`。
+- 领域错误通过 Promise rejection 传递，不伪装成取消或成功。
+- Browser 底层 `alreadyOpen` 是 host adapter 的内部结果；公共调用方只看 `status` 与 `location`。
+
+Work adapter 会在导航完成后核对请求 identity 是否成为 Work 当前目标；若导航已经被较新的事务取代，则返回 cancelled。只有同一内容将同时挂载到两个 host 时，打开协议才会 flush 另一侧；Browser 打开无关 surface 不会提交 Work 的编辑；Work 更换内容时仍会保存即将离开的编辑器。Browser coordinator 在切换或替换 Browser tab 前执行当前 tab 的 flush；失败时返回取消，调用方保留现有 tab。编辑器保存/数据解析等实际错误继续 rejection。
+
+## Renderer presentation 与 lifecycle 覆盖
+
+下表按 renderer 代码盘点：静态 presentation 来自公共注册和 host target；“动态”指 renderer 向公共运行时通道发布信息。内部组件已有自己的加载/保存 UI，不代表它已接入公共 surface 状态或生命周期。
+
+| Surface | Presentation | Lifecycle / 编辑状态 |
+| --- | --- | --- |
+| Markdown | 静态标题/图标；DocumentContainer 发布真实读取 loading / error / ready；插件预览动态更新外观与能力 | DocumentContainer 注册 ready、flush、discard、focus、dispose |
+| Code | 静态标题/图标；DocumentContainer 发布真实读取 loading / error / ready | DocumentContainer 生命周期已注册 |
+| CSV | 动态发布文件名及读取 loading / error / ready；加载错误通过公共 retry action 重试。分隔符选择仍由 renderer 内联呈现；保存进度和冲突沿用 CSV actionable notice | 公共 flush 等待同一保存 Promise 及保存期间产生的新 revision；冲突/失败返回 false，草稿仍由 CSV 保留；不提供 discard |
+| Image / Video / Media | 动态发布文件名与 loading / error / ready / unsupported；错误提供 retry。图片在 DOM 解码完成后 ready，视频在授权并读取 metadata 后 ready | 只读，无编辑 lifecycle |
+| Table | 动态发布集合标题及 content loading / error / ready；错误支持重载，引用的 `table.id` 与当前文件不一致时发布 `unavailable/stale-context`。单元格、保存和集合操作反馈留在 TableDocumentView | 公共 flush 同时等待集合事务与单元格属性队列；事务失败、字段错误或 session 切换返回 false；不提供 discard |
+| Media library | 动态发布集合标题及 content loading / error / ready；错误支持重载。筛选、导入/删除及保存反馈留在 MediaLibraryView | 公共 flush 等待配置、重命名及导入/删除的完整事务，嵌套配置写入不提前释放屏障；失败返回 false；不提供 discard |
+| HTML | 预览 iframe 发布 loading / error / ready 与重试；源码视图发布 DocumentContainer 的读取状态 | DocumentContainer 生命周期已注册 |
+| DOCX | 动态发布标题、预览 loading / error / ready、重试与 reveal/convert 操作；转换进度、结果和警告通过公共 notices 发布 | 预览为只读；转换动作由组件管理 |
+| Unavailable | 动态发布标题、unsupported 状态和 reveal/default-app 操作；Browser 文件浏览器发布 MIME 解析状态，识别为代码时切换公共外观、能力和 ready 状态 | 识别为代码时使用 DocumentContainer lifecycle；其他 fallback 只读 |
+| File browser | 当前目录静态；活动文件后动态更新外观、能力和 loading / unavailable / ready | 文件内容 renderer 自行注册；目录外壳没有编辑 lifecycle |
+| Agent conversation | 动态发布 agent 图标、从 session store 派生的标题，以及 hydration loading / error / missing / ready；错误和 missing 提供重试 | 没有 workspace surface lifecycle；消息发送/草稿由 Agent 自身管理 |
+| Web | 静态外观；现在动态发布 hostname 标题、favicon、loading / error / ready 和重试动作 | 无编辑 lifecycle；Work 状态由 renderer 管理，Browser 导航状态由 tab runtime 管理 |
+| Mindmap / Plugin artifact | 插件产物加载时动态发布标题、状态和重试；注册提供默认外观/能力 | 只读渲染，无编辑 lifecycle |
+| Plugin workbench | 静态外观；插件生成中、生成失败和产物列表读取失败发布公共 notices；列表空态与刷新状态保留在组件内 | 无文档编辑 lifecycle |
+
+CSV、Table、Media library 已接入公共 flush；它们只承诺等待已经提交的编辑事务，不会自动提交尚未确认的配置表单草稿。三类没有可安全复用的 discard 实现，因此 Browser 关闭 API 在它们不支持 discard 时仍执行 flush，失败保留当前 tab。Work 与 Browser 都登记当前挂载 view；Work 保存入口查询 mounted view lifecycle，避免按文件类型重建 renderer 的实例 key。
+
+动态状态代码覆盖已补齐 Table / Media library 的 content loading、error、retry 和 ready。单元格校验、筛选/配置草稿及导入/删除反馈继续留在相应操作附近；它们不是缺少公共加载状态。Table / Media library 的保存进度和失败反馈仍由领域组件呈现，CSV 保存进度和冲突继续由现有 actionable notice 管理；只有产品需要在 tab 级汇总保存状态时，才应扩展通用 notice，而不能同时重复显示 toast、inline 提示和 surface notice。HTML iframe 的失败事件受浏览器行为限制，应用内错误覆盖需要实际桌面验收；HTML 与 Code 源码视图共用 DocumentContainer 的文件读取状态。插件工作台将产物列表加载提示留在列表区域，公共层接收列表读取失败和 Agent 插件运行状态。
+
+## 实施状态
+
+1. **公共模型与注册：已完成。** Surface kind、target、identity、宿主支持、能力、外观和状态由 workspace 公共模型定义；宿主只传目标与 context。
+2. **共享渲染链路：已完成。** `workspaceSurfaceRendererRegistry` 从公共 surface 注册生成 rendererId 映射；Work / Browser 共用 renderer 实现，差异通过 `WorkspaceSurfaceRenderContext` 提供。重型 renderer lazy load。
+3. **运行时展示与生命周期：代码覆盖已完成，集成验收待进行。** Markdown / Code 文档读取、表格、媒体库、HTML 预览、Browser 文件解析、插件产物、网页、媒体资源、DOCX、不可预览文件、Agent 对话和 CSV 均可发布其适用的动态 presentation；Markdown、Code、HTML、CSV、Table、Media library 注册公共 lifecycle。Table / Media library 的单元格和领域操作反馈、CSV 保存通知保持在现有操作上下文；表格引用身份变化已进入公共 unavailable 状态。需在桌面应用验证异步重试、HTML iframe 错误展示和各 renderer 的标题/ready 时序。
+4. **旧打开 API 收敛：产品入口已统一。** 功能层可见的按类型 Browser 打开方法、Work-column transfer 别名和 plugin-workbench 独立打开入口已移除；Agent Work 产品入口也统一使用 `openWorkspaceSurface`。Agent helper 仅由公共协议 adapter 和恢复边界调用。Browser tab 转到 Work 的动作仍有单独 transfer API，但内部提交同一公共打开协议。Browser adapter 的 `alreadyOpen` 只存在内部 use-case。旧持久化目标兼容仍保留在恢复边界。
+
+## 当前评估与优先级（2026-10-15）
+
+核心公共注册、共享 renderer 与默认 Work / 显式 Browser 的路由设计已落地；全量迁移与产品验收尚未完成。思维导图、插件产物和插件工作台目前只注册 Work 支持；通用协议不意味着每种 surface 已支持两个宿主。
+
+此前扩大回归记录：surface / workspace 与 CSV、媒体库、表格单元格队列相关测试共 36 个文件、170 项，166 通过、4 失败。集合导航 3 项失败与复用分支提前返回有关：pending 激活被拒绝后仍返回 existing，阻止新事务；已有集合直接复用也跳过类型变化和 unavailable 的重新检查。Agent 的旧测试预期已更新为默认 Work 行为；本次入口迁移后尚未重跑回归。最近一次 TypeScript 检查通过。依赖层检查仍有一个独立违规：`preferences/sections/environment-config.tsx` 直接导入 Tauri process 插件。
+
+建议按以下顺序收尾：
+
+1. 修复集合复用、并发请求和重新校验语义；重跑相关回归。
+2. 在实际应用中验收 Work / Browser 的长内容滚动、通知占位、同内容双开、保存失败阻止切换/关闭及异步重试。此前滚动修复用真实 Chromium 的独立布局复现验证，并非整个桌面应用端到端验证。
+3. 在桌面应用验收 Table / Media library 的 loading / error / retry 和重载行为；按领域保留单元格、配置表单和局部操作反馈。检查 CSV 通知与保存体验是否有重复提示。
+4. 完成 DOCX、视频、Agent 动态标题及失效请求的集成验证；核对声明能力与可执行操作；验证 HTML / Code / Plugin workbench 已发布的状态和重试操作。
+
+插件 Browser 支持是功能扩展，应在上述收尾之后单独实施。旧恢复数据兼容只在恢复边界保留，不为清理而移除。
+
+## Surface presentation 盘点维度
+
+共享 renderer 与状态容器必须保持有界的 flex 高度链：内容 slot 和 renderer wrapper 都使用 `flex flex-col flex-1 min-h-0 min-w-0 overflow-hidden`。通知占用布局高度，状态遮罩覆盖内容；加载/错误期间保留 renderer 的挂载身份。实际滚动由 renderer 内部的编辑器、表格或媒体视图负责，公共容器不新增滚动区域。新增包装层不得断开这个高度链，否则内部 `h-full` / `flex-1` 会失去约束而随内容扩展，Work 与 Browser 都会无法滚动。
+
+每个 renderer 的公共展示必须能表达：
+
+- 标题与图标（含异步解析后的更新）；
+- 标题栏样式、内容背景、加载/错误状态背景、空态装饰；
+- loading / empty / ready / unavailable / error 状态，以及可执行的恢复动作；
+- host、viewId、focused、readOnly 和 initialFocus；
+- capabilities 与 actions，且声明能力和实际可用操作一致；
+- 可编辑 surface 的 ready、flush、discard、focus 与 dispose 生命周期。
+
+静态默认值由公共注册给出；依赖实际文件、MIME、插件结果或编辑模式的信息由 renderer 通过按 `viewId` 隔离的 runtime presentation 发布。不要在 Work/Browser chrome 中按 surface kind 复制这些判断。
+
+## 验收要点与后续事项
+
+- 新增 surface 只在公共注册声明 rendererId、支持 host、能力和外观，并为数据定义公共 target；renderer implementation 表提供 rendererId 对应实现。
+- Work、Browser 不直接登记 renderer；两边同 kind 使用同一 renderer，差异通过 render context 表达。
+- 所有产品打开入口使用公共协议；内部导航 adapter 不泄漏给功能层。
+- opened 表示创建了 view，activated 表示复用了并聚焦已有 view，cancelled 表示请求未完成；错误始终 rejection。
+- 可编辑 renderer 的 flush 必须等待完整事务；不支持 discard 的 surface 不可跳过关闭前的 flush。
+- Table、Media library 已发布公共 content loading / error / retry / ready；单元格与局部操作反馈保留在领域 UI。桌面验收后再判断是否需要新增 surface notices 汇总保存状态，避免和现有提示重复。确认 HTML / Code / Plugin workbench 的异步错误与重试在 Work / Browser 两宿主表现一致。
+- 已增加媒体资源加载/失败重试/ready 与过期读取丢弃、CSV 加载失败及公共 retry action 的回归测试；本轮既有 CSV 保存/恢复、表格队列、媒体库复合事务和 host lifecycle 路由也有定向覆盖。类型检查与 diff 检查见实施汇报。
diff --git a/dsh-appserver/README.md b/dsh-appserver/README.md
index 09848bf27..0875634cd 100644
--- a/dsh-appserver/README.md
+++ b/dsh-appserver/README.md
@@ -137,6 +137,12 @@ Pending approval 是进程内状态，会在 SSE 重连时回放；持久化的
     stdio: true
 ```
 
+## Flowix 安装流程
+
+Flowix 启动时只检查本地 `dsh` 命令、Flowix 管理的 DSH Runtime，以及 `DSH_HOME/profiles/flowix` 中的 App Server profile；缺少任何一项都不会自动安装或弹窗。用户可以在 Flowix“偏好设置 → DeepSeek Harness”中打开 DSH 官方安装页面，安装后点“重新检查”。检测到 Runtime 但缺少 profile 时，用户点击“安装 DSH App Server 插件”。
+
+profile 安装到 `DSH_HOME/profiles/flowix`，其中包含 `dsh-appserver` bundle 和 Flowix Cordis patch。安装后 Flowix 启动该 profile 并通过 stdio JSON-RPC 握手；握手成功后 DSH Agent 才标记为 Ready。`DSH_HOME` 未设置时使用默认 `~/.dsh`。安装过程不会改写 DSH 默认 profile。
+
 ## 开发检查
 
 ```sh
diff --git a/dsh-appserver/test/runtime-llm.smoke.mjs b/dsh-appserver/test/runtime-llm.smoke.mjs
index 1b6c025c6..1ab8fa79c 100644
--- a/dsh-appserver/test/runtime-llm.smoke.mjs
+++ b/dsh-appserver/test/runtime-llm.smoke.mjs
@@ -10,7 +10,7 @@
 //   3. the approval decline loop — declining resolves to rejected and the
 //      command does not run
 //
-// The key is read at runtime from ~/.flowix/default.db and written only into
+// The key is read at runtime from ~/.flowix/db/default.db and written only into
 // the throwaway DSH home (mode 0600); it is never printed.
 import { prepareRuntimeTest, JsonlClient, check } from './runtime/host.mjs'
 
diff --git a/dsh-appserver/test/runtime/host.mjs b/dsh-appserver/test/runtime/host.mjs
index 8749820ac..e2b3febe2 100644
--- a/dsh-appserver/test/runtime/host.mjs
+++ b/dsh-appserver/test/runtime/host.mjs
@@ -58,7 +58,7 @@ async function baseEntries(runtimeRoot, { realLlm = false } = {}) {
  * Provision a real-model DSH home exactly the way a Flowix desktop harness
  * session does: provider routes come from the user's `~/.dsh/settings.yaml`
  * (env references only, no secrets), and the DeepSeek key is read from the
- * Flowix secret store (`~/.flowix/default.db`) into an isolated version-1
+ * Flowix secret store (`~/.flowix/db/default.db`) into an isolated version-1
  * credentials document. The key never appears in logs or process output.
  */
 async function provisionRealLlm(dshHome) {
@@ -67,10 +67,10 @@ async function provisionRealLlm(dshHome) {
   await copyFile(userSettings, join(dshHome, 'settings.yaml'))
 
   const { DatabaseSync } = await import('node:sqlite')
-  const secretDb = new DatabaseSync(join(process.env.HOME, '.flowix/default.db'), { readOnly: true })
+  const secretDb = new DatabaseSync(join(process.env.HOME, '.flowix/db/default.db'), { readOnly: true })
   const row = secretDb.prepare("SELECT value FROM secret_kv WHERE key = 'DeepSeek::default'").get()
   secretDb.close()
-  if (!row?.value) throw new Error("no DeepSeek key found in ~/.flowix/default.db (entry 'DeepSeek::default')")
+  if (!row?.value) throw new Error("no DeepSeek key found in ~/.flowix/db/default.db (entry 'DeepSeek::default')")
   const credentialsPath = join(dshHome, '.credentials.yaml')
   await writeFile(credentialsPath, `version: 1\nrefs:\n  FLOWIX_DSH_DEEPSEEK_API_KEY: ${row.value}\n`, { mode: 0o600 })
   await chmod(credentialsPath, 0o600)
diff --git a/package-lock.json b/package-lock.json
index d276463c2..ed1bf508b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "flowix",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "flowix",
-      "version": "1.5.6",
+      "version": "1.5.8",
       "dependencies": {
         "@base-ui/react": "^1.3.0",
         "@codemirror/commands": "^6.10.4",
diff --git a/package.json b/package.json
index 7a631045d..941c702fb 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "flowix",
   "private": true,
-  "version": "1.5.6",
+  "version": "1.5.8",
   "type": "module",
   "packageManager": "npm@10.8.2",
   "scripts": {
diff --git a/scripts/build-tauri-production.mjs b/scripts/build-tauri-production.mjs
index bf95b9e27..7e8b98c27 100644
--- a/scripts/build-tauri-production.mjs
+++ b/scripts/build-tauri-production.mjs
@@ -7,8 +7,13 @@ import { applyTauriSigningKey } from './resolve-tauri-signing-key.mjs'
 
 const repoRoot = path.resolve(import.meta.dirname, '..')
 // Pi is part of every production desktop package. Keep --with-pi accepted for
-// backwards compatibility, but do not require it for the normal build command.
-process.env.FLOWIX_BUNDLE_PI = '1'
+// backwards compatibility; it is no longer a product feature switch.
+delete process.env.FLOWIX_BUNDLE_PI
+// Production packages always target the production Cloud, regardless of the
+// caller's shell environment or any local development override.
+process.env.FLOWIX_CLOUD_ENVIRONMENT = 'prod'
+delete process.env.FLOWIX_CLOUD_API_BASE
+delete process.env.FLOWIX_DEV_MODE
 applyTauriSigningKey()
 const npmEntrypoint = process.env.npm_execpath
 const tauriEntrypoint = path.resolve(repoRoot, 'node_modules/@tauri-apps/cli/tauri.js')
@@ -95,13 +100,9 @@ if (targetPlatform === 'darwin') {
 }
 else npmRun('cli:build:prod')
 
-if (process.env.FLOWIX_BUNDLE_PI === '1') {
-  const piArgs = ['scripts/prepare-pi-bundle.mjs', '--platform', targetPlatform]
-  if (requestedArch) piArgs.push('--arch', requestedArch)
-  run(process.execPath, piArgs)
-} else {
-  run(process.execPath, ['scripts/prepare-pi-catalog.mjs'])
-}
+const piArgs = ['scripts/prepare-pi-bundle.mjs', '--platform', targetPlatform]
+if (requestedArch) piArgs.push('--arch', requestedArch)
+run(process.execPath, piArgs)
 
 const tauriTargets = targetPlatform === 'darwin'
   ? requestedArch
diff --git a/scripts/check-layer-boundaries.mjs b/scripts/check-layer-boundaries.mjs
index 99453dfb0..927907e8b 100644
--- a/scripts/check-layer-boundaries.mjs
+++ b/scripts/check-layer-boundaries.mjs
@@ -53,6 +53,14 @@ for (const file of files) {
   }
 
   for (const spec of specs) {
+    // Public surface models must remain usable without host stores or React renderers.
+    if (
+      !isTest(file)
+      && r.startsWith('features/workspace/model/')
+      && (/(?:^|\/)(?:store|use-cases|components)(?:\/|$)/.test(spec) || spec === 'react')
+    ) {
+      violations.push(`${r}: 公共 surface 模型不得依赖宿主状态或渲染实现 ${spec}`);
+    }
     // Rule A: 低层不得反向依赖 features / app
     if (isLowLayer(layer) && (spec.startsWith('@features/') || spec.startsWith('@app/'))) {
       violations.push(`${r}: 反向依赖 ${spec}  (低层 ${layer} 不得 import features/app)`);
@@ -72,6 +80,33 @@ for (const file of files) {
     ) {
       violations.push(`${r}: 跨模块依赖必须走公开入口，禁止 import ${spec}`);
     }
+    // Workspace host identity is a UI contract. Consumers may still use the
+    // focus store for reactive focus state, but must not import that Store
+    // module to name the host type.
+    if (
+      !isTest(file)
+      && !r.startsWith('features/workspace/')
+      && spec === '@features/workspace/store/workspace-focus-store'
+      && /\bWorkspaceHostId\b/.test(src)
+    ) {
+      violations.push(`${r}: WorkspaceHostId 必须从 host-api 公开类型入口导入`);
+    }
+    // The Editor's note-link extension opens Memo targets through Memo's
+    // stable navigation seam, not its implementation use case.
+    if (
+      !isTest(file)
+      && r.startsWith('features/editor/')
+      && spec === '@features/memo/use-cases/open-by-target'
+    ) {
+      violations.push(`${r}: 笔记导航必须走 Memo 公开入口`);
+    }
+    if (
+      !isTest(file)
+      && r.startsWith('features/agent/')
+      && spec === '@features/document/use-cases/heading-anchor-publish'
+    ) {
+      violations.push(`${r}: 文档标题导航必须走 Document 公开入口`);
+    }
     if (
       !isTest(file)
       && r.startsWith('app/main-window/')
diff --git a/scripts/check-web-bundle.mjs b/scripts/check-web-bundle.mjs
index 169809b73..3fa4ee32f 100644
--- a/scripts/check-web-bundle.mjs
+++ b/scripts/check-web-bundle.mjs
@@ -129,6 +129,22 @@ if (interFonts.some((name) => !name.endsWith('.woff2'))) {
   failures.push(`legacy Inter font formats emitted: ${interFonts.map(basename).join(', ')}`);
 }
 
+const markdownParserWorker = readdirSync(join(DIST, 'assets')).find((name) =>
+  /^markdown-parser\.worker-.+\.js$/.test(name),
+);
+if (!markdownParserWorker) {
+  failures.push('Markdown parser Worker bundle is missing');
+} else {
+  const parserWorkerPath = join(DIST, 'assets', markdownParserWorker);
+  const parserWorkerSource = readFileSync(parserWorkerPath, 'utf8');
+  if (statSync(parserWorkerPath).size > 700_000) {
+    failures.push(`Markdown parser Worker is ${statSync(parserWorkerPath).size} bytes, budget is 700000`);
+  }
+  if (/\blocalStorage\b/.test(parserWorkerSource)) {
+    failures.push('Markdown parser Worker includes browser storage code; keep feature stores out of its dependency graph');
+  }
+}
+
 if (failures.length) {
   console.error(`\n❌ Web bundle budget failed\n\n${failures.map((item) => `  ${item}`).join('\n')}\n`);
   process.exit(1);
diff --git a/scripts/prepare-tauri-production-config.mjs b/scripts/prepare-tauri-production-config.mjs
index 47de37288..306794e84 100644
--- a/scripts/prepare-tauri-production-config.mjs
+++ b/scripts/prepare-tauri-production-config.mjs
@@ -102,14 +102,70 @@ production.bundle.resources = {
   ...(production.bundle.resources && !Array.isArray(production.bundle.resources) ? production.bundle.resources : {}),
   [path.join(repoRoot, ".build", "pi-runtime", "provider-catalog.json")]: "pi/provider-catalog.json",
 };
-if (process.env.FLOWIX_BUNDLE_PI === "1") {
-  const piResources = JSON.parse(fs.readFileSync(path.join(repoRoot, ".build", "pi-runtime", "resources.json"), "utf8"));
-  const targetArch = process.env.FLOWIX_PI_TARGET_ARCH;
-  const selectedPiResources = Object.fromEntries(Object.entries(piResources).filter(([, target]) =>
-    !targetArch || target.endsWith(`-${targetArch}`),
-  ));
-  Object.assign(production.bundle.resources, selectedPiResources);
+
+// Ship the Flowix-owned DSH profile as an app resource. It is copied into the
+// user's selected DSH_HOME only after they explicitly install the App Server
+// plugin from Preferences.
+const dshProfileStage = path.join(repoRoot, ".build", "dsh-appserver-profile", "flowix");
+fs.rmSync(path.dirname(dshProfileStage), { recursive: true, force: true });
+fs.mkdirSync(path.join(dshProfileStage, "node_modules"), { recursive: true });
+fs.cpSync(path.join(repoRoot, "dsh-appserver"), path.join(dshProfileStage, "node_modules", "dsh-appserver"), {
+  recursive: true,
+  filter: (source) => !source.includes(`${path.sep}node_modules${path.sep}`),
+});
+fs.cpSync(path.join(repoRoot, "dsh-flowix-memory"), path.join(dshProfileStage, "node_modules", "dsh-flowix-memory"), {
+  recursive: true,
+  filter: (source) => !source.includes(`${path.sep}node_modules${path.sep}`),
+});
+fs.copyFileSync(
+  path.join(repoRoot, "scripts", "dsh-dev-profile.patch.yml"),
+  path.join(dshProfileStage, "cordis.patch.yml"),
+);
+fs.writeFileSync(path.join(dshProfileStage, "package.json"), `${JSON.stringify({
+  name: "dsh-profile-flowix",
+  private: true,
+  dsh: { profile: { bundles: ["@deepseek-ai/dsh-base", "dsh-appserver", "dsh-flowix-memory"] } },
+}, null, 2)}\n`);
+production.bundle.resources[dshProfileStage] = "dsh-profile/flowix";
+const piStageRoot = path.join(repoRoot, ".build", "pi-runtime");
+const providerCatalog = path.join(piStageRoot, "provider-catalog.json");
+if (!fs.existsSync(providerCatalog)) {
+  throw new Error("Pi provider catalog is missing. Run scripts/prepare-pi-bundle.mjs before generating the production config.");
+}
+const piResourcesPath = path.join(piStageRoot, "resources.json");
+if (!fs.existsSync(piResourcesPath)) {
+  throw new Error("Pi runtime resources are missing. Run scripts/prepare-pi-bundle.mjs before generating the production config.");
+}
+const piPlatform = { darwin: "darwin", win32: "windows", linux: "linux" }[targetPlatform];
+const nativePiPlatform = { darwin: "darwin", win32: "windows", linux: "linux" }[process.platform];
+const nativePiArch = { arm64: "arm64", x64: "x64" }[process.arch];
+const targetArch = process.env.FLOWIX_PI_TARGET_ARCH
+  || (nativePiPlatform === piPlatform ? nativePiArch : undefined);
+if (!targetArch || !["arm64", "x64"].includes(targetArch)) {
+  throw new Error(`Unsupported or missing Pi target architecture: ${targetArch ?? "<missing>"}`);
+}
+const piTarget = `pi/${piPlatform}-${targetArch}`;
+const piResources = JSON.parse(fs.readFileSync(piResourcesPath, "utf8"));
+const selectedPiResources = Object.entries(piResources).filter(([, target]) => target === piTarget);
+if (selectedPiResources.length !== 1) {
+  throw new Error(`Expected exactly one staged Pi runtime for ${piTarget}, found ${selectedPiResources.length}.`);
+}
+const [piResourceDirectory] = selectedPiResources[0];
+const piExecutable = path.join(piResourceDirectory, "dist", targetPlatform === "win32" ? "pi.exe" : "pi");
+const piExecutableFallback = path.join(piResourceDirectory, targetPlatform === "win32" ? "pi.exe" : "pi");
+const executablePath = [piExecutable, piExecutableFallback].find((candidate) => {
+  try {
+    if (!fs.statSync(candidate).isFile()) return false;
+    if (targetPlatform !== "win32") fs.accessSync(candidate, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+});
+if (!executablePath) {
+  throw new Error(`Staged Pi runtime for ${piTarget} is missing or not executable.`);
 }
+Object.assign(production.bundle.resources, Object.fromEntries(selectedPiResources));
 if (allowUnsigned) {
   // Local builds may omit updater artifacts; signed production Flowix builds
   // keep this enabled and require TAURI_SIGNING_PRIVATE_KEY.
diff --git a/scripts/register-macos-dev-app.mjs b/scripts/register-macos-dev-app.mjs
index d6011ad04..beeaad506 100644
--- a/scripts/register-macos-dev-app.mjs
+++ b/scripts/register-macos-dev-app.mjs
@@ -18,18 +18,20 @@ writeFileSync(path.join(contentsPath, 'Info.plist'), `<?xml version="1.0" encodi
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0"><dict>
 <key>CFBundleExecutable</key><string>flowix-desktop</string>
-<key>CFBundleIdentifier</key><string>com.flowix.app.dev</string>
+<key>CFBundleIdentifier</key><string>com.flowix-dev.app</string>
 <key>CFBundleName</key><string>Flowix Dev</string>
+<key>CFBundleDisplayName</key><string>Flowix Dev</string>
 <key>CFBundlePackageType</key><string>APPL</string>
 <key>CFBundleVersion</key><string>1</string>
 <key>CFBundleURLTypes</key><array><dict>
-<key>CFBundleURLName</key><string>com.flowix.app.dev.deeplink</string>
+<key>CFBundleURLName</key><string>com.flowix-dev.app.deeplink</string>
 <key>CFBundleTypeRole</key><string>Editor</string>
 <key>CFBundleURLSchemes</key><array><string>flowix-dev</string></array>
 </dict></array>
 </dict></plist>
 `)
 
+spawnSync(lsregister, ['-u', appPath], { stdio: 'ignore' })
 const result = spawnSync(lsregister, ['-f', '-R', appPath], { stdio: 'inherit' })
 if (result.error) throw result.error
 if (result.status !== 0) throw new Error(`Launch Services registration failed: ${result.status}`)
diff --git a/scripts/run-macos-dev-app.mjs b/scripts/run-macos-dev-app.mjs
new file mode 100755
index 000000000..f06d91225
--- /dev/null
+++ b/scripts/run-macos-dev-app.mjs
@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const appPath = path.join(repoRoot, '.build', 'macos-dev', 'Flowix Dev.app')
+const registerScript = path.join(repoRoot, 'scripts', 'register-macos-dev-app.mjs')
+const runnerArgs = process.argv.slice(2)
+const separator = runnerArgs.indexOf('--')
+const cargoArgs = separator < 0 ? runnerArgs : runnerArgs.slice(0, separator)
+const appArgs = separator < 0 ? [] : runnerArgs.slice(separator + 1)
+
+if (cargoArgs[0] !== 'run') throw new Error(`Unexpected Tauri runner arguments: ${runnerArgs.join(' ')}`)
+
+// Tauri's custom runner replaces `cargo run`; build the same target first,
+// then let Launch Services start the registered bundle around that binary.
+const build = spawnSync('cargo', ['build', ...cargoArgs.slice(1)], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+})
+if (build.error) throw build.error
+if (build.status !== 0) process.exit(build.status ?? 1)
+
+// Register the bundle before Launch Services starts it. The executable is a
+// symlink to Tauri's debug binary, but launching through the bundle gives the
+// running process the Dev bundle identity required for macOS app activation.
+const registration = spawnSync(process.execPath, [registerScript], {
+  cwd: repoRoot,
+  env: process.env,
+  stdio: 'inherit',
+})
+if (registration.error) throw registration.error
+if (registration.status !== 0) process.exit(registration.status ?? 1)
+
+const openArgs = ['-W', '-a', appPath]
+for (const name of ['FLOWIX_PI_PROVIDER_CATALOG']) {
+  const value = process.env[name]
+  if (value) openArgs.push('--env', `${name}=${value}`)
+}
+openArgs.push('--args', ...appArgs)
+
+const result = spawnSync('/usr/bin/open', openArgs, {
+  cwd: repoRoot,
+  env: process.env,
+  stdio: 'inherit',
+})
+if (result.error) throw result.error
+if (result.status !== 0) process.exit(result.status ?? 1)
diff --git a/scripts/tauri-dev.mjs b/scripts/tauri-dev.mjs
index e45721fb9..57bb7a58b 100644
--- a/scripts/tauri-dev.mjs
+++ b/scripts/tauri-dev.mjs
@@ -1,7 +1,7 @@
 import { spawn, spawnSync } from 'node:child_process'
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { delimiter, join, resolve } from 'node:path'
+import { delimiter, resolve } from 'node:path'
 
 const repoRoot = resolve(import.meta.dirname, '..')
 const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
@@ -9,10 +9,41 @@ const npmEntrypoint = process.env.npm_execpath
 const tauriEntrypoint = resolve(repoRoot, 'node_modules/@tauri-apps/cli/tauri.js')
 const args = process.argv.slice(2)
 const withPi = args.includes('--with-pi')
-const config = args.find(arg => arg !== '--with-pi') ?? 'app/flowix-desktop/tauri.conf.dev.json'
+const cloudEnvIndex = args.findIndex(arg => arg === '--cloud-env' || arg.startsWith('--cloud-env='))
+const hasCloudEnvFlag = cloudEnvIndex >= 0
+const cloudEnvValue = cloudEnvIndex < 0
+  ? undefined
+  : args[cloudEnvIndex] === '--cloud-env'
+    ? args[cloudEnvIndex + 1]
+    : args[cloudEnvIndex].slice('--cloud-env='.length)
+const configArgs = [...args]
+if (cloudEnvIndex >= 0) {
+  configArgs.splice(cloudEnvIndex, args[cloudEnvIndex] === '--cloud-env' ? 2 : 1)
+}
+const config = configArgs.find(arg => arg !== '--with-pi') ?? 'app/flowix-desktop/tauri.conf.dev.json'
 const childEnv = { ...process.env }
+// Pi is shipped by Flowix; do not let a shell override change the runtime.
+delete childEnv.PI_CLI_PATH
 childEnv.CARGO_TARGET_DIR ??= resolve(repoRoot, '.build/cargo-target')
-if (config.includes('.dev.')) childEnv.FLOWIX_DEV_MODE = '1'
+const devMode = config.includes('.dev.')
+if (devMode) childEnv.FLOWIX_DEV_MODE = '1'
+else delete childEnv.FLOWIX_DEV_MODE
+
+if (hasCloudEnvFlag && !['staging', 'prod'].includes(cloudEnvValue)) {
+  throw new Error(`Unsupported or missing --cloud-env value: ${cloudEnvValue ?? '<missing>'}. Use staging or prod.`)
+}
+if (hasCloudEnvFlag && !devMode) {
+  throw new Error('--cloud-env can only be used with a development Tauri config.')
+}
+if (process.env.FLOWIX_CLOUD_API_BASE) {
+  throw new Error('FLOWIX_CLOUD_API_BASE has been removed. Use --cloud-env=staging or --cloud-env=prod.')
+}
+if (devMode) {
+  childEnv.FLOWIX_CLOUD_ENVIRONMENT = cloudEnvValue ?? 'prod'
+} else {
+  childEnv.FLOWIX_CLOUD_ENVIRONMENT = 'prod'
+}
+console.log(`Cloud build default: ${childEnv.FLOWIX_CLOUD_ENVIRONMENT} (saved app preference takes precedence)`)
 
 // The dev config is an overlay on tauri.conf.json. Keep versions in the
 // overlay-free canonical files aligned so a stale app version fails early.
@@ -28,58 +59,15 @@ if (!packageVersion || packageVersion !== cargoVersion || packageVersion !== tau
   )
 }
 
-function findInstalledFlowixPi() {
-  if (childEnv.PI_CLI_PATH) return childEnv.PI_CLI_PATH
-
-  const platform = { darwin: 'darwin', win32: 'windows', linux: 'linux' }[process.platform]
-  if (!platform) return undefined
-  const arch = process.arch === 'arm64' ? 'arm64' : process.arch === 'x64' ? 'x64' : process.arch
-  const executable = process.platform === 'win32' ? 'pi.exe' : 'pi'
-  const appRoots = [childEnv.FLOWIX_PROD_APP_PATH]
-  if (process.platform === 'darwin') {
-    appRoots.push('/Applications/Flowix.app', join(homedir(), 'Applications', 'Flowix.app'))
-  } else if (process.platform === 'win32') {
-    appRoots.push(
-      childEnv.LOCALAPPDATA && join(childEnv.LOCALAPPDATA, 'Programs', 'Flowix'),
-      childEnv.ProgramFiles && join(childEnv.ProgramFiles, 'Flowix'),
-    )
-  } else {
-    appRoots.push('/opt/Flowix', '/usr/lib/flowix', '/usr/lib/Flowix')
-  }
-
-  for (const appRoot of appRoots.filter(Boolean)) {
-    const resourceRoots = process.platform === 'darwin'
-      ? [join(appRoot, 'Contents', 'Resources')]
-      : [join(appRoot, 'resources'), appRoot]
-    for (const resourceRoot of resourceRoots) {
-      for (const candidate of [
-        join(resourceRoot, 'pi', `${platform}-${arch}`, 'dist', executable),
-        join(resourceRoot, 'pi', `${platform}-${arch}`, executable),
-      ]) {
-        if (existsSync(candidate)) return candidate
-      }
-    }
-  }
-  return undefined
-}
-
 if (process.platform === 'win32') {
   // rustup installs Cargo here by default. GUI shells and automation often do
   // not inherit the updated user PATH until they are restarted.
-  const cargoBin = join(homedir(), '.cargo', 'bin')
+  const cargoBin = resolve(homedir(), '.cargo', 'bin')
   const pathKey = Object.keys(childEnv).find(key => key.toLowerCase() === 'path') ?? 'Path'
   childEnv[pathKey] = `${cargoBin}${delimiter}${childEnv[pathKey] ?? ''}`
 
 }
 
-if (!withPi) {
-  const installedPi = findInstalledFlowixPi()
-  if (installedPi) {
-    childEnv.PI_CLI_PATH = installedPi
-    console.log(`using Pi from installed Flowix: ${installedPi}`)
-  }
-}
-
 function run(command, args) {
   const result = spawnSync(command, args, {
     cwd: repoRoot,
@@ -100,24 +88,36 @@ function npmRun(script) {
 }
 
 npmRun('cli:build:dev')
-if (withPi) {
-  const piPlatform = { darwin: 'darwin', win32: 'windows', linux: 'linux' }[process.platform]
-  if (!piPlatform) throw new Error(`Pi v1.1.0 has no release for ${process.platform}`)
+const piPlatform = { darwin: 'darwin', win32: 'windows', linux: 'linux' }[process.platform]
+if (!piPlatform) throw new Error(`Pi v1.1.0 has no release for ${process.platform}`)
+const piArch = process.arch === 'arm64' ? 'arm64' : process.arch === 'x64' ? 'x64' : process.arch
+if (!['arm64', 'x64'].includes(piArch)) throw new Error(`Pi v1.1.0 has no release for ${process.platform}-${piArch}`)
+const piBinary = process.platform === 'win32' ? 'pi.exe' : 'pi'
+const piResourceDir = resolve(repoRoot, '.build', 'pi-runtime', 'resources', `${piPlatform}-${piArch}`)
+const stagedPiCandidates = [resolve(piResourceDir, 'dist', piBinary), resolve(piResourceDir, piBinary)]
+function hasStagedPi() {
+  return stagedPiCandidates.some(candidate => {
+    try {
+      if (!statSync(candidate).isFile()) return false
+      if (process.platform !== 'win32') accessSync(candidate, constants.X_OK)
+      return true
+    } catch {
+      return false
+    }
+  })
+}
+
+if (withPi || !hasStagedPi()) {
   run(process.execPath, [
     resolve(repoRoot, 'scripts/prepare-pi-bundle.mjs'),
     '--platform',
     process.platform,
     '--arch',
-    process.arch,
+    piArch,
   ])
-  const piArch = process.arch === 'arm64' ? 'arm64' : process.arch === 'x64' ? 'x64' : process.arch
-  const piBinary = process.platform === 'win32' ? 'pi.exe' : 'pi'
-  const piResourceDir = resolve(repoRoot, '.build', 'pi-runtime', 'resources', `${piPlatform}-${piArch}`)
-  childEnv.PI_CLI_PATH = [resolve(piResourceDir, 'dist', piBinary), resolve(piResourceDir, piBinary)]
-    .find(existsSync)
-  if (!childEnv.PI_CLI_PATH) throw new Error(`staged Pi executable was not found in ${piResourceDir}`)
-  console.log(`using bundled Pi v1.1.0 from ${childEnv.PI_CLI_PATH}`)
-} else {
+  if (!hasStagedPi()) throw new Error(`staged Pi executable was not found in ${piResourceDir}`)
+  console.log(`prepared bundled Pi v1.1.0 for ${piPlatform}-${piArch}`)
+} else if (!existsSync(resolve(repoRoot, '.build', 'pi-runtime', 'provider-catalog.json'))) {
   run(process.execPath, [resolve(repoRoot, 'scripts/prepare-pi-catalog.mjs')])
 }
 childEnv.FLOWIX_PI_PROVIDER_CATALOG = resolve(repoRoot, '.build', 'pi-runtime', 'provider-catalog.json')
@@ -135,34 +135,23 @@ function runTauriDev() {
     return
   }
 
-  const executable = resolve(childEnv.CARGO_TARGET_DIR, 'debug/flowix-desktop')
-  const previousMtime = existsSync(executable) ? statSync(executable).mtimeMs : 0
-  const registerScript = resolve(repoRoot, 'scripts/register-macos-dev-app.mjs')
-  const child = spawn(process.execPath, [tauriEntrypoint, 'dev', '--config', config], {
+  const runner = resolve(repoRoot, 'scripts/run-macos-dev-app.mjs')
+  const child = spawn(process.execPath, [
+    tauriEntrypoint,
+    'dev',
+    '--config',
+    config,
+    '--runner',
+    runner,
+  ], {
     cwd: repoRoot,
     env: childEnv,
     stdio: 'inherit',
   })
-  let registered = false
-  const check = setInterval(() => {
-    if (registered || !existsSync(executable)) return
-    if (statSync(executable).mtimeMs <= previousMtime && !existsSync(resolve(repoRoot, '.build/macos-dev/Flowix Dev.app/Contents/Info.plist'))) return
-    registered = true
-    const result = spawnSync(process.execPath, [registerScript], {
-      cwd: repoRoot,
-      env: childEnv,
-      stdio: 'inherit',
-    })
-    if (result.error || result.status !== 0) {
-      console.error('Flowix Dev deep-link registration failed; Google login callbacks may open another installed Flowix app.')
-    }
-  }, 500)
   child.on('error', (error) => {
-    clearInterval(check)
     throw error
   })
   child.on('exit', (code, signal) => {
-    clearInterval(check)
     if (signal) process.kill(process.pid, signal)
     else process.exitCode = code ?? 1
   })
diff --git a/vite.config.ts b/vite.config.ts
index 8c41b5562..17a22308d 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -70,6 +70,11 @@ export default defineConfig(({ command }) => {
     // public 閮藉湪鍚屼竴鐩綍, 閬垮厤 Tauri / Vite 璺緞浜掔浉绌胯秺銆?
     root: frontendRoot,
     publicDir: resolve(frontendRoot, "public"),
+    // Module workers need ES output so lazy Shiki grammars and WASM can stay
+    // in separate chunks instead of forcing every language into one bundle.
+    worker: {
+      format: "es",
+    },
     build: {
       outDir: resolve(__dirname, ".build/web-dist"),
       emptyOutDir: true,