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.

The navigation fixes

The plan's navigation fixes sat outside the numbered slices, and landed after them, in one commit:

• The list is by name, folders first, everywhere but the diary, which stays a journal by day; a document's row there shows when it was last edited.
• Ctrl-P goes to anything by its name, in every space (GET /api/jump): the last word is looked for in the name, the ones before along the path. / is the one full-text search, and Tab on its line takes it to every space.
• A card's notes are made in the folder being browsed when that is in the card's space, and a [[missing]] link's document beside the one linking to it.
• o in a space with templates offers them on the line, :new ; Enter on nothing is still a blank document.

The phone app, done

Written on 2026-10-22. The workspace installs on a phone as an app:

• A manifest (web/public/manifest.webmanifest) with a 192 and a 512 icon and a maskable one, drawn from the favicon.
• A service worker (web/src/sw.ts, built by a small plugin in vite.config.ts) keeps index.html, the logo, the entry with what it imports, and the latin fonts, and every hashed asset once it has been fetched. Pages are asked of the server first and answered from the cache when it is down. It never touches /api. The CSP names worker-src and manifest-src.
• A share target, POST /share, caught by the worker and never sent to the server: the text waits in the cache share and becomes a scratchpad note once someone is logged in.
• Back, on a touch screen, lets go of one thing at a time through one guard entry in the history (back() in modes.ts), and leaves the app at the root of a space.
• The bar and the band grow by the safe-area insets, so an installed app keeps them clear of the status bar and the gesture bar.

Not done, on purpose: reading documents offline, and sharing a photo or a file — a file needs a document or a folder to belong to, and a note has neither. iOS has no share target, so the iPhone keeps the Shortcut.

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:

• Read on a phone with no network: the documents opened last, kept by the service worker or in IndexedDB, and cleared on logout.
• Share a photo or a file into the app: it asks which document or folder it belongs to.
• 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: task lists and the daily review, as sections of the agenda.