@sealant/mend 0.19.0 → 0.21.0

package/dist/main.js

@@ -5,6 +5,8 @@ import { createRequire } from "node:module";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { bridgeUrlOf, shareAgent, startAgentShare } from "./agent-share.js";
+import { readClipboardImage } from "./clipboard.js";
 import { doctorCommand } from "./doctor.js";
 import { readSyncFiles, scanDotfileCandidates } from "./dotfiles.js";
 import { formatLoadReport } from "./env.js";
@@ -12,7 +14,7 @@ import { findCommand, manFileName, renderCommand, renderGroup, renderIndex, rend
 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 { agentIsLive, agentOutcome, cwdFacts, gitTopLevel, HARNESS_COMMANDS, isDetachChunk, isPasteChunk, LIVE_STATUSES, pasteBytes, trackBracketedPaste, 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";
@@ -194,7 +196,7 @@ const adopt = async (config, args) => {
     say(`${dim("  default branch")} ${project.defaultBranch}`);
     // Say which signer did the work — the clone already proved it answers.
     if (project.gitAuthMode === "mend-key") {
-        say(`${dim("  git auth")} mend key ${dim("(the machine's deploy key signed this clone)")}`);
+        say(`${dim("  git auth")} mend key ${dim("(your Mend key signed this clone)")}`);
     }
     else if (project.gitAuthMode === "bridge") {
         say(`${dim("  git auth")} bridge ${dim("(signed through the connected `mend keys share`)")}`);
@@ -452,9 +454,12 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
         finishAttachment?.();
     };
     const signals = ["SIGHUP", "SIGINT", "SIGTERM"];
+    let bracketedPaste = false;
     const onTtyFrame = (event) => {
         if (typeof event.data !== "string") {
-            process.stdout.write(Buffer.from(event.data));
+            const bytes = Buffer.from(event.data);
+            bracketedPaste = trackBracketedPaste(bytes, bracketedPaste);
+            process.stdout.write(bytes);
             return;
         }
         try {
@@ -484,9 +489,36 @@ const attachTty = async (config, sessionId, harness, from, processId, options) =
         }
         if (ws.readyState !== WebSocket.OPEN)
             return;
+        if (isPasteChunk(data)) {
+            // Ctrl+V — the agent's own clipboard is empty (the workspace has no
+            // display), so an image on THIS machine's clipboard goes up to Mend and
+            // its workspace path is pasted instead; codex and claude read the path.
+            // No image, or no way to ask: the keystroke goes through untouched.
+            void pasteClipboardImage(data);
+            return;
+        }
         // Copy into a plain ArrayBuffer (WebSocket.send rejects pooled Buffer views).
         ws.send(new Uint8Array(data).buffer);
     };
+    const forward = (bytes) => {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(new Uint8Array(bytes).buffer);
+    };
+    const pasteClipboardImage = async (keystroke) => {
+        const image = await readClipboardImage();
+        if (image === null) {
+            forward(keystroke);
+            return;
+        }
+        try {
+            const stored = await request(config, "POST", `/sessions/${sessionId}/images`, { contentsBase64: image.bytes.toString("base64") });
+            forward(pasteBytes(stored.path, bracketedPaste));
+        }
+        catch {
+            // The TUI owns the screen; a bell is the only honest signal left.
+            process.stdout.write("\x07");
+        }
+    };
     try {
         sendResize();
         process.stdout.on("resize", onWinch);
@@ -1443,9 +1475,9 @@ const printGitKey = (key) => {
     say(key.publicKey);
     if (key.fingerprint !== null)
         say(dim(`  ${key.fingerprint}`));
-    say(dim("  add this as a deploy key on your git host (GitHub/GitLab/Gitea: repo"));
-    say(dim("  settings → deploy keys; grant write access if sessions should push),"));
-    say(dim("  then adopt with: mend adopt <ssh-url> --auth mend-key"));
+    say(dim("  add this to your git account's SSH keys (GitHub: settings → SSH keys) so"));
+    say(dim("  every repository you can reach works; for one repository only, add it"));
+    say(dim("  as that repository's deploy key instead (grant write if sessions push)"));
 };
 const keysShow = async (config) => {
     const key = await api(config, "GET", "/keys/git");
@@ -1461,125 +1493,73 @@ const keysInit = async (config) => {
     printGitKey(key);
 };
 /**
- * The ssh-agent bridge, client half (docs/GIT-ACCESS.md decision 2): relay
- * the LOCAL ssh-agent to the Mend server over one standing WebSocket, so
- * bridge-mode git ops sign with a key that never leaves this machine — a
- * hardware key blinks here, not on the server. Agent-protocol messages are
- * relayed verbatim (length-prefixed frames, base64 over JSON); the only
- * inspection is each message's type byte, to say what is being asked.
+ * `mend keys share`: the ssh-agent bridge in the foreground (agent-share.ts
+ * holds the relay). Prints every connect, drop, and signature; Ctrl-C stops.
  */
 const keysShare = async (config) => {
     const agentSock = process.env["SSH_AUTH_SOCK"];
     if (agentSock === undefined || agentSock === "") {
         return fail("SSH_AUTH_SOCK is not set — start (or plug in) your ssh-agent first");
     }
-    const url = parseMendUrl(`${config.url}/api/keys/bridge/ws`);
-    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-    url.searchParams.set("host", os.hostname());
-    if (config.token !== null)
-        url.searchParams.set("token", config.token);
-    /**
-     * One complete agent exchange against the local agent: fresh connection,
-     * write the framed request verbatim, read one framed response. A hardware
-     * key blocks here until the touch — hence the generous timeout.
-     */
-    const askLocalAgent = (payload) => new Promise((resolve, reject) => {
-        const connection = net.connect(agentSock, () => {
-            connection.write(payload);
-        });
-        const timer = setTimeout(() => {
-            connection.destroy();
-            reject(new Error("the agent did not answer within 60s — touch missed?"));
-        }, 60_000);
-        let pending = Buffer.alloc(0);
-        connection.on("data", (chunk) => {
-            pending = Buffer.concat([pending, chunk]);
-            if (pending.length >= 4 && pending.length >= 4 + pending.readUInt32BE(0)) {
-                clearTimeout(timer);
-                connection.end();
-                resolve(pending.subarray(0, 4 + pending.readUInt32BE(0)));
-            }
-        });
-        connection.on("error", (error) => {
-            clearTimeout(timer);
-            reject(error);
-        });
-    });
-    // Strictly one request at a time, in arrival order — the agent protocol is
-    // request/response and a hardware key cannot answer two touches at once.
-    let chain = Promise.resolve();
-    const SSH_AGENTC_SIGN_REQUEST = 13;
-    const SSH_AGENTC_REQUEST_IDENTITIES = 11;
-    let attempt = 0;
-    for (;;) {
-        const ws = new WebSocket(url);
-        const closed = new Promise((resolve) => {
-            ws.addEventListener("close", () => resolve(), { once: true });
-        });
-        const opened = await new Promise((resolve) => {
-            ws.addEventListener("open", () => resolve(true), { once: true });
-            ws.addEventListener("error", () => resolve(false), { once: true });
-        });
-        if (opened) {
-            attempt = 0;
-            say(`${green("●")} sharing this machine's ssh-agent with ${config.url}`);
-            say(dim(`  agent: ${agentSock} · signature requests print here · Ctrl-C stops sharing`));
-            ws.addEventListener("message", (event) => {
-                const text = typeof event.data === "string"
-                    ? event.data
-                    : Buffer.from(event.data).toString("utf8");
-                let frame;
-                try {
-                    frame = JSON.parse(text);
-                }
-                catch {
+    const url = bridgeUrlOf(parseMendUrl(config.url).toString().replace(/\/$/, ""), config.token, os.hostname());
+    await shareAgent({
+        url,
+        agentSock,
+        signal: new AbortController().signal,
+        onEvent: (event) => {
+            switch (event.kind) {
+                case "connected":
+                    say(`${green("●")} sharing this machine's ssh-agent with ${config.url}`);
+                    say(dim(`  agent: ${agentSock} · signature requests print here · Ctrl-C stops sharing`));
                     return;
-                }
-                if (frame.t !== "req" ||
-                    typeof frame.id !== "number" ||
-                    typeof frame.payload !== "string") {
+                case "disconnected":
+                    say(dim(`not connected — retrying in ${Math.round(event.retryMs / 1000)}s (Ctrl-C stops)`));
                     return;
-                }
-                const id = frame.id;
-                const payload = Buffer.from(frame.payload, "base64");
-                const type = payload[4];
-                const context = typeof frame.context === "string" ? frame.context : "mend";
-                chain = chain.then(async () => {
-                    const started = Date.now();
-                    if (type === SSH_AGENTC_SIGN_REQUEST) {
-                        say(`${amber("✎")} signature requested by mend ${dim(`(${context})`)}`);
-                        say(dim("  waiting — touch your key if it blinks (up to 60s)…"));
-                    }
-                    else if (type === SSH_AGENTC_REQUEST_IDENTITIES) {
-                        say(dim(`  identities requested (${context})`));
-                    }
-                    try {
-                        const response = await askLocalAgent(payload);
-                        if (ws.readyState !== WebSocket.OPEN)
-                            return null;
-                        ws.send(JSON.stringify({ t: "res", id, payload: response.toString("base64") }));
-                        if (type === SSH_AGENTC_SIGN_REQUEST) {
-                            say(`${green("✓")} signed ${dim(`(${((Date.now() - started) / 1000).toFixed(1)}s)`)}`);
-                        }
-                    }
-                    catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        if (ws.readyState === WebSocket.OPEN) {
-                            ws.send(JSON.stringify({ t: "err", id, message }));
-                        }
-                        if (type === SSH_AGENTC_SIGN_REQUEST)
-                            say(`${amber("✗")} not signed — ${message}`);
-                    }
-                    return null;
-                });
-            });
-        }
-        await closed;
-        attempt += 1;
-        const delay = Math.min(30_000, 1000 * 2 ** Math.min(attempt - 1, 5));
-        say(dim(`not connected — retrying in ${Math.round(delay / 1000)}s (Ctrl-C stops)`));
-        await new Promise((resolve) => setTimeout(resolve, delay));
+                case "sign-requested":
+                    say(`${amber("✎")} signature requested by mend ${dim(`(${event.context})`)}`);
+                    say(dim("  waiting — touch your key if it blinks (up to 60s)…"));
+                    return;
+                case "identities-requested":
+                    say(dim(`  identities requested (${event.context})`));
+                    return;
+                case "signed":
+                    say(`${green("✓")} signed ${dim(`(${event.seconds.toFixed(1)}s)`)}`);
+                    return;
+                case "not-signed":
+                    say(`${amber("✗")} not signed — ${event.message}`);
+                    return;
+            }
+        },
+    });
+};
+/**
+ * `mend keys mode [mend-key|bridge]`: how this user's remotes are reached by
+ * default. The Mend key lives on the server and works whenever the server
+ * is up — detached sessions, the phone, the hot pool. Bridge signs with this
+ * machine's ssh-agent and only works while a mend command is running here.
+ */
+const keysMode = async (config, args) => {
+    const [value] = args;
+    if (value !== undefined && value !== "mend-key" && value !== "bridge") {
+        return fail(`keys mode takes mend-key or bridge, not "${value}"`);
+    }
+    const access = value === undefined
+        ? await api(config, "GET", "/me/git-access")
+        : await api(config, "PUT", "/me/git-access", { mode: value });
+    if (value !== undefined)
+        say(`${green("✓")} git access · ${value}`);
+    if (access.mode === "mend-key") {
+        say(`mend-key ${dim("— your Mend key on the server signs; works whenever the server is up")}`);
+        if (access.key.exists)
+            printGitKey(access.key);
+        else
+            say(dim("  no key yet — mend keys init creates it"));
+        return;
     }
+    say(`bridge ${dim("— this machine's ssh-agent signs; only while a mend command runs here")}`);
+    say(access.bridge.connected
+        ? `${green("●")} signer connected · ${access.bridge.clientName ?? "unknown machine"}`
+        : dim("  no signer connected — mend shares the agent whenever it runs (or: mend keys share)"));
 };
 const keysCommand = async (config, args) => {
     const [verb] = args;
@@ -1588,6 +1568,8 @@ const keysCommand = async (config, args) => {
             return keysInit(config);
         case "share":
             return keysShare(config);
+        case "mode":
+            return keysMode(config, args.slice(1));
         case "show":
         case undefined:
             return keysShow(config);
@@ -2534,15 +2516,58 @@ const dashboard = async (config) => {
         process.exit(rerun.status ?? 0);
     }
     const { runDashboard } = await import("./dashboard.js");
-    await runDashboard({
-        config,
-        cwd: process.cwd(),
-        cwdBranch: gitCurrentBranch(process.cwd()),
-        api: (method, route, body) => request(config, method, route, body),
-        attachTty: (sessionId, harness, processId) => attachTty(config, sessionId, harness, 0n, processId),
-    });
+    const agentShare = await startShareIfBridge(config);
+    try {
+        await runDashboard({
+            config,
+            cwd: process.cwd(),
+            cwdBranch: gitCurrentBranch(process.cwd()),
+            api: (method, route, body) => request(config, method, route, body),
+            attachTty: (sessionId, harness, processId) => attachTty(config, sessionId, harness, 0n, processId),
+            agentShare,
+        });
+    }
+    finally {
+        agentShare?.stop();
+    }
 };
 // ─── entry ──────────────────────────────────────────────────────────────────
+/**
+ * Share this machine's ssh-agent for as long as the calling command runs —
+ * only when the user's git access is bridge (mend keys mode). Their remotes
+ * then sign here, and a base fetch before a worktree is created can't be
+ * skipped for want of a signer. Any other mode, no agent, or an unreachable
+ * server: nothing is shared. A newer share replaces an older one on the
+ * server, so overlapping mend commands hand over rather than fight.
+ */
+const startShareIfBridge = async (config) => {
+    const agentSock = process.env["SSH_AUTH_SOCK"];
+    if (agentSock === undefined || agentSock === "")
+        return null;
+    let access;
+    try {
+        access = await request(config, "GET", "/me/git-access");
+    }
+    catch {
+        return null;
+    }
+    if (access.mode !== "bridge")
+        return null;
+    return startAgentShare({
+        url: bridgeUrlOf(parseMendUrl(config.url).toString().replace(/\/$/, ""), config.token, os.hostname()),
+        agentSock,
+    });
+};
+/** Run one command under the share (see startShareIfBridge); stop it on the way out. */
+const withAgentShare = async (config, work) => {
+    const share = await startShareIfBridge(config);
+    try {
+        return await work();
+    }
+    finally {
+        share?.stop();
+    }
+};
 /** `mend help [command...]`: the index, a group, or one page. */
 const helpCommand = (words) => {
     if (words.length === 0) {
@@ -2599,13 +2624,13 @@ const main = async () => {
         case "claude":
         case "opencode":
         case "run":
-            return launch(config, command, rest);
+            return withAgentShare(config, () => launch(config, command, rest));
         case "attach":
-            return attach(config, rest);
+            return withAgentShare(config, () => attach(config, rest));
         case "stop":
             return stopCommand(config, rest);
         case "shell":
-            return shellCommand(config, rest);
+            return withAgentShare(config, () => shellCommand(config, rest));
         case "service":
             return serviceCommand(config, rest);
         case "login":
@@ -2640,9 +2665,9 @@ const main = async () => {
         case "continue":
             return continueSession(config, rest);
         case "resume":
-            return resumeCommand(config, rest);
+            return withAgentShare(config, () => resumeCommand(config, rest));
         case "rejoin":
-            return rejoinCommand(config, rest);
+            return withAgentShare(config, () => rejoinCommand(config, rest));
         case "projects":
             return projectsCommand(config);
         case "refresh":

package/dist/shared.js

@@ -161,17 +161,7 @@ export const parseLaunchArgs = (args) => {
 export const isDetachChunk = (data) => {
     if (data.includes(0x1d))
         return true;
-    // latin1 maps bytes 1:1, so the scan sees exactly the wire bytes. A string
-    // scan rather than a regex: an escape byte inside a pattern trips lint, and
-    // anchoring on the real ESC[ prefix keeps pasted text from ever matching.
-    const text = data.toString("latin1");
-    const prefix = "\u001b[93;5";
-    for (let start = text.indexOf(prefix); start !== -1; start = text.indexOf(prefix, start + 1)) {
-        const rest = text.slice(start + prefix.length);
-        if (rest.startsWith("u") || rest.startsWith(":1u") || rest.startsWith(":2u"))
-            return true;
-    }
-    return false;
+    return csiUKeysOf(data).some((key) => key.code === 93 && isCtrlChord(key) && isPressOrRepeat(key));
 };
 /**
  * What to call a session's worktree in banners and rows: a NAMED worktree is
@@ -293,3 +283,56 @@ export const normalizeProjectName = (raw) => {
         .replace(/-+$/, "");
     return slug === "" ? "project" : slug.slice(0, 64);
 };
+// Built from a string: an escape byte inside a regex literal trips lint.
+const CSI_U = new RegExp(`${String.fromCharCode(0x1b)}\\[(\\d+)(?::\\d*)*(?:;(\\d+)(?::(\\d+))?)?(?:;[\\d:]+)?u`, "g");
+const LOCK_MODIFIERS = 64 | 128;
+/** Every CSI-u key report inside a chunk, in order. */
+export const csiUKeysOf = (data) => {
+    // latin1 maps bytes 1:1, so the scan sees exactly the wire bytes.
+    const text = data.toString("latin1");
+    const keys = [];
+    for (const match of text.matchAll(CSI_U)) {
+        const code = Number(match[1]);
+        const mods = (match[2] === undefined ? 1 : Number(match[2])) - 1;
+        const event = match[3] === undefined ? 1 : Number(match[3]);
+        keys.push({ code, mods: mods & ~LOCK_MODIFIERS, event });
+    }
+    return keys;
+};
+const CTRL = 4;
+const SHIFT = 1;
+/** Ctrl held, optionally shift, nothing else (alt/super/hyper/meta make it another chord). */
+const isCtrlChord = (key) => (key.mods & ~SHIFT) === CTRL;
+const isPressOrRepeat = (key) => key.event === 1 || key.event === 2;
+/**
+ * Whether one stdin chunk is Ctrl+V — the raw 0x16 byte on its own, or one
+ * CSI-u report of `v` (118) or `V` (86) with ctrl, on press or repeat. Exact
+ * for the raw byte: a paste that happens to carry 0x16 is not a request.
+ */
+export const isPasteChunk = (data) => {
+    if (data.length === 1 && data[0] === 0x16)
+        return true;
+    const keys = csiUKeysOf(data);
+    const key = keys[0];
+    return (keys.length === 1 &&
+        key !== undefined &&
+        (key.code === 118 || key.code === 86) &&
+        isCtrlChord(key) &&
+        isPressOrRepeat(key) &&
+        data.toString("latin1").startsWith("\u001b["));
+};
+/**
+ * Follow the remote app's bracketed-paste mode through the bytes it writes:
+ * the last `ESC [ ? 2004 h|l` in a chunk wins; a chunk with neither keeps the
+ * current state. A pasted image path is wrapped only when the app asked.
+ */
+export const trackBracketedPaste = (output, current) => {
+    const text = output.toString("latin1");
+    const on = text.lastIndexOf("\u001b[?2004h");
+    const off = text.lastIndexOf("\u001b[?2004l");
+    if (on === -1 && off === -1)
+        return current;
+    return on > off;
+};
+/** The bytes that paste `text` into the remote app, bracketed when it asked. */
+export const pasteBytes = (text, bracketed) => Buffer.from(bracketed ? `\u001b[200~${text}\u001b[201~` : text, "utf8");

package/man/mend-accounts.1

@@ -1,4 +1,4 @@
-.TH MEND-ACCOUNTS 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-ACCOUNTS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-accounts \- your connected accounts on the platform
 .SH SYNOPSIS

package/man/mend-adopt.1

@@ -1,4 +1,4 @@
-.TH MEND-ADOPT 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-ADOPT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-adopt \- adopt a repository into the store
 .SH SYNOPSIS
@@ -8,14 +8,14 @@ mend\-adopt \- adopt a repository into the store
 .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.
+\-\-auth says how the store fetches from the remote. Default: your mode from mend keys mode. mend\-key signs with your Mend key on the server (see mend keys). bridge relays this machine's ssh\-agent while a mend command runs here, so hardware keys stay on your desk. ambient uses the server's own credentials.
 .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
+mend\-key, bridge, or ambient. Default: mend keys mode
 .SH EXAMPLES
 .PP
 .B mend adopt

package/man/mend-attach.1

@@ -1,4 +1,4 @@
-.TH MEND-ATTACH 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-ATTACH 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-attach \- reattach this terminal to a running session
 .SH SYNOPSIS
@@ -9,5 +9,7 @@ mend\-attach \- reattach this terminal to a running session
 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.
+.PP
+Ctrl+V with an image on this machine's clipboard sends the image to the session and pastes its path; codex and claude read it. Needs wl\-paste on Wayland, xclip on X11, nothing extra on macOS.
 .SH SEE ALSO
 mend(1), mend\-stop(1), mend\-rejoin(1), mend\-shell(1)

package/man/mend-codex.1

@@ -1,4 +1,4 @@
-.TH MEND-CODEX 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-CODEX 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-codex \- launch codex, claude, or opencode in a recorded worktree
 .SH SYNOPSIS
@@ -12,6 +12,8 @@ mend codex, mend claude, and mend opencode are the same command with a different
 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.
+.PP
+Ctrl+V with an image on this machine's clipboard sends the image to the session and pastes its path; codex and claude read it. Needs wl\-paste on Wayland, xclip on X11, nothing extra on macOS.
 .SH OPTIONS
 .TP
 .B \-\-name <worktree>

package/man/mend-completions.1

@@ -1,4 +1,4 @@
-.TH MEND-COMPLETIONS 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-COMPLETIONS 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-completions \- print the TAB\-completion hook
 .SH SYNOPSIS

package/man/mend-connect.1

@@ -1,4 +1,4 @@
-.TH MEND-CONNECT 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-CONNECT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-connect \- send this machine's provider credential to the platform
 .SH SYNOPSIS

package/man/mend-continue.1

@@ -1,4 +1,4 @@
-.TH MEND-CONTINUE 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-CONTINUE 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-continue \- resume a session with its pending review follow\-up
 .SH SYNOPSIS

package/man/mend-doctor.1

@@ -1,4 +1,4 @@
-.TH MEND-DOCTOR 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-DOCTOR 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-doctor \- check this machine's setup
 .SH SYNOPSIS

package/man/mend-dotfiles-sync.1

@@ -1,4 +1,4 @@
-.TH MEND-DOTFILES-SYNC 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-DOTFILES-SYNC 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-dotfiles\-sync \- capture config files from this machine into your store
 .SH SYNOPSIS

package/man/mend-dotfiles.1

@@ -1,4 +1,4 @@
-.TH MEND-DOTFILES 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-DOTFILES 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-dotfiles \- your dotfiles on the server: repo and synced files
 .SH SYNOPSIS

package/man/mend-env-cluster.1

@@ -1,4 +1,4 @@
-.TH MEND-ENV-CLUSTER 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-ENV-CLUSTER 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-env\-cluster \- bind Kubernetes secrets and configmaps to the workspaces
 .SH SYNOPSIS

package/man/mend-env-load.1

@@ -1,4 +1,4 @@
-.TH MEND-ENV-LOAD 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-ENV-LOAD 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-env\-load \- load a .env into the project
 .SH SYNOPSIS

package/man/mend-env-show.1

@@ -1,4 +1,4 @@
-.TH MEND-ENV-SHOW 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-ENV-SHOW 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-env\-show \- what the project store holds: names only, never values
 .SH SYNOPSIS

package/man/mend-help.1

@@ -1,4 +1,4 @@
-.TH MEND-HELP 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-HELP 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-help \- this index, or one command's page
 .SH SYNOPSIS

package/man/mend-keys-init.1

@@ -1,11 +1,11 @@
-.TH MEND-KEYS-INIT 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-KEYS-INIT 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
-mend\-keys\-init \- generate this machine's Mend deploy key (ed25519)
+mend\-keys\-init \- create your Mend key (ed25519) on the server
 .SH SYNOPSIS
 .B mend keys init
 .br
 .SH DESCRIPTION
 .PP
-Creates a key under ~/.config/mend/keys for projects adopted with \-\-auth mend\-key. Add the public key on your git host as a deploy key.
+One key per user, held on the server, never copied anywhere. Add the public key to your git account's SSH keys and every repository you can reach works, from detached sessions and the phone too. For one repository only, add it as that repository's deploy key instead.
 .SH SEE ALSO
-mend(1), mend\-keys\-show(1), mend\-adopt(1)
+mend(1), mend\-keys\-show(1), mend\-keys\-mode(1), mend\-adopt(1)

package/man/mend-keys-mode.1

@@ -0,0 +1,11 @@
+.TH MEND-KEYS-MODE 1 "" "mend 0.21.0" "mend manual"
+.SH NAME
+mend\-keys\-mode \- how your remotes are reached: mend\-key or bridge
+.SH SYNOPSIS
+.B mend keys mode [mend\-key|bridge]
+.br
+.SH DESCRIPTION
+.PP
+mend\-key (the default) signs with your Mend key on the server and works whenever the server is up. bridge signs with this machine's ssh\-agent, so a hardware key never leaves your desk, but only while a mend command is running here. New projects adopt with this mode; a project's setup page can override it. Without a value, prints the current mode.
+.SH SEE ALSO
+mend(1), mend\-keys\-init(1), mend\-keys\-share(1)

package/man/mend-keys-share.1

@@ -1,4 +1,4 @@
-.TH MEND-KEYS-SHARE 1 "" "mend 0.19.0" "mend manual"
+.TH MEND-KEYS-SHARE 1 "" "mend 0.21.0" "mend manual"
 .SH NAME
 mend\-keys\-share \- relay this machine's ssh\-agent to the server
 .SH SYNOPSIS
@@ -7,5 +7,7 @@ mend\-keys\-share \- relay this machine's ssh\-agent to the server
 .SH DESCRIPTION
 .PP
 Bridge mode for projects adopted with \-\-auth bridge: the server's git operations sign with the keys in this machine's ssh\-agent, so hardware keys never leave here. Runs until Ctrl\-C.
+.PP
+When your mode is bridge (mend keys mode), every attaching mend command and the dashboard do this on their own for as long as they run, so this command is for a machine that is not running one. The server takes one signer at a time; a newer share replaces the older one.
 .SH SEE ALSO
-mend(1), mend\-adopt(1)
+mend(1), mend\-keys\-mode(1), mend\-adopt(1)