feat: align local-first workspace direction

Document the VSCode-like local-first product shape, demote Convex to a control-plane role, and retire stale architecture drafts.

Add local workspace migration/export references plus smoke coverage for no-Convex managed workspace startup, local markdown title/body/options persistence, asset upload behavior, and Convex fixture export.

Verification: git diff --cached --check; node scripts/check-local-first-convex-guard.js --staged; node scripts/task444-convex-workspace-export-local-fixture-smoke.js; node scripts/task166-local-first-managed-workspace-no-convex-smoke.js; node scripts/task167-local-markdown-title-body-options-no-convex-smoke.js

ARCHITECTURE.md

@@ -1,8 +1,10 @@
 # MNOTE 当前架构梳理
 
-> 更新时间：2026-05-16
+> 更新时间：2026-05-19
 >
-> **当前阶段：初步 MVP 已达成。** 3000 下文档页完整读写链路（标题、正文、页面设置、Page Aggregate）、Sidebar/File Tree/Page Tree 三层树模型、tree command（`tree.*` preferred）、tree realtime SSE（snapshot/delta/resync）、页面 AI 快速编辑（fast-path < 1s，当前 `local_rule` planner 为过渡实现，长期方向为 markdown 级编辑，见 7-14）均已通过真实浏览器 smoke 验证。剩余工作集中在单一真源收口、live cache 统一、AI 编辑路径从块级收敛到 markdown 文本层，而非继续证明架构可行性。
+> 2026-05-19 口径更新：产品形态已切换为 local-first workspace；本地文件夹是默认数据真相，Convex / 服务端降级为账号、分享、同步、协作和 AI 隔离控制面。相关设计已完成并迁入 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md`。本地 Markdown 图片与附件上传已新增 `/api/local-folder/assets/upload`，页面内上传默认写入 `{mdBase}.assets/` 并保存相对 Markdown 路径，不再走 Convex media asset。
+>
+> **当前阶段：local-first MVP 骨架已达成。** 3000 下文档页、Sidebar/File Tree/Page Tree 三层树模型、tree command（`tree.*` preferred）、tree realtime WS 主链 / SSE fallback、本地 Markdown 上传、AI 会话本地化与 VSCode-like agent 运行口径均已建立。剩余工作集中在管理员目录授权、VSCode-like 冲突合并 UI、agent diff 审计、本地索引 / 分享 / 同步闭环，而不是继续扩张专用 page-ai fast-path 或 Convex 主存储链。
 
 本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。
 
@@ -17,21 +19,21 @@
 当前主线固定为：
 
 1. `tree-first graph kernel` 是长期对象真相层
-2. `Convex` 继续保留为当前自托管存储 / 实时 / 文件协作底座
+2. 本地文件夹是默认数据真相，Convex / 服务端退居账号、分享、同步、协作和 AI 隔离控制面
 3. `mnote-web` 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
 4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
 5. `BlockNote` 已退出文档页默认主路径，仅作为历史参考实现 / 对照材料保留
-6. 页面 AI 工具链已建立最小闭环：`POST /api/page-ai/block-edit-workflow` 提供快速编辑 route（当前 `local_rule` planner 为过渡态，长期方向为 `mnote.doc.markdown_edit` 文本级搜索替换，见 7-14）；Hermes tools（`mnote.doc.*` / `mnote.block.*`）承担复杂任务编排
+6. 页面 AI 当前最合理的长期形态是：MNote 只负责页面定位、白名单目录权限、agent runtime 管理、文件变更同步；Hermes / Reasonix 直接在授权工作区内编辑本地文件。`page_ai_workflow` 与 `mnote.doc.*` / `mnote.block.*` 保留为兼容 / cloud / 复杂结构辅助层，不再作为 local-first 普通正文编辑默认主路径
 
 一句话收口：
 
-> **Rust 持有语义主导权，Convex 保留底座，前端逐步从重壳转向消费稳定 projection 与少量交互 island。**
+> **Rust 持有语义主导权，本地文件夹是默认数据真相，Convex 只保留控制面与可选同步协作能力，前端逐步从重壳转向消费稳定 projection 与少量交互 island。**
 
 补充口径：
 
 > **主 Web 执行面当前以 `mnote-web` 为 3000 owner；Next App Router 只保留为 legacy compat、交互 island bundle source 与显式 debug/迁移辅助边界。**
 >
-> **页面 AI 块编辑当前以 fast-path `local_rule` planner（`/api/page-ai/block-edit-workflow`）为简单操作首选；Hermes agent（`mnote.doc.*` / `mnote.block.*` tools）保留为复杂任务编排器。**
+> **页面 AI 的 local-first 主路径应尽量贴近 VSCode：当前页面解析成真实 `.md` 文件，Hermes / Reasonix 在授权目录白名单内直接读写，tiptap 只消费后台文件变化后的最新投影。**
 
 ## 2. 当前主线目录
 
@@ -122,7 +124,7 @@
 
 ## 5. 当前编辑器与页面聚合关系
 
-当前文档页已经开始消费统一的前端侧 `PageAggregateProjection`，但仍不能说“页面域已完全统一成 Rust 单一真源”。
+当前文档页已经开始消费统一的 `PageAggregateProjection`，但仍不能说“页面域已完全统一成 Rust 单一真源”。
 
 当前真实状态是：
 
@@ -132,7 +134,7 @@
 - 正文默认由 `leptos-tiptap` island 编辑与保存
 - 页面设置已有一部分进入 island 运行时语义
 - `page_tree` / `pageSubtree` 已进入统一聚合入口
-- 页面/块 AI tools 已开始通过 Page Aggregate block projection 读取、定位、dry-run、替换、插入和受限移动块，并经 `page.body.save -> documents:updateContent` 持久化
+- 页面/块 AI tools 可通过 Page Aggregate block projection 读取、定位、dry-run、替换、插入和受限移动块；local-first 普通正文编辑不再要求走块工具，在线 / cloud / compat 场景才回到受控 mnote tool 写入。
 
 2026-05-16 更新：以下四项已通过真实 3000 browser smoke 验证（证据见 `tmp/page-aggregate-*` 目录）：
 
@@ -144,8 +146,8 @@
 仍未完成的关键点是：
 
 1. Rust 侧已提供最小 `Page Aggregate` snapshot 和 block projection v1，但当前 block projection 仍主要从 `documents.content` / local markdown content 投影（`projectionSource=documents.content`），不是 EditorBlockDocument 原生落库完成态
-2. 标题 / 正文 / 页面设置虽已收口到 `page.*` family 并通过 smoke，但客户端仍保留 `PageAggregateClientState` reducer（混合 server snapshot / draft title / local content），页面域单一真源仍未完全闭环
-3. AI 块工具最小闭环已启动且 fast-path < 1s，但 `scope=selection`、`format=page_xml/text`、多块插入、复杂块移动矩阵和持久审阅 UI 仍未完成
+2. 标题 / 正文 / 页面设置虽已收口到 `page.*` family 和 local-first 文件版本模型，但客户端仍保留 `PageAggregateClientState` reducer（混合 server snapshot / draft title / local content），页面域单一真源仍未完全闭环
+3. AI 块工具继续作为复杂结构辅助；local-first 普通 Markdown 编辑主路径已经转为“授权文件引用 + agent 原生 patch/diff + watcher 同步”
 4. Sidebar 仍通过 preferred snapshot（initial / query / tree_stream）做 freshness 选择，tree realtime live cache 未统一
 
 因此当前正确表述应是：
@@ -261,8 +263,10 @@ OnlyOffice 仍然是：
 - ✅ 标题单一真源 smoke 通过（`task110`）：页头/Breadcrumb/Sidebar/Page Tree/File Tree 一致
 - ✅ 正文写入后 `body.revision` / `blockDocument` 同步 smoke 通过
 - ✅ 页面设置写入后 `pageOptions` 同步与刷新持久化 smoke 通过
+- ✅ local-first `page.body.write` / `/api/page-body/write` 与 `expectedFileVersion` 已成为本地正文写入主入口，`/api/documents/save` 降级为 compat adapter
+- ✅ 本地 Markdown 图片 / 附件上传写入 sibling assets，并由真实浏览器 smoke 覆盖保存后刷新恢复
 - ✅ Convex 不可用时返回 degraded error，不返回伪 fixture
-- ⬜ block projection 从 EditorBlockDocument 原生落库（当前仍从 `documents.content` 投影）
+- ⬜ cloud / compat block projection 继续减少 `documents.content` 后备；local-first 正文真相已转为 `.md` 文件投影
 - ⬜ 客户端 `PageAggregateClientState` reducer 退役，页面域完全以 Rust snapshot 为单一运行时真相
 
 对应设计稿：
@@ -297,37 +301,39 @@ OnlyOffice 仍然是：
 
 目标：
 
-- 让 AI 读取、定位、dry-run 和精确块写入统一走 Rust Hermes tools、Page Aggregate block projection 与 `EditorCommand`
-- 把 `mnote.page.save` 固定为页面级兜底写入工具，不再代表长期精确块编辑主入口
-- 补齐 `scope=selection`、`format=page_xml/text`、多块插入、复杂块移动矩阵和持久审阅 UI
+- 让 local-first 页面 AI 默认走“页面定位 -> 授权文件引用 -> agent 原生 patch/diff -> 前台同步”
+- 把 `mnote.page.save` 固定为页面级兜底写入工具，不再代表普通正文编辑默认入口
+- 把 `mnote.doc.*` / `mnote.block.*` 收口为兼容 / cloud / 复杂结构辅助工具
+- 补齐 `scope=selection`、白名单目录权限、changed_files/diff 审计、前台同步刷新矩阵
 
-当前进度（2026-05-16，按 7-14 v2 更新）：
+当前进度（2026-05-19，按 `2-2` 完成态更新）：
 
-- ✅ 页面 AI 快速编辑 route 已上线：`POST /api/page-ai/block-edit-workflow`
-- ✅ 简单编辑本地 planner（`local_rule`）已验证：788ms（过渡实现，将被 `markdown_edit` 替代）
-- ✅ Hermes tools（`mnote.doc.*` / `mnote.block.*`）已可读取和写入块投影
-- ✅ 参考实现已确认两层模型可行性：CLI Main（Lark Doc）`str_replace` 对应 `markdown_edit`，`block_*` 对应 `apply_block_ops`
-- ⬜ **Phase A（当前唯一活跃实施）**：`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强（search/replace + `format: "markdown"` + local source + Hermes 注册）
-- ⬜ **Phase B（下一阶段）**：退役 `direct_block_edit_operations`，`page_ai_workflow.rs` 改走 `markdown_edit`，system prompt 产 search/replace 对
-- ⬜ `scope=selection`、`format=page_xml/text` 稳定输出
-- ⬜ tool manifest annotations（`readonly` / `destructive` / `requiresApproval` 等）
+- ✅ 页面 AI 与 ACP runtime 已能承载本地优先方向
+- ✅ `page_ai_workflow` 已在 local source 下退出主路径
+- ✅ Hermes tools（`mnote.doc.*` / `mnote.block.*`）已可作为兼容 / cloud / 复杂结构辅助层读取和写入
+- ✅ 本地优先设计已经收口为 VSCode-like 运行模型：页面定位 + 白名单目录 + agent 直改文件 + tiptap 同步显示
+- ✅ 页面 AI 默认输入已收口到 `currentFile + selection + allowedRoots / aiAccessScope`
+- ✅ Hermes / Reasonix runtime 已显式带白名单目录运行
+- ⬜ MNote 回收 changed_files / diff 审计
+- ⬜ `scope=selection`、`format=page_xml/text` 继续作为结构化辅助输出，不作为普通 Markdown 编辑必需路径
+- ⬜ tool manifest annotations 继续补齐 destructive / requiresApproval 等高级语义
 - ⬜ **Phase C（设计冻结，不实施）**：`StreamApplyController` + `ReviewSession` + `GhostTextOverlay`（流式 apply + suggest/review）
 - ⬜ stale revision / idempotency 重放保护（已有 revision 乐观锁覆盖，补端到端 smoke）
 
