@brunosps00/dev-workflow 1.7.0 → 2.0.0

package/scaffold/pt-br/commands/dw-dockerize.md

@@ -129,10 +129,12 @@ Cada opcao lista estimativa de tamanho final, notas de attack surface, debug-abi
 
 Apresente os servicos detectados na Fase 0.3 como checklist. Usuario pode:
 - **Aceitar** — incluir todos os detectados no `docker-compose.dev.yml`
-- **Adicionar** — incluir extras (ex.: MailHog se SMTP usado em codigo, Jaeger se OTel)
+- **Adicionar** — incluir extras (ex.: Mailpit se SMTP usado em codigo, Jaeger se OTel)
 - **Remover** — dropar um detectado (ex.: Postgres gerenciado em dev tambem)
 
-Sempre ofereca MailHog se algum lib de envio de email foi detectada e nao tem servico de email no dev.
+Sempre ofereca Mailpit se algum lib de envio de email foi detectada e nao tem servico de email no dev.
+
+Se pgvector for detectado no projeto, nao ha recipe bundled a que recorrer — ela foi removida porque a imagem carregava CVEs sem correcao upstream. Mantenha a imagem que o projeto ja usa e diga claramente ao usuario que ela precisa de revisao propria: uma imagem reconstruida, ou um Postgres gerenciado com a extensao `vector` habilitada. Nao troque a imagem por conta propria.
 
 #### 1.4 Preview de arvore de arquivos
 
@@ -163,8 +165,11 @@ Sem aprovacao: escreve relatorio (Fase 3 com `status: PLANNED`) e para.
 **`docker-compose.dev.yml`**:
 - Componha blocos de `.agents/skills/docker-compose-recipes/services/*.yml` segundo `references/compose-composition.md`.
 - Adicione service(s) do app no fim: `build: { context: ., dockerfile: Dockerfile.dev }`, `volumes` para hot reload (bind mount do source, anonymous volume para `node_modules`/`__pycache__`), `env_file: .env`, `depends_on` com `condition: service_healthy` segundo `references/healthcheck-patterns.md`.
+- Preserve a tag da imagem de cada recipe (NAO converta nenhuma para digest — digest congela a base e nunca alcanca um rebuild de seguranca), as vars de credencial obrigatorias e os binds em `127.0.0.1`. As portas loopback mantem intencionalmente a topologia `apps no host` funcionando.
 - Header: `# Generated by /dw-dockerize on YYYY-MM-DD`.
 
+**`.env.example`**: emita toda var de credencial sem valor funcional (as recipes usam `${VAR:?}`, entao o Compose recusa subir sem valor). Depois da copia para `.env`, exija que o usuario defina valores locais unicos e gerados antes de rodar Compose. URLs das apps usam `localhost` quando apps rodam no host e DNS do servico quando rodam no Compose.
+
 **`Dockerfile.dev`** (multi-stage NAO obrigatorio em dev — single stage tudo bem):
 
 | Stack | Forma |
@@ -176,7 +181,7 @@ Sem aprovacao: escreve relatorio (Fase 3 com `status: PLANNED`) e para.
 
 **`.dockerignore`** dev: exclua `.git`, `node_modules`, `target`, `dist`, `.dw`, `.agents`, `*.md` (exceto README.md).
 
-**README.md secao "Local Dev"** (anexada): tabela de portas dos servicos, credenciais default do `.env.example`, os 4 comandos `dev:*`.
+**README.md secao "Local Dev"** (anexada): tabela de portas dos servicos, requisitos de credenciais do `.env.example` sem senhas funcionais, os 4 comandos `dev:*`.
 
 #### 2.2 Artefatos `--prod`
 
@@ -217,7 +222,8 @@ Requisitos chave (toda linguagem):
 - `restart: always`.
 - Network interna. SEM portas publicas exceto via reverse proxy.
 - Secrets via bloco `secrets:` ou manager externo.
-- Drope servicos so-de-dev (sem MailHog, Mailpit, smtp4dev, LocalStack, MinIO a menos que explicitamente preciso em prod).
+- Drope servicos so-de-dev (sem Mailpit, Mailpit, smtp4dev, LocalStack, MinIO a menos que explicitamente preciso em prod).
+- Para busca vetorial, use imagem revisada separadamente ou servico Postgres gerenciado com a extensao `vector`; este projeto nao distribui imagem pgvector validada.
 
 **`.dockerignore`** prod: mais restritivo que dev. Exclua testes, `tests/`, `.github/`, `.dw/`, `.agents/`, todo markdown exceto licenca.
 
