@skitterbyte/skitterspec 21.0.0 → 22.0.0

package/assets/skills/spec-diff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-diff
-description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, or the pasted JSON.
+description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
 ---
 
 # /spec-diff — see the phase before you commit it
@@ -41,13 +41,19 @@ sole candidate or prints the candidates.
 The page has marks on it — `✓ accept` per file, notes against a line or a whole
 file, answers to the checks a written review asked — and it
 **ends in a decision**: `✓ Approve`, `↺ Request changes` or `… Discuss first`.
-A review comes back to you one of two ways, and **both are ordinary**:
+A review comes back to you one of three ways, and **all three are ordinary**:
 
 - **A six-digit code** — `418207`, on its own. A *served* page hands its pass
   straight to the engine, which holds it until someone reads the code out. This
   is the usual way on a phone.
-- **A pasted JSON blob** — a `file://` page has no server to talk to, so it
-  copies. Not legacy: it is the whole story for a local reader.
+- **A verdict word** — `commit`, `commit-continue`, `continue`, `changes` or
+  `discuss`. A `file://` page cannot send anything, so where the reader marked
+  nothing it copies a command carrying the conclusion on its own. Send it with
+  `skitterspec spec-env review <spec> --verdict <word>`; it joins the same merge
+  a claimed pass does, so everything below is unchanged.
+- **A pasted JSON blob** — the same `file://` page, once the reader has marked
+  something up: accepts and notes do not fit on a command line, so the whole
+  pass travels. Not legacy: it is the whole story for a local reader.
 
 Either way, **this is not a request to render anything**: it is a review coming
 back, and these steps replace §3–§5 below.
@@ -151,6 +157,10 @@ back, and these steps replace §3–§5 below.
    absent verdict has always meant "report it and wait" — which is why that is
    what it still means.
 
+   **A pass may carry an `action:` instead**, and then none of the above
+   applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
+   carrying both, so there is never a choice to make between them.
+
 3. **Say what you read, then ask what's up.** Report the accepted count, then
    each open comment as `file:line — note`, then the files you would touch.
    **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -335,6 +345,69 @@ it — and the paste was the one place it broke. The *work* either authorises is
 ordinary phase-sized cost, and step 3 is where the operator decides whether to
 spend it.
 
+## 2b. An action changes something, then hands the page back
+
+Only on a pass carrying an **action**. Three of them, and
+**all three end the same way**:
+do the thing, re-render (§4), and wait again (§4b) — because the reader
+still has a decision in front of them and has not made it.
+
+| Action | Do | Then |
+|--------|----|------|
+| `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
+| `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
+| `allow-remote` | `skitterspec spec-env review allow remote --set on` | re-render, wait again |
+
+**THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
+live is about the diff on screen; handing the whole instance back to `main` is a
+workspace decision with nothing to do with this review. The `live:` line names
+`/spec-live main` for it — a command the operator types, which is also why no
+skill runs it.
+
+**AN ACTION IS NOT A VERDICT, and the gate is untouched by all three.** A phase
+that ended armed the gate, and it is discharged by a committing verdict or a
+recorded skip and by nothing else — so after any of these the phase still owes
+an answer, and that is exactly why the run waits again rather than finishing.
+The engine enforces this rather than trusting it: `ACTIONS` is disjoint from
+`VERDICTS` and `COMMITTING`, so nothing that routes on a verdict can see one.
+
+**`live-on` commits first, and the commit is a precondition rather than an answer.**
+`live take` refuses a dirty worktree, and even without that guard
+uncommitted work stays behind in the worktree — so what went live would be the
+*previous* commit while the page claimed to be showing this one. Hand off to
+`review.commitWith` exactly as §2a does (do not restate its rules here), then
+take the instance. The reader has not approved anything by pressing it.
+
+**It re-renders `--branch` afterwards**, because the working view is now empty:
+the commit just happened, and the branch range is what still answers "what am I
+looking at". §4's clean-tree fallback reaches the same place on its own, so
+passing `--branch` is belt and braces rather than a separate rule.
+
+**A mid-phase page does not get the commit.** Where the render took
+`--buttons midrun`, the work is half a phase — committing it to look at it
+running splits one phase across two commits and leaves a mess nobody asked for.
+Say the phase needs to land first, re-render, and wait.
+
+**Relay every refusal, and work around none of them.** `live take` refuses a
+workbench another spec holds, a hotfix, a stateful spec, a branch touching
+migrations, and a tree with no dev server listening. Each refusal names its own
+way out. **Never park another spec's live session** to make room — that is
+someone else's work, and freeing it is their decision. Re-render and wait, so
+the reader can choose something else.
+
+**`allow` writes a committed file, and that is worth a sentence.** It edits
+`specs/.core/env.config.json` in the **primary checkout**, so it changes
+behaviour for everyone who pulls and leaves that tree dirty — unlike the live
+actions, which move a branch and write a gitignored receipt. The engine prints
+the absolute path and whose tree it dirtied; relay that rather than letting a
+shared setting change land silently. And it is **enable-only**: there is no
+action that turns a tier off, because turning `network` off from a page reached
+over the network kills the page doing the turning.
+
+**`allow remote` permits publishing. It does not publish.** Publishing stays an
+explicit ask in every case (§6), because the page it leaves behind is one this
+tooling cannot remove.
+
 ## 3. Gate it on nothing
 
 **This skill has no preconditions and must never grow one.** Not tests passing,
