prizmkit 1.1.111 → 1.1.113

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

@@ -1,444 +1,225 @@
 ---
 name: "prizmkit-deploy"
-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, validate. Use this skill whenever the user asks about deployment, hosting, going live, or server operations. Triggers on: 'deploy', 'ship it', 'take this live', 'deploy to Vercel', 'deploy to my server', 'check deploy status', 'view logs', 'restart app', 'rollback', 'how do I deploy this', any deployment or hosting question. (project)"
+description: "Universal deployment gateway for PrizmKit projects. Discovers project type and deployment target, then routes to SSH Linux automation, cloud platform guidance, Docker guidance, or documented fallback. Also operates existing deployments: status, logs, restart, rollback, health, history, and validate. Use whenever the user asks to deploy, host, go live, release, take live, check deployment status, view logs, restart, rollback, or troubleshoot server operations. If the user says only 'ship it', clarify whether they mean commit or deploy before invoking. (project)"
 ---
 
 # PrizmKit Deploy — Universal Deployment Gateway
 
-`/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.
+`/prizmkit-deploy` is the deployment and operations entry point. It discovers what is being deployed, where it should run, and which adapter or fallback applies.
 
-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.
+Possible outcomes:
 
-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.
+1. **Full automation** — SSH Linux server for supported Node.js apps using PM2 + Nginx blue/green.
+2. **Guided setup** — cloud platforms or Docker where user CLI/account steps are required.
+3. **Documented fallback** — unsupported project/target combinations get deploy documentation and an adapter-gap record.
 
 ### When to Use
-- User says "deploy", "ship it", "take this live", "deploy to Vercel", "deploy to my server"
-- User wants to check deploy status, view logs, restart app, rollback
-- First-time deployment configuration or repair
+- User says "deploy", "go live", "take this live", "release", "deploy to Vercel", "deploy to my server"
+- User wants deploy status, logs, restart, rollback, health checks, history, or validation
+- First-time deployment configuration or existing deployment repair/takeover
 - Any deployment, hosting, or server operation question
 
 ### When NOT to Use
-- Project has no code to deploy (empty/scaffold project)
-- Local dev environment startup — use the project's dev scripts instead
-- Purely CI/CD pipeline debugging unrelated to deployment
-- User wants to edit application code — use /prizmkit-plan and /prizmkit-implement
+- User says only "ship it" — clarify commit vs deploy first
+- Local development startup — use project dev scripts or `/run`
+- Pure CI test failure unrelated to deployment
+- User wants application code changes — use `/prizmkit-plan` and `/prizmkit-implement`
 
 ## Data Safety Gate
 
-Before executing any command that could **irreversibly destroy, overwrite, or modify data**, pause and get explicit user confirmation. This is a hard gate — the cost of a false negative (losing real data) is catastrophic, while asking one extra question costs nothing.
+Before executing any command that could irreversibly destroy, overwrite, or modify data, pause and get explicit user confirmation.
 
-### Detection
+Danger signals:
 
-Before running any shell command, scan it for these patterns:
+| Category | Examples | Action |
+|---|---|---|
+| Database reset/loss | `prisma migrate reset`, `DROP TABLE`, `TRUNCATE`, broad `DELETE`/`UPDATE` | Explain data loss and require clear yes/no confirmation |
+| File/system overwrite | `rm -rf`, writes under `/etc/`, overwriting existing config without backup | Confirm and back up when applicable |
+| Cloud/resource deletion | `terraform destroy`, `kubectl delete`, bucket/resource deletion | Confirm exact resources and impact |
+| Production traffic switch | first production deploy, rollback, Nginx upstream change | Confirm target environment and rollback plan |
 
-| Category | Dangerous patterns | What's at risk |
-|----------|-------------------|----------------|
-| Database schema | `prisma db push --force-reset`, `prisma db push --accept-data-loss`, `prisma migrate reset`, `prisma migrate dev --create-only` | All existing data dropped, schema reset |
-| Database data | `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, `DELETE FROM` without `WHERE`, `UPDATE` without `WHERE` | Data deletion or corruption |
-| File system | `rm -rf`, `> /etc/`, overwriting existing configs without backup | Config loss, system breakage |
-| Cloud resources | `terraform destroy`, `kubectl delete`, cloud resource deletion, S3 bucket removal | Infrastructure/service loss |
+If a destructive data operation is detected in headless mode, refuse with `DATA_SAFETY_DENIED`; unattended pipelines must not destroy data.
 
