enigma-memory 0.1.10 → 0.1.11

package/README.md

@@ -2,18 +2,41 @@
 
 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.
 
-Start with the package path below. You do not need to understand relay, gateway, mesh, browser, desktop, or hosted infrastructure before trying Enigma locally.
+Start with the public test drive below. You do not need to understand relay, gateway, mesh, browser, desktop, or hosted infrastructure before trying Enigma locally.
 
 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.
 
+## Public test drive: prove the local package path first
+
+The fastest public test is the published npm package plus the local-only test drive:
+
+```sh
+npm install -g enigma-memory
+enigma test-drive --overwrite
+```
+
+`enigma test-drive --overwrite` needs no database, provider API key, cloud credential, npm publishing token, package registry account, or hosted Enigma account. It runs entirely on the local filesystem, does not call OpenAI, Anthropic, Cloudflare, hosted Enigma, or other external providers, and does not write Claude, Cursor, Kimi, or other third-party client configs.
+
+By default the command writes an isolated demo under `.enigma/test-drive`. Use `--dry-run` to print the plan without writing, or `--out-dir <path>` to choose another isolated demo directory. The default bundle and proof artifacts live inside that directory.
+
+The test-drive output is a single public-safe JSON summary. It points to the local setup artifacts, search/status output, cross-model demo report, and benchmark pointers, and it prints exact next commands for testers without printing raw private memory plaintext. The proof is bounded to the local demo: Enigma-controlled vault state, receipts, checkpoints, committed roots, exported bundle shape, and declared boundary operations. It is not evidence that hosted SaaS is live, that a closed provider deleted internal data, that model weights forgot, or that provider-native memory disappeared.
+
+When you are ready to connect real local clients that are already installed or already configured:
+
+```sh
+enigma setup --connect-installed --overwrite
+```
+
+`--connect-installed` is the explicit client-config write path. It skips missing client configs instead of creating every default client config.
+
 ## Install once, use everywhere
 
 Prerequisites:
 
 - Node.js `>=24`
-- No database, package registry account, provider credential, or cloud credential for the local setup path
+- No database, package registry account, provider credential, or cloud credential for the local test-drive or setup paths
 - Git only when you choose the advanced source-checkout path
 
 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.
@@ -23,7 +46,7 @@ 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 Claude, Cursor, Kimi, or other third-party app configs.
+`enigma setup --overwrite` is the safe default for creating a regular local workspace after the test drive. 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:
 
@@ -33,7 +56,7 @@ 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:
+Only when you are ready to explicitly write connector entries for installed/config-present clients:
 
 ```sh
 enigma setup --connect-installed --overwrite
@@ -53,10 +76,10 @@ enigma connect claude-desktop --dry-run
 
 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:
+One-off public test drive without a global install:
 
 ```sh
-npx --yes --package enigma-memory enigma setup --overwrite
+npx --yes --package enigma-memory enigma test-drive --overwrite
 ```
 
 ## Advanced/source-only path
@@ -164,7 +187,7 @@ Supported connector profiles are:
 - `opencode`
 - `generic-mcp`
 
-After `enigma setup --overwrite`, preview a client connection before writing anything:
+After `enigma test-drive --overwrite` proves the local package path and `enigma setup --overwrite` creates a regular local workspace, preview a client connection before writing anything:
 
 ```sh
 enigma connect claude-desktop --dry-run

package/apps/cli/bin/enigma.mjs

@@ -3,7 +3,7 @@ import { createHash } from 'node:crypto';
 import { createServer as createHttpServer } from 'node:http';
 import { realpathSync } from 'node:fs';
 import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createVault, remember, recall, updateMemory, deleteMemory, exportBundle } from '../../../packages/vault/src/index.js';
 import { createPassport, compileContextPack } from '../../../packages/passport/src/index.js';
