@ncukondo/slide-generation 0.2.5 → 0.4.0

package/dist/cli/index.js

@@ -923,25 +923,25 @@ var ReferenceManager = class {
     return items[0] || null;
   }
   /**
-   * Get multiple references by IDs
+   * Get multiple references by IDs using ref export for better performance
    */
   async getByIds(ids) {
     if (ids.length === 0) {
       return /* @__PURE__ */ new Map();
     }
-    const result = await this.execCommand(`${this.command} list --format json`);
-    const allItems = this.parseJSON(result);
-    const idSet = new Set(ids);
+    const idsArg = ids.map((id) => `"${id}"`).join(" ");
+    const result = await this.execCommand(
+      `${this.command} export ${idsArg}`
+    );
+    const items = this.parseJSON(result);
     const map = /* @__PURE__ */ new Map();
-    for (const item of allItems) {
-      if (idSet.has(item.id)) {
-        map.set(item.id, item);
-      }
+    for (const item of items) {
+      map.set(item.id, item);
     }
     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());
       });
     });
   }
@@ -1080,6 +1080,82 @@ var CitationExtractor = class {
   }
 };
 
+// src/references/utils.ts
+var JAPANESE_PATTERN = /[\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FAF]/;
+function isJapaneseAuthors(authors) {
+  if (!authors || authors.length === 0) {
+    return false;
+  }
+  return JAPANESE_PATTERN.test(authors[0].family);
+}
+function getYear(item) {
+  const dateParts = item.issued?.["date-parts"];
+  if (dateParts && dateParts[0] && dateParts[0][0]) {
+    return dateParts[0][0];
+  }
+  return 0;
+}
+function getIdentifier(item) {
+  if (item.PMID) {
+    return `PMID: ${item.PMID}`;
+  }
+  if (item.DOI) {
+    return `DOI: ${item.DOI}`;
+  }
+  return null;
+}
+function getFirstAuthorFamily(item) {
+  return item.author?.[0]?.family || "";
+}
+function formatAuthorsFull(authors, isJapanese) {
+  if (!authors || authors.length === 0) {
+    return "Unknown";
+  }
+  if (isJapanese) {
+    return authors.map((a) => `${a.family}${a.given || ""}`).join(", ");
+  }
+  if (authors.length === 1) {
+    const a = authors[0];
+    const initial = a.given ? `${a.given.charAt(0)}.` : "";
+    return `${a.family}, ${initial}`;
+  }
+  const formatted = authors.map((a, i) => {
+    const initial = a.given ? `${a.given.charAt(0)}.` : "";
+    if (i === authors.length - 1) {
+      return `& ${a.family}, ${initial}`;
+    }
+    return `${a.family}, ${initial}`;
+  });
+  return formatted.join(", ").replace(", &", ", &");
+}
+function formatFullEntry(item) {
+  const parts = [];
+  const japanese = isJapaneseAuthors(item.author);
+  const authors = formatAuthorsFull(item.author, japanese);
+  parts.push(authors);
+  const year = getYear(item);
+  parts.push(`(${year}).`);
+  if (item.title) {
+    parts.push(`${item.title}.`);
+  }
+  if (item["container-title"]) {
+    const journal = japanese ? item["container-title"] : `*${item["container-title"]}*`;
+    let location = "";
+    if (item.volume) {
+      location = item.issue ? `${item.volume}(${item.issue})` : item.volume;
+    }
+    if (item.page) {
+      location = location ? `${location}, ${item.page}` : item.page;
+    }
+    parts.push(location ? `${journal}, ${location}.` : `${journal}.`);
+  }
+  const identifier = getIdentifier(item);
+  if (identifier) {
+    parts.push(identifier);
+  }
+  return parts.join(" ");
+}
+
 // src/references/formatter.ts
 var DEFAULT_CONFIG = {
   author: {
@@ -1094,7 +1170,6 @@ var DEFAULT_CONFIG = {
     multiSep: "), ("
   }
 };
-var JAPANESE_PATTERN = /[\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FAF]/;
 var CITATION_BRACKET_PATTERN2 = /\[(@[\w-]+(?:,\s*[^;\]]+)?(?:;\s*@[\w-]+(?:,\s*[^;\]]+)?)*)\]/g;
 var SINGLE_CITATION_PATTERN2 = /@([\w-]+)(?:,\s*([^;\]]+))?/g;
 var CitationFormatter = class {
@@ -1106,6 +1181,18 @@ var CitationFormatter = class {
     };
   }
   config;
