prizmkit 1.1.40 → 1.1.41

package/bundled/skills/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.

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

@@ -0,0 +1,147 @@
+# deploy.config.json Schema
+
+This file is the machine-readable deployment configuration. Always read it before executing any deploy operation.
+
+## Top-Level Structure
+
+```json
+{
+  "version": 1,
+  "project": "project-name",
+  "deploymentMode": "ssh",
+  "defaults": { ... },
+  "environments": { ... },
+  "servers": [ ... ],
+  "repository": { ... },
+  "apps": [ ... ],
+  "nginx": { ... },
+  "env": { ... }
+}
+```
+
+## defaults
+
+```json
+{
+  "releaseRetention": 5,
+  "credentialMode": "ai-assisted|user-managed",
+  "secretStorage": "ask-every-time|encrypted-local|plaintext-local|user-managed-on-server-only",
+  "rollbackOnFailure": true,
+  "headlessDefaultEnvironment": "test"
+}
+```
+
+## environments
+
+Keyed by environment name. Each entry:
+```json
+{
+  "dev": {
+    "server": "server-id",
+    "allowHeadless": true,
+    "confirmBeforeDeploy": false
+  }
+}
+```
+
+## servers
+
+Array of server objects:
+```json
+{
+  "id": "prod-1",
+  "host": "IP or hostname",
+  "port": 22,
+  "bootstrapUser": "root",
+  "runtimeUser": "deploy",
+  "roles": ["web"],
+  "validated": {
+    "ssh": true|false,
+    "bootstrap": true|false,
+    "runtimeUser": true|false,
+    "tools": {
+      "node": "version",
+      "npm": "version",
+      "pm2": "version",
+      "nginx": "version",
+      "git": "version"
+    },
+    "directories": true|false,
+    "deployKey": true|false
+  }
+}
+```
+
+## repository
+
+```json
+{
+  "url": "git@github.com:owner/repo.git",
+  "branch": "master",
+  "auth": "deploy-key|ssh-agent|token",
+  "validated": {
+    "clone": true|false
+  }
+}
+```
+
+## apps
+
+Array of app objects:
+```json
+{
+  "id": "web",
+  "path": ".",
+  "runtime": "pm2",
+  "packageManager": "npm",
+  "installCommand": "npm ci",
+  "buildCommand": "npm run build",
+  "startCommand": "npm run start",
+  "ports": {
+    "blue": 3101,
+    "green": 3102
+  },
+  "healthChecks": [
+    { "name": "home", "url": "/", "expectedStatus": [200] },
+    { "name": "login", "url": "/login", "expectedStatus": [200, 302] }
+  ],
+  "activeColor": "blue",
+  "pm2Process": "prizm-ideas-blue"
+}
+```
+
+## nginx
+
+```json
+{
+  "enabled": true,
+  "managed": true,
+  "firstChangeRequiresConfirmation": true,
+  "domain": null,
+  "ipFallback": true,
+  "currentUpstream": "127.0.0.1:3101"
+}
+```
+
+## env
+
+```json
+{
+  "strategy": "ai-assisted|user-managed",
+  "required": ["VAR_NAME"],
+  "secrets": ["SECRET_NAME"],
+  "validated": {
+    "allRequiredPresent": true|false
+  }
+}
+```
+
+## Validation Rules
+
+- `version` must be present (always 1 for first version)
+- `servers` must have at least one entry with host and bootstrapUser
+- `repository.url` must be present
+- `apps` must have at least one entry
+- `apps[*].ports.blue` and `apps[*].ports.green` must differ
+- `apps[*].healthChecks` should have at least one entry
+- Environment referenced in `environments` must have a matching server in `servers`

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

