@softize/opus 12.11.0 → 13.1.0

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

@@ -1,6 +1,7 @@
-## Básico
+## Uma tecla
 
-Uma tecla por Kbd. É só visual — quem escuta o atalho é o seu handler, não o componente.
+Use um `Kbd` para representar cada tecla. O componente apresenta o atalho; a captura do teclado
+continua no handler do aplicativo.
 
 ```tsx preview
 <Kbd>Esc</Kbd>
@@ -8,7 +9,7 @@ Uma tecla por Kbd. É só visual — quem escuta o atalho é o seu handler, não
 
 ## Combinação
 
-Envolva as teclas num KbdGroup e ponha o conector (+) como texto entre elas — o padrão pra paleta de comandos do Maestro.
+Agrupe as teclas com `KbdGroup` e use `+` como texto entre elas.
 
 ```tsx preview
 <KbdGroup>
@@ -20,7 +21,8 @@ Envolva as teclas num KbdGroup e ponha o conector (+) como texto entre elas —
 
 ## Com ícone
 
-Um ícone (lucide) como filho do Kbd ganha size-3 automático — bom pra ⌘ e Enter, onde o glifo lê melhor que a letra.
+Um ícone Lucide recebe automaticamente a escala do componente. Use-o quando o símbolo for mais
+reconhecível que o nome da tecla.
 
 ```tsx preview col-start
 <KbdGroup>
@@ -35,7 +37,8 @@ Um ícone (lucide) como filho do Kbd ganha size-3 automático — bom pra ⌘ e
 
 ## No tooltip
 
-Dentro de um TooltipContent o Kbd inverte o tom sozinho (fundo claro sobre o balão escuro) — anuncie o atalho da ação ao passar o mouse.
+Dentro de `TooltipContent`, o componente ajusta o contraste automaticamente. O tooltip deve nomear a
+ação antes de informar seu atalho.
 
 ```tsx preview
 <Tooltip>
