@open-assets/open-assets 0.1.12 → 0.2.0

package/README.md

@@ -10,6 +10,17 @@ Dev server and export tool for app marketing assets. Like Storybook, but for mar
 
 Design your App Store screenshots, app icons, logos, OG images, favicons, and more in HTML/CSS/SVG, preview them live in the browser, and export pixel-perfect PNGs at any size — including directly into your Xcode project.
 
+## Examples
+
+<p><img src="public/img/examples/only-recipes-icon.png" width="14" height="14" /> <a href="https://onlyrecipes.app"><strong>Only Recipes</strong></a> (<a href="examples/only-recipes">examples</a>)</p>
+<img src="public/img/examples/only-recipes.png" alt="Only Recipes screenshots" width="100%" />
+
+<p><img src="public/img/examples/cat-iq-test-icon.png" width="14" height="14" /> <a href="https://apps.apple.com/us/app/cat-iq-test/id6759520249"><strong>Cat IQ Test</strong></a> (<a href="examples/cat-iq-test">examples</a>)</p>
+<img src="public/img/examples/cat-iq-test.png" alt="Cat IQ Test screenshots" width="100%" />
+
+<p><img src="public/img/examples/no-context-icon.png" width="14" height="14" /> <a href="https://nocontextbot.com"><strong>No Context Bot</strong></a> (<a href="examples/no-context">examples</a>)</p>
+<img src="public/img/examples/no-context.png" alt="No Context Bot screenshots" width="100%" />
+
 ## Installation
 
 ```bash
@@ -48,7 +59,7 @@ Then use `oa` anywhere:
 
 ```bash
 oa dev
-oa render --all
+oa render --force
 oa init
 ```
 
@@ -101,7 +112,7 @@ Claude reads your `assets.json` and `publicDir` to understand the project struct
 
 ```bash
 # With Tailwind
-concurrently "npx @tailwindcss/cli -i src/styles.css -o dist/styles.css --watch" "npx open-assets dev"
+concurrently "npx @tailwindcss/cli -i assets/styles.css -o dist/styles.css --watch" "npx open-assets dev"
 
 # Without Tailwind
 npx open-assets dev
@@ -112,7 +123,7 @@ Opens a live preview UI at `http://localhost:3200` with zoom/pan controls and ex
 ### 4. Export
 
 ```bash
-npx open-assets render --all
+npx open-assets render --force
 ```
 
 Exports every template at every configured export size into `./exports/`, organized as `exports/{collection}/{size}/{template}.png`.
@@ -130,7 +141,7 @@ Capture real app screenshots via Playwright or XCTest, then use them inside your
 npx playwright test --project=screenshots
 
 # 2. Export marketing screenshots with those captures embedded
-npx open-assets render --all
+npx open-assets render --force
 ```
 
 Reference captured screenshots in your HTML templates:
@@ -141,7 +152,7 @@ Reference captured screenshots in your HTML templates:
 The `assets.json` `command` field stores the export command so automation tools know what to run:
 ```json
 {
-  "command": "npx open-assets render --all"
+  "command": "npx open-assets render --force"
 }
 ```
 
@@ -181,12 +192,11 @@ Render assets headlessly via the command line, without opening a browser.
 
 ```bash
 open-assets render                              # Render all collections at source size
-open-assets render --all                        # Export at EVERY configured size
+open-assets render --force                      # Export at every size, ignore cache
 open-assets render --collection screenshots     # Render a specific collection
 open-assets render --template 01-hero           # Render a single template
 open-assets render --size iphone-6.9            # Use a named export size
 open-assets render --width 1320 --height 2868   # Custom size
-open-assets render --force                      # Re-render everything, ignore cache
 open-assets render -o ./build                   # Custom output directory
 open-assets render --json                       # Output results as JSON (for CI)
 open-assets render --quiet                      # Suppress progress logs
@@ -200,8 +210,7 @@ Options:
 | `--size <name>` | — | — | Use a named export size from config |
 | `--width <px>` | — | — | Custom output width |
 | `--height <px>` | — | — | Custom output height |
-| `--all` | — | — | Export at every size defined in the config |
-| `--force` | — | — | Re-render all assets even if unchanged |
+| `-f, --force` | — | — | Export at every size and re-render all (ignores cache) |
 | `-o, --output <dir>` | `OPEN_ASSETS_OUTPUT` | `./exports` | Output directory |
 | `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--parallel <count>` | `OPEN_ASSETS_PARALLEL` | `1` | Number of parallel renders |
@@ -215,7 +224,7 @@ Options:
 open-assets render --collection screenshots --template 01-hero --size iphone-6.9
 
 # One template at all device sizes
-open-assets render --collection screenshots --template 01-hero --all
+open-assets render --collection screenshots --template 01-hero --force
 
 # All templates at one device size
 open-assets render --collection screenshots --size iphone-6.9
@@ -295,7 +304,7 @@ Your project needs a `assets.json` at its root. This file defines the collection
   "version": 1,
   "name": "My App",
   "publicDir": "public",
