primitive-admin 1.0.53 → 1.0.55

package/dist/src/commands/guides.js

@@ -2,13 +2,97 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join, basename } from "path";
 import { error, info, warn, formatTable, json, keyValue, } from "../lib/output.js";
+import { getServerUrl } from "../lib/config.js";
+import { ALPHA_SERVER_URL } from "../lib/constants.js";
 const GUIDES_CACHE_DIR = process.env.PRIMITIVE_CONFIG_DIR
     ? join(process.env.PRIMITIVE_CONFIG_DIR, "guides")
     : join(homedir(), ".primitive", "guides");
 const CACHE_META_FILE = join(GUIDES_CACHE_DIR, "cache-meta.json");
-const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/Primitive-Labs/primitive-docs/main/guides";
+const GITHUB_RAW_ROOT = "https://raw.githubusercontent.com/Primitive-Labs/primitive-docs";
+const DEFAULT_DOCS_BRANCH = "main";
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const CLIENT_PACKAGE_NAME = "js-bao-wss-client";
+/**
+ * Normalize a server URL for comparison against `ALPHA_SERVER_URL`: keep the
+ * scheme/host/port, strip all trailing slashes from the pathname. Returns null
+ * for an unparseable value. `http` vs `https` intentionally does NOT normalize
+ * to the same string (scheme is significant), and a custom domain is never an
+ * alias of the alpha constant.
+ */
+export function normalizeServerUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const path = u.pathname.replace(/\/+$/, "");
+        return `${u.protocol}//${u.host}${path}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is `value` a plausible git branch ref that is safe to interpolate into a raw
+ * GitHub URL path? Deliberately strict — only ASCII letters/digits and
+ * `._/-`, no leading dash, no `..`, capped length. This guards the
+ * `PRIMITIVE_GUIDES_BRANCH` override so no arbitrary string reaches the URL.
+ */
+export function isValidBranchName(value) {
+    if (value.length === 0 || value.length > 100)
+        return false;
+    if (value.includes(".."))
+        return false;
+    return /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value);
+}
+/**
+ * Resolve which `primitive-docs` branch to fetch guides from.
+ *
+ * Precedence (issue #1463):
+ *   1. `PRIMITIVE_GUIDES_BRANCH` override (undocumented, internal). Takes
+ *      precedence over detection. An empty value is ignored; a value that is
+ *      not a plausible git ref is rejected (throws) so no arbitrary string is
+ *      interpolated into a raw GitHub URL.
+ *   2. Alpha detection: a normalized-URL match of the resolved server URL
+ *      against `ALPHA_SERVER_URL` → `next`.
+ *   3. Otherwise `main` (production / local / any non-alpha target, or no
+ *      target at all when the CLI is logged out).
+ *
+ * Pure and side-effect free: the caller passes the resolved server URL (or
+ * `undefined` when `getServerUrl()` threw) and the override, so this is fully
+ * unit-testable without config/credentials.
+ */
+export function resolveDocsBranch(serverUrl, override = process.env.PRIMITIVE_GUIDES_BRANCH) {
+    const trimmedOverride = override?.trim();
+    if (trimmedOverride) {
+        if (!isValidBranchName(trimmedOverride)) {
+            throw new Error(`Invalid PRIMITIVE_GUIDES_BRANCH "${override}": must be a plausible git branch name.`);
+        }
+        return trimmedOverride;
+    }
+    if (serverUrl) {
+        const target = normalizeServerUrl(serverUrl);
+        const alpha = normalizeServerUrl(ALPHA_SERVER_URL);
+        if (target !== null && alpha !== null && target === alpha) {
+            return "next";
+        }
+    }
+    return DEFAULT_DOCS_BRANCH;
+}
+/**
+ * Resolve the docs branch for the current invocation, reading the target from
+ * `getServerUrl()`. Logged-out / legacy-no-creds makes `getServerUrl()` throw;
+ * we treat that as "no target" and fall back to `main` (the override still
+ * applies). Only the branch decision is wrapped here — an invalid override
+ * still throws out to the command's error handler.
+ */
+function resolveDocsBranchForInvocation() {
+    let serverUrl;
+    try {
+        serverUrl = getServerUrl();
+    }
+    catch {
+        serverUrl = undefined;
+    }
+    return resolveDocsBranch(serverUrl);
+}
 // Language aliases — map the agent's natural vocabulary onto canonical values.
 const LANGUAGE_ALIASES = {
     typescript: "ts",
@@ -112,6 +196,84 @@ export function selectVariant(guide, request) {
     // 4. Nothing matched → the guide's default file (never throws).
     return { file: guide.file, matchedOn: "default" };
 }
+/**
+ * The global set of languages a manifest supports. Derived (never hardcoded)
+ * from: every guide variant's `language`, the manifest-level `defaults.language`
+ * (falling back to `"ts"` when absent), and every `platforms[*].language`. Used
+ * to validate `--language` and to render the `guides list` legend / `--json`.
+ *
+ * Derived per-request from the manifest ACTUALLY loaded (so it stays correct
+ * for stale-cache / `--guide-version` fallbacks), and grows automatically as
+ * new languages appear in the manifest — no CLI change needed.
+ */
+export function deriveLanguages(manifest) {
+    const languages = new Set();
+    for (const guide of manifest.guides ?? []) {
+        for (const variant of guide.variants ?? []) {
+            if (variant.language !== undefined)
+                languages.add(variant.language);
+        }
+    }
+    languages.add(manifest.defaults?.language ?? "ts");
+    for (const entry of Object.values(manifest.platforms ?? {})) {
+        if (entry.language)
+            languages.add(entry.language);
+    }
+    return languages;
+}
+/**
+ * Validate the requested `(language, platform)` against the loaded manifest and
+ * resolve the effective language (issue #1219). Behavior:
+ *
+ *  - Normalizes both values first (lowercase + trim, aliases, `"" → undefined`)
+ *    via the existing `normalizeLanguage`/`normalizePlatform` helpers, then
+ *    validates the NORMALIZED value.
+ *  - `--language` is validated against `deriveLanguages(manifest)` whether or
+ *    not a `platforms` block exists (the set is derivable from any manifest).
+ *  - `--platform` is validated + inferred ONLY when `manifest.platforms` is
+ *    present. With the block, an unknown platform is a hard error and a known
+ *    platform infers `language = platforms[p].language` (an explicit
+ *    `--language` always wins the language dimension). WITHOUT the block, the
+ *    platform passes through unvalidated and uninferred — today's non-enforcing
+ *    behavior, so older manifests / stale cache don't start hard-failing.
+ *  - Unknown values produce a hard-error message mirroring `init --platform`'s
+ *    style, plus a cross-hint when the bad value names the other dimension
+ *    (`--platform swift` → "Did you mean --language swift?", and vice versa).
+ */
+export function validateAndResolveRequest(manifest, rawLanguage, rawPlatform) {
+    const language = normalizeLanguage(rawLanguage);
+    const platform = normalizePlatform(rawPlatform);
+    const supportedLanguages = deriveLanguages(manifest);
+    const platforms = manifest.platforms; // may be undefined (back-compat)
+    // Validate --language (independent of the platforms block).
+    if (language !== undefined && !supportedLanguages.has(language)) {
+        const supported = [...supportedLanguages].sort().join(", ");
+        let message = `Unknown language "${language}". Supported languages: ${supported}`;
+        // Cross-hint: the value names a known platform, not a language.
+        if (platforms && platforms[language]) {
+            message += `. Did you mean --platform ${language}?`;
+        }
+        return { error: message };
+    }
+    let effectiveLanguage = language;
+    // Validate + infer --platform — active ONLY when the platforms block exists.
+    if (platform !== undefined && platforms !== undefined) {
+        if (!platforms[platform]) {
+            const supported = Object.keys(platforms).sort().join(", ");
+            let message = `Unknown platform "${platform}". Supported platforms: ${supported}`;
+            // Cross-hint: the value names a known language, not a platform
+            // (the reporter's exact `--platform swift` case).
+            if (supportedLanguages.has(platform)) {
+                message += `. Did you mean --language ${platform}?`;
+            }
+            return { error: message };
+        }
+        // Infer the language from the platform; an explicit --language wins.
+        effectiveLanguage = language ?? platforms[platform].language;
+    }
+    // else: no platforms block → back-compat pass-through (no validate, no infer).
+    return { language: effectiveLanguage, platform };
+}
 function detectClientVersion() {
     const clientPkgPath = join(process.cwd(), "node_modules", CLIENT_PACKAGE_NAME, "package.json");
     try {
@@ -159,18 +321,21 @@ function formatClientVersion(info) {
 function formatGuidesVersion(info) {
     return info.version;
 }
-function getVersionCacheDir(version) {
-    return join(GUIDES_CACHE_DIR, version);
+// Cache paths are segmented by branch (#1463): ~/.primitive/guides/{branch}/
+// {version}/... so a `next` fetch never overwrites the `main` cached copy of
+// the same version+filename (and vice versa).
+function getVersionCacheDir(branch, version) {
+    return join(GUIDES_CACHE_DIR, branch, version);
 }
-function getManifestPath(version) {
-    return join(getVersionCacheDir(version), "manifest.json");
+function getManifestPath(branch, version) {
+    return join(getVersionCacheDir(branch, version), "manifest.json");
 }
-function getGuidesCacheDir(version) {
-    return join(getVersionCacheDir(version), "guides");
+function getGuidesCacheDir(branch, version) {
+    return join(getVersionCacheDir(branch, version), "guides");
 }
-function ensureCacheDir(version) {
-    const versionDir = getVersionCacheDir(version);
-    const guidesDir = getGuidesCacheDir(version);
+function ensureCacheDir(branch, version) {
+    const versionDir = getVersionCacheDir(branch, version);
+    const guidesDir = getGuidesCacheDir(branch, version);
     if (!existsSync(versionDir)) {
         mkdirSync(versionDir, { recursive: true });
     }
@@ -201,11 +366,15 @@ function isCacheExpired(fetchedAt) {
     const fetchedTime = new Date(fetchedAt).getTime();
     return Date.now() - fetchedTime > CACHE_TTL_MS;
 }
-function getManifestUrl(version) {
-    return `${GITHUB_RAW_BASE}/${version}/guides.json`;
+/** The raw-GitHub base for a docs branch, e.g. `.../primitive-docs/next/guides`. */
+function githubRawBase(branch) {
+    return `${GITHUB_RAW_ROOT}/${branch}/guides`;
 }
-function getGuideUrl(version, fileName) {
-    return `${GITHUB_RAW_BASE}/${version}/${fileName}`;
+export function buildManifestUrl(branch, version) {
+    return `${githubRawBase(branch)}/${version}/guides.json`;
+}
+export function buildGuideUrl(branch, version, fileName) {
+    return `${githubRawBase(branch)}/${version}/${fileName}`;
 }
 async function fetchWithTimeout(url, timeoutMs = 10000) {
     const controller = new AbortController();
@@ -218,11 +387,26 @@ async function fetchWithTimeout(url, timeoutMs = 10000) {
         clearTimeout(timeout);
     }
 }
-async function fetchManifestForVersion(version, forceRefresh = false) {
-    ensureCacheDir(version);
+/**
+ * Thrown by `fetchManifest` when a branch/version genuinely has no published
+ * manifest — every candidate manifest URL returned 404. Distinct from a
+ * transport or server error (timeout, DNS, 5xx), which `fetchManifest` lets
+ * propagate as a plain `Error`. `resolveManifest` relies on this distinction:
+ * only a truly-absent branch may fall back to `main`; a transient failure must
+ * surface so an alpha/preview invocation is never silently downgraded to
+ * production `main` docs on a flake (#1463).
+ */
+export class ManifestNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ManifestNotFoundError";
+    }
+}
+async function fetchManifestForVersion(branch, version, forceRefresh = false) {
+    ensureCacheDir(branch, version);
     const meta = loadCacheMeta();
-    const manifestPath = getManifestPath(version);
-    const cacheExpired = isCacheExpired(meta.manifestFetchedAt?.[version]);
+    const manifestPath = getManifestPath(branch, version);
+    const cacheExpired = isCacheExpired(meta.manifestFetchedAt?.[branch]?.[version]);
     const hasCachedManifest = existsSync(manifestPath);
     // If cache is valid and not forcing refresh, use it
     if (!forceRefresh && !cacheExpired && hasCachedManifest) {
@@ -235,11 +419,11 @@ async function fetchManifestForVersion(version, forceRefresh = false) {
         }
     }
     // Try to fetch from network
-    const manifestUrl = getManifestUrl(version);
+    const manifestUrl = buildManifestUrl(branch, version);
     try {
         const response = await fetchWithTimeout(manifestUrl);
         if (response.status === 404) {
-            return null; // Version doesn't exist
+            return null; // Version (or branch) doesn't exist
         }
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -248,7 +432,8 @@ async function fetchManifestForVersion(version, forceRefresh = false) {
         // Save to cache
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
         meta.manifestFetchedAt = meta.manifestFetchedAt || {};
-        meta.manifestFetchedAt[version] = new Date().toISOString();
+        meta.manifestFetchedAt[branch] = meta.manifestFetchedAt[branch] || {};
+        meta.manifestFetchedAt[branch][version] = new Date().toISOString();
         saveCacheMeta(meta);
         return { manifest, fromCache: false, stale: false };
     }
@@ -266,15 +451,15 @@ async function fetchManifestForVersion(version, forceRefresh = false) {
         throw new Error(`Failed to fetch guides manifest: ${err.message}`);
     }
 }
-async function fetchManifest(versionInfo, forceRefresh = false) {
+async function fetchManifest(branch, versionInfo, forceRefresh = false) {
     // Try the requested version first
-    const result = await fetchManifestForVersion(versionInfo.version, forceRefresh);
+    const result = await fetchManifestForVersion(branch, versionInfo.version, forceRefresh);
     if (result) {
         return { ...result, versionInfo };
     }
     // Version not found, fall back to latest (unless already trying latest)
     if (versionInfo.version !== "latest") {
-        const fallbackResult = await fetchManifestForVersion("latest", forceRefresh);
+        const fallbackResult = await fetchManifestForVersion(branch, "latest", forceRefresh);
         if (fallbackResult) {
             const fallbackInfo = {
                 version: "latest",
@@ -285,18 +470,110 @@ async function fetchManifest(versionInfo, forceRefresh = false) {
             return { ...fallbackResult, versionInfo: fallbackInfo };
         }
     }
-    throw new Error(`Failed to fetch guides manifest for ${versionInfo.version}`);
+    // Every candidate URL 404'd — the branch/version is genuinely absent. Signal
+    // this with a typed error so `resolveManifest` can tell it apart from a
+    // transport/server error (which arrives as a plain `Error` from
+    // `fetchManifestForVersion`) and only fall back to `main` in the former case.
+    throw new ManifestNotFoundError(`Failed to fetch guides manifest for ${versionInfo.version}`);
 }
-async function fetchGuide(guide, version, request = {}, forceRefresh = false) {
-    ensureCacheDir(version);
+/**
+ * Fetch the manifest for `requestedBranch`, falling back to `main` **only when
+ * the non-`main` branch has no published manifest** — i.e. every candidate URL
+ * 404s and `fetchManifest` throws a `ManifestNotFoundError`. That fallback is
+ * what makes the alpha `next` target safe before `primitive-docs` publishes its
+ * `next` guides, and it covers a `PRIMITIVE_GUIDES_BRANCH` override that names a
+ * nonexistent branch.
+ *
+ * A transport or server error (timeout, DNS, 5xx) on the requested branch is
+ * NOT a missing branch — it arrives as a plain `Error` and is re-thrown, never
+ * downgraded to `main`. Silently serving production `main` docs for an
+ * alpha/preview invocation because of a transient flake would be wrong: a
+ * preview run must fail loudly rather than quietly return the wrong branch's
+ * docs (#1463).
+ */
+export async function resolveManifest(requestedBranch, versionInfo, forceRefresh = false) {
+    try {
+        const result = await fetchManifest(requestedBranch, versionInfo, forceRefresh);
+        return { ...result, branch: requestedBranch, requestedBranch, branchFellBack: false };
+    }
+    catch (err) {
+        // Only a genuinely-absent branch/version (a 404 on every candidate URL) may
+        // fall back to `main`. A transport/server error must surface — see the
+        // function doc.
+        if (!(err instanceof ManifestNotFoundError)) {
+            throw err;
+        }
+        if (requestedBranch === DEFAULT_DOCS_BRANCH) {
+            throw err; // already on main; nothing to fall back to
+        }
+        const result = await fetchManifest(DEFAULT_DOCS_BRANCH, versionInfo, forceRefresh);
+        return {
+            ...result,
+            branch: DEFAULT_DOCS_BRANCH,
+            requestedBranch,
+            branchFellBack: true,
+        };
+    }
+}
+/**
+ * One stderr line reporting the served docs branch, only when a non-`main`
+ * branch was requested (alpha detection or the override) — a plain `main`
+ * target prints nothing so stdout/stderr stay clean for the common case
+ * (#1463, behavior 8). Uses `info()` (stderr) so guide content on stdout is
+ * never polluted.
+ */
+function reportDocsBranch(resolved) {
+    if (resolved.requestedBranch === DEFAULT_DOCS_BRANCH)
+        return;
+    if (resolved.branchFellBack) {
+        info(`Guides branch: ${resolved.requestedBranch} unavailable; using main`);
+    }
+    else {
+        info(`Guides branch: ${resolved.requestedBranch}`);
+    }
+}
+/**
+ * Internal error thrown by `fetchGuide` on a non-ok guide-file response. NOT
+ * exported. `status` lets the `get` action distinguish a 404 (the cached
+ * manifest may name a file that was renamed/removed upstream — heal by
+ * refetching the manifest) from a transport error (keep the stale-cache
+ * fallback). `staleContent` carries the on-disk copy for the failed filename,
+ * if any, so the action can serve it as the option-(b) last resort (#1034).
+ */
+class GuideFetchError extends Error {
+    status;
+    selectedFile;
+    staleContent;
+    constructor(status, message, selectedFile, staleContent) {
+        super(message);
+        this.status = status;
+        this.selectedFile = selectedFile;
+        this.staleContent = staleContent;
+        this.name = "GuideFetchError";
+    }
+}
+/** Read an on-disk cached guide file, or undefined if absent/corrupted. */
+function readCachedGuide(cachedPath) {
+    if (!existsSync(cachedPath))
+        return undefined;
+    try {
+        return readFileSync(cachedPath, "utf-8");
+    }
+    catch {
+        return undefined; // corrupted cache
+    }
+}
+async function fetchGuide(guide, branch, version, request = {}, forceRefresh = false) {
+    ensureCacheDir(branch, version);
     const meta = loadCacheMeta();
     // Resolve the variant filename for the requested (language, platform).
     const { file: selectedFile } = selectVariant(guide, request);
     const guideFileName = basename(selectedFile);
-    const cachedPath = join(getGuidesCacheDir(version), guideFileName);
-    // Freshness is keyed by the RESOLVED filename (not topic) so a `ts` fetch
-    // cannot mark the `swift` variant fresh — and vice versa (#977).
-    const fetchedAt = meta.guidesFetchedAt?.[version]?.[guideFileName];
+    const cachedPath = join(getGuidesCacheDir(branch, version), guideFileName);
+    // Freshness is keyed by branch + the RESOLVED filename (not topic): a `ts`
+    // fetch cannot mark the `swift` variant fresh (#977), and a `next` fetch
+    // cannot mark the `main` copy of the same file fresh (#1463, behavior 7).
+    const fetchedAt = meta.guidesFetchedAt?.[branch]?.[version]?.[guideFileName];
     const cacheExpired = isCacheExpired(fetchedAt);
     const hasCachedGuide = existsSync(cachedPath);
     // If cache is valid and not forcing refresh, use it
@@ -310,9 +587,17 @@ async function fetchGuide(guide, version, request = {}, forceRefresh = false) {
         }
     }
     // Try to fetch from network
-    const guideUrl = getGuideUrl(version, selectedFile);
+    const guideUrl = buildGuideUrl(branch, version, selectedFile);
     try {
         const response = await fetchWithTimeout(guideUrl);
+        if (response.status === 404) {
+            // The cache-derived filename no longer exists upstream (a docs rename /
+            // removal). Let the 404 escape to the `get` action so it can refetch the
+            // manifest and re-resolve — heal must take priority over serving stale.
+            // Attach the on-disk copy (if any) so the action can serve it as the
+            // option-(b) last resort when the heal can't help (#1034).
+            throw new GuideFetchError(404, `Failed to fetch guide "${guide.topic}": HTTP 404: ${response.statusText}`, selectedFile, readCachedGuide(cachedPath));
+        }
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}: ${response.statusText}`);
         }
