jekyll-theme-zer0 0.22.21 → 1.0.0

data/scripts/lib/install/deploy/azure-swa.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/azure-swa.sh
+#
+# Deploy module: Azure Static Web Apps. Replaces the legacy
+# install.sh::create_azure_static_web_apps_workflow heredoc and adds
+# a sensible staticwebapp.config.json.
+
+DEPLOY_AZURE_SWA_TITLE="Azure Static Web Apps"
+DEPLOY_AZURE_SWA_SUMMARY="Workflow + config for Azure SWA. Requires AZURE_STATIC_WEB_APPS_API_TOKEN secret."
+
+deploy_azure_swa_check_prereqs() {
+    local target_dir="$1"
+    if [ ! -f "$target_dir/Gemfile" ]; then
+        log_warning "Gemfile not found in $target_dir — Azure build step will fail until one exists."
+    fi
+    return 0
+}
+
+deploy_azure_swa_install() {
+    local target_dir="$1"
+    local repo_root="${REPO_ROOT:-$(deploy_repo_root)}"
+    local src_dir="$repo_root/templates/deploy/azure-swa"
+
+    deploy_render_if_absent \
+        "$src_dir/azure-static-web-apps.yml.template" \
+        "$target_dir/.github/workflows/azure-static-web-apps.yml"
+
+    deploy_copy \
+        "$src_dir/staticwebapp.config.json" \
+        "$target_dir/staticwebapp.config.json"
+}
+
+deploy_azure_swa_verify() {
+    local target_dir="$1"
+    local wf="$target_dir/.github/workflows/azure-static-web-apps.yml"
+    local cfg="$target_dir/staticwebapp.config.json"
+    local ok=0
+    [ -f "$wf" ]  || { log_error "Missing $wf"; ok=1; }
+    [ -f "$cfg" ] || { log_error "Missing $cfg"; ok=1; }
+    [ "$ok" = "0" ] || return 1
+    grep -q 'Azure/static-web-apps-deploy' "$wf" || {
+        log_warning "Workflow does not reference Azure/static-web-apps-deploy"
+        return 1
+    }
+    return 0
+}
+
+deploy_azure_swa_doc_url() {
+    echo "https://learn.microsoft.com/azure/static-web-apps/"
+}

data/scripts/lib/install/deploy/docker-prod.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/docker-prod.sh
+#
+# Deploy module: self-hosted production Docker (multi-stage Ruby + Nginx).
+# Installs docker/Dockerfile.prod, docker-compose.prod.yml, docker/nginx.conf,
+# and (if absent) a .dockerignore tuned for the build context.
+
+DEPLOY_DOCKER_PROD_TITLE="Self-hosted production Docker"
+DEPLOY_DOCKER_PROD_SUMMARY="Two-stage build (Ruby builder + nginx:alpine runtime) with healthcheck + compose."
+
+deploy_docker_prod_check_prereqs() {
+    local target_dir="$1"
+    if ! command -v docker >/dev/null 2>&1; then
+        log_warning "docker CLI not found in PATH — files will be installed but you cannot build the image locally."
+    fi
+    if [ ! -f "$target_dir/Gemfile" ]; then
+        log_warning "Gemfile not found in $target_dir — Docker build will fail until one exists."
+    fi
+    return 0
+}
+
+deploy_docker_prod_install() {
+    local target_dir="$1"
+    local repo_root="${REPO_ROOT:-$(deploy_repo_root)}"
+    local src_dir="$repo_root/templates/deploy/docker-prod"
+
+    DEPLOY_SITE_NAME="${DEPLOY_SITE_NAME:-$(basename "$target_dir")}"
+
+    deploy_render_if_absent \
+        "$src_dir/Dockerfile.prod.template" \
+        "$target_dir/docker/Dockerfile.prod"
+
+    deploy_render_if_absent \
+        "$src_dir/docker-compose.prod.yml.template" \
+        "$target_dir/docker-compose.prod.yml"
+
+    deploy_copy \
+        "$src_dir/nginx.conf" \
+        "$target_dir/docker/nginx.conf"
+
+    # .dockerignore: only install when missing so we never clobber user rules.
+    if [ ! -f "$target_dir/.dockerignore" ]; then
+        deploy_copy "$src_dir/.dockerignore" "$target_dir/.dockerignore"
+    else
+        log_warning ".dockerignore already exists, leaving untouched."
+    fi
+}
+
+deploy_docker_prod_verify() {
+    local target_dir="$1"
+    local ok=0
+    for f in \
+        "$target_dir/docker/Dockerfile.prod" \
+        "$target_dir/docker-compose.prod.yml" \
+        "$target_dir/docker/nginx.conf"; do
+        if [ ! -f "$f" ]; then
+            log_error "Missing $f"
+            ok=1
+        fi
+    done
+    [ "$ok" = "0" ] || return 1
+    grep -q 'nginx:alpine' "$target_dir/docker/Dockerfile.prod" || {
+        log_warning "Dockerfile.prod is missing the nginx:alpine runtime stage"
+        return 1
+    }
+    return 0
+}
+
+deploy_docker_prod_doc_url() {
+    echo "https://docs.docker.com/compose/production/"
+}

