@spacefast/common 0.0.5 → 0.0.7

package/dist/utils/static-runtime-policy.js

@@ -46,19 +46,17 @@ export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
 export const NON_IMMUTABLE_EXTENSIONS = ["html", "htm", "php", "txt", "xml"];
 const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
 const NON_IMMUTABLE_EXTENSION_SET = new Set(NON_IMMUTABLE_EXTENSIONS);
-// Two real bundler content-hash shapes. (A) lowercase hex (git/webpack short
-// SHAs, many tools): >=7 chars of [0-9a-f]. (B) base64url (Vite/Rollup/esbuild/
-// Next): >=8 chars of [A-Za-z0-9_-]. Both forms are recognized; the entropy
-// guards in looksLikeBundlerFingerprint are what keep human names out.
-const HEX_FINGERPRINT = /^[0-9a-f]{7,}$/;
-const BASE64URL_FINGERPRINT = /^[A-Za-z0-9_-]{8,}$/;
-// Durable path-convention layer over the filename-entropy heuristic
-// (looksLikeBundlerFingerprint). These are reserved build-output directories that the
-// framework OWNS and fills exclusively with content-addressed ([contenthash]) output by
-// construction — so every asset served from under them is safe to pin immutable for a
-// year regardless of how its individual filename reads. This recovers the real hashes the
-// filename heuristic conservatively MISSES (no-digit / single-case base64url draws like
-// `oton0Guf`, `DYyuCeEr`) without loosening the heuristic itself.
+// Immutable caching is decided by DETERMINISTIC signals only — reserved framework
+// build directories below, plus user-declared `_headers` Cache-Control rules that
+// override the baked default at serve time. There is deliberately NO filename-entropy
+// heuristic: an 8-char base64url bundler hash is character-for-character
+// indistinguishable from a short human name (D3GeoMap, McKayCV2), so any guess either
+// pins a user's mutable file for a year (stale site nobody can fix — browsers have no
+// bust channel) or silently downgrades real hashes to revalidate-every-load, which
+// under the wp.cloud edge per-IP rate limiter turned dashboard page loads into 429
+// storms (2026-07-06). Unrecognized files default to the safe direction:
+// `max-age=0, must-revalidate` for browsers, long s-maxage + purge-on-publish at the
+// edge.
 //
 // Each prefix is HIGH-CONFIDENCE guaranteed-hashed:
 //   - `_next/static/`   Next.js immutable build assets (chunks/css/media), all
@@ -71,9 +69,10 @@ const BASE64URL_FINGERPRINT = /^[A-Za-z0-9_-]{8,}$/;
 //
 // DELIBERATELY EXCLUDED: generic user-writable dirs (Vite's `assets/`, CRA/Gatsby's
 // `static/`). Users drop NON-hashed files there, so widening to them would create
