@jaimevalasek/aioson 1.36.0 → 1.37.0

package/docs/en/5-reference/cli-reference.md

@@ -73,6 +73,8 @@ aioson update --lang=pt-BR
 
 **What it updates:** all files in the `MANAGED_FILES` list that match your install profile (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
 
+**Output:** on completion, prints `Template version applied: <version>` (and `(<sha>, <date>)` when the install is a git checkout — e.g. an `npm link`ed dogfood setup) so you can tell exactly which template landed.
+
 ---
 
 ## info
@@ -346,6 +348,10 @@ aioson workflow:next ./my-project --skip=dev
 - `agent:next` is an alias for compatibility
 - `workflow.config.json` and `workflow.state.json` live under `.aioson/context/`, so normal framework updates preserve them
 
+### workflow:execute --seed (full-feature autopilot)
+
+`aioson workflow:execute . --feature=<slug> --seed --tool=<tool>` seeds the agentic scheme (`.aioson/context/workflow-execute.json` with `agentic_policy.enabled: true`) without advancing a stage — this is what a spec agent (`@product`/`@sheldon`/`@orchestrator`) runs on its own once it finishes, to arm the full-feature autopilot chain described in [Autopilot handoff](./autopilot-handoff.md). Add `--step` to seed it already disarmed (equivalent to the inline `--step` token). A stale `workflow.state.json` left by a closed/abandoned feature is discarded and reseeded automatically; a genuinely different active feature returns `different_active_feature` — close/pause it, or run `aioson feature:sweep .` to discard stale state explicitly.
+
 ---
 
 ## feature:close

package/docs/pt/1-entender/glossario.md

@@ -129,7 +129,7 @@ Termos em ordem alfabética. Cada um tem **definição curta** + **exemplo concr
 
 **Exemplos prontos:** Clean SaaS UI, Aurora Command UI, Cognitive Core UI, Bold Editorial UI, Warm Craft UI, Glassmorphism UI, Neo Brutalist UI.
 
-**Onde escolher:** durante o `aioson init`, no wizard.
+**Onde escolher:** durante o `aioson init`, no wizard, ou depois com `@setup`/`@ux-ui`. A rota recomendada é o motor `interface-design` guiado pelas suas **imagens de referência**, extraídas uma única vez num `identity.md` que o motor aplica; os presets ficam como alternativa explícita.
 
 ---
 

package/docs/pt/1-entender/mapa-do-ecossistema.md

@@ -88,7 +88,7 @@ A ordem padrão depende da classificação (v1.35.0):
 | **`@pm`** | Backlog, user stories, plano de implementação. **MEDIUM:** sub-agente do `@orchestrator`. **Qualquer tamanho:** detour opt-in. | `tasks.md`, `implementation-plan-{slug}.md` |
 | **`@orchestrator`** | **MEDIUM:** maestro de spec (faz fan-out para @analyst/@architect/@pm/@ux-ui, consolida e verifica, entrega pacote de spec com Gates A/B/C). Também coordena lanes paralelas de implementação pós-spec. | `parallel/`, `implementation-plan-{slug}.md`, `harness-contract.json` |
 | **`@dev`** | Implementa a feature | Código + `dev-state.md` |
-| **`@qa`** | Escreve testes, valida ACs, ciclo autônomo de correção (cap 2) | `test-plan.md`, `qa-report-*.md` |
+| **`@qa`** | Escreve testes, valida ACs, ciclo autônomo de correção (cap 3), hub do autopilot pós-dev (roteia para `@tester`/`@pentester`/`@validator`) | `test-plan.md`, `qa-report-*.md` |
 | **`@validator`** | Valida tecnicamente contra `harness-contract.json` em sandbox de contexto | `.aioson/plans/{slug}/last-validator-output.json` (consumido por `harness:apply-validation`, atualiza `progress.json`) |
 | **`@tester`** | Engenharia sistemática de testes (legacy/brownfield) | `test-inventory.md`, coverage tier |
 | **`@pentester`** | Revisão adversarial de segurança (OWASP, LLM Top 10) | `security-findings-*.json` |

package/docs/pt/2-comecar/decisoes-iniciais.md

@@ -133,7 +133,9 @@ npx @jaimevalasek/aioson squad:scaffold compliance
 
 ## Escolhendo o Design System
 
-Disponíveis no wizard:
+> **Rota recomendada: `interface-design` + suas imagens de referência.** Em vez de herdar o visual idêntico de um preset fixo, você fornece imagens de referência (identidade/marca e, opcionalmente, estrutura de componentes); a skill `reference-identity-extract` as converte **uma única vez** num `identity.md` de texto que o motor `interface-design` aplica em tudo que vier depois (protótipo e build). O `@setup` oferece essa rota primeiro — sempre com confirmação explícita, nunca auto-seleção. Os presets abaixo continuam disponíveis como alternativa.
+
+Presets disponíveis no wizard:
 
 | Skill | Estilo | Casos |
 |---|---|---|
@@ -146,7 +148,7 @@ Disponíveis no wizard:
 | **Neo Brutalist UI** | Contornos pretos, cores fortes, sem sombra | Marcas marcantes |
 
 **Pular** é uma opção legítima. Você pode:
-- Escolher depois com `@ux-ui`
+- Escolher depois com `@ux-ui` — ele oferece as mesmas duas rotas (imagens de referência ou preset)
 - Clonar o design de um site real com `@site-forge`
 - Criar um híbrido com `@design-hybrid-forge` (ex: clean-saas + neo-brutalist)
 

package/docs/pt/2-comecar/primeiro-projeto.md

@@ -229,7 +229,7 @@ Você > @qa
 @qa > test-plan.md e qa-report.md gravados. Feature pronta.
 ```
 
-> **A novidade:** o ciclo *autônomo QA→Dev* (cap 2) deixa o @qa pedir correções pequenas sem você ter que reativar manualmente. Foi adicionado em Mai/2026.
+> **A novidade:** o ciclo *autônomo QA→Dev* (cap 3, `agentic_policy.review_cycle`) deixa o @qa pedir correções pequenas sem você ter que reativar manualmente. Sob autopilot, esse mesmo ciclo pode encadear até `@tester`/`@pentester`/`@validator` e a recomendação de `feature:close` sem parar — veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
 
 ---
 

package/docs/pt/3-receitas/da-ideia-ao-prd-via-briefing.md

@@ -23,6 +23,8 @@ ideia vaga / anotações
        ↓
    @briefing   →  .aioson/briefings/{slug}/briefings.md
        ↓
+ (opcional) @briefing-refiner  →  loop de refino: auditoria + review.html + apply-feedback
+       ↓
 aioson briefing:approve
        ↓
    @product   →  prd.md (ou prd-{slug}.md)
@@ -87,7 +89,11 @@ Você > Todos.
 
 ### Passo 3 — Revise e aprove
 
-Leia `.aioson/briefings/notificacoes-push/briefings.md`. Se estiver bom:
+Leia `.aioson/briefings/notificacoes-push/briefings.md`.
+
+> **Quer uma revisão estruturada antes de aprovar?** Ative o [`@briefing-refiner`](../4-agentes/briefing-refiner.md): ele audita o briefing em achados estruturados (categoria, severidade, bloqueio), o CLI renderiza a superfície `review.html` (`aioson briefing:review . --slug=notificacoes-push`) para você decidir cada achado e editar cada seção **num navegador de verdade**, e o feedback confirmado é aplicado com `aioson briefing:apply-feedback . --slug=notificacoes-push --confirm` — em rodadas, até nada bloquear o PRD.
+
+Se estiver bom:
 
 ```bash
 aioson briefing:approve
@@ -231,4 +237,5 @@ plans/                              ← seus rascunhos (intocados)
 - [Plans externos para @product](./plans-externos-para-product.md) — como usar ChatGPT/Claude.ai como fonte para `plans/`
 - [Feature completa com @sheldon](./feature-completa-com-sheldon.md) — quando o PRD está pronto e a trilha é SMALL/MEDIUM
 - [@briefing — ficha](../4-agentes/briefing.md) — referência técnica do agente
+- [@briefing-refiner — ficha](../4-agentes/briefing-refiner.md) — loop de revisão/refino do briefing antes do PRD
 - [@product — ficha](../4-agentes/product.md) — referência técnica do agente

package/docs/pt/3-receitas/feature-completa-com-sheldon.md

@@ -24,6 +24,8 @@
 
 `@orchestrator` é o maestro de spec: faz fan-out para `@analyst` + `@architect` + `@pm` (+ `@ux-ui` quando UI-heavy) como sub-agentes, consolida os artefatos, e entrega o pacote de spec aprovado para `@dev`. `@pentester` é inline (entre `@dev` e `@qa`).
 
+> **Passo a passo ou autopilot?** Esta receita mostra o fluxo **manual** — você invoca cada agente. Mas construir a feature do jeito normal (`@product` → `@sheldon`/`@orchestrator` → `@dev` → `@qa`) também pode rodar **sozinho** até a recomendação de `feature:close`: `@product` pergunta o modo de execução uma vez no handoff do PRD (ou você já decide na hora com `/product --auto`/`/product --step`), e cada agente invoca o próximo automaticamente. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md) para a cadeia completa, os tokens inline e as condições de parada. Os passos abaixo continuam valendo — é o que cada agente faz por trás, autopilot ligado ou não.
+
 ---
 
 ## SMALL lean — passo a passo
