From 0ffe5add0c786aef0cf0170bb5a9f986bb127f3d Mon Sep 17 00:00:00 2001
From: itsablabla <garzasecure@pm.me>
Date: Sun, 5 Jul 2026 03:52:22 +0000
Subject: [PATCH 1/2] docs: add Niteshift browser verification runbook

Run-on: Niteshift
---
 .../niteshift-browser-verification.md         | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docs/runbooks/niteshift-browser-verification.md

diff --git a/docs/runbooks/niteshift-browser-verification.md b/docs/runbooks/niteshift-browser-verification.md
new file mode 100644
index 00000000..6a93909c
--- /dev/null
+++ b/docs/runbooks/niteshift-browser-verification.md
@@ -0,0 +1,88 @@
+# Runbook: Niteshift Browser Verification
+
+Use this when a Niteshift task asks for `/browser`, `/screenshots`, `/demo`, or
+`/browser-profiler` verification.
+
+## Prerequisites
+
+- `agent-browser` CLI available in `PATH`
+- Preview URL in `/tmp/browser-preview.json`, or a known local app URL
+- GitHub CLI authenticated for the task branch
+
+## Install
+
+Install the browser binary before the first verification run:
+
+```bash
+agent-browser install
+```
+
+If Chromium launches with missing shared library errors on Linux, install the
+system dependencies too:
+
+```bash
+agent-browser install --with-deps
+```
+
+## Verify a Preview
+
+Prefer the preview URL Niteshift already provisioned:
+
+```bash
+APP_URL="$(node -e "console.log(require('/tmp/browser-preview.json').baseUrl)")"
+agent-browser open "$APP_URL"
+agent-browser wait --text "GARZA OS"
+agent-browser snapshot -i
+```
+
+Use targeted waits such as `--text`, `--url`, or an element ref. Avoid waiting
+for network idle on realtime pages.
+
+## Screenshots
+
+Capture final states only, then inspect the image before uploading it:
+
+```bash
+agent-browser screenshot /tmp/niteshift-screenshot.png --full
+```
+
+Upload accepted images with the Niteshift PR media tool and embed them inside
+the single `<!-- niteshift:media -->` fence in the PR description.
+
+## Demo
+
+Record the shortest useful browser walkthrough:
+
+```bash
+agent-browser record start /tmp/niteshift-demo.webm "$APP_URL"
+# Exercise the relevant flow.
+agent-browser record stop
+agent-browser screenshot /tmp/niteshift-demo-thumbnail.png
+```
+
+Upload the video with its thumbnail. If code, styling, copy, or state changes
+after recording, discard the stale recording and capture it again.
+
+## Browser Profile
+
+Capture only the relevant interaction and stop profiling promptly:
+
+```bash
+agent-browser profiler start
+# Exercise the relevant flow.
+agent-browser profiler stop /tmp/niteshift-profile.json
+test -s /tmp/niteshift-profile.json
+```
+
+Summarize any bottlenecks or regressions found during the profiled flow.
+
+## PR Handling
+
+After verification, commit and push the task branch:
+
+```bash
+git push -u origin "$(git branch --show-current)"
+```
+
+If no PR exists, create a draft PR against `main`. If a PR already exists, only
+push to the branch and preserve its draft or ready-for-review state.

From 3998663e5c1041928f36271ced38b40f29564a4f Mon Sep 17 00:00:00 2001
From: itsablabla <garzasecure@pm.me>
Date: Sun, 5 Jul 2026 03:59:32 +0000
Subject: [PATCH 2/2] docs: add browser preview fallback

Run-on: Niteshift
---
 docs/runbooks/niteshift-browser-verification.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/runbooks/niteshift-browser-verification.md b/docs/runbooks/niteshift-browser-verification.md
index 6a93909c..d489e9d6 100644
--- a/docs/runbooks/niteshift-browser-verification.md
+++ b/docs/runbooks/niteshift-browser-verification.md
@@ -26,10 +26,15 @@ agent-browser install --with-deps
 
 ## Verify a Preview
 
-Prefer the preview URL Niteshift already provisioned:
+Prefer the preview URL Niteshift already provisioned. If the preview file is
+absent, use an existing `APP_URL` value or fall back to `http://localhost:3000`:
 
 ```bash
-APP_URL="$(node -e "console.log(require('/tmp/browser-preview.json').baseUrl)")"
+if [ -f /tmp/browser-preview.json ]; then
+  APP_URL="$(node -e "console.log(require('/tmp/browser-preview.json').baseUrl)")"
+else
+  APP_URL="${APP_URL:-http://localhost:3000}"
+fi
 agent-browser open "$APP_URL"
 agent-browser wait --text "GARZA OS"
 agent-browser snapshot -i