k0-board 0.1.2 → 0.3.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
 
@@ -128,7 +133,7 @@ Nothing on this list happens before you have seen it and said yes. Everything on
 | What | Where | Why |
 |---|---|---|
 | A copy of k0 | `~/.k0/app` | so the service does not point at a temporary npx cache |
-| Your board, logs and cache | `~/.k0/` | `%LOCALAPPDATA%\k0` on Windows |
+| Your board, settings, logs and cache | `~/.k0/` | `%LOCALAPPDATA%\k0` on Windows |
 | A service that starts at login | LaunchAgents · systemd user unit · Task Scheduler | so k0 is simply there |
 | **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 |
@@ -195,8 +200,10 @@ k0 makes **no network requests**. Not one, not even for a font.
 - **double click** — brings that session's terminal back to the front, even if you had minimised
   it. It is what stops you losing track of which window is which.
 
-- **Resume** — appears once you have closed the terminal: it reopens the same conversation exactly
-  where it was.
+- **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 —
+  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.
@@ -205,6 +212,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
@@ -218,17 +235,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
 
@@ -248,6 +301,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
@@ -366,10 +506,55 @@ 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**.
 
+### 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
+you a gigabyte is the one you stopped thinking about yesterday. So **after twelve hours with
+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**
+picks the conversation up where it was. That is the whole reason this is safe: a closed terminal
+has never been a lost session.
+
+**Only yellow is ever touched** — *Your turn*, the ball in your court and nothing happening. The
+rest is left alone, and each for its own reason:
+
+- **Working** and **Planning** are somebody mid-thought. Stopping one is not memory saved, it is
+  work lost — the same rule the `Close` link has always followed.
+- **Needs answer** and **Needs approval** would lose the very thing they were showing you. A
+  question and a finished plan are drawn by the terminal and are not written to the transcript
+  until they are answered, so closing that window throws the question away.
+- A session sitting in a **shell** is left alone as well. That is a shell you dropped into, and
+  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
+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
+*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
+19% · closes at 8h**, in lighter type than the numbers beside it. That is the whole announcement,
+and it is on that chip rather than anywhere else because that is where the memory is already being
+talked about — something that closes your windows for you should never be a surprise. Hover for
+the sentence. Switched off, the chip says nothing at all rather than *0h*, which would read as
+"closes immediately", and the hover is what tells you it is off.
+
+Twelve hours is what it does if you never say otherwise. `closeIdleTerminalsAfterHours` in the
+settings file changes it, and **`0` switches it off** — see below.
+
 ---
 
 ## Filling the board with what you have already done
@@ -580,6 +765,38 @@ Two side effects of the Cmd+V k0 uses to write your prompt, worth knowing:
 
 ---
 
+## Settings
+
+There is no settings page on the board, and there is not going to be one. The board is for what
+changes during a working day; a number you set once and then never look at again is the opposite of
+that, and putting it on screen would cost the one page that has to stay readable in exchange for
+nothing.
+
+So the settings are a file, and **the file is the list**:
+
+```
+~/.k0/config.json                        macOS and Linux
+%LOCALAPPDATA%\k0\config.json            Windows
+```
+
+k0 writes it on the first run with **every setting already in it at its default**, so opening it is
+how you find out what there is to change. It sits beside the board rather than inside the app —
+`npx` unpacks into a cache npm is free to wipe, and `k0-board install` overwrites the app
+directory, so a setting kept in there would not survive an update. Change it and k0 picks it up by
+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. |
+
+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.
+
+**`k0-board doctor` prints the same list**, with the value actually in force and where the file is,
+for the times you would rather ask than go and look.
+
+---
+
 ## How it is put together
 
 No dependencies, nothing to compile. Change a file, reload the page.
@@ -595,33 +812,61 @@ platform/
                  (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
-  paths.js       where the board, the logs and the cache live
+  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, 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
-  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)
+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
@@ -637,6 +882,13 @@ 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.
@@ -665,6 +917,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.

package/bin/k0-board.js