+  availabilityChecked = false;
+  isAvailable = false;
+  /**
+   * Check if reference-manager is available (cached)
+   */
+  async checkAvailability() {
+    if (!this.availabilityChecked) {
+      this.isAvailable = await this.manager.isAvailable();
+      this.availabilityChecked = true;
+    }
+    return this.isAvailable;
+  }
   /**
    * Format an inline citation
    * e.g., "(Smith et al., 2024; PMID: 12345678)"
@@ -1125,13 +1212,16 @@ var CitationFormatter = class {
     if (!item) {
       return `[${id}]`;
     }
-    return this.formatFullItem(item);
+    return formatFullEntry(item);
   }
   /**
    * Expand all citations in text
    * e.g., "[@smith2024]" -> "(Smith et al., 2024; PMID: 12345678)"
    */
   async expandCitations(text) {
+    if (!await this.checkAvailability()) {
+      return text;
+    }
     const ids = /* @__PURE__ */ new Set();
     CITATION_BRACKET_PATTERN2.lastIndex = 0;
     let match;
@@ -1186,117 +1276,102 @@ var CitationFormatter = class {
       sortedItems = ids.map((id) => items.get(id)).filter((item) => item !== void 0);
     } else if (sort === "author") {
       sortedItems = [...items.values()].sort((a, b) => {
-        const authorA = this.getFirstAuthorFamily(a);
-        const authorB = this.getFirstAuthorFamily(b);
+        const authorA = getFirstAuthorFamily(a);
+        const authorB = getFirstAuthorFamily(b);
         return authorA.localeCompare(authorB);
       });
     } else {
       sortedItems = [...items.values()].sort((a, b) => {
-        const yearA = this.getYear(a);
-        const yearB = this.getYear(b);
+        const yearA = getYear(a);
+        const yearB = getYear(b);
         return yearA - yearB;
       });
     }
-    return sortedItems.map((item) => this.formatFullItem(item));
+    return sortedItems.map((item) => formatFullEntry(item));
   }
   formatInlineItem(item) {
     const author = this.formatAuthorInline(item.author);
-    const year = this.getYear(item);
-    const identifier = this.getIdentifier(item);
+    const year = getYear(item);
+    const identifier = getIdentifier(item);
     if (identifier) {
       return `(${author}, ${year}; ${identifier})`;
     }
     return `(${author}, ${year})`;
   }
-  formatFullItem(item) {
-    const parts = [];
-    const isJapanese = this.isJapaneseAuthors(item.author);
-    const authors = this.formatAuthorsFull(item.author, isJapanese);
-    parts.push(authors);
-    const year = this.getYear(item);
-    parts.push(`(${year}).`);
-    if (item.title) {
-      parts.push(`${item.title}.`);
-    }
-    if (item["container-title"]) {
-      const journal = isJapanese ? item["container-title"] : `*${item["container-title"]}*`;
-      let location = "";
-      if (item.volume) {
-        location = item.issue ? `${item.volume}(${item.issue})` : item.volume;
-      }
-      if (item.page) {
-        location = location ? `${location}, ${item.page}` : item.page;
-      }
-      parts.push(location ? `${journal}, ${location}.` : `${journal}.`);
-    }
-    const identifier = this.getIdentifier(item);
-    if (identifier) {
-      parts.push(identifier);
-    }
-    return parts.join(" ");
-  }
   formatAuthorInline(authors) {
     if (!authors || authors.length === 0) {
       return "Unknown";
     }
-    const isJapanese = this.isJapaneseAuthors(authors);
+    const japanese = isJapaneseAuthors(authors);
     const { etAl, etAlJa, separatorJa } = this.config.author;
     const firstAuthor = authors[0];
     if (authors.length === 1) {
       return firstAuthor.family;
     }
     if (authors.length === 2) {
-      const separator = isJapanese ? separatorJa : " & ";
+      const separator = japanese ? separatorJa : " & ";
       return `${firstAuthor.family}${separator}${authors[1].family}`;
     }
-    const suffix = isJapanese ? etAlJa : ` ${etAl}`;
+    const suffix = japanese ? etAlJa : ` ${etAl}`;
     return `${firstAuthor.family}${suffix}`;
   }
