slotdeck 0.1.0 → 0.1.2

package/docs/deck-format.md

@@ -0,0 +1,225 @@
+# Deck format
+
+A deck is a JSON object of type `DeckSpec`. It describes one presentation and contains no binary data.
+
+```ts
+import type { DeckSpec, SlideSpec, SlotValue, ImageRef, TableValue, ChartValue } from 'slotdeck';
+```
+
+## Complete example
+
+```json
+{
+  "version": 1,
+  "title": "A year of Riverbend Bike Share",
+  "language": "en",
+  "direction": "ltr",
+  "fields": { "organizationDepartment": "Riverbend Bike Share  |  Season review" },
+  "slides": [
+    {
+      "pattern": "cover",
+      "slots": { "title": "A year of Riverbend Bike Share", "subtitle": "What the 2025 season taught us" }
+    },
+    {
+      "pattern": "text-and-photo",
+      "slots": {
+        "title": "Bikes became part of the daily commute",
+        "body": ["Most rides used to be weekend outings.", "This year the busiest hour is eight on a weekday morning."],
+        "photo": { "asset": "photo-commute", "alt": "A commuter on a river path" }
+      }
+    },
+    {
+      "pattern": "icon-cards",
+      "items": 3,
+      "slots": {
+        "title": "Three changes for next season",
+        "card1Icon": { "asset": "clock" },
+        "card1Heading": "Longer hours",
+        "card1Text": "Bikes unlock from five in the morning.",
+        "card2Icon": { "asset": "shield" },
+        "card2Heading": "Safer docks",
+        "card2Text": "Every station gets lighting and a camera.",
+        "card3Icon": { "asset": "people" },
+        "card3Heading": "Group passes",
+        "card3Text": "One pass for up to five riders."
+      }
+    },
+    {
+      "pattern": "table",
+      "slots": {
+        "title": "The busiest stations",
+        "table": {
+          "header": ["Station", "Docks", "Rides a day"],
+          "rows": [["Tram Square", "24", "410"], ["River Gate", "18", "365"]]
+        }
+      }
+    },
+    {
+      "pattern": "chart-native",
+      "slots": {
+        "title": "Rides grew through the summer",
+        "chart": {
+          "type": "column",
+          "categories": ["Apr-May", "Jun-Jul", "Aug-Sep"],
+          "series": [
+            { "name": "2024", "values": [5, 9, 11] },
+            { "name": "2025", "values": [7, 15, 19] }
+          ]
+        },
+        "chartDescription": "Rides in thousands for each part of the season."
+      }
+    },
+    { "pattern": "closing", "slots": { "title": "Thank you" } }
+  ]
+}
+```
+
+The pattern ids and slot names in this example come from the demo template's manifest. Yours come from your own
+manifest.
+
+## `DeckSpec`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `version` | `1` | yes | Always the number 1. |
+| `slides` | `SlideSpec[]` | yes | The slides in order. Must not be empty. |
+| `title` | string | no | A name for the deck. Not placed on any slide by itself. |
+| `brief` | string | no | The request the deck was written from. `editDeck` uses it as background. |
+| `language` | string | no | BCP 47 tag of the deck's text, such as `en` or `he`. |
+| `direction` | `"ltr"` or `"rtl"` | no | Reading direction. Defaults to the template's. See [languages.md](languages.md). |
+| `fields` | object of strings | no | Values shared by every slide, by field name. See "Deck fields" below. |
+| `textScale` | number | no | Size of body text as a factor on the template's: `1` as designed, `1.25` large, `1.5` extra large. See [layout-freedom.md](layout-freedom.md). |
+
+## `SlideSpec`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `pattern` | string | yes | The `id` of a pattern in the manifest. |
+| `slots` | object | yes | Slot name to value. |
+| `items` | integer | no | Only for a pattern with a row or grid of items: how many items this slide has. Defaults to the number drawn on the template slide. Must be within the pattern's range. |
+
+## Slot values
+
+The value depends on the slot's kind in the manifest.
+
+### Text slot
+
+A string, or an array of strings with one entry per paragraph.
+
+```json
+"title": "Deliveries are faster"
+"body": ["First paragraph.", "Second paragraph."]
+"body": "First paragraph.\nSecond paragraph."
+```
+
+- A newline inside a string starts a new paragraph, so the last two lines above mean the same.
+- Empty paragraphs are dropped.
+- Each paragraph takes its formatting (font, size, colour, bullet) from the template paragraph in the same
+  position. When there are more paragraphs than the template slot has, the last template paragraph's formatting
+  is reused. This is how a bulleted list works: the template shape has bulleted paragraphs, and the deck gives
+  one string per bullet.
+- Do not put bullet characters, numbering or Markdown in the text. The text is used literally.
+- Limits: `maxChars` counts all characters of all paragraphs together; `maxParagraphs` counts paragraphs. Both
+  are soft (a warning, not an error).
+
+### Image slot
+
+An `ImageRef`:
+
+```json
+"photo": { "asset": "photo-commute", "alt": "A commuter on a river path" }
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `asset` | string | yes | The id of the picture. The bytes are passed to `renderDeck` in `options.assets` under this id. |
+| `alt` | string | no | Alternative text for screen readers, stored on the picture. |
+| `prompt` | string | no | A description the picture can be generated from. Written by the planner for photos; lets the picture be made again later. |
+
+How the picture is placed depends on the slot (`fit` in the manifest):
+
+- `cover` (the default for photos): the picture fills the frame and is cropped at the edges, keeping its
+  proportions. The frame's shape (rounded corners, a circle) is kept.
+- `contain` (the default for icons and graphics): the whole picture is shown, centred, inside the frame's
+  area, keeping its proportions.
+
+Supported formats are PNG, JPEG and GIF.
+
+### Table slot
+
+A `TableValue`:
+
+```json
+"table": { "header": ["Station", "Docks"], "rows": [["Tram Square", "24"], ["River Gate", "18"]] }
+```
+
+- `header` sets the number of columns. Every row must have exactly that many cells, or the deck is invalid.
+- Cells are strings. Numbers must be written as strings (`"24"`).
+- The template table's first row supplies the header style and its following rows supply the body styles in
+  turn (so banding is kept). Columns share the table's width equally.
+- Limits (`maxColumns`, `maxRows`, `maxCellChars`) are soft.
+
+### Chart slot
+
+A `ChartValue`, which becomes a native PowerPoint chart that can be changed with Edit Data:
+
+```json
+"chart": {
+  "type": "column",
+  "categories": ["Q1", "Q2", "Q3"],
+  "series": [{ "name": "Revenue", "values": [12, 15, 19] }],
+  "format": "number"
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `type` | `"column"`, `"bar"`, `"line"` or `"pie"` | yes | `column` has vertical bars, `bar` horizontal ones. |
+| `categories` | string[] | yes | Labels along the axis, or the names of the pie slices. At least one. |
+| `series` | `{ name, values }[]` | yes | At least one. Each `values` array must have exactly one number per category. A pie takes exactly one series. |
+| `format` | `"number"` or `"percent"` | no | `percent` shows values with a percent sign (45 is shown as 45%). Any other value is ignored with a warning. |
+
+Bars start at zero. Colours and fonts come from the manifest.
+
+### Leaving a slot out
+
+- Omit the slot, or give an empty string: the slot has no value, and its `empty` policy decides what happens
+  (see [concepts.md](concepts.md)).
+- Give `null`: the slot is explicitly left out and its shape is removed. This needs `layout: 'adaptive'` and a
+  slot that is not required.
+
+A name in `slots` that the pattern does not have is ignored with a warning.
+
+## Deck fields
+
+A text slot whose manifest entry has `"deckField": "x"` takes its value from `deck.fields.x` when the slide does
+not give that slot a value itself. Use it for text that repeats on every slide.
+
+```json
+{ "fields": { "organizationDepartment": "Acme  |  Operations" }, "slides": [ ... ] }
+```
+
+If a required slot depends on a field that the deck does not give, validation reports `this slot is required`
+for that slot on every slide that has it.
+
+## Items of a row or grid
+
+For a pattern with a row or grid of items, `items` says how many. The slots of each item are numbered:
+`card1Heading`, `card2Heading`, and so on. With `"items": 3`, give slots for items 1 to 3 only. With more items
+than the template slide draws, the extra items are copies of the last one and have the next numbers
+(`card5Heading`, ...).
+
+The first item is the first in the deck's reading direction. In a right-to-left deck on a left-to-right
+template, `card1...` appears at the right.
+
+## Checking a deck
+
+```ts
+import { validateDeck } from 'slotdeck';
+
+const issues = validateDeck(manifest, deck, { layout: 'adaptive', assets: ['photo-commute', 'clock'] });
+// [{ severity: 'error' | 'warning', slide?: number, slot?: string, message: string }]
+```
+
+Errors make `renderDeck` throw. Warnings do not. Every message is listed in
+[troubleshooting.md](troubleshooting.md).

package/docs/generating.md

@@ -0,0 +1,254 @@
+# Generating and editing decks with a model
+
+The planner turns a brief into deck JSON by asking a language model you provide. The model never produces a
+file and never positions anything: it chooses patterns from the manifest and writes text for their slots, inside
+a JSON schema built from the manifest.
+
+```ts
+import { generateDeck, editDeck, planDeck, planOutline, editPlan, writeDeck, planEdit, resolveAssets, PlanError, DeckValidationError } from 'slotdeck';
+import type { Brief, PlanOptions, GenerateOptions, IconDef, AssetDef } from 'slotdeck';
+```
+
+All functions on this page need an `LlmProvider` (see [providers.md](providers.md)).
+
+## `generateDeck(template, brief, options)`: brief in, pptx out
+
+```ts
+const result = await generateDeck(template, brief, options);
+// result.pptx      Uint8Array   the file
+// result.deck      DeckSpec     store this: it is what gets edited and rendered again
+// result.assets    Record<string, Uint8Array>   every picture the deck uses, by asset id
+// result.warnings  Issue[]      limits the final draft still exceeds
+// result.outline   OutlineEntry[]   [{ pattern, purpose, items? }] for each slide
+```
+
+It runs `planDeck`, then `resolveAssets`, then `renderDeck`.
+
+### `Brief`
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `prompt` | string | required | What the deck is about, in the person's own words. Include every fact, figure and name that should appear: the model is told to use only what is stated. |
+| `slideCount` | number, or `{ min, max }` | 6 to 10 | A fixed number of slides, or a range. |
+| `language` | string | the template's | BCP 47 tag of the language to write in. |
+| `direction` | `"ltr"` or `"rtl"` | the language's | Reading direction. |
+| `imageDensity` | `"none"`, `"low"`, `"medium"`, `"high"` | `medium` | How many slides carry a photo: none, at most a quarter, about half, or wherever it suits. Forced to `none` by `generateDeck` when no image source and no supplied photos were given. |
+| `instructions` | string | none | Anything else to respect: audience, tone, points that must be covered. |
+| `fields` | object of strings | none | Deck-level values the template needs (see "Deck fields" in [deck-format.md](deck-format.md)). A pattern that needs a field that is not given is not offered. |
+| `textSize` | `"normal"`, `"large"`, `"x-large"` | `normal` | Size of body text. Larger text gets smaller budgets, so less is written. |
+| `textOnly` | boolean | `false` | Plan every slide as plain text. Only the template's plain text patterns are offered. See "Asking for a kind of slide" below. |
+
+### Options (`GenerateOptions`)
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `llm` | `LlmProvider` | required | The text model. |
+| `images` | `ImageProvider` | none | Makes photos from descriptions. Without it, decks are planned with no generated photos. |
+| `icons` | `IconDef[]` | none | Your icon set: `{ id, description, data }`. Patterns with icon slots are offered only when this is given. The model picks icons by `description`, so describe what each shows and what it stands for ("a clock: time, schedule"). |
+| `assets` | `AssetDef[]` | none | Pictures you already have: `{ id, kind: 'photo' | 'graphic', description, data }`. The model decides where each fits from its description. |
+| `layout` | `"strict"` or `"adaptive"` | `strict` | Whether optional slots may be left out. |
+| `patterns` | string[] | all | Restrict the deck to these pattern ids. |
+| `numberPatterns` | `"from-brief"`, `"always"`, `"never"` | `from-brief` | When patterns marked `figures` may be used. `from-brief` offers them only if the brief contains digits. |
+| `maxRepairs` | number | 2 | How many times a draft that breaks the template's limits is sent back to the model. |
+| `cache` | `Map<string, Uint8Array>` | none | Generated pictures by asset id. Pass the same map on later calls and pictures whose description did not change are reused. |
+| `imageConcurrency` | number | 3 | How many pictures to generate at once. |
+| `onProgress` | function | none | Called with `{ stage: 'outline' }`, `{ stage: 'write', slides }`, `{ stage: 'repair', attempt, issues }`, `{ stage: 'images', done, total }`, `{ stage: 'render' }`. |
+| `signal` | `AbortSignal` | none | Cancels the work. |
+
+### Example
+
+```ts
+const { pptx, deck, warnings } = await generateDeck(
+  template,
+  {
+    prompt: 'A deck for new adopters: why adopt a rescue dog, the first month at home, what it costs. We rehomed 286 dogs in 2023, 351 in 2024 and 412 in 2025.',
+    language: 'en',
+    slideCount: 9,
+    imageDensity: 'medium',
+    fields: { organizationDepartment: 'Harbor Street Shelter  |  Adoption team' },
+  },
+  {
+    llm,
+    images,
+    icons: [
+      { id: 'clock', description: 'a clock: time, schedule, duration', data: clockPng },
+      { id: 'heart', description: 'a heart: care, health, loyalty', data: heartPng },
+    ],
+    assets: [{ id: 'flow', kind: 'graphic', description: 'diagram of the adoption process in four steps', data: flowPng }],
+    layout: 'adaptive',
+    onProgress: (event) => console.log(event.stage),
+  },
+);
+```
+
+## How planning works
+
+1. **Outline** (one model call). The model sees every usable pattern with its description and slot limits, and
+   answers with one pattern per slide and the point each slide makes.
+2. **Write** (one model call). The model fills a JSON schema built for exactly that sequence of slides, so it
+   cannot invent patterns or slots.
+3. **Repair** (up to `maxRepairs` more calls). The draft is validated against the manifest. Errors and
+   over-budget text go back to the model with the list of problems.
+
+Which patterns are offered depends on what you supplied:
+
+| A pattern with | Is offered only when |
+| --- | --- |
+| a required photo slot | `imageDensity` is not `none`. `generateDeck` and the chat tools set it to `none` when there is no image source and no supplied photo. If you call `planDeck` yourself without a way to make photos, set `imageDensity: 'none'`. |
+| a required icon slot | `icons` is given |
+| a required graphic slot | `assets` has a picture of kind `graphic` |
+| a required deck field | `brief.fields` has it |
+| `figures: true` | the brief contains digits (or `numberPatterns: 'always'`) |
+
+"Required" follows the layout: in `strict` layout an optional slot (`empty: "remove"`) counts as required,
+because nothing may be removed from a slide. Slots with `empty` of `keep` or `drop` are never shown to the
+model.
+
+If nothing can be offered, `PlanError` is thrown with the reasons.
+
+### Asking for a kind of slide
+
+By default the planner varies the patterns across a deck. A wish about the kind of slides overrides that, and
+there are two ways to state one.
+
+**In words.** A wish in `prompt` or `instructions`, such as "text only", "no tables" or "only cards", decides
+which patterns may be used and comes before variety. The planner is told so, and the pattern list it reads marks
+each plain text pattern with the words "Plain text.".
+
+**As a flag.** `textOnly: true` is the reliable way to get a deck of text and nothing else. The planner is then
+offered only the plain text patterns, so no other kind can be chosen, and it is told that using the same pattern
+for several slides in a row is expected.
+
+```ts
+await generateDeck(template, { prompt: 'Our move to hybrid work: why, the rules, what changed', textOnly: true }, { llm });
+// for example: cover, text-only, text-only, text-only, text-only, closing
+```
+
+A pattern counts as **plain text** when a slide made from it holds running text and nothing else: all its
+slots are text (a picture that the pattern always drops does not count), it has no row or grid of items, and it
+is not marked `figures`. A cover, a closing slide, a quotation and a title-with-paragraphs slide are plain text;
+cards, tables, charts and anything with a picture or icon are not.
+
+Two things to know:
+
+- "No pictures" is a different wish. `imageDensity: 'none'` removes photos but still allows cards, tables and
+  charts.
+- A text-only deck is only as varied as the template's plain text patterns. A template without one cannot make
+  such a deck: `PlanError: Template "x" has no plain text pattern, so a text-only deck cannot be planned from it`.
+  Add one as a derived pattern (see [layout-freedom.md](layout-freedom.md)).
+
+### Why numbers are guarded
+
+A model given a slide built around a statistic and no data tends to invent one. So patterns marked `figures` are
+held back unless the brief itself contains figures, and chart values that the brief does not state come back as
+warnings such as `chart values not stated in the brief: 89`. Values worked out from the brief, such as a sum, are
+flagged too; treat the warning as a prompt to check.
+
+Contact details and names are not guarded. A model asked for a closing slide may invent an email address. State
+such details in the brief, or review the deck.
+
+## The steps on their own
+
+Use these when a person should see and approve a plan before the content is written.
+
+```ts
+// 1. Decide the slides. One call, quick, small result: the thing to show a person.
+const plan = await planOutline(template, brief, { llm, icons, layout: 'adaptive' });
+// plan = { version: 1, title, brief, slides: [{ pattern, purpose, items? }] }
+
+// 2. Change the plan by instruction. One call. Returns a new plan and one sentence on what changed.
+const { plan: revised, summary } = await editPlan(template, plan, 'Add a slide about pricing before the end', { llm, icons, layout: 'adaptive' });
+
+// 3. Write the content. One call plus repairs.
+const { deck, warnings, outline } = await writeDeck(template, revised, { llm, icons, layout: 'adaptive' });
+
+// 4. Pictures and file.
+const assets = await resolveAssets(template, deck, { images, icons, assets: supplied });
+const { pptx } = renderDeck(template, deck, { assets, layout: 'adaptive' });
+```
+
+`planDeck(template, brief, options)` is steps 1 and 3 in one call and returns `{ deck, warnings, outline }`.
+
+Pass the same `icons`, `assets` and `layout` to every step: the plan was made on the assumption that they are
+available.
+
+### `resolveAssets(template, deck, options?)`
+
+Collects the bytes of every picture a deck refers to: supplied icons and assets as they are, described pictures
+from `cache` or from `images`. Returns a map from asset id to bytes, ready for `renderDeck`.
+
+| Option | Meaning |
+| --- | --- |
+| `images` | The `ImageProvider` that makes described pictures. |
+| `icons`, `assets` | The same sets the deck was planned with. |
+| `cache` | A `Map` of pictures already made. New ones are added to it. |
+| `concurrency` | How many to generate at once (default 3). |
+| `onProgress`, `signal` | As above. |
+
+The image provider is asked for a picture with the aspect ratio of the frame it goes into.
+
+## Editing a deck
+
+```ts
+const edited = await editDeck(template, deck, 'Shorten slide 3 to two bullets and translate the deck to Hebrew', {
+  llm,
+  images,
+  icons,
+  assets,
+  cache, // pictures of the earlier version; see extractAssets in rendering.md
+  layout: 'adaptive',
+});
+// edited.deck       the new deck
+// edited.pptx       the new file
+// edited.assets     its pictures
+// edited.summary    one sentence from the model on what it changed
+// edited.rewritten  numbers of the slides in the new deck that were written or rewritten
+// edited.warnings
+```
+
+An edit is two model calls. The first decides what the deck looks like after the change: which slides stay,
+move, go, get rewritten or are new. The second writes only the slides that change. Reordering and deleting need
+no second call.
+
+- Slides the instruction does not touch are copied by code, so their text cannot drift.
+- A rewritten slide keeps its pictures unless the instruction is about them.
+- A slide given a different pattern takes its photo along.
+- A change of language rewrites every slide, sets the reading direction and translates deck-level fields.
+- "Make the text larger" sets `textScale` and rewrites only the slides whose text no longer fits.
+- "Use three cards instead of four" changes `items` on that slide.
+
+`planEdit(template, deck, instruction, options)` does the same without pictures or rendering and returns
+`{ deck, summary, rewritten, warnings }`.
+
+Extra options for edits (`EditOptions`):
+
+| Option | Meaning |
+| --- | --- |
+| `fields` | Replaces the deck-level values, for example a translated header text. Defaults to the deck's own. |
+| `direction` | Reading direction after the edit. Defaults to the direction of the deck's language. |
+| `imageDensity` | Whether slides added by the edit may use photo patterns. Default `medium`. |
+
+Changes made by hand in PowerPoint are not read back. The deck JSON is the source of truth.
+
+## Errors
+
+| Error | When | What to do |
+| --- | --- | --- |
+| `PlanError` | No pattern can be used with what was supplied; or the model's outline or edit plan is unusable; or the plan uses patterns that cannot be filled | Read the message: it names the patterns and reasons. Supply the missing icons, fields or images, or retry. |
+| `DeckValidationError` | After all repairs the draft still has error-level issues | `error.issues` lists them. Retry, raise `maxRepairs`, or simplify the brief. |
+| Anything your provider throws | The model call failed | Handled by you: slotdeck does not retry model calls. |
+
+Warnings (text a little over a budget, for instance) do not throw. They are returned with the result.
+
+## Cost and time
+
+For one deck: two text calls, more if repairs are needed, and one image call per generated photo. Measured on
+the demo template with `gemini-3.8-flash`: a plan takes about 5 seconds, an eight-slide deck about 30 seconds
+from brief to file (with drawn stand-in pictures), and an edit that rewrites one slide about 8 seconds.
+
+Planning calls (the outline, a change to a plan, the first step of an edit) ask the model for light reasoning,
+because they choose and arrange rather than write. This made them several times faster and removed the runaway
+answers described in [providers.md](providers.md). Writing the slides keeps the model's default.
+
+To keep cost down: reuse `cache` across calls, set `imageDensity: 'low'` or `'none'`, and use `planOutline`
+first so a person can correct the plan before content and pictures are produced.

package/docs/getting-started.md

@@ -0,0 +1,139 @@
+# Getting started
+
+## Install
+
+```bash
+npm install slotdeck
+```
+
+- Node 22.18 or later.
+- ESM only. Your `package.json` needs `"type": "module"`, or your files need the `.mjs` extension (or you use
+  TypeScript with ESM output).
+- Two runtime dependencies come with it: `fflate` (zip) and `@xmldom/xmldom` (XML). There is no native code
+  and no office program involved.
+
+## What you need
+
+| Thing | What it is | Where it comes from |
+| --- | --- | --- |
+| Template | A `.pptx` file with sample slides | Your designer, or your organization's standard deck |
+| Manifest | JSON describing the template | Written once per template: by `draftManifest` (see [template-studio.md](template-studio.md)) or by hand (see [manifest-format.md](manifest-format.md)) |
+| Deck | JSON describing one new presentation | Written by your code, or by a model through `generateDeck` |
+| Assets | Picture bytes by id | Your icon set, your own pictures, or an image source you plug in |
+
+## 1. Render a deck from JSON (no model)
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs';
+import { loadTemplate, renderDeck } from 'slotdeck';
+import type { DeckSpec, TemplateManifest } from 'slotdeck';
+
+const manifest = JSON.parse(readFileSync('template.manifest.json', 'utf8')) as TemplateManifest;
+const template = loadTemplate(readFileSync('template.pptx'), manifest); // do this once and keep it
+
+const deck: DeckSpec = {
+  version: 1,
+  title: 'Quarterly review',
+  fields: { organizationDepartment: 'Acme  |  Operations' },
+  slides: [
+    { pattern: 'cover', slots: { title: 'Quarterly review', subtitle: 'What changed since March' } },
+    {
+      pattern: 'text-and-photo',
+      slots: {
+        title: 'Deliveries are faster',
+        body: ['Median delivery time fell from four days to three.', 'The new depot explains most of it.'],
+        photo: { asset: 'depot', alt: 'The new depot' },
+      },
+    },
+    { pattern: 'closing', slots: { title: 'Thank you' } },
+  ],
+};
+
+const { pptx, warnings } = renderDeck(template, deck, {
+  assets: { depot: readFileSync('depot.jpg') },
+  layout: 'adaptive', // optional slots that the deck leaves out are removed from the slide
+});
+for (const warning of warnings) console.log(`slide ${warning.slide} ${warning.slot ?? ''}: ${warning.message}`);
+writeFileSync('review.pptx', pptx);
+```
+
+The pattern ids (`cover`, `text-and-photo`, `closing`) and slot names (`title`, `body`, `photo`) are whatever
+the manifest defines. To list them:
+
+```ts
+for (const pattern of manifest.patterns) {
+  console.log(pattern.id, '-', pattern.description);
+  for (const slot of pattern.slots) console.log('   ', slot.name, slot.kind, slot.empty ?? 'required');
+}
+```
+
+If the deck does not fit the manifest (unknown pattern, a required slot without a value, a picture whose
+asset was not passed), `renderDeck` throws a `DeckValidationError` whose `issues` array says what is wrong. Call
+`validateDeck` first if you want the list without an exception. See [rendering.md](rendering.md).
+
+## 2. Generate a deck with a language model
+
+```ts
+import { generateDeck, loadTemplate } from 'slotdeck';
+import type { LlmProvider } from 'slotdeck';
+
+// Any model works: the only requirement is this one method. See providers.md.
+const llm: LlmProvider = {
+  async generateJson({ system, prompt, schema }) {
+    return await myModel.completeAsJson({ system, prompt, schema }); // must resolve with a parsed JSON value
+  },
+};
+
+const { pptx, deck, warnings, outline } = await generateDeck(
+  template,
+  {
+    prompt: 'Quarterly review for the operations team: deliveries got faster, returns fell, two depots opened.',
+    slideCount: 6,
+    imageDensity: 'none', // no image source was given, so plan without photos
+    fields: { organizationDepartment: 'Acme  |  Operations' },
+  },
+  { llm, layout: 'adaptive' },
+);
+```
+
+Keep the returned `deck`: it is what you store, show, edit and render again. See [generating.md](generating.md).
+
+With the included Gemini adapter instead of your own provider:
+
+```ts
+import { gemini, geminiImages } from 'slotdeck';
+
+const llm = gemini({ model: 'gemini-3.8-flash', apiKey: process.env.GEMINI_API_KEY });
+const images = geminiImages({ model: 'gemini-3.1-flash-image', apiKey: process.env.GEMINI_API_KEY });
+```
+
+## 3. Change a deck by instruction
+
+```ts
+import { editDeck } from 'slotdeck';
+
+const edited = await editDeck(template, deck, 'Shorten slide 2 and add a slide about returns before the end', { llm });
+// edited.deck, edited.pptx, edited.summary, edited.rewritten
+```
+
+## 4. Describe a new template
+
+```ts
+import { checkManifest, draftManifest, loadTemplate, renderDeck, sampleDeck } from 'slotdeck';
+
+const { manifest, skipped, issues } = await draftManifest(readFileSync('new-template.pptx'), { llm, name: 'new-template' });
+const draft = loadTemplate(readFileSync('new-template.pptx'), manifest);
+console.log(checkManifest(draft)); // [] when the manifest matches the file
+
+// A deck that uses every pattern once with every slot full: render it and look at it.
+const { deck: sample, assets } = sampleDeck(draft);
+writeFileSync('sample.pptx', renderDeck(draft, sample, { assets }).pptx);
+```
+
+A drafted manifest is a starting point that a person reviews. See [template-studio.md](template-studio.md).
+
+## Where to go next
+
+- The two JSON formats: [deck-format.md](deck-format.md), [manifest-format.md](manifest-format.md)
+- Using it inside a chat assistant: [chat-tools.md](chat-tools.md)
+- Connecting an internal model gateway: [providers.md](providers.md)