enigma-memory 0.1.18 → 0.1.22

package/deploy/docker-compose.local-production-simulation.yml

@@ -70,6 +70,13 @@ services:
       start_period: 3s
     restart: unless-stopped
 
+  simulation-state-init:
+    image: alpine:3.22
+    command: ["sh", "-c", "chown -R 1000:1000 /simulation-state && chmod 700 /simulation-state"]
+    volumes:
+      - simulation-state:/simulation-state
+    restart: "no"
+
   relay:
     build:
       context: ..
@@ -85,6 +92,10 @@ services:
       - operator_acceptance_evidence_uri
     environment:
       NODE_ENV: production
+      # Guarded local-only serve module; never use this module in hosted/BYOC manifests.
+      ENIGMA_LOCAL_PRODUCTION_SIMULATION: "true"
+      ENIGMA_RELAY_SERVE_MODULE: /app/scripts/local-production-simulation-serve.mjs
+      ENIGMA_SIMULATION_STATE_DIR: /simulation-state
       ENIGMA_BACKEND_MODE: production
       ENIGMA_REQUIRE_EXTERNAL_STORAGE: "true"
       ENIGMA_REQUIRE_EXTERNAL_KMS: "true"
@@ -96,7 +107,9 @@ services:
       ENIGMA_RELAY_RUNTIME_AUTH_REF: local-simulation-relay-runtime-auth-ref
       ENIGMA_RELAY_MONITORING_REF: local-simulation-relay-monitoring-ref
       ENIGMA_SIEM_REF: local-simulation-siem-ref
+      ENIGMA_RELAY_STORAGE_REF: local-simulation-relay-storage-ref
       ENIGMA_BACKUP_TARGET_URI_FILE: /run/secrets/backup_target_uri
+      ENIGMA_BACKUP_TARGET_REF: local-simulation-backup-target-ref
       ENIGMA_NETWORK_ACCESS_POLICY_REF: local-simulation-network-access-policy-ref
       ENIGMA_KMS_CUSTODY_REF: local-simulation-kms-custody-ref
       ENIGMA_KMS_KEY_REF: local-simulation-kms-key-ref
@@ -115,9 +128,15 @@ services:
       ENIGMA_EXTERNAL_STORAGE_DSN_FILE: /run/secrets/external_storage_dsn
       ENIGMA_KMS_KEY_REF_FILE: /run/secrets/kms_key_ref
       ENIGMA_OPERATOR_ACCEPTANCE_EVIDENCE_URI_FILE: /run/secrets/operator_acceptance_evidence_uri
+    volumes:
+      - simulation-state:/simulation-state
     depends_on:
       postgres:
         condition: service_healthy
+      kms-mock:
+        condition: service_healthy
+      simulation-state-init:
+        condition: service_completed_successfully
     read_only: true
     user: "1000:1000"
     cap_drop: ["ALL"]
@@ -151,6 +170,12 @@ services:
       ENIGMA_GATEWAY_ADMIN_AUTH_BEARER_SHA256: ${ENIGMA_GATEWAY_ADMIN_AUTH_BEARER_SHA256:-operator-required-admin-bearer-sha256}
       ENIGMA_GATEWAY_DATA_PLANE_AUTH_BEARER_SHA256: ${ENIGMA_GATEWAY_DATA_PLANE_AUTH_BEARER_SHA256:-operator-required-data-plane-bearer-sha256}
       NODE_ENV: production
+      # Guarded local-only serve module; never use this module in hosted/BYOC manifests.
+      ENIGMA_LOCAL_PRODUCTION_SIMULATION: "true"
+      ENIGMA_GATEWAY_SERVE_MODULE: /app/scripts/local-production-simulation-serve.mjs
+      ENIGMA_SIMULATION_STATE_DIR: /simulation-state
+      ENIGMA_SIMULATION_KMS_KEY_PATH: /simulation-kms/kms-key-ref.json
+      ENIGMA_SIMULATION_SIEM_URL: http://siem-mock:3000/events
       ENIGMA_BACKEND_MODE: production
       ENIGMA_REQUIRE_EXTERNAL_STORAGE: "true"
       ENIGMA_REQUIRE_EXTERNAL_KMS: "true"