@@ -267,7 +269,7 @@ Você > @pentester
 | **MEDIUM, você quer gerenciar a spec manualmente** | `@product → @analyst → @architect → @ux-ui → @pm → @orchestrator (lanes only) → @dev → @pentester → @qa` — o "escape hatch" full-merged. |
 | **Sessão caiu no meio do `@dev`** | `@deyvin` retoma. Ver [Continuidade entre sessões](./continuidade-entre-sessoes.md). |
 | **`@sheldon` reclama que PRD está vago** | Volte ao `@product` e refine. `@sheldon` não inventa o que não está claro. |
-| **Ciclo `@qa ↔ @dev` estourou cap 2** | Há defeito de design. Volte ao `@sheldon` (SMALL) ou `@orchestrator` (MEDIUM) antes de mais código. |
+| **Ciclo `@qa ↔ @dev` estourou cap 3** | Há defeito de design. Volte ao `@sheldon` (SMALL) ou `@orchestrator` (MEDIUM) antes de mais código. |
 | **`@pentester` HIGH não baixa** | Não force. Documente como risco aceito ou adie a feature. |
 
 ---

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

@@ -1,9 +1,11 @@
 # Guia de Agentes AIOSON
 
-> Índice com 30 agentes e 1 alias, com situação de uso e saída esperada.
+> Índice com 31 agentes e 1 alias, com situação de uso e saída esperada.
 > Cada agente tem sua ficha — clique no nome para detalhes.
 > `@pair` é alias de `@deyvin` e não possui ficha separada.
 
