@rubytech/create-siteoffice-code 0.1.256

package/payload/premium-plugins/venture-studio/skills/prototype-host/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: prototype-host
+description: Use when the operator asks to "host the landing", "host the prototype", "deploy this", "give me a public URL", or any variant that means "make the landing page or wedge prototype reachable on a real URL the founder can send to a customer". Scaffolds a source tree, allocates a local port, edits the brand's cloudflared ingress, creates a DNS row, runs the dev server (or static file-server) under a systemd-user unit, and verifies HTTP 200 from outside the box. Idempotent: re-run for the same surface restarts cleanly without duplicating ports, ingress rows, or units.
+---
+
+# prototype-host
+
+## Outcome
+
+A founder asks "host the landing" or "host the prototype" and ends the turn with a working public URL — `https://<surface>.<brand-hostname>` — that returns HTTP 200, backed by a dev server (or static file server) supervised by systemd so it survives reboot. No CI, no Vercel, no Pages — the install device itself serves the prototype through the brand's existing cloudflared tunnel.
+
+The skill is a composition of primitives that already exist on every Maxy Code install: cloudflared multi-hostname ingress (see [`cloudflared/references/manual-setup.md`](../../../../platform/plugins/cloudflare/references/manual-setup.md)), `systemctl --user` unit files for per-process supervision, and the agent's Bash + Read + Write + Edit tools for source scaffolding. The skill's job is to compose them deterministically so the founder never has to.
+
+## Inputs
+
+The agent gathers these before invoking any of the six phases. Defaults below; use `AskUserQuestion` only when the operator's intent is ambiguous about surface name or framework.
+
+| Input | Default | Notes |
+|---|---|---|
+| `surface` | `landing` for "host the landing"; `prototype` for "host the prototype"; otherwise ask | The DNS label; becomes `<surface>.<brand-hostname>`. Lowercase, kebab-case, must be a valid DNS label (`^[a-z0-9-]+$`, max 63 chars). |
+| `framework` | `static` for `landing`; `vite` for `prototype` | One of `static`, `vite`, `next`, `sveltekit`, `astro`. See [`references/scaffold-frameworks.md`](references/scaffold-frameworks.md). |
+| `surface-dir` | `${PROJECT_ROOT}/.docs/data-room/prototype/<surface>/` | Source tree root. |
+
+Two environment values the skill derives, never asks for:
+
+- `BRAND` — from `jq -r '.hostname' <PROJECT_ROOT>/platform/config/brand.json` (same idiom every other skill uses).
+- `BRAND_HOSTNAME` — the cloudflared root domain for this install: `jq -r '.cloudflareRootDomain // .hostname' <PROJECT_ROOT>/platform/config/brand.json`. If the field is empty, abort with literal stderr `[prototype-host] FATAL brand-hostname-unresolved — set cloudflareRootDomain in brand.json`.
+
+## Hard prerequisite — brand-pack must have run
+
+Before phase 1, check `[ -d "${PROJECT_ROOT}/.docs/data-room/06-product-ip/brand" ]` and `[ -n "$(ls -A "${PROJECT_ROOT}/.docs/data-room/06-product-ip/brand" 2>/dev/null)" ]`. If either fails, abort:
+
+```
+[prototype-host] FATAL brand-pack-missing — run brand-pack first; hosted surfaces consume 06-product-ip/brand/{color-palette,typography-system,tone-of-voice}.md
+```
+
+This is doctrinal — hosting a brandless landing ships a surface that either confounds conversion data or forces a re-render after brand-pack. The check is exit-code, not LLM judgement.
+
+## Phases
+
+Every phase emits exactly one structured stdout line on success:
+
+```
+[prototype-host] phase=<n> surface=<surface> framework=<framework> port=<port> ingress=<state> dns=<state> service=<unit> status=<systemd-state> http=<code>
+```
+
+Any phase that cannot produce its key/value pair fails by emitting literal stderr (no narration, no retry, no menu-phrasings — [[feedback_no_stdout_parsing_for_control_flow]]) and exits non-zero. The agent surfaces the stderr verbatim to the operator.
+
+### Phase 1 — Surface intake (idempotency check)
+
+If `<surface-dir>/.port` exists, this is a re-run. Read the port from `.port`, skip directly to phase 5 (systemd restart) then phase 6 (verify). Log:
+
+```
+[prototype-host] phase=1 surface=<surface> idempotent=true port=<port>
+```
+
+Otherwise proceed to phase 2.
+
+### Phase 2 — Scaffold source
+
+Run the framework's canonical scaffolder into `<surface-dir>/`. The exact commands per framework live in [`references/scaffold-frameworks.md`](references/scaffold-frameworks.md). Static `landing` is a special case: write `<surface-dir>/index.html` directly from `01-narrative/LANDING.md` using the brand tokens.
+
+Brand application (every framework):
+
+1. Read `06-product-ip/brand/color-palette.md` — extract the CSS custom properties (the file ships a `:root { --color-*: ... }` block).
+2. Read `06-product-ip/brand/typography-system.md` — extract the font-family + scale tokens.
+3. For `static`: inline both into the `<head>` of `<surface-dir>/index.html`.
+4. For framework scaffolds: write the tokens into the framework's global stylesheet entry point (`src/index.css` for Vite/Astro, `app/globals.css` for Next, `src/app.css` for SvelteKit).
+5. For the landing's hero + CTA copy: read `06-product-ip/brand/tone-of-voice.md` and apply it when rewriting `01-narrative/LANDING.md` into HTML.
+
+### Phase 3 — Port allocation
+
+First unbound port in 4100–4199:
+
+```bash
+for p in $(seq 4100 4199); do
+  ss -tln 2>/dev/null | awk '{print $4}' | grep -qE ":${p}$" || { echo "$p"; break; }
+done
+```
+
+Write to `<surface-dir>/.port`. If the range is exhausted, abort:
+
+```
+[prototype-host] FATAL port-range-exhausted range=4100-4199 — free a port or extend the range
+```
+
+The range is a skill constant (not a `brand.json` field) because it sits below every documented admin/chat/VNC band and above the OS ephemeral range default. Extending the range is a follow-up task, not a per-install knob.
+
+### Phase 4 — Cloudflared ingress edit
+
+Per [`references/cloudflared-ingress-edit.md`](references/cloudflared-ingress-edit.md):
+
+1. Append a hostname rule for `<surface>.<BRAND_HOSTNAME>` → `http://localhost:<port>` immediately before the final `http_status:404` catch-all in `${CFG_DIR}/config.yml`. The reference doc carries the exact `awk` insert pattern (sed cannot safely insert before the last line of a multi-line YAML rule).
+2. Validate: `cloudflared --origincert "${CFG_DIR}/cert.pem" --config "${CFG_DIR}/config.yml" tunnel ingress validate`. Non-zero exit aborts with the literal cloudflared error.
+3. Create DNS row: `cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel route dns --overwrite-dns "${TUNNEL_ID}" <surface>.<BRAND_HOSTNAME>`. `TUNNEL_ID` comes from `${CFG_DIR}/tunnel.state` (the Step 5b file every install writes).
+4. Reload cloudflared: `systemctl --user restart ${BRAND}-cloudflared.service`.
+
+Idempotency: before appending, grep `${CFG_DIR}/config.yml` for `<surface>.<BRAND_HOSTNAME>`. If present, skip the append + DNS route + reload — the row already exists; this is a re-run after a failed phase 5 or 6.
+
+### Phase 5 — Systemd user unit
+
+Per [`references/systemd-user-service.md`](references/systemd-user-service.md), write `${HOME}/.config/systemd/user/${BRAND}-prototype-<surface>.service`. Two modes:
+
+- **Dev-server mode** (frameworks with hot-reload — Vite, Next dev, SvelteKit dev, Astro dev): `ExecStart=` runs the framework's dev command bound to `<port>` via `PORT=` or `--port`.
+- **Static file-server mode** (the `static` framework): run `npm run build` first (no-op for raw HTML), then `ExecStart=cloudflared file-server --port <port> <surface-dir>` (or `<surface-dir>/dist` for built output). No Node process for raw static landings.
+
+Then:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now "${BRAND}-prototype-<surface>.service"
+```
+
+Check `systemctl --user is-active "${BRAND}-prototype-<surface>.service"` returns `active`. If not, dump the last 50 lines of `journalctl --user -u ${BRAND}-prototype-<surface>.service -n 50 --no-pager` to stderr and abort.
+
+### Phase 6 — External verification
+
+```bash
+curl -I -m 15 "https://<surface>.<BRAND_HOSTNAME>"
+```
+
+The skill emits the full HTTP response line (e.g. `HTTP/2 200`) to chat. Anything other than `200` aborts with the full curl output as literal stderr — same setup-done contract Task 288 established for cloudflare setup. This is end-to-end proof because the chat itself runs through the same tunnel: if the cloudflared connector were dead, the agent would never have answered the operator.
+
+Final success line:
+
+```
+[prototype-host] DONE surface=<surface> url=https://<surface>.<BRAND_HOSTNAME> port=<port> service=${BRAND}-prototype-<surface>.service http=200
+```
+
+## Idempotency contract
+
+Re-running the skill with the same `<surface>` is a first-class flow, not an error:
+
+| State on re-run | Behaviour |
+|---|---|
+| `<surface-dir>/.port` exists, ingress row exists, service active | Restart the systemd unit; re-verify; emit `idempotent=true` |
+| `.port` exists, ingress row missing | Re-run phase 4 (append, validate, route, reload); restart unit; verify |
+| `.port` exists, service failed | Restart unit; if still failing, dump journal and abort |
+| Nothing exists | Fresh six-phase run |
+
+The skill never allocates a second port for the same surface, never appends a duplicate ingress row, never creates a second systemd unit with a different name.
+
+## Failure surfaces
+
+Likely failure points and the literal stderr the agent should expect:
+
+- **Port range exhausted** — `[prototype-host] FATAL port-range-exhausted range=4100-4199`
+- **Ingress validate fails** — cloudflared's own multi-line YAML error, verbatim
+- **DNS route fails** — cloudflared's stderr (typically a 1xxx error code from the API)
+- **Systemd unit fails to start** — last 50 lines of journalctl, verbatim
+- **Curl returns non-200** — full `curl -I` output, verbatim
+
+Diagnostic commands the agent should suggest on failure:
+
+```bash
+cat ${CFG_DIR}/config.yml
+cloudflared --origincert "${CFG_DIR}/cert.pem" --config ${CFG_DIR}/config.yml tunnel ingress validate
+systemctl --user status ${BRAND}-prototype-<surface>.service
+journalctl --user -u ${BRAND}-prototype-<surface>.service -n 200 --no-pager
+ss -tln | grep :<port>
+dig <surface>.<BRAND_HOSTNAME>
+```
+
+## Out of scope
+
+- Production hosting (Cloudflare Pages, Vercel, Netlify, Workers). The dev server on the install device covers the founder workflow; production deploy is a separate, later task.
+- TLS / cert handling beyond cloudflared's own.
+- Per-prototype auth gating — the public landing is public; access control is a separate skill.
+- `brand.json` schema changes. Port range is a skill constant.
+- `paths.ts` reads.
+- Multi-tunnel — one tunnel per install with multiple ingress rules is the existing pattern.
+- CI/CD or git-push deploy.
+- Pre-built framework templates beyond the framework's official `create-*` scaffolders.
+- Telemetry on the public URL — the founder wires their own (Plausible, GA, server logs).
+- A `prototype-host-remove` companion skill. For now: `systemctl --user disable --now ${BRAND}-prototype-<surface>.service` + manually strip the ingress row + delete the DNS record. Removal is a follow-up task if it becomes friction.
+
+## Multi-prototype is supported by construction
+
+Port allocation scans first-free; ingress rules are additive; systemd unit names are namespaced by `<surface>`. Running `landing` + `prototype` + `prototype-v2` simultaneously on the same install requires no special handling — invoke the skill three times with three different surface names.

package/payload/premium-plugins/venture-studio/skills/prototype-host/references/cloudflared-ingress-edit.md

@@ -0,0 +1,81 @@
+# Cloudflared ingress edit — append a hostname rule before the catch-all
+
+This is the canonical pattern for adding a new hostname → local port mapping to an existing brand cloudflared `config.yml`. Sourced from the multi-hostname ingress block documented at [`platform/plugins/cloudflare/references/manual-setup.md`](../../../../../platform/plugins/cloudflare/references/manual-setup.md) under the "Multi-ingress: adding hostnames for prototype services" section.
+
+## The config.yml shape
+
+A working brand `config.yml` always looks like:
+
+```yaml
+tunnel: <TUNNEL_ID>
+credentials-file: <CFG_DIR>/<TUNNEL_ID>.json
+ingress:
+  - hostname: admin.<BRAND_HOSTNAME>
+    service: http://localhost:<PORT>
+  - hostname: public.<BRAND_HOSTNAME>
+    service: http://localhost:<PORT>
+  - service: http_status:404
+```
+
+A new prototype rule must land **before** the `http_status:404` catch-all; otherwise cloudflared matches the catch-all first and the prototype hostname returns 404.
+
+## The append pattern
+
+`sed` cannot safely insert before the last block of a multi-line YAML rule (`- service: http_status:404` is one logical entry but the line above it might be a comment or blank). `awk` is the right primitive: scan for the literal `- service: http_status:404` line and insert two lines before it.
+
+```bash
+SURFACE="<surface>"            # e.g. landing
+PORT="<port>"                  # from <surface-dir>/.port
+HOSTNAME="${SURFACE}.${BRAND_HOSTNAME}"
+
+# Idempotency guard — skip if the hostname already appears as an ingress rule.
+if grep -qE "^[[:space:]]*-[[:space:]]+hostname:[[:space:]]+${HOSTNAME}\b" "${CFG_DIR}/config.yml"; then
+  echo "[prototype-host] ingress-row-exists hostname=${HOSTNAME} — skipping append"
+else
+  awk -v host="${HOSTNAME}" -v port="${PORT}" '
+    /^[[:space:]]*-[[:space:]]+service:[[:space:]]+http_status:404[[:space:]]*$/ {
+      print "  - hostname: " host
+      print "    service: http://localhost:" port
+    }
+    { print }
+  ' "${CFG_DIR}/config.yml" > "${CFG_DIR}/config.yml.new"
+  mv "${CFG_DIR}/config.yml.new" "${CFG_DIR}/config.yml"
+fi
+```
+
+## Validate, route, reload
+
+```bash
+# 1. Validate the YAML and ingress semantics.
+cloudflared --origincert "${CFG_DIR}/cert.pem" \
+  --config "${CFG_DIR}/config.yml" \
+  tunnel ingress validate
+
+# 2. Create the DNS row (CNAME from <hostname> to <TUNNEL_ID>.cfargotunnel.com).
+TUNNEL_ID=$(jq -r '.id // .tunnelId' "${CFG_DIR}/tunnel.state")
+cloudflared --origincert "${CFG_DIR}/cert.pem" \
+  tunnel route dns --overwrite-dns "${TUNNEL_ID}" "${HOSTNAME}"
+
+# 3. Reload the connector so it picks up the new ingress rule.
+systemctl --user restart "${BRAND}-cloudflared.service"
+```
+
+Each step is its own command, runs sequentially, exits non-zero on failure. The skill propagates the failing command's stderr verbatim — no parsing, no narration ([[feedback_no_stdout_parsing_for_control_flow]]).
+
+## What `--overwrite-dns` does
+
+If a CNAME for `<hostname>` already exists in the account's DNS (e.g. from a prior install), `tunnel route dns` errors with `record already exists`. `--overwrite-dns` replaces the existing record with one pointing at this tunnel. Use it unconditionally — the alternative (probe-then-create) doubles the API surface and races with concurrent DNS edits.
+
+## Why restart, not reload
+
+`cloudflared` watches `config.yml` only when launched with `--config-watch` (off by default in the brand service unit). `systemctl --user restart` is the deterministic way to pick up the new rule. Brief connection blip (~1s) is acceptable because the brand's admin + public hostnames already tolerate the same blip on every cloudflared upgrade.
+
+## Failure points
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| `validate: ingress rule N has no service` | `awk` inserted only the hostname line, not the service line | Re-run; the snippet emits both lines atomically per match |
+| `validate: failed to parse YAML` | A previous `awk` run left a partial line | `cat ${CFG_DIR}/config.yml` and hand-fix; the skill cannot recover from corrupt YAML |
+| `route dns: 1004 invalid hostname` | `<surface>` violates DNS label rules (uppercase, underscore, leading dash) | Re-run with a valid `<surface>`; the skill validates `^[a-z0-9-]+$` before phase 4 |
+| `route dns: 9103 unauthorized` | The cert.pem in `${CFG_DIR}` doesn't grant DNS-edit on the zone | Re-run Step 1 of the cloudflare runbook to refresh `cert.pem` |
+| Restart succeeds but `curl -I` returns 502 | The dev server isn't actually listening on `<port>` | Phase 5 (systemd) failed earlier; the skill should have caught it. Read `journalctl --user -u ${BRAND}-prototype-<surface>.service -n 50` |

package/payload/premium-plugins/venture-studio/skills/prototype-host/references/scaffold-frameworks.md

@@ -0,0 +1,60 @@
+# Framework scaffolders, dev-server commands, and port overrides
+
+Five frameworks supported. Each row gives the exact command set the prototype-host skill runs in phases 2 and 5.
+
+## Selection defaults
+
+| Surface intent | Default framework | Reason |
+|---|---|---|
+| `landing` | `static` | One HTML file rendered from `01-narrative/LANDING.md` is faster to ship and faster to load than a Vite bundle. Lighthouse-clean by construction. |
+| `prototype` | `vite` | Vue/React/Svelte all supported; HMR is the founder's iteration loop. |
+
+If the operator names a framework explicitly, use that. Otherwise these defaults stand.
+
+## `static`
+
+No scaffolder. The skill writes a single `index.html` directly into `<surface-dir>/` from `01-narrative/LANDING.md`, with brand tokens inlined into `<style>` in the `<head>`.
+
+- **Build:** none (raw HTML); for a `dist/` build (if the operator adds Tailwind etc later) the skill respects `<surface-dir>/dist/` if present.
+- **Serve:** `cloudflared file-server --port <port> <surface-dir>` (or `<surface-dir>/dist` if a build directory exists).
+- **Port override:** `--port <port>` on `cloudflared file-server`.
+
+## `vite`
+
+- **Scaffold:** `cd <surface-dir-parent> && npm create vite@latest <surface-name> -- --template vanilla-ts -- --yes`. The agent prompts the operator before this if they want a non-vanilla template (`react-ts`, `svelte-ts`, `vue-ts`); otherwise `vanilla-ts` is the default — the founder can rewrite `index.html` + `src/main.ts` to anything from there.
+- **Install:** `cd <surface-dir> && npm install`
+- **Build:** `npm run build` (outputs to `<surface-dir>/dist/`)
+- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
+- **Port override:** `--port <port>` (Vite respects the flag; `PORT=` is ignored).
+
+## `next`
+
+- **Scaffold:** `cd <surface-dir-parent> && npx -y create-next-app@latest <surface-name> --typescript --app --tailwind --eslint --src-dir --import-alias "@/*" --use-npm --yes`
+- **Install:** scaffolder runs `npm install` automatically.
+- **Build:** `npm run build`
+- **Dev server:** `npm run dev -- -p <port> -H 127.0.0.1`
+- **Port override:** `-p <port>` (Next.js dev/start respect the flag; `PORT=` also works but `-p` is explicit).
+
+## `sveltekit`
+
+- **Scaffold:** `cd <surface-dir-parent> && npx -y sv create <surface-name> --template minimal --types ts --no-add-ons --install npm`
+- **Install:** scaffolder runs `npm install` automatically when `--install npm` is passed.
+- **Build:** `npm run build`
+- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
+- **Port override:** `--port <port>`.
+
+## `astro`
+
+- **Scaffold:** `cd <surface-dir-parent> && npm create astro@latest <surface-name> -- --template minimal --typescript strict --install --no-git --yes`
+- **Install:** scaffolder runs `npm install` when `--install` is passed.
+- **Build:** `npm run build` (outputs to `<surface-dir>/dist/`)
+- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
+- **Port override:** `--port <port>`.
+
+## Why `--host 127.0.0.1`
+
+Every dev server above binds to `127.0.0.1`, not `0.0.0.0`. Cloudflared connects to the loopback address; binding to `0.0.0.0` would expose the dev server on the install device's LAN address, which is unwanted (LAN clients should reach the prototype through the tunnel, not directly).
+
+## Why no `--yes` on `create-next-app` interactive prompts in older versions
+
+`create-next-app@latest` (≥14.2) treats all listed flags as the answer set and runs non-interactively. If a flag is omitted it falls back to a TTY prompt — fatal under the agent's non-TTY Bash invocation. Always pass every flag the table lists.

package/payload/premium-plugins/venture-studio/skills/prototype-host/references/systemd-user-service.md

@@ -0,0 +1,104 @@
+# Systemd user unit template for a hosted prototype surface
+
+One unit per hosted surface: `${HOME}/.config/systemd/user/${BRAND}-prototype-<surface>.service`.
+
+Two flavours: dev-server mode (frameworks with hot-reload) and static file-server mode (raw HTML or built `dist/`).
+
+## Dev-server mode (vite, next, sveltekit, astro)
+
+```ini
+[Unit]
+Description=${BRAND} prototype surface <surface> — <framework> dev server
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=<surface-dir>
+Environment="PORT=<port>"
+Environment="NODE_ENV=development"
+ExecStart=/usr/bin/env npm run dev -- <framework-port-flag> <port> --host 127.0.0.1
+Restart=on-failure
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+```
+
+`<framework-port-flag>` is the per-framework override from [`scaffold-frameworks.md`](scaffold-frameworks.md): `--port` for Vite/SvelteKit/Astro, `-p` for Next.
+
+## Static file-server mode
+
+For the `static` framework (raw HTML rendered from `LANDING.md`):
+
+```ini
+[Unit]
+Description=${BRAND} prototype surface <surface> — static file server
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=<surface-dir>
+ExecStart=/usr/local/bin/cloudflared file-server --port <port> --address 127.0.0.1 <surface-dir>
+Restart=on-failure
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+```
+
+If `<surface-dir>/dist/` exists (the founder added a build step later), point `ExecStart`'s last arg at `<surface-dir>/dist` instead of `<surface-dir>`. The skill detects this automatically with `[ -d <surface-dir>/dist ] && SERVE_DIR=<surface-dir>/dist || SERVE_DIR=<surface-dir>`.
+
+## Why a user unit, not a root unit
+
+The brand cloudflared connector already runs as a `systemctl --user` unit ([`platform/plugins/cloudflare/references/reset-guide.md`](../../../../../platform/plugins/cloudflare/references/reset-guide.md)). Keeping prototype units in the same scope means:
+
+- Same `journalctl --user` namespace — the operator reads one log namespace, not two.
+- No `sudo` required to install, enable, or restart.
+- `loginctl enable-linger <user>` (already set by the installer) survives reboot — units come back without an SSH session.
+
+Root units would also work, but split the operator's mental model and require `sudo` for every restart. Not worth the tradeoff for a per-prototype surface.
+
+## Enabling and starting
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now "${BRAND}-prototype-<surface>.service"
+
+# Verify it stayed up.
+systemctl --user is-active "${BRAND}-prototype-<surface>.service"
+
+# If not active, dump the journal and surface verbatim.
+if [ "$(systemctl --user is-active "${BRAND}-prototype-<surface>.service")" != "active" ]; then
+  journalctl --user -u "${BRAND}-prototype-<surface>.service" -n 50 --no-pager >&2
+  exit 1
+fi
+```
+
+## Re-run after edit
+
+If the skill regenerates the unit file (e.g. the port changed, or the static surface gained a `dist/` directory), the sequence is:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart "${BRAND}-prototype-<surface>.service"
+```
+
+`daemon-reload` is required after any unit-file edit; `restart` picks up the new `ExecStart`.
+
+## Why `Restart=on-failure`, not `always`
+
+Dev servers exit 0 in legitimate cases (the operator killed `npm run dev` from another shell to apply a config edit). `on-failure` respects those exits; `always` would fight them.
+
+## Logging
+
+All output (stdout + stderr from the dev server / file server) goes to the user journal. Read with:
+
+```bash
+journalctl --user -u "${BRAND}-prototype-<surface>.service" -f
+```
+
+No file-based log rotation needed — systemd handles journal rotation.