gipity 1.0.356 → 1.0.365

package/dist/capture/sources/claude-code.js

@@ -24,6 +24,25 @@
  * so retried POSTs are deduplicated by the partial unique index on
  * messages(conversation_id, source_uuid).
  */
+/** Pull token usage + model + stop_reason off an assistant `message` object.
+ *  Same shape in the transcript JSONL and the stream-json assistant event, so
+ *  both capture paths share this. Only includes keys that are actually present
+ *  (so they spread cleanly onto an assistant entry without writing nulls).
+ *  Cost is NOT here — it doesn't exist per-message; only the stream `result`
+ *  footer reports a session total. */
+export function usageFields(msg) {
+    const out = {};
+    const u = msg?.usage;
+    if (u && typeof u.input_tokens === 'number')
+        out.input_tokens = u.input_tokens;
+    if (u && typeof u.output_tokens === 'number')
+        out.output_tokens = u.output_tokens;
+    if (typeof msg?.model === 'string')
+        out.model = msg.model;
+    if (typeof msg?.stop_reason === 'string')
+        out.stop_reason = msg.stop_reason;
+    return out;
+}
 /** Extract joined `{type:'text', text}` blocks into a single string.
  *  The full blocks array is emitted separately so the client can render
  *  text + tool_use in the agent's original narrative order. */
@@ -37,8 +56,38 @@ function joinText(content) {
     }
     return parts.join('\n');
 }
