pagespeed-quest 0.10.0 → 0.11.0

package/build/command.js

@@ -1,230 +1,4 @@
 #!/usr/bin/env node
-import Path from 'path';
-import { Command } from 'commander';
-import Watch from 'node-watch';
-import { Dependency } from './dependency.js';
-import { execLighthouse } from './lighthouse.js';
-import { execLoadshow } from './loadshow.js';
-import { execWebshotCapture, execWebshotCompare } from './webshot.js';
-import { InventoryRepository, withPlaybackProxy, withRecordingProxy } from './index.js';
-const dependency = new Dependency();
-function collect(value, previous) {
-    return previous.concat([value]);
-}
-const main = new Command();
-main.option('-i, --inventory <dir>', 'Inventory directory', './inventory');
-function registerLighthouseCommands(main) {
-    const lighthouse = main.command('lighthouse');
-    lighthouse.description('Run Lighthouse (performance category) via a proxy');
-    lighthouse.option('-a, --artifacts <dir>', 'Artifacts directory', './artifacts');
-    lighthouse.option('-l, --laud', 'Show browser and open the report after completion', false);
-    lighthouse.option('-t, --timeout <ms>', 'Timeout milliseconds', '30000');
-    const recording = lighthouse.command('recording');
-    recording.description('Record contents by lighthouse');
-    recording.option('-d, --device <mobile|desktop>', 'Device type', 'mobile');
-    recording.option('-x, --exclude <pattern>', 'Regex patterns to exclude URLs from recording (repeatable)', collect, []);
-    recording.argument('<url>', 'Url to measure performance');
-    recording.action(async (url) => {
-        const inventoryRepository = new InventoryRepository(main.opts().inventory || './inventory');
-        const deviceType = recording.opts().device || 'mobile';
-        const artifactsDir = lighthouse.opts().artifacts || './artifacts';
-        const laud = !!lighthouse.opts().laud;
-        const timeout = Number(lighthouse.opts().timeout || '30000');
-        const excludePatterns = recording.opts().exclude || [];
-        await withRecordingProxy({
-            entryUrl: url,
-            deviceType,
-            inventoryRepository,
-            excludePatterns: excludePatterns.length > 0 ? excludePatterns : undefined,
-        }, dependency, async (proxy) => {
-            await execLighthouse({
-                url,
-                proxyPort: proxy.port,
-                deviceType,
-                view: laud,
-                artifactsDir,
-                headless: !laud,
-                timeout,
-            }, dependency);
-            dependency.logger?.info('Lighthouse completed. Saving inventory...');
-        });
-    });
-    const playback = lighthouse.command('playback');
-    playback.description('Playback contents for lighthouse');
-    playback.action(async () => {
-        const inventoryDir = main.opts().inventory || './inventory';
-        const inventoryRepository = new InventoryRepository(inventoryDir);
-        const artifactsDir = lighthouse.opts().artifacts || './artifacts';
-        const laud = !!lighthouse.opts().laud;
-        const timeout = Number(lighthouse.opts().timeout || '30000');
-        // Load inventory for traffic statistics
-        const inventory = await inventoryRepository.loadInventory();
-        await withPlaybackProxy({
-            inventoryRepository,
-        }, dependency, async (proxy) => {
-            await execLighthouse({
-                url: proxy.entryUrl,
-                proxyPort: proxy.port,
-                deviceType: proxy.deviceType,
-                view: laud,
-                artifactsDir,
-                headless: !laud,
-                timeout,
-                inventoryDir,
-                resources: inventory.resources,
-            }, dependency);
-            dependency.logger?.info('Lighthouse completed');
-        });
-    });
-}
-function registerLoadshowCommands(main) {
-    const loadshow = main.command('loadshow');
-    loadshow.description('Run loadshow via a proxy');
-    loadshow.option('-a, --artifacts <dir>', 'Artifacts directory', './artifacts');
-    loadshow.option('-c, --credit <string>', 'Credit string');
-    loadshow.option('-t, --timeout <ms>', 'Timeout milliseconds', '30000');
-    const recording = loadshow.command('recording');
-    recording.description('Record contents by loadshow');
-    recording.option('-d, --device <mobile|desktop>', 'Device type', 'mobile');
-    recording.option('-x, --exclude <pattern>', 'Regex patterns to exclude URLs from recording (repeatable)', collect, []);
-    recording.argument('<url>', 'Url to measure performance');
-    recording.action(async (url) => {
-        const inventoryRepository = new InventoryRepository(main.opts().inventory || './inventory');
-        const deviceType = recording.opts().device || 'mobile';
-        const artifactsDir = loadshow.opts().artifacts || './artifacts';
-        const credit = loadshow.opts().credit || '';
-        const timeout = Number(loadshow.opts().timeout || '30000');
-        const excludePatterns = recording.opts().exclude || [];
-        await withRecordingProxy({
-            entryUrl: url,
-            deviceType,
-            inventoryRepository,
-            excludePatterns: excludePatterns.length > 0 ? excludePatterns : undefined,
-        }, dependency, async (proxy) => {
-            await execLoadshow({ url, proxyPort: proxy.port, deviceType, artifactsDir, credit, timeout }, dependency);
-            dependency.logger?.info('Loadshow completed. Saving inventory...');
-        });
-    });
-    const playback = loadshow.command('playback');
-    playback.description('Playback contents for loadshow');
-    playback.action(async () => {
-        const inventoryRepository = new InventoryRepository(main.opts().inventory || './inventory');
-        const artifactsDir = loadshow.opts().artifacts || './artifacts';
-        const credit = loadshow.opts().credit || '';
-        const timeout = Number(loadshow.opts().timeout || '30000');
-        await withPlaybackProxy({
-            inventoryRepository,
-        }, dependency, async (proxy) => {
-            await execLoadshow({
-                url: proxy.entryUrl,
-                proxyPort: proxy.port,
-                deviceType: proxy.deviceType,
-                artifactsDir,
-                credit,
-                timeout,
-            }, dependency);
-            dependency.logger?.info('Loadshow completed');
-        });
-    });
-}
-function registerProxyCommands(main) {
-    const proxy = main.command('proxy');
-    proxy.option('-p, --port <number>', 'Proxy port', '8080');
-    proxy.option('-r, --record <url>', 'Recording URL to start the proxy as recording mode', '');
-    proxy.option('-x, --exclude <pattern>', 'Regex patterns to exclude URLs from recording (repeatable)', collect, []);
-    proxy.action(async () => {
-        const inventoryRepository = new InventoryRepository(main.opts().inventory || './inventory');
-        const port = Number(proxy.opts().port || '8080');
-        if (proxy.opts().record) {
-            const url = proxy.opts().record;
-            if (!url) {
-                throw new Error('Recording URL must be specified with --record option.');
-            }
-            const excludePatterns = proxy.opts().exclude || [];
-            // Recordingモード
-            await withRecordingProxy({
-                inventoryRepository,
-                port,
-                entryUrl: url,
-                excludePatterns: excludePatterns.length > 0 ? excludePatterns : undefined,
-            }, dependency, async () => {
-                dependency.logger?.info(`Recording proxy started on port ${port}. Press Ctrl+C to stop.`);
-                // Wait for Ctrl+C signal
-                return new Promise((resolve) => {
-                    process.on('SIGINT', () => {
-                        dependency.logger?.info('Saving the inventory...');
-                        resolve();
-                    });
-                });
-            });
-        }
-        else {
-            // Playbackモード
-            // eslint-disable-next-line no-constant-condition
-            while (true) {
-                await withPlaybackProxy({ inventoryRepository, port }, dependency, async () => {
-                    const watcher = Watch(inventoryRepository.dirPath, { recursive: true });
-                    return new Promise((ok) => {
-                        watcher.on('change', () => {
-                            watcher.close();
-                            dependency.logger?.info('Inventory changed. Restarting proxy...');
-                            ok();
-                        });
-                    });
-                });
-            }
-        }
-    });
-}
-function registerCaptureCommands(main) {
-    const visualTest = main.command('capture');
-    visualTest.description('Capture a screenshot via playback proxy and optionally compare with a baseline');
-    visualTest.option('-a, --artifacts <dir>', 'Artifacts directory', './artifacts');
-    visualTest.option('-t, --timeout <ms>', 'Timeout milliseconds', '30000');
-    visualTest.option('--compare <file>', 'Baseline PNG file to compare against');
-    visualTest.option('--baseline-label <label>', 'Label for the baseline image', '前回');
-    visualTest.option('--current-label <label>', 'Label for the current image', '今回');
-    visualTest.action(async () => {
-        const inventoryRepository = new InventoryRepository(main.opts().inventory || './inventory');
-        const artifactsDir = visualTest.opts().artifacts || './artifacts';
-        const timeout = Number(visualTest.opts().timeout || '30000');
-        const compareFile = visualTest.opts().compare;
-        const baselineLabel = visualTest.opts().baselineLabel || '前回';
-        const currentLabel = visualTest.opts().currentLabel || '今回';
-        await withPlaybackProxy({
-            inventoryRepository,
-            fullThrottle: true,
-        }, dependency, async (proxy) => {
-            const outputPath = Path.join(artifactsDir, 'capture.png');
-            await dependency.mkdirp(artifactsDir);
-            await execWebshotCapture({
-                url: proxy.entryUrl,
-                proxyPort: proxy.port,
-                preset: proxy.deviceType === 'desktop' ? 'desktop' : 'mobile',
-                output: outputPath,
-                timeout,
-            }, dependency);
-            dependency.logger?.info(`Screenshot saved to ${outputPath}`);
-            if (compareFile) {
-                const diffOutput = Path.join(artifactsDir, 'capture-diff.png');
-                const digestTxt = Path.join(artifactsDir, 'capture-diff.txt');
-                await execWebshotCompare({
-                    baseline: compareFile,
-                    current: outputPath,
-                    output: diffOutput,
-                    digestTxt,
-                    baselineLabel,
-                    currentLabel,
-                }, dependency);
-                dependency.logger?.info(`Diff image saved to ${diffOutput}`);
-                dependency.logger?.info(`Diff digest saved to ${digestTxt}`);
-            }
-        });
-    });
-}
-registerLighthouseCommands(main);
-registerLoadshowCommands(main);
-registerProxyCommands(main);
-registerCaptureCommands(main);
-main.parse(process.argv);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29tbWFuZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9jb21tYW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFFQSxPQUFPLElBQUksTUFBTSxNQUFNLENBQUE7QUFFdkIsT0FBTyxFQUFFLE9BQU8sRUFBRSxNQUFNLFdBQVcsQ0FBQTtBQUNuQyxPQUFPLEtBQUssTUFBTSxZQUFZLENBQUE7QUFFOUIsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLGlCQUFpQixDQUFBO0FBQzVDLE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQTtBQUNoRCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sZUFBZSxDQUFBO0FBRTVDLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGNBQWMsQ0FBQTtBQUVyRSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsaUJBQWlCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxZQUFZLENBQUE7QUFFdkYsTUFBTSxVQUFVLEdBQUcsSUFBSSxVQUFVLEVBQUUsQ0FBQTtBQUVuQyxTQUFTLE9BQU8sQ0FBQyxLQUFhLEVBQUUsUUFBa0I7SUFDaEQsT0FBTyxRQUFRLENBQUMsTUFBTSxDQUFDLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQTtBQUNqQyxDQUFDO0FBRUQsTUFBTSxJQUFJLEdBQUcsSUFBSSxPQUFPLEVBQUUsQ0FBQTtBQUMxQixJQUFJLENBQUMsTUFBTSxDQUFDLHVCQUF1QixFQUFFLHFCQUFxQixFQUFFLGFBQWEsQ0FBQyxDQUFBO0FBRTFFLFNBQVMsMEJBQTBCLENBQUMsSUFBYTtJQUMvQyxNQUFNLFVBQVUsR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLFlBQVksQ0FBQyxDQUFBO0lBQzdDLFVBQVUsQ0FBQyxXQUFXLENBQUMsbURBQW1ELENBQUMsQ0FBQTtJQUMzRSxVQUFVLENBQUMsTUFBTSxDQUFDLHVCQUF1QixFQUFFLHFCQUFxQixFQUFFLGFBQWEsQ0FBQyxDQUFBO0lB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
+import { createProgram } from './cli.js';
+createProgram().parse(process.argv);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29tbWFuZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9jb21tYW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFFQSxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sVUFBVSxDQUFBO0FBRXhDLGFBQWEsRUFBRSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUEifQ==

