@jaimevalasek/aioson 1.36.0 → 1.37.1

package/docs/pt/4-agentes/briefing-refiner.md

@@ -1,16 +1,17 @@
 # @briefing-refiner — Revisa e refina um briefing antes do PRD
 
 > **Para quem é:** quem já tem um briefing gerado pelo `@briefing` e quer revisá-lo, anotar e refinar antes de comprometer um PRD.
-> **Tempo de leitura:** 4 min.
+> **Tempo de leitura:** 5 min.
 > **O que você vai sair sabendo:**
 > - O que o `@briefing-refiner` faz e onde ele entra no fluxo.
-> - Como funciona a superfície de revisão local em HTML e por que o feedback é estruturado (JSON), não o DOM.
+> - Como funciona o loop de refinamento em rodadas (auditoria → revisão no navegador → aplicação).
+> - Como a superfície `review.html` salva de verdade (autosave local + 3 rotas de retorno do JSON).
 
 ## Para que serve
 
 Entre o briefing gerado e o PRD há uma etapa que costuma ser pulada: **revisar o briefing com olhar crítico**. Ambiguidades, redundâncias, decisões faltando, riscos vagos e gaps de impacto de implementação passam direto para o `@product` e viram dívida no PRD.
 
-O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, gera uma **superfície de revisão local** (`review.html`) onde você edita cada seção, marca status e deixa notas, e depois aplica de volta ao briefing **apenas o feedback estruturado que você confirmar** — preservando o contrato do briefing (todas as seções obrigatórias).
+O `@briefing-refiner` preenche essa etapa em um **loop de rodadas**: ele audita o briefing e registra **achados estruturados** (findings com categoria, severidade e se bloqueiam o PRD); o CLI renderiza a superfície de revisão determinística (`aioson briefing:review`); você decide cada achado e edita cada seção no navegador; o feedback estruturado volta e é aplicado (`aioson briefing:apply-feedback`) — e o ciclo se repete até nada bloquear o PRD.
 
 É o complemento do [`@briefing`](./briefing.md): um gera, o outro refina.
 
@@ -18,7 +19,8 @@ O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, ger
 
 - Você já tem um briefing em `.aioson/briefings/{slug}/briefings.md` e quer revisá-lo antes do PRD.
 - O briefing está `draft`, ou `approved` mas ainda **sem PRD gerado** (`prd_generated: null`).
-- Quer registrar comentários, pedir mudanças por seção ou marcar bloqueios antes de seguir para `@product`.
+- Quer registrar comentários, decidir achados, pedir mudanças por seção ou marcar bloqueios antes de seguir para `@product`.
+- Quer **ver a solução** antes do PRD (modo prototype) e, opcionalmente, definir a identidade visual a partir das suas imagens de referência.
 
 ## Quando NÃO invocar
 
@@ -26,71 +28,89 @@ O `@briefing-refiner` preenche essa etapa. Ele audita um briefing existente, ger
 - O briefing já gerou PRD (`prd_generated` preenchido) — refinar exigiria uma rota nova de PRD/enrichment, fora deste agente.
 - A ideia mudou tanto que vale regerar do zero — volte ao `@briefing`.
 
-## Dois modos de operação
+## O loop de refinamento
+
+```
+auditoria (agente) → review.html (CLI) → você decide no navegador
+       ↑                                            ↓
+regenera a revisão  ←  aplica feedback confirmado (CLI)
+(enquanto houver bloqueios ou mudanças de texto)
+```
+
+Cada rodada tem número (`round`) e arquiva o feedback consumido (`refinement-feedback.applied-round{N}.json`), então "existe `refinement-feedback.json`" = "há feedback pendente" — um sinal determinístico.
 
 ### 1. Gerar revisão
 
-Quando ainda não há feedback pendente. O agente audita o briefing e escreve a superfície de revisão:
+O agente audita o briefing e escreve os achados em `refinement-findings.json`; o CLI valida e renderiza:
 
 ```
 Você > @briefing-refiner
 
 @briefing-refiner > Briefing refinável encontrado: marketplace-v1 (draft).
 
-                    Auditando seções... ambiguidades: 3, redundâncias: 1,
-                    gaps de implementação: 2, riscos vagos: 1.
+                    Auditando... 10 achados (3 ambiguidades, 2 gaps,
+                    1 bloqueante: modelo de comissão indefinido).
 
-                    Gerei a revisão:
-                    - .aioson/briefings/marketplace-v1/review.html
-                    - .aioson/briefings/marketplace-v1/refinement-feedback.json
-                    - .aioson/briefings/marketplace-v1/refinement-report.md
+                    aioson briefing:review . --slug=marketplace-v1  ✓ (rodada 1)
 
-                    Abra o review.html, edite as seções, marque status/notas,
-                    salve/exporte o refinement-feedback.json e me reative.
+                    Abra .aioson/briefings/marketplace-v1/review.html
+                    NUM NAVEGADOR DE VERDADE (duplo clique) — previews de
+                    editor são sandboxed e bloqueiam salvar/baixar.
 ```
 
 ### 2. Aplicar feedback pendente
 
-Quando existe um `refinement-feedback.json` com mudanças não aplicadas. O agente valida, resume o que vai mudar e **pede confirmação explícita** antes de tocar o briefing:
+O CLI valida (schema, slug, hash da fonte) e faz um **dry-run** com o resumo; o agente pede confirmação explícita antes de tocar o briefing:
 
 ```
-Você > @briefing-refiner
-
-@briefing-refiner > Feedback pendente em marketplace-v1:
-                    - 4 seções com mudança aceita
-                    - 2 comentários não resolvidos
-                    - 1 item bloqueante (modelo de comissão)
+@briefing-refiner > Feedback pendente em marketplace-v1 (rodada 1):
+                    - 4 seções com mudança, 1 bloqueada
+                    - achados: 6 aceitos, 2 rejeitados, 1 adiado, 1 pendente (bloqueante)
 
-                    Aplico as 4 mudanças confirmadas? (o item bloqueante
-                    impede o handoff para @product até ser resolvido)
+                    Aplico as mudanças confirmadas? O achado bloqueante
+                    pendente mantém o bloqueio do PRD.
 Você > Sim.
 
-@briefing-refiner > Aplicado. Como o briefing estava `approved` sem PRD,
-                    voltei para `draft`. Relatório: refinement-report.md.
+@briefing-refiner > aioson briefing:apply-feedback --confirm  ✓
+                    Aplicado; briefing voltou de approved para draft.
+                    Bloqueio restante → regenerando a revisão (rodada 2)...
 ```
 
-Se você recusar, o `briefings.md` fica intacto e as mudanças puladas são registradas no relatório.
+Se você recusar, o `briefings.md` fica intacto e as mudanças puladas são registradas no relatório. Quando não sobra bloqueio: `aioson briefing:approve . --slug={slug}` → `@product`.
 
 ## A superfície de revisão (review.html)
 
-O diferencial deste agente. O `review.html` é **estático, local e self-contained**:
+Renderizada pelo CLI (`aioson briefing:review`) — estática, local, self-contained e no seu idioma:
+
+- seções editáveis em texto puro + status por seção (`unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`) e notas;
+- **achados da auditoria por seção**, cada um com decisão própria (`pending`/`accepted`/`rejected`/`deferred`) e nota — com filtros funcionais por categoria;
+- painel com o que mudou, o que bloqueia o PRD e quantos achados seguem pendentes;
+- **autosave local**: cada edição é salva no navegador (localStorage) e restaurada ao reabrir — fechar a aba não perde nada;
+- **3 rotas para devolver o JSON**: *Salvar no arquivo* (File System Access, com fallback automático para download quando o contexto é sandboxed), *Baixar JSON* (e mover por cima do `refinement-feedback.json`), ou *Copiar JSON e colar no chat* — a rota de menor atrito.
 
