pagespeed-quest 0.10.0 → 0.12.0

package/llmdocs/00-guide.md

@@ -0,0 +1,146 @@
+# pagespeed-quest — reference for AI agents
+
+PageSpeed Quest (`psq`) records a real page load through an HTTP proxy, writes
+it to disk as an editable set of files, and replays it with the **original
+timing** reproduced. You then edit those files — the HTML, the CSS, the images,
+even the per-resource latency — replay again, and measure the difference.
+
+The point is that you do **not** need the site's development environment, its
+repository, or a deploy. Any public page can be frozen into a local, editable,
+repeatable copy of itself. A hypothesis like "inlining critical CSS would gain
+0.4s of LCP" becomes something you can answer in minutes, on someone else's
+site, before writing a line of production code.
+
+Recording is powered by [rust-http-playback-proxy]. Measurement is delegated to
+[Lighthouse] (scores and metrics), [loadshow] (a video of the load) and
+[static-webshot] (screenshots and visual diffs). `psq` is the layer that makes
+the recording **editable** and the comparison **repeatable**.
+
+[rust-http-playback-proxy]: https://github.com/ideamans/rust-http-playback-proxy
+[Lighthouse]: https://developer.chrome.com/docs/lighthouse/overview/
+[loadshow]: https://github.com/ideamans/go-loadshow
+[static-webshot]: https://github.com/ideamans/static-webshot
+
+This reference ships inside the package, so `psq llm` always describes the exact
+version installed in the project you are working in.
+
+## Ground rules
+
+1. **Record once. Compare against that recording, never against the live site.**
+   The live site changes between runs; the recording does not. That is the whole
+   value proposition. A "before" measured against the network and an "after"
+   measured against the inventory are not comparable numbers.
+
+2. **Copy the inventory before you edit it.** There is no undo, and the baseline
+   is the thing you are comparing to.
+
+   ```sh
+   cp -r inventory baseline
+   ```
+
+   Then measure either side by pointing `-i` at it. Keep `baseline/` untouched
+   for the rest of the quest.
+
+3. **`-i/--inventory` is a root option — it goes before the subcommand.**
+   `psq -i ./baseline lighthouse playback` works; `psq lighthouse playback -i
+   ./baseline` does not. The same applies one level down: `-a`, `-t`, `-l` and
+   `-c` belong to the `lighthouse` / `loadshow` group, so they go *before*
+   `recording` / `playback`.
+
+4. **`playback` takes no URL.** The entry URL and the device type are stored in
+   the inventory at recording time and reused. If you need to change either,
+   record again.
+
+5. **Lighthouse reports the load as observed** (`--throttling-method=provided`,
+   `--throttling.*=0`, `cpuSlowdownMultiplier=1`). Timing is reproduced by the
+   proxy, per resource, so Lighthouse must neither throttle again nor simulate.
+   Its default `simulate` method re-derives the metrics from a network model
+   that ignores the proxy — psq before 0.12 did that, and its numbers could even
+   fall below the document's TTFB. Do not compare scores across that boundary.
+
+6. **Unmatched requests get a 404.** The playback proxy only serves what is in
+   the inventory. That is deliberate — falling through to the network would make
+   the replay non-deterministic. So a URL you delete from `index.json` becomes a
+   failed request, not a request that never happens. To model "this resource is
+   gone", also remove the reference to it from the HTML.
+
+7. **Never conclude from one run.** Runs of the same recording are close but
+   not identical, and an occasional run is an outlier. Measure each state at
+   least three times, compare medians, and treat a difference smaller than the
+   spread within each state as no difference.
+
+8. **The recording run is not the baseline.** `psq lighthouse recording` also
+   writes a Lighthouse report, but it measured the live site through the
+   recording proxy. Send it somewhere out of the way
+   (`psq lighthouse -a ./artifacts/recording recording <url>`) and measure the
+   baseline by playback.
+
+## The loop
+
+```sh
+# 1. Freeze the page (writes ./inventory)
+npx psq lighthouse -a ./artifacts/recording recording https://example.com/
+
+# 2. Keep the untouched copy, and a copy that accumulates adopted changes
+cp -r inventory baseline
+cp -r inventory accepted
+
+# 3. Measure the baseline, three runs  → artifacts/baseline-N/summary.md, lighthouse.report.json
+for n in 1 2 3; do npx psq -i ./baseline lighthouse -a ./artifacts/baseline-$n playback; done
+
+# 4. Each trial: start from accepted, make ONE edit to ./inventory (chapter "Experiments")
+rm -rf inventory && cp -r accepted inventory
+
+# 5. Measure the trial, three runs, and check it still renders (chapter "Measuring")
+for n in 1 2 3; do npx psq lighthouse -a ./artifacts/t01-$n playback; done
+
+# 6. Better beyond the spread and visually unchanged → adopt it
+rm -rf accepted && cp -r inventory accepted
+
+# 7. At the end, measure accepted against baseline from scratch
+for n in 1 2 3; do npx psq -i ./accepted lighthouse -a ./artifacts/final-$n playback; done
+```
+
+`summary.md` is a short Markdown digest (metrics, per-metric scores with their
+Lighthouse weights, traffic by resource type). Medians across runs and the
+evidence for *why* a page is slow come from `lighthouse.report.json` — see
+"Measuring".
+
+## What lives where
+
+| Path | What it is |
+| --- | --- |
+| `inventory/index.json` | the resource list and every resource's metadata. This is the file the proxy reads |
+| `baseline/`, `accepted/` | conventional copies: the page as recorded, and the page with the adopted changes |
+| `inventory/contents/<method>/<protocol>/<host>/<path>` | one file per recorded response body; `contentFilePath` gives the exact path |
+| `artifacts/lighthouse.report.html`, `.report.json` | the full Lighthouse report |
+| `artifacts/summary.md` | the digest to diff |
+| `artifacts/lighthouse.digest.png` | score and metrics as an image |
+| `artifacts/loadshow.mp4` | filmstrip video of the load |
+| `artifacts/capture.png`, `capture-diff.png`, `capture-diff.txt` | screenshot and visual diff |
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `playback` serves nothing, every request 404s | the inventory is empty, or `-i` points at the wrong directory | record first; check `inventory/index.json` exists and `resources` is non-empty |
+| `unknown option '-i'` / the option is ignored | root and group options were placed after the subcommand | `psq -i ./baseline lighthouse -a ./art playback` |
+| the "after" is faster but the page is visibly broken | a referenced resource was deleted from `index.json` but not from the HTML | run `psq capture --compare` and look at the diff before trusting any number |
+| edits to a `.js` / `.css` file seem to have no effect on transfer size | the resource has `"minify": true`, so playback re-minifies before serving | expected — the wire size reflects the minified bytes, which is what the original site shipped |
+| a smaller file loads no faster | the recording has no `formatVersion: 2` (made before psq 0.12) and replays the recorded duration | re-record |
+| the page looks fine but LCP got worse for no reason | an edit changed the byte size of a resource, and transfer time scales with size at the recorded `mbps` | that *is* the simulation working; check `summary.md` traffic figures |
+| recording captured analytics and ad beacons | third parties were not excluded | re-record with `-x 'google-analytics|doubleclick|facebook'` (repeatable) |
+| `loadshow` / `static-webshot` not found | the postinstall step that downloads them did not run | re-run `npm rebuild pagespeed-quest`, or set `LOADSHOW_PATH` / `WEBSHOT_PATH` |
+| Lighthouse cannot be found | it resolves to `./node_modules/.bin/lighthouse` | run inside the quest project, or set `LIGHTHOUSE_PATH` |
+| numbers drift between identical runs | normal measurement noise | three runs or more per state; compare medians against the spread |
+| the baseline came from the recording run | that report measured the live site | measure the baseline with `psq -i ./baseline lighthouse … playback` |
+| trial deltas cannot be attributed | a trial was built on the previous trial, or bundled several edits | start every trial from a fresh copy of `accepted/`, one edit each |
+
+## What this tool will not do
+
+- It does not crawl. One entry URL plus whatever that page load requests.
+- It does not modify the live site, and nothing you edit locally reaches it.
+- It does not rewrite your resources for you, and this reference does not
+  prescribe optimizations. Deciding what to change is the work; this reference
+  covers how an edit reaches the replay and how to measure it.
+- It does not replay user interaction. What is recorded is one page load.

