mumpix 1.0.6 → 1.0.13

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 1.0.11 - 2026-03-03
+
+## 1.0.12 - 2026-03-03
+
+### Fixes
+- Fixed CLI database opening bug: `mumpix` commands now correctly `await Mumpix.open(...)` before operations, resolving `db.close is not a function`.
+
+### Verification
+- Added executable truth-audit script: `npm run verify:claims`.
+- Script validates core API, WAL replay, verified audit methods, integrations, CLI basic commands, SDK error surface, and license policy defaults.
+
+### Documentation
+- Updated README examples to use `await Mumpix.open(...)`.
+- Clarified that `strict`/`verified` are tier-gated capabilities (SDK and CLI).
+- Added `verify:claims` usage to the examples section.
+
+## Unreleased
+
+### Licensing (offline/air-gapped)
+- Added monthly tier capability mapping for paid durability modes (`eventual`, `strict`) while active.
+- Set monthly offline lease default to 45 days (`MUMPIX_LICENSE_MAX_DAYS_MONTHLY=45` by default).
+- Set enterprise/government/compliance lease defaults to long-window values (100 years default, env configurable).
+- Enforced expiry downgrade policy: expired paid licenses continue in `eventual` mode; paid modes require renewal.
+- Added `examples/license-expiry-downgrade-check.js` to verify downgrade behavior locally.
+
+### Authentication
+- Added local account auth state support in `src/core/auth.js`.
+- Added CLI auth commands: `mumpix auth login|status|logout`.
+- Added automatic local-license loading in `MumpixDB.open()` when `licenseKey` is not passed explicitly.
+- Added install-time auth script (`postinstall`) that prompts for account sign-in in interactive terminals.
+- Added browser-open device flow on install; skip path remains `eventual` only.
+
+## 1.0.9 - 2026-03-02
+
+### Developer experience
+- Added `MumpixDevClient` HTTP SDK for developers building on Mumpix services.
+- Added `MumpixApiError` with structured `.status` and `.data` for reliable client-side error handling.
+- Added API helpers for memory ops, explorer file ops, settings, ROM/manual endpoints, and export URL generation.
+- Added `examples/developer-sdk.js` quick-start integration script.
+- Updated README with a dedicated Developer SDK usage section and method reference.
+
+## 1.0.8 - 2026-02-27
+
+### Crash safety + integrity recovery hardening
+- Added durable WAL writes (`fdatasync`) before main-file append to ensure recovery intent survives crashes.
+- Added process lock file (`.lock`) to prevent concurrent writers from corrupting the same database file.
+- Added strict-mode recovery path for tail corruption when WAL exists:
+  - truncates corrupted tail to last verified-good record set,
+  - replays WAL,
+  - continues open instead of hard-failing.
+- Kept strict behavior secure when no WAL evidence exists (tamper/noise still fails fast).
+
+## 1.0.7 - 2026-02-27
+
+### Documentation
+- Updated licensing and tier model in README to capability-based gating:
+  - Community: `eventual`
+  - Developer/Teams: `eventual`, `strict`
+  - Compliance: `eventual`, `strict`, `verified`
+- Removed outdated mention of a 100-record free-tier cap from package docs.
+
 ## 1.0.6 - 2026-02-27
 
 ### Security hardening
@@ -19,4 +80,3 @@
 
 ### Reliability
 - Hardened strict-mode behavior to fail fast on malformed or tampered WAL/record entries.
-

package/README.md

@@ -27,7 +27,7 @@ If you've ever watched an agent "forget" what it just learned, or had to explain
 const { Mumpix } = require('mumpix')
 
 // Open (or create) a local database
-const db = Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+const db = await Mumpix.open('./agent.mumpix', { consistency: 'eventual' })
 
 // Store memories
 await db.remember('User prefers TypeScript over JavaScript')
@@ -45,7 +45,47 @@ await db.close()
 
 ## API
 
