@softize/opus 12.11.0 → 13.1.0

package/src/ui/docs/content/action-view.md

@@ -1,8 +1,8 @@
-## Detalhe com estados padronizados
+## Carregar um recurso
 
-Troque o workspace pra ver o skeleton; o inexistente mostra o erro padrão com o Tentar de novo. O
-preview roda num client de mentira — no app, cada feature embrulha (TicketView…) delegando o
-fetching pra cá.
+Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento, erro e vazio no
+mesmo fluxo. No exemplo, alterne entre os workspaces para observar o carregamento e a recuperação de
+erro. O consumidor compõe somente o conteúdo disponível.
 
 ```tsx preview col
 const [id, setId] = useState('empresa-x')
@@ -35,13 +35,20 @@ render(
 )
 ```
 
-## Props
+## useViewAction
 
-| Prop | Tipo | Default | Descrição |
+`ActionView` é uma composição sobre `useViewAction(action, input)`, que devolve `data`, `error`,
+`isLoading` e `refetch` sob o `QueryClientProvider`. Use o hook direto quando o recurso alimenta
+mais de uma região da tela ou quando o carregamento precisa ser orquestrado por outro componente.
+
+## Propriedades de ActionView
+
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `ViewAction<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
 | `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
-| `children` | `(data: TData, refetch) => ReactNode` | | O estado feliz — layout 100% do consumidor; refetch pra recarregar por código. |
-| `render` | `(data: TData, refetch) => ReactNode` | | Alias de children (a API original). Children tem precedência. |
-| `loading / empty` | `ReactNode` | `3 skeletons / nada` | Sobrescreve os estados padrão quando o contexto pedir. |
-| `error` | `(err, retry) => ReactNode` | `mensagem + Tentar de novo` | Sobrescreve o estado de erro padrão. |
+| `children` | `(data: TData, refetch) => ReactNode` | | Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
+| `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. |
+| `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
+| `empty` | `ReactNode` | `nada` | Sobrescreve o estado vazio (200 sem dado). |
+| `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |

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

@@ -10,7 +10,7 @@ o handler e a web usa a mesma definição para executar ou renderizar a operaç
 
 ## Contrato primeiro
 
-> `defineContract` no `shared/` — entidades, schemas (zod + `t.*` pra tipos lógicos) e os
+> `defineContract` no `shared/` — entidades, schemas (zod + `t.*` para tipos lógicos) e os
 > metadados da action. `api` e `web` importam; nada se duplica.
 
 ```ts
@@ -64,18 +64,18 @@ name → kind → (label / summary / messages / tags…)
   → invalidates
 ```
 
-Fail-closed por padrão: `input`/`output` via `z.object` + `t.*` pros tipos lógicos; `authorize`
+Fail-closed por padrão: `input`/`output` via `z.object` + `t.*` para os tipos lógicos; `authorize`
 declarado ou gate explícito do adapter.
 
-Os átomos do catálogo servem TAMBÉM dentro dos schemas de input/output — não re-escreva
+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…).
 
 ## Modo design — o mock mora no contrato
 
 Um `mockHandler` no contrato deixa a UI rodar com dado realista **sem backend nem banco**: em
-`OPUS_MODE=design` o runtime roteia o `execute` pro `mockHandler` (cai no `handler` real se
-ausente). Como ele fica no CONTRATO (não no `bindAction`), é isomorfo — o design autora, o
+`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`.
 
 Alimente com `fake`/`fakeMany` (fixtures determinísticas do próprio schema — ver [Testes](testing)):
@@ -92,15 +92,15 @@ export const eventGet = defineContract({
 })
 // listas: `mockHandler: () => fakeMany(EventEntity.zod(), 20)`
 
-// o handoff, depois, só pluga o real — MESMO contrato:
+// o handoff, depois, só pluga o real — mesmo contrato:
 export const eventGetImpl = bindAction(eventGet, { handler: async (ctx, input) => { /* db */ } })
 ```
 
 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` pra backend externo desligado (prefixo ex-proxy sem cobertura responde
-503 em envelope — nada vaza pra prod). A SPA chama `/api` normal e recebe o dado fake, isolado:
+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:
 
 ```ts
 // vite.config.ts
