kandown 0.34.3 → 0.35.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.35.1 — 2026-07-26 — "Light Identity"
+
+### Added
+
+- **Homepage video storyboard**: Replaced the hand-built board and terminal mocks with black recording frames that specify the exact scenario, duration, aspect ratio, and filename for six real product clips: the hero workflow, a two-agent handoff, Markdown-to-board synchronization, and dedicated Web, TUI, and CLI demonstrations. The three interface briefs share one interactive tabbed stage so the final page will never autoplay three videos at once.
+
+### Changed
+
+- **Agent-first homepage narrative**: Reordered and rewrote the landing page around long-running work that survives agent sessions, durable Markdown ownership, completion reports, handoffs, and one shared board across the Web UI, TUI, and CLI. The feature grid, final call to action, shared metadata, footer, and recording documentation now follow the same product promise.
+- **One permanent light website identity**: The marketing and documentation website now uses a single warm light palette regardless of the device preference. Native controls declare `color-scheme: light`, browser chrome uses a fixed white theme color, syntax highlighting emits only the GitHub Light palette, and the animated hero shader uses one documented color path.
+- **Light embedded demo**: The in-browser demo project now starts explicitly in light mode rather than inheriting `prefers-color-scheme`, keeping the transition from the website into the real Kandown application visually consistent while installed projects retain the full product theme system.
+- **Video production guide**: Expanded the website README with the six expected WebM filenames, target durations, 16:10 recording dimensions, loop guidance, and the exact actions to capture in every clip.
+
+### Removed
+
+- **Website dark-mode runtime**: Removed the header theme toggle, localStorage preference, pre-paint theme script, OS dark-mode listeners, `data-theme` selectors, dark CSS tokens, dual Shiki palette, shader theme observer, and View Transition wipe. A device can no longer select a different visual identity for the site.
+
+## 0.35.0 — 2026-07-25 — "House Green"
+
+- **Added**: **Kandown finally has its own theme, and it is the default** — a `kandown` preset built from the brand palette registered on the website: `#88E138` brand lime (the logo arrow) as the dark-mode primary, `#7AD12A` as its light-background variant, `#0CE931` (the hero shader green) reused as the `success` token, `#F1FFB8` for accent surfaces and `#EBEBEB` for neutral borders, on 4px radius to match the website. Because lime cannot carry white text at any usable contrast, `primary-foreground` is a near-black green in both modes (7.9:1 light, 11.2:1 dark) rather than the usual white. Every other foreground/background pair passes WCAG AA in both modes.
+- **Fixed**: **The default skin silently resolved to Vercel** — `DEFAULT_CONFIG.ui.skin` already read `'kandown'`, but `LEGACY_SKIN_MAP` still aliased `kandown` to `vercel` from before the FABLE_UI theme system, so every fresh project opened in monochrome instead of the brand colors. The alias is gone, the preset now sits first in `THEME_PRESETS` (and is therefore the `[0]` fallback for an unknown id), and `normalizeSkinId` falls back to `kandown` instead of `vercel`.
+- **Changed**: **Website hero rewritten** — the technical breadcrumb (Local-first / MIT / Node / npm) is replaced by a short free, open-source, local promise, and the headline is reframed around Markdown tasks built for AI agents, long-running work, and the web/TUI/CLI trio. The shared tagline and description used for SEO and machine-readable docs were aligned with it.
+- **Added**: **Demo mode** — a third backend for the web UI that answers the Kandown REST API from an in-memory `Map` instead of a disk, so the whole application can run in a browser tab with no CLI, no server and no storage. It plugs in at `apiFetch` (`src/lib/filesystem.ts`) via `registerDemoApi()`, which is why the board, drawer, editor, search, archive and drag-and-drop all work without knowing anything changed — nothing is mocked. Built with `pnpm build:demo`, which also drops `vite-plugin-singlefile` in favour of a normal chunked build. The entire feature is compiled out of the bundle `npx kandown` ships, behind the `__KANDOWN_DEMO_BUILD__` define.
+- **Fixed**: **Header task counter rendered `[object Object] tasks`** — `useAnimatedNumber` returns a Motion `MotionValue`, which has to be rendered by a `motion.*` component that subscribes to it; wrapping it in `String()` stringified the object itself. Every user of the web board saw this on every screen.
+- **Fixed**: **Repository root could open as a project named `templates`** — implicit project resolution now checks the current directory and walks upward for the nearest valid `.kandown/kandown.json` instead of recursively scanning child directories. This keeps the live board anchored to the canonical root `.kandown/` + `tasks/` layout, works from nested paths such as `src/`, and prevents packaged init assets under `templates/` from being mistaken for a project.
+- **Changed**: **Removed downward child-project auto-discovery** — launching Kandown from a directory above a project no longer guesses which descendant board to open. Run it inside the intended project (or one of its subdirectories), or pass an explicit `--path`, for deterministic selection.
+- **Cleaned**: Removed accidentally committed `templates/daemon.json` runtime state and `templates/kandown.html` generated output. The configuration, documentation, and welcome-task seeds required by `kandown init` remain in `templates/`.
+
 ## 0.34.3 — 2026-07-24 — "Motion Polish — Drag Fix"
 
 - **Fixed**: **Cards could not be dragged between columns after the v0.34.2 motion polish** — the `motion.div` → plain `<div>` replacement in `Card.tsx` accidentally dropped the `draggable` HTML5 attribute and the `{...dragHandlers}` spread that wire `onDragStart` / `onDragEnd` on each card. Without `draggable` the native HTML5 drag event never fired, so the board could not move tasks between columns even though the click-to-open drawer still worked. Restores `draggable` and `dragHandlers` on the card container; no other behavior changes.
