@spacefast/common 0.0.2

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

@@ -0,0 +1,35 @@
+export declare const ARCHIVE_SECRET_GLOBS: readonly [".env*", ".npmrc", ".netrc", "*/.git/*", "*/.stattic/*", "*/.ssh/*", "*/.aws/*", "*/.kube/*", "*/.docker/*", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*"];
+/**
+ * The credential rules every surface must repeat. Treat tokens as secrets, keep
+ * them out of logs and transcripts, and never echo them back.
+ */
+export declare const SECRET_RULES_PROSE: string;
+/**
+ * The zero-install publish sequence: one curl for a file, a secret-preflighted
+ * zip for a folder. This is the load-bearing rung 0 — an agent that stops here
+ * must still succeed.
+ */
+export declare const PUBLISH_SEQUENCE_PROSE: string;
+/**
+ * What the JSON publish receipt contains and how to read it. The receipt is the
+ * source of truth; never invent a separate success signal.
+ */
+export declare const RECEIPT_SHAPE_PROSE: string;
+/**
+ * The large/cloud-agent path. This keeps file bytes out of MCP JSON and chat
+ * transcripts while still giving agents a way to upload arbitrary artifacts.
+ */
+export declare const SIGNED_UPLOAD_PROSE: string;
+/**
+ * Named fragments for the skill-template generator. The template carries
+ * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
+ * `{{prose.receiptShape}}`, and `{{prose.signedUpload}}` placeholders;
+ * generate-skill.mjs substitutes these.
+ */
+export declare const AGENT_PROSE: {
+    readonly secretRules: string;
+    readonly publishSequence: string;
+    readonly receiptShape: string;
+    readonly signedUpload: string;
+};
+export type AgentProseKey = keyof typeof AGENT_PROSE;

package/dist/docs/agent-prose.js

@@ -0,0 +1,153 @@
+import { BRAND } from "../brand.js";
+// Single home for the agent-facing prose that was triplicated across the three
+// surfaces that teach an agent how to publish:
+//
+//   - packages/cli/skill.template.md  (the SKILL.md router + copies)
+//   - packages/common/src/docs/agent-setup.ts (the /ai and /ai.txt page body)
+//   - apps/www/src/lib/llmo.ts                (the agent-card / discovery prose)
+//
+// Each surface re-stated the publish sequence, the secret rules, and the receipt
+// shape in its own words, so they drifted. These fragments are the one source of
+// truth. They are plain Markdown strings (no surface-specific framing) so any
+// surface can splice them in: the skill template substitutes the `{{prose.*}}`
+// placeholders during generation, and the TS surfaces import the strings.
+//
+// Keep these grounded in the real API receipt and the real /v1/publish flow. If
+// the receipt shape or secret handling changes, change it here once.
+const API_ORIGIN = BRAND.apiOrigin;
+const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
+// Centralized secret/credential patterns excluded from a publish archive. The
+// `find` preflight and the `zip -x` exclusions are derived from the same list so
+// they can never disagree, and the no-install / skill copies stay identical.
+export const ARCHIVE_SECRET_GLOBS = [
+    ".env*",
+    ".npmrc",
+    ".netrc",
+    "*/.git/*",
+    "*/.stattic/*",
+    "*/.ssh/*",
+    "*/.aws/*",
+    "*/.kube/*",
+    "*/.docker/*",
+    "credentials.json",
+    "*.pem",
+    "*.key",
+    "*.p12",
+    "*.pfx",
+    "*.crt",
+    "*id_rsa*",
+];
+function findExpr(globs) {
+    return globs
+        .map((glob) => (glob.includes("/") ? `-path "${glob}"` : `-name "${glob}"`))
+        .join(" -o ");
+}
+function zipExcludeExpr(globs) {
+    // zip uses relative patterns: a leading "*/" is just a directory match, so
+    // collapse it to the directory glob the archive root sees.
+    return globs.map((glob) => `"${glob.replace(/^\*\//, "")}"`).join(" ");
+}
+/**
+ * The credential rules every surface must repeat. Treat tokens as secrets, keep
+ * them out of logs and transcripts, and never echo them back.
+ */
+export const SECRET_RULES_PROSE = [
+    "Treat claim tokens, upload tokens, device codes, and API keys as credentials. Do not print",
+    "them, paste them into chat, commit them, archive them, or include them in shared logs. Avoid",
+    "`set -x`, persistent shell history, CI log echoing, and command transcripts when secrets are",
+    "present. On shared hosts, prefer one-off environment variables or restrictive temporary files,",
+    "clear them after use, and avoid durable auth unless the user explicitly asks.",
+].join("\n");
+/**
+ * The zero-install publish sequence: one curl for a file, a secret-preflighted
+ * zip for a folder. This is the load-bearing rung 0 — an agent that stops here
+ * must still succeed.
+ */
+export const PUBLISH_SEQUENCE_PROSE = [
+    "Publish a single file:",
+    "",
+    "```bash",
+    `curl -sS -F "files=@index.html" ${PUBLISH_ENDPOINT}`,
+    "```",
+    "",
+    "Publish a folder by zipping only the intended public output root. Do not archive a repository",
+    "root or `.` blindly. Before zipping, confirm the publish root contains no secrets, source",
+    "control, auth state, or unrelated build/cache folders:",
+    "",
+    "```bash",
+    `find {publish-root} \\( ${findExpr(ARCHIVE_SECRET_GLOBS)} \\) -print`,
+    `(cd {publish-root} && zip -r ../spacefast-site.zip . -x ${zipExcludeExpr(ARCHIVE_SECRET_GLOBS)} "*.zip" "*.tar" "*.tgz")`,
+    `curl -sS -F archive=@spacefast-site.zip ${PUBLISH_ENDPOINT}`,
+    "```",
+    "",
+    "If the preflight prints credential-like files, stop and choose a narrower generated output",
+    "directory or remove those files from the publish root before uploading.",
+].join("\n");
+/**
+ * What the JSON publish receipt contains and how to read it. The receipt is the
+ * source of truth; never invent a separate success signal.
+ */
+export const RECEIPT_SHAPE_PROSE = [
+    "The JSON receipt is the source of truth:",
+    "",
+    "- `data.space.liveUrl` — the live URL.",
+    "- `data.version.immutableUrl` — the permanent, frozen version URL when available; share it for reviews.",
+    "- `data.shareBlurb` — a paste-ready one-liner with the URL and claim nudge; relay it verbatim when present.",
+    "- `data.upload` — signed upload instructions for manifest publishes when file bytes were not sent",
+    "  with the request. Send each `data.upload.targets[]` instruction exactly as returned, treat",
+    "  authorization headers and upload tokens as secrets, then finalize.",
+    "- `data.claim.url` and `data.claim.expiresAt` — the space is anonymous and expires unless claimed;",
+    "  always show the user the claim link and the deadline so the space becomes theirs.",
+    "- `data.claim.token` — a secret capability. Save it only when needed to update the space later, send it as",
+    "  `Authorization: Bearer <claim-token>` with the same `spaceId`, and never print it back to the user.",
+    "- `data.links.inspect`, `resume`, `finalize`, and `promote` — follow-up API paths.",
+    "- `error.code`, `error.docsUrl`, and `error.hint` — stable error code plus exact recovery docs and a next step.",
+    "",
+    "If no files changed, the API may omit `upload`; report the receipt and diagnostics rather than",
+    "inventing a separate success signal.",
+].join("\n");
+/**
+ * The large/cloud-agent path. This keeps file bytes out of MCP JSON and chat
+ * transcripts while still giving agents a way to upload arbitrary artifacts.
+ */
+export const SIGNED_UPLOAD_PROSE = [
+    "Use signed upload sessions when the artifact is large, the client is cloud-hosted, or inline/base64",
+    "content would be awkward. Start with a manifest instead of file bytes:",
+    "",
+    "```bash",
+    `curl -sS ${PUBLISH_ENDPOINT} \\`,
+    '  -H "content-type: application/json" \\',
+    '  -d \'{"files":[{"path":"index.html","size":1234,"contentType":"text/html","sha256":"...","sourceUrl":"https://example.com/index.html"}]}\'',
+    "```",
+    "",
+    "For each `data.upload.targets[]`, send `target.method` to `target.url` with `target.headers`.",
+    'If `target.body.kind` is `url`, send JSON `{ "url": target.body.url }`; otherwise send the',
+    "local file bytes for `target.path`. Then call `data.links.finalize` and share the final receipt.",
+    "If the session expires or only a page of files is returned, follow `data.links.resume`.",
+    "",
+    "For importing an archive that already lives somewhere else, prefer the import-from-link API:",
+    "",
+    "```bash",
+    "curl -sS https://api.spacefast.com/v1/spaces/{spaceId}/imports \\",
+    '  -H "content-type: application/json" \\',
+    '  -H "Authorization: Bearer $SPACEFAST_TOKEN" \\',
+    '  -d \'{"source":{"kind":"url","url":"https://example.com/site.zip"}}\'',
+    "```",
+    "",
+    "If the archive is only local to the agent, create an upload-sourced import, PUT the archive to",
+    "`{archiveUpload.baseUrl}/{archiveUpload.files[0]}` with the returned bearer token, then finalize",
+    "the import. If the token expires, fetch/resume the import for fresh `archiveUpload` instructions.",
+    "Do not base64 large archives into chat or MCP tool arguments.",
+].join("\n");
+/**
+ * Named fragments for the skill-template generator. The template carries
+ * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
+ * `{{prose.receiptShape}}`, and `{{prose.signedUpload}}` placeholders;
+ * generate-skill.mjs substitutes these.
+ */
+export const AGENT_PROSE = {
+    secretRules: SECRET_RULES_PROSE,
+    publishSequence: PUBLISH_SEQUENCE_PROSE,
+    receiptShape: RECEIPT_SHAPE_PROSE,
+    signedUpload: SIGNED_UPLOAD_PROSE,
+};

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

@@ -0,0 +1,6 @@
+export declare const agentSetupUrl: string;
+export declare const agentSetupTextUrl: string;
+export declare const agentSetupHostLabel: string;
+export declare const agentSetupPrompt: string;
+export declare function renderAgentSetupTemplate(value: string): string;
+export declare function aiInstructionsText(): string;

package/dist/docs/agent-setup.js

@@ -0,0 +1,164 @@
+import { BRAND } from "@spacefast/common/brand";
+import { PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, } from "@spacefast/common/docs/agent-prose";
+import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "@spacefast/common/docs/skill-distribution";
+export const agentSetupUrl = `${BRAND.agentSetupOrigin}/ai`;
+export const agentSetupTextUrl = `${BRAND.agentSetupOrigin}/ai.txt`;
+const agentSetupParsedUrl = new URL(agentSetupUrl);
+export const agentSetupHostLabel = agentSetupParsedUrl.host + agentSetupParsedUrl.pathname;
+export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow the instructions to publish for me. Ask me what I want to publish if it isn't obvious.`;
+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}, the static host where`,
+        "AI-made things are kept: permanent URLs, immutable versions, anonymous publish",
+        "with a claim link. Static files only — server code is never executed.",
+        "",
+        "## Publish with curl (no install, no account)",
+        "",
+        PUBLISH_SEQUENCE_PROSE,
+        "",
+        RECEIPT_SHAPE_PROSE,
+        "",
+        "## Big files and cloud agents",
+        "",
+        SIGNED_UPLOAD_PROSE,
+        "",
+        "## Secret handling",
+        "",
+        SECRET_RULES_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.",
+        "",
+        "## 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",
+        "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 --connect  # pick the right MCP lane and write client config",
+        "sf publish {file-or-dir}   # publish; prints live, version, and claim URLs",
+        "sf versions                # 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 `.stattic/state.json`.",
+        "",
+        "## MCP for agent clients",
+        "",
+        "Hosted MCP is the no-download cloud lane for ChatGPT, Codex, Claude, Cursor, and browser",
+        "clients that can authenticate with OAuth/API bearer credentials:",
+        "",
+        "```text",
+        "https://mcp.spacefast.com/mcp",
+        "```",
+        "",
+        "Request `mcp:tools` plus the API scopes the tools need: `teams:read` for team context,",
+        "`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",
+        "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_spacefast` is dry-run-first; mutating multi-step workflows can return",
+        "`approval_required` and continue through `resume_spacefast` after the user approves.",
+        "",
+        "Use On-Device MCP when the agent needs the user's checkout, path-based publish, or file edits:",
+        "",
+        "```bash",
+        "sf setup agent --agent auto --connect",
+        "sf mcp install --agent codex --mode hosted --connect",
+        "sf mcp install --agent codex --mode local --transport stdio --connect",
+        "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, fetch the official skill for the",
+        `complete command reference: \`${spacefastSkillInstallCommand}\` (source: ${spacefastSkillUrl}).`,
+        "",
+        "## After publishing",
+        "",
+        "- Share the live URL, the immutable version URL, and — for anonymous spaces — the",
+        "  claim link with its expiry.",
+        "- Never print access tokens, claim tokens, auth files, or `.stattic/state.json`.",
+        "",
+        "## Space conventions",
+        "",
+        "- `_redirects` — redirects, rewrites, SPA fallbacks, custom 404 rules, and external",
+        "  `200` proxy rules.",
+        "- `_headers` — response headers and Basic Auth rules.",
+        "- `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",
+        "- `/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.",
+        "",
+        "## 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. This very page uses it:",
+        "",
+        "```text",
+        "/ai /ai.txt 200! Agent=true",
+        "```",
+        "",
+        "## Going deeper",
+        "",
+        "- Docs index for agents: https://spacefast.com/llms.txt",
+        "- 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",
+        "- Every error code: https://spacefast.com/docs/errors",
+        "",
+        "Append `.md` to any docs URL for Markdown, or just fetch — agent user agents get",
+        "Markdown automatically.",
+        "",
+    ].join("\n");
+}

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

