@brunosps00/dev-workflow 1.7.0 → 1.7.1

package/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
   "author": {
     "name": "Bruno Santos"
   },
-  "homepage": "https://github.com/brunosantos/dev-workflow",
+  "homepage": "https://github.com/brunosps/dev-workflow",
   "license": "MIT",
   "keywords": [
     "ai",

package/README.md

@@ -81,7 +81,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-harness-audit`** | Deterministic health scorecard for the dev-workflow install, agents, wrappers, MCPs, and gates. |
 | **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references. |
 | **`/dw-learn`** | Synthesizes durable decisions (confidence-tagged), bugfixes, deviations, and git history into atomic confidence-weighted **instincts** you approve at `.dw/memory/instincts/`; can propose constitution principles. On-demand and human-in-the-loop — **no always-on observer**. |
-| **`/dw-new-project`** | Bootstrap a new project from empty directory. Stack interview, wraps official `create-*` tools, composes docker-compose for dev, seeds `.env`, scripts, CI, `.dw/rules/`. |
+| **`/dw-new-project`** | Bootstrap a new project from an empty or docs-first directory while preserving existing documentation and prototypes. Stack interview includes Next.js + NestJS, Postgres + pgvector, pg-boss, Mailpit, dev topology, and wraps official `create-*` tools before composing dev infrastructure, `.env`, scripts, CI, and `.dw/rules/`. |
 | **`/dw-dockerize`** | Reads existing project, detects stack + runtime deps, proposes Dockerfile + docker-compose for dev/prod with explicit trade-offs (Conservative/Balanced/Bold). |
 | **`/dw-install-azure-skills`** | **Opt-in.** Clones curated Azure skills from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0) into `.agents/skills/azure/` and registers the [Microsoft Learn MCP Server](https://learn.microsoft.com/en-us/training/support/mcp-get-started) (HTTP, no-auth). Interactive category selection (Compute / Data & Storage / AI & ML / Networking / Identity & Security / DevOps / Observability / Integration / Architecture / All). Re-run to refresh from upstream. Also available as CLI: `npx @brunosps00/dev-workflow install-azure-skills`. |
 | **`/dw-install-aws-skills`** | **Opt-in.** Clones curated AWS skills from [`aws/agent-toolkit-for-aws`](https://github.com/aws/agent-toolkit-for-aws) (Apache 2.0) into `.agents/skills/aws/` and registers the unified [AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/) (stdio via `uvx mcp-proxy-for-aws@latest`). **Requires `uv`, `aws cli ≥ 2.32.0`, and AWS credentials.** Interactive category selection (Core / Analytics / Database / EC2 / Migration / Networking / Operations / Security / Serverless / Storage / All). The agent gains `aws___call_aws` (executes 15,000+ AWS APIs) and `aws___run_script` (Python sandboxed) — review `.dw/references/aws-mcp-instructions.md` for the destructive-operations protocol. Also available as CLI: `npx @brunosps00/dev-workflow install-aws-skills [--region=<aws-region>]`. |

package/lib/install-deps.js

@@ -90,6 +90,7 @@ function run() {
       check: openDesign.check,
       install: openDesign.install,
       instructions: openDesign.instructions(),
+      sync: openDesign.syncProjectAssets,
     },
   ];
 
@@ -122,6 +123,7 @@ function run() {
     try {
       if (typeof dep.check === 'function' && dep.check()) {
         console.log(' \x1b[32m✓ already installed\x1b[0m');
+        runDepSync(dep);
         installed++;
         continue;
       }
@@ -131,6 +133,7 @@ function run() {
         execSync(dep.install, { stdio: 'pipe', timeout: 300000 });
       }
       console.log(' \x1b[32m✓\x1b[0m');
+      runDepSync(dep);
       installed++;
     } catch (err) {
       console.log(' \x1b[31m✗\x1b[0m');
@@ -202,3 +205,15 @@ function printBrowserGuidance() {
 }
 
 module.exports = { run };
+
+function runDepSync(dep) {
+  if (typeof dep.sync !== 'function') return;
+  try {
+    const result = dep.sync();
+    if (result && result.synced === false && result.reason) {
+      console.log(`    (project assets not synced: ${result.reason})`);
+    }
+  } catch (err) {
+    console.log(`    (project asset sync failed: ${err.message})`);
+  }
+}

package/lib/install-open-design.js

@@ -2,6 +2,12 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { COMMANDS } = require('./constants');
+const { copyDir, writeFile, log } = require('./utils');
+const { generateWrappers } = require('./wrappers');
+const { readInstallState } = require('./install-state');
+
+const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 
 const OPEN_DESIGN_REPO = 'https://github.com/nexu-io/open-design';
 const OPEN_DESIGN_REF = '1cb7eae';
@@ -35,6 +41,38 @@ function install() {
   }
 }
 
+/**
+ * Sync the dw-open-design command, scripts and harness wrappers into the
+ * current project. install-deps provisions the od CLI, but the skill lives in
+ * the project scaffold — without this, users only get the command after a
+ * manual `dev-workflow update` (the exact gap reported in the field).
+ */
+function syncProjectAssets(projectRoot = process.cwd()) {
+  const state = readInstallState(projectRoot);
+  if (!state) {
+    return { synced: false, reason: 'no dev-workflow install found in this project (run init/update first)' };
+  }
+  const lang = state.lang && COMMANDS[state.lang] ? state.lang : 'en';
+  const cmd = COMMANDS[lang].find((entry) => entry.name === 'dw-open-design')
+    || COMMANDS.en.find((entry) => entry.name === 'dw-open-design');
+  if (!cmd) {
+    return { synced: false, reason: 'dw-open-design missing from command registry' };
+  }
+
+  const commandSrc = path.join(SCAFFOLD_DIR, lang, 'commands', 'dw-open-design.md');
+  const commandDest = path.join(projectRoot, '.dw', 'commands', 'dw-open-design.md');
+  const status = writeFile(commandDest, fs.readFileSync(commandSrc, 'utf-8'), true);
+  log(status, commandDest);
+
+  const scriptsSrc = path.join(SCAFFOLD_DIR, 'scripts', 'open-design');
+  if (fs.existsSync(scriptsSrc)) {
+    copyDir(scriptsSrc, path.join(projectRoot, '.dw', 'scripts', 'open-design'), true);
+  }
+
+  generateWrappers(projectRoot, [cmd], true);
+  return { synced: true };
+}
+
 function instructions() {
   return [
     'Open Design CLI is provisioned by dev-workflow into a managed checkout:',
@@ -80,6 +118,7 @@ function isAtLeast(actual, minimum) {
 }
 
 module.exports = {
+  syncProjectAssets,
   OPEN_DESIGN_REF,
   OPEN_DESIGN_VENDOR_DIR,
   check,

package/lib/utils.js

@@ -90,6 +90,20 @@ function writeJson(filePath, value) {
   fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + '\n', 'utf-8');
 }
 
+function findStandaloneMarkers(content, marker) {
+  // Marker names also appear in explanatory prose, so only a full marker line delimits a block.
+  const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`^[\\t ]*${escapedMarker}[\\t ]*\\r?$`, 'gm');
+  const markers = [];
+  let match;
+
+  while ((match = pattern.exec(content)) !== null) {
+    const start = match.index + match[0].indexOf(marker);
+    markers.push({ start, end: start + marker.length });
+  }
+  return markers;
+}
+
 /**
  * Upsert a delimited block inside an existing file.
  *
@@ -105,8 +119,19 @@ function upsertDelimitedBlock(filePath, blockContent, startMarker, endMarker) {
 
   // The block content already includes its own start/end markers (so the scaffold
   // file can be read verbatim). Validate that.
-  if (!blockContent.includes(startMarker) || !blockContent.includes(endMarker)) {
-    throw new Error(`Block content for ${filePath} is missing its markers`);
+  const blockStarts = findStandaloneMarkers(blockContent, startMarker);
+  const blockEnds = findStandaloneMarkers(blockContent, endMarker);
+  if (blockStarts.length === 0 || blockEnds.length === 0) {
+    throw new Error(`Block content for ${filePath} is missing standalone markers`);
+  }
+  if (blockStarts.length > 1 || blockEnds.length > 1) {
+    throw new Error(`Block content for ${filePath} has duplicate standalone markers`);
+  }
+
+  const blockStart = blockStarts[0];
+  const blockEnd = blockEnds[0];
+  if (blockEnd.start < blockStart.end) {
+    throw new Error(`Block content for ${filePath} is missing standalone markers`);
   }
 
   if (!exists) {
@@ -115,17 +140,32 @@ function upsertDelimitedBlock(filePath, blockContent, startMarker, endMarker) {
   }
 
   const current = fs.readFileSync(filePath, 'utf-8');
-  const hasMarkers = current.includes(startMarker) && current.includes(endMarker);
+  const currentStarts = findStandaloneMarkers(current, startMarker);
+  const currentEnds = findStandaloneMarkers(current, endMarker);
 
-  if (!hasMarkers) {
+  if (currentStarts.length === 0 && currentEnds.length === 0) {
     const separator = current.endsWith('\n') ? '\n' : '\n\n';
     const next = current + separator + (blockContent.endsWith('\n') ? blockContent : blockContent + '\n');
     fs.writeFileSync(filePath, next, 'utf-8');
     return 'updated';
   }
 
-  const before = current.slice(0, current.indexOf(startMarker));
-  const after = current.slice(current.indexOf(endMarker) + endMarker.length);
+  if (currentStarts.length > 1 || currentEnds.length > 1) {
+    throw new Error(`Existing file ${filePath} has duplicate standalone markers`);
+  }
+
+  if (currentStarts.length !== 1 || currentEnds.length !== 1) {
+    throw new Error(`Existing file ${filePath} has unbalanced standalone markers`);
+  }
+
+  const currentStart = currentStarts[0];
+  const currentEnd = currentEnds[0];
+  if (currentEnd.start < currentStart.end) {
+    throw new Error(`Existing file ${filePath} has unbalanced standalone markers`);
+  }
+
+  const before = current.slice(0, currentStart.start);
+  const after = current.slice(currentEnd.end);
   const next = before + blockContent.trim() + after;
   if (next === current) return 'unchanged';
   fs.writeFileSync(filePath, next, 'utf-8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"
@@ -42,7 +42,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/brunosantos/dev-workflow"
+    "url": "https://github.com/brunosps/dev-workflow"
   },
   "author": "Bruno Santos"
 }

package/scaffold/en/commands/dw-new-project.md

@@ -1,17 +1,17 @@
 <system_instructions>
-You are a workspace bootstrap lead for the dev-workflow ecosystem. Your job is to take an empty (or near-empty) directory, run a Socratic stack interview, and produce a working monorepo or single-app project with: (1) the right framework scaffolds via official `create-*` tools, (2) a `docker-compose.dev.yml` covering every selected dev dependency (db, cache, queue, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, and (4) a seeded `.dw/rules/index.md`.
+You are a workspace bootstrap lead for the dev-workflow ecosystem. Your job is to take an empty, near-empty, or docs-first directory (documentation without application code), run a Socratic stack interview, and produce a working monorepo or single-app project with: (1) the right framework scaffolds via official `create-*` tools, (2) a `docker-compose.dev.yml` covering every selected dev dependency (db, cache, queue, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, and (4) a seeded `.dw/rules/index.md`.
 
 <critical>This command MUST run AFTER `npx dev-workflow init` has populated `.dw/`. If `.dw/commands/` does not exist in the target directory, abort with: "Run `npx @brunosps00/dev-workflow init` first, then re-invoke /dw-new-project."</critical>
 <critical>NEVER touch files outside the new project's directory. The interview captures `{{TARGET_DIR}}`; all writes are scoped under it.</critical>
 <critical>Phase 3 (execution) runs ONLY after the user explicitly approves the plan presented in Phase 2. No flag bypass.</critical>
-<critical>MailHog is the DEFAULT for email-in-dev. The user must explicitly opt out before any other SMTP target is wired into dev.</critical>
+<critical>Mailpit is the DEFAULT for email-in-dev. The user must explicitly opt out before any other SMTP target is wired into dev.</critical>
 
 ## When to Use
 
-- Starting a new project from an empty directory and you want the dev-workflow conventions, containerized infra, and CI scaffolding from day one
+- Starting a new project from an empty or docs-first directory and you want the dev-workflow conventions, containerized infra, and CI scaffolding from day one
 - Replacing manual `pnpm create next-app && create vite ...` ceremony with a guided interview that captures the full dev environment
 - Spinning up a learning sandbox where you want a realistic stack (db + cache + email + observability) without 30 minutes of YAML
-- NOT for adding services to an existing project — use `/dw-dockerize --audit` for that
+- NOT for adding services to a project that already has manifests or application code — use `/dw-dockerize --audit`
 - NOT for adding a new app inside an existing monorepo — that needs a different command (planned for a future release)
 - NOT a replacement for `/dw-plan prd` — this generates the workspace, not the product spec
 
@@ -52,7 +52,7 @@ Execute phases in order. Phase 3 runs ONLY after user approval at the end of Pha
 1. Verify `.dw/commands/` exists in `{{TARGET_DIR}}`. If not, abort with the message above.
 2. Verify Docker is available: run `docker --version` and `docker compose version` (or `docker-compose --version`). If either fails, warn the user and point to `npx @brunosps00/dev-workflow install-deps`. Do NOT abort — the user may want a `--dry-run` plan even without Docker.
 3. Capture `{{PROJECT_NAME}}` (default: kebab-case of CWD basename) and confirm `{{TARGET_DIR}}`.
-4. Confirm the target directory is empty or contains only `.dw/`, `.git/`, `.agents/`, `.claude/`, `.opencode/`. If other files exist, list them and ask whether to proceed (anything else risks clobbering user code).
+4. Classify the target directory as `empty`, `workflow-only`, `docs-first`, or `existing-app`. A docs-first directory may contain documentation, prototypes, assets, and README files, but no application manifests or source directories. List every path that will be preserved and ask for confirmation. If it is an existing app, abort and point to `/dw-dockerize --audit`; never overwrite existing code.
 
 Emit a VERIFICATION REPORT for Phase 0 (Docker version captured, target dir state).
 
@@ -68,21 +68,21 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
 2. **Language(s)**: TypeScript/JavaScript, Python, C#, Rust (per app)
 3. **Framework per layer** (curated list — refuse anything outside):
    - **Frontend**: Next.js (app router), Vite + React (TS template)
-   - **Backend**: FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust), Fastify (Node TS)
-   - **Fullstack** (single bundle): T3 stack (Next.js + tRPC + Prisma + NextAuth), or Next.js front + FastAPI back (separate apps in monorepo)
+   - **Backend**: NestJS or Fastify (Node TS), FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust)
+   - **Fullstack**: T3 stack (single bundle), Next.js + NestJS, or Next.js + FastAPI (separate apps in a monorepo)
 4. **Package manager** (NO default — ask explicitly):
    - For Node: npm / pnpm / yarn
    - For Python: poetry / uv / pip + venv
    - For .NET: dotnet (built-in)
    - For Rust: cargo (built-in)
-5. **If fullstack** — monorepo orchestrator (NO default — ask explicitly): pnpm workspaces, npm workspaces, Turborepo, Nx
+5. **If fullstack** — workspace + task runner (NO default — ask explicitly): package-manager workspaces with native scripts, Turborepo, or Nx. Record combinations such as `pnpm workspaces + Turborepo`.
 
 #### Layer B — Infra (only ask what fits the shape)
 
-6. **Database**: Postgres / MySQL / SQLite (file, no service) / MongoDB (out of scope for compose recipes — note and skip if chosen) / none
+6. **Database**: Postgres / Postgres + pgvector / MySQL / SQLite (file, no service) / MongoDB (out of scope for compose recipes — note and skip if chosen) / none. For Postgres + pgvector, select an explicit supported recipe/version.
 7. **Cache**: Redis / Memcached / none
-8. **Queue / message broker**: BullMQ (Node only), Celery (Python only), RabbitMQ (any), LocalStack SQS (any), none. If chosen, also ask whether the project will have async workers.
-9. **Email — dev capture** (default: **MailHog**, ask only if user wants to override): MailHog / Mailpit / smtp4dev / skip
+8. **Queue / message broker**: pg-boss (Node + Postgres, no extra service), BullMQ (Node + Redis), Celery (Python only), RabbitMQ (any), LocalStack SQS (any), none. If chosen, also ask whether the project will have async workers.
+9. **Email — dev capture** (default: **Mailpit**, ask only if user wants to override): Mailpit / MailHog / smtp4dev / skip
 10. **Email — prod target** (only ask if user wants email at all): SMTP relay / SendGrid / Resend / Postmark / SES / skip
 11. **Object storage**: S3 (real, no service in compose) / MinIO (dev) / GCS (no service) / none
 12. **Search**: Meilisearch / Typesense / Elasticsearch / none
@@ -93,7 +93,8 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
 #### Layer C — Tooling
 
 16. **Auth** (only ask if applicable to chosen stack):
-    - Next.js: NextAuth / Lucia / Clerk / custom JWT / none
+    - Next.js: Auth.js / generic OIDC / Clerk / custom JWT / none
+    - NestJS: generic OIDC / Passport JWT / custom auth / none
     - FastAPI: fastapi-users / authlib / custom JWT / none
     - ASP.NET: built-in Identity / IdentityServer / custom JWT / none
     - Axum: tower-cookies + jsonwebtoken / custom / none
@@ -102,7 +103,8 @@ Use `AskUserQuestion` when available; otherwise plain numbered prompts. Ask in *
     - Python: Ruff + Black / Ruff only
     - C#: dotnet format
     - Rust: rustfmt + clippy (default)
-18. **CI**: GitHub Actions (always seed; user can opt out)
+18. **Dev topology**: apps on host + infrastructure in Compose / everything in Compose. For Node monorepos, recommend apps on host when fast hot reload is the priority.
+19. **CI**: GitHub Actions (always seed; user can opt out)
 
 Save all answers in memory for Phase 2.
 
@@ -133,6 +135,7 @@ Run in this order. Each step emits its own mini-VERIFICATION block.
 | Next.js | `pnpm create next-app@latest <dir> --ts --tailwind --eslint --app --import-alias '@/*' --use-pnpm --no-git` |
 | Vite + React | `pnpm create vite@latest <dir> --template react-ts` |
 | T3 | `pnpm dlx create-t3-app@latest <dir> --noGit --CI --tailwind --trpc --prisma --nextAuth --appRouter` |
+| NestJS | `pnpm dlx @nestjs/cli@latest new <dir> --package-manager pnpm --skip-git --strict` |
 | Fastify | `pnpm create fastify@latest <dir>` then trim interactive prompts; if no non-interactive flag works, generate the structure inline (`src/server.ts` + `src/routes/` + `package.json`) |
 | FastAPI | NO official `create-*`. Generate inline: `pyproject.toml` (with chosen package manager), `app/{routers,models,schemas,deps}/`, `app/main.py`, `tests/` skeleton |
 | ASP.NET Core | `dotnet new webapi -n <name> --use-minimal-apis --auth None` (use `--auth Individual` if Identity was chosen) |
@@ -142,12 +145,12 @@ Adjust the package manager flag per the user's choice (e.g., `--use-npm`, `--use
 
 For **fullstack-T3**: that's it for app code (T3 ships everything in one tree).
 
-For **fullstack-NextJS+FastAPI**: run two scaffolds, then move them into `apps/web/` and `apps/api/`.
+For **fullstack-NextJS+NestJS** or **fullstack-NextJS+FastAPI**: scaffold directly into `apps/web/` and `apps/api/` without moving or deleting pre-existing documentation.
 
 #### 3.2 Compose monorepo (fullstack only)
 
 If fullstack:
-1. Move scaffolded apps under `apps/<name>/`.
+1. If an app was scaffolded outside its final workspace path, move it under `apps/<name>/`. Apps scaffolded directly into `apps/web/` or `apps/api/` are already in place and must not be moved again.
 2. Create `pnpm-workspace.yaml` (or equivalent), root `package.json` with workspace scripts, root `tsconfig.base.json` if shared TS config.
 3. If user picked Turborepo: add `turbo.json` with `dev`, `build`, `lint`, `test` pipelines.
 4. If user picked Nx: run `pnpm dlx nx@latest init` after the apps are in place; integrate them as Nx projects.
@@ -159,7 +162,7 @@ If fullstack:
    - Concatenate selected service blocks under `services:`.
    - Aggregate named volumes under `volumes:`.
    - Resolve port collisions if any.
-   - Add the app service(s) at the end (build context = `apps/<name>` or root, Dockerfile.dev, env_file, volumes, depends_on with `condition: service_healthy` per `references/healthcheck-patterns.md`).
+   - For `everything in Compose`, add the app service(s) at the end (build context = `apps/<name>` or root, Dockerfile.dev, env_file, volumes, depends_on with `condition: service_healthy`). For `apps on host`, compose infrastructure only and use `localhost` endpoints in app-facing environment variables.
 3. Add a header comment: `# Generated by /dw-new-project on YYYY-MM-DD`.
 
 #### 3.4 Generate `.env.example`
@@ -214,7 +217,7 @@ Minimal scaffold:
 | Database | <db or n/a> |
 | Cache | <cache or n/a> |
 | Queue | <queue or n/a> |
-| Email (dev) | <mailhog|mailpit|smtp4dev|none> |
+| Email (dev) | <mailpit|mailhog|smtp4dev|none> |
 | Search | <search or n/a> |
 | Observability | <observability or n/a> |
 | Reverse proxy | <traefik|none> |
@@ -230,7 +233,7 @@ Minimal scaffold:
 ## Conventions
 
 - See `.dw/rules/<module>.md` after `/dw-analyze-project` runs.
-- Email-in-dev uses MailHog by default; the app NEVER sends real mail in dev.
+- Email-in-dev uses Mailpit by default; the app NEVER sends real mail in dev.
 - All env vars live in `.env` (gitignored); `.env.example` is the template.
 ```
 
@@ -273,7 +276,7 @@ date: YYYY-MM-DD
 shape: <frontend|backend|fullstack>
 languages: [typescript, python, ...]
 frameworks: { web: '...', api: '...' }
-services: [postgres, redis, mailhog, ...]
+services: [postgres-pgvector, mailpit, minio, ...]
 package_manager: <pnpm|npm|yarn|poetry|uv|cargo|dotnet>
 monorepo: <pnpm-workspaces|turborepo|nx|none>
 ---
@@ -302,7 +305,7 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 1. `cp .env.example .env` and review credentials.
 2. `pnpm install` (or your chosen package manager).
 3. `pnpm dev:up` to bring up all services. Wait for healthchecks.
-4. Open MailHog UI at http://localhost:8025 to confirm email capture is wired.
+4. Open Mailpit UI at http://localhost:8025 to confirm email capture is wired.
 5. `/dw-plan prd` to draft the first feature.
 6. After your first substantial commit, run `/dw-analyze-project` to enrich `.dw/rules/`.
 ```
@@ -332,7 +335,7 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 - User picks MongoDB → note "MongoDB recipe not bundled in v0.8.0; we'll add app dependencies but you'll need to wire the service manually". Continue.
 - User picks Caddy → same: note as not in bundled recipes; continue without compose service.
 - Port already bound on host → suggest the override env var and continue; do not pick a different port silently.
-- Working tree contains files other than the allowed set → list them and ask explicitly before proceeding.
+- Docs-first working tree → preserve every listed path and write only to approved new paths. Existing app → abort and point to `/dw-dockerize --audit`.
 
 ## Integration With Other dw-* Commands
 

package/scaffold/en/templates/project-onepager.md

@@ -23,20 +23,21 @@ services: []
 |-------|--------|-----------|
 | Shape | frontend / backend / fullstack | [why this shape — single product surface, API for partners, etc.] |
 | Frontend | Next.js / Vite+React / n/a | [why this framework — SSR needs, SPA simplicity, etc.] |
-| Backend | FastAPI / ASP.NET Core minimal / Axum / Fastify / n/a | [why this framework — team expertise, ecosystem, latency targets] |
-| Database | Postgres / MySQL / SQLite / MongoDB / none | [why this DB — relational needs, JSON-heavy, transactional, etc.] |
+| Backend | NestJS / Fastify / FastAPI / ASP.NET Core minimal / Axum / n/a | [why this framework — team expertise, ecosystem, latency targets] |
+| Database | Postgres / Postgres+pgvector / MySQL / SQLite / MongoDB / none | [why this DB — relational, vector, transactional needs, etc.] |
 | Cache | Redis / Memcached / none | [why or why not] |
-| Queue | BullMQ / Celery / RabbitMQ / LocalStack SQS / none | [why or why not + sync vs async workers] |
-| Email — dev | MailHog (default) / Mailpit / smtp4dev / none | [usually MailHog — capture only, never sends real mail] |
+| Queue | pg-boss / BullMQ / Celery / RabbitMQ / LocalStack SQS / none | [why or why not + sync vs async workers] |
+| Email — dev | Mailpit (default) / MailHog / smtp4dev / none | [usually Mailpit — capture only, never sends real mail] |
 | Email — prod | SMTP / SendGrid / Resend / Postmark / SES / none | [why this provider — volume, deliverability, cost] |
 | Object storage | S3 / MinIO (dev) / GCS / none | [why or why not] |
 | Search | Meilisearch / Typesense / Elasticsearch / none | [why this engine — features, scale, simplicity] |
 | Observability | Sentry / OTel + Jaeger / none | [why this approach — error tracking only, full tracing, etc.] |
 | Reverse proxy | Traefik / Caddy / none | [usually only needed for multi-host dev or prod] |
-| Auth | NextAuth / Lucia / Clerk / fastapi-users / dotnet Identity / custom JWT / none | [why this approach — social login needs, B2B, etc.] |
+| Auth | Auth.js / generic OIDC / Clerk / fastapi-users / dotnet Identity / custom JWT / none | [why this approach — social login needs, B2B, etc.] |
 | Linter / formatter | Biome / ESLint+Prettier / Ruff+Black / dotnet format / cargo fmt+clippy | [team preference] |
 | Package manager | pnpm / npm / yarn / poetry / uv / cargo / dotnet | [team preference] |
-| Monorepo orchestrator | pnpm workspaces / npm workspaces / Turborepo / Nx / n/a | [only for fullstack — caching/build needs] |
+| Workspace + task runner | pnpm workspaces + Turborepo / npm workspaces / Nx / n/a | [only for fullstack — caching/build needs] |
+| Dev topology | apps on host / everything in Compose | [hot reload versus environment parity] |
 | CI | GitHub Actions / none | [usually GitHub Actions; opt out only for non-public repos] |
 
 ## Services & Infra
@@ -47,7 +48,7 @@ services: []
 |---------|-------------|----|--------------------|
 | postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
 | redis | 6379 | — | (no auth in dev) |
-| mailhog | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (no auth) |
+| mailpit | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (no auth) |
 | ... | ... | ... | ... |
 
 ## Architecture Diagram
@@ -59,12 +60,12 @@ services: []
 [ Browser ] -> [ Next.js (apps/web) ]
 
 # Fullstack
-[ Browser ] -> [ Next.js (apps/web) ] -> [ FastAPI (apps/api) ] -> [ Postgres ]
+[ Browser ] -> [ Next.js (apps/web) ] -> [ NestJS (apps/api) ] -> [ Postgres ]
                                                                 |-> [ Redis ]
-                                                                |-> [ MailHog ]
+                                                                |-> [ Mailpit ]
 
 # With observability
-... -> [ FastAPI ] -> { OTLP } -> [ Jaeger ]
+... -> [ NestJS ] -> { OTLP } -> [ Jaeger ]
 ```
 
 ## Generated Files
@@ -75,7 +76,7 @@ services: []
 {{TARGET_DIR}}/
 ├── apps/
 │   ├── web/                      (created by `pnpm create next-app`)
-│   └── api/                      (inline scaffold — FastAPI)
+│   └── api/                      (created by `pnpm dlx @nestjs/cli` or selected scaffold)
 ├── packages/
 │   └── shared/                   (created by /dw-new-project)
 ├── docker-compose.dev.yml        (composed from .agents/skills/docker-compose-recipes/)

package/scaffold/pt-br/commands/dw-new-project.md

@@ -1,17 +1,17 @@
 <system_instructions>
-Voce e o lider de bootstrap de workspace do dev-workflow. Sua funcao e pegar um diretorio vazio (ou quase vazio), rodar uma entrevista socratica de stack e produzir um monorepo ou app unico funcional com: (1) os scaffolds de framework certos via tools `create-*` oficiais, (2) um `docker-compose.dev.yml` cobrindo cada dependencia de dev escolhida (db, cache, fila, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, e (4) um `.dw/rules/index.md` semeado.
+Voce e o lider de bootstrap de workspace do dev-workflow. Sua funcao e pegar um diretorio vazio, quase vazio ou docs-first (documentacao sem codigo de aplicacao), rodar uma entrevista socratica de stack e produzir um monorepo ou app unico funcional com: (1) os scaffolds de framework certos via tools `create-*` oficiais, (2) um `docker-compose.dev.yml` cobrindo cada dependencia de dev escolhida (db, cache, fila, email, storage, search, observability, proxy), (3) `.env.example`, scripts, `.gitignore`, `.dockerignore`, GitHub Action, README, e (4) um `.dw/rules/index.md` semeado.
 
 <critical>Este comando RODA APOS `npx dev-workflow init` ja ter populado o `.dw/`. Se `.dw/commands/` nao existir no diretorio alvo, aborte com: "Rode `npx @brunosps00/dev-workflow init` primeiro, depois reinvoque /dw-new-project."</critical>
 <critical>NUNCA toque arquivos fora do diretorio do novo projeto. A entrevista captura `{{TARGET_DIR}}`; toda escrita fica escopada ali.</critical>
 <critical>A Fase 3 (execucao) so roda apos o usuario aprovar explicitamente o plano apresentado na Fase 2. Sem flag de bypass.</critical>
-<critical>MailHog e o DEFAULT para email-em-dev. O usuario tem que optar OUT explicitamente antes de qualquer outro destino SMTP ser ligado em dev.</critical>
+<critical>Mailpit e o DEFAULT para email-em-dev. O usuario tem que optar OUT explicitamente antes de qualquer outro destino SMTP ser ligado em dev.</critical>
 
 ## Quando Usar
 
-- Comecando um projeto novo de diretorio vazio e voce quer as convencoes do dev-workflow, infra containerizada e CI prontos do dia 1
+- Comecando um projeto novo de diretorio vazio ou docs-first e voce quer as convencoes do dev-workflow, infra containerizada e CI prontos do dia 1
 - Substituindo o ritual manual de `pnpm create next-app && create vite ...` por uma entrevista guiada que captura o ambiente de dev inteiro
 - Subindo uma sandbox de aprendizado onde voce quer um stack realista (db + cache + email + observability) sem 30 minutos de YAML
-- NAO use para adicionar servicos a um projeto existente — use `/dw-dockerize --audit`
+- NAO use para adicionar servicos a um projeto que ja tenha manifests ou codigo de aplicacao — use `/dw-dockerize --audit`
 - NAO use para adicionar app novo dentro de um monorepo existente — outra release vai cobrir isso
 - NAO substitui `/dw-plan prd` — este aqui gera o workspace, nao a spec do produto
 
@@ -52,7 +52,7 @@ Execute as fases em ordem. A Fase 3 so roda apos a aprovacao do usuario no fim d
 1. Verifique se `.dw/commands/` existe em `{{TARGET_DIR}}`. Se nao, aborte com a mensagem acima.
 2. Verifique Docker: `docker --version` e `docker compose version` (ou `docker-compose --version`). Se algum falhar, avise e aponte `npx @brunosps00/dev-workflow install-deps`. NAO aborte — o usuario pode querer um `--dry-run` mesmo sem Docker.
 3. Capture `{{PROJECT_NAME}}` (default: kebab-case do basename do CWD) e confirme `{{TARGET_DIR}}`.
-4. Confirme que o diretorio alvo esta vazio ou contem so `.dw/`, `.git/`, `.agents/`, `.claude/`, `.opencode/`. Se houver outros arquivos, liste e pergunte se procede (qualquer outra coisa pode sobrescrever codigo do usuario).
+4. Classifique o diretorio alvo: `empty`, `workflow-only`, `docs-first` ou `existing-app`. `docs-first` pode conter documentacao, prototipos, assets e README, mas nao manifests nem diretorios de codigo de aplicacao. Liste os paths que serao preservados e peca confirmacao. Se for `existing-app`, aborte e indique `/dw-dockerize --audit`; nunca sobreponha codigo existente.
 
 Emita VERIFICATION REPORT da Fase 0 (versao do Docker capturada, estado do diretorio).
 
@@ -68,21 +68,21 @@ Use `AskUserQuestion` quando disponivel; senao prompts numerados. Pergunte em **
 2. **Linguagem(s)**: TypeScript/JavaScript, Python, C#, Rust (por app)
 3. **Framework por camada** (lista curada — recuse fora dela):
    - **Frontend**: Next.js (app router), Vite + React (template TS)
-   - **Backend**: FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust), Fastify (Node TS)
-   - **Fullstack** (bundle unico): T3 stack (Next.js + tRPC + Prisma + NextAuth), ou Next.js front + FastAPI back (apps separados em monorepo)
+   - **Backend**: NestJS ou Fastify (Node TS), FastAPI (Python), ASP.NET Core minimal API (C#), Axum (Rust)
+   - **Fullstack**: T3 stack (bundle unico), Next.js + NestJS ou Next.js + FastAPI (apps separados em monorepo)
 4. **Package manager** (SEM default — perguntar explicitamente):
    - Node: npm / pnpm / yarn
    - Python: poetry / uv / pip + venv
    - .NET: dotnet (built-in)
    - Rust: cargo (built-in)
-5. **Se fullstack** — orchestrator do monorepo (SEM default — perguntar): pnpm workspaces, npm workspaces, Turborepo, Nx
+5. **Se fullstack** — workspace + task runner (SEM default — perguntar): workspaces do package manager com scripts nativos, Turborepo ou Nx. Registre combinacoes como `pnpm workspaces + Turborepo`.
 
 #### Camada B — Infra (so pergunte o que cabe na forma)
 
-6. **Database**: Postgres / MySQL / SQLite (arquivo, sem service) / MongoDB (fora do escopo dos compose recipes — anote e siga sem service se escolhido) / nenhum
+6. **Database**: Postgres / Postgres + pgvector / MySQL / SQLite (arquivo, sem service) / MongoDB (fora do escopo dos compose recipes — anote e siga sem service se escolhido) / nenhum. Para Postgres + pgvector, selecione explicitamente a recipe/version suportada.
 7. **Cache**: Redis / Memcached / nenhum
-8. **Fila / message broker**: BullMQ (so Node), Celery (so Python), RabbitMQ (qualquer), LocalStack SQS (qualquer), nenhum. Se escolheu, pergunte tambem se vai ter workers async.
-9. **Email — captura em dev** (default: **MailHog**, so pergunte se quer override): MailHog / Mailpit / smtp4dev / pular
+8. **Fila / message broker**: pg-boss (Node + Postgres, sem service extra), BullMQ (so Node + Redis), Celery (so Python), RabbitMQ (qualquer), LocalStack SQS (qualquer), nenhum. Se escolheu, pergunte tambem se vai ter workers async.
+9. **Email — captura em dev** (default: **Mailpit**, so pergunte se quer override): Mailpit / MailHog / smtp4dev / pular
 10. **Email — destino em prod** (so pergunte se quer email): SMTP relay / SendGrid / Resend / Postmark / SES / pular
 11. **Object storage**: S3 (real, sem service) / MinIO (dev) / GCS (sem service) / nenhum
 12. **Search**: Meilisearch / Typesense / Elasticsearch / nenhum
@@ -93,7 +93,8 @@ Use `AskUserQuestion` quando disponivel; senao prompts numerados. Pergunte em **
 #### Camada C — Tooling
 
 16. **Auth** (so pergunte se aplicavel ao stack):
-    - Next.js: NextAuth / Lucia / Clerk / JWT custom / nenhum
+    - Next.js: Auth.js / OIDC generico / Clerk / JWT custom / nenhum
+    - NestJS: OIDC generico / Passport JWT / auth custom / nenhum
     - FastAPI: fastapi-users / authlib / JWT custom / nenhum
     - ASP.NET: Identity built-in / IdentityServer / JWT custom / nenhum
     - Axum: tower-cookies + jsonwebtoken / custom / nenhum
@@ -102,7 +103,8 @@ Use `AskUserQuestion` quando disponivel; senao prompts numerados. Pergunte em **
     - Python: Ruff + Black / Ruff so
     - C#: dotnet format
     - Rust: rustfmt + clippy (default)
-18. **CI**: GitHub Actions (sempre seed; usuario pode optar OUT)
+18. **Topologia de dev**: apps no host + infra no Compose / tudo no Compose. Para monorepo Node, recomende apps no host quando hot reload for prioridade.
+19. **CI**: GitHub Actions (sempre seed; usuario pode optar OUT)
 
 Guarde todas as respostas para a Fase 2.
 
@@ -133,6 +135,7 @@ Rode nesta ordem. Cada passo emite seu mini-VERIFICATION block.
 | Next.js | `pnpm create next-app@latest <dir> --ts --tailwind --eslint --app --import-alias '@/*' --use-pnpm --no-git` |
 | Vite + React | `pnpm create vite@latest <dir> --template react-ts` |
 | T3 | `pnpm dlx create-t3-app@latest <dir> --noGit --CI --tailwind --trpc --prisma --nextAuth --appRouter` |
+| NestJS | `pnpm dlx @nestjs/cli@latest new <dir> --package-manager pnpm --skip-git --strict` |
 | Fastify | `pnpm create fastify@latest <dir>` (corte prompts interativos; se nenhuma flag servir, gere a estrutura inline com `src/server.ts` + `src/routes/` + `package.json`) |
 | FastAPI | SEM `create-*` oficial. Gere inline: `pyproject.toml` (com o package manager escolhido), `app/{routers,models,schemas,deps}/`, `app/main.py`, esqueleto de `tests/` |
 | ASP.NET Core | `dotnet new webapi -n <name> --use-minimal-apis --auth None` (use `--auth Individual` se Identity foi escolhido) |
@@ -142,12 +145,12 @@ Ajuste a flag de package manager para a escolha do usuario (ex.: `--use-npm`, `-
 
 Para **fullstack-T3**: e so isso (T3 entrega tudo numa arvore so).
 
-Para **fullstack-NextJS+FastAPI**: rode dois scaffolds, depois mova para `apps/web/` e `apps/api/`.
+Para **fullstack-NextJS+NestJS** ou **fullstack-NextJS+FastAPI**: rode dois scaffolds diretamente em `apps/web/` e `apps/api/`, sem mover ou apagar documentacao preexistente.
 
 #### 3.2 Compor monorepo (so se fullstack)
 
 Se fullstack:
-1. Mova os apps scaffoldados para `apps/<nome>/`.
+1. Se um app foi scaffoldado fora do caminho final do workspace, mova-o para `apps/<nome>/`. Apps scaffoldados diretamente em `apps/web/` ou `apps/api/` ja estao no lugar e nao devem ser movidos novamente.
 2. Crie `pnpm-workspace.yaml` (ou equivalente), `package.json` raiz com scripts de workspace, `tsconfig.base.json` se TS config compartilhado.
 3. Se o usuario escolheu Turborepo: adicione `turbo.json` com pipelines `dev`, `build`, `lint`, `test`.
 4. Se o usuario escolheu Nx: rode `pnpm dlx nx@latest init` apos os apps estarem no lugar; integre como projetos Nx.
@@ -159,7 +162,7 @@ Se fullstack:
    - Concatene blocos sob `services:`.
    - Agregue volumes nomeados sob `volumes:`.
    - Resolva colisoes de porta se houver.
-   - Adicione o(s) service(s) do app no fim (build context = `apps/<nome>` ou raiz, Dockerfile.dev, env_file, volumes, depends_on com `condition: service_healthy` segundo `references/healthcheck-patterns.md`).
+   - Se a topologia for `tudo no Compose`, adicione o(s) service(s) do app no fim (build context = `apps/<nome>` ou raiz, Dockerfile.dev, env_file, volumes, depends_on com `condition: service_healthy`). Se for `apps no host`, componha apenas infraestrutura e use endpoints `localhost` nas env vars consumidas pelas apps.
 3. Adicione header: `# Generated by /dw-new-project on YYYY-MM-DD`.
 
 #### 3.4 Gerar `.env.example`
@@ -214,7 +217,7 @@ Scaffold minimo:
 | Database | <db ou n/a> |
 | Cache | <cache ou n/a> |
 | Fila | <fila ou n/a> |
-| Email (dev) | <mailhog|mailpit|smtp4dev|nenhum> |
+| Email (dev) | <mailpit|mailhog|smtp4dev|nenhum> |
 | Search | <search ou n/a> |
 | Observability | <observability ou n/a> |
 | Reverse proxy | <traefik|nenhum> |
@@ -230,7 +233,7 @@ Scaffold minimo:
 ## Convencoes
 
 - Veja `.dw/rules/<modulo>.md` apos o `/dw-analyze-project` rodar.
-- Email em dev usa MailHog por default; o app NUNCA envia email real em dev.
+- Email em dev usa Mailpit por default; o app NUNCA envia email real em dev.
 - Toda env var vive em `.env` (gitignored); `.env.example` e o template.
 ```
 
@@ -273,7 +276,7 @@ date: YYYY-MM-DD
 shape: <frontend|backend|fullstack>
 languages: [typescript, python, ...]
 frameworks: { web: '...', api: '...' }
-services: [postgres, redis, mailhog, ...]
+services: [postgres-pgvector, mailpit, minio, ...]
 package_manager: <pnpm|npm|yarn|poetry|uv|cargo|dotnet>
 monorepo: <pnpm-workspaces|turborepo|nx|none>
 ---
@@ -302,7 +305,7 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 1. `cp .env.example .env` e revise credenciais.
 2. `pnpm install` (ou seu package manager).
 3. `pnpm dev:up` para subir todos os servicos. Aguarde os healthchecks.
-4. Abra a UI do MailHog em http://localhost:8025 para confirmar a captura de email.
+4. Abra a UI do Mailpit em http://localhost:8025 para confirmar a captura de email.
 5. `/dw-plan prd` para a primeira feature.
 6. Apos o primeiro commit substancial, rode `/dw-analyze-project` para enriquecer `.dw/rules/`.
 ```
@@ -332,7 +335,7 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 - Usuario escolhe MongoDB → anote "Recipe MongoDB nao bundled na v0.8.0; vamos adicionar deps de app mas voce vai precisar ligar o servico manualmente". Continue.
 - Usuario escolhe Caddy → idem: anote como nao bundled; siga sem servico no compose.
 - Porta ja ocupada no host → sugira a env var de override e siga; nao escolha outra porta em silencio.
-- Working tree contem arquivos fora do conjunto permitido → liste e pergunte explicitamente antes de prosseguir.
+- Working tree docs-first → preserve cada path listado e escreva apenas nos novos paths aprovados. Existing app → aborte e indique `/dw-dockerize --audit`.
 
 ## Integracao com Outros dw-* Commands
 

package/scaffold/pt-br/templates/project-onepager.md

@@ -23,20 +23,21 @@ services: []
 |--------|---------|---------------|
 | Forma | frontend / backend / fullstack | [por que essa forma — superficie unica, API para parceiros, etc.] |
 | Frontend | Next.js / Vite+React / n/a | [por que esse framework — SSR, simplicidade SPA, etc.] |
-| Backend | FastAPI / ASP.NET Core minimal / Axum / Fastify / n/a | [por que — expertise do time, ecosystem, alvo de latencia] |
-| Database | Postgres / MySQL / SQLite / MongoDB / nenhum | [por que esse DB — relacional, JSON-heavy, transacional, etc.] |
+| Backend | NestJS / Fastify / FastAPI / ASP.NET Core minimal / Axum / n/a | [por que — expertise do time, ecosystem, alvo de latencia] |
+| Database | Postgres / Postgres+pgvector / MySQL / SQLite / MongoDB / nenhum | [por que esse DB — relacional, vetorial, transacional, etc.] |
 | Cache | Redis / Memcached / nenhum | [por que ou por que nao] |
-| Fila | BullMQ / Celery / RabbitMQ / LocalStack SQS / nenhum | [por que ou nao + sync vs async workers] |
-| Email — dev | MailHog (default) / Mailpit / smtp4dev / nenhum | [normalmente MailHog — captura only, nunca envia real] |
+| Fila | pg-boss / BullMQ / Celery / RabbitMQ / LocalStack SQS / nenhum | [por que ou nao + sync vs async workers] |
+| Email — dev | Mailpit (default) / MailHog / smtp4dev / nenhum | [normalmente Mailpit — captura only, nunca envia real] |
 | Email — prod | SMTP / SendGrid / Resend / Postmark / SES / nenhum | [por que esse provider — volume, deliverability, custo] |
 | Object storage | S3 / MinIO (dev) / GCS / nenhum | [por que ou nao] |
 | Search | Meilisearch / Typesense / Elasticsearch / nenhum | [por que esse engine — features, escala, simplicidade] |
 | Observability | Sentry / OTel + Jaeger / nenhum | [por que essa abordagem — so error tracking, tracing completo, etc.] |
 | Reverse proxy | Traefik / Caddy / nenhum | [normalmente so multi-host dev ou prod] |
-| Auth | NextAuth / Lucia / Clerk / fastapi-users / dotnet Identity / JWT custom / nenhum | [por que — social login, B2B, etc.] |
+| Auth | Auth.js / OIDC generico / Clerk / fastapi-users / dotnet Identity / JWT custom / nenhum | [por que — social login, B2B, etc.] |
 | Linter / formatter | Biome / ESLint+Prettier / Ruff+Black / dotnet format / cargo fmt+clippy | [preferencia do time] |
 | Package manager | pnpm / npm / yarn / poetry / uv / cargo / dotnet | [preferencia do time] |
-| Monorepo orchestrator | pnpm workspaces / npm workspaces / Turborepo / Nx / n/a | [so para fullstack — caching/build] |
+| Workspace + task runner | pnpm workspaces + Turborepo / npm workspaces / Nx / n/a | [so para fullstack — caching/build] |
+| Topologia de dev | apps no host / tudo no Compose | [trade-off de hot reload e paridade] |
 | CI | GitHub Actions / nenhum | [normalmente GitHub Actions; pular so para repos nao-publicos] |
 
 ## Servicos & Infra
@@ -47,7 +48,7 @@ services: []
 |---------|--------------|----|--------------------|
 | postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
 | redis | 6379 | — | (sem auth em dev) |
-| mailhog | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (sem auth) |
+| mailpit | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (sem auth) |
 | ... | ... | ... | ... |
 
 ## Diagrama da Arquitetura
@@ -59,12 +60,12 @@ services: []
 [ Browser ] -> [ Next.js (apps/web) ]
 
 # Fullstack
-[ Browser ] -> [ Next.js (apps/web) ] -> [ FastAPI (apps/api) ] -> [ Postgres ]
+[ Browser ] -> [ Next.js (apps/web) ] -> [ NestJS (apps/api) ] -> [ Postgres ]
                                                                 |-> [ Redis ]
-                                                                |-> [ MailHog ]
+                                                                |-> [ Mailpit ]
 
 # Com observability
-... -> [ FastAPI ] -> { OTLP } -> [ Jaeger ]
+... -> [ NestJS ] -> { OTLP } -> [ Jaeger ]
 ```
 
 ## Arquivos Gerados
@@ -75,7 +76,7 @@ services: []
 {{TARGET_DIR}}/
 ├── apps/
 │   ├── web/                      (criado por `pnpm create next-app`)
-│   └── api/                      (scaffold inline — FastAPI)
+│   └── api/                      (criado por `pnpm dlx @nestjs/cli` ou scaffold escolhido)
 ├── packages/
 │   └── shared/                   (criado pelo /dw-new-project)
 ├── docker-compose.dev.yml        (composto a partir de .agents/skills/docker-compose-recipes/)

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docker-compose-recipes
-description: Use for docker-compose service blocks (postgres, redis, mailhog, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
+description: Use for docker-compose service blocks (postgres, pgvector, redis, mailpit, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
 allowed-tools:
   - Read
   - Write
@@ -49,13 +49,14 @@ Each row points to `services/<name>.yml`.
 | Service | Use | Default port(s) | Recipe |
 |---------|-----|-----------------|--------|
 | Postgres 16 (alpine) | Relational DB | `5432` | `services/postgres.yml` |
+| PostgreSQL 18 + pgvector 0.8.2 | Relational + vector DB | `5432` | `services/postgres-pgvector.yml` |
 | MySQL 8 | Relational DB | `3306` | `services/mysql.yml` |
 | Redis 7 (alpine) | Cache, pub/sub, BullMQ backend | `6379` | `services/redis.yml` |
 | Memcached 1.6 (alpine) | Cache | `11211` | `services/memcached.yml` |
 | RabbitMQ 3 (management-alpine) | Message broker + UI | `5672`, UI `15672` | `services/rabbitmq.yml` |
 | LocalStack | AWS-compatible local (S3, SQS, SNS, DynamoDB) | `4566` | `services/localstack.yml` |
-| MailHog | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
-| Mailpit | Modern MailHog alternative | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
+| Mailpit | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
+| MailHog | Legacy email capture alternative | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
 | smtp4dev | Windows-friendly SMTP capture | SMTP `2525`, UI `5000` | `services/smtp4dev.yml` |
 | MinIO | S3-compatible local | API `9000`, UI `9001` | `services/minio.yml` |
 | Meilisearch | Search engine (lightweight) | `7700` | `services/meilisearch.yml` |
@@ -76,12 +77,12 @@ Each row points to `services/<name>.yml`.
 - **Pin major.minor** in every `image:` line. Patch updates are safe; major bumps are deliberate.
 - **Always include healthcheck**. No service is allowed to be opaque about readiness.
 - **Default to dev**. Prod transforms are explicit (see `prod-vs-dev.md`).
-- **Email-in-dev defaults to MailHog**. The user must opt OUT of capture-only email for dev — never silently route to a real SMTP.
+- **Email-in-dev defaults to Mailpit**. The user must opt OUT of capture-only email for dev — never silently route to a real SMTP.
 - **Secrets never in the recipe**. Env vars reference `.env`; defaults in the recipe are OK only for non-secret config.
 
 ## Inspired by
 
-Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `mailhog/mailhog`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
+Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `pgvector/pgvector`, `redis`, `axllent/mailpit`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
 
 ## Structured Return
 

package/scaffold/skills/docker-compose-recipes/references/compose-composition.md

@@ -4,7 +4,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 
 ## The merge algorithm
 
-1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres, redis, mailhog, minio]`.
+1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres-pgvector, mailpit, minio]`.
 2. **Read each `services/<name>.yml`** as a standalone fragment. Each file declares ONE top-level service block (e.g., `postgres:`) plus comments at the bottom describing the volumes block to merge.
 3. **Concatenate under a single `services:` map.** Indent each block under `services:` in the final file. Order does not matter for compose, but for readability sort by tier: storage → cache/queue → search → email → observability → proxy.
 4. **Collect the volumes.** Each recipe's comments list the named volumes it needs. Aggregate them under a top-level `volumes:` block. Example:
@@ -31,7 +31,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
          condition: service_healthy
    ```
 
