@ncukondo/slide-generation 0.3.0 → 0.4.0

package/dist/cli/index.js

@@ -941,7 +941,7 @@ var ReferenceManager = class {
     return map;
   }
   execCommand(cmd) {
-    return new Promise((resolve7, reject) => {
+    return new Promise((resolve8, reject) => {
       exec(cmd, (error, stdout) => {
         if (error) {
           reject(
@@ -949,7 +949,7 @@ var ReferenceManager = class {
           );
           return;
         }
-        resolve7(stdout.toString());
+        resolve8(stdout.toString());
       });
     });
   }
@@ -1688,7 +1688,7 @@ var Pipeline = class {
 };
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 
 // src/cli/commands/convert.ts
 import { Command } from "commander";
@@ -3337,8 +3337,8 @@ import { tmpdir as tmpdir2 } from "os";
 
 // src/cli/commands/preview.ts
 import { Command as Command3 } from "commander";
-import { access as access6, unlink as unlink2, readdir as readdir4, mkdir as mkdir2, writeFile as writeFile2, readFile as readFile10, rm } from "fs/promises";
-import { basename as basename4, dirname as dirname4, join as join9, extname as extname2 } from "path";
+import { access as access6, readdir as readdir4, mkdir as mkdir2, writeFile as writeFile2, readFile as readFile10, rm } from "fs/promises";
+import { basename as basename4, dirname as dirname5, join as join9, extname as extname2 } from "path";
 import * as path6 from "path";
 import { tmpdir } from "os";
 import { createServer } from "http";
@@ -3347,16 +3347,24 @@ import { watch as chokidarWatch } from "chokidar";
 
 // src/cli/utils/marp-runner.ts
 import { existsSync } from "fs";
-import { join as join8 } from "path";
+import { join as join8, resolve, dirname as dirname4 } from "path";
 import {
   execFileSync,
   spawn
 } from "child_process";
 function getMarpCommand(projectDir) {
-  const dir = projectDir ?? process.cwd();
-  const localMarp = join8(dir, "node_modules", ".bin", "marp");
-  if (existsSync(localMarp)) {
-    return localMarp;
+  const startDir = resolve(projectDir ?? process.cwd());
+  let currentDir = startDir;
+  while (true) {
+    const localMarp = join8(currentDir, "node_modules", ".bin", "marp");
+    if (existsSync(localMarp)) {
+      return localMarp;
+    }
+    const parentDir = dirname4(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
   }
   try {
     execFileSync("marp", ["--version"], { stdio: "ignore", timeout: 5e3 });
@@ -3513,23 +3521,19 @@ async function collectSlideInfo(dir, baseName, format) {
 async function checkMarpCliAvailable(projectDir) {
   return isMarpAvailable(projectDir);
 }
-function getTempOutputPath(inputPath) {
+function getTempPreviewDir(inputPath) {
   const base = basename4(inputPath, ".yaml");
-  return join9(tmpdir(), `slide-gen-preview-${base}-${Date.now()}.md`);
+  return join9(tmpdir(), `slide-gen-preview-${base}-${Date.now()}`);
 }
-function buildMarpCommand(markdownPath, options) {
-  const parts = ["marp", "--preview"];
-  if (options.port) {
-    parts.push("-p", String(options.port));
-  }
+function buildMarpCommand(markdownDir, options) {
+  const parts = ["marp", "--server", "-I", markdownDir];
   if (options.watch) {
     parts.push("--watch");
   }
-  parts.push(markdownPath);
   return parts.join(" ");
 }
 function startStaticServer(baseDir, port, options = {}) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const mimeTypes = {
       ".html": "text/html",
       ".png": "image/png",
@@ -3566,7 +3570,7 @@ function startStaticServer(baseDir, port, options = {}) {
         const prefix = options.messagePrefix ?? "Server";
         console.log(`${prefix} running at ${chalk3.cyan(url)}`);
       }
-      resolve7(server);
+      resolve8(server);
     });
   });
 }
@@ -3583,7 +3587,7 @@ async function executeGalleryPreview(inputPath, options) {
     return { success: false, errors };
   }
   console.log("Checking for Marp CLI...");
-  const projectDir = dirname4(inputPath);
+  const projectDir = dirname5(inputPath);
   const marpAvailable = await checkMarpCliAvailable(projectDir);
   if (!marpAvailable) {
     console.error(
@@ -3600,7 +3604,7 @@ async function executeGalleryPreview(inputPath, options) {
   const configLoader = new ConfigLoader();
   let configPath = options.config;
   if (!configPath) {
-    configPath = await configLoader.findConfig(dirname4(inputPath));
+    configPath = await configLoader.findConfig(dirname5(inputPath));
   }
   const config = await configLoader.load(configPath);
   console.log("Initializing pipeline...");
@@ -3698,11 +3702,11 @@ Showing ${slides.length} slides in gallery mode`);
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve7) => {
+  await new Promise((resolve8) => {
     if (options.signal) {
-      options.signal.addEventListener("abort", () => resolve7());
+      options.signal.addEventListener("abort", () => resolve8());
     }
-    server.on("close", () => resolve7());
+    server.on("close", () => resolve8());
   });
   return { success: true, errors };
 }
@@ -3736,7 +3740,7 @@ async function executePreview(inputPath, options) {
     return { success: false, errors };
   }
   console.log("Checking for Marp CLI...");
-  const marpAvailable = await checkMarpCliAvailable(dirname4(inputPath));
+  const marpAvailable = await checkMarpCliAvailable(dirname5(inputPath));
   if (!marpAvailable) {
     console.error(
       chalk3.red(
@@ -3751,7 +3755,7 @@ async function executePreview(inputPath, options) {
   const configLoader = new ConfigLoader();
   let configPath = options.config;
   if (!configPath) {
-    configPath = await configLoader.findConfig(dirname4(inputPath));
+    configPath = await configLoader.findConfig(dirname5(inputPath));
   }
   const config = await configLoader.load(configPath);
   console.log("Initializing pipeline...");
@@ -3765,7 +3769,9 @@ async function executePreview(inputPath, options) {
     process.exitCode = ExitCode.ConversionError;
     return { success: false, errors };
   }
-  const tempMarkdownPath = getTempOutputPath(inputPath);
+  const tempDir = getTempPreviewDir(inputPath);
+  await mkdir2(tempDir, { recursive: true });
+  const tempMarkdownPath = join9(tempDir, "slides.md");
   console.log(`Converting ${chalk3.cyan(inputPath)}...`);
   try {
     await pipeline.runWithResult(inputPath, { outputPath: tempMarkdownPath });
@@ -3775,23 +3781,29 @@ async function executePreview(inputPath, options) {
     console.error(chalk3.red(`Error: Conversion failed: ${message}`));
     errors.push(message);
     process.exitCode = ExitCode.ConversionError;
+    await rm(tempDir, { recursive: true, force: true });
     return { success: false, errors };
   }
   console.log(`
 Starting preview server on port ${chalk3.cyan(port)}...`);
-  const marpCommand = buildMarpCommand(tempMarkdownPath, {
+  const marpCommand = buildMarpCommand(tempDir, {
     ...options,
-    port,
-    watch: false
-    // We handle watch ourselves if needed
+    watch: options.watch ?? false
   });
   if (verbose) {
     console.log(`Running: ${marpCommand}`);
   }
-  const marpProcess = spawnMarp(["--preview", "-p", String(port), tempMarkdownPath], {
-    projectDir: dirname4(inputPath),
+  const marpArgs = ["--server", "-I", tempDir];
+  if (options.watch) {
+    marpArgs.push("--watch");
+  }
+  const marpProcess = spawnMarp(marpArgs, {
+    projectDir: dirname5(inputPath),
     stdio: "inherit"
   });
+  console.log(`
+Preview available at ${chalk3.cyan(`http://localhost:${port}/slides.md`)}`);
+  console.log("Open this URL in your browser to view the slides.");
   let watcher = null;
   let debounceTimer = null;
   if (options.watch) {
@@ -3829,7 +3841,7 @@ Watching ${chalk3.cyan(inputPath)} for changes...`);
     watcher?.close();
     marpProcess.kill();
     try {
-      await unlink2(tempMarkdownPath);
+      await rm(tempDir, { recursive: true, force: true });
     } catch {
     }
   };
@@ -3845,13 +3857,13 @@ Watching ${chalk3.cyan(inputPath)} for changes...`);
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve7) => {
+  await new Promise((resolve8) => {
     marpProcess.on("exit", () => {
       cleanup();
-      resolve7();
+      resolve8();
     });
     if (options.signal) {
-      options.signal.addEventListener("abort", () => resolve7());
+      options.signal.addEventListener("abort", () => resolve8());
     }
   });
   return {
@@ -4396,8 +4408,8 @@ Showing ${templatePreviews.length} template preview(s)`);
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve7) => {
-    server.on("close", () => resolve7());
+  await new Promise((resolve8) => {
+    server.on("close", () => resolve8());
   });
 }
 function createTemplatesCommand() {
@@ -5195,7 +5207,7 @@ import { mkdir as mkdir7, writeFile as writeFile7, access as access10, readdir a
 import { existsSync as existsSync2 } from "fs";
 import { execSync, spawnSync } from "child_process";
 import { createInterface } from "readline";
-import { basename as basename7, dirname as dirname6, join as join16, resolve as resolve5, sep } from "path";
+import { basename as basename7, dirname as dirname7, join as join16, resolve as resolve6, sep } from "path";
 import { fileURLToPath } from "url";
 import chalk6 from "chalk";
 import ora3 from "ora";
@@ -6126,6 +6138,49 @@ The \`validate --format llm\` command provides:
 - Fix examples from template definitions
 - Contextual hints for unknown templates/icons
 
+## Visual Feedback Loop
+
+After creating or modifying slides, use this workflow to review and iterate:
+
+### Step 1: Take Screenshot
+\`\`\`bash
+# AI-optimized format (recommended)
+slide-gen screenshot presentation.yaml --format ai
+
+# Or contact sheet for overview
+slide-gen screenshot presentation.yaml --contact-sheet
+\`\`\`
+
+### Step 2: Review Images
+Use the Read tool to view the generated screenshots:
+\`\`\`
+Read ./screenshots/presentation.001.jpeg
+\`\`\`
+
+### Step 3: Identify Issues
+Look for:
+- Layout problems (text overflow, alignment)
+- Visual balance (too much/little content)
+- Icon and color appropriateness
+- Readability of text and diagrams
+
+### Step 4: Make Adjustments
+Edit presentation.yaml to fix identified issues.
+
+### Step 5: Repeat
+Take new screenshots and verify improvements.
+
+### Example Iteration Cycle
+
+1. Create initial slides
+2. \`slide-gen screenshot presentation.yaml --format ai --slide 3\`
+3. \`Read ./screenshots/presentation.003.jpeg\`
+4. Notice: "Title text is too long, wrapping awkwardly"
+5. Edit presentation.yaml to shorten title
+6. \`slide-gen screenshot presentation.yaml --format ai --slide 3\`
+7. \`Read ./screenshots/presentation.003.jpeg\`
+8. Verify fix, move to next slide
+
 ## Reference Management
 
 For academic presentations, manage citations and references:
@@ -6212,7 +6267,24 @@ Read \`.skills/slide-assistant/SKILL.md\` for detailed instructions.
 - \`/slide-validate\` - Validate slide source file
 - \`/slide-preview\` - Preview slides in browser
 - \`/slide-screenshot\` - Take screenshots for review
+- \`/slide-review\` - Visual review and iteration workflow
 - \`/slide-theme\` - Adjust theme and styling
+
+## Important: Visual Review
+
+**After creating or editing slides, always run visual review:**
+
+\`\`\`bash
+/slide-review
+\`\`\`
+
+Or manually:
+1. \`slide-gen screenshot presentation.yaml --format ai\`
+2. \`Read ./screenshots/presentation.001.jpeg\`
+3. Check layout, text overflow, visual balance
+4. Edit and repeat until satisfied
+
+This ensures slides look correct before delivery.
 `;
 }
 
@@ -6528,6 +6600,69 @@ After user provides images:
 
 ### Phase 4: Iteration
 Handle adjustments (cropping, replacement) as needed.
+
+## Visual Review Flow
+
+### When to Use Visual Review
+
+- After initial slide creation
+- When adjusting layouts or styling
+- Before final delivery
+- When user reports visual issues
+
+### Quick Review Workflow
+
+1. **Generate screenshots**:
+   \`\`\`bash
+   slide-gen screenshot presentation.yaml --format ai
+   \`\`\`
+
+2. **Review each slide**:
+   \`\`\`
+   Read ./screenshots/presentation.001.jpeg
+   Read ./screenshots/presentation.002.jpeg
+   ...
+   \`\`\`
+
+3. **Document issues** found in each slide
+
+4. **Make batch edits** to presentation.yaml
+
+5. **Regenerate and verify**:
+   \`\`\`bash
+   slide-gen screenshot presentation.yaml --format ai
+   \`\`\`
+
+### Contact Sheet Review
+
+For quick overview of all slides:
+
+1. **Generate contact sheet**:
+   \`\`\`bash
+   slide-gen screenshot presentation.yaml --contact-sheet
+   \`\`\`
+
+2. **Review overview**:
+   \`\`\`
+   Read ./screenshots/presentation-contact.png
+   \`\`\`
+
+3. **Identify slides needing attention**
+
+4. **Deep dive on specific slides**:
+   \`\`\`bash
+   slide-gen screenshot presentation.yaml --format ai --slide 5
+   \`\`\`
+
+### Common Visual Issues to Check
+
+| Issue | What to Look For | Fix |
+|-------|------------------|-----|
+| Text overflow | Text cut off or wrapped | Shorten text, use bullet-list |
+| Empty space | Large blank areas | Add content or use different template |
+| Cluttered | Too much content | Split into multiple slides |
+| Poor contrast | Hard to read text | Adjust colors in theme |
+| Icon mismatch | Icon doesn't fit context | Search for better icon |
 `;
 }
 
@@ -6804,18 +6939,128 @@ slide-gen screenshot $ARGUMENTS
 
 If no argument provided:
 \`\`\`bash
-slide-gen screenshot presentation.yaml -o screenshots/
+slide-gen screenshot presentation.yaml --format ai
 \`\`\`
 
 ## Options
 
-- \`--slide <number>\`: Screenshot specific slide only
-- \`--width <pixels>\`: Image width (default: 1280)
-- \`--output <dir>\`: Output directory
+| Option | Description | Default |
+|--------|-------------|---------|
+| \`--format <fmt>\` | Output format (png/jpeg/ai) | png |
+| \`--slide <number>\` | Screenshot specific slide only | All |
+| \`--contact-sheet\` | Generate overview of all slides | false |
+| \`--columns <num>\` | Contact sheet columns | 2 |
+| \`--width <pixels>\` | Image width | 1280 (ai: 640) |
+| \`--quality <num>\` | JPEG quality (1-100) | 80 |
+| \`--output <dir>\` | Output directory | ./screenshots |
+
+## AI Optimization Mode
+
+Use \`--format ai\` for token-efficient screenshots:
+- 640px width (75% token reduction)
+- JPEG format
+- Shows estimated token consumption
+
+\`\`\`bash
+# AI-optimized screenshots
+slide-gen screenshot presentation.yaml --format ai
+
+# Contact sheet for overview
+slide-gen screenshot presentation.yaml --contact-sheet
+
+# AI-optimized contact sheet
+slide-gen screenshot presentation.yaml --format ai --contact-sheet
+\`\`\`
+
+## Token Efficiency
 
-## After Screenshot
+| Format | Width | Est. Tokens/slide |
+|--------|-------|-------------------|
+| png/jpeg | 1280 | ~1,229 |
+| ai | 640 | ~308 (~75% reduction) |
 
-Read the screenshot images to review slide content and provide feedback.
+## Visual Feedback Workflow
+
+1. Take screenshot: \`slide-gen screenshot presentation.yaml --format ai\`
+2. Review image: \`Read ./screenshots/presentation.001.jpeg\`
+3. Identify issues (layout, text, icons)
+4. Edit presentation.yaml
+5. Repeat until satisfied
+`;
+}
+
+// src/cli/templates/ai/commands/slide-review.ts
+function generateSlideReviewCommand() {
+  return `Review slides visually and iterate on improvements.
+
+## Workflow
+
+1. **Take AI-optimized screenshots**:
+   \`\`\`bash
+   slide-gen screenshot $ARGUMENTS --format ai
+   \`\`\`
+   If no argument: \`slide-gen screenshot presentation.yaml --format ai\`
+
+2. **Review each slide image**:
+   \`\`\`
+   Read ./screenshots/presentation.001.jpeg
+   Read ./screenshots/presentation.002.jpeg
+   ...
+   \`\`\`
+
+3. **Check for issues**:
+   - Text overflow or awkward wrapping
+   - Poor visual balance (too empty / too cluttered)
+   - Icon appropriateness
+   - Color contrast and readability
+   - Diagram clarity
+
+4. **Report findings** to user with specific slide numbers
+
+5. **If issues found**, edit presentation.yaml and repeat from step 1
+
+## Quick Overview
+
+For a quick overview of all slides:
+\`\`\`bash
+slide-gen screenshot presentation.yaml --contact-sheet
+Read ./screenshots/presentation-contact.png
+\`\`\`
+
+## Token Efficiency
+
+Always use \`--format ai\` for ~75% token reduction:
+- Default: ~1,229 tokens/slide
+- AI mode: ~308 tokens/slide
+
+## Common Issues Checklist
+
+| Issue | What to Look For | Fix |
+|-------|------------------|-----|
+| Text overflow | Text cut off or wrapped | Shorten text, use bullet-list |
+| Empty space | Large blank areas | Add content or use different template |
+| Cluttered | Too much content | Split into multiple slides |
+| Poor contrast | Hard to read text | Adjust colors in theme |
+| Icon mismatch | Icon doesn't fit context | Search for better icon |
+
+## Example Session
+
+\`\`\`bash
+# Initial review
+slide-gen screenshot presentation.yaml --format ai
+
+# Check slide 3
+Read ./screenshots/presentation.003.jpeg
+# Notice: "Title text is too long"
+
+# Edit presentation.yaml to shorten title
+
+# Re-take screenshot for slide 3
+slide-gen screenshot presentation.yaml --format ai --slide 3
+
+# Verify fix
+Read ./screenshots/presentation.003.jpeg
+\`\`\`
 `;
 }
 
@@ -6910,7 +7155,7 @@ slide-gen validate presentation.yaml
 
 // src/cli/commands/init.ts
 function getPackageRoot() {
-  const __dirname = dirname6(fileURLToPath(import.meta.url));
+  const __dirname = dirname7(fileURLToPath(import.meta.url));
   if (__dirname.includes(`${sep}src${sep}`) || __dirname.includes("/src/")) {
     return join16(__dirname, "..", "..", "..");
   }
@@ -6923,7 +7168,7 @@ function createInitCommand() {
 }
 async function executeInit(directory, options) {
   const spinner = ora3();
-  const targetDir = resolve5(directory);
+  const targetDir = resolve6(directory);
   const includeExamples = options.examples !== false;
   const includeAiConfig = options.aiConfig !== false;
   const includeSources = options.sources !== false;
@@ -6972,11 +7217,11 @@ async function executeInit(directory, options) {
         await sourcesManager.init({
           name: "Untitled Project",
           setup_pattern: options.fromDirectory ? "A" : void 0,
-          original_source: options.fromDirectory ? resolve5(options.fromDirectory) : void 0
+          original_source: options.fromDirectory ? resolve6(options.fromDirectory) : void 0
         });
         if (options.fromDirectory) {
           const importer = new SourceImporter(targetDir, sourcesManager);
-          const result = await importer.importDirectory(resolve5(options.fromDirectory), {
+          const result = await importer.importDirectory(resolve6(options.fromDirectory), {
             recursive: true
           });
           sourcesImported = result.imported;
@@ -6997,6 +7242,7 @@ async function executeInit(directory, options) {
     }
     if (includeAiConfig) {
       console.log(`  ${chalk6.cyan(".skills/")} - AgentSkills configuration`);
+      console.log(`  ${chalk6.cyan(".claude/skills/")} - Claude Code skills`);
       console.log(`  ${chalk6.cyan("CLAUDE.md")} - Claude Code configuration`);
       console.log(`  ${chalk6.cyan("AGENTS.md")} - OpenCode configuration`);
       console.log(`  ${chalk6.cyan(".cursorrules")} - Cursor configuration`);
@@ -7081,16 +7327,16 @@ async function promptMarpInstallChoice() {
   console.log(`  ${chalk6.cyan("2)")} Local install ${chalk6.dim("(creates package.json)")}`);
   console.log(`  ${chalk6.cyan("3)")} Skip ${chalk6.dim("(I'll install it later)")}`);
   console.log("");
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     rl.question("Choice [1]: ", (answer) => {
       rl.close();
       const normalized = answer.trim();
       if (normalized === "" || normalized === "1") {
-        resolve7("global");
+        resolve8("global");
       } else if (normalized === "2") {
-        resolve7("local");
+        resolve8("local");
       } else {
-        resolve7("skip");
+        resolve8("skip");
       }
     });
   });
@@ -7204,30 +7450,35 @@ async function showMarpCliInfo(targetDir) {
 async function generateAiConfig(targetDir) {
   await mkdir7(join16(targetDir, ".skills", "slide-assistant", "references"), { recursive: true });
   await mkdir7(join16(targetDir, ".skills", "slide-assistant", "scripts"), { recursive: true });
+  await mkdir7(join16(targetDir, ".claude", "skills", "slide-assistant", "references"), { recursive: true });
   await mkdir7(join16(targetDir, ".claude", "commands"), { recursive: true });
   await mkdir7(join16(targetDir, ".opencode", "agent"), { recursive: true });
-  await writeFileIfNotExists(
-    join16(targetDir, ".skills", "slide-assistant", "SKILL.md"),
-    generateSkillMd()
-  );
-  await writeFileIfNotExists(
-    join16(targetDir, ".skills", "slide-assistant", "references", "templates.md"),
-    generateTemplatesRef()
-  );
-  await writeFileIfNotExists(
-    join16(targetDir, ".skills", "slide-assistant", "references", "workflows.md"),
-    generateWorkflowsRef()
-  );
-  await writeFileIfNotExists(
-    join16(targetDir, ".skills", "slide-assistant", "references", "skill.md"),
-    generateReferenceSkillMd()
-  );
+  const skillDirs = [
+    join16(targetDir, ".skills", "slide-assistant"),
+    join16(targetDir, ".claude", "skills", "slide-assistant")
+  ];
+  for (const skillDir of skillDirs) {
+    await writeFileIfNotExists(join16(skillDir, "SKILL.md"), generateSkillMd());
+    await writeFileIfNotExists(
+      join16(skillDir, "references", "templates.md"),
+      generateTemplatesRef()
+    );
+    await writeFileIfNotExists(
+      join16(skillDir, "references", "workflows.md"),
+      generateWorkflowsRef()
+    );
+    await writeFileIfNotExists(
+      join16(skillDir, "references", "skill.md"),
+      generateReferenceSkillMd()
+    );
+  }
   await writeFileIfNotExists(join16(targetDir, "CLAUDE.md"), generateClaudeMd());
   const commandGenerators = {
     "slide-create": generateSlideCreateCommand,
     "slide-validate": generateSlideValidateCommand,
     "slide-preview": generateSlidePreviewCommand,
     "slide-screenshot": generateSlideScreenshotCommand,
+    "slide-review": generateSlideReviewCommand,
     "slide-theme": generateSlideThemeCommand,
     "slide-references": generateSlideReferencesCommand
   };
@@ -7340,7 +7591,7 @@ slides:
 // src/cli/commands/watch.ts
 import { Command as Command7 } from "commander";
 import { access as access11 } from "fs/promises";
-import { basename as basename8, dirname as dirname7, join as join17 } from "path";
+import { basename as basename8, dirname as dirname8, join as join17 } from "path";
 import chalk7 from "chalk";
 import { watch as chokidarWatch2 } from "chokidar";
 var WatchState = class {
@@ -7373,7 +7624,7 @@ var WatchState = class {
   }
 };
 function getDefaultOutputPath2(inputPath) {
-  const dir = dirname7(inputPath);
+  const dir = dirname8(inputPath);
   const base = basename8(inputPath, ".yaml");
   return join17(dir, `${base}.md`);
 }
@@ -7435,7 +7686,7 @@ async function executeWatch(inputPath, options) {
   const configLoader = new ConfigLoader();
   let configPath = options.config;
   if (!configPath) {
-    configPath = await configLoader.findConfig(dirname7(inputPath));
+    configPath = await configLoader.findConfig(dirname8(inputPath));
   }
   const config = await configLoader.load(configPath);
   const pipeline = new Pipeline(config);
@@ -7504,9 +7755,9 @@ async function executeWatch(inputPath, options) {
   };
   process.on("SIGINT", signalHandler);
   process.on("SIGTERM", signalHandler);
-  await new Promise((resolve7) => {
+  await new Promise((resolve8) => {
     if (options.signal) {
-      options.signal.addEventListener("abort", () => resolve7());
+      options.signal.addEventListener("abort", () => resolve8());
     }
   });
   return {
@@ -7519,7 +7770,7 @@ async function executeWatch(inputPath, options) {
 // src/cli/commands/images.ts
 import { Command as Command8 } from "commander";
 import { readFile as readFile15, stat as stat2, mkdir as mkdir8 } from "fs/promises";
-import { dirname as dirname8, basename as basename9, join as join18 } from "path";
+import { dirname as dirname9, basename as basename9, join as join18 } from "path";
 import chalk8 from "chalk";
 import { stringify as stringifyYaml3 } from "yaml";
 function createImagesCommand() {
@@ -7542,7 +7793,7 @@ function createImagesRequestCommand() {
 async function executeImagesStatus(inputPath) {
   try {
     const slides = await loadPresentation(inputPath);
-    const baseDir = dirname8(inputPath);
+    const baseDir = dirname9(inputPath);
     const validator = new ImageValidator(baseDir);
     const imageRefs = validator.extractImageReferences(slides);
     if (imageRefs.length === 0) {
@@ -7642,7 +7893,7 @@ async function outputImageStatus(stats, imageRefs, _validator, baseDir) {
 async function executeImagesRequest(inputPath, options) {
   try {
     const slides = await loadPresentation(inputPath);
-    const baseDir = dirname8(inputPath);
+    const baseDir = dirname9(inputPath);
     const validator = new ImageValidator(baseDir);
     const missingImages = await validator.getMissingImages(slides);
     if (missingImages.length === 0) {
@@ -7842,7 +8093,7 @@ async function processSingleFile(filePath, options) {
     return;
   }
   const processor = new ImageProcessor();
-  const dir = dirname8(filePath);
+  const dir = dirname9(filePath);
   const filename = basename9(filePath);
   const outputDir = join18(dir, options.output);
   await mkdir8(outputDir, { recursive: true });
@@ -7940,10 +8191,11 @@ function parseBlurSpec(spec) {
 
 // src/cli/commands/screenshot.ts
 import { Command as Command9 } from "commander";
-import { access as access12, mkdir as mkdir9, readdir as readdir7, unlink as unlink3 } from "fs/promises";
-import { basename as basename10, dirname as dirname9, join as join19 } from "path";
+import { access as access12, mkdir as mkdir9, readdir as readdir7, unlink as unlink2 } from "fs/promises";
+import { basename as basename10, dirname as dirname10, join as join19 } from "path";
 import chalk9 from "chalk";
 import ora4 from "ora";
+import sharp2 from "sharp";
 async function filterToSpecificSlide(outputDir, baseName, slideNumber, format) {
   const slideStr = slideNumber.toString().padStart(3, "0");
   const targetFileName = `${baseName}.${slideStr}.${format}`;
@@ -7962,7 +8214,7 @@ async function filterToSpecificSlide(outputDir, baseName, slideNumber, format) {
   );
   for (const file of slideFiles) {
     if (file !== targetFileName) {
-      await unlink3(join19(outputDir, file));
+      await unlink2(join19(outputDir, file));
     }
   }
   return {
@@ -7973,19 +8225,120 @@ async function filterToSpecificSlide(outputDir, baseName, slideNumber, format) {
 function checkMarpCliAvailable2(projectDir) {
   return isMarpAvailable(projectDir);
 }
+function estimateTokens(width, height) {
+  return Math.ceil(width * height / 750);
+}
+function calculateGridDimensions(slideCount, columns) {
+  const rows = Math.ceil(slideCount / columns);
+  return { rows, columns };
+}
+function createNumberOverlay(number, width) {
+  const svg = `
+    <svg width="${width}" height="30">
+      <rect width="${width}" height="30" fill="rgba(0,0,0,0.6)"/>
+      <text x="10" y="22" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="16" fill="white">
+        Slide ${number}
+      </text>
+    </svg>
+  `;
+  return Buffer.from(svg);
+}
+async function generateContactSheet(slides, options) {
+  const {
+    columns,
+    padding = 10,
+    showNumbers = true,
+    slideWidth = 640,
+    slideHeight = 360
+  } = options;
+  if (slides.length === 0) {
+    return { success: false, error: "No slides provided" };
+  }
+  try {
+    const { rows } = calculateGridDimensions(slides.length, columns);
+    const canvasWidth = columns * slideWidth + (columns + 1) * padding;
+    const canvasHeight = rows * slideHeight + (rows + 1) * padding;
+    const composites = [];
+    for (let i = 0; i < slides.length; i++) {
+      const slide = slides[i];
+      const col = i % columns;
+      const row = Math.floor(i / columns);
+      const x = padding + col * (slideWidth + padding);
+      const y = padding + row * (slideHeight + padding);
+      const resized = await sharp2(slide.path).resize(slideWidth, slideHeight, { fit: "contain", background: { r: 255, g: 255, b: 255 } }).toBuffer();
+      composites.push({
+        input: resized,
+        left: x,
+        top: y
+      });
+      if (showNumbers) {
+        const numberOverlay = createNumberOverlay(slide.index, slideWidth);
+        composites.push({
+          input: numberOverlay,
+          left: x,
+          top: y + slideHeight - 30
+        });
+      }
+    }
+    await sharp2({
+      create: {
+        width: canvasWidth,
+        height: canvasHeight,
+        channels: 4,
+        background: { r: 245, g: 245, b: 245, alpha: 1 }
+      }
+    }).composite(composites).png().toFile(options.outputPath);
+    return {
+      success: true,
+      outputPath: options.outputPath
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error"
+    };
+  }
+}
+function formatAiOutput(options) {
+  const { files, width, height, outputDir } = options;
+  const tokensPerImage = estimateTokens(width, height);
+  const totalTokens = tokensPerImage * files.length;
+  const imageLabel = files.length === 1 ? "image" : "images";
+  const lines = [
+    "Screenshots saved (AI-optimized):",
+    ""
+  ];
+  for (const file of files) {
+    lines.push(`  ${join19(outputDir, file)}`);
+  }
+  lines.push("");
+  lines.push(`Estimated tokens: ~${totalTokens} (${files.length} ${imageLabel})`);
+  if (files.length > 0) {
+    lines.push("");
+    lines.push("To review in Claude Code:");
+    lines.push(`  Read ${join19(outputDir, files[0])}`);
+  }
+  return lines.join("\n");
+}
 function buildMarpCommandArgs(markdownPath, outputDir, options) {
-  const format = options.format || "png";
-  const args = ["--images", format];
-  if (options.width && options.width !== 1280) {
-    const scale = options.width / 1280;
+  const isAiFormat = options.format === "ai";
+  const imageFormat = isAiFormat ? "jpeg" : options.format || "png";
+  const width = isAiFormat ? 640 : options.width || 1280;
+  const args = ["--images", imageFormat];
+  if (width !== 1280) {
+    const scale = width / 1280;
     args.push("--image-scale", String(scale));
   }
+  if (imageFormat === "jpeg") {
+    const quality = options.quality || 80;
+    args.push("--jpeg-quality", String(quality));
+  }
   args.push("-o", outputDir);
   args.push(markdownPath);
   return args;
 }
 function createScreenshotCommand() {
-  return new Command9("screenshot").description("Take screenshots of slides (requires Marp CLI)").argument("<input>", "Source YAML file").option("-o, --output <path>", "Output directory", "./screenshots").option("-s, --slide <number>", "Specific slide number (1-based)", parseInt).option("-w, --width <pixels>", "Image width", parseInt, 1280).option("-f, --format <fmt>", "Image format (png/jpeg)", "png").option("-c, --config <path>", "Config file path").option("-v, --verbose", "Verbose output").action(async (input, options) => {
+  return new Command9("screenshot").description("Take screenshots of slides (requires Marp CLI)").argument("<input>", "Source YAML file").option("-o, --output <path>", "Output directory", "./screenshots").option("-s, --slide <number>", "Specific slide number (1-based)", parseInt).option("-w, --width <pixels>", "Image width", parseInt, 1280).option("-f, --format <fmt>", "Output format (png/jpeg/ai)", "png").option("-q, --quality <num>", "JPEG quality (1-100)", parseInt, 80).option("--contact-sheet", "Generate contact sheet").option("--columns <num>", "Contact sheet columns", parseInt, 2).option("-c, --config <path>", "Config file path").option("-v, --verbose", "Verbose output").action(async (input, options) => {
     await executeScreenshot(input, options);
   });
 }
@@ -8010,7 +8363,7 @@ async function executeScreenshot(inputPath, options) {
     return { success: false, errors };
   }
   spinner?.start("Checking for Marp CLI...");
-  if (!checkMarpCliAvailable2(dirname9(inputPath))) {
+  if (!checkMarpCliAvailable2(dirname10(inputPath))) {
     spinner?.fail("Marp CLI not found");
     const message = "Marp CLI not found. Install it with: npm install -D @marp-team/marp-cli";
     console.error(chalk9.red(`Error: ${message}`));
@@ -8032,7 +8385,7 @@ async function executeScreenshot(inputPath, options) {
   const configLoader = new ConfigLoader();
   let configPath = options.config;
   if (!configPath) {
-    configPath = await configLoader.findConfig(dirname9(inputPath));
+    configPath = await configLoader.findConfig(dirname10(inputPath));
   }
   const config = await configLoader.load(configPath);
   spinner?.succeed("Configuration loaded");
@@ -8053,7 +8406,7 @@ async function executeScreenshot(inputPath, options) {
   const tempMdPath = inputPath.replace(/\.ya?ml$/i, ".md");
   const cleanupTempFile = async () => {
     try {
-      await unlink3(tempMdPath);
+      await unlink2(tempMdPath);
     } catch {
     }
   };
@@ -8076,7 +8429,7 @@ async function executeScreenshot(inputPath, options) {
   }
   try {
     runMarp(marpArgs, {
-      projectDir: dirname9(inputPath),
+      projectDir: dirname10(inputPath),
       stdio: options.verbose ? "inherit" : "pipe"
     });
     spinner?.succeed(`Screenshots saved to ${outputDir}`);
@@ -8089,15 +8442,18 @@ async function executeScreenshot(inputPath, options) {
     await cleanupTempFile();
     return { success: false, errors };
   }
+  const isAiFormat = options.format === "ai";
+  const actualFormat = isAiFormat ? "jpeg" : options.format || "png";
+  let actualWidth = isAiFormat ? 640 : options.width || 1280;
+  let actualHeight = Math.round(actualWidth * 9 / 16);
   if (options.slide !== void 0) {
     spinner?.start(`Filtering to slide ${options.slide}...`);
-    const mdBaseName = basename10(tempMdPath, ".md");
-    const format = options.format || "png";
+    const mdBaseName2 = basename10(tempMdPath, ".md");
     const filterResult = await filterToSpecificSlide(
       outputDir,
-      mdBaseName,
+      mdBaseName2,
       options.slide,
-      format
+      actualFormat
     );
     if (!filterResult.success) {
       spinner?.fail("Failed to filter slides");
@@ -8109,20 +8465,71 @@ async function executeScreenshot(inputPath, options) {
     }
     spinner?.succeed(`Kept slide ${options.slide}: ${filterResult.keptFile}`);
   }
+  const allFiles = await readdir7(outputDir);
+  const mdBaseName = basename10(tempMdPath, ".md");
+  const generatedFiles = allFiles.filter((f) => f.startsWith(mdBaseName) && f.endsWith(`.${actualFormat}`)).sort();
+  if (generatedFiles.length > 0) {
+    try {
+      const metadata = await sharp2(join19(outputDir, generatedFiles[0])).metadata();
+      if (metadata.width && metadata.height) {
+        actualWidth = metadata.width;
+        actualHeight = metadata.height;
+      }
+    } catch {
+    }
+  }
+  if (options.contactSheet && generatedFiles.length > 0) {
+    spinner?.start("Generating contact sheet...");
+    const slides = generatedFiles.map((file, index) => ({
+      path: join19(outputDir, file),
+      index: index + 1
+    }));
+    const contactSheetPath = join19(outputDir, `${mdBaseName}-contact.png`);
+    const contactResult = await generateContactSheet(slides, {
+      outputPath: contactSheetPath,
+      columns: options.columns || 2,
+      slideWidth: actualWidth,
+      slideHeight: actualHeight
+    });
+    if (!contactResult.success) {
+      spinner?.fail("Failed to generate contact sheet");
+      console.error(chalk9.red(`Error: ${contactResult.error}`));
+      errors.push(contactResult.error || "Contact sheet generation failed");
+    } else {
+      spinner?.succeed(`Contact sheet saved: ${basename10(contactSheetPath)}`);
+    }
+  }
   await cleanupTempFile();
   console.log("");
-  console.log(`Output: ${chalk9.cyan(outputDir)}`);
+  if (isAiFormat && generatedFiles.length > 0) {
+    const output = formatAiOutput({
+      files: generatedFiles,
+      width: actualWidth,
+      height: actualHeight,
+      outputDir
+    });
+    console.log(output);
+  } else if (isAiFormat) {
+    console.log(`Output: ${chalk9.cyan(outputDir)}`);
+    console.log("No screenshots generated");
+  } else {
+    console.log(`Output: ${chalk9.cyan(outputDir)}`);
+    if (generatedFiles.length > 0) {
+      console.log(`Files: ${generatedFiles.length} screenshot(s)`);
+    }
+  }
   return {
     success: true,
     errors,
-    outputDir
+    outputDir,
+    files: generatedFiles
   };
 }
 
 // src/cli/commands/sources.ts
 import { Command as Command10 } from "commander";
 import { access as access13, stat as stat3 } from "fs/promises";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 import chalk10 from "chalk";
 import ora5 from "ora";
 function createSourcesCommand() {
@@ -8171,7 +8578,7 @@ function createSourcesSyncCommand() {
   });
 }
 async function executeSourcesInit(projectDir, options) {
-  const resolvedDir = resolve6(projectDir);
+  const resolvedDir = resolve7(projectDir);
   const spinner = ora5("Initializing sources...").start();
   try {
     const manager = new SourcesManager(resolvedDir);
@@ -8187,10 +8594,10 @@ async function executeSourcesInit(projectDir, options) {
     let originalSource;
     if (options.fromDirectory) {
       setupPattern = "A";
-      originalSource = resolve6(options.fromDirectory);
+      originalSource = resolve7(options.fromDirectory);
     } else if (options.fromFile) {
       setupPattern = "B";
-      originalSource = resolve6(options.fromFile);
+      originalSource = resolve7(options.fromFile);
     }
     await manager.init({
       name: projectName,
@@ -8201,14 +8608,14 @@ async function executeSourcesInit(projectDir, options) {
     if (options.fromDirectory) {
       const importer = new SourceImporter(resolvedDir, manager);
       const result = await importer.importDirectory(
-        resolve6(options.fromDirectory),
+        resolve7(options.fromDirectory),
         { recursive: true }
       );
       filesImported = result.imported;
     }
     if (options.fromFile) {
       const importer = new SourceImporter(resolvedDir, manager);
-      await importer.importFile(resolve6(options.fromFile), {
+      await importer.importFile(resolve7(options.fromFile), {
         type: "scenario"
       });
       filesImported = 1;
@@ -8233,8 +8640,8 @@ async function executeSourcesInit(projectDir, options) {
   }
 }
 async function executeSourcesImport(projectDir, sourcePath, options) {
-  const resolvedDir = resolve6(projectDir);
-  const resolvedSource = resolve6(sourcePath);
+  const resolvedDir = resolve7(projectDir);
+  const resolvedSource = resolve7(sourcePath);
   const spinner = ora5("Importing files...").start();
   try {
     const manager = new SourcesManager(resolvedDir);
@@ -8293,7 +8700,7 @@ async function executeSourcesImport(projectDir, sourcePath, options) {
   }
 }
 async function executeSourcesStatus(projectDir, _options) {
-  const resolvedDir = resolve6(projectDir);
+  const resolvedDir = resolve7(projectDir);
   try {
     const manager = new SourcesManager(resolvedDir);
     if (!await manager.exists()) {
@@ -8380,7 +8787,7 @@ async function executeSourcesStatus(projectDir, _options) {
   }
 }
 async function executeSourcesSync(projectDir, options) {
-  const resolvedDir = resolve6(projectDir);
+  const resolvedDir = resolve7(projectDir);
   try {
     const manager = new SourcesManager(resolvedDir);
     if (!await manager.exists()) {