refactor: overhaul the cli api, from the scenarios up

Author: cablehead

changes/v0.5.0.md

@@ -1,23 +1,28 @@
 # v0.5.0
 
-Breaking. Six commands are gone and `expose` refuses to run without a grantee.
+Breaking. The CLI is overhauled: six commands are replaced, and `expose` now
+requires a grantee.
 
 ## Where this came from
 
-The commands came last.
+The CLI had grown organically. A feature landed, a command arrived with it, and
+each one made sense next to the one before. Nobody had looked at the whole
+surface in a while. By 0.4 there were five commands covering a single job,
+getting two machines to talk to each other: `ticket`, `grant-token`, `add-peer`,
+`pin`, `remove-peer`.
 
-We started by writing `docs/scenarios.md`: two flows spelled out end to end from
-the operator's side, before touching any code. The first was reaching a shared
-build box from a laptop that was already running a daemon of its own.
+So we stopped adding to it and sat down with `docs/scenarios.md` instead. Two
+real flows, spelled out end to end from the operator's side, every command a
+person types, in order, across both machines.
 
-It did not work. Two values had to travel out of band, a key and a token, and
-they were always used together. `add-peer` could not present a token. `--enroll`
-existed only on `pai-sho daemon`, so a laptop already serving other peers had to
-restart to admit one more. None of that was news to the code. It became obvious
-the moment someone had to write down what a person actually types, in order,
-across two machines.
+The first flow did not work. Reaching a shared build box from a laptop already
+running a daemon meant two values travelling out of band, a key and a token,
+always used together. `add-peer` could not present a token. `--enroll` existed
+only on `pai-sho daemon`, so a laptop already serving other peers had to restart
+to admit one more. None of this was hidden in the code. It just never came up
+until someone had to write down what you actually type.
 
-Then the names went through several rounds. `pin` was tried and dropped. So were
+The names took several rounds. `pin` was tried and dropped, along with
 `grant-key` and `allow`/`connect`. Each described a mechanism rather than the
 thing happening, which is closer to: hi, be friends. And: yeah, be friends. That
 is `invite` and `accept`, and once the pair had honest names the rest followed.
@@ -95,6 +100,8 @@ replacing the grant check with `if true` fails five tests.
 
 ## Raw commits
 
+* refactor: overhaul the cli api, from the scenarios up (2026-08-19)
+* docs: a narrative for how the CLI fell out of the scenarios (2026-08-19)
 * docs: absolute links in the changelog, and 0003's name note up top (2026-08-19)
 * docs: lead the tagline's list with no account (2026-08-19)
 * refactor: move grants into the pure core, and give the model one home (2026-08-19)
@@ -111,4 +118,3 @@ replacing the grant check with `if true` fails five tests.
 * refactor: pure core for admission and authorization, and expose requires a grantee (#10) (2026-08-18)
 * docs: macOS supervised operator via brew services, with the trust/XDG note (2026-08-07)
 * chore: bump to v0.4.2-dev (2026-08-07)
-* docs: a narrative for how the CLI fell out of the scenarios (2026-08-19)