-8. **Add the app service(s) at the end.** For monorepo projects, declare an `api` service (and `web` if backend serves the frontend) that builds from the local Dockerfile.dev and binds the source as a volume for hot reload.
+8. **Apply the selected dev topology.** For `everything in Compose`, add the app service(s) at the end and bind source for hot reload. For `apps on host`, do not generate app services or Dockerfile.dev files; expose only infrastructure ports and point application-facing env vars at `localhost`.
 
 ## Final file shape
 
@@ -42,15 +42,15 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 services:
   # --- storage tier ---
   postgres:
-    # ... contents from services/postgres.yml
+    # ... contents from services/postgres-pgvector.yml
 
   # --- cache tier ---
   redis:
     # ... contents from services/redis.yml
 
   # --- email-in-dev (capture only) ---
-  mailhog:
-    # ... contents from services/mailhog.yml
+  mailpit:
+    # ... contents from services/mailpit.yml
 
   # --- object storage ---
   minio:
@@ -72,8 +72,8 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
-      mailhog:
-        condition: service_started
+      mailpit:
+        condition: service_healthy
       minio:
         condition: service_healthy
 

package/scaffold/skills/docker-compose-recipes/references/env-conventions.md

@@ -23,7 +23,9 @@ POSTGRES_PORT=5432
 DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
 ```
 
-Compose performs variable substitution in `.env` references, so the application sees `DATABASE_URL` already-resolved.
+Compose performs variable substitution in `.env` references. When the application also runs in Compose, use service DNS such as `postgres`; when applications run on the host, the committed example must use `localhost` and the published host port instead.
+
+For the PostgreSQL + pgvector recipe, use the same connection variables. The image provides the extension binaries, but `CREATE EXTENSION IF NOT EXISTS vector` belongs in the application's reviewed migrations, not container startup scripts.
 
 ## What goes in `.env.example` vs `.env`
 

package/scaffold/skills/docker-compose-recipes/references/healthcheck-patterns.md

@@ -13,7 +13,7 @@ Every recipe ships a healthcheck. App services that depend on infra MUST gate st
 | RabbitMQ | `rabbitmq-diagnostics ping` | Built-in; takes ~30s to be ready, hence `start_period: 30s` |
 | LocalStack | `curl -sf http://localhost:4566/_localstack/health \| grep -q running` | Internal endpoint reports per-service readiness |
 | MailHog | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
