kankaku 0.12.1 → 1.0.0

package/README.md

@@ -1,1430 +1,472 @@
 # kankaku
 
-A [pi](https://pi.dev) extension that measures how long an agent actually
-spends working on each prompt, so the time can later be accounted for
-(billing, reporting).
+A standalone terminal app, `kankaku`, that reads every project's
+`.kankaku/worklog.jsonl` under a configurable list of roots and shows the
+day across projects — the one view the [kankaku](https://kankaku.io) pi
+panel cannot give, since it only ever sees the one project pi is running
+in. Built with [Ink](https://github.com/vadimdemedes/ink) on Node 24. Four
+screens — Dashboard, Tasks, Catalog and Sync — share one tab bar, and each
+has a plain-text subcommand for scripts and cron.
 
-Docs and guide: [kankaku.io](https://kankaku.io). This package lives in
-the [kankaku monorepo](https://github.com/soyunninja/kankaku), under
-`packages/kankaku`.
+This package lives in the [kankaku monorepo](https://github.com/soyunninja/kankaku),
+under `packages/cli`. It was published as `kankaku-tui` up to 0.12.1; the
+`kankaku` npm name is now this package (the pi extension moved to
+`kankaku-pi`).
 
-## What it measures
-
-For every prompt, kankaku tracks the span from `before_agent_start` to
-`agent_settled` (or to `session_shutdown` if pi exits mid-run) and splits it
-into:
-
-- **`waitingMs`**: time pi spent blocked on the user — the union of
-  `ui_prompt_start/end` spans and the execution spans of configured
-  interactive tools (default `ask_user_question`, `ask_user_choice`). Union
-  avoids double-counting when a tool internally triggers a UI prompt.
-- **`workMs`**: `wallMs - waitingMs`, the actual work time.
-
-Every pi process — the orchestrator and any subagent child spawned by
-`subagent_run` — records its own prompt-to-idle spans, tagged with a `role`
-(`orchestrator` or `subagent`) and its `pid`/`parentPid`, so records can be
-joined later.
-
-## Install
-
-kankaku is a pi package. Pick one source:
+## Install everything
 
 ```
-pi install npm:kankaku                                    # from npm
-pi install git:github.com/soyunninja/kankaku              # from git (add @v0.12.1 or later to pin)
-pi install /absolute/path/to/kankaku/packages/kankaku     # local checkout, no copy
+npm i -g kankaku
+kankaku setup
 ```
 
-`pi install` writes to your global `~/.pi/agent/settings.json`, so the
-extension loads in every pi process, including the subagent children that
-`subagent_run` spawns. Use `-l` to install into a project's `.pi/settings.json`
-instead; note that project-local resources load only after the project is
-trusted, which a subagent child may not inherit.
+`npm i -g kankaku` installs the `kankaku` command, the bundled Claude Code
+plugin (`kankaku-claude`) and the pi extension. The extension is carried
+inside the tarball, under `vendor/kankaku-pi/`, and the package's `pi`
+manifest points at it, so `pi install npm:kankaku` also works and loads
+exactly the extension `kankaku-pi` ships. It is vendored rather than
+declared as a dependency because pi installs npm packages into one shared
+directory with a flat `node_modules`: a dependency of `kankaku` would not
+sit next to it, and pi could not find the extension.
+
+If you only use pi and do not want the dashboard, install the light
+package instead: `pi install npm:kankaku-pi`.
+
+### Do not load the extension twice
+
+The extension is reachable through several sources: `npm:kankaku-pi`,
+`npm:kankaku`, the `git:github.com/soyunninja/kankaku` repository and a
+local checkout. Listing more than one of them in the same pi settings file
+loads the extension more than once and doubles every measurement.
+`kankaku doctor` reports it (`pi: todo — loaded 2 times: npm:kankaku,
+npm:kankaku-pi`), and `kankaku setup` repairs it, keeping exactly one
+source by this precedence: a local path, then `npm:kankaku-pi`, then a
+`git:` source, then `npm:kankaku`. Nothing else in the file is touched and
+the original is saved once as `settings.json.bak`. An install with only
+`npm:kankaku` is configured and is left as it is; new installs write
+`npm:kankaku-pi`. Entries in pi's object form
+(`{ "source": "npm:kankaku-pi", "extensions": [...] }`) count as well.
+Unchecking pi in the wizard removes every kankaku source.
+
+### Migrating from `kankaku-tui`
+
+`kankaku-tui` is retired and its package is deprecated in favour of
+`kankaku`. Both packages provide the `kankaku` command, so uninstall the
+old one first, then install the new one and run setup again:
 
-To try it without installing: `pi -e /absolute/path/to/kankaku/packages/kankaku`.
+```
+npm uninstall -g kankaku-tui
+npm i -g kankaku
+kankaku setup
+```
 
-## Quick start
+On a real terminal, `kankaku setup` opens as a full-screen wizard — one
+step at a time, in the same header/panel/footer look as the rest of the
+app (there's no sidebar in the wizard itself: the panel's own title
+tracks progress instead, e.g. `Setup · Agents 1/4`). `kankaku` with no
+arguments does the same the very first time (no `~/.kankaku/tui.json`
+yet); after that first run it opens straight into the Dashboard as usual.
+
+The wizard's steps, `enter` to advance and `esc` to go back throughout
+(`esc` at the first step, Agents, quits):
+
+1. **Agents** — a checklist (`space` toggles) that also carries detection
+   for every agent kankaku knows about: pi, gentle-shell and Claude Code
+   each show `configured (<path, shortened with ~>)` or `not configured`;
+   pre-checked means already configured, and unchecking a configured
+   agent schedules removing kankaku from it, not just skipping it. Codex
+   and OpenCode are listed but disabled, showing `no adapter yet` (found,
+   but kankaku can't write its config) or `not installed` (not found).
+   Checking Claude Code needs no extra step or path — see "Claude Code"
+   below.
+2. **Hub** — `use an existing hub` (URL, email, masked password, a `c`
+   inline health check, reusing the current credentials as the default),
+   `install locally`, or `skip`. Installing locally asks only for the
+   owner's email and password and then runs the same installer as
+   `kankaku hub install` (see "Local hub" below): no `kankaku-hub`
+   checkout is needed, and the wizard writes the local hub's service
+   account as this machine's hub credentials. The wizard always uses the
+   default port; if another process already holds it the step fails with
+   the port-in-use message, and `kankaku hub install --port <N>` is the
+   way to pick another one.
+3. **Roots** — the comma-separated project roots, defaulting to the
+   current `tui.json` (or the parent of the current directory the first
+   time). See "Configuration" below for how deep each root is searched.
+4. **Review** — the plan: one line per change, with the exact file it
+   touches. `enter` applies it.
+5. **Apply** — runs each change and shows its result
+   (`wrote`/`unchanged`/`removed`/`started`/`error: …`) as it happens.
+6. **Done** — a summary, then `enter` opens the Dashboard in place — no
+   restart.
+
+### Claude Code
+
+Checking Claude Code (in the wizard, or answering yes in `kankaku setup`'s
+non-interactive flow) writes two things into `~/.claude/settings.json`,
+merged in — every other key, every foreign hook and every other event is
+left untouched — and installs the slash commands:
+
+- `statusLine.command`, so Claude Code reports per-prompt cost.
+- `hooks` for every event the bundled `kankaku-claude` plugin declares
+  (`packages/claude/hooks/hooks.json`), so the plugin actually measures
+  time even when Claude Code is started as plain `claude` — **no
+  `--plugin-dir` flag needed**.
+
+It also installs the `/kankaku:*` slash commands (`/kankaku:report`,
+`/kankaku:status`, `/kankaku:task`, `/kankaku:sync`, …) as user commands under
+`~/.claude/commands/kankaku/<name>.md`, generated from the plugin's own
+`commands/*.md` with the plugin's absolute install path filled in. Setup
+lists each file it wrote or left unchanged; `kankaku doctor` reports Claude
+Code as configured only when the installed state equals what the plugin
+expects: the exact statusLine command, every hook event in the plugin's
+`hooks/hooks.json` with the same command, matcher and timeout, and every
+command file byte-identical to the generated one, with no stale generated
+file left. Anything else is `todo`, and the note names what is wrong (for
+example `hooks missing: Stop, SessionEnd; commands missing: sync; commands
+outdated: status`), including after an upgrade that adds a command or hook
+event. `kankaku setup --yes` reconciles a selected Claude Code every time,
+so a damaged or outdated install is repaired. A file in that directory that kankaku did not
+generate is never overwritten or removed, and setup says so. **Re-run
+`kankaku setup` if the install path changes** — for example after switching
+Node versions, which moves the global `node_modules`.
+
+`kankaku` depends on `kankaku-claude` directly (lockstep, same as its
+`kankaku-pi`/`kankaku-hub` dependencies), so the plugin's files ship inside
+every `kankaku` install; setup resolves their location on disk itself.
+There is nothing to check out and no second `npm install`.
+
+**If you previously ran Claude Code with `--plugin-dir <checkout>` to load
+kankaku-claude, drop that flag once `kankaku setup` has configured Claude
+Code** — the hooks it now writes into `settings.json` run on every Claude
+Code launch regardless, so a `--plugin-dir` load on top of that would run
+the hooks twice and double-write worklog records. The `/kankaku:*` slash
+commands do not need it either: setup installs them as user commands.
+
+Unchecking Claude Code (or removing it from an already-configured
+machine) removes exactly kankaku's own statusLine and hooks entries,
+leaving everything else in `settings.json` untouched, and removes the
+generated command files (plus the `kankaku/` directory once it is empty,
+and never anything else under `~/.claude/commands`).
+
+**Overriding the plugin root.** For local development, or to point at a
+different kankaku-claude checkout, pass `--claude-plugin-dir <dir>` to
+`kankaku setup`/`kankaku setup --yes`/`kankaku setup --dry-run`, or set
+`KANKAKU_CLAUDE_PLUGIN_DIR`. The flag/env value must be a directory
+containing `hooks/hooks.json` and a built `dist/hook.js` (i.e. a
+`kankaku-claude` checkout or `packages/claude` in a kankaku monorepo
+checkout, after `npm install && npm run build` in it — Node cannot run a
+plugin's `.ts` sources directly once they are outside a fresh checkout,
+so setup reports "run npm run build in `<dir>` first" when the build is
+missing). Without either, setup resolves the bundled package
+automatically — most users never need this.
+
+`kankaku setup --yes` and `kankaku setup --dry-run` stay exactly as
+before: non-interactive, driven by argv/env only, never opening the
+wizard (even on a TTY). `--yes` accepts every question's own default
+without asking; `--dry-run` prints the plan — each step's state
+(`done`/`todo`/`unavailable`) and the exact file it would change —
+without writing anything. Nothing is ever written without either an
+explicit answer (in the wizard or the `--yes`/readline flow) or `--yes`
+itself. Before the first change to any file, kankaku setup creates a
+`<file>.bak` next to it; re-running `kankaku setup` in any form is always
+safe, since it only ever writes what is still missing or what you
+explicitly change.
+
+`kankaku setup` ends with, and `kankaku doctor` prints on its own, the
+same read-only report: one line per agent, one for the hub, one for
+`tui.json`, and a `next: …` hint for anything still `todo`.
 
-Once installed, kankaku records every prompt on its own; there is nothing
-to start. Inside pi's TUI, type `/kankaku` to open the panel, the one
-place everything is managed from:
+## Install
 
 ```
-╭─ >_ kankaku ─────────────────────────────────────────╮
-│                                                      │
-│ → Target        Billing client, project, hub task    │
-│   Report        Today/all totals, tasks, sessions    │
-│   Sync          Status, sync now, sync all, backfill │
-│   Export        Write today's or every task as csv   │
-│   Doctor        Orphan/uncertain subagent counts     │
-│   About         Versions, KANKAKU_DIR, hub URL       │
-│                                                      │
-│ ↑↓ move · enter open · esc close                     │
-╰──────────────────────────────────────────────────────╯
+npm install -g kankaku
 ```
 
-- **Target** is where you pick the client and project the time is billed
-  to and, with a hub, the task you are working on right now.
-- **Report** shows today's work, waiting and cost, per task or grouped by
-  client or project.
-- **Sync** pushes the consolidated tasks to your hub when one is configured.
-
-Every panel action is also a subcommand (`/kankaku tasks`, `/kankaku sync`,
-…) for scripts and headless runs — see "The `/kankaku` command" below. The
-footer clock (`🕒 03:12 · acme`) shows the running prompt's elapsed time
-and billing client while an agent works.
+Then run `kankaku setup` (or just `kankaku` the first time) to configure
+the coding agents on this machine, the hub and your project roots. The
+package depends on the published `kankaku-pi` library (`kankaku-pi/domain`,
+`kankaku-pi/hub`), on `kankaku-hub` for the local hub installer, and on
+`kankaku-claude` for the bundled Claude Code plugin files (see "Claude
+Code" above); nothing else needs to be checked out. To work on this repo
+itself, run `npm install` inside it and `npm run dev`.
 
-## Record schema
+## Configuration
 
-Each line in `worklog.jsonl` is one JSON object:
+`~/.kankaku/tui.json`:
 
 ```json
 {
-  "schema": 1,
-  "id": "uuid",
-  "role": "orchestrator",
-  "pid": 4242,
-  "parentPid": 4000,
-  "project": "/abs/project/path",
-  "sessionId": "…",
-  "sessionFile": "…",
-  "mode": "tui",
-  "model": "anthropic/claude-opus",
-  "client": "acme",
-  "sessionName": "billing sprint",
-  "sessionDir": "/abs/custom/session/dir",
-  "clientId": "pocketbase-record-id",
-  "clientName": "Acme",
-  "projectId": "pocketbase-record-id",
-  "projectName": "Portal",
-  "machine": "laptop",
-  "agent": "pi",
-  "agentVersion": "0.87.1",
-  "plugin": "kankaku",
-  "pluginVersion": "0.7.1",
-  "prompt": "first 200 chars of the first prompt",
-  "startedAt": "2026-09-10T16:00:00.000Z",
-  "settledAt": "2026-09-10T16:04:10.000Z",
-  "wallMs": 250000,
-  "waitingMs": 30000,
-  "workMs": 220000,
-  "runs": 2,
-  "turns": 9,
-  "tools": { "bash": 4, "read": 3, "subagent_run": 1, "ask_user_question": 1 },
-  "subagents": [{ "toolCallId": "…", "agent": "sdd-explore", "mode": "task", "taskId": "t1", "ms": 90000 }],
-  "segments": { "review": 62000 },
-  "usage": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "cost": 0 },
-  "status": "completed",
-  "roleConfidence": "uncertain",
-  "orchestratorRef": { "pid": 4000, "project": "/abs/other-worktree", "startedAt": "2026-09-10T15:59:00.000Z", "dir": "/abs/other-worktree/.kankaku" }
+  "roots": ["/absolute/path/to/workspace", "~/another-workspace"]
 }
 ```
 
-`status` is one of `completed`, `aborted` (the last assistant message had
-`stopReason: "aborted"`), or `interrupted` (pi shut down while still
-running).
-
-`runs` counts the agent loops inside the record: the first one plus every
-continuation pi ran before settling it (an automatic retry after a provider
-error, overflow recovery, a queued steer or follow-up). Informational only.
-
-`trigger` is optional. `"extension"` marks a record no user prompt started:
-an extension woke the agent itself — this is how gentle-pi resumes the
-orchestrator when a background subagent finishes. Its `prompt` is the fixed
-text `(no user prompt — run started by an extension)`. Without it that work
-would not be recorded at all, since pi only announces user prompts.
-
-`roleConfidence` and `orchestratorRef` are both optional and normally
-absent — see "Subagents" below. `roleConfidence` is only ever set to
-`"uncertain"`, and only on an `orchestrator`-role record kankaku could not
-positively prove top-level; `orchestratorRef` is only ever set on a
-`subagent`-role record that discovered its tracked ancestor via the
-machine-wide process registry. Its optional `dir` field carries that
-orchestrator's resolved kankaku directory — the real top-level one even
-across a subagent-of-subagent chain — and is what this process's own
-work log and inflight checkpoints were actually routed into when it
-differs from this process's own (see "Subagents" > "Cross-worktree write
-routing"). Neither field, nor `orchestratorRef.dir`, bumps
-`WORK_RECORD_SCHEMA` — a record without them (from an older kankaku build)
-remains valid.
-
-`clientId`, `clientName`, `projectId`, `projectName` and `machine` are only
-present once a hub is configured (see "Hub (PocketBase)"); every report and
-export written before this feature, or by a user without a hub, is
-unaffected. `hubTaskId`/`hubTaskTitle` are set alongside them only when a
-hub task is linked to the session (`/kankaku task pick`) — see "Linking to
-a hub task" below.
-
-`sessionDir` is present only when pi's session manager reports a
-*non-default* session directory (`--session-dir`, or a resumed session
-started that way) — exactly the condition under which pi's own printed "To
-resume this session: ..." line includes `--session-dir`. Most records never
-carry it. `/kankaku doctor` shows it for the current session when set, and
-it is available on a task's orchestrator record (`TaskView.sessionDir`) for
-anything that wants to reconstruct the exact `pi --session-dir <dir>
---session <id>` resume command locally. When a hub is configured it is also
-sent as `session_dir` on every sync (see "Hub (PocketBase)" > "Sync" >
-"Agent and measurement quality").
-
-`agent`, `agentVersion`, `plugin` and `pluginVersion` are optional and
-identify who *measured* this record, not who later syncs it: a worklog can
-be synced by a process that did not write it (a standalone `kankaku` TUI
-syncing pi's records; a session syncing a directory another agent also
-wrote to), so this identity travels with the record instead of being
-resolved fresh by whichever process happens to push it to the hub. For a
-record this package writes, `agent` is always `"pi"` and `plugin` is always
-`"kankaku"`; `agentVersion`/`pluginVersion` are included when known and
-omitted rather than guessed. Neither field bumps `WORK_RECORD_SCHEMA` — an
-older record without them stays valid and falls back to the syncing
-process's own identity on create only (see "Hub (PocketBase)" > "Sync" >
-"Agent and measurement quality").
-
-## Task and session views
-
-Each `WorkRecord` still measures one pi process's own prompt-to-idle span.
-But a `subagent_run` in `background` mode returns immediately while its
-child process keeps working, so the orchestrator's own `wallMs` can
-under-report how long the task actually took. Two derived, read-only views
-correct for that, built purely from `pid`/`parentPid`/`startedAt`/`settledAt`
-already present on every record — no new fields are persisted to
-`worklog.jsonl`.
-
-- **Task**: one *confirmed* orchestrator record (see "Subagents" below —
-  an orchestrator-role record flagged uncertain never anchors a task) plus
-  every subagent record matched to it — `parentPid === orchestrator.pid`
-  and the child's `startedAt` falling inside the orchestrator's
-  `[startedAt, settledAt]` window; `project` is only a **hint**, preferred
-  when it matches but never a hard filter (see "Subagents"). (If a pid is
-  reused across runs and several orchestrator records match, a same-project
-  candidate is preferred, then the latest-starting one.) A task's `wallMs`
-  is the **union** of the orchestrator's interval and every matched child's
-  interval — never their sum — so parallel background children are not
-  double-counted, and a child that outlives the orchestrator's own settle
-  time correctly extends the task's span. `waitingMs` is the orchestrator's
-  own waiting time, `workMs = wallMs - waitingMs`, and `usage` is the sum of
-  the orchestrator's and every child's token/cost totals.
-- **Session**: tasks grouped by `sessionId` (tasks with no `sessionId` are
-  grouped under `"unknown"`). A session's `wallMs` is the union of every
-  interval — orchestrator and subagent alike — across all of its tasks;
-  `waitingMs` is the sum of each task's `waitingMs`, and `workMs = wallMs -
-  waitingMs`.
-- **Orphan subagents**: a subagent record with no matching orchestrator
-  record (for example, its parent's record was lost, or a cross-worktree
-  registry entry had already expired) is excluded from every task but is
-  not silently dropped — it stays visible so gaps in the log are noticeable
-  rather than hidden. See "Subagents" for how a cross-worktree child is
-  usually reunited *before* it ever becomes an orphan.
-
-## Subagents
-
-kankaku recognises gentle-pi's `subagent_run` tool as opening a subagent
-span (unchanged from before this section); this describes how it decides,
-for a process that shows no such marker, whether it is a genuine top-level
-session or actually someone's subagent — and how a gentle-pi subagent
-running in a *different git worktree* than its orchestrator still gets
-correctly counted.
-
-### The role/state model
-
-Every record still carries the same binary persisted `role`
-(`"orchestrator"` | `"subagent"`, unchanged — see "Record schema"). On top
-of it, kankaku's task/session views and the hub sync apply a four-state
-classification:
-
-- **orchestrator** — confirmed top-level: no recognised child-env-marker
-  (`GENTLE_PI_AGENTS_CHILD=1`, or an explicit `KANKAKU_ROLE=orchestrator` —
-  see "Interactive sessions and `KANKAKU_ROLE`" below) is present, and
-  either no live tracked ancestor process was found, or this session is
-  itself interactive (see "The registry" and "Interactive sessions" below).
-  This is the default for a plain, ordinary `pi` session — unaffected by
-  any of this.
-- **subagent (joined)** — a gentle-pi child matched to its orchestrator, as
-  described in "Task and session views" above.
-- **subagent (orphan)** — a gentle-pi child that could not be matched to
-  any orchestrator (shown separately, never dropped — `orphanSubagents`).
-- **uncertain** — no recognised child-env-marker, a live tracked ancestor
-  process *was* found, **and** this process is not itself an interactive
-  TUI session: it cannot be proven top-level, so it is never counted as a
-  new task locally and never synced to the hub as one, but it is not
-  dropped either — `WorkRecord.roleConfidence` is set to `"uncertain"` on
-  it, and `/kankaku doctor` (and a one-line hint on the plain `/kankaku`
-  summary) surface it so the gap is visible instead of silently wrong.
-  This is the fix for a real bug: a subagent mechanism kankaku does not
-  specifically recognise (for example, pi's own bundled reference
-  `subagent` example, which sets no env marker at all) used to default to
-  `"orchestrator"` outright — a phantom top-level task on top of the time
-  already measured inside its parent's own tool-call span, billed twice.
-  An unrecognised process now degrades to a safe, visible **undercount**
-  instead of a silent, unrecoverable **overcount**. An *interactive*
-  session is never demoted this way, no matter what its ancestry looks
-  like — see "Interactive sessions and `KANKAKU_ROLE`" below for why, and
-  for the escape hatch when kankaku still gets it wrong.
-
-An `uncertain` classification is recoverable going forward: once the
-mechanism is recognised (for example, by upgrading kankaku, setting
-`KANKAKU_ROLE` explicitly, or — in a later version — registering it via a
-configured tool/env marker), a later `/kankaku sync all` or `backfill`
-picks up the record correctly. It never resolves itself by guessing. A
-record that was *already written* `uncertain`, however, cannot be rewritten
-after the fact — `worklog.jsonl` is append-only and kankaku never edits a
-past line (see AGENTS.md) — so only a run *after* the fix correctly
-anchors a task; there is no migration that goes back and reclassifies old
-lines.
-
-### The registry
-
-Every kankaku process writes a small entry to
-`~/.kankaku/run/<pid>.json` at startup — `pid`, `parentPid`, `role`,
-`project`, its resolved (and, for a routed subagent, actually-used —
-see "Cross-worktree write routing" below) `KANKAKU_DIR`, `startedAt`, and
-`processStartId` (below) — independent of any project's own `KANKAKU_DIR`,
-so it survives a project boundary. Both `~/.kankaku/run` and its entry
-files are created owner-only (`0700`/`0600` — an existing looser mode, left
-by an older kankaku build, is tightened on the next write, best-effort);
-they name absolute project paths and session ids. **The registry is a
-startup-time lookup only** — "who is my tracked ancestor, and where does
-it keep its log" — resolved once, at process factory time, and never
-consulted again later as a live pointer (this used to matter: see
-"Cross-worktree write routing" below for why it no longer does). This is
-what powers both of the following:
-
-- **Uncertain detection**: a process with no child-env-marker walks its own
-  OS ancestor chain (one snapshot, see "Ancestor-chain detection" below)
-  looking for *any* live registry entry whose identity it can actually
-  **prove** — see "Identity, not just pid" below. Finding one means some
-  other tracked kankaku process is an ancestor of this one; combined with
-  this process *not* being an interactive TUI session (see "Interactive
-  sessions and `KANKAKU_ROLE`" below), it is classified `uncertain` rather
-  than defaulting to `orchestrator`.
-- **Cross-worktree write routing** (ADR 0023, rewritten for a real bug —
-  see below): a gentle-pi subagent running in a different git worktree than
-  its orchestrator walks its ancestor chain, finds its orchestrator's
-  registry entry (identity-verified), and resolves it to an
-  `orchestratorRef` (`{ pid, project, startedAt, dir }` — `dir` also
-  resolves through a subagent-of-subagent chain to the real, top-level
-  orchestrator, never a middle hop). When that orchestrator's directory
-  differs from this process's own, the child writes its work log **and**
-  its inflight crash-recovery checkpoints straight into the orchestrator's
-  directory instead of its own cwd-relative one — so parent and child
-  records end up in the *same* `worklog.jsonl` from the moment the child's
-  first record is appended, not merely discovered there later. The
-  orchestrator's later `buildTasks` call joins them with the same
-  `pid`/`parentPid`/project-hint keys it always has; the interval-union
-  rule itself is still computed in exactly one place (`buildTasks`) — this
-  only changes *where the bytes physically live*, never how they are
-  joined. If the orchestrator's directory cannot be created or written to
-  (gone, or no permission), the child falls back to its own local
-  directory instead of losing the record, and `/kankaku doctor` reports the
-  fallback so it can be reunited manually; a record is always written to
-  **exactly one** log, never both. Because reunification no longer depends
-  on any pointer still being alive at read time, it survives the child's
-  own exit cleanup removing its registry entry — which, for gentle-pi's
-  main case (a blocking `subagent_run` in task mode), has already happened
-  by the time the parent regains control. If ancestry could not be
-  established at all (or the write genuinely could not go anywhere), the
-  child stays a visible orphan instead — undercounted, never lost, and
-  never compensated for by summing two independently synced rows: **the
-  hub never sums two unions to recover a missing one**, since that would
-  double-count the overlap between parent and child. `project` is
-  therefore only ever a *hint* for the join (preferred when it matches),
-  never a hard filter.
-- The registry is swept opportunistically (when a process writes its own
-  entry) — see "Registry cleanup and health" below — so it does not grow
-  unbounded and never keeps serving a stale identity.
-
-#### Identity, not just pid — the PID-reuse fix
-
-Matching an ancestor pid to a registry entry by **pid number alone** is not
-safe: operating systems reuse pids. A kankaku process that dies without
-cleanup (a crash, `kill -9`) can leave its `~/.kankaku/run/<pid>.json`
-entry behind; the OS can later hand that same pid to the user's own
-interactive shell, and every *genuine* top-level pi session launched from
-that shell would then falsely resolve a "tracked ancestor" — silently
-misclassified `uncertain` forever, its task never synced. This inverts the
-whole guarantee this feature exists for, so identity is proven, not
-assumed:
-
-- Every registry entry also carries `processStartId`: an approximate,
-  self-consistent epoch-ms estimate of that process's actual OS start time.
-  **This process's own** `processStartId` (the one it records about
-  itself) is derived cheaply and portably — `Date.now() - process.uptime()
-  * 1000`, sampled once at factory time — with **no subprocess spawn and no
-  `/proc` read at all**, so it is available on every platform, Windows
-  included, and never adds startup cost (see "Startup cost" below).
-  Verifying *another* process's (an ancestor's) live identity still needs a
-  fresh reading of that specific pid from an OS ancestor-chain snapshot: on
-  macOS/BSD, `ps -eo pid,ppid,etime` (`[[dd-]hh:]mm:ss` elapsed time,
-  forced through the portable `etime` keyword — BSD `ps` has no `etimes`);
-  on Linux, `/proc/<pid>/stat`'s `starttime` (clock ticks since boot)
-  combined with `/proc/uptime`, assuming the near-universal `USER_HZ=100` —
-  a wrong assumption never causes a false match, since the same (possibly
-  wrong) constant is used both when an entry is written and whenever it is
-  re-verified, and a process's `starttime` ticks never change during its
-  life. `process.uptime()`-derived and `ps`/`/proc`-derived readings of the
-  *same* process instance agree within the same tolerance (2000ms, which
-  also absorbs each source's own second-granularity rounding) — this is
-  cross-checked against a real OS reading by
-  `scripts/e2e-cross-worktree-real-processes.ts`. Windows has no supported
-  source for a *live ancestor's* start time — see "Ancestor-chain
-  detection" — so an ancestor still cannot be identity-verified there, even
-  though this process's own id is now always available.
-- A match is only trusted when **both** sides prove the same identity: the
-  registry entry's own `processStartId` **and** a fresh re-derivation of
-  that live pid's start time (from the ancestor's own current snapshot)
-  agree within tolerance. A pid with a registry entry but a mismatched — or
-  unprovable, on either side — identity is walked past exactly like an
-  untracked hop, not treated as a match; if nothing further up the chain is
-  provable either, ancestry detection reports "no tracked ancestor," which
-  is the same safe fallback as if the registry were empty (this process
-  classifies as a confirmed `orchestrator`, never `uncertain`, from an
-  unprovable candidate alone).
-- A legacy entry with no `processStartId` at all (written by a kankaku
-  build predating this field) is never trusted for identity matching or
-  kept around: it reads as stale and is removed by the normal sweep the
-  next time any process writes its own entry.
-
-#### Registry cleanup and health
-
-- Every kankaku process removes its own entry file on a normal exit and on
-  `session_shutdown` (best-effort, verifying the on-disk file's `pid` and
-  `processStartId` still match its own before unlinking, so it can never
-  remove a file it does not verifiably own) — a crash still leaves the
-  entry for the next sweep. Immediately before unlinking a *discarded*
-  entry, the sweep also re-reads that file and compares it byte-for-byte
-  against what it judged stale: if the pid was reused and a fresh entry
-  already written to the same path in the meantime, the file is left alone
-  instead of destroying a live registration the sweep never actually
-  evaluated.
-- The opportunistic sweep (run whenever any process writes its own entry)
-  removes: entries for a dead pid; entries whose pid is alive but whose
-  recorded identity no longer matches that live process (pid reuse); and,
-  as a last resort, entries older than 7 days regardless of
-  aliveness/identity. An entry with **no verifiable identity at all**
-  (legacy/malformed, no `processStartId`) is *never itself* grounds for
-  deletion while its pid is alive and within the age ceiling — such an
-  entry is never *used* for ancestor matching either way (matching always
-  requires a verifiable `processStartId` on both sides), but deleting it
-  outright used to risk un-registering a genuinely live orchestrator whose
-  own start-time read happened to fail, at the mercy of an unrelated
-  sibling process's sweep. It still gets cleaned up the ordinary way, once
-  its pid dies or it ages out. The sweep never removes the entry the
-  writing process itself just wrote.
-- `/kankaku doctor` reports registry health: how many entries it currently
-  trusts, how many it would discard, and why (dead / stale-reuse /
-  over-age).
-
-### Ancestor-chain detection
-
-Reading "a live tracked ancestor process" above requires one OS-level
-ancestor-chain snapshot. On Linux this is a set of `/proc/<pid>/stat` reads
-(ppid and start-time ticks together, plus one `/proc/uptime` read); on
-macOS, one `ps -eo pid,ppid,etime` snapshot (ppid and
-elapsed-time-since-start together); a shell-wrapper hop with no registry
-entry of its own is walked past, not stopped at.
-
-**Startup cost.** This snapshot is taken at most once per process, at
-extension startup, never on a later hot path — and, since it is the only
-part of startup that ever spawns anything, it is skipped entirely unless
-there is something for it to find: the machine-wide registry is read
-*first*, and the snapshot is only taken when at least one other entry
-exists that could possibly be this process's ancestor. The common case (no
-other kankaku process running on the machine at all) therefore never
-spawns `ps` or reads `/proc` — this process's own identity
-(`processStartId`) is unaffected, since it comes from `process.uptime()`
-instead (see "Identity, not just pid" above).
-
-**On a platform or environment where this mechanism cannot run at all** —
-Windows (no supported mechanism in this version), or any platform where a
-fresh attempt still fails (`ps`/`/proc` missing, timing out, or producing
-unreadable output) — ancestor-chain detection degrades gracefully to "no
-ancestor found" (never a spawn attempt beyond the one failed try, never a
-crash). Critically, this does **not** mean every unmarked process there is
-classified `uncertain`: with no way to check, kankaku falls back to the
-same marker-only detection it used before this feature existed
-(`GENTLE_PI_AGENTS_CHILD=1`/`KANKAKU_ROLE=subagent` → subagent, anything
-else → confirmed orchestrator) — the deliberately chosen default, because
-marking *every* genuine top-level session `uncertain` on such a platform
-would drop all of that user's work, which is far worse than the narrow
-overcount risk this guards against elsewhere. The trade-off is visible, not
-silent: `/kankaku doctor` reports ancestor-chain detection as unavailable
-whenever this happens (distinguishing it from "checked, no tracked
-ancestor found" — a separate, always-accurate report never folded into
-`roleConfidence`) and names `KANKAKU_ROLE` as the remedy for a genuine
-subagent system that needs marking explicitly on such a platform — see
-"Interactive sessions and `KANKAKU_ROLE`" below.
-
-### The `/kankaku doctor` diagnostic
-
-`/kankaku doctor` reports, with no network call:
-
-- How many records are orphaned subagents, and why.
-- How many are `uncertain`, and why.
-- Whether ancestor-chain detection is actually usable right now (see
-  above) — and, when it is not, a reminder that an unmarked subagent
-  system on this platform/environment may be counted twice, with
-  `KANKAKU_ROLE` named as the fix.
-- `KANKAKU_ROLE`, when it decided this process's role, as the deciding
-  signal — or, when it did not (a confirmed child marker took precedence,
-  or an interactive session's `subagent` override was ignored — see
-  "Interactive sessions and `KANKAKU_ROLE`" below), the contradiction and
-  the resolved outcome instead.
-- Whether this process is a subagent that could not write to its
-  orchestrator's directory and fell back to its own local one (see
-  "Cross-worktree write routing" above) — a hint to go reunite that record
-  manually, since `worklog.jsonl` can never be rewritten after the fact.
-- Registry health (see "Registry cleanup and health" above).
-- The current session's non-default session directory, when set.
-
-The plain `/kankaku` summary also appends a one-line hint (`N uncertain
-record(s) excluded from tasks — run /kankaku doctor`) whenever any exist,
-so an undercount is never silent.
-
-### Interactive sessions and `KANKAKU_ROLE`
-
-Every subagent mechanism kankaku recognises today launches its child
-**non-interactively**, over pipes (gentle-pi's `--mode rpc`, pi's own
-bundled `subagent` example's `--mode json -p`, `pi-subagents`) — a human
-never sits in front of one. A process running as an **interactive TUI
-session** (`ctx.mode === "tui"`, pi's own signal for "a real terminal, a
-human is here") is therefore always treated as a genuine top-level session
-and is **never** classified `uncertain`, even when some ancestor in its
-process chain happens to be a tracked pi process (for example, pi launched
-from inside another pi's `bash` tool). Interactivity can only be known once
-pi's own `ExtensionContext` is available, at `session_start` — later than
-this process's binary `role` (orchestrator vs. subagent) is decided, but
-`roleConfidence` is deferred and finalised exactly once, then, and stays
-stable for the rest of the process's life.
-
-**`KANKAKU_ROLE=orchestrator` or `KANKAKU_ROLE=subagent`** is an explicit
-escape hatch — validated; any other value is ignored, falling back to
-normal detection. Use it to force a session kankaku still gets wrong: mark
-a genuine subagent system it does not recognise as `subagent` (this is
-also the remedy `/kankaku doctor` names when ancestor-chain detection is
-unavailable on the current platform), or force a session `orchestrator`
-regardless of what its ancestry looks like. It has no effect on a record
-already written — see "The role/state model" above.
-
-**Scope it to one invocation. Never export it in a shell rc, tmux config,
-or CI environment file.** `process.env` is inherited by every OS child by
-default: an exported `KANKAKU_ROLE` reaches every `pi` invocation that
-shell/session ever starts, subagents included. Set it only on the one
-command it is meant for:
+### Projects across roots
+
+Each root is searched recursively for projects, up to 5 directory levels
+below it by default: a directory is a project once it has its own
+`.kankaku/worklog.jsonl` — including the root itself — and the search
+still continues below it, so a stray worklog in a parent directory (a pi
+session run once in `~/desarrollo`) never hides the projects beneath;
+every directory is listed at most once. Subdirectories are searched one
+level deeper, skipping `node_modules`, `.git` and any hidden
+(dot-prefixed) directory. This lets one root cover a whole workspace, e.g.
+`~/desarrollo` finding every project under `~/desarrollo/<client>/<project>`
+without listing each one. Projects are deduped by real (symlink-resolved)
+path and sorted by name — the directory's basename, or the last two path
+segments joined with `/` when two discovered projects share a basename
+(e.g. `clientA/shared` and `clientB/shared`). `~` expands to the home
+directory. Missing or malformed config falls back to the current working
+directory as the only root.
+
+### Hub credentials (Catalog and Sync)
+
+The Catalog and Sync screens (and their subcommands) talk to the same
+PocketBase hub kankaku itself syncs to, through kankaku's own
+`resolveHubCredentials`: `~/.kankaku/credentials.json`
 
-```
-KANKAKU_ROLE=orchestrator pi ...
+```json
+{
+  "url": "https://your-hub.example.com",
+  "email": "you@example.com",
+  "password": "…"
+}
 ```
 
-**Precedence (rewritten for a real bug — a BLOCKER fix).** `KANKAKU_ROLE`
-no longer overrides every other signal unconditionally:
-
-1. A **confirmed child marker** (`GENTLE_PI_AGENTS_CHILD=1`, set only by
-   the subagent runner itself, never something a shell rc/tmux/CI
-   environment would export) **always wins**, even over an explicit
-   `KANKAKU_ROLE=orchestrator`. Without this, a `KANKAKU_ROLE=orchestrator`
-   export that leaked into a shell rc — the natural thing to do after
-   hitting a false `uncertain` once — would turn every one of that shell's
-   later subagent invocations into a confirmed, independently-billed
-   orchestrator: systematic multi-counting, invisible until someone
-   compares the hub totals against what actually happened.
-2. `KANKAKU_ROLE=subagent`, with no confirmed marker, is **ignored for an
-   interactive session** (`ctx.mode === "tui"`). No subagent mechanism
-   kankaku recognises ever launches its child interactively, so this is
-   almost always the *mirror* leak — a globally exported
-   `KANKAKU_ROLE=subagent` reaching a genuine top-level terminal session —
-   and honouring it would silently drop that session's own work from every
-   report and the hub (an orphaned subagent record that never anchors a
-   task), with no way to recover it later, since `worklog.jsonl` is
-   append-only. Between kankaku's two guiding rules — "undercount is
-   recoverable, overcount is not" (which governs the *opposite* risk,
-   inventing extra billing, and does not apply to this contradiction) and
-   "never silently drop genuine work" — this one is governed by the
-   second: the override is ignored, the session is classified
-   `orchestrator` (what it structurally must be), and the contradiction is
-   surfaced once via `ctx.ui.notify` (a warning) at `session_start` and in
-   `/kankaku doctor` — never resolved silently. `KANKAKU_ROLE=orchestrator`
-   has no such exception: forcing a session `orchestrator` can never drop
-   work, only (rarely) invent a task that should not exist, a risk the
-   user accepted by setting it explicitly.
-3. Otherwise `KANKAKU_ROLE`, when set to a recognised value, decides — as
-   before.
-
-`/kankaku doctor` reports `KANKAKU_ROLE` as the deciding signal only when
-it actually decided anything: it flags "override present AND child marker
-present" with the resolved outcome (`subagent`, per rule 1) when both are
-set, and reports the resolved `orchestrator` outcome (per rule 2) when a
-`subagent` override was ignored for an interactive session — in neither
-case does it claim the override was the deciding signal.
-
-**Non-propagation.** `KANKAKU_ROLE` decides only the process that reads
-it. kankaku strips it from its own `process.env` right after reading it
-(before spawning anything), so a child it spawns — a subagent runner, a
-tool shell — never inherits it, even when this process's own copy came
-from something outside kankaku's control (a shell rc, tmux, CI). This is
-a second, independent layer on top of rule 1 above: rule 1 already
-neutralises a leaked `KANKAKU_ROLE=orchestrator` for any *recognised*
-subagent mechanism (its confirmed marker always wins regardless), but
-stripping means the leak can never reach an *unrecognised* one, or any
-other child process, either.
-
-**Captured once per process, survives `/new`/`/resume`/`/fork`/`/reload`.**
-pi re-invokes an extension's factory function in the SAME OS process for
-each of those (it "reloads and rebinds extensions" for the new session);
-kankaku reads `KANKAKU_ROLE` and decides `role` from the very first
-invocation and reuses that exact result for every later one in the same
-process, so a `KANKAKU_ROLE=orchestrator` you set for one `pi` command
-stays honoured across every `/new`/`/resume`/`/fork`/`/reload` you run
-inside that same session, not just the first. This does **not** widen the
-"scope it to one invocation" rule above — it still applies only to the one
-`pi` process you set it on, and is still stripped from that process's own
-`process.env` right after the first read, so it is still never inherited
-by anything that process spawns. It only means "one invocation" is
-honoured for as long as that OS process stays alive, across every reload,
-rather than being silently forgotten the moment pi reloads extensions
-internally.
-
-### Subagent profiles (phase 6b)
-
-kankaku recognises a subagent-opening tool call through a `SubagentProfile`
-(one per ecosystem package), not a single hardcoded tool name. Three
-profiles are built in:
-
-- **gentle-pi** (first-class): `subagent_run`, joined by explicit `taskId`
-  (`result.details.gentleAgents`), confirmed by `GENTLE_PI_AGENTS_CHILD=1`.
-  Nothing about gentle-pi changes — every field it already exposed (agent,
-  mode, taskId, live status, cross-worktree `cwd`) still does.
-- **pi's bundled reference example**: the `subagent` tool, no env marker at
-  all — recognised only through ancestry, always starts `uncertain` until
-  the registry/ancestor-chain mechanism above corroborates it.
-- **pi-subagents**: also registers a tool named `subagent`, confirmed by
-  `PI_SUBAGENT_DEPTH` (present with any value — its own recursion-depth
-  counter, not a fixed sentinel).
-
-Two packages registering a tool with the exact same name (`subagent`) is a
-real ambiguity kankaku never guesses through: which ecosystem package
-actually made a given call can only be told apart by its child-env marker
-(present in the *child* process, not visible from the parent's tool-call
-alone), so a call to `subagent` still opens a span (best-effort agent/mode,
-kept only when every candidate profile that reports one agrees), but is
-never attributed to one specific profile unless a marker resolves it.
-**Nothing money- or join-affecting is ever taken from an ambiguous call
-either** — no `usage`, no `taskId` — even when one of the colliding
-profiles would normally forward one, because kankaku cannot tell whether
-that specific call actually came from that profile. `/kankaku doctor`
-reports this as an "ambiguous tool name" line.
-
-**`KANKAKU_SUBAGENT_TOOLS`** registers one or more additional tool names as
-subagent-opening spans, comma-separated, parsed exactly like
-`KANKAKU_INTERACTIVE_TOOLS` — always additive to the built-ins, never
-replacing gentle-pi's own recognition.
-
-**`KANKAKU_SUBAGENT_CHILD_ENV`** registers one or more child-process env
-markers that confirm a process as this configured tool's subagent,
-`;`-separated `NAME=VALUE` (exact match) or a bare `NAME` (presence-only,
-any non-empty value) — mirrors `KANKAKU_SEGMENTS`'s tolerant parsing:
-malformed entries are skipped, not fatal.
+or the environment (env takes precedence per field over the file):
+
+- `KANKAKU_PB_URL`, `KANKAKU_PB_EMAIL`, `KANKAKU_PB_PASSWORD`
+- `KANKAKU_SYNC_WINDOW_HOURS` — revisit window for `sync`/`sync status` (default 24)
+- `KANKAKU_SYNC_PROMPT` — `none` (default), `truncated` or `full`
+- `KANKAKU_SYNC_RECORDS` — set to `0` to skip uploading individual `work_records`
+- `KANKAKU_MACHINE` — overrides the reported hostname
+
+Without credentials, the Catalog and Sync screens show a one-line note
+instead of a list; `kankaku catalog` and `kankaku sync status` print the
+same note and exit 0 (no network attempted); `kankaku catalog refresh` and
+`kankaku sync`/`kankaku sync all` print an error and exit 1.
+
+Every sync uploaded from here is stamped `plugin: kankaku-tui` (the identifier is kept from before the rename so existing rows stay consistent); a task's
+`agent` comes from its own orchestrator record when it carries one (see
+kankaku's `hub-entry.ts`), else falls back to `agent: unknown` — this app
+never guesses which coding agent produced someone else's worklog.
+
+### Local hub
+
+Instead of pointing at someone else's PocketBase, `kankaku hub install`
+sets up and runs your own hub on this machine, under `~/.kankaku/hub/`:
+
+- `bin/pocketbase` — the PocketBase binary for this OS/CPU, downloaded
+  from the `kankaku-hub` npm package's manifest and SHA256-verified.
+- `pb_data/` — the hub's own database; never touched by an upgrade.
+- `app/<version>/` — a fresh copy of that package version's migrations,
+  hooks and static files (never a symlink, so `npm update` can't change a
+  running hub out from under it); `current` names the active version.
+- `hub.json` — the installed port and versions.
+- `accounts.json` (owner-only, `0600`) — the PocketBase superuser email
+  and generated password, and the owner account's email. The owner logs
+  into the hub's own web admin UI with that owner account.
+- `~/.kankaku/credentials.json` — the generated `service` account
+  (`kankaku-sync@kankaku.local`) this app and kankaku's own sync already
+  read, exactly like a remote hub's credentials.
+
+Commands (macOS and Linux only — PocketBase ships no other build):
+
+- `kankaku hub install [--port N] [--owner-email E] [--owner-password P]`
+  — installs (or, run again, verifies) the hub and leaves it running. On
+  a real terminal, a missing owner email/password is prompted for
+  (masked); without a TTY, both flags are required. Idempotent: re-running
+  with everything already in place changes nothing. If another process
+  already answers on the target port, `install`/`start`/`upgrade` refuse
+  with `port <N> is already in use by another process — pass --port <N>
+  or stop it` instead of provisioning accounts against it; pass a
+  different `--port` or free the port and retry.
+- `kankaku hub start` / `kankaku hub stop` — start or stop the server
+  process; `stop` is a no-op when it isn't running.
+- `kankaku hub status` — `local hub: running 0.2.0 (PocketBase 0.40.4) at
+  http://127.0.0.1:8090 · pb_data 1.2 MB`, `stopped`, or `not installed`.
+- `kankaku hub upgrade` — copies a fresh `app/<version>/` from the
+  currently installed `kankaku-hub` package, downloads a new PocketBase
+  binary only if that version changed, and restarts — `pb_data` is never
+  touched.
+- `kankaku hub logs [-n N]` — the last `N` (default 50) lines of
+  `hub.log`.
+
+The Dashboard's Hub card shows `local hub · running`/`stopped` when the
+configured hub is this machine's own local install, with a matching `h`
+quick action to start or stop it. The setup wizard's Hub step's
+`install locally` option runs this same installer (asking for the owner
+email/password inline); the older checkout-based dev install
+(`kankaku-hub`'s own `scripts/dev.sh`) is still available for hub
+developers via `kankaku setup --from-checkout <dir>`.
+
+## Usage
+
+- `kankaku` — opens the interactive TUI on the Dashboard screen.
+- `kankaku today [--roots a,b]` — today's work per project, plain text.
+- `kankaku tasks [--all]` — every task's line (kankaku's own `formatTasks`),
+  grouped under a `== <project> ==` header per project; restricted to
+  today unless `--all`.
+- `kankaku catalog [refresh]` — without `refresh`, reports the locally
+  cached client/project counts (no network); `refresh` fetches a fresh
+  snapshot from the hub and caches it to `~/.kankaku/catalog.json`.
+- `kankaku sync [status|all] [--project <dir>]` — `status` reports the
+  pending count and last sync per project, no network; with no argument,
+  syncs the pending window; `all` does a full resync. Defaults to every
+  discovered project, sequentially; `--project <dir>` restricts to one.
+- `kankaku setup [--yes] [--dry-run] [--from-checkout <dir>]` — see
+  "Install everything" above; `--from-checkout` is the hub-developer-only
+  checkout-based local hub install, see "Local hub" above.
+- `kankaku doctor` — the same read-only report `kankaku setup` ends with,
+  without prompting or writing anything.
+- `kankaku hub install|start|stop|status|upgrade|logs` — the local hub's
+  lifecycle; see "Local hub" above.
+
+`--roots` (on `today`/`tasks`) overrides the configured roots for that run.
+
+`--theme <name>` picks one of the three built-in colour presets for the
+interactive TUI; `KANKAKU_TUI_THEME=<name>` does the same through the
+environment (the flag wins when both are given). The valid names are
+`gentleman-sexy` (the default), `gentleman-cute` and `gentle` — resolved
+hex values copied from [gentle-pi](https://github.com/Gentleman-Programming/gentle-pi)'s
+own themes (MIT), so this TUI matches the owner's pi panel instead of an
+unrelated default. An unknown name prints a usage error listing the valid
+names and exits 1 without opening the TUI.
+
+## Screens
+
+One visual system drives all four screens: a left sidebar for navigation,
+titled bordered panels, aligned tables with a highlighted selection, text
+bars and sparklines, a header line and a footer of key hints — all driven
+by a single theme of colour roles (`src/ui/theme.ts`, see `--theme` above
+for the three built-in presets). The app runs fullscreen, in the
+terminal's alternate screen buffer: the frame fills the whole terminal
+height, resizing live with the terminal. The sidebar sits beside the
+screen at 100+ terminal columns, stacks full-width above it at 70-99
+columns, and collapses to a one-line tab strip below 70 columns; a
+selected row or card is always marked with a visible `›`, never colour
+alone. The sidebar itself shows which zone has focus: its border switches
+to the active border colour and the active item gets a full-row highlight
+when it has focus, dropping back to a plain `›` marker with no highlight
+once focus moves to the screen's own content.
+
+Every panel in the main area is sized to a fixed height derived from the
+terminal's own height, so it never grows with its content and shifts the
+rest of the screen — a long value (e.g. the Tasks screen's full prompt)
+is wrapped and, if it still doesn't fit the panel's fixed height, clipped
+with a trailing `… N more lines` note instead of silently overflowing or
+pushing the header out of view.
+
+Any list that can grow past the available height (the Tasks table, the
+Catalog Clients/Projects lists, the Dashboard Projects table, the Sync
+card grid) scrolls instead of overflowing the terminal: the viewport
+follows the current selection, and a `↑ N more` / `↓ N more` line marks
+rows hidden above or below it.
+
+Dashboard is the app's home screen: a Today card (work/wait/cost/tasks/
+cache hit — it shows today's numbers, hence its own title), a Last 7 days
+card (work and cost sparklines with weekday labels), a Projects table
+(work, cost and a share bar per project), a Hub card (pending/stale, last
+sync time, catalog summary) and a Quick actions panel (`c` refresh the
+catalog, `s` sync every project, `S` full-sync every project, `r` reload):
 
 ```
-KANKAKU_SUBAGENT_TOOLS=my_subagent_tool
-KANKAKU_SUBAGENT_CHILD_ENV=MY_TOOL_CHILD=1
-```
-
-**What NOT to use as a marker.** A configured marker must be exclusive to
-the child process your subagent tool actually spawns — never an ambient
-variable pi, your shell, npm, or the OS sets on *every* process. kankaku
-rejects an obviously-ambient name outright at load time (case-insensitive):
-`PI_CODING_AGENT` and `AI_AGENT` (pi sets both on every process it runs,
-not just a subagent's child), the generic shell/OS variables `PATH`,
-`HOME`, `USER`, `SHELL`, `PWD`, `CI`, `LANG`, `TMUX`, and anything prefixed
-`PI_`, `TERM`, `LC_`, `NODE_`, `NPM_`, or `KANKAKU_`. A rejected marker
-never reaches the configured profile — it is reported once via
-`ctx.ui.notify` and listed in `/kankaku doctor`, never silently accepted.
-This denylist cannot enumerate every possible ambient variable, though, so
-there is a second, runtime layer: **a configured marker never demotes an
-interactive session**, exactly like `KANKAKU_ROLE=subagent` already does
-not (see "Interactive sessions and `KANKAKU_ROLE`" above) — if a configured
-marker matches on a session that turns out to be interactive, kankaku
-treats it as the orchestrator it structurally must be and warns once
-(escalated to a stronger warning when that session also has no tracked
-ancestor at all, the clearest sign the "marker" is actually ambient). A
-**built-in** marker (`GENTLE_PI_AGENTS_CHILD`, `PI_SUBAGENT_DEPTH`) keeps
-the unconditional precedence it always had — no built-in mechanism kankaku
-recognises ever launches its child interactively, so this exception never
-actually applies to it in practice.
-
-**Verify with `/kankaku doctor`.** After configuring
-`KANKAKU_SUBAGENT_CHILD_ENV`, run `/kankaku doctor` from an ordinary
-top-level session: it must **not** report a "configured marker" or
-"rejected marker" line for a ordinary interactive session. If it does, the
-chosen name is either denylisted or ambient enough to trip the interactive
-guard — pick something the third-party tool's own child process sets that
-nothing else on the system would ever set.
-
-A confirmed marker from a configured profile that passes both layers above
-still takes the same "always wins over `KANKAKU_ROLE`" precedence gentle-pi's
-own marker already had for a **non-interactive** process — see "Interactive
-sessions and `KANKAKU_ROLE`" above.
-
-`/kankaku doctor` reports the active profile set, any configured tools/
-markers, which profile matched each subagent record (or "unmatched" when
-no marker resolved it), any rejected marker names with why, and a
-configured-marker-ignored-for-interactivity contradiction when one occurs.
-
-### In-process subagents (phase 6c)
-
-A subagent tool result's `usage` field — pi's own documented convention
-for "a tool making nested LLM calls should return their combined `Usage`
-as `usage`" — is recorded on the span itself (never folded into the
-triggering record's own usage totals at write time any more), and added to
-the *task's* aggregate total by `buildTasks` — the one place per-task
-usage is ever assembled — except when this same task also has a joined
-child record confirmed by the **same** profile: that child's own usage
-already carries this cost through its own confirmed-marker/ancestry join,
-so the span's forwarded figure is excluded instead of counted a second
-time. gentle-pi is unaffected (its result never carries one — cost for its
-children is, and stays, tracked through the registry/ancestry join above).
-A profile whose marker can also produce an ancestry-joined child record
-with its own usage (pi-subagents) never forwards `usage` even when its
-result happens to carry one, to avoid counting the same nested work twice
-by construction; a *configured* profile that declares **both** a marker
-and forwards usage relies on the runtime reconciliation above instead (see
-"Subagent profiles (phase 6b)"). **Usage is never forwarded for an
-ambiguous tool-name match** (2+ profiles registering the same name, e.g.
-`subagent`) — see "Subagent profiles (phase 6b)" above.
-
-Real in-process (same-OS-process, no separate `pid`) subagent nesting was
-investigated directly against pi's own source and documented API
-(`docs/extensions.md`) for this release: none of gentle-pi, pi's bundled
-reference example, or pi-subagents actually run a child *inside* the
-parent's process — every one of them spawns a real, separate OS process.
-pi's own in-process mechanism (`ctx.newSession`/`ctx.fork`) replaces one
-session with another *sequentially* in the same process (the old session's
-`session_shutdown` fires, then the new one's `session_start` — never
-concurrently), which is exactly what "kankaku reads/writes a fresh record
-per session_start, same pid" already handles correctly. As a defensive
-guard for the pattern true concurrent nesting *would* leave behind,
-`/kankaku doctor` flags two confirmed-orchestrator records sharing a pid
-with **overlapping** `[startedAt, settledAt]` windows as "likely
-in-process nesting", unioning (never summing) their wall time via the
-same interval-union primitive `buildTasks` itself uses — informational
-only, it never changes a task's own numbers. This has not been observed
-from any real subagent mechanism in this codebase's research; if pi (or an
-extension built on its SDK) grows genuine concurrent in-process nesting in
-the future, this is the signal that would surface it.
-
-### Limitations, honestly
-
-- **Windows has no ancestor-chain detection** (an ancestor can never be
-  identity-verified there), though this process's own `processStartId` is
-  always available regardless of platform — see "Identity, not just pid"
-  above. Mark a genuine subagent system explicitly with `KANKAKU_ROLE` on
-  such a platform; see "Interactive sessions and `KANKAKU_ROLE`" above.
-- **gentle-pi's child cannot currently read its own task id** — the
-  cross-worktree join above relies on ancestry plus the registry, not on an
-  explicit shared id, because upstream gentle-pi does not hand the child
-  process its task id today. If that changes upstream, a future kankaku
-  version can upgrade this join to a higher-confidence explicit-id match.
-- **Ancestor-chain detection only sees the chain as it exists when a
-  process looks.** A detached child reparented to init/launchd before that
-  point cannot recover its original ancestry this way — the same limitation
-  the existing `pid`/`parentPid` capture already has (see AGENTS.md).
-- **A record already written `uncertain` (or already routed to a fallback
-  local directory) cannot be rewritten.** `worklog.jsonl` is append-only;
-  fixing the underlying cause (upgrading kankaku, setting `KANKAKU_ROLE`,
-  restoring access to an orchestrator's directory) only helps a *later*
-  run's records, never edits a line already on disk. There is no migration
-  planned for this — it follows directly from "never rewrite the log" (see
-  AGENTS.md).
-
-## The `/kankaku` command
-
-`/kankaku` with no arguments, run inside pi's TUI, opens an overlay panel
-modelled on pi's own `/settings` (the same pi-tui `SettingsList`/
-`SelectList` widgets, the same keys) from which every kankaku view and
-action is reachable:
-
-- **Target** — billing client, project, hub task, and the legacy label
-  (see "Billing labels" and "Hub (PocketBase)" below). The Task row lists
-  the open/doing hub tasks of the current project; picking one links the
-  session, exactly like `/kankaku task pick` below — **session-only**,
-  never persisted (see "Linking to a hub task").
-- **Report** — today/all totals, tasks, sessions, clients, and projects:
-  the same five views `/kankaku`'s subcommands produce.
-- **Sync** (hub only) — status, sync now, sync all, backfill, and a
-  catalog refresh.
-- **Export** — write today's or every task as csv/json.
-- **Doctor** — orphan/uncertain subagent counts and ancestor-detection
-  availability.
-- **About** — versions, the resolved `KANKAKU_DIR`, the hub URL, and every
-  env-only setting, read-only.
-
-Keys: `↑↓` move, `Enter` open a section or select a value, `Esc` or `←` go
-back (or close the panel at the root), `q` close from anywhere. Mouse: the
-footer hints and list rows are clickable, but only in pi's fullscreen
-mode — pi does not dispatch mouse events in its regular (non-fullscreen)
-mode, so there the panel is keyboard-only.
-
-Every subcommand below is unchanged, and is exactly what headless (print
-or RPC) mode still uses — `/kankaku` there keeps showing today's totals
-directly, never the panel, since there is no UI to open one in. Run
-`/kankaku <subcommand>` (with arguments) in the TUI to skip the panel and
-go straight to that subcommand's output, exactly as before the panel
-existed.
-
-Plain `/kankaku` (headless, or any subcommand below) shows today's totals
-(work, waiting, record count) per role, plus a union-based tasks segment.
-Each totals line also shows `cache hit NN%` when tokens were recorded: the
-share of prompt input tokens served from the provider's prompt cache, cache
-reads over input plus cache reads plus cache writes; the segment is
-omitted, not shown as `0%`, when no tokens were recorded. In the
-interactive TUI the report is appended to the chat transcript as a durable
-card that is never sent to the LLM; without a UI (print or RPC mode) it
-falls back to a notification. Arguments are whitespace-separated and
-order-insensitive:
-
-- `/kankaku` (headless only — the TUI opens the panel instead, whose
-  Report screen defaults to the same view) — today's role totals and
-  tasks segment, each with its estimated cost.
-- `/kankaku all` — same, but across every record.
-- `/kankaku tasks` — one line per task (time, union wall/work, cost,
-  subagent count, truncated prompt) for the **current pi session**. Add `all` for
-  every session. If the current session has no `sessionId`, tasks from every
-  session are shown instead.
-- `/kankaku sessions` — one line per session (id, time range, union
-  wall/work, cost, task count) for today. Add `all` for every day.
-- `/kankaku client <name>` — set the billing client for the current pi
-  session. `/kankaku client` alone shows the effective client and which
-  source it came from; `/kankaku client --clear` removes the session-level
-  override. See "Billing labels" below. When a hub is configured, `<name>`
-  must match a catalog client's code or name (case-insensitive) instead of
-  being free text — see "Hub (PocketBase)".
-- `/kankaku clients` — one line per client (work/waiting/wall time, cost,
-  task count) for today. Add `all` for every day. Tasks with no resolved
-  client are grouped under `(none)`.
-- `/kankaku doctor` — orphan/uncertain subagent record counts and why,
-  plus ancestor-detection platform availability. No network call. See
-  "Subagents".
-
-The following are available only when a hub is configured (see "Hub
-(PocketBase)" below):
-
-- `/kankaku target` — show the effective client/project and which source
-  produced it. `/kankaku target pick` runs the picker again (works
-  mid-session; the new target applies to records settled afterwards).
-  `/kankaku target clear` clears the session-level target.
-- `/kankaku task` (or `/kankaku task pick`) — link this session to an
-  open/doing hub task of the effective project. `/kankaku task clear`
-  drops the link. See "Linking to a hub task" below.
-- `/kankaku catalog refresh` — force a catalog refresh and report the
-  client/project counts.
-- `/kankaku projects` — one line per project (work/waiting/wall time, cost,
-  task count) for today. Add `all` for every day. Tasks with no resolved
-  project are grouped under `(no project)`.
-
-Cost figures are the sum of `usage.cost` as priced by pi's model table
-(per-million-token rates in `models.json`, adjustable with `modelOverrides`).
-For subscription-based providers this is an estimate at API list prices, not
-an invoice.
-
-While an agent is running, pi's status bar shows a `🕒 mm:ss · <client>` indicator (the client part appears only when one resolves); while idle it shows `💼 <client>`, or nothing when no client resolves. The entry is keyed `zz-kankaku` so it sorts last among extension statuses. The running indicator carries
-the elapsed time for the current run.
-
-## Billing labels
-
-Every `WorkRecord` can carry a `client` — who the work is billed to — so
-reports and exports can be grouped by client. The effective client is
-resolved from three sources, in decreasing precedence:
-
-1. **Session** — set with `/kankaku client <name>` (see above), persisted as
-   a `kankaku-client` custom session entry and restored on session reload.
-2. **`KANKAKU_CLIENT`** — the environment variable, a per-process default.
-3. **Project** — `client` in `<KANKAKU_DIR>/config.json` (e.g.
-   `{"client": "acme"}`), the project's own default.
-
-A client name must match `/^[A-Za-z0-9._-]{1,64}$/`; anything else (empty,
-too long, containing spaces or other characters) is ignored and resolution
-falls through to the next source.
-
-A `subagent_run` child process does not resolve its own client — a
-subagent's own `WorkRecord` never carries `client`. Instead, the **task**
-view (see "Task and session views") exposes the client from its
-orchestrator record only, so `/kankaku tasks`, `/kankaku clients`, and the
-export all see subagent work grouped under the task's (i.e. the
-orchestrator's) client.
-
-`sessionName` is also attached to every record from `pi.getSessionName()`,
-so reports can show which named session produced a task.
-
-## Hub (PocketBase)
-
-kankaku can optionally resolve the billing client (and a project) **from a
-PocketBase instance** instead of free text, so `cajamar`/`Cajamar`/`cjamar`
-can no longer become three different clients. This is phase 1 of the hub
-integration (catalog + selection only): nothing is uploaded anywhere.
-
-### Configuration
-
-Set `KANKAKU_PB_URL`, `KANKAKU_PB_EMAIL`, `KANKAKU_PB_PASSWORD`, or write
-`~/.kankaku/credentials.json`:
-
-```json
-{ "url": "https://pb.example.com", "email": "bot@example.com", "password": "secret" }
+ >_ kankaku 0.1.0                              hub ● kankaku.soyun.ninja · synced 08:20
+┌──────────────┐ ╭─[ Today ]────────────────────╮ ╭─[ Last 7 days ]──────────────────╮
+│ › Dashboard  │ │   work   1h 42m               │ │ work  ▂▅▇▃▁▆█   cost  ▁▃▆▂▁▅█    │
+│   Tasks      │ │   wait      6m   cost  $9.83  │ │ mon tue wed thu fri sat sun       │
+│   Catalog    │ │   tasks 12       cache hit 68%│ ╰──────────────────────────────────╯
+│   Sync       │ ╰──────────────────────────────╯ ╭─[ Hub ]──────────────────────────╮
+│              │ ╭─[ Projects ]────────────────────────────╮ │ pending 1 · stale 0     │
+│              │ │ project       work    cost   share      │ │ last sync ok 08:20      │
+│              │ │ kankaku       1h 02m  $6.49  ████████░░ │ │ catalog 9 clients ·     │
+│              │ │ kankaku-tui     31m   $2.10  █████░░░░░ │ │         17 projects     │
+│              │ │ kankaku-hub      9m   $1.24  ██░░░░░░░░ │ ╰─────────────────────────╯
+│              │ ╰─────────────────────────────────────────╯
+├──────────────┤
+│ roots 1      │
+│ projects 3   │
+└──────────────┘
+ ↑↓ move   enter open   r refresh   1-4 screens   q quit
 ```
 
-Environment variables take precedence over the file, field by field. The
-hub URL must be HTTPS unless it points at `localhost`/`127.0.0.1`/`::1`; a
-plain-HTTP URL for any other host is refused (surfaced once via a
-notification). The project's own `<KANKAKU_DIR>/config.json` is never read
-for credentials — it is project-local and frequently committed.
-
-`KANKAKU_MACHINE` optionally names this machine (for a multi-machine setup
-later); it defaults to the OS hostname and is attached to every record as
-`machine` once the hub is configured.
-
-**When no hub is configured, kankaku behaves exactly as it does today** —
-this whole feature is additive and every existing behaviour, record shape,
-and report stays unchanged.
-
-### Selection
-
-On `session_start`, for the orchestrator role with a UI available:
-
-1. **Session** — restored from the last `kankaku-target` session entry
-   (including a remembered "skipped" choice, so a reload does not ask
-   again).
-2. **Project config** — `clientId`/`projectId` in `<KANKAKU_DIR>/config.json`.
-3. **`repo_paths`** — the current working directory matched against each
-   project's `repo_paths` (exact match, or a subdirectory of one; the
-   longest match wins).
-4. Otherwise, a picker: `ctx.ui.select` for the client (active clients,
-   sorted by name, plus "— skip —"), then for the project (active projects
-   of that client, plus "(no project)" and "— skip —"). Declining at either
-   step — "— skip —" or dismissing the dialog — cancels the whole pick and
-   is remembered for the session. The picker shows the freshly refreshed
-   catalog when the hub answered within the deadline described in "Caching
-   and offline behaviour" below; otherwise it falls back to the cache.
-
-After a pick, kankaku asks whether to remember it for this repository; a
-"yes" merges `clientId`/`projectId` into `<KANKAKU_DIR>/config.json`.
-
-An id from any source that no longer resolves to an active, non-"unassigned"
-catalog entry is treated as absent for that source and resolution falls
-through to the next one, exactly like the legacy client precedence.
-
-Once a hub target is active for a run, the legacy `client` label is set to
-the target's client `code` (so every existing report/export keeps grouping
-correctly), and the record additionally carries `clientId`, `clientName`,
-and — when a project is selected — `projectId`/`projectName`. A subagent
-never resolves its own target, exactly like the legacy `client` label — the
-task view exposes it from the orchestrator record only.
-
-The status bar shows `💼 <client> · <project>` (or just `💼 <client>` without
-a project) in place of the legacy client label, both idle and during a run.
-
-Mid-session, the `/kankaku` panel's Target screen (see "The `/kankaku`
-command" above) is the interactive way to change the client or project
-without going through `/kankaku target pick`'s picker dialog — it edits the
-same session-level target, applies through the same `SessionTarget`, and
-has its own "Remember" row for `<KANKAKU_DIR>/config.json`.
-
-### Linking to a hub task
-
-`/kankaku task` (or `/kankaku task pick`) links the current session to one
-of the effective project's existing hub `tasks` rows: a `ctx.ui.select`
-picker lists the project's `open`/`doing` tasks, sorted by title (colliding
-titles are disambiguated with the task's external reference, or its id).
-`/kankaku task clear` drops the link, keeping the rest of the session
-target. kankaku never creates a task from pi — this only links to one
-that already exists in the hub.
-
-The link is **session-only**: unlike `clientId`/`projectId`, it is never
-persisted to `<KANKAKU_DIR>/config.json`, and it is never asked for at
-`session_start` — you always link a task explicitly, with `/kankaku task`.
-Any target change (`/kankaku target pick`, `/kankaku target clear`, or the
-legacy `/kankaku client <name>`) drops the linked task, since a new client
-or project makes the old task's link meaningless. A task whose project no
-longer matches the effective project (e.g. after a target change or a
-reassignment in the hub) is also dropped by the domain resolver, never
-silently linked across projects. A task already marked `done` when linked
-keeps linking for the rest of the session — only the picker itself hides
-`done` tasks, so you cannot accidentally pick a closed one, but finishing
-the picked task in the hub mid-session does not break the link. Subagent
-records never carry a linked task, exactly like `clientId`/`projectId` —
-the task view exposes it from the orchestrator record only, and
-`formatWorkTargetLabel` appends it to the status-bar/report label as
-`<client> · <project> › <task title>`.
-
-The `/kankaku` panel's Target screen's Task row is the interactive
-equivalent of `/kankaku task pick`/`clear`: it lists the same open/doing
-tasks, applies the link through the same `SessionTarget.setTask`, and
-stays just as session-only — picking a task there is never persisted to
-`config.json` either.
-
-### Caching and offline behaviour
-
-The catalog (clients/projects) is cached machine-wide at
-`~/.kankaku/catalog.json`. On `session_start`, for the orchestrator role
-with a UI available, kankaku always starts a background refresh when a
-cache already exists — regardless of the cache's age — so a client or
-project created in the hub minutes ago shows up without waiting for a TTL
-to expire (the 6-hour TTL and `isStale()` still exist and still gate other
-callers, but session start no longer depends on them). If the target
-resolves silently from the project config file or `repo_paths` against
-the cached snapshot, `ensurePicked` returns immediately without waiting
-for that refresh at all; it keeps running in the background and
-`catalog.read()` reflects it once it lands, exactly as before. Only when
-the picker is actually about to be shown does kankaku wait for the
-in-flight refresh, bounded by a short deadline (1.5s by default,
-`pickerRefreshDeadlineMs`): if the hub answers in time, the picker offers
-the fresh clients/projects; otherwise (or if the refresh fails) it falls
-back to the cached snapshot silently, and the refresh keeps running
-in the background rather than being aborted. `/kankaku target pick` (the
-explicit re-pick command) follows the same wait-then-fall-back rule. When
-there is no cache at all, one refresh is still awaited (bounded by the hub
-client's own request timeout, 3s by default) before falling back — this
-path is unchanged. If the hub is unreachable and there is no cache,
-kankaku notifies once (`kankaku: hub unreachable, using local labels`) and
-continues exactly as it would without a hub configured; a background
-refresh that merely fails once a cache already exists is silent, with no
-notification. `/kankaku catalog refresh` still forces a refresh on demand
-independently of any of this. The cache file is always written owner-only
-(`0600`); if kankaku is the first thing to ever create `~/.kankaku` itself
-(no project has put its own `.kankaku` there), the directory is created
-owner-only (`0700`) too — but an already-existing `~/.kankaku` is never
-chmod'd, since it may be a project's own kankaku directory (see "The
-registry" below for the same rule applied to `run/`).
-
-### Privacy (catalog)
-
-The catalog itself (clients/projects) is read-only — nothing about *that*
-data is ever written back. Whether your own work records ever leave the
-machine is a separate, opt-in decision: see "Sync" below.
-
-### Sync
-
-Once a hub is configured, kankaku can push consolidated **task** rows (see
-"Task and session views" above) to PocketBase, so a project/task manager
-can report AI time and cost per project. This is an outbox pattern:
-`worklog.jsonl` stays the local source of truth, append-only and never
-rewritten, exactly as without a hub. A separate sync step reads it and
-uploads what is pending — nothing in a pi event handler ever waits on the
-network.
-
-**What gets uploaded.** One `task_entries` row per task — never raw
-`WorkRecord`s re-aggregated on the server. The union-of-intervals rule
-(`wallMs`, "Task and session views") is computed exactly once, locally, by
-`buildTasks`; the hub only ever sums already-consolidated rows. When
-`KANKAKU_SYNC_RECORDS` is not `0` (the default), each task's underlying
-`WorkRecord`s are also uploaded as `work_records`, raw per-run detail for
-drilling into a task — these rows overlap each other and must never be
-summed, unlike `task_entries`.
-
-**Idempotency and the revisit window.** Every task is upserted by its id
-(the orchestrator record's `id`), never blindly created — safe to
-re-send. A task is not final the moment its orchestrator settles: a
-background subagent can settle *after* it and extend the task's union
-(`wallMs`, cost, subagent count) for a task that may already be in
-PocketBase. So every sync revisits a trailing window behind its own
-watermark — `KANKAKU_SYNC_WINDOW_HOURS`, 24h by default — and re-evaluates
-every task whose `endedAt` falls inside it. A cheap content hash per task
-(`<KANKAKU_DIR>/sync-state.json`) means an unchanged task inside the window
-costs nothing: running `/kankaku sync` twice in a row performs zero writes.
-
-The window is anchored to `syncedThrough` (the watermark), never to
-current wall-clock time — see "Limitations" below for what that means for
-a background subagent that settles long after its orchestrator, and after
-the directory has otherwise gone quiet.
-
-**Assignment is create-only.** You (or whoever reassigns work in the hub's
-web app) can move a task from one client/project to another directly in
-PocketBase — for example, moving a "Sin determinar" row to its real
-client once you have identified it. A later re-sync of that same task
-**must never undo that**: on create kankaku sends the full row, including
-`client`/`project`/`task`/`legacy_client_label`; on every subsequent update
-it sends measurement fields only (`wall_ms`, `cost`, `status`, ...) and
-never touches assignment fields again. `task` (the linked `tasks` relation)
-is create-only for the exact same reason: reassigning which task a row
-belongs to in the web app is never undone by a later sync. If you need
-kankaku itself to change a task's assignment, do it in the web app, not by
-re-syncing.
-
-**Historical ("Sin determinar") records.** A record with no `clientId`, or
-whose `clientId` no longer resolves in the catalog, is routed to the hub's
-"Sin determinar" (unassigned) client, carrying its old free-text `client`
-label (or `clientName`) forward as `legacy_client_label` — the exact
-mechanism that lets you bulk-reassign "everything that said `cjamar`" once,
-in the web app, from the unassigned queue.
-
-**Agent and measurement quality.** Every `task_entries` row also carries
-who produced it and how well each figure was measured, so the hub can
-label what it has instead of silently blending incompatible numbers from
-different agents: `agent` (`"pi"` for this package), `agent_version` (the
-agent's own version, when it could be determined — never guessed, omitted
-otherwise), `plugin` (`"kankaku"`), `plugin_version` (this package's own
-version), `waiting_quality` (always `"measured"` for kankaku/pi — it
-always instruments waiting time), `cost_quality` (`"measured"` when the
-task's own record or any joined subagent observed a real provider cost
-figure on at least one turn; `"unknown"` when none did, e.g. a
-subscription/OAuth provider that reports no cost — kankaku has no
-token-price estimator, so it never sends `"estimated"`), and
-`subagent_linkage` (`"not_applicable"` when the task opened no subagent
-spans; `"linked"` when at least as many child records were joined as spans
-were opened; `"unlinked"` otherwise — a task-level approximation, since
-there is no per-span correlation id today, see "Subagents" >
-"Limitations"). These are measurement fields, not assignment, but
-`agent`/`agent_version`/`plugin`/`plugin_version` specifically identify
-who *measured* the task, not who *syncs* it: they are taken from the
-orchestrator record's own `agent`/`agentVersion`/`plugin`/`pluginVersion`
-(see "Record schema") when it carries one, and only fall back to the
-syncing process's own identity for a legacy record written before this
-field existed. On create, `agent`/`plugin` are always sent (from the
-record or the fallback). On update, all four are sent when the record
-carries an identity, and OMITTED ENTIRELY for a legacy record — so a
-re-sync by a *different* process (a standalone `kankaku` TUI, or a
-different agent syncing a shared directory) can never overwrite a row's
-original identity with its own. `waiting_quality`/`cost_quality`/
-`subagent_linkage` are unaffected by this and are always sent on both
-create and update. All of these are included in the sync content hash
-(the record's own `agent`/`plugin`, not their versions), so a background
-subagent that joins later, or a task that first gains a who-measured
-identity — improving `cost_quality`/`subagent_linkage`/`agent` without
-changing any other number — still triggers a resync. An older hub
-predating these fields simply ignores them (PocketBase silently drops
-unrecognized fields on write); no capability probing is needed.
-
-**Session directory.** `session_dir` carries a task's non-default session
-directory (`TaskView.sessionDir`, see "Record schema") to the hub, so a
-resumable session can be resumed from the web, not just locally via
-`/kankaku doctor`. It is optional — only present when pi reports a
-non-default session directory — and, like the fields above, a measurement
-field: sent on both create and update, and included in the sync content
-hash so a session dir change alone triggers a resync. Like `repo_project`,
-it is an absolute local filesystem path (username, disk layout) — the same
-category of exposure the hub already accepts for `repo_project`, not a new
-one. An older hub predating this field simply ignores it (PocketBase
-silently drops unrecognized fields on write).
-
-**Privacy.** `KANKAKU_SYNC_PROMPT` controls whether a task's prompt text
-leaves the machine at all: `none` (default — omitted entirely), `truncated`
-(first 120 chars plus `…`), or `full`.
-
-**Commands:**
-
-- `/kankaku sync` — push everything pending (new tasks, plus anything
-  inside the revisit window that changed).
-- `/kankaku sync all` — a full re-evaluation: every task, not just the
-  window. Safe and cheap to run — the content hash still skips anything
-  unchanged.
-- `/kankaku sync status` — the current watermark, a locally-computed
-  pending count (no network), how many never-synced tasks fall outside the
-  current revisit window (needs `sync all` — see "Limitations" below), and
-  the last sync error, if any.
-- `/kankaku backfill` — a full sync, reported grouped by
-  `legacy_client_label`: how many tasks went to "Sin determinar" and under
-  which old label, so you know what to reassign in the web app's
-  unassigned queue. This never rewrites `worklog.jsonl` locally — the
-  reassignment happens once, in PocketBase, and survives every future sync
-  (see "Assignment is create-only" above).
-
-**Automatic sync.** Unless `KANKAKU_SYNC_AUTO=0`, kankaku also syncs
-automatically on three triggers (orchestrator role only): fire-and-forget
-(never awaited, errors never surface as a failure of the run that
-triggered them) on `session_start` (after crash recovery) and again after
-`agent_settled`; and, on `session_shutdown`, one **awaited**, time-bounded
-sync — pi awaits its `session_shutdown` handlers with no timeout of its
-own, so this is the one place kankaku's own handler awaits the network, up
-to `shutdownSyncTimeoutMs` (default 3 s). This is what makes the last
-prompt(s) of a session reach the hub when the session ends, rather than
-only on the next session's `session_start`: quitting with an unreachable
-hub costs at most that timeout longer, never more, and cleanup (status
-bar, session-client bookkeeping) still runs even if the sync times out or
-fails. All three triggers share one single-flight guard, so they never
-race each other within a process — a `session_shutdown` sync that arrives
-while one is already in flight awaits that same one rather than starting a
-second — and a lock file (`<KANKAKU_DIR>/sync.lock`, an atomic
-exclusive-create so two racing processes can never both acquire it, stale
-after 5 minutes) keeps two pi processes from syncing the same directory
-concurrently. Subagents never sync. None of the three triggers notify on
-success; on failure (including a shutdown timeout) they notify at most
-once per session (`kankaku: sync failed: ...` / `kankaku: shutdown sync
-timed out`) — check `/kankaku sync status` for the details, including on a
-later run.
-
-The automatic path is cheap on every prompt, not just fire-and-forget: it
-skips entirely (no read of `worklog.jsonl`, no network) when the log has
-not changed since the last successful sync, for all three triggers.
-Otherwise, only `agent_settled` — fired once per prompt — is throttled, to
-at most once per `KANKAKU_SYNC_MIN_INTERVAL_MINUTES` (default 5; `0`
-disables the throttle); since right after `agent_settled` the log *has*
-just changed (a record was just appended), this throttle is what actually
-keeps that trigger cheap. `session_start` and `session_shutdown` never
-throttle: a session boundary is worth catching up on regardless of how
-recently the last automatic run happened, so a stuck hub does not stay
-silently unsynced across restarts, and the shutdown sync is already
-bounded by its own timeout. None of this ever applies to a manual
-`/kankaku sync`, `sync all`, or `backfill`.
-
-**Network/validation failures.** A network or server (5xx) error stops a
-sync run where it is and does not advance its watermark past the failing
-task — nothing is lost, and the next sync (manual or automatic) picks up
-exactly there. A task that fails **validation** (e.g. a genuinely malformed
-payload) is recorded with its reason and skipped — not retried on every
-single run — but is retried automatically the moment its content changes.
-
-**Limitations:**
-
-- Sync state (`sync-state.json`) is per repository/machine, not
-  centralized; there is no standalone CLI entry point yet (`npx kankaku
-  sync` outside of pi) — see "Roadmap".
-- **A late background child, and the revisit window (R3).** A background
-  subagent can settle well after its (possibly cross-worktree)
-  orchestrator process has already exited — its record still writes
-  correctly into the orchestrator's `worklog.jsonl` (see "Subagents" >
-  "Cross-worktree write routing"), but nothing *syncs* it until that
-  directory is next visited: pi opened there again (`session_start`'s
-  auto-sync), or `/kankaku sync`/`sync all` run there manually. Subagents
-  themselves never sync (see "Automatic sync" above). An ordinary
-  incremental sync then picks the late child up wherever the task sits: a
-  task the hub **already holds** is re-synced whenever its content changed,
-  inside the revisit window or not, so a row on the hub never goes stale —
-  including a task that *shrank* because a child moved to another task. The
-  window (`syncedThrough - windowHours`) only bounds how far back work that
-  was **never synced** is looked for; `/kankaku sync status` reports how
-  many such tasks there are, and `/kankaku sync all` (or `backfill`)
-  uploads them.
-
-  **What the stale count means.** Only tasks outside the window that were
-  never synced to this hub. A task the hub already holds never appears
-  here: if it changed it is simply re-synced.
-
-## Tagged segments
-
-While a run is open, kankaku can also time tool executions that match a
-configured rule and tag the resulting span with a name — for example,
-knowing how much of a task went to gentle-ai's review-with-receipts step,
-which runs as `gentle-ai review ...` commands through the `bash` tool inside
-the prompt's run.
-
-The default rule tags `review`: tool `bash` running a command matching
-`/\bgentle-ai review\b/`. Configure rules with `KANKAKU_SEGMENTS`, a
-`;`-separated list of `tag=tool:regex` entries, e.g.:
+The Quick actions panel sits below the Hub card in wide mode (100+
+columns), or right after the Projects table in stacked mode (70-99
+columns):
 
 ```
-KANKAKU_SEGMENTS="review=bash:gentle-ai review;commit=bash:git commit"
-```
-
-Setting `KANKAKU_SEGMENTS` replaces the default rule entirely; malformed
-entries (missing tag, tool or regex, or an invalid regex) are skipped.
-When several rules could match the same tool call, only the first one
-applies. A `WorkRecord`'s `segments` field is the **union** of milliseconds
-per tag within that one record, so overlapping matching calls are not
-double-counted. `TaskView.segments` and `SessionView.segments` are instead
-the **sum** of `segments` across the orchestrator and its children (or
-across a session's tasks): segment spans are not persisted to
-`worklog.jsonl`, so once a record settles there is nothing left to union
-across records, only per-record totals to add up.
-
-Note that the reviewer's own token cost is not observable here: gentle-pi
-runs it with `--no-extensions`, so kankaku never sees the reviewer's own
-prompt/tool events, only the `bash` call the orchestrator makes to invoke
-it.
-
-## Crash recovery
-
-While a run is open, each pi process writes a checkpoint of its current
-record to `<KANKAKU_DIR>/inflight/<pid>.json` — first as soon as the run
-starts (`before_agent_start`), so even a crash on the very first turn still
-leaves a checkpoint, and then again after every `turn_end` and
-`tool_execution_end` — and removes it on a normal
-`agent_settled`/`session_shutdown`. If the process is killed outright
-(`kill -9`, power loss) before it can settle, the checkpoint file survives
-it. On the next pi start, `session_start` scans `inflight/` for checkpoints
-whose owning pid is no longer alive, appends each one to `worklog.jsonl` as
-`interrupted`, deletes the checkpoint file, and shows a
-`kankaku: recovered N interrupted record(s)` notice. `settledAt` on a
-recovered record is the time of its last checkpoint, not the actual crash
-time, so `wallMs`/`workMs` are a **lower bound** on the real duration.
-
-The same scan also sweeps `inflight/` for orphaned `.tmp` files: `save`
-writes to a temp file before renaming it into place, and a process killed
-between those two steps leaves the temp file behind. A stray `.tmp` file is
-deleted once its writer pid is no longer alive (or its name cannot be
-parsed); one still owned by a live writer — including this very process's
-own in-progress write — is left alone.
-
-## Export
-
-`/kankaku export [csv|json] [all]` writes one flat row per task (today's
-tasks by default, or every task with `all`) to
-`<KANKAKU_DIR>/export/tasks-<YYYY-MM-DD or all>.<csv|json>`, and confirms
-with the file's path and row count via the durable report card. Format
-defaults to `csv`; each subagent's own time is folded into its task's row
-rather than exported separately (see "Task and session views").
-
-Columns (in this order for CSV; the same fields for JSON):
-
-| Column | Meaning |
-| --- | --- |
-| `id` | Task id (the orchestrator record's `id`). |
-| `day` | Local calendar day (`YYYY-MM-DD`) the task started on. |
-| `startedAt` / `endedAt` | ISO timestamps of the task's span. |
-| `client` | Billing client, or empty when unresolved. |
-| `sessionName` | pi session display name, or empty. |
-| `sessionId` | pi session id, or empty. |
-| `project` | Project cwd. |
-| `status` | `completed`, `aborted`, or `interrupted`. |
-| `prompt` | First 200 chars of the prompt, newlines collapsed to spaces. |
-| `wallMs` / `waitingMs` / `workMs` | Union-based task timings (see "Task and session views"). |
-| `cost` | Estimated USD cost, orchestrator plus subagents. |
-| `tokensIn` / `tokensOut` / `cacheRead` | Token usage totals. |
-| `subagentCount` | Number of subagent records matched to the task. |
-| `segments` | JSON-encoded per-tag segment totals (see "Tagged segments"). |
-| `model` | The orchestrator record's model, or empty. |
-
-## Environment variables
-
-- `KANKAKU_DIR`: directory for the work log (`worklog.jsonl`) and the
-  crash-recovery checkpoints (`inflight/`, see above), relative to the
-  project cwd unless given as an absolute path. Defaults to `.kankaku`.
-- `KANKAKU_INTERACTIVE_TOOLS`: comma-separated list of tool names whose
-  execution span counts as waiting time. Defaults to
-  `ask_user_question,ask_user_choice`.
-- `KANKAKU_SEGMENTS`: `;`-separated `tag=tool:regex` rules for tagged
-  segments (see above). Defaults to the single `review` rule.
-- `KANKAKU_SUBAGENT_TOOLS`: comma-separated list of additional tool names
-  treated as subagent-opening spans, parsed exactly like
-  `KANKAKU_INTERACTIVE_TOOLS`. Always additive to the built-in profiles
-  (gentle-pi, pi's bundled reference example, pi-subagents) — never
-  replaces gentle-pi's own recognition. See "Subagents" > "Subagent
-  profiles (phase 6b)". Unset by default (built-in profiles' tool names
-  only).
-- `KANKAKU_SUBAGENT_CHILD_ENV`: `;`-separated `NAME=VALUE` (exact match) or
-  bare `NAME` (presence-only) child-process env markers that confirm a
-  process as the configured tool's subagent — parsed like `KANKAKU_SEGMENTS`,
-  malformed entries skipped. The separator is `;`, **not** the `,` that
-  `KANKAKU_SUBAGENT_TOOLS` takes: a name that is not a valid environment
-  variable name (such as `A,B`) is rejected and reported, never silently
-  accepted. A name that looks pi/shell/OS/npm-owned
-  (`PI_CODING_AGENT`, `AI_AGENT`, `PATH`, `HOME`, `USER`, `SHELL`, `PWD`,
-  `CI`, `LANG`, `TMUX`, or a `PI_`/`TERM`/`LC_`/`NODE_`/`NPM_`/`KANKAKU_`
-  prefix, case-insensitive) is rejected outright, and even an accepted
-  marker never demotes an interactive session — see "Subagents" > "Subagent
-  profiles (phase 6b)" for both layers, and verify with `/kankaku doctor`.
-  Unset by default.
-- `KANKAKU_ROLE`: `orchestrator` or `subagent` — an explicit escape hatch
-  for this process. Any other value is ignored. Scope it to one
-  invocation (`KANKAKU_ROLE=orchestrator pi ...`) — **never export it in
-  a shell rc, tmux config, or CI environment file**: a confirmed child
-  marker always wins over `KANKAKU_ROLE=orchestrator`, `KANKAKU_ROLE=
-  subagent` is ignored for an interactive session, and kankaku strips it
-  from the environment it passes to any child it spawns, but none of that
-  helps if it reaches a session it was never meant for in the first
-  place. See "Subagents" > "Interactive sessions and `KANKAKU_ROLE`" for
-  the full precedence.
-- `KANKAKU_CLIENT`: default billing client for this project (see "Billing
-  labels" above). Lower precedence than the session-level
-  `/kankaku client` override, higher than `<KANKAKU_DIR>/config.json`.
-- `KANKAKU_PB_URL`, `KANKAKU_PB_EMAIL`, `KANKAKU_PB_PASSWORD`: hub
-  (PocketBase) credentials (see "Hub (PocketBase)" above). Take precedence,
-  field by field, over `~/.kankaku/credentials.json`.
-- `KANKAKU_MACHINE`: this machine's display name for the hub, attached to
-  every record as `machine` once the hub is configured. Defaults to the OS
-  hostname.
-- `KANKAKU_SYNC_PROMPT`: prompt privacy for sync — `none` (default, omitted
-  entirely), `truncated` (first 120 chars + `…`), or `full`. See "Hub
-  (PocketBase)" > "Sync" > "Privacy".
-- `KANKAKU_SYNC_WINDOW_HOURS`: how far behind the sync watermark to revisit
-  on every run, so a subagent that settles after its orchestrator still
-  reaches its task. Defaults to 24; a non-positive or non-numeric value
-  falls back to the default.
-- `KANKAKU_SYNC_RECORDS`: `0` disables uploading `work_records` (raw
-  per-`WorkRecord` detail); `task_entries` are always uploaded regardless.
-  Defaults to enabled.
-- `KANKAKU_SYNC_AUTO`: `0` disables the automatic `session_start`/
-  `agent_settled`/`session_shutdown` sync; `/kankaku sync` still works.
-  Defaults to enabled.
-- `KANKAKU_SYNC_MIN_INTERVAL_MINUTES`: how often the automatic
-  `agent_settled` sync is allowed to actually run, at most — see
-  "Automatic sync" above. Defaults to 5; `0` disables the throttle. Only
-  ever applies to `agent_settled`: `session_start` and `session_shutdown`
-  are never throttled, and none of this applies to a manual `/kankaku
-  sync`, `sync all`, or `backfill`.
-
-## Using kankaku as a library
-
-Besides the pi extension, `kankaku` publishes three compiled, pi-free entry
-points for a plain Node consumer — no pi, no TypeScript loader — such as a
-separate CLI or another agent's plugin (e.g. the `kankaku-claude` package):
-
-- `kankaku/domain` — the pure domain layer: `WorkTracker`, `buildTasks`,
-  `unionMs`, and the rest of `src/domain/`.
-- `kankaku/ports` — the port interfaces only (`Clock`, `WorkLog`, `Catalog`,
-  `WorkSink`, `ProcessRegistry`, `InflightStore`), for writing your own
-  adapters against.
-- `kankaku/hub` — the pi-free adapters: the PocketBase HTTP client and
-  catalog/sink, `runSync`, the JSONL work log, the cached catalog, hub
-  credentials, and related filesystem helpers; also the report formatters
-  and the five report view builders (`formatReport`, `summarize`,
-  `buildSummaryView`, `buildTasksView`, etc.), the hub action line-builders
-  (`buildSyncStatusLines`, `formatSyncSummaryLines`, ...), the export
-  writer (`writeExport`) and the project config reader/writer
-  (`readProjectTargetIds`, `writeProjectTargetIds`). These exist so a
-  standalone CLI or TUI (e.g. a future Ink-based one) can render the exact
-  same reports and hub actions as the `/kankaku` subcommands and panel,
-  without reimplementing them. Nothing reachable from this entry point ever
-  imports a pi package type.
-
-```js
-import { runSync } from "kankaku/hub";
-import { buildTasks } from "kankaku/domain";
+╭─[ Quick actions ]────────────────╮
+│ c  refresh catalog               │
+│ s  sync all projects             │
+│ S  full sync all                 │
+│ r  reload                        │
+│ catalog: 9 clients · 17 projects │
+╰──────────────────────────────────╯
 ```
 
-Each entry point is compiled ahead of time (`npm run build`, part of `npm
-run check`) to `dist/<domain|ports|hub>/index.{js,d.ts}` and resolved
-through `package.json`'s `exports` map, so importing it never needs type
-stripping or a `.ts` loader. `kankaku/src/*` is how pi itself loads
-`./src/extension.ts` and is not a public API — its shape can change without
-notice; import only `kankaku/domain`, `kankaku/ports`, or `kankaku/hub`.
-
-## Limitations
-
-- A prompt shown by a tool that does not go through `ctx.ui` and is not
-  listed in `KANKAKU_INTERACTIVE_TOOLS` counts as work, not waiting time.
-- Subagent totals are reported separately in the per-role summary and are
-  **not** summed into the orchestrator's `wallMs` there: task-mode subagents
-  run inside the parent's wall clock, and background subagents can outlive
-  the parent's idle moment, so naively adding them would double-count or
-  misrepresent billable time. Use the task/session views above (union-based,
-  never a sum) for a correct combined figure.
-
-## Roadmap
-
-- Hub sync (phase 2): push consolidated task rows to PocketBase (outbox
-  pattern, idempotent upsert by task id) so a task/project manager can
-  report AI time and cost per project. The catalog/selection layer in "Hub
-  (PocketBase)" above is phase 1; sync itself ("Hub (PocketBase)" > "Sync")
-  is phase 2 — both already shipped.
-- A standalone CLI entry point (`npx kankaku sync`, for a cron/launchd job
-  outside of any pi session) is deliberately not included yet. The build
-  step it needs now exists — `sync-runner.ts` and its adapters are
-  published pi-free and pre-compiled as `kankaku/hub` (see "Using kankaku
-  as a library") — but a `bin` script that wires that up as a runnable CLI
-  is not; the compiled entry points are today consumed as a library, not a
-  binary.
-- Linking a `task_entries` row to an existing `tasks` record (phase 3 in the
-  hub's own data model) has shipped: `/kankaku task pick`/`clear` (see
-  "Linking to a hub task" above). Creating a task from pi
-  (`/kankaku task new`) is deliberately not included — kankaku never
-  invents tasks; it only ever links to one already created in the manager.
-- Generic subagent detection (phase 6): 6a fixed the two correctness bugs
-  described in "Subagents" above (a phantom-orchestrator double count; a
-  gentle-pi cross-worktree child's work going missing). 6b added the
-  `SubagentProfile` abstraction, built-in profiles for pi's bundled
-  reference example and pi-subagents alongside gentle-pi, and
-  `KANKAKU_SUBAGENT_TOOLS`/`KANKAKU_SUBAGENT_CHILD_ENV` for a third-party
-  tool kankaku does not recognise out of the box. 6c added subagent-result
-  `usage` forwarding and the same-pid overlapping-orchestrator guard — see
-  "Subagents" > "Subagent profiles (phase 6b)" / "In-process subagents
-  (phase 6c)" above. Built-in profiles beyond these three
-  (`pi-background-tasks`, `@d3ara1n/pi-subagent`), gentle-pi handing a
-  child its own task id, and the cosmetic `linked_task_id` hub
-  self-relation remain out of scope.
+The bottom line is the status line: empty until the first action runs,
+`… <label>` while one is running, its result message once it settles
+(e.g. the catalog refresh above, or a sync summary), `error: <message>`
+if it failed, or `hub not configured (~/.kankaku/credentials.json)` when
+the hub has no credentials — in which case `c`/`s`/`S` do nothing.
+
+- **Tasks** — a table (time, project, work, cost, prompt) with a
+  highlighted row on the left, and a `[ Task ]` detail panel on the right
+  showing the selected row's full prompt, client, project, hub task,
+  wall/work/wait time, cost, cache hit and subagent count.
+- **Catalog** — `[ Clients ]` on the left; the selected client's
+  `[ Projects ]`, with open/doing hub task counts, on the right. The
+  Clients panel header shows the cache's age and a `(stale)` flag.
+- **Sync** — one card per project in a wrapping grid; the selected card is
+  highlighted, and each action's result line shows inside its card while
+  it runs and once it settles.
+
+## Keys (TUI)
+
+The app has two focus zones — the sidebar and the active screen's own main
+content — and one of them always has focus (`domain/nav-model.ts`'s
+`NavState.focus`, starting on the sidebar). `1`-`4` switch the Dashboard/
+Tasks/Catalog/Sync tab bar and `q` quits from anywhere, in either zone; every
+other key belongs to whichever zone currently has focus, so a screen's own
+list never moves by accident while you are still picking a screen.
+
+- **Sidebar focused** (the app's own starting state) — `↑`/`↓` move
+  between screens, and the screen switches as you move, so you see each
+  one before committing to it. `enter`, `→` or `Tab` focus the main zone
+  (the screen you last landed on).
+- **Main zone focused** — the active screen's own keys work as below.
+  `←` or `Tab` return focus to the sidebar. `esc` also returns to the
+  sidebar, unless the screen consumes it first: on Tasks with a project
+  filter set (from Dashboard's `enter`), the first `esc` clears the filter
+  and the next `esc` returns to the sidebar.
+
+The focused zone is visible in the frame: the sidebar's active-item marker
+is in the accent colour when the sidebar is focused and muted otherwise,
+the focused screen's primary panel gets the accent border, and the footer
+key hints change — the sidebar's own hints while it is focused, the
+screen's hints plus `← menu` while the main zone is focused.
+
+The app fills the whole terminal; every scrolling list (Tasks, Catalog's
+Clients/Projects, Dashboard's Projects, Sync's cards) additionally takes
+`PageUp`/`PageDown` to move a full window at a time and `Home`/`End` to
+jump to the first/last row.
+
+- **Dashboard** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the
+  Projects selection, `enter` opens the selected project in Tasks
+  (filtered to it), `r` refresh; the Quick actions panel additionally
+  takes `c` (refresh catalog), `s` (sync all projects) and `S` (full sync
+  all) — one at a time, ignored while another is running.
+- **Tasks** — `a` toggle today/all, `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End`
+  move the selection, `r` refresh, `esc` clears a project filter set from
+  Dashboard.
+- **Catalog** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the client
+  selection, `r` refresh from the hub.
+- **Sync** — `↑`/`↓`/`PageUp`/`PageDown`/`Home`/`End` move the selection,
+  `s` sync the selected project, `f` full-sync the selected project, `S`
+  sync every project. Each action's summary shows inline in its card
+  while it runs and once it settles.
+
+The TUI never writes to disk on its own — Dashboard, Tasks and read-only
+Catalog views write nothing at all; Catalog's `refresh`, Sync's
+`s`/`f`/`S` and Dashboard's Quick actions `c`/`s`/`S` write only through
+kankaku's own adapters (`CachedCatalog`, `SyncStateStore`, the hub
+itself), exactly as kankaku's own sync paths do.