@rubytech/create-maxy-code 0.1.169 → 0.1.170

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

@@ -1,179 +0,0 @@
----
-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/platform/plugins/venture-studio/skills/prototype-host/references/cloudflared-ingress-edit.md

@@ -1,81 +0,0 @@
-# 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/platform/plugins/venture-studio/skills/prototype-host/references/scaffold-frameworks.md

@@ -1,60 +0,0 @@
-# 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/platform/plugins/venture-studio/skills/prototype-host/references/systemd-user-service.md

@@ -1,104 +0,0 @@
-# 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.