@brandon_m_behring/book-scaffold-astro 5.0.0 → 5.2.0

package/CLAUDE.md

@@ -50,9 +50,11 @@ those directories belong to scaffold content collections, not chapter owners.
 Keep every lookup book-scoped: navigation/previous-next, labels, references,
 tips, exercises, questions, and glossary entries must select the current
 manifest book. Corpus JSON is `{ schemaVersion: 1, books: { [id]: payload } }`;
-single-book JSON remains flat. Use `--book <id>` only with the content-derived
-`build-labels`, `build-bib`, `build-tips`, `build-exercises`, and `validate`
-commands. Figures and notebooks remain application-wide.
+single-book JSON remains flat. The content-derived `build-labels`, `build-bib`,
+`build-tips`, `build-exercises`, and `validate` commands accept `--book <id>`
+in corpus mode. `qa` defaults to all manifest books, accepts either one exact
+`--book <id>` or `--all`, and rejects `--book` in single-book mode. Figures and
+notebooks remain application-wide.
 
 Convergence collateral lives at `changelog/<book>/patterns.yaml` and
 `changelog/<book>/tools/*.yaml`; root-level v4 collateral is single-book only.
@@ -201,6 +203,7 @@ npm install                  # once after clone
 npm run dev                  # localhost:4321
 npm run build                # astro build + pagefind index → dist/
 npm run validate             # pre-flight check (recipe 09)
