k0-board 0.1.1 → 0.2.0

package/.claude/skills/k0-changelog/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: k0-changelog
+description: Writes the summary of a stretch of work — what got committed, what is already online, what is still sitting on this machine — from the facts k0 hands over on standard input. k0 calls it by itself when somebody opens the ChangeLog page, and it is what turns a list of commits into something a person can read. Use this skill when the user types "/k0-changelog", or asks "what did I do yesterday", "write up my week", "summarise what I shipped". Do not use it to look the facts up: they arrive on standard input already, and this skill never runs git itself.
+---
+
+# /k0-changelog
+
+You are handed, on standard input, a JSON description of everything that happened in a stretch
+of time across somebody's repositories. Write it up so they can read it over a coffee and know
+where they stand.
+
+Your entire reply is the summary. It is printed as it is, so there is no room for a preamble,
+no "here is your summary", no closing offer of further help, and no code fence around the
+whole thing. Markdown, starting at the first word that belongs to the summary.
+
+## What arrives
+
+```json
+{
+  "period": "yesterday",
+  "from": "…", "to": "…",
+  "totals": { "repositories": 3, "commits": 11, "online": 9, "local": 2, "dirty": 4, … },
+  "repositories": [
+    {
+      "name": "k0",
+      "commits": [{ "at": "…", "subject": "…", "body": "…", "online": true }],
+      "unpushed_total": 2,
+      "uncommitted_files": ["web/board.js"],
+      "unreleased_changelog": ["### Fixed", "- the board stays pinned to the bar"],
+      "cards": [{ "title": "…", "description": "…", "status": "IDLE", "done": false }]
+    }
+  ]
+}
+```
+
+`online: true` means that commit has left this machine. `online: false` means it is done but
+still only here. `unpushed_total` counts those from before this window too — a commit made on
+Tuesday and still sitting here on Friday is worth a mention.
+
+## What to write
+
+**One opening paragraph**, no heading above it. Two or three sentences: how many repositories
+were touched, what actually got out, and what did not. Write the sentence you would say out
+loud if somebody asked how yesterday went — not a table read aloud.
+
+**Then one block per repository**, in the order they arrive:
+
+```markdown
+## k0
+
+**The zoom moves ten per cent at a time, and the button that puts a column away stays put.**
+
+Two touches to the board. The zoom used to jump in steps too wide to land on 90%, and the
+button that folds a column away appeared and disappeared depending on the session: now it is
+always there.
+
+- The zoom goes down ten per cent a click, so 90% is one click away
+- The button that puts a column away no longer blinks with the session
+- The `Old` column now reads like `Others`
+
+**Done, not online yet:** two commits still on this machine, and three changelog lines written
+but not yet closed into a version.
+**Still half-done:** three files changed and never committed.
+```
+
+The bold first line is the point of the whole thing: it says **what is different now**, not
+what was modified. Not "the zoom step was made configurable" but "the zoom moves ten per cent
+at a time". If you cannot say what is different, the commit subjects will usually say it for
+you — they were written by the same person you are writing for.
+
+Keep a block short. A paragraph, a handful of bullets, and the two closing lines when there is
+something to put in them. This is a summary somebody reads standing up.
+
+## Rules
+
+- **Write in the language of the facts.** The commit subjects and the card titles tell you what
+  language this person works in: write in that one, and do not translate anything. The headings,
+  the bold lines, the bullets — all of it in their language.
+- **Leave the words of the trade alone.** *commit*, *push*, *branch*, *changelog* are what these
+  things are called in every language, and they do not decline: six commits, not *sei commessi*.
+  Translate the sentence around them, never the word itself.
+- **Do not invent.** If a commit subject does not say what it did, say what it says and leave
+  it there. A summary that guesses is worse than a summary that is short.
+- **What changed for whoever uses the thing, not which function moved.** No file paths, no
+  function names, no jargon, unless the repository itself is a tool for programmers and the
+  commit already speaks that way.
+- **Never print commit hashes.** They are not in what you are given, and they should not be in
+  what you write.
+- **Leave out the two closing lines when they are empty.** No "nothing left half-done": an
+  absent line already says that, and a line saying nothing is one more line to read.
+- **No emoji and no exclamation marks.** Nothing is exciting; things happened.
+- **If a repository has only uncommitted files and nothing else**, that is still worth a block —
+  it just says work is in progress there, and what it is about.
+- **If `repositories` is empty**, write one line saying so and stop. Do not pad it out, do not
+  encourage anybody, do not suggest what they might do next. Nothing happened, and saying that
+  plainly is the whole job.

