@tycoworks/tycoslide 0.11.2 → 0.11.4

package/README.md

@@ -16,7 +16,7 @@ Create editable, on-brand PowerPoint slides from markdown.
 npm install @tycoworks/tycoslide
 ```
 
-Installing also downloads Chromium (~554MB), via `@playwright/browser-chromium`, which tycoslide uses to render mermaid diagrams. If you install with `--ignore-scripts`, run `npx playwright install chromium-headless-shell` before building a deck with diagrams.
+Mermaid diagrams need Chrome on the machine. See [Diagrams](#diagrams).
 
 Create `deck.md`:
 
@@ -54,7 +54,7 @@ npx tycoslide build deck.md               # → deck.pptx
 ```bash
 npx tycoslide build deck.md       # markdown → PPTX (theme resolved from deck frontmatter)
 npx tycoslide build deck.md --no-notes   # omit speaker notes from the output
-npx tycoslide package             # regenerate skill.md/syntax.md/manifest.json + zip the whole theme into a self-contained <package-name>.zip
+npx tycoslide package             # regenerate skill.md/syntax.md/manifest.json + zip the theme into a self-contained <package-name>.zip
 ```
 
 ## Theme Structure
@@ -78,3 +78,14 @@ my-theme/
 **Layout** — a slide pattern in the template (Title, Body, Quote, etc.).
 **Theme** — the directory that bundles a template, assets, and config.
 **Manifest** — a machine-readable catalog of layouts and assets for AI agents.
+
+## Diagrams
+
+Mermaid blocks are rendered with a headless Chrome. tycoslide does not download one.
+It uses a browser you already have, in this order:
+
+1. `--browser-path <path>`
+2. A system Chrome install
+3. `npx playwright install chromium-headless-shell`
+
+Decks without diagrams need no browser.

package/SKILL.md

@@ -17,6 +17,7 @@ npm install
 
 This installs the tycoslide engine and its dependencies. You only need to do this once.
 
+
 ## Overview
 
 This skill builds on-brand decks from a markdown deck file. The theme provides slide layouts that control design. Your job: pick the right layouts, fill them with content, and build. You never restyle the layout; the engine clones the real slides, so brand, layout, fonts, and chrome come for free.
@@ -35,12 +36,12 @@ This skill builds on-brand decks from a markdown deck file. The theme provides s
 
 Before writing anything, read `manifest.json`. It contains:
 
-- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `accepts` and optionally `required` (plus, for assets, a `type` of `icon`/`image`/`background`)
+- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions). A layout is identified by its `name`; every parameter and slot by its `key`. Parameters carry a `type`, slots carry `accepts`, and either may be `required`
 - **assets** -- brand logos, client logos, illustrations, and icons (`description`)
 
 A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
 - **parameters** -- one value on a frontmatter line. Types: `template`, `image`. Fill by putting a value under the parameter's key in the slide frontmatter.
-- **slots** -- a multi-line region in the body. Accept types: `text`, `table`, `image`. Fill as a `::name::` region; a fenced code block routes to a `text` slot, a fenced mermaid block to an `image` slot.
+- **slots** -- a multi-line region in the body. Accept types: `text`, `table`, `image`. Fill as a `::key::` region, using the slot's `key` from the manifest; a fenced code block routes to a `text` slot, a fenced mermaid block to an `image` slot.
 
 A slot may accept more than one content type -- the manifest lists each slot's `accepts`, and the shape of the content you write selects which one.
 
@@ -105,7 +106,7 @@ subtitle: This Quarter
 
 ### Body content, slots, and formatting
 
-See [syntax.md](syntax.md) for the full syntax reference: body content (paragraphs, bullets, nesting), inline formatting (bold, italic, strikethrough, underline, hyperlinks), named slots (`::name::` markers), the parameter/slot split (parameters: template, image; slots accept: text, table, image), and image parameters.
+See [syntax.md](syntax.md) for the full syntax reference: body content (paragraphs, bullets, nesting), inline formatting (bold, italic, strikethrough, underline, hyperlinks), named slots (`::key::` markers), the parameter/slot split (parameters: template, image; slots accept: text, table, image), and image parameters.
 
 ### Build
 
@@ -140,7 +141,7 @@ Keep each slot's content to what its region comfortably holds. When content over
 - **Don't repeat the same layout** -- vary layouts for visual rhythm
 - **Don't overstuff a slot** -- keep content to what its region comfortably holds; split across slides when there's too much
 - **Don't restyle the layout** -- the theme owns all design; you only fill slots
-- **Don't use an image that's wrong for the slot** -- a small slot wants a simple icon, not a dense illustration; if the build warns an image shrank to a small %, swap it for a simpler one
+- **Don't use an image that's wrong for the slot** -- a small slot wants a simple icon, not a dense illustration. If you get a `shrunk to X%` warning, look at the rendered slide: if the image is now too small to make out, use a simpler one.
 - **Don't invent layout or asset names** -- only use what exists in the manifest
 - **Don't leave required parameters or slots empty** -- and don't leave a placeholder logo or dummy text in an image parameter you care about
 
@@ -156,7 +157,7 @@ Build the deck again ([Build](#build)) and read the output carefully. Common err
 
 | Error | Fix |
 |-------|-----|
-| `Unknown layout: 'xyz'` | Check layout names in `manifest.json` |
+| `unknown layout "xyz"` | Check layout names in `manifest.json` |
 | A parameter or slot didn't fill | Use the key names the layout declares -- parameters in frontmatter, slots as body regions |
 | An image didn't swap / placeholder remains | Use the image parameter's key name in frontmatter, and an asset path that exists in `manifest.json` |
 | YAML parse error | Fix the YAML syntax in the slide's frontmatter |
@@ -167,7 +168,7 @@ Build the deck again ([Build](#build)) and read the output carefully. Common err
 ### Verification Loop
 
 1. Write the deck file → Build
-2. **Read every error** -- fix all of them
+2. **Fix the error** -- the build stops at the first one, so expect several rounds
 3. Rebuild
 4. **If content overflows**: reduce content or split into two slides
 5. Repeat until the build exits cleanly

package/dist/cli.js

@@ -23,6 +23,7 @@ program
     .argument("<deck>", "path to deck markdown file")
     .option(`-c, --config <path>`, "override theme config path (default: read from frontmatter)")
     .option("--no-notes", "omit speaker notes from the output (also strips any inherited template notes)")
+    .option("--browser-path <path>", "Chrome executable to render diagrams with (default: auto-detect)")
     .action(async (deckPath, opts) => {
     const absDeckPath = resolve(process.cwd(), deckPath);
     let source;
@@ -42,7 +43,7 @@ program
     if (!absConfigPath) {
         throw new Error(`${basename(deckPath)}: missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
     }
