@brandon_m_behring/book-scaffold-astro 4.5.1 → 4.6.1

package/CLAUDE.md

@@ -58,6 +58,35 @@ sources: []                        # array of source-manifest keys
 ---
 ```
 
+### Research-portfolio profile (`src/schemas.ts:researchPortfolioChapterSchema`)
+
+Hybrid of academic + tools provenance with research-paper-style inline sources. Only `title` + `last_verified` are required; all hierarchy and classification fields are optional.
+
+```yaml
+---
+title: "..."                       # required
+last_verified: 2026-05-19          # date, required
+# optional — hierarchy (use whichever fits; all may be omitted)
+slug: ch01-introduction            # defaults to filename
+chapter: 1
+part: 1                            # number OR academic-style string enum
+week: 1
+# optional — status (AUTHORING state) vs freshness (EPISTEMIC type) are ORTHOGONAL
+status: prose_only                 # 'scaffolded'|'prose_only'|'code_only'|'chapter_only'|'reading_only'|'implemented'|'planned'
+freshness: experimental-result     # 'experimental-result'|'literature-survey'|'theoretical'|'reference'
+# optional — provenance + inline sources (T1-T4 tiers)
+volatility: feature-surface        # 'stable-principle'|'architectural-pattern'|'feature-surface'
+tags: [prompt-injection, ...]      # freeform string array
+sources:
+  - tier: T1
+    url: https://...
+    label: Primary source
+# optional: description, draft, updated, author, published, image (SEO/og:*)
+---
+```
+
+**`status` vs `freshness` is the #1 author gotcha.** `status` = authoring state (have I written it?). `freshness` = epistemic type (what kind of evidence?). A chapter can be `status: scaffolded` (not written yet) AND `freshness: theoretical` (will be a math argument). See Recipe 13 for the full table.
+
 ## Component reference
 
 Two callout families coexist. Authors import what they need.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-DLIpEgTm.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, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-DLIpEgTm.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-B2bO9Nga.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, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-B2bO9Nga.js';
 import 'astro/zod';
 
 /**

package/dist/index.mjs

@@ -117,6 +117,7 @@ var init_katex_macros = __esm({
 // src/config.ts
 import mdx from "@astrojs/mdx";
 import preact from "@astrojs/preact";
+import sitemap from "@astrojs/sitemap";
 
 // src/profile-kit.ts
 function defineProfile(p) {
@@ -177,7 +178,14 @@ var academicChapterSchema = z.object({
   tests_path: z.string().optional(),
   notebook_path: z.string().optional(),
   description: z.string().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // All optional; existing chapters without these continue to work.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
@@ -189,7 +197,13 @@ var toolsChapterSchema = z.object({
   sources: z.array(z.string()).default([]),
   description: z.string().optional(),
   draft: z.boolean().default(false),
-  updated: z.date().optional()
+  updated: z.date().optional(),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `updated` already existed; the rest are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var minimalChapterSchema = toolsChapterSchema;
 var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
@@ -216,7 +230,14 @@ var courseNotesChapterSchema = z.object({
   last_verified: z.date(),
   volatility: z.enum(volatilityLevels).default("architectural-pattern"),
   sources: z.array(z.string()).default([]),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` already existed; the rest are new. `instructor` (line 130) is
