setup.sh

#!/usr/bin/env bash
#
# Plan Forge — Project Setup Wizard (Bash)
#
# Usage:
#   ./setup.sh --preset dotnet --path ~/projects/MyApp --name MyApp
#   ./setup.sh                  # Interactive mode
#   ./setup.sh --force          # Overwrite existing files
#
# Presets: dotnet, typescript, python, java, go, swift, rust, php, azure-iac, custom

set -euo pipefail

TEMPLATE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# ─── Defaults ──────────────────────────────────────────────────────────
PRESET=""
PROJECT_PATH=""
PROJECT_NAME=""
FORCE=false
AUTO_DETECT=false
AGENTS="copilot"
GENERIC_DIR=".ai"
# Take every default without prompting and skip the "Proceed?" and OpenBrain prompts (#304).
# Also honored: $CI and $PFORGE_NONINTERACTIVE; the OpenBrain prompt also skips when stdin is not a TTY.
NON_INTERACTIVE=false

# ─── Color helpers ─────────────────────────────────────────────────────
cyan()   { printf '\033[0;36m%s\033[0m\n' "$*"; }
green()  { printf '\033[0;32m%s\033[0m\n' "$*"; }
yellow() { printf '\033[0;33m%s\033[0m\n' "$*"; }
red()    { printf '\033[0;31m%s\033[0m\n' "$*"; }

# ─── Parse arguments ──────────────────────────────────────────────────
while [[ $# -gt 0 ]]; do
    case "$1" in
        --preset|-p)  PRESET="$2"; shift 2 ;;
        --path)       PROJECT_PATH="$2"; shift 2 ;;
        --name|-n)    PROJECT_NAME="$2"; shift 2 ;;
        --agent)      AGENTS="$2"; shift 2 ;;
        --generic-dir) GENERIC_DIR="$2"; shift 2 ;;
        --force|-f)   FORCE=true; shift ;;
        --auto-detect|-a) AUTO_DETECT=true; shift ;;
        --non-interactive) NON_INTERACTIVE=true; shift ;;
        --help|-h)
            echo "Usage: ./setup.sh [--preset dotnet|typescript|python|java|go|swift|rust|php|azure-iac|custom] [--path DIR] [--name NAME] [--agent copilot|claude|cursor|codex|gemini|generic|all] [--generic-dir DIR] [--force] [--auto-detect] [--non-interactive]"
            exit 0 ;;
        *) red "Unknown option: $1"; exit 1 ;;
    esac
done

# ─── Helpers ───────────────────────────────────────────────────────────
# Non-interactive runs (--non-interactive, CI, PFORGE_NONINTERACTIVE) take every
# default without prompting (#304).
skip_prompts() {
    [[ "$NON_INTERACTIVE" == true ]] || [[ -n "${CI:-}" ]] || [[ -n "${PFORGE_NONINTERACTIVE:-}" ]]
}

prompt_value() {
    local message="$1"
    local default="${2:-}"
    local value=""
    if skip_prompts; then
        echo "$default"
        return 0
    fi
    if [[ -n "$default" ]]; then
        read -rp "$message [$default]: " value || true
        echo "${value:-$default}"
    else
        while true; do
            # End of input would otherwise loop forever.
            read -rp "$message: " value || break
            [[ -n "$value" ]] && break
        done
        echo "$value"
    fi
}

copy_with_create() {
    local src="$1"
    local dst="$2"
    local dst_dir
    dst_dir="$(dirname "$dst")"

    mkdir -p "$dst_dir"

    if [[ -f "$dst" ]] && [[ "$FORCE" != true ]]; then
        yellow "  SKIP  $dst (exists)"
        return 1
    fi

    cp "$src" "$dst"
    green "  COPY  $dst"
    return 0
}

# Lists, NUL-separated, the files of a runtime package (pforge-mcp, pforge-master, pforge-sdk) that setup
# copies. Directories named node_modules, .forge or coverage below the package stay behind, installed
# dependencies, run state and coverage output, and find does not walk them. The filter used to be
# `! -path '*/.forge/*'`, which matches the whole path: a source tree under a .forge folder installed
# nothing at all, and the install still reported success (#346, with #400 for setup.ps1).
list_runtime_package_files() {
    find "$1" \( -type d \( -name node_modules -o -name .forge -o -name coverage \) -prune \) -o -type f -print0 2>/dev/null
}

replace_placeholders() {
    local file="$1"
    local name="$2"
    local stack="$3"
    local today
    today="$(date +%Y-%m-%d)"

    [[ ! -f "$file" ]] && return

    if [[ "$(uname)" == "Darwin" ]]; then
        sed -i '' "s|<YOUR PROJECT NAME>|${name}|g" "$file"
        sed -i '' "s|<YOUR TECH STACK>|${stack}|g" "$file"
        sed -i '' "s|<YOUR BUILD COMMAND>|${BUILD_CMD}|g" "$file"
        sed -i '' "s|<YOUR TEST COMMAND>|${TEST_CMD}|g" "$file"
        sed -i '' "s|<YOUR LINT COMMAND>|${LINT_CMD}|g" "$file"
        sed -i '' "s|<YOUR DEV COMMAND>||g" "$file"
        sed -i '' "s|<DATE>|${today}|g" "$file"
    else
        sed -i "s|<YOUR PROJECT NAME>|${name}|g" "$file"
        sed -i "s|<YOUR TECH STACK>|${stack}|g" "$file"
        sed -i "s|<YOUR BUILD COMMAND>|${BUILD_CMD}|g" "$file"
        sed -i "s|<YOUR TEST COMMAND>|${TEST_CMD}|g" "$file"
        sed -i "s|<YOUR LINT COMMAND>|${LINT_CMD}|g" "$file"
        sed -i "s|<YOUR DEV COMMAND>||g" "$file"
        sed -i "s|<DATE>|${today}|g" "$file"
    fi
}

# ─── .gitignore Manager (Issue #211) ───────────────────────────────────
# Seed/refresh a marker-delimited managed block in the consumer's .gitignore
# so runtime artifacts under .forge/ never get committed. Idempotent — user
# content outside the markers is preserved. Twin of setup.ps1's
# Update-PlanForgeGitignore. Used by setup.sh + pforge.sh self-update.
pf_update_gitignore() {
    local repo_root="$1"
    local gitignore="$repo_root/.gitignore"
    local begin="# >>> plan-forge managed (do not edit between markers) >>>"
    local end="# <<< plan-forge managed <<<"
    local body
    body="${begin}
# Runtime / cache / telemetry produced by pforge — never commit.
# This block is refreshed by setup + 'pforge self-update'. Issue #211.
**/.forge/
.forge/secrets.json
pforge-mcp/node_modules/
pforge-mcp/cli-schema.json
pforge-mcp/.vitest-results.json
pforge-master/node_modules/
pforge-sdk/node_modules/
${end}"

    if [[ -f "$gitignore" ]]; then
        if grep -qF "$begin" "$gitignore"; then
            local tmp
            tmp="$(mktemp)"
            awk -v begin="$begin" -v end="$end" -v body="$body" '
              BEGIN { in_block = 0 }
              {
                if (index($0, begin) == 1 && !in_block) { in_block = 1; print body; next }
                if (index($0, end) == 1 && in_block) { in_block = 0; next }
                if (!in_block) print
              }
            ' "$gitignore" > "$tmp"
            if ! cmp -s "$gitignore" "$tmp"; then
                mv "$tmp" "$gitignore"
                green "  ✅ Refreshed plan-forge managed block in .gitignore"
            else
                rm -f "$tmp"
                echo "  ✓ .gitignore plan-forge block already current"
            fi
        else
            # Ensure trailing newline before appending
            if [[ -s "$gitignore" ]] && [[ -n "$(tail -c 1 "$gitignore")" ]]; then
                echo "" >> "$gitignore"
            fi
            echo "" >> "$gitignore"
            printf "%s\n" "$body" >> "$gitignore"
            green "  ✅ Appended plan-forge managed block to .gitignore"
        fi
    else
        printf "%s\n" "$body" > "$gitignore"
        green "  ✅ Created .gitignore with plan-forge managed block"
    fi

    if [[ -d "$repo_root/.git" ]]; then
        local tracked
        tracked="$(cd "$repo_root" && git ls-files .forge 2>/dev/null | head -1)"
        if [[ -n "$tracked" ]]; then
            echo ""
            yellow "⚠  Files under .forge/ are currently tracked by git but the managed"
            yellow "   .gitignore now excludes them. Clean up with:"
            cyan   "     git rm -r --cached .forge"
            cyan   "     git commit -m \"chore(pforge): untrack .forge/ runtime artifacts\""
            echo ""
        fi
    fi
}

