primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.40

package/dist/src/commands/guides.js

@@ -9,6 +9,187 @@ 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 CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const CLIENT_PACKAGE_NAME = "js-bao-wss-client";
+// Language aliases — map the agent's natural vocabulary onto canonical values.
+const LANGUAGE_ALIASES = {
+    typescript: "ts",
+    javascript: "ts",
+    js: "ts",
+};
+/**
+ * Normalize a `--language` flag value: lowercase, trim, and map known aliases
+ * (typescript/javascript/js → ts). Unknown values pass through unchanged.
+ *
+ * NOTE: guide flags are intentionally NOT validated against a fixed enum. An
+ * unknown/typo'd value simply matches no variant and falls back to the guide's
+ * default `file` (the "never fail" behavior from #977). This DIVERGES from
+ * `init --platform`, which validates and exits for unsupported values
+ * (cli/src/commands/init.ts) — that divergence is deliberate and guide-specific.
+ */
+export function normalizeLanguage(value) {
+    if (value === undefined)
+        return undefined;
+    const lower = value.trim().toLowerCase();
+    if (lower === "")
+        return undefined;
+    return LANGUAGE_ALIASES[lower] ?? lower;
+}
+/**
+ * Normalize a `--platform` flag value: lowercase + trim. No aliases for now.
+ * Like `normalizeLanguage`, unknown values pass through and fall back to the
+ * default `file` rather than erroring (guide-specific "never fail" behavior).
+ */
+export function normalizePlatform(value) {
+    if (value === undefined)
+        return undefined;
+    const lower = value.trim().toLowerCase();
+    if (lower === "")
+        return undefined;
+    return lower;
+}
+/**
+ * Select the guide variant filename for a requested (language, platform).
+ *
+ * Implemented as ordered `find()` passes — NOT a wildcard scoring system —
+ * with the no-flags case special-cased to the default `file`:
+ *
+ *   0. No flags at all          → guide.file (deterministic "default")
+ *   1. Exact pair               → variant pins BOTH requested dims
+ *   2. Language-only            → variant pins language; platform agnostic
+ *   3. Platform-only            → variant pins platform; language agnostic
+ *   4. Default                  → guide.file
+ *
+ * An omitted REQUEST dimension acts as a wildcard during matching (a
+ * `--language swift` request matches a swift variant regardless of platform).
+ * This function NEVER throws — an unknown/typo'd/unavailable combination simply
+ * falls through to the guide's default `file`.
+ */
+export function selectVariant(guide, request) {
+    const reqLang = request.language;
+    const reqPlat = request.platform;
+    const variants = guide.variants ?? [];
+    // 0. No flags supplied at all → deterministically serve the default file.
+    if (reqLang === undefined && reqPlat === undefined) {
+        return { file: guide.file, matchedOn: "default" };
+    }
+    // A variant "matches" a dimension if the request omits it (wildcard) OR the
+    // variant pins it to exactly the requested value. A variant that omits a
+    // dimension is agnostic and matches any requested value for that dimension.
+    const langMatches = (v) => reqLang === undefined || v.language === undefined || v.language === reqLang;
+    const platMatches = (v) => reqPlat === undefined || v.platform === undefined || v.platform === reqPlat;
+    // 1. Exact pair: variant pins both requested dimensions to the request.
+    if (reqLang !== undefined && reqPlat !== undefined) {
+        const exact = variants.find((v) => v.language === reqLang && v.platform === reqPlat);
+        if (exact)
+            return { file: exact.file, matchedOn: "exact" };
+    }
+    // 2. Language requested. Prefer a platform-agnostic variant that pins the
+    //    language (reported as "language" — pinned one dim, agnostic on the
+    //    other). If none exists, honor the omitted-platform wildcard and fall
+    //    back to a pair-specific variant that still satisfies the request
+    //    (e.g. only `{swift,ios}` published + `--language swift`). That fallback
+    //    pins BOTH dimensions to satisfy the request, so it's reported as
+    //    "exact" — the variant is as specific as an exact-pair hit.
+    if (reqLang !== undefined) {
+        const langAgnostic = variants.find((v) => v.language === reqLang && v.platform === undefined);
+        if (langAgnostic)
+            return { file: langAgnostic.file, matchedOn: "language" };
+        const langWildcard = variants.find((v) => v.language === reqLang && platMatches(v));
+        if (langWildcard)
+            return { file: langWildcard.file, matchedOn: "exact" };
+    }
+    // 3. Platform requested (symmetric to pass 2). Prefer a language-agnostic
+    //    variant that pins the platform ("platform"); otherwise honor the
+    //    omitted-language wildcard and fall back to a pair-specific variant
+    //    satisfying the request, reported as "exact".
+    if (reqPlat !== undefined) {
+        const platAgnostic = variants.find((v) => v.platform === reqPlat && v.language === undefined);
+        if (platAgnostic)
+            return { file: platAgnostic.file, matchedOn: "platform" };
+        const platWildcard = variants.find((v) => v.platform === reqPlat && langMatches(v));
+        if (platWildcard)
+            return { file: platWildcard.file, matchedOn: "exact" };
+    }
+    // 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 {
@@ -184,28 +365,71 @@ async function fetchManifest(versionInfo, forceRefresh = false) {
     }
     throw new Error(`Failed to fetch guides manifest for ${versionInfo.version}`);
 }