@@ -367,15 +440,17 @@ skitterspec spec-env review <spec> --branch     # everything since the base bran
 skitterspec spec-env review serve               # every spec, on localhost
 ```
 
-**The engine handles the switch.** A file when the reader is at this machine, a
-served URL when they are not: on a `remote` reader it stands its own server up
-and puts a URL the reader can open on the `open:` line. Both are free and neither
-publishes anything. You are not choosing between them; you are relaying whichever
-one the engine printed.
+**There is no switch left to handle.** The engine serves and prints a **stack** —
+one line per tier, `local`, `network`, `remote`, each either a URL or the one
+command that turns it on. All of it is free and none of it publishes anything.
+You are not choosing between them; you are relaying every line it printed.
+`.claude/rules/spec-reports.md` carries the shape and why.
 
-The operator who does not want a LAN listener started for them sets
-`review.serveOnRemote: false` in `env.config.json`, and the `file://` link with
-its *will not open where you are reading* marker comes back.
+The operator who does not want a LAN listener sets `review.allowNetwork: false`
+in `env.config.json` — `network` then reads `off` with the command that turns it
+back on, and `local` is the loopback page. Turning serving off entirely is
+`review.serve: "never"`, and then `local` is the `file://` page, which says on
+its own line that it cannot send a verdict.
 
 `serve` renders **per request**, so nothing it shows can be stale, and it lists
 every spec with a worktree rather than one. `--host 0.0.0.0` binds beyond
@@ -428,21 +503,29 @@ committing verdict or a recorded skip.
 
 **On `--page-only`, stop here** and report the path.
 
-## 4a. Read the `reader:` line — never sniff for it yourself
-
-`spec-env review` reports where it believes the reader is, and
-**that is the only place this question is answered.** Three states:
-
-| `reader:` | What to offer |
-|-----------|---------------|
-| absent (`unknown`) | the `file://` URL, exactly as always. **Do not warn** — unknown is the ordinary state of a local machine |
-| `local` | the `file://` URL |
-| `remote` | the `open:` line as printed — the engine already served it. Pass on any `also:` lines too |
-
-**Never read an environment variable to decide this.** Not `SSH_CONNECTION`, not
-`CLAUDE_CODE_*`, not a tty check — the engine already did it, reports the answer
-on that line and in `--json`, and a second implementation here could not be
-tested and would drift from the first. The ranking and the traps
+## 4a. Relay the stack — every tier, never one you picked
+
+`spec-env review` prints one line per tier and `--json` carries the same thing
+as `tiers`. **Relay all of them, in that order**, whatever the `reader:` line
+says:
+
+| Tier | Carries |
+|------|---------|
+| `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
+| `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
+| `remote` | the published URL and *a verdict here needs `/spec-reviewed`* — or `off` with the command that turns it on |
+
+**The `reader:` line decides nothing here any more.** It is still printed and
+still the only place that question is answered, but the offer no longer branches
+on it — because branching on it is what produced a `file://` page for a session
+detected `unknown`, a LAN URL for a phone off the network, and an address that
+changed underneath a reader mid-session. A tier that is off keeps its line, so a
+reader who has left the house can see the surface exists and ask for it.
+
+**Never read an environment variable to decide anything about the offer.** Not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check — there is nothing left
+for a detection to decide, and a second implementation of one could not be
+tested and would drift. The ranking and the traps
 (`CLAUDE_CODE_ENTRYPOINT` describes the *process*, not the reader; stdin is never
 a tty under Claude Code) live in `review.js` beside the code, which is where they
 belong.
