@brunosps00/dev-workflow 1.6.0 → 1.7.1

package/.claude-plugin/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "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

@@ -42,7 +42,7 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v1.6.0 ships **37 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v1.7.0 ships **38 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (3)
 
@@ -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/constants.js

@@ -22,6 +22,7 @@ const COMMANDS = {
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Trigger when user asks to generate, iterate, or refactor/redesign headless Open Design HTML prototypes via the od CLI. Imports a target folder with isolated OD_DATA_DIR, refines briefs before dispatch, supports --refactor screenshots via --url/--viewports or --screenshot, runs web-prototype briefs with explicit --agent codex|claude, verifies files, captures JSONL audit logs, and stops for a dual >=9 visual gate.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
     { name: 'dw-plan', description: 'Trigger when user has a feature idea and needs spec + architecture + tasks. Runs PRD → TechSpec → Tasks sequentially. Stages: prd / techspec / tasks; --from techspec; --council.' },
@@ -61,6 +62,7 @@ const COMMANDS = {
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Trigger quando usuario pede para gerar, iterar ou refatorar/redesenhar prototipos HTML headless do Open Design via od CLI. Importa pasta alvo com OD_DATA_DIR isolado, refina briefs antes de despachar, suporta prints --refactor via --url/--viewports ou --screenshot, roda briefs web-prototype com --agent codex|claude explicito, verifica arquivos, captura logs JSONL e para para gate visual dual >=9.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
     { name: 'dw-plan', description: 'Trigger quando usuario tem ideia de feature e precisa spec + arquitetura + tasks. Roda PRD → TechSpec → Tasks sequencial. Stages: prd / techspec / tasks; --from techspec; --council.' },

package/lib/install-deps.js

@@ -1,4 +1,5 @@
 const { execSync } = require('child_process');
+const openDesign = require('./install-open-design');
 
 function run() {
   console.log('\n  dev-workflow install-deps');
@@ -84,6 +85,13 @@ function run() {
         'Verify after install:  docker --version && docker compose version',
       ],
     },
+    {
+      name: 'Open Design CLI (od)',
+      check: openDesign.check,
+      install: openDesign.install,
+      instructions: openDesign.instructions(),
+      sync: openDesign.syncProjectAssets,
+    },
   ];
 
   let installed = 0;
@@ -113,12 +121,28 @@ function run() {
 
     process.stdout.write(`  Installing ${dep.name}...`);
     try {
-      execSync(dep.install, { stdio: 'pipe', timeout: 300000 });
+      if (typeof dep.check === 'function' && dep.check()) {
+        console.log(' \x1b[32m✓ already installed\x1b[0m');
+        runDepSync(dep);
+        installed++;
+        continue;
+      }
+      if (typeof dep.install === 'function') {
+        dep.install();
+      } else {
+        execSync(dep.install, { stdio: 'pipe', timeout: 300000 });
+      }
       console.log(' \x1b[32m✓\x1b[0m');
+      runDepSync(dep);
       installed++;
     } catch (err) {
       console.log(' \x1b[31m✗\x1b[0m');
       console.log(`    Error: ${err.message.split('\n')[0]}`);
+      if (Array.isArray(dep.instructions)) {
+        for (const line of dep.instructions) {
+          console.log(`    ${line}`);
+        }
+      }
       failed++;
     }
   }
@@ -181,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

@@ -0,0 +1,128 @@
+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';
+const OPEN_DESIGN_VENDOR_DIR = path.join(os.homedir(), '.dw', 'vendor', 'open-design');
+
+function odBin(dir = OPEN_DESIGN_VENDOR_DIR) {
+  return path.join(dir, 'apps', 'daemon', 'bin', 'od.mjs');
+}
+
+function check() {
+  return fs.existsSync(odBin());
+}
+
+function install() {
+  checkPrerequisites();
+
+  fs.mkdirSync(path.dirname(OPEN_DESIGN_VENDOR_DIR), { recursive: true });
+  if (!fs.existsSync(path.join(OPEN_DESIGN_VENDOR_DIR, '.git'))) {
+    if (fs.existsSync(OPEN_DESIGN_VENDOR_DIR)) {
+      throw new Error(`${OPEN_DESIGN_VENDOR_DIR} exists but is not a git checkout; move it aside and retry.`);
+    }
+    execFileSync('git', ['clone', OPEN_DESIGN_REPO, OPEN_DESIGN_VENDOR_DIR], { stdio: 'pipe', timeout: 600000 });
+  }
+
+  execFileSync('git', ['fetch', '--tags', '--force', 'origin'], { cwd: OPEN_DESIGN_VENDOR_DIR, stdio: 'pipe', timeout: 600000 });
+  execFileSync('git', ['checkout', OPEN_DESIGN_REF], { cwd: OPEN_DESIGN_VENDOR_DIR, stdio: 'pipe', timeout: 120000 });
+  execFileSync('pnpm', ['install', '--frozen-lockfile'], { cwd: OPEN_DESIGN_VENDOR_DIR, stdio: 'pipe', timeout: 1200000 });
+
+  if (!check()) {
+    throw new Error(`Open Design install finished but ${odBin()} was not found.`);
+  }
+}
+
+/**
+ * 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:',
+    `  ${OPEN_DESIGN_VENDOR_DIR}`,
+    `  repo: ${OPEN_DESIGN_REPO}`,
+    `  pinned ref: ${OPEN_DESIGN_REF}`,
+    '',
+    'Prerequisites:',
+    '  Node.js ~24: install with fnm/nvm/asdf, then verify: node -v',
+    '  pnpm >=10.33: corepack enable && corepack prepare pnpm@10.33.2 --activate',
+    '  git: required to clone the upstream monorepo',
+    '',
+    'Then run: dev-workflow install-deps',
+    'To use your own checkout instead of the managed one, set OD_CLI_DIR=/path/to/open-design.',
+  ];
+}
+
+function checkPrerequisites() {
+  const nodeVersion = process.versions.node;
+  const nodeMajor = Number(nodeVersion.split('.')[0]);
+  if (nodeMajor !== 24) {
+    throw new Error(`Open Design requires Node.js ~24; detected ${nodeVersion}.`);
+  }
+
+  const pnpmRaw = execFileSync('pnpm', ['-v'], { stdio: 'pipe', timeout: 10000 }).toString().trim();
+  if (!isAtLeast(pnpmRaw, '10.33.0')) {
+    throw new Error(`Open Design requires pnpm >=10.33; detected ${pnpmRaw}.`);
+  }
+
+  execFileSync('git', ['--version'], { stdio: 'pipe', timeout: 10000 });
+}
+
+function isAtLeast(actual, minimum) {
+  const a = actual.split('.').map((part) => Number(part));
+  const b = minimum.split('.').map((part) => Number(part));
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const av = a[index] || 0;
+    const bv = b[index] || 0;
+    if (av > bv) return true;
+    if (av < bv) return false;
+  }
+  return true;
+}
+
+module.exports = {
+  syncProjectAssets,
+  OPEN_DESIGN_REF,
+  OPEN_DESIGN_VENDOR_DIR,
+  check,
+  install,
+  instructions,
+  odBin,
+};

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.6.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-help.md

@@ -38,12 +38,13 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-commit` | Atomic Conventional Commits for pending work. |
 | `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-## Tier 3 — Specialty (11)
+## Tier 3 — Specialty (12)
 
 | Command | What |
 |---------|------|
 | `/dw-analyze-project` | Scan the repo, write `.dw/rules/`, offer `.dw/constitution.md`, generate `.dw/rules/concerns.md`, and synthesize frontend `DESIGN.md` when tokens exist. |
 | `/dw-redesign-ui "target"` | Audit, propose 2-3 design directions, ship. Enforces UI grounding + WCAG; can run the deterministic impeccable slop detector. |
+| `/dw-open-design --brief <file>` | Generate, iterate, or `--refactor` headless Open Design HTML prototypes via `od`; refines briefs first, can capture current screenshots with `--url --viewports` or `--screenshot`, then verifies file + visual gate. |
 | `/dw-refactor "target"` | Audit code-health and tech debt with Fowler smells, deep-modules analysis, and behavior-preserving test gates. |
 | `/dw-functional-doc` | Map screens + flows into a functional doc validated with Playwright; uses WSL-resilient browser resolution. |
 | `/dw-context-budget` | Audit context overhead from commands, skills, agents, instructions, and MCPs. |
@@ -112,6 +113,7 @@ Match the keyword and suggest:
 | `research`, `compare`, `state of the art` | `/dw-brainstorm --research` |
 | `refactor`, `smell`, `code health`, `tech debt` | `/dw-refactor` |
 | `ui`, `design`, `redesign` | `/dw-redesign-ui` |
+| `open design`, `prototype`, `prototipo`, `od cli`, `html prototype` | `/dw-open-design --brief <file>`, `/dw-open-design --brief-glob "<glob>" --agent claude`, or `/dw-open-design --refactor --url <url> --viewports "1440x900,375x812"` |
 | `intel`, `where is`, `what uses` | `/dw-intel` (or `--build` to (re)create the index) |
 | `context`, `tokens`, `slow agent` | `/dw-context-budget` |
 | `harness`, `install`, `wrappers`, `agents` | `/dw-harness-audit` |

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