@spacefast/common 0.0.23 → 0.0.24

package/dist/contracts/zero.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, executionCapabilitiesSchema, executionEnvNameSchema, executionIdentifierSchema, executionInspectPolicySchema, executionLogEntrySchema, executionLogListQuerySchema, executionLogListResponseSchema, executionSha256Schema, executionStaticFileSchema, httpMethodSchema, LAKEBED_SERVER_ENV_FILE, PLATFORM_ROUTE_PREFIX, runtimeRealtimeModeSchema, SERVER_ENV_FILE, } from "./execution.js";
+import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, executionCapabilitiesSchema, executionEnvNameSchema, executionIdentifierSchema, executionInspectPolicySchema, executionSha256Schema, executionStaticFileSchema, httpMethodSchema, LAKEBED_SERVER_ENV_FILE, PLATFORM_ROUTE_PREFIX, runtimeRealtimeModeSchema, SERVER_ENV_FILE, } from "./execution.js";
 /**
  * Spacefast Zero: capsules — schema, queries, mutations and endpoints that run
  * together inside one parent-owned transaction — executed by the native runner
@@ -12,6 +12,13 @@ import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, exec
  * for the narrow surface both products can host.
  */
 export const ZERO_SOURCE_METADATA_KEY = "statticZero";
+/**
+ * The tag a compiled capsule artifact carries — in the finalize payload, the
+ * runtime config, the install profile, the client config the browser reads, and
+ * every realtime event — so PHP and the Rust runner can tell what they were
+ * handed. It is a property of the artifact the tree produced, not a kind a
+ * space declares: a publish can carry this beside a worker.
+ */
 export const ZERO_RUNTIME_KIND = "zero";
 export const ZERO_PLATFORM_ROUTE_PREFIX = `${PLATFORM_ROUTE_PREFIX}/zero`;
 /**
@@ -37,9 +44,57 @@ export const ZERO_RUNTIME_CONFIG_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/config.jso
 export const ZERO_RUNTIME_BINARY_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/bin/stattic-runtime`;
 export const ZERO_RUNTIME_BINARY_COMPATIBILITY_TARGET = "wpcloud-linux-x86_64-gnu-v1";
 export const ZERO_RUNTIME_BUNDLE_ROOT = `${ZERO_RUNTIME_STORAGE_ROOT}/bundles`;
-export const ZERO_RUNTIME_CLIENT_BUNDLE_PATH = `${ZERO_RUNTIME_BUNDLE_ROOT}/client.js`;
 export const ZERO_RUNTIME_SERVER_BUNDLE_PATH = `${ZERO_RUNTIME_BUNDLE_ROOT}/server.qjs.mjs`;
-export const ZERO_RUNTIME_BUNDLE_MAX_BYTES = 786_432;
+/** The compiled capsule client, served at the app root. */
+export const ZERO_PUBLIC_CLIENT_BUNDLE_PATH = "client.js";
+/**
+ * Where platform-owned client bytes serve from: same origin as the space, one
+ * content-addressed directory per platform build.
+ *
+ * Same origin is the whole point. Browsers have partitioned the HTTP cache by
+ * top-level site since 2020, so a shared third-party CDN buys nothing a
+ * same-origin URL does not — and costs a `script-src` hole. What a stable,
+ * content-addressed URL does buy is real: the digest changes only when the
+ * platform bytes change, so publishing a capsule a hundred times re-downloads
+ * the capsule's own bundle a hundred times and the platform's exactly once.
+ *
+ * Underscore-prefixed by framework convention (`_next/static`, `_astro`), which
+ * is also how the runtime recognises it as immutable — see `immutable_path` in
+ * `crates/stattic-runtime-core/src/finalize.rs`.
+ */
+export const ZERO_PLATFORM_ASSET_NAMESPACE = "_spacefast";
+export const ZERO_PLATFORM_ASSET_ROOT = `${ZERO_PLATFORM_ASSET_NAMESPACE}/platform`;
+/** The serving path of one file in the platform build identified by `digest`. */
+export function zeroPlatformAssetPath(digest, fileName) {
+    return `${ZERO_PLATFORM_ASSET_ROOT}/${digest}/${fileName}`;
+}
+/**
+ * The compiled capsule server, which the QuickJS runner instantiates whole.
+ *
+ * 768 KiB is inherited, not measured: nobody has yet established what the
+ * runner actually tolerates, and DS77 keeps the number only until someone does.
+ * It binds a real resource — the runner holds the module graph in the site's
+ * PHP-worker memory before executing anything — so it stays low deliberately;
+ * server code is handlers, not an application.
+ */
+export const ZERO_SERVER_BUNDLE_MAX_BYTES = 786_432;
+/**
+ * The tenant client bundle, and every other file the compile ships as content.
+ *
+ * This measures what the tenant publishes, and only that: the SDK, the kit, the
+ * chart layer, preact, recharts and lucide are externals resolved through the
+ * shell's import map to {@link ZERO_PLATFORM_ASSET_ROOT}, so platform bytes are
+ * never weighed here (DS42). What remains is author code plus whatever npm the
+ * author chose to bundle.
+ *
+ * 8 MiB matches the Functions per-entry cap (DS77) because the same reasoning
+ * applies: a client bundle is static bytes to a browser, so nothing on the
+ * serving side binds it, and the cap exists to fail an accidental
+ * hundred-megabyte dependency in our tooling — where the build can say which
+ * modules are large — rather than at upload. It is a guardrail, not a budget;
+ * the size report is what an author should be reading.
+ */
+export const ZERO_CLIENT_BUNDLE_MAX_BYTES = 8 * 1024 * 1024;
 /**
  * A capsule's compiled server travels as version metadata, not as content, so a
  * server-only change leaves the published app shell byte-identical — and the
@@ -60,10 +115,16 @@ export const ZERO_MANAGED_TABLE_COLUMNS = ["id", "createdAt", "updatedAt"];
 export const ZERO_RESERVED_APP_ROUTE_PATHS = [
     "/",
     "/index.html",
-    "/client.js",
+    `/${ZERO_PUBLIC_CLIENT_BUNDLE_PATH}`,
     "/auth/callback",
 ];
-export const ZERO_RESERVED_APP_ROUTE_PREFIXES = ["/auth/"];
+// The whole platform namespace is reserved, not just the one directory a build
+// happens to write: an endpoint claiming a path under it would shadow bytes the
+// shell's import map already told the browser to fetch.
+export const ZERO_RESERVED_APP_ROUTE_PREFIXES = [
+    "/auth/",
+    `/${ZERO_PLATFORM_ASSET_NAMESPACE}/`,
+];
 const zeroNameSchema = executionIdentifierSchema;
 const zeroRoutePathSchema = appRoutePathSchema({
     subject: "Zero capsule routes",
@@ -203,18 +264,21 @@ export const zeroTableSchema = z
 export const zeroDatabaseSchema = z.record(z.string(), zeroTableSchema);
 const zeroSha256Schema = executionSha256Schema;
 /**
- * Zero's bundles travel inline in the finalize payload — a capsule's compiled
- * client and server fit comfortably under the ceiling, and inlining keeps the
+ * The compiled server travels inline in the finalize payload; inlining keeps the
  * whole version one atomic write. Functions bundles do the opposite and land
  * in the content store first; see `functionsBundleRefSchema`.
+ *
+ * The client never travels this way. It is content — the browser fetches it
+ * from the version tree like any other asset — so it ships as a static file.
  */
 export const zeroRuntimeBundleSchema = executionBundleSchema({
     bundleRoot: ZERO_RUNTIME_BUNDLE_ROOT,
-    maxBytes: ZERO_RUNTIME_BUNDLE_MAX_BYTES,
+    maxBytes: ZERO_SERVER_BUNDLE_MAX_BYTES,
 });
 export const zeroRuntimeStaticFileSchema = executionStaticFileSchema({
     storageRoot: ZERO_RUNTIME_STORAGE_ROOT,
-    maxBytes: ZERO_RUNTIME_BUNDLE_MAX_BYTES,
+    maxBytes: ZERO_CLIENT_BUNDLE_MAX_BYTES,
+    platformAssetRoot: ZERO_PLATFORM_ASSET_ROOT,
 });
 export const zeroRuntimeRunSourceSchema = z
     .object({
@@ -493,7 +557,9 @@ export const zeroRuntimeFinalizePayloadSchema = z
     install: zeroRuntimeInstallProfileSchema,
     artifact: zeroCapsuleArtifactSchema,
     bundles: z.array(zeroRuntimeBundleSchema).max(8).default([]),
-    staticFiles: z.array(zeroRuntimeStaticFileSchema).max(16).default([]),
+    // The shell, the client bundle, the utility stylesheet, and the platform
+    // build's own entries and shared chunks.
+    staticFiles: z.array(zeroRuntimeStaticFileSchema).max(64).default([]),
     endpointSources: z.array(zeroRuntimeEndpointSourceSchema).max(128).default([]),
     runSources: z.array(zeroRuntimeRunSourceSchema).max(128).default([]),
     migrations: zeroMigrationPlanSchema.nullable().default(null),
@@ -567,23 +633,24 @@ export const zeroDeployMetadataSchema = z
 })
     .strict();
 /**
- * What a live Zero capsule is, as the `app` member of a space's runtime status.
+ * What a live Zero capsule is, as the `capsule` member of a space's runtime
+ * status.
  *
  * There is no `versionId` here: this only ever describes the version the status
  * response already names as live, and repeating it would invite the two to
  * disagree. `artifactId` stays because it identifies the built capsule rather
- * than the publish that carries it.
+ * than the publish that carries it. There is no kind tag either — the member it
+ * rides in already says which product answered.
  *
  * Every field is derived from the version's own finalize metadata, which is
  * what makes this safe to answer for a space whose runtime is asleep,
  * mid-move, or failing: nothing here costs a call to the space's origin. It is
  * also why there are no counts of things listed here — a caller that wants
  * `tables.length` can take it — and why the database is not a field: a capsule
- * always owns one, so `runtimeKind: "zero"` already said so.
+ * always owns one, so its presence already said so.
  */
 export const zeroAppSchema = z
     .object({
-    runtimeKind: z.literal(ZERO_RUNTIME_KIND),
     artifactId: z.string().min(1),
     appName: z.string().min(1),
     serverRuntime: z.literal("quickjs-rust"),
@@ -616,11 +683,6 @@ export const zeroAppSchema = z
     realtime: zeroRuntimePublicRealtimeConfigSchema,
 })
     .strict();