-### Confirmation Flow
+Read `${SKILL_DIR}/references/data-safety-examples.md` when concrete examples are needed.
 
-When a dangerous pattern is detected:
+## Discovery
 
-1. **Stop.** Do not execute. Do not ask "should I proceed?" while already running the command.
-2. **Explain** what the command will do and what data will be lost, in plain language.
-3. **Ask** an explicit yes/no question. Accept only a clear "yes" or equivalent — ambiguous responses ("sure, I guess", "ok go ahead") count as "no" when the consequence is data loss.
-4. **Only proceed** on unambiguous consent. If the user says anything other than a clear affirmative, abort.
-5. **Record** the confirmation decision and the command that was run in deploy history.
+Before deploying, discover project and target.
 
-### Headless Mode
+### Project Detection
 
-If a destructive data operation is detected in headless mode, **refuse and exit** with `DATA_SAFETY_DENIED`. Data destruction must never happen without human oversight — an unattended pipeline that runs `--force-reset` could wipe a production database with no one watching.
+Scan build/package files and classify:
 
-### Examples
+| Signal | Classification |
+|---|---|
+| `package.json` with `next` | Next.js |
+| `package.json` with `vite` | Vite frontend |
+| generic `package.json` | Node.js |
+| `requirements.txt` / `pyproject.toml` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `Dockerfile` | Docker image |
+| `docker-compose.yml` | Docker Compose |
 
-Read `${SKILL_DIR}/references/data-safety-examples.md` for concrete few-shot examples of dangerous commands caught by this gate, including the correct and incorrect ways to handle them.
+Also detect:
+- environment variables referenced in source
+- ports/listen calls
+- database dependencies
+- existing deployment config at `.prizmkit/deploy/deploy.config.json`
 
-## Deployment Discovery
+### Target Detection
 
-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.
+Priority:
 
-### Step 1: Project Detection
+1. User-specified target: Vercel, own server, Docker, etc.
+2. Existing config: `.prizmkit/deploy/deploy.config.json`
+3. Project files: `vercel.json`, `netlify.toml`, `fly.toml`, `Dockerfile`, `docker-compose.yml`, GitHub deploy workflow, `app.yaml`, `serverless.yml`
+4. Interactive question: ask where the project should be deployed
+5. Headless with missing target: exit `NEEDS_INPUT` and write pending questions to `.prizmkit/deploy/pending-input.json`
 
-Scan the project root for build/package files and classify:
+## Adapter Routing
 
-| 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 |
+| Target | Route | Reference |
+|---|---|---|
+| SSH Linux server + Node.js project | Full automation | `references/ssh-adapter-flow.md` |
+| Vercel / Netlify / Fly.io | Guided CLI setup | `references/cloud-platform-deploy.md` |
+| Docker / Docker Compose | Guided build/run | `references/docker-deploy.md` |
+| Unsupported target or project type | Documented fallback | §Unsupported Fallback |
 
-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:
-
-1. **SSH Linux server** → §SSH Deployment Path — full automation: bootstrap, configure, deploy, operate. First-version adapter: PM2 + Nginx + blue/green.
-2. **Vercel / Netlify** → §Cloud Platform Deployment Path — guided: detect CLI tools, walk through deploy commands, generate deploy.md. Details in `references/cloud-platform-deploy.md`.
-3. **Docker** → §Docker Deployment Path — guided: detect Dockerfile/Compose, build image, container lifecycle. Details in `references/docker-deploy.md`.
-4. **Unsupported** → §Unsupported Deployment Fallback — generate deploy.md, record adapter gap, provide manual checklist.
-
-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, environment variables table, build/start instructions, health check suggestions.
-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").
-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.
+Compatibility check before SSH: the full SSH adapter currently requires a Node.js project with `package.json`. Non-Node Linux server targets route to Unsupported Fallback with an adapter-gap note.
 
 ## 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.
