@spacefast/common 0.0.8 → 0.0.10

package/dist/dashboard-paths/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dashboard route first-segments that cannot be used as team slugs.
+ *
+ * Append-only: add a new top-level static dashboard route's first segment here
+ * before its route module lands. A repository structural test enforces this.
+ */
+export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "account", "agent", "claim", "device", "drop", "new-team", "oauth", "sign-in", "start", "terminal", "two-factor"];
+/**
+ * Dashboard route first-segments that cannot be used as space slugs.
+ *
+ * Append-only: add a new static route directly below a team's first segment
+ * here before its route module lands. A repository structural test enforces
+ * this.
+ */
+export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["billing", "connect", "domains", "drop", "members", "new", "settings"];
+export type TeamSlugRouteReservation = (typeof TEAM_SLUG_ROUTE_RESERVATIONS)[number];
+export type SpaceSlugRouteReservation = (typeof SPACE_SLUG_ROUTE_RESERVATIONS)[number];
+export declare const TEAM_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
+export declare const SPACE_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
+export type SpaceSettingsDestination = "access" | "advanced" | "appearance" | "builds" | "integrations" | "integrations/add" | "source-builds";
+export type TeamSettingsDestination = "access" | "audit" | "developer" | "developer/agents" | "developer/environment-variables" | "developer/handoffs" | "developer/service-tokens" | "developer/webhooks" | "integrations";
+export declare function teamPath(teamSlug: string): string;
+export declare function spacePath(teamSlug: string, spaceSlug: string): string;
+export declare function versionDetailPath(teamSlug: string, spaceSlug: string, versionRef: string): string;
+export declare function buildDetailPath(teamSlug: string, spaceSlug: string, buildId: string): string;
+export declare function spaceDomainsPath(teamSlug: string, spaceSlug: string): string;
+export declare function spaceSettingsPath(teamSlug: string, spaceSlug: string, destination?: SpaceSettingsDestination): string;
+export declare function teamDomainsPath(teamSlug: string): string;
+export declare function teamBillingPath(teamSlug: string): string;
+export declare function teamDomainDetailPath(teamSlug: string, domainRef: string): string;
+export declare function teamSettingsPath(teamSlug: string, destination?: TeamSettingsDestination): string;

package/dist/dashboard-paths/index.js

@@ -0,0 +1,80 @@
+/**
+ * Dashboard route first-segments that cannot be used as team slugs.
+ *
+ * Append-only: add a new top-level static dashboard route's first segment here
+ * before its route module lands. A repository structural test enforces this.
+ */
+export const TEAM_SLUG_ROUTE_RESERVATIONS = [
+    "accept-beta-invite",
+    "accept-invitation",
+    "account",
+    // Not a TanStack route module: /agent* is the edge-served handoff-document
+    // surface (apps/my/public/_redirects + vite middleware, #417). Those rewrite
+    // rules deliberately swallow every /agent-prefixed path, so a team named
+    // "agent" could never reach its canonical dashboard. Reserved per the spec's
+    // own rule that a static first segment is reserved before the surface owning
+    // it ships (#417 predates this set; this closes that drift).
+    "agent",
+    "claim",
+    "device",
+    "drop",
+    "new-team",
+    "oauth",
+    "sign-in",
+    "start",
+    "terminal",
+    "two-factor",
+];
+/**
+ * Dashboard route first-segments that cannot be used as space slugs.
+ *
+ * Append-only: add a new static route directly below a team's first segment
+ * here before its route module lands. A repository structural test enforces
+ * this.
+ */
+export const SPACE_SLUG_ROUTE_RESERVATIONS = [
+    "billing",
+    "connect",
+    "domains",
+    "drop",
+    "members",
+    "new",
+    "settings",
+];
+export const TEAM_SLUG_ROUTE_RESERVATION_SET = new Set(TEAM_SLUG_ROUTE_RESERVATIONS);
+export const SPACE_SLUG_ROUTE_RESERVATION_SET = new Set(SPACE_SLUG_ROUTE_RESERVATIONS);
+function dynamicSegment(value) {
+    return encodeURIComponent(value);
+}
+export function teamPath(teamSlug) {
+    return `/${dynamicSegment(teamSlug)}`;
+}
+export function spacePath(teamSlug, spaceSlug) {
+    return `${teamPath(teamSlug)}/${dynamicSegment(spaceSlug)}`;
+}
+export function versionDetailPath(teamSlug, spaceSlug, versionRef) {
+    return `${spacePath(teamSlug, spaceSlug)}/versions/${dynamicSegment(versionRef)}`;
+}
+export function buildDetailPath(teamSlug, spaceSlug, buildId) {
+    return `${spacePath(teamSlug, spaceSlug)}/builds/${dynamicSegment(buildId)}`;
+}
+export function spaceDomainsPath(teamSlug, spaceSlug) {
+    return `${spacePath(teamSlug, spaceSlug)}/domains`;
+}
+export function spaceSettingsPath(teamSlug, spaceSlug, destination) {
+    const root = `${spacePath(teamSlug, spaceSlug)}/settings`;
+    return destination ? `${root}/${destination}` : root;
+}
+export function teamDomainsPath(teamSlug) {
+    return `${teamPath(teamSlug)}/domains`;
+}
+export function teamBillingPath(teamSlug) {
+    return `${teamPath(teamSlug)}/billing`;
+}
+export function teamDomainDetailPath(teamSlug, domainRef) {
+    return `${teamDomainsPath(teamSlug)}/${dynamicSegment(domainRef)}`;
+}
+export function teamSettingsPath(teamSlug, destination) {
+    const root = `${teamPath(teamSlug)}/settings`;
+    return destination ? `${root}/${destination}` : root;
+}