@@ -356,8 +384,8 @@
 
 ## 0.15.0 — 2026-07-07 — "Boot Splash"
 
-- **Added**: **Boot splash** — au lancement du projet, le titre `kandown` + badge `v<version>` reste affiché pendant 5 secondes, puis fond en fade-out pour ne laisser que le logo. Le nom du projet ouvert prend ensuite sa place comme titre de page du header, avec une transition douce.
-- **Added**: **Document title dynamique** — l'onglet du navigateur reflète désormais le projet courant (`<Projet> · Kandown`) au lieu d'un titre statique.
+- **Added**: **Boot splash** — on project launch, the `kandown` title and a `v<version>` badge stay on screen for 5 seconds, then fade out to leave only the logo. The name of the open project then takes its place as the header's page title, with a soft transition.
+- **Added**: **Dynamic document title** — the browser tab now reflects the current project (`<Project> · Kandown`) instead of a static title.
 
 ## 0.14.1 — 2026-07-07 — "Resilience Pass"
 

package/README.md

@@ -6,8 +6,8 @@
 
 <p align="center">
   <strong>Too Many Ideas, Not Enough Agents.</strong><br>
-  Kandown helps you queue tasks in an elegant and clever way — file-based Kanban backed by plain Markdown.<br>
-  Zero backend · Zero database · No account · AI-agent friendly
+  A local-first Kanban board where every task is a Markdown file you own forever.<br>
+  Zero backend · Zero database · No account · Built for working alongside AI agents
 </p>
 
 <p align="center">
@@ -17,230 +17,224 @@
   <img src="https://img.shields.io/badge/local--first-100%25-orange" alt="100% local-first">
 </p>
 
----
-
-## Description
-
-Kandown is a **local-first Kanban board** where your tasks live as plain Markdown files. No cloud, no account, no vendor lock-in — just a `.kandown/` folder in your project that you own forever.
-
-- **Your data is portable** — tasks are `.md` files versioned with git, readable by any text editor or AI agent
-- **AI-agent friendly** — Claude, Codex, Gemini, Goose, Aider, and OpenCode can read and update tasks directly
-- **Dual interface** — a polished web UI + a full terminal TUI, both running entirely offline
-- **Single-file deployment** — `kandown.html` is a self-contained app you can open in any browser
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#for-ai-agents">For AI agents</a> ·
+  <a href="#cli-reference">CLI</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#contributing">Contributing</a>
+</p>
 
 ---
 
-## Installation
+## What it is
 
-```bash
-npm install -g kandown
-```
+Kandown drops a `tasks/` folder into your project and gives you three ways to work
+with it: a polished web board, a full terminal UI, and a scriptable CLI. All three
+read and write the same plain Markdown files.
 
