better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-har-derived-api-client.md

@@ -0,0 +1,180 @@
+---
+title: "Har Derived Api Client — Record a site's XHR into a HAR, derive an HTTP client"
+sidebar_label: "Har Derived Api Client"
+description: "Record a site's XHR into a HAR, derive an HTTP client"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Har Derived Api Client
+
+Record a site's XHR into a HAR, derive an HTTP client.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/web-development/har-derived-api-client` |
+| Path | `optional-skills/web-development\har-derived-api-client` |
+| Version | `0.1.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Browser`, `HAR`, `API`, `Reverse-Engineering`, `Playwright` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# HAR-Derived API Client
+
+Drive a website once with a real browser while recording its network traffic
+to a HAR file, then distill that HAR into the site's private JSON API so you
+can call it directly with plain HTTP — far cheaper and faster than
+browser-controlling the page on every request. Credit: trick by Jared Longster,
+popularized by Dax (thdxr). This captures and replays; it does NOT bypass
+auth, solve CAPTCHAs, or defeat bot-detection — if the site needs a logged-in
+session, you carry its headers/cookies forward, you don't forge them.
+
+The scripts are stdlib-plus-Playwright: capture needs Playwright, derivation
+is pure stdlib, replay needs only `requests`/`httpx` (or `curl`).
+
+Covers **every Hermes browser pathway**: the default local `browser_navigate`
+backend, plus the cloud/remote backends (Browserbase, Browser-Use, Firecrawl)
+and any `/browser connect` CDP endpoint. There are two capture scripts — one
+for a browser you launch, one for a browser you attach to over CDP — because
+HAR recording works differently in each case (see How to Run).
+
+## When to Use
+
+- "Build a CLI/client for <website>" — derive its API instead of scripting clicks.
+- "This site has no public API but the page clearly fetches JSON."
+- You're about to loop `browser_navigate` for the same query repeatedly — stop and derive the endpoint once.
+- Reverse-engineering an autocomplete, search, feed, or checkout XHR.
+- You captured a session on a cloud backend (Browserbase / Browser-Use / Firecrawl) or via `/browser connect` and want the API without re-renting the browser.
+
+## Prerequisites
+
+- Playwright + a browser binary (capture step only):
+  - `pip install playwright` then `playwright install chromium`
+  - (If a system Playwright already has browsers under `~/.cache/ms-playwright`, reuse it.)
+- `requests` or `httpx` for the replay step (stdlib `urllib` also works).
+- No API keys. Any keys/tokens the client needs are the ones the HAR captured.
+- For the CDP path (`har_capture_cdp.py`): a reachable CDP endpoint. On Hermes,
+  run `/browser connect` to print the active endpoint, or read `BROWSER_CDP_URL`
+  / `browser.cdp_url` in config. Cloud backends expose it as `cdpUrl`/`connectUrl`.
+
+## How to Run
+
+Scripts under this skill's `scripts/`, invoked through the `terminal` tool.
+**Pick the capturer by pathway** — this is the part that trips people up:
+
+| Browser pathway | How Hermes reaches it | Capturer |
+|---|---|---|
+| Local `browser_navigate` (default, agent-browser/Playwright) | launched locally | `har_capture.py` |
+| Camofox (`CAMOFOX_URL` set) | local REST/CDP | `har_capture_cdp.py` if it exposes CDP, else drive it yourself |
+| Browserbase / Browser-Use / Firecrawl (cloud) | **CDP** (`cdpUrl`) | `har_capture_cdp.py` |
+| `/browser connect <url>` / `BROWSER_CDP_URL` | **CDP** | `har_capture_cdp.py` |
+
+Rule of thumb: **if Hermes *launched* the browser, use `har_capture.py`; if it
+*connected to* one over CDP, use `har_capture_cdp.py`.** `har_capture.py` uses
+Playwright's `record_har_path`, which only works on a locally-owned context.
+`har_capture_cdp.py` attaches with `connect_over_cdp()` and assembles the HAR
+from `page.on("request"/"response")` events, because `record_har_path` is
+unavailable on a connected browser.
+
+Then, for either path:
+
+- `har_to_client.py` — filters the HAR to XHR/fetch/JSON, groups by endpoint, and prints params, headers, bodies, and replay hints (User-Agent / cookie / auth).
+
+Resolve paths against this skill's directory. Canonical loop:
+
+```bash
+# 1a. Capture, LOCAL browser (Hermes launched it)
+python3 scripts/har_capture.py "https://SITE/" out.har \
+  --action "fill:input[name=search]:my query" --action "sleep:3" --wait 2
+
+# 1b. Capture, CDP browser (cloud backend or /browser connect)
+#     get the endpoint from /browser connect or BROWSER_CDP_URL
+python3 scripts/har_capture_cdp.py "ws://HOST/devtools/browser/..." out.har \
+  --goto "https://SITE/" --action "fill:input[name=search]:my query" \
+  --action "sleep:3" --wait 2
+
+# 2. Derive — read the endpoints out of the HAR
+python3 scripts/har_to_client.py out.har --host SITE --max-body 400
+
+# 3. Replay — write a tiny client from the printed endpoint (see Procedure)
+```
+
+## Quick Reference
+
+```
+har_capture.py <url> <out.har> [--wait S] [--headed] [--action SPEC ...]
+  action SPEC:  fill:SELECTOR:TEXT | press:SELECTOR:KEY | click:SELECTOR
+                goto:URL | sleep:SECONDS      (run in order after page load)
+  use when Hermes LAUNCHED the browser (local browser_navigate default)
+
+har_capture_cdp.py <cdp_url> <out.har> [--goto URL] [--wait S] [--action SPEC ...]
+  same action SPEC; attaches to an existing CDP browser and does NOT close it
+  use for cloud backends (Browserbase/Browser-Use/Firecrawl) & /browser connect
+
+har_to_client.py <in.har> [--host SUBSTR] [--include-static] [--max-body N]
+  default: keeps only XHR/fetch/JSON; --host narrows to one domain
+  prints per endpoint: query params, non-boring req headers, req body sample,
+                       response status/content-type + body sample
+  prints "### Replay hints": the browser User-Agent, cookie/auth presence
+```
+
+## Procedure
+
+0. **Pick the capturer by pathway** (see How to Run table). Launched-locally → `har_capture.py`; reached over CDP → `har_capture_cdp.py`. On Hermes, `/browser connect` tells you the CDP endpoint when a cloud/remote backend is active.
+1. **Find the interaction.** Open the site with `browser_navigate` (or `--headed` capture) to see which selector to type into / click, and confirm a JSON XHR fires in devtools/network.
+2. **Capture the HAR** via the `terminal` tool. Order `--action` to reach the request: `fill` the box, then `sleep` long enough for the debounced XHR, and always leave `--wait` at the end so late responses flush. Both capturers embed response bodies, so the derived client sees real payload shapes.
+3. **Derive** with `har_to_client.py --host <domain>`. Read off: the method, the URL/path template (numeric/UUID segments collapse to `{id}`), query params, request-body JSON, and the `### Replay hints` block.
+4. **Write the client.** Recreate the request exactly — same method, path, query params, body. Send the headers the site actually needs: at minimum copy the **User-Agent** from the replay hints. If hints report cookies or an auth/token header, resend those too.
+5. **Test browserless.** Run the client with the `terminal` tool and confirm it returns the same data the browser saw. This is the payoff: no browser in the loop.
+6. **(Optional) Wrap as a CLI** — a small `argparse` script over the derived call, e.g. `search.py "frank herbert"`.
+
+Worked example (Wikipedia search-title, derived + replayed live):
+
+```python
+import requests
+r = requests.get(
+    "https://en.wikipedia.org/w/rest.php/v1/search/title",
+    params={"q": "frank herbert", "limit": 5},
+    headers={"accept": "application/json",
+             "User-Agent": "Mozilla/5.0 ... Chrome/131 Safari/537.36"},  # from HAR
+    timeout=15,
+)
+for p in r.json()["pages"]:
+    print(p["title"], "-", p.get("description"))
+```
+
+## Pitfalls
+
+- **Default library User-Agent gets 403.** Many sites (Wikipedia, Cloudflare-fronted APIs) reject `python-requests/x.y`. Always send the browser UA from the replay hints. This is the #1 reason a derived client fails when the browser succeeded.
+- **A failed `--action` aborts before the HAR flushes** — you get no file. If capture errors on a selector, the run produced nothing; fix the selector (use `--headed` to watch) and rerun. Don't debug a missing HAR.
+- **Server-rendered pages have no XHR** to derive — `har_to_client.py` prints "No API-looking entries". The data came in the HTML; scrape it or find the interaction that does fetch JSON.
+- **Debounced/typeahead XHRs need a real pause.** Add `--action "sleep:3"` after `fill`; typing alone won't have fired the request when the HAR closes.
+- **Auth/session endpoints** need the captured `Cookie`/`Authorization` header, and those expire. The derived client is only as durable as the credential; re-capture when it 401s. HARs contain live secrets — treat `out.har` as sensitive and delete it after deriving.
+- **`record_har_content="embed"` makes big HARs.** Use `--max-body` to cap what's printed; the file itself can be large for media-heavy pages.
+- **Endpoints shift.** Sites change private APIs without notice. Re-run the capture→derive loop when a client breaks rather than patching URLs by hand.
+- **Wrong capturer = empty/no HAR.** `har_capture.py` on a cloud/CDP backend records nothing (it launches its own local browser instead of the one you meant). `har_capture_cdp.py` needs the endpoint; on Hermes get it from `/browser connect` or `BROWSER_CDP_URL`. Match the capturer to the pathway (How to Run table).
+- **Headless-Chrome UA is a weak tell.** Local/agent-browser capture yields a `HeadlessChrome/...` User-Agent; some sites sniff the "Headless" token. Cloud backends (Browserbase/Browser-Use) send a real desktop-Chrome UA, so a client derived from a cloud capture replays more reliably. If a headless-derived client 403s where the browser didn't, swap the "Headless" UA for a normal Chrome UA string before assuming the endpoint changed.
+- **CDP capture doesn't close the browser.** `har_capture_cdp.py` attaches to a browser it doesn't own and leaves it running — correct for cloud/remote sessions Hermes manages. Don't add a close; let the owning backend tear it down.
+
+## Verification
+
+End-to-end proof against a live site with no API key:
+
+```bash
+python3 scripts/har_capture.py "https://en.wikipedia.org/wiki/Main_Page" /tmp/wiki.har \
+  --action "fill:input[name=search]:dune messiah" --action "sleep:3" --wait 2
+python3 scripts/har_to_client.py /tmp/wiki.har --host wikipedia.org --max-body 200
+```
+
+Expect the derivation to print `GET https://en.wikipedia.org/w/rest.php/v1/search/title`
+with `q` and `limit` params and a JSON `pages` response — then replay it with the
+Procedure snippet and confirm matching titles come back over plain HTTP.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-page-agent.md

