enigma-memory 0.1.5 → 0.1.7

package/README.md

@@ -1,48 +1,62 @@
 # Enigma
 
-Enigma is a provider-agnostic AI memory custody and proof layer. It gives a user or enterprise a local canonical memory vault, emits offline-verifiable receipts for Enigma-controlled lifecycle events, and connects that vault to assistants through CLI, MCP, browser, desktop, relay, gateway, and enterprise policy surfaces.
+Enigma Memory is a local-first AI Memory Passport. It gives you one canonical local memory vault, receipt-backed proof for Enigma-controlled events, and MCP connections into assistants such as Claude Desktop, Cursor, Kimi Code, and generic MCP clients.
 
-Current status:
+Start with the package path below. You do not need to understand relay, gateway, mesh, browser, desktop, or hosted infrastructure before trying Enigma locally.
 
-- Local production foundation: CLI, verifier, vault, passport, boundary, MCP server, connector, importer, relay, gateway, enterprise, mesh, browser-extension, and desktop scaffold code exist in this repository.
-- Published npm package: package bins and module entry points are available as `enigma-memory`; use the npm install path below for the simplest onboarding flow.
-- Source-only artifacts: `docs/`, `Dockerfile`, and `docker-compose.yml` live in the source checkout. The package README and CLI help are the package-included install guides; the full runbooks require the repository or hosted docs.
-- Hosted cloud is not included by default. Hosted relay/gateway/cloud operation requires deployment credentials, a domain, TLS, production durable storage, KMS/secrets, monitoring, backups, operator policy, and a completed operator acceptance packet. Local relay/gateway `--state-file` demo state does not satisfy those hosted/BYOC requirements.
-- Cloudflare API/domain/hosting automation is documented but safe-by-default: [`docs/cloudflare-token-and-domain-runbook.md`](docs/cloudflare-token-and-domain-runbook.md) gives the token recipe, Registrar prerequisites, local token storage rule, search/check flow, explicit domain+price purchase gate, Pages deploy gate, custom-domain steps, and post-setup token rotation.
-- Overnight execution plan: [`docs/overnight-build-master-plan.md`](docs/overnight-build-master-plan.md) defines the GPT-5.5/Kimi overnight build cadence, acceptance gates, exact non-claims, and hosted/BYOC blockers.
-- Security and production review artifacts: [`SECURITY.md`](SECURITY.md) defines reporting, safe harbor, disclosure, incident, secret-handling, plaintext-minimization, and proof-boundary policy; [`docs/security-threat-model.md`](docs/security-threat-model.md) maps assets, trust boundaries, controls, residual risks, and verification evidence; [`docs/operator-acceptance-packet.md`](docs/operator-acceptance-packet.md) is required before hosted/BYOC can be called live.
-- Public API reference: [`docs/public-api-reference.md`](docs/public-api-reference.md) lists package exports, CLI bins, MCP tools/resources/prompts, relay/gateway endpoints, importer/capsule APIs, connector profiles, verifier outputs, schemas, and local-vs-hosted boundaries.
-- Local release provenance/SBOM: [`docs/release-provenance-and-sbom.md`](docs/release-provenance-and-sbom.md) documents `npm run provenance:local -- --out ./.enigma/release-provenance.json` as unsigned local package-surface inventory and SHA-256 evidence only, not signed attestation, registry provenance, source-control proof, SLSA/compliance, Docker image, or hosted/cloud deployment evidence.
-- Reviewer packet: [`docs/reviewer-packet.md`](docs/reviewer-packet.md) documents `npm run review:packet -- --out ./.enigma-review-packet --public-site <path-to-_public_site>` as a local hand-review bundle for package, release-audit, provenance, and optional generated public-site evidence; it is not npm publication, live Cloudflare deployment, Docker runtime proof, hosted/BYOC readiness, legal approval, signed provenance, or compliance evidence.
+The package path needs no database, provider credential, cloud credential, npm publishing token, or external account. Hosted cloud and BYOC operation are separate advanced modes that require real deployment credentials, domains, TLS, durable storage, KMS/secrets, monitoring, backups, and operator acceptance.
 
 Enigma does not claim that a closed provider deleted internal data, that model weights forgot, or that provider-native memory disappeared. It proves facts about Enigma-controlled vault state, receipts, checkpoints, and declared boundary operations.
 
-## Install and run locally
+## Install once, use everywhere
 
 Prerequisites:
 
 - Node.js `>=24`
-- No database, package registry account, provider credential, or cloud credential for the local package quickstart
+- No database, package registry account, provider credential, or cloud credential for the local setup path
 - Git only when you choose the advanced source-checkout path
 
-## Quickstart from npm
-
-Use the published package first:
+Use Enigma as a one-time AI Memory Passport setup: install the package, create the local Enigma workspace once, then use the same memory/search/context/verify/connect loop from any supported client.
 
 ```sh
 npm install -g enigma-memory
-enigma quickstart --bundle ./.enigma/bundle.json --overwrite
-enigma doctor
-enigma-relay demo
-enigma-gateway demo
+enigma setup --overwrite
+```
+
+`enigma setup --overwrite` is the safe default. It writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON without printing raw memory plaintext. It does not write Claude, Cursor, Kimi, or other third-party app configs.
+
+To let setup detect installed or already-configured clients and show the connector plan without mutating client configs:
+
+```sh
+enigma setup --client auto --overwrite
+```
+
+`--client auto` selects clients found by connector detection and falls back to the default setup client list when none are present. The setup output lists which clients were selected, which were skipped, and why.
+
+When you are ready to explicitly write connector entries for installed/config-present clients only:
+
+```sh
+enigma setup --connect-installed --overwrite
+```
+
+`--connect-installed` implies auto client selection and is an explicit client-config write flag. It skips missing client configs instead of creating every default client config. Only explicit write flags mutate client configs. Existing explicit connector writes remain available through `enigma connect <client>` without `--dry-run`, and existing `enigma setup --write-connectors` behavior for explicit/default setup clients is unchanged; keep `--dry-run` while reviewing a single planned MCP entry.
+
+After setup, use the same local vault from the CLI or connected clients:
+
+```sh
+enigma remember --text-file ./memory.txt
+enigma search --query "..."
+enigma context --query "..." --optimize
+enigma verify --export ./.enigma/export.json
+enigma connect claude-desktop --dry-run
 ```
 
-`enigma quickstart` creates a local Enigma workspace for proof review: a local vault bundle, a context pack, an export proof bundle, and a verify report. These artifacts prove Enigma-controlled local vault state, receipts, checkpoints, and verification results only; they do not prove provider deletion, provider model forgetting, provider-native memory removal, hosted availability, or compliance certification.
+The local Enigma vault remains canonical. Provider-native memory is non-canonical and should be treated as a convenience cache only. Enigma receipts prove Enigma-controlled vault state, receipts, checkpoints, and declared boundary operations; they do not prove provider deletion, provider model forgetting, provider-native memory removal, hosted availability, ROI/savings, or compliance certification.
 
 One-off execution without a global install:
 
 ```sh
-npx --yes --package enigma-memory enigma quickstart --bundle ./.enigma/bundle.json --overwrite
+npx --yes --package enigma-memory enigma setup --overwrite
 ```
 
 ## Advanced/source-only path
@@ -60,7 +74,7 @@ enigma-gateway demo
 
 `install:local` is dry-run unless `--execute` is present. The command above installs the checked-out package globally and creates a local vault bundle. It does not require Cloudflare, OpenAI, Anthropic, npm publish credentials, a database, or hosted infrastructure.
 
-Manual alternative: create a no-network local vault, write one local memory from a file, compile a context pack, export a proof bundle, and verify it. Use a tenant-approved smoke file; do not expand private memory into shell argv.
+Manual alternative: inspect the lower-level local vault steps that `enigma setup` prepares for you. Use a tenant-approved smoke file; do not expand private memory into shell argv.
 
 POSIX shell:
 