package/dist/docs/agent-handoff-document.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The exact markdown body served to agents at `/agent/<documentId>`.
+ * Deterministic and ID-free on purpose — see the module comment.
+ */
+export declare function renderAgentHandoffDocumentMarkdown(input: {
+    mcpEndpoint: string;
+}): string;
+/**
+ * The browser variant served at `/agent/<documentId>`: the full instructions in
+ * the initial response body, zero scripts (nothing may ever read or echo the
+ * URL fragment), same bytes for every ID.
+ */
+export declare function renderAgentHandoffDocumentHtml(input: {
+    mcpEndpoint: string;
+}): string;

package/dist/docs/agent-handoff-document.js

@@ -0,0 +1,179 @@
+/*
+ * The public setup document behind agent handoff links.
+ *
+ * Handoff links are `https://<dashboard-origin>/agent/<documentId>#<secret>` and
+ * the minted prompt tells the agent to fetch that URL. Fragments never reach the
+ * server, so this fetch is UNAUTHENTICATED BY DESIGN — which means the response
+ * must never become an existence oracle. The contract here is
+ * indistinguishability: every well-formed document ID serves the exact same
+ * bytes, with the same status and the same timing, whether or not a handoff with
+ * that ID exists. That is why these renderers take no document ID and hit no
+ * store: the document is one static artifact, target-agnostic, published behind
+ * a `/agent/*` rewrite on the dashboard space. Per-target polish deliberately
+ * loses to indistinguishability — instead of looking up the handoff's client
+ * target (which would need a public by-ID lookup, an oracle), the document
+ * carries a named section for every connect target and the minted prompt's
+ * "follow the <client> setup instructions" resolves to the right section.
+ *
+ * Lifecycle safety stays where the secret authenticates: an expired, used, or
+ * revoked link fails at the app-private exchange, never at fetch time (see
+ * ./agent-setup.ts, `AGENT_HANDOFF_DECLINE_REASONS`).
+ */
+import { buildConnectTargets } from "../agents/connect-targets.js";
+import { BRAND } from "../brand.js";
+import { AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_TARGET_IDS, AGENT_HANDOFF_FETCH_SAFETY, AGENT_HANDOFF_FRAGMENT_HYGIENE, AGENT_HANDOFF_PREAMBLE, AGENT_HANDOFF_PUBLISH_PROSE, agentHandoffConnectSections, agentSetupTextUrl, } from "./agent-setup.js";
+const DOCUMENT_TITLE = `Set up ${BRAND.productName} from an agent handoff`;
+const DOCUMENT_SCOPE = `This is the public setup document for ${BRAND.productName} agent handoff links (\`/agent/<id>\` on the dashboard origin). Every link serves this same document — fetching it never uses a handoff and reveals nothing about one.`;
+const CONNECT_INTRO = "Set up the client you are running in. Each section stands on its own.";
+/**
+ * The exact markdown body served to agents at `/agent/<documentId>`.
+ * Deterministic and ID-free on purpose — see the module comment.
+ */
+export function renderAgentHandoffDocumentMarkdown(input) {
+    const targets = buildConnectTargets({ mcpEndpoint: input.mcpEndpoint });
+    const cliTargetNames = targets
+        .filter((target) => AGENT_HANDOFF_CLI_TARGET_IDS.includes(target.id))
+        .map((target) => target.name);
+    const connectSections = targets.flatMap((target) => {
+        const sections = agentHandoffConnectSections(target);
+        sections.unshift(`### ${target.name}`);
+        return sections;
+    });
+    const sections = [
+        `# ${DOCUMENT_TITLE}`,
+        DOCUMENT_SCOPE,
+        AGENT_HANDOFF_PREAMBLE,
+        ["## Connect", CONNECT_INTRO, ...connectSections].join("\n\n"),
+        [
+            "## Continue the approved handoff",
+            AGENT_HANDOFF_FETCH_SAFETY,
+            `From ${cliTargetNames.join(" or ")} (or any client with a shell): ${AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE}`,
+            `From every other client: ${AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE}`,
+            AGENT_HANDOFF_FRAGMENT_HYGIENE,
+        ].join("\n\n"),
+        ["## Publish", AGENT_HANDOFF_PUBLISH_PROSE].join("\n\n"),
+        `General agent instructions: ${agentSetupTextUrl}`,
+    ];
+    return `${sections.join("\n\n")}\n`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function linkify(escaped) {
+    return escaped.replace(/https?:\/\/[^\s<)]+/g, (url) => `<a href="${url}" rel="noopener">${url}</a>`);
+}
+/** Inline markdown: backtick code spans stay literal; bare URLs become links. */
+function renderInline(text) {
+    return text
+        .split("`")
+        .map((part, index) => index % 2 === 1 ? `<code>${escapeHtml(part)}</code>` : linkify(escapeHtml(part)))
+        .join("");
+}
+/**
+ * Renders the document's own markdown grammar (headings, paragraphs, fenced
+ * code, inline code, bare URLs) to HTML. Not a general markdown engine: the
+ * input is our generated document above, so anything else stays literal text.
+ */
+function markdownToHtmlBody(markdown) {
+    const html = [];
+    let paragraph = [];
+    let codeBlock = null;
+    const flushParagraph = () => {
+        if (paragraph.length > 0) {
+            html.push(`<p>${paragraph.map(renderInline).join("\n")}</p>`);
+            paragraph = [];
+        }
+    };
+    for (const line of markdown.split("\n")) {
+        if (codeBlock !== null) {
+            if (line.startsWith("```")) {
+                html.push(`<pre><code>${escapeHtml(codeBlock.join("\n"))}</code></pre>`);
+                codeBlock = null;
+            }
+            else {
+                codeBlock.push(line);
+            }
+            continue;
+        }
+        if (line.startsWith("```")) {
+            flushParagraph();
+            codeBlock = [];
+            continue;
+        }
+        const heading = /^(#{1,3}) (.*)$/.exec(line);
+        if (heading?.[1] && heading[2] !== undefined) {
+            flushParagraph();
+            const level = heading[1].length;
+            html.push(`<h${level}>${renderInline(heading[2])}</h${level}>`);
+            continue;
+        }
+        if (line.trim() === "") {
+            flushParagraph();
+            continue;
+        }
+        paragraph.push(line);
+    }
+    flushParagraph();
+    return html.join("\n");
+}
+const DOCUMENT_STYLES = `
+:root { color-scheme: light dark; }
+body {
+  margin: 0 auto;
+  padding: 3rem 1.25rem 5rem;
+  max-width: 42rem;
+  font: 16px/1.6 ui-sans-serif, system-ui, sans-serif;
+  background: #ffffff;
+  color: #1a1a1e;
+}
+h1 { font-size: 1.6rem; line-height: 1.25; margin: 0 0 1rem; }
+h2 { font-size: 1.2rem; margin: 2.5rem 0 0.75rem; }
+h3 { font-size: 1rem; margin: 2rem 0 0.5rem; }
+p { margin: 0.75rem 0; }
+a { color: inherit; text-underline-offset: 3px; word-break: break-word; }
+code {
+  font: 0.875em ui-monospace, monospace;
+  background: rgba(125, 125, 135, 0.14);
+  border-radius: 4px;
+  padding: 0.1em 0.35em;
+}
+pre {
+  background: rgba(125, 125, 135, 0.1);
+  border: 1px solid rgba(125, 125, 135, 0.25);
+  border-radius: 8px;
+  padding: 0.875rem 1rem;
+  overflow-x: auto;
+}
+pre code { background: none; padding: 0; font-size: 0.8125rem; }
+@media (prefers-color-scheme: dark) {
+  body { background: #0e0e10; color: #ececf1; }
+}
+`.trim();
+/**
+ * The browser variant served at `/agent/<documentId>`: the full instructions in
+ * the initial response body, zero scripts (nothing may ever read or echo the
+ * URL fragment), same bytes for every ID.
+ */
+export function renderAgentHandoffDocumentHtml(input) {
+    const markdown = renderAgentHandoffDocumentMarkdown(input);
+    return [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<meta name="robots" content="noindex">',
+        `<title>${escapeHtml(DOCUMENT_TITLE)}</title>`,
+        `<style>${DOCUMENT_STYLES}</style>`,
+        "</head>",
+        "<body>",
+        markdownToHtmlBody(markdown),
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+}

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

@@ -1,4 +1,4 @@
-import { type ConnectTargetId } from "../agents/connect-targets.js";
+import { type ConnectTarget, type ConnectTargetId } from "../agents/connect-targets.js";
 export declare const agentSetupUrl: string;
 export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
@@ -46,6 +46,17 @@ export declare function parseAgentHandoffUrl(value: string, expectedOrigin: stri
     documentUrl: 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.";
+/** 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_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.";
+/** 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;

package/dist/docs/agent-setup.js

@@ -98,32 +98,46 @@ function validateMcpEndpoint(value) {
     }
     return url.href.replace(/\/$/, "");
 }
-function renderAgentHandoffInstructions(documentUrl, target) {
+/*
+ * Shared handoff prose. The per-handoff "Copy Markdown" artifact (below) and the
+ * public /agent/<id> document (./agent-handoff-document.ts) must tell agents the
+ * same contract in the same words, so the sentences live here exactly once.
+ */
+/** 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.";
+/** 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_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.";
+/** 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")] : []);
-    const connectSections = [
+    return [
         target.blurb,
         ...setupSections,
-        target.deeplink ? `${target.deeplink.label}: ${target.deeplink.href}` : null,
-        target.download ? `${target.download.label}: ${target.download.href}` : null,
-    ].filter((section) => section !== null);
-    const approvalGuidance = target.id === "claude-code" || target.id === "codex"
-        ? `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.`
-        : "When the client opens browser approval, ask the user to approve there before publishing.";
+        ...(target.deeplink ? [`${target.deeplink.label}: ${target.deeplink.href}`] : []),
+        ...(target.download ? [`${target.download.label}: ${target.download.href}`] : []),
+    ];
+}
+function renderAgentHandoffInstructions(documentUrl, target) {
+    const approvalGuidance = AGENT_HANDOFF_CLI_TARGET_IDS.includes(target.id)
+        ? AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE
+        : AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE;
     const sections = [
         `# Set up ${BRAND.productName} with ${target.name}`,
         `This is the public setup document for ${documentUrl}.`,
-        "Talk to the user before installing tools or publishing. Confirm the file or folder they want to make public.",
-        ["## Connect", ...connectSections].join("\n\n"),
+        AGENT_HANDOFF_PREAMBLE,
+        ["## Connect", ...agentHandoffConnectSections(target)].join("\n\n"),
         [
             "## Continue the approved handoff",
-            "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.",
+            AGENT_HANDOFF_FETCH_SAFETY,
             approvalGuidance,
-            "Keep its fragment out of commands, request URLs, logs, and replies.",
-        ].join("\n\n"),
-        [
-            "## Publish",
-            "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.",
+            AGENT_HANDOFF_FRAGMENT_HYGIENE,
         ].join("\n\n"),
+        ["## Publish", AGENT_HANDOFF_PUBLISH_PROSE].join("\n\n"),
         `General agent instructions: ${agentSetupTextUrl}`,
     ];
     return `${sections.join("\n\n")}\n`;

package/dist/docs/catalog.d.ts

@@ -472,10 +472,10 @@ export declare const DOCS_CATALOG: readonly [{
     readonly title: "sf api";
     readonly kind: "cli";
     readonly tier: "full";
-    readonly summary: "Make an authenticated raw call to the platform API.";
+    readonly summary: "Call the core public API through a safe escape hatch.";
     readonly keywords: readonly ["api", "sf api", "http", "raw", "request", "curl", "endpoint"];
     readonly url: "https://spacefast.com/docs/cli";
-    readonly 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.";
+    readonly body: "`sf api <METHOD> /v1/...` calls only the core public contract with resolved CLI credentials. JSON envelopes print verbatim; cursor lists support `--paginate`, and non-JSON bodies require `--output` or `--raw-stdout`.";
 }, {
     readonly slug: "cli/mcp";
     readonly title: "sf mcp";

package/dist/docs/catalog.js

@@ -537,10 +537,10 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "sf api",
         kind: "cli",
         tier: "full",
-        summary: "Make an authenticated raw call to the platform API.",
+        summary: "Call the core public API through a safe escape hatch.",
         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.",
+        body: "`sf api <METHOD> /v1/...` calls only the core public contract with resolved CLI credentials. JSON envelopes print verbatim; cursor lists support `--paginate`, and non-JSON bodies require `--output` or `--raw-stdout`.",
     },
     {
         slug: "cli/mcp",

package/dist/docs/error-docs.js

@@ -28,6 +28,14 @@ export const ERROR_DOCS = {
         summary: "The authorization request was denied by the user.",
         fix: "Restart the login flow and approve the request to continue.",
     },
+    agent_handoff_declined: {
+        summary: "The app-private agent handoff cannot be redeemed.",
+        fix: "Ask the user to create a fresh handoff for this Space and client, then redeem that new link once.",
+    },
+    agent_handoff_limit_reached: {
+        summary: "This user already has the maximum number of pending handoffs for the Space.",
+        fix: "Redeem or revoke an existing pending handoff for the Space before creating another.",
+    },
     ambiguous_space_slug: {
         summary: "The slug matches spaces in more than one of your teams, so it cannot be resolved.",
         fix: "Pass a teamRef alongside the slug, or reference the space by its spc_ id.",
@@ -160,6 +168,10 @@ export const ERROR_DOCS = {
         summary: "This CLI version is too old to talk to the API safely.",
         fix: "Upgrade the CLI to the latest release and retry.",
     },
+    comment_screenshot_rate_limited: {
+        summary: "Too many anonymous comment screenshot uploads were attempted.",
+        fix: "Wait for the one-minute window to reset, then retry the screenshot upload.",
+    },
     config_file_too_large: {
         summary: "The sf.jsonc configuration file exceeds the maximum size.",
         fix: "Keep the configuration file under the documented size limit (256 KB).",
@@ -536,6 +548,10 @@ export const ERROR_DOCS = {
         summary: "The authorization grant is invalid or was already used.",
         fix: "Restart the login flow to obtain a new grant.",
     },
+    invalid_idempotency_key: {
+        summary: "The Idempotency-Key header is missing, empty, or too long.",
+        fix: "Send a non-empty Idempotency-Key header of at most 512 characters.",
+    },
     invalid_publish_archive: {
         summary: "The uploaded archive could not be read as a valid zip.",
         fix: "Re-create the archive as a standard zip and upload again.",
@@ -664,6 +680,10 @@ export const ERROR_DOCS = {
         summary: "The upload manifest declares more files than the allowed ceiling.",
         fix: "Reduce the file count or split content across multiple spaces.",
     },
+    mcp_acted_for_team_deleted: {
+        summary: "This MCP approval or execution run acted only for a team that has since been deleted, so it can no longer be approved, denied, or canceled.",
+        fix: "Nothing to do — the record is read-only history. Restore the deleted team within its recovery window if you still need to act on it.",
+    },
     member_already_exists: {
         summary: "This user is already a member of the team.",
         fix: "Update the existing member's role instead of inviting again.",
@@ -780,6 +800,10 @@ export const ERROR_DOCS = {
         summary: "Someone published new space settings after the base you loaded, so saving would overwrite their change.",
         fix: "Reload the latest settings, review the difference, and save again; pass force only to overwrite deliberately.",
     },
+    publish_bytes_missing: {
+        summary: "The publish has no complete staged content to materialize.",
+        fix: "Finish uploading the staged content, or start a new publish.",
+    },
     publish_config_unsupported: {
         summary: "The publish carries configuration this endpoint does not support.",
         fix: "Move the configuration into sf.jsonc or the space settings.",
@@ -792,10 +816,34 @@ export const ERROR_DOCS = {
         summary: "A declared file was never uploaded, so the publish cannot finalize.",
         fix: "Upload every declared file, or resume the upload session to see what is missing.",
     },
+    publish_hash_mismatch: {
+        summary: "Publish content does not match its declared sha256.",
+        fix: "Re-send the file with matching bytes, or correct the declared hash.",
+    },
+    publish_inline_limit_exceeded: {
+        summary: "The inline publish exceeds the file-count or total-size limit.",
+        fix: "Trim the inline payload, or switch to an upload-based publish for larger content.",
+    },
+    publish_not_cancelable: {
+        summary: "The publish has progressed past the point where it can be canceled.",
+        fix: "Wait for the publish to finish, then roll back by promoting a previous version if needed.",
+    },
+    publish_path_collision: {
+        summary: "Two entries in the publish payload normalize to the same path.",
+        fix: "Remove the duplicate; each path may appear once across files and deletes.",
+    },
+    publish_path_invalid: {
+        summary: "A publish path is not a relative, normalized POSIX path.",
+        fix: "Use forward-slash relative paths without traversal segments or control characters.",
+    },
     publish_setup_failed: {
         summary: "Provisioning for this publish failed.",
         fix: "Retry the publish; if it persists, contact support with the requestId.",
     },
+    publish_snapshot_empty: {
+        summary: "An empty snapshot was sent without an explicit base version.",
+        fix: "Include at least one file, or declare the base version to intentionally publish an empty site.",
+    },
     publish_upload_failed: {
         summary: "Uploading the publish content failed.",
         fix: "Retry the publish; partial uploads are resumable through the upload session.",
@@ -972,6 +1020,10 @@ export const ERROR_DOCS = {
         summary: "The space expired and is no longer served.",
         fix: "If it is within the recovery window, claim or restore it; otherwise publish again.",
     },
+    space_has_active_publish: {
+        summary: "The space has a publish in progress, which blocks this operation.",
+        fix: "Wait for the publish to finish or cancel it, then retry.",
+    },
     space_has_active_version: {
         summary: "The space still has an active version, which blocks this operation.",
         fix: "Delete or supersede the active version first.",

package/dist/utils/asset-fingerprint.d.ts

@@ -0,0 +1,53 @@
+export declare const FINGERPRINT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+export declare const FINGERPRINT_HASH_LENGTH = 8;
+export type FingerprintCandidateFile = {
+    /** Canonical manifest path (no leading slash). */
+    path: string;
+    /** Full lowercase-hex sha256 of the file's bytes. */
+    sha256?: string | undefined;
+    /** UTF-8 text for html/css files that may need reference rewriting. */
+    text?: string | undefined;
+};
+export type FingerprintSkipReason = "css_cycle" | "alias_collision" | "user_cache_control" | "budget";
+export type FingerprintPlan = {
+    /**
+     * Alias manifest entries to add, sorted by sourcePath; content is identical
+     * to sourcePath's. This is also the "what got fingerprinted" relation —
+     * one array, `path` = the hashed alias, `sourcePath` = the original.
+     */
+    aliases: Array<{
+        path: string;
+        sourcePath: string;
+    }>;
+    /** html/css files whose published content changes (both paths, one blob). */
+    rewrites: Array<{
+        path: string;
+        text: string;
+        sha256: string;
+    }>;
+    /** Eligible-looking files the pass left on the default lane, with reasons. */
+    skipped: Array<{
+        path: string;
+        reason: FingerprintSkipReason;
+    }>;
+};
+export declare function planAssetFingerprints(input: {
+    files: readonly FingerprintCandidateFile[];
+    /** sha256 as lowercase hex over UTF-8 bytes of `text`. */
+    hashHex: (text: string) => string;
+    /**
+     * True when a user `_headers` Cache-Control rule already covers this URL
+     * path ("/"-prefixed). Files whose original OR probe-alias path is covered
+     * are never fingerprinted — user rules always win.
+     */
+    pathCoveredByUserCacheControl?: ((urlPath: string) => boolean) | undefined;
+    /** Extra per-path exclusion (e.g. header-rule budget trimming). */
+    excludePath?: ((path: string) => boolean) | undefined;
+}): FingerprintPlan;
+/**
+ * Merges the generated immutable pins into user `_headers` content. The user
+ * content is preserved byte-for-byte; generated exact-path rules are appended
+ * (per-path Cache-Control conflicts are impossible — files covered by a user
+ * Cache-Control rule are never fingerprinted).
+ */
+export declare function mergeFingerprintHeaders(userHeaders: string | undefined, aliasPaths: readonly string[]): string;