package/CHANGELOG.md

@@ -6,6 +6,167 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0]
+
+k0 could always tell you how the work stood. This version lets it tell you whether the work is
+*running*: a globe in each column heading says whether that repository's site is up, and switches
+it on or off from the board. The server it starts belongs to nobody and outlives everything —
+the session that asked for it, the other sessions, and k0 itself — which is the one thing a dev
+server started inside a session could never do.
+
+### Added
+
+- **A globe next to every repository: is the site up, and one click to change it.** Last on a
+  column's heading, after the git mark. Grey is off, green is up, it breathes while it is coming
+  up, and red means it was started and did not come up — with the reason and the log a hover
+  away. **One click switches it, two restart it**, and while it is green the repository's **name
+  is underlined with a green dashed line** and becomes a link that opens the site in another tab,
+  on the port it is really listening on. The line is the same green as the globe and stays for as
+  long as the server does, so a repository that is up can be told apart from across the board
+  without going near it. A
+  repository gets one when its `package.json` has a `dev` script, or failing that a `serve` one:
+  nothing to configure, nothing to fill in. The point of it is where the server lives: k0 starts
+  it **detached and owned by nobody**, so it survives the session that asked for it, every other
+  session, and k0 restarting under it. A dev server started inside a session belongs to that
+  session and dies with it, which is what made "is the site up" a question nobody could answer
+  from the board. k0 also **never asks the server whether it is up** — it makes no network
+  requests, here as everywhere else — so "up" means the process is alive and the system says it
+  is holding a TCP port open, which is both stronger evidence and where the real port in the
+  tooltip comes from. And a server **you** started by hand in a terminal turns the globe green on
+  its own within a few seconds, and switches off from the board like any other: a globe that only
+  knew about its own servers would sit grey next to a site that is plainly running. On Windows
+  that last part is missing, because nothing there can read another process's working directory,
+  and k0 says so instead of drawing those servers as off. Tried on a real board, against a
+  repository that had a `server-restart` skill to compare with: the globe went green on port
+  4321 — read off the running process, not off the port written in the skill — the name opened
+  the site, a double click brought it back on a new process with nothing orphaned behind it, and
+  a server started by hand in a terminal was picked up and then switched off from the board. And
+  the one that matters: after `k0-board restart` the globe was still green and the site still
+  answering on the same process.
+
+### Changed
+
+- **A column's heading is two groups now, and the count of post-its is gone.** What you press is
+  on the left — the `+` and the fold — and what tells you how things stand is on the right: the
+  git mark, and the globe after it. The number that used to follow the repository name has been
+  taken out. It sat in the middle of the row taking up the room the name now uses, and it was
+  never the answer to a question anybody had: the post-its are right there to be counted, and
+  the number moved every time a filter did. Long repository names now give up characters to an
+  ellipsis instead of pushing the marks off the end of the row.
+
+### Fixed
+
+- **A tab left open no longer shows you the old interface.** k0 sent its own pages and stylesheets
+  with no instruction about keeping them, so the browser decided for itself — and a board left
+  open all day went on using the stylesheet it loaded that morning. It showed up the first time
+  the globe arrived: the servers switched on and off correctly and the board redrew every second,
+  but the heading kept the shape it had before, because the page redraws itself and the stylesheet
+  does not. After an update it is worse than confusing: the new k0 on disk, the old one on screen.
+  They are a few kilobytes over a connection to your own machine, so nothing is kept now.
+
+- **`Close` gives the memory back without closing the work.** A link at the end of a card's row,
+  after `Done` and quieter than it: it stops the session and shuts its terminal — which is where
+  the memory was going — and leaves the card 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` picks the conversation up where it left off. Until now the only way
+  to give a machine its memory back was `Done`, which also declares the work finished, so a dozen
+  windows open meant choosing between a struggling computer and a board that lies. It is not there
+  while a session is working: stopping one mid-thought is not memory saved, it is work lost. Tried
+  on a real board, on a session weighing 380 MB: the window and the process were gone in a second
+  and a bit, the card stayed where it was, and `Resume` came back to the same conversation.
+- **A ChangeLog page that tells you what you have been doing.** The list-shaped button next to
+  the `+` opens a page of its own that reads like a release note: an opening paragraph on how the
+  day went, then one block per repository saying what is different now — and, underneath it, what
+  is **done but not out yet**. A commit still sitting on your machine, changelog lines written
+  but never closed into a version, files never committed. Four windows across the top — Today,
+  Yesterday, Week, Month — and it opens on none of them: it opens on the last day you actually
+  worked, so on a Monday you get Friday instead of an empty page. Only repositories you touched
+  in that window appear, so the one that has been dirty since March stops turning up every
+  morning as if it were news, and only your own commits are counted, so a repository shared with
+  other people still tells you about your day. The facts sit folded under each block, one line to
+  open them, with every commit marked green if it is online and amber if it is still only here.
+  The words are written by the Claude Code already on your machine — no key to paste, no account
+  to configure, nothing leaving the machine — and they come out in the language you commit in,
+  because they are written out of your own commit messages. Nothing is stored: the page is
+  written again every time you open it. Without Claude Code it still opens, with the facts and a
+  line saying why the rest is missing.
+- **The board keeps itself down to what you are working on.** A repository you have not touched
+  since the day before your last piece of work folds away by itself: its column leaves the board
+  and its name appears in `Old`, the new column next to `Others` and built exactly like it — a
+  `+`, a name and the git mark. Click that row and the column comes back at full width for the
+  rest of the visit, with everything that was in it. There is nothing to switch on — with a dozen
+  repositories open, you arrive in the morning and the three or four you are actually on are the
+  ones standing there, side by side. The day is counted back from your last piece of work rather
+  than from the clock, so on Monday you find Friday's work instead of an empty board. A column
+  with something going on in it — working, planning, asking you something, holding a plan up for
+  approval — never folds, whatever its age; a terminal simply left open at *Your turn* folds like
+  anything else, and folding closes nothing. And nothing folds while you are looking at it: the
+  board tidies itself on the next reload, never out from under your hands.
+- **A column can be put away now.** Next to a column's `+`, a button that folds it immediately
+  instead of waiting for it to go quiet — for a repository you are finished with for the day. It
+  goes faint and refuses on a column with something going on in it, and says why if you hover it.
+  It 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. What closes a session is
+  `Close` or `Done` on a card.
+- **The installation ends on the board.** `npx k0-board` now opens it in your browser once
+  everything is in place, after the cards have been imported, so the first thing you see is your
+  own work and there is no address to copy out of the terminal. `--no-open` finishes without it,
+  for installing over SSH. Where the name `k0.localhost` does not resolve, k0 falls back to
+  `127.0.0.1` rather than leaving you on a blank page.
+
+### Changed
+
+- **The zoom goes ten per cent at a time.** `+` and `−` used to jump from 100% straight to 80%,
+  or up to 125%: the steps in between simply did not exist, and the only way to a size like 90%
+  was a pinch on the trackpad — if you knew to try it. Now every click is ten points — 90%, 80%,
+  70% and so on, still stopping at 30% and 200% — so where the next one lands is something you
+  can guess before you press it. The pinch still gets you to anything in between, and from there
+  the next click picks the nearest step.
+- **Nothing here changes what you see using k0.** The work went underneath, and it was worth doing
+  for two reasons. The tests now run on the machinery Node already ships with rather than on a loop
+  written by hand, which turns seven pass-or-fail files into five hundred and twenty-one named
+  checks — still a quarter of a second, still nothing to install, but a failure now names the one
+  thing that broke instead of the file it was in. And two parts that had never been tested at all
+  are: the one that decides whether a request reaching k0 may be answered, which is what stands
+  between a web page you happen to have open and a program that opens terminals on your machine,
+  and the one that keeps your cards, which is where a mistake loses work you cannot get back.
+  Every build from now on refuses to go backwards on how much of k0 is covered.
+- **The reasoning behind k0 is now written down where it can be found.** Two documents for whoever
+  works on it: the shape of what k0 remembers, and how its tests are put together and what they
+  deliberately leave alone. Neither is shipped with the package.
+- **Nothing changes for you here either.** Putting out a new version of k0 — the documents brought
+  up to date, the tests run, and the version that reaches the registry — is now one road written
+  down rather than a sequence somebody has to remember, with a single stop to ask before the step
+  that cannot be undone. Like the two documents above, it is for whoever works on k0 and is not in
+  the package.
+
+## [0.1.2]
+
+Two things that were in the way every day: a field nobody needed, and a notification that opened
+the wrong application.
+
+### Fixed
+
+- **Clicking a notification opens that session's terminal**, on all three platforms. On macOS it
+  used to open **Script Editor** with a file dialog: when the Mac would not deliver k0's own
+  notifications, k0 fell back to posting one through `osascript`, and a banner posted that way
+  belongs to Script Editor rather than to k0 — no card, no click, wrong application. The fallback
+  is gone. When macOS refuses the permission, k0 now says so in the menu bar and takes you to the
+  Notifications pane — and switch it on there and the menu says so on the next pass, a couple of
+  seconds later, instead of leaving you looking at a message that reads as stuck. It writes what
+  the answer was in its log, and asks again rather than giving up on the first refusal. On Linux
+  the notification carries an action, on Windows the balloon finally has a click.
+
+### Changed
+
+- **A new card asks for three things**: the repository, a title, and what Claude should do when it
+  starts — which can be left empty and typed straight into Claude Code. The *Description* field is
+  gone: it never went anywhere except onto the note. Imported sessions keep theirs, which is the
+  one place it says something, and `/k0-import` still writes it.
+- **A note is never taller than it is wide.** Long text used to push a card down the column until
+  it stopped looking like a note. The repository, the title, the age and the buttons always show;
+  the text in the middle is what gets clipped.
+
 ## [0.1.1]
 
 Documentation, and how a release is made. Nothing about k0 itself changed.
@@ -65,6 +226,7 @@ here is everything that had to change for it to be somebody else's tool as well.
 - The personal fixtures k0 grew up on. `test/clean.test.mjs` now fails the build if any of them
   come back.
 
-[Unreleased]: https://github.com/alessio-ragni/k0-board/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/alessio-ragni/k0-board/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/alessio-ragni/k0-board/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/alessio-ragni/k0-board/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/alessio-ragni/k0-board/releases/tag/v0.1.0

package/README.md

@@ -40,7 +40,8 @@ npx k0-board
 ```
 
 That is the whole thing. It tells you everything it is about to change, asks, and only then does
