@softize/opus 19.0.0 → 20.0.0

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

@@ -1,10 +1,11 @@
-O calendário fala pt-BR por padrão: nomes de mês e de dia vêm do `locale` (`ptBR` de
-`date-fns/locale`) e os controles de navegação têm rótulos acessíveis em português. Passe outro
-`locale` para trocar o idioma; `labels` sobrescreve rótulos individualmente.
-
 ## Dia único
 
-mode=single guarda uma Date — controle por selected/onSelect. defaultMonth abre o calendário no mês certo sem mexer na seleção.
+Use `Calendar` quando a pessoa precisar escolher datas vendo o mês inteiro, como a data de uma
+entrega ou a janela de um relatório. Para abrir o calendário a partir de um campo, ancore-o em um
+[`Popover`](/ui/popover).
+
+Com `mode="single"`, a seleção é uma `Date`, controlada por `selected` e `onSelect`. `defaultMonth`
+abre o calendário no mês desejado sem alterar a seleção.
 
 ```tsx preview
 const [day, setDay] = useState<Date | undefined>(new Date(2026, 5, 22))
@@ -19,9 +20,14 @@ render(
 )
 ```
 
+O calendário usa pt-BR por padrão: os nomes de mês e de dia vêm do `locale` (`ptBR`, de
+`date-fns/locale`) e os controles de navegação têm nomes acessíveis em português. Passe outro
+`locale` para trocar o idioma; `labels` substitui nomes acessíveis individualmente.
+
 ## Intervalo
 
-mode=range guarda { from, to } — o padrão para filtrar sessões por janela de datas. O primeiro clique fixa o início; o segundo, o fim.
+Com `mode="range"`, a seleção é um intervalo `{ from, to }`, o formato comum para filtrar registros
+por período. O primeiro clique define o início e o segundo, o fim.
 
 ```tsx preview
 const [week, setWeek] = useState<DateRange | undefined>({
@@ -39,9 +45,73 @@ render(
 )
 ```
 
-## Navegação por dropdown
+Para um intervalo que atravessa meses, `numberOfMonths` mostra meses lado a lado.
+
+```tsx preview
+const [range, setRange] = useState<DateRange | undefined>({
+  from: new Date(2026, 5, 24),
+  to: new Date(2026, 6, 8),
+})
+
+render(
+  <Calendar
+    mode="range"
+    numberOfMonths={2}
+    selected={range}
+    onSelect={setRange}
+    defaultMonth={new Date(2026, 5, 1)}
+  />,
+)
+```
+
+## Vários dias
 
-captionLayout=dropdown troca o título do mês por seletores de mês e ano — bom para pular para um período distante (ex.: histórico de um repositório) sem clicar mês a mês.
+Com `mode="multiple"`, a seleção é uma lista de datas, e cada clique marca ou desmarca um dia. Use
+esse modo quando os dias escolhidos não formarem um intervalo contínuo, como os plantões de uma
+equipe.
+
+```tsx preview
+const [days, setDays] = useState<Date[] | undefined>([
+  new Date(2026, 5, 3),
+  new Date(2026, 5, 10),
+  new Date(2026, 5, 17),
+])
+
+render(
+  <Calendar
+    mode="multiple"
+    selected={days}
+    onSelect={setDays}
+    defaultMonth={new Date(2026, 5, 1)}
+  />,
+)
+```
+
+## Datas indisponíveis
+
+`disabled` impede a escolha de datas específicas. Ele aceita uma data, uma lista, um intervalo
+`{ from, to }`, um predicado ou combinações como `{ before: data }` e `{ dayOfWeek: [0, 6] }`. No
+exemplo, dias anteriores a 10 de junho e fins de semana ficam indisponíveis.
+
+```tsx preview
+const [day, setDay] = useState<Date | undefined>()
+
+render(
+  <Calendar
+    mode="single"
+    selected={day}
+    onSelect={setDay}
+    defaultMonth={new Date(2026, 5, 1)}
+    disabled={[{ before: new Date(2026, 5, 10) }, { dayOfWeek: [0, 6] }]}
+  />,
+)
+```
+
+## Navegação por seletores
+
+`captionLayout="dropdown"` troca o título do mês por seletores de mês e ano. Use essa forma quando a
+pessoa precisar chegar a um período distante, como o histórico de anos anteriores, sem avançar mês
+a mês.
 
 ```tsx preview
 <Calendar
@@ -51,25 +121,63 @@ captionLayout=dropdown troca o título do mês por seletores de mês e ano — b
 />
 ```
 
