@ohos-ports/slides-grab 1.5.0-beta.0

package/skills/slides-grab-image/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: slides-grab-image
+description: Image-native presentation pipeline usable in Codex and Claude Code. Generate whole-slide raster images one slide at a time with slides-grab image, passing the reference template page as --reference so the model copies the layout and style and only swaps the content. Use when visual fidelity to an existing template matters more than editable text.
+metadata:
+  short-description: Image-native pipeline — per-slide raster generation with template reference
+---
+
+# slides-grab Image Skill
+
+Generate whole-slide raster images where the generated PNG **is** the slide. Each slide is generated individually with `slides-grab image`, passing the matching reference template page image(s) via `--reference` so the model reproduces the template's layout, colors, fonts, and density — only swapping in the new slide's content. Use this pipeline when the user wants to match an existing corporate template, filled deck, or brand form visually.
+
+## Mode signal
+The plan stage records `mode: image-native` in `slide-outline.md`. The user typically provides a reference template (PPTX, PDF, HTML examples) and says "make slides in this form."
+
+## Core rule: reference-guided per-slide generation
+- **Generate one slide at a time** with `slides-grab image`. Do NOT use `slides-grab generate-images` (the batch command auto-assembles garbage prompts from markdown and produces inconsistent output).
+- **Always pass at least one reference template page image** via `--reference <path>` (repeatable). The reference page(s) must be the same slide-type (cover, content, closing) from the source template. The model must copy the reference's layout, color bands, typography hierarchy, whitespace, and density — only the text content and any embedded photos change.
+- The prompt must explicitly instruct: *"Follow the reference image's layout, composition, color palette, and typography hierarchy exactly. Keep the same band positions, spacing, and visual rhythm. Only replace the text content and photos with the new slide's content below."*
+- Pass any real photos/assets to embed as additional `--reference` images so the model can place them into the template layout.
+
+## Prompt structure (use this pattern)
+```
+slides-grab image \
+  --prompt "Follow the reference image layout exactly — same color bands, same typography hierarchy, same spacing and density. This is a [cover/content/closing] slide. Replace the text with: Title: '<new title>'. Body: '<new body text>'. Bullets: <bullet list>. Keep the template's visual style, fonts, and color palette. Render all text sharp and legible. 16:9, 720pt × 405pt." \
+  --slides-dir <path> \
+  --reference <template-page-cover.png> \
+  --reference <real-photo-to-embed.png>
+```
+
+Key prompt principles:
+- **Describe the content to inject**, not the visual design — the reference image defines the design.
+- Name the slide type (cover, content, closing, stat) so the model picks the right reference density.
+- List the exact title, body, and bullets as literal strings the model should render.
+- If embedding real photos, name them in the prompt ("place photo-1 in the left grid cell") and pass them as `--reference`.
+- Require sharp, legible, correctly spelled text.
+
+## Workflow
+
+### Stage 1 — Plan (template-driven dense outline)
+Use the installed **slides-grab-plan** skill with image-native outline density rules.
+1. Take topic, audience, and tone.
+2. If the user provides a reference template/PDF/PPTX, import it with `slides-grab import-template --input <path>`. Also render the template pages to PNG (e.g. `pdftoppm -png -r 150 <input>.pdf <prefix>`) and store under `<slides-dir>/.slides-grab/template-previews/`. These page renders are the `--reference` images for Stage 2.
+3. **Read the template pages in order** (page-01, page-02, ...). For each page, identify its layout type and information density — how many text blocks, data points, bullets, captions, and visual elements it carries. This is the critical step: the outline must match the template's per-slide density, not write a thin HTML-style summary.
+4. **Write a dense outline**: one outline slide per template page, carrying the full content the user wants — titles, subtitles, body paragraphs, full bullet lists, stat values, table data, captions, and image placement notes — at the volume the template page demonstrates. Image-native slides are single rasters with no HTML structure limits, so they hold more text and data per slide than semantic HTML. Do not under-fill.
+5. Tag each outline slide with `template-page: NN` so Stage 2 knows which reference image to pass.
+6. Record `mode: image-native` and `style: template-pack` in `slide-outline.md` meta.
+7. Present outline, revise until approved.
+
+### Stage 2 — Design (per-slide image generation)
+1. Read approved `slide-outline.md`. For each slide, read its `template-page: NN` tag and pick that exact template page render from `.slides-grab/template-previews/page-NN.png` as the primary `--reference`. If the slide has no tag, pick 1–2 layout-similar pages by slide type (cover, content, stat, closing).
+2. For each slide, run `slides-grab image` with:
+   - `--prompt` containing ALL the content from the outline for that slide — the full title, subtitle, body paragraphs, every bullet, every stat value, every caption — not a summary. Precede the content with "Follow the reference image layout exactly — same color bands, same typography hierarchy, same spacing and density. Only replace the text content with the content below."
+   - `--reference` pointing to the matching template page render(s)
+   - `--reference` for any real photos to embed (member photos, product shots, logos)
+   - `--slides-dir <path>` and `--name slide-XX` (so the output is `assets/slide-XX.png`)
+   - `--image-native` so the command also writes the editor-compatible `slide-XX.html` wrapper and `.slides-grab/image-native/slide-XX.json` regeneration metadata
+   - `--provider codex` (default; reuses `~/.codex/auth.json`, run `codex login` once, no API key). Alternatives: `--provider openai` (OPENAI_API_KEY, gpt-image-2), `--provider nano-banana` (GOOGLE_API_KEY/GEMINI_API_KEY).
+3. Confirm each command reports `Created image-native slide wrapper: slide-XX.html`. Do not hand-write the wrapper; `--image-native` keeps the PNG, wrapper, and regeneration metadata contract aligned for `slides-grab edit-image`.
+4. Run `slides-grab validate --slides-dir <path>`. Auto-fix failures until it passes.
+5. Run the design gate (`../slides-grab-design/references/design-gate.md`): capture PNG evidence, run Pass A + Pass B, synthesize verdict. Resolve all Critical findings, re-generate the failing slide, re-render, re-review until `Proceed`. Record with `slides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <a.md> --pass-b-report <b.md>`.
+6. For revisions, regenerate the specific slide with `slides-grab image` (same `--reference`, adjusted `--prompt`), or launch the image-native editor with `slides-grab edit-image --slides-dir <path>`.
+
+### Stage 3 — Export
+Use the installed **slides-grab-export** skill. Requires a fresh `Proceed` gate receipt.
+1. Widescreen → `slides-grab pdf --slides-dir <path> --output <name>.pdf`.
+2. Per-slide PNG → `slides-grab png --slides-dir <path> --output-dir <path>/out-png --resolution 2160p`.
+3. PPTX/Figma (experimental / unstable) → `slides-grab convert` / `slides-grab figma`.
+
+## Rules
+- Keep slide size 720pt × 405pt (16:9).
+- **Always pass `--reference` template page images** — never generate image-native slides from a text-only prompt. The reference defines the visual design; the prompt defines the content.
+- Generate one slide at a time with `slides-grab image`. Do not use `slides-grab generate-images`.
+- `slides-grab image --image-native --name slide-XX` writes the wrapper and regeneration metadata. Do not hand-write semantic text into wrapper slides.
+- Put generated assets under `<slides-dir>/assets/`, reference as `./assets/<file>`.
+- Allow `data:` URLs when a slide must be self-contained; never leave remote `http(s)://` image URLs in saved HTML.
+- Do not present slides for review until `slides-grab validate` passes.
+- Do not advance to export while any Critical design-gate finding is unresolved.
+
+## Reference
+- `../slides-grab-plan/SKILL.md` and `../slides-grab-plan/references/`
+- `../slides-grab-design/SKILL.md` and `../slides-grab-design/references/`
+- `../slides-grab-export/SKILL.md` and `../slides-grab-export/references/`

