gipity 1.0.428 → 1.1.1

package/dist/relay/media-upload.js

@@ -0,0 +1,184 @@
+/**
+ * Transcript image rewrite — the relay's "no inline base64" chokepoint.
+ *
+ * Claude Code's `Read` of an image file (screenshots, generated art, …)
+ * returns the bytes as a `{type:'image', source:{type:'base64', data}}`
+ * block inside the tool_result. Shipping that through ingest bloats the
+ * transcript DB and, worse, blows the server's 200 KB per-entry cap so
+ * real screenshots silently never reach the web client at all.
+ *
+ * `ImageBlockRewriter` sits in front of the ingest POST: it uploads each
+ * base64 image block's bytes to `POST /remote-sessions/:convGuid/media`
+ * (raw binary body) and swaps the block for a small `image_ref` pointing
+ * at the stored VFS file. The server dedups by content hash — a `Read` of
+ * an already-synced screenshot references the existing node.
+ *
+ * Failure handling: an upload that fails leaves small images inline
+ * (status-quo rendering still works) but replaces oversize ones with a
+ * text stub so one bad image can't poison the whole ingest batch. The
+ * IngestQueue retries a failed batch through this rewriter again, and the
+ * server's content-addressed storage makes replayed uploads idempotent.
+ */
+import path from 'path';
+import { deviceFetchBinary } from './device-http.js';
+/** Below this the upload round-trip outweighs the base64: tiny images
+ *  (icons, favicons) stay inline. */
+const MIN_UPLOAD_BYTES = 4 * 1024;
+/** Server-side cap (TRANSCRIPT_MEDIA_MAX_BYTES). Larger images can't be
+ *  stored; they get stubbed rather than shipped. */
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+/** Base64 payloads above this would break the server's 200 KB tool_result
+ *  cap if left inline — when the upload fails, stub instead of poisoning
+ *  the batch. Leaves headroom for the rest of the tool_result JSON. */
+const INLINE_SAFE_B64_CHARS = 120_000;
+/** How many tool_use → file_path pairs to remember for captioning/dedup. */
+const PATH_MAP_CAP = 500;
+/** Default uploader: raw-binary POST to the transcript-media endpoint. */
+export const uploadViaDevice = async (convGuid, buf, opts) => {
+    const qs = new URLSearchParams({ filename: opts.filename, media_type: opts.mediaType });
+    if (opts.suggestedPath)
+        qs.set('suggested_path', opts.suggestedPath);
+    const res = await deviceFetchBinary('POST', `/remote-sessions/${encodeURIComponent(convGuid)}/media?${qs.toString()}`, buf, opts.mediaType, 30_000);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`HTTP ${res.status} ${body.slice(0, 120)}`);
+    }
+    const json = await res.json();
+    return json.data;
+};
+function extForMime(mime) {
+    switch (mime) {
+        case 'image/jpeg': return '.jpg';
+        case 'image/gif': return '.gif';
+        case 'image/webp': return '.webp';
+        case 'image/svg+xml': return '.svg';
+        default: return '.png';
+    }
+}
+function isBase64ImageBlock(b) {
+    return b?.type === 'image'
+        && b.source?.type === 'base64'
+        && typeof b.source.data === 'string'
+        && b.source.data.length > 0;
+}
+export class ImageBlockRewriter {
+    convGuid;
+    onWarn;
+    upload;
+    /** tool_use_id → the file_path the tool was asked to read (for naming +
+     *  server-side dedup against the synced node at that path). */
+    pathsByToolUseId = new Map();
+    /** Project root on this machine, once the dispatch resolves it — lets an
+     *  absolute Read path map to its project-relative VFS path. */
+    cwd = null;
+    constructor(convGuid, onWarn, upload = uploadViaDevice) {
+        this.convGuid = convGuid;
+        this.onWarn = onWarn;
+        this.upload = upload;
+    }
+    setCwd(cwd) {
+        this.cwd = cwd;
+    }
+    /** Rewrite every base64 image block in the batch to an image_ref. Never
+     *  throws — per-image failures degrade per the policy above. */
+    async rewrite(entries) {
+        const out = [];
+        for (const entry of entries) {
+            if (entry.kind === 'tool_use') {
+                this.recordToolPath(entry);
+                out.push(entry);
+                continue;
+            }
+            if (entry.kind !== 'tool_result' || !Array.isArray(entry.content) || typeof entry.tool_use_id !== 'string') {
+                out.push(entry);
+                continue;
+            }
+            const blocks = [];
+            for (const block of entry.content) {
+                blocks.push(isBase64ImageBlock(block)
+                    ? await this.rewriteBlock(block, entry.tool_use_id)
+                    : block);
+            }
+            out.push({ ...entry, content: blocks });
+        }
+        return out;
+    }
+    recordToolPath(entry) {
+        if (typeof entry.tool_use_id !== 'string')
+            return;
+        const input = entry.tool_input;
+        const p = input && typeof input === 'object'
+            ? (input.file_path ?? input.path ?? input.notebook_path)
+            : undefined;
+        if (typeof p !== 'string' || !p)
+            return;
+        if (this.pathsByToolUseId.size >= PATH_MAP_CAP) {
+            const oldest = this.pathsByToolUseId.keys().next().value;
+            if (oldest !== undefined)
+                this.pathsByToolUseId.delete(oldest);
+        }
+        this.pathsByToolUseId.set(entry.tool_use_id, p);
+    }
+    async rewriteBlock(block, toolUseId) {
+        const b64 = block.source.data;
+        let buf;
+        try {
+            buf = Buffer.from(b64, 'base64');
+        }
+        catch {
+            return block; // not decodable — leave as-is
+        }
+        if (buf.length < MIN_UPLOAD_BYTES)
+            return block;
+        const mediaType = block.source.media_type || 'image/png';
+        const sourcePath = this.pathsByToolUseId.get(toolUseId);
+        const filename = sourcePath ? path.basename(sourcePath) : `image${extForMime(mediaType)}`;
+        const suggested = this.projectRelative(sourcePath);
+        if (buf.length > MAX_UPLOAD_BYTES) {
+            this.onWarn?.('transcript image exceeds upload cap - stubbed', { bytes: buf.length, filename });
+            return this.stub(filename, buf.length, 'too large to store');
+        }
+        try {
+            const ref = await this.upload(this.convGuid, buf, {
+                filename, mediaType, ...(suggested ? { suggestedPath: suggested } : {}),
+            });
+            return {
+                type: 'image_ref',
+                url: ref.url,
+                ...(ref.thumb_url ? { thumb_url: ref.thumb_url } : {}),
+                media_type: mediaType,
+                path: ref.path,
+                ...(ref.width != null ? { width: ref.width } : {}),
+                ...(ref.height != null ? { height: ref.height } : {}),
+                bytes: ref.bytes,
+            };
+        }
+        catch (err) {
+            this.onWarn?.('transcript image upload failed', { filename, err: err?.message });
+            // Small enough to survive the ingest cap inline → keep the original
+            // (renders exactly as before this feature). Oversize → stub, because
+            // shipping it would 400 the entire batch and lose sibling entries.
+            if (b64.length <= INLINE_SAFE_B64_CHARS)
+                return block;
+            return this.stub(filename, buf.length, `upload failed: ${err?.message || 'unknown error'}`);
+        }
+    }
+    stub(filename, bytes, reason) {
+        return {
+            type: 'text',
+            text: `[image ${filename} (${Math.round(bytes / 1024)} KB) omitted: ${reason}]`,
+        };
+    }
+    /** Map an absolute local path to its project-relative VFS path, when it
+     *  falls inside the dispatch's project root. */
+    projectRelative(p) {
+        if (!p || !this.cwd)
+            return undefined;
+        const abs = path.resolve(p);
+        const root = path.resolve(this.cwd);
+        if (!abs.startsWith(root + path.sep))
+            return undefined;
+        return abs.slice(root.length + 1).split(path.sep).join('/');
+    }
+}
+//# sourceMappingURL=media-upload.js.map

