pagespeed-quest 0.11.0 → 0.13.0

package/llmdocs/10-inventory.md

@@ -6,8 +6,9 @@ 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/
+    └── get/
         └── https/
             └── example.com/
                 ├── index.html
@@ -22,25 +23,32 @@ inventory/
   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, converted to UTF-8 and pretty-printed, so they are diffable and
-  editable by hand.
+  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>/<protocol>/<host>/<pathname>`
+`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/api?id=1` | `contents/GET/https/example.com/api~id=1` |
-| `https://cdn.example.com:8443/a.js` | `contents/GET/https/cdn.example.com~8443/a.js` |
+| `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 `/` (or a path with no extension) gets `index.html`; the query
-string is appended after `~`; a colon in the host becomes `~`; an over-long
-basename is truncated and suffixed with a short SHA-1. Do not rename these files
-by hand — the mapping comes from `contentFilePath` in `index.json`, and the file
-name is only a convenience.
+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`
 
@@ -48,6 +56,7 @@ name is only a convenience.
 {
   "entryUrl": "https://example.com/",
   "deviceType": "mobile",
+  "formatVersion": 2,
   "resources": [ ... ]
 }
 ```
@@ -55,35 +64,49 @@ name is only a convenience.
 `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 |
-| `ttfbMs` | **the proxy sleeps this long after receiving the request, before the first byte.** Per request, not an offset from page start |
-| `durationMs` | recorded transfer duration. Informational; playback derives its own from size and `mbps` |
-| `mbps` | transfer speed for the body. Missing → 1.0 Mbps |
+| `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 instead of the file when present |
+| `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
 
 ```
-response time ≈ ttfbMs  +  (bytes on the wire × 8) / (mbps × 1,000,000)
+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.
-- The second term is recomputed **from the bytes you leave in the file**, after
-  minification and after `contentEncoding` compression. So shrinking a file
-  makes it arrive sooner, automatically, with no other edit.
+- 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.
 
@@ -104,9 +127,10 @@ discarded.
 
 ## Editing safely
 
-1. Copy `inventory/` to `baseline/` before the first edit.
+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.
+   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.

package/llmdocs/20-experiments.md

@@ -1,175 +1,72 @@
-# Experiments — which edit models which optimization
+# Experiments — how an edit reaches the replay
 
-Each recipe is: the hypothesis, the exact edit, what should move, and what to
-watch out for. Make one edit, measure, record the delta, revert or keep. The
-metric names are the Lighthouse ones reported in `artifacts/summary.md`
-(LCP ×0.25, CLS ×0.25, TBT ×0.30, FCP ×0.10, SI ×0.10).
+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.
 
-## Images
-
-### Compress or re-encode an image
-
-**Hypothesis** "the hero image is far heavier than it needs to be."
-
-Replace the file in place, keeping the same path:
-
-```sh
-cwebp -q 75 contents/GET/https/example.com/img/hero.jpg \
-  -o contents/GET/https/example.com/img/hero.jpg
-```
-
-Then, in `index.json`, set the served type to match the new bytes:
-
-```json
-{ "contentTypeMime": "image/webp", "rawHeaders": { "content-type": "image/webp" } }
-```
-
-**Moves** LCP, SI, and total transfer. Transfer time falls in proportion to the
-byte count at the recorded `mbps`.
-
-**Watch out** The URL still ends in `.jpg`; that is fine, browsers go by
-`Content-Type`. Do not touch `content-length`. If the format is not supported by
-the recorded device profile the image simply fails to decode — check
-`psq capture`.
-
-### Serve a correctly sized image
-
-Same edit, but resize rather than re-encode. This is usually the larger win on
-mobile recordings, because the recorded page often ships a desktop-sized asset.
-Compare `summary.md`'s image traffic line before and after.
-
-### Lazy-load below-the-fold images
-
-Edit the document: add `loading="lazy"` to `<img>` elements below the fold.
-
-**Moves** FCP and SI, sometimes LCP indirectly (bandwidth freed for the hero).
-Nothing needs to change in `index.json` — the lazily-loaded requests simply do
-not happen during the measured window.
-
-### Preload the LCP image
-
-```html
-<link rel="preload" as="image" href="/img/hero.webp" fetchpriority="high">
-```
-
-in `<head>`. **Moves** LCP. **Watch out** the recorded `ttfbMs` of that resource
-still applies as a fixed delay, so the win is bounded by it.
-
-## Scripts
-
-### Defer or async a render-blocking script
-
-Edit the document, add `defer` (order preserved) or `async` (order not).
-
-**Moves** FCP, LCP, SI. TBT often moves too, because the work lands after the
-first paint.
-
-### Remove a third-party tag
-
-Delete the `<script>` from the document. Optionally also delete the resource
-from `index.json` — but only after the reference is gone, or the browser will
-record a failed request (see the 404 rule).
-
-**Moves** TBT most visibly, plus whatever the tag was blocking. This is the
-single most informative experiment on most commercial pages: it puts a number on
-"what is the tag manager costing us".
-
-**Watch out** Some tags inject further requests. Removing the parent removes
-those too, which is realistic — but it makes the delta larger than the tag's own
-weight, so say so when reporting.
-
-### Shrink the bundle
-
-Replace the file under `contents/` with a smaller build (drop a polyfill, remove
-a library, run a real minifier). Because the browser actually executes what you
-serve, **TBT and main-thread time respond for real** — this is not a simulated
-number.
-
-## CSS and fonts
-
-### Inline critical CSS, defer the rest
-
-In the document, add a `<style>` block with the above-the-fold rules and switch
-the stylesheet link to a deferred load:
-
-```html
-<link rel="preload" href="/assets/app.css" as="style" onload="this.rel='stylesheet'">
-```
-
-**Moves** FCP, LCP, SI. **Watch out** CLS often gets *worse* if the inlined
-subset is incomplete — check `psq capture --compare` as well as the score.
-
-### Remove unused CSS
-
-Edit the stylesheet under `contents/`. Remember `minify: true` re-minifies, so
-the win shows up as fewer bytes, not as tidier formatting.
-
-### `font-display: swap` and font preloading
-
-Edit the `@font-face` block in the stylesheet, and/or add
-`<link rel="preload" as="font" crossorigin>` to the document.
-
-**Moves** FCP and LCP when text was the largest element; CLS if the swap causes
-reflow. Subsetting the font file itself is the transfer-size half of the same
-experiment.
-
-## Network and server
-
-These are the levers that do not exist in a normal development environment, and
-they are the reason for the `index.json` fields.
-
-### "What if the server responded faster?"
-
-Lower `ttfbMs` on the document resource (often 200–800 ms on a real recording):
-
-```json
-{ "url": "https://example.com/", "ttfbMs": 80 }
-```
-
-**Moves** everything downstream, roughly one-for-one. Run this early — it tells
-you how much of the budget is back-end and therefore *not* fixable in the
-front-end.
-
-### "What if we put it on a CDN / on a faster link?"
-
-Raise `mbps` on the resources served from the slow host. To model a slower
-network instead, lower it. Apply it to a whole host, not a single file, or the
-result will not resemble anything real.
-
-### "What if we finally enabled compression?"
-
-Set `contentEncoding` to `br` (or `gzip`) on the text resources that had
-`identity`. The proxy re-compresses and the transfer time follows.
-
-The reverse — setting `identity` on everything — quantifies what compression is
-already buying you, which is a useful number when someone proposes turning it
-off for CPU reasons.
-
-### "What if there were fewer requests?"
-
-Concatenate two files into one under `contents/`, update the document to
-reference the survivor, and delete the other entry from `index.json`. The win
-here is mostly the removed `ttfbMs`, so it is only worth it where that value is
-large.
-
-## Layout stability
-
-### Reserve space for images and embeds
-
-Add `width` / `height` (or an `aspect-ratio` rule) in the document or the
-stylesheet. **Moves** CLS, which carries the same weight as LCP — a cheap edit
-with a disproportionate score effect.
+## 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.
+- **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
-  its own local server; the real contention on a shared connection is not
-  reproduced.
+  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.
@@ -179,16 +76,18 @@ State these plainly when reporting results.
   moment of recording, which is a feature for comparison and a limitation for
   representativeness.
 
-## Reporting a result
+## Reporting a trial
 
-A useful report answers three questions: what was changed, what moved, and
-whether the page still looks right.
+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.
 
 ```
