jekyll-theme-zer0 0.22.20 → 0.22.22

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

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# scripts/lib/install/ai/diagnose.sh
+#
+# `install diagnose [--ai]` — Jekyll build / runtime error analysis.
+#
+# Two modes:
+#
+# 1. Rule-based (default, no network). Pattern-matches a curated list of
+#    known errors against a build log and prints structured fixes.
+#
+# 2. AI-assisted (`--ai`). Sends a sanitized error log + the most relevant
+#    config files to OpenAI, returns a unified diff for user review.
+#
+# Public API:
+#     diagnose_run <target_dir> <repo_root> [--log <file>] [--ai] [--auto-accept]
+#
+# If --log is not provided, runs `jekyll build` once and captures output.
+
+# shellcheck disable=SC2034
+AI_DIAGNOSE_LIB_VERSION="1.0.0"
+
+# ----- Rule-based pattern table --------------------------------------------
+# Each rule: [pattern_regex] [short_label] [explanation+fix]
+# Order matters — first match wins. Keep patterns specific.
+_diagnose_rules() {
+    cat <<'EOF'
+theme could not be found|MISSING_THEME|The Jekyll theme gem is not installed. Run `bundle install` (or `bundle update jekyll-theme-zer0`) and confirm the gem name in _config.yml matches your Gemfile entry.
+Address already in use|PORT_IN_USE|Port 4000 is already bound. Either stop the existing process (`lsof -ti :4000 | xargs kill`) or run on a different port (`bundle exec jekyll serve --port 4001`).
+You have requested:.*Could not find compatible versions|GEM_VERSION_CONFLICT|A gem version constraint cannot be satisfied. Run `bundle update` to refresh the lockfile, or pin to compatible versions in your Gemfile.
+Liquid Exception:.*Could not locate the included file|MISSING_INCLUDE|A `{% include %}` tag references a file that doesn't exist. Verify the path inside `_includes/` and check for typos.
+Liquid Exception|LIQUID_ERROR|A Liquid template raised an error. Check the file path printed above the exception and look for unmatched tags ({% if %} without {% endif %}, etc.).
+SassC::SyntaxError|SASS_SYNTAX|Sass compilation failed. Review the file/line printed in the error and check for missing semicolons, unclosed braces, or invalid @import paths.
+No such file or directory @ rb_sysopen|MISSING_FILE|Jekyll tried to open a file that doesn't exist. Common causes: deleted but still referenced in _config.yml or front matter; typo in include path.
+incompatible character encodings|ENCODING_ISSUE|A file has mixed encodings. Re-save the offending file as UTF-8 without BOM.
+EOF
+}
+
+_diagnose_rule_based() {
+    local log_file="$1"
+    local matched=0 line key label fix
+    while IFS='|' read -r pattern label fix; do
+        [[ -z "$pattern" ]] && continue
+        if grep -qE "$pattern" "$log_file" 2>/dev/null; then
+            log_info "Matched rule: $label"
+            echo "  ↳ $fix"
+            echo
+            matched=$((matched+1))
+        fi
+    done < <(_diagnose_rules)
+
+    if [[ "$matched" = "0" ]]; then
+        log_warning "No known patterns matched. Re-run with --ai for AI analysis (requires OPENAI_API_KEY)."
+        return 1
+    fi
+    log_success "Matched $matched rule(s)."
+    return 0
+}
+
+_diagnose_capture_build_log() {
+    local target_dir="$1" log_file="$2"
+    log_info "Running 'jekyll build' to capture errors ..."
+    (
+        cd "$target_dir" || exit 1
+        if [[ -f Gemfile ]] && command -v bundle >/dev/null 2>&1; then
+            bundle exec jekyll build 2>&1 | tee "$log_file"
+        elif command -v jekyll >/dev/null 2>&1; then
+            jekyll build 2>&1 | tee "$log_file"
+        else
+            echo "neither bundler nor jekyll is installed" > "$log_file"
+            return 1
+        fi
+    ) || true
+}
+
+_diagnose_ai() {
+    local log_file="$1" target_dir="$2" repo_root="$3" auto_accept="$4"
+
+    if ! ai_enabled; then
+        log_warning "AI is disabled (ZER0_NO_AI=1) — using rule-based mode only."
+        return 1
+    fi
+    if ! ai_require_key; then
+        return 1
+    fi
+
+    local sys_prompt_file="$repo_root/templates/ai/prompts/diagnose-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")"
+
+    # Build sanitized context (last 80 lines of log + _config.yml + Gemfile)
+    local sanitized_log sanitized_cfg sanitized_gem
+    sanitized_log="$(tail -n 80 "$log_file" | ai_sanitize_text)"
+    if [[ -f "$target_dir/_config.yml" ]]; then
+        sanitized_cfg="$(ai_sanitize_text < "$target_dir/_config.yml")"
+    else
+        sanitized_cfg="(missing)"
+    fi
+    if [[ -f "$target_dir/Gemfile" ]]; then
+        sanitized_gem="$(ai_sanitize_text < "$target_dir/Gemfile")"
+    else
+        sanitized_gem="(missing)"
+    fi
+
+    local user_prompt="===== BUILD LOG (last 80 lines) =====
+${sanitized_log}
+
+===== _config.yml =====
+${sanitized_cfg}
+
+===== Gemfile =====
+${sanitized_gem}
+
+Diagnose the failure and propose a minimal fix. If a file change is needed, output a unified diff. Be concise."
+
+    local model
+    model="$(ai_default_model diagnose)"
+    local in_chars=$(( ${#system_prompt} + ${#user_prompt} ))
+    log_info "About to call OpenAI:"
+    ai_estimate_cost "$model" "$in_chars" 600
+
+    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
+
+    log_info "Calling $model ..."
+    local resp
+    if ! resp="$(ai_call_chat "$model" "$system_prompt" "$user_prompt" 800 0.2)"; then
+        log_error "OpenAI call failed."
+        return 1
+    fi
+
+    echo
+    log_info "AI diagnosis:"
+    echo "─────────────────────────────────────────────────────────────"
+    printf '%s\n' "$resp"
+    echo "─────────────────────────────────────────────────────────────"
+    log_info "If the response includes a unified diff, save it to a file and apply with: patch -p0 < fix.diff"
+    return 0
+}
+
+diagnose_run() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local log_file="" use_ai=0 auto_accept=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --log) log_file="${2:-}"; shift ;;
+            --ai)  use_ai=1 ;;
+            --auto-accept) auto_accept=1 ;;
+            *) log_warning "diagnose_run: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    if [[ ! -d "$target_dir" ]]; then
+        log_error "Target directory does not exist: $target_dir"
+        return 1
+    fi
+
+    local cleanup_log=0
+    if [[ -z "$log_file" ]]; then
+        log_file="$(mktemp)"
+        cleanup_log=1
+        _diagnose_capture_build_log "$target_dir" "$log_file"
+    fi
+
+    if [[ ! -f "$log_file" ]]; then
+        log_error "Log file not found: $log_file"
+        [[ "$cleanup_log" = "1" ]] && rm -f "$log_file"
+        return 1
+    fi
+
+    log_info "Diagnosing build log ($(wc -l < "$log_file" | tr -d ' ') lines) ..."
+    echo
+
+    # Always run rule-based first
+    local rule_result=0
+    _diagnose_rule_based "$log_file" || rule_result=1
+
+    # AI if requested
+    if [[ "$use_ai" = "1" ]]; then
+        echo
+        _diagnose_ai "$log_file" "$target_dir" "$repo_root" "$auto_accept" || true
+    fi
+
+    [[ "$cleanup_log" = "1" ]] && rm -f "$log_file"
+    return $rule_result
+}

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"
+}