@spacefast/common 0.2.1 → 0.4.1

package/dist/contracts/zero.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
+import { connectorRoleSchema } from "./connectors.js";
+import { contentStableIdSchema } from "./content-model.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";
+import { compiledContentModelArtifactsV1Schema, runtimeCapabilityIdSchema, } from "./runtime-components.js";
 /**
  * Spacefast Zero: capsules of schema, queries, mutations and endpoints that run
  * together inside one parent-owned transaction, executed by the native runner
@@ -18,7 +21,19 @@ export const ZERO_SOURCE_METADATA_KEY = "statticZero";
  * worker.
  */
 export const ZERO_RUNTIME_KIND = "zero";
-export const ZERO_PLATFORM_ROUTE_PREFIX = `${PLATFORM_ROUTE_PREFIX}/zero`;
+/**
+ * The canonical Zero control namespace. Every Zero HTTP control route lives
+ * under this prefix; new clients, the dev server, the runtime engine and the
+ * finalizer all emit it.
+ */
+export const ZERO_PLATFORM_ROUTE_PREFIX = "/__zero";
+/**
+ * The pre-cutover namespace, served forever as an alias of the canonical one.
+ * Frozen capsules baked clients that fetch these paths at build time and a
+ * republish cannot be assumed, so the runtime answers both prefixes with the
+ * same handlers and never redirects between them.
+ */
+export const ZERO_LEGACY_ROUTE_PREFIX = `${PLATFORM_ROUTE_PREFIX}/zero`;
 /**
  * Entry paths the Zero scaffold writes into `sf.jsonc#runtime`. Starting points
  * only: a capsule's entries are whatever its `runtime.server`/`runtime.client`
@@ -33,9 +48,27 @@ export const ZERO_RUNTIME_ROUTE_PATHS = {
     db: `${ZERO_PLATFORM_ROUTE_PREFIX}/db`,
     logs: `${ZERO_PLATFORM_ROUTE_PREFIX}/logs`,
     run: `${ZERO_PLATFORM_ROUTE_PREFIX}/run`,
-    authStart: `${ZERO_PLATFORM_ROUTE_PREFIX}/auth/gravatar/start`,
+    // Provider-agnostic on purpose: which identity providers answer it (Gravatar
+    // today, WordPress.com as the option lands) is the auth flow's business, not
+    // the URL's.
+    authStart: `${ZERO_PLATFORM_ROUTE_PREFIX}/auth/start`,
     authSignOut: `${ZERO_PLATFORM_ROUTE_PREFIX}/auth/sign-out`,
 };
+/**
+ * The same operations under {@link ZERO_LEGACY_ROUTE_PREFIX}, spelled exactly
+ * as frozen clients baked them (note `auth/gravatar/start`). Registration-side
+ * only: handlers register both, emission always uses the canonical paths.
+ */
+export const ZERO_LEGACY_ROUTE_PATHS = {
+    config: `${ZERO_LEGACY_ROUTE_PREFIX}/config`,
+    realtime: `${ZERO_LEGACY_ROUTE_PREFIX}/realtime`,
+    inspect: `${ZERO_LEGACY_ROUTE_PREFIX}/inspect`,
+    db: `${ZERO_LEGACY_ROUTE_PREFIX}/db`,
+    logs: `${ZERO_LEGACY_ROUTE_PREFIX}/logs`,
+    run: `${ZERO_LEGACY_ROUTE_PREFIX}/run`,
+    authStart: `${ZERO_LEGACY_ROUTE_PREFIX}/auth/gravatar/start`,
+    authSignOut: `${ZERO_LEGACY_ROUTE_PREFIX}/auth/sign-out`,
+};
 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`;
@@ -64,6 +97,20 @@ export const ZERO_PLATFORM_ASSET_ROOT = `${ZERO_PLATFORM_ASSET_NAMESPACE}/platfo
 export function zeroPlatformAssetPath(digest, fileName) {
     return `${ZERO_PLATFORM_ASSET_ROOT}/${digest}/${fileName}`;
 }
+/**
+ * Where a capsule's island bytes serve from: one content-addressed directory per
+ * build.
+ *
+ * Capsule code, unlike {@link ZERO_PLATFORM_ASSET_ROOT} — these are the author's
+ * own components, code-split. They share the namespace because they share its
+ * one property that matters: the URL names the bytes, so a browser holding the
+ * previous build's chunk never serves it for this one.
+ */
+export const ZERO_ISLANDS_ASSET_ROOT = `${ZERO_PLATFORM_ASSET_NAMESPACE}/islands`;
+/** The serving path of one file in the island bundle identified by `digest`. */
+export function zeroIslandAssetPath(digest, fileName) {
+    return `${ZERO_ISLANDS_ASSET_ROOT}/${digest}/${fileName}`;
+}
 /**
  * The compiled capsule server, which the QuickJS runner instantiates whole.
  *
@@ -120,8 +167,108 @@ const zeroRoutePathSchema = appRoutePathSchema({
     reservedPaths: ZERO_RESERVED_APP_ROUTE_PATHS,
     reservedPrefixes: ZERO_RESERVED_APP_ROUTE_PREFIXES,
 });
+const zeroPageAppPathSchema = appRoutePathSchema({
+    subject: "Zero pages",
+    reservedPaths: [
+        ...ZERO_RESERVED_APP_ROUTE_PATHS.filter((path) => path !== "/"),
+        ZERO_PLATFORM_ROUTE_PREFIX,
+        "/zero",
+    ],
+    reservedPrefixes: [
+        ...ZERO_RESERVED_APP_ROUTE_PREFIXES,
+        `${ZERO_PLATFORM_ROUTE_PREFIX}/`,
+        "/zero/",
+    ],
+});
+export const zeroPagePathSchema = z.string().superRefine((path, ctx) => {
+    const segments = path.split("/");
+    if (segments.some((segment, index) => segment.startsWith(".") && !(index === 1 && segment.toLowerCase() === ".well-known")) ||
+        ["/.well-known/spacefast-runtime", "/.well-known/stattic-runtime"].includes(path.toLowerCase())) {
+        ctx.addIssue({ code: "custom", message: "Zero pages cannot use a runtime-private path." });
+    }
+    const params = new Set();
+    for (const [index, segment] of segments.entries()) {
+        if (!segment.startsWith(":") && !segment.startsWith("*"))
+            continue;
+        const name = segment.slice(1);
+        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ||
+            params.has(name) ||
+            (segment.startsWith("*") && index !== segments.length - 1)) {
+            ctx.addIssue({
+                code: "custom",
+                message: "Zero pages require unique named parameters and a terminal catch-all.",
+            });
+        }
+        params.add(name);
+    }
+    const parsed = zeroPageAppPathSchema.safeParse(segments
+        .map((segment) => segment.startsWith("*") ? ":splat" : segment.startsWith(":") ? ":param" : segment)
+        .join("/"));
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues)
+            ctx.addIssue({ code: "custom", message: issue.message });
+    }
+    if (path === `/${ZERO_PLATFORM_ASSET_NAMESPACE}` || path === `/${ZERO_RUNTIME_STORAGE_ROOT}`) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Zero pages cannot use a path the platform reserves.",
+        });
+    }
+});
+export const ZERO_PUBLIC_CLIENT_SHELL_PATH = "_spacefast/pages/client.html";
+const zeroPageFields = {
+    id: contentStableIdSchema,
+    path: zeroPagePathSchema,
+    file: z.string().min(1),
+    params: z.array(z.string()),
+};
+export const zeroPageSchema = z
+    .discriminatedUnion("render", [
+    z
+        .object({
+        ...zeroPageFields,
+        render: z.literal("document"),
+        bindingId: contentStableIdSchema,
+    })
+        .strict(),
+    z
+        .object({
+        ...zeroPageFields,
+        render: z.literal("client"),
+        shell: z.literal(ZERO_PUBLIC_CLIENT_SHELL_PATH),
+    })
+        .strict(),
+])
+    .superRefine((page, ctx) => {
+    const params = page.path
+        .split("/")
+        .filter((segment) => /^[*:]/.test(segment))
+        .map((segment) => segment.slice(1));
+    if (params.length !== page.params.length ||
+        params.some((param, index) => param !== page.params[index])) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["params"],
+            message: "Page parameters must match the route, in order.",
+        });
+    }
+    if (page.render === "document" && params.length > 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["path"],
+            message: "Document pages require a literal route.",
+        });
+    }
+});
+/**
+ * What an invocation is allowed to do. Every Zero invocation declares it, and
+ * the runtime opens the matching transaction: a `read` runs on one read-only
+ * consistent snapshot, a `write` on the handler's own transaction.
+ */
+export const zeroExecutionModeSchema = z.enum(["read", "write"]);
 export const zeroEndpointSchema = z
     .object({
+    mode: zeroExecutionModeSchema,
     method: httpMethodSchema,
     path: zeroRoutePathSchema,
 })
@@ -251,6 +398,12 @@ export const zeroTableSchema = z
     }
 });
 export const zeroDatabaseSchema = z.record(z.string(), zeroTableSchema);
+export const ZERO_BUILD_CONTEXT_ENV = "SPACEFAST_ZERO_BUILD_CONTEXT";
+export const zeroBuildContextSchema = z
+    .object({
+    previousSchema: zeroDatabaseSchema.nullable(),
+})
+    .strict();
 const zeroSha256Schema = executionSha256Schema;
 /**
  * The compiled server travels inline in the finalize payload, which keeps the
@@ -267,10 +420,16 @@ export const zeroRuntimeBundleSchema = executionBundleSchema({
 export const zeroRuntimeStaticFileSchema = executionStaticFileSchema({
     storageRoot: ZERO_RUNTIME_STORAGE_ROOT,
     maxBytes: ZERO_CLIENT_BUNDLE_MAX_BYTES,
-    platformAssetRoot: ZERO_PLATFORM_ASSET_ROOT,
+    // The whole namespace, not just `platform/`: it already holds two
+    // content-addressed directories — the platform build and a capsule's island
+    // bundle — and {@link ZERO_RESERVED_APP_ROUTE_PREFIXES} reserves all of it
+    // from capsule routes for exactly that reason. A third would be the compiler's
+    // too, and enumerating them here would only ever be a list to forget.
+    platformAssetRoot: ZERO_PLATFORM_ASSET_NAMESPACE,
 });
 export const zeroRuntimeRunSourceSchema = z
     .object({
+    executionMode: zeroExecutionModeSchema,
     runId: z.string().min(1).max(256),
     source: z
         .string()
@@ -283,6 +442,7 @@ export const zeroRuntimeRunSourceSchema = z
     .strict();
 export const zeroRuntimeEndpointSourceSchema = z
     .object({
+    executionMode: zeroExecutionModeSchema,
     method: httpMethodSchema,
     path: zeroRoutePathSchema,
     endpointId: z.string().min(1).max(256),
@@ -506,6 +666,9 @@ export const zeroCapsuleArtifactSchema = z
     format: z.literal("stattic.zero.capsule.v1"),
     appName: z.string().min(1).max(128),
     serverRuntime: z.literal("quickjs-rust"),
+    requiredRuntimeCapabilities: z.array(runtimeCapabilityIdSchema).max(100).optional(),
+    pages: z.array(zeroPageSchema).optional(),
+    connectors: z.array(connectorRoleSchema).default([]),
     client: z
         .object({
         bundlePath: z.string().min(1),
@@ -518,7 +681,6 @@ export const zeroCapsuleArtifactSchema = z
         schema: zeroDatabaseSchema.default({}),
         queries: z.array(zeroNameSchema).default([]),
         mutations: z.array(zeroNameSchema).default([]),
-        actions: z.array(zeroNameSchema).default([]),
         endpoints: z.array(zeroEndpointSchema).default([]),
         sockets: z.array(zeroNameSchema).default([]),
     })
@@ -576,9 +738,23 @@ export const zeroRuntimeFinalizePayloadSchema = z
     auth: z
         .object({
         provider: z.literal("gravatar").default("gravatar"),
-        signInPath: z.literal(ZERO_RUNTIME_ROUTE_PATHS.authStart).nullable().default(null),
+        // Canonical or legacy spelling: configs frozen before the /__zero
+        // cutover carry the legacy paths and must keep validating.
+        signInPath: z
+            .union([
+            z.literal(ZERO_RUNTIME_ROUTE_PATHS.authStart),
+            z.literal(ZERO_LEGACY_ROUTE_PATHS.authStart),
+        ])
+            .nullable()
+            .default(null),
         signInUrl: zeroHttpUrlSchema.nullable().default(null),
-        signOutPath: z.literal(ZERO_RUNTIME_ROUTE_PATHS.authSignOut).nullable().default(null),
+        signOutPath: z
+            .union([
+            z.literal(ZERO_RUNTIME_ROUTE_PATHS.authSignOut),
+            z.literal(ZERO_LEGACY_ROUTE_PATHS.authSignOut),
+        ])
+            .nullable()
+            .default(null),
         signOutUrl: zeroHttpUrlSchema.nullable().default(null),
         returnToParam: z.string().min(1).max(64).default("returnTo"),
     })
@@ -611,14 +787,30 @@ export const zeroRuntimeConfigSchema = zeroRuntimeFinalizePayloadSchema
     inspect: true,
 })
     .extend({
+    connectors: z.object({ token: z.string().min(1) }).optional(),
     variableValues: z.record(z.string(), z.string()).default({}),
     databaseUrlSource: z.enum(["application", "provider"]).default("application"),
 })
     .strict();
+/**
+ * The `statticZero` bag a published version carries in its source metadata.
+ *
+ * `contentModel` rides here beside `finalize` because both are compiled from
+ * the same capsule in the same publish, and both must roll back with the
+ * version that shipped them. The bag stays `.strict()`: this schema is parsed
+ * on the finalize path, so an unrecognized key is a compiler and a control
+ * plane that disagree about what a publish carries, and that is worth failing
+ * on rather than dropping silently.
+ */
 export const zeroDeployMetadataSchema = z
     .object({
+    connectorsTokenHash: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .optional(),
     artifactId: z.string().min(1).optional(),
     finalize: zeroRuntimeFinalizePayloadSchema,
+    contentModel: compiledContentModelArtifactsV1Schema.optional(),
 })
     .strict();
 /**
@@ -647,7 +839,6 @@ export const zeroAppSchema = z
     tables: z.array(z.string()).default([]),
     queries: z.array(z.string()).default([]),
     mutations: z.array(z.string()).default([]),
-    actions: z.array(z.string()).default([]),
     endpoints: z.array(zeroEndpointSchema).default([]),
     sockets: z.array(z.string()).default([]),
     /**
@@ -710,9 +901,10 @@ export function isDestructiveZeroMigrationOperation(operation) {
         operation.op === "rename_column");
 }
 export function createZeroCapsuleArtifact(input) {
-    return zeroCapsuleArtifactSchema.parse({
+    const artifact = {
         format: "stattic.zero.capsule.v1",
         appName: input.appName,
+        connectors: input.connectors ?? [],
         serverRuntime: "quickjs-rust",
         client: {
             bundlePath: input.clientBundlePath ?? ZERO_PUBLIC_CLIENT_BUNDLE_PATH,
@@ -723,7 +915,6 @@ export function createZeroCapsuleArtifact(input) {
             schema: input.schema ?? {},
             queries: input.queries ?? [],
             mutations: input.mutations ?? [],
-            actions: input.actions ?? [],
             endpoints: input.endpoints ?? [],
             sockets: input.sockets ?? [],
         },
@@ -745,7 +936,10 @@ export function createZeroCapsuleArtifact(input) {
             sourceRoot: ".",
             files: [],
         },
-    });
+    };
+    if (input.pages?.length)
+        artifact.pages = input.pages;
+    return zeroCapsuleArtifactSchema.parse(artifact);
 }
 export function createZeroRuntimeInstallProfile(input) {
     return zeroRuntimeInstallProfileSchema.parse({

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

@@ -4,9 +4,9 @@
  */
 export declare const UNBUILT_SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["connect"];
 /** Dashboard route first-segments that cannot be used as team slugs. */
-export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "access", "account", "approvals", "claim", "device", "drop", "new-team", "oauth", "push", "sign-in", "start", "terminal", "two-factor"];
+export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "access", "account", "approvals", "claim", "device", "domains", "drop", "new-team", "oauth", "partners", "push", "sign-in", "spaces", "start", "terminal", "two-factor"];
 /** Dashboard route first-segments that cannot be used as space slugs. */
-export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["agents", "api-keys", "billing", "domains", "drop", "handoffs", "members", "new", "resume", "settings", "variables", "webhooks", "connect"];
+export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["agents", "api-keys", "billing", "connectors", "domains", "drop", "handoffs", "members", "new", "partners", "resume", "settings", "variables", "webhooks", "connect"];
 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>;

package/dist/dashboard-paths/route-reservations.generated.d.ts

@@ -1,2 +1,2 @@
-export declare const DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "access", "account", "approvals", "claim", "device", "drop", "new-team", "oauth", "push", "sign-in", "start", "terminal", "two-factor"];
-export declare const DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["agents", "api-keys", "billing", "domains", "drop", "handoffs", "members", "new", "resume", "settings", "variables", "webhooks"];
+export declare const DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "access", "account", "approvals", "claim", "device", "domains", "drop", "new-team", "oauth", "partners", "push", "sign-in", "spaces", "start", "terminal", "two-factor"];
+export declare const DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["agents", "api-keys", "billing", "connectors", "domains", "drop", "handoffs", "members", "new", "partners", "resume", "settings", "variables", "webhooks"];