-Hypothesis : defer the tag manager
-Edit       : removed <script src="gtm.js"> from contents/GET/https/example.com/index.html
-Before     : LCP 3.41s  TBT 890ms  Overall 42   (artifacts-baseline/summary.md)
-After      : LCP 2.78s  TBT 210ms  Overall 61   (artifacts/summary.md)
-Visual     : no diff    (artifacts/capture-diff.txt)
-Caveat     : removing the parent tag also removed 4 requests it injected
+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

@@ -12,40 +12,78 @@ see the same page. Choose by the question being asked.
 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 before / after
+## Lighthouse, several runs per state
 
 ```sh
-psq -i ./baseline  lighthouse -a ./artifacts-baseline playback
-psq -i ./inventory lighthouse -a ./artifacts-after    playback
-diff artifacts-baseline/summary.md artifacts-after/summary.md
+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 |
+| `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`) |
 
-`summary.md` is the file to diff. It is deliberately short and stable, so the
-diff shows the delta and nothing else.
+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.
 
-**Repeat before concluding.** Lighthouse noise on a fixed recording is a few
-points. Three runs per side is usually enough to see whether a delta is real.
+### 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-baseline playback
-psq -i ./inventory loadshow -a ./artifacts-after    playback
+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
@@ -57,15 +95,15 @@ 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-baseline -c "Before" playback
-psq -i ./inventory loadshow -a ./artifacts-after    -c "After — deferred GTM" playback
+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-baseline/loadshow.mp4 -i artifacts-after/loadshow.mp4 \
+ffmpeg -i artifacts/video-baseline/loadshow.mp4 -i artifacts/video-after/loadshow.mp4 \
   -filter_complex hstack -c:v libx264 before-after.mp4
 ```
 
