flowsprite 0.1.0 → 0.1.4

package/dist/cli.js

@@ -1,14 +1,17 @@
 import { homedir } from "node:os";
 import { parseArgs } from "node:util";
-import { credentialsPath, deleteCredential, readCredentials, resolveToken, writeCredential, } from "./credentials.js";
-import { formatDoctor, MIN_NODE_MAJOR, nodeMajor } from "./doctor.js";
+import { clearPendingLogin, credentialsPath, deleteCredential, readCredentials, readPendingLogin, resolveToken, writeCredential, writePendingLogin, } from "./credentials.js";
+import { doctorOk, formatDoctor, MIN_NODE_MAJOR, nodeMajor } from "./doctor.js";
 import { parseEndpoint } from "./endpoint.js";
-import { deviceCodeLogin } from "./login.js";
+import { deviceCodeLogin, ghCliLogin } from "./login.js";
 import { createMcpClient, toolJson } from "./mcpClient.js";
 import { jsonConfigHasServer, McpConfigError, SERVER_NAME, tomlConfigHasServer, upsertJsonConfig, } from "./mcpConfig.js";
 import { CLIENTS, commandFor, configPathFor, isClientId, planInstall, renderSnippet, TOKEN_PLACEHOLDER, } from "./mcpInstall.js";