-it. `k0-board uninstall` undoes all of it.
+it — and when it is finished it opens the board in your browser, so there is no address to write
+down anywhere. `k0-board uninstall` undoes all of it.
 
 k0 is published on npm as [`k0-board`](https://www.npmjs.com/package/k0-board): one package, no
 dependencies, nothing to compile. `npx` fetches it, runs the installer once and leaves nothing
@@ -69,8 +70,9 @@ that and went out from a laptop.)
 | `k0-board doctor` | what this machine can and cannot do, and why |
 
 `--yes` does not ask. `--from-source` points the service at the directory you are in instead of
-copying it, which is what you want while working on k0 itself. `--no-<name>` skips one optional
-change — `--no-lid-sleep`, `--no-shift-enter`. `K0_PORT` moves the board off 4319.
+copying it, which is what you want while working on k0 itself. `--no-open` finishes without
+opening a browser, which is what you want over SSH. `--no-<name>` skips one optional change —
+`--no-lid-sleep`, `--no-shift-enter`. `K0_PORT` moves the board off 4319.
 
 From a clone, if you would rather look first:
 
@@ -83,7 +85,10 @@ node bin/k0-board.js start
 That runs the server in the foreground and opens the board. Nothing is installed and nothing
 outside the directory is touched.
 
-The board lives at <http://k0.localhost:4319>.
+The board lives at <http://k0.localhost:4319>, which is the address both `install` and `start`
+open for you. If that name does not resolve on your machine — which happens on Windows, because
+only browsers are obliged to know that `.localhost` means this computer — k0 opens
+<http://127.0.0.1:4319> instead, and says so.
 
 ### Requirements
 