@@ -320,21 +605,23 @@ async function fetchGuide(guide, version, request = {}, forceRefresh = false) {
         // Save to cache
         writeFileSync(cachedPath, content);
         meta.guidesFetchedAt = meta.guidesFetchedAt || {};
-        meta.guidesFetchedAt[version] = meta.guidesFetchedAt[version] || {};
-        meta.guidesFetchedAt[version][guideFileName] = new Date().toISOString();
+        meta.guidesFetchedAt[branch] = meta.guidesFetchedAt[branch] || {};
+        meta.guidesFetchedAt[branch][version] = meta.guidesFetchedAt[branch][version] || {};
+        meta.guidesFetchedAt[branch][version][guideFileName] = new Date().toISOString();
         saveCacheMeta(meta);
         return { content, fromCache: false, stale: false, selectedFile };
     }
     catch (err) {
-        // Network failed, try stale cache
-        if (hasCachedGuide) {
-            try {
-                const content = readFileSync(cachedPath, "utf-8");
-                return { content, fromCache: true, stale: true, selectedFile };
-            }
-            catch {
-                // Cache corrupted
-            }
+        // A 404 must reach the action (heal takes priority over stale) — re-throw it
+        // unchanged rather than serving the stale copy here.
+        if (err instanceof GuideFetchError && err.status === 404) {
+            throw err;
+        }
+        // Non-404 (transport error / 5xx): serve the stale on-disk copy if present
+        // (Fork F — transport problems are not manifest skew), else throw.
+        const stale = readCachedGuide(cachedPath);
+        if (stale !== undefined) {
+            return { content: stale, fromCache: true, stale: true, selectedFile };
         }
         throw new Error(`Failed to fetch guide "${guide.topic}": ${err.message}`);
     }
@@ -347,23 +634,40 @@ function normalizeVariants(guide) {
         file: v.file,
     }));
 }