-### `Mumpix.open(filePath, [opts])` → `MumpixDB`
+### Developer SDK (HTTP Client)
+
+For developers integrating Mumpix-backed services (local runner, benchmark APIs, hosted tools):
+
+```js
+const { MumpixDevClient } = require('mumpix')
+
+const client = new MumpixDevClient({
+  baseUrl: 'https://mumpixdb.com/benchmark'
+})
+
+const health = await client.health()
+await client.remember('user likes concise answers')
+const hit = await client.recall('what does the user like?')
+const stats = await client.stats()
+```
+
+### `MumpixDevClient` methods
+
+- `health()`
+- `remember(content)`
+- `recall(query)`
+- `recallMany(query, k)`
+- `memories()`
+- `clear()`
+- `stats()`
+- `settings()`
+- `updateSettings(patch)`
+- `files()`
+- `readFile(file, { atTs, source })`
+- `timeline(file, { source })`
+- `exportUrl(file, format, { atTs, source })`
+- `roms()`
+- `manualForRom(file)`
+- `manualViewUrl(file, { isolate, v })`
+
+Errors are thrown as `MumpixApiError` with `.status` and `.data` fields.
+
+---
+
+### `Mumpix.open(filePath, [opts])` → `Promise<MumpixDB>`
 
 Opens (or creates) a Mumpix database.
 
@@ -54,6 +94,8 @@ Opens (or creates) a Mumpix database.
 | `consistency` | `string` | `'eventual'` | `'eventual'` / `'strict'` / `'verified'` |
 | `embedFn` | `async fn(texts[]) → number[][]` | — | Custom embedding function (OpenAI, Cohere, etc.) |
 
+Note: `strict` and `verified` are tier-gated capabilities. Without an active paid license, paid mode requests are blocked or downgraded to `eventual` based on license state.
+
 ### Consistency modes
 
 | Mode | Write behaviour | Audit log | Use case |
@@ -105,7 +147,7 @@ await db.close()
 ### Verified-mode methods
 
 ```js
-const db = Mumpix.open('./compliance.mumpix', { consistency: 'verified' })
+const db = await Mumpix.open('./compliance.mumpix', { consistency: 'verified' })
 
 // Full audit log
 await db.audit()
@@ -145,7 +187,7 @@ async function embedFn(texts) {
   return res.data.map(d => d.embedding)
 }
 
-const db = Mumpix.open('./agent.mumpix', { consistency: 'strict', embedFn })
+const db = await Mumpix.open('./agent.mumpix', { consistency: 'strict', embedFn })
 // db.recall() and db.recallMany() now use OpenAI embeddings automatically
 ```
 
@@ -157,7 +199,7 @@ const db = Mumpix.open('./agent.mumpix', { consistency: 'strict', embedFn })
 const { Mumpix } = require('mumpix')
 const { MumpixVectorStore, MumpixChatMemory, MumpixRetriever } = require('mumpix/src/integrations/langchain')
 
-const db = Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+const db = await Mumpix.open('./agent.mumpix', { consistency: 'strict' })
 
 // As a VectorStore
 const store = new MumpixVectorStore(db)
@@ -178,7 +220,7 @@ const results = await retriever.getRelevantDocuments('query')
 const { Mumpix } = require('mumpix')
 const { MumpixIndex, MumpixReader } = require('mumpix/src/integrations/llamaindex')
 
-const db = Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+const db = await Mumpix.open('./agent.mumpix', { consistency: 'strict' })
 
 const index    = new MumpixIndex(db)
 const retriever = index.asRetriever({ topK: 5 })
@@ -213,6 +255,8 @@ mumpix recall ./agent.mumpix "query" --consistency=strict
 mumpix shell  ./compliance.mumpix --consistency=verified
 ```
 
+Note: CLI strict/verified modes are tier-gated the same as SDK/API mode selection.
+
 ---
 
 ## File format
@@ -221,8 +265,8 @@ The `.mumpix` file is plain NDJSON — human-readable, portable, no binary parse
 
 ```
 {"v":1,"consistency":"strict","created":1740000000000,"path":"agent.mumpix"}