-| Mailpit | `wget --spider http://localhost:8025` | Same |
+| Mailpit | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
 | smtp4dev | `wget --spider http://localhost:80` | UI on internal port 80 |
 | MinIO | `curl -f http://localhost:9000/minio/health/live` | Documented liveness endpoint |
 | Meilisearch | `curl -f http://localhost:7700/health` | Documented |
@@ -41,11 +41,11 @@ api:
       condition: service_healthy   # waits for the healthcheck to pass
     redis:
       condition: service_healthy
-    mailhog:
-      condition: service_started   # MailHog is light enough that started == ready
+    mailpit:
+      condition: service_healthy
 ```
 
-`service_healthy` is the strictest gate — no traffic until the healthcheck has passed at least once. Use it for all data stores. Use `service_started` only for stateless services (proxy, mail capture).
+`service_healthy` is the strictest gate — no traffic until the healthcheck has passed at least once. Use it for every dependency that declares a healthcheck, including Mailpit. Use `service_started` only when a dependency has no healthcheck to gate on.
 
 ## Common mistakes
 

package/scaffold/skills/docker-compose-recipes/services/mailpit.yml

@@ -1,9 +1,9 @@
-# Mailpit — modern alternative to MailHog (active maintenance, full-text search, REST API)
+# Mailpit — maintained email capture for local development
 # Env vars: MAILPIT_SMTP_PORT (default 1025), MAILPIT_UI_PORT (default 8025)
-# Application-side SMTP config: same as MailHog (drop-in replacement)
+# Application-side SMTP config: SMTP_HOST=mailpit; SMTP_PORT=1025
 
 mailpit:
-  image: axllent/mailpit:latest
+  image: axllent/mailpit:v1.30
   restart: unless-stopped
   ports:
     - "${MAILPIT_SMTP_PORT:-1025}:1025"
@@ -24,4 +24,4 @@ mailpit:
 #   mailpit_data: {}
 #
 # Prod notes:
-# - DEV ONLY. Do not ship to prod. See mailhog.yml notes for prod email guidance.
+# - DEV ONLY. Do not ship to prod; replace it with a real SMTP relay or transactional email API.

package/scaffold/skills/docker-compose-recipes/services/postgres-pgvector.yml

@@ -0,0 +1,31 @@
+# PostgreSQL 18 + pgvector 0.8.2 — relational and vector database
+# Env vars: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_PORT (default 5432)
+# Application-side: derive DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+# The image ships pgvector; create the extension in an application migration with: CREATE EXTENSION IF NOT EXISTS vector;
+
+postgres:
+  image: pgvector/pgvector:0.8.2-pg18
+  restart: unless-stopped
+  environment:
+    POSTGRES_USER: ${POSTGRES_USER:-app}
+    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+    POSTGRES_DB: ${POSTGRES_DB:-app}
+  ports:
+    - "${POSTGRES_PORT:-5432}:5432"
+  volumes:
+    - postgres_data:/var/lib/postgresql
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app} -d ${POSTGRES_DB:-app}"]
+    interval: 5s
+    timeout: 3s
+    retries: 10
+    start_period: 5s
+
+# volumes block to merge:
+# volumes:
+#   postgres_data: {}
+#
+# Prod notes:
+# - Use a current patch release derived from PostgreSQL 18 and pgvector 0.8.2 or newer compatible patch.
+# - Move POSTGRES_PASSWORD to a secret and remove the public port mapping.
+# - Keep CREATE EXTENSION and vector indexes in reviewed application migrations.