docs: revise to a three-surface model (CLI/TUI/nvim) from a Todoist study

Study of the owner's live Todoist (387 tasks, 34 hierarchical projects)
grounds a surface-strategy revision: structured task fields suit CLI flags,
large-set triage suits an interactive TUI, and context/KB suits nvim — so v1
adopts three surfaces, each to its strength. Supersedes the earlier
"heph.nvim is the primary surface" framing.

- design.md: new §6.2.1 (Todoist study) + revised §4 (three-surface model)
- tech-spec §1/§8: reframe surface roles; new §8.1 (planned heph-tui agenda)
- tech-spec §14: reorder remaining work (CLI-complete task surface in progress,
  heph-tui next, nvim navigation polish, tags/hierarchy deferred)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/explanation/design.md

@@ -89,7 +89,11 @@ A **recurring task** carries an **RFC-5545 RRULE** and acts as a recurring **def
 
 Layers, top to bottom:
 
-- **Surfaces (thin clients):** the **nvim plugin (`heph.nvim`)** is the **primary surface for v1** — a full "org-mode"-style experience (markdown buffers backed by `doc` nodes; agenda / "what is next" / capture / linking / journaling as plugin commands). It is the explicit **successor to obsidian.nvim**, which the owner currently drives the ZK with (telescope picker, `<Leader>o*` verbs, `<Enter>` to follow `[[wiki-links]]`, dailies, multi-state checkboxes) and rarely uses Obsidian-proper alongside. heph.nvim must reach that feature parity (see §6.5) and replace it. The **CLI** (`heph`) is a secondary/utility surface (export, scripting, admin) — explicitly *not* a focus, though it shares the same command surface. The **web UI** is the occasional hub-served surface. A later iOS/Watch client talks to the hub directly.
+- **Surfaces (thin clients) — a three-surface model (revised 2026-06 after the §6.2.1 Todoist study; supersedes the earlier "nvim is *the* primary surface" framing).** Tasks and knowledge pull in different interaction directions, so each surface plays to its strength rather than one trying to do everything:
+  - **`heph.nvim` — the primary *context / knowledge-base* surface.** The full "org-mode"-style experience (markdown buffers backed by `doc` nodes; wiki-links, journaling, the canonical-context doc, per-task log, checklists). The explicit **successor to obsidian.nvim** (telescope picker, follow `[[wiki-links]]` on `<Enter>`, dailies, multi-state checkboxes); must reach that parity (§6.5). It surfaces tasks for **navigation/reading and context**, not as the primary place to *edit* structured task fields.
+  - **`heph` CLI — capture/scripting + the complete daemon API.** Every structured task field is a flag (`-a red --do tomorrow --late fri --recur weekly --project Maintenance`), which is exactly what command-line flags are good at and dissolves the "how do I edit N structured fields" problem. The CLI implements the *entire* API (admin, sync, conflicts, export) so it is also the scripting/automation surface.
+  - **`heph-tui` — the primary *task agenda / triage* surface (planned, [[tech-spec]] §8.1).** The §6.2.1 study shows the dominant task activity is *interactive triage of a large set* (daily orange reconfirm, blue keep/drop review, browse-by-project) — work that is awkward as either CLI flags or nvim buffers. A terminal UI owns that, and **launches into nvim** for a task's context (and nvim launches back). Not yet built.
+  - The **web UI** is the occasional hub-served surface. A later iOS/Watch client talks to the hub directly.
   - 🔒 **Single binary, three modes.** One Rust binary runs as `local` / `server` / `client` ([[tech-spec]] §3.1); the `heph` CLI shares the same command surface. Mode is two orthogonal axes (backend + inbound listener) plus an optional `hub_url` that makes any `local` instance a syncing **spoke** — the everyday device is `local` + `hub_url`, the hub is `server`, `client` is the online-only convenience.
 - **Per-device daemon (`hephd`):** owns the local SQLite handle, the CRDT/op-log state, and background sync. All local surfaces connect to it over a local socket. This is what makes multi-surface access concurrent and safe on one SQLite file, and gives one place to run background sync.
 - **Core crate (Rust lib):** data model, query engine, markdown parsing + wiki-link extraction, and sync logic. Linked by both `hephd` and the hub server.
