@spacefast/common 0.0.26 → 0.2.2

package/dist/docs/agent-setup.js

@@ -1,58 +1,51 @@
-import { buildClaudeMcpAddCommand, buildHermesMcpAddCommand, cursorHostedMcpDeeplink, cursorHostedMcpServersJson, getConnectTarget, opencodeHostedMcpConfig, vscodeHostedMcpDeeplink, vscodeHostedMcpServersJson, } from "../agents/connect-targets.js";
-import { BRAND } from "../brand.js";
+import { buildConnectTargets, CONNECT_TARGET_IDS, getConnectTarget, } from "../agents/connect-targets.js";
+import { AGENT_REGISTRY, hostedMcpServersConfig, presentAgentEntry, } from "../agents/registry/core.js";
+import { BRAND, SPACEFAST_POSITIONING_SHORT } from "../brand.js";
 import { serviceOrigin } from "../config/domains.js";
 import { PLAN_DEFINITIONS, SELF_SERVE_PLAN_CODES } from "../contracts/features.js";
-import { createBrowserCredentialUrl, parseBrowserCredentialUrl, } from "../utils/browser-credential.js";
-import { CHECK_BEFORE_PUBLISH_PROSE, CONTINUE_AFTER_CLAIM_PROSE, ENV_NOTES_PROSE, FAILURE_CONDUCT_PROSE, FEEDBACK_PROSE, HOW_TO_RESEARCH_PROSE, LANE_PICKER_PROSE, POSITIONING_PROSE, PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SAVE_STATE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, UPDATE_SPACE_PROSE, } from "./agent-prose.js";
-import { spacefastClaudePluginAddCommand, spacefastClaudeDesktopExtensionUrl, spacefastClaudePluginInstallCommand, spacefastCodexPluginAddCommand, spacefastCodexPluginInstallCommand, spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "./skill-distribution.js";
-// The one URL every agent prompt points at. /setup.md is the actionable front
-// door (publish now, then set up your client); /ai.txt stays the deep
-// reference contract it links out to.
+import { BROWSER_HANDOFF_TOKEN_PATTERN } from "../utils/browser-credential.js";
+import { CHECK_BEFORE_PUBLISH_PROSE, FEEDBACK_PROSE, PUSH_TO_DEPLOY_PROSE } from "./agent-prose.js";
+import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastNpxCommand, spacefastSkillInstallCommand, } from "./skill-distribution.js";
+// /setup.md is THE agent document: every prompt points at it, and retired
+// paths (/ai.txt, /ai.md) permanently redirect to it.
 export const agentSetupUrl = `${serviceOrigin("www", "prod")}/setup.md`;
-export const agentSetupTextUrl = `${serviceOrigin("www", "prod")}/ai.txt`;
 const agentSetupParsedUrl = new URL(agentSetupUrl);
 export const agentSetupHostLabel = agentSetupParsedUrl.host + agentSetupParsedUrl.pathname;
-// Deliberately bare: the document itself tells the agent to ask what to
-// publish when it isn't obvious and to update an existing space, so the prompt
-// stays a single gesture that works in any client.
+// Deliberately bare: the fetched document carries the rest, so the prompt stays
+// a single gesture that works in any client.
 export const agentSetupPrompt = `Fetch ${agentSetupUrl}`;
-// The no-install publish: one POST, no account. Single-sourced so the
-// marketing pages and the setup doc can never show different commands.
+// The no-install publish: one POST, no account. Single-sourced so the marketing
+// pages and the setup doc can never show different commands.
 //
-// `?wait=1` is load-bearing, not decoration. Without it the request takes the
-// default finalize budget (SPACEFAST_PUBLISH_DEFAULT_WAIT_MS, 1.5s), so the 201
-// comes back with `activation.outcome: "pending"` plus a `next.action: "poll"`
-// pointer — measured in production at ~4.2s to a receipt describing a site that
-// is not serving yet, settling ~37s later. A one-shot agent then has to run a
-// poll loop against an endpoint that requires the space key as bearer. With
-// `?wait=1` the same publish returns `activation.outcome: "activated"` and
-// `next.action: "done"`, so the documented happy path is genuinely one command.
+// `?wait=1` is load-bearing. Without it the 201 returns
+// `activation.outcome: "pending"` and a `next.action: "poll"` pointer at an
+// endpoint that needs the space key as bearer (measured in production: a receipt
+// at ~4.2s for a site that only settles ~37s later). With it the publish returns
+// `activated` / `done`, so the happy path is genuinely one command.
 //
-// The URL is quoted because `?` is a glob character in zsh: unquoted, the
-// documented command dies with "no matches found" before curl ever runs.
+// The URL is quoted because `?` globs in zsh: unquoted, the command dies with
+// "no matches found" before curl ever runs.
 export const anonymousPublishCurlCommand = `curl -F "files=@index.html" "${serviceOrigin("api", "prod")}/v1/publish?wait=1"`;
 /*
- * Agent handoff contract: private links carry a one-use path token on
- * https://<access-origin>/agent/<documentId>/<token>; durable agent credentials stay encrypted at
- * the broker. Agents fetch the reconstructed clean dashboard document URL, never the private
- * handoff URL. Fetching never consumes a
- * handoff; exactly one successful redemption
- * does. Redemption is app-private, reuses the existing device/OAuth approval service, and returns
- * the already-approved finite Space-scoped credential: there is no public AgentGrant resource,
- * durable key table, or team-wide publisher key. The CLI accepts links only through stdin or a
- * browser callback and redacts them from JSON output, telemetry, shell history, doctor, and
- * receipts. The dashboard can revoke an unused handoff.
+ * Agent handoff contract: one opaque bearer lives at
+ * https://<access-origin>/handoffs/<token>. Fetching that URL records a read and
+ * returns the setup document without consuming the handoff. Exactly one
+ * successful redemption spends it and returns the pre-approved credential.
+ * The token is stored only as a hash. The CLI accepts the URL only through stdin
+ * or a browser callback and redacts it from output, telemetry, and receipts.
+ *
+ * The token is the sole bearer now that the URL carries no separate document id,
+ * so it stays a 256-bit random value in URL-safe base64 rather than a UUID's 122
+ * random bits. This pattern is the same one the one-use bridge enforces on the
+ * wire (`access/handoffs.ts`), single-sourced here so the grammar cannot fork.
  */