+Interactive mode:
+- May ask questions and request approvals.
+- May deploy to dev, test, or production.
+- Production requires explicit confirmation before execution.
 
-**Headless mode** (invoked via `--headless` flag, pipeline, or script):
-- Never wait for user input — unattended shells that time out on a prompt block pipelines silently without visible errors, so exit with clear status codes instead.
-- May ONLY target `dev` or `test` environments.
-- If `--env production` in headless mode: exit immediately with `ENVIRONMENT_DENIED — production deployment requires interactive mode`, because production deploys must never happen without human oversight.
-- 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`.
+Headless mode:
+- Never wait for user input.
+- May target only dev or test environments.
+- Reject production with `ENVIRONMENT_DENIED`.
+- If required info is missing, exit `NEEDS_INPUT` and write `.prizmkit/deploy/pending-input.json`.
+- Perform only 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
+Determine intent from the first word after `/prizmkit-deploy`:
+
+```text
+/prizmkit-deploy                    -> deploy if config exists, otherwise configure
+/prizmkit-deploy configure          -> first-run or repair configuration wizard
+/prizmkit-deploy deploy             -> full deployment pipeline
+/prizmkit-deploy status             -> show runtime and active release status
+/prizmkit-deploy logs --app <id>    -> show recent logs
+/prizmkit-deploy restart --app <id> -> restart active app process and health check
+/prizmkit-deploy rollback --app <id> [--to <releaseId>] -> rollback
+/prizmkit-deploy health --app <id>  -> run health checks
+/prizmkit-deploy history            -> list deploy history
+/prizmkit-deploy validate           -> validate config and target 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.
+No-arg behavior:
+- If config is missing, start configuration.
+- If config exists and validates, show deployment summary and ask for environment.
+- If config exists but is incomplete or stale, enter repair flow.
 
-## File Structure
+## Artifact Structure
 
-All artifacts live under `.prizmkit/deploy/`:
+All deployment artifacts live under `.prizmkit/deploy/`:
 
-```
+```text
 .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.md
+  deploy.config.json
+  pending-input.json
   deploy-history/
-    <deployment-id>.json             # one per deploy/rollback/event
-  deploy-scripts/                    # future — PrizmKit-managed deploy scripts
-  secrets.enc.json                   # optional, encrypted local secrets
-  secrets.local.json                 # optional, plaintext secrets (must be gitignored)
-```
-
-Read `references/deploy-config-schema.md` when writing or validating `deploy.config.json`. Read `references/deploy-history-schema.md` when writing history records.
-
-## SSH Deployment Path
-
-The following sections define the SSH deployment adapter — the only fully-automated path. Route here when Discovery determines the target is a Linux server with SSH access.
-
-### SSH: Deployment Mode Selection
-
-After Discovery routes to SSH, **before** entering the configuration wizard, ask the user how they want to deploy.
-
-**First question:**
-> "How do you want to deploy to the server?"
-> - **A. Direct Upload (quick start)** — build locally, transfer to server and start. Good for first deployment.
-> - **B. CI/CD Auto-Deploy (recommended)** — configure GitHub Actions, then `git push` auto-deploys.
-
-**If user chooses CI/CD, second question:**
-> "CI/CD has two modes:"
-> - **Push mode** — GitHub Actions runner builds, SCP transfers to server. Low server load.
-> - **Pull mode** — server pulls code and builds itself. Simpler config but requires a Deploy Key.
-
-For detailed mode descriptions and the full Push/Pull comparison table, read `references/deployment-modes.md`.
-
-**Config field:** `deployStrategy` in `deploy.config.json` — `"direct-upload"`, `"ci-cd-push"`, or `"ci-cd-pull"`. Existing configs without this field default to `"ci-cd-pull"` for backward compatibility.
-
-### 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 (Pull mode only).
-
-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/
+  deploy-scripts/
+  secrets.enc.json
+  secrets.local.json
 ```
 
