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 层。
• Convex / 服务端不再是默认正文、附件、AI 会话全文主存储，只保留 auth、membership、share grants、sync state、AI policy、cloud source、compat 和 sync replica 控制面。
• mnote-web 是当前 3000 owner；旧 Next / React / wolai-frontend 已移入 recycle/，默认不作为当前实现依据。

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 — auth/share/sync/ACP/Hermes control plane and optional cloud/compat/sync replica, not the default 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/core-protocol/	Kernel types, projection protocol, tree/graph terms
rust/crates/bridge-runtime/	Kernel query/command, projection bridge, source normalization
rust/crates/mnote-cli/	CLI tool (sidebar dataset, page get/create/title/save/move, block insert/patch)
rust/crates/storage-convex-bridge/	Convex compat / control-plane bridge for Rust
convex/	Active Convex deploy source for ACP / Hermes runtime state (schema.ts + aiSessions.ts)
infra/convex/	Docker Compose for self-hosted Convex backend
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.

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, and Resource Tree. Use Convex paths only for auth/cloud/share/ACP/compat-specific 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).
• Rust workspace: edition 2021, resolver "2", MIT license. All crates inherit workspace version (rust/Cargo.toml:2-8).
• Convex boundary: root convex/ is the active deploy source for ACP / Hermes runtime state (schema.ts + aiSessions.ts). Do not deploy from recycle/wolai-frontend/convex; old documents / mediaAssets / users / workspaces functions must be explicitly migrated to active code, moved to an auxiliary area, or retired.
• 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.
• 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 unless the test explicitly covers auth, cloud source, share grants, ACP/Hermes runtime state, or sync replica behavior.
• 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 index, and share/sync productization.
• 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.