@sealant/mend 0.16.0 → 0.18.0

package/dist/main.js

@@ -8,12 +8,14 @@ import * as path from "node:path";
 import { doctorCommand } from "./doctor.js";
 import { readSyncFiles, scanDotfileCandidates } from "./dotfiles.js";
 import { formatLoadReport } from "./env.js";
+import { findCommand, manFileName, renderCommand, renderGroup, renderIndex, renderManIndex, renderManPage, usageOf, } from "./help.js";
 import { loginCommand } from "./login.js";
 import { pairCommand, qrCommand } from "./pair.js";
 import { isComposeFile, proposeFromCompose, proposeFromPackageJson, proposeFromWorkspacePackage, renderMendToml, workspaceGlobs, } from "./service-init.js";
 import { agentIsLive, agentOutcome, cwdFacts, gitTopLevel, HARNESS_COMMANDS, isDetachChunk, LIVE_STATUSES, sessionDisplayName, matchProjectByCwd, normalizeProjectName, gitCurrentBranch, parseLaunchArgs, } from "./shared.js";
 import { DEFAULT_SKILLS_DIR, scanSkillLibrary } from "./skills.js";
 import { sshCommand } from "./ssh-setup.js";
+import { cliVersion, fetchServerVersion, versionLines } from "./version.js";
 // `$XDG_CONFIG_HOME/mend`, default `~/.config/mend`; a pre-XDG `~/.mend` stays authoritative
 // when it is the only one present (mirrors @mend/store's resolver — the CLI stays dependency-light).
 const mendCliHome = () => {
@@ -270,14 +272,14 @@ const launch = async (config, harness, args) => {
         parsed.ask ||
         parsed.fast;
     if (harness === "run" && structured) {
-        return fail("mend run takes no prompt or harness flags — usage: mend run [--project p] -- <command...>");
+        return fail(`mend run takes no prompt or harness flags · ${usageOf("run")}`);
     }
     if (harness === "run" && (parsed.detach || parsed.foreground)) {
         return fail("mend run takes no lifecycle flags — it tails the record; Ctrl+C stops watching, not the command");
     }
     const argv = harness === "run" ? parsed.custom : (HARNESS_COMMANDS[harness] ?? []);
     if (argv.length === 0) {
-        return fail(harness === "run" ? "usage: mend run -- <command...>" : `unknown harness ${harness}`);
+        return fail(harness === "run" ? usageOf("run") : `unknown harness ${harness}`);
     }
     const project = await findProject(config, parsed.project, true);
     // Say which project the cwd resolved to before anything is created — a
@@ -618,16 +620,41 @@ const exitAfterSessionEnd = (config, sessionId) => {
 /** Reattach a terminal to a running session (full scrollback replay, then live). */
 const attach = async (config, args) => {
     const prefix = args.find((a) => !a.startsWith("--"));
-    if (prefix === undefined)
-        return fail("usage: mend attach <session-id-prefix>");
+    // No id: the picker IS the selection surface (the resolution `mend shell`
+    // already uses), so attaching never demands an id the user must go look up.
+    if (prefix === undefined) {
+        const picked = await resolveLiveSession(config, undefined, "attach");
+        return attachPicked(config, picked);
+    }
     const sessions = await api(config, "GET", "/sessions");
     const match = sessions.find((s) => s.id.startsWith(prefix));
     if (match === undefined)
         return fail(`no active session matches "${prefix}"`);
-    say(`${green("✓")} attaching to ${sessionDisplayName(match)} · ${match.harness} ${dim(match.id.slice(0, 8))}${detachHint()}`);
+    return attachPicked(config, match);
+};
+/** Attach to one resolved session — the tail both `mend attach` paths share. */
+const attachPicked = async (config, session) => {
+    say(`${green("✓")} attaching to ${sessionDisplayName(session)} · ${session.harness} ${dim(session.id.slice(0, 8))}${detachHint()}`);
     say("");
-    await attachOrExit(config, match.id, match.harness);
-    exitAfterSessionEnd(config, match.id);
+    const outcome = await attachTty(config, session.id, session.harness, 0n, undefined, {
+        handleSignals: true,
+    });
+    // A live protocol agent (a phone pickup) has no PTY behind it — the attach
+    // reports "unavailable" with nothing wrong. Take the session over: end the
+    // protocol agent, resume the same conversation as a TUI, then attach to it.
+    if (outcome === "unavailable") {
+        const detail = await api(config, "GET", `/sessions/${session.id}`);
+        if (detail.currentAgent?.kind === "agent-protocol" &&
+            agentIsLive(detail.session, detail.currentAgent)) {
+            say(`${amber("taking over")} from the protocol session`);
+            await withSpinner("reopening as a terminal — same conversation…", api(config, "POST", `/sessions/${session.id}/handoff`, { to: "pty" }));
+            say("");
+            await attachOrExit(config, session.id, session.harness);
+            return exitAfterSessionEnd(config, session.id);
+        }
+    }
+    await finishAttach(config, session.id, outcome);
+    return exitAfterSessionEnd(config, session.id);
 };
 /**
  * Explicit stop — the one intent detaching never carries. Ends the agent; the
@@ -640,8 +667,15 @@ const stopCommand = async (config, args) => {
         ? String(args[projectFlag + 1])
         : null;
     const prefix = args.find((arg, index) => !arg.startsWith("--") && index !== projectFlag + 1);
+    // Neither an id nor --all: pick the session to close, the same resolution
+    // `mend attach` uses. --all and --project keep their bulk meaning.
+    if (!all && prefix === undefined && projectName === null) {
+        const picked = await resolveLiveSession(config, undefined, "stop");
+        await stopSessions(config, [picked], false);
+        return;
+    }
     if (!all && prefix === undefined) {
-        return fail("usage: mend stop <session-id-prefix> | --all [--project <p>]");
+        return fail(usageOf("stop"));
     }
     const [sessions, projects] = await Promise.all([
         api(config, "GET", "/sessions"),
@@ -671,19 +705,24 @@ const stopCommand = async (config, args) => {
         }
         targets = matches;
     }
+    await stopSessions(config, targets, all);
+};
+/** Stop each target and print its record link — the tail every stop path shares. */
+const stopSessions = async (config, targets, summarise) => {
     for (const session of targets) {
         await api(config, "POST", `/sessions/${session.id}/stop`);
         say(`${green("✓")} stopped · ${session.harness} · ${dim(session.id.slice(0, 8))} · ${session.branch}`);
         say(`${cobalt("  review")} · ${config.url}/sessions/${session.id}`);
     }
-    if (all)
+    if (summarise) {
         say(`${green("✓")} stopped ${targets.length} session${targets.length === 1 ? "" : "s"}`);
+    }
 };
 /** Compact picker: numbered live sessions, one keystroke of typing. */
 const pickSessionInteractively = async (rows) => {
     say(dim("more than one live session — pick one:"));
     rows.forEach((row, index) => {
-        say(`  ${index + 1}. ${row.session.harness.padEnd(8)} ${dim(row.session.id.slice(0, 8))}  ${row.projectName}  ${dim(row.session.branch)}`);
+        say(`  ${index + 1}. ${row.session.harness.padEnd(8)} ${dim(row.session.id.slice(0, 8))}  ${row.projectName}  ${dim(row.session.branch)}  ${dim(row.session.status)}`);
     });
     const readline = await import("node:readline/promises");
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -699,7 +738,7 @@ const pickSessionInteractively = async (rows) => {
  * the cwd's project narrows, one candidate is taken, several go to the
  * picker, and a non-interactive caller never gets a silent guess.
  */
-const resolveLiveSession = async (config, prefix) => {
+const resolveLiveSession = async (config, prefix, command) => {
     const sessions = await api(config, "GET", "/sessions?retained=1");
     if (prefix !== undefined) {
         const matches = sessions.filter((s) => s.id.startsWith(prefix));
@@ -721,7 +760,7 @@ const resolveLiveSession = async (config, prefix) => {
     if (candidates.length === 1)
         return only;
     if (process.stdin.isTTY !== true) {
-        return fail("several live sessions — name one: mend shell <session-id-prefix>");
+        return fail(`several live sessions — name one: mend ${command} <session-id-prefix>`);
     }
     const nameById = new Map(projects.map((p) => [p.id, p.name]));
     return pickSessionInteractively(candidates.map((session) => ({
@@ -737,7 +776,7 @@ const resolveLiveSession = async (config, prefix) => {
  */
 const shellCommand = async (config, args) => {
     const prefix = args.find((a) => !a.startsWith("--"));
-    const session = await resolveLiveSession(config, prefix);
+    const session = await resolveLiveSession(config, prefix, "shell");
     say(`${green("✓")} shell in ${session.harness} session ${dim(session.id.slice(0, 8))} · ${dim(session.branch)}${detachHint()}`);
     const shellProcess = await withSpinner("opening a shell in the session workspace…", api(config, "POST", `/sessions/${session.id}/shell`));
     say("");
@@ -865,14 +904,14 @@ const serviceAdd = async (config, args) => {
     const positional = args.filter((a, i) => !a.startsWith("--") && (nameFlag === -1 || i !== nameFlag + 1));
     const portRaw = positional.find((a) => /^\d+$/.test(a));
     if (portRaw === undefined) {
-        return fail("usage: mend service add [session] <port> [--name <n>] [--udp] [--http|--https]");
+        return fail(usageOf("service add"));
     }
     const port = Number(portRaw);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
         return fail(`"${portRaw}" is not a port`);
     }
     const prefix = positional.find((a) => a !== portRaw);
-    const session = await resolveLiveSession(config, prefix);
+    const session = await resolveLiveSession(config, prefix, "service add");
     const service = await mutateService(config, "POST", `/sessions/${session.id}/services`, {
         port,
         name,
@@ -900,7 +939,7 @@ const serviceList = async (config) => {
 const serviceStop = async (config, args) => {
     const needle = args.find((a) => !a.startsWith("--"));
     if (needle === undefined)
-        return fail("usage: mend service stop <name-or-id-prefix>");
+        return fail(usageOf("service stop"));
     const services = await fetchServices(config);
     const matches = services.filter((service) => service.label === needle || service.id.startsWith(needle));
     if (matches.length === 0)
@@ -943,8 +982,7 @@ const autoConnect = async (config, service) => {
 };
 const serviceRun = async (config, args) => {
     const dashdash = args.indexOf("--");
-    const usage = "usage: mend service run [session] --port <port> [--name <n>] [--udp] [--http|--https] [--no-connect] -- <command...>\n" +
-        "       mend service run [session] <name> [--no-connect]          (a declared recipe)";
+    const usage = usageOf("service run");
     // No explicit command = a DECLARED Service: resolve the name against the
     // session worktree's mend.toml and start (or adopt) its recipe.
     if (dashdash === -1) {
@@ -953,7 +991,7 @@ const serviceRun = async (config, args) => {
         if (name === undefined)
             return fail(usage);
         const prefix = positionals.length > 1 ? positionals[0] : undefined;
-        const session = await resolveLiveSession(config, prefix);
+        const session = await resolveLiveSession(config, prefix, "service run");
         const recipes = await api(config, "GET", `/sessions/${session.id}/recipes`);
         const recipe = recipes.find((entry) => entry.name === name);
         if (recipe === undefined) {
@@ -996,7 +1034,7 @@ const serviceRun = async (config, args) => {
     if (protocol === "udp" && browserScheme !== null)
         return fail(usage);
     const prefix = head.find((a, i) => !a.startsWith("--") && i !== portFlag + 1 && i !== nameFlag + 1);
-    const session = await resolveLiveSession(config, prefix);
+    const session = await resolveLiveSession(config, prefix, "service run");
     const service = await withSpinner(protocol === "udp"
         ? `starting ${name ?? argv[0]} (udp :${port})…`
         : `starting ${name ?? argv[0]} — waiting for :${port} to answer…`, mutateService(config, "POST", `/sessions/${session.id}/services/run`, {
@@ -1019,7 +1057,7 @@ const serviceLogs = async (config, args) => {
     const from = fromFlag === -1 ? "0" : args[fromFlag + 1];
     const needle = args.find((argument, index) => !argument.startsWith("--") && index !== fromFlag + 1);
     if (needle === undefined || from === undefined || !/^(0|[1-9]\d*)$/.test(from)) {
-        return fail("usage: mend service logs <name-or-id-prefix> [--from <decimal-sequence>]");
+        return fail(usageOf("service logs"));
     }
     const everything = await fetchServiceViews(config, true);
     const matches = everything.filter((view) => view.service.name === needle ||
@@ -1075,7 +1113,7 @@ const serviceLogs = async (config, args) => {
 const serviceRestart = async (config, args) => {
     const needle = args.find((a) => !a.startsWith("--"));
     if (needle === undefined)
-        return fail("usage: mend service restart <name-or-id-prefix>");
+        return fail(usageOf("service restart"));
     const service = await findLiveService(config, needle);
     const restarted = await withSpinner(`restarting ${service.label ?? service.id.slice(0, 8)}…`, mutateService(config, "POST", `/services/${service.id}/restart`));
     say(`${green("✓")} restarted · ${restarted.status}`);
@@ -1321,7 +1359,7 @@ const accountsCommand = async (config) => {
 const connectCommand = async (config, args) => {
     const [providerArg, ...flags] = args;
     if (!isProvider(providerArg)) {
-        return fail("usage: mend connect claude|codex|github [--from-stdin] [--remove]");
+        return fail(usageOf("connect"));
     }
     const provider = providerArg;
     if (flags.includes("--remove")) {
@@ -1554,7 +1592,7 @@ const keysCommand = async (config, args) => {
         case undefined:
             return keysShow(config);
         default:
-            return fail(`unknown keys command "${verb}" — try: mend keys init | show | share`);
+            return fail(`unknown keys command "${verb}" · mend help keys lists them`);
     }
 };
 const formatDotfileBytes = (bytes) => bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
@@ -1717,14 +1755,14 @@ const envCluster = async (config, args) => {
     const explicitProject = takeFlagValue(args, "--project");
     const positional = args.filter((arg, i) => !arg.startsWith("--") && args[i - 1] !== "--project");
     const [verb, ...rest] = positional;
-    const usage = "try: mend env cluster add secret <name> | add configmap <name> | remove <kind>/<name> | sa <name> | sa --clear";
+    const usage = usageOf("env cluster");
     const project = await findProject(config, explicitProject);
     const route = `/projects/${project.id}/cluster-bindings`;
     const appliesLine = () => say(dim("  applies from the next workspace launch; running workspaces keep what they started with"));
     if (verb === "add") {
         const [kind, objectName] = rest;
         if ((kind !== "secret" && kind !== "configmap") || objectName === undefined) {
-            return fail(`env cluster add takes a kind and an object name — ${usage}`);
+            return fail(`env cluster add takes a kind and an object name\n${usage}`);
         }
         const result = await api(config, "POST", route, {
             kind,
@@ -1738,7 +1776,7 @@ const envCluster = async (config, args) => {
         const [ref] = rest;
         const [kind, objectName] = ref?.split("/", 2) ?? [];
         if ((kind !== "secret" && kind !== "configmap") || objectName === undefined) {
-            return fail(`env cluster remove takes <kind>/<name>, e.g. secret/app-env — ${usage}`);
+            return fail(`env cluster remove takes <kind>/<name>, e.g. secret/app-env\n${usage}`);
         }
         const snapshot = await api(config, "GET", route);
         const binding = snapshot.bindings.find((b) => b.kind === kind && b.objectName === objectName);
@@ -1752,7 +1790,7 @@ const envCluster = async (config, args) => {
         const clear = args.includes("--clear");
         const [name] = rest;
         if (!clear && name === undefined)
-            return fail(`env cluster sa takes a name or --clear — ${usage}`);
+            return fail(`env cluster sa takes a name or --clear\n${usage}`);
         const result = await api(config, "PUT", `${route}/service-account`, { serviceAccount: clear ? null : name });
         say(result.serviceAccount === null
             ? `${green("✓")} cleared the workspace service account ${dim(`· cluster r${result.revision}`)}`
@@ -1762,7 +1800,7 @@ const envCluster = async (config, args) => {
         }
         return appliesLine();
     }
-    return fail(`unknown env cluster command "${verb ?? ""}" — ${usage}`);
+    return fail(`unknown env cluster command "${verb ?? ""}"\n${usage}`);
 };
 const envCommand = async (config, args) => {
     const [verb, ...rest] = args;
@@ -1775,7 +1813,7 @@ const envCommand = async (config, args) => {
         case undefined:
             return envShow(config, rest);
         default:
-            return fail(`unknown env command "${verb}" — try: mend env load | show | cluster`);
+            return fail(`unknown env command "${verb}" · mend help env lists them`);
     }
 };
 const dotfilesCommand = async (config, args) => {
@@ -1787,7 +1825,7 @@ const dotfilesCommand = async (config, args) => {
         case undefined:
             return dotfilesShow(config);
         default:
-            return fail(`unknown dotfiles command "${verb}" — try: mend dotfiles sync | show`);
+            return fail(`unknown dotfiles command "${verb}" · mend help dotfiles lists them`);
     }
 };
 /** With `--project` the project's library; bare, your own. */
@@ -1856,7 +1894,7 @@ const skillsCommand = async (config, args) => {
             // Bare flags (`mend skills --project web`) read as the list.
             if (verb.startsWith("--"))
                 return skillsList(config, args);
-            return fail(`unknown skills command "${verb}" — try: mend skills push | list`);
+            return fail(`unknown skills command "${verb}" · mend help skills lists them`);
     }
 };
 // ─── completions: live sessions under TAB ───────────────────────────────────
@@ -1941,7 +1979,7 @@ const completionsCommand = (args) => {
             process.stdout.write(BASH_COMPLETIONS);
             return;
         default:
-            return fail('usage: mend completions zsh|bash — e.g. mend completions zsh > "$fpath[1]/_mend"');
+            return fail(`${usageOf("completions")} · e.g. mend completions zsh > "$fpath[1]/_mend"`);
     }
 };
 // ─── supervised run: platform workspace + PTY + record ──────────────────────
@@ -2482,7 +2520,7 @@ const hasNodeFfi = () => {
  */
 const dashboard = async (config) => {
     if (process.stdout.isTTY !== true) {
-        say(HELP);
+        say(renderIndex());
         return;
     }
     if (!hasNodeFfi()) {
@@ -2503,98 +2541,54 @@ const dashboard = async (config) => {
     });
 };
 // ─── entry ──────────────────────────────────────────────────────────────────
-const HELP = `mend — the agent workbench
-
-start
-  mend login [--url <server>]           sign this terminal in through the browser: opens
-                                        <server>/authorize, you press Authorize there, and the
-                                        CLI saves a revocable device token (0600); no password
-                                        is ever typed here
-  mend connect <provider> [--from-stdin] [--remove]
-                                        send THIS machine's claude/codex/github credential to the
-                                        platform under your own user (reads the file the provider's
-                                        CLI wrote at login; --from-stdin pastes one instead)
-  mend adopt [source] [--name <name>] [--auth ambient|mend-key|bridge]
-                                        adopt a repository into the store (default: cwd; any git
-                                        URL — GitHub, GitLab, self-hosted, ssh://, a local path)
-  mend codex|claude|opencode ["prompt"] [--name <worktree>] [--worktree <existing>]
-                             [--model <id>] [--effort low|medium|high|xhigh|max]
-                             [--base <ref>] [--ask] [--fast] [--detach|-d] [--foreground]
-                                        launch the harness in a worktree; the worktree's name is
-                                        asked first (--name skips the ask — an EXISTING name joins
-                                        that worktree as a new session; --worktree joins only,
-                                        failing if absent), a
-                                        quoted prompt becomes its first message,
-                                        --ask restores the harness's permission prompts, --fast
-                                        requests priority processing (codex service tier),
-                                        --detach launches without attaching (reattach anywhere),
-                                        --foreground stops the session when this CLI exits
-  mend pair [--url <base url>]          pair a phone or a second machine: prints a QR, the code, and
-                                        the URL to reach this server (one device, once, 10 minutes)
-  mend doctor                           read-only checklist of this machine's setup — one line per
-                                        fact, each unfinished one ending in the command that fixes it
-
-everything else
-  mend                                  the dashboard: every project and session, live
-  mend logout                           revoke this terminal's device token and forget it
-  mend keys init                        generate the machine's Mend deploy key (ed25519)
-  mend keys show                        print the public key — add it as a deploy key on your git host
-  mend env load [file] [--secret [A,B]] load a .env into the project: ordinary names → configuration,
-                                        secret-shaped names → secrets; --secret sends all (or the
-                                        named ones, e.g. DATABASE_URL) to secrets
-  mend env show                         what the project store holds — names only, never values
-  mend accounts                         your connected accounts on the platform (claude, codex, github)
-  mend dotfiles                         your dotfiles on the server: repo + synced home files
-  mend dotfiles sync [--all | paths…]   capture config files from THIS machine into your store
-  mend skills [--project [p]]           your skill library on the server (or a project's)
-  mend skills push [--project [p]] [--prune] [--dir <path>]
-                                        upload ~/.agents/skills bundles into the library; sessions
-                                        receive them at launch (--prune removes what's gone)
-  mend keys share                       relay THIS machine's ssh-agent to the server (bridge mode:
-                                        hardware keys sign here; Ctrl-C stops sharing)
-  mend run -- <command...>              same, with an arbitrary command
-  mend worktrees [--project <p>] [--json]
-                                        every worktree and the sessions inside it (mend sessions
-                                        --json stays the v1 flat list; --json=v2 groups like this)
-  mend attach <session-id-prefix>       reattach this terminal to a running session
-  mend stop <session-id-prefix> | --all [--project <p>]
-                                        stop the agent — the workspace harvests and closes; the
-                                        record and review remain
-  mend shell [session-id-prefix]        open a shell in a live session's workspace
-  mend service run [session] --port <p> [--name <n>] [--udp] -- <command...>
-                                        start + supervise a server in the session workspace
-  mend service run [session] <name>     start a declared Service (mend.toml recipe)
-  mend service <name>                   shorthand for the above
-  mend service init [--yes]             scaffold mend.toml from package.json + compose ports
-  mend service add [session] <port> [--name <n>] [--udp]
-                                        adopt a listening workspace port — reachable on this machine
-  mend service connect [name…] [--port <p>]
-                                        bring live Services to THIS machine's loopback — each
-                                        connection tunnels through the server, authenticated as you
-  mend service list                     every live service and its observed state
-  mend service logs <name-or-id>        follow a supervised service's output (replay, then live)
-  mend service restart <name-or-id>     re-run its recorded command — same URL
-  mend service stop <name-or-id>        stop a service (closes its host port)
-  mend continue [session-id]            resume a session with its pending review follow-up
-  mend resume [session-id] [--with h]   rejoin a settled session (state restored; --with switches harness)
-  mend rejoin [session-id] [--harness h] attach if live, otherwise resume; newest live wins
-  mend refresh [project]                fetch origin's branches into the store — new sessions
-                                        base on current tips (default: the cwd's project)
-  mend projects                         adopted projects and their live sessions
-  mend sessions [--all] [--project p] [--json]
-                                        sessions with review facts; JSON is stable for integrations
-  mend status                           active sessions (alias of mend sessions)
-  mend ssh                              workspace SSH status: gateway, registered keys, ssh config
-  mend ssh setup [--key <path>]         make this machine ready once: offer a key (ssh-agent
-                                        preferred — nothing new created), write Host mend-ws
-  mend completions zsh|bash             print the TAB-completion hook (live session ids under TAB)
-
-  server: MEND_URL (default http://localhost:3105) · auth: MEND_TOKEN
-  detach key: Ctrl+] (set MEND_DETACH_KEY=none when an outer multiplexer owns detaching)
-  config file: ~/.config/mend/cli.json { "url": ..., "token": ..., "deviceId": ... }
-`;
+/** `mend help [command...]`: the index, a group, or one page. */
+const helpCommand = (words) => {
+    if (words.length === 0) {
+        say(renderIndex());
+        return;
+    }
+    const doc = findCommand(words);
+    if (doc !== null && (doc.name.split(" ").length > 1 || words.length === 1)) {
+        say(renderCommand(doc));
+        return;
+    }
+    const group = renderGroup(words[0] ?? "");
+    if (doc !== null) {
+        say(renderCommand(doc));
+        return;
+    }
+    if (group !== null) {
+        say(group);
+        return;
+    }
+    return fail(`no command "${words.join(" ")}" · mend help lists them`);
+};
+/** `mend man [command...]`: the same page through man(1), or the text page without it. */
+const manCommand = (words) => {
+    const doc = words.length === 0 ? null : findCommand(words);
+    if (words.length > 0 && doc === null) {
+        return fail(`no command "${words.join(" ")}" · mend help lists them`);
+    }
+    const version = cliVersion();
+    const page = doc === null ? renderManIndex(version) : renderManPage(doc, version);
+    const file = path.join(os.tmpdir(), `mend-man-${process.pid}-${manFileName(doc)}`);
+    fs.writeFileSync(file, page);
+    const result = spawnSync("man", ["-l", file], { stdio: "inherit" });
+    fs.rmSync(file, { force: true });
+    if (result.error !== undefined || result.status !== 0) {
+        say(doc === null ? renderIndex() : renderCommand(doc));
+    }
+};
 const main = async () => {
     const [command, ...rest] = process.argv.slice(2);
+    // `mend <command> --help` (or -h) before the separator is that command's page,
+    // never an argument: `mend run -- cmd --help` keeps its --help for cmd.
+    const ownArgs = rest.slice(0, rest.indexOf("--") === -1 ? rest.length : rest.indexOf("--"));
+    if (command !== undefined &&
+        command !== "help" &&
+        ownArgs.some((a) => a === "--help" || a === "-h")) {
+        return helpCommand([command, ...ownArgs.filter((a) => !a.startsWith("-"))]);
+    }
     const config = loadConfig();
     switch (command) {
         case "adopt":
@@ -2628,7 +2622,7 @@ const main = async () => {
             return connectCommand(config, rest);
         case "pair":
             return pairCommand(rest, boundApi(config));
-        // Deliberately absent from HELP: the installer renders its own QR through this.
+        // Hidden in the catalog: the installer renders its own QR through this.
         case "qr":
             return qrCommand(rest);
         case "doctor":
@@ -2661,10 +2655,18 @@ const main = async () => {
             return dashboard(config);
         case "help":
         case "--help":
-            say(HELP);
+        case "-h":
+            return helpCommand(rest);
+        case "man":
+            return manCommand(rest);
+        case "version":
+        case "--version":
+        case "-v":
+            for (const line of versionLines(cliVersion(), await fetchServerVersion(config.url)))
+                say(line);
             return;
         default:
-            return fail(`unknown command "${command}" — try: mend help`);
+            return fail(`unknown command "${command}" · mend help lists them`);
     }
 };
 await main();

package/dist/version.js

@@ -0,0 +1,48 @@
+import * as fs from "node:fs";
+/**
+ * `mend version`: this CLI's version, then the server's when it answers.
+ * The two drift apart in practice — an npm install on one machine, a cluster
+ * roll on another — and "which one am I on" is the first question any bug
+ * report needs answered. The server line is best-effort: a missing server is
+ * a fact to print, never an error.
+ */
+/** The published version, read from the package this file ships in (dist/ and src/ sit one level under it). */
+export const cliVersion = () => {
+    const raw = fs.readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "version" in parsed) {
+        const version = parsed.version;
+        if (typeof version === "string")
+            return version;
+    }
+    return "unknown";
+};
+/** Ask the server's health route, briefly; a slow or absent server is `null`. */
+export const fetchServerVersion = async (url, timeoutMs = 2_000) => {
+    try {
+        const response = await fetch(`${url}/api/health`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return { url, version: null };
+        const body = await response.json();
+        const version = typeof body === "object" && body !== null && "version" in body ? body.version : null;
+        return { url, version: typeof version === "string" ? version : null };
+    }
+    catch {
+        return { url, version: null };
+    }
+};
+/** The lines `mend version` prints — terse facts, no verdict beyond the mismatch note. */
+export const versionLines = (cli, server) => {
+    const lines = [`mend ${cli}`];
+    if (server.version === null) {
+        lines.push(`server · unreachable · ${server.url}`);
+    }
+    else {
+        lines.push(`server ${server.version} · ${server.url}`);
+        if (server.version !== cli)
+            lines.push("versions differ — the server's API wins");
+    }
+    return lines;
+};

package/man/mend-accounts.1

@@ -0,0 +1,11 @@
+.TH MEND-ACCOUNTS 1 "" "mend 0.18.0" "mend manual"
+.SH NAME
+mend\-accounts \- your connected accounts on the platform
+.SH SYNOPSIS
+.B mend accounts
+.br
+.SH DESCRIPTION
+.PP
+claude, codex, and github: connected, invalid, or archived, and when each was last used.
+.SH SEE ALSO
+mend(1), mend\-connect(1)

package/man/mend-adopt.1

@@ -0,0 +1,27 @@
+.TH MEND-ADOPT 1 "" "mend 0.18.0" "mend manual"
+.SH NAME
+mend\-adopt \- adopt a repository into the store
+.SH SYNOPSIS
+.B mend adopt [source] [\-\-name <name>] [\-\-auth ambient|mend\-key|bridge]
+.br
+.SH DESCRIPTION
+.PP
+Clones the repository into Mend's store. Every session then gets its own worktree of it. The default source is the current directory; any git URL works, GitHub, GitLab, self\-hosted, ssh://, or a local path.
+.PP
+\-\-auth says how the store fetches from the remote. ambient uses the server's own credentials. mend\-key uses this machine's deploy key (see mend keys). bridge relays this machine's ssh\-agent while mend keys share runs, so hardware keys stay here.
+.SH OPTIONS
+.TP
+.B \-\-name <name>
+the project's name in Mend. Default: the repository's
+.TP
+.B \-\-auth <mode>
+ambient, mend\-key, or bridge. Default: ambient
+.SH EXAMPLES
+.PP
+.B mend adopt
+.br
+the repository you are standing in
+.PP
+.B mend adopt git@github.com:acme/api.git \-\-auth mend\-key
+.SH SEE ALSO
+mend(1), mend\-keys\-init(1), mend\-keys\-share(1), mend\-refresh(1)

package/man/mend-attach.1

@@ -0,0 +1,13 @@
+.TH MEND-ATTACH 1 "" "mend 0.18.0" "mend manual"
+.SH NAME
+mend\-attach \- reattach this terminal to a running session
+.SH SYNOPSIS
+.B mend attach [session\-id\-prefix]
+.br
+.SH DESCRIPTION
+.PP
+With no id, the one live session is taken; with several, a picker opens. A prefix of the id is enough.
+.PP
+A session that was picked up on the phone is taken back into this terminal: the phone's agent ends and the same conversation continues here.
+.SH SEE ALSO
+mend(1), mend\-stop(1), mend\-rejoin(1), mend\-shell(1)