@softize/opus 18.5.0 → 20.0.0

package/src/ui/docs/content/chat.md

@@ -1,11 +1,14 @@
 ## Conversa com resposta integral
 
-Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por dentro (estado, loading, auto-scroll; **Enter** envia, **Shift+Enter** quebra linha) — a inteligência vem da prop `send`. Com o composer vazio, **↑** recupera as mensagens anteriores do usuário e **↓** volta em direção ao rascunho; durante a edição, as setas continuam movendo o cursor normalmente. O `greeting` é o estado vazio (centrado; some quando a conversa começa e não entra no transcript). Dê altura ao container.
+Use `Chat` para uma conversa completa: transcript, composer, indicador de atividade e rolagem
+automática até a última mensagem. No modo mais simples, o componente guarda as mensagens e chama
+`send` com o histórico a cada envio; o texto devolvido entra no transcript como resposta. Dê altura
+ao contêiner, porque o transcript rola dentro dele.
 
 ```tsx preview
 <div className="h-96 rounded-lg border">
   <Chat
-    greeting="Oi! Sou o assistente. Pergunte algo."
+    greeting="Pergunte sobre os workspaces da sua equipe."
     send={async (messages) => {
       await new Promise((r) => setTimeout(r, 500))
       const last = messages[messages.length - 1]
@@ -15,12 +18,17 @@ Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por den
 </div>
 ```
 
+**Enter** envia e **Shift+Enter** quebra a linha. Com o composer vazio, **↑** recupera as mensagens
+anteriores da pessoa e **↓** volta em direção ao rascunho; durante a edição, as setas continuam
+movendo o cursor. `greeting` ocupa o transcript vazio, some quando a conversa começa e não entra no
+histórico enviado a `send`.
+
 ## Estado vazio composto
 
 Quando uma frase não basta — marca, nome do agente e saudação administrável, por exemplo — o
 app compõe o vazio com os slots de `Empty` e entrega em `empty`. O nó ocupa o mesmo lugar do
-`greeting`, vence quando os dois existem e some quando a conversa começa. Sem a moldura `Empty`
-em volta: o chat já é a estrutura, e a moldura tracejada é para região de criação.
+`greeting`, vence quando os dois existem e some quando a conversa começa. Não envolva o conteúdo em
+`Empty`: o chat já é a estrutura, e a moldura tracejada é para região de criação.
 
 ```tsx preview
 <div className="h-72 rounded-lg border">
@@ -30,8 +38,8 @@ em volta: o chat já é a estrutura, e a moldura tracejada é para região de cr
         <EmptyMedia variant="icon">
           <Sparkles />
         </EmptyMedia>
-        <EmptyTitle>Copilot</EmptyTitle>
-        <EmptyDescription>Pergunte sobre vendas, estoque, oficina ou pessoas.</EmptyDescription>
+        <EmptyTitle>Assistente da equipe</EmptyTitle>
+        <EmptyDescription>Pergunte sobre os workspaces, os membros e as atividades da equipe.</EmptyDescription>
       </EmptyHeader>
     }
     send={async () => 'Pronto.'}
@@ -39,40 +47,52 @@ em volta: o chat já é a estrutura, e a moldura tracejada é para região de cr
 </div>
 ```
 
-## O backend (o agente)
+## O backend
 
-O `send` posta a conversa no seu endpoint, que resolve o usuário e roda o agente sobre as actions `ai:enabled` — **como o usuário logado**:
+O `send` posta a conversa no endpoint do aplicativo, que resolve o usuário e executa o agente
+sobre as actions expostas à IA, com a autorização desse usuário:
 
 ```ts
 // Rota do app (server): recebe { messages }, devolve { reply }.
 async function chatRoute(req) {
-  const base = await auth.resolveContext(req)                 // quem é o usuário
+  const base = await auth.resolveContext(req)                 // Quem é o usuário.
   const { messages } = req.body
-  const { text } = await runtime.aiFor(base)!.run(messages)   // o agente age nas actions
+  const { text } = await runtime.aiFor(base)!.run(messages)   // O agente usa as actions.
   return { reply: text }
 }
 ```
 
 ```tsx
-// No cliente, o send bate nessa rota:
+// No cliente, o send chama essa rota:
 <Chat send={async (messages) => (await api.post('/chat', { messages })).reply} />
 ```
 
