enigma-memory 0.1.16 → 0.1.18

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;
@@ -75,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:

package/docs/install-anywhere.md

@@ -1,8 +1,7 @@
 # Install Enigma anywhere
 
-Start with the published npm package path for `enigma-memory`: install once, run `enigma setup --overwrite` once, then use memory/search/context/verify/connect from the same local AI Memory Passport. Use a source checkout only when you need source-only docs, Docker assets, browser-extension scaffolding, package development, or release scripts.
-
-Hosted cloud and BYOC operation require real deployment credentials, domains, TLS, durable storage, KMS/secrets, monitoring, backups, and operator/customer infrastructure; they are not activated by installing the package, running setup, or running the test drive.
+Start with the published npm package path for `enigma-memory`: install once, connect your installed AI clients, then inspect Memory Drive health and passport status. Use a source checkout only when you need source-only docs, Docker assets, browser-extension scaffolding, package development, or release scripts.
+Hosted cloud and BYOC operation are waitlist/operator-deploy only; they require real deployment credentials, domains, TLS, durable storage, KMS/secrets, monitoring, backups, and operator/customer infrastructure. The relay and gateway binaries included in the package are local bootstrap probes, not a live hosted service. They are not activated by installing the package, running setup, or running the test drive.
 
 ## Requirements
 
@@ -18,15 +17,19 @@ Use the published package as the primary path:
 
 ```sh
 npm install -g enigma-memory
-enigma setup --overwrite
+enigma init
+enigma setup --client auto --connect-installed --overwrite
+enigma drive health
+enigma status
 enigma remember --text-file ./memory.txt
-enigma search --query "..."
-enigma context --query "..." --optimize
+enigma search --query "project context"
+enigma context --query "project context" --optimize
 enigma verify --export ./.enigma/export.json
-enigma connect claude-desktop --dry-run
 ```
 
-`enigma setup --overwrite` 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. Client config writes happen only when you explicitly run `enigma connect <client>` without `--dry-run`.
+`enigma init` is the credential-free first run that creates the local `.enigma` workspace, bundle, and proof artifacts. `enigma setup --client auto --connect-installed --overwrite` then configures the drive and writes the `mcpServers.enigma` entry into every installed/config-present client it detects; it skips clients that are not installed and never creates configs from scratch. Preview with `--dry-run` first to see which clients will be written. Both commands emit deterministic, public-safe JSON without printing raw memory plaintext, and both run on Windows PowerShell via the `enigma.cmd` shim the npm global install adds.
+
+`enigma drive health` reports a SMART-style memory-drive health packet — freshness, duplicate rate, tombstone backlog, stale derived artifacts, receipt coverage, and connector health — from local metadata only, with no network calls or private payloads. It is part of the Memory Drive surface in this release; `enigma status` and `enigma doctor` cover local passport counts, roots, and connector readiness in every build.
 
 The local Enigma vault is the canonical memory passport. Provider-native memory is non-canonical cache only. Enigma proof covers Enigma-controlled vault state, receipts, checkpoints, committed roots, and exported bundle shape; it does not prove provider deletion, model forgetting, provider-native memory removal, hosted/BYOC availability, legal approval, ROI/savings, or compliance certification.
 
@@ -173,15 +176,14 @@ MCP resource and prompt:
 
 Use `docs/client-connectors.md` from a source checkout for Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo Code, OpenCode, and generic MCP JSON. Connector entries default to command `enigma-mcp` and env key `ENIGMA_BUNDLE`.
 
-Npm-first connector flow:
+Npm-first connector flow — one command connects every installed/config-present client:
 
 ```sh
 npm install -g enigma-memory
-enigma setup --overwrite
-enigma connect claude-desktop --dry-run
+enigma setup --client auto --connect-installed --overwrite
 ```
 
-Run `enigma setup --overwrite` for a regular local workspace. It writes local Enigma artifacts only. Use `enigma connect <client> --dry-run` when you want to preview one client config without writing it; remove `--dry-run` only when you explicitly want Enigma to merge that MCP entry while preserving unrelated client settings.
+`--connect-installed` detects installed/config-present clients (Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo, OpenCode, generic MCP) and writes only those existing client configs; missing client configs are reported and skipped. To preview a single client without writing, or to connect just one client later, use `enigma connect <client> --dry-run` and then drop `--dry-run`.
 
 Copy-paste MCP snippets:
 
