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 |