data/scripts/lib/install/deploy/github-pages.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/github-pages.sh
+#
+# Deploy module: GitHub Pages (Actions-based, peaceiris/actions-gh-pages).
+# Generates .github/workflows/jekyll-gh-pages.yml.
+
+DEPLOY_GITHUB_PAGES_TITLE="GitHub Pages (Actions)"
+DEPLOY_GITHUB_PAGES_SUMMARY="Builds with Bundler and publishes _site/ to the gh-pages branch."
+
+deploy_github_pages_check_prereqs() {
+    local target_dir="$1"
+    if [ ! -f "$target_dir/_config.yml" ]; then
+        log_warning "_config.yml not found in $target_dir — workflow will still install but may not build."
+    fi
+    return 0
+}
+
+deploy_github_pages_install() {
+    local target_dir="$1"
+    local repo_root="${REPO_ROOT:-$(deploy_repo_root)}"
+    local src="$repo_root/templates/deploy/github-pages/jekyll-gh-pages.yml.template"
+    local dest="$target_dir/.github/workflows/jekyll-gh-pages.yml"
+
+    DEPLOY_SITE_NAME="${DEPLOY_SITE_NAME:-$(basename "$target_dir")}"
+    deploy_render_if_absent "$src" "$dest"
+}
+
+deploy_github_pages_verify() {
+    local target_dir="$1"
+    local f="$target_dir/.github/workflows/jekyll-gh-pages.yml"
+    if [ ! -f "$f" ]; then
+        log_error "Expected $f not present"
+        return 1
+    fi
+    grep -q 'peaceiris/actions-gh-pages' "$f" || {
+        log_warning "Workflow does not reference peaceiris/actions-gh-pages"
+        return 1
+    }
+    return 0
+}
+
+deploy_github_pages_doc_url() {
+    echo "https://docs.github.com/pages"
+}

