@hachazal/lvtn 3.10.0

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright © 2026 Chaz Leland Hamm (HaChazal) / Metanoia Unlimited LLC.
+All Rights Reserved.
+
+This software ("lvtn", the Leviathan Shel HaShem command-line client) is
+proprietary. It is a thin client that authenticates to and calls the
+Leviathan-of-HaShem cloud backend; it performs no model compute locally.
+
+Permission is granted to install and run this client solely to access the
+Leviathan-of-HaShem service using a valid Leviathan-of-HaShem API key, subject
+to the service's terms. No other rights are granted. You may not copy, modify,
+redistribute, sublicense, reverse-engineer, or create derivative works of this
+software without the prior written consent of Metanoia Unlimited LLC.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# lvtn — Leviathan Shel HaShem CLI
+
+**A Kabbalistic 708-agent swarm in your terminal.** Zero local compute — you hold a key, the cloud backend runs the swarm, you're metered in KTRS.
+
+Master orchestrator `hachazal` at Da'ath → 7 Angels (Zadkiel · Gavriel · Raphael · Uriel · Michael · Malika · Katan HaShem) × 100 agents each = 708.
+
+## Install — one line, universal
+
+```bash
+npm install -g lvtn
+# or run with zero install:
+npx lvtn
+```
+
+Aliases install the same binary — `lvtn`, `leviathantalon`, and `hachazal` all do the same thing. (`npm i -g leviathantalon`, `npm i -g hachazal`, and `npm i -g lvtn-sl-hshm` are thin wrappers that pull in `lvtn`.)
+
+Requires **Node 18+** (uses the built-in global `fetch`). No other dependencies.
+
+> Prefer Python? `pip install lvtn` ships the same commands plus a 6-frame sixel art TUI. Both share your key at `~/.lvtn/credentials.json`.
+
+## First run
+
+```bash
+lvtn signup     # open the portal → join the email list → get your key
+lvtn login      # paste your lvtn-hshm-... key (stored at ~/.lvtn/credentials.json)
+lvtn balance    # KTRS balance
+lvtn chat       # interactive cloud chat
+```
+
+## Commands
+
+| Area | Command |
+|---|---|
+| Account | `signup`, `login [--key …]`, `balance` |
+| Swarm | `chat`, `angels`, `swarm <angel> "task" [--agents N] [--tools]`, `council "task" [--angels a,b] [--per-angel N]`, `orchestrate "task"`, `fleet "task" [--per-angel N]` |
+| Skills | `skill search <q>`, `skill run <id> "input"`, `skill stats`, `skill domains` |
+| Integrations | `integrations list`, `integrations connect <svc> <token>`, `integrations action <svc> <action> --params '{…}'`, `integrations status`, `integrations disconnect <svc>` |
+| Memory | `remember "…" [--tag a,b]`, `recall "query" [--all] [--limit N]` |
+| Media | `video gen "prompt"`, `video extend --video-url …`, `video slingshot "prompt"`, `video jobs` |
+| Local files | `fs read\|write\|ls\|find\|grep\|mv\|cp\|rm\|extract\|zip\|reveal\|ask` (`rm` archives, never true-deletes) |
+
+`lvtn --version` · `lvtn help`.
+
+## Environment overrides
+
+| Var | Default |
+|---|---|
+| `LVTN_API_BASE` | `https://api.leviathansi.xyz` |
+| `LVTN_NODE_BASE` | `https://lvtn.metanoiaunlimited.com` (video extend/slingshot) |
+| `LVTN_PORTAL_URL` | `https://portal.leviathansi.xyz` (signup) |
+
+## Notes
+
+- This is a **thin client** — every swarm/LLM/skill call runs server-side and is KTRS-metered. The only local work is the `fs` tools.
+- The rich 6-frame sixel/braille art deck is in the Python build only; the npm `banner`/`deck` print a lightweight ANSI banner.
+
+Copyright © 2026 Chaz Leland Hamm / Metanoia Unlimited LLC. All Rights Reserved. Proprietary — see `LICENSE`.

package/bin/lvtn.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// lvtn — Leviathan of HaShem swarm CLI (npm). Universal one-line install:
+//   npm i -g lvtn   ·   npx lvtn
+// Aliases (same binary): leviathantalon · hachazal · lvtn-sl-hshm
+import { run } from '../src/cli.mjs'
+
+// Set exitCode and let the event loop drain — do NOT call process.exit().
+// On Windows, process.exit() right after an undici fetch races libuv's socket
+// teardown and trips `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`.
+// Letting the loop drain exits cleanly and promptly (undici unrefs idle sockets).
+// The unref'd safety timer only force-exits if some handle genuinely hangs the
+// loop past 30s; being unref'd it never delays a clean exit.
+function finish(code) {
+  process.exitCode = typeof code === 'number' ? code : 0
+  const guard = setTimeout(() => process.exit(process.exitCode), 30_000)
+  if (typeof guard.unref === 'function') guard.unref()
+}
+
+run(process.argv.slice(2))
+  .then(finish)
+  .catch((e) => { process.stderr.write(`\nlvtn error: ${e && e.stack ? e.stack : e}\n`); finish(1) })

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hachazal/lvtn",
+  "version": "3.10.0",
+  "description": "Leviathan Shel HaShem — a Kabbalistic 708-agent swarm in your terminal. Thin cloud client: login/balance/chat + angels/swarm/council/orchestrate/fleet, skills, integrations, video, HiveMind memory. KTRS-metered; the backend does all compute. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "lvtn": "bin/lvtn.mjs",
+    "leviathantalon": "bin/lvtn.mjs",
+    "hachazal": "bin/lvtn.mjs",
+    "lvtn-sl-hshm": "bin/lvtn.mjs"
+  },
+  "exports": {
+    ".": "./src/cli.mjs"
+  },
+  "main": "./src/cli.mjs",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lvtn": "node bin/lvtn.mjs"
+  },
+  "keywords": [
+    "leviathan",
+    "leviathantalon",
+    "lvtn",
+    "swarm",
+    "agent",
+    "orchestration",
+    "ai",
+    "cli",
+    "kabbalah",
+    "metanoia",
+    "hachazal",
+    "thin-client"
+  ],
+  "author": "HaChazal (Chaz Leland Hamm), Metanoia Unlimited LLC <hachazal418@metanoiaunlimited.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://leviathansi.xyz"
+}

