Add comprehensive documentation and catalog reference validation#5
Merged
Conversation
- Add docs/how-opf-works.md, a conceptual introduction covering the document model, the three content shapes, layouts-as-hints, narrative beats, catalog resolution order, and the validation philosophy. - Add docs/design-resolution.md, stating the design precedence chain (slide design -> deck design -> resolved theme -> engine defaults) as an explicit algorithm with worked examples. - Add a warnings array to ValidationResult. The validator now warns, never errors, on unknown bare catalog ids (narrative, design.theme, design.colorScheme, design.fontScheme, chart type) and on broken recommendedNarratives/recommendedTones cross-links in audience, purpose, and tone records. Inline catalogs.<kind>.records and custom catalogs.<kind>.source exempt a document from these checks. - Generate a lightweight src/generated/catalog-ids.ts so the validator checks ids without bundling full catalog records. - Fix four broken catalog cross-links surfaced by the new check: engineering-update -> status-update, all-hands -> focus. - Enforce zero warnings for bundled examples and catalog cross-links in the smoke test. - Add spec/README.md orienting readers to the spec directory, including what the optional openapi.yaml reference contract is for. - Serve .md spec files with a text/markdown media type. https://claude.ai/code/session_01NBXPAPfAVXS9R83Nny7Qpg
- Expand docs/how-opf-works.md with a document-anatomy diagram, the 3x3 region-grid diagram, a catalog-resolution flow diagram, runnable examples for every content shape, a narrative-beats example, an inline-catalog example, and a complete small QBR deck. - Add precedence-stack and base-plus-overrides diagrams to docs/design-resolution.md, using the real cool-horizon slot values. - Add the region-grid cheat sheet to docs/content-payloads.md. - Add examples/technical/full-feature-tour.opf.json: one fixture exercising every major schema surface (intent metadata, organizations and speakers, narrative beat overrides, design with slide overrides, assets, inline catalog records, all ten content payload kinds, blocks, regions, hidden slides, extensions). Referenced from the examples guides. - Expand spec/README.md with consumption snippets (package imports, raw file addressing, any-language validation) and a stability note. - Document the validator warnings channel in both READMEs. - Smoke test now validates every presentation-shaped JSON example embedded in the shipped docs, so doc examples cannot drift from the schema. https://claude.ai/code/session_01NBXPAPfAVXS9R83Nny7Qpg
- Extrapolate the region grid into span-composition diagrams (sidebar + main, headline band + body, and their combination) in docs/how-opf-works.md and docs/content-payloads.md, each tied to the JSON that produces it. - Add a 'Start in three steps' section to the README: install, author and validate a deck, build on the catalogs and roadmap. - Frame the how-opf-works intro and closing around the author: you own the story, the format keeps it diffable; commit a deck and read the diff. - Promote the misplaced 'Expected Usage' heading out of the Toolkit roadmap section to a top-level 'Usage' section. - Add a root llms.txt index pointing agents at the docs, schemas, catalogs, and the full-feature example with a one-paragraph authoring rule of thumb. https://claude.ai/code/session_01NBXPAPfAVXS9R83Nny7Qpg
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds extensive documentation for the OPF format and implements catalog reference validation with warnings. It introduces three new documentation files explaining how OPF works, how design resolution works, and provides a complete technical example. The validator now checks catalog references (narratives, themes, color schemes, font schemes, chart types) and emits warnings for unknown IDs while maintaining the principle that unknown references never cause validation to fail.
Key Changes
Documentation
docs/how-opf-works.md: Comprehensive conceptual guide covering the document model, three content shapes (root payload, blocks, regions), layouts as hints, narrative beats, catalog resolution, and validation philosophydocs/design-resolution.md: Explicit algorithm for design precedence across slide, deck, theme, and engine defaults with worked examplesspec/README.md: Guide to the spec directory structure and how to consume canonical schemas and catalogsexamples/technical/full-feature-tour.opf.json: Complete technical fixture exercising all major schema surfacesdocs/content-payloads.mdwith detailed region key documentation and visual grid examplesdocs/examples.mdandexamples/technical/README.mdto reference the new full-feature tourllms.txt: Quick reference for LLM contextValidator Enhancements
ValidationResultinterface to includewarningsarray (separate fromerrors)presentationReferenceWarnings()to check catalog references in presentations:catalogCrossLinkWarnings()to validate cross-references within catalog records (e.g., audience'srecommendedNarrativesfield)unknownIdWarning()helper that checks against bundled catalog IDs and respects inline/custom sourcesCode Generation
generateCatalogIds()function to generate lightweight id-only view of bundled catalogs for validator usemediaTypeForSpecFile()to handle.mdfiles astext/markdownCatalog Corrections
spec/catalogs/audiences/engineering-team.json: changedengineering-updatetostatus-updateinrecommendedNarrativesspec/catalogs/tones/casual.json: changedall-handstofocusinrecommendedNarrativesspec/catalogs/tones/conversational.json: changedall-handstofocusinrecommendedNarrativesspec/catalogs/tones/technical.json: changedengineering-updatetostatus-updateinrecommendedNarrativesTests
Notable Implementation Details
validis never affected by unknown catalog IDscatalogs.<kind>.records[]andcatalogs.<kind>.sourcedeclarations, treating them as legitimate sources for ids{ "id": "my-custom-narrative", ... }) are treated as fully custom inline definitions, not broken referenceshttps://claude.ai/code/session_01NBXPAPfAVXS9R83Nny7Qpg