+  // attribution metadata — distinct from `author` (the note-writer/curator).
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  image: z.string().optional()
 });
 var researchPortfolioChapterSchema = z.object({
   // Identity
@@ -269,7 +290,12 @@ var researchPortfolioChapterSchema = z.object({
   // Status + dates.
   last_verified: z.date(),
   updated: z.date().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` + `updated` already existed; `author` + `published` + `image` are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  image: z.string().optional()
 });
 var sourcesSchema = z.object({
   url: z.string().url(),
@@ -372,8 +398,8 @@ var academicProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // academic consumers ship their own week-based /chapters listing
+    chapters: true,
+    // v4.6.1 (#75 follow-up): auto-injected /chapters/[...slug]/ + /chapters/ index. Pre-v4.3.0 academic books shipped their own listing; v4.6.0 (#76 Layer 3c) removed the consumer template assuming auto-injection. Default flipped here to close the gap. Consumers wanting their own listing override via `routes: { chapters: false }` + their own src/pages/chapters/* — see recipe 18.
     convergence: false,
     // tools-profile-specific
     frontmatter: false,
@@ -387,8 +413,11 @@ var academicProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
-  chaptersRenderer: academicChaptersRenderer
+  chaptersRenderer: academicChaptersRenderer,
   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Academic-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/lib/freshness.ts
@@ -578,7 +607,8 @@ var minimalProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on across all profiles. Consumer override via routes: { chapters: false }.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -602,8 +632,8 @@ var courseNotesProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // multi-book consumers route via [book]/[slug] themselves
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Multi-book consumers (DLAI-style) override via routes: { chapters: false } + own [book]/[slug] routes — see #15 deferred.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -616,7 +646,10 @@ var courseNotesProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
-  chaptersRenderer: fallbackChaptersRenderer
+  chaptersRenderer: fallbackChaptersRenderer,
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Course-notes-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/profiles/research-portfolio.ts
@@ -627,8 +660,8 @@ var researchPortfolioProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // portfolio books ship their own landing/index
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Portfolios still ship their own /frontmatter/* + landing; /chapters/* renders the underlying chapter list.
     convergence: false,
     // tools-profile-specific
     frontmatter: true,
@@ -824,19 +857,19 @@ function defineMdxComponents(components) {
 }
 
 // src/integration.ts
-var LANDING_VIRTUAL_ID = "virtual:book-scaffold/landing-config";
-var LANDING_RESOLVED_ID = "\0" + LANDING_VIRTUAL_ID;
-function makeLandingConfigVitePlugin(config) {
+var BOOK_CONFIG_VIRTUAL_ID = "virtual:book-scaffold/book-config";
+var BOOK_CONFIG_RESOLVED_ID = "\0" + BOOK_CONFIG_VIRTUAL_ID;
+function makeBookConfigVitePlugin(config) {
   const serialized = `export default ${JSON.stringify(config)};`;
   return {
-    name: "book-scaffold:landing-config",
+    name: "book-scaffold:book-config",
     enforce: "pre",
     resolveId(id) {
-      if (id === LANDING_VIRTUAL_ID) return LANDING_RESOLVED_ID;
+      if (id === BOOK_CONFIG_VIRTUAL_ID) return BOOK_CONFIG_RESOLVED_ID;
       return null;
     },
     load(id) {
-      if (id !== LANDING_RESOLVED_ID) return null;
+      if (id !== BOOK_CONFIG_RESOLVED_ID) return null;
       return serialized;
     }
   };
@@ -887,10 +920,14 @@ function bookScaffoldIntegration(opts) {
     routes: userOverrides = {},
     extraStyles = [],
     mdxComponentsModule,
-    // v4.5.0: landing-page data, propagated via vite.define to /index.astro.
+    // v4.5.0: landing-page data, propagated via virtual module to /index.astro.
     title,
     description,
-    portfolio
+    portfolio,
+    // v4.6.0: book-level author + SEO config, propagated through the
+    // (renamed) book-config virtual module to Base.astro + Chapter.astro.
+    author,
+    seo
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -937,11 +974,16 @@ function bookScaffoldIntegration(opts) {
           vite: {
             plugins: [
               makeMdxComponentsVitePlugin(resolvedMdxPath),
-              makeLandingConfigVitePlugin({
+              makeBookConfigVitePlugin({
                 title: title ?? null,
                 description: description ?? null,
                 portfolio: portfolio ?? false,
-                enabledRoutes: enabledRouteNames
+                enabledRoutes: enabledRouteNames,
+                author: author ?? null,
+                seo: {
+                  ogImage: seo?.ogImage ?? null,
+                  twitterHandle: seo?.twitterHandle ?? null
+                }
               })
             ],
             define: {
@@ -1045,19 +1087,36 @@ async function defineBookConfig(opts) {
     ]);
   }
   const resolvedPortfolio = opts.portfolio === false ? false : opts.portfolio ?? BRANDON_PORTFOLIO_DEFAULT;
+  const profileSitemapFilter = PROFILES[profile]?.sitemapFilter;
+  const sitemapFilter = opts.seo?.sitemap?.filter ?? profileSitemapFilter;
+  const sitemapCustomPages = opts.seo?.sitemap?.customPages;
+  const sitemapOptions = {};
+  if (sitemapFilter) sitemapOptions.filter = sitemapFilter;
+  if (sitemapCustomPages) sitemapOptions.customPages = sitemapCustomPages;
   const integrations = [
     mdx(),
     preact(),
+    // v4.6.0: @astrojs/sitemap default integration. Emits
+    // /sitemap-index.xml + per-route sitemaps from the resolved `site:`
+    // (defineBookConfig throws above if site is missing, so the URL is
+    // always available to the sitemap integration here).
+    sitemap(sitemapOptions),
     bookScaffoldIntegration({
       profile,
       routes: mergedRoutes,
       mdxComponentsModule,
       extraStyles: mergedExtraStyles,
       // v4.5.0: pass landing-page data through to the integration so it can
-      // be exposed to the auto-injected /index.astro via vite.define.
+      // be exposed to the auto-injected /index.astro via the virtual module.
       title: opts.title,
       description: opts.description,
-      portfolio: resolvedPortfolio
+      portfolio: resolvedPortfolio,
+      // v4.6.0: book-level author + SEO config (ogImage, twitterHandle),
+      // propagated through the renamed `book-config` virtual module to
+      // Base.astro + Chapter.astro. `seo.sitemap` is NOT passed through —
+      // it's consumed below at config-time by the @astrojs/sitemap call.
+      author: opts.author,
+      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0
     }),
     ...mergedExtraIntegrations
   ];
@@ -1096,6 +1155,9 @@ async function defineBookConfig(opts) {
     title: _title,
     description: _description,
     portfolio: _portfolio,
+    // v4.6.0: strip new book-level SEO opts (author + seo block).
+    author: _author,
+    seo: _seo,
     ...rest
   } = opts;
   void _styles;
@@ -1110,6 +1172,8 @@ async function defineBookConfig(opts) {
   void _title;
   void _description;
   void _portfolio;
+  void _author;
+  void _seo;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const config = {
     site,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-DLIpEgTm.js';
+import { g as BookSchemasOptions } from './types-B2bO9Nga.js';
 import 'astro';
 import 'astro/zod';
 

package/dist/schemas.mjs

@@ -62,7 +62,14 @@ var academicChapterSchema = z.object({
   tests_path: z.string().optional(),
   notebook_path: z.string().optional(),
   description: z.string().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // All optional; existing chapters without these continue to work.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var toolsChapterSchema = z.object({
   title: z.string().min(1),
@@ -74,7 +81,13 @@ var toolsChapterSchema = z.object({
   sources: z.array(z.string()).default([]),
   description: z.string().optional(),
   draft: z.boolean().default(false),
-  updated: z.date().optional()
+  updated: z.date().optional(),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `updated` already existed; the rest are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional()
 });
 var minimalChapterSchema = toolsChapterSchema;
 var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
@@ -101,7 +114,14 @@ var courseNotesChapterSchema = z.object({
   last_verified: z.date(),
   volatility: z.enum(volatilityLevels).default("architectural-pattern"),
   sources: z.array(z.string()).default([]),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` already existed; the rest are new. `instructor` (line 130) is
+  // attribution metadata — distinct from `author` (the note-writer/curator).
+  author: z.string().optional(),
+  published: z.date().optional(),
+  updated: z.date().optional(),
+  image: z.string().optional()
 });
 var researchPortfolioChapterSchema = z.object({
   // Identity
@@ -154,7 +174,12 @@ var researchPortfolioChapterSchema = z.object({
   // Status + dates.
   last_verified: z.date(),
   updated: z.date().optional(),
-  draft: z.boolean().default(false)
+  draft: z.boolean().default(false),
+  // v4.6.0: optional SEO / article:* fields consumed by Chapter.astro.
+  // `tags` + `updated` already existed; `author` + `published` + `image` are new.
+  author: z.string().optional(),
+  published: z.date().optional(),
+  image: z.string().optional()
 });
 var sourcesSchema = z.object({
   url: z.string().url(),
@@ -257,8 +282,8 @@ var academicProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // academic consumers ship their own week-based /chapters listing
+    chapters: true,
+    // v4.6.1 (#75 follow-up): auto-injected /chapters/[...slug]/ + /chapters/ index. Pre-v4.3.0 academic books shipped their own listing; v4.6.0 (#76 Layer 3c) removed the consumer template assuming auto-injection. Default flipped here to close the gap. Consumers wanting their own listing override via `routes: { chapters: false }` + their own src/pages/chapters/* — see recipe 18.
     convergence: false,
     // tools-profile-specific
     frontmatter: false,
@@ -272,8 +297,11 @@ var academicProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
-  chaptersRenderer: academicChaptersRenderer
+  chaptersRenderer: academicChaptersRenderer,
   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Academic-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/lib/freshness.ts
@@ -463,7 +491,8 @@ var minimalProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on across all profiles. Consumer override via routes: { chapters: false }.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -487,8 +516,8 @@ var courseNotesProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // multi-book consumers route via [book]/[slug] themselves
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Multi-book consumers (DLAI-style) override via routes: { chapters: false } + own [book]/[slug] routes — see #15 deferred.
     convergence: false,
     frontmatter: false,
     // opt-in per book; see #7
@@ -501,7 +530,10 @@ var courseNotesProfile = defineProfile({
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
-  chaptersRenderer: fallbackChaptersRenderer
+  chaptersRenderer: fallbackChaptersRenderer,
+  // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
+  // view, crawl-redundant. Course-notes-profile default.
+  sitemapFilter: (page) => !page.includes("/print/")
 });
 
 // src/profiles/research-portfolio.ts
@@ -512,8 +544,8 @@ var researchPortfolioProfile = defineProfile({
     references: true,
     search: true,
     print: true,
-    chapters: false,
-    // portfolio books ship their own landing/index
+    chapters: true,
+    // v4.6.1 (#75 follow-up): default-on. Portfolios still ship their own /frontmatter/* + landing; /chapters/* renders the underlying chapter list.
     convergence: false,
     // tools-profile-specific
     frontmatter: true,

package/examples/chapter-template-research-portfolio.mdx

@@ -1,25 +1,33 @@
 ---
+# required fields — schema will reject the chapter if missing
 title: "Chapter N — Title goes here"
-slug: chN-short-slug
-chapter: 1
-part: 1
+last_verified: 2026-05-19              # required; YAML date (no quotes)
+
+# optional — hierarchy (use whichever fits; all may be omitted)
+slug: chN-short-slug                   # optional; defaults to filename
+chapter: 1                             # optional; tools-style numeric
+part: 1                                # optional; number OR academic-style string enum
 week: 1                                # optional; omit if not on a weekly cadence
-status: prose_only                     # 'prose_only' | 'code_only' | 'implemented' | ...
-freshness: experimental-result         # 'experimental-result' | 'literature-survey' | 'theoretical' | 'reference'
-volatility: feature-surface            # 'stable-principle' | 'architectural-pattern' | 'feature-surface'
-tags:
+
+# optional — status (AUTHORING state) vs freshness (EPISTEMIC type); see Recipe 13
+status: prose_only                     # 'scaffolded'|'prose_only'|'code_only'|'chapter_only'|'reading_only'|'implemented'|'planned'
+freshness: experimental-result         # 'experimental-result'|'literature-survey'|'theoretical'|'reference'
+
+# optional — provenance
+volatility: feature-surface            # 'stable-principle'|'architectural-pattern'|'feature-surface'
+tags:                                  # optional; freeform string array
   - replace-me
   - with
   - real-tags
-sources:
+sources:                               # optional; structured inline T1-T4
   - tier: T1
     url: https://example.invalid/primary-source
     label: Primary source (e.g., NVD CVE / arXiv paper / official spec)
   - tier: T2
     url: https://example.invalid/secondary
     label: Secondary corroboration
-last_verified: 2026-05-19
-draft: true
+
+draft: true                            # optional; defaults to false
 ---
 
 import PreReleaseBanner from '@brandon_m_behring/book-scaffold-astro/components/PreReleaseBanner.astro';

package/layouts/Base.astro

@@ -50,6 +50,10 @@ import '../styles/print.css';
 import VersionSelector from '@brandon_m_behring/book-scaffold-astro/components/VersionSelector';
 import ToolFilter from '@brandon_m_behring/book-scaffold-astro/components/ToolFilter';
 import Sidebar from '../components/Sidebar.astro';
+// v4.6.0: SEO meta tags read book-level identity (title fallback,
+// description fallback, ogImage default, twitterHandle) from the
+// book-config virtual module (was landing-config in v4.5.1).
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
 const showToolsChrome = profile !== 'academic';
@@ -59,9 +63,37 @@ interface Props {
   description?: string;
   lang?: string;
   showSidebar?: boolean;
+  /** v4.6.0: Open Graph image URL (relative to site root, or absolute). */
+  ogImage?: string;
+  /** v4.6.0: Open Graph type. Defaults to 'website'; Chapter.astro passes 'article'. */
+  ogType?: string;
 }
 
-const { title, description, lang = 'en', showSidebar = true } = Astro.props;
+const {
+  title,
+  description,
+  lang = 'en',
+  showSidebar = true,
+  ogImage,
+  ogType = 'website',
+} = Astro.props;
+
+// v4.6.0: canonical + og:url need Astro.site. defineBookConfig throws at
+// config-load if `site` is missing, so Astro.site is guaranteed populated
+// here. `new URL` resolves the relative pathname against it.
+const canonicalURL = new URL(Astro.url.pathname, Astro.site).toString();
+
+// Per D3: og:image emits only when an image is explicitly set — either via
+// per-page Astro.props.ogImage or book-level bookConfig.seo.ogImage. No
+// '/og-default.png' fallback to avoid broken-link meta tags on consumers
+// without an OG image authored.
+const resolvedOgImage = ogImage ?? bookConfig.seo?.ogImage ?? null;
+const absoluteOgImage = resolvedOgImage
+  ? new URL(resolvedOgImage, Astro.site).toString()
+  : null;
+const twitterHandle = bookConfig.seo?.twitterHandle ?? null;
+const ogSiteName = bookConfig.title ?? title;
+const ogDescription = description ?? bookConfig.description ?? '';
 ---
 
 <!doctype html>
@@ -74,6 +106,27 @@ const { title, description, lang = 'en', showSidebar = true } = Astro.props;
     <meta name="generator" content={Astro.generator} />
     <title>{title}</title>
     {description && <meta name="description" content={description} />}
+
+    {/* v4.6.0: SEO meta-tag block (issue #76 Primary). canonical + og:* +
+        twitter:* on every page; article:* lives in Chapter.astro via the
+        Base `<slot name="head" />` (below). og:image + twitter:image emit
+        only when an image is explicitly set (per D3, avoids broken-link
+        OG tags). sitemap link points at @astrojs/sitemap's auto-emitted
+        index. */}
+    <link rel="canonical" href={canonicalURL} />
+    <link rel="sitemap" type="application/xml" href="/sitemap-index.xml" />
+    <meta property="og:title" content={title} />
+    {ogDescription && <meta property="og:description" content={ogDescription} />}
+    <meta property="og:url" content={canonicalURL} />
+    <meta property="og:type" content={ogType} />
+    <meta property="og:site_name" content={ogSiteName} />
+    {absoluteOgImage && <meta property="og:image" content={absoluteOgImage} />}
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content={title} />
+    {ogDescription && <meta name="twitter:description" content={ogDescription} />}
+    {absoluteOgImage && <meta name="twitter:image" content={absoluteOgImage} />}
+    {twitterHandle && <meta name="twitter:site" content={twitterHandle} />}
+
     {/* FOUC prevention — apply saved theme before any paint. */}
     <script is:inline>
       (function () {

package/layouts/Chapter.astro

@@ -12,10 +12,17 @@
  *
  * Driven by a CollectionEntry<'chapters'> passed in Astro.props.entry
  * plus the `headings` array Astro's MDX renderer provides.
+ *
+ * v4.6.0: passes ogType="article" to Base + emits article:* meta tags via
+ * Base's `<slot name="head" />`. Article tags read from chapter frontmatter
+ * (`author`, `published`, `updated`, `tags`) with `author` falling back to
+ * book-level `bookConfig.author`. `entry.data.image` (chapter-specific OG
+ * image) is passed as `ogImage` for richer per-chapter social cards.
  */
 import type { CollectionEntry } from 'astro:content';
 import type { MarkdownHeading } from 'astro';
 import Base from './Base.astro';
+import bookConfig from 'virtual:book-scaffold/book-config';
 import ChapterHeader from '../components/ChapterHeader.astro';
 import ChapterTOC from '../components/ChapterTOC.astro';
 import ChapterNav from '../components/ChapterNav.astro';
@@ -25,9 +32,36 @@ interface Props {
   headings: MarkdownHeading[];
 }
 const { entry, headings } = Astro.props;
+
+// v4.6.0: article:* meta-tag data. All fields are Zod-optional in the
+// chapter schemas (academic / tools / course-notes / research-portfolio),
+// so any of these may be undefined. `author` falls back to bookConfig.author
+// (the top-level defineBookConfig field) so single-author books don't
+// repeat themselves per chapter.
+const articleAuthor =
+  (entry.data as { author?: string }).author ?? bookConfig.author ?? null;
+const articlePublished = (entry.data as { published?: Date }).published;
+const articleUpdated = (entry.data as { updated?: Date }).updated;
+const articleTags = ((entry.data as { tags?: string[] }).tags ?? []) as string[];
+const chapterImage = (entry.data as { image?: string }).image;
 ---
 
-<Base title={entry.data.title} description={entry.data.description}>
+<Base
+  title={entry.data.title}
+  description={entry.data.description}
+  ogType="article"
+  ogImage={chapterImage}
+>
+  <Fragment slot="head">
+    {articleAuthor && <meta property="article:author" content={articleAuthor} />}
+    {articlePublished && (
+      <meta property="article:published_time" content={articlePublished.toISOString()} />
+    )}
+    {articleUpdated && (
+      <meta property="article:modified_time" content={articleUpdated.toISOString()} />
+    )}
+    {articleTags.map((t) => <meta property="article:tag" content={t} />)}
+  </Fragment>
   <article class="prose">
     <ChapterHeader data={entry.data} />
     <ChapterTOC headings={headings} />

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.5.1",
+  "version": "4.6.1",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -152,6 +152,7 @@
     "remark-math": { "optional": true }
   },
   "dependencies": {
+    "@astrojs/sitemap": "^3.6.1",
     "@citation-js/core": "^0.7.21",
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",

package/pages/index.astro

@@ -9,8 +9,10 @@
  * config needed.
  *
  * Reads book identity + portfolio + enabled-routes from the
- * `virtual:book-scaffold/landing-config` virtual module exposed by
- * makeLandingConfigVitePlugin (see integration.ts §4.5.1). v4.5.0 used
+ * `virtual:book-scaffold/book-config` virtual module exposed by
+ * makeBookConfigVitePlugin (renamed from makeLandingConfigVitePlugin in
+ * v4.6.0 since Base.astro now also imports the module on every page).
+ * v4.5.0 used
  * import.meta.env.BOOK_* env vars; that pattern was vulnerable to silent
  * override by consumer .env files (caught during DML deploy when a stale
  * `BOOK_TITLE=web` in web/.env overrode defineBookConfig({title})). The
@@ -31,7 +33,7 @@
  *     or defineBookConfig({ portfolio: false })
  */
 import Base from '../layouts/Base.astro';
-import bookConfig from 'virtual:book-scaffold/landing-config';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 const title = bookConfig.title ?? 'book-scaffold-astro';
 const description = bookConfig.description;