narl-workspace/PLAN.md

Findings, possible bugs, and what comes next

The simplification, done

Written on 2026-10-22. The app had grown slice by slice to about 85 commands, 60 browse keys and 11 overlays, with the same idea modelled two or three times: text in three editors, files in two places, cards that pointed at a document the document could not see, four inboxes, two layout systems, and keys documented by hand in seven places. A plan in eleven slices made the same features out of fewer things, one place for each, and one key grammar. Every one has landed:

	slice	commit
0	the audit's fixes: Ctrl-P keeps its query, :today by the server's day, card descriptions resolve links	7f8a381
1	one keymap table drives the dispatch, help, the footers, the rail and the wiki; a mode stack replaces the flags	0eabcb2
2	one Sheet component; the info sheet holds headings, versions, backlinks and sharing	26b3c68
3	the board, agenda, calendar and a card's back are tiles; the special workspace is gone	5684614
4	documents and cards linked both ways: gc, card verbs on the card in focus, cards in search	b8b3641
5	one editor for documents, descriptions and notes, all saving themselves	ccc9102
6	the scratchpad is the inbox, with three ways out and a search	2233fa4
7	a file belongs to a node; the media browser is gone	d8e72c6
8	! means force or everything only; merged commands; a settings sheet; two-level help	7f8d625
9	the store split into parts under one Workspace	b110701
9b	fixes from daily use: Ctrl-h/j/k/l between tiles, Ctrl-Q from anywhere, the plan screen	650fc40
10	the docs: the guide around the four things, the README, new screenshots	this commit

The model it leaves: a document is the thorough record, a card the short actionable summary of work, a note a thought not sorted yet, and a diary entry a document about a day. A file sits in a folder or belongs to its document. The documents and the plan each have a screen, and the scratchpad comes down over either.

Left over from the plan, not started

These were in the plan's navigation fixes, outside the numbered slices:

• The list groups documents by day in every space; the plan had that only in the diary, and folders first then by name elsewhere.
• Ctrl-P is full-text search across every space; the plan had it become a jump to a node by its name and path, with Tab in / reaching every space.
• A card's notes are made in the space's root, not in the folder being browsed.
• o does not offer the space's templates; :new <template> does.

Fixed before, on 2026-10-21

After the seven slices of the feature plan (trash 8ffad63, revisions fc2be66, links a42f907, capture tokens f629f5a, diary 824f2bb, recurring cards 6673298, search in files 909abf5), writing the wiki, taking the screenshots and probing the API turned these up:

	finding	fix
1	A rename sent the whole node without the version it had seen, so it could write a stale draft over a save made elsewhere.	3a6ad94: a rename sends the name alone, with the tile's updated_at when the document is open, and is refused like :w when it was saved since.
2	PUT /api/nodes/{id} without body emptied the document.	3a6ad94: every field changes only when it is sent.
3	A search of only punctuation answered with the list of spaces.	a1f6f60: it finds nothing.
4	The agenda grouped cards and opened itself by the browser's day, not WORKSPACE_TIMEZONE, and took a day to be 24 hours.	0e0d215: the agenda answer carries today with its bounds, from the same day_bounds the mails use.
5	Two spaces could share a name.	a1f6f60: refused, in any case or by slug, for a new space, a rename, and mkdir at the root of the mount.
6	Names had no length limit.	a1f6f60: at most 200 characters.
7	A hard-wrapped paragraph rendered with a break in every line.	767dd07: a paragraph that looks wrapped at a width has its soft breaks read as spaces; hand-broken lines and explicit breaks stay.
8	A fresh clone did not compile before the frontend was built.	a59ba4a: allow_missing on the embed.
9	Indexing a file walked every file node on each write, and the excerpt did not mark the match.	c72b65f: a write reads only the folder it wrote into, and the matched words are lit.

Still open, on purpose

• Results from documents and from files are ranked by two separate BM25 indexes, so their order relative to each other is approximate. A shared rank would mean one index for both, which costs more than it gives for a list this short.
• PDFs and office documents are not read for search. That needs a parser crate, and waits until it is missed.

Before the first wiki publish: GitHub creates a wiki's repository only when its first page is saved, so save any page once in the repository's Wiki tab. .github/workflows/wiki.yml replaces it on its first run.

Next, unplanned

The backlog, fitted to the model rather than given new surfaces:

• Install the app on a phone (a PWA: manifest plus a service worker for the app shell, CSP worker-src 'self'), with a share target that posts into capture as a note. The touch and desktop menus are already the same.
• Task lists: toggle - [ ] in the reader, and the open ones of a space as a section of the agenda rather than a :tasks command.
• A daily review, also as a section of the agenda: yesterday's entry, what was finished this week, and cards in doing for more than 14 days.
• Mail-in capture: IMAP polling of a plus-address onto the scratchpad.

Dropped: marks (ma … mz). The info sheet's headings and the tiles cover what they were for, and m stays picking nodes up.

Suggested next: the PWA.