jekyll-theme-zer0 0.22.21 → 0.22.22

data/scripts/lib/install/ai/openai.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+# scripts/lib/install/ai/openai.sh
+#
+# Shared OpenAI client + safety primitives for Phase 5 AI features.
+#
+# All AI features (wizard, diagnose, suggest) source this module. It provides:
+#   - ai_enabled            — global kill-switch check (ZER0_NO_AI=1 disables)
+#   - ai_require_key        — verify OPENAI_API_KEY is present
+#   - ai_default_model      — model selection (env override: ZER0_AI_MODEL)
+#   - ai_sanitize_text      — strip secrets/PII before sending to API
+#   - ai_estimate_cost      — print rough token + USD estimate
+#   - ai_call_chat          — POST to /v1/chat/completions (curl, 30s timeout)
+#   - ai_show_diff_confirm  — diff-then-confirm gate for any AI-generated file
+#
+# All network I/O is curl-based — no SDK dependency. All keys read from env
+# only — never persisted, never logged. All calls timeout at 30s with graceful
+# fallback (callers should check the return code and degrade to non-AI path).
+
+# shellcheck disable=SC2034
+AI_OPENAI_LIB_VERSION="1.0.0"
+
+AI_OPENAI_ENDPOINT="${AI_OPENAI_ENDPOINT:-https://api.openai.com/v1/chat/completions}"
+AI_OPENAI_TIMEOUT_SECS="${AI_OPENAI_TIMEOUT_SECS:-30}"
+
+# Default model per use-case. gpt-4o-mini is cheap; gpt-4o for harder tasks.
+ai_default_model() {
+    local kind="${1:-wizard}"
+    if [[ -n "${ZER0_AI_MODEL:-}" ]]; then
+        echo "$ZER0_AI_MODEL"
+        return
+    fi
+    case "$kind" in
+        diagnose) echo "gpt-4o" ;;
+        *)        echo "gpt-4o-mini" ;;
+    esac
+}
+
+# Returns 0 if AI is enabled (no kill-switch), 1 if disabled.
+ai_enabled() {
+    if [[ "${ZER0_NO_AI:-0}" = "1" ]]; then
+        return 1
+    fi
+    return 0
+}
+
+# Verify OPENAI_API_KEY is present. Prints install hint on failure.
+ai_require_key() {
+    if [[ -z "${OPENAI_API_KEY:-}" ]]; then
+        log_error "OPENAI_API_KEY environment variable is not set."
+        log_info  "Get a key at https://platform.openai.com/api-keys then:"
+        log_info  "  export OPENAI_API_KEY='sk-...'"
+        log_info  "Or run without --ai for the rule-based fallback."
+        return 1
+    fi
+    return 0
+}
+
+# Strip secrets and PII from a string before sending to the API.
+# Reads from stdin, writes sanitized text to stdout.
+#
+# Strips:
+#   - OPENAI_API_KEY / RUBYGEMS_API_KEY / GITHUB_TOKEN values
+#   - sk-... API key patterns
+#   - email addresses
+#   - $HOME absolute paths (replaced with ~)
+#   - 40+ char hex strings (likely tokens)
+ai_sanitize_text() {
+    local home_esc
+    # Escape $HOME for sed (handle / in path)
+    home_esc="$(printf '%s' "${HOME:-/Users/none}" | sed 's:/:\\/:g')"
+
+    sed \
+        -e "s/${home_esc}/~/g" \
+        -e 's/sk-[A-Za-z0-9_-]\{20,\}/[REDACTED_API_KEY]/g' \
+        -e 's/rubygems_[A-Za-z0-9]\{40,\}/[REDACTED_RUBYGEMS_KEY]/g' \
+        -e 's/ghp_[A-Za-z0-9]\{20,\}/[REDACTED_GITHUB_TOKEN]/g' \
+        -e 's/github_pat_[A-Za-z0-9_]\{20,\}/[REDACTED_GITHUB_PAT]/g' \
+        -e 's/[A-Za-z0-9._%+-]\{1,\}@[A-Za-z0-9.-]\{1,\}\.[A-Za-z]\{2,\}/[REDACTED_EMAIL]/g' \
+        -e 's/[^A-Fa-f0-9]\([A-Fa-f0-9]\{40,\}\)[^A-Fa-f0-9]/ [REDACTED_HASH] /g'
+}
+
+# Print a rough token + cost estimate so the user knows what they're spending
+# before the call goes out. Writes to stderr so caller can capture stdout.
+#
+# Args: <model> <input_chars> <expected_output_tokens>
+ai_estimate_cost() {
+    local model="$1" input_chars="$2" out_tokens="${3:-500}"
+    # ~4 chars per token (English text avg)
+    local in_tokens=$(( input_chars / 4 + 1 ))
+    local in_cents out_cents total_cents
+    case "$model" in
+        gpt-4o-mini)
+            # $0.15/1M input, $0.60/1M output  (approx, Nov 2024)
+            in_cents=$(( (in_tokens * 15 + 999999) / 1000000 ))
+            out_cents=$(( (out_tokens * 60 + 999999) / 1000000 ))
+            ;;
+        gpt-4o)
+            # $2.50/1M input, $10.00/1M output
+            in_cents=$(( (in_tokens * 250 + 999999) / 1000000 ))
+            out_cents=$(( (out_tokens * 1000 + 999999) / 1000000 ))
+            ;;
+        *)
+            in_cents=0; out_cents=0 ;;
+    esac
+    total_cents=$(( in_cents + out_cents ))
+    {
+        echo "  Model:     $model"
+        echo "  Input:     ~${in_tokens} tokens (${input_chars} chars)"
+        echo "  Output:    ~${out_tokens} tokens (cap)"
+        echo "  Est. cost: ≤ \$0.0$(printf '%02d' $total_cents)  (≤ ${total_cents}¢)"
+    } >&2
+}
+
+# Make a chat completion call. Returns the assistant message content on stdout.
+# Non-zero return on failure (network, auth, rate-limit, timeout).
+#
+# Args:
+#   $1 = model
+#   $2 = system prompt (string)
+#   $3 = user prompt (string)
+#   $4 = max_tokens (default 1024)
+#   $5 = temperature (default 0.3)
+ai_call_chat() {
+    local model="$1" system="$2" user="$3"
+    local max_tokens="${4:-1024}" temp="${5:-0.3}"
+
+    if ! ai_require_key; then
+        return 1
+    fi
+
+    # Build JSON payload via python (handles escaping safely; available on
+    # all macOS + most Linux distros). Falls back to a naive heredoc if
+    # python is missing — caller is expected to keep prompts ASCII-safe.
+    local payload
+    if command -v python3 >/dev/null 2>&1; then
+        payload="$(python3 - "$model" "$system" "$user" "$max_tokens" "$temp" <<'PY'
+import json, sys
+model, system, user, max_tokens, temp = sys.argv[1:]
+print(json.dumps({
+    "model": model,
+    "messages": [
+        {"role": "system", "content": system},
+        {"role": "user",   "content": user},
+    ],
+    "max_tokens": int(max_tokens),
+    "temperature": float(temp),
+}))
+PY
+)"
+    else
+        log_error "python3 not found — required for safe JSON payload construction."
+        return 1
+    fi
+
+    local resp http_code tmpfile
+    tmpfile="$(mktemp)"
+    # Capture body to tmpfile, status code to stdout, so we can branch on HTTP code.
+    http_code="$(curl -sS -o "$tmpfile" -w '%{http_code}' \
+        --max-time "$AI_OPENAI_TIMEOUT_SECS" \
+        -X POST "$AI_OPENAI_ENDPOINT" \
+        -H "Authorization: Bearer $OPENAI_API_KEY" \
+        -H 'Content-Type: application/json' \
+        --data-binary "$payload" 2>/dev/null || echo "000")"
+
+    resp="$(cat "$tmpfile")"
+    rm -f "$tmpfile"
+
+    if [[ "$http_code" != "200" ]]; then
+        log_error "OpenAI API call failed (HTTP $http_code)"
+        # Print first ~200 chars of response (already from API, no secrets)
+        echo "$resp" | head -c 200 >&2
+        echo >&2
+        return 1
+    fi
+
+    # Extract message content
+    if command -v python3 >/dev/null 2>&1; then
+        echo "$resp" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d["choices"][0]["message"]["content"])
+except Exception as e:
+    print(f"[parse error: {e}]", file=sys.stderr)
+    sys.exit(1)
+'
+    else
+        # Last-resort grep extraction (fragile; warn)
+        log_warning "python3 unavailable — falling back to fragile JSON extraction"
+        echo "$resp" | sed -n 's/.*"content":"\([^"]*\)".*/\1/p' | head -1
+    fi
+}
+
+# Show a unified diff between an existing file and a proposed new content,
+# and prompt the user to accept. Auto-accepts if --auto-accept (CI mode).
+#
+# Args: <existing_file_or_/dev/null> <proposed_content_string> <description> [auto_accept]
+# Returns 0 if user accepts (or auto-accept), 1 if rejected.
+ai_show_diff_confirm() {
+    local existing="$1" proposed="$2" desc="$3" auto="${4:-0}"
+    local tmp
+    tmp="$(mktemp)"
+    printf '%s\n' "$proposed" > "$tmp"
+
+    echo
+    log_info "Proposed change: $desc"
+    echo "─────────────────────────── diff ───────────────────────────"
+    if [[ -f "$existing" ]]; then
+        diff -u "$existing" "$tmp" || true
+    else
+        echo "(new file)"
+        diff -u /dev/null "$tmp" || true
+    fi
+    echo "────────────────────────────────────────────────────────────"
+    echo
+
+    if [[ "$auto" = "1" ]]; then
+        log_info "Auto-accept enabled — applying change."
+        echo "$tmp"  # caller reads this path then deletes
+        return 0
+    fi
+
+    printf "Apply this change? [y/N] "
+    local reply
+    read -r reply
+    if [[ "$reply" =~ ^[Yy]$ ]]; then
+        echo "$tmp"
+        return 0
+    fi
+    rm -f "$tmp"
+    log_warning "Rejected by user — no changes written."
+    return 1
+}

