gipity 1.0.425 → 1.0.427

package/dist/banner.js

@@ -52,12 +52,12 @@ const INFRASTRUCTURE = [
     'Compute', 'CDN', 'Storage', 'Inference', 'Hosting',
     'Deploy', 'Uploads', 'Rollback',
 ];
-// ── Egg color palette (shared) - gradient built around #FEA60E ───────
+// ── Egg color palette (shared) - gradient built around #FEA60B ───────
 // Colors route through fg() so they downgrade (256 / 16 / none) on terminals
 // without truecolor support instead of rendering as misparsed garbage.
 const _hi = fg(255, 215, 80); // golden highlight
 const _lt = fg(254, 190, 45); // light
-const _br = fg(254, 166, 14); // base - #FEA60E
+const _br = fg(254, 166, 11); // base - #FEA60B
 const _md = fg(218, 112, 8); // medium-dark
 const _sh = fg(170, 68, 4); // shadow
 // Wobbly egg - asymmetric left/right, organic feel (8 rows)

package/dist/bug-queue.js

@@ -0,0 +1,77 @@
+/**
+ * Local queue for `gipity bug report` submissions that couldn't be delivered
+ * immediately (no network, session expired, server hiccup). The report is
+ * the one artifact that must survive the platform being the thing that's
+ * broken - a bug report failing to file because the session that just broke
+ * is also required to file it would silently lose the report. Queued entries
+ * are flushed opportunistically wherever there's a good "we're reconnected"
+ * signal: the next successful login, the top of the next `bug report`
+ * invocation, and `gipity status` when it finds a valid, unexpired session.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { post } from './api.js';
+const QUEUE_DIR = join(process.env.GIPITY_DIR || join(homedir(), '.gipity'), 'bug-queue');
+/** Persist a report that failed to submit so it survives to the next attempt. */
+export function queueBugReport(report) {
+    mkdirSync(QUEUE_DIR, { recursive: true, mode: 0o700 });
+    const file = join(QUEUE_DIR, `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+    writeFileSync(file, JSON.stringify(report, null, 2), { mode: 0o600 });
+}
+/** True when a submit failure is worth queuing for later delivery: the
+ *  network was unreachable, the request timed out, the session/token was
+ *  rejected, or the server had a transient failure. A validation error
+ *  (bad category, missing field) would fail identically on retry, so those
+ *  surface immediately instead of queuing silently forever. */
+export function isRetryableFailure(err) {
+    if (err?.name === 'ApiError') {
+        return err.statusCode === 401 || err.statusCode === 408 || err.statusCode >= 500;
+    }
+    // fetch()-level network errors and the "Not authenticated" pre-check both
+    // have no statusCode - both mean "can't reach/use the platform right now".
+    return typeof err?.statusCode !== 'number';
+}
+/** Best-effort delivery of every queued report. Never throws - called
+ *  opportunistically and a flush failure must not block the caller's actual
+ *  command. Returns the count successfully delivered. */
+export async function flushBugQueue() {
+    if (!existsSync(QUEUE_DIR))
+        return 0;
+    let delivered = 0;
+    for (const file of readdirSync(QUEUE_DIR)) {
+        if (!file.endsWith('.json'))
+            continue;
+        const path = join(QUEUE_DIR, file);
+        let report;
+        try {
+            report = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            try {
+                unlinkSync(path);
+            }
+            catch { /* already gone */ }
+            continue; // corrupt entry - retrying it can never succeed
+        }
+        try {
+            await post(`/api/${report.projectGuid}/services/bug-report/submit`, {
+                category: report.category,
+                severity: report.severity,
+                summary: report.summary,
+                detail: report.detail,
+            });
+            unlinkSync(path);
+            delivered++;
+        }
+        catch {
+            // Still undeliverable - leave it queued for the next attempt. A queued
+            // report was only ever retryable at queue time (isRetryableFailure gates
+            // queuing); if the server later hard-rejects it permanently (e.g. the
+            // project was deleted), it sticks and retries forever. Accepted given
+            // bug-report volume is tiny - better than silently dropping it.
+        }
+    }
+    return delivered;
+}
+//# sourceMappingURL=bug-queue.js.map

package/dist/colors.js

@@ -145,7 +145,7 @@ export const underline = makeStyle(4, 24);
 // ── Gipity platform palette ────────────────────────────────────────────
 // Colors sourced from platform/client/src/css/styles.css and
 // platform/apps/gipitsm/src/css/tokens.css
-export const brand = makeFg(254, 166, 14, bold); // Gipity orange #fea60e (→ bold on 16-color; no orange in palette)
+export const brand = makeFg(254, 166, 11, bold); // Gipity orange #fea60b (→ bold on 16-color; no orange in palette)
 export const error = makeFg(239, 68, 68); // #ef4444
 export const warning = makeFg(245, 158, 11); // #f59e0b
 export const success = makeFg(34, 197, 94); // #22c55e
@@ -156,7 +156,7 @@ export const faint = makeFg(111, 111, 120); // #6f6f78
 export const accent = makeFg(178, 186, 250); // Light blue-purple
 export const cyan = makeFg(9, 146, 179); // Teal
 // ── Background variants ────────────────────────────────────────────────
-export const bgBrand = makeBg(242, 101, 34);
+export const bgBrand = makeBg(254, 166, 11);
 export const bgError = makeBg(239, 68, 68);
 export const bgSuccess = makeBg(34, 197, 94);
 // ── Convenience combinators ────────────────────────────────────────────

package/dist/commands/add.js

@@ -209,8 +209,13 @@ export const addCommand = new Command('add')
     // The spinner is TTY-only, so piped/agent transcripts would otherwise show
     // a silent multi-second gap (favicon generation on a cold cache can take
     // ~10s, cli#117) - leave one stderr marker so the wait reads as work.
+    // Favicons are generated for templates only, so don't claim them on a kit
+    // install (kits are quick; the slow first-add path is template scaffolding).
     if (!opts.json && !process.stdout.isTTY) {
-        console.error(muted('Installing (server writes files + generates favicons; first add for a title can take ~10s)...'));
+        const isKit = KITS.some(k => k.key === name);
+        console.error(muted(isKit
+            ? 'Installing kit (server-side install pipeline)...'
+            : 'Installing (server writes files + generates favicons; first add for a title can take ~10s)...'));
     }
     const doAdd = () => post(`/projects/${config.projectGuid}/add`, body);
     const res = opts.json

package/dist/commands/bug.js

@@ -3,6 +3,7 @@ import { get, post } from '../api.js';
 import { resolveProjectContext } from '../config.js';
 import { bold, muted, success, warning } from '../colors.js';
 import { run } from '../helpers/index.js';
+import { flushBugQueue, isRetryableFailure, queueBugReport } from '../bug-queue.js';
 // Kept in sync with @easyclaw/shared BUG_REPORT_CATEGORIES / _SEVERITIES (the CLI
 // package can't import the server's shared package). The server validates
 // authoritatively; these are for --help and a friendly client-side check.
@@ -38,12 +39,34 @@ bugCommand
         throw new Error('--summary must be 7 words or fewer');
     }
     const { config } = await resolveProjectContext({ projectOverride: opts.project });
-    const res = await post(`/api/${config.projectGuid}/services/bug-report/submit`, { category, severity, summary: opts.summary, detail: opts.detail });
-    if (opts.json) {
-        console.log(JSON.stringify(res.data));
-        return;
+    // Best-effort: deliver anything stranded by an earlier outage/session-expiry
+    // before filing the new one, so a single working connection clears the backlog.
+    const delivered = await flushBugQueue().catch(() => 0);
+    if (delivered > 0 && !opts.json) {
+        console.log(muted(`Delivered ${delivered} previously queued bug report${delivered === 1 ? '' : 's'}.`));
+    }
+    const payload = { category, severity, summary: opts.summary, detail: opts.detail };
+    try {
+        const res = await post(`/api/${config.projectGuid}/services/bug-report/submit`, payload);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data));
+            return;
+        }
+        console.log(success(`✓ Bug report filed (${res.data.report_guid}) — queued for triage.`));
+    }
+    catch (err) {
+        // The report itself is the record of "the platform broke" - don't lose it
+        // just because the breakage (dead session, no network) also blocks filing it.
+        if (!isRetryableFailure(err))
+            throw err;
+        queueBugReport({ projectGuid: config.projectGuid, ...payload });
+        if (opts.json) {
+            console.log(JSON.stringify({ queued: true }));
+            return;
+        }
+        console.log(warning('Bug report saved locally - no connection or session expired.'));
+        console.log(muted('It will be delivered automatically next time you log in or file another report.'));
     }
-    console.log(success(`✓ Bug report filed (${res.data.report_guid}) — queued for triage.`));
 }));
 bugCommand
     .command('retract <id>')

package/dist/commands/claude.js

@@ -71,7 +71,7 @@ import { getProjectsRoot } from '../relay/paths.js';
  *
  *  Returns a best-effort local fallback if the API call fails (offline,
  *  auth missing, etc.) so the prompt still builds. */
-async function fetchProjectStats(projectGuid, cwd) {
+export async function fetchProjectStats(projectGuid, cwd) {
     if (projectGuid) {
         try {
             const res = await get(`/projects/${encodeURIComponent(projectGuid)}/files/stats`);

package/dist/commands/credits.js

@@ -133,6 +133,7 @@ export const creditsCommand = new Command('credits')
     }
     else {
         console.log(dim('Need more credits? Run `gipity credits list` to see credit packs, then `gipity credits buy <pack>`.'));
+        console.log(dim('Manage or cancel your subscription with `gipity credits manage`.'));
     }
 }));
 // `credits list` compares every plan (with full limits) and the available
@@ -289,6 +290,51 @@ creditsCommand
         throw err;
     }
 }));
+// `credits manage` is the ONE manage/cancel command: it mints a Stripe
+// Customer Portal link (cancel at period end, renew, update card, invoices).
+// Like `buy`, the link is always printed so an agent can relay it; --open
+// also launches a browser. Falls back to the pricing page on error.
+creditsCommand
+    .command('manage')
+    .alias('cancel')
+    .description('Manage or cancel your subscription (opens the Stripe billing portal)')
+    .option('--open', 'Open the billing portal in your browser')
+    .option('--json', 'Output the portal URL as JSON')
+    // optsWithGlobals(): the parent `credits` command also declares --json, which
+    // commander binds to the parent - read merged opts so --json/--open are seen here.
+    .action((_opts, cmd) => run('Manage', async () => {
+    const opts = cmd.optsWithGlobals();
+    try {
+        const res = await post('/credits/portal', {});
+        const url = res.data.portalUrl;
+        if (opts.json) {
+            console.log(JSON.stringify({ portalUrl: url }));
+            return;
+        }
+        console.log(`  ${bold('Billing portal:')} ${success(url)}`);
+        console.log('');
+        console.log(dim('Open the link to cancel, renew, update your card, or view invoices. Cancelling takes effect at the end of the billing period — you keep your credits.'));
+        if (opts.open)
+            openInBrowser(url);
+    }
+    catch (err) {
+        // No billing account / payments not configured: point at the pricing page
+        // so the user is never dead-ended.
+        if (err instanceof ApiError) {
+            if (opts.json) {
+                console.log(JSON.stringify({ error: err.message, portalUrl: null, fallbackUrl: PRICING_URL }));
+            }
+            else {
+                console.log(muted(`Couldn't open the billing portal (${err.message}).`));
+                console.log(`Manage your plan at ${brand(PRICING_URL)}`);
+            }
+            if (opts.open)
+                openInBrowser(PRICING_URL);
+            return;
+        }
+        throw err;
+    }
+}));
 creditsCommand
     .command('usage')
     .description('Show recent usage')

