prizmkit 1.1.39 → 1.1.41

package/bundled/skills/prizmkit-deploy/SKILL.md

@@ -1,214 +1,496 @@
 ---
 name: "prizmkit-deploy"
-description: "Generate or update .prizmkit/deploy.md with local dev setup, testing, production deployment, and rollback procedures. Can also supplement infrastructure config and execute deployments via SaaS CLI. On-demand skill — trigger when deployment docs are needed or user wants to deploy. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'deploy.md', 'deploy my app', 'help me deploy'. (project)"
+description: "Universal deployment gateway for any PrizmKit project. Discovers project type and target (SSH server, Vercel, Docker, etc.), then routes: full automation for SSH Linux with PM2 + Nginx + blue/green switching, guided setup for cloud platforms, or safe documentation fallback for unsupported targets. Also operates existing deployments: status, logs, restart, rollback, health checks, history. Trigger on: 'deploy', 'deploy my app', 'help me deploy', 'ship it', 'take this live', 'deploy to Vercel', 'deploy to my server', 'how do I deploy this', any deployment or hosting question."
 ---
 
-# PrizmKit Deploy
+# PrizmKit Deploy — Universal Deployment Gateway
 
-### When to Use
-- When the project has no deployment documentation yet
-- When new infrastructure components have been added (new database, cache, message queue, etc.)
-- When deployment-related configuration has changed significantly
-- When the user wants to supplement or update infrastructure config (database conventions, deployment settings) that was deferred during init or app-planner
-- When the user wants AI-assisted deployment execution
-- When explicitly requested by user or caller
-
-### When NOT to Use
-- When only application logic changed with no infra/config impact
-
-> **On-demand skill** — not part of the default `plan → implement → code-review → retrospective → committer` chain. Invoke independently when deployment documentation needs creation or update, or when user wants to deploy.
-
-### PRECONDITION
-- Project contains deployable artifacts (at least one of: `package.json`, `Dockerfile`, `Makefile`, `go.mod`, `Cargo.toml`, `pyproject.toml`, or equivalent)
-
-## Context Loading
-
-1. **Architecture context**: Read `.prizm-docs/root.prizm` → identify modules with deployment-relevant components (APIs, services, workers)
-2. **Project config**: Read `.prizmkit/config.json` for `deploy_strategy` and `tech_stack`
-   - If `.prizmkit/config.json` does not exist → proceed without it, infer from project file scanning. Log warning: "No .prizmkit/config.json found — inferring deployment strategy from project files."
-3. **Module detail**: Read relevant `.prizm-docs/<module>.prizm` L1/L2 for INTERFACES and DEPENDENCIES sections that inform deployment topology
-4. **Infrastructure config**: Read `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section for database conventions and deployment configuration collected by `prizmkit-init` or `app-planner`
-
-## Invocation Mode Detection
-
-This skill behaves differently depending on how it is invoked:
-
-- **User-invoked** (default): user calls `/prizmkit-deploy` directly → display current infrastructure config, allow modifications/supplements, then generate docs and optionally execute deployment
-- **Auto-invoked** (via pipeline or other skill, with `--auto` or `--pipeline` flag): use existing config from `CLAUDE.md` / `CODEBUDDY.md` and `.prizmkit/deploy.md` as-is, no interactive questions → generate/update docs only
-
-Pipeline launcher scripts pass the `--auto` flag automatically. If no flag is present, treat as user-invoked.
-
-## Execution Steps
-
-**Phase 0 — Configuration Check & Supplement** (user-invoked only — skip entirely if auto-invoked):
-
-1. Read `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section
-2. Read `.prizmkit/deploy.md` if it exists
-3. **Assess configuration completeness**:
-
-   **If `### Infrastructure` section is missing entirely**:
-   - Show: "No infrastructure configuration found. Let's set it up."
-   - Run full database inquiry + full deployment inquiry (see question pools below)
-
-   **If partial configuration exists** (some fields answered, some still deferred — e.g., database configured but `<!-- deployment: deferred -->` present):
-   - Display current config summary showing both answered and deferred items
-   - Run inquiry for deferred topics only, preserve existing answered items unchanged
-
-   **If `<!-- infrastructure: deferred -->` marker found**:
-   - Show: "Infrastructure configuration was deferred during project setup."
-   - Ask: "Would you like to configure it now?" (options: "Yes — configure now (Recommended)", "Skip — keep deferred")
-   - If yes → run full database inquiry + full deployment inquiry
-
-   **If `<!-- database: deferred -->` found**:
-   - Run database inquiry only
-
-   **If deployment section is missing or `<!-- deployment: deferred -->`**:
-   - Run deployment inquiry only
-
-   **If both sections exist with real values**:
-   - Display current config summary
-   - Ask: "Would you like to update any infrastructure settings?" (options: "Looks good — proceed (Recommended)", "Update database config", "Update deployment config", "Update both")
-
-4. **Database inquiry** (same question pool as app-planner — AI selects relevant questions):
-   - Table naming convention (snake_case / camelCase / PascalCase, prefix)
-   - Field naming convention (common fields: created_at, updated_at, deleted_at)
-   - Migration conventions (directory, naming rule, migration tool)
-   - Primary key strategy (auto-increment / UUID / ULID / Snowflake)
-   - Index naming convention
-   - Environment separation (dev/test/prod, connection config)
-
-5. **Deployment inquiry** (same question pool as app-planner — AI selects relevant questions):
-   - Deployment target refinement (own server details / SaaS platform / container orchestration)
-   - Existing infrastructure (remote machines, CI/CD, domain, SSL)
-   - AI-assisted deployment (whether AI should execute deploy commands, credentials info)
-   - Environment variable management strategy
-
-6. **Write results**:
-   - Update `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section — replace `<!-- deferred -->` markers with real values, preserve unchanged values
-   - Update `#### Deployment Credentials Reference` section if new auth methods were collected during inquiry
-   - Update `.prizmkit/deploy.md` with new information
-
-**Phase 1 — Project Scanning:**
-1. Scan project for deployment-related files:
-   - Container: `Dockerfile`, `docker-compose.yml`, `.dockerignore`
-   - Cloud platforms: `vercel.json`, `netlify.toml`, `fly.toml`, `app.yaml` (GCP), `appspec.yml` (AWS)
-   - CI/CD: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`
-   - Package managers: `package.json` scripts (start, build, preview), `Makefile`, `Procfile`
-   - Infrastructure as Code: `terraform/`, `pulumi/`, `cdk/`, `serverless.yml`
-2. Scan source code for environment variable references:
-   - Grep for `process.env.`, `os.environ`, `os.Getenv`, `env::var`, `System.getenv`
-   - Cross-reference with `.env.example`, `.env.template`, or `.env.sample` if they exist
-   - Catalog all env vars with their usage context
-3. Check for existing `.prizmkit/deploy.md`
-4. If `.prizmkit/deploy.md` exists → use `git log` to identify infra changes since last update; otherwise treat all infrastructure as "new"
-
-**Phase 2 — Document Generation:**
-5. If NO existing deploy doc:
-   - Generate `.prizmkit/deploy.md` from template (`${SKILL_DIR}/assets/deploy-template.md`)
-   - Fill all sections based on scanned project state
-   - If `deploy_strategy` exists in config → use it as the authoritative deployment approach
-   - If `deploy_strategy` is absent → infer from detected files (Dockerfile → Docker-based, vercel.json → Vercel, etc.) and note "Inferred from project files"
-6. If existing deploy doc found:
-   - Compare current project state against documented state
-   - Identify gaps: new env vars not documented, new services not covered, outdated commands
-   - Apply incremental updates — preserve user-written sections, only add/update auto-detectable content
-   - Mark updated sections with `<!-- Updated by prizmkit-deploy -->` comment
-
-**Phase 3 — Validation:**
-7. Verify completeness checklist:
-   - [ ] All detected env vars are documented with descriptions
-   - [ ] Local development setup commands are runnable (check referenced scripts/commands exist)
-   - [ ] Build command documented and exists in package.json/Makefile
-   - [ ] Production deployment steps match `deploy_strategy` in config (if configured)
-   - [ ] Health check or verification step is included
-8. If any checklist item fails, add a `## TODO` section at the bottom listing what needs manual completion
-9. If interactive session is available → show summary and ask if user wants to review before finishing
-10. Output: `.prizmkit/deploy.md` path, summary of sections generated/updated, list of TODOs if any
-
-**Phase 4 — Deployment Execution** (conditional):
-
-**Trigger**: Read `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` → `#### Deployment` → `**AI-assisted deploy**` field. Only execute this phase if the value is `yes`.
-
-If `AI-assisted deploy` is `no` or not present → skip Phase 4 entirely, proceed to HANDOFF.
-
-**Execution flow**:
-
-1. **Read deployment config** from `.prizmkit/deploy.md` (Production Deployment section, Platform-Specific Deploy Commands section, AI Deploy Playbook section)
-2. **Build command sequence** based on the deployment target:
-
-   | Target | Command Sequence |
-   |--------|-----------------|
-   | Vercel | `vercel --version` → `vercel deploy --prod` |
-   | Railway | `railway --version` → `railway up` |
-   | Fly.io | `fly version` → `fly deploy` |
-   | Docker + registry | `docker build -t {tag} .` → `docker push {tag}` |
-   | Docker + SSH | `docker build -t {tag} .` → `docker save` → `scp` → `ssh docker load && docker run` |
-   | Custom | Read custom commands from deploy.md |
-
-3. **Pre-flight checks**:
-   - Verify CLI tools are installed (run version commands)
-   - Verify authentication (check if logged in to the platform)
-   - If auth missing: show instructions for how to authenticate (e.g., "Run `vercel login` or set `VERCEL_TOKEN` env var") and stop
-
-4. **Execute with user confirmation** (safety mechanism):
-   - Display the full command list to the user before executing anything
-   - Ask: "Ready to execute these deployment commands?" (options: "Yes — execute step by step", "Let me review first", "Cancel")
-   - Execute one command at a time:
-     - Show the command about to be executed
-     - Wait for user confirmation (implicit: proceed; explicit: user can say "skip" or "stop")
-     - Execute the command
-     - Show output (stdout + stderr)
-     - If command fails → **stop immediately**, show error details, suggest remediation
-     - If command succeeds → proceed to next command
-   - **Sensitive operations**: if a command involves API tokens, secrets, or irreversible actions (e.g., production database migration), add an explicit warning and require user to type confirmation
-
-5. **Post-deployment verification**:
-   - If Health Check section exists in deploy.md → run the health check commands
-   - Show deployment result summary: success/failure, URL (if SaaS platform returns one), any warnings
-
-6. **Output**: Deployment execution report — commands executed, results, any errors encountered
-
-**HANDOFF:** `/prizmkit-committer` — commit changes including `.prizmkit/deploy.md`.
-
-## Document Sections
-
-The generated deploy doc includes these sections (skip any that don't apply to the project):
-
-| Section | Content | Source |
-|---------|---------|--------|
-| Prerequisites | Required tools, versions, accounts | `tech_stack` from config + detected tooling |
-| Environment Variables | Full list with descriptions and examples | Source code scan + `.env.example` |
-| Local Development | Clone, install, configure, run locally | `package.json` scripts, `Makefile`, `docker-compose` |
-| Testing | Run tests locally, staging test procedures | `tech_stack.testing` + test scripts |
-| Build | Build commands and output artifacts | Build tool config (Vite, Webpack, Go build, etc.) |
-| Production Deployment | Step-by-step deployment procedure | `deploy_strategy` from config |
-| CI/CD | Pipeline overview and trigger conditions | Detected CI/CD config files |
-| Rollback | How to revert a bad deployment | Inferred from deployment method |
-| Health Check | How to verify deployment succeeded | API routes, health endpoints, smoke tests |
-| Troubleshooting | Common deployment issues and fixes | Generated from known patterns per tech stack |
-
-## Incremental Update Rules
-
-When updating an existing `.prizmkit/deploy.md`:
-- **NEVER delete** user-written content (sections without `<!-- Updated by prizmkit-deploy -->` markers)
-- **ADD** newly detected env vars to the Environment Variables table
-- **ADD** new services/components to Production Deployment
-- **UPDATE** version numbers and commands if they changed in config files
-- **APPEND** new troubleshooting entries for newly added tech stack components
-- **PRESERVE** custom sections the user may have added (e.g., team-specific procedures)
-
-## Example
-
-**Input state:**
-- `config.json` has `deploy_strategy: { primary: "docker", components: { app: "Docker → AWS ECS", db: "RDS PostgreSQL" } }`
-- Project has `Dockerfile`, `docker-compose.yml`, `package.json` with build script
-- 12 env vars detected in source code, `.env.example` has 8
-
-**Output:** `.prizmkit/deploy.md` with all sections filled, plus TODO:
-```
-## TODO
-- [ ] 4 environment variables found in code but missing from `.env.example`: `REDIS_URL`, `SMTP_HOST`, `SMTP_PORT`, `SENTRY_DSN`
-- [ ] No health check endpoint detected — consider adding `GET /health`
-```
-
-IMPORTANT: Use `${SKILL_DIR}` placeholder for all path references. Never hardcode absolute paths.
+`/prizmkit-deploy` is the single entry point for all deployment work. When a user asks to deploy anything — any project type, any target — this skill handles it.
+
+Three possible outcomes depending on what's supported:
+1. **Full automation** (SSH Linux server): configure, bootstrap, deploy, verify, operate — complete AI takeover.
+2. **Guided setup** (cloud platforms like Vercel, Netlify, Docker): generate config, walk through CLI steps, verify.
+3. **Documented fallback** (unsupported targets): detect what's possible, produce deploy.md, record the adapter gap.
+
+When invited, behave as a deployment engineer. Ask until you understand what is being deployed, where it runs, how it is built, how it starts, what secrets it needs, how traffic reaches it, and how health is checked.
+
+## Deployment Discovery
+
+Before doing anything else, discover what you're deploying and where. This phase routes the request to the right adapter or fallback. It runs regardless of mode (interactive or headless), but interactive mode may ask questions; headless mode reads from existing config and exits with `NEEDS_INPUT` if critical details are missing.
+
+### Step 1: Project Detection
+
+Scan the project root for build/package files and classify:
+
+| File found | Language/Framework | Build command | Start command |
+|------------|-------------------|---------------|---------------|
+| `package.json` with `next` dep | Next.js | `next build` | `next start -p <port>` |
+| `package.json` with `vite` dep | Vite (React/Vue) | `vite build` | `vite preview` |
+| `package.json` (generic) | Node.js | `npm run build` | `npm run start` |
+| `go.mod` | Go | `go build` | `./<binary>` |
+| `Cargo.toml` | Rust | `cargo build --release` | `./target/release/<binary>` |
+| `requirements.txt` / `pyproject.toml` | Python | — | `python -m uvicorn` or similar |
+| `Dockerfile` | Containerized | `docker build` | `docker run` |
+| `docker-compose.yml` | Docker Compose | `docker compose build` | `docker compose up` |
+| `Makefile` only | C/C++/generic | `make` | `make run` or binary |
+
+Also scan for:
+- **Environment variables**: grep for `process.env.`, `os.environ`, `os.Getenv`, `env::var` — catalog every reference
+- **Port usage**: grep for port numbers, `listen()`, `PORT` env var
+- **Database dependencies**: check package.json/requirements.txt/go.mod for database drivers
+
+### Step 2: Deployment Target Detection
+
+Determine WHERE the user wants to deploy. Check in order:
+
+**A. User-specified target** (highest priority):
+- "deploy to Vercel" / "deploy to my server" / "deploy with Docker" → use what the user says.
+
+**B. Detect from project files** (if user hasn't specified):
+- `vercel.json` → Vercel
+- `netlify.toml` → Netlify
+- `fly.toml` → Fly.io
+- `Dockerfile` or `docker-compose.yml` → Docker
+- `.github/workflows/deploy.yml` → check what it targets
+- `app.yaml` → GCP App Engine
+- `serverless.yml` → Serverless Framework
+
+**C. Ask the user** (interactive only):
+- "Where should this project be deployed?"
+- Options to suggest based on detected files + common choices:
+  - "My own Linux server (SSH access) — full AI automation"
+  - "Vercel / Netlify — guided CLI setup"
+  - "Docker — guided container deployment"
+  - "Other — generate deployment documentation"
+
+If headless mode and no target can be determined, exit with `NEEDS_INPUT` listing the missing target information.
+
+**D. Check for existing deployment**:
+- Does `.prizmkit/deploy/deploy.config.json` already exist? If yes, read the configured target.
+- Does the user mention a server IP or hostname? Check if it's already reachable.
+
+### Step 3: Route to Adapter
+
+Based on detected target, route the rest of the session:
+
+```
+SSH Linux server  → §SSH Deployment Path (full automation)
+                     bootstrap, configure, deploy, operate
+                     First-version: PM2 + Nginx + blue/green
+
+Vercel / Netlify  → §Cloud Platform Deployment Path (guided)
+                     detect CLI tools, walk through deploy commands,
+                     generate deploy.md with platform-specific steps
+
+Docker            → §Docker Deployment Path (guided)
+                     detect Dockerfile/Compose, build image,
+                     container lifecycle (run, stop, logs, restart)
+
+Unsupported       → §Unsupported Deployment Fallback
+                     generate deploy.md with detected info,
+                     record missing adapter gap,
+                     provide manual deployment checklist
+```
+
+The SSH path is fully documented in the sections below. Cloud and Docker paths follow the same discovery and documentation patterns but use platform CLIs instead of SSH + PM2.
+
+**Compatibility check before routing to SSH**: The SSH adapter (PM2 + Nginx + blue/green) requires a Node.js project — verify `package.json` exists. Non-Node.js projects (Go, Rust, Python) targeting a Linux server route to Unsupported Fallback with a note: "Adapter gap: PM2 adapter requires Node.js."
+
+### Step 4: Unsupported Deployment Fallback
+
+When the deployment target or project type isn't covered by any adapter, don't fail silently. Instead:
+
+1. **Detect what you can**: project language, framework, build/start commands, env vars, port usage, database dependencies.
+2. **Generate `.prizmkit/deploy/deploy.md`**: human-readable deployment guide with:
+   - Prerequisites (tools, accounts, versions)
+   - Environment variables table (detected from code scan)
+   - Build and start instructions
+   - Health check suggestions
+   - Platform-specific tips if the target is partially recognized
+3. **Record the adapter gap**: write a note in deploy.md and deploy-history identifying what's missing (e.g., "Adapter needed: Python/FastAPI on systemd", "Adapter needed: Go binary deployment").
+4. **Provide a manual checklist**: concrete steps the user can follow to deploy manually.
+5. **Offer to generate CI/CD config**: if `.github/workflows/` exists or the user wants one, generate a basic deploy workflow.
+
+This ensures every deployment request produces useful output, even when full automation isn't available yet.
+
+## Mode Detection
+
+Detect invocation mode from the user's initial message. The mode determines what you're allowed to do:
+
+**Interactive mode** (user typed `/prizmkit-deploy` or asked directly):
+- May ask as many questions as needed to fill in missing deployment details.
+- May request approvals for privileged, destructive, or traffic-impacting actions.
+- May deploy to any environment (dev/test/production).
+- Production requires explicit user confirmation before execution.
+
+**Headless mode** (invoked via `--headless` flag, pipeline, or script):
+- Must never wait for user input or prompt — unattended shells timing out on a prompt blocks pipelines silently.
+- May ONLY target `dev` or `test` environments.
+- If `--env production` in headless mode: exit immediately with `ENVIRONMENT_DENIED — production deployment requires interactive mode`.
+- If required info is missing, exit with `NEEDS_INPUT` and write pending questions to `.prizmkit/deploy/pending-input.json`.
+- May only perform actions already authorized by `deploy.config.json`.
+
+## Command Routing
+
+When the user invokes `/prizmkit-deploy`, determine intent from the first word after the command:
+
+```
+/prizmkit-deploy                  → deploy (if config exists) or configure (if not)
+/prizmkit-deploy configure        → first-run or repair configuration wizard
+/prizmkit-deploy deploy           → full deployment pipeline
+/prizmkit-deploy status           → show PM2 process status for all apps
+/prizmkit-deploy logs --app <id>  → tail PM2 logs for the given app
+/prizmkit-deploy restart --app <id> → PM2 restart for the given app
+/prizmkit-deploy rollback --app <id> [--to <releaseId>] → rollback to previous or specified release
+/prizmkit-deploy health --app <id> → run configured health checks
+/prizmkit-deploy history          → list recent deployment events from deploy-history/
+/prizmkit-deploy validate         → run validation checks without deploying
+```
+
+### No-arg behavior
+
+- If `.prizmkit/deploy/deploy.config.json` does not exist → start first-run configuration wizard.
+- If config exists and validates → show deployment summary (active release, app status, last deploy time) and ask which environment, then proceed to deploy.
+- If config exists but required fields are missing or validation is stale → enter repair flow.
+
+## File Structure
+
+All artifacts live under `.prizmkit/deploy/`:
+
+```
+.prizmkit/deploy/
+  deploy.md                          # human-readable documentation
+  deploy.config.json                 # machine-readable config & validation state
+  pending-input.json                 # pending questions for headless mode resume
+  deploy-history/
+    <deployment-id>.json             # one per deploy/rollback/event
+  deploy-scripts/                    # future — currently unused, place for PrizmKit-managed deploy scripts and templates
+  secrets.enc.json                   # optional, encrypted local secrets
+  secrets.local.json                 # optional, plaintext secrets (must be gitignored)
+```
+
+The full `deploy.config.json` schema is documented in `references/deploy-config-schema.md`. Read it when writing or validating config.
+
+## SSH Deployment Path (Full Automation)
+
+The following sections — Server Model through Multi-App Coordination — define the SSH deployment adapter. This is the only fully-automated path in the first version. Route here when Discovery determines the target is a Linux server with SSH access.
+
+### SSH: Server Model
+
+Servers are generic SSH targets. A server is valid if it:
+- Can be reached over SSH.
+- Provides a Linux shell.
+- Can install or has Node.js, npm, PM2, Nginx, Git.
+- Can access the configured Git repository.
+
+Server-side directory layout:
+```
+/var/www/<project>/
+  releases/
+    <release-id>/
+  shared/
+    .env.production          # mode 600, owner: runtime user
+    deploy-metadata.json     # active color, last release, timestamp
+  current -> releases/<release-id>
+  deploy-logs/
+```
+
+SSH roles: `bootstrapUser` (usually root, for initial setup) and `runtimeUser` (default `deploy`, for app processes). App processes never run as root.
+
+### SSH: First-Run Configuration Wizard
+
+When `.prizmkit/deploy/deploy.config.json` does not exist, enter configuration wizard. The flow is: **collect → validate → confirm → persist**.
+
+#### Step 1: SSH Server Discovery
+
+Ask for and validate:
+- **Server host and port** (e.g., `43.161.221.171:22`)
+- **Bootstrap user** (usually `root`) — used for initial package install and user creation
+- **Runtime user** (recommend `deploy`) — app runs as this user, never root
+- **Auth method** — SSH key path or agent
+
+Validate immediately: `ssh <bootstrapUser>@<host> 'echo OK'`. If that fails, nothing else matters — stop and fix connectivity first.
+
+#### Step 2: Repository Access
+
+Ask for and validate:
+- **Git URL** (e.g., `git@github.com:owner/repo.git`)
+- **Branch** (e.g., `master`)
+- **Auth strategy** — prefer read-only Deploy Key
+
+If using Deploy Key:
+1. Generate ed25519 key on server: `sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""`
+2. Show the public key to the user with explicit instruction: "Add this to GitHub Deploy Keys (read-only)"
+3. Wait for user confirmation, then verify: attempt a git clone as runtime user
+
+#### Step 3: Application Configuration
+
+For each app, collect:
+- **id** — short name (e.g., `web`)
+- **path** — relative path within repo
+- **packageManager** — npm / yarn / pnpm
+- **installCommand** — `npm ci` / `yarn install` etc.
+- **buildCommand** — `npm run build` etc.
+- **startCommand** — `npm run start` etc.
+- **ports** — blue/green port pair (default 3101/3102)
+- **healthChecks** — list of `{ name, url, expectedStatus[] }`
+
+#### Step 4: Environment Variables
+
+- Scan source code for `process.env.<VAR>` references.
+- Ask user for each required value.
+- Identify which are secrets (API keys, tokens) vs. non-secrets (URLs, anon keys).
+- Ask about secret storage strategy (see Secrets Management below).
+
+#### Step 5: Persist Configuration
+
+Write `deploy.config.json` with all collected values and `validated: {}` stubs for each section. Write `deploy.md` as human-readable documentation.
+
+### SSH: Bootstrap Flow
+
+Before first deployment, bootstrap the server. Present a plan to the user showing every privileged action before executing anything.
+
+**Always-run preflight:**
+```
+locale-gen en_US.UTF-8           # fix locale warnings on bare Ubuntu
+apt-get update -qq               # refresh package list
+```
+
+**Check-and-install (idempotent):**
+- **Node.js**: check `node --version`. If missing or too old, install via NodeSource. Use v22 LTS if v25 not available — that's fine for most projects.
+- **npm**: verify separately from node (`which npm`). On minimal installs, npm may be a separate package.
+- **PM2**: `npm install -g pm2` if missing.
+- **Nginx**: `apt-get install -y nginx` if missing.
+- **Git**: `apt-get install -y git` if missing.
+
+**Detect port conflicts before starting Nginx:**
+```
+ss -tlnp | grep :80 || true
+```
+If port 80/443 is occupied, report what's using it and ask how to resolve.
+
+**User and directory setup:**
+```
+useradd -m -s /bin/bash <runtimeUser>   # if not exists
+mkdir -p /var/www/<project>/{releases,shared,deploy-logs}
+chown -R <runtimeUser>:<runtimeUser> /var/www/<project>
+```
+
+**PM2 startup:**
+```
+env PATH=$PATH:/usr/bin pm2 startup systemd -u <runtimeUser> --hp /home/<runtimeUser>
+```
+
+**Deploy key (if strategy is deploy-key):**
+```
+sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
+sudo -u <runtimeUser> ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+```
+
+After each bootstrap step, record the result. Bootstrap operations must be idempotent. Back up any existing config files before modifying them.
+
+### SSH: Deployment Execution Flow
+
+Pipeline runs in strict order. Each group must complete before the next begins. If any step before traffic switch fails, STOP — do not touch the live version.
+
+**Group 1 — Pre-flight & Prepare:**
+- Verify SSH, runtime user, tools, deploy key, port availability.
+- Generate `releaseId`: `YYYYMMDD-<short-commit-sha>`. Create `releases/<releaseId>`.
+- Determine target color: read `activeColor` from `shared/deploy-metadata.json` and use the opposite. If first deploy (no metadata, no `current` symlink), default to blue (port 3101).
+
+**Group 2 — Fetch & Build:**
+- `git clone <repoUrl> --branch <branch> releases/<releaseId>` as runtime user.
+- `cd releases/<releaseId> && <installCommand>` as runtime user.
+- Copy `.env.production` from `shared/` into release dir BEFORE build — `NEXT_PUBLIC_*` vars are baked at build time.
+- Run `<buildCommand>`. If build fails: STOP.
+
+**Group 3 — Stage & Health Check:**
+- Start new version on the inactive port via PM2: `pm2 start npm --name <project>-<app>-<color> -- run start -- -p <inactivePort>`.
+- PM2 process naming: `<project>-<app>-<color>` (e.g., `prizm-ideas-web-green`).
+- Wait 3-5 seconds, run health checks against new port. If any fails: STOP. Do NOT switch traffic. Record failure.
+
+**Group 4 — Switch & Verify:**
+- Update Nginx upstream to new port. Run `nginx -t` — abort on failure.
+- `systemctl reload nginx`. Update `current` symlink to new release.
+- Write `shared/deploy-metadata.json` with new `activeColor`, `activePort`, `lastReleaseId`.
+- Run health checks against public endpoint. If any fails: rollback immediately (switch Nginx back, restart old PM2).
+
+**Group 5 — Cleanup & Record:**
+- Stop old PM2 process. Remove oldest releases beyond `releaseRetention` count. `pm2 save`.
+- Write deploy-history JSON to `.prizmkit/deploy/deploy-history/<releaseId>.json` (schema: `references/deploy-history-schema.md`).
+- Update `deploy.config.json` with new validation status.
+
+### SSH: Blue/Green PM2 + Nginx Strategy
+
+The active color (blue or green) maps to a port:
+- Blue: port 3101 (default)
+- Green: port 3102 (default)
+
+Active color is persisted in `/var/www/<project>/shared/deploy-metadata.json`. If metadata is missing, rediscover from Nginx `proxy_pass` directive or from running PM2 processes.
+
+PM2 process naming: `<project>-<app>-<color>` (deterministic, never reuse old release IDs in names).
+
+Nginx config must include the PrizmKit managed marker:
+```
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+```
+
+Before modifying any Nginx config that lacks this marker, ask for user confirmation.
+
+Always `nginx -t` before `systemctl reload nginx`. If syntax check fails, abort.
+
+### SSH: Rollback
+
+Two rollback triggers:
+1. **Automatic**: health check failure after traffic switch → roll back immediately.
+2. **Manual**: `/prizmkit-deploy rollback --app <id> [--to <releaseId>]`
+
+Rollback steps:
+1. Identify target release: `--to <releaseId>` or discover previous release from deploy history.
+2. Verify target release directory exists and has a valid build.
+3. Determine which port the target release used (from deploy history or release metadata).
+4. Start the target PM2 process on its port (if not already running).
+5. Update Nginx upstream to target port, run `nginx -t`, reload.
+6. Run health checks against the restored version.
+7. Write a rollback event to deploy history.
+8. Do NOT delete the failed release or its logs — preserve for debugging.
+
+If no previous release exists (first deployment), rollback is not possible — state this clearly.
+
+### SSH: Operations Commands
+
+#### status
+SSH to server and run `pm2 list` as runtime user. Also show:
+- Active release (from `current` symlink target)
+- Active color/port (from `deploy-metadata.json`)
+- Last deploy timestamp
+
+#### logs --app <id>
+SSH to server and run `pm2 logs <process-name> --lines 100` as runtime user.
+
+#### restart --app <id>
+1. Identify the active PM2 process for the app.
+2. Run `pm2 restart <process-name>` as runtime user.
+3. Wait for process to come online.
+4. Run health checks to verify recovery.
+
+#### health --app <id>
+Run all configured health checks for the app against the public endpoint. Report pass/fail for each.
+
+#### history
+Read `.prizmkit/deploy/deploy-history/` directory, list events chronologically. Show event type, release ID, commit SHA, timestamp, status.
+
+## Environment Policy
+
+| Mode | dev | test | production |
+|------|-----|------|------------|
+| Interactive | Allowed | Allowed | Allowed (requires confirmation) |
+| Headless | Allowed | Allowed | **REJECTED** — exits with ENVIRONMENT_DENIED |
+
+This is non-negotiable. Even if config allows it, headless must reject production.
+
+## Secrets Management
+
+Four storage modes, configured during first-run wizard:
+
+- **ask-every-time**: Prompt for secrets on each deploy. Safest, most manual.
+- **encrypted-local**: Store in `.prizmkit/deploy/secrets.enc.json`. Encrypt with user passphrase using Argon2id/scrypt KDF. Decryption material never stored alongside ciphertext.
+- **plaintext-local**: Store in `.prizmkit/deploy/secrets.local.json`. Must be gitignored. Before each deploy, verify the file is not tracked by git. If tracked, stop and ask to resolve.
+- **user-managed-on-server-only**: User handles secrets manually. Skill verifies server-side `.env.production` has all required vars before deploying.
+
+Server runtime secrets live in `/var/www/<project>/shared/.env.production` with mode `600`, owned by runtime user.
+
+Deploy history records secret presence metadata only (e.g., `{"SUPABASE_SERVICE_ROLE_KEY": {"present": true}}`). Never record raw secret values or unsalted hashes.
+
+### SSH: Existing Deployment Takeover
+
+When deploying to a server that already has deployment assets:
+
+1. Detect: existing `/var/www/<project>` directory, existing PM2 processes with similar names, Nginx config referencing the same domain/IP, port conflicts.
+2. Report findings to the user and ask for takeover decision:
+   - **Take over and backup**: Back up existing config, then proceed.
+   - **Coexist**: Use different directory/ports/process names.
+   - **Manual resolve**: Stop and let the user handle it.
+3. Record takeover decision and validation results in config and history.
+
+### SSH: Nginx Management
+
+- First Nginx config creation or update of a non-PrizmKit block requires user confirmation.
+- Subsequent updates to PrizmKit-managed blocks (`# PrizmKit Managed:` marker) may proceed automatically.
+- Managed marker format: `# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY`
+- Always run `nginx -t` before reload.
+- If a server block exists without the managed marker, ask before modifying.
+
+See `references/nginx-blue-green.md` for the full Nginx config template, traffic switch procedure, and active port rediscovery technique.
+
+### SSH: Bootstrap Safety Rules
+
+Before executing privileged bootstrap work, generate an action plan listing:
+- Packages to install/upgrade
+- Users/groups to create/modify
+- SSH keys to create
+- Nginx config to create/modify
+- Directories and permissions to change
+- Services that may be restarted
+
+Execution rules:
+- User gives one explicit approval for the entire bootstrap plan.
+- If the plan changes during execution, pause and ask again.
+- Bootstrap operations must be idempotent.
+- Existing config files must be backed up before modification.
+- All privileged actions and results recorded in deploy history.
+- Failed bootstrap stops before deployment, provides recovery instructions.
+
+### SSH: Multi-App Coordination
+
+An all-app deploy creates one release group. Rules:
+- Pre-traffic phases (fetch, install, build, stage) must complete for ALL selected apps before ANY app switches traffic.
+- If any app fails before traffic switch, NO app switches traffic. Staged processes are stopped, live system unchanged.
+- If any app fails after traffic switch, default: group rollback (all apps in the release group roll back).
+- Single-app deploys (`--app <id>`) do not affect unrelated apps.
+
+## Validation
+
+Validation is mandatory before production deploy. Check:
+- SSH connectivity and user permissions
+- Required tools present (node, npm, git, pm2, nginx)
+- Repository reachability and branch existence
+- Ports availability
+- Required env vars present
+- Nginx config syntax
+- Health check routes accessible
+
+Persist validation in `deploy.config.json` under each section's `validated` field.
+
+## Adapter Paths
+
+After Discovery routes to a deployment target, read the corresponding reference file for execution details:
+
+| Target | Reference | Mode |
+|--------|-----------|------|
+| SSH Linux server | SSH sections below (Server Model through Multi-App) | Full automation |
+| Vercel, Netlify, Fly.io | `references/cloud-platform-deploy.md` | Guided CLI |
+| Docker / Docker Compose | `references/docker-deploy.md` | Guided build + run |
+| Unrecognized target | Deployment Discovery Step 4 | Documented fallback |
+
+The SSH path is documented inline below because it is the fully-automated adapter and the model needs its instructions in every SSH deployment session. Cloud and Docker paths are in references because they're loaded only when Discovery routes to them.
+
+## Deploy History Record Schema
+
+Each deployment, rollback, or significant event writes a record to `.prizmkit/deploy/deploy-history/<id>.json`. The full schema is in `references/deploy-history-schema.md` — read it when writing history records.
+
+Never record raw secret values in history — presence metadata only.
+
+## Implementation Notes from Live Validation
+
+These findings from PrizmIdeas first deployment should guide your behavior:
+
+1. **Detect port conflicts before installing Nginx.** Check what's on port 80/443 and ask before stopping anything.
+2. **Verify npm separately from node.** Minimal Node installs may not bundle npm.
+3. **Fix locale on bare Ubuntu.** Run `locale-gen en_US.UTF-8` early to avoid perl warnings in apt.
+4. **Deploy key workflow is inherently interactive.** Generate key → wait for user to add to GitHub → verify. Headless mode cannot complete this.
+5. **`pm2 startup` needs explicit PATH.** Always use `env PATH=$PATH:/usr/bin pm2 startup ...`.
+6. **Persist deploy metadata on server.** Write `activeColor`, `activePort`, `lastReleaseId`, `lastDeployTimestamp` to `shared/deploy-metadata.json`.
+7. **Detect first deployment.** If no `current` symlink and no PM2 process for the app, skip rollback safety checks and use blue (3101) as initial color.
+8. **Build-time env vars.** Copy `.env.production` before `npm run build`, not after. `NEXT_PUBLIC_*` vars are baked at build time.
+9. **Node.js version flexibility.** Default to v22 LTS if v25 is unavailable. Most frameworks tolerate a minor version diff.