@rubytech/create-maxy-code 0.1.108 → 0.1.109

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

@@ -184,325 +184,13 @@ If the initial Cloudflare login fails during setup, {{productName}} will fall ba
 
 ---
 
-## Action runner — upgrade or Cloudflare setup appears stuck
 
-replaced the ttyd/xterm admin terminal with a detached action runner. Upgrades and Cloudflare setup now run under transient `systemd-run --user` units whose stdout+stderr land in a persisted per-action log, streamed to the browser via SSE. An earlier fix moved the four routes that serve the modal (`/api/admin/actions/*`, `/api/admin/version`) onto `maxy-edge.service`, so the log panel's stream survives a mid-run restart of `maxy.service` without reconnecting.
+## Software update and Cloudflare setup
 
-**"Connection lost — reconnecting…" banner appears during an upgrade.** On post-Task-666 bundles this should never appear while the upgrade is in flight — the routes live on the always-on edge. If you see the banner during steps 8→11 of an upgrade on a current bundle, it is a **regression**, not expected behaviour: the routes have drifted back onto `maxy.service` or the edge's Hono dispatcher is not intercepting them. Check `~/.maxy/logs/edge.log` for `[edge-admin]` entries during the window; absence means the edge never received the request. The prebuild gate `platform/ui/scripts/check-edge-admin-routes.mjs` exists specifically to catch this drift before it ships.
+Both flows run on the native Claude Code PTY surface in admin chat (Task 287). The retired action-runner / terminal-modal troubleshooting sections that lived here have been removed because those surfaces no longer exist; failures now manifest as plain stderr from the agent-invoked Bash command, visible in chat.
 