-  "command": "npx open-assets render --all",
+  "command": "npx open-assets render --force",
   "collections": [ ... ]
 }
 ```
@@ -321,14 +330,12 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 440, "height": 956 },
   "borderRadius": 4,
   "templates": [
-    { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
-    { "src": "src/screenshots/02-features.html", "name": "02-features", "label": "Features" }
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
+    { "src": "assets/screenshots/02-features.html", "name": "02-features", "label": "Features" }
   ],
   "export": [
     { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
-    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } }
-  ],
-  "outputs": [
+    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } },
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
   ]
 }
@@ -344,16 +351,18 @@ All collections follow the same structure. No `type` field needed.
 | `templates[].src` | string | Path to HTML/SVG file (relative to project root) |
 | `templates[].name` | string | Filename for exports (used by `--template` flag) |
 | `templates[].label` | string | Display label |
-| `export` | array | Flat array of export size definitions |
+| `export` | array | Array of export sizes and output actions |
 | `export[].name` | string | Size identifier (used by `--size` flag) |
 | `export[].label` | string | Display label |
 | `export[].size` | object | `{ width, height }` — output dimensions in pixels |
 | `export[].outFile` | string | Optional output path for this size (supports .png, .jpg) |
-| `outputs` | array | Optional post-render actions |
+| `export[].type` | string | Output action type (`xcode`, `copy-source`). Entries with `type` are post-render actions, not sizes |
 | `customExport` | object | Optional `{ defaultWidth, defaultHeight }` for custom size UI |
 
 ### Output Types
 
+Export entries with a `type` field are post-render actions (run with `--force`):
+
 | Type | Config | Description |
 |------|--------|-------------|
 | `xcode` | `{ "type": "xcode", "path": "..." }` | Render icon and write to Xcode asset catalog |
@@ -369,8 +378,8 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 440, "height": 956 },
   "borderRadius": 4,
   "templates": [
-    { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
-    { "src": "src/screenshots/02-import.html", "name": "02-import", "label": "Import" }
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
+    { "src": "assets/screenshots/02-import.html", "name": "02-import", "label": "Import" }
   ],
   "export": [
     { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
@@ -389,14 +398,12 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 1024, "height": 1024 },
   "borderRadius": 224,
   "templates": [
-    { "src": "src/icon.html", "name": "icon", "label": "App Icon" }
+    { "src": "assets/icon.html", "name": "icon", "label": "App Icon" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
     { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } },
-    { "name": "120", "label": "120px", "size": { "width": 120, "height": 120 } }
-  ],
-  "outputs": [
+    { "name": "120", "label": "120px", "size": { "width": 120, "height": 120 } },
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
   ]
 }
@@ -410,9 +417,9 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 1024, "height": 1024 },
   "borderRadius": 224,
   "templates": [
-    { "src": "src/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
-    { "src": "src/icons/concept-b.html", "name": "concept-b", "label": "Concept B" },
-    { "src": "src/icons/seasonal-winter.html", "name": "seasonal-winter", "label": "Winter" }
+    { "src": "assets/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
+    { "src": "assets/icons/concept-b.html", "name": "concept-b", "label": "Concept B" },
+    { "src": "assets/icons/seasonal-winter.html", "name": "seasonal-winter", "label": "Winter" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
@@ -428,16 +435,14 @@ All collections follow the same structure. No `type` field needed.
   "label": "Logo",
   "sourceSize": { "width": 940, "height": 940 },
   "templates": [
-    { "src": "src/logo.svg", "name": "logo", "label": "Logo" },
-    { "src": "src/logo-dark.svg", "name": "logo-dark", "label": "Dark" },
-    { "src": "src/wordmark.svg", "name": "wordmark", "label": "Wordmark" }
+    { "src": "assets/logo.svg", "name": "logo", "label": "Logo" },
+    { "src": "assets/logo-dark.svg", "name": "logo-dark", "label": "Dark" },
+    { "src": "assets/wordmark.svg", "name": "wordmark", "label": "Wordmark" }
   ],
   "export": [
     { "name": "2048", "label": "2048px", "size": { "width": 2048, "height": 2048 } },
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
-    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } }
-  ],
-  "outputs": [
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
     { "type": "copy-source", "format": "svg" }
   ]
 }
@@ -450,7 +455,7 @@ All collections follow the same structure. No `type` field needed.
   "label": "Social Cards",
   "sourceSize": { "width": 1200, "height": 630 },
   "templates": [
-    { "src": "src/og/default.html", "name": "default", "label": "Default OG" }
+    { "src": "assets/og/default.html", "name": "default", "label": "Default OG" }
   ],
   "export": [
     { "name": "og", "label": "OG Image", "size": { "width": 1200, "height": 630 } }
@@ -465,7 +470,7 @@ All collections follow the same structure. No `type` field needed.
   "label": "Favicons",
   "sourceSize": { "width": 512, "height": 512 },
   "templates": [
-    { "src": "src/favicon.html", "name": "favicon", "label": "Favicon" }
+    { "src": "assets/favicon.html", "name": "favicon", "label": "Favicon" }
   ],
   "export": [
     { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
@@ -482,7 +487,7 @@ All collections follow the same structure. No `type` field needed.
 The `render` command maintains a `assets.lock` file that stores SHA256 checksums of each source HTML/SVG file. On subsequent renders, unchanged assets are skipped automatically:
 
 ```
-$ open-assets render --all
+$ open-assets render --force
   Skipping 01-hero at 1320x2868 (unchanged)
   Rendering 03-new-screen at 1320x2868...
     → exports/screenshots/iphone-6.9/03-new-screen.png
@@ -494,7 +499,7 @@ Use `--force` to re-render everything regardless of the cache.
 
 **Limitation**: Only source HTML/SVG files are checksummed. Changes to referenced assets (images in `publicDir`, compiled Tailwind CSS) won't trigger re-renders — use `--force` when those change.
 
-Add `assets.lock` to your `.gitignore` (done automatically by `open-assets init`).
+Commit `assets.lock` to your repository so teammates and CI benefit from the cache.
 
 ## CI/CD with GitHub Actions
 
@@ -517,7 +522,7 @@ jobs:
           node-version: 20
       - run: npm ci
       - run: npx open-assets validate
-      - run: npx open-assets render --all --json --quiet
+      - run: npx open-assets render --force --json --quiet
       - uses: actions/upload-artifact@v4
         with:
           name: screenshots
@@ -544,14 +549,14 @@ jobs:
 ```
 project/
   assets.json
-  assets.lock              # Auto-generated cache (gitignored)
+  assets.lock              # Auto-generated cache (commit this)
   public/                    # Shared assets (configured via publicDir)
     logo-round.png
     social/
       youtube.svg
     screenshots/             # Real app screenshots from UI tests
       01-home.png
-  src/
+  assets/
     styles.css               # Tailwind input
     icon.html                # App icon template
     logo.svg                 # Vector logo template

package/bin/open-assets.mjs

@@ -63,7 +63,7 @@ program
 
     const { startServer } = await import("../lib/server.mjs");
     const port = parseInt(opts.port, 10);
-    startServer(projectDir, {
+    const { port: actualPort } = await startServer(projectDir, {
       port,
       host: opts.host,
       quiet: opts.quiet,
@@ -74,7 +74,8 @@ program
 
     if (opts.open) {
       const open = (await import("open")).default;
-      setTimeout(() => open(`http://${opts.host}:${port}`), 500);
+      const displayHost = opts.host === "0.0.0.0" ? "localhost" : opts.host;
+      setTimeout(() => open(`http://${displayHost}:${actualPort}`), 500);
     }
   });
 