-import { redact } from "./redact.js";
-import { asArray, asObject, planBindArgs, planNextStep, rungConnectionIds, runLinkStep, } from "./setup.js";
+import { SAME_ACCOUNT_NOTE } from "./messages.js";
+import { printable, redact } from "./redact.js";
+import { asArray, asObject, browserWaitNotice, createStepTracker, planBindArgs, planNextStep, rerunHint, rungConnectionIds, runLinkStep, stepOfRung, waitForRepository, } from "./setup.js";
+import { MAX_EXPIRES_IN_SECONDS } from "./ghLogin.js";
+import { doorRefusalSentence, FROM_SF_CLI_EXCLUSIVE, parseSfAuthUrl, projectDoorResult, scrubForceUrls, SF_ALIAS_RE, SF_ALIAS_RULE, SF_TOO_OLD_REMEDY, sfLoginLine, sfRelogin, sfRemedy, } from "./sfCli.js";
 import { renderStatus } from "./status.js";
 import { USAGE } from "./usage.js";
 /**
@@ -25,14 +28,18 @@ import { USAGE } from "./usage.js";
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_USAGE = 2;
-const OPTIONS = {
+/** The parser's option table — exported so usage.test.ts can prove USAGE names every flag. */
+export const OPTIONS = {
     endpoint: { type: "string" },
     json: { type: "boolean" },
     token: { type: "string" },
     save: { type: "boolean" },
     "no-open": { type: "boolean" },
+    workspace: { type: "string" },
+    "no-gh": { type: "boolean" },
     sandbox: { type: "boolean" },
     "my-domain": { type: "string" },
+    "from-sf-cli": { type: "string" },
     connection: { type: "string" },
     installation: { type: "string" },
     repo: { type: "string" },
@@ -73,6 +80,12 @@ export async function main(argv, deps) {
     if (!COMMANDS.has(command)) {
         return usageError(deps.writer, `Unknown command '${command}'.`);
     }
+    // `--from-sf-cli` is accepted by exactly one command. Refused elsewhere
+    // rather than ignored: FLO-514 found that a flag `setup` accepts and
+    // silently drops is how a person's intent goes missing.
+    if (typeof values["from-sf-cli"] === "string" && !(command === "connect" && positionals[1] === "salesforce")) {
+        return usageError(deps.writer, "--from-sf-cli belongs to `connect salesforce`: flowsprite connect salesforce --from-sf-cli <alias>.");
+    }
     const endpoint = parseEndpoint({
         flag: typeof values.endpoint === "string" ? values.endpoint : undefined,
         env: deps.env.FLOWSPRITE_ENDPOINT,
@@ -131,6 +144,13 @@ function clientFor(deps, origin, values) {
 }
 // ------------------------------------------------------------------- commands
 async function cmdLogin(deps, origin, values) {
+    // `--workspace` is the one value the gh road sends that a person typed.
+    // Refused empty HERE, before any spawn or request, rather than sent for the
+    // door to refuse: the door's `invalid_argument` costs a round trip to say so.
+    const workspaceFlag = typeof values.workspace === "string" ? values.workspace.trim() : null;
+    if (workspaceFlag !== null && workspaceFlag.length === 0) {
+        return usageError(deps.writer, "--workspace needs a name: flowsprite login --workspace <name>.");
+    }
     // A token handed in on the command line or the environment SKIPS the device
     // loop entirely — there is nothing to approve. It is not stored unless --save
     // is given, so a one-off token in a CI job leaves nothing behind.
@@ -149,14 +169,30 @@ async function cmdLogin(deps, origin, values) {
         }
         return EXIT_OK;
     }
-    const result = await deviceCodeLogin({
+    // ONE deps object for both roads, so the 409 road's browser tail inherits
+    // `--no-open` (and an absent opener) exactly as the device-code road does.
+    const loginDeps = {
         origin,
         fetch: deps.fetch,
         sleep: deps.sleep,
         writer: deps.writer,
         version: deps.version,
         ...(values["no-open"] === true || deps.openUrl === undefined ? {} : { openUrl: deps.openUrl }),
-    });
+        ...(deps.progress === undefined ? {} : { progress: deps.progress }),
+        pending: pendingLoginPort(deps, origin),
+    };
+    // FLO-517: the gh road first, unless opted out. Null means it fell to the
+    // browser login at its own start, having said why in one line.
+    const viaGh = values["no-gh"] === true
+        ? null
+        : await ghCliLogin({
+            ...loginDeps,
+            isOnPath: deps.isOnPath,
+            spawn: deps.spawn,
+            ...(deps.ask === undefined ? {} : { ask: deps.ask }),
+            workspaceName: workspaceFlag,
+        });
+    const result = viaGh ?? (await deviceCodeLogin(loginDeps));
     if (!result.ok) {
         deps.writer.err(result.message);
         return EXIT_FAILED;
@@ -169,7 +205,9 @@ async function cmdLogin(deps, origin, values) {
         savedAt: deps.now(),
     };
     // The token is NOT in this sentence, and the writer would redact it anyway.
-    const who = `Logged in to ${origin} as ${result.userId} in workspace ${result.orgId}`;
+    // C4: the email and workspace name are DISPLAY ONLY — scrubbed in login.ts,
+    // and never in `cred` above, so they are never stored.
+    const who = `Logged in to ${origin} as ${result.userEmail ?? result.userId} in workspace ${result.orgName ?? result.orgId}`;
     try {
         writeCredential(deps.env, origin, cred, deps.home);
     }
@@ -192,37 +230,90 @@ async function cmdLogin(deps, origin, values) {
         return EXIT_FAILED;
     }
     deps.writer.out(who);
+    deps.writer.out(SAME_ACCOUNT_NOTE);
     return EXIT_OK;
 }
+/**
+ * C3 — the pending device login for THIS origin, kept in `pending-login.json`
+ * beside the credential store (0600, see `credentials.ts`). The clock lives here
+ * so `login.ts` stays clock-free: it is handed seconds LEFT and hands back the
+ * payload's own TTL.
+ */
+function pendingLoginPort(deps, origin) {
+    return {
+        load: () => {
+            const saved = readPendingLogin(deps.env, origin, deps.now(), deps.home);
+            if (saved === null)
+                return null;
+            return {
+                deviceCode: saved.deviceCode,
+                ...(saved.userCode === null || saved.openTarget === null
+                    ? {}
+                    : { userCode: saved.userCode, openTarget: saved.openTarget }),
+                expiresIn: Math.ceil((saved.expiresAtMs - deps.now()) / 1000),
+                interval: saved.interval,
+            };
+        },
+        save: (p) => writePendingLogin(deps.env, {
+            origin,
+            deviceCode: p.deviceCode,
+            userCode: p.userCode ?? null,
+            openTarget: p.openTarget ?? null,
+            expiresAtMs: deps.now() + p.expiresIn * 1000,
+            savedAtMs: deps.now(),
+            interval: p.interval,
+        }, deps.home),
+        clear: (deviceCode) => clearPendingLogin(deps.env, origin, deps.home, deviceCode),
+    };
+}
 function cmdLogout(deps, origin) {
+    // C3: a half-finished login goes too, so the next `login` starts fresh. Best
+    // effort: an undeletable file must not turn a logout into a crash. No device
+    // code is named (G2): logout drops whatever is pending for this origin.
+    try {
+        clearPendingLogin(deps.env, origin, deps.home);
+    }
+    catch {
+        // The credential removal below is what logout promises; this is housekeeping.
+    }
     const removed = deleteCredential(deps.env, origin, deps.home);
     deps.writer.out(removed ? `Logged out of ${origin}.` : `There was no stored credential for ${origin}.`);
     return EXIT_OK;
 }
 async function cmdDoctor(deps, origin, values) {
     const stored = readCredentials(deps.env, deps.home)[origin];
-    let reachable = false;
-    let detail = "no credential, so reachability was not tested";
-    const built = clientForQuiet(deps, origin, values, stored?.token);
-    if (built !== null) {
-        const probe = await built.initialize();
-        reachable = probe.ok;
-        // `initialize` is the reachability probe (DM2). An `unauthorized` answer
-        // still proves the endpoint is THERE — it is reported as its own line rather
-        // than folded into "unreachable", which would send someone to check DNS.
-        detail = probe.ok ? "reachable" : `${probe.kind}: ${probe.message}`;
-    }
-    const report = {
+    const token = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: stored?.token,
+    });
+    // N7: the endpoint is probed WITH OR WITHOUT a credential — `initialize` with
+    // an empty bearer. HEALTHY is exactly two answers (G8): a successful
+    // `initialize`, or a 401 (`unauthorized` — the auth layer answered, the
+    // credential is the problem or is absent). Anything else — no answer, a body
+    // that is not JSON-RPC, a JSON-RPC error, a tool error — FAILS the endpoint.
+    const probe = await createMcpClient({ origin, token: token?.token ?? "", fetch: deps.fetch, version: deps.version }).initialize();
+    const unauthorized = !probe.ok && probe.kind === "unauthorized";
+    const reachable = probe.ok || unauthorized;
+    const detail = probe.ok || (token !== null && unauthorized)
+        ? "reachable"
+        : unauthorized
+            ? "reachable (it answered HTTP 401 to a request with no credential, as it should)"
+            : `${probe.kind}: ${probe.message}`;
+    const checks = {
         nodeVersion: deps.nodeVersion,
         nodeOk: nodeMajor(deps.nodeVersion) >= MIN_NODE_MAJOR,
         endpoint: origin,
         endpointReachable: reachable,
         endpointDetail: detail,
-        hasCredential: stored !== undefined,
+        hasCredential: token !== null,
+        credentialSource: token?.source ?? null,
+        credentialRefused: token !== null && unauthorized,
         credentialsPath: credentialsPath(deps.env, deps.home),
         sfOnPath: deps.isOnPath("sf"),
         ghOnPath: deps.isOnPath("gh"),
     };
+    const report = { ...checks, ok: doctorOk(checks) };
     if (values.json === true) {
         deps.writer.out(JSON.stringify(report, null, 2));
     }
@@ -230,18 +321,8 @@ async function cmdDoctor(deps, origin, values) {
         for (const line of formatDoctor(report))
             deps.writer.out(line);
     }
-    return report.nodeOk ? EXIT_OK : EXIT_FAILED;
-}
-/** Like `clientFor` but silent and optional — doctor reports absence, it does not refuse. */
-function clientForQuiet(deps, origin, values, storedToken) {
-    const token = resolveToken({
-        flag: typeof values.token === "string" ? values.token : undefined,
-        env: deps.env.FLOWSPRITE_TOKEN,
-        stored: storedToken,
-    });
-    if (token === null)
-        return null;
-    return createMcpClient({ origin, token: token.token, fetch: deps.fetch, version: deps.version });
+    // N16: exit 1 iff any check FAILs (see `doctorOk`); sf/gh are notes only.
+    return report.ok ? EXIT_OK : EXIT_FAILED;
 }
 async function fetchStatus(deps, client) {
     const result = await client.callTool("setup_status", {});
@@ -270,42 +351,287 @@ async function cmdStatus(deps, origin, values) {
     return EXIT_OK;
 }
 function setupDeps(deps, client) {
-    return { client, writer: deps.writer, sleep: deps.sleep, now: deps.now };
+    return {
+        client,
+        writer: deps.writer,
+        sleep: deps.sleep,
+        now: deps.now,
+        // C8: the setup-link countdown shares the login's status line — a terminal only.
+        ...(deps.progress === undefined ? {} : { progress: deps.progress }),
+    };
 }
 async function cmdConnect(deps, origin, values, which) {
     if (which !== "salesforce" && which !== "github") {
         return usageError(deps.writer, "connect takes 'salesforce' or 'github'.");
     }
+    // The `sf`-CLI door (FLO-515): a branch chosen BEFORE the link is minted,
+    // not a change to the link step. The alias was already routed here by `main`.
+    if (which === "salesforce" && typeof values["from-sf-cli"] === "string") {
+        return await connectFromSfCli(deps, origin, values, values["from-sf-cli"]);
+    }
     const built = clientFor(deps, origin, values);
     if (!built.ok)
         return EXIT_FAILED;
     const tool = which === "salesforce" ? "setup_connect_salesforce" : "setup_connect_github";
-    const stepKind = which === "salesforce" ? "connect_salesforce" : "connect_github";
-    // ponytail: both alternative doors are absent here, and both plug in at THIS
-    // call, as a branch chosen before the link is minted — not as a change to the
-    // link step itself. Salesforce: the `sf`-CLI handoff (card B4, Blocked), which
-    // would reuse a `sf org login` session instead of a browser link. GitHub: the
-    // gh-token door (card A3, blocked), which would use a token the person already
-    // holds instead of an app install.
-    const args = which === "salesforce"
-        ? {
-            ...(values.sandbox === true ? { env: "sandbox" } : {}),
-            ...(typeof values["my-domain"] === "string" ? { myDomain: values["my-domain"] } : {}),
+    // ponytail: the GitHub alternative door is absent here and plugs in at THIS
+    // call, as a branch chosen before the link is minted — the gh-token door
+    // (card A3, blocked), which would use a token the person already holds
+    // instead of an app install. The Salesforce one is `connectFromSfCli` above.
+    const args = which === "salesforce" ? salesforceLinkArgs(values) : {};
+    // The pre-mint snapshot is read HERE (it was read inside the link step before
+    // N1) so the used-but-no-new-id outcome can compare "connected" before and
+    // after. `done` still means a NEW connection or installation.
+    const before = await fetchStatus(deps, built.client);
+    if (!before.ok)
+        return EXIT_FAILED;
+    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, which, before.payload);
+    return await settleLinkOutcome(deps, built.client, outcome, which, before.payload);
+}
+/** `workspace.<provider>.connected === true` in a `setup_status` payload — strictly true. */
+function providerConnected(status, provider) {
+    return asObject(asObject(asObject(status)?.workspace)?.[provider])?.connected === true;
+}
+/**
+ * Card eecc9d6f N1 — a link that was USED but produced no NEW id. The success
+ * sentence is NEUTRAL (G7): "is connected" is what the read shows; whether a row
+ * was refreshed or newly made is not something this read can tell. Re-authorizing
+ * a connection Flowsprite already had a row for refreshes that row, so no new id
+ * appears even when the person did exactly the right thing. The rule: the step
+ * SUCCEEDED iff the provider was NOT connected in the pre-mint snapshot and IS
+ * connected now — the link changed the answer. (Connected BEFORE as well is the
+ * second-org case, which stays the old "used, but nothing new" failure: nothing
+ * shows this link did anything.) Applied to both providers: the GitHub link step
+ * shares this exact outcome path.
+ */
+async function settleLinkOutcome(deps, client, outcome, provider, before) {
+    if ((outcome.kind === "expired" || outcome.kind === "timeout") && outcome.used && !providerConnected(before, provider)) {
+        const read = await client.callTool("setup_status", {});
+        if (read.ok && providerConnected(toolJson(read), provider)) {
+            deps.writer.out(provider === "salesforce"
+                ? "Salesforce is connected."
+                : "GitHub is connected.");
+            return EXIT_OK;
+        }
+        if (read.ok) {
+            deps.writer.err(provider === "salesforce"
+                ? "The link was opened, but Salesforce is still not connected to this workspace — the Salesforce sign-in did not complete a connection. Run the command again for a fresh link."
+                : "The link was opened, but GitHub is still not connected to this workspace — the app install did not complete. Run the command again for a fresh link.");
+            return EXIT_FAILED;
+        }
+    }
+    return reportLinkOutcome(deps.writer, outcome, provider);
+}
+/**
+ * `flowsprite connect salesforce --from-sf-cli <alias>` (FLO-515): read the
+ * Salesforce CLI's own login for that alias and hand it to the server door
+ * `setup_connect_salesforce_cli`, so the credential crosses inside THIS process
+ * — spawn stdout → parser → tools/call arguments — and never enters a chat, a
+ * transcript or this CLI's output. Why that matters: an agent harness redacted
+ * `result.sfdxAuthUrl` before its model could relay it (measured 2026-09-17,
+ * Claude Code), and the writer's redactor covers `fp_` tokens only, so the URL
+ * is scoped to the spawn-to-call span below and appears in NO string. Every
+ * printed text that did not originate in this CLI's constants goes through
+ * `scrubForceUrls` as defence in depth. The acceptance oracle censuses this
+ * function's source for `fs` / `console` identifiers: the writer and the
+ * tools/call body are its only sinks.
+ *
+ * WHICH COMMAND, and why it changed (card 263cefa5, 2026-09-20): ONE spawn of
+ * `sf org auth show-sfdx-auth-url --target-org <alias> --json`, whose stdout
+ * under `--json` is `{status, result:{sfdxAuthUrl}, warnings}` — no
+ * accessToken, no password, no clientId. The command's own "this exposes an
+ * SFDX Auth URL" warning lands BOTH in that `warnings` array and on stderr
+ * (sf-plugins-core `toSuccessJson`/`warn`, measured against 12.2.6), and this
+ * CLI prints neither. What IS read off that envelope: `status` (to tell a
+ * success from an error), the identifier-shaped `name` on a non-zero one (the
+ * error CLASS, printed; never its free text), and `result.sfdxAuthUrl` — the
+ * only one of the three that is a credential, and it is read into one scope
+ * and never printed. FLO-515 read the login from `sf org display --verbose --json`,
+ * and sf 2.147.0 (published 2026-07-31) bundles a @salesforce/plugin-org that
+ * redacts `sfdxAuthUrl` there behind a placeholder unless a
+ * documented-temporary env var is set — so on sf 2.150.6 a good web login was
+ * answered with the logout-then-login remedy (measured in UAT, 2026-09-20).
+ * The stable command ships in the same plugin version and needs no env var,
+ * which is why this door passes NO third argument to `deps.spawn` and overlays
+ * no environment on the child.
+ *
+ * Refusals BEFORE the network, in this order: the flag exclusivity (DM5), the
+ * alias rule (DM4), `sf` on PATH (DM3: install lines, never an auto-install),
+ * the stored credential, the spawn's own failure, an `sf` too old to have the
+ * command (263cefa5 DM2), sf's own non-zero exit (which is where a login with
+ * no refresh token lands: the command throws rather than answering with a url,
+ * so a JWT or access-token login is refused HERE and not by the url check
+ * below), then the envelope's shape (DM2: an empty-client or other-app url is
+ * refused here with the alias-bearing remedy rather than round-tripped to a
+ * server that would refuse it anyway).
+ */
+async function connectFromSfCli(deps, origin, values, alias) {
+    if (values.sandbox === true || typeof values["my-domain"] === "string") {
+        return usageError(deps.writer, FROM_SF_CLI_EXCLUSIVE);
+    }
+    if (!SF_ALIAS_RE.test(alias))
+        return usageError(deps.writer, SF_ALIAS_RULE);
+    // On Windows the npm install of sf is a `sf.cmd` shim, which node refuses to
+    // spawn without a shell (>= 20.12), so `isOnPath("sf")` reads FALSE for a
+    // person who has it (reasoned from Node's documented .cmd refusal, FLO-515
+    // fix round 1 — no Windows run exists in this repo's harness). There the
+    // PATH probe is skipped and the spawn itself is the probe.
+    const win32 = deps.platform === "win32";
+    if (!win32 && !deps.isOnPath("sf")) {
+        for (const line of sfRemedy(alias, deps.platform))
+            deps.writer.err(line);
+        return EXIT_USAGE;
+    }
+    const built = clientFor(deps, origin, values);
+    if (!built.ok)
+        return EXIT_FAILED;
+    // sf's stdout and stderr are NEVER printed: either can quote the URL.
+    // UNVERIFIED: the win32 arm — no Windows machine in this repo's harness. It
+    // runs sf through cmd.exe as ONE command string; that string is safe by
+    // construction because SF_ALIAS_RE (checked above) admits no quote, space or
+    // shell metacharacter, so the alias cannot end the command or start another.
+    const run = win32
+        ? await deps.spawn("cmd.exe", ["/d", "/s", "/c", "sf org auth show-sfdx-auth-url --target-org " + alias + " --json"])
+        : await deps.spawn("sf", ["org", "auth", "show-sfdx-auth-url", "--target-org", alias, "--json"]);
+    const spawnError = run.error !== undefined && run.error !== null;
+    // On win32 "sf is not installed" arrives two ways, both the install remedy
+    // the PATH probe gives elsewhere: cmd.exe itself could not start (a spawn
+    // `error`), or cmd.exe started and reported the command not recognized —
+    // its documented command-not-found ERRORLEVEL is 9009, so that STATUS is
+    // read as "no sf", never as "that org is not logged in". Reasoned from
+    // Windows' documented behaviour; UNVERIFIED on a real box like the rest of
+    // this branch.
+    if (win32 && (spawnError || run.status === 9009)) {
+        for (const line of sfRemedy(alias, "win32"))
+            deps.writer.err(line);
+        return EXIT_USAGE;
+    }
+    if (spawnError) {
+        deps.writer.err(`sf org auth show-sfdx-auth-url could not be run for '${alias}'. Is that org logged in? ${sfLoginLine(alias)}`);
+        return EXIT_FAILED;
+    }
+    const parsed = parseSfAuthUrl(run.stdout ?? "");
+    // THE RULE: exit 127 with NO JSON envelope on stdout is READ AS "this `sf`
+    // lacks the subcommand", i.e. it predates 2.147.0. That is an operational
+    // classification, not a proven cause: a missing subcommand is the only shape
+    // measured to produce it, on sf 2.127.2 (2026-09-20), in both its forms — a
+    // clean shell gives rc 127 with EMPTY stdout and "is not a sf command" on
+    // stderr, and the SAME run under `DEBUG=sf:*` gives rc 127 with ~2.5 KB
+    // (2509-2510 bytes across runs; a timestamp digit) of debug noise on stdout
+    // carrying zero `{` characters and absolute filesystem paths, a second
+    // reason never to print it. So the test is "did anything parse", not "was
+    // stdout empty" — fix round 1 F1: the empty-stdout form sent a debug shell
+    // down the logged-out remedy, this card's own defect class. Exit 127 that DOES carry an envelope is not this
+    // arm; it falls to the generic non-zero arm below and is named from its
+    // `name`. The remedy here is to update sf, never to log in again, so this
+    // sentence carries neither the login line nor sf's own stderr. It must sit
+    // above the generic non-zero arm, which would otherwise swallow it.
+    if (run.status === 127 && !parsed.ok && parsed.reason === "not_json") {
+        deps.writer.err(SF_TOO_OLD_REMEDY);
+        return EXIT_FAILED;
+    }
+    if (run.status !== 0) {
+        // sf's JSON error envelope names an error CLASS. `NamedOrgNotFoundError`
+        // for a logged-out alias at exit 2 is MEASURED (sf 2.127.2, via the shared
+        // `Flags.requiredOrg()` resolution). For a JWT or access-token login the
+        // command throws instead of answering with a url — so that login lands
+        // HERE rather than in the `no_url` arm below — and the card's NC-3 reads
+        // plugin-org 6.0.11 as throwing `error.noRefreshToken` there, i.e. a name
+        // such as `NoRefreshTokenError`; UNVERIFIED on this box, which has
+        // plugin-org 5.9.71 and no `org/auth` command at all. Nothing depends on
+        // the spelling: whatever identifier-shaped `name` arrives is printed, and
+        // its free text, `actions` and stderr never are.
+        const named = !parsed.ok && parsed.reason === "status" && parsed.message !== "";
+        const what = named ? `reported ${parsed.message}` : `failed for '${alias}'`;
+        deps.writer.err(`sf org auth show-sfdx-auth-url ${what} (exit ${run.status ?? "by signal"}). Is that org logged in? ${sfLoginLine(alias)}`);
+        return EXIT_FAILED;
+    }
+    if (!parsed.ok) {
+        switch (parsed.reason) {
+            case "not_json":
+                deps.writer.err(`sf org auth show-sfdx-auth-url did not return its JSON. ${sfLoginLine(alias)}`);
+                break;
+            case "status":
+                deps.writer.err(`sf org auth show-sfdx-auth-url reported ${parsed.message || "an error"}. ${sfLoginLine(alias)}`);
+                break;
+            default:
+                // `no_url`: no url in the envelope, a non-string one, another connected
+                // app's (`force://Other::…`) or an older auth file's empty client id
+                // (`force://:…`) — the server door would refuse every one of them.
+                deps.writer.err("That sf login cannot be handed over: only the Salesforce CLI's default connected app (PlatformCLI) " +
+                    `with a web login works. ${sfRelogin(alias)}`);
         }
-        : {};
-    const outcome = await runLinkStep(setupDeps(deps, built.client), tool, args, stepKind);
-    return reportLinkOutcome(deps.writer, outcome);
+        return EXIT_FAILED;
+    }
+    // The ONE place the URL leaves this process: exactly this key, nothing else.
+    const res = await built.client.callTool("setup_connect_salesforce_cli", { sfdxAuthUrl: parsed.sfdxAuthUrl });
+    if (!res.ok) {
+        switch (res.kind) {
+            case "tool_error":
+                // The door's own refusal sentence (or whatever the server said), scrubbed.
+                deps.writer.err(scrubForceUrls(res.message));
+                break;
+            case "rpc_error":
+                // A JSON-RPC error's message is the server's text: only its code is printed.
+                deps.writer.err(`Flowsprite's endpoint rejected the call${res.code === undefined ? "" : ` (JSON-RPC error ${res.code})`}. Run \`flowsprite doctor\`.`);
+                break;
+            default:
+                // `unauthorized` / `transport`: the client builds these sentences from
+                // its own URL, the HTTP status and an error NAME — no server text.
+                deps.writer.err(scrubForceUrls(res.message));
+        }
+        return EXIT_FAILED;
+    }
+    const doc = projectDoorResult(toolJson(res));
+    if (doc === null) {
+        deps.writer.err("Flowsprite sent an unexpected reply while connecting that Salesforce CLI login.");
+        return EXIT_FAILED;
+    }
+    if (values.json === true)
+        deps.writer.out(JSON.stringify(doc, null, 2));
+    if (!doc.ok) {
+        deps.writer.err(doorRefusalSentence(doc.code, alias));
+        return EXIT_FAILED;
+    }
+    if (values.json !== true) {
+        deps.writer.out(`Connected ${doc.orgName ?? doc.username} (${doc.envType}).`);
+        if (doc.reconnected)
+            deps.writer.out("That org was already connected to this workspace; its login was refreshed.");
+        deps.writer.out("Done.");
+    }
+    return EXIT_OK;
+}
+/**
+ * The `setup_connect_salesforce` arguments the flags ask for — ONE home, used by
+ * `connect salesforce` and by `setup`'s Salesforce rung, so a flag `setup`
+ * accepts cannot be one it silently ignores (FLO-514: `--my-domain` was).
+ */
+function salesforceLinkArgs(values) {
+    return {
+        ...(values.sandbox === true ? { env: "sandbox" } : {}),
+        ...(typeof values["my-domain"] === "string" ? { myDomain: values["my-domain"] } : {}),
+    };
 }
-function reportLinkOutcome(writer, outcome) {
+function reportLinkOutcome(writer, outcome, provider) {
+    const noun = provider === "github" ? "GitHub installation" : "Salesforce org";
     switch (outcome.kind) {
         case "done":
             writer.out("Done.");
             return EXIT_OK;
         case "expired":
-            writer.err("That setup link expired before it was used. Run the command again for a fresh one.");
-            return EXIT_FAILED;
         case "timeout":
-            writer.err("Gave up waiting after 10 minutes. The link may still work — finish it in the browser, then run `flowsprite status`.");
+            if (outcome.used) {
+                // The link was opened but no new id arrived: re-authorizing an org (or
+                // re-installing on an account) that is already connected refreshes the
+                // existing row and mints nothing new, so "expired" would misdescribe it.
+                writer.err(`The link was used, but no new ${noun} appeared in this workspace. ` +
+                    "If you signed in to one that was already connected, it was refreshed — run `flowsprite status`.");
+            }
+            else if (outcome.kind === "expired") {
+                writer.err("That setup link expired before it was used. Run the command again for a fresh one.");
+            }
+            else {
+                writer.err("Gave up waiting after 10 minutes. The link may still work — finish it in the browser, then run `flowsprite status`.");
+            }
             return EXIT_FAILED;
         default:
             writer.err(outcome.message);
@@ -352,13 +678,13 @@ async function cmdBind(deps, origin, values) {
     const built = clientFor(deps, origin, values);
     if (!built.ok)
         return EXIT_FAILED;
-    return await runBind(deps, values, built.client, null);
+    return await runBind(deps, origin, values, built.client, null);
 }
-async function runBind(deps, values, client, rung) {
-    const filled = await fillBindInput(deps, client, values, rung);
-    if (filled === null)
-        return EXIT_USAGE;
-    const plan = planBindArgs(filled);
+async function runBind(deps, origin, values, client, rung) {
+    const filled = await fillBindInput(deps, origin, client, values, rung);
+    if (!filled.ok)
+        return filled.rc;
+    const plan = planBindArgs(filled.input);
     if (!plan.ok) {
         // A ONE-LINE REMEDY, not the whole usage text. By the time we are here the
         // command line parsed fine and the workspace was read; dumping 39 lines of
@@ -379,8 +705,45 @@ async function runBind(deps, values, client, rung) {
         for (const line of textOf(result.content))
             deps.writer.out(line);
     }
+    // Only `setup` waits: its NEXT rung is the first sync, which refuses a
+    // repository that is still being created. The wait sits inside the bind step,
+    // before the ladder's next read, so FIX-F1's identity guard compares the
+    // payload AFTER the repository settled.
+    // ponytail: a bare `flowsprite bind` does not wait — it has no next step to
+    // protect; `flowsprite status` shows "(creating)". Wait there too if people
+    // chain `bind && sync` in scripts.
+    if (rung !== null && asObject(toolJson(result))?.bootstrapState === "creating") {
+        return await reportRepositoryWait(deps, values, client, String(filled.input.connection));
+    }
     return EXIT_OK;
 }
+async function reportRepositoryWait(deps, values, client, connectionId) {
+    // Progress is prose, so under --json it goes to stderr and stdout stays parseable.
+    const say = (line) => (values.json === true ? deps.writer.err(line) : deps.writer.out(line));
+    say("Waiting for GitHub to create the repository...");
+    const outcome = await waitForRepository(setupDeps(deps, client), connectionId);
+    switch (outcome.kind) {
+        case "ready":
+            say("Repository ready.");
+            return EXIT_OK;
+        case "gone":
+            return EXIT_OK;
+        case "failed":
+            // Scrubbed HERE as well as at the writer: the writer keeps newlines (a
+            // multi-line refusal or a --json document is meant to stay lines), but a
+            // stored error INTERPOLATED into one sentence must not forge a second line
+            // (FLO-511 F3 pins it).
+            deps.writer.err(`Creating the repository failed: ${printable(outcome.error)}`);
+            deps.writer.err("Run `flowsprite setup` again to choose another name, or pick an existing repository.");
+            return EXIT_FAILED;
+        case "timeout":
+            deps.writer.err("The repository is still being created. Run `flowsprite setup` again in a minute.");
+            return EXIT_FAILED;
+        default:
+            deps.writer.err(outcome.message);
+            return EXIT_FAILED;
+    }
+}
 /**
  * Fill in `--connection`, `--installation` and the repository when the workspace
  * leaves no choice, and ask when it does.
@@ -391,14 +754,16 @@ async function runBind(deps, values, client, rung) {
  * refuses — never guessed, because binding SUPERSEDES whatever that connection
  * was bound to before and switches off its data export.
  *
- * THE REPOSITORY IS PICKED THE SAME WAY, and that is what makes a bare
- * `flowsprite setup` able to pass this rung at all: `setup_status` already
- * carries each installation's repositories (FLO-496 AC6), so the ladder does not
- * have to ask the person for a flag it never told them they needed. `--create`
- * stays the non-interactive alternative for a workspace whose repos Flowsprite
- * has not listed.
+ * THE REPOSITORY DEFAULTS TO A NEW PRIVATE ONE (FLO-511, Noah 2026-09-17). A
+ * fresh GitHub installation has no repository list Flowsprite can show, so
+ * picking cannot be the default. Creating writes to the person's GitHub account,
+ * and the tool treats create + private as a consent decision, so it happens only
+ * after a yes at a prompt (or an explicit `--create`); without a prompt the
+ * command refuses and names the flag. Picking an existing repository is the "no"
+ * branch, and `--repo` is its non-interactive form.
  */
-async function fillBindInput(deps, client, values, rung) {
+async function fillBindInput(deps, origin, client, values, rung) {
+    const refuse = { ok: false, rc: EXIT_USAGE };
     const input = {
         connection: typeof values.connection === "string" ? values.connection : undefined,
         installation: typeof values.installation === "string" ? values.installation : undefined,
@@ -410,7 +775,7 @@ async function fillBindInput(deps, client, values, rung) {
         return status.ok ? status.payload : undefined;
     })();
     if (payload === undefined)
-        return null;
+        return refuse;
     const root = asObject(payload);
     const connections = asArray(root?.connections);
     const installations = asArray(root?.installations);
@@ -428,7 +793,7 @@ async function fillBindInput(deps, client, values, rung) {
     if (typeof input.connection === "string") {
         if (rung !== null && !rung.connectionIds.includes(input.connection)) {
             deps.writer.err(outOfRungRefusal(input.connection, rung));
-            return null;
+            return refuse;
         }
     }
     else {
@@ -437,7 +802,7 @@ async function fillBindInput(deps, client, values, rung) {
             `${String(c.displayName ?? "?")} [${String(c.envType ?? "?")}]`,
         ]));
         if (picked === null)
-            return null;
+            return refuse;
         input.connection = picked;
     }
     // ---- which GitHub installation ------------------------------------------
@@ -447,30 +812,70 @@ async function fillBindInput(deps, client, values, rung) {
             `@${String(i.accountLogin ?? "?")} [${String(i.accountType ?? "?")}]`,
         ]));
         if (picked === null)
-            return null;
+            return refuse;
         input.installation = picked;
     }
-    // ---- which repository ----------------------------------------------------
+    // ---- create a new repository, or pick an existing one -------------------
     if (typeof input.repo !== "string" && typeof input.create !== "string") {
-        const chosen = installations.find((i) => String(i.installationId ?? "") === String(input.installation));
+        const installationId = String(input.installation);
+        const chosen = installations.find((i) => String(i.installationId ?? "") === installationId);
+        const target = connections.find((c) => String(c.id ?? "") === String(input.connection));
+        const suggested = typeof target?.suggestedRepoName === "string" && target.suggestedRepoName.length > 0
+            ? target.suggestedRepoName
+            : null;
+        // Decided from setup_status BEFORE any call: a refusal's `kind` never
+        // reaches this client over HTTP, only its sentence.
+        if (chosen?.needsUserAuth === true) {
+            deps.writer.err(`GitHub needs a one-time sign-in before Flowsprite can create a repository on @${String(chosen.accountLogin ?? "?")}. ` +
+                `Open ${origin}/api/auth/github/user/start?installation_id=${installationId} in the browser where this workspace is open, ` +
+                "then run `flowsprite setup` again.");
+            deps.writer.err("To use a repository that already exists instead, pass --repo owner/name.");
+            return { ok: false, rc: EXIT_FAILED };
+        }
+        if (deps.ask === undefined) {
+            deps.writer.err("Flowsprite creates a new private repository here by default, and that needs a yes. " +
+                `Run \`flowsprite setup\` at a terminal, or pass --create ${suggested ?? "<name>"} ` +
+                "(or --repo owner/name to use an existing repository).");
+            return refuse;
+        }
+        const answer = (await deps.ask(`Create a new private GitHub repository for ${String(target?.displayName ?? input.connection)}? [Y/n] `)).trim().toLowerCase();
+        if (answer !== "" && answer !== "y" && answer !== "yes" && answer !== "n" && answer !== "no") {
+            // A typo is neither answer: reading it as "no" would bind an existing
+            // repository (silently, when exactly one is listed).
+            deps.writer.err("Answer y or n.");
+            return refuse;
+        }
+        if (answer === "" || answer === "y" || answer === "yes") {
+            const typed = (await deps.ask(`Repository name [${suggested ?? ""}]: `)).trim();
+            const name = typed.length > 0 ? typed : suggested;
+            if (name === null) {
+                deps.writer.err("The new repository needs a name. Run `flowsprite setup` again and type one, or pass --create <name>.");
+                return refuse;
+            }
+            // Not validated here: the server's own rule refuses a bad name, and its
+            // sentence is what the person sees.
+            input.create = name;
+            return { ok: true, input };
+        }
         const repos = asArray(chosen?.repos);
         if (repos.length === 0) {
             // An EMPTY list means Flowsprite has not listed that installation's
-            // repositories, not that the installation has none — the distinction the
-            // setup_bind_repo description draws, and the remedy differs.
-            deps.writer.err(`Flowsprite has not listed any repositories for installation ${String(input.installation)}. ` +
-                "Refresh Sync Accounts in the app, then try again — or pass --create <name> to make a new private one.");
-            return null;
+            // repositories, not that the installation has none. The web's repository
+            // dropdown on Salesforce Orgs is the only thing that lists them.
+            deps.writer.err(`Flowsprite has not listed any repositories for installation ${installationId} yet. ` +
+                "Open this connection's repository list on the Salesforce Orgs page in the app and press Refresh, " +
+                "then run `flowsprite setup` again — or answer yes to create a new private one.");
+            return refuse;
         }
         const picked = await pickOne(deps, REPOSITORY, repos.map((r) => [
             String(r.fullName ?? ""),
             `${r.private === true ? "private" : "PUBLIC — will be refused"}, default branch ${String(r.defaultBranch ?? "?")}`,
         ]));
         if (picked === null)
-            return null;
+            return refuse;
         input.repo = picked;
     }
-    return input;
+    return { ok: true, input };
 }
 /**
  * One of a list, or nothing.
@@ -574,21 +979,68 @@ async function runSync(deps, values, client, rung) {
  * it is a backstop, not a budget.
  */
 const MAX_SETUP_RUNGS = 24;
+/** Which login `setup` would use, in words, or null when there is none (N3 step 1). */
+function loginInWords(deps, origin, values) {
+    const stored = readCredentials(deps.env, deps.home)[origin];
+    const token = resolveToken({
+        flag: typeof values.token === "string" ? values.token : undefined,
+        env: deps.env.FLOWSPRITE_TOKEN,
+        stored: stored?.token,
+    });
+    if (token === null)
+        return null;
+    if (token.source !== "stored")
+        return `using the token from ${token.source}`;
+    // The stored ids are what the file holds (C4: names are never stored).
+    return stored !== undefined && stored.userId.length > 0
+        ? `already logged in as ${stored.userId} in workspace ${stored.orgId}`
+        : "already logged in with a saved token";
+}
 async function cmdSetup(deps, origin, values) {
     // Doctor-lite: the two things that make every later step fail confusingly.
     if (nodeMajor(deps.nodeVersion) < MIN_NODE_MAJOR) {
         deps.writer.err(`flowsprite needs node ${MIN_NODE_MAJOR} or newer; this is ${deps.nodeVersion}.`);
         return EXIT_FAILED;
     }
-    if (readCredentials(deps.env, deps.home)[origin] === undefined && resolveToken({
-        flag: typeof values.token === "string" ? values.token : undefined,
-        env: deps.env.FLOWSPRITE_TOKEN,
-    }) === null) {
+    const steps = createStepTracker(deps.writer);
+    const rc = await runSetup(deps, origin, values, steps);
+    // N14: EVERY non-success exit past the node check ends with how to continue.
+    // No new state: a rerun re-derives its step from setup_status.
+    if (rc !== EXIT_OK)
+        deps.writer.err(rerunHint(rerunLogin(deps, origin, values), steps.current()));
+    return rc;
+}
+/** G6: what a rerun would log in with — a saved credential is claimed only when one is stored. */
+function rerunLogin(deps, origin, values) {
+    // H2: an explicit token wins for THIS run, so a plain rerun would use a
+    // different login (the stored one, or none) — say "supplied" whatever is stored.
+    const flag = typeof values.token === "string" && values.token.length > 0;
+    const env = typeof deps.env.FLOWSPRITE_TOKEN === "string" && deps.env.FLOWSPRITE_TOKEN.length > 0;
+    if (flag || env)
+        return "supplied";
+    return readCredentials(deps.env, deps.home)[origin] !== undefined ? "stored" : "none";
+}
+async function runSetup(deps, origin, values, steps) {
+    let noticePrinted = false;
+    const login = loginInWords(deps, origin, values);
+    /** N4: once, before the first thing that waits on the browser — naming only what this run waits on (G9a). */
+    const browserNotice = () => {
+        if (noticePrinted)
+            return;
+        noticePrinted = true;
+        deps.writer.out(browserWaitNotice(login === null ? MAX_EXPIRES_IN_SECONDS : null));
+    };
+    if (login === null) {
         deps.writer.out(`Not logged in to ${origin} yet.`);
+        browserNotice();
+        steps.enter(1);
         const rc = await cmdLogin(deps, origin, values);
         if (rc !== EXIT_OK)
             return rc;
     }
+    else {
+        steps.skip(1, login);
+    }
     const built = clientFor(deps, origin, values);
     if (!built.ok)
         return EXIT_FAILED;
@@ -610,14 +1062,15 @@ async function cmdSetup(deps, origin, values) {
      * even when a volatile field makes two payloads differ.
      */
     let previousStatus = null;
-    let previousTool = null;
+    /** C7: the step that just ran, in words — the tool name is MCP vocabulary, not a terminal user's. */
+    let previousStep = null;
     for (let rungs = 0;; rungs++) {
         const status = await fetchStatus(deps, built.client);
         if (!status.ok)
             return EXIT_FAILED;
         const serialized = JSON.stringify(status.payload) ?? "";
-        if (previousTool !== null && serialized === previousStatus) {
-            deps.writer.err(`\`${previousTool}\` reported success, but this workspace's setup status did not change. ` +
+        if (previousStep !== null && serialized === previousStatus) {
+            deps.writer.err(`${previousStep} reported success, but this workspace's setup status did not change. ` +
                 "Stopping rather than repeating it: the setup steps are list-wide, so a step that does not " +
                 "move the checklist would repeat forever. Run `flowsprite status` to see what is left.");
             return EXIT_FAILED;
@@ -628,6 +1081,11 @@ async function cmdSetup(deps, origin, values) {
         }
         previousStatus = serialized;
         const step = planNextStep(status.payload);
+        const stepNumber = stepOfRung(step.kind);
+        if (stepNumber !== null)
+            steps.enter(stepNumber);
+        else if (step.kind === "first_sync")
+            steps.finishSteps();
         switch (step.kind) {
             case "done":
                 deps.writer.out("Setup is complete.");
@@ -640,12 +1098,20 @@ async function cmdSetup(deps, origin, values) {
             case "connect_salesforce":
             case "connect_github": {
                 deps.writer.out(step.text);
-                const tool = step.kind === "connect_salesforce" ? "setup_connect_salesforce" : "setup_connect_github";
-                const args = step.kind === "connect_salesforce" && values.sandbox === true ? { env: "sandbox" } : {};
-                const rc = reportLinkOutcome(deps.writer, await runLinkStep(sdeps, tool, args, step.kind));
+                if (step.kind === "connect_salesforce" && deps.isOnPath("sf")) {
+                    deps.writer.out("Already logged in to that org with the Salesforce CLI? `flowsprite connect salesforce --from-sf-cli <alias>` connects it without a browser.");
+                }
+                const provider = step.kind === "connect_salesforce" ? "salesforce" : "github";
+                const tool = provider === "salesforce" ? "setup_connect_salesforce" : "setup_connect_github";
+                const args = provider === "salesforce" ? salesforceLinkArgs(values) : {};
+                // The payload just read IS the pre-mint snapshot: the rung is done when a
+                // NEW connection / installation appears in it, and the identity check at
+                // the top of the loop then sees the ladder move on that same new row.
+                browserNotice();
+                const rc = await settleLinkOutcome(deps, built.client, await runLinkStep(sdeps, tool, args, provider, status.payload), provider, status.payload);
                 if (rc !== EXIT_OK)
                     return rc;
-                previousTool = tool;
+                previousStep = provider === "salesforce" ? "Connecting Salesforce" : "Connecting GitHub";
                 break;
             }
             default: {
@@ -660,13 +1126,27 @@ async function cmdSetup(deps, origin, values) {
                     return EXIT_FAILED;
                 }
                 deps.writer.out(step.text);
+                if (step.kind === "first_sync") {
+                    // A repository still being CREATED already counts as bound, so a re-run
+                    // of `setup` (or a wait that ended "gone") can land here while
+                    // `sfdc_trigger_sync` would refuse it. Wait for each one first, then
+                    // re-read the ladder rather than syncing off this stale payload.
+                    const creating = asArray(asObject(status.payload)?.connections).filter((c) => connectionIds.includes(String(c.id)) && c.bootstrapState === "creating");
+                    for (const c of creating) {
+                        const rc = await reportRepositoryWait(deps, values, built.client, String(c.id));
+                        if (rc !== EXIT_OK)
+                            return rc;
+                    }
+                    if (creating.length > 0)
+                        continue;
+                }
                 const rung = { kind: step.kind, connectionIds, status: status.payload };
                 const rc = step.kind === "bind_repo"
-                    ? await runBind(deps, values, built.client, rung)
+                    ? await runBind(deps, origin, values, built.client, rung)
                     : await runSync(deps, values, built.client, rung);
                 if (rc !== EXIT_OK)
                     return rc;
-                previousTool = step.kind === "bind_repo" ? "setup_bind_repo" : "sfdc_trigger_sync";
+                previousStep = step.kind === "bind_repo" ? "Binding a repository" : "Starting the first sync";
                 break;
             }
         }
@@ -715,12 +1195,44 @@ function mcpPrint(deps, origin, values, flag) {
     const stored = readCredentials(deps.env, deps.home)[origin];
     const mcpEndpoint = stored?.mcpEndpoint ?? `${origin}/api/mcp`;
     const tokenEnv = typeof values["token-env"] === "string" ? values["token-env"] : undefined;
-    let placeholder = TOKEN_PLACEHOLDER;
+    const clients = flag !== undefined ? [flag] : [...CLIENTS];
+    const ctxLite = pathContext(deps);
+    /** Every stdout line of this invocation, with `placeholder` where the bearer goes. */
+    const render = (placeholder) => {
+        const rows = clients.map((client) => {
+            const cfg = configPathFor(client, ctxLite);
+            const command = commandFor(client);
+            return {
+                client,
+                // What `mcp install` WOULD do for this client, on this machine, right now —
+                // derived from the same planner, so `print --json` cannot describe a route
+                // `install` does not take.
+                kind: planInstall(client, {
+                    ...ctxLite,
+                    origin,
+                    mcpEndpoint,
+                    token: TOKEN_PLACEHOLDER,
+                    tokenEnv,
+                    onPath: deps.isOnPath,
+                    fileExists: deps.fileExists,
+                }).kind,
+                path: cfg.path,
+                ...(command === null ? {} : { command }),
+                snippet: renderSnippet(client, { url: mcpEndpoint, placeholder, tokenEnv }),
+            };
+        });
+        // ONE client asked for, one object; no client asked for, the array. Nothing
+        // else on stdout either way — that is what makes this parseable.
+        if (values.json === true)
+            return [JSON.stringify(flag !== undefined ? rows[0] : rows, null, 2)];
+        return rows.flatMap((row, n) => [...(n > 0 ? [""] : []), `# ${row.client}`, row.snippet]);
+    };
     if (values.reveal === true) {
-        if (deps.isTTY !== true) {
+        if (deps.reveal === undefined) {
             // A SECRET GOES TO A TERMINAL OR NOWHERE. Through a pipe the destination is
             // a file, a log or another process's buffer, and none of those is something
-            // the person watching can decide to clear.
+            // the person watching can decide to clear. The sink exists iff stdout is a
+            // terminal (wiring.ts), so its absence IS the pipe.
             deps.writer.err("--reveal prints the real token, so it only runs at a terminal and stdout here is not one. " +
                 "Re-run it at a terminal, or drop --reveal for a snippet with a placeholder.");
             return EXIT_USAGE;
@@ -734,44 +1246,16 @@ function mcpPrint(deps, origin, values, flag) {
             deps.writer.err(`Not logged in to ${origin}, so there is no token to reveal. Run \`flowsprite login\`.`);
             return EXIT_FAILED;
         }
-        placeholder = token.token;
-    }
-    const clients = flag !== undefined ? [flag] : [...CLIENTS];
-    const ctxLite = pathContext(deps);
-    const rows = clients.map((client) => {
-        const cfg = configPathFor(client, ctxLite);
-        const command = commandFor(client);
-        return {
-            client,
-            // What `mcp install` WOULD do for this client, on this machine, right now —
-            // derived from the same planner, so `print --json` cannot describe a route
-            // `install` does not take.
-            kind: planInstall(client, {
-                ...ctxLite,
-                origin,
-                mcpEndpoint,
-                token: TOKEN_PLACEHOLDER,
-                tokenEnv,
-                onPath: deps.isOnPath,
-                fileExists: deps.fileExists,
-            }).kind,
-            path: cfg.path,
-            ...(command === null ? {} : { command }),
-            snippet: renderSnippet(client, { url: mcpEndpoint, placeholder, tokenEnv }),
-        };
-    });
-    if (values.json === true) {
-        // ONE client asked for, one object; no client asked for, the array. Nothing
-        // else on stdout either way — that is what makes this parseable.
-        deps.writer.out(JSON.stringify(flag !== undefined ? rows[0] : rows, null, 2));
+        // THE ONE CALL SITE OF THE UNREDACTED SINK (FLO-513 AC3). Every stdout line
+        // of a --reveal run — the `# client` headers, the snippet, or the --json
+        // document — goes through it, because the writer would redact the token
+        // back out. The real token enters `render` only on this path.
+        for (const line of render(token.token))
+            deps.reveal(line);
         return EXIT_OK;
     }
-    rows.forEach((row, n) => {
-        if (n > 0)
-            deps.writer.out("");
-        deps.writer.out(`# ${row.client}`);
-        deps.writer.out(row.snippet);
-    });
+    for (const line of render(TOKEN_PLACEHOLDER))
+        deps.writer.out(line);
     return EXIT_OK;
 }
 async function mcpInstall(deps, origin, values, flag) {