# ─── Agent Adapter: Claude Code ────────────────────────────────────────
install_claude_agent() {
    local target="$1"
    echo "  Installing Claude Code files..."

    # Generate rich CLAUDE.md — copilot-instructions + all instruction files
    local copilot_instr="$target/.github/copilot-instructions.md"
    local claude_ctx="$target/CLAUDE.md"
    if [ -f "$copilot_instr" ] && [ ! -f "$claude_ctx" ]; then
        {
            echo "# Project Context for Claude"
            echo ""
            echo "> Auto-generated by Plan Forge. Includes project instructions + all guardrail files."
            echo "> Regenerate with: pforge smith or re-run setup with --agent claude"
            echo ""
            echo "## How to Use These Guardrails"
            echo ""
            echo "This file contains domain-specific guardrails organized by section. When editing code:"
            echo "- Editing database/SQL/repository code → follow the **database** section"
            echo "- Editing auth/JWT/OIDC code → follow the **auth** section"
            echo "- Editing API controllers/routes → follow the **api-patterns** section"
            echo "- Editing tests → follow the **testing** section"
            echo "- Editing Docker/deploy files → follow the **deploy** section"
            echo "- Always follow **architecture-principles** and **security** sections"
            echo ""
            echo "**After every file edit**: Scan for TODO, FIXME, HACK, stub, placeholder markers. Warn immediately if found."
            echo ""
            echo "**Before editing any file**: If a hardened plan exists in \`docs/plans/\`, check its Forbidden Actions section. Do not edit files listed there."
            echo ""
            echo "**Pipeline flow**: After completing a step, tell the user what to invoke next:"
            echo "- After Step 0 (Specify) → \`/planforge-step1-preflight-check\`"
            echo "- After Step 2 (Harden) → \`/planforge-step3-execute-slice\`"
            echo "- After Step 4 (Sweep) → Start a NEW session for Step 5 (Review)"
            echo "- After Step 5 (Review) → \`/planforge-step6-ship\`"
            echo ""
            echo "## Project Instructions"
            echo ""
            cat "$copilot_instr"
            echo ""

            # Embed all instruction files by domain
            local instr_dir="$target/.github/instructions"
            if [ -d "$instr_dir" ]; then
                echo "---"
                echo ""
                echo "## Guardrail Files"
                echo ""
                echo "The following guardrails are auto-loaded in VS Code Copilot by file type. In Claude, they are embedded here for reference."
                echo ""
                for instr_file in "$instr_dir"/*.instructions.md; do
                    [ -f "$instr_file" ] || continue
                    local domain
                    domain="$(basename "$instr_file" .instructions.md)"
                    echo "### $domain"
                    echo ""
                    # Strip YAML frontmatter
                    sed -n '/^---$/,/^---$/!p' "$instr_file" | tail -n +1
                    echo ""
                done
            fi
        } > "$claude_ctx"
        green "  CREATE CLAUDE.md (project context + guardrails)"
    fi

    # Convert ALL prompts → Claude skills
    local prompts_dir="$target/.github/prompts"
    local skills_dir="$target/.claude/skills"
    if [ -d "$prompts_dir" ]; then
        for prompt_file in "$prompts_dir"/*.prompt.md; do
            [ -f "$prompt_file" ] || continue
            local base
            base="$(basename "$prompt_file" .prompt.md)"
            local skill_dir="$skills_dir/planforge-$base"
            local skill_file="$skill_dir/SKILL.md"
            mkdir -p "$skill_dir"

            local desc="Plan Forge prompt"
            local got_desc
            got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$prompt_file" 2>/dev/null | head -1)" || true
            [ -n "$got_desc" ] && desc="$got_desc"

            {
                echo "---"
                echo "name: planforge-$base"
                echo "description: $desc"
                echo "metadata:"
                echo "  author: plan-forge"
                echo "  source: .github/prompts/$(basename "$prompt_file")"
                echo "user-invocable: true"
                echo "argument-hint: \"Provide context or parameters for this prompt\""
                echo "---"
                echo ""
                cat "$prompt_file"
            } > "$skill_file"
            green "  CREATE .claude/skills/planforge-$base/SKILL.md"
        done
    fi

    # Convert reviewer agents → Claude skills
    local agents_dir="$target/.github/agents"
    if [ -d "$agents_dir" ]; then
        for agent_file in "$agents_dir"/*.agent.md; do
            [ -f "$agent_file" ] || continue
            local base
            base="$(basename "$agent_file" .agent.md)"
            local skill_dir="$skills_dir/planforge-$base"
            local skill_file="$skill_dir/SKILL.md"
            mkdir -p "$skill_dir"

            local desc="Plan Forge reviewer agent"
            local got_desc
            got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$agent_file" 2>/dev/null | head -1)" || true
            [ -n "$got_desc" ] && desc="$got_desc"

            {
                echo "---"
                echo "name: planforge-$base"
                echo "description: $desc"
                echo "metadata:"
                echo "  author: plan-forge"
                echo "  source: .github/agents/$(basename "$agent_file")"
                echo "user-invocable: true"
                echo "argument-hint: \"Specify files or areas to review\""
                echo "---"
                echo ""
                cat "$agent_file"
            } > "$skill_file"
            green "  CREATE .claude/skills/planforge-$base/SKILL.md"
        done
    fi
}

# ─── Agent Adapter: Cursor ─────────────────────────────────────────────
install_cursor_agent() {
    local target="$1"
    echo "  Installing Cursor files..."

    # Generate rich .cursor/rules — copilot-instructions + all guardrails
    local copilot_instr="$target/.github/copilot-instructions.md"
    local cursor_dir="$target/.cursor"
    local cursor_rules="$cursor_dir/rules"
    if [ -f "$copilot_instr" ] && [ ! -f "$cursor_rules" ]; then
        mkdir -p "$cursor_dir"
        {
            cat "$copilot_instr"
            echo ""
            echo "---"
            echo ""
            echo "## Plan Forge Agent Guidelines"
            echo ""
            echo "When editing code, apply the guardrail section that matches the file type:"
            echo "- Database/SQL/ORM → **database** section | Auth/JWT → **auth** section"
            echo "- API routes → **api-patterns** section | Tests → **testing** section"
            echo "- Always follow **architecture-principles** and **security**"
            echo ""
            echo "After every file edit: scan for TODO/FIXME/HACK/stub markers. Warn immediately."
            echo "Before editing: check the active plan's Forbidden Actions — do not touch listed files."
            echo ""

            local instr_dir="$target/.github/instructions"
            if [ -d "$instr_dir" ]; then
                echo "---"
                echo ""
                echo "## Guardrail Files (from Plan Forge)"
                echo ""
                for instr_file in "$instr_dir"/*.instructions.md; do
                    [ -f "$instr_file" ] || continue
                    local domain
                    domain="$(basename "$instr_file" .instructions.md)"
                    echo "### $domain"
                    echo ""
                    sed -n '/^---$/,/^---$/!p' "$instr_file" | tail -n +1
                    echo ""
                done
            fi
        } > "$cursor_rules"
        green "  CREATE .cursor/rules (project context + guardrails)"
    fi

    # Convert ALL prompts → Cursor commands
    local prompts_dir="$target/.github/prompts"
    local commands_dir="$cursor_dir/commands"
    if [ -d "$prompts_dir" ]; then
        mkdir -p "$commands_dir"
        for prompt_file in "$prompts_dir"/*.prompt.md; do
            [ -f "$prompt_file" ] || continue
            local base
            base="$(basename "$prompt_file" .prompt.md)"
            local cmd_file="$commands_dir/planforge.$base.md"
            if [ ! -f "$cmd_file" ]; then
                local desc="Plan Forge prompt"
                local got_desc
                got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$prompt_file" 2>/dev/null | head -1)" || true
                [ -n "$got_desc" ] && desc="$got_desc"
                {
                    echo "---"
                    echo "description: $desc"
                    echo "---"
                    echo ""
                    cat "$prompt_file"
                } > "$cmd_file"
                green "  CREATE .cursor/commands/planforge.$base.md"
            fi
        done
    fi

    # Convert reviewer agents → Cursor commands
    local agents_dir="$target/.github/agents"
    if [ -d "$agents_dir" ]; then
        mkdir -p "$commands_dir"
        for agent_file in "$agents_dir"/*.agent.md; do
            [ -f "$agent_file" ] || continue
            local base
            base="$(basename "$agent_file" .agent.md)"
            local cmd_file="$commands_dir/planforge.$base.md"
            if [ ! -f "$cmd_file" ]; then
                local desc="Plan Forge reviewer"
                local got_desc
                got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$agent_file" 2>/dev/null | head -1)" || true
                [ -n "$got_desc" ] && desc="$got_desc"
                {
                    echo "---"
                    echo "description: $desc"
                    echo "---"
                    echo ""
                    cat "$agent_file"
                } > "$cmd_file"
                green "  CREATE .cursor/commands/planforge.$base.md"
            fi
        done
    fi
}

# ─── Agent Adapter: Windsurf ───────────────────────────────────────────
install_windsurf_agent() {
    local target="$1"
    echo "  Installing Windsurf files..."

    # Generate .windsurf/rules/planforge.md — copilot-instructions + all guardrails
    local copilot_instr="$target/.github/copilot-instructions.md"
    local windsurf_dir="$target/.windsurf"
    local rules_dir="$windsurf_dir/rules"
    local rules_file="$rules_dir/planforge.md"
    if [ -f "$copilot_instr" ] && [ ! -f "$rules_file" ]; then
        mkdir -p "$rules_dir"
        {
            cat "$copilot_instr"
            echo ""
            echo "---"
            echo ""
            echo "## Plan Forge Agent Guidelines"
            echo ""
            echo "When editing code, apply the guardrail section that matches the file type:"
            echo "- Database/SQL/ORM → **database** section | Auth/JWT → **auth** section"
            echo "- API routes → **api-patterns** section | Tests → **testing** section"
            echo "- Always follow **architecture-principles** and **security**"
            echo ""
            echo "After every file edit: scan for TODO/FIXME/HACK/stub markers. Warn immediately."
            echo "Before editing: check the active plan's Forbidden Actions — do not touch listed files."
            echo ""

            local instr_dir="$target/.github/instructions"
            if [ -d "$instr_dir" ]; then
                echo "---"
                echo ""
                echo "## Guardrail Files (from Plan Forge)"
                echo ""
                for instr_file in "$instr_dir"/*.instructions.md; do
                    [ -f "$instr_file" ] || continue
                    local domain
                    domain="$(basename "$instr_file" .instructions.md)"
                    echo "### $domain"
                    echo ""
                    sed -n '/^---$/,/^---$/!p' "$instr_file" | tail -n +1
                    echo ""
                done
            fi
        } > "$rules_file"
        green "  CREATE .windsurf/rules/planforge.md (project context + guardrails)"
    fi

    # Convert ALL prompts → Windsurf workflows
    local prompts_dir="$target/.github/prompts"
    local workflows_dir="$windsurf_dir/workflows"
    if [ -d "$prompts_dir" ]; then
        mkdir -p "$workflows_dir"
        for prompt_file in "$prompts_dir"/*.prompt.md; do
            [ -f "$prompt_file" ] || continue
            local base
            base="$(basename "$prompt_file" .prompt.md)"
            local wf_file="$workflows_dir/planforge.$base.md"
            if [ ! -f "$wf_file" ]; then
                local desc="Plan Forge prompt"
                local got_desc
                got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$prompt_file" 2>/dev/null | head -1)" || true
                [ -n "$got_desc" ] && desc="$got_desc"
                {
                    echo "---"
                    echo "description: $desc"
                    echo "---"
                    echo ""
                    cat "$prompt_file"
                } > "$wf_file"
                green "  CREATE .windsurf/workflows/planforge.$base.md"
            fi
        done
    fi

    # Convert reviewer agents → Windsurf workflows
    local agents_dir="$target/.github/agents"
    if [ -d "$agents_dir" ]; then
        mkdir -p "$workflows_dir"
        for agent_file in "$agents_dir"/*.agent.md; do
            [ -f "$agent_file" ] || continue
            local base
            base="$(basename "$agent_file" .agent.md)"
            local wf_file="$workflows_dir/planforge.$base.md"
            if [ ! -f "$wf_file" ]; then
                local desc="Plan Forge reviewer"
                local got_desc
                got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$agent_file" 2>/dev/null | head -1)" || true
                [ -n "$got_desc" ] && desc="$got_desc"
                {
                    echo "---"
                    echo "description: $desc"
                    echo "---"
                    echo ""
                    cat "$agent_file"
                } > "$wf_file"
                green "  CREATE .windsurf/workflows/planforge.$base.md"
            fi
        done
    fi
}

# ─── Agent Adapter: Codex CLI ──────────────────────────────────────────
install_codex_agent() {
    local target="$1"
    echo "  Installing Codex CLI files..."

    # Convert ALL prompts → Codex skills
    local prompts_dir="$target/.github/prompts"
    local skills_dir="$target/.agents/skills"
    if [ -d "$prompts_dir" ]; then
        for prompt_file in "$prompts_dir"/*.prompt.md; do
            [ -f "$prompt_file" ] || continue
            local base
            base="$(basename "$prompt_file" .prompt.md)"
            local skill_dir="$skills_dir/planforge-$base"
            local skill_file="$skill_dir/SKILL.md"
            mkdir -p "$skill_dir"

            local desc="Plan Forge prompt"
            local got_desc
            got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$prompt_file" 2>/dev/null | head -1)" || true
            [ -n "$got_desc" ] && desc="$got_desc"

            {
                echo "---"
                echo "name: planforge-$base"
                echo "description: $desc"
                echo "metadata:"
                echo "  author: plan-forge"
                echo "  source: .github/prompts/$(basename "$prompt_file")"
                echo "---"
                echo ""
                cat "$prompt_file"
            } > "$skill_file"
            green "  CREATE .agents/skills/planforge-$base/SKILL.md"
        done
    fi

    # Convert reviewer agents → Codex skills
    local agents_dir="$target/.github/agents"
    if [ -d "$agents_dir" ]; then
        for agent_file in "$agents_dir"/*.agent.md; do
            [ -f "$agent_file" ] || continue
            local base
            base="$(basename "$agent_file" .agent.md)"
            local skill_dir="$skills_dir/planforge-$base"
            local skill_file="$skill_dir/SKILL.md"
            mkdir -p "$skill_dir"

            local desc="Plan Forge reviewer"
            local got_desc
            got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$agent_file" 2>/dev/null | head -1)" || true
            [ -n "$got_desc" ] && desc="$got_desc"

            {
                echo "---"
                echo "name: planforge-$base"
                echo "description: $desc"
                echo "metadata:"
                echo "  author: plan-forge"
                echo "  source: .github/agents/$(basename "$agent_file")"
                echo "---"
                echo ""
                cat "$agent_file"
            } > "$skill_file"
            green "  CREATE .agents/skills/planforge-$base/SKILL.md"
        done
    fi
}

# ─── Agent Adapter: Gemini CLI ─────────────────────────────────────────
install_gemini_agent() {
    local target="$1"
    echo "  Installing Gemini CLI files..."

    # Generate GEMINI.md — uses @import syntax for guardrail files
    local copilot_instr="$target/.github/copilot-instructions.md"
    local gemini_ctx="$target/GEMINI.md"
    if [ -f "$copilot_instr" ] && [ ! -f "$gemini_ctx" ]; then
        {
            echo "# Project Context for Gemini CLI"
            echo ""
            echo "> Auto-generated by Plan Forge. Includes project instructions + guardrail imports."
            echo "> Regenerate with: re-run setup with --agent gemini"
            echo ""
            echo "## How to Use These Guardrails"
            echo ""
            echo "This file contains domain-specific guardrails organized by section. When editing code:"
            echo "- Editing database/SQL/repository code → follow the **database** section"
            echo "- Editing auth/JWT/OIDC code → follow the **auth** section"
            echo "- Editing API controllers/routes → follow the **api-patterns** section"
            echo "- Editing tests → follow the **testing** section"
            echo "- Editing Docker/deploy files → follow the **deploy** section"
            echo "- Always follow **architecture-principles** and **security** sections"
            echo ""
            echo "**After every file edit**: Scan for TODO, FIXME, HACK, stub, placeholder markers. Warn immediately if found."
            echo ""
            echo "**Before editing any file**: If a hardened plan exists in \`docs/plans/\`, check its Forbidden Actions section. Do not edit files listed there."
            echo ""
            echo "**Pipeline flow**: After completing a step, tell the user what to invoke next:"
            echo "- After Step 0 (Specify) → \`/planforge:step1-preflight-check\`"
            echo "- After Step 2 (Harden) → \`/planforge:step3-execute-slice\`"
            echo "- After Step 4 (Sweep) → Start a NEW session for Step 5 (Review)"
            echo "- After Step 5 (Review) → \`/planforge:step6-ship\`"
            echo ""
            echo "## Project Instructions"
            echo ""
            cat "$copilot_instr"
            echo ""

            # Import guardrail files using Gemini's @import syntax
            local instr_dir="$target/.github/instructions"
            if [ -d "$instr_dir" ]; then
                echo "---"
                echo ""
                echo "## Guardrail Files"
                echo ""
                echo "The following guardrails are imported from Plan Forge instruction files. Gemini CLI auto-loads these via \`@\` imports."
                echo ""

                for instr_file in "$instr_dir"/*.instructions.md; do
                    [ -f "$instr_file" ] || continue
                    local domain
                    domain="$(basename "$instr_file" .instructions.md)"
                    local rel_path=".github/instructions/$(basename "$instr_file")"
                    echo "### $domain"
                    echo ""
                    echo "@$rel_path"
                    echo ""
                done
            fi
        } > "$gemini_ctx"
        green "  CREATE GEMINI.md (project context + guardrail imports)"
    fi

    # Convert ALL prompts → Gemini CLI commands (.toml)
    local prompts_dir="$target/.github/prompts"
    local commands_dir="$target/.gemini/commands/planforge"
    if [ -d "$prompts_dir" ]; then
        mkdir -p "$commands_dir"
        for prompt_file in "$prompts_dir"/*.prompt.md; do
            [ -f "$prompt_file" ] || continue
            local base
            base="$(basename "$prompt_file" .prompt.md)"
            local toml_file="$commands_dir/$base.toml"

            if [ ! -f "$toml_file" ]; then
                local desc="Plan Forge prompt"
                local got_desc
                got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$prompt_file" 2>/dev/null | head -1)" || true
                [ -n "$got_desc" ] && desc="$got_desc"

                # Strip YAML frontmatter
                local prompt_body
                prompt_body="$(sed '/^---$/,/^---$/d' "$prompt_file")"

                # Escape any triple quotes for TOML
                prompt_body="$(echo "$prompt_body" | sed 's/"""/\\"\\"\\"/g')"

                {
                    echo "# Invoked via: /planforge:$base"
                    echo "description = \"${desc//\"/\\\"}\""
                    echo ""
                    echo "prompt = \"\"\""
                    echo "$prompt_body"
                    echo "\"\"\""
                } > "$toml_file"
                green "  CREATE .gemini/commands/planforge/$base.toml"
            fi
        done
    fi

    # Convert reviewer agents → Gemini CLI commands (.toml)
    local agents_dir="$target/.github/agents"
    if [ -d "$agents_dir" ]; then
        mkdir -p "$commands_dir"
        for agent_file in "$agents_dir"/*.agent.md; do
            [ -f "$agent_file" ] || continue
            local base
            base="$(basename "$agent_file" .agent.md)"
            local toml_file="$commands_dir/$base.toml"

            if [ ! -f "$toml_file" ]; then
                local desc="Plan Forge reviewer"
                local got_desc
                got_desc="$(grep -oP 'description:\s*"?\K[^"]+' "$agent_file" 2>/dev/null | head -1)" || true
                [ -n "$got_desc" ] && desc="$got_desc"

                local prompt_body
                prompt_body="$(sed '/^---$/,/^---$/d' "$agent_file")"
                prompt_body="$(echo "$prompt_body" | sed 's/"""/\\"\\"\\"/g')"

                {
                    echo "# Invoked via: /planforge:$base"
                    echo "description = \"${desc//\"/\\\"}\""
                    echo ""
                    echo "prompt = \"\"\""
                    echo "$prompt_body"
                    echo "\"\"\""
                } > "$toml_file"
                green "  CREATE .gemini/commands/planforge/$base.toml"
            fi
        done
    fi

    # Generate .gemini/settings.json with MCP server config
    local settings_file="$target/.gemini/settings.json"
    if [ ! -f "$settings_file" ]; then
        mkdir -p "$target/.gemini"
        cat > "$settings_file" << 'SETTINGS_EOF'
{
  "theme": "Default",
  "mcpServers": {
    "plan-forge": {
      "command": "node",
      "args": ["pforge-mcp/server.mjs"]
    }
  }
}
SETTINGS_EOF
        green "  CREATE .gemini/settings.json (MCP server config)"
    fi
}

# ─── Agent Adapter: Generic (any AI coding assistant) ──────────────────
install_generic_agent() {
    local target="$1"
    local generic_dir="${2:-.ai}"
    local output_dir="$target/$generic_dir"
    echo "  Installing Generic AI adapter files (dir: $generic_dir)..."

    mkdir -p "$output_dir"

    # Generate AI_INSTRUCTIONS.md — full context + guardrails embedded inline
    local copilot_instr="$target/.github/copilot-instructions.md"
    local ai_ctx="$output_dir/AI_INSTRUCTIONS.md"
    if [ -f "$copilot_instr" ] && [ ! -f "$ai_ctx" ]; then
        {
            echo "# Project Context for AI Coding Assistants"
            echo ""
            echo "> Auto-generated by Plan Forge. Load this file into your AI assistant's context."
            echo "> Regenerate with: re-run setup with --agent generic"
            echo ""
            echo "## How to Use These Guardrails"
            echo ""
            echo "This file contains domain-specific guardrails organized by section. When editing code:"
            echo "- Editing database/SQL/repository code → follow the **database** section"
            echo "- Editing auth/JWT/OIDC code → follow the **auth** section"
            echo "- Editing API controllers/routes → follow the **api-patterns** section"
            echo "- Editing tests → follow the **testing** section"
            echo "- Editing Docker/deploy files → follow the **deploy** section"
            echo "- Always follow **architecture-principles** and **security** sections"
            echo ""
            echo "**After every file edit**: Scan for TODO, FIXME, HACK, stub, placeholder markers. Warn immediately if found."
            echo ""
            echo "**Before editing any file**: If a hardened plan exists in \`docs/plans/\`, check its Forbidden Actions section. Do not edit files listed there."
            echo ""
            echo "**Pipeline flow**: After completing a step, tell the user what to invoke next:"
            echo "- After Step 0 (Specify) → run step1-preflight-check"
            echo "- After Step 2 (Harden) → run step3-execute-slice"
            echo "- After Step 4 (Sweep) → Start a NEW session for Step 5 (Review)"
            echo "- After Step 5 (Review) → run step6-ship"
            echo ""
            echo "## Project Instructions"
            echo ""
            cat "$copilot_instr"
            echo ""

            # Embed all instruction files inline
            local instr_dir="$target/.github/instructions"
            if [ -d "$instr_dir" ]; then
                echo "---"
                echo ""
                echo "## Guardrail Files"
                echo ""
                echo "The following guardrails are embedded from Plan Forge instruction files."
                echo ""

                for instr_file in "$instr_dir"/*.instructions.md; do
                    [ -f "$instr_file" ] || continue
                    local domain
                    domain="$(basename "$instr_file" .instructions.md)"
                    echo "### $domain"
                    echo ""
                    # Strip YAML frontmatter
                    sed '/^---$/,/^---$/d' "$instr_file"
                    echo ""
                done
            fi
        } > "$ai_ctx"
        green "  CREATE $generic_dir/AI_INSTRUCTIONS.md (project context + guardrails)"
    fi

    # Copy prompts as plain markdown files
    local prompts_src="$target/.github/prompts"
    local prompts_dst="$output_dir/prompts"
    if [ -d "$prompts_src" ]; then
        mkdir -p "$prompts_dst"
        for prompt_file in "$prompts_src"/*.prompt.md; do
            [ -f "$prompt_file" ] || continue
            local base
            base="$(basename "$prompt_file")"
            local dst="$prompts_dst/$base"
            if [ ! -f "$dst" ]; then
                cp "$prompt_file" "$dst"
                green "  COPY  $generic_dir/prompts/$base"
            fi
        done
    fi

    # Copy agent definition files as plain markdown files
    local agents_src="$target/.github/agents"
    local agents_dst="$output_dir/agents"
    if [ -d "$agents_src" ]; then
        mkdir -p "$agents_dst"
        for agent_file in "$agents_src"/*.agent.md; do
            [ -f "$agent_file" ] || continue
            local base
            base="$(basename "$agent_file")"
            local dst="$agents_dst/$base"
            if [ ! -f "$dst" ]; then
                cp "$agent_file" "$dst"
                green "  COPY  $generic_dir/agents/$base"
            fi
        done
    fi
}

detect_preset() {
    local target="$1"

    # .NET markers
    if find "$target" -maxdepth 3 -name "*.csproj" -o -name "*.sln" -o -name "*.fsproj" 2>/dev/null | head -1 | grep -q .; then
        yellow "  AUTO-DETECT  Found .NET project markers"
        echo "dotnet"
        return
    fi

    # Go markers
    if [[ -f "$target/go.mod" ]]; then
        yellow "  AUTO-DETECT  Found Go project markers"
        echo "go"
        return
    fi

    # Swift markers
    if [[ -f "$target/Package.swift" ]] || find "$target" -maxdepth 1 -name "*.xcodeproj" -o -name "*.xcworkspace" 2>/dev/null | head -1 | grep -q .; then
        yellow "  AUTO-DETECT  Found Swift project markers"
        echo "swift"
        return
    fi

    # Rust markers
    if [[ -f "$target/Cargo.toml" ]]; then
        yellow "  AUTO-DETECT  Found Rust project markers"
        echo "rust"
        return
    fi

    # Java markers
    if [[ -f "$target/pom.xml" ]] || [[ -f "$target/build.gradle" ]] || [[ -f "$target/build.gradle.kts" ]]; then
        yellow "  AUTO-DETECT  Found Java project markers"
        echo "java"
        return
    fi

    # Python markers
    if [[ -f "$target/pyproject.toml" ]] || [[ -f "$target/requirements.txt" ]] || [[ -f "$target/setup.py" ]] || [[ -f "$target/Pipfile" ]]; then
        yellow "  AUTO-DETECT  Found Python project markers"
        echo "python"
        return
    fi

    # TypeScript/Node markers
    if [[ -f "$target/package.json" ]] || [[ -f "$target/tsconfig.json" ]]; then
        yellow "  AUTO-DETECT  Found TypeScript/Node project markers"
        echo "typescript"
        return
    fi

    # PHP/Laravel markers
    if [[ -f "$target/composer.json" ]] || [[ -f "$target/artisan" ]]; then
        yellow "  AUTO-DETECT  Found PHP/Laravel project markers"
        echo "php"
        return
    fi

    # Azure IaC markers
    if find "$target" -maxdepth 4 -name "*.bicep" -o -name "bicepconfig.json" -o -name "azure.yaml" 2>/dev/null | head -1 | grep -q .; then
        yellow "  AUTO-DETECT  Found Azure IaC project markers"
        echo "azure-iac"
        return
    fi
    if find "$target" -maxdepth 4 -name "*.tf" 2>/dev/null | head -1 | grep -q .; then
        yellow "  AUTO-DETECT  Found Terraform project markers"
        echo "azure-iac"
        return
    fi

    yellow "  AUTO-DETECT  No known markers found — using 'custom'"
    echo "custom"
}

# ─── Banner ────────────────────────────────────────────────────────────
echo ""
cyan "╔══════════════════════════════════════════════════════════════╗"
cyan "║       Plan Forge — Project Setup Wizard              ║"
cyan "║       Bootstraps planning pipeline + tech instructions      ║"
cyan "╚══════════════════════════════════════════════════════════════╝"
echo ""

# ─── Interactive Prompts ───────────────────────────────────────────────
# Floor is read from pforge-mcp/package.json so this never drifts from the manifest.
MCP_PKG_PATH="$TEMPLATE_ROOT/pforge-mcp/package.json"
if [[ -f "$MCP_PKG_PATH" ]]; then
    if ! command -v node &>/dev/null; then
        red "  ERROR  Node.js not found — Plan Forge requires a modern Node runtime"
        red "         Install from https://nodejs.org/ and re-run setup."
        exit 1
    fi
    if ! REQUIRED_NODE="$(node -p "JSON.parse(require('node:fs').readFileSync(0,'utf8')).engines.node.replace(/^>=/,'')" < "$MCP_PKG_PATH")"; then
        red "  ERROR  Could not read the Node.js requirement from $MCP_PKG_PATH"
        exit 1
    fi
    CURRENT_NODE="$(node --version 2>/dev/null | sed 's/^v//')"
    if [[ -n "$REQUIRED_NODE" ]]; then
        req_major="${REQUIRED_NODE%%.*}"; req_rest="${REQUIRED_NODE#*.}"; req_minor="${req_rest%%.*}"
        cur_major="${CURRENT_NODE%%.*}"; cur_rest="${CURRENT_NODE#*.}"; cur_minor="${cur_rest%%.*}"
        if [ "$cur_major" -lt "$req_major" ] 2>/dev/null || { [ "$cur_major" -eq "$req_major" ] && [ "$cur_minor" -lt "$req_minor" ]; } 2>/dev/null; then
            red "  ERROR  Node.js v$CURRENT_NODE is below the required >= $REQUIRED_NODE"
            red "         npm reports this only as an EBADENGINE warning, so setup stops here instead."
            red "         Upgrade Node.js from https://nodejs.org/ and re-run setup."
            exit 1
        fi
        echo "  Node.js v$CURRENT_NODE (requires >= $REQUIRED_NODE)"
    fi
fi

if [[ -z "$PROJECT_PATH" ]]; then
    PROJECT_PATH="$(prompt_value "Target project directory" "$(pwd)")"
fi

# Resolve to absolute path
PROJECT_PATH="$(cd "$PROJECT_PATH" 2>/dev/null && pwd || echo "$PROJECT_PATH")"

if [[ ! -d "$PROJECT_PATH" ]]; then
    yellow "Creating directory: $PROJECT_PATH"
    mkdir -p "$PROJECT_PATH"
fi

# ─── Spec Kit Detection ───────────────────────────────────────────────
SPEC_KIT_LINES=()
if [[ -d "$PROJECT_PATH/specs" ]]; then
    while IFS= read -r sf; do
        rel="${sf#$PROJECT_PATH/}"
        SPEC_KIT_LINES+=("  • $rel — feature specification")
    done < <(find "$PROJECT_PATH/specs" -name "spec.md" -type f 2>/dev/null | head -5)
    while IFS= read -r pf; do
        rel="${pf#$PROJECT_PATH/}"
        SPEC_KIT_LINES+=("  • $rel — implementation plan")
    done < <(find "$PROJECT_PATH/specs" -name "plan.md" -type f 2>/dev/null | head -5)
    while IFS= read -r tf; do
        rel="${tf#$PROJECT_PATH/}"
        SPEC_KIT_LINES+=("  • $rel — task breakdown")
    done < <(find "$PROJECT_PATH/specs" -name "tasks.md" -type f 2>/dev/null | head -5)
fi
if [[ -f "$PROJECT_PATH/memory/constitution.md" ]]; then
    SPEC_KIT_LINES+=("  • memory/constitution.md — project constitution")
fi
if [[ "${#SPEC_KIT_LINES[@]}" -gt 0 ]]; then
    echo ""
    printf '\033[0;35m%s\033[0m\n' "╔══════════════════════════════════════════════════════════════╗"
    printf '\033[0;35m%s\033[0m\n' "║       Spec Kit Artifacts Detected                          ║"
    printf '\033[0;35m%s\033[0m\n' "╚══════════════════════════════════════════════════════════════╝"
    echo ""
    printf '\033[0;35m%s\033[0m\n' "Found Spec Kit artifacts in this project:"
    for line in "${SPEC_KIT_LINES[@]}"; do
        printf '\033[0;35m%s\033[0m\n' "$line"
    done
    echo ""
    cyan "Plan Forge will complement your Spec Kit workflow:"
    echo "  - Spec Kit defines WHAT to build"
    echo "  - Plan Forge hardens specs into execution contracts with validation gates"
    echo "  - To import a spec: open docs/plans/AI-Plan-Hardening-Runbook-Instructions.md after setup"
    echo ""
fi

if [[ -z "$PROJECT_NAME" ]]; then
    default_name="$(basename "$PROJECT_PATH")"
    PROJECT_NAME="$(prompt_value "Project name" "$default_name")"
fi

if [[ -z "$PRESET" ]]; then
    if [[ "$AUTO_DETECT" == true ]]; then
        echo ""
        cyan "Auto-detecting tech stack..."
        PRESET="$(detect_preset "$PROJECT_PATH")"
        if [[ "$FORCE" != true ]] && ! skip_prompts; then
            read -rp "Detected preset: $PRESET. Is this correct? (Y/n) " confirm_preset
            if [[ -n "$confirm_preset" ]] && [[ "$confirm_preset" != [yY]* ]]; then
                echo ""
                cyan "Available presets:"
                echo "  1) dotnet      — .NET / C# / ASP.NET Core"
                echo "  2) typescript  — TypeScript / React / Node.js / Express"
                echo "  3) python      — Python / FastAPI / SQLAlchemy"
                echo "  4) java        — Java / Spring Boot / Gradle / Maven"
                echo "  5) go          — Go / Chi / Gin / Standard Library"
                echo "  6) swift       — Swift / SwiftUI / iOS / Vapor"
                echo "  7) azure-iac   — Azure Bicep / Terraform / PowerShell / azd"
                echo "  8) custom      — Shared files only (add your own instructions)"
                echo "  9) rust        — Rust / Axum / Tokio / SQLx"
                echo " 10) php         — PHP / Laravel"
                echo ""
                choice="$(prompt_value "Select preset (1-10 or name)" "1")"
                case "$choice" in
                    1|dotnet)     PRESET="dotnet" ;;
                    2|typescript) PRESET="typescript" ;;
                    3|python)     PRESET="python" ;;
                    4|java)       PRESET="java" ;;
                    5|go)         PRESET="go" ;;
                    6|swift)      PRESET="swift" ;;
                    7|azure-iac)  PRESET="azure-iac" ;;
                    8|custom)     PRESET="custom" ;;
                    9|rust)       PRESET="rust" ;;
                    10|php)       PRESET="php" ;;
                    *)            PRESET="$choice" ;;
                esac
            fi
        fi
    else
        echo ""
        cyan "Available presets:"
        echo "  1) dotnet      — .NET / C# / ASP.NET Core"
        echo "  2) typescript  — TypeScript / React / Node.js / Express"
        echo "  3) python      — Python / FastAPI / SQLAlchemy"
        echo "  4) java        — Java / Spring Boot / Gradle / Maven"
        echo "  5) go          — Go / Chi / Gin / Standard Library"
        echo "  6) swift       — Swift / SwiftUI / iOS / Vapor"
        echo "  7) azure-iac   — Azure Bicep / Terraform / PowerShell / azd"
        echo "  8) custom      — Shared files only (add your own instructions)"
        echo "  9) rust        — Rust / Axum / Tokio / SQLx"
        echo " 10) php         — PHP / Laravel"
        echo ""
        choice="$(prompt_value "Select preset (1-10 or name)" "1")"
        case "$choice" in
            1|dotnet)     PRESET="dotnet" ;;
            2|typescript) PRESET="typescript" ;;
            3|python)     PRESET="python" ;;
            4|java)       PRESET="java" ;;
            5|go)         PRESET="go" ;;
            6|swift)      PRESET="swift" ;;
            7|azure-iac)  PRESET="azure-iac" ;;
            8|custom)     PRESET="custom" ;;
            9|rust)       PRESET="rust" ;;
            10|php)       PRESET="php" ;;
            *)            PRESET="$choice" ;;
        esac
    fi
fi

# ─── Build/Test/Lint Commands ──────────────────────────────────────────
# Normalise: split comma-separated preset string into array
IFS=',' read -ra PRESETS <<< "$PRESET"
for i in "${!PRESETS[@]}"; do
    PRESETS[$i]="$(echo "${PRESETS[$i]}" | tr -d ' ')"
done

VALID_PRESETS=(dotnet typescript python java go swift rust php azure-iac custom)
for p in "${PRESETS[@]}"; do
    valid=false
    for v in "${VALID_PRESETS[@]}"; do [[ "$p" == "$v" ]] && valid=true && break; done
    if [[ "$valid" != true ]]; then
        red "  ERROR  Unknown preset '$p'. Valid values: ${VALID_PRESETS[*]}"
        exit 1
    fi
done

# Determine if custom-only
IS_CUSTOM_ONLY=false
if [[ "${#PRESETS[@]}" -eq 1 ]] && [[ "${PRESETS[0]}" == "custom" ]]; then
    IS_CUSTOM_ONLY=true
fi

# Primary preset drives build/test/lint defaults
PRIMARY_PRESET="custom"
for p in "${PRESETS[@]}"; do
    if [[ "$p" != "custom" ]]; then PRIMARY_PRESET="$p"; break; fi
done

case "$PRIMARY_PRESET" in
    dotnet)     STACK_LABEL=".NET / C# / ASP.NET Core" ;;
    typescript) STACK_LABEL="TypeScript / React / Node.js" ;;
    python)     STACK_LABEL="Python / FastAPI" ;;
    java)       STACK_LABEL="Java / Spring Boot" ;;
    go)         STACK_LABEL="Go / Standard Library" ;;
    swift)      STACK_LABEL="Swift / SwiftUI / iOS / Vapor" ;;
    rust)       STACK_LABEL="Rust / Axum / Tokio / SQLx" ;;
    php)        STACK_LABEL="PHP / Laravel" ;;
    azure-iac)  STACK_LABEL="Azure Bicep / Terraform / PowerShell / azd" ;;
    custom)     STACK_LABEL="Custom (configure manually)" ;;
    *)          red "Unknown preset: $PRIMARY_PRESET"; exit 1 ;;
esac

case "$PRIMARY_PRESET" in
    dotnet)     DEFAULT_BUILD="dotnet build"; DEFAULT_TEST="dotnet test"; DEFAULT_LINT="dotnet format --verify-no-changes" ;;
    typescript) DEFAULT_BUILD="pnpm build"; DEFAULT_TEST="pnpm test"; DEFAULT_LINT="pnpm lint" ;;
    python)     DEFAULT_BUILD="python -m build"; DEFAULT_TEST="pytest"; DEFAULT_LINT="ruff check ." ;;
    java)       DEFAULT_BUILD="./gradlew build"; DEFAULT_TEST="./gradlew test"; DEFAULT_LINT="./gradlew spotlessCheck" ;;
    go)         DEFAULT_BUILD="go build ./..."; DEFAULT_TEST="go test ./..."; DEFAULT_LINT="golangci-lint run" ;;
    swift)      DEFAULT_BUILD="swift build"; DEFAULT_TEST="swift test"; DEFAULT_LINT="swift package plugin --allow-writing-to-package-directory swiftlint" ;;
    rust)       DEFAULT_BUILD="cargo build --locked"; DEFAULT_TEST="cargo test"; DEFAULT_LINT="cargo clippy --all-targets --all-features -- -D warnings" ;;
    php)        DEFAULT_BUILD="composer install"; DEFAULT_TEST="php artisan test"; DEFAULT_LINT="vendor/bin/pint --test" ;;
    azure-iac)  DEFAULT_BUILD="az bicep build --file infra/main.bicep"; DEFAULT_TEST="Invoke-Pester -Path ./tests -Output Detailed"; DEFAULT_LINT="az bicep lint --file infra/main.bicep" ;;
    custom)     DEFAULT_BUILD=""; DEFAULT_TEST=""; DEFAULT_LINT="" ;;
esac

if [[ "$FORCE" != true ]]; then
    echo ""
    cyan "Build/Test/Lint commands (press Enter for defaults):"
    BUILD_CMD="$(prompt_value "Build command" "$DEFAULT_BUILD")"
    TEST_CMD="$(prompt_value "Test command" "$DEFAULT_TEST")"
    LINT_CMD="$(prompt_value "Lint command" "$DEFAULT_LINT")"
else
    BUILD_CMD="$DEFAULT_BUILD"
    TEST_CMD="$DEFAULT_TEST"
    LINT_CMD="$DEFAULT_LINT"
fi

# ─── Summary ───────────────────────────────────────────────────────────
echo ""
cyan "Configuration:"
echo "  Project:  $PROJECT_NAME"
echo "  Path:     $PROJECT_PATH"
echo "  Preset(s): ${PRESETS[*]} ($STACK_LABEL)"
echo "  Build:    $BUILD_CMD"
echo "  Test:     $TEST_CMD"
echo "  Lint:     $LINT_CMD"
echo "  Force:    $FORCE"
echo ""

if [[ "$FORCE" != true ]] && ! skip_prompts; then
    read -rp "Proceed? (Y/n) " confirm || confirm=""
    if [[ -n "$confirm" ]] && [[ "$confirm" != [yY]* ]]; then
        red "Aborted."
        exit 0
    fi
fi

# ─── Step 1: Copy Core Files ──────────────────────────────────────────
echo ""
cyan "Step 1: Core planning files"

declare -A CORE_FILES=(
    ["docs/plans/AI-Plan-Hardening-Runbook.md"]="docs/plans/AI-Plan-Hardening-Runbook.md"
    ["docs/plans/AI-Plan-Hardening-Runbook-Instructions.md"]="docs/plans/AI-Plan-Hardening-Runbook-Instructions.md"
    ["docs/plans/README.md"]="docs/plans/README.md"
    ["docs/plans/DEPLOYMENT-ROADMAP-TEMPLATE.md"]="docs/plans/DEPLOYMENT-ROADMAP.md"
    ["docs/plans/PROJECT-PRINCIPLES-TEMPLATE.md"]="docs/plans/PROJECT-PRINCIPLES-TEMPLATE.md"
)

for src_rel in "${!CORE_FILES[@]}"; do
    dst_rel="${CORE_FILES[$src_rel]}"
    src="$TEMPLATE_ROOT/$src_rel"
    dst="$PROJECT_PATH/$dst_rel"
    if [[ -f "$src" ]]; then
        copy_with_create "$src" "$dst" || true
    else
        yellow "  WARN  Source not found: $src_rel"
    fi
done

# ─── Step 2: Copy Shared Instruction Files ─────────────────────────────
echo ""
cyan "Step 2: Shared instruction files"

# Source paths:
#   .github/instructions/                  — Plan-Forge-internal files that are universal & ship as-is to consumers
#   presets/shared/.github/instructions/   — consumer-facing genericized versions (no Plan-Forge-internal references)
#   templates/.github/instructions/        — pure templates
# aci-design.instructions.md intentionally NOT shipped — it governs MCP tool authoring, which consumers don't typically do.
# The file names themselves live in pforge-mcp/preset-catalog.json (internalInstructions /
# sharedInstructions) so this list can't drift from update-plan.mjs's instruction categories (#299).
PRESET_CATALOG_PATH="$TEMPLATE_ROOT/pforge-mcp/preset-catalog.json"
mapfile -t _INTERNAL_INSTRUCTIONS < <(node -p "JSON.parse(require('node:fs').readFileSync(0,'utf8')).internalInstructions.join('\n')" < "$PRESET_CATALOG_PATH")
mapfile -t _SHARED_INSTRUCTIONS < <(node -p "JSON.parse(require('node:fs').readFileSync(0,'utf8')).sharedInstructions.join('\n')" < "$PRESET_CATALOG_PATH")
SHARED_FILES=()
for _name in "${_INTERNAL_INSTRUCTIONS[@]}"; do
    SHARED_FILES+=(".github/instructions/$_name")
done
for _name in "${_SHARED_INSTRUCTIONS[@]}"; do
    SHARED_FILES+=("presets/shared/.github/instructions/$_name:.github/instructions/$_name")
done
# project-principles.instructions.md is a pure template, not a shipped instruction file,
# so it isn't part of preset-catalog.json's internal/shared lists.
SHARED_FILES+=("templates/.github/instructions/project-principles.instructions.md:.github/instructions/project-principles.instructions.md")

# A selected stack preset's own copy (e.g. testing or security) wins over the shared
# one. Copying the shared file first would make Step 3 skip the preset's (#280).
for rel in "${SHARED_FILES[@]}"; do
    if [[ "$rel" == *":"* ]]; then
        src="$TEMPLATE_ROOT/${rel%%:*}"
        dst_rel="${rel##*:}"
    else
        src="$TEMPLATE_ROOT/$rel"
        dst_rel="$rel"
    fi
    dst="$PROJECT_PATH/$dst_rel"
    shared_owned_by_preset=false
    for shared_preset in "${PRESETS[@]}"; do
        [[ "$shared_preset" == "custom" ]] && continue
        if [[ -f "$TEMPLATE_ROOT/presets/$shared_preset/$dst_rel" ]]; then
            shared_owned_by_preset=true
            break
        fi
    done
    if [[ -f "$src" ]] && [[ "$shared_owned_by_preset" != true ]]; then
        copy_with_create "$src" "$dst" || true
    fi
done

# ─── Step 3: Copy Preset Files ────────────────────────────────────────
if [[ "$IS_CUSTOM_ONLY" != true ]]; then
    is_first_preset=true

    for active_preset in "${PRESETS[@]}"; do
        [[ "$active_preset" == "custom" ]] && continue

        echo ""
        cyan "Step 3: $active_preset preset files"

        PRESET_DIR="$TEMPLATE_ROOT/presets/$active_preset"
        if [[ ! -d "$PRESET_DIR" ]]; then
            red "  ERROR  Preset directory not found: $PRESET_DIR"
            exit 1
        fi

        # Copy all files from preset, preserving relative paths
        while IFS= read -r -d '' file; do
            rel_path="${file#"$PRESET_DIR/"}"
            dst="$PROJECT_PATH/$rel_path"
            copy_with_create "$file" "$dst" || true
        done < <(find "$PRESET_DIR" -type f -print0)

        # First preset sets copilot-instructions.md; subsequent ones don't overwrite
        preset_copilot="$PRESET_DIR/.github/copilot-instructions.md"
        root_copilot="$PROJECT_PATH/.github/copilot-instructions.md"
        if [[ "$is_first_preset" == true ]] && [[ -f "$preset_copilot" ]] && [[ ! -f "$root_copilot" ]]; then
            copy_with_create "$preset_copilot" "$root_copilot" || true
        fi

        # First preset sets AGENTS.md; subsequent ones don't overwrite
        preset_agents="$PRESET_DIR/AGENTS.md"
        root_agents="$PROJECT_PATH/AGENTS.md"
        if [[ "$is_first_preset" == true ]] && [[ -f "$preset_agents" ]] && [[ ! -f "$root_agents" ]]; then
            copy_with_create "$preset_agents" "$root_agents" || true
        fi

        is_first_preset=false
    done
else
    echo ""
    cyan "Step 3: Custom preset — copying template copilot-instructions.md only"

    src="$TEMPLATE_ROOT/.github/copilot-instructions.md"
    dst="$PROJECT_PATH/.github/copilot-instructions.md"
    if [[ -f "$src" ]]; then
        copy_with_create "$src" "$dst" || true
    fi
fi

# ─── Step 3b: Copy Shared Agents ───────────────────────────────────────
if [[ "$IS_CUSTOM_ONLY" != true ]]; then
    echo ""
    cyan "Step 3b: Shared agents (cross-stack reviewers + pipeline agents)"

    # Shared agents (api-contract, accessibility, multi-tenancy, cicd, observability, dependency, compliance)
    SHARED_AGENTS_DIR="$TEMPLATE_ROOT/presets/shared/.github/agents"
    if [[ -d "$SHARED_AGENTS_DIR" ]]; then
        while IFS= read -r -d '' file; do
            filename="$(basename "$file")"
            dst="$PROJECT_PATH/.github/agents/$filename"
            copy_with_create "$file" "$dst" || true
        done < <(find "$SHARED_AGENTS_DIR" -name "*.agent.md" -type f -print0)
    fi

    # Pipeline agents (specifier, plan-hardener, executor, reviewer-gate, shipper)
    PIPELINE_AGENTS_DIR="$TEMPLATE_ROOT/templates/.github/agents"
    if [[ -d "$PIPELINE_AGENTS_DIR" ]]; then
        while IFS= read -r -d '' file; do
            filename="$(basename "$file")"
            dst="$PROJECT_PATH/.github/agents/$filename"
            copy_with_create "$file" "$dst" || true
        done < <(find "$PIPELINE_AGENTS_DIR" -name "*.agent.md" -type f -print0)
    fi

    # Shared skills (health-check, forge-execute, security-audit — stack-independent fallbacks)
    # Note: Never force-overwrite — preset skills take priority over shared versions
    SHARED_SKILLS_DIR="$TEMPLATE_ROOT/presets/shared/skills"
    if [[ -d "$SHARED_SKILLS_DIR" ]]; then
        for skill_dir in "$SHARED_SKILLS_DIR"/*/; do
            skill_name="$(basename "$skill_dir")"
            skill_src="$skill_dir/SKILL.md"
            skill_dst="$PROJECT_PATH/.github/skills/$skill_name/SKILL.md"
            if [[ -f "$skill_src" ]]; then
                # Don't overwrite — preset skills should win over shared fallbacks.
                # `local` is invalid here (we're at script scope, not inside a
                # function) — a plain assignment does the same job and is
                # portable across Bash 3/4/5.
                saved_force="$FORCE"
                FORCE=false
                copy_with_create "$skill_src" "$skill_dst" || true
                FORCE="$saved_force"
            fi
        done
    fi
fi

# ─── Step 3c: Copy Project Principles Prompt + Extension Templates ─────
if [[ "$IS_CUSTOM_ONLY" != true ]]; then
    echo ""
    cyan "Step 3c: Project Principles prompt + extension templates + hooks"

    # Project Principles prompt
    pp_prompt_src="$TEMPLATE_ROOT/templates/.github/prompts/project-principles.prompt.md"
    pp_prompt_dst="$PROJECT_PATH/.github/prompts/project-principles.prompt.md"
    if [[ -f "$pp_prompt_src" ]]; then
        copy_with_create "$pp_prompt_src" "$pp_prompt_dst" || true
    fi

    # Pipeline prompts (step0-step6 + project-profile) from repo .github/prompts/
    pipeline_prompts_src="$TEMPLATE_ROOT/.github/prompts"
    if [[ -d "$pipeline_prompts_src" ]]; then
        while IFS= read -r -d '' file; do
            base_name="$(basename "$file")"
            # Skip project-principles.prompt.md — already handled from templates/ above
            if [[ "$base_name" == "project-principles.prompt.md" ]]; then continue; fi
            dst="$PROJECT_PATH/.github/prompts/$base_name"
            copy_with_create "$file" "$dst" || true
        done < <(find "$pipeline_prompts_src" -maxdepth 1 -name "*.prompt.md" -type f -print0)
    fi

    # Extension template directory
    ext_template_src="$TEMPLATE_ROOT/templates/.forge"
    if [[ -d "$ext_template_src" ]]; then
        while IFS= read -r -d '' file; do
            rel_path="${file#"$ext_template_src/"}"
            dst="$PROJECT_PATH/.forge/$rel_path"
            copy_with_create "$file" "$dst" || true
        done < <(find "$ext_template_src" -type f -print0)
    fi

    # Hooks
    hooks_src="$TEMPLATE_ROOT/templates/.github/hooks"
    if [[ -d "$hooks_src" ]]; then
        while IFS= read -r -d '' file; do
            rel_path="${file#"$hooks_src/"}"
            dst="$PROJECT_PATH/.github/hooks/$rel_path"
            copy_with_create "$file" "$dst" || true
        done < <(find "$hooks_src" -type f -print0)
    fi

    # VS Code automation templates (import from the Agents window > Automations)
    automations_src="$TEMPLATE_ROOT/templates/.github/automations"
    if [[ -d "$automations_src" ]]; then
        while IFS= read -r -d '' file; do
            rel_path="${file#"$automations_src/"}"
            dst="$PROJECT_PATH/.github/automations/$rel_path"
            copy_with_create "$file" "$dst" || true
        done < <(find "$automations_src" -type f -print0)
    fi
fi

# ─── Step 4: Replace Placeholders ─────────────────────────────────────
echo ""
cyan "Step 4: Replacing placeholders"

while IFS= read -r -d '' file; do
    replace_placeholders "$file" "$PROJECT_NAME" "$STACK_LABEL"
done < <(find "$PROJECT_PATH" -name "*.md" -type f -print0)

green "  DONE  Placeholders replaced"

# ─── Step 5: Generate .forge.json ─────────────────────────────
echo ""
cyan "Step 5: Generating .forge.json"

CONFIG_PATH="$PROJECT_PATH/.forge.json"
VERSION_FILE="$TEMPLATE_ROOT/VERSION"
TEMPLATE_VERSION="1.0.0"
if [[ -f "$VERSION_FILE" ]]; then
    TEMPLATE_VERSION="$(tr -d '\n' < "$VERSION_FILE")"
fi

# Phase-26 Slice 14 — best-defaults preset writer.
# Gated on existence so upgrades never clobber a user-customized config.
# Every Phase-26 inner-loop subsystem ships in ADVISORY posture: detection
# runs but no action is taken without explicit opt-in.
write_best_defaults_preset() {
    local target="$1"
    cat > "$target" <<EOF
{
  "projectName": "$PROJECT_NAME",
  "preset": "$(IFS=','; echo "${PRESETS[*]}")",
  "agents": "$AGENTS",
  "stack": "$STACK_LABEL",
  "setupDate": "$(date +%Y-%m-%d)",
  "templateVersion": "$TEMPLATE_VERSION",
  "modelRouting": {
    "default": "claude-opus-5.5"
  },
  "hooks": {
    "preDeploy": { "blockOnSecrets": true, "warnOnEnvGaps": true, "scanSince": "HEAD~1" },
    "postSlice": { "silentDeltaThreshold": 5, "warnDeltaThreshold": 10, "scoreFloor": 70 },
    "preAgentHandoff": { "injectContext": true, "runRegressionGuard": true, "cacheMaxAgeMinutes": 30, "minAlertSeverity": "medium" },
    "postRun": { "invokeAuditor": { "onFailure": false, "everyNRuns": null } }
  },
  "innerLoop": {
    "competitive": { "enabled": false },
    "autoFix": { "enabled": true, "applyWithoutReview": false },
    "costAnomaly": { "enabled": true, "ratio": 2.0, "medianWindow": 20 }
  },
  "brain": {
    "federation": { "enabled": false, "repos": [] }
  }
}
EOF
}

if [[ -f "$CONFIG_PATH" ]]; then
    yellow "  SKIPPED  .forge.json already exists (preserving user config)"
else
    write_best_defaults_preset "$CONFIG_PATH"
    green "  CREATED  .forge.json (best-defaults preset)"
fi

# ─── Step 5a: Create docs/plans/auto/ for LiveGuard fix proposals ────
AUTO_PLANS_DIR="$PROJECT_PATH/docs/plans/auto"
mkdir -p "$AUTO_PLANS_DIR"
if [[ ! -f "$AUTO_PLANS_DIR/README.md" ]]; then
    cat > "$AUTO_PLANS_DIR/README.md" <<'AUTOEOF'
# Auto-Generated Plans

This directory contains plans auto-generated by LiveGuard tools (e.g. `forge_fix_proposal`).

Files in this directory (except this README) are gitignored — they are runtime artifacts, not source-controlled plans.
AUTOEOF
fi
green "  CREATED  docs/plans/auto/"

# ─── Step 5b: Generate capabilities.json (machine-readable discovery) ────
CAPABILITIES_PATH="$PROJECT_PATH/.forge/capabilities.json"
mkdir -p "$(dirname "$CAPABILITIES_PATH")"

PROMPT_LIST="[]"
if [[ -d "$PROJECT_PATH/.github/prompts" ]]; then
    PROMPT_LIST=$(find "$PROJECT_PATH/.github/prompts" -maxdepth 1 -name "*.prompt.md" -printf '"%f",' 2>/dev/null | sed 's/,$//' | awk '{print "["$0"]"}')
    [[ "$PROMPT_LIST" == "[]" ]] || true
fi

AGENT_LIST="[]"
if [[ -d "$PROJECT_PATH/.github/agents" ]]; then
    AGENT_LIST=$(find "$PROJECT_PATH/.github/agents" -maxdepth 1 -name "*.agent.md" -printf '"%f",' 2>/dev/null | sed 's/,$//' | awk '{print "["$0"]"}')
    [[ "$AGENT_LIST" == "[]" ]] || true
fi

SKILL_LIST="[]"
if [[ -d "$PROJECT_PATH/.github/skills" ]]; then
    SKILL_LIST=$(find "$PROJECT_PATH/.github/skills" -mindepth 1 -maxdepth 1 -type d -printf '"%f",' 2>/dev/null | sed 's/,$//' | awk '{print "["$0"]"}')
    [[ "$SKILL_LIST" == "[]" ]] || true
fi

INSTR_LIST="[]"
if [[ -d "$PROJECT_PATH/.github/instructions" ]]; then
    INSTR_LIST=$(find "$PROJECT_PATH/.github/instructions" -maxdepth 1 -name "*.instructions.md" -printf '"%f",' 2>/dev/null | sed 's/,$//' | awk '{print "["$0"]"}')
    [[ "$INSTR_LIST" == "[]" ]] || true
fi

cat > "$CAPABILITIES_PATH" <<EOF
{
  "generatedBy": "plan-forge-setup",
  "generatedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "preset": "$(IFS=','; echo "${PRESETS[*]}")",
  "prompts": ${PROMPT_LIST:-[]},
  "skills": ${SKILL_LIST:-[]},
  "instructions": ${INSTR_LIST:-[]},
  "hooks": [".github/hooks/plan-forge.json"]
}
EOF

green "  CREATED  .forge/capabilities.json"

# ─── Step 6: Copy VS Code Settings Template ────────────────────────────
echo ""
cyan "Step 6: VS Code settings template"

vscode_src="$TEMPLATE_ROOT/templates/vscode-settings.json.template"
vscode_dst="$PROJECT_PATH/.vscode/settings.json"
if [[ -f "$vscode_src" ]]; then
    copy_with_create "$vscode_src" "$vscode_dst" || true
fi

# ─── Step 6b: Install Agent Adapters ───────────────────────────────────
AGENT_LIST="$AGENTS"
if [[ "$AGENT_LIST" == "all" ]]; then
    AGENT_LIST="copilot,claude,cursor,windsurf,codex,gemini,generic"
fi

IFS=',' read -ra AGENT_ARRAY <<< "$AGENT_LIST"
EXTRA_AGENTS=()
for ag in "${AGENT_ARRAY[@]}"; do
    ag="$(echo "$ag" | tr -d ' ')"
    [[ "$ag" != "copilot" ]] && EXTRA_AGENTS+=("$ag")
done

if [[ ${#EXTRA_AGENTS[@]} -gt 0 ]]; then
    echo ""
    cyan "Step 6b: Agent adapters (${EXTRA_AGENTS[*]})"

    for ag in "${EXTRA_AGENTS[@]}"; do
        case "$ag" in
            claude)    install_claude_agent "$PROJECT_PATH" ;;
            cursor)    install_cursor_agent "$PROJECT_PATH" ;;
            windsurf)  install_windsurf_agent "$PROJECT_PATH" ;;
            codex)     install_codex_agent "$PROJECT_PATH" ;;
            gemini)    install_gemini_agent "$PROJECT_PATH" ;;
            generic)   install_generic_agent "$PROJECT_PATH" "$GENERIC_DIR" ;;
            *) yellow "  Unknown agent: $ag — skipping" ;;
        esac
    done
