@spacefast/common 0.0.26 → 0.2.1

package/dist/docs/error-docs.js

@@ -1,9 +1,8 @@
-// Error reference content (the platform spec "Global API Conventions"):
-// every problem document `type` points at `https://spacefast.com/docs/errors/{code}`,
-// and those pages are GENERATED from this table — one entry per member of
-// `ERROR_CODES`, asserted complete by the conformance suite so links never rot
-// and pages never go missing. The standalone website renders the HTML pages and writes the
-// `.md` twins from the same entries.
+// Error reference content (the platform spec "Global API Conventions"): every
+// problem document `type` points at `https://spacefast.com/docs/errors/{code}`,
+// and those pages are GENERATED from this table, one entry per `ERROR_CODES`
+// member. The conformance suite asserts completeness, so links never rot; the
+// website renders the HTML pages and `.md` twins from the same entries.
 import { BRAND } from "../brand.js";
 import { serviceOrigin } from "../config/domains.js";
 import { errorDocsUrl, errorTitle, PROBLEM_CONTENT_TYPE, } from "../contracts/error-codes.js";
@@ -69,6 +68,10 @@ export const ERROR_DOCS = {
         summary: "An authorization code is required to complete this step.",
         fix: "Pass the code returned by the authorization step.",
     },
+    authorization_level_not_allowed: {
+        summary: "This operation is reserved for a signed-in person, or the credential is acting at an authorization level the operation does not accept.",
+        fix: "This is not a scope problem and elevation will not clear it. Ask the person to perform the action in the dashboard.",
+    },
     authorization_pending: {
         summary: "The device login is not approved yet.",
         fix: "Keep polling at the advised interval until the user approves the request.",
@@ -189,9 +192,29 @@ export const ERROR_DOCS = {
         summary: "The configuration declares more template files than the plan allows.",
         fix: "Reduce the number of template entries in sf.jsonc. If you are still stuck, POST /v1/feedback with the error code and requestId.",
     },
+    confirmation_denied: {
+        summary: "A person reviewed this exact action and denied it. The denial is terminal.",
+        fix: "Stop retrying. You cannot clear this yourself; report the denial to the person who asked for the action.",
+    },
+    confirmation_expired: {
+        summary: "The confirmation for this action expired before a person decided it.",
+        fix: "Request the action again to get a fresh confirmation URL and continuation token. Do not retry the old token.",
+    },
+    confirmation_mismatch: {
+        summary: "The continuation token is bound to different action terms or a different resource revision than the request presenting it.",
+        fix: "Request a fresh confirmation for the action you actually intend to perform.",
+    },
+    confirmation_required: {
+        summary: "This action destroys live content or spends money, so a person must approve this exact action before it runs.",
+        fix: "Send the person to the `url` in the error details, then poll `pollUrl` with the `continuationToken` every 5 seconds. Give up after 10 minutes and report back. No flag or environment variable can clear this.",
+    },
+    confirmation_token_required: {
+        summary: "This exact action already has a decision, and a retry without its continuation token cannot clear the gate.",
+        fix: "Resume the existing decision with its continuation token instead of repeating the original request.",
+    },
     continuation_unavailable: {
         summary: "This space key can no longer be exchanged for an API key.",
-        fix: "If the space is claimed, ask its owner for an API key (dashboard: Account → API keys). If it is still unclaimed, keep using the space key as bearer auth instead of exchanging it. If you are still stuck, POST /v1/feedback with the error code and requestId.",
+        fix: "If the space is claimed, ask its owner for an API key (dashboard: team → Agents → API keys). If it is still unclaimed, keep using the space key as bearer auth instead of exchanging it. If you are still stuck, POST /v1/feedback with the error code and requestId.",
     },
     continuation_used: {
         summary: "This space key was already exchanged for a durable API key.",
@@ -213,6 +236,10 @@ export const ERROR_DOCS = {
         summary: "The credential used for this request was revoked.",
         fix: "Create a new API key and update your client.",
     },
+    credential_sponsor_inactive: {
+        summary: "The person who authorized this machine credential is no longer an active member of the team it acts for.",
+        fix: "A team admin must re-authorize the credential, or point it at a live member, before it works again.",
+    },
     csam_blocked: {
         summary: "The content was blocked because it matched known child sexual abuse material.",
         fix: "This action is final and reported as required by law. Do not retry.",
@@ -221,6 +248,18 @@ export const ERROR_DOCS = {
         summary: "CSAM enforcement policy cannot be set below the mandatory account-suspend floor.",
         fix: "Set the CSAM category enforcement tier to account suspension.",
     },
+    dashboard_prefs_key_invalid: {
+        summary: "A dashboard preference key is empty or longer than the 64-character limit.",
+        fix: "Send preference keys that are between 1 and 64 characters long.",
+    },
+    dashboard_prefs_too_large: {
+        summary: "The merged dashboard preferences would exceed the 16KB serialized size limit.",
+        fix: "Store smaller values, or delete preferences you no longer need by setting them to null.",
+    },
+    dashboard_prefs_too_many_keys: {
+        summary: "The merged dashboard preferences would hold more than the 50 allowed keys.",
+        fix: "Delete preferences you no longer need by setting them to null before adding more.",
+    },
     data_location_immutable: {
         summary: "This request tried to change data location through an immutable path.",
         fix: "Data location is fixed when the space is created and cannot be changed afterwards. Create a new space in the region you want.",
@@ -229,6 +268,14 @@ export const ERROR_DOCS = {
         summary: "The live version has no database to read.",
         fix: 'Publish a Zero app, or declare `"database": true` under `runtime` in sf.jsonc for a Functions app.',
     },
+    decision_execution_lost: {
+        summary: "The approved action's execution lease is no longer held, so its result cannot be recorded.",
+        fix: "Poll the continuation to read the decision's current state before requesting the action again.",
+    },
+    decision_in_progress: {
+        summary: "This approved action is already executing.",
+        fix: "Poll the continuation instead of retrying the action; the original receipt is returned once it finishes.",
+    },
     device_authorization_failed: {
         summary: "The device login request failed and cannot be completed.",
         fix: "Start a new device login flow.",
@@ -419,7 +466,7 @@ export const ERROR_DOCS = {
     },
     domain_reserved_suffix: {
         summary: `The hostname is under a ${BRAND.productName}-managed suffix and cannot be added as a domain.`,
-        fix: `Use a domain you own. ${BRAND.productName} assigns default and management hostnames automatically.`,
+        fix: `Use a domain you own. ${BRAND.productName} assigns default hostnames automatically.`,
     },
     domain_transfer_active: {
         summary: "The domain has a transfer in progress, which blocks this operation.",
@@ -441,6 +488,18 @@ export const ERROR_DOCS = {
         summary: "The version upload declares the same file path twice.",
         fix: "Deduplicate the file list so every path appears once.",
     },
+    elevation_not_required: {
+        summary: "The grant already includes every scope the elevation asked for.",
+        fix: "Retry the operation with the credential you already have; no elevation is needed.",
+    },
+    email_already_claimed: {
+        summary: "That email address is already verified on an account.",
+        fix: "Sign in with the address instead of adding it, or use a different address.",
+    },
+    email_verification_code_invalid: {
+        summary: "The emailed confirmation code is wrong, expired, or already used.",
+        fix: "Request a new code and enter the six digits from the newest email.",
+    },
     enforcement_policy_overlap: {
         summary: "Enforcement policy severity ranges overlap within a category.",
         fix: "Adjust the category ranges so at most one policy covers each severity.",
@@ -485,6 +544,10 @@ export const ERROR_DOCS = {
         summary: "An inject snippet exceeds the per-snippet size limit.",
         fix: "Keep each inject snippet at or under 8 KB.",
     },
+    insufficient_scope: {
+        summary: "The credential authenticated, but its granted scopes do not include a set this operation accepts.",
+        fix: "Read the `WWW-Authenticate` challenge for the missing scopes, then request elevation or reconnect with them.",
+    },
     internal_error: {
         summary: "Something went wrong on our side.",
         fix: "Retry the request. If the error persists, contact support with the requestId.",
@@ -501,6 +564,10 @@ export const ERROR_DOCS = {
         summary: "The requested data location is not a supported region.",
         fix: "Pick a region from the documented data locations, or use auto.",
     },
+    invalid_decision_state: {
+        summary: "The decision record is in a state this endpoint cannot interpret.",
+        fix: "Request the action again to open a fresh decision.",
+    },
     invalid_device_code: {
         summary: "The device code is invalid or expired.",
         fix: "Start a new device login flow.",
@@ -513,6 +580,10 @@ export const ERROR_DOCS = {
         summary: "The domain name is not a valid registrable hostname.",
         fix: "Check the spelling and use a fully qualified domain name.",
     },
+    invalid_elevation_request: {
+        summary: "An elevation request needs at least one scope and a rationale of 1 to 1024 characters.",
+        fix: "Send a non-empty scope list and a specific rationale, then retry.",
+    },
     invalid_file_path: {
         summary: "A file path in the request is not a valid space path.",
         fix: "Use forward-slash relative paths without traversal segments.",
@@ -557,6 +628,18 @@ export const ERROR_DOCS = {
         summary: "The user code does not match a pending device login.",
         fix: "Enter the code exactly as your CLI shows it. Codes expire after a few minutes.",
     },
+    invalid_usage_bucket: {
+        summary: "The usage bucket has an invalid time range.",
+        fix: "Set bucketEnd to an instant after bucketStart, then retry.",
+    },
+    invalid_usage_correction: {
+        summary: "The correction does not match the original usage record.",
+        fix: "Use the same tenant, principal, space, mode, dimension, and bucket as the original.",
+    },
+    invalid_usage_window: {
+        summary: "The requested usage window is invalid or longer than 92 days.",
+        fix: "Use a positive window of 92 days or less.",
+    },
     invalid_version_path: {
         summary: "A file path in the version is not a valid space path.",
         fix: "Use forward-slash relative paths without traversal segments.",
@@ -583,7 +666,7 @@ export const ERROR_DOCS = {
     },
     invalid_zero_realtime_replay_query: {
         summary: "The Zero realtime replay query parameters are invalid.",
-        fix: "Use a valid afterEventId cursor and a numeric replay limit between 1 and 100.",
+        fix: "Send a retained `afterEventId` from a previous page's `nextAfterEventId`, and a replay limit between 1 and 100.",
     },
     invitation_already_exists: {
         summary: "An invitation for this email already exists on the team.",
@@ -605,6 +688,26 @@ export const ERROR_DOCS = {
         summary: "Requests from this IP address are blocked for abuse or policy reasons.",
         fix: "If you believe this block is a mistake, contact support with your IP address.",
     },
+    issuer_exists: {
+        summary: "This partner token issuer is already active for another tenant.",
+        fix: "Use a globally unique issuer URL, or revoke the existing issuer before registering it here.",
+    },
+    issuer_not_active: {
+        summary: "The partner token issuer is registered but is not active.",
+        fix: "Activate the issuer, then request a new partner token.",
+    },
+    issuer_proof_invalid: {
+        summary: "The partner token issuer key-possession proof is invalid.",
+        fix: "Sign the current challenge and minted audience with one of the registered Ed25519 keys, then retry activation.",
+    },
+    issuer_tenant_occupied: {
+        summary: "This tenant already has a pending or active partner token issuer.",
+        fix: "Activate or revoke the tenant's existing issuer before registering another one.",
+    },
+    issuer_unknown: {
+        summary: "The partner token names an issuer that Spacefast does not recognize.",
+        fix: "Register the exact token issuer, then request a new partner token.",
+    },
     job_not_found: {
         summary: "The background job was not found.",
         fix: "Verify the job id. Spacefast eventually prunes completed jobs.",
@@ -685,6 +788,10 @@ export const ERROR_DOCS = {
         summary: "The domain's observed nameservers diverge from the expected set.",
         fix: "Align the registrar's nameserver records with the expected set, then re-check.",
     },
+    no_space_selected: {
+        summary: "The command needs a Space and this directory does not select one.",
+        fix: "Pass --space, link the directory with `sf link --space <id>`, or run it where a project link already selects a Space. `sf spaces ls` lists what the credential can reach.",
+    },
     noop_publish: {
         summary: "The publish matched the live version exactly, so nothing changed.",
         fix: "No action is needed. The existing live version already serves this content.",
@@ -697,6 +804,22 @@ export const ERROR_DOCS = {
         summary: "The requested resource was not found.",
         fix: "Verify that the id is correct and that your credential can access the resource.",
     },
+    partner_preset_not_grantable: {
+        summary: "The `partner_admin` preset is a tenant-rooted partner credential and cannot be minted as an ordinary team API key.",
+        fix: "Ask an operator to bootstrap a partner key for the tenant, or request a team-scoped preset such as `space_admin`.",
+    },
+    partner_tenant_immutable_client: {
+        summary: "The tenant's provider client cannot be changed.",
+        fix: "Create a new tenant with the desired provider client instead.",
+    },
+    password_already_set: {
+        summary: "The account already has a password.",
+        fix: "Change the existing password instead of setting a new one.",
+    },
+    password_compromised: {
+        summary: "The password appears in a public breach corpus.",
+        fix: "Pick a password you have not used anywhere else, then try again.",
+    },
     path_case_collision: {
         summary: "Two file paths differ only by letter case, which collides on serving.",
         fix: "Rename one of the files so that paths are unique case-insensitively.",
@@ -713,14 +836,14 @@ export const ERROR_DOCS = {
         summary: "This plan grant was already revoked.",
         fix: "No action is needed. If the team should regain the plan, create a new grant.",
     },
+    plan_unknown: {
+        summary: "The requested plan name is not in the tenant's live plan catalog, so it cannot be assigned to a principal.",
+        fix: "Assign a plan declared in the tenant's system-space manifest. List the catalog's plan names and use one of them.",
+    },
     placement_invalid_burstable: {
         summary: "The placement burstable option was used with an unsupported placement mode.",
         fix: 'Set `placement.mode` to `"dedicated"` before setting `placement.burstable`, or remove the burstable option.',
     },
-    platform_tenant_immutable_client: {
-        summary: "The tenant's provider client cannot be changed.",
-        fix: "Create a new tenant with the desired provider client instead.",
-    },
     policy_exceeds_grantor: {
         summary: "The requested key policy grants more than your own credential allows.",
         fix: "Request a policy that is a subset of the credential creating the key.",
@@ -733,14 +856,66 @@ export const ERROR_DOCS = {
         summary: "Too many concurrent uploads for this space.",
         fix: "Wait for the Retry-After window, then resume. At most 4 uploads run per space at once.",
     },
+    primary_email_not_removable: {
+        summary: "The primary email address cannot be removed while it is the primary.",
+        fix: "Make another verified address primary first, then remove this one.",
+    },
+    principal_closed: {
+        summary: "The external principal is closed. Its spaces are tombstoned and cannot be modified.",
+        fix: "A closed principal is terminal and cannot be reopened; create a new principal to resume.",
+    },
+    principal_has_active_spaces: {
+        summary: "The external principal still owns spaces, so it cannot be closed.",
+        fix: "Delete the principal's spaces first, or retry with `force` to tombstone them as part of the close.",
+    },
+    principal_not_found: {
+        summary: "No external principal with that id exists in this tenant.",
+        fix: "List `/v1/principals` to see the ids this tenant knows; a principal appears only once it owns a resource.",
+    },
     principal_space_mismatch: {
         summary: "The space does not belong to the principal in the request.",
         fix: "Use the space's owning team or account in the request path.",
     },
+    principal_suspended: {
+        summary: "The external principal is suspended. Its spaces serve the suspended page and its mutations are blocked.",
+        fix: "Unsuspend the principal to restore serving and writes; a Spacefast-applied suspension can only be lifted by Spacefast.",
+    },
+    principal_suspension_locked: {
+        summary: "The suspension was applied by Spacefast (legal/abuse) and cannot be lifted by the partner.",
+        fix: "Contact Spacefast support to resolve a platform-applied suspension.",
+    },
     promote_admission_exceeded: {
         summary: "Too many archived files are being restored for this space right now.",
         fix: "Retry shortly. Spacefast limits restores to protect the host.",
     },
+    promotion_live_content_missing: {
+        summary: "The live tenant's system space has nothing published, so promotion has no content to carry forward.",
+        fix: "Publish the live system space once, then promote the test tenant again.",
+    },
+    promotion_live_system_space_invalid: {
+        summary: "The space designated as the live tenant's system space is not an active space that tenant owns.",
+        fix: "Designate a live, active space owned by this tenant as its system space, then promote again.",
+    },
+    promotion_live_system_space_not_designated: {
+        summary: "The live tenant has no designated system space, and promotion publishes the test manifest onto it.",
+        fix: "Set the live tenant's systemSpaceId to a space it owns, then promote again.",
+    },
+    promotion_not_live_tenant: {
+        summary: "Promotion targets a live tenant, and the tenant named in the request is not in live mode.",
+        fix: "Call promotion against the live tenant, not its test twin.",
+    },
+    promotion_nothing_to_promote: {
+        summary: "The test tenant's system space has no live manifest, so there is no configuration to promote.",
+        fix: "Publish the test tenant's system space first, then promote it.",
+    },
+    promotion_runtime_publish_incomplete: {
+        summary: "The promoted version was accepted but its runtime publish did not finish, so live is unchanged.",
+        fix: "Retry the promotion. If it keeps failing, contact support with the `requestId`.",
+    },
+    promotion_test_twin_missing: {
+        summary: "This live tenant has no linked test tenant, so there is nothing to promote from.",
+        fix: "Create the tenant's test twin and publish its system space before promoting.",
+    },
     provider_error: {
         summary: "WP Cloud reported an error.",
         fix: "Retry. If the error persists, contact support with the `requestId`.",
@@ -853,6 +1028,10 @@ export const ERROR_DOCS = {
         summary: "The named job queue does not exist.",
         fix: "Check the queue name against the operator queue list.",
     },
+    quota_exceeded: {
+        summary: "This action would exceed a quota on the plan assigned to the owning customer. The problem details name which quota (for example, the spaces cap) and its limit.",
+        fix: "Delete an existing resource to free room, or assign the customer a plan whose quota allows it.",
+    },
     response_headers_unservable: {
         summary: "A file needs a response header that the platform cannot deliver for large files.",
         fix: "Reduce the file below 100 MiB or drop the custom header.",
@@ -890,8 +1069,8 @@ export const ERROR_DOCS = {
         fix: "Use a runtime token scoped for this action.",
     },
     runtime_api_not_found: {
-        summary: "The runtime management endpoint was not found.",
-        fix: "Send the request with the management hostname as the Host header. Spacefast does not serve management routes on public hostnames.",
+        summary: "The requested runtime action was not found.",
+        fix: "Use a supported runtime action and a token scoped for that action.",
     },
     runtime_callback_forbidden: {
         summary: "The runtime callback cannot be authenticated.",
@@ -989,6 +1168,10 @@ export const ERROR_DOCS = {
         summary: "The service request signature cannot be verified.",
         fix: "Sign the exact request method, path, body digest, timestamp, and a fresh nonce.",
     },
+    session_not_fresh: {
+        summary: "This action needs a recent identity confirmation.",
+        fix: "Confirm it's you (password, authenticator code, or a code sent to your primary email), then retry.",
+    },
     site_already_deleted: {
         summary: "The site was already deleted.",
         fix: "No action is needed. The site is gone.",
@@ -1101,6 +1284,10 @@ export const ERROR_DOCS = {
         summary: "A space reference is required for this operation.",
         fix: "Pass a `spc_` id, slug, or hostname.",
     },
+    space_selection_conflict: {
+        summary: "The command asked to create a Space while this directory already selects one.",
+        fix: "Drop --slug to publish to the selected Space, or publish from an unlinked directory to create a new one.",
+    },
     space_transferring: {
         summary: "The space has a transfer in progress, which blocks this operation.",
         fix: "Complete or cancel the transfer first.",
@@ -1177,10 +1364,26 @@ export const ERROR_DOCS = {
         summary: "The billing provider reported an error.",
         fix: "Retry. If the error persists, check the team's billing settings.",
     },
+    superadmin_two_factor_required: {
+        summary: "The user must have two-factor authentication enrolled before being granted superadmin.",
+        fix: "Ask them to enrol a second factor in account security, then grant the role again.",
+    },
+    superadmin_wpcom_account_required: {
+        summary: "The user must have a WordPress.com account linked before being granted superadmin.",
+        fix: "Ask them to link WordPress.com in account security, then grant the role again.",
+    },
     superseded_by_publish: {
         summary: "A newer publish superseded this operation, so it was skipped.",
         fix: "No action is needed. The newer publish already carries the change.",
     },
+    system_space_conflict: {
+        summary: "The tenant's system space changed since the value you sent as `baseSystemSpaceId`, so the update was rejected.",
+        fix: "Re-read `/v1/tenants/{tenantId}`, confirm the current `systemSpaceId`, and retry with a matching `baseSystemSpaceId`.",
+    },
+    system_space_invalid: {
+        summary: "The requested system space does not exist, is disabled, or belongs to another tenant.",
+        fix: "Designate a live space this tenant owns as its system space.",
+    },
     takeover_notice_window: {
         summary: "The hostname was recently bound elsewhere. A takeover notice window applies.",
         fix: "Retry after the notice window, or have the current holder release the binding.",
@@ -1197,6 +1400,10 @@ export const ERROR_DOCS = {
         summary: "This operation requires an acting team.",
         fix: "Choose a team or pass a team reference.",
     },
+    team_scope_mismatch: {
+        summary: "The requested team conflicts with the team this credential or resource is bound to.",
+        fix: "Drop the team parameter to act on the bound team, or use a credential for the team you named.",
+    },
     team_slug_conflict: {
         summary: "The team slug is already taken.",
         fix: "Choose a different slug.",
@@ -1249,6 +1456,42 @@ export const ERROR_DOCS = {
         summary: "A theme value in the configuration is outside the allowed grammar.",
         fix: "Use allowed CSS values. Otherwise the offending key is dropped with a warning.",
     },
+    token_alg_invalid: {
+        summary: "The partner token uses a signing algorithm that Spacefast does not allow.",
+        fix: "Sign the token with a registered Ed25519 key.",
+    },
+    token_audience_mismatch: {
+        summary: "The partner token audience does not match the audience for its issuer.",
+        fix: "Set aud to the exact audience that Spacefast assigned to the issuer.",
+    },
+    token_claims_invalid: {
+        summary: "The partner token omits a required claim or contains an invalid claim value.",
+        fix: "Add valid iss, aud, sub, client_id, jti, iat, and exp claims.",
+    },
+    token_header_forbidden: {
+        summary: "The partner token contains a header that can select an untrusted key.",
+        fix: "Remove jku, x5u, jwk, and x5c from the token header.",
+    },
+    token_malformed: {
+        summary: "The partner token is not a valid compact JWT within the size limit.",
+        fix: "Send a valid compact JWT that is no larger than 8192 bytes.",
+    },
+    token_signature_invalid: {
+        summary: "The partner token signature does not match a registered issuer key.",
+        fix: "Sign the token with an active key that is registered for the issuer.",
+    },
+    token_subject_invalid: {
+        summary: "The partner token subject is not a normalized lowercase external principal id.",
+        fix: "Use a trimmed lowercase ASCII subject without wildcards, slashes, or reserved policy characters.",
+    },
+    token_ttl_invalid: {
+        summary: "The partner token time claims are expired, premature, or outside the lifetime limit.",
+        fix: "Issue a new token with exp after iat and no more than 1800 seconds after iat.",
+    },
+    token_type_invalid: {
+        summary: "The partner token has a typ header that Spacefast does not accept.",
+        fix: "Set typ to at+jwt or application/at+jwt.",
+    },
     transfer_cross_tenant_unsupported: {
         summary: "Spaces cannot be transferred across tenants.",
         fix: "Export the space and import it under the target tenant instead.",
@@ -1297,6 +1540,10 @@ export const ERROR_DOCS = {
         summary: "An uploaded file's size does not match the declared size.",
         fix: "Re-check the local file and upload it again.",
     },
+    usage_period_not_found: {
+        summary: "The requested usage period does not exist in this tenant.",
+        fix: "List usage periods and use an id returned for the selected tenant.",
+    },
     user_banned: {
         summary: "This user is banned for a policy or abuse violation and cannot perform this action.",
         fix: "If you believe the ban is a mistake, contact support to appeal it.",
@@ -1397,6 +1644,10 @@ export const ERROR_DOCS = {
         summary: "The webhook exhausted its delivery budget and was paused.",
         fix: "Fix the receiving endpoint, then redeliver or re-enable the webhook.",
     },
+    webhook_managed_by_manifest: {
+        summary: "The webhook is declared in the tenant's system-space manifest.",
+        fix: "Edit its `system.subscriptions` entry and publish the system space.",
+    },
     whois_unavailable: {
         summary: "WHOIS data is unavailable for this domain right now.",
         fix: "Retry later.",
@@ -1637,10 +1888,18 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoints payload exceeds the supported endpoint count.",
         fix: "Reduce the project to at most 128 Zero endpoints, then publish again.",
     },
+    zero_email_unavailable: {
+        summary: "The local Zero email service is not configured.",
+        fix: "Publish the capsule to call the hosted email service, or guard the `ctx.email` call so local runs skip it.",
+    },
     zero_envelope_encode_failed: {
         summary: "The PHP bridge cannot encode the Zero runner request envelope.",
         fix: "Retry with valid request data. If the issue persists, report it.",
     },
+    zero_gravatar_unavailable: {
+        summary: "The local Zero gravatar service is not configured.",
+        fix: "Publish the capsule to call the hosted gravatar service. `ctx.gravatar.avatarUrl` needs no service and works locally.",
+    },
     zero_js_context_init_failed: {
         summary: "The Zero runner cannot initialize a QuickJS context.",
         fix: "Retry or rebuild the runner. Report persistent runtime initialization failures.",
@@ -1715,7 +1974,7 @@ export const ERROR_DOCS = {
     },
     zero_replay_query_invalid: {
         summary: "The hosted Zero realtime replay query is invalid.",
-        fix: "Use a valid `afterEventId` cursor and numeric limit.",
+        fix: "Send a retained `afterEventId` from a previous page's `nextAfterEventId`, and a numeric limit.",
     },
     zero_replay_unavailable: {
         summary: "Realtime replay is not configured for this Zero version.",
@@ -1797,6 +2056,10 @@ export const ERROR_DOCS = {
         summary: "The Zero runner process cannot be started.",
         fix: "Verify the runner binary is installed and executable in the runtime.",
     },
+    zero_spam_unavailable: {
+        summary: "The local Zero spam service is not configured.",
+        fix: "Publish the capsule to call the hosted spam service, or guard the `ctx.spam` call so local runs skip it.",
+    },
     zero_runs_invalid: {
         summary: "The Zero run-handler payload is invalid.",
         fix: "Send a valid array of generated run handlers and publish again.",
@@ -1841,6 +2104,8 @@ export const ERROR_DOCS = {
         summary: "The infra webhook secret is not configured on this deployment.",
         fix: "Set the infra webhook secret in the control-plane environment.",
     },
+    // `satisfies`, not an annotation, so the table keeps its literal types while
+    // still failing the build the moment a code has no entry.
 };
 const PRODUCT = BRAND.productName;
 /** One generated reference page per error code; the `.md` twin is this exact text. */

package/dist/docs/index-build.d.ts

@@ -9,7 +9,6 @@ export interface DocIndexEntry extends DocEntry {
 /** The bundled, generated docs index. */
 export interface DocsIndex {
     readonly version: typeof DOCS_INDEX_VERSION;
-    /** Provenance marker so a reader knows the artifact is generated. */
     readonly generatedFrom: string;
     readonly entries: readonly DocIndexEntry[];
 }

package/dist/docs/index-build.js

@@ -1,7 +1,6 @@
 // Pure transform from the curated docs catalog (catalog.ts) to a search index.
-// Both the CLI's generator script and its drift-guard test call buildDocsIndex,
-// and the control-plane builds the same index in memory for GET /v1/docs, so the
-// served index, the bundled artifact, and the source can never silently diverge.
+// The CLI's generator, its drift-guard test, and the control-plane's
+// GET /v1/docs all call buildDocsIndex, so they cannot silently diverge.
 import { DOCS_CATALOG } from "./catalog.js";
 /** Current on-disk index schema version; bump when the shape changes. */
 export const DOCS_INDEX_VERSION = 1;

package/dist/docs/page-context-prompt.d.ts

@@ -0,0 +1,77 @@
+export type PageContextPromptInput = {
+    readonly page: {
+        readonly title: string;
+        readonly url: string;
+        readonly description?: string;
+    };
+    /**
+     * Live state of the resource the page is about: which space, whether its
+     * repository is connected, where it serves. This is what makes a builds brief
+     * about *this* space's builds rather than about builds in general, so it is
+     * rendered above the references an agent would use to act on it.
+     */
+    readonly facts?: {
+        readonly title: string;
+        readonly items: readonly {
+            readonly label: string;
+            readonly value: string;
+        }[];
+    };
+    readonly docs: readonly {
+        readonly title: string;
+        readonly url: string;
+    }[];
+    readonly operations: readonly {
+        readonly method: string;
+        readonly path: string;
+        readonly summary: string;
+        /**
+         * The operation's page in the API reference, which is also where its
+         * parameters and request/response schemas are rendered. Derived from the
+         * operation's id and tag (`apiOperationDocsUrl`), never written by hand.
+         */
+        readonly docsUrl?: string;
+    }[];
+    /**
+     * Real invocations, e.g. `sf builds ls --space lunar-sitemap --json`, derived
+     * from the oclif manifest's own examples with the current space substituted.
+     * `docsUrl` deep-links to that command's section of the CLI reference.
+     */
+    readonly cli: readonly {
+        readonly command: string;
+        readonly summary?: string;
+        readonly docsUrl?: string;
+    }[];
+    /** Include the short hosted-MCP pointer. */
+    readonly mcp?: boolean;
+    readonly form?: {
+        readonly surface: string;
+        readonly values: Readonly<Record<string, string | number | boolean | readonly string[]>>;
+    };
+};
+/** Builds the copy-ready markdown prompt for one dashboard page. Pure: same input, same bytes. */
+export declare function buildPageContextPrompt(input: PageContextPromptInput): string;
+/**
+ * Adds one private exchange to the safe page brief. The caller must send this
+ * result only to the clipboard. The private URL must not enter a rendered node,
+ * a query string, a log, or a cache key.
+ *
+ * The wording is calibrated on fresh-agent evals. First person — the user is
+ * the one pasting it, so the user is speaking. It says what the link is BEFORE
+ * asking for the fetch, because an unexplained "fetch this and obey it" reads
+ * as a phishing template to a careful agent. And it names the right mechanics:
+ * the naive `curl <url>` puts the bearer in argv and shell history, so the
+ * prompt says to use a URL-fetch tool.
+ */
+export declare function buildPrivatePageContextPrompt(input: {
+    context: string;
+    expiresAt: string;
+    handoffUrl: string;
+    targetLabel: string;
+    /**
+     * What to do once connected. The default closes the loop back to the page
+     * brief above; a caller with no page brief (the /start copy) supplies its
+     * own so the prompt never points at references that are not there.
+     */
+    closing?: string | undefined;
+}): string;