enigma-memory 0.1.15 → 0.1.17

package/docs/developer-ecosystem.md

@@ -1,223 +1,207 @@
-# Developer ecosystem
-
-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.
-
-## 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 test-drive --overwrite
-```
-
-`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 explicitly connect real local clients that are already installed or already configured:
-
-```sh
-enigma setup --connect-installed --overwrite
-```
-
-`--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
-npm install -g enigma-memory
-enigma setup --overwrite
-```
-
-`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:
-
-```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)
-- Node example app: [`examples/node-basic-memory.mjs`](../examples/node-basic-memory.mjs)
-- GitHub Actions example: [`examples/ci/github-actions.yml`](../examples/ci/github-actions.yml)
-- Benchmark reproducibility guide: [`docs/benchmark-reproducibility.md`](./benchmark-reproducibility.md)
-- Generic MCP client template: [`templates/mcp-client-config.json`](../templates/mcp-client-config.json)
-
-## Local SDK loop
-
-Use the SDK when you want an app-owned vault and receipt-backed proof loop:
-
-1. Create a local vault with `createVault`.
-2. Add a generic, non-private memory with `remember`.
-3. Create a passport with `createPassport`.
-4. Compile a receipt-backed context pack with `compileContextPack`.
-5. Export a proof-carrying bundle with `exportBundle`; keep full bundles private unless local import key material has been reviewed and removed.
-6. Verify receipts with `verifyReceiptChain`, `enigma verify`, `enigma-verify`, or MCP `enigma_verify_receipts`.
-
-The example app prints ids, counts, roots, and verification status only. It does not print raw memory text, generated key material, credentials, provider transcripts, or local absolute paths.
-
-## CLI and CI loop
-
-The CI example installs Node 24, installs `enigma-memory` into a disposable npm project, exposes the package benchmark script, then runs:
-
-```sh
-npx enigma test-drive --overwrite
-npx enigma setup --overwrite
-npx 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, 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:
-
-```sh
-node ./node_modules/enigma-memory/scripts/download-standard-benchmarks.mjs --dry-run
-node ./node_modules/enigma-memory/scripts/download-standard-benchmarks.mjs --execute --dataset all --out-dir .enigma/benchmarks/datasets --manifest .enigma/benchmarks/dataset-manifest.json
-node ./node_modules/enigma-memory/scripts/run-standard-memory-benchmarks.mjs --locomo .enigma/benchmarks/datasets/locomo10.json --longmemeval .enigma/benchmarks/datasets/longmemeval_s_cleaned.json --max-locomo-qa 25 --max-longmemeval-items 25 --top-k 5 --out .enigma/standard-memory-benchmark-sample.json
-```
-
-Those commands produce a dataset manifest with source URLs, byte sizes, and SHA-256 hashes plus a standard benchmark report using schema `enigma.standard_memory_benchmark_suite.v1`. The standard runner is retrieval/evidence proxy scoring only: it does not call providers, grade generated answers, or produce competitor scores.
-
-Use the workflow as a template in a consumer repository. It is intentionally limited to install/import/doctor smoke coverage, local proof generation, and deterministic local benchmark evidence by default; it does not publish packages, deploy infrastructure, contact hosted Enigma cloud, call external memory providers, or download official benchmark datasets unless you intentionally enable `run_standard_benchmark` for a manual workflow run.
-
-## Proof Network developer loop
-
-The proof-network path gives integrators a public, privacy-preserving adoption track before any chain transaction or hosted integration exists. The adoption ladder is intentionally simple:
-
-1. Install or invoke the npm package.
-2. Run the local test drive to produce safe roots/receipts/counts.
-3. Generate proof-network chain artifacts from public-safe inputs.
-4. Verify those artifacts locally.
-5. Wire the same artifact contract into a connector, benchmark dashboard, or conformance test.
-
-```sh
-npx --yes --package enigma-memory enigma test-drive --overwrite
-npx --yes --package enigma-memory enigma chain anchor --root sha256:8f8f... --root sha256:9a9a... --ref demo-local-vault --authority demo-public-authority --batch-ref demo-anchor-batch --out .enigma/proof-anchor-batch.json
-npx --yes --package enigma-memory enigma chain grant --subject did:example:agent --capability memory.read --scope demo-scope --resource-ref sha256:8f8f... --policy-hash sha256:7e7e... --expires-at 2026-07-01T00:00:00Z --grant-ref demo-grant --out .enigma/proof-capability-grant.json
-npx --yes --package enigma-memory enigma chain revoke --grant-hash sha256:6d6d... --reason scope-ended --revocation-ref demo-revocation --out .enigma/proof-capability-revocation.json
-npx --yes --package enigma-memory enigma chain attest --report-file benchmark-report.json --dataset-ref sha256:5c5c... --runner-ref enigma-standard-runner --package-ref enigma-memory@0.1.15 --score accuracy=0.92 --out .enigma/proof-benchmark-attestation.json
-npx --yes --package enigma-memory enigma chain verify --file .enigma/proof-anchor-batch.json
-```
-
-`enigma chain anchor`, `grant`, `revoke`, `attest`, and `verify` are local planning commands. They create or validate opaque JSON proof-network artifacts for Solana-ready anchoring, but they do not create accounts, sign with private keys, submit transactions, deploy programs, or call RPC providers. Generated chain artifacts must keep `transaction_submitted:false` and `raw_memory_on_chain:false`; if an example needs a memory reference, use a public-safe commitment or receipt root rather than raw memory, prompts, transcripts, completions, embeddings, ACL bodies, tenant names, provider responses, private keys, seed phrases, or credentials.
-
-Use proof artifacts as the common exchange format for developer integrations:
-
-- **NPM test-drive adopters:** run the test drive, create an anchor batch from local roots/refs, verify the artifact, and attach the JSON to a pull request, demo, or release note without exposing private memory.
-- **Chain artifact builders:** treat `anchor_batch`, `capability_grant`, `capability_revocation`, `benchmark_attestation`, and `packet` as the supported public artifact types. Anchors carry roots/refs/counts for later settlement; grants carry subject, capability, scope, resource refs, policy hashes, and expiry; revocations carry grant hashes and nullifiers; attestations carry report hashes plus dataset, runner, package, and score refs.
-- **Conformance program partners:** build fixtures that accept valid proof-network artifacts and reject artifacts that leak private payload keys or values, omit the false transaction flags, use raw ACL or tenant bodies, or mix raw memory with public chain payloads. A connector should pass conformance before it claims proof-network support.
-- **Benchmark attestation contributors:** hash the benchmark report or pass the report file, then bind it to dataset, runner, and package refs. The attestation makes benchmark evidence portable, but benchmark claims still depend on the benchmark guide's dataset, scoring, and comparison boundaries.
-- **Connector authors:** wallet, agent, MCP, CI, and dashboard connectors can verify packets, display opaque Solana-ready roots, enforce grants before retrieval, publish revocation/nullifier artifacts when access ends, and keep private bundles off-chain while sharing verifiable commitments.
-
-Conformance should stay narrow and testable. A proof-network connector is ready for public examples when it can:
-
-1. accept every supported proof-network artifact shape and return a deterministic validation result;
-2. reject any artifact containing private-looking field names or values before display, upload, signing, or indexing;
-3. preserve `transaction_submitted:false` unless a separate reviewed settlement path actually submits a transaction;
-4. preserve `raw_memory_on_chain:false` for every chain-facing artifact;
-5. enforce capability grant subject, capability, scope, resource-ref, policy-hash, and expiry constraints before retrieval;
-6. accept capability revocations/nullifiers and stop treating revoked grants as usable;
-7. bind benchmark attestations to report hashes/files plus dataset, runner, and package refs without importing the raw benchmark corpus or private model output.
-
-Good first connector projects are deliberately small: a CLI verifier that fails CI on leaked private payloads, a wallet preview that shows only roots/scopes/expiry/nullifiers, an MCP middleware that blocks retrieval without a live grant, a benchmark dashboard that accepts attestation JSON beside a report hash, and a Solana explorer plugin that labels opaque anchor batches without claiming transaction submission.
-
-This path is intentionally copyable: npm install, run a local test drive, generate proof artifacts, verify them, then wire the same public-safe contract into a connector or conformance test. Do not position it as live settlement, provider deletion proof, compliance certification, or benchmark leadership without the separate evidence those claims require.
-
-## MCP client loop
-
-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:
-
-```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": "/absolute/path/to/.enigma/bundle.json"
-      }
-    }
-  }
-}
-```
-
-Do not commit private bundle paths if they reveal local usernames, workspace names, account ids, or other personal details.
-
-## Claim boundaries for developers
-
-Enigma proof artifacts cover Enigma-controlled or Enigma-mediated state: local vault events, receipts, active/tombstoned memory addresses, context-pack retrieval/injection receipts, relay/gateway records, usage events, and settlement receipts.
-
-They do not prove:
-
-- provider-side deletion;
-- model forgetting;
-- compliance certification;
-- token ROI, investment outcome, or provider invoice savings;
-- hosted-cloud readiness from a local demo;
-- benchmark leadership from SDK mechanics alone.
-
-Benchmark claims require benchmark-specific evidence. LoCoMo covers long-term conversational memory QA, event summarization, and multimodal generation across long conversations. LongMemEval covers extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention. Agent-memory benchmark results can depend heavily on the agent/framework/tool loop, not only on the memory store. Keep those distinctions when writing integrations or public copy.
-
-## What to keep out of examples
-
-Do not add secrets, tokens, 2FA codes, cloud account ids, personal data, provider transcripts, raw private memory, absolute local paths, or unreviewed hosted endpoints to examples/templates. Public-safe examples should use generic ids, relative paths, placeholders, hashes, commitments, counts, receipt ids, and roots.
+# Developer ecosystem
+
+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 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
+```
+
+`enigma init` creates the local `.enigma` workspace, bundle, and proof artifacts with no provider or cloud credentials. `enigma setup --client auto --connect-installed --overwrite` configures the drive and writes the `mcpServers.enigma` entry into every installed/config-present client it detects, skipping clients that are not installed; preview with `--dry-run` first. `enigma drive health` reports a SMART-style memory-drive health packet (freshness, duplicate rate, tombstone backlog, stale derived artifacts, receipt coverage, connector health) from local metadata only; it is part of the Memory Drive surface in this release, and `enigma status` plus `enigma doctor` cover local passport counts, roots, and connector readiness in every build. Neither setup command prints raw memory plaintext. Treat provider-native memory as non-canonical cache only; the local Enigma vault is canonical.
+
+Optional public test-drive loop:
+
+```sh
+npx --yes --package enigma-memory enigma test-drive --overwrite
+```
+
+`enigma test-drive --overwrite` is zero-credential, local-only, and public-safe by default. It does not call external providers, contact hosted Enigma SaaS, require OpenAI/Anthropic/Cloudflare credentials, create accounts, or write third-party client configs.
+
+## Copyable starting points
+
+- SDK/API guide: [`docs/sdk-api.md`](./sdk-api.md)
+- Node example app: [`examples/node-basic-memory.mjs`](../examples/node-basic-memory.mjs)
+- GitHub Actions example: [`examples/ci/github-actions.yml`](../examples/ci/github-actions.yml)
+- Benchmark reproducibility guide: [`docs/benchmark-reproducibility.md`](./benchmark-reproducibility.md)
+- Generic MCP client template: [`templates/mcp-client-config.json`](../templates/mcp-client-config.json)
+
+## Local SDK loop
+
+Use the SDK when you want an app-owned vault and receipt-backed proof loop:
+
+1. Create a local vault with `createVault`.
+2. Add a generic, non-private memory with `remember`.
+3. Create a passport with `createPassport`.
+4. Compile a receipt-backed context pack with `compileContextPack`.
+5. Export a proof-carrying bundle with `exportBundle`; keep full bundles private unless local import key material has been reviewed and removed.
+6. Verify receipts with `verifyReceiptChain`, `enigma verify`, `enigma-verify`, or MCP `enigma_verify_receipts`.
+
+The example app prints ids, counts, roots, and verification status only. It does not print raw memory text, generated key material, credentials, provider transcripts, or local absolute paths.
+
+## CLI and CI loop
+
+The CI example installs Node 24, installs `enigma-memory` into a disposable npm project, exposes the package benchmark script, then runs:
+
+```sh
+npx enigma test-drive --overwrite
+npx enigma setup --overwrite
+npx 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, 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:
+
+```sh
+node ./node_modules/enigma-memory/scripts/download-standard-benchmarks.mjs --dry-run
+node ./node_modules/enigma-memory/scripts/download-standard-benchmarks.mjs --execute --dataset all --out-dir .enigma/benchmarks/datasets --manifest .enigma/benchmarks/dataset-manifest.json
+node ./node_modules/enigma-memory/scripts/run-standard-memory-benchmarks.mjs --locomo .enigma/benchmarks/datasets/locomo10.json --longmemeval .enigma/benchmarks/datasets/longmemeval_s_cleaned.json --max-locomo-qa 25 --max-longmemeval-items 25 --top-k 5 --out .enigma/standard-memory-benchmark-sample.json
+```
+
+Those commands produce a dataset manifest with source URLs, byte sizes, and SHA-256 hashes plus a standard benchmark report using schema `enigma.standard_memory_benchmark_suite.v1`. The standard runner is retrieval/evidence proxy scoring only: it does not call providers, grade generated answers, or produce competitor scores.
+
+Use the workflow as a template in a consumer repository. It is intentionally limited to install/import/doctor smoke coverage, local proof generation, and deterministic local benchmark evidence by default; it does not publish packages, deploy infrastructure, contact hosted Enigma cloud, call external memory providers, or download official benchmark datasets unless you intentionally enable `run_standard_benchmark` for a manual workflow run.
+
+## Proof Network developer loop
+
+The proof-network path gives integrators a public, privacy-preserving adoption track before any chain transaction or hosted integration exists. The adoption ladder is intentionally simple:
+
+1. Install or invoke the npm package.
+2. Run the local test drive to produce safe roots/receipts/counts.
+3. Generate proof-network chain artifacts from public-safe inputs.
+4. Verify those artifacts locally.
+5. Wire the same artifact contract into a connector, benchmark dashboard, or conformance test.
+
+```sh
+npx --yes --package enigma-memory enigma test-drive --overwrite
+npx --yes --package enigma-memory enigma chain anchor --root sha256:8f8f... --root sha256:9a9a... --ref demo-local-vault --authority demo-public-authority --batch-ref demo-anchor-batch --out .enigma/proof-anchor-batch.json
+npx --yes --package enigma-memory enigma chain grant --subject did:example:agent --capability memory.read --scope demo-scope --resource-ref sha256:8f8f... --policy-hash sha256:7e7e... --expires-at 2026-07-01T00:00:00Z --grant-ref demo-grant --out .enigma/proof-capability-grant.json
+npx --yes --package enigma-memory enigma chain revoke --grant-hash sha256:6d6d... --reason scope-ended --revocation-ref demo-revocation --out .enigma/proof-capability-revocation.json
+npx --yes --package enigma-memory enigma chain attest --report-file benchmark-report.json --dataset-ref sha256:5c5c... --runner-ref enigma-standard-runner --package-ref enigma-memory@0.1.5 --score accuracy=0.92 --out .enigma/proof-benchmark-attestation.json
+npx --yes --package enigma-memory enigma chain verify --file .enigma/proof-anchor-batch.json
+```
+
+`enigma chain anchor`, `grant`, `revoke`, `attest`, and `verify` are local planning commands. They create or validate opaque JSON proof-network artifacts for Solana-ready anchoring, but they do not create accounts, sign with private keys, submit transactions, deploy programs, or call RPC providers. Generated chain artifacts must keep `transaction_submitted:false` and `raw_memory_on_chain:false`; if an example needs a memory reference, use a public-safe commitment or receipt root rather than raw memory, prompts, transcripts, completions, embeddings, ACL bodies, tenant names, provider responses, private keys, seed phrases, or credentials.
+
+Use proof artifacts as the common exchange format for developer integrations:
+
+- **NPM test-drive adopters:** run the test drive, create an anchor batch from local roots/refs, verify the artifact, and attach the JSON to a pull request, demo, or release note without exposing private memory.
+- **Chain artifact builders:** treat `anchor_batch`, `capability_grant`, `capability_revocation`, `benchmark_attestation`, and `packet` as the supported public artifact types. Anchors carry roots/refs/counts for later settlement; grants carry subject, capability, scope, resource refs, policy hashes, and expiry; revocations carry grant hashes and nullifiers; attestations carry report hashes plus dataset, runner, package, and score refs.
+- **Conformance program partners:** build fixtures that accept valid proof-network artifacts and reject artifacts that leak private payload keys or values, omit the false transaction flags, use raw ACL or tenant bodies, or mix raw memory with public chain payloads. A connector should pass conformance before it claims proof-network support.
+- **Benchmark attestation contributors:** hash the benchmark report or pass the report file, then bind it to dataset, runner, and package refs. The attestation makes benchmark evidence portable, but benchmark claims still depend on the benchmark guide's dataset, scoring, and comparison boundaries.
+- **Connector authors:** wallet, agent, MCP, CI, and dashboard connectors can verify packets, display opaque Solana-ready roots, enforce grants before retrieval, publish revocation/nullifier artifacts when access ends, and keep private bundles off-chain while sharing verifiable commitments.
+
+Conformance should stay narrow and testable. A proof-network connector is ready for public examples when it can:
+
+1. accept every supported proof-network artifact shape and return a deterministic validation result;
+2. reject any artifact containing private-looking field names or values before display, upload, signing, or indexing;
+3. preserve `transaction_submitted:false` unless a separate reviewed settlement path actually submits a transaction;
+4. preserve `raw_memory_on_chain:false` for every chain-facing artifact;
+5. enforce capability grant subject, capability, scope, resource-ref, policy-hash, and expiry constraints before retrieval;
+6. accept capability revocations/nullifiers and stop treating revoked grants as usable;
+7. bind benchmark attestations to report hashes/files plus dataset, runner, and package refs without importing the raw benchmark corpus or private model output.
+
+Good first connector projects are deliberately small: a CLI verifier that fails CI on leaked private payloads, a wallet preview that shows only roots/scopes/expiry/nullifiers, an MCP middleware that blocks retrieval without a live grant, a benchmark dashboard that accepts attestation JSON beside a report hash, and a Solana explorer plugin that labels opaque anchor batches without claiming transaction submission.
+
+This path is intentionally copyable: npm install, run a local test drive, generate proof artifacts, verify them, then wire the same public-safe contract into a connector or conformance test. Do not position it as live settlement, provider deletion proof, compliance certification, or benchmark leadership without the separate evidence those claims require.
+
+## MCP client loop
+
+The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. The smooth path is still one local setup plus a dry-run connector preview: `enigma setup --overwrite`, then `enigma connect claude-desktop --dry-run` or the matching client id. Remove `--dry-run` only when you explicitly want Enigma to write that client config. 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": "/absolute/path/to/.enigma/bundle.json"
+      }
+    }
+  }
+}
+```
+
+Do not commit private bundle paths if they reveal local usernames, workspace names, account ids, or other personal details.
+
+## Claim boundaries for developers
+
+Enigma proof artifacts cover Enigma-controlled or Enigma-mediated state: local vault events, receipts, active/tombstoned memory addresses, context-pack retrieval/injection receipts, relay/gateway records, usage events, and settlement receipts.
+
+They do not prove:
+
+- provider-side deletion;
+- model forgetting;
+- compliance certification;
+- token ROI, investment outcome, or provider invoice savings;
+- hosted-cloud readiness from a local demo;
+- benchmark leadership from SDK mechanics alone.
+
+Benchmark claims require benchmark-specific evidence. LoCoMo covers long-term conversational memory QA, event summarization, and multimodal generation across long conversations. LongMemEval covers extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention. Agent-memory benchmark results can depend heavily on the agent/framework/tool loop, not only on the memory store. Keep those distinctions when writing integrations or public copy.
+
+## What to keep out of examples
+
+Do not add secrets, tokens, 2FA codes, cloud account ids, personal data, provider transcripts, raw private memory, absolute local paths, or unreviewed hosted endpoints to examples/templates. Public-safe examples should use generic ids, relative paths, placeholders, hashes, commitments, counts, receipt ids, and roots.

