fix(FR-2754): per-version metadata propagation in docs site (#7103)

Resolves #7101 (FR-2754)

Stacked on top of #7099 (FR-2753).

## Why

Two per-version-metadata bugs surface on the multi-version docs deploy (FR-2729). Both predate FR-2753; they are observable now that the version selector reaches a real archive on the deployed site.

### Bug 1 — Spurious version-mismatch banner

From a page on the latest minor (e.g. `/26.4/ko/`), clicking "next" in the sidebar version selector lands on `/next/ko/index.html` with the banner *"이 페이지는 버전 next에 존재하지 않습니다. 해당 버전의 인덱스 페이지로 이동했습니다."*. The page exists in `next` — the message is wrong. Refreshing clears it. The reverse direction (`next → 26.4`) is fine.

**Cause:** `availability` is computed from `pageRegistry.hasSlug(version, slug)` and the registry is filled incrementally as pages render. With `versions: [26.4 (latest), next]`, `next`'s slugs are not yet in the registry when 26.4 pages render, so `availability["next"] = false` is baked into 26.4 pages. The inline switcher script reads that and arms a sessionStorage notice on click.

### Bug 2 — Brand pill always shows the workspace version

The pill in the topbar (`<span class="bai-brand-version">`) reads `v26.5.0-alpha.0 (sha)` on every page including pages under `/26.4/`. It should reflect the version the user is viewing.

**Cause:** `metadata.version` is set once from `getDocVersion()` at build start and reused for every per-version render.

## What

- **`VersionPageRegistry.declareSlug(version, slug)`** — records slug presence without adding a sitemap row. `record()` reuses it so callers cannot accidentally diverge the two paths.
- **Pre-pass in `generateWebsite`** (versioned mode only) iterates every declared version, loads its `book.config.yaml`, and `declareSlug()`'s every (lang × nav-item) slug plus the synthetic home slug. Runs BEFORE any page is rendered, so per-page `availability` is correct regardless of build order. No markdown files are loaded — only `book.config.yaml` navigation entries.
- **`pickDisplayVersion()` helper** in `versions.ts` chooses the brand pill text per render: workspace version in flat mode and on workspace-source entries (`next`); `pdfTag` (e.g. `v26.4.7`) for an archive-branch version when set; the version label itself as final fallback. `buildLanguage` calls it via metadata.
- **`packages/backend.ai-webui-docs/.docs-archive/` gitignored** — that directory is the local materialization point for `docs-archive/<minor>` worktrees and must not be tracked back into the workspace.

## Tests

7 new unit tests in `versions.test.ts`:

- `VersionPageRegistry.declareSlug` records slug presence without adding sitemap rows.
- `record()` after `declareSlug()` is idempotent on the slug set but still emits one row per `record()` call.
- `pickDisplayVersion`:
  - flat mode → workspace version
  - workspace-source `next` → workspace version
  - archive-branch with `pdfTag` → `pdfTag`
  - archive-branch without `pdfTag` → version label
  - missing `versionEntry` → workspace version (defensive)

## Verification

- `pnpm --filter backend.ai-docs-toolkit test` → **146 pass / 0 fail** (was 139 before this PR).
- `bash scripts/verify.sh` → ALL PASS.
- `pnpm run build:web --lang all` against the live config with `docs-archive/26.4` worktree materialized:
  - `/26.4/ko/index.html` `data-availability` is `{"26.4":true,"next":true}` (was `{"26.4":true,"next":false}`).
  - `/26.4/ko/index.html` brand pill renders `v26.4.7` (was `v26.5.0-alpha.0 (sha)`).
  - `/next/ko/index.html` brand pill renders `v26.5.0-alpha.0 (sha)` (workspace) — preserved.
  - Browser-driven Playwright check (5/5 pass): 26.4→next click leaves sessionStorage clean (no banner); next→26.4 likewise; brand pill text matches the version on each page; both pages share the corrected `data-availability` map.

## Files changed

- `packages/backend.ai-docs-toolkit/src/versions.ts` — `declareSlug` + `pickDisplayVersion`.
- `packages/backend.ai-docs-toolkit/src/website-generator.ts` — pre-pass loop + `pickDisplayVersion` call site.
- `packages/backend.ai-docs-toolkit/src/versions.test.ts` — 7 tests.
- `packages/backend.ai-webui-docs/.gitignore` — `.docs-archive/` entry.

## Checklist

- [x] Documentation — N/A (toolkit-internal change; user-facing doc pages unaffected)
- [x] Minimum required manager version — N/A (no backend change)
- [x] Test case(s) to demonstrate the difference of before/after — 7 unit tests + end-to-end build inspection + Playwright browser verification

Author: yomybaby

packages/backend.ai-docs-toolkit/src/styles-web.ts

@@ -2101,6 +2101,20 @@ details > :last-child {
    content column slightly and removes the chapter top padding so the
    hero can breathe.
    ========================================================================== */
+/*
+ * The home page does not emit a right-rail .doc-toc (it has no
+ * headings to scroll-spy), so the default .doc-page 3-column grid
+ * (sidebar + main + TOC) leaves an empty 240px column on the right
+ * and main sits flush against the sidebar — making the hero look
+ * left-shifted on wide viewports. The .doc-page--home modifier is
+ * already emitted on the home page outer div; collapse the grid to
+ * two columns there and center the (max-width 960px) main inside
+ * the post-sidebar region.
+ */
+.doc-page--home {
+  grid-template-columns: var(--bai-sider-w) minmax(0, 1fr);
+}
+
 .doc-main--home {
   padding-top: 56px;
   max-width: 960px;

packages/backend.ai-docs-toolkit/src/versions.test.ts

@@ -20,8 +20,10 @@ import {
   loadVersions,
   findLatest,
   canonicalPathFor,
+  pickDisplayVersion,
   resolveVersionSource,
   VersionPageRegistry,
+  type Version,
 } from "./versions.js";
 import type { ResolvedDocConfig, VersionEntry } from "./config.js";
 
@@ -523,4 +525,133 @@ describe("VersionPageRegistry", () => {
     assert.equal(reg.hasSlug("25.05", "overview"), false);
     assert.equal(reg.enumerateAll().length, 3);
   });
+
+  it("declareSlug records slug presence without adding sitemap rows (FR-2754)", () => {
+    // Bug 1 of FR-2754: when versions render in declared order, later
+    // versions are absent from the registry while earlier ones render,
+    // so the per-page `availability` map is wrong. Fix: pre-pass calls
+    // declareSlug() for every (version, slug) pair before rendering.
+    // declareSlug must NOT add sitemap rows — only record() does that.
+    const reg = new VersionPageRegistry();
+    reg.declareSlug("26.4", "index");
+    reg.declareSlug("26.4", "quickstart");
+    reg.declareSlug("next", "index");
+    assert.equal(reg.hasSlug("26.4", "index"), true);
+    assert.equal(reg.hasSlug("26.4", "quickstart"), true);
+    assert.equal(reg.hasSlug("next", "index"), true);
+    assert.equal(reg.hasSlug("next", "quickstart"), false);
+    // Critical: declareSlug must not pollute the sitemap row stream.
+    assert.equal(reg.enumerateAll().length, 0);
+  });
+
+  it("record() after declareSlug() of the same (version, slug) is idempotent", () => {
+    // The pre-pass declares every slug it can find from book.config;
+    // the render pass then calls record() with the full row. The set
+    // membership stays the same, but the sitemap row is added exactly
+    // once per call to record().
+    const reg = new VersionPageRegistry();
+    reg.declareSlug("26.4", "overview");
+    reg.record({
+      version: "26.4",
+      lang: "en",
+      slug: "overview",
+      path: "26.4/en/overview.html",
+      isLatest: true,
+    });
+    reg.record({
+      version: "26.4",
+      lang: "ko",
+      slug: "overview",
+      path: "26.4/ko/overview.html",
+      isLatest: true,
+    });
+    assert.equal(reg.hasSlug("26.4", "overview"), true);
+    // declareSlug added 0 rows; the two record() calls each added 1.
+    assert.equal(reg.enumerateAll().length, 2);
+  });
+});
+
+describe("pickDisplayVersion — FR-2754 brand version pill", () => {
+  const archive26: Version = {
+    label: "26.4",
+    source: { kind: "archive-branch", ref: "docs-archive/26.4" },
+    isLatest: true,
+    outDir: "26.4",
+    pdfTag: "v26.4.7",
+  };
+  const archive26NoTag: Version = {
+    label: "26.3",
+    source: { kind: "archive-branch", ref: "docs-archive/26.3" },
+    isLatest: false,
+    outDir: "26.3",
+  };
+  const workspaceNext: Version = {
+    label: "next",
+    source: { kind: "workspace" },
+    isLatest: false,
+    outDir: "next",
+  };
+  const ws = "v26.5.0-alpha.0 (be6c92b05)";
+
+  it("returns the workspace version in flat (non-versioned) mode", () => {
+    assert.equal(
+      pickDisplayVersion({
+        workspaceVersion: ws,
+        versionLabel: null,
+        versionEntry: null,
+      }),
+      ws,
+    );
+  });
+
+  it("returns the workspace version for the workspace-source `next` entry", () => {
+    // `next` IS the workspace tip, so the SHA is meaningful and the
+    // pdfTag concept does not apply.
+    assert.equal(
+      pickDisplayVersion({
+        workspaceVersion: ws,
+        versionLabel: "next",
+        versionEntry: workspaceNext,
+      }),
+      ws,
+    );
+  });
+
+  it("returns the pdfTag for archive-branch versions when set (e.g. v26.4.7)", () => {
+    // This is the user-facing fix: visiting `/26.4/...` should reveal
+    // exactly which Backend.AI release the docs were cut from, not the
+    // workspace version of whichever build emitted the page.
+    assert.equal(
+      pickDisplayVersion({
+        workspaceVersion: ws,
+        versionLabel: "26.4",
+        versionEntry: archive26,
+      }),
+      "v26.4.7",
+    );
+  });
+
+  it("falls back to the version label when an archive-branch entry has no pdfTag", () => {
+    assert.equal(
+      pickDisplayVersion({
+        workspaceVersion: ws,
+        versionLabel: "26.3",
+        versionEntry: archive26NoTag,
+      }),
+      "26.3",
+    );
+  });
+
+  it("returns the workspace version when versionEntry is missing (defensive)", () => {
+    // If the caller couldn't resolve the entry from the label, the
+    // safe fallback is the workspace version — same as flat mode.
+    assert.equal(
+      pickDisplayVersion({
+        workspaceVersion: ws,
+        versionLabel: "26.4",
+        versionEntry: null,
+      }),
+      ws,
+    );
+  });
 });

packages/backend.ai-docs-toolkit/src/versions.ts

@@ -367,6 +367,38 @@ export function canonicalPathFor(
   return `${loaded.latest.label}/${lang}/${slug}.html`;
 }
 
+/**
+ * Choose the version string to render in the topbar brand pill for a
+ * single page render (FR-2754 Fix 2).
+ *
+ *   - Flat / non-versioned mode (`versionLabel === null`): use the
+ *     workspace version (`package.json` version + git short SHA from
+ *     `getDocVersion()`). Same as pre-FR-2754 behavior.
+ *   - Workspace-source version (`next`): also use the workspace
+ *     version — `next` IS the workspace tip, so the SHA is meaningful.
+ *   - Archive-branch version (`26.4` and earlier minors): prefer its
+ *     pinned release tag (`pdfTag`, e.g. `v26.4.7`) so the pill tells
+ *     the reader exactly which Backend.AI release they are reading
+ *     docs for. Fall back to the version label itself when no tag was
+ *     configured.
+ *
+ * Kept here next to `Version` / `LoadedVersions` so the rule stays in
+ * one place; `website-generator.ts` just calls this from inside
+ * `buildLanguage`.
+ */
+export function pickDisplayVersion(args: {
+  workspaceVersion: string;
+  versionLabel: string | null;
+  versionEntry: Version | null | undefined;
+}): string {
+  const { workspaceVersion, versionLabel, versionEntry } = args;
+  if (!versionLabel || !versionEntry) return workspaceVersion;
+  if (versionEntry.source.kind === "archive-branch") {
+    return versionEntry.pdfTag ?? versionEntry.label;
+  }
+  return workspaceVersion;
+}
+
 /**
  * Cross-version slug map: for a given slug, which versions contain it.
  * The header version selector uses this to fall back to the version's
@@ -382,12 +414,25 @@ export class VersionPageRegistry {
 
   record(row: PageEnumerationRow): void {
     this.rows.push(row);
-    let bucket = this.slugsByVersion.get(row.version);
+    this.declareSlug(row.version, row.slug);
+  }
+
+  /**
+   * Mark `slug` as existing in `version` without adding a sitemap row
+   * (FR-2754). The website generator's pre-pass uses this to populate
+   * the slug-by-version map for every declared version BEFORE any page
+   * is rendered, so the per-page `availability` map is correct
+   * regardless of build/iteration order. Calling this for a slug that
+   * is later passed to `record()` is harmless — `Set.add` is
+   * idempotent.
+   */
+  declareSlug(version: string, slug: string): void {
+    let bucket = this.slugsByVersion.get(version);
     if (!bucket) {
       bucket = new Set<string>();
-      this.slugsByVersion.set(row.version, bucket);
+      this.slugsByVersion.set(version, bucket);
     }
-    bucket.add(row.slug);
+    bucket.add(slug);
   }
 
   /** True when `slug` exists in `version` (any language). */

packages/backend.ai-docs-toolkit/src/website-generator.ts

@@ -12,6 +12,7 @@ import { processMarkdownFilesForWeb } from "./markdown-processor-web.js";
 import type { LinkDiagnostic } from "./markdown-processor-web.js";
 import {
   RESERVED_HOME_SLUG,
+  resolveMarkdownPath,
   slugFromNavPath,
 } from "./markdown-processor.js";
 import {
@@ -57,6 +58,7 @@ import {
 } from "./image-optimizer.js";
 import {
   loadVersions,
+  pickDisplayVersion,
   resolveVersionSource,
   VersionPageRegistry,
   type LoadedVersions,
@@ -561,6 +563,78 @@ export async function generateWebsite(
   // language. Populated inside the versioned-mode loop below.
   let latestVersionLanguages: string[] | null = null;
 
+  // FR-2754 Fix 1: pre-populate the slug registry before any version is
+  // rendered, so per-page `availability` is correct regardless of build
+  // order. Without this pass the FIRST version in the loop sees an
+  // empty registry for every other version and bakes
+  // `availability[<other>] = false` into its pages — which spuriously
+  // fires the version-mismatch banner on click even when the slug
+  // exists in both versions. The walk only consults `book.config.yaml`
+  // navigation, so it does not need any markdown files to be loaded.
+  // Versions whose archive-branch source isn't materialized are still
+  // skipped (no entries declared); their availability remains `false`,
+  // which is the desired fallback.
+  if (loadedVersions.enabled) {
+    for (const v of loadedVersions.entries) {
+      const resolved = resolveVersionSource(config, v);
+      if (!resolved.ok || !resolved.rootDir) continue;
+      const versionConfig: ResolvedDocConfig =
+        v.source.kind === "workspace"
+          ? config
+          : {
+              ...config,
+              projectRoot: resolved.rootDir,
+              srcDir: path.join(resolved.rootDir, "src"),
+            };
+      let versionBookConfig: NormalizedBookConfig;
+      try {
+        versionBookConfig = loadBookConfig(versionConfig.srcDir);
+      } catch {
+        // If a past minor's archive can't be parsed for any reason,
+        // skip it here — the main render loop below will surface the
+        // diagnostic with full context.
+        continue;
+      }
+      // The synthetic home chapter writes to `<lang>/index.html` and
+      // is always present in every version's output, so register it
+      // even though it has no `navigation[]` entry of its own.
+      pageRegistry.declareSlug(v.label, RESERVED_HOME_SLUG);
+      // Mirror the renderer's path resolution: a `book.config.yaml`
+      // entry whose markdown file does not actually exist in the
+      // version's `src/<lang>/` tree is silently skipped by
+      // `processMarkdownFilesForWeb` (it warns and continues), so
+      // declaring its slug here would over-promise — the version
+      // selector would link to a slug that never produced HTML and
+      // 404. We therefore gate `declareSlug()` on `resolveMarkdownPath`
+      // succeeding for at least one language; once the slug is on disk
+      // for any lang the renderer will emit it for that lang and the
+      // version-switcher fallback to the index page is enough for the
+      // languages where it is missing. `pathFallbacks` is sourced from
+      // the version's resolved config, mirroring the renderer.
+      const pathFallbacks = versionConfig.pathFallbacks ?? {};
+      for (const lang of languages) {
+        if (!versionBookConfig.languages.includes(lang)) continue;
+        const navGroups: NavGroup[] =
+          versionBookConfig.navigationGroups[lang] ?? [];
+        for (const group of navGroups) {
+          for (const item of group.items) {
+            try {
+              resolveMarkdownPath(
+                lang,
+                item.path,
+                versionConfig.srcDir,
+                pathFallbacks,
+              );
+            } catch {
+              continue;
+            }
+            pageRegistry.declareSlug(v.label, slugFromNavPath(item.path));
+          }
+        }
+      }
+    }
+  }
+
   if (loadedVersions.enabled) {
     // Versioned mode — iterate over each declared version.
     // Past minors that fail to resolve their archive-branch worktree are
@@ -876,7 +950,21 @@ async function buildLanguage(args: {
   for (const d of langDiagnostics) allDiagnostics.push(d);
 
   const availableLanguages = bookConfig.languages;
-  const metadata: WebsiteMetadata = { title, version, lang, availableLanguages };
+  // FR-2754 Fix 2: choose what the brand version pill shows for THIS
+  // version. See `pickDisplayVersion` for the exact rule.
+  const displayVersion = pickDisplayVersion({
+    workspaceVersion: version,
+    versionLabel,
+    versionEntry: versionLabel
+      ? loadedVersions.entries.find((v) => v.label === versionLabel) ?? null
+      : null,
+  });
+  const metadata: WebsiteMetadata = {
+    title,
+    version: displayVersion,
+    lang,
+    availableLanguages,
+  };
 
   // F3: nav groups for the current language. Always present — even legacy
   // flat configs are wrapped in a single anonymous-category group by the

packages/backend.ai-webui-docs/.gitignore

@@ -1,3 +1,8 @@
 dist/
 node_modules/
 .agent-output/
+# Local checkouts of `docs-archive/<minor>` branches used by
+# docs-toolkit for versioned builds. Materialized via `git worktree
+# add .docs-archive/docs-archive__<minor> docs-archive/<minor>` and
+# never tracked back into the workspace.
+.docs-archive/