@@ -72,7 +86,7 @@ enigma init --bundle ./.enigma/bundle.json --subject local-user --display-name "
 enigma remember --bundle ./.enigma/bundle.json --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose user_memory --tags local
 enigma context --bundle ./.enigma/bundle.json --query "local context" --purpose local_answer --out ./.enigma/context-pack.json
 enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
-enigma verify --bundle ./.enigma/export.json
+enigma verify --export ./.enigma/export.json
 ```
 
 Windows PowerShell:
@@ -85,7 +99,7 @@ enigma init --bundle .\.enigma\bundle.json --subject local-user --display-name "
 enigma remember --bundle .\.enigma\bundle.json --text-file $env:ENIGMA_DEMO_MEMORY_FILE --purpose user_memory --tags local
 enigma context --bundle .\.enigma\bundle.json --query "local context" --purpose local_answer --out .\.enigma\context-pack.json
 enigma export --bundle .\.enigma\bundle.json --out .\.enigma\export.json
-enigma verify --bundle .\.enigma\export.json
+enigma verify --export .\.enigma\export.json
 ```
 
 The bundle is local. Exported proof artifacts contain encrypted/committed vault state and receipt metadata; do not paste raw memory plaintext into relay records, witness checkpoints, SIEM events, public proof artifacts, or shell command lines.
@@ -150,16 +164,33 @@ Supported connector profiles are:
 - `opencode`
 - `generic-mcp`
 
-Use the config in `docs/client-connectors.md` from a source checkout for Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo Code, OpenCode, or any MCP-compatible client. The generated entry defaults to command `enigma-mcp` and sets `ENIGMA_BUNDLE` to the local vault bundle.
-
-CLI connector commands:
+After `enigma setup --overwrite`, preview a client connection before writing anything:
 
 ```sh
-enigma doctor
-enigma install --bundle "$HOME/.enigma/bundle.json"
-enigma connect claude-desktop --bundle "$HOME/.enigma/bundle.json"
-enigma connect kimi-code --bundle "$HOME/.enigma/bundle.json" --mcp-command "/absolute/path/to/enigma-mcp"
-enigma disconnect claude-desktop
+enigma connect claude-desktop --dry-run
+enigma connect cursor --dry-run
+enigma connect kimi-code --dry-run
+enigma connect generic-mcp --dry-run
+```
+
+For the one-time setup flow, `enigma setup --client auto --overwrite` reports the installed/config-present clients that connector detection selected and the clients it skipped with reasons. It remains read-only for client configs. `enigma setup --connect-installed --overwrite` is the explicit setup-time write path for installed/config-present clients only; missing configs are skipped rather than created.
+
+Remove `--dry-run` from `enigma connect <client>` only after you are ready for Enigma to merge the `mcpServers.enigma` entry into that specific client config. The safe default setup command never writes third-party app configs.
+
+Manual MCP entry for Claude Desktop, Cursor, Kimi Code, or any generic MCP client:
+
+```json
+{
+  "mcpServers": {
+    "enigma": {
+      "command": "enigma-mcp",
+      "args": [],
+      "env": {
+        "ENIGMA_BUNDLE": "/absolute/path/to/.enigma/bundle.json"
+      }
+    }
+  }
+}
 ```
 
 Use `--mcp-command` (alias `--command`) when a GUI app cannot find shell-installed binaries or needs a `.cmd` path on Windows.
@@ -291,7 +322,7 @@ test -f "$ENIGMA_DEMO_MEMORY_FILE"
 enigma init --bundle ./.enigma/bundle.json
 enigma remember --bundle ./.enigma/bundle.json --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose local_test
 enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
