English everywhere: code, comments, docs, commits — regardless of
conversation language.
One logical change per commit; never bundle unrelated changes.
No god classes: one class per file, split at ~300 lines or when
responsibilities mix. Layout: lib/src/<module>/ (see
architecture). test/unit/source_file_size_test.dart
holds every file in lib/ to 600 code lines (blank and comment-only lines
do not count); the few already over it are listed at their size and can
only shrink. A new feature’s commands, panes and flows go in a file of
their own (ui/shell_<feature>.dart, ui/note_<feature>.dart), never into
shell.dart or note_view.dart, which only wire them in (#100).
Vocabulary: Library, note, folder, tag, template, wikilink, trash,
history. Not vault/canvas/daily note/backlinks.
Design rules:
Disk is source of truth — store nothing in SQLite that cannot be
rebuilt from files.
No disk I/O on the UI isolate — use Isolate.run (every
listSync/statSync is a FUSE round trip on Android). Drift writes
stay on main.
No O(n) full scans on hot paths; FTS5 for search; tree rows
materialized. Target: 1M notes + novel-length files.
Android storage is plain dart:io (MANAGE_EXTERNAL_STORAGE, gated
by core/storage_access.dart) — SAF grants are not a substitute.
R8 strips the reminder icon unless pinned via tools:keep in
android/app/src/main/res/raw/dev_niman_niman_keep.xml — update the
keep file when renaming the drawable.
A cache that can be rebuilt gives itself back: one kept only to save a
re-read of the note, the index or a pure computation implements
Reclaimable and calls MemoryReclaim.track(this), so the system’s call
for memory and the app going to the background empty it
(memory). Not a cache of user data or of
what is on screen.
Interface rules:
Icons are outline. A filled icon says a state is on: the selected
tab, a pinned note, the current library, the note in use as the
quick note. Two weights in one list with no state behind them is a
bug.
A control that shows in only some states keeps its place. Disable
it instead of dropping it, or put it on the side the row grows
from, so nothing already on screen slides under a thumb that is
already on it.
A pointer’s menus are compact by default (lib/src/ui/pointer_menu.dart):
PointerMenuScope puts pointerMenuTheme into the app’s theme (popup
and MenuAnchor menus follow it), and what a theme cannot say is
menuItem(), menuDivider() and MenuRow. Never build a raw
PopupMenuItem or PopupMenuDivider (test/unit/menu_sources_test.dart
fails on one) and never copy the numbers. A drop-down choice is
MenuChoiceButton (lib/src/ui/menu_choice_button.dart), inline or,
with a decoration, as a form’s field — never Material’s
DropdownButton or DropdownButtonFormField, whose rows are never
under 48 px (#1119, #1123; the same source test fails on one). A
setting’s choice is a SettingsValueRow opening showSettingsChoice,
not a SimpleDialog of its own.
Portability: new tests must be portable — p.join for paths
(never literal /), no chmod.
Output discipline: never dump large output into context. Redirect
to scratch dir (/tmp/niman, %TEMP%\niman), read selectively;
never cat whole large files (grep -n / sed -n); paste log lines
only on failure, only the relevant ones.
Docs in the same PR: when a feature is added, modified, or removed,
update the corresponding docs/ page in the same PR (see AGENTS.md).