@@ -108,6 +113,7 @@ The board lives at <http://k0.localhost:4319>.
 | Keep the machine awake | ✅ | ✅ | ✅ |
 | Keep working with the lid closed | ✅ | ❌ system setting | ❌ system setting |
 | Tray icon and notifications | ✅ | ✅ GNOME/KDE | ✅ |
+| Clicking a notification takes you to that terminal | ✅ needs the permission | ✅ if the desktop honours actions | ✅ |
 
 **macOS is the only platform the author has.** Linux and Windows are written from the
 documentation and reviewed carefully, and the logic they share with macOS is tested on all three
@@ -146,8 +152,9 @@ 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. First the repository, then a title, then what Claude
-  should do when it starts. The prompt can be left empty.
+  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.
 
   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
@@ -203,6 +210,16 @@ k0 makes **no network requests**. Not one, not even for a font.
   still inside it makes macOS put up the "terminate running processes" dialog, and the window does
   not close at all.
 
+- **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
+  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.
+
+  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.
 
 Cards reorder themselves inside a column: first the ones waiting for you, then the ones grinding
@@ -216,17 +233,53 @@ right, left, up, down, and diagonally in the corners — faster the closer you a
 where the board ends. The thin shadow along one side says there is still something over there.
 Holding a mouse button keeps the board still, so a click near the edge lands.
 