@@ -52,11 +55,16 @@ Dentro de um TooltipContent o Kbd inverte o tom sozinho (fundo claro sobre o bal
 </Tooltip>
 ```
 
-## Props
+## Propriedades de Kbd
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `children (Kbd)` | `React.ReactNode` | | A tecla — texto (Esc, ⌘, K) ou um ícone lucide, que recebe size-3 automático. |
-| `className (Kbd)` | `string` | | Classes extras na tecla, mescladas com cn — pra ajustar tamanho ou cor pontualmente. |
-| `children (KbdGroup)` | `React.ReactNode` | | As teclas do combo, mais o conector (ex.: "+") como texto entre elas. |
-| `className (KbdGroup)` | `string` | | Classes extras no agrupador (inline-flex + gap-1), mescladas com cn. |
+| `children` | `React.ReactNode` | | Texto ou ícone que representa a tecla. Ícones Lucide recebem a escala visual do componente. |
+| `className` | `string` | | Classes adicionais aplicadas à tecla. |
+
+## Propriedades de KbdGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | | Teclas da combinação e conectores, como `+`, entre elas. |
+| `className` | `string` | | Classes adicionais aplicadas ao agrupador. |

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

@@ -1,6 +1,6 @@
 ## Com campo de texto
 
-htmlFor aponta pro id do controle — clicar no rótulo foca o campo.
+Associe `htmlFor` ao `id` do controle para que clicar no rótulo mova o foco para o campo.
 
 ```tsx preview col md
 <div className="grid gap-2">
@@ -11,7 +11,8 @@ htmlFor aponta pro id do controle — clicar no rótulo foca o campo.
 
 ## Com Checkbox
 
-O Label já é flex com gap — controle inline entra sem wrapper extra; clicar no texto alterna a caixa.
+`Label` já organiza controles inline com espaçamento. Ao associá-lo ao `Checkbox`, clicar no texto
+também alterna a seleção.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -22,7 +23,8 @@ O Label já é flex com gap — controle inline entra sem wrapper extra; clicar
 
 ## Par desabilitado
 
-Controle disabled esmaece o rótulo junto (peer-disabled) — o par inteiro comunica o estado, sem classe manual.
+Quando o controle está desabilitado, o rótulo associado acompanha o tratamento visual sem exigir
+uma classe adicional.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -30,3 +32,10 @@ Controle disabled esmaece o rótulo junto (peer-disabled) — o par inteiro comu
   <Label htmlFor="archive-workspace">Arquivar o workspace</Label>
 </div>
 ```
+
+## Propriedades de Label
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `htmlFor` | `string` | | O `id` do controle rotulado; clicar no rótulo foca o controle. |
+| `className` | `string` | | Compõe sobre o estilo padrão; o rótulo esmaece com `peer-disabled` e dentro de `group[data-disabled]`. |

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

@@ -4,9 +4,9 @@ title: Log
 
 # Log
 
-Log estruturado que chega no handler já com contexto (per-request, per-action) via
-`ctx.log`. O contrato é o `LoggerAdapter` — a mesma interface `Logger` que o core usa por
-dentro, então o seu log e o do runtime saem no mesmo lugar, no mesmo formato.
+Use `ctx.log` para registrar eventos estruturados com o contexto da requisição e da action. O
+`LoggerAdapter` também recebe os registros internos do runtime, mantendo aplicação e Opus no mesmo
+destino e formato.
 
 ## O contrato
 
@@ -49,7 +49,7 @@ handler: async (ctx, input) => {
 }
 ```
 
-## Limites (por enquanto)
+## Limites atuais
 
 Superfície mínima de níveis + `child`. Sem sampling nem transports próprios — isso mora no
 `pino` que você passa. Drivers hoje: `pino`; outros entram por reincidência.

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

@@ -1,13 +1,14 @@
 ## Fonte e resultado
 
-Uso: <Markdown content={fonte} />. No palco, o resultado; no bloco abaixo, a fonte markdown que o produziu. O componente recebe só content: string.
+Passe o texto em `content`. O exemplo mostra primeiro o resultado renderizado e, depois, o Markdown
+que o produziu.
 
 ```tsx preview col 2xl
 const sample = [
   '# Markdown na Softize',
   '',
   'Renderiza **doc técnica** e mensagem de chat — `SKILL.md`, síntese de papel, resposta de agente.',
-  'O motor é o markdown-it, o MESMO que renderiza estas páginas.',
+  'O motor é o markdown-it, o mesmo que renderiza estas páginas.',
   '',
   '## Sintaxe coberta',
   '',
@@ -18,7 +19,7 @@ const sample = [
   '1. Primeiro passo',
   '2. Segundo passo',
   '',
-  '> Citação calma, pro tom certo.',
+  '> Citação calma, para o tom certo.',
   '',
   '---',
   '',
@@ -33,9 +34,9 @@ render(<Markdown content={sample} />)
 ```
 
 
-## Props
+## Propriedades de Markdown
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `content` | `string` | | O markdown cru (CommonMark + tabela GFM, via markdown-it). HTML no fonte é **escapado**, não interpretado — por isso serve pra texto vindo de gente ou de modelo. |
+| `content` | `string` | | O markdown cru (CommonMark + tabela GFM, via markdown-it). HTML no fonte é **escapado**, não interpretado — por isso serve para texto vindo de gente ou de modelo. |
 | `className` | `string` | | Classes do wrapper. |

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

@@ -4,10 +4,9 @@ title: MCP
 
 # MCP
 
-Expõe as actions `ai:enabled` do runtime como **tools MCP** — a porta pra uma IA de **fora**
-(Claude Desktop, o agente de um parceiro, um hub próprio) alcançar o app pelo protocolo. É o
-mesmo bridge do agente co-locado (`runtime.aiTools`) e a mesma execução (`runtime.execute`,
-como o usuário resolvido). O MCP é só o transporte.
+Use o servidor MCP para disponibilizar actions `ai:enabled` a agentes que executam fora da
+aplicação. A chamada continua passando por `runtime.execute`, com a mesma validação, autorização e
+auditoria; o MCP fornece apenas o transporte.
 
 ## Montar
 
@@ -22,23 +21,22 @@ const server = createOpusMcpServer(runtime, {
   resolveContext: async (extra) => auth.resolveFromMcp(extra),
 })
 
-await server.connect(new StdioServerTransport()) // local; HTTP/SSE pra remoto
+await server.connect(new StdioServerTransport()) // local; HTTP/SSE para remoto
 ```
 
 `ListTools` devolve as actions `ai:enabled` (nome + descrição + JSON Schema do input);
 `CallTool` executa a action pelo `runtime.execute` — validação, auth (`ctx.can`) e audit,
 tudo igual a uma chamada normal. Read-only? Marque só actions de leitura com `ai:enabled`.
 
-## Interno × MCP
+## Escolher entre integração interna e MCP
 
-- **Monolito / chat co-locado:** não precisa de MCP — `runtime.aiFor(base).run()` chama as
-  actions direto, in-process (ver o recurso **IA generativa**).
-- **IA por fora / ecossistema:** o agente vive num serviço próprio e alcança N apps pela
-  mesma porta MCP. É aqui que ele se paga.
+- **Agente dentro da aplicação:** use `runtime.aiFor(base).run()` para chamar as actions no mesmo
+  processo.
+- **Agente em outro serviço:** use MCP para oferecer a mesma coleção de ferramentas por uma
+  interface interoperável.
 
-Mesmas tools, transportes diferentes.
+## Limites atuais
 
-## Limites (por enquanto)
-
-Você monta o transporte (stdio/HTTP) — o server é agnóstico. A confirmação de action
-`destructive` sobre MCP (elicitation) entra quando um caso real cobrar; comece read-only.
+O consumidor escolhe e monta o transporte, como stdio ou HTTP. A confirmação de actions destrutivas
+ainda não faz parte desta integração; até que esse fluxo exista, exponha somente operações de
+leitura.

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

@@ -1,7 +1,7 @@
 ## Menu de ações
 
-Ícone à esquerda, atalho à direita (MenuShortcut), separador antes da zona perigosa e
-`context="danger"` na ação que destrói.
+Use `Menu` para reunir ações relacionadas em um painel ancorado. `MenuShortcut` posiciona o atalho à
+direita; separe ações perigosas e declare `context="danger"` nelas.
 
 ```tsx preview
 <Menu>
@@ -17,11 +17,10 @@
 </Menu>
 ```
 
-## Contexto: clique direito
+## Abrir pelo menu de contexto
 
-O papel do ContextMenu (aposentado na 5.0.0) com o MESMO componente — só muda o
-gatilho: controlado, ancorado no ponteiro. `onContextMenu` guarda a posição e abre;
-um gatilho invisível `position: fixed` naquele ponto ancora o conteúdo.
+Para abrir pelo clique direito, controle o estado do menu e use a posição do ponteiro como âncora.
+Esse padrão substitui o antigo `ContextMenu` sem introduzir outra família de componentes.
 
 ```tsx preview
 const [pos, setPos] = useState(null)
@@ -52,9 +51,10 @@ render(
 )
 ```
 
-## Seleção: checkbox e radio
+## Seleção por checkbox ou radio
 
-CheckboxItem pra liga/desliga, RadioGroup pra escolha exclusiva — estado fica no consumidor (controlado).
+Use `MenuCheckboxItem` para opções independentes e `MenuRadioGroup` para escolhas mutuamente
+exclusivas. O consumidor controla o estado nos dois casos.
 
 ```tsx preview
 const [showArchived, setShowArchived] = useState(false)
@@ -93,7 +93,7 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
   <MenuContent align="start">
     <MenuItem><ExternalLink /> Abrir preview</MenuItem>
     <MenuSub>
-      <MenuSubTrigger><ArrowDownAZ /> Mover pra</MenuSubTrigger>
+      <MenuSubTrigger><ArrowDownAZ /> Mover para</MenuSubTrigger>
       <MenuSubContent>
         <MenuItem>Empresa X</MenuItem>
         <MenuItem>Softize</MenuItem>
@@ -104,12 +104,36 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 </Menu>
 ```
 
-## Props
+## Propriedades de MenuItem
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `MenuItem.context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma consequência perigosa. |
-| `MenuItem.inset` | `boolean` | | Recuo à esquerda pra alinhar item sem ícone com os que têm. |
-| `MenuContent.align / sideOffset` | `'start' \| 'center' \| 'end' / number` | `'center' / 4` | Alinhamento e distância em relação ao gatilho (Radix). |
-| `MenuCheckboxItem.checked / onCheckedChange` | `boolean / (checked: boolean) => void` | | Estado do liga/desliga — controlado pelo consumidor. |
-| `MenuRadioGroup.value / onValueChange` | `string / (value: string) => void` | | Escolha exclusiva entre os MenuRadioItem filhos. |
+| `context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma ação com consequência perigosa. |
+| `inset` | `boolean` | | Alinha um item sem ícone com os itens que possuem ícone. |
+
+## Propriedades de MenuGroup
+
+`MenuGroup` agrupa itens relacionados para leitores de tela (`role="group"`); combine com
+`MenuLabel` para nomear o grupo e `MenuSeparator` para separá-lo do próximo. Não tem props
+próprias além das de DOM.
+
+## Propriedades de MenuContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
+| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+
+## Propriedades de MenuCheckboxItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `checked` | `boolean` | | Estado controlado do item. |
+| `onCheckedChange` | `(checked: boolean) => void` | | Chamado quando a pessoa alterna o item. |
+
+## Propriedades de MenuRadioGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Valor selecionado no grupo. |
+| `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outro `MenuRadioItem`. |

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

@@ -39,3 +39,16 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 ```tsx preview col
 <MetricCard loading />
 ```
+
+## Propriedades de MetricCard
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `ReactNode` | | O nome da medida. |
+| `value` | `ReactNode` | | O valor já formatado pelo consumidor. |
+| `loading` | `boolean` | `false` | Substitui rótulo e valor por skeletons e marca `aria-busy`. |
+| `labelAction` | `ReactNode` | | Controle ao lado do rótulo, como uma explicação em tooltip. |
+| `description` | `ReactNode` | | Contexto que explica recorte, proporção ou significado do valor. |
+| `icon` | `ReactNode` | | Ícone decorativo que identifica a natureza da medida. |
+| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card. |
+| `action` | `ReactNode` | | Ação relacionada diretamente à medida. |

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

@@ -4,8 +4,8 @@ title: Observabilidade
 
 # Observabilidade
 
-O core expõe uma porta vendor-neutral; o driver OpenTelemetry cria spans ativos para actions
-e reactions sem escolher backend, exporter ou Collector.
+Use `ObservabilityAdapter` para envolver actions e reactions em spans sem acoplar o core a um
+fornecedor. O driver OpenTelemetry deixa backend, exporter e Collector sob controle do aplicativo.
 
 ## Driver OpenTelemetry
 

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

@@ -16,10 +16,9 @@ Uma navegação contextual para outra página pode ocupar `actions`, e tabs fica
 recortes da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell
 próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes da superfície.
 
-Quando carregamento, falha ou ausência substituírem toda a área de conteúdo, use `PageState`. Na
-forma curta ele pode ser escrito como filho direto, pois `Page` cria o `PageBody`; na composição
-explícita, coloque-o dentro de `PageBody`. `Page` não recebe flags de dados: uma página pode agregar
-fontes independentes e uma falha parcial não deve ocultar as demais seções.
+Estados integrais de carregamento, falha ou ausência são compostos no body com `PageState`,
+detalhado abaixo. `Page` não recebe flags de dados: uma página pode agregar fontes independentes e
+uma falha parcial não deve ocultar as demais seções.
 
 ```tsx preview col
 render(
@@ -42,6 +41,14 @@ render(
 )
 ```
 
+## Ações no chrome do shell
+
+Quando o shell reserva uma barra própria para contexto e ações, envolva sua região de conteúdo com
+`PageActionsTarget` e passe o elemento de destino em `target`. As ações declaradas em `Page`
+continuam pertencendo semanticamente ao cabeçalho da página, mas são projetadas nesse elemento.
+Com `target={null}`, elas permanecem na posição padrão; isso permite montar o alvo por `ref` sem
+uma renderização intermediária inconsistente.
+
 ## Composição explícita
 
 Use os slots quando a página precisar compor o header diretamente. Não misture propriedades da
@@ -65,9 +72,44 @@ render(
 )
 ```
 
-## Props
+## Estados integrais
+
+Use `PageState` quando carregamento, falha ou ausência substituírem todo o conteúdo principal. Na
+forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
+explícita, coloque-o dentro de `PageBody`. O cabeçalho continua visível e o estado recebe composição,
+altura e semântica acessível consistentes.
+
+```tsx preview col
+<Page title="Relatório">
+  <PageState
+    status="error"
+    title="Não foi possível carregar o relatório"
+    description="Tente novamente. Se o problema continuar, volte mais tarde."
+    action={<Button>Tentar novamente</Button>}
+  />
+</Page>
+```
+
+`loading` centraliza o `Spinner`; `error` compõe `Alert`; `empty` compõe `Empty`; e `ready` entrega
+os filhos sem acrescentar uma superfície.
 
-| Prop          | Tipo        | Default     | Descrição                                                                                       |
+```tsx preview col
+<Page title="Relatórios">
+  <PageState
+    status="empty"
+    title="Nenhum relatório"
+    description="Crie o primeiro relatório para começar."
+    action={<Button>Novo relatório</Button>}
+  />
+</Page>
+```
+
+Não use `PageState` para uma falha parcial. Se outra parte da página continua utilizável, mantenha o
+estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert`.
+
+## Propriedades de Page
+
+| Propriedade   | Tipo        | Padrão      | Descrição                                                                                       |
 | ------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`       | `string`    |             | O h1 da página.                                                                                 |
 | `count`       | `number`    |             | Total de itens ao lado do título (mono, esmaecido).                                             |
@@ -75,3 +117,14 @@ render(
 | `actions`     | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
 | `className`   | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`    | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
+
+## Propriedades de PageState
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `status` | `'loading' \| 'error' \| 'empty' \| 'ready'` | | Estado integral do conteúdo. |
+| `title` | `ReactNode` | Texto seguro por estado | Situação reconhecível pela pessoa. |
+| `description` | `ReactNode` | | Impacto ou próximo passo aplicável. |
+| `icon` | `ReactNode` | Alerta no erro | Ícone decorativo do estado. |
+| `action` | `ReactNode` | | Recuperação, seleção ou criação aplicável. |
+| `children` | `ReactNode` | | Conteúdo renderizado somente em `ready`. |

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

@@ -1,10 +1,9 @@
-## Básico
+## Navegação entre páginas
 
-É composição: Pagination embrulha PaginationContent, e cada PaginationItem segura um link. `page`
-dá o número e o nome acessível (“Página N”); `isActive` marca a página atual (vira outline). Cada
-número tem altura fixa e largura mínima quadrada que cresce com os dígitos — 5726 e 5727 nunca se
-colam. As setas seguem quadradas e já falam pt-BR; `label` localiza, `iconOnly` deixa só a seta.
-É o único paginador da casa: `ActionList` compõe esta primitiva no rodapé, na escala densa.
+Componha `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
+número e o nome acessível; `isActive` identifica a página atual. Os controles mantêm altura fixa e
+a largura cresce quando o número precisa de mais espaço. `ActionList` usa esta mesma primitiva no
+rodapé.
 
 ```tsx preview
 <Pagination>
@@ -30,7 +29,7 @@ colam. As setas seguem quadradas e já falam pt-BR; `label` localiza, `iconOnly`
 
 ## Números longos
 
-A largura mínima é quadrada; o número manda no resto. Na escala densa de um rodapé, ajuste por
+A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, ajuste por
 `className` (`h-7 min-w-7 text-xs` nos números; `size-7` mais `iconClassName="size-3.5"` nas
 setas com `iconOnly`).
 
@@ -61,7 +60,8 @@ setas com `iconOnly`).
 
 ## Com elipse
 