data/scripts/lib/install/ai/suggest.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# scripts/lib/install/ai/suggest.sh
+#
+# `install deploy --ai-suggest` — recommend a deploy target.
+#
+# Two modes:
+#   - Rule-based (default): inspects target dir for signals and picks a slug.
+#   - AI-assisted (--ai):  sends sanitized site stats to OpenAI for rationale.
+#
+# Public API:
+#     suggest_deploy_target <target_dir> <repo_root> [--ai] [--auto-accept]
+#
+# Prints recommended slug to stdout (last line). All other output to stderr.
+
+# shellcheck disable=SC2034
+AI_SUGGEST_LIB_VERSION="1.0.0"
+
+# Inspect the target dir and emit a human-readable summary on stdout.
+_suggest_collect_signals() {
+    local target_dir="$1"
+    local total_size site_files has_dockerfile has_api has_cname has_workflows
+    if command -v du >/dev/null 2>&1; then
+        total_size="$(du -sh "$target_dir" 2>/dev/null | awk '{print $1}')"
+    else
+        total_size="?"
+    fi
+    site_files="$(find "$target_dir" -type f \( -name '*.md' -o -name '*.html' \) 2>/dev/null | wc -l | tr -d ' ')"
+    has_dockerfile=no; [[ -f "$target_dir/Dockerfile" ]] || [[ -f "$target_dir/docker/Dockerfile.prod" ]] && has_dockerfile=yes
+    has_api=no
+    if find "$target_dir" -type d \( -name 'api' -o -name 'functions' \) 2>/dev/null | grep -q .; then
+        has_api=yes
+    fi
+    has_cname=no; [[ -f "$target_dir/CNAME" ]] && has_cname=yes
+    has_workflows=no; [[ -d "$target_dir/.github/workflows" ]] && has_workflows=yes
+
+    cat <<EOF
+size:         $total_size
+content_files: $site_files
+has_dockerfile: $has_dockerfile
+has_api_or_functions: $has_api
+has_cname: $has_cname
+has_workflows: $has_workflows
+EOF
+}
+
+# Pure rule-based scoring. Deterministic.
+_suggest_rule_based() {
+    local signals="$1"
+    local has_api has_dockerfile has_cname
+    has_api="$(printf '%s\n' "$signals" | grep '^has_api_or_functions:' | awk '{print $2}')"
+    has_dockerfile="$(printf '%s\n' "$signals" | grep '^has_dockerfile:' | awk '{print $2}')"
+    has_cname="$(printf '%s\n' "$signals" | grep '^has_cname:' | awk '{print $2}')"
+
+    local slug rationale
+    if [[ "$has_api" = "yes" ]]; then
+        slug="azure-swa"
+        rationale="API/functions directory present → Azure Static Web Apps integrates serverless functions out of the box."
+    elif [[ "$has_dockerfile" = "yes" ]] && [[ "$has_cname" = "yes" ]]; then
+        slug="docker-prod"
+        rationale="Existing Dockerfile + custom domain (CNAME) → self-hosted Docker gives full control."
+    else
+        slug="github-pages"
+        rationale="No API code, no custom Docker build → GitHub Pages is the simplest, cheapest target."
+    fi
+    {
+        echo "Rule-based recommendation:"
+        echo "  Target:    $slug"
+        echo "  Rationale: $rationale"
+    } >&2
+    printf '%s\n' "$slug"
+}
+
+# AI-assisted recommendation. Returns slug on stdout.
+_suggest_ai() {
+    local signals="$1" repo_root="$2" auto_accept="$3"
+
+    if ! ai_enabled; then
+        log_warning "AI is disabled (ZER0_NO_AI=1) — using rule-based only."
+        return 1
+    fi
+    if ! ai_require_key; then
+        return 1
+    fi
+
+    local sys_prompt_file="$repo_root/templates/ai/prompts/suggest-system.md"
+    if [[ ! -f "$sys_prompt_file" ]]; then
+        log_error "System prompt missing: $sys_prompt_file"
+        return 1
+    fi
+    local system_prompt
+    system_prompt="$(cat "$sys_prompt_file")"
+
+    local user_prompt="Site signals:
+${signals}
+
+Available deploy targets:
+- github-pages: GitHub Pages with peaceiris/actions-gh-pages
+- azure-swa:    Azure Static Web Apps (supports serverless functions)
+- docker-prod:  Self-hosted Ruby builder + nginx:alpine container
+
+Recommend exactly one target. Respond with two lines:
+TARGET: <slug>
+RATIONALE: <one sentence>"
+
+    local model
+    model="$(ai_default_model wizard)"
+    local in_chars=$(( ${#system_prompt} + ${#user_prompt} ))
+    {
+        log_info "About to call OpenAI:"
+        ai_estimate_cost "$model" "$in_chars" 200
+    } >&2
+
+    if [[ "$auto_accept" != "1" ]]; then
+        printf "Proceed with API call? [y/N] " >&2
+        local go
+        read -r go
+        if [[ ! "$go" =~ ^[Yy]$ ]]; then
+            log_warning "Aborted by user."
+            return 1
+        fi
+    fi
+
+    log_info "Calling $model ..." >&2
+    local resp
+    if ! resp="$(ai_call_chat "$model" "$system_prompt" "$user_prompt" 200 0.2)"; then
+        log_error "OpenAI call failed."
+        return 1
+    fi
+
+    {
+        echo "AI recommendation:"
+        printf '%s\n' "$resp" | sed 's/^/  /'
+    } >&2
+
+    # Extract slug from "TARGET: <slug>" line
+    local slug
+    slug="$(printf '%s\n' "$resp" | sed -n 's/^TARGET:[[:space:]]*\([a-z-]*\).*/\1/p' | head -1)"
+    if [[ -z "$slug" ]]; then
+        log_error "Could not parse TARGET: line from AI response."
+        return 1
+    fi
+    printf '%s\n' "$slug"
+}
+
+suggest_deploy_target() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local use_ai=0 auto_accept=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ai) use_ai=1 ;;
+            --auto-accept) auto_accept=1 ;;
+            *) log_warning "suggest_deploy_target: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    if [[ ! -d "$target_dir" ]]; then
+        log_error "Target directory does not exist: $target_dir"
+        return 1
+    fi
+
+    log_info "Inspecting target site for deploy signals ..." >&2
+    local signals
+    signals="$(_suggest_collect_signals "$target_dir")"
+    {
+        echo "Site signals:"
+        printf '%s\n' "$signals" | sed 's/^/  /'
+        echo
+    } >&2
+
+    local slug
+    if [[ "$use_ai" = "1" ]]; then
+        if slug="$(_suggest_ai "$signals" "$repo_root" "$auto_accept")"; then
+            printf '%s\n' "$slug"
+            return 0
+        fi
+        log_warning "AI suggestion failed — falling back to rule-based."
+    fi
+    _suggest_rule_based "$signals"
+}

