create-snipara 2.0.9 → 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,
@@ -26,7 +29,7 @@ Use it for:
 - free account signup with reviewed Context + Memory
 - local project wiring, `doctor`, `repair`, and `upgrade`
 - local source activation without GitHub, plus optional GitHub repository sync and PR Answer Packs approval when the current folder is a GitHub repo
-- day-zero Project Intelligence proof: a First Work Brief, a ready-to-run `snipara_context_query`, review-only decision archaeology candidates, possible doc-staleness findings, and an estimated context economy report from the user's own repository
+- day-zero Project Intelligence proof: a First Work Brief, a ready-to-run `snipara_context_query`, a small hosted README/docs seed sync for virgin projects, review-only decision archaeology candidates, possible doc-staleness findings, and an estimated context economy report from the user's own repository
 
 ## Why It Exists
 

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.9",
+  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",
@@ -104,6 +104,9 @@ var SANDBOX_COMMAND_NAME = "snipara-sandbox";
 var LEGACY_SANDBOX_COMMAND_NAME = "rlm";
 var ORCHESTRATOR_COMMAND_NAME = "snipara-orchestrator";
 var DEVICE_CLIENT_ID = "create-snipara";
+var DAY_ZERO_CORPUS_MAX_FILES = 8;
+var DAY_ZERO_CORPUS_MAX_FILE_CHARS = 12e3;
+var DAY_ZERO_CORPUS_MAX_TOTAL_CHARS = 5e4;
 var EXPERIENCE_GOAL_SECTION = `## Experience Goal
 
 The target experience is outcome-first agent work across supported clients:
@@ -288,6 +291,63 @@ function readTextFileSnippet(relativePath, maxChars = 24e3) {
     return "";
   }
 }
+function collectDayZeroCorpusDocuments(scan) {
+  const documents = [];
+  let totalChars = 0;
+  const cwd = process.cwd();
+  const rootReadmes = fs.existsSync(cwd) ? fs.readdirSync(cwd).filter((entry) => /^readme(?:\.[a-z0-9_-]+)?\.mdx?$/i.test(entry)).sort() : [];
+  const sources = [
+    ...rootReadmes,
+    ...listFilesUnder("docs", DAY_ZERO_CORPUS_MAX_FILES * 8),
+    ...scan.files.candidateDocs
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    const normalized = source.replace(/\\/g, "/");
+    if (seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    const lower = normalized.toLowerCase();
+    const isReadme = /^readme(?:\.[a-z0-9_-]+)?\.mdx?$/.test(lower);
+    const isDocsMarkdown = lower.startsWith("docs/") && /\.(?:md|mdx|markdown|txt|rst|adoc)$/.test(lower);
+    if (!isReadme && !isDocsMarkdown) {
+      continue;
+    }
+    if (documents.length >= DAY_ZERO_CORPUS_MAX_FILES) {
+      break;
+    }
+    if (totalChars >= DAY_ZERO_CORPUS_MAX_TOTAL_CHARS) {
+      break;
+    }
+    const remainingChars = DAY_ZERO_CORPUS_MAX_TOTAL_CHARS - totalChars;
+    const content = readTextFileSnippet(
+      source,
+      Math.min(DAY_ZERO_CORPUS_MAX_FILE_CHARS, remainingChars)
+    ).trim();
+    if (!content) {
+      continue;
+    }
+    documents.push({
+      path: normalized,
+      content
+    });
+    totalChars += content.length;
+  }
+  return documents;
+}
+function createDayZeroCorpusReport(status, documents, detail, options = {}) {
+  return {
+    status,
+    documents: documents.map((document) => ({
+      path: document.path,
+      chars: document.content.length
+    })),
+    detail,
+    ...options.tool ? { tool: options.tool } : {},
+    ...options.error ? { error: options.error.slice(0, 500) } : {}
+  };
+}
 function buildStalenessFindings(scan) {
   const findings = [];
   const scriptSet = new Set(scan.scripts);
@@ -367,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(
@@ -380,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.",
@@ -489,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";
@@ -506,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}.`
         ]
       },
@@ -534,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",
@@ -552,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,
@@ -566,6 +637,11 @@ function createActivationManifest(answers, detection, mode = "default", scan) {
       query: dayZeroQuery,
       expectedOutcome: "First own-repo answer pack before the user reads product docs."
     },
+    dayZeroCorpus: createDayZeroCorpusReport(
+      "queued",
+      collectDayZeroCorpusDocuments(localScan),
+      "README and docs Markdown will be submitted to hosted context before the first day-zero query when live hosted checks are enabled."
+    ),
     agentReadiness: buildAgentReadinessReport(localScan),
     contextEconomy: buildContextEconomyReport(localScan, dayZeroQuery),
     projectSlug: answers.projectSlug,
@@ -593,8 +669,8 @@ function createActivationManifest(answers, detection, mode = "default", scan) {
         hasCompanion ? "Local source activation will create a repository snapshot." : "Install companion later to activate local source context."
       ),
       contextIndex: createActivationLane(
-        hasCompanion ? "queued" : "skipped",
-        hasCompanion ? "Context indexing starts from local docs and instruction files." : "Context indexing requires companion or hosted provider sync."
+        hasHostedConfig || hasCompanion ? "queued" : "skipped",
+        hasCompanion ? "Context indexing starts from local docs and instruction files." : hasHostedConfig ? "Day-zero README/docs sync will seed hosted context when live hosted checks run." : "Context indexing requires companion or hosted provider sync."
       ),
       codeGraph: createActivationLane(
         hasCompanion ? "queued" : "skipped",
@@ -698,6 +774,115 @@ function runLocalSourceActivation(answers, manifest) {
   }
   updateActivationManifest(manifest);
 }
