jekyll-theme-zer0 1.26.0 → 1.27.0

data/scripts/features/install-preview-generator

@@ -14,13 +14,15 @@
 #   -h, --help              Show this help message
 #   -d, --dry-run           Preview what would be installed (no changes)
 #   -f, --force             Overwrite existing files
-#   -p, --provider PROVIDER Set default AI provider (openai, stability, local)
+#   -p, --provider PROVIDER Set default renderer
+#                           (openai, xai, stability, gemini, local)
 #   --no-config             Skip _config.yml modification
 #   --no-tasks              Skip VS Code tasks installation
 #
 # Requirements:
 #   - Jekyll site using zer0-mistakes theme
 #   - curl and jq installed
+#   - python3 with PyYAML (runs the generation engine)
 #   - Git repository (for version tracking)
 #
 
@@ -43,12 +45,12 @@ RAW_URL="https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main"
 SOURCE_FILES=(
     "scripts/features/generate-preview-images"
     "scripts/lib/preview_generator.py"
-    "_plugins/preview_image_generator.rb"
+    "scripts/dev/rasterize-svg.js"
 )
 DEST_FILES=(
     "scripts/generate-preview-images.sh"
     "scripts/lib/preview_generator.py"
-    "_plugins/preview_image_generator.rb"
+    "scripts/dev/rasterize-svg.js"
 )
 
 # Default options
@@ -96,20 +98,21 @@ ${YELLOW}OPTIONS:${NC}
     -h, --help              Show this help message
     -d, --dry-run           Preview what would be installed (no changes)
     -f, --force             Overwrite existing files
-    -p, --provider PROVIDER Set default AI provider (openai, stability, local)
+    -p, --provider PROVIDER Set default renderer
+                            (openai, xai, stability, gemini, local)
     --no-config             Skip _config.yml modification
     --no-tasks              Skip VS Code tasks installation
     -l, --local PATH        Copy files from local theme directory instead of downloading
 
 ${YELLOW}EXAMPLES:${NC}
-    # Install with defaults
+    # Install with defaults (OpenAI renders; Claude analyzes + reviews)
     ./$SCRIPT_NAME
 
     # Preview installation
     ./$SCRIPT_NAME --dry-run
 
-    # Install with Stability AI as default provider
-    ./$SCRIPT_NAME --provider stability
+    # Install with Gemini as the renderer
+    ./$SCRIPT_NAME --provider gemini
 
     # Force reinstall
     ./$SCRIPT_NAME --force
@@ -118,8 +121,13 @@ ${YELLOW}REMOTE INSTALLATION:${NC}
     curl -fsSL ${RAW_URL}/scripts/$SCRIPT_NAME | bash
 
 ${YELLOW}AFTER INSTALLATION:${NC}