-enigma verify --bundle ./.enigma/export.json
+enigma verify --export ./.enigma/export.json
 enigma boundary run --scenario committed_crossing
 ```
 

package/apps/cli/bin/enigma.mjs

@@ -11,13 +11,17 @@ import { runBoundarySimulation } from '../../../packages/boundary/src/index.js';
 import { startStdioServer } from '../../../packages/mcp-server/src/index.js';
 import { runMeshDemo } from '../../../packages/mesh/src/index.js';
 import { runEnterpriseDemo } from '../../../packages/enterprise/src/index.js';
-import { connectClient, disconnectClient, doctorConnectors, getClientProfile, renderMcpConfig, supportedClients } from '../../../packages/connectors/src/index.js';
+import { connectClient, disconnectClient, doctorConnectors, getClientProfile, planConnectWizard, renderMcpConfig, supportedClients } from '../../../packages/connectors/src/index.js';
 import { exportEnigmaCapsule, importChatGptExport, importClaudeMemory, importEnigmaCapsule, importLangGraphStore, importLettaAgentFile, importMem0Export, importZepGraphitiExport } from '../../../packages/importers/src/index.js';
 import * as relayServer from '../../relay/src/server.mjs';
 import * as gatewayServer from '../../gateway/src/server.mjs';
 import { verifyBundle } from '../../verifier/bin/enigma-verify.mjs';
 import { createNativeHostInstallPlan, createNativeHostManifest } from '../../native-host/bin/enigma-native-host.mjs';
 import { aggregateUsageEvents, createUsageEvent } from '../../../packages/metering/src/index.js';
+import {
+  createMemoryAccessReceipt,
+  createMemoryOptimizationPlan,
+} from '../../../packages/optimizer/src/index.js';
 import {
   createConsumerGpuCapacityProfile,
   createOperatorServiceQuote,
@@ -33,6 +37,21 @@ export const DEFAULT_GATEWAY_PORT = 8797;
 const DEFAULT_QUICKSTART_MEMORY = 'Enigma quickstart demo memory: local proof bundles can be created and verified without provider or cloud credentials.';
 const DEFAULT_CROSS_MODEL_DEMO_BUNDLE = '.enigma/cross-model-demo-bundle.json';
 const DEFAULT_CROSS_MODEL_MEMORY = 'Enigma cross-model demo memory: a local encrypted memory can be packaged for ChatGPT, Claude, Kimi, Cursor, and a local LLM without provider credentials.';
+const DEFAULT_SETUP_CLIENTS = Object.freeze(['generic-mcp', 'claude-desktop', 'cursor', 'kimi-code']);
+const SETUP_CLAIM_BOUNDARIES = Object.freeze({
+  local_only: true,
+  provider_credentials_required: false,
+  provider_native_memory_canonical: false,
+  provider_deletion_proof: false,
+  model_forgetting_proof: false,
+  roi_or_savings_guarantee: false,
+  compliance_certification: false,
+});
+const QUICKSTART_ARTIFACT_NAMES = Object.freeze({
+  contextPack: 'context-pack.json',
+  export: 'export.json',
+  verifyReport: 'verify-report.json',
+});
 const CROSS_MODEL_PROFILES = Object.freeze([
   { id: 'chatgpt', provider: 'chatgpt', model: 'chatgpt-mcp-profile', label: 'ChatGPT' },
   { id: 'claude', provider: 'claude', model: 'claude-mcp-profile', label: 'Claude' },
@@ -77,6 +96,19 @@ const IMPORTERS = Object.freeze({
 
 export const REQUIRED_PACKAGE_BINS = Object.freeze(['enigma', 'enigma-verify', 'enigma-mcp', 'enigma-relay', 'enigma-gateway', 'enigma-native-host']);
 
+function setFlagValue(flags, name, value) {
+  if (!flags.has(name)) {
+    flags.set(name, value);
+    return;
+  }
+  const current = flags.get(name);
+  if (Array.isArray(current)) {
+    current.push(value);
+  } else {
+    flags.set(name, [current, value]);
+  }
+}
+
 function parseArgs(argv) {
   const flags = new Map();
   for (let i = 0; i < argv.length; i += 1) {
@@ -84,11 +116,11 @@ function parseArgs(argv) {
     if (!arg.startsWith('--')) continue;
     const eq = arg.indexOf('=');
     if (eq !== -1) {
-      flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+      setFlagValue(flags, arg.slice(2, eq), arg.slice(eq + 1));
     } else if (!argv[i + 1] || argv[i + 1].startsWith('--')) {
-      flags.set(arg.slice(2), true);
+      setFlagValue(flags, arg.slice(2), true);
     } else {
-      flags.set(arg.slice(2), argv[i + 1]);
+      setFlagValue(flags, arg.slice(2), argv[i + 1]);
       i += 1;
     }
   }
@@ -100,6 +132,19 @@ function getFlag(flags, names, fallback = undefined) {
   return fallback;
 }
 
+function lastFlagValue(value) {
+  return Array.isArray(value) ? value[value.length - 1] : value;
+}
+
+function booleanFlag(flags, names, fallback = false) {
+  const value = lastFlagValue(getFlag(flags, names, fallback));
+  if (value === true || value === false) return value;
+  if (value === undefined || value === '') return fallback;
+  if (String(value) === 'true') return true;
+  if (String(value) === 'false') return false;
+  throw new Error(`--${names[0]} must be true or false.`);
+}
+
 function requireFlag(flags, names, label = names[0]) {
   const value = getFlag(flags, names);
   if (value === undefined || value === true || value === '') throw new Error(`Missing required --${label}.`);
@@ -166,7 +211,7 @@ async function fileExists(path) {
 }
 
 function pathFlag(flags, names, fallback) {
-  const value = getFlag(flags, names, fallback);
+  const value = lastFlagValue(getFlag(flags, names, fallback));
   if (value === true || value === '') throw new Error(`Missing required --${names[0]}.`);
   return String(value);
 }
@@ -210,6 +255,74 @@ async function quickstartMemoryTextFromFlags(flags) {
   return DEFAULT_QUICKSTART_MEMORY;
 }
 
+function quickstartOutputs(bundleInput, outDirInput) {
+  const bundlePath = resolve(bundleInput);
+  const outDirPath = resolve(outDirInput);
+  const contextPackPath = resolve(outDirPath, QUICKSTART_ARTIFACT_NAMES.contextPack);
+  const exportPath = resolve(outDirPath, QUICKSTART_ARTIFACT_NAMES.export);
+  const verifyReportPath = resolve(outDirPath, QUICKSTART_ARTIFACT_NAMES.verifyReport);
+  return {
+    bundlePath,
+    outDirPath,
+    contextPackPath,
+    exportPath,
+    verifyReportPath,
+    contextPackDisplay: quickstartPathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.contextPack),
+    exportDisplay: quickstartPathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.export),
+    verifyReportDisplay: quickstartPathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.verifyReport),
+    outputs: [
+      { path: bundlePath, display: bundleInput },
+      { path: contextPackPath, display: quickstartPathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.contextPack) },
+      { path: exportPath, display: quickstartPathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.export) },
+      { path: verifyReportPath, display: quickstartPathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.verifyReport) },
+    ],
+  };
+}
+
+async function buildQuickstartArtifacts(flags, { bundleInput = DEFAULT_BUNDLE, outDirInput = dirname(bundleInput), overwrite = false, write = true } = {}) {
+  const paths = quickstartOutputs(bundleInput, outDirInput);
+  ensureDistinctOutputPaths(paths.outputs.map((output) => output.path));
+  await assertCanWriteQuickstartOutputs(paths.outputs, overwrite);
+
+  const vault = createVault({
+    subjectId: String(getFlag(flags, ['subject', 'subject-id'], 'local-user')),
+    displayName: String(getFlag(flags, ['display-name', 'name'], 'Local user')),
+    passphrase: String(getFlag(flags, ['passphrase'], 'local-development-passphrase')),
+  });
+  const passport = createPassport({
+    vault,
+    subjectId: vault.subject_id,
+    displayName: String(getFlag(flags, ['display-name', 'name'], 'Local user')),
+  });
+  remember({
+    vault,
+    passport,
+    text: await quickstartMemoryTextFromFlags(flags),
+    purpose: 'quickstart_local_proof',
+    purpose_tags: ['quickstart'],
+    metadata: { source: 'enigma quickstart' },
+  });
+  const contextPack = compileContextPack({
+    vault,
+    passport,
+    query: '',
+    purpose: 'quickstart_local_context',
+    limit: 8,
+  });
+  const exported = exportBundle({ vault, includePlaintext: false });
+  const bundle = exported.bundle ?? exported;
+  const verifyReport = verifyBundle(bundle);
+
+  if (write) {
+    await writeJson(paths.bundlePath, bundle);
+    await writeJson(paths.contextPackPath, contextPack);
+    await writeJson(paths.exportPath, bundle);
+    await writeJson(paths.verifyReportPath, verifyReport);
+  }
+
+  return { ...paths, vault, passport, contextPack, bundle, verifyReport };
+}
+
 async function crossModelMemoryTextFromFlags(flags) {
   const textFile = getFlag(flags, ['memory-file', 'memoryFile', 'text-file', 'textFile']);
   if (textFile === undefined) return DEFAULT_CROSS_MODEL_MEMORY;
@@ -273,6 +386,157 @@ function publicContextPackSummary(pack) {
   };
 }
 
+const SEARCH_RELEVANCE_STOPWORDS = new Set([
+  'about',
+  'after',
+  'again',
+  'against',
+  'also',
+  'and',
+  'any',
+  'are',
+  'assistant',
+  'because',
+  'been',
+  'before',
+  'being',
+  'between',
+  'can',
+  'could',
+  'current',
+  'does',
+  'from',
+  'has',
+  'have',
+  'how',
+  'into',
+  'its',
+  'latest',
+  'more',
+  'most',
+  'number',
+  'own',
+  'owns',
+  'please',
+  'should',
+  'that',
+  'the',
+  'their',
+  'then',
+  'there',
+  'these',
+  'they',
+  'this',
+  'use',
+  'using',
+  'was',
+  'what',
+  'when',
+  'where',
+  'which',
+  'who',
+  'whose',
+  'why',
+  'with',
+  'would',
+]);
+
+function addSearchToken(tokens, token) {
+  if (token.length < 3) return;
+  if (!/[a-z]/u.test(token)) return;
+  if (SEARCH_RELEVANCE_STOPWORDS.has(token)) return;
+  tokens.add(token);
+}
+
+function searchTokensFrom(value) {
+  const tokens = new Set();
+  if (value === undefined || value === null) return tokens;
+  for (const match of String(value).toLowerCase().matchAll(/[a-z0-9]+(?:[-_][a-z0-9]+)*/gu)) {
+    const token = match[0];
+    addSearchToken(tokens, token);
+    if (token.includes('-') || token.includes('_')) {
+      for (const part of token.split(/[-_]+/u)) addSearchToken(tokens, part);
+    }
+  }
+  return tokens;
+}
+
+function addSearchTokensFromValue(tokens, value) {
+  for (const token of searchTokensFrom(value)) tokens.add(token);
+}
+
+function recordSearchTokens(record, content) {
+  const tokens = new Set();
+  addSearchTokensFromValue(tokens, content);
+  addSearchTokensFromValue(tokens, record?.kind);
+  for (const tag of record?.purpose_tags ?? []) addSearchTokensFromValue(tokens, tag);
+  return tokens;
+}
+
+function searchScore(queryTokens, memoryTokens) {
+  if (queryTokens.size === 0) return 0;
+  let overlap = 0;
+  for (const token of queryTokens) {
+    if (memoryTokens.has(token)) overlap += 1;
+  }
+  return Math.round((overlap / queryTokens.size) * 1_000_000) / 1_000_000;
+}
+
+function searchResultReceiptIds(vault, memoryAddr) {
+  return vault.receipts
+    .filter((receipt) => receipt?.memory_addr === memoryAddr || receipt?.source_addr === memoryAddr)
+    .map((receipt) => receipt.receipt_id)
+    .filter((receiptId) => typeof receiptId === 'string' && receiptId.length > 0);
+}
+
+function publicAccessReceiptRef(receipt) {
+  return {
+    access_receipt_ref: `enigma://memory-access/${receipt.receipt_id}`,
+    receipt_id: receipt.receipt_id,
+    operation: receipt.operation,
+    memory_addr: receipt.address,
+    plan_hash: receipt.plan_hash,
+    estimated_prompt_tokens: receipt.estimated_prompt_tokens,
+    access_boundary: receipt.access_boundary,
+  };
+}
+
+function searchCandidates(vault, queryTokens) {
+  const candidates = [];
+  const byAddress = new Map();
+  for (const memoryAddr of [...vault.activeAddresses].sort()) {
+    const record = vault.__getRecord(memoryAddr);
+    if (!record || record.state !== 'active') continue;
+    const content = vault.__getPlaintext(memoryAddr);
+    const score = searchScore(queryTokens, recordSearchTokens(record, content));
+    if (queryTokens.size > 0 && score === 0) continue;
+    const candidate = {
+      address: memoryAddr,
+      content,
+      importance: typeof record.importance === 'number' ? record.importance : typeof record.confidence === 'number' ? record.confidence : undefined,
+      last_accessed_at: record.updated_at ?? record.created_at,
+      metadata: {
+        kind: record.kind,
+        sensitivity: record.sensitivity,
+        purpose_tags: record.purpose_tags ?? [],
+      },
+    };
+    candidates.push(candidate);
+    byAddress.set(memoryAddr, { record, content, score });
+  }
+  return { candidates, byAddress };
+}
+
+function connectorReadinessSummary(bundlePath) {
+  return {
+    ready: true,
+    bundle: bundlePath,
+    bundle_env: 'ENIGMA_BUNDLE',
+    mcp_command: 'enigma-mcp',
+    supported_clients: supportedClients,
+  };
+}
+
 function demoBundleRef(bundleWasSupplied) {
   return bundleWasSupplied ? 'supplied_bundle' : DEFAULT_CROSS_MODEL_DEMO_BUNDLE;
 }
