create-snipara 2.0.1 → 2.0.3

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.1",
+  version: "2.0.3",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -92,6 +92,7 @@ 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 CREATE_SNIPARA_NPX_COMMAND = "npx -y create-snipara@latest";
 var MIN_COMPANION_VERSION = "3.0.0";
 var GITHUB_ANSWER_PACKS_LABEL = "GitHub PR Answer Packs";
 var MCP_PACKAGE_NAME = "snipara-mcp";
@@ -1284,6 +1285,11 @@ async function createClaudeCodeConfig(answers) {
   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(
+      "   Claude Code does not load project .env files for MCP; export SNIPARA_API_KEY before launching it."
+    )
+  );
   console.log(chalk.dim(`   Verify with: claude mcp list && claude mcp test snipara`));
 }
 async function createProjectBinding(answers) {
@@ -1493,18 +1499,24 @@ Canonical project context is in \`AGENTS.md\`. This file exists for Claude Code
 Use Snipara Hosted MCP before answering project-specific questions.
 
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
-- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` before concluding a tool is unavailable.
+- Auth: use \`SNIPARA_API_KEY\` from the environment. Never commit keys.
+- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
+- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
 
 ${EXPERIENCE_GOAL_SECTION}
 
 - Start substantial work with \`snipara_recall\` and a targeted \`snipara_context_query\`.
 - Use \`snipara_context_query\` for source truth and \`snipara_get_chunk\` for exact cited sections.
 - When \`snipara_context_query\` returns \`answer_pack\`, use its facts, caveats, source map, and verification checklist before drafting claims.
+- For coding tasks, choose a workflow mode before editing: LITE for small single-phase changes, FULL managed workflow for multi-file, risky, release/deploy, architectural, compaction-prone, or future-maintainer-sensitive work.
+- Use \`snipara_plan\` for complex work when exposed; reserve \`snipara_decompose\` for FULL-mode work when the hosted server exposes it.
 - Use \`snipara_code_callers\`, \`snipara_code_imports\`, \`snipara_code_neighbors\`, or \`snipara_code_shortest_path\` for canonical structural code questions.
 - For code impact and structural code questions, use \`snipara-companion code callers/imports/neighbors/shortest-path/impact\` first when \`snipara-companion\` is installed; it auto-selects hosted MCP for clean indexed code or the local overlay for dirty/ahead worktrees and reports \`sourceSelection\`. Use hosted \`snipara_code_impact\` only when companion is unavailable or after push/reindex for canonical graph impact.
+- Run \`snipara-companion code impact\` before risky multi-file changes, PR reviews, routes, services, jobs, auth, billing, deployment, schema, migrations, or explicit "what is missing" assessments.
 - On paid Context plans, use \`snipara_code_symbol_card\` before editing important symbols.
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact edits/current working tree; use Snipara for architecture and indexed code graph context.
+- If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
 - When the plan is visible and \`snipara-companion\` is installed, keep the machine plan in JSON, use \`snipara-companion workflow start\`, \`phase-start\`, and \`phase-commit\` per phase, and after \`workflow resume\` rerun \`workflow phase-start\` before editing again.
 - If generated hooks are enabled, \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` provide runtime Rescue Pack checks when the agent loops on failures or empty searches.
 - Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps. For runtime-bound phases, capture compact rehydratable state with \`workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>\`. Then \`workflow resume\` restores workflow and memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It does not snapshot or exactly restore a live Snipara Sandbox or REPL process.
@@ -1526,8 +1538,9 @@ alwaysApply: true
 This workspace uses Snipara Hosted MCP for current project context, business/client context, and reviewed memory.
 
 - Check the configured Snipara MCP server before answering project-specific questions.
-- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` before concluding a tool is unavailable.
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
+- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
+- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
 
 ${EXPERIENCE_GOAL_SECTION}
 
@@ -1535,12 +1548,15 @@ ${EXPERIENCE_GOAL_SECTION}
 - Use \`snipara_context_query\` for docs, business context, current client/project truth, and narrative source material.
 - When \`snipara_context_query\` returns \`answer_pack\`, use its facts, caveats, source map, and verification checklist before drafting claims.
 - Use \`snipara_get_chunk\` before relying on exact cited wording from reference-based results.
+- For coding tasks, choose a workflow mode before editing: LITE for small single-phase changes, FULL managed workflow for multi-file, risky, release/deploy, architectural, compaction-prone, or future-maintainer-sensitive work.
 - Use \`snipara_code_callers\`, \`snipara_code_imports\`, \`snipara_code_neighbors\`, or \`snipara_code_shortest_path\` for canonical structural code questions.
 - For code impact and structural code questions, use \`snipara-companion code callers/imports/neighbors/shortest-path/impact\` first when \`snipara-companion\` is installed; it auto-selects hosted MCP for clean indexed code or the local overlay for dirty/ahead worktrees and reports \`sourceSelection\`. Use hosted \`snipara_code_impact\` only when companion is unavailable or after push/reindex for canonical graph impact.
+- Run \`snipara-companion code impact\` before risky multi-file changes, PR reviews, routes, services, jobs, auth, billing, deployment, schema, migrations, or explicit "what is missing" assessments.
 - On paid Context plans, use \`snipara_code_symbol_card\` before editing important symbols.
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
 - Use \`snipara_plan\` for complex work when available; use \`snipara_decompose\` when deeper decomposition is needed and the hosted server exposes it.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact code edits and current working-tree state.
+- If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
 - When \`snipara-companion\` is installed and the LLM has a visible multi-phase plan, keep the machine plan in JSON, use \`snipara-companion workflow start\`, \`phase-start\`, and \`phase-commit\` per phase, and after \`workflow resume\` rerun \`workflow phase-start\` before editing again.
 - Generated hooks can call \`snipara-companion pre-tool\`, \`post-tool\`, and \`stuck-guard status\` so Rescue Packs are runtime-triggered rather than relying only on instructions.
 - Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps. For runtime-bound phases, capture compact rehydratable state with \`workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>\`. Then \`workflow resume\` restores workflow and memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It does not snapshot or exactly restore a live Snipara Sandbox or REPL process.
@@ -2263,9 +2279,9 @@ function getCompanionCommands(answers) {
     }
   ] : [
     {
-      title: "Enable local source activation",
-      command: "npx create-snipara repair --with-companion",
-      purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run ${COMPANION_NPX_COMMAND} source init without GitHub.`
+      title: "Enable local companion workflows",
+      command: `${CREATE_SNIPARA_NPX_COMMAND} repair --with-companion`,
+      purpose: `Install ${COMPANION_PACKAGE_NAME} so this project can run local source activation, folder onboarding, and managed workflow commands without the dashboard.`
     }
   ];
   const businessOnboardingCommands = answers.installCompanion ? [
@@ -2279,20 +2295,14 @@ function getCompanionCommands(answers) {
       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_NPX_COMMAND} onboard-folder without using the dashboard.`
-    }
-  ];
+  ] : [];
   const githubAnswerPacksCommand = answers.githubRepo ? {
     title: "Connect GitHub PR Answer Packs",
-    command: `npx create-snipara --github${answers.githubPath ? ` --github-path ${answers.githubPath}` : ""}`,
+    command: `${CREATE_SNIPARA_NPX_COMMAND} --github${answers.githubPath ? ` --github-path ${answers.githubPath}` : ""}`,
     purpose: `Open the Snipara GitHub App flow for ${answers.githubRepo.fullName}. After the repo is connected, Snipara can generate scoped PR Answer Packs for GitHub-native agent workflows.`
   } : {
     title: "Connect a GitHub repo for PR Answer Packs",
-    command: "npx create-snipara --github",
+    command: `${CREATE_SNIPARA_NPX_COMMAND} --github`,
     purpose: "Run this from a GitHub-backed repository to approve the Snipara GitHub App and enable repository sync plus PR Answer Packs."
   };
   return [
@@ -2303,12 +2313,12 @@ function getCompanionCommands(answers) {
     },
     {
       title: "Run doctor for this project",
-      command: "create-snipara doctor",
+      command: `${CREATE_SNIPARA_NPX_COMMAND} doctor`,
       purpose: "Inspect local wiring, hosted reachability, and generated assets."
     },
     {
       title: "Repair local setup",
-      command: "create-snipara repair",
+      command: `${CREATE_SNIPARA_NPX_COMMAND} repair`,
       purpose: "Rebuild config files, hooks, and the companion pack."
     },
     ...localSourceCommands,
@@ -2344,7 +2354,7 @@ function getCompanionCommands(answers) {
     },
     {
       title: answers.installOrchestrator ? "Run an explicit production orchestration gate" : "Enable explicit production orchestration",
-      command: answers.installOrchestrator ? `${ORCHESTRATOR_COMMAND_NAME} check-drift --route /api/health` : "npx create-snipara repair --with-orchestrator",
+      command: answers.installOrchestrator ? `${ORCHESTRATOR_COMMAND_NAME} check-drift --route /api/health` : `${CREATE_SNIPARA_NPX_COMMAND} repair --with-orchestrator`,
       purpose: answers.installOrchestrator ? "Use snipara-orchestrator only for proof-based validation, drift checks, htasks, or multi-agent coordination." : "Install snipara-orchestrator only when production gates, drift checks, htasks, or multi-agent coordination are required."
     },
     githubAnswerPacksCommand,
@@ -2505,10 +2515,15 @@ ${guidance.map((line) => `- ${line}`).join("\n")}
 
 ## Agent Workflow
 
+- At the start of every new thread, validate hosted MCP with a tool-oriented call such as \`snipara_settings\`, \`tools/list\`, or a lightweight \`snipara_context_query\`. Do not treat empty MCP resources/templates as an outage because Snipara may be tool-only.
+- If a session exposes only a subset of expected Snipara tools, call \`snipara_help(list_all=true)\` and compare exact tool names before concluding a tool is unavailable. If only a partial surface remains after exact discovery, use \`snipara-companion recall\`, \`snipara-companion query\`, and \`snipara-companion task-commit\` as a reliable local fallback.
 - 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\` for important symbols. For risky multi-file changes, use \`snipara-companion code impact\` first when companion is available; use hosted \`snipara_code_impact\` only when companion is unavailable or after push/reindex for canonical graph impact.
+- For coding tasks, choose a workflow mode before editing: LITE for small single-phase changes, FULL managed workflow for multi-file, risky, release/deploy, architectural, compaction-prone, or future-maintainer-sensitive work.
+- Use \`snipara_plan\` for complex work when exposed; reserve \`snipara_decompose\` for FULL-mode work when the hosted server exposes it.
+- Use \`snipara_code_symbol_card\` for important symbols. For risky multi-file changes, PR reviews, routes, services, jobs, auth, billing, deployment, schema, migrations, or explicit "what is missing" assessments, use \`snipara-companion code impact\` first when companion is available; use hosted \`snipara_code_impact\` only when companion is unavailable or after push/reindex for canonical graph impact.
 - Use the installed \`snipara-companion\` binary for low-latency hooks; use \`${COMPANION_NPX_COMMAND}\` for one-off terminal commands when freshness matters.
+- If a broad query is slow, retry once with a narrow keyword query before falling back to local search.
 - Use a JSON machine plan plus \`snipara-companion workflow start\`, \`phase-start\`, \`phase-commit\`, \`workflow resume\`, and \`final-commit\` for multi-phase work. After \`workflow resume\`, rerun \`workflow phase-start <phase_id>\` before editing again.
 - When remembered knowledge is obsolete or replaced, use \`snipara-companion memory invalidate <memory-id>\` or \`snipara-companion memory supersede <old-memory-id> <new-memory-id>\` when companion is installed; otherwise use hosted \`snipara_memory_invalidate\` or \`snipara_memory_supersede\`.
 - Persist only durable decisions, learnings, preferences, workflows, and troubleshooting outcomes. Never persist secrets.
@@ -2566,7 +2581,7 @@ Apply only after reviewing the manifest:
 
 \`${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\``}