@@ -48,6 +48,7 @@ if (Number(process.versions.node.split('.')[0]) < MIN_NODE) {
 
 const { name: platformName, capabilities, notes, service, extras, shell } = await import('../platform/index.js')
 const paths = await import('../server/paths.js')
+const settings = await import('../server/settings.js')
 
 const APP_DIR = flag('from-source') ? SOURCE : paths.APP_DIR
 const ENTRY = path.join(APP_DIR, 'server', 'index.js')
@@ -126,6 +127,31 @@ async function waitForServer(seconds = 10) {
   return false
 }
 
+// ── Opening the board ────────────────────────────────────────────────────────
+/**
+ * Opens the board in a browser and answers with the address it used.
+ *
+ * `k0.localhost` is the name the board deserves, and inside a browser it is guaranteed to mean
+ * this machine — RFC 6761 reserves the whole of `.localhost` for loopback and every browser
+ * honours it. A resolver is under no such obligation, and on Windows usually declines. So the
+ * name is tried first, from here, and the number is what we fall back to: a board at a duller
+ * address beats a blank page at a prettier one.
+ *
+ * Not being able to open anything at all is not a failure. Installing over SSH, or on a machine
+ * with no session to put a window in, is an ordinary thing to do, and the install has already
+ * succeeded by the time we get here.
+ */
+async function openBoard() {
+  let url = `http://k0.localhost:${PORT}`
+  try {
+    await fetch(`${url}/api/status`, { signal: AbortSignal.timeout(1500) })
+  } catch {
+    url = `http://127.0.0.1:${PORT}`
+  }
+  await shell.openBrowser(url).catch(() => {})
+  return url
+}
+
 // ── install ──────────────────────────────────────────────────────────────────
 async function install() {
   say(`\n${bold('k0')} — the board that drives your Claude Code sessions`)
@@ -218,7 +244,8 @@ async function install() {
     appDir: APP_DIR,
     tray,
   })
-  if (await waitForServer()) ok(`k0 is up: ${bold(`http://k0.localhost:${PORT}`)}`)
+  const up = await waitForServer()
+  if (up) ok(`k0 is up: ${bold(`http://k0.localhost:${PORT}`)}`)
   else warn(`the server is not answering yet — look in ${paths.LOG_DIR}`)
 
   // ── The two invitations ────────────────────────────────────────────────────
@@ -231,6 +258,12 @@ async function install() {
     note(`Where: ${extra.target}`)
   }
 
+  // Last of all, on purpose: by now the imported cards are on the board, so what opens is
+  // somebody's own work rather than an empty grid they would have to reload.
+  if (up && !flag('no-open')) {
+    say(`\n${bold('Done.')} The board is open at ${await openBoard()}`)
+    return
+  }
   say(`\n${bold('Done.')} The board is at http://k0.localhost:${PORT}`)
   if (process.platform === 'win32') note(`If that name does not resolve, use http://127.0.0.1:${PORT}`)
 }
@@ -334,16 +367,17 @@ async function uninstall() {
 // ── start ────────────────────────────────────────────────────────────────────
 /** Runs the server in the foreground and opens the board. No service, nothing installed. */
 async function start() {
+  const open = !flag('no-open')
   if (await alive()) {
     ok(`k0 is already running on http://k0.localhost:${PORT}`)
-    await shell.openBrowser(`http://k0.localhost:${PORT}`).catch(() => {})
+    if (open) await openBoard()
     return
   }
   const child = spawn(process.execPath, [path.join(SOURCE, 'server', 'index.js')], {
     stdio: 'inherit',
     env: { ...process.env, K0_PORT: String(PORT) },
   })
-  if (await waitForServer()) await shell.openBrowser(`http://k0.localhost:${PORT}`).catch(() => {})
+  if ((await waitForServer()) && open) await openBoard()
   child.on('exit', (code) => process.exit(code ?? 0))
 }
 
@@ -387,6 +421,19 @@ async function doctor() {
   ]
   for (const [what, yes] of rows) (yes ? ok : warn)(what)
 
+  // The settings, in full, with what is actually in force. k0 has no settings page and is not
+  // getting one, so this — and the file itself — is where the list lives. Printing every key
+  // rather than only the ones somebody has changed is the point: it is an inventory.
+  step('Settings')
+  const conf = settings.status()
+  say(dim(`  ${conf.path}${conf.exists ? '' : ' (not written yet — the defaults are in force)'}`))
+  if (conf.broken) warn('this file could not be read: it is being ignored and the defaults are in force')
+  for (const [key, value] of Object.entries(conf.values)) {
+    const dflt = settings.DEFAULTS[key]
+    const off = key === 'closeIdleTerminalsAfterHours' && value === 0
+    say(`  ${bold(key)}  ${off ? 'off' : value}${value === dflt ? dim(' (default)') : dim(` (default ${dflt})`)}`)
+  }
+
   const explained = Object.entries(notes)
   if (explained.length) {
     step('Why not')
@@ -434,6 +481,7 @@ ${bold('k0-board')} — a board of sticky notes that drives your Claude Code ses
 Options
   ${bold('--yes')}            do not ask, assume yes
   ${bold('--from-source')}    point the service at this directory instead of copying it
+  ${bold('--no-open')}        do not open the board in a browser at the end
   ${bold('--no-<name>')}      skip one optional change, e.g. --no-lid-sleep
 `)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k0-board",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A board of sticky notes that drives your Claude Code sessions",
   "keywords": [
     "claude-code",
@@ -32,14 +32,17 @@
     "web",
     "menubar",
     "!menubar/k0.app",
-    ".claude/skills",
+    ".claude/skills/k0-import",
+    ".claude/skills/k0-changelog",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "node server/index.js",
-    "test": "node test/clean.test.mjs && node test/states.test.mjs && node test/files.test.mjs && node test/mentions.test.mjs && node test/refs.test.mjs && node test/machine.test.mjs && node test/mode.test.mjs",
+    "test": "node --test \"test/*.test.mjs\"",
+    "test:watch": "node --test --watch \"test/*.test.mjs\"",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude=\"platform/**\" --test-coverage-exclude=\"test/**\" \"test/*.test.mjs\"",
     "doctor": "node bin/k0-board.js doctor"
   }
 }

package/platform/contract.js

@@ -33,6 +33,10 @@
  * @property {object} metrics
  * @property {boolean} metrics.pressure              the kernel publishes a memory-pressure verdict
  * @property {boolean} metrics.swap                  swap usage is readable
+ * @property {object} servers
+ * @property {boolean} servers.run                   can start and stop a project's dev server
+ * @property {boolean} servers.ports                 can tell which port a process is listening on
+ * @property {boolean} servers.adopt                 can recognise a server started outside k0
  * @property {object} service
  * @property {boolean} service.autostart             can register a service that starts at login
  * @property {boolean} tray                          a menu bar / system tray icon is available
@@ -47,6 +51,7 @@ export const NO_CAPABILITIES = {
   terminal: { windows: false, font: false, readScreen: false, pasteWithoutSending: false, title: false },
   power: { keepAwake: false, keepDisplayAwake: false, lidSleep: false, battery: false },
   metrics: { pressure: false, swap: false },
+  servers: { run: false, ports: false, adopt: false },
   service: { autostart: false },
   tray: false,
   revealInFileManager: false,
@@ -101,6 +106,30 @@ export const NO_CAPABILITIES = {
  * @property {() => Promise<number>} pressureLevel  1 normal, 2 warning, 4 critical
  */
 
+/**
+ * The dev server a project runs while you are working on it — the one the globe in the column
+ * heading switches on and off. k0 starts it detached, so it outlives both the session that
+ * asked for it and k0 itself; what this adapter adds is the two things only the operating
+ * system knows, and the one gesture Node cannot make portably.
+ *
+ * @typedef {object} ServersAdapter
+ * @property {() => {run: boolean, ports: boolean, adopt: boolean}} capabilities
+ * @property {() => Promise<Map<number, Set<number>>>} listeners
+ *   Every process holding a TCP port open, and which ports. This is how k0 knows a server is
+ *   up: not by asking it, which would be a network request, but by seeing it hold the socket.
+ * @property {(pids: number[]) => Promise<Map<number, string>>} cwds
+ *   Where each of those processes is working from, which is what ties one to a repository.
+ *   An adapter that cannot say returns an empty map and reports `adopt: false`.
+ * @property {(command: string) => {file: string, args: string[]}} shell
+ *   How to run `command` inside a project. It goes through a LOGIN shell on Unix, and that is
+ *   not a flourish: the server runs from a launch agent whose PATH is barely more than
+ *   /usr/bin:/bin, while npm and node usually arrive from a version manager whose PATH only
+ *   exists inside a shell. It is the same reason `findClaude` ends up in a shell.
+ * @property {(root: number, pids: number[], signal?: string) => Promise<boolean>} stop
+ *   Stops the server and everything it started. `pids` is the whole subtree, `root` included:
+ *   killing the top process alone leaves the real server holding the port.
+ */
+
 /**
  * @typedef {object} ShellAdapter
  * @property {(absPath: string) => Promise<unknown>} revealInFileManager
@@ -129,6 +158,7 @@ export const NO_CAPABILITIES = {
  * @property {TerminalAdapter} terminal
  * @property {PowerAdapter} power
  * @property {MetricsAdapter} metrics
+ * @property {ServersAdapter} servers
  * @property {ShellAdapter} shell
  * @property {ServiceAdapter} service
  */