-  formatAuthorsFull(authors, isJapanese) {
-    if (!authors || authors.length === 0) {
-      return "Unknown";
-    }
-    if (isJapanese) {
-      return authors.map((a) => `${a.family}${a.given || ""}`).join(", ");
-    }
-    if (authors.length === 1) {
-      const a = authors[0];
-      const initial = a.given ? `${a.given.charAt(0)}.` : "";
-      return `${a.family}, ${initial}`;
-    }
-    const formatted = authors.map((a, i) => {
-      const initial = a.given ? `${a.given.charAt(0)}.` : "";
-      if (i === authors.length - 1) {
-        return `& ${a.family}, ${initial}`;
-      }
-      return `${a.family}, ${initial}`;
-    });
-    return formatted.join(", ").replace(", &", ", &");
+};
+
+// src/references/bibliography.ts
+var BibliographyGenerator = class {
+  constructor(manager) {
+    this.manager = manager;
   }
-  isJapaneseAuthors(authors) {
-    if (!authors || authors.length === 0) {
-      return false;
+  /**
+   * Generate bibliography entries from citation IDs
+   */
+  async generate(citationIds, options = {}) {
+    const { sort = "citation-order" } = options;
+    if (citationIds.length === 0) {
+      return { entries: [], items: [], missing: [] };
     }
-    return JAPANESE_PATTERN.test(authors[0].family);
-  }
-  getFirstAuthorFamily(item) {
-    return item.author?.[0]?.family || "";
-  }
-  getYear(item) {
-    const dateParts = item.issued?.["date-parts"];
-    if (dateParts && dateParts[0] && dateParts[0][0]) {
-      return dateParts[0][0];
+    const uniqueIds = [...new Set(citationIds)];
+    const itemsMap = await this.manager.getByIds(uniqueIds);
+    const missing = [];
+    const foundItems = [];
+    for (const id of uniqueIds) {
+      const item = itemsMap.get(id);
+      if (item) {
+        foundItems.push(item);
+      } else {
+        missing.push(id);
+      }
     }
-    return 0;
+    const sortedItems = this.sortItems(foundItems, sort);
+    const entries = sortedItems.map((item) => formatFullEntry(item));
+    return {
+      entries,
+      items: sortedItems,
+      missing
+    };
   }
-  getIdentifier(item) {
-    if (item.PMID) {
-      return `PMID: ${item.PMID}`;
-    }
-    if (item.DOI) {
-      return `DOI: ${item.DOI}`;
+  /**
+   * Sort items according to the specified order
+   */
+  sortItems(items, sort) {
+    switch (sort) {
+      case "citation-order":
+        return items;
+      case "author":
+        return [...items].sort((a, b) => {
+          const authorA = getFirstAuthorFamily(a);
+          const authorB = getFirstAuthorFamily(b);
+          return authorA.localeCompare(authorB);
+        });
+      case "year":
+        return [...items].sort((a, b) => {
+          const yearA = getYear(a);
+          const yearB = getYear(b);
+          return yearA - yearB;
+        });
+      default:
+        return items;
     }
-    return null;
   }
 };
 
@@ -1335,6 +1410,7 @@ var Pipeline = class {
         }
       }
     );
+    this.bibliographyGenerator = new BibliographyGenerator(this.referenceManager);
     this.transformer = new Transformer(
       this.templateEngine,
       this.templateLoader,
@@ -1351,6 +1427,7 @@ var Pipeline = class {
   referenceManager;
   citationExtractor;
   citationFormatter;
+  bibliographyGenerator;
   transformer;
   renderer;
   warnings = [];
@@ -1360,9 +1437,10 @@ var Pipeline = class {
   async run(inputPath, options) {
     this.warnings = [];
     try {
-      const presentation = await this.parseSource(inputPath);
+      let presentation = await this.parseSource(inputPath);
       const citationIds = this.collectCitations(presentation);
       await this.resolveReferences(citationIds);
+      presentation = await this.processBibliography(presentation, citationIds);
       const transformedSlides = await this.transformSlides(presentation);
       const output = this.render(transformedSlides, presentation);
       if (options?.outputPath) {
@@ -1386,9 +1464,10 @@ var Pipeline = class {
   async runWithResult(inputPath, options) {
     this.warnings = [];
     try {
-      const presentation = await this.parseSource(inputPath);
+      let presentation = await this.parseSource(inputPath);
       const citationIds = this.collectCitations(presentation);
       await this.resolveReferences(citationIds);
+      presentation = await this.processBibliography(presentation, citationIds);
       const transformedSlides = await this.transformSlides(presentation);
       const output = this.render(transformedSlides, presentation);
       if (options?.outputPath) {
@@ -1464,6 +1543,13 @@ var Pipeline = class {
     if (!this.config.references.enabled || ids.length === 0) {
       return /* @__PURE__ */ new Map();
     }
+    const isAvailable = await this.referenceManager.isAvailable();
+    if (!isAvailable) {
+      this.warnings.push(
+        "reference-manager CLI is not available. Install it to enable citation features: npm install -g @ncukondo/reference-manager"
+      );
+      return /* @__PURE__ */ new Map();
+    }
     try {
       const items = await this.referenceManager.getByIds(ids);
       for (const id of ids) {
@@ -1512,10 +1598,97 @@ var Pipeline = class {
       );
     }
   }
+  /**
+   * Process bibliography slides with autoGenerate: true
+   * Populates references array from collected citations
+   */
+  async processBibliography(presentation, citationIds) {
+    if (!this.config.references.enabled || citationIds.length === 0) {
+      return presentation;
+    }
+    const hasBibliographyAutoGenerate = presentation.slides.some(
+      (slide) => slide.template === "bibliography" && slide.content?.["autoGenerate"] === true
+    );
+    if (!hasBibliographyAutoGenerate) {
+      return presentation;
+    }
+    const isAvailable = await this.referenceManager.isAvailable();
+    if (!isAvailable) {
+      return presentation;
+    }
+    try {
+      const updatedSlides = await Promise.all(
+        presentation.slides.map(async (slide) => {
+          if (slide.template === "bibliography" && slide.content?.["autoGenerate"] === true) {
+            const sort = slide.content["sort"] || "citation-order";
+            const result = await this.bibliographyGenerator.generate(
+              citationIds,
+              { sort }
+            );
+            for (const id of result.missing) {
+              this.warnings.push(`Bibliography: reference not found: ${id}`);
+            }
+            const references = result.items.map((item) => ({
+              id: item.id,
+              authors: this.formatAuthorsForTemplate(item.author),
+              title: item.title || "",
+              year: this.getYear(item),
+              journal: item["container-title"],
+              volume: item.volume,
+              pages: item.page,
+              doi: item.DOI,
+              url: item.URL
+            }));
+            return {
+              ...slide,
+              content: {
+                ...slide.content,
+                references,
+                _autoGenerated: true,
+                _generatedEntries: result.entries
+              }
+            };
+          }
+          return slide;
+        })
+      );
+      return {
+        ...presentation,
+        slides: updatedSlides
+      };
+    } catch (error) {
+      this.warnings.push(
+        `Failed to auto-generate bibliography: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      return presentation;
+    }
+  }
+  /**
+   * Format authors for template-compatible format
+   */
+  formatAuthorsForTemplate(authors) {
+    if (!authors || authors.length === 0) {
+      return void 0;
+    }
+    return authors.map((a) => {
+      const initial = a.given ? `${a.given.charAt(0)}.` : "";
+      return initial ? `${a.family}, ${initial}` : a.family;
+    });
+  }
+  /**
+   * Get year from CSL item
+   */
+  getYear(item) {
+    const dateParts = item.issued?.["date-parts"];
+    if (dateParts && dateParts[0] && dateParts[0][0]) {
+      return dateParts[0][0];
+    }
+    return void 0;
+  }
 };
 
 // src/index.ts
-var VERSION = "0.2.5";
+var VERSION = "0.4.0";
 
 // src/cli/commands/convert.ts
 import { Command } from "commander";
@@ -2593,12 +2766,167 @@ import { dirname as dirname3 } from "path";
 import chalk2 from "chalk";
 import ora2 from "ora";
 import { parse as parseYaml6, stringify as yamlStringify } from "yaml";
+
+// src/references/validator.ts
+var ReferenceValidator = class {
+  constructor(manager) {
+    this.manager = manager;
+  }
+  extractor = new CitationExtractor();
+  availableCache = null;
+  /**
+   * Check if reference-manager is available (cached)
+   */
+  async checkAvailable() {
+    if (this.availableCache === null) {
+      this.availableCache = await this.manager.isAvailable();
+    }
+    return this.availableCache;
+  }
+  async validateCitations(citationIds) {
+    const available = await this.checkAvailable();
+    if (!available) {
+      return {
+        valid: true,
+        found: [],
+        missing: [],
+        skipped: true,
+        reason: "reference-manager CLI is not available"
+      };
+    }
+    if (citationIds.length === 0) {
+      return {
+        valid: true,
+        found: [],
+        missing: []
+      };
+    }
+    const references = await this.manager.getByIds(citationIds);
+    const found = [];
+    const missing = [];
+    for (const id of citationIds) {
+      if (references.has(id)) {
+        found.push(id);
+      } else {
+        missing.push(id);
+      }
+    }
+    return {
+      valid: missing.length === 0,
+      found,
+      missing
+    };
+  }
+  async validateWithLocations(slides) {
+    const available = await this.checkAvailable();
+    if (!available) {
+      return {
+        valid: true,
+        found: [],
+        missing: [],
+        skipped: true,
+        reason: "reference-manager CLI is not available",
+        missingDetails: []
+      };
+    }
+    const citationLocations = /* @__PURE__ */ new Map();
+    const allCitationIds = [];
+    for (let i = 0; i < slides.length; i++) {
+      const slide = slides[i];
+      const slideNumber = i + 1;
+      const citations = this.extractor.extractFromSlide(slide);
+      for (const citation of citations) {
+        if (!citationLocations.has(citation.id)) {
+          citationLocations.set(citation.id, []);
+          allCitationIds.push(citation.id);
+        }
+        const text = this.findCitationText(slide, citation.id);
+        citationLocations.get(citation.id).push({
+          slide: slideNumber,
+          text
+        });
+      }
+    }
+    if (allCitationIds.length === 0) {
+      return {
+        valid: true,
+        found: [],
+        missing: [],
+        missingDetails: []
+      };
+    }
+    const references = await this.manager.getByIds(allCitationIds);
+    const found = [];
+    const missing = [];
+    const missingDetails = [];
+    for (const id of allCitationIds) {
+      if (references.has(id)) {
+        found.push(id);
+      } else {
+        missing.push(id);
+        missingDetails.push({
+          id,
+          locations: citationLocations.get(id) || []
+        });
+      }
+    }
+    return {
+      valid: missing.length === 0,
+      found,
+      missing,
+      missingDetails
+    };
+  }
+  /**
+   * Generate suggestions for adding missing references
+   */
+  static generateSuggestions(missingIds) {
+    if (missingIds.length === 0) {
+      return "";
+    }
+    const lines = [
+      "Missing citations:",
+      ...missingIds.map((id) => `  - @${id}`),
+      "",
+      "To add these references, use:",
+      "  ref add --pmid <pmid>     # Add by PubMed ID",
+      '  ref add "<doi>"           # Add by DOI',
+      "  ref add --isbn <isbn>     # Add by ISBN"
+    ];
+    return lines.join("\n");
+  }
+  findCitationText(slide, citationId) {
+    const searchValue = (value) => {
+      if (typeof value === "string") {
+        if (value.includes(`@${citationId}`)) {
+          return value;
+        }
+      } else if (Array.isArray(value)) {
+        for (const item of value) {
+          const found = searchValue(item);
+          if (found) return found;
+        }
+      } else if (value && typeof value === "object") {
+        for (const v of Object.values(value)) {
+          const found = searchValue(v);
+          if (found) return found;
+        }
+      }
+      return null;
+    };
+    return searchValue(slide.content) || `@${citationId}`;
+  }
+};
+
+// src/cli/commands/validate.ts
 function getHintForErrorType(errorType) {
   switch (errorType) {
     case "unknown_template":
       return "Run `slide-gen templates list --format llm` to see available templates.";
     case "unknown_icon":
       return "Run `slide-gen icons search <query>` to find icons.";
+    case "missing_reference":
+      return 'Run `ref add --pmid <pmid>` or `ref add "<doi>"` to add the reference.';
     default:
       return null;
   }
@@ -2660,7 +2988,9 @@ async function executeValidate(inputPath, options) {
       slideCount: 0,
       templatesFound: false,
       iconsResolved: false,
-      referencesCount: 0
+      referencesCount: 0,
+      referencesValidated: false,
+      missingReferences: []
     }
   };
   try {
@@ -2841,15 +3171,45 @@ ${formatExampleAsYaml(template.example, 2)}` : void 0;
         }
       }
     }
-    const citationPattern = /@([a-zA-Z0-9_-]+)/g;
-    const references = /* @__PURE__ */ new Set();
-    for (const slide of presentation.slides) {
-      const contentStr = JSON.stringify(slide.content);
-      for (const match of contentStr.matchAll(citationPattern)) {
-        references.add(match[1]);
+    const citationExtractor = new CitationExtractor();
+    const extractedCitations = citationExtractor.extractFromPresentation(presentation);
+    const citationIds = citationExtractor.getUniqueIds(extractedCitations);
+    result.stats.referencesCount = citationIds.length;
+    if (config.references?.enabled && citationIds.length > 0) {
+      const refManager = new ReferenceManager();
+      const refValidator = new ReferenceValidator(refManager);
+      const refValidationResult = await refValidator.validateWithLocations(
+        presentation.slides
+      );
+      if (refValidationResult.skipped) {
+        result.warnings.push(
+          `Reference validation skipped: ${refValidationResult.reason}`
+        );
+      } else {
+        result.stats.referencesValidated = true;
+        result.stats.missingReferences = refValidationResult.missing;
+        if (!refValidationResult.valid) {
+          for (const missingDetail of refValidationResult.missingDetails) {
+            for (const location of missingDetail.locations) {
+              const slideLine = result.slideLines[location.slide - 1];
+              result.warnings.push(
+                `Citation not found in library: ${missingDetail.id} (Slide ${location.slide})`
+              );
+              const structuredError = {
+                slide: location.slide,
+                template: presentation.slides[location.slide - 1]?.template || "unknown",
+                message: `Citation not found in library: ${missingDetail.id}`,
+                errorType: "missing_reference"
+              };
+              if (slideLine !== void 0) {
+                structuredError.line = slideLine;
+              }
+              result.structuredErrors.push(structuredError);
+            }
+          }
+        }
       }
     }
-    result.stats.referencesCount = references.size;
     if (result.errors.length > 0) {
       result.valid = false;
     }
@@ -2885,7 +3245,16 @@ function outputResult(result, options) {
           valid: result.valid,
           errors: result.errors,
           warnings: result.warnings,
-          stats: result.stats
+          stats: {
+            yamlSyntax: result.stats.yamlSyntax,
+            metaValid: result.stats.metaValid,
+            slideCount: result.stats.slideCount,
+            templatesFound: result.stats.templatesFound,
+            iconsResolved: result.stats.iconsResolved,
+            referencesCount: result.stats.referencesCount,
+            referencesValidated: result.stats.referencesValidated,
+            missingReferences: result.stats.missingReferences
+          }
         },
         null,
         2
@@ -2922,6 +3291,22 @@ function outputResult(result, options) {
   if (result.stats.referencesCount > 0) {
     console.log(chalk2.green("\u2713") + ` ${result.stats.referencesCount} references found`);
   }
+  if (result.stats.referencesValidated) {
+    if (result.stats.missingReferences.length === 0) {
+      console.log(chalk2.green("\u2713") + " All references validated");
+    } else {
+      console.log(
+        chalk2.yellow("\u26A0") + ` ${result.stats.missingReferences.length} reference(s) not found in library`
+      );
+      const suggestions = ReferenceValidator.generateSuggestions(
+        result.stats.missingReferences
+      );
+      if (suggestions) {
+        console.log("");
+        console.log(chalk2.dim(suggestions));
+      }
+    }
+  }
   for (const error of result.errors) {
     console.log(chalk2.red("\u2717") + ` ${error}`);
   }
@@ -2952,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";
@@ -2962,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 });
@@ -3128,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",
@@ -3181,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);
     });
   });
 }
@@ -3198,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(
@@ -3215,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...");
@@ -3313,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 };
 }
@@ -3351,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(
@@ -3366,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...");
@@ -3380,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 });
@@ -3390,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) {
@@ -3444,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 {
     }
   };
@@ -3460,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 {
@@ -4011,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() {
@@ -4810,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";
@@ -4889,14 +5286,105 @@ var missingItemSchema = z8.object({
   status: z8.string().optional(),
   notes: z8.string().optional()
 });
+var referenceItemSchema = z8.object({
+  id: z8.string(),
+  status: z8.enum(["pending", "added", "existing"]),
+  slide: z8.number(),
+  purpose: z8.string(),
+  requirement: z8.enum(["required", "recommended"]).optional(),
+  added_date: z8.string().optional(),
+  suggested_search: z8.array(z8.string()).optional(),
+  notes: z8.string().optional()
+});
+var referencesStatusSchema = z8.object({
+  required: z8.number().default(0),
+  found: z8.number().default(0),
+  pending: z8.number().default(0)
+});
+var referencesSectionSchema = z8.object({
+  status: referencesStatusSchema.optional(),
+  items: z8.array(referenceItemSchema).default([])
+});
 var sourcesYamlSchema = z8.object({
   project: projectSchema,
   context: contextSchema.optional(),
   sources: z8.array(sourceEntrySchema).optional(),
   dependencies: z8.record(dependencySchema).optional(),
-  missing: z8.array(missingItemSchema).optional()
+  missing: z8.array(missingItemSchema).optional(),
+  references: referencesSectionSchema.optional()
 });
 
+// src/sources/references-tracker.ts
+var ReferencesTracker = class {
+  items = [];
+  constructor(initial) {
+    if (initial?.items) {
+      this.items = [...initial.items];
+    }
+  }
+  /**
+   * Add a pending reference that needs to be found
+   */
+  addPending(ref) {
+    this.items.push({
+      ...ref,
+      status: "pending"
+    });
+  }
+  /**
+   * Mark a pending reference as added with its actual citation key
+   */
+  markAdded(pendingId, actualId) {
+    const item = this.items.find((i) => i.id === pendingId);
+    if (item) {
+      item.id = actualId;
+      item.status = "added";
+      item.added_date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    }
+  }
+  /**
+   * Mark a reference as existing in the bibliography
+   */
+  markExisting(ref) {
+    this.items.push({
+      ...ref,
+      status: "existing"
+    });
+  }
+  /**
+   * Get all reference items
+   */
+  getItems() {
+    return [...this.items];
+  }
+  /**
+   * Get only pending references
+   */
+  getPending() {
+    return this.items.filter((i) => i.status === "pending");
+  }
+  /**
+   * Calculate status summary
+   */
+  getStatus() {
+    const required = this.items.filter(
+      (i) => i.requirement === "required"
+    ).length;
+    const pending = this.items.filter((i) => i.status === "pending").length;
+    const found = this.items.filter((i) => i.status !== "pending").length;
+    return { required, found, pending };
+  }
+  /**
+   * Convert to YAML-compatible object
+   */
+  toYaml() {
+    return {
+      status: this.getStatus(),
+      items: this.items
+    };
+  }
+};
+
 // src/sources/manager.ts
 var SourcesManager = class _SourcesManager {
   sourcesDir;
@@ -5071,6 +5559,44 @@ var SourcesManager = class _SourcesManager {
     const data = await this.load();
     return data.sources?.filter((s) => s.type === type) ?? [];
   }
+  /**
+   * Get references from sources.yaml
+   */
+  async getReferences() {
+    const data = await this.load();
+    const tracker = new ReferencesTracker(data.references);
+    return tracker.toYaml();
+  }
+  /**
+   * Add a pending reference that needs to be found
+   */
+  async addPendingReference(ref) {
+    const data = await this.load();
+    const tracker = new ReferencesTracker(data.references);
+    tracker.addPending(ref);
+    data.references = tracker.toYaml();
+    await this.save(data);
+  }
+  /**
+   * Mark a pending reference as added with its actual citation key
+   */
+  async markReferenceAdded(pendingId, actualId) {
+    const data = await this.load();
+    const tracker = new ReferencesTracker(data.references);
+    tracker.markAdded(pendingId, actualId);
+    data.references = tracker.toYaml();
+    await this.save(data);
+  }
+  /**
+   * Mark a reference as existing in the bibliography
+   */
+  async markReferenceExisting(ref) {
+    const data = await this.load();
+    const tracker = new ReferencesTracker(data.references);
+    tracker.markExisting(ref);
+    data.references = tracker.toYaml();
+    await this.save(data);
+  }
 };
 
 // src/sources/importer.ts
@@ -5467,6 +5993,51 @@ allowed-tools: Read Write Edit Bash Glob Grep
 
 Helps create Marp slides using the slide-gen CLI tool.
 
+## First Question
+
+**Always start by asking about the user's material situation:**
+
+> "Let's create slides. What materials do you have?
+>
+> A) I have detailed materials organized in a directory
+>    (scenarios, scripts, data files, images, etc.)
+>
+> B) I have partial materials like a scenario or script
+>    (but need to supplement with additional info)
+>
+> C) I don't have materials yet
+>    (starting from scratch, will collect info through dialogue)"
+
+Then follow the appropriate pattern below.
+
+## Workflow Patterns
+
+### Pattern A: Explore Mode (Detailed Materials Exist)
+
+When user has materials organized in a directory:
+1. Ask for directory path and scan with Glob
+2. Read and classify files (scenario, scripts, data, images)
+3. Summarize findings and confirm with user
+4. Configure \`sources/\` directory
+
+### Pattern B: Supplement Mode (Partial Materials)
+
+When user has only a scenario or partial materials:
+1. Read and analyze provided content
+2. Identify what's present vs. missing
+3. Ask targeted questions to fill gaps
+4. Configure \`sources/\` directory
+
+### Pattern C: Interview Mode (Starting from Scratch)
+
+When user has no materials:
+1. Ask basic questions (purpose, audience, duration)
+2. Collect data and examples
+3. Propose slide structure for approval
+4. Configure \`sources/\` directory
+
+**See [references/workflows.md](references/workflows.md) for detailed steps.**
+
 ## Capabilities
 
 1. **Project initialization**: \`slide-gen init\`
@@ -5476,21 +6047,14 @@ Helps create Marp slides using the slide-gen CLI tool.
 5. **Conversion**: \`slide-gen convert\`
 6. **Screenshot**: \`slide-gen screenshot\` (for AI review)
 
-## Workflow
-
-### New Project
-
-1. Run \`slide-gen init <directory>\` to initialize
-2. Gather requirements from user
-3. Check templates with \`slide-gen templates list --format llm\`
-4. Create presentation.yaml
-5. Validate and convert
+## Slide Creation Flow
 
-### Existing Project
+After material collection (Pattern A/B/C above):
 
-1. Read presentation.yaml
-2. Edit according to user request
-3. Validate and convert
+1. Check templates with \`slide-gen templates list --format llm\`
+2. Create presentation.yaml
+3. Validate: \`slide-gen validate presentation.yaml\`
+4. Convert: \`slide-gen convert presentation.yaml\`
 
 ## YAML Source Format
 
@@ -5573,6 +6137,76 @@ The \`validate --format llm\` command provides:
 - Error locations with line numbers
 - 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:
+
+1. **Analyze** content for citation needs
+2. **Search** existing library: \`ref search\`
+3. **Add** new references: \`ref add pmid:XXX\`
+4. **Validate** citations: \`slide-gen validate\`
+
+See \`.skills/slide-assistant/references/skill.md\` for detailed workflow.
+
+### Quick Commands
+
+\`\`\`bash
+# Search library
+ref search "keyword" --format json
+
+# Add from PMID
+ref add pmid:38941256
+
+# Add from DOI
+ref add "10.1038/xxxxx"
+
+# Validate citations
+slide-gen validate presentation.yaml
+\`\`\`
 `;
 }
 
@@ -5633,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.
 `;
 }
 
@@ -5835,31 +6486,72 @@ Image with text side by side.
 function generateWorkflowsRef() {
   return `# Workflow Reference
 
+## Entry Point
+
+**Always start by asking this question:**
+
+> "Let's create slides. What materials do you have?
+>
+> A) I have detailed materials organized in a directory
+>    (scenarios, scripts, data files, images, etc.)
+>
+> B) I have partial materials like a scenario or script
+>    (but need to supplement with additional info)
+>
+> C) I don't have materials yet
+>    (starting from scratch, will collect info through dialogue)"
+
+Based on the answer, follow the appropriate pattern below.
+
 ## Source Collection Flow
 
-### Pattern A: Directory Exploration
-When user has materials in a directory:
-1. Ask for directory path
-2. Scan with Glob tool
-3. Read and classify files
-4. Summarize and confirm with user
-5. Create sources/sources.yaml
-
-### Pattern B: Supplement Mode
-When user has partial materials:
-1. Read provided file/text
-2. Analyze content
-3. Identify missing information
-4. Ask supplementary questions
-5. Create sources/sources.yaml
-
-### Pattern C: Interview Mode
+### Pattern A: Explore Mode (Detailed Materials Exist)
+
+When user has materials organized in a directory:
+
+1. **Ask for the directory path**
+2. **Scan directory structure** with Glob tool
+3. **Read and analyze each file**
+4. **Classify files** into categories:
+   - Scenario/scripts
+   - Data files (CSV, JSON, etc.)
+   - Images and diagrams
+   - Reference documents
+5. **Summarize findings** and confirm with user
+6. **Ask clarifying questions** about gaps
+7. **Configure \`sources/\` directory** with organized materials
+8. Proceed to slide creation
+
+### Pattern B: Supplement Mode (Partial Materials)
+
+When user has only a scenario or partial materials:
+
+1. **Ask user** to provide the file path or paste content
+2. **Analyze the content** thoroughly
+3. **Identify what information is present** vs. missing
+4. **Ask targeted questions** to fill gaps:
+   - Purpose and audience
+   - Duration and format
+   - Key messages
+   - Available data/examples
+5. **Load any additional files** user mentions
+6. **Configure \`sources/\` directory**
+7. Proceed to slide creation
+
+### Pattern C: Interview Mode (Starting from Scratch)
+
 When user has no materials:
-1. Ask basic questions (purpose, audience, duration)
-2. Deep-dive based on purpose
-3. Propose slide structure
-4. Iterate based on feedback
-5. Create sources/sources.yaml
+
+1. **Ask basic questions**:
+   - "What is this presentation about?"
+   - "Who is the audience?"
+   - "How long is the presentation?"
+2. **Ask purpose-specific questions** (proposal, report, introduction, etc.)
+3. **Collect data and examples** user can provide
+4. **Propose slide structure** for approval
+5. **Incorporate feedback**
+6. **Configure \`sources/\` directory** from conversation
+7. Proceed to slide creation
 
 ## Slide Creation Flow
 
@@ -5908,6 +6600,221 @@ 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 |
+`;
+}
+
+// src/cli/templates/ai/references/skill-references.ts
+function generateReferenceSkillMd() {
+  return `## Reference Management Skill
+
+### When to Invoke
+
+Use this skill when:
+- Creating academic or research presentations
+- User mentions needing citations or references
+- Scenario contains statistical claims or research findings
+- User provides literature (URL, PDF, DOI, PMID)
+
+### Citation Requirement Analysis
+
+Analyze scenario/script for statements requiring citations:
+
+| Statement Type | Requirement | Example |
+|---------------|-------------|---------|
+| Statistical claims | Required | "Accuracy exceeds 90%" |
+| Research findings | Required | "Studies show that..." |
+| Methodology references | Required | "Using the XYZ method" |
+| Comparative claims | Recommended | "Better than conventional" |
+| Historical facts | Recommended | "First introduced in 2020" |
+| General knowledge | Not required | "AI is widely used" |
+
+### Workflow
+
+#### Phase 1: Analyze Content
+1. Read scenario/script thoroughly
+2. Identify statements requiring citations
+3. Categorize as Required or Recommended
+4. Note the slide number and exact statement
+
+#### Phase 2: Search Existing Library
+\`\`\`bash
+# List all references
+ref list --format json
+
+# Search by keyword
+ref search "diagnostic accuracy" --format json
+\`\`\`
+
+#### Phase 3: Match or Request
+
+**If found in library:**
+- Confirm relevance with user
+- Insert \`[@id]\` citation in YAML
+
+**If not found:**
+- Present clear request to user
+- Specify what type of source is needed
+- Provide suggested search terms
+
+#### Phase 4: Add New References
+
+From user-provided input:
+
+\`\`\`bash
+# From PMID
+ref add pmid:38941256
+
+# From DOI
+ref add "10.1038/s41591-024-xxxxx"
+
+# From ISBN
+ref add "ISBN:978-4-00-000000-0"
+
+# From BibTeX file
+ref add paper.bib
+\`\`\`
+
+#### Phase 5: Insert Citations
+
+Update presentation.yaml:
+\`\`\`yaml
+items:
+  - "This claim is supported [@smith2024]"
+\`\`\`
+
+### Extracting from Non-Standard Input
+
+#### URL Patterns
+- PubMed: Extract PMID from \`pubmed.ncbi.nlm.nih.gov/XXXXXXXX\`
+- DOI: Extract from \`doi.org/10.XXXX/XXXXX\`
+- Publisher sites: Fetch page, extract DOI from metadata
+
+#### PDF Files
+1. Read PDF file
+2. Extract DOI from first page or metadata
+3. If not found, extract title and search databases
+
+#### Free Text
+1. Parse author, year, journal information
+2. Search PubMed/CrossRef
+3. Present candidates for user confirmation
+
+### User Communication Templates
+
+**Analyzing content:**
+\`\`\`
+I've analyzed your scenario and identified citation needs:
+
+Required Citations (N)
+----------------------
+1. Slide X: '[statement]'
+   -> Needs: [type of source]
+
+Recommended Citations (M)
+-------------------------
+...
+
+Let me check your reference library...
+\`\`\`
+
+**Requesting references:**
+\`\`\`
+I need your help finding references:
+
+[REQUIRED] Reference 1: [Topic]
+-------------------------------
+Purpose: Support claim '[statement]' on Slide X
+
+Ideal source type:
+- [type1]
+- [type2]
+
+Suggested search terms:
+- [term1]
+- [term2]
+
+How to provide:
+A) DOI or PMID (e.g., 'PMID: 38941256')
+B) URL (PubMed, journal site, etc.)
+C) PDF file
+D) Manual citation details
+\`\`\`
+
+**Confirming addition:**
+\`\`\`
+Reference added successfully:
+-----------------------------
+Citation key: [@id]
+Authors: ...
+Title: '...'
+Journal: ...
+Year: XXXX
+
+I'll use this for Slide X.
+\`\`\`
 `;
 }
 
