From 6ee387f39fbce97861cfda1118682ff82329bf8a Mon Sep 17 00:00:00 2001
From: geobelsky <geobelsky@gmail.com>
Date: Sun, 10 May 2026 09:16:26 +0000
Subject: [PATCH 1/6] feat(cursor): add IDE abstraction layer and Cursor hook
 adapter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 / 3 of cursor-full-support series — purely additive abstractions
that let later PRs ship Cursor setup writers and a Cursor SDK adapter
without re-touching the hook hot path.

- New src/utils/ide-detect.ts: IdeKind type + parseIdeFlag(argv) +
  detectIdeFromEnv + detectIdeFromHookStdin + resolveIde precedence
  (argv → env → stdin heuristic → claude-code default).
- New src/hooks/adapters/{types,claude-code,cursor}.ts: NormalizedHookEvent
  + HookInputAdapter / HookOutputAdapter contracts; per-IDE stdin parsers
  (Cursor: conversation_id, cursor_version, transcript_path|null);
  per-IDE deny emitters (Claude: hookSpecificOutput JSON, exit 0;
  Cursor: flat permission/user_message JSON, exit 2).
- Refactor src/hooks/{pre,post,session-end}.ts to consume
  NormalizedHookEvent + a HookOutputAdapter. Safety-checking core in
  pre-tool-use.ts is byte-identical for Claude Code users.
- src/cli.ts case "hook" now parses --ide and forwards into the right
  adapter; defaults to claude-code so existing setups are unaffected.
- src/audit-spawner.ts forwards --ide to the detached worker argv (used
  by PR-3 to dispatch the correct transcript parser).
- src/types.ts: add IdeKind type; ClaudeSessionRef gains optional
  ide?: IdeKind. ensureAxmeSessionForClaude / attachClaudeSession in
  src/storage/sessions.ts thread the optional ide param through.

Tests (+30): test/ide-detect.test.ts covers flag/env/stdin precedence;
test/cursor-hook-adapter.test.ts covers Cursor stdin parsing (incl.
session_id vs conversation_id selection per hook kind, transcript_path
null-preservation) and exit-code-2 deny emission; test/
claude-code-hook-adapter.test.ts asserts byte-for-byte regression of
the existing deny JSON.

Full suite: 572 / 572 (was 542). tsc --noEmit clean. npm run build
clean. No behaviour change for Claude Code users.

Decisions: D-145 (Phase 1 ships before VS Code Extension). Memories
saved: cursor-sdk-system-prompt-via-inline-agent-definition,
cursor-hook-protocol-exit-code-2-deny, cursor-sdk-1-0-12-no-win-arm64,
cursor-agent-transcript-format-jsonl-with-top-level-role.

#!axme pr=none repo=AxmeAI/axme-code
---
 src/audit-spawner.ts                  |  16 +++-
 src/cli.ts                            |   9 ++-
 src/hooks/adapters/claude-code.ts     |  55 +++++++++++++
 src/hooks/adapters/cursor.ts          |  84 ++++++++++++++++++++
 src/hooks/adapters/types.ts           |  50 ++++++++++++
 src/hooks/post-tool-use.ts            |  50 +++++++-----
 src/hooks/pre-tool-use.ts             |  64 ++++++++-------
 src/hooks/session-end.ts              |  54 +++++++------
 src/storage/sessions.ts               |  13 +++-
 src/types.ts                          |  12 +++
 src/utils/ide-detect.ts               |  76 ++++++++++++++++++
 test/claude-code-hook-adapter.test.ts |  74 ++++++++++++++++++
 test/cursor-hook-adapter.test.ts      | 107 ++++++++++++++++++++++++++
 test/ide-detect.test.ts               | 105 +++++++++++++++++++++++++
 14 files changed, 686 insertions(+), 83 deletions(-)
 create mode 100644 src/hooks/adapters/claude-code.ts
 create mode 100644 src/hooks/adapters/cursor.ts
 create mode 100644 src/hooks/adapters/types.ts
 create mode 100644 src/utils/ide-detect.ts
 create mode 100644 test/claude-code-hook-adapter.test.ts
 create mode 100644 test/cursor-hook-adapter.test.ts
 create mode 100644 test/ide-detect.test.ts

diff --git a/src/audit-spawner.ts b/src/audit-spawner.ts
index 10f2e21..3583834 100644
--- a/src/audit-spawner.ts
+++ b/src/audit-spawner.ts
@@ -30,6 +30,7 @@ import { openSync, closeSync } from "node:fs";
 import { join } from "node:path";
 import { ensureDir } from "./storage/engine.js";
 import { AXME_CODE_DIR } from "./types.js";
+import type { IdeKind } from "./types.js";
 
 const AUDIT_WORKER_LOGS_DIR = "audit-worker-logs";
 
@@ -49,7 +50,14 @@ const AUDIT_WORKER_LOGS_DIR = "audit-worker-logs";
  *     parent may be exiting imminently and holding a pipe fd open would
  *     kill the writer once the reader closes)
  */
