@spacefast/common 0.0.23 → 0.0.26

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`;
 /**
@@ -35,11 +42,59 @@ export const ZERO_RUNTIME_STORAGE_ROOT = "__spacefast/zero";
 export const ZERO_RUNTIME_ARTIFACT_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/artifact.json`;
 export const ZERO_RUNTIME_CONFIG_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/config.json`;
 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_BINARY_COMPATIBILITY_TARGET = "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",
@@ -76,7 +137,7 @@ export const zeroEndpointSchema = z
     path: zeroRoutePathSchema,
 })
     .strict();
-function zeroEndpointRouteMatchShape(path) {
+function zeroEndpointRouteMatch(path) {
     const segments = [];
     let score = 0;
     let splat = false;
@@ -105,17 +166,17 @@ export function zeroEndpointRoutesAmbiguous(left, right) {
         (left.method === "HEAD" && right.method === "GET");
     if (!methodsOverlap)
         return false;
-    const leftShape = zeroEndpointRouteMatchShape(left.path);
-    const rightShape = zeroEndpointRouteMatchShape(right.path);
-    if (leftShape.score !== rightShape.score)
+    const leftMatch = zeroEndpointRouteMatch(left.path);
+    const rightMatch = zeroEndpointRouteMatch(right.path);
+    if (leftMatch.score !== rightMatch.score)
         return false;
-    if (!leftShape.splat && leftShape.segments.length < rightShape.segments.length)
+    if (!leftMatch.splat && leftMatch.segments.length < rightMatch.segments.length)
         return false;
-    if (!rightShape.splat && rightShape.segments.length < leftShape.segments.length)
+    if (!rightMatch.splat && rightMatch.segments.length < leftMatch.segments.length)
         return false;
-    return Array.from({ length: Math.min(leftShape.segments.length, rightShape.segments.length) }, (_, index) => index).every((index) => {
-        const segment = leftShape.segments[index];
-        const other = rightShape.segments[index];
+    return Array.from({ length: Math.min(leftMatch.segments.length, rightMatch.segments.length) }, (_, index) => index).every((index) => {
+        const segment = leftMatch.segments[index];
+        const other = rightMatch.segments[index];
         return segment === null || other === null || segment === other;
     });
 }
@@ -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({
@@ -472,7 +536,7 @@ export const zeroCapsuleArtifactSchema = z
         .strict(),
     db: z
         .object({
-        backend: z.literal("wpcloud-mysql"),
+        backend: z.literal("mysql"),
         migrations: z.array(zeroMigrationOperationSchema).default([]),
     })
         .strict(),
@@ -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: {
@@ -664,7 +726,7 @@ export function createZeroCapsuleArtifact(input) {
             sockets: input.sockets ?? [],
         },
         db: {
-            backend: "wpcloud-mysql",
+            backend: "mysql",
             migrations: [],
         },
         realtime: {

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

@@ -6,6 +6,7 @@ export declare const ARCHIVE_SECRET_GLOBS: readonly [".env*", ".npmrc", ".netrc"
 export declare const SECRET_RULES_PROSE: string;
 export declare const POSITIONING_PROSE: string;
 export declare const EXPLAIN_TO_USER_PROSE: string;
+export declare const FEEDBACK_PROSE = "With user approval, send feedback with `sf feedback`, MCP `execute` (search `send feedback`), or `POST /v1/feedback`. Never include credentials or private links.";
 export declare const FAILURE_CONDUCT_PROSE: string;
 export declare const LANE_PICKER_PROSE: string;
 export declare const HOW_TO_RESEARCH_PROSE: string;
@@ -40,7 +41,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;
 /**
@@ -91,4 +92,3 @@ export declare const AGENT_PROSE: {
     readonly envNotes: string;
     readonly envNotesApi: string;
 };
-export type AgentProseKey = keyof typeof AGENT_PROSE;

package/dist/docs/agent-prose.js

@@ -4,7 +4,7 @@ import { serviceOrigin } from "../config/domains.js";
 //
 //   - packages/cli/skill.template.md  (the SKILL.md router + copies)
 //   - packages/common/src/docs/agent-setup.ts (the /ai and /ai.txt page body)
-//   - apps/www/src/lib/llmo.ts                (the agent-card / discovery prose)
+//   - spacefast/www                           (the agent-card / discovery prose)
 //
 // Each surface re-stated the publish sequence, the secret rules, and the receipt
 // shape in its own words, so they drifted. These fragments are the one source of
@@ -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,21 +63,22 @@ 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,",
     "clear them after use, and avoid durable auth unless the user explicitly asks.",
 ].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.",
+    "Spacefast is the best place to share AI artifacts.",
+    "Spaces serve files directly; 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 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",
@@ -70,10 +86,12 @@ export const EXPLAIN_TO_USER_PROSE = [
     "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 FEEDBACK_PROSE = "With user approval, send feedback with `sf feedback`, MCP `execute` (search `send feedback`), or `POST /v1/feedback`. Never include credentials or private links.";
 export const FAILURE_CONDUCT_PROSE = [
     "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`.",
+    "Do not invent undocumented endpoints. Do not read credentials out of auth files. Retrying a",
+    "failed publish with the same files is safe: it returns the Space the first attempt created.",
+    FEEDBACK_PROSE,
 ].join("\n");
 export const LANE_PICKER_PROSE = [
     "Pick the lane by environment: filesystem plus repeat work means CLI or On-Device MCP; no",
@@ -124,7 +142,7 @@ export const CHECK_BEFORE_PUBLISH_PROSE = [
     "",
     "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.",
+    "and the user wants a new one.",
 ].join("\n");
 export const CHECK_BEFORE_PUBLISH_API_PROSE = [
     "Before creating a space, check whether this project already has one:",
@@ -140,7 +158,7 @@ export const CHECK_BEFORE_PUBLISH_API_PROSE = [
     "",
     "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.",
+    "and the user wants a new one.",
 ].join("\n");
 export const CHECK_BEFORE_PUBLISH_MCP_PROSE = [
     "Before creating a space, check whether this project already has one:",
@@ -151,7 +169,7 @@ export const CHECK_BEFORE_PUBLISH_MCP_PROSE = [
     "- 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.",
+    "another. Only create a new space when none exists and the user wants a new one.",
 ].join("\n");
 /**
  * The SAVE verb: persist the space id and credential after a first publish so
@@ -186,16 +204,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 +225,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 +329,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}"',
@@ -324,27 +341,9 @@ export const PUBLISH_SEQUENCE_PROSE = [
     '[ -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",
+    'curl -q -sS -F "files=@\\"$escaped_path\\"" \\',
+    '  "$api_origin/v1/publish"',
     "SPACEFAST_PUBLISH",
     "```",
     "",
@@ -361,14 +360,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 +380,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 +424,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