@@ -82,8 +120,8 @@ so that the recording and the playback are driven the same way.
 ## Screenshot and visual diff
 
 ```sh
-psq -i ./baseline capture -a ./artifacts-baseline      # baseline.png
-psq capture --compare ./artifacts-baseline/capture.png \
+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"
 ```
 
@@ -112,6 +150,9 @@ banner will make every metric better and the page wrong.
 - script / 14 / 512.3 KB / 524595
 ```
 
-*Traffic* is what crossed the wire (after compression); *Resource* is the
-decompressed size. A change that moves resource size but not traffic size means
-you edited something that compresses away — expect little timing effect.
+*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.

package/llmdocs/90-commands.md

@@ -12,7 +12,8 @@ Record a web page through a proxy, edit the recording, and replay it to measure
 ```
 Usage: psq [options] [command]
 
-Record a web page through a proxy, edit the recording, and replay it to measure the difference
+Record a web page through a proxy, edit the recording, and replay it to measure
+the difference
 
 Options:
   -v, --version          Output the version number
@@ -23,7 +24,8 @@ Commands:
   lighthouse [options]   Run Lighthouse (performance category) via a proxy
   loadshow [options]     Run loadshow via a proxy
   proxy [options]        Run the playback (or recording) proxy standalone
-  capture [options]      Capture a screenshot via playback proxy and optionally compare with a baseline
+  capture [options]      Capture a screenshot via playback proxy and optionally
+                         compare with a baseline
   llm [options]          Print the embedded reference for AI agents
   help [command]         display help for command
 ```
@@ -39,7 +41,8 @@ Run Lighthouse (performance category) via a proxy
 
 Options:
   -a, --artifacts <dir>      Artifacts directory (default: "./artifacts")
-  -l, --laud                 Show browser and open the report after completion (default: false)
+  -l, --laud                 Show browser and open the report after completion
+                             (default: false)
   -t, --timeout <ms>         Timeout milliseconds (default: "30000")
   -h, --help                 display help for command
 
@@ -63,7 +66,8 @@ Arguments:
 
 Options:
   -d, --device <mobile|desktop>  Device type (default: "mobile")
-  -x, --exclude <pattern>        Regex patterns to exclude URLs from recording (repeatable) (default: [])
+  -x, --exclude <pattern>        Regex patterns to exclude URLs from recording
+                                 (repeatable) (default: [])
   -h, --help                     display help for command
 ```
 
@@ -115,7 +119,8 @@ Arguments:
 
 Options:
   -d, --device <mobile|desktop>  Device type (default: "mobile")
-  -x, --exclude <pattern>        Regex patterns to exclude URLs from recording (repeatable) (default: [])
+  -x, --exclude <pattern>        Regex patterns to exclude URLs from recording
+                                 (repeatable) (default: [])
   -h, --help                     display help for command
 ```
 
@@ -143,8 +148,10 @@ Run the playback (or recording) proxy standalone
 
 Options:
   -p, --port <number>      Proxy port (default: "8080")
-  -r, --record <url>       Recording URL to start the proxy as recording mode (default: "")
-  -x, --exclude <pattern>  Regex patterns to exclude URLs from recording (repeatable) (default: [])
+  -r, --record <url>       Recording URL to start the proxy as recording mode
+                           (default: "")
+  -x, --exclude <pattern>  Regex patterns to exclude URLs from recording
+                           (repeatable) (default: [])
   -h, --help               display help for command
 ```