@spacefast/common 0.0.13 → 0.0.18

package/dist/docs/agent-prose.js

@@ -1,4 +1,4 @@
-import { BRAND } 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:
 //
@@ -14,7 +14,7 @@ import { BRAND } from "../brand.js";
 //
 // 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.
-const API_ORIGIN = BRAND.apiOrigin;
+const API_ORIGIN = serviceOrigin("api", "prod");
 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
@@ -43,20 +43,6 @@ function findExpr(globs) {
         .map((glob) => (glob.includes("/") ? `-path "${glob}"` : `-name "${glob}"`))
         .join(" -o ");
 }
-function zipExcludeExpr(globs) {
-    // 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
  * them out of logs and transcripts, and never echo them back.
@@ -79,12 +65,13 @@ export const POSITIONING_PROSE = [
     "optimizes for agent-safe one-shot publish, claim, versioning, rollback, and continuation.",
 ].join("\n");
 export const EXPLAIN_TO_USER_PROSE = [
-    "Report the bare Live URL, repeatable expiring private Open URL, immutable Version URL, and Claim link",
-    "as separate actions. 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.",
+    "Present Open and Claim as the only actions. State anonymous expiry in user terms: the Space",
+    "exists until `data.claim.expiresAt` unless claimed; claiming preserves Open and removes its expiry.",
+    "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 FAILURE_CONDUCT_PROSE = [
-    "On failure, surface `error.code`, `error.docsUrl`, and `error.requestId`, then stop.",
+    "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`.",
 ].join("\n");
@@ -94,14 +81,34 @@ export const LANE_PICKER_PROSE = [
     "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",
+    "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. */
+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/getting-started/agents.md`) or read",
+    "`https://spacefast.com/llms.txt`. For contracts, read `https://spacefast.com/publish-spec.json`",
+    "or the OpenAPI linked from the API docs. Never guess limits: publish, then read diagnostics.",
+].join("\n");
+/** MCP plugin skill lane: prefer skills for workflows and execute for the OpenAPI catalog. */
+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 contracts, read `publish-spec.json` or OpenAPI via docs. Never guess limits: publish,",
+    "then inspect status or diagnostics through `execute`.",
+].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");
+export const ENV_NOTES_API_PROSE = [
+    "claude.ai: allow `api.spacefast.com` in egress settings. Codex sandbox: escalate only the",
+    "network call to `api.spacefast.com`. This skill is complete with curl and the docs links above;",
+    "CLI and MCP are optional upgrades documented at https://spacefast.com/docs/cli and",
+    "https://spacefast.com/docs/getting-started/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
@@ -113,33 +120,83 @@ export const CHECK_BEFORE_PUBLISH_PROSE = [
     "- 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).",
+    "- When authenticated, list existing spaces (`sf spaces list`, or `execute` with the generated list-spaces operation).",
     "",
     "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");
+export const CHECK_BEFORE_PUBLISH_API_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 you already have a bearer token, list spaces:",
+    "",
+    "```bash",
+    'curl -q -sS https://api.spacefast.com/v1/spaces -H "Authorization: Bearer $SPACEFAST_TOKEN"',
+    "```",
+    "",
+    "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");
+export const CHECK_BEFORE_PUBLISH_MCP_PROSE = [
+    "Before creating a space, check whether this project already has one:",
+    "",
+    "- Look for `.spacefast/space.json` or `.spacefast/state.json`, walking up from the working",
+    "  directory toward the filesystem root (On-Device reuses this link automatically).",
+    "- Look for a publish receipt earlier in this conversation.",
+    "- When authenticated, use `execute` to call the generated list-spaces operation.",
+    "",
+    "If any of these finds a space, publish a new version to that space instead of creating",
+    "another. Only create a new space when none exists and the user wants a new 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 = [
+export const BUNDLED_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:",
+    "the same space instead of creating a new one. Prefer MCP `publish` on On-Device — it writes",
+    "`.spacefast/` automatically. After a curl publish, pass the complete JSON receipt to the",
+    "bundled hardened writer. Set `SPACEFAST_SKILL_SCRIPTS` through the agent runtime/environment",
+    "to the absolute bundled `scripts/` directory; never interpolate that path into shell source:",
     "",
     "```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",
+    "\"${SPACEFAST_SKILL_SCRIPTS:?set this to the bundled scripts directory}/save-state.sh\" <<'SPACEFAST_PUBLISH_RECEIPT'",
+    "<paste the complete JSON publish receipt here>",
+    "SPACEFAST_PUBLISH_RECEIPT",
     "```",
     "",
-    "`<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.",
+    "The helper rejects symlinked state paths and uses exclusive, descriptor-relative atomic writes.",
+    "If the helper is unavailable, keep the receipt in agent memory for this session; do not",
+    "recreate credential state with shell redirections. Keep `.spacefast/state.json` out of",
+    "publish archives, commits, logs, and chat.",
+].join("\n");
+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/`. This distribution does not include the hardened filesystem helper, so keep",
+    "the receipt in agent memory or use CLI/MCP for the next publish. Do not recreate credential",
+    "state with shell redirections. Keep `.spacefast/state.json` out of publish archives, commits,",
+    "logs, and chat.",
+].join("\n");
+/** Curl/API skill: no CLI/MCP required to continue in-session. */
+export const SAVE_STATE_API_PROSE = [
+    "After the first publish, keep `data.space.id` and `data.claim.token` (when present) in agent",
+    "memory for this session so later publishes update the same space. You may write non-secret",
+    '`.spacefast/space.json` as `{"space":"<spc_id>"}` when helpful. Do not recreate credential',
+    "state with shell redirections. Keep claim tokens and `.spacefast/state.json` out of publish",
+    "archives, commits, logs, and chat.",
+].join("\n");
+export const SAVE_STATE_MCP_PROSE = [
+    "After the first publish, On-Device MCP persists `.spacefast/` automatically so the next",
+    "`publish` updates the same space. Hosted MCP has no local filesystem state; keep the space id",
+    "in the current agent session or pass it explicitly. Never ask the user to paste claim tokens",
+    "or access tokens into chat.",
 ].join("\n");
 /**
  * The UPDATE verb: a new version to the SAME space. Never re-run the
@@ -150,8 +207,8 @@ export const UPDATE_SPACE_PROSE = [
     "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>' \\",
+    'curl -q -sS -H "Authorization: Bearer <claim-token-or-access-token>" \\',
+    "  --form-string 'spaceId=<spc_id>' \\",
     '  -F "files=@index.html" \\',
     `  ${PUBLISH_ENDPOINT}`,
     "```",
