@spacefast/common 0.0.12 → 0.0.17

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

@@ -4,7 +4,7 @@
  * 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"];
+export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "account", "access", "agent", "claim", "device", "drop", "new-team", "oauth", "sign-in", "start", "terminal", "two-factor"];
 /**
  * Dashboard route first-segments that cannot be used as space slugs.
  *
@@ -12,18 +12,33 @@ export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite
  * 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 declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["billing", "connect", "domains", "drop", "members", "new", "resume", "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>;
+/**
+ * The Runtime page's sections. They are search params rather than path
+ * segments, so `runtime` stays a single route (and a single ledger row) and a
+ * space slugged "runtime" keeps its own Runtime page at
+ * `/<team>/runtime/runtime`.
+ */
+export declare const SPACE_RUNTIME_SECTIONS: readonly ["overview", "database", "storage", "logs"];
+export type SpaceRuntimeSection = (typeof SPACE_RUNTIME_SECTIONS)[number];
+export declare const DEFAULT_SPACE_RUNTIME_SECTION: SpaceRuntimeSection;
 export type SpaceSettingsDestination = "access" | "advanced" | "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 type TeamSettingsDestination = "access" | "audit" | "developer" | "developer/agents" | "developer/environment-variables" | "developer/handoffs" | "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;
+/**
+ * The space's Runtime page. The default section is the bare URL — the route
+ * strips it back out of the address bar — so a link to "overview" and a link to
+ * the page itself are the same link.
+ */
+export declare function spaceRuntimePath(teamSlug: string, spaceSlug: string, section?: SpaceRuntimeSection): 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;

package/dist/dashboard-paths/index.js