@@ -0,0 +1,207 @@
+---
+title: "Page Agent — Embed an in-page natural-language GUI copilot in web apps"
+sidebar_label: "Page Agent"
+description: "Embed an in-page natural-language GUI copilot in web apps"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Page Agent
+
+Embed an in-page natural-language GUI copilot in web apps.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/web-development/page-agent` |
+| Path | `optional-skills/web-development\page-agent` |
+| Version | `1.0.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `web`, `javascript`, `agent`, `browser`, `gui`, `alibaba`, `embed`, `copilot`, `saas` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# page-agent
+
+alibaba/page-agent (https://github.com/alibaba/page-agent, 17k+ stars, MIT) is an in-page GUI agent written in TypeScript. It lives inside a webpage, reads the DOM as text (no screenshots, no multi-modal LLM), and executes natural-language instructions like "click the login button, then fill username as John" against the current page. Pure client-side — the host site just includes a script and passes an OpenAI-compatible LLM endpoint.
+
+## When to use this skill
+
+Load this skill when a user wants to:
+
+- **Ship an AI copilot inside their own web app** (SaaS, admin panel, B2B tool, ERP, CRM) — "users on my dashboard should be able to type 'create invoice for Acme Corp and email it' instead of clicking through five screens"
+- **Modernize a legacy web app** without rewriting the frontend — page-agent drops on top of existing DOM
+- **Add accessibility via natural language** — voice / screen-reader users drive the UI by describing what they want
+- **Demo or evaluate page-agent** against a local (Ollama) or hosted (Qwen, OpenAI, OpenRouter) LLM
+- **Build interactive training / product demos** — let an AI walk a user through "how to submit an expense report" live in the real UI
+
+## When NOT to use this skill
+
+- User wants **Hermes itself to drive a browser** → use Hermes' built-in browser tool (Browserbase / Camofox). page-agent is the *opposite* direction.
+- User wants **cross-tab automation without embedding** → use Playwright, browser-use, or the page-agent Chrome extension
+- User needs **visual grounding / screenshots** → page-agent is text-DOM only; use a multimodal browser agent instead
+
+## Prerequisites
+
+- Node 22.13+ or 24+, npm 10+ (docs claim 11+ but 10.9 works fine)
+- An OpenAI-compatible LLM endpoint: Qwen (DashScope), OpenAI, Ollama, OpenRouter, or anything speaking `/v1/chat/completions`
+- Browser with devtools (for debugging)
+
+## Path 1 — 30-second demo via CDN (no install)
+
+Fastest way to see it work. Uses alibaba's free testing LLM proxy — **for evaluation only**, subject to their terms.
+
+Add to any HTML page (or paste into the devtools console as a bookmarklet):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>
+```
+
+A panel appears. Type an instruction. Done.
+
+Bookmarklet form (drop into bookmarks bar, click on any page):
+
+```javascript
+javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();
+```
+
+## Path 2 — npm install into your own web app (production use)
+
+Inside an existing web project (React / Vue / Svelte / plain):
+
+```bash
+npm install page-agent
+```
+
+Wire it up with your own LLM endpoint — **never ship the demo CDN to real users**:
+
+```javascript
+import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+    model: 'qwen3.5-plus',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+    apiKey: process.env.LLM_API_KEY,   // never hardcode
+    language: 'en-US',
+})
+
+// Show the panel for end users:
+agent.panel.show()
+
+// Or drive it programmatically:
+await agent.execute('Click submit button, then fill username as John')
+```
+
+Provider examples (any OpenAI-compatible endpoint works):
+
+| Provider | `baseURL` | `model` |
+|----------|-----------|---------|
+| Qwen / DashScope | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3.5-plus` |
+| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
+| Ollama (local) | `http://localhost:11434/v1` | `qwen3:14b` |
+| OpenRouter | `https://openrouter.ai/api/v1` | `anthropic/claude-sonnet-4.6` |
+
+**Key config fields** (passed to `new PageAgent({...})`):
+
+- `model`, `baseURL`, `apiKey` — LLM connection
+- `language` — UI language (`en-US`, `zh-CN`, etc.)
+- Allowlist and data-masking hooks exist for locking down what the agent can touch — see https://alibaba.github.io/page-agent/ for the full option list
+
+**Security.** Don't put your `apiKey` in client-side code for a real deployment — proxy LLM calls through your backend and point `baseURL` at your proxy. The demo CDN exists because alibaba runs that proxy for evaluation.
+
+## Path 3 — clone the source repo (contributing, or hacking on it)
+
+Use this when the user wants to modify page-agent itself, test it against arbitrary sites via a local IIFE bundle, or develop the browser extension.
+
+```bash
+git clone https://github.com/alibaba/page-agent.git
+cd page-agent
+npm ci              # exact lockfile install (or `npm i` to allow updates)
+```
+
+Create `.env` in the repo root with an LLM endpoint. Example:
+
+```
+LLM_MODEL_NAME=gpt-4o-mini
+LLM_API_KEY=sk-...
+LLM_BASE_URL=https://api.openai.com/v1
+```
+
+Ollama flavor:
+
+```
+LLM_BASE_URL=http://localhost:11434/v1
+LLM_API_KEY=NA
+LLM_MODEL_NAME=qwen3:14b
+```
+
+Common commands:
+
+```bash
+npm start           # docs/website dev server
+npm run build       # build every package
+npm run dev:demo    # serve IIFE bundle at http://localhost:5174/page-agent.demo.js
+npm run dev:ext     # develop the browser extension (WXT + React)
+npm run build:ext   # build the extension
+```
+
+**Test on any website** using the local IIFE bundle. Add this bookmarklet:
+
+```javascript
+javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);})();
+```
+
+Then: `npm run dev:demo`, click the bookmarklet on any page, and the local build injects. Auto-rebuilds on save.
+
+**Warning:** your `.env` `LLM_API_KEY` is inlined into the IIFE bundle during dev builds. Don't share the bundle. Don't commit it. Don't paste the URL into Slack. (Verified: grepping the public dev bundle returns the literal values from `.env`.)
+
+## Repo layout (Path 3)
+
+Monorepo with npm workspaces. Key packages:
+
+| Package | Path | Purpose |
+|---------|------|---------|
+| `page-agent` | `packages/page-agent/` | Main entry with UI panel |
+| `@page-agent/core` | `packages/core/` | Core agent logic, no UI |
+| `@page-agent/mcp` | `packages/mcp/` | MCP server (beta) |
+| — | `packages/llms/` | LLM client |
+| — | `packages/page-controller/` | DOM ops + visual feedback |
+| — | `packages/ui/` | Panel + i18n |
+| — | `packages/extension/` | Chrome/Firefox extension |
+| — | `packages/website/` | Docs + landing site |
+
+## Verifying it works
+
+After Path 1 or Path 2:
+1. Open the page in a browser with devtools open
+2. You should see a floating panel. If not, check the console for errors (most common: CORS on the LLM endpoint, wrong `baseURL`, or a bad API key)
+3. Type a simple instruction matching something visible on the page ("click the Login link")
+4. Watch the Network tab — you should see a request to your `baseURL`
+
+After Path 3:
+1. `npm run dev:demo` prints `Accepting connections at http://localhost:5174`
+2. `curl -I http://localhost:5174/page-agent.demo.js` returns `HTTP/1.1 200 OK` with `Content-Type: application/javascript`
+3. Click the bookmarklet on any site; panel appears
+
+## Pitfalls
+
+- **Demo CDN in production** — don't. It's rate-limited, uses alibaba's free proxy, and their terms forbid production use.
+- **API key exposure** — any key passed to `new PageAgent({apiKey: ...})` ships in your JS bundle. Always proxy through your own backend for real deployments.
+- **Non-OpenAI-compatible endpoints** fail silently or with cryptic errors. If your provider needs native Anthropic/Gemini formatting, use an OpenAI-compatibility proxy (LiteLLM, OpenRouter) in front.
+- **CSP blocks** — sites with strict Content-Security-Policy may refuse to load the CDN script or disallow inline eval. In that case, self-host from your origin.
+- **Restart dev server** after editing `.env` in Path 3 — Vite only reads env at startup.
+- **Node version** — the repo declares `^22.13.0 || >=24`. Node 20 will fail `npm ci` with engine errors.
+- **npm 10 vs 11** — docs say npm 11+; npm 10.9 actually works fine.
+
+## Reference
+
+- Repo: https://github.com/alibaba/page-agent
+- Docs: https://alibaba.github.io/page-agent/
+- License: MIT (built on browser-use's DOM processing internals, Copyright 2024 Gregor Zunic)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-publish-site.md

@@ -0,0 +1,174 @@
+---
+title: "Publish Site — Versioned site deploys to GitHub/Cloudflare/Netlify Pages"
+sidebar_label: "Publish Site"
+description: "Versioned site deploys to GitHub/Cloudflare/Netlify Pages"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Publish Site
+
+Versioned site deploys to GitHub/Cloudflare/Netlify Pages.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/web-development/publish-site` |
+| Path | `optional-skills/web-development\publish-site` |
+| Version | `1.0.0` |
+| Author | Hermes Agent (Nous Research) |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `publish`, `deploy`, `hosting`, `github-pages`, `cloudflare-pages`, `netlify`, `static-site`, `versioning`, `rollback`, `web-development` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Publish Site
+
+Take a website, dashboard, or web app the user built (or you built for them) and put it online on infrastructure the user owns — GitHub Pages by default, Cloudflare Pages or Netlify when they need more. The discipline: preview locally for sign-off, version every deploy with a git tag, deploy through a provider ladder, verify the live URL with a real HTTP check, and keep rollback one command away.
+
+This skill covers static sites and SPA build output (plain HTML/CSS/JS, or the `dist/`/`build/` folder from Vite/Next-export/Astro/etc.). It does not cover server-side runtimes — for throwaway serverless deploys with zero account setup, use the `cloudflare-temporary-deploy` optional skill instead.
+
+## When to Use
+
+Load this skill when the user asks to:
+
+- **Put a site online** — "publish this", "host this somewhere", "give me a link I can share"
+- **Deploy a dashboard, report, portfolio, docs site, or prototype** you just generated
+- **Update an already-published site** with new content (redeploy = new version)
+- **Roll back** a bad deploy to the previous version
+- **Pick a host** — they don't care where, they just want a URL
+
+## Prerequisites
+
+At least ONE authenticated provider CLI (check in this order):
+
+- **GitHub Pages (default):** `gh auth status` succeeds. Needs `git` too.
+- **Cloudflare Pages:** `wrangler whoami` succeeds (or `CLOUDFLARE_API_TOKEN` is set). Install: `npm i -g wrangler` or use `npx wrangler@latest`.
+- **Netlify (fallback):** `netlify status` succeeds. Install: `npm i -g netlify-cli`.
+
+Plus:
+
+- A directory of static output to publish (site root or a `dist/`/`build/` folder). If the project needs a build step, run it first and publish the output directory, never the source.
+- For local preview sharing: `cloudflared` (optional — `python3 -m http.server` covers local-only preview).
+
+## How to Run
+
+All commands below run via the `terminal` tool from the site's project directory. The pipeline is always the same five moves:
+
+1. Build → 2. Preview for sign-off → 3. Commit + tag (version-before-deploy) → 4. Deploy via the provider ladder → 5. Verify the live URL with `curl` and report it.
+
+## Quick Reference
+
+| Step | Command |
+|---|---|
+| Local preview | `python3 -m http.server 8080 --directory dist` |
+| Shareable preview | `cloudflared tunnel --url http://localhost:8080` |
+| Version a deploy | `git add -A && git commit -m "deploy: <what>" && git tag deploy-YYYYMMDD-HHMM` |
+| GitHub Pages (branch mode) | `git subtree push --prefix dist origin gh-pages` |
+| Enable Pages on repo | `gh api repos/{owner}/{repo}/pages -X POST -f 'source[branch]=gh-pages' -f 'source[path]=/'` |
+| Cloudflare Pages | `npx wrangler@latest pages deploy dist --project-name <name>` |
+| Netlify | `netlify deploy --prod --dir dist` |
+| Rollback | `git checkout <previous-tag> -- . && redeploy` (or provider dashboard) |
+| Verify live | `curl -sS -o /dev/null -w '%{http_code}' <url>` → expect `200` |
+
+## Procedure
+
+### 1. Build and preview locally
+
+Build if needed (`npm run build`, etc.) and identify the output directory. Serve it:
+
+```bash
+python3 -m http.server 8080 --directory dist
+```
+
+For a shareable preview link (user on another machine, or you want their sign-off before going live), open a quick tunnel in a background `terminal` session:
+
+```bash
+cloudflared tunnel --url http://localhost:8080
+```
+
+Give the user the `https://*.trycloudflare.com` URL and get sign-off before deploying. Kill the tunnel afterwards.
+
+### 2. Version before deploy — no exceptions
+
+Every deploy must come from a git commit, so every deploy is reproducible and rollback is trivial.
+
+```bash
+git init 2>/dev/null; git add -A
+git commit -m "deploy: <short description>"
+git tag "deploy-$(date +%Y%m%d-%H%M)"
+```
+
+If the project already has a repo, just commit + tag. Never deploy uncommitted files.
+
+### 3. Deploy — provider ladder
+
+**Rung 1 — GitHub Pages (default: free, zero extra accounts if `gh` is authed):**
+
+```bash
+gh repo create <name> --public --source . --push   # skip if repo exists
+git subtree push --prefix dist origin gh-pages      # publish build output
+gh api "repos/{owner}/<name>/pages" -X POST \
+  -f 'source[branch]=gh-pages' -f 'source[path]=/'  # first time only
+```
+
+Site appears at `https://<owner>.github.io/<name>/`. If the site is the repo root (no build dir), push `main` and set Pages source to `main` instead of using subtree. For build-step projects that will redeploy often, prefer the official `actions/deploy-pages` workflow so pushes auto-publish.
+
+**Rung 2 — Cloudflare Pages (when the user wants a custom domain, redirects/headers, or Functions):**
+
+```bash
+npx wrangler@latest pages deploy dist --project-name <name>
+```
+
+First run creates the project and prints the `https://<name>.pages.dev` URL. Custom domains attach via the Cloudflare dashboard (Pages → project → Custom domains).
+
+**Rung 3 — Netlify (fallback, or when the user already lives there):**
+
+```bash
+netlify deploy --prod --dir dist
+```
+
+`netlify deploy --dir dist` (no `--prod`) gives a draft URL — useful as a second preview stage.
+
+### 4. Rollback
+
+Rollback = redeploy a previous tag. Never hand-edit live output.
+
+```bash
+git checkout deploy-<previous> -- .   # or: git checkout deploy-<previous>; rebuild
+# then rerun the same deploy command from step 3
+```
+
+Cloudflare Pages and Netlify also keep per-deploy history in their dashboards ("Rollback to this deploy"), which is faster when the CLI isn't handy.
+
+### 5. Secrets and environment variables
+
+- **NEVER commit secrets, API keys, or `.env` files** — they'd be public on Pages hosting. Check with `git status` before the first commit and keep `.env*` in `.gitignore`.
+- Runtime env vars belong in the provider's dashboard: Cloudflare Pages → Settings → Environment variables; Netlify → Site settings → Environment variables. GitHub Pages is static-only — no server env; anything embedded in the bundle is public by definition. Warn the user if their build inlines a key.
+
+## Pitfalls
+
+- **SPA routes 404 on GitHub Pages.** Pages has no rewrite rules. Copy `index.html` to `404.html` in the output dir (`cp dist/index.html dist/404.html`) so client-side routing recovers. Cloudflare Pages and Netlify handle SPAs via `_redirects` (`/* /index.html 200`).
+- **GitHub Pages build lag.** The site can take 1–10 minutes to appear after the first enable, and ~1 minute per subsequent push. Don't declare failure on the first 404 — poll `curl` a few times before investigating.
+- **Case-sensitive paths.** Pages hosts are case-sensitive Linux; a site that worked on macOS/Windows can 404 on assets referenced as `Logo.PNG` but committed as `logo.png`. Grep the HTML for mismatched casing when an asset 404s.
+- **Project-page base path.** `https://<owner>.github.io/<name>/` serves under `/<name>/` — absolute asset URLs like `/app.js` break. Use relative paths or set the build tool's base (`vite build --base=/<name>/`).
+- **`wrangler` auth flow needs a browser.** `wrangler login` opens OAuth; in a headless session prefer `CLOUDFLARE_API_TOKEN` (user creates it at dash.cloudflare.com → API Tokens) and never echo the token into logs.
+- **DNS propagation on custom domains.** New CNAMEs can take minutes to hours. Verify against the provider's default URL (`*.pages.dev`, `*.netlify.app`, `*.github.io`) first, then check the custom domain separately — don't conflate the two failures.
+- **Deploying source instead of build output.** Publishing the repo root when the real site lives in `dist/` yields a directory listing or raw JSX. Always confirm the output dir contains an `index.html`.
+
+## Verification
+
+Do NOT report success from the deploy log alone. Before telling the user anything:
+
+1. `curl -sS -o /dev/null -w '%{http_code}' <live-url>` returns `200` (retry over ~2 minutes for a first GitHub Pages deploy).
+2. `curl -sS <live-url> | head -30` shows the expected `index.html` content — optionally confirm markup with `web_extract` on the live URL.
+3. For SPAs, also curl one deep route (e.g. `/about`) and confirm it returns `200`, not `404`.
+4. `git tag --list 'deploy-*'` shows the tag for this deploy.
+
+Then report the live URL to the user, along with the deploy tag they can roll back to.