-{"id":1,"content":"User prefers TypeScript","ts":1740000001000,"h":"0x4a2b1c3d"}
-{"id":2,"content":"Use pnpm workspaces","ts":1740000002000,"h":"0x9f8e7d6c"}
+{"id":1,"content":"User prefers TypeScript","ts":1740000001000,"h":"hmac256:..."}
+{"id":2,"content":"Use pnpm workspaces","ts":1740000002000,"h":"hmac256:..."}
 ```
 
 **Crash safety**: Mumpix uses a WAL (`.mumpix.wal`). On write:
@@ -242,6 +286,20 @@ On open, any leftover WAL is replayed before accepting new writes. A record is e
 node examples/basic.js          # Zero-config 5-line demo
 node examples/agent-memory.js   # Persistent agent preferences (run twice)
 node examples/verified-mode.js  # Compliance audit log export
+npm run verify:claims           # executable truth-audit for package claims
+```
+
+### Release maintenance
+
+```bash
+# Publish current version and deprecate all older npm versions
+npm run release:publish-and-deprecate -- --otp=123456
+
+# Optional flags:
+# --skip-verify   skip verify:claims
+# --skip-publish  only deprecate older versions
+# --dry-run       no writes to npm
+# --remove-old    try to unpublish old versions; deprecate on failure
 ```
 
 ---
@@ -262,14 +320,35 @@ Copyright © 2026 Mumpix (vdsx.cloud). All Rights Reserved.
 
 ## Licensing & Tiers
 
-Mumpix requires a license key for commercial use and advanced features.
+Mumpix uses capability-based tiering: community is for building, paid tiers are for production operation and compliance.
 
-| Feature | Free | Pro ($79/mo) | Enterprise ($5K) |
-|---|---|---|---|
-| Max Records | 100 | Unlimited | Unlimited |
-| `strict` mode | ✅ | ✅ | ✅ |
-| `verified` mode | ❌ | ✅ | ✅ |
-| Offline Use | ✅ | ✅ | ✅ |
+| Capability | Community (Free) | Developer ($19/mo) | Teams ($79/mo) | Compliance ($5K/mo) |
+|---|---|---|---|---|
+| `eventual` mode | ✅ | ✅ | ✅ | ✅ |
+| `strict` mode | ❌ | ✅ | ✅ | ✅ |
+| `verified` mode | ❌ | ❌ | ❌ | ✅ |
+| Record writes | Unlimited | Unlimited | Unlimited | Unlimited |
+| Offline use | ✅ | ✅ | ✅ | ✅ |
+
+### Tier intent
+
+- **Community**: build and prototype with full local development flow.
+- **Developer**: unlock production durability via `strict`.
+- **Teams**: same core durability plus team/commercial operations.
+- **Compliance**: regulated workflows with `verified` audit capabilities.
+
+### Offline/Air-gapped expiry policy
+
+- Monthly licenses use a **45-day offline lease window** by default.
+- Enterprise/government/compliance licenses support long/custom lease windows (for example 5-year, 10-year, or custom).
+- When a paid license is expired, requested paid modes are automatically downgraded to `eventual` until renewal.
+
+You can tune lease windows with environment variables:
+
+- `MUMPIX_LICENSE_MAX_DAYS_MONTHLY` (default `45`)
+- `MUMPIX_LICENSE_MAX_DAYS_ENTERPRISE` (default `36500`)
+- `MUMPIX_LICENSE_MAX_DAYS_GOVERNMENT` (default `36500`)
+- `MUMPIX_LICENSE_MAX_DAYS_COMPLIANCE` (default `36500`)
 
 ### Using a License Key
 