-PaginationEllipsis é o atalho decorativo (aria-hidden) entre blocos de páginas distantes — útil quando a lista de sessões do workspace tem páginas demais pra caber na barra.
+`PaginationEllipsis` marca, de forma decorativa e com `aria-hidden`, uma sequência de páginas que
+não cabe na barra.
 
 ```tsx preview
 <Pagination>
@@ -123,14 +123,19 @@ render(
 )
 ```
 
-## Props
+## Propriedades de PaginationLink
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `page (PaginationLink)` | `number` | | Número da página: vira o conteúdo (quando não há `children`) e o nome acessível “Página N”. |
-| `isActive (PaginationLink)` | `boolean` | `false` | Marca a página atual: vira outline e ganha aria-current="page". Os demais ficam ghost. |
-| `href (PaginationLink)` | `string` | | Com `href` o link é um `<a>`; sem `href` é um `<button>` controlado por `onClick`, com `disabled`. |
-| `size (PaginationLink)` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | Escala do Button. Números usam `default` (largura mínima quadrada que cresce); as setas com `iconOnly` usam `icon`. |
-| `label (Previous/Next)` | `string` | `'Página anterior'` / `'Próxima página'` | Nome acessível e texto visível das setas. |
-| `iconOnly (Previous/Next)` | `boolean` | `false` | Só a seta, quadrada (`size="icon"`); o `label` continua como nome acessível. |
-| `iconClassName (Previous/Next)` | `string` | | Classe do svg da seta, para a escala densa (`size-3.5`). |
+| `page` | `number` | | Número usado como conteúdo, quando `children` não é informado, e no nome acessível “Página N”. |
+| `isActive` | `boolean` | `false` | Marca a página atual com `aria-current="page"` e tratamento `outline`. |
+| `href` | `string` | | Renderiza um `<a>`. Sem `href`, o componente usa `<button>` e aceita `onClick` e `disabled`. |
+| `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | Escala herdada de `Button`. A largura mínima cresce para acomodar números longos. |
+
+## Propriedades de PaginationPrevious e PaginationNext
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | `'Página anterior'` ou `'Próxima página'` | Nome acessível e texto visível da ação. |
+| `iconOnly` | `boolean` | `false` | Exibe somente a seta; `label` continua disponível para leitura assistiva. |
+| `iconClassName` | `string` | | Classes aplicadas ao ícone da seta. |

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

@@ -1,6 +1,8 @@
-## Estrutura
+## Painel ancorado
 
-PopoverHeader agrupa título e descrição; o corpo é livre (form curto, detalhes). Superfície bg-popover — a elevação da casa.
+Use `Popover` para apresentar conteúdo livre junto a um gatilho, sem abrir um modal.
+`PopoverHeader` agrupa título e descrição; o restante do painel aceita formulários curtos ou
+detalhes.
 
 ```tsx preview
 <Popover>