package/skills/slides-grab-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: slides-grab-plan
+description: Stage 1 planning skill usable in Codex and Claude Code. Build and iterate slide-outline.md until explicit user approval.
+metadata:
+  short-description: Create and revise slide outline before design stage
+---
+
+# slides-grab Plan Skill
+
+Use this when the user asks to start a new presentation from scratch.
+
+## Goal
+Produce an approved `slide-outline.md` before any slide HTML generation.
+
+## Inputs
+- Topic and intent
+- Audience
+- Tone and constraints
+- Optional research findings
+
+## Output
+- `slide-outline.md` (must include `style: <id>`, `style: template-pack`, or an approved custom style direction in meta section)
+- For chart-heavy decks, explicit chart slide notes: chart type, data source, key comparison, and whether the design stage should use the default Chart.js canvas template.
+
+## Workflow
+1. Analyze user goal and audience.
+2. **Style selection (mandatory, before outline):** Four paths are accepted, in priority order:
+   a. **Imported template pack** — when the user provides a corporate deck, reference slides, HTML examples, or brand images, run `slides-grab import-template --input <path> --slides-dir <slides-dir>` (repeat `--input` for multiple examples). Prefer filled representative decks/examples over empty master templates: filled examples reveal density, schema field limits, font resolution, and layout stress cases; an empty master alone is insufficient. Confirm the generated `<slides-dir>/.slides-grab/template-pack.json` is the intended reference source. Record as `style: template-pack`.
+   b. **Bundled style** — run `slides-grab list-styles`, shortlist 2–3 styles, and get explicit user approval. Optionally offer `slides-grab preview-styles` for visual preview. Record as `style: <id>`.
+   c. **Custom DESIGN.md path** — if a local `DESIGN.md` exists (e.g. provided directly or fetched via `slides-grab import-design <https-url>`), inspect it with `slides-grab show-design ./DESIGN.md` and confirm with the user.
+   d. **Free-form custom direction** — if neither imported template pack, bundled style, nor DESIGN.md fits, propose a written custom direction and get approval.
+3. **DESIGN.md → DESIGN.slides.md conversion (mandatory when path 2c was chosen):**
+   - A `DESIGN.md` imported from `voltagent/awesome-design-md` or similar sources describes a **marketing website** (top-nav, hero-band, CTA buttons, pricing cards, footer-band). Slides are **single 720pt × 405pt frames** with no scroll, no nav, no clicks — copying web components into slides produces deck pages that look like landing pages.
+   - Read `references/design-md-to-slides-conversion.md` for the canonical conversion guide.
+   - Translate the imported `./DESIGN.md` into a sibling `./DESIGN.slides.md` next to it. Leave the original `DESIGN.md` untouched. The `DESIGN.slides.md` MUST follow the Output Contract in the reference and apply every row of the web → slide mapping table (top-nav → eyebrow strip, hero-band → cover layout, CTA buttons → kicker text, footer-band → thin footer strip, pricing grids → dropped, etc.).
+   - Present a 5–10 line summary of the conversion to the user (kept tokens + dropped web sections + new slide layouts inferred) and wait for explicit approval before continuing.
+   - After approval, run `slides-grab show-design ./DESIGN.slides.md` to confirm the parser reads it cleanly.
+4. Create or revise `slide-outline.md` with ordered slides and key messages. Record the approved style reference in the meta section:
+   - bundled style → `style: <id>`
+   - converted DESIGN.slides.md → `style: ./DESIGN.slides.md`
+   - imported template pack → `style: template-pack` and keep `<slides-dir>/.slides-grab/template-pack.json` with its `.slides-grab/template-previews/` assets
+   - free-form custom direction → leave a one-paragraph `style:` block describing it
+   - for chart slides, name the intended chart type and data payload in the slide notes so Stage 2 can build a real Chart.js canvas instead of placeholder bars or decorative pseudo-charts
+   - delivery mode → `mode: html` for semantic slide HTML, or `mode: image-native` for raster wrapper slides generated from the approved template/style; prefer `image-native` for existing corporate templates/forms when the user asks for visual matching rather than editable HTML
+4b. **Image-native outline density (mandatory when mode: image-native and a template is provided):** When the user provides a reference template (PDF/PPTX) for image-native generation, do NOT write a thin HTML-style outline. Instead:
+   - Render the template pages to PNG and open them in order (page-01, page-02, ...).
+   - For each template page, identify its layout type (cover, section divider, content grid, stat tiles, table, timeline, closing) and measure its **information density** — how many distinct text blocks, data points, bullets, captions, and visual elements it carries.
+   - Write one outline slide per template page (or per logical template section), matching that page's layout type and information volume. If template page 3 has a 2×3 stat grid with 6 data points and 3 captions, the corresponding outline slide must also list 6 data points and 3 captions — not just a one-line summary.
+   - Image-native slides are single raster images with no HTML structure constraints, so they can hold **more text and data per slide** than semantic HTML. Pack the outline with the full content the user wants on each slide — titles, subtitles, body paragraphs, bullet lists, data tables, stat values, captions, and image placement notes — at the density the template page demonstrates.
+   - Tag each outline slide with its matching template page number (e.g. `template-page: 03`) so Stage 2 knows which `--reference` image to pass.
+   - The result should be a noticeably denser outline than HTML mode: more bullets, more data, more text per slide, matching what the template's filled pages actually carry.
+5. Present a concise summary to user.
+6. Repeat revisions until explicit approval.
+
+## Rules
+- **Do not write the outline before the user approves a style.** Style selection comes first.
+- Do not generate slide HTML (`<slides-dir>/slide-*.html`) in this stage.
+- Keep scope to structure, narrative, and style selection.
+- For quantitative stories, plan charts as evidence: identify the source values, comparison axis, baseline, and intended takeaway. Do not invent filler metrics just to fill a chart.
+- Ask for approval before moving to design.
+- Assume later stages run through the packaged `slides-grab` CLI.
+- Use the packaged CLI and bundled references only; do not depend on unpublished agent-specific files.
+
+## Reference
+If needed, use the bundled outline reference:
+- `references/outline-format.md`
+- `references/plan-workflow-reference.md` — archived detailed planning workflow and runtime-neutral outline-worker guidance
+- `references/design-md-to-slides-conversion.md` — DESIGN.md (web) → DESIGN.slides.md (slide) translation guide, including the structured output template and the web → slide mapping table