-    1. Set your API key in .env file:
-       OPENAI_API_KEY=your-key-here
+    1. Set credentials in .env:
+       OPENAI_API_KEY=...            # the default renderer
+       Plus ONE Claude credential so Claude can analyze articles and
+       review the rendered images (optional — degrades to template prompts):
+       CLAUDE_CODE_OAUTH_TOKEN=...   # from \`claude setup-token\`
+       ANTHROPIC_API_KEY=...         # from console.anthropic.com
+       (or just have the \`claude\` CLI installed and logged in)
 
     2. Generate preview images:
        ./scripts/generate-preview-images.sh --list-missing
@@ -145,13 +153,13 @@ check_jekyll_site() {
 # Check dependencies
 check_dependencies() {
     local missing=()
-    
-    for cmd in curl jq; do
+
+    for cmd in curl jq python3; do
         if ! command -v "$cmd" &> /dev/null; then
             missing+=("$cmd")
         fi
     done
-    
+
     if [[ ${#missing[@]} -gt 0 ]]; then
         error "Missing required dependencies: ${missing[*]}"
         info "Install them with:"
@@ -159,7 +167,13 @@ check_dependencies() {
         info "  Ubuntu: sudo apt-get install ${missing[*]}"
         exit 1
     fi
-    
+
+    # The generation engine needs PyYAML (front matter / _config.yml parsing)
+    if ! python3 -c "import yaml" &> /dev/null; then
+        warn "PyYAML not found — the generator will not run until it is installed:"
+        info "  pip3 install pyyaml   (or: python3 -m pip install --user pyyaml)"
+    fi
+
     log "All dependencies satisfied"
 }
 
@@ -242,19 +256,22 @@ update_config() {
 
 # =============================================================================
 # AI Preview Image Generator Configuration
-# Feature: ZER0-003
+# Feature: ZER0-004
 # Documentation: ${REPO_URL}/blob/main/docs/features/preview-image-generator.md
 # =============================================================================
 preview_images:
   enabled: true
-  provider: ${DEFAULT_PROVIDER}          # openai, stability, or local
-  model: dall-e-3                        # OpenAI model to use
-  size: "1792x1024"                      # Landscape banner size
-  quality: standard                      # standard or hd
+  provider: ${DEFAULT_PROVIDER}          # renderer: openai, xai, stability, gemini, local
+  model: ""                              # empty = renderer default (gpt-image-2, grok-2-image, ...)
+  size: "1536x1024"                      # Landscape banner size
+  quality: auto                          # auto for GPT Image; standard/hd for DALL-E 3
   style: "retro pixel art, 8-bit video game aesthetic, vibrant colors, nostalgic, clean pixel graphics"
   style_modifiers: "pixelated, retro gaming style, CRT screen glow effect, limited color palette"
   output_dir: assets/images/previews     # Where to save generated images
-  auto_generate: false                   # Generate during build (slow, use script instead)
+  prompt_engine: claude                  # claude analyzes the article (template = built-in prompt)
+  review_engine: claude                  # claude reviews the render (none = skip)
+  assets_prefix: /assets                 # Prefix prepended to relative preview paths
+  auto_prefix: true                      # Auto-add assets_prefix when missing
   collections:                           # Collections to scan for missing previews
     - posts
     - docs
@@ -270,28 +287,32 @@ create_env_example() {
     
     if [[ -f "$env_example" ]]; then
         # Check if our keys are already there
-        if grep -q "OPENAI_API_KEY" "$env_example"; then
+        if grep -q "CLAUDE_CODE_OAUTH_TOKEN" "$env_example"; then
             info ".env.example already contains preview generator keys"
             return 0
         fi
     fi
-    
+
     if [[ "$DRY_RUN" == true ]]; then
         dry_run_log "Would add API keys to .env.example"
         return 0
     fi
-    
+
     step "Updating .env.example"
-    
-    cat >> "$env_example" << 'EOF'
 
-# AI Preview Image Generator API Keys
-# Get your key from: https://platform.openai.com/api-keys
-OPENAI_API_KEY=your-openai-api-key-here
+    cat >> "$env_example" << 'EOF'
 
-# Stability AI (alternative provider)
-# Get your key from: https://platform.stability.ai/
-STABILITY_API_KEY=your-stability-api-key-here
+# AI Preview Image Generator credentials
+# Renderer (the default provider is openai):
+# OPENAI_API_KEY=...      # https://platform.openai.com/api-keys (also powers --enhance)
+# XAI_API_KEY=...         # https://console.x.ai/
+# STABILITY_API_KEY=...   # https://platform.stability.ai/
+# GEMINI_API_KEY=...      # https://aistudio.google.com/apikey
+
+# Claude orchestration (analyzes articles + reviews renders) — any ONE of
+# (or a logged-in `claude` CLI; optional, degrades to template prompts):
+# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...   # from `claude setup-token`
+# ANTHROPIC_API_KEY=sk-ant-...               # from console.anthropic.com
 EOF
     
     log "Updated .env.example"
@@ -431,9 +452,10 @@ print_instructions() {
     echo ""
     echo -e "${YELLOW}NEXT STEPS:${NC}"
     echo ""
-    echo "  1. ${BLUE}Set up your API key:${NC}"
-    echo "     cp .env.example .env"
-    echo "     # Edit .env and add your OPENAI_API_KEY"
+    echo "  1. ${BLUE}Set up credentials:${NC}"
+    echo "     cp .env.example .env     # add OPENAI_API_KEY (the renderer)"
+    echo "     claude setup-token       # optional: lets Claude analyze + review"
+    echo "     (a logged-in \`claude\` CLI also works for the Claude side)"
     echo ""
     echo "  2. ${BLUE}Check for missing preview images:${NC}"
     echo "     ./scripts/generate-preview-images.sh --list-missing"

data/scripts/install/README.md

@@ -50,8 +50,7 @@ scripts/install/
 
 ### The Spec
 
-A single JSON document (`.zer0/install.spec.json`) is the universal contract
-between all front-ends and the executor:
+A single JSON document (`.zer0/install.spec.json`) is the universal contract between all front-ends and the executor:
 
 ```
 CLI flags → plan.sh → spec.json → apply.sh → tasks → files on disk
@@ -59,21 +58,18 @@ AI wizard → spec.json → apply.sh → tasks → files on disk
 TUI wizard → spec.json → apply.sh → tasks → files on disk
 ```
 
-The spec schema is defined in `ai/prompts/spec.schema.json`. The AI is
-constrained to emit only valid spec JSON — never raw file content.
+The spec schema is defined in `ai/prompts/spec.schema.json`. The AI is constrained to emit only valid spec JSON — never raw file content.
 
 ### Write contract
 
-**ALL filesystem writes go through `fs.sh`**. No raw `>`, `cp`, or `echo >` 
-outside of `fs.sh` functions. This enforces:
+**ALL filesystem writes go through `fs.sh`**. No raw `>`, `cp`, or `echo >` outside of `fs.sh` functions. This enforces:
 - `--dry-run`: zero mutations
 - `--backup`: auto-backup before overwrite
 - `--force`: overwrite without prompting
 
 ### Template contract
 
-**ALL generated file content comes from `templates/`**. No heredocs in shell
-code. Templates use `{{VARIABLE}}` substitution via `template.sh::tmpl_apply`.
+**ALL generated file content comes from `templates/`**. No heredocs in shell code. Templates use `{{VARIABLE}}` substitution via `template.sh::tmpl_apply`.
 
 ### Bash 3.2 compatibility
 
@@ -122,16 +118,13 @@ The AI path is a first-class citizen but never mandatory:
 - `ai_diagnose_run` → post-build error analysis  
 - `ai_suggest_run` → profile + deploy recommendation
 
-All three are guarded by `ZER0_NO_AI=1` kill-switch and degrade gracefully
-to defaults or rule-based logic when AI is unavailable.
+All three are guarded by `ZER0_NO_AI=1` kill-switch and degrade gracefully to defaults or rule-based logic when AI is unavailable.
 
 To enable: set `OPENAI_API_KEY` (or `OPENAI_BASE_URL` for Azure/Ollama).
 
 ## Deploy plugins
 
-Deploy targets listed in the spec (`SPEC_DEPLOY`) are dispatched as
-`tasks/deploy_<target>.sh` modules that render reusable templates from
-`templates/deploy/<target>/`. Built-in plugins:
+Deploy targets listed in the spec (`SPEC_DEPLOY`) are dispatched as `tasks/deploy_<target>.sh` modules that render reusable templates from `templates/deploy/<target>/`. Built-in plugins:
 
 | Target            | Writes                                                              |
 |-------------------|---------------------------------------------------------------------|
@@ -139,14 +132,11 @@ Deploy targets listed in the spec (`SPEC_DEPLOY`) are dispatched as
 | `azure-swa`       | `.github/workflows/azure-static-web-apps.yml`, `staticwebapp.config.json` |
 | `docker-prod`     | `Dockerfile.prod`, `docker-compose.prod.yml`, `nginx.conf`, `.dockerignore` |
 
-Add a new plugin by dropping `tasks/deploy_<target>.sh` with a
-`task_deploy_<target>_run` function plus a `templates/deploy/<target>/`
-template directory. The dispatcher is generic — no registry changes needed.
+Add a new plugin by dropping `tasks/deploy_<target>.sh` with a `task_deploy_<target>_run` function plus a `templates/deploy/<target>/` template directory. The dispatcher is generic — no registry changes needed.
 
 ## Testing
 
-A regression harness lives at [`test/test_installer.sh`](../../test/test_installer.sh)
-and is wired into the main runner as the `installer` suite:
+A regression harness lives at [`test/test_installer.sh`](../../test/test_installer.sh) and is wired into the main runner as the `installer` suite:
 
 ```bash
 # Standalone (auto-enables AI tier when OPENAI_API_KEY is set)
@@ -158,5 +148,4 @@ and is wired into the main runner as the `installer` suite:
 ./test/test_runner.sh --suites installer
 ```
 
-The harness covers: module syntax, all 6 profile inits, all 3 deploy plugins,
-all 5 agent flavours, and (when keyed) the full AI wizard → apply pipeline.
+The harness covers: module syntax, all 6 profile inits, all 3 deploy plugins, all 5 agent flavours, and (when keyed) the full AI wizard → apply pipeline.

data/scripts/install/ai/prompts/wizard.system.md

@@ -1,31 +1,24 @@
 # zer0-mistakes AI Installation Wizard
 
-You are the **zer0-mistakes installer wizard**. You convert the user's intent
-into a single, valid **install spec JSON** that conforms to the schema the
-caller will provide in the user prompt.
+You are the **zer0-mistakes installer wizard**. You convert the user's intent into a single, valid **install spec JSON** that conforms to the schema the caller will provide in the user prompt.
 
-You NEVER write files yourself. You ONLY emit a JSON spec. The installer's
-`apply.sh` is the sole writer.
+You NEVER write files yourself. You ONLY emit a JSON spec. The installer's `apply.sh` is the sole writer.
 
 ---
 
 ## Hard constraints (do not violate)
 
 1. **Output ONLY one JSON object.** No prose. No explanations. No markdown
-   fences (no triple-backticks). The first character of your reply MUST be
-   `{` and the last MUST be `}`.
+fences (no triple-backticks). The first character of your reply MUST be `{` and the last MUST be `}`.
 2. **Conform exactly to the provided schema.** All `required` keys must be
    present. All enums must match. `additionalProperties: false` is enforced.
 3. **Honor every value the user already provided** in the "Key info" block of
-   the user prompt — copy them through unchanged. Only fill in fields the
-   user left as `not set`.
+the user prompt — copy them through unchanged. Only fill in fields the user left as `not set`.
 4. **Always include `schema_version: "1"`**, the supplied `target_dir`, and
-   a complete `options` object (all 5 required keys: `dry_run`, `force`,
-   `backup`, `non_interactive`, `output`).
+a complete `options` object (all 5 required keys: `dry_run`, `force`, `backup`, `non_interactive`, `output`).
 5. **`tasks` MUST be non-empty and end with `"marker"`.**
 6. **Be decisive.** If information is ambiguous, pick the most reasonable
-   default and move on. Do not ask follow-up questions in non-interactive
-   mode.
+default and move on. Do not ask follow-up questions in non-interactive mode.
 
 ---
 
@@ -49,8 +42,7 @@ If a flag in "Key info" already names a profile, USE IT — do not second-guess.
 
 ## Task defaults (per profile)
 
-If you are unsure which tasks to enable, use these defaults. `marker` is
-always last.
+If you are unsure which tasks to enable, use these defaults. `marker` is always last.
 
 - `minimal`:      `["config", "gemfile", "gitignore", "marker"]`
 - `default`:      `["config", "gemfile", "docker", "pages", "nav", "data", "gitignore", "readme", "agents", "marker"]`
@@ -102,8 +94,7 @@ Populate `agents` (array, may be empty) based on signals:
 
 ## Required output shape (example)
 
-The example below is illustrative. Adapt every value to the user's request.
-The exact field set is enforced by the schema in the user prompt.
+The example below is illustrative. Adapt every value to the user's request. The exact field set is enforced by the schema in the user prompt.
 
 ```
 {

data/scripts/lib/README.md

@@ -49,11 +49,7 @@ validate_environment false false  # skip_publish=false, require_gh=false
 
 ### ✅ `scripts/bin/validate` - Preflight Validation
 
-Canonical command for local and CI preflight checks. It composes the release
-validation helpers with project-specific checks for version consistency, YAML
-configuration/data files, active configuration contracts, config-file
-classification, navigation data shape, Jekyll build/doctor, compiled assets,
-and optional test suites.
+Canonical command for local and CI preflight checks. It composes the release validation helpers with project-specific checks for version consistency, YAML configuration/data files, active configuration contracts, config-file classification, navigation data shape, Jekyll build/doctor, compiled assets, and optional test suites.
 
 **Usage:**
 

data/scripts/lib/install/deploy/README.md

@@ -1,8 +1,6 @@
 # scripts/lib/install/deploy/
 
-Pluggable deploy-target modules consumed by `scripts/bin/install deploy`
-(Phase 4 of the installer refactor). Each module configures one target;
-the registry coordinates discovery, dispatch, and verification.
+Pluggable deploy-target modules consumed by `scripts/bin/install deploy` (Phase 4 of the installer refactor). Each module configures one target; the registry coordinates discovery, dispatch, and verification.
 
 ## Files
 
@@ -26,16 +24,12 @@ Every module must define:
 | `deploy_<slug>_verify <dir>`            | Confirm expected files exist + look correct.             |
 | `deploy_<slug>_doc_url`                 | Print the canonical upstream documentation URL.          |
 
-Modules use the lightweight `deploy_render` placeholder set
-(`{{RUBY_VERSION}}`, `{{DEFAULT_BRANCH}}`, `{{GITHUB_USER}}`,
-`{{SITE_NAME}}`) so they can run without the full install.sh global
-environment.
+Modules use the lightweight `deploy_render` placeholder set (`{{RUBY_VERSION}}`, `{{DEFAULT_BRANCH}}`, `{{GITHUB_USER}}`, `{{SITE_NAME}}`) so they can run without the full install.sh global environment.
 
 ## Adding a target
 
 1. Add `templates/deploy/<slug>/` with the assets (workflow YAML,
-   Dockerfile, README, etc.). Use `*.template` for files that need
-   variable substitution.
+Dockerfile, README, etc.). Use `*.template` for files that need variable substitution.
 2. Create `scripts/lib/install/deploy/<slug>.sh` exporting the four
    hooks above.
 3. Add `<slug>` to `DEPLOY_TARGETS_LIST` in `registry.sh` (alphabetical).