gipity 1.0.380 → 1.0.384

package/dist/commands/add.js

@@ -8,20 +8,25 @@ import { sync } from '../sync.js';
 import { success, muted, bold } from '../colors.js';
 import { run } from '../helpers/index.js';
 const STARTERS = [
-    { key: 'web-fullstack', hint: 'backend API + database (weather-by-zip demo)' },
     { key: 'web-vision-cam', hint: 'fullscreen camera app with on-device vision (MediaPipe)' },
+    { key: 'object-spotter', hint: 'camera app that boxes, labels, and counts objects (YOLOX on-device)' },
     { key: '2d-game', hint: '2D games with Phaser 3 - platformer, arcade, puzzle' },
     { key: '3d-world', hint: 'playable 3D multiplayer rocket-launcher demo' },
-    { key: 'api', hint: 'pure API backend, no frontend' },
+    { key: 'karaoke-captions', hint: 'audio + lyrics -> word-synced karaoke captions (GPU job)' },
 ];
 const BLANK = [
     { key: 'web-simple', hint: 'static frontend-only site - pages, dashboards, simple games' },
+    { key: 'web-fullstack', hint: 'backend API + database wiring - frontend, functions, migrations; deploys green' },
+    { key: 'api', hint: 'pure API backend, no frontend - one example function + test' },
     { key: '3d-engine', hint: '3D multiplayer wiring - Three.js + Rapier + Gipity Realtime' },
 ];
 const HIDDEN = [{ key: 'app-itsm', hint: 'IT service management / helpdesk / ticketing' }];
 const KITS = [
     { key: 'realtime', hint: 'multiplayer / presence / shared state' },
     { key: 'web-vision-mediapipe', hint: 'browser camera vision - gesture, pose, object detection' },
+    { key: 'web-vision-detect', hint: 'browser object detection - YOLOX, WebGPU/WASM, custom models' },
+    { key: 'chatbot', hint: 'drop-in chatbot - persona, guardrails, streaming responses' },
+    { key: 'audio-align', hint: 'audio + lyrics -> word-level timing JSON (GPU job)' },
     { key: 'i18n', hint: 'multi-language web apps - language picker, RTL, translations' },
 ];
 // The catalog block, rendered once and reused by the full help output
@@ -142,7 +147,7 @@ export const addCommand = new Command('add')
     .argument('[name]', 'Template/kit key, OR a local directory path (./, ~/, or /abs). Omit for help; use --list for just the catalog.')
     .option('--title <title>', 'App title - templates only (defaults to project name)')
     .option('--description <desc>', 'App description for meta tags - templates only')
-    .option('--force', 'Templates only: overwrite any colliding files')
+    .option('--force', 'Templates only: install into a non-empty project (same-named files get a new version; other files are kept)')
     .option('--list', 'List the template/kit catalog and exit')
     .option('--json', 'Output as JSON')
     .addHelpText('after', () => catalogText() + '\n\n'

package/dist/commands/claude.js

@@ -676,8 +676,8 @@ export const claudeCommand = new Command('claude')
         }
         if (!nonInteractive) {
             console.log(`  ${bold('Launching Claude Code, powered by Gipity.')}`);
-            console.log(`  ${muted("Just tell Claude what you'd like to build or do - everything Claude could do")}`);
-            console.log(`  ${muted('before, and now, on Gipity, so much more.')}`);
+            console.log(`  ${muted("Just tell Claude what you'd like to build or do - everything Claude can do,")}`);
+            console.log(`  ${muted('plus hosting, databases, and live deploys on Gipity.')}`);
             console.log('');
         }
         // In non-interactive (-p) mode, prepend a Gipity preamble to the

package/dist/commands/status.js