-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. Flow: **deployment mode → collect → validate → confirm → persist**.
-
-**Before any questions:** ask deployment mode (see §SSH: Deployment Mode Selection). This determines required steps:
-
-| Step | Direct Upload | CI/CD Push | CI/CD Pull |
-|------|:---:|:---:|:---:|
-| SSH Server Discovery | Required | Required | Required |
-| Repository Access | Skipped | Skipped | Required |
-| Application Configuration | Required | Required | Required |
-| Environment Variables | Required | Required | Required |
-| Persist Configuration | Required | Required | Required |
-
-#### Step 1: SSH Server Discovery
-
-Ask for and validate:
-- **Server host and port** (e.g., `43.161.221.171:22`)
-- **Bootstrap user** (usually `root`) — 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 (CI/CD Pull mode only)
-
-Only needed when `deployStrategy` is `"ci-cd-pull"` — the server needs to `git pull` code. Skip for `"direct-upload"` (no Git on server) and `"ci-cd-push"` (GitHub Actions handles checkout).
-
-Ask for: Git URL, branch, 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 public key to user: "Add this to GitHub Deploy Keys (read-only)"
-3. Wait for confirmation, then verify: attempt a git clone as runtime user
-
-#### Step 3: Application Configuration
-
-For each app, collect: id, path, packageManager, installCommand, buildCommand, startCommand, blue/green port pair (default 3101/3102), healthChecks.
-
-#### Step 4: Environment Variables
-
-Scan source code for `process.env.<VAR>` references. Ask user for each required value. Identify secrets vs non-secrets. Ask about secret storage strategy (see §Secrets Management).
-
-#### Step 5: Persist Configuration
+Read `references/deploy-config-schema.md` when writing or validating config. Read `references/deploy-history-schema.md` when writing history records.
 
-Write `deploy.config.json` with all collected values and `validated: {}` stubs for each section. Write `deploy.md` as human-readable documentation.
+Reference index:
+- `references/ssh-adapter-flow.md` — load when routing to SSH Linux full automation.
+- `references/deployment-modes.md` — load when the user needs push/pull/direct-upload comparison.
+- `references/ssh-bootstrap-flow.md`, `references/firewall-setup.md`, `references/database-setup.md` — load during SSH bootstrap branches.
+- `references/direct-upload.md`, `references/ci-cd-workflows.md` — load for strategy-specific setup.
+- `references/dns-setup.md`, `references/ssl-setup.md` — load for domain and HTTPS setup.
+- `references/ssh-execution-flow.md`, `references/nginx-blue-green.md`, `references/ssh-takeover.md` — load for deploy execution, traffic switching, rollback, or takeover.
+- `references/cloud-platform-deploy.md`, `references/docker-deploy.md` — load for non-SSH guided routes.
+- `references/live-validation-notes.md` — load when troubleshooting bootstrap or deploy failures.
 
-### SSH: Bootstrap Flow
+Never record raw secret values in config, docs, or history. Secret presence metadata is allowed; raw values and unsalted hashes are not.
 
-Before first deployment, bootstrap the server. Present a plan showing every privileged action before executing anything.
+## SSH Automation Route
 
-Read `${SKILL_DIR}/references/ssh-bootstrap-flow.md` for the full bootstrap procedure (preflight, check-and-install, user/dir setup, PM2 startup, deploy key). When the bootstrap reaches firewall or database steps, it routes to `references/firewall-setup.md` and `references/database-setup.md`. Key rules: bootstrap operations must be idempotent, existing config files must be backed up before modification, and each step's result must be recorded.
+When routing to SSH Linux full automation, read `${SKILL_DIR}/references/ssh-adapter-flow.md` first. That reference coordinates the detailed SSH sub-procedures:
 
