create-snipara 2.0.7 → 2.0.9

package/README.md

@@ -26,6 +26,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
 
 ## Why It Exists
 
@@ -114,7 +115,7 @@ That distinction matters:
 - installs optional `snipara-sandbox`
 - installs optional `snipara-orchestrator` for proof gates, drift checks, and htask workflows when requested
 - configures `.mcp.json`
-- generates merge-ready AI agent templates in `.snipara/templates/`, including Pro+ symbol-card, code-impact, and managed workflow guidance for paid Context plans
+- generates merge-ready AI agent templates in `.snipara/templates/`, including symbol-card, code-impact, and managed workflow guidance within plan capacity
 - creates `AGENTS.md` and `CLAUDE.md` when missing, or appends a marked Snipara section when those files already exist
 - creates `.cursor/rules/snipara.mdc` and `.codex/config.toml` when those files do not already exist
 - validates Codex config against Hosted MCP plus `bearer_token_env_var = "SNIPARA_API_KEY"` and tells users to restart Codex after MCP config changes

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.7",
+  version: "2.0.9",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -115,6 +115,612 @@ deployment, and production smoke checks behind the scenes. Surface important
 decisions, blockers, and evidence, but do not make the user manually orchestrate
 routine Snipara or release mechanics.`;
 var UNIVERSAL_CLIENT_GUIDANCE = "The target experience is outcome-first: the user can ask for engineering judgment or a release, and the agent should use Snipara context, workflow state, verification, package checks, Git, deploy, and smoke checks without making the user orchestrate routine mechanics.";
+var DECISION_COMMIT_TERMS = [
+  "adopt",
+  "because",
+  "decide",
+  "decision",
+  "drop",
+  "migrate",
+  "prefer",
+  "replace",
+  "revert",
+  "standardize",
+  "switch"
+];
+function buildActivationId() {
+  return `act_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function getActivationDir() {
+  return path.join(process.cwd(), ".snipara", "activation");
+}
+function getActivationManifestPath() {
+  return path.join(getActivationDir(), "manifest.json");
+}
+function getActivationHandoffPath() {
+  return path.join(getActivationDir(), "handoff.md");
+}
+function getMemoryCandidatesPath() {
+  return path.join(getActivationDir(), "memory-candidates.json");
+}
+function writeActivationManifest(manifest) {
+  fs.mkdirSync(getActivationDir(), { recursive: true });
+  fs.writeFileSync(getActivationManifestPath(), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+function updateActivationManifest(manifest) {
+  manifest.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  writeActivationManifest(manifest);
+}
+function createActivationLane(status, detail, command) {
+  return command ? { status, detail, command } : { status, detail };
+}
+function failActivationLane(detail, command, error) {
+  const message = error instanceof Error && error.message ? error.message : "unknown error";
+  return {
+    status: "failed",
+    detail,
+    command,
+    error: message.slice(0, 500)
+  };
+}
+function readPackageJsonScripts() {
+  const packageJsonPath = path.join(process.cwd(), "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return Object.keys(parsed.scripts ?? {}).sort();
+  } catch {
+    return [];
+  }
+}
+function readGitRemote() {
+  try {
+    const remote = execSync("git remote get-url origin", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
+    }).trim();
+    return remote || null;
+  } catch {
+    return null;
+  }
+}
+function readGitStatusPorcelain() {
+  try {
+    const output = execSync("git status --short", {
+      cwd: process.cwd(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1e3
+    }).trim();
+    return output ? output.split(/\r?\n/).slice(0, 25) : [];
+  } catch {
+    return [];
+  }
+}
+function readRecentCommitSubjects() {
+  try {
+    const output = execSync("git log --oneline --max-count=5", {
+      cwd: process.cwd(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1e3
+    }).trim();
+    return output ? output.split(/\r?\n/) : [];
+  } catch {
+    return [];
+  }
+}
+function readDecisionCommitSubjectLines() {
+  try {
+    const output = execSync("git log --pretty=format:%h%x20%s --max-count=50", {
+      cwd: process.cwd(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1500
+    }).trim();
+    if (!output) {
+      return [];
+    }
+    return output.split(/\r?\n/).map((line) => line.trim()).filter((line) => DECISION_COMMIT_TERMS.some((term) => line.toLowerCase().includes(term))).slice(0, 8);
+  } catch {
+    return [];
+  }
+}
+function readMemoryCandidateLines(relativePath) {
+  const absolutePath = path.join(process.cwd(), relativePath);
+  if (!fs.existsSync(absolutePath) || fs.statSync(absolutePath).isDirectory()) {
+    return [];
+  }
+  const content = fs.readFileSync(absolutePath, "utf8").slice(0, 24e3);
+  return content.split(/\r?\n/).map((line) => line.trim()).filter((line) => /decision|decided|must|should|always|never|convention|rule/i.test(line)).slice(0, 4).map((line) => ({
+    source: relativePath,
+    text: line.slice(0, 280),
+    status: "needs_review",
+    reason: "Detected project guidance language. Review before storing as durable memory.",
+    evidence: classifyDecisionSource(relativePath)
+  }));
+}
+function estimateFileTokens(relativePath) {
+  const absolutePath = path.join(process.cwd(), relativePath);
+  if (!fs.existsSync(absolutePath) || fs.statSync(absolutePath).isDirectory()) {
+    return 0;
+  }
+  try {
+    const content = fs.readFileSync(absolutePath, "utf8");
+    return Math.ceil(content.length / 4);
+  } catch {
+    return 0;
+  }
+}
+function buildMemoryCandidatePreviews(scan) {
+  const seen = /* @__PURE__ */ new Set();
+  const gitCandidates = scan.git.recentDecisionCommits.map((line) => ({
+    source: "git log",
+    text: line.slice(0, 280),
+    status: "needs_review",
+    reason: "Detected decision-language in recent commit history. Confirm intent before storing.",
+    evidence: "git_commit_subject"
+  }));
+  const candidates = [
+    ...scan.files.candidateDocs.flatMap(readMemoryCandidateLines),
+    ...gitCandidates
+  ];
+  return candidates.filter((candidate) => {
+    const key = `${candidate.source}:${candidate.text}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  }).slice(0, 20);
+}
+function readTextFileSnippet(relativePath, maxChars = 24e3) {
+  const absolutePath = path.join(process.cwd(), relativePath);
+  if (!fs.existsSync(absolutePath) || fs.statSync(absolutePath).isDirectory()) {
+    return "";
+  }
+  try {
+    return fs.readFileSync(absolutePath, "utf8").slice(0, maxChars);
+  } catch {
+    return "";
+  }
+}
+function buildStalenessFindings(scan) {
+  const findings = [];
+  const scriptSet = new Set(scan.scripts);
+  for (const source of scan.files.candidateDocs.slice(0, 30)) {
+    const content = readTextFileSnippet(source);
+    if (!content) {
+      continue;
+    }
+    const scriptMatches = [...content.matchAll(/\b(?:npm|pnpm|yarn|bun)\s+run\s+([a-z0-9:_-]+)/gi)];
+    for (const match of scriptMatches) {
+      const scriptName = match[1];
+      if (scriptName && !scriptSet.has(scriptName)) {
+        findings.push({
+          source,
+          severity: "possible",
+          summary: `Documentation references \`${match[0]}\`, but package.json has no \`${scriptName}\` script.`,
+          recommendation: "Verify the setup docs or add the missing script before relying on this instruction."
+        });
+      }
+    }
+    if (scan.packageManagers.length === 1 && scan.packageManagers[0] === "pnpm" && /\bnpm install\b/i.test(content)) {
+      findings.push({
+        source,
+        severity: "possible",
+        summary: "Documentation mentions `npm install`, but the repo has a pnpm lockfile.",
+        recommendation: "Confirm whether npm remains supported or update setup docs to pnpm."
+      });
+    }
+  }
+  return findings.slice(0, 8);
+}
+function buildContextEconomyReport(scan, dayZeroQuery) {
+  const indexedSourceTokens = scan.files.candidateDocs.reduce(
+    (total, source) => total + estimateFileTokens(source),
+    0
+  );
+  const rawWindowBaselineTokens = Math.max(indexedSourceTokens, 8e3);
+  const estimatedPromptTokens = Math.ceil(dayZeroQuery.length / 4);
+  const estimatedRetrievedTokens = Math.min(
+    rawWindowBaselineTokens,
+    Math.max(estimatedPromptTokens + scan.files.candidateDocs.length * 160, 1200)
+  );
+  const estimatedSavedTokens = Math.max(0, rawWindowBaselineTokens - estimatedRetrievedTokens);
+  return {
+    basis: "activation_estimate",
+    rawWindowBaselineTokens,
+    estimatedRetrievedTokens,
+    estimatedSavedTokens,
+    savingsPercent: rawWindowBaselineTokens > 0 ? Math.round(estimatedSavedTokens / rawWindowBaselineTokens * 100) : 0,
+    note: "Estimated from activation sources until hosted query receipts provide measured savings."
+  };
+}
+function buildAgentReadinessReport(scan) {
+  const findings = buildStalenessFindings(scan);
+  return {
+    stalenessFindings: findings,
+    summary: findings.length > 0 ? `${findings.length} possible doc staleness finding(s) need review.` : "No obvious setup-doc staleness found in activation sources."
+  };
+}
+function writeMemoryCandidates(candidates) {
+  fs.mkdirSync(getActivationDir(), { recursive: true });
+  fs.writeFileSync(
+    getMemoryCandidatesPath(),
+    JSON.stringify({ candidates, note: "Review required before durable memory import." }, null, 2) + "\n",
+    "utf8"
+  );
+}
+function writeInitialHandoff(answers, manifest) {
+  fs.mkdirSync(getActivationDir(), { recursive: true });
+  const statusLines = readGitStatusPorcelain();
+  const recentCommits = readRecentCommitSubjects();
+  const lines = [
+    `# Initial Snipara Handoff`,
+    "",
+    `Project: ${answers.projectSlug}`,
+    `AI client: ${getClientDisplayName(answers.aiClient)}`,
+    `Repo path: ${manifest.repoPath}`,
+    `Git branch: ${manifest.git.branch ?? "not detected"}`,
+    `Git remote: ${manifest.git.remote ?? "not detected"}`,
+    "",
+    "## Activation lanes",
+    ...Object.entries(manifest.lanes).map(
+      ([name, lane]) => `- ${name}: ${lane.status} - ${lane.detail}`
+    ),
+    "",
+    "## Local status",
+    ...statusLines.length > 0 ? statusLines.map((line) => `- ${line}`) : ["- clean or unavailable"],
+    "",
+    "## Recent commits",
+    ...recentCommits.length > 0 ? recentCommits.map((line) => `- ${line}`) : ["- not available"],
+    "",
+    "## Next",
+    "- 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.",
+    ""
+  ];
+  fs.writeFileSync(getActivationHandoffPath(), lines.join("\n"), "utf8");
+}
+function detectLocalActivationScan(detection) {
+  const cwd = process.cwd();
+  const exists = (relativePath) => fs.existsSync(path.join(cwd, relativePath));
+  const candidateDocs = findDecisionArchaeologySources(cwd);
+  const lockfiles = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"].filter(
+    exists
+  );
+  const packageManagers = [
+    exists("pnpm-lock.yaml") ? "pnpm" : null,
+    exists("package-lock.json") ? "npm" : null,
+    exists("yarn.lock") ? "yarn" : null,
+    exists("bun.lockb") ? "bun" : null
+  ].filter((value) => Boolean(value));
+  const rootEntries = fs.existsSync(cwd) ? fs.readdirSync(cwd).slice(0, 250) : [];
+  const rootExtensions = new Set(
+    rootEntries.map((entry) => path.extname(entry).replace(/^\./, "")).filter(Boolean)
+  );
+  const languages = [
+    exists("package.json") || rootExtensions.has("ts") || rootExtensions.has("tsx") ? "typescript" : null,
+    exists("package.json") || rootExtensions.has("js") || rootExtensions.has("jsx") ? "javascript" : null,
+    exists("pyproject.toml") || exists("requirements.txt") || rootExtensions.has("py") ? "python" : null,
+    exists("go.mod") || rootExtensions.has("go") ? "go" : null,
+    exists("Cargo.toml") || rootExtensions.has("rs") ? "rust" : null
+  ].filter((value) => Boolean(value));
+  return {
+    files: {
+      candidateDocs,
+      lockfiles,
+      hasPackageJson: exists("package.json"),
+      hasPyproject: exists("pyproject.toml"),
+      hasRequirements: exists("requirements.txt"),
+      hasDockerfile: exists("Dockerfile")
+    },
+    packageManagers,
+    languages: [...new Set(languages)],
+    scripts: readPackageJsonScripts(),
+    git: {
+      detected: detection.inGitRepo,
+      branch: detection.inGitRepo ? detectGitBranch() : null,
+      remote: detection.inGitRepo ? readGitRemote() : null,
+      recentDecisionCommits: detection.inGitRepo ? readDecisionCommitSubjectLines() : []
+    }
+  };
+}
+function classifyDecisionSource(relativePath) {
+  if (/(^|\/)(adr|decisions?)(\/|$)/i.test(relativePath)) {
+    return "adr_or_decision_doc";
+  }
+  if (/AGENTS\.md|CLAUDE\.md|MEMORY\.md|\.cursor\/rules|copilot-instructions/i.test(relativePath)) {
+    return "agent_instruction";
+  }
+  if (/CHANGELOG/i.test(relativePath)) {
+    return "changelog";
+  }
+  return "project_document";
+}
+function listFilesUnder(relativeDir, maxFiles) {
+  const root = path.join(process.cwd(), relativeDir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return [];
+  }
+  const results = [];
+  const visit = (dir) => {
+    if (results.length >= maxFiles) {
+      return;
+    }
+    for (const entry of fs.readdirSync(dir).sort()) {
+      const absolutePath = path.join(dir, entry);
+      const stat = fs.statSync(absolutePath);
+      if (stat.isDirectory()) {
+        visit(absolutePath);
+      } else if (/\.(md|mdx|txt|mdc)$/i.test(entry)) {
+        results.push(path.relative(process.cwd(), absolutePath));
+      }
+      if (results.length >= maxFiles) {
+        return;
+      }
+    }
+  };
+  visit(root);
+  return results;
+}
+function findDecisionArchaeologySources(cwd) {
+  const exists = (relativePath) => fs.existsSync(path.join(cwd, relativePath));
+  const directSources = [
+    "README.md",
+    "CHANGELOG.md",
+    "MEMORY.md",
+    ...["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"].filter(
+      (source) => exists(source)
+    )
+  ].filter(exists);
+  const archaeologySources = [
+    ...listFilesUnder("docs/adr", 20),
+    ...listFilesUnder("docs/adrs", 20),
+    ...listFilesUnder("docs/decision", 20),
+    ...listFilesUnder("docs/decisions", 20),
+    ...listFilesUnder(".cursor/rules", 20)
+  ];
+  return [.../* @__PURE__ */ new Set([...directSources, ...archaeologySources])].slice(0, 80);
+}
+function createInitialFirstWorkBrief(answers, detection, scan) {
+  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";
+  const languages = scan.languages.length > 0 ? scan.languages.join(", ") : "not detected yet";
+  const hotFiles = scan.files.candidateDocs.slice(0, 5);
+  const hotFileLine = hotFiles.length > 0 ? `First files to ground on: ${hotFiles.join(", ")}.` : "First grounding files will appear after local source sync or hosted provider sync.";
+  const dayZeroQuery = "What is this project, what is currently in flight, and what should an agent know before making the first edit?";
+  return {
+    title: `First Work Brief for ${answers.projectSlug}`,
+    status: "partial",
+    sections: [
+      {
+        title: "Repository summary",
+        lines: [
+          detection.inGitRepo ? "Local Git repository detected." : "Local folder detected.",
+          githubLine,
+          `AI client: ${getClientDisplayName(answers.aiClient)}.`,
+          `Languages: ${languages}.`
+        ]
+      },
+      {
+        title: "Current architecture",
+        lines: [
+          `Initial docs: ${docs}.`,
+          `Package scripts: ${commands}.`,
+          hotFileLine,
+          "Source indexing runs before claiming architecture certainty."
+        ]
+      },
+      {
+        title: "Day-zero answer pack",
+        lines: [
+          `Ask Snipara: "${dayZeroQuery}"`,
+          "Goal: reach one correct, non-obvious statement about this repository in under 5 minutes."
+        ]
+      },
+      {
+        title: "Current risks",
+        lines: [
+          "Treat generated memory as candidates until reviewed.",
+          "GitHub PR/review intelligence requires explicit GitHub connection later."
+        ]
+      },
+      {
+        title: "Suggested next task",
+        lines: ["Ask your agent what it should know before editing the first target area."]
+      },
+      {
+        title: "Top impacted modules",
+        lines: [
+          "Code Graph is available on Free within capacity caps; first answers improve as symbols index.",
+          "For the first PR, run snipara_code_impact or companion code impact before editing."
+        ]
+      }
+    ]
+  };
+}
+function createActivationManifest(answers, detection, mode = "default", scan) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const hasHostedConfig = answers.profile !== "runtime-only";
+  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?";
+  return {
+    version: "create-snipara-activation-v1",
+    activationId: buildActivationId(),
+    mode,
+    activationMetric: {
+      name: "time_to_how_did_it_know_that",
+      targetMinutes: 5,
+      proof: "A correct, non-obvious statement about this repository from the first answer pack."
+    },
+    dayZeroQuery: {
+      tool: "snipara_context_query",
+      query: dayZeroQuery,
+      expectedOutcome: "First own-repo answer pack before the user reads product docs."
+    },
+    agentReadiness: buildAgentReadinessReport(localScan),
+    contextEconomy: buildContextEconomyReport(localScan, dayZeroQuery),
+    projectSlug: answers.projectSlug,
+    projectId: answers.projectId || null,
+    repoPath: process.cwd(),
+    aiClient: answers.aiClient,
+    git: {
+      detected: detection.inGitRepo,
+      branch: answers.githubRepo?.branch ?? localScan.git.branch,
+      remote: answers.githubRepo?.remoteUrl ?? localScan.git.remote,
+      githubRepo: answers.githubRepo?.fullName ?? null
+    },
+    localScan,
+    lanes: {
+      connection: createActivationLane(
+        hasHostedConfig ? "ready" : "skipped",
+        hasHostedConfig ? "Hosted MCP config written." : "Runtime-only profile skipped Hosted MCP config."
+      ),
+      clientConfig: createActivationLane(
+        hasHostedConfig ? "ready" : "skipped",
+        hasHostedConfig ? `${getClientDisplayName(answers.aiClient)} project files generated.` : "No AI client config generated for runtime-only profile."
+      ),
+      localSnapshot: createActivationLane(
+        hasCompanion ? "queued" : "skipped",
+        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."
+      ),
+      codeGraph: createActivationLane(
+        hasCompanion ? "queued" : "skipped",
+        hasCompanion ? "Free Code Graph indexing starts from local source overlay within capacity caps." : "Free Code Graph is available after companion or hosted provider sync."
+      ),
+      memoryCandidates: createActivationLane(
+        hasCompanion ? "needs_review" : "skipped",
+        hasCompanion ? "Candidate decisions stay pending review; no durable memory is auto-approved." : "Install companion later to extract reviewable memory candidates."
+      ),
+      handoff: createActivationLane(
+        hasCompanion ? "queued" : "skipped",
+        hasCompanion ? "Initial local handoff will summarize branch, files, and setup state." : "Install companion later to create local handoffs."
+      ),
+      firstBrief: createActivationLane(
+        "ready",
+        "First Work Brief and day-zero answer-pack prompt generated from local setup signals."
+      ),
+      githubSync: createActivationLane(
+        answers.configureGitHub && answers.githubRepo ? "queued" : "skipped",
+        answers.configureGitHub && answers.githubRepo ? "GitHub automation can be connected after explicit approval." : "No GitHub integration required; connect later for PRs, reviews, and team sync."
+      )
+    },
+    artifacts: {
+      handoffPath: null,
+      memoryCandidatesPath: null
+    },
+    firstBrief: createInitialFirstWorkBrief(answers, detection, localScan),
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function runLocalSourceActivation(answers, manifest) {
+  if (!answers.installCompanion || answers.profile === "runtime-only") {
+    updateActivationManifest(manifest);
+    return;
+  }
+  const companionCommand = detectCompanionCommand();
+  if (!companionCommand) {
+    const detail = `${COMPANION_COMMAND_NAME} ${MIN_COMPANION_VERSION}+ is not on PATH after setup.`;
+    manifest.lanes.localSnapshot = createActivationLane("skipped", detail);
+    manifest.lanes.contextIndex = createActivationLane("skipped", detail);
+    manifest.lanes.codeGraph = createActivationLane("skipped", detail);
+    updateActivationManifest(manifest);
+    return;
+  }
+  const initCommand = `${companionCommand} source init .`;
+  const syncCommand = `${companionCommand} source sync --json`;
+  const spinner = ora("Activating local Project Intelligence").start();
+  try {
+    execSync(initCommand, {
+      cwd: process.cwd(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 3e4
+    });
+    manifest.lanes.localSnapshot = createActivationLane(
+      "ready",
+      "Local source snapshot created.",
+      initCommand
+    );
+  } catch (error) {
+    spinner.warn("Local source snapshot was not created");
+    manifest.lanes.localSnapshot = failActivationLane(
+      "Local source activation failed; setup can still continue.",
+      initCommand,
+      error
+    );
+    updateActivationManifest(manifest);
+    return;
+  }
+  try {
+    execSync(syncCommand, {
+      cwd: process.cwd(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 45e3
+    });
+    manifest.lanes.contextIndex = createActivationLane(
+      "indexing",
+      "Local documents submitted for context indexing.",
+      syncCommand
+    );
+    manifest.lanes.codeGraph = createActivationLane(
+      "indexing",
+      "Local code overlay submitted for Code Graph indexing.",
+      syncCommand
+    );
+    spinner.succeed("Local Project Intelligence activation started");
+  } catch (error) {
+    spinner.warn("Local source sync did not complete");
+    manifest.lanes.contextIndex = failActivationLane(
+      "Context indexing could not be started from the local snapshot.",
+      syncCommand,
+      error
+    );
+    manifest.lanes.codeGraph = failActivationLane(
+      "Code Graph indexing could not be started from the local snapshot.",
+      syncCommand,
+      error
+    );
+  }
+  updateActivationManifest(manifest);
+}
+function createActivationArtifacts(answers, manifest) {
+  const candidates = buildMemoryCandidatePreviews(manifest.localScan);
+  writeMemoryCandidates(candidates);
+  manifest.artifacts.memoryCandidatesPath = path.relative(process.cwd(), getMemoryCandidatesPath());
+  manifest.lanes.memoryCandidates = createActivationLane(
+    candidates.length > 0 ? "needs_review" : "skipped",
+    candidates.length > 0 ? `${candidates.length} memory candidates prepared for review; none were imported.` : "No memory candidates found in local docs.",
+    manifest.artifacts.memoryCandidatesPath
+  );
+  writeInitialHandoff(answers, manifest);
+  manifest.artifacts.handoffPath = path.relative(process.cwd(), getActivationHandoffPath());
+  manifest.lanes.handoff = createActivationLane(
+    "ready",
+    "Initial local handoff created.",
+    manifest.artifacts.handoffPath
+  );
+  manifest.lanes.firstBrief = createActivationLane(
+    "ready",
+    "First Work Brief generated from local setup and scan signals.",
+    path.relative(process.cwd(), getActivationManifestPath())
+  );
+  updateActivationManifest(manifest);
+}
 var DeviceAuthorizationAborted = class extends Error {
 };
 var AI_CLIENT_CHOICES = [
@@ -204,7 +810,7 @@ function buildProgram() {
   ).option("--advanced", "Show advanced profile, project id, hooks, GitHub, and sandbox prompts").option(
     "--profile <profile>",
     "Install profile: hosted-only, hosted-companion, full-stack, runtime-only"
-  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--with-orchestrator", "Install optional snipara-orchestrator package").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only Snipara Sandbox").addOption(new Option("--full", "Legacy alias for --profile full-stack").hideHelp()).option("-y, --yes", "Accept defaults without prompting").action(async (options) => {
+  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--with-orchestrator", "Install optional snipara-orchestrator package").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--starter", "Mark this run as a starter activation and print dashboard-first guidance").option("--runtime-only", "Install only Snipara Sandbox").addOption(new Option("--full", "Legacy alias for --profile full-stack").hideHelp()).option("-y, --yes", "Accept defaults without prompting").action(async (options) => {
     printBanner();
     await runInit(options);
   });
@@ -219,6 +825,10 @@ function buildProgram() {
     printBanner();
     await runRepair(options);
   });
+  program.command("demo").description("Open the guided Snipara activation demo without changing this repository").option("--no-open", "Print demo links without opening a browser").action((options) => {
+    printBanner();
+    runDemo(options);
+  });
   program.command("upgrade").description("Upgrade installed Snipara local components").option("--slug <slug>", "Project slug override").option("--with-hooks", "Refresh hooks after upgrade").option("--with-runtime", "Upgrade Snipara Sandbox even if not detected").option("--with-mcp", "Upgrade snipara-mcp even if not detected").option("--with-companion", "Upgrade companion even if not detected").option("--with-orchestrator", "Upgrade snipara-orchestrator even if not detected").action(async (options) => {
     printBanner();
     await runUpgrade(options);
@@ -241,7 +851,7 @@ function addSharedRootOptions(program) {
   ).option("--advanced", "Show advanced profile, project id, hooks, GitHub, and sandbox prompts").option(
     "--profile <profile>",
     "Install profile: hosted-only, hosted-companion, full-stack, runtime-only"
-  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--with-orchestrator", "Install optional snipara-orchestrator package").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--runtime-only", "Install only Snipara Sandbox").addOption(new Option("--full", "Legacy alias for --profile full-stack").hideHelp()).option("-y, --yes", "Accept defaults without prompting");
+  ).option("--skip-companion", "Skip local companion CLI installation").option("--skip-mcp", "Skip local snipara-mcp package installation").option("--skip-runtime", "Skip snipara-sandbox installation").option("--skip-hooks", "Skip hook generation").option("--skip-test", "Skip hosted connection test").option("--with-orchestrator", "Install optional snipara-orchestrator package").option("--github", "Open GitHub repository automation setup when a git remote is detected").option("--skip-github", "Skip the GitHub automation prompt").option("--github-path <path>", "Optional GitHub path filter for the initial repository sync").option("--starter", "Mark this run as a starter activation and print dashboard-first guidance").option("--runtime-only", "Install only Snipara Sandbox").addOption(new Option("--full", "Legacy alias for --profile full-stack").hideHelp()).option("-y, --yes", "Accept defaults without prompting");
 }
 async function main() {
   const program = buildProgram();
@@ -340,6 +950,7 @@ function parseInitOptionsFromArgv(args) {
     "--Full": "full",
     "--github": "github",
     "--skip-github": "skipGithub",
+    "--starter": "starter",
     "--yes": "yes",
     "-y": "yes"
   };
@@ -368,6 +979,8 @@ function parseInitOptionsFromArgv(args) {
 async function runInit(options) {
   const normalizedOptions = normalizeInitOptions(options);
   const answers = await gatherConfiguration(normalizedOptions);
+  const activationDetection = detectEnvironment();
+  const activationScan = detectLocalActivationScan(activationDetection);
   if (answers.installMcp || answers.installRuntime || answers.installOrchestrator) {
     await installPythonPackages(answers, false);
   }
@@ -392,7 +1005,15 @@ async function runInit(options) {
   await createCompanionPack(answers);
   const validationReport = await runValidation(answers, !normalizedOptions.skipTest);
   writeDoctorReport(validationReport);
-  printSuccess(answers, validationReport);
+  const activationManifest = createActivationManifest(
+    answers,
+    activationDetection,
+    normalizedOptions.starter ? "starter" : "default",
+    activationScan
+  );
+  runLocalSourceActivation(answers, activationManifest);
+  createActivationArtifacts(answers, activationManifest);
+  printSuccess(answers, validationReport, activationManifest);
   if (answers.configureGitHub && answers.githubRepo) {
     await openGitHubAutomation(answers);
   }
@@ -1031,6 +1652,27 @@ function openBrowser(url) {
 `));
   }
 }
+function runDemo(options) {
+  const demoUrl = `${BASE_URL}/demo#sixty-second-demo`;
+  const docsUrl = `${BASE_URL}/docs/integration/create-snipara`;
+  const proofUrl = `${BASE_URL}/proof`;
+  console.log(chalk.bold("\nSnipara activation demo\n"));
+  console.log("Use this when you want to see the value before connecting a real repository.");
+  console.log("\nWhat to inspect:");
+  console.log("   1. What Changed");
+  console.log("   2. Start Work / First Work Brief");
+  console.log("   3. Project Intelligence");
+  console.log("   4. Impact Graph");
+  console.log("   5. Adaptive Routing");
+  console.log("\nLinks:");
+  console.log(`   Demo: ${demoUrl}`);
+  console.log(`   Setup docs: ${docsUrl}`);
+  console.log(`   Proof: ${proofUrl}`);
+  if (options.open !== false) {
+    console.log(chalk.dim("\nOpening the 60-second demo...\n"));
+    openBrowser(demoUrl);
+  }
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1765,8 +2407,8 @@ Agent task lifecycle:
    work.
 6. Use whichever structural code graph tools are exposed in the current session
    for callers, imports, neighbors, and path questions. Tool exposure can vary.
-7. On paid Context plans, use \`snipara_code_symbol_card\` for agent-ready symbol
-   context and \`snipara-companion code impact\` before risky multi-file changes, PR
+7. Use \`snipara_code_symbol_card\` for agent-ready symbol context within plan
+   capacity and \`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.
 8. Use \`snipara_plan\` for complex or multi-surface work in any plan when
@@ -1833,7 +2475,7 @@ ${EXPERIENCE_GOAL_SECTION}
 - 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.
+- Use \`snipara_code_symbol_card\` before editing important symbols within plan capacity.
 - 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.
@@ -1873,7 +2515,7 @@ ${EXPERIENCE_GOAL_SECTION}
 - 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.
+- Use \`snipara_code_symbol_card\` before editing important symbols within plan capacity.
 - Check every \`snipara_code_*\` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
 - Use \`snipara_plan\` for complex or multi-surface work when available. Keep simple Q&A on targeted \`snipara_context_query\`; for FULL-mode audits, comparisons, roadmap/implementation planning, release readiness, or package-surface reviews, use \`snipara_decompose\` to preserve axes and \`snipara_multi_query\` for independent follow-up questions when Pro+ tools are exposed.
 - Use local file reads, \`rg\`, \`git status --short\`, and tests for exact code edits and current working-tree state.
@@ -2685,7 +3327,7 @@ function getCompanionCommands(answers) {
     {
       title: "Analyze code impact before a risky change",
       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."
+      purpose: "Use code impact analysis within plan capacity to surface likely tests, docs, routes, config, and risks."
     },
     {
       title: answers.installOrchestrator ? "Run an explicit production orchestration gate" : "Enable explicit production orchestration",
@@ -2856,7 +3498,7 @@ ${guidance.map((line) => `- ${line}`).join("\n")}
 - Use \`answer_pack\` facts, caveats, source maps, and verification checks before making 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 or multi-surface work when exposed. Keep simple Q&A on targeted \`snipara_context_query\`; for FULL-mode audits, comparisons, roadmap/implementation planning, release readiness, or package-surface reviews, use \`snipara_decompose\` to preserve axes and \`snipara_multi_query\` for independent follow-up questions when Pro+ tools are exposed.
-- 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 \`snipara_code_symbol_card\` for important symbols within plan capacity. 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.
@@ -3643,7 +4285,85 @@ function printSetupVerdict(answers, report) {
     console.log("   AI client loaded MCP: not verifiable from this terminal");
   }
 }
-function printSuccess(answers, report) {
+function formatActivationStatus(status) {
+  if (status === "ready") {
+    return chalk.green("\u2713 ready");
+  }
+  if (status === "indexing" || status === "queued") {
+    return chalk.yellow(`\u23F3 ${status}`);
+  }
+  if (status === "needs_review") {
+    return chalk.yellow("review");
+  }
+  if (status === "failed") {
+    return chalk.red("failed");
+  }
+  return chalk.dim("skipped");
+}
+function printActivationSummary(manifest) {
+  console.log(chalk.bold("\nProject Intelligence activation:\n"));
+  const orderedLanes = [
+    ["Connected", manifest.lanes.connection],
+    ["AI client configured", manifest.lanes.clientConfig],
+    ["Repository analyzed", manifest.lanes.localSnapshot],
+    ["Context index", manifest.lanes.contextIndex],
+    ["Code Graph", manifest.lanes.codeGraph],
+    ["Memory candidates", manifest.lanes.memoryCandidates],
+    ["Initial handoff", manifest.lanes.handoff],
+    ["First Work Brief", manifest.lanes.firstBrief],
+    ["GitHub sync", manifest.lanes.githubSync]
+  ];
+  for (const [label, lane] of orderedLanes) {
+    console.log(`   ${formatActivationStatus(lane.status)} ${label} - ${lane.detail}`);
+  }
+  console.log(chalk.bold("\nFirst Work Brief:\n"));
+  for (const section of manifest.firstBrief.sections) {
+    console.log(`   ${section.title}`);
+    for (const line of section.lines.slice(0, 2)) {
+      console.log(chalk.dim(`   - ${line}`));
+    }
+  }
+  console.log(chalk.bold("\nDay-zero proof:\n"));
+  console.log(`   Tool: ${manifest.dayZeroQuery.tool}`);
+  console.log(`   Query: ${manifest.dayZeroQuery.query}`);
+  console.log(
+    chalk.dim(
+      `   Target: ${manifest.activationMetric.targetMinutes} minutes to a true, non-obvious own-repo answer.`
+    )
+  );
+  console.log(chalk.bold("\nAgent readiness:\n"));
+  console.log(`   ${manifest.agentReadiness.summary}`);
+  for (const finding of manifest.agentReadiness.stalenessFindings.slice(0, 3)) {
+    console.log(chalk.dim(`   - ${finding.source}: ${finding.summary}`));
+  }
+  console.log(chalk.bold("\nContext economy:\n"));
+  console.log(
+    `   Estimated ${manifest.contextEconomy.estimatedRetrievedTokens.toLocaleString("en-US")} tokens retrieved instead of ${manifest.contextEconomy.rawWindowBaselineTokens.toLocaleString("en-US")} raw-window tokens.`
+  );
+  console.log(
+    chalk.dim(
+      `   Saved about ${manifest.contextEconomy.estimatedSavedTokens.toLocaleString("en-US")} tokens (${manifest.contextEconomy.savingsPercent}%). ${manifest.contextEconomy.note}`
+    )
+  );
+  console.log(
+    chalk.dim(
+      `
+   Activation manifest: ${path.relative(process.cwd(), getActivationManifestPath())}`
+    )
+  );
+  if (manifest.artifacts.handoffPath) {
+    console.log(chalk.dim(`   Initial handoff: ${manifest.artifacts.handoffPath}`));
+  }
+  if (manifest.artifacts.memoryCandidatesPath) {
+    console.log(chalk.dim(`   Memory candidates: ${manifest.artifacts.memoryCandidatesPath}`));
+  }
+  if (manifest.mode === "starter") {
+    console.log(
+      chalk.dim(`   Starter tour: ${BASE_URL}/demo#sixty-second-demo and ${BASE_URL}/dashboard`)
+    );
+  }
+}
+function printSuccess(answers, report, activationManifest) {
   console.log(
     chalk.green(`
 \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
@@ -3691,6 +4411,9 @@ function printSuccess(answers, report) {
   console.log(
     chalk.green("   \u2713 .snipara/companion") + chalk.dim(" - Doctor report and optional command references")
   );
+  if (activationManifest) {
+    printActivationSummary(activationManifest);
+  }
   const failedChecks = report.checks.filter((check) => check.status === "fail");
   const warnedChecks = report.checks.filter((check) => check.status === "warn");
   console.log(chalk.bold("\nNext steps:\n"));

package/package.json

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