@spacefast/common 0.0.2

package/dist/docs/error-docs.js

@@ -0,0 +1,1601 @@
+// Error reference content (internal-docs/platform.md "Global API Conventions"):
+// every error envelope `docsUrl` 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. apps/www renders the HTML pages and writes the
+// `.md` twins from the same entries.
+import { BRAND } from "../brand.js";
+import { ERROR_CODES, errorDocsUrl } from "../contracts/error-codes.js";
+export const ERROR_DOCS = {
+    abuse_report_invalid_transition: {
+        summary: "The abuse report cannot move to the requested status from its current status.",
+        fix: "Fetch the report to see its current status and apply a valid transition.",
+    },
+    account_suspended: {
+        summary: "This account is suspended for a policy or abuse violation and cannot be used.",
+        fix: "Contact support to review the suspension if you believe it is a mistake.",
+    },
+    abuse_report_rate_limited: {
+        summary: "Too many abuse reports were submitted from this client in a short window.",
+        fix: "Wait for the window in the Retry-After header to pass before reporting again.",
+    },
+    abuse_takedown: {
+        summary: "This space was disabled by an abuse takedown and cannot be served or modified.",
+        fix: "If you believe this is a mistake, contact support with the space id.",
+    },
+    access_denied: {
+        summary: "The authorization request was denied by the user.",
+        fix: "Restart the login flow and approve the request to continue.",
+    },
+    ambiguous_space_slug: {
+        summary: "The slug matches spaces in more than one of your teams, so it cannot be resolved.",
+        fix: "Pass a teamRef alongside the slug, or reference the space by its spc_ id.",
+    },
+    anonymous_expired: {
+        summary: "This anonymous space expired before it was claimed.",
+        fix: "Publish again to get a fresh space, or claim spaces before their expiry next time.",
+    },
+    anonymous_pool_unavailable: {
+        summary: "No pooled capacity is available for anonymous publishes right now.",
+        fix: "Retry shortly; capacity replenishes automatically.",
+    },
+    anonymous_publish_rate_limited: {
+        summary: "Too many anonymous publishes came from this network in a short window.",
+        fix: "Wait for the window to pass, or sign in with an API key for higher limits.",
+    },
+    archive_body_required: {
+        summary: "This request must carry an archive body but none was provided.",
+        fix: "Send the zip bytes as the request body with the matching content-type header.",
+    },
+    archive_too_large: {
+        summary: "The uploaded archive exceeds the maximum allowed size.",
+        fix: "Reduce the archive size or upload files individually through a version upload session.",
+    },
+    auth_code_required: {
+        summary: "An authorization code is required to complete this step.",
+        fix: "Pass the code returned by the authorization step.",
+    },
+    authorization_pending: {
+        summary: "The device login has not been approved yet.",
+        fix: "Keep polling at the advised interval until the user approves the request.",
+    },
+    billing_receipt_invalid: {
+        summary: "The store receipt or notification could not be verified with the payment provider.",
+        fix: "Re-check the transaction id or purchase token and retry; contact support if it persists.",
+    },
+    billing_receipt_not_bound_to_team: {
+        summary: "The store purchase was made under a different account token than this team's.",
+        fix: "Verify the purchase from the team that initiated it, or contact support to rebind it.",
+    },
+    billing_store_not_configured: {
+        summary: "App Store or Google Play billing is not configured on this deployment.",
+        fix: "Use another billing method, or configure the store credentials on the server.",
+    },
+    billing_subscription_conflict: {
+        summary: "The team already has an active subscription with another payment provider.",
+        fix: "Cancel the existing subscription before subscribing through a different provider.",
+    },
+    billing_unknown_product: {
+        summary: "The purchased store product does not map to any plan sold by this deployment.",
+        fix: "Check the product id against the store catalog returned by the billing endpoints.",
+    },
+    build_command_missing: {
+        summary: "A build or install command could not be found during the build run.",
+        fix: "Check the command spelling and ensure its tool is declared in package.json or available in the build image.",
+    },
+    build_execution_unavailable: {
+        summary: "Build execution is not available on this deployment.",
+        fix: "Publish prebuilt static output instead, or wait for builds to become available.",
+    },
+    build_failed: {
+        summary: "The build run failed before producing a version.",
+        fix: "Inspect the build logs, fix the failure, and start a new build.",
+    },
+    build_install_failed: {
+        summary: "The dependency install step failed during the build run.",
+        fix: "Inspect the build logs for the install error, fix the lockfile or install command, and start a new build.",
+    },
+    build_no_index_html: {
+        summary: "The build produced output but no index.html at the site root.",
+        fix: "Make sure your build writes an index.html to the output directory, or point the output directory at the folder that contains it.",
+    },
+    build_not_created: {
+        summary: "The build could not be created.",
+        fix: "Verify the build request payload and retry.",
+    },
+    build_oom: {
+        summary: "The build process was killed, most likely after running out of memory.",
+        fix: "Reduce the build's memory usage or concurrency, then start a new build.",
+    },
+    build_output_dir_missing: {
+        summary: "The build finished but its output directory was not produced.",
+        fix: "Point the output directory setting at the folder your build writes (for example dist, build, out, or public).",
+    },
+    build_timeout: {
+        summary: "The build exceeded its time limit before producing a version.",
+        fix: "Speed up the build or raise the build timeout in the build settings, then start a new build.",
+    },
+    cache_purge_domain_required: {
+        summary: "A purge request must name the domain to purge.",
+        fix: "Pass the domain to purge in the request.",
+    },
+    cache_purge_path_required: {
+        summary: "A purge request must name at least one path.",
+        fix: "Pass one or more request paths to purge.",
+    },
+    channel_name_reserved: {
+        summary: "The channel name collides with a reserved hostname suffix and cannot be used.",
+        fix: "Choose a different channel name; v-prefixed numeric names and ver- prefixes are reserved.",
+    },
+    channel_pointer_moved: {
+        summary: "The channel was promoted to a different version since you read it.",
+        fix: "Re-read the channel pointer and retry the promote with the current version id.",
+    },
+    channel_unsupported: {
+        summary: "This space does not support the requested channel.",
+        fix: "Use the live channel, or create the channel before promoting to it.",
+    },
+    claim_blocked_takedown: {
+        summary: "This space is under an abuse takedown and cannot be claimed.",
+        fix: "Contact support if you believe the takedown is a mistake.",
+    },
+    claim_target_not_found: {
+        summary: "The team or account to claim the space into was not found.",
+        fix: "Verify the claim target and that your credential can act for it.",
+    },
+    claimed_space_quota_exceeded: {
+        summary: "Claiming this space would exceed the target team's space quota.",
+        fix: "Delete unused spaces or upgrade the plan, then claim again.",
+    },
+    cli_upgrade_required: {
+        summary: "This CLI version is too old to talk to the API safely.",
+        fix: "Upgrade the CLI to the latest release and retry.",
+    },
+    config_file_too_large: {
+        summary: "The sf.jsonc configuration file exceeds the maximum size.",
+        fix: "Keep the configuration file under the documented size limit (256 KB).",
+    },
+    config_invalid: {
+        summary: "The space configuration failed validation.",
+        fix: "Fix the reported fields against the published schema at /schemas/sf.json.",
+    },
+    config_meta_too_long: {
+        summary: "A meta field in the space configuration exceeds its maximum length.",
+        fix: "Shorten the meta title, description, or other reported field.",
+    },
+    config_templates_over_limit: {
+        summary: "The configuration declares more template files than the plan allows.",
+        fix: "Reduce the number of template entries in sf.jsonc.",
+    },
+    credential_expired: {
+        summary: "The credential used for this request has expired.",
+        fix: "Create a new API key or sign in again.",
+    },
+    credential_not_yet_valid: {
+        summary: "The credential is not valid yet because its start time is in the future.",
+        fix: "Wait until the credential's notBefore time, or adjust it.",
+    },
+    credential_retired: {
+        summary: "This request used a retired Spacefast token format or authentication header.",
+        fix: "Run sf login again and send the new sfa_ key as Authorization: Bearer.",
+    },
+    credential_revoked: {
+        summary: "The credential used for this request was revoked.",
+        fix: "Create a new API key and update your client.",
+    },
+    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.",
+    },
+    csam_policy_floor: {
+        summary: "CSAM enforcement policy cannot be set below the mandatory account-suspend floor.",
+        fix: "Set the CSAM category enforcement tier to account suspension.",
+    },
+    data_location_immutable: {
+        summary: "A space's data location cannot be changed after placement.",
+        fix: "Create a new space in the desired region and transfer content into it.",
+    },
+    device_authorization_failed: {
+        summary: "The device login request failed and cannot be completed.",
+        fix: "Start a new device login flow.",
+    },
+    device_verification_rate_limited: {
+        summary: "Too many incorrect device codes were entered in a short window.",
+        fix: "Wait for the lockout to pass, then enter the code shown by your CLI exactly.",
+    },
+    dns_export_required: {
+        summary: "This operation requires exporting the current DNS records first.",
+        fix: "Export the zone, confirm the snapshot, and retry the operation.",
+    },
+    dns_field_conflict: {
+        summary: "Two DNS fields cannot be used together for this provider or record type.",
+        fix: "Follow the capability rule in the error details and submit only the compatible fields.",
+    },
+    dns_import_partial_visibility: {
+        summary: "The DNS import could not see the full zone, so importing would lose records.",
+        fix: "Verify delegation and retry once the full zone is visible.",
+    },
+    dns_provider_auth_expired: {
+        summary: "The connected DNS provider authorization expired or was revoked.",
+        fix: "Reconnect the provider account for the affected connection, refresh the zone, then retry the DNS operation.",
+    },
+    dns_provider_batch_unsupported: {
+        summary: "The connected DNS provider cannot apply this batch with the required semantics.",
+        fix: "Split the change or use a provider/zone that supports atomic batch writes.",
+    },
+    dns_provider_change_pending: {
+        summary: "The DNS provider accepted the change but propagation or provider completion is still pending.",
+        fix: "Wait and re-check the pollable DNS operation before submitting another conflicting change.",
+    },
+    dns_provider_connection_in_use: {
+        summary: "The DNS provider connection is still attached to one or more zones.",
+        fix: "Detach or migrate attached zones before revoking the connection.",
+    },
+    dns_provider_connection_unavailable: {
+        summary: "The DNS provider connection cannot currently be used.",
+        fix: "Reconnect, re-enable, or replace the provider connection before retrying.",
+    },
+    dns_provider_conflict: {
+        summary: "The DNS provider rejected the change because it conflicts with existing provider state.",
+        fix: "Refresh the provider snapshot, resolve the conflicting record or setting, and retry.",
+    },
+    dns_provider_controlled_desired_state: {
+        summary: "This DNS provider is controlled through desired-state templates instead of direct record edits.",
+        fix: "Use the provider workflow template or primary-domain action for this provider-managed zone.",
+    },
+    dns_provider_credentials_expired: {
+        summary: "The DNS provider credentials have expired or were revoked.",
+        fix: "Reconnect the provider account or replace the API token.",
+    },
+    dns_provider_feature_descriptors: {
+        summary: "This provider exposes domain features through capability descriptors.",
+        fix: "Render and run the advertised feature action instead of assuming a raw DNS record change.",
+    },
+    dns_provider_feature_unavailable: {
+        summary: "The requested DNS provider field or feature is not available for this zone.",
+        fix: "Check the DNS capabilities response and remove unsupported fields.",
+    },
+    dns_provider_field_unsupported: {
+        summary: "The DNS provider does not support one of the requested record fields.",
+        fix: "Remove the unsupported field or switch to a provider and plan whose capabilities allow it.",
+    },
+    dns_provider_future_authoritative_backend: {
+        summary: `This domain uses a future ${BRAND.productName} authoritative DNS backend adapter.`,
+        fix: "Use the provider-neutral DNS endpoints and rely on the advertised capabilities for supported actions.",
+    },
+    dns_field_not_applicable: {
+        summary: "The DNS field is not writable for this provider, record type, or management mode.",
+        fix: "Check the DNS capabilities response and remove fields that are not creatable or patchable.",
+    },
+    dns_provider_missing_permission: {
+        summary: "The connected DNS provider account lacks the required permission.",
+        fix: "Reconnect with the required scope or use a provider credential that can edit this zone.",
+    },
+    dns_provider_not_connected: {
+        summary: "This domain has no connected DNS provider zone.",
+        fix: `Attach a provider zone or move the domain to ${BRAND.productName}-managed DNS before retrying.`,
+    },
+    dns_provider_operation_failed: {
+        summary: "The DNS provider operation failed before the requested change was accepted.",
+        fix: "Open the DNS operation details, follow its diagnostics, and retry only after the failing cause is resolved.",
+    },
+    dns_provider_permission_denied: {
+        summary: "The connected DNS provider denied permission for this zone or action.",
+        fix: "Grant DNS edit access for this zone, reconnect with broader scopes, or connect a different provider account.",
+    },
+    dns_provider_rate_limited: {
+        summary: "The DNS provider rate-limited the requested operation.",
+        fix: "Wait for the retry window in the error details, then retry.",
+    },
+    dns_provider_replace_all_requires_fresh_plan: {
+        summary: "This provider requires a fresh full-zone plan before replacing DNS records.",
+        fix: "Refresh the provider snapshot, review the replace-all plan, then run the action from that fresh plan.",
+    },
+    dns_provider_replace_all_write_strategy: {
+        summary: "This provider applies DNS changes with a replace-all write strategy.",
+        fix: "Review the full-zone diff carefully so unrelated MX, TXT, CAA, NS, and wildcard records are preserved.",
+    },
+    dns_provider_snapshot_stale: {
+        summary: "The cached DNS provider snapshot is stale.",
+        fix: "Refresh the provider snapshot, review the new diff, and retry the change against the latest record ids.",
+    },
+    dns_provider_snapshot_unavailable: {
+        summary: `${BRAND.productName} could not cache the latest DNS provider snapshot.`,
+        fix: "Retry refresh after the cache or provider recovers; do not edit connected-provider records from stale data.",
+    },
+    dns_provider_temporarily_unavailable: {
+        summary: "The DNS provider is rate-limited, degraded, or temporarily unavailable.",
+        fix: "Wait for the retry time in the error details or operation receipt, then retry the DNS operation.",
+    },
+    dns_provider_timeout: {
+        summary: "The DNS provider did not accept the change within the bounded wait.",
+        fix: "Check the operation status before retrying to avoid duplicate changes.",
+    },
+    dns_provider_validation_failed: {
+        summary: "The DNS provider rejected the submitted record data.",
+        fix: "Use the field details and provider message to correct the record.",
+    },
+    dns_provider_workflow_templates: {
+        summary: "This provider exposes setup through workflow templates instead of low-level DNS edits.",
+        fix: "Preview and run the advertised template so provider-specific side effects and receipts are captured.",
+    },
+    dns_provider_zone_not_found: {
+        summary: "The connected DNS provider zone could not be found.",
+        fix: "Refresh the provider account, reattach the zone, or reconnect the provider.",
+    },
+    dns_record_conflicts_with_managed: {
+        summary: `The DNS change conflicts with a record ${BRAND.productName} manages for this domain.`,
+        fix: "Remove or adjust the conflicting record; managed records cannot be overridden.",
+    },
+    dns_record_managed: {
+        summary: `This DNS record is managed by ${BRAND.productName} and cannot be edited directly.`,
+        fix: "Change the binding or feature that owns the record instead of editing it.",
+    },
+    dns_record_not_found: {
+        summary: "The DNS record was not found in this zone.",
+        fix: "List the zone's records to confirm the record id.",
+    },
+    domain_already_exists: {
+        summary: "This domain is already present in your inventory.",
+        fix: "Use the existing domain record instead of adding it again.",
+    },
+    domain_bound: {
+        summary: "The domain is currently bound to a space, which blocks this operation.",
+        fix: "Remove the domain's bindings first, then retry.",
+    },
+    domain_facet_already_managed: {
+        summary: `This facet of the domain is already managed by ${BRAND.productName}.`,
+        fix: "No action is needed; the facet is already active.",
+    },
+    domain_facet_external: {
+        summary: `This facet of the domain is managed outside ${BRAND.productName}.`,
+        fix: `Manage that facet at its external provider, or move it to ${BRAND.productName} first.`,
+    },
+    domain_facet_not_applicable: {
+        summary: "The requested facet does not apply to this domain.",
+        fix: "Check the domain's facets and use one that applies.",
+    },
+    domain_hostname_site_mismatch: {
+        summary: "All bindings of one hostname must point at spaces on the same underlying site.",
+        fix: "Bind the hostname to spaces on the same site, or remove the conflicting binding.",
+    },
+    domain_in_use: {
+        summary: "The domain is in use by another binding or assignment.",
+        fix: "Remove the existing use of the domain before retrying.",
+    },
+    domain_lookup_rate_limited: {
+        summary: "Too many domain lookups were made in a short window.",
+        fix: "Wait for the window in the Retry-After header to pass before searching again.",
+    },
+    domain_not_bound: {
+        summary: "The domain is not bound to this space.",
+        fix: "Bind the domain to the space first.",
+    },
+    domain_quota_exceeded: {
+        summary: "Adding this domain would exceed the plan's external domain allowance.",
+        fix: "Remove unused domains or upgrade the plan.",
+    },
+    domain_registration_active: {
+        summary: "The domain has an active registration, which blocks this operation.",
+        fix: "Wait for or cancel the registration before retrying.",
+    },
+    domain_registration_not_renewable: {
+        summary: "The domain registration cannot be renewed right now.",
+        fix: "Check the registration status and renewal window for the domain.",
+    },
+    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} default and management hostnames are assigned automatically.`,
+    },
+    domain_transfer_active: {
+        summary: "The domain has a transfer in progress, which blocks this operation.",
+        fix: "Wait for the transfer to finish or cancel it before retrying.",
+    },
+    domain_wildcard_label: {
+        summary: "The hostname uses a wildcard label in a position that is not allowed.",
+        fix: "Use a single leading wildcard (*.example.com) or a concrete hostname.",
+    },
+    domain_wildcard_not_enabled: {
+        summary: "Wildcard hostnames are not enabled for this domain or plan.",
+        fix: "Bind concrete hostnames, or enable wildcard support for the domain.",
+    },
+    download_required: {
+        summary: "This content is too large to return inline and must be downloaded.",
+        fix: "Use the download endpoint referenced in the error details.",
+    },
+    duplicate_version_path: {
+        summary: "The version upload declares the same file path twice.",
+        fix: "Deduplicate the file list so every path appears once.",
+    },
+    expired_token: {
+        summary: "The token has expired.",
+        fix: "Request a new token and retry.",
+    },
+    export_archive_not_ready: {
+        summary: "The export archive is still being prepared.",
+        fix: "Poll the export until its status is ready, then download the archive.",
+    },
+    export_version_not_found: {
+        summary: "The version requested for export was not found.",
+        fix: "List the space's versions and export an existing version id.",
+    },
+    feature_unavailable: {
+        summary: "This feature is not available on this deployment or plan.",
+        fix: "Check the feature's availability, or upgrade if it is plan-gated.",
+    },
+    files_mode_does_not_support_spa: {
+        summary: "SPA fallback cannot be combined with files-listing mode.",
+        fix: "Remove the SPA fallback or serve the space as a site instead of a file listing.",
+    },
+    forbidden: {
+        summary: "The credential is valid but does not allow this action.",
+        fix: "Use a credential whose policy grants this action on this resource.",
+    },
+    free_external_proxy_disabled: {
+        summary: "Proxy routes to external upstreams are not available on the Free plan.",
+        fix: "Remove the proxy rules or upgrade the plan to enable external proxying.",
+    },
+    free_headers_basic_auth_disabled: {
+        summary: "Basic-Auth via _headers is not available on the Free plan.",
+        fix: "Use space password protection, or upgrade the plan for _headers Basic Auth.",
+    },
+    idempotency_conflict_in_progress: {
+        summary: "Another request with the same Idempotency-Key is still in flight.",
+        fix: "Wait for the original request to finish; its response will be replayed.",
+    },
+    idempotency_key_reused: {
+        summary: "The Idempotency-Key was reused with a different request body.",
+        fix: "Use a fresh key for new requests; keys bind to one exact request body.",
+    },
+    immutable_version_requires_login: {
+        summary: "This immutable version URL is past its public window and now requires login.",
+        fix: "Sign in to view it, or promote the version to a channel for public serving.",
+    },
+    import_archive_not_uploaded: {
+        summary: "The import has no uploaded archive yet.",
+        fix: "Upload the archive to the import's upload target, then finalize.",
+    },
+    import_not_cancelable: {
+        summary: "The import has progressed past the point where it can be canceled.",
+        fix: "Wait for the import to finish; completed imports can be deleted as versions.",
+    },
+    import_not_waiting_for_archive: {
+        summary: "The import is not waiting for an archive upload.",
+        fix: "Check the import status; the archive step may already be complete.",
+    },
+    incumbent_controls_dns: {
+        summary: "Another team controls this domain's DNS, so the operation is blocked.",
+        fix: "Prove control by completing domain verification, or coordinate with the incumbent.",
+    },
+    inject_invalid: {
+        summary: "The inject config key is malformed.",
+        fix: "Make inject an object whose head/bodyStart/bodyEnd/noscript entries are arrays of up to 16 strings.",
+    },
+    inject_snippet_too_large: {
+        summary: "An inject snippet exceeds the per-snippet size limit.",
+        fix: "Keep each inject snippet at or under 8 KB.",
+    },
+    internal_error: {
+        summary: "Something went wrong on our side.",
+        fix: "Retry the request; if it persists, contact support with the requestId.",
+    },
+    invalid_claim_token: {
+        summary: "The claim token is invalid or does not match this space.",
+        fix: "Use the exact claim URL returned by the publish that created the space.",
+    },
+    invalid_data_location: {
+        summary: "The requested data location is not a supported region.",
+        fix: "Pick a region from the documented data locations, or use auto.",
+    },
+    invalid_device_code: {
+        summary: "The device code is invalid or has expired.",
+        fix: "Start a new device login flow.",
+    },
+    invalid_domain: {
+        summary: "The domain reference is invalid.",
+        fix: "Pass a valid domain id or name.",
+    },
+    invalid_domain_name: {
+        summary: "The domain name is not a valid registrable hostname.",
+        fix: "Check the spelling and use a fully-qualified domain name.",
+    },
+    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.",
+    },
+    invalid_grant: {
+        summary: "The authorization grant is invalid or was already used.",
+        fix: "Restart the login flow to obtain a new grant.",
+    },
+    invalid_publish_archive: {
+        summary: "The uploaded archive could not be read as a valid zip.",
+        fix: "Re-create the archive as a standard zip and upload again.",
+    },
+    invalid_publish_path: {
+        summary: "A file path in the publish payload is not allowed.",
+        fix: "Use forward-slash relative paths without traversal or control characters.",
+    },
+    invalid_publish_payload: {
+        summary: "The publish payload is malformed.",
+        fix: "Check the request against the publish schema in the API docs.",
+    },
+    invalid_request: {
+        summary: "The request is malformed.",
+        fix: "Fix the field referenced by param and details, then retry.",
+    },
+    invalid_runtime_event: {
+        summary: "The runtime event payload is not recognized.",
+        fix: "Verify the event shape matches the runtime callback contract.",
+    },
+    invalid_space: {
+        summary: "The space reference is invalid.",
+        fix: "Pass a valid spc_ id, slug, or hostname.",
+    },
+    invalid_space_mode: {
+        summary: "The requested space serving mode is not supported.",
+        fix: "Use a supported serving configuration.",
+    },
+    invalid_user_code: {
+        summary: "The user code does not match a pending device login.",
+        fix: "Enter the code exactly as shown by your CLI; codes expire after a few minutes.",
+    },
+    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.",
+    },
+    invalid_webhook_events: {
+        summary: "One or more webhook event codes are not in the event taxonomy.",
+        fix: "Subscribe only to documented activity event codes.",
+    },
+    invalid_webhook_payload: {
+        summary: "The webhook configuration payload is malformed.",
+        fix: "Fix the field referenced by param and retry.",
+    },
+    invalid_webhook_signature: {
+        summary: "The webhook signature did not verify.",
+        fix: "Verify with the current webhook secret over `{t}.{rawBody}` and reject stale timestamps.",
+    },
+    invalid_webhook_url: {
+        summary: "The webhook URL is not an allowed public HTTPS endpoint.",
+        fix: "Use a public HTTPS URL; private networks and link-local addresses are blocked.",
+    },
+    invalid_zero_realtime_event: {
+        summary: "The Zero realtime event payload is malformed or scoped to the wrong space.",
+        fix: "Send a valid Zero realtime event for the space in the request path.",
+    },
+    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.",
+    },
+    invitation_already_exists: {
+        summary: "An invitation for this email already exists on the team.",
+        fix: "Resend the existing invitation instead of creating a new one.",
+    },
+    invitation_not_pending: {
+        summary: "The invitation is no longer pending.",
+        fix: "Create a new invitation if the member still needs to join.",
+    },
+    ip_blocked: {
+        summary: "Requests from this IP address are blocked for abuse or policy reasons.",
+        fix: "Contact support with your IP address if you believe this block is in error.",
+    },
+    job_not_found: {
+        summary: "The background job was not found.",
+        fix: "Verify the job id; completed jobs are eventually pruned.",
+    },
+    job_not_promotable: {
+        summary: "The job cannot be promoted in its current state.",
+        fix: "Only delayed jobs can be promoted to run immediately.",
+    },
+    job_not_removable: {
+        summary: "The job cannot be removed in its current state.",
+        fix: "Wait for the job to settle before removing it.",
+    },
+    job_not_retryable: {
+        summary: "The job cannot be retried in its current state.",
+        fix: "Only failed jobs can be retried.",
+    },
+    last_owner: {
+        summary: "The last owner of a team cannot be removed or downgraded.",
+        fix: "Promote another member to owner first.",
+    },
+    log_retention_clamped: {
+        summary: "The requested log range exceeds the plan's retention and was clamped.",
+        fix: "Narrow the range, or upgrade the plan for longer retention.",
+    },
+    lost_domain_control: {
+        summary: `${BRAND.productName} no longer observes DNS control for this domain.`,
+        fix: "Restore the documented DNS records, then re-run domain verification.",
+    },
+    malware_detected: {
+        summary: "Malware was detected in the uploaded content.",
+        fix: "Remove the flagged files; contact support if you believe this is a false positive.",
+    },
+    managed_domain_protected: {
+        summary: "This is a system-managed view.fast hostname and cannot be mutated like a custom domain.",
+        fix: "Use it as a read-only managed hostname, or add a custom domain if you need editable DNS and binding controls.",
+    },
+    manifest_body_too_large: {
+        summary: "The upload manifest body exceeds the maximum size.",
+        fix: "Keep the manifest under 16 MB; split very large publishes into batches.",
+    },
+    manifest_duplicate_path: {
+        summary: "The upload manifest declares the same path more than once.",
+        fix: "Deduplicate paths; comparisons use the canonical (decoded, NFC) form.",
+    },
+    manifest_too_many_files: {
+        summary: "The upload manifest declares more files than the allowed ceiling.",
+        fix: "Reduce the file count or split content across multiple spaces.",
+    },
+    member_already_exists: {
+        summary: "This user is already a member of the team.",
+        fix: "Update the existing member's role instead of inviting again.",
+    },
+    missing_route_param: {
+        summary: "A required route parameter is missing from the request path.",
+        fix: "Check the endpoint path in the API reference and include every parameter.",
+    },
+    nameserver_delegation_required: {
+        summary: `This operation requires the domain to be delegated to ${BRAND.productName} nameservers.`,
+        fix: "Update the domain's nameservers at the registrar, then retry once delegation propagates.",
+    },
+    nameserver_divergence: {
+        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.",
+    },
+    noop_publish: {
+        summary: "The publish matched the live version exactly, so nothing changed.",
+        fix: "No action needed; the existing live version already serves this content.",
+    },
+    not_enrolled: {
+        summary: "This account is not enrolled in the private beta, so the API cannot be used yet.",
+        fix: "Join the waitlist or open your beta invite link, then sign in again.",
+    },
+    not_found: {
+        summary: "The requested resource was not found.",
+        fix: "Verify the id and that your credential can access the resource.",
+    },
+    path_case_collision: {
+        summary: "Two file paths differ only by letter case, which collides on serving.",
+        fix: "Rename one of the files so paths are unique case-insensitively.",
+    },
+    path_too_long: {
+        summary: "A file path exceeds the maximum length.",
+        fix: "Keep each file path at or under 1024 bytes.",
+    },
+    plan_grant_already_active: {
+        summary: "The team already holds an active operator grant for this plan.",
+        fix: "Revoke the existing grant first, or grant a different plan.",
+    },
+    plan_grant_already_revoked: {
+        summary: "This plan grant was already revoked.",
+        fix: "Nothing to do; create a new grant if the team should regain the plan.",
+    },
+    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.",
+    },
+    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.",
+    },
+    provider_error: {
+        summary: "The hosting provider reported an error.",
+        fix: "Retry; if the error persists, contact support with the requestId.",
+    },
+    provider_job_failed: {
+        summary: "A hosting-provider job failed while processing this operation.",
+        fix: "Retry the operation; if it keeps failing, contact support with the operation id.",
+    },
+    provider_job_timeout: {
+        summary: "A hosting-provider job timed out while processing this operation.",
+        fix: "Retry the operation; the provider may be slow right now.",
+    },
+    provider_runtime_feature_unsupported: {
+        summary: "The hosting provider does not support this runtime feature.",
+        fix: "Check the feature's availability for this site's runtime.",
+    },
+    provider_site_id_required: {
+        summary: "A provider site id is required for this internal operation.",
+        fix: "Pass the provider site reference.",
+    },
+    proxy_upstream_denied: {
+        summary: "The proxy upstream is on a denied network and cannot be used.",
+        fix: "Proxy only to public HTTPS upstreams; private and internal addresses are blocked.",
+    },
+    proxy_upstream_unresolved: {
+        summary: "The proxy upstream hostname could not be resolved.",
+        fix: "Verify the upstream DNS name resolves publicly, then publish again.",
+    },
+    publish_archive_compression_ratio_exceeded: {
+        summary: "The archive's compression ratio is suspiciously high and was rejected.",
+        fix: "Repackage the content without highly-compressible filler data.",
+    },
+    publish_archive_expanded_size_exceeded: {
+        summary: "The archive expands beyond the maximum allowed total size.",
+        fix: "Reduce the content size or upgrade the plan for higher limits.",
+    },
+    publish_archive_file_count_exceeded: {
+        summary: "The archive contains more files than the allowed ceiling.",
+        fix: "Reduce the file count or split content across multiple spaces.",
+    },
+    publish_archive_too_large: {
+        summary: "The uploaded archive exceeds the maximum allowed size.",
+        fix: "Reduce the archive size or use a version upload session for big publishes.",
+    },
+    publish_config_unsupported: {
+        summary: "The publish carries configuration this endpoint does not support.",
+        fix: "Move the configuration into sf.jsonc or the space settings.",
+    },
+    publish_failed: {
+        summary: "The publish failed before going live.",
+        fix: "Check the version diagnostics for the cause, then publish again.",
+    },
+    publish_file_missing: {
+        summary: "A declared file was never uploaded, so the publish cannot finalize.",
+        fix: "Upload every declared file, or resume the upload session to see what is missing.",
+    },
+    publish_setup_failed: {
+        summary: "Provisioning for this publish failed.",
+        fix: "Retry the publish; if it persists, contact support with the requestId.",
+    },
+    publish_upload_failed: {
+        summary: "Uploading the publish content failed.",
+        fix: "Retry the publish; partial uploads are resumable through the upload session.",
+    },
+    publish_verification_failed: {
+        summary: "Post-publish verification did not see the new content serving.",
+        fix: "Retry; if the space still serves stale content, contact support.",
+    },
+    queue_not_found: {
+        summary: "The named job queue does not exist.",
+        fix: "Check the queue name against the operator queue list.",
+    },
+    rate_limited: {
+        summary: "Too many requests were made in a short window.",
+        fix: "Wait for the window in the Retry-After header to pass, then retry.",
+    },
+    registration_expired: {
+        summary: "The domain registration has expired.",
+        fix: "Renew the domain at its registrar before retrying.",
+    },
+    registration_expiring: {
+        summary: "The domain registration is about to expire, which blocks this operation.",
+        fix: "Renew the domain first, then retry.",
+    },
+    routing_rules_over_plan: {
+        summary: "The published _redirects and _headers exceed the plan's routing-rule allowance.",
+        fix: "Reduce the rule count or upgrade the plan.",
+    },
+    runtime_action_forbidden: {
+        summary: "The runtime credential does not allow this action.",
+        fix: "Use a runtime token scoped for this action.",
+    },
+    runtime_api_not_found: {
+        summary: "The runtime management endpoint was not found.",
+        fix: "Check the runtime API path against the runtime contract.",
+    },
+    runtime_callback_forbidden: {
+        summary: "The runtime callback could not be authenticated.",
+        fix: "Verify the callback secret configuration for this runtime.",
+    },
+    runtime_engine_zip_missing: {
+        summary: "The runtime engine artifact is missing from this deployment.",
+        fix: "Rebuild the control plane so dist/runtime-engine.zip exists.",
+    },
+    runtime_hostname_unassigned: {
+        summary: "The hostname is not assigned to a runtime, so the request cannot be routed.",
+        fix: `Verify the binding is active and DNS points at ${BRAND.productName}.`,
+    },
+    runtime_instance_mismatch: {
+        summary: "The request reached a different runtime instance than the one it was issued for.",
+        fix: "Re-request instructions; the space may have moved to another instance.",
+    },
+    runtime_jti_missing: {
+        summary: "The runtime token is missing its replay-protection id.",
+        fix: "Mint a fresh runtime token; tokens must carry a jti claim.",
+    },
+    runtime_jti_replayed: {
+        summary: "The runtime token was already used; replays are rejected.",
+        fix: "Mint a fresh runtime token for each request.",
+    },
+    runtime_jwks_key_missing: {
+        summary: "No signing key matching the token's key id was found.",
+        fix: "Refresh the runtime JWKS; the signing keys may have rotated.",
+    },
+    runtime_logs_unavailable: {
+        summary: "Runtime logs are not available for this space right now.",
+        fix: "Retry shortly; logs may lag behind serving.",
+    },
+    runtime_management_unavailable: {
+        summary: "The runtime management surface is unavailable for this site.",
+        fix: "Retry shortly; if the site stays unreachable, contact support.",
+    },
+    runtime_not_provisioned: {
+        summary: "The space has no provisioned runtime yet.",
+        fix: "Wait for provisioning to finish; the operation receipt reports progress.",
+    },
+    runtime_operation_missing: {
+        summary: "The runtime operation referenced by this request was not found.",
+        fix: "Re-request instructions and retry with a current operation id.",
+    },
+    runtime_scope_forbidden: {
+        summary: "The runtime token's scope does not cover this path or action.",
+        fix: "Use the token minted for this exact session, space, and step.",
+    },
+    runtime_token_bad_signature: {
+        summary: "The runtime token signature did not verify.",
+        fix: "Mint a fresh token; verify clocks and JWKS freshness if it persists.",
+    },
+    runtime_token_expired: {
+        summary: "The runtime token has expired.",
+        fix: "Mint a fresh runtime token; step tokens are short-lived by design.",
+    },
+    runtime_token_invalid: {
+        summary: "The runtime token could not be parsed or validated.",
+        fix: "Mint a fresh runtime token.",
+    },
+    runtime_unauthorized: {
+        summary: "The request to the runtime carried no valid credential.",
+        fix: "Send the runtime JWT in the Authorization header.",
+    },
+    runtime_upload_operation_not_supported: {
+        summary: "The runtime upload session does not support this operation.",
+        fix: "Follow the upload instructions returned when the session was created.",
+    },
+    runtime_upload_required: {
+        summary: "This step requires uploaded content that has not arrived yet.",
+        fix: "Complete the uploads for this session, then retry the step.",
+    },
+    scan_pending: {
+        summary: "The content is still being scanned for safety and cannot be served yet.",
+        fix: "Wait for the scan to finish; serving resumes automatically once it clears.",
+    },
+    secret_variable_in_template: {
+        summary: "A secret variable was referenced in a template, which is blocked.",
+        fix: "Templates may only substitute non-secret variables; remove the secret reference.",
+    },
+    site_already_deleted: {
+        summary: "The site was already deleted.",
+        fix: "No action needed; the site is gone.",
+    },
+    site_capacity_exceeded: {
+        summary: "The site has reached its capacity and cannot take more content.",
+        fix: "Retry shortly; the platform rebalances spaces onto new sites automatically.",
+    },
+    site_has_live_spaces: {
+        summary: "The site still has live spaces assigned to it, so it cannot be deleted.",
+        fix: "Delete the live spaces or move them to another site before deleting this site.",
+    },
+    site_not_static: {
+        summary: "This operation only applies to static-runtime sites.",
+        fix: "Target a static-runtime site.",
+    },
+    site_required: {
+        summary: "A site reference is required for this operation.",
+        fix: "Pass the site id.",
+    },
+    site_suspended: {
+        summary: "The site is suspended, so its spaces cannot be served or modified.",
+        fix: "Resolve the suspension reason with support or the owning tenant.",
+    },
+    slow_down: {
+        summary: "The device login is being polled faster than the advised interval.",
+        fix: "Increase the polling interval; aggressive polling invalidates the flow.",
+    },
+    space_already_claimed: {
+        summary: "The space was already claimed by someone else.",
+        fix: "Publish a new space; a claim can only succeed once.",
+    },
+    space_claim_unavailable: {
+        summary: "This space cannot be claimed.",
+        fix: "Only anonymous, unexpired spaces with a valid claim token can be claimed.",
+    },
+    space_disabled: {
+        summary: "The space is disabled and cannot be served or modified.",
+        fix: "Check the disabled reason on the space; it explains the path to restore it.",
+    },
+    space_expired: {
+        summary: "The space expired and is no longer served.",
+        fix: "If it is within the recovery window, claim or restore it; otherwise publish again.",
+    },
+    space_has_active_version: {
+        summary: "The space still has an active version, which blocks this operation.",
+        fix: "Delete or supersede the active version first.",
+    },
+    space_import_archive_invalid: {
+        summary: `The import archive is not a valid ${BRAND.productName} export.`,
+        fix: "Export the source space again and upload the unmodified archive.",
+    },
+    space_import_archive_too_large: {
+        summary: "The import archive exceeds the maximum allowed size.",
+        fix: "Reduce the export size, or import versions individually.",
+    },
+    space_import_config_only_archive: {
+        summary: "The archive contains only configuration and cannot be imported as content.",
+        fix: "Include files in the export, or apply the configuration directly.",
+    },
+    space_import_runtime_schema_unsupported: {
+        summary: "The export was produced by an unsupported runtime schema version.",
+        fix: "Re-export from a current runtime, or upgrade before exporting.",
+    },
+    space_moving: {
+        summary: "The space is moving between sites, which blocks this operation.",
+        fix: "Wait for the move to finish, then retry.",
+    },
+    space_no_live_version: {
+        summary: "The space has no live version, so this operation has nothing to act on.",
+        fix: "Publish a version to the space, then retry.",
+    },
+    space_not_disabled: {
+        summary: "The space is not disabled, so it cannot be restored.",
+        fix: "No action needed; the space is already active.",
+    },
+    space_not_restorable: {
+        summary: "The space is past its recovery window and cannot be restored.",
+        fix: "Publish the content to a new space.",
+    },
+    space_ref_ambiguous: {
+        summary: "The space reference matches more than one accessible space.",
+        fix: "Use the spc_ id, or scope the reference with a teamRef.",
+    },
+    space_ref_required: {
+        summary: "A space reference is required for this operation.",
+        fix: "Pass a spc_ id, slug, or hostname.",
+    },
+    space_transferring: {
+        summary: "The space has a transfer in progress, which blocks this operation.",
+        fix: "Complete or cancel the transfer first.",
+    },
+    space_unclaimed: {
+        summary: "This operation requires a claimed space.",
+        fix: "Claim the space first using its claim URL.",
+    },
+    ssl_renewal_blocked: {
+        summary: "SSL certificate renewal is blocked for this hostname.",
+        fix: `Verify DNS still points at ${BRAND.productName}, then retry SSL issuance.`,
+    },
+    static_control_file_not_supported: {
+        summary: "This control file is not supported by the static runtime.",
+        fix: "Remove the file; see the routing docs for supported convention files.",
+    },
+    static_runtime_control_path_not_supported: {
+        summary: "This control path is not supported by the static runtime.",
+        fix: "Remove the path from the upload.",
+    },
+    static_runtime_required: {
+        summary: "This operation only applies to static-runtime spaces.",
+        fix: "Target a static-runtime space.",
+    },
+    storage_quota_exceeded: {
+        summary: "The publish would exceed the plan's storage allowance.",
+        fix: "Delete old versions or upgrade the plan.",
+    },
+    storage_usage_unavailable: {
+        summary: "Storage usage could not be computed right now.",
+        fix: "Retry shortly.",
+    },
+    stripe_error: {
+        summary: "The billing provider reported an error.",
+        fix: "Retry; if it persists, check the team's billing settings.",
+    },
+    superseded_by_publish: {
+        summary: "A newer publish superseded this operation, so it was skipped.",
+        fix: "No action needed; the newer publish already carries the change.",
+    },
+    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.",
+    },
+    team_ref_required: {
+        summary: "A team reference is required for this operation.",
+        fix: "Pass the team id or slug.",
+    },
+    team_required: {
+        summary: "This operation requires an acting team.",
+        fix: "Choose a team or pass a team reference.",
+    },
+    team_slug_conflict: {
+        summary: "The team slug is already taken.",
+        fix: "Choose a different slug.",
+    },
+    event_payload_too_large: {
+        summary: "The event payload exceeds the maximum size.",
+        fix: "Send smaller batches.",
+    },
+    event_rate_limited: {
+        summary: "Too many event submissions came from this client in a short window.",
+        fix: "Drop or batch events; event delivery is best-effort and never required.",
+    },
+    template_file_too_large: {
+        summary: "A template file exceeds the maximum size for substitution.",
+        fix: "Keep template files under the documented size limit (16 KB).",
+    },
+    template_not_in_version: {
+        summary: "The configuration names a template file the version does not contain.",
+        fix: "Upload the file or remove its templates entry from sf.jsonc.",
+    },
+    template_variable_unresolved: {
+        summary: "A template references a variable that has no value.",
+        fix: "Define the variable for the space, site, or team, or remove the reference.",
+    },
+    tenant_id_mismatch: {
+        summary: "The resource belongs to a different tenant than the request.",
+        fix: "Use a credential and tenant header matching the resource's tenant.",
+    },
+    tenant_not_found: {
+        summary: "The tenant was not found.",
+        fix: "Verify the tenant id.",
+    },
+    tenant_not_granted: {
+        summary: "Your credential has no grant on the requested tenant.",
+        fix: "Use a credential issued for this tenant.",
+    },
+    tenant_past_due: {
+        summary: "The tenant is past due; mutations are rejected while serving continues.",
+        fix: "Settle the outstanding balance to restore full access.",
+    },
+    tenant_selection_required: {
+        summary: "The credential spans multiple tenants, so the request must select one.",
+        fix: "Send the tenant header naming the tenant to act on.",
+    },
+    tenant_suspended: {
+        summary: "The tenant is suspended, so its resources cannot be served or modified.",
+        fix: "Resolve the suspension with support.",
+    },
+    theme_value_invalid: {
+        summary: "A theme value in the configuration is outside the allowed grammar.",
+        fix: "Use allowed CSS values; the offending key is dropped with a warning otherwise.",
+    },
+    transfer_cross_tenant_unsupported: {
+        summary: "Spaces cannot be transferred across tenants.",
+        fix: "Export the space and import it under the target tenant instead.",
+    },
+    transfer_move_failed: {
+        summary: "The space move backing this transfer failed.",
+        fix: "Retry the transfer; if it persists, contact support with the transfer id.",
+    },
+    transfer_not_cancelable: {
+        summary: "The transfer has progressed past the point where it can be canceled.",
+        fix: "Wait for the transfer to finish.",
+    },
+    transfer_source_changed: {
+        summary: "The space changed since the transfer was created, so it must be re-confirmed.",
+        fix: "Review the space's current state and confirm the transfer again.",
+    },
+    transfer_target_same_as_source: {
+        summary: "The transfer target is the same principal that already owns the space.",
+        fix: "Pick a different target team or account.",
+    },
+    unauthorized: {
+        summary: "The request carried no valid credential.",
+        fix: "Send a bearer access token, use an agent OAuth client, or sign in.",
+    },
+    unsupported_publish_media_type: {
+        summary: "The publish content-type is not supported.",
+        fix: "Send JSON, multipart form data, or a zip archive.",
+    },
+    upload_hash_mismatch: {
+        summary: "An uploaded file's bytes do not match the declared sha256.",
+        fix: "Re-hash the local file and upload it again.",
+    },
+    upload_path_not_canonical: {
+        summary: "An upload path is not in canonical (decoded, NFC-normalized) form.",
+        fix: "Send paths exactly as declared, decoded once and NFC-normalized.",
+    },
+    upload_path_not_declared: {
+        summary: "An uploaded path was not declared in the version's manifest.",
+        fix: "Declare every path up front, or use an open session for incremental uploads.",
+    },
+    upload_session_cap_exceeded: {
+        summary: "The open upload session exceeded its file or byte cap.",
+        fix: "Stay within the session caps, or declare a manifest for large publishes.",
+    },
+    upload_size_mismatch: {
+        summary: "An uploaded file's size does not match the declared size.",
+        fix: "Re-check the local file and upload it again.",
+    },
+    user_banned: {
+        summary: "This user is banned for a policy or abuse violation and cannot perform this action.",
+        fix: "Contact support to appeal the ban if you believe it is a mistake.",
+    },
+    validation_error: {
+        summary: "A request field failed validation.",
+        fix: "Fix the field referenced by param and details, then retry.",
+    },
+    variable_cascade_failed: {
+        summary: "Republishing spaces after a variable change failed.",
+        fix: "Check the operation's diagnostics; live content keeps serving the previous values.",
+    },
+    verification_required: {
+        summary: "Domain verification is required before this operation.",
+        fix: "Add the verification DNS record, then run verify on the domain.",
+    },
+    version_already_live: {
+        summary: "The version is already live on this channel.",
+        fix: "No action needed.",
+    },
+    version_artifact_not_found: {
+        summary: "The requested version artifact was not found.",
+        fix: "List the version's convention artifacts to see what exists.",
+    },
+    version_busy: {
+        summary: "The version is busy with another operation.",
+        fix: "Wait for the in-flight operation to finish, then retry.",
+    },
+    version_canceled: {
+        summary: "The version was canceled and cannot be used.",
+        fix: "Start a new version.",
+    },
+    version_closed: {
+        summary: "The version's upload session is closed; no more files can be added.",
+        fix: "Start a new version for additional changes.",
+    },
+    version_expired: {
+        summary: "The version's upload session expired before it was finalized.",
+        fix: "Start a new version and finalize within the session window.",
+    },
+    version_failed: {
+        summary: "The version failed and cannot be used.",
+        fix: "Check the version diagnostics, fix the cause, and publish again.",
+    },
+    version_file_count_exceeded: {
+        summary: "The version exceeds the maximum number of files.",
+        fix: "Reduce the file count or split content across multiple spaces.",
+    },
+    version_file_not_found: {
+        summary: "The requested file does not exist in this version.",
+        fix: "List the version's files to confirm the path.",
+    },
+    version_file_too_large: {
+        summary: "A file exceeds the plan's maximum file size.",
+        fix: "Reduce the file size or upgrade the plan.",
+    },
+    version_files_missing: {
+        summary: "Declared files were never uploaded, so the version cannot finalize.",
+        fix: "Resume the upload session to see and upload the missing files.",
+    },
+    version_in_use: {
+        summary: "The version is referenced by one or more channels and cannot be deleted.",
+        fix: "Promote another version on those channels first; details lists them.",
+    },
+    version_live: {
+        summary: "The version is live and cannot be deleted.",
+        fix: "Promote another version to live first.",
+    },
+    version_no_publishable_files: {
+        summary: "The version contains no publishable files.",
+        fix: "Add at least one servable file before finalizing.",
+    },
+    version_not_finalizable: {
+        summary: "The version cannot be finalized in its current status.",
+        fix: "Only uploaded versions finalize; check the version status.",
+    },
+    version_not_found: {
+        summary: "The version was not found.",
+        fix: "List the space's versions to confirm the id.",
+    },
+    version_not_prepared: {
+        summary: "The version is not prepared for this operation.",
+        fix: "Complete the version's upload and finalize steps first.",
+    },
+    version_not_promotable: {
+        summary: "The version cannot be promoted in its current status.",
+        fix: "Only ready versions can be promoted to a channel.",
+    },
+    version_not_ready: {
+        summary: "The version is not ready yet.",
+        fix: "Wait for finalize to complete; the operation receipt reports progress.",
+    },
+    version_quota_exceeded: {
+        summary: "The space has reached its version quota.",
+        fix: "Delete old versions or upgrade the plan.",
+    },
+    version_total_bytes_exceeded: {
+        summary: "The version exceeds the maximum total size.",
+        fix: "Reduce the content size or upgrade the plan.",
+    },
+    webhook_delivery_budget_exceeded: {
+        summary: "The webhook exhausted its delivery budget and was paused.",
+        fix: "Fix the receiving endpoint, then redeliver or re-enable the webhook.",
+    },
+    whois_unavailable: {
+        summary: "WHOIS data is unavailable for this domain right now.",
+        fix: "Retry later.",
+    },
+    zero_artifact_abi_mismatch: {
+        summary: "The Zero endpoint artifact was built for a different runner ABI.",
+        fix: `Rebuild and republish the Zero project with the current ${BRAND.productName} CLI and runtime.`,
+    },
+    zero_artifact_invalid: {
+        summary: "The Zero endpoint artifact is missing required runtime metadata.",
+        fix: "Rebuild the Zero project and verify the generated zero endpoint artifacts are uploaded.",
+    },
+    zero_artifact_malformed: {
+        summary: "The Zero endpoint artifact could not be parsed.",
+        fix: "Rebuild the Zero project; do not edit generated artifact JSON by hand.",
+    },
+    zero_artifact_path_invalid: {
+        summary: "The Zero endpoint artifact path is invalid.",
+        fix: "Rebuild the Zero routes so all artifact paths stay inside the version bundle.",
+    },
+    zero_artifact_unreadable: {
+        summary: "The Zero endpoint artifact could not be read by the runtime.",
+        fix: "Verify the version finalized with all generated Zero files present.",
+    },
+    zero_auth_unavailable: {
+        summary: "Hosted Zero auth is not configured for this deployment.",
+        fix: "Finalize the Zero version with hosted auth URLs or use guest/local auth.",
+    },
+    zero_blob_key_invalid: {
+        summary: "The local Zero blob key is invalid.",
+        fix: "Use a non-empty blob key without unsafe path segments.",
+    },
+    zero_blob_store_full: {
+        summary: "The local Zero blob store reached its configured size limit.",
+        fix: "Delete local blobs or raise the dev blob store limit.",
+    },
+    zero_blob_too_large: {
+        summary: "The local Zero blob value exceeds the maximum allowed size.",
+        fix: "Store a smaller value or move the payload to external storage.",
+    },
+    zero_blob_value_invalid: {
+        summary: "The local Zero blob request body is invalid.",
+        fix: "Send a valid blob body within the configured local size limits.",
+    },
+    zero_bootstrap_encode_failed: {
+        summary: "The Zero runner could not encode the JavaScript bootstrap data.",
+        fix: "Retry with valid request metadata; report the issue if it persists.",
+    },
+    zero_bytecode_hash_mismatch: {
+        summary: "The Zero endpoint bytecode hash does not match its artifact metadata.",
+        fix: "Rebuild and republish so bytecode and endpoint metadata are from the same build.",
+    },
+    zero_bytecode_invalid: {
+        summary: "The Zero endpoint bytecode could not be loaded by QuickJS.",
+        fix: "Rebuild the project with the current Zero runner and redeploy.",
+    },
+    zero_bytecode_path_invalid: {
+        summary: "The Zero endpoint bytecode path is invalid.",
+        fix: "Rebuild the Zero routes so bytecode paths stay inside the version bundle.",
+    },
+    zero_bytecode_unreadable: {
+        summary: "The Zero endpoint bytecode file could not be read.",
+        fix: "Verify the version finalized with the generated bytecode files present.",
+    },
+    zero_client_bundle_not_loaded: {
+        summary: "The local Zero dev client bundle has not been generated or loaded.",
+        fix: "Restart zero dev or run a fresh local build before loading the client route.",
+    },
+    zero_db_connect_failed: {
+        summary: "The Zero runner could not connect to the configured database.",
+        fix: "Verify DATABASE_URL or the generated MySQL connection variables and retry.",
+    },
+    zero_db_execute_failed: {
+        summary: "A Zero database write failed.",
+        fix: "Inspect the mutation, schema, and database logs, then retry after fixing the SQL issue.",
+    },
+    zero_db_host_install_failed: {
+        summary: "The Zero runner could not install the database host bridge.",
+        fix: "Rebuild with a current runner and report the failure if it repeats.",
+    },
+    zero_db_operation_invalid: {
+        summary: "The Zero database bridge received an invalid operation payload.",
+        fix: "Use the generated Zero database client instead of constructing bridge calls manually.",
+    },
+    zero_db_operation_too_large: {
+        summary: "The Zero database operation payload is too large.",
+        fix: "Reduce query parameters or batch size and retry.",
+    },
+    zero_db_param_invalid: {
+        summary: "A Zero database query parameter has an unsupported value.",
+        fix: "Pass JSON-serializable scalar values or nulls to generated database helpers.",
+    },
+    zero_db_query_failed: {
+        summary: "A Zero database read failed.",
+        fix: "Inspect the query, schema, and database logs, then retry after fixing the SQL issue.",
+    },
+    zero_db_row_invalid: {
+        summary: "A database row could not be converted into a Zero response value.",
+        fix: "Check the table schema and stored values for unsupported data.",
+    },
+    zero_db_sql_invalid: {
+        summary: "The Zero runner rejected unsafe or unsupported SQL.",
+        fix: "Use generated Zero query helpers and avoid multiple statements or unsupported SQL forms.",
+    },
+    zero_db_too_many_params: {
+        summary: "The Zero database operation has too many parameters.",
+        fix: "Reduce the number of bound parameters or split the operation.",
+    },
+    zero_db_transaction_commit_failed: {
+        summary: "The Zero database transaction could not be committed.",
+        fix: "Retry after checking database connectivity and transaction conflicts.",
+    },
+    zero_db_transaction_invalid: {
+        summary: "The Zero database transaction mode is invalid.",
+        fix: "Use a supported generated transaction mode.",
+    },
+    zero_db_transaction_start_failed: {
+        summary: "The Zero database transaction could not be started.",
+        fix: "Check database connectivity and retry the mutation.",
+    },
+    zero_db_url_invalid: {
+        summary: "The Zero database URL is malformed.",
+        fix: "Set DATABASE_URL or the generated database variables to a valid MySQL connection URL.",
+    },
+    zero_db_url_missing: {
+        summary: "No Zero database URL is configured.",
+        fix: "Configure DATABASE_URL or finalize the version with database connection variables.",
+    },
+    zero_dev_endpoint_failed: {
+        summary: "A local Zero dev endpoint failed while handling the request.",
+        fix: "Check the local dev console output and fix the endpoint implementation.",
+    },
+    zero_dump_query_invalid: {
+        summary: "The Zero database dump query parameters are invalid.",
+        fix: "Use valid table, limit, and cursor parameters.",
+    },
+    zero_endpoint_index_invalid: {
+        summary: "The Zero endpoint index does not contain valid endpoint mappings.",
+        fix: "Rebuild and republish the Zero project.",
+    },
+    zero_endpoint_index_malformed: {
+        summary: "The Zero endpoint index could not be parsed.",
+        fix: "Rebuild the generated endpoint index and redeploy.",
+    },
+    zero_endpoint_index_path_invalid: {
+        summary: "The Zero endpoint index path is invalid.",
+        fix: "Verify the runtime bundle was finalized with the standard Zero layout.",
+    },
+    zero_endpoint_index_unreadable: {
+        summary: "The Zero endpoint index could not be read.",
+        fix: "Verify the version finalized with zero/endpoints-index.json present.",
+    },
+    zero_endpoint_mismatch: {
+        summary: "The requested Zero endpoint does not match the endpoint artifact.",
+        fix: "Rebuild routes and artifacts together and redeploy the version.",
+    },
+    zero_endpoint_not_found: {
+        summary: "No Zero endpoint artifact exists for this endpoint id.",
+        fix: "Check the route path and rebuild the Zero endpoint index.",
+    },
+    zero_envelope_encode_failed: {
+        summary: "The PHP bridge could not encode the Zero runner request envelope.",
+        fix: "Retry with valid request data; report the issue if it persists.",
+    },
+    zero_js_context_init_failed: {
+        summary: "The Zero runner could not initialize a QuickJS context.",
+        fix: "Retry or rebuild the runner; report persistent runtime initialization failures.",
+    },
+    zero_js_execution_failed: {
+        summary: "The Zero endpoint JavaScript threw during execution.",
+        fix: "Inspect the endpoint error and fix the handler code.",
+    },
+    zero_js_execution_timeout: {
+        summary: "The Zero endpoint exceeded its JavaScript execution budget.",
+        fix: "Reduce synchronous work or database round trips in the handler.",
+    },
+    zero_js_globals_failed: {
+        summary: "The Zero runner could not install runtime globals for the endpoint.",
+        fix: "Rebuild with a current runner and report the failure if it repeats.",
+    },
+    zero_js_response_malformed: {
+        summary: "The Zero endpoint returned a malformed runner response.",
+        fix: "Return a valid Response or supported Zero handler result.",
+    },
+    zero_js_runtime_init_failed: {
+        summary: "The Zero runner could not initialize QuickJS.",
+        fix: "Retry on a healthy runtime or rebuild the runner binary.",
+    },
+    zero_log_query_invalid: {
+        summary: "The Zero log query parameters are invalid.",
+        fix: "Use valid cursor, limit, mutationName, and requestId parameters.",
+    },
+    zero_method_not_allowed: {
+        summary: "The request method is not allowed for this Zero endpoint.",
+        fix: "Call the endpoint with one of the methods declared by the Zero route.",
+    },
+    zero_query_name_missing: {
+        summary: "A Zero realtime query subscription did not include a query name.",
+        fix: "Send a query.subscribe frame with a valid query name.",
+    },
+    zero_realtime_forbidden: {
+        summary: "The Zero realtime event intake credential is invalid.",
+        fix: "Send the configured bearer token or a valid signed realtime event.",
+    },
+    zero_realtime_message_invalid: {
+        summary: "The Zero realtime websocket message is malformed.",
+        fix: "Send a supported JSON realtime frame.",
+    },
+    zero_realtime_operation_unsupported: {
+        summary: "The Zero realtime websocket operation is unsupported.",
+        fix: "Use a supported Zero realtime operation such as query.subscribe or query.unsubscribe.",
+    },
+    zero_realtime_query_invalid: {
+        summary: "The Zero realtime query subscription payload is invalid.",
+        fix: "Include a valid query name and argument list.",
+    },
+    zero_realtime_space_required: {
+        summary: "The Zero realtime request does not identify a space.",
+        fix: "Use a /spaces/{spaceId} realtime URL or include a valid spaceId query parameter.",
+    },
+    zero_realtime_unavailable: {
+        summary: "Zero realtime helpers are unavailable for this endpoint.",
+        fix: "Enable realtime capability for the handler and rebuild the project.",
+    },
+    zero_realtime_websocket_forbidden: {
+        summary: "The Zero realtime websocket credential is invalid.",
+        fix: "Send the configured realtime client token by query, header, bearer token, or websocket subprotocol.",
+    },
+    zero_replay_failed: {
+        summary: "The hosted Zero runtime could not fetch realtime replay events.",
+        fix: "Retry shortly; check the central realtime and control-plane logs if it persists.",
+    },
+    zero_replay_query_invalid: {
+        summary: "The hosted Zero realtime replay query is invalid.",
+        fix: "Use a valid afterEventId cursor and numeric limit.",
+    },
+    zero_replay_unavailable: {
+        summary: "Realtime replay is not configured for this Zero version.",
+        fix: "Finalize the version with a Zero realtime replay URL or disable replay catch-up.",
+    },
+    zero_request_body_too_large: {
+        summary: "The Zero request body exceeds the runtime size limit.",
+        fix: "Send a smaller request body or move large payloads to blob/object storage.",
+    },
+    zero_response_too_large: {
+        summary: "The Zero endpoint response exceeds the runtime size limit.",
+        fix: "Return a smaller response body or paginate the data.",
+    },
+    zero_run_operation_unsupported: {
+        summary: "The hosted Zero runtime does not support this run operation yet.",
+        fix: "Use a generated endpoint or deploy a generated run handler for this operation.",
+    },
+    zero_runner_envelope_invalid: {
+        summary: "The Zero runner request envelope is malformed.",
+        fix: "Use the generated runtime bridge and redeploy if generated files are stale.",
+    },
+    zero_runner_failed: {
+        summary: "The Zero runner process exited without a valid response.",
+        fix: "Inspect runtime logs and rebuild the Zero project with the current runner.",
+    },
+    zero_runner_invalid_body: {
+        summary: "The Zero runner returned an invalid response body.",
+        fix: "Check the endpoint response and runner logs.",
+    },
+    zero_runner_invalid_response: {
+        summary: "The Zero runner output was not valid JSON.",
+        fix: "Inspect runner stderr and rebuild the runner if the failure persists.",
+    },
+    zero_runner_invalid_status: {
+        summary: "The Zero runner returned an invalid HTTP status.",
+        fix: "Ensure endpoint handlers return a status between 100 and 599.",
+    },
+    zero_runner_protocol_unsupported: {
+        summary: "The Zero runner received an unsupported invoke protocol.",
+        fix: "Rebuild and redeploy so the PHP bridge and Rust runner versions match.",
+    },
+    zero_runner_response_encode_failed: {
+        summary: "The Zero runner could not encode its response.",
+        fix: "Return JSON-serializable response metadata from the endpoint.",
+    },
+    zero_runner_stdin_invalid: {
+        summary: "The Zero runner could not read its request envelope.",
+        fix: "Retry; report the runtime bridge failure if it persists.",
+    },
+    zero_runner_stdin_too_large: {
+        summary: "The Zero runner request envelope is too large.",
+        fix: "Reduce request headers, body size, or route parameters.",
+    },
+    zero_runner_unavailable: {
+        summary: "The Zero runner process could not be started.",
+        fix: "Verify the runner binary is installed and executable in the runtime.",
+    },
+    zero_source_compile_failed: {
+        summary: "The Zero endpoint source fallback failed to compile.",
+        fix: "Fix the endpoint source and rebuild bytecode.",
+    },
+    zero_source_hash_mismatch: {
+        summary: "The Zero endpoint source hash does not match its artifact metadata.",
+        fix: "Rebuild and republish so source and endpoint metadata are from the same build.",
+    },
+    zero_source_invalid: {
+        summary: "The Zero endpoint source is invalid.",
+        fix: "Fix the generated endpoint source and rebuild.",
+    },
+    zero_source_path_invalid: {
+        summary: "The Zero endpoint source path is invalid.",
+        fix: "Rebuild the Zero routes so source paths stay inside the version bundle.",
+    },
+    zero_source_unreadable: {
+        summary: "The Zero endpoint source file could not be read.",
+        fix: "Verify the version finalized with generated source files present.",
+    },
+    wp_cloud_anonymous_pool_required: {
+        summary: "This operation requires an anonymous pool site.",
+        fix: "Target a pool-class site.",
+    },
+    wp_cloud_assignment_kind_mismatch: {
+        summary: "The domain assignment's kind does not match the site.",
+        fix: "Verify the assignment against the site's hosting kind.",
+    },
+    wp_cloud_assignment_space_mismatch: {
+        summary: "The domain assignment belongs to a different space.",
+        fix: "Use the assignment's owning space.",
+    },
+    wp_cloud_assignment_team_mismatch: {
+        summary: "The domain assignment belongs to a different team.",
+        fix: "Use the assignment's owning team.",
+    },
+    wp_cloud_client_in_use: {
+        summary: "The provider client is in use and cannot be removed.",
+        fix: "Reassign or delete the dependent sites first.",
+    },
+    wp_cloud_client_not_found: {
+        summary: "The provider client was not found.",
+        fix: "Verify the provider client id.",
+    },
+    wp_cloud_site_still_assigned: {
+        summary: "The provider site still has assignments and cannot be released.",
+        fix: "Remove the site's assignments first.",
+    },
+    wp_cloud_team_shared_site_exists: {
+        summary: "The team already has a shared site of this class.",
+        fix: "Use the existing shared site.",
+    },
+    wp_cloud_webhook_secret_not_configured: {
+        summary: "The WP.Cloud webhook secret is not configured on this deployment.",
+        fix: "Set the WP.Cloud webhook secret in the control-plane environment.",
+    },
+};
+const PRODUCT = BRAND.productName;
+/** One generated reference page per error code; the `.md` twin is this exact text. */
+export function errorDocMarkdown(code) {
+    const doc = ERROR_DOCS[code];
+    return [
+        `# ${code}`,
+        "",
+        doc.summary,
+        "",
+        `**How to resolve:** ${doc.fix}`,
+        "",
+        "## Error envelope",
+        "",
+        `Every ${PRODUCT} API error uses one envelope. \`code\` is stable and machine-readable,`,
+        "`param` (when present) points at the offending request field, and `details` may carry",
+        "structured context. Match on `code`, never on `message`.",
+        "",
+        "```json",
+        JSON.stringify({
+            error: {
+                code,
+                message: doc.summary,
+                docsUrl: errorDocsUrl(code),
+                requestId: "req_4mz0v8qk",
+            },
+        }, null, 2),
+        "```",
+        "",
+        `See the full list of error codes in the [error reference](${BRAND.websiteOrigin}/docs/errors).`,
+        "",
+    ].join("\n");
+}
+/** The generated `/docs/errors` index page; the `.md` twin is this exact text. */
+export function errorDocsIndexMarkdown() {
+    return [
+        "# Error reference",
+        "",
+        `Every ${PRODUCT} API error response carries a stable \`code\` and a \`docsUrl\` that`,
+        "links to one of the pages below. Codes are never renamed or removed. Match on",
+        "`code` in clients; `message` text may improve over time.",
+        "",
+        "| Code | Meaning |",
+        "| --- | --- |",
+        ...ERROR_CODES.map((code) => `| [\`${code}\`](/docs/errors/${code}) | ${ERROR_DOCS[code].summary} |`),
+        "",
+    ].join("\n");
+}