gipity 1.0.392 → 1.0.394

package/dist/commands/agent.js

@@ -68,12 +68,103 @@ agentCommand
     else if (field === 'temp' || field === 'temperature')
         body.temperature = parseFloat(value);
     else {
-        console.error(clrError(`Unknown field: ${field}. Use: model, temp`));
+        console.error(clrError(`Unknown field: ${field}. Use: model, temp (for soul/goal use \`gipity agent soul|goal\`)`));
         process.exit(1);
     }
     await put(`/agents/${config.agentGuid}`, body);
     printResult(`Set ${field} = ${value}`, opts, { success: true, field, value });
 }));
+/** The active agent's guid, or a clear error - the brain commands all need one. */
+function requireAgentGuid() {
+    const config = requireConfig();
+    if (!config.agentGuid) {
+        console.error(clrError('No active agent. Switch to one with: gipity agent <name>'));
+        process.exit(1);
+    }
+    return config.agentGuid;
+}
+// --- Brain: soul / goal / rules / learn ---
+// These hit the account-scoped /account/agents surface (the same dual-auth,
+// app-callable routes a deployed app uses), so the CLI, the web terminal, and an
+// app all drive the agent's brain through one set of endpoints. No more
+// hand-rolled `curl -X PUT a.gipity.ai/agents/:guid/soul` with a scraped token.
+agentCommand
+    .command('soul [text...]')
+    .description("Show the current agent's soul, or set it (its voice/personality)")
+    .option('--json', 'Output as JSON')
+    .action((text, opts) => run('Soul', async () => {
+    const guid = requireAgentGuid();
+    if (text && text.length) {
+        const content = text.join(' ');
+        const res = await put(`/account/agents/${guid}/soul`, { content });
+        printResult('Soul updated.', opts, res.data);
+    }
+    else {
+        const res = await get(`/account/agents/${guid}/soul`);
+        printResult(res.data.content || '(no soul set)', opts, res.data);
+    }
+}));
+agentCommand
+    .command('goal [text...]')
+    .description("Show the current agent's goal, or set it")
+    .option('--clear', 'Clear the goal (back to a plain assistant)')
+    .option('--json', 'Output as JSON')
+    .action((text, opts) => run('Goal', async () => {
+    const guid = requireAgentGuid();
+    if (opts.clear) {
+        const res = await put(`/account/agents/${guid}/goal`, { goal: null });
+        printResult('Goal cleared.', opts, res.data);
+    }
+    else if (text && text.length) {
+        const goal = text.join(' ');
+        const res = await put(`/account/agents/${guid}/goal`, { goal });
+        printResult('Goal updated.', opts, res.data);
+    }
+    else {
+        const res = await get(`/account/agents/${guid}/goal`);
+        printResult(res.data.goal || '(no goal set)', opts, res.data);
+    }
+}));
+const rulesCommand = agentCommand
+    .command('rules')
+    .description("Show the agent's rules playbook (manual + learned)")
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Rules', async () => {
+    const guid = requireAgentGuid();
+    const res = await get(`/account/agents/${guid}/rules`);
+    printList(res.data, opts, 'No rules yet.', r => `[${r.source}]  ${r.short_guid}  ${r.text}`);
+}));
+rulesCommand
+    .command('add <text...>')
+    .description('Add a manual rule')
+    .option('--json', 'Output as JSON')
+    .action((text, opts) => run('Add', async () => {
+    const guid = requireAgentGuid();
+    const res = await post(`/account/agents/${guid}/rules`, { text: text.join(' ') });
+    printResult(`Added rule ${res.data[0].short_guid}.`, opts, res.data[0]);
+}));
+rulesCommand
+    .command('rm <rule-guid>')
+    .alias('delete')
+    .description('Deactivate a rule by its guid')
+    .option('--json', 'Output as JSON')
+    .action((ruleGuid, opts) => run('Remove', async () => {
+    const guid = requireAgentGuid();
+    await del(`/account/agents/${guid}/rules/${ruleGuid}`);
+    printResult(`Removed rule ${ruleGuid}.`, opts, { removed: ruleGuid });
+}));
+agentCommand
+    .command('learn')
+    .description("Teach the agent from one correction (distills a durable learned rule)")
+    .requiredOption('--original <text>', 'What the agent originally produced')
+    .requiredOption('--comment <text>', "Your correction / why it was wrong")
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Learn', async () => {
+    const guid = requireAgentGuid();
+    const res = await post(`/account/agents/${guid}/learn`, { original: opts.original, comment: opts.comment });
+    const d = res.data;
+    printResult(d.saved ? `Learned: ${d.rule.text}` : `No rule saved (${d.reason || 'too idiosyncratic to generalize'}).`, opts, d);
+}));
 agentCommand
     .command('rename <new-name>')
     .description('Rename the current agent')

