enigma-memory 0.1.15 → 0.1.17

package/README.md

@@ -2,112 +2,48 @@
 
 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 `enigma init --dry-run` below. You do not need to understand relay, gateway, mesh, browser, desktop, or hosted infrastructure before trying Enigma locally.
+Start with the Memory Drive loop below — one install, one connect, then health and status verification. You do not need to understand relay, gateway, mesh, browser, desktop, hosted infrastructure, or the proof network 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.
 
-## First run: install and inspect the safe local plan
-
-The top public path is the published npm package plus the first-run planner:
-
-```sh
-npm install -g enigma-memory
-enigma init --dry-run
-```
-
-`enigma init --dry-run` prints a public-safe JSON plan with exact next commands. It does not write local artifacts or third-party client configs, does not require provider credentials, hosted Enigma SaaS, Solana, or a browser extension, and states `provider_credentials_required:false`, `hosted_saas_live:false`, and `raw_memory_printed:false`.
-
-When the plan looks right, create the local Memory Passport artifacts:
-
-```sh
-enigma init --overwrite
-```
-
-The execute path writes only local Enigma artifacts under the workspace `.enigma` path by default. It still does not write Claude, Cursor, Kimi, or other third-party app configs unless you explicitly add `--connect`.
-
-Public demo path, preserved for reviewers who want the isolated proof/demo bundle:
-
-```sh
-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 init --connect --overwrite
-```
-
-`--connect` is the explicit first-run client-config write path. With default client selection it skips missing client configs instead of creating every default client config.
-
-## Enigma Proof Network
-
-Enigma Proof Network is the public proof layer for AI memory: local tools can package privacy-preserving roots, refs, counts, signatures, scoped capability grants, revocations, and benchmark attestations without exposing raw memory, prompts, transcripts, completions, embeddings, tenant names, private keys, provider responses, or provider credentials.
-
-The `enigma chain anchor|grant|revoke|attest|verify` commands are local planning and verification commands. They emit public-safe JSON with `transaction_submitted:false` and `raw_memory_on_chain:false`; they do not submit Solana transactions, deploy hosted SaaS, create accounts, or call external providers.
-
-Start with the category narrative in [`docs/market-category-narrative.md`](docs/market-category-narrative.md), then read the technical overview in [`docs/proof-network.md`](docs/proof-network.md), use its [Solana role](docs/proof-network.md#solana-role) section for the Solana-ready anchoring boundary, and read [`docs/proof-network-faq.md`](docs/proof-network-faq.md) for claim boundaries.
-
 ## Install once, use everywhere
 
 Prerequisites:
 
 - Node.js `>=24`
-- No database, package registry account, provider credential, or cloud credential for the local test-drive or setup paths
+- No database, package registry account, provider credential, cloud credential, hosted Enigma account, or external account for the local setup path
 - Git only when you choose the advanced source-checkout path
 
-Use Enigma as a one-time AI Memory Passport setup: install the package, inspect the local plan, create the local Enigma workspace once, then use the same memory/search/context/verify/connect loop from any supported client.
+Use Enigma as your private Memory Drive for AI: install once, connect the AI clients you already have, then inspect drive health and passport status before remembering, retrieving, packaging, and verifying context.
 
 ```sh
 npm install -g enigma-memory
-enigma init --dry-run
-enigma init --overwrite
-```
-
-`enigma init --overwrite` is the safe default for creating a regular local workspace after reviewing the plan. 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 first-run setup detect installed or already-configured clients and show the connector plan without mutating client configs:
-
-```sh
-enigma init --client auto --dry-run
+enigma init
+enigma setup --client auto --connect-installed --overwrite
+enigma drive health
+enigma status
+enigma remember --text-file ./memory.txt
+enigma search --query "project context"
+enigma context --query "project context" --optimize
+enigma verify --export ./.enigma/export.json
 ```
 
-`--client auto` selects clients found by connector detection and falls back to the default setup client list when none are present. The init output lists which clients were selected, which were skipped, and why.
-
-Only when you are ready to explicitly write connector entries for installed/config-present clients:
-
-```sh
-enigma init --connect --overwrite
-```
+`enigma init` is the credential-free first run: it creates the local `.enigma` workspace, bundle, and proof artifacts and emits public-safe JSON without provider or cloud credentials. `enigma setup --client auto --connect-installed --overwrite` then configures the drive and merges the `mcpServers.enigma` entry into every installed/config-present client it detects (Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo, OpenCode, generic MCP). It skips clients that are not installed and never creates configs from scratch; preview with `--dry-run` first if you want to see which clients will be written. The same commands run on Windows PowerShell because the npm global install adds an `enigma.cmd` shim. Neither command prints raw memory plaintext.
 
-`--connect` implies installed/config-present client selection when no explicit `--client` is supplied and is an explicit client-config write flag. It skips missing client configs instead of creating every default client config. Existing setup commands remain available: `enigma setup --overwrite`, `enigma setup --client auto --overwrite`, and `enigma setup --connect-installed --overwrite`. Existing explicit connector writes remain available through `enigma connect <client>` without `--dry-run`; keep `--dry-run` while reviewing a single planned MCP entry.
+`enigma drive health` reports a SMART-style memory-drive health packet — freshness, duplicate rate, tombstone backlog, stale derived artifacts, receipt coverage, and connector health — computed from local metadata only, with no network calls or private payloads. It is part of the Memory Drive surface in this release; in any build where it is unavailable, `enigma status` and `enigma doctor` cover the same local passport counts, roots, and connector readiness.
 
-After init or setup, use the same local vault from the CLI or connected clients:
+`enigma status` shows passport counts, roots, owner display fields, and connector readiness. 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.
 
-```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 Proof Network
 
-`enigma context --query ...` automatically applies local relevance scoring; `--optimize` is still accepted when you want explicit optimizer evidence or token/cost bounds.
+Enigma Proof Network is the public proof layer for AI memory: local tools can package privacy-preserving roots, refs, counts, signatures, scoped capability grants, revocations, and benchmark attestations without exposing raw memory, prompts, transcripts, completions, embeddings, tenant names, private keys, provider responses, or provider credentials.
 
-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.
+The `enigma chain anchor|grant|revoke|attest|verify` commands are local planning and verification commands. They emit public-safe JSON with `transaction_submitted:false` and `raw_memory_on_chain:false`; they do not submit Solana transactions, deploy hosted SaaS, create accounts, or call external providers.
 
-One-off public test drive without a global install:
+Start with the category narrative in [`docs/market-category-narrative.md`](docs/market-category-narrative.md), then read the technical overview in [`docs/proof-network.md`](docs/proof-network.md), use its [Solana role](docs/proof-network.md#solana-role) section for the Solana-ready anchoring boundary, and read [`docs/proof-network-faq.md`](docs/proof-network-faq.md) for claim boundaries.
 
-```sh
-npx --yes --package enigma-memory enigma test-drive --overwrite
-```
 
 ## Advanced/source-only path
 
@@ -214,7 +150,7 @@ Supported connector profiles are:
 - `opencode`
 - `generic-mcp`
 
-After `enigma init --dry-run` previews the local package path and `enigma init --overwrite` creates a regular local workspace, preview a client connection before writing anything:
+The one-command path above (`enigma setup --client auto --connect-installed --overwrite`) already connects every installed/config-present client. To connect or preview a single client instead:
 
 ```sh
 enigma connect claude-desktop --dry-run
@@ -223,11 +159,59 @@ enigma connect kimi-code --dry-run
 enigma connect generic-mcp --dry-run
 ```
 
-For the one-time setup flow, `enigma init --client auto --dry-run` 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 init --connect --overwrite` is the explicit init-time write path for installed/config-present clients by default; missing configs are skipped rather than created. The older `enigma setup --client auto --overwrite` and `enigma setup --connect-installed --overwrite` commands remain available.
+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. Bare `enigma setup` without `--connect-installed` or `--write-connectors` never writes third-party app configs.
 
-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 init/setup command never writes third-party app configs.
+Copy-paste MCP snippets:
+
+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"
+      }
+    }
+  }
+}
+```
 
-Manual MCP entry for Claude Desktop, Cursor, Kimi Code, or any generic MCP client:
+Generic MCP:
 
 ```json
 {

package/apps/cli/bin/enigma.mjs

@@ -6,7 +6,7 @@ import { access, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promi
 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';
+import { createPassport, compileContextPack, createMemoryDriveHealthReport } from '../../../packages/passport/src/index.js';
 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';
@@ -36,11 +36,15 @@ import {
   createCapabilityGrant,
   createCapabilityRevocation,
   createProofNetworkAnchorBatch,
+  createRegistryEntry,
+  createRegistryBatch,
   sha256Json as proofNetworkSha256Json,
   validateBenchmarkAttestation,
   validateCapabilityGrant,
   validateCapabilityRevocation,
   validateProofNetworkAnchorBatch,
+  validateRegistryEntry,
+  validateRegistryBatch,
   validateProofNetworkPacket,
 } from '../../../packages/proof-network/src/index.js';
 
@@ -53,7 +57,7 @@ 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 DEFAULT_SETUP_CLIENTS = Object.freeze(['generic-mcp', 'claude-desktop', 'cursor', 'kimi-code', 'vscode-cline']);
 const SETUP_CLAIM_BOUNDARIES = Object.freeze({
   local_only: true,
   provider_credentials_required: false,
@@ -1043,15 +1047,32 @@ function publicSetupError(error, rawDisplays, publicDisplays) {
   return new Error(message);
 }
 
+function oneCommandInstallConnect(bundleDisplay = DEFAULT_BUNDLE, outDirDisplay = dirname(bundleDisplay)) {
+  const parts = ['npm install -g enigma-memory && enigma setup'];
+  if (bundleDisplay !== DEFAULT_BUNDLE) parts.push(`--bundle ${commandPath(bundleDisplay)}`);
+  if (outDirDisplay !== dirname(bundleDisplay)) parts.push(`--out-dir ${commandPath(outDirDisplay)}`);
+  const base = parts.join(' ');
+  return {
+    installed_clients: `${base} --client auto --connect-installed --overwrite`,
+    claude_desktop: `${base} --client claude-desktop --write-connectors --overwrite`,
+    cursor: `${base} --client cursor --write-connectors --overwrite`,
+    kimi_code: `${base} --client kimi-code --write-connectors --overwrite`,
+    vscode_cline: `${base} --client vscode-cline --write-connectors --overwrite`,
+  };
+}
+
 function setupNextCommands(bundleInput, exportDisplay, clients, writeConnectors) {
   const primaryClient = clients[0] ?? DEFAULT_SETUP_CLIENTS[0];
+  const bundle = commandPath(bundleInput);
   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 status --bundle ${bundle}`,
+    `enigma drive health --bundle ${bundle}`,
+    `enigma remember --bundle ${bundle} --text-file ./memory.txt`,
+    `enigma search --bundle ${bundle} --query "project context"`,
+    `enigma context --bundle ${bundle} --query "project context"`,
     `enigma verify --export ${commandPath(exportDisplay)}`,
   ];
-  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${commandPath(bundleInput)} --dry-run`);
+  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${bundle} --dry-run`);
   return commands;
 }
 
@@ -1072,10 +1093,13 @@ function initNextCommands({ dryRun, bundleDisplay, outDirDisplay, exportDisplay,
 
 function doctorNextCommands(bundleDisplay, client) {
   const clientId = client ?? DEFAULT_SETUP_CLIENTS[0];
+  const bundle = commandPath(bundleDisplay);
   return [
-    `enigma setup --bundle ${commandPath(bundleDisplay)}`,
-    `enigma doctor --bundle ${commandPath(bundleDisplay)} --client ${clientId}`,
-    `enigma connect ${clientId} --bundle ${commandPath(bundleDisplay)}`,
+    `enigma status --bundle ${bundle}`,
+    `enigma drive health --bundle ${bundle}`,
+    `enigma setup --bundle ${bundle}`,
+    `enigma doctor --bundle ${bundle} --client ${clientId}`,
+    `enigma connect ${clientId} --bundle ${bundle}`,
   ];
 }
 
@@ -1297,6 +1321,7 @@ export async function setupCommand(flags, io) {
     client_selection: publicSetupClientSelection(selection),
     connector_write_skips: connectorWriteSkips(connectors),
     connectors,
+    one_command_install_connect: oneCommandInstallConnect(displays.bundle, publicPathDisplay(outDirInput, 'out-dir')),
     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)),
@@ -1675,6 +1700,27 @@ async function statusCommand(flags, io) {
   print(passportStatusReport({ bundlePath, stored, vault, passport }), io);
   return 0;
 }
+async function readOptionalJsonInput(flags, names) {
+  const path = getFlag(flags, names);
+  if (!path) return null;
+  if (!(await fileExists(path))) return null;
+  return readJson(path);
+}
+
+async function driveHealthCommand(flags, io) {
+  const bundlePath = resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE)));
+  const { vault, passport } = await loadState(bundlePath);
+  const benchmarkSummary = await readOptionalJsonInput(flags, ['benchmark-summary', 'benchmarkSummary']);
+  const connectorSummary = await readOptionalJsonInput(flags, ['connector-summary', 'connectorSummary']);
+  const replicas = await readOptionalJsonInput(flags, ['replicas']);
+  const latestAnchorBatchRef = getFlag(flags, ['latest-anchor-batch-ref', 'latestAnchorBatchRef']);
+  const now = getFlag(flags, ['now'], '2026-06-25T00:00:00.000Z');
+  const report = createMemoryDriveHealthReport({ vault, passport, benchmarkSummary, connectorSummary, replicas, latestAnchorBatchRef, now });
+  const outPath = getFlag(flags, ['out']);
+  if (outPath) await writeJson(outPath, report);
+  print(report, io);
+  return 0;
+}
 
 function testDrivePathDisplay(outDirInput, name) {
   return isAbsolute(outDirInput) ? join(outDirInput, name) : quickstartPathDisplay(outDirInput, name);
@@ -1731,6 +1777,7 @@ function testDriveNextCommands(bundleDisplay, crossModelReportDisplay) {
   const quotedReport = commandPath(crossModelReportDisplay);
   return [
     `enigma status --bundle ${quotedBundle}`,
+    `enigma drive health --bundle ${quotedBundle}`,
     `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
     `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
     'enigma setup --overwrite',
@@ -1745,6 +1792,7 @@ function testDriveFlowCommands({ bundleDisplay, outDirInput, crossModelReportDis
   return [
     `enigma quickstart --bundle ${quotedBundle} --out-dir ${quotedOutDir}${overwriteSuffix}`,
     `enigma status --bundle ${quotedBundle}`,
+    `enigma drive health --bundle ${quotedBundle}`,
     `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
     `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
   ];
@@ -1938,7 +1986,7 @@ export async function testDriveCommand(flags, io) {
     out_dir: outDirInput,
     bundle: bundleInput,
     install_command: `npm install -g ${packageJson.name ?? 'enigma-memory'}`,
-    release_target: '0.1.15',
+    release_target: '0.1.17',
     artifacts_written: !dryRun,
     client_configs_written: false,
     client_config_write_required: false,
@@ -2122,6 +2170,7 @@ export async function installCommand(flags, io) {
     mcp_command: connectorOptions(flags).mcpCommand ?? 'enigma-mcp',
     clients: profiles,
     mcp_config_snippets: snippets,
+    one_command_install_connect: oneCommandInstallConnect(bundlePath, dirname(bundlePath)),
     out: out && out !== true ? resolve(String(out)) : undefined,
   }, io);
   return 0;
@@ -2389,6 +2438,8 @@ function chainArtifactValidator(artifact) {
   if (schema === 'enigma.proof_network.capability_revocation.v1') return [schema, validateCapabilityRevocation];
   if (schema === 'enigma.proof_network.benchmark_attestation.v1') return [schema, validateBenchmarkAttestation];
   if (schema === 'enigma.proof_network.packet.v1') return [schema, validateProofNetworkPacket];
+  if (schema === 'enigma.proof_network.registry_entry.v1') return [schema, validateRegistryEntry];
+  if (schema === 'enigma.proof_network.registry_batch.v1') return [schema, validateRegistryBatch];
   throw new Error(schema ? 'Unsupported proof-network artifact schema.' : 'Unsupported proof-network artifact schema: missing.');
 }
 
@@ -2445,11 +2496,11 @@ async function readSolanaKeypair(path) {
   } catch {
     throw new Error('Unable to read a valid Solana --keypair JSON array.');
   }
-  if (!Array.isArray(parsed) || parsed.length === 0) throw new Error('Solana --keypair must be a JSON array of secret-key bytes.');
+  if (!Array.isArray(parsed) || parsed.length !== 64) throw new Error('Solana --keypair must be a JSON array of 64 secret-key bytes.');
   const bytes = new Uint8Array(parsed.length);
   for (let i = 0; i < parsed.length; i += 1) {
     const value = parsed[i];
-    if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error('Solana --keypair must be a JSON array of secret-key bytes.');
+    if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error('Solana --keypair must be a JSON array of 64 secret-key bytes.');
     bytes[i] = value;
   }
   return bytes;
@@ -2686,6 +2737,60 @@ export async function chainVerifyCommand(flags, io, positionalFile = undefined)
   return result.ok === true ? 0 : 1;
 }
 
+export async function chainRegisterCommand(flags, io) {
+  const entryType = requireFlag(flags, ['entry-type', 'entryType', 'type'], 'entry-type');
+  const artifactHashFlag = getFlag(flags, ['artifact-hash', 'artifactHash', 'digest-ref', 'digestRef', 'artifact-ref', 'artifactRef']);
+  const artifactFile = getFlag(flags, ['artifact-file', 'artifactFile']);
+  const resolvedArtifactHash = artifactHashFlag || (artifactFile ? await sha256PublicFile(resolve(String(artifactFile))) : undefined);
+  if (!resolvedArtifactHash) throw new Error('Missing required --artifact-hash or --artifact-file.');
+  const digestRefs = flagValues(flags, ['digest-ref', 'digest-refs', 'digestRef', 'digestRefs', 'root', 'roots']);
+  const entry = createRegistryEntry({
+    entry_type: entryType,
+    artifact_hash: resolvedArtifactHash,
+    artifact_schema_ref: requireFlag(flags, ['artifact-schema-ref', 'artifactSchemaRef', 'schema-ref', 'schemaRef'], 'artifact-schema-ref'),
+    digest_refs: digestRefs.length ? digestRefs : resolvedArtifactHash,
+    signer_refs: flagValues(flags, ['signer', 'signers', 'signer-ref', 'signerRef', 'signer-refs', 'signerRefs', 'attestor', 'attestor-ref', 'attestorRef']),
+    registry_ref: getFlag(flags, ['registry-ref', 'registryRef', 'marketplace-ref', 'marketplaceRef']),
+    entry_ref: getFlag(flags, ['entry-ref', 'entryRef']),
+    entry_count: getFlag(flags, ['entry-count', 'entryCount', 'count']),
+    created_at: getFlag(flags, ['created-at', 'createdAt', 'registered-at', 'registeredAt']),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+  });
+  assertChainArtifact(validateRegistryEntry, entry);
+  return chainWriteOrPrint(flags, io, entry, {
+    artifact_type: entry.schema,
+    registry_entry_id: entry.registry_entry_id,
+    registry_entry_hash: entry.registry_entry_hash ?? proofNetworkSha256Json(entry),
+  });
+}
+
+export async function chainRegistryCommand(flags, io, positionalFile = undefined) {
+  const entryPaths = flagValues(flags, ['entry', 'entries', 'entry-file', 'entryFile']);
+  const positionalEntry = positionalFile && !String(positionalFile).startsWith('--') ? positionalFile : undefined;
+  const paths = entryPaths.length ? entryPaths : (positionalEntry ? [positionalEntry] : []);
+  if (paths.length === 0) throw new Error('Missing required --entry <registry-entry.json>.');
+  const entries = [];
+  for (const entryPath of paths) {
+    const entry = await readJson(resolve(entryPath));
+    assertNoPrivateProofPayload(entry);
+    entries.push(entry);
+  }
+  const batch = createRegistryBatch({
+    entries,
+    registry_ref: getFlag(flags, ['registry-ref', 'registryRef', 'marketplace-ref', 'marketplaceRef']),
+    created_at: getFlag(flags, ['created-at', 'createdAt']),
+    transaction_submitted: false,
+    raw_memory_on_chain: false,
+  });
+  assertChainArtifact(validateRegistryBatch, batch);
+  return chainWriteOrPrint(flags, io, batch, {
+    artifact_type: batch.schema,
+    registry_batch_id: batch.registry_batch_id,
+    registry_batch_hash: batch.registry_batch_hash ?? proofNetworkSha256Json(batch),
+  });
+}
+
 
 export async function meterEventCommand(flags, io) {
   const event = createUsageEvent({
@@ -2911,6 +3016,9 @@ function usage() {
       'chain attest',
       'chain verify',
       'chain submit-solana',
+      'chain register',
+      'chain registry',
+      'drive health',
     ],
     connector_options: {
       '--bundle <path>': 'Absolute local Enigma vault bundle path rendered as ENIGMA_BUNDLE.',
@@ -2955,6 +3063,15 @@ function usage() {
       '--dry-run': 'Plan setup without writing local artifacts or client configs.',
       '--write-connectors': 'Also write selected client MCP config files. Defaults to false.',
     },
+    install_options: {
+      'one-command installed clients': 'npm install -g enigma-memory && enigma setup --client auto --connect-installed --overwrite',
+      'one-command Claude Desktop': 'npm install -g enigma-memory && enigma setup --client claude-desktop --write-connectors --overwrite',
+      'one-command Cursor': 'npm install -g enigma-memory && enigma setup --client cursor --write-connectors --overwrite',
+      'one-command Kimi Code': 'npm install -g enigma-memory && enigma setup --client kimi-code --write-connectors --overwrite',
+      'one-command VS Code Cline': 'npm install -g enigma-memory && enigma setup --client vscode-cline --write-connectors --overwrite',
+      '--client <id>': 'Limit generated MCP snippets to one supported client.',
+      '--out <path>': 'Write generated MCP snippets to a JSON file for review without hand-editing client config JSON.',
+    },
     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.',
@@ -3022,9 +3139,26 @@ function usage() {
       revoke: 'enigma chain revoke --grant-hash <sha256:...> --reason <public-reason-code> [--revocation-ref <public-ref>] [--out <file>]',
       attest: 'enigma chain attest (--report-hash <sha256:...> | --report-file <report.json>) --dataset-ref <sha256:...> --runner-ref <public-runner-ref> --package-ref <public-package-ref> [--score name=value] [--out <file>]',
       verify: 'enigma chain verify --file <proof-artifact.json>',
-      submit_solana: 'enigma chain submit-solana --file <proof-artifact.json> --cluster <devnet|testnet|mainnet-beta|localnet> [--rpc <url>] [--execute --keypair <solana-keypair.json>]',
+      register: 'enigma chain register --entry-type <anchor_batch|benchmark_attestation|connector_conformance|health_report|operator_receipt|settlement_job> (--artifact-hash <sha256:...> | --artifact-file <artifact.json>) --artifact-schema-ref <schema-id> [--digest-ref <sha256:...>] [--signer <public-ref>] [--registry-ref <public-ref>] [--entry-ref <public-ref>] [--entry-count <n>] [--out <file>]',
+      registry: 'enigma chain registry --entry <registry-entry.json> [--entry <registry-entry.json>] [--registry-ref <public-ref>] [--out <file>]',
+      submit_solana: 'enigma chain submit-solana --file <proof-artifact.json> --cluster <devnet|testnet|mainnet-beta|localnet> [--rpc <url>] [--execute --keypair <solana-cli-64-byte-keypair.json>]',
       boundary: 'Proof Network chain commands default to local planning and dry-run validation. submit-solana only submits a Solana Memo transaction when --execute is passed; it carries compact public-safe commitment/ref JSON, never raw memory or artifact bodies.',
     },
+    memory_drive_health: {
+      command: 'enigma drive health --bundle <path> [--now <iso>] [--benchmark-summary <path>] [--connector-summary <path>] [--replicas <path>] [--latest-anchor-batch-ref <ref>] [--out <file>]',
+      schema: 'enigma.memory_drive_health_report.v1',
+      output_shape: 'SMART-style report: overall_status/overall_score, ten metrics (freshness, duplicate_rate, tombstone_risk, stale_derived_artifacts, retrieval_hit_rate, token_reduction, leakage_scan, receipt_coverage, connector_health, sync_fork_risk), each with status/score/observed/thresholds/evidence_refs/recommended_actions, plus roots, privacy_boundaries, claim_boundaries, and a conservative proof_network_ready block.',
+      options: {
+        '--bundle <path>': 'Local Enigma vault bundle to inspect. Defaults to .enigma/bundle.json.',
+        '--now <iso>': 'ISO-8601 timestamp used for age calculations. Defaults to a deterministic timestamp.',
+        '--benchmark-summary <path>': 'Optional JSON file with public-safe retrieval probes (probe_count, top_k, hit_at_k, exact_coverage, abstention_correctness). Omit to default gracefully.',
+        '--connector-summary <path>': 'Optional JSON file with public-safe connector health (connector_count, healthy_connector_count, lagging_connector_count, error_rate_24h, cursor_gap_count). Omit to default gracefully.',
+        '--replicas <path>': 'Optional JSON file of replica root reports for sync fork risk.',
+        '--latest-anchor-batch-ref <ref>': 'Optional public-safe proof-network anchor batch ref for receipt coverage.',
+        '--out <path>': 'Write the JSON report to a file in addition to stdout.',
+      },
+      boundary: 'Computed locally from public-safe counters, roots, receipt metadata, tombstones, and derived/context-pack refs only. No network or chain calls; transaction_submitted and raw_memory_on_chain are always false. It is local operational evidence, not provider-deletion, model-forgetting, compliance, or live-chain-settlement proof.',
+    },
     relay_gateway_options: {
       '--host <host>': 'Bind host. Defaults to 127.0.0.1.',
       '--port <port>': `Bind port. Defaults to ${DEFAULT_RELAY_PORT} for relay and ${DEFAULT_GATEWAY_PORT} for gateway.`,
@@ -3051,10 +3185,10 @@ 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', 'chain', 'demo', 'passport'];
+  const twoPartCommands = ['boundary', 'mcp', 'mesh', 'enterprise', 'capsule', 'relay', 'gateway', 'connect', 'disconnect', 'import', 'native-host', 'meter', 'settlement', 'chain', 'demo', 'passport', 'drive'];
   const flags = parseArgs(twoPartCommands.includes(command) ? argv.slice(2) : argv.slice(1));
   const positionalFile = optionalPositional(argv[2]);
-  if ((command === 'chain' && (!subcommand || subcommand === '--help' || subcommand === '-h' || flags.has('help'))) || ((flags.has('help') || argv.includes('-h')) && (command === 'init' || 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')))) {
+  if ((command === 'chain' && (!subcommand || subcommand === '--help' || subcommand === '-h' || flags.has('help'))) || ((flags.has('help') || argv.includes('-h')) && (command === 'init' || 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') || (command === 'drive' && subcommand === 'health')))) {
     print(usage(), io);
     return 0;
   }
@@ -3076,6 +3210,7 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     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 === 'drive' && subcommand === 'health') return await driveHealthCommand(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);
@@ -3102,6 +3237,8 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
     if (command === 'chain' && subcommand === 'attest') return await chainAttestCommand(flags, io);
     if (command === 'chain' && subcommand === 'verify') return await chainVerifyCommand(flags, io, positionalFile);
     if (command === 'chain' && subcommand === 'submit-solana') return await chainSubmitSolanaCommand(flags, io, positionalFile);
+    if (command === 'chain' && subcommand === 'register') return await chainRegisterCommand(flags, io);
+    if (command === 'chain' && subcommand === 'registry') return await chainRegistryCommand(flags, io, positionalFile);
     if (command === 'native-host' && subcommand === 'install-plan') return await nativeHostInstallPlanCommand(flags, io);
     if (command === 'mesh' && subcommand === 'demo') return await meshDemoCommand(flags, io);
     if (command === 'enterprise' && subcommand === 'demo') return await enterpriseDemoCommand(flags, io);

package/apps/native-host/README.md

@@ -55,6 +55,26 @@ The CLI manifest generator and install-plan preview are the recommended path bec
 
 4. If your browser does not inherit the `ENIGMA_BUNDLE` user environment, create a small local wrapper that sets `ENIGMA_BUNDLE` and then execs the absolute `enigma-native-host` path. Point the manifest `path` to that wrapper. Keep the wrapper owner-writable only.
 
+
+## Fast MCP client setup
+
+For Claude Desktop, Cursor, Kimi Code, and VS Code Cline, avoid hand-editing MCP JSON. After installing the package, use the CLI to create the local bundle and merge only the Enigma MCP server entry into the selected client config:
+
+```sh
+npm install -g enigma-memory && enigma setup --client claude-desktop --write-connectors --overwrite
+npm install -g enigma-memory && enigma setup --client cursor --write-connectors --overwrite
+npm install -g enigma-memory && enigma setup --client kimi-code --write-connectors --overwrite
+npm install -g enigma-memory && enigma setup --client vscode-cline --write-connectors --overwrite
+```
+
+To connect only clients whose config files already exist, use:
+
+```sh
+npm install -g enigma-memory && enigma setup --client auto --connect-installed --overwrite
+```
+
+The generated MCP entry uses `enigma-mcp` with `ENIGMA_BUNDLE` pointing at the local bundle. Existing sibling MCP servers are preserved; changed configs are backed up by `enigma connect`.
+
 ## Generate a manifest
 
 Use the CLI generator instead of hand-editing JSON: