create-snipara 1.3.37 → 1.3.39

package/README.md

@@ -208,7 +208,7 @@ Writes `.snipara/companion/doctor.json` and validates:
 For Claude-specific support, run:
 
 ```bash
-npx create-snipara doctor --client claude
+npx create-snipara doctor --client claude-code
 ```
 
 This separates "Snipara config was written" from "Claude actually loaded the MCP

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "1.3.37",
+  version: "1.3.39",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -88,6 +88,8 @@ var BASE_URL = "https://www.snipara.com";
 var API_URL = "https://api.snipara.com";
 var COMPANION_PACKAGE_NAME = "snipara-companion";
 var COMPANION_COMMAND_NAME = "snipara-companion";
+var COMPANION_NPX_COMMAND = "npx -y snipara-companion@latest";
+var MIN_COMPANION_VERSION = "1.1.37";
 var GITHUB_ANSWER_PACKS_LABEL = "GitHub PR Answer Packs";
 var MCP_PACKAGE_NAME = "snipara-mcp";
 var SANDBOX_PACKAGE_NAME = "snipara-sandbox[all]";
@@ -288,7 +290,8 @@ function parseInitOptionsFromArgv(args) {
   return parsed;
 }
 async function runInit(options) {
-  const answers = await gatherConfiguration(normalizeInitOptions(options));
+  const normalizedOptions = normalizeInitOptions(options);
+  const answers = await gatherConfiguration(normalizedOptions);
   if (answers.installMcp || answers.installRuntime || answers.installOrchestrator) {
     await installPythonPackages(answers, false);
   }
@@ -308,9 +311,9 @@ async function runInit(options) {
   }
   await updateEnvFiles(answers);
   await createCompanionConfig(answers);
-  await syncRemoteAutomationClient(answers, { enabled: !options.skipTest });
+  await syncRemoteAutomationClient(answers, { enabled: !normalizedOptions.skipTest });
   await createCompanionPack(answers);
-  const validationReport = await runValidation(answers, !options.skipTest);
+  const validationReport = await runValidation(answers, !normalizedOptions.skipTest);
   writeDoctorReport(validationReport);
   printSuccess(answers, validationReport);
   if (answers.configureGitHub && answers.githubRepo) {
@@ -937,8 +940,40 @@ function isProvisionedApiKey(value) {
 function provisionedApiKeyValidationMessage() {
   return "New Snipara API keys should start with snp-";
 }
+function normalizeSemver(value) {
+  const match = value?.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}
+function getCompanionCommandVersion() {
+  if (!commandExists(COMPANION_COMMAND_NAME)) {
+    return null;
+  }
+  try {
+    return execSync(`${COMPANION_COMMAND_NAME} --version`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1e3
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function isSupportedCompanionVersion(version) {
+  const current = normalizeSemver(version);
+  return Boolean(current && compareSemver(current, MIN_COMPANION_VERSION) >= 0);
+}
+function getCompanionRequirementMessage() {
+  const version = getCompanionCommandVersion();
+  if (!version) {
+    return `${COMPANION_PACKAGE_NAME} not found on PATH`;
+  }
+  return `${COMPANION_PACKAGE_NAME} ${version} is older than required ${MIN_COMPANION_VERSION}`;
+}
 function detectCompanionCommand() {
-  if (commandExists(COMPANION_COMMAND_NAME)) {
+  if (isSupportedCompanionVersion(getCompanionCommandVersion())) {
     return COMPANION_COMMAND_NAME;
   }
   return null;
@@ -1032,11 +1067,11 @@ function detectNodePackageManagers() {
   }
   return managers;
 }
-function getCompanionInstallCommand(packageManager, upgrade) {
+function getCompanionInstallCommand(packageManager, _upgrade) {
   if (packageManager === "pnpm") {
-    return `pnpm add -g ${upgrade ? "--latest " : ""}${COMPANION_PACKAGE_NAME}`;
+    return `pnpm add -g ${COMPANION_PACKAGE_NAME}@latest`;
   }
-  return `npm install -g ${upgrade ? COMPANION_PACKAGE_NAME + "@latest" : COMPANION_PACKAGE_NAME}`;
+  return `npm install -g ${COMPANION_PACKAGE_NAME}@latest`;
 }
 async function installNodeCompanion(upgrade) {
   console.log(chalk.bold(`
@@ -1045,7 +1080,7 @@ async function installNodeCompanion(upgrade) {
   const packageManagers = detectNodePackageManagers();
   if (packageManagers.length === 0) {
     console.log(chalk.yellow("   \u26A0\uFE0F  npm/pnpm not found. Please install manually:\n"));
-    console.log(chalk.gray(`      npm install -g ${COMPANION_PACKAGE_NAME}
+    console.log(chalk.gray(`      npm install -g ${COMPANION_PACKAGE_NAME}@latest
 `));
     return;
   }
@@ -1081,12 +1116,8 @@ async function installNodeCompanion(upgrade) {
     console.log(chalk.gray(`   - ${failure}`));
   }
   console.log(chalk.yellow("\n   Install manually with:"));
-  console.log(
-    chalk.gray(
-      `   npm install -g ${upgrade ? COMPANION_PACKAGE_NAME + "@latest" : COMPANION_PACKAGE_NAME}
-`
-    )
-  );
+  console.log(chalk.gray(`   npm install -g ${COMPANION_PACKAGE_NAME}@latest
+`));
 }
 async function createMcpConfig(answers) {
   console.log(chalk.bold("\n\u2699\uFE0F  Creating Configuration\n"));
@@ -1137,31 +1168,10 @@ async function createClaudeCodeConfig(answers) {
   if (answers.profile === "runtime-only") {
     return;
   }
-  const claudeDir = path.join(homedir(), ".claude");
-  const settingsPath = path.join(claudeDir, "settings.json");
-  console.log(chalk.bold("\n\u{1F916} Configuring Claude Code MCP\n"));
-  try {
-    fs.mkdirSync(claudeDir, { recursive: true });
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-      settings = asObjectRecord(JSON.parse(fs.readFileSync(settingsPath, "utf-8")));
-    }
-    const mcpServers = asObjectRecord(settings.mcpServers);
-    settings.mcpServers = {
-      ...mcpServers,
-      snipara: buildHostedMcpServer(answers)
-    };
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 384 });
-    try {
-      fs.chmodSync(settingsPath, 384);
-    } catch {
-    }
-    console.log(chalk.green("   \u2713 Updated ~/.claude/settings.json with Snipara MCP"));
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    console.log(chalk.yellow(`   \u26A0\uFE0F  Could not update Claude Code MCP config: ${detail}`));
-    console.log(chalk.dim("   Run create-snipara doctor --client claude after manual setup."));
-  }
+  console.log(chalk.bold("\n\u{1F916} Claude Code MCP\n"));
+  console.log(chalk.green("   \u2713 Project .mcp.json contains the Snipara Hosted MCP server"));
+  console.log(chalk.dim("   Claude Code loads project-scoped MCP servers from .mcp.json."));
+  console.log(chalk.dim(`   Verify with: claude mcp list && claude mcp test snipara`));
 }
 async function createProjectBinding(answers) {
   if (answers.profile === "runtime-only") {
@@ -1469,14 +1479,8 @@ async function createClaudeDesktopConfig(answers) {
 }
 async function installClaudeCodeHooks(answers) {
   console.log(chalk.bold("\n\u{1FA9D} Installing Claude Code Hooks\n"));
-  const claudeDir = path.join(homedir(), ".claude");
+  const claudeDir = path.join(process.cwd(), ".claude");
   const hooksDir = path.join(claudeDir, "hooks");
-  if (!fs.existsSync(claudeDir)) {
-    console.log(
-      chalk.yellow("   \u26A0\uFE0F  ~/.claude not found. Install Claude Code first, then rerun repair.\n")
-    );
-    return;
-  }
   if (!fs.existsSync(hooksDir)) {
     fs.mkdirSync(hooksDir, { recursive: true });
   }
@@ -1513,41 +1517,88 @@ async function installClaudeCodeHooks(answers) {
       settings = {};
     }
   }
-  settings.hooks = settings.hooks || {};
+  settings.hooks = asObjectRecord(settings.hooks);
   const hooksConfig = settings.hooks;
   const hookEntries = [
     {
       event: "PreToolUse",
-      script: path.join(hooksDir, "snipara-stuck-guard.sh"),
-      matcher: { tool_name: "Bash|Read|Grep|Glob|Edit|MultiEdit|Write" }
+      entry: {
+        matcher: "Bash|Read|Grep|Glob|Edit|MultiEdit|Write",
+        hooks: [
+          {
+            type: "command",
+            command: createClaudeProjectHookCommand("snipara-stuck-guard.sh"),
+            timeout: 10
+          }
+        ]
+      }
     },
     {
-      event: "PreToolUse",
-      script: path.join(hooksDir, "snipara-startup.sh"),
-      matcher: { tool_name: "TodoWrite" }
+      event: "SessionStart",
+      entry: {
+        matcher: "startup|resume|compact|clear",
+        hooks: [
+          {
+            type: "command",
+            command: createClaudeProjectHookCommand("snipara-startup.sh"),
+            timeout: 30
+          }
+        ]
+      }
     },
     {
       event: "PostToolUse",
-      script: path.join(hooksDir, "snipara-session.sh"),
-      matcher: { tool_name: "Bash|Read|Grep|Glob|Edit|MultiEdit|Write" }
+      entry: {
+        matcher: "Bash|Read|Grep|Glob|Edit|MultiEdit|Write",
+        hooks: [
+          {
+            type: "command",
+            command: createClaudeProjectHookCommand("snipara-session.sh"),
+            timeout: 10
+          }
+        ]
+      }
     },
     {
       event: "PreCompact",
-      script: path.join(hooksDir, "snipara-compact.sh")
+      entry: {
+        matcher: "manual|auto",
+        hooks: [
+          {
+            type: "command",
+            command: createClaudeProjectHookCommand("snipara-compact.sh"),
+            timeout: 30
+          }
+        ]
+      }
     }
   ];
-  for (const entry of hookEntries) {
-    const eventHooks = hooksConfig[entry.event] || [];
-    const exists = eventHooks.some(
-      (hook) => typeof hook === "object" && hook !== null && "script" in hook && hook.script === entry.script
-    );
+  for (const { event, entry } of hookEntries) {
+    const eventHooks = Array.isArray(hooksConfig[event]) ? hooksConfig[event] : [];
+    const expectedCommand = entry.hooks[0].command;
+    const exists = eventHooks.some((hook) => hookConfigEntryHasCommand(hook, expectedCommand));
     if (!exists) {
       eventHooks.push(entry);
-      hooksConfig[entry.event] = eventHooks;
+      hooksConfig[event] = eventHooks;
     }
   }
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-  console.log(chalk.green("   \u2713 Updated ~/.claude/settings.json"));
+  console.log(chalk.green("   \u2713 Updated .claude/settings.json hooks"));
+}
+function createClaudeProjectHookCommand(scriptName) {
+  return `bash -lc 'cd "\${CLAUDE_PROJECT_DIR:-$PWD}" && ./.claude/hooks/${scriptName}'`;
+}
+function hookConfigEntryHasCommand(entry, expectedCommand) {
+  if (!entry || typeof entry !== "object") {
+    return false;
+  }
+  const hooks = entry.hooks;
+  if (!Array.isArray(hooks)) {
+    return false;
+  }
+  return hooks.some(
+    (hook) => hook && typeof hook === "object" && hook.command === expectedCommand
+  );
 }
 function createStuckGuardHook(answers) {
   return `#!/usr/bin/env bash
@@ -1772,7 +1823,7 @@ function getClientGuidance(client) {
   if (client === "windsurf") {
     return [
       "Windsurf should use the hosted MCP surface plus generated Windsurf automation bundles when available.",
-      "Use snipara-companion automations install --client windsurf when you want dashboard-managed hook files in the local project."
+      "Use npx -y snipara-companion@latest automations install --client windsurf when you want dashboard-managed hook files in the local project."
     ];
   }
   if (client === "codex") {
@@ -1822,19 +1873,19 @@ function getCompanionCommands(answers) {
   const businessOnboardingCommands = answers.installCompanion ? [
     {
       title: "Preview a business folder import",
-      command: `${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`,
+      command: `${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`,
       purpose: "Classify a local or LLM-materialized business folder and review the Snipara sync manifest before upload."
     },
     {
       title: "Apply a business folder import",
-      command: `${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --apply`,
+      command: `${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --apply`,
       purpose: "Upload approved business-context documents to hosted Snipara and trigger document reindexing."
     }
   ] : [
     {
       title: "Enable business folder onboarding",
       command: "npx create-snipara repair --with-companion",
-      purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run ${COMPANION_COMMAND_NAME} onboard-folder without using the dashboard.`
+      purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run ${COMPANION_NPX_COMMAND} onboard-folder without using the dashboard.`
     }
   ];
   const githubAnswerPacksCommand = answers.githubRepo ? {
@@ -1849,7 +1900,7 @@ function getCompanionCommands(answers) {
   return [
     {
       title: "Bootstrap local companion",
-      command: `${COMPANION_COMMAND_NAME} init${clientFlag}${projectFlag}`,
+      command: `${COMPANION_NPX_COMMAND} init${clientFlag}${projectFlag}`,
       purpose: "Re-run local companion setup if this workstation needs to refresh browser login or project selection."
     },
     {
@@ -1864,32 +1915,32 @@ function getCompanionCommands(answers) {
     },
     {
       title: "Run a focused hosted query",
-      command: `${COMPANION_COMMAND_NAME} query --query "how does auth middleware work?" --max-tokens 4000`,
+      command: `${COMPANION_NPX_COMMAND} query --query "how does auth middleware work?" --max-tokens 4000`,
       purpose: "Pull ranked source context before editing, reviewing, or drafting."
     },
     {
       title: "Load linked standards only when needed",
-      command: `${COMPANION_COMMAND_NAME} shared-context --categories MANDATORY BEST_PRACTICES`,
+      command: `${COMPANION_NPX_COMMAND} shared-context --categories MANDATORY BEST_PRACTICES`,
       purpose: "Fetch project-linked team or workspace guidance without treating it as memory."
     },
     {
       title: "Generate a hosted plan",
-      command: `${COMPANION_COMMAND_NAME} plan --query "Implement webhook retry hardening" --max-tokens 3000`,
+      command: `${COMPANION_NPX_COMMAND} plan --query "Implement webhook retry hardening" --max-tokens 3000`,
       purpose: "Produce a structured execution plan against indexed project knowledge."
     },
     {
       title: "Start a managed workflow from the visible plan",
-      command: `${COMPANION_COMMAND_NAME} workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.md`,
+      command: `${COMPANION_NPX_COMMAND} workflow start --goal "Implement webhook retry hardening" --plan-file ./plan.md`,
       purpose: "Record the LLM-visible plan in .snipara/workflow/current.json so phase state survives compaction."
     },
     {
       title: "Start the current workflow phase",
-      command: `${COMPANION_COMMAND_NAME} workflow phase-start context`,
+      command: `${COMPANION_NPX_COMMAND} workflow phase-start context`,
       purpose: "Mark a phase active and print the required Snipara context gate for the agent."
     },
     {
       title: "Analyze code impact before a risky change",
-      command: `${COMPANION_COMMAND_NAME} code impact --changed-files src/api/webhooks.ts tests/webhooks.test.ts --diff-summary "webhook retry hardening"`,
+      command: `${COMPANION_NPX_COMMAND} code impact --changed-files src/api/webhooks.ts tests/webhooks.test.ts --diff-summary "webhook retry hardening"`,
       purpose: "Use paid Context code impact analysis to surface likely tests, docs, routes, config, and risks."
     },
     {
@@ -1900,48 +1951,48 @@ function getCompanionCommands(answers) {
     githubAnswerPacksCommand,
     {
       title: "Upload or refresh a doc",
-      command: `${COMPANION_COMMAND_NAME} upload --path docs/local-playbook.md --file ./docs/local-playbook.md`,
+      command: `${COMPANION_NPX_COMMAND} upload --path docs/local-playbook.md --file ./docs/local-playbook.md`,
       purpose: "Push local notes or docs into hosted Snipara context."
     },
     ...businessOnboardingCommands,
     {
       title: "Inspect a specific chunk",
-      command: `${COMPANION_COMMAND_NAME} chunk get --chunk-id <chunk_id>`,
+      command: `${COMPANION_NPX_COMMAND} chunk get --chunk-id <chunk_id>`,
       purpose: "Open an exact chunk returned by references-based search."
     },
     {
       title: "Bootstrap the session memory view",
-      command: `${COMPANION_COMMAND_NAME} session-bootstrap`,
+      command: `${COMPANION_NPX_COMMAND} session-bootstrap`,
       purpose: "Load durable decisions, learnings, and optional short-lived carryover at session start."
     },
     {
       title: "Check Stuck Guard status",
-      command: `${COMPANION_COMMAND_NAME} stuck-guard status`,
+      command: `${COMPANION_NPX_COMMAND} stuck-guard status`,
       purpose: "Inspect whether recent tool failures, empty searches, or risky workflow signals should trigger a Rescue Pack."
     },
     {
       title: "Simulate a Stuck Guard fixture",
-      command: `${COMPANION_COMMAND_NAME} stuck-guard simulate --fixture ./stuck-guard-fixture.json`,
+      command: `${COMPANION_NPX_COMMAND} stuck-guard simulate --fixture ./stuck-guard-fixture.json`,
       purpose: "Replay canonical events against the hosted Stuck Guard decision API before enabling stricter modes."
     },
     {
       title: "Ask memory about past decisions",
-      command: `${COMPANION_COMMAND_NAME} recall --query "What did we decide about auth retries?" --type decision`,
+      command: `${COMPANION_NPX_COMMAND} recall --query "What did we decide about auth retries?" --type decision`,
       purpose: "Query durable memory for past decisions, preferences, or validated learnings."
     },
     {
       title: "Commit durable task memory",
-      command: `${COMPANION_COMMAND_NAME} task-commit --summary "Hardened webhook retries and updated tests" --category engineering --outcome completed --files src/api/webhooks.ts tests/webhooks.test.ts`,
+      command: `${COMPANION_NPX_COMMAND} task-commit --summary "Hardened webhook retries and updated tests" --category engineering --outcome completed --files src/api/webhooks.ts tests/webhooks.test.ts`,
       purpose: "Persist reusable outcomes back into hosted memory after the work is done."
     },
     {
       title: "Commit a managed workflow phase",
-      command: `${COMPANION_COMMAND_NAME} workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/api/webhooks.ts tests/webhooks.test.ts`,
+      command: `${COMPANION_NPX_COMMAND} workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/api/webhooks.ts tests/webhooks.test.ts`,
       purpose: "Persist this phase through hosted memory and advance the local managed workflow state."
     },
     {
       title: "Commit the final managed workflow result",
-      command: `${COMPANION_COMMAND_NAME} final-commit --summary "Shipped webhook retry hardening and tests" --files src/api/webhooks.ts tests/webhooks.test.ts`,
+      command: `${COMPANION_NPX_COMMAND} final-commit --summary "Shipped webhook retry hardening and tests" --files src/api/webhooks.ts tests/webhooks.test.ts`,
       purpose: "Persist the final workflow outcome and close the managed workflow after verification."
     }
   ];
@@ -1978,7 +2029,7 @@ function getClientPackFilename(client) {
 }
 function getClientConfigArtifacts(client) {
   if (client === "claude-code") {
-    return ["AGENTS.md", "CLAUDE.md", "~/.claude/settings.json MCP server"];
+    return ["AGENTS.md", "CLAUDE.md", ".mcp.json MCP server", ".claude/settings.json hooks"];
   }
   if (client === "cursor") {
     return [".mcp.json", ".cursor/rules/snipara.mdc", "dashboard automation bundle when installed"];
@@ -2008,7 +2059,7 @@ function getClientConfigArtifacts(client) {
 }
 function getClientAutomationCommand(client) {
   const companionClient = getCompanionInitClientFlag(client).match(/--client\s+(\S+)/)?.[1];
-  return companionClient ? `${COMPANION_COMMAND_NAME} automations install --client ${companionClient}` : null;
+  return companionClient ? `${COMPANION_NPX_COMMAND} automations install --client ${companionClient}` : null;
 }
 function buildClientPackMarkdown(answers, commands, guidance) {
   const clientName = getClientDisplayName(answers.aiClient);
@@ -2033,7 +2084,7 @@ ${getClientConfigArtifacts(answers.aiClient).map((item) => `- \`${item}\``).join
 
 ## Recommended Setup
 
-${bootstrapCommand ? `1. Bootstrap companion: \`${bootstrapCommand.command}\`` : "1. Bootstrap companion with `snipara-companion init`."}
+${bootstrapCommand ? `1. Bootstrap companion: \`${bootstrapCommand.command}\`` : `1. Bootstrap companion with \`${COMPANION_NPX_COMMAND} init\`.`}
 2. Confirm the client can list or call the \`snipara_*\` MCP tools.
 3. Keep exact edits, tests, and dirty working-tree checks local; use Snipara for memory, source truth, and indexed code graph context.
 ${automationCommand ? `4. For generated local automations, run \`${automationCommand}\` when that client exposes usable automation files.` : "4. This client is treated as MCP-first; no local hook surface is assumed."}
@@ -2047,6 +2098,7 @@ ${guidance.map((line) => `- ${line}`).join("\n")}
 - Start substantial work with \`snipara_recall\` and \`snipara_context_query\`.
 - Use \`answer_pack\` facts, caveats, source maps, and verification checks before making claims.
 - Use \`snipara_code_symbol_card\` and \`snipara_code_impact\` for important symbols or risky multi-file changes when available.
+- Use the installed \`snipara-companion\` binary for low-latency hooks; use \`${COMPANION_NPX_COMMAND}\` for one-off terminal commands when freshness matters.
 - Use \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` for multi-phase work.
 - Persist only durable decisions, learnings, preferences, workflows, and troubleshooting outcomes. Never persist secrets.
 `;
@@ -2097,11 +2149,11 @@ Use this when Claude, ChatGPT, Codex, or another LLM client has already material
 
 ${answers.installCompanion ? `Preview first:
 
-\`${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json\`
+\`${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json\`
 
 Apply only after reviewing the manifest:
 
-\`${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --apply\`` : `This setup did not install snipara-companion. Enable it before business folder imports:
+\`${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --apply\`` : `This setup did not install snipara-companion. Enable it before business folder imports:
 
 \`npx create-snipara repair --with-companion\``}
 
@@ -2237,11 +2289,15 @@ function getClaudeClientChecks(answers, detection) {
   const checks = [];
   const claudePaths = getClaudeConfigPaths();
   const projectConfig = readJsonFile(path.join(process.cwd(), ".mcp.json"));
+  const projectSettings = readJsonFile(path.join(process.cwd(), ".claude", "settings.json"));
   const codeSettings = readJsonFile(claudePaths.codeSettingsPath);
   const desktopConfig = readJsonFile(claudePaths.desktopConfigPath);
   const projectHasSnipara = containsSniparaMcpReference(projectConfig);
+  const projectSettingsHasSnipara = containsSniparaMcpReference(projectSettings);
   const codeSettingsHasSnipara = containsSniparaMcpReference(codeSettings);
+  const hasLegacyCodeSettingsMcp = projectSettingsHasSnipara || codeSettingsHasSnipara;
   const desktopHasSnipara = containsSniparaMcpReference(desktopConfig);
+  const projectHooksConfigured = containsClaudeHooksReference(projectSettings);
   checks.push({
     name: "claude_project_config",
     status: projectHasSnipara ? "pass" : "warn",
@@ -2250,8 +2306,13 @@ function getClaudeClientChecks(answers, detection) {
   if (answers.aiClient === "claude-code") {
     checks.push({
       name: "claude_code_settings",
-      status: detection.files.claudeSettings ? codeSettingsHasSnipara ? "pass" : "warn" : "warn",
-      detail: detection.files.claudeSettings ? codeSettingsHasSnipara ? "~/.claude/settings.json contains a Snipara MCP server" : "~/.claude/settings.json exists but no Snipara MCP server was found" : "~/.claude/settings.json not found; Claude may require Settings -> MCP UI setup"
+      status: hasLegacyCodeSettingsMcp ? "warn" : "pass",
+      detail: hasLegacyCodeSettingsMcp ? "Legacy Claude settings contain an MCP server entry; Claude Code project MCP should live in .mcp.json or be managed by claude mcp add --scope project" : "Claude settings are not being used as the MCP destination; .claude/settings.json is hooks-only"
+    });
+    checks.push({
+      name: "claude_code_hooks",
+      status: !answers.installHooks || projectHooksConfigured ? "pass" : "warn",
+      detail: answers.installHooks ? projectHooksConfigured ? "Project .claude/settings.json contains Snipara hook commands" : "Project .claude/settings.json hooks missing; run create-snipara repair --with-hooks" : "Claude hooks not requested"
     });
   }
   if (answers.aiClient === "claude-desktop") {
@@ -2298,6 +2359,15 @@ function containsSniparaMcpReference(value) {
   }
   return false;
 }
+function containsClaudeHooksReference(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const hooks = value.hooks;
+  return Boolean(
+    hooks && typeof hooks === "object" && JSON.stringify(hooks).includes(COMPANION_COMMAND_NAME)
+  );
+}
 function getCreateSniparaPackageFreshnessCheck() {
   if (!commandExists("npm")) {
     return {
@@ -2388,7 +2458,7 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
   checks.push({
     name: "companion_cli",
     status: answers.installCompanion ? detection.tooling.companionCli ? "pass" : "fail" : "pass",
-    detail: answers.installCompanion && !detection.tooling.companionCli ? `${COMPANION_PACKAGE_NAME} not found on PATH` : "Companion CLI ready or not requested"
+    detail: answers.installCompanion && !detection.tooling.companionCli ? getCompanionRequirementMessage() : "Companion CLI ready or not requested"
   });
   checks.push({
     name: "sandbox_cli",
@@ -2417,8 +2487,8 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
   });
   checks.push({
     name: "hooks",
-    status: answers.installHooks && targetClient === "claude-code" ? detection.files.claudeDir ? "pass" : "warn" : "pass",
-    detail: answers.installHooks && targetClient === "claude-code" ? detection.files.claudeDir ? "~/.claude detected" : "~/.claude missing" : "Hooks not requested"
+    status: answers.installHooks && targetClient === "claude-code" ? detection.files.claudeProjectSettings ? "pass" : "warn" : "pass",
+    detail: answers.installHooks && targetClient === "claude-code" ? detection.files.claudeProjectSettings ? "Project .claude/settings.json hooks present" : "Project .claude/settings.json hooks missing" : "Hooks not requested"
   });
   if (targetClient === "claude-code" || targetClient === "claude-desktop") {
     checks.push(...getClaudeClientChecks(effectiveAnswers, detection));
@@ -2679,7 +2749,7 @@ function printSuccess(answers, report) {
   }
   if (answers.aiClient === "claude-code" && answers.profile !== "runtime-only") {
     console.log(
-      chalk.green("   \u2713 ~/.claude/settings.json") + chalk.dim(" - Claude Code Hosted MCP server")
+      chalk.green("   \u2713 Claude Code") + chalk.dim(" - .mcp.json MCP config, .claude/settings.json hooks when enabled")
     );
   }
   console.log(chalk.green("   \u2713 .snipara/companion") + chalk.dim(" - Local pack + doctor report"));
@@ -2696,7 +2766,9 @@ function printSuccess(answers, report) {
     printNextStep(
       "For Claude Code, start a new session and confirm Snipara appears in Settings -> MCP or ToolSearch."
     );
-    printNextStep("If Snipara tools are missing, run: npx create-snipara doctor --client claude");
+    printNextStep(
+      "If Snipara tools are missing, run: npx create-snipara doctor --client claude-code"
+    );
   }
   if (answers.aiClient === "claude-desktop") {
     printNextStep(
@@ -2714,15 +2786,17 @@ function printSuccess(answers, report) {
   printNextStep("Open .snipara/companion/README.md for local commands and repair flow.");
   printNextStep("Run create-snipara doctor anytime you want a fresh local validation report.");
   if (answers.installCompanion) {
-    printNextStep(`${COMPANION_COMMAND_NAME} is the companion command for local workflow helpers.`);
     printNextStep(
-      `Use ${COMPANION_COMMAND_NAME} query / plan / upload / task-commit for explicit local workflows.`
+      `${COMPANION_COMMAND_NAME} ${MIN_COMPANION_VERSION}+ is installed for low-latency local hooks.`
+    );
+    printNextStep(
+      `Use ${COMPANION_NPX_COMMAND} query / plan / upload / task-commit for explicit local workflows.`
     );
     printNextStep(
-      `For business folders, preview with: ${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`
+      `For business folders, preview with: ${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json`
     );
     printNextStep(
-      `Apply after review with: ${COMPANION_COMMAND_NAME} onboard-folder ./client-export --source-provider local_folder --apply`
+      `Apply after review with: ${COMPANION_NPX_COMMAND} onboard-folder ./client-export --source-provider local_folder --apply`
     );
   } else if (answers.profile !== "runtime-only") {
     printNextStep(
@@ -2799,6 +2873,8 @@ function detectEnvironment() {
       sniparaProject: fs.existsSync(path.join(process.cwd(), ".snipara", "project")),
       claudeDir: fs.existsSync(path.join(homedir(), ".claude")),
       claudeSettings: fs.existsSync(claudePaths.codeSettingsPath),
+      claudeProjectDir: fs.existsSync(path.join(process.cwd(), ".claude")),
+      claudeProjectSettings: fs.existsSync(path.join(process.cwd(), ".claude", "settings.json")),
       claudeDesktopConfig: fs.existsSync(claudePaths.desktopConfigPath),
       cursorDir: fs.existsSync(path.join(homedir(), ".cursor")),
       sniparaCompanionPack: fs.existsSync(path.join(process.cwd(), ".snipara", "companion")),
@@ -3024,7 +3100,8 @@ function detectRepoProjectSlug() {
   try {
     const remote = execSync("git remote get-url origin", {
       encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"]
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
     }).trim();
     const match = remote.match(/[/:]([^/]+?)(?:\.git)?$/);
     if (match) {
@@ -3041,7 +3118,8 @@ function detectGitRepository() {
   try {
     const remoteUrl = execSync("git remote get-url origin", {
       encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"]
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
     }).trim();
     const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/) || remoteUrl.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
     if (!match) {
@@ -3065,7 +3143,8 @@ function detectGitBranch() {
   try {
     const branch = execSync("git branch --show-current", {
       encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"]
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
     }).trim();
     if (branch) {
       return branch;
@@ -3075,7 +3154,8 @@ function detectGitBranch() {
   try {
     const branch = execSync("git rev-parse --abbrev-ref HEAD", {
       encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"]
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
     }).trim();
     return branch && branch !== "HEAD" ? branch : "main";
   } catch {
@@ -3085,7 +3165,8 @@ function detectGitBranch() {
 function isGitRepo() {
   try {
     execSync("git rev-parse --is-inside-work-tree", {
-      stdio: "ignore"
+      stdio: "ignore",
+      timeout: 500
     });
     return true;
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "1.3.37",
+  "version": "1.3.39",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   "main": "dist/index.js",
   "type": "module",