@@ -118,7 +118,7 @@ persistindo, o envelope traz a mensagem-guia apontando o entry.
 
 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á pra gatear no call-site com `import.meta.env` sem quebrar o servidor
+(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.
 

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

@@ -64,10 +64,10 @@ handler: async (ctx, input) => {
 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 pro modelo → repete até a resposta em texto.
+`ctx.can`) → o resultado volta para o modelo → repete até a resposta em texto.
 
 ```ts
-// A action opta por entrar — o contrato já tem o schema, que vira a tool spec de graça:
+// A action opta por entrar; o schema do contrato também descreve a ferramenta:
 export const buscarNotas = defineContract({
   name: 'nota.buscar',
   kind: 'list',
@@ -76,7 +76,7 @@ export const buscarNotas = defineContract({
   ai: { enabled: true, description: 'Busca notas por cliente e mês.' },
 })
 
-// No handler — ou fora dele, via runtime.aiFor(base), pro backend de um chat:
+// No handler — ou fora dele, via runtime.aiFor(base), para o backend de um chat:
 const { text } = await ctx.ai!.run('Quantas notas a Empresa X emitiu em junho?')
 // o modelo chamou nota.buscar sozinho, como o usuário logado, e respondeu em texto.
 ```

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

@@ -1,6 +1,7 @@
 ## Forma curta
 
-Quase todo alert é ícone + título + uma frase — então isso é UMA linha: `title`, `description` e `icon` como props. O componente monta os slots e a a11y (`role="alert"`, que faz o leitor de tela anunciar sozinho).
+Use a forma curta quando o aviso tiver ícone, título e uma frase. Declare `title`, `description` e
+`icon`; o componente monta os slots e anuncia o conteúdo com `role="alert"`.
 
 ```tsx preview col
 <Alert icon={<Info />} title="Opus 2.8.0" description="Este workspace usa a versão pinada em opus.json." />
@@ -37,10 +38,9 @@ borda e texto; o conteúdo comunica o significado sem depender somente da cor.
 ## Mídia é opcional
 
 Sem `icon` o alert mantém somente a coluna de texto. Com ele, a forma curta materializa
-`AlertMedia` à esquerda e `AlertHeader` à direita. A mídia tem largura estável e acompanha a
-altura útil do header; com título e descrição de uma linha, a moldura termina junto do texto,
-sem sobra inferior. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) e se torna
-uma descrição.
+`AlertMedia` à esquerda e `AlertHeader` à direita. A mídia mantém uma moldura quadrada de tamanho
+estável, mesmo quando o título ou a descrição ocupam mais linhas. Texto solto como filho também
+vale (`<Alert>Sincronizado.</Alert>`) e se torna uma descrição.
 
 ```tsx preview col
 <Alert title="Sem provider próprio" description="As conversas usam o padrão do sistema." />
@@ -51,7 +51,8 @@ uma descrição.
 
 Quando a mensagem precisa de conteúdo rico, componha os slots da família. `AlertMedia`,
 `AlertHeader` e `AlertActions` são filhos diretos de `Alert`; `AlertTitle` e
-`AlertDescription` pertencem ao header.
+`AlertDescription` pertencem ao header. As ações ficam no fim lógico da superfície e centralizadas
+verticalmente na mesma linha do conteúdo — a mesma posição usada pelas ações do Toast.
 
 ```tsx preview col
 <Alert context="danger">
@@ -59,21 +60,22 @@ Quando a mensagem precisa de conteúdo rico, componha os slots da família. `Ale
     <CircleAlert />
   </AlertMedia>
   <AlertHeader>
-    <AlertTitle>Não deu pra publicar</AlertTitle>
+    <AlertTitle>Não deu para publicar</AlertTitle>
     <AlertDescription>
       <p>O registry recusou a versão 3.0.0 — ela já existe.</p>
       <p>Suba o patch e tente de novo.</p>
     </AlertDescription>
   </AlertHeader>
   <AlertActions>
-    <Button size="sm" variant="outline">
+    <Button size="sm">
       Tentar novamente
     </Button>
   </AlertActions>
 </Alert>
 ```
 
-Os dois modos convivem: com `title`/`description` preenchidos, `children` entra DEPOIS da frase — é onde vai a ação.
+Os dois modos convivem: com `title` ou `description`, `children` entra depois da mensagem e recebe a
+ação.
 
 ```tsx preview col
 <Alert
@@ -81,15 +83,15 @@ Os dois modos convivem: com `title`/`description` preenchidos, `children` entra
   title="Sessão presa"
   description="O ambiente não subiu no tempo esperado."
 >
-  <Button size="sm" variant="outline">
+  <Button size="sm">
     Reiniciar
   </Button>
 </Alert>
 ```
 
-## Props
+## Propriedades de Alert
 
-| Prop          | Tipo                                                        | Default     | Descrição                                                                                                                               |
+| Propriedade   | Tipo                                                        | Padrão      | Descrição                                                                                                                               |
 | ------------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `title`       | `React.ReactNode`                                           |             | Título do alert (a forma curta). Não é o atributo `title` do HTML — esse é tooltip nativo, banido na casa, e o componente não o aceita. |
 | `description` | `React.ReactNode`                                           |             | A frase. Sozinha, dispensa título.                                                                                                      |

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

@@ -29,3 +29,14 @@ render(
 ```
 
 Cada pergunta exige pelo menos uma opção válida selecionada **ou** texto livre não vazio. `busy` mostra o progresso no botão e trava os controles; `disabled` apenas trava a interação. A ordem de `answers` acompanha a ordem de `questions`, e o `header` de cada resposta é derivado de `question.header` (ou do próprio enunciado quando o header estiver vazio).
+
+## Propriedades de Ask
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `questions` | `AskQuestion[]` | | Uma a quatro perguntas do contrato de elicitação; fora dessa faixa o envio é bloqueado. |
+| `answers` | `AskAnswer[]` | | Respostas controladas, na mesma ordem de `questions`; entradas ausentes contam como vazias. |
+| `onChange` | `(answers: AskAnswer[]) => void` | | Recebe a lista completa a cada alteração. |
+| `onSubmit` | `(answers: AskAnswer[]) => void` | | Dispara somente quando toda pergunta tem uma opção ou texto livre. |
+| `disabled` | `boolean` | `false` | Trava as opções e o envio. |
+| `busy` | `boolean` | `false` | Envio em andamento: o botão mostra o spinner e desabilita. |

package/src/ui/docs/content/aspect-ratio.md

@@ -15,7 +15,7 @@ contêiner (o pai): a altura o componente deriva sozinho.
 
 ## Quadrado (1/1)
 
-ratio={1} trava num quadrado — o formato dos avatares de agente e dos ícones de skill, onde a
+ratio={1} trava em um quadrado — o formato dos avatares de agente e dos ícones de skill, onde a
 moldura precisa ser previsível.
 
 ```tsx preview col-start
@@ -57,10 +57,10 @@ layout quando o preview carrega.
 </div>
 ```
 
-## Props
+## Propriedades de AspectRatio
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `ratio` | `number` | `1` | A razão largura/altura. 16/9 pra vídeo/preview, 1 pra quadrado, 4/3 pra clássico. |
+| `ratio` | `number` | `1` | A razão largura/altura. 16/9 para vídeo/preview, 1 para quadrado, 4/3 para clássico. |
 | `children` | `React.ReactNode` | | O conteúdo a enquadrar (img, iframe, div) — preencha com h-full w-full e object-cover. |
 | `className` | `string` | | Estilo do bloco — borda, rounded e overflow-hidden moram aqui, não no filho. |

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

@@ -5,7 +5,7 @@ title: Auditoria
 # Auditoria
 
 Toda action executada vira um registro imutável: quem, o quê, quando, com que entrada e
-resultado. O runtime emite um `AuditRecord` por execução pro(s) sink(s) configurado(s) — de
+resultado. O runtime emite um `AuditRecord` por execução para o(s) sink(s) configurado(s) — de
 graça, sem o handler pedir. O contrato é o `AuditSink`.
 
 ## O contrato
@@ -43,7 +43,7 @@ interface AuditRecord {
 import { consoleAudit } from '@softize/opus/audit/console'
 import { pgAudit } from '@softize/opus/audit/pg'
 
-// Dev: uma linha por action (pretty num TTY, json senão).
+// Dev: uma linha por action (pretty em um TTY, json senão).
 const dev = consoleAudit()
 
 // Produção: grava na tabela audit_log (Postgres).

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

@@ -7,7 +7,7 @@ title: Autenticação
 Quem é o usuário, de qual tenant, e o que ele pode. O contrato é um adapter do core
 (`AuthAdapter`): a cada request o runtime chama `resolveContext` e injeta o resultado no
 handler — `ctx.user`, `ctx.tenantId`, `ctx.can`. O Opus **não** implementa RBAC/ABAC; ele
-delega a decisão pro `can` que o driver pluga.
+delega a decisão para o `can` que o driver pluga.
 
 ## O contrato
 
@@ -31,7 +31,7 @@ política usada por ela.
 import { jwtAuth } from '@softize/opus/auth/jwt'
 import { betterAuthSession } from '@softize/opus/auth/better-auth'
 
-// JWT: valida o token (HS256 por padrão) e mapeia o payload pro User.
+// JWT: valida o token (HS256 por padrão) e mapeia o payload para o User.
 const jwt = jwtAuth({ secret: process.env.JWT_SECRET! })
 
 // better-auth: valida a sessão contra um IdP better-auth remoto.
@@ -44,7 +44,7 @@ const idp = betterAuthSession({
 
 O `jwt` procura o token no `Authorization: Bearer`, em cookie ou custom (via `getToken`); o
 `secret` pode ser string ou um resolver async por `kid`. O `betterAuthSession` faz fetch da
-sessão no IdP (`timeoutMs`, default 5s) e mapeia pro `User`/tenant/can (o `can` default nega
+sessão no IdP (`timeoutMs`, default 5s) e mapeia para o `User`/tenant/can (o `can` default nega
 tudo — plugue o seu).
 
 ## No runtime

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

@@ -1,4 +1,4 @@
-## Básico
+## Retrato com imagem
 
 AvatarImage com src/alt e AvatarFallback com as iniciais — o fallback aparece enquanto a imagem
 carrega ou se ela falha.
@@ -12,8 +12,8 @@ carrega ou se ela falha.
 
 ## Fallback de iniciais
 
-Sem AvatarImage (ou com src quebrado), só o AvatarFallback renderiza — iniciais pra pessoa, ícone
-pra agente.
+Sem AvatarImage (ou com src quebrado), só o AvatarFallback renderiza — iniciais para pessoa, ícone
+para agente.
 
 ```tsx preview
 <Avatar>
@@ -28,7 +28,7 @@ pra agente.
 
 ## Tamanhos
 
-size sm/default/lg — o fallback acompanha o tamanho. sm pra listas densas, lg pra cabeçalho de
+size sm/default/lg — o fallback acompanha o tamanho. sm para listas densas, lg para cabeçalho de
 workspace.
 
 ```tsx preview
@@ -45,8 +45,8 @@ workspace.
 
 ## Com selo de status
 
-AvatarBadge é o ponto no canto inferior — verde pro agente developer rodando uma sessão, cinza
-pro ocioso. Tinja com className.
+AvatarBadge é o ponto no canto inferior — verde para o agente developer rodando uma sessão, cinza
+para o ocioso. Tinja com className.
 
 ```tsx preview
 <Avatar>
@@ -82,13 +82,33 @@ excedente — os membros do workspace Empresa X.
 </AvatarGroup>
 ```
 
-## Props
+## Propriedades de Avatar
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` (Avatar) | `'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato — o fallback e o selo acompanham. |
-| `src` (AvatarImage) | `string` | | URL da imagem. Enquanto carrega (ou se falha), o AvatarFallback fica no lugar. |
-| `alt` (AvatarImage) | `string` | | Texto alternativo da imagem — o nome da pessoa ou do agente. |
-| `children` (AvatarFallback) | `React.ReactNode` | | O que aparece sem imagem: iniciais (pessoa) ou ícone (agente). |
-| `className` (AvatarBadge) | `string` | | Selo no canto inferior — tinja o fundo (ex.: bg-emerald-500) pra refletir o status. |
-| `children` (AvatarGroupCount) | `React.ReactNode` | | O excedente da pilha (ex.: "+3"), fechando o AvatarGroup. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato; o fallback e o selo acompanham a escala. |
+
+## Propriedades de AvatarImage
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `src` | `string` | | URL da imagem. Enquanto ela carrega ou quando falha, `AvatarFallback` ocupa o lugar. |
+| `alt` | `string` | | Texto alternativo que identifica a pessoa ou o agente. |
+
+## Propriedades de AvatarFallback
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | | Iniciais ou ícone exibido quando a imagem não está disponível. |
+
+## Propriedades de AvatarBadge
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Classes usadas para comunicar visualmente o status no selo. |
+
+## Propriedades de AvatarGroupCount
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | | Quantidade excedente no fim do grupo, como `+3`. |

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

@@ -24,7 +24,7 @@ decisão em cada tela.
 
 ## Com ícone
 
-Um svg filho ganha size-3 automaticamente — bom pra reforçar o estado sem crescer o rótulo.
+Um svg filho ganha size-3 automaticamente — bom para reforçar o estado sem crescer o rótulo.
 
 ```tsx preview
 <Badge context="success"><CircleCheck /> Regressão verde</Badge>
@@ -41,9 +41,9 @@ variantes.
 </Badge>
 ```
 
-## Props
+## Propriedades de Badge
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado ou destaque contextual. |
 | `variant` | `'solid' \| 'subtle' \| 'outline'` | `'subtle'` | O tratamento visual aplicado ao contexto. |

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

@@ -1,4 +1,4 @@
-## Básico
+## Caminho atual
 
 A composição é manual: BreadcrumbLink nos níveis navegáveis, BreadcrumbPage no atual (não
 clicável, aria-current=page) e um BreadcrumbSeparator entre cada item.
@@ -23,7 +23,7 @@ clicável, aria-current=page) e um BreadcrumbSeparator entre cada item.
 
 ## Com ícone e separador custom
 
-O primeiro nível pode levar um ícone do lucide. BreadcrumbSeparator aceita children pra trocar o
+O primeiro nível pode levar um ícone do lucide. BreadcrumbSeparator aceita children para trocar o
 chevron padrão por outro glifo (aqui, uma barra).
 
 ```tsx preview col-start
@@ -53,7 +53,7 @@ chevron padrão por outro glifo (aqui, uma barra).
 
 ## Colapsado
 
-Trilha funda demais pro espaço: BreadcrumbEllipsis substitui os níveis do meio (que viram um
+Trilha funda demais para o espaço: BreadcrumbEllipsis substitui os níveis do meio (que viram um
 menu/popover) e mantém só a raiz e o destino.
 
 ```tsx preview col-start
@@ -78,10 +78,15 @@ menu/popover) e mantém só a raiz e o destino.
 </Breadcrumb>
 ```
 
-## Props
+## Propriedades de BreadcrumbLink
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `asChild` (BreadcrumbLink) | `boolean` | `false` | Funde as props no filho (via Slot) — use pra integrar o Link do seu roteador no lugar do `<a>` nativo. |
-| `href` (BreadcrumbLink) | `string` | | Destino do nível navegável — o que o consumidor decide por item. |
-| `children` (BreadcrumbSeparator) | `React.ReactNode` | `<ChevronRight />` | Glifo entre os itens. Omita pro chevron padrão ou passe outro ícone. |
+| `asChild` | `boolean` | `false` | Repassa as propriedades ao filho para integrar o link do roteador no lugar de `<a>`. |
+| `href` | `string` | | Destino do nível navegável. |
+
+## Propriedades de BreadcrumbSeparator
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | `<ChevronRight />` | Elemento entre os itens. Omita para usar o chevron padrão ou passe outro ícone. |

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

@@ -31,7 +31,7 @@ O tamanho icon exige `aria-label`, porque não há texto visível. Os botões s
 
 busy = ação em andamento (DEPOIS do clique): o Spinner e o disabled vêm do botão. Com icon, o
 Spinner TROCA o ícone (não soma). Não confunda com carregar conteúdo (ANTES) — isso é Spinner
-centralizado/Skeleton num nível de página.
+centralizado/Skeleton em um nível de página.
 
 ```tsx preview
 <Button disabled>Desabilitado</Button>
@@ -43,7 +43,7 @@ centralizado/Skeleton num nível de página.
 ## Como outro elemento (asChild)
 
 Âncora com cara de botão: asChild renderiza o filho (Radix Slot) — sem forkar estilo.
-buttonVariants serve pro caso sem filho único.
+buttonVariants serve para o caso sem filho único.
 
 ```tsx preview
 <Button asChild variant="outline">
@@ -51,13 +51,88 @@ buttonVariants serve pro caso sem filho único.
 </Button>
 ```
 
-## Props
+## Propriedades de Button
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | A hierarquia ou o risco comunicado pela ação. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'solid'` | O tratamento visual aplicado ao contexto. |
 | `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | O tamanho. Os icon* são quadrados (2.25/2/1.5rem) para botões só de ícone, com `aria-label`. |
-| `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<button>` — pra âncoras e afins. |
-| `busy` | `boolean` | `false` | Ação em andamento (depois do clique): mostra Spinner + desabilita. Não é "carregando" de conteúdo (que é Spinner/Skeleton num nível de página). |
+| `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<button>` — para âncoras e afins. |
+| `busy` | `boolean` | `false` | Ação em andamento (depois do clique): mostra Spinner + desabilita. Não é "carregando" de conteúdo (que é Spinner/Skeleton em um nível de página). |
 | `icon` | `React.ElementType` | | Ícone à esquerda (ex.: icon={Plus}). No busy é trocado pelo Spinner — não soma. |
+
+## ButtonGroup
+
+Use `ButtonGroup` quando ações relacionadas precisarem formar um bloco contínuo. As bordas internas
+colapsam e somente as pontas externas permanecem arredondadas. Mantenha a mesma variante nos filhos
+para preservar a unidade visual.
+
+```tsx preview
+<ButtonGroup>
+  <Button variant="outline">Visão geral</Button>
+  <Button variant="outline">Sessões</Button>
+  <Button variant="outline">Habilidades</Button>
+</ButtonGroup>
+```
+
+### Ação dividida
+
+Combine a ação principal, um separador e um botão de ícone quando o mesmo comando oferecer
+variações.
+
+```tsx preview
+<ButtonGroup>
+  <Button icon={Play}>Rodar agente developer</Button>
+  <ButtonGroupSeparator />
+  <Button size="icon" aria-label="Mais opções">
+    <ChevronDown />
+  </Button>
+</ButtonGroup>
+```
+
+### Com rótulo
+
+`ButtonGroupText` adiciona um contexto inerte ao grupo. Ele também aceita `asChild` para assumir a
+semântica de outro elemento, como `label`.
+
+```tsx preview
+<ButtonGroup>
+  <ButtonGroupText>
+    <GitBranch />
+    empresa-x-api
+  </ButtonGroupText>
+  <Button variant="outline" icon={RotateCw}>Sincronizar</Button>
+</ButtonGroup>
+```
+
+### Vertical
+
+`orientation="vertical"` empilha os filhos e transfere a junção das bordas para o eixo vertical.
+
+```tsx preview col-start
+<ButtonGroup orientation="vertical">
+  <Button variant="outline" size="icon" aria-label="Rodar sessão"><Play /></Button>
+  <Button variant="outline" size="icon" aria-label="Pausar sessão"><Pause /></Button>
+  <Button variant="outline" size="icon" aria-label="Reiniciar sessão"><RotateCw /></Button>
+</ButtonGroup>
+```
+
+### Propriedades de ButtonGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do bloco e do colapso das bordas. |
+| `shape` | `'default' \| 'pill'` | `'default'` | Geometria das extremidades externas do grupo. |
+
+### Propriedades de ButtonGroupSeparator
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Direção do traço divisor; use vertical em grupos horizontais. |
+
+### Propriedades de ButtonGroupText
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Renderiza como o filho para assumir outra semântica sem perder o estilo. |

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

@@ -1,3 +1,7 @@
+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.
@@ -17,7 +21,7 @@ render(
 
 ## Intervalo
 
-mode=range guarda { from, to } — o padrão pra filtrar sessões por janela de datas. O primeiro clique fixa o início; o segundo, o fim.
+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.
 
 ```tsx preview
 const [week, setWeek] = useState<DateRange | undefined>({
@@ -37,7 +41,7 @@ render(
 
 ## Navegação por dropdown
 
-captionLayout=dropdown troca o título do mês por seletores de mês e ano — bom pra pular pra um período distante (ex.: histórico de um repositório) sem clicar mês a mês.
+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.
 
 ```tsx preview
 <Calendar
@@ -47,16 +51,25 @@ captionLayout=dropdown troca o título do mês por seletores de mês e ano — b
 />
 ```
 
-## Props
+## Propriedades de Calendar
 
-| Prop | Tipo | Default | Descrição |
+| 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 pra escolher um intervalo longo. |
+| `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. |
+
+## 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.

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

@@ -10,7 +10,7 @@ O uso mais comum: a superfície de conteúdo em repouso (`rounded-xl` + `border`
 
 ## Estruturado (header / conteúdo / rodapé)
 
-Pra painel com estrutura: cada slot é dono do próprio padding (como o Dialog). CardTitle/CardDescription no header; CardFooter alinha as ações.
+Para painel com estrutura: cada slot é dono do próprio padding (como o Dialog). CardTitle/CardDescription no header; CardFooter alinha as ações.
 
 ```tsx preview col
 <Card>
@@ -47,3 +47,29 @@ Pra painel com estrutura: cada slot é dono do próprio padding (como o Dialog).
   </CardFooter>
 </Card>
 ```
+
+## Ação no cabeçalho
+
+`CardAction` é o slot de ação do header (um botão ou menu). Quem compõe posiciona — em geral um
+`CardHeader` em `flex-row` com o título de um lado e a ação do outro.
+
+```tsx preview col
+<Card>
+  <CardHeader className="flex-row items-start justify-between">
+    <div>
+      <CardTitle>Empresa X</CardTitle>
+      <CardDescription>3 agentes vinculados.</CardDescription>
+    </div>
+    <CardAction>
+      <Button size="sm" variant="outline">Editar</Button>
+    </CardAction>
+  </CardHeader>
+</Card>
+```
+
+## Propriedades de Card
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Renderiza o filho com a superfície do Card (ex.: um `<button>` clicável inteiro). |
+| `className` | `string` | | Compõe sobre a superfície; os slots (`CardHeader`, `CardBody`, `CardContent`, `CardFooter`, `CardAction`) são donos do próprio padding. |