@@ -8,6 +8,7 @@ export const TEAM_SLUG_ROUTE_RESERVATIONS = [
     "accept-beta-invite",
     "accept-invitation",
     "account",
+    "access",
     // 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
@@ -39,10 +40,19 @@ export const SPACE_SLUG_ROUTE_RESERVATIONS = [
     "drop",
     "members",
     "new",
+    "resume",
     "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);
+/**
+ * The Runtime page's sections. They are search params rather than path
+ * segments, so `runtime` stays a single route (and a single ledger row) and a
+ * space slugged "runtime" keeps its own Runtime page at
+ * `/<team>/runtime/runtime`.
+ */
+export const SPACE_RUNTIME_SECTIONS = ["overview", "database", "storage", "logs"];
+export const DEFAULT_SPACE_RUNTIME_SECTION = "overview";
 function dynamicSegment(value) {
     return encodeURIComponent(value);
 }
@@ -61,6 +71,15 @@ export function buildDetailPath(teamSlug, spaceSlug, buildId) {
 export function spaceDomainsPath(teamSlug, spaceSlug) {
     return `${spacePath(teamSlug, spaceSlug)}/domains`;
 }
+/**
+ * The space's Runtime page. The default section is the bare URL — the route
+ * strips it back out of the address bar — so a link to "overview" and a link to
+ * the page itself are the same link.
+ */
+export function spaceRuntimePath(teamSlug, spaceSlug, section = DEFAULT_SPACE_RUNTIME_SECTION) {
+    const root = `${spacePath(teamSlug, spaceSlug)}/runtime`;
+    return section === DEFAULT_SPACE_RUNTIME_SECTION ? root : `${root}?section=${section}`;
+}
 export function spaceSettingsPath(teamSlug, spaceSlug, destination) {
     const root = `${spacePath(teamSlug, spaceSlug)}/settings`;
     return destination ? `${root}/${destination}` : root;

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

@@ -7,8 +7,8 @@ export declare function renderAgentHandoffDocumentMarkdown(input: {
 }): 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.
+ * the initial response body, zero scripts (nothing may ever inspect or echo a
+ * handoff credential), same bytes for every ID.
  */
 export declare function renderAgentHandoffDocumentHtml(input: {
     mcpEndpoint: string;

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

@@ -1,9 +1,10 @@
 /*
  * 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
+ * Private handoff links carry a one-use path token while the durable agent
+ * credential stays encrypted at the broker. The minted prompt tells the agent
+ * to fetch the reconstructed clean document URL instead. 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
@@ -21,7 +22,7 @@
  */
 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";
+import { AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_TARGET_IDS, AGENT_HANDOFF_CREDENTIAL_HYGIENE, AGENT_HANDOFF_FETCH_SAFETY, 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.";
@@ -49,7 +50,7 @@ export function renderAgentHandoffDocumentMarkdown(input) {
             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,
+            AGENT_HANDOFF_CREDENTIAL_HYGIENE,
         ].join("\n\n"),
         ["## Publish", AGENT_HANDOFF_PUBLISH_PROSE].join("\n\n"),
         `General agent instructions: ${agentSetupTextUrl}`,
@@ -155,8 +156,8 @@ pre code { background: none; padding: 0; font-size: 0.8125rem; }
 `.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.
+ * the initial response body, zero scripts (nothing may ever inspect or echo a
+ * handoff credential), same bytes for every ID.
  */
 export function renderAgentHandoffDocumentHtml(input) {
     const markdown = renderAgentHandoffDocumentMarkdown(input);

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

@@ -9,19 +9,30 @@ export declare const EXPLAIN_TO_USER_PROSE: string;
 export declare const FAILURE_CONDUCT_PROSE: string;
 export declare const LANE_PICKER_PROSE: string;
 export declare const HOW_TO_RESEARCH_PROSE: string;
+/** Curl/API skill lane: docs URLs only — no MCP or CLI tools required. */
+export declare const HOW_TO_RESEARCH_API_PROSE: string;
+/** MCP plugin skill lane: prefer skills for workflows and execute for the OpenAPI catalog. */
+export declare const HOW_TO_RESEARCH_MCP_PROSE: string;
 export declare const ENV_NOTES_PROSE: string;
+export declare const ENV_NOTES_API_PROSE: string;
 /**
  * The CHECK verb: before ever creating a space, look for the one the project
  * already has. This is what keeps a returning agent from pushing a duplicate
  * anonymous space instead of a new version.
  */
 export declare const CHECK_BEFORE_PUBLISH_PROSE: string;
+export declare const CHECK_BEFORE_PUBLISH_API_PROSE: string;
+export declare const CHECK_BEFORE_PUBLISH_MCP_PROSE: string;
 /**
  * The SAVE verb: persist the space id and credential after a first publish so
  * every later publish targets the same space. The CLI and On-Device MCP write
  * this state automatically; curl-only agents write the same files themselves.
  */
+export declare const BUNDLED_SAVE_STATE_PROSE: string;
 export declare const SAVE_STATE_PROSE: string;
+/** Curl/API skill: no CLI/MCP required to continue in-session. */
+export declare const SAVE_STATE_API_PROSE: string;
+export declare const SAVE_STATE_MCP_PROSE: string;
 /**
  * The UPDATE verb: a new version to the SAME space. Never re-run the
  * first-publish recipe when saved state exists.
@@ -33,9 +44,9 @@ export declare const UPDATE_SPACE_PROSE: string;
  */
 export declare const CONTINUE_AFTER_CLAIM_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.
+ * The zero-install publish sequence: a replay-safe curl loop 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;
 /**
@@ -65,11 +76,19 @@ export declare const AGENT_PROSE: {
     readonly receiptShape: string;
     readonly signedUpload: string;
     readonly checkBeforePublish: string;
+    readonly checkBeforePublishApi: string;
+    readonly checkBeforePublishMcp: string;
+    readonly bundledSaveState: string;
     readonly saveState: string;
+    readonly saveStateApi: string;
+    readonly saveStateMcp: string;
     readonly updateSpace: string;
     readonly continueAfterClaim: string;
     readonly lanePicker: string;
     readonly howToResearch: string;
+    readonly howToResearchApi: string;
+    readonly howToResearchMcp: string;
     readonly envNotes: string;
+    readonly envNotesApi: string;
 };
 export type AgentProseKey = keyof typeof AGENT_PROSE;

package/dist/docs/agent-prose.js

@@ -1,4 +1,4 @@
-import { BRAND } from "../brand.js";
+import { serviceOrigin } from "../config/domains.js";
 // Single home for the agent-facing prose that was triplicated across the three
 // surfaces that teach an agent how to publish:
 //
@@ -14,7 +14,7 @@ import { BRAND } from "../brand.js";
 //
 // 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 API_ORIGIN = serviceOrigin("api", "prod");
 const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
 const EXCHANGE_ENDPOINT = `${API_ORIGIN}/v1/anonymous-claim/exchange`;
 // Centralized secret/credential patterns excluded from a publish archive. The
@@ -43,20 +43,6 @@ function findExpr(globs) {
         .map((glob) => (glob.includes("/") ? `-path "${glob}"` : `-name "${glob}"`))
         .join(" -o ");
 }
-function zipExcludeExpr(globs) {
-    // zip -x patterns need both the archive-root form and an any-depth form:
-    // ".spacefast/*" excludes only at the root, while "*/.spacefast/*" catches
-    // nested copies.
-    return globs
-        .flatMap((glob) => {
-        if (glob.startsWith("*/")) {
-            return [glob.slice(2), glob];
-        }
-        return [glob, `*/${glob}`];
-    })
-        .map((glob) => `"${glob}"`)
-        .join(" ");
-}
 /**
  * The credential rules every surface must repeat. Treat tokens as secrets, keep
  * them out of logs and transcripts, and never echo them back.
@@ -79,12 +65,13 @@ export const POSITIONING_PROSE = [
     "optimizes for agent-safe one-shot publish, claim, versioning, rollback, and continuation.",
 ].join("\n");
 export const EXPLAIN_TO_USER_PROSE = [
-    "Relay `data.shareBlurb` verbatim when present. State anonymous expiry in user terms:",
-    "the space expires unless claimed by `data.claim.expiresAt`. After claim, the agent key is",
-    "named and revocable in the dashboard.",
+    "Present Open and Claim as the only actions. State anonymous expiry in user terms: the Space",
+    "exists until `data.claim.expiresAt` unless claimed; claiming preserves Open and removes its expiry.",
+    "Keep live and immutable Version addresses as receipt metadata. After claim, the agent key is named",
+    "and revocable in the dashboard.",
 ].join("\n");
 export const FAILURE_CONDUCT_PROSE = [
-    "On failure, surface `error.code`, `error.docsUrl`, and `error.requestId`, then stop.",
+    "On failure, surface the problem document's `code`, `type`, and `requestId`, then stop.",
     "Do not invent undocumented endpoints. Do not read credentials out of auth files. Do not",
     "retry a one-shot operation without reusing its `Idempotency-Key`.",
 ].join("\n");
@@ -94,14 +81,34 @@ export const LANE_PICKER_PROSE = [
     "success, recommend the best next-time setup for the user's client.",
 ].join("\n");
 export const HOW_TO_RESEARCH_PROSE = [
-    "For an error, fetch `error.docsUrl`. For capability questions, use `search_docs` or append",
+    "For an error, fetch the problem document's `type` URL. For capability questions, search the OpenAPI catalog with `execute` or append",
     "`.md` to website docs URLs. For contracts, read `publish-spec.json` or OpenAPI. Never guess",
     "limits: publish, then read diagnostics.",
 ].join("\n");
+/** Curl/API skill lane: docs URLs only — no MCP or CLI tools required. */
+export const HOW_TO_RESEARCH_API_PROSE = [
+    "For an error, fetch the problem document's `type` URL. For capability questions, append `.md` to website docs",
+    "URLs (for example `https://spacefast.com/docs/getting-started/agents.md`) or read",
+    "`https://spacefast.com/llms.txt`. For contracts, read `https://spacefast.com/publish-spec.json`",
+    "or the OpenAPI linked from the API docs. Never guess limits: publish, then read diagnostics.",
+].join("\n");
+/** MCP plugin skill lane: prefer skills for workflows and execute for the OpenAPI catalog. */
+export const HOW_TO_RESEARCH_MCP_PROSE = [
+    "For an error, fetch the problem document's `type` URL when present. For workflows, call the `skills` tool",
+    "(list/search, then read by exact name). For capability questions, use `execute` with `tools.search`.",
+    "For contracts, read `publish-spec.json` or OpenAPI via docs. Never guess limits: publish,",
+    "then inspect status or diagnostics through `execute`.",
+].join("\n");
 export const ENV_NOTES_PROSE = [
     "claude.ai: allow `api.spacefast.com` in egress settings. Codex sandbox: escalate only the",
     "network call. Terminal agents: use the CLI when filesystem access matters.",
 ].join("\n");
+export const ENV_NOTES_API_PROSE = [
+    "claude.ai: allow `api.spacefast.com` in egress settings. Codex sandbox: escalate only the",
+    "network call to `api.spacefast.com`. This skill is complete with curl and the docs links above;",
+    "CLI and MCP are optional upgrades documented at https://spacefast.com/docs/cli and",
+    "https://spacefast.com/docs/getting-started/agents.",
+].join("\n");
 /**
  * The CHECK verb: before ever creating a space, look for the one the project
  * already has. This is what keeps a returning agent from pushing a duplicate
@@ -113,33 +120,83 @@ export const CHECK_BEFORE_PUBLISH_PROSE = [
     "- Look for `.spacefast/space.json` or `.spacefast/state.json`, walking up from the working",
     "  directory toward the filesystem root.",
     "- Look for a publish receipt earlier in this conversation.",
-    "- When authenticated, list existing spaces (`sf spaces list`, or the `spaces_list` MCP tool).",
+    "- When authenticated, list existing spaces (`sf spaces list`, or `execute` with the generated list-spaces operation).",
     "",
     "If any of these finds a space, publish a new version to that `spaceId` (see the update",
     "instructions) instead of creating another space. Only create a new space when none exists",
     "and the user wants a new site.",
 ].join("\n");
+export const CHECK_BEFORE_PUBLISH_API_PROSE = [
+    "Before creating a space, check whether this project already has one:",
+    "",
+    "- Look for `.spacefast/space.json` or `.spacefast/state.json`, walking up from the working",
+    "  directory toward the filesystem root.",
+    "- Look for a publish receipt earlier in this conversation.",
+    "- When you already have a bearer token, list spaces:",
+    "",
+    "```bash",
+    'curl -q -sS https://api.spacefast.com/v1/spaces -H "Authorization: Bearer $SPACEFAST_TOKEN"',
+    "```",
+    "",
+    "If any of these finds a space, publish a new version to that `spaceId` (see the update",
+    "instructions) instead of creating another space. Only create a new space when none exists",
+    "and the user wants a new site.",
+].join("\n");
+export const CHECK_BEFORE_PUBLISH_MCP_PROSE = [
+    "Before creating a space, check whether this project already has one:",
+    "",
+    "- Look for `.spacefast/space.json` or `.spacefast/state.json`, walking up from the working",
+    "  directory toward the filesystem root (On-Device reuses this link automatically).",
+    "- Look for a publish receipt earlier in this conversation.",
+    "- When authenticated, use `execute` to call the generated list-spaces operation.",
+    "",
+    "If any of these finds a space, publish a new version to that space instead of creating",
+    "another. Only create a new space when none exists and the user wants a new site.",
+].join("\n");
 /**
  * The SAVE verb: persist the space id and credential after a first publish so
  * every later publish targets the same space. The CLI and On-Device MCP write
  * this state automatically; curl-only agents write the same files themselves.
  */
-export const SAVE_STATE_PROSE = [
+export const BUNDLED_SAVE_STATE_PROSE = [
     "After the first publish, persist the space id and credential so every later publish updates",
-    "the same space instead of creating a new one. The CLI and On-Device MCP do this automatically",
-    "in `.spacefast/`; when publishing with curl, write the files yourself from the receipt:",
+    "the same space instead of creating a new one. Prefer MCP `publish` on On-Device — it writes",
+    "`.spacefast/` automatically. After a curl publish, pass the complete JSON receipt to the",
+    "bundled hardened writer. Set `SPACEFAST_SKILL_SCRIPTS` through the agent runtime/environment",
+    "to the absolute bundled `scripts/` directory; never interpolate that path into shell source:",
     "",
     "```bash",
-    "mkdir -p .spacefast",
-    "# non-secret, committable:",
-    `printf '{"space":"<spc_id>"}' > .spacefast/space.json`,
-    "# secret — never publish, never print:",
-    `printf '{"spaceId":"<spc_id>","claimToken":"<token>","apiUrl":"${API_ORIGIN}"}' > .spacefast/state.json`,
-    "grep -qx '.spacefast/state.json' .gitignore 2>/dev/null || echo '.spacefast/state.json' >> .gitignore",
+    "\"${SPACEFAST_SKILL_SCRIPTS:?set this to the bundled scripts directory}/save-state.sh\" <<'SPACEFAST_PUBLISH_RECEIPT'",
+    "<paste the complete JSON publish receipt here>",
+    "SPACEFAST_PUBLISH_RECEIPT",
     "```",
     "",
-    "`<spc_id>` is `data.space.id` and `<token>` is `data.claim.token` from the receipt. Keep",
-    "`.spacefast/state.json` out of publish archives, commits, logs, and chat.",
+    "The helper rejects symlinked state paths and uses exclusive, descriptor-relative atomic writes.",
+    "If the helper is unavailable, keep the receipt in agent memory for this session; do not",
+    "recreate credential state with shell redirections. Keep `.spacefast/state.json` out of",
+    "publish archives, commits, logs, and chat.",
+].join("\n");
+export const SAVE_STATE_PROSE = [
+    "After the first publish, persist the space id and credential so every later publish updates",
+    "the same space instead of creating a new one. The CLI and On-Device MCP do this automatically",
+    "in `.spacefast/`. This distribution does not include the hardened filesystem helper, so keep",
+    "the receipt in agent memory or use CLI/MCP for the next publish. Do not recreate credential",
+    "state with shell redirections. Keep `.spacefast/state.json` out of publish archives, commits,",
+    "logs, and chat.",
+].join("\n");
+/** Curl/API skill: no CLI/MCP required to continue in-session. */
+export const SAVE_STATE_API_PROSE = [
+    "After the first publish, keep `data.space.id` and `data.claim.token` (when present) in agent",
+    "memory for this session so later publishes update the same space. You may write non-secret",
+    '`.spacefast/space.json` as `{"space":"<spc_id>"}` when helpful. Do not recreate credential',
+    "state with shell redirections. Keep claim tokens and `.spacefast/state.json` out of publish",
+    "archives, commits, logs, and chat.",
+].join("\n");
+export const SAVE_STATE_MCP_PROSE = [
+    "After the first publish, On-Device MCP persists `.spacefast/` automatically so the next",
+    "`publish` updates the same space. Hosted MCP has no local filesystem state; keep the space id",
+    "in the current agent session or pass it explicitly. Never ask the user to paste claim tokens",
+    "or access tokens into chat.",
 ].join("\n");
 /**
  * The UPDATE verb: a new version to the SAME space. Never re-run the
@@ -150,8 +207,8 @@ export const UPDATE_SPACE_PROSE = [
     "never re-run the first-publish recipe when saved state exists:",
     "",
     "```bash",
-    'curl -sS -H "Authorization: Bearer <claim-token-or-access-token>" \\',
-    "  -F 'spaceId=<spc_id>' \\",
+    'curl -q -sS -H "Authorization: Bearer <claim-token-or-access-token>" \\',
+    "  --form-string 'spaceId=<spc_id>' \\",
     '  -F "files=@index.html" \\',
     `  ${PUBLISH_ENDPOINT}`,
     "```",
@@ -173,7 +230,7 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "failure is the signal to upgrade your credential — call the exchange endpoint exactly once:",
     "",
     "```bash",
-    'curl -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
+    'curl -q -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
     `  ${EXCHANGE_ENDPOINT}`,
     "```",
     "",
@@ -181,32 +238,137 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "Save `data.credential.accessToken` into `.spacefast/state.json` (replace the `claimToken`",
     'field with `"accessToken"`), then retry the publish with the new bearer. The exchange works',
     "exactly once; if it returns `continuation_used` or `continuation_unavailable`, ask the user",
-    "to mint an access token in the dashboard (Account → Access tokens).",
+    "to create an API key in the dashboard (Account → API keys).",
 ].join("\n");
+const LEXICAL_PUBLISH_PATH_PREFLIGHT = [
+    'case "$publish_target" in /*) check_path="$publish_target" ;; *) check_path="$PWD/$publish_target" ;; esac',
+    'remaining="${check_path#/}"; check_path="/"',
+    'while [ -n "$remaining" ]; do',
+    '  case "$remaining" in */*) component="${remaining%%/*}"; remaining="${remaining#*/}" ;; *) component="$remaining"; remaining="" ;; esac',
+    '  case "$component" in ""|.) continue ;; ..) check_path="${check_path%/*}"; [ -n "$check_path" ] || check_path="/"; continue ;; esac',
+    '  [ "$check_path" = "/" ] && check_path="/$component" || check_path="$check_path/$component"',
+    '  [ ! -L "$check_path" ] || { printf "error: symbolic link in publish path: %s\\n" "$check_path" >&2; exit 2; }',
+    "done",
+];
+const SECURE_ARCHIVE_RECIPE = [
+    'secure_python=""',
+    "for candidate in /usr/bin/python3.14 /usr/bin/python3.13 /usr/bin/python3.12 /usr/bin/python3.11 /usr/bin/python3.10 /usr/bin/python3.9 /usr/bin/python3.8 /usr/local/bin/python3.14 /usr/local/bin/python3.13 /usr/local/bin/python3.12 /usr/local/bin/python3.11 /usr/local/bin/python3.10 /usr/local/bin/python3.9 /opt/homebrew/bin/python3 /opt/homebrew/bin/python3.14 /opt/homebrew/bin/python3.13 /opt/homebrew/bin/python3.12 /opt/homebrew/bin/python3.11 /opt/homebrew/bin/python3.10 /opt/homebrew/bin/python3.9; do",
+    '  [ -x "$candidate" ] && [ -f "$candidate" ] || continue',
+    '  case "$candidate" in /opt/homebrew/*) ;; *) [ ! -L "$candidate" ] || continue ;; esac',
+    '  secure_python="$candidate"; break',
+    "done",
+    '[ -n "$secure_python" ] || { printf "error: trusted python3 is required for a race-safe archive\\n" >&2; exit 2; }',
+    `"$secure_python" -I - "$publish_target" <<'SPACEFAST_ARCHIVE' | curl -q -sS -F 'archive=@-;filename="spacefast-site.zip"' ${PUBLISH_ENDPOINT}`,
+    "import fnmatch, os, stat, sys, zipfile",
+    'directory_flags = os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)',
+    'file_flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)',
+    'excluded_directories = {".git", ".spacefast", ".ssh", ".aws", ".kube", ".docker"}',
+    'excluded_files = (".env*", ".npmrc", ".netrc", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*", "*.zip", "*.tar", "*.tgz")',
+    "def excluded(path):",
+    '    parts = path.split("/")',
+    "    return any(part in excluded_directories for part in parts[:-1]) or any(fnmatch.fnmatchcase(parts[-1], pattern) for pattern in excluded_files)",
+    "def same(left, right): return (left.st_dev, left.st_ino) == (right.st_dev, right.st_ino)",
+    'def walk(archive, directory_fd, prefix=""):',
+    "    for name in sorted(os.listdir(directory_fd)):",
+    '        archive_name = f"{prefix}/{name}" if prefix else name',
+    "        if excluded(archive_name): continue",
+    "        entry = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)",
+    '        if stat.S_ISLNK(entry.st_mode): raise RuntimeError(f"symbolic link in publish root: {archive_name}")',
+    "        if stat.S_ISDIR(entry.st_mode):",
+    "            child_fd = os.open(name, directory_flags, dir_fd=directory_fd)",
+    "            try:",
+    '                if not same(os.fstat(child_fd), entry): raise RuntimeError(f"directory changed while opening: {archive_name}")',
+    "                walk(archive, child_fd, archive_name)",
+    "            finally: os.close(child_fd)",
+    "            continue",
+    '        if not stat.S_ISREG(entry.st_mode) or entry.st_nlink != 1: raise RuntimeError(f"unsafe publish entry: {archive_name}")',
+    "        file_fd = os.open(name, file_flags, dir_fd=directory_fd)",
+    "        try:",
+    "            opened = os.fstat(file_fd); current = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)",
+    '            if opened.st_nlink != 1 or not same(opened, entry) or not same(opened, current): raise RuntimeError(f"file changed while opening: {archive_name}")',
+    "            info = zipfile.ZipInfo(archive_name); info.compress_type = zipfile.ZIP_DEFLATED; info.external_attr = (opened.st_mode & 0xFFFF) << 16",
+    '            with archive.open(info, "w") as output:',
+    "                while True:",
+    "                    chunk = os.read(file_fd, 65536)",
+    "                    if not chunk: break",
+    "                    output.write(chunk)",
+    "        finally: os.close(file_fd)",
+    "path = os.path.normpath(sys.argv[1] if os.path.isabs(sys.argv[1]) else os.path.join(os.getcwd(), sys.argv[1]))",
+    'root_fd = os.open("/", directory_flags)',
+    "try:",
+    '    for component in [part for part in path.split("/") if part]:',
+    "        next_fd = os.open(component, directory_flags, dir_fd=root_fd); os.close(root_fd); root_fd = next_fd",
+    '    with zipfile.ZipFile(sys.stdout.buffer, "w", allowZip64=True) as archive: walk(archive, root_fd)',
+    "finally: os.close(root_fd)",
+    "SPACEFAST_ARCHIVE",
+];
 /**
- * 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.
+ * The zero-install publish sequence: a replay-safe curl loop 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:",
+    "Publish a single file after rejecting symbolic links in the file or any existing ancestor:",
+    "Set `SPACEFAST_PUBLISH_TARGET` through the agent runtime/environment, not by interpolating",
+    "a repository path into this source. The recipe passes it as a separately quoted argv element.",
+    "Fresh serving capacity can take a moment; it replays only `space_capacity_warming` with one",
+    "stable idempotency identity, follows `Retry-After`, and stops after ten attempts:",
     "",
     "```bash",
-    `curl -sS -F "files=@index.html" ${PUBLISH_ENDPOINT}`,
+    ': "${SPACEFAST_PUBLISH_TARGET:?set this through the runtime environment}"',
+    "bash -s -- \"$SPACEFAST_PUBLISH_TARGET\" <<'SPACEFAST_PUBLISH'",
+    "set -euo pipefail",
+    'publish_target="$1"',
+    'case "$publish_target" in -*) publish_target="./$publish_target" ;; esac',
+    ...LEXICAL_PUBLISH_PATH_PREFLIGHT,
+    '[ -f "$publish_target" ] || { printf "error: publish file is not a regular file\\n" >&2; exit 2; }',
+    'escaped_path="${publish_target//\\\\/\\\\\\\\}"',
+    'escaped_path="${escaped_path//\\"/\\\\\\"}"',
+    "idempotency_key=\"publish-$(od -An -N16 -tx1 /dev/urandom | tr -d ' \\n')\"",
+    "idempotency_principal=\"$(od -An -N32 -tx1 /dev/urandom | tr -d ' \\n')\"",
+    'api_origin="${SPACEFAST_API_ORIGIN:-https://api.spacefast.com}"',
+    'headers_file="$(mktemp)"',
+    "trap 'rm -f \"$headers_file\"' EXIT",
+    "attempt=1",
+    "while :; do",
+    '  response="$(curl -q -sS -D "$headers_file" -F "files=@\\"$escaped_path\\"" \\',
+    '    -H "Idempotency-Key: $idempotency_key" \\',
+    '    -H "x-spacefast-idempotency-principal: $idempotency_principal" \\',
+    '    "$api_origin/v1/publish")"',
+    '  if ! printf \'%s\' "$response" | grep -Eq \'"code"[[:space:]]*:[[:space:]]*"space_capacity_warming"\'; then',
+    "    printf '%s\\n' \"$response\"",
+    "    break",
+    "  fi",
+    '  [ "$attempt" -lt 10 ] || { printf \'%s\\n\' "$response"; exit 1; }',
+    '  retry_after="$(awk \'tolower($1) == "retry-after:" { gsub("\\r", "", $2); print $2; exit }\' "$headers_file")"',
+    '  case "$retry_after" in ""|*[!0-9]*) retry_after=20 ;; esac',
+    "  attempt=$((attempt + 1))",
+    '  sleep "$retry_after"',
+    "done",
+    "SPACEFAST_PUBLISH",
     "```",
     "",
     "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:",
+    "control, auth state, unrelated build/cache folders, or symbolic links:",
+    "Set `SPACEFAST_PUBLISH_TARGET` through the agent runtime/environment. It is passed as a",
+    "separately quoted argv element and is never evaluated as outer shell source:",
     "",
     "```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}`,
+    ': "${SPACEFAST_PUBLISH_TARGET:?set this through the runtime environment}"',
+    "bash -s -- \"$SPACEFAST_PUBLISH_TARGET\" <<'SPACEFAST_PUBLISH'",
+    "set -euo pipefail",
+    'publish_target="$1"',
+    'case "$publish_target" in -*) publish_target="./$publish_target" ;; esac',
+    ...LEXICAL_PUBLISH_PATH_PREFLIGHT,
+    `find "$publish_target" \\( ${findExpr(ARCHIVE_SECRET_GLOBS)} \\) -print`,
+    '! find "$publish_target" -type l -print -quit | grep -q . || { printf "error: symbolic link in publish root\\n" >&2; exit 2; }',
+    ...SECURE_ARCHIVE_RECIPE,
+    "SPACEFAST_PUBLISH",
     "```",
     "",
-    "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.",
+    "If the preflight prints credential-like files, or the publish root contains a symbolic link,",
+    "stop and choose a narrower generated output directory or remove the unsafe entry before uploading.",
 ].join("\n");
 /**
  * What the JSON publish receipt contains and how to read it. The receipt is the
@@ -216,10 +378,12 @@ 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; share it for reviews.",
-    "  It is reserved in the initial receipt. If the publish is still finalizing, poll `data.links.status`",
-    "  with the claim token until the status is `ready`.",
-    "- `data.shareBlurb` — a paste-ready one-liner with the URL and claim nudge; relay it verbatim when present.",
+    "- `data.open.url` and `data.open.expiresAt` — reusable access; claim preserves the URL and changes its expiry to null.",
+    "  It is not a stable URL or recipient Link; clients must not persist it as Space state.",
+    "- `data.version.immutableUrl` — the permanent address of the frozen Version. The bare URL",
+    "  carries no authority: use the receipt's Open URL for the author's browser or create a scoped",
+    "  Link for a recipient. It is reserved in the initial receipt. If the publish is still",
+    "  finalizing, poll `data.links.status` with the claim token until the status is `ready`.",
     "- `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.",
@@ -232,7 +396,7 @@ export const RECEIPT_SHAPE_PROSE = [
     `  \`POST ${EXCHANGE_ENDPOINT}\` for a durable credential.`,
     "  Never print it back to the user.",
     "- `data.links.status`, `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.",
+    "- `code`, `type`, and `suggestions` on the problem document — stable error code plus exact recovery docs and next steps.",
     "",
     "If no files changed, the API may omit `upload`; report the receipt and diagnostics rather than",
     "inventing a separate success signal.",
@@ -246,7 +410,7 @@ export const SIGNED_UPLOAD_PROSE = [
     "content would be awkward. Start with a manifest instead of file bytes:",
     "",
     "```bash",
-    `curl -sS ${PUBLISH_ENDPOINT} \\`,
+    `curl -q -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"}]}\'',
     "```",
@@ -259,7 +423,7 @@ export const SIGNED_UPLOAD_PROSE = [
     "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 \\",
+    "curl -q -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"}}\'',
@@ -287,10 +451,18 @@ export const AGENT_PROSE = {
     receiptShape: RECEIPT_SHAPE_PROSE,
     signedUpload: SIGNED_UPLOAD_PROSE,
     checkBeforePublish: CHECK_BEFORE_PUBLISH_PROSE,
+    checkBeforePublishApi: CHECK_BEFORE_PUBLISH_API_PROSE,
+    checkBeforePublishMcp: CHECK_BEFORE_PUBLISH_MCP_PROSE,
+    bundledSaveState: BUNDLED_SAVE_STATE_PROSE,
     saveState: SAVE_STATE_PROSE,
+    saveStateApi: SAVE_STATE_API_PROSE,
+    saveStateMcp: SAVE_STATE_MCP_PROSE,
     updateSpace: UPDATE_SPACE_PROSE,
     continueAfterClaim: CONTINUE_AFTER_CLAIM_PROSE,
     lanePicker: LANE_PICKER_PROSE,
     howToResearch: HOW_TO_RESEARCH_PROSE,
+    howToResearchApi: HOW_TO_RESEARCH_API_PROSE,
+    howToResearchMcp: HOW_TO_RESEARCH_MCP_PROSE,
     envNotes: ENV_NOTES_PROSE,
+    envNotesApi: ENV_NOTES_API_PROSE,
 };