proof-artifacts 0.1.0-preview.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# Linux VPS v0 Architecture
+
+## Goal
+
+Build the smallest useful primitive for cloud coding agents: an installable CLI that creates an isolated Linux desktop on a VPS, lets an agent open and inspect a project UI, records the screen, captures screenshots, and leaves behind artifacts the user can review.
+
+## Non-goals for v0
+
+- No macOS or Windows host automation.
+- No custom cloud scheduler.
+- No model loop.
+- No browser-only abstraction as the primary layer.
+- No driver-level virtual monitor work.
+
+Those can come later. The v0 bet is that Linux containers are the simplest reliable substrate for background visual verification.
+
+## Runtime
+
+Each session is one Docker container:
+
+- `Xvfb` provides display `:99`.
+- `fluxbox` provides a lightweight window manager.
+- `Chromium` provides a real visible browser.
+- `x11vnc` and `noVNC` expose a watchable remote desktop.
+- `ffmpeg` captures screenshots and MP4 recordings.
+- `/workspace` is the mounted project.
+- `/artifacts` is the mounted evidence directory.
+
+On Unix hosts, the container runs as the invoking UID/GID when available so screenshots, recordings, and reports stay removable by the VPS user.
+Bridge-mode sessions also add `host.docker.internal` as a Docker host-gateway alias for VPS-host app access when the provider allows bridge-to-host traffic. That path is best-effort: some VPS firewall/Docker setups block bridge-to-host traffic. For localhost dev servers on the VPS host, `start --url http://127.0.0.1:<port>` infers host networking so Chromium can use the same network namespace as the app. Host-network sessions bind noVNC to VPS localhost and auto-probe noVNC/VNC ports when possible.
+
+The CLI can use a configured runtime image with local Docker build fallback. A public prebuilt image still needs CI publishing before the first-run experience is fast.
+
+The host keeps artifacts at:
+
+```txt
+.proof-artifacts/sessions/<session-name>/
+  manifest.json
+  session.json
+  report.json
+  report.html
+  screenshots/
+  recordings/
+  logs/
+  session-readme.txt
+```
+
+The host also writes a lightweight global index under `~/.proof-artifacts/sessions/` so commands can find a session from another working directory.
+
+## CLI Surface
+
+```txt
+proof-artifacts doctor
+proof-artifacts detect --project .
+proof-artifacts smoke
+proof-artifacts start --name task --project . --url http://127.0.0.1:3000 --fullscreen
+proof-artifacts launch --name task --window-match "My App" -- npm run electron
+proof-artifacts open http://127.0.0.1:3000 --name task
+proof-artifacts screenshot --name task --label before
+proof-artifacts record start --name task --label demo
+proof-artifacts record stop --name task
+proof-artifacts report --name task
+proof-artifacts artifacts --name task
+proof-artifacts exec --name task --stdin -- sh -s
+proof-artifacts cleanup --max-age-hours 24 --dry-run
+proof-artifacts stop --name task
+proof-artifacts install-skill
+```
+
+`start` binds noVNC to `127.0.0.1` with a Docker-assigned host port unless `--novnc-port` is supplied. `cleanup` removes managed containers by age and keeps artifacts unless `--delete-artifacts` is explicitly set.
+`detect` is a lightweight project classifier for agent guidance, not a full build system. `launch` is for Linux desktop apps that can run inside the existing Xvfb desktop session.
+
+## Isolation Model
+
+The first version isolates by Docker container and display server. This gives each agent its own:
+
+- desktop process tree
+- browser profile
+- display
+- recording process
+- artifact directory
+
+It does not yet provide hard multi-tenant security. For untrusted workloads, run each agent on a separate VM or with stricter Docker isolation.
+
+## Why Linux First
+
+Linux lets us create virtual displays without OS-private APIs or driver installation. On macOS, virtual monitors usually require private `CGVirtualDisplay` APIs. On Windows, virtual displays usually require an Indirect Display Driver and admin installation. Those are real future paths, but they are the wrong first bottleneck.
+
+## Success Criteria
+
+- A fresh Linux VPS with Docker can run `npm i -g proof-artifacts`.
+- `proof-artifacts start` creates a watchable desktop.
+- `proof-artifacts open` launches a visible browser.
+- `proof-artifacts launch` starts a Linux desktop app in the visible desktop.
+- `proof-artifacts screenshot` writes a PNG.
+- `proof-artifacts record start/stop` writes an MP4.
+- `proof-artifacts report` writes a human-readable handoff with summary cards, artifact counts, recent failures, screenshots, recordings, logs, and the redacted manifest.
+- `proof-artifacts smoke` proves the core path end-to-end.
+- `proof-artifacts list/status` lets agents understand existing sessions before starting, stopping, or replacing anything.
+- `proof-artifacts install-skill` gives Codex agents the workflow.
+
+Future v0 success criteria should include CI-published prebuilt images, more project/runtime coverage, and an MCP wrapper after CLI semantics settle.

