mnote/REASONIX.md

# MNOTE — Reasonix working knowledge

## Current Baseline

- MNote 已进入 **local-first MVP 后阶段**：最小可用闭环已建立，后续重点是底座统一、compat 瘦身和产品化闭环。
- 产品形态固定为：`VSCode 简化版工作区 + tiptap 的 Markdown 前端编辑器 + Hermes/Reasonix agent + simplemindmap/office 插件 + Wolai 主题 Web 壳 + 鉴权控制面`。
- 本地 workspace folder 是默认数据真相；本地 `.md` 是页面正文真相；Page Aggregate、tiptap state、AI context 都是投影或工作副本。
- Rust kernel / projection / command 持有树、页面、资源和权限语义；新增树规则不要散落到前端、Next route 或临时 compat 层。
- Rust SQLite control-plane 已承接默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 等控制面；Convex / 服务端不再是默认正文、附件、AI 会话全文主存储，只保留历史迁移源、显式 cloud source、compat 和 sync replica 边界。
- `mnote-web` 是当前 3000 owner；旧 Next / React / wolai-frontend 已移入 `recycle/`，默认不作为当前实现依据。
- 前端 runtime 已完成第一轮模块级拆分；查浏览器 JS 功能默认先看 `rust/crates/mnote-web/browser/*.js`，查 tiptap island 行为默认先看 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。不要把 `layout.rs` / `tree.rs` / `web_shell.rs` 的历史 raw string 当作当前符号定位入口。
- Knowledge RAG 当前统一到 LightRAG：LiteParse、旧 OCR sidecar、旧 evidence search / local-index agent tools 不再作为默认 fallback；LightRAG 负责 OCR / parse / index / RAG，MNote 负责 source registry、权限、FileTree 灯号、资料库 UI、dashboard/status 和 citation/open-reference。当前模型口径为 `aigc/qwen-3.5`。

## Stack

- **Rust** — workspace of 11 crates, edition 2021, resolver 2, wasm32 target (`rust/rust-toolchain.toml`)
- **Axum 0.8** — HTTP/WebSocket server in `mnote-web` crate
- **Leptos 0.8.14** — SSR island rendering in `mnote-web`
- **Convex 1.x** — retired root functions source plus optional cloud/compat/sync replica service boundary, not the default control plane or document/media/session full-text store
- **Playwright** — browser smoke tests in `scripts/task-*.js`

## Layout

| Path | Contents |
|------|----------|
| `rust/crates/mnote-web/` | Rust web gateway (axum + Leptos SSR, `:3000`) |
| `rust/crates/mnote-web/browser/` | Browser runtime modules for sidebar, filetree, document adapter, tree shell, Page AI panel host |
| `rust/crates/mnote-web/src/routes/knowledge_rag.rs` | MNote LightRAG connector routes: status, ingest, query, delete, prune, open-reference |
| `rust/crates/mnote-web/src/hermes_tools/knowledge_rag.rs` | Hermes / Reasonix-facing knowledge RAG tool facade |
| `rust/crates/core-protocol/` | Kernel types, projection protocol, tree/graph terms |
| `rust/crates/bridge-runtime/` | Kernel query/command, projection bridge, source normalization |
| `rust/spikes/leptos-tiptap-spike/src/editor_runtime/` | Leptos-tiptap island runtime modules; use before editing root `lib.rs` |
| `rust/crates/mnote-cli/` | CLI tool (`sidebar dataset`, `page get/create/title/save/move`, `block insert/patch`) |
| `rust/crates/storage-convex-bridge/` | Convex compat / cloud source / sync-replica bridge for Rust |
| `recycle/20260522-convex-runtime-retirement/convex/` | Retired root Convex functions source retained for audit / migration reference |
| `recycle/20260522-convex-runtime-retirement/infra/convex/` | Retired self-hosted Convex backend compose kept only for historical cloud/compat/sync-replica reference |
| `infra/onlyoffice/` | Docker Compose for OnlyOffice |
| `scripts/` | Node.js dev/build scripts + Playwright smoke tests |
| `design/` | Architecture design documents organized by domain |
| `bugs/` | Bug tracking mirroring design domain structure |
| `recycle/` | Retired code (old frontend, deprecated design drafts) |

## Commands

- **`npm run desktop:hot`** — hot-reload dev start (Rust gateway + optional FastAPI backend + optional Celery)
- **`npm run dev:hot`** — same but with `cargo-watch` for Rust auto-recompile
- **`npm run desktop`** — production start
- **`cargo test -p <crate>`** — test a specific Rust crate
- **`cargo run -p mnote-web --bin mnote-web`** — run the web server binary directly
- **`codegraph sync .`** — refresh CodeGraph after normal code changes
- **`codegraph index . --force`** — rebuild CodeGraph after large refactors, ignore-rule changes, or stale index behavior

## CodeGraph MCP

- Reasonix has `codegraph=codegraph serve --mcp` configured in `/home/lix/.reasonix/config.json`.
- Prefer CodeGraph for structural code questions: symbol lookup, definitions, callers/callees, impact analysis, and focused cross-file context.
- Use `codegraph_search` for symbol names, `codegraph_callers` / `codegraph_callees` for call flow, `codegraph_impact` before risky edits, `codegraph_context` for focused task context, and `codegraph_files` / `codegraph_status` for index inspection.
- Use native search only for literal text, comments, log messages, or after a specific file is already identified.
- Keep the project index fresh in development: run `codegraph sync .` after code changes; use `codegraph index . --force` when the index looks stale or after broad restructuring.
- Runtime split is the current CodeGraph baseline: JS functions should be found in `browser/*.js` and editor runtime symbols in `editor_runtime/*.rs`. If search results point to `recycle/`, historical design docs, or old Rust raw strings, treat them as historical context unless the task explicitly targets legacy code.