data/scripts/lib/install/ai/wizard.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# scripts/lib/install/ai/wizard.sh
+#
+# `install wizard --ai` — opt-in OpenAI-powered config generation.
+#
+# Flow:
+#   1. ai_enabled() check (ZER0_NO_AI kill-switch)
+#   2. ai_require_key() check (OPENAI_API_KEY)
+#   3. Prompt user for: site description, target audience, deploy preference
+#   4. Read system prompt from templates/ai/prompts/wizard-system.md
+#   5. ai_estimate_cost() → user sees price estimate
+#   6. ai_call_chat() → returns JSON: {title, description, tagline, navigation,
+#                                       welcome_post_outline, suggested_deploy_target}
+#   7. ai_show_diff_confirm() per generated file (_config.yml, navigation,
+#                                                  welcome post)
+#   8. On any failure → fall back to non-AI wizard (delegated to caller).
+#
+# Public API:
+#     wizard_ai_run <target_dir> <repo_root> [--auto-accept]
+#
+# Returns 0 on success, 1 on failure (caller should fall back).
+
+# shellcheck disable=SC2034
+AI_WIZARD_LIB_VERSION="1.0.0"
+
+wizard_ai_run() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local auto_accept=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --auto-accept) auto_accept=1 ;;
+            *) log_warning "wizard_ai_run: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    if ! ai_enabled; then
+        log_warning "AI is disabled (ZER0_NO_AI=1) — cannot run --ai wizard."
+        return 1
+    fi
+    if ! ai_require_key; then
+        return 1
+    fi
+
+    # 1. Gather user inputs
+    log_info "AI Wizard — describe your site in a sentence or two."
+    log_info "Examples: 'Personal blog about Rust performance' or 'Docs site for an open-source CLI'."
+    printf "Site description: "
+    local site_desc audience deploy_pref
+    read -r site_desc
+    if [[ -z "$site_desc" ]]; then
+        log_error "Empty description — aborting AI wizard."
+        return 1
+    fi
+    printf "Target audience (e.g., 'developers', 'data scientists', 'general'): "
+    read -r audience
+    [[ -z "$audience" ]] && audience="developers"
+    printf "Deploy preference (github-pages | azure-swa | docker-prod | unsure): "
+    read -r deploy_pref
+    [[ -z "$deploy_pref" ]] && deploy_pref="unsure"
+
+    # 2. Load system prompt
+    local sys_prompt_file="$repo_root/templates/ai/prompts/wizard-system.md"
+    if [[ ! -f "$sys_prompt_file" ]]; then
+        log_error "System prompt missing: $sys_prompt_file"
+        return 1
+    fi
+    local system_prompt
+    system_prompt="$(cat "$sys_prompt_file")"
+
+    # 3. Build user prompt
+    local user_prompt
+    user_prompt="Site description: ${site_desc}
+Target audience: ${audience}
+Deploy preference: ${deploy_pref}
+
+Return ONLY a JSON object with keys: title, description, tagline, suggested_deploy_target, navigation (array of {label, url}), welcome_post_outline (string of 3-5 bullet points)."
+
+    # Sanitize (paranoid — user input could contain pasted secrets)
+    user_prompt="$(printf '%s' "$user_prompt" | ai_sanitize_text)"
+
+    # 4. Cost estimate + confirm
+    local model
+    model="$(ai_default_model wizard)"
+    local in_chars=$(( ${#system_prompt} + ${#user_prompt} ))
+    log_info "About to call OpenAI:"
+    ai_estimate_cost "$model" "$in_chars" 800
+    if [[ "$auto_accept" != "1" ]]; then
+        printf "Proceed with API call? [y/N] "
+        local go
+        read -r go
+        if [[ ! "$go" =~ ^[Yy]$ ]]; then
+            log_warning "Aborted by user."
+            return 1
+        fi
+    fi
+
+    # 5. Call API
+    log_info "Calling $model ..."
+    local raw
+    if ! raw="$(ai_call_chat "$model" "$system_prompt" "$user_prompt" 1024 0.4)"; then
+        log_error "OpenAI call failed."
+        return 1
+    fi
+
+    # 6. Parse JSON (strip code-fence if present)
+    local json
+    json="$(printf '%s' "$raw" | sed -E '/^```(json)?$/d')"
+    if ! command -v python3 >/dev/null 2>&1; then
+        log_error "python3 required to parse wizard response."
+        return 1
+    fi
+
+    # Extract fields safely
+    local title description tagline suggested_deploy
+    title="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("title",""))' 2>/dev/null || echo "")"
+    description="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("description",""))' 2>/dev/null || echo "")"
+    tagline="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("tagline",""))' 2>/dev/null || echo "")"
+    suggested_deploy="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("suggested_deploy_target",""))' 2>/dev/null || echo "")"
+
+    if [[ -z "$title" ]]; then
+        log_error "Failed to parse AI response (missing 'title' field)."
+        log_info  "Raw response: $raw"
+        return 1
+    fi
+
+    # 7. Build proposed _config.yml fragment + diff
+    local cfg_file="$target_dir/_config.yml"
+    local proposed
+    proposed="$(cat <<EOF
+# Generated by install wizard --ai
+title: "$title"
+description: "$description"
+tagline: "$tagline"
+EOF
+)"
+    log_info "AI suggests deploy target: ${suggested_deploy:-(none)}"
+    if [[ -f "$cfg_file" ]]; then
+        log_warning "_config.yml already exists. The AI suggestions above won't be merged automatically."
+        log_info  "Recommended: cp the values you like into _config.yml manually."
+    else
+        local accepted_path
+        if accepted_path="$(ai_show_diff_confirm "$cfg_file" "$proposed" "Create _config.yml" "$auto_accept")"; then
+            mv "$accepted_path" "$cfg_file"
+            log_success "Wrote $cfg_file"
+        fi
+    fi
+
+    # 8. Print full JSON for user reference (so welcome post outline + nav
+    #    aren't lost). User can manually convert to files.
+    echo
+    log_info "Full AI response (use these to flesh out navigation + a welcome post):"
+    echo "─────────────────────────────────────────────────────────────"
+    printf '%s\n' "$json"
+    echo "─────────────────────────────────────────────────────────────"
+
+    return 0
+}

data/scripts/lib/install/config.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# =========================================================================
+# scripts/lib/install/config.sh
+# =========================================================================
+# Configuration loader for install.sh.
+#
+# load_install_config <SCRIPT_DIR> [<SOURCE_DIR>]
+#   Searches for templates/config/install.conf in either of the supplied
+#   directories. On success: sources it, exports TEMPLATES_DIR, returns 0.
+#   On failure: applies hard-coded fallback defaults and returns 1.
+#
+# This function is identical in behaviour to the previous private
+# `_load_install_config` inside install.sh; the only change is location +
+# accepting the search roots as parameters (so the function is testable
+# without globals).
+# =========================================================================
+
+load_install_config() {
+    local script_dir="${1:-${SCRIPT_DIR:-$(pwd)}}"
+    local source_dir="${2:-${SOURCE_DIR:-$script_dir}}"
+
+    local config_paths=(
+        "$script_dir/templates/config/install.conf"
+        "$source_dir/templates/config/install.conf"
+    )
+
+    local config_path
+    for config_path in "${config_paths[@]}"; do
+        if [[ -f "$config_path" ]]; then
+            # shellcheck source=/dev/null
+            source "$config_path"
+            export TEMPLATES_DIR="$(dirname "$(dirname "$config_path")")"
+            return 0
+        fi
+    done
+
+    # Fallback defaults when templates not available (remote install
+    # without bundled templates/, or stripped distribution).
+    export THEME_NAME="${THEME_NAME:-zer0-mistakes}"
+    export THEME_GEM_NAME="${THEME_GEM_NAME:-jekyll-theme-zer0}"
+    export THEME_DISPLAY_NAME="${THEME_DISPLAY_NAME:-Zer0-Mistakes Jekyll Theme}"
+    export GITHUB_USER="${GITHUB_USER:-bamr87}"
+    export GITHUB_REPO="${GITHUB_REPO:-bamr87/zer0-mistakes}"
+    export GITHUB_URL="${GITHUB_URL:-https://github.com/bamr87/zer0-mistakes}"
+    export GITHUB_RAW_URL="${GITHUB_RAW_URL:-https://raw.githubusercontent.com/bamr87/zer0-mistakes/main}"
+    export DEFAULT_PORT="${DEFAULT_PORT:-4000}"
+    export DEFAULT_URL="${DEFAULT_URL:-http://localhost:4000}"
+    export JEKYLL_VERSION="${JEKYLL_VERSION:-~> 4.3}"
+    export FFI_VERSION="${FFI_VERSION:-~> 1.17.0}"
+    export WEBRICK_VERSION="${WEBRICK_VERSION:-~> 1.7}"
+    export COMMONMARKER_VERSION="${COMMONMARKER_VERSION:-0.23.10}"
+    export GITHUB_PAGES_MAX_VERSION="${GITHUB_PAGES_MAX_VERSION:-232}"
+    export COMMONMARKER_MACOS_VERSION="${COMMONMARKER_MACOS_VERSION:-~> 0.23}"
+    export RUBY_MIN_VERSION_MACOS="${RUBY_MIN_VERSION_MACOS:-2.6.0}"
+    return 1
+}

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

@@ -0,0 +1,52 @@
+# 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.
+
+## Files
+
+| File              | Role                                                                |
+| ----------------- | ------------------------------------------------------------------- |
+| `registry.sh`     | Module discovery, dispatch, shared `deploy_render` / `deploy_copy`. |
+| `github-pages.sh` | Actions workflow that publishes `_site/` to `gh-pages`.             |
+| `azure-swa.sh`    | Azure SWA workflow + `staticwebapp.config.json`.                    |
+| `docker-prod.sh`  | Multi-stage Docker build + production compose + nginx config.       |
+
+## Module contract
+
+Every module must define:
+
+| Symbol                                  | Purpose                                                  |
+| --------------------------------------- | -------------------------------------------------------- |
+| `DEPLOY_<SLUG_UPPER>_TITLE`             | One-line display name shown by `install list-targets`.   |
+| `DEPLOY_<SLUG_UPPER>_SUMMARY`           | One-line description shown by `install list-targets`.    |
+| `deploy_<slug>_check_prereqs <dir>`     | Print warnings; return non-zero only on hard blockers.   |
+| `deploy_<slug>_install <dir>`           | Idempotent file install (uses `deploy_render_if_absent`).|
+| `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.
+
+## Adding a target
+
+1. Add `templates/deploy/<slug>/` with the assets (workflow YAML,
+   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).
+4. Optionally reference `<slug>` under `deploy_targets:` in
+   `templates/profiles/*.yml` so the profile can suggest it.
+5. Update `templates/deploy/README.md` with the new target row.
+
+## CLI integration
+
+```bash
+./scripts/bin/install list-targets
+./scripts/bin/install deploy github-pages /path/to/site
+./scripts/bin/install deploy azure-swa,docker-prod /path/to/site
+```