@rubytech/create-maxy-code 0.1.108 → 0.1.109

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.108",
+  "version": "0.1.109",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -31,7 +31,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is dr
 
 | Script | Purpose |
 |---|---|
-| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel — the agent enumerates them via `cloudflared tunnel list --output json` and presents the list in chat) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and prints it as `OAUTH_URL: <url>` on its own stdout — the admin UI's `ActionLogPanel` renders that line as a clickable Authorize link with `target=_blank` so the operator authorizes Cloudflare in a new tab of their own browser. The script does not spawn a browser of its own; cloudflared's OAuth callback writes `~/.cloudflared/cert.pem` regardless of which browser completed the Authorize click. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
+| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel — the agent enumerates them via `cloudflared tunnel list --output json` and presents the list in chat) or `TUNNEL_NAME` (operator typed a name to create). Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and prints it as `OAUTH_URL: <url>` on its own stdout — the native Claude Code PTY linkifies bare URLs so the operator clicks it from chat and authorizes Cloudflare in their own browser. The script does not spawn a browser of its own; cloudflared's OAuth callback writes `~/.cloudflared/cert.pem` regardless of which browser completed the Authorize click. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
 | [`scripts/reset-tunnel.sh`](scripts/reset-tunnel.sh) | Deletes every tunnel on the brand's CF account and wipes `${CFG_DIR}`. Does not touch the platform service, stray CNAMEs, or token-mode connectors — those require dashboard cleanup or `pkill`. Invocation: `~/reset-tunnel.sh <brand>`. No polling blocks — every long-wait is bounded by `cloudflared`'s network round-trip, so no heartbeat contract applies. |
 
 ### Skills

package/payload/platform/plugins/cloudflare/scripts/list-cf-domains.sh

@@ -24,17 +24,18 @@
 
 set -euo pipefail
 
-# --------------------------------------------------------------------------
-# Shared stream-log helpers (require STREAM_LOG_PATH, phase_line, …).
-# --------------------------------------------------------------------------
-
-# shellcheck source=_stream-log.sh
 # Resolve symlinks before dirname — ~/list-cf-domains.sh is installed as a
 # symlink into $HOME, so the raw BASH_SOURCE[0] points at $HOME, not the
-# scripts directory where _stream-log.sh lives.
+# scripts directory.
 SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
-source "${SCRIPT_DIR}/_stream-log.sh"
-require_stream_log_path list-cf-domains
+
+# Phase-line helper. Stream-log plumbing retired in Task 287 — every
+# observation goes straight to stdout for the PTY to render.
+phase_line() {
+  local scope=$1
+  shift
+  printf '[%s] %s\n' "${scope}" "$*"
+}
 
 if [ "$#" -lt 1 ] || [ -z "${1:-}" ]; then
   phase_line list-cf-domains phase=error reason=brand-arg-missing
@@ -45,10 +46,9 @@ BRAND="${1}"
 CONFIG_DIR=".${BRAND}"
 mkdir -p "${HOME}/${CONFIG_DIR}/logs"
 
-# MAXY_PLATFORM_ROOT is set by the systemd service when the admin server
-# spawns this script via runFormSpawn. Direct-SSH invocation has no such env
-# so derive it from the resolved script location: scripts/ → cloudflare/ →
-# plugins/ → platform → install root (three dirs up).
+# MAXY_PLATFORM_ROOT may be set by the calling environment. Direct-from-Bash
+# invocation has no such env so derive it from the resolved script location:
+# scripts/ → cloudflare/ → plugins/ → platform → install root (three dirs up).
 if [ -z "${MAXY_PLATFORM_ROOT:-}" ]; then
   MAXY_PLATFORM_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
 fi

package/payload/platform/plugins/cloudflare/scripts/list-cf-domains.ts

@@ -34,15 +34,15 @@
 // zones at t=1000 ms). The `scrapeDomains` poll waits for the observed count
 // to stabilise across two consecutive iterations before returning.
 //
-// Contract with the caller (list-cf-domains.sh → route → form):
+// Contract with the caller (the agent invokes list-cf-domains.sh via Bash):
 //   stdout on exit 0: JSON `string[]`  (empty array means signed-in-but-empty)
