slides-grab 1.3.0 → 1.3.1

package/README-ko.md

@@ -54,11 +54,13 @@ CLI와 공유 에이전트 스킬만 사용하려면 npm 패키지를 설치하
 ```bash
 npm install slides-grab
 npx playwright install chromium
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx slides-grab install-skills --target all --scope user
 ```
 
 이 방법은 일반적인 사용에 충분합니다. slides-grab 자체를 수정하거나 기여하려는 경우에만 저장소를 클론하세요.
 
+이 명령은 같은 공유 Agent Skills와 얇은 런타임 adapter를 Codex 런타임과 Claude Code 런타임 위치에 모두 설치합니다. 패키지된 워크플로우는 번들된 `SKILL.md`, `references/`, `slides-grab` CLI만 사용합니다. `slides-grab pdf`, `slides-grab convert`, `slides-grab figma` export는 현재 슬라이드 파일에 대한 최신 `slides-grab design-gate` `proceed` 기록이 없으면 차단됩니다.
+
 ## 왜 slides-grab인가요?
 
 많은 AI 도구가 슬라이드 HTML을 생성하지만, 사용자가 화면에서 **수정하고 싶은 부분을 직접 가리키고** 그 자리에서 반복 편집할 수 있게 해 주는 도구는 드뭅니다. slides-grab은 다음 흐름을 제공합니다.
@@ -72,7 +74,7 @@ npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --cop
 
 워크플로 명령은 `--slides-dir <path>`를 지원하며 기본값은 `slides`입니다.
 
-새 클론에서는 `--help`, `list-templates`, `list-styles`, `preview-styles` 같은 탐색 명령은 덱 없이도 동작합니다. `edit`, `build-viewer`, `validate`, `convert`, `pdf`는 `slide-*.html` 파일이 들어 있는 슬라이드 작업공간이 필요합니다.
+새 클론에서는 `--help`, `list-templates`, `list-styles`, `preview-styles` 같은 탐색 명령은 덱 없이도 동작합니다. `edit`, `build-viewer`, `validate`, `png`, `design-gate`는 `slide-*.html` 파일이 들어 있는 슬라이드 작업공간이 필요하고, `convert`, `pdf`, `figma`는 추가로 최신 `Proceed` design gate가 필요합니다.
 
 ```bash
 slides-grab edit              # 시각적 슬라이드 편집기 실행
@@ -90,13 +92,13 @@ slides-grab image --prompt "..."    # 로컬 슬라이드 이미지 생성
 slides-grab fetch-video --url <youtube-url> --slides-dir decks/my-deck  # yt-dlp로 동영상 에셋 다운로드
 slides-grab tldraw            # .tldr 다이어그램을 슬라이드 크기의 로컬 SVG로 렌더링
 slides-grab list-templates    # 사용 가능한 슬라이드 템플릿 표시
-slides-grab list-styles       # 번들된 35개 디자인 스타일 표시
-slides-grab preview-styles    # 35개 스타일 미리보기 갤러리를 브라우저에서 열기
+slides-grab list-styles       # 번들된 95개 디자인 스타일 표시
+slides-grab preview-styles    # 95개 스타일 미리보기 갤러리를 브라우저에서 열기
 ```
 
 ## 디자인 스타일 모음
 
