kankaku-tui 0.2.1 → 0.3.1

package/README.md

@@ -15,24 +15,60 @@ npm i -g kankaku-tui
 kankaku setup
 ```
 
-`kankaku setup` detects every coding agent kankaku knows how to configure
-on this machine (pi, gentle-shell, Claude Code — each by its own settings
-file) and, for each one that already exists but isn't wired up, offers to
-add it: `npm:kankaku` to a pi-family `packages` array, or Claude Code's
-`statusLine` pointing at a `kankaku-claude` checkout. It also offers to
-configure hub credentials (reusing `~/.kankaku/credentials.json` or the
-`KANKAKU_PB_*` environment when either is already set) and writes this
-app's own `~/.kankaku/tui.json`. Codex and OpenCode are detected and
-reported, but kankaku has no adapter for either yet.
-
-Every question has a sensible default; `kankaku setup --yes` accepts every
-default without asking, and `kankaku setup --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 prompt answer or `--yes`. Before the first change to
-any file, kankaku setup creates a `<file>.bak` next to it; re-running
-`kankaku setup` is always safe, since it only ever writes what is still
-missing or what you explicitly change.
+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/5`, numbering only the
+steps this run will actually show). `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).
+2. **Claude Code** — the `kankaku-claude` checkout path (only shown when
+   Claude Code is checked and not already configured), guessed from any
+   existing `statusLine`.
+3. **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 looks for a
+   `kankaku-hub` checkout first; if found, its path is prefilled and
+   confirming it downloads PocketBase, starts the dev server in the
+   background and creates a **development** service account (its email
+   and password are fixed constants from `kankaku-hub`'s own dev script,
+   never meant for anything but a local machine) — the wizard writes that
+   account as this machine's hub credentials. Without a checkout, the
+   wizard shows the exact commands to run in another terminal and a `c`
+   "check again" action, plus `m` to acknowledge you'll install it
+   manually.
+4. **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.
+5. **Review** — the plan: one line per change, with the exact file it
+   touches. `enter` applies it.
+6. **Apply** — runs each change and shows its result
+   (`wrote`/`unchanged`/`removed`/`started`/`error: …`) as it happens.
+7. **Done** — a summary, then `enter` opens the Dashboard in place — no
+   restart.
+
+`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
@@ -57,10 +93,23 @@ this repo with `npm run dev`.
 }
 ```
 
-Each root is either a project itself (it has its own `.kankaku/worklog.jsonl`)
-or a directory containing one or more projects as direct subdirectories.
-`~` expands to the home directory. Missing or malformed config falls back
-to the current working directory as the only root.
+### 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)
 

package/dist/adapters/project-discovery.js

@@ -1,12 +1,20 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+/** How many directory levels below each root {@link discoverProjects} descends into by default. */
+const DEFAULT_MAX_DEPTH = 5;
+const SKIPPED_DIR_NAMES = new Set(["node_modules", ".git"]);
 function hasWorklog(dir) {
     return existsSync(join(dir, ".kankaku", "worklog.jsonl"));
 }
