todo: one file per item, grouped by theme, with a generated index

TODO.md had reached 1050 lines and 72 open items across 28 sections, read mostly
on a phone. It is now a directory: todo/<theme>/<item>.md, one card per file, with
frontmatter carrying id, status, created date and order, and the prose body copied
across verbatim. TODO.md becomes a generated index (bun run todo:index).

Dates: where an item's prose stated one it is used; otherwise its old section's;
otherwise 2026-08-20, floored at the day before the split rather than invented.
date_source records which.

Shaped for a two-way Kanban board, filed as todo/tooling — a card is a file, id is
the identity, frontmatter is the machine's half and the body is the owner's.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

todo/files-app/_index.md

@@ -0,0 +1,16 @@
+---
+theme: files-app
+heading: "Files app — routing"
+kind: theme
+---
+
+**The URL model is done (2026-08-15).** The folder is the pathname —
+`/files/archive/Tests/platform/docs` — and `?view=` is a NAME within it, not a second copy of the path.
+Deep links and refresh work, which they never had. Landed across `559560de`, `98ba604a`, `7e31564c`,
+`0dc88b51`, `7359af2f`, with `files-route.ts` + 23 tests as the one owner of encoding and of which params
+belong to the overlay.
+
+Four bugs came out of that work and are fixed: closing a pane sent you home; `?view=` was stripped on
+every page load by a mount effect that had made deep links impossible since 2026-02-23; navigating kept a
+pane belonging to the folder you left; and the breadcrumb opted out of that last rule because it is a
+`<Link>` and never called the function enforcing it.

todo/files-app/a-panel-s-folder-is-still-not-addressable.md

@@ -0,0 +1,14 @@
+---
+id: files-app/a-panel-s-folder-is-still-not-addressable
+title: "A panel's folder is still not addressable"
+theme: files-app
+status: open
+created: 2026-08-20
+date_source: assumed
+order: 3
+---
+
+**A panel's folder is still not addressable.** `urlPath` is true only on the `/files` screen;
+panels keep the path in local state, so they always open at their base and cannot be linked or
+restored. Deliberate as written — a dashboard can hold two browsers and one URL cannot serve both —
+but worth re-deciding rather than inheriting.

todo/files-app/rows-are-still-not-links.md

@@ -0,0 +1,24 @@
+---
+id: files-app/rows-are-still-not-links
+title: "Rows are still not links"
+theme: files-app
+status: open
+created: 2026-08-20
+date_source: assumed
+order: 1
+---
+
+**Rows are still not links.** This is the half that did not get done, and it is the original
+finding. Both list and grid render `<div onDoubleClick>` (`FileItem.tsx:701,748`), and search
+results render `<div onClick>` (`FileViewContainer.tsx:187`) — the "opaque click" that
+`docs/navigation-audit.md` names. No cmd-click into a new tab, no middle-click, not
+link-focusable, and the target lives in a closure rather than the DOM.
+
+It is now much easier than it was: `folderHref(path)` gives a folder's URL and `hrefForPath` gives
+a full `To` with the overlay already stripped, so a row becomes
+`<Link to={hrefForPath(childPath)}>` and a file row becomes a link that sets `?view=<name>`. The
+breadcrumb has done exactly this since before today and is the model.
+
+Watch for: a row is also a click target for SELECTION (single click selects, double opens,
+shift/cmd extend). An anchor changes what those gestures mean by default, so the selection
+handlers have to keep working and `preventDefault` where they win.

todo/files-app/the-acts-that-clear-the-overlay-have-no-owner.md

@@ -0,0 +1,15 @@
+---
+id: files-app/the-acts-that-clear-the-overlay-have-no-owner
+title: "The acts that clear the overlay have no owner, only the list does"
+theme: files-app
+status: open
+created: 2026-08-20
+date_source: assumed
+order: 2
+---
+
+**The acts that clear the overlay have no owner, only the list does.** `VIEWER_PARAMS` and
+`withoutViewerParams` live in `files-route.ts` and are shared. But every site still decides FOR
+ITSELF whether to call them, which is precisely how the breadcrumb shipped wrong an hour after the
+rule was written. Three bugs in a row came from this. A single `navigateToFolder()` that every
+caller must go through — rather than a helper they may remember — is the fix if a fourth appears.