package/skills/slides-grab-plan/references/design-md-to-slides-conversion.md

@@ -0,0 +1,135 @@
+# DESIGN.md → DESIGN.slides.md Conversion
+
+Web-flavored `DESIGN.md` files (Google Stitch / voltagent/awesome-design-md
+convention) describe **marketing websites**: top-nav, hero-band, CTA buttons,
+pricing cards, footer-band, multi-section scrolling pages.
+
+A slide is a **720pt × 405pt single frame, no scroll, no clicks, no nav**.
+Pasting a web design system into slides produces deck pages that look like
+landing pages — wrong slot.
+
+This document is the canonical reference the agent uses to translate a
+DESIGN.md into a sibling `DESIGN.slides.md` that fits the slide medium.
+
+## Output contract
+
+The agent MUST produce a file named `DESIGN.slides.md` next to the source
+`DESIGN.md` at the deck root. The original `DESIGN.md` MUST be left untouched.
+
+`DESIGN.slides.md` MUST contain the following sections, in this order:
+
+```markdown
+---
+version: alpha
+name: <inherited from DESIGN.md `name`>
+description: <one-sentence slide-flavored mood — not a marketing paragraph>
+derived-from: <relative path to source DESIGN.md, e.g. ./DESIGN.md>
+medium: slides-16x9
+colors:
+  <token-name>: <#hex>
+---
+
+## Overview
+One short paragraph describing the slide deck's atmosphere — material, energy,
+typographic voice. No mention of pages, scroll, nav, CTA, pricing, or routes.
+
+## Background
+Solid fills only. List 1-3 canvas modes that alternate across slides.
+
+## Colors
+Markdown table of the slide-active palette. Drop any role that exists only
+for hover/focus/disabled states (those don't apply to static slides).
+
+## Typography
+Two faces: a display face for headlines and a body face for everything else.
+Optionally a mono face for eyebrows / IDs / code motifs. Include working
+font-stack fallbacks (Google Fonts that render in Playwright capture).
+
+## Slide Layouts
+Enumerate the slide archetypes this design system supports. ALWAYS include
+at least these five:
+- **Cover** — single dominant headline, no nav, no CTA buttons
+- **Section divider** — short anchor headline, optional eyebrow
+- **Content** — copy + single supporting visual (60/40 or 50/50 split)
+- **Statistic** — one oversized number, one short caption
+- **Closing** — final thesis line, footer/page-number strip
+
+For each layout, describe the dominant rhythm in 1-3 bullets — what scale
+carries the slide, what's allowed in the corners, what's NOT allowed.
+
+## Signature Motifs
+Two-to-five small visual elements that make the deck recognizably this brand.
+Examples: a colored underline, a strike-through wordmark, a dot cluster,
+a serif italic accent on one word per slide. Each motif MUST be reproducible
+purely with inline HTML + CSS on a single slide.
+
+## Avoid
+Explicit list of web-only patterns the slides MUST NOT carry. ALWAYS include:
+- top-nav bars, sticky headers, menu rows
+- clickable CTA buttons ("Sign up", "Start free trial", "Read docs")
+- multi-column footer-bands beyond a single thin strip with attribution + page number
+- pricing tier grids
+- hover/focus/active state styling
+- atmospheric multi-stop gradients (unless the source spec mandates them)
+Plus any AVOID rules carried over from the source DESIGN.md.
+
+## Source mapping (for traceability)
+A short bullet list showing how each web concept was mapped. Format:
+- `<web concept from DESIGN.md>` → `<slide concept in DESIGN.slides.md>` OR `dropped`
+```
+
+## Web → slide mapping rules
+
+Apply these mappings while converting. The left column is what DESIGN.md
+contains; the right column is the slide-appropriate replacement.
+
+| DESIGN.md (web) | DESIGN.slides.md (slide) |
+|---|---|
+| `top-nav` / sticky header | A 12pt-tall mono **eyebrow strip** at the top of each slide with section number + brand wordmark — never a horizontal menu of items |
+| `hero-band` (h1 + sub + dual CTA + illustration card) | **Cover layout** — single oversized headline, single sub, footer strip with page number. CTA buttons → discarded (no clicks possible). Illustration card → optional single visual anchor |
+| `feature-card grid (3-up / 4-up)` | **Content layout** with 3-up grid OK, but cards must be cardless-leaning (whitespace-driven) — drop the marketing icon + blurb pattern, prefer pull quotes or per-track/per-member rows |
+| `pricing tier grid` | **Discard entirely** — pricing has no slide analogue |
+| `connector tile grid` | **Discard or convert to small badge row** — never a 4×4 grid of generic logos |
+| `CTA banner` (full-bleed coral / brand) | **Section divider** or **closing** layout — keep the full-bleed color, replace CTA buttons with a thesis sentence and a page number |
+| `product-mockup-card-dark` (code editor screenshot card) | **Content motif** — fine to keep as a single dark surface inside a content slide, but it can NOT dominate every slide |
+| `footer-band` (4-column legal/sitemap) | **Single thin footer strip** — at most 1 line: brand wordmark left, page number right |
+| `button-primary` / `button-secondary` | **Kicker text only** — write the verb as plain text ("Read the next issue") without box/border/click affordance |
+| Hover / focus / pressed / disabled states | **Drop all of them** — slides are static |
+| Multi-stop atmospheric gradients | **Drop unless source spec calls for one or two** — convert to a single accent shape |
+| Spike-mark / asterisk-style brand glyph | **Keep as a small motif** — inline SVG at the slide eyebrow or footer |
+
+## Preservation rules (do NOT translate away)
+
+The conversion MUST carry over from DESIGN.md unchanged:
+
+- The **color palette** (canvas, surface, ink, primary accent, secondary accents)
+- The **type pairing** — display face vs body face vs mono face
+- The **mood / atmosphere** — warm-editorial vs dark-product vs pastel-pop is the
+  whole reason the user imported this DESIGN.md; the slide deck must still feel
+  like the source brand
+- **Brand-specific signature motifs** (spike-mark, hard offset shadow, slab-serif italic
+  accent, etc.) — translate the surface, not the identity
+
+## Process checklist for the agent
+
+1. Read `./DESIGN.md` in full.
+2. Identify which sections are web-only and slot them through the mapping table.
+3. Identify the design tokens (colors, type, spacing) that survive unchanged.
+4. Draft `./DESIGN.slides.md` using the Output Contract template.
+5. Show the user a short summary: 5–10 lines covering kept tokens + dropped
+   web sections + new slide layouts inferred.
+6. Wait for explicit user approval ("looks good" or specific edits) before
+   moving to outline / slide generation.
+7. Once approved, record `style: ./DESIGN.slides.md` in `slide-outline.md`.
+
+## When DESIGN.slides.md should be re-converted
+
+Suggest a re-conversion when:
+- The source `DESIGN.md` is replaced / re-imported with a different brand
+- The user explicitly asks for a different deck flavor (e.g. "more editorial",
+  "less code-heavy")
+- A slide deck visibly carries web-only artifacts (nav bars, CTAs, footers
+  with link columns) that the current DESIGN.slides.md doesn't forbid
+
+A `DESIGN.slides.md` is never regenerated automatically. It is the agent's
+job, in conversation with the user.

