create-snipara 2.0.10 → 2.0.11

package/README.md

@@ -14,6 +14,9 @@ npx create-snipara
 creates or reuses auth, writes Hosted MCP config, and prepares the local project
 so an LLM client can use Snipara context and reviewed memory. The default path is
 hosted-only so the first success is a grounded answer, not a local tooling tour.
+It is also the canonical activation engine behind editor setup docs: VS Code can
+surface activation as a native command, Cursor can pair OpenVSX UI with Hosted
+MCP, but both paths should land on the same project context.
 
 Use it when the goal is outcome-first agent work: the user asks for judgment,
 implementation, release, or verification, and the agent handles Snipara context,

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.10",
+  version: "2.0.11",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -427,6 +427,9 @@ function writeInitialHandoff(answers, manifest) {
     `Repo path: ${manifest.repoPath}`,
     `Git branch: ${manifest.git.branch ?? "not detected"}`,
     `Git remote: ${manifest.git.remote ?? "not detected"}`,
+    `Activation doctrine: ${manifest.surfaceContract.doctrine}`,
+    `Activation engine: ${manifest.surfaceContract.engine}`,
+    `Entry point: ${manifest.surfaceContract.entryPoint}`,
     "",
     "## Activation lanes",
     ...Object.entries(manifest.lanes).map(
@@ -440,6 +443,7 @@ function writeInitialHandoff(answers, manifest) {
     ...recentCommits.length > 0 ? recentCommits.map((line) => `- ${line}`) : ["- not available"],
     "",
     "## Next",
+    `- ${manifest.surfaceContract.nextSurfaceAction}`,
     "- Ask the coding agent what it should know before editing the first target area.",
     "- Review memory candidates before accepting durable memory.",
     "- Connect GitHub later for PRs, reviews, team sync, and continuous sync.",
@@ -549,6 +553,7 @@ function findDecisionArchaeologySources(cwd) {
   return [.../* @__PURE__ */ new Set([...directSources, ...archaeologySources])].slice(0, 80);
 }
 function createInitialFirstWorkBrief(answers, detection, scan) {
+  const surfaceContract = buildActivationSurfaceContract(answers.aiClient);
   const githubLine = answers.githubRepo ? `GitHub detected: ${answers.githubRepo.fullName}` : "No GitHub integration required for first value.";
   const commands = scan.scripts.length > 0 ? scan.scripts.join(", ") : "no package scripts detected";
   const docs = scan.files.candidateDocs.length > 0 ? scan.files.candidateDocs.join(", ") : "no standard docs detected";
@@ -566,6 +571,7 @@ function createInitialFirstWorkBrief(answers, detection, scan) {
           detection.inGitRepo ? "Local Git repository detected." : "Local folder detected.",
           githubLine,
           `AI client: ${getClientDisplayName(answers.aiClient)}.`,
+          `Activation entry point: ${surfaceContract.entryPoint}.`,
           `Languages: ${languages}.`
         ]
       },
@@ -594,7 +600,10 @@ function createInitialFirstWorkBrief(answers, detection, scan) {
       },
       {
         title: "Suggested next task",
-        lines: ["Ask your agent what it should know before editing the first target area."]
+        lines: [
+          surfaceContract.nextSurfaceAction,
+          "Ask your agent what it should know before editing the first target area."
+        ]
       },
       {
         title: "Top impacted modules",
@@ -612,10 +621,12 @@ function createActivationManifest(answers, detection, mode = "default", scan) {
   const hasCompanion = answers.installCompanion;
   const localScan = scan ?? detectLocalActivationScan(detection);
   const dayZeroQuery = "What is this project, what is currently in flight, and what should an agent know before making the first edit?";
+  const surfaceContract = buildActivationSurfaceContract(answers.aiClient);
   return {
     version: "create-snipara-activation-v1",
     activationId: buildActivationId(),
     mode,
+    surfaceContract,
     activationMetric: {
       name: "time_to_how_did_it_know_that",
       targetMinutes: 5,
@@ -3330,6 +3341,49 @@ function readCompanionConfigFile(filePath) {
     return {};
   }
 }
+function buildActivationSurfaceContract(client) {
+  const shared = {
+    doctrine: "one_activation_engine_multiple_entry_points",
+    engine: "create-snipara",
+    firstSuccessState: "Hosted MCP connected, local workspace context seeded, and a First Work Brief ready for the next agent session.",
+    mustNotDuplicate: [
+      "Local source scan heuristics",
+      "First Work Brief generation",
+      "memory-candidate extraction",
+      "Hosted MCP config contract"
+    ]
+  };
+  if (client === "cursor") {
+    return {
+      ...shared,
+      entryPoint: "Cursor extension or Cursor agent instructions call create-snipara",
+      clientRole: "Lightweight editor surface: expose rules, skills, and the canonical bootstrap path; do not fork activation logic.",
+      nextSurfaceAction: "In Cursor, ask the agent to run or verify `npx create-snipara@latest init --client cursor --starter`, then use the generated rules and Hosted MCP tools."
+    };
+  }
+  if (client === "vscode") {
+    return {
+      ...shared,
+      entryPoint: "VS Code extension command or create-snipara bootstrap",
+      clientRole: "Native editor UX surface: provide SecretStorage, progress, panels, status, and Copilot handoff while keeping activation semantics aligned with create-snipara.",
+      nextSurfaceAction: "In VS Code, run `Snipara: Activate Workspace` when the extension is installed, or keep using this generated pack when bootstrapping from the terminal."
+    };
+  }
+  if (client === "claude-code") {
+    return {
+      ...shared,
+      entryPoint: "Claude Code plugin or create-snipara bootstrap",
+      clientRole: "Agent-first surface: load Hosted MCP and project instructions, then use Companion only for explicit local continuity workflows.",
+      nextSurfaceAction: "Start a new Claude Code session and validate Snipara tools before enabling hooks or managed workflows."
+    };
+  }
+  return {
+    ...shared,
+    entryPoint: `${getClientDisplayName(client)} setup generated by create-snipara`,
+    clientRole: "MCP-compatible surface: consume the generated Hosted MCP reference and AGENTS.md rather than owning a separate activation model.",
+    nextSurfaceAction: "Restart or reload the client, verify Snipara tools, then ask the first grounded project question from the generated First Work Brief."
+  };
+}
 function getClientGuidance(client) {
   if (client === "claude-code") {
     return [
@@ -3339,6 +3393,7 @@ function getClientGuidance(client) {
   }
   if (client === "cursor") {
     return [
+      "Cursor is a lightweight editor entry point: use create-snipara as the canonical activation engine, then let Cursor consume the generated rules and Hosted MCP context.",
       "Cursor reads the generated .mcp.json directly, so the hosted Snipara MCP surface is available after restart.",
       "Use the companion CLI only for explicit upload, planning, chunk lookup, doctor, and task commit workflows outside the editor UI."
     ];
@@ -3374,6 +3429,7 @@ function getClientGuidance(client) {
   }
   if (client === "vscode") {
     return [
+      "VS Code can provide native activation UX, but create-snipara remains the canonical activation contract for generated files and local briefing semantics.",
       "VS Code and Copilot-style clients should use Hosted MCP plus AGENTS.md for project workflow rules.",
       "Use .snipara/templates/vscode-mcp-reference.json as the Snipara server reference when adding an MCP server."
     ];
@@ -3639,11 +3695,24 @@ function buildClientPackMarkdown(answers, commands, guidance) {
   const bootstrapCommand = commands.find(
     (command) => command.title === "Bootstrap local companion"
   );
+  const surfaceContract = buildActivationSurfaceContract(answers.aiClient);
   return `# Snipara Pack: ${clientName}
 
 This pack is the client-specific overlay for the generated Snipara project setup.
 Use \`AGENTS.md\` as the shared source of agent behavior, then apply the client-specific files below.
 
+## Activation Contract
+
+- Doctrine: one activation engine, multiple entry points
+- Canonical engine: \`${surfaceContract.engine}\`
+- Entry point: ${surfaceContract.entryPoint}
+- Client role: ${surfaceContract.clientRole}
+- First success state: ${surfaceContract.firstSuccessState}
+- Next surface action: ${surfaceContract.nextSurfaceAction}
+
+The client-specific files in this pack should not reimplement local source scanning,
+First Work Brief generation, memory-candidate extraction, or Hosted MCP config semantics.
+
 ## Hosted MCP
 
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
@@ -3692,6 +3761,8 @@ async function createCompanionPack(answers) {
   const readme = `# Snipara Companion Pack
 
 This project uses Snipara as a hosted-first project intelligence layer with source-backed context, reviewed memory, and local companion workflow helpers.
+The activation doctrine is: one shared activation engine, multiple entry points.
+\`create-snipara\` is the canonical bootstrap; editor extensions and plugins should provide UI, rules, or handoff affordances without forking the activation engine.
 
 ## Install Profile
 
@@ -3721,6 +3792,18 @@ This project uses Snipara as a hosted-first project intelligence layer with sour
 
 ${guidance.map((line) => `- ${line}`).join("\n")}
 
+## Activation Continuity Loop
+
+After the First Work Brief, use Companion when local continuity matters:
+
+1. Start or resume with \`${COMPANION_NPX_COMMAND} session-bootstrap --include-session-context --max-context-tokens 1000\`.
+2. Refresh local source context with \`${COMPANION_NPX_COMMAND} source sync --json\` after meaningful doc or code movement.
+3. Before risky edits, use \`${COMPANION_NPX_COMMAND} code impact --changed-files <files> --diff-summary "<change>"\`.
+4. End durable work with \`${COMPANION_NPX_COMMAND} task-commit --summary "<what changed>" --files <files>\`.
+
+Keep quick editor usage in the editor. Use Companion for explicit continuity, source refresh,
+workflow phase state, guards, impact checks, business-folder onboarding, and durable task memory.
+
 ## Business Folder Onboarding
 
 Use this when Claude, ChatGPT, Codex, or another LLM client has already materialized Drive, Notion, Gmail, or local business files into a folder.
@@ -4511,6 +4594,11 @@ function printActivationSummary(manifest) {
       `   Day-zero corpus: ${manifest.dayZeroCorpus.status} - ${manifest.dayZeroCorpus.detail}`
     )
   );
+  console.log(chalk.bold("\nActivation surface:\n"));
+  console.log(`   Engine: ${manifest.surfaceContract.engine}`);
+  console.log(`   Entry point: ${manifest.surfaceContract.entryPoint}`);
+  console.log(chalk.dim(`   Role: ${manifest.surfaceContract.clientRole}`));
+  console.log(chalk.dim(`   Next: ${manifest.surfaceContract.nextSurfaceAction}`));
   console.log(chalk.bold("\nAgent readiness:\n"));
   console.log(`   ${manifest.agentReadiness.summary}`);
   for (const finding of manifest.agentReadiness.stalenessFindings.slice(0, 3)) {

package/package.json

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