-O agente só executa actions marcadas com `ai.enabled` e, nelas, aplica o `authorize` com o contexto do usuário; uma action sem `authorize` fica aberta a qualquer usuário autenticado. Actions com `ai.destructive` ou `ai.requiresConfirmation` são recusadas nesse exemplo, porque ele não passa `confirm`; para aprovar essas chamadas, use `run(messages, { confirm })`. Para expor as actions ao agente, marque-as com `ai: { enabled: true }` no contrato — ver o recurso **IA generativa**.
+O agente só executa actions expostas à IA (`ai: true` ou um objeto `ai` sem `enabled: false`) e,
+nelas, aplica o `authorize` com o contexto do usuário; uma action sem `authorize` fica aberta a qualquer usuário autenticado. Actions com
+`ai.destructive` ou `ai.requiresConfirmation` são recusadas nesse exemplo, porque ele não passa
+`confirm`; para aprovar essas chamadas, use `run(messages, { confirm })`. Para expor uma action ao
+agente e conhecer as demais opções do runtime, consulte a página de [IA generativa](/docs/ai).
+
+## Streaming de eventos
+
+`send` também pode devolver um `AsyncIterable<ChatEvent>`. Assim, a resposta chega aos poucos e a
+conversa mostra o que o agente está fazendo. O protocolo tem quatro eventos:
 
-## Streaming — eventos de conversa
+- `{ type: 'text', delta }` acrescenta um trecho à resposta em andamento.
+- `{ type: 'tool', name, detail? }` informa a ferramenta em uso. O Chat mostra esse passo no
+  indicador de atividade, com o rótulo de `humanizeTool`, e não o grava no transcript.
+- `{ type: 'artifact', kind, ref, title? }` acrescenta ao transcript algo produzido na conversa,
+  apresentado por `renderArtifact` ou, sem ele, como link.
+- `{ type: 'done', ok, error? }` encerra o turno; com `ok: false`, o transcript recebe a mensagem de
+  erro.
 
-O `send` também aceita devolver um **`AsyncIterable<ChatEvent>`** (o protocolo de
-`docs/chat-event-protocol.md`): o texto chega incremental, o tool em uso vira o
-**indicador vivo** (pontinhos + rótulo humano — nunca uma mensagem no transcript) e
-artefatos produzidos na conversa rendem pelo `renderArtifact` do app. O backend liga em
-`runtime.aiFor(base).runStream(...)` e streama por SSE; o `Promise<string>` de sempre
-continua valendo — é o caso degenerado do protocolo.
+No backend, `runtime.aiFor(base).runStream(...)` emite esses eventos, que podem seguir por SSE.
+Devolver `Promise<string>` continua válido: equivale a um único `text` seguido de `done`.
 
 ```tsx preview
 <div className="h-96 rounded-lg border">
   <Chat
-    greeting="Oi! Pergunte algo — a resposta chega em streaming."
+    greeting="Pergunte algo e acompanhe a resposta chegando aos poucos."
     send={async function* (messages) {
       yield { type: 'tool', name: 'query' }
       await new Promise((r) => setTimeout(r, 600))
@@ -88,32 +108,93 @@ continua valendo — é o caso degenerado do protocolo.
 </div>
 ```
 
-Reidratação: passe `initialMessages` com o histórico persistido e troque a `key` do
-componente ao trocar de conversa. O rótulo do indicador é customizável por
-`humanizeTool={(name) => '…'}`.
+Para retomar uma conversa salva, passe `initialMessages` com o histórico persistido e troque a
+`key` do componente ao trocar de conversa. `kickoff` inicia a conversa pelo assistente, uma vez,
+quando o transcript nasce vazio.
 
