@ncukondo/slide-generation 0.2.5 → 0.3.0

package/dist/cli/index.js

@@ -923,20 +923,20 @@ 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;
   }
@@ -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.3.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}`);
   }
@@ -4889,14 +5274,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 +5547,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 +5981,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 +6035,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 +6125,33 @@ The \`validate --format llm\` command provides:
 - Error locations with line numbers
 - Fix examples from template definitions
 - Contextual hints for unknown templates/icons
+
+## 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
+\`\`\`
 `;
 }
 
@@ -5835,31 +6414,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
 
@@ -5911,6 +6531,158 @@ Handle adjustments (cropping, replacement) as needed.
 `;
 }
 
+// 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.
+\`\`\`
+`;
+}
+
 // src/cli/templates/ai/commands/slide-create.ts
 function generateSlideCreateCommand() {
   return `Create slides from user requirements.
@@ -6070,6 +6842,72 @@ 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));
@@ -6380,13 +7218,18 @@ async function generateAiConfig(targetDir) {
     join16(targetDir, ".skills", "slide-assistant", "references", "workflows.md"),
     generateWorkflowsRef()
   );
+  await writeFileIfNotExists(
+    join16(targetDir, ".skills", "slide-assistant", "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-theme": generateSlideThemeCommand,
+    "slide-references": generateSlideReferencesCommand
   };
   for (const [name, generator] of Object.entries(commandGenerators)) {
     await writeFileIfNotExists(
@@ -7499,6 +8342,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}