kaizen-agent 1.47.0 → 1.49.0

package/README.md

@@ -1,78 +1,118 @@
-<div align="center">
-<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/banner.png" alt="kaizen" width="760">
-</div>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/readme/banner.png" alt="kaizen: build what you have in mind. Apps, documents, videos and games, with your AI agent" width="100%">
+</p>
 
-<p align="center"><b>One tool to build and maintain your product with AI agents.</b><br>Requests in, a plan you approve, the work, an independent review, done.</p>
+<p align="center">
+  <b>Build what you have in mind: an app, a document, a video, a game.</b><br>
+  Your AI agent plans it, you approve, it builds, and a reviewer that never saw the work checks it.
+</p>
 
-<p align="center"><img src="assets/hero.gif" alt="Animated walkthrough of the real kaizen board with sample data. 1: a request gathered from a support sheet waits in the Icebox and is promoted. 2: it is an idea on the board, and Run opens Claude Code. 3: the agent works in the card's own terminal and writes a plan. 4: the plan panel shows what done and wrong mean, and it is approved. 5: it builds, then a reviewer that never saw the work reports a high finding, a double charge. 6: only that finding is ticked and fixed. 7: the reviewer re-checks it. 8: the run lands in Done, with the low finding left in the backlog." width="760"></p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/kaizen-agent"><img alt="npm" src="https://img.shields.io/npm/v/kaizen-agent?style=for-the-badge&color=000&labelColor=1c1c1e&logo=npm"></a>
+  <a href="https://github.com/hfadhlullah/kaizen/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/hfadhlullah/kaizen?style=for-the-badge&logo=github&color=000&labelColor=1c1c1e"></a>
+  <img alt="Bun 1.1+" src="https://img.shields.io/badge/Bun-1.1%2B-000?style=for-the-badge&logo=bun&logoColor=white">
+  <img alt="macOS · Linux · Windows beta" src="https://img.shields.io/badge/macOS_·_Linux_·_Windows_beta-000?style=for-the-badge">
+  <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/license-MIT-000?style=for-the-badge"></a>
+</p>
 
-## The problem
-
-You ask an AI coding agent to retry a payment webhook when the bank times out. It starts editing at once, then says *"Done, tests pass."* The tests do pass. They were written by the same agent, from the same assumption: that a timeout means the charge failed. Sometimes the bank said yes and the reply got lost. Now a retry charges the customer twice, and nothing in the agent's report would make you look.
+> **kaizen runs inside an AI agent; it is not one.** The agent does the work; kaizen gives it a plan, an approval stop and an independent review. It works with Claude Code, Codex, Antigravity and Gemini CLI, and the installer offers to set one up if you have none. A run costs several times a single prompt, so it is meant for work where being wrong is expensive. Windows support is in beta.
 
-None of this is a lack of intelligence. It is a missing workflow:
+<br>
 
-| What goes wrong | What kaizen does |
-| :--- | :--- |
-| The agent decides what "done" means on its own, and you find out from the diff | It writes a plan first, including what *wrong* would look like, and waits for your approve or change |
-| The author grades its own work, so its blind spot is in the code *and* in the check | A second agent that never saw the work reviews it, from the request, the plan and the diff only |
-| Findings get fixed in an endless loop, or silently dropped | Serious findings are fixed and re-checked, at most twice; the rest come to you, and what is left goes to a backlog |
-| Requests live in sheets, docs and social posts; the plan in one chat, the review in another, the commit somewhere else | One board, from an icebox that gathers those requests to an idea, a plan, the build, the review, the fix loop and the commit, every step on file |
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/readme/what-kaizen-does.png" alt="What kaizen does: plan first, a reviewer that starts cold, a fix loop that ends, one board, requests from where they live, a notebook agents read, on your phone, any agent. Built by Husein Fadhlullah" width="100%">
+</p>
 
-Many assistants now ask for approval before they act, and some run a checker on their own draft. The difference here is *who* checks: a reviewer that shares the author's context shares its blind spots. Kaizen's reviewer starts cold, on purpose.
+<details>
+<summary><b>What kaizen does</b>, as text</summary>
 