-- sem servidor, sem scripts ou serviços externos;
-- seções editáveis em texto puro, com layout denso de revisão;
-- controles de status por seção: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`;
-- notas/comentários por seção e um resumo do que será feito, do que é incerto e do que bloqueia o PRD;
-- filtros por ambiguidade, redundância, gap, risco, decisão pendente e sugestão de escopo;
-- **exportar/baixar/copiar o JSON sempre disponível** (a File System Access API é só um plus opcional, após ação explícita).
+> **Por que JSON e não o HTML editado?** O agente nunca trata o DOM/HTML editado como feedback canônico — só o `refinement-feedback.json` estruturado (schema v1.1, validado por hash da fonte). Isso evita aplicar mudanças inferidas e mantém o processo auditável.
 
-> **Por que JSON e não o HTML editado?** O agente nunca trata o DOM/HTML editado como feedback canônico — só o `refinement-feedback.json` estruturado. Isso evita aplicar mudanças inferidas e mantém o processo auditável.
+> **Importante:** abra o `review.html` num navegador de verdade (duplo clique). Previews embutidos de editor rodam em sandbox e bloqueiam o file picker e downloads.
+
+## Modo prototype e identidade visual (opcional)
+
+Para briefings com superfície rica (workspaces, boards, CRM/Kanban, dashboards, CRUD de uso repetido), o agente recomenda — sem bloquear — gerar um protótipo clicável antes do PRD. É nesse momento (ou já na revisão, via achado não-bloqueante) que a **identidade visual** entra:
+
+- você solta imagens de referência em `references/identity/` (marca: cor, tipografia, clima) e `references/structure/` (um board, uma tabela, uma tela);
+- a skill `reference-identity-extract` lê as imagens **uma única vez** e escreve `identity.md` (tokens + notas de estrutura por componente);
+- o motor `interface-design` **aplica** o `identity.md` em tudo que vier depois (protótipo e build) — sem imagens, ele roda intent-first.
+
+O protótipo é mock-only e nunca vira feedback canônico.
 
 ## Saídas em disco
 
 | Arquivo | O que contém |
 |---|---|
-| `.aioson/briefings/{slug}/review.html` | Superfície de revisão local e editável |
-| `.aioson/briefings/{slug}/refinement-feedback.json` | Feedback estruturado (a única fonte que o agente aplica) |
-| `.aioson/briefings/{slug}/refinement-report.md` | Relatório do que foi aplicado, pulado ou bloqueado |
+| `.aioson/briefings/{slug}/refinement-findings.json` | Achados da auditoria do agente (entrada do CLI) |
+| `.aioson/briefings/{slug}/review.html` | Superfície de revisão renderizada pelo CLI |
+| `.aioson/briefings/{slug}/refinement-feedback.json` | Feedback estruturado v1.1 (a única fonte que é aplicada) |
+| `.aioson/briefings/{slug}/refinement-report.md` | Relatório da rodada: aplicado, pulado, bloqueado, achados |
+| `.aioson/briefings/{slug}/refinement-*.{applied,declined}-round{N}.json` | Arquivo morto por rodada (feedback aplicado ou recusado, e findings consumidos) |
 | `.aioson/briefings/{slug}/briefings.md` | Atualizado **apenas** após confirmação |
 | `.aioson/briefings/config.md` | Índice/registro de briefings atualizado |
 
@@ -105,15 +125,19 @@ O diferencial deste agente. O `review.html` é **estático, local e self-contain
 
 - Nunca cria ou edita `prd*.md`.
 - Nunca aprova um briefing automaticamente.
-- Nunca roteia para `@product` enquanto houver itens bloqueantes.
+- Nunca roteia para `@product` enquanto houver itens bloqueantes (inclusive achado bloqueante pendente).
 - Nunca trata HTML/DOM editado como feedback canônico — só o JSON estruturado.
+- Nunca escreve `review.html` à mão nem aplica feedback manualmente enquanto os comandos CLI existirem — o done-gate (`verify:artifact --kind=review`) rejeita superfícies feitas à mão.
 - Nunca descarta seções obrigatórias do briefing.
-- Em V1, não há comando CLI dedicado de refinement — tudo passa pelo agente.
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/briefing-refiner --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
 
 ## Handoff típico
 
 - **Vem de:** [`@briefing`](./briefing.md) (briefing gerado) ou de você, retomando uma revisão.
-- **Vai para:** depois de aplicar as mudanças e sem bloqueios → `aioson briefing:approve . --slug={slug}` → [`@product`](./product.md). Se sobrar bloqueio, você resolve no review e reativa o `@briefing-refiner`.
+- **Vai para:** depois de aplicar as mudanças e sem bloqueios → `aioson briefing:approve . --slug={slug}` → [`@product`](./product.md); para superfícies ricas, o modo prototype antes. Se sobrar bloqueio, a próxima rodada do loop resolve — nunca edição manual.
 
 ## Próximo passo
 

package/docs/pt/4-agentes/briefing.md

@@ -72,10 +72,14 @@ Você > Todos.
 
 > **Fast path de ativação (v1.29.0):** ativar `@briefing` "seco", sem nomear plano ou tarefa, carrega **só** o `project.context.md`, o frontmatter do registro e a *listagem de nomes* de `plans/` — apresenta o menu e para. O conteúdo dos planos e PRDs acima entra só no passo que os usa. Veja [Carregamento seletivo de contexto](../5-referencia/memoria-e-contexto.md#carregamento-seletivo-de-contexto-v1290).
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/briefing --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** você, com anotações em `plans/` ou uma ideia conversacional.
-- **Vai para:** `@product` (que usa o briefing como contexto enriquecido no PRD).
+- **Vai para:** [`@briefing-refiner`](./briefing-refiner.md) (opcional — loop de revisão e refino do briefing antes do PRD) ou, após `aioson briefing:approve`, `@product` (que usa o briefing como contexto enriquecido no PRD).
 
 ## Modo conversacional
 
@@ -93,5 +97,6 @@ Você > Sim.
 ## Próximo passo
 
 - Entender o fluxo completo → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)
+- Revisar e refinar o briefing antes do PRD → [@briefing-refiner](./briefing-refiner.md)
 - Após o briefing aprovado → [@product](./product.md) *(ficha em construção)*
 - Termos como "gap" e "PRD" → [Glossário](../1-entender/glossario.md)

package/docs/pt/4-agentes/dev.md

@@ -108,16 +108,34 @@ Depende do modo:
 
 **Nunca carrega** arquivos de outros agentes (`.aioson/agents/`), specs de outras features, ou mais de 5 arquivos antes do primeiro código.
 
+**Inputs de UI (modo feature):** quando o PRD tem `## Prototype reference`, o `@dev` reproduz as telas e interações do `prototype.html`; e quando `design_skill: interface-design` e existe um `identity.md` (`.aioson/briefings/{slug}/identity.md`, senão `.aioson/context/identity.md`), ele o lê como input visual ao lado da referência de protótipo — é a identidade extraída das suas imagens de referência, e o `@dev` não entrega visual genérico enquanto ela existir.
+
 ---
 
 ## Detalhes recentes
 