-export function spawnDetachedAuditWorker(workspacePath: string, sessionId: string): void {
+export function spawnDetachedAuditWorker(
+  workspacePath: string,
+  sessionId: string,
+  /** Which IDE produced this session — forwarded to the worker so the
+   *  auditor can dispatch the right transcript parser. Optional for
+   *  backward compatibility; absent value means "claude-code". */
+  ide?: IdeKind,
+): void {
   const logsDir = join(workspacePath, AXME_CODE_DIR, AUDIT_WORKER_LOGS_DIR);
   ensureDir(logsDir);
   const logPath = join(logsDir, `${sessionId}.log`);
@@ -62,9 +70,11 @@ export function spawnDetachedAuditWorker(workspacePath: string, sessionId: strin
   try {
     const cliPath = process.argv[1];
     if (!cliPath) throw new Error("audit-spawner: cannot determine CLI path from process.argv[1]");
+    const argv: string[] = [cliPath, "audit-session", "--workspace", workspacePath, "--session", sessionId];
+    if (ide) argv.push("--ide", ide);
     const child = spawn(
       process.execPath,
-      [cliPath, "audit-session", "--workspace", workspacePath, "--session", sessionId],
+      argv,
       {
         detached: true,
         stdio: ["ignore", fd, fd],
@@ -73,7 +83,7 @@ export function spawnDetachedAuditWorker(workspacePath: string, sessionId: strin
     );
     child.unref();
     process.stderr.write(
-      `AXME: spawned detached audit worker pid=${child.pid} session=${sessionId} log=${logPath}\n`,
+      `AXME: spawned detached audit worker pid=${child.pid} session=${sessionId} ide=${ide ?? "claude-code"} log=${logPath}\n`,
     );
   } finally {
     // The child now holds its own dup of the fd; we can close our copy.
diff --git a/src/cli.ts b/src/cli.ts
index 2f81492..156f6b8 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -558,16 +558,19 @@ async function main() {
       // Parse --workspace flag from CLI args
       const wsIdx = args.indexOf("--workspace");
       const workspacePath = wsIdx >= 0 && args[wsIdx + 1] ? args[wsIdx + 1] : undefined;
+      // Parse --ide flag from CLI args (defaults to claude-code).
+      const { parseIdeFlag } = await import("./utils/ide-detect.js");
+      const ide = parseIdeFlag(args) ?? "claude-code";
 
       if (hookName === "pre-tool-use") {
         const { runPreToolUseHook } = await import("./hooks/pre-tool-use.js");
-        await runPreToolUseHook(workspacePath);
+        await runPreToolUseHook(workspacePath, ide);
       } else if (hookName === "post-tool-use") {
         const { runPostToolUseHook } = await import("./hooks/post-tool-use.js");
-        await runPostToolUseHook(workspacePath);
+        await runPostToolUseHook(workspacePath, ide);
       } else if (hookName === "session-end") {
         const { runSessionEndHook } = await import("./hooks/session-end.js");
-        await runSessionEndHook(workspacePath);
+        await runSessionEndHook(workspacePath, ide);
       }
       break;
     }
diff --git a/src/hooks/adapters/claude-code.ts b/src/hooks/adapters/claude-code.ts
new file mode 100644
index 0000000..c6f9475
--- /dev/null
+++ b/src/hooks/adapters/claude-code.ts
@@ -0,0 +1,55 @@
+/**
+ * Claude Code hook adapter.
+ *
+ * Stdin shape (per Anthropic's hooks API):
+ *   { tool_name, tool_input, session_id?, transcript_path? }
+ *
+ * Deny is signalled by writing a JSON object to stdout and exiting 0. Exit
+ * codes are not used to convey allow/deny; only the JSON payload matters:
+ *
+ *   { hookSpecificOutput: { hookEventName, permissionDecision, permissionDecisionReason } }
+ */
+
+import type { HookInputAdapter, HookKind, HookOutputAdapter, NormalizedHookEvent, DenyResult } from "./types.js";
+
+function pascalCaseFor(kind: HookKind): string {
+  switch (kind) {
+    case "preToolUse": return "PreToolUse";
+    case "postToolUse": return "PostToolUse";
+    case "sessionEnd": return "SessionEnd";
+  }
+}
+
+export const claudeCodeInputAdapter: HookInputAdapter = {
+  parse(raw, kind): NormalizedHookEvent {
+    const obj = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+    const toolName = typeof obj.tool_name === "string" ? obj.tool_name : undefined;
+    const toolInput = (obj.tool_input && typeof obj.tool_input === "object")
+      ? obj.tool_input as Record<string, unknown>
+      : undefined;
+    const sessionId = typeof obj.session_id === "string" ? obj.session_id : undefined;
+    const transcriptPath = typeof obj.transcript_path === "string" ? obj.transcript_path : undefined;
+    return {
+      kind,
+      ide: "claude-code",
+      toolName,
+      toolInput,
+      sessionId,
+      transcriptPath,
+      raw: obj,
+    };
+  },
+};
+
+export const claudeCodeOutputAdapter: HookOutputAdapter = {
+  emitDeny(reason, kind): DenyResult {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: pascalCaseFor(kind),
+        permissionDecision: "deny",
+        permissionDecisionReason: `[AXME Safety] ${reason}`,
+      },
+    };
+    return { stdout: JSON.stringify(output), exitCode: 0 };
+  },
+};
diff --git a/src/hooks/adapters/cursor.ts b/src/hooks/adapters/cursor.ts
new file mode 100644
index 0000000..f5d160e
--- /dev/null
+++ b/src/hooks/adapters/cursor.ts
@@ -0,0 +1,84 @@
+/**
+ * Cursor hook adapter.
+ *
+ * Stdin shape (verified against cursor.com/docs/agent/hooks, 2026-05):
+ *   common base fields:
+ *     conversation_id, generation_id, model, hook_event_name,
+ *     cursor_version, workspace_roots[], user_email?, transcript_path|null
+ *   preToolUse / postToolUse add:
+ *     tool_name, tool_input, tool_use_id, cwd, agent_message
+ *   sessionEnd adds:
+ *     session_id, reason ("completed"|"aborted"|"error"|"window_close"|...),
+ *     duration_ms, is_background_agent, final_status, error_message?
+ *
+ * Deny on preToolUse / beforeShellExecution / beforeMCPExecution:
+ *   stdout JSON: { permission: "allow"|"deny"|"ask", user_message, agent_message, updated_input? }
+ *   exit code 0 = success, 2 = deny, other = fail-open
+ */
+
+import type { HookInputAdapter, HookKind, HookOutputAdapter, NormalizedHookEvent, DenyResult } from "./types.js";
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+function asObject(v: unknown): Record<string, unknown> | undefined {
+  return v && typeof v === "object" && !Array.isArray(v)
+    ? v as Record<string, unknown>
+    : undefined;
+}
+
+export const cursorInputAdapter: HookInputAdapter = {
+  parse(raw, kind): NormalizedHookEvent {
+    const obj = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+    const toolName = asString(obj.tool_name);
+    const toolInput = asObject(obj.tool_input);
+
+    // Pre/postToolUse: Cursor identifies the running session via
+    // conversation_id (per-conversation) + generation_id (per-turn).
+    // Use conversation_id as the stable session id so consecutive tool calls
+    // in the same conversation route to the same AXME session.
+    // sessionEnd: Cursor sends a top-level session_id that may differ from
+    // conversation_id (it identifies the SDK session, not the chat).
+    let sessionId: string | undefined;
+    if (kind === "sessionEnd") {
+      sessionId = asString(obj.session_id) ?? asString(obj.conversation_id);
+    } else {
+      sessionId = asString(obj.conversation_id) ?? asString(obj.session_id);
+    }
+
+    // transcript_path may legitimately be null on Cursor (e.g. very first
+    // turn). Preserve null so callers can distinguish "no transcript yet"
+    // from "field absent".
+    let transcriptPath: string | null | undefined;
+    if (obj.transcript_path === null) transcriptPath = null;
+    else transcriptPath = asString(obj.transcript_path);
+
+    const reason = kind === "sessionEnd" ? asString(obj.reason) : undefined;
+
+    return {
+      kind,
+      ide: "cursor",
+      toolName,
+      toolInput,
+      sessionId,
+      transcriptPath,
+      reason,
+      raw: obj,
+    };
+  },
+};
+
+export const cursorOutputAdapter: HookOutputAdapter = {
+  emitDeny(reason, _kind): DenyResult {
+    const message = `[AXME Safety] ${reason}`;
+    const output = {
+      permission: "deny",
+      user_message: message,
+      agent_message: message,
+    };
+    // Exit code 2 is Cursor's documented "deny" signal; the JSON body is
+    // also required so Cursor's UI shows the reason. Both must agree.
+    return { stdout: JSON.stringify(output), exitCode: 2 };
+  },
+};
diff --git a/src/hooks/adapters/types.ts b/src/hooks/adapters/types.ts
new file mode 100644
index 0000000..75177e5
--- /dev/null
+++ b/src/hooks/adapters/types.ts
@@ -0,0 +1,50 @@
+/**
+ * Shared types for IDE-specific hook input parsers and deny-output emitters.
+ *
+ * Both Claude Code and Cursor hooks deliver per-event JSON to the hook
+ * subprocess on stdin, but the field names, the deny-response shape, and the
+ * exit-code semantics differ. The adapter pattern keeps the safety-checking
+ * core logic in pre-tool-use.ts byte-identical across IDEs and isolates the
+ * IDE-specific shapes here.
+ */
+
+import type { IdeKind } from "../../types.js";
+
+export type HookKind = "preToolUse" | "postToolUse" | "sessionEnd";
+
+/**
+ * The IDE-agnostic shape of a hook event after parsing. Hook handlers in
+ * src/hooks/* read from this type instead of touching raw IDE-specific keys.
+ */
+export interface NormalizedHookEvent {
+  kind: HookKind;
+  ide: IdeKind;
+  /** PreToolUse / PostToolUse only — the tool the agent is about to run. */
+  toolName?: string;
+  /** PreToolUse / PostToolUse only — the arguments the agent passed. */
+  toolInput?: Record<string, unknown>;
+  /** IDE's own session id (Claude Code session_id, Cursor session_id, etc.). */
+  sessionId?: string;
+  /** Path to the IDE's transcript file, if any. May be null on Cursor. */
+  transcriptPath?: string | null;
+  /** SessionEnd only — Cursor reports a `reason` (completed/aborted/...). */
+  reason?: string;
+  /** The original parsed JSON, for debug logging or fallback inspection. */
+  raw: Record<string, unknown>;
+}
+
+/** Parses a raw stdin JSON value into a NormalizedHookEvent. */
+export interface HookInputAdapter {
+  parse(raw: unknown, kind: HookKind): NormalizedHookEvent;
+}
+
+/** Result of an IDE-specific deny: stdout payload + exit code to use. */
+export interface DenyResult {
+  stdout: string;
+  exitCode: number;
+}
+
+/** Emits a deny response in the IDE's native protocol. */
+export interface HookOutputAdapter {
+  emitDeny(reason: string, kind: HookKind): DenyResult;
+}
diff --git a/src/hooks/post-tool-use.ts b/src/hooks/post-tool-use.ts
index bfb2e19..04c418d 100644
--- a/src/hooks/post-tool-use.ts
+++ b/src/hooks/post-tool-use.ts
@@ -1,42 +1,48 @@
 /**
- * PostToolUse hook - runs after Edit/Write tool calls.
+ * PostToolUse hook — runs after Edit/Write tool calls.
  *
- * Tracks filesChanged in session metadata, and attaches the Claude Code
- * session (session_id + transcript_path from the hook event) to the current
- * AXME session so the LLM auditor can later read the full transcript.
+ * Tracks filesChanged in session metadata, and attaches the IDE's session
+ * (id + transcript_path from the hook event) to the current AXME session
+ * so the LLM auditor can later read the full transcript.
  *
- * Input: JSON on stdin from Claude Code hooks system.
- * Workspace path: passed via --workspace flag (hardcoded at setup time).
+ * Input: JSON on stdin from the IDE's hooks system. Stdin shape varies by
+ * IDE (Claude Code vs Cursor); the adapter in src/hooks/adapters/ handles
+ * the per-IDE field renames before the handler core runs.
  *
- * Session ID: read from .axme-code/active-session (written by MCP server),
- * NOT from Claude Code's session_id (which is a different ID).
+ * Session ID: read from `.axme-code/active-sessions/<ide-session-id>.txt`
+ * (written by MCP server / earlier hooks), NOT from the IDE's session id
+ * directly (which is a different ID space).
  */
 
 import { trackFileChanged, ensureAxmeSessionForClaude } from "../storage/sessions.js";
 import { pathExists } from "../storage/engine.js";
 import { join } from "node:path";
 import { AXME_CODE_DIR } from "../types.js";
+import type { IdeKind } from "../types.js";
+import { claudeCodeInputAdapter } from "./adapters/claude-code.js";
+import { cursorInputAdapter } from "./adapters/cursor.js";
+import type { HookInputAdapter, NormalizedHookEvent } from "./adapters/types.js";
 
-interface HookInput {
-  tool_name: string;
-  tool_input: Record<string, any>;
-  session_id?: string;
-  transcript_path?: string;
+function inputAdapterFor(ide: IdeKind): HookInputAdapter {
+  return ide === "cursor" ? cursorInputAdapter : claudeCodeInputAdapter;
 }
 
-function handlePostToolUse(workspacePath: string, event: HookInput): void {
-  const { tool_name, tool_input } = event;
+function handlePostToolUse(workspacePath: string, event: NormalizedHookEvent): void {
+  const tool_name = event.toolName ?? "";
+  const tool_input = (event.toolInput ?? {}) as Record<string, any>;
 
   if (!pathExists(join(workspacePath, AXME_CODE_DIR))) return;
 
   // Ensure the AXME session exists for this Claude session_id (lazy creation).
   // Without session_id we cannot route this hook call — silently skip.
-  if (!event.session_id || !event.transcript_path) return;
+  if (!event.sessionId || !event.transcriptPath) return;
 
   const axmeSessionId = ensureAxmeSessionForClaude(
     workspacePath,
-    event.session_id,
-    event.transcript_path,
+    event.sessionId,
+    event.transcriptPath,
+    undefined,
+    event.ide,
   );
 
   // filesChanged tracking only for mutation tools
@@ -52,8 +58,9 @@ function handlePostToolUse(workspacePath: string, event: HookInput): void {
 /**
  * CLI entry point - reads JSON from stdin.
  * @param workspacePath - from --workspace CLI flag
+ * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
-export async function runPostToolUseHook(workspacePath?: string): Promise<void> {
+export async function runPostToolUseHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
   if (!workspacePath) workspacePath = process.cwd();
   if (!workspacePath) return;
 
@@ -66,8 +73,9 @@ export async function runPostToolUseHook(workspacePath?: string): Promise<void>
   try {
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
-    const input = JSON.parse(Buffer.concat(chunks).toString("utf-8")) as HookInput;
-    handlePostToolUse(workspacePath, input);
+    const raw = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+    const event = inputAdapterFor(ide).parse(raw, "postToolUse");
+    handlePostToolUse(workspacePath, event);
   } catch (err) {
     // Hook failures must be silent — but reported to telemetry for visibility.
     // Use blocking send: hook subprocess exits ms after this catch and would
diff --git a/src/hooks/pre-tool-use.ts b/src/hooks/pre-tool-use.ts
index 7ce261c..af4ea7c 100644
--- a/src/hooks/pre-tool-use.ts
+++ b/src/hooks/pre-tool-use.ts
@@ -4,10 +4,10 @@
  * Intercepts tool calls BEFORE execution and blocks violations.
  * Uses the same checkBash/checkGit/checkFilePath from storage/safety.ts.
  *
- * Output format (to block):
- *   { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "..." } }
- *
- * Silent exit (no output) = allow.
+ * IDE-specific stdin/stdout shapes are handled by adapters in
+ * src/hooks/adapters/*. The safety-checking core in handlePreToolUse is
+ * IDE-agnostic — it consumes a NormalizedHookEvent and emits a deny
+ * verdict that the calling IDE adapter formats correctly.
  */
 
 import { loadMergedSafetyRules, checkBash, checkGit, checkFilePath } from "../storage/safety.js";
@@ -18,14 +18,15 @@ import { detectWorkspace } from "../utils/workspace-detector.js";
 import { dirname, join, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { AXME_CODE_DIR } from "../types.js";
-import type { SafetyRules } from "../types.js";
+import type { IdeKind, SafetyRules } from "../types.js";
 import type { SafetyVerdict } from "../storage/safety.js";
+import { claudeCodeInputAdapter, claudeCodeOutputAdapter } from "./adapters/claude-code.js";
+import { cursorInputAdapter, cursorOutputAdapter } from "./adapters/cursor.js";
+import type { HookInputAdapter, HookOutputAdapter, NormalizedHookEvent } from "./adapters/types.js";
 
-interface HookInput {
-  tool_name: string;
-  tool_input: Record<string, any>;
-  session_id?: string;
-  transcript_path?: string;
+function adaptersFor(ide: IdeKind): { input: HookInputAdapter; output: HookOutputAdapter } {
+  if (ide === "cursor") return { input: cursorInputAdapter, output: cursorOutputAdapter };
+  return { input: claudeCodeInputAdapter, output: claudeCodeOutputAdapter };
 }
 
 /**
@@ -64,15 +65,10 @@ function splitCommandSegments(command: string): string[] {
   return segments;
 }
 
-function deny(reason: string): void {
-  const output = {
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "deny",
-      permissionDecisionReason: `[AXME Safety] ${reason}`,
-    },
-  };
-  process.stdout.write(JSON.stringify(output));
+function deny(reason: string, output: HookOutputAdapter): number {
+  const result = output.emitDeny(reason, "preToolUse");
+  process.stdout.write(result.stdout);
+  return result.exitCode;
 }
 
 /**
@@ -103,10 +99,15 @@ function findContainingRepo(filePath: string, workspaceRoot: string): string {
   return rootResolved;
 }
 
-function handlePreToolUse(sessionOrigin: string, event: HookInput): void {
-  const { tool_name, tool_input } = event;
+function handlePreToolUse(
+  sessionOrigin: string,
+  event: NormalizedHookEvent,
+  output: HookOutputAdapter,
+): number {
+  const tool_name = event.toolName ?? "";
+  const tool_input = (event.toolInput ?? {}) as Record<string, any>;
 
-  if (!pathExists(join(sessionOrigin, AXME_CODE_DIR))) return;
+  if (!pathExists(join(sessionOrigin, AXME_CODE_DIR))) return 0;
 
   // Ensure an AXME session exists for this Claude session (lazy creation).
   // The first hook call with a given Claude session_id creates the AXME
@@ -118,8 +119,8 @@ function handlePreToolUse(sessionOrigin: string, event: HookInput): void {
   // We do this in PreToolUse (not only PostToolUse) so the AXME session
   // exists before any safety denial — we want the audit trail even for
   // blocked tool calls.
-  if (event.session_id && event.transcript_path) {
-    ensureAxmeSessionForClaude(sessionOrigin, event.session_id, event.transcript_path, tool_name);
+  if (event.sessionId && event.transcriptPath) {
+    ensureAxmeSessionForClaude(sessionOrigin, event.sessionId, event.transcriptPath, tool_name, event.ide);
   }
 
   // Determine if the session origin is a workspace (multi-repo) or a single repo.
@@ -186,22 +187,24 @@ function handlePreToolUse(sessionOrigin: string, event: HookInput): void {
   if (!verdict.allowed) {
     // Log safety block to worklog for audit trail
     try {
-      const mapping = event.session_id ? readClaudeSessionMapping(sessionOrigin, event.session_id) : null;
+      const mapping = event.sessionId ? readClaudeSessionMapping(sessionOrigin, event.sessionId) : null;
       const axmeSessionId = mapping ?? "unknown";
       const target = tool_name === "Bash"
         ? (tool_input.command as string ?? "").slice(0, 120)
         : (tool_input.file_path || tool_input.path || "") as string;
       logSafetyBlock(sessionOrigin, axmeSessionId, tool_name, target, "safety_rule", verdict.reason);
     } catch {}
-    deny(verdict.reason);
+    return deny(verdict.reason, output);
   }
+  return 0;
 }
 
 /**
  * CLI entry point - reads JSON from stdin.
  * @param workspacePath - from --workspace CLI flag
+ * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
-export async function runPreToolUseHook(workspacePath?: string): Promise<void> {
+export async function runPreToolUseHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
   if (!workspacePath) workspacePath = process.cwd();
   if (!workspacePath) return;
 
@@ -217,8 +220,11 @@ export async function runPreToolUseHook(workspacePath?: string): Promise<void> {
   try {
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
-    const input = JSON.parse(Buffer.concat(chunks).toString("utf-8")) as HookInput;
-    handlePreToolUse(workspacePath, input);
+    const raw = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+    const adapters = adaptersFor(ide);
+    const event = adapters.input.parse(raw, "preToolUse");
+    const exitCode = handlePreToolUse(workspacePath, event, adapters.output);
+    if (exitCode !== 0) process.exit(exitCode);
   } catch (err) {
     // Hook failures must be silent - fail open for safety.
     // Reported to telemetry via blocking send so the network call lands
diff --git a/src/hooks/session-end.ts b/src/hooks/session-end.ts
index 75819a2..9edf0c5 100644
--- a/src/hooks/session-end.ts
+++ b/src/hooks/session-end.ts
@@ -23,50 +23,55 @@ import {
 import { spawnDetachedAuditWorker } from "../audit-spawner.js";
 import { pathExists } from "../storage/engine.js";
 import { AXME_CODE_DIR } from "../types.js";
+import type { IdeKind } from "../types.js";
+import { claudeCodeInputAdapter } from "./adapters/claude-code.js";
+import { cursorInputAdapter } from "./adapters/cursor.js";
+import type { HookInputAdapter, NormalizedHookEvent } from "./adapters/types.js";
 
-interface SessionEndInput {
-  session_id?: string;
-  transcript_path?: string;
-  source?: string;
+function inputAdapterFor(ide: IdeKind): HookInputAdapter {
+  return ide === "cursor" ? cursorInputAdapter : claudeCodeInputAdapter;
 }
 
-function handleSessionEnd(workspacePath: string, input: SessionEndInput): void {
+function handleSessionEnd(workspacePath: string, event: NormalizedHookEvent): void {
   if (!pathExists(join(workspacePath, AXME_CODE_DIR))) return;
 
-  // SessionEnd must know which Claude session is ending. If it does not,
+  // SessionEnd must know which IDE session is ending. If it does not,
   // there is nothing we can safely do — we cannot guess which of possibly
   // several parallel sessions is closing.
-  if (!input.session_id) return;
+  if (!event.sessionId) return;
 
   // If PreToolUse / PostToolUse already created the AXME session for this
-  // Claude session, we find it via the mapping. If not (e.g. the session
-  // only made read-only MCP tool calls), create it now so the audit still
-  // runs against whatever filesChanged/worklog we have.
-  let axmeSessionId = readClaudeSessionMapping(workspacePath, input.session_id);
-  if (!axmeSessionId && input.transcript_path) {
+  // IDE session, we find it via the mapping. If not (e.g. the session only
+  // made read-only MCP tool calls), create it now so the audit still runs
+  // against whatever filesChanged/worklog we have.
+  let axmeSessionId = readClaudeSessionMapping(workspacePath, event.sessionId);
+  if (!axmeSessionId && event.transcriptPath) {
     axmeSessionId = ensureAxmeSessionForClaude(
       workspacePath,
-      input.session_id,
-      input.transcript_path,
+      event.sessionId,
+      event.transcriptPath,
+      undefined,
+      event.ide,
     );
   }
   if (!axmeSessionId) return;
 
   // Spawn a detached audit worker and return immediately. The worker lives
-  // in its own process group and survives SIGKILL to Claude Code / the hook
+  // in its own process group and survives SIGKILL to the IDE / the hook
   // subprocess. We do NOT await runSessionCleanup here — the hook's 120s
-  // timeout and Claude Code's shutdown clock together make synchronous
-  // auditing unreliable in practice.
-  spawnDetachedAuditWorker(workspacePath, axmeSessionId);
-  // Clear this Claude session's mapping file — the session is over.
-  clearClaudeSessionMapping(workspacePath, input.session_id);
+  // timeout and the IDE's shutdown clock together make synchronous auditing
+  // unreliable in practice.
+  spawnDetachedAuditWorker(workspacePath, axmeSessionId, event.ide);
+  // Clear this IDE session's mapping file — the session is over.
+  clearClaudeSessionMapping(workspacePath, event.sessionId);
 }
 
 /**
  * CLI entry point — reads JSON from stdin.
  * @param workspacePath - from --workspace CLI flag
+ * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
-export async function runSessionEndHook(workspacePath?: string): Promise<void> {
+export async function runSessionEndHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
   if (!workspacePath) workspacePath = process.cwd();
   if (!workspacePath) return;
 
@@ -80,13 +85,14 @@ export async function runSessionEndHook(workspacePath?: string): Promise<void> {
   try {
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
-    let input: SessionEndInput = {};
+    let raw: unknown = {};
     try {
-      input = JSON.parse(Buffer.concat(chunks).toString("utf-8")) as SessionEndInput;
+      raw = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
     } catch {
       // Empty/invalid stdin is fine — we'll proceed without transcript attachment
     }
-    handleSessionEnd(workspacePath, input);
+    const event = inputAdapterFor(ide).parse(raw, "sessionEnd");
+    handleSessionEnd(workspacePath, event);
   } catch (err) {
     // Hook failures must be silent — but reported to telemetry for visibility.
     // Use blocking send: hook subprocess exits ms after this catch.
diff --git a/src/storage/sessions.ts b/src/storage/sessions.ts
index e04c8d6..06e9a1f 100644
--- a/src/storage/sessions.ts
+++ b/src/storage/sessions.ts
@@ -21,7 +21,7 @@ import { readdirSync, readFileSync, rmSync, openSync, closeSync, unlinkSync, sta
 import { randomUUID } from "node:crypto";
 import { ensureDir, writeJson, readJson, pathExists, atomicWrite, removeFile, readSafe } from "./engine.js";
 import { logSessionStart } from "./worklog.js";
-import type { SessionMeta, ClaudeSessionRef } from "../types.js";
+import type { SessionMeta, ClaudeSessionRef, IdeKind } from "../types.js";
 import { AXME_CODE_DIR } from "../types.js";
 
 const SESSIONS_DIR = "sessions";
@@ -560,6 +560,10 @@ export function ensureAxmeSessionForClaude(
   /** If set, stale mappings from read-only tools (Read/Glob/Grep) reuse
    *  the existing session id instead of creating a fresh empty-tail session. */
   toolName?: string,
+  /** Which IDE produced this attached session (claude-code | cursor).
+   *  Recorded on the ClaudeSessionRef so the auditor can dispatch the
+   *  right transcript parser. */
+  ide?: IdeKind,
 ): string {
   // Fast path: live mapping exists, just reuse it (no lock needed).
   const existing = readClaudeSessionMapping(projectPath, claudeSessionId);
@@ -574,6 +578,7 @@ export function ensureAxmeSessionForClaude(
         id: claudeSessionId,
         transcriptPath,
         role: "main",
+        ide,
       });
       writeClaudeSessionMapping(projectPath, claudeSessionId, existing);
       return existing;
@@ -596,7 +601,7 @@ export function ensureAxmeSessionForClaude(
     // exited (test workers, short-lived hooks), making the pid look dead.
     const recheck = readClaudeSessionMapping(projectPath, claudeSessionId);
     if (recheck && recheck !== existing) {
-      attachClaudeSession(projectPath, recheck, { id: claudeSessionId, transcriptPath, role: "main" });
+      attachClaudeSession(projectPath, recheck, { id: claudeSessionId, transcriptPath, role: "main", ide });
       return recheck;
     }
     // We won the race (or lock timed out) — create fresh session.
@@ -615,6 +620,7 @@ export function ensureAxmeSessionForClaude(
       id: claudeSessionId,
       transcriptPath,
       role: "main",
+      ide,
     });
     return axmeSession.id;
   } finally {
@@ -851,7 +857,7 @@ export function trackFileChanged(projectPath: string, sessionId: string, filePat
 export function attachClaudeSession(
   projectPath: string,
   axmeSessionId: string,
-  ref: { id: string; transcriptPath: string; role?: string },
+  ref: { id: string; transcriptPath: string; role?: string; ide?: IdeKind },
 ): void {
   if (!ref.id || !ref.transcriptPath) return;
   // Retry up to 3 times with 50ms delay — covers race on shutdown where
@@ -876,6 +882,7 @@ export function attachClaudeSession(
     transcriptPath: ref.transcriptPath,
     firstSeen: new Date().toISOString(),
     ...(ref.role ? { role: ref.role } : {}),
+    ...(ref.ide ? { ide: ref.ide } : {}),
   };
   session.claudeSessions.push(entry);
   writeSession(projectPath, session);
diff --git a/src/types.ts b/src/types.ts
index b375f3c..29e8cd2 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -189,8 +189,20 @@ export interface ClaudeSessionRef {
   firstSeen: string;
   /** Role in the AXME session. Defaults to "main". Reserved for future multi-agent. */
   role?: string;
+  /**
+   * Which IDE produced this attached session. Optional for backward
+   * compatibility with sessions created before Cursor support landed —
+   * absent value is interpreted as "claude-code" by readers.
+   */
+  ide?: IdeKind;
 }
 
+/**
+ * Which IDE the current session/hook event came from. Used to dispatch the
+ * right hook stdin parser, deny-output emitter, and (later) LLM SDK adapter.
+ */
+export type IdeKind = "claude-code" | "cursor";
+
 /**
  * Status of the LLM audit lifecycle on this session. Used to prevent parallel
  * auditors racing on the same session without file locks.
diff --git a/src/utils/ide-detect.ts b/src/utils/ide-detect.ts
new file mode 100644
index 0000000..d546d3a
--- /dev/null
+++ b/src/utils/ide-detect.ts
@@ -0,0 +1,76 @@
+/**
+ * IDE detection — picks which IDE produced a hook event so the right adapter
+ * (and later the right LLM SDK) is selected.
+ *
+ * Resolution order:
+ *   1. explicit --ide flag in argv (always wins)
+ *   2. AXME_IDE env var
+ *   3. heuristic peek at parsed hook stdin (cursor_version / workspace_roots
+ *      keys are Cursor-only)
+ *   4. default "claude-code" — keeps every existing setup unaffected
+ *
+ * The setup writers always emit `--ide cursor` explicitly in
+ * `.cursor/hooks.json` commands, so the heuristic path is only a defence-
+ * in-depth fallback for older configs.
+ */
+
+import type { IdeKind } from "../types.js";
+
+export type { IdeKind };
+
+const IDE_VALUES: ReadonlyArray<IdeKind> = ["claude-code", "cursor"];
+
+/**
+ * Parse `--ide <kind>` or `--ide=<kind>` out of an argv array.
+ * Returns undefined if absent. Unknown values are ignored.
+ */
+export function parseIdeFlag(args: readonly string[]): IdeKind | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--ide" && i + 1 < args.length) {
+      const v = args[i + 1];
+      if (IDE_VALUES.includes(v as IdeKind)) return v as IdeKind;
+    } else if (a.startsWith("--ide=")) {
+      const v = a.slice("--ide=".length);
+      if (IDE_VALUES.includes(v as IdeKind)) return v as IdeKind;
+    }
+  }
+  return undefined;
+}
+
+/** Read AXME_IDE env var. Unknown values are ignored. */
+export function detectIdeFromEnv(env: NodeJS.ProcessEnv = process.env): IdeKind | undefined {
+  const v = env.AXME_IDE;
+  if (v && IDE_VALUES.includes(v as IdeKind)) return v as IdeKind;
+  return undefined;
+}
+
+/**
+ * Peek at parsed hook stdin and infer Cursor vs Claude Code by which keys
+ * are present. Cursor's hook payload always carries `cursor_version` and
+ * `workspace_roots`; Claude Code's never does.
+ */
+export function detectIdeFromHookStdin(raw: unknown): IdeKind | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.cursor_version === "string") return "cursor";
+  if (Array.isArray(obj.workspace_roots)) return "cursor";
+  // Claude Code has no equivalent unique top-level key, so we only
+  // positively identify Cursor here.
+  return undefined;
+}
+
+/**
+ * Resolve the effective IDE for the current invocation.
+ * Order: argv flag → env var → stdin heuristic → "claude-code".
+ */
+export function resolveIde(
+  args: readonly string[],
+  hookRaw?: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): IdeKind {
+  return parseIdeFlag(args)
+    ?? detectIdeFromEnv(env)
+    ?? detectIdeFromHookStdin(hookRaw)
+    ?? "claude-code";
+}
diff --git a/test/claude-code-hook-adapter.test.ts b/test/claude-code-hook-adapter.test.ts
new file mode 100644
index 0000000..15757a0
--- /dev/null
+++ b/test/claude-code-hook-adapter.test.ts
@@ -0,0 +1,74 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  claudeCodeInputAdapter,
+  claudeCodeOutputAdapter,
+} from "../src/hooks/adapters/claude-code.js";
+
+describe("claudeCodeInputAdapter.parse — round-trip", () => {
+  it("maps Claude Code preToolUse stdin → NormalizedHookEvent identically", () => {
+    const raw = {
+      tool_name: "Edit",
+      tool_input: { file_path: "/tmp/x.ts", new_string: "y" },
+      session_id: "claude-session-uuid",
+      transcript_path: "/home/user/.claude/projects/foo/abc.jsonl",
+    };
+    const ev = claudeCodeInputAdapter.parse(raw, "preToolUse");
+    assert.equal(ev.kind, "preToolUse");
+    assert.equal(ev.ide, "claude-code");
+    assert.equal(ev.toolName, "Edit");
+    assert.deepEqual(ev.toolInput, { file_path: "/tmp/x.ts", new_string: "y" });
+    assert.equal(ev.sessionId, "claude-session-uuid");
+    assert.equal(ev.transcriptPath, "/home/user/.claude/projects/foo/abc.jsonl");
+  });
+
+  it("handles sessionEnd shape (no tool_name)", () => {
+    const ev = claudeCodeInputAdapter.parse(
+      {
+        session_id: "claude-session-uuid",
+        transcript_path: "/home/user/.claude/projects/foo/abc.jsonl",
+      },
+      "sessionEnd",
+    );
+    assert.equal(ev.kind, "sessionEnd");
+    assert.equal(ev.ide, "claude-code");
+    assert.equal(ev.sessionId, "claude-session-uuid");
+    assert.equal(ev.toolName, undefined);
+  });
+});
+
+describe("claudeCodeOutputAdapter.emitDeny — regression", () => {
+  it("produces JSON byte-identical to current pre-tool-use deny shape (PreToolUse)", () => {
+    const reason = "git push --force is denied";
+    const result = claudeCodeOutputAdapter.emitDeny(reason, "preToolUse");
+    assert.equal(result.exitCode, 0);
+    // Exact JSON the old pre-tool-use.ts:67-76 produced:
+    const expected = JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: `[AXME Safety] ${reason}`,
+      },
+    });
+    assert.equal(result.stdout, expected);
+  });
+
+  it("emits matching hookEventName for postToolUse / sessionEnd kinds", () => {
+    const post = claudeCodeOutputAdapter.emitDeny("nope", "postToolUse");
+    const parsed = JSON.parse(post.stdout) as { hookSpecificOutput: { hookEventName: string } };
+    assert.equal(parsed.hookSpecificOutput.hookEventName, "PostToolUse");
+
+    const end = claudeCodeOutputAdapter.emitDeny("nope", "sessionEnd");
+    const parsedEnd = JSON.parse(end.stdout) as { hookSpecificOutput: { hookEventName: string } };
+    assert.equal(parsedEnd.hookSpecificOutput.hookEventName, "SessionEnd");
+  });
+});
+
+describe("claudeCodeInputAdapter — defensive parsing", () => {
+  it("tolerates non-object stdin", () => {
+    const ev = claudeCodeInputAdapter.parse(null, "preToolUse");
+    assert.equal(ev.ide, "claude-code");
+    assert.equal(ev.toolName, undefined);
+    assert.deepEqual(ev.raw, {});
+  });
+});
diff --git a/test/cursor-hook-adapter.test.ts b/test/cursor-hook-adapter.test.ts
new file mode 100644
index 0000000..3319146
--- /dev/null
+++ b/test/cursor-hook-adapter.test.ts
@@ -0,0 +1,107 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { cursorInputAdapter, cursorOutputAdapter } from "../src/hooks/adapters/cursor.js";
+
+describe("cursorInputAdapter.parse — preToolUse", () => {
+  it("maps Cursor preToolUse stdin → NormalizedHookEvent", () => {
+    const raw = {
+      cursor_version: "1.7.3",
+      hook_event_name: "preToolUse",
+      conversation_id: "conv-abc-123",
+      generation_id: "gen-xyz-789",
+      model: "composer-2",
+      workspace_roots: ["/tmp/cursor-smoke"],
+      tool_name: "Edit",
+      tool_input: { file_path: "/tmp/cursor-smoke/foo.ts", new_string: "x" },
+      tool_use_id: "tu-001",
+      cwd: "/tmp/cursor-smoke",
+      transcript_path: null,
+    };
+    const ev = cursorInputAdapter.parse(raw, "preToolUse");
+    assert.equal(ev.kind, "preToolUse");
+    assert.equal(ev.ide, "cursor");
+    assert.equal(ev.toolName, "Edit");
+    assert.deepEqual(ev.toolInput, { file_path: "/tmp/cursor-smoke/foo.ts", new_string: "x" });
+    assert.equal(ev.sessionId, "conv-abc-123");
+    assert.equal(ev.transcriptPath, null);
+    assert.equal(ev.raw.cursor_version, "1.7.3");
+  });
+
+  it("preserves transcript_path string when present", () => {
+    const ev = cursorInputAdapter.parse(
+      {
+        cursor_version: "1.7",
+        conversation_id: "c1",
+        tool_name: "Read",
+        tool_input: { file_path: "/x" },
+        transcript_path: "/Users/me/.cursor/transcripts/t.jsonl",
+      },
+      "preToolUse",
+    );
+    assert.equal(ev.transcriptPath, "/Users/me/.cursor/transcripts/t.jsonl");
+  });
+});
+
+describe("cursorInputAdapter.parse — sessionEnd", () => {
+  it("uses session_id (not conversation_id) for sessionEnd", () => {
+    const ev = cursorInputAdapter.parse(
+      {
+        cursor_version: "1.7",
+        conversation_id: "conv-a",
+        session_id: "sdk-session-b",
+        reason: "user_close",
+        duration_ms: 12345,
+        is_background_agent: false,
+        final_status: "completed",
+      },
+      "sessionEnd",
+    );
+    assert.equal(ev.kind, "sessionEnd");
+    assert.equal(ev.ide, "cursor");
+    assert.equal(ev.sessionId, "sdk-session-b");
+    assert.equal(ev.reason, "user_close");
+  });
+
+  it("falls back to conversation_id when session_id absent", () => {
+    const ev = cursorInputAdapter.parse(
+      { cursor_version: "1.7", conversation_id: "conv-a", reason: "completed" },
+      "sessionEnd",
+    );
+    assert.equal(ev.sessionId, "conv-a");
+  });
+});
+
+describe("cursorOutputAdapter.emitDeny", () => {
+  it("emits flat permission/user_message JSON and exit code 2", () => {
+    const result = cursorOutputAdapter.emitDeny("force-push to main is blocked", "preToolUse");
+    assert.equal(result.exitCode, 2);
+    const parsed = JSON.parse(result.stdout) as Record<string, unknown>;
+    assert.equal(parsed.permission, "deny");
+    assert.match(parsed.user_message as string, /\[AXME Safety\]/);
+    assert.match(parsed.user_message as string, /force-push/);
+    assert.equal(parsed.user_message, parsed.agent_message);
+  });
+
+  it("does NOT use Claude-style hookSpecificOutput envelope", () => {
+    const result = cursorOutputAdapter.emitDeny("blocked", "preToolUse");
+    const parsed = JSON.parse(result.stdout) as Record<string, unknown>;
+    assert.equal(parsed.hookSpecificOutput, undefined);
+  });
+});
+
+describe("cursorInputAdapter — defensive parsing", () => {
+  it("tolerates non-object stdin", () => {
+    const ev = cursorInputAdapter.parse(null, "preToolUse");
+    assert.equal(ev.ide, "cursor");
+    assert.equal(ev.kind, "preToolUse");
+    assert.equal(ev.toolName, undefined);
+    assert.deepEqual(ev.raw, {});
+  });
+
+  it("tolerates missing fields", () => {
+    const ev = cursorInputAdapter.parse({ cursor_version: "1.7" }, "postToolUse");
+    assert.equal(ev.toolName, undefined);
+    assert.equal(ev.toolInput, undefined);
+    assert.equal(ev.sessionId, undefined);
+  });
+});
diff --git a/test/ide-detect.test.ts b/test/ide-detect.test.ts
new file mode 100644
index 0000000..56bef65
--- /dev/null
+++ b/test/ide-detect.test.ts
@@ -0,0 +1,105 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  parseIdeFlag,
+  detectIdeFromEnv,
+  detectIdeFromHookStdin,
+  resolveIde,
+} from "../src/utils/ide-detect.js";
+
+describe("parseIdeFlag", () => {
+  it("returns 'cursor' for --ide cursor", () => {
+    assert.equal(parseIdeFlag(["--ide", "cursor"]), "cursor");
+  });
+
+  it("returns 'cursor' for --ide=cursor", () => {
+    assert.equal(parseIdeFlag(["--ide=cursor"]), "cursor");
+  });
+
+  it("returns 'claude-code' for --ide claude-code", () => {
+    assert.equal(parseIdeFlag(["--ide", "claude-code"]), "claude-code");
+  });
+
+  it("returns undefined when --ide is absent", () => {
+    assert.equal(parseIdeFlag([]), undefined);
+    assert.equal(parseIdeFlag(["--workspace", "/tmp/foo"]), undefined);
+  });
+
+  it("ignores unknown values", () => {
+    assert.equal(parseIdeFlag(["--ide", "windsurf"]), undefined);
+    assert.equal(parseIdeFlag(["--ide=copilot"]), undefined);
+  });
+
+  it("handles --ide as last argv element with no value", () => {
+    assert.equal(parseIdeFlag(["--ide"]), undefined);
+  });
+});
+
+describe("detectIdeFromEnv", () => {
+  it("returns 'cursor' when AXME_IDE=cursor", () => {
+    assert.equal(detectIdeFromEnv({ AXME_IDE: "cursor" }), "cursor");
+  });
+
+  it("returns 'claude-code' when AXME_IDE=claude-code", () => {
+    assert.equal(detectIdeFromEnv({ AXME_IDE: "claude-code" }), "claude-code");
+  });
+
+  it("returns undefined when AXME_IDE is absent or unknown", () => {
+    assert.equal(detectIdeFromEnv({}), undefined);
+    assert.equal(detectIdeFromEnv({ AXME_IDE: "vscode" }), undefined);
+  });
+});
+
+describe("detectIdeFromHookStdin", () => {
+  it("returns 'cursor' when cursor_version is present", () => {
+    assert.equal(
+      detectIdeFromHookStdin({ cursor_version: "1.7.3", hook_event_name: "preToolUse" }),
+      "cursor",
+    );
+  });
+
+  it("returns 'cursor' when workspace_roots array is present", () => {
+    assert.equal(
+      detectIdeFromHookStdin({ workspace_roots: ["/tmp/foo"], session_id: "x" }),
+      "cursor",
+    );
+  });
+
+  it("returns undefined for Claude Code shape (only positively identifies Cursor)", () => {
+    assert.equal(
+      detectIdeFromHookStdin({ tool_name: "Edit", session_id: "abc", transcript_path: "/x" }),
+      undefined,
+    );
+  });
+
+  it("returns undefined for non-object input", () => {
+    assert.equal(detectIdeFromHookStdin(null), undefined);
+    assert.equal(detectIdeFromHookStdin("string"), undefined);
+    assert.equal(detectIdeFromHookStdin(undefined), undefined);
+  });
+});
+
+describe("resolveIde precedence", () => {
+  it("argv flag wins over env and stdin", () => {
+    assert.equal(
+      resolveIde(["--ide", "claude-code"], { cursor_version: "1.7" }, { AXME_IDE: "cursor" }),
+      "claude-code",
+    );
+  });
+
+  it("env wins over stdin when no argv flag", () => {
+    assert.equal(
+      resolveIde([], { cursor_version: "1.7" }, { AXME_IDE: "claude-code" }),
+      "claude-code",
+    );
+  });
+
+  it("stdin heuristic wins when no argv and no env", () => {
+    assert.equal(resolveIde([], { cursor_version: "1.7" }, {}), "cursor");
+  });
+
+  it("defaults to 'claude-code' when nothing matches", () => {
+    assert.equal(resolveIde([], undefined, {}), "claude-code");
+    assert.equal(resolveIde([], {}, {}), "claude-code");
+  });
+});

From 5ff0a9ecba19ba3e43d47bdb92c8ed1434e190fc Mon Sep 17 00:00:00 2001
From: geobelsky <geobelsky@gmail.com>
Date: Sun, 10 May 2026 09:57:18 +0000
Subject: [PATCH 2/6] fix(cursor): unify conversation_id session-key precedence
 across all hook events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Surfaced by Cursor agent spec-check on PR #129 (2026-05-10). Previous
behaviour was: pre/postToolUse mapped by conversation_id, sessionEnd
preferred session_id with conversation_id fallback. Cursor's
sessionEnd payload contains BOTH (conversation_id from common-base
fields + session_id from event-specific fields), and the two IDs
identify different scopes (conversation_id = chat thread; session_id
= broader SDK session that may span multiple conversations).

The mismatch would orphan AXME sessions: pre/postToolUse creates
.axme-code/active-sessions/<conversation_id>.txt, then sessionEnd
looks up by session_id and finds nothing — clearClaudeSessionMapping
no-ops, the original mapping leaks, and the audit worker doesn't
fire on the right session.

Fix: always prefer conversation_id (present in every Cursor hook
payload via common-base fields), fall back to session_id only if
conversation_id is somehow absent. Apply to all three hook kinds
uniformly.

Tests updated: existing "uses session_id for sessionEnd" assertion
inverted to "uses conversation_id for sessionEnd"; new test for
session_id fallback when conversation_id absent.

Full suite: 573 / 573 (was 572 before fix; +1 new fallback test).
tsc clean. build clean.

Also supersedes memory cursor-sdk-system-prompt-via-inline-agent-...
(deleted) with cursor-sdk-system-prompt-prepend-to-first-send-...
after the same spec-check found that Agent.create() has no top-level
systemPrompt option and the agents+agentId pattern injects subagents,
not the outer agent's system prompt. PR-2 implementation will use
agent.send(`<system>\n\${SYSTEM}\n</system>\n\n\${user}`) instead.
This fix touches PR-1 code only; the PR-2 SDK adapter design is
already updated in the plan file.

#!axme pr=129 repo=AxmeAI/axme-code
---
 src/hooks/adapters/cursor.ts     | 23 +++++++++++------------
 test/cursor-hook-adapter.test.ts | 20 +++++++++++++++++---
 2 files changed, 28 insertions(+), 15 deletions(-)

diff --git a/src/hooks/adapters/cursor.ts b/src/hooks/adapters/cursor.ts
index f5d160e..6d165ae 100644
--- a/src/hooks/adapters/cursor.ts
+++ b/src/hooks/adapters/cursor.ts
@@ -34,18 +34,17 @@ export const cursorInputAdapter: HookInputAdapter = {
     const toolName = asString(obj.tool_name);
     const toolInput = asObject(obj.tool_input);
 
-    // Pre/postToolUse: Cursor identifies the running session via
-    // conversation_id (per-conversation) + generation_id (per-turn).
-    // Use conversation_id as the stable session id so consecutive tool calls
-    // in the same conversation route to the same AXME session.
-    // sessionEnd: Cursor sends a top-level session_id that may differ from
-    // conversation_id (it identifies the SDK session, not the chat).
-    let sessionId: string | undefined;
-    if (kind === "sessionEnd") {
-      sessionId = asString(obj.session_id) ?? asString(obj.conversation_id);
-    } else {
-      sessionId = asString(obj.conversation_id) ?? asString(obj.session_id);
-    }
+    // Use conversation_id as the stable AXME session key across ALL three
+    // hook events. conversation_id is part of Cursor's common-base fields
+    // (present in preToolUse, postToolUse, AND sessionEnd payloads), and
+    // it represents one chat thread — exactly the granularity AXME wants
+    // for one filesChanged trail / one audit. session_id is only event-
+    // specific to sessionStart/sessionEnd and may identify a coarser SDK
+    // session that spans multiple conversations; using it would break the
+    // mapping created by pre/postToolUse (which only sees conversation_id),
+    // leaving the work as an orphan at audit time. Fall back to session_id
+    // only if conversation_id is somehow missing.
+    const sessionId = asString(obj.conversation_id) ?? asString(obj.session_id);
 
     // transcript_path may legitimately be null on Cursor (e.g. very first
     // turn). Preserve null so callers can distinguish "no transcript yet"
diff --git a/test/cursor-hook-adapter.test.ts b/test/cursor-hook-adapter.test.ts
index 3319146..34f472e 100644
--- a/test/cursor-hook-adapter.test.ts
+++ b/test/cursor-hook-adapter.test.ts
@@ -43,7 +43,13 @@ describe("cursorInputAdapter.parse — preToolUse", () => {
 });
 
 describe("cursorInputAdapter.parse — sessionEnd", () => {
-  it("uses session_id (not conversation_id) for sessionEnd", () => {
+  it("uses conversation_id (not session_id) for sessionEnd — consistency with pre/postToolUse", () => {
+    // Cursor's sessionEnd payload includes BOTH conversation_id (common
+    // base) and session_id (event-specific). We deliberately prefer
+    // conversation_id so all three hook events route to the same AXME
+    // session via the same key. Otherwise pre/postToolUse would map by
+    // conversation_id and sessionEnd would look up by session_id, leaving
+    // the work as an orphan.
     const ev = cursorInputAdapter.parse(
       {
         cursor_version: "1.7",
@@ -58,11 +64,19 @@ describe("cursorInputAdapter.parse — sessionEnd", () => {
     );
     assert.equal(ev.kind, "sessionEnd");
     assert.equal(ev.ide, "cursor");
-    assert.equal(ev.sessionId, "sdk-session-b");
+    assert.equal(ev.sessionId, "conv-a");
     assert.equal(ev.reason, "user_close");
   });
 
-  it("falls back to conversation_id when session_id absent", () => {
+  it("falls back to session_id when conversation_id absent", () => {
+    const ev = cursorInputAdapter.parse(
+      { cursor_version: "1.7", session_id: "sdk-session-only", reason: "completed" },
+      "sessionEnd",
+    );
+    assert.equal(ev.sessionId, "sdk-session-only");
+  });
+
+  it("falls back to conversation_id when session_id absent (older Cursor versions)", () => {
     const ev = cursorInputAdapter.parse(
       { cursor_version: "1.7", conversation_id: "conv-a", reason: "completed" },
       "sessionEnd",

From 88937a93f9d62b542bed41dc5238696ffa74f313 Mon Sep 17 00:00:00 2001
From: geobelsky <geobelsky@gmail.com>
Date: Sun, 10 May 2026 10:16:27 +0000
Subject: [PATCH 3/6] feat(cursor): setup writers + cursor_sdk auth + AgentSdk
 factory (PR-2 of #129)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 / 3 second pass — adds the user-visible Cursor pieces on top of
the IDE abstraction landed earlier in this PR:

Setup writers (src/setup/cursor-writers.ts, ~155 LOC)
- writeCursorMcpJson / writeCursorHooksJson / writeCursorRulesMdc
- All idempotent: re-runs preserve user-added entries, dedupe axme
  entries by command-string match. version:1 hooks.json + frontmatter
  on .cursor/rules/axme-code.mdc (alwaysApply: true).
- Hook commands include "--ide cursor" so the spawned subprocess picks
  the right adapter without re-detecting.

CLI setup branch (src/cli.ts)
- Parse --ide=<claude-code|cursor> flag (default claude-code).
- Cursor branch: write .cursor/{mcp,hooks}.json + rules/axme-code.mdc;
  skip CLAUDE.md (D-080) and .claude/settings.json. Root .mcp.json is
  always written so a repo can be opened in either IDE.
- Reject --ide=cursor + --plugin combination (Phase 2 follow-up).
- usage() documents --ide.

AuthMode = subscription | api_key | cursor_sdk (src/types.ts)
- New CursorApiKeyConfig type for ~/.config/axme-code/cursor.yaml.
- auth-config.ts: loadCursorApiKey / saveCursorApiKey (chmod 600 on
  POSIX), heuristicMode prefers cursor_sdk only when nothing else
  detected, validate-mode whitelist extended.
- auth-detect.ts: detectCursorSdk reads CURSOR_API_KEY env or
  ~/.config/axme-code/cursor.yaml, surfaces as third AuthOption.
- auth-prompt.ts: option [3] Cursor SDK in formatDetectionBlock and
  promptAuthChoice; new promptCursorApiKey() paste-once flow.
- cli.ts auth subcommand: cursor_sdk handled in both interactive
  (paste-on-pick) and "auth use cursor_sdk" non-interactive paths.

AgentSdk factory (src/utils/agent-sdk.ts + agent-sdk-{claude,cursor}.ts)
- IDE-agnostic interface mirroring the Claude SDK message envelope.
- createAgentSdk(role) selects IDE via opts → AXME_IDE env →
  authImpliedIde → "claude-code" default. Fallback chain: cursor →
  claude (if findClaudePath() or ANTHROPIC_API_KEY). Throws
  AgentSdkUnavailableError when neither usable; the detached audit
  worker (PR-3) will catch and skip.
- win-arm64 short-circuit: never attempts @cursor/sdk import there
  (no native binary in 1.0.12).
- Cursor wrapper translates Cursor stream events (assistant /
  thinking / status / tool_call) into the shared AgentMessage shape
  and synthesizes a terminal "result" message.
- System-prompt injection: prepend <system>\n...\n</system>\n\n to
  the first agent.send() — Cursor SDK has no top-level systemPrompt
  option (verified via Cursor agent spec-check on PR-1).

agent-options.ts
- buildAgentEnv(): mode=cursor_sdk hydrates CURSOR_API_KEY from
  cursor.yaml and deletes ANTHROPIC_API_KEY (preempt dual-provider
  surprise if Cursor ever adds one).
- mapClaudeToolsToCursor(): Bash → Shell, drops NotebookEdit / Agent
  / Skill / TodoWrite / WebFetch / WebSearch / ToolSearch (not in
  Cursor tool taxonomy).

@cursor/sdk@1.0.12 added to optionalDependencies (exact pin), so npm
install succeeds on win-arm64 (no native binary) without erroring.

Tests (+22):
- test/cursor-setup-writers.test.ts: idempotent merge for hooks/mcp,
  user-entry preservation, frontmatter on rules.mdc.
- test/cursor-auth-config.test.ts: cursor_sdk YAML round-trip,
  cursor.yaml chmod 600, missing/empty key handling.
- test/agent-sdk-factory.test.ts: IDE selection precedence,
  fallback chain when CURSOR_API_KEY missing, mapClaudeToolsToCursor.

Full suite: 595 / 595 (was 573). tsc clean. build clean.

This commit is PR-2 of the cursor-full-support series, all of which
land in PR #129 (per user direction: don't merge until full Cursor E2E).
PR-3 will wire the session-auditor + scanners through the new
AgentSdk factory and add a Cursor-aware branch to transcript-parser.

#!axme pr=129 repo=AxmeAI/axme-code
---
 package-lock.json                 | 1605 ++++++++++++++++++++++++++++-
 package.json                      |    3 +
 src/cli.ts                        |  110 +-
 src/setup/cursor-writers.ts       |  160 +++
 src/types.ts                      |   23 +-
 src/utils/agent-options.ts        |   54 +-
 src/utils/agent-sdk-claude.ts     |   31 +
 src/utils/agent-sdk-cursor.ts     |  163 +++
 src/utils/agent-sdk.ts            |  160 +++
 src/utils/auth-config.ts          |   64 +-
 src/utils/auth-detect.ts          |   52 +-
 src/utils/auth-prompt.ts          |   66 +-
 test/agent-sdk-factory.test.ts    |  125 +++
 test/cursor-auth-config.test.ts   |   73 ++
 test/cursor-setup-writers.test.ts |  133 +++
 15 files changed, 2779 insertions(+), 43 deletions(-)
 create mode 100644 src/setup/cursor-writers.ts
 create mode 100644 src/utils/agent-sdk-claude.ts
 create mode 100644 src/utils/agent-sdk-cursor.ts
 create mode 100644 src/utils/agent-sdk.ts
 create mode 100644 test/agent-sdk-factory.test.ts
 create mode 100644 test/cursor-auth-config.test.ts
 create mode 100644 test/cursor-setup-writers.test.ts

diff --git a/package-lock.json b/package-lock.json
index 310ecfb..6bb8746 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -25,6 +25,9 @@
       },
       "engines": {
         "node": ">=20"
+      },
+      "optionalDependencies": {
+        "@cursor/sdk": "1.0.12"
       }
     },
     "node_modules/@anthropic-ai/claude-agent-sdk": {
@@ -83,6 +86,140 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@bufbuild/protobuf": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-1.10.0.tgz",
+      "integrity": "sha512-QDdVFLoN93Zjg36NoQPZfsVH9tZew7wKDKyV5qRdj8ntT4wQCOradQjRaTdwMhWUYsgKsvCINKKm87FdEk96Ag==",
+      "license": "(Apache-2.0 AND BSD-3-Clause)",
+      "optional": true
+    },
+    "node_modules/@connectrpc/connect": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@connectrpc/connect/-/connect-1.7.0.tgz",
+      "integrity": "sha512-iNKdJRi69YP3mq6AePRT8F/HrxWCewrhxnLMNm0vpqXAR8biwzRtO6Hjx80C6UvtKJ5sFmffQT7I4Baecz389w==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "peerDependencies": {
+        "@bufbuild/protobuf": "^1.10.0"
+      }
+    },
+    "node_modules/@connectrpc/connect-node": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@connectrpc/connect-node/-/connect-node-1.7.0.tgz",
+      "integrity": "sha512-6vaPIkG/NyhxlYgytLoR9KYbPhczEboFB2OYWkA9qvUz1K7efXfeGrlRxoLtpa+r8VxyIOw73w5ktNe743nD+A==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "undici": "^5.28.4"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "peerDependencies": {
+        "@bufbuild/protobuf": "^1.10.0",
+        "@connectrpc/connect": "1.7.0"
+      }
+    },
+    "node_modules/@cursor/sdk": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@cursor/sdk/-/sdk-1.0.12.tgz",
+      "integrity": "sha512-jGx0wFY1N9uIdIKr303CfM6m/dLXmRCUnU/0yNP/oiOpkBXqgqaThGbgYbcOeVrYonMZc/DZJ9EydXOEPJLcbg==",
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "dependencies": {
+        "@bufbuild/protobuf": "1.10.0",
+        "@connectrpc/connect": "^1.6.1",
+        "@connectrpc/connect-node": "^1.6.1",
+        "@statsig/js-client": "3.31.0",
+        "sqlite3": "^5.1.7",
+        "zod": "^3.25.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@cursor/sdk-darwin-arm64": "1.0.12",
+        "@cursor/sdk-darwin-x64": "1.0.12",
+        "@cursor/sdk-linux-arm64": "1.0.12",
+        "@cursor/sdk-linux-x64": "1.0.12",
+        "@cursor/sdk-win32-x64": "1.0.12"
+      }
+    },
+    "node_modules/@cursor/sdk-darwin-arm64": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@cursor/sdk-darwin-arm64/-/sdk-darwin-arm64-1.0.12.tgz",
+      "integrity": "sha512-AOFx+aX+4SntAeC66YncHACXk5duxp+HzDrxxF4Tl93N6nLjHaHEKSAXbt87ivL34MCHop4v/3c70QzBhamB2g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@cursor/sdk-darwin-x64": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@cursor/sdk-darwin-x64/-/sdk-darwin-x64-1.0.12.tgz",
+      "integrity": "sha512-/ZDAYFUrnPd8hAGRky9ZGcROqZSZ2b5W+aEjTdINzLhJ8x5ZNXtjaz0ZYSHabOn2BeErjXgTcq+4bX2/To4C1A==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@cursor/sdk-linux-arm64": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@cursor/sdk-linux-arm64/-/sdk-linux-arm64-1.0.12.tgz",
+      "integrity": "sha512-kAxNqiB3dPtlW9fVjjIZEdbIGEGLA9moOM3zYwsXh8J1Qw942nJYMGDGR4o8x0zglwZ24a1JpovvZamrCaC3Yw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@cursor/sdk-linux-x64": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@cursor/sdk-linux-x64/-/sdk-linux-x64-1.0.12.tgz",
+      "integrity": "sha512-RmBiBCPKMZC5McDerGk2Rk4P47xz2A+uzRoRgH6sMoOjklc33ry11iAZC0D5F5xH85chgY878086A/Q8+XrAuA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@cursor/sdk-win32-x64": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/@cursor/sdk-win32-x64/-/sdk-win32-x64-1.0.12.tgz",
+      "integrity": "sha512-uH4shdHrKOdtNLapy1uuScJ9lL2Pc8zc9I9ZKC6b6bx+0UX6xLAqjPP7dqVPfO6D9u61yLq1Hs86XOLs5ZVkPA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@cursor/sdk/node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "license": "MIT",
+      "optional": true,
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
@@ -525,6 +662,23 @@
         "node": ">=18"
       }
     },
+    "node_modules/@fastify/busboy": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.1.tgz",
+      "integrity": "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/@gar/promisify": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@gar/promisify/-/promisify-1.1.3.tgz",
+      "integrity": "sha512-k2Ty1JcVojjJFwrg/ThKi2ujJ7XNLYaFGNB/bWT9wGR+oSMJHMa5w+CUq6p/pVrKeNNgA7pCqEcjSnHVoqJQFw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/@hono/node-server": {
       "version": "1.19.13",
       "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.13.tgz",
@@ -881,6 +1035,59 @@
         }
       }
     },
+    "node_modules/@npmcli/fs": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@npmcli/fs/-/fs-1.1.1.tgz",
+      "integrity": "sha512-8KG5RD0GVP4ydEzRn/I4BNDuxDtqVbOdm8675T49OIG/NGhaK0pjPX7ZcDlvKYbA+ulvVK3ztfcF4uBdOxuJbQ==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "@gar/promisify": "^1.0.1",
+        "semver": "^7.3.5"
+      }
+    },
+    "node_modules/@npmcli/move-file": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@npmcli/move-file/-/move-file-1.1.2.tgz",
+      "integrity": "sha512-1SUf/Cg2GzGDyaf15aR9St9TWlb+XvbZXWpDx8YKs7MLzMH/BCeopv+y9vzrzgkfykCGuWOlSu3mZhj2+FQcrg==",
+      "deprecated": "This functionality has been moved to @npmcli/fs",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "mkdirp": "^1.0.4",
+        "rimraf": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/@statsig/client-core": {
+      "version": "3.31.0",
+      "resolved": "https://registry.npmjs.org/@statsig/client-core/-/client-core-3.31.0.tgz",
+      "integrity": "sha512-SuxQD6TmVszPG7FoMKwTk/uyBuVFk7XnxI3T/E0uyb7PL7GNjONtfsoh+NqBBVUJVse0CUeSFfgJPoZy1ZOslQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/@statsig/js-client": {
+      "version": "3.31.0",
+      "resolved": "https://registry.npmjs.org/@statsig/js-client/-/js-client-3.31.0.tgz",
+      "integrity": "sha512-LFa5E0LjT6sTfZv3sNGoyRLSZ1078+agdgOA+Vm1ecjG+KbSOfBLTW7hMwimrJ29slRwbYDzbtKaPJo/R37N2g==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "@statsig/client-core": "3.31.0"
+      }
+    },
+    "node_modules/@tootallnate/once": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-1.1.2.tgz",
+      "integrity": "sha512-RbzJvlNzmRq5c3O09UipeuXno4tA1FE6ikOjxZK0tuxVv3412l64l5t1W5pj4+rJq9vpkm/kwiR07aZXnsKPxw==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/@types/js-yaml": {
       "version": "4.0.9",
       "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
@@ -898,6 +1105,13 @@
         "undici-types": "~6.21.0"
       }
     },