@@ -0,0 +1,110 @@
+export declare const hostedMcpEndpointUrl = "https://mcp.spacefast.com/mcp";
+export type AgentSolutionLane = "plugin" | "hosted-mcp" | "local-mcp" | "cli" | "prompt";
+export type AgentSolutionId = "codex" | "claude-code" | "claude-cowork" | "chatgpt" | "claude-ai" | "raycast" | "cursor" | "terminal" | "generic";
+export type AgentSolution = {
+    aliases: readonly string[];
+    commands?: readonly string[];
+    description: string;
+    detailGuideUrl?: string;
+    guideUrl: string;
+    id: AgentSolutionId;
+    label: string;
+    lane: AgentSolutionLane;
+    setupText: string;
+    summary: string;
+};
+export declare const agentSolutions: readonly [{
+    readonly id: "codex";
+    readonly label: "Codex";
+    readonly aliases: readonly ["codex cli", "codex plugin", "openai codex"];
+    readonly lane: "plugin";
+    readonly summary: "Recommended: Codex plugin.";
+    readonly description: "Install the Spacefast skill/plugin so Codex can publish, update, and inspect spaces from the same setup path.";
+    readonly commands: readonly ["npx skills add spacefast/plugins --skill spacefast -g"];
+    readonly guideUrl: `${string}/for-codex`;
+    readonly detailGuideUrl: `${string}/guides/how-to-use-with-codex`;
+    readonly setupText: string;
+}, {
+    readonly id: "claude-code";
+    readonly label: "Claude Code";
+    readonly aliases: readonly ["claude code", "claude cli"];
+    readonly lane: "plugin";
+    readonly summary: "Recommended: Claude plugin.";
+    readonly description: "Install the Spacefast Claude plugin once, then Claude Code can publish and operate spaces from the terminal.";
+    readonly commands: readonly ["claude plugin marketplace add spacefast/plugins", "claude plugin install spacefast@spacefast"];
+    readonly guideUrl: `${string}/for-claude`;
+    readonly detailGuideUrl: `${string}/guides/how-to-use-with-claude-code`;
+    readonly setupText: string;
+}, {
+    readonly id: "claude-cowork";
+    readonly label: "Claude Cowork";
+    readonly aliases: readonly ["cowork", "claude cowork"];
+    readonly lane: "plugin";
+    readonly summary: "Recommended: Claude plugin.";
+    readonly description: "Use the Spacefast Claude plugin path so Cowork gets the same publish instructions and MCP-aware setup as Claude Code.";
+    readonly commands: readonly ["claude plugin marketplace add spacefast/plugins", "claude plugin install spacefast@spacefast"];
+    readonly guideUrl: `${string}/for-claude`;
+    readonly detailGuideUrl: `${string}/guides/how-to-use-with-claude-cowork`;
+    readonly setupText: string;
+}, {
+    readonly id: "chatgpt";
+    readonly label: "ChatGPT";
+    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 commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly guideUrl: `${string}/docs/agents`;
+    readonly setupText: string;
+}, {
+    readonly id: "claude-ai";
+    readonly label: "Claude.ai";
+    readonly aliases: readonly ["claude.ai", "claude app", "claude web"];
+    readonly lane: "hosted-mcp";
+    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/mcp"];
+    readonly guideUrl: `${string}/docs/agents`;
+    readonly setupText: string;
+}, {
+    readonly id: "raycast";
+    readonly label: "Raycast";
+    readonly aliases: readonly ["raycast", "raycast ai"];
+    readonly lane: "hosted-mcp";
+    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/mcp"];
+    readonly guideUrl: `${string}/docs/agents`;
+    readonly setupText: string;
+}, {
+    readonly id: "cursor";
+    readonly label: "Cursor or MCP client";
+    readonly aliases: readonly ["cursor", "mcp client", "windsurf", "opencode"];
+    readonly lane: "local-mcp";
+    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 setupText: string;
+}, {
+    readonly id: "terminal";
+    readonly label: "Terminal or CI";
+    readonly aliases: readonly ["terminal", "cli", "ci", "github actions"];
+    readonly lane: "cli";
+    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 setupText: string;
+}, {
+    readonly id: "generic";
+    readonly label: "Generic agent prompt";
+    readonly aliases: readonly ["generic", "unknown", "gemini"];
+    readonly lane: "prompt";
+    readonly summary: "Recommended: generic prompt + setup contract.";
+    readonly description: "Use this when the client has no known plugin or MCP connector. The agent reads Spacefast's setup contract and picks the smallest working lane.";
+    readonly guideUrl: string;
+    readonly setupText: string;
+}];
+export declare function getAgentSolution(id: AgentSolutionId): AgentSolution;
+export declare function renderAgentSolutionIndexText(solutions?: readonly AgentSolution[]): string;

