@spacefast/common 0.0.3 → 0.0.6

package/dist/docs/catalog.js

@@ -0,0 +1,758 @@
+// Canonical, single-sourced documentation catalog. This hand-curated product
+// content (guides + API reference + CLI + recipes) is the ONE source of truth
+// shared by two surfaces so they can never drift:
+//   - the CLI's offline `sf docs` index (packages/cli re-exports this module and
+//     derives the bundled `docs-index.generated.json` from it), and
+//   - the control-plane's machine-readable `GET /v1/docs` API, which builds the
+//     same index in memory at startup.
+//
+// Entries are tier-tagged from the SAME disclosure tiers the CLI help uses
+// (vocabulary.ts), so listings are ESSENTIAL by default and widen to FULL /
+// REFERENCE. Vocabulary rules apply: say "space", "publish", "version",
+// "channel", "API key", "infra" — never "deployment"/"project"/"site"/"E2B".
+//
+// The "error" kind entries below are GENERATED from ERROR_DOCS (error-docs.ts),
+// not hand-written — one catalog entry per ERROR_CODES member, reference tier —
+// so every error code is searchable from `sf docs <code>`, `GET /v1/docs?q=`,
+// and MCP search without a second hand-maintained corpus to drift.
+import { errorDocsUrl } from "../contracts/error-codes.js";
+import { ERROR_DOCS } from "./error-docs.js";
+/** Which part of the docs a page belongs to (runtime list + derived type). */
+export const DOC_KINDS = ["guide", "cli", "api", "recipe", "workflow", "error"];
+/** Base URL all bundled docs links resolve against. */
+export const DOCS_BASE_URL = "https://spacefast.com/docs";
+/** Base URL for the standalone recipe pages (served at /recipes, not /docs). */
+export const RECIPES_BASE_URL = "https://spacefast.com/recipes";
+const HAND_WRITTEN_DOCS_CATALOG = [
+    // ----- Guides -----------------------------------------------------------
+    {
+        slug: "quickstart",
+        title: "Quickstart",
+        kind: "guide",
+        tier: "essential",
+        summary: "Publish your first space in under two minutes.",
+        keywords: ["start", "getting started", "first", "new", "setup", "hello world"],
+        url: `${DOCS_BASE_URL}/quickstart`,
+        body: "Install the CLI, run `sf init` in your working directory, then `sf publish` to take the current build live on a new space.",
+    },
+    {
+        slug: "publishing",
+        title: "Publishing a space",
+        kind: "guide",
+        tier: "essential",
+        summary: "How `sf publish` builds, uploads, and goes live.",
+        keywords: ["publish", "go live", "upload", "release", "static"],
+        url: `${DOCS_BASE_URL}/publishing`,
+        body: "`sf publish` snapshots your output directory into an immutable version and promotes it to the production channel. Use `--no-wait` to return before serving finishes.",
+    },
+    {
+        slug: "versions-and-rollback",
+        title: "Versions and rollback",
+        kind: "guide",
+        tier: "essential",
+        summary: "Every publish is an immutable version you can roll back to.",
+        keywords: ["version", "rollback", "history", "revert", "channel", "promote"],
+        url: `${DOCS_BASE_URL}/rollback`,
+        body: "List versions with `sf versions`, promote one to a channel, and undo a bad publish instantly with `sf rollback`.",
+    },
+    {
+        slug: "anonymous-publish",
+        title: "Anonymous publish and claim",
+        kind: "guide",
+        tier: "essential",
+        summary: "Publish without an account, then claim the space with its token.",
+        keywords: ["anonymous", "claim", "unclaimed", "agent", "token", "adopt"],
+        url: `${DOCS_BASE_URL}/anonymous-publish`,
+        body: "Publish without logging in to get an instant URL and a claim token; run `sf spaces claim` with that token to bind the space to your account.",
+    },
+    {
+        slug: "agents",
+        title: "Agents and MCP",
+        kind: "guide",
+        tier: "essential",
+        summary: "Let an AI agent publish and operate spaces via the CLI, API, or MCP.",
+        keywords: ["agent", "ai", "mcp", "model context protocol", "automation", "assistant"],
+        url: `${DOCS_BASE_URL}/agents`,
+        body: "Agents use the same REST API and CLI as humans. Install the MCP server with `sf mcp install` so an assistant can publish, inspect, and manage spaces with structured tools.",
+    },
+    // ----- Agent workflows --------------------------------------------------
+    {
+        slug: "workflow/publish-curl",
+        title: "No-install publish with curl",
+        kind: "workflow",
+        tier: "full",
+        summary: "Publish a file or zipped output folder directly to /v1/publish. No account, CLI install, or MCP setup is required for anonymous publishes.",
+        keywords: ["publish", "curl", "anonymous", "no install", "claim"],
+        url: `${DOCS_BASE_URL}/agents#publish-with-curl`,
+        body: "curl publish static file folder archive zip anonymous no account no install live URL immutable version claim link /v1/publish",
+    },
+    {
+        slug: "workflow/publish-receipt",
+        title: "Publish receipt fields",
+        kind: "workflow",
+        tier: "full",
+        summary: "Use the receipt as the source of truth: space.liveUrl, version.immutableUrl, shareBlurb, claim.url, claim.expiresAt, links, diagnostics, and errors.",
+        keywords: ["receipt", "share", "claim", "diagnostics"],
+        url: `${DOCS_BASE_URL}/api#publish`,
+        body: "receipt liveUrl immutableUrl shareBlurb claim url expiresAt diagnostics links finalize promote upload errors docsUrl",
+    },
+    {
+        slug: "workflow/continue-after-claim",
+        title: "Keep publishing after the user claims",
+        kind: "workflow",
+        tier: "full",
+        summary: "After the owner claims an anonymous space with continuation enabled, exchange the saved claim token once for a durable space-scoped access token, save it over the claim token, and keep publishing.",
+        keywords: [
+            "continue",
+            "exchange",
+            "claim token",
+            "space_claimed_credential_available",
+            "continuation",
+        ],
+        url: `${DOCS_BASE_URL}/agents#continue-after-claim`,
+        body: "continue continuation claim token exchange voucher continue_space POST /v1/anonymous-claim/exchange space_claimed_credential_available continuation_used continuation_unavailable durable access token state.json update after claim claim_status",
+    },
+    {
+        slug: "workflow/secret-handling",
+        title: "Secret handling rules",
+        kind: "workflow",
+        tier: "full",
+        summary: "Treat claim tokens, upload tokens, device codes, API keys, auth files, and .spacefast state as credentials. Do not print, commit, archive, or log them.",
+        keywords: ["secret", "token", "claim token", "redact"],
+        url: `${DOCS_BASE_URL}/agents#secret-handling`,
+        body: "secret handling claim token upload token device code API key auth file .spacefast state redact logs transcripts archive",
+    },
+    {
+        slug: "workflow/cli-surface",
+        title: "CLI command surface",
+        kind: "workflow",
+        tier: "full",
+        summary: "Use sf for repeat work: publish, versions, rollback, logs, domains, passwords, teams, API calls, and On-Device MCP serving.",
+        keywords: ["sf", "cli", "spacefast", "mcp", "json"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "sf spacefast CLI publish versions rollback logs domains passwords teams api mcp setup profile login --json",
+    },
+    {
+        slug: "workflow/mcp-local",
+        title: "On-Device MCP through the CLI",
+        kind: "workflow",
+        tier: "full",
+        summary: "Run sf mcp for stdio or sf mcp http --host 127.0.0.1 --port 3945 --path /mcp for On-Device Streamable HTTP.",
+        keywords: ["mcp", "stdio", "streamable http", "on-device", "local"],
+        url: `${DOCS_BASE_URL}/agents#mcp`,
+        body: "MCP on-device local CLI stdio streamable HTTP sf mcp roots files workspace tool calls structuredContent apps",
+    },
+    {
+        slug: "workflow/workspace-files",
+        title: "Agent workspace files",
+        kind: "workflow",
+        tier: "full",
+        summary: "Hosted MCP workspace tools edit, import, export, and publish a durable virtual workspace; On-Device MCP workspace tools edit the bounded local root.",
+        keywords: [
+            "workspace",
+            "files",
+            "patch",
+            "diff",
+            "virtual workspace",
+            "workspace import",
+            "workspace export",
+            "just-bash",
+        ],
+        url: `${DOCS_BASE_URL}/agents#workspace-files`,
+        body: "workspace file editing read write patch diff list manifest import export import_url hosted virtual workspace just-bash shell handoff on-device root SPACEFAST_MCP_WORKSPACE_ROOT secret scanning bounded files",
+    },
+    {
+        slug: "workflow/mcp-resources",
+        title: "MCP resources for account, teams, spaces, and policy",
+        kind: "workflow",
+        tier: "full",
+        summary: "Use read-only resources for bounded context before tools: account/current, teams/current, spaces/recent, space detail, recent versions, policy/current, and workspace/manifest.",
+        keywords: ["resources", "account", "teams", "spaces", "policy", "context"],
+        url: `${DOCS_BASE_URL}/agents#mcp-resources`,
+        body: "MCP resources account current teams current list spaces recent space detail versions recent domains logs summary policy current workspace manifest tools catalog read-only context redacted",
+    },
+    {
+        slug: "workflow/space-files",
+        title: "Space file conventions",
+        kind: "workflow",
+        tier: "full",
+        summary: "Spacefast recognizes _redirects, _headers, nearest 404.html, and sf.jsonc. Static artifacts are served as files; server code is not executed.",
+        keywords: ["_redirects", "_headers", "sf.jsonc", "spacefast.jsonc", "404"],
+        url: `${DOCS_BASE_URL}/configuration`,
+        body: "_redirects _headers 404.html sf.jsonc static artifact server code not executed proxy rewrite headers basic auth",
+    },
+    {
+        slug: "workflow/domains-diagnostics",
+        title: "Domains and DNS diagnostics",
+        kind: "workflow",
+        tier: "full",
+        summary: "Use domain diagnostics for attach, verification, DNS, nameserver, and rollback-safe recovery steps.",
+        keywords: ["domain", "dns", "verification"],
+        url: `${DOCS_BASE_URL}/domains`,
+        body: "domains DNS diagnostics attach verification nameservers custom domain certificate recovery instructions",
+    },
+    {
+        slug: "workflow/logs-diagnostics",
+        title: "Logs and diagnostics",
+        kind: "workflow",
+        tier: "full",
+        summary: "Use access logs for traffic questions, runtime logs for serving diagnostics, and build logs for publish/finalize failures.",
+        keywords: ["logs", "diagnostics", "build logs"],
+        url: `${DOCS_BASE_URL}/builds#watch-and-manage-builds`,
+        body: "logs access runtime build diagnostics publish finalize failures request id docsUrl suggestions recovery",
+    },
+    {
+        slug: "workflow/agent-auth",
+        title: "Agent accounts and OAuth",
+        kind: "workflow",
+        tier: "full",
+        summary: "Prefer OAuth agent accounts with private_key_jwt and SPACEFAST_AGENT_CONFIG for On-Device MCP and automation instead of broad shared API keys.",
+        keywords: ["oauth", "agent account", "private_key_jwt", "SPACEFAST_AGENT_CONFIG"],
+        url: `${DOCS_BASE_URL}/agents#agent-accounts`,
+        body: "OAuth agent account private_key_jwt SPACEFAST_AGENT_CONFIG client credentials scoped token mcp automation teams",
+    },
+    {
+        slug: "custom-domains",
+        title: "Custom domains",
+        kind: "guide",
+        tier: "full",
+        summary: "Attach your own domain and let Spacefast manage TLS.",
+        keywords: ["domain", "dns", "https", "tls", "certificate", "cname", "nameserver"],
+        url: `${DOCS_BASE_URL}/domains`,
+        body: "Add a domain with `sf domains add`, point DNS at Spacefast, and a certificate is issued automatically. Inspect status with `sf domains check`.",
+    },
+    {
+        slug: "configuration",
+        title: "Configuration (sf.jsonc)",
+        kind: "guide",
+        tier: "full",
+        summary: "Ship space metadata and SPA settings alongside your files.",
+        keywords: ["config", "sf.jsonc", "spacefast.jsonc", "metadata", "spa", "schema", "settings"],
+        url: `${DOCS_BASE_URL}/configuration`,
+        body: "Add `sf.jsonc` at your publish root so configuration travels with each version and rolls back with it. `sf init` scaffolds it with a `$schema` pointer for autocomplete.",
+    },
+    {
+        slug: "environment-variables",
+        title: "Environment variables",
+        kind: "guide",
+        tier: "full",
+        summary: "Set build-time configuration and secrets per space.",
+        keywords: ["env", "environment", "secrets", "config", "variables", "dotenv"],
+        url: `${DOCS_BASE_URL}/configuration`,
+        body: "Manage a space's variables with `sf env set` / `sf env ls`, or import a dotenv file with `sf env import`. Secret values are masked in `--json` output.",
+    },
+    {
+        slug: "access-control",
+        title: "Access control",
+        kind: "guide",
+        tier: "full",
+        summary: "Password-protect a space or grant access to specific people.",
+        keywords: ["access", "password", "grant", "ban", "private", "audience", "auth"],
+        url: `${DOCS_BASE_URL}/access`,
+        body: "Gate a space with `sf password set`, grant individuals with `sf access grant`, and review effective rules with `sf access effective`.",
+    },
+    {
+        slug: "redirects",
+        title: "Redirects",
+        kind: "guide",
+        tier: "full",
+        summary: "Declare redirect rules that travel with each version.",
+        keywords: ["redirect", "rewrite", "routing", "301", "302", "_redirects"],
+        url: `${DOCS_BASE_URL}/redirects`,
+        body: "Add a `_redirects` file at your publish root to redirect, rewrite, or proxy; it compiles at finalize and rolls back with the version. Inspect resolution with `sf routing inspect`.",
+    },
+    {
+        slug: "headers",
+        title: "Custom headers",
+        kind: "guide",
+        tier: "full",
+        summary: "Attach response headers and path-scoped Basic Auth.",
+        keywords: ["headers", "cache", "security", "basic auth", "_headers", "cors"],
+        url: `${DOCS_BASE_URL}/headers`,
+        body: "Add a `_headers` file at your publish root to set or remove response headers per path. Path-scoped Basic Auth credentials travel with the publish.",
+    },
+    {
+        slug: "builds",
+        title: "Build from Git",
+        kind: "guide",
+        tier: "full",
+        summary: "Connect a repository so pushes build and publish automatically.",
+        keywords: ["build", "git", "github", "ci", "push", "connect", "preview"],
+        url: `${DOCS_BASE_URL}/builds`,
+        body: "Connect a repository with `sf git connect`; each push runs your build on Spacefast and publishes a version, with branches and pull requests getting preview URLs.",
+    },
+    {
+        slug: "collab",
+        title: "Collaboration and annotations",
+        kind: "guide",
+        tier: "full",
+        summary: "Leave review comments on a published space.",
+        keywords: ["collab", "annotations", "comments", "review", "feedback", "annotate"],
+        url: `${DOCS_BASE_URL}/collab`,
+        body: "Annotate a live space with review comments and resolve them from the CLI with `sf annotations` or in the dashboard.",
+    },
+    {
+        slug: "analytics",
+        title: "Analytics",
+        kind: "guide",
+        tier: "full",
+        summary: "See traffic and visitor counts for a space.",
+        keywords: ["analytics", "traffic", "visitors", "stats", "metrics", "pageviews"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "Inspect a space's traffic with `sf analytics`; history depth and granularity depend on the team's plan.",
+    },
+    {
+        slug: "proxy-routes",
+        title: "Proxy routes",
+        kind: "guide",
+        tier: "reference",
+        summary: "Proxy selected paths to an upstream origin.",
+        keywords: ["proxy", "upstream", "route", "api", "backend", "rewrite"],
+        url: `${DOCS_BASE_URL}/proxy-routes`,
+        body: "Forward specific path prefixes to an external upstream so a static space can front a dynamic API without exposing the origin.",
+    },
+    {
+        slug: "image-acceleration",
+        title: "Image acceleration",
+        kind: "guide",
+        tier: "reference",
+        summary: "Serve optimized, resized images from your space.",
+        keywords: ["image", "images", "optimization", "resize", "cdn", "acceleration"],
+        url: `${DOCS_BASE_URL}/image-acceleration`,
+        body: "Spacefast can resize and re-encode images on the fly so you ship one source asset and serve device-appropriate variants.",
+    },
+    {
+        slug: "integrations/nextjs",
+        title: "Next.js integration",
+        kind: "guide",
+        tier: "reference",
+        summary: "Publish a Next.js static export to a space.",
+        keywords: ["nextjs", "next", "react", "framework", "integration", "export"],
+        url: `${DOCS_BASE_URL}/integrations/nextjs`,
+        body: "Build your Next.js static export and publish the output directory with `sf publish`; `sf init` detects the framework and sets the output path.",
+    },
+    {
+        slug: "integrations/vite",
+        title: "Vite integration",
+        kind: "guide",
+        tier: "reference",
+        summary: "Publish a Vite build to a space.",
+        keywords: ["vite", "react", "vue", "svelte", "framework", "integration", "build"],
+        url: `${DOCS_BASE_URL}/integrations/vite`,
+        body: "Run your Vite build and publish `dist/` with `sf publish`; `sf init` detects Vite and preconfigures the output directory.",
+    },
+    {
+        slug: "limits",
+        title: "Limits and quotas",
+        kind: "guide",
+        tier: "reference",
+        summary: "File counts, sizes, and rate limits per plan.",
+        keywords: ["limits", "quota", "size", "rate limit", "plan", "storage"],
+        url: `${DOCS_BASE_URL}/limits`,
+        body: "Reference for per-space file counts, archive and file size ceilings, version retention, and rate limits, which vary by plan.",
+    },
+    {
+        slug: "troubleshooting",
+        title: "Troubleshooting",
+        kind: "guide",
+        tier: "reference",
+        summary: "Diagnose failed publishes, builds, and domains.",
+        keywords: ["troubleshoot", "debug", "error", "doctor", "diagnose", "fix"],
+        url: `${DOCS_BASE_URL}/troubleshooting`,
+        body: "Common publish, build, and domain failures and how to resolve them. Run `sf doctor` to check your local setup and auth state.",
+    },
+    {
+        slug: "migrate-from",
+        title: "Migrate to Spacefast",
+        kind: "guide",
+        tier: "reference",
+        summary: "Move from Netlify, Vercel, and other hosts.",
+        keywords: ["migrate", "netlify", "vercel", "cloudflare", "github pages", "here.now", "import"],
+        url: `${DOCS_BASE_URL}/migrate-from`,
+        body: "Step-by-step migrations that map another host's build output, redirects, and headers onto a Spacefast space.",
+    },
+    // ----- CLI reference ----------------------------------------------------
+    {
+        slug: "cli",
+        title: "CLI overview",
+        kind: "cli",
+        tier: "essential",
+        summary: "Install, authenticate, and the first-publish command path.",
+        keywords: ["cli", "sf", "command", "install", "overview", "help"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "Run `sf help` for the essential commands, `sf help --full` for everything. The CLI emits a `{ data }` / `{ error }` JSON envelope under `--json`.",
+    },
+    {
+        slug: "cli/publish",
+        title: "sf publish",
+        kind: "cli",
+        tier: "essential",
+        summary: "Build, upload, and take the current output live on a space.",
+        keywords: ["publish", "sf publish", "go live", "upload", "release"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf publish [DIR]` snapshots a directory into an immutable version and promotes it to the production channel. Add `--no-wait` to return before serving finishes.",
+    },
+    {
+        slug: "login",
+        title: "sf login",
+        kind: "cli",
+        tier: "essential",
+        summary: "Authenticate the CLI with your Spacefast account.",
+        keywords: ["login", "auth", "authenticate", "token", "device", "signin"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf login` starts the device-authorization flow; for non-interactive use pass `--token` or set `SPACEFAST_TOKEN`.",
+    },
+    {
+        slug: "init",
+        title: "sf init",
+        kind: "cli",
+        tier: "essential",
+        summary: "Scaffold an sf.jsonc config in the current directory.",
+        keywords: ["init", "config", "scaffold", "sf.jsonc", "setup"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf init` detects your framework and writes a starter `sf.jsonc` so subsequent `sf publish` runs are zero-config.",
+    },
+    {
+        slug: "claim",
+        title: "sf spaces claim",
+        kind: "cli",
+        tier: "essential",
+        summary: "Attach an anonymously-published space to your account.",
+        keywords: ["claim", "anonymous", "attach", "token", "adopt", "spaces"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "After an agent publishes anonymously, run `sf spaces claim` with the claim token to bind the space to your account.",
+    },
+    {
+        slug: "cli/spaces",
+        title: "sf spaces",
+        kind: "cli",
+        tier: "full",
+        summary: "List, inspect, transfer, import, and remove spaces.",
+        keywords: ["spaces", "space", "ls", "get", "rm", "transfer", "import", "export"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "The `sf spaces` group manages spaces: `ls`, `get`, `claim`, `transfer`, `duplicate`, `import`/`export`, and `rm`.",
+    },
+    {
+        slug: "cli/versions",
+        title: "sf versions",
+        kind: "cli",
+        tier: "full",
+        summary: "List, inspect, download, and remove immutable versions.",
+        keywords: ["versions", "version", "ls", "get", "download", "rollback", "history"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf versions ls` shows a space's history; `sf versions get` inspects one and `sf rollback` promotes an earlier version back to live.",
+    },
+    {
+        slug: "cli/channels",
+        title: "sf channels",
+        kind: "cli",
+        tier: "full",
+        summary: "List channels and see which version each points at.",
+        keywords: ["channels", "channel", "promote", "production", "preview", "history"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf channels ls` lists a space's channels and their current version; `sf channels history` shows past pointer moves. Move a channel with `sf promote`.",
+    },
+    {
+        slug: "cli/domains",
+        title: "sf domains",
+        kind: "cli",
+        tier: "full",
+        summary: "Add, check, and manage custom domains and DNS.",
+        keywords: ["domains", "domain", "dns", "add", "check", "nameservers", "diagnostics"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "The `sf domains` group covers `add`, `check`, `diagnostics`, `ls`, `rm`, and a full `dns` subtree for managing records and nameservers.",
+    },
+    {
+        slug: "cli/env",
+        title: "sf env",
+        kind: "cli",
+        tier: "full",
+        summary: "Set, list, import, and pull a space's variables.",
+        keywords: ["env", "environment", "variables", "secrets", "set", "import", "pull"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf env set` / `sf env ls` manage a space's variables; `sf env import` loads a dotenv file and `sf env pull` writes them back out.",
+    },
+    {
+        slug: "cli/builds",
+        title: "sf builds",
+        kind: "cli",
+        tier: "full",
+        summary: "List, inspect, and retry cloud builds.",
+        keywords: ["builds", "build", "ls", "logs", "retry", "cancel", "ci"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf builds ls` lists cloud builds; `sf builds logs`, `sf builds retry`, and `sf builds cancel` operate on a single build.",
+    },
+    {
+        slug: "cli/git",
+        title: "sf git",
+        kind: "cli",
+        tier: "full",
+        summary: "Connect a repository for push-to-publish builds.",
+        keywords: ["git", "github", "connect", "repository", "ci", "sync", "disconnect"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf git connect` links a repository so pushes build and publish automatically; `sf git ls`, `sf git sync`, and `sf git disconnect` manage the connection.",
+    },
+    {
+        slug: "cli/access",
+        title: "sf access",
+        kind: "cli",
+        tier: "full",
+        summary: "Grant, ban, and inspect who can view a space.",
+        keywords: ["access", "grant", "ban", "password", "effective", "rules", "policy"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf access grant` / `sf access ban` edit access rules; `sf access effective` shows the resolved policy. Use `sf password set` for a shared password.",
+    },
+    {
+        slug: "cli/teams",
+        title: "sf teams",
+        kind: "cli",
+        tier: "full",
+        summary: "Create teams, invite members, and switch context.",
+        keywords: ["teams", "team", "members", "invitations", "switch", "create"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf teams create` makes a team, `sf teams invitations add` invites people, `sf teams members ls` lists them, and `sf teams switch` sets the active team.",
+    },
+    {
+        slug: "cli/api-keys",
+        title: "sf api-keys",
+        kind: "cli",
+        tier: "full",
+        summary: "Create and revoke API keys for the platform API.",
+        keywords: ["api-keys", "api key", "token", "create", "revoke", "list", "credential"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf api-keys create` mints a bearer key (shown once, masked in `--json`); `sf api-keys list` and `sf api-keys revoke` manage existing keys.",
+    },
+    {
+        slug: "cli/analytics",
+        title: "sf analytics",
+        kind: "cli",
+        tier: "full",
+        summary: "Print traffic and visitor counts for a space.",
+        keywords: ["analytics", "traffic", "visitors", "stats", "metrics"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf analytics` reports a space's traffic; history depth and granularity depend on the team's plan.",
+    },
+    {
+        slug: "cli/api",
+        title: "sf api",
+        kind: "cli",
+        tier: "full",
+        summary: "Make an authenticated raw call to the platform API.",
+        keywords: ["api", "sf api", "http", "raw", "request", "curl", "endpoint"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf api <METHOD> <PATH>` sends an authenticated request against the platform API and prints the `{ data }` / `{ error }` envelope — handy for endpoints without a dedicated command.",
+    },
+    {
+        slug: "cli/mcp",
+        title: "sf mcp",
+        kind: "cli",
+        tier: "full",
+        summary: "Run and install the Spacefast MCP server.",
+        keywords: ["mcp", "model context protocol", "agent", "install", "server", "tools"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf mcp` runs the MCP server so an AI assistant can call Spacefast tools; `sf mcp install` wires it into a supported client's config.",
+    },
+    {
+        slug: "cli/docs",
+        title: "sf docs",
+        kind: "cli",
+        tier: "full",
+        summary: "Search the offline documentation index from the CLI.",
+        keywords: ["docs", "search", "help", "reference", "offline", "topic"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "`sf docs` lists documentation topics and `sf docs <topic>` prints a page. The index ships with the CLI and mirrors the machine-readable `GET /v1/docs` API.",
+    },
+    {
+        slug: "json-output",
+        title: "JSON output and exit codes",
+        kind: "cli",
+        tier: "full",
+        summary: "Machine-readable envelopes and stable exit codes for scripts.",
+        keywords: ["json", "exit code", "scripting", "envelope", "automation", "ci", "agent"],
+        url: `${DOCS_BASE_URL}/cli`,
+        body: "Pass `--json` for a `{ data }` success or `{ error }` failure envelope on stdout/stderr. Exit codes are stable so scripts and agents can branch on them.",
+    },
+    // ----- API reference ----------------------------------------------------
+    {
+        slug: "api",
+        title: "Platform API overview",
+        kind: "api",
+        tier: "full",
+        summary: "Authenticate and call the Spacefast platform API.",
+        keywords: ["api", "rest", "http", "platform", "endpoint", "openapi", "bearer"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "The platform API uses bearer API keys and returns the same `{ data }` / `{ error }` envelope as the CLI. Create a key with `sf api-keys create`.",
+    },
+    {
+        slug: "api/publish",
+        title: "Publish API",
+        kind: "api",
+        tier: "full",
+        summary: "Publish a version in a single authenticated request.",
+        keywords: ["api", "publish", "upload", "version", "archive", "http"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "Send your files in one authenticated publish request to create an immutable version and take it live; the response carries the space and live URL.",
+    },
+    {
+        slug: "api/spaces",
+        title: "Spaces API",
+        kind: "api",
+        tier: "full",
+        summary: "Create, list, and update spaces over HTTP.",
+        keywords: ["api", "spaces", "space", "create", "list", "endpoint"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "`GET /v1/spaces` lists spaces; `POST /v1/spaces` creates one. Responses carry the space id, slug, and live URL.",
+    },
+    {
+        slug: "api/versions",
+        title: "Versions API",
+        kind: "api",
+        tier: "full",
+        summary: "List versions and promote them to channels over HTTP.",
+        keywords: ["api", "versions", "publish", "channel", "promote", "rollback"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "List a space's versions, then promote one to a channel to move traffic. Rolling back is promoting an earlier version.",
+    },
+    {
+        slug: "api/domains",
+        title: "Domains API",
+        kind: "api",
+        tier: "reference",
+        summary: "Attach and inspect custom domains over HTTP.",
+        keywords: ["api", "domains", "domain", "dns", "certificate", "endpoint"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "Add a custom domain, read its verification and certificate status, and manage DNS records through the platform API.",
+    },
+    {
+        slug: "api/teams",
+        title: "Teams API",
+        kind: "api",
+        tier: "reference",
+        summary: "Manage teams, members, and invitations over HTTP.",
+        keywords: ["api", "teams", "team", "members", "invitations", "endpoint"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "Create teams, list members, and manage invitations programmatically. Webhooks and API keys are team-scoped.",
+    },
+    {
+        slug: "api/docs",
+        title: "Docs API (GET /v1/docs)",
+        kind: "api",
+        tier: "reference",
+        summary: "Fetch the machine-readable documentation index.",
+        keywords: ["api", "docs", "index", "discovery", "machine-readable", "v1/docs"],
+        url: `${DOCS_BASE_URL}/api`,
+        body: "`GET /v1/docs` returns the tier-aware docs index (filter with `q` and `category`); `GET /v1/docs/{slug}` returns one page. It mirrors the CLI's offline `sf docs`.",
+    },
+    {
+        slug: "api/webhooks",
+        title: "Webhooks",
+        kind: "api",
+        tier: "reference",
+        summary: "Subscribe to version, build, and domain lifecycle events.",
+        keywords: ["api", "webhook", "events", "callback", "notifications", "build", "signature"],
+        url: `${DOCS_BASE_URL}/webhooks`,
+        body: "Register a team-scoped, signed webhook to receive version, build, domain, and transfer events. Verify the signature header before trusting a payload.",
+    },
+    {
+        slug: "api/platform",
+        title: "Platform (tenant) API",
+        kind: "api",
+        tier: "reference",
+        summary: "The tenant-facing platform API for running Spacefast as infra.",
+        keywords: ["api", "platform", "tenant", "infra", "openapi", "multi-tenant"],
+        url: `${DOCS_BASE_URL}/platforms`,
+        body: "The platform API is the tenant-facing surface for operating Spacefast as hosting infra. It shares the `{ data }` / `{ error }` envelope and is documented via OpenAPI.",
+    },
+    // ----- Recipes ----------------------------------------------------------
+    {
+        slug: "recipes/github-deploys",
+        title: "Publish from GitHub",
+        kind: "recipe",
+        tier: "full",
+        summary: "Connect a repository so pushes publish automatically.",
+        keywords: ["github", "git", "ci", "push", "connect", "automatic", "recipe"],
+        url: `${DOCS_BASE_URL}/builds`,
+        body: "Connect a repository with `sf git connect`; each push builds on Spacefast and publishes a version, with pull requests getting preview URLs.",
+    },
+    {
+        slug: "recipes/preview-channels",
+        title: "Preview channels for pull requests",
+        kind: "recipe",
+        tier: "full",
+        summary: "Give every branch a shareable preview URL.",
+        keywords: ["preview", "channel", "branch", "pull request", "staging", "recipe"],
+        url: `${DOCS_BASE_URL}/builds`,
+        body: "Push a branch or open a pull request on a connected repository, or publish to a named channel, to get an isolated preview URL without touching production.",
+    },
+    {
+        slug: "recipes/agent-publish",
+        title: "Let an agent publish for you",
+        kind: "recipe",
+        tier: "full",
+        summary: "Drive a first publish from an AI agent, then claim it.",
+        keywords: ["agent", "ai", "mcp", "anonymous", "claim", "automation", "recipe"],
+        url: `${DOCS_BASE_URL}/anonymous-publish`,
+        body: "Let an agent publish anonymously for an instant URL and a claim token, then hand the token to a human who runs `sf spaces claim`.",
+    },
+    {
+        slug: "recipes/custom-domain",
+        title: "Add a custom domain",
+        kind: "recipe",
+        tier: "full",
+        summary: "Point your own domain at a space with automatic TLS.",
+        keywords: ["domain", "custom domain", "dns", "tls", "https", "recipe"],
+        url: `${RECIPES_BASE_URL}/custom-domain`,
+        body: "Add the domain with `sf domains add`, set the DNS records Spacefast prints, and wait for `sf domains check` to report a ready certificate.",
+    },
+    {
+        slug: "recipes/password-protect",
+        title: "Password-protect a space",
+        kind: "recipe",
+        tier: "full",
+        summary: "Put one shared password in front of a whole space.",
+        keywords: ["password", "protect", "private", "access", "gate", "recipe"],
+        url: `${RECIPES_BASE_URL}/password-protect-a-space`,
+        body: "Run `sf password set` to gate a space behind a single shared secret; clear it later with `sf password clear`.",
+    },
+    {
+        slug: "recipes/redirects",
+        title: "Set up redirects",
+        kind: "recipe",
+        tier: "reference",
+        summary: "Add redirect rules that ship and roll back with a version.",
+        keywords: ["redirect", "rewrite", "routing", "301", "recipe"],
+        url: `${RECIPES_BASE_URL}/redirects`,
+        body: "Add redirect rules to a `_redirects` file at your publish root so they publish as part of the version and roll back with it.",
+    },
+    {
+        slug: "recipes/migrate-dns",
+        title: "Migrate DNS to a custom domain",
+        kind: "recipe",
+        tier: "reference",
+        summary: "Cut traffic over to a Spacefast-served domain safely.",
+        keywords: ["dns", "migrate", "cutover", "domain", "nameserver", "recipe"],
+        url: `${RECIPES_BASE_URL}/custom-domain`,
+        body: "Pre-stage the domain with `sf domains add`, verify the certificate is ready with `sf domains check`, then update DNS to flip traffic with zero downtime.",
+    },
+];
+// ----- Error reference (generated) -----------------------------------------
+// One reference-tier catalog entry per ERROR_DOCS member, so `sf docs <code>`,
+// `GET /v1/docs?q=<code>`, and MCP search all resolve error codes in a single
+// query. Slug is `errors/{code}` (matches the /docs/errors/{code} route); body
+// is the summary + fix, mirroring the generated error doc page.
+function errorDocsCatalogEntries() {
+    return Object.entries(ERROR_DOCS).map(([code, doc]) => ({
+        slug: `errors/${code}`,
+        title: code,
+        kind: "error",
+        tier: "reference",
+        summary: doc.summary,
+        keywords: ["error", "code", code],
+        url: errorDocsUrl(code),
+        body: `${doc.summary} **How to resolve:** ${doc.fix}`,
+    }));
+}
+export const DOCS_CATALOG = [
+    ...HAND_WRITTEN_DOCS_CATALOG,
+    ...errorDocsCatalogEntries(),
+];