@spacefast/common 0.0.24 → 0.2.1

package/dist/docs/agent-arrival.js

@@ -0,0 +1,227 @@
+import { z } from "zod";
+import { ANONYMOUS_AGENT_HANDOFF_TTL_MS, AnonymousAgentHandoffSchema, AnonymousAgentHandoffStatusSchema, } from "../contracts/device-auth.js";
+import { buildAnonymousAgentHandoff, parseAgentHandoffUrl } from "./agent-setup.js";
+/*
+ * Agent arrival, signed out: the whole flow behind "your agent picked the
+ * prompt up", framework-free so the dashboard and the marketing site run one
+ * implementation instead of two that drift.
+ *
+ * The shape of the flow: mint an anonymous handoff, compose the copied prompt
+ * around its one-use URL, then poll that handoff's own fetch state until the
+ * counter leaves zero. The handoff carries no team, no Space, and nothing to
+ * redeem — its only job is to make the fetch observable — so the visitor learns
+ * their agent arrived without signing up first.
+ *
+ * Everything here is a plain function: no React, no query client, no clock but
+ * the one the caller passes. Cadence and reuse are policy, so they live here
+ * with the numbers rather than in whichever UI happens to render the wait.
+ */
+const ANONYMOUS_ARRIVAL_PATH = "/v1/auth/agent-handoffs/anonymous";
+export const AGENT_HANDOFF_REQUEST_FAILED_MESSAGE = "Request failed.";
+export const AGENT_HANDOFF_INVALID_RESPONSE_MESSAGE = "Invalid agent handoff response.";
+/**
+ * The messages that say nothing a person can act on. A UI showing an error
+ * detail line suppresses these, so it never renders "failed: Request failed."
+ */
+export const AGENT_HANDOFF_GENERIC_MESSAGES = new Set([
+    AGENT_HANDOFF_REQUEST_FAILED_MESSAGE,
+    AGENT_HANDOFF_INVALID_RESPONSE_MESSAGE,
+]);
+export class AgentHandoffRequestError extends Error {
+    code;
+    constructor(message, code = null) {
+        super(message);
+        this.name = "AgentHandoffRequestError";
+        this.code = code;
+    }
+}
+/**
+ * The parts of an RFC 9457 problem document that may reach a person. Anything
+ * else the server sent is dropped here rather than carried on an error: a
+ * malformed field costs the reader a detail line, never a leaked credential.
+ */
+const AgentHandoffProblemSchema = z.object({
+    code: z.string().optional().catch(undefined),
+    detail: z.string().optional().catch(undefined),
+});
+// Codes are lowercase snake tokens; anything else (including a secret-shaped
+// blob smuggled into the field) is dropped rather than carried on the error.
+const SAFE_ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/;
+function safeProblemDetail(detail) {
+    if (detail === undefined || !detail.trim())
+        return AGENT_HANDOFF_REQUEST_FAILED_MESSAGE;
+    // Error copy must never echo a handoff URL or a secret-shaped opaque credential.
+    if (/https?:\/\/|[A-Za-z0-9_-]{16,}/i.test(detail))
+        return AGENT_HANDOFF_REQUEST_FAILED_MESSAGE;
+    return detail;
+}
+/** The failure a non-2xx answer becomes, sanitized at the boundary that read it. */
+async function agentHandoffErrorFromResponse(response) {
+    const parsed = AgentHandoffProblemSchema.safeParse(await response.json().catch(() => null));
+    const problem = parsed.success ? parsed.data : {};
+    const code = problem.code !== undefined && SAFE_ERROR_CODE.test(problem.code) ? problem.code : null;
+    return new AgentHandoffRequestError(safeProblemDetail(problem.detail), code);
+}
+function invalidResponse() {
+    return new AgentHandoffRequestError(AGENT_HANDOFF_INVALID_RESPONSE_MESSAGE);
+}
+/*
+ * The success envelope, parsed as one shape. `{ data }` is the API's contract
+ * and the payload schema is the handoff's, so a response that is neither never
+ * reaches a caller as a half-parsed object.
+ */
+const MintEnvelopeSchema = z.object({ data: AnonymousAgentHandoffSchema });
+const StatusEnvelopeSchema = z.object({ data: AnonymousAgentHandoffStatusSchema });
+function endpoint(config, path) {
+    return `${config.apiOrigin.replace(/\/+$/, "")}${path}`;
+}
+function transport(config) {
+    return config.fetch ?? globalThis.fetch;
+}
+function clock(config) {
+    return config.now ? config.now() : Date.now();
+}
+/**
+ * Mints the signed-out handoff a copied prompt carries.
+ *
+ * The anonymous surface is anonymous by contract, so this deliberately sends no
+ * credentials: it works signed out, and a mint that carried a session would
+ * answer differently for gated accounts.
+ */
+export async function mintAnonymousArrival(config) {
+    const response = await transport(config)(endpoint(config, ANONYMOUS_ARRIVAL_PATH), {
+        method: "POST",
+        credentials: "omit",
+        headers: { accept: "application/json" },
+    });
+    if (!response.ok)
+        throw await agentHandoffErrorFromResponse(response);
+    const parsed = MintEnvelopeSchema.safeParse(await response.json().catch(() => null));
+    if (!parsed.success)
+        throw invalidResponse();
+    const data = parsed.data.data;
+    let handoffUrl = null;
+    let secret = null;
+    for (const origin of config.allowedOrigins ?? [config.apiOrigin]) {
+        try {
+            ({ handoffUrl, secret } = parseAgentHandoffUrl(data.url, origin));
+            break;
+        }
+        catch {
+            // Try the next explicitly allowed origin.
+        }
+    }
+    // Sanitization boundary: the ledger id is rendered and polled on, so it must
+    // be provably free of the bearer whatever the server fed us.
+    if (handoffUrl === null || secret === null || data.id.includes(secret)) {
+        throw invalidResponse();
+    }
+    const url = handoffUrl;
+    const bearer = secret;
+    return {
+        id: data.id,
+        expiresAt: Date.parse(data.expiresAt),
+        promptFor: (context) => {
+            // The caller's text is authored before the mint, so it can only contain
+            // the bearer if something upstream is already broken.
+            if (context.includes(bearer))
+                throw invalidResponse();
+            return buildAnonymousAgentHandoff({
+                expectedOrigin: new URL(url).origin,
+                url,
+                context,
+            }).prompt;
+        },
+    };
+}
+/** Reads one anonymous handoff's fetch state by its non-secret ledger id. */
+export async function readAnonymousArrivalStatus(id, config) {
+    const path = `${ANONYMOUS_ARRIVAL_PATH}/${encodeURIComponent(id)}`;
+    const response = await transport(config)(endpoint(config, path), {
+        method: "GET",
+        credentials: "omit",
+        headers: { accept: "application/json" },
+    });
+    if (!response.ok)
+        throw await agentHandoffErrorFromResponse(response);
+    const parsed = StatusEnvelopeSchema.safeParse(await response.json().catch(() => null));
+    if (!parsed.success)
+        throw invalidResponse();
+    return parsed.data.data;
+}
+/*
+ * Cadence, owned in one place with its numbers.
+ *
+ * The answer being waited on is one counter that leaves zero exactly once, and
+ * it changes from outside this browser, so polling is the whole mechanism.
+ * Eager while an agent is plausibly still landing, relaxed for the rest of the
+ * handoff's life, stopped once nothing can change.
+ */
+export const AGENT_ARRIVAL_EAGER_POLL_MS = 2_000;
+export const AGENT_ARRIVAL_EAGER_WINDOW_MS = 2 * 60_000;
+export const AGENT_ARRIVAL_RELAXED_POLL_MS = 10_000;
+/**
+ * The handoff's own TTL is the clock: with no `since` to carry, "how much
+ * runway is left" says how long ago it was minted.
+ */
+export const AGENT_ARRIVAL_RELAXED_AFTER_MS = ANONYMOUS_AGENT_HANDOFF_TTL_MS - AGENT_ARRIVAL_EAGER_WINDOW_MS;
+/**
+ * One live handoff per visit is reused while it still has this much runway.
+ * Every copy gesture minting its own would spend rows against the caller's
+ * budget for a signal that only has to flip once.
+ */
+export const AGENT_ARRIVAL_REFRESH_RUNWAY_MS = 2 * 60_000;
+/** How long to wait before the next status read, or `false` to stop polling. */
+export function anonymousArrivalPollDelayMs(status, now = Date.now()) {
+    if (status === undefined)
+        return AGENT_ARRIVAL_EAGER_POLL_MS;
+    if (hasAgentArrived(status))
+        return false;
+    const remaining = Date.parse(status.expiresAt) - now;
+    if (remaining <= 0)
+        return false;
+    return remaining > AGENT_ARRIVAL_RELAXED_AFTER_MS
+        ? AGENT_ARRIVAL_EAGER_POLL_MS
+        : AGENT_ARRIVAL_RELAXED_POLL_MS;
+}
+/** The arrival itself: one fetch of the private URL is the whole signal. */
+export function hasAgentArrived(status) {
+    return (status?.fetchCount ?? 0) > 0;
+}
+/**
+ * One visit's arrival flow. Hold one of these for as long as the visitor is on
+ * the surface: the reuse discipline lives in the instance, so re-copies keep
+ * the same handoff instead of piling fresh rows behind one signal.
+ */
+export function createAnonymousArrival(config) {
+    let inflight = null;
+    const fresh = () => {
+        const pending = mintAnonymousArrival(config);
+        inflight = pending;
+        // A mint that failed is not the visit's handoff; the next copy mints anew.
+        void pending.catch(() => {
+            if (inflight === pending)
+                inflight = null;
+        });
+        return pending;
+    };
+    const ensureMinted = () => {
+        const cached = inflight;
+        if (!cached)
+            return fresh();
+        return cached.then((minted) => minted.expiresAt - clock(config) > AGENT_ARRIVAL_REFRESH_RUNWAY_MS ? minted : fresh());
+    };
+    return {
+        ensureMinted,
+        promptFor: (context) => ensureMinted().then((minted) => ({
+            id: minted.id,
+            // Composed from THIS copy's context, never the one the handoff was
+            // first minted for: one handoff spans the visit, the task does not.
+            prompt: minted.promptFor(context),
+            expiresAt: minted.expiresAt,
+        })),
+        readStatus: (id) => readAnonymousArrivalStatus(id, config),
+        nextPollDelayMs: (status) => anonymousArrivalPollDelayMs(status, clock(config)),
+        hasArrived: hasAgentArrived,
+    };
+}

