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/`，默认不作为当前实现依据。

## 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/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 / cloud source / sync-replica bridge for Rust |
| `recycle/20260522-convex-runtime-retirement/convex/` | Retired root Convex functions source retained for audit / migration reference |
| `infra/convex/` | Docker Compose for self-hosted Convex backend, used only for explicit cloud/compat/sync-replica paths |
| `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, 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`).
- **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/`; do not recreate it 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.
- **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.
- **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.