noteconnection 1.6.8 → 1.8.0

package/dist/src/frontend/README.md

@@ -1,4 +1,4 @@
-# 2026-03-24 v1.6.0
+# 2026-04-07 v1.7.0
 
 # NoteConnection Knowledge Graph
 
@@ -27,6 +27,99 @@ Unlike traditional "network" views that show a messy web of links, NoteConnectio
 
 ---
 
+## Current Mainline Architecture Status (2026-07-03)
+
+### English
+
+- The Mermaid fallback failure class reported through the Node-side renderer is now closed at the correct owners: `src/notemd/MermaidProcessor.ts` and `src/reader_renderer.ts` both normalize malformed quoted bracketed-node labels per line before parse/render. `PathBridge` remains transport-only.
+- Guided Learning no longer pays repeated full hosted `Graph` / `PathEngine` reconstruction for the same graph snapshot. `src/frontend/workspace_panes.js` now reuses the hosted Future Path runtime by source-graph signature while keeping the pending-pane behavior in `src/frontend/agent_workspace.js`.
+- Hosted Future Path runtime reuse now has a narrower owner: `src/frontend/hosted_future_path_runtime.js` holds signature-based cache identity plus cold/hot-path diagnostics, and `workspace_panes.js` now consumes that owner instead of holding the cache logic inline.
+- Guided Learning first-open behavior is now two-stage: when local graph state is already available, the pending pane can render an immediate hosted Future Path projection before `/api/knowledge/path` returns, and identical in-flight Learning Path requests are deduped by normalized payload.
+- Knowledge Workspace public answers now consume bounded DAG context on the main answer path instead of collapsing to only the first top-hit sentence. `src/learning/graphContextAssembler.ts` now emits `anchorGraphProfile`, and `conversationComposer.ts` plus `answerReleaseReview.ts` use bounded path and degree context while keeping the public answer contracted.
+- The local design references under `ref/enterprise_agent_platform` and `ref/codex` now reinforce the current owner split: runtime/retrieval/memory/release-review stay local, and model-visible context stays bounded and additive.
+- Compared with the 2026-05-25 through 2026-06-18 plan chain, the missing gap is no longer whether DAG context reaches the public answer path. The remaining gap is calibration and architecture concentration inside a few oversized owners.
+- Current architecture pressure is still concentrated in `src/server.ts` (~15850 lines), `src/learning/KnowledgeLearningPlatform.ts` (~11200), `src/frontend/workspace_panes.js` (~9289), `src/frontend/agent_workspace.js` (~4882), and `src/learning/answerReleaseReview.ts` (~4261). The next step is narrower extraction around real invariants, not another framework import pass.
+- Current code-vs-plan details are tracked in [Agent Knowledge Workspace Graph Preview and Review Closure (2026-06-20)](docs/solutions/agent-knowledge-workspace-graph-preview-and-review-closure-2026-06-20.md) and the [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
+
+### 中文
+
+- 通过 Node 侧 renderer 暴露出来的 Mermaid 回退失败类现在已经在正确 owner 处关闭：`src/notemd/MermaidProcessor.ts` 与 `src/reader_renderer.ts` 现在都会在解析/渲染前按行归一化畸形带引号 bracketed-node label；`PathBridge` 继续只做 transport。
+- Guided Learning 对同一图快照不再重复支付完整托管 `Graph` / `PathEngine` 重建成本。`src/frontend/workspace_panes.js` 现在会按 source-graph signature 复用 hosted Future Path runtime，同时保留 `src/frontend/agent_workspace.js` 中已有的 pending-pane 行为。
+- Hosted Future Path runtime 复用现在也有了更窄的 owner：`src/frontend/hosted_future_path_runtime.js` 持有按签名复用的 cache identity 与冷/热路径诊断，`workspace_panes.js` 不再内联持有整套 cache 逻辑。
+- Guided Learning 首开现在也变成了两阶段行为：只要本地图状态已可用，pending pane 就能在 `/api/knowledge/path` 返回前先渲染 hosted Future Path 投影，而且相同的在途 Learning Path 请求会按归一化 payload 去重。
+- Knowledge Workspace 的公开回答现在已经在主回答路径消费有界 DAG context，而不再只退化成首条 top-hit 句子。`src/learning/graphContextAssembler.ts` 现在会发射 `anchorGraphProfile`，`conversationComposer.ts` 与 `answerReleaseReview.ts` 会在保持回答收缩的前提下使用 bounded path / degree context。
+- 本地 `ref/enterprise_agent_platform` 与 `ref/codex` 设计参考现在进一步支撑当前 owner 切分：runtime / retrieval / memory / release-review 继续留在本地运行时，model-visible context 继续保持 bounded + additive。
+- 相对 2026-05-25 到 2026-06-18 的方案链，当前缺口已经不再是“DAG context 有没有真正进入公开回答路径”。剩余缺口主要是回答校准，以及少数大 owner 内的架构集中度。
+- 当前架构压力仍集中在 `src/server.ts`（约 `15850` 行）、`src/learning/KnowledgeLearningPlatform.ts`（约 `11200` 行）、`src/frontend/workspace_panes.js`（约 `9289` 行）、`src/frontend/agent_workspace.js`（约 `4882` 行）与 `src/learning/answerReleaseReview.ts`（约 `4261` 行）。下一步应该围绕真实不变量做窄提取，而不是再做一轮框架导入。
+- 当前代码 / 方案对齐详情见 [Agent 知识工作区图预览与回答审核收口（2026-06-20）](docs/solutions/agent-knowledge-workspace-graph-preview-and-review-closure-2026-06-20.md) 与 [开发进度看板](docs/diataxis/zh/explanation/development-progress-dashboard.md)。
+
+---
+
+## Current Mainline Architecture Status (2026-06-24)
+
+### English
+
+- The Agent Knowledge Workspace closure now combines three mainline owners: bounded DAG context assembly, deterministic final-answer release review, and right-pane graph/source projections.
+- Public answers remain contracted to the reviewed answer path; citations, graph context, reviewer details, provenance diagnostics, and developer traces belong to secondary panes, artifacts, traces, or exports.
+- Matched-file discoverability is now intentionally compact: users get a question-mark help affordance for "left-click opens source and highlights the basis" instead of permanent instructional text in the workspace.
+- The matched-file/source-focus path is now right-pane-first: source clicks resolve candidate paths, render Markdown, highlight matched evidence, and expose close controls for the affected right-pane surfaces.
+- `Related Focus` is implemented as a side-pane Focus-mode host backed by the main graph projection contract and the shared double-click decision contract; it switches anchors and opens Markdown inside the pane without moving the main graph DOM or calling the global reader, and the hosted view intentionally omits the main toolbar frame, visible edge layer, and dense background context dots. `Learning Path` hosts the Godot Future Path `diffusion/core/treeLayout` contract, inherits matching Path-mode expansion/collapse/completion state when the live target matches, and routes DOM input through TreeRenderer-style spine-only signals, including right-click prerequisite collapse for the selected node.
+- The hosted `Related Focus` viewport now has pane-local wheel zoom, icon reset, and icon focus-history controls; these controls are intentionally scoped to the right-side Knowledge Focus pane and do not mutate the Tauri main graph runtime.
+- The hosted `Learning Path` Future Path surface now routes node double-click to the same pane-local Markdown reader used by Knowledge Focus, so opening concrete node text stays inside the Guided Learning pane instead of delegating to the global reader.
+- The current implementation uses resolved graph labels such as `water glass`, not internal atom IDs, for the knowledge graph preview surface. This behavior is pinned by strict browser verification.
+- Current code-vs-plan details are tracked in [Agent Knowledge Workspace Graph Preview and Review Closure (2026-06-20)](docs/solutions/agent-knowledge-workspace-graph-preview-and-review-closure-2026-06-20.md) and the [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
+
+### 中文
+
+- Agent Knowledge Workspace 本轮收口现在合并了三类主线 owner：有界 DAG context assembly、确定性最终回答 release review，以及右侧 graph/source projection。
+- 公开回答继续收缩到经过审核的回答路径；citation、graph context、reviewer detail、provenance diagnostics 与 developer trace 进入次级 pane、artifact、trace 或 export。
+- 命中文件可发现性现在刻意保持克制：用户通过问号帮助入口了解“左键打开源文档并高亮依据”，而不是在 workspace 中常驻说明文案。
+- 命中文件 / source-focus 路径现在以右侧 pane 为权威阅读面：单击后解析候选路径、渲染 Markdown、高亮命中依据，并在受影响的右侧 pane surface 上提供关闭控件。
+- `关联聚焦` 已实现为右侧 pane 内托管的 Focus-mode：复用主图投影契约与共享双击决策契约，在 pane 内切换 anchor 或打开 Markdown，不移动主图 DOM，也不调用全局 reader；托管视图刻意不显示主界面的工具框、可见边线与密集灰色背景 context 点。`学习路径` 托管 Godot Future Path 的 `diffusion/core/treeLayout` 契约；当主 Path mode 当前 target 匹配时，会继承其 expansion/collapse/completion 状态包，并将 DOM 输入路由为 TreeRenderer 风格的 spine-only 信号，包括对选中主干节点的右键 prerequisite 收起。
+- 托管 `关联聚焦` viewport 现在具备 pane-local 滚轮缩放、图标式 reset 与图标式 focus history 控件；这些控制只作用于右侧知识聚焦 pane，不会修改 Tauri 主图运行时。
+- 托管 `学习路径` Future Path surface 现在把节点双击路由到与知识聚焦相同的 pane-local Markdown reader，因此打开具体节点文本会留在引导式学习 pane 内，而不是委托给全局 reader。
+- 当前实现使用 `water glass` 这类解析后的图标签，而不是内部 atom ID，作为知识图预览展示名称；该行为已由 strict browser verification 固定。
+- 当前代码 / 方案对齐详情见 [Agent 知识工作区图预览与回答审核收口（2026-06-20）](docs/solutions/agent-knowledge-workspace-graph-preview-and-review-closure-2026-06-20.md) 与 [开发进度看板](docs/diataxis/zh/explanation/development-progress-dashboard.md)。
+
+---
+
+## Current Mainline Architecture Status (2026-06-17)
+
+### English
+
+- The current DAG clarification is now explicit: "graph structure" means this project's existing DAG-shaped `KnowledgeAtom` / `RelationEdge` / `TemporalEdge` substrate, not a generic graph database integration target.
+- The 2026-06-17 agent-knowledge slice now includes a first-class graph-conditioned context assembly step: `src/learning/graphContextAssembler.ts` selects the anchor, reorders support nodes, attaches explicit store-backed `connectionPaths`, builds bounded predecessor/successor windows, records evidence refs/diagnostics, and still preserves legacy `assistantMessage` compatibility.
+- Persistence is guarded for this slice: before auto-saving a rebuilt learning snapshot, `KnowledgeLearningPlatform` merges still-valid store-side relation/temporal edges into the new snapshot so read-side query/conversation flows do not erase externally enriched DAG edges before path enrichment can inspect them.
+- The next architecture move is no longer extracting the assembler itself; it is expanding graph-aware ranking features beyond relation-degree bonuses, hardening right-pane diagnostics, and adding graph-specific quality gates on top of the new bounded context pack.
+- The public answer contract is now enforced in the current composer path: `answer` / `directAnswer` stays to the targeted response, while citations, connection paths, temporal details, durable artifacts, and developer traces belong in the evidence pane or export payload unless the user explicitly asks to inspect them.
+- The prior DSPy / Guidance / Semantic Kernel / LangChain Core / LiteLLM review is retained as design input only. The main runtime should stay TypeScript-native and use local graph store operations instead of importing Python prompt frameworks into the Tauri/Node path.
+- Current code-vs-plan details are tracked in [Agent Knowledge DAG Answer Contract Plan (2026-06-17)](docs/solutions/agent-knowledge-dag-answer-contract-plan-2026-06-17.md), [Knowledge Workspace and DAG Alignment Plan (2026-06-10)](docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md), and the [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
+
+### 中文
+
+- 当前已明确：这里的“图结构”指本项目现有 DAG 形态的 `KnowledgeAtom` / `RelationEdge` / `TemporalEdge` 底座，不是泛化的图数据库接入目标。
+- 2026-06-17 agent knowledge 切片现在已经包含一等 graph-conditioned context assembly 步骤：`src/learning/graphContextAssembler.ts` 会在回答合成前选择 anchor、重排 support node、挂接 store 支撑的显式 `connectionPaths`、构建有界 predecessor/successor window，并记录 evidence ref / diagnostics，同时保持 legacy `assistantMessage` 兼容。
+- 当前切片也补了持久化保护：`KnowledgeLearningPlatform` 在自动保存重建后的 learning snapshot 前，会把仍然有效的 store 侧 relation/temporal edges 合并回新快照，避免 read-side query/conversation 流程在路径增强读取前抹掉外部增强的 DAG 边。
+- 下一步正确的架构动作已经不再是“把 assembler 抽出来”，而是基于新的 bounded context pack 继续扩展 graph-aware ranking feature、右侧原文诊断以及图专项质量门禁。
+- 公开回答契约已在当前 composer 路径中强制收缩：`answer` / `directAnswer` 只保留 targeted response；citation、connection path、temporal detail、durable artifact 与 developer trace 默认进入 evidence pane 或 export payload，除非用户显式要求查看。
+- 先前对 DSPy / Guidance / Semantic Kernel / LangChain Core / LiteLLM 的研究继续作为设计输入，不作为运行时依赖引入。主运行时应保持 TypeScript-native，并优先使用本地图 store operations。
+- 当前代码 / 方案对齐详情见 [Agent Knowledge DAG Answer Contract Plan (2026-06-17)](docs/solutions/agent-knowledge-dag-answer-contract-plan-2026-06-17.md)、[Knowledge Workspace and DAG Alignment Plan (2026-06-10)](docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md) 与 [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md)。
+
+---
+
+## Current Mainline Architecture Status (2026-06-10)
+
+- The current `main` branch has code-backed scoped retrieval, grounded conversation, durable resource/index/workspace/session/memory/export substrate, explicit export profiles, and PNG-first Godot/mobile render materialization.
+- The Knowledge Workspace now includes an in-pane scope switcher, a compact `/api/knowledge/conversation` status strip, grouped file-first knowledge hits, source-markdown rendering with matched-span highlighting in the focus pane, and durable workflow artifacts for `flashcard_batch` and `knowledge_run`.
+- Agent conversation runtime is no longer limited to one flat string: `answer`, `assistantBlocks`, `knowledgeRun`, grouped knowledge points, citations, memory actions, and trace are all present while legacy `assistantMessage` remains valid.
+- The current DAG-backed learning substrate is real: `KnowledgeAtom`, `RelationEdge`, `TemporalEdge`, path queries, mastery-path/session logic, and `KnowledgeQueryItem.relationPath` already exist. The remaining gap is not “having a graph,” but letting answer planning consume it through a dedicated graph-conditioned context layer.
+- graphdb/sqlite and ANN/external connector paths remain operational baselines, not production-closed claims. Release closure still depends on repeated soak evidence, workload thresholds, recall/latency calibration, strict rollout proof, and multi-host evidence.
+- `npm run verify:foundation:release-evidence` audits the latest sqlite soak and ANN release-gate reports for freshness and passing gates before host evidence is used as release context; `npm run verify:foundation:release-evidence:strict` requires repeated fresh valid history and is exposed in foundation readiness as `foundation_release_evidence_history`; `npm run verify:foundation:release-evidence:multi-host` is available for release windows that require host diversity.
+- The current architecture pressure remains ownership reduction: `src/server.ts`, `src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/agent_workspace.js`, and `src/frontend/workspace_panes.js` remain the main simplification targets.
+- Current code-vs-plan details are tracked in [Knowledge Workspace and DAG Alignment Plan (2026-06-10)](docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md), [Architecture Progress Alignment and Mainline Plan (2026-06-06)](docs/solutions/architecture-progress-alignment-2026-06-06.md), and the [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
+
+---
+
 <a id="key-features-en"></a>
 
 ## 🚀 Key Features
@@ -127,6 +220,16 @@ NoteConnection is built on a modular architecture designed for performance and e
 
 ## 📦 Quick Start
 
+### Desktop System Dependencies
+
+| Platform | Required Dependencies |
+|---|---|
+| **Linux** | `libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `libsoup3.0`, `libjavascriptcoregtk-4.1-0` (Ubuntu/Debian: `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev patchelf`) |
+| **macOS** | No additional dependencies (system WebKit included) |
+| **Windows** | [Edge WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/) (pre-installed on Windows 11; Windows 10 may need manual install) |
+
+> **Linux Wayland users**: Godot Path Mode requires `GDK_BACKEND=x11` on pure Wayland compositors. The launcher sets this automatically when `XDG_SESSION_TYPE=wayland` is detected.
+
 ### Option 1: Windows Installer (Recommended)
 
 1. Download `NoteConnection.Setup.exe` from the [Latest Releases](https://github.com/Jacobinwwey/NoteConnection/releases).
@@ -161,42 +264,36 @@ npm start
 
 ### Option 5: Mobile Support (Android)
 
-NoteConnection now supports **two Android generation paths**:
-
-1. **Capacitor APK path** (web-asset runtime, stable for reader/visualization workflows).
-2. **Tauri Android path** (native shell pipeline aligned with `docs/tauri_brainstorming.md`).
+NoteConnection supports Android via **Tauri Android** (native shell pipeline). The Capacitor APK path is **deprecated** and retained for historical reference only.
 
 #### Prerequisites
 
 - **Node.js** (LTS)
-- **Java JDK** (17 or higher)
+- **Java JDK** (21 or higher)
 - **Android SDK** (Configured in `ANDROID_HOME` or via Android Studio)
 
-#### Method A: Capacitor Build (Stable)
+#### Recommended: Tauri Android Build (Native Shell)
 
-Simply run the included batch script on Windows:
-
-```cmd
-build_apk.bat
-```
+```bash
+# First-time setup
+npm run tauri:android:init
 
-This script automatically:
+# Development build
+npm run tauri:android:dev
 
-1. Checks your environment (Node, Java, Android SDK).
-2. Installs dependencies.
-3. Builds web assets.
-4. Syncs with Capacitor.
-5. Compiles the APK using Gradle.
+# Release APK/AAB
+npm run tauri:android:build
+```
 
-You can also trigger the same pipeline through npm:
+For universal APK (armeabi-v7a + arm64-v8a + x86_64):
 
 ```bash
-npm run mobile:build:capacitor
+npm run tauri:android:build:universal
 ```
 
-#### Method B: Tauri Android Build (Native Shell)
+#### Deprecated: Capacitor Build
 
-```bash
+The Capacitor APK path (`build_apk.bat`, `npm run mobile:build:capacitor`) is deprecated as of 2026-05. The `android/` Capacitor project directory is retained for historical reference. All active Android development targets the Tauri Android pipeline.
 # First-time setup on the machine
 npm run tauri:android:init
 
@@ -224,8 +321,8 @@ npm run tauri:android:build
 
 #### Mobile Capability Boundary
 
-- Capacitor path currently packages web assets and does not embed the local Node sidecar workflow (`/api/build`, `/api/folders`, `/api/content`).
-- Tauri Android path is provided as the native-shell migration route and should be used when mobile-side parity with the Tauri architecture is required.
+- Capacitor packaging path does not embed the desktop Node sidecar workflow, but native Capacitor runtime can still build graph payloads locally when Filesystem APIs are available and the dataset stays within mobile limits.
+- Tauri Android path provides the native-shell runtime route and uses Android-native `build_graph_runtime` when mobile-side parity with the Tauri architecture is required.
 
 ### 3. Usage Guide
 
@@ -309,7 +406,7 @@ index_cache_ttl_sec = 1800
 max_doc_bytes = 100663296
 ```
 
-### Markdown Reader Protocol (v1.6.6)
+### Markdown Reader Protocol (v1.6.8)
 
 - **Dual-engine gray release**:
   - `markdown_engine = "auto"`: prefer `pulldown-cmark`, fallback to legacy on failure.
@@ -317,15 +414,29 @@ max_doc_bytes = 100663296
   - `markdown_engine = "legacy"`: force original parser path.
 - **Unified cross-window behavior**: Tauri reader and Godot reader now both consume the same sidecar markdown protocol (`index/chunk/resolve-node/resolve-wiki`).
 - **Large file stability**: reader no longer requires single-shot full markdown payloads and supports block-based incremental loading.
+- **Mermaid reliability hardening**:
+  - Godot reader Mermaid rendering now uses `renderer = "auto"` so it can prefer frontend bridge and automatically fallback to local `resvg` when bridge render is unavailable.
+  - Mermaid fences must start on a new line; inline `$$```mermaid` patterns can break block classification.
+  - Use `npm run verify:markdown:mermaid:fence -- Knowledge_Base/testconcept` to catch malformed inline Mermaid fences before release.
+- **Local MCP web-debug baseline (Runbrowser)**:
+  - Build locally from source: `pnpm --filter @jiweiyuan/runbrowser-server build`, `pnpm --filter @jiweiyuan/runbrowser-core build`, `pnpm --filter @jiweiyuan/runbrowser-mcp build`.
+  - Run local MCP entrypoint: `node E:\Knowledge_project\tools\runbrowser\packages\mcp\bin.js`.
 
 ## 🏗️ Build & Deployment
 
-For developers building from source, NoteConnection offers two build modes:
+For developers building from source, NoteConnection now defaults to the runtime-first path:
 
 - **Electron desktop pipeline was removed on 2026-03-01 (deprecated and decommissioned).**
 
-- **Tauri Full Build (`npm run tauri:build`)**: Builds desktop package with full frontend assets.
-- **Tauri Mini Build (`npm run tauri:build:mini`)**: Builds desktop package excluding large pre-generated graph data files.
+- **Tauri Build (`npm run tauri:build`)**: Default desktop package path. Uses runtime-first assets and excludes pre-generated graph payloads.
+- **Tauri Mini Build (`npm run tauri:build:mini`)**: Legacy-compatible alias of the same runtime-first packaging path.
+- **Tauri Full Graph Build (`npm run tauri:build:full`)**: Explicit opt-in path for including generated graph assets when real files are present locally.
+- **Build (`npm run build`)**: Default runtime-first frontend build.
+- **Build Full Graph Assets (`npm run build:full`)**: Explicit opt-in frontend build for local/demo scenarios that need pre-generated graph assets.
+- **Godot Bootstrap** (`npm run prepare:godot:bin`): materializes the host Godot sidecar from local overrides/search paths, cache, or a pinned download URL.
+- **Desktop Release Godot Mirror**: release CI now seeds a project-controlled GitHub Releases mirror tag for Godot archives, then downloads mirror-first with upstream fallback.
+- **LFS Policy Guard** (`npm run verify:lfs:policy`): blocks new Git LFS drift under `src/frontend/` and `src-tauri/bin/` while migration still carries legacy exemptions. Future strict mode is available via `npm run verify:lfs:policy:strict`.
+- **Sidecar Supply Readiness** (`npm run verify:sidecar:supply`): reports whether the current desktop host is offline-ready or still network-dependent before shrinking the remaining sidecar LFS bridge.
 - **GPU Dev Start (`npm run tauri:dev:mini:gpu`)**: Recommended GPU-enabled Tauri development command.
 - **Do not use** `npm run tauri:dev:mini --gpu` because npm treats `--gpu` as config and prints warnings.
 
@@ -342,6 +453,8 @@ For developers building from source, NoteConnection offers two build modes:
 - Recommended lookup entry points:
   - Users: `/diataxis/zh/tutorials/first-run/` or `/diataxis/en/tutorials/first-run/`
   - Developers: `/diataxis/en/reference/interfaces-and-runtime/` and `/diataxis/en/reference/release-and-governance/`
+  - Maintainers assessing LFS / desktop bootstrap risk: `/en/sidecar_supply_strategy/` or `/zh/sidecar_supply_strategy/`
+  - Maintainers comparing mirror cost / user friction / maintenance burden: `/diataxis/en/explanation/sidecar-supply-feasibility/` or `/diataxis/zh/explanation/sidecar-supply-feasibility/`
 - CI auto publish workflow (GitHub Pages): `.github/workflows/docs-github-pages-publish.yml`.
 - Manual rollback entry: run workflow dispatch and set `git_ref` to a stable tag/commit.
 - MkDocs base/path can be overridden by environment variables: `MKDOCS_SITE_URL`, `MKDOCS_BASE_PATH`.
@@ -363,6 +476,25 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 
 ## 📅 Changelog
 
+### v1.7.0 - Startup Acceleration Closure, Multi-Platform Validation, and Learning Roadmap Foundation (2026-03-31)
+- **Tag Compare Snapshot (`v1.6.0..v1.7.0`)**:
+  - `47` commits, `160` files changed, `+20,224 / -1,444` churn.
+  - Engineering footprint concentrated in: `src/frontend/`, `scripts/`, `docs/`, `src-tauri/`, `package*.json`.
+- **Startup Runtime Optimization Closure (Phase 2/3/4 + v1.1 Hardening)**:
+  - Added startup delta tick transport (`tickMode: full|delta`) with low-alpha adaptive controls (`lowAlphaDeltaEpsilonMultiplier`, `lowAlphaFullSyncEveryTicks`).
+  - Added frame-coalesced startup tick application on main thread to reduce redundant repaint pressure near stable phase.
+  - Hardened warm-start recovery with strict snapshot validation (fingerprint, age, node/edge consistency, position coverage threshold).
+  - Expanded startup telemetry at `T5 stable_layout` with `tickSummary` (`fullTicks`, `deltaTicks`, `deltaRatio`, payload and frame metrics).
+- **Cross-Platform Startup Validation Toolchain**:
+  - Added/extended compare + matrix + watch + simulate + cohorts + signoff automation scripts for startup KPI governance.
+  - Introduced no-hardware engineering signoff flow (Windows real logs + simulated cohorts) while preserving release-grade requirement for real multi-device cohorts.
+- **Runtime Contract and Documentation Alignment**:
+  - Synced Diataxis EN/ZH runtime references with the new startup profile fields and telemetry semantics.
+  - Extended startup acceleration plan docs with v1.1 optimization and risk-guardrail closure details.
+  - Added bilingual knowledge-mastery evolution roadmap docs and integrated them into Diataxis navigation and mapping.
+- **Version Metadata Alignment**:
+  - Unified release metadata to `1.7.0` in `package.json`, `package-lock.json`, and `src-tauri/tauri.conf.json`.
+
 ### v1.6.7 - Docs Governance Cleanup & GitHub Pages Stabilization (2026-03-29)
 - Removed unrelated external community UI documentation references from the repository documentation system.
 - Replaced legacy external runbooks with project-owned docs operations runbooks:
@@ -946,7 +1078,7 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 ## 中文文档
 
 
-# 2026-03-29 v1.6.7
+# 2026-04-07 v1.7.0
 # NoteConnection: 层级知识图谱可视化系统
 
 <img width="606" height="309" alt="banner" src="https://github.com/user-attachments/assets/92e90de5-2b1a-4398-8e8b-6e142c92b6a2" />
@@ -965,6 +1097,19 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 
 ---
 
+## 当前主线架构状态（2026-06-10）
+
+- 当前 `main` 已具备代码支撑的 scoped retrieval、grounded conversation、持久化 resource/index/workspace/session/memory/export 底座、显式 export profiles，以及 Godot/mobile PNG-first 渲染物化边界。
+- 知识工作区除了工作区内 scope 切换器、conversation API 状态条、按文件优先的 grouped knowledge hit 与 focus pane 中的 matched-span 高亮之外，还已经具备 durable workflow artifact：`flashcard_batch` 与 `knowledge_run`。
+- agent conversation 运行时已经不再只是单一回答字符串：`answer`、`assistantBlocks`、`knowledgeRun`、按文档聚合的 `knowledgePoints`、citations、memory actions 与 trace 已进入当前兼容性表面，同时保留 legacy `assistantMessage`。
+- 现有 DAG 学习底座是真实存在的：`KnowledgeAtom`、`RelationEdge`、`TemporalEdge`、path query、mastery-path/session 逻辑以及 `KnowledgeQueryItem.relationPath` 都已落地。真正剩余的缺口不是“有没有图”，而是“回答规划层还没有 dedicated graph-conditioned context layer”。
+- graphdb/sqlite 与 ANN/external connector 仍是 operational baseline。生产闭环仍需要多轮 soak 证据、工作负载阈值、recall/latency 校准、strict rollout proof 与多宿主证据。
+- 当前 release-evidence 审计面已由 `verify:foundation:release-evidence`、`verify:foundation:release-evidence:strict` 与 `verify:foundation:release-evidence:multi-host` 统一。
+- 下一阶段架构工作仍是缩减 `src/server.ts`、`src/learning/KnowledgeLearningPlatform.ts`、`src/frontend/agent_workspace.js` 与 `src/frontend/workspace_panes.js` 的所有权压力。
+- 当前代码 / 方案详细对齐请查看 [知识工作区与 DAG 对齐推进方案（2026-06-10）](docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md)、[架构推进对齐与主线推进方案（2026-06-06）](docs/solutions/architecture-progress-alignment-2026-06-06.md) 与 [开发进度看板](docs/diataxis/zh/explanation/development-progress-dashboard.md)。
+
+---
+
 <a id="key-features-zh"></a>
 
 ## 🚀 核心特性
@@ -1066,6 +1211,16 @@ NoteConnection 基于模块化架构构建，旨在实现高性能和可扩展
 
 ## 📦 快速开始
 
+### 桌面系统依赖
+
+| 平台 | 必要依赖 |
+|---|---|
+| **Linux** | `libwebkit2gtk-4.1-dev`、`libgtk-3-dev`、`libsoup3.0`、`libjavascriptcoregtk-4.1-0`（Ubuntu/Debian: `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev patchelf`） |
+| **macOS** | 无需额外依赖（系统内置 WebKit） |
+| **Windows** | [Edge WebView2 运行时](https://developer.microsoft.com/microsoft-edge/webview2/)（Windows 11 预装；Windows 10 可能需要手动安装） |
+
+> **Linux Wayland 用户**：Godot Path Mode 在纯 Wayland 合成器上需要 `GDK_BACKEND=x11`。启动器检测到 `XDG_SESSION_TYPE=wayland` 时会自动设置。
+
 ### 选项 1: Windows 安装程序 (推荐)
 
 1. 从 [最新发布页面](https://github.com/Jacobinwwey/NoteConnection/releases) 下载 `NoteConnection.Setup.exe`。
@@ -1100,50 +1255,38 @@ npm start
 
 ### 选项 5: 移动端支持 (Android)
 
-NoteConnection 现支持 **两条 Android 生成路径**：
-
-1. **Capacitor APK 路径**（Web 资产运行时，适合阅读与可视化流程）。
-2. **Tauri Android 路径**（原生壳流程，对齐 `docs/tauri_brainstorming.md`）。
+NoteConnection 通过 **Tauri Android**（原生壳流水线）支持 Android。Capacitor APK 路径已**废弃**，仅保留作为历史参考。
 
 #### 先决条件
 
 - **Node.js** (LTS)
-- **Java JDK** (17 或更高版本)
+- **Java JDK** (21 或更高版本)
 - **Android SDK** (配置在 `ANDROID_HOME` 或通过 Android Studio 安装)
 
-#### 方法 A: Capacitor 构建（稳定）
+#### 推荐: Tauri Android 构建（原生壳）
 
-在 Windows 上直接运行包含的批处理脚本：
-
-```cmd
-build_apk.bat
-```
+```bash
+# 首次初始化
+npm run tauri:android:init
 
-该脚本会自动：
+# 开发构建
+npm run tauri:android:dev
 
-1. 检查您的环境 (Node, Java, Android SDK)。
-2. 安装依赖项。
-3. 构建 Web 资源。
-4. 同步 Capacitor。
-5. 使用 Gradle 编译 APK。
+# 发布 APK/AAB
+npm run tauri:android:build
+```
 
-也可以通过 npm 脚本触发同一路径：
+构建通用 APK（armeabi-v7a + arm64-v8a + x86_64）：
 
 ```bash
-npm run mobile:build:capacitor
+npm run tauri:android:build:universal
 ```
 
-#### 方法 B: Tauri Android 构建（原生壳）
-
-```bash
-# 机器首次初始化
-npm run tauri:android:init
+#### 已废弃: Capacitor 构建
 
-# 通过 Tauri Android 流水线构建
-npm run tauri:android:build
-```
+Capacitor APK 路径（`build_apk.bat`、`npm run mobile:build:capacitor`）已于 2026-05 废弃。`android/` 目录保留作为历史参考。所有活跃的 Android 开发均以 Tauri Android 流水线为目标。
 
-#### 方法 C: Capacitor 手动构建步骤
+#### 历史参考: Capacitor 手动构建步骤
 
 1.  **构建 Web 资源**:
     ```bash
@@ -1163,8 +1306,8 @@ npm run tauri:android:build
 
 #### 移动端能力边界
 
-- Capacitor 路径当前是 Web 资产打包，不内置桌面端本地 Node sidecar 流程（`/api/build`、`/api/folders`、`/api/content`）。
-- 若需要与 Tauri 架构一致的移动端原生壳路线，请使用 Tauri Android 路径。
+- Capacitor 打包路径本身不内置桌面 Node sidecar，但在具备 Filesystem API 且数据量不超过移动端限制时，Capacitor 原生运行时仍可本地图谱构建。
+- 如果需要与 Tauri 架构一致的移动端原生壳能力，请使用 Tauri Android 路径；该路径会通过 Android 原生命令 `build_graph_runtime` 构图。
 
 ---
 
@@ -1242,7 +1385,7 @@ index_cache_ttl_sec = 1800
 max_doc_bytes = 100663296
 ```
 
-### Markdown 阅读协议（v1.6.6）
+### Markdown 阅读协议（v1.6.8）
 
 - **双引擎灰度发布**：
   - `markdown_engine = "auto"`：优先 `pulldown-cmark`，失败自动回退 legacy。
@@ -1250,15 +1393,28 @@ max_doc_bytes = 100663296
   - `markdown_engine = "legacy"`：强制使用旧解析链路。
 - **双窗口统一行为**：Tauri 阅读器与 Godot 阅读器都统一消费 sidecar Markdown 协议（`index/chunk/resolve-node/resolve-wiki`）。
 - **大文档稳定性提升**：阅读链路不再依赖单次整文全量载入，改为块级增量加载。
+- **Mermaid 稳定性加固**：
+  - Godot 阅读器 Mermaid 渲染已切换为 `renderer = "auto"`，优先走前端桥接渲染，桥接不可用时自动回退本地 `resvg`。
+  - Mermaid fenced code 必须独占新行起始；`$$```mermaid` 这类行内拼接会导致分块识别失败。
+  - 发布前可执行 `npm run verify:markdown:mermaid:fence -- Knowledge_Base/testconcept`，提前拦截异常 Mermaid fence。
+- **本地 MCP 网页调试基线（Runbrowser）**：
+  - 建议按源码本地构建：`pnpm --filter @jiweiyuan/runbrowser-server build`、`pnpm --filter @jiweiyuan/runbrowser-core build`、`pnpm --filter @jiweiyuan/runbrowser-mcp build`。
+  - 本地 MCP 入口：`node E:\Knowledge_project\tools\runbrowser\packages\mcp\bin.js`。
 
 ## 🏗️ 构建与部署 (Build & Deployment)
 
-对于从源码构建的开发者，NoteConnection 提供两种构建模式：
+对于从源码构建的开发者，NoteConnection 现在默认采用 runtime-first 路径：
 
 - **Electron 桌面构建链路已于 2026-03-01 下线（弃用并完成清退）。**
-
-- **Tauri 完整构建** (`npm run tauri:build`): 构建带完整前端资源的桌面安装包。
-- **Tauri 精简构建** (`npm run tauri:build:mini`): 构建排除大型预生成图谱数据的桌面安装包。
+- **Tauri 构建** (`npm run tauri:build`)：默认桌面打包路径，采用 runtime-first 资产流，不默认打入预生成图谱载荷。
+- **Tauri 精简构建** (`npm run tauri:build:mini`)：与当前默认 runtime-first 打包路径保持兼容的旧别名。
+- **Tauri 完整图谱构建** (`npm run tauri:build:full`)：仅在本地存在真实图谱文件时，显式选择把生成型图谱资产打入包中。
+- **Build (`npm run build`)**：默认 runtime-first 前端构建。
+- **完整图谱前端构建** (`npm run build:full`)：仅供本地 / demo 场景显式选择预生成图谱资产。
+- **Godot Bootstrap** (`npm run prepare:godot:bin`)：可从本地覆盖路径 / 搜索目录 / 缓存 / 固定下载 URL 物化当前主机所需的 Godot sidecar。
+- **桌面 Release Godot 镜像**：release CI 现在会先在项目 GitHub Releases 中维护 Godot 镜像 tag，并以“镜像优先、上游回退”方式下载。
+- **LFS Policy Guard** (`npm run verify:lfs:policy`)：在迁移仍保留历史豁免项时，阻止新的 Git LFS 路径再次进入 `src/frontend/` 与 `src-tauri/bin/`。未来严格模式可通过 `npm run verify:lfs:policy:strict` 启用。
+- **Sidecar 供给就绪度** (`npm run verify:sidecar:supply`)：在继续缩减桌面 sidecar 的 LFS 桥接之前，显式报告当前主机是否已具备离线 bootstrap 能力，还是仍依赖网络。
 - **GPU 开发启动（推荐）** (`npm run tauri:dev:mini:gpu`)。
 - **不要使用** `npm run tauri:dev:mini --gpu`，该写法会被 npm 当作配置参数并触发告警。
 
@@ -1275,6 +1431,8 @@ max_doc_bytes = 100663296
 - 推荐查询入口：
   - 用户文档：`/diataxis/zh/tutorials/first-run/` 或 `/diataxis/en/tutorials/first-run/`
   - 开发文档：`/diataxis/en/reference/interfaces-and-runtime/` 与 `/diataxis/en/reference/release-and-governance/`
+  - 维护者评估 LFS / 桌面 bootstrap 风险：`/en/sidecar_supply_strategy/` 或 `/zh/sidecar_supply_strategy/`
+  - 维护者比较镜像成本 / 用户门槛 / 维护负担：`/diataxis/en/explanation/sidecar-supply-feasibility/` 或 `/diataxis/zh/explanation/sidecar-supply-feasibility/`
 - CI 自动发布工作流（GitHub Pages）：`.github/workflows/docs-github-pages-publish.yml`。
 - 手动回滚入口：运行 workflow_dispatch 并设置 `git_ref` 为稳定 tag/commit。
 - MkDocs base/path 可通过环境变量覆盖：`MKDOCS_SITE_URL`、`MKDOCS_BASE_PATH`。
@@ -1289,6 +1447,25 @@ max_doc_bytes = 100663296
 
 ## 更新日志 (Changelog)
 
+### v1.7.0 - 启动加速收口、多平台验证与学习路线图底座 (2026-03-31)
+- **Tag 对比快照（`v1.6.0..v1.7.0`）**:
+  - `47` 个提交、`160` 个变更文件、`+20,224 / -1,444` 代码/文档变更量。
+  - 工程变更面主要集中在：`src/frontend/`、`scripts/`、`docs/`、`src-tauri/`、`package*.json`。
+- **启动运行时优化收口（Phase 2/3/4 + v1.1 加固）**:
+  - 新增启动 tick 差量传输（`tickMode: full|delta`），并引入低 alpha 自适应控制（`lowAlphaDeltaEpsilonMultiplier`、`lowAlphaFullSyncEveryTicks`）。
+  - 主线程新增按帧合并的 startup tick 应用策略，减少稳定阶段附近的重复重绘压力。
+  - 加固 warm-start 恢复，新增严格快照校验（fingerprint、age、node/edge 一致性、position coverage 阈值）。
+  - 在 `T5 stable_layout` 扩展启动遥测，新增 `tickSummary`（`fullTicks`、`deltaTicks`、`deltaRatio`、payload/frame 指标）。
+- **跨平台启动验证工具链**:
+  - 新增/扩展 compare、matrix、watch、simulate、cohorts、signoff 自动化脚本，形成启动 KPI 治理闭环。
+  - 建立“无硬件工程签收”流程（Windows 实机日志 + 模拟 cohorts），并保留正式发布阶段的实机多设备 cohorts 要求。
+- **运行时契约与文档对齐**:
+  - 同步 Diataxis EN/ZH 运行时参考文档，对齐新的 startup profile 字段与遥测语义。
+  - 扩展启动加速方案文档，纳入 v1.1 优化与风险护栏收口细节。
+  - 新增知识掌握演进路线图双语文档，并接入 Diataxis 导航与映射。
+- **版本元数据对齐**:
+  - 将 `package.json`、`package-lock.json`、`src-tauri/tauri.conf.json` 的发布元数据统一到 `1.7.0`。
+
 ### v1.6.7 - 文档治理清理与 GitHub Pages 稳定性修复 (2026-03-29)
 - 清理并移除了项目文档体系中与本项目无关的外部社区界面文档引用。
 - 将历史外部手册替换为项目内通用文档运维手册：
@@ -1782,3 +1959,20 @@ max_doc_bytes = 100663296
 
 - [x] **Canvas 渲染器**: 添加 HTML5 Canvas 支持以实现高性能。
 - [x] **Worker 扩展**: 将线程限制增加到 12。
+
+## Acknowledgments / 致谢
+
+Standing on the shoulders of these great projects. Thank you to their authors and maintainers!
+
+感谢以下优秀开源项目及其作者与维护者：
+
+- **[obsidian-notemd](https://github.com/Jacobinwwey/obsidian-NotEMD)** — the heart of our Notemd engine ❤️
+- **[GitNexus](https://github.com/Compound-Engineering/GitNexus)** — shared types, staleness tracking, and graph ops patterns
+- **[DeepTutor](https://github.com/DeepTutor/DeepTutor)** — agent-native two-layer model (Tools + Capabilities)
+- **[cline](https://github.com/cline/cline)** — co-located test architecture that keeps our tests close
+
+## License / 开源许可
+
+This project is licensed under the **GNU General Public License v3.0 (GPL-3.0-only)**.
+
+本项目采用 **GNU General Public License v3.0（GPL-3.0-only）** 开源协议。