data/scripts/lib/install/deploy/registry.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/registry.sh
+#
+# Discovery + dispatch helpers for deploy target modules.
+#
+# Each module under scripts/lib/install/deploy/<slug>.sh must define the
+# four hooks below (the registry verifies presence after sourcing):
+#
+#   deploy_<slug>_check_prereqs <target_dir>
+#       Print warnings / errors. Return 0 if safe to proceed.
+#
+#   deploy_<slug>_install <target_dir>
+#       Render templates / copy files into <target_dir>. Idempotent.
+#
+#   deploy_<slug>_verify <target_dir>
+#       Confirm the install produced the expected files. Return 0 on OK.
+#
+#   deploy_<slug>_doc_url
+#       Print a single URL pointing at upstream documentation.
+#
+# A target's display name + one-line description live next to the module
+# in scripts/lib/install/deploy/<slug>.sh as `DEPLOY_<SLUG_UPPER>_TITLE`
+# and `DEPLOY_<SLUG_UPPER>_SUMMARY` (sourced via `eval`).
+#
+# Bash 3.2 compatible. No associative arrays, no mapfile.
+
+# Canonical list of supported targets (alphabetical).
+DEPLOY_TARGETS_LIST="azure-swa docker-prod github-pages"
+
+# Resolve REPO_ROOT lazily so callers can override via $1.
+deploy_repo_root() {
+    if [ -n "${REPO_ROOT:-}" ]; then
+        echo "$REPO_ROOT"
+        return 0
+    fi
+    local here
+    here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    ( cd "$here/../../.." && pwd )
+}
+
+deploy_targets_dir() {
+    local repo_root="${1:-$(deploy_repo_root)}"
+    echo "$repo_root/templates/deploy"
+}
+
+deploy_modules_dir() {
+    local repo_root="${1:-$(deploy_repo_root)}"
+    echo "$repo_root/scripts/lib/install/deploy"
+}
+
+deploy_target_known() {
+    local slug="$1" t
+    for t in $DEPLOY_TARGETS_LIST; do
+        [ "$t" = "$slug" ] && return 0
+    done
+    return 1
+}
+
+# Convert kebab-case to function-name fragment: github-pages -> github_pages
+deploy_slug_fn() {
+    echo "$1" | tr '-' '_'
+}
+
+# Convert kebab-case to upper var fragment: github-pages -> GITHUB_PAGES
+deploy_slug_var() {
+    echo "$1" | tr '[:lower:]-' '[:upper:]_'
+}
+
+# Source a target module (idempotent). Sets DEPLOY_LAST_LOADED on success.
+deploy_load_module() {
+    local slug="$1"
+    local repo_root="${2:-$(deploy_repo_root)}"
+    local module="$(deploy_modules_dir "$repo_root")/${slug}.sh"
+    if [ ! -f "$module" ]; then
+        log_error "Deploy module not found: $module"
+        return 1
+    fi
+    # shellcheck disable=SC1090
+    . "$module"
+    DEPLOY_LAST_LOADED="$slug"
+}
+
+# Print one-line summary for `install list-targets`.
+deploy_print_summary() {
+    local slug="$1"
+    local repo_root="${2:-$(deploy_repo_root)}"
+    deploy_load_module "$slug" "$repo_root" >/dev/null 2>&1 || return 0
+    local var_frag title summary
+    var_frag="$(deploy_slug_var "$slug")"
+    eval "title=\${DEPLOY_${var_frag}_TITLE:-$slug}"
+    eval "summary=\${DEPLOY_${var_frag}_SUMMARY:-(no summary)}"
+    printf '  %-13s %s\n' "$slug" "$title"
+    printf '                %s\n' "$summary"
+}
+
+# Run the four hooks for a single target.
+deploy_run_target() {
+    local slug="$1" target_dir="$2"
+    local repo_root="${3:-$(deploy_repo_root)}"
+    local fn
+
+    if ! deploy_target_known "$slug"; then
+        log_error "Unknown deploy target: $slug"
+        log_info  "Available targets: $DEPLOY_TARGETS_LIST"
+        return 1
+    fi
+
+    if [ ! -d "$target_dir" ]; then
+        log_error "Target directory does not exist: $target_dir"
+        return 1
+    fi
+
+    deploy_load_module "$slug" "$repo_root" || return 1
+    fn="$(deploy_slug_fn "$slug")"
+
+    log_info "▶ Configuring deploy target: $slug"
+
+    if ! "deploy_${fn}_check_prereqs" "$target_dir"; then
+        log_error "Prerequisite check failed for $slug"
+        return 1
+    fi
+
+    if ! "deploy_${fn}_install" "$target_dir"; then
+        log_error "Install step failed for $slug"
+        return 1
+    fi
+
+    if ! "deploy_${fn}_verify" "$target_dir"; then
+        log_warning "Verification reported issues for $slug (manual review recommended)"
+    else
+        log_success "Deploy target $slug installed successfully"
+    fi
+
+    local url
+    url="$("deploy_${fn}_doc_url" 2>/dev/null || true)"
+    [ -n "$url" ] && log_info "Documentation: $url"
+}
+
+# Lightweight renderer used by all deploy modules. Operates on a small,
+# explicit allow-list of placeholders so modules don't need to set up
+# install.sh's full global environment.
+#
+# Usage: deploy_render <template_file> <output_file>
+# Variables consulted (with defaults):
+#   DEPLOY_RUBY_VERSION   (default 3.3)
+#   DEPLOY_DEFAULT_BRANCH (default main)
+#   DEPLOY_GITHUB_USER    (default $GITHUB_USER, then $USER, then "me")
+#   DEPLOY_SITE_NAME      (default basename of target dir, then "site")
+deploy_render() {
+    local src="$1" dest="$2"
+    [ -f "$src" ] || { log_error "Template not found: $src"; return 1; }
+
+    local ruby_v branch user site
+    ruby_v="${DEPLOY_RUBY_VERSION:-3.3}"
+    branch="${DEPLOY_DEFAULT_BRANCH:-main}"
+    user="${DEPLOY_GITHUB_USER:-${GITHUB_USER:-${USER:-me}}}"
+    site="${DEPLOY_SITE_NAME:-site}"
+
+    mkdir -p "$(dirname "$dest")"
+    sed \
+        -e "s|{{RUBY_VERSION}}|${ruby_v}|g" \
+        -e "s|{{DEFAULT_BRANCH}}|${branch}|g" \
+        -e "s|{{GITHUB_USER}}|${user}|g" \
+        -e "s|{{SITE_NAME}}|${site}|g" \
+        "$src" > "$dest"
+}
+
+# Copy a file verbatim (no rendering). Skips when destination exists
+# unless DEPLOY_FORCE=1.
+deploy_copy() {
+    local src="$1" dest="$2"
+    [ -f "$src" ] || { log_error "Source not found: $src"; return 1; }
+    if [ -f "$dest" ] && [ "${DEPLOY_FORCE:-0}" != "1" ]; then
+        log_warning "Exists, skipping: ${dest}"
+        return 0
+    fi
+    mkdir -p "$(dirname "$dest")"
+    cp "$src" "$dest"
+    log_info "Wrote: ${dest}"
+}
+
+# Same as deploy_copy but for rendered templates (logs accordingly).
+deploy_render_if_absent() {
+    local src="$1" dest="$2"
+    if [ -f "$dest" ] && [ "${DEPLOY_FORCE:-0}" != "1" ]; then
+        log_warning "Exists, skipping: ${dest}"
+        return 0
+    fi
+    deploy_render "$src" "$dest" && log_info "Rendered: ${dest}"
+}

