moshcode 0.66.0 → 0.68.0

package/README.md

@@ -48,6 +48,7 @@ or miss one that does. A test fails the build when it drifts.
 | `moshcode load` | account | bring your saved pit settings onto this machine |
 | `moshcode console` | account | serve or connect to the browser terminal |
 | `moshcode dns` | hosting | resolve Moshpit names on this machine |
+| `moshcode name` | hosting | prove you hold a Moshpit name, so an app can use it as your identity |
 | `moshcode doh` | hosting | run the DNS-over-HTTPS resolver |
 | `moshcode site` <br>`serve` | hosting | install web-server config for a Moshpit name |
 | `moshcode template` <br>`templates` | hosting | scaffold a stack for a Moshpit-hosted service |
@@ -590,6 +591,40 @@ moshcode ugig --json gigs list    # arguments/output go straight to ugig
 moshcode coinpay wallet balance   # arguments/output go straight to coinpay
 ```
 
+### BufferOverride — the failure in front of you, already answered
+
+[BufferOverride](https://bufferoverride.com) is where humans and agents debug
+together: every answer declares the versions it works on, who or what wrote it,
+and whether anyone independent reproduced it. `bo` is that from a terminal.
+
+```sh
+moshcode install bo               # npm i -g @profullstack/bufferoverride
+
+moshcode bo run -- pnpm test      # run it, keep what it printed, search for it
+moshcode bo search "worker exited before finishing"
+moshcode bo get a1b2c3d4e5 --markdown
+```
+
+The product is BufferOverride and the binary is `bo` — the same split
+`secrets`/`logicsrc` and `spinifex`/`spx` have, keyed the short way round here
+because this is a command you type every time something fails.
+
+`bo run --` wraps a command rather than replacing it: the wrapped command's exit
+code passes straight through, so it can go in front of something already in CI
+without changing what CI sees. It captures stdout, stderr, the exit code, the
+OS, the architecture and the detected dependency versions, redacts what it
+recognises as a secret, and searches for the failure **before** offering to
+publish it. Nothing leaves the machine until you have seen it, and outside a TTY
+nothing is published at all unless you pass `--ask`.
+
+Redaction is best effort and cannot be complete — no pattern list catches a
+custom-format secret — so `--dry-run` is the habit its own docs ask for.
+
+Reads need no credential: `search` and `get` work before you have ever run `bo
+login`. Publishing needs one, and `bo login` is a device-code exchange, so a
+terminal never handles a browser session. `bo mcp config` prints the MCP
+registration for a coding agent, which is the same graph over a different door.
+
 ### Cloud + infra CLIs
 
 ```sh
@@ -665,6 +700,35 @@ engines, `mcpjam` tells you whether that server is healthy first — health
 checks, OAuth conformance, tool-surface diffing, and structured triage from the
 terminal or CI. Re-running `moshcode install mcpjam` is also its upgrade path.
 