+async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
+  if (answers.profile === "runtime-only") {
+    manifest.dayZeroCorpus = createDayZeroCorpusReport(
+      "skipped",
+      [],
+      "Runtime-only profile skipped Hosted MCP config and hosted document sync."
+    );
+    updateActivationManifest(manifest);
+    return;
+  }
+  if (!enabled) {
+    const documents2 = collectDayZeroCorpusDocuments(manifest.localScan);
+    manifest.dayZeroCorpus = createDayZeroCorpusReport(
+      "skipped",
+      documents2,
+      "Skipped because hosted validation was disabled with --skip-test."
+    );
+    updateActivationManifest(manifest);
+    return;
+  }
+  if (answers.apiKeyType === "none" || answers.apiKey.includes("YOUR_")) {
+    manifest.dayZeroCorpus = createDayZeroCorpusReport(
+      "skipped",
+      [],
+      "Skipped because no live hosted API key was available."
+    );
+    updateActivationManifest(manifest);
+    return;
+  }
+  const documents = collectDayZeroCorpusDocuments(manifest.localScan);
+  if (documents.length === 0) {
+    manifest.dayZeroCorpus = createDayZeroCorpusReport(
+      "skipped",
+      [],
+      "No README or docs Markdown files were found to seed hosted context."
+    );
+    if (manifest.lanes.contextIndex.status === "queued") {
+      manifest.lanes.contextIndex = createActivationLane(
+        "skipped",
+        "No README or docs Markdown files were found to seed hosted context."
+      );
+    }
+    updateActivationManifest(manifest);
+    return;
+  }
+  const syncTool = "snipara_sync_documents";
+  const syncResponse = await callHostedMcp(answers, "tools/call", {
+    name: syncTool,
+    arguments: {
+      documents,
+      delete_missing: false
+    }
+  });
+  if (syncResponse.ok && !syncResponse.data.error) {
+    manifest.dayZeroCorpus = createDayZeroCorpusReport(
+      "submitted",
+      documents,
+      `Submitted ${documents.length} README/docs files to hosted context for the first day-zero answer pack.`,
+      { tool: syncTool }
+    );
+    manifest.lanes.contextIndex = createActivationLane(
+      "indexing",
+      "Day-zero README/docs corpus submitted to hosted context indexing.",
+      syncTool
+    );
+    updateActivationManifest(manifest);
+    return;
+  }
+  const uploadTool = "snipara_upload_document";
+  const uploadErrors = [];
+  for (const document of documents) {
+    const uploadResponse = await callHostedMcp(answers, "tools/call", {
+      name: uploadTool,
+      arguments: document
+    });
+    if (!uploadResponse.ok || uploadResponse.data.error) {
+      uploadErrors.push(
+        uploadResponse.ok ? describeJsonRpcError(uploadResponse.data) : describeHostedHttpFailure(uploadResponse.status, uploadResponse.bodyText)
+      );
+      break;
+    }
+  }
+  if (uploadErrors.length === 0) {
+    manifest.dayZeroCorpus = createDayZeroCorpusReport(
+      "submitted",
+      documents,
+      `Submitted ${documents.length} README/docs files to hosted context for the first day-zero answer pack.`,
+      { tool: uploadTool }
+    );
+    manifest.lanes.contextIndex = createActivationLane(
+      "indexing",
+      "Day-zero README/docs corpus submitted to hosted context indexing.",
+      uploadTool
+    );
+  } else {
+    const syncError = syncResponse.ok ? describeJsonRpcError(syncResponse.data) : describeHostedHttpFailure(syncResponse.status, syncResponse.bodyText);
+    const detail = `Could not submit the day-zero README/docs corpus. sync_documents: ${syncError}; upload_document: ${uploadErrors[0]}`;
+    manifest.dayZeroCorpus = createDayZeroCorpusReport("failed", documents, detail, {
+      tool: syncTool,
+      error: detail
+    });
+    manifest.lanes.contextIndex = failActivationLane(
+      "Hosted day-zero README/docs sync failed; the first answer may need GitHub, companion, or a later sync.",
+      syncTool,
+      new Error(detail)
+    );
+  }
+  updateActivationManifest(manifest);
+}
 function createActivationArtifacts(answers, manifest) {
   const candidates = buildMemoryCandidatePreviews(manifest.localScan);
   writeMemoryCandidates(candidates);
@@ -1011,6 +1196,7 @@ async function runInit(options) {
     normalizedOptions.starter ? "starter" : "default",
     activationScan
   );
+  await runHostedDayZeroCorpusSync(answers, activationManifest, !normalizedOptions.skipTest);
   runLocalSourceActivation(answers, activationManifest);
   createActivationArtifacts(answers, activationManifest);
   printSuccess(answers, validationReport, activationManifest);
@@ -3155,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 [
@@ -3164,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."
     ];
@@ -3199,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."
     ];
@@ -3464,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)}\`
@@ -3517,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
 
@@ -3546,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.
@@ -4331,6 +4589,16 @@ function printActivationSummary(manifest) {
       `   Target: ${manifest.activationMetric.targetMinutes} minutes to a true, non-obvious own-repo answer.`
     )
   );
+  console.log(
+    chalk.dim(
+      `   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.9",
+  "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",