+\`${CREATE_SNIPARA_NPX_COMMAND} repair --with-companion\``}
 
 ## Local Source Activation
 
@@ -2586,7 +2601,7 @@ Inspect local drift:
 
 \`${COMPANION_NPX_COMMAND} source status --json\`` : `This setup did not install snipara-companion. Enable it before local source activation:
 
-\`npx create-snipara repair --with-companion\``}
+\`${CREATE_SNIPARA_NPX_COMMAND} repair --with-companion\``}
 
 GitHub automation remains useful after first value: it gives Snipara a canonical hosted repository
 sync and PR Answer Packs. Local source activation is the fallback, not a replacement for explicit
@@ -2599,7 +2614,7 @@ They attach scoped repository context to pull requests so coding agents can load
 architecture notes, related history, conventions, and linked documentation without rescanning the
 entire repository.
 
-${answers.githubRepo ? `This folder maps to \`${answers.githubRepo.fullName}\`. Use the GitHub App setup link below to connect the repo and enable PR Answer Packs for new or updated pull requests.` : `Run \`npx create-snipara --github\` from a GitHub-backed repository to open the approval flow for repository sync and PR Answer Packs.`}
+${answers.githubRepo ? `This folder maps to \`${answers.githubRepo.fullName}\`. Use the GitHub App setup link below to connect the repo and enable PR Answer Packs for new or updated pull requests.` : `Run \`${CREATE_SNIPARA_NPX_COMMAND} --github\` from a GitHub-backed repository to open the approval flow for repository sync and PR Answer Packs.`}
 
 ## GitHub Repository Automation
 
