premanmcp 0.7.0 → 0.8.0

package/bin/account.js

@@ -0,0 +1,223 @@
+/**
+ * Account-adjacent commands: browser login, logout, doctor, and watch.
+ *
+ * `loginBrowser` drives the device-code flow at /auth/device/*, which has existed
+ * in the backend with no client. It is the right path for anyone who does not
+ * want to type a password into a terminal, and the only one that works when the
+ * account is behind SSO.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { spawn } from "node:child_process";
+import os from "node:os";
+
+import { detectCandidates } from "./detect.js";
+import {
+  CREDENTIALS_FILE,
+  backendUrl,
+  callBackendJson,
+  cliInvocation,
+  frontendUrl,
+  makeArgs,
+  readStoredCredentials,
+  resolveApiKey,
+  saveStoredCredentials,
+} from "./shared.js";
+
+export const ACCOUNT_HELP = `
+Account options:
+  login --browser       Approve sign-in in the browser instead of typing a password
+  logout                Delete stored CLI credentials
+  doctor                Check backend, credentials, target, and integrations
+  watch <run-id>        Follow a push simulation as it runs
+`;
+
+const POLL_INTERVAL_MS = 3000;
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+function openBrowser(url) {
+  const opener =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(opener, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function loginBrowser(args) {
+  const start = await callBackendJson(args, "POST", "/auth/device/request", {
+    json: { device_name: `PreMan CLI (${os.hostname()})` },
+  });
+  if (!start.ok) {
+    throw new Error(`could not start browser login: ${start.status_code} ${start.detail || ""}`);
+  }
+
+  const verificationUrl = start.verification_url || `${frontendUrl(args)}/device/verify?code=${start.device_code}`;
+  process.stdout.write(
+    `\nApprove this device in your browser:\n  ${verificationUrl}\n\n` +
+      `Confirmation code: ${start.user_code}\n\n`
+  );
+  if (!openBrowser(verificationUrl)) {
+    process.stdout.write("Could not open a browser automatically — open the link above.\n");
+  }
+  process.stdout.write("Waiting for approval…\n");
+
+  const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    const poll = await callBackendJson(args, "POST", "/auth/device/poll", {
+      json: { device_code: start.device_code },
+    });
+    const status = String(poll.status || "").toLowerCase();
+    if (poll.ok && poll.api_key) {
+      const creds = {
+        api_key: String(poll.api_key),
+        backend_url: backendUrl(args),
+        user_email: poll.user_email || "",
+        device_name: os.hostname(),
+        created_at: new Date().toISOString(),
+      };
+      saveStoredCredentials(creds);
+      process.stdout.write(`\nSigned in${creds.user_email ? ` as ${creds.user_email}` : ""}.\n`);
+      process.stdout.write(`Saved to ${CREDENTIALS_FILE}\n`);
+      return creds;
+    }
+    if (status === "expired" || status === "denied") {
+      throw new Error(`browser login ${status}. Run \`${cliInvocation()} login --browser\` again.`);
+    }
+  }
+  throw new Error("browser login timed out after 5 minutes.");
+}
+
+export async function logoutCommand() {
+  if (existsSync(CREDENTIALS_FILE)) {
+    rmSync(CREDENTIALS_FILE, { force: true });
+    process.stdout.write(`Removed ${CREDENTIALS_FILE}\n`);
+  } else {
+    process.stdout.write("No stored credentials to remove.\n");
+  }
+  process.stdout.write(
+    "Note: this does not revoke the API key. Revoke it in the dashboard if the machine is shared.\n"
+  );
+}
+
+function line(label, ok, detail) {
+  const mark = ok === null ? "–" : ok ? "✓" : "✗";
+  return `  ${mark} ${label}${detail ? `  ${detail}` : ""}`;
+}
+
+export async function doctorCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const results = [];
+  let failures = 0;
+
+  const stored = readStoredCredentials();
+  const token = resolveApiKey(args);
+  results.push(
+    line(
+      "credentials",
+      Boolean(token),
+      token
+        ? `${stored?.user_email || "key present"} (${CREDENTIALS_FILE})`
+        : `none — run \`${cliInvocation()} login\``
+    )
+  );
+  if (!token) failures += 1;
+
+  let health = { ok: false, status_code: 0, detail: "" };
+  try {
+    health = await callBackendJson(args, "GET", "/health");
+  } catch (error) {
+    health = { ok: false, status_code: 0, detail: String(error?.message || error) };
+  }
+  results.push(line("backend", health.ok, `${backendUrl(args)}${health.ok ? "" : ` — ${health.detail || health.status_code}`}`));
+  if (!health.ok) failures += 1;
+
+  let status = null;
+  if (token && health.ok) {
+    try {
+      status = await callBackendJson(args, "GET", "/cli/status", { token });
+    } catch (error) {
+      status = { ok: false, detail: String(error?.message || error) };
+    }
+    results.push(
+      line("api key", Boolean(status.ok), status.ok ? `workspace ${status.workspace?.name || "?"}` : status.detail || `status ${status.status_code}`)
+    );
+    if (!status.ok) failures += 1;
+  }
+
+  const candidates = detectCandidates(process.cwd());
+  results.push(
+    line(
+      "local target",
+      candidates.length > 0,
+      candidates.length
+        ? `${candidates.length} candidate${candidates.length === 1 ? "" : "s"} (${candidates[0].url} from ${candidates[0].source})`
+        : "no signals in this directory"
+    )
+  );
+
+  if (status?.ok) {
+    const integrations = status.integrations || {};
+    for (const [name, section] of Object.entries(integrations)) {
+      results.push(line(name, Boolean(section?.connected), section?.connected ? "" : "not connected"));
+    }
+    results.push(
+      line("project link", Boolean(status.workspace?.project_id), status.workspace?.project_id ? "" : "workspace is not linked to a project")
+    );
+  }
+
+  process.stdout.write(`PreMan doctor\n\n${results.join("\n")}\n\n`);
+  process.stdout.write(failures ? `${failures} problem${failures === 1 ? "" : "s"} found.\n` : "Everything looks healthy.\n");
+  if (failures) process.exitCode = 1;
+  return { failures };
+}
+
+const TERMINAL_STATUSES = new Set(["complete", "completed", "failed", "error", "cancelled"]);
+
+export async function watchCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const token = resolveApiKey(args);
+  if (!token) throw new Error(`no API key. Run \`${cliInvocation()} login\` first.`);
+
+  const positional = commandArgs.filter((value) => !value.startsWith("-"));
+  const runId = args.value("--run", positional[0] || "");
+  const integrationId = args.value("--integration", positional[1] || "");
+  if (!runId || !integrationId) {
+    throw new Error(
+      "usage: watch <run-id> <integration-id>  (both are shown by `preman status`)"
+    );
+  }
+
+  const seen = new Set();
+  const deadline = Date.now() + 15 * 60 * 1000;
+  while (Date.now() < deadline) {
+    const result = await callBackendJson(
+      args,
+      "GET",
+      `/integrations/github/${integrationId}/simulations/${runId}`,
+      { token }
+    );
+    if (!result.ok) throw new Error(`could not read run: ${result.status_code} ${result.detail || ""}`);
+
+    for (const step of result.steps || []) {
+      const key = `${step.key}:${step.status}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const mark = step.status === "succeeded" ? "✓" : step.status === "failed" ? "✗" : "·";
+      process.stdout.write(`  ${mark} ${String(step.key || "").padEnd(14)} ${step.message || ""}\n`);
+    }
+
+    if (TERMINAL_STATUSES.has(String(result.status || "").toLowerCase())) {
+      const verdict = result.summary?.verdict || result.status;
+      process.stdout.write(`\nRun ${result.status}: ${verdict}\n`);
+      return result;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error("stopped watching after 15 minutes; the run is still in progress.");
+}

package/bin/changed.js

@@ -0,0 +1,175 @@
+/**
+ * Which files a push actually touches.
+ *
+ * Git hands a pre-push hook one line per ref on stdin —
+ * `<local ref> <local sha> <remote ref> <remote sha>` — which is the only
+ * authoritative statement of what is about to leave the machine. Everything
+ * else (diffing against HEAD, against a guessed upstream) is a guess that goes
+ * wrong on exactly the pushes that matter: a first push of a new branch, an
+ * amend, a force push.
+ *
+ * Reading it is best-effort by design. If stdin is absent, empty, or malformed,
+ * we fall back rather than fail, because a hook that cannot decide what changed
+ * must still let the push through.
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+// Git's "this ref does not exist yet" sentinel, in both SHA-1 and SHA-256 form.
+const NULL_SHAS = new Set(["0".repeat(40), "0".repeat(64)]);
+
+// A push of a brand-new branch has no remote counterpart to diff against, so
+// walking its full history could mean scanning the entire repository. Cap it.
+const NEW_BRANCH_DEPTH = 50;
+
+const CODE_EXTENSIONS = new Set([
+  ".py", ".js", ".ts", ".mjs", ".cjs", ".tsx", ".jsx", ".go", ".rb", ".java", ".php", ".cs", ".rs",
+]);
+
+const SPEC_NAMES = new Set([
+  "openapi.json", "openapi.yaml", "openapi.yml",
+  "swagger.json", "swagger.yaml", "swagger.yml",
+]);
+
+function git(cwdArgs, { cwd } = {}) {
+  const result = spawnSync("git", cwdArgs, { encoding: "utf8", cwd, maxBuffer: 32 * 1024 * 1024 });
+  if (result.status !== 0) return null;
+  return String(result.stdout || "");
+}
+
+export function repoRoot() {
+  const out = git(["rev-parse", "--show-toplevel"]);
+  return out ? out.trim() : null;
+}
+
+/** Parse git's pre-push stdin payload into the ref pairs being pushed. */
+export function parsePushRefs(raw) {
+  return String(raw || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [localRef, localSha, remoteRef, remoteSha] = line.split(/\s+/);
+      return { localRef, localSha, remoteRef, remoteSha };
+    })
+    .filter((ref) => ref.localSha && !NULL_SHAS.has(ref.localSha));
+}
+
+/** Read git's stdin payload without hanging when the hook was run by hand. */
+export function readPushRefsFromStdin() {
+  // A TTY means a human typed the command, so there is no ref payload coming
+  // and a blocking read would hang the terminal.
+  if (process.stdin.isTTY) return [];
+  try {
+    return parsePushRefs(readFileSync(0, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+function diffNames(range, cwd) {
+  const out = git(["diff", "--name-only", "--diff-filter=ACMR", range], { cwd });
+  if (out === null) return null;
+  return out.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * Files touched by the last `depth` commits reachable from `sha`.
+ *
+ * A new branch has no remote counterpart, and the obvious `sha~N..sha` range
+ * fails outright when the branch is younger than N commits -- which is most
+ * new branches. Walking the log bounds the work the same way without needing
+ * the ancestor to exist.
+ */
+function logNames(sha, depth, cwd) {
+  const out = git(
+    ["log", "--format=", "--name-only", "--diff-filter=ACMR", `-n${depth}`, sha],
+    { cwd }
+  );
+  if (out === null) return null;
+  return out.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * The files this push introduces, relative to the repo root.
+ *
+ * Uncommitted work is deliberately excluded: a push ships commits, so testing
+ * the dirty working tree would report on code the teammate pulling this branch
+ * will never receive.
+ */
+export function changedFilesForPush(refs, { cwd } = {}) {
+  const root = cwd || repoRoot();
+  if (!root) return { files: [], reason: "not_a_git_repository" };
+
+  const names = new Set();
+  let reason = null;
+
+  for (const ref of refs) {
+    const isNewBranch = !ref.remoteSha || NULL_SHAS.has(ref.remoteSha);
+    // Never fall back to a bare `git diff <sha>`: that compares the working
+    // tree, so a clean checkout reports nothing at all and a dirty one reports
+    // edits this push does not carry.
+    let found;
+    if (isNewBranch) {
+      found = logNames(ref.localSha, NEW_BRANCH_DEPTH, root);
+      reason = "new_branch_bounded_history";
+    } else {
+      found = diffNames(`${ref.remoteSha}..${ref.localSha}`, root);
+    }
+    for (const name of found ?? []) names.add(name);
+  }
+
+  if (!refs.length) {
+    // Run by hand rather than by git: compare against the tracked upstream.
+    const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], { cwd: root });
+    const fallback = upstream ? diffNames(`${upstream.trim()}..HEAD`, root) : null;
+    for (const name of fallback ?? []) names.add(name);
+    reason = upstream ? "upstream_diff" : "no_refs_no_upstream";
+  }
+
+  return { files: [...names], reason, root };
+}
+
+/** Only files a scanner could find an endpoint in. */
+export function isScannable(relPath) {
+  const base = path.basename(relPath).toLowerCase();
+  if (SPEC_NAMES.has(base)) return true;
+  return CODE_EXTENSIONS.has(path.extname(relPath).toLowerCase());
+}
+
+/**
+ * Read the pushed files' contents for the backend to scan.
+ *
+ * Reads from the working tree rather than the commit. They agree on the
+ * overwhelmingly common push-what-you-committed path, and when they disagree
+ * the working tree is what the developer's running dev server is serving —
+ * which is what the plan is about to be tested against.
+ */
+export function readChangedFiles(files, { root, maxFiles = 300, maxBytes = 512 * 1024 } = {}) {
+  const out = [];
+  let skipped = 0;
+
+  for (const rel of files) {
+    if (out.length >= maxFiles) {
+      skipped += 1;
+      continue;
+    }
+    if (!isScannable(rel)) continue;
+    try {
+      const content = readFileSync(path.join(root, rel), "utf8");
+      if (Buffer.byteLength(content, "utf8") > maxBytes) {
+        skipped += 1;
+        continue;
+      }
+      out.push({ path: rel, content });
+    } catch {
+      // Deleted in the working tree, or unreadable. Either way there is nothing
+      // to scan, and the diff still reports the endpoint as removed.
+      skipped += 1;
+    }
+  }
+
+  return { files: out, skipped };
+}

package/bin/cli.js

@@ -26,8 +26,14 @@ import {
   slackCommand,
 } from "./integrations.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
+import { STATUS_HELP, statusCommand } from "./status.js";
+import { HOOK_HELP, hookCommand } from "./hook.js";
+import { VERIFY_HELP, verifyCommand } from "./verify.js";
+import { DESKTOP_HELP, installDesktopCommand } from "./desktop.js";
+import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
 import {
   CREDENTIALS_FILE,
+  cliInvocation,
   DEFAULT_BACKEND,
   DEFAULT_FRONTEND,
   authenticateTerminal,
@@ -58,24 +64,45 @@ function hasFlag(name) {
 }
 
 function printHelp() {
+  // Say "preman x" only to people who can actually run it; everyone else gets
+  // the form that works from a bare npm install.
+  const cli = cliInvocation();
+  // Padded here rather than hand-aligned: the invocation prefix is 6 characters
+  // for a global install and 38 for npm exec, so a fixed layout is wrong for
+  // one of them.
+  const usage = [
+    ["status", "Healthy / failing / recently fixed endpoints"],
+    ["verify [options]", "Test endpoints against your local app"],
+    ["hook install|uninstall|status", "Manage the git pre-push hook"],
+    ["doctor", "Diagnose credentials, backend, target, integrations"],
+    ["install-desktop", "Download and install the PreMan desktop app"],
+    ["onboard", "Sign in, then connect agent, GitHub, AWS, Slack"],
+    ["connect [options]", "Pick a coding agent and connect it"],
+    ["aws | github | slack", "Connect one integration on its own"],
+    ["login [--browser]", "Create/login to PreMan from the terminal"],
+    ["logout", "Delete stored CLI credentials"],
+    ["watch <run> <integration>", "Follow a push simulation live"],
+    ["install [options]", "Install PreMan into Cursor MCP config"],
+    ["", "Start the PreMan MCP server"],
+    ["link|tools|run ...", "Drive a published hosted MCP"],
+    ["endpoints list|discover|setup ...", "Discover, list, and set up API endpoints"],
+    ["test <id> [--scenario ...] [--stress]", "Generate + run tests for an endpoint"],
+  ];
+  const width = Math.max(...usage.map(([command]) => `${cli} ${command}`.trimEnd().length));
+  const usageLines = usage
+    .map(([command, blurb]) => `  ${`${cli} ${command}`.trimEnd().padEnd(width)}  ${blurb}`)
+    .join("\n");
+
   process.stdout.write(`PreMan MCP
 
 Usage:
-  preman onboard                                     Sign in, then connect agent, GitHub, AWS, Slack
-  preman connect [options]                           Pick a coding agent and connect it
-  preman aws | github | slack                        Connect one integration on its own
-  npm exec -y premanmcp@latest -- login              Create/login to PreMan from the terminal
-  npm exec -y premanmcp@latest -- install [options]  Install PreMan into Cursor MCP config
-  npm exec -y premanmcp@latest --                    Start the PreMan MCP server
-  preman link|tools|run ...                          Drive a published hosted MCP
-  preman endpoints list|discover|setup ...           Discover, list, and set up API endpoints
-  preman test <id> [--scenario ...] [--stress]       Generate + run tests for an endpoint
-${INTEGRATIONS_HELP}${CONNECT_HELP}${ENDPOINTS_HELP}${TEST_HELP}
+${usageLines}
+${INTEGRATIONS_HELP}${CONNECT_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
 
-Install options (Cursor only — prefer 'preman connect'):
+Install options (Cursor only — prefer '${cli} connect'):
   --api-key <key>       PreMan API key. If omitted, stored CLI credentials are used
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
   --frontend <url>      PreMan frontend URL. Defaults to ${DEFAULT_FRONTEND}
@@ -87,13 +114,17 @@ Install options (Cursor only — prefer 'preman connect'):
 
 Examples:
   npm exec -y premanmcp@latest -- connect
-  preman connect --agent claude-code
-  npm exec -y premanmcp@latest -- login
+  ${cli} connect --agent claude-code
+  ${cli} login
   npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
 ${HOSTED_HELP}`);
 }
 
 async function loginCommand() {
+  if (hasFlag("--browser")) {
+    await loginBrowser(cliArgs);
+    return;
+  }
   const creds = await authenticateTerminal(cliArgs);
   process.stdout.write(`PreMan account ready.
 
@@ -103,7 +134,7 @@ API key: ${creds.api_key}
 Saved to: ${CREDENTIALS_FILE}
 
 You can now run:
-  preman connect
+  ${cli} connect
 `);
 }
 
@@ -138,12 +169,12 @@ Server name: ${serverName}
 Backend: ${serverConfig.env.PREMAN_BACKEND}
 
 Next steps:
-1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : "Run npm exec -y premanmcp@latest -- login to create/connect your account and generate an API key."}
+1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : "Run ${cli} login to create/connect your account and generate an API key."}
 2. Restart Cursor or toggle the PreMan MCP server off/on.
 3. In your API repo, ask your coding agent:
    "Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet."
 
-Tip: 'preman connect' also supports Claude Code and Codex, and links the agent to your account.
+Tip: '${cli} connect' also supports Claude Code and Codex, and links the agent to your account.
 `);
 }
 
@@ -177,6 +208,20 @@ function startServer() {
 async function main() {
   if (command === "login") {
     await loginCommand();
+  } else if (command === "status") {
+    await statusCommand(commandArgs);
+  } else if (command === "verify") {
+    await verifyCommand(commandArgs);
+  } else if (command === "hook") {
+    await hookCommand(commandArgs);
+  } else if (command === "logout") {
+    await logoutCommand();
+  } else if (command === "doctor") {
+    await doctorCommand(commandArgs);
+  } else if (command === "watch") {
+    await watchCommand(commandArgs);
+  } else if (command === "install-desktop") {
+    await installDesktopCommand(commandArgs);
   } else if (command === "connect") {
     await connectCommand(commandArgs);
   } else if (command === "onboard" || command === "setup") {

package/bin/connect.js

@@ -22,8 +22,11 @@ import {
   backendUrl,
   buildServerConfig,
   callBackendJson,
+  cliInvocation,
   frontendUrl,
   hasKeyAvailable,
+  LAUNCHER_ARGS,
+  LAUNCHER_COMMAND,
   makeArgs,
   promptSecret,
   promptText,
@@ -271,8 +274,13 @@ export function renderAllAgentSnippets(args, serverName, { projectInstall = fals
     PREMAN_BACKEND: backendUrl(args),
     PREMAN_FRONTEND: frontendUrl(args),
   };
-  const serverConfig = { command: "npx", args: ["-y", "premanmcp@latest"], env };
-  
+  const serverConfig = {
+    command: LAUNCHER_COMMAND,
+    args: [...LAUNCHER_ARGS],
+    env,
+  };
+
+
   return AGENTS.map((agent) => {
     // Adjust hint based on projectInstall, matching verifyWrittenConfig logic
     let hint = agent.snippetHint;
@@ -318,8 +326,11 @@ export function verifyWrittenConfig(agent, { serverName, written }) {
       if (!block) {
         return { status: "mismatch", detail: `no [mcp_servers.${serverName}] block in ${written.path}` };
       }
-      if (!block.some((line) => line.trim() === 'command = "npx"')) {
-        return { status: "mismatch", detail: `${written.path} does not launch npx` };
+      if (!block.some((line) => line.trim() === `command = "${LAUNCHER_COMMAND}"`)) {
+        return {
+          status: "mismatch",
+          detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
+        };
       }
       return { status: "verified" };
     }
@@ -335,8 +346,11 @@ export function verifyWrittenConfig(agent, { serverName, written }) {
 
     const entry = readJsonFile(written.path).mcpServers?.[serverName];
     if (!entry) return { status: "mismatch", detail: `${serverName} is missing from ${written.path}` };
-    if (entry.command !== "npx") {
-      return { status: "mismatch", detail: `${written.path} does not launch npx` };
+    if (entry.command !== LAUNCHER_COMMAND) {
+      return {
+        status: "mismatch",
+        detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
+      };
     }
     return { status: "verified" };
   } catch (error) {
@@ -401,11 +415,21 @@ async function captureDispatchCredential(args, agent, apiKey) {
 
   if (!secret) {
     if (!process.stdin.isTTY) return;
+    // Framed as the expected step rather than an optional aside. Without it
+    // PreMan can only suggest fixes; with it, it can run them. Presenting it as
+    // "optional, press Enter to skip" meant almost everyone skipped the thing
+    // that makes the product act rather than advise.
     process.stdout.write(
-      `\nOptional: paste a ${agent.dispatch.credential} so PreMan can start ${agent.label} runs for you.\n`
+      `\nLet PreMan start ${agent.label} runs for you — it can then apply fixes and\n` +
+        `run checks on a schedule instead of only telling you what to do.\n`
     );
-    secret = await promptSecret("(Enter to skip): ");
-    if (!secret) return;
+    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to set up later): `);
+    if (!secret) {
+      process.stdout.write(
+        `Skipped. Run '${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
+      );
+      return;
+    }
     if (agent.dispatch.needsRoutine && !routineId) {
       routineId = await promptText("Routine id or URL: ");
     }