-Bottom right there is the **zoom** and a percentage that, clicked, goes back to 100%; the button
+Bottom right there is the **zoom**: + and − move it ten per cent at a time — 90%, 80%, 70% and so
+on, between 30% and 200% — and the percentage between them, clicked, goes back to 100%. The button
 next to it shrinks just enough to fit the whole board on the screen. On a trackpad, two fingers
-move the view and a pinch zooms. Where you were is still there after a reload.
+move the view and a pinch zooms to anything in between; the next click of + or − picks the nearest
+step from there. Where you were is still there after a reload.
 
 The pills at the top are both legend and filter: click one and that status leaves the board. They
 stay as you left them.
 
-**The last column on the right is `Others`**: the repositories that have no column because they
-have no cards. Headings only, in alphabetical order. It is there for two things — getting into
-the files of a directory you are not working on, and giving birth to the first card there with
-its `+`.
+**The board keeps itself down to what you are working on.** A repository you have not touched
+since the day before your last piece of work folds away by itself: its column leaves the board
+and its name appears in `Old`, over on the right. There is nothing to switch on and nothing to
+tidy up — with a dozen repositories open, you arrive in the morning and the three or four you are
+actually on are the ones standing there, side by side.
+
+The day is counted back from **your last piece of work, not from the clock**, and that is what
+makes it survive a weekend: on Monday the freshest thing on the board is Friday evening, so what
+you find is Friday — not an empty board on the one morning you most need to see where you left
+off. The moment you start something on Monday the line moves with you.
+
+Two things never fold. **A column with something going on in it** — working, planning, asking you
+something, holding a plan up for approval — stays where it is however old it is: hiding the one
+that is waiting for you is the opposite of what the board is for. A terminal simply left open at
+**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
+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
+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
+there with the `+`.
+
+Next to a column's `+` there is one more button, which **puts that column away now** instead of
+waiting for it to go quiet on its own — for when you are finished with a repository for the day
+and would rather not look at it. On a column with something going on in it the button goes faint
+and refuses, and says why if you hover it — it does not disappear, because a column runs and goes
+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.
 
 ### The git mark
 