@@ -90,8 +91,7 @@ program
   .option("--size <name>", "Use a named export size from config")
   .option("--width <px>", "Output width in pixels (custom size)")
   .option("--height <px>", "Output height in pixels (custom size)")
-  .option("--all", "Export at every size defined in the config")
-  .option("--force", "Re-render all assets even if unchanged")
+  .option("-f, --force", "Export at every size and re-render all assets (ignores cache)")
   .option("-o, --output <dir>", "Output directory (env: OPEN_ASSETS_OUTPUT)", env("OPEN_ASSETS_OUTPUT", "./exports"))
   .option("--config <path>", "Path to config file (env: OPEN_ASSETS_CONFIG)", env("OPEN_ASSETS_CONFIG", "assets.json"))
   .option("--parallel <count>", "Number of parallel renders (env: OPEN_ASSETS_PARALLEL)", env("OPEN_ASSETS_PARALLEL", "1"))
@@ -189,8 +189,9 @@ program
   .description("Validate the assets.json and check that all referenced files exist")
   .argument("[dir]", "Project directory containing assets.json", ".")
   .option("--config <path>", "Path to config file", env("OPEN_ASSETS_CONFIG", "assets.json"))
+  .option("--fix", "Interactively fix issues (e.g. remove missing templates)")
   .action(async (dir, opts) => {
-    const { loadConfig } = await import("../lib/manifest.mjs");
+    const { loadConfig, saveConfig } = await import("../lib/manifest.mjs");
     const { validateConfig } = await import("../lib/validate.mjs");
 
     const projectDir = resolve(dir);
@@ -204,7 +205,7 @@ program
 
     console.log(`\n  Validating ${opts.config}...\n`);
 
-    const { checks, errors } = validateConfig(manifest, projectDir);
+    const { checks, errors, missingTemplates, emptyCollections } = validateConfig(manifest, projectDir);
 
     for (const check of checks) {
       console.log(`  ${check.ok ? "\u2713" : "\u2717"} ${check.message}`);
@@ -215,6 +216,58 @@ program
       console.log("  All checks passed.\n");
     } else {
       console.log(`  ${errors} error(s) found.\n`);
+
+      const fixable = missingTemplates.length > 0 || emptyCollections.length > 0;
+
+      if (fixable && opts.fix) {
+        const { createInterface } = await import("readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (question) =>
+          new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim().toLowerCase())));
+
+        let changes = 0;
+
+        for (const missing of missingTemplates) {
+          const answer = await ask(
+            `  Remove template "${missing.templateSrc}" from collection "${missing.collectionId}"? (y/N) `
+          );
+          if (answer === "y" || answer === "yes") {
+            const col = manifest.collections.find((c) => c.id === missing.collectionId);
+            if (col) {
+              col.templates = col.templates.filter((t) => t.src !== missing.templateSrc);
+              changes++;
+            }
+          }
+        }
+
+        // Include collections that were already empty plus ones emptied by template removal
+        const emptyIds = new Set(emptyCollections.map((e) => e.collectionId));
+        for (const col of manifest.collections) {
+          if (!col.templates || col.templates.length === 0) {
+            emptyIds.add(col.id);
+          }
+        }
+
+        for (const collectionId of emptyIds) {
+          const answer = await ask(
+            `  Remove empty collection "${collectionId}"? (y/N) `
+          );
+          if (answer === "y" || answer === "yes") {
+            manifest.collections = manifest.collections.filter((c) => c.id !== collectionId);
+            changes++;
+          }
+        }
+
+        rl.close();
+
+        if (changes > 0) {
+          saveConfig(projectDir, opts.config, manifest);
+          console.log(`\n  Updated ${opts.config} (${changes} fix(es) applied).\n`);
+        }
+      } else if (fixable) {
+        console.log(`  Run with --fix to remove missing templates and empty collections.\n`);
+      }
+
       process.exit(1);
     }
   });

package/lib/add.mjs

@@ -150,8 +150,8 @@ const COLLECTION_PRESETS = [
       { name: "800", label: "800px", size: { width: 800, height: 800 } },
       { name: "400", label: "400px", size: { width: 400, height: 400 } },
       { name: "200", label: "200px", size: { width: 200, height: 200 } },
+      { type: "copy-source", format: "svg" },
     ],