@@ -1,48 +1,40 @@
 import { Command } from 'commander';
 import { existsSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
+import { homedir } from 'os';
 import { getAuth, getTimeRemaining } from '../auth.js';
 import { getConfig, liveUrl } from '../config.js';
 import { brand, success, warning, muted, error as clrError } from '../colors.js';
-import { HOOKS_SETTINGS, setupClaudeHooks } from '../setup.js';
-/** Inspect `.claude/settings.json` against the current `HOOKS_SETTINGS`.
- *  Returns the set of hook-event names that are missing or mismatched. */
-function checkCaptureHooks(cwd) {
-    const path = join(cwd, '.claude', 'settings.json');
-    if (!existsSync(path))
-        return { missing: Object.keys(HOOKS_SETTINGS.hooks), ok: false };
-    let settings;
-    try {
-        settings = JSON.parse(readFileSync(path, 'utf-8'));
-    }
-    catch {
-        return { missing: Object.keys(HOOKS_SETTINGS.hooks), ok: false };
-    }
-    const actualHooks = settings?.hooks ?? {};
-    const missing = [];
-    for (const [event, expectedGroups] of Object.entries(HOOKS_SETTINGS.hooks)) {
-        const actualGroups = Array.isArray(actualHooks[event]) ? actualHooks[event] : [];
-        const expectedCmds = new Set(expectedGroups.flatMap(g => (g.hooks ?? []).map((h) => h.command)));
-        const actualCmds = new Set(actualGroups.flatMap(g => (g.hooks ?? []).map((h) => h.command)));
-        // Every expected command must be present. Users can add their own.
-        for (const cmd of expectedCmds) {
-            if (!actualCmds.has(cmd)) {
-                missing.push(event);
-                break;
-            }
+import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, setupClaudeHooks, ensureGipityPlugin } from '../setup.js';
+/** Hooks ship in the Gipity Claude Code plugin now - "installed" means the
+ *  user-scope settings register the marketplace and enable the plugin.
+ *  Claude Code fetches/updates the plugin itself at launch. */
+function checkGipityPlugin() {
+    const path = join(homedir(), '.claude', 'settings.json');
+    let settings = {};
+    if (existsSync(path)) {
+        try {
+            settings = JSON.parse(readFileSync(path, 'utf-8'));
         }
+        catch { /* treat as empty */ }
     }
+    const missing = [];
+    if (!settings?.extraKnownMarketplaces?.[GIPITY_MARKETPLACE_NAME])
+        missing.push('marketplace');
+    if (settings?.enabledPlugins?.[GIPITY_PLUGIN_ID] !== true)
+        missing.push('plugin');
     return { missing, ok: missing.length === 0 };
 }
 export const statusCommand = new Command('status')
     .description('Show project and login status')
     .option('--json', 'Output as JSON')
-    .option('--repair-hooks', 'Reinstall the capture hooks in .claude/settings.json if missing')
+    .option('--repair-hooks', 'Re-enable the Gipity Claude Code plugin (hooks) if missing or disabled')
     .action(async (opts) => {
     const config = getConfig();
     const auth = getAuth();
     const cwd = resolve(process.cwd());
-    const hookCheck = config ? checkCaptureHooks(cwd) : null;
+    void cwd;
+    const hookCheck = config ? checkGipityPlugin() : null;
     if (opts.json) {
         console.log(JSON.stringify({
             project: config ? {
@@ -57,7 +49,7 @@ export const statusCommand = new Command('status')
                 expiresAt: auth.expiresAt,
                 valid: new Date(auth.expiresAt).getTime() > Date.now(),
             } : null,
-            capture_hooks: hookCheck,
+            plugin: hookCheck,
         }, null, 2));
         return;
     }
@@ -80,16 +72,18 @@ export const statusCommand = new Command('status')
     }
     if (hookCheck) {
         if (hookCheck.ok) {
-            console.log(`${muted('Hooks:')}   ${success('capture hooks installed')}`);
+            console.log(`${muted('Hooks:')}   ${success(`Gipity plugin enabled (${GIPITY_PLUGIN_ID})`)}`);
         }
         else if (opts.repairHooks) {
+            // force: an explicit repair request overrides a previous disable.
+            ensureGipityPlugin(true);
             setupClaudeHooks();
-            console.log(`${muted('Hooks:')}   ${success('repaired - re-installed capture hooks')}`);
+            console.log(`${muted('Hooks:')}   ${success('repaired - Gipity plugin re-enabled')}`);
         }
         else {
-            console.log(`${muted('Hooks:')}   ${warning(`missing/modified: ${hookCheck.missing.join(', ')}`)}`);
-            console.log(muted('Run `gipity status --repair-hooks` to re-install.'));
-            console.log(muted('Without these, web CLI dispatches can\'t show Claude Code output.'));
+            console.log(`${muted('Hooks:')}   ${warning(`Gipity plugin not enabled (missing: ${hookCheck.missing.join(', ')})`)}`);
+            console.log(muted('Run `gipity status --repair-hooks` to re-enable.'));
+            console.log(muted('Without it, files don\'t auto-sync and web CLI dispatches can\'t show Claude Code output.'));
         }
     }
 });

package/dist/commands/sync.js

@@ -3,7 +3,7 @@ import { sync } from '../sync.js';
 import { createProgressReporter } from '../progress.js';
 import { error as clrError } from '../colors.js';
 export const syncCommand = new Command('sync')
-    .description('Sync files')
+    .description('Sync files (a .gipityignore at the project root excludes paths, gitignore-style)')
     .option('--plan', 'Print the plan without applying any changes')
     .option('--force', 'Bypass the bulk-deletion guard')
     .option('--json', 'Output as JSON')

package/dist/commands/test.js

@@ -12,6 +12,8 @@ function statusIcon(status) {
         return muted('→');
     return muted('?');
 }
+// Long-run hint for non-TTY runs: after this, print a one-time "not hung" + faster-path hint.
+const LONG_RUN_MS = 60000;
 async function pollTestStatus(projectGuid, runGuid, opts) {
     // Adaptive polling: fast at first (tests often finish quickly with warm pool),
     // then back off for long-running suites.
@@ -24,7 +26,21 @@ async function pollTestStatus(projectGuid, runGuid, opts) {
             return 1000; // next 15s: poll every 1s
         return 3000; // after 20s: poll every 3s
     };
+    // Heartbeat cadence for non-TTY runs (background/piped output, e.g. a watching
+    // agent): every line is re-read by the watcher, and on long LLM-backed suites
+    // nothing changes second-to-second — so back off like getPollInterval does.
+    const getHeartbeatInterval = () => {
+        const elapsed = Date.now() - startTime;
+        if (elapsed < 120000)
+            return 10000; // first 2 min: every 10s
+        if (elapsed < 300000)
+            return 30000; // to 5 min: every 30s
+        return 60000; // after 5 min: every 60s
+    };
     let lastResultCount = 0;
+    const isTTY = !!process.stdout.isTTY;
+    let lastHeartbeat = 0; // 0 => emit the first heartbeat immediately (non-TTY)
+    let longRunHintShown = false;
     while (true) {
         const res = await get(`/projects/${projectGuid}/test/status/${runGuid}`);
         const data = res.data;
@@ -61,14 +77,38 @@ async function pollTestStatus(projectGuid, runGuid, opts) {
         if (data.status !== 'running') {
             return data;
         }
-        // Show progress indicator (overwrite in-place) - only in real terminals
-        if (!opts.json && process.stdout.isTTY) {
-            if (data.totalFiles === 0) {
-                process.stdout.write(`\r  ${muted('Starting...')}          `);
+        if (!opts.json) {
+            if (isTTY) {
+                // Real terminal: overwrite a single in-place progress line.
+                if (data.totalFiles === 0) {
+                    process.stdout.write(`\r  ${muted('Starting...')}          `);
+                }
+                else {
+                    const pct = Math.round((data.completedFiles / data.totalFiles) * 100);
+                    process.stdout.write(`\r  ${muted(`${data.completedFiles}/${data.totalFiles} files (${pct}%)`)}`);
+                }
             }
             else {
-                const pct = Math.round((data.completedFiles / data.totalFiles) * 100);
-                process.stdout.write(`\r  ${muted(`${data.completedFiles}/${data.totalFiles} files (${pct}%)`)}`);
+                // Non-TTY (background/piped, e.g. a watching agent): a \r line never
+                // shows up in a captured file, so emit periodic newline heartbeats.
+                // Time-based so the file always grows — lets a watcher tell a slow run
+                // from a hung one, and gives elapsed time to budget against.
+                const now = Date.now();
+                if (now - lastHeartbeat >= getHeartbeatInterval()) {
+                    lastHeartbeat = now;
+                    const elapsed = Math.round((now - startTime) / 1000);
+                    const progress = data.totalFiles === 0
+                        ? 'starting up'
+                        : `${data.completedFiles}/${data.totalFiles} files`;
+                    const tally = data.passed + data.failed > 0
+                        ? ` (${data.passed} passed${data.failed > 0 ? `, ${data.failed} failed` : ''})`
+                        : '';
+                    console.log(muted(`  … still running — ${progress}${tally}, ${elapsed}s elapsed`));
+                    if (now - startTime >= LONG_RUN_MS && !longRunHintShown) {
+                        longRunHintShown = true;
+                        console.log(muted('  Note: progressing, not hung. LLM-backed tests can take minutes. To verify one function fast, use `gipity fn call <name>`; narrow this suite with `gipity test <path>`.'));
+                    }
+                }
             }
         }
         await new Promise(resolve => setTimeout(resolve, getPollInterval()));
@@ -78,13 +118,15 @@ async function pollTestStatus(projectGuid, runGuid, opts) {
 export const testCommand = new Command('test')
     .description('Run tests')
     .argument('[path]', 'Test path filter (e.g. "api", "e2e/portal")')
+    .option('--filter <path>', 'Alias for the positional test path filter')
     .option('--timeout <ms>', 'Per-test timeout in ms', '30000')
     .option('--retry <n>', 'Retry failed tests N times', '0')
     .option('--no-sync', 'Skip sync-up before tests')
     .option('--json', 'Output as JSON')
-    .action((filterPath, opts) => run('Test', async () => {
+    .action((pathFilter, opts) => run('Test', async () => {
     const config = requireConfig();
     await syncBeforeAction(opts);
+    const filterPath = opts.filter || pathFilter;
     if (!opts.json) {
         console.log(bold(`Running tests: ${filterPath || 'all'}`));
         console.log('');
@@ -113,6 +155,10 @@ export const testCommand = new Command('test')
     // Print any remaining results not yet shown (edge case: final batch)
     // (pollTestStatus already printed results incrementally)
     console.log('');
+    if (filterPath && data.total === 0 && data.results.length === 0) {
+        console.log(clrError(`No tests matched filter: ${filterPath}`));
+        process.exit(1);
+    }
     // Summary
     const parts = [];
     if (data.passed > 0)

package/dist/commands/uninstall.js

@@ -1,14 +1,15 @@
 /**
  * `gipity uninstall` - true reset. Stops the relay daemon, removes the
  * platform autostart service, revokes the device on the server (best-effort),
- * and wipes ~/.gipity/. Never touches ~/GipityProjects/ - your local
- * project trees are yours to keep or remove yourself.
+ * removes the Gipity Claude Code plugin enablement (which removes all Gipity
+ * hooks at once), and wipes ~/.gipity/. Never touches ~/GipityProjects/ -
+ * your local project trees are yours to keep or remove yourself.
  *
  * Does not touch the npm-installed shim - the user removes that separately
  * via `npm uninstall -g gipity`.
  */
 import { Command } from 'commander';
-import { existsSync, rmSync, unlinkSync } from 'fs';
+import { existsSync, rmSync, unlinkSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, resolve } from 'path';
 import { spawnSync } from 'child_process';
@@ -18,6 +19,39 @@ import { confirm, getAutoConfirm } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as relayState from '../relay/state.js';
 import { planFor, UnsupportedPlatformError } from '../relay/installers.js';
+import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, stripGipityHooks } from '../setup.js';
+/** Remove Gipity's entries from the user-scope Claude Code settings: the
+ *  plugin enablement, the marketplace registration, and any legacy hook
+ *  blocks older CLI versions wrote there. Surgical - everything else in the
+ *  file (the user's own permissions, hooks, other plugins) is untouched. */
+function removeGipityPluginConfig() {
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    if (!existsSync(settingsPath))
+        return false;
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+    let changed = stripGipityHooks(settings);
+    if (settings.enabledPlugins && GIPITY_PLUGIN_ID in settings.enabledPlugins) {
+        delete settings.enabledPlugins[GIPITY_PLUGIN_ID];
+        if (Object.keys(settings.enabledPlugins).length === 0)
+            delete settings.enabledPlugins;
+        changed = true;
+    }
+    if (settings.extraKnownMarketplaces?.[GIPITY_MARKETPLACE_NAME]) {
+        delete settings.extraKnownMarketplaces[GIPITY_MARKETPLACE_NAME];
+        if (Object.keys(settings.extraKnownMarketplaces).length === 0)
+            delete settings.extraKnownMarketplaces;
+        changed = true;
+    }
+    if (changed)
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    return changed;
+}
 function resolveCliPath() {
     return resolve(process.argv[1] ?? 'gipity');
 }
@@ -99,6 +133,7 @@ export const uninstallCommand = new Command('uninstall')
     console.log(`• Stop the running relay daemon (if any)`);
     console.log(`• Remove the OS autostart service (launchd / systemd / Task Scheduler)`);
     console.log(`• Revoke this device on the server (best-effort)`);
+    console.log(`• Remove the Gipity Claude Code plugin enablement (all Gipity hooks)`);
     console.log(`• Delete ${gipityDir}/`);
     console.log('');
     console.log(`${dim('It will NOT remove the `gipity` binary. Run `npm uninstall -g gipity` afterward if you want that too.')}`);
@@ -124,7 +159,14 @@ export const uninstallCommand = new Command('uninstall')
     // 3. Revoke device on server.
     await revokeDeviceBestEffort();
     console.log(`${success('Device revoked on server (or was already revoked).')}`);
-    // 4. Wipe ~/.gipity/.
+    // 4. Remove the Claude Code plugin enablement + any legacy hook blocks.
+    if (removeGipityPluginConfig()) {
+        console.log(`${success('Gipity Claude Code plugin disabled (hooks removed).')}`);
+    }
+    else {
+        console.log(`${muted('No Gipity entries in Claude Code settings.')}`);
+    }
+    // 5. Wipe ~/.gipity/.
     if (existsSync(gipityDir)) {
         try {
             rmSync(gipityDir, { recursive: true, force: true });

package/dist/hooks/capture-runner.js

@@ -6,8 +6,10 @@
  * session into the Gipity server so the web CLI can display it read-only.
  *
  * Not a user-facing `gipity` subcommand by design: users never invoke
- * this directly. `setupClaudeHooks` wires up hook entries that call
- * `node <absolute-path>/capture-runner.js <source> <event>`.
+ * this directly. The Gipity Claude Code plugin's capture hook script
+ * (claude-plugin hooks/scripts/capture.cjs) resolves this file inside the
+ * installed CLI at fire time and runs it - so the capture logic versions
+ * with the CLI, not the plugin.
  *
  * Usage:
  *   node capture-runner.js <source> <event>

package/dist/knowledge.js

@@ -14,6 +14,7 @@ Templates:
     - \`web-simple\` - Landing page, dashboard, calculator, canvas demo, visualization, animation, single-page tool
     - \`web-fullstack\` - Web app with login, database, or API - CRM, invoice tracker, booking system, admin panel
     - \`web-vision-cam\` - Live camera app with gesture, pose, or object detection - hand-tracking input, fitness/pose feedback, object-aware UI; on-device, no upload
+    - \`object-spotter\` - Object-detection app - count or label things from the camera or a photo, inventory/shelf counting, custom-model detection; on-device, no upload
     - \`2d-game\` - Platformer, arcade, puzzle, endless runner, physics toy (Phaser 3)
     - \`3d-engine\` - Minimal 3D multiplayer base - Three.js + Rapier + Colyseus, no gameplay; build your own scene and mechanics on top
     - \`3d-world\` - Multiplayer world, 3D sandbox, shooter, exploration, virtual showroom (Three.js + Rapier + Colyseus)
@@ -29,9 +30,13 @@ Hidden types (do NOT suggest unsolicited - use only when the user explicitly ask
 Kits are reusable building blocks added to an existing app, not whole templates - their files land in \`src/packages/<name>/\`:
     - \`gipity add realtime\` - Multiplayer / presence / shared state - channels, host election, server-persisted sync. Engine-agnostic; works in any app.
     - \`gipity add web-vision-mediapipe\` - On-device camera vision - gesture recognition, body pose, object detection. Runs fully client-side via MediaPipe Tasks; no server, no upload. Web only.
+    - \`gipity add web-vision-detect\` - High-accuracy object detection in the browser - YOLOX (Apache-2.0) on ONNX Runtime Web, WebGPU with WASM fallback. 80 COCO classes, three speed/accuracy presets, or bring your own custom-trained YOLO/YOLOX ONNX model. Client-side; no server, no upload. Web only.
     - \`gipity add chatbot\` - Drop-in chatbot - configurable persona, scope guardrails, static knowledge (20k budget), streaming responses. Headless engine + bubble widget; bring your own UI if you want. Works in any app.
     - \`gipity add audio-align\` - Audio + lyrics -> word-level timing JSON. Demucs vocal isolation + MMS_FA forced alignment, runs as a Modal L4 GPU job (~$0.01 per 3-min song). For karaoke captions, subtitling, language learning, dubbing alignment.
-    - \`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 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.`;
 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.
@@ -40,15 +45,19 @@ 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\`.
+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 - they auto-sync to Gipity via hooks. Don't run \`npm install\`, \`npm start\`, \`node\`, or \`python\` locally; there is no local runtime. Code runs in the Gipity sandbox.
+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.
 
 ## Use first-party services before reaching outside
 
 Gipity ships first-party services for what apps usually pull from third parties - auth, location/geocoding, LLM, image/audio/video generation, transcription, file uploads, realtime. Before calling an external API or adding an npm package for one of these, check \`gipity skill list\` for a match. First-party services need no API keys, cost less, and keep data in-house. Reach outside only when the catalog has no equivalent - and say so when you do.
 
+## Don't guess Gipity facts - look them up
+
+When a user asks about Gipity itself - how to install it, what it costs, what's shipped, how a command or flag works - answer from an authoritative source, not memory, and don't hedge with "I don't want to guess." Check in this order: (1) \`gipity skill read <name>\` / \`gipity skill list\` - install and account basics live in \`getting-started\`; (2) \`gipity <command> --help\` for command syntax; (3) if it's genuinely not in the skills or CLI help, fetch the live site at \`https://gipity.ai\` (or web search) and cite what you found. A wrong or vague answer about the product is worse than spending one tool call to get the current, correct one.
+
 ## Gipity is opinionated - build on its stack
 
 Gipity is an opinionated platform with its own best-practice stack, and that stack is the one you use - whatever tools the user names. The platform layer is fixed:
@@ -84,7 +93,9 @@ Every tool call returns its full output with that call. There is no output buffe
 
 ## Files and sync
 
-Write files locally - hooks auto-push to Gipity on every save. Remote-generated files (images, audio from \`gipity chat\`) auto-pull. Use \`gipity sync\` if things get out of sync. Deletes are safe - use \`rollback\` with a datetime to undo, or \`file_version_restore\` for individual files.
+Write files locally - the Gipity Claude Code plugin's hooks auto-push every save to Gipity and auto-pull remote changes (images, audio from \`gipity chat\`) before each turn. Use \`gipity sync\` if things get out of sync (or if the plugin isn't installed - \`gipity status --repair-hooks\` re-enables it). Deletes are safe - use \`rollback\` with a datetime to undo, or \`file_version_restore\` for individual files.
+
+To keep local-only material (research clones, scratch data, vendored references) in the project directory without syncing or deploying it, list it in a \`.gipityignore\` at the project root - gitignore-style, one pattern per line, \`#\` comments. Ignored paths are invisible to sync in both directions; anything that already synced before being ignored stays on the server until you delete it.
 
 ## Skills (detailed documentation)
 

package/dist/prompts.js

@@ -162,13 +162,6 @@ export function buildFreshWrap(contextBlock, userMsg) {
     ].join('\n');
 }
 // ---------------------------------------------------------------------------
-// PreToolUse soft-warning hook (advisory message printed to stderr)
-// ---------------------------------------------------------------------------
-/** Plain ASCII, no apostrophes or backslashes - embedded inside a node -e shell command. */
-export const SCAFFOLD_HOOK_WARNING = `[gipity] Heads up: this project has no app yet. If you are building an app/game/API to deploy, ` +
-    `stop and run: gipity add <${TEMPLATE_KEY_PATTERN}>  (default: web-simple). ` +
-    `If this is a one-off task (analysis, data, PDFs, scratch work), proceed.`;
-// ---------------------------------------------------------------------------
 // Per-project CLAUDE.md / AGENTS.md body.
 //
 // The content (`SKILLS_CONTENT`) is sourced from

package/dist/relay/daemon.js

@@ -21,7 +21,7 @@
  * See docs/feature-backlog/gipity-relay-phases.md (Phase A Step 7).
  */
 import { spawn } from 'child_process';
-import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, closeSync, openSync } from 'fs';
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, closeSync, openSync, unlinkSync } from 'fs';
 import { stat, readFile } from 'fs/promises';
 import { createInterface } from 'readline';
 import { homedir, hostname, platform as osPlatform } from 'os';
@@ -29,7 +29,6 @@ import { join } from 'path';
 import { getApiBaseOverride, getConfig } from '../config.js';
 import { getProjectsRoot } from './paths.js';
 import { setupClaudeHooks, setupClaudeMd, setupAgentsMd, setupGitignore, DEFAULT_SYNC_IGNORE } from '../setup.js';
-import { sync } from '../sync.js';
 import { getAuth, readAuthFresh } from '../auth.js';
 import { post } from '../api.js';
 import * as state from './state.js';
@@ -52,6 +51,9 @@ const BACKOFF_BASE_MS = parseInt(process.env.GIPITY_RELAY_BACKOFF_BASE_MS || '10
 const BACKOFF_MAX_MS = parseInt(process.env.GIPITY_RELAY_BACKOFF_MAX_MS || '30000', 10);
 const CANCEL_POLL_INTERVAL_MS = parseInt(process.env.GIPITY_RELAY_CANCEL_POLL_MS || '3000', 10);
 const MAX_CONCURRENT_DISPATCHES = Math.max(1, parseInt(process.env.GIPITY_RELAY_MAX_CONCURRENT || '6', 10));
+// Cap how long the pre-Claude project sync (and the post-dispatch push-back) may
+// run before we kill it - a stalled sync must never hang a dispatch forever.
+const PROJECT_SYNC_TIMEOUT_MS = parseInt(process.env.GIPITY_RELAY_SYNC_TIMEOUT_MS || '120000', 10);
 // ─── HTTP helpers ──────────────────────────────────────────────────────
 // Device-auth fetch lives in ./device-http.ts - shared with the capture
 // hook runner so both POST to /remote-sessions/:convGuid/ingest with the
@@ -214,13 +216,13 @@ export async function run(opts = {}) {
     process.on('SIGTERM', () => shutdown('SIGTERM'));
     if (opts.maxRunMs)
         setTimeout(() => shutdown('maxRunMs'), opts.maxRunMs).unref();
-    // Take the PID lock. If another daemon already holds it, exit clean -
-    // the caller (usually `gipity claude`'s auto-start) is racing us.
-    try {
-        state.writeDaemonPid(process.pid);
-    }
-    catch (err) {
-        log('info', 'another daemon is already running - exiting', { err: err?.message });
+    // Take the PID lock. Only a *live* daemon should block us: a leftover pid file
+    // from an unclean exit (container SIGKILL'd, or `--restart` brought us back on
+    // the same filesystem) must not trap us in a permanent restart loop.
+    // isDaemonRunning() validates the recorded PID is actually alive and clears
+    // the file if it's stale, so writeDaemonPid below can then take the lock.
+    if (state.isDaemonRunning()) {
+        log('info', 'another daemon is already running - exiting');
         if (opts.verbose) {
             process.stderr.write('Another relay daemon is already running (likely the autostarted one).\n' +
                 'Stop it first, then retry:  gipity relay autostart uninstall  (or stop the service),\n' +
@@ -228,6 +230,14 @@ export async function run(opts = {}) {
         }
         return 0;
     }
+    try {
+        state.writeDaemonPid(process.pid);
+    }
+    catch (err) {
+        // Lost a genuine race with another daemon starting at the same instant.
+        log('info', 'lost pid-lock race with another daemon - exiting', { err: err?.message });
+        return 0;
+    }
     const releasePid = () => state.clearDaemonPid();
     process.on('exit', releasePid);
     // Also release on our shutdown signals (exit handler sometimes doesn't fire).
@@ -582,15 +592,35 @@ async function handleDispatch(d) {
     // serialization point that prevents that.
     await killRunningForConv(d.conversation_guid);
     let cwd;
+    let bootstrapped;
     try {
-        cwd = await resolveCwdForProject(d);
-        log('debug', 'resolved project cwd', { id: d.short_guid, project: d.project_slug, cwd });
+        ({ cwd, bootstrapped } = await resolveCwdForProject(d));
+        log('debug', 'resolved project cwd', { id: d.short_guid, project: d.project_slug, cwd, bootstrapped });
     }
     catch (err) {
         log('error', 'could not resolve project cwd', { id: d.short_guid, err: err?.message });
         await ack(d.short_guid, 'error', `Could not materialize project locally: ${err?.message || err}`);
         return;
     }
+    // Explicit, user-visible, timeout-bounded project sync BEFORE starting Claude -
+    // only on a freshly bootstrapped dir (the files aren't there yet). Pull the
+    // project's files first so Claude works against the real tree; a hung/slow sync
+    // is killed at PROJECT_SYNC_TIMEOUT_MS and reported instead of silently stalling
+    // the dispatch (the old in-process bootstrap sync could hang forever).
+    if (bootstrapped) {
+        await postIngest(d.conversation_guid, [{ kind: 'system', content: 'Syncing project files…' }]);
+        try {
+            await spawnSync(cwd, PROJECT_SYNC_TIMEOUT_MS);
+            await postIngest(d.conversation_guid, [{ kind: 'system', content: 'Project files synced.' }]);
+        }
+        catch (err) {
+            const msg = `project sync ${err?.message || 'failed'}`;
+            log('error', 'project sync failed - aborting dispatch', { id: d.short_guid, err: err?.message });
+            await postIngest(d.conversation_guid, [{ kind: 'system', content: `Claude Code not started - ${msg}` }]);
+            await ack(d.short_guid, 'error', msg);
+            return;
+        }
+    }
     // Build argv for `gipity claude -p …` (or with --resume). No shell - argv
     // as array so the message string can't be interpreted as shell syntax.
     //
@@ -690,7 +720,7 @@ async function handleDispatch(d) {
     // this sync redundant for that case.
     if (!spawnErr) {
         try {
-            await spawnSync(cwd);
+            await spawnSync(cwd, PROJECT_SYNC_TIMEOUT_MS);
         }
         catch (err) {
             log('warn', 'sync after dispatch failed', { id: d.short_guid, err: err?.message });
@@ -742,11 +772,11 @@ async function resolveCwdForProject(d) {
         try {
             const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
             if (cfg.projectGuid === d.project_guid)
-                return path;
+                return { cwd: path, bootstrapped: false };
             log('warn', 'project dir exists but guid mismatch - using it anyway', {
                 path, expected: d.project_guid, found: cfg.projectGuid,
             });
-            return path;
+            return { cwd: path, bootstrapped: false };
         }
         catch { /* fall through to re-bootstrap */ }
     }
@@ -771,17 +801,14 @@ async function resolveCwdForProject(d) {
         setupClaudeMd();
         setupAgentsMd();
         setupGitignore();
-        try {
-            await sync({ interactive: false });
-        }
-        catch (err) {
-            log('warn', 'initial sync failed; project dir created but empty', { err: err?.message });
-        }
     }
     finally {
         process.chdir(origCwd);
     }
-    return path;
+    // Sync is NOT done here: the dispatch handler runs it as an explicit, visible,
+    // timeout-bounded step (a blocking in-process sync here used to hang the whole
+    // dispatch with no timeout and no user feedback).
+    return { cwd: path, bootstrapped: true };
 }
 const running = new Map();
 export function getRunningDispatchGuids() {
@@ -821,7 +848,7 @@ export async function killRunningForConv(convGuid) {
  *  back to VFS. Runs as a child so we inherit sync's cwd-walk for config
  *  resolution (the daemon itself doesn't chdir into projects).
  *  Non-blocking on failure - caller catches and logs. */
-async function spawnSync(cwd) {
+async function spawnSync(cwd, timeoutMs) {
     const cmd = process.env.GIPITY_RELAY_CLAUDE_CMD || 'gipity';
     return new Promise((resolve, reject) => {
         const child = spawn(cmd, ['sync', '--json'], {
@@ -832,18 +859,39 @@ async function spawnSync(cwd) {
         // Drain pipes so the child doesn't stall on a full buffer.
         let stdoutLen = 0;
         let stderrBuf = '';
+        let settled = false;
+        let timer = null;
+        const finish = (fn) => { if (settled)
+            return; settled = true; if (timer)
+            clearTimeout(timer); fn(); };
+        // A sync that never returns must not hang the dispatch forever. Kill the child
+        // and clear its sync.lock (a SIGKILL'd `gipity sync` leaves the lock behind,
+        // which would make the next sync wait 30s on a dead holder).
+        if (timeoutMs) {
+            timer = setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* gone */ }
+                try {
+                    unlinkSync(join(cwd, '.gipity', 'sync.lock'));
+                }
+                catch { /* not there */ }
+                finish(() => reject(new Error(`timed out after ${Math.round(timeoutMs / 1000)}s`)));
+            }, timeoutMs);
+        }
         child.stdout?.on('data', (b) => { stdoutLen += b.length; });
         child.stderr?.on('data', (b) => { stderrBuf += b.toString('utf-8'); });
-        child.on('error', (err) => reject(err));
-        child.on('exit', (code) => {
+        child.on('error', (err) => finish(() => reject(err)));
+        child.on('exit', (code) => finish(() => {
             if (code === 0) {
-                log('info', 'sync after dispatch', { cwd, stdoutLen });
+                log('info', 'sync done', { cwd, stdoutLen });
                 resolve();
             }
             else {
                 reject(new Error(`gipity sync exited ${code}${stderrBuf ? `: ${stderrBuf.trim().slice(0, 300)}` : ''}`));
             }
-        });
+        }));
     });
 }
 export async function spawnGipityClaude(args, cwd, d) {

package/dist/relay/redact.js

@@ -30,15 +30,23 @@ const MIN_SECRET_LEN = 12;
  *  appearing in a relay transcript is effectively always a credential, so
  *  over-redaction risk is negligible. */
 const JWT_RE = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
-/** Replace every occurrence of each known secret - and any JWT-shaped
- *  substring - in `text` with the marker. */
+/** Anthropic credential tokens: API keys (`sk-ant-api…`) and Claude Code OAuth
+ *  tokens (`sk-ant-oat…`). These are NOT JWT-shaped, so the JWT backstop misses
+ *  them. On a bring-your-own-key relay the user's own API key lives in the
+ *  container env, and a `bypassPermissions` session could otherwise echo it
+ *  (`env`, `cat`) into the transcript — so pattern-redact it regardless of the
+ *  literal-secret list. An `sk-ant-` token in a relay transcript is always a
+ *  credential, so over-redaction risk is negligible. */
+const ANTHROPIC_KEY_RE = /sk-ant-[A-Za-z0-9_-]{20,}/g;
+/** Replace every occurrence of each known secret - and any JWT- or
+ *  Anthropic-key-shaped substring - in `text` with the marker. */
 function redactString(text, secrets) {
     let out = text;
     for (const secret of secrets) {
         if (out.includes(secret))
             out = out.split(secret).join(REDACTION_MARKER);
     }
-    return out.replace(JWT_RE, REDACTION_MARKER);
+    return out.replace(JWT_RE, REDACTION_MARKER).replace(ANTHROPIC_KEY_RE, REDACTION_MARKER);
 }
 /** Deep-walk any JSON-ish value, redacting every string. Returns a new
  *  value; objects/arrays are cloned, primitives passed through. */

package/dist/relay/state.js

@@ -116,8 +116,26 @@ export function isDaemonRunning() {
     try {
         const raw = readFileSync(RELAY_PID_FILE, 'utf-8').trim();
         const pid = parseInt(raw, 10);
-        if (!pid || isNaN(pid))
+        // A corrupt/empty pid file is stale - clear it so it can't trap a restart.
+        if (!pid || isNaN(pid)) {
+            try {
+                unlinkSync(RELAY_PID_FILE);
+            }
+            catch { /* ignore */ }
             return false;
+        }
+        // Our OWN pid in the file = stale from a previous incarnation, NOT a live peer.
+        // In a container the daemon is always pid 1, so `--restart` brings us back as
+        // pid 1 with the dead run's relay.pid (also 1) left behind; process.kill(1,0)
+        // would say "alive" (it's us) and trap us in a permanent restart loop. We write
+        // our pid only AFTER this check, so finding it here means the file predates us.
+        if (pid === process.pid) {
+            try {
+                unlinkSync(RELAY_PID_FILE);
+            }
+            catch { /* ignore */ }
+            return false;
+        }
         // `kill 0` sends no signal but checks if the PID is addressable.
         process.kill(pid, 0);
         return true;

package/dist/setup.js

@@ -2,11 +2,9 @@
  * Shared project setup helpers used by both `init` and `claude`.
  */
 import { resolve, join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
-import { SCAFFOLD_HOOK_WARNING } from './prompts.js';
 import { SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE } from './knowledge.js';
-import { getConfig } from './config.js';
 export { SKILLS_CONTENT };
 /** Canonical list of workstation artifacts that are NOT part of the project.
  *  Used as the single source of truth for three separate decisions:
@@ -91,116 +89,122 @@ export const PERMISSIONS_SETTINGS = {
         ],
     },
 };
-/** Absolute path to the bundled capture-runner script. Resolved once at
- *  install time so hook commands embed a stable `node <path>` command
- *  rather than `gipity …` (which would require re-running `gipity` every
- *  hook fire). Works whether the CLI is installed globally, linked, or
- *  run from a build output - `import.meta.url` always points at this
- *  file under `dist/`, and the runner sits at `dist/hooks/`. */
-export function resolveCaptureRunnerPath() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    return resolve(here, 'hooks', 'capture-runner.js');
+// Hooks now ship in the Gipity Claude Code plugin (GipityAI/claude-plugin,
+// which doubles as its own marketplace): file sync (push on edit, pull on
+// prompt) and `gipity claude` session capture, every script guarded to no-op
+// outside Gipity projects. Past CLI versions wrote these hook blocks directly
+// into each project's .claude/settings.json with absolute paths baked in -
+// that left orphaned entries behind on uninstall (the CLI keeps no inventory
+// of projects it touched) and could even land in the user-global settings
+// when a gipity command ran from $HOME. The plugin replaces all of it with
+// one declarative enablement entry: Claude Code resolves script paths via
+// ${CLAUDE_PLUGIN_ROOT}, fetches the marketplace non-interactively at launch
+// (headless included), and uninstall/disable removes every hook at once.
+export const GIPITY_PLUGIN_ID = 'gipity@gipity';
+export const GIPITY_MARKETPLACE_NAME = 'gipity';
+export const GIPITY_MARKETPLACE_REPO = 'GipityAI/claude-plugin';
+/** 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. */
+export function isGipityManagedHookCommand(command) {
+    return (
+    // Capture hooks: bare absolute runner path or the fire-time launcher.
+    command.includes('capture-runner.js') ||
+        // File-sync push one-liner (spawn('gipity',['push',p,'--quiet'],...)).
+        command.includes("'gipity',['push'") ||
+        // Pull-on-prompt one-liner, current and older variants.
+        command.includes('gipity sync --json') ||
+        command.includes('gipity sync down --json') ||
+        // Scaffold nudge (retired entirely - CLAUDE.md carries the rule).
+        command.includes("['gipity.yaml','src','functions','package.json']"));
 }
-// Cross-platform hooks using node -e (no bash/jq dependency).
-//
-// Two categories:
-//   1. File-sync hooks (PreToolUse / PostToolUse / UserPromptSubmit):
-//      installed unconditionally. Scaffold reminder + push/pull. Not
-//      related to conversation capture.
-//   2. Capture hooks (SessionStart / Stop / SubagentStop / SessionEnd, plus
-//      a throttled PostToolUse for mid-run flushing): mirror a terminal
-//      Claude Code session into the Gipity DB so the web CLI can display it
-//      read-only. The PostToolUse capture entry is merged alongside the
-//      file-sync one (see setupClaudeHooks). Toggled by the `captureHooks`
-//      field in `.gipity.json` - default on.
-export const HOOKS_SETTINGS = {
-    hooks: {
-        PreToolUse: [
-            {
-                // Soft scaffold reminder. If this is a Gipity project (has
-                // .gipity.json) AND has no scaffold markers (gipity.yaml, src/,
-                // functions/, package.json), nudge the agent to scaffold first
-                // when building an app. Non-blocking - exit 0 always; stderr is
-                // visible to Claude as an advisory. Auto-quiet once any scaffold
-                // marker appears, so it doesn't spam during normal editing.
-                matcher: 'Write|Edit',
-                hooks: [{
-                        type: 'command',
-                        // Embed warning as a single-quoted JS string (safe: shell double
-                        // quotes survive, and SCAFFOLD_HOOK_WARNING is plain ASCII without
-                        // single quotes or backslashes).
-                        command: `node -e "const fs=require('fs');if(!fs.existsSync('.gipity.json'))process.exit(0);const m=['gipity.yaml','src','functions','package.json'].some(p=>fs.existsSync(p));if(m)process.exit(0);process.stderr.write('${SCAFFOLD_HOOK_WARNING.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}\\n');process.exit(0)"`,
-                    }],
-            },
-        ],
-        PostToolUse: [
-            {
-                // File sync for Write/Edit - push any edited file back to the
-                // cloud workspace so web previews see the change.
-                matcher: 'Write|Edit',
-                hooks: [{
-                        type: 'command',
-                        command: `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const p=JSON.parse(d).tool_input?.file_path;if(!p||!require('fs').existsSync('.gipity.json'))process.exit(0);require('child_process').spawn('gipity',['push',p,'--quiet'],{stdio:'ignore',detached:true,shell:true}).unref()}catch{}})"`,
-                    }],
-            },
-        ],
-        UserPromptSubmit: [
-            {
-                // Pull down any cloud-side file changes before the next turn so
-                // the agent sees current state.
-                matcher: '',
-                hooks: [{
-                        type: 'command',
-                        command: `node -e "if(!require('fs').existsSync('.gipity.json'))process.exit(0);require('child_process').exec('gipity sync --json',(e,o)=>{if(e)process.exit(0);try{const r=JSON.parse(o);if(r.applied>0)console.log(JSON.stringify({systemMessage:'Gipity sync: '+(r.summary||'Files changed.')}))}catch{}})"`,
-                    }],
-            },
-        ],
-    },
-};
-/** Build the four lifecycle-hook entries that invoke the bundled capture
- *  runner. Kept as a factory rather than a constant so the absolute
- *  runner path is resolved at install time, reflecting the CLI's current
- *  install location. */
-function buildCaptureHookEntries(source) {
-    const runner = resolveCaptureRunnerPath();
-    const cmd = (event) => `node ${JSON.stringify(runner)} ${source} ${event}`;
-    return {
-        SessionStart: [{ hooks: [{ type: 'command', command: cmd('session-start') }] }],
-        Stop: [{ hooks: [{ type: 'command', command: cmd('stop') }] }],
-        SubagentStop: [{ hooks: [{ type: 'command', command: cmd('subagent-stop') }] }],
-        SessionEnd: [{ hooks: [{ type: 'command', command: cmd('session-end') }] }],
-        // Mid-run incremental flush (matcher '' = every tool). Stop/SessionEnd only
-        // fire on a CLEAN exit, so without this a session that's killed/crashes mid-run
-        // (e.g. a long headless build that times out) loses its whole transcript. The
-        // runner throttles this so it's cheap. Merged alongside the file-sync PostToolUse.
-        PostToolUse: [{ matcher: '', hooks: [{ type: 'command', command: cmd('post-tool-use') }] }],
-    };
+/** Remove Gipity-managed hook entries from a parsed settings object,
+ *  preserving user-authored hooks untouched. Returns true if anything
+ *  was removed. Exported for tests and uninstall. */
+export function stripGipityHooks(settings) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object')
+        return false;
+    let changed = false;
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        const kept = groups
+            .map((group) => {
+            if (!Array.isArray(group?.hooks))
+                return group;
+            const remaining = group.hooks.filter((h) => !(typeof h?.command === 'string' && isGipityManagedHookCommand(h.command)));
+            if (remaining.length !== group.hooks.length)
+                changed = true;
+            return { ...group, hooks: remaining };
+        })
+            .filter((group) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+        if (kept.length === 0)
+            delete hooks[event];
+        else
+            hooks[event] = kept;
+    }
+    if (Object.keys(hooks).length === 0)
+        delete settings.hooks;
+    return changed;
 }
-export function setupClaudeHooks() {
-    const claudeDir = resolve(process.cwd(), '.claude');
-    mkdirSync(claudeDir, { recursive: true });
+function readSettingsFile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return {}; // corrupted - start fresh rather than crash setup
+    }
+}
+/** Ensure the Gipity plugin is enabled at user scope (~/.claude/settings.json)
+ *  via the documented declarative keys: register the marketplace under
+ *  `extraKnownMarketplaces` and enable the plugin under `enabledPlugins`.
+ *  Claude Code fetches both non-interactively at next launch. An explicit
+ *  user disable (`"gipity@gipity": false`) is respected unless `force` -
+ *  the user said no, and `gipity status --repair-hooks` is the deliberate
+ *  way to say yes again. Also strips legacy Gipity hook blocks that older
+ *  CLI versions left in the user-global settings. */
+export function ensureGipityPlugin(force = false) {
+    const claudeDir = join(homedir(), '.claude');
     const settingsPath = join(claudeDir, 'settings.json');
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        }
-        catch {
-            // corrupted - overwrite
-        }
+    const settings = readSettingsFile(settingsPath);
+    let changed = stripGipityHooks(settings);
+    const marketplaces = settings.extraKnownMarketplaces ?? (settings.extraKnownMarketplaces = {});
+    if (!marketplaces[GIPITY_MARKETPLACE_NAME]) {
+        marketplaces[GIPITY_MARKETPLACE_NAME] = {
+            source: { source: 'github', repo: GIPITY_MARKETPLACE_REPO },
+        };
+        changed = true;
     }
-    // Merge capture hooks in only when the project opts in (default true).
-    // `captureHooks === false` in `.gipity.json` disables the mirror-to-web
-    // feature for this project without affecting the file-sync hooks.
-    const captureEnabled = getConfig()?.captureHooks !== false;
-    const captureEntries = captureEnabled ? buildCaptureHookEntries('claude-code') : {};
-    // Merge per-event arrays rather than spread-overwriting: capture and file-sync
-    // both register PostToolUse, and a plain spread would drop one of them.
-    const mergedHooks = { ...HOOKS_SETTINGS.hooks };
-    for (const [event, entries] of Object.entries(captureEntries)) {
-        mergedHooks[event] = [...(mergedHooks[event] ?? []), ...entries];
+    const enabled = settings.enabledPlugins ?? (settings.enabledPlugins = {});
+    if (enabled[GIPITY_PLUGIN_ID] !== true && (force || !(GIPITY_PLUGIN_ID in enabled))) {
+        enabled[GIPITY_PLUGIN_ID] = true;
+        changed = true;
     }
-    settings.hooks = mergedHooks;
+    if (!changed)
+        return;
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+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).
+    ensureGipityPlugin();
+    // Never treat the home directory as a project. A gipity command run from
+    // $HOME used to write "project" hooks straight into the user-global
+    // ~/.claude/settings.json; permissions are project-scoped, so at $HOME
+    // there is nothing project-level left to do.
+    const cwd = resolve(process.cwd());
+    if (cwd === resolve(homedir()))
+        return;
+    const claudeDir = join(cwd, '.claude');
+    mkdirSync(claudeDir, { recursive: true });
+    const settingsPath = join(claudeDir, 'settings.json');
+    const settings = readSettingsFile(settingsPath);
+    // Migration: remove the hook blocks older CLI versions wrote here.
+    stripGipityHooks(settings);
     // Merge permissions (additive - preserve user's existing allows)
     const perms = settings.permissions || {};
     if (!perms.allow)

package/dist/sync.js

@@ -455,17 +455,35 @@ async function applyUpload(projectGuid, root, a, onConflict) {
         throw err;
     }
 }
+/** Name of the optional per-project ignore file (gitignore-style: one pattern
+ *  per line, blank lines and `#` comments skipped). Patterns use the same
+ *  matcher as the config `ignore` list (see shouldIgnore) and let research
+ *  artifacts, scratch data, or vendored references live inside the project
+ *  directory without being synced (and therefore without being deployed). */
+export const GIPITY_IGNORE_FILE = '.gipityignore';
+export function readGipityIgnore(root) {
+    const path = join(root, GIPITY_IGNORE_FILE);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf8')
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line && !line.startsWith('#'))
+        .map(line => line.replace(/^\.\//, '').replace(/^\//, ''));
+}
+/** The ignore list a sync/push actually runs with: the project config's
+ *  `ignore` (falling back to DEFAULT_SYNC_IGNORE when empty, so an empty list
+ *  never means "sync everything - node_modules, .git and all"), plus any
+ *  `.gipityignore` patterns. The ignore file itself never syncs. */
+export function effectiveIgnore(root, configIgnore) {
+    const base = configIgnore && configIgnore.length ? configIgnore : DEFAULT_SYNC_IGNORE;
+    return [...base, GIPITY_IGNORE_FILE, ...readGipityIgnore(root)];
+}
 export async function sync(opts = {}) {
     const config = requireConfig();
     const root = projectDir();
     const interactive = opts.interactive ?? process.stdout.isTTY ?? false;
-    // A config written with an empty `ignore` (older projects, or one produced
-    // by the one-off Home-fallback path) would make sync walk and hash the
-    // entire tree - node_modules, .git, caches and all. Fall back to the
-    // standard ignore set so an empty list never means "sync everything".
-    const ignore = config.ignore && config.ignore.length
-        ? config.ignore
-        : [...DEFAULT_SYNC_IGNORE];
+    const ignore = effectiveIgnore(root, config.ignore);
     const releaseLock = await acquireLock();
     try {
         return await syncInner(config.projectGuid, root, ignore, opts, interactive);
@@ -484,6 +502,15 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
     const local = walkLocal(root, ignore, baseline.files);
     p?.phase('Checking Gipity for changes…');
     const remote = await fetchRemote(projectGuid);
+    // Ignored paths are invisible on BOTH sides: filtering only the local walk
+    // would classify a remote copy as "added" (pull it), then next pass as a
+    // local deletion (delete it remotely) - a churn loop. Filtering remote too
+    // means a path that synced before it was ignored just stays put remotely
+    // (delete it explicitly if it shouldn't be deployed).
+    for (const path of [...remote.keys()]) {
+        if (shouldIgnore(path, ignore))
+            remote.delete(path);
+    }
     // Hash everything we might classify ambiguously. Any local path also on
     // remote (and the remote has a hash) needs a local hash so size-match-but-
     // content-differs isn't misclassified. Anything in baseline that's still
@@ -792,7 +819,7 @@ export async function pushFile(filePath) {
     const config = requireConfig();
     const root = projectDir();
     const rel = relative(root, filePath).replace(/\\/g, '/');
-    if (shouldIgnore(rel, config.ignore))
+    if (shouldIgnore(rel, effectiveIgnore(root, config.ignore)))
         return;
     const baseline = readBaseline(config.projectGuid);
     const baseEntry = baseline.files[rel];

package/package.json

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