@@ -173,7 +230,7 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "failure is the signal to upgrade your credential — call the exchange endpoint exactly once:",
     "",
     "```bash",
-    'curl -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
+    'curl -q -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
     `  ${EXCHANGE_ENDPOINT}`,
     "```",
     "",
@@ -183,30 +240,135 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "exactly once; if it returns `continuation_used` or `continuation_unavailable`, ask the user",
     "to create an API key in the dashboard (Account → API keys).",
 ].join("\n");
+const LEXICAL_PUBLISH_PATH_PREFLIGHT = [
+    'case "$publish_target" in /*) check_path="$publish_target" ;; *) check_path="$PWD/$publish_target" ;; esac',
+    'remaining="${check_path#/}"; check_path="/"',
+    'while [ -n "$remaining" ]; do',
+    '  case "$remaining" in */*) component="${remaining%%/*}"; remaining="${remaining#*/}" ;; *) component="$remaining"; remaining="" ;; esac',
+    '  case "$component" in ""|.) continue ;; ..) check_path="${check_path%/*}"; [ -n "$check_path" ] || check_path="/"; continue ;; esac',
+    '  [ "$check_path" = "/" ] && check_path="/$component" || check_path="$check_path/$component"',
+    '  [ ! -L "$check_path" ] || { printf "error: symbolic link in publish path: %s\\n" "$check_path" >&2; exit 2; }',
+    "done",
+];
+const SECURE_ARCHIVE_RECIPE = [
+    'secure_python=""',
+    "for candidate in /usr/bin/python3.14 /usr/bin/python3.13 /usr/bin/python3.12 /usr/bin/python3.11 /usr/bin/python3.10 /usr/bin/python3.9 /usr/bin/python3.8 /usr/local/bin/python3.14 /usr/local/bin/python3.13 /usr/local/bin/python3.12 /usr/local/bin/python3.11 /usr/local/bin/python3.10 /usr/local/bin/python3.9 /opt/homebrew/bin/python3 /opt/homebrew/bin/python3.14 /opt/homebrew/bin/python3.13 /opt/homebrew/bin/python3.12 /opt/homebrew/bin/python3.11 /opt/homebrew/bin/python3.10 /opt/homebrew/bin/python3.9; do",
+    '  [ -x "$candidate" ] && [ -f "$candidate" ] || continue',
+    '  case "$candidate" in /opt/homebrew/*) ;; *) [ ! -L "$candidate" ] || continue ;; esac',
+    '  secure_python="$candidate"; break',
+    "done",
+    '[ -n "$secure_python" ] || { printf "error: trusted python3 is required for a race-safe archive\\n" >&2; exit 2; }',
+    `"$secure_python" -I - "$publish_target" <<'SPACEFAST_ARCHIVE' | curl -q -sS -F 'archive=@-;filename="spacefast-site.zip"' ${PUBLISH_ENDPOINT}`,
+    "import fnmatch, os, stat, sys, zipfile",
+    'directory_flags = os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)',
+    'file_flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)',
+    'excluded_directories = {".git", ".spacefast", ".ssh", ".aws", ".kube", ".docker"}',
+    'excluded_files = (".env*", ".npmrc", ".netrc", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*", "*.zip", "*.tar", "*.tgz")',
+    "def excluded(path):",
+    '    parts = path.split("/")',
+    "    return any(part in excluded_directories for part in parts[:-1]) or any(fnmatch.fnmatchcase(parts[-1], pattern) for pattern in excluded_files)",
+    "def same(left, right): return (left.st_dev, left.st_ino) == (right.st_dev, right.st_ino)",
+    'def walk(archive, directory_fd, prefix=""):',
+    "    for name in sorted(os.listdir(directory_fd)):",
+    '        archive_name = f"{prefix}/{name}" if prefix else name',
+    "        if excluded(archive_name): continue",
+    "        entry = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)",
+    '        if stat.S_ISLNK(entry.st_mode): raise RuntimeError(f"symbolic link in publish root: {archive_name}")',
+    "        if stat.S_ISDIR(entry.st_mode):",
+    "            child_fd = os.open(name, directory_flags, dir_fd=directory_fd)",
+    "            try:",
+    '                if not same(os.fstat(child_fd), entry): raise RuntimeError(f"directory changed while opening: {archive_name}")',
+    "                walk(archive, child_fd, archive_name)",
+    "            finally: os.close(child_fd)",
+    "            continue",
+    '        if not stat.S_ISREG(entry.st_mode) or entry.st_nlink != 1: raise RuntimeError(f"unsafe publish entry: {archive_name}")',
+    "        file_fd = os.open(name, file_flags, dir_fd=directory_fd)",
+    "        try:",
+    "            opened = os.fstat(file_fd); current = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)",
+    '            if opened.st_nlink != 1 or not same(opened, entry) or not same(opened, current): raise RuntimeError(f"file changed while opening: {archive_name}")',
+    "            info = zipfile.ZipInfo(archive_name); info.compress_type = zipfile.ZIP_DEFLATED; info.external_attr = (opened.st_mode & 0xFFFF) << 16",
+    '            with archive.open(info, "w") as output:',
+    "                while True:",
+    "                    chunk = os.read(file_fd, 65536)",
+    "                    if not chunk: break",
+    "                    output.write(chunk)",
+    "        finally: os.close(file_fd)",
+    "path = os.path.normpath(sys.argv[1] if os.path.isabs(sys.argv[1]) else os.path.join(os.getcwd(), sys.argv[1]))",
+    'root_fd = os.open("/", directory_flags)',
+    "try:",
+    '    for component in [part for part in path.split("/") if part]:',
+    "        next_fd = os.open(component, directory_flags, dir_fd=root_fd); os.close(root_fd); root_fd = next_fd",
+    '    with zipfile.ZipFile(sys.stdout.buffer, "w", allowZip64=True) as archive: walk(archive, root_fd)',
+    "finally: os.close(root_fd)",
+    "SPACEFAST_ARCHIVE",
+];
 /**
- * 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 const PUBLISH_SEQUENCE_PROSE = [
-    "Publish a single file:",
+    "Publish a single file after rejecting symbolic links in the file or any existing ancestor:",
+    "Set `SPACEFAST_PUBLISH_TARGET` through the agent runtime/environment, not by interpolating",
+    "a repository path into this source. The recipe passes it as a separately quoted argv element.",
+    "Fresh serving capacity can take a moment; it replays only `space_capacity_warming` with one",
+    "stable idempotency identity, follows `Retry-After`, and stops after ten attempts:",
     "",
     "```bash",
-    `curl -sS -F "files=@index.html" ${PUBLISH_ENDPOINT}`,
+    ': "${SPACEFAST_PUBLISH_TARGET:?set this through the runtime environment}"',
+    "bash -s -- \"$SPACEFAST_PUBLISH_TARGET\" <<'SPACEFAST_PUBLISH'",
+    "set -euo pipefail",
+    'publish_target="$1"',
+    'case "$publish_target" in -*) publish_target="./$publish_target" ;; esac',
+    ...LEXICAL_PUBLISH_PATH_PREFLIGHT,
+    '[ -f "$publish_target" ] || { printf "error: publish file is not a regular file\\n" >&2; exit 2; }',
+    'escaped_path="${publish_target//\\\\/\\\\\\\\}"',
+    'escaped_path="${escaped_path//\\"/\\\\\\"}"',
+    "idempotency_key=\"publish-$(od -An -N16 -tx1 /dev/urandom | tr -d ' \\n')\"",
+    "idempotency_principal=\"$(od -An -N32 -tx1 /dev/urandom | tr -d ' \\n')\"",
+    'api_origin="${SPACEFAST_API_ORIGIN:-https://api.spacefast.com}"',
+    'headers_file="$(mktemp)"',
+    "trap 'rm -f \"$headers_file\"' EXIT",
+    "attempt=1",
+    "while :; do",
+    '  response="$(curl -q -sS -D "$headers_file" -F "files=@\\"$escaped_path\\"" \\',
+    '    -H "Idempotency-Key: $idempotency_key" \\',
+    '    -H "x-spacefast-idempotency-principal: $idempotency_principal" \\',
+    '    "$api_origin/v1/publish")"',
+    '  if ! printf \'%s\' "$response" | grep -Eq \'"code"[[:space:]]*:[[:space:]]*"space_capacity_warming"\'; then',
+    "    printf '%s\\n' \"$response\"",
+    "    break",
+    "  fi",
+    '  [ "$attempt" -lt 10 ] || { printf \'%s\\n\' "$response"; exit 1; }',
+    '  retry_after="$(awk \'tolower($1) == "retry-after:" { gsub("\\r", "", $2); print $2; exit }\' "$headers_file")"',
+    '  case "$retry_after" in ""|*[!0-9]*) retry_after=20 ;; esac',
+    "  attempt=$((attempt + 1))",
+    '  sleep "$retry_after"',
+    "done",
+    "SPACEFAST_PUBLISH",
     "```",
     "",
     "Publish a folder by zipping only the intended public output root. Do not archive a repository",
     "root or `.` blindly. Before zipping, confirm the publish root contains no secrets, source",
-    "control, auth state, or unrelated build/cache folders:",
+    "control, auth state, unrelated build/cache folders, or symbolic links:",
+    "Set `SPACEFAST_PUBLISH_TARGET` through the agent runtime/environment. It is passed as a",
+    "separately quoted argv element and is never evaluated as outer shell source:",
     "",
     "```bash",
-    `find {publish-root} \\( ${findExpr(ARCHIVE_SECRET_GLOBS)} \\) -print`,
-    `(cd {publish-root} && zip -r ../spacefast-site.zip . -x ${zipExcludeExpr(ARCHIVE_SECRET_GLOBS)} "*.zip" "*.tar" "*.tgz")`,
-    `curl -sS -F archive=@spacefast-site.zip ${PUBLISH_ENDPOINT}`,
+    ': "${SPACEFAST_PUBLISH_TARGET:?set this through the runtime environment}"',
+    "bash -s -- \"$SPACEFAST_PUBLISH_TARGET\" <<'SPACEFAST_PUBLISH'",
+    "set -euo pipefail",
+    'publish_target="$1"',
+    'case "$publish_target" in -*) publish_target="./$publish_target" ;; esac',
+    ...LEXICAL_PUBLISH_PATH_PREFLIGHT,
+    `find "$publish_target" \\( ${findExpr(ARCHIVE_SECRET_GLOBS)} \\) -print`,
+    '! find "$publish_target" -type l -print -quit | grep -q . || { printf "error: symbolic link in publish root\\n" >&2; exit 2; }',
+    ...SECURE_ARCHIVE_RECIPE,
+    "SPACEFAST_PUBLISH",
     "```",
     "",
-    "If the preflight prints credential-like files, stop and choose a narrower generated output",
-    "directory or remove those files from the publish root before uploading.",
+    "If the preflight prints credential-like files, or the publish root contains a symbolic link,",
+    "stop and choose a narrower generated output directory or remove the unsafe entry before uploading.",
 ].join("\n");
 /**
  * What the JSON publish receipt contains and how to read it. The receipt is the
@@ -216,7 +378,7 @@ export const RECEIPT_SHAPE_PROSE = [
     "The JSON receipt is the source of truth:",
     "",
     "- `data.space.liveUrl` — the live URL.",
-    "- `data.open.url` and `data.open.expiresAt` — a repeatable private author Link until expiry, claim, or revocation.",
+    "- `data.open.url` and `data.open.expiresAt` — reusable access; claim preserves the URL and changes its expiry to null.",
     "  It is not a stable URL or recipient Link; clients must not persist it as Space state.",
     "- `data.version.immutableUrl` — the permanent address of the frozen Version. The bare URL",
     "  carries no authority: use the receipt's Open URL for the author's browser or create a scoped",
@@ -234,7 +396,7 @@ export const RECEIPT_SHAPE_PROSE = [
     `  \`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.",
+    "- `code`, `type`, and `suggestions` on the problem document — stable error code plus exact recovery docs and next steps.",
     "",
     "If no files changed, the API may omit `upload`; report the receipt and diagnostics rather than",
     "inventing a separate success signal.",
@@ -248,7 +410,7 @@ export const SIGNED_UPLOAD_PROSE = [
     "content would be awkward. Start with a manifest instead of file bytes:",
     "",
     "```bash",
-    `curl -sS ${PUBLISH_ENDPOINT} \\`,
+    `curl -q -sS ${PUBLISH_ENDPOINT} \\`,
     '  -H "content-type: application/json" \\',
     '  -d \'{"files":[{"path":"index.html","size":1234,"contentType":"text/html","sha256":"...","sourceUrl":"https://example.com/index.html"}]}\'',
     "```",
@@ -261,7 +423,7 @@ export const SIGNED_UPLOAD_PROSE = [
     "For importing an archive that already lives somewhere else, prefer the import-from-link API:",
     "",
     "```bash",
-    "curl -sS https://api.spacefast.com/v1/spaces/{spaceId}/imports \\",
+    "curl -q -sS https://api.spacefast.com/v1/spaces/{spaceId}/imports \\",
     '  -H "content-type: application/json" \\',
     '  -H "Authorization: Bearer $SPACEFAST_TOKEN" \\',
     '  -d \'{"source":{"kind":"url","url":"https://example.com/site.zip"}}\'',
@@ -289,10 +451,18 @@ export const AGENT_PROSE = {
     receiptShape: RECEIPT_SHAPE_PROSE,
     signedUpload: SIGNED_UPLOAD_PROSE,
     checkBeforePublish: CHECK_BEFORE_PUBLISH_PROSE,
+    checkBeforePublishApi: CHECK_BEFORE_PUBLISH_API_PROSE,
+    checkBeforePublishMcp: CHECK_BEFORE_PUBLISH_MCP_PROSE,
+    bundledSaveState: BUNDLED_SAVE_STATE_PROSE,
     saveState: SAVE_STATE_PROSE,
+    saveStateApi: SAVE_STATE_API_PROSE,
+    saveStateMcp: SAVE_STATE_MCP_PROSE,
     updateSpace: UPDATE_SPACE_PROSE,
     continueAfterClaim: CONTINUE_AFTER_CLAIM_PROSE,
     lanePicker: LANE_PICKER_PROSE,
     howToResearch: HOW_TO_RESEARCH_PROSE,
+    howToResearchApi: HOW_TO_RESEARCH_API_PROSE,
+    howToResearchMcp: HOW_TO_RESEARCH_MCP_PROSE,
     envNotes: ENV_NOTES_PROSE,
+    envNotesApi: ENV_NOTES_API_PROSE,
 };

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

@@ -3,6 +3,7 @@ export declare const agentSetupUrl: string;
 export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
 export declare const agentSetupPrompt: string;
+export declare const anonymousPublishCurlCommand: string;
 /**
  * Typed, safe decline states for the app-private redemption exchange.
  * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
@@ -31,40 +32,42 @@ export type AgentHandoff = Readonly<{
 }>;
 /**
  * The single shared grammar for handoff links:
- * `<app-origin>/agent/<documentId>#<secret>`. The document ID must match
- * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
- * high-entropy and makes the public-projection leak check meaningful); the two must differ;
- * queries and embedded credentials are forbidden. The URL must sit exactly on the caller's
- * configured HTTP(S) app origin; that origin pin enforces scheme, hostname, and port without a
- * second host allowlist that would reject legitimate dev or container origins.
+ * `<access-origin>/agent/<documentId>/<oneUseToken>`. The document ID must match
+ * `[A-Za-z0-9_-]{1,512}` and the token `[A-Za-z0-9_-]{16,512}`; the two must differ;
+ * queries, fragments, and URL userinfo are forbidden. The URL must sit exactly on the caller's
+ * configured HTTP(S) access origin; the clean static document may live on a separate explicitly
+ * supplied dashboard origin.
  * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
  * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
  * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
  * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
  * grammar can never fork.
  */