@@ -493,85 +757,380 @@ async function initCommand(flags, io) {
   return 0;
 }
 
-export async function quickstartCommand(flags, io) {
+function setupClientIds(flags) {
+  const raw = getFlag(flags, ['client']);
+  if (raw === undefined) return { mode: 'default', auto: false, clients: [...DEFAULT_SETUP_CLIENTS], explicit_clients: [] };
+  const values = Array.isArray(raw) ? raw : [raw];
+  const clients = [];
+  let auto = false;
+  for (const value of values) {
+    if (value === true || value === '') throw new Error('Missing required --client.');
+    for (const client of String(value).split(',').map((item) => item.trim()).filter(Boolean)) {
+      if (client === 'auto') {
+        auto = true;
+        continue;
+      }
+      getClientProfile(client);
+      if (!clients.includes(client)) clients.push(client);
+    }
+  }
+  if (auto) return { mode: 'auto', auto: true, clients, explicit_clients: clients };
+  return { mode: clients.length > 0 ? 'explicit' : 'default', auto: false, clients: clients.length > 0 ? clients : [...DEFAULT_SETUP_CLIENTS], explicit_clients: clients };
+}
+
+function setupDetectedClientReason(client) {
+  if (client.installed === true && client.recommended_action === 'already_configured') return 'already_configured';
+  if (client.installed === true) return 'installed_needs_repair';
+  return 'client_config_present';
+}
+
+function setupSkippedClientReason(client) {
+  if (client.parse_error === true) return 'config_json_invalid';
+  if (client.config_path_exists === false || client.exists === false) return 'client_config_missing';
+  if (client.ok === false) return 'config_unreadable';
+  return 'not_selected';
+}
+
+function publicSetupClientSelectionEntry(client, reason) {
+  return {
+    client_id: client.client_id,
+    display_name: client.display_name,
+    reason,
+    action: client.recommended_action ?? client.action ?? null,
+    installed: client.installed === true,
+    config_path_exists: client.config_path_exists === true || client.exists === true,
+  };
+}
+
+async function setupAutoClientSelection(flags, artifacts, fallbackClients, mode) {
+  const doctor = await doctorConnectors({
+    ...connectorOptions(flags),
+    bundlePath: artifacts.bundlePath,
+    redactPaths: true,
+  });
+  const detected = doctor.clients.filter((client) => (client.config_path_exists === true || client.exists === true) && client.parse_error !== true);
+  const fallbackUsed = detected.length === 0;
+  const selectedClients = fallbackUsed ? [...fallbackClients] : detected.map((client) => client.client_id);
+  const selectedSet = new Set(selectedClients);
+  const detectedSet = new Set(detected.map((client) => client.client_id));
+  const selected = fallbackUsed
+    ? selectedClients.map((clientId) => {
+      const client = doctor.clients.find((entry) => entry.client_id === clientId) ?? { client_id: clientId, display_name: getClientProfile(clientId).display_name };
+      return publicSetupClientSelectionEntry(client, 'default_fallback_no_client_configs_detected');
+    })
+    : detected.map((client) => publicSetupClientSelectionEntry(client, setupDetectedClientReason(client)));
+  const skipped = doctor.clients
+    .filter((client) => !selectedSet.has(client.client_id))
+    .map((client) => publicSetupClientSelectionEntry(client, fallbackUsed && !detectedSet.has(client.client_id) ? 'not_in_default_fallback' : setupSkippedClientReason(client)));
+  const connectableClientIds = new Set(detected.map((client) => client.client_id));
+  return {
+    mode,
+    auto: true,
+    fallback_used: fallbackUsed,
+    clients: selectedClients,
+    selected,
+    skipped,
+    connectable_client_ids: connectableClientIds,
+    detection: doctor,
+  };
+}
+
+function setupMemorySource(flags) {
+  if (getFlag(flags, ['memory-file', 'memoryFile', 'text-file', 'textFile']) !== undefined) return 'memory_file';
+  if (getFlag(flags, ['memory-text', 'memoryText']) !== undefined) return 'demo_text';
+  return 'default_demo';
+}
+
+function commandPath(path) {
+  return `"${String(path).replace(/"/g, '\\"')}"`;
+}
+
+function publicPathDisplay(path, label) {
+  const value = String(path);
+  if (/^[A-Za-z]:[\\/]/.test(value) || value.startsWith('/') || value.startsWith('\\\\')) return `<${label}>`;
+  return value;
+}
+
+function setupPublicDisplays(bundleInput, outDirInput) {
+  const outDir = publicPathDisplay(outDirInput, 'out-dir');
+  return {
+    bundle: publicPathDisplay(bundleInput, 'bundle-path'),
+    context_pack: quickstartPathDisplay(outDir, QUICKSTART_ARTIFACT_NAMES.contextPack),
+    export: quickstartPathDisplay(outDir, QUICKSTART_ARTIFACT_NAMES.export),
+    verify_report: quickstartPathDisplay(outDir, QUICKSTART_ARTIFACT_NAMES.verifyReport),
+  };
+}
+
+function setupRawDisplays(bundleInput, outDirInput) {
+  const plan = quickstartOutputs(bundleInput, outDirInput);
+  return {
+    bundle: plan.outputs[0].display,
+    context_pack: plan.contextPackDisplay,
+    export: plan.exportDisplay,
+    verify_report: plan.verifyReportDisplay,
+  };
+}
+
+function publicSetupError(error, rawDisplays, publicDisplays) {
+  let message = error.message;
+  for (const [raw, safe] of Object.entries({
+    [rawDisplays.bundle]: publicDisplays.bundle,
+    [rawDisplays.context_pack]: publicDisplays.context_pack,
+    [rawDisplays.export]: publicDisplays.export,
+    [rawDisplays.verify_report]: publicDisplays.verify_report,
+  })) {
+    message = message.split(raw).join(safe);
+  }
+  return new Error(message);
+}
+
+function setupNextCommands(bundleInput, exportDisplay, clients, writeConnectors) {
+  const primaryClient = clients[0] ?? DEFAULT_SETUP_CLIENTS[0];
+  const commands = [
+    `enigma remember --bundle ${commandPath(bundleInput)} --text-file ./memory.txt`,
+    `enigma search --bundle ${commandPath(bundleInput)} --query "project context"`,
+    `enigma context --bundle ${commandPath(bundleInput)} --query "project context"`,
+    `enigma verify --export ${commandPath(exportDisplay)}`,
+  ];
+  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${commandPath(bundleInput)}`);
+  return commands;
+}
+
+async function setupDoctorChecks(flags, artifacts, clients, displays) {
+  const packageJson = await readPackageJson();
+  const requiredNodeMajor = minimumNodeMajor(packageJson.engines?.node);
+  const currentNodeMajor = nodeMajor(process.versions.node);
+  const binMap = packageJson.bin && typeof packageJson.bin === 'object' && !Array.isArray(packageJson.bin) ? packageJson.bin : {};
+  const binEntries = await Promise.all(REQUIRED_PACKAGE_BINS.map(async (name) => {
+    const target = binMap[name];
+    const declared = typeof target === 'string' && target.length > 0;
+    return {
+      name,
+      target: declared ? target : null,
+      declared,
+      exists: declared ? await fileExists(packageFileUrl(target)) : false,
+    };
+  }));
+  const schemas = await schemaFiles();
+  const connectorBaseOptions = {
+    ...connectorOptions(flags),
+    bundlePath: artifacts.bundlePath,
+    redactPaths: true,
+  };
+  const connectorClients = [];
+  for (const client of clients) {
+    const doctor = await doctorConnectors({ ...connectorBaseOptions, clientId: client });
+    connectorClients.push(...doctor.clients);
+  }
+  const checks = {
+    node: {
+      ok: requiredNodeMajor === 0 || currentNodeMajor >= requiredNodeMajor,
+      current: process.versions.node,
+      required: packageJson.engines?.node ?? null,
+    },
+    package_bins: {
+      ok: binEntries.every((entry) => entry.declared && entry.exists),
+      required: REQUIRED_PACKAGE_BINS,
+      entries: binEntries,
+      missing: binEntries.filter((entry) => !entry.declared).map((entry) => entry.name),
+      missing_targets: binEntries.filter((entry) => entry.declared && !entry.exists).map((entry) => entry.name),
+    },
+    artifacts: {
+      ok: artifacts.verifyReport.ok === true,
+      bundle: displays.bundle,
+      context_pack: displays.context_pack,
+      export: displays.export,
+      verify_report: displays.verify_report,
+    },
+    schemas: {
+      ok: schemas.length > 0,
+      count: schemas.length,
+      files: schemas,
+    },
+    connectors: {
+      ok: connectorClients.every((client) => client.ok !== false),
+      clients: connectorClients,
+    },
+  };
+  return { ok: Object.values(checks).every((check) => check.ok !== false), checks };
+}
+
+function publicConnectPlan(plan, wizard, profile, snippet) {
+  const changed = plan?.changed !== false;
+  const dryRun = plan?.dryRun === true || plan?.dry_run === true;
+  const plannedWrites = changed ? [{ type: 'write', path: wizard.default_config_path }] : [];
+  return {
+    ok: plan?.ok !== false,
+    action: 'connect',
+    client_id: profile.client_id,
+    configPath: wizard.default_config_path,
+    config_path: wizard.default_config_path,
+    serverName: profile.server_name,
+    server_name: profile.server_name,
+    changed,
+    dryRun,
+    dry_run: dryRun,
+    writes_performed: changed && !dryRun,
+    backup_planned: Boolean(plan?.backupPath),
+    plannedWrites,
+    planned_writes: plannedWrites,
+    config: snippet,
+  };
+}
+
+async function setupConnectorPlans(flags, artifacts, clients, writeConnectors, displays, writeClientIds = null) {
+  const publicOptions = {
+    ...connectorOptions(flags),
+    bundlePath: displays.bundle,
+  };
+  const writeOptions = {
+    ...connectorOptions(flags),
+    bundlePath: artifacts.bundlePath,
+  };
+  const connectors = [];
+  for (const client of clients) {
+    const profile = getClientProfile(client, publicOptions);
+    const snippet = renderMcpConfig(client, publicOptions);
+    const wizard = planConnectWizard(client, { platform: profile.platform }).clients[0];
+    const writeAllowed = writeClientIds === null || writeClientIds.has(client);
+    const rawPlan = writeConnectors && writeAllowed
+      ? await connectClient(client, { ...writeOptions, dryRun: false })
+      : { ok: true, changed: !(writeConnectors && !writeAllowed), dryRun: true };
+    const plan = publicConnectPlan(rawPlan, wizard, profile, snippet);
+    connectors.push({
+      client_id: client,
+      display_name: profile.display_name,
+      default_config_path: wizard.default_config_path,
+      mcp_config_snippet: snippet,
+      connect_command: `enigma connect ${client} --bundle ${commandPath(displays.bundle)}`,
+      connect_plan: plan,
+      write_selected: writeAllowed,
+      write_skipped_reason: writeConnectors && !writeAllowed ? 'client_config_missing' : null,
+      wizard,
+    });
+  }
+  return connectors;
+}
+
+function publicSetupClientSelection(selection) {
+  return {
+    mode: selection.mode,
+    auto: selection.auto === true,
+    fallback_used: selection.fallback_used === true,
+    selected: selection.selected,
+    skipped: selection.skipped,
+  };
+}
+
+export async function setupCommand(flags, io) {
   const bundleInput = pathFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE);
   const outDirInput = pathFlag(flags, ['out-dir', 'outDir'], dirname(bundleInput));
-  const bundlePath = resolve(bundleInput);
-  const outDirPath = resolve(outDirInput);
-  const contextPackPath = resolve(outDirPath, 'context-pack.json');
-  const exportPath = resolve(outDirPath, 'export.json');
-  const verifyReportPath = resolve(outDirPath, 'verify-report.json');
-  const contextPackDisplay = quickstartPathDisplay(outDirInput, 'context-pack.json');
-  const exportDisplay = quickstartPathDisplay(outDirInput, 'export.json');
-  const verifyReportDisplay = quickstartPathDisplay(outDirInput, 'verify-report.json');
-  const outputs = [
-    { path: bundlePath, display: bundleInput },
-    { path: contextPackPath, display: contextPackDisplay },
-    { path: exportPath, display: exportDisplay },
-    { path: verifyReportPath, display: verifyReportDisplay },
-  ];
-  ensureDistinctOutputPaths(outputs.map((output) => output.path));
-  const overwrite = getFlag(flags, ['overwrite'], false) === true || getFlag(flags, ['overwrite'], false) === 'true';
-  await assertCanWriteQuickstartOutputs(outputs, overwrite);
+  const requestedSelection = setupClientIds(flags);
+  const overwrite = booleanFlag(flags, ['overwrite'], false);
+  const dryRun = booleanFlag(flags, ['dry-run', 'dryRun'], false);
+  const writeConnectorsFlag = booleanFlag(flags, ['write-connectors', 'writeConnectors'], false);
+  const connectInstalled = booleanFlag(flags, ['connect-installed', 'connectInstalled'], false);
+  const connectorWritesRequested = (writeConnectorsFlag || connectInstalled) && !dryRun;
+  const displays = setupPublicDisplays(bundleInput, outDirInput);
+  const rawDisplays = setupRawDisplays(bundleInput, outDirInput);
+  let artifacts;
+  try {
+    artifacts = await buildQuickstartArtifacts(flags, { bundleInput, outDirInput, overwrite, write: !dryRun });
+  } catch (error) {
+    throw publicSetupError(error, rawDisplays, displays);
+  }
+  const selection = connectInstalled || requestedSelection.auto
+    ? await setupAutoClientSelection(flags, artifacts, DEFAULT_SETUP_CLIENTS, connectInstalled ? 'connect_installed' : 'auto')
+    : {
+      ...requestedSelection,
+      fallback_used: false,
+      selected: requestedSelection.clients.map((clientId) => {
+        const profile = getClientProfile(clientId);
+        return publicSetupClientSelectionEntry({ client_id: clientId, display_name: profile.display_name }, requestedSelection.mode === 'default' ? 'default_setup_client' : 'explicit_client');
+      }),
+      skipped: [],
+      connectable_client_ids: null,
+    };
+  const clients = selection.clients;
+  const writeClientIds = connectInstalled ? selection.connectable_client_ids : null;
+  const connectors = await setupConnectorPlans(flags, artifacts, clients, connectorWritesRequested, displays, writeClientIds);
+  const doctor = await setupDoctorChecks(flags, artifacts, clients, displays);
+  const ok = artifacts.verifyReport.ok === true;
+  const anyConnectorWritePerformed = connectors.some((connector) => connector.connect_plan.writes_performed === true);
 
-  const vault = createVault({
-    subjectId: String(getFlag(flags, ['subject', 'subject-id'], 'local-user')),
-    displayName: String(getFlag(flags, ['display-name', 'name'], 'Local user')),
-    passphrase: String(getFlag(flags, ['passphrase'], 'local-development-passphrase')),
-  });
-  const passport = createPassport({
-    vault,
-    subjectId: vault.subject_id,
-    displayName: String(getFlag(flags, ['display-name', 'name'], 'Local user')),
-  });
-  remember({
-    vault,
-    passport,
-    text: await quickstartMemoryTextFromFlags(flags),
-    purpose: 'quickstart_local_proof',
-    purpose_tags: ['quickstart'],
-    metadata: { source: 'enigma quickstart' },
-  });
-  const contextPack = compileContextPack({
-    vault,
-    passport,
-    query: '',
-    purpose: 'quickstart_local_context',
-    limit: 8,
-  });
-  const exported = exportBundle({ vault, includePlaintext: false });
-  const bundle = exported.bundle ?? exported;
-  const verifyReport = verifyBundle(bundle);
+  print({
+    ok,
+    schema: 'enigma.setup.v1',
+    command: 'enigma setup',
+    dry_run: dryRun,
+    artifacts_written: !dryRun,
+    client_configs_written: writeConnectorsFlag && !dryRun ? true : anyConnectorWritePerformed,
+    client_config_write_requested: connectorWritesRequested,
+    connector_write_mode: connectInstalled ? 'installed_only' : (writeConnectorsFlag ? 'selected_clients' : 'plan_only'),
+    connect_installed: connectInstalled,
+    bundle: displays.bundle,
+    context_pack: displays.context_pack,
+    export: displays.export,
+    verify_report: displays.verify_report,
+    memory_source: setupMemorySource(flags),
+    memory_plaintext_echoed: false,
+    memory_count: Array.isArray(artifacts.bundle.memory_objects) ? artifacts.bundle.memory_objects.length : 0,
+    receipt_count: Array.isArray(artifacts.bundle.receipts) ? artifacts.bundle.receipts.length : 0,
+    context_item_count: Array.isArray(artifacts.contextPack.memories) ? artifacts.contextPack.memories.length : 0,
+    verify_ok: artifacts.verifyReport.ok === true,
+    provider_credentials_required: false,
+    provider_native_memory_canonical: false,
+    selected_clients: clients,
+    skipped_clients: selection.skipped,
+    client_selection: publicSetupClientSelection(selection),
+    connector_write_skips: connectors
+      .filter((connector) => connector.write_skipped_reason)
+      .map((connector) => ({
+        client_id: connector.client_id,
+        display_name: connector.display_name,
+        reason: connector.write_skipped_reason,
+      })),
+    connectors,
+    mcp_config_snippets: Object.fromEntries(connectors.map((connector) => [connector.client_id, connector.mcp_config_snippet])),
+    connect_plans: Object.fromEntries(connectors.map((connector) => [connector.client_id, connector.connect_plan])),
+    next_commands: setupNextCommands(displays.bundle, displays.export, clients, connectorWritesRequested && (!connectInstalled || anyConnectorWritePerformed)),
+    checks: doctor.checks,
+    claim_boundaries: { ...SETUP_CLAIM_BOUNDARIES },
+  }, io);
+  return ok ? 0 : 1;
+}
 
-  await writeJson(bundlePath, bundle);
-  await writeJson(contextPackPath, contextPack);
-  await writeJson(exportPath, bundle);
-  await writeJson(verifyReportPath, verifyReport);
+export async function quickstartCommand(flags, io) {
+  const bundleInput = pathFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE);
+  const outDirInput = pathFlag(flags, ['out-dir', 'outDir'], dirname(bundleInput));
+  const overwrite = booleanFlag(flags, ['overwrite'], false);
+  const artifacts = await buildQuickstartArtifacts(flags, { bundleInput, outDirInput, overwrite, write: true });
 
   print({
-    ok: verifyReport.ok === true,
+    ok: artifacts.verifyReport.ok === true,
     bundle: bundleInput,
-    context_pack: contextPackDisplay,
-    export: exportDisplay,
-    verify_report: verifyReportDisplay,
-    memory_count: Array.isArray(bundle.memory_objects) ? bundle.memory_objects.length : 0,
-    receipt_count: Array.isArray(bundle.receipts) ? bundle.receipts.length : 0,
-    context_item_count: Array.isArray(contextPack.memories) ? contextPack.memories.length : 0,
-    verify_ok: verifyReport.ok === true,
+    context_pack: artifacts.contextPackDisplay,
+    export: artifacts.exportDisplay,
+    verify_report: artifacts.verifyReportDisplay,
+    memory_count: Array.isArray(artifacts.bundle.memory_objects) ? artifacts.bundle.memory_objects.length : 0,
+    receipt_count: Array.isArray(artifacts.bundle.receipts) ? artifacts.bundle.receipts.length : 0,
+    context_item_count: Array.isArray(artifacts.contextPack.memories) ? artifacts.contextPack.memories.length : 0,
+    verify_ok: artifacts.verifyReport.ok === true,
     next_commands: [
-      `enigma verify --export ${exportDisplay}`,
+      `enigma verify --export ${artifacts.exportDisplay}`,
       `enigma connect generic-mcp --bundle ${bundleInput} --dry-run`,
     ],
     claim_boundaries: {
       local_only: true,
       provider_credentials_required: false,
+      provider_native_memory_canonical: false,
       provider_deletion_proof: false,
       model_forgetting_proof: false,
       roi_or_savings_guarantee: false,
       compliance_certification: false,
     },
   }, io);
-  return verifyReport.ok === true ? 0 : 1;
+  return artifacts.verifyReport.ok === true ? 0 : 1;
 }
 
 export async function crossModelDemoCommand(flags, io) {
@@ -767,6 +1326,118 @@ async function contextCommand(flags, io) {
   return 0;
 }
 
+
+async function searchCommand(flags, io) {
+  const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
+  const query = String(requireFlag(flags, ['query', 'q'], 'query'));
+  const limit = integerFlag(flags, ['limit'], 'limit', 8);
+  if (limit < 0) throw new Error('--limit must be non-negative.');
+  const includeContent = getFlag(flags, ['include-content', 'includeContent']) === true || getFlag(flags, ['include-content', 'includeContent']) === 'true';
+  const { vault } = await loadState(bundlePath);
+  const roots = vault.__computeRoots();
+  const queryTokens = searchTokensFrom(query);
+  const { candidates, byAddress } = searchCandidates(vault, queryTokens);
+  const plan = createMemoryOptimizationPlan({
+    candidates,
+    prompt: query,
+    now: getFlag(flags, ['now'], '2026-01-01T00:00:00.000Z'),
+  });
+  const planIndex = new Map(plan.items.map((item, index) => [item.address, index]));
+  const selectedItems = plan.items
+    .filter((item) => byAddress.has(item.address))
+    .sort((left, right) => {
+      const scoreDiff = byAddress.get(right.address).score - byAddress.get(left.address).score;
+      if (scoreDiff !== 0) return scoreDiff;
+      return planIndex.get(left.address) - planIndex.get(right.address);
+    })
+    .slice(0, limit);
+  const accessReceipts = selectedItems.map((item, index) => createMemoryAccessReceipt({
+    item,
+    plan,
+    sequence: index,
+    timestamp: null,
+    pricing: plan.pricing,
+  }));
+  const accessReceiptByAddress = new Map(accessReceipts.map((receipt) => [receipt.address, publicAccessReceiptRef(receipt)]));
+  const results = selectedItems.map((item) => {
+    const hit = byAddress.get(item.address);
+    const record = hit.record;
+    const accessReceipt = accessReceiptByAddress.get(item.address);
+    return {
+      memory_ref: `enigma://memory/${item.address}`,
+      memory_addr: item.address,
+      address: item.address,
+      kind: record.kind,
+      sensitivity: record.sensitivity,
+      tags: Array.isArray(record.purpose_tags) ? [...record.purpose_tags] : [],
+      purpose_tags: Array.isArray(record.purpose_tags) ? [...record.purpose_tags] : [],
+      score: hit.score,
+      tier: item.tier,
+      receipt_ids: searchResultReceiptIds(vault, item.address),
+      access_receipt_ref: accessReceipt?.access_receipt_ref,
+      access_receipt_id: accessReceipt?.receipt_id,
+      access_receipt_refs: accessReceipt?.access_receipt_ref ? [accessReceipt.access_receipt_ref] : [],
+      content_redacted: !includeContent,
+      ...(includeContent ? { content: hit.content } : {}),
+    };
+  });
+  print({
+    ok: true,
+    schema: 'enigma.memory_search.v1',
+    bundle: bundlePath,
+    query_redacted: true,
+    limit,
+    result_count: results.length,
+    results,
+    access_receipts: accessReceipts.map(publicAccessReceiptRef),
+    active_set_root: roots.active_set_root,
+    receipt_log_root: roots.receipt_log_root,
+    claim_boundary: includeContent
+      ? 'Search ran against the selected local bundle and includes plaintext only because --include-content was explicit; this does not prove provider deletion, provider-native memory state, or model forgetting.'
+      : 'Search ran against the selected local bundle and redacts plaintext by default; refs, scores, tags, roots, and receipt refs are not provider deletion proof or model forgetting proof.',
+  }, io);
+  return 0;
+}
+
+async function statusCommand(flags, io) {
+  const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
+  const { stored, vault, passport } = await loadState(bundlePath);
+  const roots = vault.__computeRoots();
+  const activeCount = activeMemoryCount(vault);
+  const tombstoneCount = vault.tombstones instanceof Map ? vault.tombstones.size : 0;
+  const receiptCount = Array.isArray(vault.receipts) ? vault.receipts.length : 0;
+  print({
+    ok: true,
+    schema: 'enigma.passport_status.v1',
+    bundle: bundlePath,
+    passport_ref: `enigma://passport/${passport.passport_id}`,
+    owner: {
+      subject_id: stored.owner?.subject_id ?? stored.passport?.owner?.subject_id ?? stored.vault?.subject_id ?? passport.owner?.subject_id ?? vault.subject_id,
+      display_name: stored.owner?.display_name ?? stored.passport?.owner?.display_name ?? stored.vault?.display_name ?? passport.owner?.display_name ?? 'Local user',
+    },
+    counts: {
+      active_memories: activeCount,
+      tombstoned_memories: tombstoneCount,
+      receipts: receiptCount,
+    },
+    active_memory_count: activeCount,
+    tombstoned_memory_count: tombstoneCount,
+    receipt_count: receiptCount,
+    active_set_root: roots.active_set_root,
+    receipt_log_root: roots.receipt_log_root,
+    connector_readiness: connectorReadinessSummary(bundlePath),
+    next_recommended_commands: [
+      `enigma remember --bundle "${bundlePath}" --text-file <path>`,
+      `enigma search --bundle "${bundlePath}" --query <text>`,
+      `enigma context --bundle "${bundlePath}" --query <text>`,
+      `enigma verify --bundle "${bundlePath}"`,
+      `enigma connect <client> --bundle "${bundlePath}"`,
+    ],
+    claim_boundary: 'Status reports local bundle counters, owner display fields, connector readiness hints, and commitment roots only; it does not expose raw memory, certify compliance, prove provider deletion, or prove model forgetting.',
+  }, io);
+  return 0;
+}
+
 async function exportCommand(flags, io) {
   const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
   const { vault } = await loadState(bundlePath);
@@ -1272,6 +1943,7 @@ function usage() {
     usage: 'enigma <command> [options]',
     commands: [
       'init',
+      'setup',
       'quickstart',
       'demo cross-model',
       'doctor',
@@ -1283,6 +1955,9 @@ function usage() {
       'update',
       'delete',
       'context',
+      'search',
+      'status',
+      'passport status',
       'export',
       'import <source>',
       'capsule export',
@@ -1318,6 +1993,28 @@ function usage() {
       '--text <text>': 'Inline local memory text. Avoid for private content because argv can be logged by process tooling.',
       '--text-file <path>': 'Read local memory text from a file so private smoke input is not exposed in shell argv. Aliases: --memory-file, --textFile, --memoryFile.',
     },
+    search_options: {
+      '--query <text>': 'Required local query. Output redacts the query and memory plaintext by default. Alias: --q.',
+      '--bundle <path>': 'Bundle JSON to search. Defaults to .enigma/bundle.json.',
+      '--limit <n>': 'Maximum ranked active memories to return. Defaults to 8.',
+      '--json': 'Reserved for explicit JSON output; CLI output is JSON by default.',
+      '--include-content': 'Opt in to returning plaintext local memory content in the JSON result.',
+    },
+    status_options: {
+      'enigma status --bundle <path>': 'Show local Memory Passport counts, roots, owner display fields, connector readiness, and next commands.',
+      'enigma passport status --bundle <path>': 'Alias for enigma status.',
+    },
+    setup_options: {
+      '--bundle <path>': 'Bundle JSON to create. Defaults to .enigma/bundle.json.',
+      '--out-dir <path>': 'Directory for context-pack.json, export.json, and verify-report.json. Defaults to the bundle directory.',
+      '--client <id|auto>': `Client to plan; repeat or comma-separate. Use auto to plan installed/config-present clients, falling back to ${DEFAULT_SETUP_CLIENTS.join(', ')}.`,
+      '--connect-installed': 'Auto-select installed/config-present clients and write only those existing client configs; missing client configs are reported and skipped.',
+      '--memory-file <path>': 'Read local memory text from a file without echoing plaintext. Alias: --text-file.',
+      '--memory-text <text>': 'Inline demo-only memory text. Avoid for private content because argv can be logged.',
+      '--overwrite': 'Replace existing local setup artifacts.',
+      '--dry-run': 'Plan setup without writing local artifacts or client configs.',
+      '--write-connectors': 'Also write selected client MCP config files. Defaults to false.',
+    },
     quickstart_options: {
       '--bundle <path>': 'Bundle JSON to create. Defaults to .enigma/bundle.json.',
       '--out-dir <path>': 'Directory for context-pack.json, export.json, and verify-report.json. Defaults to the bundle directory.',
@@ -1398,15 +2095,16 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     print(usage(), io);
     return 0;
   }
-  const twoPartCommands = ['boundary', 'mcp', 'mesh', 'enterprise', 'capsule', 'relay', 'gateway', 'connect', 'disconnect', 'import', 'native-host', 'meter', 'settlement', 'demo'];
+  const twoPartCommands = ['boundary', 'mcp', 'mesh', 'enterprise', 'capsule', 'relay', 'gateway', 'connect', 'disconnect', 'import', 'native-host', 'meter', 'settlement', 'demo', 'passport'];
   const flags = parseArgs(twoPartCommands.includes(command) ? argv.slice(2) : argv.slice(1));
   const positionalFile = optionalPositional(argv[2]);
-  if ((flags.has('help') || argv.includes('-h')) && (((command === 'relay' || command === 'gateway') && (subcommand === 'serve' || subcommand === 'demo')) || (command === 'native-host' && (subcommand === 'manifest' || subcommand === 'install-plan')) || (command === 'demo' && subcommand === 'cross-model'))) {
+  if ((flags.has('help') || argv.includes('-h')) && (command === 'setup' || command === 'search' || command === 'status' || (command === 'passport' && subcommand === 'status') || ((command === 'relay' || command === 'gateway') && (subcommand === 'serve' || subcommand === 'demo')) || (command === 'native-host' && (subcommand === 'manifest' || subcommand === 'install-plan')) || (command === 'demo' && subcommand === 'cross-model'))) {
     print(usage(), io);
     return 0;
   }
   try {
     if (command === 'init') return await initCommand(flags, io);
+    if (command === 'setup') return await setupCommand(flags, io);
     if (command === 'quickstart') return await quickstartCommand(flags, io);
     if (command === 'demo' && subcommand === 'cross-model') return await crossModelDemoCommand(flags, io);
     if (command === 'doctor') return await doctorCommand(flags, io);
@@ -1418,6 +2116,9 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     if (command === 'update') return await updateCommand(flags, io);
     if (command === 'delete') return await deleteCommand(flags, io);
     if (command === 'context') return await contextCommand(flags, io);
+    if (command === 'search') return await searchCommand(flags, io);
+    if (command === 'status') return await statusCommand(flags, io);
+    if (command === 'passport' && subcommand === 'status') return await statusCommand(flags, io);
     if (command === 'export') return await exportCommand(flags, io);
     if (command === 'import') return await importCommand(subcommand, flags, io, positionalFile);
     if (command === 'capsule' && subcommand === 'export') return await capsuleExportCommand(flags, io, positionalFile);

package/docs/developer-ecosystem.md

@@ -2,6 +2,41 @@
 
 Enigma Memory is a local-first SDK, CLI, MCP server, and service-contract package. The developer surfaces are designed to be copied without secrets, cloud credentials, hidden local paths, or account identifiers.
 
+## CLI memory passport loop
+
+For most developers, start with the installed CLI before reading the SDK internals or service contracts:
+
+```sh
+npm install -g enigma-memory
+enigma setup --overwrite
+```
+
+`enigma setup --overwrite` is the safe default. It writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON without printing raw memory plaintext. It does not write third-party app configs.
+
+To let setup auto-detect installed or already-configured clients and report the connector plan without mutating client configs:
+
+```sh
+enigma setup --client auto --overwrite
+```
+
+To explicitly write connector entries for installed/config-present clients only:
+
+```sh
+enigma setup --connect-installed --overwrite
+```
+
+`--client auto` selects clients found by connector detection and falls back to the default setup client list when none are present. The setup output lists selected clients, skipped clients, and skip reasons. `--connect-installed` implies auto selection, writes only for installed/config-present clients, and skips missing configs instead of creating every default client config. Only explicit write flags mutate client configs; `enigma connect <client>` without `--dry-run` remains the single-client write path, and existing `enigma setup --write-connectors` behavior for explicit/default clients is unchanged. Treat provider-native memory as non-canonical cache only; the local Enigma vault is canonical.
+
+After setup, use the same local vault from the CLI or connected clients:
+
+```sh
+enigma remember --text-file ./memory.txt
+enigma search --query "..."
+enigma context --query "..." --optimize
+enigma verify --export ./.enigma/export.json
+enigma connect claude-desktop --dry-run
+```
+
 ## Copyable starting points
 
 - SDK/API guide: [`docs/sdk-api.md`](./sdk-api.md)
@@ -25,11 +60,11 @@ The example app prints ids, counts, roots, and verification status only. It does
 
 ## CLI and CI loop
 
-The CI example installs Node 24, installs the published `enigma-memory@0.1.4` package, runs:
+The CI example installs Node 24, installs the published `enigma-memory@0.1.7` package, runs:
 
 ```sh
-npx enigma quickstart --overwrite
-npx enigma doctor
+npx --yes --package enigma-memory enigma setup --overwrite
+npx --yes --package enigma-memory enigma doctor
 npm run benchmark:memory-suite -- --out benchmark-report.json
 ```
 
@@ -49,22 +84,73 @@ Use the workflow as a template in a consumer repository. It is intentionally lim
 
 ## MCP client loop
 
-The generic MCP template uses the installed `enigma-mcp` command and exactly one environment placeholder:
+The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. The smooth setup path is `enigma setup --client auto --overwrite` to plan detected clients, then `enigma setup --connect-installed --overwrite` only when you explicitly want setup to write installed/config-present client configs. Manual snippets remain useful when a client needs a copied entry; replace the bundle path with the local path from your setup output, and restart the client.
+
+Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "enigma": {
+      "command": "enigma-mcp",
+      "args": [],
+      "env": {
+        "ENIGMA_BUNDLE": "/absolute/path/to/.enigma/bundle.json"
+      }
+    }
+  }
+}
+```
+
+Cursor:
+
+```json
+{
+  "mcpServers": {
+    "enigma": {
+      "command": "enigma-mcp",
+      "args": [],
+      "env": {
+        "ENIGMA_BUNDLE": "/absolute/path/to/.enigma/bundle.json"
+      }
+    }
+  }
+}
+```
+
+Kimi Code:
+
+```json
+{
+  "mcpServers": {
+    "enigma": {
+      "command": "enigma-mcp",
+      "args": [],
+      "env": {
+        "ENIGMA_BUNDLE": "/absolute/path/to/.enigma/bundle.json"
+      }
+    }
+  }
+}
+```
+
+Generic MCP:
 
 ```json
 {
   "mcpServers": {
     "enigma": {
       "command": "enigma-mcp",
+      "args": [],
       "env": {
-        "ENIGMA_BUNDLE": "<ENIGMA_BUNDLE>"
+        "ENIGMA_BUNDLE": "/absolute/path/to/.enigma/bundle.json"
       }
     }
   }
 }
 ```
 
-Replace `<ENIGMA_BUNDLE>` with the bundle file you control, or with the client-specific environment expansion syntax if your MCP client supports it. Do not commit private bundle paths if they reveal local usernames, workspace names, account ids, or other personal details.
+Do not commit private bundle paths if they reveal local usernames, workspace names, account ids, or other personal details.
 
 ## Claim boundaries for developers
 

package/docs/sdk-api.md

@@ -1,6 +1,6 @@
 # SDK and API guide
 
-This guide covers the public package imports for `enigma-memory@0.1.5`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
+This guide covers the public package imports for `enigma-memory@0.1.7`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
 
 ## Install and import style
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enigma-memory",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Provider-agnostic AI memory passport and offline-verifiable proof layer.",
   "license": "Apache-2.0",

package/packages/mcp-server/src/index.js

@@ -17,7 +17,7 @@ import {
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
 const JSONRPC_VERSION = '2.0';
 const MCP_PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.5' });
+const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.7' });
 const JSON_RPC_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 const JSON_RPC_ERROR = Object.freeze({
   INVALID_REQUEST: -32600,

package/scripts/build-installer-assets.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 
 export const INSTALLER_ASSET_SCHEMA = 'enigma.installer_assets.v1';
 export const INSTALLER_ASSET_PACKAGE = 'enigma-memory';
-export const INSTALLER_ASSET_VERSION = '0.1.5';
+export const INSTALLER_ASSET_VERSION = '0.1.7';
 export const INSTALLER_ASSET_GENERATED_AT = '1970-01-01T00:00:00.000Z';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);

package/scripts/run-standard-memory-benchmarks.mjs

@@ -995,7 +995,7 @@ function buildSuiteReport(datasetRows, topK, options) {
     generated_at: options.generated_at ?? new Date().toISOString(),
     package: {
       name: 'enigma-memory',
-      version: '0.1.5',
+      version: '0.1.7',
     },
     public_safe: true,
     top_k: topK,