@@ -32,6 +32,9 @@ import {
 } from '../../../packages/settlement/src/index.js';
 
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
+const DEFAULT_TEST_DRIVE_DIR = '.enigma/test-drive';
+const DEFAULT_TEST_DRIVE_BUNDLE_NAME = 'bundle.json';
+const DEFAULT_TEST_DRIVE_CROSS_MODEL_REPORT_NAME = 'cross-model-report.json';
 export const DEFAULT_RELAY_PORT = 8787;
 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.';
@@ -279,10 +282,10 @@ function quickstartOutputs(bundleInput, outDirInput) {
   };
 }
 
-async function buildQuickstartArtifacts(flags, { bundleInput = DEFAULT_BUNDLE, outDirInput = dirname(bundleInput), overwrite = false, write = true } = {}) {
+async function buildQuickstartArtifacts(flags, { bundleInput = DEFAULT_BUNDLE, outDirInput = dirname(bundleInput), overwrite = false, write = true, checkExisting = true } = {}) {
   const paths = quickstartOutputs(bundleInput, outDirInput);
   ensureDistinctOutputPaths(paths.outputs.map((output) => output.path));
-  await assertCanWriteQuickstartOutputs(paths.outputs, overwrite);
+  if (checkExisting) await assertCanWriteQuickstartOutputs(paths.outputs, overwrite);
 
   const vault = createVault({
     subjectId: String(getFlag(flags, ['subject', 'subject-id'], 'local-user')),
@@ -1133,6 +1136,39 @@ export async function quickstartCommand(flags, io) {
   return artifacts.verifyReport.ok === true ? 0 : 1;
 }
 
+function buildCrossModelProfileSummaries({ vault, passport, demoMemoryAddr, limit }) {
+  const profiles = [];
+  for (const profile of CROSS_MODEL_PROFILES) {
+    const pack = compileContextPack({
+      vault,
+      passport,
+      provider: profile.provider,
+      model: profile.model,
+      query: 'memory follows me across models',
+      purpose: `cross_model_demo:${profile.id}`,
+      memory_addresses: [demoMemoryAddr],
+      limit,
+    });
+    const contextPack = publicContextPackSummary(pack);
+    profiles.push({
+      profile: profile.id,
+      label: profile.label,
+      provider: profile.provider,
+      model: profile.model,
+      context_pack_ref: contextPack.context_pack_ref,
+      context_pack_id: contextPack.context_pack_id,
+      context_pack_digest: contextPack.context_pack_digest,
+      context_pack: contextPack,
+      receipt_count: contextPack.receipt_count,
+      memory_count: contextPack.memory_count,
+      provider_native_memory_canonical: false,
+      receipts: contextPack.receipts,
+      claim_boundaries: { ...CROSS_MODEL_CLAIM_BOUNDARIES },
+    });
+  }
+  return profiles;
+}
+
 export async function crossModelDemoCommand(flags, io) {
   const bundleFlag = getFlag(flags, ['bundle', 'file']);
   if (bundleFlag === true || bundleFlag === '') throw new Error('Missing required --bundle.');
@@ -1189,35 +1225,7 @@ export async function crossModelDemoCommand(flags, io) {
   const limit = integerFlag(flags, ['limit'], 'limit', 1);
   if (limit < 1) throw new Error('--limit must be at least 1.');
   const receiptCountBeforeProfiles = Array.isArray(vault.receipts) ? vault.receipts.length : 0;
-  const profiles = [];
-  for (const profile of CROSS_MODEL_PROFILES) {
-    const pack = compileContextPack({
-      vault,
-      passport,
-      provider: profile.provider,
-      model: profile.model,
-      query: 'memory follows me across models',
-      purpose: `cross_model_demo:${profile.id}`,
-      memory_addresses: [demoMemoryAddr],
-      limit,
-    });
-    const contextPack = publicContextPackSummary(pack);
-    profiles.push({
-      profile: profile.id,
-      label: profile.label,
-      provider: profile.provider,
-      model: profile.model,
-      context_pack_ref: contextPack.context_pack_ref,
-      context_pack_id: contextPack.context_pack_id,
-      context_pack_digest: contextPack.context_pack_digest,
-      context_pack: contextPack,
-      receipt_count: contextPack.receipt_count,
-      memory_count: contextPack.memory_count,
-      provider_native_memory_canonical: false,
-      receipts: contextPack.receipts,
-      claim_boundaries: { ...CROSS_MODEL_CLAIM_BOUNDARIES },
-    });
-  }
+  const profiles = buildCrossModelProfileSummaries({ vault, passport, demoMemoryAddr, limit });
 
   const bundle = await persistState(bundlePath, vault);
   const report = {
@@ -1327,20 +1335,14 @@ async function contextCommand(flags, io) {
 }
 
 
-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);
+function memorySearchReport({ bundlePath, vault, query, limit, includeContent = false, now = '2026-01-01T00:00:00.000Z' }) {
   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'),
+    now,
   });
   const planIndex = new Map(plan.items.map((item, index) => [item.address, index]));
   const selectedItems = plan.items
@@ -1381,7 +1383,7 @@ async function searchCommand(flags, io) {
       ...(includeContent ? { content: hit.content } : {}),
     };
   });
-  print({
+  return {
     ok: true,
     schema: 'enigma.memory_search.v1',
     bundle: bundlePath,
@@ -1395,18 +1397,33 @@ async function searchCommand(flags, io) {
     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) {
+async function searchCommand(flags, io) {
   const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
-  const { stored, vault, passport } = await loadState(bundlePath);
+  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);
+  print(memorySearchReport({
+    bundlePath,
+    vault,
+    query,
+    limit,
+    includeContent,
+    now: getFlag(flags, ['now'], '2026-01-01T00:00:00.000Z'),
+  }), io);
+  return 0;
+}
+
+function passportStatusReport({ bundlePath, stored = {}, vault, passport }) {
   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({
+  return {
     ok: true,
     schema: 'enigma.passport_status.v1',
     bundle: bundlePath,
@@ -1434,10 +1451,317 @@ async function statusCommand(flags, io) {
       `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);
+  };
+}
+
+async function statusCommand(flags, io) {
+  const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
+  const { stored, vault, passport } = await loadState(bundlePath);
+  print(passportStatusReport({ bundlePath, stored, vault, passport }), io);
   return 0;
 }
 
+function testDrivePathDisplay(outDirInput, name) {
+  return isAbsolute(outDirInput) ? join(outDirInput, name) : quickstartPathDisplay(outDirInput, name);
+}
+
+function testDriveBundleDisplay(outDirInput) {
+  return testDrivePathDisplay(outDirInput, DEFAULT_TEST_DRIVE_BUNDLE_NAME);
+}
+
+function testDriveOutputs(outDirInput, bundleInput = testDriveBundleDisplay(outDirInput)) {
+  const quickstart = quickstartOutputs(bundleInput, outDirInput);
+  const contextPackDisplay = testDrivePathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.contextPack);
+  const exportDisplay = testDrivePathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.export);
+  const verifyReportDisplay = testDrivePathDisplay(outDirInput, QUICKSTART_ARTIFACT_NAMES.verifyReport);
+  const crossModelReportDisplay = testDrivePathDisplay(outDirInput, DEFAULT_TEST_DRIVE_CROSS_MODEL_REPORT_NAME);
+  const crossModelReportPath = resolve(quickstart.outDirPath, DEFAULT_TEST_DRIVE_CROSS_MODEL_REPORT_NAME);
+  const artifacts = [
+    { role: 'bundle', path: quickstart.bundlePath, display: bundleInput, schema: 'enigma.bundle.v1' },
+    { role: 'context_pack', path: quickstart.contextPackPath, display: contextPackDisplay, schema: 'enigma.context_pack.v1' },
+    { role: 'export', path: quickstart.exportPath, display: exportDisplay, schema: 'enigma.bundle.v1' },
+    { role: 'verify_report', path: quickstart.verifyReportPath, display: verifyReportDisplay, schema: 'enigma.verify_report.v1' },
+    { role: 'cross_model_report', path: crossModelReportPath, display: crossModelReportDisplay, schema: 'enigma.cross_model_demo.v1' },
+  ];
+  return {
+    ...quickstart,
+    contextPackDisplay,
+    exportDisplay,
+    verifyReportDisplay,
+    crossModelReportPath,
+    crossModelReportDisplay,
+    artifacts,
+    outputs: artifacts.map((artifact) => ({ path: artifact.path, display: artifact.display })),
+  };
+}
+
+function testDriveFileSummaries(artifacts, written) {
+  return artifacts.map((artifact) => ({
+    role: artifact.role,
+    path: artifact.display,
+    schema: artifact.schema,
+    written: Boolean(written),
+  }));
+}
+
+function firstActiveMemoryAddress(vault) {
+  if (!(vault.activeAddresses instanceof Set)) throw new Error('Test drive vault did not expose an active memory set.');
+  const first = vault.activeAddresses.values().next();
+  if (first.done) throw new Error('Test drive vault did not create a demo memory.');
+  return first.value;
+}
+
+function testDriveNextCommands(bundleDisplay, crossModelReportDisplay) {
+  const quotedBundle = commandPath(bundleDisplay);
+  const quotedReport = commandPath(crossModelReportDisplay);
+  return [
+    `enigma status --bundle ${quotedBundle}`,
+    `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
+    `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
+    'node scripts/run-memory-benchmarks.mjs',
+  ];
+}
+
+function testDriveFlowCommands({ bundleDisplay, outDirInput, crossModelReportDisplay, overwrite }) {
+  const overwriteSuffix = overwrite ? ' --overwrite' : '';
+  const quotedBundle = commandPath(bundleDisplay);
+  const quotedOutDir = commandPath(outDirInput);
+  const quotedReport = commandPath(crossModelReportDisplay);
+  return [
+    `enigma quickstart --bundle ${quotedBundle} --out-dir ${quotedOutDir}${overwriteSuffix}`,
+    `enigma status --bundle ${quotedBundle}`,
+    `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
+    `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
+  ];
+}
+
+function testDriveBenchmarkPointers() {
+  return [
+    {
+      command: 'node scripts/run-memory-benchmarks.mjs',
+      public_safe: true,
+      planned_only: true,
+      requires_repo_checkout: true,
+      external_provider_calls: false,
+      raw_memory_included: false,
+      claim_boundary: 'Runs deterministic local fixture operations only; it is not a provider comparison, hosted service proof, benchmark leadership claim, ROI claim, provider deletion proof, or model forgetting proof.',
+    },
+    {
+      command: 'node scripts/download-standard-benchmarks.mjs --dry-run',
+      public_safe: true,
+      planned_only: true,
+      requires_repo_checkout: true,
+      external_provider_calls: false,
+      raw_memory_included: false,
+      claim_boundary: 'Plans official dataset downloads without fetching by default; raw benchmark records are not included in the public plan.',
+    },
+    {
+      command: 'node scripts/run-standard-memory-benchmarks.mjs --locomo <path> --longmemeval <path>',
+      public_safe: true,
+      planned_only: true,
+      requires_repo_checkout: true,
+      external_provider_calls: false,
+      raw_memory_included: false,
+      claim_boundary: 'Runs local deterministic retrieval proxies against operator-supplied dataset files; it emits no provider API calls, competitor scores, benchmark leadership claim, or model-forgetting claim.',
+    },
+  ];
+}
+
+function testDriveClaimBoundaries() {
+  return {
+    local_only: true,
+    credentials_required: false,
+    external_provider_calls: false,
+    client_config_writes_performed: false,
+    plaintext_memory_echoed: false,
+    hosted_saas_live_claim: false,
+    provider_native_memory_canonical: false,
+    provider_deletion_proof: false,
+    model_forgetting_proof: false,
+    benchmark_leadership_claim: false,
+    compliance_certification: false,
+  };
+}
+
+function publicTestDriveStatusSummary(summary, bundleDisplay) {
+  return {
+    ...summary,
+    bundle: bundleDisplay,
+    connector_readiness: {
+      ...summary.connector_readiness,
+      bundle: bundleDisplay,
+    },
+    next_recommended_commands: [
+      `enigma remember --bundle ${commandPath(bundleDisplay)} --text-file <path>`,
+      `enigma search --bundle ${commandPath(bundleDisplay)} --query <text>`,
+      `enigma context --bundle ${commandPath(bundleDisplay)} --query <text>`,
+      `enigma verify --bundle ${commandPath(bundleDisplay)}`,
+      `enigma connect <client> --bundle ${commandPath(bundleDisplay)}`,
+    ],
+  };
+}
+
+function publicTestDriveSearchSummary(summary, bundleDisplay) {
+  return {
+    ...summary,
+    bundle: bundleDisplay,
+  };
+}
+
+function staticSetupSelection(requestedSelection) {
+  return {
+    ...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,
+  };
+}
+
+export async function testDriveCommand(flags, io) {
+  const outDirInput = pathFlag(flags, ['out-dir', 'outDir'], DEFAULT_TEST_DRIVE_DIR);
+  const bundleInput = pathFlag(flags, ['bundle', 'file'], testDriveBundleDisplay(outDirInput));
+  const overwrite = booleanFlag(flags, ['overwrite'], false);
+  const dryRun = booleanFlag(flags, ['dry-run', 'dryRun'], false);
+  const outputs = testDriveOutputs(outDirInput, bundleInput);
+  ensureDistinctOutputPaths(outputs.outputs.map((output) => output.path));
+  if (!dryRun) await assertCanWriteQuickstartOutputs(outputs.outputs, overwrite);
+
+  const artifacts = await buildQuickstartArtifacts(flags, {
+    bundleInput,
+    outDirInput,
+    overwrite,
+    write: false,
+    checkExisting: false,
+  });
+  const requestedSelection = setupClientIds(flags);
+  const selection = requestedSelection.auto
+    ? await setupAutoClientSelection(flags, artifacts, DEFAULT_SETUP_CLIENTS, 'auto')
+    : staticSetupSelection(requestedSelection);
+  const demoMemoryAddr = firstActiveMemoryAddress(artifacts.vault);
+  const crossModelLimit = integerFlag(flags, ['limit'], 'limit', 1);
+  if (crossModelLimit < 1) throw new Error('--limit must be at least 1.');
+  const receiptCountBeforeProfiles = Array.isArray(artifacts.vault.receipts) ? artifacts.vault.receipts.length : 0;
+  const profiles = buildCrossModelProfileSummaries({
+    vault: artifacts.vault,
+    passport: artifacts.passport,
+    demoMemoryAddr,
+    limit: crossModelLimit,
+  });
+  const finalExport = exportBundle({ vault: artifacts.vault, includePlaintext: false });
+  const finalBundle = finalExport.bundle ?? finalExport;
+  const finalVerifyReport = verifyBundle(finalBundle);
+  const crossModelReport = {
+    ok: true,
+    schema: 'enigma.cross_model_demo.v1',
+    command: 'enigma demo cross-model',
+    story: 'One local Enigma memory is packaged as public-safe context pack references and receipts for ChatGPT, Claude, Kimi, Cursor, and a local LLM. No provider is called.',
+    bundle_ref: bundleInput,
+    bundle_supplied: true,
+    bundle_created: true,
+    demo_only_vault: true,
+    memory_source: 'test_drive_demo',
+    demo_memory_addr: demoMemoryAddr,
+    profile_count: profiles.length,
+    profiles,
+    memory_count: activeMemoryCount(artifacts.vault),
+    receipt_count: Array.isArray(finalBundle.receipts) ? finalBundle.receipts.length : 0,
+    generated_receipt_count: (Array.isArray(finalBundle.receipts) ? finalBundle.receipts.length : 0) - receiptCountBeforeProfiles,
+    provider_credentials_required: false,
+    provider_native_memory_canonical: false,
+    out_written: !dryRun,
+    claim_boundaries: { ...CROSS_MODEL_CLAIM_BOUNDARIES },
+  };
+  const rawStatusSummary = passportStatusReport({
+    bundlePath: outputs.bundlePath,
+    vault: artifacts.vault,
+    passport: artifacts.passport,
+    stored: {
+      owner: {
+        subject_id: artifacts.vault.subject_id,
+        display_name: artifacts.vault.display_name,
+      },
+    },
+  });
+  const statusSummary = publicTestDriveStatusSummary(rawStatusSummary, bundleInput);
+  const rawSearchSummary = memorySearchReport({
+    bundlePath: outputs.bundlePath,
+    vault: artifacts.vault,
+    query: 'local proof bundle',
+    limit: 3,
+    includeContent: false,
+    now: getFlag(flags, ['now'], '2026-01-01T00:00:00.000Z'),
+  });
+  const searchSummary = publicTestDriveSearchSummary(rawSearchSummary, bundleInput);
+
+  if (!dryRun) {
+    await writeJson(outputs.bundlePath, finalBundle);
+    await writeJson(outputs.contextPackPath, publicContextPackSummary(artifacts.contextPack));
+    await writeJson(outputs.exportPath, finalBundle);
+    await writeJson(outputs.verifyReportPath, finalVerifyReport);
+    await writeJson(outputs.crossModelReportPath, crossModelReport);
+  }
+
+  const flowCommands = testDriveFlowCommands({
+    bundleDisplay: bundleInput,
+    outDirInput,
+    crossModelReportDisplay: outputs.crossModelReportDisplay,
+    overwrite,
+  });
+  const nextCommands = testDriveNextCommands(bundleInput, outputs.crossModelReportDisplay);
+  const files = testDriveFileSummaries(outputs.artifacts, !dryRun);
+  const packageJson = await readPackageJson();
+  const ok = finalVerifyReport.ok === true && crossModelReport.ok === true && statusSummary.ok === true && searchSummary.ok === true;
+  print({
+    ok,
+    schema: 'enigma.test_drive.v1',
+    command: 'enigma test-drive',
+    dry_run: dryRun,
+    out_dir: outDirInput,
+    bundle: bundleInput,
+    install_command: `npm install -g ${packageJson.name ?? 'enigma-memory'}`,
+    release_target: '0.1.11',
+    artifacts_written: !dryRun,
+    client_configs_written: false,
+    client_config_write_required: false,
+    memory_plaintext_echoed: false,
+    provider_credentials_required: false,
+    hosted_saas_live: false,
+    files,
+    files_written: dryRun ? [] : files.map((file) => file.path),
+    files_planned: files.map((file) => file.path),
+    commands_run: dryRun ? [] : flowCommands,
+    commands_planned: dryRun ? flowCommands : [],
+    next_commands: nextCommands,
+    benchmark_pointers: testDriveBenchmarkPointers(),
+    setup_summary: {
+      schema: 'enigma.setup.v1',
+      artifacts_written: !dryRun,
+      bundle: bundleInput,
+      context_pack: outputs.contextPackDisplay,
+      export: outputs.exportDisplay,
+      verify_report: outputs.verifyReportDisplay,
+      selected_clients: selection.clients,
+      client_selection: publicSetupClientSelection(selection),
+      client_configs_written: false,
+      provider_credentials_required: false,
+      memory_plaintext_echoed: false,
+      memory_count: Array.isArray(finalBundle.memory_objects) ? finalBundle.memory_objects.length : 0,
+      receipt_count: Array.isArray(finalBundle.receipts) ? finalBundle.receipts.length : 0,
+      context_item_count: Array.isArray(artifacts.contextPack.memories) ? artifacts.contextPack.memories.length : 0,
+      verify_ok: finalVerifyReport.ok === true,
+    },
+    status_summary: statusSummary,
+    search_summary: searchSummary,
+    cross_model_summary: crossModelReport,
+    claim_boundaries: testDriveClaimBoundaries(),
+  }, io);
+  return ok ? 0 : 1;
+}
+
 async function exportCommand(flags, io) {
   const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
   const { vault } = await loadState(bundlePath);
@@ -1945,6 +2269,7 @@ function usage() {
       'init',
       'setup',
       'quickstart',
+      'test-drive',
       'demo cross-model',
       'doctor',
       'install',
@@ -2024,6 +2349,13 @@ function usage() {
       '--memory-text <text>': 'Inline demo memory text for non-private demos only.',
       '--overwrite': 'Replace existing quickstart output files.',
     },
+    test_drive_options: {
+      '--out-dir <path>': `Isolated demo directory. Defaults to ${DEFAULT_TEST_DRIVE_DIR}.`,
+      '--bundle <path>': `Bundle JSON to create. Defaults to ${DEFAULT_TEST_DRIVE_DIR}/${DEFAULT_TEST_DRIVE_BUNDLE_NAME}.`,
+      '--client <id|auto>': 'Client setup planning passthrough. No client config files are written by test-drive.',
+      '--overwrite': 'Replace existing test-drive artifact files.',
+      '--dry-run': 'Plan the local test drive without writing artifacts.',
+    },
     cross_model_demo_options: {
       '--bundle <path>': `Reuse a local Enigma bundle. If omitted, ${DEFAULT_CROSS_MODEL_DEMO_BUNDLE} is recreated as a demo-only local vault.`,
       '--memory-file <path>': 'Seed the demo from a local file without echoing plaintext. Alias: --text-file.',
@@ -2098,7 +2430,7 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
   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 === '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'))) {
+  if ((flags.has('help') || argv.includes('-h')) && (command === 'setup' || command === 'test-drive' || 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;
   }
@@ -2106,6 +2438,7 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     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 === 'test-drive') return await testDriveCommand(flags, io);
     if (command === 'demo' && subcommand === 'cross-model') return await crossModelDemoCommand(flags, io);
     if (command === 'doctor') return await doctorCommand(flags, io);
     if (command === 'install') return await installCommand(flags, io);

package/docs/developer-ecosystem.md

@@ -2,30 +2,37 @@
 
 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
+## Public test-drive 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 test-drive --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.
+`enigma test-drive --overwrite` is zero-credential, local-only, and public-safe by default. It writes an isolated demo under `.enigma/test-drive`, keeps the default bundle inside that directory, emits one JSON summary, and does not print raw private memory plaintext. Use `--dry-run` to preview without writing or `--out-dir <path>` to choose another isolated demo directory.
+
+The test drive runs the local proof/demo path only: setup artifacts, search/status output, a cross-model demo report, and benchmark pointers. It does not call external providers, contact hosted Enigma SaaS, require OpenAI/Anthropic/Cloudflare credentials, create accounts, or write third-party client configs. Keep public claims bounded to local Enigma-controlled vault state, receipts, checkpoints, committed roots, exported bundle shape, and declared boundary operations.
 
-To let setup auto-detect installed or already-configured clients and report the connector plan without mutating client configs:
+To explicitly connect real local clients that are already installed or already configured:
 
 ```sh
-enigma setup --client auto --overwrite
+enigma setup --connect-installed --overwrite
 ```
 
-To explicitly write connector entries for installed/config-present clients only:
+`--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.
+
+## CLI memory passport loop
+
+After the public test drive, create a regular local workspace when you want day-to-day CLI usage:
 
 ```sh
-enigma setup --connect-installed --overwrite
+npm install -g enigma-memory
+enigma setup --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.
+`enigma setup --overwrite` is the safe default for a regular local workspace. 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.
 
 After setup, use the same local vault from the CLI or connected clients:
 
@@ -60,15 +67,16 @@ 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.10` package, runs:
+The CI example installs Node 24, installs the published `enigma-memory@0.1.11` package, runs:
 
 ```sh
+npx --yes --package enigma-memory enigma test-drive --overwrite
 npx --yes --package enigma-memory enigma setup --overwrite
 npx --yes --package enigma-memory enigma doctor
 npm run benchmark:memory-suite -- --out benchmark-report.json
 ```
 
-and then runs a small ESM import smoke. It does not require GitHub secrets, cloud provider credentials, npm tokens, private bundles, local path assumptions, or official dataset network downloads in normal CI. The benchmark step writes a public-safe local JSON report using schema `enigma.memory_benchmark_suite.v1`; see the benchmark reproducibility guide for claim boundaries and the requirements for any future live third-party comparison.
+and then runs a small ESM import smoke. It does not require GitHub secrets, cloud provider credentials, npm tokens, private bundles, local path assumptions, hosted Enigma SaaS, external memory-provider calls, or official dataset network downloads in normal CI. The test-drive and benchmark steps write public-safe local JSON reports; see the benchmark reproducibility guide for claim boundaries and the requirements for any future live third-party comparison.
 
 The workflow also includes optional official-dataset benchmark preparation steps gated behind the manual `workflow_dispatch` input `run_standard_benchmark: true`. Normal `push` and `pull_request` runs skip them, so official dataset downloads are not required in normal CI. Enable the manual path only after the repository has reviewed network use and dataset-license handling:
 
@@ -84,7 +92,7 @@ Use the workflow as a template in a consumer repository. It is intentionally lim
 
 ## MCP client loop
 
-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.
+The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. Run `enigma test-drive --overwrite` first if you want a zero-credential local proof before touching real client configs. 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:
 

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.10`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, settlement artifacts, and hosted-cloud contract packets are package-level developer surfaces. They are not evidence of hosted Enigma cloud, live customer API key issuance, 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.11`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, settlement artifacts, and hosted-cloud contract packets are package-level developer surfaces. They are not evidence of hosted Enigma cloud, live customer API key issuance, 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.10",
+  "version": "0.1.11",
   "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.10' });
+const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.11' });
 const JSON_RPC_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 const JSON_RPC_ERROR = Object.freeze({
   INVALID_REQUEST: -32600,

package/scripts/build-hosted-api-key-lifecycle.mjs

@@ -13,7 +13,7 @@ import {
 } from '../packages/hosted-cloud/src/index.js';
 
 export const HOSTED_API_KEY_LIFECYCLE_PACKET_SCHEMA = HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA;
-export const HOSTED_API_KEY_LIFECYCLE_RELEASE_TARGET = '0.1.10';
+export const HOSTED_API_KEY_LIFECYCLE_RELEASE_TARGET = '0.1.11';
 
 const PROVIDED = 'provided';
 const BLOCKED = 'blocked_external_dependency';

package/scripts/build-hosted-customer-lifecycle.mjs

@@ -28,7 +28,7 @@ import {
 } from 'enigma-memory/hosted-cloud';
 
 export const HOSTED_CUSTOMER_LIFECYCLE_PACKET_SCHEMA = HOSTED_CLOUD_CUSTOMER_LIFECYCLE_PACKET_SCHEMA;
-export const HOSTED_CUSTOMER_LIFECYCLE_RELEASE_TARGET = '0.1.10';
+export const HOSTED_CUSTOMER_LIFECYCLE_RELEASE_TARGET = '0.1.11';
 
 const PROVIDED = 'provided';
 const BLOCKED_MISSING = 'blocked_missing_evidence';

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.10';
+export const INSTALLER_ASSET_VERSION = '0.1.11';
 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.10',
+      version: '0.1.11',
     },
     public_safe: true,
     top_k: topK,