package/skills/slides-grab-plan/references/outline-format.md

@@ -0,0 +1,47 @@
+# slides-grab Plan Reference
+
+Use this bundled reference when planning a new deck.
+
+## Stage boundary
+- Planning stops at an approved `slide-outline.md`.
+- Do not generate `slide-*.html` in this stage.
+- Do not start design until the user explicitly approves the outline.
+
+## Expected `slide-outline.md` shape
+
+```markdown
+# [Presentation Title]
+
+## Meta
+- **Topic**: ...
+- **Target Audience**: ...
+- **Tone/Mood**: ...
+- **Slide Count**: N slides
+- **Aspect Ratio**: 16:9
+
+## Slide Composition
+
+### Slide 1 - Cover
+- **Type**: Cover
+- **Title**: ...
+- **Subtitle**: ...
+
+### Slide 2 - Table of Contents
+- **Type**: Contents
+- **Items**: ...
+
+### Slide 3 - [Title]
+- **Type**: Section Divider / Content / Statistics / Quote / Timeline / ...
+- **Key Message**: ...
+- **Details**:
+  - ...
+
+### Slide N - Closing
+- **Type**: Closing
+- **Message**: ...
+```
+
+## Planning reminders
+- Keep the outline concise and reviewable.
+- Present total slides, slide order, and each slide's role to the user.
+- Revise until explicit approval.

