Design records

These are the design, research and measurement records behind Niman’s features — not how-to documentation, and not kept current with the code. Each was written while a feature was designed or a decision was taken, and says what was measured, which options were rejected and why. They are kept because the numbers and the reasons are the argument a later change has to answer.

Moved here from docs/dev/ on 2026-09-25. docs/dev/ now holds only the living documentation — architecture, building, conventions and the release process. The records’ content is unchanged apart from the links that followed the move; the code and the tests cite them by path in comments (docs/records/<name>.md).

Record What it covers
unified-surface.md Research and design for one Markdown surface — built (#247)
editor-alternatives.md The WYSIWYG packages measured and rejected before that decision
read-live-parity.md Where the read view and live stand, and the decisions that aligned them
huge-notes.md The 246 MB note: what was measured and what changed because of it
desktop-performance.md The desktop audit (#62): the cold-start and integration-test baseline, the animation inventory and the proposed policy
performance-audit.md The performance baseline (#1135): the scenarios, Android’s numbers from the device logs, the Linux perf suite, a million notes, the APK’s libraries, and the prioritized list
memory-usage.md Where the running app’s RAM goes: the log’s resident set, a retention probe, nine holders ranked with their fixes, and what was ruled out (#511, #1144)
tree-window.md The note tree bounded by what is on screen: a model of the visible rows from counts, pages around the viewport, the flows that read the whole list, measured over a million rows (#1200)
workspace.md The open-note model — tabs and panes (#23)
epub-reader.md Reading an EPUB into Markdown (#280)
annotations.md Annotating a PDF or a book in a companion note (#284)
sync.md Note history and WebDAV sync: the decisions, settled before the code
history-store.md The history as objects, deltas and an append-only log, with nothing flushed on a save’s path (#1148)
index-reconcile.md The index scan, a directory at a time with bounded memory (#302)
transcription.md On-device speech-to-text with whisper_ggml
ocr.md Text recognition with Tesseract, engine and languages downloaded on demand (#532)
web-capture.md Capturing a web page or a selection as Markdown, with a Dart port of Readability (#531)
flashcards.md Decks of flashcards in notes, reviewed with SM-2, the review state in .niman/review.json (#533)
calendar-txt.md Reading and writing calendar.txt beside todo.txt: the journal’s events, the line-wise sync merge, reminders on an event (#730)
recurring-tasks.md Recurring tasks: the rec: grammar shared with events, the copy completing one makes, its reminder and the sync merge (#1153) — not built
recurring-events.md Recurring events in calendar.txt: a rule on the event read virtually, except:/until:, the reminder horizon, the merge’s rule pairing (#1153) — not built
todo-note-links.md Tasks and notes linked both ways: a wikilink in a task, a note’s tasks in its panel, a todo query block, Move to tasks (#1152) — not built
note-columns.md Columns of blocks side by side with Pandoc’s fenced divs, editable in live (#729)
library-features.md A per-library switchboard for the macro features: the model, the gating seam, the introduction, the phases (#1109) — not built
apple-platforms.md The plan for macOS and iOS: storage grants, the Mac desktop, widgets, signing, CI, phases and the owner’s decisions — not built
review-v0.1.3.md Code review of everything merged after v0.1.3: what was fixed, what is open

Edit this page on GitHub