fi

# ─── Step 7: Copy Copilot VS Code Guide ────────────────────────────────
guide_src="$TEMPLATE_ROOT/docs/COPILOT-VSCODE-GUIDE.md"
guide_dst="$PROJECT_PATH/docs/COPILOT-VSCODE-GUIDE.md"
if [[ -f "$guide_src" ]]; then
    copy_with_create "$guide_src" "$guide_dst" || true
fi

# ─── Step 7b-pre-1: Copy pforge-sdk (helper library used by pforge-mcp) ───
# pforge-sdk is NOT an npm workspace member but IS imported by pforge-mcp
# via relative paths. Consumer installs that skipped this crashed at runtime
# when opt-in features (lattice, notifications, hallmark, memory-upgrade,
# forge-master-chat) tried to resolve those paths. SDK has no runtime deps.
SDK_SRC_DIR="$TEMPLATE_ROOT/pforge-sdk"
if [[ -d "$SDK_SRC_DIR" ]]; then
    echo ""
    cyan "Step 7b-pre-1: pforge-sdk (helper library)"
    SDK_DST_DIR="$PROJECT_PATH/pforge-sdk"
    mkdir -p "$SDK_DST_DIR"
    sdk_count=0
    while IFS= read -r -d '' f; do
        rel_path="${f#"$SDK_SRC_DIR/"}"
        dst_file="$SDK_DST_DIR/$rel_path"
        mkdir -p "$(dirname "$dst_file")"
        cp "$f" "$dst_file"
        sdk_count=$((sdk_count + 1))
    done < <(list_runtime_package_files "$SDK_SRC_DIR")
    green "  COPY  pforge-sdk/ ($sdk_count files: hallmark, lattice, chunker, notifications, readers)"