package/skills/slides-grab-plan/references/plan-workflow-reference.md

@@ -0,0 +1,140 @@
+# Plan Skill - Presentation Outline Planning
+
+A **supervisor skill** that takes a user topic, generates a `slide-outline.md` outline, and manages a revision loop until the user approves.
+
+Keeps the outline process separate from slide design. Use a runtime-native subagent/task for drafting when available, or draft directly from this reference when the current runtime has no subagent mechanism.
+
+---
+
+## Role Assignment
+
+| Role | Owner | Responsibility |
+|------|-------|----------------|
+| **Supervisor** | plan-skill (you) | User communication, quality control, revision loop management |
+| **Worker** | Outline worker | Draft and revise `slide-outline.md` |
+
+---
+
+## Input
+
+- User topic (required)
+- Research results (optional)
+- Reference materials, tone/mood requests, etc.
+
+## Output
+
+- User-approved `slide-outline.md`
+
+---
+
+## Workflow
+
+### 1. Create the Outline Draft
+
+Use a runtime-native task/subagent to generate a `slide-outline.md` draft when available. If the runtime has no such mechanism, write the draft directly using the format below.
+
+**Include in the prompt:**
+- User topic and requirements
+- Research results (if available)
+- Tone/mood requests
+- Expected format for `slide-outline.md` (see format below)
+
+### 2. Present Outline to User
+
+Read the generated `slide-outline.md` and present to the user:
+
+- Total number of slides
+- Slide order and each slide's role
+- Key message summary
+- Design tone/mood
+
+### 3. Feedback Revision Loop
+
+When user provides feedback:
+1. Organize the feedback
+2. Revise the existing `slide-outline.md` with the feedback, using a runtime-native task/subagent when available
+3. Present the revised outline to the user
+4. Repeat until user approves
+
+### 4. Approval Confirmation
+
+Complete the outline stage when the user explicitly approves.
+
+---
+
+## Absolute Rules
+
+1. **Never proceed to the next stage without approval** — Maintain the revision loop until the user explicitly signals approval ("looks good", "approved", "OK", "proceed", etc.).
+2. **Keep the outline stage separate** — Do not generate slide HTML while drafting or revising the outline.
+3. **Never start HTML generation** — This skill's scope ends at `slide-outline.md` approval. HTML generation is the responsibility of `design-skill`.
+
+---
+
+## Expected slide-outline.md Format
+
+```markdown
+# [Presentation Title]
+
+## Meta
+- **Topic**: ...
+- **Target Audience**: ...
+- **Tone/Mood**: ...
+- **Slide Count**: N slides
+- **Aspect Ratio**: 16:9
+
+## Slide Composition
+
+### Slide 1 - Cover
+- **Type**: Cover
+- **Title**: ...
+- **Subtitle**: ...
+
+### Slide 2 - Table of Contents
+- **Type**: Contents
+- **Items**: ...
+
+### Slide 3 - [Title]
+- **Type**: Section Divider / Content / Statistics / Quote / Timeline / ...
+- **Key Message**: ...
+- **Details**:
+  - ...
+  - ...
+
+...
+
+### Slide N - Closing
+- **Type**: Closing
+- **Message**: ...
+```
+
+---
+
+## Outline Worker Prompt Examples
+
+```
+Runtime-native task/subagent prompt:
+
+```text
+    Create a presentation outline for the following topic.
+
+    Topic: [user topic]
+    Requirements: [user requirements]
+    Research results: [if available]
+
+    Save as slide-outline.md.
+    [include expected format]
+```
+
+For feedback revisions:
+
+```
+Runtime-native task/subagent prompt:
+
+```text
+    Revise the existing outline.
+
+    Current outline: [slide-outline.md content]
+    User feedback: [feedback content]
+
+    Save the revised slide-outline.md.
+```