package/build/llm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Directory holding the single source of knowledge served to AI agents.
+ *
+ * The Markdown files are shipped with the npm package (see the `files` field in
+ * package.json) so that `psq llm` works offline and always matches the version
+ * of the package that is installed. They are also what context7 crawls.
+ */
+export declare const LlmDocsDir: string;
+/** Version of the installed package, used by `psq --version`. */
+export declare function packageVersion(): string;
+export interface LlmDocChapter {
+    /** File name without the numeric prefix and extension, e.g. `guide` */
+    name: string;
+    /** First level-1 heading of the chapter */
+    title: string;
+    /** Markdown body, heading included */
+    content: string;
+}
+export declare function loadLlmDocs(dir?: string): Promise<LlmDocChapter[]>;
+export declare function renderLlmDocs(format?: 'markdown' | 'json', dir?: string): Promise<string>;

package/build/llm.js

@@ -0,0 +1,42 @@
+import Fs from 'fs';
+import Fsp from 'fs/promises';
+import Path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = Path.dirname(__filename);
+/**
+ * Directory holding the single source of knowledge served to AI agents.
+ *
+ * The Markdown files are shipped with the npm package (see the `files` field in
+ * package.json) so that `psq llm` works offline and always matches the version
+ * of the package that is installed. They are also what context7 crawls.
+ */
+export const LlmDocsDir = Path.resolve(__dirname, '..', 'llmdocs');
+/** Version of the installed package, used by `psq --version`. */
+export function packageVersion() {
+    const packageJsonPath = Path.resolve(__dirname, '..', 'package.json');
+    const packageJson = JSON.parse(Fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.version;
+}
+function titleOf(markdown, fallback) {
+    const heading = markdown.split(/\r?\n/).find((line) => line.startsWith('# '));
+    return heading ? heading.slice(2).trim() : fallback;
+}
+export async function loadLlmDocs(dir = LlmDocsDir) {
+    const entries = await Fsp.readdir(dir);
+    const files = entries.filter((name) => name.endsWith('.md')).sort();
+    const chapters = [];
+    for (const file of files) {
+        const content = await Fsp.readFile(Path.join(dir, file), 'utf8');
+        const name = Path.basename(file, '.md').replace(/^\d+-/, '');
+        chapters.push({ name, title: titleOf(content, name), content: content.trimEnd() });
+    }
+    return chapters;
+}
+export async function renderLlmDocs(format = 'markdown', dir) {
+    const chapters = await loadLlmDocs(dir);
+    if (format === 'json')
+        return `${JSON.stringify(chapters, null, 2)}\n`;
+    return `${chapters.map((chapter) => chapter.content).join('\n\n---\n\n')}\n`;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGxtLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2xsbS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsTUFBTSxJQUFJLENBQUE7QUFDbkIsT0FBTyxHQUFHLE1BQU0sYUFBYSxDQUFBO0FBQzdCLE9BQU8sSUFBSSxNQUFNLE1BQU0sQ0FBQTtBQUN2QixPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sS0FBSyxDQUFBO0FBRW5DLE1BQU0sVUFBVSxHQUFHLGFBQWEsQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFBO0FBQ2pELE1BQU0sU0FBUyxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQUE7QUFFMUM7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsU0FBUyxFQUFFLElBQUksRUFBRSxTQUFTLENBQUMsQ0FBQTtBQUVsRSxpRUFBaUU7QUFDakUsTUFBTSxVQUFVLGNBQWM7SUFDNUIsTUFBTSxlQUFlLEdBQUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxTQUFTLEVBQUUsSUFBSSxFQUFFLGNBQWMsQ0FBQyxDQUFBO0lBQ3JFLE1BQU0sV0FBVyxHQUFHLElBQUksQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLEVBQUUsTUFBTSxDQUFDLENBQUMsQ0FBQTtJQUN4RSxPQUFPLFdBQVcsQ0FBQyxPQUFpQixDQUFBO0FBQ3RDLENBQUM7QUFXRCxTQUFTLE9BQU8sQ0FBQyxRQUFnQixFQUFFLFFBQWdCO0lBQ2pELE1BQU0sT0FBTyxHQUFHLFFBQVEsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUE7SUFDN0UsT0FBTyxPQUFPLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQTtBQUNyRCxDQUFDO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSxXQUFXLENBQUMsTUFBYyxVQUFVO0lBQ3hELE1BQU0sT0FBTyxHQUFHLE1BQU0sR0FBRyxDQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsQ0FBQTtJQUN0QyxNQUFNLEtBQUssR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUE7SUFFbkUsTUFBTSxRQUFRLEdBQW9CLEVBQUUsQ0FBQTtJQUNwQyxLQUFLLE1BQU0sSUFBSSxJQUFJLEtBQUssRUFBRSxDQUFDO1FBQ3pCLE1BQU0sT0FBTyxHQUFHLE1BQU0sR0FBRyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxJQUFJLENBQUMsRUFBRSxNQUFNLENBQUMsQ0FBQTtRQUNoRSxNQUFNLElBQUksR0FBRyxJQUFJLENBQUMsUUFBUSxDQUFDLElBQUksRUFBRSxLQUFLLENBQUMsQ0FBQyxPQUFPLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxDQUFBO1FBQzVELFFBQVEsQ0FBQyxJQUFJLENBQUMsRUFBRSxJQUFJLEVBQUUsS0FBSyxFQUFFLE9BQU8sQ0FBQyxPQUFPLEVBQUUsSUFBSSxDQUFDLEVBQUUsT0FBTyxFQUFFLE9BQU8sQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDLENBQUE7SUFDcEYsQ0FBQztJQUVELE9BQU8sUUFBUSxDQUFBO0FBQ2pCLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLGFBQWEsQ0FBQyxTQUE4QixVQUFVLEVBQUUsR0FBWTtJQUN4RixNQUFNLFFBQVEsR0FBRyxNQUFNLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQTtJQUN2QyxJQUFJLE1BQU0sS0FBSyxNQUFNO1FBQUUsT0FBTyxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsUUFBUSxFQUFFLElBQUksRUFBRSxDQUFDLENBQUMsSUFBSSxDQUFBO0lBQ3RFLE9BQU8sR0FBRyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLGFBQWEsQ0FBQyxJQUFJLENBQUE7QUFDOUUsQ0FBQyJ9

package/llmdocs/00-guide.md

@@ -0,0 +1,124 @@
+# 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 throttling is deliberately disabled** (`--throttling.*=0`,
+   `cpuSlowdownMultiplier=1`). Timing is reproduced by the proxy, per resource.
+   Re-enabling Lighthouse throttling would apply the penalty twice.
+
+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. **Treat small deltas as noise.** Even against a fixed recording, Lighthouse
+   varies by a few points and tens of milliseconds run to run. Repeat a
+   measurement before believing a change under ~5% .
+
+## The loop
+
+```sh
+# 1. Freeze the page (writes ./inventory)
+npx psq lighthouse recording https://example.com/
+
+# 2. Keep the untouched copy
+cp -r inventory baseline
+
+# 3. Measure the baseline  → artifacts/summary.md, artifacts/lighthouse.report.html
+npx psq -i ./baseline lighthouse -a ./artifacts-baseline playback
+
+# 4. Edit ./inventory — see chapter "Experiments"
+
+# 5. Measure the edited version
+npx psq lighthouse playback
+
+# 6. Compare artifacts-baseline/summary.md with artifacts/summary.md
+```
+
+`summary.md` is a short Markdown digest (metrics, per-metric scores with their
+Lighthouse weights, traffic by resource type). It is written for exactly this
+comparison — diff the two files rather than opening two HTML reports.
+
+## 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 |
+| `inventory/contents/<METHOD>/<protocol>/<host>/<path>` | one file per recorded response body |
+| `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 |
+| 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 | repeat; do not act on deltas under ~5% |
+
+## 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. Editing the inventory is the
+  work; this reference tells you which edit models which optimization.
+- It does not replay user interaction. What is recorded is one page load.

package/llmdocs/10-inventory.md

@@ -0,0 +1,133 @@
+# 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
+└── 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, converted to UTF-8 and pretty-printed, so they are diffable and
+  editable by hand.
+
+## How a URL becomes a path
+
+`contents/<METHOD>/<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` |
+
+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.
+
+## `index.json`
+
+```json
+{
+  "entryUrl": "https://example.com/",
+  "deviceType": "mobile",
+  "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.
+
+### 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 |
+| `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 |
+| `minify` | `true` → the body is **re-minified before serving**. Set during recording when the original was minified |
+| `httpVersion` | protocol version reported for the response |
+
+### The timing model, precisely
+
+```
+response time ≈ ttfbMs  +  (bytes on the wire × 8) / (mbps × 1,000,000)
+```
+
+- `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.
+- `--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/` before the first edit.
+2. Change **one thing at a time**, then measure. Two edits in one run means you
+   cannot attribute the delta.
+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.