+npm exec -- book-scaffold qa # content-readiness verdict (recipe 25)
 npm run build:bib            # rebuild references.json after .bib edit
 npm run pdf                  # render dist-pdf/book.pdf via Paged.js
 ```
@@ -227,6 +230,46 @@ A consumer `public/_headers` wins unchanged. Use
 or `securityHeaders: false` when another layer owns all headers. Recipe 05 has
 the full precedence and customization contract.
 
+## Build-time Open Graph cards (v5.2, opt-in)
+
+Set `seo: { ogCards: true }` in `defineBookConfig` to generate deterministic
+1200×630 PNG social cards for eligible static HTML that has no authored image.
+The object form accepts `{ enabled?: boolean, exclude?: string[] }`; exclusions
+are base-relative exact routes or whole-segment globs (`*` crosses one segment,
+`**` crosses zero or more). Invalid patterns fail configuration.
+
+Rendered image precedence is page/layout `ogImage` (including chapter
+frontmatter `image`) → current corpus book manifest `image` → static
+`seo.ogImage` → generated card. Generation runs after every consumer
+integration and patches only missing OG/Twitter image tags. It writes
+content-addressed `_og/<hash>.png` assets using package-owned local fonts and
+no network request. Corpus pages retain their resolved book identity; corpus
+surfaces use corpus identity; metadata combines `site` and Astro `base`
+exactly once. A requested card that cannot render, write, or patch fails the
+build. See Recipe 26 before changing card metadata, exclusion matching,
+post-render ordering, or output paths.
+
+## QA and content readiness
+
+Run `npm exec -- book-scaffold qa` after substantive content changes. It calls
+the same content-contract library as `validate`, then reports stable chapter,
+link, learning-objective, component, and JSON-fixture facts. Human output is
+the default. For CI use `npm --offline exec -- book-scaffold qa --format json`;
+JSON stdout contains only the schema-v1 result, while progress/fatal details go
+to stderr. Exit `0` means no blocking failure, `1` means a red selected/shared
+result, and `2` means the invocation or execution failed.
+
+In a corpus, omission checks every manifest book in order; `--book <id>` checks
+one and `--all` states the default explicitly. Schema v1 always includes a
+top-level `shared: { verdict, checks, diagnostics }` aggregate for corpus-wide
+fixture data. Its exact single-book value is
+`{ "verdict": "not_applicable", "checks": {}, "diagnostics": [] }`.
+
+Run `npm exec -- book-scaffold init-qa` only when a portfolio QA engine needs
+`guide_qa.yaml`. It emits one deterministic offline command per manifest book,
+or one implicit `book` entry without `--book`. It preserves an existing file;
+`--force` replaces that whole file and no other path. See Recipe 25.
+
 ## Validation
 
 `npm run validate` (also runs in prebuild) catches:

package/README.md

@@ -49,12 +49,67 @@ local `<BookLink>` targets, and Pagefind results remain book-scoped. See
 [Recipe 21](./recipes/21-multi-guide-single-app.md) for content layout, route
 ownership, `--book` tooling, shared sources, and migration.
 
+## Content readiness and CLI
+
+`book-scaffold qa` combines the existing validation contract with stable
+chapter, link, learning-objective, component, and JSON-fixture metrics. Human
+output is the default; schema-v1 JSON is deterministic and keeps stdout clean
+for CI:
+
+```bash
+npm exec -- book-scaffold qa
+npm --offline exec -- book-scaffold qa --format json
+npm exec -- book-scaffold init-qa
+```
+
+In corpus mode `qa` checks every manifest book by default, while `--book <id>`
+selects one exact id. `init-qa` creates the portfolio-engine interoperability
+file `guide_qa.yaml`; its generated checks use `npm --offline exec` and an
+existing file is preserved unless `--force` is explicit. See
+[Recipe 25](./recipes/25-qa-readiness.md) for verdicts, exit codes, the
+top-level `shared` aggregate, and CI wiring.
+
+The installed `book-scaffold` dispatcher owns these commands:
+
+| Command | Purpose |
+|---|---|
+| `validate` | Pre-flight authored content, references, figures, and links |
+| `qa` | Emit a human or schema-v1 readiness verdict |
+| `init-qa` | Generate deterministic `guide_qa.yaml` interoperability config |
+| `build-labels` | Build cross-reference and heading indexes |
+| `build-bib` | Build bibliography and source-manifest data |
+| `build-tips` | Build the tips index |
+| `build-exercises` | Build the exercises index |
+| `build-figures` | Convert and theme application-wide figure assets |
+| `render-notebooks` | Render application-wide notebook companions |
+
 Astro builds emit a Cloudflare-compatible `dist/_headers` with audited
 security defaults. A consumer-owned `public/_headers` wins unchanged;
 `defineBookConfig({ securityHeaders: false })` disables scaffold emission,
 and `securityHeaders.contentSecurityPolicy` replaces only the default CSP.
 See [Recipe 05](./recipes/05-deploy-cloudflare.md#default-security-headers).
 
+## Build-time Open Graph cards
+
+Social cards are an explicit, offline build feature:
+
+```ts
+seo: {
+  ogCards: true,
+  // or: { enabled: true, exclude: ['/print/', '/private/*/', '/archive/**'] }
+}
+```
+
+Eligible static pages without a page image, corpus-book manifest image, or
+static `seo.ogImage` receive a deterministic 1200×630 PNG at a
+content-addressed `_og/<hash>.png` URL. Exact exclusions, one-segment `*`, and
+cross-segment `**` are matched after Astro-base normalization. Package-owned
+local fonts keep generation network-free; corpus identity and `site`/`base`
+are applied exactly once. Requested-card failures fail the build instead of
+emitting broken metadata. See
+[Recipe 26](./recipes/26-generated-og-cards.md) for precedence, exclusion
+grammar, output, and verification.
+
 ## Interactive demos
 
 The opt-in `@brandon_m_behring/book-scaffold-astro/demo` entry exports

package/assets/og-fonts/LICENSE.txt

@@ -0,0 +1,89 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The fonts,
+including any derivative works, can be bundled, embedded, redistributed
+and/or sold with any software provided that any reserved names are not used
+by derivative works. The fonts and derivatives, however, cannot be released
+under any other type of license. The requirement for fonts to remain under
+this license does not apply to any document created using the fonts or their
+derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may include
+source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting, or
+substituting -- in part or in whole -- any of the components of the Original
+Version, by changing formats or by porting the Font Software to a new
+environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer or
+other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the Font Software, to use, study, copy, merge, embed, modify, redistribute,
+and sell modified and unmodified copies of the Font Software, subject to the
+following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy contains
+the above copyright notice and this license. These can be included either as
+stand-alone text files, human-readable headers or in the appropriate
+machine-readable metadata fields within text or binary files as long as
+those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font Name(s)
+unless explicit written permission is granted by the corresponding Copyright
+Holder. This restriction only applies to the primary font name as presented
+to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any Modified
+Version, except to acknowledge the contribution(s) of the Copyright Holder(s)
+and the Author(s) or with their explicit written permission.
+
+5) The Font Software, modified or unmodified, in part or in whole, must be
+distributed entirely under this license, and must not be distributed under
+any other license. The requirement for fonts to remain under this license
+does not apply to any document created using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are not
+met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
+INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/og-fonts/SOURCE.md

@@ -0,0 +1,13 @@
+# Inter font provenance
+
+The renderer vendors the unmodified static TTF files from the official Inter
+4.1 release. Builds never download a font or read a system font.
+
+- Release: <https://github.com/rsms/inter/releases/tag/v4.1>
+- Archive: <https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip>
+- Archive SHA-256: `9883fdd4a49d4fb66bd8177ba6625ef9a64aa45899767dde3d36aa425756b11e`
+- `extras/ttf/Inter-Regular.ttf` SHA-256: `40d692fce188e4471e2b3cba937be967878f631ad3ebbbdcd587687c7ebe0c82`
+- `extras/ttf/Inter-Bold.ttf` SHA-256: `288316099b1e0a47a4716d159098005eef7c0066921f34e3200393dbdb01947f`
+
+The adjacent `LICENSE.txt` is copied verbatim from that release (SIL Open Font
+License 1.1).

package/bin/book-scaffold.mjs

@@ -14,6 +14,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const handlers = {
   validate: '../scripts/validate.mjs',
+  qa: '../scripts/qa.mjs',
+  'init-qa': '../scripts/init-qa.mjs',
   'build-labels': '../scripts/build-labels.mjs',
   'build-bib': '../scripts/build-bib.mjs',
   'build-figures': '../scripts/build-figures.mjs',
@@ -26,6 +28,8 @@ const HELP = `Usage: book-scaffold <sub-command> [args...]
 
 Sub-commands:
   validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