@@ -246,6 +299,93 @@ k0 **never runs `git fetch`**. It only looks at what your git already knows abou
 itself; a push made by somebody else does not show until you fetch. On a repository with no
 remote, pushing is not mentioned at all.
 
+### The globe: is the site up
+
+Last on a column's heading, after the git mark, a small **globe** says whether that repository's
+dev server is running. **Grey** is off, **green** is up, and it **breathes** while it is coming
+up. **Red** means it was started and did not come up — hover it for the reason and the log.
+
+**One click switches it on or off. Two restart it.** And when it is green the repository's
+**name is underlined with a green dashed line** and becomes a link: click it and the site opens
+in another tab, on the port it is really listening on. The line is the same green as the globe
+and stays for as long as the server does, so a repository that is up is one you can tell apart
+at a glance, from across the board, without going near it. Hover the globe to read the rest — the port, the command it was
+started with, and where its log is.
+
+A repository gets a globe when its `package.json` has a **`dev`** script, or failing that a
+**`serve`** one. Nothing to configure and nothing to fill in. `start` is deliberately not on that
+list: by convention it runs what has been *built*, which is not what this is for.
+
+Three things are worth knowing, because they are the point.
+
+**The server outlives the session.** k0 starts it detached and owned by nobody. Close the session
+that asked for it, close every session, restart k0 itself — the server stays up and the globe
+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
+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.
+
+**A server you started yourself is recognised.** Start one by hand in a terminal and the globe
+goes green on its own within a few seconds, with the right port, and switches it off if you ask
+it to. A globe that only knew about its own servers would sit grey next to a site that is plainly
+running, which is worse than no globe at all. On Windows this one part is missing — nothing there
+can read another process's working directory — and k0 says so rather than showing those servers
+as off.
+
+---
+
+## The ChangeLog
+
+The git mark answers "is this safe" for one repository, right now. The **ChangeLog** answers a
+different question — *what have I actually been doing* — across all of them at once. It is the
+list-shaped button next to the `+`, and it opens in a page of its own.
+
+It reads like a release note rather than a report. An opening paragraph saying how the day went,
+then one block per repository: a line saying what is different now, a short paragraph, a few
+points, and — the part that matters most — **what is done but not out yet**. A commit sitting on
+your machine, three changelog lines written but not closed into a version, four files never
+committed. That is the distinction the whole page is built on: what left here, and what only
+looks finished.
+
+Four windows across the top: **Today**, **Yesterday**, **Week**, **Month**. It opens on none of
+them: it opens on **the last day you actually worked**. On a Monday that is Friday, because a
+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**
+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.
+
+Below every block the facts are folded away, one line to open them: the commits themselves, each
+marked green if it is online and amber if it is still only here. That is what to open when you do
+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.
+
+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
+facts, hands them to Claude Code, and shows what comes back. No terminal opens, nothing appears
+on the board, and there is nothing to set up: the skill that does the writing ships inside the
+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.
+
+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.
+"Today" changes while you are reading it, so keeping a copy would be wrong more often than it
+helped. If Claude Code is not on the machine the page still opens: you get the facts, and a line
+saying why the rest is missing.
+
 ---
 
 ## The files of a session
@@ -364,6 +504,10 @@ 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
+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.
+
 Reading the process table costs little on a calm machine and a lot on a struggling one, which is
 exactly when you look at it. So it is sampled every three seconds, and **only while the board is
 open**.
@@ -380,7 +524,9 @@ 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.
+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
+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,
 **Done** clears it away. Being dead sessions they do not light the tray icon. Running it again