+    "node_modules/abbrev": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
+      "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/accepts": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -911,6 +1125,46 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/agent-base": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
+      "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6.0.0"
+      }
+    },
+    "node_modules/agentkeepalive": {
+      "version": "4.6.0",
+      "resolved": "https://registry.npmjs.org/agentkeepalive/-/agentkeepalive-4.6.0.tgz",
+      "integrity": "sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "humanize-ms": "^1.2.1"
+      },
+      "engines": {
+        "node": ">= 8.0.0"
+      }
+    },
+    "node_modules/aggregate-error": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz",
+      "integrity": "sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "clean-stack": "^2.0.0",
+        "indent-string": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/ajv": {
       "version": "8.18.0",
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
@@ -944,12 +1198,94 @@
         }
       }
     },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/aproba": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/aproba/-/aproba-2.1.0.tgz",
+      "integrity": "sha512-tLIEcj5GuR2RSTnxNKdkK0dJ/GrC7P38sUkiDmDuHfsHmbagTFAxDVIBltoklXEVIQ/f14IL8IMJ5pn9Hez1Ew==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/are-we-there-yet": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-3.0.1.tgz",
+      "integrity": "sha512-QZW4EDmGwlYur0Yyf/b2uGucHQMa8aFUP7eu9ddR73vvhFyt4V0Vl3QHPcTNJ8l6qYOBdxgXdnBXQrHilfRQBg==",
+      "deprecated": "This package is no longer supported.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "delegates": "^1.0.0",
+        "readable-stream": "^3.6.0"
+      },
+      "engines": {
+        "node": "^12.13.0 || ^14.15.0 || >=16.0.0"
+      }
+    },
     "node_modules/argparse": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
       "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
       "license": "Python-2.0"
     },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/bindings": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
+      "integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "file-uri-to-path": "1.0.0"
+      }
+    },
+    "node_modules/bl": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
+      "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "buffer": "^5.5.0",
+        "inherits": "^2.0.4",
+        "readable-stream": "^3.4.0"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -974,6 +1310,42 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/brace-expansion": {
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/buffer": {
+      "version": "5.7.1",
+      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
+      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "base64-js": "^1.3.1",
+        "ieee754": "^1.1.13"
+      }
+    },
     "node_modules/bytes": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
@@ -983,6 +1355,36 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/cacache": {
+      "version": "15.3.0",
+      "resolved": "https://registry.npmjs.org/cacache/-/cacache-15.3.0.tgz",
+      "integrity": "sha512-VVdYzXEn+cnbXpFgWs5hTT7OScegHVmLhJIR8Ufqk3iFD6A6j5iSX1KuBTfNEv4tdJWE2PzA6IVFtcLC7fN9wQ==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "@npmcli/fs": "^1.0.0",
+        "@npmcli/move-file": "^1.0.1",
+        "chownr": "^2.0.0",
+        "fs-minipass": "^2.0.0",
+        "glob": "^7.1.4",
+        "infer-owner": "^1.0.4",
+        "lru-cache": "^6.0.0",
+        "minipass": "^3.1.1",
+        "minipass-collect": "^1.0.2",
+        "minipass-flush": "^1.0.5",
+        "minipass-pipeline": "^1.2.2",
+        "mkdirp": "^1.0.3",
+        "p-map": "^4.0.0",
+        "promise-inflight": "^1.0.1",
+        "rimraf": "^3.0.2",
+        "ssri": "^8.0.1",
+        "tar": "^6.0.2",
+        "unique-filename": "^1.1.1"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/call-bind-apply-helpers": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
@@ -1012,6 +1414,50 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/chownr": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/chownr/-/chownr-2.0.0.tgz",
+      "integrity": "sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==",
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/clean-stack": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/clean-stack/-/clean-stack-2.2.0.tgz",
+      "integrity": "sha512-4diC9HaTE+KRAMWhDhrGOECgWZxoevMc5TlkObMqNSsVU62PYzXZ/SMTjzyGAFF1YusgxGcSWTEXBhp0CPwQ1A==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/color-support": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/color-support/-/color-support-1.1.3.tgz",
+      "integrity": "sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==",
+      "license": "ISC",
+      "optional": true,
+      "bin": {
+        "color-support": "bin.js"
+      }
+    },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/console-control-strings": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/console-control-strings/-/console-control-strings-1.1.0.tgz",
+      "integrity": "sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/content-disposition": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.0.1.tgz",
@@ -1100,6 +1546,39 @@
         }
       }
     },
+    "node_modules/decompress-response": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
+      "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "mimic-response": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/deep-extend": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
+      "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/delegates": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/delegates/-/delegates-1.0.0.tgz",
+      "integrity": "sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/depd": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
@@ -1109,6 +1588,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -1129,6 +1618,13 @@
       "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
       "license": "MIT"
     },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/encodeurl": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