-function childDirs(root) {
+/** `node_modules`, `.git`, and any dot-prefixed (hidden) directory are never searched. */
+function isSkipped(name) {
+    return name.startsWith(".") || SKIPPED_DIR_NAMES.has(name);
+}
+function childDirs(dir) {
     try {
-        return readdirSync(root)
-            .map((entry) => join(root, entry))
+        return readdirSync(dir)
+            .filter((name) => !isSkipped(name))
+            .map((name) => join(dir, name))
             .filter((entry) => {
             try {
                 return statSync(entry).isDirectory();
@@ -21,23 +29,72 @@ function childDirs(root) {
     }
 }
 /**
- * Discover projects under `roots`: a root that itself has
- * `.kankaku/worklog.jsonl` is a project; otherwise each direct child
- * directory with one is a project. Deduped by `dir`, sorted by `name`.
- * Never throws on an unreadable or missing root.
+ * The real (symlink-resolved) path, used only as the dedup key — the
+ * `ProjectRef.dir` returned to callers always stays the path as
+ * discovered. Falls back to `dir` itself when it cannot be resolved (e.g.
+ * a permission error), so an unreadable directory never throws.
+ */
+function realDirPath(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return dir;
+    }
+}
+/**
+ * Walk `dir`, `depth` levels below its root: a directory with
+ * `.kankaku/worklog.jsonl` is a project, and the walk still continues
+ * below it — a pi session run once in a parent directory (`~/desarrollo`)
+ * leaves a worklog there, and that stray file must never hide the real
+ * projects beneath (`~/desarrollo/<client>/<project>`). Subdirectories
+ * (skipping `node_modules`, `.git` and any hidden directory) are walked
+ * one level deeper, up to `maxDepth`.
  */
-export function discoverProjects(roots) {
-    const byDir = new Map();
+function walk(dir, depth, maxDepth, found) {
+    if (hasWorklog(dir))
+        found.set(realDirPath(dir), dir);
+    if (depth >= maxDepth)
+        return;
+    for (const child of childDirs(dir)) {
+        walk(child, depth + 1, maxDepth, found);
+    }
+}
+/** `basename(dir)`, or the last two path segments joined with `/` when that basename is ambiguous (shared by another discovered project). */
+function projectName(dir, duplicateBasenames) {
+    const base = basename(dir);
+    if (!duplicateBasenames.has(base))
+        return base;
+    const segments = dir.split(sep).filter((segment) => segment.length > 0);
+    return segments.slice(-2).join("/");
+}
+/**
+ * Discover projects under `roots`, searching up to `options.maxDepth`
+ * directory levels below each root (default {@link DEFAULT_MAX_DEPTH}): a
+ * directory with `.kankaku/worklog.jsonl` is a project and is never
+ * descended into (so a project nested inside another project is never
+ * double-counted); otherwise its subdirectories are searched one level
+ * deeper, skipping `node_modules`, `.git` and any hidden (dot-prefixed)
+ * directory. Deduped by real (symlink-resolved) path; sorted by `name`,
+ * which is the directory basename, or the last two path segments joined
+ * with `/` when two discovered projects share a basename. Never throws on
+ * an unreadable or missing root or subdirectory — those are silently
+ * skipped.
+ */
+export function discoverProjects(roots, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const found = new Map();
     for (const root of roots) {
-        if (hasWorklog(root)) {
-            byDir.set(root, { name: basename(root), dir: root });
-            continue;
-        }
-        for (const child of childDirs(root)) {
-            if (hasWorklog(child)) {
-                byDir.set(child, { name: basename(child), dir: child });
-            }
-        }
+        walk(root, 0, maxDepth, found);
+    }
+    const dirs = Array.from(found.values());
+    const basenameCounts = new Map();
+    for (const dir of dirs) {
+        const base = basename(dir);
+        basenameCounts.set(base, (basenameCounts.get(base) ?? 0) + 1);
     }
-    return Array.from(byDir.values()).sort((a, b) => a.name.localeCompare(b.name));
+    const duplicateBasenames = new Set(Array.from(basenameCounts.entries())
+        .filter(([, count]) => count > 1)
+        .map(([base]) => base));
+    return dirs.map((dir) => ({ name: projectName(dir, duplicateBasenames), dir })).sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/adapters/setup/child-process-runner.js

@@ -0,0 +1,33 @@
+/**
+ * The real `ScriptRunner`: `node:child_process` over the given cmd/args.
+ * `run` collects stdout/stderr and waits for exit; `spawnDetached` starts a
+ * detached, unref'd process whose combined output is appended to `logFile`,
+ * for `local-hub.ts#installLocalHub`'s `dev.sh`.
+ */
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+export function createChildProcessRunner() {
+    return {
+        run(cmd, args, opts) {
+            return new Promise((resolve, reject) => {
+                const child = spawn(cmd, args, { cwd: opts.cwd });
+                let stdout = "";
+                let stderr = "";
+                child.stdout?.on("data", (chunk) => {
+                    stdout += chunk.toString();
+                });
+                child.stderr?.on("data", (chunk) => {
+                    stderr += chunk.toString();
+                });
+                child.on("error", reject);
+                child.on("close", (code) => resolve({ code: code ?? -1, stdout, stderr }));
+            });
+        },
+        spawnDetached(cmd, args, opts) {
+            const fd = openSync(opts.logFile, "a");
+            const child = spawn(cmd, args, { cwd: opts.cwd, detached: true, stdio: ["ignore", fd, fd] });
+            child.unref();
+            return { pid: child.pid ?? -1 };
+        },
+    };
+}

package/dist/adapters/setup/claude.js

@@ -23,3 +23,22 @@ export function writeStatusLine(settingsPath, checkoutPath) {
     writeJsonAtomic(settingsPath, { ...existing, statusLine: { type: "command", command } });
     return { changed: true };
 }
+/**
+ * Removes `statusLine` only when its `command` contains `"kankaku"` (i.e.
+ * it looks like kankaku's own statusline, not some other tool's), leaving
+ * every other key untouched. A no-op, with no backup and no write, when
+ * there is no `statusLine` or it belongs to something else.
+ */
+export function removeStatusLine(settingsPath) {
+    const existing = readJsonObjectOrEmpty(settingsPath);
+    const currentStatusLine = existing["statusLine"];
+    const currentCommand = currentStatusLine && typeof currentStatusLine === "object" && !Array.isArray(currentStatusLine)
+        ? currentStatusLine["command"]
+        : undefined;
+    if (typeof currentCommand !== "string" || !currentCommand.includes("kankaku"))
+        return { changed: false };
+    backupOnce(settingsPath);
+    const { statusLine: _statusLine, ...rest } = existing;
+    writeJsonAtomic(settingsPath, rest);
+    return { changed: true };
+}

package/dist/adapters/setup/local-hub.js

@@ -0,0 +1,86 @@
+/**
+ * Level-1 local hub install for the setup wizard's "install locally" hub
+ * option: finds a `kankaku-hub` checkout, runs its own dev scripts through
+ * the injected `ScriptRunner` (never spawning the real hub in tests), and
+ * returns the service account `scripts/create-dev-accounts.sh` creates.
+ * The service account's email/password are that script's own hardcoded
+ * constants (`SERVICE_EMAIL`/`SERVICE_PASSWORD`), read from
+ * `kankaku-hub/scripts/create-dev-accounts.sh`, not environment-overridable
+ * there — kept identical here so the credentials this writes always match
+ * what the script actually created.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const HUB_URL = "http://127.0.0.1:8090";
+const SERVICE_EMAIL = "kankaku-sync@kankaku.local";
+const SERVICE_PASSWORD = "kankaku-dev-sync";
+const DEFAULT_CHECKOUT_DIR = "~/desarrollo/soyun.ninja/kankaku-hub";
+/** The real `kankaku-hub` remote (`git -C <repo> remote get-url origin`), in its https form so no SSH key is required for a one-off clone. */
+const HUB_CLONE_URL = "https://github.com/soyunninja/kankaku_hub.git";
+const HEALTH_POLL_TIMEOUT_MS = 20000;
+const HEALTH_POLL_INTERVAL_MS = 500;
+/** The first `candidates` entry that looks like a `kankaku-hub` checkout: has `scripts/dev.sh` and `pocketbase/pb_migrations`. */
+export function findHubCheckout(candidates) {
+    return candidates.find((candidate) => existsSync(join(candidate, "scripts", "dev.sh")) && existsSync(join(candidate, "pocketbase", "pb_migrations")));
+}
+async function pollHealth(url, deps) {
+    const deadline = deps.now() + HEALTH_POLL_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const response = await deps.fetch(url);
+            if (response.ok)
+                return true;
+        }
+        catch {
+            // Not up yet; keep polling until the deadline.
+        }
+        if (deps.now() >= deadline)
+            return false;
+        await deps.sleep(HEALTH_POLL_INTERVAL_MS);
+    }
+}
+/**
+ * Installs the local hub from `checkout`: downloads PocketBase (skipped
+ * when `pocketbase/bin/pocketbase` already exists), starts `scripts/dev.sh`
+ * detached (pid at `~/.kankaku/hub/pid`, log at `~/.kankaku/hub/dev.log`),
+ * polls `<HUB_URL>/api/health` for up to ~20s, then runs
+ * `scripts/create-dev-accounts.sh`. Returns the local hub's URL and service
+ * account on success, or `ok: false` with an `error` at the first failing
+ * step — never throws.
+ */
+export async function installLocalHub(checkout, deps) {
+    const pocketbaseBinary = join(checkout, "pocketbase", "bin", "pocketbase");
+    if (!existsSync(pocketbaseBinary)) {
+        const download = await deps.runner.run(join(checkout, "scripts", "pb-download.sh"), [], { cwd: checkout });
+        if (download.code !== 0) {
+            return { ok: false, url: HUB_URL, error: `pb-download.sh failed: ${download.stderr || download.stdout || `exit code ${download.code}`}` };
+        }
+    }
+    const hubDir = join(deps.homeDir, ".kankaku", "hub");
+    mkdirSync(hubDir, { recursive: true });
+    const logFile = join(hubDir, "dev.log");
+    const { pid } = deps.runner.spawnDetached(join(checkout, "scripts", "dev.sh"), [], { cwd: checkout, logFile });
+    writeFileSync(join(hubDir, "pid"), String(pid));
+    const healthy = await pollHealth(`${HUB_URL}/api/health`, deps);
+    if (!healthy) {
+        return { ok: false, url: HUB_URL, error: "the local hub did not become healthy within 20s" };
+    }
+    const accounts = await deps.runner.run(join(checkout, "scripts", "create-dev-accounts.sh"), [], { cwd: checkout });
+    if (accounts.code !== 0) {
+        return { ok: false, url: HUB_URL, error: `create-dev-accounts.sh failed: ${accounts.stderr || accounts.stdout || `exit code ${accounts.code}`}` };
+    }
+    return { ok: true, url: HUB_URL, serviceEmail: SERVICE_EMAIL, servicePassword: SERVICE_PASSWORD };
+}
+/**
+ * The exact command lines to show when no `kankaku-hub` checkout was
+ * found: clone it (unless `checkout` names one already on disk), then run
+ * its three dev scripts in order.
+ */
+export function manualCommands(checkout) {
+    const dir = checkout ?? DEFAULT_CHECKOUT_DIR;
+    const lines = [];
+    if (!checkout)
+        lines.push(`git clone ${HUB_CLONE_URL} ${dir}`);
+    lines.push(`cd ${dir}`, "scripts/pb-download.sh", "scripts/dev.sh &", "scripts/create-dev-accounts.sh");
+    return lines;
+}

package/dist/adapters/setup/pi.js

@@ -19,3 +19,18 @@ export function addKankakuPackage(settingsPath) {
     writeJsonAtomic(settingsPath, { ...existing, packages: [...packages, "npm:kankaku"] });
     return { changed: true };
 }
+/**
+ * Removes every `packages` entry `isKankakuPackage` identifies as kankaku,
+ * leaving every other entry and key untouched. A no-op, with no backup and
+ * no write, when none is present.
+ */
+export function removeKankakuPackage(settingsPath) {
+    const existing = readJsonObjectOrEmpty(settingsPath);
+    const packages = isStringArray(existing["packages"]) ? existing["packages"] : [];
+    const filtered = packages.filter((entry) => !isKankakuPackage(entry));
+    if (filtered.length === packages.length)
+        return { changed: false };
+    backupOnce(settingsPath);
+    writeJsonAtomic(settingsPath, { ...existing, packages: filtered });
+    return { changed: true };
+}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { jsx as _jsx } from "react/jsx-runtime";
 import { homedir, hostname } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { existsSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { render } from "ink";
@@ -21,10 +21,12 @@ import { buildSyncRows } from "./domain/sync-model.js";
 import { DEFAULT_THEME, ThemeProvider, resolveTheme } from "./ui/theme.js";
 import { detectAgents, formatDoctorLines, formatSetupPlanLines, planSetup } from "./domain/setup-plan.js";
 import { readAgentFacts } from "./adapters/setup/agents.js";
-import { addKankakuPackage } from "./adapters/setup/pi.js";
-import { writeStatusLine } from "./adapters/setup/claude.js";
+import { addKankakuPackage, removeKankakuPackage } from "./adapters/setup/pi.js";
+import { removeStatusLine, writeStatusLine } from "./adapters/setup/claude.js";
 import { checkHubHealth, credentialsPath, writeHubCredentials } from "./adapters/setup/hub.js";
 import { tuiConfigPath, writeTuiConfig } from "./adapters/setup/tui-config.js";
+import { findHubCheckout, installLocalHub, manualCommands } from "./adapters/setup/local-hub.js";
+import { createChildProcessRunner } from "./adapters/setup/child-process-runner.js";
 import { createReadlinePrompter } from "./adapters/setup/readline-prompter.js";
 const USAGE = "usage: kankaku [today|tasks [--all]|catalog [refresh]|sync [status|all] [--project <dir>]|setup [--yes] [--dry-run]|doctor] [--roots a,b] [--theme name]\n";
 /** Load today's model for `roots`: discover projects, read their worklogs, build rows. */
@@ -225,6 +227,113 @@ async function runDoctorCommand(deps) {
     const { agents, hub, tui } = await gatherSetupFacts(deps);
     deps.stdout(formatDoctorLines(agents, hub, tui).join("\n"));
 }
+/** Plausible `kankaku-hub` checkout locations to probe for the wizard's Hub step: a sibling of this project's parent, and the documented default under the home directory. */
+function localHubCandidates(deps) {
+    return [join(deps.homeDir, "desarrollo", "soyun.ninja", "kankaku-hub"), join(dirname(deps.cwd), "kankaku-hub")];
+}
+/**
+ * Gather the plain facts the setup wizard needs (`domain/setup-wizard.ts#createWizardState`):
+ * every detected agent, current hub credentials (reused as the "existing
+ * hub" step's defaults) and current `tui.json` roots. Entirely read-only,
+ * with no network call — the hub's health is checked interactively, from
+ * the wizard's own Hub step, never upfront.
+ */
+function gatherWizardFacts(deps) {
+    const agentFacts = readAgentFacts(deps.homeDir);
+    const hubResolution = resolveHub({ env: deps.env ?? {}, homeDir: () => deps.homeDir });
+    const credPath = credentialsPath(deps.homeDir);
+    const localCheckoutGuess = findHubCheckout(localHubCandidates(deps)) ?? join(deps.homeDir, "desarrollo", "soyun.ninja", "kankaku-hub");
+    const hub = hubResolution.ok
+        ? {
+            credentialsPresent: true,
+            url: hubResolution.credentials.url,
+            email: hubResolution.credentials.email,
+            password: hubResolution.credentials.password,
+            credentialsPath: credPath,
+            localCheckoutGuess,
+        }
+        : { credentialsPresent: false, url: undefined, email: undefined, password: undefined, credentialsPath: credPath, localCheckoutGuess };
+    const tuiPath = tuiConfigPath(deps.homeDir);
+    const roots = {
+        current: existsSync(tuiPath) ? readTuiConfig(deps.homeDir, deps.cwd).roots : undefined,
+        defaultRoots: [dirname(deps.cwd)],
+        path: tuiPath,
+    };
+    return { agentFacts, hub, roots, homeDir: deps.homeDir };
+}
+/** Runs `adapters/setup/local-hub.ts#installLocalHub` for real, sharing one `ScriptRunner`/timer setup between the wizard's `installLocalHub` action and `apply`'s own `install-local-hub` handling. */
+async function performLocalHubInstall(checkout, deps) {
+    const { now, fetch: fetchOverride } = envDeps(deps);
+    const result = await installLocalHub(checkout, {
+        runner: createChildProcessRunner(),
+        homeDir: deps.homeDir,
+        fetch: fetchOverride ?? fetch,
+        now,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    if (!result.ok)
+        throw new Error(result.error ?? "installing the local hub failed");
+    return { url: result.url, serviceEmail: result.serviceEmail, servicePassword: result.servicePassword };
+}
+/**
+ * Apply one planned `WizardAction` for real, through the matching
+ * `adapters/setup/*` writer. Several kinds need a value `planFromWizard`
+ * never put in the action itself (`file` is always the target path, not
+ * what to write) — `state` carries it: `state.claudeCheckout` for
+ * `write-claude`, `state.hub` for `write-hub`, `state.roots` for
+ * `write-roots`. `install-local-hub` runs the real installer, then writes
+ * its returned dev-account credentials as the hub, labelling them as dev
+ * defaults in the result detail. Never throws: any adapter failure becomes
+ * an `"error"` outcome instead.
+ */
+async function applyWizardAction(action, state, deps) {
+    try {
+        switch (action.kind) {
+            case "install-pi": {
+                const result = addKankakuPackage(action.file);
+                return { action, outcome: result.changed ? "wrote" : "unchanged" };
+            }
+            case "remove-pi": {
+                const result = removeKankakuPackage(action.file);
+                return { action, outcome: result.changed ? "removed" : "unchanged" };
+            }
+            case "write-claude": {
+                const result = writeStatusLine(action.file, state.claudeCheckout);
+                return { action, outcome: result.changed ? "wrote" : "unchanged" };
+            }
+            case "remove-claude": {
+                const result = removeStatusLine(action.file);
+                return { action, outcome: result.changed ? "removed" : "unchanged" };
+            }
+            case "write-hub": {
+                const result = writeHubCredentials(deps.homeDir, { url: state.hub.url, email: state.hub.email, password: state.hub.password });
+                return { action, outcome: result.changed ? "wrote" : "unchanged" };
+            }
+            case "install-local-hub": {
+                const installed = await performLocalHubInstall(action.file, deps);
+                writeHubCredentials(deps.homeDir, { url: installed.url, email: installed.serviceEmail, password: installed.servicePassword });
+                return { action, outcome: "started", detail: `running at ${installed.url} (dev defaults: ${installed.serviceEmail} / ${installed.servicePassword})` };
+            }
+            case "write-roots": {
+                const result = writeTuiConfig(deps.homeDir, state.roots);
+                return { action, outcome: result.changed ? "wrote" : "unchanged" };
+            }
+        }
+    }
+    catch (error) {
+        return { action, outcome: "error", detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Build the setup wizard's `WizardActions` for the interactive app: every write goes through the same real `adapters/setup/*` writers `kankaku setup --yes` uses. Used only by `renderApp`. */
+function buildWizardActions(deps) {
+    return {
+        apply: (action, state) => applyWizardAction(action, state, deps),
+        checkHealth: (url) => checkHubHealth(url, { fetch: deps.fetch }),
+        findHubCheckout: () => findHubCheckout(localHubCandidates(deps)),
+        manualCommands: (checkout) => manualCommands(checkout),
+        installLocalHub: (checkout) => performLocalHubInstall(checkout, deps),
+    };
+}
 /**
  * Extract a plausible kankaku-claude checkout path from an existing
  * `statusLine.command` of the shape `node "<checkout>/src/statusline.ts"`,
@@ -352,7 +461,10 @@ export async function runCli(argv, deps) {
     const { roots, rest } = parseRoots(argvAfterTheme, deps);
     const [command] = rest;
     if (command === undefined) {
-        deps.renderApp(roots, theme);
+        // First-run hint: no `tui.json` yet means this machine has never been
+        // set up — open straight into the wizard instead of an empty Dashboard.
+        const startInWizard = !existsSync(tuiConfigPath(deps.homeDir));
+        deps.renderApp(roots, theme, { startInWizard });
         return;
     }
     if (command === "today") {
@@ -373,7 +485,13 @@ export async function runCli(argv, deps) {
         return;
     }
     if (command === "setup") {
-        await runSetupCommand(rest.slice(1), deps);
+        const setupArgs = rest.slice(1);
+        const interactiveTTY = !setupArgs.includes("--yes") && !setupArgs.includes("--dry-run") && (deps.isTTY?.() ?? false);
+        if (interactiveTTY) {
+            deps.renderApp(roots, theme, { startInWizard: true });
+            return;
+        }
+        await runSetupCommand(setupArgs, deps);
         return;
     }
     if (command === "doctor") {
@@ -504,9 +622,10 @@ if (isMain) {
         exit: (code) => {
             process.exit(code);
         },
+        isTTY: () => process.stdout.isTTY === true,
         prompter: createReadlinePrompter(process.stdin, process.stdout),
-        renderApp: (roots, theme) => {
-            render(_jsx(ThemeProvider, { theme: theme, children: _jsx(App, { roots: roots, version: readOwnVersion(), loadToday: () => loadDashboard(roots, realDeps), loadTasks: (options) => loadTasks(roots, options), catalog: catalogScreenDeps(realDeps), sync: syncScreenDeps(realDeps, roots), dashboardActions: dashboardActionsDeps(realDeps, roots) }) }), { alternateScreen: true, exitOnCtrlC: true });
+        renderApp: (roots, theme, options) => {
+            render(_jsx(ThemeProvider, { theme: theme, children: _jsx(App, { roots: roots, version: readOwnVersion(), loadToday: () => loadDashboard(roots, realDeps), loadTasks: (options) => loadTasks(roots, options), catalog: catalogScreenDeps(realDeps), sync: syncScreenDeps(realDeps, roots), dashboardActions: dashboardActionsDeps(realDeps, roots), wizard: { facts: gatherWizardFacts(realDeps), actions: buildWizardActions(realDeps) }, startInWizard: options?.startInWizard }) }), { alternateScreen: true, exitOnCtrlC: true });
         },
     };
     void runCli(process.argv.slice(2), realDeps);

package/dist/domain/setup-wizard.js

@@ -0,0 +1,245 @@
+/**
+ * Pure domain for `kankaku setup`'s interactive wizard: one `WizardState`
+ * carrying the current step, the user's in-progress answers, the computed
+ * plan and the applied results, plus reducers that transition it. No I/O —
+ * callers (`src/ui/setup/*`, `src/cli.tsx`) read the real files and pass
+ * plain facts in via `WizardFacts`, exactly like `domain/setup-plan.ts`.
+ */
+import { detectAgents } from "./setup-plan.js";
+const CLAUDE_STATUS_LINE_RE = /^node "(.+)\/src\/statusline\.ts"$/;
+/** The inverse of `adapters/setup/claude.ts#statusLineCommand`: recovers the checkout path from an existing `statusLine.command`, or `""` when it isn't kankaku's. */
+export function guessClaudeCheckout(statusLineCommand) {
+    if (!statusLineCommand)
+        return "";
+    const match = CLAUDE_STATUS_LINE_RE.exec(statusLineCommand);
+    return match ? match[1] : "";
+}
+/**
+ * Shorten `path` for display by replacing a leading `homeDir` with `~`.
+ * Only a real path-boundary match counts (`homeDir` itself, or `homeDir`
+ * followed by `/`) — a sibling directory that merely shares the prefix
+ * (e.g. `/homework` vs `/home`) is left unchanged. `path` is returned as-is
+ * when it doesn't start under `homeDir`.
+ */
+export function shortenHome(path, homeDir) {
+    if (homeDir === "")
+        return path;
+    if (path === homeDir)
+        return "~";
+    if (path.startsWith(`${homeDir}/`))
+        return `~${path.slice(homeDir.length)}`;
+    return path;
+}
+function clearError(errors, key) {
+    if (!(key in errors))
+        return errors;
+    const rest = { ...errors };
+    delete rest[key];
+    return rest;
+}
+const HUB_ERROR_KEYS = ["url", "email", "password", "localCheckout"];
+function clearHubErrors(errors) {
+    return HUB_ERROR_KEYS.reduce((acc, key) => clearError(acc, key), errors);
+}
+/** Build the wizard's initial state from plain, already-read facts: agent detection, current hub credentials and current `tui.json` roots. */
+export function createWizardState(facts) {
+    const agents = detectAgents(facts.agentFacts);
+    const selected = Object.fromEntries(agents.map((agent) => [agent.id, agent.configured]));
+    return {
+        step: "agents",
+        agents,
+        selected,
+        claudeCheckout: guessClaudeCheckout(facts.agentFacts.claudeCode?.statusLineCommand),
+        hub: {
+            mode: facts.hub.credentialsPresent ? "existing" : "skip",
+            url: facts.hub.url ?? "",
+            email: facts.hub.email ?? "",
+            password: facts.hub.password ?? "",
+            localCheckout: facts.hub.localCheckoutGuess,
+            localManual: false,
+        },
+        roots: facts.roots.current ?? facts.roots.defaultRoots,
+        errors: {},
+        plan: [],
+        results: [],
+    };
+}
+/** Whether the Claude Code step should be shown: Claude is selected and not already configured. Exported so `ui/setup/wizard-screen.tsx` can number only the steps that will actually be shown for this run. */
+export function claudeStepNeeded(state) {
+    const claude = state.agents.find((agent) => agent.id === "claude-code");
+    return state.selected["claude-code"] === true && claude !== undefined && !claude.configured;
+}
+export function toggleAgent(state, id) {
+    if (id === "codex" || id === "opencode")
+        return state;
+    return { ...state, selected: { ...state.selected, [id]: !state.selected[id] } };
+}
+export function setClaudeCheckout(state, value) {
+    return { ...state, claudeCheckout: value, errors: clearError(state.errors, "claudeCheckout") };
+}
+export function setHubMode(state, mode) {
+    return { ...state, hub: { ...state.hub, mode }, errors: clearHubErrors(state.errors) };
+}
+export function setHubField(state, field, value) {
+    return { ...state, hub: { ...state.hub, [field]: value }, errors: clearError(state.errors, field) };
+}
+export function setHubHealth(state, ok) {
+    return { ...state, hub: { ...state.hub, healthOk: ok } };
+}
+/** Parses a comma-separated list of roots: trims each entry and drops empties. */
+export function setRoots(state, text) {
+    const roots = text
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return { ...state, roots, errors: clearError(state.errors, "roots") };
+}
+export function setLocalCheckout(state, value) {
+    return { ...state, hub: { ...state.hub, localCheckout: value }, errors: clearError(state.errors, "localCheckout") };
+}
+export function setHubLocalManual(state, manual) {
+    return { ...state, hub: { ...state.hub, localManual: manual }, errors: clearError(state.errors, "localCheckout") };
+}
+function validateHub(hub) {
+    if (hub.mode === "existing") {
+        const errors = {};
+        if (!/^https?:\/\//.test(hub.url))
+            errors.url = "enter a http(s) URL";
+        if (!hub.email.includes("@"))
+            errors.email = "enter a valid email";
+        if (hub.password.trim() === "")
+            errors.password = "enter a password";
+        return errors;
+    }
+    if (hub.mode === "local") {
+        if (hub.localCheckout.trim() === "" && !hub.localManual) {
+            return { localCheckout: "enter a checkout path, or acknowledge installing manually" };
+        }
+        return {};
+    }
+    return {};
+}
+function arraysEqual(a, b) {
+    return a.length === b.length && a.every((entry, index) => entry === b[index]);
+}
+const PI_HOME_AGENTS = [
+    { id: "pi", title: "pi" },
+    { id: "gentle-shell", title: "gentle-shell" },
+];
+/** Build the ordered plan from the current wizard answers, diffed against `facts`' current on-disk state. */
+export function planFromWizard(state, facts) {
+    const actions = [];
+    for (const { id, title } of PI_HOME_AGENTS) {
+        const agent = state.agents.find((candidate) => candidate.id === id);
+        if (!agent || !agent.adapterAvailable)
+            continue;
+        const selected = state.selected[id] === true;
+        if (selected === agent.configured)
+            continue;
+        actions.push(selected
+            ? { kind: "install-pi", file: agent.detail, label: `install kankaku in ${title} (${agent.detail})` }
+            : { kind: "remove-pi", file: agent.detail, label: `remove kankaku from ${title} (${agent.detail})` });
+    }
+    const claude = state.agents.find((agent) => agent.id === "claude-code");
+    if (claude && claude.adapterAvailable) {
+        const selected = state.selected["claude-code"] === true;
+        if (selected !== claude.configured) {
+            actions.push(selected
+                ? { kind: "write-claude", file: claude.detail, label: `set the Claude Code status line (${claude.detail})` }
+                : { kind: "remove-claude", file: claude.detail, label: `remove the kankaku status line from Claude Code (${claude.detail})` });
+        }
+    }
+    if (state.hub.mode === "existing") {
+        const changed = !facts.hub.credentialsPresent ||
+            state.hub.url !== (facts.hub.url ?? "") ||
+            state.hub.email !== (facts.hub.email ?? "") ||
+            state.hub.password !== (facts.hub.password ?? "");
+        if (changed) {
+            actions.push({ kind: "write-hub", file: facts.hub.credentialsPath, label: `write hub credentials to ${facts.hub.credentialsPath}` });
+        }
+    }
+    else if (state.hub.mode === "local" && state.hub.localCheckout.trim() !== "") {
+        actions.push({ kind: "install-local-hub", file: state.hub.localCheckout, label: `install a local hub from ${state.hub.localCheckout}` });
+    }
+    const sameRoots = facts.roots.current !== undefined && arraysEqual(facts.roots.current, state.roots);
+    if (!sameRoots) {
+        actions.push({ kind: "write-roots", file: facts.roots.path, label: `write roots to ${facts.roots.path}` });
+    }
+    return actions;
+}
+/** Advance from the current step: validates it, sets `errors` and stays when invalid, otherwise moves on. */
+export function next(state, facts) {
+    switch (state.step) {
+        case "agents":
+            return { ...state, step: claudeStepNeeded(state) ? "claude" : "hub", errors: {} };
+        case "claude": {
+            if (state.claudeCheckout.trim() === "") {
+                return { ...state, errors: { ...state.errors, claudeCheckout: "enter the kankaku-claude checkout path" } };
+            }
+            return { ...state, step: "hub", errors: clearError(state.errors, "claudeCheckout") };
+        }
+        case "hub": {
+            const hubErrors = validateHub(state.hub);
+            if (Object.keys(hubErrors).length > 0) {
+                return { ...state, errors: { ...clearHubErrors(state.errors), ...hubErrors } };
+            }
+            return { ...state, step: "roots", errors: clearHubErrors(state.errors) };
+        }
+        case "roots": {
+            if (state.roots.length === 0) {
+                return { ...state, errors: { ...state.errors, roots: "enter at least one root directory" } };
+            }
+            const reviewState = { ...state, step: "review", errors: clearError(state.errors, "roots") };
+            return { ...reviewState, plan: planFromWizard(reviewState, facts) };
+        }
+        case "review":
+            return { ...state, step: "apply" };
+        case "apply":
+            return state.results.length >= state.plan.length ? { ...state, step: "done" } : state;
+        case "done":
+            return state;
+    }
+}
+/** Move back to the previous step, mirroring `next`'s claude-step skip. Terminal/first steps (`agents`, `apply`, `done`) are no-ops. */
+export function back(state) {
+    switch (state.step) {
+        case "agents":
+            return state;
+        case "claude":
+            return { ...state, step: "agents", errors: {} };
+        case "hub":
+            return { ...state, step: claudeStepNeeded(state) ? "claude" : "agents", errors: {} };
+        case "roots":
+            return { ...state, step: "hub", errors: {} };
+        case "review":
+            return { ...state, step: "roots", errors: {} };
+        case "apply":
+            return state;
+        case "done":
+            return state;
+    }
+}
+export function applyResult(state, result) {
+    return { ...state, results: [...state.results, result] };
+}
+/** The footer key hints for a given step. */
+export function hintsForStep(step) {
+    const quit = { key: "q", label: "quit" };
+    switch (step) {
+        case "agents":
+            // The first step: esc quits (handled by the caller), so it isn't hinted as "back" here.
+            return [{ key: "space", label: "toggle" }, { key: "↑↓", label: "move" }, { key: "enter", label: "next" }, quit];
+        case "claude":
+            return [{ key: "enter", label: "next" }, { key: "esc", label: "back" }, quit];
+        case "hub":
+            return [{ key: "↑↓", label: "choose" }, { key: "enter", label: "next" }, { key: "esc", label: "back" }, quit];
+        case "roots":
+            return [{ key: "enter", label: "next" }, { key: "esc", label: "back" }, quit];
+        case "review":
+            return [{ key: "enter", label: "apply" }, { key: "esc", label: "back" }, quit];
+        case "apply":
+            return [quit];
+        case "done":
+            return [{ key: "enter", label: "open dashboard" }, quit];
+    }
+}

package/dist/ports/script-runner.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/app.js

@@ -6,6 +6,7 @@ import { DashboardScreen } from "./dashboard-screen.js";
 import { TasksScreen } from "./tasks-screen.js";
 import { CatalogScreen } from "./catalog-screen.js";
 import { SyncScreen } from "./sync-screen.js";
+import { SetupWizard } from "./setup/wizard-screen.js";
 /**
  * The app shell: owns navigation state (`domain/nav-model.ts`) and renders
  * whichever screen is active, each already wrapped in the shared
@@ -24,9 +25,10 @@ import { SyncScreen } from "./sync-screen.js";
  * filter — this hook only predicts whether that will happen, to decide
  * whether it should also move focus.
  */
-export function App({ roots, version, loadToday, loadTasks, catalog, sync, dashboardActions }) {
+export function App({ roots, version, loadToday, loadTasks, catalog, sync, dashboardActions, wizard, startInWizard }) {
     const { exit } = useApp();
     const [nav, setNav] = useState(INITIAL_NAV_STATE);
+    const [showWizard, setShowWizard] = useState(startInWizard === true && wizard !== undefined);
     useInput((input, key) => {
         if (input === "q") {
             exit();
@@ -59,7 +61,14 @@ export function App({ roots, version, loadToday, loadTasks, catalog, sync, dashb
             }
             return state;
         });
-    });
+    }, 
+    // While the wizard is active, it owns every keystroke itself (including
+    // `q`, gated there by whether a text field currently has focus) — this
+    // app-wide handler must stay out of the way entirely.
+    { isActive: !showWizard });
     const focused = nav.focus === "main";
+    if (showWizard && wizard) {
+        return _jsx(SetupWizard, { facts: wizard.facts, actions: wizard.actions, onDone: () => setShowWizard(false), onQuit: () => exit(), version: version });
+    }
     return (_jsxs(_Fragment, { children: [nav.screen === "dashboard" && (_jsx(DashboardScreen, { load: loadToday, actions: dashboardActions, roots: roots, version: version, focused: focused, onOpenProject: (project) => setNav((state) => openProjectInTasks(state, project)) })), nav.screen === "tasks" && (_jsx(TasksScreen, { load: loadTasks, roots: roots, version: version, focused: focused, ...(nav.projectFilter !== undefined ? { projectFilter: nav.projectFilter } : {}), onClearFilter: () => setNav((state) => clearProjectFilter(state)) })), nav.screen === "catalog" && _jsx(CatalogScreen, { ...catalog, roots: roots, version: version, focused: focused }), nav.screen === "sync" && _jsx(SyncScreen, { ...sync, roots: roots, version: version, focused: focused })] }));
 }

package/dist/ui/components/checklist.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+import { useTheme } from "../theme.js";
+/**
+ * A checkbox list: `[x] label` checked, `[ ] label` unchecked, `[-] label
+ * (note)` disabled. Space toggles the item at `cursor` (a no-op when
+ * disabled); ↑/↓ call `onMove(-1|1)` — clamping is the caller's job, same
+ * as `Table`'s `selectedIndex`. The cursor row gets a visible `› ` marker,
+ * never colour alone.
+ */
+export function Checklist({ items, cursor, onToggle, onMove, focused }) {
+    const theme = useTheme();
+    useInput((input, key) => {
+        if (key.upArrow) {
+            onMove(-1);
+            return;
+        }
+        if (key.downArrow) {
+            onMove(1);
+            return;
+        }
+        if (input === " ") {
+            const item = items[cursor];
+            if (item && !item.disabled)
+                onToggle(item.id);
+        }
+    }, { isActive: focused });
+    return (_jsx(Box, { flexDirection: "column", children: items.map((item, index) => {
+            const marker = item.disabled ? "[-]" : item.checked ? "[x]" : "[ ]";
+            const note = item.disabled && item.note ? ` (${item.note})` : "";
+            const cursorMark = index === cursor ? "› " : "  ";
+            return (_jsx(Text, { color: item.disabled ? theme.dim : theme.text, children: `${cursorMark}${marker} ${item.label}${note}` }, item.id));
+        }) }));
+}

package/dist/ui/components/radio.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+import { useTheme } from "../theme.js";
+/**
+ * A single-select radio list: `(•) label` for the selected option, `( )
+ * label` otherwise. ↑/↓ select the previous/next option directly (clamped
+ * at the ends). The currently highlighted row also gets a visible `› `
+ * marker, matching `Checklist`'s and `Table`'s own convention.
+ */
+export function Radio({ options, value, onChange, focused }) {
+    const theme = useTheme();
+    const index = options.findIndex((option) => option.value === value);
+    useInput((_input, key) => {
+        if (key.upArrow) {
+            const targetIndex = Math.max(index - 1, 0);
+            const previous = options[targetIndex];
+            if (previous && targetIndex !== index)
+                onChange(previous.value);
+            return;
+        }
+        if (key.downArrow) {
+            const targetIndex = Math.min(index + 1, options.length - 1);
+            const next = options[targetIndex];
+            if (next && targetIndex !== index)
+                onChange(next.value);
+        }
+    }, { isActive: focused });
+    return (_jsx(Box, { flexDirection: "column", children: options.map((option, i) => (_jsx(Text, { color: theme.text, children: `${i === index ? "› " : "  "}${option.value === value ? "(•)" : "( )"} ${option.label}` }, option.value))) }));
+}

package/dist/ui/components/text-input.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Text, useInput } from "ink";
+import { useTheme } from "../theme.js";
+/**
+ * A single-line, fully controlled text input: printable characters insert
+ * at the cursor, Backspace/Delete remove the character before/after it,
+ * ←/→ and Home/End move it, Enter calls `onSubmit`. Only active while
+ * `focused` (`useInput`'s own `isActive`, matching every other kankaku-tui
+ * component). The cursor is a visible `▏` marker, shown only while
+ * focused — never colour alone (see AGENTS.md's ink-testing-library note).
+ */
+export function TextInput({ value, onChange, onSubmit, placeholder = "", masked = false, focused }) {
+    const theme = useTheme();
+    const [cursor, setCursor] = useState(value.length);
+    const position = Math.min(Math.max(cursor, 0), value.length);
+    useInput((input, key) => {
+        if (key.return) {
+            onSubmit?.(value);
+            return;
+        }
+        if (key.leftArrow) {
+            setCursor(Math.max(position - 1, 0));
+            return;
+        }
+        if (key.rightArrow) {
+            setCursor(Math.min(position + 1, value.length));
+            return;
+        }
+        if (key.home) {
+            setCursor(0);
+            return;
+        }
+        if (key.end) {
+            setCursor(value.length);
+            return;
+        }
+        if (key.backspace) {
+            if (position === 0)
+                return;
+            onChange(value.slice(0, position - 1) + value.slice(position));
+            setCursor(position - 1);
+            return;
+        }
+        if (key.delete) {
+            if (position >= value.length)
+                return;
+            onChange(value.slice(0, position) + value.slice(position + 1));
+            return;
+        }
+        if (key.upArrow || key.downArrow || key.pageUp || key.pageDown || key.tab || key.escape || key.ctrl || key.meta)
+            return;
+        if (!input)
+            return;
+        onChange(value.slice(0, position) + input + value.slice(position));
+        setCursor(position + input.length);
+    }, { isActive: focused });
+    const cursorMark = focused ? "▏" : "";
+    if (value.length === 0) {
+        return (_jsxs(Text, { children: [cursorMark, _jsx(Text, { color: theme.dim, children: placeholder })] }));
+    }
+    const displayed = masked ? "•".repeat(value.length) : value;
+    return (_jsxs(Text, { children: [displayed.slice(0, position), cursorMark, displayed.slice(position)] }));
+}

package/dist/ui/setup/wizard-screen.js

@@ -0,0 +1,195 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Box, Text, useInput, useStdout } from "ink";
+import { applyResult, back, claudeStepNeeded, createWizardState, hintsForStep, next, planFromWizard, setClaudeCheckout, setHubField, setHubHealth, setHubLocalManual, setHubMode, setLocalCheckout, setRoots, shortenHome, toggleAgent, } from "../../domain/setup-wizard.js";
+import { HeaderBar } from "../components/header-bar.js";
+import { KeyHints } from "../components/key-hints.js";
+import { Panel } from "../components/panel.js";
+import { Table } from "../components/table.js";
+import { Checklist } from "../components/checklist.js";
+import { Radio } from "../components/radio.js";
+import { TextInput } from "../components/text-input.js";
+import { useTheme } from "../theme.js";
+/** Fallback terminal height when neither `rows` nor `useStdout().rows` is available (matches `ui/layout.tsx`'s own fallback). */
+const DEFAULT_ROWS = 24;
+/** Rows used by the header line. */
+const HEADER_ROWS = 1;
+/** Rows used by the footer key-hints line. */
+const FOOTER_ROWS = 1;
+/** Panel titles for every step. Used verbatim for `apply`/`done` (never numbered); `agents`/`claude`/`hub`/`roots`/`review` get a `n/total` suffix from {@link panelTitle}. */
+const STEP_TITLES = {
+    agents: "Agents",
+    claude: "Claude Code",
+    hub: "Hub",
+    roots: "Roots",
+    review: "Review",
+    apply: "Apply",
+    done: "Done",
+};
+/** The steps a run numbers in its panel title, in order; `claude` is dropped from this list when the run doesn't need it (see {@link numberedStepsForRun}). `apply` and `done` are never numbered — `apply` is Review's own execution and `done` is the terminal summary. */
+const NUMBERED_STEPS = ["agents", "claude", "hub", "roots", "review"];
+/** The steps that will actually be shown for this run, e.g. `["agents", "hub", "roots", "review"]` when Claude Code is skipped. */
+function numberedStepsForRun(state) {
+    return NUMBERED_STEPS.filter((step) => step !== "claude" || claudeStepNeeded(state));
+}
+/** `[ Setup · Agents 1/5 ]`-style progress title: `n/total` over only the steps this run will show; `apply`/`done` render unnumbered. */
+function panelTitle(state) {
+    const title = STEP_TITLES[state.step];
+    const steps = numberedStepsForRun(state);
+    const index = steps.indexOf(state.step);
+    return index === -1 ? `Setup · ${title}` : `Setup · ${title} ${index + 1}/${steps.length}`;
+}
+const AGENT_TITLES = {
+    pi: "pi",
+    "gentle-shell": "gentle-shell",
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    opencode: "OpenCode",
+};
+/** The Agents checklist row's note: presence/configured state for pi/gentle-shell/Claude Code (always checkable), or why an agent with no adapter yet (Codex/OpenCode, always disabled) can't be. */
+function agentNote(agent, homeDir) {
+    if (!agent.adapterAvailable)
+        return agent.present ? "no adapter yet" : "not installed";
+    return agent.configured ? `configured (${shortenHome(agent.detail, homeDir)})` : "not configured";
+}
+const REVIEW_FIXED_COLUMNS_WIDTH = 30 + 1 + 2 + 2;
+function reviewColumns(panelWidth) {
+    const labelWidth = Math.max(panelWidth - REVIEW_FIXED_COLUMNS_WIDTH, 20);
+    return [
+        { key: "label", header: "action", width: labelWidth },
+        { key: "file", header: "file", width: 30 },
+    ];
+}
+function reviewCell(row, key) {
+    return key === "file" ? row.file : row.label;
+}
+function applyResultLine(result) {
+    if (result.outcome === "error")
+        return `error: ${result.detail ?? result.action.label}`;
+    const detail = result.detail ? ` (${result.detail})` : "";
+    return `${result.outcome} ${result.action.file}${detail}`;
+}
+/**
+ * Detection is folded into the Agents checklist itself (R1): each row's
+ * label already carries the agent's presence/configured state, e.g.
+ * `pi — configured (~/.pi/agent/settings.json)` or `gentle-shell — not
+ * configured`; disabled rows (no adapter yet) read `Codex — no adapter
+ * yet` or `OpenCode — not installed`. `note` is left unset so `Checklist`
+ * never appends its own `(note)` suffix on top.
+ */
+function agentChecklistItems(agents, selected, homeDir) {
+    return agents.map((agent) => ({
+        id: agent.id,
+        label: `${AGENT_TITLES[agent.id]} — ${agentNote(agent, homeDir)}`,
+        checked: selected[agent.id] === true,
+        disabled: !agent.adapterAvailable,
+    }));
+}
+const HUB_MODE_OPTIONS = [
+    { value: "existing", label: "use an existing hub" },
+    { value: "local", label: "install locally" },
+    { value: "skip", label: "skip" },
+];
+/** Mirrors `adapters/setup/local-hub.ts`'s own `HUB_URL`: where a manually-started local hub is expected to answer. */
+const LOCAL_HUB_URL = "http://127.0.0.1:8090";
+function healthLine(healthOk, checking) {
+    if (checking)
+        return "checking…";
+    if (healthOk === undefined)
+        return "";
+    return healthOk ? "health ok" : "health failed";
+}
+/**
+ * `kankaku setup`'s interactive wizard: one full-screen step at a time,
+ * driven by `domain/setup-wizard.ts`'s pure reducers. Unlike every other
+ * screen it renders its own header/panel/footer frame directly instead of
+ * `ui/layout.tsx`'s `Layout` — there is no sidebar to show, since the
+ * wizard's progress lives in the panel's own title instead (`panelTitle`,
+ * e.g. `Setup · Agents 1/5`, numbering only the steps this run will
+ * actually show — Claude Code is dropped when it isn't needed). Enter
+ * advances (validating first), Esc goes back (quits from Agents, the
+ * first step, via `onQuit`); `q` quits from anywhere a text field isn't
+ * currently capturing keystrokes.
+ */
+export function SetupWizard({ facts, actions, onDone, onQuit, version, columns, rows }) {
+    const theme = useTheme();
+    const [state, setState] = useState(() => createWizardState(facts));
+    const [agentCursor, setAgentCursor] = useState(0);
+    const [hubFocus, setHubFocus] = useState(0);
+    const [healthChecking, setHealthChecking] = useState(false);
+    const [rootsText, setRootsText] = useState(() => state.roots.join(", "));
+    const applyStartedRef = useRef(false);
+    useEffect(() => {
+        if (state.step === "hub")
+            setHubFocus(0);
+    }, [state.step]);
+    const foundCheckout = state.hub.mode === "local" ? actions.findHubCheckout() : undefined;
+    const hasCheckoutField = state.hub.mode === "local" && (state.hub.localCheckout.trim() !== "" || foundCheckout !== undefined);
+    const checkoutValue = state.hub.localCheckout.trim() !== "" ? state.hub.localCheckout : (foundCheckout ?? "");
+    const hubFieldCount = state.hub.mode === "existing" ? 4 : state.hub.mode === "local" && hasCheckoutField ? 2 : 1;
+    const textInputFocused = state.step === "claude" || state.step === "roots" || (state.step === "hub" && hubFocus >= 1 && hubFocus < hubFieldCount);
+    useEffect(() => {
+        if (state.step !== "apply" || applyStartedRef.current)
+            return;
+        applyStartedRef.current = true;
+        const snapshot = state;
+        void (async () => {
+            for (const action of snapshot.plan) {
+                const result = await actions.apply(action, snapshot);
+                setState((s) => applyResult(s, result));
+            }
+        })();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [state.step]);
+    useInput((input, key) => {
+        if (key.tab && state.step === "hub") {
+            setHubFocus((current) => (current + 1) % hubFieldCount);
+            return;
+        }
+        if (key.return) {
+            if (state.step === "done") {
+                onDone();
+                return;
+            }
+            setState((s) => next(s, facts));
+            return;
+        }
+        if (key.escape) {
+            if (state.step === "agents") {
+                onQuit();
+                return;
+            }
+            setState((s) => back(s));
+            return;
+        }
+        if (!textInputFocused && input === "q") {
+            onQuit();
+            return;
+        }
+        if (state.step === "hub" && !textInputFocused) {
+            if (input === "c") {
+                const url = state.hub.mode === "existing" ? state.hub.url : LOCAL_HUB_URL;
+                setHealthChecking(true);
+                void actions.checkHealth(url).then((ok) => {
+                    setState((s) => setHubHealth(s, ok));
+                    setHealthChecking(false);
+                });
+                return;
+            }
+            if (input === "m" && state.hub.mode === "local" && !hasCheckoutField) {
+                setState((s) => setHubLocalManual(s, true));
+                return;
+            }
+        }
+    });
+    const hints = hintsForStep(state.step);
+    const { stdout } = useStdout();
+    const width = columns ?? stdout?.columns ?? 80;
+    const height = rows ?? stdout?.rows ?? DEFAULT_ROWS;
+    const mainWidth = width;
+    const mainHeight = Math.max(height - HEADER_ROWS - FOOTER_ROWS, 0);
+    return (_jsxs(Box, { flexDirection: "column", width: width, height: height, children: [_jsx(HeaderBar, { left: `>_ kankaku setup${version ? ` ${version}` : ""}`, width: width }), _jsx(Box, { flexDirection: "column", flexGrow: 1, minHeight: 0, children: _jsxs(Panel, { title: panelTitle(state), width: mainWidth, height: mainHeight, active: true, children: [state.step === "agents" && (_jsx(Checklist, { items: agentChecklistItems(state.agents, state.selected, facts.homeDir), cursor: agentCursor, onToggle: (id) => setState((s) => toggleAgent(s, id)), onMove: (delta) => setAgentCursor((c) => Math.min(Math.max(c + delta, 0), state.agents.length - 1)), focused: true })), state.step === "claude" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "kankaku-claude checkout path:" }), _jsx(TextInput, { value: state.claudeCheckout, onChange: (value) => setState((s) => setClaudeCheckout(s, value)), focused: true }), state.errors.claudeCheckout && _jsx(Text, { color: theme.error, children: state.errors.claudeCheckout })] })), state.step === "hub" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Radio, { options: HUB_MODE_OPTIONS, value: state.hub.mode, onChange: (mode) => setState((s) => setHubMode(s, mode)), focused: hubFocus === 0 }), state.hub.mode === "existing" && (_jsxs(Box, { flexDirection: "column", children: [["url", "email", "password"].map((field, index) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: `${field}: ` }), _jsx(TextInput, { value: state.hub[field], onChange: (value) => setState((s) => setHubField(s, field, value)), masked: field === "password", focused: hubFocus === index + 1 })] }, field))), state.errors.url && _jsx(Text, { color: theme.error, children: state.errors.url }), state.errors.email && _jsx(Text, { color: theme.error, children: state.errors.email }), state.errors.password && _jsx(Text, { color: theme.error, children: state.errors.password }), _jsx(Text, { children: `[ check ] c   ${healthLine(state.hub.healthOk, healthChecking)}` })] })), state.hub.mode === "local" && hasCheckoutField && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "local checkout path:" }), _jsx(TextInput, { value: checkoutValue, onChange: (value) => setState((s) => setLocalCheckout(s, value)), focused: hubFocus === 1 })] })), state.hub.mode === "local" && !hasCheckoutField && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "no kankaku-hub checkout found; run these commands, then check again:" }), actions.manualCommands(state.hub.localCheckout || undefined).map((line) => (_jsx(Text, { children: `  ${line}` }, line))), _jsx(Text, { children: `[ check again ] c   ${healthLine(state.hub.healthOk, healthChecking)}` }), _jsx(Text, { children: `[ m ] acknowledge manual install${state.hub.localManual ? " (acknowledged)" : ""}` }), state.errors.localCheckout && _jsx(Text, { color: theme.error, children: state.errors.localCheckout })] }))] })), state.step === "roots" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "project roots (comma-separated):" }), _jsx(TextInput, { value: rootsText, onChange: (value) => {
+                                        setRootsText(value);
+                                        setState((s) => setRoots(s, value));
+                                    }, focused: true }), state.errors.roots && _jsx(Text, { color: theme.error, children: state.errors.roots })] })), state.step === "review" && (_jsx(Table, { columns: reviewColumns(mainWidth), rows: state.plan, rowKey: (row) => `${row.kind}-${row.file}`, cell: reviewCell, emptyText: "nothing to change" })), state.step === "apply" && (_jsxs(Box, { flexDirection: "column", children: [state.results.map((result, index) => (_jsx(Text, { children: applyResultLine(result) }, `${result.action.kind}-${index}`))), state.results.length < state.plan.length && _jsx(Text, { dimColor: true, children: "applying\u2026" })] })), state.step === "done" && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: `setup complete: ${state.results.length} change(s) applied` }), _jsx(Text, { dimColor: true, children: "enter open dashboard" })] }))] }) }), _jsx(KeyHints, { hints: hints })] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-tui",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Terminal app that shows today's kankaku work across every project on disk",
   "license": "MIT",
   "type": "module",