@@ -234,6 +240,7 @@ Leia `Dockerfile` e composes existentes. Aplique checks de `security-review/infr
 - Compose: servicos sem healthcheck? (flag)
 - Compose: servicos sem `restart` policy? (flag)
 - Compose: bind mounts em compose prod? (flag CRITICAL se `prod` no nome do arquivo)
+- Compose: alguma imagem pinada por digest, ou credencial com default funcional? (flag CRITICAL — ambos bloqueiam rebuild da base ou distribuem credencial usavel)
 
 Aplique `dw-review-rigor`: dedupe padroes repetidos, signal-over-volume em nits de estilo.
 
@@ -257,7 +264,7 @@ mode: <dev|prod|both|audit|dry-run>
 languages: [...]
 frameworks: { web: '...', api: '...' }
 services_detected: [postgres, redis, ...]
-services_added: [mailhog, ...]
+services_added: [mailpit, ...]
 base_image_strategy: <conservative|balanced|bold>
 ---
 ```
@@ -272,7 +279,7 @@ Secoes:
 6. **Files Created** — tabela com path + bytes + papel.
 7. **Audit Findings** (so `--audit`) — tabela de issues com severidade, file:line, recomendacao.
 8. **Next Steps:**
-   - Para `--dev`: `cp .env.example .env` (se faltar), `docker compose -f docker-compose.dev.yml up -d`, depois smoke test do app.
+   - Para `--dev`: `cp .env.example .env` (se faltar), defina cada secret obrigatorio como `POSTGRES_PASSWORD` com valor local unico, rode `docker compose -f docker-compose.dev.yml up -d`, depois smoke test do app.
    - Para `--prod`: build local primeiro (`docker build -t <name>:dev .`), rode `/dw-secure-audit` no Dockerfile e compose, depois push pro registry.
    - Para `--audit`: aplique fixes manualmente ou rode com `--mode=force-overwrite`.
    - Sempre: rode `/dw-secure-audit --plan` antes de promover a imagem para prod.
@@ -293,7 +300,7 @@ Secoes:
 - <critical>Nunca sobrescreva em silencio. Se `Dockerfile`/`docker-compose.*.yml`/`.dockerignore` existe, default para `--audit`.</critical>
 - <critical>Imagens prod NUNCA incluem secrets, tooling SDK de dev, source nao compilado, ou fixtures de teste.</critical>
 - <critical>Imagens prod SEMPRE rodam como usuario nao-root.</critical>
-- <critical>Compose prod NUNCA inclui MailHog, Mailpit, smtp4dev, LocalStack, ou servicos so-de-dev.</critical>
+- <critical>Compose prod NUNCA inclui Mailpit, Mailpit, smtp4dev, LocalStack, ou servicos so-de-dev.</critical>
 - <critical>Se `--audit` acha CRITICAL (secrets em ENV, root user, portas publicas em data tier), Next Steps lista o fix como REQUIRED antes de deploy.</critical>
 - NAO use tag `:latest` em lugar nenhum.
 - NAO execute comandos compose deste comando — gere arquivos, o usuario roda `docker compose up`.

package/scaffold/pt-br/commands/dw-generate-pr.md

@@ -106,6 +106,19 @@
 
     3. **Instruir o usuário** a colar o body (Ctrl+V) no campo de descrição
 