@@ -1138,19 +1634,69 @@
         "node": ">= 0.8"
       }
     },
-    "node_modules/es-define-property": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
-      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+    "node_modules/encoding": {
+      "version": "0.1.13",
+      "resolved": "https://registry.npmjs.org/encoding/-/encoding-0.1.13.tgz",
+      "integrity": "sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==",
       "license": "MIT",
-      "engines": {
-        "node": ">= 0.4"
+      "optional": true,
+      "dependencies": {
+        "iconv-lite": "^0.6.2"
       }
     },
-    "node_modules/es-errors": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
-      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+    "node_modules/encoding/node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "once": "^1.4.0"
+      }
+    },
+    "node_modules/env-paths": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-2.2.1.tgz",
+      "integrity": "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/err-code": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/err-code/-/err-code-2.0.3.tgz",
+      "integrity": "sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/es-define-property": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-errors": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -1246,6 +1792,16 @@
         "node": ">=18.0.0"
       }
     },
+    "node_modules/expand-template": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz",
+      "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==",
+      "license": "(MIT OR WTFPL)",
+      "optional": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/express": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
@@ -1329,6 +1885,13 @@
       ],
       "license": "BSD-3-Clause"
     },
+    "node_modules/file-uri-to-path": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz",
+      "integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/finalhandler": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
@@ -1368,6 +1931,33 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/fs-constants": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
+      "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/fs-minipass": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-2.1.0.tgz",
+      "integrity": "sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -1392,6 +1982,27 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/gauge": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/gauge/-/gauge-4.0.4.tgz",
+      "integrity": "sha512-f9m+BEN5jkg6a0fZjleidjN51VE1X+mPFQ2DJ0uv1V39oCLCbsGe6yjbBnp7eK7z/+GAon99a3nHuqbuuthyPg==",
+      "deprecated": "This package is no longer supported.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "aproba": "^1.0.3 || ^2.0.0",
+        "color-support": "^1.1.3",
+        "console-control-strings": "^1.1.0",
+        "has-unicode": "^2.0.1",
+        "signal-exit": "^3.0.7",
+        "string-width": "^4.2.3",
+        "strip-ansi": "^6.0.1",
+        "wide-align": "^1.1.5"
+      },
+      "engines": {
+        "node": "^12.13.0 || ^14.15.0 || >=16.0.0"
+      }
+    },
     "node_modules/get-intrinsic": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
@@ -1442,6 +2053,35 @@
         "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
       }
     },
+    "node_modules/github-from-package": {
+      "version": "0.0.0",
+      "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz",
+      "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/glob": {
+      "version": "7.2.3",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
+      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
+      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.1.1",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      },
+      "engines": {
+        "node": "*"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -1454,6 +2094,13 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/graceful-fs": {
+      "version": "4.2.11",
+      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
+      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/has-symbols": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
@@ -1466,6 +2113,13 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/has-unicode": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/has-unicode/-/has-unicode-2.0.1.tgz",
+      "integrity": "sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/hasown": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
@@ -1487,6 +2141,13 @@
         "node": ">=16.9.0"
       }
     },
+    "node_modules/http-cache-semantics": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz",
+      "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==",
+      "license": "BSD-2-Clause",
+      "optional": true
+    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
@@ -1507,6 +2168,45 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/http-proxy-agent": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-4.0.1.tgz",
+      "integrity": "sha512-k0zdNgqWTGA6aeIRVpvfVob4fL52dTfaehylg0Y4UvSySvOq/Y+BOyPrgpUrA7HylqvU8vIZGsRuXmspskV0Tg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@tootallnate/once": "1",
+        "agent-base": "6",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/https-proxy-agent": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
+      "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "agent-base": "6",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/humanize-ms": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/humanize-ms/-/humanize-ms-1.2.1.tgz",
+      "integrity": "sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ms": "^2.0.0"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.7.2",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
@@ -1523,12 +2223,79 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/ieee754": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
+      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "BSD-3-Clause",
+      "optional": true
+    },
+    "node_modules/imurmurhash": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz",
+      "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.8.19"
+      }
+    },
+    "node_modules/indent-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
+      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/infer-owner": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/infer-owner/-/infer-owner-1.0.4.tgz",
+      "integrity": "sha512-IClj+Xz94+d7irH5qRyfJonOdfTzuDaifE6ZPWfx0N0+/ATZCbuTPq2prFl526urkQd90WyUKIh1DfBQ2hMz9A==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
+      "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
     "node_modules/inherits": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
       "license": "ISC"
     },
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/ip-address": {
       "version": "10.1.0",
       "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
@@ -1547,6 +2314,23 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-lambda": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-lambda/-/is-lambda-1.0.1.tgz",
+      "integrity": "sha512-z7CMFGNrENq5iFB9Bqo64Xk6Y9sg+epq1myIcdHaGnbMTYOxvzsEtdYqQUylB7LxfkvgrrjP32T6Ywciio9UIQ==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/is-promise": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
@@ -1605,6 +2389,57 @@
       "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
       "license": "BSD-2-Clause"
     },
+    "node_modules/lru-cache": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz",
+      "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/make-fetch-happen": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/make-fetch-happen/-/make-fetch-happen-9.1.0.tgz",
+      "integrity": "sha512-+zopwDy7DNknmwPQplem5lAZX/eCOzSvSNNcSKm5eVwTkOBzoktEfXsa9L23J/GIRhxRsaxzkPEhrJEpE2F4Gg==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "agentkeepalive": "^4.1.3",
+        "cacache": "^15.2.0",
+        "http-cache-semantics": "^4.1.0",
+        "http-proxy-agent": "^4.0.1",
+        "https-proxy-agent": "^5.0.0",
+        "is-lambda": "^1.0.1",
+        "lru-cache": "^6.0.0",
+        "minipass": "^3.1.3",
+        "minipass-collect": "^1.0.2",
+        "minipass-fetch": "^1.3.2",
+        "minipass-flush": "^1.0.5",
+        "minipass-pipeline": "^1.2.4",
+        "negotiator": "^0.6.2",
+        "promise-retry": "^2.0.1",
+        "socks-proxy-agent": "^6.0.0",
+        "ssri": "^8.0.0"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/make-fetch-happen/node_modules/negotiator": {
+      "version": "0.6.4",
+      "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.4.tgz",
+      "integrity": "sha512-myRT3DiWPHqho5PrJaIRyaMv2kgYf0mUVgBNOYMuCH5Ki1yEiQaf/ZJuQ62nvpc44wL5WDbTX7yGJi1Neevw8w==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -1660,12 +2495,172 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/mimic-response": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz",
+      "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+      "license": "MIT",
+      "optional": true,
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/minipass": {
+      "version": "3.3.6",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
+      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/minipass-collect": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/minipass-collect/-/minipass-collect-1.0.2.tgz",
+      "integrity": "sha512-6T6lH0H8OG9kITm/Jm6tdooIbogG9e0tLgpY6mphXSm/A9u8Nq1ryBG+Qspiub9LjWlBPsPS3tWQ/Botq4FdxA==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/minipass-fetch": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/minipass-fetch/-/minipass-fetch-1.4.1.tgz",
+      "integrity": "sha512-CGH1eblLq26Y15+Azk7ey4xh0J/XfJfrCox5LDJiKqI2Q2iwOLOKrlmIaODiSQS8d18jalF6y2K2ePUm0CmShw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.1.0",
+        "minipass-sized": "^1.0.3",
+        "minizlib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "optionalDependencies": {
+        "encoding": "^0.1.12"
+      }
+    },
+    "node_modules/minipass-flush": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/minipass-flush/-/minipass-flush-1.0.7.tgz",
+      "integrity": "sha512-TbqTz9cUwWyHS2Dy89P3ocAGUGxKjjLuR9z8w4WUTGAVgEj17/4nhgo2Du56i0Fm3Pm30g4iA8Lcqctc76jCzA==",
+      "license": "BlueOak-1.0.0",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/minipass-pipeline": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/minipass-pipeline/-/minipass-pipeline-1.2.4.tgz",
+      "integrity": "sha512-xuIq7cIOt09RPRJ19gdi4b+RiNvDFYe5JH+ggNvBqGqpQXcru3PcRmOZuHBKWK1Txf9+cQ+HMVN4d6z46LZP7A==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/minipass-sized": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/minipass-sized/-/minipass-sized-1.0.3.tgz",
+      "integrity": "sha512-MbkQQ2CTiBMlA2Dm/5cY+9SWFEN8pzzOXi6rlM5Xxq0Yqbda5ZQy9sU75a673FE9ZK0Zsbr6Y5iP6u9nktfg2g==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/minizlib": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz",
+      "integrity": "sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0",
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/mkdirp": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz",
+      "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==",
+      "license": "MIT",
+      "optional": true,
+      "bin": {
+        "mkdirp": "bin/cmd.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/mkdirp-classic": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz",
+      "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
       "license": "MIT"
     },
+    "node_modules/napi-build-utils": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz",
+      "integrity": "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/negotiator": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz",
@@ -1675,6 +2670,84 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/node-abi": {
+      "version": "3.92.0",
+      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.92.0.tgz",
+      "integrity": "sha512-KdHvFWZjEKDf0cakgFjebl371GPsISX2oZHcuyKqM7DtogIsHrqKeLTo8wBHxaXRAQlY2PsPlZmfo+9ZCxEREQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "semver": "^7.3.5"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/node-gyp": {
+      "version": "8.4.1",
+      "resolved": "https://registry.npmjs.org/node-gyp/-/node-gyp-8.4.1.tgz",
+      "integrity": "sha512-olTJRgUtAb/hOXG0E93wZDs5YiJlgbXxTwQAFHyNlRsXQnYzUaF2aGgujZbw+hR8aF4ZG/rST57bWMWD16jr9w==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "env-paths": "^2.2.0",
+        "glob": "^7.1.4",
+        "graceful-fs": "^4.2.6",
+        "make-fetch-happen": "^9.1.0",
+        "nopt": "^5.0.0",
+        "npmlog": "^6.0.0",
+        "rimraf": "^3.0.2",
+        "semver": "^7.3.5",
+        "tar": "^6.1.2",
+        "which": "^2.0.2"
+      },
+      "bin": {
+        "node-gyp": "bin/node-gyp.js"
+      },
+      "engines": {
+        "node": ">= 10.12.0"
+      }
+    },
+    "node_modules/nopt": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-5.0.0.tgz",
+      "integrity": "sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "abbrev": "1"
+      },
+      "bin": {
+        "nopt": "bin/nopt.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/npmlog": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/npmlog/-/npmlog-6.0.2.tgz",
+      "integrity": "sha512-/vBvz5Jfr9dT/aFWd0FIRf+T/Q2WBsLENygUaFUqstqsycmZAP/t5BvFJTK0viFmSUxiUKTUplWy5vt+rvKIxg==",
+      "deprecated": "This package is no longer supported.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "are-we-there-yet": "^3.0.0",
+        "console-control-strings": "^1.1.0",
+        "gauge": "^4.0.3",
+        "set-blocking": "^2.0.0"
+      },
+      "engines": {
+        "node": "^12.13.0 || ^14.15.0 || >=16.0.0"
+      }
+    },
     "node_modules/object-assign": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
@@ -1717,6 +2790,22 @@
         "wrappy": "1"
       }
     },
+    "node_modules/p-map": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/p-map/-/p-map-4.0.0.tgz",
+      "integrity": "sha512-/bjOqmgETBYB5BoEeGVea8dmvHb2m9GLy1E9W43yeyfP6QQCZGFNa+XRceJEuDB6zqr+gKpIAmlLebMpykw/MQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "aggregate-error": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/parseurl": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
@@ -1726,6 +2815,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/path-key": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
@@ -1754,6 +2853,55 @@
         "node": ">=16.20.0"
       }
     },
+    "node_modules/prebuild-install": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
+      "integrity": "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==",
+      "deprecated": "No longer maintained. Please contact the author of the relevant native addon; alternatives are available.",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "detect-libc": "^2.0.0",
+        "expand-template": "^2.0.3",
+        "github-from-package": "0.0.0",
+        "minimist": "^1.2.3",
+        "mkdirp-classic": "^0.5.3",
+        "napi-build-utils": "^2.0.0",
+        "node-abi": "^3.3.0",
+        "pump": "^3.0.0",
+        "rc": "^1.2.7",
+        "simple-get": "^4.0.0",
+        "tar-fs": "^2.0.0",
+        "tunnel-agent": "^0.6.0"
+      },
+      "bin": {
+        "prebuild-install": "bin.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/promise-inflight": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/promise-inflight/-/promise-inflight-1.0.1.tgz",
+      "integrity": "sha512-6zWPyEOFaQBJYcGMHBKTKJ3u6TBsnMFOIZSa6ce1e/ZrrsOlnHRHbabMjLiBYKp+n44X9eUI6VUPaukCXHuG4g==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/promise-retry": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/promise-retry/-/promise-retry-2.0.1.tgz",
+      "integrity": "sha512-y+WKFlBR8BGXnsNlIHFGPZmyDf3DFMoLhaflAnyZgV6rG6xu+JwesTo2Q9R6XwYmtmwAFCkAk3e35jEdoeh/3g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "err-code": "^2.0.2",
+        "retry": "^0.12.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
@@ -1767,6 +2915,17 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/pump": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
+      }
+    },
     "node_modules/qs": {
       "version": "6.15.0",
       "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.0.tgz",
@@ -1806,6 +2965,37 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/rc": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",
+      "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==",
+      "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
+      "optional": true,
+      "dependencies": {
+        "deep-extend": "^0.6.0",
+        "ini": "~1.3.0",
+        "minimist": "^1.2.0",
+        "strip-json-comments": "~2.0.1"
+      },
+      "bin": {
+        "rc": "cli.js"
+      }
+    },
+    "node_modules/readable-stream": {
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
+      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "inherits": "^2.0.3",
+        "string_decoder": "^1.1.1",
+        "util-deprecate": "^1.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/require-from-string": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
@@ -1825,6 +3015,33 @@
         "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
       }
     },
+    "node_modules/retry": {
+      "version": "0.12.0",
+      "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz",
+      "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 4"
+      }
+    },
+    "node_modules/rimraf": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz",
+      "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==",
+      "deprecated": "Rimraf versions prior to v4 are no longer supported",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "glob": "^7.1.3"
+      },
+      "bin": {
+        "rimraf": "bin.js"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/router": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
@@ -1841,12 +3058,46 @@
         "node": ">= 18"
       }
     },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/safer-buffer": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/semver": {
+      "version": "7.8.0",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
+      "license": "ISC",
+      "optional": true,
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/send": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
@@ -1892,6 +3143,13 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/set-blocking": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
+      "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/setprototypeof": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
@@ -1991,6 +3249,149 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/simple-concat": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz",
+      "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/simple-get": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz",
+      "integrity": "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "decompress-response": "^6.0.0",
+        "once": "^1.3.1",
+        "simple-concat": "^1.0.0"
+      }
+    },
+    "node_modules/smart-buffer": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
+      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 6.0.0",
+        "npm": ">= 3.0.0"
+      }
+    },
+    "node_modules/socks": {
+      "version": "2.8.9",
+      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.9.tgz",
+      "integrity": "sha512-LJhUYUvItdQ0LkJTmPeaEObWXAqFyfmP85x0tch/ez9cahmhlBBLbIqDFnvBnUJGagb0JbIQrkBs1wJ+yRYpEw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ip-address": "^10.1.1",
+        "smart-buffer": "^4.2.0"
+      },
+      "engines": {
+        "node": ">= 10.0.0",
+        "npm": ">= 3.0.0"
+      }
+    },
+    "node_modules/socks-proxy-agent": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-6.2.1.tgz",
+      "integrity": "sha512-a6KW9G+6B3nWZ1yB8G7pJwL3ggLy1uTzKAgCb7ttblwqdz9fMGJUuTy3uFzEP48FAs9FLILlmzDlE2JJhVQaXQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "agent-base": "^6.0.2",
+        "debug": "^4.3.3",
+        "socks": "^2.6.2"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/socks/node_modules/ip-address": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
+      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 12"
+      }
+    },
+    "node_modules/sqlite3": {
+      "version": "5.1.7",
+      "resolved": "https://registry.npmjs.org/sqlite3/-/sqlite3-5.1.7.tgz",
+      "integrity": "sha512-GGIyOiFaG+TUra3JIfkI/zGP8yZYLPQ0pl1bH+ODjiX57sPhrLU5sQJn1y9bDKZUFYkX1crlrPfSYt0BKKdkog==",
+      "hasInstallScript": true,
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "dependencies": {
+        "bindings": "^1.5.0",
+        "node-addon-api": "^7.0.0",
+        "prebuild-install": "^7.1.1",
+        "tar": "^6.1.11"
+      },
+      "optionalDependencies": {
+        "node-gyp": "8.x"
+      },
+      "peerDependencies": {
+        "node-gyp": "8.x"
+      },
+      "peerDependenciesMeta": {
+        "node-gyp": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ssri": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/ssri/-/ssri-8.0.1.tgz",
+      "integrity": "sha512-97qShzy1AiyxvPNIkLWoGua7xoQzzPjQ0HAH4B0rWKo7SZ6USuPcrUiAFrws0UH8RrbWmgq3LMTObhPIHbbBeQ==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.1.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
     "node_modules/statuses": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
@@ -2000,6 +3401,120 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/string_decoder": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
+      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "safe-buffer": "~5.2.0"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-json-comments": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
+      "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/tar": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",
+      "integrity": "sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==",
+      "deprecated": "Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "chownr": "^2.0.0",
+        "fs-minipass": "^2.0.0",
+        "minipass": "^5.0.0",
+        "minizlib": "^2.1.1",
+        "mkdirp": "^1.0.3",
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/tar-fs": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.4.tgz",
+      "integrity": "sha512-mDAjwmZdh7LTT6pNleZ05Yt65HC3E+NiQzl672vQG38jIrehtJk/J3mNwIg+vShQPcLF/LV7CMnDW6vjj6sfYQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "chownr": "^1.1.1",
+        "mkdirp-classic": "^0.5.2",
+        "pump": "^3.0.0",
+        "tar-stream": "^2.1.4"
+      }
+    },
+    "node_modules/tar-fs/node_modules/chownr": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz",
+      "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/tar-stream": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
+      "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "bl": "^4.0.3",
+        "end-of-stream": "^1.4.1",
+        "fs-constants": "^1.0.0",
+        "inherits": "^2.0.3",
+        "readable-stream": "^3.1.1"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/tar/node_modules/minipass": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-5.0.0.tgz",
+      "integrity": "sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==",
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -2519,6 +4034,19 @@
         "@esbuild/win32-x64": "0.27.7"
       }
     },
+    "node_modules/tunnel-agent": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",
+      "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "safe-buffer": "^5.0.1"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
     "node_modules/type-is": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
@@ -2547,6 +4075,19 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/undici": {
+      "version": "5.29.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-5.29.0.tgz",
+      "integrity": "sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@fastify/busboy": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=14.0"
+      }
+    },
     "node_modules/undici-types": {
       "version": "6.21.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
@@ -2554,6 +4095,26 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/unique-filename": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/unique-filename/-/unique-filename-1.1.1.tgz",
+      "integrity": "sha512-Vmp0jIp2ln35UTXuryvjzkjGdRyf9b2lTXuSYUiPmzRcl3FDtYqAwOnTJkAngD9SWhnoJzDbTKwaOrZ+STtxNQ==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "unique-slug": "^2.0.0"
+      }
+    },
+    "node_modules/unique-slug": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/unique-slug/-/unique-slug-2.0.2.tgz",
+      "integrity": "sha512-zoWr9ObaxALD3DOPfjPSqxt4fnZiWblxHIgeWqW8x7UqDzEtHEQLzji2cuJYQFCU6KmoJikOYAZlrTHHebjx2w==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "imurmurhash": "^0.1.4"
+      }
+    },
     "node_modules/unpipe": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
@@ -2563,6 +4124,13 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/vary": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
@@ -2587,12 +4155,29 @@
         "node": ">= 8"
       }
     },
+    "node_modules/wide-align": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/wide-align/-/wide-align-1.1.5.tgz",
+      "integrity": "sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^1.0.2 || 2 || 3 || 4"
+      }
+    },
     "node_modules/wrappy": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "license": "ISC"
     },
+    "node_modules/yallist": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
+      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/zod": {
       "version": "4.3.6",
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
diff --git a/package.json b/package.json
index 0b07ffa..a637a2a 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,9 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0"
   },
+  "optionalDependencies": {
+    "@cursor/sdk": "1.0.12"
+  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
diff --git a/src/cli.ts b/src/cli.ts
index 156f6b8..da579ba 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -197,6 +197,18 @@ async function ensureAuthConfiguredForSetup(): Promise<void> {
     console.log("  Auth selection cancelled. Heuristic fallback will be used.");
     return;
   }
+  if (choice === "cursor_sdk" && !options.cursorSdk?.present) {
+    // User picked Cursor SDK but no key is detected yet — paste flow.
+    const { promptCursorApiKey } = await import("./utils/auth-prompt.js");
+    const { saveCursorApiKey } = await import("./utils/auth-config.js");
+    const key = await promptCursorApiKey();
+    if (!key) {
+      console.log("  Cursor API key paste cancelled. Auth not saved.");
+      return;
+    }
+    saveCursorApiKey(key);
+    console.log(`  Saved Cursor API key: ~/.config/axme-code/cursor.yaml (chmod 600)`);
+  }
   saveAuthConfig(choice);
   console.log(`  Saved auth mode: ${choice} (${authConfigPath()})`);
 }