@@ -6032,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
 
-## After Screenshot
+Use \`--format ai\` for token-efficient screenshots:
+- 640px width (75% token reduction)
+- JPEG format
+- Shows estimated token consumption
 
-Read the screenshot images to review slide content and provide feedback.
+\`\`\`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
+
+| Format | Width | Est. Tokens/slide |
+|--------|-------|-------------------|
+| png/jpeg | 1280 | ~1,229 |
+| ai | 640 | ~308 (~75% reduction) |
+
+## 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
+\`\`\`
 `;
 }
 
@@ -6070,9 +7087,75 @@ function generateSlideThemeCommand() {
 `;
 }
 
+// src/cli/templates/ai/commands/slide-references.ts
+function generateSlideReferencesCommand() {
+  return `Manage references and citations for the presentation.
+
+## Available Actions
+
+### 1. Analyze - Find citation needs
+Analyze the scenario/content for statements that need citations.
+
+### 2. Search - Find in library
+Search existing reference-manager library for relevant papers.
+
+### 3. Add - Add new reference
+Add a reference from PMID, DOI, URL, or file.
+
+### 4. List - Show all references
+List all references currently in the library.
+
+## Usage
+
+### Analyze scenario for citation needs:
+\`\`\`bash
+# First, read the presentation
+cat presentation.yaml
+
+# Then analyze content for citation requirements
+\`\`\`
+Report statements needing citations with slide numbers.
+
+### Search library:
+\`\`\`bash
+ref search "keyword" --format json
+ref list --format json
+\`\`\`
+
+### Add reference:
+\`\`\`bash
+# From PMID
+ref add pmid:38941256
+
+# From DOI
+ref add "10.1038/s41591-024-xxxxx"
+
+# From URL (extract identifier first)
+# PubMed URL -> extract PMID
+# DOI URL -> extract DOI
+
+# From file
+ref add paper.bib
+ref add export.ris
+\`\`\`
+
+### Validate citations:
+\`\`\`bash
+slide-gen validate presentation.yaml
+\`\`\`
+
+## Notes
+
+- Always check library before requesting new references
+- Extract PMID/DOI from URLs before adding
+- Report missing citations with suggested search terms
+- Update presentation.yaml with [@id] format
+`;
+}
+
 // 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, "..", "..", "..");
   }
