@tycoworks/bon 0.1.0

package/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: slides
+description: >
+  Use this skill any time the user wants to create branded slides, presentations,
+  pitch decks, or sales collateral as a .pptx. Trigger whenever the user mentions "deck," "slides,"
+  "presentation," "pitch," or .pptx output. Also trigger when the user says "build me a deck,"
+  "make slides about X," or "turn this into a presentation."
+---
+
+# slides
+
+This skill builds on-brand decks from a 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.
+
+For brand voice and naming guidelines, read `brand.md` if it exists alongside this skill.
+
+## Quick Reference
+
+| Task | Guide |
+|------|-------|
+| Discover layouts and assets | Read `manifest.json` |
+| Write a deck (structure, slots, assets) | See [Creating Slides](#creating-slides) below |
+| Fix build errors | See [QA](#qa-required) below |
+
+---
+
+## Layout Discovery
+
+Before writing anything, read `manifest.json`. It contains:
+
+- **layouts** -- for each: `name`, `description`, `contentSlots` (with `type` and `limit`), `assetSlots` (with `accepts` and `required`), and documentation (`whenToUse`, `whenNotToUse`)
+- **assets** -- brand logos, client logos, illustrations, and icons (`description`, `whenToUse`)
+
+Study each layout's `whenToUse` and `limit`s before writing any slides. These are your primary guide for matching content to layouts.
+
+---
+
+## Creating Slides
+
+Write a deck file: a plain JSON file with an `output` name and an ordered list of `steps`. Each step names a `layout`, fills its `content` slots, and optionally swaps `assets`.
+
+```json
+{
+  "output": "my-deck.pptx",
+  "steps": [
+    { "layout": "Title",
+      "content": { "title": "...", "name": "Presenter Name", "jobTitle": "Their Role" } },
+    { "layout": "Quote dark",
+      "content": { "quote": "...", "attribution": ["Name", "Role, Company"] },
+      "assets": { "logo": "assets/clients/acme.png" } }
+  ]
+}
+```
+
+`content` keys must match the layout's `contentSlot` keys; `assets` keys must match its `assetSlot` keys. Asset paths are relative to the repo root.
+
+### Asset slots (`assetSlots`)
+Each asset slot declares:
+- **`accepts`** — a **sizing constraint**, not a semantic label:
+  - `icon` — simple, scalable graphics that read at any size: glyphs and logos.
+  - `image` — detailed rasters that only read large: illustrations and schematics.
+  - **Match the kind exactly — the engine enforces it both ways.**
+    - An `image` asset in an `icon` slot is unreadable at card/grid size (detail turns to noise).
+    - An `icon` asset in an `image` slot blows up oversized filling a half-slide area and looks stupid.
+    - Small slots take icons; large/full-bleed `image` slots take dense `image` assets. The asset's `type` in `manifest.json` tells you which it is. The semantic role ("the client's logo here") lives in the slot's `key`/description, not the type.
+- **`required: true`** — you MUST supply this asset; the slide has no usable default and the build fails without it (e.g. team-member photos, icon-grid icons, the quote logo). If you don't have a suitable image, ask the user for one.
+- Slots without `required` are optional — omit them to keep the layout's built-in default (e.g. the full-bleed background, the two-column split image).
+
+### Slot types (in `manifest.json`)
+
+- **`text`** — a single line. Pass a string. (Use it for stat values too — a stat can be textual.)
+- **`lines`** — a fixed set of styled lines (e.g. name + job title). Pass an array of strings, one per line.
+- **`prose`** — a body block, **written as markdown**. Pass a markdown string, or an array of lines:
+  - `- ` (or `* `) starts a **bullet**; indent **2 spaces per level** to nest (`  - ` = level 1).
+  - A line with no marker is a **paragraph** (a lead-in / prose line).
+  - Blank lines are ignored.
+  - Do NOT put headings in a `prose` body — the heading is the slide's `title` slot, and a subheading is the `subtitle` slot on subtitle layouts. Prose is paragraphs + bullets only.
+  - Some slots fill *part* of a shared box (they have a `paragraph` selector in the layout definition), e.g. a cover's `name` and `jobTitle` are two slots in one box. Nothing special to do: just fill each key. Check the layout's `contentSlots` for the exact keys.
+
+  ```json
+  "body": [
+    "Every option falls short:",
+    "- OLTP databases are siloed.",
+    "- Lakehouses lack freshness.",
+    "  - and cost-efficiency."
+  ]
+  ```
+
+Build:
+
+```bash
+# Run the command from manifest.json's build.command
+# e.g.: node src/run-spec.ts deck.json my-deck.pptx
+```
+
+The deck is written to your current working directory (not inside the skill).
+
+---
+
+## Layout Selection
+
+**Don't create boring decks.** Repeating the same layout on every slide makes a forgettable presentation. Use variety and match content shape to layout purpose.
+
+### Before Starting
+
+1. **Read the manifest thoroughly.** Each layout has `whenToUse`, `whenNotToUse`, and `limit`s. Respect all three.
+2. **Match content shape to layout purpose.** A comparison belongs in a two/three-column layout, quantified proof belongs in stat blocks, a customer voice belongs in a quote or testimonial layout. Don't force content into the wrong layout.
+3. **Plan narrative arc first.** Decide the sequence of ideas before picking layouts. Then assign each idea to its best-fit layout from the manifest. Keep one variant (all dark or all light) across the deck.
+
+### For Each Slide
+
+**Every slide communicates one idea.** If you're writing more than 5 bullets or 3 paragraphs, split into two slides.
+
+Check each layout's `limit` in the manifest for content density constraints. When content overflows, split across slides.
+
+### Avoid (Common Mistakes)
+
+- **Don't repeat the same layout** -- vary layouts for visual rhythm
+- **Don't dump all content on one slide** -- two clear slides beat one crowded slide
+- **Don't ignore layout limits** -- if a slot says max 4 stats, use 4 or fewer
+- **Don't open with a body/content layout** -- use the Title layout for impact
+- **Don't skip section dividers** -- for decks over 5 slides, use Section title layouts to group sections
+- **Don't restyle the layout** -- the theme owns all design; you only fill slots
+- **Don't invent layout or asset names** -- only use what exists in the manifest
+- **Don't leave required slots empty** -- and don't leave a placeholder logo or dummy text in an asset slot you care about
+- **Don't mix dark and light** -- keep one variant across the deck
+
+---
+
+## QA (Required)
+
+**Assume the first build will fail. Your job is to fix it.**
+
+Your first draft almost never comes out clean. Approach QA as a debugging session, not a confirmation step. If you haven't run at least one build-fix cycle, you're not done.
+
+### Build
+
+Run the command from `manifest.json`'s `build.command`:
+
+```bash
+# e.g.: node src/run-spec.ts deck.json my-deck.pptx
+```
+
+Read output carefully. Common errors and fixes:
+
+| Error | Fix |
+|-------|-----|
+| `Unknown layout: 'xyz'` | Check layout names in `manifest.json` |
+| A slot didn't fill | Use the `contentSlot` key names declared by the layout |
+| An image didn't swap / placeholder remains | Use the `assetSlot` key, and an asset path that exists in `manifest.json` |
+| `Cannot read ... JSON` / parse error | Fix the JSON syntax in the deck file |
+| `Skipped setting relation target` | The asset image couldn't be placed; check the path and file |
+
+### Verification Loop
+
+1. Write the deck file → Build
+2. **Read every error** -- fix all of them
+3. Rebuild
+4. **If content overflows**: reduce content or split into two slides
+5. Repeat until the build exits cleanly
+
+**Do not declare success until you've completed at least one build-fix cycle.**
+
+### Visual Check
+
+After a clean build, render the `.pptx` to PNGs and inspect them:
+
+```bash
+soffice --headless --convert-to pdf --outdir . <deck>.pptx
+pdftoppm -png -r 96 <deck>.pdf <name>
+```
+
+Read each slide image and check for:
+
+- **Word wrapping** — text that breaks mid-word or overflows its container
+- **Cramped text** — content too dense for the slide area
+- **Leftover placeholders** — dummy text ("Lorem ipsum", "Firstname Lastname") or a placeholder logo that should have been swapped
+- **Cut-off content** — text or images clipped at slide edges
+
+If you spot issues, reduce content, switch layouts, or split into multiple slides. Rebuild and re-check.
+
+### Content Review (Use Subagents)
+
+**Use subagents for review** -- even for short decks. You've been staring at the content and will see what you expect, not what's there. Subagents have fresh eyes.
+
+After a successful build, spawn a subagent:
+
+```
+Review this deck. Assume there are issues -- find them.
+
+Check for:
+- Slides that are too dense (>7 bullets, >5 paragraphs, too many stats/rows)
+- Same layout repeated multiple times with no variety
+- Content that doesn't match layout purpose (check whenToUse in manifest.json)
+- Narrative that doesn't flow logically
+- Missing opening (Title) or closing (Thank you) slide
+- Slides that are too sparse (a single bullet doesn't need its own slide)
+- Leftover placeholder logos or dummy text in the rendered images
+
+For each issue, suggest a specific fix.
+
+Read: /path/to/deck.json and the rendered PNGs in the working directory
+Also read: manifest.json (for layout documentation)
+```
+
+If the subagent finds issues, fix them and rebuild.
+
+---
+
+## Core Commands
+
+```bash
+# Build a deck (use command from manifest.json's build.command)
+# e.g.: node src/run-spec.ts deck.json my-deck.pptx
+
+# Render to images for visual QA
+soffice --headless --convert-to pdf --outdir . <deck>.pptx
+pdftoppm -png -r 96 <deck>.pdf <name>
+```

package/bin/bon.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node --experimental-strip-types --no-warnings
+import("../src/cli.ts");

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@tycoworks/bon",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "bon": "bin/bon.js"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tycoworks/bon-core": "^0.1.0",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,98 @@
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Config, ThemeConfig } from "@tycoworks/bon-core";
+import { generate } from "@tycoworks/bon-core";
+import { Command } from "commander";
+import { generateManifest } from "./manifest.ts";
+import { smokeSteps } from "./smoke.ts";
+
+const DEFAULT_CONFIG = "theme.config.ts";
+const DEFAULT_SMOKE_OUTPUT = "smoke-all.pptx";
+const SKILL_DIR = "skills/slides";
+const MANIFEST_FILE = "manifest.json";
+const SKILL_FILE = "SKILL.md";
+const BUILD_COMMAND = "npx bon build";
+
+const sdkDir = dirname(fileURLToPath(import.meta.url));
+const skillMdPath = resolve(sdkDir, "..", SKILL_FILE);
+
+async function loadConfig(configPath: string): Promise<Config> {
+  const abs = resolve(process.cwd(), configPath);
+  let mod: Record<string, unknown>;
+  try {
+    mod = await import(abs);
+  } catch {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+  const raw = (mod.default ?? mod.config) as ThemeConfig | undefined;
+  if (!raw) {
+    throw new Error(`${configPath} must export a default or named "config" of type ThemeConfig`);
+  }
+  return { ...raw, rootDir: dirname(abs) };
+}
+
+const program = new Command().name("bon").description("PPTX template engine CLI").version("0.1.0");
+
+program
+  .command("build")
+  .description("Build a PPTX deck from a JSON spec")
+  .argument("<deck>", "path to deck JSON file")
+  .argument("[output]", "output PPTX filename")
+  .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
+  .action(async (deckPath: string, output: string | undefined, opts: { config: string }) => {
+    const config = await loadConfig(opts.config);
+    let deck: Record<string, unknown>;
+    try {
+      const raw = readFileSync(resolve(process.cwd(), deckPath), "utf-8");
+      deck = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Failed to read deck file: ${deckPath} (${(err as Error).message})`);
+    }
+    if (output) deck.output = output;
+    await generate(deck as any, config);
+  });
+
+program
+  .command("manifest")
+  .description("Generate manifest.json from theme config")
+  .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
+  .option(`-o, --out <file>`, "write to file instead of stdout")
+  .action(async (opts: { config: string; out?: string }) => {
+    const config = await loadConfig(opts.config);
+    const json = generateManifest(config, { build: { command: BUILD_COMMAND } });
+    if (opts.out) {
+      writeFileSync(resolve(process.cwd(), opts.out), `${json}\n`);
+      console.log(`WROTE ${opts.out}`);
+    } else {
+      process.stdout.write(`${json}\n`);
+    }
+  });
+
+program
+  .command("smoke")
+  .description("Generate one smoke-test slide per layout")
+  .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
+  .option(`-o, --out <file>`, "output PPTX filename", DEFAULT_SMOKE_OUTPUT)
+  .action(async (opts: { config: string; out: string }) => {
+    const config = await loadConfig(opts.config);
+    const steps = smokeSteps(config);
+    await generate({ output: opts.out, steps }, config);
+  });
+
+program
+  .command("plugin")
+  .description("Generate plugin package (manifest.json + SKILL.md) for AI agents")
+  .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
+  .action(async (opts: { config: string }) => {
+    const config = await loadConfig(opts.config);
+    const outDir = resolve(process.cwd(), SKILL_DIR);
+    mkdirSync(outDir, { recursive: true });
+    const json = generateManifest(config, { build: { command: BUILD_COMMAND } });
+    writeFileSync(resolve(outDir, MANIFEST_FILE), `${json}\n`);
+    console.log(`WROTE ${SKILL_DIR}/${MANIFEST_FILE}`);
+    copyFileSync(skillMdPath, resolve(outDir, SKILL_FILE));
+    console.log(`WROTE ${SKILL_DIR}/${SKILL_FILE}`);
+  });
+
+await program.parseAsync(process.argv);

package/src/config.ts

@@ -0,0 +1,5 @@
+import type { ThemeConfig } from "@tycoworks/bon-core";
+
+export function defineConfig(config: ThemeConfig): ThemeConfig {
+  return config;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export type {
+  AssetCatalog,
+  AssetEntry,
+  AssetSlot,
+  Config,
+  ContentSlot,
+  Deck,
+  DeckStep,
+  Layout,
+  ParagraphSelector,
+  ThemeConfig,
+} from "@tycoworks/bon-core";
+export { AssetType, Fit, generate, SlotType } from "@tycoworks/bon-core";
+export { defineConfig } from "./config.ts";
+export type { ManifestOptions } from "./manifest.ts";
+export { generateManifest } from "./manifest.ts";
+export { smokeSteps } from "./smoke.ts";

package/src/manifest.ts

@@ -0,0 +1,106 @@
+import type { Config } from "@tycoworks/bon-core";
+
+export type ManifestOptions = {
+  build?: { command: string };
+};
+
+type ManifestContentSlot = {
+  key: string;
+  type: string;
+  limit?: { maxChars?: number; maxLines?: number; maxItems?: number };
+};
+
+type ManifestAssetSlot = {
+  key: string;
+  accepts: string;
+  required?: true;
+};
+
+type ManifestLayout = {
+  name: string;
+  description: string;
+  whenToUse: string;
+  whenNotToUse: string;
+  contentSlots: ManifestContentSlot[];
+  assetSlots: ManifestAssetSlot[];
+};
+
+type ManifestAssetEntry = {
+  path: string;
+  type: string;
+  description: string;
+  whenToUse?: string;
+};
+
+type Manifest = {
+  version: 1;
+  layouts: ManifestLayout[];
+  assets: Record<string, Record<string, ManifestAssetEntry>>;
+  build: {
+    command: string;
+    deckFormat: "json";
+    deckSchema: {
+      output: "string";
+      steps: "array of { layout, content, assets }";
+    };
+  };
+};
+
+function stripContentSlot(slot: { key: string; type: string; limit?: object }): ManifestContentSlot {
+  const result: ManifestContentSlot = { key: slot.key, type: slot.type };
+  if (slot.limit) {
+    result.limit = slot.limit;
+  }
+  return result;
+}
+
+function stripAssetSlot(slot: { key: string; accepts: string; required?: boolean }): ManifestAssetSlot {
+  const result: ManifestAssetSlot = { key: slot.key, accepts: slot.accepts };
+  if (slot.required) {
+    result.required = true;
+  }
+  return result;
+}
+
+export function generateManifest(config: Config, options?: ManifestOptions): string {
+  const layouts: ManifestLayout[] = config.layouts.map((layout) => ({
+    name: layout.name,
+    description: layout.description,
+    whenToUse: layout.whenToUse,
+    whenNotToUse: layout.whenNotToUse,
+    contentSlots: layout.contentSlots.map(stripContentSlot),
+    assetSlots: (layout.assetSlots ?? []).map(stripAssetSlot),
+  }));
+
+  const assets: Record<string, Record<string, ManifestAssetEntry>> = {};
+  for (const [category, entries] of Object.entries(config.assets)) {
+    assets[category] = {};
+    for (const [name, entry] of Object.entries(entries)) {
+      const manifestEntry: ManifestAssetEntry = {
+        path: entry.path,
+        type: entry.type,
+        description: entry.description,
+      };
+      if (entry.whenToUse) {
+        manifestEntry.whenToUse = entry.whenToUse;
+      }
+      assets[category][name] = manifestEntry;
+    }
+  }
+
+  const manifest: Manifest = {
+    version: 1,
+    layouts,
+    assets,
+    build: {
+      command: options?.build?.command ?? "npx bon build",
+      deckFormat: "json",
+      deckSchema: {
+        output: "string",
+        steps: "array of { layout, content, assets }",
+      },
+    },
+  };
+
+  return JSON.stringify(manifest, null, 2);
+}

package/src/smoke.ts

@@ -0,0 +1,34 @@
+import type { Config, DeckStep } from "@tycoworks/bon-core";
+import { SlotType } from "@tycoworks/bon-core";
+
+function pickAsset(config: Config, slot: { key: string; accepts: string }): string | undefined {
+  for (const group of Object.values(config.assets)) {
+    for (const entry of Object.values(group)) {
+      if (entry.type === slot.accepts) return entry.path;
+    }
+  }
+  return undefined;
+}
+
+export function smokeSteps(config: Config): DeckStep[] {
+  return config.layouts.map((layout) => {
+    const content: Record<string, string | string[]> = {};
+    for (const s of layout.contentSlots) {
+      if (s.type === SlotType.Prose) {
+        content[s.key] = ["Sample intro line for this block.", "- First point", "- Second point"];
+      } else if (s.type === SlotType.Lines) {
+        content[s.key] = ["Sample Name", "Sample Role, Company"];
+      } else if (s.key.includes("value")) {
+        content[s.key] = "42%";
+      } else {
+        content[s.key] = `Sample ${s.key.replace(/_/g, " ")}`;
+      }
+    }
+    const assets: Record<string, string> = {};
+    for (const a of layout.assetSlots ?? []) {
+      const path = pickAsset(config, a);
+      if (path) assets[a.key] = path;
+    }
+    return { layout: layout.name, content, assets };
+  });
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "declaration": true,
+    "declarationDir": "dist",
+    "emitDeclarationOnly": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../core" }]
+}