+## Personalizar o dia
+
+Cada dia é um `CalendarDayButton`: um `Button` `ghost` quadrado que recebe os modificadores do dia,
+como `selected`, `range_start` e `today`, e cuida do foco e dos estados de seleção. Para decorar o
+dia, como marcar datas com evento, substitua o componente por `components={{ DayButton: … }}` e
+renderize `CalendarDayButton` por dentro, em vez de reimplementar esse comportamento.
+
+```tsx preview
+const eventDays = [5, 12, 26]
+
+render(
+  <Calendar
+    mode="single"
+    defaultMonth={new Date(2026, 5, 1)}
+    components={{
+      DayButton: ({ children, ...props }) => (
+        <CalendarDayButton {...props}>
+          {children}
+          {eventDays.includes(props.day.date.getDate()) &&
+            props.day.date.getMonth() === 5 && (
+              <span aria-hidden="true" className="size-1 rounded-full bg-primary" />
+            )}
+        </CalendarDayButton>
+      ),
+    }}
+  />,
+)
+```
+
+O marcador do exemplo é decorativo. Quando a informação importar para a decisão, inclua-a também
+no nome acessível do dia por `labels.labelDayButton`.
+
 ## Propriedades de Calendar
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `mode` | `'single' \| 'multiple' \| 'range'` | | O tipo de seleção — define o formato de selected/onSelect (Date, Date[] ou { from, to }). |
-| `selected` | `Date \| Date[] \| DateRange` | | A seleção atual no modo controlado — o formato segue o mode. Pareie com onSelect. |
-| `onSelect` | `(selected) => void` | | Chamado quando o usuário escolhe uma data. O argumento segue o mode. |
-| `defaultMonth` | `Date` | | O mês exibido ao montar, sem afetar a seleção. |
-| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'` | Como o título do mês aparece — label é texto fixo; dropdown vira seletores de mês e ano. |
-| `numberOfMonths` | `number` | `1` | Quantos meses mostrar lado a lado — útil para escolher um intervalo longo. |
-| `disabled` | `Matcher` | | Datas não selecionáveis — uma Date, um array, um { from, to } ou um predicado (date) => boolean. |
-| `buttonVariant` | `Button['variant']` | `'ghost'` | A variante dos botões de navegação (anterior/próximo). |
-| `showOutsideDays` | `boolean` | `true` | Mostra os dias do mês vizinho que completam a primeira e a última semana. |
-| `locale` | `Locale` | `ptBR` | Idioma dos nomes de mês e de dia (um locale do date-fns). |
-| `labels` | `Partial<Labels>` | rótulos em pt-BR | Rótulos acessíveis da navegação e dos seletores; mescla sobre o padrão. |
-
-## Personalizar o dia com CalendarDayButton
-
-Cada dia é um `CalendarDayButton` — um `Button` ghost quadrado que recebe os modificadores do
-dia (`selected`, `range-start`, `today`…). Use `components={{ DayButton: … }}` para
-decorar o dia (um marcador de evento, por exemplo) partindo dele em vez de reimplementar o
-foco e a seleção.
+| `mode` | `'single' \| 'multiple' \| 'range'` | | Tipo de seleção. Define o formato de `selected` e `onSelect`: `Date`, `Date[]` ou `{ from, to }`. |
+| `selected` | `Date \| Date[] \| DateRange` | | Seleção atual no modo controlado, no formato do `mode`. Use com `onSelect`. |
+| `onSelect` | `(selected) => void` | | Chamado quando a pessoa escolhe uma data. O argumento segue o formato do `mode`. |
+| `defaultMonth` | `Date` | | Mês exibido ao montar, sem afetar a seleção. |
+| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'` | Apresentação do título do mês: texto fixo ou seletores de mês, de ano ou de ambos. |
+| `numberOfMonths` | `number` | `1` | Quantidade de meses exibidos lado a lado. |
+| `disabled` | `Matcher \| Matcher[]` | | Datas que não podem ser escolhidas: uma data, uma lista, um intervalo, um predicado ou regras como `{ before }` e `{ dayOfWeek }`. |
+| `buttonVariant` | `ButtonVariant` | `'ghost'` | Variante dos botões de mês anterior e próximo mês. |
+| `showOutsideDays` | `boolean` | `true` | Mostra os dias dos meses vizinhos que completam a primeira e a última semana. |
+| `locale` | `Locale` | `ptBR` | Idioma dos nomes de mês e de dia, como um locale do date-fns. |
+| `labels` | `Partial<Labels>` | nomes em pt-BR | Nomes acessíveis da navegação, dos seletores e dos dias; mesclados sobre o padrão. |
+| `components` | `Partial<CustomComponents>` | | Substitui partes da grade, como `DayButton`. |
+
+`Calendar` repassa as demais propriedades ao `DayPicker` do react-day-picker.
+
+## Propriedades de CalendarDayButton
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `day` | `CalendarDay` | | O dia renderizado; `day.date` é a data. Recebido do `Calendar`. |
+| `modifiers` | `Modifiers` | | Estados do dia, como `selected`, `today`, `disabled`, `range_start` e `range_end`. Recebido do `Calendar`. |
+| `className` | `string` | | Classes somadas ao botão do dia. |
+
+`CalendarDayButton` aceita também as props nativas de `<button>`, repassadas pelo `Calendar`.

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

@@ -6,7 +6,7 @@ usa. Nesse formato o recuo vem do `className`.
 
 ```tsx preview col
 <Card className="p-4">
-  <p className="text-sm text-muted-foreground">3 sessões ativas neste momento.</p>
+  <p className="text-sm text-muted-foreground">3 veículos aguardando retirada.</p>
 </Card>
 ```
 
@@ -23,15 +23,15 @@ slots são escritos não altera a posição.
 ```tsx preview col
 <Card>
   <CardHeader>
-    <CardTitle>Empresa X</CardTitle>
-    <CardDescription>2 repositórios · 3 agentes vinculados.</CardDescription>
+    <CardTitle>Oficina Centro</CardTitle>
+    <CardDescription>4 boxes · 2 consultores de plantão.</CardDescription>
   </CardHeader>
   <CardBody>
-    <p className="text-sm text-muted-foreground">Última sessão concluída há 2 horas.</p>
+    <p className="text-sm text-muted-foreground">Próximo horário livre hoje, às 14h.</p>
   </CardBody>
   <CardFooter>
-    <Button size="sm" variant="outline">Ver repositórios</Button>
-    <Button size="sm">Abrir sessão</Button>
+    <Button size="sm" variant="outline">Ver agenda</Button>
+    <Button size="sm">Agendar revisão</Button>
   </CardFooter>
 </Card>
 ```
@@ -59,7 +59,7 @@ com ações — ou quando ele precisar conviver com um [`Dialog`](/ui/dialog), u
 
 ```tsx preview col
 render(
-  <div className="grid gap-4 md:grid-cols-2">
+  <div className="grid grid-cols-2 gap-4">
     <Card>
       <CardHeader>
         <CardTitle>Contínuo</CardTitle>
@@ -94,12 +94,15 @@ Em `sectioned`, cada região desenha a própria linha quando existe uma região
 Um cabeçalho sozinho não fecha nada, um rodapé que é a única região também não, e um cabeçalho
 seguido direto de um rodapé produz uma linha só, em vez de duas encostadas.
 
-A tela não escreve mais `border-b` no cabeçalho nem `border-t` no rodapé. A regra depende da
-presença das regiões irmãs, que o componente conhece e a tela não.
+Por isso, não escreva `border-b` no cabeçalho nem `border-t` no rodapé: a regra depende da presença
+das regiões irmãs, que o componente conhece e a tela não. Uma borda escrita à mão ignora quais
+regiões estão presentes: `border-b` num cabeçalho sozinho desenha uma linha encostada na borda do
+card, e `border-t` no corpo duplica a linha que o cabeçalho já desenha. Da mesma forma,
+`border-b-0` não apaga a linha derivada. Para um card sem divisores, use `layout="continuous"`.
 
 ## Mídia e ações no cabeçalho
 
-`CardMedia` abre a linha com a moldura de ícone da casa — o mesmo [`IconTile`](/ui/icon-tile), na
+`CardMedia` abre a linha com a moldura de ícone do Opus — o mesmo [`IconTile`](/ui/icon-tile), na
 escala `sm`, com `context` e `variant` para declarar o significado da cor. `CardAction` fica no
 extremo oposto ao título, sem precisar de classe de alinhamento.
 
@@ -137,17 +140,35 @@ estrutura do documento não muda a aparência.
 </Card>
 ```
 