@@ -23,7 +25,7 @@ PopoverHeader agrupa título e descrição; o corpo é livre (form curto, detalh
 
 ## Alinhamento
 
-align posiciona o painel em relação ao gatilho; sideOffset afasta. O padrão (center) serve pra quase tudo.
+`align` posiciona o painel em relação ao gatilho e `sideOffset` define a distância entre eles.
 
 ```tsx preview
 <Popover>
@@ -40,10 +42,22 @@ align posiciona o painel em relação ao gatilho; sideOffset afasta. O padrão (
 </Popover>
 ```
 
-## Props
+## Propriedades de Popover
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `PopoverContent.align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
-| `PopoverContent.sideOffset` | `number` | `4` | Distância (px) entre gatilho e painel. |
-| `Popover.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra fechar por código depois de salvar. |
+| `open` | `boolean` | | Estado no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
+
+## Propriedades de PopoverAnchor
+
+`PopoverAnchor` posiciona o painel em relação a um elemento que não é o gatilho — útil quando o
+clique acontece num item de linha, mas o painel deve alinhar-se ao contêiner. Aceita `asChild` para
+não introduzir um nó extra; sem ele, o `PopoverTrigger` é a âncora.
+
+## Propriedades de PopoverContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
+| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |

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

@@ -1,6 +1,7 @@
-## Básico
+## Progresso determinado
 
-value vai de 0 a 100 — o preenchimento anima a cada mudança. Sem value (ou null) a barra fica vazia.
+Use `Progress` quando a tarefa informar uma porcentagem de conclusão. `value` aceita valores de 0 a
+100 e anima o preenchimento a cada mudança. Sem valor, a barra permanece vazia.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-2">
@@ -14,7 +15,8 @@ value vai de 0 a 100 — o preenchimento anima a cada mudança. Sem value (ou nu
 
 ## Controlado
 
-Guarde o value no estado e atualize conforme a tarefa avança — aqui cada clique soma um passo na sincronização do workspace Empresa X.
+Controle `value` externamente quando o progresso acompanhar uma tarefa em andamento. No exemplo,
+cada clique avança uma etapa da sincronização.
 
 ```tsx preview col
 const [step, setStep] = useState(40)
@@ -38,32 +40,29 @@ render(
 )
 ```
 
-## Altura e cor
+## Altura e contexto
 
-className compõe sobre o padrão: ajuste a altura no Progress e tinja o preenchimento mirando o slot do indicador (&_[data-slot=progress-indicator]) para sinalizar bom/atenção.
+`context` diz o que o andamento comunica — `success` para meta atingida, `warning` ou `danger`
+para atenção — e tinge trilha e preenchimento com a família semântica. `className` compõe sobre o
+padrão para ajustar a altura.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-4">
   <div className="space-y-1.5">
     <span className="text-sm">Cobertura de testes</span>
-    <Progress
-      value={92}
-      className="h-1.5 [&_[data-slot=progress-indicator]]:bg-emerald-500"
-    />
+    <Progress value={92} context="success" className="h-1.5" />
   </div>
   <div className="space-y-1.5">
     <span className="text-sm">Skills cobertas pelo revisor</span>
-    <Progress
-      value={45}
-      className="h-3 [&_[data-slot=progress-indicator]]:bg-amber-500"
-    />
+    <Progress value={45} context="warning" className="h-3" />
   </div>
 </div>
 ```
 
-## Props
+## Propriedades de Progress
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
-| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3) ou tinja o indicador via [&_[data-slot=progress-indicator]]:bg-*. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | O que o andamento comunica; tinge trilha e preenchimento pela família `--context-*`. |
+| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3). |

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

@@ -4,8 +4,8 @@ title: Filas
 
 # Filas
 
-Action pesada não segura o request: marcada como background, ela é enfileirada e processada
-fora da linha, e o cliente acompanha por um handle. O contrato é o `QueueAdapter`.
+Use uma action em background quando a operação não puder manter a requisição aberta. O
+`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhamento pelo cliente.
 
 ## O contrato
 
@@ -44,7 +44,7 @@ const queue = bullmqQueue({ queue: new Queue('opus', { connection: { host: 'loca
 ```
 
 Redis-backed (durável, entre-processos, retries). Peers opcionais (`bullmq`, `ioredis`) só
-pra quem usa o driver.
+para quem usa o driver.
 
 ## No runtime
 
@@ -82,7 +82,7 @@ Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` cust
 é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
 envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
 
-## Limites (por enquanto)
+## Limites atuais
 
-Driver hoje: `bullmq` (Redis). In-memory pra dev e outros backends (SQS, pg-boss…) entram
+Driver hoje: `bullmq` (Redis). In-memory para dev e outros backends (SQS, pg-boss…) entram
 por reincidência.