gipity 1.0.429 → 1.1.1

package/dist/commands/chat.js

@@ -50,9 +50,15 @@ export const chatCommand = new Command('chat')
                 ...(a.remoteSize != null ? { size: a.remoteSize } : {}),
             }));
         }
+        // The server's cost-consent gate stops the agentic loop on big-build
+        // requests: content comes back empty with an explicit costWarning.
+        // Surface it - before this the CLI printed a blank line and the request
+        // silently did nothing. Re-running the command consents via chat reply.
+        const displayContent = res.data.content || res.data.costWarning?.message || '';
         if (opts.json) {
             console.log(JSON.stringify({
-                content: res.data.content,
+                content: displayContent,
+                costWarning: res.data.costWarning ?? null,
                 toolsUsed: res.data.toolsUsed?.map(t => ({
                     tool: t.toolName,
                     success: t.success,
@@ -67,8 +73,8 @@ export const chatCommand = new Command('chat')
             }));
         }
         else {
-            // Show agent response
-            console.log(res.data.content);
+            // Show agent response (or the cost warning when the gate stopped the loop)
+            console.log(displayContent);
             // Show tools used
             if (res.data.toolsUsed && res.data.toolsUsed.length > 0) {
                 const toolNames = [...new Set(res.data.toolsUsed.map(t => t.toolName))];

package/dist/commands/claude.js

@@ -9,7 +9,7 @@ import { get, post, ApiError, getAccountSlug } from '../api.js';
 import { interactiveLogin } from '../login-flow.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, DEFAULT_API_BASE, getConfigPath } from '../config.js';
 import { sync } from '../sync.js';
-import { slugify, setupClaudeHooks, ensureGipityPluginInstalled, setupClaudeMd, setupAgentsMd, setupGitignore, DEFAULT_SYNC_IGNORE, isSyncIgnored } from '../setup.js';
+import { slugify, ensureGipityPluginInstalled, setupProjectTools, DEFAULT_SYNC_IGNORE, isSyncIgnored } from '../setup.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';
@@ -481,10 +481,7 @@ export const claudeCommand = new Command('claude')
             catch (err) {
                 console.log(`  ${warning('Could not sync files (will retry on next prompt):')} ${err.message}`);
             }
-            setupClaudeHooks();
-            setupClaudeMd();
-            setupAgentsMd();
-            setupGitignore();
+            setupProjectTools();
             if (nonInteractive) {
                 // Headless: the -p message is wrapped later (Step 3). Just record
                 // whether to use the new-project framing for that wrap.
@@ -503,10 +500,7 @@ export const claudeCommand = new Command('claude')
             // cwd already has (or inherits) a .gipity.json - run inside it.
             console.log(`  Project: ${brand(existing.projectSlug)} ${muted(`(${existing.projectGuid})`)}`);
             console.log(`  ${success('Already set up.')}\n`);
-            setupClaudeHooks();
-            setupClaudeMd();
-            setupAgentsMd();
-            setupGitignore();
+            setupProjectTools();
             // Warn before syncing a very large project tree. An oversized root
             // (or a config accidentally rooted high up, e.g. at $HOME) makes the
             // sync slow, and a silent multi-GB walk reads as a hang.
@@ -658,10 +652,7 @@ export const claudeCommand = new Command('claude')
             // 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();
-            setupGitignore();
+            setupProjectTools();
             console.log(`  ${success(`Project "${project.name}" ready.`)}\n`);
         }
         // ── Step 3: Launch Claude Code ────────────────────────────────────

package/dist/commands/db.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { get, post, sendMessage } from '../api.js';
+import { get, post } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, success } from '../colors.js';
 import { run, printList, emitField } from '../helpers/index.js';
@@ -106,13 +106,20 @@ dbCommand
     .description('Create a database')
     .option('--json', 'Output as JSON')
     .action((name, opts) => run('Create', async () => {
-    // DDL delegates to agent (needs confirmation flow)
-    const response = await sendMessage(`Create a new database called "${name}" for this project. Confirm when done, no explanation.`);
+    // Direct REST create - same endpoint `db drop` uses. This used to delegate
+    // to agent chat, which burned LLM tokens and, after the cost-consent gate
+    // landed server-side, could return an empty response having created
+    // nothing. Creating a database isn't destructive, so no confirmation.
+    const config = requireConfig();
+    await post(`/projects/${config.projectGuid}/db/manage`, {
+        action: 'create',
+        name,
+    });
     if (opts.json) {
-        console.log(JSON.stringify({ response }));
+        console.log(JSON.stringify({ success: true, name }));
     }
     else {
-        console.log(response);
+        console.log(success(`Created database '${name}'.`));
     }
 }));
 dbCommand

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { existsSync, readFileSync, statSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } 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';
@@ -162,7 +162,13 @@ export const doctorCommand = new Command('doctor')
     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);
     console.log(`${muted('relay           ')} paired ${yn(env.relay.paired)} · running ${yn(env.relay.running)} · autostart ${autostartLabel}${env.relay.paused ? warning(' · paused') : ''}${env.relay.device ? muted(`  (${env.relay.device.name})`) : ''}`);
-    console.log(`${muted('ready           ')} ${env.ready ? success('yes') : warning('no - run `gipity claude` (or the desktop app) to finish setup')}`);
+    // Codex approves project hooks interactively and stores the decision in
+    // its own opaque state - we can't verify it from here, so surface the
+    // one manual step whenever this project ships Codex hooks.
+    if (existsSync(resolve(process.cwd(), '.codex', 'hooks.json'))) {
+        console.log(`${muted('codex hooks     ')} ${warning('written')} - session capture needs a one-time approval: run /hooks inside Codex in this project`);
+    }
+    console.log(`${muted('ready           ')} ${env.ready ? success('yes') : warning('no - run `gipity build` (or the desktop app) to finish setup')}`);
     // ── CLI install / update health ────────────────────────────────────
     const state = readState();
     const settings = readSettings();

package/dist/commands/init.js

@@ -4,7 +4,7 @@ import { existsSync, readFileSync } from 'fs';
 import { getAccountSlug } from '../api.js';
 import { getConfig, getConfigPath, saveConfigAt } from '../config.js';
 import { getAuth } from '../auth.js';
-import { slugify, setupClaudeHooks, setupGitignore, SUPPORTED_TOOLS, DEFAULT_TOOLS, DEFAULT_SYNC_IGNORE } from '../setup.js';
+import { slugify, setupProjectTools, SUPPORTED_TOOLS, DEFAULT_TOOLS, DEFAULT_SYNC_IGNORE } from '../setup.js';
 import { success, error as clrError, info, muted, bold } from '../colors.js';
 import { confirm } from '../utils.js';
 import { scanForAdoption, adoptCurrentDir, canAdoptCwd, formatBytes, formatCwdLabel, ADOPT_THRESHOLDS, } from '../adopt-cwd.js';
@@ -23,7 +23,7 @@ function resolveTools(forFlag) {
 }
 export const initCommand = new Command('init')
     .description('Link this directory to a project')
-    .addHelpText('after', '\nWrites CLAUDE.md/AGENTS.md primer files so your AI coding tool understands Gipity.')
+    .addHelpText('after', '\nWrites CLAUDE.md/AGENTS.md primer files so your AI coding tool understands Gipity, and installs the Gipity skills + file-sync hooks into the agent CLIs found on this machine (Claude Code, Codex, Grok).')
     .argument('[name]', 'Project name/slug (defaults to current directory name)')
     .option('--agent <guid>', 'Agent GUID to use')
     .option('--no-capture', 'Don\'t record Claude Code sessions in this directory to your Gipity project (sets captureHooks: false in .gipity.json)')
@@ -32,7 +32,8 @@ export const initCommand = new Command('init')
 Examples:
   $ gipity init                          Link cwd as a new project (slug = dir name).
   $ gipity init my-app                   Link cwd with an explicit slug.
-  $ gipity init --for codex              Write only AGENTS.md (skip Claude/Cursor/etc).
+  $ gipity init --for codex              AGENTS.md + Codex skills/sync hooks only.
+  $ gipity init --for grok               AGENTS.md + the Gipity plugin in Grok only.
   $ gipity init --for cursor,gemini      Write only the Cursor + Gemini primers.
   $ gipity init --for aider              AGENTS.md + a read: entry in .aider.conf.yml
                                          (aider auto-reads nothing, so it's opt-in).
@@ -57,10 +58,6 @@ Working with an existing Gipity project:
         process.exit(1);
     }
     const wantsClaude = tools.some(t => t.key === 'claude');
-    const writeAllPrimers = () => {
-        for (const t of tools)
-            t.setup();
-    };
     const primerSummary = tools.map(t => t.label).join(', ');
     try {
         // Check auth
@@ -77,12 +74,9 @@ Working with an existing Gipity project:
         if (existsSync(resolve(cwd, '.gipity.json'))) {
             const existing = getConfig();
             console.log(`Already linked to ${info(`"${existing?.projectSlug ?? ''}"`)} ${muted(`(${existing?.projectGuid ?? ''})`)}`);
-            // Re-run setup in case hooks/skills are missing. Claude Code hooks
-            // only matter when the Claude primer is being written.
-            if (wantsClaude)
-                setupClaudeHooks();
-            writeAllPrimers();
-            setupGitignore();
+            // Re-run setup in case primers/hooks/skills are missing - each tool's
+            // integration self-gates on its binary and current-version state.
+            setupProjectTools(tools);
             // The config's ignore list was frozen at link time, so a workstation
             // artifact introduced by a newer CLI (e.g. aider's .aider.conf.yml)
             // would sync up as project content. Union in the current defaults.
@@ -143,7 +137,7 @@ Working with an existing Gipity project:
             const sizeStr = scan.truncated ? `>${formatBytes(ADOPT_THRESHOLDS.REFUSE_BYTES)}` : formatBytes(scan.bytes);
             const fileStr = scan.truncated ? `>${ADOPT_THRESHOLDS.REFUSE_FILES}` : `${scan.files}`;
             console.error(clrError(`Directory has ${fileStr} files (${sizeStr}) - too large to adopt as a Gipity project.`));
-            console.error(muted('Move into a subdirectory, or use `gipity claude` and pick "Create new project".'));
+            console.error(muted('Move into a subdirectory, or use `gipity build` and pick "Create new project".'));
             process.exit(1);
         }
         if (scan.tier === 'moderate') {
@@ -183,7 +177,7 @@ Working with an existing Gipity project:
         }
         console.log(success(`Wrote primer files: ${primerSummary}.`));
         if (wantsClaude) {
-            console.log(success('Ready! Run `gipity claude` for Claude Code, or open this directory in your other AI coding tool.'));
+            console.log(success('Ready! Run your coding agent here (claude, codex, grok), or `gipity build` to launch one with a picker.'));
             // Recording happens by default (however Claude Code is launched), so
             // say so up front - consent should be explicit, not discovered later.
             if (opts.capture === false) {

package/dist/commands/page-eval.js

@@ -8,8 +8,10 @@ import { resolveProjectContext } from '../config.js';
 import { uploadPublicFixture, uploadCameraFeed, assertCameraFile, deleteFixture } from '../page-fixtures.js';
 // Shown when an eval runs cleanly but returns nothing serializable. Turns a
 // bare/opaque `null` into a deterministic, actionable nudge so the agent shapes
-// a returnable value instead of guessing and retrying.
-export const EVAL_NO_VALUE_HINT = 'The eval ran but returned no JSON-serializable value. A statement body with no `return`, an assignment, a void call, or a DOM node/function all serialize to null. ' +
+// a returnable value instead of guessing and retrying. (A body ending in a bare
+// expression is auto-returned SERVER-side before this can fire — so this is the
+// residue: block/loop endings, explicit undefined returns, DOM nodes, functions.)
+export const EVAL_NO_VALUE_HINT = 'The eval ran but returned no JSON-serializable value. A body ending in a loop/if-block, a `return` of undefined, or a DOM node/function all serialize to null. ' +
     'End the script with an expression — or an explicit `return` — that yields plain data, e.g. `return { label: input.value, count: items.length }` or `return JSON.stringify(payload)`.';
 /** Normalize a raw eval result for display. The eval can come back as a useful
  *  serialized value, the literal `null`/`undefined`/empty string, or — when the
@@ -346,7 +348,9 @@ export function evalExecTimeoutMessage(result, budgetMs) {
 // a trap, since --json is a real flag that changes output but still leaves the
 // script unset, sending the agent in a loop. Capture the common guesses as
 // hidden decoy options so the action can redirect to the positional arg exactly.
-const JS_DECOY_FLAGS = ['--js', '--javascript', '--script', '--code', '--expr', '--eval', '--exec'];
+// `--action` rides along: it's the sibling `page screenshot`'s spelling of
+// "run JS on the page", so an agent that learned it there guesses it here.
+const JS_DECOY_FLAGS = ['--js', '--javascript', '--script', '--code', '--expr', '--eval', '--exec', '--action'];
 // 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
@@ -360,7 +364,7 @@ const JS_DECOY_FLAGS = ['--js', '--javascript', '--script', '--code', '--expr',
 export const pageEvalCommand = new Command('eval')
     .description('Evaluate JS in a real browser on a page (DOM, computed styles, element rects; inline expr or --file script). ONE client per call - to verify realtime/presence across concurrent clients use `page test --observe` instead')
     .argument('<url>', 'URL to load')
-    .argument('[expr]', `JavaScript to evaluate in page context (inline expression or statement body with return/await; result is JSON-serialized). Omit when using --file. Time budget: the body has ${EVAL_SCRIPT_BUDGET_MS / 1000}s to finish after page load (${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s with --camera) - raise it with --timeout, max ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s.`)
+    .argument('[expr]', `JavaScript to evaluate in page context (inline expression or statement body; await works, and the trailing expression is returned automatically — REPL-style — so no explicit return is needed; result is JSON-serialized). Omit when using --file. Time budget: the body has ${EVAL_SCRIPT_BUDGET_MS / 1000}s to finish after page load (${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s with --camera) - raise it with --timeout, max ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s.`)
     .option('--file <path>', `Read the script body from a file instead of the inline <expr> arg (mutually exclusive). Runs as an async function body, so top-level return/await work. Same post-load budget as <expr> (--timeout).`)
     .option('--step <expr>', `Run another expression against the SAME loaded page, after <expr> (repeat, max ${MAX_EVAL_STEPS}). Whatever that page load paid for — a vision model coming up, a game booting, a socket connecting — stays up for every step, so an N-part check costs ONE page load instead of N. Each step gets its own in-page budget and its own reported result.`, (val, prev) => [...prev, val], [])
     .option('--fixture <path>', 'Host a local file and expose it to the eval as `fixtureUrl` (and under `fixtures` by basename) to fetch in-page. For verifying a render/parse path against a real binary (an MP3, an image) - no size limit, auto-deleted after the run. Repeat for several files (single-value so it never swallows the inline <expr>).', (val, prev) => [...prev, val], [])
@@ -372,7 +376,7 @@ export const pageEvalCommand = new Command('eval')
     .option('--wait-for <selector>', `Wait until this CSS selector appears before evaluating, then evaluate (deterministic - beats guessing a --wait). Gate on the state you are ASSERTING, not just a ready flag: '#verdict:not(:empty)' returns the instant the round lands, where a fixed wait snapshots mid-sequence. Same flag on page inspect/screenshot. Max ${WAIT_FOR_MAX_MS}ms (--wait-timeout).`)
     .option('--wait-timeout <ms>', `Max ms to wait for --wait-for before giving up (max ${WAIT_FOR_MAX_MS})`, '5000')
     .option('--timeout <ms>', `How long the script itself may run IN the page - its own await/setTimeout pauses count (default ${EVAL_SCRIPT_BUDGET_MS}, ${EVAL_SCRIPT_BUDGET_CAMERA_MS} with --camera/--fake-media; max ${EVAL_SCRIPT_BUDGET_MAX_MS}). Raise it to trace a sequence that unfolds over time (a game round, an animation). Distinct from --wait, which only sleeps BEFORE the script.`)
-    .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
+    .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
     .option('--json', 'Output as JSON')
     .action((url, exprArg, opts) => run('Page eval', async () => {
     // A JS-intent flag guess (captured as a hidden decoy below): redirect to the
@@ -470,6 +474,9 @@ export const pageEvalCommand = new Command('eval')
     // cleaned up, without shifting the fixture map the caller indexes into.
     let camera;
     let projectGuid;
+    // Completion-value semantics (a body ending in a bare expression returns it,
+    // REPL-style) are applied SERVER-side to every leg — one source of truth for
+    // every caller; the CLI sends the script as written.
     let sentExpr = expr;
     let sentSteps = steps;
     // Validate the camera file locally first: a wrong file type should cost one
@@ -574,14 +581,18 @@ export const pageEvalCommand = new Command('eval')
         if (d.slowRender) {
             console.log(slowRenderMessage(d.slowRender.fps, { camera: !!camera, waitMs }));
         }
-        // Auth state: without this line an agent can't distinguish "signed-in
-        // eval" from "--auth silently no-op'd against the anonymous page".
+        // Identity line on EVERY run: without it an agent can't distinguish
+        // "signed-in eval" from "--auth silently no-op'd against the anonymous
+        // page" — or, worse, assume an unflagged run carried a signed-in session.
         if (d.auth?.requested) {
             const who = getAuth()?.email;
             console.log(d.auth.established
                 ? `${muted('Auth:')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
                 : `${warning('Auth: session NOT established')}${d.auth.detail ? ` — ${d.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
         }
+        else {
+            console.log(muted('Auth: anonymous visitor (signed out; pass --auth to run as your Gipity account)'));
+        }
         if (camera)
             console.log(`${muted('Camera:')} ${camera.name} ${muted('(played as the webcam feed; getUserMedia resolves)')}`);
         if (hosted.length)

package/dist/commands/page-inspect.js

@@ -43,7 +43,7 @@ export const pageInspectCommand = new Command('inspect')
     .option('--all', 'Include render-blocking, large resources, oversized images, overflow culprits, and LCP detail')
     .option('--no-fake-media', "Inspect with NO camera or microphone present, so a getUserMedia app takes its no-device error path (use this only when that fallback IS what you're inspecting)")
     .option('--device <name>', `Inspect as a real touch device: ${INSPECT_DEVICES.join(', ')}. Emulates touch events, mobile user-agent and DPR, so a touch-gated mobile layout is what gets inspected.`)
-    .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
+    .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
     // 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())
@@ -164,14 +164,18 @@ export async function inspectPage(url, opts = {}) {
     if (b.navigationIncomplete) {
         console.log(`${warning('⚠ Navigation incomplete:')} ${b.note || 'page did not reach full load'}`);
     }
-    // Auth state: without this line an agent can't distinguish "signed-in render"
-    // from "--auth silently no-op'd and I'm looking at the anonymous page".
+    // Identity line on EVERY run: without it an agent can't distinguish
+    // "signed-in render" from "--auth silently no-op'd and I'm looking at the
+    // anonymous page" — or assume an unflagged run carried a signed-in session.
     if (b.auth?.requested) {
         const who = getAuth()?.email;
         console.log(b.auth.established
             ? `${muted('Auth:')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
             : `${warning('Auth: session NOT established')}${b.auth.detail ? ` — ${b.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
     }
+    else {
+        console.log(muted('Auth: anonymous visitor (signed out; pass --auth to load as your Gipity account)'));
+    }
     console.log(`${muted('Title:')} ${b.title || '(none)'}`);
     console.log(`${muted('Elements:')} ${b.elementCount || 0}`);
     console.log(`${muted('Page weight:')} ${info(formatSize(b.totalBytes || 0))}`);

package/dist/commands/page-screenshot.js

@@ -30,12 +30,15 @@ function label(text) {
 function fmtMs(ms) {
     return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
 }
-/** Auth state line (same format as page inspect/eval): without it an agent
- *  can't tell a signed-in capture from "--auth silently no-op'd and this is
- *  the anonymous page". */
+/** Identity line on EVERY capture (same format as page inspect/eval): without
+ *  it an agent can't tell a signed-in capture from "--auth silently no-op'd and
+ *  this is the anonymous page" — or assumes an unflagged capture carried a
+ *  signed-in session. */
 function printAuthLine(auth) {
-    if (!auth?.requested)
+    if (!auth?.requested) {
+        console.log(`${label('Auth')} ${muted('anonymous visitor (signed out; pass --auth to capture as your Gipity account)')}`);
         return;
+    }
     const who = getAuth()?.email;
     console.log(auth.established
         ? `${label('Auth')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
@@ -176,10 +179,13 @@ 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'];
+// names first — --eval above all, the name they already know from `page eval`.
+// The intent is unambiguous (run this JS in the page before the shot), so these
+// are working hidden aliases, not errors — same accept-the-reflex-guess pattern
+// as --full-page and --width/--height. (Supersedes the earlier decoy approach,
+// which swallowed the script and errored with a redirect: when the guess is
+// unambiguous, making it WORK beats making it a better error.)
+const ACTION_ALIAS_FLAGS = ['--eval', '--js', '--javascript', '--script', '--code', '--exec'];
 /** A capture is worthless if it fires before the app reaches the state you meant
  *  to photograph, and the only lever used to be a blind millisecond delay — so a
  *  camera/vision app got screenshotted with a guessed duration (`--wait 22000`).
@@ -216,6 +222,12 @@ export const CAMERA_DEFAULT_DELAY_MS = 15_000;
 export const pageScreenshotCommand = new Command('screenshot')
     .description('Screenshot a web page')
     .argument('<url>', 'URL to screenshot')
+    // --device / --viewport lead the options: "how does this look on a phone?" is
+    // the single most common reason to screenshot, and agents routinely read the
+    // help through `--help | head -N` — buried below the timing flags, these two
+    // fell off the bottom and the run proceeded at desktop width.
+    .option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device — touch events, mobile user-agent, DPR — so touch-gated mobile UI actually renders.`, appendOption, [])
+    .option('--viewport <dims>', 'Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag), e.g. --viewport 390x844 for a phone-sized window', appendOption, [])
     // No commander default: a default here would make the value always set, so the
     // merge below could not tell "caller chose a delay" from "nobody did" — which
     // is what --camera's model-load default and the --wait-for gate both hinge on.
@@ -225,27 +237,35 @@ export const pageScreenshotCommand = new Command('screenshot')
     .option('--action <js>', 'Run JS in the page before capturing — e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs as an async function body, so const/await and app-relative import(\'./…\') work. Runs after the post-load delay, then settles again before the shot. If it throws, the capture still happens and the failure is reported.')
     .option('--full', 'Capture the full scrollable page (default: viewport only). Scrolls the page through first so scroll-reveal/fade-in-on-scroll (IntersectionObserver) sections render into the shot instead of capturing blank.')
     .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
-    .option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device — touch events, mobile user-agent, DPR — so touch-gated mobile UI actually renders.`, 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. The video feed is a built-in test pattern — to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
     .option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture — so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
-    .option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
+    .option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
     .option('--ephemeral', 'Skip the project screenshot history: do not persist this capture to Gipity (screenshots/ in the project). Local file is still written.')
     .option('--json', 'Output JSON metadata instead of a friendly summary')
     .addOption(new Option('--post-load-delay <ms>', 'Alias for --wait').hideHelp())
+    // (--eval and the other JS-intent guesses are registered in one place from
+    // ACTION_ALIAS_FLAGS below — a second standalone registration here makes
+    // commander throw "conflicting flag" at startup.)
     // `--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())
+    // `--width 390 --height 844` is the setViewport vocabulary agents guess first
+    // when asked for a phone-sized shot. Accept the pair as a working alias for
+    // --viewport WxH instead of bouncing the guess into a --help detour.
+    .addOption(new Option('--width <px>', 'Alias: --viewport WxH').hideHelp())
+    .addOption(new Option('--height <px>', 'Alias: --viewport WxH').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()"`);
+    // A JS-intent alias guess (--eval et al., hidden): fold it into the action
+    // script so the reflex guess just works, and name the canonical flag once
+    // so the next call uses it.
+    const aliasFlag = ACTION_ALIAS_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
+    if (aliasFlag) {
+        console.error(muted(`Note: treating ${aliasFlag} as --action — it runs your JS in the page before the capture. --action is the canonical flag.`));
     }
+    const actionScript = [opts.action, ...ACTION_ALIAS_FLAGS.map((f) => opts[f.slice(2)])]
+        .filter(Boolean).join('\n');
     // --wait is the canonical name (it is what `page inspect`/`page eval` call it);
     // --post-load-delay stays as a hidden alias. Whether the caller named EITHER is
     // what decides the defaults below, so keep the raw "was it set" signal.
@@ -284,6 +304,24 @@ export const pageScreenshotCommand = new Command('screenshot')
     }
     const deviceNames = splitCsv(opts.device);
     const viewportStrs = splitCsv(opts.viewport);
+    // --width/--height: fold the alias pair into a --viewport entry. Half a
+    // pair is a mis-invocation worth one precise line, not a range error.
+    if (opts.width !== undefined || opts.height !== undefined) {
+        if (opts.width === undefined || opts.height === undefined) {
+            pageScreenshotCommand.error('error: --width and --height go together (both in px, equivalent to --viewport WxH) — ' +
+                'or use a preset like --device mobile for a real handset (touch events, mobile user-agent, DPR)');
+        }
+        if (!/^\d+$/.test(String(opts.width)) || !/^\d+$/.test(String(opts.height))) {
+            pageScreenshotCommand.error('error: --width and --height must be integers (px)');
+        }
+        viewportStrs.push(`${opts.width}x${opts.height}`);
+        // A raw phone-sized window is NOT a phone: touch-gated mobile UI still
+        // renders its desktop variant. Say so once, on the path where the caller
+        // was clearly after a phone.
+        if (parseInt(String(opts.width), 10) <= 500) {
+            console.error(muted('Tip: --device mobile emulates a real handset (touch events, mobile user-agent, DPR) — a raw viewport only resizes the window.'));
+        }
+    }
     const customViewports = [
         ...deviceNames.map(resolveDevice),
         ...viewportStrs.map(parseViewportString),
@@ -318,11 +356,12 @@ export const pageScreenshotCommand = new Command('screenshot')
     }
     // The pre-capture script the server runs after the post-load delay: the
     // --wait-for gate first (so the shot waits for the state, deterministically),
-    // then the caller's --action. Both are the same in-page primitive, so they
+    // then the caller's --action (with any alias-flag scripts folded in by
+    // actionScript above). All the same in-page primitive, so they
     // compose into one script rather than needing a second server round-trip.
     const preCapture = [
         opts.waitFor ? buildWaitForGate(opts.waitFor, waitForTimeoutMs) : '',
-        opts.action ?? '',
+        actionScript,
     ].filter(Boolean).join('\n');
     const body = {
         url,
@@ -476,10 +515,10 @@ export const pageScreenshotCommand = new Command('screenshot')
         printVfsLine(s);
     }
 }));
-// 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());
+// Register the JS-intent guesses as hidden aliases for --action (value-taking,
+// so they capture the script) — the action folds them into the pre-capture body.
+for (const f of ACTION_ALIAS_FLAGS)
+    pageScreenshotCommand.addOption(new Option(`${f} <js>`, 'Alias for --action').hideHelp());
 // `screenshot` captures the page AFTER load + settle (+ optional --wait-for gate
 // and --action). There is no scroll-to-a-position lever (agents reach for
 // --scroll and get an unknown-option detour) — but `--full` does walk the page

package/dist/commands/project.js

@@ -134,7 +134,7 @@ projectCommand
         console.log(`${muted('Next:')} switch to "${project.name}" in the sidebar.`);
     }
     else {
-        console.log(`${muted('Next:')} exit Claude (Ctrl+D), then run:  ${brand('gipity claude')}`);
+        console.log(`${muted('Next:')} exit Claude (Ctrl+D), then run:  ${brand('gipity build')}`);
         console.log(`${muted('Pick')} "${project.name}" ${muted(`- it'll be at the top of the list.`)}`);
     }
 }));

