@softize/opus 8.6.6

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

@@ -0,0 +1,44 @@
+---
+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.
+
+## Montar
+
+```ts
+import { createOpusMcpServer } from '@softize/opus/mcp'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const server = createOpusMcpServer(runtime, {
+  name: 'meu-app',
+  // Valida a identidade da requisição (IdP) → contexto do runtime. Sem isso, roda anônimo
+  // (o `can` nega → só actions públicas). Com isso, o agente age COMO O USUÁRIO.
+  resolveContext: async (extra) => auth.resolveFromMcp(extra),
+})
+
+await server.connect(new StdioServerTransport()) // local; HTTP/SSE pra 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
+
+- **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.
+
+Mesmas tools, transportes diferentes.
+
+## 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.

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

@@ -0,0 +1,114 @@
+## Menu de ações
+
+Ícone à esquerda, atalho à direita (MenuShortcut), separador antes da zona perigosa e variant destructive na ação que destrói.
+
+```tsx preview
+<Menu>
+  <MenuTrigger asChild>
+    <Button variant="outline">Ações <ChevronDown /></Button>
+  </MenuTrigger>
+  <MenuContent align="start">
+    <MenuItem><Pencil /> Editar <MenuShortcut>⌘E</MenuShortcut></MenuItem>
+    <MenuItem><Copy /> Duplicar</MenuItem>
+    <MenuSeparator />
+    <MenuItem variant="destructive"><Trash2 /> Excluir</MenuItem>
+  </MenuContent>
+</Menu>
+```
+
+## Contexto: clique direito
+
+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.
+
+```tsx preview
+const [pos, setPos] = useState(null)
+
+render(
+  <div>
+    <div
+      onContextMenu={(e) => {
+        e.preventDefault()
+        setPos({ x: e.clientX, y: e.clientY })
+      }}
+      className="flex h-28 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground select-none"
+    >
+      clique direito aqui
+    </div>
+    <Menu open={pos !== null} onOpenChange={(open) => { if (!open) setPos(null) }}>
+      <MenuTrigger asChild>
+        <span style={{ position: 'fixed', left: pos?.x ?? 0, top: pos?.y ?? 0 }} />
+      </MenuTrigger>
+      <MenuContent align="start">
+        <MenuItem><Pencil /> Renomear</MenuItem>
+        <MenuItem><Copy /> Duplicar</MenuItem>
+        <MenuSeparator />
+        <MenuItem variant="destructive"><Trash2 /> Excluir</MenuItem>
+      </MenuContent>
+    </Menu>
+  </div>,
+)
+```
+
+## Seleção: checkbox e radio
+
+CheckboxItem pra liga/desliga, RadioGroup pra escolha exclusiva — estado fica no consumidor (controlado).
+
+```tsx preview
+const [showArchived, setShowArchived] = useState(false)
+const [order, setOrder] = useState('recent')
+
+render(
+  <Menu>
+    <MenuTrigger asChild>
+      <Button variant="outline">Exibição <ChevronDown /></Button>
+    </MenuTrigger>
+    <MenuContent align="start">
+      <MenuLabel>Sessões</MenuLabel>
+      <MenuCheckboxItem checked={showArchived} onCheckedChange={setShowArchived}>
+        Mostrar arquivadas
+      </MenuCheckboxItem>
+      <MenuSeparator />
+      <MenuLabel>Ordenar por</MenuLabel>
+      <MenuRadioGroup value={order} onValueChange={setOrder}>
+        <MenuRadioItem value="recent">Mais recentes</MenuRadioItem>
+        <MenuRadioItem value="name">Nome</MenuRadioItem>
+      </MenuRadioGroup>
+    </MenuContent>
+  </Menu>,
+)
+```
+
+## Submenu e inset
+
+MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
+
+```tsx preview
+<Menu>
+  <MenuTrigger asChild>
+    <Button variant="outline">Sessão <ChevronDown /></Button>
+  </MenuTrigger>
+  <MenuContent align="start">
+    <MenuItem><ExternalLink /> Abrir preview</MenuItem>
+    <MenuSub>
+      <MenuSubTrigger><ArrowDownAZ /> Mover pra</MenuSubTrigger>
+      <MenuSubContent>
+        <MenuItem>Empresa X</MenuItem>
+        <MenuItem>Softize</MenuItem>
+      </MenuSubContent>
+    </MenuSub>
+    <MenuItem inset>Renomear</MenuItem>
+  </MenuContent>
+</Menu>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `MenuItem.variant` | `'default' \| 'destructive'` | `'default'` | destructive tonaliza texto e foco em vermelho — só pra ação que destrói. |
+| `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. |

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

@@ -0,0 +1,83 @@
+---
+title: Microcopy
+---
+
+# Microcopy
+
+Código em inglês; o que humano lê (UI, comentário, doc) em pt-BR. Frases começam com
+maiúscula e terminam com ponto; labels curtos em sentence case, sem ponto. **Esta página
+é a fonte** — a skill `code-style` aponta pra cá (regra duplicada em vez de apontada é
+defeito).
+
+## Língua por camada
+
+> Regra dura — não tem caso a caso.
+
+| Camada | Língua |
+|---|---|
+| Identificadores de código (vars, funções, tipos, arquivos, dirs, domínios) | Inglês |
+| Nomes de action / rota | Inglês (`resource.verb`) |
+| Colunas e tabelas de banco | Inglês (snake_case) |
+| Valores de código (enums, status, chaves de dict) | Inglês — mesmo em exemplos e fixtures (`active`, não `ativo`); a UI mostra o label pt |
+| Texto de UI visível (labels, headings, botões, placeholders, mensagens) | pt-BR |
+| Comentários e docs (`.md`) | pt-BR |
+
+## Frase vs label
+
+> Frase (mensagem, descrição, tooltip, help): maiúscula no início, ponto no fim. Label
+> (botão, heading, item de menu, chip): sentence case, sem ponto.
+
+| Tipo | Assim | Assim não |
+|---|---|---|
+| Frase | Opus não inicializado. | ~~opus nao inicializado~~ |
+| Frase | O Multica não respondeu — tente de novo. | ~~ERRO: request failed (500)~~ |
+| Label | Publicar | ~~PUBLICAR~~ |
+| Label | Nova sessão | ~~Nova sessão.~~ |
+| Placeholder | Selecione um cliente… | ~~Selecionar~~ · ~~digite o nome…~~ |
+
+## As regras que mais pegam
+
+> Erros recorrentes de revisão — atenção redobrada nestes.
+
+- **Maiúscula é ortografia, não estilo.** Toda frase começa com maiúscula — em UI,
+  hint/help **e comentário de código** — e nome próprio idem (Engineer, Multica, GitHub).
+  Vale com interpolação: mensagem que começaria com valor ganha um artigo na frente
+  (`O workspace '${slug}' não existe…`).
+- **Frase fluida, não telegrama.** Símbolo não é conector: nada de `—`/`+`/`≈` amarrando
+  ideias em label ou help. `Staff — acesso ao back-office + todos os workspaces` vira
+  label `Staff` + help `Tem acesso ao back-office e a todos os workspaces.`.
+- **"Opus" e "Softize" são nomes próprios.** Em prosa, maiúscula (`o Opus`, `a Softize`);
+  os tokens técnicos ficam minúsculos: `opus check`, `@softize/opus`, `opus.json`,
+  `softize.com.br`. É o nome → maiúscula; é código → minúscula.
+- **Abreviação é último caso.** Por extenso: `mínimo`, `máximo`, `configuração`.
+  `Config indisponível.` é duplamente errado (seco E abreviado): `A configuração não
+  carregou.`. `Ex.:` em placeholder é tolerado (com `E` maiúsculo).
+- **Placeholder de seleção segue UM padrão** (select simples, buscável, múltiplo):
+  `Selecione <artigo> <coisa>…` — com `…` (o caractere único), nunca o genérico
+  `Selecionar`. Declare no contrato (`fields.<campo>.placeholder`) — o default do
+  componente é rede de segurança, não estilo; dois pickers na mesma tela com padrões
+  diferentes é defeito.
+- **Nada de maiúsculo deliberado.** Sem ALL-CAPS — nem a classe `uppercase` — em labels,
+  headers ou badges.
+- **Exemplos são neutros e duráveis.** Nada de cliente real ou com cara de real: use
+  Empresa X / Empresa Y (`contato@empresa-x.com.br`). Exemplo "de verdade" envelhece,
+  vaza contexto e vira dívida.
+
+## Tom
+
+> Fale com o usuário, não com o log.
+
+- **Calmo e informativo, não alarmista.** "Indisponível" em vez de "ERRO"/"FALHOU".
+  Não culpe o usuário.
+- **Orientado à ação.** Quando dá, diga o próximo passo: `Inicie o ambiente`,
+  `Crie a primeira acima`.
+- **Conciso, mas natural — não telegráfico.** Prefira a forma completa do verbo a um
+  corte abrupto. O meio-termo é a régua: nem seco demais (`rode no projeto`) nem manual
+  técnico (jargão de arquitetura num help).
+- **Explique pelo efeito, não pelo mecanismo.** Se precisou citar sistema interno pra
+  explicar (`o push sobrescreve o runtime`), reescreva pelo que acontece pro usuário
+  (`os agentes deste workspace passam a usar esta skill`). Mecanismo é doc/comentário,
+  não tooltip.
+- **Nada de endpoint, status ou stack na tela** — detalhe técnico vai pro console/log.
+- **Termos do produto** (sessão, ambiente, cliente, agente), não do código. E o mesmo
+  termo sempre: se a UI fala "cliente", nenhum label diz "client".

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

@@ -0,0 +1,34 @@
+## Esqueleto de página
+
+O que toda página do back-office repete, num pattern só: `<main>` + container de largura cheia (o caso comum; `className="max-w-5xl"` estreita e centra) + header com título, descrição e a ação à direita. O conteúdo é children, sem nada imposto. Presentacional de propósito — uma página agrega N fontes; o que é action-driven (listas, forms) mora dentro.
+
+```tsx preview col
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    <Page
+      title="Workspaces"
+      count={3}
+      actions={
+        <Button>
+          <Plus /> Novo workspace
+        </Button>
+      }
+    >
+      <div className="rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
+        O conteúdo da página (tabela, cards, grid…).
+      </div>
+    </Page>
+  </div>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `title` | `string` | | O h1 da página. |
+| `count` | `number` | | Total de itens ao lado do título (mono, esmaecido). |
+| `description` | `ReactNode` | | Linha de contexto sob o título (ex.: "N no total · X ativos"). |
+| `actions` | `ReactNode` | | Ação à direita do header — em geral o botão de criar. |
+| `className` | `string` | largura cheia | Classes do container (`max-w-5xl` estreita e centra). |
+| `children` | `ReactNode` | | O conteúdo — espaçamento e diagramação são seus. |

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