-**Ciclo autônomo QA→Dev (cap 2, Mai 2026):** quando o `@qa` encontra falhas pequenas (testes falhando, AC não atendido), ele pode enviar correções diretamente ao `@dev` sem você precisar reativar manualmente. O ciclo se repete no máximo 2 vezes. Na terceira falha, ele sobe para você decidir.
+**Ciclo autônomo QA→Dev (cap 3):** quando o `@qa` encontra falhas pequenas (testes falhando, AC não atendido), ele pode enviar correções diretamente ao `@dev` sem você precisar reativar manualmente. O ciclo se repete no máximo 3 vezes (`agentic_policy.review_cycle`, configurável). Ao esgotar as tentativas, ele sobe para você decidir.
 
 **dev-resume helper:** se o `dev-state.md` existe mas está inconsistente com o código (drift detection), o `@dev` detecta a divergência e te avisa antes de continuar.
 
 ---
 
+## Modo de execução: autopilot
+
+- `/dev --auto`: arma o autopilot a partir daqui mesmo sem flag/esquema prévio — a implementação e o ciclo de revisão pós-dev (`@qa` → `@tester`/`@pentester` quando o trigger dispara → `@validator`) rodam sozinhos até a recomendação de `feature:close`.
+- `/dev --step`: desarma o autopilot **só para esta feature** — para no handoff `@dev → @qa` mesmo em projeto com `auto_handoff: true`. Uma escolha por feature sempre vence a flag do projeto.
+- Sem token: segue o esquema/flag já ativo, se houver.
+
+Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md) para a cadeia completa e as condições de parada.
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/dev --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Comandos CLI relacionados
 
 ```bash

package/docs/pt/4-agentes/deyvin.md

@@ -83,6 +83,10 @@ cat .aioson/context/dev-state.md
 npx @jaimevalasek/aioson live:start . --tool=claude --agent=deyvin --no-launch
 ```
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/deyvin --help`, ou `/pair --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** `@dev` (quando uma sessão fica incompleta) ou `@neo` (quando detecta `in_progress`).

