@spacefast/common 0.0.12 → 0.0.17

package/dist/docs/agent-setup.d.ts

@@ -3,6 +3,7 @@ export declare const agentSetupUrl: string;
 export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
 export declare const agentSetupPrompt: string;
+export declare const anonymousPublishCurlCommand: string;
 /**
  * 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
@@ -31,40 +32,42 @@ export type AgentHandoff = Readonly<{
 }>;
 /**
  * The single shared grammar for handoff links:
- * `<app-origin>/agent/<documentId>#<secret>`. The document ID must match
- * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
- * high-entropy and makes the public-projection leak check meaningful); the two must differ;
- * queries and embedded credentials are forbidden. The URL must sit exactly on the caller's
- * configured HTTP(S) app origin; that origin pin enforces scheme, hostname, and port without a
- * second host allowlist that would reject legitimate dev or container origins.
+ * `<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 declare function parseAgentHandoffUrl(value: string, expectedOrigin: string): Readonly<{
+export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string, documentOrigin?: string): Readonly<{
     documentId: string;
     documentUrl: string;
+    handoffUrl: string;
     secret: string;
 }>;
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export declare const AGENT_HANDOFF_CLI_TARGET_IDS: readonly ConnectTargetId[];
-export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to make public.";
+export declare 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 declare const AGENT_HANDOFF_FETCH_SAFETY = "Keep the original handoff link private. Fetching this document did not use the link or send its fragment secret; the secret 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 declare const AGENT_HANDOFF_FRAGMENT_HYGIENE = "Keep its fragment out of commands, request URLs, logs, and replies.";
+export declare 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 declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the private handoff URL out of commands, request URLs, logs, and replies.";
 export declare const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE: string;
 export declare const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Share the live URL and immutable version URL from the receipt.";
+export declare 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.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export declare function agentHandoffConnectSections(target: ConnectTarget): string[];
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
 export declare function buildAgentHandoff(input: {
     expectedOrigin: string;
+    documentOrigin?: string;
     mcpEndpoint: string;
     targetId: ConnectTargetId;
     url: string;
 }): AgentHandoff;
 export declare function renderAgentSetupTemplate(value: string): string;
 export declare function aiInstructionsText(): string;
+export declare function agentSetupMarkdown(): string;

package/dist/docs/agent-setup.js

@@ -1,16 +1,29 @@
-import { getConnectTarget, } from "../agents/connect-targets.js";
+import { buildClaudeMcpAddCommand, buildHermesMcpAddCommand, cursorHostedMcpDeeplink, cursorHostedMcpServersJson, getConnectTarget, opencodeHostedMcpConfig, vscodeHostedMcpDeeplink, vscodeHostedMcpServersJson, } from "../agents/connect-targets.js";
 import { BRAND } from "../brand.js";
+import { serviceOrigin } from "../config/domains.js";
+import { createBrowserCredentialUrl, parseBrowserCredentialUrl, } from "../utils/browser-credential.js";
 import { CHECK_BEFORE_PUBLISH_PROSE, CONTINUE_AFTER_CLAIM_PROSE, ENV_NOTES_PROSE, FAILURE_CONDUCT_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 { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "./skill-distribution.js";
-export const agentSetupUrl = `${BRAND.agentSetupOrigin}/ai`;
-export const agentSetupTextUrl = `${BRAND.agentSetupOrigin}/ai.txt`;
+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.
+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;
-export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow it to publish this project — or update it if it's already on ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
+// 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.
+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.
+export const anonymousPublishCurlCommand = `curl -F "files=@index.html" ${serviceOrigin("api", "prod")}/v1/publish`;
 /*
- * Agent handoff contract: links use https://<app-origin>/agent/<documentId>#<secret>, with
- * opaque document IDs and secrets. The fragment is the secret, so ordinary document fetches
- * never send or reveal it. Fetching never consumes a handoff; exactly one successful redemption
+ * 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
@@ -47,19 +60,18 @@ function isSafeHttpUrl(url) {
 }
 /**
  * The single shared grammar for handoff links:
- * `<app-origin>/agent/<documentId>#<secret>`. The document ID must match
- * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
- * high-entropy and makes the public-projection leak check meaningful); the two must differ;
- * queries and embedded credentials are forbidden. The URL must sit exactly on the caller's
- * configured HTTP(S) app origin; that origin pin enforces scheme, hostname, and port without a
- * second host allowlist that would reject legitimate dev or container origins.
+ * `<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) {
+export function parseAgentHandoffUrl(value, expectedOrigin, documentOrigin = expectedOrigin) {
     let expectedUrl;
     try {
         expectedUrl = new URL(expectedOrigin);
@@ -71,26 +83,54 @@ export function parseAgentHandoffUrl(value, expectedOrigin) {
         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 HTTP(S) URL.");
+        throw new TypeError("Agent handoff URL must be a valid private HTTP(S) URL.");
     }
-    const documentId = /^\/agent\/([^/]+)$/.exec(url.pathname)?.[1];
-    const secret = url.hash.slice(1);
+    const documentId = /^\/agent\/([^/]+)\/[^/]+$/.exec(url.pathname)?.[1];
+    const secret = parsedCredential.credential;
     if (url.origin !== canonicalExpectedOrigin ||
-        url.username !== "" ||
-        url.password !== "" ||
         value.includes("?") ||
+        url.hash !== "" ||
         !documentId ||
         !opaqueHandoffDocumentId.test(documentId) ||
         !opaqueHandoffSecret.test(secret) ||
         documentId === secret) {
-        throw new TypeError("Agent handoff URL must be an /agent/<id> URL on the app origin with one opaque fragment secret (16-512 chars, distinct from the id) and no credentials or query.");
+        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.");
     }
-    return { documentId, documentUrl: `${url.origin}${url.pathname}`, secret };
+    const handoffUrl = createBrowserCredentialUrl({
+        origin: canonicalExpectedOrigin,
+        path: "/agent",
+        publicId: documentId,
+        credential: secret,
+    });
+    return {
+        documentId,
+        documentUrl: new URL(`/agent/${encodeURIComponent(documentId)}`, canonicalDocumentOrigin).toString(),
+        handoffUrl,
+        secret,
+    };
 }
 function validateMcpEndpoint(value) {
     let url;
@@ -112,13 +152,13 @@ function validateMcpEndpoint(value) {
  */
 /** 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 make public.";
+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 document did not use the link or send its fragment secret; the secret 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_FRAGMENT_HYGIENE = "Keep its fragment out of commands, request URLs, logs, and replies.";
+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. Share the live URL and immutable version URL from the receipt.";
+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.";
 /** 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")] : []);
@@ -142,7 +182,7 @@ function renderAgentHandoffInstructions(documentUrl, target) {
             "## Continue the approved handoff",
             AGENT_HANDOFF_FETCH_SAFETY,
             approvalGuidance,
-            AGENT_HANDOFF_FRAGMENT_HYGIENE,
+            AGENT_HANDOFF_CREDENTIAL_HYGIENE,
         ].join("\n\n"),
         ["## Publish", AGENT_HANDOFF_PUBLISH_PROSE].join("\n\n"),
         `General agent instructions: ${agentSetupTextUrl}`,
@@ -151,12 +191,12 @@ function renderAgentHandoffInstructions(documentUrl, target) {
 }
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
 export function buildAgentHandoff(input) {
-    const { documentUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin);
+    const { documentUrl, handoffUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin, input.documentOrigin);
     const mcpEndpoint = validateMcpEndpoint(input.mcpEndpoint);
     const target = getConnectTarget(input.targetId, {
         mcpEndpoint,
     });
-    const prompt = `Fetch ${documentUrl}#${secret} and follow the ${target.name} setup instructions to publish with ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
+    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 },
@@ -188,7 +228,7 @@ export function buildAgentHandoff(input) {
         }),
     ];
     if (publicProjections.some((projection) => projection.includes(secret))) {
-        throw new TypeError("Agent handoff inputs would leak the fragment secret into a public projection.");
+        throw new TypeError("Agent handoff inputs would leak the private credential into a public projection.");
     }
     return { actions, documentUrl, instructions, prompt };
 }
@@ -244,13 +284,13 @@ export function aiInstructionsText() {
         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 JSON with stable `code` values and a",
-        "`docsUrl`; fetch the `docsUrl` when you need recovery steps.",
+        "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,",
-        "passwords, domains, logs, and diagnostics. Install it when the user will keep",
+        "sharing, domains, logs, and diagnostics. Install it when the user will keep",
         "working on the space:",
         "",
         "```bash",
@@ -282,7 +322,7 @@ export function aiInstructionsText() {
         LANE_PICKER_PROSE,
         "",
         "Hosted MCP is the no-download cloud lane for ChatGPT, Codex, Claude, Cursor, and browser",
-        "clients that can authenticate with OAuth/API bearer credentials:",
+        "clients that can authenticate with OAuth:",
         "",
         "```text",
         "https://mcp.spacefast.com",
@@ -291,26 +331,19 @@ export function aiInstructionsText() {
         "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,",
-        "`publish:write` for publish and rollback, and `domains:read`/`domains:write` for domain",
-        "inventory, DNS diagnostics, assignment, verification, and mutation. Hosted MCP does not read",
-        "local paths; its workspace tools operate on a durable virtual workspace attached to the MCP",
-        "session.",
-        "",
-        "For hosted MCP, prefer `prepare_publish`, `resume_publish`, and `finalize_publish` for large",
-        "artifacts so the agent uploads to signed URLs instead of stuffing bytes into tool calls. Use",
-        "`import_from_url` when the archive already has an HTTPS URL. Hosted MCP is the right path for",
+        "`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.",
-        "For generated files, use `workspace_write` or `workspace_import`, review with",
-        "`workspace_manifest` / `workspace_diff`, hand off with `workspace_export`, and publish the",
-        'virtual workspace with `publish({ path: "." })`.',
-        "Before acting on authenticated spaces, load MCP resources such as",
-        "`spacefast://account/current`, `spacefast://teams/current`, `spacefast://spaces/recent`,",
-        "`spacefast://spaces/{spaceId}`, and `spacefast://policy/current` for bounded read-only",
-        "context.",
-        "`execute` is dry-run-first; mutating multi-step workflows can return",
-        "`approval_required` and continue through `resume` after the user approves.",
-        "",
-        "Use On-Device MCP when the agent needs the user's checkout, path-based publish, or file edits:",
+        "`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 --connect",
@@ -329,8 +362,10 @@ export function aiInstructionsText() {
         "",
         "## After publishing",
         "",
-        "- Share the live URL, the immutable version URL when ready, and — for anonymous spaces —",
-        "  the claim link with its expiry. If the receipt's immutable URL is null, poll the",
+        "- 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 claim token as bearer auth until the version is ready.",
         "- Never print access tokens, claim tokens, auth files, or `.spacefast/state.json`.",
         "",
@@ -342,16 +377,16 @@ export function aiInstructionsText() {
         "",
         "- `_redirects` — redirects, rewrites, SPA fallbacks, custom 404 rules, and external",
         "  `200` proxy rules.",
-        "- `_headers` — response headers and Basic Auth rules.",
+        "- `_headers` — supported response headers.",
         "- `404.html` — custom not-found page.",
-        "- `sf.jsonc` — serving config (index, fallback, listing, meta) and the optional",
-        "  `space` link. JSON Schema: https://spacefast.com/schemas/sf.json",
+        "- `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 Free. Available on Personal and Work." For',
-        "  simple gated access, `sf password set` needs no plan and no `_headers` rule.",
+        '  is plan-gated, say: "Not available on Free. Available on Personal and Work."',
         "",
         "## Agent-aware routing",
         "",
@@ -366,7 +401,7 @@ export function aiInstructionsText() {
         "",
         "- 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",
+        "- Agent guide: https://spacefast.com/docs/getting-started/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",
@@ -382,3 +417,196 @@ export function aiInstructionsText() {
         "",
     ].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).
+ */
+export function agentSetupMarkdown() {
+    const mcpEndpoint = serviceOrigin("mcp", "prod");
+    const dropUrl = `${serviceOrigin("dashboard", "prod")}/drop`;
+    return [
+        `# ${BRAND.productName} agent setup`,
+        "",
+        `These are official instructions from ${BRAND.productName} for AI agents. Follow them to publish the user's file, folder, site, or app to a live URL — then, optionally, set up your own client so the next publish is one word. Every command on this page is validated by ${BRAND.productName} and ready to run.`,
+        "",
+        "Talk to the user before publishing. Confirm the file or folder they want to publish; if it isn't obvious, ask.",
+        "",
+        "## Before you publish — reuse an existing space",
+        "",
+        CHECK_BEFORE_PUBLISH_PROSE,
+        "",
+        "## Publish now — no install, no account",
+        "",
+        "Publish a single file with one POST:",
+        "",
+        "```bash",
+        anonymousPublishCurlCommand,
+        "```",
+        "",
+        "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}.`,
+        "",
+        "The JSON receipt is the result:",
+        "",
+        "- `data.space.liveUrl` — the live URL. Lead the reply with it.",
+        "- `data.version.immutableUrl` — the permanent address of this version.",
+        "- `data.claim.url` and `data.claim.expiresAt` — an anonymous space expires unless claimed.",
+        "  Always show the claim link and its deadline.",
+        "- `data.claim.token` — a secret. Use it as the bearer to update the same `spaceId`;",
+        "  never print it.",
+        "",
+        "## If you can't act on this page",
+        "",
+        "Reading this but unable to run commands or make HTTP requests — no shell, no",
+        "fetch-and-POST tool? Then this surface can't publish. Say that plainly and tell the",
+        "user what unlocks it:",
+        "",
+        "- In ChatGPT: switch to Work mode or the desktop app (paid plans). The Free plan",
+        "  can't publish.",
+        "- In any other client: enable its tool/agent mode, or pick a client from",
+        `  ${serviceOrigin("www", "prod")}/setup.`,
+        "",
+        "Don't fall back to generating files for the user to download and re-upload by hand",
+        "unless they ask for exactly that.",
+        "",
+        "## Set up your agent (optional, for repeat use)",
+        "",
+        'Use the section for your client. If yours isn\'t listed, use "Every other agent".',
+        "",
+        "### Claude Code",
+        "",
+        "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:",
+        "",
+        "```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.jsonc`:",
+        "",
+        "```json",
+        JSON.stringify(opencodeHostedMcpConfig(mcpEndpoint), null, 2),
+        "```",
+        "",
+        'Any other MCP client, under `"mcpServers"`:',
+        "",
+        "```json",
+        `"spacefast": { "url": "${mcpEndpoint}" }`,
+        "```",
+        "",
+        `Chat agents without tools (Pi, Poke): create a self-contained index.html and upload it at ${dropUrl}.`,
+        "",
+        "## After publishing",
+        "",
+        "- Report the live URL first, then the immutable version URL, then the claim link with",
+        "  its expiry.",
+        "- 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",
+        "  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.",
+        "- Recommend the matching setup above so the next publish is one word.",
+        "",
+        "## 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`,
+        `- CLI (versions, rollback, domains, logs): \`${spacefastInstallCurlCommand}\` — Windows PowerShell: \`${spacefastInstallPowerShellCommand}\``,
+        "- Every API error code: https://spacefast.com/docs/errors",
+        "",
+        `These instructions are published at ${agentSetupUrl} so you can re-verify their authenticity at any time.`,
+        "",
+    ].join("\n");
+}