## Reasonix Worker Boundary

- Reasonix is a leaf worker, not a main controller.
- Do not start nested Reasonix runners, subagents, extra worktrees, or rewrite task prompts from inside a Reasonix task.
- Coding tasks must use an explicitly assigned write scope and report every modified file.
- Read-only and browser tasks must leave `modified_files` empty and prove it with `git status --short` / `git diff --stat`.
- Browser verification must produce the artifact contract from `design/07-ai/process/7-35-reasonix-browser-test-contract-v1.md`: `result.json`, `final.md`, handoff files, screenshots, console/network evidence, and environment preconditions.
- Codex/Hermes main controller accepts Reasonix output only after checking handoff/result files, diff, validation evidence, and current repo status. Natural-language conclusions without artifacts are leads, not verification.

## Reference-Code Comparison

- Reference implementations live under `/mnt/Data1T/mnote/reference-code/`; prefer `/mnt/Data1T/mnote/reference-code/sidex-main` for VSCode workbench comparisons because it contains the fuller `src/vs/workbench` tree, while `reference-code/vscode` is a smaller auxiliary snapshot.
- Compare one feature slice at a time, such as explorer open target, editor tabs, resource lifecycle, drag-and-drop ordering, keybindings, or overlay placement.
- Fast workflow: check `codegraph_status` for both projects, locate reference entry points with `codegraph_search/context`, inspect callers/callees, inspect the matching MNote chain, then map the result onto Rust kernel / `mnote-web` / frontend host boundaries.
- Always classify findings as: reusable interaction/state model, reference-only implementation detail, or incompatible with MNote local-first / tree-first architecture.

## Conventions

- **Local-first default**: start from Rust `mnote-web`, LocalFS/local_folder projection, Page Aggregate, File Tree, Resource Tree, and SQLite control-plane auth/session/actor. Use Convex paths only for explicit cloud source, compat, sync-replica, migration, or rollback work.
- **Smoke test pattern**: standalone Playwright scripts under `scripts/task-*.js` using a shared harness (`ensureAuthenticated`, `createTempDocument`, `cleanupDocuments`). All use `"use strict"` and `require("playwright")` (`scripts/task110-page-title-single-truth-smoke.js:1-4`).
- **Smoke baseline**: use `scripts/TESTING_REFERENCE.md` for current/compat/manual/retired classification. Default browser baseline is `3000 Rust SSR + leptos-tiptap island + local-first workspace + SQLite control-plane auth`.
- **Rust workspace**: edition 2021, resolver "2", MIT license. All crates inherit workspace version (`rust/Cargo.toml:2-8`).
- **Convex boundary**: root `convex/` has been retired to `recycle/20260522-convex-runtime-retirement/convex/`; `infra/convex/` has been retired to `recycle/20260522-convex-runtime-retirement/infra/convex/`; do not recreate either as an active deploy source without a new architecture decision. `recycle/wolai-frontend/convex` is also historical. Keep Rust `transport/convex.rs` and `storage-convex-bridge` as explicit cloud/compat boundaries; do not mechanically delete them with the retired functions source.
- **AI editing path**: local-first Markdown editing should prefer `currentFile + selection + allowedRoots / aiAccessScope + agent native patch/diff + watcher sync`. `mnote.doc.*` / `mnote.block.*` are cloud, remote, compat, or complex-structure helpers.
- **Knowledge RAG path**: use `mnote.knowledge_rag.status/query/open_reference` and `/api/knowledge-rag/*`. Do not use `mnote.evidence.*`, LiteParse, or local OCR sidecar as the default retrieval/indexing path. Image sources enter LightRAG through a Markdown wrapper; MNote status bridge/backoff syncs LightRAG background completion back to the registry and FileTree.
- **Bug tracking**: bugs organized by design domain directory (e.g. `bugs/04-tree-domain/process/`), moved to `done/` when fixed (`bugs/README.md`).
- **Design docs**: organized by domain in `design/`, with `process/` (in-progress) and `done/` (completed) subdirs (`design/README.md`).

## Watch out for

- **write_file path rule**: paths are sandbox-relative; leading `/` is stripped. Use `path: "design/..."` not `/mnt/Data1T/mnote/design/...`.
- **`.aionrs/`, `.claw/`, `.codex/`, `.gemini/`** — session data from other AI tools, not project code. Don't read or edit.
- **`recycle/`** — retired code, not current implementation. Don't use as evidence for current behavior.
- **Convex availability**: local-folder / Rust projection smoke should not require Convex. Auth, share grants, ACP/Hermes runtime state, and AI policy default to SQLite control-plane; Convex is required only for tests that explicitly cover legacy cloud source, compat, sync replica, migration, or rollback behavior.
- **LightRAG boundary**: LightRAG storage is derived cache, not user source truth. MNote registry is the mapping authority for source path, doc id, stale/deleted state, FileTree lights, and citation routing.
- **MVP 后阶段优先级**: prefer WorkspacePath/ObjectIdentity runtime consumption, DocumentBuffer/BufferStore, Page Aggregate compat slimming, tree command context/context key, live cache unification, agent diff audit, conflict merge, local lightweight search, and share/sync productization. Knowledge RAG belongs to LightRAG, not a revived local evidence/LiteParse index.
- **Rust wasm32 target** required (`rust/rust-toolchain.toml`), needed for `tree-shell-runtime-wasm` crate.
- **`rust/target/`** is gitignored and large — `cargo build` runs from scratch if cache is missing.