@@ -2609,7 +2624,7 @@ Open the Snipara GitHub App setup and connect this repository:
 
 \`${buildGitHubAutomationUrl(answers)}\`
 
-After connection, Snipara creates or reuses the repository project, enables push sync, starts the first documentation sync, and can publish PR Answer Packs through GitHub-native PR surfaces. Hosted memory stays available through the same account.` : `No GitHub repository was detected for this folder. Run \`npx create-snipara --github\` from a GitHub-backed git repository to open the repo automation path.`}
+After connection, Snipara creates or reuses the repository project, enables push sync, starts the first documentation sync, and can publish PR Answer Packs through GitHub-native PR surfaces. Hosted memory stays available through the same account.` : `No GitHub repository was detected for this folder. Run \`${CREATE_SNIPARA_NPX_COMMAND} --github\` from a GitHub-backed git repository to open the repo automation path.`}
 
 ## Suggested Commands
 
@@ -2741,6 +2756,8 @@ function getClaudeClientChecks(answers, detection) {
     detail: projectHasSnipara ? "Project .mcp.json contains a Snipara Hosted MCP server" : "Project .mcp.json does not contain a Snipara Hosted MCP server"
   });
   if (answers.aiClient === "claude-code") {
+    const envFileApiKey = readApiKeyFromEnvFiles();
+    const processHasApiKey = Boolean(process.env.SNIPARA_API_KEY?.trim());
     checks.push({
       name: "claude_code_settings",
       status: hasLegacyCodeSettingsMcp ? "warn" : "pass",
@@ -2748,10 +2765,15 @@ function getClaudeClientChecks(answers, detection) {
         ", "
       )}); 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_env_key_visible",
+      status: processHasApiKey ? "pass" : "warn",
+      detail: processHasApiKey ? "SNIPARA_API_KEY is visible in the current process environment used for MCP diagnostics" : envFileApiKey ? "SNIPARA_API_KEY exists in .env/.env.local, but Claude Code does not load project .env files for MCP servers. Export it in the shell or launch environment before starting Claude Code, then run: claude mcp list && claude mcp test snipara" : "SNIPARA_API_KEY is not visible to this process. Export it in the shell or launch environment before starting Claude Code, then run: claude mcp list && claude mcp test snipara"
+    });
     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"