-Itens controlados podem carregar `id` e `createdAt`. O Chat os projeta no elemento da
-mensagem e oferece `renderMessageActions` para ações contextuais discretas tanto nas mensagens
-enviadas quanto nas recebidas. O slot não busca nem conhece detalhes: o app deve carregar
-informação complementar somente após a interação da pessoa e aplicar novamente sua autorização.
+## Conversa controlada pelo aplicativo
+
+Quando o aplicativo já é dono do transcript — por exemplo, porque o servidor mantém a conversa e a
+reenvia a cada reconexão —, passe `messages` em vez de `send`. Nesse modo, `onSend` recebe o texto
+enviado, `busy` bloqueia novos envios enquanto o turno corre e `activity` controla o indicador.
+`busy` não bloqueia a digitação: a pessoa pode escrever a próxima mensagem enquanto espera.
+Retornar `false` em `onSend` devolve o texto ao composer, para que nada se perca em uma falha de
+envio.
+
+Os itens podem carregar `id` e `createdAt`. `renderMessageActions` acrescenta ações discretas às
+mensagens enviadas e recebidas, visíveis em hover ou foco. O slot não busca dados: carregue
+informação complementar somente depois da interação da pessoa e aplique novamente a autorização.
+No exemplo, `activity=""` mostra somente os pontos, sem rótulo, e cada mensagem oferece a cópia do
+texto.
+
+```tsx preview
+const nextId = useRef(3)
+const [items, setItems] = useState<ChatTranscriptItem[]>([
+  { id: '1', role: 'user', content: 'Qual é o status da Empresa X?' },
+  { id: '2', role: 'assistant', content: 'A Empresa X está **ativa**, com 3 agentes.' },
+])
+const [busy, setBusy] = useState(false)
+
+render(
+  <div className="h-96 rounded-lg border">
+    <Chat
+      messages={items}
+      busy={busy}
+      activity={busy ? '' : undefined}
+      onSend={async (text) => {
+        setItems((list) => [...list, { id: String(nextId.current++), role: 'user', content: text }])
+        setBusy(true)
+        await new Promise((r) => setTimeout(r, 800))
+        setItems((list) => [
+          ...list,
+          { id: String(nextId.current++), role: 'assistant', content: 'Mensagem registrada.' },
+        ])
+        setBusy(false)
+      }}
+      renderMessageActions={(message) => (
+        <Copyable
+          value={message.content}
+          aria-label="Copiar mensagem"
+          className="text-muted-foreground hover:text-foreground"
+        />
+      )}
+    />
+  </div>,
+)
+```
+
+`activity` aceita `undefined`, que esconde o indicador; `null`, que mostra “Pensando…”; uma string
+com o rótulo já humanizado pelo aplicativo; ou `''`, que mostra somente os pontos e mantém
+“Pensando…” como nome acessível. No modo autogerenciado, o Chat decide o indicador sozinho e ignora
+`busy` e `activity`.
 
 ## Propriedades de Chat
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `send` | `(messages: ChatMessage[]) => Promise<string> \| AsyncIterable<ChatEvent>` | | Modo autogerenciado: envia o histórico e devolve a resposta inteira ou um stream de eventos. Ignorado no modo controlado. |
-| `messages` | `ChatTranscriptItem[]` | | Modo controlado: o transcript vem do app; com ele, `onSend`, `busy` e `activity` assumem. |
+| `send` | `(messages: ChatMessage[]) => Promise<string> \| AsyncIterable<ChatEvent>` | | Modo autogerenciado: recebe o histórico com a nova mensagem e devolve a resposta inteira ou um stream de eventos. Ignorado no modo controlado. |
+| `messages` | `ChatTranscriptItem[]` | | Modo controlado: o transcript vem do aplicativo. Com ele, `onSend`, `busy` e `activity` passam a valer. |
 | `onSend` | `(text: string) => void \| boolean \| Promise<void \| boolean>` | | Modo controlado: recebe o texto enviado; retornar `false` devolve o texto ao composer. |
-| `busy` | `boolean` | | Modo controlado: trava o composer enquanto o turno corre. |
-| `activity` | `string \| null` | `undefined` | Indicador vivo: `null` mostra “Pensando…”, string mostra o rótulo, `''` centraliza somente os pontos; `undefined` esconde. |
-| `notice` | `ReactNode` | | Aviso do app acima do composer (credencial, agente desatualizado…). |
-| `composerActions` | `ReactNode` | | Seletores discretos na barra do composer (agente, app, escopo). |
+| `busy` | `boolean` | `false` | Modo controlado: bloqueia o envio enquanto o turno corre; a digitação continua liberada. |
+| `activity` | `string \| null` | `undefined` | Modo controlado: indicador de atividade. `undefined` esconde, `null` mostra “Pensando…”, uma string mostra o rótulo e `''` mostra somente os pontos. |
+| `notice` | `ReactNode` | | Aviso do aplicativo acima do composer, como credencial expirada ou agente desatualizado. |
+| `composerActions` | `ReactNode` | | Seletores discretos na barra do composer, como agente, aplicativo ou escopo. |
 | `composerClassName` | `string` | | Ajusta o contêiner externo do composer sem alcançar o DOM interno. |
 | `greeting` | `string` | | Texto do estado vazio; some quando a conversa começa. |