fi

# ─── Step 7b-pre-2: Copy pforge-master (Forge-Master Studio MCP server) ───
# Must be copied BEFORE Step 7b so the .vscode/mcp.json merge below detects
# pforge-master/server.mjs and registers the `forge-master-chat` entry.
FM_SRC_DIR="$TEMPLATE_ROOT/pforge-master"
if [[ -d "$FM_SRC_DIR" ]]; then
    echo ""
    cyan "Step 7b-pre-2: pforge-master (Forge-Master Studio)"
    FM_DST_DIR="$PROJECT_PATH/pforge-master"
    mkdir -p "$FM_DST_DIR"
    fm_count=0
    while IFS= read -r -d '' f; do
        rel_path="${f#"$FM_SRC_DIR/"}"
        dst_file="$FM_DST_DIR/$rel_path"
        mkdir -p "$(dirname "$dst_file")"
        cp "$f" "$dst_file"
        fm_count=$((fm_count + 1))
    done < <(list_runtime_package_files "$FM_SRC_DIR")
    green "  COPY  pforge-master/ ($fm_count files: server, observer-loop, planner, providers, ui)"

    # Auto-install pforge-master dependencies (@modelcontextprotocol/sdk + ws)
    if [[ -f "$FM_DST_DIR/package.json" ]]; then
        echo "  Installing pforge-master dependencies..."
        if (cd "$FM_DST_DIR" && npm install --silent 2>/dev/null); then
            green "  ✅ npm install complete"
        else
            yellow "  ⚠️  npm install failed — run manually: cd pforge-master && npm install"
        fi
    fi