package/dist/commands/relay-install.js

@@ -6,7 +6,7 @@ import { installAutostart, removeAutostart, resolveCliPath } from '../relay/setu
 function requirePaired() {
     const device = state.getDevice();
     if (!device) {
-        console.error(`${clrError('No paired device.')} Run ${bold('gipity claude')} to pair this machine.`);
+        console.error(`${clrError('No paired device.')} Run ${bold('gipity connect')} to pair this machine.`);
         process.exit(1);
     }
     return device;

package/dist/commands/relay.js

@@ -121,7 +121,7 @@ relayCommand
         return;
     }
     if (!s.device) {
-        console.log(`${muted('No paired device.')} Run ${brand('gipity claude')} to pair this machine.`);
+        console.log(`${muted('No paired device.')} Run ${brand('gipity connect')} to pair this machine.`);
         return;
     }
     console.log(`${bold('Device:')}      ${brand(s.device.name)} ${muted(`(${s.device.guid})`)}`);
@@ -380,7 +380,7 @@ registerInstallCommands(relayCommand);
 function requirePaired() {
     const device = state.getDevice();
     if (!device) {
-        console.error(`${clrError('No paired device.')} Run ${brand('gipity claude')} to pair this machine.`);
+        console.error(`${clrError('No paired device.')} Run ${brand('gipity connect')} to pair this machine.`);
         process.exit(1);
     }
     return device;