@@ -0,0 +1,99 @@
+## Básico
+
+É composição: Pagination embrulha PaginationContent, e cada PaginationItem segura um link. isActive no PaginationLink marca a página atual (vira outline).
+
+```tsx preview
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">3</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+## 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.
+
+```tsx preview
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        8
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">9</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+## Controlado
+
+Os links são <a> — sem href, vire onClick e guarde a página no estado. Aqui a barra pagina os repositórios do workspace Empresa X.
+
+```tsx preview col
+const [page, setPage] = useState(2)
+const pages = [1, 2, 3]
+
+render(
+  <Pagination>
+    <PaginationContent>
+      <PaginationItem>
+        <PaginationPrevious
+          onClick={() => setPage((p) => Math.max(1, p - 1))}
+        />
+      </PaginationItem>
+      {pages.map((n) => (
+        <PaginationItem key={n}>
+          <PaginationLink isActive={n === page} onClick={() => setPage(n)}>
+            {n}
+          </PaginationLink>
+        </PaginationItem>
+      ))}
+      <PaginationItem>
+        <PaginationNext
+          onClick={() => setPage((p) => Math.min(pages.length, p + 1))}
+        />
+      </PaginationItem>
+    </PaginationContent>
+  </Pagination>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `isActive (PaginationLink)` | `boolean` | `false` | Marca a página atual: vira outline e ganha aria-current="page". Os demais ficam ghost. |
+| `size (PaginationLink)` | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'icon'` | Tamanho do link, herdado do Button. Previous/Next já forçam default pra caber o texto. |
+| `href (PaginationLink)` | `string` | | Cada link é um <a>: passe href pra navegação real, ou use onClick no modo controlado. |

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