-export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string): Readonly<{
+export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string, documentOrigin?: string): Readonly<{
     documentId: string;
     documentUrl: string;
+    handoffUrl: string;
     secret: string;
 }>;
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export declare const AGENT_HANDOFF_CLI_TARGET_IDS: readonly ConnectTargetId[];
 export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to publish.";
 /** The fetch-safety contract: reading the document never consumes or leaks a handoff. */
-export declare const AGENT_HANDOFF_FETCH_SAFETY = "Keep the original handoff link private. Fetching this document did not use the link or send its fragment secret; the secret is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.";
-export declare const AGENT_HANDOFF_FRAGMENT_HYGIENE = "Keep its fragment out of commands, request URLs, logs, and replies.";
+export declare const AGENT_HANDOFF_FETCH_SAFETY = "Keep the original handoff link private. Fetching this clean document URL did not use or send its credential; the credential is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.";
+export declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the private handoff URL out of commands, request URLs, logs, and replies.";
 export declare const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE: string;
 export declare const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Open URL; create a scoped Link when a recipient needs access.";
+export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Access URL; create a scoped Link when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export declare function agentHandoffConnectSections(target: ConnectTarget): string[];
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
 export declare function buildAgentHandoff(input: {
     expectedOrigin: string;
+    documentOrigin?: string;
     mcpEndpoint: string;
     targetId: ConnectTargetId;
     url: string;
 }): AgentHandoff;
 export declare function renderAgentSetupTemplate(value: string): string;
 export declare function aiInstructionsText(): string;
+export declare function agentSetupMarkdown(): string;