package/docs/pt/4-agentes/discover.md

@@ -99,6 +99,10 @@ ls .aioson/context/bootstrap/
 cat .aioson/context/bootstrap/entities.md
 ```
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/discover --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** `@setup` (primeira vez) ou qualquer ponto quando o cache está stale.

package/docs/pt/4-agentes/neo.md

@@ -77,6 +77,10 @@ npx @jaimevalasek/aioson workflow:next .
 npx @jaimevalasek/aioson memory:summary . --last=5
 ```
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/neo --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ## Handoff típico
 
 - **Vem de:** qualquer ponto — @neo é válido em qualquer momento.

package/docs/pt/4-agentes/orache.md

@@ -94,6 +94,12 @@ Você > @orache nutrição esportiva para atletas amadores
 
 ---
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/orache --help`) imprime um resumo rápido — o que faz, quando usar, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Handoff típico
 
 - **Vem de:** `@squad` (redirect automático) ou pedido direto do usuário

package/docs/pt/4-agentes/orchestrator.md

@@ -111,6 +111,18 @@ Se o PRD tiver gaps ou decisões técnicas difíceis, rode `@sheldon` antes de `
 
 ---
 
+## Autopilot: travessia automática para `@dev`
+
+Sob autopilot (`auto_handoff: true`, esquema já semeado para a feature, ou token `--auto` recebido do `@product`), `@orchestrator` não para no handoff manual: uma vez com o pacote de spec com gates aprovados (Gates A/B/C, readiness pronta) + `dev-state.md` gravados, ele invoca `@dev` diretamente. O fan-out para `@analyst`/`@architect`/`@pm` acontece como sub-agentes internos — eles não viram estágios do workflow, exceto sob um detour opt-in full-chain. Um gate bloqueado ou readiness `blocked` continua sendo parada manual normal. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/orchestrator --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Saídas em disco
 
 | Arquivo/Diretório | Conteúdo |

package/docs/pt/4-agentes/pentester.md

@@ -117,6 +117,12 @@ Você > checkout-stripe
 
 ---
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/pentester --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Handoff típico
 
 - **Vem de:** `@dev` (na lane MEDIUM, onde é inline) — ou você diretamente / `@tester` (detour em SMALL/MICRO)

package/docs/pt/4-agentes/product.md

@@ -65,6 +65,24 @@ Você > Não salvar cartões. Um cartão por pedido. Fora de escopo: parcelament
 
 ---
 
+## Modo de execução: autopilot ou passo a passo
+
+No handoff do PRD, `@product` decide como a feature vai rodar daqui em diante:
+
+- **Token inline (maior precedência, nunca pergunta):** `/product --auto <tarefa>` arma o autopilot para toda a feature; `/product --step <tarefa>` desarma para esta feature (grava a escolha mesmo em projeto "sempre autopilot"). O token é removido do texto da tarefa.
+- **Sem token, com escolha já registrada** (`auto_handoff: true`/`false` no `project.context.md`, ou um esquema já semeado para esta feature): `@product` segue a escolha em silêncio.
+- **Sem token e sem escolha registrada:** `@product` pergunta uma vez, na tela, ao fechar o PRD — *Autopilot (só esta feature)* / *Passo a passo* / *Sempre autopilot neste projeto* (grava `auto_handoff: true`).
+
+Escolhendo autopilot, `@product` semeia o esquema agêntico (`aioson workflow:execute . --feature={slug} --seed`) e invoca automaticamente o próximo agente — `@sheldon` (SMALL), `@orchestrator` (MEDIUM) ou `@dev` (MICRO) — que por sua vez encadeia sozinho até a recomendação de `aioson feature:close`. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md) para a cadeia completa e as condições de parada.
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/product --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Saídas em disco
 
 | Arquivo | Quando cria |
@@ -101,7 +119,7 @@ aioson context:validate .
 ## Handoff típico
 
 - **Vem de:** `@setup` (projeto novo) ou você mesmo (nova feature)
