@softize/opus 12.11.0 → 13.0.0

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,30 @@ 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 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/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(
@@ -65,9 +64,44 @@ render(
 )
 ```
 
-## Props
+## Estados integrais
 
-| Prop          | Tipo        | Default     | Descrição                                                                                       |
+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.
+
+```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 +109,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,16 @@ 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 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)
@@ -61,9 +63,9 @@ className compõe sobre o padrão: ajuste a altura no Progress e tinja o preench
 </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-*. |

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.

package/src/ui/docs/content/radio-group.md

@@ -1,6 +1,8 @@
-## Básico
+## Escolha única
 
-Cada RadioGroupItem tem um value; o item escolhido é o value do RadioGroup. defaultValue deixa o estado com o componente. Pareie cada item com um Label (htmlFor↔id).
+Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Cada
+`RadioGroupItem` declara um `value` e deve estar associado a um `Label`. `defaultValue` define a
+opção inicial no modo não controlado.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="balanced">
@@ -21,7 +23,7 @@ Cada RadioGroupItem tem um value; o item escolhido é o value do RadioGroup. def
 
 ## Controlado
 
-value + onValueChange no RadioGroup levam o estado pra fora — o padrão pra escolher quem recebe o handoff de uma task.
+Use `value` e `onValueChange` quando outro estado da aplicação também precisar acompanhar a escolha.
 
 ```tsx preview col-start
 const [agent, setAgent] = useState('reviewer')
@@ -46,7 +48,8 @@ render(
 
 ## Item desabilitado
 
-disabled num RadioGroupItem esmaece e tira a opção da escolha; o Label em par esmaece junto (peer-disabled). Pra bloquear o grupo inteiro, ponha disabled no RadioGroup.
+`disabled` em `RadioGroupItem` bloqueia somente aquela opção e atualiza o `Label` associado. Para
+bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="empresa-x-web">
@@ -65,13 +68,18 @@ disabled num RadioGroupItem esmaece e tira a opção da escolha; o Label em par
 </RadioGroup>
 ```
 
-## Props
+## Propriedades de RadioGroup
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value (RadioGroup)` | `string` | | A opção escolhida, no modo controlado — pareie com onValueChange. |
-| `onValueChange (RadioGroup)` | `(value: string) => void` | | Chamado quando o usuário escolhe outra opção. |
-| `defaultValue (RadioGroup)` | `string` | | A opção inicial no modo não controlado. |
-| `disabled (RadioGroup)` | `boolean` | `false` | Bloqueia e esmaece o grupo inteiro. |
-| `value (RadioGroupItem)` | `string` | | O valor que este item representa — vira o value do grupo quando escolhido. |
-| `disabled (RadioGroupItem)` | `boolean` | `false` | Esmaece e tira só este item da escolha — o Label em par esmaece junto. |
+| `value` | `string` | | Opção escolhida no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa escolhe outra opção. |
+| `defaultValue` | `string` | | Opção inicial no modo não controlado. |
+| `disabled` | `boolean` | `false` | Desabilita todo o grupo. |
+
+## Propriedades de RadioGroupItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Valor que o item atribui ao grupo quando selecionado. |
+| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` associado acompanha o estado. |

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

@@ -1,6 +1,8 @@
-## O pathname É o estado
+## A URL como estado
 
-Roteamento history-based, sem dependência: `pushState` + `popstate` + `useSyncExternalStore`. Páginas orientadas a URL — deep-link, reload e o botão voltar funcionam de graça, porque não há um segundo lugar guardando "onde estou".
+Use o router do Opus em aplicações pequenas que precisam reagir à URL sem uma tabela de rotas.
+`pushState`, `popstate` e `useSyncExternalStore` preservam links diretos, recarregamento e o botão
+Voltar sem manter uma segunda cópia do destino atual.
 
 ```tsx
 import { navigate, useSegments } from '@softize/opus/ui/react'
@@ -12,9 +14,10 @@ function App() {
 }
 ```
 
-## O escopo é pequeno de propósito
+## Limite do router
 
-Não há tabela de rotas, `<Route>`, params tipados nem carregamento de dados. Isto é a **leitura reativa da URL + um `navigate`** — quem decide o que renderizar é o app, com `if`/`switch` sobre os segmentos.
+O router oferece leitura reativa da URL e `navigate`; o aplicativo decide o que renderizar. Ele não
+inclui tabela de rotas, parâmetros tipados nem carregamento de dados.
 
 A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:postId`), params tipados ou data loaders, o caso pede uma biblioteca de rotas, não isto. Um app de back-office com uma dúzia de destinos quase nunca precisa.
 
@@ -27,13 +30,15 @@ A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:post
 | `useSearchParams()` | A querystring reativa — o lar natural do estado interno de uma seção (qual relatório está aberto, o recorte de uma lista). |
 | `navigate(path, opts?)` | `pushState` + notifica. `{ replace: true }` troca a entrada corrente. |
 
-## Dois detalhes que custaram caro nas cópias à mão
+## Comportamentos preservados
 
 **Destino igual é no-op.** `navigate` resolve o destino com `new URL` e compara o `href` inteiro — não faz nada se você já está exatamente lá. Sem isso, clicar duas vezes no mesmo item do menu empilha entradas idênticas e o botão "voltar" não sai do lugar.
 
 Comparar strings cruas parece bastar e não basta, em duas frentes. O **hash**: estando em `/a#secao`, `navigate('/a')` pareceria destino repetido e a âncora nunca sairia da URL. E o **encoding**: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então a comparação crua nunca casa e cada clique empilha — bem no caso pt-BR, e no ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
 