+      detail: answers.installHooks ? projectHooksConfigured ? "Project .claude/settings.json contains Snipara hook commands" : `Project .claude/settings.json hooks missing; run ${CREATE_SNIPARA_NPX_COMMAND} repair --with-hooks` : "Claude hooks not requested"
     });
   }
   if (answers.aiClient === "claude-desktop") {
@@ -2945,7 +2967,7 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
   checks.push({
     name: "github_answer_packs",
     status: answers.configureGitHub ? "pass" : githubRepo ? "warn" : "pass",
-    detail: answers.configureGitHub ? `GitHub App setup link generated for ${githubRepo?.fullName || "detected repo"}; PR Answer Packs are enabled after browser approval` : githubRepo ? `GitHub repo ${githubRepo.fullName} detected; run npx create-snipara --github to connect PR Answer Packs` : "No GitHub repo detected; PR Answer Packs require the GitHub App setup path"
+    detail: answers.configureGitHub ? `GitHub App setup link generated for ${githubRepo?.fullName || "detected repo"}; PR Answer Packs are enabled after browser approval` : githubRepo ? `GitHub repo ${githubRepo.fullName} detected; run ${CREATE_SNIPARA_NPX_COMMAND} --github to connect PR Answer Packs` : "No GitHub repo detected; PR Answer Packs require the GitHub App setup path"
   });
   if (includeHostedCheck && answers.apiKeyType !== "none" && !answers.apiKey.includes("YOUR_")) {
     checks.push(...await testHostedConnection(answers));
@@ -3341,7 +3363,7 @@ function printSuccess(answers, report) {
       "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-code"
+      `If Snipara tools are missing, run: ${CREATE_SNIPARA_NPX_COMMAND} doctor --client claude-code`
     );
   }
   if (answers.aiClient === "claude-desktop") {
@@ -3349,7 +3371,7 @@ function printSuccess(answers, report) {
       "For Claude Desktop, confirm the Snipara server appears in the desktop MCP settings after restart."
     );
     printNextStep(
-      "If Snipara tools are missing, run: npx create-snipara doctor --client claude-desktop"
+      `If Snipara tools are missing, run: ${CREATE_SNIPARA_NPX_COMMAND} doctor --client claude-desktop`
     );
   }
   if (answers.aiClient === "codex") {
@@ -3378,7 +3400,9 @@ 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.");
+  printNextStep(
+    `Run ${CREATE_SNIPARA_NPX_COMMAND} doctor anytime you want a fresh local validation report.`
+  );
   if (answers.installCompanion) {
     printNextStep(
       `${COMPANION_COMMAND_NAME} ${MIN_COMPANION_VERSION}+ is installed for low-latency local hooks.`
@@ -3395,7 +3419,7 @@ function printSuccess(answers, report) {
     );
   } else if (answers.profile !== "runtime-only") {
     printNextStep(
-      "For dashboardless business folder imports, enable companion with: npx create-snipara repair --with-companion"
+      `For dashboardless business folder imports, enable companion with: ${CREATE_SNIPARA_NPX_COMMAND} repair --with-companion`
     );
   }
   if (answers.installRuntime && !answers.runSandboxInit) {
@@ -3419,7 +3443,11 @@ function printSuccess(answers, report) {
       const symbol = check.status === "fail" ? chalk.red("\u2717") : chalk.yellow("!");
       console.log(`   ${symbol} ${check.name}: ${check.detail}`);
     }
-    console.log(chalk.dim("\n   Run create-snipara repair to rebuild local wiring.\n"));
+    console.log(
+      chalk.dim(`
+   Run ${CREATE_SNIPARA_NPX_COMMAND} repair to rebuild local wiring.
+`)
+    );
   } else {
     console.log(
       chalk.dim(

package/package.json

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