gipity 1.0.374 → 1.0.380

package/dist/commands/claude.js

@@ -22,10 +22,10 @@ import { get, post, publicPost, ApiError, getAccountSlug } from '../api.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, getConfigPath } from '../config.js';
 import { sync } from '../sync.js';
 import { slugify, setupClaudeHooks, setupClaudeMd, setupAgentsMd, setupGitignore, DEFAULT_SYNC_IGNORE, isSyncIgnored } from '../setup.js';
-import { buildProjectContextBlock as buildProjectContextBlockText, buildExistingProjectPrompt as buildExistingProjectPromptText, buildNewProjectPrompt, buildResumeWrap, buildFreshWrap, } from '../prompts.js';
+import { buildProjectContextBlock as buildProjectContextBlockText, buildNewProjectPrompt, buildResumeWrap, buildFreshWrap, } from '../prompts.js';
 import * as relayState from '../relay/state.js';
 import { maybeOfferRelayOn, ensureDaemonRunning } from '../relay/onboarding.js';
-import { prompt, promptBoxed, pickOne, decodeJwtExp, confirm } from '../utils.js';
+import { prompt, pickOne, decodeJwtExp, confirm } from '../utils.js';
 import { brand, bold, info, success, error as clrError, muted } from '../colors.js';
 import { createProgressReporter } from '../progress.js';
 import { printBanner } from '../banner.js';
@@ -107,10 +107,6 @@ async function buildProjectContextBlock(opts) {
     const stats = await fetchProjectStats(opts.projectGuid, opts.cwd);
     return buildProjectContextBlockText({ ...opts, ...stats });
 }
-async function buildExistingProjectPrompt(opts) {
-    const stats = await fetchProjectStats(opts.projectGuid, opts.cwd);
-    return buildExistingProjectPromptText({ ...opts, ...stats });
-}
 /** Interactive email+code login flow. Used on first login and when the
  *  server returns 401 mid-command (session expired). Writes the new auth
  *  to disk and returns it. */
@@ -410,30 +406,12 @@ export const claudeCommand = new Command('claude')
                 // whether to use the new-project framing for that wrap.
                 headlessNewProject = isNewProject;
             }
-            else if (isNewProject) {
-                console.log('');
-                console.log(`  ${bold("What's next? What would you like to build?")}`);
-                console.log('');
-                const buildIdea = (await promptBoxed()).trim();
-                const stats = await fetchProjectStats(project.short_guid, process.cwd());
-                initialPrompt = buildNewProjectPrompt({
-                    projectName: project.name,
-                    projectSlug: project.slug,
-                    projectGuid: project.short_guid,
-                    accountSlug,
-                    cwd: process.cwd(),
-                    ...stats,
-                    buildIdea,
-                });
-            }
             else {
-                initialPrompt = await buildExistingProjectPrompt({
-                    projectName: project.name,
-                    projectSlug: project.slug,
-                    projectGuid: project.short_guid,
-                    accountSlug,
-                    cwd: process.cwd(),
-                });
+                // Interactive: launch with no seeded first message. The per-project
+                // CLAUDE.md (refreshed just above) carries the project identity,
+                // scaffold rule, and definition of done, so Claude has full context
+                // the moment the user types. A welcome banner prints before launch.
+                initialPrompt = '';
             }
             console.log(`  ${success(`Project "${project.name}" ready.`)}\n`);
         }
@@ -470,13 +448,8 @@ export const claudeCommand = new Command('claude')
                     console.log('  Could not sync files (will retry on next prompt).');
                 }
             }
-            initialPrompt = await buildExistingProjectPrompt({
-                projectName: existing.projectSlug,
-                projectSlug: existing.projectSlug,
-                projectGuid: existing.projectGuid,
-                accountSlug: existing.accountSlug,
-                cwd: process.cwd(),
-            });
+            // Interactive: no seeded prompt - CLAUDE.md carries the context now.
+            initialPrompt = '';
         }
         else {
             // Fetch user's projects. If the session expired (401), re-run the
@@ -596,38 +569,11 @@ export const claudeCommand = new Command('claude')
                     console.log('  Could not sync files (will retry on next prompt).');
                 }
             }
-            // ── Step 2b: What do you want to build? (new projects only) ────
-            if (isNewProject) {
-                console.log('');
-                console.log(`  ${bold('Claude Code enabled with Gipity!')}`);
-                console.log('');
-                console.log(`  ${bold("What's next? What would you like to build?")}`);
-                console.log(`  ${muted('Examples: a landing page, a Pac-Man game, a full web app,')}`);
-                console.log(`  ${muted('an API that returns random facts, an image, just answer questions?')}`);
-                console.log('');
-                console.log(`  ${muted('Claude Code with Gipity can do everything your old Claude Code could do but so much more now!')}`);
-                console.log('');
-                const buildIdea = (await promptBoxed()).trim();
-                const stats = await fetchProjectStats(project.short_guid, process.cwd());
-                initialPrompt = buildNewProjectPrompt({
-                    projectName: project.name,
-                    projectSlug: project.slug,
-                    projectGuid: project.short_guid,
-                    accountSlug,
-                    cwd: process.cwd(),
-                    ...stats,
-                    buildIdea,
-                });
-            }
-            else {
-                initialPrompt = await buildExistingProjectPrompt({
-                    projectName: project.name,
-                    projectSlug: project.slug,
-                    projectGuid: project.short_guid,
-                    accountSlug,
-                    cwd: process.cwd(),
-                });
-            }
+            // Interactive launch: no seeded first message (new or existing). The
+            // per-project CLAUDE.md carries identity + scaffold rule + definition
+            // of done, and a welcome banner prints before launch - the user tells
+            // Claude directly what they want to build or do.
+            initialPrompt = '';
             setupClaudeHooks();
             setupClaudeMd();
             setupAgentsMd();