package/docs/developer-proof-quickstart.md

@@ -141,7 +141,7 @@ npx --yes --package enigma-memory enigma chain attest \
   --report-hash sha256:6666666666666666666666666666666666666666666666666666666666666666 \
   --dataset-ref dataset:quickstart-public-fixture:v1 \
   --runner-ref runner:enigma-local:v1 \
-  --package-ref npm:enigma-memory@0.1.15 \
+  --package-ref npm:enigma-memory@0.1.17 \
   --score recall_at_5=1 \
   --score p95_latency_ms=14 \
   --out .enigma/proof-quickstart/benchmark-attestation.json
@@ -154,7 +154,7 @@ npx --yes --package enigma-memory enigma chain attest \
   --report-file .enigma/proof-quickstart/reviewed-benchmark-report.json \
   --dataset-ref dataset:quickstart-public-fixture:v1 \
   --runner-ref runner:enigma-local:v1 \
-  --package-ref npm:enigma-memory@0.1.15 \
+  --package-ref npm:enigma-memory@0.1.17 \
   --score recall_at_5=1 \
   --score p95_latency_ms=14 \
   --out .enigma/proof-quickstart/benchmark-attestation.json
@@ -282,7 +282,7 @@ const attestation = createBenchmarkAttestation({
   report_hash: 'sha256:6666666666666666666666666666666666666666666666666666666666666666',
   dataset_ref: 'dataset:quickstart-public-fixture:v1',
   runner_ref: 'runner:enigma-local:v1',
-  package_ref: 'npm:enigma-memory@0.1.15',
+  package_ref: 'npm:enigma-memory@0.1.17',
   sample_count: 12,
   run_count: 1,
 });

