@softize/opus 19.0.0 → 20.1.0

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

@@ -5,18 +5,19 @@ title: Actions & contratos
 # Actions & contratos
 
 Uma action descreve uma operação que cliente e servidor precisam compreender da mesma forma.
-Seu contrato reúne entidade, entrada, saída e metadados no package compartilhado. A API conecta
-o handler e a web usa a mesma definição para executar ou renderizar a operação.
+Seu contrato reúne entrada, saída, documentação e regras de acesso num módulo compartilhado. O
+servidor liga o handler a esse contrato, e a interface usa a mesma definição para executar ou
+renderizar a operação.
 
 ## Contrato primeiro
 
-> `defineContract` no `shared/` — entidades, schemas (zod + `t.*` para tipos lógicos) e os
-> metadados da action. `api` e `web` importam; nada se duplica.
+O contrato fica no código que roda nos dois lados. Ele declara identidade, schemas (zod e os tipos
+lógicos `t.*`) e metadados, sem depender de banco, segredo ou driver de servidor. `api` e `web`
+importam o mesmo objeto.
 
 ```ts
-// shared/ — roda nos dois lados.
-import { defineContract } from '@softize/opus'
-import { t } from '@softize/opus/schema/zod'
+// shared/ — roda no cliente e no servidor.
+import { defineContract } from '@softize/opus/core'
 import { z } from 'zod'
 
 export const workspaceListContract = defineContract({
@@ -25,21 +26,24 @@ export const workspaceListContract = defineContract({
   summary: 'Lista os workspaces do back-office',
   description: 'O workspace é a entidade raiz que agrupa repositórios, apps e agentes…',
   input: z.object({ q: z.string().optional() }),
-  output: workspaceRowSchema,
+  output: workspaceRowSchema, // em `list`, o schema de cada item
   paginate: 'cursor',
 })
 ```
 
-## A action
+O nome segue `<recurso>.<verbo>` e o `kind` é `simple`, `form`, `list` ou `view`. Cada action fica
+em um arquivo próprio, em `src/domains/<recurso>/actions/`.
 
-> `name = <resource>.<verb>`; `kind ∈ simple | form | list | view`; uma por arquivo em
-> `src/domains/<resource>/actions/`, registrada no runtime. Não registrada = não existe.
+## Ligar o handler no servidor
+
+`bindAction` junta ao contrato a parte que só existe no servidor e produz a action executável. O
+contrato continua importável pela web sem arrastar o acesso ao banco.
 
 ```ts
-// api/ — server-only. bindAction amarra o handler no contrato compartilhado.
+// api/ — somente no servidor.
 import { randomUUID } from 'node:crypto'
 import { bindAction } from '@softize/opus/core'
-import { workspaceCreateContract } from '@app/shared' // contrato `form`, declarado no shared/ como o acima
+import { workspaceCreateContract } from '@app/shared' // contrato `form`, declarado como o acima
 
 export const workspaceCreate = bindAction(workspaceCreateContract, {
   handler: async (ctx, input) => {
@@ -50,42 +54,120 @@ export const workspaceCreate = bindAction(workspaceCreateContract, {
 })
 ```
 