-const opaqueHandoffDocumentId = /^[A-Za-z0-9_-]{1,512}$/;
-const opaqueHandoffSecret = /^[A-Za-z0-9_-]{16,512}$/;
+export const AGENT_HANDOFF_TOKEN_PATTERN = BROWSER_HANDOFF_TOKEN_PATTERN;
 const shellSafeMcpEndpoint = /^[A-Za-z0-9%+,\-./:=_[\]~]+$/;
 /**
- * Typed, safe decline states for the app-private redemption exchange.
- * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
- * decline never becomes an existence oracle; state-specific reasons are returned only after the
- * supplied secret authenticates the handoff. `already_redeemed` makes one-use explicit: after the
- * first exchange succeeds, the second fails with this reason. Declines are terminal and never
- * reveal whether a secret was close to correct.
+ * Decline states for the app-private redemption exchange. `invalid_handoff` is
+ * the single answer for both an unknown document ID and a wrong secret, so a
+ * decline never becomes an existence oracle; the other reasons are returned only
+ * after the supplied secret authenticates the handoff. Declines are terminal.
  */
 export const AGENT_HANDOFF_DECLINE_REASONS = [
     "invalid_handoff",
@@ -71,20 +64,7 @@ function isSafeHttpUrl(url) {
         !url.username &&
         !url.password);
 }