package/docs/enigma-memory-ready-conformance.md

@@ -341,7 +341,7 @@ The negative fixture set should include intentionally unsafe keys and values so
   "subject": {
     "name_ref": "public-package-or-client-ref",
     "version": "0.0.0",
-    "enigma_version": "0.1.15"
+    "enigma_version": "0.1.17"
   },
   "commands": [
     {

package/docs/hosted-cloud-product.md

@@ -16,11 +16,14 @@ The source package now has pure contract builders and validators in `packages/ho
 - backup drill records;
 - incident and SLA reference records;
 - customer lifecycle packets that aggregate those surfaces for launch-readiness evidence.
+- hosted cloud readiness aggregator packets that roll all lifecycle surfaces, auth, billing, legal/DPA, support, security review, monitoring, backup, KMS/BYOK, and operator go-live refs into one public-safe readiness assessment.
 
 These functions are contract and validation code only. They do not call an auth provider, billing provider, cloud deployment, KMS, backup target, support desk, status page, SIEM, or model provider. They are safe to import as package code because they do not start servers, read user files, mutate deployment state, publish packages, or contact external accounts.
 
 The lifecycle packet public APIs are `buildCustomerLifecyclePacket(input)` / `validateCustomerLifecyclePacket(packet)` and `buildApiKeyLifecyclePacket(input)` / `validateApiKeyLifecyclePacket(packet)` under `enigma-memory/hosted-cloud`; the script commands below emit the same schemas for release evidence.
 
+The readiness aggregator APIs are `buildHostedCloudReadinessPacket(input)` / `validateHostedCloudReadinessPacket(packet)` under `enigma-memory/hosted-cloud`; the `--readiness` script flag emits the same schema for release evidence.
+
 The validators enforce hosted-cloud boundaries:
 
 - contract artifacts must include `operator_evidence_refs` for auth provider, billing provider, legal docs, data processing terms, support ownership, and external security review;
@@ -49,6 +52,8 @@ Hosted cloud remains blocked until an operator wires and records evidence for al
 
 A `provided` operator evidence ref means the contract can point to external evidence. It still does not by itself make hosted cloud sellable; an operator must complete the release checklist and issue go-live approval. A `blocked_external_dependency` ref is an explicit blocker, not fake evidence.
 
+Hosted relay/gateway readiness is a separate backend health boundary, not hosted-cloud sellability. Operators may validate the backend path with `npm run production:hosted-collect` followed by `npm run production:hosted-live`, but those commands only prove public HTTPS relay/gateway probes and required hosted refs for the named environment. They do not wire auth, billing, legal terms, support, security review, customer lifecycle, API key lifecycle, or operator SaaS go-live approval.
+
 ## Consolidated unblocker report
 
 Before treating hosted cloud as sellable, run the consolidated public-safe unblocker report:
@@ -73,6 +78,32 @@ The command writes public-safe validation evidence only. It must not receive or
 
 The packet records lifecycle events, required evidence refs, missing evidence refs, malformed operation blockers, the operator approval ref, readiness status, `customer_api_keys_live`, and no-secret/no-plaintext guarantees. Missing evidence refs, blocked evidence refs, malformed operation surfaces, or absent operator approval keep `customer_api_keys_live:false`.
 
+## Contract-ready vs sellable
+
+Hosted cloud has two distinct readiness states:
+
+- **Contract-ready**: The contract builders and validators exist, produce deterministic public-safe JSON, and enforce the privacy firewall (no raw memory, plaintext prompts, provider payloads, credentials, API key material, or forbidden claims). Every surface emits `readiness.contract_ready: true` and `readiness.integration_kind: "contract_validator_only"`. This state is reached now — the package code is safe to import and validates evidence structure.
+
+- **Sellable**: The hosted cloud product is ready to sell to customers. This requires every readiness surface to have provided evidence refs, both the customer lifecycle packet and API key lifecycle packet to be embedded and approved, and an explicit operator go-live approval ref. This state is not reached until real external provider wiring, legal approval, security review, and operator sign-off exist.
+
+A readiness packet or lifecycle packet may mark `hosted_cloud_sellable: true` only when all evidence refs are provided, both underlying lifecycle packets are sellable, and an operator go-live approval ref is supplied. Contract-ready is a code-quality state; sellable is an operational state that depends on external systems and human approval.
+
+## Hosted cloud readiness aggregator
+
+`npm run production:hosted-customer -- --readiness --tenant <id> --domain <domain> --environment <env> --operator-go-live-ref <ref> --out <file>` builds `enigma.hosted_cloud.readiness_packet.v1`, a single public-safe packet that rolls all lifecycle surfaces plus auth, billing, legal/DPA, support, security review, monitoring, backup, KMS/BYOK, and operator go-live refs into one readiness assessment.
+
+The readiness aggregator:
+
+- accepts an optional `customer_lifecycle_packet` and `api_key_lifecycle_packet` (or builds a lifecycle packet from script args);
+- derives readiness surface evidence from the lifecycle packet's phase evidence when available;
+- propagates `external_blockers` from both embedded lifecycle packets as `propagated_lifecycle_blockers` (prefixed `customer_lifecycle.*` and `api_key_lifecycle.*`) — these are never masked;
+- gates `hosted_cloud_sellable` on: all 8 readiness surfaces provided + operator go-live ref + customer lifecycle packet embedded and sellable + API key lifecycle packet embedded with operator approval ref;
+- gates API key lifecycle readiness on `operator_approval_ref` (operator-provided evidence), not a self-asserted boolean;
+- emits a `dashboard` block with counts, status refs, blocker refs, next actions, and safety summary for a future tenant dashboard;
+- emits a schema-versioned packet with `propagated_lifecycle_blockers`, `readiness_surfaces`, and no-secret/no-plaintext guarantees.
+
+If either lifecycle packet is missing, a propagated blocker notes its absence. If either is embedded but not sellable/approved, its individual blockers propagate through. The readiness packet never claims live hosted SaaS, provider wiring, or deployment — it is evidence validation only.
+
 ## Non-claims
 
 Hosted cloud collateral must not say or imply: