@spacefast/common 0.0.13 → 0.0.18

package/dist/contracts/zero.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import { dataEnvelope } from "./common.js";
-import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, executionCapabilitiesSchema, executionEnvNameSchema, executionIdentifierSchema, executionInspectPolicySchema, executionLogEntrySchema, executionLogListQuerySchema, executionLogListResponseSchema, executionSha256Schema, executionStaticFileSchema, httpMethodSchema, PLATFORM_ROUTE_PREFIX, } from "./execution.js";
+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";
 /**
  * Spacefast Zero: capsules — schema, queries, mutations and endpoints that run
  * together inside one parent-owned transaction — executed by the native runner
@@ -15,6 +14,11 @@ import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, exec
 export const ZERO_SOURCE_METADATA_KEY = "statticZero";
 export const ZERO_RUNTIME_KIND = "zero";
 export const ZERO_PLATFORM_ROUTE_PREFIX = `${PLATFORM_ROUTE_PREFIX}/zero`;
+/**
+ * Entry paths the Zero scaffold writes into `sf.jsonc#runtime`. They are
+ * starting points, not the contract: a capsule's entries are whatever its
+ * `runtime.server`/`runtime.client` say, and nothing infers them.
+ */
 export const ZERO_CLIENT_ENTRY = "client/index.tsx";
 export const ZERO_SERVER_ENTRY = "server/index.ts";
 export const ZERO_RUNTIME_ROUTE_PATHS = {
@@ -24,7 +28,7 @@ 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/wpcom/start`,
+    authStart: `${ZERO_PLATFORM_ROUTE_PREFIX}/auth/gravatar/start`,
     authSignOut: `${ZERO_PLATFORM_ROUTE_PREFIX}/auth/sign-out`,
 };
 export const ZERO_RUNTIME_STORAGE_ROOT = "__spacefast/zero";
@@ -35,10 +39,18 @@ export const ZERO_RUNTIME_BINARY_COMPATIBILITY_TARGET = "wpcloud-linux-x86_64-gn
 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_SOURCE_ENV_FILE = ".env.zero.server";
-export const ZERO_CONFIG_FILE = "zero.json";
-export const ZERO_DEPLOY_FILE = ".zero/deploy.json";
 export const ZERO_RUNTIME_BUNDLE_MAX_BYTES = 786_432;
+/**
+ * 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
+ * version intent's manifest comparison would read it as "no changes" and never
+ * deploy it. The publish writes this one small file into the version instead:
+ * it holds a digest of everything the deploy would install, so any server,
+ * schema, or runtime-config change moves the manifest. Same channel a Functions
+ * bundle uses (`functionsBundleStoragePath`) — an ordinary manifest entry, no
+ * artifact-specific plumbing.
+ */
+export const ZERO_RUNTIME_DEPLOY_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/deploy.json`;
 export const ZERO_MANAGED_TABLE_COLUMNS = ["id", "createdAt", "updatedAt"];
 /**
  * Paths the Zero app shell itself answers, on top of the platform-reserved set
@@ -150,12 +162,44 @@ export const zeroTableColumnSchema = z
 })
     .strict()
     .superRefine(zeroDefaultMatchesColumnType);
+export const zeroTableIndexSchema = z
+    .object({
+    name: zeroNameSchema.refine((name) => name !== "by_creation", {
+        message: "by_creation is a built-in Zero index.",
+    }),
+    fields: z.array(zeroNameSchema).min(1),
+})
+    .strict();
 export const zeroTableSchema = z
     .object({
     name: zeroNameSchema,
     columns: z.array(zeroTableColumnSchema).default([]),
+    indexes: z.array(zeroTableIndexSchema).default([]),
 })
-    .strict();
+    .strict()
+    .superRefine((table, context) => {
+    const columnNames = new Set(table.columns.map((column) => column.name));
+    const indexNames = new Set();
+    for (const index of table.indexes) {
+        if (indexNames.has(index.name)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Zero table ${table.name} declares duplicate index ${index.name}.`,
+                path: ["indexes"],
+            });
+        }
+        indexNames.add(index.name);
+        for (const field of index.fields) {
+            if (!columnNames.has(field)) {
+                context.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Zero index ${table.name}.${index.name} references unknown field ${field}.`,
+                    path: ["indexes"],
+                });
+            }
+        }
+    }
+});
 export const zeroDatabaseSchema = z.record(z.string(), zeroTableSchema);
 const zeroSha256Schema = executionSha256Schema;
 /**
@@ -216,10 +260,19 @@ export const zeroMigrationOperationSchema = z.discriminatedUnion("op", [
         .object({
         op: z.literal("add_index"),
         table: zeroNameSchema,
+        name: zeroNameSchema,
         columns: z.array(zeroNameSchema).min(1),
         unique: z.boolean().default(false),
     })
         .strict(),
+    z
+        .object({
+        op: z.literal("drop_index"),
+        table: zeroNameSchema,
+        name: zeroNameSchema,
+        explicit: z.literal("drop"),
+    })
+        .strict(),
     z
         .object({
         op: z.literal("drop_table"),
@@ -261,15 +314,6 @@ export const zeroMigrationPlanSchema = z
     operations: z.array(zeroMigrationOperationSchema),
 })
     .strict();
-const zeroRealtimeCanonicalModeSchema = z.enum(["stattic-central", "spacefast-cast", "local-dev"]);
-const zeroRuntimePublicRealtimeCanonicalModeSchema = z.enum([
-    "stattic-central",
-    "spacefast-cast",
-    "local-dev",
-    "local-websocket",
-]);
-export const zeroRealtimeModeSchema = zeroRealtimeCanonicalModeSchema;
-export const zeroRuntimePublicRealtimeModeSchema = zeroRuntimePublicRealtimeCanonicalModeSchema;
 export const zeroInspectPolicySchema = executionInspectPolicySchema;
 const zeroRuntimePublicPathSchema = z.string().min(1).startsWith("/");
 const zeroHttpUrlSchema = z
@@ -288,7 +332,7 @@ const zeroRealtimeUrlSchema = z
 }, { message: "Realtime URL must use http, https, ws, or wss." });
 export const zeroRuntimePublicAuthConfigSchema = z
     .object({
-    provider: z.literal("wpcom").default("wpcom"),
+    provider: z.literal("gravatar").default("gravatar"),
     signInPath: zeroRuntimePublicPathSchema.nullable().default(null),
     signInUrl: zeroHttpUrlSchema.nullable().default(null),
     signOutPath: zeroRuntimePublicPathSchema.nullable().default(null),
@@ -298,7 +342,7 @@ export const zeroRuntimePublicAuthConfigSchema = z
     .strict();
 export const zeroRuntimePublicRealtimeConfigSchema = z
     .object({
-    mode: zeroRuntimePublicRealtimeModeSchema,
+    mode: runtimeRealtimeModeSchema,
     centralUrl: zeroRealtimeUrlSchema.nullable().default(null),
     path: zeroRuntimePublicPathSchema.optional(),
     replayPath: zeroRuntimePublicPathSchema.nullable().optional(),
@@ -306,6 +350,7 @@ export const zeroRuntimePublicRealtimeConfigSchema = z
     runPath: zeroRuntimePublicPathSchema.nullable().optional(),
     runUrl: zeroHttpUrlSchema.nullable().optional(),
     resourceKey: z.string().min(1).max(256).nullable().optional(),
+    ticketPath: zeroRuntimePublicPathSchema.nullable().optional(),
     socketPath: zeroRuntimePublicPathSchema.nullable().optional(),
     spaceId: z.string().min(1).nullable().optional(),
     versionId: z.string().min(1).nullable().optional(),
@@ -355,7 +400,7 @@ export const zeroRuntimeInstallProfileSchema = z
         .strict(),
     realtime: z
         .object({
-        production: z.literal("stattic-central"),
+        production: z.literal("central"),
         local: z.literal("foreground-cli-ws"),
     })
         .strict(),
@@ -384,42 +429,23 @@ export const zeroSourceFileSchema = z
     .strict();
 export const zeroSourceManifestSchema = z
     .object({
+    // Declared in `sf.jsonc#runtime`, so the manifest records what the author
+    // named rather than a layout the builder assumed.
     entries: z
         .object({
-        client: z.literal(ZERO_CLIENT_ENTRY),
-        server: z.literal(ZERO_SERVER_ENTRY),
+        client: z.string().min(1),
+        server: z.string().min(1),
     })
         .strict(),
     sourceRoot: z.string().min(1),
     files: z.array(zeroSourceFileSchema).default([]),
     env: z
         .object({
-        file: z.literal(ZERO_SOURCE_ENV_FILE),
+        file: z.enum([SERVER_ENV_FILE, LAKEBED_SERVER_ENV_FILE]),
         names: z.array(executionEnvNameSchema).max(EXECUTION_ENV_MAX_KEYS).default([]),
     })
         .nullable()
         .default(null),
-    sourceConfig: z
-        .object({
-        configFile: z
-            .object({
-            path: z.literal(ZERO_CONFIG_FILE),
-            appName: z.string().nullable().default(null),
-            deployId: z.string().nullable().default(null),
-            name: z.string().nullable().default(null),
-            title: z.string().nullable().default(null),
-        })
-            .nullable()
-            .default(null),
-        deployFile: z
-            .object({
-            path: z.literal(ZERO_DEPLOY_FILE),
-            keys: z.array(z.string()).default([]),
-        })
-            .nullable()
-            .default(null),
-    })
-        .default({ configFile: null, deployFile: null }),
 })
     .strict();
 export const zeroCapsuleArtifactSchema = z
@@ -439,6 +465,7 @@ 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([]),
     })
@@ -451,7 +478,7 @@ export const zeroCapsuleArtifactSchema = z
         .strict(),
     realtime: z
         .object({
-        mode: zeroRealtimeModeSchema,
+        mode: runtimeRealtimeModeSchema,
         mutationEvents: z.boolean().default(true),
     })
         .strict(),
@@ -478,7 +505,7 @@ export const zeroRuntimeFinalizePayloadSchema = z
         .strict(),
     realtime: z
         .object({
-        mode: zeroRealtimeModeSchema,
+        mode: runtimeRealtimeModeSchema,
         centralUrl: zeroRealtimeUrlSchema.nullable().default(null),
         replayUrl: zeroHttpUrlSchema.nullable().default(null),
         castResourceKey: z.string().min(1).max(256).nullable().optional(),
@@ -493,7 +520,7 @@ export const zeroRuntimeFinalizePayloadSchema = z
         .strict(),
     auth: z
         .object({
-        provider: z.literal("wpcom").default("wpcom"),
+        provider: z.literal("gravatar").default("gravatar"),
         signInPath: z.literal(ZERO_RUNTIME_ROUTE_PATHS.authStart).nullable().default(null),
         signInUrl: zeroHttpUrlSchema.nullable().default(null),
         signOutPath: z.literal(ZERO_RUNTIME_ROUTE_PATHS.authSignOut).nullable().default(null),
@@ -502,7 +529,7 @@ export const zeroRuntimeFinalizePayloadSchema = z
     })
         .strict()
         .default({
-        provider: "wpcom",
+        provider: "gravatar",
         signInPath: null,
         signInUrl: null,
         signOutPath: null,
@@ -530,6 +557,7 @@ export const zeroRuntimeConfigSchema = zeroRuntimeFinalizePayloadSchema
 })
     .extend({
     variableValues: z.record(z.string(), z.string()).default({}),
+    databaseUrlSource: z.enum(["application", "provider"]).default("application"),
 })
     .strict();
 export const zeroDeployMetadataSchema = z
@@ -545,6 +573,13 @@ export const zeroDeployMetadataSchema = z
  * 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.
+ *
+ * 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.
  */
 export const zeroAppSchema = z
     .object({
@@ -561,8 +596,17 @@ 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([]),
+    /**
+     * Migrations are operations, not names — `create_table`, `add_column` and
+     * friends — so a count is the honest summary here. The operations
+     * themselves are the database surface's answer (`GET /v1/spaces/{id}/db`).
+     */
+    migrationCount: z.number().int().nonnegative(),
+    /** Digest of the schema the live migration plan settled on, if it ran one. */
+    schemaHash: zeroSha256Schema.nullable(),
     variables: z
         .object({
         source: z.literal("stattic-variables"),
@@ -572,39 +616,6 @@ export const zeroAppSchema = z
     realtime: zeroRuntimePublicRealtimeConfigSchema,
 })
     .strict();
-export const zeroDbInspectResponseSchema = z
-    .object({
-    versionId: z.string().min(1).nullable(),
-    artifactId: z.string().min(1).nullable(),
-    backend: z.literal("wpcloud-mysql").nullable(),
-    migrationMode: z.enum(["safe", "drop", "rename"]).nullable(),
-    schemaHash: zeroSha256Schema.nullable(),
-    tables: z.array(zeroTableSchema).default([]),
-    migrations: z.array(zeroMigrationOperationSchema).default([]),
-})
-    .strict();
-export const zeroDbInspectPublicResponseSchema = dataEnvelope(zeroDbInspectResponseSchema);
-export const zeroDbDumpQuerySchema = z
-    .object({
-    table: zeroNameSchema.optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(25),
-})
-    .strict();
-export const zeroDbDumpTableSchema = z
-    .object({
-    name: zeroNameSchema,
-    rows: z.array(z.record(z.string(), z.unknown())).default([]),
-})
-    .strict();
-export const zeroDbDumpResponseSchema = z
-    .object({
-    versionId: z.string().min(1).nullable(),
-    artifactId: z.string().min(1).nullable(),
-    schemaHash: zeroSha256Schema.nullable(),
-    tables: z.array(zeroDbDumpTableSchema).default([]),
-})
-    .strict();
-export const zeroDbDumpPublicResponseSchema = dataEnvelope(zeroDbDumpResponseSchema);
 // Both products emit the same log shape; `handlerName` carries the mutation
 // name here and the worker handler name on Functions.
 export const zeroLogListQuerySchema = executionLogListQuerySchema;
@@ -618,22 +629,6 @@ export const zeroRealtimeEventIntakeResponseSchema = z
     duplicate: z.boolean().default(false),
 })
     .strict();
-export const zeroRealtimeEventListQuerySchema = z
-    .object({
-    afterEventId: z.string().min(1).optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(50),
-})
-    .strict();
-export const zeroRealtimeEventListResponseSchema = z
-    .object({
-    data: z.array(zeroRealtimeEventSchema),
-    pagination: z
-        .object({
-        nextCursor: z.string().min(1).nullable(),
-    })
-        .strict(),
-})
-    .strict();
 export const zeroLocalDevPlanSchema = z
     .object({
     runtimeKind: z.literal(ZERO_RUNTIME_KIND),
@@ -664,6 +659,7 @@ export function createZeroCapsuleArtifact(input) {
             schema: input.schema ?? {},
             queries: input.queries ?? [],
             mutations: input.mutations ?? [],
+            actions: input.actions ?? [],
             endpoints: input.endpoints ?? [],
             sockets: input.sockets ?? [],
         },
@@ -672,7 +668,7 @@ export function createZeroCapsuleArtifact(input) {
             migrations: [],
         },
         realtime: {
-            mode: input.realtimeMode ?? "stattic-central",
+            mode: input.realtimeMode ?? "central",
             mutationEvents: true,
         },
         limits: {},
@@ -712,7 +708,7 @@ export function createZeroRuntimeInstallProfile(input) {
             blockIncompatibleRollback: true,
         },
         realtime: {
-            production: "stattic-central",
+            production: "central",
             local: "foreground-cli-ws",
         },
     });

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

@@ -12,11 +12,20 @@ export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite
  * here before its route module lands. A repository structural test enforces
  * this.
  */
-export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["billing", "connect", "domains", "drop", "members", "new", "settings"];
+export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["billing", "connect", "domains", "drop", "members", "new", "resume", "settings"];
 export type TeamSlugRouteReservation = (typeof TEAM_SLUG_ROUTE_RESERVATIONS)[number];
 export type SpaceSlugRouteReservation = (typeof SPACE_SLUG_ROUTE_RESERVATIONS)[number];
 export declare const TEAM_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
 export declare const SPACE_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
+/**
+ * The Runtime page's sections. They are search params rather than path
+ * segments, so `runtime` stays a single route (and a single ledger row) and a
+ * space slugged "runtime" keeps its own Runtime page at
+ * `/<team>/runtime/runtime`.
+ */
+export declare const SPACE_RUNTIME_SECTIONS: readonly ["overview", "database", "storage", "logs"];
+export type SpaceRuntimeSection = (typeof SPACE_RUNTIME_SECTIONS)[number];
+export declare const DEFAULT_SPACE_RUNTIME_SECTION: SpaceRuntimeSection;
 export type SpaceSettingsDestination = "access" | "advanced" | "builds" | "integrations" | "integrations/add" | "source-builds";
 export type TeamSettingsDestination = "access" | "audit" | "developer" | "developer/agents" | "developer/environment-variables" | "developer/handoffs" | "developer/webhooks" | "integrations";
 export declare function teamPath(teamSlug: string): string;
@@ -24,6 +33,12 @@ export declare function spacePath(teamSlug: string, spaceSlug: string): string;
 export declare function versionDetailPath(teamSlug: string, spaceSlug: string, versionRef: string): string;
 export declare function buildDetailPath(teamSlug: string, spaceSlug: string, buildId: string): string;
 export declare function spaceDomainsPath(teamSlug: string, spaceSlug: string): string;
+/**
+ * The space's Runtime page. The default section is the bare URL — the route
+ * strips it back out of the address bar — so a link to "overview" and a link to
+ * the page itself are the same link.
+ */
+export declare function spaceRuntimePath(teamSlug: string, spaceSlug: string, section?: SpaceRuntimeSection): string;
 export declare function spaceSettingsPath(teamSlug: string, spaceSlug: string, destination?: SpaceSettingsDestination): string;
 export declare function teamDomainsPath(teamSlug: string): string;
 export declare function teamBillingPath(teamSlug: string): string;

package/dist/dashboard-paths/index.js

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

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

@@ -7,8 +7,8 @@ export declare function renderAgentHandoffDocumentMarkdown(input: {
 }): string;
 /**
  * The browser variant served at `/agent/<documentId>`: the full instructions in
- * the initial response body, zero scripts (nothing may ever read or echo the
- * URL fragment), same bytes for every ID.
+ * the initial response body, zero scripts (nothing may ever inspect or echo a
+ * handoff credential), same bytes for every ID.
  */
 export declare function renderAgentHandoffDocumentHtml(input: {
     mcpEndpoint: string;

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

@@ -1,9 +1,10 @@
 /*
  * The public setup document behind agent handoff links.
  *
- * Handoff links are `https://<dashboard-origin>/agent/<documentId>#<secret>` and
- * the minted prompt tells the agent to fetch that URL. Fragments never reach the
- * server, so this fetch is UNAUTHENTICATED BY DESIGN — which means the response
+ * Private handoff links carry a one-use path token while the durable agent
+ * credential stays encrypted at the broker. The minted prompt tells the agent
+ * to fetch the reconstructed clean document URL instead. This
+ * fetch is UNAUTHENTICATED BY DESIGN — which means the response
  * must never become an existence oracle. The contract here is
  * indistinguishability: every well-formed document ID serves the exact same
  * bytes, with the same status and the same timing, whether or not a handoff with
@@ -21,7 +22,7 @@
  */
 import { buildConnectTargets } from "../agents/connect-targets.js";
 import { BRAND } from "../brand.js";
-import { AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_TARGET_IDS, AGENT_HANDOFF_FETCH_SAFETY, AGENT_HANDOFF_FRAGMENT_HYGIENE, AGENT_HANDOFF_PREAMBLE, AGENT_HANDOFF_PUBLISH_PROSE, agentHandoffConnectSections, agentSetupTextUrl, } from "./agent-setup.js";
+import { AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE, AGENT_HANDOFF_CLI_TARGET_IDS, AGENT_HANDOFF_CREDENTIAL_HYGIENE, AGENT_HANDOFF_FETCH_SAFETY, AGENT_HANDOFF_PREAMBLE, AGENT_HANDOFF_PUBLISH_PROSE, agentHandoffConnectSections, agentSetupTextUrl, } from "./agent-setup.js";
 const DOCUMENT_TITLE = `Set up ${BRAND.productName} from an agent handoff`;
 const DOCUMENT_SCOPE = `This is the public setup document for ${BRAND.productName} agent handoff links (\`/agent/<id>\` on the dashboard origin). Every link serves this same document — fetching it never uses a handoff and reveals nothing about one.`;
 const CONNECT_INTRO = "Set up the client you are running in. Each section stands on its own.";
@@ -49,7 +50,7 @@ export function renderAgentHandoffDocumentMarkdown(input) {
             AGENT_HANDOFF_FETCH_SAFETY,
             `From ${cliTargetNames.join(" or ")} (or any client with a shell): ${AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE}`,
             `From every other client: ${AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE}`,
-            AGENT_HANDOFF_FRAGMENT_HYGIENE,
+            AGENT_HANDOFF_CREDENTIAL_HYGIENE,
         ].join("\n\n"),
         ["## Publish", AGENT_HANDOFF_PUBLISH_PROSE].join("\n\n"),
         `General agent instructions: ${agentSetupTextUrl}`,
@@ -155,8 +156,8 @@ pre code { background: none; padding: 0; font-size: 0.8125rem; }
 `.trim();
 /**
  * The browser variant served at `/agent/<documentId>`: the full instructions in
- * the initial response body, zero scripts (nothing may ever read or echo the
- * URL fragment), same bytes for every ID.
+ * the initial response body, zero scripts (nothing may ever inspect or echo a
+ * handoff credential), same bytes for every ID.
  */
 export function renderAgentHandoffDocumentHtml(input) {
     const markdown = renderAgentHandoffDocumentMarkdown(input);

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

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