-**Requirements:** Node.js 18+
+- **Your data is just files.** One `.md` per task, versioned in git, readable by any
+  editor, any script, any AI agent. Nothing to export, nothing to lose.
+- **Agents are first-class users**, not an integration. Claude Code, Codex, Gemini
+  CLI, Goose, Aider and OpenCode all drive the board directly.
+- **Fully offline.** No account, no cloud, no telemetry. The web UI is one
+  self-contained HTML file you can open anywhere.
 
 ---
 
-## Usage
-
-### Initialize in any project
+## Quick start
 
 ```bash
+npm install -g kandown     # Node.js 18+
 cd my-project
 kandown init
+kandown
 ```
 
-This creates two folders at your project root:
+`kandown init` creates two folders at your project root:
 
 ```
+tasks/                # your tasks — the source of truth
+├── t1.md             # one Markdown file per task
+└── archive/          # archived tasks live here
+
 .kandown/             # config + web UI + agent docs
-├── kandown.html      # Single-file web app
-├── kandown.json      # Project config (columns, appearance)
-├── AGENT.md          # AI-agent quick reference
-└── AGENT_KANDOWN.md  # Full agent reference
-
-tasks/                # Task files (source of truth)
-├── t1.md             # One .md file per task
-└── archive/          # Archived tasks live here
+├── kandown.json      # columns, theme, notifications, agents
+├── kandown.html      # the web app, one self-contained file
+├── instructions.md   # optional: your project's agent instructions
+└── AGENT*.md         # agent reference, kept in sync with the CLI
 ```
 
-> **Layout note:** tasks live at the project root in `./tasks/`, not inside
-> `.kandown/`. This keeps config and data cleanly separated. If you're
-> upgrading from an older version with tasks in `.kandown/tasks/`, the CLI
-> will move them automatically the first time you run it — nothing to do.
+`kandown` then starts a small local daemon and opens both a **web board** in your
+browser and a **terminal UI** in your shell. The daemon outlives the TUI, so the
+browser keeps working after you quit — stop it with `d` in the TUI or
+`kandown daemon stop`.
 
-### Launch the board
+Tasks live at your project root rather than inside `.kandown/` so that config and
+data stay cleanly separated. Upgrading from an older layout? The CLI moves them for
+you on first run.
 
-```bash
-kandown
-```
+---
 
-This starts a per-project local web daemon, then opens:
-- A **web UI** in your browser (board view, list view, task editor)
-- A **terminal TUI** for keyboard-driven workflow (works over SSH, no browser needed)
+## For AI agents
 
-The web daemon stays alive after you quit the TUI so the browser keeps working. Stop or restart it anytime from the TUI with `d`, or from the CLI with `kandown daemon stop`.
+This is the part that makes kandown different, so it is worth two minutes.
 
-### CLI Commands
+### One command for context
 
-| Command | Description |
-|---|---|
-| `kandown` | Launch web UI + board TUI |
-| `kandown init` | Initialize in current project |
-| `kandown board` | TUI only (no browser) |
-| `kandown settings` | Terminal settings editor |
-| `kandown daemon status` | Show this project's web daemon status |
-| `kandown daemon start` | Start/reconnect this project's web daemon |
-| `kandown daemon stop` | Stop this project's web daemon |
-| `kandown daemon refresh-all` | Refresh open projects and restart outdated daemons with the current CLI version |
-| `kandown update` | Update `kandown.html` to latest |
-| `kandown list` \| `show` \| `create` \| `move` \| `assign` \| `commit` | One-shot task commands (see below) |
-| `kandown tasks` | Full help for the one-shot task commands |
-| `kandown work` | **For AI agents:** print the agent rules + a live board digest (see below) |
-| `kandown help` | CLI help |
+```bash
+kandown work
+```
 
-### One-shot task commands (scriptable, agent-friendly)
+That prints, as plain Markdown on stdout:
 