+O binding aceita `handler`, `loads`, `authorize`, `background`, `emits` e `idempotency`. Exceto
+`authorize`, esses campos não existem no contrato: `defineContract` recusa qualquer um deles pelo
+tipo. O `authorize` pode aparecer nos dois lados; o declarado no binding substitui o do contrato. O handler recebe a entrada já validada pelo schema, com os
+valores padrão aplicados.
+
+[`background`](/docs/queue) e [`emits`](/docs/events) só têm efeito em actions `simple` e `form`.
+O tipo do binding os aceita em `list` e `view`, mas ali o runtime os ignora: a action executa na
+própria requisição e a lista de eventos não entra no manifest. Fora de produção, o runtime avisa ao
+registrar a action (`runtime.action_field_ignored`), e o [`opus check`](/docs/cli) aponta a regra
+`ignored-by-kind`.
+
+## Carregar dados antes de autorizar
+
+Quando a permissão depende do registro, como “só quem criou a tarefa pode editá-la”, declare em
+`loads` o que precisa ser buscado. O runtime carrega esses dados antes do `authorize` e os entrega
+também ao handler.
+
+```ts
+export const taskUpdate = bindAction(taskUpdateContract, {
+  loads: { task: 'task(:id)' },            // busca a tarefa pelo `id` do input
+  authorize: 'task.ownerId == user.id',   // expressão avaliada com user, input e o que foi carregado
+  handler: async (ctx, input, loaded) => {
+    // `loaded.task` já passou pela autorização.
+  },
+})
+
+// Na montagem do runtime: como resolver cada entidade citada em `loads`.
+runtime.registerLoaders({
+  task: (args, ctx) => findTask(ctx.db, String(args.id)),
+})
+```
+
+Uma entidade sem resolver registrado falha com `runtime.loader_not_registered`. Quando o resolver
+devolve `null` ou `undefined`, a action responde `<action>.<chave>.not_found`. `loads` também aceita
+uma função `(ctx, input) => Promise<unknown>` no lugar da expressão. A ordem completa das
+verificações está em [Autenticação](/docs/auth).
+
+## Registrar em um domínio
+
+Uma action só existe para o runtime depois de registrada. `defineDomain` agrupa as actions,
+reactions, schedules, entidades e [Produtos de Dados](/docs/data-products) de um mesmo recorte
+funcional:
+
+```ts
+// src/domains/workspace/index.ts
+import { defineDomain } from '@softize/opus/core'
+import { workspaceCreate } from './actions/create.ts'
+import { workspaceList } from './actions/list.ts'
+
+export const workspaceDomain = defineDomain({
+  name: 'workspace',
+  description: 'Workspaces do back-office e o que eles agrupam.',
+  actions: { workspaceCreate, workspaceList },
+})
+```
+
+Registre o domínio no runtime com `runtime.register([workspaceDomain])` e liste-o em `domains` no
+`opus.config.ts`, que é de onde `opus gen` projeta o manifest.
+
+`defineDomain` valida a declaração no momento em que roda: o `name` segue `[a-z][a-zA-Z0-9_]*`,
+duas actions do domínio (subdomínios incluídos) não podem ter o mesmo nome e cada Produto de Dados
+precisa citar actions e entidades existentes. Ao registrar, o runtime avisa no console quando o
+nome de uma action não começa pelo caminho do domínio, como `workspace.` ou `workspace.member.`.
+`subdomains` aceita outros domínios e forma esse caminho.
+
+`actions` aceita um mapa, uma lista ou o resultado de `import * as actions`. Um domínio também pode
+registrar só o contrato, sem handler: no modo design, descrito abaixo, o `mockHandler` responde;
+fora dele, a execução falha por falta de handler.
+
 ## Ordem canônica dos campos
 
-> Esta ordem mantém contratos previsíveis para leitura e geração. O `opus check` informa os
-> campos que precisam ser reposicionados, e a skill `create-opus-action` já cria o contrato e o
-> binding nessa estrutura.
+Manter os campos na mesma ordem torna contratos previsíveis para leitura e geração. O `opus check`
+aponta o primeiro campo fora de ordem, e a skill `$create-opus-action` já cria contrato e binding
+nessa estrutura. Os grupos seguem esta sequência; dentro de cada grupo, a ordem é livre:
 
 ```text
-name → kind → (label / summary / messages / tags…)
-  → input → output
-  → (authorize)
-  → fields / paginate
-  → handler
-  → invalidates
+name, kind
+  → label, title, summary, description, icon, color, messages, tags, examples, errors
+  → input, output
+  → public, requires, authorize, loads
+  → handler, mockHandler
+  → audit, confirm, invalidates, rateLimit, idempotency
+  → ai, automatable, internal
 ```
 
-Fail-closed por padrão: `input`/`output` via `z.object` + `t.*` para os tipos lógicos; `authorize`
-declarado ou gate explícito do adapter.
+Campos específicos de um kind, como `fields`, `paginate`, `columns`, `filters`, `expand`,
+`background` e `emits`, ficam fora dessa verificação.
 