+  qa                 Content-health and readiness report (human or schema-v1 JSON).
+  init-qa            Generate deterministic guide_qa.yaml interoperability config.
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
   build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
-import { c as BookConfigOptions, h as BookScaffoldIntegrationOptions, d as BookCorpus, l as CorpusApparatusRoute, e as BookCorpusInput, m as CorpusBook, k as ChaptersRenderer, v as SiblingBooks, x as Style } from './types-D1QZgKMO.js';
-export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, f as BookPreset, g as BookProfile, i as BookSchemasOptions, C as CORPUS_APPARATUS_ROUTES, j as ChapterFor, n as CorpusBookInput, F as FreshnessAffordance, o as FrontmatterRouteConfig, N as NUMBER_STYLES, p as NumberStyle, P as PartKey, q as PartialRouteToggles, r as ProfileDefinition, R as ReleaseStatusConfig, s as RouteToggles, S as SecurityHeadersConfig, t as SiblingBookDescriptor, u as SiblingBookEntry, w as StatusBadge, y as StyleInput, V as VolatilityBadge, z as composeStyles, A as defineProfile, D as defineStyle, E as normalizeFrontmatterConfig, G as resolvePreset, H as resolveProfile } from './types-D1QZgKMO.js';
+import { c as BookConfigOptions, h as BookScaffoldIntegrationOptions, d as BookCorpus, l as CorpusApparatusRoute, e as BookCorpusInput, m as CorpusBook, k as ChaptersRenderer, v as SiblingBooks, x as Style } from './types-DjqMnwHw.js';
+export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, f as BookPreset, g as BookProfile, i as BookSchemasOptions, C as CORPUS_APPARATUS_ROUTES, j as ChapterFor, n as CorpusBookInput, F as FreshnessAffordance, o as FrontmatterRouteConfig, N as NUMBER_STYLES, p as NumberStyle, O as OgCardsConfig, P as PartKey, q as PartialRouteToggles, r as ProfileDefinition, R as ReleaseStatusConfig, s as RouteToggles, S as SecurityHeadersConfig, t as SiblingBookDescriptor, u as SiblingBookEntry, w as StatusBadge, y as StyleInput, V as VolatilityBadge, z as composeStyles, A as defineProfile, D as defineStyle, E as normalizeFrontmatterConfig, G as resolvePreset, H as resolveProfile } from './types-DjqMnwHw.js';
 import { E as volatilityLevels, c as academicParts, Q as Question } from './schemas-CKipJ5Ie.js';
 export { A as AcademicChapter, B as BloomLevel, C as CourseNotesChapter, G as GlossaryTerm, M as MinimalChapter, P as Provenance, a as QuestionType, R as ResearchPortfolioChapter, T as ToolsChapter, b as academicChapterSchema, d as bloomLevels, e as changeKinds, f as changelogSchema, g as chapterStatus, h as citationBackstops, i as courseNotesChapterSchema, j as glossarySchema, l as layoutModes, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, n as provenanceObject, o as provenanceSchema, q as questionDifficulties, r as questionSchema, s as questionTypes, t as refineQuestion, u as refinedQuestionSchema, v as researchPortfolioChapterSchema, w as sourceTiers, x as sourceTiersResearch, y as sourcesSchema, z as toolSlugs, D as toolsChapterSchema } from './schemas-CKipJ5Ie.js';
 export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';