-Every stage is a file in `.kaizen/runs/<id>/`, so a run can be resumed later, by another session or another tool (Claude Code, Codex, Antigravity), and read back when someone asks why the code is the way it is.
-
-## Who it is for
-
-**Good fit if you:**
+| | |
+|---|---|
+| **Any kind of work** | Each run works out what it is making (code, writing, communication, operations, research) and plans, builds and reviews it in those terms. Videos and decks go through the bundled `kaizen-video` (films from scratch, or editing your own footage) and `kaizen-deck` skills; books go through `kaizen-book` (interview, writing, proofreading, then an e-book reader plus colour and black-and-white print PDFs). |
+| **Plan first** | The agent writes what it will do, and what *wrong* would look like, then waits for your approve or change. |
+| **A reviewer that starts cold** | A second agent reviews from the request, the plan and the diff only. It never saw the work, so it has nothing to defend. |
+| **A fix loop that ends** | Serious findings are fixed and re-checked, at most twice. The rest come to you; what is left goes to a backlog. |
+| **One board** | `kaizen web`: icebox, ideas, plan, build, review, fix, commit and push, in the browser or the terminal. |
+| **Requests from where they live** | Sheets, docs and social posts are gathered into an icebox, grouped, and promoted to ideas when you pick them. |
+| **A notebook agents read first** | An Obsidian-compatible vault under `.kaizen/notes/` that every stage reads before it plans or builds. |
+| **On your phone** | The board installs as a PWA over Tailscale. `kaizen setup` prints the QR code. |
+| **Any agent, any session** | Every stage is a file in `.kaizen/runs/<id>/`, so another session or another tool can pick a run up. |
+
+</details>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/hero.gif" alt="Animated walkthrough of the kaizen board, from a gathered request to a reviewed, fixed run" width="100%">
+</p>
 
-- Build and maintain a product, and want one place for it: requests gathered from where they live, then plan, build, review and commit, without switching tools.
-- Already use an AI coding agent, and have caught it confidently wrong more than once.
-- Change things where a mistake is expensive: money, data, migrations, anything a customer sees.
-- Want to see and steer the plan before code is written, not reverse-engineer it from a diff.
+## The problem
 
-**Not for you if:**
+You ask an AI coding agent to retry a payment webhook when the bank times out. It starts editing at once, then says *"Done, tests pass."* The tests do pass. They were written by the same agent, from the same assumption: that a timeout means the charge failed. Sometimes the bank said yes and the reply got lost. Now a retry charges the customer twice, and nothing in the agent's report would make you look.
 
-- Your changes are typos and one-liners. A run costs several times one prompt; kaizen takes a short path for small work, but it is not free.
-- You want the agent to ship without you. Kaizen is built to stop and ask.
-- You do not use an AI coding agent. Kaizen runs inside one; it is not one.
+None of this is a lack of intelligence. It is a missing workflow. Many assistants now ask before they act, and some check their own draft. The difference is *who* checks: a reviewer that shares the author's context shares its blind spots. Kaizen's reviewer starts cold, on purpose.
 
 ## Install
 