@@ -0,0 +1,62 @@
+# Deploy History Record Schema
+
+Each event in `.prizmkit/deploy/deploy-history/<id>.json` follows this schema:
+
+```json
+{
+  "eventId": "<releaseId or event id>",
+  "eventType": "deploy|rollback|status|validation|failed-deploy|user-aborted|takeover|adapter-gap",
+  "timestamp": "<ISO 8601>",
+  "serverId": "<server id from deploy.config.json>",
+  "appIds": ["<app ids involved>"],
+  "branch": "<git branch>",
+  "commitSha": "<full or short commit SHA>",
+  "releasePath": "<full server path, e.g. /var/www/prizm-ideas/releases/20260430-22783a3>",
+  "previousReleasePath": "<previous release path or null for first deploy>",
+  "targetPort": 3101,
+  "targetColor": "blue|green",
+  "previousPort": 3102,
+  "phases": {
+    "preflight": "success|failed|skipped",
+    "prepareRelease": "success|failed|skipped",
+    "fetchCode": "success|failed|skipped",
+    "installDependencies": "success|failed|skipped",
+    "build": "success|failed|skipped",
+    "stageRuntime": "success|failed|skipped",
+    "healthCheck": "success|failed|skipped",
+    "switchTraffic": "success|failed|skipped",
+    "verifyLive": "success|failed|skipped",
+    "cleanupOldReleases": "success|failed|skipped",
+    "recordHistory": "success|failed|skipped"
+  },
+  "healthCheckResults": [
+    {
+      "name": "home",
+      "url": "/",
+      "expected": [200],
+      "actual": 200,
+      "pass": true
+    }
+  ],
+  "rollbackResult": null,
+  "logPath": "<server log path>",
+  "operatorMode": "ai-assisted|user-managed",
+  "notes": "<human-readable summary of what happened>"
+}
+```
+
+## Field Notes
+
+- `eventId`: Use `<releaseId>` for deploy events, `<releaseId>-rollback` for rollbacks.
+- `eventType`: Use `failed-deploy` when deploy fails before traffic switch, `deploy` when it succeeds. Use `adapter-gap` when no adapter exists for the detected project type or target — include `detectedProjectType`, `missingAdapter`, and `fallbackOutput` in the record.
+- `phases`: Only include phases that were attempted. Skip phases that were never reached.
+- `healthCheckResults`: Include all configured health checks. `pass` = actual status matches one of the expected status codes.
+- `rollbackResult`: `null` for non-rollback events, `"success"` or `"failed"` for rollbacks.
+- `notes`: Keep concise but include any anomalies or manual interventions.
+
+## What NOT to record
+
+- Raw secret values or API keys — never.
+- Unsalted hashes of secret values — inferable with rainbow tables.
+- Passphrases or decryption keys — even if hashed.
+- Full environment variable values — presence metadata only (e.g., `{"SUPABASE_KEY": {"present": true}}`).

package/bundled/skills/prizmkit-deploy/references/docker-deploy.md

@@ -0,0 +1,31 @@
+# Docker Deployment Path
+
+Guided deployment when a `Dockerfile` or `docker-compose.yml` is detected, or the user requests Docker deployment.
+
+## Detect and Configure
+
+1. Read `Dockerfile` — extract base image, exposed ports, build steps.
+2. Read `docker-compose.yml` if present — extract services, volumes, environment, ports.
+3. Identify image name: from compose project name or repo directory name.
+4. Identify port mappings: from `EXPOSE`, `ports:` in compose, or ask the user.
+
+## Build and Deploy
+
+1. Build: `docker build -t <project>:<releaseId> .` or `docker compose build`.
+2. Check for running containers with the same name: `docker ps -a --filter name=<project>`.
+3. If a previous container exists:
+   - For blue/green on a server with Nginx: start new container on different port, health check, switch upstream.
+   - For single-container setup: stop old, start new — warn about brief downtime.
+4. Start: `docker run -d --name <project>-<releaseId> -p <port>:<port> <project>:<releaseId>` or `docker compose up -d`.
+5. Health check the new container.
+6. Write deploy-history event.
+
+## Operations
+
+| Command | Docker CLI |
+|---------|-----------|
+| status | `docker ps --filter name=<project>` |
+| logs | `docker logs <container-name> --tail 100` |
+| restart | `docker restart <container-name>` |
+| rollback | `docker stop <new-container> && docker start <old-container>` |
+| cleanup | `docker image prune -a --filter "label=project=<project>"` |

package/bundled/skills/prizmkit-deploy/references/nginx-blue-green.md

@@ -0,0 +1,59 @@
+# Nginx Blue/Green Configuration Template
+
+## Server Block Template
+
+```nginx
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+upstream <project>_backend {
+    server 127.0.0.1:<activePort>;
+}
+
+server {
+    listen 80 default_server;
+    server_name _;
+
+    # PrizmKit managed marker: <project>
+    location / {
+        proxy_pass http://<project>_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Traffic Switch Procedure
+
+When switching from one color to another:
+
+1. Update the `upstream` block: change `server 127.0.0.1:<oldPort>` to `server 127.0.0.1:<newPort>`
+2. Run `nginx -t` to validate syntax
+3. If syntax check passes: `systemctl reload nginx`
+4. If syntax check fails: DO NOT reload. Abort the switch. Report the error.
+
+## Managed Marker
+
+All PrizmKit-generated Nginx config must contain:
+```
+# PrizmKit Managed: <project> — DO NOT EDIT MANUALLY
+```
+
+Before modifying any server block that lacks this marker, ask for user confirmation.
+
+## First-Time Setup
+
+- Disable default nginx site: `rm -f /etc/nginx/sites-enabled/default`
+- Create new config: `/etc/nginx/sites-available/<project>`
+- Symlink: `ln -sf /etc/nginx/sites-available/<project> /etc/nginx/sites-enabled/<project>`
+- Test: `nginx -t`
+- Reload: `systemctl reload nginx`
+
+## Rediscovery of Active Port
+
+If `deploy-metadata.json` is missing, rediscover the active upstream port from Nginx config:
+```
+grep "server 127.0.0.1:" /etc/nginx/sites-available/<project>
+```
+Then match the port against configured blue/green ports to determine active color.

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

@@ -138,7 +138,6 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
      - **Target**: [platform name or "undecided"]
      ```
      → This is intentionally minimal (Quick Scan). Full conventions and deployment details will be added by app-planner or prizmkit-deploy later.