data/scripts/lib/install/doctor.sh

@@ -0,0 +1,301 @@
+#!/usr/bin/env bash
+# scripts/lib/install/doctor.sh
+#
+# `install doctor` — environment + site health check.
+#
+# Runs platform-specific prerequisite checks (delegating to
+# scripts/platform/setup-{macos,linux,wsl}.sh in check-only mode), then
+# layers zer0-mistakes-specific checks on top: gh CLI, Docker compose,
+# Bundler/Jekyll versions, agent files, and OpenAI connectivity (opt-in).
+#
+# Output: structured pass/warn/fail report. Exits 0 when no FAIL,
+# 1 when at least one FAIL.
+#
+# Public API:
+#     doctor_run <target_dir> <repo_root> [--ai] [--quiet] [--json]
+#
+# Bash 3.2-compatible. Pure shell — no jq required.
+
+# shellcheck disable=SC2034
+DOCTOR_LIB_VERSION="1.0.0"
+
+# Counters (reset on every doctor_run call)
+DOCTOR_PASS=0
+DOCTOR_WARN=0
+DOCTOR_FAIL=0
+DOCTOR_REPORT=""
+
+# Append a structured row.
+# args: status (PASS|WARN|FAIL) name detail [remediation]
+_doctor_row() {
+    local status="$1" name="$2" detail="$3" remediation="${4:-}"
+    case "$status" in
+        PASS) DOCTOR_PASS=$((DOCTOR_PASS+1)); log_success "$name: $detail" ;;
+        WARN) DOCTOR_WARN=$((DOCTOR_WARN+1)); log_warning "$name: $detail"; [[ -n "$remediation" ]] && log_info "  → $remediation" ;;
+        FAIL) DOCTOR_FAIL=$((DOCTOR_FAIL+1)); log_error "$name: $detail"; [[ -n "$remediation" ]] && log_info "  → $remediation" ;;
+    esac
+    DOCTOR_REPORT="${DOCTOR_REPORT}${status}|${name}|${detail}|${remediation}
+"
+}
+
+# ── Platform checks ────────────────────────────────────────────────────────
+_doctor_platform() {
+    local repo_root="$1"
+    local os
+    os="$(uname -s 2>/dev/null || echo unknown)"
+
+    local script=""
+    case "$os" in
+        Darwin)              script="$repo_root/scripts/platform/setup-macos.sh" ;;
+        Linux)
+            # Distinguish WSL from native Linux
+            if grep -qi microsoft /proc/version 2>/dev/null; then
+                script="$repo_root/scripts/platform/setup-wsl.sh"
+            else
+                script="$repo_root/scripts/platform/setup-linux.sh"
+            fi
+            ;;
+        *)
+            _doctor_row WARN "Platform" "$os not directly supported" \
+                "Doctor will only run zer0-mistakes-specific checks"
+            return 0
+            ;;
+    esac
+
+    if [[ ! -f "$script" ]]; then
+        _doctor_row WARN "Platform script" "Not found at ${script#$repo_root/}" \
+            "Falling back to inline checks"
+        _doctor_inline_platform_checks
+        return 0
+    fi
+
+    log_info "Running platform checks: $(basename "$script")"
+    # Source so we can call individual check functions; suppress its main
+    # entrypoint by setting a guard env.
+    # shellcheck source=/dev/null
+    if ! source "$script" 2>/dev/null; then
+        _doctor_row WARN "Platform script" "Failed to source" \
+            "Falling back to inline checks"
+        _doctor_inline_platform_checks
+        return 0
+    fi
+
+    # Each setup script exposes check_* functions. Probe the common set.
+    local suffix=""
+    case "$os" in
+        Darwin) suffix="macos" ;;
+        Linux)  suffix="linux"; grep -qi microsoft /proc/version 2>/dev/null && suffix="wsl" ;;
+    esac
+
+    if declare -F "check_git_${suffix}" >/dev/null 2>&1; then
+        if "check_git_${suffix}"; then
+            _doctor_row PASS "Git" "$(git --version 2>/dev/null | head -1)"
+        else
+            _doctor_row FAIL "Git" "Not installed" "Install via your package manager"
+        fi
+    fi
+    if declare -F "check_docker_${suffix}" >/dev/null 2>&1; then
+        if "check_docker_${suffix}"; then
+            _doctor_row PASS "Docker" "$(docker --version 2>/dev/null)"
+        elif command -v docker >/dev/null 2>&1; then
+            _doctor_row WARN "Docker" "Installed but daemon not reachable" \
+                "Start Docker Desktop / 'sudo systemctl start docker'"
+        else
+            _doctor_row WARN "Docker" "Not installed" \
+                "Optional — only needed for containerized dev"
+        fi
+    fi
+    if declare -F "check_ruby_${suffix}" >/dev/null 2>&1; then
+        if "check_ruby_${suffix}"; then
+            _doctor_row PASS "Ruby" "$(ruby --version 2>/dev/null)"
+        elif command -v ruby >/dev/null 2>&1; then
+            _doctor_row WARN "Ruby" "$(ruby --version 2>/dev/null) (3.0+ recommended)" \
+                "Upgrade via Homebrew/rbenv for best compatibility"
+        else
+            _doctor_row WARN "Ruby" "Not installed" \
+                "Optional — only needed for native (non-Docker) dev"
+        fi
+    fi
+}
+
+# Fallback when platform script is missing.
+_doctor_inline_platform_checks() {
+    if command -v git >/dev/null 2>&1; then
+        _doctor_row PASS "Git" "$(git --version 2>/dev/null | head -1)"
+    else
+        _doctor_row FAIL "Git" "Not installed" "Required for cloning + version control"
+    fi
+    if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+        _doctor_row PASS "Docker" "$(docker --version 2>/dev/null)"
+    else
+        _doctor_row WARN "Docker" "Not running or not installed" \
+            "Optional — needed for containerized dev"
+    fi
+    if command -v ruby >/dev/null 2>&1; then
+        _doctor_row PASS "Ruby" "$(ruby --version 2>/dev/null)"
+    else
+        _doctor_row WARN "Ruby" "Not installed" "Optional — needed for native dev"
+    fi
+}
+
+# ── Tooling checks ─────────────────────────────────────────────────────────
+_doctor_tooling() {
+    # gh CLI (used by deploy + agent flows that touch repos)
+    if command -v gh >/dev/null 2>&1; then
+        _doctor_row PASS "GitHub CLI" "$(gh --version 2>/dev/null | head -1)"
+    else
+        _doctor_row WARN "GitHub CLI" "Not installed" \
+            "Optional — install from https://cli.github.com for repo automation"
+    fi
+
+    # Docker Compose v2
+    if docker compose version >/dev/null 2>&1; then
+        _doctor_row PASS "Docker Compose" "$(docker compose version --short 2>/dev/null)"
+    elif command -v docker-compose >/dev/null 2>&1; then
+        _doctor_row WARN "Docker Compose" "v1 detected ($(docker-compose --version 2>/dev/null))" \
+            "Upgrade to v2: docker compose plugin"
+    else
+        _doctor_row WARN "Docker Compose" "Not available" \
+            "Optional — needed for 'docker compose up'"
+    fi
+
+    # Bundler
+    if command -v bundle >/dev/null 2>&1; then
+        # bundle --version may fail when run inside a dir with a Gemfile.lock
+        # pinning a different bundler. Probe in a neutral cwd to avoid noise.
+        local bv
+        bv="$(cd / && bundle --version 2>/dev/null | head -1)"
+        if [[ -n "$bv" ]]; then
+            _doctor_row PASS "Bundler" "$bv"
+        else
+            _doctor_row WARN "Bundler" "Installed but version probe failed" \
+                "Likely Gemfile.lock pins an unavailable bundler — run 'bundle update --bundler'"
+        fi
+    else
+        _doctor_row WARN "Bundler" "Not installed" \
+            "Install: gem install bundler (only needed for native dev)"
+    fi
+}
+
+# ── Site checks (run inside target_dir) ────────────────────────────────────
+_doctor_site() {
+    local target_dir="$1"
+
+    if [[ ! -d "$target_dir" ]]; then
+        _doctor_row FAIL "Target dir" "Does not exist: $target_dir" "Run 'install init' first"
+        return
+    fi
+
+    if [[ -f "$target_dir/_config.yml" ]]; then
+        _doctor_row PASS "_config.yml" "Present"
+    else
+        _doctor_row WARN "_config.yml" "Missing in $target_dir" \
+            "Run 'install init' to scaffold a site"
+    fi
+
+    if [[ -f "$target_dir/Gemfile" ]]; then
+        _doctor_row PASS "Gemfile" "Present"
+    else
+        _doctor_row WARN "Gemfile" "Missing" "Run 'install init' or 'install deploy'"
+    fi
+
+    if [[ -f "$target_dir/AGENTS.md" ]]; then
+        _doctor_row PASS "AI agent files" "AGENTS.md present"
+    else
+        _doctor_row WARN "AI agent files" "AGENTS.md not installed" \
+            "Run 'install agents' to add AI guidance"
+    fi
+
+    # Basic _config.yml sanity
+    if [[ -f "$target_dir/_config.yml" ]]; then
+        if grep -qE "^(remote_theme|theme):" "$target_dir/_config.yml" 2>/dev/null; then
+            _doctor_row PASS "Theme config" "remote_theme/theme set in _config.yml"
+        else
+            _doctor_row WARN "Theme config" "Neither 'theme' nor 'remote_theme' found" \
+                "Set 'remote_theme: bamr87/zer0-mistakes' or 'theme: jekyll-theme-zer0'"
+        fi
+    fi
+}
+
+# ── AI connectivity (opt-in) ───────────────────────────────────────────────
+_doctor_ai_connectivity() {
+    if [[ "${ZER0_NO_AI:-0}" = "1" ]]; then
+        _doctor_row WARN "OpenAI connectivity" "Skipped (ZER0_NO_AI=1)" \
+            "Unset ZER0_NO_AI to enable AI checks"
+        return
+    fi
+    if [[ -z "${OPENAI_API_KEY:-}" ]]; then
+        _doctor_row WARN "OpenAI API key" "OPENAI_API_KEY not set" \
+            "Export OPENAI_API_KEY to enable AI features"
+        return
+    fi
+    # Lightweight ping: check we can reach the API and the key authenticates.
+    local http_code
+    http_code="$(curl -sS -o /dev/null -w '%{http_code}' \
+        --max-time 10 \
+        -H "Authorization: Bearer ${OPENAI_API_KEY}" \
+        https://api.openai.com/v1/models 2>/dev/null || echo "000")"
+    case "$http_code" in
+        200)  _doctor_row PASS "OpenAI connectivity" "Authenticated (HTTP 200)" ;;
+        401)  _doctor_row FAIL "OpenAI connectivity" "Authentication failed (HTTP 401)" \
+                "Verify OPENAI_API_KEY is valid" ;;
+        000)  _doctor_row WARN "OpenAI connectivity" "No network response" \
+                "Check internet connection / firewall" ;;
+        *)    _doctor_row WARN "OpenAI connectivity" "Unexpected response (HTTP $http_code)" \
+                "Inspect with: curl -v https://api.openai.com/v1/models" ;;
+    esac
+}
+
+# ── Public entrypoint ──────────────────────────────────────────────────────
+doctor_run() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local check_ai=0 quiet=0 emit_json=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ai)   check_ai=1 ;;
+            --quiet) quiet=1 ;;
+            --json) emit_json=1 ;;
+            *) log_warning "doctor_run: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    DOCTOR_PASS=0; DOCTOR_WARN=0; DOCTOR_FAIL=0; DOCTOR_REPORT=""
+
+    [[ "$quiet" = "1" ]] || log_info "🩺 Running zer0-mistakes doctor..."
+    [[ "$quiet" = "1" ]] || echo
+
+    [[ "$quiet" = "1" ]] || log_info "── Platform ─────────────────────────────"
+    _doctor_platform "$repo_root"
+    [[ "$quiet" = "1" ]] || echo
+
+    [[ "$quiet" = "1" ]] || log_info "── Tooling ──────────────────────────────"
+    _doctor_tooling
+    [[ "$quiet" = "1" ]] || echo
+
+    [[ "$quiet" = "1" ]] || log_info "── Site ($target_dir) ───"
+    _doctor_site "$target_dir"
+    [[ "$quiet" = "1" ]] || echo
+
+    if [[ "$check_ai" = "1" ]]; then
+        [[ "$quiet" = "1" ]] || log_info "── AI ────────────────────────────────────"
+        _doctor_ai_connectivity
+        [[ "$quiet" = "1" ]] || echo
+    fi
+
+    if [[ "$emit_json" = "1" ]]; then
+        # Emit a tiny JSON summary — no jq, just printf.
+        printf '{"pass":%d,"warn":%d,"fail":%d}\n' \
+            "$DOCTOR_PASS" "$DOCTOR_WARN" "$DOCTOR_FAIL"
+    else
+        log_info "── Summary ──────────────────────────────"
+        log_info "  ✅ PASS: $DOCTOR_PASS"
+        log_info "  ⚠️  WARN: $DOCTOR_WARN"
+        log_info "  ❌ FAIL: $DOCTOR_FAIL"
+    fi
+
+    [[ "$DOCTOR_FAIL" = "0" ]] && return 0
+    return 1
+}