prizmkit 1.1.78 → 1.1.80

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

@@ -0,0 +1,444 @@
+---
+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."
+---
+
+# 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.
+
+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.
+
+### 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
+- 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
+
+## 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.
+
+### Detection
+
+Before running any shell command, scan it for these patterns:
+
+| 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 |
+
+### Confirmation Flow
+
+When a dangerous pattern is detected:
+
+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.
+
+### Headless Mode
+
+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.
+
+### Examples
+
+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.
+
+## 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:
+
+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.
+
+## 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):
+- 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`.
+
+## 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 — 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:**
+> "你想怎么部署到服务器？"
+> - **A. 直接上传（快速上手）** — 本地构建，传到服务器启动。适合第一次部署。
+> - **B. CI/CD 自动部署（推荐）** — 配置 GitHub Actions，以后 `git push` 自动部署。
+
+**If user chooses CI/CD, second question:**
+> "CI/CD 有两种模式："
+> - **Push 模式** — GitHub Actions runner 编译，SCP 传到服务器。服务器压力小。
+> - **Pull 模式** — 服务器自己拉代码编译。配置更简单但需 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/
+```
+
+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
+
+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 showing every privileged action before executing anything.
+
+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.
+
+### SSH: Direct Upload Deployment
+
+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`.
+
+### SSH: CI/CD Pipeline Configuration
+
+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`.
+
+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.
+
+### SSH: DNS Guidance
+
+Before SSL, check if the user has a domain pointing to the server.
+
+1. Ask: "你有没有域名要绑定到这个项目？" 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:
+
+> "部署成功。要不要顺手帮你配置 CI/CD 自动部署？以后 `git push` 就自动上线。"
+
+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.
+
+## 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.

package/bundled/skills-windows/prizmkit-deploy/references/ci-cd-workflows.md

@@ -0,0 +1,115 @@
+# CI/CD Workflow Templates
+
+Read this file when `deployStrategy` is `ci-cd-push` or `ci-cd-pull`.
+
+## Shared Configuration
+
+**Secrets** (add to GitHub repository Settings → Secrets and variables → Actions):
+- `SSH_HOST` — server IP/hostname
+- `SSH_USER` — runtime user (e.g., `deploy`)
+- `SSH_KEY` — SSH private key
+- `SSH_PORT` — SSH port (default 22)
+
+**Shared trigger:**
+```yaml
+on:
+  push:
+    branches: [<branch>]
+    paths-ignore:
+      - '.prizmkit/**'
+      - 'docs/**'
+```
+
+---
+
+## Push Mode Workflow (`ci-cd-push`)
+
+Build happens on GitHub Actions runner. Only built artifacts are transferred to the server.
+
+```yaml
+name: Deploy to Production (Push)
+
+on:
+  push:
+    branches: [<branch>]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install & Build
+        run: |
+          npm ci
+          npm run build
+
+      - name: Package & Transfer
+        run: |
+          RELEASE_ID=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
+          tar czf deploy-$RELEASE_ID.tar.gz \
+            <build-output-dir>/ node_modules/ package.json package-lock.json
+          scp -P ${{ secrets.SSH_PORT }} deploy-$RELEASE_ID.tar.gz \
+            ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/var/www/<project>/releases/
+
+      - name: Deploy on Server
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.SSH_HOST }}
+          username: ${{ secrets.SSH_USER }}
+          key: ${{ secrets.SSH_KEY }}
+          port: ${{ secrets.SSH_PORT }}
+          script: |
+            cd /var/www/<project>
+            RELEASE_ID=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
+            mkdir -p releases/$RELEASE_ID
+            tar xzf releases/deploy-$RELEASE_ID.tar.gz -C releases/$RELEASE_ID
+            rm releases/deploy-$RELEASE_ID.tar.gz
+            # PM2 start, health check, Nginx switch (same as manual flow)
+```
+
+**Key difference from Pull:** the runner checks out code, installs, builds, and only transmits the result. The server doesn't need Git or build tools — just Node.js runtime and PM2.
+
+---
+
+## Pull Mode Workflow (`ci-cd-pull`)
+
+GitHub Actions runner only triggers the server. The server does all the work.
+
+```yaml
+name: Deploy to Production (Pull)
+
+on:
+  push:
+    branches: [<branch>]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Server Deploy
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.SSH_HOST }}
+          username: ${{ secrets.SSH_USER }}
+          key: ${{ secrets.SSH_KEY }}
+          port: ${{ secrets.SSH_PORT }}
+          script: |
+            cd /var/www/<project>
+            RELEASE_ID=$(date +%Y%m%d)-$(git rev-parse --short HEAD)
+            mkdir -p releases/$RELEASE_ID
+            git clone <repoUrl> --branch <branch> releases/$RELEASE_ID
+            cd releases/$RELEASE_ID
+            npm ci
+            cp ../shared/.env.production .
+            npm run build
+            # PM2 start, health check, Nginx switch
+```
+
+**Key difference from Push:** the workflow is simpler (one step: SSH + run script), but the server needs Git, full build toolchain, and must be able to reach the repo.
+
+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.

