@sealant/mend 0.17.0 → 0.19.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
@@ -673,7 +675,7 @@ const stopCommand = async (config, args) => {
         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"),
@@ -902,7 +904,7 @@ 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) {
@@ -937,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)
@@ -980,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) {
@@ -1056,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 ||
@@ -1112,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}`);
@@ -1358,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")) {
@@ -1591,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`;
@@ -1754,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,
@@ -1775,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);
@@ -1789,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}`)}`
@@ -1799,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;
@@ -1812,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) => {
@@ -1824,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. */
@@ -1893,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 ───────────────────────────────────
@@ -1978,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 ──────────────────────
@@ -2327,7 +2328,9 @@ const sessionsCommand = async (config, args) => {
     }
     let rows;
     if (all || projectName !== null) {
-        const details = await Promise.all(scope.map((p) => api(config, "GET", `/projects/${p.id}`)));
+        // --all means all: dead ends (settled, no conversation) included, which the server hides
+        // otherwise for every client.
+        const details = await Promise.all(scope.map((p) => api(config, "GET", `/projects/${p.id}${all ? "?deadEnds=include" : ""}`)));
         rows = details.flatMap((detail) => detail.sessions.map((session) => ({
             session,
             projectName: detail.project.name,
@@ -2519,7 +2522,7 @@ const hasNodeFfi = () => {
  */
 const dashboard = async (config) => {
     if (process.stdout.isTTY !== true) {
-        say(HELP);
+        say(renderIndex());
         return;
     }
     if (!hasNodeFfi()) {
@@ -2540,99 +2543,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
-                                        (no id: pick one from the live sessions)
-  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":
@@ -2666,7 +2624,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":
@@ -2699,10 +2657,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.19.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.19.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.19.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)

package/man/mend-codex.1

@@ -0,0 +1,60 @@
+.TH MEND-CODEX 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-codex \- launch codex, claude, or opencode in a recorded worktree
+.SH SYNOPSIS
+.B mend codex ["prompt"] [\-\-name <worktree>] [\-\-worktree <existing>] [\-\-model <id>] [\-\-effort <level>] [\-\-base <ref>] [\-\-ask] [\-\-fast] [\-\-detach|\-d] [\-\-foreground] [\-\-project <p>]
+.br
+also mend claude, mend opencode, with the same options
+.SH DESCRIPTION
+.PP
+mend codex, mend claude, and mend opencode are the same command with a different harness. The session runs in a workspace on the platform, in its own git worktree, and everything it does is recorded. This terminal attaches to it.
+.PP
+The worktree's name is asked first. \-\-name skips the ask; an existing name joins that worktree as a new session. \-\-worktree joins only and fails if the name is unknown. A quoted prompt becomes the first message.
+.PP
+Detach with Ctrl+] and the session keeps running. Reattach from any terminal with mend attach, or from the phone.
+.SH OPTIONS
+.TP
+.B \-\-name <worktree>
+name the worktree; an existing name joins it
+.TP
+.B \-\-worktree <existing>
+join an existing worktree only
+.TP
+.B \-\-model <id>
+the harness's model id
+.TP
+.B \-\-effort <level>
+low, medium, high, xhigh, or max
+.TP
+.B \-\-base <ref>
+the branch or sha the worktree starts from
+.TP
+.B \-\-ask
+keep the harness's permission prompts
+.TP
+.B \-\-fast
+priority processing where the harness offers it (codex)
+.TP
+.B \-\-detach, \-d
+launch without attaching
+.TP
+.B \-\-foreground
+stop the session when this CLI exits
+.TP
+.B \-\-project <p>
+the project by name, when the current directory is not inside it
+.SH EXAMPLES
+.PP
+.B mend claude "add a health endpoint"
+.br
+asks for a worktree name, then runs
+.PP
+.B mend codex \-\-name auth\-rework \-d
+.br
+start in the background
+.PP
+.B mend codex \-\-worktree auth\-rework
+.br
+a second session in the same worktree
+.SH SEE ALSO
+mend(1), mend\-attach(1), mend\-stop(1), mend\-run(1), mend\-sessions(1)

package/man/mend-completions.1

@@ -0,0 +1,14 @@
+.TH MEND-COMPLETIONS 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-completions \- print the TAB\-completion hook
+.SH SYNOPSIS
+.B mend completions zsh|bash
+.br
+.SH DESCRIPTION
+.PP
+Commands complete, and live session ids complete under TAB by asking the server.
+.SH EXAMPLES
+.PP
+.B mend completions zsh > "$fpath[1]/_mend"
+.SH SEE ALSO
+mend(1)

package/man/mend-connect.1

@@ -0,0 +1,25 @@
+.TH MEND-CONNECT 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-connect \- send this machine's provider credential to the platform
+.SH SYNOPSIS
+.B mend connect <claude|codex|github> [\-\-from\-stdin] [\-\-remove]
+.br
+.SH DESCRIPTION
+.PP
+Sessions run on the platform, so the platform needs your provider login. This reads the file the provider's own CLI wrote when you logged in (claude, codex) or asks gh for its token (github) and stores it under your own user. Nothing is shared with other users.
+.SH OPTIONS
+.TP
+.B \-\-from\-stdin
+paste a credential instead of reading the provider's file
+.TP
+.B \-\-remove
+disconnect the provider
+.SH EXAMPLES
+.PP
+.B mend connect claude
+.br
+after `claude login` on this machine
+.PP
+.B mend connect github \-\-remove
+.SH SEE ALSO
+mend(1), mend\-accounts(1)

package/man/mend-continue.1

@@ -0,0 +1,11 @@
+.TH MEND-CONTINUE 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-continue \- resume a session with its pending review follow\-up
+.SH SYNOPSIS
+.B mend continue [session\-id]
+.br
+.SH DESCRIPTION
+.PP
+The review comments you sent to the session become its first message. With no id, the newest session with a pending follow\-up is taken.
+.SH SEE ALSO
+mend(1), mend\-resume(1), mend\-sessions(1)

package/man/mend-doctor.1

@@ -0,0 +1,11 @@
+.TH MEND-DOCTOR 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-doctor \- check this machine's setup
+.SH SYNOPSIS
+.B mend doctor
+.br
+.SH DESCRIPTION
+.PP
+Read\-only. One line per fact: the server, the sign\-in, the platform connection, the provider accounts, the git key. Each unfinished line ends with the command that fixes it.
+.SH SEE ALSO
+mend(1), mend\-login(1), mend\-connect(1), mend\-keys\-init(1)

package/man/mend-dotfiles-sync.1

@@ -0,0 +1,15 @@
+.TH MEND-DOTFILES-SYNC 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-dotfiles\-sync \- capture config files from this machine into your store
+.SH SYNOPSIS
+.B mend dotfiles sync [\-\-all | paths...]
+.br
+.SH DESCRIPTION
+.PP
+Copies the named files from your home directory into your store on the server. \-\-all takes the known shell, git, and editor files. Setups that rely on ZDOTDIR do not transfer.
+.SH OPTIONS
+.TP
+.B \-\-all
+every known config file
+.SH SEE ALSO
+mend(1), mend\-dotfiles(1)

package/man/mend-dotfiles.1

@@ -0,0 +1,11 @@
+.TH MEND-DOTFILES 1 "" "mend 0.19.0" "mend manual"
+.SH NAME
+mend\-dotfiles \- your dotfiles on the server: repo and synced files
+.SH SYNOPSIS
+.B mend dotfiles [show]
+.br
+.SH DESCRIPTION
+.PP
+Workspaces apply your dotfiles at launch, from a repository you point the server at or from files mend dotfiles sync captured. This shows what is set.
+.SH SEE ALSO
+mend(1), mend\-dotfiles\-sync(1)