-Top-level, non-interactive commands for scripting, CI, and AI agents — no wrapper prefix, just `kandown <command>`. Every command auto-inits `.kandown/` on first use, same as the interactive CLI.
+1. **The agent rules** — served from the installed CLI, so they are never a stale
+   copy frozen into your repo at init time.
+2. **Your project instructions** — optional, from `.kandown/instructions.md`. Stack
+   quirks, "always use pnpm", commit-message language, token-efficiency
+   preferences.
+3. **A live board digest** — column counts, tasks per column with blocked-by
+   annotations, and a computed **next actionable task** (unblocked, closest to done,
+   highest priority).
 
-| Command | Description |
-|---|---|
-| `kandown list` | List tasks — `[-s status] [-a assignee] [-t tag] [-p priority] [--archived] [--json]` |
-| `kandown show <id>` | Print a task file's raw content |
-| `kandown create "title"` | Create a task — `[-p priority] [-a assignee] [-t tag ...] [--to status] [--id custom-id] [--json]` |
-| `kandown move <id> <status>` | Move a task — `<status>` is a column name or `"archived"` |
-| `kandown assign <id> [name]` | Assign a task (omit name to unassign) |
-| `kandown commit [-m "message"]` | `git add tasks/ .kandown/kandown.json` + `git commit` |
+One call, full context. `kandown init` adds a single line to your `AGENTS.md` /
+`CLAUDE.md` pointing at it — no block of rules copied in to go stale.
+
+The Settings page has an **Agent → `kandown work` output** configurator: toggle each
+block, switch to a concise token-efficient mode, hide digest fields, see an
+estimated token count, or take full control with a raw template using
+`{{baseRules}}`, `{{projectInstructions}}` and `{{boardDigest}}`.
+
+### Scriptable, composable, offline
 
 ```bash
 kandown list --json | jq '.[] | select(.priority=="P1")'
-kandown create "Refactor auth middleware" -p P1 -t backend
-kandown move t42 Done
-kandown assign t42 alice
+ID=$(kandown create "Refactor auth middleware" -p P1 -t backend)
+kandown move "$ID" Done
 kandown commit -m "tasks: add auth refactor"
 ```
 
-**Output contract:** stdout carries data only (task ids, JSON, tables) — everything decorative (`✓ Created…`, warnings, errors) goes to stderr. This keeps `ID=$(kandown create "...")` and `kandown list --json | jq ...` clean and composable. Exit code `0` on success, non-zero on error — safe to check in scripts.
+**Output contract:** stdout carries data only — ids, JSON, tables. Everything
+decorative (`✓ Created…`, warnings, errors) goes to stderr. So `$(kandown create
+…)` captures exactly one id, and `--json | jq` never chokes on a checkmark. Exit
+code `0` on success, non-zero on failure.
 
-**No update checks:** the task commands and `kandown daemon` never touch the npm registry, so they stay fast and fully offline-capable — ideal for CI and for AI agents driving the board directly.
+**No network, ever.** The task commands and `kandown daemon` never contact the npm
+registry, so they stay instant and work offline — ideal for CI and for agents in a
+loop.
 
-### `kandown work` — the agent entrypoint
+### MCP
 
-`kandown init` no longer copies a block of rules into your `AGENTS.md`/`CLAUDE.md` — it appends a single line instead:
+```bash
+kandown mcp                          # stdio MCP server
+claude mcp add kandown -- kandown mcp
+```
 
-> This project uses **kandown** for task management. **Always run `kandown work` when starting a new task** — it prints the current rules and board state, kept in sync with the installed CLI version.
+### Launching agents from the board
 
-Running `kandown work` prints, as plain markdown on stdout:
+Press `a` on any task in the terminal UI to hand it to an agent:
 
-1. **The agent rules** — always fresh, served straight from the installed CLI version instead of a copy that goes stale the moment the package updates.
-2. **Project instructions** (optional) — `.kandown/instructions.md`, this project only (stack quirks, "always use pnpm", commit message language, token-efficient agent preferences, etc).
-3. **A live board digest** — column counts, tasks per column with blocked-by annotations, and a computed **"next actionable task"** (closest to done, unblocked, highest priority) — so the agent gets its context in the same call.
+| Agent | Binary | Launch mode |
+|---|---|---|
+| Claude Code | `claude` | interactive session |
+| OpenAI Codex | `codex` | interactive session |
+| Gemini CLI | `gemini` | `-p` initial prompt |
+| Goose | `goose` | `run --text`, non-interactive |
+| Aider | `aider` | `--message` initial prompt |
+| OpenCode | `opencode` | TUI, context written to `/tmp` |
 