-关键原则（2026-05-16 补充，按 7-14 v2 更新）：
+关键原则（2026-05-18 口径更新）：
 
-- **两层操作模型**（参考 CLI Main Lark Doc）：文本级 `mnote.doc.markdown_edit`（str_replace）为主路径（覆盖 80%+ 场景），块级 `mnote.doc.apply_block_ops` 为结构性辅助（< 20%）
-- AI 编辑主路径应从块级降维到 markdown 文本层：新增 `mnote.doc.markdown_edit`（search/replace 或 full_content）作为主要 AI 写入工具
+- **local-first 主路径**：当前页面解析成授权 `.md` 文件，Hermes / Reasonix 在白名单目录内直接读写，MNote 负责权限、审计和前台同步
+- **兼容两层模型**（参考 CLI Main Lark Doc）：`mnote.doc.markdown_edit` 作为文本级兼容 / fallback，`mnote.doc.apply_block_ops` 作为块级结构性辅助；local-first 正常编辑优先走“授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”
 - `mnote.block.*` 降级为结构性辅助（拖拽排序、精确块删除等），不删除
-- 当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应退役并替换为模型产出 search/replace 对
-- 在线 Convex 文档和本地 `.md` 文件共用同一条 markdown AI 写入路径（`resolve_source` → Convex | LocalFS）
+- 当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应继续退役
+- cloud / remote agent 无法直接访问本地文件时，才回到 `resolve_source` → Convex | LocalFS 的受控代理写入
 - Markdown 既是 AI 编辑格式也是人类可读格式，不需要 XML 中间层
 - 流式 apply + suggest/review（参考 BlockNote AI 的 `StreamToolExecutor` + `suggestChanges`）仅作为 Phase C 设计冻结，当前不实施
 
 对应设计稿：
 
 - `/mnt/Data1T/mnote/design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`
-- `/mnt/Data1T/mnote/design/10-review/process/09-page-ai-fast-block-edit-runtime-review.md`
+- `/mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md`
 - `/mnt/Data1T/mnote/design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md`
 
 ### 8.5 定向 Bug Hunt 与质量基线
@@ -364,7 +370,8 @@ OnlyOffice 仍然是：
 - “当前最优先是先做树域 UI 重构”
 - “Rust Web 还只是实验，没有接真实页面链路”
 - “页面 AI 编辑必须经过 Hermes agent，没有快路径”
+- “页面 AI 编辑必须经过 MNote 专用工具才能改普通 Markdown”
 
 当前真正的卡点已经从“能不能跑”变成：
 
-> **单一真源如何收口（Page Aggregate ClientState → Rust snapshot），projection / command / realtime 三条链如何从兼容态进入正式主链，以及 AI 块编辑如何从“能写”变成产品级可靠（selection、review、conflict、idempotency）。**
+> **管理员目录授权、文件版本冲突合并、agent diff 审计、本地索引 / 分享 / 同步如何产品化；Page Aggregate ClientState、projection / command / realtime 兼容链如何继续瘦身。**