@brunosps00/dev-workflow 1.6.0 → 1.7.1

package/scaffold/en/commands/dw-open-design.md

@@ -0,0 +1,324 @@
+<system_instructions>
+You are the **headless Open Design (`od`) runner** for generating and iterating HTML prototypes in a project
+folder, without Electron and without depending on the user's GUI state. Start the `nexu-io/open-design` daemon in
+`--headless`, import the target folder once, run single briefs or serial batches, verify the output file, run the
+Playwright/Firefox visual gate, and **STOP for the owner's gate** before any commit.
+
+<critical>NEVER use the user's GUI state. Always run with an isolated per-project `OD_DATA_DIR`, for example `.dw/.open-design/data/`.</critical>
+<critical>NEVER commit a rejected prototype. The gate is dual >=9: automated gate + your own visual score >=9, then owner gate.</critical>
+<critical>The agent (`codex` or `claude`) must always be explicit in `od run start --agent <agent>`. If the user does not pass one, resolve from project config/state; fallback `codex`.</critical>
+<critical>NEVER dispatch the user's raw request to `od`. This command's value is refining the prompt first: ground it in real code, structure the brief, qualify states/themes/a11y/deep-link, persist the reviewable brief, and only then append the headless appendix.</critical>
+
+## Inputs
+
+| Flag/argument | Default | Description |
+|---|---:|---|
+| `--target <dir>` | `open-design/` | Folder imported as the external project and where HTML files are written. |
+| `--brief <file>` | none | One markdown brief for a single run. |
+| `--brief-glob <glob>` | none | Serial batch. Expand to a stable list and run one prompt at a time. |
+| `--output <file>` | required in the brief/appendix | Expected HTML file; verify it on disk after the run. |
+| `--agent <codex|claude>` | state/config -> `codex` | Agent forwarded to `od run start --agent`. |
+| `--platform <text>` | `Responsive web, desktop-first and mobile-safe` | Pre-filled discovery answer for the `web-prototype` skill. |
+| `--deep-link-id <id>` | none | Value used by the behavioral gate for `?aberto=<id>` + Esc. |
+| `--refactor` | false | Existing-screen redesign/refactor mode; captures current screenshots and grounds the brief in visible state + real code. |
+| `--url <url>` | none | Running app URL for current screenshot capture via Playwright Firefox. |
+| `--viewports <list>` | `1440x900,375x812` | Comma-separated viewports for `--refactor --url`; expand as the pain requires (for example `1920x1080` for a wide table). |
+| `--screenshot <path>` | repeatable | Already-captured current screenshot when there is no `--url`; copy it into `_refs/<slug>/`. |
+
+## 0. Refine The Brief
+
+Before any daemon pre-flight or `od` call, turn the user's intent into a qualified brief. Do not send the user's raw
+sentence to the runner.
+
+Required contract:
+
+| Step | Requirement |
+|---|---|
+| Ground in reality | If the screen exists, read its real code: columns, enums, actions, states, permissions, contracts, and domain. Also read the project's design system, sibling prototypes, and design guides. Inventing a field, status, or action is forbidden. |
+| Structure | Rewrite the request into the standard skeleton below, filling real paths and the exact output file. |
+| Qualify | Cover loading/skeleton, empty, error/failure, light + dark, a11y, local design-system limits (for example <=6 cards/filters), responsiveness, and deep-link. |
+| Persist | Save the refined brief inside the project, for example `<target>/PROMPT-<slug>.md`. It is a reviewable owner deliverable, not a disposable scratch file. |
+| Review if already ready | If the user already provides a qualified brief, do a quick checklist review, patch only gaps, and persist the final version. |
+
+Standard refined brief skeleton:
+
+```markdown
+# <screen/prototype title>
+
+Paste this brief into Open Design. Exact output file: `<OUTPUT_FILE>`.
+
+## 1. Why
+<real user/product pain; observable problem this prototype must solve>
+
+## 2. Interaction Decision
+<navigation, opening, selection, filters, sorting, editing, and confirmation pattern>
+
+## 3. Layout/List
+Table/list based only on REAL columns:
+
+| Real column | Source/contract | Presentation | State/limit |
+|---|---|---|---|
+| <name> | <file/API/schema> | <text, badge, action> | <truncate, empty, error> |
+
+## 4. Detail/Actions
+<drawer/modal/detail page; contextual actions allowed by real state/permission>
+
+## 5. Domain Fidelity
+So the mock does not lie: use real enums/statuses, realistic sample data in the project's language, and include rare/broken states that exist in the domain.
+
+## 6. Visual Direction
+<tokens, components, density, inherited references, sibling prototypes, and design-system limits>
+
+## Deliver
+- `<OUTPUT_FILE>`
+- `<OUTPUT_FILE>.artifact.json` when there is a sidecar
+```
+
+Only after persisting this file should you append the headless appendix under `.dw/.open-design/runs/` and dispatch
+the run.
+
+### 0R. Refactor/Redesign Mode
+
+When `--refactor` is present, phase 0 remains mandatory. Screenshots complement grounding in code; they do not
+replace reading contracts, enums, permissions, states, the design system, and sibling prototypes.
+
+Capture or copy current screenshots into the imported folder, under `_refs/<slug>/`, before persisting the brief:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --url "<url>" \
+  --viewports "1440x900,375x812"
+```
+
+Without a running app URL, accept existing screenshots by repeating `--screenshot`:
+
+```bash
+node .dw/scripts/open-design/capture-current.mjs \
+  --target "$TARGET_DIR" \
+  --slug "<slug>" \
+  --screenshot "./before-1440-light.png" \
+  --screenshot "./before-375-dark.png"
+```
+
+Capture rules:
+
+| Case | Requirement |
+|---|---|
+| Viewports | Sensible default: desktop `1440x900` + mobile `375x812`. The agent chooses/expands as the pain requires: mobile bug includes `375x812`; wide table includes `1920x1080`; tablet/console includes `768x1024`. |
+| Themes | Capture light and dark when applicable. The helper uses `light,dark` by default and writes names like `_refs/<slug>/atual-1440-light.png` and `_refs/<slug>/atual-375-dark.png`. |
+| Robust path | The `od` agent reads images from the project filesystem. Reference relative paths inside the target; do not depend on an image flag in `run start`. |
+| Hygiene | `_refs/` and reference material must not become prototypes. If the target project tracks final prototypes, document cleanup or add `<target>/_refs/` to `.gitignore` according to local convention. |
+
+The refined refactor brief must add this block:
+
+```markdown
+## Current Screen References
+Open and ANALYZE the screenshots before writing:
+- `_refs/<slug>/atual-1440-light.png`
+- `_refs/<slug>/atual-375-dark.png`
+
+## What Is Wrong Today
+<pain pointing to visible elements in the screenshots: density, hierarchy, table, filters, states, contrast, mobile, etc.>
+
+## The Change Idea
+<what changes and why; interaction/visual decision proposed by the user or by the agent after reading code and screenshots>
+
+## Preserve
+<flows, fields, permissions, states, copy, affordances, and integrations that must not change>
+```
+
+## Pre-flight
+
+| Check | Action |
+|---|---|
+| Resolve `od` | `OD_CLI_DIR` wins. Otherwise use `~/.dw/vendor/open-design`. If `apps/daemon/bin/od.mjs` is missing, stop and tell the user to run `dev-workflow install-deps`. |
+| Prerequisites | The Open Design checkout requires Node `~24` and pnpm `>=10.33`. If missing, stop with concrete instructions. |
+| Isolated state | Create `.dw/.open-design/`, `.dw/.open-design/data/`, `.dw/.open-design/runs/`, and `.dw/.open-design/state.json`. |
+| Port | Pick a free port on `127.0.0.1`; persist `daemonUrl` and `port` in state. |
+| Live daemon | If `od daemon status --daemon-url <url> --json` returns `ok: true`, reuse it. Otherwise start a new daemon. |
+
+Daemon command shape:
+
+```bash
+OD_DATA_DIR="$PWD/.dw/.open-design/data" \
+OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000 \
+node "$OD_DIR/apps/daemon/bin/od.mjs" daemon start \
+  --headless \
+  --host 127.0.0.1 \
+  --port "$PORT"
+```
+
+Known noise: `codex_core::shell_snapshot` may log a syntax `ERROR`. Treat it as benign when the run continues and
+the target file is created.
+
+## Idempotent Import
+
+Use `project import-folder` on the resolved absolute target folder. Default: `<repo>/open-design/`.
+
+Persist in `.dw/.open-design/state.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "targetDir": "/abs/repo/open-design",
+  "projectId": "<project.id>",
+  "conversationId": "<conversationId>",
+  "daemonUrl": "http://127.0.0.1:<port>",
+  "port": 17556,
+  "agent": "codex"
+}
+```
+
+If `projectId` exists in state and `od project info <id> --daemon-url <url> --json` works for the same `targetDir`,
+reuse it. Otherwise, reimport:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" project import-folder "$TARGET_DIR" \
+  --daemon-url "$OD_URL" \
+  --name "$(basename "$TARGET_DIR")" \
+  --skill web-prototype \
+  --design-system default \
+  --json
+```
+
+Capture `project.id` and `conversationId`; do not depend on global app state.
+
+## Required Headless Appendix
+
+Append this block to every brief in a temporary file under `.dw/.open-design/runs/`.
+Fill `<PLATFORM>`, `<OUTPUT_FILE>`, and sibling references when applicable.
+
+```markdown
+---
+
+## Headless appendix for Open Design
+
+Target platform: <PLATFORM>.
+
+Do not run discovery and do not ask questions. Do not emit `<question-form>`. Follow this brief with the answers
+above and deliver file-first.
+
+Required output file: `<OUTPUT_FILE>`.
+
+File-first contract:
+- Write the HTML directly to the project filesystem, exactly at `<OUTPUT_FILE>`.
+- Do not alter existing files, except when this prompt is explicitly a surgical iteration on a target file.
+- If you need to create a sidecar, keep `<OUTPUT_FILE>.artifact.json` coherent.
+- Do not answer only with a textual `<artifact>` block; run `succeeded` without the file is a failure.
+
+To avoid headless timeout:
+- Write large files in parts, with edits of about 150 lines per call.
+- Keep visible progress until the HTML is complete.
+
+Consistency context:
+- Read sibling prototypes in `prototipos/` or the folder named by the brief before defining visual patterns.
+- Preserve the local visual system when a nearby reference exists.
+
+Required deep link:
+- Implement `?aberto=<id>` to open the correct item's drawer/modal.
+- On Esc or close action, clear the parameter with `history.replaceState`.
+- The drawer/modal must use `role="dialog"` and appropriate ARIA attributes.
+- Include skeleton/loading, empty, and error states.
+```
+
+## Single Run
+
+Always pass `--agent` explicitly:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file "$PROMPT_WITH_APPENDIX" \
+  --follow \
+  --json | tee ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+After the run, check the file. **Do not accept only `succeeded`:**
+
+```bash
+test -s "$TARGET_DIR/<OUTPUT_FILE>"
+```
+
+Record in JSONL or an audit sidecar: brief, prompt with appendix, agent, daemonUrl, projectId, conversationId,
+expected output, final status, and file verification result.
+
+## Batch
+
+For `--brief-glob`, expand the briefs, sort by name, and run serially. Stop at the first case where:
+
+| Condition | Result |
+|---|---|
+| run fails | `BLOCKED` with JSONL log |
+| run says success but file is missing or empty | `FINDINGS` and surgical follow-up or `BLOCKED` |
+| visual gate <9 | `FINDINGS`; iterate before continuing |
+
+Do not run prompts in parallel in the same `od` project; preserve auditability and context.
+
+## Surgical Iteration
+
+Use a follow-up run on the same `projectId`/`conversationId`, with a short prompt and explicit target file:
+
+```bash
+node "$OD_DIR/apps/daemon/bin/od.mjs" run start \
+  --daemon-url "$OD_URL" \
+  --project "$PROJECT_ID" \
+  --conversation "$CONVERSATION_ID" \
+  --agent "$AGENT" \
+  --skill web-prototype \
+  --design-system default \
+  --prompt-file ".dw/.open-design/runs/<slug>.followup.md" \
+  --follow \
+  --json | tee -a ".dw/.open-design/runs/<slug>.jsonl"
+```
+
+The follow-up must say: single file, exact change, do not touch sibling prototypes, preserve deep-link and states.
+
+## Required Visual Gate
+
+Run the automated gate:
+
+```bash
+node .dw/scripts/open-design/gate-prototype.mjs \
+  --file "$TARGET_DIR/<OUTPUT_FILE>" \
+  --deep-link-id "<real-id>" \
+  --expected-text "<item-text>" \
+  --out ".dw/.open-design/gate/<slug>"
+```
+
+The gate covers:
+
+| Layer | Requirement |
+|---|---|
+| Structural | `<title>`, `aberto`, `replaceState`, `role=dialog`/ARIA, skeleton/loading, empty, error. |
+| Screenshot | Headless Firefox in light and dark, with `colorScheme` and `data-theme`. |
+| Behavioral | `?aberto=<id>` opens the correct item; Esc closes and clears the parameter. |
+| Evaluation | Automated PASS + your visual score >=9. If below 9, run a surgical follow-up. |
+
+After it passes, **stop for the owner's gate**. Do not commit until the owner approves.
+
+## Validated Pitfalls
+
+| Pitfall | Symptom | Required workaround |
+|---|---|---|
+| `web-prototype` discovery | Opens with `<question-form>` and ends the turn; headless does not create GenUI (`od ui list` empty). | Append the headless appendix answering platform and forbidding questions/discovery. |
+| Inactivity timeout | Large HTML goes silent and the run dies near 10 minutes. | `OD_CHAT_RUN_INACTIVITY_TIMEOUT_MS=1800000` on the daemon + instruct ~150-line chunked writes. |
+| `codex_core::shell_snapshot` | Logs a syntax `ERROR` in the stream. | Treat as noise if the run continues and the final file exists. |
+| GUI state | App config/agent/projects leak from the user's GUI. | Isolated `OD_DATA_DIR` always; explicit `--agent`, `--skill`, and `--design-system`. |
+
+## Structured Return
+
+**Status:** `PASS` | `FINDINGS` | `BLOCKED` | `NOT_APPLICABLE`  
+**Scope:** target folder, briefs run, agent used, projectId/conversationId.  
+**Evidence:** JSONL logs, verified HTML file(s), gate JSON, light/dark screenshots.  
+**Artifacts:** prototype and sidecar paths.  
+**Decisions:** defaults/overrides applied (`agent`, `target`, platform, port).  
+**Risks:** any gate below 9, missing file despite run succeeded, missing dependency.  
+**Next Step:** owner gate, required surgical follow-up, or exact resume command.
+</system_instructions>

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

