@lovehlmmm/primekit 1.0.0

package/skills/shopify/scripts/tests/test_shopify_init.py

@@ -0,0 +1,385 @@
+"""
+Tests for shopify_init.py
+
+Run with: pytest test_shopify_init.py -v --cov=shopify_init --cov-report=term-missing
+"""
+
+import os
+import sys
+import json
+import pytest
+import subprocess
+from pathlib import Path
+from unittest.mock import Mock, patch, mock_open, MagicMock
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from shopify_init import EnvLoader, EnvConfig, ShopifyInitializer
+
+
+class TestEnvLoader:
+    """Test EnvLoader class."""
+
+    def test_load_env_file_success(self, tmp_path):
+        """Test loading valid .env file."""
+        env_file = tmp_path / ".env"
+        env_file.write_text("""
+SHOPIFY_API_KEY=test_key
+SHOPIFY_API_SECRET=test_secret
+SHOP_DOMAIN=test.myshopify.com
+# Comment line
+SCOPES=read_products,write_products
+""")
+
+        result = EnvLoader.load_env_file(env_file)
+
+        assert result['SHOPIFY_API_KEY'] == 'test_key'
+        assert result['SHOPIFY_API_SECRET'] == 'test_secret'
+        assert result['SHOP_DOMAIN'] == 'test.myshopify.com'
+        assert result['SCOPES'] == 'read_products,write_products'
+
+    def test_load_env_file_with_quotes(self, tmp_path):
+        """Test loading .env file with quoted values."""
+        env_file = tmp_path / ".env"
+        env_file.write_text("""
+SHOPIFY_API_KEY="test_key"
+SHOPIFY_API_SECRET='test_secret'
+""")
+
+        result = EnvLoader.load_env_file(env_file)
+
+        assert result['SHOPIFY_API_KEY'] == 'test_key'
+        assert result['SHOPIFY_API_SECRET'] == 'test_secret'
+
+    def test_load_env_file_nonexistent(self, tmp_path):
+        """Test loading non-existent .env file."""
+        result = EnvLoader.load_env_file(tmp_path / "nonexistent.env")
+        assert result == {}
+
+    def test_load_env_file_invalid_format(self, tmp_path):
+        """Test loading .env file with invalid lines."""
+        env_file = tmp_path / ".env"
+        env_file.write_text("""
+VALID_KEY=value
+INVALID_LINE_NO_EQUALS
+ANOTHER_VALID=test
+""")
+
+        result = EnvLoader.load_env_file(env_file)
+
+        assert result['VALID_KEY'] == 'value'
+        assert result['ANOTHER_VALID'] == 'test'
+        assert 'INVALID_LINE_NO_EQUALS' not in result
+
+    def test_get_env_paths(self, tmp_path):
+        """Test getting .env file paths."""
+        # Create directory structure
+        claude_dir = tmp_path / ".claude"
+        skills_dir = claude_dir / "skills"
+        skill_dir = skills_dir / "shopify"
+
+        skill_dir.mkdir(parents=True)
+
+        # Create .env files
+        (skill_dir / ".env").write_text("SKILL=1")
+        (skills_dir / ".env").write_text("SKILLS=1")
+        (claude_dir / ".env").write_text("CLAUDE=1")
+
+        paths = EnvLoader.get_env_paths(skill_dir)
+
+        assert len(paths) == 3
+        assert skill_dir / ".env" in paths
+        assert skills_dir / ".env" in paths
+        assert claude_dir / ".env" in paths
+
+    def test_load_config_priority(self, tmp_path, monkeypatch):
+        """Test configuration loading priority."""
+        skill_dir = tmp_path / "skill"
+        skills_dir = tmp_path
+        claude_dir = tmp_path.parent
+
+        skill_dir.mkdir(parents=True)
+
+        # Create .env files with different values
+        (skill_dir / ".env").write_text("SHOPIFY_API_KEY=skill_key")
+        (skills_dir / ".env").write_text("SHOPIFY_API_KEY=skills_key\nSHOP_DOMAIN=skills.myshopify.com")
+
+        # Override with process env
+        monkeypatch.setenv("SHOPIFY_API_KEY", "process_key")
+
+        config = EnvLoader.load_config(skill_dir)
+
+        # Process env should win
+        assert config.shopify_api_key == "process_key"
+        # Shop domain from skills/.env
+        assert config.shop_domain == "skills.myshopify.com"
+
+    def test_load_config_no_files(self, tmp_path):
+        """Test configuration loading with no .env files."""
+        config = EnvLoader.load_config(tmp_path)
+
+        assert config.shopify_api_key is None
+        assert config.shopify_api_secret is None
+        assert config.shop_domain is None
+        assert config.scopes is None
+
+
+class TestShopifyInitializer:
+    """Test ShopifyInitializer class."""
+
+    @pytest.fixture
+    def config(self):
+        """Create test config."""
+        return EnvConfig(
+            shopify_api_key="test_key",
+            shopify_api_secret="test_secret",
+            shop_domain="test.myshopify.com",
+            scopes="read_products,write_products"
+        )
+
+    @pytest.fixture
+    def initializer(self, config):
+        """Create initializer instance."""
+        return ShopifyInitializer(config)
+
+    def test_prompt_with_default(self, initializer):
+        """Test prompt with default value."""
+        with patch('builtins.input', return_value=''):
+            result = initializer.prompt("Test", "default_value")
+            assert result == "default_value"
+
+    def test_prompt_with_input(self, initializer):
+        """Test prompt with user input."""
+        with patch('builtins.input', return_value='user_input'):
+            result = initializer.prompt("Test", "default_value")
+            assert result == "user_input"
+
+    def test_select_option_valid(self, initializer):
+        """Test select option with valid choice."""
+        options = ['app', 'extension', 'theme']
+        with patch('builtins.input', return_value='2'):
+            result = initializer.select_option("Choose", options)
+            assert result == 'extension'
+
+    def test_select_option_invalid_then_valid(self, initializer):
+        """Test select option with invalid then valid choice."""
+        options = ['app', 'extension']
+        with patch('builtins.input', side_effect=['5', 'invalid', '1']):
+            result = initializer.select_option("Choose", options)
+            assert result == 'app'
+
+    def test_check_cli_installed_success(self, initializer):
+        """Test CLI installed check - success."""
+        mock_result = Mock()
+        mock_result.returncode = 0
+
+        with patch('subprocess.run', return_value=mock_result):
+            assert initializer.check_cli_installed() is True
+
+    def test_check_cli_installed_failure(self, initializer):
+        """Test CLI installed check - failure."""
+        with patch('subprocess.run', side_effect=FileNotFoundError):
+            assert initializer.check_cli_installed() is False
+
+    def test_create_app_config(self, initializer, tmp_path):
+        """Test creating app configuration file."""
+        initializer.create_app_config(tmp_path, "test-app", "read_products")
+
+        config_file = tmp_path / "shopify.app.toml"
+        assert config_file.exists()
+
+        content = config_file.read_text()
+        assert 'name = "test-app"' in content
+        assert 'scopes = "read_products"' in content
+        assert 'client_id = "test_key"' in content
+
+    def test_create_extension_config(self, initializer, tmp_path):
+        """Test creating extension configuration file."""
+        initializer.create_extension_config(tmp_path, "test-ext", "checkout")
+
+        config_file = tmp_path / "shopify.extension.toml"
+        assert config_file.exists()
+
+        content = config_file.read_text()
+        assert 'name = "test-ext"' in content
+        assert 'purchase.checkout.block.render' in content
+
+    def test_create_extension_config_admin_action(self, initializer, tmp_path):
+        """Test creating admin action extension config."""
+        initializer.create_extension_config(tmp_path, "admin-ext", "admin_action")
+
+        config_file = tmp_path / "shopify.extension.toml"
+        content = config_file.read_text()
+        assert 'admin.product-details.action.render' in content
+
+    def test_create_readme(self, initializer, tmp_path):
+        """Test creating README file."""
+        initializer.create_readme(tmp_path, "app", "Test App")
+
+        readme_file = tmp_path / "README.md"
+        assert readme_file.exists()
+
+        content = readme_file.read_text()
+        assert '# Test App' in content
+        assert 'shopify app dev' in content
+
+    @patch('builtins.input')
+    @patch('builtins.print')
+    def test_init_app(self, mock_print, mock_input, initializer, tmp_path, monkeypatch):
+        """Test app initialization."""
+        monkeypatch.chdir(tmp_path)
+
+        # Mock user inputs
+        mock_input.side_effect = ['my-app', 'read_products,write_products']
+
+        initializer.init_app()
+
+        # Check directory created
+        app_dir = tmp_path / "my-app"
+        assert app_dir.exists()
+
+        # Check files created
+        assert (app_dir / "shopify.app.toml").exists()
+        assert (app_dir / "README.md").exists()
+        assert (app_dir / "package.json").exists()
+
+        # Check package.json content
+        package_json = json.loads((app_dir / "package.json").read_text())
+        assert package_json['name'] == 'my-app'
+        assert 'dev' in package_json['scripts']
+
+    @patch('builtins.input')
+    @patch('builtins.print')
+    def test_init_extension(self, mock_print, mock_input, initializer, tmp_path, monkeypatch):
+        """Test extension initialization."""
+        monkeypatch.chdir(tmp_path)
+
+        # Mock user inputs: type selection (1 = checkout), name
+        mock_input.side_effect = ['1', 'my-extension']
+
+        initializer.init_extension()
+
+        # Check directory and files created
+        ext_dir = tmp_path / "my-extension"
+        assert ext_dir.exists()
+        assert (ext_dir / "shopify.extension.toml").exists()
+        assert (ext_dir / "README.md").exists()
+
+    @patch('builtins.input')
+    @patch('builtins.print')
+    def test_init_theme(self, mock_print, mock_input, initializer):
+        """Test theme initialization."""
+        mock_input.return_value = 'my-theme'
+
+        # Should just print instructions
+        initializer.init_theme()
+
+        # Verify print was called (instructions shown)
+        assert mock_print.called
+
+    @patch('builtins.print')
+    def test_run_no_cli(self, mock_print, initializer):
+        """Test run when CLI not installed."""
+        with patch.object(initializer, 'check_cli_installed', return_value=False):
+            with pytest.raises(SystemExit) as exc_info:
+                initializer.run()
+            assert exc_info.value.code == 1
+
+    @patch.object(ShopifyInitializer, 'check_cli_installed', return_value=True)
+    @patch.object(ShopifyInitializer, 'init_app')
+    @patch('builtins.input')
+    @patch('builtins.print')
+    def test_run_app_selected(self, mock_print, mock_input, mock_init_app, mock_cli_check, initializer):
+        """Test run with app selection."""
+        mock_input.return_value = '1'  # Select app
+
+        initializer.run()
+
+        mock_init_app.assert_called_once()
+
+    @patch.object(ShopifyInitializer, 'check_cli_installed', return_value=True)
+    @patch.object(ShopifyInitializer, 'init_extension')
+    @patch('builtins.input')
+    @patch('builtins.print')
+    def test_run_extension_selected(self, mock_print, mock_input, mock_init_ext, mock_cli_check, initializer):
+        """Test run with extension selection."""
+        mock_input.return_value = '2'  # Select extension
+
+        initializer.run()
+
+        mock_init_ext.assert_called_once()
+
+
+class TestMain:
+    """Test main function."""
+
+    @patch('shopify_init.ShopifyInitializer')
+    @patch('shopify_init.EnvLoader')
+    def test_main_success(self, mock_loader, mock_initializer):
+        """Test main function success path."""
+        from shopify_init import main
+
+        mock_config = Mock()
+        mock_loader.load_config.return_value = mock_config
+
+        mock_init_instance = Mock()
+        mock_initializer.return_value = mock_init_instance
+
+        with patch('builtins.print'):
+            main()
+
+        mock_init_instance.run.assert_called_once()
+
+    @patch('shopify_init.ShopifyInitializer')
+    @patch('sys.exit')
+    def test_main_keyboard_interrupt(self, mock_exit, mock_initializer):
+        """Test main function with keyboard interrupt."""
+        from shopify_init import main
+
+        mock_initializer.return_value.run.side_effect = KeyboardInterrupt
+
+        with patch('builtins.print'):
+            main()
+
+        mock_exit.assert_called_with(0)
+
+    @patch('shopify_init.ShopifyInitializer')
+    @patch('sys.exit')
+    def test_main_exception(self, mock_exit, mock_initializer):
+        """Test main function with exception."""
+        from shopify_init import main
+
+        mock_initializer.return_value.run.side_effect = Exception("Test error")
+
+        with patch('builtins.print'):
+            main()
+
+        mock_exit.assert_called_with(1)
+
+
+class TestEnvConfig:
+    """Test EnvConfig dataclass."""
+
+    def test_env_config_defaults(self):
+        """Test EnvConfig default values."""
+        config = EnvConfig()
+
+        assert config.shopify_api_key is None
+        assert config.shopify_api_secret is None
+        assert config.shop_domain is None
+        assert config.scopes is None
+
+    def test_env_config_with_values(self):
+        """Test EnvConfig with values."""
+        config = EnvConfig(
+            shopify_api_key="key",
+            shopify_api_secret="secret",
+            shop_domain="test.myshopify.com",
+            scopes="read_products"
+        )
+
+        assert config.shopify_api_key == "key"
+        assert config.shopify_api_secret == "secret"
+        assert config.shop_domain == "test.myshopify.com"
+        assert config.scopes == "read_products"