@@ -729,7 +675,10 @@ export const claudeCommand = new Command('claude')
             claudeArgs.push(arg);
         }
         if (!nonInteractive) {
-            console.log(`  ${info('Launching Claude Code...')}\n`);
+            console.log(`  ${bold('Launching Claude Code, powered by Gipity.')}`);
+            console.log(`  ${muted("Just tell Claude what you'd like to build or do - everything Claude could do")}`);
+            console.log(`  ${muted('before, and now, on Gipity, so much more.')}`);
+            console.log('');
         }
         // In non-interactive (-p) mode, prepend a Gipity preamble to the
         // user's raw message. Two flavors:

package/dist/commands/deploy.js

@@ -56,7 +56,7 @@ export const deployCommand = new Command('deploy')
     else {
         // Fallback for simple deploys without phases
         const size = formatSize(d.totalBytes);
-        console.log(`${success('✓')} ${d.fileCount} files (${size}) → ${success(d.url)}`);
+        console.log(`${success('✓')} ${d.fileCount} files (${size})`);
     }
     if (d.customDomains?.length) {
         console.log(`${muted('Also:')} ${d.customDomains.join(', ')}`);
@@ -80,6 +80,11 @@ export const deployCommand = new Command('deploy')
     }
     else {
         console.log(success(`✓ Deployed to ${target}`) + muted(` (${d.elapsedMs}ms)`));
+        // The live URL is the one thing the caller (often an agent) needs next
+        // - to open it, inspect it, or report it. Always surface it so nobody
+        // has to reconstruct the URL convention or guess a subdomain.
+        if (d.url)
+            console.log(`${muted('Live:')} ${brand(d.url)}`);
     }
 }));
 //# sourceMappingURL=deploy.js.map

package/dist/commands/page-eval.js

@@ -5,11 +5,13 @@ 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) {
+ *  we submit, then poll the result out of the job store. `expectedWorkMs` is
+ *  the time the server-side work is expected to take (settle + any in-page
+ *  awaits); the client budget is that plus 60s of headroom. */
+export async function pollEvalResult(evalJobId, expectedWorkMs) {
     // 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;
+    const deadline = Date.now() + expectedWorkMs + 60_000;
     let missCount = 0;
     while (Date.now() < deadline) {
         let rec;
@@ -69,4 +71,15 @@ export const pageEvalCommand = new Command('eval')
     if (d.truncated)
         console.log(muted('\n(result truncated to fit context - narrow the expression for the full value)'));
 }));
+// Each `page eval` call runs to completion before the next starts, so two evals
+// fired back-to-back never coexist in time - they CANNOT test whether two live
+// clients see each other (presence, shared state). For that, use the genuinely-
+// concurrent `page test --observe` instead, which overlaps N clients and reports
+// whether they actually ran together.
+pageEvalCommand.addHelpText('after', `
+Testing realtime/shared state across clients?
+  Separate 'page eval' calls run sequentially (one finishes before the next
+  starts), so they never overlap and will each see only themselves - a false
+  negative. Use 'gipity page test <url> --observe <expr>' for genuinely
+  concurrent clients with overlap verification.`);
 //# sourceMappingURL=page-eval.js.map

package/dist/commands/page-screenshot.js

@@ -105,6 +105,10 @@ export const pageScreenshotCommand = new Command('screenshot')
     .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())
+    // `--full-page` is the Puppeteer/Playwright name for this (their `fullPage`),
+    // so agents reach for it by reflex. Accept it as a hidden alias for `--full`
+    // 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 () => {
     const delayRaw = opts.postLoadDelay ?? opts.wait;
     const postLoadDelayMs = delayRaw !== undefined ? parseInt(String(delayRaw), 10) : undefined;
@@ -126,7 +130,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     const body = {
         url,
         postLoadDelayMs,
-        full: !!opts.full,
+        full: !!(opts.full || opts.fullPage),
         reloadBetween: opts.reloadBetween !== false,
         ...(userSpecifiedViewports ? { viewports: customViewports } : {}),
         ...(opts.fakeMedia ? { fakeMedia: true } : {}),

package/dist/commands/page-test.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { post } from '../api.js';
 import { brand, bold, muted, warning, success, error as clrError } from '../colors.js';
 import { run } from '../helpers/index.js';
+import { pollEvalResult } from './page-eval.js';
 // Lines worth surfacing - genuine errors and crash signatures, not benign warnings.
 const BAD = /^error:|uncaught|unhandled|message handler error|\bcrash|RuntimeError/i;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -15,25 +16,148 @@ async function inspectClient(url, waitMs, i) {
         return { i, lines: [], error: err instanceof Error ? err.message : String(err) };
     }
 }