@@ -166,6 +191,7 @@ services:
       ENIGMA_GATEWAY_ADMIN_AUTH_REF: local-simulation-gateway-admin-auth-ref
       ENIGMA_GATEWAY_DATA_PLANE_AUTH_REF: local-simulation-gateway-data-plane-auth-ref
       ENIGMA_BACKUP_TARGET_URI_FILE: /run/secrets/backup_target_uri
+      ENIGMA_BACKUP_TARGET_REF: local-simulation-backup-target-ref
       ENIGMA_NETWORK_ACCESS_POLICY_REF: local-simulation-network-access-policy-ref
       ENIGMA_KMS_CUSTODY_REF: local-simulation-kms-custody-ref
       ENIGMA_KMS_KEY_REF: local-simulation-kms-key-ref
@@ -185,9 +211,18 @@ services:
       ENIGMA_SIEM_EXPORT_ENDPOINT_FILE: /run/secrets/siem_export_endpoint
       ENIGMA_EXTERNAL_STORAGE_DSN_FILE: /run/secrets/external_storage_dsn
       ENIGMA_OPERATOR_ACCEPTANCE_EVIDENCE_URI_FILE: /run/secrets/operator_acceptance_evidence_uri
+    volumes:
+      - simulation-state:/simulation-state
+      - kms-data:/simulation-kms:ro
     depends_on:
       postgres:
         condition: service_healthy
+      kms-mock:
+        condition: service_healthy
+      siem-mock:
+        condition: service_healthy
+      simulation-state-init:
+        condition: service_completed_successfully
     read_only: true
     user: "1000:1000"
     cap_drop: ["ALL"]
@@ -243,3 +278,4 @@ volumes:
   pgdata:
   kms-data:
   siem-data:
+  simulation-state:

package/docs/browser-extension-install.md

@@ -32,19 +32,21 @@ The ZIP command does not publish, sign, upload, or submit the extension.
 Install the npm package, create the local bundle, and let Enigma merge the MCP server entry into the selected client config. Pick the command for the client you use:
 
 ```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
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create the protected passphrase file before setup.' >&2; exit 1; }
+npm install -g enigma-memory && enigma setup --passphrase-file "$PASSPHRASE_FILE" --client claude-desktop --write-connectors --overwrite
+npm install -g enigma-memory && enigma setup --passphrase-file "$PASSPHRASE_FILE" --client cursor --write-connectors --overwrite
+npm install -g enigma-memory && enigma setup --passphrase-file "$PASSPHRASE_FILE" --client kimi-code --write-connectors --overwrite
+npm install -g enigma-memory && enigma setup --passphrase-file "$PASSPHRASE_FILE" --client vscode-cline --write-connectors --overwrite
 ```
 
 If you want Enigma to touch only client config files that already exist, use:
 
 ```sh
-npm install -g enigma-memory && enigma setup --client auto --connect-installed --overwrite
+npm install -g enigma-memory && enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite
 ```
 
-Set `ENIGMA_BUNDLE` for the browser-launched host process to the same bundle path reported by setup, or point the native-host manifest at a small local wrapper that sets `ENIGMA_BUNDLE=<absolute-bundle-path>` before launching `enigma-native-host`. Native messaging manifests require an absolute executable path; they do not expand shell aliases, `~`, `$HOME`, `%USERPROFILE%`, or command arguments.
+Set `ENIGMA_BUNDLE` and `ENIGMA_PASSPHRASE_FILE` for the browser-launched host process to the same bundle and protected passphrase file used by setup, or point the native-host manifest at a small owner-writable-only wrapper that sets both variables before launching `enigma-native-host`. Never put the passphrase contents in the wrapper or manifest. Native messaging manifests require an absolute executable path; they do not expand shell aliases, `~`, `$HOME`, `%USERPROFILE%`, or command arguments.
 
 Resolve the absolute host executable path:
 