@@ -588,33 +734,60 @@ platform/
   contract.js    the line between k0 and the operating system, and what an adapter must fill in
   index.js       picks the adapter, and reports what this machine can and cannot do
   darwin/        AppleScript and Terminal.app, pmset and caffeinate, launchd, the Swift icon
+                 (menubar/, which is also what posts the notifications and reads the permission)
   linux/         tmux and any emulator, systemd-inhibit, systemd user units, a GTK tray
   win32/         PowerShell and Windows Terminal, execution state, Task Scheduler, a WinForms tray
-  shared/        what more than one of them needs: tmux, running commands, reading a process table
+  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
-  db.js          SQLite (node:sqlite): the card, session_event and pref tables
+  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 —
+                 docs/database.md
   paths.js       where the board, the logs and the cache live
   watcher.js     reads Claude Code's own files and derives the statuses; also renames a session
-  git.js         the only one that talks to git: what is committed, what is pushed, whose it is
+  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
   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
   pdf.js         the document on paper, printed by a headless browser
-web/             the two pages (html, css, js served exactly as they are)
-  index.html     the board — board.js, board.css, view.js
+web/             the three 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
   files.html     the file viewer — files.js, files.css
-  base.css       colours, fonts and scale: the house variables, shared by both pages
+  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
   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
   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
 .claude/skills/
   k0-import/     the skill that fills the board with sessions you have already had
-test/            npm test — plain scripts, no framework. See CONTRIBUTING.md
+  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.
+                 For whoever works on k0, not for whoever uses it: it is not in the package
+  commit-push-deploy/
+                 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
+  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
 ```
 
 ### What it reads, and what it never does
@@ -630,10 +803,23 @@ writes for itself:
 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.
 
+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 to import, which is also how it tells a hundred and forty real sessions from eight
+hundred automated ones.
+
 ### The traps
 
 Field notes the code takes for granted.
 
+- **A notification posted by `osascript` belongs to Script Editor.** `display notification` is the
+  one-line way to put a banner on screen from a script, and it works — but the banner is not
+  yours: it carries nothing, it has no delegate, and clicking it opens Script Editor with its file
+  dialog. It was in here as a fallback for when macOS would not deliver k0's own notifications,
+  and every click on it went to the wrong application. There is now one way to notify, and where
+  macOS refuses it the menu says so and takes you to the Notifications pane instead of pretending.
 - **`--dangerously-skip-permissions` switches off plan mode.** No error, no warning, and the order
   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
@@ -652,6 +838,23 @@ Field notes the code takes for granted.
 - **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.
+- **A service's PATH is not a shell's PATH.** Under launchd it is barely more than
+  `/usr/bin:/bin`, and `npm` and `node` usually arrive from a version manager whose PATH only
+  exists inside a shell. So a dev server is started through a **login shell** — which is the same
+  reason `findClaude` ends up asking one, and it is also what puts the project's own `.nvmrc` in
+  force.
+- **`npm run dev` is not the server, it is the thing that starts it.** SIGTERM to npm alone leaves
+  `vite` holding the port, which is why the old per-repo skills all ended up reaching for
+  `pkill -f`. k0 starts the server **detached**, so it leads a process group of its own, and
+  stops the *group*. But only when the process it was told about really is that group's leader:
+  a server somebody started by hand in a shell without job control can share its group with the
+  **shell**, and signalling that would close the user's terminal to stop a dev server. Where the
+  leader is somebody else, the processes are signalled one at a time instead.
+- **A remembered pid is only a number, and the system hands numbers out again.** A row written
+  before a reboot can point at a stranger's process — and that row is what a click on the globe
+  would kill. So a remembered server is only believed while the process at that pid is still
+  running the command it was started with, and `stop` reads the machine before it signals
+  anything rather than trusting what it stored.
 - **`do script … in tab 1 of window id N`** writes into the interface with no simulated keystrokes
   and no permissions, but it **always adds the Enter**. You can hold the Enter back with a
   trailing backslash, but the backslash stays on screen and forces two presses: tried and rejected.