@@ -461,8 +544,9 @@ answer left.
 
 `review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
 operator settle where they are reading, and an explicit value is believed without
-sniffing. `review.serveOnRemote` (default `true`) settles whether the engine may
-act on it.
+sniffing. What the engine may *do* is settled by the tier settings instead —
+`review.serve` (`always` · `never`), `review.allowNetwork` and
+`review.allowRemote` — not by the reader.
 
 ## 4b. Wait for the verdict — because asking for one means waiting for it
 
@@ -483,8 +567,8 @@ said the page was **ready** rather than that it was **waiting**.
 **So the question is not "can I watch a file".** It is "am I asking?" — and the
 transport only decides what carries the answer back:
 
-- **A served page** posts to the local store; a file-watch sees it, and the
-  steps below are that watch.
+- **A served page** posts to the local store; the engine's own wait returns when
+  it lands, and the steps below run it.
 - **A `file://` page** has nothing to post to, so the reader pastes the pass and
   their next message carries it. Say you are holding and **end the turn** — that
   is the same wait, carried by the conversation. It is not a lesser one.
@@ -498,9 +582,20 @@ already arrived. Those get the `Review` row, no question, and nothing is owed.
 
 1. **Note the moment**, as an ISO timestamp, before you start. That instant is
    the entire scope of what may be claimed without a person naming it.
-2. **Watch** `.spec-env/reviews/<spec>.pending.json` in the primary checkout,
-   and **end the turn**. Not a poll and not a held-open turn: the operator has
-   their terminal back, and the session costs nothing while they read.
+2. **Run the engine's wait in the background, and end the turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <timestamp>
+   ```
+
+   **Never a watcher of your own, and never a timeout.** It lasts as long as the
+   session, because a reader who walks away from a diff is the normal case — and
+   a loop composed here would be proven by nothing, which is how one written as
+   `[ "$x" \> "$y" ]` spun for five minutes in zsh and looked exactly like
+   patience. `/spec-next` §5 carries the full account.
+
+   Not a poll and not a held-open turn: the operator has their terminal back,
+   and the session costs nothing while they read.
 3. **On waking, let the engine choose:**
 
    ```
@@ -711,8 +806,8 @@ consumed rather than stored.
 purpose; someone who forgot they had voted has not, and only the report tells
 them apart.
 
-`Review` carries the files and `+`/`−`, the page's `open:` line, and the
-published URL when there is one. Where the page holds a review pass, it also
+`Review` carries the files and `+`/`−`, and the tier stack — labelled, run
+together with `·` because a row is one cell. Where the page holds a review pass, it also
 carries the three totals — files accepted, comments open, comments answered.
 `--json` reports those under `notes.totals`; read that, never the diff.
 

package/assets/skills/spec-hotfix/SKILL.md

@@ -274,30 +274,33 @@ this worktree is refused until a verdict is sent or
 `skitterspec spec-env review skip "<reason>"` records the decision to move on.
 The exit is always one command, and one of them is *"I am moving on"*.
 
-Relay the **`open:`** line rather than the bare path: a path is not clickable in
-any terminal, and a page nobody can open is a page nobody reads.
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three — rather than the bare `page:` path: a path is not clickable in any
+terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
+line with it where the engine printed one, and nothing where it did not.
+`.claude/rules/spec-reports.md` carries the shape, including why a rigid
+contract took that line.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always an ask. A
   `file://` link is no use on a phone, and saying so **is** the ask —
   `/spec-diff` §6 owns how.