-### SSH: Direct Upload Deployment
+- deployment mode selection and first-run wizard
+- server model and directory layout
+- bootstrap and privileged action safety
+- direct upload vs CI/CD push vs CI/CD pull
+- DNS and SSL guidance
+- PM2 + Nginx blue/green execution
+- rollback and operations commands
+- secrets and multi-app coordination
 
-When `deployStrategy` is `"direct-upload"`, the AI builds locally and transfers artifacts to the server. No Git operations on the server. Full procedure in `references/direct-upload.md`.
+Key invariants:
+- Present privileged bootstrap plans before execution.
+- Back up existing config before modification.
+- Run `nginx -t` before reload.
+- Do not switch traffic until staged health checks pass.
+- If failure happens before traffic switch, leave the live version unchanged.
+- Preserve failed releases/logs for debugging.
 
-### SSH: CI/CD Pipeline Configuration
+## Cloud and Docker Routes
 
-When `deployStrategy` is `"ci-cd-push"` or `"ci-cd-pull"`, generate `.github/workflows/deploy.yml` with the appropriate workflow template. Both modes share the same trigger and secrets. Full YAML templates in `references/ci-cd-workflows.md`.
+Cloud platforms:
+- Read `references/cloud-platform-deploy.md`.
+- Detect required CLI/account steps.
+- Generate or update deploy documentation and config.
+- Guide the user through interactive login or dashboard steps when needed.
 
-After generating the workflow, verify: the first `git push` to the configured branch will trigger the first deployment. Monitor the GitHub Actions run and report results.
+Docker:
+- Read `references/docker-deploy.md`.
+- Detect Dockerfile/Compose configuration.
+- Build/run/validate with explicit environment and volume handling.
+- For destructive volume or database operations, apply the Data Safety Gate.
 
-### SSH: DNS Guidance
+## Unsupported Fallback
 
-Before SSL, check if the user has a domain pointing to the server.
+When no adapter covers the detected target/project type:
 