package/llmdocs/10-inventory.md

@@ -0,0 +1,157 @@
+# The inventory — what you edit
+
+The inventory is the reverse-engineered page. Everything the browser will
+receive during playback comes from here, and nothing else does.
+
+```
+inventory/
+├── index.json                     ← the resource list. THIS is what the proxy reads
+├── originals/                     ← the recorded wire bytes of reformatted bodies. Never edit
+└── contents/
+    └── get/
+        └── https/
+            └── example.com/
+                ├── index.html
+                ├── assets/app.css
+                ├── assets/app.js
+                └── img/hero.jpg
+```
+
+- **`index.json` is authoritative.** The playback proxy reads exactly that file
+  name. If a file called `inventory.json` also exists (older recordings wrote
+  both names), `psq` will read *that* one for the entry URL, device type and
+  traffic figures while the proxy serves from `index.json` — the two silently
+  disagree. Delete `inventory.json`, or keep it byte-identical.
+- **`contents/` holds one file per response body.** Text bodies are stored
+  decoded and converted to UTF-8; minified CSS and JavaScript are also
+  pretty-printed (and marked `minify: true`), HTML is kept as recorded.
+- **`originals/` keeps the bytes that went over the wire** for every body that
+  was stored differently (decompressed, re-encoded or pretty-printed). Playback
+  serves them for unedited resources. Do not edit or delete it.
+
+## How a URL becomes a path
+
+`contents/<method, lower-case>/<protocol>/<host>/<pathname>`
+
+| URL | File |
+| --- | --- |
+| `https://example.com/` | `contents/get/https/example.com/index.html` |
+| `https://example.com/assets/app.css` | `contents/get/https/example.com/assets/app.css` |
+| `https://example.com/app.js?v=1` | `contents/get/https/example.com/app~v%3D1.js` |
+
+Rules: a trailing `/` gets `index.html`; the query string is URL-encoded and
+inserted after `~`, before the extension; a query longer than 32 characters is
+cut there and suffixed with `.~<sha1 of the rest>`. Do not guess and do not
+rename these files by hand — `contentFilePath` in `index.json` (relative to the
+inventory directory, so it starts with `contents/`) is the mapping, and the file
+name is only a convenience:
+
+```sh
+jq -r '.resources[] | [.url, .contentFilePath] | @tsv' inventory/index.json
+```
+
+## `index.json`
+
+```json
+{
+  "entryUrl": "https://example.com/",
+  "deviceType": "mobile",
+  "formatVersion": 2,
+  "resources": [ ... ]
+}
+```
+
+`entryUrl` and `deviceType` are what `playback` uses instead of asking you for a
+URL. Changing `deviceType` here changes the Lighthouse form factor and the
+loadshow preset on the next playback — it does **not** re-record.
+`formatVersion` is `2` for recordings made with psq 0.12 or later; without it
+the older timing model applies (see below).
+
+### A resource
+
+| Field | Effect at playback time |
+| --- | --- |
+| `method`, `url` | how the request is matched. A request that matches nothing gets a 404. Required |
+| `ttfbMs` | **the proxy sleeps this long after receiving the request, before the first byte.** Per request, not an offset from page start. Required |
+| `durationMs` | recorded transfer duration. Used as-is only by recordings without `formatVersion: 2` |
+| `mbps` | transfer speed for the body, measured at recording. Used for an edited body. Missing → the median of the same host |
+| `statusCode` | the status served |
+| `rawHeaders` | headers served, minus `content-length` and `content-encoding`, which are recomputed |
+| `contentEncoding` | `gzip` / `br` / `deflate` / `zstd` / `compress` / `identity`. The body is **re-compressed with this before it goes on the wire**, so it decides the transferred size |
+| `contentTypeMime`, `contentCharset` | the `Content-Type` served. `contentCharset` re-encodes the body from UTF-8 on the way out |
+| `contentFilePath` | the file under `contents/` to serve |
+| `contentUtf8` / `contentBase64` | inline body, used only when there is no `contentFilePath`. Recordings do not write it |
+| `minify` | `true` → the body is **re-minified before serving**. Set during recording when the original was minified |
+| `httpVersion` | protocol version reported for the response |
+| `original` | written by the recorder: the path of the recorded wire bytes under `originals/`, a SHA-256 of the file in `contents/`, and the `contentEncoding` / `contentCharset` / `minify` at recording time. **Do not edit** |
+
+### The timing model, precisely
+
+```
+unedited body:  recorded wire bytes, ttfbMs + the recorded transfer time
+edited body:    ttfbMs  +  (bytes on the wire × 8) / (mbps × 1,000,000)
+```
+
+- A body is **unedited** while its file still matches the hash in `original`
+  and `contentEncoding`, `contentCharset` and `minify` are as recorded. It is
+  then served byte for byte as the site sent it — same compression, same size,
+  same time. Changing any of those makes it edited.
+- `ttfbMs` is a fixed per-request delay. It models server think time plus
+  connection latency. Lower it to model a faster origin or a nearer CDN edge.
+- For an edited body the transfer time is recomputed **from the bytes you leave
+  in the file**, after minification and after `contentEncoding` compression. So
+  shrinking a file makes it arrive sooner, with no other edit. `mbps` was
+  measured per resource at recording, so the same bytes take the time they took
+  on that connection.
+- **Recordings without `formatVersion: 2`** (psq before 0.12) replay every body
+  in its recorded `durationMs` whatever its size, and re-minify text bodies with
+  an older minifier. Shrinking a file does not make it faster there. Re-record
+  to get the model above.
+- `--full-throttle` (used internally by `psq capture`) skips both. Never compare
+  a full-throttle run with a normal one.
+
+### Two traps worth stating plainly
+
+**`minify: true` re-minifies your edit.** The pretty-printed file in `contents/`
+is for you; the wire sees the minified form. This keeps the byte count honest —
+the original site shipped minified bytes — but it means whitespace edits have no
+size effect, and it means a syntax error introduced during editing can surface
+as a minifier failure rather than a browser error.
+
+**`contentEncoding` decides the transferred size, not the file size.** A 300 KB
+JavaScript file with `"contentEncoding": "br"` is perhaps 60 KB on the wire, and
+that 60 KB is what the timing is computed from. To model "we turned compression
+off", set it to `identity`; to model "we finally enabled Brotli", set it to
+`br`. Do not edit `content-length` — it is recomputed and your value is
+discarded.
+
+## Editing safely
+
+1. Copy `inventory/` to `baseline/` (and to `accepted/`) before the first edit.
+2. Change **one thing at a time**, then measure. Two edits in one run means you
+   cannot attribute the delta. Start each trial from a fresh copy of
+   `accepted/` (see "The loop" in the guide).
+3. After a structural edit (removing a script, changing a URL), run
+   `psq capture --compare` and look at the picture. A faster broken page is easy
+   to produce and easy to mistake for a win.
+4. Keep the inventory in version control if the quest lasts more than a day.
+   `git diff` over `contents/` is a readable record of the hypothesis.
+
+## Live editing with a browser
+
+```sh
+psq proxy -p 8080
+```
+
+serves the inventory and **watches it**: any change under `inventory/` restarts
+the proxy, so a browser pointed at `http://localhost:8080` picks up your edit on
+the next reload. The proxy uses a dummy certificate, so the browser has to be
+told to accept it:
+
+```sh
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --ignore-certificate-errors --proxy-server=http://localhost:8080
+```
+
+This is the fastest way to iterate on markup edits before spending a Lighthouse
+run on them.