-Use `asChild` quando o heading precisar vir de outro componente, como um link.
+Quando o título leva a outra tela, coloque o link dentro dele. O heading continua sendo o
+`CardTitle`, e o link fica no seu conteúdo:
+
+```tsx preview col
+<Card>
+  <CardHeader>
+    <CardTitle>
+      <a href="#" className="hover:underline">Revisão dos 20.000 km</a>
+    </CardTitle>
+    <CardDescription>Agendada para 12 de maio, às 9h.</CardDescription>
+  </CardHeader>
+</Card>
+```
+
+Use `asChild` só quando outro componente já renderiza o próprio heading e precisa receber a escala do
+título. Com `asChild`, o elemento é o filho: `level` deixa de valer, e um link passado ali substitui
+o heading em vez de ficar dentro dele.
 
 ## A matriz de slots
 
 As regiões são independentes: o cabeçalho existe sem corpo, o corpo existe sem cabeçalho e o rodapé
-entra apenas quando há ações persistentes. O recuo e os divisores se ajustam a cada combinação, nos
-dois layouts.
+entra apenas quando há ações persistentes. Os divisores acompanham as regiões presentes, e o corpo
+reassume o respiro de cima ou de baixo quando é a primeira ou a última região. No layout contínuo, o
+cabeçalho só se aproxima da região seguinte quando ela existe: sozinho, ele fecha o card com o mesmo
+respiro que tem em cima.
 
 ```tsx preview col
 render(
-  <div className="grid gap-4 md:grid-cols-2">
+  <div className="grid grid-cols-2 gap-4">
     <Card>
       <CardHeader>
         <CardMedia>
@@ -199,6 +220,11 @@ render(
 );
 ```
 
+No layout contínuo, o respiro de baixo de um cabeçalho sem corpo nem rodapé segue o de cima. Essa
+regra só vale quando o cabeçalho é a última região e tem precedência sobre o `className`, então um
+`pb-*` no `CardHeader` não altera esse recuo. Para um recuo diferente, escolha o `layout`: no
+`sectioned`, as regiões usam o recuo simétrico e mais contido das superfícies de operação.
+
 ## Propriedades de Card
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -231,7 +257,7 @@ As demais propriedades são as propriedades nativas de `div`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
-| `asChild` | `boolean` | `false` | Usa o filho como heading, preservando a escala do título. |
+| `asChild` | `boolean` | `false` | Usa o filho como elemento do título, com a escala do layout. Reserve para um componente que já renderiza um heading; com `asChild`, `level` não se aplica. |
 | `className` | `string` | | Ajusta o título. |
 
 ## Propriedades de CardDescription

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

@@ -1,9 +1,16 @@
 ## Um slide por vez
 
-Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext para navegar. As setas ficam fora do trilho (-left-12/-right-12), então reserve a margem lateral no entorno.
+Use `Carousel` para percorrer uma sequência de itens do mesmo tipo em um espaço limitado, um ou
+alguns de cada vez. Para consultar e comparar muitos itens, prefira uma lista, como
+[`ActionList`](/ui/action-list), que mostra tudo de uma vez.
+
+Componha `Carousel` > `CarouselContent` > `CarouselItem` e acrescente `CarouselPrevious` e
+`CarouselNext` para navegar. As setas ficam `3rem` fora da área dos slides, então reserve essa
+margem lateral no entorno, como o `mx-12` do exemplo. Dê um nome ao carrossel com `aria-label`:
+ele é anunciado como uma região.
 
 ```tsx preview
-<Carousel className="mx-12 w-full max-w-xs">
+<Carousel className="mx-12 w-full max-w-xs" aria-label="Sessões recentes">
   <CarouselContent>
     <CarouselItem>
       <div className="flex h-32 items-center justify-center rounded-lg border bg-card text-sm">
@@ -28,10 +35,11 @@ Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext
 
 ## Vários por vista
 
-O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três slides por vez. Bom para galeria de workspaces ou repositórios.
+A largura de cada `CarouselItem` decide quantos slides cabem na área visível: `basis-1/3` mostra
+três por vez. `opts={{ align: 'start' }}` alinha o primeiro slide à borda inicial.
 
 ```tsx preview
-<Carousel className="mx-12 w-full max-w-sm" opts={{ align: 'start' }}>
+<Carousel className="mx-12 w-full max-w-sm" opts={{ align: 'start' }} aria-label="Sessões da semana">
   <CarouselContent>
     {['Sessão #128', 'Sessão #131', 'Sessão #134', 'Sessão #137', 'Sessão #140'].map((session) => (
       <CarouselItem key={session} className="basis-1/3">
@@ -48,10 +56,11 @@ O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três
 
 ## Vertical
 
-orientation=vertical empilha os slides; as setas migram para cima e para baixo (-top-12/-bottom-12). Dê uma altura ao CarouselContent para delimitar a vista.
+`orientation="vertical"` empilha os slides, e as setas passam para cima e para baixo, também
+`3rem` fora da área dos slides. Dê uma altura ao `CarouselContent` para delimitar a área visível.
 
 ```tsx preview
-<Carousel className="w-full max-w-xs" orientation="vertical">
+<Carousel className="my-12 w-full max-w-xs" orientation="vertical" aria-label="Agentes">
   <CarouselContent className="h-48">
     <CarouselItem>
       <div className="flex h-24 items-center justify-center rounded-lg border bg-card text-sm">
@@ -74,6 +83,20 @@ orientation=vertical empilha os slides; as setas migram para cima e para baixo (
 </Carousel>
 ```
 
+## Teclado
+
+Com o foco dentro do carrossel, as setas do teclado mostram o slide anterior e o próximo. Na
+orientação horizontal, use as setas esquerda e direita; na vertical, as setas para cima e para
+baixo. Os botões de navegação ficam desabilitados nas pontas, a menos que `opts` declare
+`{ loop: true }`.
+
+Em um campo editável dentro de um slide, como `input`, `textarea`, `select` ou um elemento
+`contenteditable`, as setas continuam movendo o cursor ou mudando a opção, sem trocar de slide. O
+mesmo vale para controles que navegam pelas setas, como [`Slider`](/ui/slider),
+[`RadioGroup`](/ui/radio-group), [`Tabs`](/ui/tabs), [`Toggle`](/ui/toggle) em grupo,
+[`Accordion`](/ui/accordion), listas e menus. Um carrossel colocado dentro de uma barra de
+ferramentas ou de uma grade continua respondendo às setas.
+
 ## Propriedades de Carousel
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -83,6 +106,14 @@ orientation=vertical empilha os slides; as setas migram para cima e para baixo (
 | `setApi` | `(api: EmblaCarouselType \| undefined) => void` | | Recebe a instância do Embla para controle externo, como navegar com `scrollTo` ou ler o slide ativo. |
 | `plugins` | `EmblaPluginType[]` | | Plugins do Embla associados ao carrossel, como autoplay. |
 
+Os demais atributos, como `aria-label` e `className`, vão para o elemento raiz.
+
+## Propriedades de CarouselContent
+
+`CarouselContent` delimita a área visível e recorta o que passa dela. Não tem props próprias;
+`className` e os demais atributos de `div` vão para a faixa interna que se desloca e contém os
+slides. Na orientação vertical, é nela que entra a altura, como `h-48`.
+
 ## Propriedades de CarouselItem
 
 | Propriedade | Tipo | Padrão | Descrição |

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. |