+### ElevenLabs — Eleven Agents, voices, and speech
+
+```sh
+moshcode install elevenlabs       # npm i -g @elevenlabs/cli
+
+moshcode elevenlabs auth login    # PKCE OAuth, stored in the system keyring
+moshcode elevenlabs agents list
+moshcode elevenlabs agents push   # upload local agent configs to the platform
+moshcode elevenlabs text-to-speech convert …
+```
+
+[ElevenLabs](https://elevenlabs.io/docs/eleven-agents/operate/cli)' CLI manages
+**Eleven Agents** — conversational voice agents you define in files and
+`push`/`pull` against their platform, alongside the knowledge bases, tools,
+tests and phone numbers those agents use. The same binary reaches the rest of
+the API: voices, text-to-speech, dubbing, transcription, music, and workspace
+usage.
+
+They are agents in a different sense than the ones under `/agents`: you deploy
+them and callers talk to them, rather than handing your terminal to one. That is
+why it sits here with the workflow CLIs — every subcommand runs one request and
+exits, so it pipes like the rest of the roster. `--format json` (the default
+when stdout is not a TTY) and `--query` (JMESPath) are what a script wants.
+
+The npm package is a small shim over a native binary shipped as an optional
+dependency, so install it without `--omit=optional` or the `elevenlabs` on your
+PATH will refuse to run. Re-running `moshcode install elevenlabs` is its upgrade
+path.
+
 ### Alchemy — onchain data, wallets, and x402
 
 ```sh
@@ -1038,6 +1102,7 @@ Some MCP servers are worth remembering by name rather than by npx invocation:
 ```sh
 moshcode mcp catalog              # what we know how to run
 moshcode mcp add porkbun          # expands to: npx -y @porkbunllc/mcp-server
+moshcode mcp add bufferoverride   # expands to: https://bufferoverride.com/mcp
 ```
 
 That registers it across every engine that supports MCP (claude, gemini, qwen,
@@ -1059,6 +1124,23 @@ from and five to rotate. Porkbun's API access is off by default and enabled
 per-domain — and its documentation tools work with no keys at all, which is a
 sensible way to try the server before trusting it with DNS writes.
 
+**BufferOverride is the useful-unauthenticated one.** Five read tools
+(`search_questions`, `get_question`, `list_questions`, `list_tags`, `whoami`)
+work with no credential, and the write tools are gated on the scopes a key
+actually carries — `tools/list` advertises only what your key can use. So the
+bare `mcp add bufferoverride` above is a complete, working registration. To
+publish from an engine, add the credential as a header:
+
+```sh
+moshcode mcp add bufferoverride -H "Authorization: Bearer bo_..."
+```
+
+`bo mcp config` prints the same thing from a terminal that has already signed
+in, and `bo mcp config --no-token` prints a form safe to paste in public. It is
+registered under the name the CLI uses, so both routes produce one server rather
+than two. See [BufferOverride](#bufferoverride--the-failure-in-front-of-you-already-answered)
+above for the CLI itself.
+
 ## Claude Code plugins
 
 MoshCode publishes its own plugin marketplace, so the pit's slash commands work
@@ -1371,6 +1453,7 @@ chmod +x deploy.mosh
 | `coinpay(args…)` | drive the coinpay workflow CLI |
 | `c0mpute(args…)` | drive the c0mpute workflow CLI |
 | `c0upons(args…)` | drive the c0upons workflow CLI |
+| `bo(args…)` | drive the BufferOverride CLI (capture a failure, search, ask, answer, verify) |
 | `secrets(args…)` | drive the logicsrc secrets CLI |
 | `railway(args…)` | drive the Railway CLI |
 | `gh(args…)` | drive the GitHub CLI |
@@ -1384,6 +1467,7 @@ chmod +x deploy.mosh
 | `mcpjam(args…)` | drive the MCPJam CLI (test, debug, and validate MCP servers) |
 | `spinifex(args…)` | drive the Spinifex CLI (`spx` — AWS-compatible cloud on your own hardware) |
 | `alchemy(args…)` | drive the Alchemy CLI (onchain data, apps, wallets, x402) |
+| `elevenlabs(args…)` | drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing) |
 | `trade(args…)` | look up tickers, inspect markets, preview/place Alpaca orders |
 | `stocks(args…)` | research tickers via advis0r (`stocksRead` returns the data) |
 | `crypto(args…)` | research crypto pairs via advis0r (`cryptoRead` returns the data) |

package/bin/moshcode.mjs

@@ -33,6 +33,7 @@ import { consoleCommand } from "../src/console.mjs";
 import { herdCommand, herdStart, splitDetachArgs } from "../src/herd-cli.mjs";
 import { detectSubstrate, substrateNote } from "../src/herd.mjs";
 import { dnsCommand } from "../src/dns.mjs";
+import { nameCommand } from "../src/name-link.mjs";
 import { templateCommand } from "../src/templates.mjs";
 import { serveCommand } from "../src/serve.mjs";
 import { createDohServer, nginxDohSite, parseDohPort, parseGuardArgs, DEFAULT_DOH_PORT, DOH_PATH } from "../src/doh-server.mjs";
@@ -545,6 +546,10 @@ async function main() {
     process.exitCode = (await dnsCommand(rest)) || 0;
     return;
   }
+  if (cmd === "name") {
+    process.exitCode = (await nameCommand(rest)) || 0;
+    return;
+  }
   if (cmd === "doh") {
     const nameAt = rest.indexOf("--nginx");
     if (nameAt >= 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/src/cli-schema.mjs

@@ -394,6 +394,22 @@ export const CORE_CLI_COMMANDS = [
     ],
     seeAlso: ["doh", "site"],
   },
+  {
+    name: "name",
+    group: "hosting",
+    description: "prove you hold a Moshpit name, so an app can use it as your identity",
+    synopsis: [["moshcode name link <name> [--app <url>]", ""]],
+    flags: [
+      ["--app <url>", "the app to prove the name to", "https://qrypt.chat"],
+      ["--dir <path>", "where the name's key and certificate live", "/etc/ssl/moshpit"],
+      ["--json", "print the proof bundle as machine-readable JSON", ""],
+    ],
+    examples: [
+      ["sudo moshcode name link chovy.hacker", "the key is root-owned"],
+      ["sudo moshcode name link blue.eggs --json", "hand the bundle to a script"],
+    ],
+    seeAlso: ["dns", "site", "whoami"],
+  },
   {
     name: "doh",
     group: "hosting",

package/src/commands.mjs

@@ -668,6 +668,7 @@ const COMMANDS = [
   cliVerb("coinpay", "drive the coinpay workflow CLI"),
   cliVerb("c0mpute", "drive the c0mpute workflow CLI"),
   cliVerb("c0upons", "drive the c0upons workflow CLI"),
+  cliVerb("bo", "drive the BufferOverride CLI (capture a failure, search, ask, answer, verify)"),
   cliVerb("secrets", "manage/view team secrets via logicsrc (login, teams, credentials)"),
   cliVerb("railway", "drive the Railway CLI (deploys, services, env vars)"),
   cliVerb("gh", "drive the GitHub CLI (repos, PRs, issues, releases)"),
@@ -682,6 +683,7 @@ const COMMANDS = [
   cliVerb("mcpjam", "drive the MCPJam CLI (test, debug, and validate MCP servers)"),
   cliVerb("spinifex", "drive the Spinifex CLI (spx — AWS-compatible cloud on your own hardware)"),
   cliVerb("alchemy", "drive the Alchemy CLI (onchain data, apps, wallets, x402)"),
+  cliVerb("elevenlabs", "drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing)"),
   cliVerb("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
 

package/src/integrations.mjs

@@ -238,9 +238,14 @@ export async function mcpCommand(tokens, { run, installedSet } = {}) {
   const missing = (parsed.catalog?.env || []).filter((k) => !process.env[k]);
   if (missing.length) {
     console.log(ash(`  note: ${spec.name} needs ${missing.join(" and ")} in the environment.`));
-    if (parsed.catalog?.note) console.log(ash(`        ${parsed.catalog.note}`));
-    if (parsed.catalog?.docs) console.log(ash(`        ${parsed.catalog.docs}`));
   }
+  // The catalog's own note and docs are printed whenever the catalog was used,
+  // not only when a variable is missing. A server whose credential is a header
+  // rather than an environment variable — or one that needs none at all to be
+  // useful — has nothing in `env`, and hanging its note off that check is what
+  // made the note invisible for exactly the servers it was written for.
+  if (parsed.catalog?.note) console.log(ash(`  note: ${parsed.catalog.note}`));
+  if (parsed.catalog?.docs) console.log(ash(`        ${parsed.catalog.docs}`));
   if (spec.headers.length || /^https?:/i.test(spec.target)) {
     console.log(ash("  note: OAuth/HTTP servers may still need per-engine auth (e.g. `opencode mcp auth`, `codex mcp login`)."));
   }

package/src/mcp-catalog.mjs

@@ -24,6 +24,23 @@ export const MCP_CATALOG = {
     // before deciding whether to trust it with keys.
     note: "API access is off by default and must be enabled per-domain; the docs tools work without keys",
   },
+  bufferoverride: {
+    // A remote HTTP server, so the target is the URL and there are no args —
+    // every engine's builder pushes the target alone for a remote server.
+    target: "https://bufferoverride.com/mcp",
+    args: [],
+    desc: "BufferOverride — version-aware technical answers, with provenance and reproductions",
+    docs: "https://bufferoverride.com/docs/mcp",
+    // Named to match what the CLI's own `bo mcp config` emits, so registering
+    // it either way produces one server rather than two under different names.
+    //
+    // No `env`: the credential is a bearer header, not a variable, and it is
+    // deliberately not listed here. Five read tools work with no key at all,
+    // and the write tools are gated on the scopes a key actually carries — so
+    // the useful default really is unauthenticated. `bo mcp config` prints the
+    // header form for a terminal that has signed in.
+    note: "reads need no credential; to publish, add -H \"Authorization: Bearer bo_…\" (see `bo mcp config`)",
+  },
 };
 
 /** Resolve a catalog name to a spec fragment, or null. Own properties only. */
@@ -44,7 +61,10 @@ export function catalogNames() {
 
 /** One line per known server, for `mcp catalog`. */
 export function catalogList() {
+  // Width from the longest name rather than a fixed pad: `bufferoverride` is
+  // wider than the old 10, and a name that overruns the pad loses the column.
+  const width = Math.max(10, ...Object.keys(MCP_CATALOG).map((key) => key.length));
   return Object.entries(MCP_CATALOG)
-    .map(([key, e]) => `  ${key.padEnd(10)} ${e.desc}`)
+    .map(([key, e]) => `  ${key.padEnd(width)} ${e.desc}`)
     .join("\n");
 }

package/src/name-link.mjs

@@ -0,0 +1,259 @@
+// `moshcode name link <name>` — prove you hold a Moshpit name, so an app can
+// use it as your identity.
+//
+// The registry already publishes, per name, the SHA-256 of the SubjectPublicKeyInfo
+// that name's certificate must present (see src/pins.mjs). That pin is a
+// name-to-key binding nobody else can forge, which makes it a credential: sign
+// something with the pinned key and you have proved you hold the name.
+//
+// What this does NOT do is generate the app's encryption key. The pinned key is
+// P-256 and it signs; a messenger's key is ML-KEM-1024 and it encrypts, and a
+// KEM key cannot sign at all. They are two keys with two jobs, and the private
+// half of the second one belongs on the device the person actually reads
+// messages on — not here. So this emits a proof bundle and stops. The app posts
+// it alongside a key it generated itself and never showed anyone.
+//
+// The bundle is single-use and short-lived: the challenge it answers is burned
+// on redemption, so a copy of it is worth nothing once used.
+
+import fs from "node:fs";
+import crypto from "node:crypto";
+
+/** Where an app that speaks this protocol lives, unless told otherwise. */
+export const DEFAULT_APP = "https://qrypt.chat";
+
+/** Where moshcode's own tooling writes a name's key and certificate. */
+export const DEFAULT_KEY_DIR = "/etc/ssl/moshpit";
+
+/**
+ * A name is `<label>.<tld>`, lowercase.
+ *
+ * Empty segments are refused rather than collapsed. `chovy..hacker` folding
+ * into `chovy.hacker` is harmless in a filename and is a way in when the string
+ * is an identity.
+ *
+ * @param {unknown} input
+ * @returns {string | null}
+ */
+export function normalizeName(input) {
+  const clean = String(input ?? "").trim().toLowerCase().replace(/\.$/, "");
+  if (!clean) return null;
+  const parts = clean.split(".");
+  if (parts.length !== 2 || parts.some((p) => !p)) return null;
+  if (!parts.every((p) => /^[a-z0-9-]+$/.test(p) && !p.startsWith("-") && !p.endsWith("-"))) return null;
+  return parts.join(".");
+}
+
+/**
+ * Where a name's key and certificate live.
+ *
+ * Mirrors keyPaths() in src/pins.mjs, including that separators which could
+ * climb out of the directory are dropped rather than escaped.
+ *
+ * @param {string} name
+ * @param {string} [dir]
+ */
+export function keyPaths(name, dir = DEFAULT_KEY_DIR) {
+  const safe = String(name ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]/g, "")
+    .replace(/\.{2,}/g, ".")
+    .replace(/^[.-]+|[.-]+$/g, "");
+  if (!safe) return null;
+  return { key: `${dir}/${safe}.key`, cert: `${dir}/${safe}.crt` };
+}
+
+/**
+ * Sign a challenge with a name's private key.
+ *
+ * DER, because that is what `crypto.verify` reads back with `dsaEncoding: 'der'`
+ * on the other side. A P-1363 signature is the same numbers in a shape the
+ * verifier rejects, and the failure looks identical to a wrong key.
+ *
+ * @param {{keyPem: string, nonce: string}} args
+ * @returns {string} base64 signature
+ */
+export function signChallenge({ keyPem, nonce }) {
+  const key = crypto.createPrivateKey(keyPem);
+  return crypto
+    .sign("sha256", Buffer.from(nonce, "utf8"), { key, dsaEncoding: "der" })
+    .toString("base64");
+}
+
+/**
+ * The pin a certificate's key hashes to — SHA-256 over the SPKI, base64.
+ * Shown so the operator can eyeball it against what the registry publishes
+ * before wondering why a proof was refused.
+ *
+ * @param {string} certPem
+ */
+export function pinOf(certPem) {
+  const cert = new crypto.X509Certificate(certPem);
+  const der = cert.publicKey.export({ type: "spki", format: "der" });
+  return crypto.createHash("sha256").update(der).digest("base64");
+}
+
+/**
+ * Ask an app for a challenge to sign.
+ *
+ * @param {{app: string, name: string, fetchImpl?: typeof fetch}} args
+ */
+export async function fetchChallenge({ app, name, fetchImpl = fetch }) {
+  const url = `${app.replace(/\/+$/, "")}/api/auth/moshpit/challenge`;
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ name }),
+  });
+
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+
+  if (!res.ok) {
+    throw new Error(body?.error || `${app} answered ${res.status}`);
+  }
+  if (!body?.jti || !body?.nonce) {
+    throw new Error(`${app} did not return a challenge`);
+  }
+  return body;
+}
+
+/**
+ * Read a name's key and certificate off disk, with the failure a person can act on.
+ *
+ * The key is root-owned, so "permission denied" is the expected first
+ * experience and deserves the fix rather than the errno.
+ *
+ * @param {{name: string, keyPath: string, certPath: string, readFile?: (p: string, e: string) => string}} args
+ */
+export function readNameKey({ name, keyPath, certPath, readFile = (p, e) => fs.readFileSync(p, e) }) {
+  let keyPem;
+  try {
+    keyPem = readFile(keyPath, "utf8");
+  } catch (error) {
+    if (error.code === "EACCES") {
+      throw new Error(`cannot read ${keyPath} — it is root-owned, so run this with sudo`);
+    }
+    if (error.code === "ENOENT") {
+      throw new Error(`no key for ${name} at ${keyPath} — mint one before linking it`);
+    }
+    throw error;
+  }
+
+  let certPem;
+  try {
+    certPem = readFile(certPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`no certificate for ${name} at ${certPath}`);
+    }
+    throw error;
+  }
+
+  return { keyPem, certPem };
+}
+
+/**
+ * Parse `name link <name> [--app url] [--dir path] [--json]`.
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const flag = (name, fallback) => {
+    const at = argv.indexOf(`--${name}`);
+    return at >= 0 && argv[at + 1] ? argv[at + 1] : fallback;
+  };
+  const positional = argv.filter((a, i) => {
+    if (a.startsWith("--")) return false;
+    // Skip a value that belongs to the flag before it.
+    return !(i > 0 && argv[i - 1].startsWith("--") && argv[i - 1] !== "--json");
+  });
+
+  return {
+    verb: positional[0] || "",
+    name: positional[1] || "",
+    app: flag("app", DEFAULT_APP),
+    dir: flag("dir", DEFAULT_KEY_DIR),
+    json: argv.includes("--json"),
+  };
+}
+
+/**
+ * `moshcode name link <name>` — fetch a challenge, sign it, print the bundle.
+ *
+ * @param {string[]} argv
+ * @param {{out?: (s: string) => void, err?: (s: string) => void, fetchImpl?: typeof fetch,
+ *          readFile?: (p: string, e: string) => string}} [io]
+ * @returns {Promise<number>} exit code
+ */
+export async function nameCommand(argv, io = {}) {
+  const out = io.out || ((s) => console.log(s));
+  const err = io.err || ((s) => console.error(s));
+  const { verb, name: raw, app, dir, json } = parseArgs(argv);
+
+  if (verb !== "link") {
+    err("usage: moshcode name link <name> [--app <url>] [--dir <path>] [--json]");
+    return 1;
+  }
+
+  const name = normalizeName(raw);
+  if (!name) {
+    err(`not a Moshpit name: ${raw || "(none)"} — expected <label>.<tld>`);
+    return 1;
+  }
+
+  const paths = keyPaths(name, dir);
+  if (!paths) {
+    err(`not a Moshpit name: ${raw}`);
+    return 1;
+  }
+
+  let keyPem;
+  let certPem;
+  try {
+    ({ keyPem, certPem } = readNameKey({
+      name,
+      keyPath: paths.key,
+      certPath: paths.cert,
+      readFile: io.readFile,
+    }));
+  } catch (error) {
+    err(error.message);
+    return 1;
+  }
+
+  let challenge;
+  try {
+    challenge = await fetchChallenge({ app, name, fetchImpl: io.fetchImpl });
+  } catch (error) {
+    err(`could not get a challenge from ${app}: ${error.message}`);
+    return 1;
+  }
+
+  let signature;
+  try {
+    signature = signChallenge({ keyPem, nonce: challenge.nonce });
+  } catch (error) {
+    err(`could not sign with ${paths.key}: ${error.message}`);
+    return 1;
+  }
+
+  const bundle = { jti: challenge.jti, name, certPem, signature };
+
+  if (json) {
+    out(JSON.stringify(bundle));
+    return 0;
+  }
+
+  out(`Proved ${name} against ${app}`);
+  out(`  pin      ${pinOf(certPem)}`);
+  out(`  expires  ${challenge.expiresAt || "shortly"}`);
+  out("");
+  out("Paste this into the app to finish linking. It is single-use:");
+  out("");
+  out(JSON.stringify(bundle));
+  return 0;
+}

package/src/tools.mjs

@@ -82,6 +82,19 @@ export const TOOLS = {
     // where those words mean something else entirely.
     aliases: { cmd: "cli-tools", args: ["aliases", "--json"] },
   },
+  bo: {
+    desc: "BufferOverride — capture a failing command, redact it, and find the answer that already exists",
+    // The product is BufferOverride and the binary is `bo`, the same split
+    // `secrets` → `logicsrc` and `spinifex` → `spx` have. It is keyed the other
+    // way round from those two on purpose: `bo` is what its own documentation
+    // tells you to type, and this is a command you run every time something
+    // fails, so the short word is the one worth having in the pit.
+    bin: "bo",
+    // An ordinary global npm package with no dependencies of its own, and
+    // `npm install -g` is idempotent, so re-running the install IS the upgrade
+    // — no `upgrade` key, the same as mcpjam and railway.
+    install: { cmd: "npm", args: ["install", "-g", "@profullstack/bufferoverride"] },
+  },
   secrets: {
     desc: "LogicSRC — end-to-end-encrypted team credential sharing (login, teams, credentials)",
     // The passthrough target is the `logicsrc` binary; the moshcode command is
@@ -297,6 +310,32 @@ export const TOOLS = {
     // place to hear it than an install that succeeded.
     install: { cmd: "npm", args: ["install", "-g", "@alchemy/cli"] },
   },
+  elevenlabs: {
+    desc: "ElevenLabs — build, configure and deploy Eleven Agents (plus voices, TTS, dubbing, and the rest of the API)",
+    bin: "elevenlabs",
+    // A workflow tool rather than an engine, despite the name. ElevenLabs calls
+    // these "agents", but they are conversational voice agents you configure and
+    // deploy to their platform: `elevenlabs agents push/pull/list` is an API
+    // client that runs one request and exits. `/agents` promises to hand the
+    // terminal to a live session, and there is no session here to hand it, so
+    // this belongs next to the other workflow CLIs. Docs:
+    // https://elevenlabs.io/docs/eleven-agents/operate/cli
+    //
+    // Authenticate once with `moshcode elevenlabs auth login` — a PKCE OAuth
+    // flow that stores the credential in the system keyring (falling back to a
+    // file under ~/.config), rather than an env var to keep exporting.
+    //
+    // The published package is a tiny Node shim; the real CLI is a native
+    // binary shipped per platform as an OPTIONAL dependency
+    // (@elevenlabs/cli-linux-x64 and friends). That is why the install spec is
+    // the plain global install with no flags: an install run with
+    // `--omit=optional` or `--no-optional` still succeeds and still puts
+    // `elevenlabs` on PATH, but every invocation then dies with "the platform
+    // package is not installed". `npm install -g` is idempotent and the CLI
+    // ships no updater of its own, so this doubles as the upgrade path and
+    // there is deliberately no `upgrade` key.
+    install: { cmd: "npm", args: ["install", "-g", "@elevenlabs/cli"] },
+  },
 };
 
 /** Resolve a name to `[key, tool]`, or null. */