package/src/api.mjs

@@ -0,0 +1,114 @@
+// lvtn (npm) — thin cloud client for the Leviathan-of-HaShem backend.
+//
+// Port of the Python `lvtn` CLI's cloud.py. ALL compute (the 708-agent swarm,
+// LLMs, metering) runs server-side — this client only stores the API key and
+// does HTTP. Zero runtime dependencies (Node 18+ global fetch). Mirrors the
+// exact endpoint contract + key-storage path so a key works across pip + npm.
+//
+// Backend base URL: $LVTN_API_BASE  or https://api.leviathansi.xyz
+// Node base URL:    $LVTN_NODE_BASE or https://lvtn.metanoiaunlimited.com
+// Key storage:      ~/.lvtn/credentials.json  (chmod 600, shared with pip CLI)
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const VERSION = '3.10.0'
+
+const DEFAULT_BASE = 'https://api.leviathansi.xyz'
+const DEFAULT_NODE_BASE = 'https://lvtn.metanoiaunlimited.com'
+const CONF_DIR = path.join(os.homedir(), '.lvtn')
+const CONF_FILE = path.join(CONF_DIR, 'credentials.json')
+
+export const PORTAL_URL = process.env.LVTN_PORTAL_URL || 'https://portal.leviathansi.xyz'
+
+// Cloudflare's Browser Integrity Check 403-bans bare/unknown User-Agents
+// (error 1010). A named UA passes. WITHOUT THIS the CLI cannot reach the
+// backend through Cloudflare. Verified 2026-05-29.
+export const USER_AGENT = `lvtn/${VERSION} (+https://leviathansi.xyz)`
+
+export function base() {
+  return (process.env.LVTN_API_BASE || DEFAULT_BASE).replace(/\/+$/, '')
+}
+export function nodeBase() {
+  return (process.env.LVTN_NODE_BASE || DEFAULT_NODE_BASE).replace(/\/+$/, '')
+}
+export { CONF_FILE }
+
+export function loadKey() {
+  try {
+    return JSON.parse(fs.readFileSync(CONF_FILE, 'utf-8')).api_key || null
+  } catch {
+    return null
+  }
+}
+
+export function saveKey(key) {
+  fs.mkdirSync(CONF_DIR, { recursive: true })
+  fs.writeFileSync(CONF_FILE, JSON.stringify({ api_key: key, base: base() }), 'utf-8')
+  try { fs.chmodSync(CONF_FILE, 0o600) } catch { /* no-op on Windows */ }
+}
+
+/**
+ * Call a backend. Returns { status, data } — status 0 means unreachable.
+ * @param {string} root - resolved base URL (base() or nodeBase())
+ */
+async function request(root, method, apiPath, { key = null, body = undefined, timeout = 120_000 } = {}) {
+  const headers = { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT }
+  if (key) headers['X-Leviathan-Key'] = key
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeout)
+  // Don't let the timeout handle hold the loop open or churn at exit. While a
+  // fetch is in flight the request itself keeps the loop alive, so an unref'd
+  // timer still fires on a genuinely hung request.
+  if (typeof timer.unref === 'function') timer.unref()
+  try {
+    const res = await fetch(`${root}${apiPath}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: ctrl.signal,
+    })
+    let data = {}
+    const text = await res.text()
+    if (text) { try { data = JSON.parse(text) } catch { data = { detail: text } } }
+    return { status: res.status, data }
+  } catch (e) {
+    const aborted = e && e.name === 'AbortError'
+    return {
+      status: 0,
+      data: { detail: aborted ? `timed out after ${timeout}ms` : `cannot reach ${root} (${e && e.message})` },
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Call the credits-orchestrator backend (api.leviathansi.xyz). */
+export function api(method, apiPath, opts = {}) {
+  return request(base(), method, apiPath, opts)
+}
+
+/** Call the NODE backend (lvtn.metanoiaunlimited.com) — video extend/slingshot. */
+export function nodeApi(method, apiPath, opts = {}) {
+  return request(nodeBase(), method, apiPath, opts)
+}
+
+/** Require a stored key or print the login hint and return null. */
+export function requireKey() {
+  const key = loadKey()
+  if (!key) process.stderr.write('Not logged in. Run:  lvtn login\n')
+  return key
+}
+
+export function openUrl(url) {
+  // Best-effort cross-platform browser open, no deps.
+  import('node:child_process').then(({ spawn }) => {
+    try {
+      const plt = process.platform
+      const cmd = plt === 'win32' ? 'cmd' : plt === 'darwin' ? 'open' : 'xdg-open'
+      const args = plt === 'win32' ? ['/c', 'start', '', url] : [url]
+      spawn(cmd, args, { stdio: 'ignore', detached: true, shell: false }).unref()
+    } catch { /* ignore */ }
+  }).catch(() => {})
+}

package/src/cli.mjs

@@ -0,0 +1,110 @@
+// lvtn (npm) — argv parser + command dispatcher. Zero deps.
+// Exported `run(argv)` is the single entry point used by every bin alias.
+
+import { VERSION } from './api.mjs'
+import * as cmd from './commands.mjs'
+
+// Tiny flag parser: collects --flag value / --flag=value / --bool, positionals → _.
+// Known value-flags consume the next token; everything else after `--` style is boolean.
+const VALUE_FLAGS = new Set([
+  'agents', 'angel', 'angels', 'per-angel', 'max-tokens', 'tier', 'domain', 'limit',
+  'agent', 'kind', 'tag', 'params', 'model', 'resolution', 'ratio', 'seconds', 'negative',
+  'video-url', 'target-seconds', 'segments', 'mode', 'provider', 'duration', 'key',
+])
+const BOOL_FLAGS = new Set(['tools', 'all'])
+
+function parse(tokens) {
+  const args = { _: [] }
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]
+    if (t.startsWith('--')) {
+      let name = t.slice(2)
+      let val
+      const eq = name.indexOf('=')
+      if (eq >= 0) { val = name.slice(eq + 1); name = name.slice(0, eq) }
+      const camel = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+      if (BOOL_FLAGS.has(name)) { args[camel] = true }
+      else if (VALUE_FLAGS.has(name)) { args[camel] = val !== undefined ? val : tokens[++i] }
+      else { args[camel] = val !== undefined ? val : true }
+    } else {
+      args._.push(t)
+    }
+  }
+  return args
+}
+
+function num(v, d) { const n = parseInt(v, 10); return Number.isFinite(n) ? n : d }
+
+function help() {
+  cmd.cmdBanner()
+  const lines = [
+    '  Account',
+    '    lvtn signup                         open the portal → join the list → get a key',
+    '    lvtn login [--key lvtn-hshm-...]     store + verify your key',
+    '    lvtn balance                         show KTRS balance',
+    '',
+    '  Talk to the swarm (cloud, KTRS-metered)',
+    '    lvtn chat                            interactive REPL',
+    '    lvtn angels                          list the 7 Angels',
+    '    lvtn swarm <angel> "task" [--agents N] [--tools]',
+    '    lvtn council "task" [--angels a,b] [--per-angel N]',
+    '    lvtn orchestrate "task" [--max-tokens N]   HaChazal plans→dispatches→synthesizes',
+    '    lvtn fleet "task" [--per-angel N]    all 7 Angels × tool-agents',
+    '',
+    '  Skills · Integrations · Memory',
+    '    lvtn skill search|run|stats|domains',
+    '    lvtn integrations list|status|connect|action|disconnect',
+    '    lvtn remember "..." [--tag a,b]   ·   lvtn recall "query" [--all]',
+    '',
+    '  Media · Local files',
+    '    lvtn video gen|extend|slingshot|jobs',
+    '    lvtn fs read|write|ls|find|grep|mv|cp|rm|extract|zip|reveal|ask',
+    '',
+    '  lvtn --version    ·    aliases: leviathantalon · hachazal · lvtn-sl-hshm',
+    '  Env: LVTN_API_BASE · LVTN_NODE_BASE · LVTN_PORTAL_URL',
+    '',
+  ]
+  lines.forEach((l) => process.stdout.write(l + '\n'))
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const sub = argv[0]
+  if (!sub || sub === '-h' || sub === '--help' || sub === 'help') { help(); return 0 }
+  if (sub === '-v' || sub === '--version' || sub === 'version') { process.stdout.write(`lvtn ${VERSION}\n`); return 0 }
+
+  const a = parse(argv.slice(1))
+
+  switch (sub) {
+    case 'banner': cmd.cmdBanner(); return 0
+    case 'deck': case 'art':
+      cmd.cmdBanner()
+      process.stdout.write('  (the full 6-frame sixel art deck ships with the Python build: pip install lvtn)\n\n')
+      return 0
+    case 'signup': return cmd.cmdSignup()
+    case 'login': return cmd.cmdLogin(a)
+    case 'balance': return cmd.cmdBalance()
+    case 'me': return cmd.cmdBalance()
+    case 'chat': return cmd.cmdChat()
+    case 'vibe': // `lvtn vibe code` or `lvtn vibe`
+    case 'code': return cmd.cmdChat()
+    case 'angels': return cmd.cmdAngels()
+    case 'swarm': { a.agents = num(a.agents, 3); return cmd.cmdSwarm(a) }
+    case 'council': { a.perAngel = num(a.perAngel, 2); return cmd.cmdCouncil(a) }
+    case 'orchestrate': { if (a.maxTokens) a.maxTokens = num(a.maxTokens); return cmd.cmdOrchestrate(a) }
+    case 'fleet': { a.perAngel = num(a.perAngel, 2); return cmd.cmdFleet(a) }
+    case 'remember': { a.agent = a.agent || 'hachazal'; a.kind = a.kind || 'observation'; return cmd.cmdRemember(a) }
+    case 'recall': { a.agent = a.agent || 'hachazal'; a.limit = num(a.limit, 10); return cmd.cmdRecall(a) }
+    case 'skill': case 'skills': { a.limit = num(a.limit, 20); return cmd.cmdSkill(a) }
+    case 'integrations': case 'integration': return cmd.cmdIntegrations(a)
+    case 'video': {
+      a.targetSeconds = num(a.targetSeconds, 30)
+      if (a.segments != null) a.segments = num(a.segments, undefined)
+      if (a.duration != null) a.duration = num(a.duration, undefined)
+      return cmd.cmdVideo(a)
+    }
+    case 'fs': return cmd.cmdFs(a)
+    default:
+      process.stderr.write(`Unknown command: ${sub}\nRun \`lvtn help\` for usage.\n`)
+      return 1
+  }
+}