package/dist/commands/db.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { get, post, sendMessage } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, success } from '../colors.js';
-import { run, printList } from '../helpers/index.js';
+import { run, printList, emitField } from '../helpers/index.js';
 import { confirm } from '../utils.js';
 export const dbCommand = new Command('db')
     .description('Manage databases');
@@ -10,6 +10,7 @@ dbCommand
     .command('query <sql>')
     .description('Run SQL')
     .option('--database <name>', 'Database name')
+    .option('--field <path>', 'Print only this field of the result (dot path, e.g. rows.0.status)')
     .option('--json', 'Output as JSON')
     .action((sql, opts) => run('Query', async () => {
     const config = requireConfig();
@@ -24,7 +25,10 @@ dbCommand
         dbName = listRes.data[0].friendlyName;
     }
     const res = await post(`/projects/${config.projectGuid}/db/query`, { sql, database: dbName });
-    if (opts.json) {
+    if (opts.field) {
+        emitField(res.data, opts.field);
+    }
+    else if (opts.json) {
         console.log(JSON.stringify(res.data));
     }
     else {

package/dist/commands/fn.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { get, post, del } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, bold, muted, success } from '../colors.js';
-import { run, printList } from '../helpers/index.js';
+import { run, printList, emitField } from '../helpers/index.js';
 import { confirm } from '../utils.js';
 export const fnCommand = new Command('fn')
     .description('Manage functions');
@@ -38,12 +38,17 @@ fnCommand
     .command('call <name> [body]')
     .description('Call a function')
     .option('--data <json>', 'JSON request body')
+    .option('--field <path>', 'Print only this field of the result (dot path, e.g. items.0.short_guid)')
     .option('--json', 'Output as JSON')
     .action((name, bodyArg, opts) => run('Call', async () => {
     const config = requireConfig();
     const raw = bodyArg || opts.data || '{}';
     const body = JSON.parse(raw);
     const res = await post(`/api/${config.projectGuid}/fn/${encodeURIComponent(name)}`, body);
+    if (opts.field) {
+        emitField(res.data, opts.field);
+        return;
+    }
     console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
 }));
 fnCommand

package/dist/commands/page-eval.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { post, get, ApiError } from '../api.js';
 import { brand, bold, muted, warning } from '../colors.js';
 import { run } from '../helpers/index.js';
@@ -122,6 +122,13 @@ export function evalExecTimeoutMessage(result) {
         `and cannot extend it. Split a long interactive check into several shorter 'page eval' calls (e.g. ` +
         `one per state to verify), keeping each body's in-page waits well under ${EVAL_EXEC_BUDGET_MS / 1000}s.`);
 }
+// Agents instinctively reach for a flag to pass the script (`--js`, `--script`,
+// `--code`, …); the JS is actually the positional <expr> (or --file for a saved
+// script). Without these, commander answers `--js` with "did you mean --json?" —
+// 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'];
 // 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
@@ -143,6 +150,13 @@ export const pageEvalCommand = new Command('eval')
     .option('--wait-timeout <ms>', 'Max ms to wait for --wait-for before giving up', '5000')
     .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
+    // positional <expr> precisely, before the inline/--file shape checks fire.
+    const decoy = JS_DECOY_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
+    if (decoy) {
+        pageEvalCommand.error(`error: ${decoy} is not a flag — pass the JavaScript as the positional <expr> argument ` +
+            `(or --file <path> for a saved script), e.g. gipity page eval "<url>" 'document.title'`);
+    }
     // Arg-shape errors go through commander's error() so the enableHelpAfterError
     // hook renders this command's help inline with the one-line error LAST
     // (survives `| tail`), same as commander-detected errors like a missing url.
@@ -225,6 +239,11 @@ export const pageEvalCommand = new Command('eval')
         }
     }
 }));
+// Register the JS-intent flag guesses as hidden decoys (take a value so they
+// swallow the script the agent passed) — the action turns any of them into the
+// precise "JS is the positional arg" redirect above.
+for (const f of JS_DECOY_FLAGS)
+    pageEvalCommand.addOption(new Option(`${f} <value>`).hideHelp());
 // 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-

package/dist/commands/page-inspect.js