-    outputs: [{ type: "copy-source", format: "svg" }],
   },
   {
     value: "wordmark",
@@ -169,8 +169,8 @@ const COLLECTION_PRESETS = [
       { name: "1200x400", label: "Large", size: { width: 1200, height: 400 } },
       { name: "600x200", label: "Medium", size: { width: 600, height: 200 } },
       { name: "300x100", label: "Small", size: { width: 300, height: 100 } },
+      { type: "copy-source", format: "svg" },
     ],
-    outputs: [{ type: "copy-source", format: "svg" }],
   },
   {
     value: "feature-graphic",
@@ -223,7 +223,7 @@ export async function addCollection(projectDir, configName) {
   // 1. Choose from preset or custom
   const preset = await askSelect(rl, "Choose a collection type:", COLLECTION_PRESETS);
 
-  let id, label, sourceSize, borderRadius, format, tags, exportList, outputs, templateDir, templateName, templateLabel;
+  let id, label, sourceSize, borderRadius, format, tags, exportList, templateDir, templateName, templateLabel;
 
   if (preset.value === "custom") {
     // Custom collection
@@ -256,7 +256,9 @@ export async function addCollection(projectDir, configName) {
     exportList = [
       { name: `${sourceSize.width}x${sourceSize.height}`, label: "Source Size", size: { width: sourceSize.width, height: sourceSize.height } },
     ];
-    outputs = format === "svg" ? [{ type: "copy-source", format: "svg" }] : undefined;
+    if (format === "svg") {
+      exportList.push({ type: "copy-source", format: "svg" });
+    }
     templateDir = `src/${id}` === `src/${id}` && id.includes("/") ? `src` : (sourceSize.width === sourceSize.height ? "src" : `src/${id}`);
     templateDir = `src`;
     templateName = id;
@@ -270,7 +272,6 @@ export async function addCollection(projectDir, configName) {
     format = preset.format;
     tags = preset.tags;
     exportList = preset.export;
-    outputs = preset.outputs;
     templateDir = preset.templateDir;
     templateName = preset.templateName;
     templateLabel = preset.templateLabel;
@@ -310,7 +311,6 @@ export async function addCollection(projectDir, configName) {
     ],
     export: exportList,
   };
-  if (outputs) collection.outputs = outputs;
 
   manifest.collections.push(collection);
 

package/lib/init.mjs

@@ -641,7 +641,7 @@ export async function scaffoldProject(dir) {
   console.log("  Created assets.json");
 
   // Write .gitignore
-  writeFileSync(join(dir, ".gitignore"), "dist/\nexports/\nassets.lock\nnode_modules/\n");
+  writeFileSync(join(dir, ".gitignore"), "dist/\nexports/\nnode_modules/\n");
   console.log("  Created .gitignore");
 
   console.log();

package/lib/list.mjs

@@ -1,4 +1,4 @@
-import { flatSizes } from "./manifest.mjs";
+import { flatSizes, flatOutputs } from "./manifest.mjs";
 
 /**
  * Filter collections by tag. Returns filtered array.
@@ -47,17 +47,15 @@ export function formatCollectionList(manifest, collections) {
       lines.push(`  \u2022 ${template.label || template.name} \u2192 ${template.src}`);
     }
 
-    for (const entry of col.export || []) {
+    for (const entry of flatSizes(col)) {
       lines.push(`  \u21b3 ${entry.label} (${entry.size.width}\u00d7${entry.size.height})`);
     }
 
-    if (col.outputs) {
-      for (const output of col.outputs) {
-        if (output.type === "xcode") {
-          lines.push(`  \u21b3 Xcode: ${output.path}`);
-        } else if (output.type === "copy-source") {
-          lines.push(`  \u21b3 Copy source: ${output.format}`);
-        }
+    for (const output of flatOutputs(col)) {
+      if (output.type === "xcode") {
+        lines.push(`  \u21b3 Xcode: ${output.path}`);
+      } else if (output.type === "copy-source") {
+        lines.push(`  \u21b3 Copy source: ${output.format}`);
       }
     }
   }

package/lib/lockfile.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, existsSync } from "fs";
 import { createHash } from "crypto";
-import { resolve, join } from "path";
+import { resolve, join, dirname } from "path";
 
 const LOCK_FILENAME = "assets.lock";
 
@@ -27,13 +27,64 @@ export function writeLockfile(projectDir, lockData) {
   writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + "\n");
 }
 
+/**
+ * Extract local file dependencies referenced by an HTML file.
+ * Parses src="...", href="...", and url(...) references, filtering out
+ * remote URLs and returning only paths that exist on disk.
+ * Returns a sorted, deduplicated array of absolute paths.
+ */
+export function extractLocalDeps(filePath) {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf-8");
+  const dir = dirname(filePath);
+
+  const refs = new Set();
+  const srcHrefPattern = /(?:src|href)=["']([^"']+)["']/gi;
+  const cssUrlPattern = /url\(["']?([^"')]+)["']?\)/gi;
+
+  for (const pattern of [srcHrefPattern, cssUrlPattern]) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      refs.add(match[1]);
+    }
+  }
+
+  const localPaths = [];
+  for (const ref of refs) {
+    if (/^(https?:\/\/|data:|\/\/|#)/.test(ref)) continue;
+    if (!ref) continue;
+    const abs = resolve(dir, ref);
+    if (existsSync(abs)) {
+      localPaths.push(abs);
+    }
+  }
+
+  return [...new Set(localPaths)].sort();
+}
+
 /**
  * Compute SHA256 checksum of a file's contents.
+ * For .html files, includes the content of all local dependencies
+ * (images, SVGs, etc.) referenced via src/href/url() attributes.
  * Returns "sha256:<hex>" or null if file doesn't exist.
  */
 export function computeChecksum(filePath) {
   if (!existsSync(filePath)) return null;
   const content = readFileSync(filePath);
+
+  if (filePath.endsWith(".html")) {
+    const deps = extractLocalDeps(filePath);
+    if (deps.length > 0) {
+      const hash = createHash("sha256");
+      hash.update(content);
+      for (const dep of deps) {
+        hash.update("\0");
+        hash.update(readFileSync(dep));
+      }
+      return `sha256:${hash.digest("hex")}`;
+    }
+  }
+
   const hash = createHash("sha256").update(content).digest("hex");
   return `sha256:${hash}`;
 }

package/lib/manifest.mjs

@@ -2,10 +2,17 @@ import { existsSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 
 /**
- * Get all export sizes from a collection.
+ * Get all export sizes from a collection (entries without a type field).
  */
 export function flatSizes(collection) {
-  return collection.export || [];
+  return (collection.export || []).filter((e) => !e.type);
+}
+
+/**
+ * Get all output actions from a collection (entries with a type field).
+ */
+export function flatOutputs(collection) {
+  return (collection.export || []).filter((e) => e.type);
 }
 
 /**
@@ -77,7 +84,7 @@ export function filterTemplates(templates, templateName) {
 /**
  * Determine which sizes to render for a collection given CLI options.
  * @param {object} collection - The collection from the config
- * @param {{ width?: string|number, height?: string|number, size?: string, all?: boolean, platform?: string }} opts
+ * @param {{ width?: string|number, height?: string|number, size?: string, force?: boolean, platform?: string }} opts
  * @returns {{ sizes: object[], warning?: string }}
  */
 export function resolveRenderSizes(collection, opts = {}) {
@@ -109,7 +116,7 @@ export function resolveRenderSizes(collection, opts = {}) {
     };
   }
 
-  if (opts.all) {
+  if (opts.force) {
     const sizes = flatSizes(collection);
     return { sizes };
   }

package/lib/render.mjs

@@ -1,6 +1,6 @@
 import { resolve, join } from "path";
 import { mkdirSync, writeFileSync, copyFileSync, existsSync } from "fs";
-import { filterCollections, filterTemplates, resolveRenderSizes } from "./manifest.mjs";
+import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } from "./manifest.mjs";
 
 /**
  * @typedef {object} RenderDeps
@@ -27,8 +27,7 @@ import { filterCollections, filterTemplates, resolveRenderSizes } from "./manife
  * @param {string} [options.format] - Output format override (png or jpg)
  * @param {string|number} [options.width] - Custom width
  * @param {string|number} [options.height] - Custom height
- * @param {boolean} [options.all] - Export at all sizes
- * @param {boolean} [options.force] - Re-render even if unchanged
+ * @param {boolean} [options.force] - Export at all sizes and re-render (ignores cache)
  * @param {string} [options.output] - Output directory path
  * @param {boolean} [options.quiet] - Suppress logs
  * @param {RenderDeps} deps - Injected dependencies
@@ -67,7 +66,7 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
       width: options.width,
       height: options.height,
       size: options.size,
-      all: options.all,
+      force: options.force,
     });
 
     if (warning) {
@@ -80,7 +79,11 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
       continue;
     }
 
-    const useSubDirs = sizesToRender.length > 1 || options.all;
+    const singleTemplate = templates.length === 1;
+    const multipleSizes = sizesToRender.length > 1 || options.force;
+    // Single-template collections use flat layout with entry.name as filename
+    // Multi-template collections use subdirs per size
+    const useSubDirs = multipleSizes && !singleTemplate;
 
     for (const entry of sizesToRender) {
       const w = entry.size.width;
@@ -103,9 +106,15 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
         const format = outExt === "jpg" || outExt === "jpeg" ? "jpeg" : "png";
         const defaultExt = format === "jpeg" ? "jpg" : "png";
 
+        // Single-template: use entry.name as filename (e.g. logo-1024.png)
+        // Multi-template: use template.name as filename (e.g. 01-hero.png)
+        const fileName = singleTemplate && multipleSizes
+          ? `${entry.name}.${defaultExt}`
+          : `${template.name}.${defaultExt}`;
+
         const outPath = entry.outFile
           ? resolve(projectDir, entry.outFile.replace(/\{template\}/g, template.name))
-          : join(sizeDir, `${template.name}.${defaultExt}`);
+          : join(sizeDir, fileName);
 
         const assetKey = `${col.id}/${template.name}`;
         const variantKey = entry.name;
@@ -146,7 +155,7 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
           h,
           sourceW,
           sourceH,
-          { format }
+          { format, background: col.background }
         );
         writeFileSync(outPath, buffer);
         results.push({
@@ -165,30 +174,34 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
     }
 
     // Handle outputs (xcode, copy-source, etc.)
-    if (col.outputs && options.all) {
-      for (const output of col.outputs) {
+    const outputs = flatOutputs(col);
+    if (outputs.length > 0 && options.force) {
+      for (const output of outputs) {
         if (output.type === "xcode") {
           _log(`\n  Exporting to Xcode: ${output.path}`);
           const path = await deps.runXcodeOutput(projectDir, col, output);
           results.push({ collection: col.id, type: "xcode", path });
         } else if (output.type === "copy-source") {
           const format = output.format || "svg";
-          const copyDir = join(outputDir, col.id, format);
+          const copyDir = join(outputDir, col.id);
           mkdirSync(copyDir, { recursive: true });
-          for (const template of templates) {
-            if (template.src.endsWith(`.${format}`)) {
-              const srcPath = resolve(projectDir, template.src);
-              const destPath = join(copyDir, `${template.name}.${format}`);
-              if (existsSync(srcPath)) {
-                copyFileSync(srcPath, destPath);
-                results.push({
-                  collection: col.id,
-                  template: template.name,
-                  type: `copy-${format}`,
-                  path: destPath,
-                });
-                _log(`    → ${destPath}`);
-              }
+          const matchingTemplates = templates.filter((t) => t.src.endsWith(`.${format}`));
+          for (const template of matchingTemplates) {
+            const srcPath = resolve(projectDir, template.src);
+            // Use entry name when single match, template name when multiple
+            const baseName = output.name && matchingTemplates.length === 1
+              ? output.name
+              : template.name;
+            const destPath = join(copyDir, `${baseName}.${format}`);
+            if (existsSync(srcPath)) {
+              copyFileSync(srcPath, destPath);
+              results.push({
+                collection: col.id,
+                template: template.name,
+                type: `copy-${format}`,
+                path: destPath,
+              });
+              _log(`    → ${destPath}`);
             }
           }
         }

package/lib/renderer.mjs

@@ -1,6 +1,6 @@
 import { launch } from "puppeteer";
 import { resolve } from "path";
-import { writeFileSync, mkdirSync } from "fs";
+import { writeFileSync, mkdirSync, readdirSync, unlinkSync } from "fs";
 
 let browser = null;
 
@@ -27,7 +27,7 @@ export async function closeBrowser() {
  * @param {number} height
  * @param {number} sourceW
  * @param {number} sourceH
- * @param {{ format?: "png"|"jpeg", quality?: number }} [options]
+ * @param {{ format?: "png"|"jpeg", quality?: number, background?: string }} [options]
  */
 export async function renderScreenshot(
   projectDir,
@@ -56,11 +56,22 @@ export async function renderScreenshot(
     await new Promise((r) => setTimeout(r, 200));
   }
 
+  // Handle background: transparent by default for PNG, or use specified color
+  const bg = options.background;
+  if (bg) {
+    await page.evaluate((color) => {
+      document.documentElement.style.backgroundColor = color;
+    }, bg);
+  }
+
   const format = options.format || "png";
   const screenshotOpts = {
     type: format,
     clip: { x: 0, y: 0, width, height },
   };
+  if (format === "png" && !bg) {
+    screenshotOpts.omitBackground = true;
+  }
   if (format === "jpeg" && options.quality) {
     screenshotOpts.quality = options.quality;
   }
@@ -82,14 +93,39 @@ export async function runXcodeOutput(projectDir, collection, outputConfig) {
 
   const outputDir = resolve(projectDir, outputConfig.path);
   mkdirSync(outputDir, { recursive: true });
-  const outputPath = resolve(outputDir, "AppIcon.png");
 
   const sw = collection.sourceSize.width;
   const sh = collection.sourceSize.height;
+  const filename = "AppIcon.png";
+  const outputPath = resolve(outputDir, filename);
+
+  // Remove stale images that don't match the current output filename
+  for (const entry of readdirSync(outputDir)) {
+    if (entry !== filename && /\.(png|jpg|jpeg)$/i.test(entry)) {
+      unlinkSync(resolve(outputDir, entry));
+    }
+  }
 
   const buffer = await renderScreenshot(projectDir, template.src, sw, sh, sw, sh);
   writeFileSync(outputPath, buffer);
 
+  const contentsJson = {
+    images: [
+      {
+        filename,
+        idiom: "universal",
+        platform: "ios",
+        size: `${sw}x${sh}`,
+      },
+    ],
+    info: {
+      author: "xcode",
+      version: 1,
+    },
+  };
+  const contentsPath = resolve(outputDir, "Contents.json");
+  writeFileSync(contentsPath, JSON.stringify(contentsJson, null, 2) + "\n");
+
   console.log(`Updated: ${outputPath}`);
   return outputPath;
 }

package/lib/server.mjs

@@ -146,7 +146,7 @@ export async function startServer(projectDir, options = {}, renderer) {
     // API: render screenshot (unified for all collection types)
     if (req.method === "POST" && pathname === "/api/render-screenshot") {
       try {
-        const { file, width, height, sourceW, sourceH } = JSON.parse(
+        const { file, width, height, sourceW, sourceH, background } = JSON.parse(
           await readBody(req)
         );
         if (!file || !width || !height) {
@@ -158,7 +158,7 @@ export async function startServer(projectDir, options = {}, renderer) {
         const sw = sourceW || width;
         const sh = sourceH || height;
         log(`Rendering ${file} at ${width}x${height} (source ${sw}x${sh})...`);
-        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh);
+        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, { background });
         res.writeHead(200, {
           "Content-Type": "image/png",
           "Content-Length": buffer.length,
@@ -181,7 +181,8 @@ export async function startServer(projectDir, options = {}, renderer) {
           res.writeHead(404, { "Content-Type": "application/json" });
           return res.end(JSON.stringify({ ok: false, error: "Collection not found" }));
         }
-        const output = col.outputs?.[outputIndex || 0];
+        const outputs = (col.export || []).filter((e) => e.type);
+        const output = outputs[outputIndex || 0];
         if (!output) {
           res.writeHead(404, { "Content-Type": "application/json" });
           return res.end(JSON.stringify({ ok: false, error: "Output not found" }));
@@ -245,30 +246,50 @@ export async function startServer(projectDir, options = {}, renderer) {
     res.end();
   });
 
-  server.listen(port, host, () => {
-    log();
-    log(`  open-assets dev server`);
-    log(`  ───────────────────────`);
-    log(`  Local:   http://${host}:${port}`);
-    if (host === "0.0.0.0") {
-      log(`  Network: http://<your-ip>:${port}`);
-    }
-    log(`  Project: ${projectDir}`);
-    if (staticDirs.length > 0) {
-      log(`  Static:  ${staticDirs.join(", ")}`);
-    }
-    log();
-  });
+  const maxRetries = 10;
+  let currentPort = port;
+  let resolved = false;
+
+  const actualPort = await new Promise((resolvePort) => {
+    function tryListen() {
+      server.once("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+          if (currentPort - port >= maxRetries) {
+            console.error(`Error: Ports ${port}–${currentPort} are all in use.`);
+            process.exit(1);
+          }
+          currentPort++;
+          server.close(() => tryListen());
+          return;
+        }
+        throw err;
+      });
 
-  server.on("error", (err) => {
-    if (err.code === "EADDRINUSE") {
-      console.error(`Error: Port ${port} is already in use.`);
-      console.error(`Try a different port: open-assets dev --port ${port + 1}`);
-      process.exit(1);
+      server.listen(currentPort, host, () => {
+        if (resolved) return;
+        resolved = true;
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        if (currentPort !== port) {
+          log();
+          log(`  Port ${port} is in use, using ${currentPort} instead.`);
+        }
+        log();
+        log(`  Open Assets is running on http://${displayHost}:${currentPort}`);
+        log();
+        log(`  Project: ${projectDir}`);
+        if (staticDirs.length > 0) {
+          log(`  Static:  ${staticDirs.join(", ")}`);
+        }
+        log();
+        resolvePort(currentPort);
+      });
     }
-    throw err;
+
+    tryListen();
   });
 
+  return { port: actualPort };
+
   function cleanup() {
     for (const w of watchers) w.close();
     for (const client of sseClients) client.end();

package/lib/validate.mjs

@@ -1,6 +1,6 @@
 import { existsSync } from "fs";
 import { resolve } from "path";
-import { flatSizes } from "./manifest.mjs";
+import { flatSizes, flatOutputs } from "./manifest.mjs";
 
 /**
  * Validate a config object and check that referenced files exist.
@@ -12,6 +12,8 @@ import { flatSizes } from "./manifest.mjs";
  */
 export function validateConfig(manifest, projectDir) {
   const checks = [];
+  const missingTemplates = [];
+  const emptyCollections = [];
   let errors = 0;
 
   const ok = (msg) => checks.push({ ok: true, message: msg });
@@ -31,7 +33,7 @@ export function validateConfig(manifest, projectDir) {
     ok(`${manifest.collections.length} collection(s) defined`);
   } else {
     fail("Missing or empty 'collections' array");
-    return { checks, errors };
+    return { checks, errors, missingTemplates, emptyCollections };
   }
 
   // Check each collection
@@ -54,6 +56,7 @@ export function validateConfig(manifest, projectDir) {
 
     if (!col.templates || col.templates.length === 0) {
       fail(`Collection "${col.id}" has no templates`);
+      emptyCollections.push({ collectionId: col.id });
     } else {
       for (const template of col.templates) {
         if (!template.src) {
@@ -65,6 +68,11 @@ export function validateConfig(manifest, projectDir) {
           ok(`${template.src} exists`);
         } else {
           fail(`${template.src} not found`);
+          missingTemplates.push({
+            collectionId: col.id,
+            templateSrc: template.src,
+            templateName: template.name || template.label,
+          });
         }
       }
     }
@@ -74,17 +82,12 @@ export function validateConfig(manifest, projectDir) {
       ok(`Collection "${col.id}" has ${sizes.length} export size(s)`);
     }
 
-    // Validate outputs
-    if (col.outputs) {
-      for (const output of col.outputs) {
-        if (!output.type) {
-          fail(`Collection "${col.id}" has an output without 'type'`);
-        } else {
-          ok(`Output: ${output.type}`);
-        }
-      }
+    // Validate outputs (export entries with a type field)
+    const outputs = flatOutputs(col);
+    for (const output of outputs) {
+      ok(`Output: ${output.type}`);
     }
   }
 
-  return { checks, errors };
+  return { checks, errors, missingTemplates, emptyCollections };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-assets/open-assets",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "Dev server and export tool for app screenshots, icons, and logos. Like Storybook for marketing assets.",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "scripts": {
-    "assets": "node bin/open-assets.mjs render --all -o ./public/img",
+    "assets": "node bin/open-assets.mjs render --force -o ./public/img",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "release": "./scripts/release.sh"
   },

package/public/viewer.html

@@ -254,46 +254,46 @@
         const sh = col.sourceSize.height;
         const hasMultipleTemplates = col.templates.length > 1;
 
-        // Outputs (e.g., Xcode)
-        if (col.outputs) {
-          for (let i = 0; i < col.outputs.length; i++) {
-            const output = col.outputs[i];
-            if (output.type === 'xcode') {
-              const sectionLabel = document.createElement('div');
-              sectionLabel.className = 'section-label';
-              sectionLabel.textContent = 'Xcode';
-              exportDropdown.appendChild(sectionLabel);
-
-              const btn = document.createElement('button');
-              btn.innerHTML = 'Export to Xcode <span class="dim">.appiconset</span>';
-              btn.addEventListener('click', () => runOutput(col.id, i));
-              exportDropdown.appendChild(btn);
-
-              exportDropdown.appendChild(document.createElement('hr'));
-            } else if (output.type === 'copy-source') {
-              const sectionLabel = document.createElement('div');
-              sectionLabel.className = 'section-label';
-              sectionLabel.textContent = output.format.toUpperCase();
-              exportDropdown.appendChild(sectionLabel);
-
-              // SVG download for each template
-              for (const template of col.templates) {
-                if (template.src.endsWith('.' + output.format)) {
-                  const btn = document.createElement('button');
-                  const displayName = hasMultipleTemplates ? template.label : `Download ${output.format.toUpperCase()}`;
-                  btn.innerHTML = `${displayName} <span class="dim">${output.format}</span>`;
-                  btn.addEventListener('click', () => downloadSource(template));
-                  exportDropdown.appendChild(btn);
-                }
+        // Outputs (e.g., Xcode, copy-source) — export entries with a type field
+        const allExports = col.export || [];
+        const outputs = allExports.filter(e => e.type);
+        for (let i = 0; i < outputs.length; i++) {
+          const output = outputs[i];
+          if (output.type === 'xcode') {
+            const sectionLabel = document.createElement('div');
+            sectionLabel.className = 'section-label';
+            sectionLabel.textContent = 'Xcode';
+            exportDropdown.appendChild(sectionLabel);
+
+            const btn = document.createElement('button');
+            btn.innerHTML = 'Export to Xcode <span class="dim">.appiconset</span>';
+            btn.addEventListener('click', () => runOutput(col.id, i));
+            exportDropdown.appendChild(btn);
+
+            exportDropdown.appendChild(document.createElement('hr'));
+          } else if (output.type === 'copy-source') {
+            const sectionLabel = document.createElement('div');
+            sectionLabel.className = 'section-label';
+            sectionLabel.textContent = output.format.toUpperCase();
+            exportDropdown.appendChild(sectionLabel);
+
+            // SVG download for each template
+            for (const template of col.templates) {
+              if (template.src.endsWith('.' + output.format)) {
+                const btn = document.createElement('button');
+                const displayName = hasMultipleTemplates ? template.label : `Download ${output.format.toUpperCase()}`;
+                btn.innerHTML = `${displayName} <span class="dim">${output.format}</span>`;
+                btn.addEventListener('click', () => downloadSource(template));
+                exportDropdown.appendChild(btn);
               }
-
-              exportDropdown.appendChild(document.createElement('hr'));
             }
+
+            exportDropdown.appendChild(document.createElement('hr'));
           }
         }
 
-        // Export sizes
-        const sizes = col.export || [];
+        // Export sizes (entries without a type field)
+        const sizes = allExports.filter(e => !e.type);
         if (sizes.length > 0) {
           const sectionLabel = document.createElement('div');
           sectionLabel.className = 'section-label';

package/skills/open-assets/SKILL.md

@@ -15,14 +15,13 @@ open-assets is a dev server and export tool for app marketing assets — screens
 open-assets dev
 
 # Or with Tailwind
-concurrently "npx @tailwindcss/cli -i src/styles.css -o dist/styles.css --watch" "open-assets dev"
+concurrently "npx @tailwindcss/cli -i assets/styles.css -o dist/styles.css --watch" "open-assets dev"
 
 # Headless render
 open-assets render --collection screenshots --size iphone-6.9
-open-assets render --collection icon --all
-open-assets render --all
-open-assets render --template 01-hero --all
-open-assets render --force  # ignore cache, re-render everything
+open-assets render --collection icon --force
+open-assets render --force
+open-assets render --template 01-hero --force
 ```
 
 ## Concepts
@@ -44,7 +43,7 @@ The `assets.json` at the project root defines all asset collections. All collect
   "version": 1,
   "name": "App Display Name",
   "publicDir": "public",
-  "command": "npx open-assets render --all",
+  "command": "npx open-assets render --force",
   "collections": [
     {
       "id": "unique-id",
@@ -52,12 +51,11 @@ The `assets.json` at the project root defines all asset collections. All collect
       "sourceSize": { "width": 440, "height": 956 },
       "borderRadius": 4,
       "templates": [
-        { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" }
+        { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" }
       ],
       "export": [
         { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } }
       ],
-      "outputs": [],
       "customExport": { "defaultWidth": 1320, "defaultHeight": 2868 }
     }
   ]
@@ -73,12 +71,13 @@ The `assets.json` at the project root defines all asset collections. All collect
 | `sourceSize` | object | `{ width, height }` — dimensions templates are authored at |
 | `borderRadius` | number | Border radius for preview frames (px) |
 | `templates` | array | Source files: `{ src, name, label }` |
-| `export` | array | Export sizes: `[{ name, label, size: { width, height }, outFile? }]` |
-| `outputs` | array | Post-render actions (optional) |
+| `export` | array | Export sizes and output actions. Entries with a `type` field are post-render actions |
 | `customExport` | object | Custom size defaults for UI (optional) |
 
 ### Output Types
 
+Export entries with a `type` field are post-render actions (run with `--force`):
+
 | Type | Config | Description |
 |------|--------|-------------|
 | `xcode` | `{ "type": "xcode", "path": "..." }` | Render icon and write to Xcode asset catalog |
@@ -94,8 +93,8 @@ The `assets.json` at the project root defines all asset collections. All collect
   "sourceSize": { "width": 440, "height": 956 },
   "borderRadius": 4,
   "templates": [
-    { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
-    { "src": "src/screenshots/02-features.html", "name": "02-features", "label": "Features" }
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
+    { "src": "assets/screenshots/02-features.html", "name": "02-features", "label": "Features" }
   ],
   "export": [
     { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
@@ -112,13 +111,13 @@ The `assets.json` at the project root defines all asset collections. All collect
   "sourceSize": { "width": 1024, "height": 1024 },
   "borderRadius": 224,
   "templates": [
-    { "src": "src/icon.html", "name": "icon", "label": "App Icon" }
+    { "src": "assets/icon.html", "name": "icon", "label": "App Icon" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
-    { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } }
-  ],
-  "outputs": [{ "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }]
+    { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } },
+    { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
+  ]
 }
 ```
 
@@ -130,8 +129,8 @@ The `assets.json` at the project root defines all asset collections. All collect
   "sourceSize": { "width": 1024, "height": 1024 },
   "borderRadius": 224,
   "templates": [
-    { "src": "src/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
-    { "src": "src/icons/concept-b.html", "name": "concept-b", "label": "Concept B" }
+    { "src": "assets/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
+    { "src": "assets/icons/concept-b.html", "name": "concept-b", "label": "Concept B" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } }
@@ -146,14 +145,14 @@ The `assets.json` at the project root defines all asset collections. All collect
   "label": "Logo",
   "sourceSize": { "width": 940, "height": 940 },
   "templates": [
-    { "src": "src/logo.svg", "name": "logo", "label": "Logo" },
-    { "src": "src/logo-dark.svg", "name": "logo-dark", "label": "Dark" }
+    { "src": "assets/logo.svg", "name": "logo", "label": "Logo" },
+    { "src": "assets/logo-dark.svg", "name": "logo-dark", "label": "Dark" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
-    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } }
-  ],
-  "outputs": [{ "type": "copy-source", "format": "svg" }]
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
+    { "type": "copy-source", "format": "svg" }
+  ]
 }
 ```
 
@@ -164,7 +163,7 @@ The `assets.json` at the project root defines all asset collections. All collect
   "label": "Social Cards",
   "sourceSize": { "width": 1200, "height": 630 },
   "templates": [
-    { "src": "src/og/default.html", "name": "default", "label": "Default OG" }
+    { "src": "assets/og/default.html", "name": "default", "label": "Default OG" }
   ],
   "export": [
     { "name": "og", "label": "OG Image", "size": { "width": 1200, "height": 630 } }
@@ -181,7 +180,7 @@ The `assets.json` at the project root defines all asset collections. All collect
 | `open-assets dev [dir]` | Start dev server with live preview and export UI |
 | `open-assets render [dir]` | Render assets headlessly via CLI |
 | `open-assets list [dir]` | List all collections and templates in the config |
-| `open-assets validate [dir]` | Validate assets.json and check referenced files exist |
+| `open-assets validate [dir]` | Validate assets.json and check referenced files exist. Use `--fix` to interactively remove missing templates |
 | `open-assets init [dir]` | Scaffold a new assets.json and example assets |
 | `open-assets add collection [dir]` | Add a new collection (from presets or custom) |
 | `open-assets add template [dir]` | Add a new template to an existing collection |
@@ -195,15 +194,14 @@ The `assets.json` at the project root defines all asset collections. All collect
 | `--collection <id>` | Render only the collection with this ID |
 | `--template <name>` | Render only the template with this name |
 | `--size <name>` | Use a named export size from config |
-| `--all` | Export at every size defined in the config |
-| `--force` | Re-render all assets even if unchanged |
+| `-f, --force` | Export at every size and re-render all (ignores cache) |
 | `-o, --output <dir>` | Output directory (default: `./exports`) |
 | `--json` | Output results as JSON |
 | `-q, --quiet` | Suppress progress logs |
 
 Flags compose naturally:
 - `--collection screenshots --template 01-hero --size iphone-6.9` → single template, single size
-- `--collection screenshots --template 01-hero --all` → one template, all sizes
+- `--collection screenshots --template 01-hero --force` → one template, all sizes
 - `--collection screenshots --size iphone-6.9` → all templates, one size
 
 ### add commands
@@ -342,14 +340,14 @@ Note: only source HTML/SVG files are checksummed. Changes to referenced assets (
 ```
 project/
   assets.json
-  assets.lock          # Auto-generated, add to .gitignore
+  assets.lock          # Auto-generated cache (commit this)
   public/                # Shared assets (images, logos, icons, photos)
     logo-round.png
     social/
       youtube.svg
     screenshots/         # Real app screenshots for use in templates
       01.png
-  src/
+  assets/
     styles.css           # Tailwind input
     icon.html            # App icon template
     icons/               # Icon concept explorations