package/dist/docs/agent-output-policy.d.ts

@@ -0,0 +1,6 @@
+export type AgentOutput = {
+    readonly source: string;
+    readonly text: string;
+};
+/** Reject commercial plan promotion in text that an agent can receive. */
+export declare function assertNoCommercialUpsell(outputs: readonly AgentOutput[]): void;

package/dist/docs/agent-output-policy.js

@@ -0,0 +1,22 @@
+const COMMERCIAL_UPSELL_PATTERNS = [
+    /\bpricing\b/i,
+    /\bpaid plans?\b/i,
+    /\bupgrade (?:your|the|this) (?:account|plan|subscription)\b/i,
+    /\bupgrade to (?:a )?(?:paid|premium|pro)\b/i,
+    /\bsubscribe now\b/i,
+    /\bstart (?:a )?(?:free )?trial\b/i,
+    /\bbuy now\b/i,
+    /\bcontact sales\b/i,
+    /\bcheckout\b/i,
+];
+/** Reject commercial plan promotion in text that an agent can receive. */
+export function assertNoCommercialUpsell(outputs) {
+    for (const output of outputs) {
+        for (const pattern of COMMERCIAL_UPSELL_PATTERNS) {
+            const match = pattern.exec(output.text);
+            if (match) {
+                throw new Error(`${output.source} contains commercial upsell text: ${match[0]}`);
+            }
+        }
+    }
+}

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