+    ### 6. Registrar a PR de volta na spec
+
+    A URL da PR só existe depois que o usuário clica em "Create". Assim que existir, escreva de volta — senão nada do lado `.dw/` registra qual PR entregou o trabalho, e a trilha termina na branch.
+
+    ```bash
+    # Caminho rápido: resolve depois que a PR existe. Precisa do GitHub CLI; pule em silêncio se ausente.
+    gh pr view --json url -q .url 2>/dev/null
+    ```
+
+    - Se resolver uma URL, anexe na seção `## Related` do PRD como `- PR: <url>`.
+    - Se `gh` não existir ou a PR ainda não foi criada, imprima a linha exata para o usuário colar e siga. **Nunca bloqueie o comando nisso** — é registro, não gate.
+    - Para branches de bugfix, anexe a mesma linha em `.dw/bugfixes/<NNN-slug>/SUMMARY.md` sob `## Related`.
+
     ## Template da PR (copiar para clipboard)
 
     ```markdown

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 / MySQL / SQLite (arquivo, sem service) / MongoDB (fora do escopo dos compose recipes — anote e siga sem service se escolhido) / nenhum. Nao ha recipe bundled de pgvector: a imagem carregava CVEs sem correcao upstream e nenhum artefato bundled conseguia limpa-las. Se o projeto precisar de busca vetorial, anote e deixe o usuario escolher uma imagem revisada separadamente ou um Postgres gerenciado com a extensao habilitada.
 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 / 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.
 
@@ -110,7 +112,7 @@ Guarde todas as respostas para a Fase 2.
 
 ### Fase 2 — One-Pager + Plano + Gate de Aprovacao
 
-1. Renderize `.dw/spec/projects/{{PROJECT_NAME}}.md` a partir de `.dw/templates/project-onepager.md`. Preencha tudo: forma, linguagens, frameworks, tabela de servicos (nome + porta + credencial default), diagrama da arquitetura (ASCII), lista de arquivos a gerar, perguntas em aberto.
+1. Renderize `.dw/spec/projects/{{PROJECT_NAME}}.md` a partir de `.dw/templates/project-onepager.md`. Preencha tudo: forma, linguagens, frameworks, tabela de servicos (nome + porta + requisitos de credenciais, nunca uma senha funcional), diagrama da arquitetura (ASCII), lista de arquivos a gerar, perguntas em aberto.
 2. Monte o plano:
    - Comandos a rodar (em ordem, com argumentos)
    - Arquivos a criar (paths sob `{{TARGET_DIR}}`)
@@ -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,12 +162,13 @@ 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.
+   - Preserve a tag da imagem de cada recipe (NAO converta nenhuma para digest — digest congela a imagem base e nunca alcanca um rebuild de seguranca), as vars de credencial obrigatorias e os binds de porta em `127.0.0.1`. Esses mapeamentos loopback suportam intencionalmente `apps no host`; nao os remova do dev local.
 3. Adicione header: `# Generated by /dw-new-project on YYYY-MM-DD`.
 
 #### 3.4 Gerar `.env.example`
 
-Consolide cada env var referenciada pelos servicos selecionados (segundo `references/env-conventions.md`). Agrupe por servico. Sempre inclua as URLs derivadas do lado da app (`DATABASE_URL`, `REDIS_URL`, `AMQP_URL`, `SMTP_HOST`/`SMTP_PORT`, `AWS_ENDPOINT_URL`, etc.).
+Consolide cada env var referenciada pelos servicos selecionados (segundo `references/env-conventions.md`). Agrupe por servico. Sempre inclua as URLs derivadas do lado da app (`DATABASE_URL`, `REDIS_URL`, `AMQP_URL`, `SMTP_HOST`/`SMTP_PORT`, `AWS_ENDPOINT_URL`, etc.). Toda var de credencial e emitida vazia no `.env.example` (as recipes usam `${VAR:?}`, entao o Compose recusa subir sem valor real). Exija que o usuario defina valores unicos e gerados no `.env` gitignored antes de rodar Compose. Nunca emita uma senha reutilizavel.
 
 #### 3.5 Gerar scripts
 
@@ -214,7 +218,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|smtp4dev|nenhum> |
 | Search | <search ou n/a> |
 | Observability | <observability ou n/a> |
 | Reverse proxy | <traefik|nenhum> |
@@ -225,12 +229,12 @@ Scaffold minimo:
 
 ## Servicos no docker-compose.dev.yml
 