+> **As colunas "Quando invocar" abaixo descrevem a capacidade de cada agente, não a ordem obrigatória do fluxo padrão.** Desde a lane lean/maestro (v1.35.0), o fluxo padrão é `@product → @sheldon → @dev → @qa` (SMALL) ou `@product → @orchestrator → @dev → @pentester → @qa` (MEDIUM) — `@analyst`, `@architect`, `@ux-ui` e `@pm` são detours opt-in ou sub-agentes do fan-out do `@orchestrator`, não hops obrigatórios. Construir a feature assim também pode rodar sozinho até a recomendação de `feature:close` — veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
 ---
 
 ## Núcleo de desenvolvimento (neste diretório)
@@ -11,14 +13,15 @@
 | Agente | Para que serve | Quando invocar | Saída principal |
 |---|---|---|---|
 | [@product](./product.md) | Define visão, PRD e escopo da feature | Início de projeto ou nova feature | `prd.md`, `spec.md` |
-| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Após `@product`, antes de `@architect` | `architecture.md` (domínio) |
-| [@scope-check](./scope-check.md) | Confronta intenção, plano e artefatos antes do código | Antes de `@dev` e após fixes relevantes | `scope-check.md` |
-| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Após `@analyst` | `architecture.md` (técnico) |
-| [@ux-ui](./ux-ui.md) | Design system e specs de componentes | MEDIUM, após `@architect` | `design-doc.md`, `discovery.md` |
-| [@pm](./pm.md) | Backlog, user stories, ACs detalhados | MEDIUM, após `@ux-ui` | `tasks.md` |
-| [@orchestrator](./orchestrator.md) | Coordena lanes paralelas de implementação | MEDIUM, após `@pm` | `.aioson/context/parallel/` |
-| [@dev](./dev.md) | Implementa a feature | Após planning completo | código + `dev-state.md` |
-| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
+| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Detour opt-in / sub-agente do `@orchestrator` (MEDIUM) | `architecture.md` (domínio) |
+| [@scope-check](./scope-check.md) | Confronta intenção, plano e artefatos antes do código | `spec:analyze` roda automático no gate `@dev`/`@qa`; detour explícito também disponível | `scope-check.md` |
+| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Detour opt-in / sub-agente do `@orchestrator` (MEDIUM) | `architecture.md` (técnico) |
+| [@ux-ui](./ux-ui.md) | Design system e specs de componentes | Detour opt-in para specs UI-heavy | `design-doc.md`, `discovery.md` |
+| [@pm](./pm.md) | Backlog, user stories, ACs detalhados | Sub-agente do `@orchestrator` (MEDIUM) ou detour opt-in | `tasks.md` |
+| [@sheldon](./sheldon.md) | **Autoridade única de spec (SMALL)** — requirements + decisões técnicas + plano faseado + harness-contract numa passada | Após `@product`, padrão do SMALL | `requirements-*.md`, `implementation-plan-*.md`, `harness-contract.json` |
+| [@orchestrator](./orchestrator.md) | **Maestro de spec (MEDIUM)** — fan-out para `@analyst`/`@architect`/`@pm` (+`@ux-ui`), consolida o pacote de spec com Gates A/B/C; secundário: coordena lanes paralelas pós-spec | Após `@product`, padrão do MEDIUM | `.aioson/context/parallel/`, pacote de spec consolidado |
+| [@dev](./dev.md) | Implementa a feature | Após o pacote de spec (`@sheldon`/`@orchestrator`) ou direto após `@product` (MICRO) | código + `dev-state.md` |
+| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` (cap 3), hub do autopilot pós-dev | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
 | [@validator](./validator.md) | Gate final: valida contrato binário de sucesso | Após `@qa`, antes de fechar feature | veredicto em `last-handoff.json` |
 | [@forge-run](./forge-run.md) | Lane B opt-in: compila e roda o workflow de verificação executável de uma feature MEDIUM | MEDIUM com contrato `verification` + plano com Wave | `forge-run.workflow.js` |
 | [@tester](./tester.md) | Engenharia de testes para apps já existentes | Legacy/brownfield ou lacunas graves | `test-inventory.md` |
@@ -33,10 +36,9 @@
 | [@setup](./setup.md) | Onboarding: detecta stack, classifica projeto | Sempre primeiro num projeto novo | `project.context.md` |
 | [@neo](./neo.md) | Roteador: diz qual agente é o próximo | Quando você está perdido | Orientação verbal |
 | [@briefing](./briefing.md) | Transforma anotações soltas em briefing pré-PRD | Antes de `@product`, quando ideia ainda vaga | `briefing.md` |
-| [@briefing-refiner](./briefing-refiner.md) | Revisa e refina um briefing existente via superfície HTML local | Após `@briefing`, antes de `@product` | `review.html`, `refinement-report.md` |
+| [@briefing-refiner](./briefing-refiner.md) | Loop de refino de briefing: audita em achados estruturados, o CLI renderiza a revisão (`briefing:review`) e aplica o feedback confirmado (`briefing:apply-feedback`) | Após `@briefing`, antes de `@product` | `refinement-findings.json`, `review.html` (CLI), `refinement-feedback.json`, `refinement-report.md` |
 | [@deyvin](./deyvin.md) | Pair-programming e continuidade de sessão | Retomar feature interrompida | continuação do trabalho |
 | [@pair](./deyvin.md) | Alias de `@deyvin` | — | — |
-| [@sheldon](./sheldon.md) | Análise técnica profunda, revisão de arquitetura | Decisões grandes, código legado | relatório de revisão |
 | [@committer](./committer.md) | Gera mensagem de commit profissional | Após implementar, antes de commitar | mensagem de commit |
 | [@discover](./discover.md) | Constrói cache semântico do projeto | Onboarding em codebase grande | `.aioson/context/bootstrap/` |
 

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