-slides-grab은 [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles)에서 파생된 30개 스타일과 slides-grab 고유 스타일 5개, 총 35개 디자인 스타일을 제공합니다. 에이전트에게 특정 스타일을 요청하거나 완전히 커스텀 디자인을 요청할 수 있습니다.
+slides-grab은 [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles)에서 파생된 30개 스타일, slides-grab 고유 스타일 5개, [epoko77-ai/design-diversity](https://github.com/epoko77-ai/design-diversity)에서 파생된 PPT 팩 60개를 포함해 총 95개 디자인 스타일을 제공합니다. 에이전트에게 특정 스타일을 요청하거나 완전히 커스텀 디자인을 요청할 수 있습니다.
 
 ```bash
 slides-grab list-styles
@@ -229,7 +231,7 @@ npm install slides-grab
 Vercel Agent Skills로 공유 에이전트 스킬을 설치하려면 다음을 실행하세요.
 
 ```bash
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy --full-depth
 ```
 
 이 npm 설치 경로는 일반적인 사용에 충분합니다. slides-grab 자체를 수정하거나 기여하려는 경우에만 저장소를 클론하세요.

package/README.md

@@ -64,9 +64,11 @@ npm ci && npx playwright install chromium
 ```bash
 npm install slides-grab
 npx playwright install chromium
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx slides-grab install-skills --target all --scope user
 ```
 
+This installs the same shared Agent Skills plus lightweight runtime adapters into Codex and Claude Code locations. The packaged workflow relies on bundled `SKILL.md` files, bundled `references/`, and the `slides-grab` CLI. Exports through `slides-grab pdf`, `slides-grab convert`, and `slides-grab figma` are blocked until `slides-grab design-gate` records a fresh `proceed` receipt for the current slide files.
+
 ## Why This Project?
 
 There are many AI tools that generate slide HTML. Almost none let you **visually point at what you want changed** and iterate in-place. slides-grab fills that gap:
@@ -80,7 +82,7 @@ There are many AI tools that generate slide HTML. Almost none let you **visually
 
 Workflow commands support `--slides-dir <path>` (default: `slides`).
 
-On a fresh clone, the discovery commands (`--help`, `list-templates`, `list-styles`, and `preview-styles`) work without a deck. `edit`, `build-viewer`, `validate`, `convert`, and `pdf` require an existing slides workspace containing `slide-*.html`.
+On a fresh clone, the discovery commands (`--help`, `list-templates`, `list-styles`, and `preview-styles`) work without a deck. `edit`, `build-viewer`, `validate`, `png`, and `design-gate` require an existing slides workspace containing `slide-*.html`; `convert`, `pdf`, and `figma` additionally require a fresh `Proceed` design gate.
 
 ```bash
 slides-grab edit              # Launch visual slide editor
@@ -98,13 +100,13 @@ slides-grab image --prompt "..."    # Generate a local slide image with god-tibo
 slides-grab fetch-video --url <youtube-url> --slides-dir decks/my-deck  # Download a local video asset with yt-dlp
 slides-grab tldraw           # Render a .tldr diagram into a slide-sized local SVG asset
 slides-grab list-templates    # Show available slide templates
-slides-grab list-styles       # Show 35 bundled design styles (browse, preview, select)
-slides-grab preview-styles                        # Open the 35-style visual gallery in browser
+slides-grab list-styles       # Show 95 bundled design styles (browse, preview, select)
+slides-grab preview-styles                        # Open the 95-style visual gallery in browser
 ```
 
 ## Design Style Collections
 
-slides-grab bundles 35 design styles: 30 derived from [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles) plus 5 slides-grab originals. Agents can also create fully custom designs beyond the bundled collection.
+slides-grab bundles 95 design styles: 30 derived from [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles), 5 slides-grab originals, and 60 PPT packs derived from [epoko77-ai/design-diversity](https://github.com/epoko77-ai/design-diversity). Agents can also create fully custom designs beyond the bundled collection.
 
 ```bash
 slides-grab list-styles                           # Browse the catalog
@@ -237,7 +239,7 @@ npm install slides-grab
 Install shared agent skills with Vercel Agent Skills:
 
 ```bash
-npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy --full-depth
 ```
 
 This npm-install path is enough for normal usage. Clone the repo only when you want to modify or contribute to `slides-grab` itself.

package/bin/ppt-agent.js

@@ -9,6 +9,7 @@ import {
   getFigmaImportCaveats,
   getFigmaManualImportInstructions,
 } from '../src/figma.js';
+import { assertDesignGateReady } from '../src/design-gate-state.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, '..');
@@ -64,6 +65,17 @@ async function runCommand(relativePath, args = []) {
   }
 }
 
+async function ensureDesignGateForExport(slidesDir, label) {
+  try {
+    await assertDesignGateReady(resolve(process.cwd(), slidesDir), { label });
+  } catch (error) {
+    console.error(`[slides-grab] ${error.message}`);
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
 function collectRepeatedOption(value, previous = []) {
   return [...previous, value];
 }
@@ -109,6 +121,66 @@ program
     await runCommand('scripts/validate-slides.js', args);
   });
 