-**Follow the `reader:` line the engine printed — do not sniff for it.** It
-answers where the person reading this is sitting, and the offer changes with it:
-
-- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
-  unknown is the ordinary state of a local machine, and a warning there is an
-  accusation against a healthy session.
-- **`local`** — the `file://` URL.
-- **`remote`** — the engine has already stood its local server up and put a URL
-  the reader can open on `open:`. So there is **nothing special to say**: relay
-  that line like any other. Any `also:` lines under it are the other addresses
-  this machine has, offered because the best-guess one can be wrong — pass them
-  on rather than editing them out.
-
-**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
-not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
-and in `--json`, and a second implementation here could not be tested and would
-drift.
+**The `reader:` line no longer decides anything here, and that is the point.**
+It is still printed, and it is still the only place that question is answered —
+but the offer does not change with it, because the stack lists every tier
+whatever it says. Three reader states used to mean three different offers, and
+that branching is exactly what produced a `file://` page on a session detected
+`unknown`, a LAN URL for a phone off the network, and an address that changed
+underneath a reader when detection flipped mid-session.
+
+So: **relay all three tier lines, every time.** Any `also:` lines sit under
+`network` — the other addresses this machine has, offered because the
+best-guess one can be wrong — so pass them on rather than editing them out.
+
+**Never read an environment variable to decide anything about the offer** — not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
+here for a detection to decide, and a second implementation of one could not be
+tested and would drift.
 
 **Serving is the engine's to do; publishing is never.** A `remote` reader
 authorises a local server — one process, ended by one flag, leaving nothing

package/assets/skills/spec-next/SKILL.md

@@ -154,6 +154,24 @@ Before writing any code for this phase, get the workspace clean:
   being *"I am moving on"*, which is what keeps this a push rather than a wall —
   a gate with no exit gets switched off wholesale instead of answered.
 
+- **Report anything left waiting, and claim none of it.** Ask the engine once:
+
+  ```
+  skitterspec spec-env review waiting
+  ```
+
+  A pass listed here arrived when nothing was watching — a wait that never ran,
+  a session cleared, a terminal closed overnight — and no watcher can recover
+  those, however good. Relay what it prints: the spec, the code, the verdict and
+  the age, with `/spec-reviewed <code>` to pick one up and `--drop <code>` to
+  disown it.
+
+  **It is information, not a gate.** It never refuses, nothing here is
+  conditional on it, and **you never claim one** — `/spec-diff` §0 stands
+  unchanged, and a pass sitting there when you arrived was not sent to you.
+  Silent when nothing is waiting, which is the usual case: say nothing rather
+  than reporting that there was nothing to report.
+
 ## 3. Implement the phase
 
 Identify the **first unfinished phase** from the `00-overview.md` phase index,
@@ -299,30 +317,51 @@ so one subject lives in one place:
 
 ## ⏸ Review ready — <N> files, +<a> −<d>
 
-**[Open the page](<the `open:` URL>)** · I'm holding here until you send a verdict.
+- **local** — <the `local:` URL>
+- **network** — <the `network:` URL, or off with the command that turns it on>
+- **remote** — <the `remote:` URL, or off with the command that turns it on>
 