-Os átomos do catálogo servem também dentro dos schemas de input/output — não re-escreva
-regex do que o Opus já valida: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`.
-O `.zod()` devolve o schema zod subjacente do tipo lógico (slug, email, phone, money…).
+Declare `input` e `output` com `z.object` e use os tipos lógicos do catálogo em vez de reescrever
+validações: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`. O `.zod()` devolve o
+schema zod de cada tipo lógico (slug, email, phone, money…), importado de `@softize/opus/schema/zod`.
 
-## Modo design — o mock mora no contrato
+A autorização é fechada por padrão: sem `public: true`, a action exige usuário autenticado; com
+`authorize`, exige também a permissão declarada.
 
-Um `mockHandler` no contrato deixa a UI rodar com dado realista **sem backend nem banco**: em
-`OPUS_MODE=design` o runtime roteia o `execute` para o `mockHandler` (cai no `handler` real se
-ausente). Como ele fica no contrato, e não no `bindAction`, é isomorfo — o design autora, o
-handoff pluga o handler, e o mock nem toca `ctx.db`.
+## Prototipar com dados simulados
 
-Alimente com `fake`/`fakeMany` (fixtures determinísticas do próprio schema — ver [Testes](testing)):
+Para desenhar a interface antes de o backend existir, declare um `mockHandler` no contrato. Com
+`OPUS_MODE=design`, o runtime executa o `mockHandler` no lugar do `handler`; sem ele, usa o
+`handler` real. Como o mock fica no contrato, a mesma declaração serve ao design e, depois, ao
+handler real, e o mock não precisa acessar `ctx.db`.
+
+`fake` e `fakeMany` geram dados determinísticos a partir do próprio schema (ver
+[Testes de action](/docs/testing)). Em `list`, o `mockHandler` devolve a página inteira, com
+`items`, `cursor` e `total`:
 
 ```ts
+import { bindAction, defineContract } from '@softize/opus/core'
 import { entityRowSchema } from '@softize/opus/schema'
 import { fake, fakeMany } from '@softize/opus/testing'
+import { z } from 'zod'
+import { EventEntity } from '../entity.ts'
 
-// `defineEntity` devolve o próprio config; o schema da linha vem de `entityRowSchema`.
+// `entityRowSchema` deriva da entidade o schema de uma linha.
 const eventRowSchema = entityRowSchema(EventEntity)
 
 export const eventGet = defineContract({
@@ -93,19 +175,30 @@ export const eventGet = defineContract({
   kind: 'view',
   input: z.object({ id: z.string().uuid() }),
   output: eventRowSchema,
-  mockHandler: () => fake(eventRowSchema), // 1 evento fake
+  mockHandler: () => fake(eventRowSchema),
 })
-// listas: `mockHandler: () => fakeMany(eventRowSchema, 20)`
 
-// o handoff, depois, só pluga o real — mesmo contrato:
-export const eventGetImpl = bindAction(eventGet, { handler: async (ctx, input) => { /* db */ } })
+export const eventList = defineContract({
+  name: 'event.list',
+  kind: 'list',
+  input: z.object({}),
+  output: eventRowSchema,
+  paginate: 'cursor',
+  mockHandler: async () => ({ items: fakeMany(eventRowSchema, 20), cursor: { next: null }, total: 20 }),
+})
+
+// Depois, o servidor liga o handler real ao mesmo contrato.
+export const eventGetImpl = bindAction(eventGet, {
+  handler: async (ctx, input) =>
+    ctx.db.selectFrom('events').selectAll().where('id', '=', input.id).executeTakeFirstOrThrow(),
+})
 ```
 