@@ -6085,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;
@@ -6134,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;
@@ -6159,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`);
@@ -6243,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");
       }
     });
   });
@@ -6366,27 +7450,37 @@ 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()
-  );
+  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-theme": generateSlideThemeCommand
+    "slide-review": generateSlideReviewCommand,
+    "slide-theme": generateSlideThemeCommand,
+    "slide-references": generateSlideReferencesCommand
   };
   for (const [name, generator] of Object.entries(commandGenerators)) {
     await writeFileIfNotExists(
@@ -6497,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 {
@@ -6530,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`);
 }
@@ -6592,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);
@@ -6661,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 {
@@ -6676,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() {
@@ -6699,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) {
@@ -6799,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) {
@@ -6999,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 });
@@ -7097,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}`;
@@ -7119,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 {
@@ -7130,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);
   });
 }
@@ -7167,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}`));
@@ -7189,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");
@@ -7210,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 {
     }
   };
@@ -7233,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}`);
@@ -7246,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");
@@ -7266,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() {
@@ -7328,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);
@@ -7344,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,
@@ -7358,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;
@@ -7390,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);
@@ -7450,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()) {
@@ -7499,6 +8749,26 @@ async function executeSourcesStatus(projectDir, _options) {
         output += "\n";
       }
     }
+    const refs = await manager.getReferences();
+    if (refs.items.length > 0) {
+      output += "\n";
+      output += chalk10.cyan("References:\n");
+      output += `  Required: ${refs.status?.required ?? 0}
+`;
+      output += `  Found: ${refs.status?.found ?? 0}
+`;
+      output += `  Pending: ${refs.status?.pending ?? 0}
+`;
+      const pendingRefs = refs.items.filter((i) => i.status === "pending");
+      if (pendingRefs.length > 0) {
+        output += "\n";
+        output += chalk10.yellow("  \u26A0 Pending references:\n");
+        for (const ref of pendingRefs) {
+          output += `    - ${ref.id} (Slide ${ref.slide}): ${ref.purpose}
+`;
+        }
+      }
+    }
     if (data.project.updated) {
       output += "\n";
       output += chalk10.gray(`Last updated: ${data.project.updated}
@@ -7517,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()) {