@softize/opus 8.6.6

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

@@ -0,0 +1,85 @@
+## Básico
+
+Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext pra navegar. As setas ficam fora do trilho (-left-12/-right-12), então reserve a margem lateral no entorno.
+
+```tsx preview
+<Carousel className="mx-12 w-full max-w-xs">
+  <CarouselContent>
+    <CarouselItem>
+      <div className="flex h-32 items-center justify-center rounded-lg border bg-card text-sm">
+        Sessão #128
+      </div>
+    </CarouselItem>
+    <CarouselItem>
+      <div className="flex h-32 items-center justify-center rounded-lg border bg-card text-sm">
+        Sessão #131
+      </div>
+    </CarouselItem>
+    <CarouselItem>
+      <div className="flex h-32 items-center justify-center rounded-lg border bg-card text-sm">
+        Sessão #134
+      </div>
+    </CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Vários por vista
+
+O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três slides por vez. Bom pra galeria de workspaces ou repositórios.
+
+```tsx preview
+<Carousel className="mx-12 w-full max-w-sm" opts={{ align: 'start' }}>
+  <CarouselContent>
+    {['Sessão #128', 'Sessão #131', 'Sessão #134', 'Sessão #137', 'Sessão #140'].map((session) => (
+      <CarouselItem key={session} className="basis-1/3">
+        <div className="flex h-24 items-center justify-center rounded-lg border bg-card text-xs">
+          {session}
+        </div>
+      </CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Vertical
+
+orientation=vertical empilha os slides; as setas migram pra cima e pra baixo (-top-12/-bottom-12). Dê uma altura ao CarouselContent pra delimitar a vista.
+
+```tsx preview
+<Carousel className="w-full max-w-xs" orientation="vertical">
+  <CarouselContent className="h-48">
+    <CarouselItem>
+      <div className="flex h-24 items-center justify-center rounded-lg border bg-card text-sm">
+        developer
+      </div>
+    </CarouselItem>
+    <CarouselItem>
+      <div className="flex h-24 items-center justify-center rounded-lg border bg-card text-sm">
+        reviewer
+      </div>
+    </CarouselItem>
+    <CarouselItem>
+      <div className="flex h-24 items-center justify-center rounded-lg border bg-card text-sm">
+        designer
+      </div>
+    </CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `orientation (Carousel)` | `'horizontal' \| 'vertical'` | `'horizontal'` | Eixo do deslize — vertical empilha os slides e gira as setas pro topo/base. |
+| `opts (Carousel)` | `CarouselOptions` | | Opções do embla (ex.: { loop: true }, { align: "start" }). Repassadas direto pro motor. |
+| `setApi (Carousel)` | `(api: CarouselApi) => void` | | Recebe a instância do embla pra controlar de fora (scrollTo, ler o slide ativo). |
+| `plugins (Carousel)` | `CarouselPlugin` | | Plugins do embla (ex.: autoplay) anexados ao carousel. |
+| `className (CarouselItem)` | `string` | | O basis decide quantos slides cabem na vista (basis-full, basis-1/2, basis-1/3). |

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

@@ -0,0 +1,69 @@
+## Básico
+
+Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por dentro (estado, loading, auto-scroll; **Enter** envia, **Shift+Enter** quebra linha) — a inteligência vem da prop `send`. O `greeting` é o estado vazio (centrado; some quando a conversa começa e NÃO entra no transcript). Dê altura ao container.
+
+```tsx preview
+<div className="h-96 rounded-lg border">
+  <Chat
+    greeting="Oi! Sou o assistente. Pergunte algo."
+    send={async (messages) => {
+      await new Promise((r) => setTimeout(r, 500))
+      const last = messages[messages.length - 1]
+      return `Você disse: "${last.content}". (Num app real, aqui rodaria o agente.)`
+    }}
+  />
+</div>
+```
+
+## O backend (o agente)
+
+O `send` posta a conversa no seu endpoint, que resolve o usuário e roda o agente sobre as actions `ai:enabled` — **como o usuário logado**:
+
+```ts
+// Rota do app (server): recebe { messages }, devolve { reply }.
+async function chatRoute(req) {
+  const base = await auth.resolveContext(req)                 // quem é o usuário
+  const { messages } = req.body
+  const { text } = await runtime.aiFor(base)!.run(messages)   // o agente age nas actions
+  return { reply: text }
+}
+```
+
+```tsx
+// No cliente, o send bate nessa rota:
+<Chat send={async (messages) => (await api.post('/chat', { messages })).reply} />
+```
+
+O modelo só faz o que o usuário pode (`ctx.can`); o que é destrutivo pede `confirm`. Para expor as actions ao agente, marque-as com `ai: { enabled: true }` no contrato — ver o recurso **IA generativa**.
+
+## Streaming — eventos de conversa
+
+O `send` também aceita devolver um **`AsyncIterable<ChatEvent>`** (o protocolo de
+`docs/chat-event-protocol.md`): o texto chega incremental, o tool em uso vira o
+**indicador vivo** (pontinhos + rótulo humano — nunca uma mensagem no transcript) e
+artefatos produzidos na conversa rendem pelo `renderArtifact` do app. O backend liga em
+`runtime.aiFor(base).runStream(...)` e streama por SSE; o `Promise<string>` de sempre
+continua valendo — é o caso degenerado do protocolo.
+
+```tsx preview
+<div className="h-96 rounded-lg border">
+  <Chat
+    greeting="Oi! Pergunte algo — a resposta chega em streaming."
+    send={async function* (messages) {
+      yield { type: 'tool', name: 'query' }
+      await new Promise((r) => setTimeout(r, 600))
+      const last = messages[messages.length - 1]
+      for (const word of `Você disse: "${last.content}".`.split(' ')) {
+        yield { type: 'text', delta: word + ' ' }
+        await new Promise((r) => setTimeout(r, 80))
+      }
+      yield { type: 'artifact', kind: 'url', ref: 'https://opus.softize.com.br', title: 'Um artefato da conversa' }
+      yield { type: 'done', ok: true }
+    }}
+  />
+</div>
+```
+
+Reidratação: passe `initialMessages` com o histórico persistido e troque a `key` do
+componente ao trocar de conversa. O rótulo do indicador é customizável por
+`humanizeTool={(name) => '…'}`.

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

@@ -0,0 +1,75 @@
+## Básico
+
+Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defaultChecked pro modo não controlado.
+
+```tsx preview
+<div className="flex items-center gap-2">
+  <Checkbox id="run-check" defaultChecked />
+  <Label htmlFor="run-check">Rodar opus check antes do handoff</Label>
+</div>
+```
+
+## Controlado
+
+onCheckedChange recebe boolean | 'indeterminate' — compare com true pra guardar um boolean.
+
+```tsx preview
+const [autoReview, setAutoReview] = useState(true)
+
+render(
+  <div className="flex items-center gap-2">
+    <Checkbox
+      id="auto-review"
+      checked={autoReview}
+      onCheckedChange={(v) => setAutoReview(v === true)}
+    />
+    <Label htmlFor="auto-review">Acionar o revisor ao abrir o handoff</Label>
+  </div>,
+)
+```
+
+## Lista de opções
+
+Várias caixas, um estado: o conjunto marcado é a lista de valores — o padrão pra anexar skills a um agente.
+
+```tsx preview col-start
+const [skills, setSkills] = useState(['clean-code', 'test'])
+const toggleSkill = (skill: string): void => {
+  setSkills((prev) => (prev.includes(skill) ? prev.filter((s) => s !== skill) : [...prev, skill]))
+}
+
+render(
+  <>
+    {['clean-code', 'code-style', 'ddd', 'test'].map((skill) => (
+      <div key={skill} className="flex items-center gap-2">
+        <Checkbox id={skill} checked={skills.includes(skill)} onCheckedChange={() => toggleSkill(skill)} />
+        <Label htmlFor={skill}>{skill}</Label>
+      </div>
+    ))}
+  </>,
+)
+```
+
+## Desabilitado
+
+disabled esmaece a caixa e o rótulo em par (peer-disabled no Label) — marcado ou não.
+
+```tsx preview col-start
+<div className="flex items-center gap-2">
+  <Checkbox id="sync-multica" disabled />
+  <Label htmlFor="sync-multica">Sincronizar com o Multica</Label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="opus" disabled defaultChecked />
+  <Label htmlFor="opus">Opus inicializado</Label>
+</div>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `checked` | `boolean \| 'indeterminate'` | | O estado, no modo controlado — parear com onCheckedChange. |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Pra guardar um boolean, compare com true. |
+| `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |

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

@@ -0,0 +1,58 @@
+---
+title: CLI opus
+---
+
+# CLI opus
+
+O Opus traz um CLI que cobre o ciclo: faz o bootstrap, gera artefatos a partir das declarações,
+valida as convenções e expõe o estado vivo pros agentes via MCP.
+
+## Gates
+
+> A régua de entrega: 0 violação antes de qualquer handoff. Rode no CI e antes de commitar.
+
+```bash
+opus check src    # valida as convenções das actions (exit ≠ 0 se violar)
+opus db check     # drift entidade ↔ banco (read-only)
+opus db migrate   # aplica o schema idempotente + drift-check na sequência
+```
+
+## Geração e introspecção
+
+> As declarações (`description` de entidades/actions) são a fonte; o `gen` as projeta. O manifest
+> é um lockfile commitado — diff de manifest é ouro pra review.
+
+```bash
+opus gen              # manifest / openapi / docs / stubs a partir do opus.config.ts
+opus introspect       # modelo da estrutura (actions/reactions/schedules + wiring)
+opus introspect --json
+```
+
+## Bootstrap e templates
+
+> `create` scaffolda um app novo com os pré-requisitos plugados; `setup` é per-app
+> (idempotente, nunca sobrescreve o seu); `add` copia um template do registry pro consumer.
+
+```bash
+opus create meu-app              # app canônico do zero: protocolo + UI + preview + dia zero
+opus create meu-cliente --monorepo  # a RAIZ de um workspace (apps/* + packages/*)
+opus create apps/portal          # dentro de um workspace: só o app (modo detectado)
+opus setup                       # grava opus.json, mantém o bloco do CLAUDE.md e o dia zero
+opus list                        # lista os templates disponíveis
+opus add action-form             # copia um template do registry pro projeto
+```
+
+O esqueleto do `create` versiona com o Opus (sai do mesmo pacote que o SDK que ele
+configura) e nasce com os gates verdes: domínio-exemplo canônico, teste, manifest,
+CI de fábrica e o dev server pronto pro preview do Maestro. Dois modos, por detecção:
+repo standalone (template inteiro) ou **app em monorepo** (dentro de um workspace pnpm:
+só os arquivos do app; o que a raiz precisa ter vira aviso, sem clobber).
+
+## MCP — estado vivo pros agentes
+
+> O server MCP expõe `introspect`/`check`/`create-action`. É como um agente lê a estrutura e cria
+> action no formato canônico sem decorar convenção.
+
+`opus mcp` sobe o server (configurado em `.mcp.json`): o agente consulta a estrutura, roda o
+check e gera o esqueleto de uma action nova pela skill `create-action` — a mesma régua do
+`opus check`, por construção.

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

@@ -0,0 +1,64 @@
+## Básico
+
+CollapsibleTrigger alterna o CollapsibleContent — o Trigger já é o <button>. defaultOpen deixa o estado com o componente.
+
+```tsx preview col
+<Collapsible defaultOpen className="w-full max-w-sm space-y-2">
+  <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted">
+    Repositórios do workspace
+    <ChevronsUpDown className="h-4 w-4 text-muted-foreground" />
+  </CollapsibleTrigger>
+  <CollapsibleContent className="space-y-1 px-3 text-sm text-muted-foreground">
+    <p>empresa-x-api</p>
+    <p>empresa-x-web</p>
+    <p>empresa-x-infra</p>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Controlado
+
+open + onOpenChange põem o estado nas suas mãos — dá pra refletir no gatilho (aqui o chevron gira) ou guardar a preferência.
+
+```tsx preview col
+const [open, setOpen] = useState(false)
+
+render(
+  <Collapsible open={open} onOpenChange={setOpen} className="w-full max-w-sm space-y-2">
+    <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted">
+      Skills do agente developer
+      <ChevronDown className={open ? 'h-4 w-4 rotate-180 transition-transform' : 'h-4 w-4 transition-transform'} />
+    </CollapsibleTrigger>
+    <CollapsibleContent className="space-y-1 px-3 text-sm text-muted-foreground">
+      <p>clean-code</p>
+      <p>code-style</p>
+      <p>ddd</p>
+    </CollapsibleContent>
+  </Collapsible>,
+)
+```
+
+## Desabilitado
+
+disabled no Collapsible trava o gatilho — a seção fica fixa no estado atual (aqui, fechada).
+
+```tsx preview col
+<Collapsible disabled className="w-full max-w-sm space-y-2">
+  <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium disabled:cursor-not-allowed disabled:opacity-50">
+    Sessões arquivadas
+    <ChevronsUpDown className="h-4 w-4 text-muted-foreground" />
+  </CollapsibleTrigger>
+  <CollapsibleContent className="px-3 text-sm text-muted-foreground">
+    <p>Nada para mostrar enquanto o workspace está em sincronização.</p>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `defaultOpen (Collapsible)` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `open (Collapsible)` | `boolean` | | Estado no modo controlado — pareie com onOpenChange. |
+| `onOpenChange (Collapsible)` | `(open: boolean) => void` | | Chamado a cada abertura ou fechamento. |
+| `disabled (Collapsible)` | `boolean` | `false` | Trava o gatilho — a seção fica presa no estado atual. |

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

@@ -0,0 +1,56 @@
+## Lista filtrável inline
+
+Digite pra filtrar — navegação por teclado, grupos e CommandEmpty de graça (cmdk). É a base do Select buscável; pra escolha em form, use o Select.
+
+```tsx preview
+<Command className="max-w-sm rounded-lg border border-border">
+  <CommandInput placeholder="Buscar sessão ou ação…" />
+  <CommandList>
+    <CommandEmpty>Nada encontrado.</CommandEmpty>
+    <CommandGroup heading="Sessões">
+      <CommandItem><FolderGit2 /> Onboarding do faturamento</CommandItem>
+      <CommandItem><FolderGit2 /> Integração com o ERP</CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Ações">
+      <CommandItem><Plus /> Nova sessão <CommandShortcut>⌘N</CommandShortcut></CommandItem>
+      <CommandItem><Play /> Iniciar ambiente</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+## Palette modal (CommandDialog)
+
+O Command embrulhado num Dialog, com header sr-only pra a11y. O atalho ⌘K (keydown no app) só troca o open — o conteúdo é o mesmo do inline.
+
+```tsx preview
+const [open, setOpen] = useState(false)
+
+render(
+  <>
+    <Button variant="outline" onClick={() => setOpen(true)}>
+      Abrir palette <CommandShortcut>⌘K</CommandShortcut>
+    </Button>
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <CommandInput placeholder="Buscar comando…" />
+      <CommandList>
+        <CommandEmpty>Nada encontrado.</CommandEmpty>
+        <CommandGroup heading="IA">
+          <CommandItem onSelect={() => setOpen(false)}><Bot /> Chamar agente</CommandItem>
+          <CommandItem onSelect={() => setOpen(false)}><Sparkles /> Importar skill</CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  </>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `CommandDialog.open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — ligue ao atalho de teclado do app. |
+| `CommandDialog.title / description` | `string` | `'Comandos' / 'Busque um comando pra executar.'` | Texto sr-only do header (a11y do Dialog) — não aparece na tela. |
+| `CommandDialog.showCloseButton` | `boolean` | `true` | Mostra o X do Dialog — desligue se o Esc/clique fora bastarem. |
+| `CommandItem.onSelect` | `(value: string) => void` | | Dispara ao escolher (Enter ou clique) — feche o palette aqui. |

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

@@ -0,0 +1,50 @@
+## Básico
+
+A caixa de escrever da casa: textarea numa pílula elevada (`rounded-card` + `ring-edge` + `shadow-card`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/components/chat) extraído — use SOZINHO quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você.
+
+```tsx preview col
+const [text, setText] = React.useState('')
+
+render(
+  <Composer
+    value={text}
+    onChange={setText}
+    onSubmit={() => setText('')}
+    placeholder="Escreva uma mensagem…"
+  />,
+)
+```
+
+## Com seletores (barra de ações)
+
+Passe `actions` e o composer vira **duas linhas**: textarea em cima, uma barra limpa embaixo com os seletores à ESQUERDA e o enviar à direita. Estilize os controles como discretos (ghost, sem borda) — a barra não é um formulário. É onde o Maestro prende **app + task** e a GB, o **agente**. O `submitDisabled` trava o enviar além de vazio/busy (ex.: falta escolher o app), sem esconder a barra.
+
+```tsx preview col
+const [text, setText] = React.useState('')
+const [app, setApp] = React.useState('admin')
+
+render(
+  <Composer
+    value={text}
+    onChange={setText}
+    onSubmit={() => setText('')}
+    submitDisabled={app === ''}
+    rows={3}
+    placeholder="Descreva o que essa sessão vai fazer…"
+    actions={
+      <Menu>
+        <MenuTrigger asChild>
+          <Button variant="ghost" size="sm" className="gap-1 text-muted-foreground">
+            {app === 'admin' ? 'Admin' : 'Copilot'}
+            <ChevronDown className="size-3.5 opacity-60" />
+          </Button>
+        </MenuTrigger>
+        <MenuContent align="start">
+          <MenuItem onSelect={() => setApp('admin')}>Admin</MenuItem>
+          <MenuItem onSelect={() => setApp('copilot')}>Copilot</MenuItem>
+        </MenuContent>
+      </Menu>
+    }
+  />,
+)
+```

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

@@ -0,0 +1,120 @@
+## O trio imperativo: `dialog`
+
+`dialog.alert` · `dialog.confirm` · `dialog.prompt` — o trio do browser (`alert`/`confirm`/`prompt`), mas **assíncrono, com tema e a11y-correto**. Cada um pergunta e **espera a resposta**:
+
+```tsx
+await dialog.alert({ title: 'Sessão expirada', description: 'Você será desconectado.' })          // Promise<void>
+const ok   = await dialog.confirm({ title: 'Excluir a sessão?', variant: 'destructive' })          // Promise<boolean>
+const nome = await dialog.prompt({ title: 'Nome do snapshot', placeholder: 'ex.: v1-final' })      // Promise<string | null>
+```
+
+É a mesma forma do `toast` (superfície imperativa, host no shell), mas que **responde** — e é isso que tira as ~15 linhas de JSX que cada tela montava. Por baixo é o `AlertDialog`: `role="alertdialog"`, foco preso, **não fecha no clique fora** — a semântica de uma interrupção que EXIGE resposta. Fechar por ESC/Cancelar resolve o "não" de cada tipo (`void`, `false`, `null`).
+
+```tsx preview
+function Demo() {
+  const [last, setLast] = useState('—')
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <DialogHost />
+      <Button variant="outline" size="sm" onClick={async () => {
+        await dialog.alert({ title: 'Sessão expirada', description: 'Você será desconectado.' })
+        setLast('alert → OK')
+      }}>alert</Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const ok = await dialog.confirm({ title: 'Excluir a sessão?', description: 'Some o worktree e o preview.', action: 'Excluir', variant: 'destructive' })
+        setLast('confirm → ' + (ok ? 'excluída' : 'mantida'))
+      }}>confirm</Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const name = await dialog.prompt({ title: 'Nome do snapshot', placeholder: 'ex.: v1-final' })
+        setLast('prompt → ' + (name === null ? 'cancelado' : name))
+      }}>prompt</Button>
+      <span className="text-sm text-muted-foreground">Última: {last}</span>
+    </div>
+  )
+}
+render(<Demo />)
+```
+
+## Por que namespace, e não `confirm()` solto
+
+`alert`/`confirm`/`prompt` são **globais do browser**. Como função solta, esquecer o import não daria erro — o TypeScript resolveria pro global e o código abriria a caixa cinza do sistema (sem tema, que webview suprime). `window.dialog` não existe, então o namespace **imuniza** a família contra esse footgun. `confirm()` segue exportado como alias (retrocompat), mas o novo código usa `dialog.confirm`.
+
+## `body`: corpo com conteúdo próprio
+
+Os três aceitam `body` — conteúdo que a `description` de texto não expressa (uma lista do que será afetado, um detalhe destacado). É o que antes obrigava a compor o `AlertDialog` à mão:
+
+```tsx preview
+function Demo() {
+  const [status, setStatus] = useState('—')
+  return (
+    <div className="flex items-center gap-3">
+      <DialogHost />
+      <Button variant="outline" size="sm" onClick={async () => {
+        const ok = await dialog.confirm({
+          title: 'Encerrar 3 sessões?',
+          description: 'Os agentes abaixo serão interrompidos:',
+          body: (
+            <ul className="list-disc space-y-1 pl-5 text-sm text-muted-foreground">
+              <li><span className="font-medium text-foreground">developer</span> — empresa-x-api</li>
+              <li><span className="font-medium text-foreground">reviewer</span> — empresa-x-web</li>
+            </ul>
+          ),
+          action: 'Encerrar todas',
+        })
+        setStatus(ok ? 'encerradas' : 'mantidas')
+      }}>Encerrar sessões</Button>
+      <span className="text-sm text-muted-foreground">Resposta: {status}</span>
+    </div>
+  )
+}
+render(<Demo />)
+```
+
+## O host
+
+Monte **um** `<DialogHost />` no shell do app, ao lado do `<Toaster />`:
+
+```tsx
+<AppShell sidebar={…}>
+  {rotas}
+  <Toaster />
+  <DialogHost />
+</AppShell>
+```
+
+Sem ele, os três **lançam** — em vez de devolver uma promise que nunca resolve. Promise pendurada viraria clique sem efeito, o pior desfecho pra uma interrupção que exige resposta: a pessoa acha que respondeu, ou clica de novo. (`<ConfirmHost />` segue valendo como alias de `<DialogHost />`.)
+
+Várias perguntas seguidas entram numa **fila** e aparecem uma por vez — cada `await` recebe a resposta do SEU diálogo (duas caixas empilhadas seriam ambíguas sobre qual clique respondeu o quê).
+
+## Quando NÃO usar
+
+- **Excluir uma entidade por contrato** → `ActionTrigger` com `icon={<Trash2 />}`: lê o `action.confirm`, dispara a action e fala o erro de negócio.
+- **Um form de verdade** (validação, vários campos, submete uma action) → `ActionFormDialog`. O `dialog.prompt` é só pra UMA string livre.
+- **Mais de duas ações** (ex.: Salvar / Descartar / Cancelar) ou **layout totalmente custom** → componha o `AlertDialog` à mão.
+- **Só avisar, sem cobrar decisão** → `toast` (passageiro) ou `Alert` (fica na página). O `dialog.alert` é pro aviso que **bloqueia** e exige um "OK".
+
+## Opções
+
+Comuns aos três (`dialog.alert`/`confirm`/`prompt`):
+
+| Opção | Tipo | Default | Descrição |
+|---|---|---|---|
+| `title` | `React.ReactNode` | | O enunciado. Obrigatório. |
+| `description` | `React.ReactNode` | | O que a pessoa precisa saber pra decidir — a CONSEQUÊNCIA, não o óbvio. |
+| `body` | `React.ReactNode` | | Conteúdo próprio entre a descrição e os botões (lista, detalhe). |
+| `media` | `React.ReactNode` | | Ícone grande acima do título (o quadro do `AlertDialogMedia`). |
+| `action` | `string` | `'OK'` / `'Confirmar'` | Rótulo do botão que confirma (default `'OK'` no alert, `'Confirmar'` nos outros). |
+
+Só `confirm` e `prompt`:
+
+| Opção | Tipo | Default | Descrição |
+|---|---|---|---|
+| `cancel` | `string` | `'Cancelar'` | Rótulo do botão que recusa. |
+| `variant` | `'default' \| 'destructive'` | `'default'` | `destructive` pinta o confirmar — o que apaga tem que parecer o que apaga. |
+
+Só `prompt`:
+
+| Opção | Tipo | Default | Descrição |
+|---|---|---|---|
+| `placeholder` | `string` | | Texto-fantasma do input. |
+| `defaultValue` | `string` | | Valor inicial (o input abre focado e selecionado). |

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

@@ -0,0 +1,30 @@
+## Básico
+
+Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5s. Bom pra toolbar ou célula estreita, ao lado de um ID/token/slug.
+
+```tsx preview
+<Copyable value="opus_sk_1a2b3c4d5e6f" className="text-muted-foreground hover:text-foreground" />
+```
+
+## Com rótulo
+
+Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar no conjunto copia. Componha o chrome (borda, mono) por fora, via `className`.
+
+```tsx preview
+<Copyable
+  value="softize-dev/opus"
+  className="rounded-md border px-2 py-1 font-mono text-xs text-muted-foreground hover:text-foreground"
+>
+  softize-dev/opus
+</Copyable>
+```
+
+## Duração do feedback
+
+`feedbackMs` ajusta quanto o check dura (default 1500). Some no-op silencioso se o clipboard não existir (contexto inseguro/SSR).
+
+```tsx preview
+<Copyable value="copiado devagar" feedbackMs={3000} className="text-muted-foreground hover:text-foreground">
+  copiar (3s)
+</Copyable>
+```