-The Settings page includes an **Agent → kandown work output** configurator. You can toggle each generated block, switch the base rules to a concise token-efficient mode, hide detailed digest fields, see an estimated token count, or use **Raw template** mode to control the complete output with `{{baseRules}}`, `{{projectInstructions}}`, and `{{boardDigest}}` variables.
+Or point kandown at your own tooling with `KANDOWN_AGENT_HOOK_URL` and let any
+IDE, bot or webhook receive tasks.
 
-Kandown keeps generated agent reference docs inside `.kandown/` only. If `.kandown/AGENT_KANDOWN.md` is missing, malformed, or an outdated generated copy, the CLI recreates it from the installed package template. Custom behavior belongs in `.kandown/instructions.md` and `.kandown/kandown.json`, not in project-root agent files.
+---
 
-This removes the drift problem of a rules block frozen into every project's `AGENTS.md` at init time, keeps the injected footprint to one line, and lets you layer project instructions without touching the agent file at all.
+## CLI reference
 
-> **Upgrading from before v0.18.0?** `kandown shell <cmd>` was removed (no alias) — the commands are now top-level: `kandown list/show/create/move/assign/commit`. Existing projects keep their old `AGENTS.md`/`CLAUDE.md` block until you re-run `kandown init`. The CLI prints a one-time notice about this the next time you run an interactive command after updating — see [Environment variables](#environment-variables) if you want to silence version-check output entirely.
+### Interactive
 
----
+| Command | Description |
+|---|---|
+| `kandown` | Web UI + terminal board |
+| `kandown init` | Initialize in the current project |
+| `kandown board` | Terminal UI only, no browser |
+| `kandown settings` | Terminal settings editor |
+| `kandown doctor` | Diagnose config, daemon, ports, task frontmatter |
+| `kandown help` | Full help |
 
-## Environment variables
+### Tasks — non-interactive, agent- and CI-friendly
 
-| Variable | Effect |
+| Command | Description |
 |---|---|
-| `KANDOWN_NO_UPDATE=1` | Disable the background auto-update check entirely (recommended for CI) |
-| `KANDOWN_DEBUG=1` | Print full stack traces on unexpected errors instead of a one-line summary |
-| `KANDOWN_AGENT_HOOK_URL` | POST endpoint that receives tasks sent via the "Send to Agent" button / TUI `g` key |
-| `KANDOWN_AGENT_HOOK_LABEL` | Custom label for the agent hook button (default: `Agent`) |
-| `KANDOWN_AGENT_HOOK_HEADERS` | JSON object of extra HTTP headers to send with the agent hook request |
+| `kandown list` | List tasks — `[-s status] [-a assignee] [-t tag] [-p priority] [--archived] [--json]` |
+| `kandown show <id>` | Print a task file's raw content |
+| `kandown create "title"` | Create — `[-p priority] [-a assignee] [-t tag …] [--to status] [--id custom-id] [--json]` |
+| `kandown move <id> <status>` | Move to a column, or to `archived` |
+| `kandown assign <id> [name]` | Assign, or unassign by omitting the name |
+| `kandown commit [-m msg]` | `git add tasks/ .kandown/kandown.json` + commit |
+| `kandown export` / `import` | JSON / CSV out, Trello JSON or Markdown in |
 
-Interactive runs of `kandown` check npm for updates at most once every 24 hours (never for the task commands or `daemon`, never when stdout isn't a terminal) and auto-install silently when one is found.
+### Daemon & maintenance
+
+| Command | Description |
+|---|---|
+| `kandown daemon status\|start\|stop` | Manage this project's web daemon |
+| `kandown daemon refresh-all` | Restart outdated daemons on the current CLI version |
+| `kandown projects` | List every open kandown project on this machine |
+| `kandown update` | Update the CLI and the project's `kandown.html` |
 
 ---
 
-## Security notes
+## Features
 
-- The local web daemon binds to `127.0.0.1` only and issues a random per-project API token on startup (stored in the gitignored `.kandown/daemon.json`, injected into the served page). Every API route except the read-only `GET /api/daemon` identity check requires it — a stray browser tab on another site can't read or write your tasks through it.
-- `.kandown/daemon.json` and `.kandown/daemon.lock` are runtime-only files; `kandown init` adds them to `.kandown/.gitignore` automatically.
+### Board & views
 
----
+Horizontal kanban with drag-and-drop · sectioned list view with filters and search ·
+full-text search across titles, bodies, subtasks, tags, assignee and priority ·
+command palette (`⌘K`) · freely editable columns · group-by
+(priority / assignee / epic) · due-date banner · guarded double-click deletion ·
+bulk archive or delete of a whole column.
 
-## Features
+### Tasks
 
-### Board & Views
+WYSIWYG Markdown editor · subtask checklists with per-step descriptions, reports and
+keyboard reordering · priority, assignee, tags, due date, epic, owner type ·
+`depends_on` dependencies with a gate that refuses to close a blocked task ·
+human/agent owner filtering · quick-add syntax
+(`Fix login p1 #backend @chacha due:friday`) · task templates ·
+external-change detection.
 
-| Feature | Description |
-|---|---|
-| Board view | Horizontal kanban with drag-and-drop |
-| List view | Sectioned vertical list with filters, search, and drag-and-drop between statuses |
-| Content search | Search titles, body, subtasks, tags, assignee, priority |
-| Command palette | `⌘K` / `Ctrl+K` for quick actions |
-| Custom columns | Add, rename, delete columns freely |
-| Guarded deletion | Double-click to delete — no accidents |
-| Terminal bulk actions | Archive or permanently delete every task in the terminal column with confirmation |
+### Appearance
 
-### Task Management
+**38 built-in themes** (Vercel, Linear, Claude, Apple, Stripe, Catppuccin, Dracula,
+Nord, Terminal, Synthwave and more) plus custom themes defined in JSON · light /
+dark / auto · tokenised radius, shadows, density and motion · 5 font stacks ·
+animated WebGL background · **48 languages** · browser and sound notifications.
 
-| Feature | Description |
-|---|---|
-| Rich task drawer | WYSIWYG markdown editor for title, metadata, subtasks, body |
-| Subtasks | Full checklist with progress tracking on cards |
-| Subtask editor | Add, reorder-by-keyboard, check off, remove, and edit per-step descriptions and reports |
-| Metadata fields | Priority, assignee, tags, due date, owner type |
-| Owner filtering | Filter human vs AI-agent tasks separately |
-| External-change detection | Warns when files are modified outside the app |
+### Terminal UI
 
-### Appearance & UX
+Keyboard-driven and mouse-aware, works over SSH with no browser.
 
-| Feature | Description |
+| Key | Action |
 |---|---|
-| 5 built-in skins | Kandown, Graphite, Sage, Cobalt, Rose |
-| Theme modes | Auto (system), Light, Dark |
-| 5 font stacks | Inter, System, Serif, Mono, Rounded |
-| Animated backgrounds | WebGL fluid simulation (LiquidEther) |
-| 48 languages | Full i18n support |
-| Notifications | Browser + sound alerts for status changes, edits, completions |
+| `j`/`k`, `h`/`l` | Navigate tasks / columns |
+| `n` · `e` · `m` | New task · edit in `$EDITOR` · move |
+| `/` · `f` | Fuzzy search · cycle filters |
+| `a` · `g` | Launch an agent · send to agent hook |
+| `x` · `D` | Archive · delete |
+| `d` · `r` · `?` | Toggle daemon · reload · cheatsheet |
 
-### AI Agent Integration
+Drag a task with the mouse to move it between columns.
 
-Press `a` in the board TUI to launch an AI agent on any task. Supported agents:
-
-| Agent | Binary | Launch mode |
-|---|---|---|
-| Claude Code | `claude` | Interactive session |
-| OpenAI Codex | `codex` | Interactive session |
-| Gemini CLI | `gemini` | `-p` flag for initial prompt |
-| Goose | `goose` | `run --text` for non-interactive |
-| Aider | `aider` | `--message` for initial prompt |
-| OpenCode | `opencode` | TUI, context written to `/tmp` |
+### Web shortcuts
 
-### Keyboard Shortcuts
+`⌘K` palette · `⌘1`/`⌘2` board/list · `N` new · `R` reload · `/` search ·
+`⌘S` save · `⌘⌫` delete · `Esc` close.
 
-| Shortcut | Action |
-|---|---|
-| `⌘K` / `Ctrl+K` | Command palette |
-| `⌘1` / `Ctrl+1` | Board view |
-| `⌘2` / `Ctrl+2` | List view |
-| `N` | New task |
-| `R` | Reload from disk |
-| `/` | Focus search |
-| `Esc` | Close drawer / palette |
-| `⌘S` / `Ctrl+S` | Save task |
-| `⌘⌫` / `Ctrl+Backspace` | Delete task (with confirmation) |
-
-### TUI extras
-
-| Shortcut / gesture | Action |
-|---|---|
-| `d` | Start/stop the per-project web daemon |
-| Mouse drag task | Move a task between columns in the terminal |
-| `m` | Open the focused task context menu |
-| `r` | Reload board from disk |
+---
 
-### Data Model
+## The data model
 
-Each task is a standalone Markdown file:
+One task, one file, no index:
 
 ```markdown
 ---
@@ -250,6 +244,7 @@ status: Todo
 priority: P1
 tags: [backend, security]
 assignee: chacha
+depends_on: [t7]
 created: 2026-04-10
 ---
 
@@ -259,50 +254,85 @@ created: 2026-04-10
 Why this task exists.
 
 ## Subtasks
-- [ ] Set up OAuth provider
 - [x] Create user model
-- [ ] Add session middleware
+  report: Added src/models/user.ts with the schema and migrations.
+- [ ] Set up OAuth provider
 ```
 
+| Field | Meaning |
+|---|---|
+| `status` | Board column, from `board.columns` in `kandown.json` |
+| `order` | Sort position within the column |
+| `priority` | `P1`–`P4` |
+| `tags`, `assignee` | Free-form labels, username or agent name |
+| `ownerType` | `human` or `ai` — drives owner filtering |
+| `depends_on` | Task ids blocking this one; moving to the terminal column is refused while any is unresolved |
+| `report` | Completion summary in Markdown, shown prominently in the UI |
+
 ---
 
-## Contributing
+## Configuration
 
-Contributions are welcome! Please read the existing code style and conventions before submitting PRs.
+### Environment variables
 
-### Development Setup
+| Variable | Effect |
+|---|---|
+| `KANDOWN_NO_UPDATE=1` | Disable the background update check (recommended in CI) |
+| `KANDOWN_DEBUG=1` | Print full stack traces instead of a one-line summary |
+| `KANDOWN_AGENT_HOOK_URL` | Endpoint that receives tasks from "Send to Agent" / TUI `g` |
+| `KANDOWN_AGENT_HOOK_LABEL` | Custom label for the agent hook button |
+| `KANDOWN_AGENT_HOOK_HEADERS` | JSON object of extra headers for the hook request |
+
+Interactive runs check npm for updates at most once every 24 hours — never for the
+task commands, never for `daemon`, never when stdout is not a terminal — and install
+silently when one is found.
+
+### Security
+
+The local daemon binds to `127.0.0.1` only and mints a random per-project API token
+at startup, stored in the gitignored `.kandown/daemon.json` and injected into the
+page it serves. Every route except the read-only `GET /api/daemon` identity check
+requires it, so an unrelated browser tab cannot reach your tasks by scanning
+localhost ports. Task ids are validated before they touch the filesystem.
+
+---
+
+## Contributing
+
+Contributions are welcome.
 
 ```bash
 git clone https://github.com/vava-nessa/kandown.git
 cd kandown
-pnpm install
-pnpm dev          # Web UI at localhost:5176
+pnpm install          # also installs the git hooks
+pnpm dev              # web UI at localhost:5176
 ```
 
-### Scripts
+Before your first change, read — in this order:
 
-| Script | Description |
+| Document | What it gives you |
 |---|---|
-| `pnpm dev` | Vite dev server for web UI |
-| `pnpm dev:cli` | Watch-mode build for CLI TUI |
-| `pnpm build` | Full build: typecheck → web app → CLI |
-| `pnpm build:cli` | CLI TUI build only |
-| `pnpm preview` | Preview production build |
-| `pnpm typecheck` | TypeScript check |
-
----
+| [`AGENTS.md`](AGENTS.md) | The project's rules, including which files are generated |
+| [`CODEMAP.md`](CODEMAP.md) | Every source file with a one-line summary — generated from JSDoc |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | How the pieces fit and which invariants not to break |
+| [`docs/RELEASE.md`](docs/RELEASE.md) | The release runbook |
 
-## License & credits
+The short version: **`bin/*.js` are build output, not source** — edit `src/cli/`
+instead. Every source file carries a JSDoc `@file` / `@description` header, `CODEMAP.md`
+is generated from them on every commit, and CI fails if either drifts.
 
-[MIT](LICENSE) © 2026 [Vanessa Depraute](https://vanessadepraute.dev) — GitHub: [vava-nessa](https://github.com/vava-nessa).
-
-Created and maintained by [Vanessa Depraute](https://vanessadepraute.dev).
+| Script | Description |
+|---|---|
+| `pnpm dev` | Vite dev server for the web UI |
+| `pnpm dev:app` | Full build, then launch the CLI |
+| `pnpm dev:cli` | Watch-mode build of the CLI bundles |
+| `pnpm build` | Version inject → agent-doc sync → typecheck → web → CLI |
+| `pnpm typecheck` | TypeScript, no emit |
+| `pnpm codemap` | Regenerate `CODEMAP.md` / `CODEMAP.json` |
 
 ---
 
-<p align="center">
-  <a href="#-quick-start">Quick Start</a> ·
-  <a href="#-features">Features</a> ·
-  <a href="#-cli-commands">CLI</a> ·
-  <a href="#-ai-agent-integration">AI Agents</a>
-</p>
+## License
+
+[MIT](LICENSE) © 2026 [Vanessa Depraute](https://vanessadepraute.dev) —
+GitHub: [vava-nessa](https://github.com/vava-nessa)

package/bin/kandown.js

@@ -15,7 +15,7 @@ import { spawn, execSync } from "child_process";
 import { homedir } from "os";
 
 // src/lib/version.ts
-var KANDOWN_VERSION = "0.34.3";
+var KANDOWN_VERSION = "0.35.1";
 
 // src/cli/lib/updater.ts
 import { fileURLToPath } from "url";
@@ -1206,8 +1206,8 @@ function openBrowser(target) {
 }
 
 // src/cli/lib/cli-shared.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
-import { join as join7, resolve as resolve2, basename } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync7, readdirSync as readdirSync4 } from "fs";
+import { join as join7, resolve as resolve2, basename, dirname as dirname4 } from "path";
 import { spawn as spawn4 } from "child_process";
 
 // src/cli/lib/init.ts
@@ -1383,30 +1383,21 @@ function stripFirstPositional(args, value) {
   return result;
 }
 function resolveKandownDir(pathArg = ".kandown", cwd = process.cwd()) {
-  if (basename(cwd) === ".kandown" || existsSync7(join7(cwd, "kandown.json"))) {
-    return cwd;
-  }
   if (pathArg !== ".kandown") {
     return resolve2(cwd, pathArg);
   }
-  let entries;
-  try {
-    entries = readdirSync4(cwd);
-  } catch {
-    return resolve2(cwd, pathArg);
-  }
-  for (const name of entries) {
-    if (name.startsWith(".") || name === "node_modules" || name === "tasks") continue;
-    const subPath = join7(cwd, name);
-    let stat;
-    try {
-      stat = statSync4(subPath);
-    } catch {
-      continue;
+  let currentDir = resolve2(cwd);
+  while (true) {
+    if (basename(currentDir) === ".kandown" && existsSync7(join7(currentDir, "kandown.json"))) {
+      return currentDir;
+    }
+    const candidate = join7(currentDir, ".kandown");
+    if (existsSync7(join7(candidate, "kandown.json"))) {
+      return candidate;
     }
-    if (!stat.isDirectory()) continue;
-    const found = resolveKandownDir(pathArg, subPath);
-    if (existsSync7(found)) return found;
+    const parentDir = dirname4(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
   }
   return resolve2(cwd, pathArg);
 }