package/src/commands.mjs

@@ -0,0 +1,578 @@
+// lvtn (npm) — command handlers. Each returns a process exit code (0 = ok).
+// Port of the Python CLI's cloud.py + local_tools.py command surface.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline'
+import { spawnSync } from 'node:child_process'
+import {
+  api, nodeApi, loadKey, saveKey, requireKey, openUrl,
+  PORTAL_URL, CONF_FILE, base, VERSION,
+} from './api.mjs'
+
+const out = (s = '') => process.stdout.write(s + '\n')
+const err = (s = '') => process.stderr.write(s + '\n')
+
+function ask(question, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    if (hidden) {
+      const stdout = process.stdout
+      rl._writeToOutput = function (str) { if (str.includes(question)) stdout.write(str); else stdout.write('') }
+    }
+    rl.question(question, (answer) => { rl.close(); resolve((answer || '').trim()) })
+  })
+}
+
+function openSignup(reason = '') {
+  if (reason) out(reason)
+  out(`  Opening ${PORTAL_URL} — sign up with your email to join the Leviathan`)
+  out('  email list and get your Leviathan-of-HaShem key.')
+  openUrl(PORTAL_URL)
+}
+
+// ── auth / account ───────────────────────────────────────────────────────────
+export async function cmdSignup() {
+  openSignup()
+  out('  After you get your key, run:  lvtn login')
+  return 0
+}
+
+export async function cmdLogin(args) {
+  let key = args.key || null
+  if (!key) {
+    if (!loadKey()) openSignup('  No key found.')
+    key = await ask('Paste your Leviathan-of-HaShem key (lvtn-hshm-...): ', { hidden: true })
+  }
+  if (!key) { err('No key entered.'); return 1 }
+  const { status, data } = await api('GET', '/api/llm/me', { key, timeout: 30_000 })
+  if (status === 200) {
+    saveKey(key)
+    out(`  Logged in as ${data.email}`)
+    out(`  KTRS balance: $${data.balance_usd}`)
+    out(`  Key stored at ${CONF_FILE}`)
+    return 0
+  }
+  if (status === 401 || status === 403) err('  Key rejected — check it and try again.')
+  else if (status === 0) err(`  ${data.detail}`)
+  else err(`  Login failed (HTTP ${status}): ${data.detail}`)
+  return 1
+}
+
+export async function cmdBalance() {
+  const key = loadKey()
+  if (!key) { err('Not logged in. Run:  lvtn login'); return 1 }
+  const { status, data } = await api('GET', '/api/llm/me', { key, timeout: 30_000 })
+  if (status === 200) { out(`  ${data.email}  —  $${data.balance_usd} KTRS`); return 0 }
+  if (status === 401 || status === 403) err('  Key rejected — run:  lvtn login')
+  else err(`  Could not fetch balance (HTTP ${status}): ${data.detail}`)
+  return 1
+}
+
+// ── chat REPL ────────────────────────────────────────────────────────────────
+export async function cmdChat() {
+  const key = loadKey()
+  if (!key) { err('Not logged in. Run:  lvtn login'); return 1 }
+  out('  Leviathan of HaShem — cloud chat (backend swarm, KTRS-metered).')
+  out("  Type your message. Ctrl-C or 'exit' to quit.\n")
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const history = []
+  return await new Promise((resolve) => {
+    const prompt = () => rl.question('you> ', async (line) => {
+      line = (line || '').trim()
+      if (!line) return prompt()
+      if (['exit', 'quit', ':q'].includes(line.toLowerCase())) { rl.close(); return resolve(0) }
+      history.push({ role: 'user', content: line })
+      const { status, data } = await api('POST', '/api/llm/chat', { key, body: { messages: history } })
+      if (status === 200) {
+        const reply = data.text || ''
+        history.push({ role: 'assistant', content: reply })
+        out(`\nleviathan> ${reply}\n`)
+        if (data.balance_usd != null) out(`  [${data.provider} · $${data.balance_usd} KTRS left]\n`)
+      } else if (status === 402) {
+        err('\n  Out of KTRS credits — your balance refills automatically. Try again later.\n')
+        history.pop()
+      } else if (status === 401 || status === 403) {
+        err('\n  Key rejected — run:  lvtn login\n'); rl.close(); return resolve(1)
+      } else {
+        err(`\n  Error (HTTP ${status}): ${data.detail}\n`); history.pop()
+      }
+      prompt()
+    })
+    rl.on('SIGINT', () => { out(''); rl.close(); resolve(0) })
+    prompt()
+  })
+}
+
+// ── angels / swarm / council / orchestrate / fleet ───────────────────────────
+export async function cmdAngels() {
+  const { status, data } = await api('GET', '/api/llm/angels', { timeout: 30_000 })
+  if (status !== 200) { err(`  Could not fetch roster (HTTP ${status}): ${data.detail}`); return 1 }
+  const angels = data.angels || []
+  const cap = angels[0]?.swarm_capacity ?? 100
+  out(`\n  The Council — ${angels.length} Angels, each commands a ${cap}-agent swarm:\n`)
+  for (const a of angels) {
+    out(`    ${String(a.id).padEnd(14)} ${String(a.name).padEnd(14)} ${String(a.sefirah).padEnd(11)} — ${a.title}`)
+    out(`    ${''.padEnd(14)} ${a.blurb}  [${a.swarm_tier}]\n`)
+  }
+  out('  Deploy one:   lvtn swarm <id> "your task" --agents 5')
+  out('  Convene all:  lvtn council "your task" --per-angel 2\n')
+  return 0
+}
+
+export async function cmdSwarm(args) {
+  const key = requireKey(); if (!key) return 1
+  const prompt = (args._.join(' ')).trim()
+  if (!args.angel) { err('Usage: lvtn swarm <angel> "task" --agents N'); return 1 }
+  if (!prompt) { err('Give the Angel a task:  lvtn swarm uriel "scan Solana for launches"'); return 1 }
+  out(`  Deploying ${args.angel}'s swarm — ${args.agents} parallel cloud agents…`)
+  const { status, data } = await api('POST', '/api/llm/swarm', {
+    key, body: { angel: args.angel, prompt, agents: args.agents, tools: !!args.tools },
+  })
+  if (status === 402) { err('  Out of KTRS credits — balance refills automatically. Try later.'); return 1 }
+  if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+  if (status !== 200) { err(`  Swarm failed (HTTP ${status}): ${data.detail}`); return 1 }
+  const outputs = data.outputs || data.agents || []
+  out(`\n  ${args.angel} · ${outputs.length} agents:\n`)
+  outputs.forEach((o, i) => { out(`  ── agent ${i + 1} ──`); out(`  ${(o.text || o.content || '').trim()}\n`) })
+  out(`  [charged $${data.charged_usd} · $${data.balance_usd} KTRS left]\n`)
+  return 0
+}
+
+export async function cmdCouncil(args) {
+  const key = requireKey(); if (!key) return 1
+  const prompt = (args._.join(' ')).trim()
+  if (!prompt) { err('Give the Council a task:  lvtn council "design a launch plan" --per-angel 2'); return 1 }
+  const body = { prompt, agents_per_angel: args.perAngel }
+  if (args.angels) body.angels = args.angels.split(',').map((s) => s.trim()).filter(Boolean)
+  out('  Convening the Council — Angels answering in parallel…')
+  const { status, data } = await api('POST', '/api/llm/council', { key, body, timeout: 240_000 })
+  if (status === 402) { err('  Out of KTRS credits — balance refills automatically. Try later.'); return 1 }
+  if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+  if (status !== 200) { err(`  Council failed (HTTP ${status}): ${data.detail}`); return 1 }
+  const council = data.council || data.outputs || []
+  out(`\n  Council — ${council.length} replies:\n`)
+  for (const c of council) {
+    out(`  ◆ ${c.angel || c.id || '?'}`)
+    out(`  ${(c.text || c.content || '').trim()}\n`)
+  }
+  out(`  [charged $${data.charged_usd} · $${data.balance_usd} KTRS left]\n`)
+  return 0
+}
+
+export async function cmdOrchestrate(args) {
+  const key = requireKey(); if (!key) return 1
+  const prompt = (args._.join(' ')).trim()
+  if (!prompt) { err('Give HaChazal a task to orchestrate:  lvtn orchestrate "plan and launch a product"'); return 1 }
+  const body = { messages: [{ role: 'user', content: prompt }] }
+  if (args.maxTokens) body.max_tokens = args.maxTokens
+  out('  HaChazal is orchestrating — planning, dispatching the Angels, synthesizing…')
+  const { status, data } = await api('POST', '/api/llm/orchestrate', { key, body, timeout: 240_000 })
+  if (status === 402) { err('  Out of KTRS credits — balance refills automatically. Try later.'); return 1 }
+  if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+  if (status !== 200) { err(`  Orchestrate failed (HTTP ${status}): ${data.detail}`); return 1 }
+  out(`\n${(data.text || '').trim()}\n`)
+  if (data.balance_usd != null) out(`  [charged $${data.charged_usd ?? 0} · $${data.balance_usd} KTRS left]\n`)
+  return 0
+}
+
+export async function cmdFleet(args) {
+  const key = requireKey(); if (!key) return 1
+  const prompt = (args._.join(' ')).trim()
+  if (!prompt) { err('Give the fleet a task:  lvtn fleet "audit my repo" --per-angel 2'); return 1 }
+  out('  Deploying the full fleet — all 7 Angels × NanoClaw tool-agents…')
+  const { status, data } = await api('POST', '/api/llm/fleet', { key, body: { prompt, per_angel: args.perAngel }, timeout: 240_000 })
+  if (status === 402) { err('  Out of KTRS credits — balance refills automatically. Try later.'); return 1 }
+  if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+  if (status !== 200) { err(`  Fleet failed (HTTP ${status}): ${data.detail}`); return 1 }
+  const council = data.council || data.outputs || []
+  out(`\n  Fleet — ${council.length} Angel replies:\n`)
+  for (const c of council) { out(`  ◆ ${c.angel || c.id || '?'}`); out(`  ${(c.text || c.content || '').trim()}\n`) }
+  out(`  [charged $${data.charged_usd} · $${data.balance_usd} KTRS left]\n`)
+  return 0
+}
+
+// ── memory (HiveMind) ────────────────────────────────────────────────────────
+export async function cmdRemember(args) {
+  const key = requireKey(); if (!key) return 1
+  const body = (args._.join(' ')).trim()
+  if (!body) { err('Give it something to remember:  lvtn remember "we chose X because Y"'); return 1 }
+  const payload = { body, agent: args.agent, kind: args.kind }
+  if (args.tag) payload.tags = args.tag.split(',').map((t) => t.trim()).filter(Boolean)
+  const { status, data } = await api('POST', '/api/llm/memory/remember', { key, body: payload })
+  if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+  if (status !== 200) { err(`  Remember failed (HTTP ${status}): ${data.detail}`); return 1 }
+  out(`  remembered as ${data.agent} · ${data.kind} · ${data.ts}`)
+  return 0
+}
+
+export async function cmdRecall(args) {
+  const key = requireKey(); if (!key) return 1
+  const q = (args._.join(' ')).trim()
+  const path_ = `/api/llm/memory/recall?query=${encodeURIComponent(q)}&agent=${encodeURIComponent(args.agent)}`
+    + `&limit=${parseInt(args.limit, 10)}&all_agents=${args.all ? 'true' : 'false'}`
+  const { status, data } = await api('GET', path_, { key })
+  if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+  if (status !== 200) { err(`  Recall failed (HTTP ${status}): ${data.detail}`); return 1 }
+  const mems = data.memories || []
+  if (!mems.length) { out('  (no memories match)'); return 0 }
+  out(`\n  ${data.count} memory(ies):\n`)
+  for (const m of mems) {
+    out(`  ◆ ${m.ts} · ${m.agent} · ${m.kind}  tags=${JSON.stringify(m.tags)}`)
+    out(`    ${(m.body || '').trim()}\n`)
+  }
+  return 0
+}
+
+// ── skills ───────────────────────────────────────────────────────────────────
+export async function cmdSkill(args) {
+  const sub = args._.shift()
+  if (sub === 'search') {
+    const query = args._.join(' ').trim()
+    const params = new URLSearchParams({ limit: String(args.limit || 20) })
+    if (query) params.set('q', query)
+    if (args.tier) params.set('tier', args.tier)
+    if (args.domain) params.set('domain', args.domain)
+    const { status, data } = await api('GET', `/api/llm/skills/search?${params}`, { timeout: 30_000 })
+    if (status !== 200) { err(`  Search failed (HTTP ${status}): ${data.detail}`); return 1 }
+    const results = data.results || []
+    const total = data.total_in_catalog ?? data.total ?? '?'
+    out(`\n  ${results.length} results (catalog: ${total} skills)\n`)
+    for (const s of results) {
+      const desc = (s.description || '').slice(0, 72)
+      out(`  [${String(s.tier || '?').padEnd(8)}] ${String(s.id).padEnd(42)} ${s.domain || ''}`)
+      if (desc && desc !== s.id) out(`  ${''.padStart(10)}  ${desc}`)
+    }
+    if (results.length) out(`\n  Run one:  lvtn skill run ${results[0].id} "your input here"`)
+    out('')
+    return 0
+  }
+  if (sub === 'run') {
+    const key = requireKey(); if (!key) return 1
+    const skillId = (args._.shift() || '').trim()
+    let prompt = args._.join(' ').trim()
+    if (!skillId) { err('Usage: lvtn skill run <skill_id> "your input"'); return 1 }
+    if (!prompt) prompt = await ask(`  Input for skill '${skillId}': `)
+    const body = { skill_id: skillId, input: prompt }
+    if (args.angel) body.angel = args.angel
+    out(`  Running skill: ${skillId}…`)
+    const { status, data } = await api('POST', '/api/llm/skills/execute', { key, body, timeout: 120_000 })
+    if (status === 402) { err('  Out of KTRS — balance refills automatically.'); return 1 }
+    if (status === 404) { err(`  Skill '${skillId}' not found. Try: lvtn skill search <topic>`); return 1 }
+    if (status === 401 || status === 403) { err('  Key rejected — run: lvtn login'); return 1 }
+    if (status !== 200) { err(`  Execute failed (HTTP ${status}): ${data.detail}`); return 1 }
+    out(`\n  [${data.skill_name || skillId}]\n`)
+    out(`  ${(data.text || '').trim()}\n`)
+    if (data.balance_usd != null) out(`  [${data.provider} · $${data.balance_usd} KTRS left]\n`)
+    return 0
+  }
+  if (sub === 'stats') {
+    const { status, data } = await api('GET', '/api/llm/skills/stats', { timeout: 30_000 })
+    if (status !== 200) { err(`  Stats failed (HTTP ${status}): ${data.detail}`); return 1 }
+    out(`\n  ${JSON.stringify(data, null, 2)}\n`); return 0
+  }
+  if (sub === 'domains') {
+    const { status, data } = await api('GET', '/api/llm/skills/domains', { timeout: 30_000 })
+    if (status !== 200) { err(`  Domains failed (HTTP ${status}): ${data.detail}`); return 1 }
+    const domains = data.domains || data || []
+    out(`\n  ${domains.length} domains:\n`)
+    out('  ' + domains.join('\n  ') + '\n'); return 0
+  }
+  out('  lvtn skill search <query>         search the catalog')
+  out('  lvtn skill run <id> "your input"  execute a skill via LLM')
+  out('  lvtn skill stats                   show counts by tier')
+  out('  lvtn skill domains                 list all domains')
+  return sub ? 1 : 0
+}
+
+// ── integrations ─────────────────────────────────────────────────────────────
+export async function cmdIntegrations(args) {
+  const sub = args._.shift() || 'list'
+  if (sub === 'list') {
+    const { status, data } = await api('GET', '/api/integrations/services', { timeout: 30_000 })
+    if (status !== 200) { err(`  Could not list services (HTTP ${status}): ${data.detail}`); return 1 }
+    const services = data.services || []
+    const filter = (args._.join(' ') || '').toLowerCase()
+    const shown = filter ? services.filter((s) => JSON.stringify(s).toLowerCase().includes(filter)) : services
+    out(`\n  ${shown.length}${filter ? `/${services.length}` : ''} integrations:\n`)
+    for (const s of shown) {
+      out(`  ${String(s.id || s.service).padEnd(22)} ${s.category || ''}  ${s.token_format ? `token: ${s.token_format}` : ''}`)
+    }
+    out(`\n  Connect:  lvtn integrations connect <service> <token>`)
+    out(`  Run:      lvtn integrations action <service> <action> --params '{"k":"v"}'\n`)
+    return 0
+  }
+  if (sub === 'status') {
+    const key = requireKey(); if (!key) return 1
+    const { status, data } = await api('GET', '/api/integrations/status', { key, timeout: 30_000 })
+    if (status !== 200) { err(`  Status failed (HTTP ${status}): ${data.detail}`); return 1 }
+    out(`\n  ${JSON.stringify(data, null, 2)}\n`); return 0
+  }
+  if (sub === 'connect') {
+    const key = requireKey(); if (!key) return 1
+    const service = (args._.shift() || '').trim()
+    const token = (args._.shift() || '').trim()
+    if (!service || !token) {
+      err('Usage: lvtn integrations connect <service> <token>')
+      err('  Run `lvtn integrations list` to see token formats.'); return 1
+    }
+    out(`  Testing credentials for ${service}…`)
+    const { status, data } = await api('POST', '/api/integrations/connect', { key, body: { service, token }, timeout: 60_000 })
+    if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+    if (status === 400) { err(`  ${data.detail || 'bad request'}`); return 1 }
+    if (status !== 200) { err(`  Connect failed (HTTP ${status}): ${data.detail}`); return 1 }
+    if (!data.ok) { err(`  ✗ Connection test failed: ${data.error || 'unknown'}`); return 1 }
+    const info = Object.entries(data).filter(([k]) => !['ok', 'service', 'connected'].includes(k))
+    out(`  ✓ ${service} connected${info.length ? '  ' + info.map(([k, v]) => `${k}=${v}`).join('  ') : ''}`)
+    return 0
+  }
+  if (sub === 'action') {
+    const key = requireKey(); if (!key) return 1
+    const service = (args._.shift() || '').trim()
+    const action = (args._.shift() || '').trim()
+    if (!service || !action) { err("Usage: lvtn integrations action <service> <action> [--params '{\"to\":\"x@y.com\"}']"); return 1 }
+    let params = {}
+    if (args.params) { try { params = JSON.parse(args.params) } catch { err(`  --params must be valid JSON, got: ${args.params}`); return 1 } }
+    const { status, data } = await api('POST', '/api/integrations/action', { key, body: { service, action, params }, timeout: 60_000 })
+    if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+    if (status === 402) { err('  Out of KTRS — balance refills automatically. Try later.'); return 1 }
+    if (status === 424) { err(`  ${data.detail || 'service not connected'}  →  connect it first: lvtn integrations connect ${service} <token>`); return 1 }
+    if (status !== 200) { err(`  Action failed (HTTP ${status}): ${data.detail}`); return 1 }
+    out(JSON.stringify(data, null, 2)); return 0
+  }
+  if (sub === 'disconnect') {
+    const key = requireKey(); if (!key) return 1
+    const service = (args._.shift() || '').trim()
+    if (!service) { err('Usage: lvtn integrations disconnect <service>'); return 1 }
+    const { status, data } = await api('DELETE', `/api/integrations/${service}`, { key, timeout: 30_000 })
+    if (status !== 200) { err(`  Disconnect failed (HTTP ${status}): ${data.detail}`); return 1 }
+    out(`  ✓ ${service} disconnected`); return 0
+  }
+  err(`  Unknown integrations subcommand: ${sub}`)
+  return 1
+}
+
+// ── video ────────────────────────────────────────────────────────────────────
+async function pollVideo(getStatus, { tries = 60, every = 10_000, label = 'status' } = {}) {
+  for (let i = 0; i < tries; i++) {
+    await new Promise((r) => setTimeout(r, every))
+    const { status, data } = await getStatus()
+    if (status !== 200) { out(`  [${String(i + 1).padStart(2, '0')}] poll error (HTTP ${status}) — retrying`); continue }
+    const st = data.status || ''
+    out(`  [${String(i + 1).padStart(2, '0')}] ${label}=${st}${data.provider ? ` via ${data.provider}` : ''}`)
+    if (['completed', 'done', 'complete', 'delivered'].includes(st)) {
+      const url = data.video_url || data.output_url || data.url || data.delivery_path
+      out(`\n  ✓ Done!  ${url || '(no url returned)'}\n`); return 0
+    }
+    if (['error', 'failed', 'cancelled'].includes(st)) { err(`  ✗ Job ${st}: ${data.error}`); return 1 }
+  }
+  err('  Timed out waiting for video.'); return 1
+}
+
+export async function cmdVideo(args) {
+  const sub = args._.shift() || 'gen'
+  const key = requireKey(); if (!key) return 1
+
+  if (sub === 'gen' || sub === 'generate') {
+    const prompt = args._.join(' ').trim()
+    if (!prompt) { err('Usage: lvtn video gen "a dragon over the sea" [--model X --resolution 720p --ratio 16:9 --seconds 5]'); return 1 }
+    const body = {
+      prompt,
+      model: args.model || 'Wan-AI/wan2.7-t2v',
+      resolution: args.resolution || '720p',
+      ratio: args.ratio || '16:9',
+      seconds: String(args.seconds || 5),
+    }
+    if (args.negative) body.negative_prompt = args.negative
+    out(`  Generating video: ${prompt.slice(0, 72)}${prompt.length > 72 ? '…' : ''}`)
+    const { status, data } = await api('POST', '/api/llm/media/video', { key, body, timeout: 60_000 })
+    if (status === 402) { err('  Out of KTRS credits — balance refills automatically. Try later.'); return 1 }
+    if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+    if (status === 503) { err(`  ${data.detail || 'video backend not configured'}`); return 1 }
+    if (status !== 200) { err(`  Video submission failed (HTTP ${status}): ${data.detail}`); return 1 }
+    out(`  Job ID: ${data.job_id}  (charged $${data.charged_usd ?? 0} · $${data.balance_usd} KTRS left)`)
+    out('  Polling for completion (Wan2.x takes ~40 s) …')
+    return pollVideo(() => api('GET', `/api/llm/media/video/${data.job_id}`, { key, timeout: 30_000 }))
+  }
+
+  if (sub === 'extend') {
+    const videoUrl = (args.videoUrl || '').trim()
+    if (!videoUrl) { err('Usage: lvtn video extend --video-url https://... --target-seconds 30'); return 1 }
+    const body = { video_url: videoUrl, target_seconds: args.targetSeconds || 30 }
+    if (args.segments != null) body.segments = args.segments
+    out(`  Extending video to ~${body.target_seconds}s`)
+    const { status, data } = await nodeApi('POST', '/api/video/extend', { key, body, timeout: 60_000 })
+    if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+    if (![200, 201, 202].includes(status)) { err(`  Extend submit failed (HTTP ${status}): ${data.detail || JSON.stringify(data)}`); return 1 }
+    const jobId = data.jobId || data.job_id || data.id
+    if (!jobId) { out(`  Job submitted but no job ID returned: ${JSON.stringify(data)}`); return 0 }
+    out(`  Job ID: ${jobId}  — polling…`)
+    return pollVideo(() => nodeApi('GET', `/api/video/extend/status/${jobId}`, { key, timeout: 30_000 }), { tries: 120 })
+  }
+
+  if (sub === 'slingshot') {
+    const prompt = args._.join(' ').trim()
+    if (!prompt) { err('Usage: lvtn video slingshot "prompt" [--mode text_to_video --provider X --duration 5]'); return 1 }
+    const body = { prompt, mode: args.mode || 'text_to_video' }
+    const options = {}
+    if (args.provider) options.provider = args.provider
+    if (args.duration) options.duration_seconds = args.duration
+    if (Object.keys(options).length) body.options = options
+    out(`  Slingshot: ${prompt.slice(0, 72)}${prompt.length > 72 ? '…' : ''}  mode=${body.mode}`)
+    const { status, data } = await nodeApi('POST', '/api/video/slingshot/submit', { key, body, timeout: 60_000 })
+    if (status === 401 || status === 403) { err('  Key rejected — run:  lvtn login'); return 1 }
+    if (![200, 201, 202].includes(status)) { err(`  Slingshot submit failed (HTTP ${status}): ${data.detail || JSON.stringify(data)}`); return 1 }
+    const jobId = data.jobId || data.job_id || data.id
+    if (!jobId) { out(`  Job submitted but no job ID returned: ${JSON.stringify(data)}`); return 0 }
+    out(`  Job ID: ${jobId}  — polling…`)
+    return pollVideo(() => nodeApi('GET', `/api/video/slingshot/status/${jobId}`, { key, timeout: 30_000 }), { tries: 120 })
+  }
+
+  if (sub === 'jobs' || sub === 'extensions') {
+    const e = await nodeApi('GET', '/api/video/extend/jobs', { key, timeout: 30_000 })
+    const s = await nodeApi('GET', '/api/video/slingshot/jobs', { key, timeout: 30_000 })
+    out('\n  Extend jobs:'); out('  ' + JSON.stringify(e.data))
+    out('\n  Slingshot jobs:'); out('  ' + JSON.stringify(s.data) + '\n')
+    return 0
+  }
+
+  err(`  Unknown video subcommand: ${sub}  (gen | extend | slingshot | jobs)`)
+  return 1
+}
+
+// ── local filesystem tools (no backend) ──────────────────────────────────────
+const ARCHIVE_DIR = path.join(os.homedir(), '.lvtn-archive')
+
+export async function cmdFs(args) {
+  const sub = args._.shift()
+  const p = (i = 0) => args._[i]
+  switch (sub) {
+    case 'read': {
+      const f = p(0); if (!f) { err('Usage: lvtn fs read <file>'); return 1 }
+      try {
+        const st = fs.statSync(f)
+        if (st.size > 16 * 1024 * 1024) { err('  File >16MB — refusing to print.'); return 1 }
+        process.stdout.write(fs.readFileSync(f, 'utf-8')); return 0
+      } catch (e) { err(`  ${e.message}`); return 1 }
+    }
+    case 'write': {
+      const f = p(0); if (!f) { err('Usage: echo "body" | lvtn fs write <file>'); return 1 }
+      const body = await readStdin()
+      try {
+        if (fs.existsSync(f)) {
+          fs.mkdirSync(ARCHIVE_DIR, { recursive: true })
+          fs.copyFileSync(f, path.join(ARCHIVE_DIR, `${path.basename(f)}.${Date.now()}`))
+        }
+        fs.mkdirSync(path.dirname(path.resolve(f)), { recursive: true })
+        fs.writeFileSync(f, body, 'utf-8'); out(`  wrote ${f} (${body.length} bytes)`); return 0
+      } catch (e) { err(`  ${e.message}`); return 1 }
+    }
+    case 'ls': {
+      const d = p(0) || '.'
+      try {
+        for (const name of fs.readdirSync(d)) {
+          const st = fs.statSync(path.join(d, name))
+          out(`  ${st.isDirectory() ? 'd' : '-'} ${String(st.size).padStart(10)}  ${name}`)
+        }
+        return 0
+      } catch (e) { err(`  ${e.message}`); return 1 }
+    }
+    case 'find': {
+      const pattern = p(0) || '*'; const root = p(1) || '.'
+      const re = new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$')
+      walk(root, (fp, name) => { if (re.test(name)) out('  ' + fp) }); return 0
+    }
+    case 'grep': {
+      const needle = p(0); const root = p(1) || '.'
+      if (!needle) { err('Usage: lvtn fs grep <text> [root]'); return 1 }
+      walk(root, (fp) => {
+        try {
+          const lines = fs.readFileSync(fp, 'utf-8').split('\n')
+          lines.forEach((ln, i) => { if (ln.includes(needle)) out(`  ${fp}:${i + 1}: ${ln.trim().slice(0, 120)}`) })
+        } catch { /* binary/unreadable */ }
+      }); return 0
+    }
+    case 'mv': { try { fs.renameSync(p(0), p(1)); out(`  moved ${p(0)} -> ${p(1)}`); return 0 } catch (e) { err(`  ${e.message}`); return 1 } }
+    case 'cp': { try { fs.cpSync(p(0), p(1), { recursive: true }); out(`  copied ${p(0)} -> ${p(1)}`); return 0 } catch (e) { err(`  ${e.message}`); return 1 } }
+    case 'rm': {
+      const f = p(0); if (!f) { err('Usage: lvtn fs rm <path>  (archives — never true-deletes)'); return 1 }
+      try {
+        fs.mkdirSync(ARCHIVE_DIR, { recursive: true })
+        const dest = path.join(ARCHIVE_DIR, `${path.basename(f)}.${Date.now()}`)
+        fs.cpSync(f, dest, { recursive: true }); fs.rmSync(f, { recursive: true, force: true })
+        out(`  archived to ${dest} (restorable)`); return 0
+      } catch (e) { err(`  ${e.message}`); return 1 }
+    }
+    case 'reveal': {
+      const f = p(0) || '.'
+      const plt = process.platform
+      const cmd = plt === 'win32' ? 'explorer' : plt === 'darwin' ? 'open' : 'xdg-open'
+      spawnSync(cmd, [path.resolve(f)], { stdio: 'ignore' }); out(`  opened ${f}`); return 0
+    }
+    case 'extract': {
+      const f = p(0); const dest = p(1) || '.'
+      if (!f) { err('Usage: lvtn fs extract <archive> [dest]'); return 1 }
+      const r = process.platform === 'win32'
+        ? spawnSync('tar', ['-xf', f, '-C', dest], { stdio: 'inherit' })
+        : spawnSync('tar', ['-xf', f, '-C', dest], { stdio: 'inherit' })
+      return r.status || 0
+    }
+    case 'zip': {
+      const root = p(0); const o = p(1)
+      if (!root || !o) { err('Usage: lvtn fs zip <path> <out.tar.gz>'); return 1 }
+      const r = spawnSync('tar', ['-czf', o, root], { stdio: 'inherit' }); return r.status || 0
+    }
+    case 'ask': {
+      const f = p(0); if (!f) { err('Usage: lvtn fs ask <file> "your question"'); return 1 }
+      const key = requireKey(); if (!key) return 1
+      const question = args._.slice(1).join(' ').trim()
+      let content
+      try { content = fs.readFileSync(f, 'utf-8').slice(0, 200_000) } catch (e) { err(`  ${e.message}`); return 1 }
+      const prompt = `File ${f}:\n\n${content}\n\n---\n${question || 'Summarize this file.'}`
+      const { status, data } = await api('POST', '/api/llm/orchestrate', { key, body: { messages: [{ role: 'user', content: prompt }] }, timeout: 240_000 })
+      if (status !== 200) { err(`  Ask failed (HTTP ${status}): ${data.detail}`); return 1 }
+      out(`\n${(data.text || '').trim()}\n`); return 0
+    }
+    default:
+      out('  lvtn fs read|write|ls|find|grep|mv|cp|rm|extract|zip|reveal|ask')
+      return sub ? 1 : 0
+  }
+}
+
+function walk(root, cb) {
+  let entries
+  try { entries = fs.readdirSync(root, { withFileTypes: true }) } catch { return }
+  for (const e of entries) {
+    const fp = path.join(root, e.name)
+    if (e.isDirectory()) { if (!['node_modules', '.git'].includes(e.name)) walk(fp, cb) }
+    else cb(fp, e.name)
+  }
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) { resolve(''); return }
+    let data = ''
+    process.stdin.setEncoding('utf-8')
+    process.stdin.on('data', (c) => { data += c })
+    process.stdin.on('end', () => resolve(data))
+  })
+}
+
+// ── banner ───────────────────────────────────────────────────────────────────
+export function cmdBanner() {
+  const C = (n, s) => `\x1b[${n}m${s}\x1b[0m`
+  out('')
+  out(C('36', '  ╔═══════════════════════════════════════════════════════════╗'))
+  out(C('36', '  ║') + C('1;35', '          🐉  L E V I A T H A N   T A L O N  🐉            ') + C('36', '║'))
+  out(C('36', '  ║') + C('2;37', '     Leviathan of HaShem Synthetic Intelligence · swarm     ') + C('36', '║'))
+  out(C('36', '  ╚═══════════════════════════════════════════════════════════╝'))
+  out('')
+  out(C('2;37', `  708-agent Kabbalistic swarm in your terminal · v${VERSION}`))
+  out(C('2;37', '  hachazal (Da\'ath) → 7 Angels × 100 agents · cloud, KTRS-metered'))
+  out('')
+  out(`  ${C('33', 'Get started:')}  lvtn signup → lvtn login → lvtn chat`)
+  out(`  ${C('33', 'Full TUI:')}     the 6-frame sixel art deck ships with the pip build (pip install lvtn)`)
+  out('')
+}