package/docs/SMOKE_TEST_2026-05-13.md

@@ -0,0 +1,87 @@
+# VPS Smoke Test - 2026-05-13
+
+Historical note: this file is an early VPS smoke-test snapshot from May 13, 2026, not the current product status. Current behavior is documented in `README.md`, `docs/ARCHITECTURE.md`, `docs/VPS.md`, and `progress.md`.
+
+## Environment
+
+- Host: `ubuntu@165.1.74.127`
+- OS: Ubuntu Noble on Oracle kernel `6.17.0-1011-oracle`
+- User: `ubuntu`, passwordless sudo, Docker group available after install
+- Installed during test:
+  - Docker `29.1.3`
+  - Node `18.19.1`
+  - npm `9.2.0`
+
+## Commands Tested
+
+```sh
+node --check bin/proof-artifacts.js
+node ./bin/proof-artifacts.js doctor
+node ./bin/proof-artifacts.js start --name smoke --project . --width 1280 --height 800 --novnc-port 6080
+node ./bin/proof-artifacts.js open https://example.com --name smoke
+node ./bin/proof-artifacts.js screenshot --name smoke --label example
+node ./bin/proof-artifacts.js record start --name smoke --label demo
+node ./bin/proof-artifacts.js record stop --name smoke
+node ./bin/proof-artifacts.js stop --name smoke
+```
+
+## What Worked
+
+- SSH access worked with the provided key.
+- Docker installed and ran as the `ubuntu` user.
+- `doctor` correctly detected Docker.
+- Docker image build completed successfully.
+- `start` created a containerized desktop session.
+- noVNC served `vnc.html` over `127.0.0.1:<port>` with HTTP 200.
+- `open` launched Chromium in the virtual desktop.
+- `screenshot` produced a valid `1280x800` PNG.
+- `record start` and `record stop` produced a valid MP4 and ffmpeg log.
+- Session artifacts were written under `.proof-artifacts/sessions/<name>/`.
+
+## Bugs Found And Fixed
+
+- Initial screenshots showed a Fluxbox `xmessage` warning instead of the browser.
+- Root cause: Fluxbox tries to run `fbsetbg` on first launch and opens a wallpaper-setter warning dialog.
+- Fix: `runtime/entrypoint.sh` now repeatedly kills startup `fbsetbg` xmessage noise.
+- Chromium was open but not necessarily foreground.
+- Fix: `open` now waits for a visible Chromium window and raises it with `xdotool`.
+- The package declared Node `>=20`, but the CLI worked on Ubuntu's Node 18.
+- Fix: `package.json` now declares Node `>=18`.
+
+## Remaining Issues
+
+These were remaining issues at the time of the original smoke test; several have since been fixed.
+
+- First run is slow because `start` builds a large Docker image locally.
+- Docker build logs are extremely noisy and use the legacy Docker builder on this VPS.
+- The runtime image is large because Chromium, ffmpeg, noVNC, X11, Python, and desktop libraries are installed together.
+- Chromium logs DBus warnings because the container does not run a system bus. This did not block screenshots or recording.
+- noVNC is unauthenticated inside the container. The host maps it to `127.0.0.1`, which is acceptable for SSH tunneling but not public exposure.
+- The video was valid, but the test recording was mostly static. We still need a test that moves/clicks/types so recordings prove interaction, not only capture.
+
+## Product Notes
+
+- The core primitive is real enough to keep developing: isolated Linux display, noVNC, screenshots, and MP4 recording all worked on a clean VPS.
+- The next product-quality jump is a prebuilt Docker image. Building locally on first use is too slow for the desired experience.
+- A `setup` command should install/check Docker and Node without making users copy a runbook.
+- `doctor` should check Docker daemon access, available ports, image availability, noVNC reachability, and ffmpeg capture.
+- The agent-facing interface should become MCP tools instead of only shell commands.
+- A generated HTML report would make artifacts feel like a finished agent handoff instead of a folder of files. This has since been implemented.
+
+## Verified Artifacts
+
+Remote examples:
+
+```txt
+/home/ubuntu/proof-artifacts-smoke/.proof-artifacts/sessions/smoke2/screenshots/example2.png
+/home/ubuntu/proof-artifacts-smoke/.proof-artifacts/sessions/smoke2/recordings/demo2.mp4
+/home/ubuntu/proof-artifacts-smoke/.proof-artifacts/sessions/smoke3/screenshots/example3.png
+```
+
+Local inspection copies:
+
+```txt
+/tmp/proof-artifacts-smoke/example2.png
+/tmp/proof-artifacts-smoke/demo2.mp4
+/tmp/proof-artifacts-smoke/example3.png
+```

