@spacefast/common 0.0.5 → 0.0.7

package/dist/docs/error-docs.d.ts

@@ -8,5 +8,3 @@ export type ErrorDoc = {
 export declare const ERROR_DOCS: Record<ErrorCode, ErrorDoc>;
 /** One generated reference page per error code; the `.md` twin is this exact text. */
 export declare function errorDocMarkdown(code: ErrorCode): string;
-/** The generated `/docs/errors` index page; the `.md` twin is this exact text. */
-export declare function errorDocsIndexMarkdown(): string;

package/dist/docs/error-docs.js

@@ -5,7 +5,8 @@
 // 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";
+import { errorDocsUrl } from "../contracts/error-codes.js";
+// Restore upgrade-oriented recovery copy here when paid plan checkout is live.
 export const ERROR_DOCS = {
     abuse_report_invalid_transition: {
         summary: "The abuse report cannot move to the requested status from its current status.",
@@ -33,7 +34,7 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Publish a fresh space and share its claim link right away this time. If you meant to update a space that is still live, check .spacefast/ (or your saved receipt) for its spaceId and publish to that with its credential instead of creating a new space.",
     },
     anonymous_pool_unavailable: {
         summary: "No pooled capacity is available for anonymous publishes right now.",
@@ -43,6 +44,14 @@ export const ERROR_DOCS = {
         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.",
     },
+    anonymous_space_limit_reached: {
+        summary: "Too many unclaimed anonymous spaces are already active for this client.",
+        fix: "Log in to publish into an authenticated space, or claim/delete an existing anonymous space before creating another.",
+    },
+    api_key_scope_underivable: {
+        summary: "A concrete access policy could not be derived from the requested scope and permissions.",
+        fix: "Point scope at a resource you can already reach (an existing space owned by a team) and request permissions your credential already has.",
+    },
     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.",
@@ -145,7 +154,7 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Delete unused spaces, then claim again. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     cli_upgrade_required: {
         summary: "This CLI version is too old to talk to the API safely.",
@@ -165,7 +174,15 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Reduce the number of template entries in sf.jsonc. Still stuck? POST /v1/feedback with the error code and request id.",
+    },
+    continuation_unavailable: {
+        summary: "This claim token can no longer be exchanged for an access token.",
+        fix: "If the space is claimed, ask its owner for an access token (dashboard: Account → Access tokens). If it is still unclaimed, keep using the claim token as bearer auth instead of exchanging it. Still stuck? POST /v1/feedback with the error code and request id.",
+    },
+    continuation_used: {
+        summary: "This claim token was already exchanged for a durable access token.",
+        fix: "Authenticate with the exchanged access token (check .spacefast/state.json or wherever it was saved). If it was lost, ask the space owner to mint a new access token.",
     },
     credential_expired: {
         summary: "The credential used for this request has expired.",
@@ -191,9 +208,13 @@ 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.",
     },
+    datacenters_unavailable: {
+        summary: "Placement regions are temporarily unavailable.",
+        fix: "Retry after the datacenter list has synced.",
+    },
     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.",
+        summary: "This request tried to change data location through an immutable path.",
+        fix: "Use PATCH /v1/spaces/{id} to queue a region move when region changes are supported for this space.",
     },
     device_authorization_failed: {
         summary: "The device login request failed and cannot be completed.",
@@ -373,7 +394,7 @@ export const ERROR_DOCS = {
     },
     domain_quota_exceeded: {
         summary: "Adding this domain would exceed the plan's external domain allowance.",
-        fix: "Remove unused domains or upgrade the plan.",
+        fix: "Remove unused domains. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     domain_registration_active: {
         summary: "The domain has an active registration, which blocks this operation.",
@@ -407,6 +428,10 @@ export const ERROR_DOCS = {
         summary: "The version upload declares the same file path twice.",
         fix: "Deduplicate the file list so every path appears once.",
     },
+    enforcement_policy_overlap: {
+        summary: "Enforcement policy severity ranges overlap within a category.",
+        fix: "Adjust the category ranges so each severity is covered by at most one policy.",
+    },
     expired_token: {
         summary: "The token has expired.",
         fix: "Request a new token and retry.",
@@ -421,7 +446,7 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Check the feature's availability and try again when it is enabled for your team.",
     },
     files_mode_does_not_support_spa: {
         summary: "SPA fallback cannot be combined with files-listing mode.",
@@ -433,11 +458,11 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Remove the proxy rules before publishing. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     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.",
+        fix: "Use space password protection instead. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     idempotency_conflict_in_progress: {
         summary: "Another request with the same Idempotency-Key is still in flight.",
@@ -613,7 +638,7 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Narrow the range.",
     },
     lost_domain_control: {
         summary: `${BRAND.productName} no longer observes DNS control for this domain.`,
@@ -647,6 +672,10 @@ export const ERROR_DOCS = {
         summary: "A required route parameter is missing from the request path.",
         fix: "Check the endpoint path in the API reference and include every parameter.",
     },
+    move_target_capacity_lost: {
+        summary: "The selected move target no longer has capacity for the space.",
+        fix: "Retry the move with a different target or after capacity is freed.",
+    },
     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.",
@@ -683,6 +712,14 @@ export const ERROR_DOCS = {
         summary: "This plan grant was already revoked.",
         fix: "Nothing to do; create a new grant if the team should regain the plan.",
     },
+    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.',
+    },
+    placement_mode_requires_plan: {
+        summary: "The requested placement mode requires a plan entitlement.",
+        fix: "Upgrade the team plan or choose shared placement.",
+    },
     platform_tenant_immutable_client: {
         summary: "The tenant's provider client cannot be changed.",
         fix: "Create a new tenant with the desired provider client instead.",
@@ -729,7 +766,7 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Reduce the content size.",
     },
     publish_archive_file_count_exceeded: {
         summary: "The archive contains more files than the allowed ceiling.",
@@ -739,6 +776,10 @@ export const ERROR_DOCS = {
         summary: "The uploaded archive exceeds the maximum allowed size.",
         fix: "Reduce the archive size or use a version upload session for big publishes.",
     },
+    publish_base_changed: {
+        summary: "Someone published new space settings after the base you loaded, so saving would overwrite their change.",
+        fix: "Reload the latest settings, review the difference, and save again; pass force only to overwrite deliberately.",
+    },
     publish_config_unsupported: {
         summary: "The publish carries configuration this endpoint does not support.",
         fix: "Move the configuration into sf.jsonc or the space settings.",
@@ -781,7 +822,7 @@ export const ERROR_DOCS = {
     },
     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.",
+        fix: "Reduce the rule count. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     runtime_action_forbidden: {
         summary: "The runtime credential does not allow this action.",
@@ -789,7 +830,7 @@ export const ERROR_DOCS = {
     },
     runtime_api_not_found: {
         summary: "The runtime management endpoint was not found.",
-        fix: "Check the runtime API path against the runtime contract.",
+        fix: "Send the request with the management hostname as the Host header; management routes are not served on public hostnames.",
     },
     runtime_callback_forbidden: {
         summary: "The runtime callback could not be authenticated.",
@@ -899,14 +940,30 @@ export const ERROR_DOCS = {
         summary: "The device login is being polled faster than the advised interval.",
         fix: "Increase the polling interval; aggressive polling invalidates the flow.",
     },
+    slug_invalid: {
+        summary: "The slug does not meet the structural rules for managed names.",
+        fix: "Use lowercase letters, numbers, and single dashes within the allowed length; the error message identifies the failed rule.",
+    },
+    slug_reserved: {
+        summary: "The slug is reserved for infrastructure, product, or impersonation protection.",
+        fix: "Choose a different name that is not reserved by the shared slug policy.",
+    },
+    slug_unavailable: {
+        summary: "The slug is already in use within the relevant ownership scope.",
+        fix: "Choose another slug or use the available suggestion returned by the API.",
+    },
     space_already_claimed: {
-        summary: "The space was already claimed by someone else.",
-        fix: "Publish a new space; a claim can only succeed once.",
+        summary: "The space was already claimed; a claim can only succeed once.",
+        fix: "If you are the agent that published this space, exchange your claim token once at POST /v1/anonymous-claim/exchange for a durable access token and keep publishing to the same spaceId. Otherwise ask the owner for access — do not publish a duplicate space.",
     },
     space_claim_unavailable: {
         summary: "This space cannot be claimed.",
         fix: "Only anonymous, unexpired spaces with a valid claim token can be claimed.",
     },
+    space_claimed_credential_available: {
+        summary: "The space was claimed and its owner kept agent publishing enabled; this claim token now works exactly once as an exchange voucher.",
+        fix: "POST /v1/anonymous-claim/exchange with this claim token as bearer auth. Save the returned access token (e.g. .spacefast/state.json), then retry the request with it as Authorization: Bearer. Do not publish a new space.",
+    },
     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.",
@@ -919,6 +976,10 @@ export const ERROR_DOCS = {
         summary: "The space still has an active version, which blocks this operation.",
         fix: "Delete or supersede the active version first.",
     },
+    space_hostname_identity_missing: {
+        summary: "The space is missing its persisted default hostname identity.",
+        fix: "Contact support. Retrying cannot safely recreate a permanent hostname identity.",
+    },
     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.",
@@ -983,9 +1044,13 @@ export const ERROR_DOCS = {
         summary: "This operation only applies to static-runtime spaces.",
         fix: "Target a static-runtime space.",
     },
+    storage_bucket_unavailable: {
+        summary: "No usable internal storage bucket is configured for this operation.",
+        fix: "Check the storage bucket registry and credential environment references, then retry.",
+    },
     storage_quota_exceeded: {
         summary: "The publish would exceed the plan's storage allowance.",
-        fix: "Delete old versions or upgrade the plan.",
+        fix: "Delete old versions. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     storage_usage_unavailable: {
         summary: "Storage usage could not be computed right now.",
@@ -1003,6 +1068,10 @@ export const ERROR_DOCS = {
         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_member_quota_exceeded: {
+        summary: "Inviting this person would exceed the team's seat limit.",
+        fix: "Remove a team member or cancel a pending invitation to free a seat; pending invitations count toward the limit.",
+    },
     team_ref_required: {
         summary: "A team reference is required for this operation.",
         fix: "Pass the team id or slug.",
@@ -1075,6 +1144,10 @@ export const ERROR_DOCS = {
         summary: "The transfer has progressed past the point where it can be canceled.",
         fix: "Wait for the transfer to finish.",
     },
+    transfer_push_failed: {
+        summary: "The source runtime could not push the space blobs into the transfer bucket.",
+        fix: "Retry the move; if it persists, check the source runtime and bucket configuration.",
+    },
     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.",
@@ -1083,6 +1156,10 @@ export const ERROR_DOCS = {
         summary: "The transfer target is the same principal that already owns the space.",
         fix: "Pick a different target team or account.",
     },
+    transfer_verify_failed: {
+        summary: "The target runtime could not verify transferred blob content.",
+        fix: "Retry the move; if it persists, check the target runtime and bucket integrity.",
+    },
     unauthorized: {
         summary: "The request carried no valid credential.",
         fix: "Send a bearer access token, use an agent OAuth client, or sign in.",
@@ -1165,7 +1242,7 @@ export const ERROR_DOCS = {
     },
     version_file_too_large: {
         summary: "A file exceeds the plan's maximum file size.",
-        fix: "Reduce the file size or upgrade the plan.",
+        fix: "Reduce the file size.",
     },
     version_files_missing: {
         summary: "Declared files were never uploaded, so the version cannot finalize.",
@@ -1205,11 +1282,11 @@ export const ERROR_DOCS = {
     },
     version_quota_exceeded: {
         summary: "The space has reached its version quota.",
-        fix: "Delete old versions or upgrade the plan.",
+        fix: "Delete old versions. Still stuck? POST /v1/feedback with the error code and request id.",
     },
     version_total_bytes_exceeded: {
         summary: "The version exceeds the maximum total size.",
-        fix: "Reduce the content size or upgrade the plan.",
+        fix: "Reduce the content size.",
     },
     webhook_delivery_budget_exceeded: {
         summary: "The webhook exhausted its delivery budget and was paused.",
@@ -1219,6 +1296,14 @@ export const ERROR_DOCS = {
         summary: "WHOIS data is unavailable for this domain right now.",
         fix: "Retry later.",
     },
+    zero_activating: {
+        summary: "Zero endpoints are activating.",
+        fix: "Wait for the dedicated runtime move to complete, then retry the request.",
+    },
+    zero_ai_unavailable: {
+        summary: "The local Zero AI service is not configured.",
+        fix: "Configure an AI handler for zero dev before calling the AI service.",
+    },
     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.`,
@@ -1231,6 +1316,10 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint artifact could not be parsed.",
         fix: "Rebuild the Zero project; do not edit generated artifact JSON by hand.",
     },
+    zero_artifact_missing: {
+        summary: "A Zero route points to an endpoint artifact that is missing.",
+        fix: "Declare the endpoint in zero_endpoints, then rebuild and publish again.",
+    },
     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.",
@@ -1239,6 +1328,10 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint artifact could not be read by the runtime.",
         fix: "Verify the version finalized with all generated Zero files present.",
     },
+    zero_artifact_untrusted: {
+        summary: "A Zero route points to an uploaded artifact that the runtime did not compile.",
+        fix: "Declare the endpoint in zero_endpoints so finalize generates trusted bytecode.",
+    },
     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.",
@@ -1279,6 +1372,10 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint bytecode file could not be read.",
         fix: "Verify the version finalized with the generated bytecode files present.",
     },
+    zero_capabilities_encode_failed: {
+        summary: "The runtime could not encode the Zero endpoint capabilities.",
+        fix: "Rebuild with valid capability metadata; report the failure if it persists.",
+    },
     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.",
@@ -1351,6 +1448,22 @@ export const ERROR_DOCS = {
         summary: "The Zero database dump query parameters are invalid.",
         fix: "Use valid table, limit, and cursor parameters.",
     },
+    zero_endpoint_compile_failed: {
+        summary: "The runtime could not compile the Zero endpoint bytecode.",
+        fix: "Inspect the compile diagnostics, fix the endpoint source, and publish again.",
+    },
+    zero_endpoint_conflict: {
+        summary: "Two Zero routes resolve to the same runtime path.",
+        fix: "Remove the duplicate generated or explicit lookup route and publish again.",
+    },
+    zero_endpoint_duplicate: {
+        summary: "Two Zero endpoints declare the same method and route.",
+        fix: "Give each endpoint a unique method and route before publishing again.",
+    },
+    zero_endpoint_id_duplicate: {
+        summary: "Two Zero endpoints declare the same endpoint id.",
+        fix: "Give every endpoint a unique endpoint id before publishing again.",
+    },
     zero_endpoint_index_invalid: {
         summary: "The Zero endpoint index does not contain valid endpoint mappings.",
         fix: "Rebuild and republish the Zero project.",
@@ -1367,6 +1480,10 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint index could not be read.",
         fix: "Verify the version finalized with zero/endpoints-index.json present.",
     },
+    zero_endpoint_invalid: {
+        summary: "A Zero endpoint definition or its database metadata is invalid.",
+        fix: "Fix the endpoint method, route, source, capabilities, or database metadata and publish again.",
+    },
     zero_endpoint_mismatch: {
         summary: "The requested Zero endpoint does not match the endpoint artifact.",
         fix: "Rebuild routes and artifacts together and redeploy the version.",
@@ -1375,6 +1492,18 @@ export const ERROR_DOCS = {
         summary: "No Zero endpoint artifact exists for this endpoint id.",
         fix: "Check the route path and rebuild the Zero endpoint index.",
     },
+    zero_endpoints_invalid: {
+        summary: "The Zero endpoints payload is invalid.",
+        fix: "Send an endpoint array within the supported count and size limits.",
+    },
+    zero_endpoints_too_many: {
+        summary: "The Zero endpoints payload exceeds the supported endpoint count.",
+        fix: "Reduce the project to at most 128 Zero endpoints, then publish again.",
+    },
+    zero_requires_dedicated_plan: {
+        summary: "Zero endpoints require a plan with dedicated runtime isolation.",
+        fix: "Upgrade the team to a plan that includes Zero and dedicated runtime, then publish again.",
+    },
     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.",
@@ -1407,10 +1536,18 @@ export const ERROR_DOCS = {
         summary: "The Zero log query parameters are invalid.",
         fix: "Use valid cursor, limit, mutationName, and requestId parameters.",
     },
+    zero_lookup_invalid: {
+        summary: "The Zero lookup map contains an invalid path or action.",
+        fix: "Use normalized relative paths and valid finalized Zero actions.",
+    },
     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_migration_failed: {
+        summary: "The Zero database migration command failed during finalize.",
+        fix: "Inspect the migration and database logs, fix the schema issue, and publish again.",
+    },
     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.",
@@ -1463,6 +1600,22 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint response exceeds the runtime size limit.",
         fix: "Return a smaller response body or paginate the data.",
     },
+    zero_routes_invalid: {
+        summary: "The Zero routes artifact is invalid.",
+        fix: "Rebuild the generated routes and publish the version again.",
+    },
+    zero_run_compile_failed: {
+        summary: "The runtime could not compile a Zero run handler.",
+        fix: "Inspect the compile diagnostics, fix the run-handler source, and publish again.",
+    },
+    zero_run_duplicate: {
+        summary: "Two Zero run handlers declare the same run id.",
+        fix: "Give every run handler a unique run id before publishing again.",
+    },
+    zero_run_invalid: {
+        summary: "A Zero run-handler definition is invalid.",
+        fix: "Fix the run id, source, capabilities, or database metadata and publish again.",
+    },
     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.",
@@ -1507,6 +1660,22 @@ export const ERROR_DOCS = {
         summary: "The Zero runner process could not be started.",
         fix: "Verify the runner binary is installed and executable in the runtime.",
     },
+    zero_runs_invalid: {
+        summary: "The Zero run-handler payload is invalid.",
+        fix: "Send a valid array of generated run handlers and publish again.",
+    },
+    zero_runs_require_runtime_compiler: {
+        summary: "Zero run handlers require the Rust runtime compiler.",
+        fix: "Install the current runtime compiler and finalize the version again.",
+    },
+    zero_runs_too_many: {
+        summary: "The Zero run-handler payload exceeds the supported handler count.",
+        fix: "Reduce the project to at most 128 Zero run handlers, then publish again.",
+    },
+    zero_shopify_unavailable: {
+        summary: "The local Zero Shopify service is not configured.",
+        fix: "Configure a Shopify handler for zero dev before calling the Shopify service.",
+    },
     zero_source_compile_failed: {
         summary: "The Zero endpoint source fallback failed to compile.",
         fix: "Fix the endpoint source and rebuild bytecode.",
@@ -1596,18 +1765,3 @@ export function errorDocMarkdown(code) {
         "",
     ].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");
-}

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

@@ -0,0 +1,17 @@
+import { type DocEntry } from "./catalog.js";
+/** Current on-disk index schema version; bump when the shape changes. */
+export declare const DOCS_INDEX_VERSION: 1;
+/** A catalog entry plus its precomputed search blob. */
+export interface DocIndexEntry extends DocEntry {
+    /** Lowercased haystack (slug + title + summary + kind + keywords) for offline search. */
+    readonly haystack: string;
+}
+/** 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[];
+}
+/** Build the derived search index from a catalog (defaults to the bundled one). */
+export declare function buildDocsIndex(catalog?: readonly DocEntry[]): DocsIndex;

package/dist/docs/index-build.js

@@ -0,0 +1,24 @@
+// 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.
+import { DOCS_CATALOG } from "./catalog.js";
+/** Current on-disk index schema version; bump when the shape changes. */
+export const DOCS_INDEX_VERSION = 1;
+/** Build the derived search index from a catalog (defaults to the bundled one). */
+export function buildDocsIndex(catalog = DOCS_CATALOG) {
+    const entries = catalog.map((entry) => ({
+        ...entry,
+        keywords: [...entry.keywords],
+        haystack: [entry.slug, entry.title, entry.summary, entry.kind, ...entry.keywords]
+            .join(" ")
+            .toLowerCase(),
+    }));
+    return {
+        version: DOCS_INDEX_VERSION,
+        // Provenance points at the CLI's re-export path, which the committed
+        // docs-index.generated.json artifact (and its drift-guard test) pin.
+        generatedFrom: "src/docs-catalog.ts",
+        entries,
+    };
+}

package/dist/docs/search.d.ts

@@ -0,0 +1,54 @@
+import { type CliDisclosureTier } from "../vocabulary.js";
+import type { DocIndexEntry, DocsIndex } from "./index-build.js";
+/** The public, machine-readable shape of a single matched doc. */
+export interface DocResult {
+    readonly slug: string;
+    readonly title: string;
+    readonly kind: DocIndexEntry["kind"];
+    readonly tier: CliDisclosureTier;
+    readonly summary: string;
+    readonly url: string;
+}
+/** A topic result additionally carries the printable body. */
+export interface DocTopic extends DocResult {
+    readonly body: string;
+}
+/** The exact `data` payload `sf docs` emits (drives both human + `--json` output). */
+export interface DocsCommandResult {
+    /** The trimmed query, or null when listing. */
+    readonly query: string | null;
+    /** The tier the listing/search ran at. */
+    readonly tier: CliDisclosureTier;
+    /** Present when the query resolved to an exact topic. */
+    readonly topic: DocTopic | null;
+    /** Matched docs (or the full tier listing when no query). */
+    readonly results: readonly DocResult[];
+}
+/** Entries visible at `viewTier`, in catalog order. */
+export declare function visibleEntries(index: DocsIndex, viewTier: CliDisclosureTier): DocIndexEntry[];
+/** Exact topic lookup by slug (case-insensitive). Ignores tier — explicit intent wins. */
+export declare function findTopic(index: DocsIndex, slug: string): DocIndexEntry | undefined;
+/**
+ * Ranked query results are capped so a broad term (e.g. one that hits a chunk
+ * of the ~390 generated error-reference entries) can never return the whole
+ * catalog in one response. Listing a tier with no query is unaffected — that's
+ * an intentional "show me everything at this tier" request, not a search.
+ */
+export declare const SEARCH_DOCS_RESULT_LIMIT = 25;
+/**
+ * Rank docs matching `query` within the tier. Empty query returns the full tier
+ * listing (catalog order), uncapped. A non-empty query ranks matches and caps
+ * the result count at {@link SEARCH_DOCS_RESULT_LIMIT}.
+ */
+export declare function searchDocs(index: DocsIndex, options: {
+    query?: string;
+    tier: CliDisclosureTier;
+}): DocIndexEntry[];
+/**
+ * Resolve the `sf docs [query]` request: an exact-slug query prints that topic;
+ * any other query searches; an empty query lists the tier. Pure + offline.
+ */
+export declare function resolveDocsCommand(index: DocsIndex, options: {
+    query?: string;
+    tier: CliDisclosureTier;
+}): DocsCommandResult;