-| `empty` | `ReactNode` | | Estado vazio composto pelo app; vence `greeting` quando os dois existem. |
+| `empty` | `ReactNode` | | Estado vazio composto pelo aplicativo; vence `greeting` quando os dois existem. |
 | `initialMessages` | `ChatMessage[]` | | Histórico inicial do modo autogerenciado; troque a `key` ao trocar de conversa. |
 | `kickoff` | `() => Promise<string> \| AsyncIterable<ChatEvent>` | | Conversa que começa pelo assistente, uma vez, quando o transcript nasce vazio. |
-| `renderArtifact` | `(artifact: ChatArtifact) => ReactNode` | link com o título | Render do evento `artifact`. |
-| `renderMessageActions` | `(message: ChatTranscriptMessage) => ReactNode` | | Ações contextuais da mensagem; ficam visíveis em hover ou foco. |
-| `humanizeTool` | `(name: string, detail?: string) => string` | pt-BR embutido | Rótulo humano do tool em uso no indicador vivo. |
+| `renderArtifact` | `(artifact: ChatArtifact) => ReactNode` | link com o título | Apresentação do evento `artifact`. |
+| `renderMessageActions` | `(message: ChatTranscriptMessage) => ReactNode` | | Ações contextuais de mensagens enviadas e recebidas; ficam visíveis em hover ou foco. |
+| `humanizeTool` | `(name: string, detail?: string) => string` | rótulos em pt-BR | Rótulo do indicador para o evento `tool` no modo autogerenciado. |
 | `placeholder` | `string` | `'Escreva uma mensagem…'` | Placeholder do composer. |
+| `className` | `string` | | Classes da raiz, que ocupa a altura do contêiner (`h-full`). |
+
+## Tipos do transcript
+
+| Tipo | Forma | Uso |
+|---|---|---|
+| `ChatMessage` | `{ id?, createdAt?, role: 'user' \| 'assistant', content }` | Histórico enviado a `send` e aceito por `initialMessages`. `createdAt` é um instante ISO-8601. |
+| `ChatTranscriptItem` | `ChatMessage` com `role` também `'error'`, ou `{ id?, createdAt?, role: 'artifact', artifact: ChatArtifact }` | Itens de `messages` no modo controlado. Mensagens `error` aparecem destacadas no transcript. |
+| `ChatTranscriptMessage` | Os itens de `ChatTranscriptItem` que têm `content` | Argumento de `renderMessageActions`. |
+| `ChatArtifact` | `{ kind, ref, title? }` | Algo produzido na conversa, como um link ou um relatório; `ref` é o endereço ou identificador. |

package/src/ui/docs/content/checkbox.md

@@ -1,6 +1,11 @@
 ## Escolha booleana
 
-Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defaultChecked para o modo não controlado.
+Use `Checkbox` quando a pessoa precisar marcar uma opção que só vale ao salvar um formulário, como
+aceitar uma condição ou incluir uma etapa. Para uma preferência que entra em vigor no clique, use
+[`Switch`](/ui/switch).
+
+Associe cada caixa a um [`Label`](/ui/label) pelo par `htmlFor` e `id`: clicar no texto também
+alterna a caixa. `defaultChecked` define o estado inicial no modo não controlado.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -11,7 +16,8 @@ Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defa
 
 ## Controlado
 
-onCheckedChange recebe boolean | 'indeterminate' — compare com true para guardar um boolean.
+Use `checked` e `onCheckedChange` quando o estado pertencer ao consumidor. O callback recebe
+`boolean` ou `'indeterminate'`; compare com `true` para guardar um booleano.
 
 ```tsx preview
 const [autoReview, setAutoReview] = useState(true)
@@ -30,7 +36,8 @@ render(
 
 ## Lista de opções
 
-Várias caixas, um estado: o conjunto marcado é a lista de valores — o padrão para anexar skills a um agente.
+Quando várias caixas alimentam um único valor, guarde a lista dos itens marcados. É o caso de
+escolher as habilidades de um agente.
 
 ```tsx preview col-start
 const [skills, setSkills] = useState(['clean-code', 'test'])