-/** Compact human-readable rendering of a guide's available combinations. */
-function formatCombinations(guide) {
+/**
+ * Compact rendering of the LANGUAGES a guide offers, for the `guides list`
+ * table (issue #1219 renamed the ambiguous `COMBINATIONS` column to
+ * `LANGUAGES`). Lists each variant's `language`, de-duplicated and order-
+ * preserving; a guide with no language-pinned variants renders `default`.
+ * Platforms are surfaced separately as a manifest-level legend, since they are
+ * a manifest-wide map rather than a per-guide attribute.
+ */
+export function formatLanguages(guide) {
     const variants = guide.variants ?? [];
     if (variants.length === 0)
         return "default";
-    const parts = variants.map((v) => {
-        if (v.language !== undefined && v.platform !== undefined) {
-            return `${v.language}_${v.platform}`;
-        }
-        if (v.language !== undefined)
-            return v.language;
-        if (v.platform !== undefined)
-            return v.platform;
+    const languages = variants
+        .map((v) => v.language)
+        .filter((l) => l !== undefined);
+    if (languages.length === 0)
         return "default";
-    });
-    // De-dupe while preserving order.
-    return [...new Set(parts)].join("; ");
+    return [...new Set(languages)].join("; ");
+}
+/**
+ * Render the manifest-level platform→language legend for `guides list`, e.g.
+ * `web -> ts, ios -> swift, macos -> swift`. When the manifest has no
+ * `platforms` block (older manifests / stale cache, before
+ * Primitive-Labs/primitive-docs#194), platforms aren't modeled yet, so this
+ * reports `none defined yet` rather than implying a map that doesn't exist.
+ */
+function formatPlatformsLegend(manifest) {
+    const platforms = manifest.platforms;
+    if (!platforms || Object.keys(platforms).length === 0) {
+        return "none defined yet";
+    }
+    return Object.entries(platforms)
+        .map(([platform, entry]) => `${platform} -> ${entry.language}`)
+        .join(", ");
 }
 export function registerGuidesCommands(program) {
     const guides = program
@@ -371,21 +675,25 @@ export function registerGuidesCommands(program) {
         .description("Access Primitive how-to guides for building apps")
         .addHelpText("after", `
 Examples:
-  $ primitive guides list                          # List available guides + combinations
+  $ primitive guides list                          # List available guides + languages
   $ primitive guides list --json                   # List as JSON for programmatic use
   $ primitive guides get documents                 # Fetch the default (TS) documents guide
   $ primitive guides get documents --language swift  # Fetch the Swift variant
-  $ primitive guides get documents --language swift --platform ios
+  $ primitive guides get documents --platform ios   # Fetch the platform's language (e.g. Swift)
   $ primitive guides list --guide-version 1        # List guides for client v1
   $ primitive guides list --guide-version latest   # List guides for the latest line
 
 Language & platform:
-  --language <ts|swift|...> and --platform <web|ios|macos|...> let the calling
-  agent request a specific guide variant. Aliases: typescript/javascript/js -> ts.
-  These flags are guide-specific and NEVER fail: an unknown value or an
-  unavailable (language, platform) combination falls back to the guide's default
-  variant rather than erroring. (This intentionally differs from 'init --platform',
-  which validates and exits.) Run 'guides list' to see available combinations.
+  --language <ts|swift|...> fetches a specific language variant of a guide.
+  Aliases: typescript/javascript/js -> ts.
+  --platform <web|ios|macos|...> selects the language a platform targets: the
+  guides manifest maps each platform to its language (e.g. ios -> swift), so
+  'guides get documents --platform ios' returns the Swift guide. An explicit
+  --language always wins the language dimension.
+  Unknown --language values (always), and unknown --platform values (once the
+  manifest publishes its platform map), are rejected with a clear error listing
+  the supported values — mirroring 'init --platform'. Run 'guides list' to see
+  the supported languages and platforms.
 
 Versioning:
   By default, guides are fetched for the detected ${CLIENT_PACKAGE_NAME} version.
@@ -405,16 +713,27 @@ Cache:
         .option("--json", "Output as JSON")
         .option("--refresh", "Force refresh from network")
         .option("--guide-version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
-        .option("--language <lang>", "Language the agent is targeting (ts, swift, ...; informational here)")
-        .option("--platform <platform>", "Platform the agent is targeting (web, ios, macos, ...; informational here)")
+        .option("--language <lang>", "Language to validate (ts, swift, ...; informational on list)")
+        .option("--platform <platform>", "Platform to validate (web, ios, macos, ...; informational on list)")
         .action(async (options) => {
         try {
             const requestedVersion = resolveVersion(options.guideVersion);
-            const { manifest, stale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
-            // Normalize requested dimensions (informational on `list` — surfaced so
-            // the agent can confirm what it asked for; selection happens on `get`).
+            const requestedBranch = resolveDocsBranchForInvocation();
+            const resolved = await resolveManifest(requestedBranch, requestedVersion, options.refresh);
+            const { manifest, stale, versionInfo, branch } = resolved;
+            // Validate the requested dimensions against the loaded manifest (same
+            // rules as `get`, for one mental model — Q3). They have no per-row
+            // effect on `list`, but an unknown value should fail loudly here too.
+            const resolution = validateAndResolveRequest(manifest, options.language, options.platform);
+            if (resolution.error) {
+                error(resolution.error);
+                process.exit(1);
+            }
             const reqLanguage = normalizeLanguage(options.language);
             const reqPlatform = normalizePlatform(options.platform);
+            const supportedLanguages = [...deriveLanguages(manifest)].sort();
+            // Report the served docs branch (stderr) when alpha/override is involved.
+            reportDocsBranch(resolved);
             if (stale) {
                 warn("Using stale cache (network unavailable)");
             }
@@ -422,7 +741,10 @@ Cache:
                 json({
                     version: versionInfo.version,
                     versionSource: versionInfo.source,
+                    guidesBranch: branch,
                     defaults: manifest.defaults ?? null,
+                    platforms: manifest.platforms ?? null,
+                    supportedLanguages,
                     language: reqLanguage ?? null,
                     platform: reqPlatform ?? null,
                     guides: manifest.guides.map((g) => ({
@@ -444,20 +766,41 @@ Cache:
             }
             keyValue("Client version", formatClientVersion(versionInfo));
             keyValue("Guides version", formatGuidesVersion(versionInfo));
+            // Manifest-level legend: spell out languages and the platform→language
+            // map explicitly, so `--language`/`--platform` are no longer ambiguous.
+            keyValue("Languages", supportedLanguages.join(", "));
+            keyValue("Platforms", formatPlatformsLegend(manifest));
             console.log("");
             const rows = manifest.guides.map((g) => ({
                 topic: g.topic,
                 description: g.description,
-                combinations: formatCombinations(g),
+                languages: formatLanguages(g),
             }));
+            // Size DESCRIPTION from the live terminal width so wide terminals show
+            // the full description (the guides.json contract budgets descriptions
+            // at <=100 chars; DESCRIPTION_MAX mirrors that cap — see
+            // primitive-docs `scripts/sync-guides-json.mjs`) while the table never
+            // wraps. Floor 48 keeps today's readable width on an 80-col terminal;
+            // on a non-TTY (piped) the column is sized to the cap so full
+            // descriptions reach `grep`/agents. `truncate` defensively clips a
+            // description that violates the upstream contract.
+            const DESCRIPTION_MAX = 100;
             console.log(formatTable(rows, [
                 { header: "TOPIC", key: "topic" },
-                { header: "DESCRIPTION", key: "description", width: 48, truncate: true },
-                { header: "COMBINATIONS", key: "combinations" },
+                {
+                    header: "DESCRIPTION",
+                    key: "description",
+                    flex: true,
+                    truncate: true,
+                    flexFloor: 48,
+                    flexMax: DESCRIPTION_MAX,
+                },
+                { header: "LANGUAGES", key: "languages" },
             ]));
             console.log("");
-            keyValue("Cache location", getVersionCacheDir(versionInfo.version));
-            info("Use 'primitive guides get <topic> [--language <lang>] [--platform <platform>]' to fetch a guide.");
+            keyValue("Cache location", getVersionCacheDir(branch, versionInfo.version));
+            info("Use 'primitive guides get <topic> --language <ts|swift>' to fetch a guide.");
+            info("Example: primitive guides get documents --language swift");
         }
         catch (err) {
             error(err.message);
@@ -473,31 +816,48 @@ Cache:
         .option("--refresh", "Force refresh from network")
         .option("--guide-version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
         .option("--language <lang>", "Language variant to fetch (ts, swift, ...; aliases typescript/javascript/js -> ts)")
-        .option("--platform <platform>", "Platform variant to fetch (web, ios, macos, ...)")
+        .option("--platform <platform>", "Platform whose language to fetch (web, ios, macos, ...; inferred from the manifest)")
         .action(async (topic, options) => {
         try {
             const requestedVersion = resolveVersion(options.guideVersion);
-            const { manifest, stale: manifestStale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
+            const requestedBranch = resolveDocsBranchForInvocation();
+            const resolved = await resolveManifest(requestedBranch, requestedVersion, options.refresh);
+            const { manifest, fromCache, stale: manifestStale, versionInfo, branch } = resolved;
             const guide = manifest.guides.find((g) => g.topic.toLowerCase() === topic.toLowerCase());
             if (!guide) {
                 const availableTopics = manifest.guides.map((g) => g.topic).join(", ");
                 error(`Guide "${topic}" not found. Available topics: ${availableTopics}`);
                 process.exit(1);
             }
-            // Normalize the requested (language, platform). Unknown values pass
-            // through and fall back to the default variant (never fail — #977).
-            const reqLanguage = normalizeLanguage(options.language);
-            const reqPlatform = normalizePlatform(options.platform);
+            // Validate both flags against the loaded manifest and resolve the
+            // effective language (issue #1219). An unknown value is a hard error;
+            // `--platform ios` infers its language (e.g. swift) when the manifest
+            // publishes a `platforms` block, while an explicit `--language` wins.
+            const resolution = validateAndResolveRequest(manifest, options.language, options.platform);
+            if (resolution.error) {
+                error(resolution.error);
+                process.exit(1);
+            }
+            // `reqLanguage` is the EFFECTIVE language after platform inference; pass
+            // it to both the JSON selection and the content fetch so they can't
+            // desynchronize.
+            const reqLanguage = resolution.language;
+            const reqPlatform = resolution.platform;
+            const requestedAnyDimension = normalizeLanguage(options.language) !== undefined ||
+                normalizePlatform(options.platform) !== undefined;
             const selection = selectVariant(guide, {
                 language: reqLanguage,
                 platform: reqPlatform,
             });
+            // Report the served docs branch (stderr) when alpha/override is involved.
+            reportDocsBranch(resolved);
             if (options.json) {
                 // Output just metadata — does NOT fetch content. `selectedFile` is the
                 // file that WOULD be served for this request (see selection above).
                 json({
                     version: versionInfo.version,
                     versionSource: versionInfo.source,
+                    guidesBranch: branch,
                     topic: guide.topic,
                     description: guide.description,
                     keywords: guide.keywords,
@@ -507,19 +867,77 @@ Cache:
                     relatedGuides: guide.relatedGuides,
                     language: reqLanguage ?? null,
                     platform: reqPlatform ?? null,
+                    defaultPlatform: manifest.defaults?.platform ?? null,
                     selectedFile: selection.file,
                     matchedOn: selection.matchedOn,
                     availableVariants: normalizeVariants(guide),
-                    cacheLocation: join(getGuidesCacheDir(versionInfo.version), basename(selection.file)),
+                    cacheLocation: join(getGuidesCacheDir(branch, versionInfo.version), basename(selection.file)),
                 });
                 return;
             }
-            const { content, stale: guideStale } = await fetchGuide(guide, versionInfo.version, { language: reqLanguage, platform: reqPlatform }, options.refresh);
-            if (manifestStale || guideStale) {
+            const request = { language: reqLanguage, platform: reqPlatform };
+            let result;
+            try {
+                result = await fetchGuide(guide, branch, versionInfo.version, request, options.refresh);
+            }
+            catch (err) {
+                // Only a 404 is healable here. Transport errors already served stale
+                // (or threw) inside fetchGuide; rethrow anything that isn't a 404.
+                if (!(err instanceof GuideFetchError && err.status === 404)) {
+                    throw err;
+                }
+                // Heal only when the manifest came from cache — then the named file
+                // may have been renamed/removed upstream while our manifest is stale.
+                // Force a manifest refetch, re-find the topic, and retry the file
+                // ONCE. A fresh-from-network manifest (incl. --refresh) makes the 404
+                // authoritative, so we skip straight to the last resort below (#1034).
+                if (fromCache) {
+                    try {
+                        // Heal on the SAME branch the manifest resolved on, so the
+                        // manifest and guide never disagree (#1463, behavior 4).
+                        const refreshed = await fetchManifest(branch, requestedVersion, /* forceRefresh */ true);
+                        const freshGuide = refreshed.manifest.guides.find((g) => g.topic.toLowerCase() === topic.toLowerCase());
+                        if (freshGuide) {
+                            // Re-calling fetchGuide recomputes selectVariant + the cache path
+                            // for the (possibly new) filename — no extra resolve site. If the
+                            // filename is unchanged it just 404s again and falls through.
+                            const retried = await fetchGuide(freshGuide, branch, refreshed.versionInfo.version, request, options.refresh);
+                            if (basename(retried.selectedFile) !== basename(err.selectedFile)) {
+                                warn(`Guide "${topic}" file moved upstream; refreshed manifest and retried.`);
+                            }
+                            result = retried;
+                        }
+                    }
+                    catch {
+                        // Heal failed (manifest refetch failed / retry 404'd / topic gone)
+                        // → fall through to the option-(b) last resort on the ORIGINAL error.
+                    }
+                }
+                // Option (b) last resort — applies to ALL 404s, not just cached-manifest
+                // ones, so `--refresh`-on-404 still serves an old on-disk copy as it
+                // does today. Serve the old copy if we have one; otherwise surface the
+                // original terminal 404.
+                if (!result) {
+                    if (err.staleContent !== undefined) {
+                        result = { content: err.staleContent, stale: true, selectedFile: err.selectedFile };
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+            if (manifestStale || result.stale) {
                 warn("Using stale cache (network unavailable)");
             }
+            // Transparency note (issue #1219): a language/platform was requested but
+            // this topic has no variant pinning it, so the default file was served.
+            // This closes the residual silent-fallback footgun beyond `--platform`.
+            // The note goes to STDERR (via `info`) so stdout stays clean for piping.
+            if (requestedAnyDimension && selection.matchedOn === "default") {
+                info(`No ${reqLanguage ?? reqPlatform} variant for "${guide.topic}"; served the default guide.`);
+            }
             // Print the guide content directly to stdout
-            console.log(content);
+            console.log(result.content);
         }
         catch (err) {
             error(err.message);