@@ -470,6 +472,8 @@ Run it from the public-site package/artifact root after building or obtaining `_
 
 ## Enterprise hosted and BYOC modes
 
+Both modes are waitlist/operator-deploy only. The relay and gateway binaries are local bootstrap probes; production hosted or BYOC operation requires real deployment credentials, domain/TLS, durable storage, KMS/secrets, monitoring, backups, incident response, and operator acceptance.
+
 Hosted mode:
 
 - Enigma operator deploys relay/gateway for the tenant.

package/docs/memory-benchmarks.md

@@ -35,7 +35,7 @@ The fixture harness does not download or run LoCoMo, LongMemEval, provider APIs,
 
 The fixture creates multiple sessions with facts, a knowledge update, temporal questions, an abstention question, duplicate memory candidates, and provider profile labels for `chatgpt`, `claude`, `kimi`, `cursor`, and `local-llm`.
 
-The harness measures local Enigma operations only:
+The harness measures local Enigma operations only. The runtime `enigma search` and context-pack retrieval in this release use deterministic keyword token overlap only; no embedding model, vector index, or LLM is called.
 
 - vault remember/update operations;
 - vault export and import;
@@ -74,6 +74,21 @@ Because `enigma_relevance` can match normalized variants, session/role cues, tem
 
 The standard runner reports retrieval/evidence proxy metrics: LoCoMo evidence-hit@k and exact evidence coverage; LongMemEval turn evidence-hit@k, session evidence-hit@k, exact coverage, and abstention correctness; plus estimated prompt tokens, selected memory counts, and local latency. These are not LLM-generated answer-accuracy scores and must not be described as provider, competitor, or benchmark-leadership results.
 
+## Full-answer benchmark protocol plan
+
+A true apples-to-apples full-answer benchmark (same category set, same `--top-k`, same frozen answerer and judge, same prompts, same competitor adapters) is a separate credentialed run that this package does not execute. `--protocol-plan` is the readiness layer: it emits a public-safe plan of that future protocol with no provider calls, no answer generation, no judging, and no competitor adapters.
+
+```sh
+cd enigma
+node scripts/run-standard-memory-benchmarks.mjs --locomo .enigma/benchmarks/datasets/locomo10.json --longmemeval .enigma/benchmarks/datasets/longmemeval_s_cleaned.json --top-k 5 --protocol-plan --out .enigma/standard-memory-benchmark-protocol-plan.json
+```
+
+The emitted schema is `enigma.standard_memory_benchmark_protocol_plan.v1`. It records the planned category set, `--top-k`, the answerer model ref, the judge model ref, the prompt refs, the protocol ref, requirements-only competitor adapter refs, and cost-estimate inputs. Refs can be pinned with `--answerer-ref`, `--judge-ref`, `--answer-prompt-ref`, `--judge-prompt-ref`, and `--protocol-ref`; unpinned refs read `not-selected`/`not-pinned`.
+
+The plan carries explicit boundaries that must be `false`: `protocol_boundaries.network_required`, `provider_calls_made`, `answers_generated`, `judged`, and `competitor_adapters_run`, plus `benchmark_boundaries.llm_answer_accuracy_scored: false` and `retrieval_evidence_proxy_scored: false`. It contains no raw questions, answers, prompts, provider responses, credentials, or scores.
+
+The protocol plan is accepted by the benchmark proof-release builder alongside a scored retrieval proxy report, producing an `enigma.proof_network.benchmark_attestation.v1` that binds the plan's report hash. A protocol-plan proof release is evidence of protocol readiness only: it is not evidence that answers were generated or judged, that any provider or competitor ran or was outperformed, or that benchmark leadership, ROI, provider deletion, model forgetting, or compliance was achieved. Competitor adapter refs are references, not scores; a reference is never a superiority claim.
+
 ## Local baseline comparison
 
 `local_baseline_comparisons` (also mirrored at `metrics.local_baseline_comparisons`) compares Enigma against deterministic local baselines only. Every row scores the same private fixture questions and keeps raw memory, question text, and answer text out of the report.