package/llmdocs/20-experiments.md

@@ -0,0 +1,93 @@
+# Experiments — how an edit reaches the replay
+
+This chapter is about the mechanics of changing a recording so that a replay
+reflects a change you want to test. **It does not prescribe optimizations** —
+deciding what to try is the agent's or the engineer's judgement. What matters
+here is that the edit models what you intend, and nothing else.
+
+Paths below are relative to the inventory directory.
+
+## Content edits
+
+Edit the file a resource's `contentFilePath` points to. The browser receives and
+executes exactly those bytes, so effects on parsing, script execution, layout
+and paint are **measured, not estimated**, and the transfer time follows the new
+size (see the timing model in "The inventory" — this needs a recording with
+`formatVersion: 2`, i.e. made with psq 0.12 or later).
+
+psq-specific rules:
+
+- **Changing an image's format** — replace the bytes at the same path, then set
+  the served type to match:
+
+  ```json
+  { "contentTypeMime": "image/webp", "rawHeaders": { "content-type": "image/webp" } }
+  ```
+
+  The URL may keep its old extension; browsers go by `Content-Type`. Never edit
+  `content-length`.
+- **`minify: true`** — the file is re-minified before serving. Whitespace has no
+  effect on the wire; a syntax error may surface as a minifier failure.
+- **Leave `original` and `originals/` alone.** They are how playback recognises
+  the resources you did not touch and serves them exactly as recorded.
+- **`ttfbMs` does not move with the content.** A preloaded, reprioritised or
+  shrunk resource still waits its recorded `ttfbMs` before its first byte.
+
+## Adding and removing resources
+
+- **Removing**: delete the reference from the HTML (or CSS, or script) in the
+  same edit. An entry deleted while still referenced becomes a 404 — a failed
+  request, which makes the result look worse than the truth. Removing a parent
+  tag also removes whatever it would have injected; say so when reporting.
+- **Adding** (a split file, a self-hosted font, a new preload): add an entry to
+  `resources`. `method`, `url` and `ttfbMs` are required — an entry missing them
+  makes `index.json` unreadable. Set `statusCode`, `contentTypeMime` and
+  `contentFilePath`, and copy `ttfbMs` / `mbps` from a comparable resource on
+  the same host so the timing is not invented. Any URL the browser requests
+  that has no entry gets a 404.
+
+## Metadata edits — what a front-end change cannot do
+
+These levers do not exist in a normal development environment, and they are the
+reason for the `index.json` fields.
+
+| To model | Edit | Note |
+| --- | --- | --- |
+| a faster or slower origin | lower / raise `ttfbMs`, the document first | separates the back-end share of the load from the front-end share |
+| a faster or slower link, a CDN | `mbps` on every resource of that host | per host, not per file, or the result resembles nothing real |
+| compression on or off | `contentEncoding` (`br`, `gzip`, `identity`) on text resources | the proxy re-compresses; the reverse quantifies what compression already buys |
+| a different form factor | top-level `deviceType` | changes the Lighthouse form factor and the loadshow preset; does not re-record |
+
+## What this cannot model
+
+State these plainly when reporting results.
+
+- **Caching across page views.** Every playback is a cold load, so
+  `cache-insight` and `bf-cache` findings cannot be acted on in a replay.
+- **HTTP/2 prioritisation and connection contention.** Each host is served by
+  the local proxy; the real contention on a shared connection is not
+  reproduced, and `modern-http-insight` describes the proxy, not the origin.
+- **Server-side changes that alter the HTML.** You can hand-edit the HTML to
+  what the server *would* emit, but the edit is your hypothesis, not a
+  measurement of it.
+- **Anything after the load.** Interaction, INP, scrolling — a recording is one
+  page load.
+- **Variable content.** Personalised or A/B-tested pages are frozen at the
+  moment of recording, which is a feature for comparison and a limitation for
+  representativeness.
+
+## Reporting a trial
+
+A useful line answers four questions: what was changed, what evidence led to it,
+what moved (medians of several runs, reference → trial), and whether the page
+still looks right.
+
+```
+Trial      : t01 defer tag manager
+Evidence   : render-blocking-insight lists gtm.js
+Edit       : contents/get/https/example.com/index.html — added defer to <script src="gtm.js">
+Reference  : Score 61  LCP 3.41s  TBT 890ms   (median of 3, artifacts/baseline-*)
+Trial      : Score 68  LCP 2.95s  TBT 640ms   (median of 3, artifacts/t01-defer-gtm-*)
+Visual     : no diff (artifacts/t01-capture/capture-diff.txt)
+Decision   : adopted
+```

package/llmdocs/30-measuring.md

@@ -0,0 +1,158 @@
+# Measuring — scores, video, screenshots
+
+Three measurement surfaces, all driven through the same playback proxy so they
+see the same page. Choose by the question being asked.
+
+| Question | Command | Read |
+| --- | --- | --- |
+| Did the score move? | `psq lighthouse playback` | `artifacts/summary.md` |
+| What does the difference look like? | `psq loadshow playback` | `artifacts/loadshow.mp4` |
+| Did I break the page? | `psq capture --compare <png>` | `artifacts/capture-diff.png` |
+
+Keep the two sides in separate artifact directories. `-a` is an option of the
+`lighthouse` / `loadshow` group, so it goes before the sub-subcommand.
+
+## Lighthouse, several runs per state
+
+```sh
+for n in 1 2 3; do psq -i ./baseline lighthouse -a ./artifacts/baseline-$n playback; done
+for n in 1 2 3; do psq -i ./inventory lighthouse -a ./artifacts/t01-$n playback; done
+```
+
+One directory per run — the same `-a` twice overwrites. Name them
+`<label>-<n>`, the label naming the state.
+
+Each run writes:
+
+| File | Contents |
+| --- | --- |
+| `summary.md` | metrics, per-metric scores with weights, overall score, traffic and resource size by type |
+| `lighthouse.report.html` | the full report (open it when a number needs explaining) |
+| `lighthouse.report.json` | the same, machine-readable — the source for medians and for the diagnosis |
+| `lighthouse.digest.png` | score gauge and metrics as one image — the thing to paste into a report |
+| `lighthouse-0.trace.json`, `*.devtoolslog.json` | saved assets (`--save-assets`) |
+
+A playback run takes roughly 20–30 seconds: Lighthouse measures the load as
+observed (`--throttling-method=provided`) and waits for the page to go quiet.
+
+Options on the `lighthouse` group: `-a/--artifacts` (default `./artifacts`),
+`-t/--timeout` (ms, default 30000), `-l/--laud` — show the browser window and
+open the report at the end. `--laud` is for watching a run, not for measuring;
+a visible browser is not the same environment as the headless one.
+
+### Medians and spread
+
+**Never conclude from one run.** Runs of the same recording are close but not
+identical, and an occasional run is an outlier. Take the median of at least three runs
+per state, and call a difference real only when it is larger than the spread
+(max − min) within each state:
+
+```sh
+jq -s -r '
+  def median: sort | if length % 2 == 1 then .[length/2|floor] else (.[length/2-1] + .[length/2]) / 2 end;
+  map({Score: (.categories.performance.score*100),
+       LCP: .audits["largest-contentful-paint"].numericValue,
+       FCP: .audits["first-contentful-paint"].numericValue,
+       SI:  .audits["speed-index"].numericValue,
+       TBT: .audits["total-blocking-time"].numericValue,
+       CLS: .audits["cumulative-layout-shift"].numericValue}) as $r
+  | ["Score","LCP","FCP","SI","TBT","CLS"][] as $m | [$r[][$m]] as $v
+  | "\($m)\t\($v|median)\t\($v|min)\t\($v|max)"' artifacts/baseline-*/lighthouse.report.json
+```
+
+### Where the time goes
+
+`lighthouse.report.json` holds the evidence. With
+`J=artifacts/baseline-1/lighthouse.report.json`:
+
+| Question | jq |
+| --- | --- |
+| which audits flag a problem | `.audits[] \| select(.score != null and .score < 1) \| [.id, .displayValue, .metricSavings]` |
+| the LCP element | `.audits["lcp-breakdown-insight"].details.items[] \| select(.type=="node") \| .snippet` |
+| how LCP time splits | `.audits["lcp-breakdown-insight"].details.items[] \| select(.type=="table") \| .items` |
+| the request waterfall | `.audits["network-requests"].details.items` (`networkRequestTime`, `networkEndTime`, `transferSize`, `url`) |
+| script cost per URL | `.audits["bootup-time"].details.items` |
+| third parties | `.audits["third-parties-insight"].details.items` |
+
+Lighthouse 13 keeps most of its diagnosis in `*-insight` audits. To act on a
+URL, look up its `contentFilePath` in `index.json`. `cache-insight`, `bf-cache`,
+`modern-http-insight` and interaction metrics describe things a replay cannot
+model (see "Experiments").
+
+## Video of the load, before and after
+
+```sh
+psq -i ./baseline loadshow -a ./artifacts/video-baseline playback
+psq -i ./accepted loadshow -a ./artifacts/video-after    playback
+```
+
+Each writes `<artifacts>/loadshow.mp4` — a filmstrip of the load, laid out in
+3 columns for mobile recordings and 2 for desktop, plus
+`<artifacts>/loadshow/summary.md` and the intermediate frames in
+`<artifacts>/loadshow/`.
+
+Use `-c/--credit` to stamp a label into the video, which is what makes a pair of
+videos legible side by side:
+
+```sh
+psq -i ./baseline loadshow -a ./artifacts/video-baseline -c "Before" playback
+psq -i ./accepted loadshow -a ./artifacts/video-after    -c "After — deferred GTM" playback
+```
+
+To place them side by side, stack the two MP4s with ffmpeg; `psq` does not
+compose videos:
+
+```sh
+ffmpeg -i artifacts/video-baseline/loadshow.mp4 -i artifacts/video-after/loadshow.mp4 \
+  -filter_complex hstack -c:v libx264 before-after.mp4
+```
+
+### Recording *with* loadshow rather than Lighthouse
+
+```sh
+psq loadshow recording https://example.com/
+```
+
+Lighthouse and loadshow drive the browser slightly differently. If the goal of
+the quest is the video rather than the score, record with `loadshow recording`
+so that the recording and the playback are driven the same way.
+
+## Screenshot and visual diff
+
+```sh
+psq -i ./baseline capture -a ./artifacts/baseline-capture
+psq capture -a ./artifacts/t01-capture --compare ./artifacts/baseline-capture/capture.png \
+    --baseline-label "Before" --current-label "After"
+```
+
+`capture` runs the proxy in **full-throttle** mode — no TTFB, no bandwidth
+simulation — because the question is what the page looks like when fully
+loaded, not when. Never quote a timing number from a `capture` run.
+
+Output: `capture.png` (rendered at 400×1600, resized to 200×800),
+`capture-diff.png`, and `capture-diff.txt` with a text digest of the difference.
+
+Run this after **every** structural edit. A deleted script that also removed a
+banner will make every metric better and the page wrong.
+
+## Reading `summary.md`
+
+```
+## Metrics
+- LCP 2780 ms
+- CLS 0.02
+...
+## Scores
+- LCP 0.71 x0.25
+- TBT 0.88 x0.30
+- **Overall** 0.61
+## Traffic: Type / Count / Size / Bytes
+- script / 14 / 512.3 KB / 524595
+```
+
+*Traffic* is what the browser received in this run, as Lighthouse measured it
+(after compression, headers included); *Resource* is the decoded body size.
+Both come from the report's `network-requests` audit, so they count every
+request the page made, including 404s. A change that moves resource size but
+not traffic size means you edited something that compresses away — expect
+little timing effect.