@@ -1,24 +1,21 @@
 export declare const ARCHIVE_SECRET_GLOBS: readonly [".env*", ".npmrc", ".netrc", "*/.git/*", "*/.spacefast/*", "*/.ssh/*", "*/.aws/*", "*/.kube/*", "*/.docker/*", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*"];
-/**
- * The credential rules every surface must repeat. Treat tokens as secrets, keep
- * them out of logs and transcripts, and never echo them back.
- */
+/** The credential rules every surface must repeat. */
 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;
-/** Curl/API skill lane: docs URLs only — no MCP or CLI tools required. */
+/** 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.
+ * The CHECK verb: look for an existing space before creating one, so a returning
+ * agent publishes a new version instead of a duplicate anonymous space.
  */
 export declare const CHECK_BEFORE_PUBLISH_PROSE: string;
 export declare const CHECK_BEFORE_PUBLISH_API_PROSE: string;
@@ -37,6 +34,7 @@ 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.
  */
+export declare const PUSH_TO_DEPLOY_PROSE: string;
 export declare const UPDATE_SPACE_PROSE: string;
 /**
  * The CLAIM / CONTINUE verb: show the claim link, and after the user claims,
@@ -45,7 +43,7 @@ export declare const UPDATE_SPACE_PROSE: string;
 export declare const CONTINUE_AFTER_CLAIM_PROSE: string;
 /**
  * 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
+ * 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;
@@ -53,19 +51,15 @@ export declare const PUBLISH_SEQUENCE_PROSE: string;
  * What the JSON publish receipt contains and how to read it. The receipt is the
  * source of truth; never invent a separate success signal.
  */
-export declare const RECEIPT_SHAPE_PROSE: string;
+export declare const RECEIPT_CONTRACT_PROSE: string;
 /**
  * The large/cloud-agent path. This keeps file bytes out of MCP JSON and chat
  * transcripts while still giving agents a way to upload arbitrary artifacts.
  */
 export declare const SIGNED_UPLOAD_PROSE: string;
 /**
- * Named fragments for the skill-template generator. The templates carry
- * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
- * `{{prose.receiptShape}}`, `{{prose.signedUpload}}`,
- * `{{prose.checkBeforePublish}}`, `{{prose.saveState}}`,
- * `{{prose.updateSpace}}`, and `{{prose.continueAfterClaim}}` placeholders;
- * generate-skill.mjs substitutes these.
+ * Named fragments for the skill-template generator: the templates carry
+ * `{{prose.<key>}}` placeholders and generate-skill.mjs substitutes these.
  */
 export declare const AGENT_PROSE: {
     readonly positioning: string;
@@ -73,7 +67,7 @@ export declare const AGENT_PROSE: {
     readonly explainToUser: string;
     readonly failureConduct: string;
     readonly publishSequence: string;
-    readonly receiptShape: string;
+    readonly receiptContract: string;
     readonly signedUpload: string;
     readonly checkBeforePublish: string;
     readonly checkBeforePublishApi: string;
@@ -83,6 +77,7 @@ export declare const AGENT_PROSE: {
     readonly saveStateApi: string;
     readonly saveStateMcp: string;
     readonly updateSpace: string;
+    readonly pushToDeploy: string;
     readonly continueAfterClaim: string;
     readonly lanePicker: string;
     readonly howToResearch: string;
@@ -91,4 +86,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

@@ -1,25 +1,22 @@
+import { SPACEFAST_POSITIONING } from "../brand.js";
 import { serviceOrigin } from "../config/domains.js";
-// Single home for the agent-facing prose that was triplicated across the three
-// surfaces that teach an agent how to publish:
+// Single home for the agent-facing prose the three publish-teaching surfaces
+// share:
 //
 //   - 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
-// truth. They are plain Markdown strings (no surface-specific framing) so any
-// surface can splice them in: the skill template substitutes the `{{prose.*}}`
-// placeholders during generation, and the TS surfaces import the strings.
-//
-// Keep these grounded in the real API receipt and the real /v1/publish flow. If
-// the receipt shape or secret handling changes, change it here once.
+// These are plain Markdown strings with no surface-specific framing: the skill
+// template substitutes the `{{prose.*}}` placeholders during generation, and the
+// TS surfaces import them. Keep them grounded in the real API receipt and the
+// real /v1/publish flow; if either changes, change it here once.
 const API_ORIGIN = serviceOrigin("api", "prod");
 const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
 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.
+// Secret/credential patterns excluded from a publish archive. The `find`
+// preflight and the `zip -x` exclusions both derive from this list, so the
+// no-install and skill copies cannot disagree.
 export const ARCHIVE_SECRET_GLOBS = [
     ".env*",
     ".npmrc",
@@ -58,10 +55,7 @@ function findExpr(globs) {
         .map((glob) => (glob.includes("/") ? `-path "${glob}"` : `-name "${glob}"`))
         .join(" -o ");
 }
-/**
- * The credential rules every surface must repeat. Treat tokens as secrets, keep
- * them out of logs and transcripts, and never echo them back.
- */
+/** The credential rules every surface must repeat. */
 export const SECRET_RULES_PROSE = [
     "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",
@@ -70,14 +64,17 @@ export const SECRET_RULES_PROSE = [
     "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. Spaces serve",
-    "static files; app code runs only through a declared Zero or Functions runtime.",
+    // What the product is, before any claim about it. One constant, shared with
+    // the dashboard's copied page context (see docs/page-context-prompt.ts).
+    SPACEFAST_POSITIONING,
+    "",
+    "Spacefast is the best place to share AI artifacts.",
+    "Spaces serve files directly; app code runs only through a declared Zero or Functions runtime.",
     "",
     "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",
+    "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");
@@ -87,22 +84,26 @@ 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",
-    "filesystem means hosted MCP; one-off publish means curl; CI means an agent account. After",
-    "success, recommend the best next-time setup for the user's client.",
+    "Pick the lane by environment: a one-off publish means curl; a git checkout means the push.new",
+    "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",
+    "user's client.",
 ].join("\n");
 export const HOW_TO_RESEARCH_PROSE = [
     "For an error, fetch the problem document's `type` URL. For capability questions, search the OpenAPI catalog with `execute` or append",
     "`.md` to website docs URLs. For contracts, read `publish-spec.json` or OpenAPI. Never guess",
     "limits: publish, then read diagnostics.",
 ].join("\n");
-/** Curl/API skill lane: docs URLs only — no MCP or CLI tools required. */
+/** Curl/API skill lane: docs URLs only, no MCP or CLI tools required. */
 export const HOW_TO_RESEARCH_API_PROSE = [
     "For an error, fetch the problem document's `type` URL. For capability questions, append `.md` to website docs",
     "URLs (for example `https://spacefast.com/docs/agents.md`) or read",
@@ -111,8 +112,9 @@ export const HOW_TO_RESEARCH_API_PROSE = [
 ].join("\n");
 /** MCP plugin skill lane: prefer skills for workflows and execute for the OpenAPI catalog. */
 export const HOW_TO_RESEARCH_MCP_PROSE = [
-    "For an error, fetch the problem document's `type` URL when present. For workflows, call the `skills` tool",
-    "(list/search, then read by exact name). For capability questions, use `execute` with `tools.search`.",
+    "For 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 contracts, read `publish-spec.json` or OpenAPI via docs. Never guess limits: publish,",
     "then inspect status or diagnostics through `execute`.",
 ].join("\n");
@@ -127,9 +129,8 @@ export const ENV_NOTES_API_PROSE = [
     "https://spacefast.com/docs/agents.",
 ].join("\n");
 /**
- * The CHECK verb: before ever creating a space, look for the one the project
- * already has. This is what keeps a returning agent from pushing a duplicate
- * anonymous space instead of a new version.
+ * The CHECK verb: look for an existing space before creating one, so a returning
+ * agent publishes a new version instead of a duplicate anonymous space.
  */
 export const CHECK_BEFORE_PUBLISH_PROSE = [
     "Before creating a space, check whether this project already has one:",
@@ -141,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:",
@@ -157,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:",
@@ -168,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
@@ -219,6 +220,34 @@ export const SAVE_STATE_MCP_PROSE = [
  * The UPDATE verb: a new version to the SAME space. Never re-run the
  * first-publish recipe when saved state exists.
  */
+/*
+ * Push to deploy. Written for an agent that is already in a checkout, where a
+ * push is fewer moves than an upload — and where the receipt comes back in the
+ * push output, so there is no second call to learn the URL.
+ *
+ * The GitHub note is not an aside: a space bound to a GitHub repository refuses
+ * direct pushes, and an agent that does not know that reads the refusal as a
+ * broken remote instead of as the answer it is.
+ */
+export const PUSH_TO_DEPLOY_PROSE = [
+    "A space's git remote is a real remote, and pushing to it publishes. Every publish receipt",
+    "and the Space resource carry `git.remoteUrl`; authenticate as HTTP Basic user `t` with the",
+    "space key or an API key as the password. The same key you already have works — publishing",
+    "and pushing are one credential, not two.",
+    "",
+    "```bash",
+    "git remote add spacefast https://t:<key>@push.new/<space-slug>.git",
+    "git push spacefast main",
+    "```",
+    "",
+    "The push output is the receipt: it reports the live URL, the immutable version URL, and —",
+    "for an anonymous space — the claim link and its expiry, as `remote:` lines. Report those to",
+    "the user the same way you would report a publish receipt. A deploy that outruns the push",
+    "prints a status URL instead and finishes on its own; the push still exits 0.",
+    "",
+    "If `git.managedBy` is `github`, this space deploys from `git.repository` and a direct push is",
+    "refused. Push to that GitHub repository instead, or tell the user to disconnect GitHub first.",
+].join("\n");
 export const UPDATE_SPACE_PROSE = [
     "To publish a new version of an existing space, send the same `spaceId` with bearer auth —",
     "never re-run the first-publish recipe when saved state exists:",
@@ -255,7 +284,7 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "Save `data.credential.accessToken` into `.spacefast/state.json` (replace the `claimToken`",
     'field with `"accessToken"`), then retry the publish with the new bearer. The exchange works',
     "exactly once; if it returns `continuation_used` or `continuation_unavailable`, ask the user",
-    "to create an API key in the dashboard (Account → API keys).",
+    "to create an API key in the dashboard (team → Agents → API keys).",
 ].join("\n");
 const LEXICAL_PUBLISH_PATH_PREFLIGHT = [
     'case "$publish_target" in /*) check_path="$publish_target" ;; *) check_path="$PWD/$publish_target" ;; esac',
@@ -321,7 +350,7 @@ const SECURE_ARCHIVE_RECIPE = [
 ];
 /**
  * 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
+ * secret-preflighted zip for a folder. This is the load-bearing rung 0. An
  * agent that stops here must still succeed.
  */
 export const PUBLISH_SEQUENCE_PROSE = [
@@ -340,12 +369,8 @@ 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}"',
     '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",
     "```",
@@ -379,7 +404,7 @@ export const PUBLISH_SEQUENCE_PROSE = [
  * What the JSON publish receipt contains and how to read it. The receipt is the
  * source of truth; never invent a separate success signal.
  */
-export const RECEIPT_SHAPE_PROSE = [
+export const RECEIPT_CONTRACT_PROSE = [
     "The JSON receipt is the source of truth:",
     "",
     "- `data.space.liveUrl` — the live URL.",
@@ -425,18 +450,14 @@ export const SIGNED_UPLOAD_PROSE = [
     "For each `data.upload.targets[]`, send `target.method` to `target.url` with `target.headers`.",
     'If `target.body.kind` is `url`, send JSON `{ "url": target.body.url }`; otherwise send the',
     "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`.",
+    "If the session expires or only a page of files is returned, follow `data.links.refresh`.",
     "",
     "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
- * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
- * `{{prose.receiptShape}}`, `{{prose.signedUpload}}`,
- * `{{prose.checkBeforePublish}}`, `{{prose.saveState}}`,
- * `{{prose.updateSpace}}`, and `{{prose.continueAfterClaim}}` placeholders;
- * generate-skill.mjs substitutes these.
+ * Named fragments for the skill-template generator: the templates carry
+ * `{{prose.<key>}}` placeholders and generate-skill.mjs substitutes these.
  */
 export const AGENT_PROSE = {
     positioning: POSITIONING_PROSE,
@@ -444,7 +465,7 @@ export const AGENT_PROSE = {
     explainToUser: EXPLAIN_TO_USER_PROSE,
     failureConduct: FAILURE_CONDUCT_PROSE,
     publishSequence: PUBLISH_SEQUENCE_PROSE,
-    receiptShape: RECEIPT_SHAPE_PROSE,
+    receiptContract: RECEIPT_CONTRACT_PROSE,
     signedUpload: SIGNED_UPLOAD_PROSE,
     checkBeforePublish: CHECK_BEFORE_PUBLISH_PROSE,
     checkBeforePublishApi: CHECK_BEFORE_PUBLISH_API_PROSE,
@@ -454,6 +475,7 @@ export const AGENT_PROSE = {
     saveStateApi: SAVE_STATE_API_PROSE,
     saveStateMcp: SAVE_STATE_MCP_PROSE,
     updateSpace: UPDATE_SPACE_PROSE,
+    pushToDeploy: PUSH_TO_DEPLOY_PROSE,
     continueAfterClaim: CONTINUE_AFTER_CLAIM_PROSE,
     lanePicker: LANE_PICKER_PROSE,
     howToResearch: HOW_TO_RESEARCH_PROSE,