@brandon_m_behring/book-scaffold-astro 5.0.0 → 5.2.0

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { i as BookSchemasOptions } from './types-D1QZgKMO.js';
+import { i as BookSchemasOptions } from './types-DjqMnwHw.js';
 import 'astro';
 import './schemas-CKipJ5Ie.js';
 import 'astro/zod';

package/dist/{types-D1QZgKMO.d.ts → types-DjqMnwHw.d.ts}

@@ -545,6 +545,17 @@ type SiblingBooks = Record<string, SiblingBookEntry>;
 interface SecurityHeadersConfig {
     contentSecurityPolicy?: string;
 }
+/**
+ * v5.2.0 (#157): build-time Open Graph card generation.
+ *
+ * Omit `enabled` (or set it to `true`) to enable generation when the object
+ * form is present. `exclude` contains base-relative route patterns validated
+ * by the OG-card integration during config evaluation.
+ */
+interface OgCardsConfig {
+    enabled?: boolean;
+    exclude?: readonly string[];
+}
 /**
  * v4.26.2 (#149): book-level release state rendered by
  * `<PreReleaseBanner>` across every page.
@@ -746,9 +757,10 @@ interface BookConfigOptions {
      * `ogImage` — default Open Graph image URL (relative to the site root, or
      * absolute). When omitted, no `<meta property="og:image">` is emitted by
      * default; per-page `Astro.props.ogImage` can still set one. Consumers
-     * opt-in to OG cards by adding e.g. `/og-default.png` to their `public/`
-     * AND setting `seo: { ogImage: '/og-default.png' }`. Avoids broken-link
-     * meta tags on consumers who haven't authored an OG image yet.
+     * opt in to a static default by adding e.g. `/og-default.png` to `public/`
+     * and setting `seo: { ogImage: '/og-default.png' }`. A static default
+     * suppresses generation; use `ogCards` below for generated cards. Omitting
+     * both avoids broken-link meta tags when no image has been authored.
      *
      * `twitterHandle` — adds `<meta name="twitter:site" content="@handle">`
      * when set. Omitted by default.
@@ -765,6 +777,12 @@ interface BookConfigOptions {
     seo?: {
         ogImage?: string;
         twitterHandle?: string;
+        /**
+         * v5.2.0 (#157): opt into deterministic, build-time social cards. `true`
+         * uses the defaults; the object form can disable generation explicitly or
+         * add base-relative route exclusions.
+         */
+        ogCards?: boolean | OgCardsConfig;
         sitemap?: {
             filter?: (page: string) => boolean;
             customPages?: string[];
@@ -963,4 +981,4 @@ declare function resolvePreset(explicitPreset?: BookPreset, explicitProfile?: Bo
  */
 declare function resolveProfile(explicit?: BookProfile): BookProfile;
 
-export { defineProfile as A, BOOK_PRESETS as B, CORPUS_APPARATUS_ROUTES as C, defineStyle as D, normalizeFrontmatterConfig as E, type FreshnessAffordance as F, resolvePreset as G, resolveProfile as H, NUMBER_STYLES as N, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookCorpus as d, type BookCorpusInput as e, type BookPreset as f, type BookProfile as g, type BookScaffoldIntegrationOptions as h, type BookSchemasOptions as i, type ChapterFor as j, type ChaptersRenderer as k, type CorpusApparatusRoute as l, type CorpusBook as m, type CorpusBookInput as n, type FrontmatterRouteConfig as o, type NumberStyle as p, type PartialRouteToggles as q, type ProfileDefinition as r, type RouteToggles as s, type SiblingBookDescriptor as t, type SiblingBookEntry as u, type SiblingBooks as v, type StatusBadge as w, type Style as x, type StyleInput as y, composeStyles as z };
+export { defineProfile as A, BOOK_PRESETS as B, CORPUS_APPARATUS_ROUTES as C, defineStyle as D, normalizeFrontmatterConfig as E, type FreshnessAffordance as F, resolvePreset as G, resolveProfile as H, NUMBER_STYLES as N, type OgCardsConfig as O, type PartKey as P, type ReleaseStatusConfig as R, type SecurityHeadersConfig as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookCorpus as d, type BookCorpusInput as e, type BookPreset as f, type BookProfile as g, type BookScaffoldIntegrationOptions as h, type BookSchemasOptions as i, type ChapterFor as j, type ChaptersRenderer as k, type CorpusApparatusRoute as l, type CorpusBook as m, type CorpusBookInput as n, type FrontmatterRouteConfig as o, type NumberStyle as p, type PartialRouteToggles as q, type ProfileDefinition as r, type RouteToggles as s, type SiblingBookDescriptor as t, type SiblingBookEntry as u, type SiblingBooks as v, type StatusBadge as w, type Style as x, type StyleInput as y, composeStyles as z };

package/layouts/Base.astro

@@ -124,18 +124,112 @@ const showToolsChrome = (profile !== 'academic') && showChrome;
 // here. `new URL` resolves the relative pathname against it.
 const canonicalURL = new URL(Astro.url.pathname, Astro.site).toString();
 
+const baseUrl = normalizeBase(import.meta.env.BASE_URL);
+
+/**
+ * Public assets are authored relative to the deployment root, while `site`
+ * may already carry that same Astro base. Resolve against the origin and add
+ * the normalized base only when it is not already present so every local
+ * image receives the deployment prefix exactly once.
+ */
+function resolvePublicAssetUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error('Open Graph image must be a non-empty URL or public asset path.');
+  }
+  const site = new URL(Astro.site);
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    try {
+      const absolute = new URL(trimmed);
+      if (absolute.protocol !== 'http:' && absolute.protocol !== 'https:') throw new Error();
+    } catch {
+      throw new Error(`Open Graph image is not a valid http(s) URL: ${JSON.stringify(value)}`);
+    }
+    return trimmed;
+  }
+  if (trimmed.startsWith('//')) {
+    if (trimmed.startsWith('///')) {
+      throw new Error(
+        `Open Graph image has an invalid protocol-relative URL: ${JSON.stringify(value)}`,
+      );
+    }
+    try {
+      const absolute = new URL(`${site.protocol}${trimmed}`);
+      if (absolute.protocol !== 'http:' && absolute.protocol !== 'https:') throw new Error();
+      return absolute.toString();
+    } catch {
+      throw new Error(
+        `Open Graph image has an invalid protocol-relative URL: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+  if (/^[a-z][a-z\d+.-]*:/i.test(trimmed)) {
+    throw new Error(
+      `Open Graph image must use http(s) or a public asset path: ${JSON.stringify(value)}`,
+    );
+  }
+  if (trimmed.includes('\\') || /[\u0000-\u001F\u007F]/u.test(trimmed)) {
+    throw new Error(
+      `Open Graph image contains an invalid path character: ${JSON.stringify(value)}`,
+    );
+  }
+
+  const rawPath = trimmed.split(/[?#]/u, 1)[0] ?? '';
+  if (!rawPath) {
+    throw new Error(`Open Graph image must contain a public asset path: ${JSON.stringify(value)}`);
+  }
+  for (const rawSegment of rawPath.replace(/^\/+/, '').split('/')) {
+    let segment = rawSegment;
+    try {
+      for (let pass = 0; pass < 4; pass += 1) {
+        const decoded = decodeURIComponent(segment);
+        if (decoded === segment) break;
+        segment = decoded;
+      }
+    } catch {
+      throw new Error(
+        `Open Graph image contains invalid percent encoding: ${JSON.stringify(value)}`,
+      );
+    }
+    if (
+      segment === '.'
+      || segment === '..'
+      || segment.includes('/')
+      || segment.includes('\\')
+      || /[\u0000-\u001F\u007F]/u.test(segment)
+    ) {
+      throw new Error(
+        `Open Graph image contains an invalid decoded path segment: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+
+  const localPath = `/${rawPath.replace(/^\/+/, '')}`;
+  const suffix = trimmed.slice(rawPath.length);
+  const basePath = baseUrl.startsWith('/') ? baseUrl : `/${baseUrl}`;
+  const baseWithoutTrailingSlash = basePath.replace(/\/+$/, '');
+  const alreadyPrefixed = basePath === '/'
+    || localPath === baseWithoutTrailingSlash
+    || localPath.startsWith(basePath);
+  const resolvedPath = alreadyPrefixed
+    ? localPath
+    : `${basePath}${localPath.slice(1)}`;
+
+  return new URL(`${resolvedPath}${suffix}`, site.origin).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 ?? corpusBook?.image ?? bookConfig.seo?.ogImage ?? null;
 const absoluteOgImage = resolvedOgImage
-  ? new URL(resolvedOgImage, Astro.site).toString()
+  ? resolvePublicAssetUrl(resolvedOgImage)
   : null;
 const twitterHandle = bookConfig.seo?.twitterHandle ?? null;
 const ogSiteName = corpusBook?.title ?? bookConfig.title ?? title;
 const ogDescription = description ?? corpusBook?.description ?? bookConfig.description ?? '';
-const baseUrl = normalizeBase(import.meta.env.BASE_URL);
 const searchHref = bookId
   ? `${baseUrl}search/?book=${encodeURIComponent(bookId)}`
   : `${baseUrl}search/`;
@@ -147,7 +241,11 @@ const pagefindFilter = bookId
 ---
 
 <!doctype html>
-<html lang={lang}>
+<html
+  lang={lang}
+  data-book-scaffold-book={corpusBook?.id}
+  data-book-scaffold-surface={pagefindSurface === 'corpus' ? 'corpus' : undefined}
+>
   <head>
     <meta charset="utf-8" />
     <link rel="icon" type="image/svg+xml" href={`${baseUrl}favicon.svg`} />

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -158,6 +158,7 @@
     "src/schemas.ts",
     "src/types.ts",
     "components",
+    "assets",
     "styles",
     "layouts",
     "pages",
@@ -203,11 +204,14 @@
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
+    "@resvg/resvg-js": "^2.6.2",
+    "ajv": "^8.20.0",
     "pagefind": "^1.5.2",
     "parse5": "^7.3.0",
     "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
+    "satori": "^0.26.0",
     "unified": "^11.0.5",
     "vite": "^7.3.2",
     "yaml": "^2.9.0"

package/recipes/25-qa-readiness.md

@@ -0,0 +1,197 @@
+# Recipe 25 — QA and content readiness
+
+**Profile**: any, in single-book or corpus mode.
+
+**TL;DR**: `book-scaffold qa` turns the scaffold's content contract and stable
+MDX facts into one CI-safe readiness verdict. Human output is the default;
+`--format json` emits deterministic schema-v1 JSON. Use
+`book-scaffold init-qa` only when a portfolio QA engine needs a network-free
+`guide_qa.yaml` registry.
+
+## Run the readiness check
+
+Run the locally installed binary from the book root:
+
+```bash
+npm exec -- book-scaffold qa
+```
+
+This checks the implicit book in a single-book project. In a corpus, omission
+of a selector checks every manifest book in manifest order. Select one exact
+registered id or spell out the all-books default with:
+
+```bash
+npm exec -- book-scaffold qa --book evaluation
+npm exec -- book-scaffold qa --all
+```
+
+`--book` is invalid in single-book mode. `--book` and `--all` are mutually
+exclusive; an unknown book id is an invocation error rather than an empty
+report.
+
+## What QA means
+
+QA reuses the same content-contract library as `book-scaffold validate`, then
+adds deterministic readiness facts:
+
+| Check | Blocking condition |
+|---|---|
+| `content_contract` | Any validation error |
+| `chapters` | No non-draft chapter |
+| `links` | Any broken internal target or fragment |
+| `learning_objectives` | Less than 100% anchor coverage when objectives apply |
+| `components` | Never blocking; counts scaffold MDX components |
+| `demo_fixtures` | Invalid non-generated JSON or a failing referenced schema |
+
+An unavailable metric is `not_applicable`, not a fabricated zero. Component
+counts are inventory facts, not universal prose-quality scores. `qa` also does
+not replace `astro build`: rendering, content-collection Zod checks, and KaTeX
+remain build responsibilities.
+
+The traffic-light states are `green`, `amber`, `red`, and `not_applicable`.
+Amber advisories stay visible but do not fail CI. Exit status is:
+
+| Exit | Meaning |
+|---|---|
+| `0` | No blocking failure (`green` or `amber`) |
+| `1` | At least one selected book or corpus-shared check is `red` |
+| `2` | Invalid invocation, unresolved configuration, or internal failure |
+
+The link check inspects internal links authored in chapter Markdown/MDX. It
+uses the resolved scaffold route toggles, Astro page conventions, and public
+assets as its route oracle. Fragments that depend on a consumer-defined MDX
+component or a known non-chapter route are reported as amber
+`fragment_unverified` advisories instead of guessed successes or blocking
+failures.
+
+Schema-v1 fixture validation supports JSON Schema draft-07 (also the default
+when `$schema` is absent), 2019-09, and 2020-12. Recursive `$ref` resources must
+remain inside the project after symlink resolution; QA never fetches network
+schemas. The JSON Schema `format` keyword is annotation-only in v1. Unsupported
+or mixed dialects and out-of-project references make that fixture red.
+
+## Human and JSON output
+
+Human output is compact and terminal-oriented:
+
+```bash
+npm exec -- book-scaffold qa --format human
+```
+
+For automation, use the stable JSON form (`--json` is an alias):
+
+```bash
+npm --offline exec -- book-scaffold qa --format json > qa-result.json
+```
+
+JSON stdout contains only the schema-v1 document; progress and fatal
+diagnostics use stderr. The document omits timestamps and durations, preserves
+manifest/source order, and always contains `books`, `shared`, and `summary`.
+
+`books` contains only the implicit `book` result or registered manifest ids.
+`shared` is never a synthetic book. It is an always-present aggregate shaped
+like a book result:
+
+```json
+{
+  "verdict": "not_applicable",
+  "checks": {},
+  "diagnostics": []
+}
+```
+
+That exact value is used in single-book mode. In corpus mode,
+`shared.checks.demo_fixtures` holds the normal `{ state, metrics,
+diagnosticIds }` check payload for JSON under `src/data/` outside a registered
+book directory. A shared failure affects the top-level corpus verdict and
+summary, never an individual book verdict. Its diagnostics use
+`book: "corpus"` rather than borrowing a manifest id.
+
+## Generate `guide_qa.yaml`
+
+Portfolio-level QA engines can discover the scaffold check without a custom
+consumer wrapper:
+
+```bash
+npm exec -- book-scaffold init-qa
+```
+
+A single-book project gets this deterministic file:
+
+```yaml
+# Generated by book-scaffold init-qa.
+# Regenerate with: book-scaffold init-qa --force
+version: 1
+guides:
+  - id: book
+    check_cmd: npm --offline exec -- book-scaffold qa --format json
+```
+
+A corpus gets one entry per manifest book, in manifest order, with an exact
+selector:
+
+```yaml
+# Generated by book-scaffold init-qa.
+# Regenerate with: book-scaffold init-qa --force
+version: 1
+guides:
+  - id: evaluation
+    check_cmd: npm --offline exec -- book-scaffold qa --book evaluation --format json
+  - id: llm-app-engineering
+    check_cmd: npm --offline exec -- book-scaffold qa --book llm-app-engineering --format json
+```
+
+The generated `npm --offline exec --` commands can use only the installed
+toolkit; they never fetch a package. `book-scaffold qa` does not read or
+execute `guide_qa.yaml` itself.
+
+An existing file is preserved and makes `init-qa` fail. Regenerate explicitly
+with:
+
+```bash
+npm exec -- book-scaffold init-qa --force
+```
+
+`--force` replaces the whole `guide_qa.yaml` and changes no other file. A
+portfolio engine may add presentation fields, but forced regeneration removes
+those edits.
+
+## CI wiring
+
+After the dependency install, offline execution prevents a typo or missing
+local binary from becoming an implicit registry download:
+
+```yaml
+- run: npm ci
+- run: npm --offline exec -- book-scaffold qa --format json > qa-result.json
+- run: npm run build
+```
+
+Keep the build step. QA supplies a content-health verdict; the production
+build remains the render/deployment gate.
+
+## Common gotchas
+
+- **Treating N/A as zero** — unavailable profile/content metrics are explicitly
+  `not_applicable`.
+- **Expecting `components` to grade prose** — counts are informational and
+  never impose cross-preset quotas.
+- **Attributing shared corpus JSON to a book** — only files beneath
+  `src/data/<book>/` belong to that book. Other non-generated JSON is checked
+  once through the top-level `shared` result.
+- **Counting generated indexes as fixtures** — scaffold outputs including
+  `labels.json`, `references.json`, `tips.json`, and `exercises.json` are
+  excluded.
+- **Hand-editing generated commands** — use engine-owned presentation fields
+  if needed; `init-qa --force` intentionally restores canonical commands.
+- **Using `--book` for a one-book project** — the implicit id is represented as
+  `book` in results and `guide_qa.yaml`, but it is not a selectable corpus id.
+
+## Canonical files
+
+- `scripts/qa-core.mjs` — deterministic check and aggregate engine
+- `scripts/init-qa.mjs` — deterministic, overwrite-safe registry generator
+- `scripts/validate-core.mjs` — shared validation library used by QA's
+  content contract
+- `recipes/09-validation.md` — individual diagnostics and prebuild wiring
+- `../../docs/plans/active/qa-contract.md` — accepted schema and selector contract

package/recipes/26-generated-og-cards.md

@@ -0,0 +1,205 @@
+# Recipe 26 — Generate Open Graph cards at build time
+
+**Profile**: any, in single-book or corpus mode.
+
+**TL;DR**: Set `seo.ogCards: true` to generate a deterministic 1200×630 PNG
+for each eligible rendered HTML page that does not already have an authored
+Open Graph image. Generation runs offline after all other integrations, writes
+content-addressed files beneath `_og/`, and patches only the missing image
+metadata. A page image, corpus-book manifest image, or static `seo.ogImage`
+always wins.
+
+## Opt in
+
+The short form enables generation with only the built-in exclusions:
+
+```ts
+import {
+  academicStyle,
+  defineBookConfig,
+} from '@brandon_m_behring/book-scaffold-astro';
+
+export default await defineBookConfig({
+  styles: [academicStyle],
+  site: 'https://book.example/',
+  seo: {
+    ogCards: true,
+  },
+});
+```
+
+Use the object form when particular routes should not receive cards:
+
+```ts
+seo: {
+  ogCards: {
+    enabled: true,
+    exclude: [
+      '/print/',       // exact route
+      '/drafts/*/',    // one complete path segment
+      '/archive/**',   // zero or more complete path segments
+    ],
+  },
+}
+```
+
+`ogCards` is `false` by default. `false` and `{ enabled: false }` both disable
+the generator. Exclusion patterns are base-relative route paths, even when
+Astro `base` is not `/`; do not repeat the deployment base in the pattern.
+
+The accepted grammar is deliberately small:
+
+| Form | Meaning |
+|---|---|
+| `/some/route/` | Match that normalized route exactly |
+| `*` path segment | Match exactly one complete segment |
+| `**` path segment | Match zero or more complete segments |
+
+Wildcards are whole segments, not substring syntax, and a trailing slash is
+significant. Patterns must start `/` and cannot contain a host, query,
+fragment, backslash, control character, empty internal segment, `.`/`..`, or
+unsupported `?`/`[]`/`{}` glob syntax. Invalid and duplicate patterns fail
+configuration instead of being ignored. The configured list augments built-in
+skips for emitted 404/500 files, meta-refresh redirects, and
+`robots`/`googlebot` `noindex` pages.
+
+## Know which image wins
+
+Image precedence is strict:
+
+1. a page/layout `ogImage`, including chapter frontmatter `image`;
+2. the current corpus book's manifest `image`;
+3. the static application default at `seo.ogImage`;
+4. a generated per-page card.
+
+The integration inspects the final HTML. If it finds a valid
+`<meta property="og:image">`, it leaves that tag and the page untouched. This
+makes a one-page override, corpus-book image, and application-wide static
+default reliable opt-outs from generation without a second exclusion list.
+
+When generation is selected, the integration adds this complete image set:
+
+```html
+<meta property="og:image" content="https://book.example/_og/0123abcd4567ef89.png">
+<meta property="og:image:width" content="1200">
+<meta property="og:image:height" content="630">
+<meta property="og:image:type" content="image/png">
+<meta name="twitter:image" content="https://book.example/_og/0123abcd4567ef89.png">
+```
+
+Existing title, description, canonical, and Twitter text metadata remain
+authoritative. The integration does not change sitemap or Pagefind inclusion.
+
+## What the build emits
+
+The generator runs in the final `astro:build:done` hook, after scaffold and
+consumer integrations have rendered their output. It walks emitted HTML in
+stable pathname order, derives the card from the rendered metadata, renders an
+SVG tree with Satori, converts it with `@resvg/resvg-js`, and writes a 1200×630
+PNG at:
+
+```text
+_og/<first-16-hex-of-content-sha256>.png
+```
+
+The hash covers template version 1, dimensions, resolved preset and exact
+corpus book id (or `null`), the clamped book/page/description strings, and the
+rendered canonical hostname. The route is not drawn on the card. Two pages
+with the same visual payload reuse one file; changing a visual input produces
+a new immutable URL. A same-hash/different-bytes collision fails the build.
+
+Only images referenced by the current build remain. Astro normally empties the
+output directory first; when `emptyOutDir: false` preserves it, the integration
+automatically prunes stale scaffold-owned `_og` filenames matching exactly 16
+hex characters plus `.png`. It leaves every other file untouched, so there is
+no user-managed cache or cleanup step.
+
+## Offline fonts and deterministic content
+
+Cards contain the page title, optional description, resolved book or corpus
+title, canonical hostname, and a small scaffold/profile mark. After whitespace
+normalization, values are clamped by Unicode code point: page title 96,
+description 180, book/corpus title 72, and hostname 80. Truncated values use a
+word-boundary ellipsis when possible.
+
+Satori receives the package-owned Inter v4.1 assets
+`assets/og-fonts/Inter-Regular.ttf` and `Inter-Bold.ttf` under the OFL 1.1. The
+build never downloads a web font or uses a consumer machine's installed fonts,
+so an unchanged payload produces unchanged bytes on supported platforms. The
+five presets use one accessible layout and type scale with preset-specific
+colors. Corpus books keep the corpus-wide preset; the generator never invents
+a per-book profile.
+
+## Corpus identity and Astro base
+
+Corpus pages use the identity marker emitted by the scaffold runtime. A book
+chapter therefore receives its registered book title, even when two books
+reuse the same local slug or page title. Corpus-level landing and search pages
+use corpus identity and are not attributed to the first manifest book.
+
+The physical file is `<outDir>/_og/<hash>.png`. Its metadata URL combines the
+Astro `site` origin, normalized `base`, and `_og/<hash>.png` exactly once. Keep
+exclusion patterns base-relative: a deployment at `base: '/manual/'` still
+excludes its print page with `/print/`, while emitted metadata points beneath
+`https://book.example/manual/_og/…`.
+
+## Failure and skip behavior
+
+An enabled generator is fail-loud. A generated card requires one absolute
+`http(s)` canonical link and a non-empty rendered `og:title` or `<title>`.
+Missing, invalid, duplicate, or contradictory metadata/identity; unreadable
+output; font or renderer failure; a hash collision; or inability to patch the
+selected HTML fails the Astro build. It never publishes image metadata without
+the corresponding PNG and never silently downgrades a requested card.
+
+Expected exclusions are skips, not errors: a valid absolute `http(s)` authored
+image, configured patterns, emitted 404/500 files, meta-refresh redirects,
+`robots`/`googlebot` `noindex`, and non-HTML output do not generate a PNG.
+Corpus/static precedence injects its image URL without rendering a PNG.
+Server/SSR routes, runtime image services, remote templates, arbitrary
+consumer JSX card templates, and animation are outside this build-time
+contract.
+
+## Verify a deployment
+
+Build normally, then inspect both the metadata and referenced file:
+
+```bash
+npm run build
+find dist -path '*/_og/*.png' -print
+grep -R 'property="og:image"' dist --include='*.html'
+```
+
+For a subpath deployment, confirm the absolute meta URL includes `base` once.
+Build twice without changing metadata and confirm the same payload keeps the
+same filename. Add a page override and confirm its authored image remains
+unchanged.
+
+## Common gotchas
+
+- **Setting both `seo.ogImage` and `seo.ogCards`** — the static image wins on
+  every page without a page or corpus-book image, so no generated fallback is
+  needed there.
+- **Including Astro `base` in `exclude`** — patterns are matched after base
+  normalization; write `/print/`, not `/manual/print/`.
+- **Using `*` for nested paths** — `*` crosses exactly one segment; use `**`
+  for any depth.
+- **Expecting runtime generation** — cards are created only for static HTML
+  present at `astro:build:done`.
+
+## Canonical files
+
+- `src/types.ts` — `OgCardsConfig` and `seo.ogCards`
+- `src/config.ts` — opt-in normalization and final integration ordering
+- `src/lib/og-cards.ts` — route matching, rendered-metadata extraction, rendering,
+  hashing, emission, and HTML patching
+- `assets/og-fonts/` — package-owned Inter v4.1 TTF assets, `LICENSE.txt`, and
+  provenance in `SOURCE.md`
+- `tests/og-cards.test.mjs` — precedence, routes, corpus/base, determinism, and
+  failure contracts
+
+## Reference implementation
+
+The package fixtures exercise all five presets, root and non-root bases, and a
+two-book corpus. A consumer needs no page source or runtime endpoint beyond the
+`seo.ogCards` opt-in shown above.

package/recipes/README.md

@@ -30,6 +30,8 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 22 | [Responsive navigation and custom routing](22-responsive-nav-and-multibook-routing.md) | any | Mobile/desktop nav and the v4-compatible consumer-owned route-token API |
 | 23 | [Interactive demo substrate](23-interactive-demo-substrate.md) | any | Opt-in Preact shell, slider, stat cards, theme colors, a11y, and reduced motion |
 | 24 | [Figure authoring standard](24-figure-authoring-standard.md) | any | Warm–Tol semantics, Okabe–Ito series, dual-theme exports, contrast, and accessible descriptions |
+| 25 | [QA and content readiness](25-qa-readiness.md) | any | Stable human/JSON readiness verdicts, corpus selection, CI, and `guide_qa.yaml` |
+| 26 | [Build-time Open Graph cards](26-generated-og-cards.md) | any | Opt-in deterministic 1200×630 cards, precedence, exclusions, corpus identity, and base-safe URLs |
 
 ## How to read recipes