# MNOTE — Reasonix working knowledge

## 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** — self-hosted document/real-time/storage backend (`infra/convex/docker-compose.yml`)
- **Electron** — desktop packaging (`desktop-electron/`)
- **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, Convex transport args generation |
| `rust/crates/mnote-cli/` | CLI tool (`sidebar dataset`, `page get/create/title/save/move`, `block insert/patch`) |
| `rust/crates/storage-convex-bridge/` | Convex storage bridge for Rust |
| `convex/` | Convex schema (`schema.ts`) + functions (`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
- **`npm run desktop:local`** — local dev start (no build step)
- **`npm run desktop:electron`** — Electron dev runner
- **`npm run dist:win`** — build Windows installer (Next assets + electron-builder)
- **`cargo test -p <crate>`** — test a specific Rust crate
- **`cargo run -p mnote-web --bin mnote-web`** — run the web server binary directly

## Conventions

- **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 schema**: `defineSchema` + `defineTable` via `convex/server` package; typed fields with `v.*` validators (`convex/schema.ts:1-3`).
- **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 must be running** (`infra/convex/`) for full-stack dev — smoke tests depend on a live Convex backend.
- **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.