@@ -50,9 +57,53 @@ render(
 )
 ```
 
+## Seleção parcial
+
+Quando uma caixa controla um grupo, como “Selecionar todas”, ela precisa mostrar também o caso em
+que só parte do grupo está marcada. Passe `checked="indeterminate"` nesse caso: a caixa fica
+preenchida e mostra um traço no lugar do visto, e leitores de tela a anunciam como parcialmente
+marcada. Ao clicar em uma caixa indeterminada, `onCheckedChange` recebe `true`.
+
+```tsx preview col-start
+const all = ['clean-code', 'code-style', 'ddd', 'test']
+const [skills, setSkills] = useState(['clean-code', 'test'])
+const allState = skills.length === all.length ? true : skills.length > 0 ? 'indeterminate' : false
+const toggleSkill = (skill: string): void => {
+  setSkills((prev) => (prev.includes(skill) ? prev.filter((s) => s !== skill) : [...prev, skill]))
+}
+
+render(
+  <>
+    <div className="flex items-center gap-2">
+      <Checkbox
+        id="skills-all"
+        checked={allState}
+        onCheckedChange={(v) => setSkills(v === true ? all : [])}
+      />
+      <Label htmlFor="skills-all">Selecionar todas</Label>
+    </div>
+    <div className="flex flex-col gap-2 pl-6">
+      {all.map((skill) => (
+        <div key={skill} className="flex items-center gap-2">
+          <Checkbox
+            id={`partial-${skill}`}
+            checked={skills.includes(skill)}
+            onCheckedChange={() => toggleSkill(skill)}
+          />
+          <Label htmlFor={`partial-${skill}`}>{skill}</Label>
+        </div>
+      ))}
+    </div>
+  </>,
+)
+```
+
+Com o grupo inteiro marcado, o clique em “Selecionar todas” recebe `false` e limpa a lista.
+
 ## Desabilitado
 
-disabled esmaece a caixa e o rótulo em par (peer-disabled no Label) — marcado ou não.
+`disabled` esmaece e bloqueia a caixa, marcada ou não. O `Label` escrito logo depois da caixa, no
+mesmo contêiner, esmaece junto.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -65,11 +116,26 @@ disabled esmaece a caixa e o rótulo em par (peer-disabled no Label) — marcado
 </div>
 ```
 
+## Estado inválido
+
+Quando a marcação for obrigatória e estiver ausente, declare `aria-invalid` na caixa e explique o
+que falta com `FieldError`. `data-invalid="true"` no [`Field`](/ui/field) leva o contexto de erro
+também ao rótulo.
+
+```tsx preview col-start
+<Field orientation="horizontal" data-invalid="true">
+  <Checkbox id="accept-terms" aria-invalid aria-describedby="accept-terms-error" />
+  <FieldLabel htmlFor="accept-terms">Li e aceito os termos de uso</FieldLabel>
+</Field>
+<FieldError id="accept-terms-error">Aceite os termos para continuar.</FieldError>
+```
+
 ## Propriedades de Checkbox
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `checked` | `boolean \| 'indeterminate'` | | O estado, no modo controlado — parear com onCheckedChange. |
-| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Para guardar um boolean, compare com true. |
+| `checked` | `boolean \| 'indeterminate'` | | Estado no modo controlado. Use com `onCheckedChange`. |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Para guardar um booleano, compare com `true`. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |
+| `disabled` | `boolean` | `false` | Esmaece e bloqueia a caixa; o `Label` irmão posterior esmaece junto. |
+| `aria-invalid` | `boolean` | | Aplica a borda e o anel de erro. |

package/src/ui/docs/content/cli.md

@@ -4,14 +4,14 @@ title: CLI opus
 
 # CLI opus
 
-O Opus traz um CLI que cobre o ciclo: faz o bootstrap, gera artefatos a partir das declarações,
-valida as convenções e expõe o estado vivo para os agentes via MCP. `opus --help` lista os
-comandos e `opus <comando> --help` detalha cada um.
+O CLI `opus` acompanha o projeto do início à entrega: cria o app, gera artefatos a partir das
+declarações, valida as convenções e oferece a estrutura do projeto a agentes por MCP. `opus --help`
+lista os comandos e `opus <comando> --help` detalha cada um.
 
 ## Gates
 