-   - Create `.prizmkit/deploy.md` skeleton from `prizmkit-deploy` template if it does not exist, pre-filling known sections (Prerequisites, basic deployment method)
    - If user selects "Skip — decide later" for BOTH topics: write deferred marker instead:
      ```markdown
      ### Infrastructure
@@ -265,7 +264,6 @@ Infrastructure Quick Scan:
   Database: PostgreSQL (Prisma) — detected from dependencies
   Deployment: Vercel — detected from vercel.json
   → Written to CLAUDE.md ### Infrastructure
-  → Created .prizmkit/deploy.md skeleton
 
 Modules discovered:
   src/routes/     → .prizm-docs/routes.prizm (12 files)

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

@@ -68,9 +68,6 @@ A universal spec + plan generator. Takes a natural-language description of ANY d
    - Behavior preservation strategy (if the task modifies existing behavior — include what must remain unchanged and how to verify)
 5. Cross-check: every goal in spec.md maps to plan components — unmapped goals = coverage gaps
 6. Check alignment with `.prizm-docs/root.prizm` RULES section
-7. **Deployment strategy check** (skip if no deployment impact):
-   - Read `.prizmkit/config.json` `deploy_strategy` field
-   - No strategy and new infra needed → ask user, write to config.json
 
 ### Phase 2: Task Generation (plan.md → Tasks section)
 

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -176,6 +176,10 @@ Detect user intent from their message, then follow the corresponding workflow:
    - Off (default) — Skip adversarial review
    - On — Enable adversarial critic review: an independent AI agent reviews the refactor plan for completeness and the implementation for regressions, missed edge cases, and behavior violations. Adds ~5-10 min per refactor task.
 
+   **Question 4 — Deploy after completion?** (multiSelect: false):
+   - No (default) — Skip deployment after pipeline completes
+   - Yes — Run /prizmkit-deploy automatically after all refactors complete successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any refactor did not complete successfully (status not 'completed' or manually 'skipped').
+
    Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
 
    **Environment variable mapping** (for translating user responses → env vars):
@@ -190,6 +194,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    | Critic: On | `ENABLE_CRITIC=true` |
    | Timeout: value | `SESSION_TIMEOUT=<seconds>` |
    | Stop on failure: On | `STOP_ON_FAILURE=1` |
+   | Deploy: Yes | `ENABLE_DEPLOY=1` |
 
    **Advanced environment variables** (not exposed in interactive menu, pass via `--env`):
 
@@ -214,7 +219,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    ```
    With all options:
    ```bash
-   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 SESSION_TIMEOUT=3600 \
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 SESSION_TIMEOUT=3600 ENABLE_DEPLOY=1 \
      dev-pipeline/run-refactor.sh run .prizmkit/plans/refactor-list.json
    ```
 
@@ -225,7 +230,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    With all options:
    ```bash
    dev-pipeline/launch-refactor-daemon.sh start .prizmkit/plans/refactor-list.json \
-     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5"
+     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 ENABLE_DEPLOY=1"
    ```
 
    **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 8.
@@ -367,6 +372,7 @@ Notes:
 | All refactors blocked/failed | Show status, suggest recovery: `dev-pipeline/reset-refactor.sh <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
 | `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
 | `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
+| Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
 | Permission denied on script | Run `chmod +x dev-pipeline/launch-refactor-daemon.sh dev-pipeline/run-refactor.sh` |
 
 ### Integration Notes

package/package.json

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

package/bundled/dev-pipeline/templates/sections/phase-deploy-verification.md

@@ -1,31 +0,0 @@
-### Local Deploy Verification
-
-You just implemented this feature — you know the project's tech stack and build tools.
-
-1. **Build**: Run the project's build/compile commands. If a required tool is missing, install it first.
-2. **Fix**: If build fails with code errors (type errors, missing imports, config issues), fix them (max 2 rounds), then re-verify.
-3. **Assess and record** — append to context-snapshot.md:
-   - **ALL builds pass** → `## Deploy Verification: PASS` — proceed to commit
-   - **Some builds fail with fixable errors** → fix and re-verify (already handled in step 2)
-   - **Cannot build locally** (missing system-level deps you cannot install) → Record: `## Deploy Verification: PARTIAL — missing system deps (see below)`
-
-Deploy verification does NOT block the commit, but you MUST attempt it.
-
-**Smoke test** (only if build passed and project can be started):
-1. Start the project locally (e.g., `make dev`, `npm start`, `go run .`, etc.)
-2. Verify basic functionality: hit key endpoints, check health routes, confirm the UI loads
-3. Stop the server process you started — do NOT leave it running
-4. Record smoke test results in `## Deploy Verification` section
-
-If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
-
-**Deploy documentation update** — Run `/prizmkit-deploy` ONLY if this feature introduced new infrastructure or deployment-affecting changes:
-- New database, cache, message queue, or external service dependency
-- New environment variables required
-- New build steps or deployment configuration (Dockerfile, CI/CD, cloud config)
-- Changed ports, protocols, or service topology
-
-If none of the above apply (pure application logic change), skip `/prizmkit-deploy`.
-
-
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `deploy-verification` to `"completed"`.