-- **Vai para:** `@analyst` (SMALL/MEDIUM) ou `@dev` (MICRO sem novas entidades)
+- **Vai para:** `@sheldon` (SMALL — lane lean) · `@orchestrator` (MEDIUM — lane maestro) · `@dev` (MICRO)
 
 ---
 

package/docs/pt/4-agentes/qa.md

@@ -90,10 +90,18 @@ Você > @qa
 
 ## Detalhes recentes
 
-**Ciclo autônomo QA→Dev (Mai 2026):** em falhas pequenas e localizadas, `@qa` itera com `@dev` automaticamente, com cap de 2 rodadas. Na terceira falha, para e pede sua intervenção. Isso evita loops infinitos sem perder a agilidade de correções óbvias.
+**Ciclo autônomo QA→Dev (cap 3):** em falhas pequenas e localizadas, `@qa` itera com `@dev` automaticamente, com cap de 3 rodadas (`agentic_policy.review_cycle`). Ao esgotar as tentativas, para e pede sua intervenção. Isso evita loops infinitos sem perder a agilidade de correções óbvias.
 
 **Suporte a Sheldon phased plans:** quando a feature usa um plano por fases, `@qa` valida fase a fase, marcando `qa_approved` só quando todos os Criticals/Highs da fase estão resolvidos.
 
+**`@qa` é o hub do autopilot pós-dev:** sob autopilot (`auto_handoff: true`, esquema semeado, ou token `--auto`), `@qa` não para no PASS — ele encaminha automaticamente para `@tester` (se o trigger de gap de cobertura disparar), `@pentester` (se a superfície é sensível: auth/pagamentos/upload/secrets) e `@validator` (se há harness-contract), nessa ordem, até não sobrar pendência. Só então recomenda `aioson feature:close`. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/qa --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ---
 
 ## Comandos CLI relacionados
@@ -113,7 +121,7 @@ aioson dossier:show . --slug=checkout-stripe
 ## Handoff típico
 
 - **Vem de:** `@dev`
-- **Vai para:** `@validator` (quando há harness-contract) ou encerramento da feature
+- **Vai para:** `@tester` (gap de cobertura) · `@pentester` (superfície sensível) · `@validator` (harness-contract presente) — ou recomendação de `feature:close` quando nada fica pendente
 
 > Desde a v1.24.0, o `@validator` roda `aioson harness:check` **primeiro** (verificação determinística, exit 0 = pass) e julga por LLM só os critérios sem `verification`. Ele é ativado a partir do `validator-prompt.txt` autocontido (critérios + resultados do check + diff vs. base) em **contexto fresco e isolado** — não na sessão que implementou. Ver [Ficha do @validator](./validator.md).
 

package/docs/pt/4-agentes/setup.md

@@ -50,7 +50,9 @@ Você > Stripe e S3 (2)
 Você > Não
 
 @setup > Score: 1 + 1 + 0 = 2 → SMALL.
-         Design system?
+         Sistema visual? Recomendo interface-design guiado pelas suas
+         imagens de referência (extraídas uma única vez em identity.md).
+         Ou um preset instalado:
          [clean-saas-ui · aurora-command-ui · cognitive-core-ui · (outros) · Pular]
 Você > clean-saas-ui
 

package/docs/pt/4-agentes/sheldon.md

@@ -123,6 +123,18 @@ No MEDIUM, `@sheldon` pode atuar de duas formas:
 
 ---
 
+## Autopilot: travessia automática para `@dev`
+
+Sob autopilot (`auto_handoff: true`, esquema já semeado para a feature, ou token `--auto` recebido do `@product`), `@sheldon` não para no handoff manual: uma vez com sizing/enriquecimento confirmados e o pacote lean + `dev-state.md` gravados, ele semeia o esquema agêntico (`aioson workflow:execute . --feature={slug} --seed`), completa o próprio estágio (`aioson workflow:next . --complete=sheldon`) e invoca `@dev` diretamente. Um Gate A/B/C bloqueado, ou uma decisão de sizing/escopo ainda em aberto, continua sendo parada manual normal. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/sheldon --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Saídas em disco
 
 | Arquivo | Criado por | Consumido por |

package/docs/pt/4-agentes/tester.md

@@ -92,6 +92,12 @@ Você > Sim
 
 ---
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/tester --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Handoff típico
 
 - **Vem de:** `@qa` (que identificou gaps) ou você diretamente