-(tabela dos servicos selecionados com portas e credenciais default)
+(tabela dos servicos selecionados com portas e requisitos de credenciais; nunca inclua senha funcional)
 
 ## 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.
 ```
 
@@ -238,8 +242,8 @@ Scaffold minimo:
 
 Gere um README inicial:
 - Nome do projeto + 1 linha de proposito
-- Quick Start (`cp .env.example .env && pnpm install && pnpm dev:up`)
-- Local Dev (tabela de portas dos servicos selecionados + URLs das UIs + credenciais default)
+- Quick Start (`cp .env.example .env`, defina cada secret obrigatorio com valor local unico, depois `pnpm install && pnpm dev:up`)
+- Local Dev (tabela de portas dos servicos selecionados + URLs das UIs + requisitos de credenciais; nunca publique senha funcional)
 - Diagrama da arquitetura (ASCII do one-pager)
 - Layout do projeto (arvore dos diretorios top-level)
 - Integracao com dev-workflow (mencione `/dw-plan prd`, `/dw-run`, `/dw-qa`, `/dw-secure-audit --plan`, `/dw-secure-audit`)
@@ -273,7 +277,7 @@ date: YYYY-MM-DD
 shape: <frontend|backend|fullstack>
 languages: [typescript, python, ...]
 frameworks: { web: '...', api: '...' }
-services: [postgres, redis, mailhog, ...]
+services: [postgres, mailpit, minio, ...]
 package_manager: <pnpm|npm|yarn|poetry|uv|cargo|dotnet>
 monorepo: <pnpm-workspaces|turborepo|nx|none>
 ---
@@ -296,13 +300,13 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 | ... | ... | ... |
 
 ## Servicos Compostos
-<tabela de servicos com porta + URL UI + credenciais default, vinda de .agents/skills/docker-compose-recipes/>
+<tabela de servicos com porta + URL UI + requisitos de credenciais, vinda de .agents/skills/docker-compose-recipes/>
 
 ## Proximos Passos
-1. `cp .env.example .env` e revise credenciais.
+1. `cp .env.example .env`, gere secrets locais unicos e defina todo valor obrigatorio como `POSTGRES_PASSWORD`.
 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/`.
 ```
@@ -320,10 +324,10 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 
 - <critical>NUNCA pule o gate de aprovacao da Fase 2. Se rodando em contexto nao-interativo, aborte com: "/dw-new-project exige aprovacao interativa; rerode com --dry-run para so planejar."</critical>
 - <critical>NUNCA rode tools `create-*` fora de `{{TARGET_DIR}}`. CWD de cada comando e o target dir.</critical>
-- <critical>Se MailHog/Mailpit/smtp4dev foi selecionado, NUNCA tambem ligue um SMTP real em dev. O compose de dev SEMPRE captura.</critical>
+- <critical>Se Mailpit/smtp4dev foi selecionado, NUNCA tambem ligue um SMTP real em dev. O compose de dev SEMPRE captura.</critical>
 - <critical>Se uma tool `create-*` falha, PARE. Nao siga para gerar compose — scaffold parcial confunde os comandos seguintes.</critical>
 - NAO pin de versao SDK Node/Python/.NET/Rust dentro do projeto a nao ser que o usuario peca; use `package.json` engines / `pyproject.toml` / `global.json` / `rust-toolchain.toml` para indicar intencao sem forcar.
-- NAO baked secrets em arquivo gerado. `.env.example` so com defaults de dev; valor real fica em `.env` nao versionado.
+- NAO baked secrets em arquivo gerado. `.env.example` contem defaults nao secretos de dev e chaves secretas obrigatorias vazias; valores reais ficam em `.env` nao versionado.
 
 ## Tratamento de Erros
 
@@ -332,7 +336,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/commands/dw-plan.md

@@ -113,7 +113,7 @@ Roda em modo padrão OU `plan prd`.
 
 1. **Coverage matrix sobre as dimensões do PRD** (objetivos, usuários-alvo, limites de escopo, métricas de sucesso, estratégia de rollout, pontos de integração, edge cases). Monte a matriz, credite evidência de handoff alinhado e fatos descobertos do repo, e pergunte SOMENTE as dimensões descobertas — uma decisão por vez, cada uma com resposta recomendada — usando a ferramenta de entrevista estruturada quando disponível (registre o fallback em chat caso contrário). Sem contagem fixa de perguntas; nunca re-pergunte uma decisão resolvida num one-pager alinhado.
 2. **Web search MÍNIMO 3 queries** para padrões de mercado, contexto regulatório, abordagens de competidores quando relevante.
-3. **Constitution alignment.** Cada requisito funcional (FR-N.M) inclui linha `Constitution Alignment: respects P-NNN, P-MMM` OU `no applicable principle: <motivo>`.
+3. **Constitution alignment.** Cada requisito funcional (RF-N.M) inclui linha `Constitution Alignment: respects P-NNN, P-MMM` OU `no applicable principle: <motivo>`.
 4. **Awareness multi-projeto.** Se feature cruza projetos do workspace, consulte `.dw/rules/integrations.md` e documente escopo na seção "Projetos Impactados".
 5. **Output:** `.dw/spec/prd-<feature-slug>/prd.md`.
 

package/scaffold/pt-br/commands/dw-run.md

@@ -75,7 +75,7 @@ Quando disponíveis em `./.agents/skills/`, estas skills são invocadas por task
    - Mensagem atômica: `feat(<scope>): <título da task> (#<task-id>)`.
    - Referencie FRs cobertos.
    - Uma task = um commit (exceto se task tem subtask milestones explícitos que ganham commits separados).
-6. **Atualizar tasks.md:** marcar task como `Done` com SHA do commit.
+6. **Atualizar tasks.md:** marcar `Status` da task como `Done` e escrever o SHA curto (`git rev-parse --short HEAD`) na coluna `Commit`. Esse é o único registro que liga a task ao seu diff — não pule.
 7. **Reportar:** o que foi feito, testes adicionados, o que foi validado.
 
 ### CONDIÇÕES DE PARADA

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

@@ -23,33 +23,35 @@ 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 / MySQL / SQLite / MongoDB / nenhum | [por que esse DB — relacional, transacional, etc. Busca vetorial nao tem recipe bundled; nomeie a imagem revisada ou servico gerenciado se o projeto precisar] |
 | 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) / 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
 
 [Servicos gerados a partir da skill docker-compose-recipes. Preenchido pelo /dw-new-project.]
 