-**A notificação é um evento, não uma lista.** `pushState` não dispara `popstate`, então `navigate` dispara — e é `window.dispatchEvent`, não um `Set` de assinantes em escopo de módulo. A diferença aparece nas bordas: código que ainda escuta `popstate` na unha continua acompanhando, e duas cópias do pacote no `node_modules` continuam se enxergando. Uma lista privada mora numa instância do bundle; o `window` é um só.
+**A notificação usa um evento do navegador.** Como `pushState` não dispara `popstate`, `navigate`
+emite o evento explicitamente. Isso mantém listeners existentes e cópias diferentes do pacote
+sincronizados pela mesma janela.
 
 **`useSyncExternalStore`, não `useState`.** Ler `window.location` dentro de `useState`/`useEffect` sofre *tearing* no modo concurrent: dois componentes podem renderizar o mesmo commit com URLs diferentes. As cópias que este módulo substituiu faziam isso.
 

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

@@ -4,9 +4,8 @@ title: Agendador
 
 # Agendador
 
-Rodar uma action no tempo — cron ou intervalo. Você declara o schedule (qual action, quando)
-e o runtime dispara na hora, com provenance `schedule` (rastreável no audit como qualquer
-execução). O contrato é o `SchedulerAdapter`.
+Use um schedule para executar uma action por cron ou intervalo. O `SchedulerAdapter` registra o
+agendamento e o runtime executa a action com provenance `schedule`, preservando sua rastreabilidade.
 
 ## O contrato
 
@@ -59,8 +58,8 @@ const runtime = createRuntime({
 O runtime registra os schedules do domínio no `start()` e chama a action quando o tempo bate
 — nada de disparar no handler.
 
-## Limites (por enquanto)
+## Limites atuais
 
-Driver hoje: `node-cron` (in-process — some se o processo cair; num cluster, cada nó
+Driver hoje: `node-cron` (in-process — some se o processo cair; em um cluster, cada nó
 dispararia). Backends duráveis/distribuídos (BullMQ repeatable, Temporal…) entram por
 reincidência.

package/src/ui/docs/content/scroll-area.md

@@ -4,7 +4,7 @@ Dê a altura ao ScrollArea (h-48) e ponha o conteúdo dentro — a barra vertica
 
 ```tsx preview col
 const sessions = [
-  { id: 'empresa-x-1842', title: 'Migrar billing pro novo schema', agent: 'developer' },
+  { id: 'empresa-x-1842', title: 'Migrar billing para o novo schema', agent: 'developer' },
   { id: 'empresa-x-1839', title: 'Revisar handoff do checkout', agent: 'reviewer' },
   { id: 'empresa-x-1835', title: 'Redesenhar o painel de rotas', agent: 'designer' },
   { id: 'empresa-x-1830', title: 'Corrigir flaky no teste de webhook', agent: 'developer' },
@@ -30,7 +30,7 @@ render(
 
 ## Trilho horizontal
 
-Pra rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo numa linha que não quebra (flex + w-max).
+Para rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo em uma linha que não quebra (flex + w-max).
 
 ```tsx preview col
 const skills = ['implement-opus-change', 'create-opus-action', 'test-opus-action', 'build-opus-ui', 'upgrade-opus']
@@ -80,10 +80,15 @@ render(
 )
 ```
 
-## Props
+## Propriedades de ScrollArea
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `className (ScrollArea)` | `string` | | Onde a altura (h-48) ou a largura mora — é o que define a janela rolável. Sem dimensão, não há o que rolar. |
-| `children (ScrollArea)` | `React.ReactNode` | | O conteúdo da janela. Inclua um <ScrollBar orientation="horizontal" /> entre os filhos pra habilitar a rolagem lateral. |
-| `orientation (ScrollBar)` | `'vertical' \| 'horizontal'` | `'vertical'` | A direção da barra. A vertical já vem embutida; adicione a horizontal só quando precisar. |
+| `className` | `string` | | Classes que definem as dimensões da janela rolável. Sem uma dimensão limitada, não há conteúdo a recortar. |
+| `children` | `React.ReactNode` | | Conteúdo da janela, incluindo uma `ScrollBar` horizontal quando necessária. |
+
+## Propriedades de ScrollBar
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Direção da barra. A barra vertical já faz parte de `ScrollArea`. |