package/src/codex-imagen.js

@@ -0,0 +1,182 @@
+import { mkdir, readFile, readFile as readFileAsync, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+import {
+  createProvider as defaultCreateProvider,
+  resolveConfig as defaultResolveConfig,
+} from 'god-tibo-imagen';
+
+export const CODEX_DEFAULT_MODEL = 'gpt-5.4';
+export const CODEX_PROVIDER_AUTO = 'auto';
+export const CODEX_PROVIDER_PRIVATE_CODEX = 'private-codex';
+export const CODEX_PROVIDER_CODEX_CLI = 'codex-cli';
+
+const ASPECT_RATIO_HINTS = new Map([
+  ['16:9', 'wide landscape 16:9 aspect ratio'],
+  ['9:16', 'tall portrait 9:16 aspect ratio'],
+  ['1:1', 'square 1:1 aspect ratio'],
+  ['4:3', '4:3 aspect ratio'],
+  ['3:4', 'portrait 3:4 aspect ratio'],
+  ['3:2', 'landscape 3:2 aspect ratio'],
+  ['2:3', 'portrait 2:3 aspect ratio'],
+]);
+
+export function injectAspectRatioHint(prompt, aspectRatio) {
+  if (typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('injectAspectRatioHint: prompt must be a non-empty string.');
+  }
+  if (!aspectRatio || typeof aspectRatio !== 'string') {
+    return prompt;
+  }
+  const trimmed = aspectRatio.trim();
+  const explicit = ASPECT_RATIO_HINTS.get(trimmed);
+  if (explicit) {
+    return `${prompt} (${explicit})`;
+  }
+  if (/^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(trimmed)) {
+    return `${prompt} (${trimmed} aspect ratio)`;
+  }
+  return prompt;
+}
+
+export function resolveCodexConfig({ providerMode = CODEX_PROVIDER_AUTO, resolveConfigImpl = defaultResolveConfig } = {}) {
+  return resolveConfigImpl({ provider: providerMode });
+}
+
+function isCodexAuthError(error) {
+  if (!error || typeof error !== 'object') return false;
+  const code = String(error.code || '').toUpperCase();
+  if (code === 'UNAUTHORIZED' || code === 'ENOENT') return true;
+  const message = String(error.message || '').toLowerCase();
+  return (
+    message.includes('auth.json') ||
+    message.includes('unauthorized') ||
+    message.includes('chatgpt auth') ||
+    message.includes('codex login')
+  );
+}
+
+export function getCodexFallbackMessage(reason) {
+  const summary = typeof reason === 'string' && reason.trim()
+    ? reason.trim()
+    : 'codex-imagen image generation failed.';
+  return `${summary} codex-imagen is the default image provider and reuses your local Codex ChatGPT login (~/.codex/auth.json). Run \`codex login\` once to enable it. Optional fallbacks: set OPENAI_API_KEY (OpenAI gpt-image-2) or GOOGLE_API_KEY/GEMINI_API_KEY (Nano Banana). If image generation credentials are unavailable, use web search and download the chosen image into ./assets/<file>.`;
+}
+
+const MIME_BY_EXTENSION = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+/**
+ * Read reference image file paths into data URLs suitable for the Codex
+ * /responses input_image blocks. Accepts absolute paths or paths relative
+ * to process.cwd(). Already-formed data: URLs and http(s) URLs are passed
+ * through as-is.
+ */
+export async function resolveReferenceImages(paths) {
+  const list = Array.isArray(paths) ? paths : [];
+  const dataUrls = [];
+  for (const entry of list) {
+    if (typeof entry !== 'string' || !entry.trim()) continue;
+    const value = entry.trim();
+    if (value.startsWith('data:') || value.startsWith('http://') || value.startsWith('https://')) {
+      dataUrls.push(value);
+      continue;
+    }
+    const resolved = isAbsolute(value) ? value : join(process.cwd(), value);
+    if (!existsSync(resolved)) {
+      throw new Error(`Reference image not found: ${value} (resolved ${resolved})`);
+    }
+    const ext = resolved.toLowerCase().match(/\.(png|jpe?g|webp|gif)$/);
+    const mime = ext ? MIME_BY_EXTENSION[`.${ext[1]}`] : 'image/png';
+    const bytes = await readFileAsync(resolved);
+    const base64 = bytes.toString('base64');
+    dataUrls.push(`data:${mime};base64,${base64}`);
+  }
+  return dataUrls;
+}
+
+export async function generateCodexImage({
+  prompt,
+  model = CODEX_DEFAULT_MODEL,
+  aspectRatio,
+  providerMode = CODEX_PROVIDER_AUTO,
+  dryRun = false,
+  referenceImages = [],
+  deps = {},
+} = {}) {
+  if (typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('generateCodexImage: prompt must be a non-empty string.');
+  }
+
+  const createProviderImpl = deps.createProvider || defaultCreateProvider;
+  const resolveConfigImpl = deps.resolveConfig || defaultResolveConfig;
+
+  const enrichedPrompt = injectAspectRatioHint(prompt, aspectRatio);
+  const config = resolveCodexConfig({ providerMode, resolveConfigImpl });
+  const provider = createProviderImpl(config);
+
+  // Reference images are read into data URLs so the codex provider can
+  // pass them as input_image blocks in the Codex /responses request.
+  // buildResponsesRequest already accepts an images: string[] array of
+  // data URLs / URLs — we just need to surface them here.
+  const images = await resolveReferenceImages(referenceImages);
+
+  // codex's provider.generateImage writes a PNG to outputPath as a side
+  // effect. slides-grab centralizes asset path resolution in
+  // saveNanoBananaImage (src/nano-banana.js) - so we route codex's write
+  // to a tmp file and read the bytes back, letting the caller persist via
+  // the existing asset contract. This keeps the asset path policy single-sourced.
+  const tempDir = join(tmpdir(), `slides-grab-codex-${randomUUID()}`);
+  await mkdir(tempDir, { recursive: true });
+  const tempPath = join(tempDir, 'image.png');
+
+  try {
+    const result = await provider.generateImage({
+      prompt: enrichedPrompt,
+      model,
+      outputPath: tempPath,
+      dryRun: Boolean(dryRun),
+      images: images.length > 0 ? images : undefined,
+    });
+
+    if (dryRun) {
+      return {
+        mimeType: 'image/png',
+        bytes: Buffer.alloc(0),
+        mode: result?.mode || 'dry-run',
+        warnings: Array.isArray(result?.warnings) ? result.warnings : [],
+        revisedPrompt: result?.revisedPrompt ?? null,
+      };
+    }
+
+    const bytes = await readFile(tempPath);
+    return {
+      mimeType: 'image/png',
+      bytes,
+      mode: result?.mode || 'live',
+      warnings: Array.isArray(result?.warnings) ? result.warnings : [],
+      revisedPrompt: result?.revisedPrompt ?? null,
+    };
+  } catch (error) {
+    const wrapped = new Error(getCodexFallbackMessage(error?.message || String(error)));
+    wrapped.cause = error;
+    wrapped.isAuthError = isCodexAuthError(error);
+    throw wrapped;
+  } finally {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+export const __test_only__ = {
+  ASPECT_RATIO_HINTS,
+  isCodexAuthError,
+  resolveReferenceImages,
+};