package/dist/docs/agent-solutions.js

@@ -0,0 +1,181 @@
+import { BRAND } from "../brand.js";
+import { agentSetupPrompt, agentSetupTextUrl, agentSetupUrl } from "./agent-setup.js";
+import { spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, spacefastCodexSkillInstallCommand, spacefastInstallCurlCommand, } from "./skill-distribution.js";
+export const hostedMcpEndpointUrl = "https://mcp.spacefast.com/mcp";
+function pluginText(label, commands, guideUrl) {
+    return [
+        `Set up ${BRAND.productName} for ${label}.`,
+        "",
+        "Run once:",
+        ...commands.map((command) => `  ${command}`),
+        "",
+        `Then ask ${label} to publish with ${BRAND.productName}.`,
+        `Guide: ${guideUrl}`,
+        `Generic agent contract: ${agentSetupUrl}`,
+    ].join("\n");
+}
+function hostedMcpText(label, guideUrl) {
+    return [
+        `Connect ${label} to ${BRAND.productName} with hosted MCP.`,
+        "",
+        `MCP endpoint: ${hostedMcpEndpointUrl}`,
+        "Transport: Streamable HTTP",
+        "Resource: https://api.spacefast.com/mcp",
+        "Minimum scope: mcp:tools",
+        "Common scopes: teams:read spaces:read spaces:write publish:write domains:read domains:write",
+        "",
+        "Hosted MCP is for cloud/browser agents. It does not read local paths; use the hosted workspace tools or signed uploads for artifacts.",
+        `Guide: ${guideUrl}`,
+        `Plain-text setup contract: ${agentSetupTextUrl}`,
+    ].join("\n");
+}
+function localMcpText(label, guideUrl) {
+    return [
+        `Set up ${BRAND.productName} for ${label} with local MCP when it needs your checkout or filesystem.`,
+        "",
+        `Install CLI: ${spacefastInstallCurlCommand}`,
+        "Configure the agent: sf setup agent --agent auto --connect",
+        "Install local stdio MCP: sf mcp install --agent auto --mode local --transport stdio --connect",
+        "Run stdio server directly: sf mcp",
+        "",
+        `Guide: ${guideUrl}`,
+        `Plain-text setup contract: ${agentSetupTextUrl}`,
+    ].join("\n");
+}
+export const agentSolutions = [
+    {
+        id: "codex",
+        label: "Codex",
+        aliases: ["codex cli", "codex plugin", "openai codex"],
+        lane: "plugin",
+        summary: "Recommended: Codex plugin.",
+        description: `Install the ${BRAND.productName} skill/plugin so Codex can publish, update, and inspect spaces from the same setup path.`,
+        commands: [spacefastCodexSkillInstallCommand],
+        guideUrl: `${BRAND.websiteOrigin}/for-codex`,
+        detailGuideUrl: `${BRAND.websiteOrigin}/guides/how-to-use-with-codex`,
+        setupText: pluginText("Codex", [spacefastCodexSkillInstallCommand], `${BRAND.websiteOrigin}/for-codex`),
+    },
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        aliases: ["claude code", "claude cli"],
+        lane: "plugin",
+        summary: "Recommended: Claude plugin.",
+        description: `Install the ${BRAND.productName} Claude plugin once, then Claude Code can publish and operate spaces from the terminal.`,
+        commands: [spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand],
+        guideUrl: `${BRAND.websiteOrigin}/for-claude`,
+        detailGuideUrl: `${BRAND.websiteOrigin}/guides/how-to-use-with-claude-code`,
+        setupText: pluginText("Claude Code", [spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand], `${BRAND.websiteOrigin}/guides/how-to-use-with-claude-code`),
+    },
+    {
+        id: "claude-cowork",
+        label: "Claude Cowork",
+        aliases: ["cowork", "claude cowork"],
+        lane: "plugin",
+        summary: "Recommended: Claude plugin.",
+        description: `Use the ${BRAND.productName} Claude plugin path so Cowork gets the same publish instructions and MCP-aware setup as Claude Code.`,
+        commands: [spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand],
+        guideUrl: `${BRAND.websiteOrigin}/for-claude`,
+        detailGuideUrl: `${BRAND.websiteOrigin}/guides/how-to-use-with-claude-cowork`,
+        setupText: pluginText("Claude Cowork", [spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, agentSetupPrompt], `${BRAND.websiteOrigin}/guides/how-to-use-with-claude-cowork`),
+    },
+    {
+        id: "chatgpt",
+        label: "ChatGPT",
+        aliases: ["chatgpt", "custom gpt", "openai apps"],
+        lane: "hosted-mcp",
+        summary: "Recommended: direct hosted MCP.",
+        description: `Connect ChatGPT-style cloud agents to ${BRAND.productName} through hosted MCP; use the virtual workspace or signed uploads instead of local paths.`,
+        commands: [hostedMcpEndpointUrl],
+        guideUrl: `${BRAND.websiteOrigin}/docs/agents`,
+        setupText: hostedMcpText("ChatGPT", `${BRAND.websiteOrigin}/docs/agents`),
+    },
+    {
+        id: "claude-ai",
+        label: "Claude.ai",
+        aliases: ["claude.ai", "claude app", "claude web"],
+        lane: "hosted-mcp",
+        summary: "Recommended: direct hosted MCP.",
+        description: `Connect the web Claude app to ${BRAND.productName} through hosted MCP when it cannot read your local checkout.`,
+        commands: [hostedMcpEndpointUrl],
+        guideUrl: `${BRAND.websiteOrigin}/docs/agents`,
+        setupText: hostedMcpText("Claude.ai", `${BRAND.websiteOrigin}/docs/agents`),
+    },
+    {
+        id: "raycast",
+        label: "Raycast",
+        aliases: ["raycast", "raycast ai"],
+        lane: "hosted-mcp",
+        summary: "Recommended: direct hosted MCP.",
+        description: `Use hosted MCP for Raycast and similar clients that can connect to a remote MCP server but should not need a local ${BRAND.productName} install.`,
+        commands: [hostedMcpEndpointUrl],
+        guideUrl: `${BRAND.websiteOrigin}/docs/agents`,
+        setupText: hostedMcpText("Raycast", `${BRAND.websiteOrigin}/docs/agents`),
+    },
+    {
+        id: "cursor",
+        label: "Cursor or MCP client",
+        aliases: ["cursor", "mcp client", "windsurf", "opencode"],
+        lane: "local-mcp",
+        summary: "Recommended: local MCP when it needs the checkout.",
+        description: `Use On-Device MCP for editor agents that need local files; use hosted MCP instead when they only need cloud-safe tools.`,
+        commands: [
+            "sf setup agent --agent auto --connect",
+            "sf mcp install --agent auto --mode local --transport stdio --connect",
+        ],
+        guideUrl: `${BRAND.websiteOrigin}/docs/agents`,
+        setupText: localMcpText("Cursor or another MCP client", `${BRAND.websiteOrigin}/docs/agents`),
+    },
+    {
+        id: "terminal",
+        label: "Terminal or CI",
+        aliases: ["terminal", "cli", "ci", "github actions"],
+        lane: "cli",
+        summary: `Recommended: ${BRAND.productName} CLI.`,
+        description: "Use the CLI for repeat publishes, CI jobs, JSON output, rollback, logs, and domains.",
+        commands: [spacefastInstallCurlCommand, "sf login", "sf publish {file-or-dir} --json"],
+        guideUrl: `${BRAND.websiteOrigin}/docs/cli`,
+        setupText: [
+            `Install CLI: ${spacefastInstallCurlCommand}`,
+            "Login: sf login",
+            "Publish: sf publish {file-or-dir} --json",
+            `Guide: ${BRAND.websiteOrigin}/docs/cli`,
+        ].join("\n"),
+    },
+    {
+        id: "generic",
+        label: "Generic agent prompt",
+        aliases: ["generic", "unknown", "gemini"],
+        lane: "prompt",
+        summary: "Recommended: generic prompt + setup contract.",
+        description: `Use this when the client has no known plugin or MCP connector. The agent reads ${BRAND.productName}'s setup contract and picks the smallest working lane.`,
+        guideUrl: agentSetupUrl,
+        setupText: agentSetupPrompt,
+    },
+];
+export function getAgentSolution(id) {
+    const solution = agentSolutions.find((entry) => entry.id === id);
+    if (!solution)
+        throw new Error(`Unknown agent solution: ${id}`);
+    return solution;
+}
+export function renderAgentSolutionIndexText(solutions = agentSolutions) {
+    return [
+        `# ${BRAND.productName} agent setup options`,
+        "",
+        ...solutions.flatMap((solution) => [
+            `## ${solution.label}`,
+            "",
+            `Recommended lane: ${solution.lane}`,
+            solution.summary,
+            solution.description,
+            "",
+            `Guide: ${solution.guideUrl}`,
+            solution.detailGuideUrl ? `Detailed guide: ${solution.detailGuideUrl}` : null,
+            "",
+            "Setup:",
+            solution.setupText,
+            "",
+        ].filter((line) => Boolean(line))),
+    ].join("\n");
+}