package/docs/VPS.md

@@ -0,0 +1,156 @@
+# VPS Runbook
+
+## Install
+
+On a fresh Linux VPS:
+
+```sh
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs docker.io
+sudo usermod -aG docker "$USER"
+newgrp docker
+npm install -g . # from this repo until the npm package is published
+proof-artifacts doctor
+proof-artifacts smoke
+```
+
+Some providers ship newer Docker packages through their own images. If `docker.io` is old or unavailable, install Docker Engine from Docker's official apt repository instead.
+After the package is published, replace the local source install with `npm install -g proof-artifacts`.
+
+## Start A Desktop
+
+```sh
+cd /path/to/project
+proof-artifacts start --name issue-123 --project .
+```
+
+The desktop viewer is bound to `127.0.0.1` on the VPS. Do not expose noVNC publicly without authentication.
+The CLI prints the selected noVNC URL, for example `http://127.0.0.1:32771/vnc.html`.
+
+Use an SSH tunnel from your laptop:
+
+```sh
+ssh -L 6080:127.0.0.1:<printed-port> user@your-vps
+```
+
+Then open:
+
+```txt
+http://127.0.0.1:6080/vnc.html
+```
+
+## Parallel Agents
+
+Run one session per agent:
+
+```sh
+proof-artifacts start --name agent-a --project .
+proof-artifacts start --name agent-b --project .
+```
+
+Each session gets its own container, browser profile, display, and artifact directory.
+Docker assigns each session a different localhost noVNC port by default. Use `--novnc-port <port>` only when you need a fixed tunnel target.
+Starting a session with the same name as an already running session fails by default. Use a more specific name, stop the old session, or pass `--replace` only when you intentionally want to remove the existing desktop.
+
+## Record Evidence
+
+```sh
+proof-artifacts open http://127.0.0.1:3000 --name agent-a --fullscreen
+proof-artifacts record start --name agent-a --label checkout-flow
+proof-artifacts screenshot --name agent-a --label after-login
+proof-artifacts record stop --name agent-a
+proof-artifacts report --name agent-a
+proof-artifacts status --name agent-a
+```
+
+Artifacts are stored under:
+
+```txt
+.proof-artifacts/sessions/<name>/
+```
+
+Each session writes `manifest.json`, `session.json`, `report.json`, and `report.html`. A global index under `~/.proof-artifacts/sessions/` lets the CLI find recent sessions from another working directory.
+The report starts with a summary section for status, elapsed time, artifact counts, latest screenshot/recording, and any failed command context.
+
+When the app is running on the VPS host instead of inside the desktop container, pass the URL to `start` so the CLI can infer host networking for localhost URLs:
+
+```sh
+proof-artifacts start --name agent-a --project . --url http://127.0.0.1:3000 --fullscreen
+proof-artifacts open http://127.0.0.1:3000 --name agent-a
+```
+
+Use `--fullscreen` when you want Chrome to fill the proof display while keeping the tab bar and address bar visible. `start --fullscreen` stores this as the session default for later `open` calls; `open --fullscreen` applies it only to that browser open. Use `open --no-fullscreen` to override a fullscreen session default when you need a normal windowed browser.
+
+You can ask the CLI to check the host URL from both the VPS and a running desktop session:
+
+```sh
+proof-artifacts doctor --name agent-a --url http://127.0.0.1:3000
+```
+
+Use `proof-artifacts doctor --name agent-a` to inspect a running session's desktop runtime tools and noVNC reachability. Use `proof-artifacts doctor --deep` only when you want an explicit disposable smoke run.
+
+Some VPS firewall/Docker setups block bridge containers from reaching the host gateway. You can also request host networking explicitly:
+
+```sh
+proof-artifacts start --name agent-a --project . --network host --novnc-port 6080
+proof-artifacts open http://127.0.0.1:3000 --name agent-a
+```
+
+Host-network sessions bind noVNC to `127.0.0.1` on the VPS, not public interfaces. They also auto-probe noVNC/VNC ports when `--novnc-port auto` is used. If you choose fixed ports manually, avoid running multiple host-network sessions on the same ports.
+On the Oracle VPS test hosts, bridge-to-host traffic was blocked. Host-network mode worked for the ARM64 Excalidraw end-to-end test, so treat it as the practical VPS fallback for localhost dev servers.
+
+## Desktop Apps
+
+The Linux runtime can also launch Linux desktop apps inside the Xvfb session. First ask for a project hint:
+
+```sh
+proof-artifacts detect --project .
+```
+
+If the project can run as a Linux desktop app, start a session and launch the app command:
+
+```sh
+proof-artifacts start --name desktop-demo --project .
+proof-artifacts launch --name desktop-demo --window-match "My App" -- npm run electron
+proof-artifacts record start --name desktop-demo --label walkthrough
+proof-artifacts screenshot --name desktop-demo --label launched
+```
+
+Use `--window-match` with text from the expected window title. Use `--no-wait` only for commands that intentionally start background services.
+
+Native macOS, iOS, Windows, and Android apps are not supported by this Linux VPS runtime. They need a matching OS runner/backend.
+
+## Run Automation Scripts
+
+`proof-artifacts exec` runs inside the desktop container at `/workspace` with `DISPLAY=:99`. Pipe scripts with `--stdin` when you want to automate the visible browser or canvas without copying a file into the container:
+
+```sh
+proof-artifacts exec --name agent-a --stdin -- sh -s <<'SH'
+xdotool search --onlyvisible --name Chromium windowactivate || true
+xdotool mousemove 120 120 click 1
+SH
+```
+
+This is useful for repeatable UI demos, drawing/canvas tests, or small browser interactions. The CLI records that an stdin exec happened but does not store the script contents in the session manifest.
+
+## Cleanup
+
+```sh
+proof-artifacts stop --name agent-a
+proof-artifacts stop --all
+proof-artifacts list
+proof-artifacts cleanup --max-age-hours 24 --dry-run
+proof-artifacts cleanup --max-age-hours 24
+```
+
+`list` shows known sessions from the local artifact directory and global index. `status --name <name>` is the quickest way to check whether a session is running, whether noVNC responds, whether a recording is active, and how many artifacts exist.
+`stop --all` removes only Docker containers labeled as managed by proof-artifacts and keeps artifacts. `cleanup` removes managed containers by age and keeps artifact directories by default. Add `--delete-artifacts` only when you intentionally want to delete evidence.
+
+## Smoke Check
+
+```sh
+proof-artifacts smoke
+```
+
+The smoke command verifies Docker, runtime image availability, desktop startup, noVNC reachability, browser launch, screenshot capture, MP4 recording, report generation, and cleanup. Add `--keep` if you want to leave the smoke desktop running for inspection.
+Use `proof-artifacts smoke --rebuild` when testing local runtime image changes.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "proof-artifacts",
+  "version": "0.1.0-preview.0",
+  "description": "Proof artifacts for coding agents using isolated Linux desktops.",
+  "type": "module",
+  "bin": {
+    "proof-artifacts": "./bin/proof-artifacts.js",
+    "proof": "./bin/proof-artifacts.js"
+  },
+  "files": [
+    "bin/",
+    "docs/",
+    "runtime/",
+    "skills/"
+  ],
+  "scripts": {
+    "check": "node --check bin/proof-artifacts.js",
+    "test": "node --test",
+    "doctor": "node ./bin/proof-artifacts.js doctor",
+    "smoke": "node ./bin/proof-artifacts.js smoke"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/runtime/Dockerfile

@@ -0,0 +1,34 @@
+FROM debian:12-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV DISPLAY=:99
+ENV WIDTH=1280
+ENV HEIGHT=800
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    chromium \
+    curl \
+    dbus-x11 \
+    ffmpeg \
+    fluxbox \
+    net-tools \
+    novnc \
+    procps \
+    python3-websockify \
+    wmctrl \
+    x11-utils \
+    x11vnc \
+    xdotool \
+    xvfb \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+
+COPY entrypoint.sh /usr/local/bin/proof-artifacts-entrypoint
+RUN chmod +x /usr/local/bin/proof-artifacts-entrypoint
+
+EXPOSE 5900 6080
+
+ENTRYPOINT ["proof-artifacts-entrypoint"]

package/runtime/entrypoint.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env sh
+set -eu
+
+mkdir -p /artifacts/screenshots /artifacts/recordings /artifacts/logs /tmp/runtime
+
+VNC_PORT="${VNC_PORT:-5900}"
+NOVNC_PORT="${NOVNC_PORT:-6080}"
+NOVNC_LISTEN="${NOVNC_LISTEN:-0.0.0.0}"
+
+Xvfb "${DISPLAY}" -screen 0 "${WIDTH}x${HEIGHT}x24" -ac -nolisten tcp +extension RANDR > /tmp/runtime/xvfb.log 2>&1 &
+
+for _ in $(seq 1 50); do
+  xdpyinfo -display "${DISPLAY}" >/dev/null 2>&1 && break
+  sleep 0.1
+done
+
+fluxbox > /tmp/runtime/fluxbox.log 2>&1 &
+# Fluxbox may show a first-run fbsetbg xmessage when no wallpaper setter exists.
+# It blocks useful first screenshots, so dismiss that known startup noise.
+(for _ in $(seq 1 40); do pkill -f "fbsetbg:" >/dev/null 2>&1 || true; sleep 0.25; done) &
+x11vnc -display "${DISPLAY}" -forever -shared -nopw -localhost -no6 -noipv6 -listen 127.0.0.1 -rfbport "${VNC_PORT}" > /tmp/runtime/x11vnc.log 2>&1 &
+websockify --web=/usr/share/novnc/ "${NOVNC_LISTEN}:${NOVNC_PORT}" localhost:"${VNC_PORT}" > /tmp/runtime/novnc.log 2>&1 &
+
+cat > /artifacts/session-readme.txt <<EOF
+Proof Artifacts desktop is running.
+
+Display: ${DISPLAY}
+Resolution: ${WIDTH}x${HEIGHT}
+Workspace: /workspace
+Artifacts: /artifacts
+VNC: 127.0.0.1:${VNC_PORT}
+noVNC: ${NOVNC_LISTEN}:${NOVNC_PORT}
+EOF
+
+tail -f /tmp/runtime/*.log

package/skills/proof-artifacts/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: proof-artifacts
+description: Use when an agent needs to run, inspect, screenshot, or record a web/app UI inside an isolated Linux VPS desktop created by the proof-artifacts CLI.
+---
+
+# Proof Artifacts
+
+Use `proof-artifacts` when you need visual verification in a Linux/VPS sandbox. Prefer this over controlling the user's real desktop.
+
+## Bootstrap
+
+Before using the desktop workflow, make sure the CLI exists. Do this automatically; do not make the user memorize setup commands.
+
+1. Check for the CLI:
+
+```sh
+command -v proof-artifacts || command -v proof
+```
+
+2. If missing, install it:
+
+```sh
+npm install -g proof-artifacts
+```
+
+3. If the npm package is not published yet or npm returns 404, install from the `proof-artifacts` source repo root instead:
+
+```sh
+npm install -g .
+```
+
+4. Re-check `command -v proof-artifacts`, then run:
+
+```sh
+proof-artifacts doctor
+```
+
+If Node/npm is missing, install Node.js 18+ first or tell the user the machine needs Node.js before the skill can continue. If Docker is missing or the user cannot access the Docker daemon, explain that Docker Engine is the required Linux desktop substrate and give the exact next command for the detected distro when it is obvious. On a new VPS, run `proof-artifacts doctor --deep` when you want the CLI to perform a disposable smoke capture.
+
+## Workflow
+
+1. If the environment is new or suspicious, run `proof-artifacts smoke`.
+2. Run `proof-artifacts detect --project <repo-path>` before choosing how to run the project.
+3. If it is a web app, start the dev server from the detected package scripts or project docs on the VPS host, keep it running, and identify its localhost URL.
+4. If it is a web app running on the VPS host at `localhost`, pass that URL to `start` so the CLI can infer host networking: `proof-artifacts start --name <task-name> --project <repo-path> --url http://127.0.0.1:<port> --fullscreen`. For external URLs, normal bridge mode is fine.
+5. If it is a Linux desktop app, start a session and launch it with `proof-artifacts launch --name <task-name> --window-match <app-title> -- <command...>`.
+6. If it is macOS, Windows, Android, iOS, or unknown and cannot run in Linux, say that clearly instead of forcing it through the desktop container.
+7. Open the target URL with `proof-artifacts open <url> --name <task-name>` for web apps. Add `--fullscreen` if the session was not started with `--fullscreen` and the goal is a full-size browser window.
+8. Start recording before exercising the app: `proof-artifacts record start --name <task-name> --label <short-label>`.
+9. Use screenshots and shell commands to inspect state: `proof-artifacts screenshot --name <task-name> --label <checkpoint>`.
+10. Stop recording: `proof-artifacts record stop --name <task-name>`.
+11. Check the session with `proof-artifacts status --name <task-name>`, then generate a handoff with `proof-artifacts report --name <task-name>`.
+12. Use the report summary and failure context as the source of truth for what worked, what failed, and which screenshots/recordings to return to the user.
+
+## Project Detection
+
+Use `detect` to get a first-pass run plan:
+
+```sh
+proof-artifacts detect --project <repo-path>
+```
+
+Treat the output as guidance, not proof. Confirm the detected commands against project docs/scripts before running expensive installs or builds.
+
+The Linux runtime can test web apps and Linux desktop apps. It cannot run native macOS/iOS/Windows/Android apps; those need a matching runner/backend.
+
+## Linux Desktop Apps
+
+For Electron, Tauri, GTK, Qt, Java/Swing, or other Linux desktop apps, launch the app inside the desktop session:
+
+```sh
+proof-artifacts start --name <task-name> --project <repo-path>
+proof-artifacts launch --name <task-name> --window-match "<app title>" -- npm run electron
+```
+
+Then record, click, type, and screenshot with the normal workflow. If no window is detected, retry with a better `--window-match` value or use `--no-wait` when the launch command intentionally starts background services.
+
+## Host App Access
+
+When a dev server is running on the VPS host at a localhost URL, verify reachability instead of guessing:
+
+```sh
+proof-artifacts doctor --name <task-name> --url http://127.0.0.1:3000
+```
+
+If you need to be explicit, restart the session with host networking:
+
+```sh
+proof-artifacts stop --name <task-name>
+proof-artifacts start --name <task-name> --project <repo-path> --network host
+proof-artifacts open http://127.0.0.1:3000 --name <task-name>
+```
+
+Host-network sessions bind noVNC to VPS localhost and auto-probe noVNC/VNC ports when `--novnc-port auto` is used. Avoid fixed port collisions if you set ports manually.
+
+## Browser Fullscreen
+
+Prefer fullscreen browser mode for final visual proof when you want Chrome to fill the virtual display while keeping the tab bar and address bar visible:
+
+```sh
+proof-artifacts start --name <task-name> --project <repo-path> --url http://127.0.0.1:<port> --fullscreen
+proof-artifacts open http://127.0.0.1:<port> --name <task-name>
+```
+
+Use `proof-artifacts open <url> --name <task-name> --fullscreen` for a one-off fullscreen open. This is browser-window fullscreen, not kiosk mode: the tab bar and address bar should remain visible. Use `--no-fullscreen` if the session default is fullscreen but you need a normal windowed browser.
+
+## Desktop Automation Scripts
+
+`proof-artifacts exec` runs inside the desktop container at `/workspace` with `DISPLAY=:99`. Use `--stdin` for ad hoc multi-line scripts so you do not need `docker cp`:
+
+```sh
+proof-artifacts exec --name <task-name> --stdin -- sh -s <<'SH'
+xdotool search --onlyvisible --name Chromium windowactivate || true
+xdotool mousemove 120 120 click 1
+SH
+```
+
+Do not put secrets in scripts passed over stdin; the CLI does not record stdin contents, but shell history or surrounding tooling might.
+
+## Rules
+
+- Keep each task in its own named session so multiple agents do not share a display.
+- On a VPS, keep noVNC bound to localhost and use SSH port forwarding for human viewing. Use the printed port from `start`.
+- Use stable, specific names like the branch, issue id, or task slug. Avoid generic names like `default` when multiple agents may run on the same VPS.
+- If the web app is running on the VPS host, first try `proof-artifacts doctor --name <task-name> --url http://127.0.0.1:<port>`. If the VPS blocks Docker bridge-to-host traffic, use host-network mode and verify it with `screenshot` before relying on it.
+- Record evidence for user-visible changes, not every command.
+- If any setup step fails, summarize what worked, the exact blocker, and the next command. Do not leave the user with a vague "environment failed" message.
+- Stop sessions with `proof-artifacts stop --name <task-name>` when work is complete.
+- Use `proof-artifacts list` before stopping/reusing names if there may be multiple agents on the VPS.
+- If a command needs to interact with the desktop display, run it through `proof-artifacts exec` so `DISPLAY=:99` is set.
+- Use `proof-artifacts cleanup --dry-run` before deleting stale sessions. Use `proof-artifacts stop --all` only for managed proof-artifacts containers and only when emergency cleanup is needed. Add `--delete-artifacts` only when evidence can be discarded.
+
+## Useful Commands
+
+- `proof-artifacts smoke --keep` leaves the test desktop running for inspection.
+- `proof-artifacts smoke --rebuild` rebuilds the local runtime image before testing local runtime changes.
+- `proof-artifacts start --image <image> --pull` tries a configured runtime image before local build fallback.
+- `proof-artifacts open <url> --name <task-name> --fullscreen` opens Chromium as a full-display browser window with browser chrome still visible.
+- `proof-artifacts detect --project <repo-path>` suggests whether the project is web, Linux desktop, or unsupported in the Linux runtime.
+- `proof-artifacts launch --name <task-name> --window-match <title> -- <command...>` starts a Linux desktop app inside the session.
+- `proof-artifacts exec --name <task-name> --stdin -- sh -s` pipes a multi-line script into the desktop container.
+- `proof-artifacts doctor --url <url> --name <task-name>` checks whether a running session can reach a host app URL.
+- `proof-artifacts list` shows known sessions from the local artifact directory and global index.
+- `proof-artifacts status --name <task-name>` shows runtime state, noVNC reachability, active recording, and artifact counts.
+- `proof-artifacts cleanup --max-age-hours 24` removes old managed containers while preserving artifacts.