@@ -0,0 +1,49 @@
+## Estrutura
+
+PopoverHeader agrupa título e descrição; o corpo é livre (form curto, detalhes). Superfície bg-popover — a elevação da casa.
+
+```tsx preview
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Renomear sessão</Button>
+  </PopoverTrigger>
+  <PopoverContent align="start">
+    <PopoverHeader>
+      <PopoverTitle>Renomear</PopoverTitle>
+      <PopoverDescription>O slug técnico não muda — só o título.</PopoverDescription>
+    </PopoverHeader>
+    <div className="mt-3 space-y-2">
+      <Label htmlFor="pop-titulo">Título</Label>
+      <Input id="pop-titulo" defaultValue="Onboarding do faturamento" />
+      <Button size="sm" className="w-full">Salvar</Button>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+## Alinhamento
+
+align posiciona o painel em relação ao gatilho; sideOffset afasta. O padrão (center) serve pra quase tudo.
+
+```tsx preview
+<Popover>
+  <PopoverTrigger asChild><Button variant="ghost">start</Button></PopoverTrigger>
+  <PopoverContent align="start" className="w-56">
+    <PopoverDescription>Alinhado à borda esquerda do gatilho.</PopoverDescription>
+  </PopoverContent>
+</Popover>
+<Popover>
+  <PopoverTrigger asChild><Button variant="ghost">end</Button></PopoverTrigger>
+  <PopoverContent align="end" className="w-56">
+    <PopoverDescription>Alinhado à borda direita do gatilho.</PopoverDescription>
+  </PopoverContent>
+</Popover>
+```
+
+## Props
+
+| Prop | Tipo | Default | 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. |

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

@@ -0,0 +1,69 @@
+## Básico
+
+value vai de 0 a 100 — o preenchimento anima a cada mudança. Sem value (ou null) a barra fica vazia.
+
+```tsx preview col
+<div className="w-full max-w-sm space-y-2">
+  <div className="flex items-center justify-between text-sm">
+    <span>opus check</span>
+    <span className="text-muted-foreground">65%</span>
+  </div>
+  <Progress value={65} />
+</div>
+```
+
+## 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.
+
+```tsx preview col
+const [step, setStep] = useState(40)
+const advance = (): void => setStep((prev) => Math.min(prev + 20, 100))
+
+render(
+  <div className="w-full max-w-sm space-y-3">
+    <div className="flex items-center justify-between text-sm">
+      <span>Sincronizar Empresa X</span>
+      <span className="text-muted-foreground">{step}%</span>
+    </div>
+    <Progress value={step} />
+    <button
+      type="button"
+      onClick={advance}
+      className="rounded-md border px-3 py-1.5 text-sm hover:bg-muted"
+    >
+      Avançar etapa
+    </button>
+  </div>,
+)
+```
+
+## Altura e cor
+
+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.
+
+```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"
+    />
+  </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"
+    />
+  </div>
+</div>
+```
+
+## Props
+
+| Prop | Tipo | Default | 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

@@ -0,0 +1,62 @@
+---
+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`.
+
+## O contrato
+
+```ts
+interface QueueAdapter {
+  enqueue(spec: JobSpec): Promise<JobHandle>
+  status(jobId: string): Promise<JobHandle | null>
+  cancel(jobId: string): Promise<boolean>
+  subscribe?(jobId: string, listener: (h: JobHandle) => void): Unsubscribe
+}
+
+interface JobHandle<T = unknown> {
+  jobId: string
+  action: string
+  status: 'queued' | 'running' | 'done' | 'failed' | 'cancelled'
+  progress?: { percent?: number; message?: string }
+  data?: T
+  error?: ActionError
+  attempts: number
+}
+```
+
+O core monta o `JobSpec` (action, input, ctx, retry/priority/timeout); o adapter persiste e
+processa.
+
+## Driver
+
+```ts
+import { Queue } from 'bullmq'
+import { bullmqQueue } from '@softize/opus/queue/bullmq'
+
+const queue = bullmqQueue({ queue: new Queue('opus', { connection: { host: 'localhost' } }) })
+```
+
+Redis-backed (durável, entre-processos, retries). Peers opcionais (`bullmq`, `ioredis`) só
+pra quem usa o driver.
+
+## No runtime
+
+```ts
+const runtime = createRuntime({
+  // …server/data…
+  queue,
+})
+```
+
+A action declara `background: true` (+ retry/priority no contrato); chamá-la devolve um
+`JobHandle` em vez do resultado, e o cliente pola `status(jobId)` (ou `subscribe`) até
+`done`/`failed`.
+
+## Limites (por enquanto)
+
+Driver hoje: `bullmq` (Redis). In-memory pra dev e outros backends (SQS, pg-boss…) entram
+por reincidência.

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