-/**
- * The single shared grammar for handoff links:
- * `<access-origin>/agent/<documentId>/<oneUseToken>`. The document ID must match
- * `[A-Za-z0-9_-]{1,512}` and the token `[A-Za-z0-9_-]{16,512}`; the two must differ;
- * queries, fragments, and URL userinfo are forbidden. The URL must sit exactly on the caller's
- * configured HTTP(S) access origin; the clean static document may live on a separate explicitly
- * supplied dashboard origin.
- * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
- * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
- * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
- * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
- * grammar can never fork.
- */
-export function parseAgentHandoffUrl(value, expectedOrigin, documentOrigin = expectedOrigin) {
+export function parseAgentHandoffUrl(value, expectedOrigin) {
     let expectedUrl;
     try {
         expectedUrl = new URL(expectedOrigin);
@@ -96,54 +76,24 @@ export function parseAgentHandoffUrl(value, expectedOrigin, documentOrigin = exp
         throw new TypeError("Agent handoff expectedOrigin must be an HTTP(S) origin.");
     }
     const canonicalExpectedOrigin = expectedUrl.origin;
-    let canonicalDocumentOrigin;
-    try {
-        const documentUrl = new URL(documentOrigin);
-        if (!isSafeHttpUrl(documentUrl) ||
-            documentUrl.username ||
-            documentUrl.password ||
-            documentUrl.pathname !== "/" ||
-            documentUrl.search ||
-            documentUrl.hash) {
-            throw new TypeError("invalid_document_origin");
-        }
-        canonicalDocumentOrigin = documentUrl.origin;
-    }
-    catch {
-        throw new TypeError("Agent handoff documentOrigin must be a clean HTTP(S) origin.");
-    }
     let url;
-    let parsedCredential;
     try {
         url = new URL(value);
-        parsedCredential = parseBrowserCredentialUrl(value);
     }
     catch {
         throw new TypeError("Agent handoff URL must be a valid private HTTP(S) URL.");
     }
-    const documentId = /^\/agent\/([^/]+)\/[^/]+$/.exec(url.pathname)?.[1];
-    const secret = parsedCredential.credential;
+    // Defaulted, not narrowed: the token pattern already rejects the empty string.
+    const secret = /^\/handoffs\/([^/]+)$/.exec(url.pathname)?.[1] ?? "";
     if (url.origin !== canonicalExpectedOrigin ||
-        value.includes("?") ||
+        url.username ||
+        url.password ||
+        url.search ||
         url.hash !== "" ||
-        !documentId ||
-        !opaqueHandoffDocumentId.test(documentId) ||
-        !opaqueHandoffSecret.test(secret) ||
-        documentId === secret) {
-        throw new TypeError("Agent handoff URL must be a private /agent/<id>/<token> URL on the access origin with one opaque token (16-512 chars, distinct from the id) and no userinfo, query, or fragment.");
+        !AGENT_HANDOFF_TOKEN_PATTERN.test(secret)) {
+        throw new TypeError("Agent handoff URL must be a private /handoffs/<token> URL on the access origin with no userinfo, query, or fragment.");
     }
-    const handoffUrl = createBrowserCredentialUrl({
-        origin: canonicalExpectedOrigin,
-        path: "/agent",
-        publicId: documentId,
-        credential: secret,
-    });
-    return {
-        documentId,
-        documentUrl: new URL(`/agent/${encodeURIComponent(documentId)}`, canonicalDocumentOrigin).toString(),
-        handoffUrl,
-        secret,
-    };
+    return { handoffUrl: url.toString(), secret };
 }
 function validateMcpEndpoint(value) {
     let url;
@@ -153,28 +103,51 @@ function validateMcpEndpoint(value) {
     catch {
         throw new TypeError("MCP endpoint must be a valid HTTP(S) URL.");
     }
-    if (!shellSafeMcpEndpoint.test(value) || !isSafeHttpUrl(url)) {
+    if (!shellSafeMcpEndpoint.test(value) || !isSafeHttpUrl(url) || url.pathname !== "/") {
         throw new TypeError("MCP endpoint must be a shell-safe HTTPS URL with no credentials, query, fragment, or control characters (HTTP is allowed on loopback hosts).");
     }
     return url.href.replace(/\/$/, "");
 }
 /*
- * Shared handoff prose. The per-handoff "Copy Markdown" artifact (below) and the
- * public /agent/<id> document (./agent-handoff-document.ts) must tell agents the
- * same contract in the same words, so the sentences live here exactly once.
+ * Shared handoff prose. The document returned from `/handoffs/<token>` and the
+ * short clipboard prompt render from these sentences.
  */
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export const AGENT_HANDOFF_CLI_TARGET_IDS = ["claude-code", "codex"];
-export const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to publish.";
-/** The fetch-safety contract: reading the document never consumes or leaks a handoff. */
-export const AGENT_HANDOFF_FETCH_SAFETY = "Keep the original handoff link private. Fetching this clean document URL did not use or send its credential; the credential is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.";
-export const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the private handoff URL out of commands, request URLs, logs, and replies.";
-export const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE = `Run \`sf setup agent\` to initiate the handoff exchange; if \`sf\` is missing, install it first (macOS/Linux: \`${spacefastInstallCurlCommand}\`; Windows PowerShell: \`${spacefastInstallPowerShellCommand}\`). When it asks for the handoff link on stdin, paste the original link into that prompt; never pass the link as an argv value. Ask the user to approve in the browser, then wait for the CLI's approval result before publishing.`;
-export const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Access URL; create a scoped Link when a recipient needs access.";
+export const AGENT_HANDOFF_PREAMBLE = "Talk to the user before you install tools or publish. Confirm the file or folder to publish.";
+export const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the handoff URL out of command arguments, logs, and replies. It goes in exactly two places: the stdin prompt of `sf setup agent`, or the redeem request body.";
+export const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE = `Run \`sf setup agent\` — with npx, \`${spacefastNpxCommand} setup agent\` needs no install — and give it the handoff link on its stdin prompt: pipe it (a quoted heredoc works) or paste it, never as an argument. To install \`sf\`: macOS/Linux \`${spacefastInstallCurlCommand}\`; Windows PowerShell \`${spacefastInstallPowerShellCommand}\`. It stores the API key for the CLI; wait for the login result before publishing.`;
+function directHandoffExchangeGuidance(handoffOrigin) {
+    const exchangeUrl = new URL("/v1/auth/agent-handoffs/redeem", handoffOrigin).toString();
+    return `POST JSON with the URL you fetched in the \`url\` field to ${exchangeUrl}, once. The response's \`data.apiKey.secret\` is the key: send it as \`Authorization: Bearer <secret>\` and never print it. If the call fails or times out, ask the user for a fresh link — the handoff may be spent. Without secure storage, keep the key in this session; the user can manage keys in the dashboard.`;
+}
+function isConnectTargetId(value) {
+    return CONNECT_TARGET_IDS.some((candidate) => candidate === value);
+}
+function hostedHandoffTargetName(value) {
+    switch (value) {
+        case "any":
+            return "your agent";
+        case "claude":
+            return "Claude";
+        case "scira":
+            return "Scira";
+        case "t3":
+            return "T3 Chat";
+        case "v0":
+            return "v0";
+        default:
+            return value;
+    }
+}
+export const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's push.new remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export function agentHandoffConnectSections(target) {
-    const setupSections = [target.primary, target.config].flatMap((setup) => setup ? [[setup.label, `\`\`\`${setup.language}`, setup.value, "```"].join("\n")] : []);
+    // When the client's best lane IS its config file, `primary` and `config` are
+    // the same block. Rendering both prints the same paste twice under the same
+    // heading, which reads as two steps.
+    const setups = [target.primary, target.config].filter((setup, index, all) => setup !== undefined && all.findIndex((other) => other?.value === setup.value) === index);
+    const setupSections = setups.map((setup) => [setup.label, `\`\`\`${setup.language}`, setup.value, "```"].join("\n"));
     return [
         target.blurb,
         ...setupSections,
@@ -182,265 +155,252 @@ export function agentHandoffConnectSections(target) {
         ...(target.download ? [`${target.download.label}: ${target.download.href}`] : []),
     ];
 }
-function renderAgentHandoffInstructions(documentUrl, target) {
-    const approvalGuidance = AGENT_HANDOFF_CLI_TARGET_IDS.includes(target.id)
-        ? AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE
-        : AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE;
+const CONNECT_CATALOG_INTRO = "Use the section for the client you are running in.";
+/**
+ * Everything the agent needs to know about the link, said once, where it acts
+ * on it. "The URL you fetched" doubles as the only reference to the bearer —
+ * the document never repeats it, so the live secret stays out of whatever the
+ * agent caches or quotes next (`renderAgentHandoffDocument` takes an ORIGIN,
+ * never a URL, so the token cannot even reach the renderer).
+ */
+export const AGENT_HANDOFF_EXCHANGE_PROSE = `The URL you fetched is a one-use handoff: fetching did not spend it, and it expires within minutes. Exchange it now for a durable ${BRAND.productName} API key scoped to the user's team and role. Store the key as a secret and use it on every later request. MCP connectors bring their own auth and never need this key.`;
+/**
+ * The connect catalog a handoff document carries, most useful first. A chosen
+ * client leads with its own section, and its vendor's sibling clients follow
+ * ("Claude" also means Claude Code and Claude Desktop are likely where the
+ * reader actually is). "any" carries the whole catalog because nothing was
+ * chosen. A hosted-only target with no catalog row carries none — its whole
+ * setup is the exchange section.
+ */
+function handoffConnectCatalog(targetId, mcpEndpoint) {
+    const catalog = buildConnectTargets({ mcpEndpoint });
+    if (targetId === "any")
+        return catalog;
+    // The hosted "claude" target is the Claude app's page-context handoff; its
+    // catalog row lives under the registry id `claude-app`.
+    const registryId = isConnectTargetId(targetId)
+        ? targetId
+        : targetId === "claude"
+            ? "claude-app"
+            : null;
+    if (registryId === null)
+        return null;
+    const vendorById = new Map(AGENT_REGISTRY.map((agent) => [agent.id, agent.vendor]));
+    const family = catalog.filter((candidate) => vendorById.get(candidate.id) === vendorById.get(registryId));
+    return [
+        ...family.filter((candidate) => candidate.id === registryId),
+        ...family.filter((candidate) => candidate.id !== registryId),
+    ];
+}
+/** The Connect section body for a catalog: intro line, then one `###` per client. */
+function connectCatalogSections(catalog, intro) {
+    // A one-client catalog needs no picker prose and no per-client heading.
+    if (catalog.length === 1 && catalog[0])
+        return agentHandoffConnectSections(catalog[0]);
+    return [
+        intro,
+        ...catalog.flatMap((candidate) => {
+            const sections = agentHandoffConnectSections(candidate);
+            sections.unshift(`### ${candidate.name}`);
+            return sections;
+        }),
+    ];
+}
+/**
+ * The per-handoff setup document served from `/handoffs/<token>`.
+ *
+ * Takes the handoff's ORIGIN, never its URL: the bearer must not be able to
+ * reach this renderer, so it cannot end up in the bytes an agent caches.
+ *
+ * Reading order is the argument: what Spacefast is, talk to the user, exchange
+ * the link for a durable API key — the only expiring step, so it comes before
+ * client setup — then connect the client, then publish.
+ */
+export function renderAgentHandoffDocument(input) {
+    const mcpEndpoint = validateMcpEndpoint(input.mcpEndpoint);
+    const catalog = handoffConnectCatalog(input.targetId, mcpEndpoint);
+    const chosen = input.targetId !== "any" ? (catalog?.[0] ?? null) : null;
+    const targetName = chosen?.name ?? hostedHandoffTargetName(input.targetId);
+    // Both exchange lanes render for every target — the reader, not the mint,
+    // knows whether it has a shell — ordered by which one the chosen client
+    // would use.
+    const shellLane = `With a shell: ${AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE}`;
+    const directLane = `Without a shell: ${directHandoffExchangeGuidance(input.handoffOrigin)}`;
+    // Derived from the registry rather than the contracts module: device-auth
+    // imports from this file, so importing its target list back would be a cycle.
+    const shellFirst = input.targetId === "any" ||
+        AGENT_REGISTRY.some((agent) => agent.redeemableClientTargetId === input.targetId);
     const sections = [
-        `# Set up ${BRAND.productName} with ${target.name}`,
-        `This is the public setup document for ${documentUrl}.`,
+        `# Set up ${BRAND.productName} with ${targetName}`,
+        SPACEFAST_POSITIONING_SHORT,
         AGENT_HANDOFF_PREAMBLE,
-        ["## Connect", ...agentHandoffConnectSections(target)].join("\n\n"),
         [
-            "## Continue the approved handoff",
-            AGENT_HANDOFF_FETCH_SAFETY,
-            approvalGuidance,
+            "## Exchange the handoff for an API key",
+            AGENT_HANDOFF_EXCHANGE_PROSE,
+            ...(shellFirst ? [shellLane, directLane] : [directLane, shellLane]),
             AGENT_HANDOFF_CREDENTIAL_HYGIENE,
         ].join("\n\n"),
+        ...(catalog
+            ? [["## Connect", ...connectCatalogSections(catalog, CONNECT_CATALOG_INTRO)].join("\n\n")]
+            : []),
+        // No trailing "read more" pointer: this document is the one fetch, and it
+        // carries everything the agent needs.
         ["## Publish", AGENT_HANDOFF_PUBLISH_PROSE].join("\n\n"),
-        `General agent instructions: ${agentSetupTextUrl}`,
+    ];
+    return `${sections.join("\n\n")}\n`;
+}
+/**
+ * The document behind an anonymous (signed-out) handoff link. Same opening as
+ * the signed-in "any" document, ordered by usefulness: the two things the
+ * agent can actually do (publish with the no-account POST, or have the user
+ * sign in for a real handoff) come before the optional client catalog. The
+ * link itself grants nothing — its fetch only feeds the /start arrival watch —
+ * and the document doesn't narrate that; "Get a credential" states the one
+ * fact the agent needs.
+ */
+export function renderAnonymousAgentHandoffDocument(input) {
+    const mcpEndpoint = validateMcpEndpoint(input.mcpEndpoint);
+    const catalog = buildConnectTargets({ mcpEndpoint });
+    const sections = [
+        `# Set up ${BRAND.productName} with your agent`,
+        SPACEFAST_POSITIONING_SHORT,
+        AGENT_HANDOFF_PREAMBLE,
+        [
+            "## Publish now — no account",
+            "Publish one file with a single POST:",
+            ["```bash", anonymousPublishCurlCommand, "```"].join("\n"),
+            `For a folder, zip only the public output — never a repo root, \`.env*\`, \`.git\`, or \`.spacefast\` — and send it as \`-F archive=@site.zip\`.`,
+            `The \`{ data }\` receipt has the live URL and a \`claim\` block. Anonymous spaces expire unless claimed: show the user \`data.claim.claimUrl\` and its deadline.`,
+        ].join("\n\n"),
+        [
+            "## Get a credential",
+            `This link carries no credential. To act on the user's account, have them sign in at ${serviceOrigin("dashboard", "prod")}/start and copy the prompt again — that copy carries a handoff you can exchange for an API key.`,
+        ].join("\n\n"),
+        ["## Connect", ...connectCatalogSections(catalog, CONNECT_CATALOG_INTRO)].join("\n\n"),
     ];
     return `${sections.join("\n\n")}\n`;
 }
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
 export function buildAgentHandoff(input) {
-    const { documentUrl, handoffUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin, input.documentOrigin);
-    const mcpEndpoint = validateMcpEndpoint(input.mcpEndpoint);
+    const { handoffUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin);
     const target = getConnectTarget(input.targetId, {
-        mcpEndpoint,
+        mcpEndpoint: validateMcpEndpoint(input.mcpEndpoint),
     });
-    const prompt = `Fetch ${documentUrl} and follow the ${target.name} setup instructions to publish with ${BRAND.productName}. Use this private one-use handoff only for the exchange step: ${handoffUrl}. Do not fetch the private handoff URL. Ask me what I want to publish if it isn't obvious.`;
-    const instructions = renderAgentHandoffInstructions(documentUrl, target);
-    const actions = [
-        { kind: "copy", label: "Copy for my agent", sensitive: true, value: prompt },
-        { kind: "copy", label: "Copy Markdown", sensitive: false, value: instructions },
-    ];
-    if (target.deeplink) {
-        actions.push({
-            kind: "open",
-            label: target.deeplink.label,
-            href: target.deeplink.href,
-        });
-    }
-    if (target.download) {
-        actions.push({
-            kind: "open",
-            label: target.download.label,
-            href: target.download.href,
-        });
-    }
-    // The scanner-safe invariant is total, not statistical: no public projection may contain the
-    // secret, no matter what the caller fed in (a pathological mint, a poisoned MCP endpoint).
-    const publicProjections = [
-        documentUrl,
-        instructions,
-        ...actions.flatMap((action) => {
-            if (action.kind === "open")
-                return [action.href];
-            return action.sensitive ? [] : [action.value];
-        }),
-    ];
-    if (publicProjections.some((projection) => projection.includes(secret))) {
-        throw new TypeError("Agent handoff inputs would leak the private credential into a public projection.");
+    const prompt = `Fetch ${handoffUrl} and follow the private ${target.name} handoff it returns. Ask me what to publish if it isn't obvious.`;
+    return { prompt, secret, url: handoffUrl };
+}
+/**
+ * The signed-out half: a handoff that carries no team, no Space, and no
+ * authority, so its document is the public setup guide. It exists only so the
+ * fetch is observable — /start can tell the visitor their agent arrived without
+ * first making them sign up.
+ *
+ * The handoff line is APPENDED to the caller's prompt rather than replacing it:
+ * signed out, the prompt is still the thing carrying the user's actual task.
+ * One gesture, one sentence, single-sourced so no surface can word it
+ * differently. With no task selected the handoff line IS the prompt — the
+ * fetched document carries the whole setup, so the copy stays a single link.
+ */
+export function buildAnonymousAgentHandoff(input) {
+    const { handoffUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin);
+    const context = input.context.trim() === "" ? null : input.context;
+    return {
+        prompt: context === null
+            ? `Fetch ${handoffUrl} and follow it.`
+            : `${context}\n\nFirst, fetch ${handoffUrl} and follow it.`,
+        secret,
+        url: handoffUrl,
+    };
+}
+/*
+ * The machine artifacts render from the registry, not from hand-written
+ * per-client walls. `static-docs` is the right presentation context for both:
+ * no session, no mint, and no affordance that needs a browser we do not have.
+ */
+function registryContext() {
+    return {
+        apiOrigin: serviceOrigin("api", "prod"),
+        dashboardOrigin: serviceOrigin("dashboard", "prod"),
+        mcpEndpoint: serviceOrigin("mcp", "prod"),
+        wwwOrigin: serviceOrigin("www", "prod"),
+    };
+}
+/** A listing with nothing to run yet is a "soon" chip on a page, and nothing at all here. */
+function actionableDocsMethods(agent) {
+    return agent.staticDocs.filter((method) => method.action.kind !== "disabled" && method.action.value !== "");
+}
+/** One method as docs prose: what it does, then the exact thing to run or paste. */
+function methodBlock(method) {
+    if (method.action.kind === "link" || method.action.kind === "download") {
+        return [`${method.summary}`, "", `${method.action.label}: ${method.action.value}`, ""];
     }
-    return { actions, documentUrl, instructions, prompt };
+    return [method.summary, "", `\`\`\`${method.language}`, method.action.value, "```", ""];
+}
+/**
+ * Featured clients earn their own section (spec §1 "Tier is load-bearing"); the
+ * two best static-docs methods are the whole section, so the document stays
+ * short enough that an agent reads it whole.
+ */
+function featuredAgentSections(context) {
+    return AGENT_REGISTRY.filter((agent) => agent.tier === "featured").flatMap((agent) => {
+        const presented = presentAgentEntry(agent.id, context);
+        const methods = actionableDocsMethods(presented)
+            .filter((method) => method.id !== "universal-prompt")
+            .slice(0, 2);
+        return [`### ${agent.name}`, "", agent.description, "", ...methods.flatMap(methodBlock)];
+    });
+}
+/** Every listed client, one row: the single best thing that connects it. */
+function listedAgentRows(context) {
+    const rows = AGENT_REGISTRY.filter((agent) => agent.tier === "listed").flatMap((agent) => {
+        const presented = presentAgentEntry(agent.id, context);
+        const methods = actionableDocsMethods(presented);
+        const concrete = methods.filter((method) => method.id !== "universal-prompt" && method.id !== "skill");
+        // A setup.md prompt is the deliberate fallback only when the interactive
+        // registry also chose it. A client whose real integration is its skill
+        // (Continue) keeps its guide row instead of being flattened to the prompt.
+        const best = concrete[0] ??
+            (presented.methods[0]?.id === "universal-prompt"
+                ? methods.find((method) => method.id === "universal-prompt")
+                : undefined);
+        if (!best)
+            return [];
+        if (best.action.value.includes("\n")) {
+            return [`| ${agent.name} | see ${agent.docs.spacefast} |`];
+        }
+        const where = best.path === undefined ? "" : ` in ${best.path}`;
+        return [`| ${agent.name} | \`${best.action.value}\`${where} |`];
+    });
+    return ["| Client | Connect with |", "| --- | --- |", ...rows, ""];
+}
+/** Clients whose hosted-MCP lane is a browser OAuth handshake, named from the registry. */
+function oauthClientNames() {
+    return AGENT_REGISTRY.filter((agent) => agent.capabilities.includes("mcp-oauth"))
+        .map((agent) => agent.name)
+        .join(", ");
+}
+/** Clients that have a live one-click install today, named from the registry. */
+function deeplinkClientNames() {
+    return AGENT_REGISTRY.filter((agent) => agent.methods.some((method) => method.kind === "deeplink" &&
+        method.listing.status === "live" &&
+        method.verification.status !== "failed"))
+        .map((agent) => agent.name)
+        .join(", ");
 }
 export function renderAgentSetupTemplate(value) {
     return value
         .replaceAll("{{AGENT_SETUP_URL}}", agentSetupUrl)
-        .replaceAll("{{AGENT_SETUP_TEXT_URL}}", agentSetupTextUrl)
         .replaceAll("{{AGENT_SETUP_HOST_LABEL}}", agentSetupHostLabel);
 }
-// Progressive disclosure: the fast path (one curl, zero install) comes first and is
-// complete on its own; the CLI section unlocks the rest. Keep this readable top to
-// bottom — an agent that stops after "Publish with curl" must still succeed.
-export function aiInstructionsText() {
-    return [
-        `# ${BRAND.productName} for AI agents`,
-        "",
-        `Official instructions for AI agents publishing to ${BRAND.productName}.`,
-        "",
-        POSITIONING_PROSE,
-        "",
-        "## Before you publish (check for an existing space)",
-        "",
-        CHECK_BEFORE_PUBLISH_PROSE,
-        "",
-        "## Publish with curl (no install, no account)",
-        "",
-        PUBLISH_SEQUENCE_PROSE,
-        "",
-        RECEIPT_SHAPE_PROSE,
-        "",
-        "## Save your state",
-        "",
-        SAVE_STATE_PROSE,
-        "",
-        "## Update a space",
-        "",
-        UPDATE_SPACE_PROSE,
-        "",
-        "## Big files and cloud agents",
-        "",
-        SIGNED_UPLOAD_PROSE,
-        "",
-        "## Secret handling",
-        "",
-        SECRET_RULES_PROSE,
-        "",
-        "## Failure conduct",
-        "",
-        FAILURE_CONDUCT_PROSE,
-        "",
-        "## How to research",
-        "",
-        HOW_TO_RESEARCH_PROSE,
-        "",
-        'Add a bearer access token with `-H "Authorization: Bearer ..."` to publish into the user\'s',
-        "team instead of anonymously. Agent clients should prefer OAuth client credentials. Errors come back as RFC 9457 problem documents with stable `code` values and a",
-        "`type` URL; fetch the `type` URL when you need recovery steps.",
-        "",
-        "## Install the CLI (On-Device files, updates, versions, rollback, and the rest)",
-        "",
-        "The CLI is the full surface: incremental publishes, version history, rollback,",
-        "sharing, domains, logs, and diagnostics. Install it when the user will keep",
-        "working on the space:",
-        "",
-        "```bash",
-        spacefastInstallCurlCommand,
-        "```",
-        "",
-        "On Windows PowerShell:",
-        "",
-        "```bash",
-        spacefastInstallPowerShellCommand,
-        "```",
-        "",
-        "If `sf` is already on PATH, use it. The package is `spacefast`; the default binary is `sf`.",
-        "",
-        "```bash",
-        "sf setup agent --agent auto  # pick the right MCP lane and write client config",
-        "sf publish {file-or-dir}   # publish; prints live, version, and claim URLs",
-        "sf versions ls             # list versions",
-        "sf rollback {version}      # make an earlier ready version live, no rebuild",
-        "sf login                   # device flow; mints a scoped API key",
-        "sf --help                  # the full command surface",
-        "```",
-        "",
-        "Use `--json` on any command when the output will be parsed. Publishing the same",
-        "directory again updates the space saved in `.spacefast/state.json`.",
-        "",
-        "## MCP for agent clients",
-        "",
-        LANE_PICKER_PROSE,
-        "",
-        "Hosted MCP is the no-download cloud lane for ChatGPT, Codex, Claude, Cursor, and browser",
-        "clients that can authenticate with OAuth:",
-        "",
-        "```text",
-        "https://mcp.spacefast.com",
-        "```",
-        "",
-        "Request `mcp:tools` plus the API scopes the tools need: `teams:read` for team context,",
-        "`teams:create` for creating teams,",
-        "`spaces:read` for status, versions, diffs, and logs, `spaces:write` for claim/create/update,",
-        "`spaces:rename` for slug and managed-address renames, `publish:write` for publish and rollback,",
-        "and `domains:read`/`domains:write` for domain",
-        "inventory, DNS diagnostics, assignment, verification, and mutation. Hosted MCP has no",
-        "filesystem access.",
-        "",
-        "For hosted MCP, call `publish` with inline files. For larger artifacts, use `execute` to",
-        "discover and invoke the catalog publish operations. Hosted MCP is the right path for",
-        "ChatGPT/browser agents because it requires no download and never claims local filesystem access.",
-        "`execute` runs code in Spacefast's secure QuickJS sandbox. Mutating OpenAPI calls pause before HTTP",
-        "and return an execution ID; continue the same live execution with `resume` and an",
-        "`accept`, `decline`, or `cancel` action.",
-        "",
-        "Use On-Device MCP when the agent needs path-based publish from the user's checkout:",
-        "",
-        "```bash",
-        "sf setup agent --agent auto",
-        "sf mcp install --agent codex --remote --oauth",
-        "sf mcp install --agent codex",
-        "sf mcp",
-        "sf mcp http --host 127.0.0.1 --port 3945 --path /mcp",
-        "```",
-        "",
-        "Create dashboard agent accounts only for CI, bots, or durable local runtimes. In CI, prefer",
-        "`SPACEFAST_AGENT_CONFIG` with private_key_jwt when available; otherwise use one-job",
-        "`SPACEFAST_TOKEN` secrets and mask logs. Do not persist personal auth in ephemeral runners.",
-        "",
-        "If your environment supports skill import, install the official skill:",
-        `\`${spacefastSkillInstallCommand}\`. Raw markdown source: \`${spacefastSkillFetchCommand}\` (${spacefastSkillUrl}).`,
-        "",
-        "## After publishing",
-        "",
-        "- Report the bare Live URL, the immutable Version URL when ready, the private Access URL, and",
-        "  — for anonymous spaces — the claim link with its expiry. Bare Live and Version URLs carry",
-        "  no authority for a private Space; create a scoped Link when a recipient needs access.",
-        "  If the receipt's immutable URL is null, poll the",
-        "  operation and version links with the space key as bearer auth until the version is ready.",
-        "- Never print access tokens, space keys, auth files, or `.spacefast/state.json`.",
-        "",
-        "## After the user claims",
-        "",
-        CONTINUE_AFTER_CLAIM_PROSE,
-        "",
-        "## Space conventions",
-        "",
-        "- `_redirects` — redirects, rewrites, SPA fallbacks, custom 404 rules, and external",
-        "  `200` proxy rules.",
-        "- `_headers` — supported response headers.",
-        "- `404.html` — custom not-found page.",
-        "- `sf.jsonc` — serving config (index, fallback, listing, meta), the optional `space`",
-        "  link, and `redirects` / `rewrites` / `headers` arrays in the same matcher grammar",
-        "  the files use. JSON Schema: https://spacefast.com/schemas/sf.json",
-        "- `/llms.txt` and `/ai.txt` — publish these in the user's site when it should be",
-        "  agent-readable too.",
-        "- Plan limits surface as diagnostics, not failures you should guess at: publish the",
-        "  intended artifact, then read and report what the CLI or API says. When a feature",
-        `  is plan-gated, say: "Not available on ${PLAN_DEFINITIONS.free.name}. Available on ${SELF_SERVE_PLAN_CODES.map((code) => PLAN_DEFINITIONS[code].name).join(" and ")}."`,
-        "",
-        "## Agent-aware routing",
-        "",
-        `${BRAND.productName} supports an \`Agent=true\` condition in \`_redirects\` — a browser gets the HTML`,
-        "page, an agent fetch gets plain text at the same URL. For example:",
-        "",
-        "```text",
-        "/ai /ai.txt 200! Agent=true",
-        "```",
-        "",
-        "## Going deeper",
-        "",
-        "- Docs index for agents: https://spacefast.com/llms.txt",
-        "- One-click connect (Claude Code, Claude, Codex, Cursor, VS Code): https://spacefast.com/agents",
-        "- Agent guide: https://spacefast.com/docs/agents",
-        "- CLI reference: https://spacefast.com/docs/cli",
-        "- REST API + OpenAPI: https://spacefast.com/docs/api",
-        "- Publish contract (machine-readable): https://spacefast.com/publish-spec.json",
-        "- Connectors-directory manifest (hosted MCP listing): https://spacefast.com/.well-known/connector.json",
-        "- Every error code: https://spacefast.com/docs/errors",
-        "",
-        "Append `.md` to any docs URL for Markdown.",
-        "",
-        "## Environment notes",
-        "",
-        ENV_NOTES_PROSE,
-        "",
-    ].join("\n");
-}
 /*
- * The /setup.md document — the one URL every agent prompt points at. Modeled
- * on the Cloudflare/here.now agent-setup prompts: publish first with zero
- * install, then per-client setup for repeat use. Every command, endpoint,
- * deeplink, and config here is derived from the same canonical constants as
- * the plugin tree and the agent card, so this document can never drift from
- * what we ship. Keep it short enough that an agent reads it whole; the deep
- * contract stays in aiInstructionsText() (/ai.txt).
+ * The /setup.md document: publish first with zero install, then per-client setup
+ * for repeat use. Every command, endpoint, deeplink, and config is derived from
+ * the same constants as the plugin tree, so it cannot drift from what we ship.
+ * Keep it short enough that an agent reads it whole.
  */
 export function agentSetupMarkdown() {
-    const mcpEndpoint = serviceOrigin("mcp", "prod");
-    const dropUrl = `${serviceOrigin("dashboard", "prod")}/drop`;
+    const context = registryContext();
+    const dropUrl = `${context.dashboardOrigin}/drop`;
     return [
         `# ${BRAND.productName} agent setup`,
         "",
@@ -448,6 +408,21 @@ export function agentSetupMarkdown() {
         "",
         "Talk to the user before publishing. Confirm the file or folder they want to publish; if it isn't obvious, ask.",
         "",
+        "## Which lane to use",
+        "",
+        "Lead with the outcome:",
+        "",
+        "- **One file or a built folder** → publish now with the POST below. No install, no account.",
+        "- **A git checkout** → push to deploy (section below). The remote is the deploy.",
+        `- **Repeat work, and the environment allows installs** → the CLI is the best setup: \`${spacefastInstallCurlCommand}\``,
+        "  picks npm, bun, or a standalone binary for you and updates an existing install. `sf publish`",
+        "  deploys, `sf setup agent` signs your client in, and `sf plugins` installs your client's plugin.",
+        `  Have \`npx\`? \`${spacefastNpxCommand} <command>\` runs the same CLI with no install.`,
+        "- **No shell** → the hosted MCP endpoint or the skills lane below.",
+        "",
+        'If you cannot run commands or make HTTP requests at all, say so — see "If you',
+        "can't act on this page\".",
+        "",
         "## Before you publish — reuse an existing space",
         "",
         CHECK_BEFORE_PUBLISH_PROSE,
@@ -462,8 +437,7 @@ export function agentSetupMarkdown() {
         "",
         "For a folder, zip the public output only — never a repository root, never `.env*`,",
         "credentials, `.git`, or `.spacefast` — and send it as `-F archive=@site.zip` to the same",
-        "endpoint. Fetch the full contract when a publish goes beyond the happy path:",
-        `${agentSetupTextUrl}.`,
+        "endpoint.",
         "",
         "The JSON receipt is the result. **An anonymous space is private.** Until someone",
         "claims it, the only way in is the space key, so treat every link below as a",
@@ -486,6 +460,10 @@ export function agentSetupMarkdown() {
         "- `data.version.immutableUrl` — the permanent address of this exact version. Same",
         "  rule: it carries no authority of its own while the space is anonymous.",
         "",
+        "## Already in a git checkout? Push to deploy",
+        "",
+        PUSH_TO_DEPLOY_PROSE,
+        "",
         "## If you can't act on this page",
         "",
         "Reading this but unable to run commands or make HTTP requests — no shell, no",
@@ -504,110 +482,33 @@ export function agentSetupMarkdown() {
         "",
         'Use the section for your client. If yours isn\'t listed, use "Every other agent".',
         "",
-        "### Claude Code",
+        ...featuredAgentSections(context),
+        "### Every other agent",
         "",
-        "The plugin ships the publish skill plus MCP in one install:",
-        "",
-        "```bash",
-        spacefastClaudePluginAddCommand,
-        spacefastClaudePluginInstallCommand,
-        "```",
-        "",
-        "Restart Claude Code (or run `/reload-plugins`) to activate it. MCP-only alternative:",
-        "",
-        "```bash",
-        buildClaudeMcpAddCommand(mcpEndpoint),
-        "```",
-        "",
-        "### Codex",
-        "",
-        "```bash",
-        spacefastCodexPluginAddCommand,
-        spacefastCodexPluginInstallCommand,
-        "```",
-        "",
-        "Or teach every task in a repository with one AGENTS.md line:",
-        "",
-        "```text",
-        `To publish, fetch ${agentSetupUrl} and follow the instructions.`,
-        "```",
-        "",
-        "### Cursor",
-        "",
-        `One click: ${cursorHostedMcpDeeplink(mcpEndpoint)}`,
-        "",
-        "Or add to `~/.cursor/mcp.json`:",
-        "",
-        "```json",
-        JSON.stringify(cursorHostedMcpServersJson(mcpEndpoint), null, 2),
-        "```",
-        "",
-        "### VS Code",
-        "",
-        `One click: ${vscodeHostedMcpDeeplink(mcpEndpoint)}`,
-        "",
-        "Or add to `.vscode/mcp.json`:",
-        "",
-        "```json",
-        JSON.stringify(vscodeHostedMcpServersJson(mcpEndpoint), null, 2),
-        "```",
-        "",
-        "### Claude (web, desktop, and Cowork)",
-        "",
-        "Settings → Connectors → Add custom connector, paste the endpoint. Approve once in the",
-        "browser, nothing to install:",
-        "",
-        "```text",
-        mcpEndpoint,
-        "```",
-        "",
-        "On desktop, the extension is a double-click install:",
-        spacefastClaudeDesktopExtensionUrl,
-        "",
-        "### ChatGPT and ChatGPT Work",
-        "",
-        // TODO(plugin-directory): once the Spacefast listing is live, lead this
-        // section with the one-click Plugin Directory install instead.
-        "Publishing works from Work mode or the desktop app (paid plans) — follow the",
-        "publish-now section above; nothing to install. On ChatGPT Work, an admin can add",
-        "Spacefast once as a workspace app (Workspace settings → Apps) with the endpoint",
-        "below and deploy it to the whole team:",
-        "",
-        "```text",
-        mcpEndpoint,
-        "```",
-        "",
-        "If this ChatGPT can't run tools (Free plan, plain Chat), say so and point the user",
-        "at Work mode or the desktop app — see “If you can't act on this page”.",
-        "",
-        "### Every other agent (OpenClaw, Hermes, Raycast, Pi, OpenCode, Devin, Poke, Indent, …)",
-        "",
-        "Install the publish skill:",
+        "Install the publish skill — it works on every client that reads the Agent Skills standard:",
         "",
         "```bash",
         spacefastSkillInstallCommand,
         "```",
         "",
         "Clients that speak MCP add the hosted server; sign-in happens once on first tool use.",
-        "Hermes — one command:",
-        "",
-        "```bash",
-        buildHermesMcpAddCommand(mcpEndpoint),
-        "```",
-        "",
-        "OpenCode V2 — merge this schema-pinned config into `~/.config/opencode/opencode.json`:",
+        "The full entry, for any client whose config is a `mcpServers` map — a bare `url` is not",
+        "enough, several clients read one as a stdio command:",
         "",
         "```json",
-        JSON.stringify(opencodeHostedMcpConfig(mcpEndpoint), null, 2),
+        hostedMcpServersConfig(context),
         "```",
         "",
-        'Any other MCP client, under `"mcpServers"`:',
+        "Per client, the shortest path that works today:",
         "",
-        "```json",
-        `"spacefast": { "url": "${mcpEndpoint}" }`,
+        ...listedAgentRows(context),
+        "Teach a whole repository in one AGENTS.md line, whatever the client:",
+        "",
+        "```text",
+        `To publish, fetch ${agentSetupUrl} and follow the instructions.`,
         "```",
         "",
-        `Chat agents without tools (Pi, Poke): create a self-contained index.html and upload it at ${dropUrl}.`,
+        `Chat agents that cannot run tools at all: create a self-contained index.html and upload it at ${dropUrl}.`,
         "",
         "## After publishing",
         "",
@@ -618,7 +519,7 @@ export function agentSetupMarkdown() {
         "  a public post. Claiming is what turns the space into something shareable.",
         "- Persist the space id and credential so the next publish updates the same space instead",
         "  of creating a new one. The CLI and On-Device MCP do this automatically in `.spacefast/`.",
-        "  Hosted MCP is stateless between publishes: retain the receipt's `spaceId` in conversation",
+        "  Hosted MCP is stateless between publishes: retain `data.space.id` from the receipt in conversation",
         "  or project context and pass it explicitly on the next publish.",
         "- To update, post to the same endpoint with `--form-string 'spaceId=<spc_id>'` and the",
         "  saved bearer token.",
@@ -628,7 +529,6 @@ export function agentSetupMarkdown() {
         "",
         "## Resources",
         "",
-        `- Full publishing contract for agents: ${agentSetupTextUrl}`,
         `- One-POST publish spec (machine-readable): ${serviceOrigin("www", "prod")}/publish-spec.json`,
         `- Docs index for agents: ${serviceOrigin("www", "prod")}/llms.txt`,
         `- Human setup guides, per agent: ${serviceOrigin("www", "prod")}/setup`,