@@ -62,6 +62,40 @@ export const pageInspectCommand = new Command('inspect')
         };
         const res = await post(`/tools/browser/inspect`, inspectBody);
         const b = res.data;
+        // ── Strip the platform's own instrumentation noise first ──
+        // Every deployed page loads Gipity's injected analytics SDK, which POSTs to
+        // Gipity's traffic/error log endpoints (`/api/<guid>/log/traffic|error`).
+        // Those are platform infrastructure, not the app's resources, so when one
+        // fails it surfaces as a failed resource on the Gipity host PLUS a generic,
+        // URL-less "Failed to load resource" console error — identical noise on
+        // essentially every deployed app. Drop both so an agent inspecting the app
+        // it just built sees only its own code's resources, not the platform's.
+        const isPlatformLog = (entry) => {
+            const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
+            try {
+                const u = new URL(urlPart);
+                return /(^|\.)gipity\.ai$/.test(u.hostname) && /\/log\/(traffic|error)$/.test(u.pathname);
+            }
+            catch {
+                return false;
+            }
+        };
+        const platformFailures = (b.failedResources || []).filter(isPlatformLog);
+        b.failedResources = (b.failedResources || []).filter((r) => !isPlatformLog(r));
+        // Each failed platform POST also emits exactly one generic, URL-less
+        // "Failed to load resource" console error. Drop one per platform failure —
+        // the text is identical, so removing by count is exact and any genuine app
+        // 404 keeps its own (indistinguishable) line.
+        let platformConsoleToDrop = platformFailures.length;
+        if (platformConsoleToDrop > 0) {
+            b.console = (b.console || []).filter((l) => {
+                if (platformConsoleToDrop > 0 && /^error:\s*Failed to load resource:/i.test(l)) {
+                    platformConsoleToDrop--;
+                    return false;
+                }
+                return true;
+            });
+        }
         // Pull message-less cross-origin "Script error." lines out first. They carry
         // no source/stack, so they're never actionable as app-code defects, and on a
         // Gipity-deployed page the platform's own injected SDK is itself a

package/dist/commands/page-screenshot.js

@@ -100,6 +100,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     // so the `?? opts.wait` merge below would never see the --wait alias. Default
     // is applied in the merge instead.
     .option('--post-load-delay <ms>', 'Delay after DOMContentLoaded before capture, in ms (default: 1000)')
+    .option('--action <js>', 'Run JS in the page before capturing — e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs after the post-load delay, then settles again before the shot.')
     .option('--full', 'Capture the full scrollable page (default: viewport only)')
     .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
     .option('--device <names>', `Viewport preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag)`, appendOption, [])
@@ -140,6 +141,7 @@ export const pageScreenshotCommand = new Command('screenshot')
         reloadBetween: opts.reloadBetween !== false,
         ...(userSpecifiedViewports ? { viewports: customViewports } : {}),
         ...(opts.fakeMedia ? { fakeMedia: true } : {}),
+        ...(opts.action ? { action: opts.action } : {}),
     };
     const entries = await postForTarEntries('/tools/browser/screenshot', body);
     const metaEntry = entries.find((e) => e.name === 'meta.json');
@@ -231,23 +233,26 @@ export const pageScreenshotCommand = new Command('screenshot')
         console.log(`${label('Screenshot file')} ${success(savedFiles[i])}`);
     }
 }));