fi

# ─── Step 7b: Copy MCP Server + Generate Config ───────────────────────
MCP_SRC_DIR="$TEMPLATE_ROOT/pforge-mcp"
if [[ -d "$MCP_SRC_DIR" ]]; then
    echo ""
    cyan "Step 7b: MCP server (Plan Forge as tools)"

    MCP_DST_DIR="$PROJECT_PATH/pforge-mcp"
    mkdir -p "$MCP_DST_DIR"

    # Copy all MCP runtime files (not node_modules or .forge).
    # `local` is invalid at script scope — these accumulators live at
    # top-level inside the `if` block, so plain assignments are used.
    mcp_count=0
    while IFS= read -r -d '' f; do
        rel_path="${f#"$MCP_SRC_DIR/"}"
        dst_file="$MCP_DST_DIR/$rel_path"
        mkdir -p "$(dirname "$dst_file")"
        cp "$f" "$dst_file"
        mcp_count=$((mcp_count + 1))
    done < <(list_runtime_package_files "$MCP_SRC_DIR")
    green "  COPY  pforge-mcp/ ($mcp_count files: server, orchestrator, capabilities, dashboard, tests)"

    # Generate .vscode/mcp.json for Copilot MCP integration
    VSCODE_MCP="$PROJECT_PATH/.vscode/mcp.json"
    if [[ ! -f "$VSCODE_MCP" ]]; then
        mkdir -p "$PROJECT_PATH/.vscode"
        cat > "$VSCODE_MCP" <<'MCPEOF'
{
  "servers": {
    "plan-forge": {
      "type": "stdio",
      "command": "node",
      "args": ["pforge-mcp/server.mjs"],
      "cwd": "${workspaceFolder}"
    }
  }
}
MCPEOF
        green "  CREATE .vscode/mcp.json (plan-forge MCP server)"
    elif ! grep -q '"plan-forge"' "$VSCODE_MCP" 2>/dev/null; then
        # Simple check — if plan-forge not in file, tell user to add manually
        yellow "  NOTE  .vscode/mcp.json exists but missing 'plan-forge' entry — add manually"
    else
        yellow "  SKIP  .vscode/mcp.json → 'plan-forge' already exists"
    fi
    # Add forge-master-chat entry if pforge-master/server.mjs is present and not already registered.
    # Node does the merge, not python3: on Windows, Git Bash finds the Microsoft Store python3 stub,
    # which exits 49 and, under set -e, used to abort the whole install (#394).
    if [[ -f "$PROJECT_PATH/pforge-master/server.mjs" ]] && ! grep -q '"forge-master-chat"' "$VSCODE_MCP" 2>/dev/null; then
        if command -v node &>/dev/null; then
            node - "$VSCODE_MCP" <<'JSEOF' || yellow "  NOTE  add 'forge-master-chat' server to .vscode/mcp.json manually (could not merge it)"