-**Agent does not respond to any message after a fresh install or restart.** The chat ingress quartet surfaces where the request silently stopped. From admin chat, ask the agent to read the chat-ingress timeline for the last 5 minutes — internally it runs `logs-read.sh --tail chat-attempts 5`, which cross-greps `edge.log` and `server.log` for the four checkpoints (edge inbound, admin-auth verdict, handler entry, edge outcome). Any missing row localises the failure: no edge inbound = request never reached the device (network, DNS, or cloudflare tunnel); inbound present + no auth verdict = handler unreachable (Hono routing regression); auth verdict = reject + a `code=` value the client banner matches; auth = accept + no handler entry = post-auth routing regression; all three rows present + no edge outcome = upstream crash or socket abort. See the developer doc `.docs/web-chat.md#chat-ingress-quartet` for the full state-machine and the prefix taxonomy.
-
-**Heartbeat stalled** (log panel header shows rising `silent Ns` amber badge).
-
-- Open the log panel header: `state: <systemd_state>` tells you the unit's current state.
-- `systemd_state: active` + silent >30s → the child is running but emitting nothing. Expected for `npx` while it downloads the tarball, or `cloudflared tunnel login` waiting for an operator click.
-- `systemd_state: inactive` + no `exit` event → the exit event was missed; the server-side heartbeat timer will emit it on the next 5 s tick.
-- `systemd_state: failed` → see the next symptom.
-
-**`ActiveState=failed`** (log panel's exit banner shows a non-zero code).
-
-- Read the persisted log directly: `~/.maxy/logs/actions/<actionId>.log` (or `.realagent/...`) has every stdout+stderr line the unit emitted.
-- `journalctl --user --identifier=maxy-action-<actionId>` shows systemd's own record including ExecStartPre/ExecStopPost if any.
-- Common cases:
-  - Wrong sudo password → `sudo: 1 incorrect password attempt` near the top of the log; re-open the upgrade modal, enter the correct password.
-  - Network failure during `npx` → `npm ERR! network` lines; re-open the modal and retry when network is restored.
-  - `cloudflared tunnel login` timed out waiting for OAuth → action exits non-zero with `Timed out after Ns waiting for cert.pem`; re-trigger from the Cloudflare setup form.
-
-**"Authorise in Cloudflare" button never appears** (cloudflare-setup action).
-
-The setup script emits either the raw `https://dash.cloudflare.com/argotunnel?...` URL in cloudflared's own stderr OR an explicit `OAUTH_URL: <url>` stdout line once URL extraction succeeds. The log panel's regex matches either. If neither appears within ~15 s of launch:
-
-- The action log file (`~/.maxy/logs/actions/<actionId>.log`) should show `[script:setup-tunnel:cloudflared]` lines. No such lines → cloudflared isn't spawning (check whether the binary is on PATH in the transient unit; `systemctl --user show maxy-action-<actionId>` reveals the environment).
-- Lines present but no URL → cloudflared output-format drift; file a task with the last 20 lines of the action log.
-
-**Log file missing (action stream returns 404).**
-
-The transient unit was auto-collected by systemd before the client subscribed. Race condition: action finished in <1 s. The per-action log file is retained for 7 days; look for it by name under `~/.maxy/logs/actions/`. If it isn't there, the unit failed before any output (check `journalctl --user -u maxy-action-<id>`).
-
-**Cloudflare-setup action card shows "Failed (exit null)" after the tunnel works.**
-
-> **Pre-Task-860 misdiagnosis.** Devices on platform versions misrender a successful `cloudflare-setup` run as red `Failed (exit null) · ~20s` because the script-armed brand-service restart kills the SSE generator before it can read the action's exit code. The Cloudflare side is fine in this case — the tunnel is created, DNS is routed, the brand service comes back up.
->
-> **First-line check:** open the persisted action log directly. Two markers prove success:
->
-> ```bash
-> grep -E 'step=service-restart-armed exit=0|step=done' \
-> ~/.{configDir}/logs/actions/cloudflare-setup-*.log | tail -2
-> ```
->
-> Both lines present in the log ⇒ the script succeeded; the UI banner is the bug, not the run. On post-Task-860 platforms the action card renders `Completed · Ns` on the same log shape; the card now distinguishes four states:
->
-> - `Completed` (green) — `code === 0` (whether reported by systemd or recovered from the log).
-> - `Failed (exit N)` (red) — non-zero exit reported by systemd. Real failure, follow the existing remediation paths.
-> - `Restart in progress` (neutral sage) — arming line present in log but the post-arm `step=done` was not written before the unit was GC'd. Resolves automatically once `/api/admin/version` responds; if it stays >90 s, falls through to amber.
-> - `Failed (exit unobserved)` (amber) — neither systemd nor the log can confirm a terminal state. Check `journalctl --user -u maxy-action-<id>`; the unit failed early or the log was truncated.
->
-> The server emits `[action-runner] reconcile actionId=<id> result=<succeeded|failed|restart-in-progress|unresolved> source=<systemd|persisted-log> ms=<n>` once per terminal-state resolution. Missing reconcile line on a finished run = stale platform; upgrade.
-
-**Cloudflare-setup auto-relays "completed" but the next chat turn 502s.**
-
-The current contract is a single client-driven resume: when the setup script exits cleanly, the form fires a resume event, the chat hook waits for `/api/health` to fail then succeed (the brand-service down-then-up cycle), re-binds the conversation to the new server process, and sends the "completed" marker as a normal hidden chat POST that re-invokes the agent in the operator's real session. No relay queue, no boot-drain, no banner.
-
-Diagnostic recipe:
-
-```
-grep '\[admin-resume\] reason=post-restart' ~/.maxy/logs/server.log | tail   # /resume server-side
-grep '\[session\] cookie-bridge accountId=' ~/.maxy/logs/server.log | tail   # session re-hydrated
-grep '\[persist\] .* role=user .* Cloudflare setup completed' ~/.maxy/logs/server.log | tail
-grep '\[client-event\] kind=post-restart-resume' ~/.maxy/logs/server.log | tail
-```
-
-Failure modes:
-- `[client-event] kind=post-restart-resume phase=start` absent: form's CustomEvent never reached the chat hook (regression in form `onExit` or chat-listener mount).
-- `[client-event] phase=start` present, `[admin-resume] reason=post-restart` absent: `waitForRestartCycle` exhausted its bound (brand never restarted) or `/resume` rejected — check `phase=health-timeout` / `phase=resume-rejected`.
-- All four present except `[persist] role=user … Cloudflare setup completed`: marker chat POST failed — check the chat surface for an inline error or a `phase=resume-error` line.
-- Refresh after a successful Cloudflare setup shows a visible `Cloudflare setup completed (actionId: …)` user bubble: the resume mappers' synthetic-marker suppression broke or the marker shape drifted. Server-side `[admin-resume] syntheticHidden=<n>` field on the same line counts user rows the client should hide (`_componentDone` envelopes, `_lifecycle` envelopes, and the `Cloudflare setup completed (actionId: …)` literal) — a count of 0 against a refresh that should have hidden one means the helper at `platform/ui/app/lib/synthetic-marker.ts` no longer recognises the producing literal (check `CloudflareSetupForm.tsx` and `useAdminChat.ts` for shape drift).
-
----
-
-## Software Update click shows an error instead of opening the terminal
-
-> **First-line diagnostic for the byte-stream xterm.js terminal surface:** `sudo systemctl --user status maxy-ttyd` plus `sudo grep 'ttyd-proxy' ~/.maxy/logs/edge-boot.log | tail -20`. Failure mode signals: `ttyd-ws-upgrade accepted` with no `ttyd-proxy-open` → `maxy-ttyd.service` is down; `ttyd-proxy-open` with no `ttyd-proxy-chunk dir=upstream→client` → ttyd/tmux is not attaching a PTY.
-
-**Symptom:** You clicked **Upgrade** in the Software Update modal, but instead of the VNC terminal overlay appearing, the modal shows a red error row like:
-
-```
-[terminal-launch] failed err="window absent from target display after spawn" pid=1234 display=:99 observed_windows=0 transport=vnc reason=upgrade
-```
-
-…and the Upgrade button re-labels to "Try again".
-
-**What it means:** `POST /api/admin/terminal/launch-upgrade` returned a 502 — the admin server tried to spawn a real terminal on the VNC display `:99` with `npx -y @rubytech/create-maxy@latest` pre-loaded, but the spawn failed or the window never appeared on the target display. The modal's upgrade path uses the same pipeline as the header-menu Terminal; if the operator Terminal button works, the VNC stack itself is healthy and the fault is usually a missing dep or a stale binary. If the operator Terminal also fails, start with the "Header Terminal click shows an error alert" section below.
-
-Step-by-step diagnosis — the error string in the modal is identical to the entry in `~/.maxy/logs/vnc-boot.log`, so you can grep it directly:
-
-```bash
-# 1. Find the latest upgrade launch attempt
-sudo grep 'action=launch-upgrade' ~/.maxy/logs/vnc-boot.log | tail -10
-
-# 2. See the script-level failure line (same string the modal shows)
-sudo tail -n 30 ~/.maxy/logs/terminal-launch.log
-
-# 3. Verify binaries are present
-which xterm xdotool
-
-# 4. Confirm the VNC display itself is up
-DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "display:99 ok" || echo "display dead"
-```
-
-**Common upgrade-specific failures:**
-
-- `err="no terminal emulator installed"` → run `sudo apt-get install -y xterm xdotool` or re-run `npx -y @rubytech/create-maxy@latest` — the installer provisions both as hard deps.
-- `err="spawn detached but no terminal PID visible within 1s"... reason=upgrade` → X server on `:99` is wedged. the VNC stack is owned by `maxy-edge`, so the recovery is `sudo systemctl --user restart maxy-edge` (cycles `vnc.sh start` via that unit's ExecStartPre). Then click **Try again** in the modal.
-- `err="window absent from target display after spawn"... reason=upgrade` → the spawn succeeded but landed on the wrong display (earlier platform fixes class). Re-run the installer to refresh the `resolve_terminal_bin` logic. If a stale `gnome-terminal` is hitting `:99` via D-Bus delegation, the installer's `xterm` fallback is the fix.
-- `err="xdotool not installed — re-run installer to repair"` → earlier platform fixes preflight. `sudo apt-get install -y xdotool` or re-run the installer.
-- `err="VNC failed to start after recovery attempt"` → `Xtigervnc` itself is not coming up. Inspect `~/.maxy/logs/vnc-boot.log` for tigervnc startup lines; `ss -ltn '(sport = 6080 or sport = 5900)'` should show both ports listening.
-
-**Click Try again** after applying any fix — the modal re-POSTs the launch-upgrade request.
-
----
-
-## Upgrade terminal stays black after clicking Upgrade (VNC WebSocket rejected)
-
-**Symptom:** The launch-upgrade POST returns 200 (the server-side spawn succeeded), but the browser's VNC iframe shows a black rectangle and the DevTools console spins on `WebSocket connection to '/websockify' failed` / `Connection closed (code: 1006)` every few seconds.
-
-**What it means:** The browser has a session cookie the `/websockify` auth gate refuses to accept., every rejection logs three fields that identify the failing layer:
-
-```bash
-sudo tail -200 ~/.maxy/logs/vnc-boot.log | grep 'decision="rejected"'
-```
-
-- `cookieHeaderPresent=false` → the browser never sent a cookie. Check the iframe context / SameSite policy / cookie domain. Most commonly: the user opened admin over HTTP instead of HTTPS, or the cookie is scoped to a different subdomain.
-- `cookieHeaderPresent=true tokenPresent=false` → the cookie is present but the server rejects its signature. This is either tampering or a corrupted/missing shared secret. Check that `~/.maxy/credentials/remote-session-secret` exists on disk (mode `0600`, 64 hex chars) and has not been recently overwritten.
-- `tokenExpired=true` → the 24h session TTL elapsed. Log in again.
-
-If the secret file is missing entirely, re-run `npx -y @rubytech/create-maxy@latest` — the installer provisions it idempotently, preserving an existing file on upgrade and creating a fresh one on first install.
-
----
-
-## Upgrade terminal opens but npx never runs
-
-**Symptom:** You clicked **Upgrade**, the VNC overlay opened with a visible shell prompt, but `npx -y @rubytech/create-maxy@latest` does not execute and the shell is idle.
-
-**What it means:** The VNC spawn succeeded but the binary-specific command dispatcher (xterm `-e` or gnome-terminal `--`) did not forward the command. Given the installer ships `xterm` on `:99` by default (with D-Bus-safe dispatching), the likely causes are:
-
-- A stale binary override has re-pointed `resolve_terminal_bin` to `gnome-terminal` on `:99` despite the fix.
-- A shell the operator manually spawned (via the header Terminal) wasn't killed before the upgrade click, and `ensureTerminalUpgrade`'s pre-kill step silently failed.
-
-**Check:**
-
-```bash
-# The spawned binary must appear in this log with the bash-c wrapper
-sudo grep 'started.*reason=upgrade' ~/.maxy/logs/terminal-launch.log | tail -3
-# Expected shape: started pid=<N> display=:99 cmd="/usr/bin/xterm... -e bash -c 'npx -y @rubytech/create-maxy@latest; exec bash'" transport=vnc windowPresent=true reason=upgrade
-```
-
-If the `cmd=` field does not contain `-e bash -c`, re-run the installer — the vnc.sh on the device is stale. If the command IS logged correctly but nothing is running, open the VNC overlay and type `history | tail` inside the shell — if the npx line is there, it ran and exited (check `~/.maxy/logs/install-*.log` for the exit status).
-
----
-
-## Header Terminal click shows an error alert
-
-**Symptom:** You opened the burger menu and clicked **Terminal**, but instead of the overlay appearing you got an inline error like "Terminal failed to start" or "VNC failed to start".
-
-**What it means:** `POST /api/admin/terminal/launch` returned a 502 — either the VNC stack on port 5900 is down or the terminal emulator could not be spawned on display `:99`. This is a VNC-stack or display-spawn failure.
-
-Step-by-step diagnosis:
-
-```bash
-# 1. Check the terminal-launch log for the specific failure reason
-sudo tail -n 50 ~/.maxy/logs/terminal-launch.log
-
-# 2. Check the node-side state machine (ensure-terminal entries)
-sudo grep ensure-terminal ~/.maxy/logs/vnc-boot.log | tail -20
-
-# 3. Verify the VNC display itself is healthy
-sudo ~/maxy/platform/scripts/vnc.sh status # should print "running"
-DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "display ok" || echo "display dead"
-
-# 4. Confirm a terminal binary is installed (xterm is the always-available fallback)
-which gnome-terminal; which xterm
-```
-
-Most common failures and fixes:
-
-- `[terminal-launch] failed err="no terminal emulator installed"` → run `sudo apt-get install -y xterm xdotool` (or re-run the installer, which installs both as dependencies).
-- `[terminal-launch] failed err="spawn detached but no terminal PID visible within 1s"` → X server on `:99` is wedged. `sudo systemctl --user restart maxy-ui` cycles the VNC stack via `vnc.sh start`.
-- `[terminal-launch] failed err="window absent from target display after spawn" pid=<N> display=:99 observed_windows=0` → the spawned emulator's window landed on the wrong display (earlier platform fixes — almost always a stale gnome-terminal binary on an upgraded install; the fix ships `xterm` as the `:99` default but a stale `resolve_terminal_bin` on an old bundle can still trigger it). Check `which gnome-terminal xterm xdotool` — all three should exist; if not, re-run the installer. Also check `DISPLAY=:99 xdotool search --onlyvisible --class '.'` manually: empty output confirms no window on `:99`; a non-empty result after a fresh click means the window IS there and the check itself is wrong (file an issue).
-- `ensure-terminal action="escalate-vnc-restart"` followed by `degraded` → `Xtigervnc` itself is not coming up. Check `~/.maxy/logs/vnc-boot.log` for the tigervnc startup lines.
-
-## Terminal fails after upgrade — `Invalid response` or `window absent from target display`
-
-**Symptom:** You upgraded a {{productName}} device and the header-menu **Terminal** click now fails — overlay shows `Invalid response`, or `terminal-launch.log` shows `[terminal-launch] failed err="window absent from target display after spawn" pid=<N> display=:99 observed_windows=0 transport=vnc cmd="/usr/bin/xterm "`. The terminal worked on the previous version and the upgrade reported success.
-
-**What it means:** The installer declared a new apt dep between versions (e.g. `xdotool` in 1.0.667), but on your device the installer's apt step was silently skipped because `sudo` requires a password and the installer could not escalate non-interactively. The declared dep was never installed, and `vnc.sh check_window_on_display` then either failed to find the binary (exit 127 now surfaces this as a distinct `failed err="xdotool not installed — re-run installer to repair"` line) or reached the `window absent` path because its preflight tool was missing. See `.docs/deployment.md` ("sudo interactivity contract") for the full mechanism.
-
-**Check:**
-
-```bash
-dpkg -s xdotool 2>&1 | head -2 # should report "Status: install ok installed"
-which xdotool # should return /usr/bin/xdotool
-```
-
-**Fix — two options:**
-
-1. **Re-run the installer from an interactive shell** (preferred on upgrade — picks up any future missing deps too):
-
-   ```bash
-   npx -y @rubytech/create-maxy@latest
-   ```
-
-   The installer now probes `dpkg -s` for every declared apt dep and either prompts you for your sudo password to install missing ones, or loud-fails non-interactively with the exact `sudo apt-get install -y <list>` command to repair. It will no longer print `Skipping apt-get (deps assumed present from prior install)` and continue as if green.
-
-2. **Repair manually** (faster if you only want the one binary):
-
-   ```bash
-   sudo apt-get install -y xdotool
-   ```
-
-   Then click **Terminal** again — it should spawn within a second and the overlay should render the xterm.
-
-**Regression boundary:** if you see `[terminal-launch] failed err="xdotool not installed — re-run installer to repair"` in `~/.maxy/logs/terminal-launch.log`, the vnc.sh preflight is telling you the binary is missing before spawn — same class as above, distinct from the earlier platform fixes `window absent from target display after spawn` string. The two strings never appear for the same click.
-
----
-
-## Installer aborts on Ubuntu 24.04 with `dpkg -s: chromium`
-
-**Symptom:** On a fresh (or re-run) `npx -y @rubytech/create-maxy@latest` on an Ubuntu 24.04 Noble laptop/desktop, step 1/12 aborts:
-
-```
-[1/12] System dependencies and network...
-  Missing apt deps (1): chromium
-  apt install (VNC stack): tigervnc-standalone-server python3-websockify novnc xdg-utils chromium xterm xdotool
-> sudo apt-get install -y... chromium...
-  OK in 0.3s
-[ERROR] Setup failed: apt-get install (VNC stack) returned 0 but packages are still not installed per dpkg -s: chromium
-```
-
-Directly probing the device shows `dpkg -s chromium` non-zero, `apt-cache policy chromium` reports `Candidate: (none)`, but `/usr/bin/chromium` exists and works, and `snap list chromium` shows the snap is installed.
-
-**What it means:** You are on a **pre-637 installer**. On Noble, `chromium` is a virtual package aliasing to `chromium-browser` — `apt-get install chromium` succeeds silently but nothing named `chromium` ever lands in dpkg's state DB. the post-install probe (correctly) notices the discrepancy and aborts. An earlier fix added alias resolution (`chromium` → `chromium-browser`) so the probe matches the dpkg-recorded name and passes.
-
-**Fix:** Upgrade to a post-637 version of `@rubytech/create-maxy`:
-
-```bash
-npx -y @rubytech/create-maxy@latest
-```
-
-**Manual bypass** (if you must install before 637 publishes, or if you're on a restricted shell): pre-install the real.deb name and re-run the installer.
-
-```bash
-sudo apt-get install -y chromium-browser
-npx -y @rubytech/create-maxy@latest
-```
-
-The installer's resolver will then see `dpkg -s chromium-browser` exit 0 for the alias target, filter `chromium` out of the missing set, and skip the apt-install branch entirely. Raspberry Pi OS (Debian 12 Bookworm) is unaffected — `chromium` IS a concrete.deb on Bookworm.
-
-**Deeper diagnostic**: post-637 installer logs carry the full classification in the error message itself — `(resolved-name=<name>, apt-cache-policy=<summary>, command-v=<path>, snap-status=<summary>)`. If you see that longer form and still fail, the apt state itself is inconsistent (snap removed, `chromium-browser` uninstalled after previous install) — repair with `sudo apt-get install --reinstall -y chromium-browser`.
-
----
-
-## VNC browser will not start on Linux laptop — `Permission denied (13)` on SingletonLock
-
-**Symptom:** Boot log `~/.{brand}/logs/vnc-boot.log` shows:
-
-```
-Starting Chromium on :<vncDisplay> (vnc) profile=/home/<user>/.{brand}/chromium-profile CDP=:<cdpPort>
-ERROR:chrome/browser/process_singleton_posix.cc:345] Failed to create
-  /home/<user>/.{brand}/chromium-profile/SingletonLock: Permission denied (13)
-ERROR: Chromium failed to start on :<vncDisplay> (vnc) — CDP port <cdpPort> not listening (browser-specialist degraded)
-```
-
-`dmesg` (or `journalctl -k`) shows AppArmor `DENIED` lines naming `profile="snap.chromium.chromium"` and the `~/.{brand}/chromium-profile/` path. The brand admin chat reports the public-agent VNC browser as unavailable.
-
-**What it means:** Your `/usr/bin/chromium` is a snap symlink. Snap's AppArmor profile excludes hidden top-level paths under `$HOME` from its `home` interface, so writes to per-brand Chromium profile dirs at `~/.maxy/chromium-profile/` and `~/.realagent/chromium-profile/` are denied — Chromium cannot create its `SingletonLock` and never starts the CDP listener. This is exclusively a Linux-laptop problem (Ubuntu Noble); Raspberry Pi OS Bookworm ships `chromium` as a real `.deb` and is unaffected.
-
-**Fix:** Re-run the installer at version 1.0.849 or later. The installer detects the snap-confined chromium during system-dependency setup and replaces it with Google Chrome stable from Google's signed apt repo:
-
-```bash
-npx -y @rubytech/create-maxy@latest
-```
-
-The resolved non-snap binary path is recorded at `<INSTALL_DIR>/platform/config/chromium-binary.path` (single line) and read by every Chromium call site (VNC service, in-page wrapper, Playwright server). After re-running, verify with the bundled acceptance script:
-
-```bash
-MAXY_PLATFORM_ROOT=$HOME/<install-dir>/platform $HOME/<install-dir>/platform/scripts/test-laptop-vnc-boot.sh
-```
-
-The script exits 0 only when (1) the configured Chromium realpath is non-snap, (2) the path is absolute and executable, (3) the per-brand CDP port returns Chromium version JSON, and (4) `vnc-boot.log` since the last `[vnc.sh] start` ends with `VNC + browser stack running` and contains no `Chromium failed to start` line.
-
-**Deeper diagnostic:** `vnc.sh` and the in-page wrapper now refuse to start (and exit with a snap-Chromium reference in the boot log) when `chromium-binary.path` is absent or its realpath lands under `/snap/`. If you see those messages, the install completed before the fix shipped — re-run `npx -y @rubytech/create-maxy@latest`. Manual workaround for an emergency (not a fix): `sudo apt-get install -y google-chrome-stable` and confirm `which google-chrome-stable` is non-snap, then re-run the installer to write `chromium-binary.path`.
-
----
-
-## Terminal iframe renders black and cursor vanishes over the canvas
-
-**Symptom:** Header-menu Terminal click appears to succeed — no error toast, overlay opens — but the iframe renders uniformly black, keystrokes do not reach any shell, and the mouse cursor disappears the moment it enters the iframe (visible elsewhere in the page).
-
-**What it means:** This is the exact symptom class that earlier platform fixes closed. Before 632, `/usr/bin/gnome-terminal` would receive `DISPLAY=:99` but D-Bus-delegate the window-create request to the session's `gnome-terminal-server`, which opens the window on `:0` (the operator's physical screen) instead. The iframe, rendering `:99`, has no window to show — hence the black canvas, dead keystrokes, and null-cursor (noVNC's Cursor pseudo-encoding renders `cursor: none` when the server sends no cursor). If you are seeing this *after* earlier platform fixes shipped, the installer did not run on this device or a stale bundle is in place.
-
-Step-by-step diagnosis:
-
-```bash
-# 1. Check terminal-launch.log for the window-absent failure
-sudo grep 'window absent from target display' ~/.maxy/logs/terminal-launch.log | tail -5
-
-# 2. Verify the expected binaries are installed
-which xterm xdotool # both must exist — installer adds them
-
-# 3. Confirm the VNC display is serving the iframe
-DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "display:99 ok"
-DISPLAY=:99 xdotool search --onlyvisible --class '.' # non-empty means windows ARE on:99
-
-# 4. Check which binary resolve_terminal_bin chose
-grep 'cmd=' ~/.maxy/logs/terminal-launch.log | tail -3
-# Expected for remote-origin clicks: cmd="/usr/bin/xterm"
-# If you see: cmd="/usr/bin/gnome-terminal --wait" on:99 → stale bundle, re-run installer
-```
-
-If the failure log shows `window absent from target display`, the fix already ran but spawn still went to the wrong display — re-run the installer (`npx -y @rubytech/create-maxy@latest`) from a shell to pick up the latest `xterm` + `xdotool` preflight. If the failure log shows no recent entries and the iframe is still black, check `ss -ltn '(sport = 6080 or sport = 5900)'` and `pgrep -af Xtigervnc|websockify` — the symptom might be a VNC-stack regression rather than a terminal-binary mismatch.
-
-Both the header Terminal and the Software Update modal's Upgrade button now share the same VNC spawn pipeline, so a failure in one usually reproduces in the other — if the header Terminal opens a blank shell cleanly but the Upgrade modal errors, the problem is upgrade-specific (see "Software Update click shows an error" above).
+- **Software update.** Re-run `npx -y @rubytech/create-<brand>@latest` from a shell; if the installer fails, its stdout is the diagnostic record. HeaderMenu turns sage when `installed === latest`.
+- **Cloudflare setup.** The agent invokes `~/setup-tunnel.sh` via Bash. Failures surface as the script's own `[setup-tunnel] step=… result=error reason=…` lines in chat plus a non-zero exit. Recovery paths live in the cloudflare plugin's `references/reset-guide.md` and `references/manual-setup.md`.
 
 ## Orphan Account Directory Archived to `.trash/`
 

package/payload/platform/plugins/venture-studio/PLUGIN.md

@@ -23,13 +23,44 @@ Outcome (binding):
 
 Constraint (binding): **No downstream venture-studio skill (`brand-pack`, `zero-to-prototype`, `investor-data-room` Stages 3+, etc.) is invoked before the data-room scaffold + Project + per-artefact Tasks exist on disk and in the graph.** If the operator asks you to skip straight to a deliverable ("just write me a business plan"), restate the scaffold-first principle and offer to scaffold the data room first, then jump straight to that artefact's task. The principle is the outcome contract; the scaffold proves it.
 
+### Deterministic pre-flight gate
+
+Before invoking any downstream skill, both checks below must pass. Both are deterministic — exit-code on `ls`, structured output on `project-list`. Neither check depends on LLM judgement.
+
+1. **Directory check:** `[ -d "${PROJECT_ROOT}/.docs/data-room/01-narrative" ]` returns exit 0.
+2. **Graph check:** the `project-list` tool returns a Project whose `name` matches the business's working name.
+
+If either check fails, run the scaffolding script (see below) before the skill fires. If the script fails, surface the literal stderr error to the operator — do not narrate around it (memory: [[feedback_no_stdout_parsing_for_control_flow]]).
+
+### Scaffolding script
+
+`bin/scaffold.sh` is the deterministic enforcement layer. It creates the Project + eight artefact Tasks (via the work plugin's `project-create-cli` bridge) and materialises the ten-section directory tree. Graph write first, directories second; idempotent re-run if any partial state lands.
+
+```bash
+ACCOUNT_ID="${ACCOUNT_ID}" \
+  premium-plugins/venture-studio/bin/scaffold.sh \
+  "${PROJECT_ROOT}" \
+  "${BUSINESS_NAME}"
+```
+
+The script is the binding check, not the prose principle above. The prose explains why; the script is what makes it true.
+
 ## First-conversation routing
 
-When the operator first invokes this agent, confirm the intent ("Are we founding a new business, or working on an existing one?") and run the scaffolding sequence:
+When the operator first invokes this agent, confirm the intent ("Are we founding a new business, or working on an existing one?") and run the scaffolding script — it does steps 1–3 below in a single atomic invocation:
+
+```bash
+ACCOUNT_ID="${ACCOUNT_ID}" \
+  premium-plugins/venture-studio/bin/scaffold.sh \
+  "${PROJECT_ROOT}" \
+  "${BUSINESS_NAME}"
+```
+
+The script's three effects:
 
-1. **Scaffold the data room.** Invoke the `investor-data-room` skill Stage 2 — it creates the ten-section graph under the operator's project root (`<project-site>/.docs/data-room/`). The tree is named upfront so every artefact has a slot to land in.
-2. **Create the `Project` node.** Use the `projects` plugin's `project-create` tool with tier `full` (data-room work is multi-phase). Project name is the business's working name; description references the data-room root path. The `project-create` call accepts a work-items list — pre-seed it with the artefact tasks below in one transaction.
-3. **Enumerate Tasks per artefact**, one per data-room section / output document, in section order. Suggested task list (the `project-create` tool accepts these as `workItems`):
+1. **Scaffolds the data room.** Materialises the ten-section directory tree under `<project-root>/.docs/data-room/`. Every artefact has a slot to land in before any artefact is produced.
+2. **Creates the `Project` node.** Tier `full` (data-room work is multi-phase). Project name is the business's working name; description references the data-room root path.
+3. **Enumerates the eight artefact Tasks** in section order — one transaction, atomic with the Project. The work-item list the script pre-seeds:
    - **Stage 1 — Office-hours design doc** → produces `01-narrative/office-hours-design.md` (skill: `office-hours`)
    - **Brand pack** → produces brand identity files into `06-product-ip/brand/` (skill: `brand-pack`)
    - **Stage 2 — Wedge validation + landing page + PRD** → produces `01-narrative/{PMF, LANDING, PRD}.md` (skill: `zero-to-prototype`)

package/payload/platform/plugins/venture-studio/bin/scaffold.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Venture-studio data-room scaffold — deterministic enforcement of the
+# scaffold-first principle (Task 286 + feedback_doctrine_paragraph_is_not_a_gate).
+#
+# Creates exactly one Project (with eight pre-seeded artefact Tasks) in
+# the graph, then materialises the ten-section data-room directory tree
+# on disk. The venture-studio agent's downstream skills are gated on
+# both signals existing — see venture-studio/PLUGIN.md.
+#
+# Order of operations: graph write first, directories second. The CLI's
+# duplicate-name guard makes the script safely re-runnable after any
+# partial failure: a second run finds the existing Project, returns its
+# id, and retries the mkdir step.
+#
+# Usage:
+#   ACCOUNT_ID=<uuid> scaffold.sh <project-root> <business-name>
+#
+# Exit codes:
+#   0   scaffold complete (or already existed)
+#   2   bad arguments / missing ACCOUNT_ID
+#   1   graph write failed, directory mkdir failed, or CLI binary missing
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Deployed layout per packages/create-maxy-code/scripts/bundle.js:
+#   <install>/premium-plugins/venture-studio/bin/scaffold.sh
+#   <install>/platform/plugins/work/mcp/dist/cli/project-create-cli.js
+CLI_BIN="${SCRIPT_DIR}/../../../platform/plugins/work/mcp/dist/cli/project-create-cli.js"
+
+if [[ $# -ne 2 ]]; then
+  echo "scaffold.sh: usage: ACCOUNT_ID=<uuid> $0 <project-root> <business-name>" >&2
+  exit 2
+fi
+
+PROJECT_ROOT="$1"
+BUSINESS_NAME="$2"
+
+if [[ -z "${ACCOUNT_ID:-}" ]]; then
+  echo "scaffold.sh: ACCOUNT_ID env var required" >&2
+  exit 2
+fi
+
+if [[ ! -d "$PROJECT_ROOT" ]]; then
+  echo "scaffold.sh: project root does not exist: $PROJECT_ROOT" >&2
+  exit 2
+fi
+
+if [[ ! -f "$CLI_BIN" ]]; then
+  echo "scaffold.sh: project-create CLI not built or missing at: $CLI_BIN" >&2
+  exit 1
+fi
+
+DATA_ROOM="${PROJECT_ROOT}/.docs/data-room"
+
+# Eight pre-seeded artefact tasks — order and names match
+# premium-plugins/venture-studio/PLUGIN.md § First-conversation routing.
+# Section order is preserved so the agent can walk them sequentially.
+PAYLOAD=$(cat <<JSON
+{
+  "accountId": "${ACCOUNT_ID}",
+  "name": "${BUSINESS_NAME}",
+  "description": "Venture-studio data room for ${BUSINESS_NAME}. Root: ${DATA_ROOM}",
+  "tier": "full",
+  "workItems": [
+    {"name": "Stage 1 — Office-hours design doc", "description": "Produces 01-narrative/office-hours-design.md via the office-hours skill."},
+    {"name": "Brand pack", "description": "Produces brand identity (palette, typography, logo) into 06-product-ip/brand/ via the brand-pack skill."},
+    {"name": "Stage 2 — Wedge validation + landing page + PRD", "description": "Produces 01-narrative/{PMF,LANDING,PRD}.md via the zero-to-prototype skill."},
+    {"name": "Stage 3 — Business plan", "description": "Produces 01-narrative/business-plan.md via investor-data-room Stage 3."},
+    {"name": "Stage 3b — Term sheet", "description": "Produces html/prospectus/term_sheet.html via investor-data-room Stage 3b."},
+    {"name": "Stage 4 — Deck blueprint", "description": "Produces 01-narrative/deck-blueprint.md via investor-data-room Stage 4."},
+    {"name": "Stage 4b — Prospectus", "description": "Produces html/prospectus/index.html via investor-data-room Stage 4b."},
+    {"name": "Stage 5 — Rendered PDFs", "description": "Produces html/{business-plan,prospectus,deck}/*.pdf via investor-data-room Stage 5."}
+  ]
+}
+JSON
+)
+
+# Graph write first. CLI returns {projectId, existing:bool} on stdout;
+# on any failure it exits non-zero with a literal stderr message that
+# propagates here verbatim — no prose-parsing for control flow
+# (memory: feedback_no_stdout_parsing_for_control_flow).
+RESULT=$(node "$CLI_BIN" "$PAYLOAD")
+echo "scaffold.sh: project-create CLI returned: $RESULT"
+
+# Directories second. The agent's pre-flight gate keys on the existence
+# of 01-narrative/ (it AND-checks with project-list); creating it last
+# means partial state (graph-only) is naturally invisible to the gate
+# until mkdir succeeds.
+for section in \
+  01-narrative \
+  02-corporate-legal \
+  03-cap-table \
+  04-financials \
+  05-team \
+  06-product-ip \
+  07-customers \
+  08-market \
+  09-traction-metrics \
+  10-supporting; do
+  mkdir -p "${DATA_ROOM}/${section}"
+done
+
+echo "scaffold.sh: data-room scaffolded at ${DATA_ROOM}"

package/payload/platform/plugins/venture-studio/skills/investor-data-room/SKILL.md

@@ -96,7 +96,9 @@ This file is the working substrate. It stays internal-only. Every later artefact
 
 ## Stage 2 — Data room scaffold
 
-Build the directory tree above. Each section gets a `README.md` that doubles as a content checklist (purpose, expected contents, current state, gaps). The graph structure is fixed: ten numbered sections (`01-narrative` through `10-supporting`) plus a top-level README and an `html/` subdirectory for rendered deliverables.
+When invoked under the venture-studio agent, scaffolding is done by the deterministic script at `premium-plugins/venture-studio/bin/scaffold.sh` — it creates the Project + eight artefact Tasks and the ten-section directory tree in one atomic invocation. The script is idempotent; re-runs against an existing data room are a no-op. See `venture-studio/PLUGIN.md` § "Scaffolding script".
+
+When invoked outside the venture-studio agent (standalone usage of this skill), build the directory tree manually. Each section gets a `README.md` that doubles as a content checklist (purpose, expected contents, current state, gaps). The graph structure is fixed: ten numbered sections (`01-narrative` through `10-supporting`) plus a top-level README and an `html/` subdirectory for rendered deliverables.
 
 **File-naming conventions:**
 

package/payload/platform/plugins/work/mcp/dist/cli/project-create-cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=project-create-cli.d.ts.map

package/payload/platform/plugins/work/mcp/dist/cli/project-create-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-create-cli.d.ts","sourceRoot":"","sources":["../../src/cli/project-create-cli.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/work/mcp/dist/cli/project-create-cli.js

@@ -0,0 +1,78 @@
+// CLI bridge for shell scripts that need to scaffold a Project + Tasks
+// atomically (e.g. premium-plugins/venture-studio/bin/scaffold.sh). The
+// scaffold script is the deterministic enforcement layer for the
+// venture-studio scaffold-first principle (see Task 286 +
+// feedback_doctrine_paragraph_is_not_a_gate); to remain deterministic it
+// must invoke a single binary, not narrate intent for the LLM. This CLI
+// is that binary.
+//
+// Contract:
+//   node project-create-cli.js '<json-payload>'
+//   payload: { accountId, name, description, tier, workItems[], createdBy }
+//   exit 0 + stdout JSON { projectId, existing: boolean } on success
+//   exit non-zero + literal stderr message on any failure
+//
+// Idempotency guard lives here, NOT in projectCreate(). projectCreate()
+// always mints a fresh UUID — modifying it to MERGE on (accountId, name)
+// would change semantics for every existing caller. The CLI runs a
+// pre-check MATCH on (accountId, name); if a Project exists, it returns
+// the existing projectId with existing=true and skips the write. This
+// makes the scaffold script safely re-runnable after a partial failure
+// (e.g. graph write succeeds but mkdir fails — second run finds the
+// Project and only retries mkdir).
+import { projectCreate } from "../tools/project-create.js";
+import { getDriver } from "../lib/neo4j.js";
+async function findExistingProject(accountId, name) {
+    const driver = getDriver();
+    const session = driver.session();
+    try {
+        const result = await session.run(`MATCH (p:Project {accountId: $accountId, name: $name})
+       RETURN p.taskId AS projectId LIMIT 1`, { accountId, name });
+        if (result.records.length === 0)
+            return null;
+        return result.records[0].get("projectId");
+    }
+    finally {
+        await session.close();
+    }
+}
+async function main() {
+    const raw = process.argv[2];
+    if (!raw) {
+        process.stderr.write("project-create-cli: missing JSON payload argument\n");
+        process.exit(2);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`project-create-cli: malformed JSON payload: ${err.message}\n`);
+        process.exit(2);
+    }
+    if (!payload.accountId || !payload.name) {
+        process.stderr.write("project-create-cli: payload missing required field (accountId, name)\n");
+        process.exit(2);
+    }
+    const createdBy = payload.createdBy ?? {
+        tool: "project-create-cli",
+        source: "scaffold-script",
+    };
+    const existing = await findExistingProject(payload.accountId, payload.name);
+    if (existing) {
+        process.stdout.write(JSON.stringify({ projectId: existing, existing: true }) + "\n");
+        return;
+    }
+    const result = await projectCreate({
+        ...payload,
+        createdBy,
+    });
+    process.stdout.write(JSON.stringify({ projectId: result.projectId, existing: false, childTaskIds: result.childTaskIds }) + "\n");
+}
+main()
+    .then(() => process.exit(0))
+    .catch((err) => {
+    process.stderr.write(`project-create-cli: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=project-create-cli.js.map

package/payload/platform/plugins/work/mcp/dist/cli/project-create-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-create-cli.js","sourceRoot":"","sources":["../../src/cli/project-create-cli.ts"],"names":[],"mappings":"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"}

package/payload/platform/scripts/vnc.sh

@@ -323,9 +323,10 @@ start_chrome() {
 }
 
 # ---------------------------------------------------------------------------
-# retired the admin-UI terminal surface entirely: the header
-# TerminalOverlay + UpdateModal embedded terminal stack is gone. Only
-# the Chromium surface remains for BrowserOverlay.
+# Retired in Task 287: the admin-UI terminal and browser-overlay surfaces
+# are gone. This script still launches Chromium for legacy installs where
+# the brand VNC is used for ad-hoc operator browsing; on maxy-code the
+# admin chat PTY is the only interactive surface.
 # ---------------------------------------------------------------------------
 
 start_chrome_native() {