moshcode 0.64.0 → 0.66.0

package/README.md

@@ -665,6 +665,32 @@ 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.
 
+### Alchemy — onchain data, wallets, and x402
+
+```sh
+moshcode install alchemy          # npm i -g @alchemy/cli
+
+moshcode alchemy auth             # browser login, then pick an app
+moshcode alchemy evm balance --address 0x…
+moshcode alchemy --json --no-interactive wallet send …
+```
+
+[Alchemy](https://www.alchemy.com/)'s CLI covers four things from one binary:
+querying onchain data across EVM and Solana (balances, NFTs, transfers, prices,
+blocks, logs, traces, simulations, raw RPC), managing Alchemy apps, networks,
+allowlists and webhooks, driving an agent-ready wallet (sends, swaps, contract
+calls, approvals, cross-chain bridges), and paying third-party x402 APIs in
+USDC under a spend cap.
+
+`alchemy auth` opens a browser to link your account and saves the selected app's
+API key; API keys and x402 wallet auth work too, depending on the command. Pass
+`--json --no-interactive` when a script or agent is driving, which is also what
+makes it read like the rest of the roster in a pipeline. It needs Node 22 or
+newer, and re-running `moshcode install alchemy` is its upgrade path.
+
+Where CoinPay is the payments product MoshCode ships alongside, Alchemy is the
+read side of the same world — the chain itself rather than one wallet's ledger.
+
 `gh`, `supabase`, and `doctl` publish no cross-platform install script, so
 MoshCode resolves the latest GitHub release and drops the binary in
 `$MOSHCODE_BIN` (default `~/.local/bin`) — no sudo, no package manager. Set
@@ -805,6 +831,29 @@ survive between sessions. A name that is already a pit command, an engine, or a
 tool is refused rather than shadowed — built-ins are dispatched first, so such
 an alias would never run.
 
+Some workflow tools ship a *set* of commands rather than one binary, and propose
+short words for them. Installing such a tool configures those words too — a
+dispatcher fronting seven commands is not reachable from the pit until the names
+that reach them exist:
+
+```text
+/install cli-tools                # or /tools install cli-tools
+✓ cli-tools installed. 🤘
+  ✓ /blog → blog-post
+  ✓ /free → domainfree
+```
+
+`/upgrade` does the same, because an upgrade is where a tool *gains* commands —
+a roster adopted once at install time otherwise goes stale the first time the
+tool ships something new. `/alias install <tool>` (or `--all`) re-runs it on
+demand, for tools you installed before this existed.
+
+The tool proposes and the pit disposes: moshcode reads the suggestions and
+writes the file, so nothing else reaches into a config it does not own. A name
+you bound yourself always wins — your `/prs` may carry `--orgs` flags a generic
+suggestion knows nothing about — and a tool that offers nothing, or cannot be
+asked, is silent rather than turning a successful install into an error.
+
 ### Social posting from the pit
 
 The pit can hand a prepared post to Bluesky or Nostr without storing either
@@ -1334,6 +1383,7 @@ chmod +x deploy.mosh
 | `alpaca(args…)` | drive the native Alpaca trading CLI |
 | `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) |
 | `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

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { runScript } from "../src/runtime.mjs";
-import { moshVocabulary } from "../src/commands.mjs";
+import { isReserved, moshVocabulary } from "../src/commands.mjs";
 import {
   agentLaunchArgs,
   engineList,
@@ -14,7 +14,7 @@ import {
   resolveExecutable,
   runCmd,
 } from "../src/engines.mjs";
-import { TOOLS, toolList, toolStatus, resolveTool, openTool } from "../src/tools.mjs";
+import { TOOLS, toolList, toolStatus, resolveTool, openTool, adoptAliasLines } from "../src/tools.mjs";
 import { tradeArgs, tradeUsage } from "../src/trade.mjs";
 import { runUpgrade } from "../src/upgrade.mjs";
 import { selfUpdateCommand } from "../src/selfupdate.mjs";
@@ -456,7 +456,14 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    if (result.code === 0) console.log(`\n✓ ${target} installed. run it with \`${bin}\`. 🤘`);
+    if (result.code === 0) {
+      console.log(`\n✓ ${target} installed. run it with \`${bin}\`. 🤘`);
+      // Installing is also configuring: a tool that ships a set of commands is
+      // not usable from the pit until the words that reach them exist. Quiet
+      // for everything that offers none, and a name already in the file is
+      // reported by the adopter rather than replaced.
+      for (const line of adoptAliasLines(target, entry, { isReserved })) console.log(line);
+    }
     return backToPit(`install ${target}`, result.code);
   }
   if (cmd === "uninstall" || cmd === "remove") {

package/package.json

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

package/src/aliases.mjs

@@ -158,3 +158,68 @@ export function expandAlias(value, args = "") {
   const line = `${String(value).trim()}${args ? ` ${args}` : ""}`;
   return /^[/!]/.test(line) ? line : `!${line}`;
 }
+
+/**
+ * How many aliases one tool may offer in a single install.
+ *
+ * A bound, not a judgement about any tool: the proposal is a subprocess's
+ * stdout being written into the operator's config, and an unbounded loop over
+ * whatever it printed is how a bug in a tool becomes a thousand-line
+ * aliases.json. No CLI here offers more than a handful.
+ */
+export const MAX_PROPOSED = 64;
+
+/**
+ * Merge a tool's proposed aliases into the operator's file, in one write.
+ *
+ * Existing names always win. The file is the operator's: silently repointing a
+ * word they bound themselves is the kind of change nothing surfaces until the
+ * wrong command runs — and the pit's own aliases carry flags (`--orgs`,
+ * `--apply`) that a tool's generic suggestion does not know about.
+ *
+ * Names that collide with a pit command, engine, or tool are refused rather
+ * than written, for the reason setAlias refuses them: built-ins are resolved
+ * first, so such an alias would be silently dead.
+ *
+ * Returns { ok, error, added, kept, refused } — each a list of
+ * { name, value, previous? , reason? } so the caller can say what happened
+ * without re-deriving it.
+ */
+export function mergeAliases(proposed, { isReserved = () => false } = {}) {
+  const added = [];
+  const kept = [];
+  const refused = [];
+  if (!proposed || typeof proposed !== "object" || Array.isArray(proposed)) {
+    return { ok: false, error: "that isn't a set of aliases", added, kept, refused };
+  }
+
+  const existing = loadAliases();
+  const merged = { ...existing };
+  // Sorted so the report reads the same way twice regardless of the order the
+  // tool happened to print, and truncated rather than refused: a tool that
+  // offers too many still gets its first MAX_PROPOSED written, and the caller
+  // is told what was dropped.
+  const entries = Object.entries(proposed).sort(([a], [b]) => a.localeCompare(b));
+  const dropped = Math.max(0, entries.length - MAX_PROPOSED);
+
+  for (const [rawName, rawValue] of entries.slice(0, MAX_PROPOSED)) {
+    const name = normalizeName(rawName);
+    const value = typeof rawValue === "string" ? rawValue.trim() : "";
+    if (!name) { refused.push({ name: String(rawName), reason: "not a usable alias name" }); continue; }
+    if (!value) { refused.push({ name, reason: "nothing to run" }); continue; }
+    if (value.includes("\n")) { refused.push({ name, reason: "an alias is a single line" }); continue; }
+    if (value.length > MAX_VALUE) { refused.push({ name, reason: `${value.length} characters — the cap is ${MAX_VALUE}` }); continue; }
+    if (isReserved(name)) { refused.push({ name, reason: "already a pit command, engine, or tool" }); continue; }
+    if (Object.hasOwn(existing, name)) { kept.push({ name, value: existing[name], proposed: value }); continue; }
+    merged[name] = value;
+    added.push({ name, value });
+  }
+
+  // Nothing new is still a success — "already up to date" is the common case on
+  // a second run, and writing the file again to say so would only churn mtime.
+  if (added.length) {
+    try { saveAliases(merged); }
+    catch (e) { return { ok: false, error: `can't write ${aliasFile()}: ${e.message}`, added: [], kept, refused }; }
+  }
+  return { ok: true, added, kept, refused, dropped };
+}

package/src/cli-schema.mjs

@@ -214,8 +214,11 @@ export const CORE_CLI_COMMANDS = [
     examples: [
       ["moshcode install claude", "an engine"],
       ["moshcode install gh", "a workflow tool"],
+      ["moshcode install cli-tools", "a set of commands — its pit aliases come too"],
     ],
     seeAlso: ["uninstall", "upgrade", "engines", "tools"],
+    note: "a tool that ships a set of commands can propose pit aliases for them; "
+      + "installing it adopts the ones you have not already bound yourself.",
   },
   {
     name: "uninstall",
@@ -1176,23 +1179,26 @@ export const PIT_COMMANDS = [
     description: "show the current dir + git repo/branch/origin" },
   { name: "shell", aliases: ["sh"], args: "[cmd]", pitOnly: true,
     description: "drop into $SHELL (exit → back to the pit); also !cmd" },
-  { name: "alias", aliases: ["aliases"], args: 'set <name> "<cmd>" | list | get | rm', pitOnly: true,
+  { name: "alias", aliases: ["aliases"], args: 'set <name> "<cmd>" | list | get | rm | install <tool>', pitOnly: true,
     description: "name a line you keep retyping; /<name> runs it",
     synopsis: [
       ['/alias set <name> "<command>"', "define one (also: /alias <name> \"<command>\")"],
       ["/alias [list] [--json]", "every alias"],
       ["/alias get <name>", "what one expands to"],
       ["/alias rm <name>", "forget one"],
+      ["/alias install <tool> | --all", "re-adopt a tool's aliases (/install does it too)"],
     ],
     examples: [
       ['/alias set gs "git status"', "then /gs — and /gs -sb appends"],
       // Deliberately not `cc`: that one is already how the pit spells claude,
       // so the example would print a refusal for anyone who typed it.
       ['/alias set cx "/agents codex"', "a pit command, not a shell one"],
+      ["/alias install cli-tools", "/blog, /free, /whois — from the tool itself"],
       ["/alias rm gs", ""],
     ],
     note: "the command runs in $SHELL unless it starts with / — then it is a pit command. "
-      + "Aliases live in ~/.moshcode/aliases.json and cannot shadow a pit command, engine, or tool.",
+      + "Aliases live in ~/.moshcode/aliases.json and cannot shadow a pit command, engine, or tool. "
+      + "/alias install never overwrites a name you bound yourself.",
   },
   { name: "help", aliases: ["?", "h"], args: "[command]", pitOnly: true,
     description: "this, or one command in detail" },

package/src/commands.mjs

@@ -81,7 +81,7 @@ function expectNoArgs(name, args) {
  * setAlias() takes) rather than an exported list, so this stays the caller's
  * answer and not a second roster to drift from the first.
  */
-function isReserved(name) {
+export function isReserved(name) {
   const key = String(name).toLowerCase();
   return CORE_CLI_COMMAND_NAMES.includes(key)
     || PIT_COMMANDS.some((c) => (typeof c === "string" ? c : c.name) === key);
@@ -681,6 +681,7 @@ const COMMANDS = [
   cliVerb("alpaca", "drive the native Alpaca trading CLI"),
   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("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
 

package/src/tools.mjs

@@ -4,10 +4,12 @@
 // c0upons owns community coupons and bounties, the cloud CLIs below own
 // deploys/secrets/infra, Coral owns read-only data access across those systems,
 // and moshcode only conducts their native command lines.
+import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { mergeAliases } from "./aliases.mjs";
 import { isInstalled, openPassthrough } from "./engines.mjs";
 
 // gh, supabase, and doctl publish only GitHub release binaries — no official
@@ -44,6 +46,42 @@ export const TOOLS = {
     // The CLI updates itself in place from the same origin the installer uses.
     upgrade: { cmd: "c0upons", args: ["upgrade"] },
   },
+  "cli-tools": {
+    desc: "Profullstack cli-tools — blog publishing, domain availability, and GitHub PR sweeps",
+    // The odd shape here: this is a *set* of commands, not one binary. The
+    // installer symlinks blog-post, domainfree, domainjson, gh-prs,
+    // gh-prs-merge, gh-prs-fix-all and tcfeed into ~/.local/bin, and `cli-tools`
+    // is the dispatcher that fronts them. Probing the dispatcher is what makes
+    // "installed" mean "the whole set is installed" rather than "one of seven
+    // names happens to exist".
+    bin: "cli-tools",
+    install: {
+      cmd: "sh",
+      args: [
+        "-c",
+        "curl -fsSL https://raw.githubusercontent.com/profullstack/cli-tools/master/install.sh | sh",
+      ],
+    },
+    // The installer symlinks into ~/.local/bin and appends nothing to PATH, so
+    // the shell that ran the install cannot see the commands — the same gap
+    // turso, gradient and kimi have.
+    binDirs: [path.join(homedir(), ".local", "bin")],
+    // Its own updater, which pulls and relinks. Deliberately not the installer:
+    // re-running that would re-clone for someone whose checkout lives
+    // elsewhere, and `cli-tools update` refuses to move a dirty or diverged
+    // tree rather than discarding work.
+    upgrade: { cmd: "cli-tools", args: ["update"] },
+    // The pit aliases this set offers. Read at the end of /install and
+    // /upgrade, so installing the set is also configuring it — seven commands
+    // behind one dispatcher are not reachable from the pit until the words that
+    // reach them exist. `/alias install cli-tools` re-runs it on demand.
+    //
+    // Declared rather than probed: a command that prints a set of aliases is
+    // only safe to run against a tool we already know answers it, and an
+    // `aliases --json` guessed at every installed CLI would eventually hit one
+    // where those words mean something else entirely.
+    aliases: { cmd: "cli-tools", args: ["aliases", "--json"] },
+  },
   secrets: {
     desc: "LogicSRC — end-to-end-encrypted team credential sharing (login, teams, credentials)",
     // The passthrough target is the `logicsrc` binary; the moshcode command is
@@ -243,6 +281,22 @@ export const TOOLS = {
     // migrations, and restarts the services. toolUpgradeSpec falls back to
     // install, so there is deliberately no upgrade key.
   },
+  alchemy: {
+    desc: "Alchemy — onchain data, apps and webhooks, agent wallets, and x402 payments (EVM + Solana)",
+    bin: "alchemy",
+    // An ordinary global npm package, and `npm install -g` is idempotent, so
+    // re-running the install IS the upgrade — same shape as mcpjam, hence no
+    // upgrade key. Its postinstall only prints a banner on a global install:
+    // the skill-sync branch above it needs a skills-lock.json that the
+    // published tarball does not ship, so nothing reaches out or is written.
+    //
+    // No installHelp: that line is for a MISSING installer (alpaca's go,
+    // gradient's python3), and npm is already here — moshcode runs on it. The
+    // package does declare node >=22, which npm warns about rather than
+    // refuses; the CLI then says so itself on first run, which is a better
+    // place to hear it than an install that succeeded.
+    install: { cmd: "npm", args: ["install", "-g", "@alchemy/cli"] },
+  },
 };
 
 /** Resolve a name to `[key, tool]`, or null. */
@@ -280,6 +334,90 @@ export function openTool(tool, args = [], opts = {}) {
   return openPassthrough(tool, args, opts);
 }
 
+/** The command that prints a tool's proposed pit aliases, or null. */
+export function toolAliasSpec(tool) {
+  return tool?.aliases || null;
+}
+
+/**
+ * Adopt a tool's aliases and describe the result in plain lines.
+ *
+ * The unpainted counterpart to the pit's renderer, for `moshcode install` —
+ * which is a plain-stdout surface, and may be a script's stdout. Returns [] for
+ * everything with nothing to say, so hanging this off an install costs a tool
+ * that offers no aliases exactly one function call and no output.
+ *
+ * Silent on failure by design: an installer that succeeded must not be followed
+ * by an error about a nicety, and `/alias install <tool>` says the same thing
+ * loudly for anyone who goes looking.
+ */
+export function adoptAliasLines(key, tool, { isReserved = () => false, read = readToolAliases } = {}) {
+  if (!toolAliasSpec(tool)) return [];
+  const answer = read(tool);
+  if (!answer.ok) return [];
+  const result = mergeAliases(answer.aliases, { isReserved });
+  if (!result.ok || !result.added.length) return [];
+  return [
+    `\n${key} also offers ${result.added.length} pit alias${result.added.length === 1 ? "" : "es"}:`,
+    ...result.added.map(({ name, value }) => `  /${name} → ${value}`),
+    ...(result.kept.length ? [`  (kept ${result.kept.length} you had already bound)`] : []),
+  ];
+}
+
+/** Every tool that offers pit aliases, as `[key, tool]`. */
+export function toolsWithAliases() {
+  return Object.entries(TOOLS).filter(([, tool]) => toolAliasSpec(tool));
+}
+
+/**
+ * How long a tool gets to print its aliases before we stop waiting.
+ *
+ * This runs on an interactive verb, so the failure we care about is a CLI that
+ * blocks on something — a login prompt, a network read — rather than one that
+ * is merely slow. Printing a constant should take milliseconds.
+ */
+const ALIAS_TIMEOUT_MS = 10_000;
+
+/**
+ * Ask a tool for the pit aliases it proposes: `{ ok, aliases, error }`.
+ *
+ * Captured rather than passed through, because the output is data we are about
+ * to merge into the operator's config and not something to put on their
+ * screen. Every failure is a returned reason instead of a throw — a tool that
+ * is not installed, prints nothing, or prints something that is not JSON is an
+ * ordinary outcome of this verb, not an error the pit should fall over on.
+ *
+ * `run` is injectable so the tests do not need seven CLIs on PATH.
+ */
+export function readToolAliases(tool, { run = spawnSync } = {}) {
+  const spec = toolAliasSpec(tool);
+  if (!spec) return { ok: false, error: "offers no aliases" };
+  let result;
+  try {
+    result = run(spec.cmd, spec.args, {
+      encoding: "utf8",
+      timeout: ALIAS_TIMEOUT_MS,
+      // No inherited stdin: a tool that decides to ask a question here would
+      // otherwise hang the pit on a prompt nobody can see.
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  if (result.error) return { ok: false, error: result.error.message };
+  if (result.status !== 0) {
+    const said = String(result.stderr || "").trim().split("\n")[0];
+    return { ok: false, error: said || `${spec.cmd} exited ${result.status}` };
+  }
+  let parsed;
+  try { parsed = JSON.parse(String(result.stdout || "")); }
+  catch { return { ok: false, error: `${spec.cmd} didn't print JSON` }; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ok: false, error: `${spec.cmd} printed JSON, but not a set of aliases` };
+  }
+  return { ok: true, aliases: parsed };
+}
+
 // Generic utilities used by the app/package surface.
 
 /**

package/src/tui.mjs

@@ -8,7 +8,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { ENGINES, agentLaunchArgs, resolveEngine, engineStatus, openSession } from "./engines.mjs";
-import { TOOLS, resolveTool, toolStatus, openTool } from "./tools.mjs";
+import { TOOLS, resolveTool, toolStatus, openTool, readToolAliases, toolsWithAliases } from "./tools.mjs";
 import { tradeArgs, tradeUsage } from "./trade.mjs";
 import { postSocial, socialRoster } from "./socials.mjs";
 import { runUpgrade } from "./upgrade.mjs";
@@ -31,7 +31,7 @@ import { banner, hr, acid, ash, bone, dim, ok, err, warn, info, moshcodeVersion
 import { CORE_CLI_COMMAND_NAMES } from "./cli-schema.mjs";
 import { RENAMED_COMMANDS, findPitCommand, pitHelpModel, renderPitCommand, suggest, wantsHelp } from "./help.mjs";
 import { openNewTab } from "./tabs.mjs";
-import { MAX_EXPANSIONS, expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
+import { MAX_EXPANSIONS, expandAlias, getAlias, loadAliases, mergeAliases, removeAlias, setAlias } from "./aliases.mjs";
 import { herdCommand, herdStart, renderRoster, roster, splitDetachArgs } from "./herd-cli.mjs";
 import { detectSubstrate, substrateNote } from "./herd.mjs";
 
@@ -269,6 +269,115 @@ function printAliases({ json = false } = {}) {
   }
 }
 
+/**
+ * `/alias install <tool>` — adopt the pit aliases a workflow tool offers.
+ *
+ * The tools in src/tools.mjs are separate products with their own release
+ * cycles, and several of them ship a set of commands rather than one binary.
+ * Which short words those deserve at this prompt is a question only the tool
+ * can answer, and only moshcode can act on: the file is ours, so a tool that
+ * wrote it directly would be reaching into a config it does not own — the same
+ * objection that keeps `railway setup agent` out of /install.
+ *
+ * So the tool proposes and the pit disposes. Deliberately its own verb rather
+ * than a step inside /install: writing the operator's aliases is a side effect
+ * an install command has no business having, and the roster is worth adopting
+ * long after the day a tool was installed.
+ */
+function aliasInstallCommand(args) {
+  const all = args.includes("--all");
+  const names = args.filter((a) => !a.startsWith("-"));
+  if (!all && !names.length) {
+    const offered = toolsWithAliases().map(([key]) => key);
+    console.log(err("usage: /alias install <tool> | --all"));
+    console.log(ash(offered.length
+      ? `   tools that offer aliases: ${offered.join(", ")}`
+      : "   no tool offers aliases yet"));
+    return;
+  }
+
+  const wanted = all
+    ? toolsWithAliases()
+    : names.map((name) => [name, resolveTool(name)?.[1] ?? null]);
+
+  // A run over --all reports per tool, because "3 added, 2 kept" for a roster
+  // is the useful shape; a single named tool reports per alias, because those
+  // are the words you are about to type.
+  let touched = 0;
+  for (const [key, tool] of wanted) {
+    if (!tool) { console.log(err(`no tool named "${key}" — /tools for the roster`)); continue; }
+    touched += adoptToolAliases(key, tool, { compact: all, quiet: false });
+  }
+  if (touched) console.log(ash("   run one with /<name> · /alias list for all of them"));
+}
+
+/**
+ * Read one tool's proposed aliases, merge them, and say what happened.
+ *
+ * The one place that does this, because three surfaces need it: `/install` and
+ * `/tools install` at the end of an install, `/upgrade` after a tool has gained
+ * commands, and `/alias install` on its own. Returns how many names were added
+ * so a caller can decide whether the run is worth a closing line.
+ *
+ * `quiet` is what makes it safe to hang off an install: a tool that offers
+ * nothing, or that cannot be asked, must not print a failure after a install
+ * that actually succeeded. Only real adoptions and genuine surprises speak up.
+ */
+function adoptToolAliases(key, tool, { compact = false, quiet = false } = {}) {
+  const label = acid(`/${key}`);
+  if (!tool?.aliases) {
+    if (!quiet) console.log(info(`${label} offers no aliases`));
+    return 0;
+  }
+  const read = readToolAliases(tool);
+  if (!read.ok) {
+    if (quiet) return 0;
+    console.log(err(`${label} — ${read.error}`));
+    if (!isInstalledTool(key)) console.log(ash(`   not installed here — /install ${key}`));
+    return 0;
+  }
+  const result = mergeAliases(read.aliases, { isReserved: isReservedName });
+  if (!result.ok) {
+    if (!quiet) console.log(err(`${label} — ${result.error}`));
+    return 0;
+  }
+
+  if (compact) {
+    const parts = [`${result.added.length} added`];
+    if (result.kept.length) parts.push(`${result.kept.length} kept`);
+    if (result.refused.length) parts.push(`${result.refused.length} refused`);
+    console.log(`  ${label.padEnd(20)} ${ash(parts.join(", "))}`);
+    return result.added.length;
+  }
+
+  for (const { name, value } of result.added) {
+    console.log(`  ${ok(`${acid(`/${name}`)} ${ash("→")} ${bone(value)}`)}`);
+  }
+  // Named rather than counted: an alias the operator already owns is the one
+  // case where nothing changed *and* they need to know which word it was,
+  // because theirs and the tool's suggestion are both plausible. Suppressed
+  // after an install, where a list of names that did not change is noise
+  // between the installer's output and the prompt.
+  if (!quiet) {
+    for (const { name, value } of result.kept) {
+      console.log(`  ${info(`kept your own ${acid(`/${name}`)} ${ash(`(${value})`)}`)}`);
+    }
+  }
+  for (const { name, reason } of result.refused) {
+    console.log(`  ${warn(`skipped ${acid(`/${name}`)} ${ash(`— ${reason}`)}`)}`);
+  }
+  if (result.dropped) console.log(ash(`   ${result.dropped} more offered than one run writes`));
+  if (!quiet && !result.added.length && !result.kept.length && !result.refused.length) {
+    console.log(info(`${label} offers no aliases`));
+  }
+  return result.added.length;
+}
+
+/** Is this tool's native executable present? Used only to explain a failure. */
+function isInstalledTool(key) {
+  return Boolean(toolStatus().find((entry) => entry.key === key)?.installed);
+}
+
 /**
  * `/alias` — define, list, and forget the shortcuts (src/aliases.mjs).
  *
@@ -289,6 +398,13 @@ function aliasCommand(rest, line) {
     printAliases({ json });
     return;
   }
+  // Before `set`, because `install` is a verb and not a name: falling through
+  // to the bare-`/alias <name> <value>` shorthand would define an alias called
+  // "install" pointing at whatever came next.
+  if (sub === "install" || sub === "adopt") {
+    aliasInstallCommand(args);
+    return;
+  }
   if (sub === "set" || sub === "add") {
     const name = args[0];
     const value = aliasValue(line);
@@ -322,7 +438,7 @@ function aliasCommand(rest, line) {
   // when there is a value after it, or `/alias gs` would silently define
   // nothing.
   if (args.length) { aliasCommand(["set", ...rest], `/alias set ${commandRemainder(line)}`); return; }
-  console.log(err(`unknown /alias verb "${verb}" — set, list, get, rm`));
+  console.log(err(`unknown /alias verb "${verb}" — set, list, get, rm, install`));
 }
 
 /**
@@ -446,6 +562,16 @@ function printPwd() {
 async function upgradeAll(targets) {
   console.log(info(`upgrading ${bone("moshcode")} + installed engines/tools — hand-off to each updater…`));
   await runUpgrade(targets, { log: (s) => console.log(s), rule: () => console.log(hr()) });
+  // An upgrade is where a tool *gains* commands, so it is the moment its new
+  // shortcuts should appear — a roster adopted once at install time otherwise
+  // goes stale the first time the tool ships something new. Quiet and
+  // never-overwrite, exactly as at install.
+  const wanted = targets?.length
+    ? toolsWithAliases().filter(([key]) => targets.includes(key))
+    : toolsWithAliases();
+  let added = 0;
+  for (const [key, tool] of wanted) added += adoptToolAliases(key, tool, { quiet: true });
+  if (added) console.log(ash(`   ${added} new alias${added === 1 ? "" : "es"} · /alias list for all of them`));
 }
 
 // The live mirror for this pit, once /sessions is watching. Module-level so the
@@ -599,7 +725,18 @@ function installTarget(key) {
       if (e.code === "ENOENT" && target.installHelp) console.log(info(target.installHelp));
       resolve();
     });
-    child.on("exit", (code) => { console.log(hr()); console.log(code === 0 ? ok(`${key} installed. 🤘`) : err(`install exited ${code}`)); resolve(); });
+    child.on("exit", (code) => {
+      console.log(hr());
+      if (code !== 0) { console.log(err(`install exited ${code}`)); return resolve(); }
+      console.log(ok(`${key} installed. 🤘`));
+      // Installing a tool is also configuring it: a set of commands is not
+      // usable from the pit until the words that reach them exist. Quiet, so a
+      // tool with nothing to offer — every engine, and most tools — finishes
+      // exactly as it did before. Names you bound yourself are never touched.
+      const added = Object.hasOwn(TOOLS, key) ? adoptToolAliases(key, TOOLS[key], { quiet: true }) : 0;
+      if (added) console.log(ash(`   ${added} alias${added === 1 ? "" : "es"} from ${key} · /alias list for all of them`));
+      resolve();
+    });
   });
 }
 
@@ -892,6 +1029,18 @@ export async function tui() {
     }
     if (cmd === "tools") {
       if (!rest[0]) { printTools(); continue; }
+      // `/tools install <name>` reads as the obvious spelling to anyone who has
+      // just been shown the roster by `/tools`, and resolveTool would otherwise
+      // answer it with `unknown tool "install"` — a dead end pointing at the
+      // wrong word. Same for the verbs that pair with it.
+      if (["install", "upgrade", "update"].includes(rest[0].toLowerCase()) && rest[1]) {
+        const verb = rest[0].toLowerCase();
+        rl.close();
+        if (verb === "install") await installTarget(rest[1].toLowerCase());
+        else await upgradeAll(rest.slice(1).map((r) => r.toLowerCase()));
+        rl = mkrl();
+        continue;
+      }
       const resolved = resolveTool(rest[0]);
       if (!resolved) { console.log(err(`unknown tool "${rest[0]}". try: ${Object.keys(TOOLS).join(", ")}`)); continue; }
       const [key, tool] = resolved;