package/docs/pt/4-agentes/ux-ui.md

@@ -14,7 +14,7 @@ Quando o dev implementa a UI sem especificação, ele toma decisões de design n
 
 `@ux-ui` existe para separar "o que a interface faz" (responsabilidade dele) de "como o código implementa" (responsabilidade do `@dev`). Ele produz uma especificação de componentes, tokens e fluxos que o `@dev` segue como contrato.
 
-Ele é guiado pelo design skill do projeto — se `clean-saas-ui` estiver configurado, ele usa apenas esse sistema. Se nenhum skill estiver definido, ele para e pergunta antes de avançar.
+Ele é guiado pelo design skill do projeto — se `clean-saas-ui` estiver configurado, ele usa apenas esse sistema. Se nenhum skill estiver definido, ele para e oferece as **duas rotas** (espelhando o `@setup`): `interface-design` guiado pelas **suas imagens de referência** — extraídas uma única vez em `identity.md` pela skill `reference-identity-extract` — ou um **preset instalado** da lista. Nunca escolhe sozinho.
 
 > **Posição no fluxo (v1.35.0):** no MEDIUM, `@ux-ui` é disparado como **sub-agente de fan-out** pelo `@orchestrator` quando a feature tem UI pesada — você não precisa invocá-lo manualmente. No SMALL e no MICRO, `@dev` aplica o design skill diretamente; `@ux-ui` fica como detour opt-in quando você quer especificação de UI detalhada antes da implementação.
 
@@ -81,6 +81,7 @@ Você > @ux-ui
 
 - `.aioson/context/project.context.md` — detecta `design_skill`
 - `.aioson/skills/design/{design_skill}/SKILL.md` — **único** sistema visual carregado
+- `.aioson/briefings/{slug}/identity.md` (senão `.aioson/context/identity.md`) — quando `design_skill: interface-design`: identidade visual extraída das suas imagens de referência, **input** que o motor aplica (não é um segundo skill)
 - `.aioson/context/prd-{slug}.md`, `discovery.md`, `architecture.md`
 - `.aioson/context/spec-{slug}.md` (feature mode)
 - `.aioson/rules/` — regras com `agents: ux-ui`

package/docs/pt/5-referencia/README.md

@@ -12,7 +12,7 @@
 |---|---|
 | [loop-guardrails.md](./loop-guardrails.md) | Contrato verificável para o self:loop: scope guard, budget, human gates, criteria evaluation (v1.22.0) |
 | [harness-retro.md](./harness-retro.md) | Minerar o histórico de falhas de uma feature sem LLM — dossiê retrospectivo + harness:preview (v1.23.0) |
-| [autopilot-handoff.md](./autopilot-handoff.md) | Encadeamento automático de agentes pré-dev e pós-dev — opt-in via auto_handoff: true (v1.21.x–v1.22.0) |
+| [autopilot-handoff.md](./autopilot-handoff.md) | Full-feature autopilot: cadeia @product → @sheldon/@orchestrator → @dev → @qa (hub) → @tester/@pentester/@validator até `feature:close`; tokens inline `--auto`/`--step`, opção `--help` nos 13 agentes mais usados |
 | [feature-dossier.md](./feature-dossier.md) | Dossier de feature: ponto único de verdade (spec, plano, histórico, status) |
 | [agent-chain-continuity.md](./agent-chain-continuity.md) | Sistema de continuidade entre sessões — Fases 1–8 (dev-resume, drift detection, handoff v2) |
 | [sdd-framework.md](./sdd-framework.md) | Spec-Driven Development: Constitution, project-pulse, skill aioson-spec-driven, MICRO/SMALL/MEDIUM |

package/docs/pt/5-referencia/agent-chain-continuity.md

@@ -93,7 +93,7 @@ autoridade de spec:
 @pentester (MEDIUM, inline) → findings → @dev corrige → @pentester re-varre
         │
         ▼
-@qa → runtime smoke gate + ACs → devolve para @dev se houver falhas (ciclo autônomo, cap 2)
+@qa → runtime smoke gate + ACs → devolve para @dev se houver falhas (ciclo autônomo, cap 3)
         │
         ▼
 @validator → verifica contra harness-contract em contexto isolado → gate final → feature:close