-/** Map a single parsed transcript line to zero or more ingest entries. */
-export function transcriptLineToEntries(line) {
+/** Stamp a unique `source_uuid` on every entry parsed from one transcript line.
+ *
+ *  One transcript line yields many entries (an assistant line emits its text
+ *  entry PLUS one tool_use entry per tool call). The server dedupes ingest on
+ *  the partial unique index messages(conversation_id, source_uuid) with
+ *  ON CONFLICT DO NOTHING. If all siblings shared the bare `line.uuid`, the
+ *  first entry (the assistant text) would claim the row and every subsequent
+ *  tool_use would be silently dropped - leaving the later tool_result to land
+ *  as a name-less stub. That bug made 100% of terminal-session tool calls lose
+ *  their tool_name.
+ *
+ *  The primary entry keeps the bare line uuid (so it still dedupes against rows
+ *  written before this fix); each sibling gets a deterministic `#N` suffix.
+ *  Determinism matters: a retried POST re-parses the same line in the same
+ *  order, producing identical suffixes, so dedup still collapses retries. */
+function stampEntries(entries, lineUuid, lineTs) {
+    return entries.map((e, i) => ({
+        ...e,
+        source_uuid: i === 0 ? lineUuid : `${lineUuid}#${i}`,
+        ...(lineTs ? { ts: lineTs } : {}),
+    }));
+}
+/** Map a single parsed transcript line to zero or more ingest entries.
+ *
+ *  `toolNames` (optional) is a per-transcript `tool_use_id → tool_name`
+ *  map threaded across lines by `parseTranscript`: an assistant line
+ *  records each tool call's name into it, and the later user line that
+ *  carries the paired `tool_result` reads the name back out. This lets
+ *  the server denormalize `tool_name` onto the tool row even when the
+ *  result lands as a stub (the tool_use row missing/deduped). The
+ *  `tool_result` block itself never carries the name. */
+export function transcriptLineToEntries(line, toolNames) {
     if (!line || typeof line !== 'object')
         return [];
     if (typeof line.type !== 'string')
@@ -54,13 +103,14 @@ export function transcriptLineToEntries(line) {
     if (line.toolUseResult && !line.message)
         return [];
     const srcUuid = line.uuid;
+    const lineTs = typeof line.timestamp === 'string' ? line.timestamp : undefined;
     const msg = line.message ?? {};
     if (line.type === 'user') {
         const content = msg.content;
         if (typeof content === 'string') {
             if (!content)
                 return [];
-            return [{ kind: 'prompt', prompt: content, source_uuid: srcUuid }];
+            return stampEntries([{ kind: 'prompt', prompt: content }], srcUuid, lineTs);
         }
         if (Array.isArray(content)) {
             const out = [];
@@ -69,18 +119,18 @@ export function transcriptLineToEntries(line) {
                     out.push({
                         kind: 'tool_result',
                         tool_use_id: b.tool_use_id,
+                        tool_name: toolNames?.get(b.tool_use_id),
                         content: b.content ?? null,
                         is_error: Boolean(b.is_error),
-                        source_uuid: srcUuid,
                     });
                 }
                 else if (b?.type === 'text' && typeof b.text === 'string' && b.text) {
                     // A user message with raw text blocks (rare - first-turn preamble
                     // is sometimes split this way). Treat like a prompt.
-                    out.push({ kind: 'prompt', prompt: b.text, source_uuid: srcUuid });
+                    out.push({ kind: 'prompt', prompt: b.text });
                 }
             }
-            return out;
+            return stampEntries(out, srcUuid, lineTs);
         }
         return [];
     }
@@ -89,20 +139,21 @@ export function transcriptLineToEntries(line) {
         const text = joinText(content);
         const out = [];
         if (text || content.length) {
-            out.push({ kind: 'assistant', text, blocks: content, source_uuid: srcUuid });
+            out.push({ kind: 'assistant', text, blocks: content, ...usageFields(msg) });
         }
         for (const block of content) {
             if (block?.type === 'tool_use' && typeof block.id === 'string') {
+                const toolName = typeof block.name === 'string' ? block.name : 'tool';
+                toolNames?.set(block.id, toolName);
                 out.push({
                     kind: 'tool_use',
                     tool_use_id: block.id,
-                    tool_name: typeof block.name === 'string' ? block.name : 'tool',
+                    tool_name: toolName,
                     tool_input: block.input ?? null,
-                    source_uuid: srcUuid,
                 });
             }
         }
-        return out;
+        return stampEntries(out, srcUuid, lineTs);
     }
     // Other envelope types (system notes, hook-emitted, …) - not captured.
     return [];
@@ -120,6 +171,11 @@ export function parseTranscript(content, afterUuid) {
     let seenWatermark = afterUuid === null;
     let lastUuid = afterUuid;
     const out = [];
+    // tool_use_id → tool_name, accumulated across lines so a later
+    // tool_result can be denormalized with its tool's name. Built from the
+    // whole file (including pre-watermark lines) so a result whose tool_use
+    // was forwarded in an earlier sweep still resolves its name.
+    const toolNames = new Map();
     for (const raw of content.split('\n')) {
         const line = raw.trim();
         if (!line)
@@ -131,12 +187,21 @@ export function parseTranscript(content, afterUuid) {
         catch {
             continue;
         }
+        // Record tool names from every assistant line we scan, even before the
+        // watermark - the map is read-only side state, it doesn't emit entries.
         if (!seenWatermark) {
+            if (Array.isArray(parsed?.message?.content)) {
+                for (const block of parsed.message.content) {
+                    if (block?.type === 'tool_use' && typeof block.id === 'string') {
+                        toolNames.set(block.id, typeof block.name === 'string' ? block.name : 'tool');
+                    }
+                }
+            }
             if (parsed?.uuid === afterUuid)
                 seenWatermark = true;
             continue;
         }
-        const entries = transcriptLineToEntries(parsed);
+        const entries = transcriptLineToEntries(parsed, toolNames);
         if (entries.length) {
             for (const e of entries)
                 out.push(e);

package/dist/commands/add.js

@@ -7,35 +7,38 @@ import { requireConfig } from '../config.js';
 import { sync } from '../sync.js';
 import { success, muted, bold } from '../colors.js';
 import { run } from '../helpers/index.js';
-// Catalog mirrored from platform/packages/shared (TEMPLATES + KITS) -
-// the CLI ships as a standalone npm package and can't depend on the private
-// shared workspace. Keep these lists in sync when catalog entries change.
-//
-// Templates install a whole app (blank wiring or a working starter demo).
-// Kits are reusable building blocks added into an existing app's src/packages/.
-const TEMPLATES = ['web-simple', '3d-engine'];
-const STARTERS = ['web-fullstack', 'web-vision-cam', '2d-game', '3d-world', 'api'];
+const STARTERS = [
+    { key: 'web-fullstack', hint: 'backend API + database (weather-by-zip demo)' },
+    { key: 'web-vision-cam', hint: 'fullscreen camera app with on-device vision (MediaPipe)' },
+    { key: '2d-game', hint: '2D games with Phaser 3 - platformer, arcade, puzzle' },
+    { key: '3d-world', hint: 'playable 3D multiplayer rocket-launcher demo' },
+    { key: 'api', hint: 'pure API backend, no frontend' },
+];
+const BLANK = [
+    { key: 'web-simple', hint: 'static frontend-only site - pages, dashboards, simple games' },
+    { key: '3d-engine', hint: '3D multiplayer wiring - Three.js + Rapier + Gipity Realtime' },
+];
 const HIDDEN = [{ key: 'app-itsm', hint: 'IT service management / helpdesk / ticketing' }];
 const KITS = [
     { key: 'realtime', hint: 'multiplayer / presence / shared state' },
     { key: 'web-vision-mediapipe', hint: 'browser camera vision - gesture, pose, object detection' },
+    { key: 'i18n', hint: 'multi-language web apps - language picker, RTL, translations' },
 ];
-function printCatalog() {
-    console.log('');
-    console.log(`${bold('Templates')}  ${muted('- install a whole app into an empty project')}`);
-    console.log(`  ${TEMPLATES.join(', ')}  ${muted('(blank wiring)')}`);
-    console.log(`  ${STARTERS.join(', ')}  ${muted('(working demos)')}`);
-    console.log('');
-    console.log(`${bold('Kits')}  ${muted('- add a reusable building block into an existing app')}`);
-    for (const k of KITS)
-        console.log(`  ${k.key}  ${muted('- ' + k.hint)}`);
-    console.log('');
-    console.log(`${bold('Local path')}  ${muted('- install from a directory on disk (template or kit)')}`);
-    console.log(`  ${muted('gipity add ./path/to/template  (or ~/path, /abs/path)')}`);
-    console.log(`  ${muted('gipity add ./path/to/kit       (auto-detected via package.json gipity.install)')}`);
-    console.log('');
-    console.log(muted('Usage: gipity add <name|path> [--title <t>] [--description <d>] [--force]'));
-    console.log('');
+// The catalog block, rendered once and reused by the full help output
+// (`gipity add` / `gipity add --help`) and the bare listing (`gipity add
+// --list`) so they can never drift. Three sections, one entry per line, keys
+// column-aligned. No leading/trailing blank lines - callers add surrounding
+// whitespace.
+function catalogText() {
+    const width = Math.max(...[...STARTERS, ...BLANK, ...KITS].map(e => e.key.length));
+    const row = (e) => `  ${e.key.padEnd(width)}  ${muted(e.hint)}`;
+    const section = (title, blurb, entries) => [`${bold(title)}  ${muted('- ' + blurb)}`, ...entries.map(row)].join('\n');
+    return [
+        'Names to pass to `gipity add <name>`:',
+        section('Templates (working demos)', 'complete apps to run, then extend or replace', STARTERS),
+        section('Templates (blank wiring)', 'minimal framework setup - build your app on top', BLANK),
+        section('Kits', 'building blocks to add into an app you already scaffolded', KITS),
+    ].join('\n\n');
 }
 // ─── Local-path payload mode ────────────────────────────────────────────────
 //
@@ -136,14 +139,28 @@ function buildLocalPayload(rootDir) {
 }
 export const addCommand = new Command('add')
     .description('Add a template (scaffold an app) or a kit (reusable building block) to the project. Pass ./path/to/dir to install a local template directly.')
-    .argument('[name]', 'Template/kit key, OR a local directory path (./, ~/, or /abs). Omit to list the catalog.')
+    .argument('[name]', 'Template/kit key, OR a local directory path (./, ~/, or /abs). Omit for help; use --list for just the catalog.')
     .option('--title <title>', 'App title - templates only (defaults to project name)')
     .option('--description <desc>', 'App description for meta tags - templates only')
     .option('--force', 'Templates only: overwrite any colliding files')
+    .option('--list', 'List the template/kit catalog and exit')
     .option('--json', 'Output as JSON')
-    .action((name, opts) => run('Add', async () => {
+    .addHelpText('after', () => catalogText() + '\n\n'
+    + muted('Local path  gipity add ./dir  (or ~/path, /abs) - template or kit, auto-detected'))
+    .action((name, opts, command) => run('Add', async () => {
+    // `--list` is a bare catalog dump; no project/config needed.
+    if (opts.list) {
+        if (opts.json) {
+            console.log(JSON.stringify({ templates: { starters: STARTERS, blank: BLANK }, kits: KITS }));
+        }
+        else {
+            console.log('\n' + catalogText() + '\n');
+        }
+        return;
+    }
+    // No name = show the full help (usage + options + catalog), same as --help.
     if (!name) {
-        printCatalog();
+        command.outputHelp();
         return;
     }
     const config = requireConfig();

package/dist/commands/generate.js

@@ -2,15 +2,18 @@ import { Command } from 'commander';
 import { post } from '../api.js';
 import { resolveProjectContext } from '../config.js';
 import { writeFileSync } from 'fs';
+import { resolve as resolvePath } from 'path';
 import { error as clrError, success, muted, info } from '../colors.js';
 import { IMAGE_MODELS_DOC, IMAGE_GEMINI_ASPECT_RATIOS, IMAGE_GEMINI_SIZES, VIDEO_MODELS_DOC, TTS_PROVIDER_DESCRIPTIONS } from '../provider-docs.js';
-/** Download a URL and save to a local file */
+/** Download a URL and save to a local file. Returns the absolute path written,
+ *  so callers can report exactly where the file landed. */
 async function downloadFile(url, filename) {
     const res = await fetch(url);
     if (!res.ok)
         throw new Error(`Download failed: ${res.status}`);
     const buffer = Buffer.from(await res.arrayBuffer());
     writeFileSync(filename, buffer);
+    return resolvePath(filename);
 }
 // ── IMAGE ──────────────────────────────────────────────────────────────
 const imageCommand = new Command('image')
@@ -34,7 +37,7 @@ Examples:
     .option('--quality <quality>', 'Quality: low|medium|high|auto (gpt-image-1), standard|hd (dall-e-3)')
     .option('--aspect-ratio <ratio>', 'Aspect ratio (Gemini only): 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9')
     .option('--image-size <size>', 'Output resolution (Gemini only): 512, 1K, 2K, 4K')
-    .option('-o, --output <file>', 'Output filename (default: generated.png)')
+    .option('-o, --output <file>', 'Output path (default ./generated.png). For an image your app ships, write it into the source tree so it deploys, e.g. -o src/assets/images/hero.png; the cwd default is fine for one-off generation.')
     .option('--json', 'Output as JSON')
     .action(async (prompt, opts) => {
     try {
@@ -50,14 +53,14 @@ Examples:
         });
         const ext = result.content_type.includes('png') ? 'png' : 'jpg';
         const filename = opts.output || `generated.${ext}`;
-        await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename);
         if (opts.json) {
-            console.log(JSON.stringify({ ...result, saved: filename }));
+            console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
         else {
             const sizeKb = Math.round(result.size_bytes / 1024);
             console.log(`${muted(`Generated with ${result.provider}/${result.model} (${sizeKb}KB)`)}`);
-            console.log(success(`Saved to ${filename}`));
+            console.log(success(`Saved to ${savedPath}`));
         }
     }
     catch (err) {
@@ -88,7 +91,7 @@ Examples:
     .option('--model <model>', 'Veo model: veo-3.1-generate-preview (quality), veo-3.1-fast-generate-preview (speed), veo-3.1-lite-generate-preview (budget)')
     .option('--aspect <ratio>', 'Aspect ratio: 16:9 (landscape), 9:16 (portrait), 1:1 (square)')
     .option('--resolution <res>', 'Video resolution: 720p, 1080p, 4k')
-    .option('-o, --output <file>', 'Output filename (default: generated.mp4)')
+    .option('-o, --output <file>', 'Output path (default ./generated.mp4). For a clip your app ships, write it into the source tree so it deploys, e.g. -o src/assets/video/clip.mp4; the cwd default is fine for one-off generation.')
     .option('--json', 'Output as JSON')
     .action(async (prompt, opts) => {
     try {
@@ -101,14 +104,14 @@ Examples:
             resolution: opts.resolution,
         });
         const filename = opts.output || 'generated.mp4';
-        await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename);
         if (opts.json) {
-            console.log(JSON.stringify({ ...result, saved: filename }));
+            console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
         else {
             const sizeKb = Math.round(result.size_bytes / 1024);
             console.log(`${muted(`Generated with ${result.provider}/${result.model} (${sizeKb}KB)`)}`);
-            console.log(success(`Saved to ${filename}`));
+            console.log(success(`Saved to ${savedPath}`));
         }
     }
     catch (err) {
@@ -137,7 +140,7 @@ Examples:
     .option('--voice <voice>', 'Voice ID or name (provider-specific)')
     .option('--language <code>', 'BCP-47 language code, e.g. ja-JP, es-ES (Gemini only, 60+ languages)')
     .option('--speakers <json>', 'Multi-speaker config as JSON array (Gemini only, up to 2 speakers)')
-    .option('-o, --output <file>', 'Output filename (default: speech.mp3)')
+    .option('-o, --output <file>', 'Output path (default ./speech.mp3). For audio your app ships, write it into the source tree so it deploys, e.g. -o src/assets/sounds/intro.mp3; the cwd default is fine for one-off generation.')
     .option('--json', 'Output as JSON')
     .action(async (text, opts) => {
     try {
@@ -160,14 +163,14 @@ Examples:
             speakers,
         });
         const filename = opts.output || 'speech.mp3';
-        await downloadFile(result.url, filename);
+        const savedPath = await downloadFile(result.url, filename);
         if (opts.json) {
-            console.log(JSON.stringify({ ...result, saved: filename }));
+            console.log(JSON.stringify({ ...result, saved: savedPath }));
         }
         else {
             const sizeKb = Math.round(result.size_bytes / 1024);
             console.log(`${muted(`Generated with ${result.provider} (${sizeKb}KB)`)}`);
-            console.log(success(`Saved to ${filename}`));
+            console.log(success(`Saved to ${savedPath}`));
         }
     }
     catch (err) {

package/dist/commands/page-eval.js

@@ -1,7 +1,38 @@
 import { Command } from 'commander';
-import { post } from '../api.js';
+import { post, get, ApiError } from '../api.js';
 import { brand, bold, muted } from '../colors.js';
 import { run } from '../helpers/index.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Poll the async eval job until it finishes. Eval runs server-side as a
+ *  short-lived job (so a long --wait can't trip the gateway idle timeout);
+ *  we submit, then poll the result out of the job store. */
+async function pollEvalResult(evalJobId, waitMs) {
+    // Generous client budget: the server work is bounded by --wait plus browser
+    // open/settle overhead; give it that plus headroom before giving up.
+    const deadline = Date.now() + waitMs + 60_000;
+    let missCount = 0;
+    while (Date.now() < deadline) {
+        let rec;
+        try {
+            rec = (await get(`/tools/browser/eval/${evalJobId}`)).data;
+        }
+        catch (err) {
+            // A 404 right after submit can happen if the record hasn't landed yet;
+            // tolerate a few, then treat a persistent 404 as the job being gone.
+            if (err instanceof ApiError && err.statusCode === 404 && missCount++ < 3) {
+                await sleep(500);
+                continue;
+            }
+            throw err;
+        }
+        if (rec.status === 'done')
+            return rec;
+        if (rec.status === 'error')
+            throw new ApiError(rec.httpStatus, rec.code, rec.reason);
+        await sleep(1000);
+    }
+    throw new ApiError(504, 'EVAL_TIMEOUT', 'Eval did not finish in time; narrow the expression or lower --wait');
+}
 // The long-tail escape hatch alongside `page inspect`'s fixed bundle: when the
 // curated metrics don't cover what you need (computed styles, element rects,
 // visibility, z-index stacks), eval an expression in page context and get the
@@ -11,12 +42,20 @@ export const pageEvalCommand = new Command('eval')
     .argument('<url>', 'URL to load')
     .argument('<expr>', 'JavaScript expression to evaluate in page context (result is JSON-serialized)')
     .option('--wait <ms>', 'Sleep this many ms after DOMContentLoaded before evaluating (lets late async work settle)', '500')
+    .option('--wait-for <selector>', 'Wait until this CSS selector appears before evaluating (deterministic; replaces --wait)')
+    .option('--wait-timeout <ms>', 'Max ms to wait for --wait-for before giving up', '5000')
     .option('--json', 'Output as JSON')
     .action((url, expr, opts) => run('Page eval', async () => {
     const parsedWait = parseInt(opts.wait, 10);
     const waitMs = Number.isFinite(parsedWait) && parsedWait >= 0 ? parsedWait : 500;
-    const res = await post('/tools/browser/eval', { url, expr, waitMs });
-    const d = res.data;
+    const parsedTimeout = parseInt(opts.waitTimeout, 10);
+    const waitForTimeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout >= 0 ? parsedTimeout : 5000;
+    const kickoff = await post('/tools/browser/eval', {
+        url, expr, waitMs,
+        waitForSelector: opts.waitFor || undefined,
+        waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
+    });
+    const d = await pollEvalResult(kickoff.data.evalJobId, waitMs);
     if (opts.json) {
         console.log(JSON.stringify(d));
         return;

package/dist/commands/page-inspect.js

@@ -23,9 +23,12 @@ export const pageInspectCommand = new Command('inspect')
     .description('Inspect a web page (console, failed resources, timing, layout overflow)')
     .argument('<url>', 'URL to inspect')
     .option('--wait <ms>', 'Sleep this many ms after DOMContentLoaded before capturing (lets late async/LCP work settle)', '500')
+    .option('--wait-for <selector>', 'Wait until this CSS selector appears before capturing (deterministic; replaces --wait)')
+    .option('--wait-timeout <ms>', 'Max ms to wait for --wait-for before giving up', '5000')
     .option('--json', 'Output as JSON')
     .option('--no-truncate', 'Show full URLs instead of truncating long ones with middle-ellipsis')
     .option('--all', 'Include render-blocking, large resources, oversized images, overflow culprits, and LCP detail')
+    .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps run headlessly (audio is a built-in tone, not real speech)')
     // Hidden redirect: agents reach for `page inspect --screenshot`. We don't take
     // an image here (`page screenshot` is the single path for that) — just point there.
     .addOption(new Option('--screenshot [path]', 'Capture a screenshot').hideHelp())
@@ -38,9 +41,16 @@ export const pageInspectCommand = new Command('inspect')
     return run('Page inspect', async () => {
         const parsedWait = parseInt(opts.wait, 10);
         const waitMs = Number.isFinite(parsedWait) && parsedWait >= 0 ? parsedWait : 500;
+        const parsedTimeout = parseInt(opts.waitTimeout, 10);
+        const waitForTimeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout >= 0 ? parsedTimeout : 5000;
         const truncate = opts.truncate !== false;
         const showAll = opts.all === true;
-        const res = await post(`/tools/browser/inspect`, { url, waitMs });
+        const res = await post(`/tools/browser/inspect`, {
+            url, waitMs,
+            waitForSelector: opts.waitFor || undefined,
+            waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
+            fakeMedia: opts.fakeMedia || undefined,
+        });
         const b = res.data;
         if (opts.json) {
             console.log(JSON.stringify(b));
@@ -71,12 +81,30 @@ export const pageInspectCommand = new Command('inspect')
             console.log(`\n  ${bold('Console:')} ${muted('(clean)')}`);
         }
         // ── Failed Resources ──
-        if (b.failedResources?.length > 0) {
-            console.log(`\n  ${clrError(`Failed resources (${b.failedResources.length}):`)}`);
-            for (const r of b.failedResources) {
+        // Browsers auto-request /favicon.ico at the site root for every page, so a
+        // 404 there isn't a resource the page actually links — it's noise on any
+        // app served under a subpath. Split that implicit request out of the failure
+        // list into a harmless note rather than flagging it as an error.
+        const isImplicitFavicon = (entry) => {
+            const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
+            try {
+                return new URL(urlPart).pathname === '/favicon.ico';
+            }
+            catch {
+                return false;
+            }
+        };
+        const failed = (b.failedResources || []).filter((r) => !isImplicitFavicon(r));
+        const rootFaviconMissing = (b.failedResources || []).some(isImplicitFavicon);
+        if (failed.length > 0) {
+            console.log(`\n  ${clrError(`Failed resources (${failed.length}):`)}`);
+            for (const r of failed) {
                 console.log(`    ${clrError(r)}`);
             }
         }
+        if (rootFaviconMissing) {
+            console.log(`\n  ${muted('No root /favicon.ico (browsers request this automatically; harmless for app pages served under a subpath)')}`);
+        }
         // ── Layout (horizontal overflow) ──
         if (b.overflow) {
             if (b.overflow.overflowX) {

package/dist/commands/page-screenshot.js

@@ -1,6 +1,8 @@
 import { Command, Option } from 'commander';
-import { existsSync, readdirSync, writeFileSync } from 'fs';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join, resolve as resolvePath } from 'path';
 import { postForTarEntries } from '../api.js';
+import { getProjectRoot } from '../config.js';
 import { brand, bold, muted, success } from '../colors.js';
 import { formatSize } from '../utils.js';
 import { run } from '../helpers/index.js';
@@ -44,23 +46,23 @@ function dimSuffix(vp) {
     const dpr = vp.deviceScaleFactor ?? 1;
     return dpr === 1 ? `${vp.width}x${vp.height}` : `${vp.width}x${vp.height}@${dpr}`;
 }
-function nextNumberedFilename(slug, suffix) {
-    const prefix = suffix ? `ss-${slug}-${suffix}-` : `ss-${slug}-`;
-    const escaped = prefix.replace(/[-.@]/g, '\\$&');
-    const existing = readdirSync('.')
-        .map((f) => {
-        const m = f.match(new RegExp(`^${escaped}(\\d{3,})\\.png$`));
-        return m ? parseInt(m[1], 10) : -1;
-    })
-        .filter((n) => n >= 0);
-    const next = existing.length ? Math.max(...existing) + 1 : 1;
-    let n = next;
-    let candidate = `${prefix}${String(n).padStart(3, '0')}.png`;
-    while (existsSync(candidate)) {
-        n += 1;
-        candidate = `${prefix}${String(n).padStart(3, '0')}.png`;
-    }
-    return candidate;
+/** Default screenshot directory: `<project-root>/.gipity/screenshots`, falling
+ *  back to `./.gipity/screenshots` in one-off mode (no linked project). `.gipity/`
+ *  is sync-ignored, so these verification artifacts never sync to Gipity or
+ *  deploy to the CDN - and they stay out of the project root. */
+function defaultScreenshotDir() {
+    const root = getProjectRoot();
+    return join(root ?? '.', '.gipity', 'screenshots');
+}
+/** `yyyy-mm-dd_hh-mm-ss` per the repo timestamp convention - sorts chronologically,
+ *  filesystem-safe. One stamp per invocation; viewport suffixes keep multi-shot
+ *  runs distinct so they never collide on the shared timestamp. */
+export function timestampSlug(d = new Date()) {
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}_${p(d.getHours())}-${p(d.getMinutes())}-${p(d.getSeconds())}`;
+}
+export function defaultFilename(slug, ts, suffix) {
+    return suffix ? `ss-${slug}-${suffix}-${ts}.png` : `ss-${slug}-${ts}.png`;
 }
 function parseViewportString(s) {
     const m = s.trim().match(/^(\d+)x(\d+)(?:@(\d+(?:\.\d+)?))?$/i);
@@ -96,10 +98,11 @@ export const pageScreenshotCommand = new Command('screenshot')
     .argument('<url>', 'URL to screenshot')
     .option('--post-load-delay <ms>', 'Delay after DOMContentLoaded before capture, in ms', '1000')
     .option('--full', 'Capture the full scrollable page (default: viewport only)')
-    .option('-o, --output <file>', 'Output filename (single viewport only; default ss-<host>-NNN.png)')
+    .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
     .option('--device <names>', `Viewport preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag)`, appendOption, [])
     .option('--viewport <dims>', 'Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag)', appendOption, [])
     .option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
+    .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly (audio is a built-in tone, not real speech)')
     .option('--json', 'Output JSON metadata instead of a friendly summary')
     .addOption(new Option('--wait <ms>', 'Alias for --post-load-delay').hideHelp())
     .action((url, opts) => run('Page screenshot', async () => {
@@ -118,7 +121,7 @@ export const pageScreenshotCommand = new Command('screenshot')
         throw new Error('--output can only be used with a single viewport');
     }
     // Server defaults to 1280×720 when viewports is omitted - don't send it in
-    // the no-flag case so filename stays unsuffixed (`ss-host-NNN.png`).
+    // the no-flag case so the filename stays unsuffixed (no viewport segment).
     const userSpecifiedViewports = customViewports.length > 0;
     const body = {
         url,
@@ -126,6 +129,7 @@ export const pageScreenshotCommand = new Command('screenshot')
         full: !!opts.full,
         reloadBetween: opts.reloadBetween !== false,
         ...(userSpecifiedViewports ? { viewports: customViewports } : {}),
+        ...(opts.fakeMedia ? { fakeMedia: true } : {}),
     };
     const entries = await postForTarEntries('/tools/browser/screenshot', body);
     const metaEntry = entries.find((e) => e.name === 'meta.json');
@@ -137,13 +141,20 @@ export const pageScreenshotCommand = new Command('screenshot')
         throw new Error(`Server returned ${pngs.length} PNGs but ${meta.screenshots.length} metadata entries`);
     }
     const slug = slugFromUrl(url);
+    const ts = timestampSlug();
+    const dir = defaultScreenshotDir();
+    if (!opts.output)
+        mkdirSync(dir, { recursive: true });
     const savedFiles = [];
     for (let i = 0; i < pngs.length; i++) {
         const shot = meta.screenshots[i];
         const suffix = userSpecifiedViewports ? dimSuffix(shot.viewport) : undefined;
-        const filename = opts.output || nextNumberedFilename(slug, suffix);
-        writeFileSync(filename, pngs[i].buffer);
-        savedFiles.push(filename);
+        const target = opts.output
+            ? opts.output
+            : join(dir, defaultFilename(slug, ts, suffix));
+        writeFileSync(target, pngs[i].buffer);
+        // Absolute path so the agent knows exactly where the file landed.
+        savedFiles.push(resolvePath(target));
     }
     if (opts.json) {
         console.log(JSON.stringify({