-O `mockHandler` roda no **servidor em modo design** (`OPUS_MODE=design`), não no cliente — e
-quem sobe esse servidor é o próprio dev server: o plugin `opusDesign()` (`@softize/opus/vite`)
-monta o runtime Opus DENTRO do vite e serve `/api` in-process, com os mocks respondendo e
-qualquer `server.proxy` para backend externo desligado (prefixo ex-proxy sem cobertura responde
-503 em envelope — nada vaza para prod). A SPA chama `/api` normal e recebe o dado fake, isolado:
+O `mockHandler` roda no servidor, não no navegador. O plugin `opusDesign()`, de
+`@softize/opus/vite`, monta o runtime do Opus dentro do dev server e responde `/api` no próprio
+processo. No modo design, qualquer `server.proxy` para um backend externo fica desligado: um prefixo
+que ia para o proxy e não tem action correspondente responde 503 em envelope, sem alcançar o
+backend. A aplicação chama `/api` como sempre e recebe os dados simulados.
 
 ```ts
 // vite.config.ts — o plugin só carrega no modo design, por import dinâmico.
@@ -121,31 +214,32 @@ async function designPlugin(): Promise<PluginOption> {
 const designPlugins: PluginOption[] = DESIGN_RUN ? [await designPlugin()] : []
 
 export default defineConfig({ plugins: [react(), ...designPlugins] })
-// sobe com: vite --mode design --configLoader runner (script dev:design do template)
+// Execute com: vite --mode design --configLoader runner (script dev:design do template)
 ```
 
-O import fica dinâmico e condicionado porque o Opus publica TypeScript: o carregador padrão de
-config do Vite externaliza um import estático, e o Node 22+ recusa type stripping dentro de
-`node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Com `--configLoader runner`, o Vite
-transforma o TypeScript antes de avaliar o plugin. O app criado por `opus create` já traz esse arranjo.
+O import é dinâmico e condicionado porque o Opus publica TypeScript: o carregador padrão de config
+do Vite externaliza um import estático, e o Node 22+ recusa type stripping dentro de `node_modules`
+(`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Com `--configLoader runner`, o Vite transforma o
+TypeScript antes de avaliar o plugin. O app criado por `opus create` já traz esse arranjo.
+
+O runtime de design atende somente requisições: reactions e schedules dos módulos carregados não
+são registrados.
 
-O `entry` (default `./opus.config.ts`) também aceita **glob** — `opusDesign({ entry:
-'src/domains/*/contract.ts' })` — re-expandido a cada rebuild: **domínio novo entra no ar ao
-salvar o arquivo**, sem editar entry nem reiniciar o dev server (criar o arquivo já invalida o
-runtime; o rebuild é lazy, na request seguinte). E o 404 de action desconhecida **se cura
-sozinho**: antes de responder, o plugin força um rebuild (um por ciclo de mudança) e re-tenta —
-persistindo, o envelope traz a mensagem-guia apontando o entry.
+O `entry` do plugin (padrão `./opus.config.ts`) também aceita glob, como
+`opusDesign({ entry: 'src/domains/*/contract.ts' })`. O glob é expandido de novo a cada
+reconstrução: um domínio novo passa a responder assim que o arquivo é salvo, sem editar o `entry`
+nem reiniciar o dev server. Quando uma action não é encontrada, o plugin reconstrói o runtime uma
+vez por ciclo de mudança e tenta de novo; se a action continuar ausente, a resposta indica o
+`entry` a conferir.
 
-Como o contrato é isomorfo, o `mockHandler` também acompanha o **bundle web** — peso morto lá
-(a SPA nunca o chama; o dado é fake). Tirá-lo do bundle de prod é um transform de build
-(deferido); **não** dá para gatear no call-site com `import.meta.env` sem quebrar o servidor
-(não existe em Node). É a materialização Opus-nativa do "mock = contrato": o design não é
-descartável — vira o contrato que o backend honra.
+Como o contrato vai para os dois lados, o `mockHandler` também entra no bundle da web, onde nunca é
+chamado. Não o condicione com `import.meta.env` no contrato: essa variável não existe no Node e
+quebraria o servidor.
 
-## O front consome o contrato
+## Consumir o contrato na interface
 
