slides-grab 1.2.6 → 1.3.1

package/scripts/install-runtime.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, readdir, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, '..');
+const VALID_TARGETS = new Set(['all', 'codex', 'claude-code']);
+const VALID_SCOPES = new Set(['project', 'user']);
+const SKILL_NAMES = [
+  'slides-grab',
+  'slides-grab-plan',
+  'slides-grab-design',
+  'slides-grab-export',
+  'slides-grab-card-news',
+];
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: slides-grab install-skills [options]',
+      '',
+      'Options:',
+      '  --target <target>       Runtime target: all|codex|claude-code (default: all)',
+      '  --runtime <target>      Alias for --target',
+      '  --scope <scope>         Install scope: project|user (default: project)',
+      '  --project-dir <path>    Project directory for project scope (default: cwd)',
+      '  --target-root <path>    Root directory for user-style installs',
+      '  --dry-run              Print planned writes without copying',
+      '  --json                 Print JSON result',
+      '  -h, --help             Show this help message',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function parseArgs(args) {
+  const options = {
+    target: 'all',
+    scope: 'project',
+    projectDir: process.cwd(),
+    targetRoot: '',
+    dryRun: false,
+    json: false,
+    help: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (OPTION_FIELDS.has(arg)) {
+      options[OPTION_FIELDS.get(arg)] = readOptionValue(args, index, arg);
+      index += 1;
+      continue;
+    }
+    const equalSignIndex = arg.indexOf('=');
+    if (equalSignIndex > -1) {
+      const name = arg.slice(0, equalSignIndex);
+      if (OPTION_FIELDS.has(name)) {
+        options[OPTION_FIELDS.get(name)] = arg.slice(equalSignIndex + 1);
+        continue;
+      }
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.help) return options;
+
+  options.target = normalizeTarget(options.target);
+  options.scope = normalizeScope(options.scope);
+  options.projectDir = resolve(process.cwd(), options.projectDir);
+  options.targetRoot = options.targetRoot ? resolve(process.cwd(), options.targetRoot) : '';
+  return options;
+}
+
+const OPTION_FIELDS = new Map([
+  ['--target', 'target'],
+  ['--runtime', 'target'],
+  ['--scope', 'scope'],
+  ['--project-dir', 'projectDir'],
+  ['--target-root', 'targetRoot'],
+]);
+
+function readOptionValue(args, index, optionName) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+  return value;
+}
+
+function normalizeTarget(value) {
+  const target = String(value || '').trim().toLowerCase();
+  if (!VALID_TARGETS.has(target)) {
+    throw new Error(`Unknown runtime target "${value}". Expected: all, codex, or claude-code.`);
+  }
+  return target;
+}
+
+function normalizeScope(value) {
+  const scope = String(value || '').trim().toLowerCase();
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(`Unknown install scope "${value}". Expected: project or user.`);
+  }
+  return scope;
+}
+
+function selectedTargets(target) {
+  return target === 'all' ? ['codex', 'claude-code'] : [target];
+}
+
+function runtimeRoots(options, target) {
+  if (options.scope === 'project') {
+    return {
+      codex: {
+        skillsDir: join(options.projectDir, '.agents', 'skills'),
+        agentsDir: join(options.projectDir, '.codex', 'agents'),
+      },
+      'claude-code': {
+        skillsDir: join(options.projectDir, '.claude', 'skills'),
+        agentsDir: join(options.projectDir, '.claude', 'agents'),
+      },
+    }[target];
+  }
+
+  const root = options.targetRoot || homedir();
+  return {
+    codex: {
+      skillsDir: join(root, '.agents', 'skills'),
+      agentsDir: join(root, '.codex', 'agents'),
+    },
+    'claude-code': {
+      skillsDir: join(root, '.claude', 'skills'),
+      agentsDir: join(root, '.claude', 'agents'),
+    },
+  }[target];
+}
+
+async function copyDirectory(source, destination, dryRun) {
+  if (dryRun) return;
+  await rm(destination, { recursive: true, force: true });
+  await mkdir(dirname(destination), { recursive: true });
+  await cp(source, destination, { recursive: true });
+}
+
+async function installTarget(options, target) {
+  const roots = runtimeRoots(options, target);
+  const writes = [];
+  if (!options.dryRun) {
+    await mkdir(roots.skillsDir, { recursive: true });
+    await mkdir(roots.agentsDir, { recursive: true });
+  }
+
+  for (const skillName of SKILL_NAMES) {
+    const source = join(packageRoot, 'skills', skillName);
+    const destination = join(roots.skillsDir, skillName);
+    await copyDirectory(source, destination, options.dryRun);
+    writes.push(destination);
+  }
+
+  const adapterSourceDir = join(packageRoot, 'runtimes', target, 'agents');
+  const adapterFiles = await readdir(adapterSourceDir);
+  for (const adapterFile of adapterFiles) {
+    const source = join(adapterSourceDir, adapterFile);
+    const destination = join(roots.agentsDir, adapterFile);
+    await copyDirectory(source, destination, options.dryRun);
+    writes.push(destination);
+  }
+
+  return { target, skillsDir: roots.skillsDir, agentsDir: roots.agentsDir, writes };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  const installs = [];
+  for (const target of selectedTargets(options.target)) {
+    installs.push(await installTarget(options, target));
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ installs, dryRun: options.dryRun }, null, 2)}\n`);
+    return;
+  }
+
+  for (const install of installs) {
+    const label = install.target === 'claude-code' ? 'Claude Code' : 'Codex';
+    process.stdout.write(`Installed slides-grab skills for ${label}\n`);
+    process.stdout.write(`  Skills: ${install.skillsDir}\n`);
+    process.stdout.write(`  Agents: ${install.agentsDir}\n`);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}

package/skills/slides-grab/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: slides-grab
-description: End-to-end presentation workflow for Codex. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting. PDF and per-slide PNG are preferred; PPTX/Figma export is experimental / unstable.
+description: End-to-end presentation workflow usable in Codex and Claude Code. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting. PDF and per-slide PNG are preferred; PPTX/Figma export is experimental / unstable.
 metadata:
   short-description: Full pipeline from topic to PDF/PNG + experimental / unstable PPTX/Figma export
 ---
 
-# slides-grab Skill (Codex) - Full Workflow Orchestrator
+# slides-grab Skill - Full Workflow Orchestrator
 
 Guides you through the complete presentation pipeline from topic to exported file.
 
@@ -37,11 +37,12 @@ Use the installed **slides-grab-design** skill.
 7. For complex diagrams (architecture, workflows, relationship maps, multi-node concepts), prefer `tldraw` over hand-built HTML/CSS diagrams. Render the asset with `slides-grab tldraw`, store it under `<slides-dir>/assets/`, and place it in the slide with a normal `<img>`.
 8. Keep local videos under `<slides-dir>/assets/`, prefer `poster="./assets/<file>"` thumbnails, and use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly) when the source starts on a supported web page.
 9. The default provider, god-tibo-imagen, reuses the local Codex ChatGPT login (`~/.codex/auth.json`) — run `codex login` once; no API key required. ⚠️ god-tibo-imagen uses an unsupported private Codex backend that may break without notice. Optional alternatives: `--provider codex` (Codex/OpenAI gpt-image-2 via `OPENAI_API_KEY`; maps `--aspect-ratio` to the nearest supported OpenAI image size; `--image-size 2K|4K` is Nano Banana-only) or `--provider nano-banana` (Google `gemini-3-pro-image-preview` via `GOOGLE_API_KEY` or `GEMINI_API_KEY`; supports `--image-size 2K|4K`). If credentials are unavailable, fall back to web search/download into `<slides-dir>/assets/`.
-10. Launch the interactive editor for review: `slides-grab edit --slides-dir <path>`
-11. Revise slides based on user feedback via the editor, then re-run validation after each edit round.
-12. When the user confirms editing is complete, suggest next steps: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final preview, or proceed directly to Stage 3 for PDF/PPTX export.
+10. **Run the design gate as an adversarial quality loop** before presenting the deck (`skills/slides-grab-design/references/design-gate.md`): capture render evidence (`slides-grab png … --output-dir <path>/gate-preview`), dispatch two parallel read-only reviewer passes when the current runtime supports subagents/tasks (A: System Contract / Constraint Integrity, B: Audience Impact / Expressive Readability), and synthesize contract coherence against audience impact into one Design Gate Report with a verdict. If subagents are unavailable, run the same two passes sequentially from the bundled reference. Review Litmus is the shared audience-success tie-breaker, not a third pass. **Resolve every Critical finding** (unreadable text, palette violation, AI slop trope as a slide's primary treatment, key slide with no visual anchor, invented data), re-run validate, capture fresh PNGs, and re-run both adversarial passes until the latest rendered state reaches `Proceed` or requires `Rethink approach`. For `Proceed`, the Pass A/B reports must follow the CLI-enforced structure in `slides-grab-design/references/design-gate.md` (role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, findings table, and required checks marked `PASS`). When the verdict is `Proceed`, record the export-unlocking receipt with `slides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>`. If the CLI rejects the reports, continue the fix → validate → render → A/B review loop. Track deferred Minor/Note in `<slides-dir>/design-debt.md`.
+11. Launch the interactive editor for review: `slides-grab edit --slides-dir <path>`
+12. Revise slides based on user feedback via the editor, then re-run validation and the design gate after each edit round that changes layout, color, typography, imagery, or content density.
+13. When the user confirms editing is complete, suggest next steps: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final preview, or proceed directly to Stage 3 for PDF/PPTX export.
 
-**Do not proceed to Stage 3 without approval.**
+**Do not proceed to Stage 3 without approval, and never while any Critical design-gate finding is unresolved.**
 
 ### Stage 3 — Export
 
@@ -62,12 +63,13 @@ Use the installed **slides-grab-export** skill.
 
 1. **Always follow the stage order**: Plan → Design → Export.
 2. **Get explicit user approval** before advancing to the next stage.
-3. **Read each stage's SKILL.md** for detailed rules — this skill only orchestrates.
-4. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
-5. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and must be described as best-effort output.
-6. Use the stage skills as the source of truth for plan, design, and export rules.
-7. When a slide needs a complex diagram, default to a `tldraw`-generated asset unless the user explicitly asks for a different approach.
-8. When a slide needs bespoke imagery, prefer the default god-tibo-imagen provider via `slides-grab image` (reuses local Codex ChatGPT login — no API key required) and keep the saved asset local under `<slides-dir>/assets/`.
+3. **Pass the design gate before export**: Stage 2 must end with a Design Gate Report whose verdict is `Proceed` (zero unresolved Critical findings) on the **latest rendered state** before the deck advances to Stage 3. The gate (`skills/slides-grab-design/references/design-gate.md`) runs after `slides-grab validate`; use runtime-native subagents/tasks for Pass A/B when available, or run the same bundled procedure sequentially. Record the latest Proceed verdict with `slides-grab design-gate`; `slides-grab pdf`, `slides-grab convert`, and `slides-grab figma` block if that receipt is missing, stale, or backed by Pass A/B reports that fail the CLI-enforced report contract. Any fix requires fresh PNG evidence and another Pass A/B challenge. Critical hard-blocks export; Major findings are listed for user acceptance; Minor/Note findings may be tracked in the design-debt log.
+4. **Read each stage's SKILL.md** for detailed rules — this skill only orchestrates.
+5. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
+6. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and must be described as best-effort output.
+7. Use the stage skills as the source of truth for plan, design, and export rules.
+8. When a slide needs a complex diagram, default to a `tldraw`-generated asset unless the user explicitly asks for a different approach.
+9. When a slide needs bespoke imagery, prefer the default god-tibo-imagen provider via `slides-grab image` (reuses local Codex ChatGPT login — no API key required) and keep the saved asset local under `<slides-dir>/assets/`.
 
 ## Reference
 - `references/presentation-workflow-reference.md` — archived end-to-end workflow guidance from the legacy skill set

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

@@ -22,7 +22,7 @@ Use the installed **slides-grab-plan** skill.
 Use the installed **slides-grab-design** skill.
 
 1. Read approved `slide-outline.md`.
-2. If the user has not approved a visual direction yet, use `slides-grab list-styles` to shortlist bundled styles, optionally `slides-grab preview-styles` to open the visual gallery in browser, and agree on a direction with the user. If none of the 35 bundled styles fit, design a fully custom visual direction.
+2. If the user has not approved a visual direction yet, use `slides-grab list-styles` to shortlist bundled styles, optionally `slides-grab preview-styles` to open the visual gallery in browser, and agree on a direction with the user. If none of the 95 bundled styles fit, design a fully custom visual direction.
 3. Generate `slide-*.html` files in the slides workspace (default: `slides/`).
 4. Run validation: `slides-grab validate --slides-dir <path>`
 5. If validation fails, automatically fix the slide HTML/CSS until validation passes.

package/skills/slides-grab-card-news/SKILL.md

@@ -5,7 +5,7 @@ metadata:
   short-description: Square card-news workflow on top of slides-grab (PNG by default)
 ---
 
-# slides-grab Card News Skill (Codex)
+# slides-grab Card News Skill
 
 Use this when the user wants card news instead of a widescreen presentation.
 

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

@@ -1,11 +1,11 @@
 ---
 name: slides-grab-design
-description: Stage 2 design skill for Codex. Generate and iterate slide-XX.html files in the selected slides workspace.
+description: Stage 2 design skill usable in Codex and Claude Code. Generate and iterate slide-XX.html files in the selected slides workspace.
 metadata:
   short-description: Build HTML slides and viewer for review loop
 ---
 
-# slides-grab Design Skill (Codex)
+# slides-grab Design Skill
 
 Use this after `slide-outline.md` is approved.
 
@@ -22,7 +22,11 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 
 ## Workflow
 1. Read approved `slide-outline.md` and extract the `style` field from its meta section.
-2. Load the chosen style's full spec from `src/design-styles-data.js` — colors, fonts, layout, signature elements, and things to avoid. If the meta specifies a custom direction instead of a bundled ID, use that custom direction as the design basis.
+2. Load the chosen style's full spec:
+   - If `style` is a bundled id (e.g. `glassmorphism`), load from `src/design-styles-data.js` — colors, fonts, layout, signature elements, and things to avoid.
+   - If `style` ends in `.md` (e.g. `./DESIGN.slides.md` or `./DESIGN.md`), or if a design markdown file exists at the project root, parse it with `slides-grab show-design <path>` and treat the parsed output as the authoritative design system (colors, typography, layout, components, signature, avoid).
+   - **Precedence when both files exist:** `DESIGN.slides.md` takes priority over `DESIGN.md`. The `.slides.md` version is the slide-flavored conversion produced by the plan stage and is the only file safe to apply to slide HTML. If only `DESIGN.md` exists, treat it as web-flavored and follow the slide layout/avoid rules in `references/design-rules.md` strictly to avoid leaking web-only components (top-nav, CTA buttons, footer-band columns, pricing grids) into slides — or, preferably, switch back to the plan stage and produce a `DESIGN.slides.md` first.
+   - If the meta specifies a written custom direction, use that as the design basis.
 3. Before generating slides, write a quick **visual thesis** (mood/material/energy), a **content plan** (opener → support/proof → detail/story → close/CTA), a **system declaration** (reused layout patterns, max two background colors, max two typefaces, image-led vs text-led slides, where section dividers reset tempo), and the core design tokens (background, surface, text, muted, accent + display/headline/body/caption roles). Ground these tokens in the chosen style's spec. Follow `references/beautiful-slide-defaults.md` for the full working model, content discipline, color discipline, and AI slop tropes to avoid.
 4. If you need to confirm or revisit the approved bundled style before designing, re-run `slides-grab list-styles` and open the gallery from `slides-grab preview-styles` so the Stage 2 deck stays aligned with the Stage 1 direction.
 5. Generate slide HTML files with 2-digit numbering in selected `--slides-dir`.
@@ -34,10 +38,12 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 11. Run `slides-grab validate --slides-dir <path>` after generation or edits.
 12. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
 13. Run the slide litmus check from `references/beautiful-slide-defaults.md` before presenting the deck for review.
-14. Launch the interactive editor for visual review: `slides-grab edit --slides-dir <path>`
-15. Iterate on user feedback by editing only requested slide files, then re-run validation after each edit round.
-16. When the user confirms editing is complete, suggest: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final read-only preview, or proceed to export (PDF/PPTX).
-17. Keep revising until user approves conversion stage.
+14. **Run the design gate as an adversarial quality loop** (`references/design-gate.md`) before showing the deck: (a) capture render evidence with `slides-grab png --slides-dir <path> --output-dir <path>/gate-preview --resolution 1080p`; (b) run two read-only reviewer passes — Pass A (System Contract / Constraint Integrity) and Pass B (Audience Impact / Expressive Readability) — that open the rendered PNGs directly, using runtime-native subagents/tasks in parallel when available or sequential passes when not; (c) synthesize contract coherence against audience impact into a single Design Gate Report ending in a verdict (`Proceed` / `Revise and re-review` / `Rethink approach`). Review Litmus is the shared audience-success tie-breaker, not a third pass. Keep the two reviewer passes distinct from the slide-building pass. The render evidence aims the reviewers; it is not the verdict. For `Proceed`, each pass report must satisfy the CLI-enforced structure in `references/design-gate.md`: role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, a findings table, and all required checks marked `PASS`.
+15. **Repeat until the latest rendered state survives the gate.** Critical findings (unreadable text, palette violation, an AI slop trope used as a slide's primary treatment, a key slide with no real visual anchor, invented data shown as real) hard-block progress. Fix the source HTML/CSS, re-run `slides-grab validate`, capture fresh PNGs, then re-run both adversarial passes until the verdict is `Proceed` (zero unresolved Critical) or `Rethink approach` requires redesigning the visual thesis/system. When the verdict is `Proceed`, write the export-unlocking receipt with `slides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>`. If the CLI rejects the reports, treat that as the loop still failing: fix the missing evidence/checks or unresolved findings, re-render, re-review, and retry. Record deferred Minor/Note findings in `<slides-dir>/design-debt.md`; never silently drop a finding.
+16. Launch the interactive editor for visual review: `slides-grab edit --slides-dir <path>`
+17. Iterate on user feedback by editing only requested slide files, then re-run validation and the design gate after each edit round that changes layout, color, typography, imagery, or content density.
+18. When the user confirms editing is complete, suggest: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final read-only preview, or proceed to export (PDF/PPTX).
+19. Keep revising until user approves conversion stage.
 
 ## Rules
 - Keep slide size 720pt x 405pt.
@@ -62,6 +68,7 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 - Prefer `tldraw` for complex diagrams instead of recreating dense node/edge diagrams directly in HTML/CSS.
 - Use `slides-grab tldraw` plus `templates/diagram-tldraw.html` when that gives a cleaner, more export-friendly result.
 - Do not present slides for review until `slides-grab validate --slides-dir <path>` passes.
+- Do not present slides for review, and do not advance toward export, while any **Critical** design-gate finding is unresolved (`references/design-gate.md`). Critical hard-blocks; Major findings are listed for user acceptance; Minor/Note findings may be tracked. `slides-grab pdf`, `slides-grab convert`, and `slides-grab figma` require a fresh `slides-grab design-gate` Proceed receipt.
 - Do not start conversion before approval.
 - Use the packaged CLI and bundled references only; do not depend on unpublished agent-specific files.
 
@@ -70,4 +77,5 @@ For full constraints and style system, follow:
 - `references/design-rules.md`
 - `references/detailed-design-rules.md`
 - `references/beautiful-slide-defaults.md` — slide-specific art direction defaults adapted from OpenAI's frontend design guidance and Anthropic's Claude design system guidance (content/color discipline, system declaration, AI slop tropes)
+- `references/design-gate.md` — the structured design-quality gate run after validation and before export: severity rubric (Critical/Major/Minor/Note), the seven checks, evidence-before-shipping, design-debt log, and the gate report/verdict format. Run with runtime-native subagents/tasks when available, or as two explicit sequential reviewer passes, then record Proceed with `slides-grab design-gate`.
 - `references/design-system-full.md` — archived full design system, templates, and advanced pattern guidance