package/dist/docs/agent-solutions.d.ts

@@ -52,9 +52,9 @@ export declare const agentSolutions: readonly [{
     readonly aliases: readonly ["chatgpt", "custom gpt", "openai apps"];
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
-    readonly description: "Connect ChatGPT-style cloud agents to Spacefast through hosted MCP; use the virtual workspace or signed uploads instead of local paths.";
+    readonly description: "Connect ChatGPT-style cloud agents to Spacefast through hosted MCP; use inline files or signed uploads instead of local paths.";
     readonly commands: readonly ["https://mcp.spacefast.com"];
-    readonly guideUrl: `${string}/docs/agents`;
+    readonly guideUrl: `${string}/getting-started/agents`;
     readonly setupText: string;
 }, {
     readonly id: "claude-ai";
@@ -64,7 +64,7 @@ export declare const agentSolutions: readonly [{
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Connect the web Claude app to Spacefast through hosted MCP when it cannot read your local checkout.";
     readonly commands: readonly ["https://mcp.spacefast.com"];
-    readonly guideUrl: `${string}/docs/agents`;
+    readonly guideUrl: `${string}/getting-started/agents`;
     readonly setupText: string;
 }, {
     readonly id: "raycast";
@@ -74,7 +74,7 @@ export declare const agentSolutions: readonly [{
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Use hosted MCP for Raycast and similar clients that can connect to a remote MCP server but should not need a local Spacefast install.";
     readonly commands: readonly ["https://mcp.spacefast.com"];
-    readonly guideUrl: `${string}/docs/agents`;
+    readonly guideUrl: `${string}/getting-started/agents`;
     readonly setupText: string;
 }, {
     readonly id: "cursor";
@@ -84,7 +84,7 @@ export declare const agentSolutions: readonly [{
     readonly summary: "Recommended: local MCP when it needs the checkout.";
     readonly description: "Use On-Device MCP for editor agents that need local files; use hosted MCP instead when they only need cloud-safe tools.";
     readonly commands: readonly ["sf setup agent --agent auto --connect", "sf mcp install --agent auto --mode local --transport stdio --connect"];
-    readonly guideUrl: `${string}/docs/agents`;
+    readonly guideUrl: `${string}/getting-started/agents`;
     readonly setupText: string;
 }, {
     readonly id: "terminal";
@@ -94,7 +94,7 @@ export declare const agentSolutions: readonly [{
     readonly summary: "Recommended: Spacefast CLI.";
     readonly description: "Use the CLI for repeat publishes, CI jobs, JSON output, rollback, logs, and domains.";
     readonly commands: readonly [string, "sf login", "sf publish {file-or-dir} --json"];
-    readonly guideUrl: `${string}/docs/cli`;
+    readonly guideUrl: `${string}/cli`;
     readonly setupText: string;
 }, {
     readonly id: "generic";