-| Servico | Porta (host) | UI | Credenciais default |
-|---------|--------------|----|--------------------|
-| postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
+| Servico | Porta (host) | UI | Credenciais |
+|---------|--------------|----|-------------|
+| postgres | 127.0.0.1:5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD obrigatoria no `.env` (sem default), 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 +61,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 +77,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/pt-br/templates/task-template.md

@@ -12,7 +12,7 @@ status: pending
 
 [Breve descrição da tarefa]
 
-**Requisitos Funcionais cobertos**: RF[X.Y], RF[X.Z] (máximo 2 por task)
+**Requisitos Funcionais cobertos**: RF-X.Y, RF-X.Z (máximo 2 por task)
 
 <requirements>
 [Lista de requisitos obrigatórios]

package/scaffold/pt-br/templates/tasks-template.md

@@ -19,11 +19,13 @@ feat/prd-[nome-funcionalidade]
 
 ## Tarefas
 
-| Task | Descrição | RFs | Status |
-|------|-----------|-----|--------|
-| 1.0 | [Título] | RF1.1, RF1.2 | Pendente |
-| 2.0 | [Título] | RF2.1 | Pendente |
-| 3.0 | [Título] | RF3.1, RF3.2 | Pendente |
+| Task | Descrição | RFs | Status | Commit |
+|------|-----------|-----|--------|--------|
+| 1.0 | [Título] | RF-1.1, RF-1.2 | Pendente | — |
+| 2.0 | [Título] | RF-2.1 | Pendente | — |
+| 3.0 | [Título] | RF-3.1, RF-3.2 | Pendente | — |
+
+`Commit` guarda o SHA curto escrito de volta pelo `/dw-run` quando a task fecha (passo 6). É o que torna o diff da task localizável depois — deixe `—` até a task commitar.
 
 ## Progresso
 

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, redis, mailpit, minio, meilisearch, jaeger, traefik). Invoked by /dw-new-project, /dw-dockerize, or when composing dev/prod compose files.
 allowed-tools:
   - Read
   - Write
@@ -54,8 +54,7 @@ Each row points to `services/<name>.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` |
 | 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 +75,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`, `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, 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
 
@@ -49,8 +49,8 @@ services:
     # ... 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

@@ -1,12 +1,18 @@
 # Env var conventions
 
