create-snipara 2.0.17 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # create-snipara
 
-**One-command onboarding for Snipara Hosted MCP Context + Memory.**
+**One-command onboarding for Snipara Cloud or self-hosted Snipara Server.**
 
 `create-snipara` connects a local project to Snipara so AI agents can start
 with project-owned context, reviewed memory, shared guidance, and optional code
@@ -10,10 +10,30 @@ impact tooling instead of starting cold every session.
 npx create-snipara
 ```
 
-`create-snipara` is the simple onboarding package for the agent path. It
-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.
+For a local or private server, use the same activation flow:
+
+```bash
+export SNIPARA_LOCAL_API_KEY="your-server-operator-key"
+npx create-snipara@latest --self-hosted \
+  --server-url http://localhost:8000/mcp/local \
+  --api-key "$SNIPARA_LOCAL_API_KEY" \
+  --client claude-code
+```
+
+Both modes aim to finish with the same visible proof:
+
+```text
+✓ Endpoint connected
+✓ Repository README/docs seeded
+✓ First project-grounded answer verified
+✓ AI client configuration written
+```
+
+`create-snipara` is the single activation engine for the agent path. It detects
+or asks where Snipara should run, writes the right MCP config, seeds a small
+README/docs corpus, and automatically verifies a first project-grounded answer.
+The default path is Cloud because it is the fastest first experience; the same
+flow works with an existing self-hosted Snipara Server.
 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.
@@ -25,7 +45,7 @@ behind the scenes.
 
 Use it for:
 
-- Hosted MCP onboarding for Claude Code, Cursor, Kimi Code CLI, Codex, Gemini, Mistral, VS Code/Copilot, Continue, ChatGPT Desktop, Orca-style MCP clients, LM Studio-backed local stacks, and similar clients
+- Snipara Cloud or self-hosted MCP onboarding for Claude Code, Cursor, Kimi Code CLI, Codex, Gemini, Mistral, VS Code/Copilot, Continue, ChatGPT Desktop, Orca-style MCP clients, LM Studio-backed local stacks, and similar clients
 - 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
@@ -40,22 +60,22 @@ normalizes that setup.
 ```mermaid
 flowchart LR
     Project["Local project"] --> CLI["npx create-snipara"]
-    CLI --> Auth["Snipara auth and project key"]
-    CLI --> MCP["Hosted MCP config"]
+    CLI --> Auth["Cloud auth or self-hosted operator key"]
+    CLI --> MCP["Configured MCP endpoint"]
     CLI --> Templates["AGENTS.md, CLAUDE.md, Cursor, Codex, MCP references"]
     MCP --> Agents["Claude Code, Cursor, Codex, Gemini, Mistral, VS Code, ChatGPT, Orca, LM Studio stacks"]
     Templates --> Agents
     Agents --> Context["Snipara context and memory"]
 ```
 
-The CLI does not become the runtime brain. After setup, the agent talks to
-Hosted MCP and keeps using its own LLM.
+The CLI does not become the runtime brain. After setup, the agent talks to the
+configured MCP endpoint and keeps using its own LLM.
 
 Do not use it to choose business documents one by one. For local folders, mounted Drive/SharePoint exports, old offers, or PowerPoints, use `snipara-business`.
 
 The product surfaces remain:
 
-- Hosted MCP for LLM agents, context, and reviewed memory
+- Snipara Cloud or self-hosted Snipara Server for LLM agents, context, and reviewed memory
 - HTTP API / SDK for apps, integrators, backends, and pipelines
 
 Advanced flags can wire local helpers around those surfaces:
@@ -67,6 +87,24 @@ Advanced flags can wire local helpers around those surfaces:
 - local config, env files, hook scripts, and a project companion pack
 - `snipara-mcp` only for local stdio compatibility, development, or testing
 
+## Deployment Modes
+
+The deployment mode and install profile are independent:
+
+| Mode                       | Command                                                                                                                   | Data boundary                  | First proof                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| Snipara Cloud              | `npx create-snipara@latest`                                                                                               | Snipara-managed hosted project | Cloud MCP connection, README/docs seed, grounded answer            |
+| Self-hosted Snipara Server | `npx create-snipara@latest --self-hosted --server-url http://localhost:8000/mcp/local --api-key "$SNIPARA_LOCAL_API_KEY"` | Your server and storage        | Server contract, MCP connection, README/docs seed, grounded answer |
+
+Self-hosted runs use the server's `X-API-Key` operator key, the public
+`snipara-server-oss-v2` contract, and the server's `rlm_*` compatibility tools.
+They never open Cloud signup or call the Cloud dashboard automation API.
+
+Every successful live setup writes `.snipara/activation/activation-manifest.json`
+with the selected endpoint, seed status, proof tool, and a non-sensitive proof
+receipt such as `answer_pack_chars=...`. Raw API keys are never included in the
+activation report or JSON summary.
+
 ## Install Profiles
 
 The CLI now works around explicit install profiles:
@@ -199,11 +237,13 @@ npx create-snipara
 
 The interactive flow now asks for:
 
+- deployment mode when `--advanced` is used
+- a self-hosted MCP endpoint when self-hosted mode is selected
 - project slug
-- API key path: existing API key, free signup, or add key later
+- API key path: Cloud key/signup, self-hosted operator key, or add key later
 - AI client
 
-By default, this uses the minimal `hosted-only` setup: hosted MCP config and a
+By default, this uses the minimal `hosted-only` setup: configured MCP config and a
 doctor report, with no local Companion install, hooks, GitHub approval prompt, or
 sandbox prompt. Add `--advanced` when you want profile selection, project id
 entry, hook prompts, GitHub automation prompts, or sandbox provider prompts.
@@ -414,9 +454,19 @@ npx create-snipara --runtime-only
 # Safer non-interactive setup with an existing API key
 SNIPARA_API_KEY=snp-xxx npx create-snipara -y --slug my-project
 
+# Self-hosted non-interactive setup; the same command works with any MCP client
+SNIPARA_LOCAL_API_KEY=local-operator-key npx create-snipara -y \
+  --self-hosted --server-url http://localhost:8000/mcp/local \
+  --api-key "$SNIPARA_LOCAL_API_KEY" --slug my-project
+
 # Compatibility path; prints a warning because CLI args can leak
 npx create-snipara -y --api-key snp-xxx --slug my-project
 
+# Explicitly choose the deployment mode
+npx create-snipara -y --deployment hosted --api-key snp-xxx --slug my-project
+npx create-snipara -y --deployment self-hosted \
+  --server-url http://localhost:8000/mcp/local --api-key local-operator-key
+
 # Open GitHub automation after setup when a GitHub remote is detected
 npx create-snipara --github
 npx create-snipara --github-path docs/

package/dist/index.js

@@ -5,6 +5,7 @@ import { Command, Option } from "commander";
 import prompts from "prompts";
 import chalk from "chalk";
 import ora from "ora";
+import { randomUUID } from "crypto";
 import fs from "fs";
 import path from "path";
 import { execSync, spawn } from "child_process";