package/dist/commands/doctor.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
+import { homedir } from 'os';
 import { LOCAL_PKG_DIR, LOCAL_ENTRY, STATE_FILE, SETTINGS_FILE, UPDATE_LOG, readState, readSettings, updatesDisabled } from '../updater/state.js';
 import { bold, dim, success, warning, error as clrError, muted } from '../colors.js';
 import { getAuth, sessionExpired } from '../auth.js';
@@ -9,6 +10,36 @@ import * as relayState from '../relay/state.js';
 import { planFor, UnsupportedPlatformError } from '../relay/installers.js';
 import { resolveCliPath } from '../relay/setup.js';
 const NODE_MIN_MAJOR = 18;
+/**
+ * If the `node` running this CLI lives under a version-manager install tree
+ * (nvm/fnm/asdf/volta), return the manager's name; otherwise null.
+ *
+ * Why it matters: `npm install -g gipity` drops the `gipity` binary in the
+ * *active node version's* bin dir. With a lazily-activated manager (nvm's
+ * default setup), that dir isn't on a fresh shell's PATH until the manager
+ * initializes, so a new terminal reports `gipity: command not found` and users
+ * think the install failed. (Plugin hooks used to break the same way; the
+ * plugin's sh launcher now resolves node itself, so this is only about the
+ * `gipity` binary's own discoverability.) `gipity doctor` surfaces it with a
+ * remediation instead of leaving it a mystery.
+ */
+export function versionManagerNode(execPath, env = process.env, home = homedir()) {
+    const norm = (s) => s.replace(/\\/g, '/').replace(/\/+$/, '') + '/';
+    const p = norm(execPath);
+    const h = norm(home);
+    const roots = [
+        ['nvm', env.NVM_DIR ? norm(env.NVM_DIR) : `${h}.nvm/`],
+        ['fnm', env.FNM_DIR ? norm(env.FNM_DIR) : `${h}.fnm/`],
+        ['fnm', `${h}.local/share/fnm/`],
+        ['asdf', env.ASDF_DIR ? norm(env.ASDF_DIR) : `${h}.asdf/`],
+        ['volta', env.VOLTA_HOME ? norm(env.VOLTA_HOME) : `${h}.volta/`],
+    ];
+    for (const [name, root] of roots) {
+        if (p.startsWith(root))
+            return name;
+    }
+    return null;
+}
 function localVersion() {
     const pkgPath = join(LOCAL_PKG_DIR, 'package.json');
     if (!existsSync(pkgPath))
@@ -68,7 +99,11 @@ export function gatherEnv(opts = {}) {
     const auth = getAuth();
     const expired = auth ? sessionExpired() : false;
     const device = relayState.getDevice();
-    const node = { ok: nodeMajor >= NODE_MIN_MAJOR, version: process.versions.node };
+    const node = {
+        ok: nodeMajor >= NODE_MIN_MAJOR,
+        version: process.versions.node,
+        version_manager: versionManagerNode(process.execPath),
+    };
     const gipity = {
         installed: true, // we're running it
         version: shimVersion(),
@@ -118,7 +153,11 @@ export const doctorCommand = new Command('doctor')
     console.log(bold('Gipity - doctor'));
     console.log('');
     console.log(bold('Environment'));
-    console.log(`${muted('node            ')} ${env.node.version}  ${env.node.ok ? success('✓') : clrError(`(need ${NODE_MIN_MAJOR}+)`)}`);
+    console.log(`${muted('node            ')} ${env.node.version}  ${env.node.ok ? success('✓') : clrError(`(need ${NODE_MIN_MAJOR}+)`)}${env.node.version_manager ? muted(`  (via ${env.node.version_manager})`) : ''}`);
+    if (env.node.version_manager) {
+        console.log(`${muted('                ')} ${warning(`node is managed by ${env.node.version_manager}`)} - if a fresh terminal reports \`gipity: command not found\`, its bin dir isn't on your`);
+        console.log(`${muted('                ')} ${dim(`login PATH yet. Ensure ${env.node.version_manager} auto-activates in your shell rc, set it as the default version, or symlink node + gipity onto your base PATH.`)}`);
+    }
     console.log(`${muted('gipity login    ')} ${env.gipity.logged_in ? success(`logged in as ${env.gipity.email}`) : (env.gipity.session_expired ? warning(`session expired (${env.gipity.email})`) : warning('not logged in'))}`);
     console.log(`${muted('claude code     ')} installed ${yn(env.claude.installed)} · authenticated ${yn(env.claude.authenticated)}`);
     const autostartLabel = env.relay.autostart === null ? muted('n/a') : yn(env.relay.autostart);

package/dist/commands/email.js

@@ -1,14 +1,24 @@
 import { Command } from 'commander';
-import { post } from '../api.js';
+import { get, post } from '../api.js';
 import { resolveProjectContext } from '../config.js';
-import { error as clrError, success } from '../colors.js';
+import { error as clrError, success, bold, muted, warning } from '../colors.js';
+import { run } from '../helpers/index.js';
 /** Commander collector: build an array from repeated flags (--to a --to b). */
 function collect(value, prev) {
     return [...prev, value];
 }
+// `email` is a command GROUP. Agent email is `email send`; the deployed app's
+// email() service is exercised via `email test` / `email log`. (Keeping agent
+// send under `send` rather than a bare-`email` default action avoids a
+// parent/subcommand `--subject` option collision — and matches the `email`
+// skill doc, which documents the CLI verb as `gipity email send`.)
 export const emailCommand = new Command('email')
-    .description('Send email')
-    .addHelpText('after', '\nSends from gipity@gipity.ai. Omit --to to self-send.')
+    .description("Send email as the agent (send), or test/inspect a deployed app's email() sends (test/log)");
+// --- gipity email send ---
+// Agent email from gipity@gipity.ai (omit --to to self-send).
+emailCommand
+    .command('send')
+    .description('Send an email as the agent (from gipity@gipity.ai; omit --to to self-send)')
     .requiredOption('--subject <subject>', 'Email subject')
     .requiredOption('--body <body>', 'Email body (plain text)')
     .option('--to <email>', 'Recipient (repeatable; omit for self-send)', collect, [])
@@ -20,10 +30,7 @@ export const emailCommand = new Command('email')
     .action(async (opts) => {
     try {
         await resolveProjectContext();
-        const payload = {
-            subject: opts.subject,
-            body: opts.body,
-        };
+        const payload = { subject: opts.subject, body: opts.body };
         if (opts.to.length)
             payload.to = opts.to;
         if (opts.cc.length)
@@ -50,4 +57,66 @@ export const emailCommand = new Command('email')
         process.exit(1);
     }
 });
+// --- gipity email test <to> ---
+// Exercises the deployed app's email() send path (platform-brokered, owner-billed)
+// so the agent can verify email works after deploy — the parallel of `notify test`.
+emailCommand
+    .command('test')
+    .description("Send a test email through your app's email() path (owner-billed)")
+    .argument('<to>', 'Recipient address')
+    .option('--subject <text>', 'Subject', 'Test email from Gipity')
+    .option('--text <text>', 'Body text', 'This is a test email sent through your app\'s email() service. ✉️')
+    .option('--reply-to <email>', 'Reply-To address')
+    .option('--from-name <name>', 'Sender display name (address stays gipity@gipity.ai)')
+    .option('--project <guid-or-slug>', 'Target a specific project instead of cwd / Home')
+    .option('--json', 'Output raw JSON')
+    .action((to, opts) => run('Email', async () => {
+    const { config } = await resolveProjectContext({ projectOverride: opts.project });
+    const payload = { to, subject: opts.subject, text: opts.text };
+    if (opts.replyTo)
+        payload.replyTo = opts.replyTo;
+    if (opts.fromName)
+        payload.fromName = opts.fromName;
+    const res = await post(`/api/${config.projectGuid}/services/email/send`, payload);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    const { sent, skipped, results } = res.data;
+    if (sent > 0)
+        console.log(success(`✓ Sent to ${sent} recipient${sent === 1 ? '' : 's'}.`));
+    else
+        console.log(warning(`Nothing sent (${skipped} skipped).`));
+    for (const r of results)
+        console.log(muted(`  ${r.to} — ${r.status}`));
+}));
+// --- gipity email log ---
+// Recent email() sends from the credits ledger (operation = email_send).
+emailCommand
+    .command('log')
+    .description('Recent email() sends from your app')
+    .option('--range <range>', 'Time range (24h, 7d, 30d)', '7d')
+    .option('--limit <n>', 'Max rows', '50')
+    .option('--project <guid-or-slug>', 'Target a specific project instead of cwd / Home')
+    .option('--json', 'Output raw JSON')
+    .action((opts) => run('Email', async () => {
+    const { config } = await resolveProjectContext({ projectOverride: opts.project });
+    const res = await get(`/account/logs/credits?operations=email_send&app_guid=${config.projectGuid}&range=${encodeURIComponent(opts.range)}&limit=${encodeURIComponent(opts.limit)}`);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    const { totals, items } = res.data;
+    if (!items.length) {
+        console.log(muted('No email() sends in this range.'));
+        return;
+    }
+    console.log(bold(`${totals.n} send${totals.n === 1 ? '' : 's'} · ${totals.credits} credit${totals.credits === 1 ? '' : 's'}`));
+    for (const r of items) {
+        const when = new Date(r.created_at).toISOString().replace('T', ' ').slice(0, 16);
+        const to = r.detail?.to ?? '—';
+        const subj = r.detail?.subject ? ` · ${r.detail.subject}` : '';
+        console.log(`  ${muted(when)}  ${to}${muted(subj)}`);
+    }
+}));
 //# sourceMappingURL=email.js.map

package/dist/commands/generate.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { post } from '../api.js';
 import { resolveProjectContext, getConfigPath } from '../config.js';
 import { pushFile } from '../sync.js';
-import { writeFileSync } from 'fs';
+import { mkdirSync, writeFileSync } from 'fs';
 import { resolve as resolvePath, dirname, relative, isAbsolute } from 'path';
 import { error as clrError, success, muted } from '../colors.js';
 import { printCommandError } from '../helpers/command.js';
@@ -25,11 +25,27 @@ async function downloadFile(url, filename) {
     if (!res.ok)
         throw new Error(`Download failed: ${res.status}`);
     const buffer = Buffer.from(await res.arrayBuffer());
+    ensureOutputDir(filename);
     writeFileSync(filename, buffer);
     const savedPath = resolvePath(filename);
     await pushGenerated(savedPath);
     return savedPath;
 }
+/** Create the parent directory of an -o path, so `-o src/audio/ding.mp3` works
+ *  in a tree that has no `src/audio/` yet instead of dying on a raw ENOENT.
+ *
+ *  Every action also calls this *before* its generate request: generation is
+ *  billed per call, so an unwritable output path has to fail before we spend
+ *  one, not after the bytes are already paid for and in hand. */
+function ensureOutputDir(output) {
+    const dir = dirname(resolvePath(output));
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        throw new Error(`can't create the output directory ${dir} (${err.code || err.message}). Pick a different -o path.`);
+    }
+}
 /** Sync a freshly generated file up to the linked project (no-op when there's
  *  no local project, or the file was written outside the project tree). */
 async function pushGenerated(savedPath) {
@@ -74,6 +90,8 @@ Examples:
     .action(async (prompt, opts) => {
     try {
         const { config } = await resolveProjectContext();
+        if (opts.output)
+            ensureOutputDir(opts.output);
         const doGenerate = () => post(`/projects/${config.projectGuid}/generate/image`, {
             prompt,
             provider: opts.provider,
@@ -135,6 +153,8 @@ Examples:
     .action(async (prompt, opts) => {
     try {
         const { config } = await resolveProjectContext();
+        if (opts.output)
+            ensureOutputDir(opts.output);
         const doGenerate = () => post(`/projects/${config.projectGuid}/generate/video`, {
             prompt,
             model: opts.model,
@@ -187,6 +207,8 @@ Examples:
     .action(async (text, opts) => {
     try {
         const { config } = await resolveProjectContext();
+        if (opts.output)
+            ensureOutputDir(opts.output);
         let speakers;
         if (opts.speakers) {
             try {
@@ -249,6 +271,8 @@ Examples:
     .action(async (prompt, opts) => {
     try {
         const { config } = await resolveProjectContext();
+        if (opts.output)
+            ensureOutputDir(opts.output);
         const doGenerate = () => post(`/projects/${config.projectGuid}/generate/music`, {
             prompt,
             duration_seconds: opts.duration,
@@ -299,6 +323,8 @@ Examples:
     .action(async (text, opts) => {
     try {
         const { config } = await resolveProjectContext();
+        if (opts.output)
+            ensureOutputDir(opts.output);
         const doGenerate = () => post(`/projects/${config.projectGuid}/generate/sound`, {
             text,
             duration_seconds: opts.duration,

package/dist/commands/login.js

@@ -3,6 +3,7 @@ import { saveAuth, getAuth } from '../auth.js';
 import { publicPost } from '../api.js';
 import { prompt, decodeJwtExp } from '../utils.js';
 import { success, error as clrError, muted } from '../colors.js';
+import { flushBugQueue } from '../bug-queue.js';
 export const loginCommand = new Command('login')
     .description('Log in or sign up')
     .option('--email <email>', 'Email address')
@@ -59,5 +60,11 @@ async function verify(email, code) {
         expiresAt,
     });
     console.log(success(`Logged in (${email}).`));
+    // A fresh session is the clearest "we're reconnected" signal - clear any bug
+    // reports that got stranded while this account's session was expired/offline.
+    const delivered = await flushBugQueue().catch(() => 0);
+    if (delivered > 0) {
+        console.log(muted(`Delivered ${delivered} queued bug report${delivered === 1 ? '' : 's'}.`));
+    }
 }
 //# sourceMappingURL=login.js.map

package/dist/commands/logs.js

@@ -26,7 +26,10 @@ logsCommand
     for (const log of res.data) {
         const time = new Date(log.created_at).toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit' });
         const dur = log.duration_ms !== null ? `${log.duration_ms}ms`.padEnd(8) : ''.padEnd(8);
-        const statusColor = log.status === 'success' ? success : log.status === 'error' ? clrError : warning;
+        // The runtime writes 'ok' | 'error' | 'limit_exceeded'; it has never
+        // written 'success'. Matching on that dead value painted every healthy
+        // invocation with the warning colour, so a clean log read as a problem.
+        const statusColor = log.status === 'ok' ? success : log.status === 'error' ? clrError : warning;
         const status = statusColor(log.status.padEnd(8));
         const trigger = muted(log.trigger_type.padEnd(8));
         const err = log.error_message ? `  ${clrError(`"${log.error_message}"`)}` : '';

package/dist/commands/page-eval.js

@@ -275,6 +275,16 @@ export const pageEvalCommand = new Command('eval')
         if (d.navigationIncomplete) {
             console.log(`${warning('⚠ Navigation incomplete:')} ${d.note || 'page did not reach full load'}`);
         }
+        // A slow-painting page makes any wall-clock wait silently wrong: the
+        // page's rAF loop is its clock, and engines cap the per-frame delta, so
+        // `setTimeout(2000)` may advance only a fraction of a second of app time.
+        // Without this line the eval returns a plausible-looking false negative.
+        if (d.slowRender) {
+            console.log(`${warning('⚠ Slow render:')} page painted at ${d.slowRender.fps} fps. `
+                + `Waiting on real time (setTimeout) advances animation/physics time far slower than it looks — `
+                + `assertions after a wall-clock wait can report a false negative. `
+                + `Step the app's own loop deterministically instead (3D templates: ${bold('core.advance(seconds)')}).`);
+        }
         // Auth state: without this line an agent can't distinguish "signed-in
         // eval" from "--auth silently no-op'd against the anonymous page".
         if (d.auth?.requested) {

package/dist/commands/page-screenshot.js

@@ -150,6 +150,11 @@ function splitCsv(values) {
 function appendOption(value, previous = []) {
     return [...previous, value];
 }
+// Pre-capture scripting lives on --action, but agents reach for the JS-intent
+// names first and an "unknown option" alone doesn't name the right flag. Capture
+// the common guesses as hidden decoys (taking a value, so they swallow the
+// script) and redirect precisely — same pattern as `page eval`'s JS_DECOY_FLAGS.
+const ACTION_DECOY_FLAGS = ['--eval', '--js', '--javascript', '--script', '--code', '--exec'];
 export const pageScreenshotCommand = new Command('screenshot')
     .description('Screenshot a web page')
     .argument('<url>', 'URL to screenshot')
@@ -172,6 +177,13 @@ export const pageScreenshotCommand = new Command('screenshot')
     // rather than reject it as an unknown option and send them on a --help detour.
     .addOption(new Option('--full-page', 'Alias for --full').hideHelp())
     .action((url, opts) => run('Page screenshot', async () => {
+    // A JS-intent flag guess (captured as a hidden decoy below): name the real
+    // flag before any other arg-shape check fires.
+    const decoy = ACTION_DECOY_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
+    if (decoy) {
+        pageScreenshotCommand.error(`error: ${decoy} is not a flag on screenshot — use --action "<js>" to run JavaScript in the page ` +
+            `before the capture, e.g. gipity page screenshot "<url>" --action "document.getElementById('play').click()"`);
+    }
     // --wait is a hidden alias for --post-load-delay (agents reach for it because
     // sibling `page inspect`/`eval` name the flag --wait). Canonical name wins if
     // both given; fall back to the 1000ms default when neither is set.
@@ -308,6 +320,10 @@ export const pageScreenshotCommand = new Command('screenshot')
         console.log(`${label('Screenshot file')} ${success(savedFiles[i])}`);
     }
 }));
+// Register the JS-intent guesses as hidden decoys (value-taking, so they swallow
+// the script) — the action turns any of them into the "--action" redirect above.
+for (const f of ACTION_DECOY_FLAGS)
+    pageScreenshotCommand.addOption(new Option(`${f} <value>`).hideHelp());
 // `screenshot` captures the page AFTER load + settle (+ optional --action). There
 // is no scroll-to-a-position or wait-for-a-selector lever (agents reach for
 // --scroll/--selector and get an unknown-option detour) — but `--full` does walk

package/dist/commands/sandbox.js

@@ -1,8 +1,8 @@
 import { Command } from 'commander';
 import { readFileSync, existsSync, statSync } from 'fs';
-import { dirname, extname, relative } from 'path';
+import { dirname, extname, relative, resolve } from 'path';
 import { post } from '../api.js';
-import { resolveProjectContext, getConfigPath, shouldIgnore } from '../config.js';
+import { resolveProjectContext, getConfigPath, getProjectRoot, shouldIgnore } from '../config.js';
 import { SCRATCH_IGNORE } from '../setup.js';
 import { sync } from '../sync.js';
 import { error as clrError, dim } from '../colors.js';
@@ -344,10 +344,28 @@ GCC/Rust).
             console.error(res.data.stderr);
         if (res.data.timedOut)
             console.error(`[Timed out after ${res.data.durationMs}ms]`);
+        if (res.data.stdoutTruncated || res.data.stderrTruncated) {
+            console.error(dim('Note: output truncated at 256 KB. Write large results to a file instead of printing them.'));
+        }
         if (res.data.outputFiles && res.data.outputFiles.length > 0) {
-            console.log(`\nOutput files ${pulledLocal ? 'synced to this directory' : 'saved to project'}:`);
-            for (const f of res.data.outputFiles)
-                console.log(`${f}`);
+            // Only claim a file is "synced to this directory" once it is actually on
+            // local disk - a sync that ran is not the same as a file that landed.
+            const projectRoot = getProjectRoot();
+            const landed = (f) => pulledLocal && !!projectRoot && existsSync(resolve(projectRoot, f));
+            const onDisk = res.data.outputFiles.filter(landed);
+            const notOnDisk = res.data.outputFiles.filter((f) => !landed(f));
+            if (onDisk.length > 0) {
+                console.log('\nOutput files synced to this directory:');
+                for (const f of onDisk)
+                    console.log(`${f}`);
+            }
+            if (notOnDisk.length > 0) {
+                console.log('\nOutput files saved to project:');
+                for (const f of notOnDisk)
+                    console.log(`${f}`);
+                if (pulledLocal)
+                    console.log(dim("Not pulled locally - run 'gipity sync' to fetch them."));
+            }
         }
         if (res.data.skippedOutputFiles && res.data.skippedOutputFiles.length > 0) {
             console.log(dim('\nNot persisted (--no-sync-output):'));