-`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+<the `live:` line, exactly as the engine printed it — omitted when it printed none>
 
-**One link, and the engine has already chosen it.** Where it served, the
-banner carries the served URL and the wait is real. Where it could not serve —
-a busy port, a machine with no network address — that is the case publishing
-exists for, and then the banner carries the published URL with what is true of
-it: *press a verdict, then type `/spec-reviewed`*, because nothing pushes from
-the artifact store into this conversation.
+I'm holding here until you send a verdict — the wait covers local and network.
+
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
 
-**Never offer both.** Publishing while the server is reachable adds a second
-door the reader cannot tell apart from the first, and the wait only stands
-behind one of them — that was done, and three verdicts were pressed on the
-published page while each sat unread under a line saying I was holding. The
-published page is for the reader the server cannot reach, and for nobody
-else.
+**The stack is the engine's — copy it, do not compose it.** `spec-env review`
+printed one line per tier, in that order, and `--json` carries the same thing as
+`tiers`. Relay all three whatever they say, including the ones that are off with
+the command that turns them on: a reader who has left the house cannot ask for a
+remote page they were never shown.
+
+**Do not pick one for them.** The engine used to, and the guess failed three
+separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
+why the *one link, never two* rule now reads
+**one link per reachable store, each labelled** —
+local and network are two doors into one room, so the wait
+covers both. `remote` is a second store, so its own line carries its own caveat:
+*a verdict here needs `/spec-reviewed`*, because nothing pushes from
+the artifact store into this conversation. Never let the holding line promise a
+wait over that tier.
+
+**Publishing is still never yours to do.** `remote` reading `off` is the normal
+state, and the fix for it is the command on that line — typed by the operator,
+or pressed on the page, because a published page is one this tooling cannot
+remove and permitting it is not publishing it.
+
+**The `live:` line goes with the stack**, and it is the engine's line too —
+copied as printed, and **absent when the engine printed none**. The page can act
+on it: a press puts the spec live or takes it down and hands the reader back the
+same page, which is `/spec-diff` §2b's routing and not this skill's. What
+matters here is that an action **never clears the gate this phase armed** — the
+reader has looked at it running and concluded nothing, so the phase still owes a
+verdict.
 
 ---
 
 **Where you are not waiting, it stays the `Review` row** — the counts and the
 page link, and **no question**:
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) |
+| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** off |
 
 At the end of a phase you are always waiting, so this shape belongs to the
 renders that are not this step: a mid-phase `/spec-diff`, a page produced
@@ -352,16 +391,25 @@ whether the two places are adjacent rows or a row and a banner.
 
 The row is findable, but a row cannot make the continuation follow from the
 reading — and that is the gap the whole gate exists to close.
-**Where this harness can watch a file and wake the session on a change, use it.** The pass
-arrives at the engine's holding area, the watch fires, and the verdict the
-reader pressed is what carries the work on.
+
+**The wait is a command. Do not write one.**
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Watch the pending store** for the spec —
-   `.spec-env/reviews/<spec>.pending.json` in the primary checkout — and
-   **end your turn**. Do not poll, and do not hold the turn open: the point is that
-   the reader has the terminal back while they read.
+2. **Run the engine's wait in the background, and end your turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <the timestamp>
+   ```
+
+   It returns when a pass arrives inside that window, and
+   **it takes no timeout unless you pass one** —
+   the wait lasts as long as your session, because a reader who walks away from
+   a diff is the normal case rather than the edge one. Do not give it a duration
+   of your own.
+
+   Then **end your turn**. Do not poll it and do not hold the turn open: the
+   point is that the reader has the terminal back while they read.
 3. **On waking, let the engine pick**:
 
    ```
@@ -369,11 +417,26 @@ reader pressed is what carries the work on.
    ```
 
    It claims the one pass that arrived inside the window, and acts on nothing
-   at all when none did (the watch can fire on a write that was not a pass) or
-   when two did (two sittings, or two people — the operator has the codes).
+   at all when none did (the wait can be woken by something that was not a
+   pass) or when two did (two sittings, or two people — the operator has the
+   codes).
 4. **Route on the verdict** exactly as `/spec-diff` §2 and §4 describe. Do not
    restate that routing here.
 
+**WHY A COMMAND RATHER THAN A LOOP YOU COMPOSE.** This step used to say "watch
+the pending store" and stop, so every run invented its own watcher in shell —
+and three failed in two days, each reaching the operator as *"I pressed the
+button and nothing happened"*. The worst wrote
+`until [ -f "$P" ] && [ "$x" \> "$y" ]`: valid bash, a syntax error in zsh, a
+predicate that could never be true. It spun for five minutes writing to a
+stderr nobody reads.
+
+**The bug is not the lesson — the silence is.** A watcher that can never fire
+and one patiently working are indistinguishable from outside, so nothing about
+that run looked wrong until the operator asked. `review wait` says it has
+started, is written once, and is tested against a store that gains a pass
+mid-flight. A predicate composed fresh each time is proven by nothing.
+
 **WHY THIS IS SAFE, AND WHAT IT COSTS.** It was once true that a device
 reaching your page could not reach your conversation, and that fact was the
 whole guard: a pass sat in the holding area until a person typed