package/skills/show-off/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: pk:show-off
+description: "Create preference-aware self-contained HTML pages to showcase work. Use for demos, visual presentations, interactive showcases."
+user-invocable: true
+when_to_use: "Invoke to create a self-contained showcase or demo page."
+category: other
+keywords: [HTML, showcase, demo, presentation]
+argument-hint: "[markdown-or-prompt] [--no-antv|--no-diagram-design|--no-editorial-visuals]"
+license: Complete terms in LICENSE.txt
+metadata:
+  author: primekit
+  version: "1.0.0"
+---
+
+ultrathink
+Activate `pk:frontend-design` skill to create a showcase HTML presentation for the following request. That skill's Decision Procedure (one-line Design Read) and Self-Review Gate are mandatory here too — a showcase page is held to the same anti-slop bar as product UI, not a lower one because it is "just a demo".
+
+## REQUEST / MISSION:
+$ARGUMENTS
+
+## PURPOSE:
+Showcase, social media posting, and optional output images for articles.
+
+## PERSISTED PREFERENCES (MANDATORY - run BEFORE project-management)
+
+`show-off` has user-level workflow preferences. Defaults preserve legacy behavior:
+
+```json
+{
+  "screenshots": true,
+  "publishing": true,
+  "languages": ["vi", "en"]
+}
+```
+
+Before reading/analyzing the mission content, resolve preferences:
+
+```bash
+PREF_SCRIPT="scripts/preferences.js"
+node "$PREF_SCRIPT" get
+```
+
+The helper stores preferences at `$AGENTKIT_HOME/show-off/preferences.json`, or
+`~/.primekit/show-off/preferences.json` when `AGENTKIT_HOME` is unset.
+`SHOW_OFF_PREFS_PATH` may override the path for tests or one-off advanced use.
+
+Only parse workflow-control intent before project-management:
+- Screenshot capture: phrases like "no screenshots", "skip screenshots", "turn off screenshots", or `--no-screenshots`.
+- Publishing: phrases like "no publish", "skip publishing", "local only", "do not publish", or `--no-publish`.
+- Language mode: phrases like "English only", "Vietnamese only", "disable dual language", "no bilingual", or `--languages en`.
+- Reset: phrases like "reset show-off preferences" or "use defaults again".
+- One-time override: if the user says "for this run only", apply it for this invocation but do not persist it.
+
+If the user explicitly changes one of these settings and does not say it is only for this run, persist it immediately:
+
+```bash
+# Examples
+node "$PREF_SCRIPT" set --no-screenshots
+node "$PREF_SCRIPT" set --no-publish
+node "$PREF_SCRIPT" set --languages en
+node "$PREF_SCRIPT" set --screenshots on --publishing on --languages vi,en
+node "$PREF_SCRIPT" reset
+```
+
+Use the resolved preferences for the current run. The latest explicit user instruction
+wins over stored preferences. Do not ask the user to repeat a persisted opt-out.
+
+## PREREQUISITE (MANDATORY - run BEFORE content workflow)
+
+After resolving preferences, invoke `/pk:project-management` **before** reading/analyzing the request content or doing any content workflow work. This skill owns plan/task lifecycle; `show-off` is a consumer.
+
+Purpose:
+- Create a dated plan directory under `plans/` (naming from hook injection: `{date}-{issue}-{slug}`).
+- Register the resolved checklist below as trackable tasks:
+  - Always: request-analysis, content, HTML, local open/review.
+  - If `screenshots=true`: capture.
+  - If `publishing=true`: publish content/static site.
+- Set the active plan context so downstream skills (`frontend-design`, `agent-browser`, capture script) share the same plan folder and assets root.
+- Record the invocation arguments and resolved preferences (`screenshots`, `publishing`, `languages`) in `plan.md`.
+
+Hard gate: do NOT proceed to the DETAILED INSTRUCTIONS below until the plan directory exists and the checklist is registered. If `project-management` returns `BLOCKED` / `NEEDS_CONTEXT`, resolve it first.
+
+## DETAILED INSTRUCTIONS
+Follow these steps strictly in order, one by one:
+- Read and analyze the request carefully, split into topics/sections (minimum 2, maximum 6, including hero section).
+- Update the registered tasks in the active plan as each step starts/completes (via `project-management`).
+- Search the internet for supporting evidence or fact-checking information in the request/mission.
+- Write showcase content as markdown at `assets/showoff/<mission-name>/content.md` with all content organized by sections/topics.
+  **NOTE:**
+  - Check if one of these files existed:
+    [
+      `/Volumes/GOON/www/assets/writing-styles/`,
+      `~/www/writing-styles/`,
+      `~/.claude/writing-styles/`,
+      `~/writing-styles/`
+    ]
+    -> Read it to use writing style (if none of them exists, just skip).
+  - Attach citation URLs in references/footnotes at end of file.
+- If `publishing=true`, use `agentwiki` CLI to publish this document (organize or create appropriate folder).
+  If `publishing=false`, keep the document local and mark the publish task skipped.
+- Activate `pk:frontend-design` skill to create a stunning HTML file:
+  - Include visual diagrams/illustrations
+  - Include decorative elements (optional)
+  - Micro-animation or subtle animation (optional)
+  - Attach citation URLs in references/footnotes at bottom of page
+- First section (hero section): always an impressive, eye-catching, glamorous design that hooks and entices into subsequent sections.
+- Layout organized into multiple sections corresponding to request topics -> user scrolls smoothly top-to-bottom with parallax effects.
+  Remember id/class names of each section for screenshot capture later.
+- Content MUST use the resolved language preference:
+  - `["vi", "en"]`: provide Vietnamese and English content with a clear language toggle or parallel bilingual treatment.
+  - `["en"]`: English only. Do not add Vietnamese copy or a language toggle.
+  - `["vi"]`: Vietnamese only. Do not add English copy or a language toggle.
+- If `screenshots=false`, skip screenshot capture entirely. Do not run the local capture script or `rws`; mark the capture task skipped and report the local HTML path.
+- If `screenshots=true`, capture each section as images (JPG/PNG) at `assets/showoff/<mission-name>/images/` with ratio-based prefix (`horizontal`, `vertical`, `square`).
+  **NOTE:** The capture script now auto-waits for fonts, `<img>` completion, and CSS background-image loading before each shot. `--settle-delay` adds an extra cushion for animations / lazy reveals.
+  **IMPORTANT:** Use the parallel capture script for efficiency:
+  ```bash
+  node scripts/capture-sections.js \
+    --url "file:///path/to/index.html" \
+    --output-dir "assets/showoff/<mission-name>/images" \
+    --sections "#hero,#section-2,#section-3" \
+    --ratios "horizontal,vertical,square" \
+    --settle-delay 1500
+  ```
+  **FALLBACK - `rws` CLI**: if `publishing=true` and the local script fails (puppeteer missing, headless Chrome unavailable, sandbox error, script exit non-zero) AND the `rws` command is on PATH AND `$RWEB_API_KEY` is set, fall back to the ReviewWeb screenshot API. The HTML must be publicly reachable (publish via `agentwiki` first, then use the public URL + `#section-id` anchors).
+
+  Detection:
+  ```bash
+  command -v rws >/dev/null && [ -n "$RWEB_API_KEY" ] && echo "rws fallback available"
+  ```
+
+  Per (section, ratio) capture loop:
+  ```bash
+  # Viewports: horizontal=1920x1080, vertical=1080x1920, square=1080x1080
+  rws screenshot \
+    --url "https://public-host/mission/#hero" \
+    --width 1920 --height 1080 \
+    --delay 1500 \
+    --format json \
+    | jq -r '.imageUrl' \
+    | xargs -I{} curl -sSL {} -o "assets/showoff/<mission-name>/images/horizontal-hero.png"
+  ```
+
+  Fallback rules:
+  - Run per (section, ratio) combo; parallelise with `xargs -P` or shell `&`.
+  - `--delay` passes the same settle-delay value used by the local script.
+  - Skip `rws` fallback whenever `publishing=false`; the user explicitly chose a local-only flow.
+  - Skip `rws` fallback if the HTML is only reachable via `file://` and cannot be published yet — in that case, surface the local script error to the user and stop.
+  - Never pass `$RWEB_API_KEY` on the command line; rely on the env var resolution (`rws` reads it automatically).
+  - On `rws` exit code 2 (auth error) or missing `$RWEB_API_KEY`, stop and report — do not silently skip capture.
+- If `publishing=true`, use `agentwiki` CLI to publish/update this static site when complete.
+  If `publishing=false`, do not publish and report the local artifact path instead.
+- Use `open` CLI (or equivalent) to open the resulting HTML page.
+
+## OUTPUT REQUIREMENTS
+- Each section's components MUST fit within browser viewport
+- Support responsive layout, especially good display for ratios 16:9, 9:16 and 1:1
+- Font must support Vietnamese characters well when Vietnamese is enabled
+- Theme toggle button: system (default), light & dark
+- Ensure layout never breaks, section content never gets clipped on any side, displays well on all screen sizes
+- Output images MUST be in proper sizes according to their ratios when `screenshots=true`.
+- Modularization & maintainable code
+
+**Editorial visual layer (on by default, additive for non-hero panels):** read `primekit config prefs resolve --json | jq '.prefs.visual'` (nested keys spell camelCase — `diagram_design` returns as `diagramDesign`). The hero section still delegates to `pk:frontend-design` unchanged. For non-hero KPI / ranked-list / quadrant panels, the AntV Infographic palette (`CandyCardLite`, `CompactCard`, `CompareBinaryHorizontal`, `CircularProgress`, `ChartPie`, `ChartBar`) is available when `.prefs.visual.antv.enabled` AND the artifact carries ≥3 such tiles. For architecture or process diagrams inside a section, `diagram-design` (Architecture, Process, Data flow) is available when `.prefs.visual.diagramDesign.enabled`. Kill switches: `--no-antv`, `--no-diagram-design`, `--no-editorial-visuals`. See the sibling `primekit-preview` skill's `../primekit-preview/references/html-antv-infographic.md` and `../primekit-preview/references/html-diagram-design.md`.
+
+## Handoff Gate (mandatory before delivering)
+
+Before presenting the result, run the 5-dimension check in
+`../primekit-design/references/handoff-gate.md` (context fit, visual hierarchy,
+craft/detail, usability/accessibility, implementation safety) against the
+generated page(s). Fix a failing dimension now, or list it explicitly under
+"Known limitations" in the handoff template — never ship a known failure
+silently.
+
+## PREFERENCE HELPER USAGE
+
+The preference helper at `scripts/preferences.js` supports:
+
+```bash
+# Print resolved user preferences as JSON
+node scripts/preferences.js get
+
+# Persist workflow opt-outs
+node scripts/preferences.js set --no-screenshots --no-publish --languages en
+
+# Re-enable defaults
+node scripts/preferences.js reset
+```
+
+Options for `set`:
+- `--screenshots on|off`, `--no-screenshots`
+- `--publishing on|off`, `--publish on|off`, `--no-publishing`, `--no-publish`
+- `--languages en|vi|en,vi`, `--language en|vi`
+- `--dual-language on|off`, `--no-dual-language`
+
+## CAPTURE SCRIPT USAGE
+
+The parallel capture script at `scripts/capture-sections.js` supports:
+
+```bash
+# Capture all sections in parallel across multiple ratios
+node scripts/capture-sections.js \
+  --url "file:///path/to/page.html" \
+  --output-dir "./assets/showoff/my-mission/images" \
+  --sections "#hero,#about,#features,#footer" \
+  --ratios "horizontal,vertical,square" \
+  --settle-delay 1500 \
+  --format png \
+  --quality 90
+
+# Single ratio capture
+node scripts/capture-sections.js \
+  --url "http://localhost:3000" \
+  --output-dir "./output" \
+  --sections "#hero" \
+  --ratios "horizontal"
+```
+
+Options:
+- `--url` (required): Page URL to capture
+- `--output-dir` (required): Output directory for images
+- `--sections` (required): Comma-separated CSS selectors for sections
+- `--ratios` (default: "horizontal,vertical,square"): Capture ratios
+- `--settle-delay` (default: 1500): Ms to wait AFTER the page is visually ready (fonts + images + CSS backgrounds all resolved). Alias: `--delay` (back-compat).
+- `--render-timeout` (default: 15000): Max ms to wait for any single readiness signal (fonts, images, bg-images). Prevents a broken asset from hanging the run.
+- `--format` (default: "png"): Image format (png/jpg/webp)
+- `--quality` (default: 90): Image quality (1-100, for jpg/webp)
+- `--max-size` (default: 5): Max file size in MB before compression
+- `--executable-path`: Optional Chrome/Chromium executable path. Also reads `CHROME_EXECUTABLE_PATH` or `PUPPETEER_EXECUTABLE_PATH`.
+
+**Readiness chain before each capture:**
+1. `networkidle0` (no in-flight requests)
+2. `document.fonts.ready` (web fonts loaded)
+3. Every `<img>` complete (or errored)
+4. Every CSS `background-image` URL preloaded
+5. Double `requestAnimationFrame` (layout + compositor settle)
+6. `--settle-delay` ms (animations / JS-triggered reveals)
+
+Same chain runs again after `scrollIntoView()` per section, so reveal-on-scroll animations capture correctly.
+
+## SECURITY POLICY
+This skill handles HTML generation and screenshot capture only. 
+Does NOT handle: authentication, database access, server deployment, or sensitive data processing. 
+Never include API keys or credentials in generated HTML files.