-// year-long false positives. Those stay gated by the filename heuristic only. This layer
-// is purely ADDITIVE: it can only turn a heuristic-`false` into `true` for assets under a
-// guaranteed-hashed dir; it never flips a `true` to `false`.
+// year-long false positives. Deployments of bundler output declare those dirs immutable
+// themselves via a `_headers` rule (e.g. `/assets/*` → `Cache-Control: public,
+// max-age=31536000, immutable`), which the publisher — a build we ran, an agent, a CI
+// deploy — writes because it KNOWS the output is content-hashed.
 export const GUARANTEED_IMMUTABLE_PREFIXES = [
     "_next/static/",
     "_app/immutable/",
@@ -109,97 +108,14 @@ export function pathStem(filePath) {
 export function isPhpLikeStaticPath(filePath) {
     return PHP_LIKE_EXTENSION_SET.has(pathExtension(filePath));
 }
-/**
- * Classifies a candidate hash token — the final `.`/`-`-delimited tail of a
- * filename stem (see isImmutableAssetPath) — as a real bundler content hash.
- *
- * Immutable caching is a one-year pin, so the test is asymmetric on purpose: a
- * missed hash costs a cheap 304 revalidation, a false positive serves stale
- * content for a year. When a token is ambiguous we say no. The discriminator is
- * NOT character case — modern bundlers emit BOTH lowercase-hex and mixed-case
- * base64url hashes — it is entropy plus the absence of dictionary-word shape.
- *
- * IRREDUCIBLE LIMIT: an 8-char base64url token is the same size as a short
- * CamelCase-with-version-digit human name, and every default Vite/Rollup hash we
- * must accept carries only one digit (BzeDGMM3, 4A_iFExJ). So a token like
- * `D3GeoMap`, `McKayCV2`, or `v2-WebGL` is character-for-character indistinguishable
- * from a real hash and is accepted by clause B. No filename-only rule can separate
- * these without also rejecting the bundler hashes the spec mandates. The durable
- * fix is to gate immutable caching on path convention (Vite `assets/`, Next
- * `_next/static/`, SvelteKit `_app/immutable/`, …) rather than guessing from the
- * stem; this heuristic is the best-effort fallback when that context is absent.
- */
-export function looksLikeBundlerFingerprint(segment) {
-    // (A) Lowercase-hex hash (git short-SHA, webpack/Vite/Gatsby `[contenthash]`):
-    // a1b2c3d, 3f9a2b7e, d41d8cd98f00b204e980. Always require >=1 hex letter and
-    // >=1 digit so all-letter words (deadbeef) and digit-only runs (1234567) are out.
-    if (HEX_FINGERPRINT.test(segment) && /[a-f]/.test(segment) && /[0-9]/.test(segment)) {
-        // A long all-hex token is unambiguous: no human authors a 16+ char hex name, so
-        // length alone is entropy proof and the anti-word guards would only lose real
-        // hashes (most 16/20-char contenthashes contain an incidental 4-run).
-        if (segment.length >= 16) {
-            return true;
-        }
-        // Short hex (7-15) overlaps with hex-spelled words/years/colors, so require >=2
-        // digits and forbid a run of 4+ hex letters (deadbeef, cafe, face, decade) or
-        // 4+ digits (2024, 1234) — low-entropy human false positives.
-        if ((segment.match(/[0-9]/g) ?? []).length >= 2 &&
-            !/[a-f]{4}/.test(segment) &&
-            !/[0-9]{4}/.test(segment)) {
-            return true;
-        }
-    }
-    // (B) Base64url hash (Vite/Rollup/esbuild/Next): BzeDGMM3, 4A_iFExJ, P1Tx-Cyu,
-    // Z-cBR0Xb, 9-ygPMte. Random base64url draws — but immutable is a one-year pin, so
-    // against the human names that mimic this shape (acronym data/UI names, version
-    // and fiscal labels, dates, resolutions) we demand the full BALANCED-entropy
-    // signature of a real hash, and accept the safe cost of missing the minority of
-    // genuine hashes that fall short (a cheap 304):
-    //   - >=2 lowercase AND >=2 uppercase letters. Real base64url hashes carry several
-    //     of each; acronym-dominant human names (USMap-AKHIORWA, Map-USA_CA_TX,
-    //     MyCSS2DUI) have at most one lowercase token and are rejected here. This also
-    //     conservatively drops single-case and no-/one-lowercase hashes (DYyuCeEr,
-    //     ChJ_j-JJ) — the safe miss direction.
-    //   - at least one digit. ~1/4 of base64url hashes lack one and become cheap 304s,
-    //     but requiring it removes the all-letter acronym names that are otherwise
-    //     indistinguishable from a hash (USMap-AKHIORWA has no digit).
-    //   - no run of 3+ lowercase letters: a dictionary-word body (MyComponent
-    //     "omponent", LoginOAuth2 "ogin", HTTPClient2 "lient"). A packed hash breaks
-    //     lowercase up with caps/digits.
-    //   - no run of 2+ digits: clustered digits are human years/resolutions/sequences/
-    //     dates (2024, 1080, Win10, 01); a hash scatters single digits between letters.
-    // <8 chars (Widget2, API2, v2) never qualifies via the regex length floor.
-    if (BASE64URL_FINGERPRINT.test(segment) &&
-        (segment.match(/[a-z]/g) ?? []).length >= 2 &&
-        (segment.match(/[A-Z]/g) ?? []).length >= 2 &&
-        /[0-9]/.test(segment) &&
-        !/[a-z]{3}/.test(segment) &&
-        !/[0-9]{2}/.test(segment)) {
-        return true;
-    }
-    return false;
-}
 export function isImmutableAssetPath(filePath) {
     if (NON_IMMUTABLE_EXTENSION_SET.has(pathExtension(filePath))) {
         return false;
     }
-    // Path-convention layer (additive): anything under a guaranteed-content-hashed
-    // framework build dir is immutable regardless of filename. The extension gate above
-    // still applies, so an `index.html` accidentally under `_next/static/` is never pinned.
-    if (isUnderGuaranteedImmutablePrefix(filePath)) {
-        return true;
-    }
-    // Fallback for assets OUTSIDE those dirs: the filename-entropy heuristic.
-    const stem = pathStem(filePath);
-    for (let index = 0; index < stem.length; index += 1) {
-        if (index > 0 && stem[index - 1] !== "." && stem[index - 1] !== "-") {
-            continue;
-        }
-        if (looksLikeBundlerFingerprint(stem.slice(index))) {
-            return true;
-        }
-    }
-    return false;
+    // Path-convention layer: anything under a guaranteed-content-hashed framework build
+    // dir is immutable regardless of filename. The extension gate above still applies,
+    // so an `index.html` accidentally under `_next/static/` is never pinned.
+    return isUnderGuaranteedImmutablePrefix(filePath);
 }
 /** Forced inert serving policy for a committed static file. PHP-like files are never executable. */
 export function runtimeFileSafety(filePath) {

package/dist/utils/upload-session.d.ts

@@ -28,7 +28,7 @@ export declare function executeUploadSession(input: {
     session: UploadSession;
     targets?: readonly UploadTarget[] | undefined;
     concurrency?: number | undefined;
-    fetch?: typeof fetch | undefined;
+    fetch?: ((...args: Parameters<typeof fetch>) => ReturnType<typeof fetch>) | undefined;
     prepareTarget?: ((target: UploadTarget) => Promise<UploadTargetBody> | UploadTargetBody) | undefined;
     onEvent?: ((event: UploadSessionEvent) => void) | undefined;
 }): Promise<void>;

package/dist/utils/wpcom-auth-redirects.d.ts

@@ -1,11 +1,41 @@
 export type LoginIntentSearch = {
     direct?: boolean | undefined;
     returnTo?: string | undefined;
+    /** Route straight to WordPress.com's signup page instead of its login page. */
+    signup?: boolean | undefined;
 };
+/**
+ * Optional query params WordPress.com's OAuth2 authorize endpoint understands
+ * (wpcom `wp-content/mu-plugins/oauth2/oauth2.php`). All are cosmetic/flow
+ * hints — dropping them never breaks the OAuth handshake.
+ */
+export type WpcomAuthorizeExtras = {
+    /** Prefills the email field on the WP.com login screen (`user_email`). */
+    userEmail?: string | undefined;
+    /** Localizes the WP.com login/consent/signup screens (`locale`). */
+    locale?: string | undefined;
+    /**
+     * `implicit=false`: WP.com signs the user out of WordPress.com and shows a
+     * fresh login instead of silently reusing the current WP.com session. The
+     * only way to let a user switch WP.com accounts — without it, sign-out on
+     * our side loops them straight back into the same account.
+     */
+    switchAccount?: boolean | undefined;
+    /** `new-user=1`: routes straight to the WP.com signup page. */
+    signup?: boolean | undefined;
+};
+export declare function decorateWpcomAuthorizeUrl(authorizeUrl: string, extras?: WpcomAuthorizeExtras): string;
 export declare function buildDashboardLoginPath(input: LoginIntentSearch): string;
-export declare function buildWpcomAuthStartPath(input: LoginIntentSearch): string;
+export declare function buildWpcomAuthStartPath(input: LoginIntentSearch & {
+    /**
+     * A signed OAuth authorize query (Better Auth's login-page redirect).
+     * Carried through the WordPress.com round trip so the auth server can
+     * resume the authorization flow the moment the session exists. Opaque
+     * here — the auth server verifies its signature.
+     */
+    oauthQuery?: string | undefined;
+}): string;
 export declare function buildPostAuthPath(input: LoginIntentSearch): string;
-export declare function buildWpcomLoginUrl(authorizeUrl: string): string;
 export declare function buildWpcomSignInOptions(input: LoginIntentSearch, dashboardOrigin: string): {
     readonly provider: "wpcom";
     readonly callbackURL: string;

package/dist/utils/wpcom-auth-redirects.js

@@ -1,4 +1,24 @@
 import { sanitizeDashboardReturnTo } from "@spacefast/common/utils/auth-redirect";
+export function decorateWpcomAuthorizeUrl(authorizeUrl, extras = {}) {
+    const url = new URL(authorizeUrl);
+    const email = extras.userEmail?.trim();
+    if (email && email.includes("@") && email.length <= 254) {
+        url.searchParams.set("user_email", email);
+    }
+    // WP.com validates locales against its own list and falls back to English,
+    // so a light shape check is enough here. English is the default — omit it.
+    const locale = extras.locale?.trim().toLowerCase().replace("_", "-");
+    if (locale && /^[a-z]{2}(-[a-z]{2})?$/.test(locale) && locale !== "en") {
+        url.searchParams.set("locale", locale);
+    }
+    if (extras.switchAccount) {
+        url.searchParams.set("implicit", "false");
+    }
+    if (extras.signup) {
+        url.searchParams.set("new-user", "1");
+    }
+    return url.toString();
+}
 export function buildDashboardLoginPath(input) {
     const url = new URL("/sign-in", "http://dashboard.local");
     if (input.direct) {
@@ -16,6 +36,12 @@ export function buildWpcomAuthStartPath(input) {
     if (returnTo) {
         url.searchParams.set("returnTo", returnTo);
     }
+    if (input.signup) {
+        url.searchParams.set("signup", "1");
+    }
+    if (input.oauthQuery) {
+        url.searchParams.set("oauth_query", input.oauthQuery);
+    }
     return `${url.pathname}${url.search}`;
 }
 export function buildPostAuthPath(input) {
@@ -27,16 +53,6 @@ export function buildPostAuthPath(input) {
     }
     return `${url.pathname}${url.search}`;
 }
-export function buildWpcomLoginUrl(authorizeUrl) {
-    const authUrl = new URL(authorizeUrl);
-    const loginUrl = new URL("https://wordpress.com/log-in");
-    const clientId = authUrl.searchParams.get("client_id");
-    if (clientId) {
-        loginUrl.searchParams.set("client_id", clientId);
-    }
-    loginUrl.searchParams.set("redirect_to", authUrl.toString());
-    return loginUrl.toString();
-}
 export function buildWpcomSignInOptions(input, dashboardOrigin) {
     const errorCallbackUrl = new URL(buildDashboardLoginPath(input), dashboardOrigin);
     errorCallbackUrl.searchParams.set("claim_error", "login");

package/dist/vocabulary.d.ts

@@ -56,7 +56,7 @@ export declare const CONCEPTS: {
         readonly canonicalNoun: "version";
         readonly verb: "publish";
         readonly aliases: readonly [];
-        readonly deprecated: readonly ["deployment"];
+        readonly externalTerms: readonly ["deployment"];
         readonly description: string;
     };
     readonly channel: {
@@ -133,7 +133,7 @@ export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
     readonly concept: "publish";
     readonly allowedContexts: readonly ["github-integration", "platform-api"];
     readonly replacement: "publish";
-    readonly reason: "Push-deploys and the deploy status come from the GitHub integration.";
+    readonly reason: string;
 }, {
     readonly term: "site";
     readonly concept: "space";
@@ -148,6 +148,44 @@ export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
     readonly replacement: "infra";
     readonly reason: string;
 }];
+/**
+ * AMENDMENT (DECIDED 2026-07-02): the deploy vocabulary stays, as documented,
+ * first-class ALIASES of the canonical vocabulary — `deploy` is an alias of
+ * `publish` (the verb) and `deployments` is an alias of `versions` (the noun).
+ * The canonical lifecycle nouns are unchanged: version / channel / build.
+ *
+ * This relaxes the earlier total noun ban to alias-with-disambiguation:
+ *
+ *   - `sf deploy` / `sf deployments` stay listed and documented; every surface
+ *     that presents them names the canonical command first and marks the
+ *     deploy form as an alias.
+ *   - Wherever the alias is introduced, attach DEPLOY_ALIAS_DISAMBIGUATION
+ *     (the one sanctioned disambiguation sentence) so readers land on the
+ *     canonical nouns.
+ *   - A bare "deployment" noun in FRESH prose is still discouraged — write
+ *     "version" (the thing) or "publish" (the act) unless deliberately using
+ *     the alias, in which case disambiguate.
+ */
+export interface DeployAlias {
+    /** The deploy-vocabulary word being sanctioned. */
+    readonly alias: string;
+    /** The canonical word it is an alias of. */
+    readonly canonical: string;
+}
+export declare const DEPLOY_ALIASES: readonly [{
+    readonly alias: "deploy";
+    readonly canonical: "publish";
+}, {
+    readonly alias: "deployments";
+    readonly canonical: "versions";
+}];
+/**
+ * THE sanctioned disambiguation copy. Surfaces that present the deploy
+ * vocabulary (CLI --help, handbook/reference docs, generated skill docs) carry
+ * this sentence verbatim next to the alias, with the canonical command named
+ * first.
+ */
+export declare const DEPLOY_ALIAS_DISAMBIGUATION: string;
 /** An internal provider name and how it must be referred to in public copy. */
 export interface ProviderHygieneRule {
     /** Internal/vendor name that must not appear on public surfaces. */
@@ -187,34 +225,11 @@ export declare const PROVIDER_HYGIENE: {
         readonly reason: "Internal git/CI dependency; never surfaced.";
     };
 };
-export type ProviderHygieneId = keyof typeof PROVIDER_HYGIENE;
 /**
- * Canonical MCP tool naming. Tools are exposed under a namespaced canonical id
- * (`spacefast_<verb>`) plus a bare alias (`<verb>`) for clients where per-server
- * namespacing is already guaranteed.
- *
- * This replaces the current inverted form (`execute_spacefast`,
- * `resume_spacefast`) and the un-namespaced verbs (`publish`, `prepare_publish`).
- */
-export declare const MCP_TOOL_NAMING: {
-    /** Prefix that makes a tool id unambiguous across servers. */
-    readonly namespacePrefix: "spacefast_";
-    /** Canonical, namespaced tool id for a verb (e.g. "publish" → "spacefast_publish"). */
-    readonly canonical: (verb: string) => string;
-    /** Bare alias for a verb, valid only where per-server namespacing is guaranteed. */
-    readonly alias: (verb: string) => string;
-    /** Both names a verb should register under. */
-    readonly names: (verb: string) => {
-        readonly canonical: string;
-        readonly alias: string;
-    };
-};
-/**
- * Verbs that have a locked canonical MCP tool name. Generators should emit
- * `spacefast_<verb>` as the primary id and `<verb>` as the bare alias.
+ * Verbs that have a locked canonical MCP tool name. Generators emit the bare
+ * `<verb>` as the one and only tool id.
  */
-export declare const MCP_CANONICAL_VERBS: readonly ["publish", "execute", "prepare_publish", "resume_publish", "finalize_publish"];
-export type McpCanonicalVerb = (typeof MCP_CANONICAL_VERBS)[number];
+export declare const MCP_CANONICAL_VERBS: readonly ["publish", "execute", "search", "resume", "prepare_publish", "resume_publish", "finalize_publish"];
 /**
  * Canonical CLI verb → accepted aliases. Reused across command groups so every
  * `list`/`remove`/`create` command exposes the same shorthands. A command file
@@ -226,5 +241,90 @@ export declare const CLI_ALIASES: {
     readonly create: readonly ["add"];
 };
 export type CliCanonicalVerb = keyof typeof CLI_ALIASES;
-/** Aliases registered for a canonical CLI verb (empty for unknown verbs). */
-export declare function cliAliasesFor(verb: CliCanonicalVerb): readonly string[];
+/**
+ * Disclosure tiers gate how much of a surface (CLI help, `sf docs`) shows by
+ * default, so neither humans nor agents are overwhelmed:
+ *
+ *   - `essential` — the handful of commands/docs a new user or agent needs to
+ *     make a first publish and manage a space. The default everywhere.
+ *   - `full` — the complete product CLI surface (everything not hidden).
+ *   - `reference` — absolutely everything, including hidden/advanced commands.
+ *
+ * Tiers are cumulative for ranked surfaces (`reference` ⊇ `full` ⊇ `essential`);
+ * see {@link tierVisibleAt}. This is THE source of truth for tier ids + labels.
+ */
+export type CliDisclosureTier = "essential" | "full" | "reference";
+/** Display metadata for one disclosure tier. */
+export interface CliDisclosureTierMeta {
+    readonly id: CliDisclosureTier;
+    /** Human label for headers (`Essential commands`, etc.). */
+    readonly label: string;
+    /** One-line description of what the tier reveals. */
+    readonly description: string;
+    /** Flag that opts into this tier (absent for the default `essential`). */
+    readonly flag?: string;
+}
+export declare const CLI_DISCLOSURE_TIERS: {
+    readonly essential: {
+        readonly id: "essential";
+        readonly label: "Essential";
+        readonly description: "The handful of commands a new user or agent needs to publish and manage a space.";
+    };
+    readonly full: {
+        readonly id: "full";
+        readonly label: "Full";
+        readonly description: "Every command in the product CLI.";
+        readonly flag: "--full";
+    };
+    readonly reference: {
+        readonly id: "reference";
+        readonly label: "Reference";
+        readonly description: "Everything, including hidden and advanced commands.";
+        readonly flag: "--all";
+    };
+};
+/** Tiers ordered narrowest-first; index doubles as the cumulative rank. */
+export declare const CLI_DISCLOSURE_TIER_ORDER: readonly ["essential", "full", "reference"];
+/**
+ * Does a surface tagged `surfaceTier` show when viewing at `viewTier`? Ranked
+ * surfaces are cumulative: an `essential` doc shows at every tier, a `full` doc
+ * shows at `full`/`reference`, a `reference` doc only at `reference`.
+ */
+export declare function tierVisibleAt(viewTier: CliDisclosureTier, surfaceTier: CliDisclosureTier): boolean;
+/** One essential CLI verb and the registered command id it resolves to. */
+export interface CliEssentialCommand {
+    /** The verb a new user reaches for. */
+    readonly verb: string;
+    /** The registered CLI command id (some live under a topic, e.g. `spaces:claim`). */
+    readonly commandId: string;
+}
+/**
+ * The first-publish path: the essential verbs `sf help` (and `sf docs`) surface
+ * by default. Everything else is FULL (shown with `--full`) or REFERENCE
+ * (hidden/advanced, shown with `--all`). Ordered for display.
+ */
+export declare const CLI_ESSENTIAL_COMMANDS: readonly [{
+    readonly verb: "publish";
+    readonly commandId: "publish";
+}, {
+    readonly verb: "status";
+    readonly commandId: "status";
+}, {
+    readonly verb: "versions";
+    readonly commandId: "versions";
+}, {
+    readonly verb: "rollback";
+    readonly commandId: "rollback";
+}, {
+    readonly verb: "claim";
+    readonly commandId: "spaces:claim";
+}, {
+    readonly verb: "login";
+    readonly commandId: "login";
+}, {
+    readonly verb: "init";
+    readonly commandId: "init";
+}, {
+    readonly verb: "docs";
+    readonly commandId: "docs";
+}];

package/dist/vocabulary.js

@@ -11,10 +11,12 @@
 //   - `space` is the primitive noun on every user surface. `site` survives only
 //     as the platform-API term for the shared-pool host a space is placed on
 //     (see contracts/sites.ts, internal-docs/platform.md "Site").
-//   - `publish` is the verb. "deployment" is NOT a product noun — it means
-//     "publishing a version" and is retired from user-facing surfaces (drop the
-//     `dep_*` framing). It stays only inside the GitHub integration and the
-//     platform API (see EXTERNAL_TERM_ALLOWLIST).
+//   - `publish` is the verb. AMENDED 2026-07-02: `deploy` / `deployments` are
+//     first-class ALIASES of `publish` / `versions` (see DEPLOY_ALIASES) — they
+//     stay listed and documented, always with the sanctioned disambiguation
+//     line (DEPLOY_ALIAS_DISAMBIGUATION) and with the canonical command named
+//     first. A bare "deployment" noun in fresh prose is still discouraged (say
+//     "version"), and the `dep_*` id framing stays retired.
 //   - `version` / `channel` / `build` are the lifecycle nouns.
 //   - `API key` — never "access token".
 //   - `Collab` is the feature; `comment` is the unit.
@@ -40,17 +42,19 @@ export const CONCEPTS = {
         aliases: ["go live"],
         externalTerms: ["deployment", "deploy"],
         deprecated: ["dep_", "dep_build_", "dep_version_"],
-        description: "The verb for making a version live. 'Deployment' is not a product noun " +
-            "(it just means publishing a version); allowed only in GitHub + platform API.",
+        description: "The verb for making a version live. 'Deploy' is a sanctioned first-class " +
+            "alias of publish (see DEPLOY_ALIASES); introduce it with the " +
+            "disambiguation line, and keep fresh prose on 'publish'.",
     },
     version: {
         id: "version",
         canonicalNoun: "version",
         verb: "publish",
         aliases: [],
-        deprecated: ["deployment"],
+        externalTerms: ["deployment"],
         description: "An immutable snapshot of a space's content. Publishing promotes a version " +
-            "to a channel; the thing once mislabeled a 'deployment' is a version.",
+            "to a channel; a 'deployment' is a sanctioned alias for a version (see " +
+            "DEPLOY_ALIASES), though fresh prose still says 'version'.",
     },
     channel: {
         id: "channel",
@@ -109,14 +113,18 @@ export const EXTERNAL_TERM_ALLOWLIST = [
         allowedContexts: ["github-integration", "platform-api"],
         replacement: "version / publish",
         reason: "GitHub speaks 'deployment'; the platform API keeps it for contract " +
-            "stability. Everywhere else say 'publish a version'.",
+            "stability. Elsewhere it is a sanctioned alias of 'version' when paired " +
+            "with DEPLOY_ALIAS_DISAMBIGUATION (see DEPLOY_ALIASES); bare fresh prose " +
+            "still says 'publish a version'.",
     },
     {
         term: "deploy",
         concept: "publish",
         allowedContexts: ["github-integration", "platform-api"],
         replacement: "publish",
-        reason: "Push-deploys and the deploy status come from the GitHub integration.",
+        reason: "Push-deploys and the deploy status come from the GitHub integration; " +
+            "'deploy' is also a sanctioned first-class alias of 'publish' when paired " +
+            "with DEPLOY_ALIAS_DISAMBIGUATION (see DEPLOY_ALIASES).",
     },
     {
         term: "site",
@@ -136,6 +144,18 @@ export const EXTERNAL_TERM_ALLOWLIST = [
             "the provider; general copy says 'infra'.",
     },
 ];
+export const DEPLOY_ALIASES = [
+    { alias: "deploy", canonical: "publish" },
+    { alias: "deployments", canonical: "versions" },
+];
+/**
+ * THE sanctioned disambiguation copy. Surfaces that present the deploy
+ * vocabulary (CLI --help, handbook/reference docs, generated skill docs) carry
+ * this sentence verbatim next to the alias, with the canonical command named
+ * first.
+ */
+export const DEPLOY_ALIAS_DISAMBIGUATION = "Deploying is publishing: a deployment is a version, and the canonical " +
+    "nouns are version, channel, and build.";
 export const PROVIDER_HYGIENE = {
     e2b: {
         internalName: "E2B",
@@ -168,33 +188,14 @@ export const PROVIDER_HYGIENE = {
 /* MCP tool naming                                                             */
 /* -------------------------------------------------------------------------- */
 /**
- * Canonical MCP tool naming. Tools are exposed under a namespaced canonical id
- * (`spacefast_<verb>`) plus a bare alias (`<verb>`) for clients where per-server
- * namespacing is already guaranteed.
- *
- * This replaces the current inverted form (`execute_spacefast`,
- * `resume_spacefast`) and the un-namespaced verbs (`publish`, `prepare_publish`).
- */
-export const MCP_TOOL_NAMING = {
-    /** Prefix that makes a tool id unambiguous across servers. */
-    namespacePrefix: "spacefast_",
-    /** Canonical, namespaced tool id for a verb (e.g. "publish" → "spacefast_publish"). */
-    canonical: (verb) => `spacefast_${verb}`,
-    /** Bare alias for a verb, valid only where per-server namespacing is guaranteed. */
-    alias: (verb) => verb,
-    /** Both names a verb should register under. */
-    names: (verb) => ({
-        canonical: `spacefast_${verb}`,
-        alias: verb,
-    }),
-};
-/**
- * Verbs that have a locked canonical MCP tool name. Generators should emit
- * `spacefast_<verb>` as the primary id and `<verb>` as the bare alias.
+ * Verbs that have a locked canonical MCP tool name. Generators emit the bare
+ * `<verb>` as the one and only tool id.
  */
 export const MCP_CANONICAL_VERBS = [
     "publish",
     "execute",
+    "search",
+    "resume",
     "prepare_publish",
     "resume_publish",
     "finalize_publish",
@@ -212,7 +213,47 @@ export const CLI_ALIASES = {
     remove: ["rm", "delete"],
     create: ["add"],
 };
-/** Aliases registered for a canonical CLI verb (empty for unknown verbs). */
-export function cliAliasesFor(verb) {
-    return CLI_ALIASES[verb];
+export const CLI_DISCLOSURE_TIERS = {
+    essential: {
+        id: "essential",
+        label: "Essential",
+        description: "The handful of commands a new user or agent needs to publish and manage a space.",
+    },
+    full: {
+        id: "full",
+        label: "Full",
+        description: "Every command in the product CLI.",
+        flag: "--full",
+    },
+    reference: {
+        id: "reference",
+        label: "Reference",
+        description: "Everything, including hidden and advanced commands.",
+        flag: "--all",
+    },
+};
+/** Tiers ordered narrowest-first; index doubles as the cumulative rank. */
+export const CLI_DISCLOSURE_TIER_ORDER = ["essential", "full", "reference"];
+/**
+ * Does a surface tagged `surfaceTier` show when viewing at `viewTier`? Ranked
+ * surfaces are cumulative: an `essential` doc shows at every tier, a `full` doc
+ * shows at `full`/`reference`, a `reference` doc only at `reference`.
+ */
+export function tierVisibleAt(viewTier, surfaceTier) {
+    return (CLI_DISCLOSURE_TIER_ORDER.indexOf(surfaceTier) <= CLI_DISCLOSURE_TIER_ORDER.indexOf(viewTier));
 }
+/**
+ * The first-publish path: the essential verbs `sf help` (and `sf docs`) surface
+ * by default. Everything else is FULL (shown with `--full`) or REFERENCE
+ * (hidden/advanced, shown with `--all`). Ordered for display.
+ */
+export const CLI_ESSENTIAL_COMMANDS = [
+    { verb: "publish", commandId: "publish" },
+    { verb: "status", commandId: "status" },
+    { verb: "versions", commandId: "versions" },
+    { verb: "rollback", commandId: "rollback" },
+    { verb: "claim", commandId: "spaces:claim" },
+    { verb: "login", commandId: "login" },
+    { verb: "init", commandId: "init" },
+    { verb: "docs", commandId: "docs" },
+];