package/dist/relay/onboarding.js

@@ -129,7 +129,7 @@ export async function runRelaySetup(opts) {
         return false;
     }
     // Start the daemon for this session.
-    const startNow = await confirm('  Start the relay now (and on future `gipity claude` runs)?', { default: 'yes' });
+    const startNow = await confirm('  Start the relay now (and on future `gipity build` runs)?', { default: 'yes' });
     if (startNow) {
         startDaemon();
     }
@@ -145,7 +145,7 @@ export async function runRelaySetup(opts) {
                     // generic non-zero. The relay itself is unaffected (it's already
                     // running this session, and `gipity claude` restarts it).
                     console.log(`  ${muted('Auto-start needs systemd, which this WSL distro has off. The relay still runs -')}`);
-                    console.log(`  ${muted('it started just now and `gipity claude` restarts it. For boot-time auto-start:')}`);
+                    console.log(`  ${muted('it started just now and `gipity build` restarts it. For boot-time auto-start:')}`);
                     console.log(`  ${muted('add [boot] systemd=true to /etc/wsl.conf, restart WSL, then run')} ${brand('gipity relay install')}${muted('.')}`);
                 }
                 else {

package/dist/setup.js

@@ -2,10 +2,11 @@
  * Shared project setup helpers used by both `init` and `claude`.
  */
 import { resolve, join, dirname } from 'path';
-import { homedir } from 'os';
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, mkdtempSync, rmSync, cpSync, readdirSync } from 'fs';
 import { resolveCommand, spawnSyncCommand } from './platform.js';
 import { SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE } from './knowledge.js';