@@ -0,0 +1,77 @@
+## Básico
+
+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).
+
+```tsx preview col-start
+<RadioGroup defaultValue="balanced">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="speed" value="speed" />
+    <Label htmlFor="speed">Priorizar velocidade</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="balanced" value="balanced" />
+    <Label htmlFor="balanced">Equilibrado</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="thorough" value="thorough" />
+    <Label htmlFor="thorough">Priorizar profundidade</Label>
+  </div>
+</RadioGroup>
+```
+
+## Controlado
+
+value + onValueChange no RadioGroup levam o estado pra fora — o padrão pra escolher quem recebe o handoff de uma task.
+
+```tsx preview col-start
+const [agent, setAgent] = useState('reviewer')
+
+render(
+  <RadioGroup value={agent} onValueChange={setAgent}>
+    <div className="flex items-center gap-2">
+      <RadioGroupItem id="developer" value="developer" />
+      <Label htmlFor="developer">developer</Label>
+    </div>
+    <div className="flex items-center gap-2">
+      <RadioGroupItem id="reviewer" value="reviewer" />
+      <Label htmlFor="reviewer">reviewer</Label>
+    </div>
+    <div className="flex items-center gap-2">
+      <RadioGroupItem id="designer" value="designer" />
+      <Label htmlFor="designer">designer</Label>
+    </div>
+  </RadioGroup>,
+)
+```
+
+## 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.
+
+```tsx preview col-start
+<RadioGroup defaultValue="empresa-x-web">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="empresa-x-web" value="empresa-x-web" />
+    <Label htmlFor="empresa-x-web">empresa-x-web</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="empresa-x-api" value="empresa-x-api" />
+    <Label htmlFor="empresa-x-api">empresa-x-api</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="empresa-x-mobile" value="empresa-x-mobile" disabled />
+    <Label htmlFor="empresa-x-mobile">empresa-x-mobile (sem worktree)</Label>
+  </div>
+</RadioGroup>
+```
+
+## Props
+
+| Prop | Tipo | Default | 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. |