+program
+  .command('design-gate')
+  .description('Record the required visual QA gate evidence before export')
+  .option('--slides-dir <path>', 'Slide directory', 'slides')
+  .option('--slide-mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
+  .option('--resolution <preset>', 'PNG evidence resolution preset: 720p, 1080p, 1440p, 2160p, or 4k', '2160p')
+  .requiredOption('--verdict <verdict>', 'Gate verdict: proceed, revise, or rethink')
+  .requiredOption('--pass-a-report <path>', 'Pass A review report file')
+  .requiredOption('--pass-b-report <path>', 'Pass B review report file')
+  .option('--output-dir <path>', 'PNG evidence directory (default: <slides-dir>/.slides-grab/gate-preview)')
+  .action(async (options = {}) => {
+    const args = [
+      '--slides-dir',
+      options.slidesDir,
+      '--slide-mode',
+      options.slideMode,
+      '--resolution',
+      options.resolution,
+      '--verdict',
+      options.verdict,
+      '--pass-a-report',
+      options.passAReport,
+      '--pass-b-report',
+      options.passBReport,
+    ];
+    if (options.outputDir) {
+      args.push('--output-dir', String(options.outputDir));
+    }
+    await runCommand('scripts/design-gate.js', args);
+  });
+
+function registerInstallSkillsCommand(commandName) {
+  program
+    .command(commandName)
+    .description('Install slides-grab skills and lightweight runtime adapters for Codex and Claude Code')
+    .option('--target <target>', 'Runtime target: all, codex, or claude-code', 'all')
+    .option('--runtime <target>', 'Alias for --target')
+    .option('--scope <scope>', 'Install scope: project or user', 'project')
+    .option('--project-dir <path>', 'Project directory for project scope')
+    .option('--target-root <path>', 'Root directory for user-style installs')
+    .option('--dry-run', 'Print planned writes without copying')
+    .option('--json', 'Print JSON result')
+    .action(async (options = {}) => {
+      const args = [
+        '--target',
+        String(options.runtime || options.target),
+        '--scope',
+        String(options.scope),
+      ];
+      if (options.projectDir) args.push('--project-dir', String(options.projectDir));
+      if (options.targetRoot) args.push('--target-root', String(options.targetRoot));
+      if (options.dryRun) args.push('--dry-run');
+      if (options.json) args.push('--json');
+      await runCommand('scripts/install-runtime.js', args);
+    });
+}
+
+registerInstallSkillsCommand('install-skills');
+registerInstallSkillsCommand('install-runtime');
+
 program
   .command('convert')
   .description('Convert slide HTML files to experimental / unstable PPTX')
@@ -117,6 +189,7 @@ program
   .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--resolution <preset>', 'Raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p)')
   .action(async (options = {}) => {
+    if (!(await ensureDesignGateForExport(options.slidesDir, 'PPTX export'))) return;
     const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.output) {
       args.push('--output', String(options.output));
@@ -136,6 +209,7 @@ program
   .option('--slide-mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .option('--resolution <preset>', 'Capture raster size preset: 720p, 1080p, 1440p, 2160p, or 4k (default: 2160p in capture mode)')
   .action(async (options = {}) => {
+    if (!(await ensureDesignGateForExport(options.slidesDir, 'PDF export'))) return;
     const args = ['--slides-dir', options.slidesDir];
     if (options.output) {
       args.push('--output', String(options.output));
@@ -196,6 +270,7 @@ program
   .option('--mode <mode>', 'Slide mode: presentation or card-news', 'presentation')
   .addHelpText('after', figmaHelpText)
   .action(async (options = {}) => {
+    if (!(await ensureDesignGateForExport(options.slidesDir, 'Figma export'))) return;
     const args = ['--slides-dir', options.slidesDir, '--mode', options.mode];
     if (options.output) {
       args.push('--output', String(options.output));
@@ -320,7 +395,7 @@ program
 
 program
   .command('preview-styles')
-  .description('Print the path to the bundled 35-style visual preview gallery')
+  .description('Print the path to the bundled 95-style visual preview gallery')
   .action(async () => {
     try {
       const { getPreviewHtmlPath } = await import('../src/design-styles.js');
@@ -418,6 +493,8 @@ program
         console.log(`# Bundled style: ${style.title} (${style.id})`);
         console.log(`Mood: ${style.mood}`);
         console.log(`Best for: ${style.bestFor}`);
+        if (style.source?.repo) console.log(`Source: ${style.source.repo}`);
+        if (style.source?.url) console.log(`Source URL: ${style.source.url}`);
         if (Array.isArray(style.background)) {
           console.log('\n## Background');
           for (const b of style.background) console.log(`- ${b}`);
@@ -434,6 +511,14 @@ program
           console.log('\n## Layout');
           for (const l of style.layout) console.log(`- ${l}`);
         }
+        if (Array.isArray(style.signature)) {
+          console.log('\n## Signature');
+          for (const s of style.signature) console.log(`- ${s}`);
+        }
+        if (Array.isArray(style.avoid)) {
+          console.log('\n## Avoid');
+          for (const a of style.avoid) console.log(`- ${a}`);
+        }
       }
     } catch (error) {
       reportCliError(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-grab",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Agent-first presentation framework — plan, design, and visually edit HTML slides with Claude Code or Codex, then export to PDF or experimental/unstable PPTX/Figma formats",
   "license": "MIT",
   "author": "vkehfdl1",
@@ -39,10 +39,14 @@
     "scripts/generate-image.js",
     "src/god-tibo-imagen.js",
     "scripts/figma-export.js",
+    "scripts/design-gate.js",
     "scripts/html2pdf.js",
+    "scripts/html2png.js",
     "scripts/html2pptx.js",
+    "scripts/install-runtime.js",
     "scripts/render-tldraw.js",
     "scripts/validate-slides.js",
+    "runtimes/",
     "skills/",
     "src/",
     "templates/",
@@ -56,7 +60,7 @@
     "build:showcase": "node showcase/scripts/build-manifest.js",
     "validate": "node scripts/validate-slides.js",
     "convert": "node convert.cjs",
-    "test": "node --test --test-concurrency=1 tests/docs/readme-ko.test.js tests/design/design-styles.test.js tests/design/design-md-parser.test.js tests/editor/editor-codex-edit.test.js tests/editor/edit-subprocess-abort.test.js tests/editor/editor-server.test.js tests/editor/editor-server-orphan-prevention.test.js tests/editor/editor-model-dispatch.test.js tests/god-tibo/god-tibo.test.js tests/nano-banana/nano-banana.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/tldraw/render-tldraw.test.js tests/validation/validate-slides.test.js tests/viewer/build-viewer.test.js tests/skills/installable-skills.test.js tests/video/download-video.test.js",
+    "test": "node --test --test-concurrency=1 tests/docs/readme-ko.test.js tests/design/design-styles.test.js tests/design/design-md-parser.test.js tests/design-gate/design-gate.test.js tests/runtime/install-runtime.test.js tests/editor/editor-codex-edit.test.js tests/editor/edit-subprocess-abort.test.js tests/editor/editor-server.test.js tests/editor/editor-server-orphan-prevention.test.js tests/editor/editor-model-dispatch.test.js tests/god-tibo/god-tibo.test.js tests/nano-banana/nano-banana.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/tldraw/render-tldraw.test.js tests/validation/validate-slides.test.js tests/viewer/build-viewer.test.js tests/skills/installable-skills.test.js tests/video/download-video.test.js",
     "test:e2e": "node --test tests/editor/editor-ui.e2e.test.js tests/editor/editor-concurrency.e2e.test.js"
   },
   "dependencies": {

package/runtimes/claude-code/agents/design-critic-agent.md

@@ -0,0 +1,23 @@
+---
+name: design-critic-agent
+description: Run the slides-grab design gate before export.
+tools: Read, Grep, Glob, Bash, Task
+---
+
+Use the canonical gate in `skills/slides-grab-design/references/design-gate.md`.
+
+Required workflow:
+
+1. Run `slides-grab validate --slides-dir <slides-dir>`.
+2. Render evidence with `slides-grab png --slides-dir <slides-dir> --output-dir <slides-dir>/.slides-grab/gate-preview`.
+3. Produce two read-only review reports:
+   - Pass A: System Contract / Constraint Integrity.
+   - Pass B: Audience Impact / Expressive Readability.
+   Each `Proceed` report must use the CLI-enforced structure from `skills/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 all required checks marked `PASS`.
+4. If both passes conclude Proceed, record the gate with:
+
+```bash
+slides-grab design-gate --slides-dir <slides-dir> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>
+```
+
+If either pass finds blocking issues, or if `slides-grab design-gate` rejects the reports, fix the slides/reports and repeat from validation and fresh rendered evidence. Do not run `slides-grab pdf`, `slides-grab convert`, or `slides-grab figma` until the CLI gate records `proceed`.

package/runtimes/codex/agents/slides-grab-design-critic.md

@@ -0,0 +1,22 @@
+---
+name: slides-grab-design-critic
+description: Run the slides-grab design gate before export.
+---
+
+Use the canonical gate in `skills/slides-grab-design/references/design-gate.md`.
+
+Required workflow:
+
+1. Run `slides-grab validate --slides-dir <slides-dir>`.
+2. Render evidence with `slides-grab png --slides-dir <slides-dir> --output-dir <slides-dir>/.slides-grab/gate-preview`.
+3. Produce two read-only review reports:
+   - Pass A: System Contract / Constraint Integrity.
+   - Pass B: Audience Impact / Expressive Readability.
+   Each `Proceed` report must use the CLI-enforced structure from `skills/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 all required checks marked `PASS`.
+4. If both passes conclude Proceed, record the gate with:
+
+```bash
+slides-grab design-gate --slides-dir <slides-dir> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>
+```
+
+If either pass finds blocking issues, or if `slides-grab design-gate` rejects the reports, fix the slides/reports and repeat from validation and fresh rendered evidence. Do not run `slides-grab pdf`, `slides-grab convert`, or `slides-grab figma` until the CLI gate records `proceed`.

package/scripts/design-gate.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ensureSlidesPassValidation } from './validate-slides.js';
+import { assertProceedReportsComplete } from '../src/design-gate-report.js';
+import {
+  buildDesignGatePaths,
+  buildDesignGateReport,
+  collectFileFingerprints,
+  collectSlideFingerprints,
+  createDesignGateState,
+  findGateSlideFiles,
+  normalizeGateVerdict,
+  writeDesignGateState,
+} from '../src/design-gate-state.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, '..');
+const DEFAULT_SLIDES_DIR = 'slides';
+const DEFAULT_SLIDE_MODE = 'presentation';
+const DEFAULT_RESOLUTION = '2160p';
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: slides-grab design-gate [options]',
+      '',
+      'Options:',
+      `  --slides-dir <path>       Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
+      `  --slide-mode <mode>       Slide mode: presentation|card-news (default: ${DEFAULT_SLIDE_MODE})`,
+      `  --resolution <preset>     PNG evidence resolution preset (default: ${DEFAULT_RESOLUTION})`,
+      '  --verdict <verdict>       Gate verdict: proceed|revise|rethink',
+      '  --pass-a-report <path>    Pass A review report file',
+      '  --pass-b-report <path>    Pass B review report file',
+      '  --output-dir <path>       PNG evidence directory (default: <slides-dir>/.slides-grab/gate-preview)',
+      '  -h, --help                Show this help message',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function parseArgs(args) {
+  const options = {
+    slidesDir: DEFAULT_SLIDES_DIR,
+    slideMode: DEFAULT_SLIDE_MODE,
+    resolution: DEFAULT_RESOLUTION,
+    verdict: '',
+    passAReport: '',
+    passBReport: '',
+    outputDir: '',
+    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 (ARGUMENT_READERS.has(arg)) {
+      options[ARGUMENT_READERS.get(arg)] = readOptionValue(args, index, arg);
+      index += 1;
+      continue;
+    }
+
+    const equalSignIndex = arg.indexOf('=');
+    if (equalSignIndex > -1) {
+      const name = arg.slice(0, equalSignIndex);
+      const value = arg.slice(equalSignIndex + 1);
+      if (ARGUMENT_READERS.has(name)) {
+        options[ARGUMENT_READERS.get(name)] = value;
+        continue;
+      }
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.help) return options;
+
+  options.slidesDir = requireNonEmpty(options.slidesDir, '--slides-dir');
+  options.slideMode = requireNonEmpty(options.slideMode, '--slide-mode');
+  options.resolution = requireNonEmpty(options.resolution, '--resolution');
+  options.verdict = normalizeGateVerdict(requireNonEmpty(options.verdict, '--verdict'));
+  options.passAReport = requireNonEmpty(options.passAReport, '--pass-a-report');
+  options.passBReport = requireNonEmpty(options.passBReport, '--pass-b-report');
+  if (options.outputDir) options.outputDir = options.outputDir.trim();
+  return options;
+}
+
+const ARGUMENT_READERS = new Map([
+  ['--slides-dir', 'slidesDir'],
+  ['--slide-mode', 'slideMode'],
+  ['--resolution', 'resolution'],
+  ['--verdict', 'verdict'],
+  ['--pass-a-report', 'passAReport'],
+  ['--pass-b-report', 'passBReport'],
+  ['--output-dir', 'outputDir'],
+]);
+
+function readOptionValue(args, index, optionName) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+  return value;
+}
+
+function requireNonEmpty(value, optionName) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) throw new Error(`${optionName} must be a non-empty string.`);
+  return trimmed;
+}
+
+async function renderGateEvidence(options, outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  const scriptPath = resolve(packageRoot, 'scripts/html2png.js');
+  const args = [
+    scriptPath,
+    '--slides-dir',
+    options.slidesDir,
+    '--output-dir',
+    outputDir,
+    '--slide-mode',
+    options.slideMode,
+    '--resolution',
+    options.resolution,
+  ];
+
+  await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, args, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      env: { ...process.env, PPT_AGENT_PACKAGE_ROOT: packageRoot },
+    });
+    child.on('error', rejectPromise);
+    child.on('close', (code, signal) => {
+      if (signal) {
+        rejectPromise(new Error(`PNG evidence render terminated by signal ${signal}.`));
+        return;
+      }
+      if (code !== 0) {
+        rejectPromise(new Error(`PNG evidence render failed with exit code ${code}.`));
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+async function readEvidenceReport(filePath, label) {
+  const resolvedPath = resolve(process.cwd(), filePath);
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`${label} report not found: ${resolvedPath}`);
+  }
+  const report = (await readFile(resolvedPath, 'utf-8')).trim();
+  if (!report) {
+    throw new Error(`${label} report is empty: ${resolvedPath}`);
+  }
+  return { resolvedPath, report };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  const paths = buildDesignGatePaths(options.slidesDir);
+  const previewDir = options.outputDir ? resolve(process.cwd(), options.outputDir) : paths.previewDir;
+  await ensureSlidesPassValidation(paths.slidesDir, {
+    exportLabel: 'design gate',
+    slideMode: options.slideMode,
+    shouldBlockIssue: () => true,
+  });
+  await renderGateEvidence(options, previewDir);
+
+  const passA = await readEvidenceReport(options.passAReport, 'Pass A');
+  const passB = await readEvidenceReport(options.passBReport, 'Pass B');
+  let gateValidation = { status: options.verdict === 'proceed' ? 'passed' : 'not-run' };
+  const slideFiles = await findGateSlideFiles(paths.slidesDir);
+  const slideFingerprints = await collectSlideFingerprints(paths.slidesDir);
+  const evidenceFiles = slideFiles.map((fileName) => fileName.replace(/\.html$/i, '.png'));
+  const previewRelativeDir = relative(paths.slidesDir, previewDir);
+  const previewFingerprintFiles = evidenceFiles.map((fileName) => join(previewRelativeDir, fileName));
+  const passReportFingerprintFiles = [
+    relative(paths.slidesDir, passA.resolvedPath),
+    relative(paths.slidesDir, passB.resolvedPath),
+  ];
+
+  if (options.verdict === 'proceed') {
+    gateValidation = assertProceedReportsComplete({
+      passAReport: passA.report,
+      passBReport: passB.report,
+      evidenceFiles,
+      slideFingerprints,
+    });
+  }
+  const state = await createDesignGateState({
+    slidesDir: paths.slidesDir,
+    slideMode: options.slideMode,
+    resolution: options.resolution,
+    verdict: options.verdict,
+    previewDir,
+    reportPath: paths.reportPath,
+    passA: { reportPath: passA.resolvedPath, summary: firstLine(passA.report), ...gateValidation.passA },
+    passB: { reportPath: passB.resolvedPath, summary: firstLine(passB.report), ...gateValidation.passB },
+    gateValidation,
+    passReportFingerprints: await collectFileFingerprints(paths.slidesDir, passReportFingerprintFiles),
+    previewFingerprints: await collectFileFingerprints(paths.slidesDir, previewFingerprintFiles),
+  });
+  const report = buildDesignGateReport(state, passA.report, passB.report);
+  await writeDesignGateState(paths.slidesDir, state, report);
+
+  process.stdout.write(`Design gate recorded: ${state.verdict}\n`);
+  process.stdout.write(`Evidence PNGs: ${previewDir}\n`);
+  process.stdout.write(`Gate report: ${paths.reportPath}\n`);
+  process.stdout.write(`Gate state: ${paths.statePath}\n`);
+
+  if (state.verdict !== 'proceed') {
+    process.exitCode = 1;
+  }
+}
+
+function firstLine(value) {
+  return value.split(/\r?\n/).find((line) => line.trim())?.trim() || '';
+}
+
+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);
+  });
+}