@@ -36,12 +36,13 @@ Use `/dw-autopilot "desejo"` como gateway pra maior parte do trabalho. Comandos
 | `/dw-commit` | Commits atômicos Conventional pra trabalho pendente. |
 | `/dw-generate-pr [target]` | Push branch, draft do PR body, abre browser. |
 
-## Tier 3 — Especialidade (11)
+## Tier 3 — Especialidade (12)
 
 | Comando | O que |
 |---------|-------|
 | `/dw-analyze-project` | Scan do repo, escreve `.dw/rules/`, oferece `.dw/constitution.md`, gera `.dw/rules/concerns.md` e sintetiza `DESIGN.md` em frontend quando há tokens. |
 | `/dw-redesign-ui "target"` | Audit, propõe 2-3 direções, entrega. Enforça UI grounding + WCAG; pode rodar o detector determinístico do impeccable. |
+| `/dw-open-design --brief <file>` | Gera, itera ou faz `--refactor` de prototipos HTML headless via Open Design `od`; refina briefs primeiro, pode capturar prints atuais com `--url --viewports` ou `--screenshot`, depois verifica arquivo + gate visual. |
 | `/dw-refactor "target"` | Audita code health e tech debt com smells Fowler, deep-modules e gates de teste preservando comportamento. |
 | `/dw-functional-doc` | Mapeia screens + flows em doc funcional validado com Playwright; usa resolução de browser resiliente no WSL. |
 | `/dw-context-budget` | Audita contexto de commands, skills, agentes, instrucoes e MCPs. |
@@ -108,6 +109,7 @@ Auto-invocados por comandos primários mas disponíveis standalone.
 | `research`, `compara`, `estado da arte` | `/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` ou `/dw-open-design --refactor --url <url> --viewports "1440x900,375x812"` |
 | `intel`, `onde está`, `o que usa` | `/dw-intel` (ou `--build`) |
 | `contexto`, `tokens`, `agente lento` | `/dw-context-budget` |
 | `harness`, `install`, `wrappers`, `agentes` | `/dw-harness-audit` |

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