@spacefast/common 0.0.3 → 0.0.6

package/dist/contracts/zero.d.ts

@@ -183,9 +183,9 @@ export type ZeroMigrationOperation = z.infer<typeof zeroMigrationOperationSchema
 export declare const zeroMigrationPlanSchema: z.ZodObject<{
     format: z.ZodLiteral<"stattic.zero.migrations.v1">;
     mode: z.ZodDefault<z.ZodEnum<{
+        safe: "safe";
         drop: "drop";
         rename: "rename";
-        safe: "safe";
     }>>;
     schemaHash: z.ZodString;
     operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -245,8 +245,8 @@ export declare const zeroRuntimePublicRealtimeModeSchema: z.ZodEnum<{
     "local-websocket": "local-websocket";
 }>;
 export declare const zeroInspectPolicySchema: z.ZodEnum<{
-    private: "private";
     public: "public";
+    private: "private";
 }>;
 export declare const zeroRuntimePublicAuthConfigSchema: z.ZodObject<{
     provider: z.ZodDefault<z.ZodLiteral<"wpcom">>;
@@ -256,7 +256,6 @@ export declare const zeroRuntimePublicAuthConfigSchema: z.ZodObject<{
     signOutUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     returnToParam: z.ZodDefault<z.ZodString>;
 }, z.core.$strict>;
-export type ZeroRuntimePublicAuthConfig = z.infer<typeof zeroRuntimePublicAuthConfigSchema>;
 export declare const zeroRuntimePublicRealtimeConfigSchema: z.ZodObject<{
     mode: z.ZodEnum<{
         "stattic-central": "stattic-central";
@@ -275,7 +274,6 @@ export declare const zeroRuntimePublicRealtimeConfigSchema: z.ZodObject<{
     spaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     versionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
-export type ZeroRuntimePublicRealtimeConfig = z.infer<typeof zeroRuntimePublicRealtimeConfigSchema>;
 export declare const zeroRuntimeClientConfigSchema: z.ZodObject<{
     runtimeKind: z.ZodLiteral<"zero">;
     basePath: z.ZodOptional<z.ZodString>;
@@ -480,8 +478,8 @@ export declare const zeroCapsuleArtifactSchema: z.ZodObject<{
     }, z.core.$strict>;
     limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     futureCapabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-        blob: "blob";
         ai: "ai";
+        blob: "blob";
         "generalized-js": "generalized-js";
     }>>>;
     sourceManifest: z.ZodObject<{
@@ -641,8 +639,8 @@ export declare const zeroRuntimeFinalizePayloadSchema: z.ZodObject<{
         }, z.core.$strict>;
         limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         futureCapabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            blob: "blob";
             ai: "ai";
+            blob: "blob";
             "generalized-js": "generalized-js";
         }>>>;
         sourceManifest: z.ZodObject<{
@@ -705,9 +703,9 @@ export declare const zeroRuntimeFinalizePayloadSchema: z.ZodObject<{
     migrations: z.ZodDefault<z.ZodNullable<z.ZodObject<{
         format: z.ZodLiteral<"stattic.zero.migrations.v1">;
         mode: z.ZodDefault<z.ZodEnum<{
+            safe: "safe";
             drop: "drop";
             rename: "rename";
-            safe: "safe";
         }>>;
         schemaHash: z.ZodString;
         operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -782,8 +780,8 @@ export declare const zeroRuntimeFinalizePayloadSchema: z.ZodObject<{
     }, z.core.$strict>>;
     inspect: z.ZodDefault<z.ZodObject<{
         policy: z.ZodDefault<z.ZodEnum<{
-            private: "private";
             public: "public";
+            private: "private";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -916,8 +914,8 @@ export declare const zeroDeployMetadataSchema: z.ZodObject<{
             }, z.core.$strict>;
             limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             futureCapabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-                blob: "blob";
                 ai: "ai";
+                blob: "blob";
                 "generalized-js": "generalized-js";
             }>>>;
             sourceManifest: z.ZodObject<{
@@ -980,9 +978,9 @@ export declare const zeroDeployMetadataSchema: z.ZodObject<{
         migrations: z.ZodDefault<z.ZodNullable<z.ZodObject<{
             format: z.ZodLiteral<"stattic.zero.migrations.v1">;
             mode: z.ZodDefault<z.ZodEnum<{
+                safe: "safe";
                 drop: "drop";
                 rename: "rename";
-                safe: "safe";
             }>>;
             schemaHash: z.ZodString;
             operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -1057,8 +1055,8 @@ export declare const zeroDeployMetadataSchema: z.ZodObject<{
         }, z.core.$strict>>;
         inspect: z.ZodDefault<z.ZodObject<{
             policy: z.ZodDefault<z.ZodEnum<{
-                private: "private";
                 public: "public";
+                private: "private";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -1073,8 +1071,8 @@ export declare const zeroInspectResponseSchema: z.ZodObject<{
         serverRuntime: z.ZodLiteral<"quickjs-rust">;
         inspect: z.ZodObject<{
             policy: z.ZodEnum<{
-                private: "private";
                 public: "public";
+                private: "private";
             }>;
         }, z.core.$strict>;
         install: z.ZodObject<{
@@ -1156,8 +1154,8 @@ export declare const zeroInspectPublicResponseSchema: z.ZodObject<{
             serverRuntime: z.ZodLiteral<"quickjs-rust">;
             inspect: z.ZodObject<{
                 policy: z.ZodEnum<{
-                    private: "private";
                     public: "public";
+                    private: "private";
                 }>;
             }, z.core.$strict>;
             install: z.ZodObject<{
@@ -1234,9 +1232,9 @@ export declare const zeroDbInspectResponseSchema: z.ZodObject<{
     artifactId: z.ZodNullable<z.ZodString>;
     backend: z.ZodNullable<z.ZodLiteral<"wpcloud-mysql">>;
     migrationMode: z.ZodNullable<z.ZodEnum<{
+        safe: "safe";
         drop: "drop";
         rename: "rename";
-        safe: "safe";
     }>>;
     schemaHash: z.ZodNullable<z.ZodString>;
     tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1304,9 +1302,9 @@ export declare const zeroDbInspectPublicResponseSchema: z.ZodObject<{
         artifactId: z.ZodNullable<z.ZodString>;
         backend: z.ZodNullable<z.ZodLiteral<"wpcloud-mysql">>;
         migrationMode: z.ZodNullable<z.ZodEnum<{
+            safe: "safe";
             drop: "drop";
             rename: "rename";
-            safe: "safe";
         }>>;
         schemaHash: z.ZodNullable<z.ZodString>;
         tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1372,7 +1370,6 @@ export declare const zeroDbDumpQuerySchema: z.ZodObject<{
     table: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
-export type ZeroDbDumpQuery = z.infer<typeof zeroDbDumpQuerySchema>;
 export declare const zeroDbDumpTableSchema: z.ZodObject<{
     name: z.ZodString;
     rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -1447,12 +1444,10 @@ export declare const zeroRealtimeEventIntakeResponseSchema: z.ZodObject<{
     delivered: z.ZodDefault<z.ZodNumber>;
     duplicate: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
-export type ZeroRealtimeEventIntakeResponse = z.infer<typeof zeroRealtimeEventIntakeResponseSchema>;
 export declare const zeroRealtimeEventListQuerySchema: z.ZodObject<{
     afterEventId: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
-export type ZeroRealtimeEventListQuery = z.infer<typeof zeroRealtimeEventListQuerySchema>;
 export declare const zeroRealtimeEventListResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
         eventId: z.ZodString;

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

@@ -1,9 +1,37 @@
-export declare const ARCHIVE_SECRET_GLOBS: readonly [".env*", ".npmrc", ".netrc", "*/.git/*", "*/.stattic/*", "*/.ssh/*", "*/.aws/*", "*/.kube/*", "*/.docker/*", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*"];
+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.
  */
 export declare const SECRET_RULES_PROSE: string;
+export declare const POSITIONING_PROSE: string;
+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;
+export declare const ENV_NOTES_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;
+/**
+ * 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 SAVE_STATE_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 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.
+ */
+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
@@ -21,15 +49,27 @@ export declare const RECEIPT_SHAPE_PROSE: string;
  */
 export declare const SIGNED_UPLOAD_PROSE: string;
 /**
- * Named fragments for the skill-template generator. The template carries
+ * Named fragments for the skill-template generator. The templates carry
  * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
- * `{{prose.receiptShape}}`, and `{{prose.signedUpload}}` placeholders;
+ * `{{prose.receiptShape}}`, `{{prose.signedUpload}}`,
+ * `{{prose.checkBeforePublish}}`, `{{prose.saveState}}`,
+ * `{{prose.updateSpace}}`, and `{{prose.continueAfterClaim}}` placeholders;
  * generate-skill.mjs substitutes these.
  */
 export declare const AGENT_PROSE: {
+    readonly positioning: string;
     readonly secretRules: string;
+    readonly explainToUser: string;
+    readonly failureConduct: string;
     readonly publishSequence: string;
     readonly receiptShape: string;
     readonly signedUpload: string;
+    readonly checkBeforePublish: string;
+    readonly saveState: string;
+    readonly updateSpace: string;
+    readonly continueAfterClaim: string;
+    readonly lanePicker: string;
+    readonly howToResearch: string;
+    readonly envNotes: string;
 };
 export type AgentProseKey = keyof typeof AGENT_PROSE;

package/dist/docs/agent-prose.js

@@ -16,6 +16,7 @@ import { BRAND } from "../brand.js";
 // the receipt shape or secret handling changes, change it here once.
 const API_ORIGIN = BRAND.apiOrigin;
 const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
+const EXCHANGE_ENDPOINT = `${API_ORIGIN}/v1/anonymous-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.
@@ -24,7 +25,7 @@ export const ARCHIVE_SECRET_GLOBS = [
     ".npmrc",
     ".netrc",
     "*/.git/*",
-    "*/.stattic/*",
+    "*/.spacefast/*",
     "*/.ssh/*",
     "*/.aws/*",
     "*/.kube/*",
@@ -43,9 +44,18 @@ function findExpr(globs) {
         .join(" -o ");
 }
 function zipExcludeExpr(globs) {
-    // zip uses relative patterns: a leading "*/" is just a directory match, so
-    // collapse it to the directory glob the archive root sees.
-    return globs.map((glob) => `"${glob.replace(/^\*\//, "")}"`).join(" ");
+    // zip -x patterns need both the archive-root form and an any-depth form:
+    // ".spacefast/*" excludes only at the root, while "*/.spacefast/*" catches
+    // nested copies.
+    return globs
+        .flatMap((glob) => {
+        if (glob.startsWith("*/")) {
+            return [glob.slice(2), glob];
+        }
+        return [glob, `*/${glob}`];
+    })
+        .map((glob) => `"${glob}"`)
+        .join(" ");
 }
 /**
  * The credential rules every surface must repeat. Treat tokens as secrets, keep
@@ -58,6 +68,121 @@ export const SECRET_RULES_PROSE = [
     "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.",
+    "",
+    "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.",
+].join("\n");
+export const EXPLAIN_TO_USER_PROSE = [
+    "Relay `data.shareBlurb` verbatim when present. State anonymous expiry in user terms:",
+    "the space expires unless claimed by `data.claim.expiresAt`. After claim, the agent key is",
+    "named and revocable in the dashboard.",
+].join("\n");
+export const FAILURE_CONDUCT_PROSE = [
+    "On failure, surface `error.code`, `error.docsUrl`, and `error.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`.",
+].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.",
+].join("\n");
+export const HOW_TO_RESEARCH_PROSE = [
+    "For an error, fetch `error.docsUrl`. For capability questions, use `search_docs` or append",
+    "`.md` to website docs URLs. For contracts, read `publish-spec.json` or OpenAPI. Never guess",
+    "limits: publish, then read diagnostics.",
+].join("\n");
+export const ENV_NOTES_PROSE = [
+    "claude.ai: allow `api.spacefast.com` in egress settings. Codex sandbox: escalate only the",
+    "network call. Terminal agents: use the CLI when filesystem access matters.",
+].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.
+ */
+export const CHECK_BEFORE_PUBLISH_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.",
+    "- Look for a publish receipt earlier in this conversation.",
+    "- When authenticated, list existing spaces (`sf spaces list`, or the `spaces_list` MCP tool).",
+    "",
+    "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.",
+].join("\n");
+/**
+ * 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 const SAVE_STATE_PROSE = [
+    "After the first publish, persist the space id and credential so every later publish updates",
+    "the same space instead of creating a new one. The CLI and On-Device MCP do this automatically",
+    "in `.spacefast/`; when publishing with curl, write the files yourself from the receipt:",
+    "",
+    "```bash",
+    "mkdir -p .spacefast",
+    "# non-secret, committable:",
+    `printf '{"space":"<spc_id>"}' > .spacefast/space.json`,
+    "# secret — never publish, never print:",
+    `printf '{"spaceId":"<spc_id>","claimToken":"<token>","apiUrl":"${API_ORIGIN}"}' > .spacefast/state.json`,
+    "grep -qx '.spacefast/state.json' .gitignore 2>/dev/null || echo '.spacefast/state.json' >> .gitignore",
+    "```",
+    "",
+    "`<spc_id>` is `data.space.id` and `<token>` is `data.claim.token` from the receipt. Keep",
+    "`.spacefast/state.json` out of publish archives, commits, logs, and chat.",
+].join("\n");
+/**
+ * The UPDATE verb: a new version to the SAME space. Never re-run the
+ * first-publish recipe when saved state exists.
+ */
+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:",
+    "",
+    "```bash",
+    'curl -sS -H "Authorization: Bearer <claim-token-or-access-token>" \\',
+    "  -F '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.",
+].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.
+ */
+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',
+    "for a publish failure before continuing.",
+    "After the user claims the space in the browser, the saved claim token 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 -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
+    `  ${EXCHANGE_ENDPOINT}`,
+    "```",
+    "",
+    'It returns `{ "data": { "space": {...}, "credential": { "accessToken": "...", "label": "..." } } }`.',
+    "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 mint an access token in the dashboard (Account → Access tokens).",
+].join("\n");
 /**
  * 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
@@ -91,16 +216,22 @@ export const RECEIPT_SHAPE_PROSE = [
     "The JSON receipt is the source of truth:",
     "",
     "- `data.space.liveUrl` — the live URL.",
-    "- `data.version.immutableUrl` — the permanent, frozen version URL when available; share it for reviews.",
+    "- `data.version.immutableUrl` — the permanent, frozen version URL; share it for reviews.",
+    "  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`.",
     "- `data.shareBlurb` — a paste-ready one-liner with the URL and claim nudge; relay it verbatim when present.",
     "- `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;",
     "  always show the user the claim link and the deadline so the space becomes theirs.",
-    "- `data.claim.token` — a secret capability. Save it only when needed to update the space later, send it as",
-    "  `Authorization: Bearer <claim-token>` with the same `spaceId`, and never print it back to the user.",
-    "- `data.links.inspect`, `resume`, `finalize`, and `promote` — follow-up API paths.",
+    "- `data.claim.token` — a secret capability. For anonymous spaces, use it as",
+    "  `Authorization: Bearer <claim-token>` 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.`,
+    "  Never print it back to the user.",
+    "- `data.links.status`, `resume`, `finalize`, and `promote` — follow-up API paths.",
     "- `error.code`, `error.docsUrl`, and `error.hint` — stable error code plus exact recovery docs and a next step.",
     "",
     "If no files changed, the API may omit `upload`; report the receipt and diagnostics rather than",
@@ -140,14 +271,26 @@ export const SIGNED_UPLOAD_PROSE = [
     "Do not base64 large archives into chat or MCP tool arguments.",
 ].join("\n");
 /**
- * Named fragments for the skill-template generator. The template carries
+ * Named fragments for the skill-template generator. The templates carry
  * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
- * `{{prose.receiptShape}}`, and `{{prose.signedUpload}}` placeholders;
+ * `{{prose.receiptShape}}`, `{{prose.signedUpload}}`,
+ * `{{prose.checkBeforePublish}}`, `{{prose.saveState}}`,
+ * `{{prose.updateSpace}}`, and `{{prose.continueAfterClaim}}` placeholders;
  * generate-skill.mjs substitutes these.
  */
 export const AGENT_PROSE = {
+    positioning: POSITIONING_PROSE,
     secretRules: SECRET_RULES_PROSE,
+    explainToUser: EXPLAIN_TO_USER_PROSE,
+    failureConduct: FAILURE_CONDUCT_PROSE,
     publishSequence: PUBLISH_SEQUENCE_PROSE,
     receiptShape: RECEIPT_SHAPE_PROSE,
     signedUpload: SIGNED_UPLOAD_PROSE,
+    checkBeforePublish: CHECK_BEFORE_PUBLISH_PROSE,
+    saveState: SAVE_STATE_PROSE,
+    updateSpace: UPDATE_SPACE_PROSE,
+    continueAfterClaim: CONTINUE_AFTER_CLAIM_PROSE,
+    lanePicker: LANE_PICKER_PROSE,
+    howToResearch: HOW_TO_RESEARCH_PROSE,
+    envNotes: ENV_NOTES_PROSE,
 };

package/dist/docs/agent-setup.js

@@ -1,11 +1,11 @@
 import { BRAND } from "@spacefast/common/brand";
-import { PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, } from "@spacefast/common/docs/agent-prose";
-import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "@spacefast/common/docs/skill-distribution";
+import { CHECK_BEFORE_PUBLISH_PROSE, CONTINUE_AFTER_CLAIM_PROSE, ENV_NOTES_PROSE, FAILURE_CONDUCT_PROSE, HOW_TO_RESEARCH_PROSE, LANE_PICKER_PROSE, POSITIONING_PROSE, PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SAVE_STATE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, UPDATE_SPACE_PROSE, } from "@spacefast/common/docs/agent-prose";
+import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "@spacefast/common/docs/skill-distribution";
 export const agentSetupUrl = `${BRAND.agentSetupOrigin}/ai`;
 export const agentSetupTextUrl = `${BRAND.agentSetupOrigin}/ai.txt`;
 const agentSetupParsedUrl = new URL(agentSetupUrl);
 export const agentSetupHostLabel = agentSetupParsedUrl.host + agentSetupParsedUrl.pathname;
-export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow the instructions to publish for me. Ask me what I want to publish if it isn't obvious.`;
+export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow it to publish this project — or update it if it's already on ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
 export function renderAgentSetupTemplate(value) {
     return value
         .replaceAll("{{AGENT_SETUP_URL}}", agentSetupUrl)
@@ -19,9 +19,13 @@ export function aiInstructionsText() {
     return [
         `# ${BRAND.productName} for AI agents`,
         "",
-        `Official instructions for AI agents publishing to ${BRAND.productName}, the static host where`,
-        "AI-made things are kept: permanent URLs, immutable versions, anonymous publish",
-        "with a claim link. Static files only — server code is never executed.",
+        `Official instructions for AI agents publishing to ${BRAND.productName}.`,
+        "",
+        POSITIONING_PROSE,
+        "",
+        "## Before you publish (check for an existing space)",
+        "",
+        CHECK_BEFORE_PUBLISH_PROSE,
         "",
         "## Publish with curl (no install, no account)",
         "",
@@ -29,6 +33,14 @@ export function aiInstructionsText() {
         "",
         RECEIPT_SHAPE_PROSE,
         "",
+        "## Save your state",
+        "",
+        SAVE_STATE_PROSE,
+        "",
+        "## Update a space",
+        "",
+        UPDATE_SPACE_PROSE,
+        "",
         "## Big files and cloud agents",
         "",
         SIGNED_UPLOAD_PROSE,
@@ -37,6 +49,14 @@ export function aiInstructionsText() {
         "",
         SECRET_RULES_PROSE,
         "",
+        "## Failure conduct",
+        "",
+        FAILURE_CONDUCT_PROSE,
+        "",
+        "## How to research",
+        "",
+        HOW_TO_RESEARCH_PROSE,
+        "",
         'Add a bearer access token with `-H "Authorization: Bearer ..."` to publish into the user\'s',
         "team instead of anonymously. Agent clients should prefer OAuth client credentials. Errors come back as JSON with stable `code` values and a",
         "`docsUrl`; fetch the `docsUrl` when you need recovery steps.",
@@ -69,15 +89,17 @@ export function aiInstructionsText() {
         "```",
         "",
         "Use `--json` on any command when the output will be parsed. Publishing the same",
-        "directory again updates the space saved in `.stattic/state.json`.",
+        "directory again updates the space saved in `.spacefast/state.json`.",
         "",
         "## MCP for agent clients",
         "",
+        LANE_PICKER_PROSE,
+        "",
         "Hosted MCP is the no-download cloud lane for ChatGPT, Codex, Claude, Cursor, and browser",
         "clients that can authenticate with OAuth/API bearer credentials:",
         "",
         "```text",
-        "https://mcp.spacefast.com/mcp",
+        "https://mcp.spacefast.com",
         "```",
         "",
         "Request `mcp:tools` plus the API scopes the tools need: `teams:read` for team context,",
@@ -98,8 +120,8 @@ export function aiInstructionsText() {
         "`spacefast://account/current`, `spacefast://teams/current`, `spacefast://spaces/recent`,",
         "`spacefast://spaces/{spaceId}`, and `spacefast://policy/current` for bounded read-only",
         "context.",
-        "`execute_spacefast` is dry-run-first; mutating multi-step workflows can return",
-        "`approval_required` and continue through `resume_spacefast` after the user approves.",
+        "`execute` is dry-run-first; mutating multi-step workflows can return",
+        "`approval_required` and continue through `resume` after the user approves.",
         "",
         "Use On-Device MCP when the agent needs the user's checkout, path-based publish, or file edits:",
         "",
@@ -115,14 +137,19 @@ export function aiInstructionsText() {
         "`SPACEFAST_AGENT_CONFIG` with private_key_jwt when available; otherwise use one-job",
         "`SPACEFAST_TOKEN` secrets and mask logs. Do not persist personal auth in ephemeral runners.",
         "",
-        "If your environment supports skill import, fetch the official skill for the",
-        `complete command reference: \`${spacefastSkillInstallCommand}\` (source: ${spacefastSkillUrl}).`,
+        "If your environment supports skill import, install the official skill:",
+        `\`${spacefastSkillInstallCommand}\`. Raw markdown source: \`${spacefastSkillFetchCommand}\` (${spacefastSkillUrl}).`,
         "",
         "## After publishing",
         "",
-        "- Share the live URL, the immutable version URL, and — for anonymous spaces — the",
-        "  claim link with its expiry.",
-        "- Never print access tokens, claim tokens, auth files, or `.stattic/state.json`.",
+        "- Share the live URL, the immutable version URL when ready, and — for anonymous spaces —",
+        "  the claim link with its expiry. If the receipt's immutable URL is null, poll the",
+        "  operation and version links with the claim token as bearer auth until the version is ready.",
+        "- Never print access tokens, claim tokens, auth files, or `.spacefast/state.json`.",
+        "",
+        "## After the user claims",
+        "",
+        CONTINUE_AFTER_CLAIM_PROSE,
         "",
         "## Space conventions",
         "",
@@ -151,14 +178,20 @@ export function aiInstructionsText() {
         "## Going deeper",
         "",
         "- Docs index for agents: https://spacefast.com/llms.txt",
+        "- One-click connect (Claude Code, Claude, Codex, Cursor, VS Code): https://spacefast.com/agents",
         "- Agent guide: https://spacefast.com/docs/agents",
         "- CLI reference: https://spacefast.com/docs/cli",
         "- REST API + OpenAPI: https://spacefast.com/docs/api",
         "- Publish contract (machine-readable): https://spacefast.com/publish-spec.json",
+        "- Connectors-directory manifest (hosted MCP listing): https://spacefast.com/.well-known/connector.json",
         "- Every error code: https://spacefast.com/docs/errors",
         "",
         "Append `.md` to any docs URL for Markdown, or just fetch — agent user agents get",
         "Markdown automatically.",
         "",
+        "## Environment notes",
+        "",
+        ENV_NOTES_PROSE,
+        "",
     ].join("\n");
 }

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

@@ -1,4 +1,4 @@
-export declare const hostedMcpEndpointUrl = "https://mcp.spacefast.com/mcp";
+export declare const hostedMcpEndpointUrl = "https://mcp.spacefast.com";
 export type AgentSolutionLane = "plugin" | "hosted-mcp" | "local-mcp" | "cli" | "prompt";
 export type AgentSolutionId = "codex" | "claude-code" | "claude-cowork" | "chatgpt" | "claude-ai" | "raycast" | "cursor" | "terminal" | "generic";
 export type AgentSolution = {
@@ -20,7 +20,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "plugin";
     readonly summary: "Recommended: Codex plugin.";
     readonly description: "Install the Spacefast skill/plugin so Codex can publish, update, and inspect spaces from the same setup path.";
-    readonly commands: readonly ["npx skills add spacefast/plugins --skill spacefast -g"];
+    readonly commands: readonly ["npx -y skills add spacefast/plugins --skill spacefast -g -a codex -y"];
     readonly guideUrl: `${string}/for-codex`;
     readonly detailGuideUrl: `${string}/guides/how-to-use-with-codex`;
     readonly setupText: string;
@@ -53,7 +53,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Connect ChatGPT-style cloud agents to Spacefast through hosted MCP; use the virtual workspace or signed uploads instead of local paths.";
-    readonly commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly commands: readonly ["https://mcp.spacefast.com"];
     readonly guideUrl: `${string}/docs/agents`;
     readonly setupText: string;
 }, {
@@ -63,7 +63,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Connect the web Claude app to Spacefast through hosted MCP when it cannot read your local checkout.";
-    readonly commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly commands: readonly ["https://mcp.spacefast.com"];
     readonly guideUrl: `${string}/docs/agents`;
     readonly setupText: string;
 }, {
@@ -73,7 +73,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Use hosted MCP for Raycast and similar clients that can connect to a remote MCP server but should not need a local Spacefast install.";
-    readonly commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly commands: readonly ["https://mcp.spacefast.com"];
     readonly guideUrl: `${string}/docs/agents`;
     readonly setupText: string;
 }, {

package/dist/docs/agent-solutions.js

@@ -1,7 +1,7 @@
 import { BRAND } from "../brand.js";
 import { agentSetupPrompt, agentSetupTextUrl, agentSetupUrl } from "./agent-setup.js";
 import { spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, spacefastCodexSkillInstallCommand, spacefastInstallCurlCommand, } from "./skill-distribution.js";
-export const hostedMcpEndpointUrl = "https://mcp.spacefast.com/mcp";
+export const hostedMcpEndpointUrl = "https://mcp.spacefast.com";
 function pluginText(label, commands, guideUrl) {
     return [
         `Set up ${BRAND.productName} for ${label}.`,
@@ -20,7 +20,7 @@ function hostedMcpText(label, guideUrl) {
         "",
         `MCP endpoint: ${hostedMcpEndpointUrl}`,
         "Transport: Streamable HTTP",
-        "Resource: https://api.spacefast.com/mcp",
+        "Resource: https://mcp.spacefast.com",
         "Minimum scope: mcp:tools",
         "Common scopes: teams:read spaces:read spaces:write publish:write domains:read domains:write",
         "",