@@ -280,3 +359,33 @@ const db = await Mumpix.open('./agent.mumpix', {
 ```
 
 Get your key at [mumpixdb.com](https://mumpixdb.com).
+
+### No-Key account login (recommended)
+
+You can link your paid account once and let Mumpix load the local signed license automatically:
+
+```bash
+mumpix auth login            # device flow (browser-based)
+mumpix auth status
+```
+
+Advanced login options:
+
+```bash
+mumpix auth login --token=<account-token>      # backend token exchange
+mumpix auth login --license=<signed-license>   # direct import
+mumpix auth logout
+```
+
+For `--token` exchange, your backend should expose `/api/mumpix/auth/token/exchange` and map account tokens server-side (for example via `MUMPIX_AUTH_TOKEN_MAP`), not raw user IDs.
+
+By default, auth state is stored at `~/.config/mumpix/auth.json` (or `%APPDATA%/mumpix/auth.json` on Windows).
+
+### Install-time auth flow
+
+On `npm install mumpix`, the package runs an install-time auth prompt in interactive terminals:
+
+- Press **Enter**: browser opens for account auth and local signed license is stored.
+- Press any other key: install continues in `eventual` mode only.
+
+Non-interactive installs (CI/containers) skip this prompt automatically and default to `eventual`.

package/bin/mumpix.js

@@ -17,6 +17,15 @@
 const path   = require('path');
 const readline = require('readline');
 const { Mumpix } = require('../src/index');
+const {
+  loadAuthState,
+  clearAuthState,
+  upsertStoredLicense,
+  exchangeTokenForLicense,
+  loginWithDeviceFlow,
+  authStatePath,
+  configDir,
+} = require('../src/core/auth');
 
 const USAGE = `
 mumpix — SQLite for AI
@@ -33,6 +42,7 @@ Commands:
   stats    <file>                  Show database stats
   audit    <file>                  Show audit log (verified mode)
   shell    <file>                  Start interactive REPL
+  auth     <subcommand>            Account login/logout/status
   help                             Show this message
 
 Options (append to any command):
@@ -43,6 +53,9 @@ Examples:
   mumpix recall   ./agent.mumpix "what language?" --consistency=strict
   mumpix search   ./agent.mumpix "TypeScript" 3
   mumpix shell    ./agent.mumpix --consistency=verified
+  mumpix auth status
+  mumpix auth login --token=<account-token>
+  mumpix auth login --license=<signed-license-key>
 `.trim();
 
 function parseArgs(argv) {
@@ -77,15 +90,103 @@ const yellow = t => colorize(t, '33');
 const red    = t => colorize(t, '31');
 const bold   = t => colorize(t, '1');
 
+function fmtExpiry(ts) {
+  if (!ts) return '-';
+  const d = new Date(Number(ts));
+  if (Number.isNaN(d.getTime())) return '-';
+  return d.toISOString();
+}
+
+function mask(value, keep = 6) {
+  const s = String(value || '');
+  if (s.length <= keep) return s;
+  return `${s.slice(0, keep)}…`;
+}
+
+async function runAuth(parts, flags) {
+  const sub = String(parts[0] || 'status').toLowerCase();
+
+  if (sub === 'status') {
+    const s = loadAuthState();
+    if (!s || !s.license || !s.license.key) {
+      console.log(dim('Not logged in.'));
+      console.log(dim(`Config dir: ${configDir()}`));
+      return;
+    }
+    console.log(bold('Mumpix auth status'));
+    console.log(`  account_id: ${s.account && s.account.id ? s.account.id : '-'}`);
+    console.log(`  tier:       ${s.license.tier || (s.account && s.account.tier) || '-'}`);
+    console.log(`  issued_at:  ${fmtExpiry(s.license.iat)}`);
+    console.log(`  expires_at: ${fmtExpiry(s.license.exp)}`);
+    console.log(`  license:    ${green(mask(s.license.key, 18))}`);
+    console.log(`  state:      ${authStatePath()}`);
+    return;
+  }
+
+  if (sub === 'logout') {
+    clearAuthState();
+    console.log(green('✓') + ' Logged out. Local license removed.');
+    return;
+  }
+
+  if (sub === 'login') {
+    const directLicense = flags.license || flags['license-key'] || null;
+    if (directLicense) {
+      const state = upsertStoredLicense(String(directLicense));
+      console.log(green('✓') + ' License saved.');
+      console.log(`  tier:       ${state.license.tier || '-'}`);
+      console.log(`  expires_at: ${fmtExpiry(state.license.exp)}`);
+      console.log(`  state:      ${authStatePath()}`);
+      return;
+    }
+
+    const token = flags.token || process.env.MUMPIX_AUTH_TOKEN || '';
+    if (token) {
+      const state = await exchangeTokenForLicense(String(token).trim(), {});
+      console.log(green('✓') + ' Account linked and license saved.');
+      console.log(`  account_id: ${state.account.id || '-'}`);
+      console.log(`  tier:       ${state.license.tier || state.account.tier || '-'}`);
+      console.log(`  expires_at: ${fmtExpiry(state.license.exp)}`);
+      console.log(`  state:      ${authStatePath()}`);
+      return;
+    }
+
+    const state = await loginWithDeviceFlow({
+      onPrompt: ({ userCode, verifyUrl, expiresInSec, intervalSec }) => {
+        console.log(bold('Mumpix device login'));
+        console.log(`  1) Open: ${verifyUrl}`);
+        console.log(`  2) Enter code: ${cyan(userCode)}`);
+        console.log(`  3) Waiting for approval... (expires in ${expiresInSec}s, polling ${intervalSec}s)`);
+      }
+    });
+    console.log(green('✓') + ' Account linked and license saved.');
+    console.log(`  account_id: ${state.account.id || '-'}`);
+    console.log(`  tier:       ${state.license.tier || state.account.tier || '-'}`);
+    console.log(`  expires_at: ${fmtExpiry(state.license.exp)}`);
+    console.log(`  state:      ${authStatePath()}`);
+    return;
+  }
+
+  console.error(red(`Unknown auth subcommand: ${sub}`));
+  console.log('Usage: mumpix auth <status|login|logout> [--token=...] [--license=...]');
+  process.exit(1);
+}
+
 async function main() {
   const { args, flags } = parseArgs(process.argv.slice(2));
-  const [command, filePath, ...rest] = args;
+  const [command, arg1, ...rest] = args;
 
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     console.log(USAGE);
     process.exit(0);
   }
 
+  if (command === 'auth') {
+    await runAuth([arg1, ...rest], flags);
+    return;
+  }
+
+  const filePath = arg1;
   if (!filePath && command !== 'help') {
     console.error(red('Error: file path required'));
     console.log(USAGE);
@@ -96,7 +197,7 @@ async function main() {
   let db;
 
   try {
-    db = Mumpix.open(filePath, { consistency });
+    db = await Mumpix.open(filePath, { consistency });
   } catch (err) {
     console.error(red(`Error opening ${filePath}: ${err.message}`));
     process.exit(1);

package/examples/developer-sdk.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { MumpixDevClient } = require('../src');
+
+async function main() {
+  const client = new MumpixDevClient({
+    baseUrl: process.env.MUMPIX_BASE_URL || 'http://127.0.0.1:3012',
+  });
+
+  const health = await client.health();
+  console.log('health:', health);
+
+  await client.remember('Developer SDK smoke test memory');
+  const recalled = await client.recall('smoke test memory');
+  console.log('recalled:', recalled);
+
+  const stats = await client.stats();
+  console.log('stats.records:', stats.records);
+
+  const files = await client.files();
+  console.log('files:', (files.files || []).slice(0, 5));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+

package/examples/license-expiry-downgrade-check.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * examples/license-expiry-downgrade-check.js
+ *
+ * Verifies offline expiry behavior:
+ * - expired monthly license can still use eventual mode
+ * - strict mode is blocked for expired license
+ * - requested strict mode auto-downgrades to eventual at open()
+ *
+ * Run:
+ *   node examples/license-expiry-downgrade-check.js
+ */
+
+const os = require('os');
+const path = require('path');
+const { MumpixDB } = require('../src/core/MumpixDB');
+const { LicenseManager } = require('../src/core/license');
+
+async function main() {
+  const now = Date.now();
+  const lic = new LicenseManager();
+  lic.tier = 'monthly';
+  lic.verified = true;
+  lic.issuedAt = now - (50 * 24 * 60 * 60 * 1000);
+  lic.expiry = now - (60 * 1000);
+
+  // Expired monthly license: eventual should still be allowed.
+  lic.assertActive('eventual');
+
+  let strictBlocked = false;
+  try {
+    lic.assertActive('strict');
+  } catch (_) {
+    strictBlocked = true;
+  }
+  if (!strictBlocked) {
+    throw new Error('Expected strict mode to be blocked for expired monthly license');
+  }
+
+  // Requested strict should be downgraded to eventual at DB open.
+  const dbPath = path.join(
+    os.tmpdir(),
+    `mumpix-expiry-downgrade-check-${process.pid}-${Date.now()}.mpx`
+  );
+  const db = await MumpixDB.open(dbPath, {
+    consistency: 'strict',
+    licenseManager: lic
+  });
+
+  const okMode = db.consistency === 'eventual';
+  const okMeta = db._opts &&
+    db._opts.requestedConsistency === 'strict' &&
+    db._opts.downgradedConsistency &&
+    db._opts.downgradedConsistency.to === 'eventual';
+
+  await db.close();
+
+  if (!okMode || !okMeta) {
+    throw new Error(`Unexpected downgrade result: consistency=${db.consistency}`);
+  }
+
+  console.log('PASS license-expiry-downgrade-check');
+}
+
+main().catch((err) => {
+  console.error('FAIL license-expiry-downgrade-check:', err && err.message ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "mumpix",
-  "version": "1.0.6",
+  "version": "1.0.13",
   "description": "SQLite for AI — embedded, zero-config memory database for AI agents and LLM applications",
   "main": "src/index.js",
   "bin": {
-    "mumpix": "./bin/mumpix.js"
+    "mumpix": "bin/mumpix.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall-auth.js",
+    "verify:claims": "node ./scripts/verify-claims.cjs",
+    "release:publish-and-deprecate": "node ./scripts/publish-and-deprecate.cjs",
+    "release:clean": "bash ./scripts/release-clean.sh",
+    "release:pack": "npm run release:clean && npm pack --cache /tmp/mumpix-npm-cache"
   },
-  "scripts": {},
   "keywords": [
     "ai",
     "memory",
@@ -33,6 +39,7 @@
   "files": [
     "src/",
     "bin/",
+    "scripts/postinstall-auth.js",
     "examples/",
     "CHANGELOG.md",
     "README.md",

package/scripts/postinstall-auth.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+'use strict';
+
+const readline = require('readline');
+const { spawn } = require('child_process');
+const {
+  loginWithDeviceFlow,
+  exchangeTokenForLicense,
+  authStatePath,
+} = require('../src/core/auth');
+
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && process.env.CI !== 'true');
+}
+
+function fmtExpiry(ts) {
+  if (!ts) return '-';
+  const d = new Date(Number(ts));
+  if (Number.isNaN(d.getTime())) return '-';
+  return d.toISOString();
+}
+
+function openBrowser(url) {
+  if (!url) return false;
+  try {
+    if (process.platform === 'darwin') {
+      spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+      return true;
+    }
+    if (process.platform === 'win32') {
+      spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+      return true;
+    }
+    spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(String(answer || '').trim());
+    });
+  });
+}
+
+async function run() {
+  try {
+    if (String(process.env.MUMPIX_POSTINSTALL_AUTH || '1') === '0') return;
+
+    const token = String(process.env.MUMPIX_AUTH_TOKEN || '').trim();
+    if (token) {
+      const state = await exchangeTokenForLicense(token, {});
+      console.log(`[mumpix] account linked via token. tier=${state.license.tier || '-'} exp=${fmtExpiry(state.license.exp)}`);
+      return;
+    }
+
+    if (!isInteractive()) {
+      console.log('[mumpix] install complete. auth skipped (non-interactive).');
+      console.log('[mumpix] run "mumpix auth login" later to unlock strict/verified. default mode remains eventual.');
+      return;
+    }
+
+    console.log('\n[mumpix] authenticate to unlock your paid durability modes (strict/verified).');
+    const answer = await ask('[mumpix] press Enter to continue, or press any other key to install free (eventual mode): ');
+    if (answer.length > 0) {
+      console.log('[mumpix] auth skipped. default mode is eventual.');
+      return;
+    }
+
+    const state = await loginWithDeviceFlow({
+      onPrompt: ({ userCode, verifyUrl, expiresInSec, intervalSec }) => {
+        const opened = openBrowser(verifyUrl);
+        if (opened) {
+          console.log(`[mumpix] opened browser: ${verifyUrl}`);
+        } else {
+          console.log(`[mumpix] open this URL in your browser: ${verifyUrl}`);
+        }
+        console.log(`[mumpix] enter code: ${userCode}`);
+        console.log(`[mumpix] waiting for approval (expires in ${expiresInSec}s, polling ${intervalSec}s)...`);
+      }
+    });
+
+    console.log(`[mumpix] auth success. tier=${state.license.tier || state.account.tier || '-'} exp=${fmtExpiry(state.license.exp)}`);
+    console.log(`[mumpix] saved auth: ${authStatePath()}`);
+  } catch (err) {
+    const msg = err && err.message ? err.message : 'unknown error';
+    console.log(`[mumpix] auth step failed (${msg}).`);
+    if (String(msg).includes('404')) {
+      console.log('[mumpix] auth endpoints not found on this host. check MUMPIX_AUTH_BASE_URL or server auth routes.');
+    }
+    console.log('[mumpix] continuing install in eventual mode. run "mumpix auth login" later.');
+  }
+}
+
+run();