prizmkit 1.1.49 → 1.1.53

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.49",
-  "bundledAt": "2026-05-21T14:22:00.608Z",
-  "bundledFrom": "a8dea99"
+  "frameworkVersion": "1.1.53",
+  "bundledAt": "2026-05-24T05:20:15.152Z",
+  "bundledFrom": "156de40"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.49",
+  "version": "1.1.53",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -64,6 +64,13 @@
       "hasAssets": false,
       "hasScripts": false
     },
+    "prizmkit-test": {
+      "description": "Full-stack test generation and orchestration. Detects architecture, discovers/runs existing tests, analyzes coverage gaps, generates missing tests (unit/integration/E2E), outputs unified report.",
+      "tier": "1",
+      "category": "prizmkit-skill",
+      "hasAssets": false,
+      "hasScripts": false
+    },
     "feature-workflow": {
       "description": "One-stop entry point for feature development. Orchestrates feature-planner → feature-pipeline-launcher → background execution. Handles multi-feature batch development from a single request.",
       "tier": "companion",
@@ -166,6 +173,7 @@
         "prizmkit-committer",
         "prizmkit-retrospective",
         "prizmkit-deploy",
+        "prizmkit-test",
         "feature-workflow",
         "refactor-workflow",
         "app-planner",

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

@@ -1,6 +1,6 @@
 ---
 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. 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."
+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
@@ -73,26 +73,12 @@ If headless mode and no target can be determined, exit with `NEEDS_INPUT` listin
 
 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
-```
+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.
 
-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.
+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."
 
@@ -101,18 +87,11 @@ The SSH path is fully documented in the sections below. Cloud and Docker paths f
 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").
+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.
 
-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:
@@ -124,9 +103,9 @@ Detect invocation mode from the user's initial message. The mode determines what
 - 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.
+- 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`.
+- 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`.
 
@@ -164,16 +143,34 @@ All artifacts live under `.prizmkit/deploy/`:
   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
+  deploy-scripts/                    # future — PrizmKit-managed deploy scripts
   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.
+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
 
-## SSH Deployment Path (Full Automation)
+After Discovery routes to SSH, **before** entering the configuration wizard, ask the user how they want to deploy.
 
-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.
+**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
 
@@ -181,7 +178,7 @@ 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.
+- Can access the configured Git repository (Pull mode only).
 
 Server-side directory layout:
 ```
@@ -199,48 +196,46 @@ SSH roles: `bootstrapUser` (usually root, for initial setup) and `runtimeUser` (
 
 ### SSH: First-Run Configuration Wizard
 
-When `.prizmkit/deploy/deploy.config.json` does not exist, enter configuration wizard. The flow is: **collect → validate → confirm → persist**.
+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`) — used for initial package install and user creation
+- **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
+#### Step 2: Repository Access (CI/CD Pull mode only)
 
-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
+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 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
+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** — 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[] }`
+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 which are secrets (API keys, tokens) vs. non-secrets (URLs, anon keys).
-- Ask about secret storage strategy (see Secrets Management below).
+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
 
@@ -248,7 +243,7 @@ Write `deploy.config.json` with all collected values and `validated: {}` stubs f
 
 ### SSH: Bootstrap Flow
 
-Before first deployment, bootstrap the server. Present a plan to the user showing every privileged action before executing anything.
+Before first deployment, bootstrap the server. Present a plan showing every privileged action before executing anything.
 
 **Always-run preflight:**
 ```
@@ -256,18 +251,9 @@ 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.
+**Check-and-install (idempotent):** Node.js, npm, PM2, Nginx, Git. Use v22 LTS if v25 not available.
 
-**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.
+**Detect port conflicts:** `ss -tlnp | grep :80 || true`. If port 80/443 is occupied, report and ask how to resolve.
 
 **User and directory setup:**
 ```
@@ -281,104 +267,119 @@ chown -R <runtimeUser>:<runtimeUser> /var/www/<project>
 env PATH=$PATH:/usr/bin pm2 startup systemd -u <runtimeUser> --hp /home/<runtimeUser>
 ```
 
-**Deploy key (if strategy is deploy-key):**
+**Deploy key (Pull mode only):**
 ```
 sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
 sudo -u <runtimeUser> ssh-keyscan -H github.com >> ~/.ssh/known_hosts
 ```
 
+**Security baseline (firewall):** After core tools are installed, ask whether to configure ufw. If user agrees, read `references/firewall-setup.md` for the full interactive flow and rule templates.
+
+**Database setup:** If Discovery detected database drivers, ask whether to install the database on the server. If user agrees, read `references/database-setup.md` for platform-specific setup commands and security notes.
+
 After each bootstrap step, record the result. Bootstrap operations must be idempotent. Back up any existing config files before modifying them.
 
+### 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
 
 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.
 
+**Pre-flight — Change Summary:** Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD`. If first deployment, show last 5 commits. If no new commits, warn "没有新的代码变更。确定要重新部署吗？"
+
 **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.
+
+- **CI/CD Pull mode** (server-side build): git clone → install → copy `.env.production` before build (NEXT_PUBLIC_* vars are baked at build time) → build. If build fails: STOP.
+- **CI/CD Push mode** (runner-side build): extract tarball, skip install/build.
+- **Direct-upload mode**: build was already done locally and SCP'd. Skip this group.
 
 **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>`.
+- Start new version on 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.
+- Wait 3-5 seconds, run health checks against new port. If any fails: STOP, do NOT switch traffic.
 
 **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).
+- Run health checks against public endpoint. If any fails: rollback immediately.
 
 **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.
+- Write deploy-history JSON. Update `deploy.config.json` validation status.
+
+**Post-deploy — Completion Summary:** Output a summary (project, URL, version, duration, health status) and append to deploy.md. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).
 
 ### SSH: Blue/Green PM2 + Nginx Strategy
 
-The active color (blue or green) maps to a port:
-- Blue: port 3101 (default)
-- Green: port 3102 (default)
+- 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`.
 
-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.
+See `references/nginx-blue-green.md` for the full Nginx config template and traffic switch procedure.
 
-PM2 process naming: `<project>-<app>-<color>` (deterministic, never reuse old release IDs in names).
+### SSH: Rollback
 
-Nginx config must include the PrizmKit managed marker:
-```
-# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
-```
+Two triggers: **automatic** (health check failure after traffic switch) and **manual** (`/prizmkit-deploy rollback --app <id> [--to <releaseId>]`).
 
-Before modifying any Nginx config that lacks this marker, ask for user confirmation.
+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.
 
-Always `nginx -t` before `systemctl reload nginx`. If syntax check fails, abort.
+If no previous release exists, rollback is not possible — state this clearly.
 
-### SSH: Rollback
+### SSH: Operations Commands
 
-Two rollback triggers:
-1. **Automatic**: health check failure after traffic switch → roll back immediately.
-2. **Manual**: `/prizmkit-deploy rollback --app <id> [--to <releaseId>]`
+**status:** `pm2 list` as runtime user + active release, active color/port, last deploy timestamp.
 
-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.
+**logs --app \<id\>:** `pm2 logs <process-name> --lines 100` as runtime user.
 
-If no previous release exists (first deployment), rollback is not possible — state this clearly.
+**restart --app \<id\>:** identify active PM2 process → `pm2 restart` → wait → health checks.
 
-### SSH: Operations Commands
+**health --app \<id\>:** run all configured health checks, report pass/fail for each.
 
-#### 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
+**history:** list `.prizmkit/deploy/deploy-history/` events chronologically.
 
-#### logs --app <id>
-SSH to server and run `pm2 logs <process-name> --lines 100` as runtime user.
+### SSH: Post-Deploy CI/CD Upgrade
 
-#### 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.
+After a successful direct-upload deployment, proactively offer CI/CD setup:
 
-#### health --app <id>
-Run all configured health checks for the app against the public endpoint. Report pass/fail for each.
+> "部署成功。要不要顺手帮你配置 CI/CD 自动部署？以后 `git push` 就自动上线。"
 
-#### history
-Read `.prizmkit/deploy/deploy-history/` directory, list events chronologically. Show event type, release ID, commit SHA, timestamp, status.
+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
 
@@ -387,7 +388,7 @@ Read `.prizmkit/deploy/deploy-history/` directory, list events chronologically.
 | 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.
+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
 
@@ -407,7 +408,7 @@ Deploy history records secret presence metadata only (e.g., `{"SUPABASE_SERVICE_
 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:
+2. Report findings 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.
@@ -417,23 +418,15 @@ When deploying to a server that already has deployment assets:
 
 - 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.
+- Always `nginx -t` before reload.
 
-See `references/nginx-blue-green.md` for the full Nginx config template, traffic switch procedure, and active port rediscovery technique.
+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 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
+Before executing privileged bootstrap work, generate an action plan listing: packages, users/groups, SSH keys, Nginx config, directories/permissions, services that may be restarted.
 
-Execution rules:
+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.
@@ -444,53 +437,32 @@ Execution rules:
 ### 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).
+- 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 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
+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 file for execution details:
+After Discovery routes to a deployment target, read the corresponding reference:
 
 | Target | Reference | Mode |
 |--------|-----------|------|
-| SSH Linux server | SSH sections below (Server Model through Multi-App) | Full automation |
+| 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 |
-
-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.
+| 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`. 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
+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.
 
-These findings from PrizmIdeas first deployment should guide your behavior:
+## Implementation Notes
 
-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.
+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/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/prizmkit-deploy/references/database-setup.md

@@ -0,0 +1,46 @@
+# Database Setup
+
+Read this file when Discovery detected a database driver and the user wants AI-assisted database installation on the server.
+
+## Entry condition
+
+During Discovery Step 1 (Project Detection), database drivers were already scanned. If a driver was detected, ask after bootstrap tools are installed:
+
+> "检测到项目使用了 <PostgreSQL/MySQL/Redis>，需要帮你在服务器上安装配置吗？"
+> - **需要** → 继续数据库安装
+> - **不需要** → 跳过，记录到 deploy.md，标注"数据库需用户自行配置"
+
+## PostgreSQL setup
+
+```
+apt-get install -y postgresql postgresql-contrib
+sudo -u postgres psql -c "CREATE DATABASE <project>;"
+sudo -u postgres psql -c "CREATE USER <project> WITH PASSWORD '<random-password>';"
+sudo -u postgres psql -c "GRANT ALL ON DATABASE <project> TO <project>;"
+```
+
+- Generate a secure random password (32 chars, alphanumeric + symbols).
+- Write the connection string to `.prizmkit/deploy/secrets.local.json`: `DATABASE_URL=postgresql://<project>:<password>@localhost:5432/<project>`.
+- In deploy.md, write: "PostgreSQL 已安装，连接信息已记录到 `.prizmkit/deploy/secrets.local.json`（不提交到 git）".
+
+## MySQL setup (future)
+
+Similar flow. Not implemented in first version — if project uses MySQL, direct user to documentation fallback.
+
+## Redis setup
+
+```
+apt-get install -y redis-server
+redis-cli CONFIG SET requirepass "<random-password>"
+redis-cli CONFIG REWRITE
+```
+
+- Bind to localhost only (modify `/etc/redis/redis.conf` if needed).
+- Write `REDIS_URL=redis://:<password>@localhost:6379` to `.prizmkit/deploy/secrets.local.json`.
+
+## Security notes
+
+- Never write database passwords to deploy.md, because deploy.md may be committed to git and passwords would leak.
+- Passwords stored in `.prizmkit/deploy/secrets.local.json` (gitignored).
+- Default: database binds to localhost, no external access, because most indie projects only need local connections.
+- Record a `"database-setup"` event in deploy history (presence metadata only, no passwords).

package/bundled/skills/prizmkit-deploy/references/deploy-config-schema.md

@@ -9,6 +9,7 @@ This file is the machine-readable deployment configuration. Always read it befor
   "version": 1,
   "project": "project-name",
   "deploymentMode": "ssh",
+  "deployStrategy": "direct-upload|ci-cd-push|ci-cd-pull",
   "defaults": { ... },
   "environments": { ... },
   "servers": [ ... ],

package/bundled/skills/prizmkit-deploy/references/deployment-modes.md

@@ -0,0 +1,50 @@
+# Deployment Mode Details
+
+Read this file when the user needs a detailed comparison of deployment modes during mode selection. SKILL.md contains the routing logic; this file has the full descriptions.
+
+## Mode A — Direct Upload
+
+1. Local build on the user's machine.
+2. SCP built output + `node_modules` + `.env.production` to server.
+3. PM2 start → health check → Nginx switch.
+4. After success: offer to upgrade to CI/CD.
+5. Bypasses: deploy key, git clone on server, server-side build.
+
+Best for: first-time deployment, getting something live fast, low-spec servers.
+
+## Mode B1 — CI/CD Push
+
+1. Generate `.github/workflows/deploy.yml`: checkout → install → build → SCP tarball → SSH restart.
+2. Add GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY`, `SSH_PORT`.
+3. First deploy triggered by push to configured branch.
+4. Server only needs Node.js runtime + PM2 — no git, no build tools needed.
+5. GitHub Actions runner handles the heavy lifting.
+
+Best for: low-spec servers, heavy build processes, projects with large dependencies.
+
+## Mode B2 — CI/CD Pull
+
+1. Configure deploy key on server → add to GitHub.
+2. Generate `.github/workflows/deploy.yml`: triggers SSH command on server.
+3. Server-side deploy script: `git pull` → install → build → PM2 restart → health check.
+4. Server needs full build toolchain (Node.js, npm, git).
+5. Simpler workflow file, heavier server load.
+
+Best for: simple setup, servers with sufficient CPU/RAM, projects where build is fast.
+
+## Comparison
+
+| 对比 | Push 模式 | Pull 模式 |
+|------|----------|----------|
+| 构建位置 | GitHub Actions runner | 服务器本地 |
+| 服务器压力 | 低（只运行应用） | 高（编译+运行） |
+| 配置复杂度 | 中（需 SCP 传产物） | 低（只需 SSH 触发脚本） |
+| 适合场景 | 服务器配置低、编译重 | 部署简单优先、服务器性能充裕 |
+| Deploy Key 需要 | 不需要 | 需要 |
+| 产物传输 | SCP tarball | git pull（仅增量） |
+
+## Common ground between all modes
+
+- Same PM2 + Nginx blue/green strategy.
+- Same health check and traffic switch procedure.
+- Same ops commands (status/logs/restart/rollback).

package/bundled/skills/prizmkit-deploy/references/direct-upload.md

@@ -0,0 +1,26 @@
+# Direct Upload Deployment
+
+Read this file when `deployStrategy` is `"direct-upload"`. The AI handles the build locally and transfers built artifacts to the server. No Git operations on the server.
+
+## Build phase (local)
+
+1. Run `<buildCommand>` locally (e.g., `npm run build`) in the project root.
+2. Identify the build output directory: `.next/` for Next.js, `dist/` for Vite, `build/` for CRA.
+3. Prepare a deployment tarball containing: build output + `node_modules/` + `package.json` + `package-lock.json` + any runtime config files.
+
+## Transfer phase (SCP)
+
+```
+scp -P <port> deploy-<releaseId>.tar.gz <runtimeUser>@<host>:/var/www/<project>/releases/
+ssh <runtimeUser>@<host> "cd /var/www/<project>/releases && mkdir <releaseId> && tar xzf deploy-<releaseId>.tar.gz -C <releaseId>"
+```
+
+## Server-side setup
+
+1. Copy `.env.production` from `shared/` into the release directory (or SCP it alongside the tarball if first deploy).
+2. No `npm install` needed — `node_modules` was transferred directly.
+3. Start PM2 on the inactive port. Health checks and traffic switch follow the standard flow (Groups 3-5 in SKILL.md).
+
+## Why transfer node_modules
+
+Direct upload is optimized for "fast first deploy." Re-running `npm ci` on a low-spec server can be slow. Transferring pre-built artifacts means the server only needs to run the app.

package/bundled/skills/prizmkit-deploy/references/dns-setup.md

@@ -0,0 +1,42 @@
+# DNS Setup Guidance
+
+Read this file when the user has a domain for their project but DNS is not yet pointing to the server.
+
+## Step 1 — Check DNS resolution
+
+```
+dig +short <domain> A
+```
+
+If it resolves to the server IP: DNS is already configured, proceed to SSL (`references/ssl-setup.md`).
+If not: continue below.
+
+## Step 2 — DNS setup guidance
+
+```
+域名 <example.com> 还未指向服务器 <服务器IP>。
+
+请在 DNS 服务商（如阿里云、Cloudflare、Namecheap）添加以下记录：
+
+  Type:  A
+  Name:  @
+  Value: <服务器IP>
+  TTL:   600
+
+如果要同时支持 www 子域名：
+  Type:  A
+  Name:  www
+  Value: <服务器IP>
+
+配置完成后回复"好了"，我继续检查并配 SSL 证书。
+```
+
+## Step 3 — Verify after user confirmation
+
+- Re-run `dig +short <domain> A` to confirm resolution.
+- If still not resolved: warn about DNS propagation delay (can take up to 48 hours, usually 5-30 minutes). Offer to wait or continue without SSL for now.
+- Once confirmed: proceed to SSL (`references/ssl-setup.md`).
+
+## Edge case — IP-only deployment
+
+If user has no domain: skip DNS + SSL sections. Generate a note in deploy.md: "项目通过 IP 访问，未配置域名和 HTTPS。建议购买域名后运行 `/prizmkit-deploy setup-ssl`。"

package/bundled/skills/prizmkit-deploy/references/firewall-setup.md

@@ -0,0 +1,37 @@
+# Firewall Setup (UFW)
+
+Read this file when the user wants AI-assisted firewall configuration during bootstrap.
+
+## Flow
+
+1. After core tools are installed, ask the user:
+   > "是否需要帮你配置防火墙（ufw）？只开放必要的端口，提高服务器安全性。"
+
+2. If user declines: skip, record to deploy config.
+
+3. If user agrees, ask which additional ports to open (beyond SSH/HTTP/HTTPS):
+   > "默认只开放 SSH(22)、HTTP(80)、HTTPS(443)。蓝绿部署预览端口（3101/3102）要不要也开放？如果需要其他端口（如数据库远程管理），可以一起列出来。"
+
+4. Collect ports, then ask:
+   > "防火墙规则已整理好。是我直接上去改，还是你自己来？"
+   > - **A. 你帮我改** — AI 执行 ufw 命令
+   > - **B. 我自己改** — 输出规则清单，用户手工执行
+
+## Planned rules (output before executing)
+
+```
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp       # SSH
+ufw allow 80/tcp       # HTTP
+ufw allow 443/tcp      # HTTPS
+ufw allow 3101/tcp     # blue preview (user-approved)
+ufw allow 3102/tcp     # green preview (user-approved)
+ufw --force enable
+```
+
+## Rules for automatic execution
+
+- Check `ufw status` first — if rules already exist, append only missing rules, don't overwrite.
+- Never `ufw reset` unless explicitly asked, because it wipes custom rules the user may have configured manually.
+- Record a `"security-baseline"` event in deploy history with the rule list, so future sessions can detect existing configuration.

package/bundled/skills/prizmkit-deploy/references/live-validation-notes.md

@@ -0,0 +1,21 @@
+# Implementation Notes from Live Validation
+
+These findings from the first PrizmKit deployment (PrizmIdeas) guide edge-case handling. Read when troubleshooting bootstrap or deploy issues.
+
+1. **Detect port conflicts before installing Nginx.** Check what's on port 80/443 and ask before stopping anything, because overwriting an existing web server without confirmation can break unrelated services.
+
+2. **Verify npm separately from node.** Minimal Node installs may not bundle npm. Run `which npm` after installing Node, because `node --version` succeeding doesn't guarantee npm is available.
+
+3. **Fix locale on bare Ubuntu.** Run `locale-gen en_US.UTF-8` early to avoid perl warnings in apt. This is safe to run unconditionally even if locale is already configured.
+
+4. **Deploy key workflow is inherently interactive.** Generate key → wait for user to add to GitHub → verify. Headless mode cannot complete this because it requires the user to paste the key into GitHub's UI.
+
+5. **`pm2 startup` needs explicit PATH.** Always use `env PATH=$PATH:/usr/bin pm2 startup ...`, because the pm2 binary may not be on root's default PATH.
+
+6. **Persist deploy metadata on server.** Write `activeColor`, `activePort`, `lastReleaseId`, `lastDeployTimestamp` to `shared/deploy-metadata.json`, because subsequent deploys and rollbacks depend on knowing the current active slot.
+
+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 and won't be picked up if the .env is added later.
+
+9. **Node.js version flexibility.** Default to v22 LTS if v25 is unavailable. Most frameworks tolerate a minor version diff, and v22 has broader package compatibility.

package/bundled/skills/prizmkit-deploy/references/ssl-setup.md

@@ -0,0 +1,56 @@
+# SSL/HTTPS Configuration (Let's Encrypt + Certbot)
+
+Read this file when DNS is confirmed pointing to the server and SSL needs to be configured.
+
+## Step 1 — Detect cloud vendor
+
+```
+# Try metadata endpoints to detect cloud vendor
+curl -s --connect-timeout 2 http://100.100.100.200/latest/meta-data/ && echo "ALIBABA"
+curl -s --connect-timeout 2 http://metadata.tencentyun.com/latest/meta-data/ && echo "TENCENT"
+curl -s --connect-timeout 2 http://169.254.169.254/latest/meta-data/ && echo "AWS/GCP/AZURE"
+```
+Also check `/etc/hostname` for vendor patterns.
+
+## Step 2 — Choose SSL strategy
+
+- **Cloud vendor detected** → ask user:
+  > "检测到服务器运行在 <云厂商>。用哪种 SSL 方案？"
+  > - **A. Let's Encrypt 免费证书（推荐）** — 一行命令永久自动续期，最省心
+  > - **B. <云厂商> 自有证书** — 需手动下载配置，1年有效期需手动续期
+  >
+  > 选 A 我直接帮你搞定；选 B 你需要在云控制台下载证书后告诉我路径。
+- **No cloud vendor / unknown** → use certbot directly, no choice needed.
+
+## Step 3 — Certbot install & certificate request
+
+```
+# Install certbot (idempotent)
+which certbot || apt-get install -y certbot python3-certbot-nginx
+
+# Request certificate
+certbot --nginx -d <domain> -d www.<domain> --non-interactive --agree-tos --email <user-email>
+```
+
+**Collect from user before running:**
+- Email address (Let's Encrypt expiry notifications)
+- Confirm domain list (e.g., `example.com, www.example.com`)
+
+## Step 4 — Verify auto-renewal
+
+```
+systemctl status certbot.timer
+certbot renew --dry-run
+```
+If timer is inactive, enable it: `systemctl enable --now certbot.timer`.
+
+## Step 5 — Record
+
+- Write SSL configuration summary to deploy.md: certificate paths, auto-renewal status, expiry date.
+- Record a `"ssl-setup"` event in deploy history.
+
+## Edge cases
+
+- **DNS not yet propagated** → certbot challenge fails. Tell user to wait and retry: `/prizmkit-deploy setup-ssl`.
+- **Existing certificate found** → check expiry date (`certbot certificates`). If expiring within 30 days, warn. Otherwise skip.
+- **Port 80/443 occupied by non-Nginx process** → report and ask how to resolve before proceeding.

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

@@ -40,6 +40,9 @@ For each unchecked task in plan.md, in order:
 
 1. Read L1/L2 doc for the target file's module — check TRAPS and DECISIONS before modifying files
 2. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+   - **Cover three paths for each function**: happy path (valid inputs producing expected behavior), edge cases (boundary values specific to the parameter type and domain — e.g., zero/min/max for numeric, empty collection, boundary index), and error conditions (inputs that should trigger error handling). Determine edge cases from the function's parameter types and domain logic, not from a fixed checklist. If a function has no edge or error paths, don't force them.
+   - **No redundant tests**: Check if a test for this behavior already exists before writing. Each test must verify a uniquely different code path — don't write multiple tests that exercise the same logic.
+   - **Test your own code only**: Don't test framework behavior, third-party library internals, or language built-ins. For library calls, test the integration point (correct parameters passed, return value correctly handled), not the library itself.
 3. Mark task as `[x]` in `plan.md` immediately after completion — not batched at the end. Immediate marking means plan.md always reflects true progress, even if the session is interrupted.
 4. **Parallel tasks**: If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group. Sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
 5. **Checkpoint tasks** (`CP:` prefix in plan.md): When a checkpoint task is reached, verify build passes and tests pass before continuing. Checkpoints catch integration errors early — skipping them means cascading failures in later phases.

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

@@ -0,0 +1,281 @@
+---
+name: "prizmkit-test"
+description: "Full-stack test generation and orchestration. Detects architecture, discovers/runs existing tests, analyzes coverage gaps, generates missing tests (unit/integration/E2E), outputs unified report. Use after completing development to verify quality before deploy. Trigger on: 'test', 'run tests', 'check quality', 'verify code', 'generate tests', 'test coverage', 'fill test gaps', 'quality check', '测试', '验证', '跑测试', '补测试'. (project)"
+---
+
+# PrizmKit Test
+
+A comprehensive test generation and orchestration skill. Discovers existing tests, runs them, compares coverage against spec acceptance criteria and module interfaces, generates missing tests at three levels (unit → integration → E2E), and produces a unified report.
+
+### When to Use
+- After completing one or more features/refactors/bugfixes
+- As a quality gate before deploy
+- Project has a test framework installed but zero tests written (first-time test generation)
+- User says "test", "run tests", "verify", "check quality", "补测试"
+
+### When NOT to Use
+- Project has no test framework AND no code to test
+- Trivial single-line config changes
+
+## Precondition
+
+| Required State | Check | If Missing |
+|---|---|---|
+| `.prizmkit/prizm-docs/root.prizm` exists | File exists | Run `/prizmkit-init` first |
+| Test framework installed | Dependency in package.json or equivalent | Offer to skip or let user install one manually |
+
+If `.prizmkit/prizm-docs/` exists but may be stale (no retrospective run after recent changes), warn user: "Prizm docs may be out of date. Gap analysis accuracy depends on current docs. Continue anyway?"
+
+## Context Loading
+
+Before execution, load context once:
+
+1. **Architecture context**: Read `.prizmkit/prizm-docs/root.prizm` (L0 — project overview, module index, tech stack, conventions) and relevant L1 docs for modules in scope. If scope includes specific modules, also load relevant L2 docs for INTERFACES, DATA_FLOW, TRAPS, and DECISIONS.
+2. **Project config**: Read `.prizmkit/config.json` (tech stack, AI CLI config).
+3. **Dependencies**: Read `package.json` or equivalent to detect test framework and project type.
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `scope` | No | User selects interactively in Phase 1. In headless mode, defaults to full project. |
+
+## Execution
+
+### Phase 0: Architecture Detection
+
+1. From context already loaded, classify project type:
+
+| Signal | Classification |
+|--------|---------------|
+| react/vue/angular/next in deps, no backend framework | Frontend |
+| express/fastify/django/flask in deps, no frontend framework | Backend |
+| Both present | Fullstack |
+| Neither clear | Ask user (headless: mark as "unknown", skip E2E) |
+
+2. Detect test framework by scanning dependencies:
+   - Jest → `npx jest` or `npm test`
+   - Vitest → `npx vitest run`
+   - pytest → `python -m pytest`
+   - Go testing → `go test ./...`
+   - Multiple frameworks found → use the one with the most test files; list all in report
+   - Custom `npm test` script → use `npm test`
+
+3. **Interactive mode**: Show "Detected: {type}, test framework: {name}. Correct?"
+   **Headless mode**: Auto-proceed with detected values, note assumptions in report.
+
+### Phase 1: Scope Selection
+
+**Interactive mode** — present three options:
+
+1. **Full project** — all modules, all specs in `.prizmkit/specs/`
+2. **Single module** — pick from L1 doc module names (e.g., "auth", "payment")
+3. **Single feature** — pick from `.prizmkit/specs/###-*/` directories
+
+**Headless mode** — default to full project. If `artifact_dir` or `scope` was passed by the caller, use that.
+
+### Phase 2: Run Existing Tests
+
+1. Find test directories matching common patterns: `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`. If no test files exist at all, note this and skip to Phase 3 (all coverage is "missing").
+
+2. Run the detected test command in scope. Capture:
+   - Pass/fail counts and failed test details
+   - Which test files exist (for gap analysis)
+   - Raw output (saved to report directory)
+
+3. If existing tests fail: record failures but continue — this is coverage data. Do not attempt to fix pre-existing test failures (they predate this session).
+
+### Phase 3: Coverage Gap Analysis
+
+Staleness of `.prizmkit/prizm-docs/` was already checked during Context Loading (see Precondition). Gap analysis proceeds with the available data.
+
+Compare what exists against what should exist, across three levels:
+
+**Unit test gaps** — for each module in scope:
+- Read the corresponding L2 `.prizm` doc INTERFACES section to get exported functions/classes. If no L2 doc exists for a module, analyze source files directly to identify exported functions/classes.
+- Check if each has a corresponding test file (match project's test naming: `foo.test.ts`, `foo.spec.ts`, `test_foo.py`)
+- Flag uncovered interfaces
+
+**Integration test gaps** (skip if project has no API/DB layer — pure library/CLI tool):
+- Read L1 doc DEPENDENCIES section for cross-module interactions
+- Check if tests exist covering module boundaries, API endpoints, DB operations
+- Flag missing integration coverage
+
+**E2E test gaps** (skip if project has no UI):
+- Collect acceptance criteria from all spec.md files in scope
+- Check existing E2E test files against these criteria
+- Flag uncovered criteria
+
+### Phase 4: Generate Missing Tests
+
+Generate tests in priority order: unit → integration → E2E. After each batch, run immediately.
+
+When generated tests fail, distinguish two cases:
+- **Test bug** (syntax error, wrong import, wrong mock, wrong framework API usage) → fix the test and re-run
+- **Assertion failure** (test is valid but code returns unexpected result) → mark as "needs review" in report; do NOT modify production code. This is a potential bug discovered by the generated test.
+
+If a test fails repeatedly after 2 fix attempts, skip it and mark as "unresolved" in the report.
+
+**4a. Unit Tests (always applicable)**
+
+For each uncovered interface:
+- Read the source file to understand function signature and logic
+- Generate test file matching project conventions (framework, naming, directory, import style, mock/fixture patterns)
+- Common naming patterns to match:
+  - `src/foo.ts` → `src/__tests__/foo.test.ts` or `src/foo.spec.ts` or `tests/foo_test.py`
+  - Mirror the existing pattern; if no tests exist, use the framework's default convention
+- Cover: happy path, edge cases (null/undefined/empty), error conditions, boundary values
+- Do NOT test framework internals or third-party library behavior
+- Run tests immediately after generating
+
+**4b. Integration Tests**
+
+For each module with dependencies:
+- Generate tests for the module's primary interface exercising its real dependencies
+- If API endpoints exist: request/response tests (valid input, invalid input, missing params, auth)
+- If database operations exist: CRUD tests using the project's existing test database config
+- Run tests immediately after generating
+
+**4c. E2E Tests (conditional)**
+
+Preconditions (ALL must be met):
+- Playwright is available (`@playwright/test` or `playwright` in package.json dependencies, or `npx playwright --version` succeeds as fallback)
+- Playwright browsers are installed (check `npx playwright install --dry-run 2>/dev/null` exits cleanly, or `node_modules/.cache/ms-playwright/` directory exists; if missing, warn in report and skip E2E)
+- Project has a UI layer
+- Project can be started (start/dev script in package.json)
+- Acceptance criteria exist in spec.md files
+
+If ALL met:
+- **Before starting dev server**: detect whether it's already running: (1) check `package.json` scripts for port flags (`--port`, `-p`, `PORT=`), (2) fall back to framework defaults (3000 for React/Next/Express, 5173 for Vite, 8000 for Django, 5000 for Flask), (3) if still unknown, ask the user. Use the detected port in `lsof -i :<port>` to check. If running, tell user: "Dev server appears to be already running on port {N}. Use this running instance for E2E tests?" If user confirms, use existing instance. If user declines, skip E2E.
+- Start the project dev server (only if not already running). Wait for it to be ready.
+- For each uncovered acceptance criterion, generate a Playwright test script
+- Run generated E2E tests, capture screenshots of failures
+- **Only stop dev server if you started it.** Never stop a server that was already running.
+
+If NOT met:
+- Note what was skipped and why in the report
+- If only the server wasn't startable: still generate E2E script files but mark as "not run — manual execution needed"
+
+### Phase 5: Unified Report
+
+Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory.
+
+**test-report.md** format:
+
+```markdown
+# Test Report — {timestamp}
+
+## Summary
+- Scope: {full / module: name / feature: ###-name}
+- Architecture: {frontend / backend / fullstack}
+- Test framework: {name}
+- Mode: {interactive / headless}
+
+## Existing Tests
+- Total: {N} | Passed: {N} | Failed: {N}
+{failed test details or "All passing"}
+{or "No existing tests found — generated first batch"}
+
+## Coverage Gaps Found
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| ... | ... | unit/integration/e2e | covered / generated / needs-review / unresolved / skipped |
+
+## Generated Tests
+- Unit: {N} generated, {N} needs-review, {N} unresolved
+- Integration: {N} generated, {N} needs-review, {N} unresolved
+- E2E: {N} generated, {N} skipped ({reason})
+
+## Final Status
+- All tests passing: {yes / no}
+- Needs human review: {list of tests marked needs-review}
+{remaining failures if any}
+```
+
+Also save:
+- `existing-test-output.txt` — raw output from Phase 2
+- `generated-tests/` — copies of all generated test files
+- `e2e-output/` — E2E logs and failure screenshots (if applicable)
+
+## Output
+
+- Test report: `.prizmkit/test/{timestamp}_testresult/test-report.md`
+- Generated test files written to project test directories
+- Existing test output, generated test copies, and E2E artifacts in the report directory
+
+## Recovery
+
+If the session is interrupted:
+- Check `.prizmkit/test/` for the most recent report directory — it contains what was completed before interruption
+- Re-run `/prizmkit-test` — it starts fresh, but Phase 2 will skip tests that already pass, and Phase 3 will re-evaluate gaps
+
+## Examples
+
+### Example 1: Full-Project Quality Check with Test Generation
+
+**User**: `/prizmkit-test`
+
+**Phase 0 — Architecture Detection**:
+```
+Detected: Fullstack (React + Express)
+Test framework: Vitest (7 existing test files)
+```
+
+**Phase 1 — Scope Selection** (user selects option 1):
+```
+Scope: Full project (all modules, all specs)
+```
+
+**Phase 2 — Existing Tests**: 7 test files found, 20 tests run, 18 passed, 2 pre-existing failures (recorded, not fixed).
+
+**Phase 3 — Gap Analysis** (excerpt):
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| auth | login() | unit | missing |
+| auth | register() | unit | missing |
+| payment | processPayment() | unit | missing |
+| payment | api/checkout | integration | missing |
+| — | Checkout flow | e2e | missing |
+
+**Phase 4**: Generated 5 unit tests (3 passing, 2 assertion failures marked "needs-review"), 1 integration test (passing), 1 E2E test (passing).
+
+**Phase 5 — Report Summary**:
+```
+Generated: 5 unit (2 needs-review), 1 integration, 1 E2E
+Report: .prizmkit/test/2026_05_23_14_30_00_testresult/test-report.md
+Needs human review: processPayment (returns 400 for negative amounts, expected 422), refund (missing authorization header causes 500 instead of 401)
+```
+
+### Example 2: Single-Feature Targeted Test
+
+**User**: `/prizmkit-test`
+
+**Phase 0 — Architecture Detection**:
+```
+Detected: Backend (Express)
+Test framework: Vitest
+```
+
+**Phase 1 — Scope Selection** (user selects option 3, then picks "042-payment-gateway"):
+```
+Scope: Single feature — 042-payment-gateway
+Test files in scope: 2
+
+**Phase 2 — Existing Tests**: 2 test files, 8 tests, all passing.
+
+**Phase 3 — Gap Analysis** (excerpt):
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| payment | processPayment() | unit | missing |
+| payment | refund() | unit | missing |
+
+**Phase 4**: Generated 2 unit tests (both passing). No integration/E2E applicable for this scope.
+
+**Phase 5 — Report Summary**:
+```
+Generated: 2 unit tests (all passing)
+Report: .prizmkit/test/2026_05_23_15_00_00_testresult/test-report.md
+All tests passing. Ready for commit.
+```
+
+**HANDOFF:** Independent skill — no handoff. User may proceed to `/prizmkit-committer` if all tests pass, or fix issues manually if tests are marked "needs-review".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.49",
+  "version": "1.1.53",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/scaffold.js

@@ -769,6 +769,11 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
   try {
     execSync('playwright-cli install --skills', { cwd: projectRoot, stdio: 'pipe', timeout: 60000 });
     console.log(chalk.green('      ✓ playwright-cli skills installed'));
+    // playwright-cli creates an empty .playwright directory — remove it
+    const dotPlaywright = path.join(projectRoot, '.playwright');
+    if (fs.pathExistsSync(dotPlaywright)) {
+      fs.removeSync(dotPlaywright);
+    }
   } catch (e) {
     console.log(chalk.yellow(`      ⚠ Skills install skipped: ${e.message}`));
     console.log(chalk.yellow('      ⚠ Run manually: playwright-cli install --skills'));