@@ -249,6 +253,26 @@ The owner's old rule — "avoid ncurses and interactive UIs; write atomic code a
 
 > 🔒 **DECIDED ranking mechanics ([[tech-spec]] §7):** `do_date` is a *boolean candidacy filter only* (null ⇒ "now"), **never** an urgency input; **`late_on` is the sole urgency signal** (a global "now a problem" top tier); within a band, FIFO by `created_at` — **age never becomes urgency**. The order is expressed as a reorderable named-dimension list so it can be retuned without touching the engine.
 
+### 6.2.1 Todoist study (2026-06): empirical confirmation + new requirements
+
+> 📊 **Snapshot of the owner's live Todoist** (read via the blumeops `blumeops-tasks` API pattern), to ground heph against how the discipline of §6.2 *actually* manifests at scale. 387 active tasks, 34 projects.
+
+**Confirms the model:**
+
+- **Projects = contexts, used heavily and hierarchically.** 34 projects organized into top-level life-areas (`Life`, `Work`, `Coding`, `Camano`, `Culture`) → sub-projects (`Child`, `Blumeops`, `Daily Routine`, `Maintenance`, `Movies`…). The *hierarchy* is new information (§6.2 listed projects flat).
+- **Huge backlog, tiny hot set.** Priority split p1=2, p2=8, p4(default)=229, p3=148 — i.e. the genuinely "hot" set is ~10, the rest is white/blue backlog. The dominant *activity* is therefore **triage of a large set**, not editing single tasks — a direct argument for an interactive agenda surface (§4, [[tech-spec]] §8.1).
+- **Do-date, not due-date — validated to the hilt.** **Zero** Todoist *deadlines* are used; only 107/387 carry a due (do) date. `late_on` will be genuinely rare.
+- **Recurring checklists are real** ("Prep For Day", every day @ 07:00, 6 children) — exactly the §3.3 reset-each-occurrence mechanism.
+- **Daily rituals exist as tasks**: "Excess Tasks to On Deck" (= the blue keep/drop review), "Coordinate with Allison", "Check Personal Email" (= orange reconfirm). The §6.2 working-set rituals are alive in the data; the TUI should make them first-class filters.
+
+**The strongest validation — descriptions are already heph.** Real task descriptions contain `see [[review-services]]`, `See [[run-1password-backup]]`, `docs/how-to/plans/migrate-forgejo-from-brew`, plus URLs and phone numbers. The owner is **hand-rolling task↔knowledge-base wiki-links inside Todoist descriptions that cannot resolve.** heph's task → canonical-context-`doc` fusion (§6.3) is precisely the thing being worked around. (89/387 tasks carry a description; the task description ≡ heph's canonical context doc body.)
+
+**New requirements surfaced:**
+
+- **Project hierarchy** — a project needs an optional parent project. (Model it with the existing `parent` link; deeper hierarchy-aware `scope` is a later refinement.)
+- **Natural-language recurrence** — 95/107 dated tasks recur, expressed as `every 3 days`, `every 6 months`, `every workday`, `every April 15`, `every other wed`. heph stores RFC-5545 RRULE; capture should accept the common NL forms and compile them (the easy subset; time-of-day like "at 08:00" deferred — heph's `do_date` is date-grained for ranking).
+- **Tags are noise** — 7 labels, **5 task-uses across 387**. Confidently **defer** a tag surface; it is not load-bearing.
+
 ### 6.3 Two kinds of task: commitments vs. context items
 
 > 🔒 **DECIDED (shape).** A **commitment axis** orthogonal to the §6.2 attention-states.