-async function fetchGuide(guide, version, forceRefresh = false) {
+/**
+ * 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, version, request = {}, forceRefresh = false) {
     ensureCacheDir(version);
     const meta = loadCacheMeta();
-    const guideFileName = basename(guide.file);
+    // 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);
-    const fetchedAt = meta.guidesFetchedAt?.[version]?.[guide.topic];
+    // 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 cacheExpired = isCacheExpired(fetchedAt);
     const hasCachedGuide = existsSync(cachedPath);
     // If cache is valid and not forcing refresh, use it
     if (!forceRefresh && !cacheExpired && hasCachedGuide) {
         try {
             const content = readFileSync(cachedPath, "utf-8");
-            return { content, fromCache: true, stale: false };
+            return { content, fromCache: true, stale: false, selectedFile };
         }
         catch {
             // Cache corrupted, will fetch fresh
         }
     }
     // Try to fetch from network
-    const guideUrl = getGuideUrl(version, guide.file);
+    const guideUrl = getGuideUrl(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}`);
         }
@@ -214,39 +438,99 @@ async function fetchGuide(guide, version, forceRefresh = false) {
         writeFileSync(cachedPath, content);
         meta.guidesFetchedAt = meta.guidesFetchedAt || {};
         meta.guidesFetchedAt[version] = meta.guidesFetchedAt[version] || {};
-        meta.guidesFetchedAt[version][guide.topic] = new Date().toISOString();
+        meta.guidesFetchedAt[version][guideFileName] = new Date().toISOString();
         saveCacheMeta(meta);
-        return { content, fromCache: false, stale: false };
+        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 };
-            }
-            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}`);
     }
 }
+/** Normalize a guide's variants for display / --json output. */
+function normalizeVariants(guide) {
+    return (guide.variants ?? []).map((v) => ({
+        ...(v.language !== undefined ? { language: v.language } : {}),
+        ...(v.platform !== undefined ? { platform: v.platform } : {}),
+        file: v.file,
+    }));
+}
+/**
+ * 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 languages = variants
+        .map((v) => v.language)
+        .filter((l) => l !== undefined);
+    if (languages.length === 0)
+        return "default";
+    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
         .command("guides")
         .description("Access Primitive how-to guides for building apps")
         .addHelpText("after", `
 Examples:
-  $ primitive guides list              # List available guides
-  $ primitive guides list --json       # List as JSON for programmatic use
-  $ primitive guides get documents     # Fetch and display the documents guide
-  $ primitive guides get workflows     # Fetch and display the workflows guide
-  $ primitive guides list --version 1  # List guides for client v1
+  $ 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 --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|...> 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.
-  Use --version to explicitly request a specific major version.
+  Use --guide-version to explicitly request a specific major version (e.g. 1, 2,
+  or 'latest'). (The flag is --guide-version, not --version, because the root
+  'primitive --version' prints the CLI version and would otherwise swallow it.)
   Falls back to 'latest' if the version is not found.
 
 Cache:
@@ -259,11 +543,24 @@ Cache:
         .description("List available guides")
         .option("--json", "Output as JSON")
         .option("--refresh", "Force refresh from network")
-        .option("--version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .option("--guide-version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .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.version);
+            const requestedVersion = resolveVersion(options.guideVersion);
             const { manifest, stale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
+            // 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();
             if (stale) {
                 warn("Using stale cache (network unavailable)");
             }
@@ -271,6 +568,11 @@ Cache:
                 json({
                     version: versionInfo.version,
                     versionSource: versionInfo.source,
+                    defaults: manifest.defaults ?? null,
+                    platforms: manifest.platforms ?? null,
+                    supportedLanguages,
+                    language: reqLanguage ?? null,
+                    platform: reqPlatform ?? null,
                     guides: manifest.guides.map((g) => ({
                         topic: g.topic,
                         description: g.description,
@@ -279,6 +581,7 @@ Cache:
                         concepts: g.concepts,
                         prerequisites: g.prerequisites,
                         relatedGuides: g.relatedGuides,
+                        availableVariants: normalizeVariants(g),
                     })),
                 });
                 return;
@@ -289,14 +592,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("");
-            console.log(formatTable(manifest.guides, [
+            const rows = manifest.guides.map((g) => ({
+                topic: g.topic,
+                description: g.description,
+                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: 60 },
+                {
+                    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>' to fetch a guide.");
+            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);
@@ -310,19 +640,42 @@ Cache:
         .argument("<topic>", "Guide topic (e.g., documents, workflows, prompts)")
         .option("--json", "Output metadata as JSON instead of content")
         .option("--refresh", "Force refresh from network")
-        .option("--version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .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 whose language to fetch (web, ios, macos, ...; inferred from the manifest)")
         .action(async (topic, options) => {
         try {
-            const requestedVersion = resolveVersion(options.version);
-            const { manifest, stale: manifestStale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
+            const requestedVersion = resolveVersion(options.guideVersion);
+            const { manifest, fromCache, stale: manifestStale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
             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);
             }
+            // 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,
+            });
             if (options.json) {
-                // Output just metadata
+                // 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,
@@ -333,16 +686,77 @@ Cache:
                     concepts: guide.concepts,
                     prerequisites: guide.prerequisites,
                     relatedGuides: guide.relatedGuides,
-                    cacheLocation: join(getGuidesCacheDir(versionInfo.version), basename(guide.file)),
+                    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)),
                 });
                 return;
             }
-            const { content, stale: guideStale } = await fetchGuide(guide, versionInfo.version, options.refresh);
-            if (manifestStale || guideStale) {
+            const request = { language: reqLanguage, platform: reqPlatform };
+            let result;
+            try {
+                result = await fetchGuide(guide, 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 {
+                        const refreshed = await fetchManifest(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, 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);