@plumbus/core 0.2.3 → 0.2.4

package/instructions/deployment.md

@@ -1,6 +1,6 @@
 # Deployment
 
-Plumbus applications deploy as up to three services — a **backend** (Fastify API server), a **frontend** (Next.js), and optionally an **admin dashboard** (Next.js) — backed by PostgreSQL and Redis. This document covers production configuration, containerization, and operational readiness.
+Plumbus applications deploy as up to three services — a **backend** (Fastify API server), a **frontend** (Next.js), and optionally an **admin dashboard** (Next.js) — backed by PostgreSQL and Redis.
 
 ## Service Topology
 
@@ -19,46 +19,116 @@ Plumbus applications deploy as up to three services — a **backend** (Fastify A
                                 +-------+  +-------+
 ```
 
-- **Frontend** and **admin** proxy API calls to the backend via server-side route handlers (`app/api/[...path]/route.ts`). Browsers never connect directly to the backend.
+- **Frontend** and **admin** proxy API calls to the backend server-side. Browsers never connect directly to the backend.
 - **Backend** connects to PostgreSQL (data) and Redis (job queue, event dispatch).
 
-## Common Docker Pitfalls
+---
 
-Before diving into Dockerfiles, understand these critical issues that cause the most deployment failures:
+## Docker Rules — MUST follow all of these
 
-### 1. `.plumbus/` is generated — do NOT copy from host
+These rules are critical. Violating any one causes build failures or bloated images.
 
-The `.plumbus/` directory is produced by `plumbus generate`. It may not exist on the host (CI pipelines, fresh clones). **Always run `plumbus generate` inside the Docker build** instead of copying from the host.
+### Rule 1: Generate `.plumbus/` inside Docker
 
-### 2. `.npmrc` is required for frontend builds
+- **DO**: Run `plumbus generate` in a Docker build stage.
+- **DO NOT**: Copy `.plumbus/` from the host. It may not exist in CI/fresh clones.
 
-`@plumbus/ui` provides `next`, `react`, `tailwindcss`, and other packages as transitive dependencies. pnpm does not hoist them by default — the project's `.npmrc` contains `public-hoist-pattern` entries that make these packages visible to Turbopack/Next.js. **If you don't copy `.npmrc` into your Docker image, `pnpm install` will not hoist correctly and `next build` will fail** with "Cannot find module 'next'" or similar resolution errors.
+### Rule 2: Always copy `.npmrc` into Docker images
 
-### 3. pnpm symlinks break when copying `node_modules` between stages
+- **DO**: `COPY .npmrc ./` before `pnpm install`.
+- **DO NOT**: Skip `.npmrc`. It has `public-hoist-pattern` entries required for `next build` to find `next`, `react`, `tailwindcss`.
+- **Symptom if violated**: `Cannot find module 'next'` during build.
 
-pnpm uses symlinks inside `node_modules/`. When you `COPY --from=deps /app/node_modules ./node_modules` into a **new** Docker stage (`FROM base AS build`), the symlinks break. **Use `FROM deps AS build`** — this starts the build stage from the deps layer, preserving the symlink tree intact.
+### Rule 3: Never copy `pnpm-workspace.yaml` with local dev overrides
 
-### 4. Cookie `secure` flag and HTTP-only deployments
+- **DO**: Copy the clean `pnpm-workspace.yaml` (lists only `frontend` and `frontend-admin`).
+- **DO NOT**: Copy a workspace yaml that contains `link:../Plumbus/...` dev overrides.
+- **TIP**: If your project uses `dev:link`/`dev:unlink` scripts to swap workspace configs, make sure the clean version is active before building Docker images.
 
-`plumbus start` sets `secure: true` on auth cookies by default (correct for production TLS). If you deploy behind plain HTTP (no TLS), browsers will silently drop `Secure` cookies, causing infinite login redirect loops. See [HTTP Deployments Without TLS](#http-deployments-without-tls) for the workaround.
+### Rule 4: Use `FROM deps AS build` (preserve pnpm symlinks in build stage)
 
-### 5. Regenerate client types before building frontends
+- **DO**: `FROM deps AS build` — inherits the filesystem with intact symlinks.
+- **DO NOT**: `FROM base AS build` with `COPY --from=deps /app/node_modules ./node_modules`. Docker COPY breaks pnpm symlinks.
 
-The frontend typed client (`frontend/lib/client.ts`) is generated by `plumbus ui generate`. If capability schemas change and you don't regenerate, the frontend build will fail with type errors or the client will be out of sync with the API. **Always run `plumbus ui generate` before building frontend Docker images** — either locally before commit, or as a Docker build stage.
+### Rule 5: Use `pnpm deploy` to isolate frontend dependencies
 
-### 6. `app.config.ts` must use dynamic environment detection
+- **DO**: Run `pnpm --filter {./frontend} deploy --legacy /app/deployed` to create a self-contained directory with flat `node_modules` containing ONLY the frontend's dependencies.
+- **DO NOT**: Build Next.js from the workspace root with all monorepo dependencies visible. pnpm's symlinked store breaks Next.js file tracing, and hoisted layout includes every workspace package.
+- **Why**: `pnpm deploy` creates isolated flat `node_modules` with just the target package's deps. Next.js standalone traces only what the frontend actually needs (~30-40 MB vs ~600+ MB).
 
-Do **not** hardcode `environment: 'development'` in `config/app.config.ts`. In production Docker containers where `NODE_ENV=production`, a hardcoded development environment causes `plumbus start` to skip production safeguards. Use:
+### Rule 6: Never copy full `node_modules` into frontend runner stages
 
-```ts
-environment: (process.env.NODE_ENV === 'production' ? 'production' : 'development')
-```
+- **DO**: Copy ONLY `.next/standalone` and `.next/static` into the runner.
+- **DO NOT**: `COPY --from=deps /app/node_modules ./node_modules` in the runner stage.
+- **Why**: Standalone output already includes all traced modules (~60-80 MB). Copying full `node_modules` adds ~700 MB for no reason.
+- **Target image size**: Frontend/admin images should be ~150-200 MB total, not 800 MB+.
+
+### Rule 7: Strip frontend-only packages from backend prod deps
+
+- **DO**: Create a separate `proddeps` stage that removes `@plumbus/ui` from `package.json` before `npm install --omit=dev`.
+- **DO NOT**: Copy the full `node_modules` (including `@plumbus/ui`) into the backend runner.
+- **Why**: `@plumbus/ui` pulls in `next`, `react`, `react-dom`, `tailwindcss`, `lucide-react` (~300 MB). The backend only needs `@plumbus/core` at runtime.
+- **Target image size**: Backend should be ~500-700 MB, not 1.5 GB+.
+
+### Rule 8: Use `ENV PATH` instead of `npx` for frontend builds
+
+- **DO**: `ENV PATH="/app/deployed/node_modules/.bin:$PATH"` then `RUN next build`.
+- **DO NOT**: `RUN npx next build`.
+- **Why**: With `pnpm deploy`, binaries are in the deployed directory's `node_modules/.bin/`. Adding it to PATH ensures `next` resolves correctly.
+
+### Rule 9: Never run migrations in the entrypoint
+
+- **DO**: Run `npx plumbus migrate apply` as a separate CI/CD step or one-off job.
+- **DO NOT**: Put migration commands in `entrypoint.sh` or Docker init containers.
+- **Why**: In multi-replica deployments, concurrent migrations corrupt data.
+
+### Rule 10: Use dynamic environment detection in `app.config.ts`
+
+- **DO**: `environment: (process.env.NODE_ENV === 'production' ? 'production' : 'development')`
+- **DO NOT**: Hardcode `environment: 'development'`. This causes `plumbus start` to skip production safeguards in Docker.
+
+### Rule 11: Regenerate client types before building frontends
+
+- **DO**: Run `plumbus ui generate` before `next build` if capability schemas changed.
+- **DO NOT**: Build frontends with stale `frontend/lib/client.ts`.
+
+### Rule 12: Set `output: "standalone"` in all `next.config.mjs` files
+
+- **DO**: Add `output: "standalone"` to `next.config.mjs` for every Next.js app (frontend, admin).
+- **DO NOT**: Deploy without standalone output. The app would need full `node_modules` at runtime.
+
+### Rule 13: Add `outputFileTracingExcludes` in `next.config.mjs`
+
+- **DO**: Exclude build/dev tools that are transitive deps of `@plumbus/ui` but not needed at runtime:
+  ```js
+  outputFileTracingExcludes: {
+    "**": [
+      "./node_modules/typescript/**",
+      "./node_modules/@swc/core*/**",
+    ],
+  },
+  ```
+- **Why**: Even with `pnpm deploy`, some transitive deps (typescript, @swc/core) are present via `@plumbus/ui` but unnecessary at runtime. Excluding them saves ~50 MB.
+
+### Rule 14: Clean up test/build tools from backend `node_modules`
+
+- **DO**: After `npm install --omit=dev` in the backend `proddeps` stage, delete transitive deps only needed for testing/building:
+  ```dockerfile
+  RUN npm install --omit=dev && \
+      rm -rf node_modules/@vitest node_modules/vitest \
+             node_modules/playwright-core node_modules/playwright \
+             node_modules/@esbuild node_modules/esbuild \
+             node_modules/typescript
+  ```
+- **Why**: `@plumbus/core` includes vitest, playwright, esbuild, and typescript as dependencies. The backend doesn't need them at runtime.
+
+---
 
 ## Backend Deployment
 
 ### Production Command
 
-Use `plumbus start` for production. It forces production environment, binds to `0.0.0.0`, and requires `AUTH_SECRET`:
+Use `plumbus start` for production:
 
 | Behavior | `plumbus dev` | `plumbus start` |
 |----------|---------------|------------------|
@@ -75,7 +145,7 @@ npx plumbus start --port 3000
 
 ### Runtime File Requirements
 
-The backend uses dynamic resource discovery at startup — it scans the source tree for capabilities, entities, flows, events, and prompts. The following directories **must be present** in the production image:
+These directories **must be present** in the production image:
 
 | Directory | Purpose |
 |-----------|---------|
@@ -88,18 +158,20 @@ The backend uses dynamic resource discovery at startup — it scans the source t
 
 ### Entrypoint Pattern
 
-**CRITICAL**: Do **not** run migrations automatically in the container entrypoint. In multi-replica deployments (Kubernetes, ECS), concurrent migration runs can corrupt data or cause extended downtime. Run migrations as a separate, deliberate step before deploying new containers.
-
 ```sh
-# Run migrations BEFORE deploying new containers (CI/CD step or one-off job):
-npx plumbus migrate apply
-
-# Then deploy. Container entrypoint only starts the server:
+# entrypoint.sh — only starts the server. No migrations here.
 #!/bin/sh
 set -e
 exec npx plumbus start --port 3000
 ```
 
+Migrations run separately:
+
+```sh
+# Run BEFORE deploying new containers (CI/CD step or one-off job):
+npx plumbus migrate apply
+```
+
 ### Health Endpoints
 
 | Endpoint | Purpose | Healthy response |
@@ -109,11 +181,13 @@ exec npx plumbus start --port 3000
 
 Use `/ready` for container health checks and load balancer probes.
 
+---
+
 ## Frontend Deployment
 
 ### Standalone Output
 
-**CRITICAL**: Add `output: "standalone"` to `next.config.mjs` for containerized or self-hosted deployment. Without this, the build requires the full `node_modules` at runtime.
+Add to `next.config.mjs`:
 
 ```js
 const nextConfig = {
@@ -129,18 +203,12 @@ const nextConfig = {
 npx next build
 
 # Run standalone server
-node .next/standalone/<app-dir>/server.js
-```
-
-Set `PORT` and `HOSTNAME` environment variables to control the listening address:
-
-```bash
 PORT=3001 HOSTNAME=0.0.0.0 node .next/standalone/frontend/server.js
 ```
 
 ### Static Assets
 
-After a standalone build, static files live in `.next/static/`. Copy them to the correct path in your deployment:
+After a standalone build, copy static files alongside the server:
 
 ```
 .next/standalone/           # Server code
@@ -149,9 +217,11 @@ After a standalone build, static files live in `.next/static/`. Copy them to the
 
 ### Environment Variables
 
-- `NEXT_PUBLIC_*` variables are inlined at **build time**. Set them before `next build`, not at runtime.
-- `API_BASE_URL` (server-only) controls the backend URL for server-side proxy routes. Set this at runtime to the internal Docker network address (e.g., `http://backend:3000`).
-- `AUTH_SECRET` is required for cookie signing.
+- `NEXT_PUBLIC_*` — inlined at **build time**. Set before `next build`, not at runtime.
+- `API_BASE_URL` — set at **runtime**. Internal Docker network address (e.g., `http://backend:3000`).
+- `AUTH_SECRET` — required for cookie signing.
+
+---
 
 ## Environment Variables Reference
 
@@ -183,26 +253,61 @@ After a standalone build, static files live in `.next/static/`. Copy them to the
 | `AUTH_SECRET` | Runtime | Cookie signing secret |
 | `AUTH_COOKIE_SECURE` | Runtime | Set to `"true"` for TLS, `"false"` for HTTP-only deployments |
 
+---
+
 ## Docker
 
-### Backend Dockerfile (multi-stage)
+### Expected Image Sizes
+
+| Image | Target Size | Too Large If |
+|-------|-------------|--------------|
+| Frontend | ~150-200 MB | > 400 MB |
+| Admin | ~150-200 MB | > 400 MB |
+| Backend | ~500-700 MB | > 1 GB |
+
+If images exceed these sizes, you are likely not using `pnpm deploy` (Rule 5) or not stripping backend deps (Rule 7, Rule 14).
+
+### Backend Dockerfile
 
 ```dockerfile
+# ==============================================================
+# BACKEND DOCKERFILE — Reference template
+# See "Docker Rules" section above for the rationale behind each step.
+# ==============================================================
+
 # ---- Base ----
 FROM node:22-alpine AS base
 RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
-# ---- Dependencies ----
+# ---- Full dependencies (needed for plumbus generate and pnpm build) ----
 FROM base AS deps
-# Do NOT copy pnpm-workspace.yaml — it may contain local dev overrides
-# (link:../Plumbus/...) that don't exist in Docker. Packages resolve from npm.
+# DO NOT copy pnpm-workspace.yaml — it may have local dev overrides.
 COPY package.json pnpm-lock.yaml ./
 RUN pnpm install
 
+# ---- Production dependencies only ----
+# Strip @plumbus/ui and devDependencies — backend doesn't need them at runtime.
+# This saves ~300 MB (next, react, tailwindcss, etc. are excluded).
+# After install, remove test/build tools from @plumbus/core transitive deps.
+FROM node:22-alpine AS proddeps
+WORKDIR /app
+COPY package.json ./
+ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+RUN node -e "\
+  const p = JSON.parse(require('fs').readFileSync('package.json','utf8'));\
+  for (const k of ['@plumbus/ui'])\
+    delete (p.dependencies||{})[k];\
+  delete p.devDependencies;\
+  require('fs').writeFileSync('package.json', JSON.stringify(p, null, 2));" && \
+  npm install --omit=dev && \
+  rm -rf node_modules/@vitest node_modules/vitest \
+         node_modules/playwright-core node_modules/playwright \
+         node_modules/@esbuild node_modules/esbuild \
+         node_modules/typescript
+
 # ---- Generate .plumbus/ ----
-# .plumbus/ is generated — never copy it from the host. Run plumbus generate
-# inside Docker so it always exists and matches the current app/ definitions.
+# DO: Generate inside Docker. DO NOT: Copy from host.
 FROM deps AS generate
 COPY app/ ./app/
 COPY config/ ./config/
@@ -210,6 +315,7 @@ COPY tsconfig.json ./
 RUN npx plumbus generate
 
 # ---- Build ----
+# Uses "FROM deps" to preserve pnpm symlinks (Rule 4).
 FROM deps AS build
 COPY --from=generate /app/.plumbus/ ./.plumbus/
 COPY package.json tsconfig.json ./
@@ -220,65 +326,72 @@ RUN pnpm build
 
 # ---- Runner ----
 FROM node:22-alpine AS runner
-RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 ENV NODE_ENV=production
 RUN addgroup --system --gid 1001 plumbus && \
     adduser --system --uid 1001 plumbus
-COPY --from=deps /app/node_modules ./node_modules
+# Production-only node_modules from proddeps (no @plumbus/ui, no devDeps).
+COPY --from=proddeps /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 COPY --from=generate /app/.plumbus/ ./.plumbus/
 COPY package.json ./
 COPY app/ ./app/
 COPY config/ ./config/
 COPY drizzle/ ./drizzle/
-# Entrypoint starts the production server
 USER plumbus
 EXPOSE 3000
-HEALTHCHECK CMD curl -f http://localhost:3000/ready || exit 1
+HEALTHCHECK CMD wget -q -O /dev/null http://localhost:3000/ready || exit 1
 ENTRYPOINT ["./entrypoint.sh"]
 ```
 
-### Frontend Dockerfile (Next.js standalone)
+### Frontend Dockerfile
+
+For the **admin dashboard**, replace `{./frontend}` with `{./frontend-admin}`, change port 3001 to 3002, and adjust the package filter accordingly.
 
 ```dockerfile
+# ==============================================================
+# FRONTEND DOCKERFILE — Reference template
+# Uses pnpm deploy to isolate frontend deps from the monorepo.
+# See "Docker Rules" section above for the rationale behind each step.
+# ==============================================================
+
 FROM node:22-alpine AS base
 RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
+# ---- Install full workspace (needed for pnpm deploy to resolve deps) ----
 FROM base AS deps
-COPY package.json pnpm-lock.yaml ./
+COPY .npmrc package.json pnpm-lock.yaml pnpm-workspace.yaml ./
 COPY frontend/package.json ./frontend/
-# Copy .npmrc — it contains public-hoist-pattern entries that make
-# next, react, tailwindcss visible to Turbopack. Without it, next build fails.
-COPY .npmrc ./
-# Generate a clean workspace config — don't copy the host's pnpm-workspace.yaml
-RUN printf 'packages:\n  - "frontend"\n' > pnpm-workspace.yaml
+COPY frontend-admin/package.json ./frontend-admin/
 RUN pnpm install
 
-# CRITICAL: Use "FROM deps" (NOT "FROM base") to preserve pnpm symlinks.
-# Copying node_modules between stages with COPY --from breaks pnpm's symlink tree.
+# ---- Deploy + Build ----
+# pnpm deploy creates a self-contained directory with flat node_modules
+# containing ONLY the frontend's dependencies — no backend/root workspace deps.
 FROM deps AS build
 COPY frontend/ ./frontend/
-WORKDIR /app/frontend
-RUN npx next build
+RUN pnpm --filter {./frontend} deploy --legacy /app/deployed
+ENV PATH="/app/deployed/node_modules/.bin:$PATH"
+WORKDIR /app/deployed
+RUN next build
 
+# ---- Runner ----
+# Standalone output only — includes server.js + traced node_modules (~30-40 MB).
+# DO NOT copy node_modules from deps — standalone has everything it needs.
 FROM node:22-alpine AS runner
 WORKDIR /app
 ENV NODE_ENV=production
 RUN addgroup --system --gid 1001 nextjs && \
     adduser --system --uid 1001 nextjs
-COPY --from=build /app/frontend/.next/standalone ./
-COPY --from=build /app/frontend/.next/static ./frontend/.next/static
+COPY --from=build /app/deployed/.next/standalone ./
+COPY --from=build /app/deployed/.next/static ./deployed/.next/static
 USER nextjs
 EXPOSE 3001
-CMD ["node", "frontend/server.js"]
+CMD ["node", "deployed/server.js"]
 ```
 
-> **Why `FROM deps AS build` instead of `FROM base AS build`?**
-> pnpm stores packages in a content-addressable store and creates symlinks inside `node_modules/`. Docker's `COPY --from` creates new files without preserving symlinks. By starting the build stage from the deps layer (`FROM deps`), the existing filesystem (with intact symlinks) is inherited, not copied.
-
-### Docker Compose Topology
+### Docker Compose
 
 ```yaml
 services:
@@ -299,28 +412,47 @@ services:
     depends_on: [backend]
 ```
 
-### Key Docker Considerations
+### .dockerignore
 
-- **Do NOT copy `pnpm-workspace.yaml`** into Docker images. It may contain local dev overrides (`link:../Plumbus/...`) that don't exist in the build context. The backend Dockerfile doesn't need it at all. Frontend Dockerfiles generate a minimal workspace config inline (`printf 'packages: ["frontend"]' > pnpm-workspace.yaml`) to declare the sub-package.
-- **Always copy `.npmrc`** into Docker images (both backend and frontend). It defines `public-hoist-pattern` entries that pnpm needs to make framework-provided packages (`next`, `react`, `tailwindcss`, etc.) visible to the application. Without it, `next build` will fail with module resolution errors.
-- **Generate `.plumbus/` inside Docker** — never rely on it existing on the host. The backend Dockerfile should include a `generate` stage that runs `plumbus generate`. This ensures the manifests always match the current app definitions, even in CI/CD pipelines and fresh clones.
-- **Preserve pnpm symlinks** — use `FROM deps AS build` in frontend Dockerfiles. Do **not** use `FROM base AS build` with `COPY --from=deps /app/node_modules`. Docker's COPY command does not preserve symlinks, which breaks pnpm's package resolution and causes Turbopack/Next.js to fail.
-- **Regenerate client types** — run `plumbus ui generate` before building frontend Docker images. The typed client (`frontend/lib/client.ts`) must match the current capability schemas. If you changed entity or capability definitions without regenerating, the frontend build will fail.
-- **Dependency resolution**: `@plumbus/core` and `@plumbus/ui` are declared as normal dependencies in `package.json`. Without the workspace overrides, `pnpm install` resolves them from the npm registry.
-- **Volumes**: Mount persistent volumes for PostgreSQL data and the `uploads/` directory (user-generated media and exports).
-- **Internal networking**: Frontends connect to backend via Docker service name (e.g., `http://backend:3000`). Set `API_BASE_URL` accordingly.
-- **`NEXT_PUBLIC_API_BASE_URL`**: Set to empty string (`""`) if the frontend uses server-side proxy routes. The proxy route handler reads `API_BASE_URL` at runtime.
-- **File layout**: Place all Docker files (Dockerfiles, compose, entrypoint, env template) in a `docker/` subdirectory. The `.dockerignore` stays at the project root (the build context). Set `context: ..` (parent) in compose `build:` sections so COPY paths resolve from the project root.
+Place at the project root. Must include at minimum:
 
-## HTTP Deployments Without TLS
+```
+node_modules
+.next
+dist
+.turbo
+.git
+uploads
+**/e2e
+docs
+```
+
+### File Layout
+
+Place all Docker files in a `docker/` subdirectory:
+
+```
+docker/
+  Dockerfile.backend
+  Dockerfile.frontend
+  Dockerfile.admin
+  docker-compose.yml
+  entrypoint-backend.sh
+  .env.example
+.dockerignore          # at project root (the build context)
+```
 
-`plumbus start` defaults to `secure: true` for auth cookies — the correct setting for production deployments behind TLS. However, some deployment scenarios (staging servers, internal tools, EC2 without a load balancer) run over plain HTTP.
+Set `context: ..` in compose `build:` sections so COPY paths resolve from the project root.
 
-When `Secure` cookies are set over HTTP, browsers silently refuse to store them. The symptom is an infinite login redirect loop: the auth route sets the cookie, the browser drops it, and the next request redirects back to login.
+---
 
-### Workaround: `AUTH_COOKIE_SECURE` Environment Variable
+## HTTP Deployments Without TLS
+
+`plumbus start` sets `secure: true` on auth cookies by default. If you deploy over plain HTTP (no TLS), browsers silently drop `Secure` cookies, causing infinite login redirect loops.
+
+### Workaround
 
-Frontend auth route handlers should respect an `AUTH_COOKIE_SECURE` environment variable:
+Set `AUTH_COOKIE_SECURE=false` in the environment. Frontend auth route handlers must read it:
 
 ```ts
 // app/api/auth/login/route.ts
@@ -335,20 +467,12 @@ cookies().set("auth_token", token, {
 });
 ```
 
-Set `AUTH_COOKIE_SECURE=false` in your `.env` for HTTP-only deployments. **This is a security trade-off** — always use TLS in production and set `AUTH_COOKIE_SECURE=true`.
+**Security trade-off** — always use TLS in production and set `AUTH_COOKIE_SECURE=true`.
 
-Add to docker-compose environment:
-
-```yaml
-frontend:
-  environment:
-    AUTH_COOKIE_SECURE: "false"  # Set to "true" behind TLS
-```
+---
 
 ## Kubernetes / Helm
 
-The Docker images are self-contained and orchestrator-agnostic. When deploying to Kubernetes:
-
 ### Required Resources
 
 | Resource | Purpose |
@@ -361,11 +485,9 @@ The Docker images are self-contained and orchestrator-agnostic. When deploying t
 | `Secret` | `DB_PASSWORD`, `AUTH_SECRET`, AI provider keys |
 | `ConfigMap` | Non-sensitive config: `DB_HOST`, `AI_DEFAULT_PROVIDER`, etc. |
 
-### Migrations in Kubernetes — Critical
+### Migrations — Critical
 
-**NEVER** run migrations in the container entrypoint or as an init container that runs on every pod replica. In a rolling deployment with multiple pods starting concurrently, parallel migration runs against the same database can corrupt data or cause extended downtime.
-
-Run migrations as a **separate Kubernetes Job** before rolling out new pods:
+**NEVER** run migrations in the entrypoint or in init containers that run per-replica. Run as a **separate Job** before rolling out new pods:
 
 ```yaml
 apiVersion: batch/v1
@@ -397,28 +519,50 @@ readinessProbe:
   periodSeconds: 10
 ```
 
-### Scaling Notes
+### Scaling
 
 - **Backend**: Stateless — safe to scale. All replicas must share the same `AUTH_SECRET`.
 - **Frontends**: Stateless — scale freely behind a load balancer.
-- **Uploads**: Replace the local `uploads/` directory with object storage (S3, GCS) or a `ReadWriteMany` PersistentVolumeClaim.
-- **PostgreSQL / Redis**: Use managed services (RDS, ElastiCache, etc.) or official Helm charts — not the Docker Compose images.
+- **Uploads**: Replace local `uploads/` with object storage (S3, GCS) or a `ReadWriteMany` PVC.
+- **PostgreSQL / Redis**: Use managed services (RDS, ElastiCache) — not the Docker Compose images.
+
+---
 
 ## Production Checklist
 
-- [ ] `plumbus start` used as production server command
-- [ ] `AUTH_SECRET` set to a strong random value (32+ characters)
+### Server
+
+- [ ] `plumbus start` used as production command
+- [ ] `AUTH_SECRET` set to strong random value (32+ chars)
 - [ ] Database SSL enabled (automatic with `plumbus start`)
-- [ ] `plumbus migrate apply` run as a separate step before deployment (NOT in entrypoint)
-- [ ] Health checks configured for `/ready` endpoint
-- [ ] `output: "standalone"` in all `next.config.mjs` files
-- [ ] Persistent volumes for PostgreSQL data and uploads
+- [ ] Migrations run separately — NOT in entrypoint
+- [ ] Health checks on `/ready`
+- [ ] `config/app.config.ts` uses dynamic environment detection
 - [ ] AI provider API keys configured
-- [ ] Redis available for job queue and event dispatch
-- [ ] `.npmrc` copied into all Docker images (frontend and admin)
+- [ ] Redis available for job queue
+
+### Docker — Image Size
+
+- [ ] `output: "standalone"` in all `next.config.mjs` files
+- [ ] Frontend/admin runner copies ONLY `.next/standalone` + `.next/static`
+- [ ] Frontend/admin runner does NOT contain `node_modules` from deps stage
+- [ ] Backend runner uses production-only `node_modules` with `@plumbus/ui` stripped
+- [ ] Image sizes: frontends ~150-200 MB, backend ~500-700 MB
+
+### Docker — Build Correctness
+
+- [ ] `.npmrc` copied into all Docker images
+- [ ] `pnpm deploy --legacy` used to isolate frontend deps (not hoisted full-workspace install)
+- [ ] `ENV PATH="/app/deployed/node_modules/.bin:$PATH"` set before `next build`
+- [ ] `outputFileTracingExcludes` configured in `next.config.mjs` (typescript, @swc/core)
+- [ ] Backend `proddeps` cleans up vitest/playwright/esbuild/typescript after npm install
 - [ ] `.plumbus/` generated inside Docker (not copied from host)
-- [ ] Frontend Dockerfiles use `FROM deps AS build` (not `FROM base AS build`)
-- [ ] `plumbus ui generate` run before building frontend images (client types up to date)
-- [ ] `config/app.config.ts` uses dynamic environment detection (not hardcoded `'development'`)
-- [ ] `AUTH_COOKIE_SECURE` set to `"true"` (or `"false"` only if no TLS — see HTTP deployment section)
-- [ ] `.dockerignore` at project root excludes `node_modules/`, `dist/`, `.git/`, `uploads/`
+- [ ] `plumbus ui generate` run before building frontends
+- [ ] `.dockerignore` excludes `node_modules/`, `dist/`, `.git/`, `uploads/`, `**/e2e/`
+
+### Volumes and Networking
+
+- [ ] Persistent volumes for PostgreSQL data and uploads
+- [ ] `API_BASE_URL` set to Docker service name (e.g., `http://backend:3000`)
+- [ ] `NEXT_PUBLIC_API_BASE_URL` set to empty string `""` (for server-side proxy)
+- [ ] `AUTH_COOKIE_SECURE` set to `"true"` (or `"false"` only for HTTP-only — security trade-off)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",