-### macOS and Linux
-
-```bash
-curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bunx kaizen-agent
+1. **Install** on macOS or Linux:
+   ```bash
+   curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bunx kaizen-agent
+   ```
+   On Windows (beta), in PowerShell:
+   ```powershell
+   irm bun.sh/install.ps1 | iex; & "$env:USERPROFILE\.bun\bin\bunx.exe" kaizen-agent
+   ```
+   Already have Bun? `bunx kaizen-agent`.
+2. **Run `kaizen setup`.** It walks you through your project, settings, the board and the phone app.
+3. **Open the board** with `kaizen web`, or type `/kaizen <request>` in your agent.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/board-v2.png" alt="The kaizen board: icebox, ideas, plan, build, review and done columns" width="100%">
+</p>
+
+## Requirements
+
+| | |
+|---|---|
+| Runtime | [Bun](https://bun.sh) 1.1 or newer. The installer above gets it. |
+| Agent | Claude Code, Codex, Antigravity or Gemini CLI. Claude Code gets the full flow with separate subagents; the others run every stage in one session. |
+| Git | Needed for the board's commit and push. Optional otherwise. |
+| OS | macOS, Linux. Windows in beta. |
+| Phone app | [Tailscale](https://tailscale.com/download) on the PC and the phone, same account. |
+
+## How it works
+
+```mermaid
+flowchart LR
+  R[Request] --> P[Plan]
+  P --> A{You approve}
+  A -- change --> P
+  A -- yes --> B[Build]
+  B --> V[Review<br/>cold agent]
+  V -- high findings --> F[Fix] --> V
+  V -- clean --> D[Done]
+  V -. the rest .-> L[Backlog]
 ```
 
-Already have Bun? Run `bunx kaizen-agent`.
-
-kaizen needs an AI coding agent such as [Claude Code](https://docs.claude.com/en/docs/claude-code). If none is installed, the installer lets you pick one, runs its official installer after you say yes, and then carries on. Git is needed for the board's commit and push.
-
-### Windows
-
-Windows support is still in beta. In PowerShell:
-
-```powershell
-irm bun.sh/install.ps1 | iex; & "$env:USERPROFILE\.bun\bin\bunx.exe" kaizen-agent
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/readme/architecture.png" alt="From idea to finished work: your idea, plan, build, a review in a separate context, a refine loop, and the finished app, document, video or game" width="100%">
+</p>
 
-Already have Bun? Run `bunx kaizen-agent`. As on macOS and Linux, the installer offers to install an AI coding agent when none is found; Git is only needed for the board's commit and push.
+Each stage is its own agent with a clean context: planner, builder, reviewer. They never share a context window. The main thread owns the run's state in `.kaizen/runs/<id>/state.json`; the plan, the build notes, the review and every fix round are files beside it. Small changes take a short path in one session, so a typo does not cost a payroll change.
 
-## Use the board
+## What kaizen changes on your machine
 
-```bash
-kaizen web
-```
+- Installs itself to `~/kaizen`, and keeps settings and the project list in `~/.kaizen/`.
+- Links its skills, agents and `/kaizen-*` commands into each agent it finds: `~/.claude`, `~/.codex`, `~/.agents`, `~/.gemini`. Re-running is safe.
+- Per project, `kaizen init` writes `.kaizen/` and, in a git repo, a `.gitignore` entry that keeps run state out of commits but keeps the `spec*.md` files and `config.yml`.
+- `kaizen web` serves the board on `127.0.0.1:7420`. After `kaizen setup` it is also reachable from your own Tailscale network, nothing wider; never use `tailscale funnel`.
+- `kaizen uninstall` removes the app and its links, and asks whether to keep your runs and settings (`--purge` deletes them too).
 
-<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/board-v2.png" alt="kaizen board" width="760">
+## Who it is for
 
-The board opens in your browser. The side menu holds the board, notes, the icebox of gathered requests and settings, with a light and dark switch. From there you can start a run, approve or revise its plan, pick which review findings to fix, then commit and push.
+**Good fit if you** build and maintain a product with an AI coding agent, have caught it confidently wrong more than once, and change things where a mistake is expensive: money, data, migrations, anything a customer sees.
 
-Right after installing, `kaizen setup` walks you through your project, settings, this board and the phone app (it prints a QR code to scan).
+**Not for you if** your changes are typos and one-liners, or you want the agent to ship without you. Kaizen is built to stop and ask.
 
