notescraft/ROADMAP.md

NotesCraft roadmap

Stage: pre-alpha · spec approved 2026-10-13 · phase 0 done · phases 1 to 10 implemented; phase 11 (packaging, i18n migration, release) open

Last updated: 2026-10-19 (vault knowledge, settings sub-menus, macOS menu bar; calendar plugin: events, recurrence, quick add, filters, keyboard, reminders, ICS and Google feeds; assistant panel with ACP bridge and write gate, control channel, properties panel, slash menu, image paste/drop, PDF export, LaTeX math, Vim mode, resizable panels, whiteboard upgrade, fast open, editor blocks and lint, code blocks, grammars and formatting, editor previews) · Target: Obsidian-compatible vault, native egui, see SPEC.md

One-page summary of where NotesCraft stands. The contract is SPEC.md; the definition of done per feature is its section 12. One PR per phase, each reviewed before merge.

Phases

#	Phase	Crates	Status
0	Foundation	workspace, xtask, AGENTS.md, architecture doc	done (CI workflow written, not run: needs the remote runner and CRAFT_LIBS_TOKEN; craftrules 0.10 pending)
1	Vault + markdown	vault, markdown, testkit	done (testkit still empty); math delimiters \(..\), \[..\] and unbalanced $..$ recognised
2	Index + links	index, backlinks, diagrams, whiteboard parsers	done
3	Engine + app shell	engine, ui-egui shell, i18n	done: registry, Session, buffers, commands, settings via craft-settings, plugin bridge, git, control channel (loopback JSON server, CLI defers writes to the running app); i18n crate done, UI copy migrated to its catalogue
4	Editor	editor, properties panel, slash menu, image paste, recovery	done: editing, save, autosave, recovery, autocomplete, typed properties panel, slash menu, image drop and file-path paste; binary clipboard image paste needs the arboard dependency (not added)
5	Search, tags, palette	search UI, tag tree, command palette, outline, bookmarks, breadcrumbs	done (bookmarks, Source tab, context menus, tab shortcuts included)
6	Graph	graph + renderer	done
7	Daily notes, calendar, templates, themes	templates, themes	done, UI included
8	Canvas, whiteboard, diagrams UI	canvas, renderers	done: canvas, whiteboard (.draw, legacy .excalidraw), diagrams, LaTeX math (math crate and renderer)
9	Plugins	plugins (wasmi host)	done; plugin-tool toggles in Settings > AI assistant
10	MCP, CLI, control channel, assistant panel	mcp, notescraft-cli, acp	done: MCP server, CLI (mcp --via-control, export pdf, export whiteboard), ACP client, write gate with pending-change review, transcripts, assistant panel
12	Calendar plugin	calendar, engine calendar.*, calendar view, apps/notescraft services	done: events as notes, repeat subset, quick add, five views, filters and saved filters, keyboard model, reminders with inbox, ICS feeds, Google (view-only); not built: Apple, Outlook, CalDAV, two-way sync, background agent, non-English quick add (specs/calendar-plugin-redesign)
13	Vault knowledge	knowledge, engine knowledge.*, Related tab, assistant sources, Settings > Knowledge	done: passage index, vocabulary expansion, link and tag signals, five commands, MCP vault_context, auto context, sources, Related tab, compact layout; not built: embeddings (only if recall@6 falls under 80%), non-English stemming, attachments (specs/vault-knowledge)
14	Editor blocks and lint	lint, blocks, engine lint.* and block.*, slash menu, grip, Lint tab, Settings > Editor and lint	done: 12 lint rules (spelling slot only), one-click and safe fixes, learned style, dismissals, fix_on_save, slash menu with groups and preview in Source and Visual, block grip, drag, menu, Vim ]] [[ gb, Visual tables, note embeds, %% comments; not built: spell-check, mobile bottom toolbar, Fix popover in the editor, keyboard use of the block menu (specs/editor-blocks-and-lint)
15	Fast open and large vaults	vault listing and count_files, engine open_lazy, index_step, ContentSearch, index.*, Explorer virtualization and navigation, large-folder warning	done: window in under a second on 10 000 notes, background indexing with a status card, search from disk while indexing, pause and resume, rename and move refused until the index is complete, virtualized Explorer (50 000 rows), note counts, filter, collapse all, reveal and follow, pinned folders, sticky folder path, warning above 5 000 files; no index cache (not needed); not built: honouring .gitignore in non-vault folders, jump-to-letter strip, key bindings for the Explorer commands (specs/fast-open-and-explorer)
16	Editor previews	editor::preview, engine editor.previews.*, colour swatches, external-link arrows, tree card, Mermaid Source toggle	done: detect_colors (hex, rgb/rgba, hsl/hsla and the basic colour names) and detect_tree, both pure and bounded, swatches in body text, inline code and ten fenced languages, the right-click colour menu (Copy color, Copy as rgb, the two switches), external-link arrows, the TREE card, the Mermaid Diagram/Source toggle and the error/unsupported/too-big chips; not built: swatches and arrows in Source mode and in rows with inline math, swatches for a hex Obsidian reads as a tag (specs/editor-previews)
17	Mobile, sync, collaboration, launcher	sync and collab (L1), apps/notescraft-sync-server, engine sync/ and prefs/catalog/, ui-egui launcher and shell/compact, apps/notescraft launcher_window	done 2026-10-20: sync ledger, planner and merge (28 tests), server with accounts, many vaults, roles, invites, hardening, quota, GC (40 tests), engine client, worker and sync.* commands, vault catalog and launcher (host wired), OT core (22 tests), compact layout, 15 PaperCraft screens, research (3 reports) and specs (mobile-and-sync, collaboration, vault-launcher, agents); also done: sync UI (Settings > Sync, status pill, conflicts) and the live-editing endpoints (SSE rooms, flush); not built: live session client in the engine and the editor UI, Share dialog, Android and iOS shells, E2EE, deploy, attachments chunking, server version history (see the three tasks.md files)
11	PDF export, packaging, i18n coverage, hardening	pdf, packaging/, release	PDF export done (crate, export.pdf, CLI, dialog; LaTeX prints as source, craft-print not wired); packaging done for macOS (built and smoke-tested), Windows (MSI scripts, compile-checked only) and Linux (deb/rpm/AppImage scripts, untested here); i18n migration done (252 keys in en.toml, cargo xtask i18n --strict is part of ci)

Also built beyond the phase list: Vim mode (vim crate and app-wide navigation), resizable and collapsable cards with rails, Windows/Linux custom title bar.

Implemented so far

28 crates plus the CLI: acp, backlinks, blocks, calendar, canvas, diagrams, editor, engine, git, graph, i18n, index, knowledge, lint, lottie, markdown, math, mcp, pdf, plugins, syntax, templates, testkit (empty), themes, ui-egui, vault, vim, whiteboard; about 166 000 source lines. cargo xtask ci is green on develop. Per-crate API and numbers: docs/ARCHITECTURE.md.

Also done on 2026-10-17: the assistant starts opencode with a lean private config (crates/acp/src/lean.rs: no plugins, MCP, skills or agents, unused built-in tools off; about 5 000 tokens for a first prompt instead of 60 000 or more), the in-app assistant's MCP list holds only the aliases, search and plugin tools, the assistant's Preview of a pending change is a full-window side-by-side diff (still without Accept/Reject, and it opens only the first pending change), mouse-wheel scrolling works in every card, many more LaTeX commands, and a configurable note padding (Settings, Appearance).

Status checklist (2026-10-17)

Done (crossed off):

• Phases 0 to 13 (see the table)
• Calendar plugin redesign: 15 tasks, events as notes, repeats, quick add, five views, filters, keyboard model, reminders, ICS and Google (view-only)
• Calendar settings page rebuilt from the design (General, Sources, Display, Notifications, Accounts) and its wide rows (chips, quiet hours, add feed) laid out on their own line
• Core plugins as cards (toggle, tools chip, Configure) and Core plugin switches that save
• Interactive sidebar mini calendar
• Command palette redesign (icon tiles, key caps, hover glow)
• Settings sub-menus with arrows (Core plugins > Calendar, Appearance, AI assistant sections that scroll to their heading); Calendar is no longer a top-level entry
• Assistant fixes: tool calls saved per update now read back as one card; a queued write tells the agent it is NOT written yet
• Vault knowledge (RAG without vectors): crate, knowledge.* commands, MCP vault_context, auto context and sources in the assistant, Related tab, Settings > Knowledge, compact (phone-width) layouts, bottom sheet; 10 tasks in specs/vault-knowledge
• macOS: traffic-light buttons hidden, native menu bar (File, Edit, View, Window, Help), top space reclaimed (8 pt drag strip)
• Settings page at phone width: category pills on top, rows stack, 44 pt targets
• Designs made in PaperCraft: slash menu, WYSIWYG blocks, lint and fixes
• Fast open and large vaults: lazy session open, index_step in the frame loop, content search from disk, indexing card and states, virtualized Explorer with filter, pins and sticky path, large-folder warning; 12 tasks in specs/fast-open-and-explorer
• Editor blocks and lint: notescraft-lint, notescraft-blocks, lint.* and block.* commands (engine, CLI, MCP), Lint tab, slash menu with preview, block grip and menu, Settings > Editor and lint, Visual tables and note embeds
• Code blocks, grammars and formatting: notescraft-syntax (highlighting on a worker thread with a bounded cache, grammar fetch/validate/install, language suggestions), JSON check, format and minify in notescraft-blocks, the eight [syntax] theme colours, the rendered code card (Copy, Wrap, Valid chip, JSON offer, typo suggestion, "Add grammar"), rounded inline-code chips, the batch format and lint engine (batch.*, a dry run that writes nothing) and the file-by-file review view with Accept/Skip per change and Apply, the original TOML and TypeScript grammars embedded in notescraft-syntax and the third batch check "Add missing language labels"; 15 tasks in specs/code-blocks-and-formatting
• Editor previews: colour swatches in text, inline code and fenced stylesheets, the right-click colour menu (Copy color, Copy as rgb, two switches), external-link arrows, the TREE card, the Mermaid Diagram/Source toggle and the fallback chips; 11 tasks in specs/editor-previews

Pending, by area:

• Code blocks, grammars and formatting (done, 15 of 15 tasks, specs/code-blocks-and-formatting): toml and ts fences now highlight through two original grammars embedded in notescraft-syntax (crates/syntax/grammars/*.sublime-syntax), and the batch review has a third check, "Add missing language labels": blocks::detect_language names the language of an unlabeled fence conservatively (shebang, PHP, HTML, XML, JSON, YAML, diff, shell prompts, Rust, Python, SQL, TOML, on the first 4 KiB and 40 non-blank lines) and each ChangeKind::Label is a zero-length insert right after the fence run that always needs review (batch.start takes labels, on by default). Not built — the language picker of the design (a mistyped label is fixed by the suggestion chip, and nothing offers to add a label while typing in source mode), the table-alignment checks of the design, and the "more info" card of the grammar dialog. A note with 50 code blocks draws its first frame in 15 ms median (release), 87 ms in a cold process.
• Editor previews (done, 11 of 11 tasks, specs/editor-previews): not built or limited — no swatches or arrows in Source mode or in rows carrying inline math, and a hex that Obsidian reads as a tag (#cba6f7 in prose) stays a tag, so only inline code and non-tag text get swatches; Unsupported is reachable only if the diagram parser returns an unrenderable kind (today it answers NoHeader for one it does not know, so those show the Error chip). Scanning 100 rows of 10 colours (1,000 hits) takes 0.05 ms median, 0.15 ms worst, in release.
• Obsidian basics (specs/obsidian-basics, audit in audit.md): all 18 tasks built. Find and replace (with regex), back/forward, auto-pair, footnotes, explorer sort and drag-and-drop move, heading and list folding, search operators and /regex/ search, vault-wide replace, quick switcher headings and blocks, random and unique notes, Open in default app, Copy Obsidian URL, pinned and reorderable tabs, link hover preview, outgoing links, split view (two panes with their own tabs; a click in a pane makes it the editing pane), spelling lint rule, settings (default view, font size, readable width, line numbers, new-note folder, link format and path, deleted files), PDF embeds drawn as an image of the page (#page=N; macOS PDFKit, elsewhere pdftoppm when installed, else a file card), an audio tab and audio embeds that play in the app (ffplay sound, a waveform that seeks, a live spectrum from an own FFT), video embeds with a still, and in-note playback (ffmpeg decodes frames, ffplay the sound) when ffmpeg is installed, else Open in the system player, and a graph view with force sliders and colour groups that scales to 6.5k notes. Strict line breaks and show-hidden-files are settings too. Limits kept on purpose: video playback needs ffmpeg on the machine (no decoder is linked), no bundled spelling dictionary (the vault is the vocabulary). crates/ui-egui/tests/driven_features.rs drives tab drag, pinning, the link hover card, list folding, split view, hidden files, the regex find bar and Explorer drag-and-drop through real input events.
• **Obsidian basics round 2 (specs/obsidian-basics/tasks.md 19-24): query embeds (19) and stacked tabs (21) built; editor follow-ups (23) built; pop-out windows (22) built but not seen in a native window; RTL (20) built for the reading view with unicode-bidi (owner approved; Arabic unjoined, Source mode logical order); round 3 (tasks 25-30, from the audit rows still missing or partial) started: note composer (note.extract, note.merge, the toolbar button and the Explorer "Merge into…") and trash trash.list/restore/empty and the Trash tab built, folder notes (27), reading mode and the indent settings (29), table helpers, user themes, the graph timelapse and Source-mode heading folding (30), workspaces (32), heading/block links (33) and note versions (31, local snapshots plus the git history) and Cmd/Ctrl+Enter on tasks in Source and Visual (36, 37) built; unbuilt: hand check of the packaged app and a Windows playback run.
• Linux and Windows feedback (2026-10-19): built: the Explorer calendar folds (chevron, remembered, folded on a first run in a window under 720 pt), the Explorer toolbar is laid out by hand (filter box plus two pill buttons, fixed gaps, flush right), the empty Bookmarks section is gone, the menu bar words are flat text with a soft hover/open background, the Related tab scrolls, a new Outline pane (count, filter, folding, active heading, scroll), a performance overlay (view.performance: fps, frame ms, memory, CPU; /proc, ps or PowerShell, no new dependency), and a first-run UI scale taken from the desktop on Linux when the window was not told its scale (QT_SCALE_FACTOR, GDK_SCALE, Xft.dpi, GNOME text scaling). Not confirmed on those systems: the title bar blink (the bar is now drawn whole on every frame and sits above the cards) and Explorer icons drawn out of bounds on a fast scroll (not reproduced offscreen; rows are now clipped to the viewport). Windows paths (PowerShell sampler, menu bar) were not run.
• Editor (built, see phase 14): spell-check needs an owner decision (new dependency or in-house checker); open: mobile bottom toolbar, inline fix popover, block menu by keyboard, embed with other text on one line, checkboxes inside embeds, embed refresh after editing another tab.
• Editor settings: the page has only Vim mode; more settings need editor features first (line numbers, spellcheck, font size, ...), then sub-menus for them.
• Community plugins: a browse page and sub-menu.
• Calendar follow-ups: Apple (EventKit or CalDAV), Outlook, two-way Google sync, a background reminder agent, non-English quick add, Windows notification and keychain, light and 4K variants of the newer screens, a colour-blind-safe palette, an index of dated tasks, "Default view", "Notes with a date property", notification status banner.
• Assistant: Accept/Reject on the Preview page and choosing which pending change to preview; pending changes are lost when the app restarts; a lean launch for Claude Code, Gemini and Codex; hand checks still open (drag an Explorer item onto the composer, popup and chip motion, the Source selection toolbar).
• Knowledge gaps: opening a source jumps to the passage start but cannot select it; Related, sources card and Knowledge settings differ slightly from the designs (answer text 15 pt vs 14 pt, marker weight, chip padding, uppercase section headings, card tint); a dense scorer only if recall@6 falls under 80% on a real vault; the vocabulary cache keeps stale pairs after an edit outside the app until a rebuild; no other-language stemming.
• Phone width: the app shell has no bottom tab bar and there is no mobile build; only the new screens and Settings adapt.
• macOS menu: clicking the items, Cmd-W and Cmd-Q were not checked live (macOS blocked the automation check), the menu bar shows the lowercase binary name until the app is bundled, no menu on Windows and Linux, the Edit menu shows no shortcut hints; the muda dependency (pinned 0.21.2) needs owner approval.
• Release: run release.yml on the remote, install-test the Windows MSI and Linux packages, embed the Windows icon (winresource approval), first tagged release.
• Polish: animated icons authored in EffectCraft, egui menus and tooltips close without animation, binary clipboard image paste (arboard approval), craft-print for PDF export, typeset math in PDF, font coverage for some math symbols.
• Housekeeping: nothing from this session is committed (large uncommitted tree); Cargo.lock changed (muda, crossbeam-channel, keyboard-types); craftrules 0.10, regex dependency decision for search, testkit, split crates/markdown/src/lib.rs.

Known issues and review findings

• craft-atomic is the only write path. Engine commands write inside the vault only; the CLI is the one caller that places files at absolute --out paths.
• vault: \ is treated as a path separator on every OS, so a file literally named a\b.md cannot be addressed on unix.
• themes: several Latte colours deviate from stock Catppuccin for contrast (SPEC 8.2 to be updated).
• Disk: each agent's target/agent-* is about 600 MB; the volume hit 100% once and broke a build (a corrupted incremental cache needed cargo clean -p). Delete agent target dirs after merging.

Phase 0: foundation (ordered tasks)

Goal: an empty but green workspace that enforces the rules in SPEC section 3 before any feature code exists.

#	Task	Done when	Status
0.1	Root Cargo.toml: resolver 3, edition 2024, [workspace.dependencies] with the pinned craft-libs rev and every notescraft-* crate, workspace lints (unsafe_code = "forbid", clippy pedantic)	cargo metadata succeeds	done
0.2	16 stub crates under crates/ plus apps/notescraft and apps/notescraft-cli, each with package metadata, module doc, #![deny(...)] never-crash lints, one TODO(phase N) and one test	cargo test --workspace passes	done
0.3	clippy.toml, rustfmt.toml, .cargo/config.toml (xtask alias), .gitignore, licence files	cargo fmt --check passes	done
0.4	cargo xtask verify: fmt check, clippy -D warnings, test, stops at the first failure	green on the empty workspace	done
0.5	cargo xtask layers: the L0–L5 dependency rules, no egui below L5, unregistered crate is an error, with unit tests	green; rejects a deliberate upward dependency in its tests	done
0.6	cargo xtask ci = verify + layers	green	done
0.7	AGENTS.md and README.md for contributors (never-crash rules, how to add a crate, how to add a command)	reviewed	done (AGENTS.md, docs/ARCHITECTURE.md, README.md)
0.8	Design reference recorded: PaperCraft project NotesCraft (tokens, 9 screens) linked from the README	link present	done (README Design section)
0.9	CI workflow running cargo xtask ci on macOS, Linux and Windows	green on all three	workflow written (.github/workflows/ci.yml), not run: needs the remote, a runner and the CRAFT_LIBS_TOKEN secret
0.10	Reconcile with craftrules standards once the repository is available	open question in SPEC section 14 closed	pending (craftrules not on disk)

Tasks 0.1–0.6 are committed on phase-0/foundation and merged work continues on develop. 0.9 and 0.10 wait on the owner (remote, CI host, craftrules).

Not started, deliberately deferred

Sync, mobile, publish, version-history diff UI, Bases, built-in model hosting, JS plugin compatibility, web build, TeX rendering, Web Clipper, additional languages. See SPEC section 6.1.