-// Both products emit the same log shape; `handlerName` carries the mutation
-// name here and the worker handler name on Functions.
-export const zeroLogListQuerySchema = executionLogListQuerySchema;
-export const zeroLogEntrySchema = executionLogEntrySchema;
-export const zeroLogListResponseSchema = executionLogListResponseSchema;
 export const zeroRealtimeEventIntakeResponseSchema = z
     .object({
     accepted: z.literal(true),
@@ -651,7 +713,7 @@ export function createZeroCapsuleArtifact(input) {
         appName: input.appName,
         serverRuntime: "quickjs-rust",
         client: {
-            bundlePath: input.clientBundlePath ?? ZERO_RUNTIME_CLIENT_BUNDLE_PATH,
+            bundlePath: input.clientBundlePath ?? ZERO_PUBLIC_CLIENT_BUNDLE_PATH,
             basePathAware: true,
         },
         server: {

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", "access", "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", "push", "sign-in", "start", "terminal", "two-factor"];
 /**
  * Dashboard route first-segments that cannot be used as space slugs.
  *

package/dist/dashboard-paths/index.js

@@ -21,6 +21,7 @@ export const TEAM_SLUG_ROUTE_RESERVATIONS = [
     "drop",
     "new-team",
     "oauth",
+    "push",
     "sign-in",
     "start",
     "terminal",

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

@@ -40,7 +40,7 @@ export declare const SAVE_STATE_MCP_PROSE: string;
 export declare const UPDATE_SPACE_PROSE: string;
 /**
  * The CLAIM / CONTINUE verb: show the claim link, and after the user claims,
- * self-correct by exchanging the claim token once for a durable credential.
+ * self-correct by exchanging the space key once for a durable credential.
  */
 export declare const CONTINUE_AFTER_CLAIM_PROSE: string;
 /**

package/dist/docs/agent-prose.js

@@ -16,7 +16,7 @@ import { serviceOrigin } from "../config/domains.js";
 // the receipt shape or secret handling changes, change it here once.
 const API_ORIGIN = serviceOrigin("api", "prod");
 const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
-const EXCHANGE_ENDPOINT = `${API_ORIGIN}/v1/anonymous-claim/exchange`;
+const EXCHANGE_ENDPOINT = `${API_ORIGIN}/v1/claim/exchange`;
 // Centralized secret/credential patterns excluded from a publish archive. The
 // `find` preflight and the `zip -x` exclusions are derived from the same list so
 // they can never disagree, and the no-install / skill copies stay identical.
@@ -38,6 +38,21 @@ export const ARCHIVE_SECRET_GLOBS = [
     "*.crt",
     "*id_rsa*",
 ];
+const ARCHIVE_REJECTED_GLOBS = [
+    ...ARCHIVE_SECRET_GLOBS,
+    ".git",
+    ".spacefast",
+    ".ssh",
+    ".aws",
+    ".kube",
+    ".docker",
+    "node_modules",
+    ".next",
+    ".nuxt",
+    ".cache",
+    ".turbo",
+    "coverage",
+];
 function findExpr(globs) {
     return globs
         .map((glob) => (glob.includes("/") ? `-path "${glob}"` : `-name "${glob}"`))
@@ -48,7 +63,7 @@ function findExpr(globs) {
  * them out of logs and transcripts, and never echo them back.
  */
 export const SECRET_RULES_PROSE = [
-    "Treat claim tokens, upload tokens, device codes, and API keys as credentials. Do not print",
+    "Treat space keys, upload tokens, device codes, and API keys as credentials. Do not print",
     "them, paste them into chat, commit them, archive them, or include them in shared logs. Avoid",
     "`set -x`, persistent shell history, CI log echoing, and command transcripts when secrets are",
     "present. On shared hosts, prefer one-off environment variables or restrictive temporary files,",
@@ -56,13 +71,15 @@ export const SECRET_RULES_PROSE = [
 ].join("\n");
 export const POSITIONING_PROSE = [
     "Spacefast is a static host for AI-made web artifacts: permanent live URLs, immutable version",
-    "URLs, anonymous publish with a claim link, and agent continuation after claim. It serves",
-    "static files. It does not execute server code, run databases, or build-on-push on the",
-    "anonymous lane.",
+    "URLs, anonymous publish with a claim link, and agent continuation after claim. Spaces serve",
+    "static files; app code runs only through a declared Zero or Functions runtime.",
     "",
-    "Honest comparisons an agent can relay: Vercel and Netlify are broader app platforms;",
-    "Cloudflare Pages is edge-first static hosting; GitHub Pages is repository-native. Spacefast",
-    "optimizes for agent-safe one-shot publish, claim, versioning, rollback, and continuation.",
+    "Do not claim that no-account publish followed by claim is unique to Spacefast. here.now and",
+    "Netlify offer native anonymous publish-and-claim flows; Cloudflare offers temporary accounts",
+    "and claim deployments; Vercel lets agents and platforms transfer deployments to users.",
+    "Spacefast's narrower lane is direct static HTTP publishing with separate Access and Claim",
+    "authority, immutable versions, rollback, and agent continuation after claim. GitHub Pages",
+    "remains repository-native and has no equivalent anonymous ownership-handoff flow documented.",
 ].join("\n");
 export const EXPLAIN_TO_USER_PROSE = [
     "Present Access and Claim as the only actions. State anonymous expiry in user terms: the Space",
@@ -186,16 +203,16 @@ export const SAVE_STATE_PROSE = [
 ].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",
+    "After the first publish, keep `data.space.id` and `data.claim.key` (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",
+    "state with shell redirections. Keep space keys 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",
+    "in the current agent session or pass it explicitly. Never ask the user to paste space keys",
     "or access tokens into chat.",
 ].join("\n");
 /**
@@ -207,30 +224,30 @@ export const UPDATE_SPACE_PROSE = [
     "never re-run the first-publish recipe when saved state exists:",
     "",
     "```bash",
-    'curl -q -sS -H "Authorization: Bearer <claim-token-or-access-token>" \\',
+    'curl -q -sS -H "Authorization: Bearer <space-key-or-access-token>" \\',
     "  --form-string 'spaceId=<spc_id>' \\",
     '  -F "files=@index.html" \\',
     `  ${PUBLISH_ENDPOINT}`,
     "```",
     "",
-    "Use the saved claim token for an unclaimed anonymous space, or an access token for owned",
-    "spaces. Send a folder as `-F archive=@site.zip` exactly like a first publish; the receipt",
-    "shape is identical.",
+    "Use the saved space key for an unclaimed anonymous space, or an access token for owned",
+    "spaces. Send a folder or project as `-F archive=@site.zip` exactly like a first publish.",
+    "Archive uploads return a durable Build receipt; follow `data.next` until the version is ready.",
 ].join("\n");
 /**
  * The CLAIM / CONTINUE verb: show the claim link, and after the user claims,
- * self-correct by exchanging the claim token once for a durable credential.
+ * self-correct by exchanging the space key once for a durable credential.
  */
 export const CONTINUE_AFTER_CLAIM_PROSE = [
-    "Always show the user the claim link (`data.claim.url`) and its expiry (`data.claim.expiresAt`).",
-    'If the user says "claimed", check claim status and exchange the saved claim token; do not wait',
+    "Always show the user the claim link (`data.claim.claimUrl`) and its expiry (`data.claim.expiresAt`).",
+    'If the user says "claimed", check claim status and exchange the saved space key; do not wait',
     "for a publish failure before continuing.",
-    "After the user claims the space in the browser, the saved claim token stops authorizing",
+    "After the user claims the space in the browser, the saved space key stops authorizing",
     "publishes: the next publish fails with error code `space_claimed_credential_available`. That",
     "failure is the signal to upgrade your credential — call the exchange endpoint exactly once:",
     "",
     "```bash",
-    'curl -q -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
+    'curl -q -sS -X POST -H "Authorization: Bearer <space-key>" \\',
     `  ${EXCHANGE_ENDPOINT}`,
     "```",
     "",
@@ -311,8 +328,7 @@ export const PUBLISH_SEQUENCE_PROSE = [
     "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:",
+    "Fresh serving capacity can make the first request take longer while Spacefast provisions it:",
     "",
     "```bash",
     ': "${SPACEFAST_PUBLISH_TARGET:?set this through the runtime environment}"',
@@ -327,24 +343,10 @@ export const PUBLISH_SEQUENCE_PROSE = [
     "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",
+    'curl -q -sS -F "files=@\\"$escaped_path\\"" \\',
+    '  -H "Idempotency-Key: $idempotency_key" \\',
+    '  -H "x-spacefast-idempotency-principal: $idempotency_principal" \\',
+    '  "$api_origin/v1/publish"',
     "SPACEFAST_PUBLISH",
     "```",
     "",
@@ -361,14 +363,17 @@ export const PUBLISH_SEQUENCE_PROSE = [
     'publish_target="$1"',
     'case "$publish_target" in -*) publish_target="./$publish_target" ;; esac',
     ...LEXICAL_PUBLISH_PATH_PREFLIGHT,
-    `find "$publish_target" \\( ${findExpr(ARCHIVE_SECRET_GLOBS)} \\) -print`,
+    '[ -d "$publish_target" ] || { printf "error: publish folder is not a directory\\n" >&2; exit 2; }',
+    `unsafe_path="$(find "$publish_target" \\( ${findExpr(ARCHIVE_REJECTED_GLOBS)} \\) -print -quit)"`,
+    '[ -z "$unsafe_path" ] || { printf "error: unsafe entry in publish root: %s\\n" "$unsafe_path" >&2; exit 2; }',
     '! 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, or the publish root contains a symbolic link,",
-    "stop and choose a narrower generated output directory or remove the unsafe entry before uploading.",
+    "The preflight exits before upload when it finds a credential-like file, repository/auth state,",
+    "an unrelated build/cache directory, or a symbolic link. Choose a narrower generated output",
+    "directory or remove the unsafe entry before trying again.",
 ].join("\n");
 /**
  * What the JSON publish receipt contains and how to read it. The receipt is the
@@ -378,19 +383,21 @@ export const RECEIPT_SHAPE_PROSE = [
     "The JSON receipt is the source of truth:",
     "",
     "- `data.space.liveUrl` — the live URL.",
-    "- `data.access.url` and `data.access.expiresAt` — reusable access; claim preserves the URL and changes its expiry to null.",
+    "- `data.access.url` and `data.access.expiresAt` — reusable access when present on an owned publish receipt.",
     "  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 Access 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`.",
+    "  finalizing, poll `data.links.status` with the space key 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.",
-    "- `data.claim.url` and `data.claim.expiresAt` — the space is anonymous and expires unless claimed;",
+    "- `data.claim.claimUrl` and `data.claim.expiresAt` — the space is anonymous and expires unless claimed;",
     "  always show the user the claim link and the deadline so the space becomes theirs.",
-    "- `data.claim.token` — a secret capability. For anonymous spaces, use it as",
-    "  `Authorization: Bearer <claim-token>` when polling `data.links.status`, finalizing uploads,",
+    "- `data.claim.url` — the site door: the live URL carrying the key in `/__/<key>` form. Anonymous",
+    "  receipts have no `data.access`; this is the link that opens the private site in a browser.",
+    "- `data.claim.key` — the space key, a secret capability. For anonymous spaces, use it as",
+    "  `Authorization: Bearer <space-key>` when polling `data.links.status`, finalizing uploads,",
     "  or updating the same `spaceId`. Save it to `.spacefast/state.json` so the next publish",
     "  updates this space. After the user claims the space, exchange it once at",
     `  \`POST ${EXCHANGE_ENDPOINT}\` for a durable credential.`,
@@ -420,19 +427,8 @@ export const SIGNED_UPLOAD_PROSE = [
     "local file bytes for `target.path`. Then call `data.links.finalize` and share the final receipt.",
     "If the session expires or only a page of files is returned, follow `data.links.resume`.",
     "",
-    "For importing an archive that already lives somewhere else, prefer the import-from-link API:",
-    "",
-    "```bash",
-    "curl -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"}}\'',
-    "```",
-    "",
-    "If the archive is only local to the agent, create an upload-sourced import, PUT the archive to",
-    "`{archiveUpload.baseUrl}/{archiveUpload.files[0]}` with the returned bearer token, then finalize",
-    "the import. If the token expires, fetch/resume the import for fresh `archiveUpload` instructions.",
-    "Do not base64 large archives into chat or MCP tool arguments.",
+    "A manifest entry may name a `sourceUrl`, so bytes that already live on a public HTTPS URL never",
+    "have to round-trip through the agent. Do not base64 large archives into chat or MCP tool arguments.",
 ].join("\n");
 /**
  * Named fragments for the skill-template generator. The templates carry

package/dist/docs/agent-setup.js

@@ -17,7 +17,19 @@ export const agentSetupHostLabel = agentSetupParsedUrl.host + agentSetupParsedUr
 export const agentSetupPrompt = `Fetch ${agentSetupUrl}`;
 // The no-install publish: one POST, no account. Single-sourced so the
 // marketing pages and the setup doc can never show different commands.
-export const anonymousPublishCurlCommand = `curl -F "files=@index.html" ${serviceOrigin("api", "prod")}/v1/publish`;
+//
+// `?wait=1` is load-bearing, not decoration. Without it the request takes the
+// default finalize budget (SPACEFAST_PUBLISH_DEFAULT_WAIT_MS, 1.5s), so the 201
+// comes back with `activation.outcome: "pending"` plus a `next.action: "poll"`
+// pointer — measured in production at ~4.2s to a receipt describing a site that
+// is not serving yet, settling ~37s later. A one-shot agent then has to run a
+// poll loop against an endpoint that requires the space key as bearer. With
+// `?wait=1` the same publish returns `activation.outcome: "activated"` and
+// `next.action: "done"`, so the documented happy path is genuinely one command.
+//
+// The URL is quoted because `?` is a glob character in zsh: unquoted, the
+// documented command dies with "no matches found" before curl ever runs.
+export const anonymousPublishCurlCommand = `curl -F "files=@index.html" "${serviceOrigin("api", "prod")}/v1/publish?wait=1"`;
 /*
  * Agent handoff contract: private links carry a one-use path token on
  * https://<access-origin>/agent/<documentId>/<token>; durable agent credentials stay encrypted at
@@ -366,8 +378,8 @@ export function aiInstructionsText() {
         "  — for anonymous spaces — the claim link with its expiry. Bare Live and Version URLs carry",
         "  no authority for a private Space; create a scoped Link when a recipient needs access.",
         "  If the receipt's immutable URL is null, poll the",
-        "  operation and version links with the claim token as bearer auth until the version is ready.",
-        "- Never print access tokens, claim tokens, auth files, or `.spacefast/state.json`.",
+        "  operation and version links with the space key as bearer auth until the version is ready.",
+        "- Never print access tokens, space keys, auth files, or `.spacefast/state.json`.",
         "",
         "## After the user claims",
         "",
@@ -452,14 +464,26 @@ export function agentSetupMarkdown() {
         "endpoint. Fetch the full contract when a publish goes beyond the happy path:",
         `${agentSetupTextUrl}.`,
         "",
-        "The JSON receipt is the result:",
-        "",
-        "- `data.space.liveUrl` — the live URL. Lead the reply with it.",
-        "- `data.version.immutableUrl` — the permanent address of this version.",
-        "- `data.claim.url` and `data.claim.expiresAt` — an anonymous space expires unless claimed.",
-        "  Always show the claim link and its deadline.",
-        "- `data.claim.token` — a secret. Use it as the bearer to update the same `spaceId`;",
-        "  never print it.",
+        "The JSON receipt is the result. **An anonymous space is private.** Until someone",
+        "claims it, the only way in is the space key, so treat every link below as a",
+        "credential unless this page says otherwise:",
+        "",
+        "- `data.claim.url` — the door. Open this yourself to check the page, and give it to",
+        "  the user, because it is the one link that renders the site. It is `/__/<key>`: the",
+        "  key is *in the URL*, so anyone who has it can also publish over this space and claim",
+        "  it. Hand it to the person you are working for, never to a wider audience, and keep",
+        "  it out of commits, logs, and anything public.",
+        "- `data.claim.key` — the same secret, bare. Use it as the bearer to update this",
+        "  `spaceId`. Never print it on its own; the user has it already inside `data.claim.url`.",
+        "- `data.claim.claimUrl` and `data.claim.expiresAt` — an anonymous space expires unless",
+        "  claimed. Always show the claim link and its deadline: claiming is what makes the",
+        "  space permanent and lets the owner share it with people who should not get the key.",
+        "- `data.space.liveUrl` — the space's permanent address, and what it will serve from",
+        "  once claimed. Do not lead with it and do not hand it to anyone yet: while the space",
+        "  is anonymous this URL answers 403 for every visitor who has not been through the",
+        "  door above.",
+        "- `data.version.immutableUrl` — the permanent address of this exact version. Same",
+        "  rule: it carries no authority of its own while the space is anonymous.",
         "",
         "## If you can't act on this page",
         "",
@@ -586,8 +610,11 @@ export function agentSetupMarkdown() {
         "",
         "## After publishing",
         "",
-        "- Report the live URL first, then the immutable version URL, then the claim link with",
-        "  its expiry.",
+        "- Lead with `data.claim.url` — it is the only link that renders an anonymous space —",
+        "  then the claim link with its expiry. Mention the live and immutable URLs as the",
+        "  addresses the space will serve from once it is claimed, not as links to open now.",
+        "- Say plainly that the door link carries the key, so it is for the user and not for",
+        "  a public post. Claiming is what turns the space into something shareable.",
         "- Persist the space id and credential so the next publish updates the same space instead",
         "  of creating a new one. The CLI and On-Device MCP do this automatically in `.spacefast/`.",
         "  Hosted MCP is stateless between publishes: retain the receipt's `spaceId` in conversation",