@brandon_m_behring/book-scaffold-astro 4.12.0 → 4.14.0

package/components/ChapterHeader.astro

@@ -21,6 +21,7 @@
  */
 import type { CollectionEntry } from 'astro:content';
 import { getFreshness, freshnessLabel } from '../src/lib/freshness';
+import { academicPartHeading } from '../src/lib/academic-parts';
 import StatusBadge from './StatusBadge.astro';
 import CodeRef from './CodeRef.astro';
 
@@ -60,23 +61,15 @@ const freshnessText = freshness
       : 'Stale'
   : null;
 
-// Academic-profile part labels (Roman-numeral · descriptive name).
-// v2.0 post_transformers used this exact mapping; verbatim restore here so
-// the header content density matches at narrow viewports. Keys mirror
-// `academicParts` enum from src/schemas.ts.
-const ACADEMIC_PART_LABELS: Record<string, string> = {
-  foundations: 'Part I · Foundations',
-  'ssm-core': 'Part II · SSM Core',
-  'beyond-ssm': 'Part III · Beyond SSMs',
-  integration: 'Part IV · Integration',
-  synthesis: 'Part V · Synthesis',
-};
-
-// Display strings, profile-tagged for clarity in markup.
+// Display strings, profile-tagged for clarity in markup. Academic part
+// labels ("Part {roman} · {name}") come from the shared academic-parts
+// module — the single source of truth across the /chapters index, Sidebar,
+// and this header (#95). Unknown/custom academic parts fall back to the
+// title-cased name (no ordinal), consistent with the other two surfaces.
 const partLabel = (() => {
   const p = d.part;
-  if (hasAcademicMeta && typeof p === 'string' && p in ACADEMIC_PART_LABELS) {
-    return ACADEMIC_PART_LABELS[p];
+  if (hasAcademicMeta && typeof p === 'string' && p.length > 0) {
+    return academicPartHeading(p);
   }
   if (typeof p === 'number') return `Part ${p}`;
   if (typeof p === 'string' && p.length > 0) return `Part: ${p}`;

package/components/Sidebar.astro

@@ -18,26 +18,17 @@
  * them in as Astro.props from Base.astro if you want per-page overrides.
  */
 import { getCollection } from 'astro:content';
+import { academicParts } from '../src/schemas';
+import { academicPartHeading } from '../src/lib/academic-parts';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
 const siteTitle = 'Book';
 const siteSubtitle = 'A scaffold-astro book';
 
-// Academic profile: part is a string enum.
-const ACADEMIC_PART_ORDER = [
-  'foundations',
-  'ssm-core',
-  'beyond-ssm',
-  'integration',
-  'synthesis',
-] as const;
-const ACADEMIC_PART_LABEL: Record<string, string> = {
-  foundations: 'Part I · Foundations',
-  'ssm-core': 'Part II · SSM Core',
-  'beyond-ssm': 'Part III · Beyond SSMs',
-  integration: 'Part IV · Integration',
-  synthesis: 'Part V · Synthesis',
-};
+// Academic profile: part is a string enum. `academicParts` (schemas.ts) is
+// the canonical order, shared with the renderer and ChapterHeader (#95); the
+// "Part {roman} · {name}" labels come from the same academic-parts module.
+const ACADEMIC_PART_ORDER = academicParts;
 
 const rawChapters = await getCollection('chapters', (entry) => !entry.data.draft);
 
@@ -101,7 +92,7 @@ function isCurrent(id: string): boolean {
 }
 
 function partLabel(key: string): string {
-  if (profile === 'academic') return ACADEMIC_PART_LABEL[key] ?? key;
+  if (profile === 'academic') return academicPartHeading(key);
   return `Part ${key}`;
 }
 ---

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, o as Style } from './types-CULHImU4.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, r as academicParts, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CULHImU4.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
 import 'astro/zod';
 
 /**
@@ -95,14 +95,6 @@ declare function getFreshness(lastVerified: Date | undefined, volatility: Volati
  * affordance without a separate branch. */
 declare function freshnessLabel(f: Freshness | null): string;
 
-/**
- * src/lib/chapter-sort.ts — pure sort-key helper for chapter frontmatter.
- *
- * Lives in its own file (no `astro:content` imports) so tsup can include it
- * in the toolkit's DTS bundle without trying to resolve Astro's virtual
- * modules at build time. The Astro-context wrappers (sortKey, getAllChapters,
- * getNeighbors) live in src/lib/chapters.ts and import from here.
- */
 /**
  * Pure-function sort key from a chapter frontmatter object. Spans both
  * tools and academic schemas:
@@ -159,6 +151,59 @@ declare const academicChaptersRenderer: ChaptersRenderer;
 
 declare const fallbackChaptersRenderer: ChaptersRenderer;
 
+/**
+ * src/lib/academic-parts.ts — single source of truth for academic-profile
+ * part labels (#95).
+ *
+ * The academic `part` enum (src/schemas.ts: academicParts) is rendered on
+ * three surfaces — the `/chapters` index, the Sidebar nav, and the chapter
+ * header. Before v4.14.0 each surface carried its own copy of the
+ * enum→label map, and they had silently diverged: `beyond-ssm` rendered
+ * "Beyond SSM" on the index but "Beyond SSMs" in the sidebar/header. This
+ * module is the one place that owns:
+ *
+ *   - the base display name per part ("SSM Core", "Beyond SSMs", …), and
+ *   - the unknown/custom-part fallback (titleCase, consistently).
+ *
+ * The renderer uses the bare name; the Sidebar/ChapterHeader compose
+ * "Part {roman} · {name}". Both the Roman heading prefix AND the on-page
+ * sort order derive from the part's position in `academicParts` (the
+ * canonical order) via `academicPartOrdinal()` below — so labels and
+ * ordering share one source and cannot drift apart (#95 + #99).
+ */
+
+type AcademicPart = (typeof academicParts)[number];
+/**
+ * Base display names for the academic `part` enum. An explicit map (not
+ * naive title-casing) so acronyms render correctly: `ssm-core` → "SSM Core",
+ * not "Ssm Core" (#91). Keys mirror `academicParts` in src/schemas.ts.
+ * Canonical spelling for `beyond-ssm` is the plural "Beyond SSMs" (#95).
+ */
+declare const ACADEMIC_PART_NAMES: Record<AcademicPart, string>;
+/**
+ * Bare part name for the `/chapters` index group heading. Known parts use
+ * the explicit map; unknown/custom parts fall back to titleCase.
+ */
+declare function academicPartName(part: string): string;
+/** Ordinal returned for any `part` outside `academicParts` — it sorts after
+ *  all known parts and renders with no Roman prefix. */
+declare const UNKNOWN_PART_ORDINAL = 99;
+/**
+ * 1-based ordinal of an academic `part`, from its position in `academicParts`
+ * (the canonical order); `UNKNOWN_PART_ORDINAL` for anything outside the enum.
+ * The single source for BOTH the on-page sort key (academicChaptersRenderer
+ * and chapterSortKey) and the Roman heading prefix below — so a reorder of
+ * `academicParts` moves sort order and labels together, never apart (#99).
+ */
+declare function academicPartOrdinal(part: string): number;
+/**
+ * "Part {roman} · {name}" heading for the Sidebar and ChapterHeader. Known
+ * parts get the Roman-ordinal prefix; unknown/custom parts (no ordinal)
+ * fall back to the bare title-cased name — one consistent rule across both
+ * surfaces, replacing the old divergent fallbacks (raw key vs "Part: key").
+ */
+declare function academicPartHeading(part: string): string;
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -260,4 +305,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -359,25 +359,40 @@ var patternsSchema = z.object({
   convergence_date: z.date().nullable().optional()
 });
 
-// src/profiles/renderers/academic-chapters.ts
-var ACADEMIC_PART_ORDINAL = {
-  foundations: 1,
-  "ssm-core": 2,
-  "beyond-ssm": 3,
-  integration: 4,
-  synthesis: 5
+// src/lib/academic-parts.ts
+var ACADEMIC_PART_NAMES = {
+  foundations: "Foundations",
+  "ssm-core": "SSM Core",
+  "beyond-ssm": "Beyond SSMs",
+  integration: "Integration",
+  synthesis: "Synthesis"
 };
-var UNKNOWN_PART_ORDINAL = 99;
+var ROMAN = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII"];
 function titleCase(part) {
   return part.split("-").map((w) => w.length > 0 ? w.charAt(0).toUpperCase() + w.slice(1) : "").join(" ");
 }
+function academicPartName(part) {
+  return ACADEMIC_PART_NAMES[part] ?? titleCase(part);
+}
+var UNKNOWN_PART_ORDINAL = 99;
+function academicPartOrdinal(part) {
+  const i = academicParts.indexOf(part);
+  return i >= 0 ? i + 1 : UNKNOWN_PART_ORDINAL;
+}
+function academicPartHeading(part) {
+  const ord = academicPartOrdinal(part);
+  const name = academicPartName(part);
+  return ord === UNKNOWN_PART_ORDINAL ? name : `Part ${ROMAN[ord - 1]} \xB7 ${name}`;
+}
+
+// src/profiles/renderers/academic-chapters.ts
 var academicChaptersRenderer = {
   partKey(data) {
     return data.part ?? "";
   },
   formatPartLabel(part) {
     if (typeof part === "string" && part.length > 0) {
-      return titleCase(part);
+      return academicPartName(part);
     }
     return String(part);
   },
@@ -410,7 +425,7 @@ var academicChaptersRenderer = {
   },
   sortKey(data) {
     const partRaw = data.part;
-    const partOrdinal = typeof partRaw === "string" ? ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL : typeof partRaw === "number" ? partRaw : UNKNOWN_PART_ORDINAL;
+    const partOrdinal = typeof partRaw === "string" ? academicPartOrdinal(partRaw) : typeof partRaw === "number" ? partRaw : UNKNOWN_PART_ORDINAL;
     const week = typeof data.week === "number" ? data.week : 0;
     return partOrdinal * 1e3 + week;
   }
@@ -1219,17 +1234,9 @@ async function defineBookConfig(opts) {
 }
 
 // src/lib/chapter-sort.ts
-var ACADEMIC_PART_ORDINAL2 = {
-  foundations: 1,
-  "ssm-core": 2,
-  "beyond-ssm": 3,
-  integration: 4,
-  synthesis: 5
-};
-var UNKNOWN_PART_ORDINAL2 = 99;
 function chapterSortKey(data) {
   const partRaw = data.part;
-  const partOrdinal = typeof partRaw === "number" ? partRaw : typeof partRaw === "string" ? ACADEMIC_PART_ORDINAL2[partRaw] ?? UNKNOWN_PART_ORDINAL2 : UNKNOWN_PART_ORDINAL2;
+  const partOrdinal = typeof partRaw === "number" ? partRaw : typeof partRaw === "string" ? academicPartOrdinal(partRaw) : UNKNOWN_PART_ORDINAL;
   const within = typeof data.chapter === "number" ? data.chapter : typeof data.week === "number" ? data.week : 0;
   return partOrdinal * 1e3 + within;
 }
@@ -1274,13 +1281,18 @@ function defineTips(opts) {
   return { __tipsConfigVersion: 1, ...opts };
 }
 export {
+  ACADEMIC_PART_NAMES,
   BOOK_PRESETS,
   BOOK_PROFILES,
   BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
+  UNKNOWN_PART_ORDINAL,
   academicChapterSchema,
   academicChaptersRenderer,
+  academicPartHeading,
+  academicPartName,
+  academicPartOrdinal,
   academicParts,
   academicStyle,
   bookScaffoldIntegration,

package/dist/schemas.mjs

@@ -243,25 +243,34 @@ var patternsSchema = z.object({
   convergence_date: z.date().nullable().optional()
 });
 
-// src/profiles/renderers/academic-chapters.ts
-var ACADEMIC_PART_ORDINAL = {
-  foundations: 1,
-  "ssm-core": 2,
-  "beyond-ssm": 3,
-  integration: 4,
-  synthesis: 5
+// src/lib/academic-parts.ts
+var ACADEMIC_PART_NAMES = {
+  foundations: "Foundations",
+  "ssm-core": "SSM Core",
+  "beyond-ssm": "Beyond SSMs",
+  integration: "Integration",
+  synthesis: "Synthesis"
 };
-var UNKNOWN_PART_ORDINAL = 99;
 function titleCase(part) {
   return part.split("-").map((w) => w.length > 0 ? w.charAt(0).toUpperCase() + w.slice(1) : "").join(" ");
 }
+function academicPartName(part) {
+  return ACADEMIC_PART_NAMES[part] ?? titleCase(part);
+}
+var UNKNOWN_PART_ORDINAL = 99;
+function academicPartOrdinal(part) {
+  const i = academicParts.indexOf(part);
+  return i >= 0 ? i + 1 : UNKNOWN_PART_ORDINAL;
+}
+
+// src/profiles/renderers/academic-chapters.ts
 var academicChaptersRenderer = {
   partKey(data) {
     return data.part ?? "";
   },
   formatPartLabel(part) {
     if (typeof part === "string" && part.length > 0) {
-      return titleCase(part);
+      return academicPartName(part);
     }
     return String(part);
   },
@@ -294,7 +303,7 @@ var academicChaptersRenderer = {
   },
   sortKey(data) {
     const partRaw = data.part;
-    const partOrdinal = typeof partRaw === "string" ? ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL : typeof partRaw === "number" ? partRaw : UNKNOWN_PART_ORDINAL;
+    const partOrdinal = typeof partRaw === "string" ? academicPartOrdinal(partRaw) : typeof partRaw === "number" ? partRaw : UNKNOWN_PART_ORDINAL;
     const week = typeof data.week === "number" ? data.week : 0;
     return partOrdinal * 1e3 + week;
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/pages/convergence.astro

@@ -14,15 +14,39 @@ import Base from '../layouts/Base.astro';
 import PatternTimeline from '../components/PatternTimeline.astro';
 import {
   getPatternsByCategory,
+  emptyPatternsByCategory,
   CATEGORY_LABELS,
 } from '../src/lib/patterns';
 import { patternCategories } from '@brandon_m_behring/book-scaffold-astro';
 
-const grouped = await getPatternsByCategory();
+// A tools-profile book may use the inline <Convergence> component yet define
+// no `changelog/patterns.yaml` — then the `patterns` collection is never
+// registered and getCollection('patterns') errors with "The collection
+// 'patterns' does not exist or is empty" (#86). Gate on the manifest's
+// presence and never touch the collection when it is absent — the same
+// presence-gate references.astro uses for the optional `sources` collection.
+// When absent, render the dashboard's honest empty-state from a pure
+// all-empty map (no content-collection access).
+const patternsManifest = import.meta.glob('/changelog/patterns.yaml', {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+const hasPatterns = '/changelog/patterns.yaml' in patternsManifest;
+const grouped = hasPatterns
+  ? await getPatternsByCategory()
+  : emptyPatternsByCategory();
 const totalPatterns = Object.values(grouped).reduce(
   (n, arr) => n + arr.length,
   0,
 );
+// Distinguish a missing/misnamed manifest from a legitimately empty registry:
+// a tools book that uses <Convergence> but never created changelog/patterns.yaml
+// would otherwise see a blank dashboard indistinguishable from "no patterns yet".
+// Surface an actionable hint instead — matching tips.astro / references.astro.
+const noManifestHint = hasPatterns
+  ? null
+  : 'No changelog/patterns.yaml found — create it to populate this dashboard, or set routes: { convergence: false } to drop this page.';
 ---
 <Base
   title="Convergence — Agentic Coding"
@@ -43,6 +67,9 @@ const totalPatterns = Object.values(grouped).reduce(
         converge or as historical patterns get backfilled; expect the
         count to drift upward, not the existing entries.
       </p>
+      {noManifestHint && (
+        <p class="convergence-no-manifest" role="note">{noManifestHint}</p>
+      )}
     </header>
 
     {patternCategories.map((cat) => {

package/src/lib/academic-parts.ts

@@ -0,0 +1,87 @@
+/**
+ * src/lib/academic-parts.ts — single source of truth for academic-profile
+ * part labels (#95).
+ *
+ * The academic `part` enum (src/schemas.ts: academicParts) is rendered on
+ * three surfaces — the `/chapters` index, the Sidebar nav, and the chapter
+ * header. Before v4.14.0 each surface carried its own copy of the
+ * enum→label map, and they had silently diverged: `beyond-ssm` rendered
+ * "Beyond SSM" on the index but "Beyond SSMs" in the sidebar/header. This
+ * module is the one place that owns:
+ *
+ *   - the base display name per part ("SSM Core", "Beyond SSMs", …), and
+ *   - the unknown/custom-part fallback (titleCase, consistently).
+ *
+ * The renderer uses the bare name; the Sidebar/ChapterHeader compose
+ * "Part {roman} · {name}". Both the Roman heading prefix AND the on-page
+ * sort order derive from the part's position in `academicParts` (the
+ * canonical order) via `academicPartOrdinal()` below — so labels and
+ * ordering share one source and cannot drift apart (#95 + #99).
+ */
+import { academicParts } from '../schemas.js';
+
+type AcademicPart = (typeof academicParts)[number];
+
+/**
+ * Base display names for the academic `part` enum. An explicit map (not
+ * naive title-casing) so acronyms render correctly: `ssm-core` → "SSM Core",
+ * not "Ssm Core" (#91). Keys mirror `academicParts` in src/schemas.ts.
+ * Canonical spelling for `beyond-ssm` is the plural "Beyond SSMs" (#95).
+ */
+export const ACADEMIC_PART_NAMES: Record<AcademicPart, string> = {
+  foundations: 'Foundations',
+  'ssm-core': 'SSM Core',
+  'beyond-ssm': 'Beyond SSMs',
+  integration: 'Integration',
+  synthesis: 'Synthesis',
+};
+
+/** Roman ordinals for the "Part {roman}" heading prefix, indexed by the
+ *  part's position in `academicParts`. Sized past the 5 known parts so a
+ *  future enum addition still resolves a numeral. */
+const ROMAN = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII'];
+
+/** Title-case an enum string: "consumer-custom" → "Consumer Custom".
+ *  Fallback for parts outside the known ACADEMIC_PART_NAMES map. */
+function titleCase(part: string): string {
+  return part
+    .split('-')
+    .map((w) => (w.length > 0 ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
+    .join(' ');
+}
+
+/**
+ * Bare part name for the `/chapters` index group heading. Known parts use
+ * the explicit map; unknown/custom parts fall back to titleCase.
+ */
+export function academicPartName(part: string): string {
+  return ACADEMIC_PART_NAMES[part as AcademicPart] ?? titleCase(part);
+}
+
+/** Ordinal returned for any `part` outside `academicParts` — it sorts after
+ *  all known parts and renders with no Roman prefix. */
+export const UNKNOWN_PART_ORDINAL = 99;
+
+/**
+ * 1-based ordinal of an academic `part`, from its position in `academicParts`
+ * (the canonical order); `UNKNOWN_PART_ORDINAL` for anything outside the enum.
+ * The single source for BOTH the on-page sort key (academicChaptersRenderer
+ * and chapterSortKey) and the Roman heading prefix below — so a reorder of
+ * `academicParts` moves sort order and labels together, never apart (#99).
+ */
+export function academicPartOrdinal(part: string): number {
+  const i = academicParts.indexOf(part as AcademicPart);
+  return i >= 0 ? i + 1 : UNKNOWN_PART_ORDINAL;
+}
+
+/**
+ * "Part {roman} · {name}" heading for the Sidebar and ChapterHeader. Known
+ * parts get the Roman-ordinal prefix; unknown/custom parts (no ordinal)
+ * fall back to the bare title-cased name — one consistent rule across both
+ * surfaces, replacing the old divergent fallbacks (raw key vs "Part: key").
+ */
+export function academicPartHeading(part: string): string {
+  const ord = academicPartOrdinal(part);
+  const name = academicPartName(part);
+  return ord === UNKNOWN_PART_ORDINAL ? name : `Part ${ROMAN[ord - 1]} · ${name}`;
+}

package/src/lib/chapter-sort.ts

@@ -5,23 +5,13 @@
  * in the toolkit's DTS bundle without trying to resolve Astro's virtual
  * modules at build time. The Astro-context wrappers (sortKey, getAllChapters,
  * getNeighbors) live in src/lib/chapters.ts and import from here.
+ *
+ * The academic `part`→ordinal mapping is shared with the label surfaces via
+ * `academicPartOrdinal` (src/lib/academic-parts.ts, also astro:content-free),
+ * so on-page sort order and the Roman heading prefix derive from one canonical
+ * order (`academicParts`) and cannot drift apart (#99).
  */
-
-/**
- * Ordinal positions for the academic-profile `part` enum (src/schemas.ts:
- * academicParts). Order here is load-bearing: it determines the on-page
- * grouping order of academic books. Anything outside the enum (e.g., a
- * consumer-extended part name) sorts to the end.
- */
-const ACADEMIC_PART_ORDINAL: Record<string, number> = {
-  foundations: 1,
-  'ssm-core': 2,
-  'beyond-ssm': 3,
-  integration: 4,
-  synthesis: 5,
-};
-
-const UNKNOWN_PART_ORDINAL = 99;
+import { academicPartOrdinal, UNKNOWN_PART_ORDINAL } from './academic-parts.js';
 
 /**
  * Pure-function sort key from a chapter frontmatter object. Spans both
@@ -43,7 +33,7 @@ export function chapterSortKey(data: Record<string, unknown>): number {
     typeof partRaw === 'number'
       ? partRaw
       : typeof partRaw === 'string'
-        ? (ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL)
+        ? academicPartOrdinal(partRaw)
         : UNKNOWN_PART_ORDINAL;
   const within =
     typeof data.chapter === 'number'

package/src/lib/patterns.ts

@@ -79,6 +79,20 @@ export async function getAllPatterns(): Promise<PatternEntry[]> {
   });
 }
 
+/**
+ * An all-empty category map (every category → []), in the exact shape
+ * getPatternsByCategory returns. Pure — no content-collection access — so it
+ * is safe to call when a book defines no `patterns` collection at all: the
+ * convergence dashboard renders its honest "no patterns yet" placeholders
+ * from it without ever calling getCollection('patterns') (#86, cf. how
+ * references.astro gates the absent `sources` collection).
+ */
+export function emptyPatternsByCategory(): Record<PatternCategory, PatternEntry[]> {
+  return Object.fromEntries(
+    patternCategories.map((c) => [c, [] as PatternEntry[]]),
+  ) as Record<PatternCategory, PatternEntry[]>;
+}
+
 /**
  * Patterns grouped by category; categories that have no patterns are
  * still emitted with an empty array so the dashboard can render
@@ -88,9 +102,7 @@ export async function getPatternsByCategory(): Promise<
   Record<PatternCategory, PatternEntry[]>
 > {
   const all = await getAllPatterns();
-  const grouped = Object.fromEntries(
-    patternCategories.map((c) => [c, [] as PatternEntry[]]),
-  ) as Record<PatternCategory, PatternEntry[]>;
+  const grouped = emptyPatternsByCategory();
   for (const p of all) {
     const cat = p.data.category ?? 'other';
     grouped[cat].push(p);

package/src/profiles/renderers/academic-chapters.ts

@@ -12,29 +12,11 @@ import type {
   PartKey,
   StatusBadge,
 } from '../../lib/chapters-renderer.js';
-
-/**
- * Ordinal positions for the academic-profile `part` enum (src/schemas.ts:
- * academicParts). Order is load-bearing — drives both grouping order and
- * sort key. Must match academicParts in schemas.ts.
- */
-const ACADEMIC_PART_ORDINAL: Record<string, number> = {
-  foundations: 1,
-  'ssm-core': 2,
-  'beyond-ssm': 3,
-  integration: 4,
-  synthesis: 5,
-};
-
-const UNKNOWN_PART_ORDINAL = 99;
-
-/** Title-case an enum string: "ssm-core" → "Ssm Core". */
-function titleCase(part: string): string {
-  return part
-    .split('-')
-    .map((w) => (w.length > 0 ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
-    .join(' ');
-}
+import {
+  academicPartName,
+  academicPartOrdinal,
+  UNKNOWN_PART_ORDINAL,
+} from '../../lib/academic-parts.js';
 
 export const academicChaptersRenderer: ChaptersRenderer = {
   partKey(data) {
@@ -43,7 +25,7 @@ export const academicChaptersRenderer: ChaptersRenderer = {
 
   formatPartLabel(part) {
     if (typeof part === 'string' && part.length > 0) {
-      return titleCase(part);
+      return academicPartName(part);
     }
     return String(part);
   },
@@ -92,7 +74,7 @@ export const academicChaptersRenderer: ChaptersRenderer = {
     const partRaw = data.part;
     const partOrdinal =
       typeof partRaw === 'string'
-        ? (ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL)
+        ? academicPartOrdinal(partRaw)
         : typeof partRaw === 'number'
           ? partRaw
           : UNKNOWN_PART_ORDINAL;

package/styles/tokens.css

@@ -34,7 +34,9 @@
   --color-bg:         var(--paper);
   --color-bg-subtle:  var(--code-bg);
   --color-text:       var(--dark-text);
-  --color-text-muted: color-mix(in srgb, var(--dark-text) 55%, var(--paper));
+  /* 65% clears WCAG AA on --paper (~5.4:1); 55% computed to ≈#807F7E ≈3.9:1, failing AA (#91).
+     color-mix re-resolves in the dark scope (cream over deep bg → higher contrast). */
+  --color-text-muted: color-mix(in srgb, var(--dark-text) 65%, var(--paper));
   --color-border:     var(--code-frame);
   --color-link:       var(--warm-blue);
   --color-heading:    var(--warm-blue);