@@ -387,11 +450,11 @@ is that the page can now act, so the token has become a credential rather than
 a convenience — and `--claim-since` refusing to choose between two passes is
 what stops a race becoming a wrong commit.
 
-**Where the harness cannot watch a file, you still wait** — the turn ending is
-the wait. Say the page is rendered and that you are holding for the pass, then end
-your turn; the reader's next message is what carries it, and `/spec-diff` picks
-it up from the paste exactly as it always has. The gate holds either way: it is
-the engine's, not the watch's.
+**Where the harness cannot run something in the background, you still wait** —
+the turn ending is the wait. Say the page is rendered and that you are holding
+for the pass, then end your turn; the reader's next message is what carries it,
+and `/spec-diff` picks it up from the paste exactly as it always has. The gate
+holds either way: it is the engine's, not the wait's.
 
 This once read *"change nothing"* — keep the row, keep the question, do not
 wait — and that exemption is the hatch a whole class of unanswerable questions
@@ -401,38 +464,38 @@ came through. Every harness can end a turn.
 one line; by the time this step is reached the chain has finished, so waiting
 here stops nothing that was still going to happen.
 
-Relay the **`open:`** line the engine prints, not the bare path: a path is not
-clickable in any terminal, and a page nobody can open is a page nobody reads.
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines —
+never the bare `page:` path: a path is not clickable in any terminal, and a page
+nobody can open is a page nobody reads.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always something
   someone asks for. A `file://` link is no use on a phone, and saying so **is**
   the ask — publishing is the answer to it, and `/spec-diff` §6 owns how.
-**Follow the `reader:` line the engine printed — do not sniff for it.** It
-answers where the person reading this is sitting, and the offer changes with it:
-
-- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
-  unknown is the ordinary state of a local machine, and a warning there is an
-  accusation against a healthy session.
-- **`local`** — the `file://` URL.
-- **`remote`** — the engine has already stood its local server up and put a URL
-  the reader can open on `open:`. So there is **nothing special to say**: relay
-  that line like any other. Any `also:` lines under it are the other addresses
-  this machine has, offered because the best-guess one can be wrong — pass them
-  on rather than editing them out.
-
-**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
-not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
-and in `--json`, and a second implementation here could not be tested and would
-drift.
-
-**Serving is the engine's to do; publishing is never.** A `remote` reader
-authorises a local server — one process, ended by one flag, leaving nothing
-behind — and authorises nothing else. A reader the server CAN reach is not a
-reason to publish as well: the page they can already open is the page to name. Publishing leaves a page this tooling
-cannot remove, so it stays an ask in every case, always. If the engine could not
-serve (a busy port, a machine with no network address) it falls back to the
-`file://` URL with its marker, and that is when publishing is worth naming.
+**The `reader:` line no longer decides anything here, and that is the point.**
+It is still printed, and it is still the only place that question is answered —
+but the offer does not change with it, because the stack lists every tier
+whatever it says. Three reader states used to mean three different offers, and
+that branching is exactly what produced a `file://` page on a session detected
+`unknown`, a LAN URL for a phone off the network, and an address that changed
+underneath a reader when detection flipped mid-session.
+
+So: **relay all three tier lines, every time.** Any `also:` lines sit under
+`network` — the other addresses this machine has, offered because the
+best-guess one can be wrong — so pass them on rather than editing them out.
+
+**Never read an environment variable to decide anything about the offer** — not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
+here for a detection to decide, and a second implementation of one could not be
+tested and would drift.
+
+**Serving is the engine's to do; publishing is never.** The server is one
+process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
+decides whether it binds wide — no detection involved. A reader the server CAN
+reach is not a reason to publish as well: the tiers they can already open are on
+the stack. Publishing leaves a page this tooling cannot remove, so it stays an
+ask in every case, always — which is why `remote` shows the command rather than
+a URL until someone types it.
 
 - **Never fatal.** A failed render — no worktree, a git error — is one line and
   the phase is still done. The page is a convenience; the repo is the record.