package/bundled/skills-windows/prizmkit-deploy/references/cloud-platform-deploy.md

@@ -0,0 +1,93 @@
+# Cloud Platform Deployment Path
+
+Guided deployment for Vercel, Netlify, Fly.io, and similar cloud platforms. Full automation isn't available — these platforms require browser-based authentication — but the skill provides structured CLI assistance.
+
+## Detect and Validate
+
+1. Check if the platform CLI is installed: `vercel --version`, `netlify --version`, `fly version`.
+2. If missing, guide the user to install: `npm install -g vercel` or link to docs.
+3. Check authentication: `vercel whoami`, `netlify status`. If not logged in, guide the user through `vercel login`.
+4. Read the platform config file (`vercel.json`, `netlify.toml`, `fly.toml`) to understand existing settings.
+
+## Generate Configuration
+
+1. If no platform config file exists, generate one based on project detection:
+   - **Next.js on Vercel**: minimal config — Vercel auto-detects Next.js. Generate `vercel.json` only if custom rewrites/redirects are needed.
+   - **Static site on Netlify**: generate `netlify.toml` with build command and publish directory.
+   - **Any on Fly.io**: generate `fly.toml` with app name, builder, and HTTP service config.
+2. Set environment variables via the platform CLI: `vercel env add`, `netlify env:set`.
+3. Document all env vars needed (from Discovery Step 1 scan).
+
+## Deploy and Verify
+
+1. Run the platform deploy command: `vercel deploy --prod`, `netlify deploy --prod`, `fly deploy`.
+2. If the command requires interactive input, run it and show output to the user.
+3. After deploy, run health checks against the production URL.
+4. Write a deploy-history event recording: platform, project name, deploy URL, commit SHA, timestamp.
+
+## Operations
+
+| Command | Vercel | Netlify | Fly.io |
+|---------|--------|---------|--------|
+| status | `vercel list` | `netlify status` | `fly status` |
+| logs | `vercel logs` | `netlify logs` | `fly logs` |
+| rollback | `vercel rollback` | `netlify rollback` | `fly rollback` |
+| env | `vercel env ls` | `netlify env:list` | `fly secrets list` |
+
+Platform rollback is instant — no release-based rollback needed.
+
+## Platform-Specific Patterns
+
+### Vercel
+
+Vercel auto-detects Next.js projects — no config file required for basic deployments. Generate `vercel.json` only for custom rewrites, redirects, or headers.
+
+Key behaviors:
+- Next.js: framework auto-detected, build command and output directory inferred automatically
+- Static sites: set build command and output directory via `vercel.json` or CLI
+- Env vars: `vercel env add <KEY>` (supports `production`, `preview`, `development` environments)
+- Deploy preview: every branch gets a preview URL automatically (if connected via GitHub)
+
+### Netlify
+
+Netlify requires explicit build and publish configuration. Use `netlify.toml`:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = "dist"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+Key behaviors:
+- SPA redirects: the catch-all redirect above is essential for client-side routing
+- Env vars: `netlify env:set <KEY> <VALUE>` (per-context: `production`, `deploy-preview`, `branch-deploy`)
+- Branch deploys: every branch gets a deploy-preview URL automatically (if connected via GitHub)
+
+### Fly.io
+
+Fly.io requires a `fly.toml` with app name, builder, and HTTP service config:
+
+```toml
+app = "<app-name>"
+primary_region = "lhr"
+
+[build]
+  builder = "dockerfile"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+```
+
+Key behaviors:
+- Builder: `dockerfile` (default, uses Dockerfile) or `static` (static site hosting)
+- Secrets: `fly secrets set <KEY>=<VALUE>` for runtime environment variables
+- Scale: `fly scale count <N>` to adjust VM instances
+- Volumes: for persistent data, configure `[mounts]` in fly.toml
+
+**Note**: These are minimum-viable platform references; browser-based authentication remains a user-action step. Enriched platform coverage is planned for future iterations.