@openpresentation/opf 0.2.2 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Data-Advantage
+Copyright (c) 2026 OpenPresentation contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,9 +2,9 @@
 
 Canonical Open Presentation Format package for JavaScript and TypeScript.
 
-Publishes the OPF schemas, catalog presets, raw spec files, generated TypeScript types, and local validation helpers. The schema is pre-stable (0.x — expect breaking changes between minor versions until 1.0). This package does not render PowerPoint files, parse `.pptx`, fetch remote catalogs, or use AI.
+Publishes the OPF schemas, catalog presets, raw spec files, generated TypeScript types, examples, docs, and local validation helpers. The schema is pre-stable (0.x — expect breaking changes between minor versions until 1.0). This package does not render PowerPoint files, parse `.pptx`, fetch remote catalogs, call hosted APIs, provide telemetry, or use AI.
 
-The canonical npm package remains `@openpresentation/opf`; a separate `@openpresentation/opf-spec` package is not used for v0.2.0 so existing downstream imports stay stable. The packed npm artifact includes package-addressable OPF schemas, catalogs, reference files, and `openapi.yaml` under `spec/`.
+The canonical npm package remains `@openpresentation/opf`; a separate `@openpresentation/opf-spec` package is not used for v0.2.0 so existing downstream imports stay stable. The packed npm artifact includes package-addressable OPF schemas, catalogs, reference files, and an optional downstream-service reference `openapi.yaml` under `spec/`.
 
 Repository: https://github.com/OpenPresentation/opf
 
@@ -67,6 +67,8 @@ import {
 import type { Presentation, Audience, Tone } from "@openpresentation/opf/types";
 ```
 
+The root entry exports every schema, catalog, and validation helper for convenience. Prefer the focused subpaths above when a package consumer only needs one surface, so the root bundle's full catalog/schema payload is not loaded unnecessarily.
+
 ### Layout previews
 
 `@openpresentation/opf/previews` ships pre-rendered HTML thumbnails for the
@@ -93,6 +95,75 @@ export function LayoutThumbnail({ slug }: { slug: string }) {
 Raw HTML source-of-truth lives under `spec/previews/layouts/<slug>.html` and is
 also addressable via `@openpresentation/opf/spec/previews/layouts/<slug>.html`.
 
+### Example decks
+
+`@openpresentation/opf/examples` ships every `.opf.json` file from `examples/`
+in the upstream repo, already parsed and validated against the presentation
+schema at build time.
+
+```ts
+import {
+  examples,
+  galleries,
+  getExample,
+  getExamplesByGallery,
+} from "@openpresentation/opf/examples";
+
+const compliance = getExample("compliance-readiness-review");
+const businessDecks = getExamplesByGallery("business-functions");
+
+console.log(`${examples.length} example decks across ${galleries.length} galleries`);
+```
+
+Each `ExampleRecord` includes the parsed `Presentation` object plus its
+repo-relative path, top-level category (`gallery`, `technical`, …), and
+gallery slug when applicable.
+
+### Documentation pages
+
+`@openpresentation/opf/docs` ships the top-level `docs/*.md` reference pages
+(`schema-reference`, `catalog-schema-reference`, `content-payloads`,
+`content-item-design-overrides`, `examples`). Subdirectories like
+`docs/migrations` and `docs/plans` are intentionally excluded — those move too
+quickly to ship inside a pinned npm release.
+
+```ts
+import { docs, getDoc } from "@openpresentation/opf/docs";
+
+for (const doc of docs) {
+  console.log(`${doc.title} — ${doc.file}`);
+}
+
+const schemaRef = getDoc("schema-reference");
+console.log(schemaRef?.markdown.slice(0, 200));
+```
+
+### Upstream README
+
+`@openpresentation/opf/repo-readme` exposes the raw markdown of the upstream
+`OpenPresentation/opf` README.md at the version pinned by this release. Use it
+when you want to mirror the canonical README inside another site or app
+without doing a network fetch.
+
+```ts
+import { repoReadme } from "@openpresentation/opf/repo-readme";
+
+console.log(repoReadme.split("\n").slice(0, 3).join("\n"));
+```
+
+Validation results carry `errors` (structural problems that make `valid`
+false) and `warnings` (advisory issues such as unknown catalog ids in
+`narrative`, `design`, or chart `type` references — these never affect
+`valid`). Documents that declare matching inline `catalogs.<kind>.records[]`
+or a custom `catalogs.<kind>.source` are exempt from unknown-id warnings for
+that kind.
+
+```ts
+const result = validatePresentation(deck);
+if (!result.valid) console.error(result.errors);
+for (const warning of result.warnings) console.warn(warning.path, warning.message);
+```
+
 Validate catalog records locally:
 
 ```ts
@@ -114,7 +185,7 @@ import presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.js
 };
 ```
 
-The raw spec manifest exposes typed package paths for files that should be resolved from npm instead of GitHub:
+The raw spec manifest exposes typed package paths for files that should be resolved from npm instead of GitHub. `openapi.yaml` is a reference contract for downstream services that choose to expose OPF over HTTP; OpenPresentation does not host that API.
 
 ```ts
 import { specFileEntries } from "@openpresentation/opf/spec-files";