+import { DEFAULT_API_BASE, resolveApiBase } from './config.js';
 export { SKILLS_CONTENT };
 /** Canonical list of workstation artifacts that are NOT part of the project.
  *  Used as the single source of truth for three separate decisions:
@@ -30,6 +31,7 @@ export { SKILLS_CONTENT };
 export const PRIMER_FILES = {
     claude: 'CLAUDE.md',
     codex: 'AGENTS.md',
+    grok: 'AGENTS.md', // Grok Build reads the AGENTS.md family (and CLAUDE.md) natively
     aider: 'AGENTS.md', // shares the Codex primer; aider is pointed at it via .aider.conf.yml
     gemini: 'GEMINI.md',
     copilot: '.github/copilot-instructions.md',
@@ -50,10 +52,13 @@ export const AIDER_CONF_FILE = '.aider.conf.yml';
  *  scratch (the `_vsd_tmp/`/`_convert_tmp/` dirs that bloated past deploys)
  *  can't leak in either. Reference material to KEEP (diagrams, decks, ADRs) goes
  *  in `docs/` instead - synced and versioned, but outside `src/` so it's never
- *  deployed. Gitignore-glob form, matched by the `ignore` package in config.ts. */
+ *  deployed. Build screenshots follow the same keep-but-don't-deploy pattern in
+ *  `screenshots/` (page-screenshot.ts writes there; the server excludes both
+ *  dirs from root deploys in s3-deploy.ts). Gitignore-glob form, matched by the
+ *  `ignore` package in config.ts. */
 export const SCRATCH_IGNORE = ['tmp/', '.tmp/', '*_tmp/', '.gipityscratch/'];
 export const DEFAULT_SYNC_IGNORE = [
-    'node_modules', '.git', '.gipity.json', '.gipity/', '.claude/', '.gitignore', AIDER_CONF_FILE,
+    'node_modules', '.git', '.gipity.json', '.gipity/', '.claude/', '.codex/', '.gitignore', AIDER_CONF_FILE,
     // Home-directory junk: a project created inside a real home dir (or one that
     // shells out) sweeps in a cache dir + shell dotfiles that are never app
     // files. `.cache/` alone can be gigabytes (it was 2.4 GB on one project),
@@ -145,7 +150,7 @@ export const LEGACY_MARKETPLACE_REPO = 'GipityAI/claude-plugin';
 // an installed plugin when the marketplace advances - only an explicit
 // `plugin install`/`update` does - so this constant is how a CLI upgrade tells
 // ensureGipityPluginInstalled() to refresh a stale user-scope install.
-export const GIPITY_PLUGIN_VERSION = '0.5.0';
+export const GIPITY_PLUGIN_VERSION = '0.7.0';
 /** True for hook commands the CLI itself wrote into settings.json in past
  *  versions. Matched by signature so migration strips exactly our own
  *  entries and never touches user-authored hooks. */
@@ -277,8 +282,8 @@ export function userScopeInstallState() {
 export function userScopePluginCurrent() {
     return userScopeInstallState().current;
 }
-function claudeOnPath() {
-    const probe = spawnSyncCommand(process.platform === 'win32' ? 'where' : 'which', ['claude'], {
+export function binaryOnPath(bin) {
+    const probe = spawnSyncCommand(process.platform === 'win32' ? 'where' : 'which', [bin], {
         encoding: 'utf-8',
     });
     return probe.status === 0 && !!probe.stdout?.toString().trim();
@@ -301,7 +306,7 @@ export function ensureGipityPluginInstalled() {
     const state = userScopeInstallState();
     if (state.current)
         return;
-    if (!claudeOnPath())
+    if (!binaryOnPath('claude'))
         return;
     // Refresh the marketplace clone so install/update resolves the current version.
     // resolveCommand: on Windows `claude` is a .cmd shim that spawn can't launch
@@ -327,6 +332,209 @@ export function ensureGipityPluginInstalled() {
         timeout: 120_000,
     });
 }
+// --- Grok Build (xAI) ------------------------------------------------------
+// Grok Build reads Claude-format plugins natively - skills/, commands/,
+// hooks/hooks.json, and the .claude-plugin/plugin.json manifest - and sets
+// CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA aliases for plugin hooks, so the one
+// GipityAI/skills repo serves both agents. A user-scope install
+// (`grok plugin install <repo> --trust`) is trusted and enabled automatically,
+// which gives Grok sessions the same skills and file-sync hooks as Claude Code.
+/** Parsed install state for the Gipity plugin in Grok Build, read straight
+ *  from ~/.grok/installed-plugins/registry.json (no subprocess). Mirrors
+ *  {@link userScopeInstallState} for Claude Code. */
+export function grokInstallState() {
+    try {
+        const p = join(homedir(), '.grok', 'installed-plugins', 'registry.json');
+        const data = JSON.parse(readFileSync(p, 'utf-8'));
+        const versions = [];
+        for (const repo of Object.values(data?.repos ?? {})) {
+            const v = repo?.plugins?.gipity?.version;
+            if (typeof v === 'string')
+                versions.push(v);
+        }
+        return {
+            exists: versions.length > 0,
+            current: versions.some((v) => versionGte(v, GIPITY_PLUGIN_VERSION)),
+        };
+    }
+    catch {
+        return { exists: false, current: false };
+    }
+}
+/** Install (or upgrade) the Gipity plugin in Grok Build. Best-effort and
+ *  non-fatal, like the Claude Code counterpart: skips instantly when Grok
+ *  isn't installed or the plugin is already current, so the steady-state cost
+ *  is one registry.json read. */
+export function ensureGrokPluginInstalled() {
+    const state = grokInstallState();
+    if (state.current)
+        return;
+    if (!binaryOnPath('grok'))
+        return;
+    const grokCmd = resolveCommand('grok');
+    // `install` clones the repo; on an existing install `update <name>` is the
+    // verb that refetches the source and advances the recorded version.
+    const verb = state.exists
+        ? ['plugin', 'update', 'gipity']
+        : ['plugin', 'install', GIPITY_MARKETPLACE_REPO, '--trust'];
+    const res = spawnSyncCommand(grokCmd, verb, { stdio: 'ignore', timeout: 120_000 });
+    if (!state.exists && res.status === 0) {
+        console.log('Installed the Gipity plugin for Grok (skills + file-sync hooks).');
+    }
+}
+// --- OpenAI Codex ------------------------------------------------------------
+// Codex has no Claude-plugin compatibility, but it reads the same SKILL.md
+// skill format from the cross-agent `~/.agents/skills` directory (also read by
+// OpenClaw and other agentskills.io adopters), and supports project hooks in
+// `.codex/hooks.json` with Claude-style matcher groups (`Edit|Write` aliases
+// its apply_patch tool). So Codex setup = copy the plugin's skills into
+// ~/.agents/skills, stage its hook scripts under ~/.gipity/agent-hooks, and
+// write a project .codex/hooks.json pointing at them. Codex requires the user
+// to approve non-managed hooks once via /hooks - there is no supported way to
+// pre-trust, so we print a nudge on first write.
+export const AGENTS_SKILLS_DIR = join(homedir(), '.agents', 'skills');
+export const AGENT_HOOKS_DIR = join(homedir(), '.gipity', 'agent-hooks');
+/** Records what ensureAgentSkillsInstalled() put on this machine: the plugin
+ *  version and the exact skill names copied, so upgrades replace and uninstall
+ *  removes precisely those. */
+export const AGENT_SKILLS_MANIFEST = join(homedir(), '.gipity', 'agent-skills.json');
+export function agentSkillsState() {
+    try {
+        const m = JSON.parse(readFileSync(AGENT_SKILLS_MANIFEST, 'utf-8'));
+        return {
+            current: typeof m?.version === 'string' && versionGte(m.version, GIPITY_PLUGIN_VERSION),
+            skills: Array.isArray(m?.skills) ? m.skills : [],
+        };
+    }
+    catch {
+        return { current: false, skills: [] };
+    }
+}
+/** Materialize the Gipity skills into ~/.agents/skills (the cross-agent skills
+ *  dir Codex reads) and the plugin's hook scripts into ~/.gipity/agent-hooks.
+ *  Source of truth is the same GipityAI/skills repo the Claude/Grok plugin
+ *  installs clone - fetched with a shallow git clone into a temp dir.
+ *  Best-effort: no git, no network, or a failed clone all leave things as they
+ *  were; the next init retries. */
+export function ensureAgentSkillsInstalled() {
+    if (agentSkillsState().current)
+        return;
+    if (!binaryOnPath('git'))
+        return;
+    const tmp = mkdtempSync(join(tmpdir(), 'gipity-skills-'));
+    try {
+        const clone = spawnSyncCommand(resolveCommand('git'), ['clone', '--depth', '1', `https://github.com/${GIPITY_MARKETPLACE_REPO}.git`, join(tmp, 'repo')], { stdio: 'ignore', timeout: 120_000 });
+        if (clone.status !== 0)
+            return;
+        const repo = join(tmp, 'repo');
+        let version = GIPITY_PLUGIN_VERSION;
+        try {
+            const manifest = JSON.parse(readFileSync(join(repo, '.claude-plugin', 'plugin.json'), 'utf-8'));
+            if (typeof manifest?.version === 'string')
+                version = manifest.version;
+        }
+        catch { /* keep the CLI's pinned version */ }
+        const skillsSrc = join(repo, 'skills');
+        const names = [];
+        for (const entry of readdirSync(skillsSrc, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (!existsSync(join(skillsSrc, entry.name, 'SKILL.md')))
+                continue;
+            mkdirSync(AGENTS_SKILLS_DIR, { recursive: true });
+            cpSync(join(skillsSrc, entry.name), join(AGENTS_SKILLS_DIR, entry.name), {
+                recursive: true,
+                force: true,
+            });
+            names.push(entry.name);
+        }
+        mkdirSync(AGENT_HOOKS_DIR, { recursive: true });
+        for (const script of readdirSync(join(repo, 'hooks', 'scripts'))) {
+            cpSync(join(repo, 'hooks', 'scripts', script), join(AGENT_HOOKS_DIR, script), { force: true });
+        }
+        writeFileSync(AGENT_SKILLS_MANIFEST, JSON.stringify({ version, skills: names }, null, 2) + '\n');
+        console.log(`Installed ${names.length} Gipity skills for Codex (~/.agents/skills).`);
+    }
+    catch { /* best-effort - never break setup */ }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** Pure core of the .codex/hooks.json merge: given the file's current content
+ *  (`null` when absent), return the new content, or `null` when no change is
+ *  needed. Adds the Gipity sync hook groups (push on file edits, pull before
+ *  each prompt) AND the session-capture groups (SessionStart / throttled
+ *  PostToolUse / Stop → capture.cjs, which mirrors the session into the web
+ *  CLI; Codex has no SessionEnd or SubagentStop, so those are absent), while
+ *  preserving any user-authored hooks. Our groups are recognized by their
+ *  exact command string, so a re-run upgrades older sync-only files by adding
+ *  just the missing capture entries. Exported for unit testing. */
+export function applyCodexHooks(existing) {
+    const launcher = join(AGENT_HOOKS_DIR, 'launch.sh');
+    const cmd = (script, ...args) => [`sh "${launcher}" "${join(AGENT_HOOKS_DIR, script)}"`, ...args].join(' ');
+    const wanted = [
+        { event: 'PostToolUse', matcher: 'Edit|Write', command: cmd('sync-push.cjs'), timeout: 30 },
+        { event: 'UserPromptSubmit', command: cmd('sync-pull.cjs'), timeout: 300 },
+        // Session capture: mirror the Codex session into the Gipity web CLI.
+        { event: 'SessionStart', command: cmd('capture.cjs', 'codex', 'session-start'), timeout: 30 },
+        { event: 'PostToolUse', command: cmd('capture.cjs', 'codex', 'post-tool-use'), timeout: 30 },
+        { event: 'Stop', command: cmd('capture.cjs', 'codex', 'stop'), timeout: 60 },
+    ];
+    let settings = {};
+    if (existing !== null) {
+        try {
+            settings = JSON.parse(existing);
+        }
+        catch {
+            return null; // user file we can't parse - leave it alone
+        }
+    }
+    const hooks = settings.hooks ?? (settings.hooks = {});
+    let changed = false;
+    for (const w of wanted) {
+        const groups = Array.isArray(hooks[w.event]) ? hooks[w.event] : (hooks[w.event] = []);
+        const present = groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => typeof h?.command === 'string' && h.command === w.command));
+        if (present)
+            continue;
+        const group = { hooks: [{ type: 'command', command: w.command, timeout: w.timeout }] };
+        if (w.matcher)
+            group.matcher = w.matcher;
+        groups.push(group);
+        changed = true;
+    }
+    return changed ? JSON.stringify(settings, null, 2) + '\n' : null;
+}
+/** Write the project-level Codex hooks (.codex/hooks.json). POSIX only - the
+ *  commands run through the same sh launcher the plugin uses; Codex on Windows
+ *  would need commandWindows variants (not wired yet). */
+export function setupCodexHooks() {
+    if (process.platform === 'win32')
+        return;
+    const cwd = resolve(process.cwd());
+    if (cwd === resolve(homedir()))
+        return; // never treat $HOME as a project
+    const path = join(cwd, '.codex', 'hooks.json');
+    const existing = existsSync(path) ? readFileSync(path, 'utf-8') : null;
+    const next = applyCodexHooks(existing);
+    if (next === null)
+        return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+    if (existing === null) {
+        console.log('Wrote Codex sync + session-capture hooks (.codex/hooks.json) - approve them once with /hooks inside Codex.');
+    }
+    else {
+        console.log('Updated Codex hooks (.codex/hooks.json) - if Codex asks, re-approve them via /hooks.');
+    }
+}
+/** Full Codex integration: user-scope skills + project sync hooks. Gated on
+ *  the codex binary so machines without Codex get only the AGENTS.md primer. */
+export function setupCodexIntegration() {
+    if (!binaryOnPath('codex'))
+        return;
+    ensureAgentSkillsInstalled();
+    setupCodexHooks();
+}
 export function setupClaudeHooks() {
     // All hooks ship in the plugin - enable it at user scope (and clean up any
     // legacy hook blocks in the user-global settings while we're there).
@@ -371,9 +579,25 @@ export const GIPITY_BLOCK_END = '<!-- END GIPITY INTEGRATION -->';
  *  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() {
-    const body = [SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE].join('\n\n');
+ *  avoids stale values frozen into a file.
+ *
+ *  The one environment value that DOES live here is the API base. The baked
+ *  knowledge text names `https://a.gipity.ai` as the app-services endpoint;
+ *  when this session runs against a different platform instance (GIPITY_API_BASE
+ *  / --api-base, e.g. a local dev server), the project only exists there - an
+ *  agent that copies the public host into app code gets 404s it can't explain.
+ *  So the block is rendered against the resolved base, with a note naming the
+ *  instance. The block is fully regenerated each session, so it tracks the
+ *  environment rather than going stale. */
+function renderManagedBlock(apiBase) {
+    let body = [SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE].join('\n\n');
+    const base = apiBase.replace(/\/+$/, '');
+    if (base !== DEFAULT_API_BASE) {
+        body = body.replaceAll(DEFAULT_API_BASE, base);
+        const note = `> **Platform instance:** this project runs against the Gipity platform at \`${base}\`, not the public \`${DEFAULT_API_BASE}\`. The project and its data exist only on that instance; every API/service URL in this document already points there - never substitute \`a.gipity.ai\`.`;
+        const headingEnd = body.indexOf('\n');
+        body = body.slice(0, headingEnd + 1) + '\n' + note + '\n' + body.slice(headingEnd + 1);
+    }
     return `${GIPITY_BLOCK_BEGIN}\n${body}\n${GIPITY_BLOCK_END}`;
 }
 /**
@@ -393,8 +617,8 @@ function renderManagedBlock() {
  *
  * Exported for unit testing.
  */
-export function applySkillsBlock(existing) {
-    const block = renderManagedBlock();
+export function applySkillsBlock(existing, apiBase = DEFAULT_API_BASE) {
+    const block = renderManagedBlock(apiBase);
     if (existing === null)
         return block + '\n';
     let next;
@@ -422,7 +646,7 @@ function writeSkillsFile(relPath, wrap) {
     const path = resolve(process.cwd(), relPath);
     mkdirSync(dirname(path), { recursive: true });
     const existing = existsSync(path) ? readFileSync(path, 'utf-8') : null;
-    const baseNext = applySkillsBlock(existing);
+    const baseNext = applySkillsBlock(existing, resolveApiBase());
     // Frontmatter wrap only applies on first write (no existing content).
     // Re-runs preserve user content outside the managed block, including
     // any frontmatter they may have added themselves.
@@ -506,15 +730,22 @@ export function setupCopilotMd() {
 export function setupCursorMd() {
     writeSkillsFile(PRIMER_FILES.cursor, (block) => `---\ndescription: Gipity platform integration - CLI, sandbox, app services\nalwaysApply: true\n---\n\n${block}`);
 }
-/** All supported coding-tool primers and the function that writes each.
- *  Order matters for help-text rendering and the `all` expansion.
+/** All supported coding tools: the primer each gets (`setup`) plus, for tools
+ *  with a deeper Gipity integration, an `integrate` step that installs the
+ *  Gipity skills and file-sync hooks into that tool's own ecosystem (Claude
+ *  Code plugin, Grok Build plugin, Codex ~/.agents/skills + .codex hooks).
+ *  Integrations are best-effort and self-gating - each no-ops fast when its
+ *  binary is missing or the install is already current - so running the whole
+ *  default set on every init/launch is cheap and keeps all detected agents in
+ *  lockstep. Order matters for help-text rendering and the `all` expansion.
  *  `optIn` tools are excluded from the default / `all` set and must be named
  *  explicitly (`--for aider`): aider's setup writes `.aider.conf.yml`, which
  *  changes how aider behaves in this directory - a heavier footprint than
  *  dropping an inert markdown primer. */
 export const SUPPORTED_TOOLS = [
-    { key: 'claude', label: 'Claude Code (CLAUDE.md)', setup: setupClaudeMd },
-    { key: 'codex', label: 'OpenAI Codex (AGENTS.md)', setup: setupAgentsMd },
+    { key: 'claude', label: 'Claude Code (CLAUDE.md + Gipity plugin)', setup: setupClaudeMd, integrate: setupClaudeHooks },
+    { key: 'codex', label: 'OpenAI Codex (AGENTS.md + skills + sync hooks)', setup: setupAgentsMd, integrate: setupCodexIntegration },
+    { key: 'grok', label: 'Grok Build (AGENTS.md + Gipity plugin)', setup: setupAgentsMd, integrate: ensureGrokPluginInstalled },
     { key: 'aider', label: 'Aider (AGENTS.md + .aider.conf.yml)', setup: setupAiderMd, optIn: true },
     { key: 'gemini', label: 'Gemini CLI (GEMINI.md)', setup: setupGeminiMd },
     { key: 'copilot', label: 'GitHub Copilot (.github/copilot-instructions.md)', setup: setupCopilotMd },
@@ -523,6 +754,19 @@ export const SUPPORTED_TOOLS = [
 /** The primer set written when the user makes no explicit `--for` choice:
  *  every tool except opt-in ones. */
 export const DEFAULT_TOOLS = SUPPORTED_TOOLS.filter(t => !t.optIn);
+/** Registry-driven project setup - the single entry point every "link this
+ *  directory" path shares (`init`, `project create`, `gipity claude`, the
+ *  relay daemon). Writes each requested tool's primer, runs its integration
+ *  (hooks/skills install) when it has one, and refreshes .gitignore. Replaces
+ *  the setupClaudeHooks/setupClaudeMd/setupAgentsMd/setupGitignore quartet
+ *  that used to be copy-pasted per call site and silently skipped newer tools. */
+export function setupProjectTools(tools = DEFAULT_TOOLS) {
+    for (const t of tools) {
+        t.setup();
+        t.integrate?.();
+    }
+    setupGitignore();
+}
 export function setupGitignore() {
     const gitignorePath = resolve(process.cwd(), '.gitignore');
     // Sync already skips the scratch namespaces (DEFAULT_SYNC_IGNORE); ignore them

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.428",
+  "version": "1.1.1",
   "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",
@@ -14,13 +14,14 @@
     "prepack": "npm run build",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/platform.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-unretrievable.test.js dist/__tests__/sync-clean-check.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/api-401-retry.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/session-pool.test.js dist/__tests__/relay-diagnostics.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/ingest-queue.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/capture-lock.test.js dist/__tests__/capture-resolve.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-bug.test.js dist/__tests__/cli-cmd-bug-queue.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-storage.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js dist/__tests__/trace.test.js",
+    "test:smoke": "npm run build && node --test dist/__tests__/utils.test.js dist/__tests__/platform.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-unretrievable.test.js dist/__tests__/sync-clean-check.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/api-401-retry.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/session-pool.test.js dist/__tests__/relay-diagnostics.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/ingest-queue.test.js dist/__tests__/media-upload.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/capture-parsers.test.js dist/__tests__/agents.test.js dist/__tests__/capture-lock.test.js dist/__tests__/capture-resolve.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-bug.test.js dist/__tests__/cli-cmd-bug-queue.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-storage.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js dist/__tests__/setup-codex-hooks.test.js dist/__tests__/trace.test.js",
     "test:smoke:quick": "node scripts/smoke-quick.mjs",
     "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-live.test.js dist/__tests__/cli-e2e-sync-live.test.js dist/__tests__/cli-e2e-sync-stress-live.test.js dist/__tests__/cli-e2e-rollback-live.test.js dist/__tests__/cli-e2e-services-media-live.test.js dist/__tests__/cli-e2e-workflow-live.test.js dist/__tests__/cli-e2e-sandbox-live.test.js dist/__tests__/cli-e2e-page-fetch-live.test.js dist/__tests__/cli-e2e-page-test-live.test.js",
     "test:e2e:sync": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sync-live.test.js",
     "test:e2e:sync-stress": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sync-stress-live.test.js",
     "test:e2e:rollback": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-rollback-live.test.js",
-    "test:e2e:sandbox": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sandbox-live.test.js"
+    "test:e2e:sandbox": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sandbox-live.test.js",
+    "test:e2e:agents": "tsc && GIPITY_E2E=1 node --test --test-timeout=900000 dist/__tests__/cli-e2e-agents-live.test.js"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",