-// `screenshot` captures the page AS IT LOADS — there is no flag to scroll, click,
-// run a script, or wait for a selector before capture (agents reach for --eval/
-// --script/--scroll/--selector and get an unknown-option detour). State this
-// limitation and the two supported alternatives right here, so the help (rendered
-// on any bad flag, and this 'after' block survives `| tail`/`| grep`) ends the
-// hunt in one shot instead of sending the agent grepping `--help` for
-// scroll/script/before/action. The real per-element capture lives server-side and
-// isn't wired yet — until then, --full + crop or `page eval` cover the need.
+// `screenshot` captures the page AFTER load + settle (+ optional --action). It does
+// NOT scroll or wait for a selector before capture (agents reach for --scroll/
+// --selector and get an unknown-option detour). State the supported levers right
+// here, so the help (rendered on any bad flag, and this 'after' block survives
+// `| tail`/`| grep`) ends the hunt in one shot. --action covers "click, then shoot";
+// --full + crop covers off-screen regions; `page eval` reads data without a picture.
 pageScreenshotCommand.addHelpText('after', `
 Examples:
   gipity page screenshot "https://dev.gipity.ai/me/app/"
   gipity page screenshot "https://dev.gipity.ai/me/app/" --full          # whole scrollable page
   gipity page screenshot "https://dev.gipity.ai/me/app/" --device mobile,desktop
+  gipity page screenshot "https://dev.gipity.ai/me/app/" \\
+    --action "document.getElementById('play').click()"                   # capture an in-game frame
 
-Capturing a specific state (a slide, an off-screen element, a post-scroll view)?
-  screenshot captures the page as it loads — it does NOT scroll, click, wait for a
-  selector, or run a script before capture. To get the part you want:
+Capturing a state that needs an interaction (start a game, open a menu, dismiss a modal)?
+  Use --action to run JS in the page before the shot — it fires after the post-load
+  delay, then settles again so the result has painted. Do NOT hand-roll a 'page eval'
+  that returns a base64 image: the eval result is capped (~16KB) and truncates the PNG.
+
+Capturing an off-screen region or reading element data?
     • --full captures the ENTIRE scrollable page (then crop to the region).
     • 'gipity page eval <url> "<expr>"' reads any (even off-screen) element's
       data/state/rect without a picture — e.g. read the chart's bar values

package/dist/commands/sandbox.js

@@ -150,6 +150,17 @@ GCC/Rust).
     }
     const timeout = parseInt(opts.timeout, 10);
     const cwd = resolveRelativeCwd();
+    // Push local working-tree changes up before executing. The sandbox mirrors
+    // the *server* (VFS), not the local cwd, so any input staged outside Claude's
+    // Write/Edit auto-push hook - a Bash `cp`/`ffmpeg`/redirect, or any external
+    // process - would otherwise be invisible to the run and the first invocation
+    // would silently miss its inputs. Syncing first makes the auto-mirror reflect
+    // local state regardless of how files got there ("no manual copy needed").
+    // Bidirectional + CAS, so it's a cheap manifest check when nothing changed.
+    // Symmetric with the post-run pull below. Skip in one-off mode (no project).
+    if (getConfigPath()) {
+        await sync({ interactive: false });
+    }
     const res = await post(`/projects/${config.projectGuid}/sandbox/execute`, {
         code: source,
         language,

package/dist/helpers/index.js

@@ -2,6 +2,6 @@
  * CLI helpers - shared patterns across all commands.
  */
 export { run } from './command.js';
-export { printOutput, printList, printResult } from './output.js';
+export { printOutput, printList, printResult, pluckField, emitField } from './output.js';
 export { syncBeforeAction } from './sync.js';
 //# sourceMappingURL=index.js.map

package/dist/helpers/output.js

@@ -63,6 +63,29 @@ export function printResult(text, opts, jsonData) {
     }
     console.log(text);
 }
+/**
+ * Pluck a nested value out of a result by dot-path. Numeric segments index into
+ * arrays, so `items.0.short_guid` reaches the first item's guid. Returns
+ * `undefined` if any segment along the way is missing. This is what lets
+ * `--field` replace the `... | node -e "JSON.parse(...)"` extraction dance.
+ */
+export function pluckField(data, path) {
+    return path.split('.').reduce((acc, key) => (acc == null ? undefined : acc[key]), data);
+}
+/**
+ * Emit a single plucked field for `--field`. Scalars print raw (no quotes) so
+ * the output drops straight into `$(...)` / pipes; objects/arrays print as
+ * compact JSON. A missing path is an error (exit 1) so scripts fail loudly
+ * instead of silently consuming an empty string.
+ */
+export function emitField(data, path) {
+    const value = pluckField(data, path);
+    if (value === undefined) {
+        console.error(`Field not found: ${path}`);
+        process.exit(1);
+    }
+    console.log(typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value));
+}
 /**
  * Print a list with JSON mode, empty state, and per-item formatting.
  * Replaces the most common output pattern across all commands.

package/dist/knowledge.js

@@ -20,6 +20,7 @@ Templates:
     - \`3d-world\` - Multiplayer world, 3D sandbox, shooter, exploration, virtual showroom (Three.js + Rapier + Colyseus)
     - \`api\` - Backend service, webhook, data pipeline, chatbot, cron job - no frontend
     - \`karaoke-captions\` - Forced-alignment app - karaoke captions, subtitle timing, language learning, dubbing alignment
+    - \`outreach-agent\` - AI outreach / drip-email funnel - reach a list of people with personalized, human-approved emails that auto-send on a schedule and a self-improving agent that learns from your edits
 When unsure, default to \`web-simple\`. After adding the template, edit the generated files, then \`gipity deploy dev\`.
 Only skip this on a build request if the user explicitly says not to.
 
@@ -36,7 +37,8 @@ Kits are reusable building blocks added to an existing app, not whole templates
     - \`gipity add i18n\` - Multi-language for web apps - language picker, locale persistence, RTL, plural/translation lookup. Scaffolds src/js/strings.js and wires it up; move your copy there and read it with t('key'). Web only.
     - \`gipity add records\` - Registry-driven records: declare objects/fields as data, get generic CRUD functions with validation, full-text search, soft delete, ACTOR provenance, and an audit event spine - every write is transactional (row + event). Field types include relations ({id,label}), currency, emails/phones/links composites. Ships backend functions + migrations. Needs a database (web-fullstack/api template).
     - \`gipity add views\` - Generic UI over records-kit objects: sortable/filterable table with full-text search, create/edit/delete forms with type-appropriate widgets, kanban board with drag-to-update. Renders entirely from the field registry - zero per-object UI code. Requires the records kit.
-    - \`gipity add agent-api\` - Make your app agent-operable: named API keys (kit_api_keys) let agents and scripts write through the records kit's single write path with AGENT/API actor attribution - machine writes land on the same audit spine as human edits. Requires the records kit.`;
+    - \`gipity add agent-api\` - Make your app agent-operable: named API keys (kit_api_keys) let agents and scripts write through the records kit's single write path with AGENT/API actor attribution - machine writes land on the same audit spine as human edits. Requires the records kit.
+    - \`gipity add contacts\` - Source-agnostic contact data layer for lead-gen/CRM apps: import people from LinkedIn CSV + Gmail + pasted lists, resolve duplicates into one person while keeping EVERY value from every source with provenance (multi-valued attributes, never overwrites). Exact email/URL auto-merge; fuzzy name+company goes to a human merge-review queue (reversible). Re-imports detect job changes and emit signals. User-definable tags, full-text search, and a transactional event spine. Ships backend functions + migrations. Needs a database (web-fullstack/api template).`;
 export const SKILLS_CONTENT = `# Gipity Integration
 
 Gipity is the cloud platform your project runs on - hosting, databases, deployment, file storage, code execution, workflows, and monitoring. Gip is the cloud agent that runs on Gipity.
@@ -45,7 +47,7 @@ Prefer the cheapest option that works - CLI and sandbox are instant and free, ap
 
 1. CLI commands (fast, no agent overhead). The \`gipity\` CLI covers add, deploy, db, fn, logs, browser, sync, memory, skill, and more. All commands support \`--json\`.
 2. Cloud sandbox via \`gipity sandbox run\` - Docker container with pre-installed tools for media (ffmpeg, ImageMagick, sox), documents (pandoc, LibreOffice), and data (pandas, matplotlib, sqlite3). Run \`gipity skill read sandbox-tools\` for the full toolkit. No network from inside the sandbox - fetch what you need before sending it in.
-3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location. Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|music>\` or \`gipity chat\`. \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) — pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
+3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location. Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|music>\` or \`gipity chat\`. \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) - pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
 4. Delegate to Gip (\`gipity chat "<task>"\`) - only when the work genuinely needs agent reasoning or a tool not in the CLI, sandbox, or app services. Required for: Twitter/X search, Gmail, calendar, push notifications, video understanding, audio source isolation, cross-model second opinions, multi-step orchestration. Don't use \`gipity chat\` for anything the sandbox can do - it's slower and burns tokens.
 
 You are the developer. Write files in this directory - the Gipity Claude Code plugin's hooks auto-sync them to Gipity. Don't run \`npm install\`, \`npm start\`, \`node\`, or \`python\` locally; there is no local runtime. Code runs in the Gipity sandbox.
@@ -78,21 +80,32 @@ The full "when to add a template" rule and the definition of done are spelled ou
 
 Build loop: \`gipity add\` → edit files → \`gipity deploy dev\` → \`gipity page inspect <url>\` → fix any errors → repeat until the definition of done is met.
 
-\`add\` writes real files to disk — Read a scaffolded file before your first Write/Edit to it, or the call fails \`"File has not been read yet"\`. Don't rewrite from memory of the template.
+\`add\` writes real files to disk - Read a scaffolded file before your first Write/Edit to it, or the call fails \`"File has not been read yet"\`. Don't rewrite from memory of the template.
 
 Make your file changes and verify they landed, then run \`gipity deploy dev\` once. \`0 uploaded, N unchanged\` means nothing changed on disk - fix the files, don't re-run deploy or probe the environment.
 
 Before telling the user the app is online, verify the source tree is consistent: no files named like \`* (conflict from *)*\`, and every package directory has its expected canonical entry file. If a conflict artifact exists, resolve it (keep one copy), re-deploy, and re-inspect before reporting done.
 
+## Work on an existing project that isn't local yet
+
+If you're pointed at a project that already exists on Gipity but has no local copy - e.g. the user gives a live URL \`https://dev.gipity.ai/<account>/<slug>/\` (or \`app.gipity.ai\` for prod) and you need its files to edit them - the last path segment is the project **slug**. Pull it down by adopting it into a directory named for the slug:
+
+\`\`\`
+mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <slug>
+\`\`\`
+
+\`init\` matches the existing remote project by slug, links this directory to it, and syncs its files down (you'll see \`Found existing project ...\` and \`Synced N changes\`). There's no separate \`clone\`/\`pull\` - \`init\` against a matching slug *is* the pull. After it finishes, the files are in cwd; edit and \`gipity deploy dev\` as usual. (Already linked to a different project in this dir? Switch and pull instead: \`gipity project <slug>\` then \`gipity sync\`. List your projects with \`gipity project --json\`.)
+
 ## CLI quick reference
 
 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>\`.
+Pull an existing remote project local (given its URL/slug): \`mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <slug>\` (adopts the matching project and syncs files down - this is the "clone").
 For deterministic text questions (letter/word counts, substring occurrences, nth word/char, anagrams), use \`gipity text analyze "<text>"\` - local and instant, no sandbox or LLM needed.
 Run \`gipity --help\` for the full list. Use \`--help\` on any command for details.
 
-Function return shape: \`gipity fn call\`, the in-test \`ctx.fn.call\`/\`callAs\`, and the client \`Gipity.fn\` all return your function's value **unwrapped** — read/assert \`result.field\`. Only raw HTTP/\`curl\` wraps it as \`{ data: ... }\`; never write \`result.data.field\` in a test.
+Function return shape: \`gipity fn call\`, the in-test \`ctx.fn.call\`/\`callAs\`, and the client \`Gipity.fn\` all return your function's value **unwrapped** - read/assert \`result.field\`. Only raw HTTP/\`curl\` wraps it as \`{ data: ... }\`; never write \`result.data.field\` in a test.
 
-Tests write to your real DB: \`gipity test\` runs the test code sandboxed, but \`ctx.fn.call\`/\`callAs\` hit your actual deployed functions, which write to the same project database the app reads from — rows a test creates persist and surface on the live page. Register \`ctx.cleanup(fn)\` in any write-test to delete what it made; the harness runs every cleanup after the suite (even on failure).
+Tests write to your real DB: \`gipity test\` runs the test code sandboxed, but \`ctx.fn.call\`/\`callAs\` hit your actual deployed functions, which write to the same project database the app reads from - rows a test creates persist and surface on the live page. Register \`ctx.cleanup(fn)\` in any write-test to delete what it made; the harness runs every cleanup after the suite (even on failure).
 
 ## Tool output is complete and synchronous
 

package/dist/relay/state.js

@@ -1,7 +1,7 @@
 /**
  * Local state for `gipity relay`.
  *
- * One file, `~/.gipity/relay.json`, mode 0600:
+ * One file, `$GIPITY_DIR/relay.json` (default `~/.gipity/relay.json`), mode 0600:
  *   {
  *     device: { guid, name, platform, token, paired_at },
  *     // (no allowlist - daemon materializes any of the user's projects on demand)
@@ -16,7 +16,13 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
-const RELAY_DIR = join(homedir(), '.gipity');
+// GIPITY_DIR scopes the relay/device state the same way it scopes auth.json (see
+// auth.ts). Without this, a separate auth context (e.g. GIPITY_DIR=~/.giprunner-prod
+// logged in as ec-giprunner@914-6.com) would still read the DEFAULT ~/.gipity device —
+// which is paired to a DIFFERENT account — and project/chat creation fails with
+// "deviceGuid does not match a paired device". Scoping it lets each auth context pair
+// and own its own device. Unset GIPITY_DIR → ~/.gipity, unchanged for normal users.
+const RELAY_DIR = process.env.GIPITY_DIR || join(homedir(), '.gipity');
 const RELAY_FILE = join(RELAY_DIR, 'relay.json');
 const FILE_MODE = 0o600;
 function emptyState() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.392",
+  "version": "1.0.394",
   "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",