-> Nunca fetch ou tipos na mão. Os hooks e os patterns (ActionForm/ActionList…) renderizam a
-> action inteira a partir do contrato — o spec é a fonte, o pattern é o renderizador.
+A interface não precisa de fetch nem de tipos escritos à mão. Os hooks e os componentes de action,
+como `ActionForm` e `ActionList`, executam e renderizam a operação a partir do contrato:
 
 ```tsx
 import { ActionForm, useListAction } from '@softize/opus/ui/react'
@@ -153,10 +247,11 @@ import { ActionForm, useListAction } from '@softize/opus/ui/react'
 // Lista declarativa: busca ao montar e refaz quando uma action invalida `workspace.list`.
 const { items, total, isLoading } = useListAction<WorkspaceRow>(workspaceListContract, { q })
 
-// Form contract-driven: os campos (fields) moram NO contrato.
+// Formulário a partir do contrato: os campos vêm de `fields`, declarado no próprio contrato.
 <ActionForm action={workspaceCreateContract} onSuccess={…} />
 ```
 
-`useListAction` exige `OpusProvider` e um `QueryClientProvider` acima da árvore. Para buscar sob demanda, como num
-autocomplete, use `useLookupAction`: ele não busca ao montar, expõe `run(input)` e `reset()` e
-devolve `items`, `cursor`, `total` e os estados da última execução.
+Os hooks precisam de `OpusProvider` e `QueryClientProvider` acima da árvore; a montagem está em
+[Como consumir](/ui/como-consumir). Para buscar sob demanda, como num autocomplete, use
+`useLookupAction`: ele não busca ao montar, expõe `run(input)` e `reset()` e devolve `items`,
+`cursor`, `total` e os estados da última execução.

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

@@ -4,14 +4,12 @@ title: IA generativa
 
 # IA generativa
 
-> **Experimental.** Superfície mínima — cresce por reincidência de caso real, não por
-> especulação (memória longa de conversa entra quando um caso real cobrar).
+> **Experimental.** A superfície é mínima e cresce conforme casos reais a exijam.
 
-Três coisas: **completar** texto, **extrair** dado estruturado, e **rodar um agente** sobre
-as actions do app. O contrato é um adapter do core (`AiAdapter`). O diferencial do `extract`
-é que **o mesmo `Schema` das actions vira o contrato da resposta do modelo** — saída forçada
-e validada pelo schema. O do `run` é que **as actions viram as tools** — o modelo age no app,
-como o usuário, pelas mesmas actions que a UI usa.
+Use o adapter de IA para completar texto, extrair dados estruturados ou executar um agente sobre as
+actions do app. Em `extract`, o mesmo `Schema` usado nas actions define a resposta do modelo: a saída
+é forçada e validada por ele. Em `run`, as actions expostas viram as ferramentas do modelo, que age
+no app como o usuário, pelas mesmas actions usadas pela interface.
 
 ## O contrato
 