-// Headless multi-client realtime check: spin N staggered browser clients at a
-// deployed URL and flag error/crash lines across their consoles. The verifier
-// for realtime apps (host election, presence, world sync, reconnection) -
-// promotes the internal multi-client-test script to a first-class command.
-//
-// Passive page loads only: each client just loads the URL and settles. An app
-// that connects to realtime only after a user action (e.g. a lobby that joins
-// on a button press) needs a URL-param test mode so the load alone exercises
-// the path - see the app-realtime skill.
-export const pageTestCommand = new Command('test')
-    .description('Multi-client realtime check: load a URL in N staggered headless clients, flag console errors')
-    .argument('<url>', 'Deployed URL to load in every client')
-    .option('--clients <n>', 'Number of headless clients to launch', '2')
-    .option('--stagger <s>', 'Seconds between client starts (client 0 settles first, e.g. as host)', '12')
-    .option('--wait <ms>', 'Milliseconds each client stays open after load (max 30000)', '24000')
-    .option('--json', 'Output as JSON')
-    .action((url, opts) => run('Page test', async () => {
+const MAX_HOLD_MS = 15_000; // keep each in-page await under the ~20s browser action timeout
+const MIN_HOLD_MS = 1_000;
+/** Splice per-client values into a user expression. `{{label}}` → the client's
+ *  label, `{{i}}` → its 0-based index. Plain string replace (no regex) so the
+ *  expression's own characters are never treated as patterns. */
+function subst(expr, label, i) {
+    return expr.split('{{label}}').join(label).split('{{i}}').join(String(i));
+}
+/** Build the statement-body script one client runs: do the one-time action,
+ *  then sample `observe` `samples` times across `holdMs`, stamping in-page
+ *  start/end so the caller can confirm the clients overlapped. */
+function buildHarness(action, observe, label, holdMs, samples) {
+    const n = Math.max(2, samples);
+    const interval = Math.max(0, Math.floor(holdMs / (n - 1)));
+    const lines = [
+        `const __label=${JSON.stringify(label)};`,
+        `const __t0=Date.now();`,
+    ];
+    if (action && action.trim()) {
+        lines.push(`try{ ${action} }catch(__e){ return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:[],actionError:String((__e&&__e.message)||__e)}; }`);
+    }
+    lines.push(`const __s=[];`, `for(let __k=0;__k<${n};__k++){`, `  let __v; try{ __v=(${observe}); }catch(__e){ __v='ObserveError: '+String((__e&&__e.message)||__e); }`, `  __s.push(__v);`, `  if(__k<${n - 1}) await new Promise(function(r){setTimeout(r,${interval});});`, `}`, `return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:__s};`);
+    return lines.join('\n');
+}
+/** Kick off and poll one client's eval job, then parse the harness payload. */
+async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector) {
+    const base = { i, label, samples: [], startedAt: 0, endedAt: 0 };
+    try {
+        const kickoff = await post('/tools/browser/eval', {
+            url,
+            expr,
+            waitMs: settleMs,
+            waitForSelector: waitForSelector || undefined,
+            waitForTimeoutMs: waitForSelector ? 5000 : undefined,
+        });
+        // Server work ≈ nav + settle + the in-page hold; pollEvalResult adds 60s headroom.
+        const d = await pollEvalResult(kickoff.data.evalJobId, settleMs + holdMs);
+        const raw = d.result?.trim() ?? '';
+        if (raw.startsWith('EvalError:') || raw.startsWith('ObserveError:')) {
+            return { ...base, error: raw };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return { ...base, error: `unparseable client result: ${raw.slice(0, 200)}` };
+        }
+        if (parsed.actionError) {
+            return { ...base, error: `action failed: ${parsed.actionError}` };
+        }
+        return {
+            i,
+            label: typeof parsed.label === 'string' ? parsed.label : label,
+            samples: Array.isArray(parsed.samples) ? parsed.samples : [],
+            startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
+            endedAt: typeof parsed.endedAt === 'number' ? parsed.endedAt : 0,
+        };
+    }
+    catch (err) {
+        return { ...base, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Compute the window during which ALL successful clients were live at once.
+ *  Intersection of every [startedAt, endedAt]; positive duration ⇒ they
+ *  genuinely coexisted, so any shared-state reading is trustworthy. */
+function overlapMs(results) {
+    const live = results.filter((r) => !r.error && r.startedAt > 0 && r.endedAt > r.startedAt);
+    if (live.length < 2)
+        return 0;
+    const start = Math.max(...live.map((r) => r.startedAt));
+    const end = Math.min(...live.map((r) => r.endedAt));
+    return Math.max(0, end - start);
+}
+function fmtSamples(samples) {
+    if (samples.length === 0)
+        return muted('(no samples)');
+    return samples.map((s) => (typeof s === 'string' ? s : JSON.stringify(s))).join(' → ');
+}
+async function runInteractive(url, observe, opts) {
+    const clients = Math.max(1, parseInt(opts.clients, 10) || 2);
+    const stagger = opts.stagger != null ? Math.max(0, parseInt(opts.stagger, 10) || 0) : 0;
+    const hold = Math.min(MAX_HOLD_MS, Math.max(MIN_HOLD_MS, parseInt(opts.hold, 10) || 8000));
+    const samples = Math.min(30, Math.max(2, parseInt(opts.samples, 10) || 6));
+    const settle = opts.waitFor ? 200 : 1000;
+    const labels = (opts.labels ? String(opts.labels).split(',').map((s) => s.trim()) : []).filter(Boolean);
+    const labelFor = (i) => labels[i] ?? `client-${i}`;
+    if (!opts.json) {
+        console.log(`${brand('Page test')} ${muted('(interactive)')} ${bold(url)}`);
+        console.log(muted(`${clients} client(s), stagger ${stagger}s, hold ${hold}ms, ${samples} samples each`));
+    }
+    const runs = [];
+    for (let i = 0; i < clients; i++) {
+        runs.push((async () => {
+            await sleep(i * stagger * 1000);
+            if (!opts.json)
+                console.log(muted(`client ${i} (${labelFor(i)}) joining`));
+            const expr = buildHarness(opts.action ? subst(opts.action, labelFor(i), i) : undefined, subst(observe, labelFor(i), i), labelFor(i), hold, samples);
+            return observeClient(url, expr, i, labelFor(i), settle, hold, opts.waitFor);
+        })());
+    }
+    const results = (await Promise.all(runs)).sort((a, b) => a.i - b.i);
+    const errored = results.filter((r) => r.error);
+    const ovl = overlapMs(results);
+    const overlapped = ovl > 0;
+    if (opts.json) {
+        console.log(JSON.stringify({
+            url, mode: 'interactive', clients, stagger, hold, samples,
+            overlapMs: ovl, overlapped, results,
+        }));
+        if (errored.length > 0 || (clients > 1 && !overlapped))
+            process.exitCode = 1;
+        return;
+    }
+    for (const r of results) {
+        console.log(`\n${bold(`=== client ${r.i} (${r.label}) ===`)}`);
+        if (r.error) {
+            console.log(clrError(`✗ ${r.error}`));
+            continue;
+        }
+        console.log(`${muted('samples:')} ${fmtSamples(r.samples)}`);
+    }
+    console.log('');
+    if (errored.length > 0) {
+        console.log(clrError(`⚠ ${errored.length} client(s) failed (see above)`));
+    }
+    if (clients < 2) {
+        console.log(muted('Note: a single client cannot verify cross-client visibility — run with --clients 2+.'));
+    }
+    else if (overlapped) {
+        console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s — genuine concurrency, so the readings above are trustworthy`));
+    }
+    else {
+        console.log(clrError('⚠ clients did NOT overlap in time — each ran in isolation, so any shared-state reading here is a FALSE NEGATIVE, not proof the app is broken.'));
+        console.log(muted('  Likely causes: --stagger ≥ --hold, or more --clients than free browser slots (they queued). Lower --stagger / raise --hold / fewer --clients and retry.'));
+    }
+    if (errored.length > 0 || (clients > 1 && !overlapped))
+        process.exitCode = 1;
+}
+async function runPassive(url, opts) {
     const clients = Math.max(1, parseInt(opts.clients, 10) || 2);
-    const stagger = Math.max(0, parseInt(opts.stagger, 10) || 0);
+    const stagger = opts.stagger != null ? Math.max(0, parseInt(opts.stagger, 10) || 0) : 12;
     const wait = Math.min(30000, Math.max(2000, parseInt(opts.wait, 10) || 24000));
     if (!opts.json) {
         console.log(`${brand('Page test')} ${bold(url)}`);
@@ -82,5 +206,51 @@ export const pageTestCommand = new Command('test')
         : `\n${clrError(`⚠ ${problems} error/crash line(s) flagged above`)}`);
     if (problems > 0)
         process.exitCode = 1;
+}
+// Headless multi-client realtime check. Two modes:
+//
+//  Passive (default): spin N staggered browser clients at a deployed URL and
+//  flag error/crash lines across their consoles. Each client just loads the URL
+//  and settles - good for apps that connect on load (or via a URL-param test
+//  mode; see the app-realtime skill).
+//
+//  Interactive (--observe, optionally with --action): each client loads the
+//  URL, runs a one-time --action (e.g. submit a name), then samples --observe
+//  across a hold window. The clients run genuinely concurrently and the command
+//  VERIFIES they overlapped in time - so a presence/shared-state app whose
+//  readings only make sense when clients coexist can't be misread as broken
+//  just because the clients never actually ran together.
+export const pageTestCommand = new Command('test')
+    .description('Multi-client realtime check: load a URL in N concurrent headless clients; flag console errors, or drive an action and observe shared state (--observe)')
+    .argument('<url>', 'Deployed URL to load in every client')
+    .option('--clients <n>', 'Number of headless clients to launch', '2')
+    .option('--stagger <s>', 'Seconds between client starts (passive default 12; interactive default 0)')
+    .option('--wait <ms>', 'Passive mode: ms each client stays open after load (max 30000)', '24000')
+    // Interactive mode (--observe drives it):
+    .option('--observe <expr>', 'Interactive: JS expression sampled in each client to read shared state (e.g. presence count). Switches on interactive mode.')
+    .option('--action <expr>', 'Interactive: one-time JS run in each client before observing (e.g. fill a name + submit). {{label}}/{{i}} are substituted per client.')
+    .option('--labels <csv>', 'Interactive: per-client labels substituted for {{label}} (default client-0, client-1, …)')
+    .option('--hold <ms>', `Interactive: total observe window per client (${MIN_HOLD_MS}-${MAX_HOLD_MS}ms)`, '8000')
+    .option('--samples <k>', 'Interactive: number of observations across the hold window (2-30)', '6')
+    .option('--wait-for <selector>', 'Interactive: wait for this CSS selector before running --action (deterministic readiness gate)')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  # Passive: load in 3 staggered clients, flag console errors
+  gipity page test "https://dev.gipity.ai/me/app/" --clients 3 --stagger 8
+
+  # Interactive: two concurrent clients each join with a name, then watch the
+  # live presence count. The command confirms the clients actually overlapped.
+  gipity page test "https://dev.gipity.ai/me/app/" --clients 2 \\
+    --action "document.querySelector('#name').value='{{label}}'; document.querySelector('form').requestSubmit();" \\
+    --observe "document.querySelectorAll('.present').length" \\
+    --labels Alice,Bob`)
+    .action((url, opts) => run('Page test', async () => {
+    if (opts.observe) {
+        await runInteractive(url, opts.observe, opts);
+    }
+    else {
+        await runPassive(url, opts);
+    }
 }));
 //# sourceMappingURL=page-test.js.map

package/dist/commands/project.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { join } from 'path';
 import { mkdirSync } from 'fs';
 import { get, post, put, del, getAccountSlug } from '../api.js';
-import { requireConfig, saveConfig } from '../config.js';
+import { requireConfig, saveConfig, liveUrl } from '../config.js';
 import { slugify } from '../setup.js';
 import { error as clrError, brand, muted, info, success } from '../colors.js';
 import { confirm } from '../utils.js';
@@ -161,6 +161,7 @@ projectCommand
         console.log(`Name:    ${p.name}`);
         console.log(`Slug:    ${p.slug}`);
         console.log(`GUID:    ${p.short_guid}`);
+        console.log(`Live:    ${liveUrl(config)}`);
         console.log(`Created: ${new Date(p.created_at).toLocaleDateString()}`);
         if (p.description)
             console.log(`Desc:    ${p.description}`);

package/dist/commands/sandbox.js

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
-import { dirname, relative } from 'path';
+import { readFileSync } from 'fs';
+import { dirname, extname, relative } from 'path';
 import { post } from '../api.js';
 import { resolveProjectContext, getConfigPath } from '../config.js';
 import { sync } from '../sync.js';
@@ -28,9 +29,10 @@ function resolveRelativeCwd() {
 export const sandboxCommand = new Command('sandbox')
     .description('Run code in a sandbox');
 sandboxCommand
-    .command('run <code>')
+    .command('run [code]')
     .description('Run code')
     .option('--language <language>', 'Language: js, py, or bash', 'js')
+    .option('--file <path>', 'Read the code body from a file instead of the inline <code> arg; --language is inferred from the extension when not given')
     .option('--timeout <seconds>', 'Execution timeout in seconds', '30')
     .option('--input <path>', 'Narrow to specific project files instead of auto-mirroring the whole tree (repeatable). Use this only for >1 GB projects or when you want surgical control.', (v, prev) => [...(prev ?? []), v])
     .option('--json', 'Output as JSON')
@@ -55,6 +57,9 @@ Examples:
   $ gipity sandbox run --language python \\
       "import pandas as pd; print(pd.read_csv('data/sales.csv').describe())"
 
+  # Run a script file directly (language inferred from .py)
+  $ gipity sandbox run --file build_report.py
+
   # Surgical: only these files are mirrored in
   $ gipity sandbox run --language bash \\
       --input src/images/hero.png \\
@@ -68,9 +73,31 @@ Pre-installed: Python (pandas, numpy, matplotlib, Pillow, scipy, bs4),
 CLI tools (ImageMagick, FFmpeg, webp/cwebp, optipng, jq, pandoc, exiftool,
 GCC/Rust).
 `)
-    .action((code, opts) => run('Sandbox', async () => {
+    .action((code, opts, command) => run('Sandbox', async () => {
     const { config } = await resolveProjectContext();
-    const language = LANG_MAP[opts.language] || opts.language;
+    if (code !== undefined && opts.file) {
+        console.error(clrError('Pass either an inline <code> arg or --file <path>, not both'));
+        process.exit(1);
+    }
+    if (code === undefined && !opts.file) {
+        console.error(clrError('Provide an inline <code> arg or --file <path>'));
+        process.exit(1);
+    }
+    let source = code;
+    if (opts.file) {
+        try {
+            source = readFileSync(opts.file, 'utf8');
+        }
+        catch {
+            console.error(clrError(`Cannot read file: ${opts.file}`));
+            process.exit(1);
+        }
+    }
+    // Infer language from the file extension unless --language was given explicitly.
+    const fromExt = opts.file && command.getOptionValueSource('language') === 'default'
+        ? LANG_MAP[extname(opts.file).slice(1).toLowerCase()]
+        : undefined;
+    const language = fromExt || LANG_MAP[opts.language] || opts.language;
     if (!['javascript', 'python', 'bash'].includes(language)) {
         console.error(clrError(`Invalid language: ${opts.language}. Use: js, py, or bash`));
         process.exit(1);
@@ -78,7 +105,7 @@ GCC/Rust).
     const timeout = parseInt(opts.timeout, 10);
     const cwd = resolveRelativeCwd();
     const res = await post(`/projects/${config.projectGuid}/sandbox/execute`, {
-        code,
+        code: source,
         language,
         timeout: isNaN(timeout) ? 30 : timeout,
         input_files: opts.input,

package/dist/commands/status.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { existsSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { getAuth, getTimeRemaining } from '../auth.js';
-import { getConfig } from '../config.js';
+import { getConfig, liveUrl } from '../config.js';
 import { brand, success, warning, muted, error as clrError } from '../colors.js';
 import { HOOKS_SETTINGS, setupClaudeHooks } from '../setup.js';
 /** Inspect `.claude/settings.json` against the current `HOOKS_SETTINGS`.
@@ -50,6 +50,7 @@ export const statusCommand = new Command('status')
                 slug: config.projectSlug,
                 account: config.accountSlug,
                 apiBase: config.apiBase,
+                url: liveUrl(config),
             } : null,
             auth: auth ? {
                 email: auth.email,
@@ -66,6 +67,7 @@ export const statusCommand = new Command('status')
     else {
         console.log(`${muted('Project:')} ${brand(config.projectSlug)} ${muted(`(${config.projectGuid})`)}`);
         console.log(`${muted('Account:')} ${config.accountSlug}`);
+        console.log(`${muted('Live:')} ${liveUrl(config)}`);
         console.log(`${muted('API:')} ${config.apiBase}`);
         if (config.agentGuid)
             console.log(`${muted('Agent:')} ${config.agentGuid}`);

package/dist/config.js

@@ -127,6 +127,17 @@ export async function resolveProjectContext(opts) {
         oneOff: true,
     };
 }
+/** The canonical live URL for a deployed project. This is THE place the
+ *  dev/prod URL convention lives - every command that tells the user (or an
+ *  agent) where their app is (`deploy`, `status`, `project info`) derives it
+ *  here, so nothing ever has to reconstruct `dev.gipity.ai/<account>/<slug>/`
+ *  by hand or guess a subdomain like `<slug>.gipity.app` (which doesn't
+ *  resolve). Mirrors the server's deploy URL; `deploy` itself prints the
+ *  server-authoritative URL, the read-only commands derive it from config. */
+export function liveUrl(config, target = 'dev') {
+    const host = target === 'prod' ? 'app.gipity.ai' : 'dev.gipity.ai';
+    return `https://${host}/${config.accountSlug}/${config.projectSlug}/`;
+}
 export function clearConfigCache() {
     cached = null;
     cachedPath = null;

package/dist/flag-aliases.js

@@ -62,9 +62,17 @@ function collectRealFlags(argv, program) {
     const args = argv.slice(2);
     let cmd = program;
     const chain = [program];
-    for (const tok of args) {
-        if (tok.startsWith('-'))
-            break; // first flag ends command resolution
+    // Root value-options (e.g. `--api-base <url>`) may legitimately precede the
+    // subcommand; skip them (and their value token) rather than ending resolution
+    // there, so a command's own flag is still discovered when a global flag leads.
+    const rootValueFlags = new Set(program.options.filter(o => o.long && o.required).map(o => o.long));
+    for (let i = 0; i < args.length; i++) {
+        const tok = args[i];
+        if (tok.startsWith('-')) {
+            if (!tok.includes('=') && rootValueFlags.has(tok))
+                i++; // consume its value
+            continue;
+        }
         const next = cmd.commands.find(c => c.name() === tok || c.aliases().includes(tok));
         if (!next)
             break;

package/dist/knowledge.js

@@ -3,7 +3,7 @@
  *
  * AUTO-GENERATED - do not edit directly.
  * Source: platform/docs/knowledge/*.md + docs/skills/*.md frontmatter + gipity-overview.ts
- * Run `just sync-knowledge` to refresh.
+ * Run `just build-knowledge` to refresh.
  */
 export const BUILD_VS_NON_BUILD_RULE = `## When to add a template
 If the user wants a deployable app (web, game, API): run \`gipity add <template>\` before writing any files. A template wires up \`gipity.yaml\`, deploy config, and sync; hand-written files miss all of it.
@@ -63,9 +63,9 @@ When a user asks for a foreign stack ("build it in React", "use MS SQL Server",
 
 The one exception is app-level libraries the user imports into their own \`src/\` code - Three.js, Rapier, Phaser, MediaPipe, a charting or animation library. Those are fine. The opinionation is about the *platform* layer (framework, backend, database, styling system, hosting, auth, services), not every npm package.
 
-## When to add a template
+## Build loop
 
-The full rule and definition of done are injected at the top of every session context. In short: if the user asks you to build something deployable (web app, game, API), run \`gipity add <template>\` first (default \`web-simple\`); if it's a one-off task (analysis, PDFs, data work), use \`gipity sandbox run\` instead. To add a reusable building block to an existing app (e.g. multiplayer), \`gipity add <kit>\`.
+The full "when to add a template" rule and the definition of done are spelled out in the two sections at the end of this document. In short: if the user wants something deployable (web app, game, API), \`gipity add <template>\` first (default \`web-simple\`); for a one-off task (analysis, PDFs, data work), use \`gipity sandbox run\` instead; to add a reusable building block to an existing app (e.g. multiplayer), \`gipity add <kit>\`.
 
 Build loop: \`gipity add\` → edit files → \`gipity deploy dev\` → \`gipity page inspect <url>\` → fix any errors → repeat until the definition of done is met.
 
@@ -75,7 +75,7 @@ Before telling the user the app is online, verify the source tree is consistent:
 
 ## CLI quick reference
 
-Key commands: \`gipity add <template|kit>\`, \`gipity deploy dev\`, \`gipity sandbox run\`, \`gipity page inspect <url>\`, \`gipity db query "SQL"\`, \`gipity fn call <name>\`, \`gipity logs fn <name>\`, \`gipity skill read <name>\`.
+Key commands: \`gipity add <template|kit>\`, \`gipity deploy dev\`, \`gipity sandbox run\`, \`gipity page inspect <url>\`, \`gipity page screenshot <url>\`, \`gipity db query "SQL"\`, \`gipity fn call <name>\`, \`gipity logs fn <name>\`, \`gipity skill read <name>\`.
 Run \`gipity --help\` for the full list. Use \`--help\` on any command for details.
 
 ## Tool output is complete and synchronous

package/dist/progress.js

@@ -19,11 +19,26 @@ class TerminalProgress {
     /** True while an in-place transfer line is on screen and not yet committed. */
     liveOpen = false;
     lastRenderAt = 0;
+    /** The label of the current transfer session; a change starts a fresh one. */
+    barLabel = null;
+    /** True once the current session hit 100% - late/overshoot ticks are dropped. */
+    barSettled = false;
     phase(message) {
         this.commitLive();
         process.stdout.write(`  ${muted(message)}\n`);
     }
     transfer(label, doneBytes, totalBytes) {
+        // A new label begins a fresh transfer session (e.g. downloads → uploads on
+        // the same reporter). Within a session, once we've drawn the 100% frame we
+        // drop any further ticks - download byte totals are estimated, so the wire
+        // can deliver a hair more or fewer bytes than expected and we don't want a
+        // late chunk reopening a second "100%" line.
+        if (label !== this.barLabel) {
+            this.barLabel = label;
+            this.barSettled = false;
+        }
+        if (this.barSettled)
+            return;
         const finished = totalBytes > 0 && doneBytes >= totalBytes;
         // Throttle mid-flight redraws; always paint the first and final frames.
         const now = Date.now();
@@ -32,8 +47,10 @@ class TerminalProgress {
         this.lastRenderAt = now;
         this.liveOpen = true;
         process.stdout.write('\r' + this.frame(label, doneBytes, totalBytes) + CLEAR_TO_EOL);
-        if (finished)
+        if (finished) {
             this.commitLive();
+            this.barSettled = true;
+        }
     }
     finish() {
         this.commitLive();

package/dist/prompts.js

@@ -105,14 +105,6 @@ export function buildProjectContextBlock(opts) {
         DEFINITION_OF_DONE,
     ].join('\n').replace(/\n{3,}/g, '\n\n');
 }
-/** Project-context block + a brief greeting instruction. */
-export function buildExistingProjectPrompt(opts) {
-    const isEmpty = opts.fileCount === 0;
-    const greeting = isEmpty
-        ? `Briefly greet the user and ask what they want to build.`
-        : `Briefly greet the user, summarize what this project appears to be (based on the file listing and any README/CLAUDE.md/gipity.yaml), and ask what they want to work on next.`;
-    return [buildProjectContextBlock(opts), ``, greeting].join('\n');
-}
 /** First-launch prompt for a brand-new (empty) project. Reuses buildProjectContextBlock. */
 export function buildNewProjectPrompt(opts) {
     const base = buildProjectContextBlock(opts);

package/dist/setup.js

@@ -5,7 +5,7 @@ import { resolve, join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { SCAFFOLD_HOOK_WARNING } from './prompts.js';
-import { SKILLS_CONTENT } from './knowledge.js';
+import { SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE } from './knowledge.js';
 import { getConfig } from './config.js';
 export { SKILLS_CONTENT };
 /** Canonical list of workstation artifacts that are NOT part of the project.
@@ -218,9 +218,20 @@ export function setupClaudeHooks() {
  *  are stable - changing them would orphan the blocks in existing files. */
 export const GIPITY_BLOCK_BEGIN = '<!-- BEGIN GIPITY INTEGRATION - auto-generated by gipity, do not edit this block -->';
 export const GIPITY_BLOCK_END = '<!-- END GIPITY INTEGRATION -->';
-/** The Gipity-owned section: current SKILLS_CONTENT wrapped in the markers. */
+/** The Gipity-owned section, marker-wrapped: the integration guide + the full
+ *  scaffold rule + the definition of done. The rule and DoD used to be injected
+ *  only into the interactive `gipity claude` seed; folding the *static* parts
+ *  into the primer means every agent (Claude, Codex, Gemini, ...) gets them, and
+ *  the seed no longer has to carry that context.
+ *
+ *  Per-project values (GUID, live URL) deliberately do NOT live here - baking
+ *  them into a generated doc is the wrong layer. The CLI surfaces them where the
+ *  agent actually looks: `gipity deploy` prints the live URL, `gipity status` and
+ *  `gipity project info` show the URL + GUID. That keeps them authoritative and
+ *  avoids stale values frozen into a file. */
 function renderManagedBlock() {
-    return `${GIPITY_BLOCK_BEGIN}\n${SKILLS_CONTENT}\n${GIPITY_BLOCK_END}`;
+    const body = [SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE].join('\n\n');
+    return `${GIPITY_BLOCK_BEGIN}\n${body}\n${GIPITY_BLOCK_END}`;
 }
 /**
  * Pure core of `writeSkillsFile`: given a file's current content (or `null`

package/dist/sync.js

@@ -195,14 +195,14 @@ async function fetchRemote(projectGuid) {
     }
     return out;
 }
-async function downloadAll(projectGuid) {
+async function downloadAll(projectGuid, onBytes) {
     const stream = await downloadStream(`/projects/${projectGuid}/files/tree?content=tar`);
     const extract = tar.extract();
     const files = new Map();
     return new Promise((resolve, reject) => {
         extract.on('entry', (header, entryStream, next) => {
             const chunks = [];
-            entryStream.on('data', (c) => chunks.push(c));
+            entryStream.on('data', (c) => { chunks.push(c); onBytes?.(c.length); });
             entryStream.on('end', () => { files.set(header.name, Buffer.concat(chunks)); next(); });
             entryStream.resume();
         });
@@ -519,9 +519,23 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
     const downloadedBytes = new Map();
     const needsBulkDownload = plannedToApply.some(a => a.kind === 'download' || a.kind === 'conflict');
     if (needsBulkDownload) {
-        p?.phase('Downloading updates from Gipity…');
+        // The tree endpoint streams the *whole* remote tree as one tar (the caller
+        // then picks out only the paths it planned to apply), so the bytes that
+        // actually move = the sum of every remote file's size. That's the honest
+        // denominator for the bar - it tracks real wire progress, not just the
+        // handful of changed files.
+        const downloadLabel = 'Downloading updates from Gipity';
+        const totalDownloadBytes = [...remote.values()].reduce((sum, r) => sum + r.size, 0);
+        let recvBytes = 0;
+        p?.transfer(downloadLabel, 0, totalDownloadBytes);
+        const onBytes = p
+            ? (delta) => {
+                recvBytes = Math.min(recvBytes + delta, totalDownloadBytes);
+                p.transfer(downloadLabel, recvBytes, totalDownloadBytes);
+            }
+            : undefined;
         try {
-            const all = await downloadAll(config.projectGuid);
+            const all = await downloadAll(config.projectGuid, onBytes);
             for (const a of plannedToApply) {
                 if (a.kind === 'download' || a.kind === 'conflict') {
                     const buf = all.get(a.path);
@@ -533,6 +547,11 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
         catch (err) {
             errors.push(`Download batch failed: ${err.message}`);
         }
+        finally {
+            // Settle the bar even if the extracted-byte tally fell short of the
+            // estimate (the live line stays open until something hits 100% or finish()).
+            p?.finish();
+        }
     }
     // ── Writes pass: uploads, downloads, conflicts (rename + download + upload copy) ──
     // We serialize conflicts; uploads run with bounded concurrency.

package/dist/template-vars.js

@@ -68,7 +68,10 @@ export function buildTemplateVars(v) {
         '{{DESCRIPTION_META}}': v.description ? `\n  <meta name="description" content="${safeDesc}">` : '',
         '{{OG_DESCRIPTION}}': v.description ? `\n  <meta property="og:description" content="${safeDesc}">` : '',
         '{{JSON_LD_BLOCK}}': `<script type="application/ld+json">\n${jsonLd}\n  </script>`,
-        '{{ANALYTICS_SCRIPT}}': `<script defer src="https://media.gipity.ai/client/v1/gipity.js" data-app="${v.projectGuid}"></script>`,
+        // `crossorigin="anonymous"` so SDK errors surface with a real message/stack
+        // (CORS mode) instead of a sanitized message-less "Script error". The CDN
+        // returns Access-Control-Allow-Origin:*, so it works on any app domain.
+        '{{ANALYTICS_SCRIPT}}': `<script defer crossorigin="anonymous" src="https://media.gipity.ai/client/v1/gipity.js" data-app="${v.projectGuid}"></script>`,
     };
 }
 /** Pure string substitution — exported so the test can exercise it without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.374",
+  "version": "1.0.380",
   "description": "The full-stack platform tuned for AI agents. Database, storage, auth, functions, deploy, and drop-in kits - all agent-tuned. Pair with Claude Code or use standalone.",
   "bin": {
     "gipity": "dist/updater/shim.js",