package/dist/dashboard-paths/route-reservations.generated.js

@@ -11,11 +11,14 @@ export const DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS = [
     "approvals",
     "claim",
     "device",
+    "domains",
     "drop",
     "new-team",
     "oauth",
+    "partners",
     "push",
     "sign-in",
+    "spaces",
     "start",
     "terminal",
     "two-factor",
@@ -24,11 +27,13 @@ export const DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS = [
     "agents",
     "api-keys",
     "billing",
+    "connectors",
     "domains",
     "drop",
     "handoffs",
     "members",
     "new",
+    "partners",
     "resume",
     "settings",
     "variables",

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

@@ -9,7 +9,7 @@ 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. */
+/** MCP plugin skill lane: use execute for documentation and 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;

package/dist/docs/agent-prose.js

@@ -86,13 +86,15 @@ export const EXPLAIN_TO_USER_PROSE = [
 ].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. Retrying a",
-    "failed publish with the same files is safe: it returns the Space the first attempt created.",
+    "On failure, report the problem document's `code`, `type`, and `requestId`. Follow its documented recovery.",
+    "Do not invent endpoints or read credentials out of auth files. After an uncertain write,",
+    "reuse its retry ID and exact input. Identical files alone do not make a new request safe to retry.",
+    "For authenticated MCP publish, set `requestId` before the first call. For HTTP writes, follow",
+    "the endpoint's idempotency contract. When a receipt provides a status operation, read it before another write.",
     FEEDBACK_PROSE,
 ].join("\n");
 export const LANE_PICKER_PROSE = [
-    "Pick the lane by environment: a one-off publish means curl; a git checkout means the push.new",
+    "Pick the lane by environment: a one-off publish means curl; a git checkout means the git.spacefast.com",
     "remote; repeat work with a filesystem means the CLI — the best setup, `npx -y spacefast` runs it",
     "with no install, and `sf plugins` installs your client's plugin; no filesystem means hosted MCP;",
     "CI means a machine OAuth client. After success, recommend the best next-time setup for the",
@@ -110,11 +112,11 @@ export const HOW_TO_RESEARCH_API_PROSE = [
     "`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. */
+/** MCP plugin skill lane: use execute for documentation and the OpenAPI catalog. */
 export const HOW_TO_RESEARCH_MCP_PROSE = [
-    "For an error, fetch the problem document's `type` URL when present. For workflows and how-to",
-    "recipes, call `search_docs`; the `skills` tool serves the `execute` guide, not workflow recipes.",
-    "For capability questions, use `execute` with `tools.search`.",
+    "For an error, fetch the problem document's `type` URL when present. For workflows, how-to",
+    "recipes, and capability questions, use one `execute` program with `tools.search`.",
+    "Search for and describe the generated documentation operation before you call it.",
     "For contracts, read `publish-spec.json` or OpenAPI via docs. Never guess limits: publish,",
     "then inspect status or diagnostics through `execute`.",
 ].join("\n");
@@ -161,15 +163,10 @@ export const CHECK_BEFORE_PUBLISH_API_PROSE = [
     "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:",
-    "",
-    "- 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 one.",
+    "Use the Space from the current conversation or checkout link for an ordinary publish.",
+    "On-Device reuses `.spacefast/` automatically. Do not read its credential file or list all",
+    "Spaces before publishing. Hosted callers must pass the known `spaceId` to update a Space.",
+    "Set `createNew` only when the user requests a separate Space. Do not also set `spaceId`.",
 ].join("\n");
 /**
  * The SAVE verb: persist the space id and credential after a first publish so
@@ -236,7 +233,7 @@ export const PUSH_TO_DEPLOY_PROSE = [
     "and pushing are one credential, not two.",
     "",
     "```bash",
-    "git remote add spacefast https://t:<key>@push.new/<space-slug>.git",
+    "git remote add spacefast https://t:<key>@git.spacefast.com/<space-slug>.git",
     "git push spacefast main",
     "```",
     "",

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

@@ -37,7 +37,7 @@ export declare const AGENT_HANDOFF_CLI_TARGET_IDS: readonly ConnectTargetId[];
 export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before you install tools or publish. Confirm the file or folder to publish.";
 export declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the handoff URL out of command arguments, logs, and replies. It goes in exactly two places: the stdin prompt of `sf setup agent`, or the redeem request body.";
 export declare const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE: string;
-export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's push.new remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
+export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's git.spacefast.com remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export declare function agentHandoffConnectSections(target: ConnectTarget): string[];
 /**

package/dist/docs/agent-setup.js

@@ -17,15 +17,9 @@ 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.
 //
-// `?wait=1` is load-bearing. Without it the 201 returns
-// `activation.outcome: "pending"` and a `next.action: "poll"` pointer at an
-// endpoint that needs the space key as bearer (measured in production: a receipt
-// at ~4.2s for a site that only settles ~37s later). With it the publish returns
-// `activated` / `done`, so the happy path is genuinely one command.
-//
-// The URL is quoted because `?` globs in zsh: unquoted, the 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"`;
+// Omit `async` to wait for finalize. A publish that reaches the request ceiling
+// still returns a polling receipt; agents must follow its `next` instruction.
+export const anonymousPublishCurlCommand = `curl -F "files=@index.html" "${serviceOrigin("api", "prod")}/v1/publish"`;
 /*
  * Agent handoff contract: one opaque bearer lives at
  * https://<access-origin>/handoffs/<token>. Fetching that URL records a read and
@@ -140,7 +134,7 @@ function hostedHandoffTargetName(value) {
             return value;
     }
 }
-export const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's push.new remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
+export const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's git.spacefast.com remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export function agentHandoffConnectSections(target) {
     // When the client's best lane IS its config file, `primary` and `config` are
@@ -381,9 +375,7 @@ function oauthClientNames() {
 }
 /** Clients that have a live one-click install today, named from the registry. */
 function deeplinkClientNames() {
-    return AGENT_REGISTRY.filter((agent) => agent.methods.some((method) => method.kind === "deeplink" &&
-        method.listing.status === "live" &&
-        method.verification.status !== "failed"))
+    return AGENT_REGISTRY.filter((agent) => agent.methods.some((method) => method.kind === "deeplink" && method.listing.status === "live"))
         .map((agent) => agent.name)
         .join(", ");
 }