-    const config = loadThemeConfig(absConfigPath);
+    const config = { ...loadThemeConfig(absConfigPath), browserPath: opts.browserPath };
     const deck = await compileDeck(doc, config);
     // Always write the .pptx next to the input deck, named after it.
     const outName = basename(deckPath).replace(/\.md$/, ".pptx");
@@ -83,4 +84,13 @@ program
     writeFileSync(resolve(process.cwd(), zipFile), await zipDir(process.cwd(), skillName, config, generated));
     console.log(`WROTE ${zipFile}`);
 });
-await program.parseAsync(process.argv);
+// Everything below the CLI throws plain Errors carrying a written-for-humans
+// message. Print that message and stop; a Node stack trace tells a deck author
+// nothing about their deck, and buries the part that does.
+try {
+    await program.parseAsync(process.argv);
+}
+catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+}

package/dist/markdown/blocks/code.js

@@ -18,7 +18,7 @@ export const CODE = {
         // A fence with no language can't be highlighted (no Shiki grammar to pick),
         // so fail fast naming the slot rather than attempt a language-less highlight.
         if (!code.lang) {
-            throw new Error(`Slide ${ctx.slideIdx}: layout "${ctx.layoutName}" slot content (from ${ctx.source}) has a code fence ` +
+            throw new Error(`Slide ${ctx.slideNo}: layout "${ctx.layoutName}" slot content (from ${ctx.source}) has a code fence ` +
                 "with no language; add one after the opening ``` (e.g. ```sql).");
         }
         const codeTheme = ctx.config.codeTheme;

package/dist/markdown/blocks/mermaid.d.ts

@@ -13,3 +13,18 @@ export declare const MERMAID_LANG = "mermaid";
  * throws by name.
  */
 export declare const MERMAID: BlockHandler;
+type Chromium = typeof import("playwright-core")["chromium"];
+/**
+ * Find a browser rather than ship one. tycoslide never downloads Chromium: the
+ * binary comes from a CDN rather than the npm registry, so bundling it breaks
+ * installs anywhere egress is restricted to the registry, and pins the build to
+ * one revision that a machine's existing browser will rarely match.
+ *
+ * Three ways in, most explicit first: `--browser-path` names an executable
+ * outright (any build, the revision is not checked), `channel: "chrome"` picks
+ * up a system Chrome install, and the bare launch falls back to whatever `npx
+ * playwright install` put in Playwright's own cache. If none work, the error
+ * names every remedy a caller can act on.
+ */
+export declare function launchChromium(chromium: Chromium, browserPath?: string): Promise<Awaited<ReturnType<Chromium["launch"]>>>;
+export {};

package/dist/markdown/blocks/mermaid.js

@@ -125,7 +125,7 @@ async function renderOne(definition, variantName, variant, cacheDir, compilerCon
     const outputPath = join(cacheDir, `${key}.png`);
     if (existsSync(outputPath))
         return outputPath;
-    await renderMermaidToPng(processed, renderConfig, fonts, outputPath);
+    await renderMermaidToPng(processed, renderConfig, fonts, outputPath, compilerConfig.browserPath);
     return outputPath;
 }
 let bundleCache = null;
@@ -142,6 +142,45 @@ function fontFaceCss(fonts) {
         .map((f) => `@font-face { font-family: '${f.family}'; src: url('${f.url}') format('${f.format}'); font-weight: ${f.weight}; font-style: normal; }`)
         .join("\n");
 }
+const LAUNCH_ARGS = { headless: true, args: ["--no-sandbox"] };
+/**
+ * Find a browser rather than ship one. tycoslide never downloads Chromium: the
+ * binary comes from a CDN rather than the npm registry, so bundling it breaks
+ * installs anywhere egress is restricted to the registry, and pins the build to
+ * one revision that a machine's existing browser will rarely match.
+ *
+ * Three ways in, most explicit first: `--browser-path` names an executable
+ * outright (any build, the revision is not checked), `channel: "chrome"` picks
+ * up a system Chrome install, and the bare launch falls back to whatever `npx
+ * playwright install` put in Playwright's own cache. If none work, the error
+ * names every remedy a caller can act on.
+ */
+export async function launchChromium(chromium, browserPath) {
+    const attempts = [
+        ...(browserPath
+            ? [
+                {
+                    label: `--browser-path ${browserPath}`,
+                    launch: () => chromium.launch({ ...LAUNCH_ARGS, executablePath: browserPath }),
+                },
+            ]
+            : []),
+        { label: "system Chrome", launch: () => chromium.launch({ ...LAUNCH_ARGS, channel: "chrome" }) },
+        { label: "Playwright's downloaded browser", launch: () => chromium.launch(LAUNCH_ARGS) },
+    ];
+    const failures = [];
+    for (const attempt of attempts) {
+        try {
+            return await attempt.launch();
+        }
+        catch (e) {
+            failures.push(`  ${attempt.label}: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`);
+        }
+    }
+    throw new Error(`No Chromium available to render mermaid. Tried:\n${failures.join("\n")}\n` +
+        "Fix by any one of: pass --browser-path, install Google Chrome, " +
+        "or run `npx playwright install chromium-headless-shell`.");
+}
 /**
  * Render a mermaid definition to a transparent PNG via a headless Chromium
  * (Playwright — the proven old driver, stronger headless font fidelity). The
@@ -151,7 +190,7 @@ function fontFaceCss(fonts) {
  * font instead of a substitute. mmdc's `--cssFile` injects too late (after layout)
  * to affect metrics, which is why this replaces its programmatic API.
  */
-async function renderMermaidToPng(processed, renderConfig, fonts, outputPath) {
+async function renderMermaidToPng(processed, renderConfig, fonts, outputPath, browserPath) {
     const bundle = getMermaidBundle();
     // JSON script blocks pass data without escaping issues; escape `</` so a value
     // can't close the surrounding <script>.
@@ -200,12 +239,12 @@ ${fontFaceCss(fonts)}
     // origin can't fetch the file:// font resources (@font-face silently fails),
     // whereas a file://-origin document loads them.
     const htmlPath = `${outputPath}.html`;
-    const { chromium } = await import("playwright");
+    const { chromium } = await import("playwright-core");
     let browser;
     try {
         // Written inside the try so the finally always cleans it up, even if launch throws.
         writeFileSync(htmlPath, html);
-        browser = await chromium.launch({ headless: true, args: ["--no-sandbox"] });
+        browser = await launchChromium(chromium, browserPath);
         const page = await browser.newPage({ viewport: { width: 800, height: 600 }, deviceScaleFactor: 2 });
         await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
         await page.waitForSelector(`#output[${RENDER_SIGNAL_ATTR}="${RenderSignal.Done}"]`, { timeout: 30000 });

package/dist/markdown/blocks/text.js

@@ -34,7 +34,7 @@ export function compileTextAggregate(nodes, ctx) {
  * (table/image/code) mixed into prose — both name the layout/slide/slot + type.
  */
 function reject(nodeCount, nodeType, ctx) {
-    const where = `Slide ${ctx.slideIdx}: layout "${ctx.layoutName}" slot content (from ${ctx.source})`;
+    const where = `Slide ${ctx.slideNo}: layout "${ctx.layoutName}" slot content (from ${ctx.source})`;
     if (nodeCount === 1) {
         return `${where} is a standalone "${nodeType}" block, which is not a supported content kind.`;
     }

package/dist/markdown/deckCompiler.js

@@ -29,10 +29,10 @@ const ASSET_REF_RE = /^\$([a-zA-Z]\w*)\.([a-zA-Z]\w*)$/;
  * the author's markdown shape selects one. A type the slot does not accept fails
  * fast, naming the layout, slot, the type it got, and the types the slot accepts.
  */
-function assertSlotRegion(slot, got, layoutName, slideIdx, source) {
+function assertSlotRegion(slot, got, layoutName, slideNo, source) {
     if (!slot.accepts.some((b) => b.type === got)) {
         const accepted = slot.accepts.map((b) => b.type).join(", ");
-        throw new Error(`Slide ${slideIdx}: layout "${layoutName}" slot "${slot.key}" does not accept ${got} content ` +
+        throw new Error(`Slide ${slideNo}: layout "${layoutName}" slot "${slot.key}" does not accept ${got} content ` +
             `(from ${source}); it accepts: ${accepted}.`);
     }
 }
@@ -124,9 +124,13 @@ function validateLayout(layout) {
 async function compileStep(slide, config, assetTypeByPath, resolveAssetRef) {
     const { layouts, rootDir } = config;
     const { frontmatter, slots, index } = slide;
+    // Slide numbers in errors are 1-based, matching how an author counts slides in
+    // the deck file. Derive it once: every message below, and the parse-time errors
+    // in slideParser, must agree or the author looks at the wrong slide.
+    const slideNo = index + 1;
     const layout = frontmatter[RESERVED_KEY.LAYOUT];
     if (layout === undefined) {
-        throw new Error(`Slide ${index}: missing required "${RESERVED_KEY.LAYOUT}" in frontmatter`);
+        throw new Error(`Slide ${slideNo}: missing required "${RESERVED_KEY.LAYOUT}" in frontmatter`);
     }
     // Speaker notes are slide-level metadata, stripped from frontmatter before
     // slot/param resolution — exactly like `layout`. Coerce to string if present.
@@ -138,12 +142,12 @@ async function compileStep(slide, config, assetTypeByPath, resolveAssetRef) {
     const layoutDef = layouts.find((l) => l.name === layoutName);
     if (!layoutDef) {
         const known = layouts.map((l) => l.name).join(", ");
-        throw new Error(`Slide ${index}: unknown layout "${layoutName}". Available layouts: ${known}`);
+        throw new Error(`Slide ${slideNo}: unknown layout "${layoutName}". Available layouts: ${known}`);
     }
     // Reject any frontmatter key not declared by this layout's parameters (reserved
     // layout/notes stripped first). The per-layout strict schema IS the unknown-key
     // check — it fires before the resolution loop, so that loop only sees valid keys.
-    validateSlideFrontmatter(frontmatter, layoutDef, index);
+    validateSlideFrontmatter(frontmatter, layoutDef, slideNo);
     // Map each author-facing key to its owning parameter: template keys → the template
     // parameter that declares them, image keys → the image parameter. validateLayout
     // (run once per layout in compileDeck) has already proven these key spaces are
@@ -202,7 +206,7 @@ async function compileStep(slide, config, assetTypeByPath, resolveAssetRef) {
         const supplied = valuesByTemplateParam.get(templateParam);
         if (!supplied) {
             if (templateParam.required) {
-                throw new Error(`Slide ${index}: layout "${layoutName}" requires template parameter "${templateParam.shapeName}" ` +
+                throw new Error(`Slide ${slideNo}: layout "${layoutName}" requires template parameter "${templateParam.shapeName}" ` +
                     `(keys: ${templateKeys(templateParam.template).join(", ")}); none provided`);
             }
             continue;
@@ -215,14 +219,14 @@ async function compileStep(slide, config, assetTypeByPath, resolveAssetRef) {
     for (const [name, text] of Object.entries(slots)) {
         const slot = slotsByKey.get(name);
         if (!slot) {
-            throw new Error(`Slide ${index}: unknown slot "::${name}::" in layout "${layoutName}". ` +
+            throw new Error(`Slide ${slideNo}: unknown slot "::${name}::" in layout "${layoutName}". ` +
                 `Valid slots: ${[...slotsByKey.keys()].join(", ")}`);
         }
         const source = `::${name}::`;
         const parsed = parseSlotContent(text, {
             resolveAssetRef,
             layoutName,
-            slideIdx: index,
+            slideNo: slideNo,
             source,
             config,
             layoutVariant: layoutDef.variant,
@@ -235,12 +239,12 @@ async function compileStep(slide, config, assetTypeByPath, resolveAssetRef) {
     // enforced during expansion above.
     for (const image of imageByKey.values()) {
         if (image.required && content[image.key] === undefined) {
-            throw new Error(`Slide ${index}: layout "${layoutName}" requires parameter "${image.key}"; none provided`);
+            throw new Error(`Slide ${slideNo}: layout "${layoutName}" requires parameter "${image.key}"; none provided`);
         }
     }
     for (const slot of layoutDef.slots) {
         if (slot.required && content[slot.key] === undefined) {
-            throw new Error(`Slide ${index}: layout "${layoutName}" requires slot "${slot.key}"; none provided`);
+            throw new Error(`Slide ${slideNo}: layout "${layoutName}" requires slot "${slot.key}"; none provided`);
         }
     }
     // Content values are already engine fills — code fences highlighted to TextFill

package/dist/markdown/schema/deckSchema.d.ts

@@ -27,4 +27,4 @@ export declare function deckFrontmatterSchema(layout: CompilerLayout): z.ZodObje
  * shared `strict` "Valid keys: …" formatter). Reserved keys (`layout`, `notes`) are
  * slide-level metadata, not parameters, so they are stripped before `safeParse`.
  */
-export declare function validateSlideFrontmatter(frontmatter: Record<string, unknown>, layout: CompilerLayout, slideIdx: number): void;
+export declare function validateSlideFrontmatter(frontmatter: Record<string, unknown>, layout: CompilerLayout, slideNo: number): void;

package/dist/markdown/schema/deckSchema.js

@@ -42,10 +42,10 @@ export function deckFrontmatterSchema(layout) {
  * shared `strict` "Valid keys: …" formatter). Reserved keys (`layout`, `notes`) are
  * slide-level metadata, not parameters, so they are stripped before `safeParse`.
  */
-export function validateSlideFrontmatter(frontmatter, layout, slideIdx) {
+export function validateSlideFrontmatter(frontmatter, layout, slideNo) {
     const { [RESERVED_KEY.LAYOUT]: _layout, [RESERVED_KEY.NOTES]: _notes, ...params } = frontmatter;
     const result = deckFrontmatterSchema(layout).safeParse(params);
     if (!result.success) {
-        throw new Error(`Slide ${slideIdx}: ${z.prettifyError(result.error)}`);
+        throw new Error(`Slide ${slideNo}: ${z.prettifyError(result.error)}`);
     }
 }

package/dist/markdown/schema/themeConfigSchema.d.ts

@@ -49,8 +49,8 @@ export declare const ThemeConfigSchema: z.ZodObject<{
     assets: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
         path: z.ZodString;
         type: z.ZodEnum<{
-            image: "image";
             icon: "icon";
+            image: "image";
             background: "background";
         }>;
         description: z.ZodString;

package/dist/markdown/types.d.ts

@@ -93,7 +93,7 @@ export type BlockFill = TextFill | TableFill | ImageFill;
 export type BlockContext = {
     resolveAssetRef: (ref: string) => ImageFill;
     layoutName: string;
-    slideIdx: number;
+    slideNo: number;
     source: string;
     config: CompilerConfig;
     /**
@@ -308,4 +308,10 @@ export type CompilerThemeConfig = {
 };
 export type CompilerConfig = CompilerThemeConfig & {
     rootDir: string;
+    /**
+     * Browser executable to render mermaid with, from `--browser-path`. Added
+     * after load like `rootDir`: it is a per-invocation choice, not a theme's.
+     * Unset means discover one (see `launchChromium`).
+     */
+    browserPath?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Create editable, on-brand PowerPoint slides from markdown.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,13 +23,12 @@
     "format": "biome format --write ."
   },
   "dependencies": {
-    "@playwright/browser-chromium": "^1.62.1",
     "@xmldom/xmldom": "^0.9.10",
     "commander": "^15.0.0",
     "image-size": "^2.0.2",
     "jszip": "^3.10.1",
     "mermaid": "^11.16.1",
-    "playwright": "^1.62.1",
+    "playwright-core": "^1.62.1",
     "pptx-automizer": "^0.8.2",
     "remark-gfm": "^4.0.1",
     "remark-ins": "^1.2.5",

package/syntax.md

@@ -24,7 +24,7 @@ The output `.pptx` is written next to the deck file, named after it (`deck.md`
 
 ## Body content
 
-A slide's body is split into named regions with `::name::` markers. Each region fills the slot whose key matches the marker name.
+A slide's body is split into regions with `::key::` markers. Each region fills the slot whose `key` matches the marker.
 
 ```markdown
 ---
@@ -58,9 +58,9 @@ Inline formatting is supported in body content:
 
 ---
 
-## Named slots with `::name::` markers
+## Named slots with `::key::` markers
 
-For layouts with multiple content regions (e.g., two-column layouts), use `::name::` markers to split body content into named slots.
+For layouts with multiple content regions (e.g., two-column layouts), use `::key::` markers to split body content into named slots.
 
 ```markdown
 ---
@@ -87,7 +87,7 @@ Content after a marker goes to the slot matching that name. The marker names mus
 
 ## Parameters and slots (in `manifest.json`)
 
-A layout advertises two kinds of author-facing input, split by one rule: **a parameter is one value on a frontmatter line; a slot is a multi-line region in the body** (a `::name::` region). In `manifest.json` each layout carries two lists, `parameters` and `slots`:
+A layout advertises two kinds of author-facing input, split by one rule: **a parameter is one value on a frontmatter line; a slot is a multi-line region in the body** (a `::key::` region). In `manifest.json` each layout carries two lists, `parameters` and `slots`:
 
 ```jsonc
 {
@@ -125,7 +125,7 @@ Fill a parameter by putting a value under its key in the slide's frontmatter.
 
 ### Body content shapes
 
-Fill a slot by writing a `::name::` region in the body; the marker maps to the slot of that name. A slot's manifest entry lists which content types it `accepts` (`text`, `table`, `image`) -- write content whose shape matches one of them:
+Fill a slot by writing a `::key::` region in the body; the marker maps to the slot with that `key`. A slot's manifest entry lists which content types it `accepts` (`text`, `table`, `image`) -- write content whose shape matches one of them:
 
 - **text** (slots that accept `text`) -- markdown paragraphs and bullets, rebuilt from the template's specimen paragraph styles. A fenced code block also routes here:
   ````markdown
@@ -227,7 +227,7 @@ Each layout also declares a `slideNumber` pointing at the physical slide in the
 
 Any slide may carry a `notes:` key in its frontmatter -- a plain-text speaker-notes block attached to that slide's notes page. It is slide-level metadata, not a parameter or a slot: it is never routed to a shape and never appears on the slide face, only in the presenter/notes view.
 
-Write multiple lines with a YAML block scalar (`|`); each line becomes one notes paragraph. Blank template notes on the underlying slide are always stripped, so only what you author here shows up.
+Write multiple lines with a YAML block scalar (`|`); each line becomes one notes paragraph. Template notes on the underlying slide are always stripped, so only what you author here shows up.
 
 ```yaml
 ---
@@ -239,7 +239,7 @@ notes: |
 ---
 ```
 
-To build with all speaker notes omitted, pass `--no-notes` to `npx tycoslide build` (see [README](README.md#cli)).
+To build with all speaker notes omitted, pass `--no-notes` to `npx tycoslide build`.
 
 ---