gitnexushub 0.4.5 → 0.7.0

package/dist/api.d.ts

@@ -33,6 +33,44 @@ export interface IndexResult {
     fullName: string;
     status: string;
 }
+/**
+ * Response from `POST /api/repos/:id/install-ci-bundle`.
+ *
+ * Hub mints a long-lived CI token + renders the single Claude-led
+ * workflow YAML. `token` and `ciToken` are the same value emitted
+ * twice for back-compat with the v1 client (which read `ciToken`)
+ * and any future caller that reads the more conventional `token`.
+ * Use `ciToken` — the field name documents intent.
+ *
+ * `workflowYaml` is the rendered `.github/workflows/gitnexus.yml`
+ * contents. The CLI base64-encodes and PUTs it via the GitHub
+ * Contents API; no template assembly happens client-side.
+ */
+export interface InstallCiBundle {
+    /** CI token. Same value as `ciToken` — emitted twice for back-compat. */
+    token: string;
+    /** CI token (preferred field name; documents intent). */
+    ciToken: string;
+    /** First 12 chars of the token for display in the CLI summary. */
+    ciTokenPrefix?: string;
+    /** Repo secret name the workflow YAML references for the gnx_ token. */
+    ciTokenSecretName?: string;
+    /** Repo secret name the workflow YAML references for Claude OAuth. */
+    claudeOauthSecretName?: string;
+    /** Rendered `.github/workflows/gitnexus.yml` contents. */
+    workflowYaml: string;
+    /** Hub MCP endpoint URL embedded in the workflow YAML. */
+    hubMcpUrl?: string;
+    /** owner/repo this token + workflow target. */
+    repoFullName: string;
+    /**
+     * Map of relative-path → file-content. Currently always
+     * `{ '.github/workflows/gitnexus.yml': workflowYaml }` — emitted as
+     * an object so future installs can ship sidecar config files (e.g.
+     * `.gitnexus.toml`) without bumping the response shape.
+     */
+    files?: Record<string, string>;
+}
 export interface RepoDetail {
     id: string;
     name: string;
@@ -121,6 +159,24 @@ export interface WikiUploadStatus {
     active: WikiUploadSessionRow | null;
     last: WikiUploadSessionRow | null;
 }
+export interface WikiGroupingContext {
+    communityGroups: string;
+    interCommunityEdges: string;
+    crossCommunityProcesses: string;
+    filesWithExports: string;
+    directoryTree: string;
+    communityMapping?: Array<{
+        label: string;
+        files: string[];
+    }>;
+    filesWithExportsRaw?: Array<{
+        filePath: string;
+        symbols: Array<{
+            name: string;
+            type: string;
+        }>;
+    }>;
+}
 export declare class HubAPI {
     private hubUrl;
     private token;
@@ -135,6 +191,14 @@ export declare class HubAPI {
     listRepos(): Promise<HubRepo[]>;
     getConnectContext(repoFullName: string): Promise<ConnectContext>;
     indexRepo(fullName: string): Promise<IndexResult>;
+    /**
+     * Mint a CI token for the given repo and fetch the rendered
+     * Claude-led workflow YAML in one call. Hub atomically revokes
+     * any prior `GitNexus CI` token for this repo and mints a fresh
+     * one — calling this repeatedly is safe and idempotent (the prior
+     * token stops working, the new one starts).
+     */
+    installCiBundle(repoId: string): Promise<InstallCiBundle>;
     getRepo(repoId: string): Promise<RepoDetail>;
     meta(repoId: string): Promise<RepoMeta>;
     sync(repoId: string, params: {
@@ -158,7 +222,32 @@ export declare class HubAPI {
     }>;
     wikiUploadStatus(repoId: string): Promise<WikiUploadStatus>;
     getWikiConfig(): Promise<WikiConfig>;
-    wikiGroupingContext(repoId: string): Promise<any>;
+    wikiGroupingContext(repoId: string): Promise<WikiGroupingContext>;
+    wikiStatus(repoId: string): Promise<{
+        status: string;
+        fromCommit?: string | null;
+        generatedAt?: string | null;
+        pageCount?: number;
+        generating?: boolean;
+    } | null>;
+    wikiTree(repoId: string): Promise<{
+        tree: Array<{
+            name: string;
+            slug: string;
+            files: string[];
+            children?: Array<{
+                name: string;
+                slug: string;
+                files: string[];
+            }>;
+        }>;
+    } | null>;
+    wikiPage(repoId: string, slug: string): Promise<{
+        slug: string;
+        title: string;
+        content: string;
+        updatedAt: string;
+    } | null>;
     wikiLeafContext(repoId: string, moduleName: string, filePaths: string[]): Promise<any>;
     wikiOverviewContext(repoId: string, moduleFiles: Record<string, string[]>): Promise<any>;
     wikiPromptTemplates(repoId: string): Promise<{

package/dist/api.js

@@ -77,6 +77,16 @@ export class HubAPI {
     async indexRepo(fullName) {
         return this.post('/api/repos/public', { fullName });
     }
+    /**
+     * Mint a CI token for the given repo and fetch the rendered
+     * Claude-led workflow YAML in one call. Hub atomically revokes
+     * any prior `GitNexus CI` token for this repo and mints a fresh
+     * one — calling this repeatedly is safe and idempotent (the prior
+     * token stops working, the new one starts).
+     */
+    async installCiBundle(repoId) {
+        return this.post(`/api/repos/${repoId}/install-ci-bundle`, {});
+    }
     async getRepo(repoId) {
         return this.request(`/api/repos/${repoId}`);
     }
@@ -143,6 +153,30 @@ export class HubAPI {
     async wikiGroupingContext(repoId) {
         return this.request(`/api/repos/${repoId}/wiki/context/grouping`);
     }
+    async wikiStatus(repoId) {
+        try {
+            return await this.request(`/api/repos/${repoId}/wiki/status`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async wikiTree(repoId) {
+        try {
+            return await this.request(`/api/repos/${repoId}/wiki/tree`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async wikiPage(repoId, slug) {
+        try {
+            return await this.request(`/api/repos/${repoId}/wiki/page/${encodeURIComponent(slug)}`);
+        }
+        catch {
+            return null;
+        }
+    }
     async wikiLeafContext(repoId, moduleName, filePaths) {
         const params = new URLSearchParams({ name: moduleName, files: filePaths.join(',') });
         return this.request(`/api/repos/${repoId}/wiki/context/leaf?${params}`);

package/dist/cli-helpers.js

@@ -12,11 +12,13 @@ import { claudeCodeEditor } from './editors/claude-code.js';
 import { cursorEditor } from './editors/cursor.js';
 import { windsurfEditor } from './editors/windsurf.js';
 import { opencodeEditor } from './editors/opencode.js';
+import { kiroEditor } from './editors/kiro.js';
 export const EDITORS = {
     'claude-code': claudeCodeEditor,
     cursor: cursorEditor,
     windsurf: windsurfEditor,
     opencode: opencodeEditor,
+    kiro: kiroEditor,
 };
 export const ok = (msg) => console.log(`  ${pc.green('✔')} ${msg}`);
 export const info = (msg) => console.log(`  ${pc.cyan('ℹ')} ${msg}`);

package/dist/connect-command.js

@@ -13,7 +13,7 @@ import { generateConnectContext } from './content.js';
 import { isGitRepo, getGitRemoteUrl, parseGitRemote, matchRepo } from './project.js';
 import { writeProjectContext } from './context.js';
 import { detectInstalledEditors } from './editors/detect.js';
-import { installClaudeCodeHook, installCursorHook, installOpenCodeHook, } from './hooks-installer.js';
+import { installClaudeCodeHook, installCursorHook, installKiroHook, installOpenCodeHook, } from './hooks-installer.js';
 import { ok, info, warn, fail, resolveAuth, EDITORS } from './cli-helpers.js';
 /**
  * Resolve the path to the shipped hook script (`gitnexus-enterprise-hook.cjs`).
@@ -65,7 +65,7 @@ export async function runConnect(tokenArg, opts) {
         }
         else {
             fail('No editor detected. Please specify one:');
-            console.error(`      ${pc.cyan('--editor claude-code | cursor | windsurf | opencode')}`);
+            console.error(`      ${pc.cyan('--editor claude-code | cursor | windsurf | opencode | kiro')}`);
             console.error('');
             return process.exit(1);
         }
@@ -116,6 +116,10 @@ export async function runConnect(tokenArg, opts) {
                 await installOpenCodeHook({ hookScriptPath });
                 ok('Hooks installed');
             }
+            else if (editorId === 'kiro') {
+                await installKiroHook({ hookScriptPath });
+                ok('Hooks installed');
+            }
             // windsurf: no hook system, skip silently
         }
         catch (err) {

package/dist/context.js

@@ -5,7 +5,7 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
-import { upsertMarkedSection, removeMarkedSection } from './utils.js';
+import { upsertMarkedSection, removeMarkedSection, fileExists } from './utils.js';
 export async function writeProjectContext(projectDir, ctx) {
     const files = [];
     // Write CLAUDE.md
@@ -16,6 +16,31 @@ export async function writeProjectContext(projectDir, ctx) {
     const agentsPath = path.join(projectDir, 'AGENTS.md');
     const agentsResult = await upsertMarkedSection(agentsPath, ctx.agentsMd);
     files.push(`AGENTS.md (${agentsResult})`);
+    // Write Kiro steering doc — Kiro doesn't read AGENTS.md / CLAUDE.md,
+    // so we mirror the same content into .kiro/steering/gitnexus.md with
+    // `inclusion: always` frontmatter so it's loaded into every Kiro
+    // chat in this workspace.
+    //
+    // Unlike CLAUDE.md / AGENTS.md (which may carry hand-written user
+    // content alongside the gitnexus block), this file is dedicated to
+    // gitnexus — it's named gitnexus.md, lives in a gitnexus-managed
+    // path, and isn't expected to host anything else. So we rewrite the
+    // whole file every run instead of using upsertMarkedSection. The
+    // previous marker-based approach broke because the YAML frontmatter
+    // sat *outside* the gitnexus markers (Kiro requires frontmatter on
+    // line 1), so each re-run's "before" prefix re-included the existing
+    // frontmatter and stacked another copy on top — Bugbot caught the
+    // accumulation on commit de24e98c.
+    const kiroSteeringPath = path.join(projectDir, '.kiro', 'steering', 'gitnexus.md');
+    const kiroBody = `---\n` +
+        `inclusion: always\n` +
+        `description: GitNexus code intelligence — graph-backed query, context, and impact tools\n` +
+        `---\n\n` +
+        `${ctx.agentsMd}\n`;
+    const kiroExisted = await fileExists(kiroSteeringPath);
+    await fs.mkdir(path.dirname(kiroSteeringPath), { recursive: true });
+    await fs.writeFile(kiroSteeringPath, kiroBody, 'utf-8');
+    files.push(`.kiro/steering/gitnexus.md (${kiroExisted ? 'updated' : 'created'})`);
     // Write skills to .claude/skills/gitnexus/
     if (ctx.skills.length > 0) {
         const skillsDir = path.join(projectDir, '.claude', 'skills', 'gitnexus');
@@ -30,13 +55,27 @@ export async function writeProjectContext(projectDir, ctx) {
 }
 export async function removeProjectContext(projectDir) {
     const removed = [];
-    // Remove marked sections from CLAUDE.md and AGENTS.md
+    // CLAUDE.md / AGENTS.md may carry user content; only strip the
+    // gitnexus-marked block.
     for (const name of ['CLAUDE.md', 'AGENTS.md']) {
         const filePath = path.join(projectDir, name);
         if (await removeMarkedSection(filePath)) {
             removed.push(name);
         }
     }
+    // The Kiro steering doc is dedicated to gitnexus (no user content
+    // ever lives here, no markers are written), so delete the file
+    // outright when it exists.
+    const kiroSteeringPath = path.join(projectDir, '.kiro', 'steering', 'gitnexus.md');
+    if (await fileExists(kiroSteeringPath)) {
+        try {
+            await fs.unlink(kiroSteeringPath);
+            removed.push('.kiro/steering/gitnexus.md');
+        }
+        catch {
+            // Already gone
+        }
+    }
     // Remove .claude/skills/gitnexus/ directory
     const skillsDir = path.join(projectDir, '.claude', 'skills', 'gitnexus');
     try {

package/dist/editors/detect.js

@@ -27,6 +27,11 @@ const PROBES = [
         name: 'OpenCode',
         dirs: [path.join(os.homedir(), '.config', 'opencode')],
     },
+    {
+        id: 'kiro',
+        name: 'Kiro',
+        dirs: [path.join(os.homedir(), '.kiro')],
+    },
 ];
 export async function detectInstalledEditors() {
     const found = [];

package/dist/editors/kiro.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Kiro Editor Setup
+ *
+ * Writes MCP config to ~/.kiro/settings/mcp.json
+ * Installs skill content as steering files in ~/.kiro/steering/
+ *
+ * Kiro (kiro.dev) doesn't have a SKILL.md system like Claude Code or
+ * Cursor — its closest concept is "steering" (always-on guidance docs
+ * with optional frontmatter for fileMatch / manual inclusion modes).
+ * We emit each Hub skill as `~/.kiro/steering/gitnexus-<name>.md` with
+ * `inclusion: manual` so the user pulls them in via `#gitnexus-<name>`
+ * in chat — same mental model as `/gitnexus-<name>` in Claude Code.
+ */
+import type { EditorConfig } from './types.js';
+export declare const kiroEditor: EditorConfig;

package/dist/editors/kiro.js

@@ -0,0 +1,118 @@
+/**
+ * Kiro Editor Setup
+ *
+ * Writes MCP config to ~/.kiro/settings/mcp.json
+ * Installs skill content as steering files in ~/.kiro/steering/
+ *
+ * Kiro (kiro.dev) doesn't have a SKILL.md system like Claude Code or
+ * Cursor — its closest concept is "steering" (always-on guidance docs
+ * with optional frontmatter for fileMatch / manual inclusion modes).
+ * We emit each Hub skill as `~/.kiro/steering/gitnexus-<name>.md` with
+ * `inclusion: manual` so the user pulls them in via `#gitnexus-<name>`
+ * in chat — same mental model as `/gitnexus-<name>` in Claude Code.
+ */
+import os from 'os';
+import path from 'path';
+import fs from 'fs/promises';
+import { readJsonFile, writeJsonFile } from '../utils.js';
+import { HUB_SKILLS } from '../content.js';
+import { computeFingerprint, getDeviceName } from '../fingerprint.js';
+function getMcpConfig(hubUrl, token) {
+    // Kiro's `~/.kiro/settings/mcp.json` is documented at
+    // kiro.dev/docs/mcp/configuration. Remote HTTP MCP servers are
+    // identified by the presence of `url`. `disabled: false` and the
+    // `autoApprove` array are optional — we leave them off so Kiro
+    // falls back to its sensible defaults (auto-approval prompts on
+    // first call).
+    return {
+        url: `${hubUrl}/mcp`,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'X-Device-Fingerprint': computeFingerprint(),
+            'X-Device-Name': getDeviceName(),
+        },
+    };
+}
+async function configure(hubUrl, token) {
+    const mcpPath = path.join(os.homedir(), '.kiro', 'settings', 'mcp.json');
+    try {
+        const existing = (await readJsonFile(mcpPath)) || {};
+        if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+            existing.mcpServers = {};
+        }
+        const overrodeCli = !!(existing.mcpServers.gitnexus && 'command' in existing.mcpServers.gitnexus);
+        existing.mcpServers.gitnexus = getMcpConfig(hubUrl, token);
+        await writeJsonFile(mcpPath, existing);
+        return { success: true, message: 'MCP configured in ~/.kiro/settings/mcp.json', overrodeCli };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+/**
+ * Wrap raw skill content in a steering frontmatter block so Kiro
+ * treats it as a manually-included guidance doc. Without the
+ * `inclusion: manual` line Kiro defaults to `always`, which would
+ * shove every GitNexus skill into every chat turn — far too noisy.
+ */
+function toSteeringDoc(name, body) {
+    return `---
+inclusion: manual
+description: ${name} (GitNexus skill — invoke via #${name})
+---
+
+${body.trim()}
+`;
+}
+async function installSkills(skills) {
+    const steeringDir = path.join(os.homedir(), '.kiro', 'steering');
+    let installed = 0;
+    await fs.mkdir(steeringDir, { recursive: true });
+    for (const skill of skills) {
+        try {
+            const filePath = path.join(steeringDir, `${skill.name}.md`);
+            await fs.writeFile(filePath, toSteeringDoc(skill.name, skill.content), 'utf-8');
+            installed++;
+        }
+        catch {
+            // Skip on error
+        }
+    }
+    return installed;
+}
+async function unconfigure() {
+    const mcpPath = path.join(os.homedir(), '.kiro', 'settings', 'mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        if (existing?.mcpServers?.gitnexus) {
+            delete existing.mcpServers.gitnexus;
+            await writeJsonFile(mcpPath, existing);
+        }
+        return { success: true, message: 'MCP removed from ~/.kiro/settings/mcp.json' };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+async function removeSkills() {
+    const steeringDir = path.join(os.homedir(), '.kiro', 'steering');
+    let removed = 0;
+    for (const name of HUB_SKILLS) {
+        try {
+            await fs.rm(path.join(steeringDir, `${name}.md`), { force: true });
+            removed++;
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    return removed;
+}
+export const kiroEditor = {
+    id: 'kiro',
+    name: 'Kiro',
+    configure,
+    unconfigure,
+    installSkills,
+    removeSkills,
+};

package/dist/editors/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Editor Types
  */
-export type EditorId = 'claude-code' | 'cursor' | 'windsurf' | 'opencode';
+export type EditorId = 'claude-code' | 'cursor' | 'windsurf' | 'opencode' | 'kiro';
 export interface EditorConfig {
     id: EditorId;
     name: string;

package/dist/hooks-installer.d.ts

@@ -17,10 +17,42 @@ export interface InstallOptions {
  */
 export declare function installClaudeCodeHook(opts: InstallOptions): Promise<string>;
 /**
- * Install the Cursor beforeShellExecution hook.
+ * Install the Cursor preToolUse + postToolUse hooks.
  * Returns the absolute path to the written hooks.json.
+ *
+ * Cursor 2.4+ hooks live at ~/.cursor/hooks.json with a
+ *   { version: 1, hooks: { <eventName>: [{ command, ... }] } }
+ * shape (cursor.com/docs/hooks). We register `preToolUse` for
+ * graph-context augmentation on Shell/Read/Write, and `postToolUse`
+ * for staleness detection after `git commit/merge/...` and for
+ * edit-closure capture on Edit/Write/MultiEdit.
+ *
+ * The earlier 0.6.0 implementation used `beforeShellExecution`,
+ * which:
+ *   1. fires *before* shell execution — wrong direction for the
+ *      git-staleness post-commit nudge,
+ *   2. sends a different stdin shape (no `tool_name`/`tool_input`),
+ *      so the hook script silently bails on the event check,
+ *   3. has no documented context-injection envelope.
+ * Switching to pre/postToolUse fixes all three.
  */
 export declare function installCursorHook(opts: InstallOptions): Promise<string>;
+/**
+ * Install the Kiro graph-context + staleness hooks.
+ * Returns the absolute paths to both written hook files.
+ *
+ * Kiro hooks (kiro.dev/docs/hooks/types) live as one JSON file per
+ * hook under `.kiro/hooks/<name>.kiro.hook`. Trigger names are kebab-
+ * case ("pre-tool-use" / "post-tool-use"), matching the Claude Code
+ * PreToolUse/PostToolUse semantics. The gitnexus hook script handles
+ * both — it normalises the kebab-case event name back to PascalCase
+ * internally so a single script serves Kiro + Claude Code + Cursor +
+ * OpenCode.
+ *
+ * We register two hook files because Kiro's hook spec is one trigger
+ * per file; bundling both into a single file would silently lose one.
+ */
+export declare function installKiroHook(opts: InstallOptions): Promise<string[]>;
 /**
  * Install the OpenCode plugin stub.
  * Returns the absolute path to the written TypeScript file.

package/dist/hooks-installer.js

@@ -16,6 +16,35 @@ async function writeJsonIdempotent(filePath, obj) {
     const body = JSON.stringify(obj, null, 2) + '\n';
     await fs.writeFile(filePath, body);
 }
+/**
+ * Quote a path for embedding in a shell-style command string. The
+ * hook spec across Claude Code / Cursor / Kiro is a literal shell
+ * command, not an argv array — so spaces (`John Doe`) and stray
+ * quotes both have to survive shell parsing. Wraps in `"..."` and
+ * escapes any `"` already inside the path so the shell sees a single
+ * argument.
+ *
+ * Realistic risk of `"` inside the path is near-zero (npm install
+ * dirs, Windows profile dirs), but matching the same defensive quoting
+ * the OSS gitnexus/src/cli/setup.ts uses keeps the two installers
+ * symmetrical.
+ */
+function shellQuote(p) {
+    return `"${p.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Read an existing JSON file, returning null if the file is absent
+ * or unparseable. Used by installers that need to merge into a
+ * shared config rather than clobber it.
+ */
+async function readJsonOrNull(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Install the Claude Code PreToolUse + PostToolUse hooks.
  * Returns the absolute path to the written hooks.json.
@@ -24,11 +53,15 @@ export async function installClaudeCodeHook(opts) {
     const home = getHome(opts);
     const hooksDir = path.join(home, '.claude', 'plugins', 'gitnexus-enterprise', 'hooks');
     const hooksJsonPath = path.join(hooksDir, 'hooks.json');
-    // Double-quote the absolute path so shell splitting doesn't break
-    // when the install dir contains a space (e.g. Windows profiles at
-    // `C:\Users\John Doe\...`). The hook spec is a shell-style command
-    // string, not an argv array, so quoting is the only knob available.
-    const quotedScriptPath = `"${opts.hookScriptPath}"`;
+    // Double-quote (and escape any embedded quotes) so shell splitting
+    // doesn't break when the install dir contains a space (e.g. Windows
+    // profiles at `C:\Users\John Doe\...`). The hook spec is a shell-
+    // style command string, not an argv array, so quoting is the only
+    // knob available. The `--agent=claude-code` flag tells the hook
+    // script which editor it's running under so /api/activity captures
+    // get the right agentName (the stdin payload alone can't
+    // distinguish editors that share the PascalCase MCP event names).
+    const command = `node ${shellQuote(opts.hookScriptPath)} --agent=claude-code`;
     const config = {
         hooks: {
             PreToolUse: [
@@ -37,7 +70,7 @@ export async function installClaudeCodeHook(opts) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `node ${quotedScriptPath}`,
+                            command,
                             timeout: 5,
                         },
                     ],
@@ -49,7 +82,7 @@ export async function installClaudeCodeHook(opts) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `node ${quotedScriptPath}`,
+                            command,
                             timeout: 5,
                         },
                     ],
@@ -61,24 +94,92 @@ export async function installClaudeCodeHook(opts) {
     return hooksJsonPath;
 }
 /**
- * Install the Cursor beforeShellExecution hook.
+ * Install the Cursor preToolUse + postToolUse hooks.
  * Returns the absolute path to the written hooks.json.
+ *
+ * Cursor 2.4+ hooks live at ~/.cursor/hooks.json with a
+ *   { version: 1, hooks: { <eventName>: [{ command, ... }] } }
+ * shape (cursor.com/docs/hooks). We register `preToolUse` for
+ * graph-context augmentation on Shell/Read/Write, and `postToolUse`
+ * for staleness detection after `git commit/merge/...` and for
+ * edit-closure capture on Edit/Write/MultiEdit.
+ *
+ * The earlier 0.6.0 implementation used `beforeShellExecution`,
+ * which:
+ *   1. fires *before* shell execution — wrong direction for the
+ *      git-staleness post-commit nudge,
+ *   2. sends a different stdin shape (no `tool_name`/`tool_input`),
+ *      so the hook script silently bails on the event check,
+ *   3. has no documented context-injection envelope.
+ * Switching to pre/postToolUse fixes all three.
  */
 export async function installCursorHook(opts) {
     const home = getHome(opts);
     const hooksJsonPath = path.join(home, '.cursor', 'hooks.json');
-    // Same shell-quoting rationale as installClaudeCodeHook — the
-    // command is a shell string, not argv, so the absolute path must
-    // be quoted to survive spaces.
-    const config = {
-        beforeShellExecution: {
-            command: `node "${opts.hookScriptPath}"`,
-            timeout: 5000,
-        },
-    };
-    await writeJsonIdempotent(hooksJsonPath, config);
+    const command = `node ${shellQuote(opts.hookScriptPath)} --agent=cursor`;
+    // Merge into the user's existing ~/.cursor/hooks.json instead of
+    // clobbering it — that file is the GLOBAL Cursor hooks config and
+    // may already carry the user's own audit / lint hooks. Idempotent:
+    // re-running replaces only the gitnexus entries (matched by their
+    // command containing "gitnexus-enterprise-hook") and leaves
+    // unrelated event arrays + entries intact.
+    const existing = (await readJsonOrNull(hooksJsonPath)) || {};
+    if (typeof existing.version !== 'number')
+        existing.version = 1;
+    if (!existing.hooks || typeof existing.hooks !== 'object')
+        existing.hooks = {};
+    function upsertGitNexus(eventName, matcher, timeout) {
+        const arr = Array.isArray(existing.hooks[eventName])
+            ? existing.hooks[eventName]
+            : [];
+        const filtered = arr.filter((e) => !e.command?.includes('--agent=cursor'));
+        filtered.push({ matcher, command, timeout });
+        existing.hooks[eventName] = filtered;
+    }
+    upsertGitNexus('preToolUse', 'Shell|Read|Write', 5);
+    upsertGitNexus('postToolUse', 'Shell|Edit|Write|MultiEdit', 5);
+    await fs.mkdir(path.dirname(hooksJsonPath), { recursive: true });
+    await fs.writeFile(hooksJsonPath, JSON.stringify(existing, null, 2) + '\n');
     return hooksJsonPath;
 }
+/**
+ * Install the Kiro graph-context + staleness hooks.
+ * Returns the absolute paths to both written hook files.
+ *
+ * Kiro hooks (kiro.dev/docs/hooks/types) live as one JSON file per
+ * hook under `.kiro/hooks/<name>.kiro.hook`. Trigger names are kebab-
+ * case ("pre-tool-use" / "post-tool-use"), matching the Claude Code
+ * PreToolUse/PostToolUse semantics. The gitnexus hook script handles
+ * both — it normalises the kebab-case event name back to PascalCase
+ * internally so a single script serves Kiro + Claude Code + Cursor +
+ * OpenCode.
+ *
+ * We register two hook files because Kiro's hook spec is one trigger
+ * per file; bundling both into a single file would silently lose one.
+ */
+export async function installKiroHook(opts) {
+    const home = getHome(opts);
+    const hooksDir = path.join(home, '.kiro', 'hooks');
+    // `--agent=kiro` tags /api/activity captures so distillation can
+    // split rows by editor — Kiro's kebab-case events would also let
+    // detectAgent infer "kiro", but explicit > inferred.
+    const cmd = `node ${shellQuote(opts.hookScriptPath)} --agent=kiro`;
+    const preHookPath = path.join(hooksDir, 'gitnexus-graph-context.kiro.hook');
+    const postHookPath = path.join(hooksDir, 'gitnexus-staleness-check.kiro.hook');
+    await writeJsonIdempotent(preHookPath, {
+        name: 'gitnexus-graph-context',
+        description: 'Inject GitNexus graph context (callers, callees, impact) before Grep/Glob/Bash tool calls',
+        trigger: { type: 'pre-tool-use' },
+        actions: [{ type: 'shell', command: cmd }],
+    });
+    await writeJsonIdempotent(postHookPath, {
+        name: 'gitnexus-staleness-check',
+        description: 'Capture file edits (edit-closure) and nudge to gnx sync after git commit/merge/rebase',
+        trigger: { type: 'post-tool-use' },
+        actions: [{ type: 'shell', command: cmd }],
+    });
+    return [preHookPath, postHookPath];
+}
 /**
  * Install the OpenCode plugin stub.
  * Returns the absolute path to the written TypeScript file.
@@ -95,6 +196,12 @@ export async function installOpenCodeHook(opts) {
     const content = `// GitNexus Enterprise OpenCode plugin
 // Stub — delegates to gitnexus-enterprise-hook.cjs via child process.
 // Hook script: ${opts.hookScriptPath}
+//
+// When wiring up the real spawn() call, pass --agent=opencode so
+// /api/activity captures land with agentName='opencode' (otherwise
+// the script defaults to 'claude-code', which corrupts distillation).
+// Example:
+//   spawn('node', [HOOK_PATH, '--agent=opencode'], { stdio: ... })
 
 export default {
   async toolBefore(ctx: { tool: string }) {