-//   stderr on any path: phase_line-formatted lines, `[list-cf-domains] …`
+//   stderr on any path: `[list-cf-domains] …` phase lines
 //   exit 1: `reason=<enum>` on stderr; scrape-empty-but-no-error is exit 0
-//            with body dump (the enum exists so the caller can distinguish
-//            "selector drift" from "empty account" — both shapes arrive via
-//            stdout).
+//            with body dump (the enum exists so the operator/agent can
+//            distinguish "selector drift" from "empty account" — both
+//            shapes arrive via stdout).
 
-import { appendFileSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
@@ -90,45 +90,11 @@ type Reason =
   | "brand-config-missing"
   | "cdp-port-unresolved";
 
-// Sticky flag: once a stream-log write fails (EACCES, ENOENT, …), skip
-// subsequent file writes for the rest of this process. Repeated appends to an
-// unwritable path would spam stderr with identical `phase=stream-log-write-failed`
-// lines and crowd result.stderr that the route handler regex reads. Losing a
-// log line is strictly better than aborting the scrape — observability failure
-// must not mask the scrape's real signal.
-let streamLogWriteFailed = false;
-
 function logPhase(line: string): void {
-  // Stderr: preserved for direct-SSH invocation parity AND for runFormSpawn's
-  // in-memory `result.stderr`, which the route handler greps for `reason=<enum>`
-  // on non-zero exit. Removing this write would break the form's error-card path.
+  // Stderr: the agent-via-Bash invocation streams the script's stderr into
+  // the PTY chat verbatim, so phase lines land in the operator's view
+  // alongside any other script output.
   process.stderr.write(`[list-cf-domains] ${line}\n`);
-
-  // Stream log: direct write by the TS helper (not via wrapper tee) so phase
-  // lines reach the per-conversation file the tailer reads, even on
-  // exit 0 where runFormSpawn discards `result.stderr`. Format parity with
-  // `_stream-log.sh phase_line`: `[<ISO-ts>] [script:<scope>] <content>\n` —
-  // the `script:` prefix is the chat-surface namespace so the line
-  // passes the tightened tailer regex (`[mcp:*]` / `[init]` / `[api-wait-*]`
-  // lines in the same file are excluded by construction). Asserted by the
-  // vitest regression under platform/ui/__tests__. Sync append so the
-  // terminal `phase=script-exit code=0 count=N` lands before process exit.
-  const streamLogPath = process.env.STREAM_LOG_PATH;
-  if (!streamLogPath || streamLogWriteFailed) return;
-  try {
-    appendFileSync(
-      streamLogPath,
-      `[${new Date().toISOString()}] [script:list-cf-domains] ${line}\n`,
-    );
-  } catch (err) {
-    streamLogWriteFailed = true;
-    const detail = (err instanceof Error ? err.message : String(err))
-      .slice(0, 200)
-      .replace(/"/g, "'");
-    process.stderr.write(
-      `[list-cf-domains] phase=stream-log-write-failed detail="${detail}"\n`,
-    );
-  }
 }
 
 function die(reason: Reason, detail = ""): never {

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -14,32 +14,32 @@
 # hostnames. The script writes the ingress rule for them but prints an
 # explicit ACTION REQUIRED message naming the manual dashboard step.
 #
-# Step 1 surfaces the argotunnel URL on stdout as an `OAUTH_URL:` line.
-# The admin UI renders that line as a clickable link (target=_blank) so the
-# operator authorizes Cloudflare in the same browser they are already using
-# to talk to the admin chat. The script spawns no browser of its own — the
-# operator's local browser is the canonical operator-visible surface; the
-# brand VNC iframe is derived/optional and never the OAuth-completion path.
-# cloudflared's stdout+stderr is teed line-by-line into STREAM_LOG_PATH so
-# the chat UI's server-side tailer renders live progress in-turn.
+# Step 1 surfaces the argotunnel URL on stdout as an `OAUTH_URL:` line. The
+# native Claude Code PTY linkifies bare URLs so the operator clicks it from
+# their admin chat directly. The script spawns no browser of its own.
+# cloudflared's stdout+stderr stream verbatim into the PTY chat alongside
+# the script's own `[setup-tunnel] step=<phase> …` phase lines.
 
 set -euo pipefail
 
 # Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
 # (see packages/create-maxy-code/src/index.ts:installTunnelScripts), so the raw
 # BASH_SOURCE[0] points at $HOME, not the scripts directory where the sibling
-# helpers (_stream-log.sh, tunnel-ingress.ts) live. Factored to SCRIPT_DIR so
-# the stream-log-contract scanner can statically resolve the
-# tunnel-ingress.ts target.
+# helper (tunnel-ingress.ts) lives.
 SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
 
 # --------------------------------------------------------------------------
-# Shared stream-log helpers (require STREAM_LOG_PATH, phase_line, …).
+# Phase-line helper. Stream-log plumbing retired in Task 287 — every
+# observation goes straight to stdout for the PTY to render. Format is
+# `[<scope>] <key>=<value> …` to keep operator-grep parity with the prior
+# `[<scope>] phase=…` shape that the now-deleted _stream-log.sh emitted.
 # --------------------------------------------------------------------------
 
-# shellcheck source=_stream-log.sh
-source "${SCRIPT_DIR}/_stream-log.sh"
-require_stream_log_path setup-tunnel
+phase_line() {
+  local scope=$1
+  shift
+  printf '[%s] %s\n' "${scope}" "$*"
+}
 
 # --------------------------------------------------------------------------
 # Args
@@ -123,13 +123,12 @@ fi
 #                                                   cert.pem, mv.
 #
 # Control flow when both certs are missing:
-#   1. Spawn cloudflared with stdout+stderr teed line-by-line to
-#      $STREAM_LOG_PATH with prefix [script:setup-tunnel:cloudflared]
-#      (the chat-surface namespace — see _stream-log.sh header).
+#   1. Spawn cloudflared; its stdout+stderr stream into the PTY via stderr
+#      prefixed with `[script:setup-tunnel:cloudflared]`.
 #   2. Extract the authorize URL with a tolerant regex as it streams.
-#   3. Print the URL on stdout as `OAUTH_URL: <url>` so the admin UI
-#      renders a clickable link. The script does not spawn a browser —
-#      the operator's local browser is the canonical surface; cloudflared's
+#   3. Print the URL on stdout as `OAUTH_URL: <url>` — the native Claude
+#      Code PTY linkifies it. The script does not spawn a browser; the
+#      operator's local browser is the canonical surface. cloudflared's
 #      OAuth callback writes ~/.cloudflared/cert.pem regardless of which
 #      browser completed the Authorize click (it's a server-to-server poll
 #      against login.cloudflareaccess.org).
@@ -192,16 +191,15 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   }
   trap cleanup_oauth EXIT
 
-  # cloudflared is line-buffered (stdbuf), teed to the stream log, URL
-  # extracted as it streams. The subshell holds the whole pipeline so
-  # PIPESTATUS[0] (cloudflared's exit code) is reachable later.
+  # cloudflared is line-buffered (stdbuf); each line is echoed verbatim into
+  # the PTY (stderr) while the OAuth URL is also extracted as it streams.
+  # The subshell holds the whole pipeline so PIPESTATUS[0] (cloudflared's
+  # exit code) is reachable later.
   (
     stdbuf -oL -eL cloudflared \
       --origincert "${CFG_DIR}/cert.pem" tunnel login 2>&1 |
       while IFS= read -r line; do
-        ts="$(stream_log_ts)"
-        printf '[%s] [script:setup-tunnel:cloudflared] %s\n' "${ts}" "${line}" >> "${STREAM_LOG_PATH}"
-        printf '%s\n' "${line}" >&2
+        printf '[script:setup-tunnel:cloudflared] %s\n' "${line}" >&2
         printf '%s\n' "${line}" > "${LAST_LINE_FILE}"
         if [ ! -s "${URL_FILE}" ]; then
           url="$(printf '%s' "${line}" | grep -oE 'https://dash\.cloudflare\.com/argotunnel\?[^ ]+' | head -1 || true)"
@@ -240,8 +238,8 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   AUTH_URL="$(cat "${URL_FILE}")"
   phase_line setup-tunnel step=oauth-url-extracted url_extracted=1
 
-  # Emit the URL on stdout in a shape ActionLogPanel's regex captures.
-  # The admin UI renders this line as a clickable link (target=_blank) so
+  # Emit the URL on stdout in a shape the PTY linkifies natively.
+  # The native Claude Code terminal renderer turns bare URLs into clicks so
   # the operator authorizes Cloudflare in the same browser they are using
   # for the admin chat. The script does not spawn a browser of its own.
   printf 'OAUTH_URL: %s\n' "${AUTH_URL}"

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -22,9 +22,9 @@ Any Cloudflare action outside these four surfaces is a discipline violation —
 
 Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, and dispatches the `${BRAND}.service` restart to a transient `systemd-run` unit — all in one invocation. The restart fires a few seconds after the script exits so the script does not kill its own cgroup when invoked via the Bash tool; the chat UI receives a `server_shutdown` SSE frame and reconnects automatically. Post-restart hostname verification is out of scope for the script (connector is not up when the script exits) — verify via the next admin turn or manually with `curl -I https://<hostname>`. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
 
-Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and prints it on its own stdout as `OAUTH_URL: <url>` plus a `step=oauth-url-extracted url_extracted=1` phase line. The admin UI's `ActionLogPanel` renders that `OAUTH_URL` line as a clickable Authorize link with `target=_blank`, opening a new tab in the operator's own browser — the canonical operator-visible OAuth surface. The wrapper does not spawn a browser of its own; cloudflared's OAuth callback polls Cloudflare server-to-server and writes `~/.cloudflared/cert.pem` regardless of which browser completed the Authorize click. The wrapper's cert-poll (180 s budget) picks the cert up and `mv`s it to the brand-scoped path. There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login` and surface the URL for the operator to click.
+Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and prints it on its own stdout as `OAUTH_URL: <url>` plus a `step=oauth-url-extracted url_extracted=1` phase line. The native Claude Code PTY linkifies bare URLs, so the `OAUTH_URL: <https…>` line surfaces in chat as a clickable link the operator opens in a new tab of their own browser — the canonical operator-visible OAuth surface. The wrapper does not spawn a browser of its own; cloudflared's OAuth callback polls Cloudflare server-to-server and writes `~/.cloudflared/cert.pem` regardless of which browser completed the Authorize click. The wrapper's cert-poll (180 s budget) picks the cert up and `mv`s it to the brand-scoped path. There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login` and surface the URL for the operator to click.
 
-**Operator-visible-surface doctrine.** The operator's visible surface is their local browser — the one already showing the admin UI. The brand VNC iframe is a derived, optional surface that the operator may or may not have open. Any agent claim that ties a UI outcome to a Pi-side surface (a brand VNC chromium tab, a `:N` display) is wrong by construction — the operator may not be watching that surface. Surfaces the agent can trust as operator-visible: the admin chat itself, the admin UI's ActionLogPanel banner, and links the operator clicked from either of those two. Everything else is best-effort.
+**Operator-visible-surface doctrine.** The operator's visible surface is the admin chat PTY itself plus their own local browser. Any agent claim that ties a UI outcome to a Pi-side surface (a brand VNC chromium tab, a `:N` display) is wrong by construction — the operator may not be watching that surface. Surfaces the agent can trust as operator-visible: the admin chat PTY (the script's stdout, including its `OAUTH_URL` line) and pages the operator opened from links rendered in that chat. Everything else is best-effort.
 
 ### How inputs reach the script
 
@@ -32,9 +32,10 @@ The agent collects inputs in plain chat, then invokes the script via Bash. Four
 
 Sequence:
 
-1. **Set the admin password** before invoking the script. Use the same endpoint onboarding uses — `curl -X POST http://127.0.0.1:${PORT}/api/remote-auth/set-password -H 'Content-Type: application/json' -d '{"password":"…"}'` — where `${PORT}` is read from `brand.json`.
+0. **Derive `BRAND` from disk.** `BRAND=$(jq -r .hostname ~/.<configDir>/brand.json)` — never hardcode `maxy` or any literal brand name. The same install can host different brands on different ports; the `brand.json.hostname` field is the only authoritative source. Substituting the wrong literal here cascades into a script writing to the wrong `~/.${BRAND}/` tree and restarting the wrong service.
+1. **Set the admin password only if not configured.** Gate on `[ -s "${HOME}/.${BRAND}/remote-password" ]` first — when the file is non-empty, a password already exists from a prior onboarding run. Skip the set step entirely. Only when the file is missing or empty, prompt the operator for the password and POST it to `curl -X POST http://127.0.0.1:${PORT}/api/remote-auth/set-password -H 'Content-Type: application/json' -d '{"password":"…"}'` (`${PORT}` from `brand.json`). Rotation requires the operator to ask for it explicitly — never re-set on every retry.
 2. **(Optional) enumerate existing tunnels** when the operator wants to pick from the logged-in account rather than create a new one. Invoke `cloudflared tunnel list --output json` via Bash, present the result as a numbered list, and let the operator type the number (use that tunnel's `id`) or a fresh name.
-3. **Invoke the script** with `~/setup-tunnel.sh <brand> <port> <admin-fqdn> [<public-fqdn>] [<apex-fqdn>]`. Pass either `TUNNEL_ID=<uuid>` (operator selected) or `TUNNEL_NAME=<name>` (operator named a new one) in env — exactly one. `STREAM_LOG_PATH` and `ACCOUNT_DIR` are resolved from `brand.json` and the `${HOME}/.${BRAND}/` layout.
+3. **Invoke the script** with `~/setup-tunnel.sh "$BRAND" "$PORT" "$ADMIN_FQDN" [<public-fqdn>] [<apex-fqdn>]`. Pass either `TUNNEL_ID=<uuid>` (operator selected) or `TUNNEL_NAME=<name>` (operator named a new one) in env — exactly one. `ACCOUNT_DIR` is resolved from the `${HOME}/.${BRAND}/` layout.
 4. **Alias-domain classification.** For each non-admin hostname that does not start with `public.`, append it to `~/{configDir}/alias-domains.json` so `isPublicHost()` treats it as public. The platform server watches that file (`watchFile`, ~2 s pickup) — no restart needed. Use this idempotent Bash command per hostname (HOST is the FQDN, FILE is `~/.${BRAND}/alias-domains.json`):
 
 ```bash
@@ -52,10 +53,14 @@ Repeated calls with the same hostname are a no-op (the `| unique` filter dedupes
 ~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]
 ```
 
-Example ({{productName}} on `maxy.bot` with a public subdomain and the `maxy.chat` apex):
+Examples — placeholders show the substitution shape; the literal `BRAND` always derives from `brand.json.hostname`:
 
 ```
-~/setup-tunnel.sh maxy 19200 admin.maxy.bot public.maxy.bot maxy.chat
+BRAND=$(jq -r .hostname ~/.maxy/brand.json)        # e.g. yields "maxy"
+~/setup-tunnel.sh "$BRAND" 19200 admin.maxy.bot public.maxy.bot maxy.chat
+
+BRAND=$(jq -r .hostname ~/.maxy-code/brand.json)   # e.g. yields "maxy-code"
+~/setup-tunnel.sh "$BRAND" 19200 admin.maxy.bot public.maxy.bot maxy.chat
 ```
 
 ### Optional SSH and SMB ingress
@@ -104,12 +109,12 @@ The agent invokes the script directly via the Bash tool — there is no form, no
 
 ### Narrating OAuth progress
 
-The script tees structured phase lines into the stream log (`[setup-tunnel] step=<phase> <key=value …>`). The admin UI renders the `OAUTH_URL` stdout line as a clickable Authorize link directly above the log panel; the operator clicks it and authorizes in a new tab of their own browser. The agent's narration job is to let that link do the work and not claim where any tab is open.
+The script prints structured phase lines to stdout (`[setup-tunnel] step=<phase> <key=value …>`) — these stream straight into the PTY chat verbatim. The `OAUTH_URL: <https…>` line is on a line by itself; the native Claude Code terminal renderer linkifies it so the operator clicks the link directly from chat and authorises in their own browser. The agent's narration job is to let that link do the work and not claim where any tab is open.
 
-- **When `step=oauth-url-extracted url_extracted=1` appears,** the URL is already surfaced as a clickable link in the operator's chat. The agent says one short line — "click the Authorize link and I'll pick up the cert once you've authorised" — and waits. No claim about which device or screen the link opens on; the operator's browser handles that.
+- **When `step=oauth-url-extracted url_extracted=1` appears,** the `OAUTH_URL: …` line above it is already clickable in the operator's chat. The agent says one short line — "click the Authorize link above and I'll pick up the cert once you've authorised" — and waits. No claim about which device or screen the link opens on; the operator's browser handles that.
 - **When `step=oauth-login result=ok reason=cert-promoted-from-default-path` appears,** a prior run already completed OAuth — Step 1 short-circuits to the existing cert. No operator action is needed.
 - **When `step=oauth-login result=error reason=<token>` appears,** the agent restates the literal `reason=…` and any `last_line=…` field and stops per the discipline rule below. The reasons that can fire on this path are `cloudflared-exited-before-url`, `url-not-extracted`, `timeout-waiting-cert`, `cloudflared-exited-no-cert`, and `cert-promote-failed`. `timeout-waiting-cert` specifically means the operator did not click Authorize within 180 s; the remediation is a fresh `~/setup-tunnel.sh` invocation, which will land on the cert-promotion pre-flight if the operator authorised after the timeout.
-- **Stream-log `result=ok` on its own steps is not narration evidence.** The agent narrates from operator-action outcomes — link clicked, cert landed — not from script-internal phase ticks.
+- **`result=ok` on a script-internal phase is not narration evidence.** The agent narrates from operator-action outcomes — link clicked, cert landed — not from internal phase ticks.
 
 ### When the script exits non-zero
 

package/payload/platform/plugins/docs/references/platform.md

@@ -62,7 +62,7 @@ The graph view (at `/graph`) lets you explore the memory directly. Pick a catego
 
 ## The Web Interface
 
-The web app runs on your Pi on port 19200. A small always-on front door (`maxy-edge`) owns that port and the remote terminal transport — so when the Software Update command restarts the app server, the browser-side terminal keeps streaming bytes exactly like an SSH session would. The edge also hosts the update flow's own routes (the sudo prompt, the action launcher, the SSE progress stream, the installed-version poll), so the Software Update modal's log panel does not go blank during the app-server restart window — it keeps receiving lines, heartbeats, and the final exit event unbroken. Login cookies are HMAC-signed with a shared key on disk, so both processes recognise the same session without any coordination and you do not have to log in again after an update. Every request is also classified as LAN or external based on the network shape it arrived on — LAN browsers reach admin directly; the remote password screen only appears on the tunnel-exposed admin domain. It provides:
+The web app runs on your Pi on port 19200. A small always-on front door (`maxy-edge`) owns that port. The edge also hosts the `/api/admin/version` route so the HeaderMenu version display keeps reading even during a mid-restart of the brand service. Login cookies are HMAC-signed with a shared key on disk, so both processes recognise the same session without any coordination and you do not have to log in again after an update. Every request is also classified as LAN or external based on the network shape it arrived on — LAN browsers reach admin directly; the remote password screen only appears on the tunnel-exposed admin domain. It provides:
 
 - **Admin chat** (at `/`) — your primary interface, PIN-protected
 - **Public chat** (at `/{agent-name}`) — visitor-facing agents, each with their own URL. On public hostnames, the root path serves the default agent.
@@ -108,31 +108,13 @@ The Data search panel ranks results by combining vector similarity with keyword
 
 ## Software Update and Cloudflare Setup
 
-There is no free-form terminal surface in the admin UI — ad-hoc shell access stays on SSH. The two flows that used to need a terminal (upgrade, Cloudflare tunnel setup) run as **detached actions** instead.
+Both flows run on the native Claude Code PTY surface in admin chat (Task 287). There is no in-app upgrade modal and no Cloudflare setup form — the agent invokes the relevant Bash command directly and its stdout streams into chat verbatim.
 
-**Software Update flow.** Click Upgrade in the modal → the modal asks for your sudo password once → the admin server validates it and launches a transient `systemd-run --user` unit running `npx -y @rubytech/create-maxy@latest`. The action unit is a peer of the brand service (not a child), so the installer's mid-run `systemctl --user restart maxy` does not kill the upgrade itself — it finishes running, then the web UI reloads on the new version. The modal shows a live log panel with three event types:
-- every stdout/stderr line the installer emits, timestamped server-side;
-- a heartbeat every 5 seconds carrying `state=active` + `last_phase` so you can see the installer is alive even during silent phases (tarball download, dep install);
-- a final banner on exit with the return code and elapsed time.
-
-If the browser drops the SSE connection mid-upgrade (typical during the maxy restart window), the panel reconnects within two seconds and replays any lines you missed from the persisted log.
+- **Software update.** Re-run the installer (`npx -y @rubytech/create-<brand>@latest`) from a shell; HeaderMenu's version row turns sage when `installed === latest`.
+- **Cloudflare setup.** Operator asks in chat; the agent invokes `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]` via the Bash tool. The script's `[setup-tunnel] step=<phase> …` phase lines and cloudflared's own stdout stream into the PTY; the `OAUTH_URL: <url>` line is linkified by the terminal so the operator clicks it and authorises Cloudflare in their own browser.
 
 **Mid-turn stream-drop banners.** If a chat turn ends abruptly the bubble shows one of two messages depending on what actually happened. You see "Server is restarting — reconnect will happen automatically." only when the app server itself emits the restart signal — typically during a Software Update or a Cloudflare setup that re-launches the brand service. You see "Lost connection — retrying." when your browser's connection to the Pi dropped mid-stream while the server was still up — typically a flaky Wi-Fi moment or the tunnel hiccupping. Either way the chat resumes once the connection is back; the previously-rendered messages stay on screen so you don't lose context.
 
-**Cloudflare setup flow.** Same pattern — POST to `/api/admin/cloudflare/setup` launches a `cloudflare-setup` action that runs `~/setup-tunnel.sh <brand> <port> <hostname...>`. When the script emits the OAuth consent URL on stdout, the log panel surfaces an **"Authorise in Cloudflare"** button; clicking it opens the consent page in a new tab. After you approve, the script's callback receives `cert.pem` and the setup continues through `tunnel create`/`route`/`run`. On devices where a VNC Chromium is also running, the script can drive the click via CDP automatically (same button remains a harmless safety net). Setup failures return a `CloudflareSetupError` carrying `inputsAlreadyHeld:{admin,public,apex}` and `discoveryResults:{tunnels,domains}` (from the process-lifetime discovery cache `/tunnels` and `/domains` populate on success); the form appends both fields as a fenced JSON block to the chat-relay body so the agent's next reply quotes held values verbatim rather than re-soliciting hostnames.
-
-**Active-chat stream-log click telemetry.** Clicking "Stream log" in the active chat fetches the URL inline (`/api/admin/logs?type=stream&conversationId=…&download=1`), emits a `[stream-log-click] status=<c> bytes=<n> conversationId=<tail>` line in `server.log` via the `/api/_client-error` event pipe, and downloads the same response. Operator-grep `[stream-log-click] status=404` for client/server identity mismatches.
-
-**Bundle-mtime session prelude.** Each admin session boot stamps `[boot] bundleMtime=<iso> conversationId=<tail>` in `server.log` next to `[plugins] MCP servers for session:`; the value is consumed by the Cloudflare setup route's retry-decision branch (it compares against the most recent terminal `:Task.completedAt`), never by the LLM. The prior `<deployment>` block was removed in 2026-05-13 doctrine fix because the admin LLM read it as narration permission for internal state; the route now owns the retry decision, the agent restates the literal envelope.
-
-**Post-action restatement block (2026-05-13 doctrine fix).** `assembleSystemPrompt` injects `<post-action>actionId=<id> outcome=<completed|failed> phase=<phase> at=<iso></post-action>` into the system prompt whenever the dispatcher resolves a terminal `:Task {kind:"cloudflare-tunnel-login"}` on the conversation. Agent-type-agnostic. The IDENTITY clause "If `<post-action>` is present, restate the literal outcome and stop" routes the operator-visible reply. Observability: `[post-action-block] injected|no-prior-action|lookup-failed` log line every turn.
-
-**Admin reply scrub (2026-05-13 doctrine fix).** Closed-list token scrub at `platform/ui/app/lib/admin-reply-scrub.ts`; tokens `bundle`, `bundleMtime`, `overnight`, `the fix may`, `was patched`, `re-rendering`, `paste the output`, `run the script`, `re-attempt`. Hit records a violation under `llm-narrates-internal-state` (rule_family `extension`) and emits `[admin-reply-scrub] agent=<name> tokens_found=[…] reply_blocked=false`. Future doctrine paragraphs naming a new internal token MUST extend the list in the same PR.
-
-**Sudo password** is prompted once per upgrade. The admin server pipes it to `sudo -S -v` to validate + cache, then forwards it to the action unit via `systemd-run --setenv=SUDO_PASSWORD` so the installer's in-unit `sudo -S` reads it directly — per-TTY sudoers configurations where the user-level cache does not cover a fresh systemd-run unit still work. The password is never written to any log, SSE frame, or persisted file.
-
-**Log files.** Each action writes its full output to `~/.maxy/logs/actions/<actionId>.log` for seven days. `journalctl --user --identifier=maxy-action-<actionId>` gives the systemd-level view.
-
 **Authorisation** is inherited from the same `canAccessAdmin()` gate that wraps every `/api/admin/*` route.
 
 ## AI Content Provenance

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -152,7 +152,7 @@ After this, every `console.error("[your-tool]...")` from any tool in the plugin
 
 **How the tee decides which file to write to:** the platform sets `STREAM_LOG_PATH` as an environment variable on every MCP server spawn, pointing to the conversation-scoped stream log. The MCP server does not know about conversations — it just trusts `STREAM_LOG_PATH`. Multiple concurrent conversations produce multiple concurrent MCP server processes, each teeing to its own file; no cross-conversation leakage.
 
-**`STREAM_LOG_PATH` reaches every Claude Code child.** The platform now sets `STREAM_LOG_PATH` on the parent `claude` spawn env itself (not only on MCP server envs), so the bundled Bun runtime inherits it and every Bash-tool subprocess the CLI spawns sees it too. Opt-in shell scripts — currently `setup-tunnel.sh`, `reset-tunnel.sh`, and `list-cf-domains.sh` under `platform/plugins/cloudflare/scripts/` — read the variable, guard against a missing value with a loud exit, and tee subprocess output line-by-line into the same per-conversation file. Each spawn writes one `[spawn-env] STREAM_LOG_PATH=set pid=… conversationId=… site=…` line so the env-propagation is auditable per session. The chat UI tails the same file for lines matching `^\[([^\]]+)\] \[([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] ` — any lowercase scope shape participates on first write (earlier platform fixes generalised from the pre-592 enum `setup-tunnel|reset-tunnel`) — and emits them as `script_stream` SSE events; see `.docs/web-chat.md` for the contract. Inner-layer helpers that a.sh wrapper spawns (e.g. `list-cf-domains.ts` via `node --experimental-strip-types`) must write phase lines directly to `STREAM_LOG_PATH` rather than relying on stderr propagation; the build-gate `platform/ui/scripts/check-stream-log-contract.mjs` enforces this and is the definitive reference for the three allowed patterns (tee-wrapped, direct-write, or explicit stderr-only marker).
+**Bash scripts stream straight into the PTY.** Maxy Code's admin and public chat run on the native Claude Code PTY (Task 287). The per-conversation server-side stream log that the retired web-UI dispatcher tailed is gone; agent-invoked shell scripts (`setup-tunnel.sh`, `reset-tunnel.sh`, `list-cf-domains.sh`) print `[<scope>] <key>=<value>` phase lines directly to stdout, which the PTY renders in chat verbatim.
 
 **Retrieve MCP diagnostic lines for a conversation:**