package/docs/client-connectors.md

@@ -16,17 +16,21 @@ Supported connector IDs:
 
 ```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
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create $HOME/.enigma/passphrase with an approved secret manager or secure editor, then restrict it to the current user.' >&2; exit 1; }
+enigma init --passphrase-file "$PASSPHRASE_FILE"
+enigma setup --passphrase-file "$PASSPHRASE_FILE" --client auto --connect-installed --overwrite
+enigma drive health --passphrase-file "$PASSPHRASE_FILE"
+enigma status --passphrase-file "$PASSPHRASE_FILE"
+enigma remember --passphrase-file "$PASSPHRASE_FILE" --text-file ./memory.txt
+enigma search --passphrase-file "$PASSPHRASE_FILE" --query "project context"
+enigma context --passphrase-file "$PASSPHRASE_FILE" --query "project context" --optimize
 enigma verify --export ./.enigma/export.json
 ```
 
-One command connects every installed client: `enigma setup --client auto --connect-installed --overwrite` writes 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. `enigma drive health` reports a SMART-style memory-drive health packet (freshness, 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. No setup command prints raw memory plaintext.
+One command connects every installed client: `enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite` writes 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. Normal setup is encrypted and requires `ENIGMA_PASSPHRASE` or `--passphrase-file`; never put the passphrase itself in shell arguments. `enigma drive health` reports a SMART-style memory-drive health packet from local metadata only. No setup command prints raw memory plaintext.
+
+Run setup or quickstart before using `enigma doctor` as the final green check. Doctor reads existing client configs as well as the local environment, so an already-present `generic-mcp` or other MCP config can make doctor red on a fresh install if its `ENIGMA_BUNDLE` points to a bundle that does not exist yet, or to a different bundle than the one passed to doctor. That is expected first-run connector state, not an npm install failure. After securely creating `./.enigma/passphrase`, use `enigma quickstart --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite` or `enigma setup --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite`, then rerun `enigma doctor --bundle ./.enigma/bundle.json`.
 
 For a single client, or to preview before writing, use `enigma connect <client> --dry-run` and then drop `--dry-run`.
 
@@ -68,13 +72,13 @@ enigma connect generic-mcp
 Optional setup-time planning for installed/config-present connector targets remains available:
 
 ```sh
-enigma setup --client auto --overwrite
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --overwrite
 ```
 
 Use the explicit setup-time write flag only when you want setup to write all installed/config-present client configs it discovers:
 
 ```sh
-enigma setup --connect-installed --overwrite
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --connect-installed --overwrite
 ```
 
 `--connect-installed` skips missing client configs instead of creating every default client config. It is for installed/config-present clients only. Existing `enigma setup --write-connectors` behavior for explicit/default clients is unchanged.
@@ -107,7 +111,7 @@ Connector writes are semantic and idempotent. Enigma preserves unrelated client
 
 ## Copy-paste MCP snippets
 
-Use an absolute bundle path. The MCP process inherits client environment in some apps and not in others; setting `ENIGMA_BUNDLE` directly in the entry is the portable path. The command defaults to `enigma-mcp`; if a GUI app cannot find shell-installed binaries, render an absolute command with `--mcp-command` (alias: `--command`).
+Use an absolute bundle path. The MCP process inherits client environment in some apps and not in others; setting `ENIGMA_BUNDLE` directly in the entry is the portable path. For an encrypted bundle, arrange for the client process to receive `ENIGMA_PASSPHRASE` from an approved OS credential manager or secure launcher. Never put its value in MCP JSON, source, documentation, or shell arguments. The command defaults to `enigma-mcp`; if a GUI app cannot find shell-installed binaries, render an absolute command with `--mcp-command` (alias: `--command`).
 
 Claude Desktop:
 

package/docs/developer-ecosystem.md

@@ -8,25 +8,27 @@ For most developers, start with the installed CLI before reading the SDK interna
 
 ```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
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create the protected passphrase file before setup.' >&2; exit 1; }
+enigma init --passphrase-file "$PASSPHRASE_FILE"
+enigma setup --passphrase-file "$PASSPHRASE_FILE" --client auto --connect-installed --overwrite
+enigma drive health --passphrase-file "$PASSPHRASE_FILE"
+enigma status --passphrase-file "$PASSPHRASE_FILE"
+enigma remember --passphrase-file "$PASSPHRASE_FILE" --text-file ./memory.txt
+enigma search --passphrase-file "$PASSPHRASE_FILE" --query "project context"
+enigma context --passphrase-file "$PASSPHRASE_FILE" --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.
+`enigma init` creates an encrypted local `.enigma` workspace, bundle, and proof artifacts with no provider or cloud credentials; it requires a local passphrase through `ENIGMA_PASSPHRASE` or `--passphrase-file`. `enigma setup --passphrase-file "$HOME/.enigma/passphrase" --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. Never place the passphrase itself in shell arguments.
 
 Optional public test-drive loop:
 
 ```sh
-npx --yes --package enigma-memory enigma test-drive --overwrite
+npx --yes --package enigma-memory enigma test-drive --insecure-dev --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.
+`enigma test-drive --insecure-dev --overwrite` is an **INSECURE, EVALUATION-ONLY** disposable local exercise. It does not call external providers, contact hosted Enigma SaaS, require provider/cloud credentials, create accounts, or write third-party client configs, but its unencrypted keyring has no at-rest confidentiality and must not hold normal data.
 
 ## Copyable starting points
 
@@ -54,8 +56,8 @@ The example app prints ids, counts, roots, and verification status only. It does
 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 test-drive --insecure-dev --overwrite # INSECURE, EVALUATION ONLY
+npx enigma setup --passphrase-file ./.enigma/passphrase --overwrite
 npx enigma doctor
 npm run benchmark:memory-suite -- --out benchmark-report.json
 ```
@@ -119,7 +121,7 @@ This path is intentionally copyable: npm install, run a local test drive, genera
 
 ## 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.
+The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. The smooth path is one encrypted local setup plus a dry-run connector preview: securely create `./.enigma/passphrase`, run `enigma setup --passphrase-file ./.enigma/passphrase --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:
 

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

@@ -30,19 +30,21 @@ Conformant integrations must expose or document these commands in a way a review
 ### Baseline local memory commands
 
 ```sh
-enigma test-drive --overwrite
-enigma setup --overwrite
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create the protected passphrase file before normal conformance setup.' >&2; exit 1; }
+enigma test-drive --insecure-dev --overwrite # INSECURE, EVALUATION ONLY
+enigma setup --passphrase-file "$PASSPHRASE_FILE" --overwrite
 enigma doctor
-enigma remember --text-file ./public-safe-memory.txt
-enigma search --query "public-safe query"
-enigma context --query "public-safe query" --optimize
+enigma remember --passphrase-file "$PASSPHRASE_FILE" --text-file ./public-safe-memory.txt
+enigma search --passphrase-file "$PASSPHRASE_FILE" --query "public-safe query"
+enigma context --passphrase-file "$PASSPHRASE_FILE" --query "public-safe query" --optimize
 enigma verify --export ./.enigma/export.json
 ```
 
 Requirements:
 
-- `test-drive` must be zero-credential and local-only.
-- `setup` must not write third-party client configs unless an explicit write flag is used.
+- `test-drive --insecure-dev` is an explicit **INSECURE, EVALUATION-ONLY** disposable exercise with no at-rest confidentiality; it must not contain normal data.
+- Normal `setup` must require `ENIGMA_PASSPHRASE` or `--passphrase-file`, create an encrypted keyring, and not write third-party client configs unless an explicit write flag is used.
 - `doctor` must not print secrets, local account names, provider tokens, or raw private memory.
 - `remember`, `search`, and `context` examples must use public-safe sample text only.
 - `verify` must check receipt-chain consistency and fail closed on malformed exports.
@@ -50,8 +52,8 @@ Requirements:
 ### Connector commands
 
 ```sh
-enigma setup --client auto --overwrite
-enigma setup --connect-installed --overwrite
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --overwrite
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --connect-installed --overwrite
 enigma connect <connector-id> --dry-run
 enigma connect <connector-id>
 ```

package/docs/install-anywhere.md

@@ -6,7 +6,7 @@ Hosted cloud and BYOC operation are waitlist/operator-deploy only; they require
 ## Requirements
 
 - Node.js `>=24`
-- A local filesystem path for the Enigma vault bundle
+- A local filesystem path for the Enigma vault bundle and a passphrase supplied through `ENIGMA_PASSPHRASE` or a user-readable-only passphrase file
 - No database, provider credential, cloud credential, npm publishing token, package registry account, or hosted Enigma account for the local test-drive or setup paths
 - Git only for the advanced source-checkout path
 - Optional: Docker for source-checkout containerized relay/gateway operation
@@ -17,17 +17,42 @@ Use the published package as the primary path:
 
 ```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
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create $HOME/.enigma/passphrase with an approved secret manager or secure editor, then restrict it to the current user.' >&2; exit 1; }
+enigma init --passphrase-file "$PASSPHRASE_FILE"
+enigma setup --passphrase-file "$PASSPHRASE_FILE" --client auto --connect-installed --overwrite
+enigma drive health --passphrase-file "$PASSPHRASE_FILE"
+enigma status --passphrase-file "$PASSPHRASE_FILE"
+enigma remember --passphrase-file "$PASSPHRASE_FILE" --text-file ./memory.txt
+enigma search --passphrase-file "$PASSPHRASE_FILE" --query "project context"
+enigma context --passphrase-file "$PASSPHRASE_FILE" --query "project context" --optimize
 enigma verify --export ./.enigma/export.json
 ```
 
-`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 init` is the encrypted first run: it requires `ENIGMA_PASSPHRASE` or `--passphrase-file`, then creates the local `.enigma` workspace, encrypted bundle, and proof artifacts. `enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite` 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.
+
+### Keyring Security & At-Rest Confidentiality Note
+
+- **Encrypted default (`local_secret_encrypted`)**: Normal `enigma init`, `enigma setup`, and `enigma quickstart` require `ENIGMA_PASSPHRASE` or `--passphrase-file <path>`. Prefer a user-readable-only file created through an approved secret manager or secure editor; never put the passphrase itself in command arguments.
+- **Insecure evaluation mode (`local_secret`)**: `--insecure-dev` is an explicit, **INSECURE, EVALUATION-ONLY** escape hatch for disposable data. It stores an unencrypted keyring (`unencrypted: true`), provides no at-rest confidentiality, and must not be used for normal or persistent data.
+
+Encrypted + Solana-connected package path:
+
+```sh
+npm install -g enigma-memory
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create $HOME/.enigma/passphrase securely before continuing.' >&2; exit 1; }
+enigma quickstart --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --overwrite
+enigma-terminal --exec "solana status --cluster devnet"
+enigma chain anchor-bundle --bundle "$HOME/.enigma/bundle.json" --cluster devnet --out "$HOME/.enigma/anchor-batch.json"
+enigma chain submit-solana --file "$HOME/.enigma/anchor-batch.json" --cluster devnet
+```
+
+The final command is a Solana Memo dry-run by default. To write on-chain, pass `--execute --keypair <funded-solana-cli-keypair.json>`. The memo payload is a compact public proof reference derived from local bundle commitment roots; raw memory, prompts, key material, passphrases, and bundle ciphertext are never placed on-chain.
+
+Run setup or quickstart before treating `enigma doctor` as a fully green install check. Doctor checks Node/package state, local paths, schemas, MCP command naming, and connector configs. On a fresh install it can return `ok:false` when an existing MCP client config points at a bundle that has not been initialized yet, or at a different bundle than the one you are checking. That is expected first-run state, not a package install failure. After securely creating `./.enigma/passphrase`, run `enigma quickstart --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite` or `enigma setup --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite`, then `enigma doctor --bundle ./.enigma/bundle.json`.
+
+For the one-off npm path, create the same protected passphrase file, then run `npx --yes --package enigma-memory enigma quickstart --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite` before `npx --yes --package enigma-memory enigma doctor --bundle ./.enigma/bundle.json`. Running npx doctor first can report a red generic-MCP connector if an existing client config names a not-yet-created bundle.
 
 `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.
 
@@ -36,8 +61,9 @@ The local Enigma vault is the canonical memory passport. Provider-native memory
 Optional public test drive without a global install:
 
 ```sh
-npx --yes --package enigma-memory enigma test-drive --overwrite
+npx --yes --package enigma-memory enigma test-drive --insecure-dev --overwrite
 ```
+This command is **INSECURE, EVALUATION ONLY**: the isolated test drive is disposable and has no at-rest confidentiality. Normal setup uses an encrypted passphrase file as shown above.
 
 ## Source checkout versus package install
 
@@ -51,7 +77,7 @@ From the repository root, use the local installer in preview mode first:
 
 ```sh
 npm run install:local
-npm run install:local -- --init-vault --bundle ./.enigma/bundle.json
+npm run install:local -- --init-vault --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase
 ```
 
 `install:local` is dry-run by default. It validates Node.js `>=24`, resolves the local bundle path, previews `npm install -g .`, and emits public-safe JSON without printing local absolute paths, credentials, account IDs, or memory plaintext. It does not mutate global npm state or create a vault unless you explicitly request execute mode.
@@ -59,8 +85,9 @@ npm run install:local -- --init-vault --bundle ./.enigma/bundle.json
 To perform the local global install from the checkout and initialize a local vault bundle:
 
 ```sh
-npm run install:local -- --execute --init-vault --bundle ./.enigma/bundle.json
-enigma doctor
+test -s ./.enigma/passphrase || { printf '%s\n' 'Create ./.enigma/passphrase securely before continuing.' >&2; exit 1; }
+npm run install:local -- --execute --init-vault --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase
+enigma doctor --bundle ./.enigma/bundle.json
 enigma --help
 enigma demo cross-model
 enigma-verify --help
@@ -72,8 +99,8 @@ Equivalent explicit source-checkout steps:
 
 ```sh
 npm install -g .
-enigma init --bundle ./.enigma/bundle.json --subject local-user --display-name "Local user"
-enigma doctor
+enigma init --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --subject local-user --display-name "Local user"
+enigma doctor --bundle ./.enigma/bundle.json
 enigma --help
 enigma demo cross-model
 enigma-verify --help
@@ -99,10 +126,12 @@ Use this when you want to inspect each step behind the setup-first path:
 mkdir -p .enigma
 ENIGMA_DEMO_MEMORY_FILE=/absolute/path/to/tenant-approved-smoke-memory.txt
 test -f "$ENIGMA_DEMO_MEMORY_FILE"
-enigma init --bundle ./.enigma/bundle.json --subject local-user --display-name "Local user"
-enigma remember --bundle ./.enigma/bundle.json --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose user_memory --tags local
-enigma context --bundle ./.enigma/bundle.json --query "local context" --purpose local_context --out ./.enigma/context-pack.json
-enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
+ENIGMA_PASSPHRASE_FILE=./.enigma/passphrase
+test -s "$ENIGMA_PASSPHRASE_FILE" || { printf '%s\n' 'Create ./.enigma/passphrase securely before continuing.' >&2; exit 1; }
+enigma init --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --subject local-user --display-name "Local user"
+enigma remember --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose user_memory --tags local
+enigma context --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --query "local context" --purpose local_context --out ./.enigma/context-pack.json
+enigma export --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --out ./.enigma/export.json
 enigma verify --export ./.enigma/export.json
 ```
 
@@ -112,10 +141,12 @@ Windows PowerShell equivalent:
 New-Item -ItemType Directory -Force .enigma
 $env:ENIGMA_DEMO_MEMORY_FILE='C:\path\to\tenant-approved-smoke-memory.txt'
 if (-not (Test-Path $env:ENIGMA_DEMO_MEMORY_FILE)) { throw 'Set ENIGMA_DEMO_MEMORY_FILE to a tenant-approved smoke file first.' }
-enigma init --bundle .\.enigma\bundle.json --subject local-user --display-name "Local user"
-enigma remember --bundle .\.enigma\bundle.json --text-file $env:ENIGMA_DEMO_MEMORY_FILE --purpose user_memory --tags local
-enigma context --bundle .\.enigma\bundle.json --query "local context" --purpose local_context --out .\.enigma\context-pack.json
-enigma export --bundle .\.enigma\bundle.json --out .\.enigma\export.json
+$env:ENIGMA_PASSPHRASE_FILE='.\.enigma\passphrase'
+if (-not (Test-Path -LiteralPath $env:ENIGMA_PASSPHRASE_FILE -PathType Leaf)) { throw 'Create the passphrase file securely before continuing.' }
+enigma init --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --subject local-user --display-name "Local user"
+enigma remember --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --text-file $env:ENIGMA_DEMO_MEMORY_FILE --purpose user_memory --tags local
+enigma context --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --query "local context" --purpose local_context --out .\.enigma\context-pack.json
+enigma export --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --out .\.enigma\export.json
 enigma verify --export .\.enigma\export.json
 ```
 
@@ -180,7 +211,7 @@ Npm-first connector flow — one command connects every installed/config-present
 
 ```sh
 npm install -g enigma-memory
-enigma setup --client auto --connect-installed --overwrite
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite
 ```
 
 `--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`.
@@ -502,9 +533,11 @@ CLI/verifier:
 ```sh
 ENIGMA_DEMO_MEMORY_FILE=/absolute/path/to/tenant-approved-smoke-memory.txt
 test -f "$ENIGMA_DEMO_MEMORY_FILE"
-enigma init --bundle ./.enigma/bundle.json
-enigma remember --bundle ./.enigma/bundle.json --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose verification
-enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
+ENIGMA_PASSPHRASE_FILE=./.enigma/passphrase
+test -s "$ENIGMA_PASSPHRASE_FILE" || { printf '%s\n' 'Create ./.enigma/passphrase securely before continuing.' >&2; exit 1; }
+enigma init --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE"
+enigma remember --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose verification
+enigma export --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --out ./.enigma/export.json
 enigma verify --export ./.enigma/export.json
 ```
 
@@ -517,7 +550,7 @@ printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion
 Connector/importer/relay/gateway checks:
 
 ```sh
-enigma doctor
+enigma doctor --bundle ./.enigma/bundle.json
 enigma import chatgpt --file ./chatgpt-export.json --out ./enigma-import-report.json
 enigma capsule export --file ./enigma-import-report.json --out ./enigma-capsule.json
 enigma capsule import --file ./enigma-capsule.json --bundle "$PWD/.enigma/bundle.json"

package/docs/installers-and-desktop.md

@@ -8,13 +8,14 @@ Use the published package path when you want the current supported local install
 
 ```sh
 npm install -g enigma-memory
-enigma test-drive --dry-run
-enigma setup --overwrite
+test -s "$HOME/.enigma/passphrase" || { printf '%s\n' 'Create the protected passphrase file before setup.' >&2; exit 1; }
+enigma test-drive --dry-run --insecure-dev # INSECURE, EVALUATION ONLY
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --overwrite
 enigma doctor
 enigma connect <client> --dry-run
 ```
 
-The package exposes the CLI bins `enigma`, `enigma-verify`, `enigma-mcp`, `enigma-relay`, `enigma-gateway`, and `enigma-native-host`. Node.js `>=24` is required. The installer smoke path keeps `enigma test-drive --dry-run` and `enigma connect <client> --dry-run` non-mutating; `enigma setup --overwrite` writes Enigma-controlled local artifacts only and does not write third-party app configs. It does not prove provider deletion, model forgetting, hosted availability, compliance certification, savings, or provider-native memory removal.
+The package exposes the CLI bins `enigma`, `enigma-verify`, `enigma-mcp`, `enigma-relay`, `enigma-gateway`, and `enigma-native-host`. Node.js `>=24` is required. The installer smoke path labels `enigma test-drive --dry-run --insecure-dev` as **INSECURE, EVALUATION ONLY**; normal `enigma setup --passphrase-file "$HOME/.enigma/passphrase" --overwrite` writes an encrypted Enigma-controlled bundle and does not write third-party app configs. It does not prove provider deletion, model forgetting, hosted availability, compliance certification, savings, or provider-native memory removal.
 
 ## Tier 2: generated source installer assets
 
@@ -32,9 +33,9 @@ node scripts/build-installer-assets.mjs --out-dir dist/installer-assets --write
 
 Generated asset paths are listed in deterministic code-point lexical order:
 
-- `homebrew/enigma-memory.rb` — Homebrew formula draft. It is not submitted to a tap by the generator; release engineering must replace the source archive URL and SHA before any tap workflow. Its test metadata exercises `enigma test-drive --dry-run`, `enigma setup --dry-run`, and `enigma doctor`, then prints the next client-connect preview command.
-- `install-linux.sh` — POSIX shell source installer. It previews by default and only mutates global npm/local setup files when called with `--execute`. Its preview includes package install, `enigma test-drive --dry-run`, `enigma setup --bundle <bundle> --overwrite`, `enigma doctor`, and `enigma connect <client> --dry-run` as the next client-connect command.
-- `install-windows.ps1` — PowerShell source installer. It previews by default and only runs `npm install -g enigma-memory`, `enigma test-drive --dry-run`, `enigma setup --bundle <bundle> --overwrite`, and `enigma doctor` when called with `-Execute`; it then prints `enigma connect <client> --dry-run` as the next client-connect command.
+- `homebrew/enigma-memory.rb` — Homebrew formula draft. Its disposable test metadata uses explicit `--insecure-dev` and labels it **INSECURE, EVALUATION ONLY**; normal setup documentation requires a passphrase file.
+- `install-linux.sh` — POSIX shell source installer. It previews by default and only mutates global npm/local setup files when called with `--execute`. Execute mode requires `--passphrase-file <path>` (default `./.enigma/passphrase`) and passes it explicitly to encrypted setup.
+- `install-windows.ps1` — PowerShell source installer. It previews by default and only runs setup with `-Execute`; execute mode requires a non-empty `-PassphraseFile` (default `.\.enigma\passphrase`) and passes it explicitly to encrypted setup.
 - `installer-assets-manifest.json` — deterministic public manifest with checksums for the generated source assets.
 - `macos-pkgbuild/README.md` — macOS package source plan and blockers, not a signed package.
 - `macos-pkgbuild/manifest.json` — macOS package source metadata and blockers, not a signed package.
@@ -62,7 +63,7 @@ Until those blockers are cleared, use npm or generated source scripts only.
 
 ## Homebrew path
 
-The formula generated under `homebrew/enigma-memory.rb` is a draft for a future tap workflow. It records the intended package name, license, Node dependency, command shims, and installer smoke test shape: `enigma test-drive --dry-run`, `enigma setup --dry-run`, `enigma doctor`, and the printed next command `enigma connect <client> --dry-run`. Before publication, release engineering must replace the placeholder tarball URL and SHA with a real release archive and confirm the formula installs only the intended package files.
+The formula generated under `homebrew/enigma-memory.rb` is a draft for a future tap workflow. It records the intended package name, license, Node dependency, command shims, and installer smoke shape. Formula-only dry runs use explicit `--insecure-dev` and are labeled **INSECURE, EVALUATION ONLY**; normal setup uses `--passphrase-file "$HOME/.enigma/passphrase"`. Before publication, release engineering must replace the placeholder tarball URL and SHA with a real release archive and confirm the formula installs only the intended package files.
 
 ## Desktop tray model boundary