-1. Ask: "Do you have a domain to bind to this project?" If no domain → skip DNS + SSL, note in deploy.md.
-2. Check DNS: `dig +short <domain> A`. If resolved → proceed to SSL.
-3. If not resolved: show the user DNS setup instructions. Full procedure in `references/dns-setup.md`.
-
-### SSH: SSL/HTTPS Configuration
-
-Once DNS is confirmed pointing to the server, configure HTTPS via Let's Encrypt.
-
-1. Detect cloud vendor via metadata endpoints.
-2. If cloud vendor detected, ask: Let's Encrypt (recommended) or cloud vendor certificate.
-3. Install certbot and request certificate.
-4. Verify auto-renewal with `certbot renew --dry-run`.
-
-Full procedure in `references/ssl-setup.md`.
-
-### SSH: Deployment Execution Flow
-
-Read `${SKILL_DIR}/references/ssh-execution-flow.md` for the full 5-group pipeline: pre-flight, fetch & build, stage & health check, switch & verify, cleanup & record. Key invariant: if any step before traffic switch fails, STOP — do not touch the live version.
-
-### SSH: Blue/Green PM2 + Nginx Strategy
-
-- Blue: port 3101 (default), Green: port 3102 (default).
-- Active color persisted in `/var/www/<project>/shared/deploy-metadata.json`.
-- PM2 process naming: `<project>-<app>-<color>` (deterministic, never reuse old release IDs).
-- Nginx config must include: `# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY`.
-- Before modifying any Nginx config lacking this marker, ask for user confirmation.
-- Always `nginx -t` before `systemctl reload nginx`.
-
-See `references/nginx-blue-green.md` for the full Nginx config template and traffic switch procedure.
-
-### SSH: Rollback
-
-Two triggers: **automatic** (health check failure after traffic switch) and **manual** (`/prizmkit-deploy rollback --app <id> [--to <releaseId>]`).
-
-Steps: identify target release → verify build exists → start PM2 on its port → update Nginx upstream → `nginx -t` → reload → health checks → write rollback event. Do NOT delete the failed release or its logs — preserve for debugging.
-
-If no previous release exists, rollback is not possible — state this clearly.
-
-### SSH: Operations Commands
-
-**status:** `pm2 list` as runtime user + active release, active color/port, last deploy timestamp.
-
-**logs --app \<id\>:** `pm2 logs <process-name> --lines 100` as runtime user.
-
-**restart --app \<id\>:** identify active PM2 process → `pm2 restart` → wait → health checks.
-
-**health --app \<id\>:** run all configured health checks, report pass/fail for each.
-
-**history:** list `.prizmkit/deploy/deploy-history/` events chronologically.
-
-### SSH: Post-Deploy CI/CD Upgrade
-
-After a successful direct-upload deployment, proactively offer CI/CD setup:
-
-> "Deployment succeeded. Want me to set up CI/CD auto-deploy? After that, `git push` will auto-deploy."
-
-If user agrees, ask push vs pull, then configure accordingly. If Pull mode: set up deploy key. If Push mode: add GitHub Actions secrets. Generate `deploy.yml` from `references/ci-cd-workflows.md`, update `deployStrategy` in config, write upgrade event to history.
-
-## Environment Policy
-
-| Mode | dev | test | production |
-|------|-----|------|------------|
-| Interactive | Allowed | Allowed | Allowed (requires confirmation) |
-| Headless | Allowed | Allowed | **REJECTED** — exits with ENVIRONMENT_DENIED |
-
-Headless must reject production because production deploys require human oversight — an unattended pipeline timing out mid-deploy can leave the site in a broken state with no one monitoring.
-
-## 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, read `${SKILL_DIR}/references/ssh-takeover.md` for the detection procedure and takeover decision flow. 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.
-- Always `nginx -t` before reload.
-
-See `references/nginx-blue-green.md` for the full Nginx config template.
-
-### SSH: Bootstrap Safety Rules
-
-Before executing privileged bootstrap work, generate an action plan listing: packages, users/groups, SSH keys, Nginx config, directories/permissions, services that may be restarted.
-
-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 must complete for ALL selected apps before ANY app switches traffic.
-- If any app fails before traffic switch, NO app switches traffic. Staged processes stopped, live system unchanged.
-- If any app fails after traffic switch, default: group rollback.
-- Single-app deploys (`--app <id>`) do not affect unrelated apps.
+1. Detect what you can: language, framework, build/start commands, env vars, port usage, databases.
+2. Generate `.prizmkit/deploy/deploy.md` with prerequisites, env vars, build/start instructions, health checks, and manual steps.
+3. Record adapter gap in deploy history: missing adapter, detected project type, target, fallback output.
+4. Offer to generate basic CI/CD config when applicable.
 
 ## Validation
 
-Validation is mandatory before production deploy. Check: SSH connectivity, required tools (node, npm, git, pm2, nginx), repository reachability, port availability, required env vars, 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:
-
-| Target | Reference | Mode |
-|--------|-----------|------|
-| SSH Linux server | SSH sections in this file | 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 |
-
-## Deploy History Record Schema
-
-Each deployment, rollback, or significant event writes a record to `.prizmkit/deploy/deploy-history/<id>.json`. Full schema in `references/deploy-history-schema.md`. Never record raw secret values in history — presence metadata only.
-
-## Implementation Notes
-
-Live validation findings from the first PrizmKit deployment are in `references/live-validation-notes.md`. Read when troubleshooting bootstrap or deploy issues — these cover port conflict detection, npm verification, locale fixes, deploy key interactivity, PM2 PATH handling, and build-time env var timing.
+Before production deploy, validate:
+
+- target connectivity
+- required tools
+- repository or artifact availability
+- port availability
+- required environment variables
+- process manager/runtime config
+- Nginx syntax when applicable
+- health check routes
+- rollback readiness
+
+Persist validation results in `deploy.config.json` under the relevant `validated` fields.
+
+## Output
+
+Report:
+- detected project and target
+- selected adapter or fallback
+- environment and deploy strategy
+- actions performed
+- validation/health results
+- deploy history record path
+- next recommended action