@@ -19,7 +17,7 @@ como o usuário, pelas mesmas actions que a UI usa.
 interface AiAdapter {
   complete(prompt: string, opts?: AiCompleteOptions): Promise<string>
   extract<T>(prompt: string, schema: Schema<T>, opts?: AiCompleteOptions): Promise<T>
-  // Loop agêntico: o modelo chama tools (as actions ai:enabled) até responder em texto.
+  // Loop agêntico: o modelo chama tools (as actions expostas à IA) até responder em texto.
   run?(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult>
   // O mesmo loop emitindo ChatEvent conforme acontece (ver Streaming, abaixo).
   runStream?(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent>
@@ -32,16 +30,15 @@ interface AiAdapter {
 ```ts
 import { anthropicAi } from '@softize/opus/ai/anthropic'
 
-// Default: haiku (rápido/barato) e ANTHROPIC_API_KEY do ambiente.
+// Padrão: modelo Haiku e ANTHROPIC_API_KEY do ambiente.
 const ai = anthropicAi()
 
 // Tudo injetável: client próprio, modelo default, teto de tokens.
 const custom = anthropicAi({ apiKey, model: 'claude-sonnet-5', maxTokens: 2048 })
 ```
 
-O peer é **opcional** (`@anthropic-ai/sdk`): quem não usa o driver não o instala —
-importado sob demanda. Em teste, injete um client fake (`{ messages: { create } }`)
-e nada toca a rede.
+`@anthropic-ai/sdk` é dependência opcional, carregada só quando o driver é usado. Em teste, injete um
+client falso (`{ messages: { create } }`) para que nada acesse a rede.
 
 ## No runtime
 
@@ -54,50 +51,52 @@ const runtime = createRuntime({
 // No handler: ctx.ai (null quando não configurado).
 handler: async (ctx, input) => {
   const meta = await ctx.ai!.extract(
-    `Classifique o chamado e proponha um título curto: ${input.texto}`,
-    z.object({ titulo: z.string(), prioridade: z.enum(['baixa', 'media', 'alta']) }),
+    `Classifique o chamado e proponha um título curto: ${input.text}`,
+    z.object({ title: z.string(), priority: z.enum(['low', 'medium', 'high']) }),
   )
-  return meta // já validado pelo schema — fora do contrato, o extract estoura.
+  return meta // já validado; uma resposta fora do schema faz o extract lançar erro
 }
 ```
 
-## Actions como tools (o agente)
+## Actions como ferramentas do agente
 
-Marque uma action com `ai: { enabled: true }` no contrato e ela vira uma **tool** que o
-modelo pode chamar. Aí `ctx.ai.run(prompt)` roda o loop agêntico sobre as actions `ai:enabled`:
-o modelo escolhe a tool → o runtime executa a action **como o usuário logado** (limitado pelo
-`ctx.can`) → o resultado volta para o modelo → repete até a resposta em texto.
+Exponha uma action à IA no contrato, com `ai: true` ou com um objeto `ai` que não declare
+`enabled: false`, para que o modelo possa chamá-la. Então `ctx.ai.run(prompt)` executa o ciclo do
+agente sobre as actions expostas: o modelo escolhe uma
+ferramenta, o runtime executa a action como o usuário autenticado, limitado por `ctx.can`, e o
+resultado volta ao modelo. O ciclo se repete até o modelo responder em texto.
 
 ```ts
 // A action opta por entrar; o schema do contrato também descreve a ferramenta:
-export const buscarNotas = defineContract({
-  name: 'nota.buscar',
+export const searchInvoices = defineContract({
+  name: 'invoice.search',
   kind: 'list',
   label: 'Buscar notas',
-  input: z.object({ cliente: z.string(), mes: z.string() }),
-  output: z.object({ numero: z.string(), valor: z.number() }), // em `list`, o schema de cada item
+  input: z.object({ customer: z.string(), month: z.string() }),
+  output: z.object({ number: z.string(), amount: z.number() }), // em `list`, o schema de cada item
   ai: { enabled: true, description: 'Busca notas por cliente e mês.' },
 })
 
 // No handler — ou fora dele, via runtime.aiFor(base), para o backend de um chat:
 const { text } = await ctx.ai!.run('Quais notas a Empresa X emitiu em junho?')
-// o modelo chamou nota.buscar sozinho, como o usuário logado, e respondeu em texto.
+// o modelo chamou invoice.search sozinho, como o usuário logado, e respondeu em texto.
 ```
 
 `runtime.aiTools()` projeta cada action exposta como um `AiTool`: `name` é o identificador técnico
 usado na execução e na auditoria; `title` traz a `label` legível da action, quando existe;
 `description` vem de `ai.description` (ou da `description` da action) e `inputSchema`, do input.
-`metadata.dataProducts` lista os Produtos de Dados relacionados e `metadata.dataProductLabels`
-associa cada identificador ao seu nome legível. Esses metadados servem ao host: não entram no
+`metadata.dataProducts` lista os [Produtos de Dados](/docs/data-products) relacionados e
+`metadata.dataProductLabels` associa cada identificador ao seu nome legível. Esses metadados servem ao host: não entram no
 prompt e não concedem acesso.
 
 O agente só executa nomes que `aiTools()` anunciou; uma chamada a outra action volta como erro
 para o modelo. Actions marcadas com `ai: { destructive: true }` ou `ai: { requiresConfirmation: true }`
-**não rodam sem aprovação**: passe `run(prompt, { confirm })` — o chat mostra o "confirmar?"; sem
-isso, a action é recusada e o modelo avisa. O gate lê somente esses dois campos de `ai`: o
+não rodam sem aprovação: passe `run(prompt, { confirm })` para que o chat peça a confirmação. Sem
+`confirm`, a action é recusada e o modelo informa a recusa. O gate lê somente esses dois campos de `ai`: o
 `confirm: { destructive: true }` da action configura a confirmação da UI e não protege a chamada
-feita pelo agente. Fora do handler, `runtime.aiFor(base)` devolve o `ai` já ligado a um contexto —
-o backend do chat resolve o usuário e chama `.run(historico)`.
+feita pelo agente. Fora do handler, `runtime.aiFor(base)` devolve o `ai` já ligado a um contexto:
+o backend do chat resolve o usuário e chama `.run(history)`. Para agentes fora da aplicação, veja
+[MCP](/docs/mcp).
 
 Para o modelo perguntar algo à pessoa no meio do turno, passe `onAsk` em `run` ou `runStream`. O
 driver Anthropic então oferece a tool reservada `ask_user`, entrega as perguntas (`AskQuestion[]`)
@@ -105,13 +104,13 @@ ao seu `onAsk` e devolve as respostas (`AskAnswer[]`) ao modelo. Sem `onAsk`, um
 `ask_user` é recusada com a orientação de perguntar em texto. Na interface, o componente
 [Ask](/ui/ask) apresenta essas perguntas e coleta as respostas.
 
-## Streaming — o protocolo de eventos de conversa
+## Streaming da conversa
 
-`runStream` é o mesmo loop agêntico do `run`, emitindo **`ChatEvent`** conforme acontece
-(o contrato: `docs/chat-event-protocol.md`): `text` (delta incremental), `tool` (a action
-em uso — dado cru; humanizar é da apresentação), `artifact` (algo produzido na conversa)
-e `done`. Aditivo: o `run` clássico permanece, e `Promise<string>` segue sendo o caso
-degenerado do protocolo (um `text` + um `done`).
+`runStream` executa o mesmo ciclo do `run` e emite `ChatEvent` à medida que ele avança. O protocolo
+está em `docs/chat-event-protocol.md`, dentro do pacote: `text` traz um trecho novo de texto,
+`tool` identifica a action em uso (sem tradução para a interface, que fica com quem apresenta),
+`artifact` entrega algo produzido na conversa e `done` encerra o turno. O `run` continua disponível;
+uma resposta completa equivale a um `text` seguido de `done`.
 
 ```ts
 // O backend de um chat streamando por SSE:
@@ -120,12 +119,12 @@ for await (const event of runtime.aiFor(base)!.runStream(messages)) {
 }
 ```
 
-O driver Anthropic emite os deltas token a token quando o client suporta `messages.stream`;
-com um client só-`create` (ex.: fake de teste), o texto de cada passo sai como delta único.
-O `<Chat>` do opus/ui consome os dois modos — ver a página **Chat**.
+O driver Anthropic emite o texto em trechos, à medida que chega, quando o client oferece
+`messages.stream`. Com um client que só tem `create`, como um client falso de teste, o texto de cada
+passo sai num único trecho. O componente [Chat](/ui/chat) consome os dois modos.
 
-## Limites (por enquanto)
+## Limites atuais
 
-O `run`/`runStream` fiam histórico multi-turn, mas sem memória longa/resumo automático.
-`extract` exige schema com objeto na raiz (`z.object`) — regra da API de tools do provider
-e o formato natural de um contrato.
+`run` e `runStream` aceitam o histórico da conversa, mas não mantêm memória longa nem resumem o
+histórico automaticamente. `extract` exige um schema com objeto na raiz (`z.object`), uma regra da
+API de ferramentas do provedor.