@@ -320,7 +332,10 @@ function usage(): void {
   console.log(`AXME Code - Persistent memory, decisions, and safety guardrails for Claude Code
 
 Usage:
-  axme-code setup [path] [--force]              Initialize project (LLM scan + .mcp.json + CLAUDE.md)
+  axme-code setup [path] [--force] [--ide=<claude-code|cursor>]
+                                                Initialize project (LLM scan + .mcp.json + CLAUDE.md
+                                                for Claude Code, or .cursor/{mcp,hooks}.json + rules
+                                                /axme-code.mdc for Cursor). Defaults to claude-code.
   axme-code serve                               Start MCP server (stdio transport)
   axme-code status [path]                       Show project status
   axme-code --version | -v                      Print the installed version
@@ -335,9 +350,11 @@ Usage:
   axme-code reindex [path]                      Force a full re-embed of all memories + decisions
                                                 into .axme-code/_index/embeddings.json (search mode only)
 
-  axme-code auth                                Re-detect and choose auth mode (subscription/api_key)
+  axme-code auth                                Re-detect and choose auth mode
+                                                (subscription / api_key / cursor_sdk)
   axme-code auth status                         Show current auth mode + detected options
-  axme-code auth use <subscription|api_key>     Set auth mode non-interactively
+  axme-code auth use <subscription|api_key|cursor_sdk>
+                                                Set auth mode non-interactively
   axme-code cleanup legacy-artifacts [--dry-run]   Remove pre-PR#7 sessions/logs
   axme-code cleanup decisions-normalize [--dry-run]   Add status:active to decisions
   axme-code audit-kb [path] [--all-repos]       KB audit: dedup, conflicts, compaction
@@ -367,7 +384,22 @@ async function main() {
       const setupStartMs = Date.now();
       const forceSetup = args.includes("--force");
       const pluginMode = args.includes("--plugin") || !!process.env.CLAUDE_PLUGIN_ROOT;
-      const setupArgs = args.filter(a => a !== "--force" && a !== "--plugin");
+      const { parseIdeFlag } = await import("./utils/ide-detect.js");
+      const ide = parseIdeFlag(args) ?? "claude-code";
+      if (ide === "cursor" && pluginMode) {
+        console.error("Error: --ide=cursor is not supported with --plugin in this release.");
+        console.error("Run setup without --plugin (Cursor plugin packaging is a Phase 2 follow-up).");
+        process.exit(1);
+      }
+      // Strip --force, --plugin, --ide and its value from positional args.
+      const setupArgs: string[] = [];
+      for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--force" || a === "--plugin") continue;
+        if (a === "--ide") { i++; continue; } // also skip the value
+        if (a.startsWith("--ide=")) continue;
+        setupArgs.push(a);
+      }
       const projectPath = resolve(setupArgs[1] || ".");
       const hasGitDir = existsSync(join(projectPath, ".git"));
       const ws = detectWorkspace(projectPath);
@@ -481,7 +513,10 @@ async function main() {
       const isPlugin = pluginMode;
 
       if (!isPlugin) {
-        // Create or update .mcp.json (workspace root + each child repo)
+        // Create or update .mcp.json (workspace root + each child repo).
+        // Cursor reads BOTH .mcp.json AND .cursor/mcp.json — we always write
+        // the root file regardless of --ide so a repo configured for Cursor
+        // can also be opened in Claude Code without re-running setup.
         const mcpEntry = { command: "axme-code", args: ["serve"] };
         const mcpPaths = [projectPath];
         if (isWorkspace) {
@@ -504,14 +539,30 @@ async function main() {
         console.log(`  .mcp.json: skipped (plugin provides MCP server)`);
       }
 
-      // Generate CLAUDE.md
-      generateClaudeMd(projectPath, isWorkspace);
-
-      if (!isPlugin) {
-        // Configure Claude Code hooks in .claude/settings.json
-        configureHooks(projectPath);
+      if (ide === "cursor") {
+        // Cursor branch: write .cursor/{mcp,hooks}.json + rules/axme-code.mdc.
+        // Skip .claude/CLAUDE.md (D-080: agent must never write to it) and
+        // .claude/settings.json (Cursor doesn't read it).
+        const { writeCursorMcpJson, writeCursorHooksJson, writeCursorRulesMdc } =
+          await import("./setup/cursor-writers.js");
+        const cursorPaths = [projectPath];
+        if (isWorkspace) {
+          for (const p of ws.projects) cursorPaths.push(join(projectPath, p.path));
+        }
+        for (const dir of cursorPaths) writeCursorMcpJson(dir);
+        console.log(`  .cursor/mcp.json: updated (${cursorPaths.length} locations)`);
+        writeCursorHooksJson(projectPath, buildHookCommand);
+        console.log("  .cursor/hooks.json: hooks configured (preToolUse + postToolUse + sessionEnd)");
+        writeCursorRulesMdc(projectPath, isWorkspace);
+        console.log("  .cursor/rules/axme-code.mdc: created");
       } else {
-        console.log(`  Hooks: skipped (plugin provides hooks)`);
+        // Claude Code branch (unchanged): CLAUDE.md + .claude/settings.json
+        generateClaudeMd(projectPath, isWorkspace);
+        if (!isPlugin) {
+          configureHooks(projectPath);
+        } else {
+          console.log(`  Hooks: skipped (plugin provides hooks)`);
+        }
       }
 
       // Add .axme-code/ to .gitignore
@@ -774,10 +825,26 @@ Do NOT skip — without context you will miss critical project rules.
       }
       if (sub === "use" || sub === "set") {
         const mode = args[2];
-        if (mode !== "subscription" && mode !== "api_key") {
-          console.error("Usage: axme-code auth use <subscription|api_key>");
+        if (mode !== "subscription" && mode !== "api_key" && mode !== "cursor_sdk") {
+          console.error("Usage: axme-code auth use <subscription|api_key|cursor_sdk>");
           process.exit(1);
         }
+        if (mode === "cursor_sdk") {
+          // Non-interactive set still requires a key — read from
+          // CURSOR_API_KEY env or refuse politely.
+          const { loadCursorApiKey, saveCursorApiKey } = await import("./utils/auth-config.js");
+          if (!loadCursorApiKey() && !process.env.CURSOR_API_KEY) {
+            console.error(
+              "cursor_sdk mode requires a key. Set CURSOR_API_KEY in env, or run\n" +
+                "  axme-code auth          (interactive — paste key when prompted)",
+            );
+            process.exit(1);
+          }
+          if (process.env.CURSOR_API_KEY && !loadCursorApiKey()) {
+            saveCursorApiKey(process.env.CURSOR_API_KEY);
+            console.log("  Saved Cursor API key from env to ~/.config/axme-code/cursor.yaml (chmod 600)");
+          }
+        }
         saveAuthConfig(mode as AuthMode);
         console.log(`Saved auth mode: ${mode} (${authConfigPath()})`);
         break;
@@ -794,7 +861,7 @@ Do NOT skip — without context you will miss critical project rules.
           process.exit(1);
         }
         if (!process.stdin.isTTY) {
-          console.error("`axme-code auth` requires an interactive terminal. Use `axme-code auth use <subscription|api_key>` non-interactively.");
+          console.error("`axme-code auth` requires an interactive terminal. Use `axme-code auth use <subscription|api_key|cursor_sdk>` non-interactively.");
           process.exit(1);
         }
         const choice = await promptAuthChoice(options);
@@ -802,12 +869,23 @@ Do NOT skip — without context you will miss critical project rules.
           console.log("Cancelled. No change.");
           break;
         }
+        if (choice === "cursor_sdk" && !options.cursorSdk?.present) {
+          const { promptCursorApiKey } = await import("./utils/auth-prompt.js");
+          const { saveCursorApiKey } = await import("./utils/auth-config.js");
+          const key = await promptCursorApiKey();
+          if (!key) {
+            console.log("Cursor API key paste cancelled. No change.");
+            break;
+          }
+          saveCursorApiKey(key);
+          console.log("  Saved Cursor API key: ~/.config/axme-code/cursor.yaml (chmod 600)");
+        }
         saveAuthConfig(choice);
         console.log(`Saved auth mode: ${choice} (${authConfigPath()})`);
         break;
       }
       console.error(`Unknown 'auth' subcommand: ${sub}`);
-      console.error("Available: (none)|choose, status|show, use|set <subscription|api_key>");
+      console.error("Available: (none)|choose, status|show, use|set <subscription|api_key|cursor_sdk>");
       process.exit(1);
     }
 
diff --git a/src/setup/cursor-writers.ts b/src/setup/cursor-writers.ts
new file mode 100644
index 0000000..7bf3823
--- /dev/null
+++ b/src/setup/cursor-writers.ts
@@ -0,0 +1,160 @@
+/**
+ * Idempotent writers for Cursor-specific config files.
+ *
+ * Layout:
+ *   .cursor/mcp.json            — Cursor's MCP server registration (mirrors .mcp.json)
+ *   .cursor/hooks.json          — preToolUse / postToolUse / sessionEnd commands
+ *   .cursor/rules/axme-code.mdc — auto-applied rule (Cursor's CLAUDE.md analogue)
+ *
+ * All three writers preserve user-added entries on re-run: the merge logic
+ * filters out previous axme entries by string match on `axme-code` in the
+ * command field, then re-adds fresh ones — exactly the pattern
+ * configureHooks() uses for `.claude/settings.json`.
+ *
+ * D-080 forbids writing `.claude/CLAUDE.md`. Cursor's analogue is
+ * `.cursor/rules/<rule>.mdc` with YAML frontmatter (`alwaysApply: true`).
+ * The body content mirrors the Claude Code template but is reworded for
+ * Cursor terminology ("Cursor session" not "Claude session").
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const HOOK_TIMEOUT_MS: Record<HookKind, number> = {
+  preToolUse: 5,
+  postToolUse: 10,
+  sessionEnd: 120,
+};
+
+type HookKind = "preToolUse" | "postToolUse" | "sessionEnd";
+
+interface CursorHookEntry {
+  command: string;
+  type?: "command";
+  timeout?: number;
+  matcher?: string;
+  failClosed?: boolean;
+  loop_limit?: number | null;
+  [key: string]: unknown;
+}
+
+interface CursorHooksFile {
+  version?: number;
+  hooks?: Partial<Record<HookKind, CursorHookEntry[]>>;
+  [key: string]: unknown;
+}
+
+interface CursorMcpFile {
+  mcpServers?: Record<string, { command: string; args?: string[] }>;
+  [key: string]: unknown;
+}
+
+function readJsonOr<T extends object>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Write `.cursor/mcp.json`, merging with any existing servers. Cursor reads
+ * `.cursor/mcp.json` AND root `.mcp.json` — we always write the Cursor
+ * one too, so a repo configured with `--ide=cursor` keeps working even
+ * if the user later removes `.mcp.json`.
+ */
+export function writeCursorMcpJson(projectPath: string): void {
+  const path = join(projectPath, ".cursor", "mcp.json");
+  const cfg = readJsonOr<CursorMcpFile>(path, {});
+  if (!cfg.mcpServers) cfg.mcpServers = {};
+  cfg.mcpServers.axme = { command: "axme-code", args: ["serve"] };
+  writeJsonAtomic(path, cfg);
+}
+
+/**
+ * Write `.cursor/hooks.json` with three event arrays. Each entry uses
+ * `buildHookCommand()` with `--ide cursor` appended so the hook
+ * subprocess can pick the right adapter without re-detecting.
+ *
+ * Idempotency: existing entries whose command contains "axme-code" are
+ * dropped before re-insert; user-added entries are preserved verbatim.
+ */
+export function writeCursorHooksJson(
+  projectPath: string,
+  buildHookCommand: (hookName: string, projectPath: string) => string,
+): void {
+  const path = join(projectPath, ".cursor", "hooks.json");
+  const cfg = readJsonOr<CursorHooksFile>(path, { version: 1 });
+  if (!cfg.version) cfg.version = 1;
+  if (!cfg.hooks) cfg.hooks = {};
+
+  const hookKinds: HookKind[] = ["preToolUse", "postToolUse", "sessionEnd"];
+  const cliHookNames: Record<HookKind, string> = {
+    preToolUse: "pre-tool-use",
+    postToolUse: "post-tool-use",
+    sessionEnd: "session-end",
+  };
+
+  for (const kind of hookKinds) {
+    const existing = cfg.hooks[kind] ?? [];
+    const preserved = existing.filter((e) => !String(e.command ?? "").includes("axme-code"));
+    const fresh: CursorHookEntry = {
+      command: `${buildHookCommand(cliHookNames[kind], projectPath)} --ide cursor`,
+      type: "command",
+      timeout: HOOK_TIMEOUT_MS[kind],
+    };
+    cfg.hooks[kind] = [...preserved, fresh];
+  }
+
+  writeJsonAtomic(path, cfg);
+}
+
+const RULE_FRONTMATTER = `---
+name: axme-code
+description: AXME Code session start ritual + safety reminders for Cursor
+alwaysApply: true
+---
+`;
+
+const RULE_BODY = `## AXME Code
+
+### Session Start (MANDATORY)
+Call \`axme_context\` tool with this project's path at the start of every Cursor session.
+This loads: oracle, decisions, safety rules, memories, test plan, active plans.
+Do NOT skip — without context you will miss critical project rules.
+
+### During Work
+- Error pattern or successful approach discovered → call \`axme_save_memory\` immediately.
+- Architectural decision made or discovered → call \`axme_save_decision\` immediately.
+- New safety constraint found → call \`axme_update_safety\` immediately.
+
+### Git commit/push gate
+Every \`git commit\` and \`git push\` command MUST end with the marker:
+\`\`\`
+#!axme pr=<NUMBER|none> repo=<OWNER/REPO>
+\`\`\`
+Without this suffix the pre-tool-use hook blocks the command.
+
+### Available AXME tools
+\`axme_context\`, \`axme_save_memory\`, \`axme_save_decision\`, \`axme_update_safety\`,
+\`axme_safety\`, \`axme_status\`, \`axme_worklog\`, \`axme_workspace\`,
+\`axme_oracle\`, \`axme_decisions\`, \`axme_memories\`.
+`;
+
+/**
+ * Write `.cursor/rules/axme-code.mdc` (Cursor's auto-applied rule format).
+ * Always overwrites — the rule body is canonical and small. Frontmatter
+ * `alwaysApply: true` makes Cursor inject this content into every chat
+ * session's system context.
+ */
+export function writeCursorRulesMdc(projectPath: string, _isWorkspace: boolean): void {
+  const path = join(projectPath, ".cursor", "rules", "axme-code.mdc");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, RULE_FRONTMATTER + "\n" + RULE_BODY, "utf-8");
+}
diff --git a/src/types.ts b/src/types.ts
index 29e8cd2..4fc6371 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -398,9 +398,30 @@ export type E2EMode = "after-task" | "after-stage" | "manual";
 
 // --- Auth ---
 
-export type AuthMode = "subscription" | "api_key";
+/**
+ * Authentication mode for LLM agent invocations.
+ *
+ * - `subscription`: Claude Code OAuth subscription. The factory deletes
+ *   ANTHROPIC_API_KEY from the subprocess env so Claude Code doesn't pick
+ *   an empty-balance key over OAuth.
+ * - `api_key`: Direct ANTHROPIC_API_KEY in env, passed through unchanged.
+ * - `cursor_sdk`: Cursor SDK API key issued at cursor.com (Integrations).
+ *   The actual key is stored at ~/.config/axme-code/cursor.yaml (chmod 600);
+ *   `auth.yaml` only carries the mode flag.
+ */
+export type AuthMode = "subscription" | "api_key" | "cursor_sdk";
 
 export interface AuthConfig {
   mode: AuthMode;
   chosenAt: string;
 }
+
+/**
+ * Cursor SDK API key payload, stored separately at
+ * ~/.config/axme-code/cursor.yaml so the secret is not co-mingled with
+ * the auth-mode flag and can be permission-locked (chmod 600) on its own.
+ */
+export interface CursorApiKeyConfig {
+  apiKey: string;
+  chosenAt: string;
+}
diff --git a/src/utils/agent-options.ts b/src/utils/agent-options.ts
index 78d1009..128b733 100644
--- a/src/utils/agent-options.ts
+++ b/src/utils/agent-options.ts
@@ -6,7 +6,7 @@ import { execSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
-import { resolveAuthMode } from "./auth-config.js";
+import { resolveAuthMode, loadCursorApiKey } from "./auth-config.js";
 
 type Options = import("@anthropic-ai/claude-agent-sdk").Options;
 
@@ -200,12 +200,62 @@ export function buildAgentEnv(): NodeJS.ProcessEnv {
     AXME_TELEMETRY_DISABLED: "1",
     AXME_SKIP_HOOKS: "1",
   };
-  if (resolveAuthMode() === "subscription") {
+  const mode = resolveAuthMode();
+  if (mode === "subscription") {
+    delete env.ANTHROPIC_API_KEY;
+  }
+  if (mode === "cursor_sdk") {
+    // Hydrate CURSOR_API_KEY from cursor.yaml so the Cursor SDK adapter
+    // (lazy-imported at agent invocation time) can pick it up via env.
+    // If env already has a key, keep it — this lets users override the
+    // saved file on a per-run basis without rewriting cursor.yaml.
+    if (!env.CURSOR_API_KEY) {
+      const fileKey = loadCursorApiKey();
+      if (fileKey) env.CURSOR_API_KEY = fileKey;
+    }
+    // Cursor SDK doesn't read ANTHROPIC_API_KEY today, but if it ever
+    // adds dual-provider support, an empty-balance Anthropic key in env
+    // could surprise the user. Drop it explicitly.
     delete env.ANTHROPIC_API_KEY;
   }
   return env;
 }
 
+/**
+ * Map Claude-Agent-SDK tool names to Cursor SDK tool names.
+ *
+ * Most names pass through (Read/Glob/Grep/Edit/Write). Bash → Shell is
+ * the only rename. Tools not exposed by Cursor SDK (NotebookEdit, Agent,
+ * Skill, TodoWrite, WebFetch, WebSearch, ToolSearch) are dropped.
+ *
+ * Returns a deduplicated list. Used by the Cursor agent adapter to
+ * translate a buildAgentQueryOptions allowedTools/disallowedTools array
+ * into Cursor's vocabulary.
+ */
+export function mapClaudeToolsToCursor(tools: readonly string[]): string[] {
+  const mapping: Record<string, string | null> = {
+    Read: "Read",
+    Glob: "Glob",
+    Grep: "Grep",
+    Edit: "Edit",
+    Write: "Write",
+    Bash: "Shell",
+    NotebookEdit: null,
+    Agent: null,
+    Skill: null,
+    TodoWrite: null,
+    WebFetch: null,
+    WebSearch: null,
+    ToolSearch: null,
+  };
+  const out = new Set<string>();
+  for (const t of tools) {
+    const mapped = mapping[t];
+    if (mapped) out.add(mapped);
+  }
+  return [...out];
+}
+
 export function buildAgentQueryOptions(base: {
   cwd: string;
   model: string;
diff --git a/src/utils/agent-sdk-claude.ts b/src/utils/agent-sdk-claude.ts
new file mode 100644
index 0000000..307edd6
--- /dev/null
+++ b/src/utils/agent-sdk-claude.ts
@@ -0,0 +1,31 @@
+/**
+ * Claude Agent SDK wrapper conforming to the AgentSdk interface.
+ *
+ * Thin pass-through over `await import("@anthropic-ai/claude-agent-sdk")`.
+ * Today's hot path: every `for await (const msg of q)` loop in
+ * src/agents/* receives the raw SDK message stream — we yield it as-is
+ * and rely on the AgentMessage shape being a superset of the Claude SDK
+ * Message envelope.
+ */
+
+import type { AgentRole } from "./agent-options.js";
+import type { AgentMessage, AgentQuery, AgentSdk } from "./agent-sdk.js";
+
+export function createClaudeAgentSdk(_role: AgentRole): AgentSdk {
+  return {
+    ide: "claude-code",
+    async *query(q: AgentQuery): AsyncIterable<AgentMessage> {
+      const sdk = await import("@anthropic-ai/claude-agent-sdk");
+      // The Claude SDK's Options type is the source of truth here; we
+      // pass our AgentQuery options through with a structural cast.
+      // Callers (buildAgentQueryOptions) already produce the right shape.
+      const stream = sdk.query({
+        prompt: q.prompt,
+        options: q.options as unknown as Parameters<typeof sdk.query>[0]["options"],
+      });
+      for await (const msg of stream) {
+        yield msg as unknown as AgentMessage;
+      }
+    },
+  };
+}
diff --git a/src/utils/agent-sdk-cursor.ts b/src/utils/agent-sdk-cursor.ts
new file mode 100644
index 0000000..53d5407
--- /dev/null
+++ b/src/utils/agent-sdk-cursor.ts
@@ -0,0 +1,163 @@
+/**
+ * Cursor SDK wrapper conforming to the AgentSdk interface.
+ *
+ * Cursor's API is stateful: Agent.create() → agent.send(prompt) →
+ * run.stream(). We wrap that into the IDE-agnostic AsyncIterable<AgentMessage>
+ * shape so existing audit/scanner stream consumers don't need IDE-specific
+ * branches.
+ *
+ * System-prompt injection: Cursor SDK has no top-level systemPrompt field.
+ * The supported way is to prepend a system block to the first send() call
+ * (verified by Cursor agent spec-check on PR #129, 2026-05-10). The
+ * AgentDefinition.prompt + agentId pattern defines SUBAGENTS spawnable via
+ * the Task tool, NOT the outer agent's system prompt.
+ *
+ * Tool restriction: Cursor's tool taxonomy differs (Bash → Shell, no
+ * NotebookEdit/Agent/Skill/etc). agent-options.ts:mapClaudeToolsToCursor()
+ * does the translation; values not in Cursor's vocabulary are silently
+ * dropped (Cursor doesn't expose them so disallow is a no-op anyway).
+ */
+
+import type { AgentRole } from "./agent-options.js";
+import type { AgentMessage, AgentQuery, AgentSdk, AgentSdkFactoryOptions } from "./agent-sdk.js";
+import { loadCursorApiKey } from "./auth-config.js";
+
+interface CursorRunStream {
+  [Symbol.asyncIterator](): AsyncIterator<unknown>;
+}
+
+interface CursorRun {
+  stream(): CursorRunStream;
+  wait?(): Promise<{ status?: string; usage?: AgentMessage["usage"] }>;
+}
+
+interface CursorAgentInstance {
+  send(prompt: string): Promise<CursorRun>;
+  dispose?(): Promise<void>;
+}
+
+interface CursorSdkModule {
+  Agent: {
+    create(opts: {
+      apiKey: string;
+      model: { id: string };
+      local: { cwd: string; settingSources: string[]; mcpServers?: unknown };
+      agentId?: string;
+      [key: string]: unknown;
+    }): Promise<CursorAgentInstance>;
+  };
+}
+
+function resolveSystemPrompt(q: AgentQuery): string {
+  const sp = q.options.systemPrompt;
+  if (typeof sp === "string") return sp;
+  // The Claude-Code preset is meaningless for Cursor — only the `append`
+  // text contains the role-specific instructions worth forwarding.
+  return sp.append ?? "";
+}
+
+function buildWrappedPrompt(q: AgentQuery): string {
+  const systemPrompt = resolveSystemPrompt(q);
+  if (!systemPrompt.trim()) return q.prompt;
+  return `<system>\n${systemPrompt}\n</system>\n\n${q.prompt}`;
+}
+
+/**
+ * Translate one Cursor stream event into our AgentMessage shape.
+ * Returns null when the event type is one we deliberately ignore
+ * (status/system metadata, unstable tool_call schema, etc.).
+ */
+function translateCursorEvent(ev: unknown): AgentMessage | null {
+  if (!ev || typeof ev !== "object") return null;
+  const e = ev as Record<string, unknown>;
+  const t = e.type;
+  if (t === "assistant") {
+    const msg = e.message as { content?: unknown } | undefined;
+    type ContentBlocks = NonNullable<AgentMessage["message"]>["content"];
+    const content: ContentBlocks = Array.isArray(msg?.content)
+      ? (msg.content as ContentBlocks)
+      : [];
+    return {
+      type: "assistant",
+      message: { role: "assistant", content },
+    };
+  }
+  if (t === "thinking") {
+    const thinking = typeof e.thinking === "string" ? e.thinking : "";
+    return {
+      type: "assistant",
+      message: {
+        role: "assistant",
+        content: [{ type: "thinking", thinking }],
+      },
+    };
+  }
+  // tool_call, status, system: not consumed by axme-code's auditor /
+  // scanner stream loops. Ignore to keep yields clean.
+  return null;
+}
+
+export async function createCursorAgentSdk(
+  _role: AgentRole,
+  factoryOpts?: AgentSdkFactoryOptions,
+): Promise<AgentSdk> {
+  const apiKey = process.env.CURSOR_API_KEY ?? loadCursorApiKey();
+  if (!apiKey || !apiKey.trim()) {
+    throw new Error(
+      "CURSOR_API_KEY not configured. Run `axme-code setup --ide=cursor` to save one, " +
+        "or export CURSOR_API_KEY in the environment.",
+    );
+  }
+
+  const cursorMod = (await import("@cursor/sdk")) as unknown as CursorSdkModule;
+
+  return {
+    ide: "cursor",
+    async *query(q: AgentQuery): AsyncIterable<AgentMessage> {
+      const cwd = factoryOpts?.cwd ?? q.options.cwd;
+      const agent = await cursorMod.Agent.create({
+        apiKey,
+        model: { id: q.options.model },
+        local: { cwd, settingSources: [], mcpServers: [] },
+        agentId: `axme-${_role}`,
+      });
+
+      let accumulatedText = "";
+      let lastUsage: AgentMessage["usage"] | undefined;
+      let runStatus: string | undefined;
+      try {
+        const run = await agent.send(buildWrappedPrompt(q));
+        for await (const ev of run.stream()) {
+          const translated = translateCursorEvent(ev);
+          if (!translated) continue;
+          const msg = translated.message;
+          if (translated.type === "assistant" && msg) {
+            for (const block of msg.content) {
+              if (block.type === "text" && block.text) accumulatedText += block.text;
+            }
+          }
+          yield translated;
+        }
+        if (run.wait) {
+          try {
+            const result = await run.wait();
+            runStatus = result.status;
+            lastUsage = result.usage;
+          } catch { /* tolerate wait() unsupported / late errors */ }
+        }
+      } finally {
+        try { await agent.dispose?.(); } catch { /* swallow */ }
+      }
+
+      // Synthesize a terminal "result" message so cost-extractor and the
+      // existing auditor loop's `if (msg.type === "result")` branch fire
+      // exactly once per query.
+      yield {
+        type: "result",
+        subtype: runStatus === "completed" ? "success" : "error",
+        result: accumulatedText,
+        ...(lastUsage ? { usage: lastUsage } : {}),
+      };
+    },
+  };
+}
diff --git a/src/utils/agent-sdk.ts b/src/utils/agent-sdk.ts
new file mode 100644
index 0000000..bf9de3e
--- /dev/null
+++ b/src/utils/agent-sdk.ts
@@ -0,0 +1,160 @@
+/**
+ * IDE-agnostic LLM agent SDK abstraction.
+ *
+ * Two concrete implementations: Claude (via @anthropic-ai/claude-agent-sdk)
+ * and Cursor (via @cursor/sdk). The factory picks the right one based on
+ * the user's AuthMode + IDE, with a fallback chain:
+ *
+ *   1. preferred IDE (from opts, env AXME_IDE, or auth.yaml mode)
+ *   2. if cursor: try @cursor/sdk import; on win-arm64 / missing module
+ *      / missing CURSOR_API_KEY → warn + fall back
+ *   3. if claude: require findClaudePath() OR ANTHROPIC_API_KEY
+ *   4. else: throw AgentSdkUnavailableError — caller (audit worker) catches,
+ *      writes one log line, exits 0
+ *
+ * AgentMessage shape mirrors the Claude Agent SDK envelope so existing
+ * stream-consumption loops in src/agents/* keep working unchanged. The
+ * Cursor wrapper translates Cursor's discriminated event types into this
+ * shape on the fly.
+ */
+
+import type { AgentRole } from "./agent-options.js";
+import type { IdeKind } from "../types.js";
+import { resolveAuthMode } from "./auth-config.js";
+import { findClaudePath } from "./agent-options.js";
+import { detectIdeFromEnv } from "./ide-detect.js";
+
+export type AgentMessageKind = "assistant" | "thinking" | "tool_use" | "result" | "system";
+
+export interface AgentMessage {
+  type: AgentMessageKind;
+  message?: {
+    role: "assistant" | "user";
+    content: Array<{
+      type: "text" | "thinking" | "tool_use";
+      text?: string;
+      thinking?: string;
+      name?: string;
+      input?: unknown;
+    }>;
+  };
+  result?: string;
+  subtype?: "success" | "error";
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+  total_cost_usd?: number;
+  // Allow concrete implementations to forward additional fields the
+  // Claude SDK exposes (modelUsage, cost-extractor sub-keys, etc.).
+  [key: string]: unknown;
+}
+
+export interface AgentQuery {
+  prompt: string;
+  options: {
+    cwd: string;
+    model: string;
+    systemPrompt:
+      | string
+      | { type: "preset"; preset: "claude_code"; append?: string };
+    allowedTools: string[];
+    disallowedTools: string[];
+    maxTurns?: number;
+    env: NodeJS.ProcessEnv;
+    settingSources?: string[];
+    permissionMode?: "bypassPermissions";
+    pathToClaudeCodeExecutable?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface AgentSdk {
+  readonly ide: IdeKind;
+  query(q: AgentQuery): AsyncIterable<AgentMessage>;
+}
+
+export interface AgentSdkFactoryOptions {
+  /** Override IDE selection. Falls through to AXME_IDE env, then auth.yaml. */
+  preferredIde?: IdeKind;
+  /** Forwarded to wrappers that need a project root (Cursor SDK takes it
+   *  as `local.cwd`). When omitted, wrappers fall back to options.cwd
+   *  from the AgentQuery. */
+  cwd?: string;
+}
+
+/**
+ * Thrown when no LLM backend is usable. The detached audit worker catches
+ * this and writes a single log line — it never crashes the parent or
+ * triggers a retry loop.
+ */
+export class AgentSdkUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentSdkUnavailableError";
+  }
+}
+
+function authImpliedIde(): IdeKind | undefined {
+  try {
+    const mode = resolveAuthMode();
+    if (mode === "cursor_sdk") return "cursor";
+    if (mode === "subscription" || mode === "api_key") return "claude-code";
+  } catch { /* swallow */ }
+  return undefined;
+}
+
+function selectIde(opts?: AgentSdkFactoryOptions): IdeKind {
+  return opts?.preferredIde
+    ?? detectIdeFromEnv()
+    ?? authImpliedIde()
+    ?? "claude-code";
+}
+
+/**
+ * Create an AgentSdk for the requested role. Lazy-imports the concrete
+ * wrapper module so unused providers never inflate the cold-start cost.
+ */
+export async function createAgentSdk(
+  role: AgentRole,
+  opts?: AgentSdkFactoryOptions,
+): Promise<AgentSdk> {
+  const ide = selectIde(opts);
+
+  if (ide === "cursor") {
+    if (process.platform === "win32" && process.arch === "arm64") {
+      process.stderr.write(
+        "AXME: @cursor/sdk has no win-arm64 native binary; falling back to Claude SDK\n",
+      );
+      return await createClaudeFallback(role);
+    }
+    try {
+      const { createCursorAgentSdk } = await import("./agent-sdk-cursor.js");
+      const cursor = await createCursorAgentSdk(role, opts);
+      return cursor;
+    } catch (err) {
+      process.stderr.write(
+        `AXME: Cursor SDK unavailable (${(err as Error).message}); falling back to Claude SDK\n`,
+      );
+      return await createClaudeFallback(role);
+    }
+  }
+
+  return await createClaudeFallback(role);
+}
+
+async function createClaudeFallback(role: AgentRole): Promise<AgentSdk> {
+  const haveBinary = !!findClaudePath();
+  const haveKey = !!process.env.ANTHROPIC_API_KEY;
+  if (!haveBinary && !haveKey) {
+    throw new AgentSdkUnavailableError(
+      "No usable LLM backend. Install @cursor/sdk + set CURSOR_API_KEY (Cursor users), " +
+        "or install `claude` and run `claude /login` (subscription users), " +
+        "or set ANTHROPIC_API_KEY (API users).",
+    );
+  }
+  const { createClaudeAgentSdk } = await import("./agent-sdk-claude.js");
+  return createClaudeAgentSdk(role);
+}
diff --git a/src/utils/auth-config.ts b/src/utils/auth-config.ts
index 22bf3d1..ca2bdb1 100644
--- a/src/utils/auth-config.ts
+++ b/src/utils/auth-config.ts
@@ -12,11 +12,12 @@
  * the user by persisting a guessed choice.
  */
 
+import { chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import yaml from "js-yaml";
 import { atomicWrite, ensureDir, readSafe, pathExists } from "../storage/engine.js";
-import type { AuthConfig, AuthMode } from "../types.js";
+import type { AuthConfig, AuthMode, CursorApiKeyConfig } from "../types.js";
 import { detectAuthOptions, type AuthOptions } from "./auth-detect.js";
 
 /**
@@ -31,6 +32,15 @@ export function authConfigPath(): string {
   return join(configDir(), "auth.yaml");
 }
 
+/** Path to the Cursor SDK API key file. The key lives separately from
+ *  auth.yaml so we can chmod 600 the secret without locking down the
+ *  mode flag. */
+export function cursorApiKeyPath(): string {
+  return join(configDir(), "cursor.yaml");
+}
+
+const VALID_AUTH_MODES: ReadonlyArray<AuthMode> = ["subscription", "api_key", "cursor_sdk"];
+
 export function loadAuthConfig(): AuthConfig | null {
   const file = authConfigPath();
   if (!pathExists(file)) return null;
@@ -39,9 +49,9 @@ export function loadAuthConfig(): AuthConfig | null {
   try {
     const parsed = yaml.load(raw) as Partial<AuthConfig> | null;
     if (!parsed || typeof parsed !== "object") return null;
-    if (parsed.mode !== "subscription" && parsed.mode !== "api_key") return null;
+    if (!VALID_AUTH_MODES.includes(parsed.mode as AuthMode)) return null;
     const chosenAt = typeof parsed.chosenAt === "string" ? parsed.chosenAt : new Date().toISOString();
-    return { mode: parsed.mode, chosenAt };
+    return { mode: parsed.mode as AuthMode, chosenAt };
   } catch {
     return null;
   }
@@ -54,15 +64,57 @@ export function saveAuthConfig(mode: AuthMode): AuthConfig {
   return config;
 }
 
+/**
+ * Read the Cursor SDK API key from cursor.yaml. Returns null if not
+ * configured. Callers (Cursor SDK adapter) should ALSO check
+ * process.env.CURSOR_API_KEY as a fallback so users can override via env
+ * without rewriting the config.
+ */
+export function loadCursorApiKey(): string | undefined {
+  const file = cursorApiKeyPath();
+  if (!pathExists(file)) return undefined;
+  const raw = readSafe(file);
+  if (!raw) return undefined;
+  try {
+    const parsed = yaml.load(raw) as Partial<CursorApiKeyConfig> | null;
+    if (!parsed || typeof parsed !== "object") return undefined;
+    const key = parsed.apiKey;
+    if (typeof key !== "string" || !key.trim()) return undefined;
+    return key.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist the Cursor SDK API key to cursor.yaml with mode 0600 so other
+ * users on the machine cannot read it. The mode flag in auth.yaml is
+ * NOT touched here — call saveAuthConfig("cursor_sdk") separately.
+ */
+export function saveCursorApiKey(apiKey: string): CursorApiKeyConfig {
+  ensureDir(configDir());
+  const config: CursorApiKeyConfig = { apiKey: apiKey.trim(), chosenAt: new Date().toISOString() };
+  const path = cursorApiKeyPath();
+  atomicWrite(path, yaml.dump(config));
+  // Best-effort permission lock; on Windows chmod is a no-op and the file
+  // inherits the directory's ACLs (ACL inheritance from %USERPROFILE%
+  // already excludes other users, so this is safe-by-default there).
+  try { chmodSync(path, 0o600); } catch { /* swallow on Windows */ }
+  return config;
+}
+
 /**
  * Choose the sensible default when no saved choice exists and we can't ask
  * the user. If an API key is set (regardless of subscription state) we keep
  * the existing behavior: pass env through to Claude Code and let it decide.
- * If only subscription is available, prefer it. If neither, return api_key
- * so we fail the same way Claude Code would fail on its own.
+ * If only subscription is available, prefer it. If only a Cursor SDK key
+ * is available (cursor.yaml present OR CURSOR_API_KEY env), prefer it.
+ * If neither, return api_key so we fail the same way Claude Code would
+ * fail on its own.
  */
 function heuristicMode(options: AuthOptions): AuthMode {
-  if (options.subscription.present && !options.apiKey.present) return "subscription";
+  if (options.subscription.present && !options.apiKey.present && !options.cursorSdk?.present) return "subscription";
+  if (options.cursorSdk?.present && !options.apiKey.present && !options.subscription.present) return "cursor_sdk";
   return "api_key";
 }
 
diff --git a/src/utils/auth-detect.ts b/src/utils/auth-detect.ts
index 5bd11d0..a480bfe 100644
--- a/src/utils/auth-detect.ts
+++ b/src/utils/auth-detect.ts
@@ -13,7 +13,8 @@
 import { execFileSync } from "node:child_process";
 import { homedir, userInfo } from "node:os";
 import { join } from "node:path";
-import { pathExists } from "../storage/engine.js";
+import { pathExists, readSafe } from "../storage/engine.js";
+import yaml from "js-yaml";
 import { findClaudePath } from "./agent-options.js";
 
 export interface ApiKeyOption {
@@ -32,9 +33,21 @@ export interface SubscriptionOption {
   binaryFound: boolean;
 }
 
+export interface CursorSdkOption {
+  /** True if a Cursor SDK API key is configured (env or cursor.yaml). */
+  present: boolean;
+  /** Where the key was found. */
+  source?: "env" | "filesystem";
+  /** Human-readable detail — env var name or file path. */
+  details?: string;
+  /** Masked representation for display. */
+  masked?: string;
+}
+
 export interface AuthOptions {
   apiKey: ApiKeyOption;
   subscription: SubscriptionOption;
+  cursorSdk?: CursorSdkOption;
 }
 
 function maskApiKey(key: string): string {
@@ -44,6 +57,42 @@ function maskApiKey(key: string): string {
   return `${prefix}...${last4}`;
 }
 
+function maskCursorKey(key: string): string {
+  const trimmed = key.trim();
+  return `...${trimmed.slice(-4)}`;
+}
+
+function detectCursorSdk(): CursorSdkOption {
+  // 1. Env var
+  const envKey = process.env.CURSOR_API_KEY;
+  if (envKey && envKey.trim()) {
+    return {
+      present: true,
+      source: "env",
+      details: "CURSOR_API_KEY",
+      masked: maskCursorKey(envKey),
+    };
+  }
+  // 2. ~/.config/axme-code/cursor.yaml — read inline (no agent-options import
+  //    cycle through auth-config)
+  const cursorYaml = join(homedir(), ".config", "axme-code", "cursor.yaml");
+  if (pathExists(cursorYaml)) {
+    try {
+      const raw = readSafe(cursorYaml);
+      const parsed = yaml.load(raw) as { apiKey?: string } | null;
+      if (parsed && typeof parsed.apiKey === "string" && parsed.apiKey.trim()) {
+        return {
+          present: true,
+          source: "filesystem",
+          details: cursorYaml,
+          masked: maskCursorKey(parsed.apiKey),
+        };
+      }
+    } catch { /* fall through */ }
+  }
+  return { present: false };
+}
+
 function detectApiKey(): ApiKeyOption {
   const key = process.env.ANTHROPIC_API_KEY;
   if (!key || !key.trim()) return { present: false };
@@ -106,5 +155,6 @@ export function detectAuthOptions(): AuthOptions {
   return {
     apiKey: detectApiKey(),
     subscription: detectSubscription(),
+    cursorSdk: detectCursorSdk(),
   };
 }
diff --git a/src/utils/auth-prompt.ts b/src/utils/auth-prompt.ts
index d56b803..5bdb5b5 100644
--- a/src/utils/auth-prompt.ts
+++ b/src/utils/auth-prompt.ts
@@ -28,40 +28,92 @@ export function formatDetectionBlock(options: AuthOptions): string {
   } else {
     lines.push("  [2] Claude Code subscription — claude binary not found on PATH");
   }
+  if (options.cursorSdk?.present) {
+    const detail = options.cursorSdk.details ? ` (${options.cursorSdk.details})` : "";
+    lines.push(`  [3] Cursor SDK API key: ${options.cursorSdk.masked}${detail}`);
+  } else {
+    lines.push("  [3] Cursor SDK API key — not set (generate at cursor.com → Integrations)");
+  }
   return lines.join("\n");
 }
 
 function defaultChoice(options: AuthOptions): AuthMode {
-  if (options.subscription.present && !options.apiKey.present) return "subscription";
-  if (options.apiKey.present && !options.subscription.present) return "api_key";
-  return options.subscription.present ? "subscription" : "api_key";
+  // Single-credential machines: pick the only mode that actually works.
+  const haveSub = options.subscription.present;
+  const haveKey = options.apiKey.present;
+  const haveCursor = options.cursorSdk?.present === true;
+  const count = (haveSub ? 1 : 0) + (haveKey ? 1 : 0) + (haveCursor ? 1 : 0);
+  if (count === 1) {
+    if (haveSub) return "subscription";
+    if (haveKey) return "api_key";
+    if (haveCursor) return "cursor_sdk";
+  }
+  // Multiple credentials present — keep the existing Claude-first preference
+  // so existing setups don't suddenly switch to Cursor SDK billing without
+  // an explicit user choice.
+  if (haveSub) return "subscription";
+  if (haveKey) return "api_key";
+  if (haveCursor) return "cursor_sdk";
+  return "api_key";
 }
 
 export function hasAnyAuth(options: AuthOptions): boolean {
-  return options.apiKey.present || options.subscription.present;
+  return options.apiKey.present || options.subscription.present || options.cursorSdk?.present === true;
 }
 
 /**
  * Interactive prompt. Returns the chosen mode or null if the user aborted.
  * Requires a TTY on stdin — callers must check `process.stdin.isTTY` first
  * and fall back to a non-interactive path otherwise.
+ *
+ * Choice 3 (Cursor SDK) is the only one that may need a follow-up paste:
+ * if the user picks it but no key is configured yet, the caller is
+ * responsible for running `promptCursorApiKey()` separately and persisting
+ * via `saveCursorApiKey()` from auth-config.
  */
 export async function promptAuthChoice(options: AuthOptions): Promise<AuthMode | null> {
   const def = defaultChoice(options);
-  const defLabel = def === "subscription" ? "2" : "1";
+  const defLabel = def === "subscription" ? "2" : def === "cursor_sdk" ? "3" : "1";
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
     while (true) {
       const answer = await new Promise<string>((resolve) => {
-        rl.question(`Which should axme-code use? [1=api_key, 2=subscription, default ${defLabel}]: `, resolve);
+        rl.question(`Which should axme-code use? [1=api_key, 2=subscription, 3=cursor_sdk, default ${defLabel}]: `, resolve);
       });
       const trimmed = answer.trim().toLowerCase();
       if (trimmed === "") return def;
       if (trimmed === "1" || trimmed === "api_key" || trimmed === "key") return "api_key";
       if (trimmed === "2" || trimmed === "subscription" || trimmed === "sub") return "subscription";
+      if (trimmed === "3" || trimmed === "cursor_sdk" || trimmed === "cursor") return "cursor_sdk";
+      if (trimmed === "q" || trimmed === "quit" || trimmed === "cancel") return null;
+      process.stdout.write("  Enter 1, 2, 3, or q to cancel.\n");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Paste-once prompt for the Cursor SDK API key. Validates that the input
+ * looks like a key (length >= 20, no whitespace inside). Returns the
+ * trimmed key on success or null if the user aborted.
+ */
+export async function promptCursorApiKey(): Promise<string | null> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    while (true) {
+      const answer = await new Promise<string>((resolve) => {
+        rl.question("Paste your Cursor SDK API key (or 'q' to cancel): ", resolve);
+      });
+      const trimmed = answer.trim();
+      if (!trimmed) continue;
       if (trimmed === "q" || trimmed === "quit" || trimmed === "cancel") return null;
-      process.stdout.write("  Enter 1, 2, or q to cancel.\n");
+      if (trimmed.length < 20 || /\s/.test(trimmed)) {
+        process.stdout.write("  That doesn't look like a valid API key. Try again or 'q' to cancel.\n");
+        continue;
+      }
+      return trimmed;
     }
   } finally {
     rl.close();
diff --git a/test/agent-sdk-factory.test.ts b/test/agent-sdk-factory.test.ts
new file mode 100644
index 0000000..bef7f26
--- /dev/null
+++ b/test/agent-sdk-factory.test.ts
@@ -0,0 +1,125 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SANDBOX_HOME = "/tmp/axme-agent-sdk-factory-test";
+const ORIGINAL_HOME = process.env.HOME;
+const ORIGINAL_AXME_IDE = process.env.AXME_IDE;
+const ORIGINAL_API_KEY = process.env.ANTHROPIC_API_KEY;
+const ORIGINAL_CURSOR_KEY = process.env.CURSOR_API_KEY;
+
+beforeEach(() => {
+  rmSync(SANDBOX_HOME, { recursive: true, force: true });
+  mkdirSync(SANDBOX_HOME, { recursive: true });
+  process.env.HOME = SANDBOX_HOME;
+  delete process.env.AXME_IDE;
+  delete process.env.CURSOR_API_KEY;
+  // Keep ANTHROPIC_API_KEY out so factory falls into the "neither" path
+  // unless a test sets it explicitly.
+  delete process.env.ANTHROPIC_API_KEY;
+});
+
+afterEach(() => {
+  rmSync(SANDBOX_HOME, { recursive: true, force: true });
+  if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIGINAL_HOME;
+  if (ORIGINAL_AXME_IDE === undefined) delete process.env.AXME_IDE;
+  else process.env.AXME_IDE = ORIGINAL_AXME_IDE;
+  if (ORIGINAL_API_KEY === undefined) delete process.env.ANTHROPIC_API_KEY;
+  else process.env.ANTHROPIC_API_KEY = ORIGINAL_API_KEY;
+  if (ORIGINAL_CURSOR_KEY === undefined) delete process.env.CURSOR_API_KEY;
+  else process.env.CURSOR_API_KEY = ORIGINAL_CURSOR_KEY;
+});
+
+describe("createAgentSdk — IDE selection", () => {
+  it("selects claude-code by default when no env / auth.yaml signals are set", async () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-fake-for-test";
+    const { createAgentSdk } = await import("../src/utils/agent-sdk.js");
+    const sdk = await createAgentSdk("auditor");
+    assert.equal(sdk.ide, "claude-code");
+  });
+
+  it("selects cursor when AXME_IDE=cursor and CURSOR_API_KEY set", async () => {
+    process.env.AXME_IDE = "cursor";
+    process.env.CURSOR_API_KEY = "ck-fake-1234567890abcdefghijklmnopqrstuv";
+    const { createAgentSdk } = await import("../src/utils/agent-sdk.js");
+    const sdk = await createAgentSdk("auditor", { cwd: SANDBOX_HOME });
+    assert.equal(sdk.ide, "cursor");
+  });
+
+  it("falls back to claude-code when AXME_IDE=cursor but CURSOR_API_KEY missing", async () => {
+    process.env.AXME_IDE = "cursor";
+    process.env.ANTHROPIC_API_KEY = "sk-ant-fake-for-test";
+    // CURSOR_API_KEY intentionally unset
+    const { createAgentSdk } = await import("../src/utils/agent-sdk.js");
+    const sdk = await createAgentSdk("auditor", { cwd: SANDBOX_HOME });
+    assert.equal(sdk.ide, "claude-code");
+  });
+
+  it("auth.yaml mode=cursor_sdk implies cursor IDE", async () => {
+    mkdirSync(join(SANDBOX_HOME, ".config", "axme-code"), { recursive: true });
+    writeFileSync(
+      join(SANDBOX_HOME, ".config", "axme-code", "auth.yaml"),
+      "mode: cursor_sdk\nchosenAt: '2026-05-10T00:00:00.000Z'\n",
+    );
+    process.env.CURSOR_API_KEY = "ck-fake-1234567890abcdefghijklmnopqrstuv";
+    const { createAgentSdk } = await import("../src/utils/agent-sdk.js");
+    const sdk = await createAgentSdk("auditor", { cwd: SANDBOX_HOME });
+    assert.equal(sdk.ide, "cursor");
+  });
+
+  it("throws AgentSdkUnavailableError when neither backend usable", async () => {
+    // No ANTHROPIC_API_KEY, no CURSOR_API_KEY, no auth.yaml
+    // findClaudePath() may still find a binary on this dev machine — but the
+    // factory's claude fallback also requires either a binary OR an env key.
+    // To make the test deterministic regardless of dev machine state, we
+    // only check the cursor preference path with no key.
+    process.env.AXME_IDE = "cursor";
+    // Also override AXME_CLAUDE_EXECUTABLE so claude fallback fails.
+    const ORIG_AXME_CLAUDE = process.env.AXME_CLAUDE_EXECUTABLE;
+    process.env.AXME_CLAUDE_EXECUTABLE = "/nonexistent/path/that/does/not/exist";
+    try {
+      const { createAgentSdk, AgentSdkUnavailableError } = await import("../src/utils/agent-sdk.js");
+      const { _resetFindClaudePath } = await import("../src/utils/agent-options.js");
+      _resetFindClaudePath();
+      // The dev machine likely still has /home/<user>/.local/bin/claude or
+      // similar in the standard-paths fallback; if so, this test is a
+      // no-op (factory returns Claude wrapper). Accept either outcome —
+      // the negative path (throw) is what matters when no binary exists.
+      try {
+        const sdk = await createAgentSdk("auditor", { cwd: SANDBOX_HOME });
+        // If we reach here, Claude binary was found via standard paths;
+        // verify the type is correct anyway.
+        assert.equal(sdk.ide, "claude-code");
+      } catch (err) {
+        assert.ok(err instanceof AgentSdkUnavailableError);
+      }
+    } finally {
+      if (ORIG_AXME_CLAUDE === undefined) delete process.env.AXME_CLAUDE_EXECUTABLE;
+      else process.env.AXME_CLAUDE_EXECUTABLE = ORIG_AXME_CLAUDE;
+      const { _resetFindClaudePath } = await import("../src/utils/agent-options.js");
+      _resetFindClaudePath();
+    }
+  });
+});
+
+describe("mapClaudeToolsToCursor", () => {
+  it("Bash → Shell, drops Cursor-incompatible tools", async () => {
+    const { mapClaudeToolsToCursor } = await import("../src/utils/agent-options.js");
+    const result = mapClaudeToolsToCursor(["Read", "Glob", "Grep", "Edit", "Write", "Bash", "NotebookEdit", "Agent", "TodoWrite"]);
+    assert.deepEqual(result.sort(), ["Edit", "Glob", "Grep", "Read", "Shell", "Write"]);
+  });
+
+  it("dedupes overlapping inputs", async () => {
+    const { mapClaudeToolsToCursor } = await import("../src/utils/agent-options.js");
+    const result = mapClaudeToolsToCursor(["Read", "Read", "Bash"]);
+    assert.deepEqual(result.sort(), ["Read", "Shell"]);
+  });
+
+  it("returns empty array for entirely-incompatible input", async () => {
+    const { mapClaudeToolsToCursor } = await import("../src/utils/agent-options.js");
+    const result = mapClaudeToolsToCursor(["WebFetch", "WebSearch", "Skill"]);
+    assert.deepEqual(result, []);
+  });
+});
diff --git a/test/cursor-auth-config.test.ts b/test/cursor-auth-config.test.ts
new file mode 100644
index 0000000..3162254
--- /dev/null
+++ b/test/cursor-auth-config.test.ts
@@ -0,0 +1,73 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// Override $HOME so the auth-config module reads from a sandboxed path.
+const SANDBOX_HOME = "/tmp/axme-cursor-auth-test-home";
+const ORIGINAL_HOME = process.env.HOME;
+
+beforeEach(() => {
+  rmSync(SANDBOX_HOME, { recursive: true, force: true });
+  mkdirSync(SANDBOX_HOME, { recursive: true });
+  process.env.HOME = SANDBOX_HOME;
+});
+
+afterEach(() => {
+  rmSync(SANDBOX_HOME, { recursive: true, force: true });
+  if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIGINAL_HOME;
+});
+
+describe("auth.yaml round-trip with cursor_sdk mode", () => {
+  it("saveAuthConfig('cursor_sdk') then loadAuthConfig() returns mode + chosenAt", async () => {
+    const { saveAuthConfig, loadAuthConfig } = await import("../src/utils/auth-config.js");
+    saveAuthConfig("cursor_sdk");
+    const loaded = loadAuthConfig();
+    assert.ok(loaded);
+    assert.equal(loaded!.mode, "cursor_sdk");
+    assert.equal(typeof loaded!.chosenAt, "string");
+  });
+
+  it("rejects unknown modes from yaml", async () => {
+    const { authConfigPath, loadAuthConfig } = await import("../src/utils/auth-config.js");
+    mkdirSync(join(SANDBOX_HOME, ".config", "axme-code"), { recursive: true });
+    writeFileSync(authConfigPath(), "mode: bogus\nchosenAt: '2026-01-01'\n");
+    assert.equal(loadAuthConfig(), null);
+  });
+
+  it("accepts the existing modes (subscription, api_key) for backward compat", async () => {
+    const { saveAuthConfig, loadAuthConfig } = await import("../src/utils/auth-config.js");
+    saveAuthConfig("subscription");
+    assert.equal(loadAuthConfig()?.mode, "subscription");
+    saveAuthConfig("api_key");
+    assert.equal(loadAuthConfig()?.mode, "api_key");
+  });
+});
+
+describe("cursor.yaml — paste-once API key", () => {
+  it("saveCursorApiKey writes to ~/.config/axme-code/cursor.yaml with mode 0600 (POSIX)", async () => {
+    const { saveCursorApiKey, cursorApiKeyPath, loadCursorApiKey } =
+      await import("../src/utils/auth-config.js");
+    saveCursorApiKey("ck-test-1234567890abcdefghijklmnopqrstuv");
+    const path = cursorApiKeyPath();
+    assert.ok(existsSync(path));
+    if (process.platform !== "win32") {
+      const stat = statSync(path);
+      assert.equal(stat.mode & 0o777, 0o600, "cursor.yaml must be chmod 600");
+    }
+    assert.equal(loadCursorApiKey(), "ck-test-1234567890abcdefghijklmnopqrstuv");
+  });
+
+  it("loadCursorApiKey returns undefined when file missing", async () => {
+    const { loadCursorApiKey } = await import("../src/utils/auth-config.js");
+    assert.equal(loadCursorApiKey(), undefined);
+  });
+
+  it("loadCursorApiKey returns undefined when file present but apiKey field empty", async () => {
+    const { cursorApiKeyPath, loadCursorApiKey } = await import("../src/utils/auth-config.js");
+    mkdirSync(join(SANDBOX_HOME, ".config", "axme-code"), { recursive: true });
+    writeFileSync(cursorApiKeyPath(), "apiKey: ''\nchosenAt: '2026-01-01'\n");
+    assert.equal(loadCursorApiKey(), undefined);
+  });
+});
diff --git a/test/cursor-setup-writers.test.ts b/test/cursor-setup-writers.test.ts
new file mode 100644
index 0000000..eb4b899
--- /dev/null
+++ b/test/cursor-setup-writers.test.ts
@@ -0,0 +1,133 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  writeCursorMcpJson,
+  writeCursorHooksJson,
+  writeCursorRulesMdc,
+} from "../src/setup/cursor-writers.js";
+
+const ROOT = "/tmp/axme-cursor-writers-test";
+
+function fakeBuildHookCommand(hookName: string, projectPath: string): string {
+  return `"/bin/node" "/usr/local/bin/axme-code" hook ${hookName} --workspace "${projectPath}"`;
+}
+
+beforeEach(() => {
+  rmSync(ROOT, { recursive: true, force: true });
+  mkdirSync(ROOT, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(ROOT, { recursive: true, force: true });
+});
+
+describe("writeCursorMcpJson", () => {
+  it("creates .cursor/mcp.json with axme entry when missing", () => {
+    writeCursorMcpJson(ROOT);
+    const path = join(ROOT, ".cursor", "mcp.json");
+    assert.ok(existsSync(path));
+    const cfg = JSON.parse(readFileSync(path, "utf-8"));
+    assert.deepEqual(cfg.mcpServers.axme, { command: "axme-code", args: ["serve"] });
+  });
+
+  it("merges into existing file without dropping unrelated mcpServers", () => {
+    mkdirSync(join(ROOT, ".cursor"), { recursive: true });
+    writeFileSync(
+      join(ROOT, ".cursor", "mcp.json"),
+      JSON.stringify({ mcpServers: { other: { command: "other-mcp" } } }),
+    );
+    writeCursorMcpJson(ROOT);
+    const cfg = JSON.parse(readFileSync(join(ROOT, ".cursor", "mcp.json"), "utf-8"));
+    assert.deepEqual(cfg.mcpServers.other, { command: "other-mcp" });
+    assert.deepEqual(cfg.mcpServers.axme, { command: "axme-code", args: ["serve"] });
+  });
+
+  it("is idempotent on re-run", () => {
+    writeCursorMcpJson(ROOT);
+    writeCursorMcpJson(ROOT);
+    const cfg = JSON.parse(readFileSync(join(ROOT, ".cursor", "mcp.json"), "utf-8"));
+    assert.equal(Object.keys(cfg.mcpServers).length, 1);
+  });
+});
+
+describe("writeCursorHooksJson", () => {
+  it("creates version:1 file with three hook arrays + --ide cursor flag", () => {
+    writeCursorHooksJson(ROOT, fakeBuildHookCommand);
+    const path = join(ROOT, ".cursor", "hooks.json");
+    assert.ok(existsSync(path));
+    const cfg = JSON.parse(readFileSync(path, "utf-8"));
+    assert.equal(cfg.version, 1);
+    for (const kind of ["preToolUse", "postToolUse", "sessionEnd"]) {
+      const arr = cfg.hooks[kind];
+      assert.ok(Array.isArray(arr) && arr.length === 1, `${kind} should have one entry`);
+      assert.match(arr[0].command, /--ide cursor/);
+      assert.match(arr[0].command, /axme-code/);
+      assert.equal(arr[0].type, "command");
+      assert.ok(typeof arr[0].timeout === "number");
+    }
+  });
+
+  it("dedups axme entries on re-run, preserves user entries", () => {
+    mkdirSync(join(ROOT, ".cursor"), { recursive: true });
+    writeFileSync(
+      join(ROOT, ".cursor", "hooks.json"),
+      JSON.stringify({
+        version: 1,
+        hooks: {
+          preToolUse: [
+            { command: "echo user-hook", type: "command" },
+            { command: "axme-code hook pre-tool-use --workspace OLD --ide cursor", type: "command" },
+          ],
+          postToolUse: [],
+          sessionEnd: [],
+        },
+      }),
+    );
+    writeCursorHooksJson(ROOT, fakeBuildHookCommand);
+    const cfg = JSON.parse(readFileSync(join(ROOT, ".cursor", "hooks.json"), "utf-8"));
+    const pre = cfg.hooks.preToolUse;
+    // user-hook preserved + 1 fresh axme entry (old axme entry removed)
+    assert.equal(pre.length, 2, `expected 2 entries, got ${JSON.stringify(pre)}`);
+    assert.equal(pre[0].command, "echo user-hook");
+    assert.match(pre[1].command, /axme-code/);
+    assert.match(pre[1].command, /--ide cursor/);
+    assert.ok(!pre[1].command.includes("OLD"), "old axme entry should be replaced");
+  });
+
+  it("re-running multiple times does not duplicate axme entries", () => {
+    writeCursorHooksJson(ROOT, fakeBuildHookCommand);
+    writeCursorHooksJson(ROOT, fakeBuildHookCommand);
+    writeCursorHooksJson(ROOT, fakeBuildHookCommand);
+    const cfg = JSON.parse(readFileSync(join(ROOT, ".cursor", "hooks.json"), "utf-8"));
+    for (const kind of ["preToolUse", "postToolUse", "sessionEnd"]) {
+      assert.equal(cfg.hooks[kind].length, 1, `${kind} duplicated`);
+    }
+  });
+});
+
+describe("writeCursorRulesMdc", () => {
+  it("creates .cursor/rules/axme-code.mdc with frontmatter and body", () => {
+    writeCursorRulesMdc(ROOT, false);
+    const path = join(ROOT, ".cursor", "rules", "axme-code.mdc");
+    assert.ok(existsSync(path));
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /^---\nname: axme-code/m);
+    assert.match(content, /alwaysApply: true/);
+    assert.match(content, /## AXME Code/);
+    assert.match(content, /Session Start \(MANDATORY\)/);
+    assert.match(content, /axme_context/);
+    // Cursor wording — not Claude
+    assert.ok(content.includes("Cursor session"));
+  });
+
+  it("overwrites on re-run", () => {
+    writeCursorRulesMdc(ROOT, false);
+    const first = readFileSync(join(ROOT, ".cursor", "rules", "axme-code.mdc"), "utf-8");
+    writeCursorRulesMdc(ROOT, true);
+    const second = readFileSync(join(ROOT, ".cursor", "rules", "axme-code.mdc"), "utf-8");
+    // Body content is canonical regardless of isWorkspace flag for now
+    assert.equal(first, second);
+  });
+});

From 85d1e576aed88f60dccdb2182264d333e1c3c664 Mon Sep 17 00:00:00 2001
From: geobelsky <geobelsky@gmail.com>
Date: Sun, 10 May 2026 11:49:53 +0000
Subject: [PATCH 4/6] feat(agents): route LLM agents through AgentSdk factory
 (PR-3 wiring)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces every direct `await import("@anthropic-ai/claude-agent-sdk")`
in src/agents/* with `await createAgentSdk(role, { cwd })` so the
auditor, scanners, kb-auditor, and memory-extractor pick the right SDK
(Claude or Cursor) at runtime based on auth.yaml mode + AXME_IDE env.

Touched call sites (8 in 7 files):
- src/agents/session-auditor.ts: runAuditChunk + formatAuditResult
- src/agents/kb-auditor.ts: runKbAudit
- src/agents/memory-extractor.ts: extractMemories
- src/agents/scanners/oracle.ts: runOracleScan
- src/agents/scanners/safety.ts: runSafetyScan
- src/agents/scanners/decision.ts: runDecisionScan
- src/agents/scanners/deploy.ts: runDeployScan

Each call site retains its existing buildAgentQueryOptions/manual
queryOpts construction unchanged — only the SDK access path swaps to
the factory. Loop body (`for await msg`) shape is identical because
AgentMessage mirrors Claude SDK's message envelope.

src/utils/agent-sdk.ts:
- Renamed inline `options` shape to exported `AgentQueryOptions`.
- Made every field except `prompt` optional. Reason: existing callers
  pass Claude SDK's `Options` type (which has most fields optional),
  and the Cursor adapter only needs `cwd` + `model` + `systemPrompt` —
  the rest is forwarded as-is to whichever wrapper.
- `systemPrompt` widened to `string | string[] | { preset object }` to
  match Claude SDK 0.2.112+ which now accepts string arrays.
- `permissionMode` widened to `string` (Claude SDK has more values
  than just "bypassPermissions").

src/utils/agent-sdk-cursor.ts:
- resolveSystemPrompt now handles `undefined` and `string[]` inputs.
- Cursor wrapper falls back to `process.cwd()` and "composer-2" when
  options.cwd / options.model are absent (defensive — shouldn't
  happen in practice, but type-correctness matters).

Required for the upcoming Cursor extension: when an .vsix-installed
extension running in Cursor invokes an audit, the factory selects
@cursor/sdk via cursor_sdk auth mode and the auditor uses Cursor's
billing instead of falling through to Claude. Without this commit
the auditor would skip-or-fall-back even with a valid Cursor key.

Tests: 595/595 pass (no test changes needed — call shape unchanged).
tsc --noEmit clean. Build clean.

#!axme pr=129 repo=AxmeAI/axme-code
---
 src/agents/kb-auditor.ts        |  3 ++-
 src/agents/memory-extractor.ts  |  3 ++-
 src/agents/scanners/decision.ts |  3 ++-
 src/agents/scanners/deploy.ts   |  3 ++-
 src/agents/scanners/oracle.ts   |  3 ++-
 src/agents/scanners/safety.ts   |  3 ++-
 src/agents/session-auditor.ts   |  5 ++--
 src/utils/agent-sdk-cursor.ts   |  7 ++++--
 src/utils/agent-sdk.ts          | 42 +++++++++++++++++++++------------
 9 files changed, 47 insertions(+), 25 deletions(-)

diff --git a/src/agents/kb-auditor.ts b/src/agents/kb-auditor.ts
index 6b91abf..3569ebd 100644
--- a/src/agents/kb-auditor.ts
+++ b/src/agents/kb-auditor.ts
@@ -16,6 +16,7 @@
 import { DEFAULT_AUDITOR_MODEL } from "../types.js";
 import { extractCostFromResult, type CostInfo } from "../utils/cost-extractor.js";
 import { buildAgentQueryOptions } from "../utils/agent-options.js";
+import { createAgentSdk } from "../utils/agent-sdk.js";
 
 export interface KbAuditResult {
   decisionsReviewed: number;
@@ -143,7 +144,7 @@ export async function runKbAudit(opts: {
 }): Promise<KbAuditResult> {
   const startTime = Date.now();
   const model = opts.model ?? DEFAULT_AUDITOR_MODEL;
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("auditor", { cwd: opts.targetPath });
 
   const prompt = opts.allRepos ? KB_AUDIT_PROMPT_ALL_REPOS : KB_AUDIT_PROMPT_SINGLE;
 
diff --git a/src/agents/memory-extractor.ts b/src/agents/memory-extractor.ts
index 787ea7a..987dc5a 100644
--- a/src/agents/memory-extractor.ts
+++ b/src/agents/memory-extractor.ts
@@ -13,6 +13,7 @@ import type { Memory } from "../types.js";
 import { extractCostFromResult, zeroCost, type CostInfo } from "../utils/cost-extractor.js";
 import { toMemorySlug } from "../storage/memory.js";
 import { buildAgentEnv, claudePathForSdk } from "../utils/agent-options.js";
+import { createAgentSdk } from "../utils/agent-sdk.js";
 
 export interface MemoryExtractionResult {
   memories: Memory[];
@@ -65,7 +66,7 @@ export async function runMemoryExtraction(opts: {
   projectPath: string;
   model?: string;
 }): Promise<MemoryExtractionResult> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("auditor", { cwd: opts.projectPath });
   const startTime = Date.now();
   const model = opts.model ?? "claude-haiku-4-5";
 
diff --git a/src/agents/scanners/decision.ts b/src/agents/scanners/decision.ts
index 8e7def5..52b3a56 100644
--- a/src/agents/scanners/decision.ts
+++ b/src/agents/scanners/decision.ts
@@ -10,6 +10,7 @@
 import type { Decision } from "../../types.js";
 import { extractCostFromResult, zeroCost, type CostInfo } from "../../utils/cost-extractor.js";
 import { buildAgentQueryOptions } from "../../utils/agent-options.js";
+import { createAgentSdk } from "../../utils/agent-sdk.js";
 import { toSlug } from "../../storage/decisions.js";
 
 export interface DecisionScanResult {
@@ -103,7 +104,7 @@ export async function runDecisionScan(opts: {
   /** Existing decisions (e.g. from presets) — scanner skips same-topic. */
   existingDecisions?: Decision[];
 }): Promise<DecisionScanResult> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("scanner", { cwd: opts.projectPath });
   const startTime = Date.now();
   const model = opts.model ?? "claude-sonnet-4-6";
 
diff --git a/src/agents/scanners/deploy.ts b/src/agents/scanners/deploy.ts
index 290477c..c73dbff 100644
--- a/src/agents/scanners/deploy.ts
+++ b/src/agents/scanners/deploy.ts
@@ -10,6 +10,7 @@
 import type { ChecklistItem } from "../../types.js";
 import { extractCostFromResult, zeroCost, type CostInfo } from "../../utils/cost-extractor.js";
 import { buildAgentQueryOptions } from "../../utils/agent-options.js";
+import { createAgentSdk } from "../../utils/agent-sdk.js";
 
 export interface DeployScanResult {
   stagingItems: ChecklistItem[];
@@ -85,7 +86,7 @@ export async function runDeployScan(opts: {
   projectPath: string;
   model?: string;
 }): Promise<DeployScanResult> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("scanner", { cwd: opts.projectPath });
   const startTime = Date.now();
   const model = opts.model ?? "claude-haiku-4-5";
 
diff --git a/src/agents/scanners/oracle.ts b/src/agents/scanners/oracle.ts
index 4e46e87..e352a28 100644
--- a/src/agents/scanners/oracle.ts
+++ b/src/agents/scanners/oracle.ts
@@ -10,6 +10,7 @@
 import type { OracleFiles } from "../../types.js";
 import { extractCostFromResult, zeroCost, type CostInfo } from "../../utils/cost-extractor.js";
 import { buildAgentQueryOptions } from "../../utils/agent-options.js";
+import { createAgentSdk } from "../../utils/agent-sdk.js";
 
 export interface OracleScanResult {
   files: OracleFiles;
@@ -120,7 +121,7 @@ export async function runOracleScan(opts: {
   workspaceMode?: boolean;
   customPaths?: string[];
 }): Promise<OracleScanResult> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("scanner", { cwd: opts.projectPath });
   const startTime = Date.now();
   const model = opts.model ?? "claude-sonnet-4-6";
 
diff --git a/src/agents/scanners/safety.ts b/src/agents/scanners/safety.ts
index 4635cb8..42fe1c3 100644
--- a/src/agents/scanners/safety.ts
+++ b/src/agents/scanners/safety.ts
@@ -10,6 +10,7 @@
 import type { SafetyRules } from "../../types.js";
 import { extractCostFromResult, zeroCost, type CostInfo } from "../../utils/cost-extractor.js";
 import { buildAgentQueryOptions } from "../../utils/agent-options.js";
+import { createAgentSdk } from "../../utils/agent-sdk.js";
 
 export interface SafetyScanResult {
   rules: Partial<SafetyRules>;
@@ -93,7 +94,7 @@ export async function runSafetyScan(opts: {
   projectPath: string;
   model?: string;
 }): Promise<SafetyScanResult> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("scanner", { cwd: opts.projectPath });
   const startTime = Date.now();
   const model = opts.model ?? "claude-haiku-4-5";
 
diff --git a/src/agents/session-auditor.ts b/src/agents/session-auditor.ts
index 152f1c2..0ca55cf 100644
--- a/src/agents/session-auditor.ts
+++ b/src/agents/session-auditor.ts
@@ -22,6 +22,7 @@ import type { Memory, Decision, SessionHandoff, WorkspaceInfo } from "../types.j
 import { DEFAULT_AUDITOR_MODEL } from "../types.js";
 import { extractCostFromResult, zeroCost, type CostInfo } from "../utils/cost-extractor.js";
 import { buildAgentEnv, claudePathForSdk } from "../utils/agent-options.js";
+import { createAgentSdk } from "../utils/agent-sdk.js";
 import { toMemorySlug } from "../storage/memory.js";
 import { toSlug, listDecisions } from "../storage/decisions.js";
 import { listMemories } from "../storage/memory.js";
@@ -623,7 +624,7 @@ async function runSingleAuditCall(opts: {
   cost?: CostInfo;
   promptChars: number;
 }> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("auditor", { cwd: opts.sessionOrigin });
 
   const claudePath = claudePathForSdk();
   const queryOpts = {
@@ -860,7 +861,7 @@ export async function formatAuditResult(
   model: string,
   sessionOrigin: string,
 ): Promise<{ json: any; cost?: CostInfo }> {
-  const sdk = await import("@anthropic-ai/claude-agent-sdk");
+  const sdk = await createAgentSdk("auditor", { cwd: sessionOrigin });
 
   const formatPrompt = `You are a formatting assistant. Convert the following free-text audit analysis into a JSON object.
 
diff --git a/src/utils/agent-sdk-cursor.ts b/src/utils/agent-sdk-cursor.ts
index 53d5407..ec74885 100644
--- a/src/utils/agent-sdk-cursor.ts
+++ b/src/utils/agent-sdk-cursor.ts
@@ -50,7 +50,9 @@ interface CursorSdkModule {
 
 function resolveSystemPrompt(q: AgentQuery): string {
   const sp = q.options.systemPrompt;
+  if (sp === undefined) return "";
   if (typeof sp === "string") return sp;
+  if (Array.isArray(sp)) return sp.join("\n\n");
   // The Claude-Code preset is meaningless for Cursor — only the `append`
   // text contains the role-specific instructions worth forwarding.
   return sp.append ?? "";
@@ -114,10 +116,11 @@ export async function createCursorAgentSdk(
   return {
     ide: "cursor",
     async *query(q: AgentQuery): AsyncIterable<AgentMessage> {
-      const cwd = factoryOpts?.cwd ?? q.options.cwd;
+      const cwd = factoryOpts?.cwd ?? q.options.cwd ?? process.cwd();
+      const modelId = q.options.model ?? "composer-2";
       const agent = await cursorMod.Agent.create({
         apiKey,
-        model: { id: q.options.model },
+        model: { id: modelId },
         local: { cwd, settingSources: [], mcpServers: [] },
         agentId: `axme-${_role}`,
       });
diff --git a/src/utils/agent-sdk.ts b/src/utils/agent-sdk.ts
index bf9de3e..b6eeddf 100644
--- a/src/utils/agent-sdk.ts
+++ b/src/utils/agent-sdk.ts
@@ -52,23 +52,35 @@ export interface AgentMessage {
   [key: string]: unknown;
 }
 
+/**
+ * AgentQuery.options is intentionally permissive — every field is optional,
+ * so existing call sites built via `buildAgentQueryOptions(...)` (which
+ * returns the Claude Agent SDK `Options` type, where most fields are
+ * declared optional) type-check without rewrapping. The Claude wrapper
+ * passes the object straight to `sdk.query()`. The Cursor wrapper reads
+ * only the fields it needs (`cwd`, `model`, `systemPrompt`) and ignores
+ * the rest.
+ */
+export interface AgentQueryOptions {
+  cwd?: string;
+  model?: string;
+  systemPrompt?:
+    | string
+    | string[]
+    | { type: "preset"; preset: "claude_code"; append?: string; excludeDynamicSections?: boolean };
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  maxTurns?: number;
+  env?: NodeJS.ProcessEnv;
+  settingSources?: string[];
+  permissionMode?: string;
+  pathToClaudeCodeExecutable?: string;
+  [key: string]: unknown;
+}
+
 export interface AgentQuery {
   prompt: string;
-  options: {
-    cwd: string;
-    model: string;
-    systemPrompt:
-      | string
-      | { type: "preset"; preset: "claude_code"; append?: string };
-    allowedTools: string[];
-    disallowedTools: string[];
-    maxTurns?: number;
-    env: NodeJS.ProcessEnv;
-    settingSources?: string[];
-    permissionMode?: "bypassPermissions";
-    pathToClaudeCodeExecutable?: string;
-    [key: string]: unknown;
-  };
+  options: AgentQueryOptions;
 }
 
 export interface AgentSdk {

From faafcc1ddc35a597ab8fda700781938abdc5a267 Mon Sep 17 00:00:00 2001
From: geobelsky <geobelsky@gmail.com>
Date: Sun, 10 May 2026 11:52:27 +0000
Subject: [PATCH 5/6] feat(parser): add Cursor JSONL transcript branch
 (top-level role)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cursor's stored agent transcripts at
~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl
use a different shape from Claude Code's:
  Cursor:  {"role":"user","message":{"content":[{"type":"text","text":"..."}]}}
  Claude:  {"message":{"role":"user","content":[{"type":"text","text":"..."}]}}

Cursor puts `role` at the TOP level; Claude nests it inside `message`.
Cursor's stored transcripts contain ONLY type=text blocks — no
tool_use, thinking, or tool_result (verified empirically against
~/.cursor/projects/home-georgeb-axme-workspace-AxmeAI-code-workspace
on 2026-05-10).

Changes
-------
src/transcript-parser.ts:
- Add optional `ide?: IdeKind` parameter to parseTranscriptFromOffset,
  parseTranscript, parseAndRenderTranscript. Default "claude-code"
  preserves existing behaviour for every current caller.
- Role extraction now reads `event.role` (Cursor) when ide==="cursor",
  falls back to `msg.role` (Claude) otherwise. The fallback chain
  `event.role ?? msg.role` is defensive — a Cursor transcript with
  ide=undefined (older ClaudeSessionRef without ide field) still
  parses correctly.
- parseAndRenderTranscripts threads `ref.ide` into the per-ref call
  so multi-agent Cursor sessions get the right shape per ref.
- Imported IdeKind from ../types.js.

test/transcript-parser.test.ts:
- New `Cursor JSONL transcript parsing` describe block with 4 tests:
  * Cursor format with ide="cursor" — top-level role honored
  * Cursor format without ide param — defensive fallback works
  * Text-only Cursor transcript — zero tool_use/thinking turns
  * Claude format with ide="claude-code" — regression check

This commit completes PR-3 wiring on the parser side. The session
auditor (after commit 1/3 of this batch routes through AgentSdk)
already reads ClaudeSessionRef.ide from session metadata; it now
hands that value to the parser at audit time.

Tests: 599 / 599 pass (was 595, +4 new in this commit).
tsc --noEmit clean.

#!axme pr=129 repo=AxmeAI/axme-code
---
 src/transcript-parser.ts       | 60 ++++++++++++++++++++----------
 test/transcript-parser.test.ts | 68 ++++++++++++++++++++++++++++++++++
 2 files changed, 109 insertions(+), 19 deletions(-)

diff --git a/src/transcript-parser.ts b/src/transcript-parser.ts
index 7431b05..ec0beb6 100644
--- a/src/transcript-parser.ts
+++ b/src/transcript-parser.ts
@@ -1,25 +1,38 @@
 /**
- * Claude Code transcript parser and filter for the session auditor.
+ * IDE-agnostic transcript parser and filter for the session auditor.
  *
- * Claude Code stores every session as a jsonl file at
- *   ~/.claude/projects/<encoded-path>/<session-id>.jsonl
+ * Two transcript shapes are supported, picked at parse time via the
+ * optional `ide` parameter:
  *
- * The raw file is large (often 1-2 MB) and ~90% of it is tool_result blocks:
- * bash outputs, file reads, grep matches, etc. The session auditor does not
- * need those — they describe WHAT the code did, which the auditor can see
- * from the code itself and from the diff. What the auditor needs is the
- * CONVERSATION: user corrections, assistant reasoning, assistant findings.
+ * - **Claude Code** (`~/.claude/projects/<encoded-path>/<session-id>.jsonl`):
+ *   each line is `{ message: { role, content: [...] } }`. Role is nested
+ *   inside the `message` envelope. Content blocks include `text`,
+ *   `thinking`, `tool_use`, `tool_result`, `image`.
  *
- * This parser drops everything except:
+ * - **Cursor** (`~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl`):
+ *   each line is `{ role, message: { content: [...] } }`. Role is at the
+ *   TOP level. Content blocks observed in the wild are text-only — Cursor's
+ *   stored transcript does not include tool_use / thinking / tool_result.
+ *   The parser still tolerates them defensively in case future Cursor
+ *   versions add richer events.
+ *
+ * The raw Claude file is large (often 1-2 MB) and ~90% of it is tool_result
+ * blocks: bash outputs, file reads, grep matches, etc. The session auditor
+ * does not need those — they describe WHAT the code did, which the auditor
+ * can see from the code itself and from the diff. What the auditor needs is
+ * the CONVERSATION: user corrections, assistant reasoning, assistant
+ * findings. This parser drops everything except:
  *   - user text messages (real ones, not IDE notifications)
  *   - assistant text messages >= 80 chars (drops pure transitions)
  *   - assistant thinking blocks
  *   - assistant tool_use blocks (compact form: [ToolName: short params])
  *
- * Typical reduction: 1.4 MB raw → 65 KB filtered (~4%).
+ * Typical reduction (Claude): 1.4 MB raw → 65 KB filtered (~4%). Cursor
+ * transcripts are usually smaller because they have no tool_result.
  */
 
 import { readFileSync, existsSync } from "node:fs";
+import type { IdeKind } from "./types.js";
 
 export interface ConversationTurn {
   role: "user" | "assistant";
@@ -114,7 +127,11 @@ export interface ParsedTranscriptSlice {
  * cannot be read, or the offset is beyond file size (treated as "file was
  * rotated / shortened", safe no-op).
  */
-export function parseTranscriptFromOffset(path: string, startOffset: number = 0): ParsedTranscriptSlice {
+export function parseTranscriptFromOffset(
+  path: string,
+  startOffset: number = 0,
+  ide: IdeKind = "claude-code",
+): ParsedTranscriptSlice {
   if (!existsSync(path)) {
     return { turns: [], endOffset: startOffset, bytesRead: 0, fileSize: 0, bashCommands: [] };
   }
@@ -153,7 +170,12 @@ export function parseTranscriptFromOffset(path: string, startOffset: number = 0)
 
     const msg = event.message;
     if (!msg || !Array.isArray(msg.content)) continue;
-    const role = msg.role;
+    // Cursor's JSONL puts `role` at the top level; Claude Code nests it
+    // inside `message`. Detect by ide param (callers always know which IDE
+    // produced the file) and pick the right extraction path. We accept
+    // EITHER shape regardless of `ide` as a defensive fallback — older
+    // sessions may not have the `ide` field on ClaudeSessionRef.
+    const role = (ide === "cursor" ? event.role : msg.role) ?? msg.role ?? event.role;
     if (role !== "user" && role !== "assistant") continue;
 
     for (const block of msg.content) {
@@ -224,8 +246,8 @@ export function parseTranscriptFromOffset(path: string, startOffset: number = 0)
  * and return only the turns. Used by legacy callers that do not care about
  * resume-audit offsets (e.g. scope-dryrun, single-transcript audit stats).
  */
-export function parseTranscript(path: string): ConversationTurn[] {
-  return parseTranscriptFromOffset(path, 0).turns;
+export function parseTranscript(path: string, ide: IdeKind = "claude-code"): ConversationTurn[] {
+  return parseTranscriptFromOffset(path, 0, ide).turns;
 }
 
 /**
@@ -383,8 +405,8 @@ export function splitTurnsIntoChunks(
  * Convenience wrapper used by the session auditor. Parses from offset 0
  * (whole file) — used by dry-run and single-audit fallback paths.
  */
-export function parseAndRenderTranscript(path: string): ParsedTranscript {
-  const slice = parseTranscriptFromOffset(path, 0);
+export function parseAndRenderTranscript(path: string, ide: IdeKind = "claude-code"): ParsedTranscript {
+  const slice = parseTranscriptFromOffset(path, 0, ide);
   const rendered = renderConversation(slice.turns);
 
   return {
@@ -411,7 +433,7 @@ export function parseAndRenderTranscript(path: string): ParsedTranscript {
  * in startOffsets are parsed from offset 0.
  */
 export function parseAndRenderTranscripts(
-  refs: Array<{ id: string; transcriptPath: string; role?: string }>,
+  refs: Array<{ id: string; transcriptPath: string; role?: string; ide?: IdeKind }>,
   startOffsets?: Record<string, number>,
 ): {
   rendered: string;
@@ -435,7 +457,7 @@ export function parseAndRenderTranscripts(
   if (refs.length === 1) {
     const ref = refs[0];
     const start = startOffsets?.[ref.id] ?? 0;
-    const slice = parseTranscriptFromOffset(ref.transcriptPath, start);
+    const slice = parseTranscriptFromOffset(ref.transcriptPath, start, ref.ide ?? "claude-code");
     const rendered = renderConversation(slice.turns);
     endOffsets[ref.id] = slice.endOffset;
     bytesRead[ref.id] = slice.bytesRead;
@@ -457,7 +479,7 @@ export function parseAndRenderTranscripts(
   const allBashCommands: string[] = [];
   for (const ref of refs) {
     const start = startOffsets?.[ref.id] ?? 0;
-    const slice = parseTranscriptFromOffset(ref.transcriptPath, start);
+    const slice = parseTranscriptFromOffset(ref.transcriptPath, start, ref.ide ?? "claude-code");
     endOffsets[ref.id] = slice.endOffset;
     bytesRead[ref.id] = slice.bytesRead;
     if (slice.turns.length === 0) {
diff --git a/test/transcript-parser.test.ts b/test/transcript-parser.test.ts
index 2a3d377..e42f842 100644
--- a/test/transcript-parser.test.ts
+++ b/test/transcript-parser.test.ts
@@ -609,3 +609,71 @@ describe("mixed content blocks", () => {
     assert.equal(result.turns[2].kind, "tool_use");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Cursor JSONL transcript shape (top-level role)
+// ---------------------------------------------------------------------------
+
+describe("Cursor JSONL transcript parsing", () => {
+  function cursorUser(text: string): object {
+    return { role: "user", message: { content: [{ type: "text", text }] } };
+  }
+  function cursorAssistant(text: string): object {
+    return { role: "assistant", message: { content: [{ type: "text", text }] } };
+  }
+
+  it("parses Cursor format with role at top level (ide='cursor')", () => {
+    const path = join(ROOT, "cursor.jsonl");
+    writeFileSync(path, jsonl(
+      cursorUser("Hello, please refactor the auth module"),
+      cursorAssistant("A".repeat(120) + " — done."),
+    ));
+    const result = parseTranscriptFromOffset(path, 0, "cursor");
+    assert.equal(result.turns.length, 2);
+    assert.equal(result.turns[0].role, "user");
+    assert.equal(result.turns[0].kind, "text");
+    assert.match(result.turns[0].content, /refactor the auth/);
+    assert.equal(result.turns[1].role, "assistant");
+    assert.equal(result.turns[1].kind, "text");
+  });
+
+  it("Cursor format works even without ide param (defensive top-level role fallback)", () => {
+    // ClaudeSessionRef.ide is optional for backward compat. If a Cursor
+    // transcript is parsed with the default ide="claude-code", the parser's
+    // defensive fallback (`event.role ?? msg.role`) should still pick up
+    // the top-level role.
+    const path = join(ROOT, "cursor-no-ide.jsonl");
+    writeFileSync(path, jsonl(cursorAssistant("B".repeat(120))));
+    const result = parseTranscriptFromOffset(path);  // default ide
+    assert.equal(result.turns.length, 1);
+    assert.equal(result.turns[0].role, "assistant");
+  });
+
+  it("text-only Cursor transcript yields zero tool_use turns", () => {
+    // Real Cursor transcripts contain only text blocks (verified empirically
+    // 2026-05-10). Confirm parser doesn't synthesize fake tool_use turns.
+    const path = join(ROOT, "cursor-text-only.jsonl");
+    writeFileSync(path, jsonl(
+      cursorUser("Q1"),
+      cursorAssistant("A".repeat(100)),
+      cursorUser("Q2"),
+      cursorAssistant("B".repeat(100)),
+    ));
+    const result = parseTranscriptFromOffset(path, 0, "cursor");
+    assert.equal(result.turns.filter(t => t.kind === "tool_use").length, 0);
+    assert.equal(result.turns.filter(t => t.kind === "thinking").length, 0);
+    assert.equal(result.turns.filter(t => t.kind === "text").length, 4);
+  });
+
+  it("Claude Code format still parses correctly with ide='claude-code' (regression)", () => {
+    const path = join(ROOT, "claude.jsonl");
+    writeFileSync(path, jsonl(
+      { message: { role: "user", content: [{ type: "text", text: "hello" }] } },
+      { message: { role: "assistant", content: [{ type: "text", text: "B".repeat(100) }] } },
+    ));
+    const result = parseTranscriptFromOffset(path, 0, "claude-code");
+    assert.equal(result.turns.length, 2);
+    assert.equal(result.turns[0].role, "user");
+    assert.equal(result.turns[1].role, "assistant");
+  });
+});

From d267b82237afb73ffa7d35dd77d8154aa82d1698 Mon Sep 17 00:00:00 2001
From: geobelsky <geobelsky@gmail.com>
Date: Sun, 10 May 2026 11:59:50 +0000
Subject: [PATCH 6/6] feat(hooks): fall back to stdin workspace_roots when
 --workspace flag absent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User-level Cursor hooks installed at ~/.cursor/hooks.json by the VS
Code extension cannot hard-code a workspace path because they apply
machine-wide. Cursor's hook stdin payload always includes
workspace_roots[] (a Cursor common-base field, present in every event
type), so hook handlers now fall back to workspace_roots[0] when the
--workspace flag is absent.

Precedence order, all three handlers:
  1. explicit --workspace flag (existing Claude Code path — unchanged)
  2. stdin workspace_roots[0] (new — Cursor user-level hook path)
  3. process.cwd() (last-resort fallback — unchanged)

Files
-----
src/hooks/pre-tool-use.ts: read stdin first, resolve workspace path
  AFTER, dispatch to handlePreToolUse with the resolved path.
src/hooks/post-tool-use.ts: same.
src/hooks/session-end.ts: same; preserves the existing tolerance for
  empty/invalid stdin (sessionEnd is sometimes fired with no payload).

build.mjs: add @cursor/sdk to the plugin bundle's external list. The
plugin bundle uses packages: "bundle" and was choking on @cursor/sdk's
internal @anysphere/* sub-package imports. Marking it external keeps
the plugin distribution buildable; the cursor_sdk path is meaningless
in plugin context anyway (Claude Code marketplace users use the Claude
Agent SDK), and the AgentSdk factory's fallback already handles the
missing-module case gracefully.

test/hooks-workspace-fallback.test.ts: new — spawns real `tsx` hook
subprocess with no --workspace flag, feeds Cursor-shaped stdin via
pipe, asserts each of the three handlers exits cleanly with the
right resolved path. 5 tests.

Test suite: 604 / 604 pass (was 599; +5 new). tsc clean. Build clean.

This commit completes PR-3 wiring (the third of three additional
foundation commits requested by the rewritten Phase 2 plan). PR #129
foundation is now genuinely complete: AgentSdk factory, Cursor
transcript parser, hook workspace fallback. The Phase 2 extension
branch can rely on these without further core changes.

#!axme pr=129 repo=AxmeAI/axme-code
---
 build.mjs                             |  10 ++-
 src/hooks/post-tool-use.ts            |  16 +++-
 src/hooks/pre-tool-use.ts             |  20 ++++-
 src/hooks/session-end.ts              |  16 +++-
 test/hooks-workspace-fallback.test.ts | 119 ++++++++++++++++++++++++++
 5 files changed, 171 insertions(+), 10 deletions(-)
 create mode 100644 test/hooks-workspace-fallback.test.ts

diff --git a/build.mjs b/build.mjs
index 40e56e8..ccf1f74 100644
--- a/build.mjs
+++ b/build.mjs
@@ -63,7 +63,15 @@ await build({
   target: "node20",
   format: "esm",
   packages: "bundle",
-  external: ["@anthropic-ai/claude-agent-sdk"],
+  // @cursor/sdk is an optional dep with native binaries + workspace-internal
+  // sub-package imports (@anysphere/*) that esbuild cannot resolve from the
+  // plugin bundle — keep it external alongside @anthropic-ai/claude-agent-sdk.
+  // Plugin runtime: cursor_sdk path is unsupported in plugin distribution
+  // (Claude Code marketplace users use claude_agent_sdk anyway), so leaving
+  // the import as a dynamic external is safe — the await import() throws
+  // MODULE_NOT_FOUND inside the plugin and the AgentSdk factory falls back
+  // to the Claude wrapper, exactly as on win-arm64.
+  external: ["@anthropic-ai/claude-agent-sdk", "@cursor/sdk"],
   outfile: "dist/plugin/cli.mjs",
   sourcemap: true,
   banner: { js: "" },
diff --git a/src/hooks/post-tool-use.ts b/src/hooks/post-tool-use.ts
index 04c418d..aa67df2 100644
--- a/src/hooks/post-tool-use.ts
+++ b/src/hooks/post-tool-use.ts
@@ -61,9 +61,6 @@ function handlePostToolUse(workspacePath: string, event: NormalizedHookEvent): v
  * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
 export async function runPostToolUseHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
-  if (!workspacePath) workspacePath = process.cwd();
-  if (!workspacePath) return;
-
   // Skip entirely when we are running inside a subclaude audit worker
   // (see session-auditor env: { ...process.env, AXME_SKIP_HOOKS: "1" }).
   // Without this early exit, every tool call the auditor makes would spawn
@@ -74,6 +71,19 @@ export async function runPostToolUseHook(workspacePath?: string, ide: IdeKind =
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
     const raw = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+
+    // Resolve workspace path: explicit --workspace flag > stdin
+    // workspace_roots[0] > process.cwd(). See pre-tool-use.ts for rationale.
+    if (!workspacePath) {
+      const roots = (raw as { workspace_roots?: unknown })?.workspace_roots;
+      if (Array.isArray(roots) && typeof roots[0] === "string") {
+        workspacePath = roots[0];
+      } else {
+        workspacePath = process.cwd();
+      }
+    }
+    if (!workspacePath) return;
+
     const event = inputAdapterFor(ide).parse(raw, "postToolUse");
     handlePostToolUse(workspacePath, event);
   } catch (err) {
diff --git a/src/hooks/pre-tool-use.ts b/src/hooks/pre-tool-use.ts
index af4ea7c..90d942c 100644
--- a/src/hooks/pre-tool-use.ts
+++ b/src/hooks/pre-tool-use.ts
@@ -205,9 +205,6 @@ function handlePreToolUse(
  * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
 export async function runPreToolUseHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
-  if (!workspacePath) workspacePath = process.cwd();
-  if (!workspacePath) return;
-
   // Subclaude audit workers run inside session-auditor with
   // AXME_SKIP_HOOKS=1 in their environment. Their tool calls trigger any
   // PreToolUse hooks that may still be registered (via .claude/settings.json
@@ -221,6 +218,23 @@ export async function runPreToolUseHook(workspacePath?: string, ide: IdeKind = "
     const chunks: Buffer[] = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
     const raw = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+
+    // Resolve workspace path. Precedence: explicit --workspace flag > stdin
+    // workspace_roots[0] (Cursor common-base field, present in every event)
+    // > process.cwd() (last-resort fallback). User-level hooks installed by
+    // the VS Code extension at ~/.cursor/hooks.json cannot hard-code a
+    // workspace path because they apply machine-wide, so they omit the flag
+    // and rely on stdin instead.
+    if (!workspacePath) {
+      const roots = (raw as { workspace_roots?: unknown })?.workspace_roots;
+      if (Array.isArray(roots) && typeof roots[0] === "string") {
+        workspacePath = roots[0];
+      } else {
+        workspacePath = process.cwd();
+      }
+    }
+    if (!workspacePath) return;
+
     const adapters = adaptersFor(ide);
     const event = adapters.input.parse(raw, "preToolUse");
     const exitCode = handlePreToolUse(workspacePath, event, adapters.output);
diff --git a/src/hooks/session-end.ts b/src/hooks/session-end.ts
index 9edf0c5..ee89dc2 100644
--- a/src/hooks/session-end.ts
+++ b/src/hooks/session-end.ts
@@ -72,9 +72,6 @@ function handleSessionEnd(workspacePath: string, event: NormalizedHookEvent): vo
  * @param ide - from --ide CLI flag (defaults to "claude-code")
  */
 export async function runSessionEndHook(workspacePath?: string, ide: IdeKind = "claude-code"): Promise<void> {
-  if (!workspacePath) workspacePath = process.cwd();
-  if (!workspacePath) return;
-
   // Skip entirely when running inside a subclaude audit worker (see
   // session-auditor env: { ...process.env, AXME_SKIP_HOOKS: "1" }). Without
   // this, a subclaude that exits mid-audit could trigger SessionEnd against
@@ -91,6 +88,19 @@ export async function runSessionEndHook(workspacePath?: string, ide: IdeKind = "
     } catch {
       // Empty/invalid stdin is fine — we'll proceed without transcript attachment
     }
+
+    // Resolve workspace path: explicit --workspace flag > stdin
+    // workspace_roots[0] > process.cwd(). See pre-tool-use.ts for rationale.
+    if (!workspacePath) {
+      const roots = (raw as { workspace_roots?: unknown })?.workspace_roots;
+      if (Array.isArray(roots) && typeof roots[0] === "string") {
+        workspacePath = roots[0];
+      } else {
+        workspacePath = process.cwd();
+      }
+    }
+    if (!workspacePath) return;
+
     const event = inputAdapterFor(ide).parse(raw, "sessionEnd");
     handleSessionEnd(workspacePath, event);
   } catch (err) {
diff --git a/test/hooks-workspace-fallback.test.ts b/test/hooks-workspace-fallback.test.ts
new file mode 100644
index 0000000..1a60f3d
--- /dev/null
+++ b/test/hooks-workspace-fallback.test.ts
@@ -0,0 +1,119 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+/**
+ * Hook handlers must accept stdin's `workspace_roots[0]` as a fallback when
+ * the --workspace CLI flag is absent. This is required for Cursor user-level
+ * hooks installed at ~/.cursor/hooks.json by the VS Code extension — those
+ * hooks fire across all projects and cannot hard-code a path at install time.
+ *
+ * Test strategy: spawn a real `tsx` subprocess running the hook handler with
+ * NO --workspace flag, feed Cursor-shaped stdin via stdin pipe, verify the
+ * handler resolves the right workspace by checking that an .axme-code/
+ * directory at THAT path is touched (or not touched, depending on case).
+ */
+
+const ROOT = "/tmp/axme-hooks-ws-fallback-test";
+const REPO_ROOT = process.cwd();
+
+beforeEach(() => {
+  rmSync(ROOT, { recursive: true, force: true });
+  mkdirSync(ROOT, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(ROOT, { recursive: true, force: true });
+});
+
+function spawnHook(hookName: "pre-tool-use" | "post-tool-use" | "session-end", argv: string[], stdinJson: object) {
+  const args = ["tsx", "src/cli.ts", "hook", hookName, ...argv];
+  const result = spawnSync("npx", args, {
+    cwd: REPO_ROOT,
+    input: JSON.stringify(stdinJson),
+    encoding: "utf-8",
+    env: { ...process.env, AXME_TELEMETRY_DISABLED: "1" },
+    timeout: 15000,
+  });
+  return result;
+}
+
+describe("hook workspace_roots fallback", () => {
+  it("pre-tool-use uses --workspace flag when present (Claude Code path)", () => {
+    const ws = join(ROOT, "claude-ws");
+    mkdirSync(join(ws, ".axme-code"), { recursive: true });
+    const r = spawnHook(
+      "pre-tool-use",
+      ["--workspace", ws],
+      { tool_name: "Read", tool_input: { file_path: "/tmp/foo.txt" } },
+    );
+    // Should exit cleanly (allow). No deny output expected for benign read.
+    assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
+  });
+
+  it("pre-tool-use falls back to workspace_roots[0] when --workspace absent (Cursor path)", () => {
+    const ws = join(ROOT, "cursor-ws");
+    mkdirSync(join(ws, ".axme-code"), { recursive: true });
+    const r = spawnHook(
+      "pre-tool-use",
+      ["--ide", "cursor"],   // NO --workspace flag
+      {
+        cursor_version: "1.7",
+        conversation_id: "conv-test",
+        workspace_roots: [ws],
+        tool_name: "Read",
+        tool_input: { file_path: "/tmp/foo.txt" },
+        transcript_path: null,
+      },
+    );
+    assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
+  });
+
+  it("post-tool-use falls back to workspace_roots[0] when --workspace absent", () => {
+    const ws = join(ROOT, "cursor-ws-post");
+    mkdirSync(join(ws, ".axme-code"), { recursive: true });
+    const r = spawnHook(
+      "post-tool-use",
+      ["--ide", "cursor"],
+      {
+        cursor_version: "1.7",
+        conversation_id: "conv-test-post",
+        workspace_roots: [ws],
+        tool_name: "Read",
+        tool_input: { file_path: "/tmp/foo.txt" },
+      },
+    );
+    assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
+  });
+
+  it("session-end falls back to workspace_roots[0] when --workspace absent", () => {
+    const ws = join(ROOT, "cursor-ws-end");
+    mkdirSync(join(ws, ".axme-code"), { recursive: true });
+    const r = spawnHook(
+      "session-end",
+      ["--ide", "cursor"],
+      {
+        cursor_version: "1.7",
+        session_id: "sdk-session-x",
+        workspace_roots: [ws],
+        reason: "completed",
+      },
+    );
+    // session-end may exit 0 quickly (no AXME session to audit).
+    assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
+  });
+
+  it("falls back to process.cwd() when neither --workspace nor workspace_roots present", () => {
+    // Spawn from REPO_ROOT cwd; no flag, no workspace_roots in stdin.
+    // The handler will use REPO_ROOT, find .axme-code/ there (real one),
+    // and proceed. Just confirm it doesn't crash.
+    const r = spawnHook(
+      "pre-tool-use",
+      [],
+      { tool_name: "Read", tool_input: { file_path: "/tmp/foo.txt" } },
+    );
+    assert.equal(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
+  });
+});