enigma-memory 0.1.18 → 0.1.22

package/README.md

@@ -1,5 +1,9 @@
 # Enigma
 
+> **Official $ENIGMA Token (Solana Mainnet):**  
+> Contract Address (CA): `EknDj8VZUHL6FhV9pSk3m6xP2U2sDzwjRDVstKeQpump`  
+> [Solscan Explorer](https://solscan.io/token/EknDj8VZUHL6FhV9pSk3m6xP2U2sDzwjRDVstKeQpump) • [Pump.fun](https://pump.fun/coin/EknDj8VZUHL6FhV9pSk3m6xP2U2sDzwjRDVstKeQpump) • [Official Website](https://enigmamemory.com) • [Official X (@Engimamemory)](https://x.com/Engimamemory)
+
 Enigma Memory is a local-first AI Memory Passport. It gives you one canonical local memory vault, receipt-backed proof for Enigma-controlled events, and MCP connections into assistants such as Claude Desktop, Cursor, Kimi Code, and generic MCP clients.
 
 Start with the Memory Drive loop below — one install, one connect, then health and status verification. You do not need to understand relay, gateway, mesh, browser, desktop, hosted infrastructure, or the proof network before trying Enigma locally.
@@ -13,18 +17,20 @@ Enigma does not claim that a closed provider deleted internal data, that model w
 Prerequisites:
 
 - Node.js `>=24`
-- No database, package registry account, provider credential, cloud credential, hosted Enigma account, or external account for the local setup path
+- A local passphrase supplied through `ENIGMA_PASSPHRASE` or a user-readable-only passphrase file; no database, package registry account, provider credential, cloud credential, hosted Enigma account, or external account is needed
 - Git only when you choose the advanced source-checkout path
 
 Use Enigma as your private Memory Drive for AI: install once, connect the AI clients you already have, then inspect drive health and passport status before remembering, retrieving, packaging, and verifying context.
 
 ```sh
 npm install -g enigma-memory
-enigma setup --bundle "$HOME/.enigma/bundle.json" --client auto --connect-installed --overwrite
+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 setup --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --client auto --connect-installed --overwrite
 echo "Keep all Q3 planning notes in the project-context tag." > memory.txt
-enigma remember --bundle "$HOME/.enigma/bundle.json" --text-file memory.txt
-enigma search --bundle "$HOME/.enigma/bundle.json" --query "Q3 planning"
-enigma context --bundle "$HOME/.enigma/bundle.json" --query "Q3 planning" --out "$HOME/.enigma/context-pack.json"
+enigma remember --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --text-file memory.txt
+enigma search --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --query "Q3 planning"
+enigma context --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --query "Q3 planning" --out "$HOME/.enigma/context-pack.json"
 enigma verify --export "$HOME/.enigma/export.json"
 ```
 
@@ -32,16 +38,45 @@ Windows CMD:
 
 ```cmd
 npm install -g enigma-memory
-enigma setup --bundle "%USERPROFILE%\.enigma\bundle.json" --client auto --connect-installed --overwrite
+set "ENIGMA_PASSPHRASE_FILE=%USERPROFILE%\.enigma\passphrase"
+if not exist "%ENIGMA_PASSPHRASE_FILE%" (echo Create the passphrase file with an approved secret manager or secure editor and restrict it to your user. & exit /b 1)
+enigma setup --bundle "%USERPROFILE%\.enigma\bundle.json" --passphrase-file "%ENIGMA_PASSPHRASE_FILE%" --client auto --connect-installed --overwrite
 echo Keep all Q3 planning notes in the project-context tag.> memory.txt
-enigma remember --bundle "%USERPROFILE%\.enigma\bundle.json" --text-file memory.txt
-enigma search --bundle "%USERPROFILE%\.enigma\bundle.json" --query "Q3 planning"
-enigma context --bundle "%USERPROFILE%\.enigma\bundle.json" --query "Q3 planning" --out "%USERPROFILE%\.enigma\context-pack.json"
+enigma remember --bundle "%USERPROFILE%\.enigma\bundle.json" --passphrase-file "%ENIGMA_PASSPHRASE_FILE%" --text-file memory.txt
+enigma search --bundle "%USERPROFILE%\.enigma\bundle.json" --passphrase-file "%ENIGMA_PASSPHRASE_FILE%" --query "Q3 planning"
+enigma context --bundle "%USERPROFILE%\.enigma\bundle.json" --passphrase-file "%ENIGMA_PASSPHRASE_FILE%" --query "Q3 planning" --out "%USERPROFILE%\.enigma\context-pack.json"
 enigma verify --export "%USERPROFILE%\.enigma\export.json"
 ```
 
-`enigma setup` is the credential-free first run: it creates the local `.enigma` workspace, bundle, proof artifacts, and a demo memory, then connects every installed/config-present client it detects (Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo, OpenCode, generic MCP). It skips clients that are not installed and never creates configs from scratch; preview with `--dry-run` first if you want to see which clients will be written. If no clients are installed, setup still succeeds and the local CLI path works; use the copy-paste MCP snippets below to connect a client later, or run `enigma connect generic-mcp --dry-run` to preview a standalone snippet. The same commands run on Windows PowerShell via the `enigma.cmd` shim the npm global install adds. Neither command prints raw memory plaintext.
+`enigma setup` is the encrypted first run: it requires `ENIGMA_PASSPHRASE` or `--passphrase-file`, creates the local `.enigma` workspace, encrypted bundle, proof artifacts, and a demo memory, then connects every installed/config-present client it detects (Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo, OpenCode, generic MCP). `enigma start` aliases the quickstart flow. Setup skips clients that are not installed and never creates configs from scratch; preview with `--dry-run` first if you want to see which clients will be written.
+
+### Keyring Security Modes & At-Rest Confidentiality
+
+- **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 local data. It stores an unencrypted developer keyring (`unencrypted: true`), provides no at-rest confidentiality, and must not be used for normal or persistent data.
+
+Encrypted + Solana-connected local flow:
+
+```sh
+npm install -g enigma-memory
+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 quickstart --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --overwrite
+enigma remember --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --text-file memory.txt
+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
+# Actual on-chain write, when you provide a funded Solana CLI keypair:
+# enigma chain submit-solana --file "$HOME/.enigma/anchor-batch.json" --cluster devnet --execute --keypair ~/.config/solana/id.json
+```
 
+`chain anchor-bundle` anchors only public commitment roots (`active_set_root`, `receipt_log_root`) and public refs. It never places raw memory, plaintext prompts, vault keys, passphrases, private keys, or encrypted bundle bodies on-chain. `chain submit-solana` defaults to dry-run; `--execute` writes a compact SPL Memo proof reference to Solana using your explicitly supplied funded keypair.
+
+The cypherpunk research basis is recorded in [`docs/research/sovereign-cypherpunk-memory.md`](docs/research/sovereign-cypherpunk-memory.md): Shamir 1979 threshold sharing, Merkle 1979 accumulators, Rubberhose/TrueCrypt plausible-deniability storage patterns, OTR/Signal ratchets, and Unix/Windows memory-locking constraints. The document is explicitly exploratory; production Enigma only ships the reviewed local vault primitives and public-safe Solana commitment anchoring described above.
+
+Run setup or quickstart before treating `enigma doctor` as a fully green install check. Doctor checks both the local package/runtime environment and existing connector configs; on a fresh install it can be red when an MCP client config already names an Enigma bundle that has not been initialized yet, or when clients still point somewhere else. That is expected first-run state, not evidence that the npm package failed to install. After creating `./.enigma/passphrase` through an approved secret manager or secure editor, 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`. If no clients are installed, setup still succeeds and the local CLI path works; use the copy-paste MCP snippets below to connect a client later.
+
+For the no-global-install 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 surface the same expected red generic-MCP missing-bundle state.
 ## Enigma Proof Network
 
 Enigma Proof Network is the public proof layer for AI memory: local tools can package privacy-preserving roots, refs, counts, signatures, scoped capability grants, revocations, and benchmark attestations without exposing raw memory, prompts, transcripts, completions, embeddings, tenant names, private keys, provider responses, or provider credentials.
@@ -50,6 +85,16 @@ The `enigma chain anchor|grant|revoke|attest|verify` commands are local planning
 
 Start with the category narrative in [`docs/market-category-narrative.md`](docs/market-category-narrative.md), then read the technical overview in [`docs/proof-network.md`](docs/proof-network.md), use its [Solana role](docs/proof-network.md#solana-role) section for the Solana-ready anchoring boundary, and read [`docs/proof-network-faq.md`](docs/proof-network-faq.md) for claim boundaries.
 
+## ZK state layer (localnet-verified)
+
+`cortex-v3/` contains a working zero-knowledge state layer for AI agent memory on Solana: every shared-state transition is a **client-generated Groth16 proof** (circom 2.2.3, BN254, ~2s proving) verified **on-chain** by the `enigma_nullifier` Anchor program via `alt_bn128` syscalls. Notes are E2EE-sealed (per-note XChaCha20-Poly1305 + HPKE/X25519 recipient envelopes) and bound into the proof as Poseidon commitments; revocations insert deterministic nullifiers into an Aztec-style indexed Merkle tree with strict non-membership proofs. Only `{proof, 6 public inputs}` ever leave the client.
+
+- Program: `E18KZR1Jq8fG3FFACpoHsE21ME3t1ftKPEwXL7cFWkoZ` (localnet; **not** on mainnet)
+- Circuit: 90,897 constraints, one fixed-shape VK, alias-safe (`Num2Bits_strict`, adversarially tested)
+- Reproduce end-to-end (E2EE → prove → on-chain verify → replay rejection): [`docs/zk-state-layer.md`](docs/zk-state-layer.md)
+
+Claim boundaries: development trusted setup (production needs a multi-party ceremony); nullifiers prove protocol-level non-use, never physical deletion; privacy requires a populated shared tree — the mechanism is verified, operative anonymity requires real participants.
+
 
 ## Advanced/source-only path
 
@@ -58,8 +103,9 @@ Use a source checkout only when you need source-only docs, Docker assets, browse
 ```sh
 git clone https://github.com/Enigma-Memory/enigma-memory.git
 cd enigma-memory
-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-relay demo
 enigma-gateway demo
 ```
@@ -74,10 +120,12 @@ POSIX shell:
 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_answer --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_answer --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
 ```
 
@@ -87,10 +135,12 @@ Windows PowerShell:
 New-Item -ItemType Directory -Force .enigma | Out-Null
 $env:ENIGMA_DEMO_MEMORY_FILE = "C:\path\to\tenant-approved-smoke-memory.txt"
 if (-not (Test-Path -LiteralPath $env:ENIGMA_DEMO_MEMORY_FILE)) { throw "Missing 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 $env:ENIGMA_DEMO_MEMORY_FILE --purpose user_memory --tags local
-enigma context --bundle .\.enigma\bundle.json --query "local context" --purpose local_answer --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_answer --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
 ```
 
@@ -156,7 +206,7 @@ Supported connector profiles are:
 - `opencode`
 - `generic-mcp`
 
-The one-command path above (`enigma setup --client auto --connect-installed --overwrite`) already connects every installed/config-present client. To connect or preview a single client instead:
+The one-command path above (`enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite`) already connects every installed/config-present client. To connect or preview a single client instead:
 
 ```sh
 enigma connect claude-desktop --dry-run
@@ -359,9 +409,11 @@ Local smoke path:
 ```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 local_test
-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 local_test
+enigma export --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --out ./.enigma/export.json
 enigma verify --export ./.enigma/export.json
 enigma boundary run --scenario committed_crossing
 ```

package/apps/cli/bin/enigma-desktop.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { startDesktopServer } from '../../desktop/src/server.mjs';
+import { ENIGMA_VERSION } from '../../../packages/core/src/version.mjs';
+import { createEmbeddingProvider } from '../../../packages/rag/src/index.js';
+import { EnigmaRagClient } from '../../../packages/sdk/src/index.js';
+
+export function parseArgs(argv) {
+  const flags = {
+    port: 8765,
+    openBrowser: true,
+    bundlePath: undefined,
+    passphrase: process.env.ENIGMA_PASSPHRASE || undefined,
+    vaultKey: process.env.ENIGMA_VAULT_KEY || undefined,
+    allowHostBoundDemo: process.env.ENIGMA_ALLOW_HOSTBOUND === '1' || undefined,
+    embeddingModel: undefined,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--port' || arg === '-p') {
+      const value = argv[++i];
+      const port = Number(value);
+      if (value === undefined || !Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error('--port must be an integer between 0 and 65535');
+      }
+      flags.port = port;
+    } else if (arg === '--no-open' || arg === '--headless') {
+      flags.openBrowser = false;
+    } else if (arg === '--bundle' || arg === '-b') {
+      flags.bundlePath = argv[++i];
+    } else if (arg === '--passphrase-file') {
+      const p = argv[++i];
+      if (!p) throw new Error('Missing file path for --passphrase-file');
+      flags.passphrase = fs.readFileSync(path.resolve(p), 'utf8').trim();
+    } else if (arg === '--vault-key-file') {
+      const p = argv[++i];
+      if (!p) throw new Error('Missing file path for --vault-key-file');
+      flags.vaultKey = fs.readFileSync(path.resolve(p), 'utf8').trim();
+    } else if (arg === '--allow-host-bound-demo') {
+      flags.allowHostBoundDemo = true;
+    } else if (arg === '--embedding-model') {
+      const modelType = argv[++i];
+      if (modelType !== 'neural' && modelType !== 'lexical') {
+        throw new Error('--embedding-model must be "neural" or "lexical"');
+      }
+      flags.embeddingModel = modelType;
+    } else if (arg === '--passphrase' || arg === '--vault-key') {
+      throw new Error(
+        `Passing secrets directly in CLI arguments (${arg}) is prohibited by security policy (process table leakage). `
+        + 'Use --passphrase-file <path>, --vault-key-file <path>, or set ENIGMA_PASSPHRASE / ENIGMA_VAULT_KEY environment variables.'
+      );
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    }
+  }
+
+  return flags;
+}
+
+export async function main(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  let flags;
+  try {
+    flags = parseArgs(argv);
+  } catch (err) {
+    io.stderr.write(`Error: ${err.message}\n`);
+    return 1;
+  }
+
+  if (flags.version) {
+    io.stdout.write(`enigma-desktop v${ENIGMA_VERSION}\n`);
+    return 0;
+  }
+
+  if (flags.help) {
+    io.stdout.write(`
+Enigma Sovereign AI Memory Terminal — Desktop GUI Application
+
+Usage: enigma-desktop [options]
+
+Options:
+  --port, -p <number>          Port to bind local desktop host server (default: 8765)
+  --no-open, --headless        Start host server without automatically opening window
+  --bundle, -b <path>          Active memory bundle path (default: .enigma/bundle.json)
+  --passphrase-file <path>     Path to file containing master passphrase (zero-secrets-in-argv)
+  --vault-key-file <path>      Path to file containing 32-byte hex master vault key
+  --allow-host-bound-demo      Explicitly allow host-bound key custody for local CLI demos
+  --embedding-model <type>      Embedding runtime: neural (default) or lexical
+  --version, -v                Display enigma-desktop version
+  --help, -h                   Show this help reference
+
+Environment Variables:
+  ENIGMA_PASSPHRASE            Master passphrase for encrypted memory and vector store
+  ENIGMA_VAULT_KEY             32-byte hex master vault key
+  ENIGMA_ALLOW_HOSTBOUND       Set to '1' to allow host-bound key custody in development
+\n`);
+    return 0;
+  }
+
+  let server;
+  try {
+    const embeddingProvider = flags.embeddingModel
+      ? createEmbeddingProvider({ modelType: flags.embeddingModel })
+      : undefined;
+    const ragClient = flags.embeddingModel
+      ? new EnigmaRagClient({ embeddingModel: flags.embeddingModel })
+      : undefined;
+    server = await startDesktopServer({
+      port: flags.port,
+      openBrowser: flags.openBrowser,
+      bundlePath: flags.bundlePath,
+      passphrase: flags.passphrase,
+      vaultKey: flags.vaultKey,
+      allowHostBoundDemo: flags.allowHostBoundDemo,
+      ...(embeddingProvider ? { embeddingProvider, ownEmbeddingProvider: true } : {}),
+      ...(ragClient ? { sdk: { ragClient, ownRagClient: true } } : {}),
+    });
+  } catch (err) {
+    io.stderr.write(`Error starting enigma-desktop: ${err.message}\n`);
+    return 1;
+  }
+
+  await new Promise((resolve) => {
+    process.on('SIGINT', resolve);
+    process.on('SIGTERM', resolve);
+  });
+
+  await server.close();
+  return 0;
+}
+
+if (process.argv[1] && process.argv[1].endsWith('enigma-desktop.mjs')) {
+  main().catch((err) => {
+    process.stderr.write(`Error starting enigma-desktop: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/apps/cli/bin/enigma-terminal.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { runTerminalConsole, renderTerminalBanner } from '../../../packages/terminal-console/index.mjs';
+import { ENIGMA_VERSION } from '../../../packages/core/src/version.mjs';
+
+function parseArgs(argv) {
+  const flags = {};
+  let execCommand = undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--bundle' || arg === '-b') {
+      flags.bundle = argv[++i];
+    } else if (arg === '--exec' || arg === '-e') {
+      execCommand = argv[++i];
+    } else if (arg === '--no-color') {
+      flags.noColor = true;
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+    }
+  }
+
+  return { flags, execCommand };
+}
+
+export async function main(argv = process.argv.slice(2), io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }) {
+  const { flags, execCommand } = parseArgs(argv);
+
+  if (flags.version) {
+    io.stdout.write(`enigma-terminal v${ENIGMA_VERSION}\n`);
+    return 0;
+  }
+
+  if (flags.help) {
+    io.stdout.write(renderTerminalBanner({ color: !flags.noColor }) + '\n');
+    io.stdout.write(`
+Usage: enigma-terminal [options]
+
+Options:
+  --bundle, -b <path>   Path to memory bundle (default: .enigma/bundle.json)
+  --exec, -e <cmd>      Execute a command and exit immediately
+  --no-color            Disable colored ANSI output
+  --help, -h            Show this help catalog
+  --version, -v         Show version
+
+Interactive Commands:
+  quickstart            Initialize a new sovereign memory vault
+  remember <text>       Store encrypted memory atom with signed receipt
+  context <query>       Retrieve purpose-scoped context pack
+  tree                  Render live ASCII Merkle tree with proof path
+  tui | dashboard       Launch real-time terminal control plane HUD
+  enclave cycle         Execute atomic ephemeral key zeroization
+  swarm status          Inspect multi-agent swarm namespace state
+  export / verify       Export & verify cryptographic receipts offline
+  token | ca            Display Solana SPL token contract address
+  exit | quit           Close session
+\n`);
+    return 0;
+  }
+
+  return await runTerminalConsole({
+    bundlePath: flags.bundle || '.enigma/bundle.json',
+    color: !flags.noColor,
+    execCommand,
+    interactive: Boolean(io.stdin?.isTTY) && !execCommand,
+    io,
+  });
+}
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  return metaUrl.endsWith(process.argv[1].replace(/\\/g, '/')) || process.argv[1].replace(/\\/g, '/').endsWith('enigma-terminal.mjs');
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = await main();
+}