-All recipes reference env vars via `${VAR:-default}` so a project's `.env` (or `.env.example`) is the single source of truth.
+Recipes reference non-secret env vars via `${VAR:-default}` — ports, users, database names. **Every credential uses `${VAR:?error}` instead**, so Compose refuses to start when the value is missing rather than falling back to a value published in this repository. That applies to `postgres`, `mysql`, `elasticsearch`, `meilisearch`, `minio`, and `rabbitmq`; `test/compose-recipe-safety.test.js` enforces it across every recipe.
+
+Authenticated services also publish on `127.0.0.1:` only. Docker's `"HOST:CONTAINER"` short form binds every host interface, which turns a local dev credential into a network-reachable one.
+
+A project's `.env` is the local source of truth; `.env.example` documents required keys without supplying reusable credentials.
+
+[source: https://docs.docker.com/reference/compose-file/interpolation/, version: Compose Specification, retrieved: 2026-07-15]
 
 ## Naming pattern
 
 - **Service-scoped** vars use the upstream image's convention: `POSTGRES_USER`, `MYSQL_ROOT_PASSWORD`, `MEILI_MASTER_KEY`, etc. This avoids surprises when reading the image's documentation.
 - **Application-scoped** vars use a generic name that spans implementations: `DATABASE_URL`, `REDIS_URL`, `SMTP_HOST`, `AWS_ENDPOINT_URL`. The application reads these, not the service-specific ones.
-- **Port overrides** use `<SERVICE>_PORT` (or `<SERVICE>_<ROLE>_PORT` when there are several): `POSTGRES_PORT`, `MAILHOG_SMTP_PORT`, `MAILHOG_UI_PORT`, `RABBITMQ_PORT`, `RABBITMQ_UI_PORT`.
+- **Port overrides** use `<SERVICE>_PORT` (or `<SERVICE>_<ROLE>_PORT` when there are several): `POSTGRES_PORT`, `MAILPIT_SMTP_PORT`, `MAILPIT_UI_PORT`, `RABBITMQ_PORT`, `RABBITMQ_UI_PORT`.
 
 ## Mapping between service vars and app vars
 
@@ -15,19 +21,22 @@ When a project uses Postgres, the `.env.example` should declare BOTH the service
 ```dotenv
 # Postgres (consumed by the postgres service)
 POSTGRES_USER=app
-POSTGRES_PASSWORD=app
+# Required: generate a unique value in .env before running Compose.
+POSTGRES_PASSWORD=
 POSTGRES_DB=app
 POSTGRES_PORT=5432
 
-# Application-side connection string
-DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+# Application-side connection string for apps running on the host
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${POSTGRES_PORT}/${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.
+
+If a project needs the `vector` extension, there is no bundled recipe for it — use a separately reviewed image or a managed Postgres, with the same connection variables above. `CREATE EXTENSION IF NOT EXISTS vector` belongs in the application's reviewed migrations, never in a container startup script.
 
 ## What goes in `.env.example` vs `.env`
 
-- `.env.example` — committed. Holds DEFAULTS that are safe for dev and template values for prod.
+- `.env.example` — committed. Holds non-secret defaults and empty required secret keys; it never contains a working database password.
 - `.env` — gitignored. Real values for the user's local machine.
 
 Never commit a `.env`. Always commit a `.env.example`.
@@ -41,11 +50,11 @@ Never commit a `.env`. Always commit a `.env.example`.
 | Redis URL | `REDIS_URL` | `REDIS_PASSWORD` (if set) |
 | RabbitMQ URL | `AMQP_URL` | `RABBITMQ_USER`, `RABBITMQ_PASSWORD` |
 | AWS-compatible | `AWS_ENDPOINT_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | LocalStack: `test`/`test`. MinIO: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` |
-| SMTP | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_SECURE` | Service hostname (`mailhog`/`mailpit`/`smtp4dev`) + recipe's SMTP port |
+| SMTP | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_SECURE` | Service hostname (`mailpit`/`smtp4dev`) + recipe's SMTP port |
 | OTel | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://jaeger:4318` |
 
 ## Reserved names
 
 The recipes use these env var names. Do NOT reuse them for unrelated config:
 
-`POSTGRES_*`, `MYSQL_*`, `MEILI_*`, `MINIO_*`, `RABBITMQ_*`, `MAILHOG_*`, `MAILPIT_*`, `SMTP4DEV_*`, `JAEGER_*`, `TRAEFIK_*`, `LOCALSTACK_*`, `ELASTIC_*`, `TYPESENSE_*`, `MEMCACHED_*`, `REDIS_*`.
+`POSTGRES_*`, `MYSQL_*`, `MEILI_*`, `MINIO_*`, `RABBITMQ_*`, `MAILPIT_*`, `SMTP4DEV_*`, `JAEGER_*`, `TRAEFIK_*`, `LOCALSTACK_*`, `ELASTIC_*`, `TYPESENSE_*`, `MEMCACHED_*`, `REDIS_*`.

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

@@ -12,8 +12,7 @@ Every recipe ships a healthcheck. App services that depend on infra MUST gate st
 | Memcached | `echo stats | nc -w 1 localhost 11211 \| grep -q uptime` | Memcached has no native ping; stats command is the cheapest readiness signal |
 | 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 +40,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