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/file-watchers/_index.md

@@ -0,0 +1,5 @@
+---
+theme: file-watchers
+heading: "File watchers"
+kind: theme
+---

todo/file-watchers/watch-a-directory-and-attach-actions-to-what.md

@@ -0,0 +1,45 @@
+---
+id: file-watchers/watch-a-directory-and-attach-actions-to-what
+title: "Watch a directory, and attach actions to what lands in it"
+theme: file-watchers
+status: open
+created: 2026-08-21
+date_source: stated
+order: 1
+---
+
+**Watch a directory, and attach actions to what lands in it.** Wanted 2026-08-21. The owner sets a
+watcher on a path and configures what happens when a file appears there — the general mechanism,
+not one hard-coded flow.
+
+**The driving use case, end to end:** instead of opening a chat, record an audio note; it lands in
+a watched directory; the existing transcription path turns it into a text file; and on the watch,
+an agent picks the new files up and files them as todos. So the owner can capture an idea with no
+session open and no phone unlocked into the right screen.
+
+What it needs, in rough order: a watcher registry (path + what to do), a trigger that fires on
+file arrival rather than on a clock, and a way to hand the file to an agent turn. **The third is
+no longer missing** — see "Speaking into a session from the backend"; the nudger already starts a
+server-side turn with no browser attached. What is missing here is arrival-triggered firing, since
+the existing scheduler is a clock tick.
+
+Open, not decided: whether the watcher is a plugin or core; whether "action" is a task, a
+prompt from the prompt library, or a chat message; and how a file is marked consumed so it is not
+picked up twice.
+
+**The split, settled by the owner 2026-08-21: it is two stages, and only one of them is an
+agent.**
+
+1. **Audio lands → transcribe.** Purely mechanical: watch the directory, call the transcription
+   service, write the markdown out. A script and a service call, no model anywhere. This is the
+   part that genuinely needs building, and building it as a script is the point — an agent here
+   would be cost and nondeterminism for a job with one correct answer.
+2. **Markdown appears → read, understand, act.** Reading a note and deciding it is a todo (and
+   which one, and where it belongs) is real agent work. This half needs no new infrastructure:
+   a recurring agent job already does it — the same hourly loop that logs a heartbeat can instead
+   be told "look in this folder for new markdown and file what it contains". The prompt is the
+   configuration.
+
+So the watcher to build is the dumb one. What a built-in watcher buys over a standing agent job
+for stage 2 — arrival-time firing instead of a poll, a UI to manage watchers, working with no
+session open — is worth re-asking then, not now.