const fs = require("node:fs");
const file = process.argv[2];
const data = JSON.parse(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
data.servers = data.servers || {};
if (!data.servers["forge-master-chat"]) {
  data.servers["forge-master-chat"] = {
    type: "stdio", command: "node",
    args: ["pforge-master/server.mjs"], cwd: "${workspaceFolder}"
  };
  fs.writeFileSync(file, JSON.stringify(data, null, 2));
  console.log("  MERGE .vscode/mcp.json -> added 'forge-master-chat' server");
}
JSEOF
        else
            yellow "  NOTE  add 'forge-master-chat' server to .vscode/mcp.json manually (node not found)"
        fi
    fi

    # Generate .claude/mcp.json for Claude MCP integration (if --agent claude)
    if [[ "$AGENTS" == *"claude"* ]] || [[ "$AGENTS" == "all" ]]; then
        CLAUDE_MCP_DIR="$PROJECT_PATH/.claude"
        CLAUDE_MCP="$CLAUDE_MCP_DIR/mcp.json"
        if [[ ! -f "$CLAUDE_MCP" ]]; then
            mkdir -p "$CLAUDE_MCP_DIR"
            cat > "$CLAUDE_MCP" <<'MCPEOF'
{
  "servers": {
    "plan-forge": {
      "type": "stdio",
      "command": "node",
      "args": ["pforge-mcp/server.mjs"],
      "cwd": "${workspaceFolder}"
    }
  }
}
MCPEOF
            green "  CREATE .claude/mcp.json (plan-forge MCP server)"
        fi
    fi

    # Auto-install MCP dependencies
    if [[ -f "$MCP_DST_DIR/package.json" ]]; then
        echo "  Installing MCP dependencies..."
        if (cd "$MCP_DST_DIR" && npm install --silent 2>/dev/null); then
            green "  ✅ npm install complete"
        else
            yellow "  ⚠️  npm install failed — run manually: cd pforge-mcp && npm install"
        fi
    fi
fi

# ─── Step 7c: Copy CLI Scripts + VERSION + validators ─────────────────
# Ships root `pforge` shim + validate-setup.{ps1,sh} so the consumer can run
# `pforge check` immediately post-install (parity with setup.ps1).
echo ""
cyan "Step 7c: CLI scripts"

for cli_file in "pforge.ps1" "pforge.sh" "pforge" "VERSION" "validate-setup.ps1" "validate-setup.sh"; do
    src_cli="$TEMPLATE_ROOT/$cli_file"
    dst_cli="$PROJECT_PATH/$cli_file"
    if [[ -f "$src_cli" ]]; then
        cp "$src_cli" "$dst_cli"
        green "  COPY  $cli_file"
    fi
done

# ─── Step 7d: Manage consumer .gitignore (Issue #211) ─────────────────
echo ""
cyan "Step 7d: .gitignore managed block"
pf_update_gitignore "$PROJECT_PATH"

# ─── Done ──────────────────────────────────────────────────────────────
echo ""
green "╔══════════════════════════════════════════════════════════════╗"
green "║                    Setup Complete!                          ║"
green "╚══════════════════════════════════════════════════════════════╝"
echo ""
cyan "Files installed to: $PROJECT_PATH"
echo ""
yellow "Next steps:"
echo "  1. Review .github/copilot-instructions.md — fill in project-specific details"
echo "  2. Review AGENTS.md — customize worker patterns for your app"
echo "  3. Review .vscode/settings.json — uncomment instruction file references"
echo "  4. Review .github/prompts/ — customize scaffolding recipes for your conventions"
echo "  5. Review .github/agents/ — tailor reviewer checklists for your project"
echo "  6. Review .github/skills/ — update build/deploy commands for your CI/CD"
echo "  7. Review docs/plans/DEPLOYMENT-ROADMAP.md — add your phases"
echo "  8. Read docs/COPILOT-VSCODE-GUIDE.md for Copilot Agent Mode workflow"
echo "  9. Start planning: open docs/plans/AI-Plan-Hardening-Runbook-Instructions.md"
echo ""
yellow "Optional (recommended):"
echo "  - Run .github/prompts/project-profile.prompt.md to generate project-specific guardrails"
echo "  - Run .github/prompts/project-principles.prompt.md to define project principles"
echo "  - Use .github/prompts/step0-specify-feature.prompt.md to define your first feature"
echo "  - Start your first plan the Crucible way: call forge_crucible_submit (MCP) — every plan ships with a crucibleId for full traceability"
echo "  - On GitHub? Run 'pforge github status' for a GitHub-native readiness check, or read /manual/plan-forge-on-the-github-stack.html"
echo ""

# ─── Step 7.5: OpenBrain L3 Memory Prompt (Phase-OPENBRAIN-PROMOTION Slice 4) ──
# Plan Forge ships with L1 (Hub) + L2 (.forge/*.jsonl) memory built in. The L3 layer
# — cross-session, cross-tool, semantic-search memory — requires OpenBrain. Optional
# but recommended. Prompt only fires in interactive TTY runs.
#
# Skip gates (any one suppresses the prompt):
#   - --non-interactive flag (NON_INTERACTIVE=true)
#   - $CI (set by GitHub Actions, GitLab CI, Azure DevOps, CircleCI, etc.)
#   - $PFORGE_NONINTERACTIVE (Plan Forge — internal automation flag)
#   - stdin is not a TTY ([ -t 0 ] is false)
if [[ "$NON_INTERACTIVE" == "true" ]] || [[ -n "${CI:-}" ]] || [[ -n "${PFORGE_NONINTERACTIVE:-}" ]] || [[ ! -t 0 ]]; then
    printf '\033[0;90m%s\033[0m\n' "i Skipping OpenBrain prompt (non-interactive / CI). Run 'pforge brain hint' anytime to revisit."
    echo ""
else
    cyan "================================================================"
    cyan " Recommended: Enable Persistent Memory (OpenBrain)"
    cyan "================================================================"
    echo ""
    echo "Plan Forge ships with L1 (Hub) + L2 (.forge/*.jsonl) memory."
    echo "The L3 layer — cross-session semantic memory that powers Reflexion"
    echo "lessons, Auto-skills, and cross-project Federation — requires"
    echo "OpenBrain, a self-hosted MCP server. Plan Forge works without it,"
    echo "but the inner loop only improves over time when L3 is present."
    echo ""
    OB_RESP=""
    read -rp "Show me OpenBrain install options? [Y/n/skip]: " OB_RESP || OB_RESP="skip"
    OB_RESP_LC="$(printf '%s' "$OB_RESP" | tr '[:upper:]' '[:lower:]')"

    case "$OB_RESP_LC" in
        n|no)
            echo ""
            yellow "!  Skipping. Reflexion / Auto-skills / Federation will be inert. Re-enable anytime with 'pforge brain hint'."
            echo ""
            ;;
        s|skip)
            echo ""
            printf '\033[0;90m%s\033[0m\n' "i Skipped. Re-enable anytime with 'pforge brain hint'."
            echo ""
            ;;
        *)
            # Empty or any other input → default Y branch.
            echo ""
            yellow "OpenBrain deploy options:"
            echo "  - Docker Compose       ~5 min   Free                Local dev / single machine"
            echo "  - Supabase Cloud       ~10 min  ~\$0.10-\$0.30/mo     Solo / small team, zero ops"
            echo "  - Kubernetes / Azure   ~30 min  Cloud rates         Teams, federation across repos"
            echo ""
            cyan "Full walkthrough:  https://srnichols.github.io/OpenBrain"
            printf '\033[0;90m%s\033[0m\n' "Source repo:       https://github.com/srnichols/OpenBrain"
            echo ""
            green "After installing, run 'pforge brain status' to confirm Plan Forge sees it."
            echo ""
            ;;
    esac
fi

# ─── Step 8: Auto-validate ─────────────────────────────────────────────
cyan "Running validation..."
validate_script="$TEMPLATE_ROOT/validate-setup.sh"
if [[ -f "$validate_script" ]]; then
    bash "$validate_script" --path "$PROJECT_PATH"
fi