-> Use os gates no CI e antes de entregar uma mudança. Cada um informa o que precisa de ajuste e
-> encerra com sucesso (exit 0) quando não encontra violação.
+Use os gates no CI e antes de entregar uma mudança. Cada um informa o que precisa de ajuste e
+encerra com sucesso (exit 0) quando não encontra violação.
 
 ```bash
 opus check src        # convenções das actions e da UI (exit ≠ 0 se violar)
@@ -20,33 +20,37 @@ opus db check         # drift entidade ↔ banco (read-only)
 opus seed check       # bindings, dependências, ciclos e scripts paralelos de seed
 ```
 
-`opus check` lê o source sem executar nada e aplica regras em três grupos: actions
-(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`), UI
-(`ui-structure`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e Produtos de Dados
-(`data-product-export`, `-id`, `-duplicate`, `-version`, `-interfaces`, `-interface`, `-entities`
-e `-entity`, todas com o prefixo `data-product`). Um projeto
-marcado com `opus.json` e ainda sem actions passa vacuamente; sem o marcador, zero actions
-falha, porque um gate vazio não é aprovação. `opus check --help` descreve cada regra.
+`opus check` lê o código-fonte sem executá-lo e aplica regras em três grupos: actions
+(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind`), UI
+(`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e
+[Produtos de Dados](/docs/data-products) (`data-product-export`, `-id`, `-duplicate`, `-version`,
+`-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`). Um projeto
+marcado com `opus.json` e ainda sem actions passa sem achados; sem o marcador, nenhuma action
+encontrada é falha, porque um gate que não verificou nada não é aprovação. `opus check --help` descreve cada regra.
 
 ### Hook de pré-push
 
-O hook Git que `opus setup` instala roda, antes de cada push: `opus copy --check`; depois
-`opus pre-push materialization` na raiz, para confirmar que os artefatos Opus materializados
-(skills, hooks, instruções) correspondem à versão adotada; e `opus check` em cada app com
-`opus.json`. Qualquer um com exit ≠ 0 bloqueia o push. Os mesmos comandos podem ser executados à
-mão para antecipar o resultado:
+O hook Git que `opus setup` instala executa, antes de cada push:
+
+1. `opus copy --check`;
+2. `opus pre-push materialization` na raiz, que confirma se os artefatos Opus materializados
+   (skills, hooks e instruções) correspondem à versão adotada;
+3. `opus check` em cada app com `opus.json`.
+
+Qualquer comando com exit ≠ 0 bloqueia o push. Para antecipar o resultado, execute os mesmos
+comandos manualmente:
 
 ```bash
 opus pre-push                  # o mesmo opus check no diretório atual
 opus pre-push apps/portal      # o check de um app específico
-opus pre-push materialization  # só a freshness dos artefatos materializados
+opus pre-push materialization  # só confere se os artefatos materializados estão atualizados
 ```
 
 ## Seeds de desenvolvimento e teste
 
-> Seeds registrados no `opus.config.ts` têm perfis, métricas e escopos explícitos. Listagem e gate
-> não abrem o banco; planejamento, aplicação e verificação só conectam com
-> `NODE_ENV=development` ou `NODE_ENV=test`.
+Seeds registrados no `opus.config.ts` têm perfis, métricas e escopos explícitos. Listagem e gate
+não abrem o banco; planejamento, aplicação e verificação só conectam com `NODE_ENV=development` ou
+`NODE_ENV=test`.
 
 ```bash
 opus seed list
@@ -58,7 +62,7 @@ NODE_ENV=development opus seed verify customers.scenarios --profile smoke --scop
 Com qualquer outro valor de `NODE_ENV`, inclusive ausente, esses três comandos falham antes de
 abrir a conexão. O escopo informado também precisa constar em `safety.scopes` do seed.
 
-`--profile` escolhe o perfil (default: o `defaultProfile` do seed) e `--scope` declara o escopo
+`--profile` escolhe o perfil (padrão: o `defaultProfile` do seed) e `--scope` declara o escopo
 dos dados (a variável `OPUS_SEED_SCOPE` é a alternativa). `--json` devolve o resultado
 estruturado, inclusive em caso de erro. `apply` converge quando repetido; não há reset ou
 truncate no contrato. A skill `$create-opus-seed` estrutura um novo dataset, e
@@ -66,33 +70,47 @@ truncate no contrato. A skill `$create-opus-seed` estrutura um novo dataset, e
 
 ## Geração e introspecção
 
-> As declarações (`description` de entidades/actions) são a fonte; o `gen` as projeta. O manifest
-> é um lockfile versionado. A diferença do manifest torna a revisão objetiva.
+As declarações, incluindo a `description` de entidades e actions, são a fonte; `opus gen` as
+projeta. O manifest é versionado como um lockfile, e sua diferença mostra na revisão o que mudou
+no contrato.
 
 ```bash
 opus gen                                    # manifest / openapi / docs / stubs a partir do opus.config.ts
 opus gen --config ./apps/api/opus.config.ts # config fora do diretório atual
-opus gen --output ./custom/gen              # pasta de saída (default: a do config, ou ./.gen)
+opus gen --output ./custom/gen              # pasta de saída (padrão: a do config, ou ./.gen)
 opus copy                                   # inventário semântico de copy dos contratos
-opus introspect                             # modelo da estrutura (actions/reactions/schedules + wiring)
+opus introspect                             # modelo da estrutura: actions, reactions, schedules e ligações
 opus introspect --json
 ```
 
 `opus copy` projeta os textos de `defineAction`/`defineContract` no inventário que a política de
-copy da `@softize/base` valida. O caminho vem de `base.json` (`copy.inventory`; default
+copy da `@softize/base` valida. O caminho vem de `base.json` (`copy.inventory`; padrão
 `.base/copy-inventory.json` na raiz Git), a escrita é atômica e o arquivo gerado deve ser
 versionado. `--check` compara sem escrever e falha quando o inventário está ausente,
 desatualizado ou contém copy dinâmica não declarada.
 
+`opus introspect` lê o código sem executá-lo e só reconhece `defineAction`, `defineReaction`,
+`defineSchedule` e `defineDataProduct`. Actions do par `defineContract` e `bindAction`, reactions do
+par `defineReactionContract` e `bindReaction` e schedules declarados sem `defineSchedule` ficam fora
+do modelo. Para conferir as actions do split, use `opus check`.
+
 `--config` vale para `gen`, `db` e `seed` e sempre aponta para um caminho dentro do projeto. O
-`gen` aceita `--force` por compatibilidade, mas a flag não altera nada: a saída mora em um
+`gen` aceita `--force` por compatibilidade, mas a flag não altera nada: a saída fica em um
 diretório dedicado e é sempre sobrescrita.
 
+### Variáveis de ambiente
+
+`gen`, `db` e `seed` carregam o `.env` que está ao lado do `opus.config.ts` antes de importar o
+config. Assim, a conexão aberta pelo config usa as mesmas variáveis do projeto. Uma variável já
+definida no ambiente vence o arquivo: `DATABASE_URL=… opus db migrate` usa a URL informada no
+comando. A ausência do `.env` não é erro, porque containers e CI costumam injetar as variáveis
+diretamente.
+
 ## Banco
 
-> Os comandos `db` carregam o `opus.config.ts` e abrem conexão; por isso rodam num runner isolado
-> via `tsx`. O padrão é um schema idempotente: um script SQL evolutivo re-rodável, não migrations
-> versionadas.
+Os comandos `db` carregam o `opus.config.ts` e abrem conexão; por isso rodam num processo separado,
+com `tsx`. O padrão é um schema idempotente: um único script SQL que pode ser executado de novo a
+cada mudança, em vez de migrations numeradas.
 
 ```bash
 opus db check      # compara o schema do banco com as entidades (read-only)
@@ -100,36 +118,57 @@ opus db migrate    # aplica o schema idempotente e roda o drift-check na sequên
 opus db scaffold   # rascunho kysely a partir do diff, como referência para escrever o SQL
 ```
 
-`db scaffold` gera um rascunho para revisão à mão; a verdade continua sendo o script. `db migrate
-down` está aposentado e encerra com erro: sem histórico de migrations não há o que reverter —
-rollback é editar o schema e rodar `opus db migrate` de novo. O `opus.config.ts` precisa expor a
-factory lazy `database`, as entidades (ou domínios) e, opcionalmente, `schema` e `migrations`;
-`opus db --help` detalha.
+`db scaffold` gera um rascunho para revisão manual; a fonte continua sendo o script. `db migrate
+down` foi descontinuado e encerra com erro: sem histórico de migrations, não há o que reverter.
+Para desfazer uma mudança, edite o schema e rode `opus db migrate` de novo.
+
+O `opus.config.ts` precisa expor a factory `database`, chamada só quando um comando precisa do
+banco, as entidades ou os domínios e, opcionalmente, `schema` e `migrations`; `opus db --help`
+detalha cada campo.
 
 ## Bootstrap
 
-> `create` scaffolda um app novo com os pré-requisitos plugados; `setup` é per-app
-> (idempotente, nunca sobrescreve o seu).
+`create` gera um app novo com os pré-requisitos configurados. `setup` roda em cada app, pode ser
+repetido e não sobrescreve arquivos do projeto.
 
 ```bash
-opus create meu-app                 # app canônico do zero: protocolo + UI + preview + automação
-opus create meu-cliente --monorepo  # a RAIZ de um workspace (apps/* + packages/*)
+opus create meu-app                 # app novo: protocolo, UI, preview e automação
+opus create meu-cliente --monorepo  # a raiz de um workspace (apps/* + packages/*)
 opus create apps/portal             # dentro de um workspace: só o app (modo detectado)
 opus setup                          # grava opus.json e materializa a camada específica do SDK
 ```
 
-O esqueleto do `create` versiona com o Opus (sai do mesmo pacote que o SDK que ele
-configura) e nasce com os gates verdes: domínio-exemplo canônico, teste, manifest e o dev
-server pronto para o preview do Maestro. O método geral, a memória e a revisão vêm da Base
-depois de `pnpm run setup`. Dois modos, por detecção:
-repo standalone (template inteiro) ou **app em monorepo** (dentro de um workspace pnpm:
-só os arquivos do app; o que a raiz precisa ter vira aviso, sem clobber).
-
-## MCP — estado vivo para os agentes
-
-> O server MCP expõe introspecção, check e scaffold de action. É como um agente lê a estrutura e cria
-> action no formato canônico sem decorar convenção.
-
-`opus mcp` sobe o server (configurado em `.mcp.json`): o agente consulta a estrutura, roda o
-check e gera o esqueleto de uma action nova pela skill `$create-opus-action` — a mesma régua do
-`opus check`, por construção.
+O esqueleto do `create` vem do mesmo pacote que o SDK e acompanha sua versão. O app nasce com os
+gates aprovados: domínio de exemplo, teste, manifest e dev server que respeita a variável `PORT`,
+para que um orquestrador de preview escolha a porta. O método geral, a memória e a revisão vêm da
+Base depois de `pnpm run setup`.
+
+O `create` detecta o modo. Fora de um workspace pnpm, gera o repositório inteiro. Dentro de um
+workspace, gera só os arquivos do app e lista como aviso o que a raiz precisa ter, sem alterar os
+arquivos dela.
+
+## MCP para agentes de desenvolvimento
+
+`opus mcp` inicia, por stdio, um servidor MCP para o agente que trabalha no código do projeto. Com
+ele, o agente consulta a estrutura, valida convenções, gera actions no formato esperado e
+consulta o catálogo de componentes. Esse servidor não executa actions do app; para expor actions a
+agentes em produção, use o [servidor MCP do runtime](/docs/mcp).
+
+| Tool | O que faz |
+| --- | --- |
+| `opus_introspect` | Devolve o modelo de `opus introspect`, com os mesmos limites descritos acima. |
+| `opus_check` | Executa as regras de `opus check` e devolve os achados. |
+| `opus_create_action` | Devolve, sem gravar, o contrato e o binding iniciais de uma action a partir de recurso, verbo e kind. A skill `$create-opus-action` usa o mesmo gerador. |
+| `opus_list_components` | Lista os componentes da UI, quando usar cada um e o que importar. |
+| `opus_get_component` | Detalha um componente pelo nome. |
+
+O setup não cria a configuração do cliente MCP. Em clientes que leem `.mcp.json` na raiz do
+projeto, registre o servidor assim:
+
+```json
+{
+  "mcpServers": {
+    "opus": { "command": "pnpm", "args": ["exec", "opus", "mcp"] }
+  }
+}
+```