@tycoworks/tycoslide 0.12.0 → 0.13.1

package/README.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 theme into a self-contained <package-name>.zip
+npx tycoslide package             # regenerate the skill files + zip the theme into a self-contained <package-name>.zip
 ```
 
 ## Theme Structure
@@ -68,16 +68,18 @@ my-theme/
   assets/icons/
   theme.json
   package.json
-  skill.md          # generated by `tycoslide package`
+  SKILL.md          # generated by `tycoslide package`
   syntax.md         # generated by `tycoslide package`
-  manifest.json     # generated by `tycoslide package`
+  manifest.json     # generated by `tycoslide package` -- the theme's layouts
+  assets.json       # generated by `tycoslide package` -- the theme's picture catalog
   <package-name>.zip  # uploadable Agent Skill bundle
 ```
 
 **Template** — the PPTX file with named shapes that tycoslide fills.
 **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.
+**Manifest** — the machine-readable list of layouts, for an AI agent to read.
+**Catalog** — the machine-readable list of assets, for an AI agent to search.
 
 ## Diagrams
 

package/SKILL.md

@@ -26,7 +26,8 @@ This skill builds on-brand decks from a markdown deck file. The theme provides s
 
 | Task | Guide |
 |------|-------|
-| Discover layouts and assets | Read `manifest.json` |
+| Discover layouts | Read `manifest.json` |
+| Find a logo, illustration or icon | Search `assets.json` |
 | Write a deck (structure, slots, assets) | See [Creating Slides](#creating-slides) below |
 | Fix build errors | See [QA](#qa-required) below |
 
@@ -34,10 +35,9 @@ This skill builds on-brand decks from a markdown deck file. The theme provides s
 
 ## Layout Discovery
 
-Before writing anything, read `manifest.json`. It contains:
+Before writing anything, read `manifest.json`. It lists the theme's **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`.
 
-- **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`)
+Pictures live in `assets.json`: every logo, illustration and icon the theme offers, keyed by category and name. **Search it, do not read it whole** -- an icon set alone can run to thousands of entries. Grep for it and use the `$category.name` you find -- but **search for what the icon depicts, not what you mean by it**: a catalog is indexed by picture, so "freshness" finds nothing while `grep -i "clock" assets.json` and `grep -i "bolt"` find the icon you wanted.
 
 A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
 - **parameters** -- one value on a frontmatter line. Fill by putting a value under the parameter's key in the slide frontmatter.
@@ -89,7 +89,7 @@ A deck file has three parts:
 
 ### Slide frontmatter
 
-Every slide must have a `layout:` key. All other frontmatter keys map 1:1 to the layout's **parameters**.
+Every slide must have a `layout:` key. All other frontmatter keys map 1:1 to the layout's **parameters**. A value containing a colon-then-space must be quoted -- `title: "The change: compute on the difference"` -- or YAML reads it as a second key and the build fails.
 
 ```yaml
 ---
@@ -141,8 +141,8 @@ 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 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 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. A `leaves X% of the frame empty` warning is the opposite: the image is a different shape from the slot. Neither fails the build -- judge both from the rendered slide.
+- **Don't invent layout or asset names** -- only use layouts from `manifest.json` and assets from `assets.json`
 - **Don't leave required parameters or slots empty** -- and don't leave a placeholder logo or dummy text in an image slot you care about
 
 ---
@@ -159,7 +159,7 @@ Build the deck again ([Build](#build)) and read the output carefully. Common err
 |-------|-----|
 | `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 | Write a `::key::` region using the image slot's key, containing `![]($category.name)` from `manifest.json` |
+| An image didn't swap / placeholder remains | Write a `::key::` region using the image slot's key, containing `![]($category.name)` from `assets.json` |
 | YAML parse error | Fix the YAML syntax in the slide's frontmatter |
 | `Skipped setting relation target` | The asset image couldn't be placed; check the path and file |
 | `forbidden style directive` | Remove `style`, `classDef`, `linkStyle`, or `%%{init}` from your mermaid block -- use `class` for grouping instead |
@@ -211,7 +211,7 @@ Check for:
 For each issue, suggest a specific fix.
 
 Read: /path/to/deck.md and the rendered PNGs in the working directory
-Also read: manifest.json (for layout documentation)
+Also read: manifest.json (for layout documentation); search assets.json for pictures
 ```
 
 If the subagent finds issues, fix them and rebuild.

package/dist/cli.js

@@ -3,14 +3,14 @@ import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { buildDeck } from "./index.js";
-import { generateManifest } from "./manifest.js";
+import { ASSETS_FILE, generateAssetCatalog, generateManifest } from "./manifest.js";
 import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
-import { renameSkill, zipDir } from "./skillZip.js";
+import { renameSkill, skillPackageJson, zipDir } from "./skillZip.js";
 const DEFAULT_CONFIG = "theme.json";
 const MANIFEST_FILE = "manifest.json";
-// The theme skill is written as lowercase skill.md (copied from tycoslide's own
-// SKILL.md), so the skill folder can live at the theme repo root.
-const SKILL_FILE = "skill.md";
+// SKILL.md, uppercase: the Agent Skills format requires that exact filename at the
+// root of a skill folder, and a case-sensitive filesystem will not find any other.
+const SKILL_FILE = "SKILL.md";
 const SYNTAX_FILE = "syntax.md";
 const sdkDir = dirname(fileURLToPath(import.meta.url));
 const skillMdPath = resolve(sdkDir, "..", "SKILL.md");
@@ -60,11 +60,12 @@ program
     if (!themePkg.name) {
         throw new Error('Cannot name the skill: the theme\'s package.json has no "name" field.');
     }
-    // basename drops any npm scope, e.g. "@acme/mz-slides" -> "mz-slides".
+    // basename drops any npm scope, e.g. "@acme/acme-slides" -> "acme-slides".
     const skillName = basename(themePkg.name);
-    const manifestJson = `${generateManifest(config)}\n`;
-    writeFileSync(resolve(process.cwd(), MANIFEST_FILE), manifestJson);
+    writeFileSync(resolve(process.cwd(), MANIFEST_FILE), `${generateManifest(config)}\n`);
     console.log(`WROTE ${MANIFEST_FILE}`);
+    writeFileSync(resolve(process.cwd(), ASSETS_FILE), `${generateAssetCatalog(config)}\n`);
+    console.log(`WROTE ${ASSETS_FILE}`);
     let skillMd;
     try {
         skillMd = renameSkill(readFileSync(skillMdPath, "utf-8"), skillName);
@@ -80,8 +81,9 @@ program
     // Bundle the WHOLE theme so the skill is self-contained: unzip ->
     // `npm install` (pulls the engine + its deps) -> `npx tycoslide build`.
     const zipFile = `${skillName}.zip`;
-    const generated = [opts.config, MANIFEST_FILE, SKILL_FILE, SYNTAX_FILE];
-    writeFileSync(resolve(process.cwd(), zipFile), await zipDir(process.cwd(), skillName, config, generated));
+    const generated = [opts.config, MANIFEST_FILE, ASSETS_FILE, SKILL_FILE, SYNTAX_FILE];
+    const skillPkg = skillPackageJson(themePkg, { name: pkg.name, version: pkg.version });
+    writeFileSync(resolve(process.cwd(), zipFile), await zipDir(process.cwd(), skillName, config, generated, skillPkg));
     console.log(`WROTE ${zipFile}`);
 });
 // Everything below the CLI throws plain Errors carrying a written-for-humans

package/dist/index.d.ts

@@ -34,6 +34,6 @@ export declare function toEngineConfig(config: CompilerConfig): Config;
 export declare function buildDeck(deck: CompilerDeck, config: CompilerConfig, options?: GenerateOptions): Promise<void>;
 export type { Config, Deck, DeckStep, GenerateOptions, ImageFill, Layout, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
-export { generateManifest } from "./manifest.js";
+export { ASSETS_FILE, generateAssetCatalog, generateManifest } from "./manifest.js";
 export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, MermaidConfig, MermaidVariant, ParsedDocument, RawSlide, } from "./markdown/index.js";
 export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig } from "./markdown/index.js";

package/dist/index.js

@@ -118,6 +118,6 @@ export async function buildDeck(deck, config, options = {}) {
 // Engine — primitives-only public surface.
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
 // Authoring
-export { generateManifest } from "./manifest.js";
+export { ASSETS_FILE, generateAssetCatalog, generateManifest } from "./manifest.js";
 // Markdown / Compiler
 export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig } from "./markdown/index.js";

package/dist/manifest.d.ts

@@ -1,2 +1,7 @@
 import type { CompilerConfig } from "./markdown/types.js";
+/** Filename of the searchable asset catalog, named by the manifest that points at it. */
+export declare const ASSETS_FILE = "assets.json";
+/** The layouts document: read whole, so it carries no open-ended list. */
 export declare function generateManifest(config: CompilerConfig): string;
+/** The catalog document: searched by name, never read whole. */
+export declare function generateAssetCatalog(config: CompilerConfig): string;

package/dist/manifest.js

@@ -18,6 +18,9 @@ function stripSlot(slot) {
         result.required = true;
     return result;
 }
+/** Filename of the searchable asset catalog, named by the manifest that points at it. */
+export const ASSETS_FILE = "assets.json";
+/** The layouts document: read whole, so it carries no open-ended list. */
 export function generateManifest(config) {
     const layouts = config.layouts.map((layout) => {
         const ml = {
@@ -30,18 +33,17 @@ export function generateManifest(config) {
             ml.description = layout.description;
         return ml;
     });
+    const manifest = { layouts, assets: ASSETS_FILE };
+    return JSON.stringify(manifest, null, 2);
+}
+/** The catalog document: searched by name, never read whole. */
+export function generateAssetCatalog(config) {
     const assets = {};
     for (const [category, entries] of Object.entries(config.assets)) {
         assets[category] = {};
         for (const [name, entry] of Object.entries(entries)) {
-            const manifestEntry = {
-                path: entry.path,
-                type: entry.type,
-                description: entry.description,
-            };
-            assets[category][name] = manifestEntry;
+            assets[category][name] = { path: entry.path, type: entry.type, description: entry.description };
         }
     }
-    const manifest = { layouts, assets };
-    return JSON.stringify(manifest, null, 2);
+    return JSON.stringify(assets, null, 2);
 }

package/dist/markdown/deckCompiler.js

@@ -257,7 +257,8 @@ export async function compileDeck(doc, config) {
         const [, category, name] = match;
         const entry = assets[category]?.[name];
         if (!entry) {
-            // Every asset in the catalog is far too many to read (mz-slides has 126).
+            // Every asset in the catalog is far too many to read: a theme's icon set
+            // alone can run to thousands.
             // A known category narrows it to that category's names, which is what the
             // author is choosing between; an unknown one lists the categories instead.
             const group = assets[category];

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

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

package/dist/skillZip.d.ts

@@ -1,16 +1,35 @@
 import type { CompilerThemeConfig } from "./markdown/types.js";
 /**
- * Rewrite the `name:` value in a skill.md's leading YAML frontmatter so the
+ * Rewrite the `name:` value in a SKILL.md's leading YAML frontmatter so the
  * packaged skill is named after the consuming theme, not the source template.
  * Only the leading `---`…`---` block is touched; the body is left byte-for-byte.
  * Throws if there is no frontmatter or no `name:` line — the caller names the file.
  */
 export declare function renameSkill(md: string, name: string): string;
+/**
+ * The `package.json` a packaged skill installs from — deliberately NOT the theme's
+ * own. A theme repo's manifest is a development document: it carries the script
+ * that regenerates the skill, and lists the engine as a devDependency because the
+ * repo builds with it rather than shipping it.
+ *
+ * Copying that verbatim breaks the consumer twice. The build script runs as a
+ * postinstall inside their container, so anything it touches that is read-only
+ * fails their whole `npm install`. And under `--omit=dev` the engine is never
+ * installed, so neither the postinstall nor `npx tycoslide build` can find it.
+ *
+ * What ships instead declares only what the skill needs to RUN: the theme's own
+ * dependencies plus the engine, as runtime dependencies, and no scripts at all.
+ */
+export declare function skillPackageJson(theme: Record<string, unknown>, engine: {
+    name: string;
+    version: string;
+}): string;
 /**
  * Zip a theme into an uploadable Agent Skill archive whose entries all live
- * under a single root folder (e.g. `mz-slides/theme.json`), matching Anthropic's
+ * under a single root folder (e.g. `acme-slides/theme.json`), matching Anthropic's
  * custom-skill format. `generated` names the files the caller just wrote (the
- * config, manifest, skill.md, syntax.md). Optional support files are skipped
- * when absent; anything the config declares but that is missing is an error.
+ * config, manifest, SKILL.md, syntax.md); `packageJson` is the authored manifest
+ * from `skillPackageJson`. Optional support files are skipped when absent;
+ * anything the config declares but that is missing is an error.
  */
-export declare function zipDir(rootDir: string, folderName: string, config: CompilerThemeConfig, generated: string[]): Promise<Buffer>;
+export declare function zipDir(rootDir: string, folderName: string, config: CompilerThemeConfig, generated: string[], packageJson: string): Promise<Buffer>;

package/dist/skillZip.js

@@ -5,7 +5,7 @@ import { TEMPLATE_DIR } from "./engine/index.js";
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
 const NAME_LINE = /^name:[ \t]*.*$/m;
 /**
- * Rewrite the `name:` value in a skill.md's leading YAML frontmatter so the
+ * Rewrite the `name:` value in a SKILL.md's leading YAML frontmatter so the
  * packaged skill is named after the consuming theme, not the source template.
  * Only the leading `---`…`---` block is touched; the body is left byte-for-byte.
  * Throws if there is no frontmatter or no `name:` line — the caller names the file.
@@ -13,18 +13,47 @@ const NAME_LINE = /^name:[ \t]*.*$/m;
 export function renameSkill(md, name) {
     const block = md.match(FRONTMATTER);
     if (!block)
-        throw new Error("skill.md has no YAML frontmatter block");
+        throw new Error("SKILL.md has no YAML frontmatter block");
     if (!NAME_LINE.test(block[1]))
-        throw new Error('skill.md frontmatter has no "name:" line');
+        throw new Error('SKILL.md frontmatter has no "name:" line');
     return md.replace(block[0], block[0].replace(NAME_LINE, `name: ${name}`));
 }
+/** The manifest a packaged skill installs from, authored rather than copied. */
+const PACKAGE_JSON = "package.json";
 /**
- * Files a packaged skill needs beyond the theme's own declarations. `package.json`
- * matters most: the unzip flow is `npm install` -> `npx tycoslide build`, so it
- * restores the engine and any npm-resolved brand fonts. The lockfile is taken
- * when present so that install is reproducible.
+ * Files a packaged skill needs beyond the theme's own declarations. Only the
+ * lockfile: `package.json` is authored by `skillPackageJson` rather than taken
+ * from the theme directory.
  */
-const SUPPORT_FILES = ["package.json", "package-lock.json"];
+const SUPPORT_FILES = ["package-lock.json"];
+/**
+ * The `package.json` a packaged skill installs from — deliberately NOT the theme's
+ * own. A theme repo's manifest is a development document: it carries the script
+ * that regenerates the skill, and lists the engine as a devDependency because the
+ * repo builds with it rather than shipping it.
+ *
+ * Copying that verbatim breaks the consumer twice. The build script runs as a
+ * postinstall inside their container, so anything it touches that is read-only
+ * fails their whole `npm install`. And under `--omit=dev` the engine is never
+ * installed, so neither the postinstall nor `npx tycoslide build` can find it.
+ *
+ * What ships instead declares only what the skill needs to RUN: the theme's own
+ * dependencies plus the engine, as runtime dependencies, and no scripts at all.
+ */
+export function skillPackageJson(theme, engine) {
+    const dependencies = {
+        ...(theme.dependencies ?? {}),
+        [engine.name]: `^${engine.version}`,
+    };
+    const skill = {
+        name: theme.name,
+        version: theme.version,
+        description: theme.description,
+        private: true,
+        dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b))),
+    };
+    return `${JSON.stringify(skill, null, 2)}\n`;
+}
 /**
  * Every path a packaged theme needs, relative to `rootDir` and POSIX-separated.
  *
@@ -40,18 +69,20 @@ function skillPaths(config, generated) {
 }
 /**
  * Zip a theme into an uploadable Agent Skill archive whose entries all live
- * under a single root folder (e.g. `mz-slides/theme.json`), matching Anthropic's
+ * under a single root folder (e.g. `acme-slides/theme.json`), matching Anthropic's
  * custom-skill format. `generated` names the files the caller just wrote (the
- * config, manifest, skill.md, syntax.md). Optional support files are skipped
- * when absent; anything the config declares but that is missing is an error.
+ * config, manifest, SKILL.md, syntax.md); `packageJson` is the authored manifest
+ * from `skillPackageJson`. Optional support files are skipped when absent;
+ * anything the config declares but that is missing is an error.
  */
-export async function zipDir(rootDir, folderName, config, generated) {
+export async function zipDir(rootDir, folderName, config, generated, packageJson) {
     const zip = new JSZip();
     const folder = zip.folder(folderName);
     if (!folder)
         throw new Error(`Failed to create zip folder: ${folderName}`);
+    folder.file(PACKAGE_JSON, packageJson);
     const optional = new Set(SUPPORT_FILES);
-    let count = 0;
+    let count = 1;
     for (const rel of skillPaths(config, generated)) {
         const abs = join(rootDir, ...rel.split("/"));
         if (!existsSync(abs)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Create editable, on-brand PowerPoint slides from markdown.",
   "type": "module",
   "main": "dist/index.js",

package/syntax.md

@@ -140,7 +140,7 @@ Fill a slot by writing a `::key::` region in the body; the marker maps to the sl
 
   ![]($brand.primaryDarkWordmark)
   ```
-  The categories and names are listed in `manifest.json`. How the picture is scaled and cropped comes from the **asset's `type`** in the catalog: `icon` never enlarges past native and never crops, `image` fits the whole picture without cropping, `background` fills the frame and center-crops. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
+  The categories and names are catalogued in `assets.json`. How the picture is scaled and cropped comes from the **asset's `type`** in the catalog: `icon` never enlarges past native and never crops, `image` fits the whole picture without cropping, `background` fills the frame and center-crops. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
 
 ---