@@ -13,8 +14,8 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "2.0.17",
-  description: "Onboard Snipara Hosted MCP Context + Memory with project bootstrap intelligence and optional local workflows",
+  version: "2.1.0",
+  description: "Onboard Snipara Cloud or self-hosted MCP with an automatic project-grounded proof of value",
   main: "dist/index.js",
   type: "module",
   bin: {
@@ -52,7 +53,11 @@ var package_default = {
     "lm-studio",
     "vscode",
     "continue",
-    "claude-desktop"
+    "claude-desktop",
+    "self-hosted",
+    "snipara-server",
+    "project-intelligence",
+    "persistent-memory"
   ],
   author: "Snipara",
   license: "MIT",
@@ -134,7 +139,7 @@ var DECISION_COMMIT_TERMS = [
   "switch"
 ];
 function buildActivationId() {
-  return `act_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+  return `act_${Date.now().toString(36)}_${randomUUID().replace(/-/g, "").slice(0, 12)}`;
 }
 function getActivationDir() {
   return path.join(process.cwd(), ".snipara", "activation");
@@ -1188,7 +1193,7 @@ function createInitialFirstWorkBrief(answers, detection, scan) {
 }
 function createActivationManifest(answers, detection, mode = "default", scan) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const hasHostedConfig = answers.profile !== "runtime-only";
+  const hasMcpConfig = 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?";
@@ -1196,6 +1201,8 @@ function createActivationManifest(answers, detection, mode = "default", scan) {
   return {
     activationId: buildActivationId(),
     mode,
+    deployment: answers.deployment,
+    serverUrl: answers.serverUrl,
     surfaceContract,
     consumerContract: buildEditorActivationConsumerContract(answers.aiClient),
     activationMetric: {
@@ -1204,15 +1211,22 @@ function createActivationManifest(answers, detection, mode = "default", scan) {
       proof: "A correct, non-obvious statement about this repository from the first answer pack."
     },
     dayZeroQuery: {
-      tool: "snipara_context_query",
+      tool: answers.deployment === "self-hosted" ? "rlm_context_query" : "snipara_context_query",
       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."
+      `README and docs Markdown will be submitted to ${getDeploymentLabel(answers.deployment)} before the first day-zero query when live checks are enabled.`
     ),
+    valueProof: {
+      status: "skipped",
+      deployment: answers.deployment,
+      query: dayZeroQuery,
+      detail: "Waiting for the configured MCP connection and source seeding.",
+      observedAt: now
+    },
     agentReadiness: buildAgentReadinessReport(localScan),
     contextEconomy: buildContextEconomyReport(localScan, dayZeroQuery),
     projectSlug: answers.projectSlug,
@@ -1228,20 +1242,20 @@ function createActivationManifest(answers, detection, mode = "default", scan) {
     localScan,
     lanes: {
       connection: createActivationLane(
-        hasHostedConfig ? "ready" : "skipped",
-        hasHostedConfig ? "Hosted MCP config written." : "Runtime-only profile skipped Hosted MCP config."
+        hasMcpConfig ? "ready" : "skipped",
+        hasMcpConfig ? `${getDeploymentLabel(answers.deployment)} MCP config written.` : "Runtime-only profile skipped MCP config."
       ),
       clientConfig: createActivationLane(
-        hasHostedConfig ? "ready" : "skipped",
-        hasHostedConfig ? `${getClientDisplayName(answers.aiClient)} project files generated.` : "No AI client config generated for runtime-only profile."
+        hasMcpConfig ? "ready" : "skipped",
+        hasMcpConfig ? `${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(
-        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."
+        hasMcpConfig || hasCompanion ? "queued" : "skipped",
+        hasCompanion ? "Context indexing starts from local docs and instruction files." : hasMcpConfig ? `Day-zero README/docs sync will seed ${getDeploymentLabel(answers.deployment)} when live checks run.` : "Context indexing requires companion or hosted provider sync."
       ),
       codeGraph: createActivationLane(
         hasCompanion ? "queued" : "skipped",
@@ -1360,7 +1374,7 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
     manifest.dayZeroCorpus = createDayZeroCorpusReport(
       "skipped",
       [],
-      "Runtime-only profile skipped Hosted MCP config and hosted document sync."
+      "Runtime-only profile skipped MCP config and document sync."
     );
     updateActivationManifest(manifest);
     return;
@@ -1370,7 +1384,7 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
     manifest.dayZeroCorpus = createDayZeroCorpusReport(
       "skipped",
       documents2,
-      "Skipped because hosted validation was disabled with --skip-test."
+      `Skipped because ${getDeploymentLabel(answers.deployment)} validation was disabled with --skip-test.`
     );
     updateActivationManifest(manifest);
     return;
@@ -1379,7 +1393,7 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
     manifest.dayZeroCorpus = createDayZeroCorpusReport(
       "skipped",
       [],
-      "Skipped because no live hosted API key was available."
+      `Skipped because no live ${getDeploymentLabel(answers.deployment)} API key was available.`
     );
     updateActivationManifest(manifest);
     return;
@@ -1389,18 +1403,18 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
     manifest.dayZeroCorpus = createDayZeroCorpusReport(
       "skipped",
       [],
-      "No README or docs Markdown files were found to seed hosted context."
+      `No README or docs Markdown files were found to seed ${getDeploymentLabel(answers.deployment)}.`
     );
     if (manifest.lanes.contextIndex.status === "queued") {
       manifest.lanes.contextIndex = createActivationLane(
         "skipped",
-        "No README or docs Markdown files were found to seed hosted context."
+        `No README or docs Markdown files were found to seed ${getDeploymentLabel(answers.deployment)}.`
       );
     }
     updateActivationManifest(manifest);
     return;
   }
-  const syncTool = "snipara_sync_documents";
+  const syncTool = answers.deployment === "self-hosted" ? "rlm_sync_documents" : "snipara_sync_documents";
   const syncResponse = await callHostedMcp(answers, "tools/call", {
     name: syncTool,
     arguments: {
@@ -1412,18 +1426,18 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
     manifest.dayZeroCorpus = createDayZeroCorpusReport(
       "submitted",
       documents,
-      `Submitted ${documents.length} README/docs files to hosted context for the first day-zero answer pack.`,
+      `Submitted ${documents.length} README/docs files to ${getDeploymentLabel(answers.deployment)} for the first day-zero answer pack.`,
       { tool: syncTool }
     );
     manifest.lanes.contextIndex = createActivationLane(
       "indexing",
-      "Day-zero README/docs corpus submitted to hosted context indexing.",
+      `Day-zero README/docs corpus submitted to ${getDeploymentLabel(answers.deployment)} indexing.`,
       syncTool
     );
     updateActivationManifest(manifest);
     return;
   }
-  const uploadTool = "snipara_upload_document";
+  const uploadTool = answers.deployment === "self-hosted" ? "rlm_upload_document" : "snipara_upload_document";
   const uploadErrors = [];
   for (const document of documents) {
     const uploadResponse = await callHostedMcp(answers, "tools/call", {
@@ -1441,12 +1455,12 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
     manifest.dayZeroCorpus = createDayZeroCorpusReport(
       "submitted",
       documents,
-      `Submitted ${documents.length} README/docs files to hosted context for the first day-zero answer pack.`,
+      `Submitted ${documents.length} README/docs files to ${getDeploymentLabel(answers.deployment)} for the first day-zero answer pack.`,
       { tool: uploadTool }
     );
     manifest.lanes.contextIndex = createActivationLane(
       "indexing",
-      "Day-zero README/docs corpus submitted to hosted context indexing.",
+      `Day-zero README/docs corpus submitted to ${getDeploymentLabel(answers.deployment)} indexing.`,
       uploadTool
     );
   } else {
@@ -1457,13 +1471,96 @@ async function runHostedDayZeroCorpusSync(answers, manifest, enabled) {
       error: detail
     });
     manifest.lanes.contextIndex = failActivationLane(
-      "Hosted day-zero README/docs sync failed; the first answer may need GitHub, companion, or a later sync.",
+      `${getDeploymentLabel(answers.deployment)} day-zero README/docs sync failed; the first answer may need GitHub, companion, or a later sync.`,
       syncTool,
       new Error(detail)
     );
   }
   updateActivationManifest(manifest);
 }
+async function runDayZeroValueProof(answers, manifest, enabled) {
+  const observedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (!enabled || answers.profile === "runtime-only") {
+    manifest.valueProof = {
+      status: "skipped",
+      deployment: answers.deployment,
+      query: manifest.dayZeroQuery.query,
+      detail: "Skipped because live MCP validation was disabled or the profile is runtime-only.",
+      observedAt
+    };
+    updateActivationManifest(manifest);
+    return;
+  }
+  if (answers.apiKeyType === "none" || answers.apiKey.includes("YOUR_")) {
+    manifest.valueProof = {
+      status: "skipped",
+      deployment: answers.deployment,
+      query: manifest.dayZeroQuery.query,
+      detail: "Skipped because no live API key was available.",
+      observedAt
+    };
+    updateActivationManifest(manifest);
+    return;
+  }
+  const queryTool = answers.deployment === "self-hosted" ? "rlm_context_query" : "snipara_context_query";
+  const spinner = ora(`Running ${getDeploymentLabel(answers.deployment)} value proof...`).start();
+  try {
+    const response = await callHostedMcp(answers, "tools/call", {
+      name: queryTool,
+      arguments: {
+        query: manifest.dayZeroQuery.query,
+        max_tokens: 1200,
+        search_mode: "keyword",
+        return_references: true,
+        auto_decompose: false
+      }
+    });
+    if (!response.ok || response.data.error) {
+      const detail = response.ok ? describeJsonRpcError(response.data) : describeHostedHttpFailure(response.status, response.bodyText);
+      throw new Error(detail);
+    }
+    const evidenceChars = extractMcpText(response.data).length;
+    if (evidenceChars === 0) {
+      throw new Error("The MCP query returned no answer content");
+    }
+    manifest.valueProof = {
+      status: "ready",
+      deployment: answers.deployment,
+      query: manifest.dayZeroQuery.query,
+      tool: queryTool,
+      detail: "A non-empty project answer pack was returned from the configured MCP endpoint.",
+      evidence: `answer_pack_chars=${evidenceChars}`,
+      observedAt
+    };
+    spinner.succeed("Value proof ready: Snipara returned a project-grounded answer.");
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "unknown MCP value-proof error";
+    manifest.valueProof = {
+      status: "failed",
+      deployment: answers.deployment,
+      query: manifest.dayZeroQuery.query,
+      tool: queryTool,
+      detail: "The connection succeeded, but the first project answer could not be verified.",
+      observedAt,
+      error: detail.slice(0, 300)
+    };
+    spinner.warn(`Value proof needs attention: ${detail}`);
+  }
+  updateActivationManifest(manifest);
+}
+function extractMcpText(data) {
+  const content = data.result?.content;
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content.map((item) => {
+    if (!item || typeof item !== "object") {
+      return "";
+    }
+    const record = item;
+    return typeof record.text === "string" ? record.text : "";
+  }).filter(Boolean).join("\n");
+}
 function createActivationArtifacts(answers, manifest) {
   const projectBootstrap = buildProjectBootstrap(manifest.localScan);
   writeProjectBootstrap(projectBootstrap);
@@ -1587,14 +1684,14 @@ function shouldInstallDefaultHooks(aiClient) {
 }
 function buildProgram() {
   const program = new Command();
-  program.name("create-snipara").description("Scaffold hosted Snipara MCP config; advanced flags add local helpers").version(VERSION);
+  program.name("create-snipara").description("Connect Snipara Cloud or a self-hosted Snipara Server with a fast proof of value").version(VERSION);
   program.command("init").description("Install and configure Snipara for this project").option("--api-key <key>", "Snipara API key").option("--slug <slug>", "Project slug").option("--project-id <id>", "Project ID").option(
     "--client <client>",
     "AI client: claude-code, cursor, kimi, codex, gemini, mistral, chatgpt, vscode, continue, claude-desktop, other"
   ).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("--starter", "Mark this run as a starter activation and print dashboard-first guidance").option("--json", "Print a machine-readable activation summary after setup").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("--deployment <deployment>", "Deployment: hosted or self-hosted").option("--self-hosted", "Use an existing self-hosted Snipara MCP server").option("--server-url <url>", "Self-hosted MCP endpoint URL").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 MCP connection and value-proof checks").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("--json", "Print a machine-readable activation summary after setup").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);
   });
@@ -1605,7 +1702,7 @@ function buildProgram() {
     printBanner();
     await runDoctor(options);
   });
-  program.command("repair").description("Rebuild local Snipara config and re-run validation").option("--api-key <key>", "Snipara API key override").option("--slug <slug>", "Project slug override").option("--project-id <id>", "Project ID override").option("--profile <profile>", "Target install profile").option("--with-hooks", "Force hook generation").option("--with-runtime", "Force Snipara Sandbox server/config").option("--with-mcp", "Force MCP config").option("--with-companion", "Force companion pack generation").option("--with-orchestrator", "Install optional snipara-orchestrator package").action(async (options) => {
+  program.command("repair").description("Rebuild local Snipara config and re-run validation").option("--api-key <key>", "Snipara API key override").option("--slug <slug>", "Project slug override").option("--project-id <id>", "Project ID override").option("--profile <profile>", "Target install profile").option("--deployment <deployment>", "Deployment: hosted or self-hosted").option("--self-hosted", "Use an existing self-hosted Snipara MCP server").option("--server-url <url>", "Self-hosted MCP endpoint URL").option("--with-hooks", "Force hook generation").option("--with-runtime", "Force Snipara Sandbox server/config").option("--with-mcp", "Force MCP config").option("--with-companion", "Force companion pack generation").option("--with-orchestrator", "Install optional snipara-orchestrator package").action(async (options) => {
     printBanner();
     await runRepair(options);
   });
@@ -1635,7 +1732,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("--starter", "Mark this run as a starter activation and print dashboard-first guidance").option("--json", "Print a machine-readable activation summary after setup").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("--deployment <deployment>", "Deployment: hosted or self-hosted").option("--self-hosted", "Use an existing self-hosted Snipara MCP server").option("--server-url <url>", "Self-hosted MCP endpoint URL").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 MCP connection and value-proof checks").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("--json", "Print a machine-readable activation summary after setup").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();
@@ -1719,6 +1816,8 @@ function parseInitOptionsFromArgv(args) {
     "--project-id": "projectId",
     "--client": "client",
     "--profile": "profile",
+    "--deployment": "deployment",
+    "--server-url": "serverUrl",
     "--github-path": "githubPath"
   };
   const booleanFlags = {
@@ -1732,6 +1831,7 @@ function parseInitOptionsFromArgv(args) {
     "--runtime-only": "runtimeOnly",
     "--full": "full",
     "--Full": "full",
+    "--self-hosted": "selfHosted",
     "--github": "github",
     "--skip-github": "skipGithub",
     "--starter": "starter",
@@ -1797,6 +1897,7 @@ async function runInit(options) {
     activationScan
   );
   await runHostedDayZeroCorpusSync(answers, activationManifest, !normalizedOptions.skipTest);
+  await runDayZeroValueProof(answers, activationManifest, !normalizedOptions.skipTest);
   runLocalSourceActivation(answers, activationManifest);
   createActivationArtifacts(answers, activationManifest);
   printSuccess(answers, validationReport, activationManifest);
@@ -1816,14 +1917,17 @@ function buildActivationJsonSummary(manifest, validation) {
   const laneEntries = Object.entries(manifest.lanes);
   const failedLanes = laneEntries.filter(([, lane]) => lane.status === "failed").map(([name]) => name);
   const pendingLanes = laneEntries.filter(([, lane]) => lane.status === "queued" || lane.status === "indexing").map(([name]) => name);
-  const activationStatus = failedLanes.length > 0 ? "partial" : pendingLanes.length > 0 ? "partial" : "complete";
+  const activationStatus = failedLanes.length > 0 || manifest.valueProof.status === "failed" ? "partial" : pendingLanes.length > 0 ? "partial" : "complete";
   return {
     ok: true,
     activationStatus,
     activationId: manifest.activationId,
     projectSlug: manifest.projectSlug,
+    deployment: manifest.deployment,
+    serverUrl: manifest.serverUrl,
     aiClient: manifest.aiClient,
     profile: validation.profile,
+    valueProof: manifest.valueProof,
     artifacts: manifest.artifacts,
     lanes: Object.fromEntries(
       laneEntries.map(([name, lane]) => [
@@ -1981,8 +2085,8 @@ function printBanner() {
 \u2551                                                                       \u2551
 \u2551   ${chalk.bold("Snipara")} - Context + Memory onboarding                            \u2551
 \u2551                                                                       \u2551
-\u2551   \u2022 Hosted MCP for LLM agents                                         \u2551
-\u2551   \u2022 Free account path with hosted context and reviewed memory         \u2551
+\u2551   \u2022 Cloud or self-hosted MCP for LLM agents                           \u2551
+\u2551   \u2022 First project-grounded answer in minutes                          \u2551
 \u2551   \u2022 First grounded answer before local workflow setup                 \u2551
 \u2551   \u2022 API / SDK for product integrations                                \u2551
 \u2551   \u2022 Optional advanced companion, hooks, and Snipara Sandbox helpers   \u2551
@@ -2014,17 +2118,26 @@ async function gatherConfiguration(options) {
     detectedProjectId = existingConfig.projectId || "";
   }
   const initialProfile = resolveRequestedProfile(options);
-  const providedApiKey = options.apiKey?.trim();
-  if (providedApiKey && !isManualApiKey(providedApiKey)) {
-    throw new Error(manualApiKeyValidationMessage());
-  }
-  if (providedApiKey) {
+  const initialDeployment = resolveRequestedDeployment(options);
+  const initialServerUrl = normalizeMcpEndpoint(
+    options.serverUrl || process.env.SNIPARA_MCP_URL || getExistingConfig()?.serverUrl || "http://localhost:8000/mcp/local"
+  );
+  const defaultProjectSlug = options.slug || detectedSlug || (initialDeployment === "self-hosted" ? extractSlugFromMcpEndpoint(initialServerUrl) || "local" : "");
+  const optionApiKey = options.apiKey?.trim();
+  const environmentApiKey = options.yes ? initialDeployment === "self-hosted" ? process.env.SNIPARA_LOCAL_API_KEY?.trim() || process.env.SNIPARA_API_KEY?.trim() : process.env.SNIPARA_API_KEY?.trim() : void 0;
+  const providedApiKey = optionApiKey || environmentApiKey;
+  if (providedApiKey && !isValidApiKey(providedApiKey, initialDeployment)) {
+    throw new Error(manualApiKeyValidationMessage(initialDeployment));
+  }
+  if (optionApiKey) {
     warnApiKeyCliExposure();
   }
   if (options.yes) {
     return buildAnswersFromProfile({
-      projectSlug: options.slug || detectedSlug || "my-project",
+      projectSlug: defaultProjectSlug || "my-project",
       projectId: options.projectId || detectedProjectId,
+      deployment: initialDeployment,
+      serverUrl: initialServerUrl,
       apiKey: providedApiKey || "YOUR_API_KEY_HERE",
       apiKeyType: providedApiKey ? "api" : "none",
       profile: initialProfile,
@@ -2035,13 +2148,45 @@ async function gatherConfiguration(options) {
       withOrchestrator: !!options.withOrchestrator,
       skipHooks: !!options.skipHooks,
       configureGitHub: Boolean(
-        (options.github || options.githubPath) && detectedGitRepo && !options.skipGithub
+        initialDeployment === "hosted" && (options.github || options.githubPath) && detectedGitRepo && !options.skipGithub
       ),
       githubRepo: detectedGitRepo || void 0,
       githubPath: options.githubPath
     });
   }
   const response = await prompts([
+    {
+      type: showAdvancedPrompts ? "select" : null,
+      name: "deployment",
+      message: "Where should this project connect?",
+      initial: initialDeployment === "self-hosted" ? 1 : 0,
+      choices: [
+        {
+          title: "Snipara Cloud (fastest first experience)",
+          value: "hosted",
+          description: "Hosted MCP, account signup, and automatic day-zero proof"
+        },
+        {
+          title: "Existing self-hosted Snipara Server",
+          value: "self-hosted",
+          description: "Your MCP endpoint, operator API key, and local data boundary"
+        }
+      ]
+    },
+    {
+      type: (_, values) => initialDeployment === "self-hosted" || values.deployment === "self-hosted" ? "text" : null,
+      name: "serverUrl",
+      message: "Self-hosted MCP endpoint URL:",
+      initial: options.serverUrl || process.env.SNIPARA_MCP_URL || initialServerUrl,
+      validate: (value) => {
+        try {
+          normalizeMcpEndpoint(value);
+          return true;
+        } catch {
+          return "Enter a valid http:// or https:// MCP endpoint URL";
+        }
+      }
+    },
     {
       type: showAdvancedPrompts ? "select" : null,
       name: "profile",
@@ -2053,7 +2198,7 @@ async function gatherConfiguration(options) {
       type: "text",
       name: "projectSlug",
       message: "Project slug:",
-      initial: options.slug || detectedSlug || "",
+      initial: defaultProjectSlug,
       validate: (value) => value.length > 0 ? true : "Project slug is required (for example my-project)"
     },
     {
@@ -2065,8 +2210,18 @@ async function gatherConfiguration(options) {
     {
       type: (_, values) => values.profile === "runtime-only" || providedApiKey ? null : "select",
       name: "apiKeyType",
-      message: "How do you want to add your Snipara API key?",
-      choices: [
+      message: (_, values) => values.deployment === "self-hosted" || initialDeployment === "self-hosted" ? "How do you want to add the self-hosted operator API key?" : "How do you want to add your Snipara API key?",
+      choices: (_, values) => values.deployment === "self-hosted" || initialDeployment === "self-hosted" ? [
+        {
+          title: "I have an operator API key",
+          value: "api",
+          description: "Use the X-API-Key configured for your server"
+        },
+        {
+          title: "I'll add the API key later",
+          value: "skip"
+        }
+      ] : [
         {
           title: "I have an API key",
           value: "api",
@@ -2087,7 +2242,10 @@ async function gatherConfiguration(options) {
       type: (_, values) => values.profile === "runtime-only" ? null : values.apiKeyType === "api" ? "text" : null,
       name: "apiKey",
       message: (_, values) => values.apiKeyType === "api" ? "Enter your Snipara API key:" : "Enter your API key:",
-      validate: (value) => isManualApiKey(value) ? true : manualApiKeyValidationMessage()
+      validate: (value, values) => {
+        const deployment = normalizeDeployment(values.deployment) || initialDeployment;
+        return isValidApiKey(value, deployment) ? true : manualApiKeyValidationMessage(deployment);
+      }
     },
     {
       type: "select",
@@ -2126,11 +2284,15 @@ async function gatherConfiguration(options) {
       initial: options.githubPath || ""
     }
   ]);
+  const selectedDeployment = normalizeDeployment(response.deployment) || initialDeployment;
+  const selectedServerUrl = normalizeMcpEndpoint(
+    options.serverUrl || response.serverUrl || initialServerUrl
+  );
   let apiKey = providedApiKey;
   let apiKeyType = response.profile === "runtime-only" ? "none" : providedApiKey ? "api" : "none";
   let signupResult = null;
   if (!apiKey && response.profile !== "runtime-only") {
-    if (response.apiKeyType === "signup") {
+    if (response.apiKeyType === "signup" && selectedDeployment === "hosted") {
       signupResult = await handleSignup({
         projectHint: response.projectSlug,
         repoHint: detectedGitRepo?.fullName
@@ -2148,6 +2310,8 @@ async function gatherConfiguration(options) {
   const answers = buildAnswersFromProfile({
     projectSlug: signupResult?.projectSlug || response.projectSlug,
     projectId: signupResult?.projectId || response.projectId || options.projectId || "",
+    deployment: selectedDeployment,
+    serverUrl: selectedServerUrl,
     apiKey: apiKey || "",
     apiKeyType,
     profile: response.profile || initialProfile,
@@ -2158,7 +2322,7 @@ async function gatherConfiguration(options) {
     withOrchestrator: Boolean(options.withOrchestrator || response.installOrchestrator),
     skipHooks: !!options.skipHooks || !(typeof response.installHooks === "boolean" ? response.installHooks : shouldInstallDefaultHooks(requestedClient || response.aiClient || detectedClient)),
     configureGitHub: Boolean(
-      (response.configureGitHub || options.github || options.githubPath) && detectedGitRepo && !options.skipGithub
+      selectedDeployment === "hosted" && (response.configureGitHub || options.github || options.githubPath) && detectedGitRepo && !options.skipGithub
     ),
     githubRepo: detectedGitRepo || void 0,
     githubPath: response.githubPath || options.githubPath
@@ -2226,6 +2390,33 @@ function resolveRequestedProfile(options) {
   }
   return "hosted-only";
 }
+function normalizeDeployment(value) {
+  if (value === "hosted" || value === "self-hosted") {
+    return value;
+  }
+  return null;
+}
+function resolveRequestedDeployment(options) {
+  if (options.selfHosted || options.serverUrl) {
+    return "self-hosted";
+  }
+  if (normalizeDeployment(options.deployment)) {
+    return normalizeDeployment(options.deployment);
+  }
+  const existingEndpoint = getExistingConfig()?.serverUrl;
+  return existingEndpoint && !existingEndpoint.startsWith(API_URL) ? "self-hosted" : "hosted";
+}
+function normalizeMcpEndpoint(value) {
+  const normalized = value.trim().replace(/\/+$/, "");
+  const parsed = new URL(normalized);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("MCP endpoint must use http:// or https://");
+  }
+  return normalized;
+}
+function getDeploymentLabel(deployment) {
+  return deployment === "self-hosted" ? "self-hosted Snipara Server" : "Snipara Cloud";
+}
 function isInstallProfile(value) {
   return ["hosted-only", "hosted-companion", "full-stack", "runtime-only"].includes(value);
 }
@@ -2321,6 +2512,8 @@ function buildAnswersFromProfile(input) {
   return {
     projectSlug: input.projectSlug,
     projectId: input.projectId,
+    deployment: input.deployment,
+    serverUrl: input.deployment === "hosted" ? `${API_URL}/mcp/${encodeURIComponent(input.projectSlug)}` : normalizeMcpEndpoint(input.serverUrl),
     apiKey: input.apiKey || "YOUR_API_KEY_HERE",
     apiKeyType: input.profile === "runtime-only" ? "none" : input.apiKeyType,
     profile: input.profile,
@@ -2495,17 +2688,20 @@ function runDemo(options) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function isManualApiKey(value) {
+function isValidApiKey(value, deployment) {
   const trimmed = value.trim();
+  if (deployment === "self-hosted") {
+    return trimmed.length >= 8 && !/\s/.test(trimmed);
+  }
   return trimmed.startsWith("snp-");
 }
-function manualApiKeyValidationMessage() {
-  return "API key should start with snp-";
+function manualApiKeyValidationMessage(deployment = "hosted") {
+  return deployment === "self-hosted" ? "Self-hosted API key should be at least 8 characters and contain no spaces" : "API key should start with snp-";
 }
 function warnApiKeyCliExposure() {
   console.log(
     chalk.yellow(
-      "   \u26A0\uFE0F  --api-key can be exposed in shell history or process lists. Prefer SNIPARA_API_KEY or the interactive prompt for future runs."
+      "   \u26A0\uFE0F  --api-key can be exposed in shell history or process lists. Prefer SNIPARA_API_KEY, SNIPARA_LOCAL_API_KEY, or the interactive prompt for future runs."
     )
   );
 }
@@ -2788,7 +2984,7 @@ function readExistingCorrelationSessionId() {
 }
 function getCorrelationSessionId(answers) {
   const existing = normalizeCorrelationSessionId(answers.correlationSessionId) || readExistingCorrelationSessionId();
-  const sessionId = existing || `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const sessionId = existing || `sess_${Date.now()}_${randomUUID().replace(/-/g, "").slice(0, 12)}`;
   answers.correlationSessionId = sessionId;
   return sessionId;
 }
@@ -2800,7 +2996,11 @@ async function createClaudeCodeConfig(answers) {
     return;
   }
   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.green(
+      `   \u2713 Project .mcp.json contains the ${getDeploymentLabel(answers.deployment)} MCP server`
+    )
+  );
   console.log(chalk.dim("   Claude Code loads project-scoped MCP servers from .mcp.json."));
   console.log(
     chalk.dim(
@@ -2921,8 +3121,14 @@ function writeIfMissing(filePath, content, label) {
   fs.writeFileSync(filePath, content);
   console.log(chalk.green(`   Created ${label}`));
 }
+function buildMcpEndpoint(answers) {
+  if (answers.deployment === "self-hosted") {
+    return answers.serverUrl;
+  }
+  return `${API_URL}/mcp/${encodeURIComponent(answers.projectSlug)}`;
+}
 function buildHostedMcpEndpoint(answers) {
-  return `${API_URL}/mcp/${answers.projectSlug}`;
+  return buildMcpEndpoint(answers);
 }
 function writeAgentSkillPackTemplates(skillsDir, answers) {
   const skills = buildSniparaSkillPackTemplates(answers);
@@ -3874,15 +4080,19 @@ async function updateEnvFiles(answers) {
   const envPath = path.join(process.cwd(), ".env");
   let envVars = "";
   let envExampleVars = "";
-  if (answers.apiKeyType !== "none") {
+  if (answers.profile !== "runtime-only") {
     envVars += `
 # Snipara Configuration
+SNIPARA_DEPLOYMENT=${answers.deployment}
+SNIPARA_MCP_URL=${answers.serverUrl}
 SNIPARA_API_KEY=${answers.apiKey.includes("YOUR_") ? "your_api_key_here" : answers.apiKey}
 SNIPARA_PROJECT_SLUG=${answers.projectSlug}
 ${answers.projectId ? `SNIPARA_PROJECT_ID=${answers.projectId}` : ""}
 `.trim();
     envExampleVars += `
 # Snipara Configuration
+SNIPARA_DEPLOYMENT=${answers.deployment}
+SNIPARA_MCP_URL=${answers.serverUrl}
 SNIPARA_API_KEY=your_api_key_here
 SNIPARA_PROJECT_SLUG=${answers.projectSlug || "your_project_slug"}
 ${answers.projectId ? `SNIPARA_PROJECT_ID=${answers.projectId}` : "SNIPARA_PROJECT_ID=your_project_id"}
@@ -3907,10 +4117,14 @@ ${llmVarName}=your_${answers.llmProvider}_api_key_here`;
   }
   if (envExampleVars && fs.existsSync(envExamplePath)) {
     const content = fs.readFileSync(envExamplePath, "utf-8");
-    if (!content.includes("SNIPARA_API_KEY") && !content.includes("SNIPARA_PROJECT_SLUG")) {
+    const missingLines = envExampleVars.split("\n").filter((line) => {
+      const match = line.match(/^([A-Z0-9_]+)=/);
+      return Boolean(match && !content.includes(`${match[1]}=`));
+    });
+    if (missingLines.length > 0) {
       fs.appendFileSync(envExamplePath, `
 
-${envExampleVars}
+${missingLines.join("\n")}
 `);
       console.log(chalk.green("   \u2713 Updated .env.example"));
     }
@@ -3921,16 +4135,26 @@ ${envExampleVars}
   const targetEnvPath = fs.existsSync(envLocalPath) ? envLocalPath : envPath;
   if (fs.existsSync(targetEnvPath)) {
     const content = fs.readFileSync(targetEnvPath, "utf-8");
-    if (!content.includes("SNIPARA_API_KEY") && !answers.apiKey.includes("YOUR_")) {
+    const missingLines = envVars.split("\n").filter((line) => {
+      const match = line.match(/^([A-Z0-9_]+)=/);
+      if (!match) {
+        return false;
+      }
+      if (match[1] === "SNIPARA_API_KEY") {
+        return !content.includes("SNIPARA_API_KEY=") && !answers.apiKey.includes("YOUR_");
+      }
+      return !content.includes(`${match[1]}=`);
+    });
+    if (missingLines.length > 0) {
       fs.appendFileSync(targetEnvPath, `
 
-${envVars}
+${missingLines.join("\n")}
 `);
       console.log(chalk.green(`   \u2713 Updated ${path.basename(targetEnvPath)}`));
     }
     return;
   }
-  if (!answers.apiKey.includes("YOUR_") || answers.llmApiKey) {
+  if (!answers.apiKey.includes("YOUR_") && answers.profile !== "runtime-only" || answers.llmApiKey) {
     fs.writeFileSync(targetEnvPath, envVars + "\n");
     console.log(chalk.green(`   \u2713 Created ${path.basename(targetEnvPath)}`));
   }
@@ -3946,7 +4170,7 @@ async function createCompanionConfig(answers) {
   const workspaceConfig = {
     ...existingWorkspaceConfig,
     apiKey: answers.apiKey,
-    apiUrl: API_URL,
+    apiUrl: answers.deployment === "hosted" ? API_URL : answers.serverUrl,
     projectId: answers.projectId || answers.projectSlug,
     sessionId: getCorrelationSessionId(answers),
     client: getAutomationClientId(answers.aiClient)
@@ -3991,7 +4215,7 @@ async function installLocalCodeOverlayHooks(answers) {
   }
 }
 async function syncRemoteAutomationClient(answers, options) {
-  if (!options.enabled || answers.apiKeyType === "none" || !answers.apiKey || answers.apiKey.includes("YOUR_") || !answers.projectSlug) {
+  if (answers.deployment !== "hosted" || !options.enabled || answers.apiKeyType === "none" || !answers.apiKey || answers.apiKey.includes("YOUR_") || !answers.projectSlug) {
     return;
   }
   const automationClient = getAutomationClientId(answers.aiClient);
@@ -4035,7 +4259,7 @@ 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.",
+    firstSuccessState: "The configured Snipara endpoint connected, local workspace context was seeded, and a First Work Brief is ready for the next agent session.",
     mustNotDuplicate: [
       "Local source scan heuristics",
       "First Work Brief generation",
@@ -4266,6 +4490,11 @@ function getCompanionCommands(answers) {
       title: "Refresh local source context",
       command: `${COMPANION_NPX_COMMAND} source sync --json`,
       purpose: "Refresh the local snapshot, document dry-run, and code overlay cache after files change."
+    },
+    {
+      title: "Generate a reviewable Project Brief",
+      command: `${COMPANION_NPX_COMMAND} docs bootstrap --preview`,
+      purpose: "Preview a safe, evidence-linked project brief when the repository has little or no documentation; apply it only after review."
     }
   ] : [];
   const businessOnboardingCommands = answers.installCompanion ? [
@@ -4472,6 +4701,8 @@ function getClientAutomationCommand(client) {
 function buildClientPackMarkdown(answers, commands, guidance) {
   const clientName = getClientDisplayName(answers.aiClient);
   const automationCommand = getClientAutomationCommand(answers.aiClient);
+  const deploymentLabel = getDeploymentLabel(answers.deployment);
+  const toolNamespace = answers.deployment === "self-hosted" ? "rlm_*" : "snipara_*";
   const bootstrapCommand = commands.find(
     (command) => command.title === "Bootstrap local companion"
   );
@@ -4491,9 +4722,9 @@ Use \`AGENTS.md\` as the shared source of agent behavior, then apply the client-
 - 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.
+First Work Brief generation, memory-candidate extraction, or MCP config semantics.
 
-## Hosted MCP
+## ${deploymentLabel}
 
 - Endpoint: \`${buildHostedMcpEndpoint(answers)}\`
 - Auth: \`SNIPARA_API_KEY\` from the environment or local client secret store
@@ -4506,7 +4737,7 @@ ${getClientConfigArtifacts(answers.aiClient).map((item) => `- \`${item}\``).join
 ## Recommended Setup
 
 ${bootstrapCommand ? `1. Bootstrap companion: \`${bootstrapCommand.command}\`` : `1. Bootstrap companion with \`${COMPANION_NPX_COMMAND} init\`.`}
-2. Confirm the client can list or call the \`snipara_*\` MCP tools.
+2. Confirm the client can list or call the \`${toolNamespace}\` MCP tools.
 3. Keep exact edits, tests, and dirty working-tree checks local; use Snipara for memory, source truth, and indexed code graph context.
 ${automationCommand ? `4. For generated local automations, run \`${automationCommand}\` when that client exposes usable automation files.` : "4. This client is treated as MCP-first; no local hook surface is assumed."}
 
@@ -4537,10 +4768,11 @@ async function createCompanionPack(answers) {
   const guidance = [UNIVERSAL_CLIENT_GUIDANCE, ...getClientGuidance(answers.aiClient)];
   const detection = detectEnvironment();
   const clientPackFilename = getClientPackFilename(answers.aiClient);
+  const deploymentLabel = getDeploymentLabel(answers.deployment);
   fs.mkdirSync(packDir, { recursive: true });
   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.
+This project uses ${deploymentLabel} as a 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.
 
@@ -4552,7 +4784,7 @@ The activation doctrine is: one shared activation engine, multiple entry points.
 - AI client: \`${answers.aiClient}\`
 - Client pack: \`${clientPackFilename}\`
 - Installed local companion: \`${answers.installCompanion ? "yes" : "no"}\`
-- Generated hosted MCP config: \`${answers.profile !== "runtime-only" ? "yes" : "no"}\`
+- Generated ${deploymentLabel} MCP config: \`${answers.profile !== "runtime-only" ? "yes" : "no"}\`
 - Installed local snipara-mcp package: \`${answers.installMcp ? "yes" : "no"}\`
 - Installed Snipara Sandbox: \`${answers.installRuntime ? "yes" : "no"}\`
 - Installed Snipara Orchestrator: \`${answers.installOrchestrator ? "yes" : "no"}\`
@@ -4612,15 +4844,25 @@ Refresh after file changes:
 
 \`${COMPANION_NPX_COMMAND} source sync --json\`
 
+If the folder has little or no documentation, preview a Project Brief before writing it:
+
+\`${COMPANION_NPX_COMMAND} docs bootstrap --preview\`
+
+After reviewing the generated brief, apply and index it:
+
+\`${COMPANION_NPX_COMMAND} docs bootstrap --apply\`
+
+\`${COMPANION_NPX_COMMAND} source sync --apply --reindex\`
+
 Inspect local drift:
 
 \`${COMPANION_NPX_COMMAND} source status --json\`` : `This setup did not install snipara-companion. Enable it before local source activation:
 
 \`${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
-provider approval when a team wants shared hosted code context.
+GitHub automation remains a Cloud-only option after first value: it gives Snipara a canonical
+hosted repository sync and PR Answer Packs. In self-hosted mode, keep source activation local and
+do not send repository data to the Cloud unless the user explicitly starts a separate Cloud setup.
 
 ## GitHub PR Answer Packs
 
@@ -4962,10 +5204,10 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
     detail: detection.files.sniparaSkillPack ? ".snipara/templates/skills contains the Snipara skill pack" : "Snipara skill pack missing from .snipara/templates/skills"
   });
   if (targetClient === "codex") {
-    checks.push(getCodexConfigCheck());
+    checks.push(getCodexConfigCheck(effectiveAnswers));
   }
   if (targetClient === "mistral") {
-    checks.push(getMistralConfigCheck());
+    checks.push(getMistralConfigCheck(effectiveAnswers));
   }
   checks.push({
     name: "env_files",
@@ -4995,7 +5237,7 @@ async function runValidation(answers, includeHostedCheck, options = {}) {
     checks.push({
       name: "hosted_connection",
       status: "warn",
-      detail: "Skipped hosted connectivity test because no live API key was available"
+      detail: `Skipped ${getDeploymentLabel(answers.deployment)} connectivity test because no live API key was available`
     });
   }
   for (const check of checks) {
@@ -5014,7 +5256,7 @@ function writeDoctorReport(report) {
   fs.writeFileSync(path.join(reportDir, "doctor.json"), JSON.stringify(report, null, 2) + "\n");
   console.log(chalk.green("   \u2713 Wrote .snipara/companion/doctor.json"));
 }
-function getCodexConfigCheck() {
+function getCodexConfigCheck(answers) {
   const candidates = [
     {
       label: ".codex/config.toml",
@@ -5054,8 +5296,8 @@ function getCodexConfigCheck() {
   const nonSniparaBearerEnvVars = configuredBearerEnvVars.filter(
     (candidate) => candidate.value !== "SNIPARA_API_KEY"
   );
-  const hasHostedEndpoint = present.some(
-    (candidate) => candidate.content.includes(`${API_URL}/mcp/`)
+  const hasConfiguredEndpoint = present.some(
+    (candidate) => candidate.content.includes(buildMcpEndpoint(answers))
   );
   const labels = present.map((candidate) => candidate.label).join(", ");
   if (nonSniparaBearerEnvVars.length > 0) {
@@ -5066,20 +5308,20 @@ function getCodexConfigCheck() {
       detail: `Codex config uses a non-Snipara bearer env var (${details}); use SNIPARA_API_KEY and restart Codex`
     };
   }
-  if (!usesSniparaEnv || !hasHostedEndpoint) {
+  if (!usesSniparaEnv || !hasConfiguredEndpoint) {
     return {
       name: "codex_config",
       status: "warn",
-      detail: `Codex config found in ${labels}, but expected hosted MCP endpoint plus bearer_token_env_var = "SNIPARA_API_KEY"`
+      detail: `Codex config found in ${labels}, but expected the configured ${getDeploymentLabel(answers.deployment)} endpoint plus bearer_token_env_var = "SNIPARA_API_KEY"`
     };
   }
   return {
     name: "codex_config",
     status: "pass",
-    detail: `Codex config uses hosted MCP and SNIPARA_API_KEY (${labels}); restart Codex after config changes`
+    detail: `Codex config uses ${getDeploymentLabel(answers.deployment)} and SNIPARA_API_KEY (${labels}); restart Codex after config changes`
   };
 }
-function getMistralConfigCheck() {
+function getMistralConfigCheck(answers) {
   const candidates = [
     {
       label: ".vibe/config.toml",
@@ -5105,24 +5347,24 @@ function getMistralConfigCheck() {
       detail: "No Mistral Vibe config found; use .snipara/templates/mistral-vibe-config.toml or add Snipara as a Le Chat Custom MCP Connector"
     };
   }
-  const hasHostedEndpoint = present.some(
-    (candidate) => candidate.content.includes(`${API_URL}/mcp/`)
+  const hasConfiguredEndpoint = present.some(
+    (candidate) => candidate.content.includes(buildMcpEndpoint(answers))
   );
   const hasSniparaEnv = present.some(
     (candidate) => candidate.content.includes('api_key_env = "SNIPARA_API_KEY"')
   );
   const labels = present.map((candidate) => candidate.label).join(", ");
-  if (!hasHostedEndpoint || !hasSniparaEnv) {
+  if (!hasConfiguredEndpoint || !hasSniparaEnv) {
     return {
       name: "mistral_config",
       status: "warn",
-      detail: `Mistral config found in ${labels}, but expected hosted MCP endpoint plus api_key_env = "SNIPARA_API_KEY"`
+      detail: `Mistral config found in ${labels}, but expected the configured ${getDeploymentLabel(answers.deployment)} endpoint plus api_key_env = "SNIPARA_API_KEY"`
     };
   }
   return {
     name: "mistral_config",
     status: "pass",
-    detail: `Mistral Vibe config uses hosted MCP and SNIPARA_API_KEY (${labels}); restart Vibe after config changes`
+    detail: `Mistral Vibe config uses ${getDeploymentLabel(answers.deployment)} and SNIPARA_API_KEY (${labels}); restart Vibe after config changes`
   };
 }
 function printDoctorReport(detection, report) {
@@ -5144,7 +5386,8 @@ function printDoctorReport(detection, report) {
   console.log("");
 }
 async function testHostedConnection(answers) {
-  const spinner = ora("Connecting to Snipara Hosted MCP...").start();
+  const deploymentLabel = getDeploymentLabel(answers.deployment);
+  const spinner = ora(`Connecting to ${deploymentLabel}...`).start();
   try {
     const toolsResponse = await callHostedMcp(answers, "tools/list", {});
     if (!toolsResponse.ok) {
@@ -5167,7 +5410,9 @@ async function testHostedConnection(answers) {
         }
       ];
     }
-    spinner.succeed("Connected to Snipara Hosted MCP.");
+    spinner.succeed(
+      answers.deployment === "hosted" ? "Connected to Snipara Hosted MCP." : `Connected to ${deploymentLabel}.`
+    );
     const toolNames = extractMcpToolNames(toolsResponse.data);
     const hasSniparaTools = toolNames.some((name) => name.startsWith("snipara_"));
     const advertisesLegacyTools = toolNames.some((name) => name.startsWith("rlm_"));
@@ -5179,29 +5424,32 @@ async function testHostedConnection(answers) {
       },
       {
         name: "hosted_snipara_tools",
-        status: hasSniparaTools ? "pass" : "warn",
-        detail: hasSniparaTools ? "snipara_* tools are advertised by Hosted MCP" : "tools/list succeeded, but expected snipara_* tools were not detected"
+        status: hasSniparaTools || advertisesLegacyTools ? "pass" : "warn",
+        detail: hasSniparaTools || advertisesLegacyTools ? `${toolNames.filter((name) => name.startsWith("snipara_") || name.startsWith("rlm_")).length} Snipara MCP tools are advertised` : "tools/list succeeded, but no Snipara tool namespace was detected"
       },
       {
         name: "hosted_legacy_tools_hidden",
-        status: advertisesLegacyTools ? "warn" : "pass",
-        detail: advertisesLegacyTools ? "tools/list still advertises legacy rlm_* tools; update or redeploy the hosted MCP surface" : "tools/list does not advertise legacy rlm_* duplicates"
+        status: answers.deployment === "hosted" && advertisesLegacyTools ? "warn" : "pass",
+        detail: answers.deployment === "hosted" && advertisesLegacyTools ? "Hosted MCP still advertises legacy rlm_* tools; update or redeploy the hosted surface" : answers.deployment === "self-hosted" ? "Self-hosted deployment may expose the public rlm_* compatibility namespace" : "Hosted MCP does not advertise legacy rlm_* duplicates"
       }
     ];
-    const settingsTool = "snipara_settings";
+    if (answers.deployment === "self-hosted") {
+      checks.push(...await testSelfHostedCapabilities(answers));
+    }
+    const settingsTool = answers.deployment === "self-hosted" ? "rlm_settings" : "snipara_settings";
     const settingsResponse = await callHostedMcp(answers, "tools/call", {
       name: settingsTool,
       arguments: {}
     });
     if (settingsResponse.ok && !settingsResponse.data.error) {
       checks.push({
-        name: "hosted_settings",
+        name: "deployment_settings",
         status: "pass",
         detail: `${settingsTool} tool call succeeded`
       });
     } else {
       checks.push({
-        name: "hosted_settings",
+        name: "deployment_settings",
         status: "warn",
         detail: settingsResponse.ok ? describeJsonRpcError(settingsResponse.data) : describeHostedHttpFailure(settingsResponse.status, settingsResponse.bodyText)
       });
@@ -5213,7 +5461,40 @@ async function testHostedConnection(answers) {
       {
         name: "hosted_connection",
         status: "warn",
-        detail: "Could not reach Snipara Hosted MCP from this machine"
+        detail: `Could not reach ${deploymentLabel} from this machine`
+      }
+    ];
+  }
+}
+async function testSelfHostedCapabilities(answers) {
+  try {
+    const endpoint = new URL(answers.serverUrl);
+    const response = await fetch(`${endpoint.origin}/capabilities`, {
+      headers: { "X-API-Key": answers.apiKey }
+    });
+    const body = await response.json();
+    if (!response.ok) {
+      return [
+        {
+          name: "self_hosted_contract",
+          status: "warn",
+          detail: `Could not verify /capabilities (HTTP ${response.status})`
+        }
+      ];
+    }
+    return [
+      {
+        name: "self_hosted_contract",
+        status: body.contract === "snipara-server-oss-v2" ? "pass" : "warn",
+        detail: body.contract === "snipara-server-oss-v2" ? "snipara-server-oss-v2 contract verified" : `Unexpected self-hosted contract${body.contract ? `: ${body.contract}` : ""}`
+      }
+    ];
+  } catch {
+    return [
+      {
+        name: "self_hosted_contract",
+        status: "warn",
+        detail: "Self-hosted /capabilities endpoint could not be verified"
       }
     ];
   }
@@ -5228,7 +5509,7 @@ function extractMcpToolNames(data) {
   ).filter(Boolean);
 }
 async function callHostedMcp(answers, method, params) {
-  const response = await fetch(`${API_URL}/mcp/${answers.projectSlug}`, {
+  const response = await fetch(buildMcpEndpoint(answers), {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -5300,8 +5581,24 @@ function printActivationSummary(manifest) {
     `   ${formatActivationStatus(manifest.lanes.connection.status)} Connected - ${manifest.lanes.connection.detail}`
   );
   console.log(`   ${formatActivationStatus(contextLane.status)} Context - ${contextLane.detail}`);
-  console.log(`   ${chalk.dim("\u25CB pending")} First grounded answer`);
-  console.log(chalk.yellow("\n   Activation pending: first grounded answer needed."));
+  if (manifest.valueProof.status === "ready") {
+    console.log(
+      `   ${chalk.green("\u2713 ready")} Value proof - ${manifest.valueProof.detail} (${manifest.valueProof.evidence || "evidence recorded"})`
+    );
+    console.log(chalk.green("\n   Activation ready: First grounded answer verified."));
+  } else if (manifest.valueProof.status === "failed") {
+    console.log(
+      `   ${chalk.red("\u2717 failed")} Value proof - ${manifest.valueProof.error || manifest.valueProof.detail}`
+    );
+    console.log(
+      chalk.yellow(
+        "\n   Activation needs attention: run create-snipara doctor after checking the MCP endpoint."
+      )
+    );
+  } else {
+    console.log(`   ${chalk.dim("\u25CB pending")} First grounded answer`);
+    console.log(chalk.yellow("\n   Activation pending: first grounded answer needed."));
+  }
   console.log(
     chalk.dim(
       `
@@ -5425,6 +5722,7 @@ function detectEnvironment() {
     existingConfig: {
       slug: existingConfig?.slug,
       projectId: existingConfig?.projectId,
+      serverUrl: existingConfig?.serverUrl,
       hasSniparaServer: existingConfig?.hasSniparaServer ?? false,
       hasRuntimeServer: existingConfig?.hasRuntimeServer ?? false
     }
@@ -5433,19 +5731,22 @@ function detectEnvironment() {
 function loadExistingAnswers(options) {
   const detection = detectEnvironment();
   const effectiveProfile = resolveMaintenanceProfile(detection, options.profile);
+  const deployment = resolveRequestedDeployment(options);
   const providedApiKey = options.apiKey?.trim();
-  if (providedApiKey && !isManualApiKey(providedApiKey)) {
-    throw new Error(manualApiKeyValidationMessage());
+  if (providedApiKey && !isValidApiKey(providedApiKey, deployment)) {
+    throw new Error(manualApiKeyValidationMessage(deployment));
   }
   if (providedApiKey) {
     warnApiKeyCliExposure();
   }
-  const envApiKey = readApiKeyFromEnvFiles();
+  const envApiKey = readApiKeyFromEnvFiles(deployment);
   const apiKey = providedApiKey || envApiKey || "YOUR_API_KEY_HERE";
   const apiKeyType = effectiveProfile === "runtime-only" ? "none" : providedApiKey || envApiKey ? "api" : "none";
   return buildAnswersFromProfile({
     projectSlug: options.slug || detection.projectSlug || "my-project",
     projectId: options.projectId || detection.existingConfig.projectId || "",
+    deployment,
+    serverUrl: options.serverUrl || process.env.SNIPARA_MCP_URL || getExistingConfig()?.serverUrl || "http://localhost:8000/mcp/local",
     apiKey,
     apiKeyType,
     profile: effectiveProfile,
@@ -5472,10 +5773,13 @@ function resolveMaintenanceProfile(detection, explicitProfile) {
   }
   return "hosted-only";
 }
-function readApiKeyFromEnvFiles() {
+function readApiKeyFromEnvFiles(deployment = "hosted") {
   const candidates = [".env.local", ".env"];
   for (const file of candidates) {
-    const value = readEnvValueFromFile(file, ["SNIPARA_API_KEY"]);
+    const value = readEnvValueFromFile(
+      file,
+      deployment === "self-hosted" ? ["SNIPARA_LOCAL_API_KEY", "SNIPARA_API_KEY"] : ["SNIPARA_API_KEY"]
+    );
     if (value) {
       return value;
     }
@@ -5782,6 +6086,7 @@ function getExistingConfig() {
     return {
       slug: extractSlugFromMcpEndpoint(sniparaServer?.url) || void 0,
       projectId: readExistingCompanionProjectId(),
+      serverUrl: typeof sniparaServer?.url === "string" ? normalizeMcpEndpoint(sniparaServer.url) : void 0,
       hasSniparaServer: Boolean(sniparaServer),
       hasRuntimeServer: Boolean(runtimeServer)
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-snipara",
-  "version": "2.0.17",
-  "description": "Onboard Snipara Hosted MCP Context + Memory with project bootstrap intelligence and optional local workflows",
+  "version": "2.1.0",
+  "description": "Onboard Snipara Cloud or self-hosted MCP with an automatic project-grounded proof of value",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -39,7 +39,11 @@
     "lm-studio",
     "vscode",
     "continue",
-    "claude-desktop"
+    "claude-desktop",
+    "self-hosted",
+    "snipara-server",
+    "project-intelligence",
+    "persistent-memory"
   ],
   "author": "Snipara",
   "license": "MIT",