-### Phone app
+## Phone app
 
 The board is a PWA: installed from the browser, it opens full screen with the kaizen icon. It needs [Tailscale](https://tailscale.com/download) on this PC and on your phone, both signed in to the same account.
 
@@ -82,32 +122,18 @@ kaizen setup        # guided: starts the board, runs tailscale serve, prints a Q
 
 Scan the QR code with your phone camera, then **Add to Home screen** (iOS: Share menu; Android: browser menu, *Install app*).
 
-By hand: run `kaizen web`, then `tailscale serve --bg 127.0.0.1:7420`, add `<pc>.<tailnet>.ts.net` to `~/.kaizen/web-hosts`, and open `https://<pc>.<tailnet>.ts.net` on the phone. Details in [docs/guide.md](docs/guide.md#from-your-phone-tailscale). Never use `tailscale funnel` — it publishes the board to the internet.
+By hand: run `kaizen web`, then `tailscale serve --bg 127.0.0.1:7420`, add `<pc>.<tailnet>.ts.net` to `~/.kaizen/web-hosts`, and open `https://<pc>.<tailnet>.ts.net` on the phone. Details in [docs/guide.md](docs/guide.md#in-a-browser). Never use `tailscale funnel` — it publishes the board to the internet.
 
 To add a launcher (Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows), run `kaizen web --shortcut` once.
 
 ## Development
 
-TypeScript on [Bun](https://bun.sh) 1.1 or newer, zero runtime dependencies. No build step for the CLI — `cli/*.ts` runs as-is — and the web front end ships prebuilt.
+TypeScript on Bun, zero runtime dependencies. No build step for the CLI.
 
 ```bash
 git clone https://github.com/hfadhlullah/kaizen.git && cd kaizen
-bun install               # dev dependencies only
-bun test                  # the suite; what CI runs
-```
-
-To work on kaizen, install from your checkout so every link points at it:
-
-```bash
-bun run cli/install.ts
-```
-
-Skills, agents and commands are symlinked into every AI agent it finds; re-running is safe. From a checkout the workflow updates on any run, and `kaizen upgrade` leaves your local edits alone — update them with git.
-
-After editing `web/notebook.ts` or `web/notes-lib.ts`, rebuild the committed bundle:
-
-```bash
-bun run build:web         # rewrites web/notebook.js; a test fails if it goes stale
+bun install && bun test
+bun run cli/install.ts    # install from this checkout
 ```
 
 ### Layout
@@ -115,7 +141,7 @@ bun run build:web         # rewrites web/notebook.js; a test fails if it goes st
 | Path | What it is |
 |---|---|
 | `cli/` | The installer and the runtime behind every `kaizen` command: `install.ts` (the CLI), `state.ts` (runs), `web.ts` (board server), `dashboard.ts` (terminal board), `sources.ts`, `settings.ts`, `notes.ts`. Tests beside them. |
-| `skills/` | The workflow as Agent Skills folders: `kaizen/` (`SKILL.md`, the `spec-*.md` stage contracts, `adapters.md`, `config.default.yml`), `kaizen-help/`, `story-deck/`, `story-video/`. |
+| `skills/` | The workflow as Agent Skills folders: `kaizen/` (`SKILL.md`, the `spec-*.md` stage contracts, `adapters.md`, `config.default.yml`), `kaizen-help/`, and `media/` with `kaizen-deck/`, `kaizen-video/`, `kaizen-book/`. |
 | `agents/` | The Claude Code subagents: `kaizen-planner`, `kaizen-builder`, `kaizen-reviewer`. |
 | `commands/` | The `/kaizen-*` slash commands, one file each. |
 | `web/` | The board and notebook front end: `board.html`, `notes.html`, `notebook.ts`. |
@@ -124,20 +150,21 @@ bun run build:web         # rewrites web/notebook.js; a test fails if it goes st
 | `design.md` | Design notes for the repo. |
 | `.kaizen/` | This repo's own runs — kaizen is built with kaizen. Gitignored: a fresh clone gets it on its first run. |
 
-### Kaizen Bot
-
-```bash
-cd bot
-cp .env.example .env      # PROVIDER, MODEL, that provider's key
-bun start                 # http://127.0.0.1:7430 — run `kaizen web` first
-bun test
-bun run build             # the desktop app, into dist/
-```
+Kaizen Bot: [bot/README.md](bot/README.md). Other docs: [docs/README.md](docs/README.md). Pull requests welcome; CI runs `bun test` on Ubuntu and Windows and it must pass. For non-trivial work, dogfood: `/kaizen <change>` in this repo plans, builds and reviews it — [`skills/kaizen/spec.md`](skills/kaizen/spec.md) is the contract the stages follow.
 
-### Contributing
+## What you can make
 
-Pull requests; CI runs `bun test` on Ubuntu and Windows and it must pass. For non-trivial work, dogfood: `/kaizen <change>` in this repo plans, builds and reviews it — [`skills/kaizen/spec.md`](skills/kaizen/spec.md) is the contract the stages follow.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/readme/bento.png" alt="What you can make with kaizen: an app, a document, a video, a game. Plan first, a fresh review, keep refining, keep it together" width="100%">
+</p>
 
 ## License
 
-MIT
+kaizen is licensed under the [MIT License](LICENSE).
+
+<p>
+  <a href="https://github.com/hfadhlullah"><img src="https://github.com/hfadhlullah.png?size=64" width="32" height="32" alt="" align="left"></a>
+  &nbsp;Built by <a href="https://github.com/hfadhlullah"><b>Husein Fadhlullah</b></a>, with kaizen.
+</p>
+
+<sub>kaizen is not affiliated with Anthropic, OpenAI or Google. Claude Code, Codex, Antigravity and Gemini CLI are trademarks of their owners.</sub>

package/cli/build-web.ts

@@ -1,7 +1,7 @@
 // `bun run build:web`: bundles the notebook's script and CodeMirror into
 // web/notebook.js, the in-card terminal and xterm.js into web/term.js (+ its
 // stylesheet, web/term.css), the board's modules (web/board/) into web/board.js and
-// Kaizen Bot's page modules (bot/web/app/) into bot/web/app.js, all committed, so an install or a checkout serves it with no
+// Kaizen Bot's page modules (bot/web/app/) into bot/web/app.js, the Video page's script into web/video.js, all committed, so an install or a checkout serves it with no
 // install step and no network. The first line is a hash of what it was built from;
 // cli/notes.test.ts fails when a committed file no longer matches.
 import { createHash } from "node:crypto";
@@ -10,11 +10,12 @@ import { join, dirname } from "node:path";
 
 const root = dirname(import.meta.dir);
 const modules = (dir: string) => readdirSync(join(root, dir)).filter((f) => f.endsWith(".ts")).sort().map((f) => `${dir}/${f}`);
-const SOURCES = ["web/notebook.ts", "web/notes-lib.ts", "web/term.ts", ...modules("web/board"), ...modules("bot/web/app")];
+const SOURCES = ["web/notebook.ts", "web/notes-lib.ts", "web/term.ts", "web/video.ts", ...modules("web/board"), ...modules("bot/web/app")];
 export const OUT = join(root, "web", "notebook.js");
 export const TERM_OUT = join(root, "web", "term.js");
 export const BOARD_OUT = join(root, "web", "board.js");
 export const BOT_OUT = join(root, "bot", "web", "app.js");
+export const VIDEO_OUT = join(root, "web", "video.js");
 
 // The sources and the exact dependency versions: a CodeMirror bump is a rebuild too.
 export function sourceHash() {
@@ -31,6 +32,7 @@ if (import.meta.main) {
     ["web/term.ts", TERM_OUT, "terminal"],
     ["web/board/main.ts", BOARD_OUT, "board"],
     ["bot/web/app/main.ts", BOT_OUT, "bot page"],
+    ["web/video.ts", VIDEO_OUT, "video page"],
   ] as const;
   for (const [src, out, what] of bundles) {
     // The terminal, the board and the bot page are classic scripts: wrapped, or their

package/cli/hermes.ts

@@ -0,0 +1,65 @@
+// WhatsApp through Hermes (`hermes send`): the chats it knows, and one file with a
+// message to one of them. Always argv, never a shell line: the message is one argument.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export type Chat = { id: string; name: string; type: string };
+type Out = { code: number | string; out: string; err: string };
+
+// On PATH first (tests put a fake there), else where Hermes' installer puts it: a board
+// started from a desktop launcher often has no ~/.local/bin on its PATH.
+function bin() {
+  const p = Bun.which("hermes", { PATH: process.env.PATH ?? "" });
+  if (p) return p;
+  const home = join(process.env.HOME || process.env.USERPROFILE || "", ".local", "bin", "hermes");
+  return existsSync(home) ? home : null;
+}
+
+function run(args: string[], ms: number): Promise<Out> {
+  const exe = bin();
+  if (!exe) return Promise.resolve({ code: "Hermes is not installed (no hermes on PATH or in ~/.local/bin)", out: "", err: "" });
+  return new Promise((done) => {
+    const p = spawn(exe, args, { env: process.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let out = "", err = "";
+    p.stdout!.on("data", (c) => { out += c; });
+    p.stderr!.on("data", (c) => { err += c; });
+    const t = setTimeout(() => { p.kill("SIGKILL"); done({ code: `Hermes did not finish in ${Math.round(ms / 1000)} s`, out, err }); }, ms);
+    p.on("error", (e) => { clearTimeout(t); done({ code: `Hermes could not start: ${e.message}`, out, err }); });
+    p.on("close", (c) => { clearTimeout(t); done({ code: c ?? 1, out, err }); });
+  });
+}
+const lastLine = (s: string) => s.trim().split("\n").filter(Boolean).pop()?.replace(/^hermes send:\s*/, "") ?? "";
+
+export async function targets(): Promise<{ chats: Chat[] } | { error: string }> {
+  const r = await run(["send", "--list", "whatsapp", "--json"], 10_000);
+  if (typeof r.code === "string") return { error: r.code };
+  let j: any;
+  try { j = JSON.parse(r.out); } catch { return { error: lastLine(r.err) || "Hermes gave no chat list" }; }
+  const wa = j?.platforms?.whatsapp;
+  if (!Array.isArray(wa) || !wa.length) return { error: "WhatsApp is not set up in Hermes (hermes gateway setup)" };
+  return { chats: wa.filter((c: any) => typeof c?.id === "string" && c.id).map((c: any) => ({ id: `whatsapp:${c.id}`, name: String(c.name ?? c.id), type: String(c.type ?? "") })) };
+}
+
+// Hermes attaches every MEDIA:<path> it finds in the text, so the user's words may not
+// carry one: that would send a file the page never offered.
+export function message(text: string, file: string): string | { error: string } {
+  if (text.length > 1000) return { error: "the message is over 1,000 characters" };
+  if (/MEDIA:/i.test(text)) return { error: "the message may not contain MEDIA:" };
+  if (/[`\n\r]/.test(file)) return { error: "the file's path cannot be passed to Hermes" };
+  // The path in backticks: Hermes reads a quoted path whole, spaces and all.
+  return `${text.trim()}${text.trim() ? "\n" : ""}MEDIA:\`${file}\``;
+}
+
+// Sent only when Hermes exits 0 with {success: true}; anything else is its own error.
+export async function sendMedia(target: string, text: string, file: string): Promise<{ ok: true } | { ok: false; error: string }> {
+  const m = message(text, file);
+  if (typeof m !== "string") return { ok: false, error: m.error };
+  // "--" so a message starting with "-" is text, not an option.
+  const r = await run(["send", "-t", target, "--json", "--", m], 5 * 60_000);
+  if (typeof r.code === "string") return { ok: false, error: r.code };
+  let j: any = null;
+  try { j = JSON.parse(r.out); } catch { /* not JSON: fall through to stderr */ }
+  if (r.code === 0 && j?.success && !j.error) return { ok: true };
+  return { ok: false, error: String(j?.error ?? (lastLine(r.err) || `Hermes exited ${r.code}`)).slice(0, 400) };
+}

package/cli/install.ts

@@ -2,7 +2,7 @@
 import {
   symlinkSync, mkdirSync, readdirSync, lstatSync, unlinkSync,
   existsSync, copyFileSync, readFileSync, appendFileSync, rmSync, writeFileSync, renameSync,
-  statSync, cpSync, realpathSync, rmdirSync,
+  statSync, cpSync, realpathSync, rmdirSync, readlinkSync,
 } from "node:fs";
 import { join, dirname, basename, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
@@ -46,8 +46,12 @@ const c = {
   green: (s: string) => `\x1b[32m${s}\x1b[0m`,
 };
 
-// Skill folders shipped in skills/ and linked into every agent.
-const SKILLS = ["kaizen", "kaizen-help", "story-deck", "story-video"];
+// Skill folders shipped in skills/ and linked into every agent, by their last
+// path segment: media/kaizen-deck is linked as skills/kaizen-deck.
+const SKILLS = ["kaizen", "kaizen-help", "media/kaizen-deck", "media/kaizen-video", "media/kaizen-book"];
+// Skill names an older release linked; uninstall drops them and install
+// clears them when they are still our links.
+const RENAMED_SKILLS = ["story-deck", "story-video", "kaizen-motion"];
 
 // Where each agent reads skills from. The skill folders follow the open Agent
 // Skills standard, so every one of these can run the workflow; agents/ and
@@ -244,7 +248,9 @@ async function removeEverything() {
 
   for (const root of roots) {
     for (const a of AGENTS) {
-      for (const n of SKILLS) drop(join(root, a.dir, "skills", n));
+      for (const n of SKILLS) drop(join(root, a.dir, "skills", basename(n)));
+      // An old name is only ours while it is still a link; a real folder there is the user's.
+      for (const n of RENAMED_SKILLS) if (isLink(join(root, a.dir, "skills", n))) drop(join(root, a.dir, "skills", n));
       for (const sub of ["agents", "commands"]) {
         const dir = join(root, a.dir, sub);
         try {
@@ -311,6 +317,12 @@ function removeLink(p: string) {
   try { unlinkSync(p); } catch { rmdirSync(p); }
 }
 
+// Setup only wires the board to the phone; it installs nothing, so no agent is needed.
+if (args.has("setup")) {
+  await runSetup();
+  process.exit(0);
+}
+
 // Nothing to install into. kaizen is a workflow an agent runs; on its own it does
 // nothing, so send them to the agent first rather than laying out files no reader
 // will ever load.
@@ -406,11 +418,6 @@ async function openUrl(url: string) {
   try { await Bun.$`${opener} ${url}`.quiet(); return true; } catch { return false; }
 }
 
-if (args.has("setup")) {
-  await runSetup();
-  process.exit(0);
-}
-
 async function runSetup() {
   const s = await import("./setup.ts");
   if (!process.stdin.isTTY) { console.log(s.manual()); return; }
@@ -523,7 +530,7 @@ if (interactive && !upgrade && Bun.argv.length === 2) {
   if (!stale) {
     const here = found(home);
     const linked = here.length > 0 && here.every((a) =>
-      SKILLS.every((n) => existsSync(join(home, a.dir, "skills", n))));
+      SKILLS.every((n) => existsSync(join(home, a.dir, "skills", basename(n)))));
     if (linked) {
       const { dashboard } = await import("./dashboard.ts");
       await dashboard(repoDir, here.map((a) => a.name), async (action) => {
@@ -899,6 +906,13 @@ for (const [src, sub] of links) {
   wrote++;
   if (verbose) console.log(c.dim(`  link  ${name}`));
 }
+if (!check) {
+  for (const a of targets) for (const n of RENAMED_SKILLS) {
+    const p = join(root, a.dir, "skills", n);
+    // Ours only: a dangling link to a folder of that same name, which kaizen has since renamed.
+    if (isLink(p) && !existsSync(p) && basename(readlinkSync(p).replace(/[\\/]+$/, "")) === n) removeLink(p);
+  }
+}
 
 // A project's spec copies are what a run there reads, and they are copied once.
 function specDrift() {

package/cli/localsend.test.ts

@@ -0,0 +1,84 @@
+// LocalSend's sending half against a fake device that speaks protocol v2: what it
+// receives, and what each of its refusals reads as on the page.
+import { test, expect } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes, X509Certificate, createPrivateKey } from "node:crypto";
+import { identity, sendFile, type Device } from "./localsend.ts";
+
+// prepare: what prepare-upload answers (a status, or "hang" to never answer).
+function fakeDevice(prepare: number | "hang") {
+  const got: { prepare?: any; upload?: { query: Record<string, string>; bytes: Buffer } } = {};
+  const srv = Bun.serve({ port: 0, hostname: "127.0.0.1", async fetch(req) {
+    const u = new URL(req.url);
+    if (u.pathname === "/api/localsend/v2/prepare-upload") {
+      got.prepare = await req.json();
+      if (prepare === "hang") { await Bun.sleep(5000); return new Response(null, { status: 500 }); }
+      if (prepare !== 200) return new Response(null, { status: prepare });
+      return Response.json({ sessionId: "s-1", files: { f1: "tok-1" } });
+    }
+    if (u.pathname === "/api/localsend/v2/upload") {
+      const q = Object.fromEntries(u.searchParams);
+      if (q.sessionId !== "s-1" || q.token !== "tok-1" || q.fileId !== "f1") return new Response(null, { status: 403 });
+      got.upload = { query: q, bytes: Buffer.from(await req.arrayBuffer()) };
+      return new Response(null, { status: 200 });
+    }
+    return new Response(null, { status: 404 });
+  } });
+  const dev: Device = { alias: "Pixel 8", deviceModel: "Pixel", deviceType: "mobile", ip: "127.0.0.1", port: srv.port, protocol: "http", fingerprint: "fp" };
+  return { dev, got, stop: () => srv.stop(true) };
+}
+
+function file() {
+  const f = join(mkdtempSync(join(tmpdir(), "kaizen-ls-")), "demo-9x16.mp4");
+  writeFileSync(f, randomBytes(300_000));
+  return f;
+}
+
+test("a send carries the file's bytes with the session and token the device gave", async () => {
+  const d = fakeDevice(200), f = file(), steps: string[] = [];
+  try {
+    expect(await sendFile(d.dev, f, (p) => steps.push(p.phase))).toEqual({ ok: true });
+    expect(d.got.prepare.files.f1).toMatchObject({ id: "f1", fileName: "demo-9x16.mp4", size: 300_000, fileType: "video/mp4" });
+    expect(d.got.prepare.info.alias).toStartWith("kaizen");
+    expect(d.got.upload!.query).toEqual({ sessionId: "s-1", fileId: "f1", token: "tok-1" });
+    expect(d.got.upload!.bytes.equals(await Bun.file(f).bytes().then(Buffer.from))).toBe(true);
+    expect(steps[0]).toBe("waiting");
+    expect(steps.at(-1)).toBe("uploading");
+  } finally { d.stop(); }
+});
+
+test("a refusal, a busy device and no answer each say so, never sent", async () => {
+  const f = file();
+  for (const [status, words] of [[403, "Pixel 8 said no"], [409, "Pixel 8 is busy with another transfer"], [401, "PIN"], [500, "Pixel 8 answered 500"]] as const) {
+    const d = fakeDevice(status);
+    try {
+      const r = await sendFile(d.dev, f);
+      expect(r.ok).toBe(false);
+      expect((r as any).error).toContain(words);
+      expect(d.got.upload).toBeUndefined();
+    } finally { d.stop(); }
+  }
+  const d = fakeDevice("hang");
+  try {
+    const r = await sendFile(d.dev, f, () => {}, { acceptMs: 300 });
+    expect(r).toEqual({ ok: false, error: "No answer from Pixel 8 in 1 minute" });
+  } finally { d.stop(); }
+  // Nobody there at all.
+  const r = await sendFile({ ...d.dev, port: 1 }, f);
+  expect(r.ok).toBe(false);
+  expect((r as any).error).toStartWith("Could not reach Pixel 8");
+});
+
+// A real LocalSend in HTTPS mode refuses a sender without a client certificate
+// ("tlsv13 alert certificate required"), and reads the sender's fingerprint as its SHA-256.
+test("we carry a self-signed certificate whose SHA-256 is our fingerprint", () => {
+  const me = identity(), x = new X509Certificate(me.cert);
+  expect(x.subject).toBe("CN=kaizen");
+  expect(x.verify(x.publicKey)).toBe(true);
+  expect(x.checkPrivateKey(createPrivateKey(me.key))).toBe(true);
+  expect(x.fingerprint256.replace(/:/g, "")).toBe(me.fingerprint);
+  expect(new Date(x.validTo).getTime()).toBeGreaterThan(Date.now() + 365 * 86_400_000);
+  expect(identity()).toBe(me);
+});