k0-board 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # k0
 
 **A board of sticky notes that drives your Claude Code sessions.** One column per project, one
-card per piece of work. From a card you open a real terminal, and on the card you see at a
+story per piece of work. From a story you open a real terminal, and on the story you see at a
 glance whether the session is working, has finished, is asking you something, or has a plan
 waiting for your approval.
 
@@ -9,12 +9,15 @@ It exists because of one specific moment: four terminals open, and no way to tel
 waiting for you without clicking through all four.
 
 If you have used a kanban board, an infinite canvas like Miro, and a wall of paper sticky notes,
-you have already seen the three pieces k0 is made of: cards standing in columns, a board that pans
+you have already seen the three pieces k0 is made of: stories standing in columns, a board that pans
 and zooms instead of scrolling, and notes that sit at their own slightly crooked angle. What is
-different is what those things are underneath. **A column is a repository, not a stage** — nothing
-gets dragged from one to the next; the cards reorder themselves by who is waiting for you.
-**A card is a real Claude Code session** — it opens a terminal, it knows what that session is
-doing, and it goes on saying so while you are looking somewhere else.
+different is what those things are underneath. **A column is a repository, not a stage** — the
+stories reorder themselves by who is waiting for you, rather than being pushed along a pipeline.
+(One switch in the top bar lays the same stories out as a list instead, for the days you are
+planning rather than working.)
+**A story drives real Claude Code sessions** — it opens a terminal, it knows what that session
+is doing, and it goes on saying so while you are looking somewhere else. A story may have had
+several over its life, one at a time, and it keeps all of them.
 
 ![Four columns of paper sticky notes — yellow, blue, amber and green — pinned on a dark wall, each note tilted at its own angle, with a row of small coloured status pills along the top bar.](https://raw.githubusercontent.com/alessio-ragni/k0-board/main/docs/board.jpg)
 
@@ -23,6 +26,7 @@ doing, and it goes on saying so while you are looking somewhere else.
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational)](LICENSE)
 
 **Contents** · [Install](#install) · [How it is used](#how-it-is-used) ·
+[The backlog](#the-backlog) · [The ChangeLog](#the-changelog) · [What's New](#whats-new) ·
 [The files of a session](#the-files-of-a-session) · [What it costs](#what-it-costs) ·
 [Filling the board with what you have already done](#filling-the-board-with-what-you-have-already-done) ·
 [The statuses](#the-statuses) · [The four modes](#the-four-modes) ·
@@ -95,7 +99,7 @@ only browsers are obliged to know that `.localhost` means this computer — k0 o
 - **Node 24 or newer.** k0 keeps the board in SQLite through `node:sqlite`, which is built into
   Node — there is nothing to install and there are no npm dependencies at all.
 - **Claude Code**, obviously.
-- **git**, for the mark on each card that says whether your work is safe.
+- **git**, for the mark on each story that says whether your work is safe.
 - **macOS**: Xcode Command Line Tools, to build the menu bar icon. Nothing else.
 - **Linux**: tmux, which is how k0 drives terminals there. Optionally `xdotool` for window
   placement, and `python3` with PyGObject for the tray icon.
@@ -108,6 +112,7 @@ only browsers are obliged to know that `.localhost` means this computer — k0 o
 | Open a terminal and run Claude Code in it | ✅ | ✅ tmux | ✅ |
 | Read the terminal to know when it is ready | ✅ | ✅ | ❌ waits a fixed moment instead |
 | Leave your prompt in place, unsent | ✅ needs Accessibility | ✅ | ✅ |
+| Rename a running session when its title changes | ✅ needs Accessibility | ❌ when it ends | ❌ when it ends |
 | Place, resize and raise windows | ✅ | ✅ X11 only | ✅ |
 | Large text in terminals for driving mode | ✅ | ❌ | ❌ |
 | Keep the machine awake | ✅ | ✅ | ✅ |
@@ -138,12 +143,19 @@ Nothing on this list happens before you have seen it and said yes. Everything on
 | **macOS only** — one administrator rule | `/etc/sudoers.d/k0-pmset` | to keep the Mac awake with the lid closed. Asks for your password once, and grants exactly two command lines |
 | **macOS only** — one key binding | your Terminal profile (backed up first) | so Shift+Enter starts a new line |
 | **macOS only** — Accessibility for `node` | you grant it by hand, in System Settings | so k0 can place a prompt without sending it |
+| The commands, and the `k0-links` mod, if you want them | `~/.claude/skills/` | Claude Code looks there and in the repository you have open, and nowhere else. Asked once; installing again brings the copies up to date without asking |
 
 That last one deserves a sentence of its own: a process with the Accessibility permission can
 send keystrokes to any application, and here it is granted to your `node`, not to a signed k0
 app. Skipping it breaks nothing — the prompt gets typed and the session starts by itself.
 
-k0 makes **no network requests**. Not one, not even for a font.
+k0 makes **exactly one network request**, and you can switch it off. Once a day it asks the public
+npm registry what the newest version of `k0-board` is, so the board can mention that there is one.
+The package name is in the address and nothing else is in the request: not the version you are
+running, not your repositories, not your commits, not your board, not an identifier of any kind.
+Nothing is downloaded and nothing is run — k0 cannot update itself. Set `"updateCheck": false` in `~/.k0/config.json` and and no
+socket is opened, ever. Everything else stays as it was: no fonts fetched, no telemetry, no
+`git fetch`.
 
 ---
 
@@ -152,9 +164,13 @@ k0 makes **no network requests**. Not one, not even for a font.
 ### The board
 
 - **+** — at the left, next to k0, and next to every repository name on the board: that one opens
-  a card with the repository already chosen. Three fields and no more: the repository, a title,
-  and what Claude should do when it starts. The prompt can be left empty — nothing stops you from
-  starting the session and typing straight into Claude Code.
+  a story with the repository already chosen. Two fields and no more: the repository and a title.
+  Nothing is asked about what the story is for, because both ways out of the dialog open a terminal
+  and you say it there. (With a backlog behind the board the `+` at the left is a menu of two — a
+  story typed here, or an epic told to a terminal — the dialog gains a field for the story's epic,
+  and the two buttons are *Discuss* and *Quick Start*. Editing a story that exists adds a list of
+  **notes**, which sit on the post-it for you to read and are never sent to Claude Code. It is
+  written out [below](#the-two-views).)
 
   The repository has to be **picked from the list** (searchable, most used at the top; arrow keys
   to move, Enter takes the highlighted row): a name typed by hand does not count. On leaving the
@@ -168,19 +184,26 @@ k0 makes **no network requests**. Not one, not even for a font.
   spaces, and the capitals you typed stay where you put them — `fix api` becomes `Fix-Api`, while
   `Fix API` stays `Fix-API`. What you see in the field is exactly the name the session will have.
 
-- **the pencil** (top right of a card) — the only way to open the editor: clicking the card
-  itself does nothing. On a card that is already finished, where there is nothing left to edit,
+- **the pencil** (top right of a story) — the only way to open the editor: clicking the story
+  itself does nothing. On a story that is already finished, where there is nothing left to edit,
   the **bin** takes its place.
 
-  Changing the title — only the title; the prompt has nothing to do with it — **immediately**
-  rewrites the name in the window's title bar, even while the session is running. Inside Claude
-  Code the real name catches up when the session ends: while the process is alive the transcript
-  already has an owner, and it would write the old name back over ours.
-
-- **Start** — opens a new terminal window, runs `claude` in the right repository under the card's
+  Changing the title — only the title; the prompt has nothing to do with it — renames the session
+  too, in three places at three moments. The window's title bar, **immediately**, session running
+  or not. The session itself, if it is still running, **the first time you look at it**: when that
+  window is the one in front of you and Claude Code is sitting idle with nothing under the cursor,
+  k0 types `/rename` with the new name into it and presses Enter — you will see the command go by.
+  It never brings the window up to do that: the keyboard is yours, and a terminal jumping up while
+  you type somewhere else would take your next words. And the list of sessions you can resume,
+  **when the session ends** — while the process is alive the transcript already has an owner, and
+  it would write the old name back over ours. On Linux and Windows the second of the three is
+  missing, and `k0-board doctor` says so: there the name catches up when the session ends. The
+  same happens when a skill changes the title through the API.
+
+- **Start** — opens a new terminal window, runs `claude` in the right repository under the story's
   name, and puts the prompt in it. You press Enter.
 
-  The session is **born in plan mode**, always. On the board the card turns **Planning** as soon
+  The session is **born in plan mode**, always. On the board the story turns **Planning** as soon
   as it gets to work, and amber **Needs approval** when the plan is ready. If you need something
   else, shift+tab as usual. **Resume** forces nothing: that session already had a mode, and it
   comes back as it was.
@@ -189,6 +212,11 @@ k0 makes **no network requests**. Not one, not even for a font.
   never asking anything are two things Claude Code does not do together — the why is
   [further down](#the-traps).
 
+  Every session, new or resumed, is also born **with Claude Code's task list switched on**. On a
+  newer model Claude Code leaves it off unless it is told otherwise, and the commands that plan,
+  work and check keep a task per step — so without it they would be asking for a tool that is not
+  there.
+
   The window is born **centred on the screen you are using**, at 86% of the free space: the same
   margin on all four sides, never under a menu bar or a dock. Open more than one and they stack
   in the middle — double click brings the one underneath back.
@@ -201,12 +229,16 @@ k0 makes **no network requests**. Not one, not even for a font.
   it. It is what stops you losing track of which window is which.
 
 - **Resume** — appears once the terminal has been closed, by you or by k0 after a long silence: it
-  reopens the same conversation exactly where it was. The card's prompt is **not** put back in —
+  reopens the same conversation exactly where it was. The story's prompt is **not** put back in —
   that conversation answered it hours ago, and typing it in again would be at best something stale
   in the way.
 
 - **Done** — closes the work **and its terminal**, with no questions: undo it with **Reopen**, and
-  pick the conversation up again with **Resume**. It is not on backlog cards: they never started.
+  pick the conversation up again with **Resume**. On a story that has never been started there is
+  no terminal to close, and the button is there anyway as long as there is a backlog behind the
+  board — a story planned here and then worked on in a terminal you opened yourself has to be
+  closable, and `Done` is the only thing in k0 that closes one. With the backlog switched off it
+  is not drawn on those stories at all.
 
   The session is stopped first and only then is the window closed. Closing a window with `claude`
   still inside it makes macOS put up the "terminate running processes" dialog, and the window does
@@ -214,7 +246,7 @@ k0 makes **no network requests**. Not one, not even for a font.
 
 - **Close** — a link at the end of the row, quieter than the buttons because it is the one you
   reach for least: it closes the terminal and **not the work**. The session is stopped, its window
-  goes, and the machine gets the memory back; the card stays exactly where it is, with the colour
+  goes, and the machine gets the memory back; the story stays exactly where it is, with the colour
   it had — the one asking you something stays red, the one holding a plan up stays amber, the one
   at your turn stays yellow — and **Resume** takes it from there. It is what a dozen windows open
   and a computer running out of air are answered with.
@@ -222,9 +254,9 @@ k0 makes **no network requests**. Not one, not even for a font.
   It is **not there while the session is working**: stopping one mid-thought is not memory saved,
   it is work lost. Wait for it to come back to you, and then close it.
 
-The only thing that asks for confirmation is throwing a card away.
+The only thing that asks for confirmation is throwing a story away.
 
-Cards reorder themselves inside a column: first the ones waiting for you, then the ones grinding
+Stories reorder themselves inside a column: first the ones waiting for you, then the ones grinding
 away, backlog at the bottom, and among equals the most recent first.
 
 ### Moving around
@@ -261,16 +293,16 @@ that is waiting for you is the opposite of what the board is for. A terminal sim
 **Your turn** is not one of those: it is the resting state of every window you have not closed,
 and a session you finished with three weeks ago would otherwise hold its column at full width for
 ever. It folds like anything else — and folding closes nothing, so the terminal is still open and
-the card is still exactly where you left it. And **nothing folds while you are looking at it**: within one visit the set of columns can only grow, and the board tidies itself
+the story is still exactly where you left it. And **nothing folds while you are looking at it**: within one visit the set of columns can only grow, and the board tidies itself
 on the next reload, so a column never disappears out from under your hands.
 
 **The last two columns on the right are `Old` and `Others`**, and they are the same list twice
 over: a `+`, a name and the git mark, in alphabetical order. `Old` is the repositories that have
 work on the board, just not lately; `Others` is the ones that have no column because they have no
-cards at all. **Click a row in `Old` and the column comes back** at full width for the rest of the
+stories at all. **Click a row in `Old` and the column comes back** at full width for the rest of the
 visit — with everything that was in it, which is why the row itself says nothing about how much
 that is or how long it has been there. Both columns are also there for the same two things:
-getting into the files of a directory you are not working on, and giving birth to the first card
+getting into the files of a directory you are not working on, and giving birth to the first story
 there with the `+`.
 
 Next to a column's `+` there is one more button, which **puts that column away now** instead of
@@ -281,18 +313,18 @@ back to your turn every few seconds and it would spend the session blinking.
 Unlike the automatic fold, this one is remembered across reloads, until you fetch the column back
 or something in it wakes up. It **closes nothing**: no session is stopped and no terminal is
 shut. It is the board that gets smaller, not the work — what closes a session is `Close` or `Done`
-on a card.
+on a story.
 
 ### The git mark
 
-On every card, next to the repository name, and next to every column name, one symbol says
+On every story, next to the repository name, and next to every column name, one symbol says
 whether the work is safe: a **dot** with how many files, if there is work that is nowhere yet; an
 **up arrow** with how many commits, if it is committed but not pushed; a faded **tick**, if
 everything is saved. Hover to read it in full — branch, files, commits, and how many of those
 commits belong to that session. **Click it and the files open.**
 
-A card running in an **isolated worktree** has a working tree of its own, so the mark is really
-its own. A card working in the base repository shares the working tree with everybody — there the
+A story running in an **isolated worktree** has a working tree of its own, so the mark is really
+its own. A story working in the base repository shares the working tree with everybody — there the
 dot belongs to the repository, and the only thing that belongs to the session is the commits made
 since it started, which k0 counts by remembering where `HEAD` was at that moment.
 
@@ -325,8 +357,9 @@ that asked for it, close every session, restart k0 itself — the server stays u
 stays green. This is the whole reason it exists: a dev server started inside a session belongs to
 that session, and dies with it.
 
-**k0 never asks the server whether it is up.** It makes no network requests, here as everywhere
-else. "Up" means the process is alive *and* the operating system says it is holding a TCP port
+**k0 never asks the server whether it is up.** Nothing here opens a socket — the one request k0
+makes goes to npm, and it is about versions, not about you. "Up" means the process is alive *and*
+the operating system says it is holding a TCP port
 open. That is stronger evidence than a reply would be, and it is where the port in the tooltip
 comes from — k0 never guesses a port, it reads the one your server actually chose.
 
@@ -339,6 +372,478 @@ as off.
 
 ---
 
+## The backlog
+
+A post-it used to be a name and a prompt. That is enough to start a session and nothing like
+enough to remember why you started it: three weeks later the title says `Fix-Invoicing`, and the
+half hour that decided what *fixed* meant has scrolled off the top of a terminal you have since
+closed.
+
+The backlog is the rest of it. Same board, same notes, same gestures — what is added is what the
+work is *about*: what it belongs to, what was settled while you were talking about it, what has
+to be true before it can be called finished, and a check that holds the finished thing up against
+all of that before you are allowed to tick it off.
+
+**The board is the menu; the commands are the engine.** Every story says what the one next thing
+to do with it is — *Discuss*, *Plan*, *Work* — and pressing that opens a terminal with
+the command already in it. The work happens there, in Claude Code, and you do not come back to the
+board until it is finished. Almost nothing here is typed into a form.
+
+If you want the argument rather than the manual — why a decision has to be an object, what a
+round of questions is for, what the counter-check is really checking — it is in
+[docs/method.md](docs/method.md), and it is a shorter read than this section.
+
+### Before anything else: the commands have to be on your machine
+
+Everything below runs on ten commands you type at Claude Code, and Claude Code looks for a
+command in exactly two places: **the repository you have open**, and **your own
+`~/.claude/skills/`**. Neither of those is where npm puts k0. So a command that was not copied out
+is a command that does not exist, however carefully it was written — and every button on the board
+that offers to run one leads nowhere.
+
+Copying them out is **one question, asked by the installer**, right after it starts the service:
+
+```
+  /k0-epic    — an epic, discussed in rounds, then a tree of stories
+  /k0-story   — one story, straight onto the board
+  …
+  Install 11 commands and the mod for Claude Code? (Y/n)
+```
+
+Say yes and they are there in every repository you ever open. It is worth saying plainly what
+happens if you do not, because it is what happened to this feature the first time round: the
+commands were written and they worked — inside a clone of k0, and nowhere else on the machine.
+From any other repository the board offered *Discuss*, the terminal opened, and Claude Code had
+never heard of `/k0-discuss`. The whole backlog was invisible for want of one copy step.
+
+**If you are not sure you said yes, run `npx k0-board@latest` again.** It asks only about the ones
+that are missing, so somebody who already has them is not asked at all, and somebody who said no
+in a hurry gets the question back. `ls ~/.claude/skills` answers it too.
+
+If you **cloned this repository** rather than installing the package, they are already in its
+`.claude/skills/` and there is nothing to do — but only while you are working *in this clone*.
+Copy them out anyway if you use them anywhere else.
+
+### A day with it
+
+**You open the board.** Every story that has something to do carries **one button, first in the
+row, saying what that is**: **Discuss**, **Plan**, **Work** — in that order, because that is the
+order the work goes in — or **Resume**, when a terminal was opened on it and then closed. Hover it
+and it says why this and not something else: *It has been discussed and has no plan yet*. There is
+one button and never a menu, and there are three words on the list and no more.
+
+There is also a story that carries **no** button, and that is an answer too. A session that is
+running needs nothing suggested about it — the terminal is where the work is, and a double click on
+the note goes there. A story waiting for you to look it over is waiting for a person. A story that
+is finished is finished. Filling any of those in with a command would be k0 inventing work.
+
+k0 works that out and the page never does. It is the same reasoning `/k0-next` does, in the same
+place, so the button on the note and the answer the command gives can never drift apart.
+
+**You press it.** A terminal opens in that repository and `/k0-plan K42` — the line you would have
+typed yourself — goes in with it, already sent: k0 wrote that line out of a button you pressed, so
+there is nothing on it for you to read over first, and a prompt left sitting unsent under the
+cursor is a window that did nothing.
+
+**Or you take the short way in.** **Quick Start** is the other road out of a story and it is not
+the same road: it opens a terminal on that repository with *nothing* in it and leaves the typing to
+you. That is the whole of it — no discussion, no plan, no command. It sits at the end of the row as
+a quiet link on a story that has a suggestion, and it is the plain button on one that has not.
+
+Only `/k0-work` counts as the work having begun. Press *Discuss* or *Plan* and the story stays
+where it was until the discussion or the plan moves it itself — otherwise walking away from a
+discussion half way through would leave a story sitting in `Working` with nothing worked on.
+
+**You work in the terminal, and only in the terminal.** The discussion asks its rounds and writes
+each one down as it is answered; the plan comes back for your approval with the standing decisions
+written into it as constraints; `/k0-work` opens a worktree, does the work, keeps the log, and
+merges it back; `/k0-verify` walks the result past every decision one at a time. None of that
+needs the board. You can leave the tab open and watch the rounds land — it follows a live
+discussion once a second — but nothing asks you to.
+
+**You come back, and the button has moved on.** A story you discussed now says *Plan*. One you
+planned says *Work*. One whose terminal you closed says *Resume*, and picks the conversation up
+where it was rather than starting a second one beside it.
+
+**Double click the note to go where the work is.** Its terminal if one is running; the conversation
+it left behind if the terminal was closed; a fresh session if there was never one. It is the same
+gesture on every note, which is what makes it worth having — and if the window has been closed by
+hand while the session is still thinking, k0 goes and looks for it by name before it tells you
+anything, and offers to open it again when there is really nothing left to find.
+
+**Done is yours and nothing else's.** No command sets it and no gesture sets it: when the work is
+really finished you press **Done** on the note, and it closes the terminal with it. A story that
+came through its counter-check clean is offered no command at all — there is nothing left for one
+to do, and the only thing in front of it is you pressing Done. `/k0-verify` and `/k0-split` are
+still there and still do what they always did: they are commands you type, on the days you want
+them, rather than advice the board pushes at you.
+
+**Things arrive during the day, and they do not interrupt this.** Something you already know you
+want is `/k0-story` in whatever terminal you have open — you say it, it lands on the board with a
+key of its own, and adding *and start it* opens the session in the same breath. Something big
+enough that you do not yet know what it is made of is `/k0-epic`: ten minutes of questions in
+rounds, everything settled written down as it is settled, and only at the end a tree of stories
+proposed for your approval — it creates none of them until you have said yes. Both are on the
+board's `+` as well, which is a small menu now: **Story** opens the dialog you know, with one
+field added for its epic; **Epic** asks which repository and then opens a terminal running
+`/k0-epic`, because an epic is told, not typed.
+
+### The two views
+
+The switch in the top bar, in among the filters, says **Kanban** or **List**. It changes the shape
+of what you are looking at and never what you are looking at: the state pills, the repository and
+the epic lane apply to both, so switching back and forth is free and nothing appears or vanishes
+under you.
+
+**Kanban is for working.** It is the board you already know — one column per repository, notes
+that reorder themselves by who is waiting for you. With a backlog behind it a note grows four
+marks and no more: its **key**; the **epic** it belongs to, as a small label in the epic's own
+colour, worked out from the key so there is nothing to choose and nothing to keep in step; a
+**flag** in the bottom corner; and a warning when something it **waits on** is not finished.
+
+The flag is put on and taken off **from the note itself** — it is the mark and the target both,
+and it mirrors the pencil at the other corner. It is invisible until the pointer is on the note,
+because an outline sitting on every note all the time is a mark that is everywhere and therefore
+marks nothing. Once it is on it stays on, and the note takes a border and its key and title take
+the flag's colour with it: the point of flagging something is finding it again from across the
+room, and a fifteen-pixel glyph cannot be seen from there.
+
+**Click an epic's label and the board becomes that epic.** A strip appears under the top bar with
+its key, its title, its repository, a progress bar and `4 of 11 done`, and the way back out. Inside
+the lane the label is not drawn on the notes — everything in here belongs to the same epic, and
+saying so eleven times says nothing. The lane survives a reload: going into an epic is a decision
+about where you are working, and a page that forgets it every time you press F5 is a page you stop
+going into. The progress is counted over the epic's stories, not over the notes a filter left on
+screen, and it is not weighted: eleven stories with one done is 1 of 11, however big the one was.
+Anything else is an estimate, and an estimate here is a lie with a progress bar drawn round it.
+
+**List is for planning.** The same stories as rows, three levels deep and every repository at
+once: a thin heading per repository, an epic that opens and closes with its progress bar — and,
+while a discussion is running on it, which round that is on — and under it its stories, with tasks
+indented beneath the story they were cut from. Stories belonging to no epic are grouped at the
+end. A row carries key, title, state, flag, how many decisions are still standing, how much of
+the checklist has passed, and the same next-step button. Which epics you left open is remembered.
+
+**Click a row and the story opens beside it**, not underneath: the counter-check first, then why
+it exists, the rounds with their questions and answers, the decisions with the verdict each one
+got, the plan, the checklist and the log — with a line under the title saying both what it waits
+for and what is waiting for it, each key a way into that story. Beside rather than below, because
+the point of a list is to run down it, and a panel that pushes the rows off the bottom of the page
+loses the thing you were comparing against. Click an epic and the epic opens the same way — the
+rounds it was argued out in, and the decisions every story under it is held to. That is the only
+place that conversation can be watched, because it happens before a single story of it exists.
+
+Two things in this view write rather than read, and they are the two you do while *looking* at a
+backlog rather than while working on one: **the next step, started from the end of a row**, and **a
+checklist line you have just watched work with your own eyes** — ticked in the panel, and recorded
+as yours rather than the model's, which is the difference the checklist exists to keep.
+
+**Dragging a row moves it.** Up and down to change the order, onto another epic's heading to move
+it there, onto `No epic` to take it out of one. That is the whole of it: **dragging never changes
+state.** A state is a road the work walks, and walking it by dropping a piece of paper somewhere
+was always the wrong gesture — states move from the terminal, and from the Done button.
+
+### The ten commands
+
+Ten you type, and the installer offers eleven — these ten plus
+[`/k0-import`](#filling-the-board-with-what-you-have-already-done) — and one more thing that is not a
+command at all, [the `k0-links` mod](#what-claude-points-at-one-click-away). `/k0-whatsnew` and
+`/k0-changelog` are deliberately not on that list: k0 runs those two itself, out of its own
+directory, and you never type them.
+
+| | |
+|---|---|
+| `/k0-story` | one story, straight onto the board — the fast door |
+| `/k0-epic` | the long way in: rounds, decisions, then a tree of stories you approve |
+| `/k0-discuss` | the same rounds against a story that already exists |
+| `/k0-split` | a story that will not close, cut into tasks that inherit its decisions |
+| `/k0-plan` | plan mode, with the standing decisions written into the plan as constraints |
+| `/k0-work` | the worktree, the work, the log as it goes, and the merge back |
+| `/k0-ultracode` | a whole epic, or one story, run by a manager with agents under it |
+| `/k0-verify` | the counter-check |
+| `/k0-next` | what to pick up now, and why |
+| `/k0-order` | priority and dependencies, dictated: *K51 to the top, K42 waits on K37, flag K19* |
+
+These ten are also the only ten a button on the board may start. They are written out by name in
+the server and checked against that list before anything reaches a command line — and it is a list
+and not a directory listing on purpose: a folder arriving in your skills directory, from a clone or
+a package or an installer, must not thereby become something a web page can ask k0 to run.
+
+`/k0-next` is worth one sentence of its own, because the answer is not the model's. k0 works out
+what to pick up — a live session first, then something in `Review` and the one that has been
+sitting there longest, then what is not waiting on unfinished work, then the flag, then how far
+along it is, then the order you put the board in — and hands over the story with the sentence that
+says why. Ask twice and you get the same answer, which is not true of anything a model reasons out
+each time.
+
+**Dependencies are a note, not a lock.** Nothing refuses to start a story that is waiting on
+another one: the note is marked, the button that starts the work asks you once and then goes
+ahead, and the story sinks down `/k0-next`. A backlog that will not let you work on what you want
+is a backlog you stop using.
+
+### An epic, a story, a task
+
+**A story is one post-it**, and it is the thing you work on. Everything the board already does it
+still does: a story opens a terminal, drives the session in it, and says what that session is
+doing.
+
+**An epic is a reason** with several stories under it — an area, a feature, a rewrite. It lives in
+exactly one repository, because a piece of work that spans two of them is two pieces of work with
+a wish in the middle.
+
+**A task is a story that was cut out of another one.** It is not a different kind of thing: same
+table, same rules, same key — a story that turned out too big to close gets split, not turned into
+another species. A task takes its parent's epic unless you give it one of its own, because a task
+planned outside the epic its parent sits in would be planned blind to every decision that shaped
+the whole thing.
+
+### The key, and where it sits
+
+Every epic, story and task gets a **key**: `K` plus a number, `K42`. It is counted per repository,
+shared between epics and stories, and it is **never reused and never reassigned** — not when the
+story moves under another epic, not when you delete it, not when the repository is renamed. Two
+repositories can both have a `K42`, and that is intended: a key means something inside its
+repository and nowhere else. Move a story to another repository and it is given a key from *that*
+repository, rather than carrying a number into a place that already has one.
+
+Beside it there is a **position**: `1.12.1`. The first epic, its twelfth story, that story's first
+task. The position is worked out fresh every time it is shown and never stored, so it cannot
+disagree with the tree it describes — move a story and its position moves with it.
+
+The key is the name you say out loud; the position is where the thing is sitting today. When you
+say `K42` to a command it knows what you mean, whatever the board has been rearranged into since.
+
+### Why a story is not a session
+
+This is the one change underneath everything else, and it is worth a paragraph.
+
+A card used to *be* a session: one note, one conversation, and ticking the note off ended both. So
+a piece of work you came back to twice was two notes, and the first one was a note about a
+conversation nobody could remember.
+
+Now a story keeps **every session it has had**, one at a time, over as long as it takes. And it
+carries two different clocks, which used to be one column fighting itself:
+
+- **the story's state** — `Backlog` · `Discussed` · `Planned` · `Working` · `Review` · `Done` —
+  which is where the *work* is;
+- **the session's status** — working, planning, holding a plan up, asking you something, your turn
+  — which is what a *terminal* is doing this second.
+
+No transition is required. Any state may follow any other, and `Backlog` straight to `Done` is a
+legal thing to do that nothing will warn you about — a backlog that argues with you about the road
+is a backlog you route around. `Working` sets itself when a session goes live. `Review` is where
+`/k0-verify` puts a story when it starts checking it. **`Done` is only ever yours**: nothing in k0
+sets it, and the Done button on the note is still what confirms it.
+
+The post-it itself still draws one word and one colour, exactly as before — the two clocks put
+back together. Nothing about the board you know got louder.
+
+### Rounds, and why they say how many are left
+
+A round is one small group of questions — four at the most — with your answers written down before
+the next one is asked.
+
+Each round opens by saying where it is: **"Round 3 of about 8"**. The number comes from counting
+the things where a different answer would produce different work, and it is recalculated after
+every answer, because answers both close questions and open them. When it moves, it says so in the
+same breath — *round 4 of about 6, two of the questions answered themselves* — and never drifts in
+silence. A count that quietly becomes twelve after promising eight is a count you stop believing,
+and once you stop believing it you start answering to get it over with.
+
+It stops when no remaining question would change the work, which is stricter than it sounds and is
+the only test being applied: a question worth asking is one whose two answers lead to two different
+builds. There is a hard ceiling of **fifteen rounds**. At fifteen it stops wherever it is, shows
+you the list of what it never got to in your own words, and says the story is recorded as it stands
+and can be picked up whenever you like. A discussion that reaches fifteen is telling you the story
+is really two, and it says that as well.
+
+**Every round is written to k0 before the next question is asked.** Not at the end, not on a save.
+A terminal that dies at round three does not take the first three with it, and neither does a
+session that runs out of context in the middle — which is the one that actually happens, and the one
+nobody thinks about until the second time.
+
+### Decisions
+
+What comes out of the rounds is not a summary. It is a row of **decisions**, one complete sentence
+each, numbered — `D1`, `D2` — and written in your language, about behaviour rather than about
+implementation. A decision that names a function is one you cannot check without opening the code,
+and six months from now you will not open the code.
+
+A decision is **never rewritten**. When you change your mind, the new decision *supersedes* the old
+one and both stay, the old one crossed through and pointing at what replaced it. This is the whole
+reason they are objects and not paragraphs: the point is to hold the work up against what was
+actually said at the time, and prose you can edit afterwards proves nothing.
+
+An epic's decisions belong to the epic, and every story under it **inherits** them rather than being
+handed a copy. They are shown with the epic's key in front — `K7·D3` — so it is obvious a rule came
+down from above and applies to everything in the lane. Inheriting rather than copying is what makes
+changing your mind work: supersede `K7·D3` on the epic and it is superseded for all eleven stories
+at once, where eleven copies would have forked the first time one of them was touched.
+
+An epic is discussed and decided before a single story of it exists, which is why its decisions
+have to be able to live on the epic. That is not a detail: it is the main way anybody uses this.
+
+And when something you say now contradicts something you settled earlier, the discussion **stops
+there and asks** — naming the decision it clashes with, saying which of the two it thinks should
+stand, and why. Writing both down and carrying on is how you end up with two rules that disagree
+and no way of knowing which one the work followed.
+
+### The counter-check
+
+Here is what this is for.
+
+You explain a piece of work to a model, properly, for half an hour. It asks good questions — some
+of the answers surprise you, because you did not know what you wanted until it asked. It says it
+has understood, and it has: the summary it gives back is better than the one you would have
+written. Then it builds something that quietly contradicts half of it. Not all of it, and not
+obviously. One thing you settled at minute twenty is simply not there, and something you ruled out
+is there instead. You notice three days later, and by then you cannot even prove you said it.
+
+That half hour did not merely fail to help. It cost you the half hour and it bought a false
+confidence that the thing was understood, which is worse than knowing it was not, because you
+stopped watching.
+
+`/k0-verify` is the thing that was missing. When the work is done it takes the decisions **one at a
+time** — the story's own and the ones it inherited — and records a verdict for each: **kept**,
+**violated**, or **not applicable**, with the evidence. A file and a line, or a sentence saying why
+the decision does not apply here. Never a summary standing in for the row, because a summary is
+where the one that was broken goes to hide.
+
+Three rules make it worth something rather than a ceremony:
+
+- **A run is the whole set or it is not a run.** One that answers nine decisions of ten is refused
+  and told which one it passed over. `na` is a verdict; silence is not. A check that reports a
+  clean sweep of whatever it happened to look at is worse than no check.
+- **A run never overwrites the one before it.** Runs are numbered and they all stay, so you can see
+  that something was broken, then fixed, rather than only that it is fine now.
+- **A story cannot be marked `Done` while a decision a run found broken has not been answered
+  since.** It is read decision by decision and not run by run: a later run that finds the same
+  decision kept closes it, and a later run that says nothing about it, or says it does not apply,
+  leaves it exactly where it was. This is the only refusal in the whole feature, and it applies to
+  whatever is asking: the Done button on the note, the one at the end of a row in the list, a
+  command. It comes back as a sentence saying which decision, from which run, and what to do about
+  it.
+
+There are exactly two ways to answer it, and both are honest: **put the work right and run the
+counter-check again**, or **supersede the decision** if it turns out the decision was the thing that
+was wrong. What you cannot do is talk past it: a story with a broken decision is drawn on the board
+so that it cannot be scrolled past, and pressing Done on it comes back with the sentence rather than
+the story closed.
+
+There is also a **checklist** on the story — what has to be true for it to be finished. `/k0-verify`
+does itself everything a machine can do, runs the project's tests, drives the browser when the thing
+is a web application, and leaves you only the lines that genuinely need a person.
+
+### `/k0-work` and the worktree
+
+`/k0-work` gives the session a working copy of its own: a git worktree under
+`<repo>/.claude/worktrees/`, on a branch named after the story, opened **from the branch you are
+standing on** — not from `main`, not from `origin`. You keep working in the repository, the session
+works next door, and at the end its branch comes back in as one merge commit and the copy is
+destroyed. The folder is kept out of git's way through `.git/info/exclude`, never by writing in
+your `.gitignore`.
+
+Everything the board starts opens in the story's **own repository**, never in a worktree. `/k0-work`
+makes one when it needs one, and it is the only command here that does: the others talk about the
+story rather than change it, and a discussion held inside somebody else's working copy is a
+discussion about a copy.
+
+It will not open one over uncommitted work, and it says how much there is. And three things it
+never does, each of which has already cost somebody a day:
+
+- **It never pushes and never opens a pull request.** The merge stops on this machine. Publishing
+  is a decision you make when you are ready to make it.
+- **It never resolves a conflict.** There is no way for a program to tell a conflict it resolved
+  correctly from one it resolved plausibly, and taking a side to make the command succeed throws
+  away something somebody typed. A conflict stops everything and says which files.
+- **It never runs tests, a build or a dev server in there.** A worktree copies the code but not the
+  untracked files around it, so the `.env` somebody copies across carries the *base* repository's
+  port — and a test runner that finds a server already listening on it uses that one, goes green,
+  and tells you the new code passes when what it tested was the old checkout. Tests run on the base
+  branch, after the merge.
+
+That last rule has one honest edge. Merging commits whatever the session left pending, a commit
+runs your repository's own hooks, and a `pre-commit` hook that runs the whole suite is normal. k0
+does not step round it with `--no-verify` — a commit that only went through because k0 avoided your
+hooks has not been checked at all — so the hook does run, next door, with the wrong `.env` beside
+it. k0 says so when it happens rather than being quiet about it.
+
+### `/k0-ultracode`: the same work, with a manager over it
+
+On a note that is ready to be worked on, next to **Work**, there is a quieter word: **Ultracode**.
+It is the same act at a larger size. One session becomes a **manager**: it cuts the story's plan
+into **assignments**, gives each one to an **agent** working in a copy of the repository of its own,
+brings the work back one piece at a time, and only then — on your branch, where the code on the disk
+is the code that was merged — runs the tests, has the result read by an agent that wrote none of it,
+and walks the story past every decision. It is offered on an epic too, from the epic's panel, and
+that is what it is really for: story after story, each one finished before the next one starts.
+
+Before it does anything it asks you two questions and never asks again. **How much rope** —
+*interactive*, where every question an agent brings back reaches you while it is warm; *checkpoint*,
+which stops at the cut, before the merge and on a red test run; or *autonomous*, which goes to the
+end and comes back with the list of everything it decided on your behalf. And **how hard** — two,
+three or five agents at a time, one repair attempt or two, one pair of fresh eyes or three. Both
+answers go into the Log, so a terminal you closed halfway through is picked up again on the same
+terms rather than on new ones.
+
+What it does not do is the point of the shape. It never pushes. It never runs anything inside a
+worktree, for the reason above. It never presses **Done** — the stories come back sitting in
+`Review`, counter-checked, waiting for you. And it stops: the repair attempts are spent and then it
+tells you what is still broken, having merged everything that works. A run that never ends is not
+thoroughness, it is a run nobody can plan around.
+
+### The `.k0/` folder
+
+Each repository with a backlog grows a `.k0/` folder: a `README.md` explaining itself, one file per
+epic under `epics/`, one per story or task under `stories/`. A story file opens with its header —
+key, epic, state, flag, what it waits on, the sessions it has lived through — and then
+**Why**, the **Prompt**, the **Discussion** round by round, the **Decisions**, the **Plan**, the
+**Verification** run by run with its checklist, and the **Log**. An epic's file is the same header,
+its own **Why**, **Discussion** and **Decisions**, and then the list of its stories with a line
+saying how far it has got.
+
+The database is the source of truth and these are printed from it — whole, every time the story
+changes, never diffed cleverly — so a file cannot end up claiming something the board does not. But
+they are files, so they diff, they review, and they go in the commit with the work they describe.
+Write in them if you like: anything you put under a heading k0 does not print is left exactly where
+you put it, and so is a line you add to the header at the top and a note you leave under the title.
+
+**Commit the folder.** It is the only copy of this that outlives the database, and it is the way
+back: open a repository k0 has no stories for and it reads the folder in and rebuilds them, keys
+and all. That is the reason the files exist at all — the rest is a pleasant side effect.
+
+The folder is written **only** inside `.k0/` — never your `.gitignore`, never a line anywhere else
+in your repository — and a test walks the tree afterwards to prove nothing else appeared. The one
+other thing that ever writes into a repository is `/k0-work`, which you have to ask for: it is
+written out in full under [What it reads, and what it never
+does](#what-it-reads-and-what-it-never-does).
+
+One thing to expect: the git mark on that column will go from a tick to a dot the day the folder
+first appears. That is honest — there is something there that is not committed yet — and committing
+it puts the mark back.
+
+### Switching it off
+
+The whole feature is one line in `~/.k0/config.json`, the same file the idle timeout lives in:
+
+```json
+{ "backlog": false }
+```
+
+and the board is exactly the board it has always been: nothing extra on a note, no next-step
+button, no Kanban/List switch in the bar, no lanes, **no `.k0/` folder created in any repository**,
+and the commands say plainly that the backlog is switched off rather than reporting an empty one.
+Telling somebody their backlog is empty when it is really turned off is the one answer worse than
+no answer. The `+` goes back to being a plain `+` that opens the story dialog, with no menu behind
+it and no epic on the form.
+
+It is in that file and not in k0's database on purpose: a switch you would need `sqlite3` to reach
+is not a switch. k0 re-reads the file whenever it changes, so nothing has to be restarted, and
+deleting the line puts the default back. `"updateCheck": false` is its neighbour — [the one that
+stops the npm question](#what-installing-it-changes).
+
+---
+
 ## The ChangeLog
 
 The git mark answers "is this safe" for one repository, right now. The **ChangeLog** answers a
@@ -359,7 +864,7 @@ page that comes up empty after every weekend is a page you stop opening.
 **Only what you touched in that window appears.** A repository that has been dirty since March
 and that you have not opened since is not news, and a summary that repeats it every morning is
 one nobody is still reading by Thursday. Something has to have happened there — a commit, a file
-saved, a card moved — before k0 will tell you what is still outstanding in it. And only **your**
+saved, a story moved — before k0 will tell you what is still outstanding in it. And only **your**
 commits are counted: k0 asks git which email you commit with in that repository and shows that
 person's day, so a repository shared with other people still tells you about yours.
 
@@ -369,9 +874,10 @@ not believe the paragraph above it.
 
 ### Who writes it
 
-k0 does not. **k0 makes no network requests**, and that is worth more than a better paragraph: a
-model of its own would mean a key to keep, an account to configure, and your commit messages
-leaving this machine.
+k0 does not. **Nothing about your work leaves this machine**, and that is worth more than a better
+paragraph: a model of its own would mean a key to keep, an account to configure, and your commit
+messages going out over a wire. The one request k0 makes is to the npm registry, asking after its
+own version; it carries no commits, no repository names and no identifier.
 
 It does not need one. If you are running k0 you already have Claude Code installed, signed in and
 paid for — that is the whole point of the board — so the model is already here. k0 works out the
@@ -380,7 +886,7 @@ on the board, and there is nothing to set up: the skill that does the writing sh
 package, the same way `/k0-import` does.
 
 It is written **in your language**, without a setting anywhere, because it is written out of your
-own commit messages and card titles.
+own commit messages and story titles.
 
 Nothing is saved. Every time you open the page it is written again, and changing the window
 writes it again — which is why there is no stale summary to clear and no history to prune.
@@ -390,20 +896,142 @@ saying why the rest is missing.
 
 ---
 
+## What's New
+
+k0 updates by having its files replaced under it. You restart, everything looks the same, and
+whatever changed is in a file called `CHANGELOG.md` that nobody opens. So the version you are
+running drifts away from the one you learned, and the new thing sits there unused because you
+never found out it was there.
+
+A small **mark appears next to `k0`** in the top bar for exactly two reasons: k0 moved on while you
+were not looking, or npm says there is a version newer than the one installed here. Hover it and it
+says which. **It never opens the page by itself** — it sits next to the name and waits, and it goes
+out when you have read the page, not when you close the tab.
+
+The page says which two versions it stands between — *you had k0 0.3.1, you are running 0.4.0 now,
+two versions later* — and then says what that means in prose, written by your own Claude out of the
+changelog entries in between. Two controls, and both of them change who it is being written for
+rather than what is in it: **the language**, and **how technical** — `Plain`, `Normal` or `Nerd`.
+Both are remembered, because coming back to find the page in a language you do not read is the
+whole page wasted.
+
+Underneath, folded open from the first moment, are the changelog entries themselves, exactly as
+they were written. While the prose is being written they are what there is to read; afterwards they
+are what you check it against.
+
+It is the same machinery as the ChangeLog, and it has the same shape: nothing is stored, no model
+of k0's own, no key and no account — the Claude Code you already pay for does the writing, on this
+machine. Nothing is downloaded either. k0 cannot update itself; the most it can do is say a newer
+version exists, and leave `npx k0-board@latest` to you.
+
+---
+
+## Usage: what your sessions consumed
+
+The icon with three bars, next to the ChangeLog's, opens a page that answers a question Claude Code
+leaves you to guess at: **where did the week go?** You switch between models, between efforts,
+between one agent and a whole workflow, and between accounts, and the only thing you ever see is a
+limit arriving.
+
+A week at a time, Monday to Sunday, with the arrows to go back:
+
+- **what each day would have cost at the API price list**, stacked by model. With a subscription
+  you do not pay this — it is the one scale on which a Fable hour and a Sonnet hour can be put side
+  by side, and the page says so;
+- **how full each account's weekly limit was**, as a line per account, and the five-hour limit as
+  it was last seen;
+- the week split **by model and effort** (fast mode is a row of its own), by **who did the work** —
+  the conversation itself, its subagents, or a workflow's agents — by **repository** and by
+  **account**;
+- and every **session**, the most expensive first: the model and effort it ran on, when it started,
+  how long Claude actually worked on your turns (not how long the window was open), its tokens, its
+  cost, its estimated share of the weekly limit, and how many times a limit stopped it. A session k0
+  started or imported links to its story, which opens on the board.
+
+**It costs nothing to find out.** No model is asked and nothing goes over the network: Claude Code
+already writes every reply's token counts, model and effort into the transcripts on your disk, and
+k0 reads them as they grow — the history first, a few megabytes at a time so the board never
+stalls, and after that once a minute. The first time, the page says how much history is still left
+to read.
+
+Two things are not in the transcripts, and the page is straight about both:
+
+- **Which account a reply came from.** Claude Code only records the account signed in *now*. k0
+  writes down every change of account it sees from the moment it is running, and the statusline
+  snippet below writes down the account of every session it draws. Everything before that stays
+  **"Unknown account"** — it is not guessed.
+- **How full the limits are.** Claude Code tells the statusline and keeps it nowhere else. So the
+  statusline has to write it down:
+
+### The limits: a few lines in your statusline
+
+If you have a statusline command, add this to it, where it has read Claude Code's JSON from standard
+input into `input` (Node, no packages; the same idea works in any language). It appends a line to
+`~/.k0/usage/limits.jsonl` only when a number has changed, and never breaks the bar if anything
+fails:
+
+```js
+try {
+  const fs = require('fs'), path = require('path'), os = require('os')
+  const data = JSON.parse(input), rl = data.rate_limits
+  if (rl && (rl.five_hour || rl.seven_day)) {
+    const pick = (w) => (w ? { pct: w.used_percentage, resets_at: w.resets_at } : null)
+    const now = { five_hour: pick(rl.five_hour), seven_day: pick(rl.seven_day) }
+    const dir = path.join(os.homedir(), '.k0', 'usage'), seen = path.join(dir, '.last')
+    const sig = JSON.stringify([data.session_id, now])
+    let last = ''
+    try { last = fs.readFileSync(seen, 'utf8') } catch {}
+    if (sig !== last) {
+      const a = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8')).oauthAccount || {}
+      const account = { uuid: a.accountUuid, email: a.emailAddress, org_type: a.organizationType, tier: a.organizationRateLimitTier }
+      fs.mkdirSync(dir, { recursive: true })
+      fs.appendFileSync(path.join(dir, 'limits.jsonl'),
+        JSON.stringify({ at: Date.now(), session_id: data.session_id, account, model: data.model?.id, ...now }) + '\n')
+      fs.writeFileSync(seen, sig)
+    }
+  }
+} catch {}
+```
+
+Claude Code only passes the limits to the statusline on a subscription, and only after the first
+reply of a session. Without the snippet the page works the same, with the limits chart empty and a
+note saying why.
+
+The share of the weekly limit next to each session is an **estimate**, and marked with `≈`: the
+statusline says how full the week is, not who filled it, so each rise is shared among the sessions
+that account ran in that hour, in proportion to their cost.
+
+The prices are Anthropic's published API rates, dated in the source. A model k0 does not have a
+price for is counted in tokens and shown as `?` in dollars — never as free.
+
+---
+
 ## The files of a session
 
 The git mark is also the door: clicking it opens a file viewer **in another tab**, and the board
 stays where it is. Where there is no mark — a repository without git, or git that has not answered
-yet — a **lens** takes its place, so every card and every column still leads in.
+yet — a **lens** takes its place, so every story and every column still leads in.
 
 Files on the left, what they say on the right, and a divider in between that you can drag.
 
-**Only documents are listed** — markdown, html, text, PDF, Word: things you read and print. In a
-real repository code is 95% of the files, and among two thousand `.tsx` files the document you
+**Documents are what is listed** — markdown, html, text, PDF, Word: things you read and print. In
+a real repository code is 95% of the files, and among two thousand `.tsx` files the document you
 were after cannot be found. This closes nothing off: a code file reached by a link inside a
-document still opens, and so do images.
+document still opens, and so do images — and the configuration is one switch away, below.
+
+A **generated directory** — `out/`, `dist/`, `build/` — is walked into like any other, and the
+documents in it are listed like any others: the PDFs, and the pages you open with a double click.
+A document is a document wherever it was made, and it has to be findable by name. What stays out
+is the configuration a build leaves lying there, and the directories that hold nothing anybody
+reads — `node_modules` and its like — which are not walked into at all.
+
+There is **one exception, and only one**: where git is in charge, git decides. k0 reads a
+directory your `.gitignore` names only to go and fetch the finished documents from it — the PDFs,
+the Word files — never the pages, because a real site's ignored `dist/` is four thousand pages and
+not one of them is the file you went looking for. Where git names the directory itself, everything
+in it comes through, pages included.
 
-The listing is flat, in three groups:
+At the top come the **folders**, then the files, in three groups:
 
 - **Changed** — what this session has touched: files still hanging in the working tree plus the
   ones inside commits made since it started.
@@ -411,19 +1039,91 @@ The listing is flat, in three groups:
   no git.
 - **All files** — everything else, in path order.
 
+### Searching
+
 The search at the top looks in two places and keeps them apart:
 
-- **Names** — not the exact word, but the letters you type in the order you type them: `audrep`
-  finds `docs/audit-report.md`. It filters as you type, asking the server nothing.
+- **Names** — not the exact word, but the letters you type in the order you type them, **inside
+  the file's own name**: `audrep` finds `docs/audit-report.md`. It filters as you type, asking the
+  server nothing. The directory is never searched — it used to be, and `.env` would turn up a
+  `v1.0-ROADMAP.md` that merely had those four letters scattered across its folder, three of them
+  in a name nobody was reading. The letters that matched are **underlined**, so every row says why
+  it is there: `aud`it-`rep`ort reads as the two words you meant.
 - **In the text** — inside the documents, with the line the word appears on and the word
-  highlighted. Because what you remember about a file is what was in it, not what it was called.
-  Accents do not need typing — `cafe` finds `café`.
+  highlighted in yellow. Because what you remember about a file is what was in it, not what it was
+  called. Accents do not need typing — `cafe` finds `café`.
+
+The two marks are different on purpose: a line under the letters means they are in the file's
+name, yellow means the word was found inside the file.
 
 There is no index. The documents are read every time: a few hundred files of a few KB, all
 already in the operating system's cache. An index would cost more and go stale.
 
 `/` puts the cursor in the search, arrows scroll, Enter opens, Esc clears.
 
+### Going into a folder
+
+Click a folder and the listing narrows to it: the folders inside it first, then its files. At the
+top the path is written out one piece at a time, and **every piece is a way back up** — from
+`docs/backlog/handover` you get to `docs` in one click, and to the whole repository by clicking
+the repository's name. The path above an open document works the same way, so from a file you can
+step into the folder it lives in.
+
+The arrows walk folders like anything else and Enter goes in; Esc comes back out. A folder is a
+real link, so ⌘/Ctrl-click opens it in another tab, and the address follows you: reload it and
+you are still where you were.
+
+Next to it is a button that hands the folder to your **file manager** — the Finder on a Mac,
+Explorer on Windows, whatever your desktop uses on Linux. Every file has the same button in the
+row above it, and there it points the file out inside its folder rather than opening it. On a
+system where k0 has no way to do that, the button stays where it is, greyed out, with the reason
+in its tooltip.
+
+### The `config` switch, beside the search
+
+The viewer lists documents. The one thing that was missing from that is **configuration**: an
+`.env` you want to check a key in, the `package.json`, a workflow's YAML. They are not documents,
+and in a repository of prose they would be noise — so they live behind a switch, the **`config`**
+button to the right of the search box.
+
+Switch it on and `.env` (and `.env.local`, and the rest of them), `.json`, `.yml`, `.yaml`,
+`.toml` and `.ini` join the listing, the name search and the search inside the text. **Including
+the ones git is told to ignore** — an `.env` is ignored by definition, and it is the file you came
+for. Code does not join: `.js`, `.py`, `.css` stay out either way.
+
+The switch is remembered, per browser. It is not a search, it is a way of working.
+
+And if you forget it is off, the search says so: when a hidden configuration file would have come
+**above** everything on screen — searching `.env` in a repository that has one — a line appears at
+the top of the results saying how many, and clicking it turns the switch on. Only then: a hidden
+file that merely matches somewhere does not raise it, or the line would be there on every search
+and you would stop seeing it.
+
+Each of them opens as the kind of thing it is:
+
+- a **JSON** file becomes a tree that folds, coloured by type, with the first two levels open;
+- an **.env** becomes a table of names and values, comments and all;
+- **YAML, TOML and INI** keep their shape, with keys, values and comments told apart by colour.
+
+A JSON tree has its **own search box**, and that is not a duplicate of the browser's: the
+browser's find does not look inside a branch that is closed, so on a folded tree ⌘F says "not
+found" for something three lines away. This one counts what it found and opens the branches
+holding it.
+
+### Editing a file
+
+Configuration and notes can be changed from here: `.env` and the rest of the configuration above,
+plus `.md` and `.txt`. Click the **pencil** in the row above the document and the file becomes a
+text box as tall as the pane — not a small window over it, because a README does not fit in one.
+**Save** (or ⌘/Ctrl+S) writes it; **Cancel** goes back to what is on disk.
+
+Nothing else is editable: no code, no PDFs, no images, and no creating or deleting files. That is
+what you opened the repository with Claude for.
+
+If the file **changed on disk** while you were editing — a session wrote it, or you did, in
+another window — the save stops and says so, and what you typed stays where it is. k0 will not
+quietly write over somebody else's work.
+
 ### Pasting a chunk of chat
 
 There is a way to reach files that does not go through searching for them. When a session ends,
@@ -431,9 +1131,14 @@ the summary in the chat says what it touched and **names the files already**. Cl
 the top, paste that piece of conversation, press **Find the files**, and the list on the left
 narrows to the files that text names.
 
-It looks **only for the names written down**, not for the subject: no index, no server, no
-waiting — the file listing is already in the browser. The price is stated: a file the chat talks
-about without ever naming does not come out, and for that there is the search above.
+It looks **only for the names written down**, not for the subject: no index and no waiting — the
+file listing is already in the browser. The price is stated: a file the chat talks about without
+ever naming does not come out, and for that there is the search above.
+
+One question does go out, and only one: when the text writes a name **in full** and the listing has
+no such file, the disk is asked about those names and no others. That is how a document under an
+ignored directory comes out of a paste — the listing never saw it, but a text naming a file names
+it whole.
 
 The results come in two groups, because they are two different degrees of certainty:
 
@@ -464,10 +1169,45 @@ The hard part is not finding the names, it is choosing **which**. In a repositor
 directory up, and so on to the top. If it is still ambiguous, **it does not become a link**:
 better nothing than sending you to the wrong README.
 
-Files the listing does **not** show open too. `out/`, `dist/`, `node_modules/` stay out of the
-listing — in a code repository they are generated — but in a directory of documents `out/` holds
-the real PDFs. When it is a document naming them, that file counts. Hidden directories really do
-stay out: `.claude/` is configuration, not something to read.
+Files the listing does **not** show open too. Where git rules, a directory your `.gitignore` names
+gives the listing only its finished documents — so a page under an ignored `dist/` is not in it.
+Named inside a document it still counts: the document said so, not the directory. Hidden
+directories really do stay out: `.claude/` is configuration, not something to read.
+
+### What Claude points at, one click away
+
+The same idea, one step earlier: in the Claude Code session itself. Claude says "open
+`localhost:4321/projects/furniture/`", "the photos are in `docs/projects/sideboard-140/`", "the
+manual is `README.md`", or publishes an artifact and talks about it by its title — and in the
+terminal all of that was dead text. With the `k0-links` mod installed, and **while k0 is running**,
+everything the last reply pointed at is in a row **just above the prompt**, and **one plain click**
+on an entry opens it:
+
+| | What the reply wrote | Opens in |
+|---|---|---|
+| 🌐 | an address — `https://…`, `localhost:4321/…`, `alessioragni.com/projects/…` | the browser, in a new tab |
+| 📁 | a folder, relative to the repository or written in full | Finder |
+| 📄 | a document the viewer shows — Markdown, HTML, text, PDF, Word… | this viewer, in a new tab |
+| ✦ | the title of an artifact this session published | its claude.ai page |
+
+Code files and a repository's own name stay out of the row: they are not places you go to. A
+domain counts as an address only with a path after it — `alessioragni.com` alone is usually the
+name of a repository.
+
+**Claude's reply is left exactly as Claude Code draws it.** The macOS Terminal cannot open a link
+drawn inside the text — it shows the words, and a click does nothing — and redrawing every reply to
+get around that would have changed a screen that works. The row is the mod's own space, and its
+entries are buttons, which Claude Code itself receives the click for. That needs Claude Code's
+**fullscreen** view (`"tui": "fullscreen"` in `~/.claude/settings.json`, or `/config`), where the
+mouse reaches it; in the classic view the row is still there, and ctrl+x tab then Enter opens an
+entry.
+
+It is a **mod**, a small piece of code Claude Code runs inside itself, and the installer copies it
+into `~/.claude/skills/k0-links` together with the commands, behind the same question. So it is
+there in **every** Claude Code session on the machine, not only the ones a story opened — new
+sessions pick it up when they start, an open one with `/reload-plugins` — and it does nothing at
+all while k0 is off. Documents become entries only in **a repository k0 knows**; elsewhere the
+addresses, folders and artifacts still do.
 
 ### On paper
 
@@ -493,11 +1233,11 @@ kernel's own verdict, plus one added rule: amber when memory in use goes over 90
 the whole picture, including **what is heavy and is not k0**: if the machine is struggling because
 of Chrome it is fair to know that, instead of closing sessions for nothing.
 
-On every card there is **what that session weighs**. Not the `claude` process: everything it has
+On every story there is **what that session weighs**. Not the `claude` process: everything it has
 dragged along — the MCP servers, the Chromes they open, a `tsc` started from a commit hook. That
-is where the memory goes, and it is the thing no other tool can attribute to the right card.
+is where the memory goes, and it is the thing no other tool can attribute to the right story.
 
-Only one card is red, the heaviest, and only while the machine is struggling: if they were all
+Only one story is red, the heaviest, and only while the machine is struggling: if they were all
 red they would say nothing.
 
 Two things said plainly. The CPU is the CPU of **right now**, worked out from the difference in
@@ -506,7 +1246,7 @@ which on an old session says nothing about this minute. And summing the memory o
 counts shared memory twice, so the total is a little generous: it is the usual approximation, and
 it is the right one for the question that matters — which one do I close to feel better.
 
-And once you have decided, **`Close` on that card is how you give the memory back**: the session
+And once you have decided, **`Close` on that story is how you give the memory back**: the session
 is stopped and its window goes, the work stays on the board as it was, and `Resume` picks the
 conversation up where it left off. Nothing has to be declared finished to stop weighing.
 
@@ -514,6 +1254,40 @@ Reading the process table costs little on a calm machine and a lot on a struggli
 exactly when you look at it. So it is sampled every three seconds, and **only while the board is
 open**.
 
+### And what k0 costs
+
+The chip measured everybody but itself, which is the one thing a program running under launchd for
+weeks should be least able to hide. Hover it and the last line is **k0's own weight, its CPU, how
+often it asks git anything, how many queries it is holding, and how hard the watching loop is
+currently running**.
+
+That loop is the whole of k0's cost, and it now runs at the pace the work deserves. With a session
+open — or with you in front of the board — it goes round every two seconds. With neither, there is
+nothing it could see change, so it drops to **once a minute** and k0 stops costing anything on a
+machine nobody is using. Pressing anything wakes it at once, so nothing ever waits on it.
+
+The git marks follow the same rule. Every repository on the board used to be asked `status` and
+`rev-list` every five seconds, all night; now the full list is only asked while you are looking,
+away from the board only the repositories a session is actually working in, and a reading is good
+for half a minute. Nothing in a repository changes faster than that unless you make it.
+
+### And what the page downloads
+
+The other half of the bill is paid by the browser, and it was the larger one. The board asked for
+everything k0 knows once a second and got it: two thirds of a megabyte, six hundred stories with
+their whole "Why" and their whole plan, most of them finished weeks ago and hidden from view. Over
+a day with one tab open that came to **fifty-six gigabytes**, to draw post-its that had not moved.
+
+Now the board sends back a stamp of the answer it already has, and when the answer would be the
+same — which on a board nobody is touching is every round of every day — the server says so in a
+couple of hundred bytes and sends nothing else. When something really did change, what goes out is
+only what a post-it draws, compressed. The long texts come with the story's own panel, when you
+open one, where they were always read from anyway.
+
+A still board also stops asking so often: after a few rounds saying nothing moved it drops to one
+in four seconds, and the first thing that moves — or your coming back to the tab — puts it
+straight back to one.
+
 ### And the ones you forget, k0 closes for you
 
 The paragraph above assumes you noticed. Most of the time nobody does: the window that is costing
@@ -521,7 +1295,7 @@ you a gigabyte is the one you stopped thinking about yesterday. So **after twelv
 nothing happening, k0 does that `Close` itself** — the session is stopped, its window goes, and the
 memory comes back.
 
-Nothing is lost by it. The card stays exactly where it is with the status it had, and **Resume**
+Nothing is lost by it. The story stays exactly where it is with the status it had, and **Resume**
 picks the conversation up where it was. That is the whole reason this is safe: a closed terminal
 has never been a lost session.
 
@@ -537,12 +1311,12 @@ rest is left alone, and each for its own reason:
   there may be a command of yours running in it; k0 cannot see what it is, so k0 does not touch it.
   On the board it reads as yellow like any other, which is exactly why this one has to be said.
 
-And a window you were using an hour ago is never closed, whatever the card's history says. k0 has
+And a window you were using an hour ago is never closed, whatever the story's history says. k0 has
 four clocks for a session — two of its own and two Claude Code keeps — and **the newest one wins**.
 Being wrong in that direction leaves a window open until tomorrow; being wrong the other way closes
 a terminal you were about to go back to.
 
-A card k0 tidied away says so: where one you closed yourself reads *session closed*, this one reads
+A story k0 tidied away says so: where one you closed yourself reads *session closed*, this one reads
 *closed automatically*. Same italic, same place, one word different.
 
 And the memory chip at the end of the top bar says it is watching, and from when: **RAM 79% · CPU
@@ -561,17 +1335,17 @@ settings file changes it, and **`0` switches it off** — see below.
 
 An empty board is no help in getting your bearings. The installer offers to do this on the first
 run; afterwards, `/k0-import` from a Claude Code session picks up the sessions that already
-happened — including the ones opened by hand, outside k0 — and puts them on the board as cards:
+happened — including the ones opened by hand, outside k0 — and puts them on the board as stories:
 the last 14 days, at most the 10 most recent per repository. `/k0-import 30 5` changes the two
 numbers.
 
 The difference between the two is the writing. The installer uses the name the session already
 had, or the first few words of the first prompt. `/k0-import` has Claude read the conversation and
 write a title and a description in the language it was held in. That description is the line in
-italics under the title on the note, and importing is the only thing that writes one: a card you
+italics under the title on the note, and importing is the only thing that writes one: a story you
 write yourself has a title and a prompt, which is all it needs.
 
-Imported cards are born yellow — *Your turn*: **Resume** reopens the conversation where it was,
+Imported stories are born yellow — *Your turn*: **Resume** reopens the conversation where it was,
 **Done** clears it away. Being dead sessions they do not light the tray icon. Running it again
 skips the ones already imported.
 
@@ -584,8 +1358,12 @@ real machine that separated 145 genuine sessions from 867 automated ones, and it
 
 ## The statuses
 
-A card **is** the colour of its status — there is nothing else to read. On the left is the code in
-the database, then how it reads on screen.
+A story **is** the colour of its status — there is nothing else to read. On the left is the code
+k0 speaks internally — the API, the menu bar icon and the colours in `web/base.css` all say these
+seven words — then how it reads on screen. None of the seven is a column in the database: `BACKLOG`
+and `COMPLETED` are worked out from the story (no session, and closed), and the other five belong
+to the live session, not to the story. See [`docs/database.md`](docs/database.md) for where each
+half really lives.
 
 | | | | |
 |---|---|---|---|
@@ -607,12 +1385,12 @@ How awake the machine has to stay while sessions are working. It is a **scale of
 four switches: each includes the one before it, and exactly **one** is always lit. Clicking the lit
 one again does nothing — you leave a mode, you do not switch it off.
 
-| Icon | Mode | The machine | The screen | The text |
+| Icon | Mode | The machine | The screen | The text and the windows |
 |---|---|---|---|---|
 | two **z** | **Sleep** | sleeps as it normally would | goes off | normal |
 | a **palm tree** | **Away** | does not sleep, not even with the lid closed | may sleep and lock | normal |
 | a **nerd face** with glasses | **Nerd** | does not sleep | **stays on** | normal |
-| a **car** | **Driving** | does not sleep | **stays on** | **large**, here and in the terminals |
+| a **car** | **Driving** | does not sleep | **stays on** | **large**: the text here and in the terminals, and the terminals fill the screen |
 
 The four icons do not describe the machine: they describe **where you are**. Asleep, away, at the
 desk, watching from across the room. That is where the order comes from, and it is why the second
@@ -622,9 +1400,9 @@ one is a palm tree and not a technical symbol: the mode does not say "the machin
 The four buttons are at the end of the board's bar, or four ticked entries in the tray menu. They
 are the same control: changed on one side, the other catches up within a couple of seconds.
 
-**Nerd** and **Driving** do exactly the same things to the machine: the only difference is the size
-of the text. Nerd is "I am sitting here programming", Driving is "I glance at it from across the
-room".
+**Nerd** and **Driving** do exactly the same things to the machine: the only difference is how big
+everything is — the text, and the terminal windows it sits in. Nerd is "I am sitting here
+programming", Driving is "I glance at it from across the room".
 
 ### Why an idle inhibitor is not enough
 
@@ -648,7 +1426,7 @@ it does not do.
 no business rewriting behind your back. The switch reports itself unavailable, and `k0-board
 doctor` says where to change it yourself.
 
-### Large text, and windows that do not move
+### Large text, and windows to match
 
 In Driving the **text inside the terminals** goes from the profile's size to 22, the board's from
 17 to 22 pixels, and the **things you click** grow too — the `+`, the git lens, the corner pencil
@@ -660,16 +1438,27 @@ they reorder by urgency, reddest to the left. On a screen you glance at, two or
 visible at a time and the most urgent one has to come to you. Full screen you have them all in
 front of you already, and a board that reshuffles itself while you work only loses your place.
 
-**The windows do not move.** New ones are born centred at 86% as always; ones already open do not
-shift by a pixel — if you had dragged one to the other monitor, there it stays. Terminals already
-open change size **immediately**, not only the ones you open next.
+**The windows grow with the text.** In Driving a terminal takes the whole free screen; leave
+Driving and it goes back to the usual 86% centred, with the text back at the profile's size. It is
+one gesture and not two, and it lands on the terminals **already open**, not only on the ones you
+open next.
+
+It used to be the opposite, and the reason is worth keeping in mind: Terminal.app holds rows and
+columns when the font changes and resizes the window to match — going from 12 to 22 turns a 700×500
+window into 1378×856, measured — so k0 read each window's own bounds first and put them back, and
+nothing moved. What that left behind was a window holding 22 point text in a box measured for 12.
+Half a gesture is worse than none, so the size of the text and the size of the window now travel
+together, and the price is said plainly: **a window you had dragged onto another screen comes back
+to the middle of the main one.**
 
-That the window does not move **is not free**, and it is the least obvious part of this whole
-chapter: Terminal.app keeps rows and columns when the font changes and resizes the window to
-match — going from 12 to 22 turns a 700×500 window into 1378×856, measured. So the bounds are read
-first, the font is changed, and **its own** bounds are put back.
+**All of them, every time.** k0 asks Terminal once for the windows it has open and changes those
+that are its own, rather than asking after every window id it has ever written down. On a board
+with two hundred stories almost every one of those ids names a window closed weeks ago, and asking
+after them one at a time took seven seconds — long enough to be cut short halfway, which left half
+the terminals large, half of them small, and nothing said about it anywhere. Walking the windows
+that exist takes about a second and does not grow with the board.
 
-k0 touches **only its own windows**, the ones born from a card.
+k0 touches **only its own windows**, the ones born from a story.
 
 ### What it remembers, and what it looks at
 
@@ -758,7 +1547,7 @@ Worth knowing:
 
 Two side effects of the Cmd+V k0 uses to write your prompt, worth knowing:
 
-- the card's prompt replaces whatever was on your clipboard (if the paste fails, the clipboard is
+- the story's prompt replaces whatever was on your clipboard (if the paste fails, the clipboard is
   put back);
 - to paste, the terminal is brought to the front for an instant: if you happen to be **dictating**
   at that moment, the dictation lands in there and sticks to the prompt.
@@ -787,7 +1576,7 @@ itself on the next round: nothing to restart.
 
 | | |
 |---|---|
-| `closeIdleTerminalsAfterHours` | How long a yellow card's terminal may sit there before k0 closes it and gives the memory back. `12` if you say nothing. **`0` switches it off.** Anything under an hour is treated as an hour — below that this stops being a tidy-up and starts closing windows while you are using them. |
+| `closeIdleTerminalsAfterHours` | How long a yellow story's terminal may sit there before k0 closes it and gives the memory back. `12` if you say nothing. **`0` switches it off.** Anything under an hour is treated as an hour — below that this stops being a tidy-up and starts closing windows while you are using them. |
 
 Delete a line to go back to its default; a file k0 cannot read is ignored altogether and the
 defaults hold, rather than k0 refusing to start over a stray comma.
@@ -815,46 +1604,103 @@ platform/
   shared/        what more than one of them needs: tmux, running commands, reading a process
                  table, and reading who is holding which port
 server/
-  index.js       the http server, the API, and the watching loop that runs every second
+  index.js       the http server, the API, and the watching loop — every two seconds while a
+                 session is running or somebody is at the board, once a minute when neither, and
+                 awake at once on anything you press
   guard.js       who is allowed to talk to this server at all: the Host and the Origin
-  db.js          SQLite (node:sqlite): the card, session_event, pref and dev_server tables —
+  db.js          SQLite (node:sqlite): the only file that talks to it. epic, story, session,
+                 decision, round, check_item, dependency, session_event and the rest —
                  docs/database.md
+  backlog.js     the model: epics, stories, tasks, decisions, dependencies, the order, and
+                 what to pick up next. Pure logic over db.js — no http, no disk
+  mirror.js      writes and re-reads <repo>/.k0/, the readable copy of the backlog. It writes
+                 nowhere else, ever, and a test proves it. No domain logic
+  worktree.js    a session working copy of its own: open it from the branch you are on, merge
+                 it back, destroy it. Never a push, never a pull request, never a conflict
+                 resolved for you, and it never runs tests or a build in there
+  update.js      the one request k0 makes — what npm says the newest version is — and the
+                 version jump that puts the mark next to k0 in the top bar
   paths.js       where the board, the logs, the settings and the cache live
   settings.js    the few things you can change, and the file that is the list of them —
                  ~/.k0/config.json, written out with everything in it and re-read when it changes
   idle.js        which terminals have sat still long enough to be closed and given back. Only the
                  deciding: it kills nothing, so every rule in it can be proved without a machine
   watcher.js     reads Claude Code's own files and derives the statuses; also renames a session
+  usage.js       reads what every session consumed out of its transcripts, a few megabytes at a
+                 time and only what is new, plus the statusline's limit samples and which account
+                 is signed in; adds it up by the hour for the Usage page. Never asks a model
+  prices.js      the API price list the Usage page's dollars come from, dated; a model not on it
+                 has no price rather than a zero one
   git.js         the only one that talks to git: what is committed, what is pushed, whose it is,
                  and — for the ChangeLog — what the commits actually said
   changelog.js   gathers what happened in a window, out of git and out of session_event. Decides
                  which repositories are worth mentioning at all, and stores nothing
   writer.js      hands those facts to the Claude Code already on this machine and gets the words
-                 back. The only place k0 starts a model, and it never leaves the machine to do it
+                 back. The only place k0 starts a model, and it never leaves the machine to do
+                 it. Keyed by skill and by window, so the ChangeLog and the What is New page can
+                 be writing at the same time without cancelling each other
   launcher.js    starts and resumes sessions, through the platform's terminal
   servers.js     the dev server of a repository: what starts it, whether it is up, and on what
                  port. The only thing k0 starts that is meant to outlive k0
-  mode.js        the four modes: how awake to keep the machine, and whether the text goes large
-  projects.js    the repositories, in the order you last used them
-  sessions.js    digs already-lived sessions out of the transcripts, to import as cards
-  files.js       the only one that reads the projects' disk: what is there, what changed, what it says
-  machine.js     the only one that looks at processes and memory: what it all costs, and who is costing it
+  mode.js        the four modes: how awake to keep the machine, and whether text and windows go
+                 large. How large is `launcher.js`, which is what talks to the terminal
+  projects.js    the repositories, in the order you last used them — and which directories k0 is
+                 allowed to open at all, which is one answer and not one per endpoint
+  sessions.js    digs already-lived sessions out of the transcripts, to import as stories
+  files.js       the only one that reads the projects' disk — and the only one that writes back
+                 into it: what is there, what changed, what it says, and the one small write
+  machine.js     the only one that looks at processes and memory: what it all costs, and who is
+                 costing it — k0's own process included, which is the only honest way to publish
+                 a number like that
   pdf.js         the document on paper, printed by a headless browser
-web/             the three pages (html, css, js served exactly as they are)
+web/             the four pages (html, css, js served exactly as they are)
   index.html     the board — board.js, board.css, view.js. A note is never taller than it is
                  wide: the title, the age and the buttons always show, the text in the middle is
                  what gets clipped
+  list.js        the same stories as rows, list.css beside it: the other shape of the same page,
+                 not a page of its own. Handed the stories the board is already showing, so the
+                 filters cannot mean two things, and the story you open follows a live discussion
+                 by asking .../live once a second, the cadence the rest of k0 already uses
   files.html     the file viewer — files.js, files.css
-  changelog.html what you have been doing — changelog.js, changelog.css. The only page in k0 you
-                 read top to bottom instead of looking at, so it is the only one that scrolls
-  base.css       colours, fonts and scale: the house variables, shared by all three pages
+  changelog.html what you have been doing — changelog.js, changelog.css. Read top to bottom
+                 instead of looked at, so it is one of the three pages that scroll
+  whatsnew.html  what changed in k0 between the version you had and this one — whatsnew.js,
+                 whatsnew.css. Reached from the mark next to k0, and never opened by itself
+  base.css       colours, fonts and scale: the house variables, shared by all of them
+  awake.js       the one place that repeats anything: a job that runs only while its tab is in
+                 front of you, and takes a fresh reading the moment you come back to it. A page
+                 nobody can see must not be asking the server anything — asking is also how the
+                 server learns somebody is watching
   md.js          markdown laid out, written by hand because nothing here is compiled
   recency.js     which repositories are still warm, and which fold away into `Old`
-  fuzzy.js       searching the names: the letters you type, in the order you type them
+  fuzzy.js       searching the names: the letters you type, in the order you type them — the
+                 file viewer, the repository the new story goes in, and the repository menu on
+                 the bar, which is drawn here rather than left to the system
   mentions.js    which of a repository's files a piece of text names
   refs.js        what a name written inside a document points at, and which of the nine READMEs
+  json.js        a JSON file as a tree that folds, and the search that opens the right branches
+  conf.js        an .env as the table it always was, and YAML/TOML/INI with their parts told apart
 .claude/skills/
   k0-import/     the skill that fills the board with sessions you have already had
+  k0-epic/       the long way in: rounds of questions, decisions, then a tree of stories
+  k0-story/      one story, fast path, no ceremony
+  k0-discuss/    an existing story, discussed in rounds until nothing more would change it
+  k0-split/      a story too big to close, split into tasks that inherit its decisions
+  k0-plan/       plan mode, with the standing decisions injected as constraints
+  k0-work/       the worktree, the work, the Log as it goes, and the merge back
+  k0-ultracode/  the manager: a plan cut into assignments, an agent and a worktree each, and every
+                 story tested and counter-checked before the next one starts
+  k0-verify/     the counter-check: every decision one by one, the checklist, the outcome
+  k0-next/       what to pick up now, and why — the server decides, not the model
+  k0-order/      priority and dependencies, dictated
+  k0-links/      not a skill but a mod: hooks Claude Code runs inside itself. At the end of each
+                 reply it finds the addresses, folders and documents the reply named, asks the
+                 disk what each path is and k0, on loopback, which documents its viewer has
+                 (POST /api/files/exist), adds the artifacts the session published, and draws them
+                 as buttons in the row above the prompt; a press runs the system's `open`. It never
+                 touches the reply. links.js is the pure half, tested by npm test; nothing in it
+                 may come from k0's own folders, because it is copied out alone
+  k0-whatsnew/   the What is New page, written from the changelog entries k0 hands it
   k0-changelog/  the one that turns the facts of a stretch of work into something readable. k0
                  calls it by itself when the ChangeLog is opened, so it is in the package too
   changelog/     the one that writes the changelog and the documentation when work is finished.
@@ -863,7 +1709,9 @@ web/             the three pages (html, css, js served exactly as they are)
                  the road out: the documents, the tests, the commit, the push, and the tag that
                  publishes. Also for whoever works on k0, and also not in the package
 docs/
-  database.md    the shape of the database as it is now: the four tables, column by column
+  database.md    the shape of the database as it is now, table by table, column by column
+  method.md      why a decision has to be an object, what a round of questions is for, and
+                 what the counter-check is actually checking
   testing.md     how the tests are written, run and measured, and what is left untested on purpose
 test/            npm test — Node's own runner, no framework. See docs/testing.md
   harness.mjs    check(label, got, want), and the sections the labels are grouped under
@@ -871,21 +1719,52 @@ test/            npm test — Node's own runner, no framework. See docs/testing.
 
 ### What it reads, and what it never does
 
-k0 does not emulate a terminal and installs no hooks. It reads two things Claude Code already
-writes for itself:
+k0 reads your repositories. It writes into one in three places, and all three are named here
+because a tool that writes where you did not expect it is a tool you stop leaving running.
+
+The first is the pencil in the file viewer, on a configuration file or a note that is already
+there. That write is deliberately narrow — no code, no new files, no deletions — it carries the
+file's own permissions across, it lands as a rename so an interrupted save leaves the old file
+whole, and it refuses outright if the file has changed on disk since the page read it.
+
+The second is the `.k0/` folder, and only ever inside it: the readable copy of that repository's
+backlog, rewritten whenever a story changes. Never your `.gitignore`, never a file beside it, and
+a test walks the tree afterwards to prove nothing else appeared. With the backlog switched off the
+folder is never made at all.
+
+The third only happens when you ask for it, and it is `/k0-work` opening a worktree. That one is
+the largest thing k0 does to a repository, so it is worth reading twice: it adds a worktree under
+`.claude/worktrees/`, it writes two lines into `.git/info/exclude` so that directory does not show
+up as something you forgot to commit, and at the end it commits inside the worktree and merges
+that branch into the branch you were standing on. It never pushes, never opens a pull request, and
+never resolves a conflict on your behalf — where it cannot merge cleanly it stops and says so.
+None of it happens unless you run `/k0-work`.
+
+k0 does not emulate a terminal and installs no settings hooks. The one thing it puts inside Claude
+Code is [the `k0-links` mod](#what-claude-points-at-one-click-away), and only if you
+said yes: it draws a row above the prompt, never touches a reply, and talks to nobody but k0 on the
+loopback address. Beyond that k0 reads what Claude Code already writes for itself:
 
 - `~/.claude/sessions/<pid>.json` — live status (`busy`, `idle`, `waiting` with the reason for the
   wait) and the session id;
 - `~/.claude/projects/<project>/<session>.jsonl` — the transcript, read incrementally, which is
-  where you can tell whether you are inside a plan.
+  where you can tell whether you are inside a plan — and, for the Usage page, what every reply
+  consumed, the subagents' and workflows' transcripts beside it included.
 
-Sessions are launched with `--session-id` (k0 chooses the id, so the card ↔ session link is
-certain), `-n` for the name, `--resume` to pick one up, and `--permission-mode plan` on new ones.
+For the Usage page alone, two more: the account in `~/.claude.json`, read again only when that file
+changes, and `~/.k0/usage/limits.jsonl`, which your statusline writes if you gave it the snippet.
 
-The ChangeLog runs Claude Code a second way: `claude -p /k0-changelog`, with the facts on
-standard input and no terminal at all. It is the one time k0 starts a model, and it still opens
-no socket of its own — the request is Claude Code's, made with your own account, from your own
-machine. Those runs cannot come back as cards: `sessions.js` drops `claude -p` when it looks for
+Sessions are launched with `--session-id` (k0 chooses the id, so the story ↔ session link is
+certain), `-n` for the name, `--resume` to pick one up, and `--permission-mode plan` on new ones.
+Both kinds start with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in their environment, set on the command
+line the terminal is handed — `env` in front of `claude` on macOS and Linux, `$env:` before it on
+Windows.
+
+The ChangeLog and the What's New page run Claude Code a second way: `claude -p` on the skill that
+writes them, with the facts on standard input and no terminal at all. Those are the only times k0
+starts a model, and they still open no socket of k0's own — the request is Claude Code's, made
+with your own account, from your own machine. Both pages can be writing at once without either
+cancelling the other. Those runs cannot come back as stories: `sessions.js` drops `claude -p` when it looks for
 sessions to import, which is also how it tells a hundred and forty real sessions from eight
 hundred automated ones.
 
@@ -903,6 +1782,12 @@ Field notes the code takes for granted.
   of the two flags changes nothing — the session starts in `bypassPermissions` and there is no
   trace of a plan. It looks like it works, which is what makes it a trap. The only way to really
   start inside a plan is `--allow-dangerously-skip-permissions`.
+- **On a newer model Claude Code starts with no task tools.** It offers `TaskCreate`, `TaskUpdate`
+  and the rest only to a list of older models, or when `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` is in the
+  environment, and Opus 5 is not on the list. Nothing says so up front: the model calls
+  `TaskCreate`, is told it is disabled for the session, and carries on without. The variable is
+  read once, when the process starts, so a session opened before k0 set it gets the tools only by
+  being resumed.
 - **While a dialog is open, the call that caused it is not yet in the transcript.** A plan to
   approve and a question are told apart by the `waitingFor` field of the session file:
   `permission prompt` is the plan, `input needed` is the question.
@@ -910,10 +1795,17 @@ Field notes the code takes for granted.
   replaced by `-`, truncated at 200 characters with a hash on the end. That is lossy: `my_project`
   and `my-project` become the same name, so the working directory is always read from inside the
   transcript, never by reversing the directory name.
-- **A session's name lives in two places** — the session file, rewritten by the live process, and
-  the end of the transcript, in `custom-title` and `agent-name` lines that Claude Code rewrites
-  every turn. **The last one wins.** So renaming a closed session means appending another copy; a
-  live one would have the old name written back over it.
+- **A session's name lives in three places** — the process's own memory, the session file it
+  rewrites (`name`, with `nameSource: "user"` when `-n` or `/rename` set it), and the end of the
+  transcript, in `custom-title` and `agent-name` lines that Claude Code rewrites every turn.
+  **The last one wins.** So renaming a closed session means appending another copy; a live one
+  would have the old name written back over it, and the only way into a live one is its own
+  `/rename` command — typed at the keyboard. Written into the terminal as one block (Terminal's
+  `do script`, a paste) the same line reaches it as a message, and the model answers that it
+  cannot rename the session. The session file is how k0 knows the command took.
+- **The transcript is not always under the repository's slug.** A session that moves into a
+  worktree writes under the worktree's slug from then on, and a story only knows the repository —
+  so a rename looks in the work path, then the repository, then walks the projects directory.
 - **The session file appears before the interface is ready to receive.** Writing at that moment
   loses the first characters and swallows the Enter. So k0 waits until it can see the input box —
   and where a platform cannot read a terminal's screen, it waits a fixed moment and says so.
@@ -954,11 +1846,11 @@ Field notes the code takes for granted.
 The order is the fresher of two histories. The first is `~/.claude.json`, where Claude Code notes
 when you opened each one — but `lastStartTime` is rewritten when the session *ends*, so on its own
 it only tells you about the past. The second is k0's own database, which moves when you create or
-edit a card and on every status change of a live session. That is what brings the repository you
+edit a story and on every status change of a live session. That is what brings the repository you
 are working in right now to the top.
 
 The list holds directories with a `.git`, directories you have already worked in even if they are
-not repositories, directories with a card, directories with a document inside them — and **empty
+not repositories, directories with a story, directories with a document inside them — and **empty
 ones**.
 
 Empty ones belong because an empty directory under your home is one you just made, and it cannot
@@ -967,8 +1859,8 @@ in `Others` with its `+`. Anything starting with a dot does not make it full, or
 file manager would be enough to make it disappear again.
 
 **A column lives as long as its directory does.** If that directory is gone — deleted, renamed, an
-external disk unmounted — the column does not appear, and neither do its cards. **Hiding is not
-deleting**: the cards stay in the database, and if the directory comes back so do they.
+external disk unmounted — the column does not appear, and neither do its stories. **Hiding is not
+deleting**: the stories stay in the database, and if the directory comes back so do they.
 
 ---
 
@@ -980,15 +1872,25 @@ HTML files from your repositories are shown in a sandbox with no permissions. Th
 and no token: anything already running as you on this machine can reach the API, and that is worth
 knowing rather than glossing over.
 
+**One request leaves this machine, and it is about k0 rather than about you.** Once a day k0 asks
+the public npm registry what the newest version of `k0-board` is, so the board can say there is
+one. The package name is in the address and nothing else — nothing about you, your repositories,
+your commits or your board — nothing is downloaded, and `"updateCheck": false` in `~/.k0/config.json` switches it off entirely.
+
 The full picture, and how to report a problem privately, is in [SECURITY.md](SECURITY.md).
 
 ## What is not here yet
 
-Checkboxes inside a card. In the viewer only documents are listed: code opens if you arrive at it
-from a link, but it is not browsable and the text search does not look at it. Files are read only:
-they are not edited, not diffed, and you cannot talk to them — for that you open the repository
-with Claude. Sessions opened by hand outside k0 are picked up with `/k0-import`, on request:
-nothing notices them by itself yet.
+Ticking a line off on the post-it itself: a story's checklist is written by `/k0-verify`, and the
+place to work through it is the story's panel in the list. Writing a decision, discussing one and
+superseding one are still done by talking to Claude — the board says which of those to do next and
+opens the terminal on it, but nothing on the page writes a decision.
+In the viewer the listing is documents and configuration: code opens if
+you arrive at it from a link, but it is not browsable and the text search does not look at it.
+Only configuration and notes can be edited, one file at a time — nothing is diffed, no file is
+created or deleted, and you cannot talk to them; for that you open the repository with Claude.
+Sessions opened by hand outside k0 are picked up with `/k0-import`, on request: nothing notices
+them by itself yet.
 
 ## Contributing