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-16 (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) · 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
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

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

Next up

1. Assistant overhaul: merged (connections manager, OpenAI-compatible backend over curl, @ mentions and chips, Add to chat from Source and Visual, new panel layout, static agent icons). Still to check by hand: dragging an Explorer item onto the composer, the motion of the popup and chips in the running app, the Source selection toolbar.
2. Folder restructure: done for every crate (PENDING in xtask/src/tree.rs is empty); the layout is described in docs/ARCHITECTURE.md, the rule in AGENTS.md.
3. First tagged release: the macOS .dmg dry run passes locally (ad-hoc signed, signature valid from the mounted image, app starts); still to do: run release.yml on the remote (signing secrets, the shared craft-common-actions workflow), then install-test the Windows MSI and the Linux packages on real machines; embed the app icon into the Windows .exe (needs a build dependency such as winresource, owner approval). The runtime window icon is set on Windows and Linux.
4. Polish: the tab row clears the macOS traffic lights when the sidebar is collapsed to its rail; animated icons: author the set in EffectCraft instead of generating it (its Lottie export adds fields such as ml that the player rejects) and tune individual icons as they are noticed (notescraft-icon-motion skill); egui's own menus and tooltips still close without animation.
5. Binary clipboard image paste (needs the arboard dependency approved), craft-print hook for PDF export, typeset math in PDF.
6. Housekeeping: craftrules reconciliation (0.10), regex dependency decision for search, testkit, split crates/markdown/src/lib.rs (568 lines).

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.