enigma-memory 0.1.0 → 0.1.2

package/apps/desktop/src/tray.js

@@ -0,0 +1,231 @@
+export const TRAY_MODEL_SCHEMA = 'enigma.desktop.tray_model.v1';
+export const TRAY_MENU_SCHEMA = 'enigma.desktop.tray_menu.v1';
+
+export const TRAY_ACTION_TYPES = Object.freeze({
+  STATUS: 'tray/status',
+  QUICKSTART: 'tray/quickstart',
+  CONNECT_CLIENTS: 'tray/connect-clients',
+  OPEN_DOCS: 'tray/open-docs',
+  RUN_DIAGNOSTICS: 'tray/run-diagnostics',
+  QUIT: 'tray/quit',
+});
+
+const DEFAULT_DOCS_URL = 'https://docs.enigmaprotocol.net/docs/install';
+const STATUS_VALUES = Object.freeze(new Set(['not-installed', 'ready', 'needs-setup', 'running', 'degraded', 'offline']));
+const DIAGNOSTIC_VALUES = Object.freeze(new Set(['idle', 'queued', 'running', 'passed', 'failed']));
+const CLIENTS = Object.freeze([
+  Object.freeze({ id: 'claude-desktop', label: 'Claude Desktop', kind: 'mcp-client' }),
+  Object.freeze({ id: 'cursor', label: 'Cursor', kind: 'mcp-client' }),
+  Object.freeze({ id: 'vscode', label: 'VS Code', kind: 'mcp-client' }),
+  Object.freeze({ id: 'browser-bridge', label: 'Browser bridge', kind: 'extension' }),
+]);
+
+function cleanString(value) {
+  return String(value ?? '').trim();
+}
+
+function normalizeStatus(value) {
+  const status = cleanString(value);
+  return STATUS_VALUES.has(status) ? status : 'needs-setup';
+}
+
+function normalizeDiagnostics(value) {
+  const status = cleanString(value);
+  return DIAGNOSTIC_VALUES.has(status) ? status : 'idle';
+}
+
+function normalizeClients(value) {
+  const requested = Array.isArray(value) ? value : [];
+  const seen = new Set();
+  const known = new Map(CLIENTS.map((client) => [client.id, client]));
+  const clients = [];
+  for (const item of requested) {
+    const id = cleanString(typeof item === 'string' ? item : item?.id);
+    const connected = typeof item === 'string' || item?.connected === true;
+    if (!known.has(id) || seen.has(id) || !connected) continue;
+    seen.add(id);
+    clients.push({ ...known.get(id), connected: true });
+  }
+  for (const client of CLIENTS) {
+    if (!seen.has(client.id)) clients.push({ ...client, connected: false });
+  }
+  return clients;
+}
+
+function menuItem(id, label, action, options = {}) {
+  return Object.freeze({
+    id,
+    label,
+    action,
+    enabled: options.enabled !== false,
+    checked: options.checked === true,
+    role: cleanString(options.role) || 'item',
+    honest_boundary: cleanString(options.honest_boundary),
+  });
+}
+
+function action(type, payload = {}) {
+  return Object.freeze({ type, ...payload });
+}
+
+export function createTrayState(options = {}) {
+  const status = normalizeStatus(options.status);
+  const clients = normalizeClients(options.connectedClients ?? options.clients);
+  const connectedCount = clients.filter((client) => client.connected).length;
+  return Object.freeze({
+    schema: TRAY_MODEL_SCHEMA,
+    model_only: true,
+    native_tray_started: false,
+    status,
+    status_label: statusLabel(status),
+    quickstart_available: options.quickstartAvailable !== false,
+    clients: Object.freeze(clients.map((client) => Object.freeze({ ...client }))),
+    connected_client_count: connectedCount,
+    docs_url: cleanString(options.docsUrl) || DEFAULT_DOCS_URL,
+    diagnostics: Object.freeze({
+      status: normalizeDiagnostics(options.diagnosticsStatus),
+      last_result: cleanString(options.diagnosticsResult),
+    }),
+    quit_requested: options.quitRequested === true,
+  });
+}
+
+export function statusLabel(status) {
+  switch (normalizeStatus(status)) {
+    case 'ready':
+      return 'Ready';
+    case 'running':
+      return 'Running';
+    case 'degraded':
+      return 'Needs attention';
+    case 'offline':
+      return 'Offline';
+    case 'not-installed':
+      return 'Not installed';
+    default:
+      return 'Needs setup';
+  }
+}
+
+export function createTrayMenu(state = createTrayState()) {
+  const model = state?.schema === TRAY_MODEL_SCHEMA ? state : createTrayState(state);
+  return Object.freeze({
+    schema: TRAY_MENU_SCHEMA,
+    model_only: true,
+    native_tray_started: false,
+    status: model.status,
+    items: Object.freeze([
+      menuItem('status', `Status: ${model.status_label}`, TRAY_ACTION_TYPES.STATUS, {
+        enabled: false,
+        honest_boundary: 'Local tray status is an application model snapshot, not cryptographic proof.',
+      }),
+      menuItem('quickstart', 'Run quickstart', TRAY_ACTION_TYPES.QUICKSTART, {
+        enabled: model.quickstart_available && model.status !== 'running',
+        honest_boundary: 'Emits an intent to run the existing quickstart command; this module does not execute commands.',
+      }),
+      menuItem('connect-clients', `Connect clients (${model.connected_client_count})`, TRAY_ACTION_TYPES.CONNECT_CLIENTS, {
+        honest_boundary: 'Opens client-connection intent only; no MCP client is configured by this pure model.',
+      }),
+      menuItem('open-docs', 'Open install docs', TRAY_ACTION_TYPES.OPEN_DOCS, {
+        honest_boundary: 'Emits a docs URL intent only; this module does not launch a browser.',
+      }),
+      menuItem('run-diagnostics', diagnosticsLabel(model.diagnostics.status), TRAY_ACTION_TYPES.RUN_DIAGNOSTICS, {
+        enabled: model.diagnostics.status !== 'running',
+        honest_boundary: 'Emits diagnostics intent only; the caller owns command execution and evidence capture.',
+      }),
+      menuItem('separator-before-quit', '—', '', { enabled: false, role: 'separator' }),
+      menuItem('quit', 'Quit Enigma tray', TRAY_ACTION_TYPES.QUIT, {
+        honest_boundary: 'Emits quit intent only; host application owns process shutdown.',
+      }),
+    ]),
+  });
+}
+
+function diagnosticsLabel(status) {
+  switch (normalizeDiagnostics(status)) {
+    case 'queued':
+      return 'Diagnostics queued';
+    case 'running':
+      return 'Diagnostics running';
+    case 'passed':
+      return 'Run diagnostics (last passed)';
+    case 'failed':
+      return 'Run diagnostics (last failed)';
+    default:
+      return 'Run diagnostics';
+  }
+}
+
+export function trayStatus(status) {
+  return action(TRAY_ACTION_TYPES.STATUS, { status: normalizeStatus(status) });
+}
+
+export function runQuickstart(options = {}) {
+  return action(TRAY_ACTION_TYPES.QUICKSTART, { bundle: cleanString(options.bundle) || '<bundle-path>', overwrite: options.overwrite !== false });
+}
+
+export function connectClients(clientIds = []) {
+  return action(TRAY_ACTION_TYPES.CONNECT_CLIENTS, { clients: normalizeClients(clientIds).filter((client) => client.connected).map((client) => client.id) });
+}
+
+export function openDocs(url = DEFAULT_DOCS_URL) {
+  return action(TRAY_ACTION_TYPES.OPEN_DOCS, { url: cleanString(url) || DEFAULT_DOCS_URL });
+}
+
+export function runDiagnostics(scope = 'local') {
+  return action(TRAY_ACTION_TYPES.RUN_DIAGNOSTICS, { scope: cleanString(scope) || 'local' });
+}
+
+export function quitTray() {
+  return action(TRAY_ACTION_TYPES.QUIT, { quit_requested: true });
+}
+
+export function reduceTrayState(state = createTrayState(), requestedAction = {}) {
+  const model = state?.schema === TRAY_MODEL_SCHEMA ? state : createTrayState(state);
+  const type = cleanString(requestedAction.type);
+  switch (type) {
+    case TRAY_ACTION_TYPES.STATUS:
+      return createTrayState({ ...model, status: requestedAction.status });
+    case TRAY_ACTION_TYPES.QUICKSTART:
+      return createTrayState({ ...model, status: 'running', diagnosticsStatus: model.diagnostics.status });
+    case TRAY_ACTION_TYPES.CONNECT_CLIENTS:
+      return createTrayState({ ...model, connectedClients: requestedAction.clients });
+    case TRAY_ACTION_TYPES.OPEN_DOCS:
+      return createTrayState({ ...model, docsUrl: requestedAction.url });
+    case TRAY_ACTION_TYPES.RUN_DIAGNOSTICS:
+      return createTrayState({ ...model, diagnosticsStatus: 'queued' });
+    case TRAY_ACTION_TYPES.QUIT:
+      return createTrayState({ ...model, quitRequested: true });
+    default:
+      return model;
+  }
+}
+
+export function trayActionIntent(requestedAction = {}) {
+  const type = cleanString(requestedAction.type);
+  switch (type) {
+    case TRAY_ACTION_TYPES.STATUS:
+      return Object.freeze({ kind: 'status', status: normalizeStatus(requestedAction.status), side_effect: false });
+    case TRAY_ACTION_TYPES.QUICKSTART:
+      return Object.freeze({ kind: 'quickstart', command: 'enigma', args: ['quickstart', '--bundle', '<bundle-path>', '--overwrite'], side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.CONNECT_CLIENTS:
+      return Object.freeze({ kind: 'connect_clients', clients: normalizeClients(requestedAction.clients).filter((client) => client.connected).map((client) => client.id), side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.OPEN_DOCS:
+      return Object.freeze({ kind: 'open_docs', url: cleanString(requestedAction.url) || DEFAULT_DOCS_URL, side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.RUN_DIAGNOSTICS:
+      return Object.freeze({ kind: 'run_diagnostics', command: 'enigma', args: ['doctor'], side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.QUIT:
+      return Object.freeze({ kind: 'quit', side_effect: 'caller-owned' });
+    default:
+      return Object.freeze({ kind: 'unknown', side_effect: false });
+  }
+}
+
+export const trayActions = Object.freeze({
+  trayStatus,
+  runQuickstart,
+  connectClients,
+  openDocs,
+  runDiagnostics,
+  quitTray,
+});

package/docs/browser-extension-install.md

@@ -0,0 +1,169 @@
+# Browser extension local install
+
+This guide is for local developer installation only. It does not submit Enigma to Chrome Web Store, Microsoft Edge Add-ons, Mozilla Add-ons, or any external account.
+
+## Boundaries
+
+- The extension is loaded by the user as an unpacked or temporary local extension.
+- The native host is installed by the user and runs on the local machine as `com.enigma.native_host`.
+- Context insertion requires two user clicks: request context, then approve insertion.
+- The extension must not auto-inject context into a provider page.
+- The extension does not use browser sync storage and must not store raw memory in browser storage.
+- Provider-native memory is cache only. The local Enigma bundle/native host remains canonical.
+
+## Package preflight
+
+From the package root, validate the extension before loading or zipping it:
+
+```sh
+node scripts/package-browser-extension.mjs
+```
+
+The command emits public-safe JSON with a deterministic file list, SHA-256 checksums, and safety fields. To also write a deterministic local ZIP for manual inspection or enterprise review:
+
+```sh
+node scripts/package-browser-extension.mjs --zip ./dist/enigma-browser-extension.zip
+```
+
+The ZIP command does not publish, sign, upload, or submit the extension.
+
+## Install the native host first
+
+Install the npm package so both `enigma` and `enigma-native-host` are available:
+
+```sh
+npm install -g enigma-memory
+```
+
+Create or select a local bundle:
+
+```sh
+enigma init --bundle <absolute-bundle-path> --subject local-user --display-name "Local user"
+```
+
+Set `ENIGMA_BUNDLE` for the browser-launched host process, 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.
+
+Resolve the absolute host executable path:
+
+```sh
+command -v enigma-native-host
+```
+
+Windows PowerShell:
+
+```powershell
+(Get-Command enigma-native-host.cmd).Source
+```
+
+## Load the extension locally
+
+### Chrome
+
+1. Open `chrome://extensions`.
+2. Enable **Developer mode**.
+3. Select **Load unpacked**.
+4. Choose `enigma/apps/browser-extension`.
+5. Open the Enigma extension details and copy the 32-character extension ID.
+
+### Microsoft Edge
+
+1. Open `edge://extensions`.
+2. Enable **Developer mode**.
+3. Select **Load unpacked**.
+4. Choose `enigma/apps/browser-extension`.
+5. Open the Enigma extension details and copy the 32-character extension ID.
+
+### Firefox
+
+1. Open `about:debugging#/runtime/this-firefox`.
+2. Select **Load Temporary Add-on**.
+3. Choose `enigma/apps/browser-extension/manifest.json`.
+4. Copy the temporary extension ID shown by Firefox. For repeatable development, use a stable development add-on ID and pass the same value to the native-host manifest generator.
+
+## Generate the browser native-host manifest
+
+Generate a manifest after you know the extension ID and absolute host path.
+
+Chrome:
+
+```sh
+enigma native-host manifest \
+  --browser chrome \
+  --host-path <absolute-enigma-native-host-path> \
+  --extension-id <chrome-extension-id> \
+  --out ./com.enigma.native_host.json
+```
+
+Edge:
+
+```sh
+enigma native-host manifest \
+  --browser edge \
+  --host-path <absolute-enigma-native-host-path> \
+  --extension-id <edge-extension-id> \
+  --out ./com.enigma.native_host.json
+```
+
+Firefox:
+
+```sh
+enigma native-host manifest \
+  --browser firefox \
+  --host-path <absolute-enigma-native-host-path> \
+  --extension-id <firefox-extension-id> \
+  --out ./com.enigma.native_host.json
+```
+
+Preview browser-specific install locations without mutating registry or profile state:
+
+```sh
+enigma native-host install-plan \
+  --browser chrome \
+  --manifest <absolute-path-to-com.enigma.native_host.json>
+```
+
+Use `--browser edge` or `--browser firefox` for the other browsers. The install plan is a checklist: it does not copy manifests, write registry keys, or change browser profiles. Copy the generated manifest to the listed native messaging host location yourself, and on Windows review and run the listed registry command only when you are ready to register `com.enigma.native_host`.
+
+## Register the native-host manifest locally
+
+Use the paths from `enigma native-host install-plan` as the source of truth. These are the common manual targets:
+
+### Chrome native host
+
+- macOS per-user: `<home>/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.enigma.native_host.json`
+- Linux per-user: `<home>/.config/google-chrome/NativeMessagingHosts/com.enigma.native_host.json`
+- Windows per-user: copy the manifest to an operator-chosen local file, then set `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.enigma.native_host` to that manifest path.
+
+### Microsoft Edge native host
+
+- macOS per-user: `<home>/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.enigma.native_host.json`
+- Linux per-user: `<home>/.config/microsoft-edge/NativeMessagingHosts/com.enigma.native_host.json`
+- Windows per-user: copy the manifest to an operator-chosen local file, then set `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.enigma.native_host` to that manifest path.
+
+### Firefox native host
+
+- macOS per-user: `<home>/Library/Application Support/Mozilla/NativeMessagingHosts/com.enigma.native_host.json`
+- Linux per-user: `<home>/.mozilla/native-messaging-hosts/com.enigma.native_host.json`
+- Windows per-user: copy the manifest to an operator-chosen local file, then set `HKCU\Software\Mozilla\NativeMessagingHosts\com.enigma.native_host` to that manifest path.
+
+All-users locations and registry hives are operator-managed deployment choices. Local developer install should prefer per-user targets unless an enterprise policy requires otherwise.
+
+## Local insertion demo flow
+
+1. Confirm the native-host manifest allowlist uses the extension ID from the local browser profile.
+2. Restart the browser after native-host registration so it can discover `com.enigma.native_host`.
+3. Visit a supported HTTPS provider page: ChatGPT, Claude, Kimi, or Perplexity.
+4. Open the Enigma control shown by the content script.
+5. Click **Request context**. The extension asks the local native host for a transient context pack; selected page text is included only if the user explicitly enables it for that request.
+6. Review the returned context in the panel.
+7. Click **Approve and insert** to insert plain text into the active prompt surface.
+8. Submit to the provider only if you choose to. Enigma does not submit prompts for you.
+
+After insertion, the extension records only target metadata, insertion timestamp, receipt metadata, and insertion counts. It must not write raw memory, context plaintext, or receipt plaintext into browser sync storage or public artifacts.
+
+## Troubleshooting
+
+- **Host not found**: confirm the manifest filename is `com.enigma.native_host.json`, the manifest `name` is `com.enigma.native_host`, and the browser-specific install location or registry key points to the manifest.
+- **Host exits immediately**: confirm `ENIGMA_BUNDLE` is visible to the browser-launched process or use a local wrapper that sets it before launching `enigma-native-host`.
+- **Extension cannot connect**: confirm the extension ID in the native-host manifest matches the locally loaded extension.
+- **No insertion happens**: confirm you clicked both **Request context** and **Approve and insert**. The extension intentionally does not auto-inject.

package/docs/developer-ecosystem.md

@@ -0,0 +1,74 @@
+# 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.
+
+## 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)
+- 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 the published `enigma-memory` package, runs:
+
+```sh
+npx enigma quickstart --overwrite
+npx enigma doctor
+```
+
+and then runs a small ESM import smoke. It does not require GitHub secrets, cloud provider credentials, npm tokens, private bundles, or local path assumptions.
+
+Use the workflow as a template in a consumer repository. It is intentionally limited to install/import/doctor smoke coverage and local proof generation; it does not publish packages, deploy infrastructure, or contact hosted Enigma cloud.
+
+## MCP client loop
+
+The generic MCP template uses the installed `enigma-mcp` command and exactly one environment placeholder:
+
+```json
+{
+  "mcpServers": {
+    "enigma": {
+      "command": "enigma-mcp",
+      "env": {
+        "ENIGMA_BUNDLE": "<ENIGMA_BUNDLE>"
+      }
+    }
+  }
+}
+```
+
+Replace `<ENIGMA_BUNDLE>` with the bundle file you control, or with the client-specific environment expansion syntax if your MCP client supports it. 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/hosted-cloud-product.md

@@ -0,0 +1,68 @@
+# Hosted cloud product contract
+
+This document separates the hosted-cloud product contract surface from the external systems still required before Enigma can sell or operate a hosted cloud service.
+
+## Production contract-ready now
+
+The source package now has pure contract builders and validators in `packages/hosted-cloud/src/index.js` for:
+
+- user account records;
+- tenant records;
+- hosted vault records;
+- API key metadata records;
+- usage billing records;
+- dashboard summaries;
+- backup drill records;
+- incident and SLA reference records.
+
+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 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;
+- missing operator evidence references are rejected;
+- raw memory, plaintext prompts, provider responses, transcripts, credential-looking values, token values, private keys, and API key secret material are rejected;
+- financial outcome claims, token ROI/profit claims, provider-side deletion claims, and model-forgetting claims are rejected;
+- API key contracts store identifiers, fingerprints, scopes, rotation refs, and timestamps only, not key material;
+- hosted vault contracts are opaque-record and plaintext-minimized contracts only;
+- billing records remain contract records until an external billing provider invoice flow is wired.
+
+Every builder emits `readiness.contract_ready: true` and `readiness.integration_kind: "contract_validator_only"`. It also emits `readiness.hosted_cloud_sellable: false` because contract readiness is not provider wiring, legal approval, security review, or operator go-live approval.
+
+## Externally blocked before hosted cloud can be sold
+
+Hosted cloud remains blocked until an operator wires and records evidence for all of the following:
+
+| Blocker | Required before selling hosted cloud |
+| --- | --- |
+| Auth provider | A real auth provider, tenant/user lifecycle, access-control rules, session/token handling, rotation, revocation, and audit evidence. |
+| Billing provider | A real billing provider, customer/subscription mapping, invoice lifecycle, tax/legal handling, dunning/refund policy, and reconciliation evidence. |
+| Legal docs | Approved hosted terms, privacy notice, service descriptions, acceptable-use terms, retention/deletion language, and claim review. |
+| Data processing terms | Approved DPA or equivalent data-processing terms, subprocessors, data residency, retention, deletion, legal hold, and customer notice process. |
+| Support ownership | Named support owner, escalation policy, incident owner, response process, status communication process, and support tooling. |
+| External security review | External security review or audit scope, remediation tracking, approval record, and release sign-off. |
+
+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.
+
+## Non-claims
+
+Hosted cloud collateral must not say or imply:
+
+- Enigma has live hosted cloud tenants before provider wiring and operator acceptance exist;
+- Enigma has made any model or provider forget data;
+- Enigma has provider-side deletion proof;
+- Enigma guarantees ROI, profit, investment return, token price movement, or invoice savings;
+- Enigma has SOC 2, HIPAA, GDPR, or other compliance certification unless separately audited and approved;
+- local/package evidence, contract validation, static docs, or dashboard summaries are live service evidence.
+
+Safe wording:
+
+```text
+Enigma has hosted-cloud contract builders and validators for account, tenant, vault, API key, billing, dashboard, backup drill, and incident/SLA records. Hosted cloud remains blocked until auth, billing, legal/data-processing terms, support ownership, external security review, and operator go-live evidence are complete.
+```
+
+Avoid wording:
+
+```text
+Enigma hosted cloud is ready to sell because the contracts exist.
+```

package/docs/installers-and-desktop.md

@@ -0,0 +1,76 @@
+# Installers and desktop boundary
+
+Enigma Memory currently has one production install tier and several source-asset tiers. This page is intentionally conservative: it documents what can be used now, what can be generated from source, and what is blocked before native installer distribution.
+
+## Tier 1: npm package now
+
+Use the published package path when you want the current supported local install:
+
+```sh
+npm install -g enigma-memory
+enigma quickstart --bundle ./.enigma/bundle.json --overwrite
+enigma doctor
+```
+
+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 local quickstart writes Enigma-controlled local artifacts only; it does not prove provider deletion, model forgetting, hosted availability, compliance certification, savings, or provider-native memory removal.
+
+## Tier 2: generated source installer assets
+
+The source checkout includes `scripts/build-installer-assets.mjs`, a dependency-free generator for reviewable installer source assets. Dry-run is the default:
+
+```sh
+node scripts/build-installer-assets.mjs --out-dir dist/installer-assets
+```
+
+Write mode is explicit:
+
+```sh
+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.
+- `install-linux.sh` — POSIX shell source installer. It previews by default and only mutates global npm/local quickstart files when called with `--execute`.
+- `install-windows.ps1` — PowerShell source installer. It previews by default and only runs `npm install -g enigma-memory`, `enigma quickstart`, and `enigma doctor` when called with `-Execute`.
+- `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.
+
+The generator intentionally redacts the requested output directory in its public manifest as `<requested-output-dir>`. The generated content must not embed tokens, local absolute paths, account identifiers, raw memory, provider transcripts, signing identities, or hosted credentials.
+
+## Native `.exe` and `.pkg` blockers
+
+No signed Windows `.exe` or signed/notarized macOS `.pkg` exists from this generator.
+
+Windows `.exe` distribution is blocked on:
+
+- A selected native installer builder and reproducible input tree.
+- A Windows code-signing certificate and signing workflow.
+- Release review that installer logs and metadata do not expose local paths, credentials, account data, raw memory, or provider transcripts.
+
+macOS `.pkg` distribution is blocked on:
+
+- macOS release runner access with `pkgbuild` and `productbuild`.
+- A staged package layout for npm-installed command shims and package resources.
+- Developer ID Installer certificate selection, signing, and notarization.
+- Release review of package scripts and evidence output.
+
+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 test shape. 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
+
+`apps/desktop/src/tray.js` is a pure tray model module. It exposes deterministic state/menu/action helpers for:
+
+- status
+- quickstart
+- connect clients
+- open docs
+- run diagnostics
+- quit
+
+It does not start a native tray process, create OS menu items, run shell commands, launch browsers, configure MCP clients, or quit a process. Host applications such as Electron, Tauri, WebView, or native wrappers must translate its action intents into real side effects and own their own OS integration, evidence capture, and shutdown behavior.

package/docs/memory-benchmarks.md

@@ -0,0 +1,51 @@
+# Memory benchmarks
+
+Enigma includes a local, dependency-free memory benchmark harness for package-readiness evidence:
+
+```sh
+cd enigma
+node scripts/run-memory-benchmarks.mjs
+node scripts/run-memory-benchmarks.mjs --out ./.enigma/memory-benchmark.json
+```
+
+The report schema is `enigma.memory_benchmark_suite.v1`. It is public-safe by design: aggregate metrics, commitments, citations, boundaries, and cross-provider profile labels are emitted, but raw fixture memory, question text, and answer text are not included.
+
+## External standards and boundaries
+
+- LoCoMo is the relevant long-term conversational-memory standard for multi-session QA, event summarization, and multimodal generation over long conversations. See https://snap-research.github.io/locomo/.
+- LongMemEval is the relevant standard for information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention. See https://arxiv.org/abs/2410.10813.
+- Letta's benchmark discussion is a useful boundary reminder: measured memory quality depends on the agent/framework/tool loop as well as memory-store mechanics. See https://www.letta.com/blog/benchmarking-ai-agent-memory/.
+
+This repository harness does not download or run LoCoMo, LongMemEval, provider APIs, or third-party agents. It mirrors their task categories with a deterministic local fixture so Enigma can make narrow package claims about local vault operations, context-pack generation, optimizer token estimates, export/import, verification, deduplication, abstention behavior, and latency.
+
+## What the harness measures
+
+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:
+
+- vault remember/update operations;
+- vault export and import;
+- context-pack retrieval through the passport package;
+- optimizer plan token estimates and duplicate removal;
+- bundle and context-pack verification;
+- p50/p95 latency with `performance.now`.
+
+Reported metrics include exact-answer recall, abstention correctness, context-token reduction versus a full-context baseline, duplicate candidates removed, operation latency summaries, verification status, and same-boundary cross-provider profile rows.
+
+## Claim limits
+
+The benchmark report is evidence for this local deterministic fixture only. It is not provider deletion proof, model forgetting proof, compliance certification, ROI evidence, provider invoice savings evidence, benchmark leadership proof, hosted cloud readiness, or a substitute for external LoCoMo/LongMemEval evaluation.
+
+Cross-provider rows are profile labels using the same Enigma context-pack boundary. They do not call or rank live provider models.
+
+## Extending with external datasets later
+
+To extend this harness with real external benchmark datasets without weakening claim boundaries:
+
+1. Add an explicit dataset loader that reads a local file supplied by the operator; do not add network downloads to the benchmark command.
+2. Preserve source license, version, split, and checksum metadata in the report.
+3. Keep raw conversations, private memory, questions, and answers out of public reports unless the dataset license and review process explicitly allow publication.
+4. Route every candidate through the same Enigma vault, context-pack, optimizer, export, and verify operations measured here.
+5. Add separate agent/model evaluation only when the evaluated agent loop is fixed and documented; do not attribute agent/tool behavior solely to the memory store.
+6. Keep release notes bounded to the observed command, dataset, timestamp, and review approval.